Skip to main content

Fusion Harness — Scoped Run Ledger & Safe Workflow Spine

Fusion Harness — Scoped Run Ledger & Safe Workflow Spine

MC: #107024
Owner: John / ALAI System
Source candidate: a0d65a97aaf2607af27701fa4be0d177a4934ade
Status: Active and postflight-verified since 2026-08-09; installed ACTIVATION.json points to candidate a0d65a97aaf2607af27701fa4be0d177a4934ade and the verified rollback snapshot.

Why this exists

The Fusion Harness already combines independent ARCHITECT and BUILDER work, deterministic validation gates, persistent role memory, and explicit abort handling. The Software Factory review identified one useful production-safe next step: make every expensive harness command produce a durable, queryable lifecycle record without persisting sensitive agent content.

This tranche adds an observability spine, not a new autonomous factory.

Commands covered

  • /fusion <prompt> :: <merge instruction>
  • /auto-validate <task>
  • /opinion <prompt>
  • /fh-runs [N] — show the latest 1–50 records for only the current authoritative Pi session + canonical cwd scope

/system-prompt, /thinking, and /fh-reset do not create execution records.

/opinion context-cost isolation follow-up

The first live ledger canary exposed a concrete inefficiency: a 31-character /opinion prompt inherited 327,799 BUILDER input tokens from the long-lived host transcript and reported USD 3.278395 for a 16-character answer. The ledger itself behaved correctly and retained no prompt/output/error content, but observability proved that persistent continuity is the wrong policy for an independent A/B opinion read.

Follow-up MC #107039 candidate 998d96302009ea860b2ccf8e890555977b1cca8b changes only /opinion:

  • both roles receive fresh throwaway session directories inside the unique per-run artifact directory;
  • no persistent role ID, host fork, or resume path is passed;
  • summary metadata records actual child session refs and policy: fresh-per-run;
  • /fusion and /auto-validate retain persistent continuity;
  • strict typecheck and 21/21 deterministic tests pass, including compiled wiring assertions.

Status: independently reviewed PASS, pending installed activation/canary. The external Claude monthly spend cap remains separate; this fix prevents the other model from needlessly resending a large historical context when one side is unavailable.

Exact isolation scope

The ledger reuses the existing Fusion host identity:

  1. authoritative Pi session ID from ctx.sessionManager.getSessionId();
  2. canonical cwd from realpath;
  3. a 24-hex SHA-derived scope key.

Records live under:

/tmp/fusion-harness-runs/v1/<scope-key>/

/fh-runs derives this directory from the current host identity. It never performs a cross-scope scan, so another Pi thread or another worktree cannot appear in the view.

A missing or unsafe authoritative session ID fails closed.

Schema v1

Each JSON record contains only:

  • schema version and run UUID;
  • exact scope key;
  • command name;
  • status and bounded stage name;
  • host PID;
  • start/update/end timestamps;
  • prompt SHA-256 and character count;
  • absolute per-run artifact directory;
  • bounded role/model telemetry (status, latency, token counts, cost, tool-call count, output character count);
  • aggregate telemetry;
  • optional numeric/boolean validation-gate metadata.

Allowed statuses:

  • running
  • succeeded
  • failed
  • aborted
  • interrupted

The parser rejects unknown top-level or nested keys. This prevents a malformed/tampered record from smuggling prompt, output, error, or tool payload fields through a later recovery write.

Data that must never enter the ledger

  • prompt text;
  • agent/model output;
  • errors or stderr;
  • tool names, arguments, or results;
  • environment values;
  • credentials/tokens;
  • raw Pi session ID or raw cwd.

Full command artifacts continue to use their existing private /tmp/fusion-harness-* directory. The ledger stores only that path.

Atomicity and filesystem safety

  • Directories are enforced as 0700.
  • Record files are enforced as 0600.
  • Updates use a same-directory exclusive temporary file, file fsync, atomic rename, permission enforcement, and best-effort directory fsync.
  • The in-memory manifest is updated only after the atomic disk replacement succeeds, so a failed write can be retried.
  • Scope directories that are symlinks are refused.
  • Record symlinks, non-regular files, hard links, oversized records, malformed JSON, mismatched run IDs/timestamps, foreign scope keys, and noncanonical metadata are refused or skipped.
  • Artifact paths must resolve inside the configured artifact root.
  • Listing/recovery examine at most 1,000 records per scope; /fh-runs displays at most 50.

