@worca/app 1.2.0 → 1.3.0

package/src/core/run-harness.mjs

@@ -19,7 +19,7 @@ import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { join, basename, resolve, sep, relative } from 'node:path';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
-import { readFile, writeFile, readdir, mkdir, realpath } from 'node:fs/promises';
+import { readFile, writeFile, readdir, mkdir, realpath, rename } from 'node:fs/promises';
 
 import { generateTitle } from './title.mjs';
 import {
@@ -38,7 +38,10 @@ import { worcaHome } from './projects.mjs';
 import {
   runRootMode, getProjectsRoot,
   pipelineCostLimitUsd, totalCostLimitUsd, costLimitResetPeriod,
+  memoryCaps,
 } from './settings.mjs';
+import { mountDirs, mountMemory, syncBack, memoryTotals, validateMemoryScope, withStoreLock, memoryMountPath, MEMORY_RULES_REL, MEMORY_INJECTED_ENTRY } from './memory-sync.mjs';
+import { memoryRoot, renderMemoryBlock, bumpScopeState } from './memory-store.mjs';
 import { readCostCapOverride, totalWindowSpendUsd, costWindowStart, recordCostDelta } from './cost-budget.mjs';
 import {
   writeRunManifest, readRunManifest, updateRunManifest, rmGuarded, rescueModifiedMounts,
@@ -67,6 +70,7 @@ import {
   resolveFailure, isTerminal, markTerminal, answerFromDecision,
   REASON, pauseConsequences, describePauseReason,
 } from './failure-policy.mjs';
+import { recordRunMetrics } from './metrics/record.mjs';
 
 // worca-cc repo root; holds skills/. fileURLToPath, never URL.pathname: the
 // latter is `/C:/…` on Windows and %-encoded everywhere (see DEFAULT_AGENTS_DIR
@@ -557,6 +561,11 @@ export function normalizeClarifyAnswer(payload, questions) {
   }));
 }
 
