@dzhechkov/harness-core 0.4.1 → 0.4.3

package/src/loop-plan-graph.ts

@@ -0,0 +1,132 @@
+/**
+ * loop-plan-graph (idea d25a3c8a) — the COMPLETENESS leg of loop-plan/1's closed-world checking.
+ *
+ * What existed before this module (the round-7 cross-family reviewer's ONE not-met bar item,
+ * SIGNOFF's "B-not-A reason 1"): `KNOWN_KEYS === INJECT` and the honesty test's `SCANNED` roster
+ * all compare artifacts DOWNSTREAM of FIELD_DOMAINS — equality proves the rosters are consistent
+ * with each other, never that they are COMPLETE against the interface source. The reviewer's
+ * constructive counterexample: declare `LoopStep.extra?: ExtraPolicy`, add only the parent
+ * `{t:'record'}` domain entry, and `extra: { enabeld: true }` escapes every check while every
+ * equality guard stays green — "a new record kind cannot escape is unproven and demonstrably
+ * false" (verbatim). The shipped mitigation was a documented four-step extension discipline — a
+ * layer-4 instruction, exactly the layer the cost-of-detection ladder says such a check must not
+ * live on.
+ *
+ * THE FIX (this module, layer 1): walk the interface graph from `LoopPlan` in the SOURCE TEXT,
+ * transitively collect every reachable named interface, and let the honesty test require that the
+ * reachable set is exactly the wired set. An interface reachable from LoopPlan but absent from the
+ * wiring fails BY CONSTRUCTION, naming itself — no memory, no discipline, no fourth manual step.
+ *
+ * PURE: operates on source text handed in by the caller; no fs, no clock. That is what lets the
+ * acceptance test run the reviewer's counterexample against a SABOTAGED COPY of the source and
+ * require a red, while the real source stays green.
+ */
+
+/** One parsed field: its name and the DECLARED interface names its type text references. */
+export interface GraphField {
+  readonly field: string;
+  readonly refs: readonly string[];
+}
+
+/** interface name → its fields (index signatures like `[xKey: \`x-${string}\`]` are excluded:
+ * they open no named-interface edge and are the extension escape hatch by design). */
+export type InterfaceGraph = ReadonlyMap<string, readonly GraphField[]>;
+
+/** Brace-matched interface extraction. A regex-only scan truncates at the first nested brace
+ * (inline object fields are everywhere in this file), so bodies are cut by depth counting. */
+export function parseInterfaceGraph(source: string): InterfaceGraph {
+  const names = new Set<string>();
+  const headRe = /(?:^|\n)\s*(?:export\s+)?interface\s+([A-Za-z_$][\w$]*)/g;
+  for (let m = headRe.exec(source); m !== null; m = headRe.exec(source)) names.add(m[1]!);
+
+  const graph = new Map<string, GraphField[]>();
+  headRe.lastIndex = 0;
+  for (let m = headRe.exec(source); m !== null; m = headRe.exec(source)) {
+    const name = m[1]!;
+    const open = source.indexOf('{', m.index + m[0].length);
+    if (open === -1) continue;
+    let depth = 0;
+    let close = -1;
+    for (let i = open; i < source.length; i += 1) {
+      const ch = source[i];
+      if (ch === '{') depth += 1;
+      else if (ch === '}') {
+        depth -= 1;
+        if (depth === 0) { close = i; break; }
+      }
+    }
+    if (close === -1) continue;
+    const body = source.slice(open + 1, close);
+
+    // Split the body into top-level entries at depth 0 (`;` inside an inline `{...}` must not cut).
+    const entries: string[] = [];
+    let entry = '';
+    let d = 0;
+    for (const ch of body) {
+      if (ch === '{' || ch === '(' || ch === '<' || ch === '[') d += 1;
+      else if (ch === '}' || ch === ')' || ch === '>' || ch === ']') d -= 1;
+      if (ch === ';' && d === 0) { entries.push(entry); entry = ''; continue; }
+      entry += ch;
+    }
+    if (entry.trim() !== '') entries.push(entry);
+
+    const fields: GraphField[] = [];
+    for (const raw of entries) {
+      // strip comments, then match `readonly? name?: TYPE`
+      const text = raw.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '').trim();
+      if (text === '' || text.startsWith('[')) continue; // index signature — by-design escape hatch
+      const fm = /^(?:readonly\s+)?([A-Za-z_$][\w$]*)\s*\??:\s*([\s\S]+)$/.exec(text);
+      if (fm === null) continue;
+      const typeText = fm[2]!;
+      const refs = new Set<string>();
+      const idRe = /[A-Za-z_$][\w$]*/g;
+      for (let im = idRe.exec(typeText); im !== null; im = idRe.exec(typeText)) {
+        if (names.has(im[0]) && im[0] !== name) refs.add(im[0]);
+      }
+      fields.push({ field: fm[1]!, refs: [...refs] });
+    }
+    graph.set(name, fields);
+  }
+  return graph;
+}
+
+/** Every interface reachable from `root` (inclusive), via any field's declared-interface refs —
+ * arrays, unions and nullables all count: `LoopStep[]`, `RetryProfile | null` open the same edge. */
+export function reachableInterfaces(graph: InterfaceGraph, root: string): string[] {
+  const seen = new Set<string>();
+  const queue = [root];
+  while (queue.length > 0) {
+    const name = queue.shift()!;
+    if (seen.has(name) || !graph.has(name)) continue;
+    seen.add(name);
+    for (const f of graph.get(name)!) for (const ref of f.refs) if (!seen.has(ref)) queue.push(ref);
+  }
+  return [...seen].sort();
+}
+
+export interface GraphWiringReport {
+  readonly ok: boolean;
+  /** Reachable from the root but NOT in the wired roster — each one is exactly the reviewer's
+   * counterexample: a record kind whose key space is open while every equality guard stays green. */
+  readonly unwired: string[];
+  readonly reachable: string[];
+  /** Wired but no longer reachable — a stale roster entry (the reverse rot). */
+  readonly stale: string[];
+}
+
+/** The completeness check the equality guards could not perform: reachable(source) vs wired. */
+export function checkGraphWiring(source: string, wired: readonly string[], root = 'LoopPlan'): GraphWiringReport {
+  const graph = parseInterfaceGraph(source);
+  const reachable = reachableInterfaces(graph, root);
+  const wiredSet = new Set(wired);
+  const reachableSet = new Set(reachable);
+  const unwired = reachable.filter((n) => !wiredSet.has(n));
+  // The wired roster (KNOWN_KEYS) legitimately mixes interface names with INLINE-record FIELD names
+  // (`artifacts`, `budget`, `checkpointing`, …) — those are the inlineSubFields machinery's
+  // business, not this check's. Staleness is judged only for entries that ARE declared interfaces
+  // in this source: a declared-but-unreachable interface in the roster is real rot; an inline field
+  // name is not an interface and must not be reported as one (caught on the first live run: five
+  // false stale entries, all inline fields).
+  const stale = [...wiredSet].filter((n) => graph.has(n) && !reachableSet.has(n)).sort();
+  return { ok: unwired.length === 0 && stale.length === 0, unwired, reachable, stale };
+}