Lifecycle and terminal outcomes

Each execution command creates its record immediately before entering a command-level try/finally.

  • Normal validated completion → succeeded
  • Model/gate/setup/handler failure → failed
  • User Escape stop → aborted
  • A later process opening the exact same scope finds a leftover running record whose host PID is dead → interrupted

UI cleanup is best effort and cannot prevent the final ledger write attempt. A live PID record remains running.

PID reuse remains a documented residual risk: recovery deliberately prefers a false-live result over interrupting a possibly live process.

/fh-runs

Example:

/fh-runs 10

The panel displays metadata only: outcome, command, stage, start time, elapsed time, role statuses, abbreviated prompt digest/character count, abbreviated run ID, and artifact path.

It does not display model text, errors, tool data, credentials, or records from other scopes.

Verification baseline

Candidate a0d65a97aaf2607af27701fa4be0d177a4934ade has HEAD-bound evidence for:

  • strict full-extension TypeScript check: PASS;
  • existing session-isolation regression: 9/9 PASS;
  • run-ledger tests: 8/8 PASS;
  • no-model command-finalization integration: 3/3 PASS;
  • total: 20/20 PASS;
  • Gitleaks: no leaks;
  • local Semgrep ledger policy: 4 rules, 0 findings;
  • independent Securion re-review: PASS, no P0/P1;
  • independent Proveo review: PASS, fresh 20/20.

Evidence root:

~/system/evidence/107024/

Key artifacts:

  • candidate/IMPLEMENTATION-REPORT.md
  • candidate/test-run.log
  • candidate/candidate-review.diff
  • securion-review.md
  • proveo-review.md
  • proveo-test-run.log
  • activation-plan.md

Activation and rollback

Activation completed after current global state was re-read and matched the validated baseline:

  1. candidate HEAD/hashes and tracked cleanliness verified;
  2. active ACTIVATION.json and every active source file matched the expected prior decision;
  3. full rollback snapshot created at /Users/makinja/.pi/agent/extensions-disabled/fusion-harness-pre-107024-20260809T192341Z;
  4. run-ledger.ts installed atomically before index.ts;
  5. README.local.md replaced and ACTIVATION.json written last;
  6. fresh installed-file canary passed strict typecheck + 20/20, and the existing global runner passed 9/9;
  7. a real fresh Pi RPC process loaded only the installed extension and executed /fh-runs 1 successfully with no model agent event.

Installed hashes:

  • index.ts: fa67fbfcf4720056c1553023c8c4d935262304ee425db6b38247418effa60786
  • run-ledger.ts: 0d064d066cc6a634786aca6146963fec8fab88babd2a54b4b7d3ec60a21c2f9b
  • session-scope.ts: 26adb50b14d73907d5e79ea9751321dc9f7a254a26bfce1f424dce5cf792881d

Postflight evidence:

  • ~/system/evidence/107024/activation-preflight.log
  • ~/system/evidence/107024/activation.log
  • ~/system/evidence/107024/active-canary.log
  • ~/system/evidence/107024/active-rpc-canary.log
  • ~/system/evidence/107024/rollback-snapshot-path.txt

The installed ACTIVATION.json remains the runtime truth. On any later regression, restore the timestamped snapshot with dependency-safe atomic replacement and rerun the previous 9/9 isolation suite.

Explicit non-goals

This tranche does not provide:

  • process/model resume after a crash;
  • branch or worktree sandboxing;
  • concurrent write-agent isolation;
  • automatic merge approval;
  • deployment approval or production health proof;
  • SQLite, a web console, or a cross-project dashboard.

Use /auto-validate only from the correct trusted worktree. Existing merge/deploy/security gates remain authoritative.

Software Factory source decision

Useful ideas adopted from disler/super-simple-software-factory:

  • explicit phase lifecycle;
  • durable/queryable outcomes;
  • code-owned checkpoints;
  • small typed metadata handoffs.

Rejected for this tranche:

  • direct repository installation/execution;
  • shell=True patterns;
  • prompt/full-trace persistence;
  • work directly on main;
  • unsupported sandbox/resume claims;
  • placeholder quality gates;
  • SQLite/UI expansion before the minimal ledger proves useful.

This keeps the useful architectural lesson — agents plus deterministic code — without importing the prototype's production hazards.

Back to top