+// Upper bound for one RunHarness._git call. Matches worktree.mjs's slow-git
+// budget (SLOW_GIT_TIMEOUT_MS): `diff --cached` on a large agent change is the
+// slowest command issued here, and it legitimately takes seconds, never minutes.
+const HARNESS_GIT_TIMEOUT_MS = 120_000;
+
 export class RunHarness extends EventEmitter {
   constructor(opts) {
     super();
@@ -612,6 +621,10 @@ export class RunHarness extends EventEmitter {
     }
     this.agentsDir = this.opts.agentsDir || DEFAULT_AGENTS_DIR;
     this.auto = !!this.opts.auto;
+    // Auto workflow (spec D3/D15): the human-in-the-loop switch. `--yes` (auto
+    // mode) implies it is off. It changes nothing on a saved workflow — only an
+    // Auto run reads it (proposal question, clarifier stage, agent questions).
+    this.humanInLoop = !this.auto && this.opts.humanInLoop !== false;
     this.stepModels = null; // { planner:{model,effort}, refiner:{...}, ... } | null until run()
     // Guardrails: resolved by _resolveGuardrails() from run() AND resume(); null
     // until then, so dispatcher tests that bypass run() get claudeOpts without
@@ -662,17 +675,36 @@ export class RunHarness extends EventEmitter {
     this.pauseAbort = new AbortController(); // aborts ONLY node children on pause
     this.pauseReason = null;                 // WHY the run paused: 'cost_pipeline'|'cost_total'|'error'|<usage-limit line>|null
     this.pauseDetail = null;                 // the human detail behind pauseReason ('error': the clipped message)
+    // Team metrics (§4.4 interventions). Resume runs on a NEW instance, so the counters are
+    // stamped into the persisted resume point at every pause and re-seeded in resume().
+    this._metricsIv = { questions: 0, pauses: 0, resumes: 0, lastPauseReason: null, lastPauseDetail: null };
+    this._metricsRecorded = false;
     this._setupDone = false;                 // run()/resume() flip this right before _engineRun (setup replay)
     this._rehydrated = true;                 // resume() clears this until the paused run is rehydrated (the 'resume' site)
     this._modeRecorded = false;              // resume(): the row recorded a run-root mode (a setup-incomplete point may not)
     this._pauseGate = null;                  // gate context snapshot when paused at a gate
     this._resumeNodeSessions = null;         // nodeId -> sessionId map, set by resume() (Task 5)
     this.resumeOpts = this.opts.resume || null; // { row, resumePoint, steps } from readPipelineForResume
+    // Agent memory (agent-memory-design.md §7.3): the defragment run option. A resumed run reads
+    // it back from its resume point — the resume sites pass no run options (B10). The API and the
+    // CLI validated already; this throw is the programming-error backstop (never a 400).
+    this.memoryScope = this.opts.memoryScope || this.resumeOpts?.resumePoint?.memoryScope || null;
+    {
+      const wf = this.resumeOpts?.resumePoint?.workflowId || this.workflowId;
+      const reason = validateMemoryScope({ workflowId: wf, memoryScope: this.memoryScope, isWorkspace: this.isWorkspace });
+      if (reason) throw new Error(reason);
+    }
     this.pendingQuestion = null; // { id, resolve, reject, kind }
     this._recovery = null;      // class -> in-flight Promise<'retry'|'pause'> (same-class dedupe)
     this._askTail = null;       // serializes _ask: ONE prompt open at a time (recovery + step questions)
     this._recoverySeq = 0;      // monotonic id source for recovery prompts (determinism-safe)
     this.agentPrompts = null;
+    this.memory = null;          // { root, mount, dirs, baseline } after _mountMemory
+    this.memoryBlock = '';       // the ## Worca memory pointer block, rendered once per mount (files load natively — no per-spawn re-render)
+    this.memoryChanges = [];     // Change[] — the durable ledger's `changes`
+    this._memoryWarned = new Set();
+    this._memoryTail = null;     // per-run sync chain: one syncBack at a time (F1)
+    this._ledgerSeq = 0;         // monotonic: two ledger writes must never share a temp name
     this.toolInstruction = '';
     // Cap for the in-worktree graphify build (macOS has no timeout(1)).
     // Resolution order: constructor option → WORCA_GRAPH_TIMEOUT_MS env → 120s.
@@ -717,6 +749,7 @@ export class RunHarness extends EventEmitter {
       // detached run throws TypeError on the first this.state.branches[key] = … .
       branches: {},
       checkpointRefs: {},
+      memoryMount: null, // <runCwd>/.claude/rules/worca after _mountMemory (native rules: inside every spawn's cwd)
       pauseReason: null,   // mirrors this.pauseReason so getState() (a deep clone of state) carries it live
       pauseDetail: null,   // mirrors this.pauseDetail
       // Sub-agent lifecycle records (rides the existing `state` snapshot; mirrored to
@@ -743,6 +776,18 @@ export class RunHarness extends EventEmitter {
       this._log('orchestrator', 'warn', `answer() ignored: no pending question with id ${id}`);
       return false;
     }
+    if (pq.validate) {
+      // A question that carries a validator (the Auto proposal) stays OPEN on a
+      // malformed payload (spec §5.4); the awaiting code receives the CLEAN value.
+      const clean = pq.validate(payload);
+      if (clean == null) {
+        this._log('orchestrator', 'warn', `answer() ignored: malformed payload for ${id} — the question stays open`);
+        return false;
+      }
+      this.pendingQuestion = null;
+      pq.resolve(clean);
+      return true;
+    }
     this.pendingQuestion = null;
     pq.resolve(payload);
     return true;
@@ -891,7 +936,7 @@ export class RunHarness extends EventEmitter {
       // fan-out forcing + the v1 stepper manifest; v2 = resolveGraph +
       // buildGraphManifest. It yields the manifest the UI renders, the agent-key
       // set the preflight and skills gates walk, and the workflow's id/name.
-      const topology = await this._resolveTopology(registry);
+      let topology = await this._resolveTopology(registry);
       if (!topology?.manifest || !topology.agentKeys || !topology.workflow?.id) throw new Error('engine hook contract: _resolveTopology must return { manifest, agentKeys, workflow:{id,name} }');
       // §9.4: hard-fail BEFORE the stepper is STAMPED / createPipeline / worktree
       // (the manifest is built inside the hook, which tolerates unknown keys) —
@@ -1040,6 +1085,15 @@ export class RunHarness extends EventEmitter {
       if (!this.resumeOpts) this._kickoffTitleGeneration();
       this._checkAbort();
 
+      // 3b') Auto workflow (spec §5.3): the run row and the run root exist, so the
+      // engine may now DECIDE the graph (classifier call, proposal question, reuse
+      // or create) and re-stamp the manifest. Returns null for a saved workflow.
+      // `topology` is consumed AFTER this point (collectRequiredSkills, the workflow
+      // audit line), so the adopted graph is what they see.
+      const decided = await this._decideTopology();
+      if (decided) topology = decided;
+      this._checkAbort();
+
       // 3c) Build the knowledge graph INSIDE each worktree so agents can query it.
       if (this.isWorkspace) await this._buildWorktreeGraphAll();
       else await this._buildWorktreeGraph();
@@ -1087,6 +1141,12 @@ export class RunHarness extends EventEmitter {
         await this._assembleContext(resolvedSkills);
       }
       this._checkAbort();
+      // 3f) Agent memory: mount the store into <runCwd>/.claude/rules/worca — the CLI loads it
+      // natively — and render the pointer block every spawn carries. Pure fs work, both modes,
+      // mock included. AFTER 3e: the assembly rewrites injectedPaths and the mount registers
+      // itself into that map.
+      await this._mountMemory();
+      this._checkAbort();
       // D7: every setup step above is done — a pause from here on has nothing to
       // replay, so _completePaused strips any `setupIncomplete` stamp instead.
       this._setupDone = true;
@@ -1110,7 +1170,9 @@ export class RunHarness extends EventEmitter {
       await this._persist();
       await appendAudit(this.pipeline.dir, `Pipeline finished with status **done**.`);
       await this._buildResults();          // refs + worktree still live here
+      await this._stampDefrag();           // AFTER the final sync inside _buildResults counted the defragmenter's writes
       await this._reportToSource();        // task-source write-back (never throws, spec §7.5)
+      await this._recordRunMetrics('done');
       this._emit('done', { status: 'done', pipelineDir: this.pipeline.dir });
       return { status: 'done', pipelineDir: this.pipeline.dir };
     } catch (err) {
@@ -1153,6 +1215,7 @@ export class RunHarness extends EventEmitter {
           await this._buildResults({ stage: true });
           await this._reportToSource(); // statusToResult('stopped') -> 'failed' (design PR12: no longer success-only)
         }
+        await this._recordRunMetrics('stopped');
         this._emit('done', {
           status: 'stopped',
           pipelineDir: this.pipeline?.dir || null,
@@ -1193,6 +1256,7 @@ export class RunHarness extends EventEmitter {
         await this._buildResults({ stage: true });
         await this._reportToSource(); // statusToResult('error') -> 'failed' (design PR12: no longer success-only)
       }
+      await this._recordRunMetrics('error', err);
       this._emit('done', {
         status: 'error',
         pipelineDir: this.pipeline?.dir || null,
@@ -1260,6 +1324,13 @@ export class RunHarness extends EventEmitter {
       recordArtifact(row.id, RUN_LOG_KIND, RUN_LOG_FILE);
       this.stepModels = rp.stepModels || null;
       this.workflowId = rp.workflowId || this.workflowId;
+      // Pauses are counted only in _completePaused, so a crash-resume of an `interrupted`
+      // run adds a resume but no pause (§4.4 decision 6).
+      const iv = rp.interventions && typeof rp.interventions === 'object' ? rp.interventions : {};
+      this._metricsIv = {
+        questions: iv.questions | 0, pauses: iv.pauses | 0, resumes: (iv.resumes | 0) + 1,
+        lastPauseReason: iv.lastPauseReason ?? null, lastPauseDetail: iv.lastPauseDetail ?? null,
+      };
       // The saved point carries the pause that produced it; a resumed run is running.
       this._clearPauseReason();
       // Rehydrate the run's selection BEFORE re-resolving so resume enforces the
@@ -1377,6 +1448,18 @@ export class RunHarness extends EventEmitter {
       await appendAudit(this.pipeline.dir, rehydrated.audit);
       this._emit('state', this.getState());
       this._rehydrated = true;
+      // The pause that parked this run is over; it must not colour a later failure
+      // or stop (§4.4 decision 2).
+      this._metricsIv.lastPauseReason = null;
+      this._metricsIv.lastPauseDetail = null;
+
+      // 3a') Auto workflow (spec §5.6): a run that paused BEFORE its graph was
+      // decided re-enters the decision HERE — before the setup replay, so the
+      // skills gate and the context assembly below see the ADOPTED agent keys, not
+      // the bootstrap's empty set. null for a saved workflow and for an Auto run
+      // that already adopted (rp.workflowId is then the real id).
+      await this._decideTopology({ resume: rp });
+      this._checkAbort();
 
       // ── setup replay (D7): a converted setup failure paused this run before its
       //    checkout / graph / skills gate existed. Re-run exactly what run() never
@@ -1417,6 +1500,10 @@ export class RunHarness extends EventEmitter {
         }
       }
 
+      // Agent memory on resume (§5): capture what the interrupted execution wrote,
+      // then remount fresh from the store.
+      await this._mountMemory({ resume: true });
+
       const dispatched = await this._engineRun({ resume: rp, rehydrated });
       this._checkAbort();
       if (dispatched === 'paused') return await this._completePaused();
@@ -1427,7 +1514,9 @@ export class RunHarness extends EventEmitter {
       await this._persist();
       await appendAudit(this.pipeline.dir, `Pipeline finished with status **done**.`);
       await this._buildResults();          // refs + worktree still live here
+      await this._stampDefrag();           // AFTER the final sync inside _buildResults counted the defragmenter's writes
       await this._reportToSource();        // task-source write-back (never throws, spec §7.5)
+      await this._recordRunMetrics('done');
       this._emit('done', { status: 'done', pipelineDir: this.pipeline.dir });
       return { status: 'done', pipelineDir: this.pipeline.dir };
     } catch (err) {
@@ -1462,6 +1551,7 @@ export class RunHarness extends EventEmitter {
           await this._buildResults({ stage: true });
           await this._reportToSource(); // statusToResult('stopped') -> 'failed' (design PR12: no longer success-only)
         }
+        await this._recordRunMetrics('stopped');
         this._emit('done', { status: 'stopped', pipelineDir: this.pipeline?.dir || null });
         return { status: 'stopped', pipelineDir: this.pipeline?.dir || null };
       }
@@ -1497,6 +1587,7 @@ export class RunHarness extends EventEmitter {
         await this._buildResults({ stage: true });
         await this._reportToSource(); // statusToResult('error') -> 'failed' (design PR12: no longer success-only)
       }
+      await this._recordRunMetrics('error', err);
       this._emit('done', { status: 'error', pipelineDir: this.pipeline?.dir || null });
       return { status: 'error', pipelineDir: this.pipeline?.dir || null, error: message };
     } finally {
@@ -1754,6 +1845,244 @@ export class RunHarness extends EventEmitter {
     return rc;
   }
 
+  /** Absolute `<pipeline.dir>/memory.json` — the durable memory ledger (amendment A2). */
+  _memoryLedgerPath() { return join(this.pipeline.dir, 'memory.json'); }
+
+  /** Mount the memory store into this run — best-effort. Memory is additive (spec §4.3):
+   *  a store/mount fs failure degrades the run to "no memory" (no pointer block, no sync) and is
+   *  logged + audited; it never pauses the run at 'setup', where the replay would hit the
+   *  same error again. EXCEPTION (amendment B8): a DEFRAGMENT run (`this.memoryScope` set) IS
+   *  its mount — the error is rethrown and run()'s setup failure policy parks the run
+   *  paused/error with setupIncomplete, so a retryable mount failure can resume. */
+  async _mountMemory({ resume = false } = {}) {
+    if (!this.pipeline?.dir) return;
+    try { await this._mountMemoryUnguarded({ resume }); }
+    catch (err) {
+      this.memory = null; this.memoryBlock = ''; this.state.memoryMount = null;
+      if (existsSync(this._memoryLedgerPath())) await this._writeMemoryLedger({ neutralised: true });
+      const why = String(err?.message || err).split('\n')[0];
+      // A defragment run IS its mount (B8): rethrow, and run()'s setup failure policy parks the run
+      // as paused/error with setupIncomplete — a retryable mount failure resumes, a persistent one
+      // stays visible. An ordinary run degrades to "no memory" as in P1.
+      if (this.memoryScope) {
+        await appendAudit(this.pipeline.dir, `Memory: not mounted (${why}) — a defragment run cannot continue.`).catch(() => {});
+        throw new Error(`memory not mounted: ${why}`);
+      }
+      this._log('memory', 'warn', `memory not mounted: ${why} — this run's agents see no memory and their memory writes are not captured`);
+      await appendAudit(this.pipeline.dir, `Memory: not mounted (${why}).`).catch(() => {});
+    }
+  }
+
+  /**
+   * Mount the memory store into this run at `<runCwd>/.claude/rules/worca` — INSIDE the cwd of
+   * every spawn, where Claude Code discovers rules natively (run root on a detached workspace
+   * run, the primary worktree otherwise). Always recomputed, never the ledger's absolute path.
+   * On resume, the previous segment's ledger is read first and its mount is synced back BEFORE
+   * anything else (§5 "resume of a paused run"): the sync is pure fs and needs neither git nor
+   * the tracked guard, so a guard that fails only NOW (git broken, the previous segment's agent
+   * staged the mount) can never lose the interrupted segment's writes.
+   */
+  async _mountMemoryUnguarded({ resume }) {
+    const root = memoryRoot();
+    // Pre-setup there is no run cwd, and the LIVE checkout must never take a mount.
+    const cwd = this.runCwd || null;
+    if (!cwd || cwd === this.projectDir) throw new Error('no run cwd to mount into');
+    const mount = memoryMountPath(cwd);
+    // §8.8 scope of the record: 'runRoot' when the cwd IS the run root, else the member whose
+    // checkout is the cwd (the primary member on single and legacy-workspace runs).
+    const scope = (this.runRoot && cwd === this.runRoot) ? 'runRoot'
+      : ([...this.workDirs.entries()].find(([, d]) => d === cwd)?.[0] ?? null);
+    if (!scope) throw new Error(`run cwd ${cwd} is neither the run root nor a member checkout`);
+    const dirs = mountDirs({ members: this.members, isWorkspace: this.isWorkspace, memoryScope: this.memoryScope });
+    const onError = (p, err) => this._memoryReadWarn(p, err);
+    if (resume) {
+      let ledger = null;
+      try { ledger = JSON.parse(await readFile(this._memoryLedgerPath(), 'utf8')); } catch { ledger = null; }
+      if (ledger && ledger.baseline && Array.isArray(ledger.dirs)) {
+        this.memoryChanges = Array.isArray(ledger.changes) ? ledger.changes : [];
+        // A run paused BEFORE the native-rules revision still has its files at the ledger's
+        // old path (<pipeline.dir>/memory): sync THAT dir once, so nothing the interrupted
+        // execution wrote is lost; the recomputed path is used from here on.
+        const prev = (typeof ledger.mount === 'string' && ledger.mount !== mount && existsSync(ledger.mount)) ? ledger.mount : mount;
+        try {
+          await this._syncMemoryWith({ mount: prev, dirs: ledger.dirs, baseline: ledger.baseline, nodeId: 'resume', executionId: null, agentKey: null, label: 'the interrupted execution' });
+        } catch (err) {
+          // Defensive — syncBack does not reject today (every fs error is per-file or routed
+          // through onError). If it ever does: do NOT remount over unsynced writes; keep the
+          // PREVIOUS mount + baseline so the next execution's sync retries them.
+          this._log('memory', 'warn', `memory: the interrupted execution's writes could not be synced (${err?.message || err}); keeping the previous mount`);
+          this.memory = { root, mount: prev, dirs: ledger.dirs, baseline: ledger.baseline };
+          this.state.memoryMount = prev;
+          // Register ONLY when the kept mount is the one inside this run's cwd: a mount there must
+          // stay excluded from the commit and removed at teardown, while the pre-revision
+          // <pipeline.dir>/memory path is outside every checkout and needs no §8.8 record.
+          if (prev === mount) await this._registerMemoryMount(scope);
+          this._refreshMemoryBlock();
+          return;
+        }
+      }
+    }
+    // A checkout that TRACKS the mount path would have its committed files overwritten, excluded
+    // from the commit and deleted at teardown — refuse, like the skill mount's trackedNames guard.
+    // `:(icase)`: on a case-insensitive file system a repo tracking `.Claude/rules/worca` would
+    // otherwise pass the guard and have those files rm'd through the case-folded path. The
+    // detached workspace run root has no git and no check.
+    if (scope !== 'runRoot') {
+      const tracked = await this._git(['ls-files', '--', `:(icase)${MEMORY_RULES_REL}`], { cwd });
+      if (!tracked.ok) throw new Error(`cannot tell whether the checkout tracks ${MEMORY_RULES_REL} (git ls-files: ${tracked.stderr.trim() || `exit ${tracked.code}`})`);
+      // The way out differs: an ordinary run has nowhere else to go (its checkout IS the project's),
+      // a defragment targets a scope and can be started from any other project's checkout.
+      if (tracked.stdout.trim()) throw new Error(`the checkout tracks ${MEMORY_RULES_REL} — untrack it${this.memoryScope ? ' (or start the defragment from another project)' : ''}`);
+    }
+    // Register BEFORE anything touches the disk: a mount that fails half-way (EACCES, a Windows
+    // EBUSY past the retries) leaves files under the cwd, and only the §8.8 entry keeps them out
+    // of the commit and gets them removed at teardown. Idempotent, harmless on failure.
+    await this._registerMemoryMount(scope);
+    // gitIgnore: the mount now lives INSIDE a checkout an AGENT runs git in. `<mount>/.gitignore`
+    // = `*` makes it invisible to an agent's own `git add -A`, to a staging pre-commit hook, to
+    // snapshotWorktreePatch's bare `git add -A` and to the reviewer's `git status`. The §8.8
+    // `:(exclude)` pathspec stays as defence in depth. Harmless at a non-git run root.
+    const m = await mountMemory({ root, mount, dirs, onError, gitIgnore: true });
+    this.memory = { root, mount, dirs, baseline: m.baseline };
+    this.state.memoryMount = mount;
+    this._refreshMemoryBlock();
+    await this._writeMemoryLedger();
+    this._log('memory', 'info', `Memory mounted at ${mount}: ${m.files} file(s) across ${dirs.length} scope(s)`);
+  }
+
+  /**
+   * §8.8: the mount rides `injectedPaths[<scope>]` as a `kind:'memory'` entry — excluded from the
+   * commit, the intent-to-add staging and the three result diffs (_excludePathspecs), removed at
+   * teardown (removeInjectedPaths), never rescued (sync-back is its rescue). Idempotent: a resume
+   * re-assembly rewrites the map without it, so it is re-added here; persisted into run.json on
+   * detached runs so the boot sweep and pipeline-delete see the same set. Under legacy the map was
+   * always {} — the memory entry is the ONE legacy pathspec, and the legacy `git add -A` becomes
+   * `git add -A -- . :(exclude).claude/rules/worca` (§10's byte-identical contract, amended: memory
+   * has been mounted in both modes since P1, and an unexcluded mount would be committed).
+   */
+  async _registerMemoryMount(scope) {
+    const map = { ...(this.injectedPaths || {}) };
+    map[scope] = [...(map[scope] || []).filter((e) => e?.kind !== 'memory'), { ...MEMORY_INJECTED_ENTRY }];
+    this.injectedPaths = map;
+    if (this.runRoot) await updateRunManifest(this.runRoot, { injectedPaths: map }).catch(() => {});
+  }
+
+  /** The `## Worca memory` pointer block: heading, one-line intro, one `Label — /abs/dir:` line per
+   *  mounted scope. Depends on dirs + mount only (never on file contents), so one render per mount. */
+  _refreshMemoryBlock() {
+    if (!this.memory) { this.memoryBlock = ''; return; }
+    this.memoryBlock = renderMemoryBlock(this.memory.dirs.map((d) => ({ label: d.label, dir: join(this.memory.mount, d.rel) })));
+  }
+
+  /** The `onError` every memory listing gets. A junk NAME is not an I/O failure — phrasing it
+   *  as "cannot read" sends the user hunting a broken disk instead of renaming a file. */
+  _memoryReadWarn(p, err) {
+    if (err?.code === 'ENAME') this._memoryWarn(`memory: ignored ${p} (invalid name — not a memory file)`);
+    else this._memoryWarn(`memory: cannot read ${p}: ${err?.code || err?.message || err}`);
+  }
+
+  /** Record-once warnings: the pointer block is rendered once per mount. */
+  _memoryWarn(text) {
+    if (this._memoryWarned.has(text)) return;
+    this._memoryWarned.add(text);
+    this._log('memory', 'warn', text);
+  }
+
+  /** After ONE execution (orchestrator._afterExecution) — never rejects, and serialised per
+   *  run: the job reads `this.memory` when the PREVIOUS sync has published its baseline.
+   *  (Composite slices and parallel branches finish together; two syncs diffing against one
+   *  baseline would both write and both report the same files.) */
+  _syncMemory(nc, ctx) {
+    if (!this.memory) return Promise.resolve(null);
+    const job = async () => {
+      if (!this.memory) return null;
+      try {
+        return await this._syncMemoryWith({ ...this.memory, nodeId: ctx.nodeId, executionId: ctx.executionId, agentKey: nc?.key ?? null, label: nc?.key || ctx.label || ctx.nodeId });
+      } catch (err) {
+        this._log('memory', 'warn', `memory sync failed after ${ctx.executionId}: ${err?.message || err}`);
+        return null;
+      }
+    };
+    this._memoryTail = (this._memoryTail || Promise.resolve()).then(job, job);
+    return this._memoryTail;
+  }
+
+  async _syncMemoryWith({ mount, dirs, baseline, nodeId, executionId, agentKey, label }) {
+    const now = new Date().toISOString();
+    const res = await syncBack({
+      root: memoryRoot(), mount, dirs, baseline, source: `${this.memoryScope ? 'defrag' : 'run'}:${this.pipeline.id}`, now,
+      caps: memoryCaps(), onWarn: (w) => this._log('memory', 'warn', w),
+      onError: (p, err) => this._memoryReadWarn(p, err),
+    });
+    // `mount` equals this.memory.mount for every in-run sync and for a same-process resume;
+    // an OLD instance can never race a resumed one because the scheduler drains in-flight
+    // executions before the run reports 'paused' (scheduler.mjs, the pause drain).
+    if (this.memory && this.memory.mount === mount) this.memory.baseline = res.baseline;
+    if (res.total || res.rejected.length) {
+      this.memoryChanges.push({
+        executionId, nodeId, agentKey, at: now,
+        added: res.added, modified: res.modified, deleted: res.deleted, rejected: res.rejected,
+      });
+      const head = `Memory: +${res.added.length} ~${res.modified.length} -${res.deleted.length}` +
+        `${res.rejected.length ? ` (${res.rejected.length} rejected)` : ''} by ${label}`;
+      const name = (r) => `${r.scope}/${r.name}.md`;
+      const details = [
+        ...res.added.map((r) => `added ${name(r)}`), ...res.modified.map((r) => `updated ${name(r)}`),
+        ...res.deleted.map((r) => `deleted ${name(r)}`), ...res.rejected.map((r) => `rejected ${name(r)} — ${r.reason}`),
+      ];
+      this._log('memory', 'info', `${head}: ${details.join('; ')}`, { nodeId, executionId });
+      await appendAudit(this.pipeline.dir, `${head}: ${details.join('; ')}`).catch(() => {});
+    }
+    if (this.memory && this.memory.mount === mount) await this._writeMemoryLedger();
+    return res;
+  }
+
+  /** `{ mount, dirs, baseline, changes }` — best-effort, atomic via temp + rename. */
+  async _writeMemoryLedger({ neutralised = false } = {}) {
+    if (!this.pipeline?.dir || (!this.memory && !neutralised)) return;
+    const file = this._memoryLedgerPath();
+    // `neutralised` (after a mount failure) keeps the change history but writes no dirs and
+    // no baseline, so a later resume has nothing stale to diff against (a missing mount dir
+    // must never read as "the run deleted every file").
+    const payload = neutralised
+      ? { mount: null, dirs: [], baseline: {}, changes: this.memoryChanges }
+      : { mount: this.memory.mount, dirs: this.memory.dirs, baseline: this.memory.baseline, changes: this.memoryChanges };
+    const tmp = `${file}.tmp-${process.pid}-${++this._ledgerSeq}`;
+    try { await writeFile(tmp, `${JSON.stringify(payload, null, 2)}\n`, 'utf8'); await rename(tmp, file); }
+    catch (err) { this._log('memory', 'warn', `memory ledger not written: ${err?.message || err}`); }
+  }
+
+  /** A finished defragment run resets the scope's counters (spec §5, §7): called on the `done`
+   *  arms only, after _buildResults' final sync. `this.memory.dirs[0]` is the one mounted scope.
+   *  Amendment B31: a run whose ledger holds ANY rejected write did not produce the scope the
+   *  agent intended — leave the counters alone (health stays `due`) and say so, loudly.
+   *  `withStoreLock` is a per-process promise chain: it serialises this stamp against this
+   *  process's own syncs only, not against another worca process. */
+  async _stampDefrag() {
+    if (!this.memoryScope || !this.memory?.dirs?.length) return;
+    const d = this.memory.dirs[0];
+    const { rejected } = memoryTotals(this.memoryChanges);
+    if (rejected) {
+      this._log('memory', 'warn', `Memory: ${d.label} — ${rejected} write(s) were rejected during this defragment; counters NOT reset (see the rejections above)`);
+      await appendAudit(this.pipeline.dir, `Memory: ${d.label} defragment finished with ${rejected} rejected write(s) — counters not reset.`).catch(() => {});
+      return;
+    }
+    const now = new Date().toISOString();
+    try {
+      await withStoreLock(memoryRoot(), () => bumpScopeState(memoryRoot(), d.scope, { lastDefragAt: now, lastDefragRunId: this.pipeline.id, writesSinceDefrag: 0 }));
+      this._log('memory', 'info', `Memory: ${d.label} defragmented — write counter reset`);
+      await appendAudit(this.pipeline.dir, `Memory: ${d.label} defragmented by this run.`).catch(() => {});
+    } catch (err) {
+      this._log('memory', 'warn', `memory: defrag stamp failed: ${err?.message || err}`);
+    }
+  }
+
+  /** The run-summary shape (§6). null when nothing changed, so results.json is unchanged for such runs. */
+  memorySummary() {
+    if (!this.memoryChanges.length) return null;
+    return { changes: this.memoryChanges, totals: memoryTotals(this.memoryChanges) };
+  }
+
   /**
    * §8.18 / gate V5: parse `claude --help` ONCE per run and assert `--mcp-config`.
    * On absence, degrade gracefully — skip the flag, warn loudly naming the required
@@ -1920,7 +2249,12 @@ export class RunHarness extends EventEmitter {
     // branch carries no changes (the staging in _stageWorkingTree is intent-to-add
     // for the reviewer's diff only — it never creates a commit). On error/stop this
     // is what captures the partial work made up to that point.
-    const commit = await this._commitWork(info);
+    const key = this.members[0]?.projectKey ?? null;
+    const injected = key ? (this.injectedPaths?.[key] ?? []) : [];
+    const commit = await this._commitWork(info, this.state.branch, { excludePathspecs: this._excludePathspecs(key) });
+    // The memory mount (the one legacy injected path) was synced at _buildResults; remove it now
+    // so it rides neither the retained-work snapshot nor an outlived checkout.
+    await removeInjectedPaths(info.worktreeDir, injected);
     const retained = await this._recordCommitFailure(commit, { info, branchRecord: this.state.branch });
     if (retained) {
       await this._snapshotRetained(info);
@@ -1970,7 +2304,8 @@ export class RunHarness extends EventEmitter {
     for (const [projectKey_, info] of entries) {
       if (!info || !info.worktreeDir) continue;
       const branchRecord = (this.state.branches && this.state.branches[projectKey_]) || null;
-      const commit = await this._commitWork(info, branchRecord);
+      const commit = await this._commitWork(info, branchRecord, { excludePathspecs: this._excludePathspecs(projectKey_) });
+      await removeInjectedPaths(info.worktreeDir, this.injectedPaths?.[projectKey_] ?? []);
       if (await this._recordCommitFailure(commit, { key: projectKey_, info, branchRecord })) {
         anyRetained = true;
         await this._snapshotRetained(info, projectKey_);
@@ -2018,7 +2353,8 @@ export class RunHarness extends EventEmitter {
    * Still skipped entirely when the run paused (§8.13) — the caller guards.
    *
    * Under `legacy` this delegates to today's _teardownWorktree / _teardownWorktreeAll
-   * verbatim and does nothing else. Under `detached`, per member, in NORMATIVE order:
+   * verbatim, except that both now commit with the §8.8 exclusion set (the memory mount)
+   * and remove the mount after the commit attempt. Under `detached`, per member, in NORMATIVE order:
    *   1. modified-mount rescue (§8.20) — read-only, so it survives any later failure
    *   2. strip every claudeMdSection fenced block (must precede the commit — that
    *      file is deliberately NOT in the exclusion pathspecs)
@@ -2260,8 +2596,12 @@ export class RunHarness extends EventEmitter {
    *   (defaults to the scalar this.state.branch; a workspace member passes its own
    *   state.branches[projectKey] so per-member SHAs are recorded distinctly).
    * @param {{excludePathspecs?:string[]}} [opts] §8.8 exclusion set for this
-   *   worktree. With the DEFAULT empty array — every legacy run — the method keeps
-   *   today's bare `git add -A` byte-identically (§10 rollback contract).
+   *   worktree. Since the native-rules revision every run passes one (the memory mount),
+   *   so the argv is `git add -A -- . :(exclude).claude/rules/worca`, preceded by a
+   *   `git rm -r --cached --ignore-unmatch -- .claude/rules/worca` that unstages anything an
+   *   agent force-staged there (`git add -A` with an exclude never unstages); the DEFAULT empty
+   *   array (a refused mount) still reproduces the bare `git add -A`. The detached
+   *   `_teardownRunRoot` path commits through this same method, so it is covered too.
    * @returns {Promise<{ok:true,committed:boolean,sha:string|null}|
    *                   {ok:false,step:'status'|'add'|'commit',message:string,fromStderr:boolean}>}
    *   `fromStderr` records whether `message` embeds real stderr bytes (vs. the
@@ -2289,6 +2629,15 @@ export class RunHarness extends EventEmitter {
       this._log('git', 'info', 'No changes to commit (working tree clean).');
       return { ok: true, committed: false, sha: null };
     }
+    // `git add -A -- . :(exclude)X` does not UNSTAGE what is already in the index: an agent that
+    // ran `git add -f .claude/rules/worca` (the one way past the mount's `.gitignore` sentinel)
+    // would otherwise put memory files on the kept branch, and on a resume the tracked guard would
+    // then refuse the mount for the rest of the run. Drop the exclusion set from the index first —
+    // a no-op (exit 0) when nothing under it is staged, thanks to --ignore-unmatch.
+    if (excludePathspecs.length) {
+      await this._git(['rm', '-r', '--cached', '-q', '--ignore-unmatch', '--',
+        ...excludePathspecs.map((s) => s.replace(/^:\(exclude\)/, ''))], gitOpts);
+    }
     const add = excludePathspecs.length
       ? await this._git(['add', '-A', '--', '.', ...excludePathspecs], gitOpts)
       : await this._git(['add', '-A'], gitOpts);
@@ -2319,8 +2668,9 @@ export class RunHarness extends EventEmitter {
         gitOpts,
       );
     }
-    if (!commit.ok && excludePathspecs.length) {
-      // §8.8 (detached runs — the same scope as the exclusion set): a failing hook
+    if (!commit.ok && this.runRootMode === 'detached') {
+      // §8.8 (detached runs only — legacy keeps its verbatim commit even now that it carries an
+      // exclusion set): a failing hook
       // must never silently delete an agent's work. Teardown removeWorktree(force:true)s
       // the checkout right after a successful commit, so this commit is the ONLY thing
       // that carries the work onto the kept branch. A diff artifact does now survive
@@ -2329,7 +2679,9 @@ export class RunHarness extends EventEmitter {
       // rebase or push. Detached worktrees make hook failure MORE likely (§8.1:
       // husky/lint-staged resolve through an ancestor node_modules today and do not
       // detached). Retry ONCE with hooks disabled for that invocation only, logging
-      // both facts.
+      // both facts. The gate is the MODE, not the exclusion set: before the native-rules
+      // revision a detached default-workflow run recorded no injected path at all and was
+      // silently excluded from the retry — exactly the runs §8.1 is about.
       const hookErr = commit.stderr.trim() || `exit ${commit.code}`;
       this._log('git', 'warn', `commit failed with hooks enabled: ${hookErr}`, errStreamAttr(commit.stderr));
       const retry = await this._git(
@@ -2556,7 +2908,7 @@ export class RunHarness extends EventEmitter {
    * Freezes the active-time clock while blocked on the user (active-time-only).
    * @returns {Promise<any>} the answer payload
    */
-  async _ask({ id, kind, questions, issues, recovery, agent, nodeId, wireId, executionId, deliveryNo, holdNo }) {
+  async _ask({ id, kind, questions, issues, recovery, agent, nodeId, wireId, executionId, deliveryNo, holdNo, workflow, validate }) {
     this._checkAbort();
     // No interactive prompt may OPEN on a pausing run. pause() rejects only the
     // prompt that is currently open; a queued ask (a parallel sibling's questions
@@ -2587,7 +2939,9 @@ export class RunHarness extends EventEmitter {
       // trail — reads these fields instead of parsing the id (MAJ-11).
       ...(deliveryNo != null ? { deliveryNo } : {}),
       ...(holdNo != null ? { holdNo } : {}),
+      ...(workflow !== undefined ? { workflow } : {}),
     });
+    this._metricsIv.questions += 1;
 
     try {
       if (this.auto) {
@@ -2597,6 +2951,11 @@ export class RunHarness extends EventEmitter {
           // pauses the run (errors never end one), so 'pause' is the answer.
           return { decision: 'pause' };
         }
+        if (kind === 'workflow') {
+          // Auto workflow under --yes: the proposal is accepted as proposed (spec D3).
+          this._log('orchestrator', 'info', `auto-accepting workflow proposal ${id}`);
+          return { decision: 'accept' };
+        }
         if (kind === 'clarify' || kind === 'questions') {
           this._log('orchestrator', 'info', `auto-answering ${kind} ${id}`);
           return {
@@ -2610,7 +2969,7 @@ export class RunHarness extends EventEmitter {
         return { decision: 'continue' };
       }
       return await new Promise((resolveP, rejectP) => {
-        this.pendingQuestion = { id, kind, resolve: resolveP, reject: rejectP };
+        this.pendingQuestion = { id, kind, resolve: resolveP, reject: rejectP, validate: typeof validate === 'function' ? validate : null };
       });
     } finally {
       // Resume only the rows that are STILL running AND only while the run has not
@@ -2718,6 +3077,10 @@ export class RunHarness extends EventEmitter {
       // bound signal kills the staging before git can touch the index.
       // INSIDE the try: the stopped path calls _buildResults from run()'s catch, so
       // anything that escaped here would reject run() itself.
+      // The final sync runs BEFORE the two early returns below (`!members.length`,
+      // `noPatch && stage && !listed`), so results.json.memory is absent on those paths;
+      // the ledger (memory.json) is the durable carrier and History reads it.
+      if (this.memory) await this._syncMemory(null, { nodeId: 'final', executionId: null, label: 'the run end' }).catch(() => {});
       if (stage) await this._stageWorkingTree({ ignoreAbort: true });
       const reviews = readPipelineExtras(this.pipeline.id).reviews || [];
       // Unified iteration over workDirs + checkpointRefs — the ref map is filled in
@@ -2764,12 +3127,14 @@ export class RunHarness extends EventEmitter {
       // no-op run must not lose them (review of PR #376). The 0-byte
       // diff-patch.patch is still never written on any path.
       if (noPatch && stage && !listed) return;
+      const memory = this.memorySummary();
       if (members.length === 1 && !this.isWorkspace) {
+        if (memory) members[0].results.memory = memory;
         await persistResults(this.pipeline.dir, members[0].results);
         if (!noPatch) await persistDiffPatch(this.pipeline.dir, patches[0].patch);
       } else {
         const perProject = buildPerProject(members);
-        const results = { summary: rollupSummary(perProject), perProject };
+        const results = { summary: rollupSummary(perProject), perProject, ...(memory ? { memory } : {}) };
         await persistResults(this.pipeline.dir, results);
         if (!noPatch) await persistDiffPatch(this.pipeline.dir, patches.map((p) => `# ${p.key}\n${p.patch}`).join('\n\n'));
       }
@@ -2809,6 +3174,19 @@ export class RunHarness extends EventEmitter {
     }
   }
 
+  /** Team metrics (team-metrics-design.md §4.5): one record per terminal run. Idempotent per
+   *  instance and fail-soft — a metrics failure is a log line, never a run failure. */
+  async _recordRunMetrics(status, error = null) {
+    if (this._metricsRecorded) return null;
+    this._metricsRecorded = true;
+    try {
+      return await recordRunMetrics(this, { status, error });
+    } catch (err) {
+      try { this._log('metrics', 'warn', `team metrics: ${err?.message || err}`); } catch { /* never */ }
+      return null;
+    }
+  }
+
   /** Single-project checkpoint: own repo + commit, record the scalar ref + state. */
   async _ensureGitCheckpoint() {
     this.checkpointRef = await this._ensureGitCheckpointFor(this.projectDir);
@@ -2877,8 +3255,8 @@ export class RunHarness extends EventEmitter {
     // setup never ran, in which case staging must be a NO-OP — the old single arm
     // fell back to this.workDir, which pre-setup is the user's LIVE checkout.
     for (const [key, dir] of this.workDirs.entries()) {
-      // §8.8: an empty exclusion set (every legacy run) reproduces today's argv
-      // byte-identically — `--` with no trailing pathspec is a no-op for git add.
+      // §8.8: the exclusion set is the memory mount in both modes (and the skill mount under
+      // detached); an empty set (a refused mount) reproduces the bare argv.
       const ex = this._excludePathspecs(key);
       const args = ex.length ? ['add', '-A', '-N', '--', '.', ...ex] : ['add', '-A', '-N'];
       const res = await this._git(args, { cwd: dir, ignoreAbort });
@@ -2894,8 +3272,9 @@ export class RunHarness extends EventEmitter {
    * `kind:'claudeMdSection'` entries are deliberately EXCLUDED from the set — their
    * file is the user's tracked CLAUDE.md, and a blanket `:(exclude)CLAUDE.md` would
    * silently strip the agent's legitimate edits (teardown strips the fence instead).
-   * Returns [] under legacy and through Phase 2 (this.injectedPaths is always {}),
-   * which is what makes every legacy argv byte-identical.
+   * Under legacy the set holds exactly the memory mount (`_registerMemoryMount`), so
+   * `git add -A -- . :(exclude).claude/rules/worca` is the legacy argv since the
+   * native-rules revision.
    * @param {string} projectKey
    * @returns {string[]}
    */
@@ -2909,9 +3288,17 @@ export class RunHarness extends EventEmitter {
 
   /**
    * Run a git command in the project dir. Never throws; returns
-   * { ok, code, stdout, stderr }. Honors the abort signal.
+   * { ok, code, stdout, stderr }. Honors the abort signal. Bounded by
+   * `timeoutMs` (default HARNESS_GIT_TIMEOUT_MS): the commands issued here are
+   * local (init/add/status/rev-parse/commit/diff --cached), and a git that does
+   * not come back in that time is stuck, not working — it is SIGKILLed and
+   * reported as `{ ok: false, stderr: 'git timed out' }`, which every caller
+   * already handles as a failed git step. Without this bound a wedged git on
+   * the stop/teardown path (which deliberately ignores the abort signal) held
+   * the whole process, and under `npm test` the runner, until the CI job's
+   * 30-minute limit killed it.
    */
-  _git(args, { cwd, ignoreAbort = false } = {}) {
+  _git(args, { cwd, ignoreAbort = false, timeoutMs = HARNESS_GIT_TIMEOUT_MS } = {}) {
     return new Promise((resolveP) => {
       let child;
       try {
@@ -2929,12 +3316,26 @@ export class RunHarness extends EventEmitter {
       }
       let stdout = '';
       let stderr = '';
+      let settled = false;
+      const done = (val) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolveP(val);
+      };
+      const timer = timeoutMs > 0
+        ? setTimeout(() => {
+          try { child.kill('SIGKILL'); } catch { /* already gone */ }
+          // A grandchild (hook, alias, pager) that inherited the pipes would keep
+          // them — and this process's event loop — open after git itself is dead.
+          try { child.stdout?.destroy(); child.stderr?.destroy(); } catch { /* best effort */ }
+          done({ ok: false, code: -1, stdout, stderr: stderr ? `git timed out: ${stderr}` : 'git timed out' });
+        }, timeoutMs)
+        : null;
       child.stdout?.on('data', (d) => (stdout += d.toString()));
       child.stderr?.on('data', (d) => (stderr += d.toString()));
-      child.on('error', (err) =>
-        resolveP({ ok: false, code: -1, stdout, stderr: stderr || err.message }),
-      );
-      child.on('close', (code) => resolveP({ ok: code === 0, code: code ?? -1, stdout, stderr }));
+      child.on('error', (err) => done({ ok: false, code: -1, stdout, stderr: stderr || err.message }));
+      child.on('close', (code) => done({ ok: code === 0, code: code ?? -1, stdout, stderr }));
     });
   }
 
@@ -3096,7 +3497,7 @@ export class RunHarness extends EventEmitter {
   /**
    * @param {string} kind
    * @param {string} path
-   * @param {{nodeId?:string, executionId?:string, port?:string|null}|null} [attr]
+   * @param {{nodeId?:string, executionId?:string, port?:string|null, cycle?:number|null}|null} [attr]
    *   v2 attribution (§5.7). Omitted keys are omitted from the event, so every
    *   2-arg v1 call emits the byte-identical `{kind, path}` payload it always did.
    */
@@ -3106,15 +3507,19 @@ export class RunHarness extends EventEmitter {
       if (attr.nodeId != null) evt.nodeId = attr.nodeId;
       if (attr.executionId != null) evt.executionId = attr.executionId;
       if (attr.port != null) evt.port = attr.port;
+      if (attr.cycle != null) evt.cycle = attr.cycle;
     }
     this._emit('artifact', evt);
-    // Phase 3.9: ALSO index FS markdown/extra paths so pipeline-delete (Task 3.13)
-    // can unlink the EXACT files later (best-effort; never blocks a run). Skip the
-    // synthetic 'pipeline'/'clarify' kinds (clarify lives in the clarify table;
-    // 'pipeline' is the dir itself). plan/review markdown live under
-    // <store>/<key>/{plans,reviews} (store-root-relative); checklist/webui live in
-    // the pipeline dir (dir-relative).
-    if (!this.pipeline || !path || kind === 'pipeline' || kind === 'clarify' || kind === 'questions') return;
+    // ALSO index FS markdown/extra paths so pipeline-delete can unlink the EXACT
+    // files later, per-step attribution rides along (best-effort; never blocks a
+    // run). Every kind with a durable on-disk relPath is recorded. Skipped:
+    // 'pipeline' (the run DIR itself, no single file) and 'questions' (a scratch
+    // file the orchestrator deletes once the round is answered — the Q&A lives in
+    // the step_questions table, so an index row would only ever 404). The WS
+    // event above still carries 'questions' for the live view. plan/review
+    // markdown live under <store>/<key>/{plans,reviews} (store-root-relative);
+    // prompt/checklist/webui live in the pipeline dir (dir-relative).
+    if (!this.pipeline || !path || kind === 'pipeline' || kind === 'questions') return;
     let relPath = null;
     const pdir = this.pipeline.dir;
     if (path.startsWith(pdir + sep)) {
@@ -3128,7 +3533,13 @@ export class RunHarness extends EventEmitter {
     // Indexed with '/' on every OS: the row is a store-layout key, not a native
     // path (pipeline-delete re-roots 'plans/…' / 'reviews/…' under the store),
     // so a Windows-native 'reviews\\x.md' would silently miss that re-rooting.
-    if (relPath) recordArtifact(this.pipeline.id, kind, relPath.split(sep).join('/'));
+    if (relPath) {
+      recordArtifact(this.pipeline.id, kind, relPath.split(sep).join('/'), {
+        stepKey: attr?.executionId ?? null,
+        nodeId: attr?.nodeId ?? null,
+        cycle: attr?.cycle ?? null,
+      });
+    }
   }
 
   /** Translate a low-level claude/mock event into a pipeline 'log' event. */
@@ -3680,6 +4091,8 @@ export class RunHarness extends EventEmitter {
   }
 
   async _persist() {
+    const rpNow = this.state.resumePoint;
+    if (rpNow && typeof rpNow === 'object' && this._metricsIv) rpNow.interventions = { ...this._metricsIv };
     if (!this.pipeline) return;
     try {
       await writeState(this.pipeline.dir, this.state);
@@ -3718,6 +4131,11 @@ export class RunHarness extends EventEmitter {
     // 'pausing') must replay that setup on resume; a completed setup never leaves a
     // stale stamp behind (resume() re-arms the consumed point, which may carry one).
     const rp = this.state.resumePoint;
+    // ABOVE the `if (rp …)` — a pause counts whether or not the engine produced a resume point.
+    this._metricsIv.pauses += 1;
+    this._metricsIv.lastPauseReason = this.pauseReason || null;
+    // _setPauseReason (run-harness.mjs:820) always stores a string or null.
+    this._metricsIv.lastPauseDetail = this.pauseDetail == null ? null : String(this.pauseDetail).slice(0, 400);
     if (rp && typeof rp === 'object') {
       if (this._setupDone) { delete rp.setupIncomplete; delete rp.titleProvisional; }
       else {
@@ -3727,6 +4145,7 @@ export class RunHarness extends EventEmitter {
         // not a row column.
         rp.titleProvisional = this.state.titleProvisional === true;
       }
+      rp.interventions = { ...this._metricsIv };
     }
     this._setStatus('paused');
     await this._persist();
@@ -3878,6 +4297,13 @@ export class RunHarness extends EventEmitter {
    *  workflow -> the run's audit line. */
   async _resolveTopology(_registry) { throw new Error('engine hook not implemented: _resolveTopology'); }
 
+  /** Decide the run's topology AFTER the run row + run root exist (the Auto
+   *  workflow). run() calls it with no argument and REPLACES the bootstrap
+   *  manifest with a non-null return (the same bag as _resolveTopology); resume()
+   *  calls it with `{ resume: rp }` before the setup replay. null keeps what
+   *  _resolveTopology produced (every saved workflow). */
+  async _decideTopology(_o = {}) { return null; }
+
   /** Run the pipeline to completion or to a pause.
    *  @param {{resume?:object|null, rehydrated?:object|null}} _args resume point + _engineRehydrate's bag
    *  @returns {Promise<'done'|'paused'>} */