package/src/loop-plan.ts

@@ -389,22 +389,20 @@ export const FIELD_DOMAINS: Record<string, FieldDomain> = {
 // domain entry fails the honesty test; adding it WITH one makes it known here automatically. There
 // is exactly one roster, and it is the source's.
 //
-// WHAT THIS DOES AND DOES NOT PROVE (QE round-7, the cross-family reviewer's ONE not-met bar item,
-// CONCEDED). PROVEN, and tested: every record path CURRENTLY WIRED here is closed — no key of any
-// present-day spelling reaches the plan without a diagnostic, and the accepted roster is the
-// source's, not a second hand-list. NOT PROVEN, and it would be an overclaim to say otherwise: that
-// a record kind added in the FUTURE is closed AUTOMATICALLY. Three things remain hand-bounded —
-// (a) the honesty test's `SCANNED` names the interfaces it scans, (b) the fuzz's `INJECT` names the
-// injection sites, and (c) `checkKeys`' parser DESCENT names which nested records it walks. The
-// reviewer's constructive counterexample: declare `LoopStep.extra?: ExtraPolicy` with only a
-// `LoopStep.extra: {t:'record'}` domain entry and an `ExtraPolicy { enabled?: boolean }` interface —
-// unless someone ALSO hand-adds ExtraPolicy's own domains, the descent, `SCANNED` and `INJECT`, then
-// `extra: { enabeld: true }` escapes closed-world checking WHILE the equality assertions stay green.
-// That is a future-extension / proof-maintenance hole, not an input bypass that works today.
+// WHAT THIS PROVES (updated 2026-08-17, idea d25a3c8a — the round-7 not-met bar item is now MET).
+// PROVEN, and tested: every record path wired here is closed, the accepted roster is the source's,
+// AND the roster is COMPLETE against the interface graph: `loop-plan-graph.ts` walks the interfaces
+// reachable from LoopPlan in this file's SOURCE and the honesty test requires reachable == wired ==
+// SCANNED. The reviewer's constructive counterexample (`LoopStep.extra?: ExtraPolicy` with a
+// parent-only domain entry) is the ACCEPTANCE TEST: it goes red naming ExtraPolicy, by
+// construction, before any hand step. Still out of scope, said plainly: interfaces referenced only
+// through type ALIASES are followed one identifier deep (the graph collects declared-interface
+// names from the field's type text); an alias chain that hides an interface behind a non-interface
+// alias would need the alias declared in this file to be walked.
 //
-// EXTENSION DISCIPLINE (the manual step the derivation does not perform for you). When you add a
-// NEW nested record-typed field, do ALL FOUR in the same change, or the key space it opens is not
-// closed: 1) add `<NewIface>.<field>` entries to FIELD_DOMAINS for every field of the new interface
+// EXTENSION CONVENIENCE (no longer load-bearing — the graph-completeness test reddens on a missed
+// step by construction; this list just tells you what the red means). When you add a NEW nested
+// record-typed field: 1) add `<NewIface>.<field>` entries to FIELD_DOMAINS for every field of the new interface
 // (not just the `{t:'record'}` entry on its PARENT); 2) add the new interface to the honesty test's
 // `SCANNED`; 3) add an `INJECT` site for it in the closed-world fuzz; 4) descend into it in
 // `checkKeys`. A structural fix that derives 2–4 from the interface graph — so a new record kind is

package/src/loop-render.ts

@@ -149,6 +149,7 @@ function landedBarrier(id: string, phase: string, writes: string[], pad: string)
     `${pad}  const probeCmd = 'cd ' + shqRt(TRACE_DIR === null ? '.' : TRACE_DIR) + ${jsString(' && ' + testExpr + ' && echo LANDED || echo NOT-LANDED')}`,
     `${pad}  let landed = false`,
     `${pad}  for (let p = 0; p < 5 && !landed; p++) {`,
+    `${pad}    __agentCalls++`,
     `${pad}    const probe = await agent('Run EXACTLY this one shell command via your Bash tool and reply with ONLY its raw stdout: ' + probeCmd, { label: ${jsString('landed:' + id)}, phase: ${jsString(phase)}, effort: 'low' }) // loop-lint: infra-agent`,
     `${pad}    landed = typeof probe === 'string' && probe.indexOf('NOT-LANDED') === -1 && probe.indexOf('LANDED') !== -1`,
     `${pad}  }`,
@@ -283,8 +284,8 @@ function renderStep(v: StepPlanView, plan: LoopPlan, env: RenderEnv): string {
       .map((d) => `r_${ident(d)}`);
     const hashParts = `[P_${ident(id)}${depVars.length > 0 ? ', ' + depVars.join(', ') : ''}]`;
     const artifactRel = writes.length > 0 ? JSON.stringify(writes) : 'null';
-    const tpLine = (pad: string): string =>
-      `${pad}await __tpCapture(${jsString(id)}, ${jsString(s.phase)}, P_${ident(id)}, r_${ident(id)}, ${typeof s.model === 'string' && s.model !== '' ? jsString(s.model) : 'null'})`;
+    const tpLine = (pad: string, resumed: boolean): string =>
+      `${pad}await __tpCapture(${jsString(id)}, ${jsString(s.phase)}, P_${ident(id)}, r_${ident(id)}, ${typeof s.model === 'string' && s.model !== '' ? jsString(s.model) : 'null'}, ${resumed ? 'true' : 'false'})`;
 
     // ROUND-6 B3 SHAPE: `let r_x` + (optional) dispatch-fn declaration form the await-free
     // preamble; then exactly ONE settle-routed try wraps EVERY await this step performs —
@@ -303,13 +304,14 @@ function renderStep(v: StepPlanView, plan: LoopPlan, env: RenderEnv): string {
         lines.push(`  if (__live !== true && __ckptResume(${jsString(id)}, __h, ${artifactRel})) {`);
         lines.push(`    r_${ident(id)} = __ckptEntries[${jsString(id)}].result`);
         lines.push(`    log(${jsString(`checkpoint: step ${id} RESUMED (fingerprint+artifact match) — dispatch skipped`)})`);
+        if (tp) lines.push(tpLine('    ', true));
         lines.push(`    return r_${ident(id)}`);
         lines.push(`  }`);
       }
       lines.push(`  r_${ident(id)} = await ${runExpr}`);
       if (writes.length > 0) lines.push(...landedBarrier(id, s.phase, writes, '  '));
       if (ckpt) lines.push(`  await __ckptAppend(${jsString(id)}, ${jsString(s.phase)}, __h, r_${ident(id)})`);
-      if (tp) lines.push(tpLine('  '));
+      if (tp) lines.push(tpLine('  ', false));
       lines.push(`  return r_${ident(id)}`);
       lines.push(`}`);
     }
@@ -320,16 +322,17 @@ function renderStep(v: StepPlanView, plan: LoopPlan, env: RenderEnv): string {
         lines.push(`  if (__ckptResume(${jsString(id)}, __h_${ident(id)}, ${artifactRel})) {`);
         lines.push(`    r_${ident(id)} = __ckptEntries[${jsString(id)}].result`);
         lines.push(`    log(${jsString(`checkpoint: step ${id} RESUMED (fingerprint+artifact match) — dispatch skipped`)})`);
+        if (tp) lines.push(tpLine('    ', true));
         lines.push(`  } else {`);
         lines.push(`    r_${ident(id)} = await ${runExpr}`);
         if (writes.length > 0) lines.push(...landedBarrier(id, s.phase, writes, '    '));
         lines.push(`    await __ckptAppend(${jsString(id)}, ${jsString(s.phase)}, __h_${ident(id)}, r_${ident(id)})`);
-        if (tp) lines.push(tpLine('    '));
+        if (tp) lines.push(tpLine('    ', false));
         lines.push(`  }`);
       } else {
         lines.push(`  r_${ident(id)} = await ${runExpr}`);
         if (writes.length > 0) lines.push(...landedBarrier(id, s.phase, writes, '  '));
-        if (tp) lines.push(tpLine('  '));
+        if (tp) lines.push(tpLine('  ', false));
       }
     } else {
       lines.push(`  await __dispatch_${ident(id)}()`);
@@ -353,6 +356,7 @@ function renderStep(v: StepPlanView, plan: LoopPlan, env: RenderEnv): string {
         if (routeIsTerminal) {
           lines.push(`  if (__v_${ident(id)} !== 'pass') {`);
           lines.push(`    // typed terminal failure route (plan gates[].failRoute) — a NAMED phase, never a silent pass; settled durably through the single exit (round-5 B3)`);
+          lines.push(`    await __ledgerAppend(${jsString(s.phase)}, ${jsString((route as string).slice('terminal:'.length))})`);
           lines.push(`    return await __settleStep({ stepId: ${jsString(id)}, phase: ${jsString(s.phase)}, outcome: 'terminal', value: { phase: ${jsString(route as string)}, gate: ${jsString(id)}, verdict: __v_${ident(id)} } })`);
           lines.push(`  }`);
         } else {
@@ -373,8 +377,10 @@ function renderStep(v: StepPlanView, plan: LoopPlan, env: RenderEnv): string {
     if (pause?.payloadSchema !== undefined) {
       // enacts pauses[].payloadSchema: the pause return CARRIES the declared payload shape, so the
       // re-invoking caller sees what the resume arg must contain.
+      lines.push(`  await __ledgerAppend(${jsString(s.phase)}, ${jsString(pauseState)})`);
       lines.push(`  return await __settleStep({ stepId: ${jsString(id)}, phase: ${jsString(s.phase)}, outcome: 'terminal', value: { phase: ${jsString(pauseState)}, resumeArg: ${jsString(resumeArg)}, payloadSchema: ${JSON.stringify(pause.payloadSchema)} } })`);
     } else {
+      lines.push(`  await __ledgerAppend(${jsString(s.phase)}, ${jsString(pauseState)})`);
       lines.push(`  return await __settleStep({ stepId: ${jsString(id)}, phase: ${jsString(s.phase)}, outcome: 'terminal', value: { phase: ${jsString(pauseState)}, resumeArg: ${jsString(resumeArg)} } })`);
     }
     lines.push(`}`);
@@ -481,8 +487,17 @@ function renderRuntime(plan: LoopPlan, planDig: string, execFp: string, blobs: L
   lines.push(`const RUN_ID = (typeof A.runId === 'string' && /^[a-z0-9-]{1,40}$/.test(A.runId)) ? A.runId : 'run-1'`);
   lines.push(`const TRACE_DIR = (typeof A.traceDir === 'string' && A.traceDir.charAt(0) === '/') ? A.traceDir.replace(/\\/+$/, '') : null`);
   lines.push(`const TRACE_FILE = TRACE_DIR === null ? null : TRACE_DIR + '/trace.jsonl'`);
+  lines.push(`const REPO_DIR = (typeof A.repo === 'string' && A.repo.charAt(0) === '/') ? A.repo.replace(/\\/+$/, '') : null`);
+  lines.push(`const DZ_BIN = (typeof A.dz === 'string' && A.dz !== '') ? A.dz : 'dz'`);
+  lines.push(`const LOOP_SLUG = ${jsString(plan.name)}`);
   lines.push(`// budget guard — spent BEFORE every spawn; retries consume budget (lint: budget-before-spawn)`);
   lines.push(`const __budget = { left: ${budgetTotal} }`);
+  lines.push(`// Total agent invocations this run made — model dispatches AND infra agents. The ledger's`);
+  lines.push(`// \`agents\` column means agent_count from the completion notification (ALL subagents), so the`);
+  lines.push(`// automated row must count every dispatch, never the trace's model-dispatch subset (QE F1).`);
+  lines.push(`let __agentCalls = 0`);
+  lines.push(`let __ledgerDone = false`);
+  if (traceOn) lines.push(`let __faLegWarned = false`);
   lines.push(`function __spendBudget(stepId) { if (__budget.left <= 0) { throw new Error('loop budget exhausted before ' + stepId) } __budget.left-- }`);
   lines.push(`const __hooks = { onDispatch: null, onSettle: null }`);
   lines.push(`const __settled = {}`);
@@ -580,7 +595,11 @@ function renderRuntime(plan: LoopPlan, planDig: string, execFp: string, blobs: L
   lines.push(`// SECONDARY event; it never replaces the primary outcome — success included (the ha-consilium`);
   lines.push(`// totality lesson at the flush layer).`);
   lines.push(`async function __settleStep(o) {`);
-  lines.push(`  try { await __traceFlushNow(o.phase) } catch (_fe) { log('settle flush for ' + o.stepId + ' threw: ' + __errText(_fe) + ' — primary outcome preserved') }`);
+  lines.push(`  try { await __traceFlushNow(o.phase, o.stepId) } catch (_fe) { log('settle flush for ' + o.stepId + ' threw: ' + __errText(_fe) + ' — primary outcome preserved') }`);
+  if (plan.subsystems?.trainingPairs === true) {
+    lines.push(`  // The ONE producer of the captureFailures channel on terminal values — the four terminal call sites never carry the key, so future routes inherit it.`);
+    lines.push(`  if (o.outcome === 'terminal' && o.value !== null && typeof o.value === 'object') { o.value.captureFailures = __captureFailures }`);
+  }
   lines.push(`  if (o.outcome === 'failed') { throw o.error }`);
   lines.push(`  return o.value`);
   lines.push(`}`);
@@ -588,7 +607,7 @@ function renderRuntime(plan: LoopPlan, planDig: string, execFp: string, blobs: L
   lines.push(`// secondary event, never a replaced outcome (the naked await __traceFlushNow at phase`);
   lines.push(`// boundaries was the round-5 success-replacement hole).`);
   lines.push(`async function __phaseFlush(phaseName) {`);
-  lines.push(`  try { await __traceFlushNow(phaseName) } catch (_fe) { log('phase flush threw: ' + __errText(_fe) + ' — outcome preserved (flush failure is secondary)') }`);
+  lines.push(`  try { await __traceFlushNow(phaseName, null) } catch (_fe) { log('phase flush threw: ' + __errText(_fe) + ' — outcome preserved (flush failure is secondary)') }`);
   lines.push(`}`);
   lines.push(`// join failures route through the single exit too (joinRegion throws; the wrapper settles)`);
   lines.push(`async function __joinSettled(joinStepId, phaseName, results, o) {`);
@@ -620,6 +639,7 @@ function renderRuntime(plan: LoopPlan, planDig: string, execFp: string, blobs: L
   lines.push(`    let value = null`);
   lines.push(`    let outcome = 'ok'`);
   lines.push(`    try {`);
+  lines.push(`      __agentCalls++`);
   lines.push(`      value = await thunk()`);
   lines.push(`      if (value === null || value === undefined) outcome = 'null'`);
   lines.push(`    } catch (err) {`);
@@ -706,15 +726,36 @@ function renderRuntime(plan: LoopPlan, planDig: string, execFp: string, blobs: L
     lines.push(`const __traceState = traceInit(RUN_ID, PLAN_DIGEST, EXEC_FP)`);
     lines.push(`__hooks.onDispatch = function (e) { return traceOnDispatch(__traceState, e) }`);
     lines.push(`__hooks.onSettle = function (e) { return traceOnSettle(__traceState, e) }`);
-    lines.push(`async function __traceFlushNow(phaseName) {`);
+    lines.push(`async function __traceFlushNow(phaseName, stepLabel) {`);
     lines.push(`  if (TRACE_FILE === null) { return }`);
-    lines.push(`  const cmd = traceFlushCmd(__traceState, TRACE_FILE)`);
+    lines.push(`  // cmd must be let: the trace payload stays LEFT and must never be replaced by the fa-record panel leg; both ride the SAME writer agent.`);
+    lines.push(`  let cmd = traceFlushCmd(__traceState, TRACE_FILE)`);
     lines.push(`  if (cmd === null) { return }`);
+    lines.push(`  const fa = traceFaRecordCmd(DZ_BIN, LOOP_SLUG, (typeof stepLabel === 'string' && stepLabel !== '') ? stepLabel : phaseName, REPO_DIR)`);
+    lines.push(`  if (fa !== null) { cmd = cmd + ' && { ' + fa + ' || true; }' }`);
+    lines.push(`  else if (REPO_DIR === null && !__faLegWarned) { __faLegWarned = true; log('fa-record leg skipped — the live panel was not updated because no args.repo was given (the trace flush still runs)') }`);
     lines.push(`  // the flush agent is infra, not a step (it would otherwise recurse) // loop-lint: infra-agent`);
+    lines.push(`  __agentCalls++`);
     lines.push(`  await agent('Run EXACTLY this one shell command via your Bash tool and reply with only OK: ' + cmd, { label: 'trace:flush', phase: phaseName, effort: 'low' }) // loop-lint: infra-agent`);
     lines.push(`}`);
+    lines.push(`async function __ledgerAppend(phaseName, outcome) {`);
+    lines.push(`  if (__ledgerDone) { return } __ledgerDone = true`);
+    lines.push(`  // Ledger telemetry is SECONDARY: this whole body is total and can never fail the run.`);
+    lines.push(`  try {`);
+    lines.push(`    if (REPO_DIR === null) { log('ledger:append skipped — ledger row was not written because no args.repo was given'); return }`);
+    lines.push(`    // + 1 is THIS ledger writer, which is about to be invoked and not yet counted.`);
+    lines.push(`    const line = traceLedgerLine({ slug: LOOP_SLUG, runId: RUN_ID, planDigest: PLAN_DIGEST, agents: __agentCalls + 1, outcome: outcome, date: A.date })`);
+    lines.push(`    if (line === null) { log('ledger:append skipped — traceLedgerLine returned null'); return }`);
+    lines.push(`    const cmd = traceLedgerAppendCmd(REPO_DIR, line)`);
+    lines.push(`    if (cmd === null) { log('ledger:append skipped — traceLedgerAppendCmd returned null'); return }`);
+    lines.push(`    __agentCalls++`);
+    lines.push(`    const reply = await agent('Run EXACTLY this one shell command via your Bash tool and reply with only its stdout: ' + cmd, { label: 'ledger:append', phase: phaseName, effort: 'low' }) // loop-lint: infra-agent`);
+    lines.push(`    if (!/LEDGER-OK/.test(String(reply))) { log('ledger:append UNVERIFIED — ledger row write was not confirmed; run continues') }`);
+    lines.push(`  } catch (_le) { log('ledger:append failed as a SECONDARY event: ' + __errText(_le) + ' — run continues') }`);
+    lines.push(`}`);
   } else {
-    lines.push(`async function __traceFlushNow(phaseName) { /* trace.emit=false — no trace plane; fitness-suite verification is NOT claimable for this loop */ }`);
+    lines.push(`async function __traceFlushNow(phaseName, stepLabel) { /* trace.emit=false — no trace plane; fitness-suite verification is NOT claimable for this loop */ }`);
+    lines.push(`async function __ledgerAppend(phaseName, outcome) { /* trace off — no agents counted, no ledger row */ }`);
   }
   if (ckptOn) {
     lines.push(`// checkpoint wiring (blob-provided pure half; the read/write agents are infra) — the resume`);
@@ -738,6 +779,7 @@ function renderRuntime(plan: LoopPlan, planDig: string, execFp: string, blobs: L
     lines.push(`  if (CKPT_DIR === null) { log('checkpointing enabled but no traceDir given — running LIVE; nothing resumes, nothing persists (named, never silent)'); return }`);
     lines.push(`  try {`);
     lines.push(`    const cmd = checkpointReadCmd(TRACE_DIR)`);
+    lines.push(`    __agentCalls++`);
     lines.push(`    const out = await agent('Run EXACTLY this one shell command via your Bash tool and reply with ONLY its raw stdout: ' + cmd, { label: 'ckpt:read', phase: phaseName, effort: 'low' }) // loop-lint: infra-agent`);
     lines.push(`    const parsed = parseCheckpointRead(typeof out === 'string' ? out : '')`);
     lines.push(`    __ckptEntries = parsed.entries`);
@@ -760,6 +802,7 @@ function renderRuntime(plan: LoopPlan, planDig: string, execFp: string, blobs: L
     lines.push(`  if (line === null) { log('checkpoint: ' + stage + ' not persisted (null/oversize/unserializable — named, never silent)'); return }`);
     lines.push(`  try {`);
     lines.push(`    const cmd = checkpointAppendCmd(TRACE_DIR, line)`);
+    lines.push(`    __agentCalls++`);
     lines.push(`    await agent('Run EXACTLY this one shell command via your Bash tool and reply with only OK: ' + cmd, { label: 'ckpt:write:' + stage, phase: phaseName, effort: 'low' }) // loop-lint: infra-agent`);
     lines.push(`  } catch (_ce) { log('checkpoint append for ' + stage + ' threw: ' + __errText(_ce) + ' — run continues (the step outcome stands; the next run re-runs this step)') }`);
     lines.push(`}`);
@@ -776,15 +819,41 @@ function renderRuntime(plan: LoopPlan, planDig: string, execFp: string, blobs: L
     lines.push(`// SUCCESSFUL step (the step's own catch settled it as failed). The whole capture — pair`);
     lines.push(`// construction, serialization and write — now rides ONE catch, the same discipline as`);
     lines.push(`// __errText/__phaseFlush: a capture failure is a SECONDARY logged event, never an outcome.`);
-    lines.push(`async function __tpCapture(stage, phaseName, input, output, model) {`);
+    lines.push(`const __captureFailures = []`);
+    lines.push(`async function __tpCapture(stage, phaseName, input, output, model, resumed) {`);
     lines.push(`  if (TRACE_DIR === null) { return }`);
+    lines.push(`  let __captureMode = null`);
     lines.push(`  try {`);
-    lines.push(`    const pair = buildTrainingPair({ slug: RUN_ID, stage: stage, ts: null, input: input, output: output, evaluation: null, provenance: { model: model === null ? 'unknown' : model, role: stage } })`);
+    lines.push(`    // enabled is true because this entire wiring block is gated at render time by the subsystem opt-in.`);
+    lines.push(`    const recordCount = output === null || output === undefined ? 0 : 1`);
+    lines.push(`    const mode = decideCaptureMode({ enabled: true, resumed: resumed === true, recordCount: recordCount })`);
+    lines.push(`    __captureMode = mode`);
+    lines.push(`    if (mode === 'skip-disabled') { return }`);
+    lines.push(`    if (mode === 'skip-empty') { log('training-pair: ' + stage + ' not captured (null/undefined output — named, never silent)'); __captureFailures.push(captureFailureRecord(stage, mode, 'empty-output', null)); return }`);
+    lines.push(`    const pair = buildTrainingPair({ slug: RUN_ID, stage: stage, ts: null, input: input, output: output, evaluation: null, provenance: { model: model === null ? 'unknown' : model, role: stage }, captureMode: mode === 'backfill' ? 'backfill' : 'capture', resumed: resumed === true })`);
     lines.push(`    const line = serializeTrainingPair(pair)`);
-    lines.push(`    if (line === null) { log('training-pair: ' + stage + ' not captured (unserializable) — named, never silent'); return }`);
-    lines.push(`    const cmd = trainingPairAppendCmd(TRACE_DIR, RUN_ID, stage, line)`);
-    lines.push(`    await agent('Run EXACTLY this one shell command via your Bash tool and reply with only OK: ' + cmd, { label: 'tp:write:' + stage, phase: phaseName, effort: 'low' }) // loop-lint: infra-agent`);
-    lines.push(`  } catch (_ce) { log('training-pair capture for ' + stage + ' threw: ' + __errText(_ce) + ' — run continues (capture is never load-bearing)') }`);
+    lines.push(`    if (line === null) { log('training-pair: ' + stage + ' not captured (unserializable) — named, never silent'); __captureFailures.push(captureFailureRecord(stage, mode, 'unserializable', null)); return }`);
+    lines.push(`    if (mode === 'capture') {`);
+    lines.push(`      const cmd = trainingPairAppendCmd(TRACE_DIR, RUN_ID, stage, line)`);
+    lines.push(`      __agentCalls++`);
+    lines.push(`      await agent('Run EXACTLY this one shell command via your Bash tool and reply with only OK: ' + cmd, { label: 'tp:write:' + stage, phase: phaseName, effort: 'low' }) // loop-lint: infra-agent`);
+    lines.push(`      return`);
+    lines.push(`    }`);
+    lines.push(`    if (mode === 'backfill') {`);
+    lines.push(`      // Exclude pair.slug (RUN_ID) and pair.ts (null) from the mark key: normalized input/output`);
+    lines.push(`      // identify the pair across runIds, which is the cross-run at-most-once property.`);
+    lines.push(`      const markKey = fnv1a64(stage + '\\0' + pair.input + '\\0' + pair.output)`);
+    lines.push(`      const cmd = trainingPairBackfillCmd(TRACE_DIR, RUN_ID, stage, [line], markKey)`);
+    lines.push(`      __agentCalls++`);
+    lines.push(`      const readback = await agent('Run EXACTLY this one shell command via your Bash tool and reply with ONLY its raw stdout: ' + cmd, { label: 'tp:backfill:' + stage, phase: phaseName, effort: 'low' }) // loop-lint: infra-agent`);
+    lines.push(`      const status = typeof readback === 'string' ? readback.trim() : ''`);
+    lines.push(`      if (status === TP_BACKFILL_OK) { log('training-pair: ' + stage + ' backfilled from the checkpoint'); return }`);
+    lines.push(`      if (status === TP_BACKFILL_SKIP) { log('training-pair: ' + stage + ' pair file already existed; nothing written'); return }`);
+    lines.push(`      if (status === TP_BACKFILL_DUP) { log('training-pair: ' + stage + ' another run already captured this pair; nothing written'); return }`);
+    lines.push(`      log('training-pair: ' + stage + ' checkpoint backfill UNVERIFIED: ' + __errText(readback))`);
+    lines.push(`      __captureFailures.push(captureFailureRecord(stage, mode, 'backfill-unverified', readback))`);
+    lines.push(`    }`);
+    lines.push(`  } catch (_ce) { log('training-pair capture for ' + stage + ' threw: ' + __errText(_ce) + ' — run continues (capture is never load-bearing)'); __captureFailures.push(captureFailureRecord(stage, __captureMode, 'threw', __errText(_ce))) }`);
     lines.push(`}`);
   }
   if (plan.steps.some((s) => s.kind === 'gate')) {
@@ -966,14 +1035,17 @@ export function renderPlan(plan: LoopPlan): RenderResult {
 
   const header = `// ── LOOP-PLAN plan=loop-plan/1 digest=sha256:${digest} exec-fp=sha256:${execFp} generator=${LOOP_RENDER_GENERATOR} ──`;
   const runtime = renderRuntime(norm, digest, execFp, blobs);
+  const completedValue = `{ phase: 'COMPLETED', runId: RUN_ID, planDigest: PLAN_DIGEST, execFp: EXEC_FP }`;
 
   const ending = [
     G('epilogue'),
     `traceCloseIfOn()`,
     `function traceCloseIfOn() { ${norm.trace?.emit === true ? 'traceClose(__traceState)' : '/* trace off */'} }`,
+    `await __phaseFlush(${jsString(phaseOrder[phaseOrder.length - 1] ?? 'End')})`,
+    `await __ledgerAppend(${jsString(phaseOrder[phaseOrder.length - 1] ?? 'End')}, 'completed')`,
     `// the COMPLETED return rides the single exit too (round-5 B3): the epilogue flush happens inside`,
     `// __settleStep, so a flush rejection is a logged secondary event, never a replaced COMPLETED.`,
-    `return await __settleStep({ stepId: '__epilogue__', phase: ${jsString(phaseOrder[phaseOrder.length - 1] ?? 'End')}, outcome: 'terminal', value: { phase: 'COMPLETED', runId: RUN_ID, planDigest: PLAN_DIGEST, execFp: EXEC_FP } })`,
+    `return await __settleStep({ stepId: '__epilogue__', phase: ${jsString(phaseOrder[phaseOrder.length - 1] ?? 'End')}, outcome: 'terminal', value: ${completedValue} })`,
     GE('epilogue'),
   ].join('\n');
 
@@ -982,8 +1054,12 @@ export function renderPlan(plan: LoopPlan): RenderResult {
     header,
     ...blobChunks,
     runtime,
+    `try {`,
     ...stepChunks,
     ending,
+    norm.subsystems?.trainingPairs === true
+      ? `} catch (__runErr) { await __ledgerAppend(${jsString(phaseOrder[phaseOrder.length - 1] ?? 'End')}, 'failed'); if (__captureFailures.length > 0) { log('training-pair capture failures this run: ' + __captureFailures.length + ' — ' + __captureFailures.map(function (f) { return f.stage + ':' + f.reason }).join(', ')) } throw __runErr }`
+      : `} catch (__runErr) { await __ledgerAppend(${jsString(phaseOrder[phaseOrder.length - 1] ?? 'End')}, 'failed'); throw __runErr }`,
     '',
   ].join('\n\n');
 

package/src/loop-trace.ts

@@ -26,7 +26,7 @@
 import type { TraceProjection } from './loop-plan.js';
 
 /** Blob version stamp for the emitter half (read by scripts/gen-loop-blobs.mjs). */
-export const LOOP_TRACE_BLOB_VERSION = '1.0.0';
+export const LOOP_TRACE_BLOB_VERSION = '1.1.0';
 
 export const LOOP_TRACE_SCHEMA_VERSION = 1;
 
@@ -211,6 +211,83 @@ export function traceFlushCmd(state: TraceState, traceFileAbs: string): string |
   return 'mkdir -p ' + dir + ' && ' + printfs;
 }
 
+/**
+ * Build the feature-ADR live-panel telemetry leg. Totality comes from the caller's grouped splice:
+ * returning the bare command lets that splice preserve the trace flush's exit status while
+ * swallowing only the panel leg's failure. The `loop` producer marker stops a generated loop's
+ * high-frequency zero counters from displacing a live `/feature-adr` run's meaningful panel.
+ */
+export function traceFaRecordCmd(dzBin: unknown, slug: unknown, stepLabel: unknown, projectAbs: unknown): string | null {
+  if (typeof slug !== 'string' || slug === ''
+    || typeof stepLabel !== 'string' || stepLabel === ''
+    || typeof projectAbs !== 'string' || projectAbs === '') return null;
+  const bin = typeof dzBin === 'string' && dzBin !== '' ? dzBin : 'dz';
+  const cmd = traceShellQuote(bin) + ' statusline --fa-record --slug ' + traceShellQuote(slug)
+    + ' --step ' + traceShellQuote(stepLabel) + ' --kind loop --project ' + traceShellQuote(projectAbs);
+  return cmd + ' >/dev/null 2>&1';
+}
+
+/** Build one feature-ADR run-cost row without manufacturing wall-clock data in JavaScript. */
+export function traceLedgerLine(opts: {
+  slug: unknown;
+  runId?: unknown;
+  planDigest?: unknown;
+  /**
+   * `agents` is the TOTAL number of agent invocations this run made — model dispatches AND infra
+   * agents (trace flush, checkpoint read/write, training-pair write/backfill, landed-barrier probes,
+   * and this ledger writer itself) — counted at write time. It is NOT the trace's model-dispatch
+   * count; the ledger's `agents` column means `agent_count` from the Workflow completion
+   * notification, and this row must not silently redefine it.
+   */
+  agents?: unknown;
+  date?: unknown;
+  outcome?: unknown;
+}): string | null {
+  try {
+    if (typeof opts.slug !== 'string' || opts.slug === '') return null;
+    const agents = typeof opts.agents === 'number'
+      && Number.isFinite(opts.agents)
+      && Number.isInteger(opts.agents)
+      && opts.agents >= 0
+      ? opts.agents
+      : 0;
+    const date = typeof opts.date === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(opts.date) ? opts.date : null;
+    const outcome = typeof opts.outcome === 'string' && opts.outcome !== '' ? opts.outcome : 'unknown';
+    const line = JSON.stringify({
+      slug: opts.slug,
+      stage: 'loop-run',
+      tier: null,
+      tokens: null,
+      minutes: null,
+      agents,
+      coder: null,
+      grade: null,
+      date,
+      auto: true,
+      outcome,
+      runId: typeof opts.runId === 'string' ? opts.runId : null,
+      planDigest: typeof opts.planDigest === 'string' ? opts.planDigest : null,
+    });
+    return line.length <= 4000 ? line : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Build the single command that appends a run-cost row and confirms the write. */
+export function traceLedgerAppendCmd(repoAbs: unknown, line: unknown): string | null {
+  if (typeof repoAbs !== 'string' || repoAbs === '' || typeof line !== 'string' || line === '') return null;
+  const dir = traceShellQuote(repoAbs + '/.dz/feature-adr');
+  const file = traceShellQuote(repoAbs + '/.dz/feature-adr/run-cost-ledger.jsonl');
+  // The field token has a fixed position, and JSON-escaped scalar values (including slug,
+  // runId, and planDigest) cannot introduce the raw `"date":null` token targeted by sed.
+  return 'mkdir -p ' + dir
+    + " && printf '%s' " + traceShellQuote(line)
+    + ' | sed "s/\\"date\\":null/\\"date\\":\\"$(date -u +%Y-%m-%d)\\"/" >> ' + file
+    + " && printf '\\n' >> " + file
+    + ' && echo LEDGER-OK';
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // READER HALF — parseTrace / runInvariants / assembleTimeline / renderTimelineHtml.
 // Pure over strings; the CLI does the fs.