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: Validated candidate; not active until the installed ACTIVATION.json and post-activation canary evidence say otherwise.

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.

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 is permitted only after current global state is re-read:

  1. verify candidate HEAD/hashes and tracked cleanliness;
  2. re-read active ACTIVATION.json and stop on an unexpected newer decision;
  3. copy the full active directory to a timestamped task-specific rollback snapshot;
  4. atomically replace run-ledger.ts before index.ts;
  5. replace README.local.md and write ACTIVATION.json last;
  6. run a fresh-process canary against the installed files: typecheck + 20/20 + installed hash checks;
  7. on any failure, restore the timestamped snapshot and report PARTIAL/BLOCKED.

The installed ACTIVATION.json is the runtime truth. This page must be updated with the postflight evidence path after activation.

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