@dzhechkov/harness-core 0.4.1 → 0.4.2

package/src/feature-adr-checkpoints.ts

@@ -26,7 +26,7 @@
 
 /** Blob version stamp read by scripts/gen-loop-blobs.mjs (feature loop-designer, ADR-004) — the
  * ONLY loop-designer change to this canonical file; bump when any blob-exported semantic changes. */
-export const BLOB_VERSION = '1.0.0';
+export const BLOB_VERSION = '1.1.0';
 
 /** Stages the workflow checkpoints, in pipeline order. Cheap side-channel agents (usage probes,
  * fa-record, auto-cost selects) are never checkpointed; the opt-in Delivery gate re-runs by design
@@ -241,13 +241,59 @@ export function checkpointAppendCmd(fdirAbs: string, line: string): string {
 // dataset must honour the cross-model rule — QE pairs must come from a DIFFERENT
 // family than the coder's pairs; router/plan distill easily, code is hardest.
 //
-// Pure and deterministic like the checkpoint half: ts is PASSED IN (never Date.now()
+// Pure and deterministic like the checkpoint half: ts is PASSED IN (never read from a clock
 // — the workflow sandbox forbids Date, and tests must stay deterministic); the
 // workflow mirrors these functions inline and fills ts shell-side via sed.
 // ─────────────────────────────────────────────────────────────────────────────
 
+export type CaptureMode = 'capture' | 'backfill' | 'skip-disabled' | 'skip-empty';
+
+/** Decide whether this completion is captured. A resumed stage is backfilled rather than
+ * skipped: its input (stage template + args) and checkpointed output are both in scope at the
+ * capture site, so the pair is deterministically reconstructible. trainingPairBackfillCmd's
+ * persistent atomic mark makes that write at-most-once, so concurrent invocations and later
+ * runIds cannot double-append the same pair. */
+export function decideCaptureMode(opts: { enabled: boolean; resumed: boolean; recordCount: number }): CaptureMode {
+  if (!opts.enabled) return 'skip-disabled';
+  if (!Number.isInteger(opts.recordCount) || opts.recordCount <= 0) return 'skip-empty';
+  return opts.resumed ? 'backfill' : 'capture';
+}
+
+export type CaptureFailureReason = 'threw' | 'unserializable' | 'unverified' | 'backfill-unverified' | 'empty-output';
+
+export interface CaptureFailureRecord {
+  stage: string;
+  mode: CaptureMode | null;
+  reason: CaptureFailureReason;
+  detail: string | null;
+}
+
+/** Normalize capture failures for collection by the caller. This recorder must never throw:
+ * replacing the original capture failure with a reporting failure would hide the real cause. */
+export function captureFailureRecord(stage: unknown, mode: unknown, reason: unknown, detail: unknown): CaptureFailureRecord {
+  const normalizedStage = typeof stage === 'string' && stage.trim() !== '' ? stage : 'unknown';
+  const normalizedMode: CaptureMode | null =
+    mode === 'capture' || mode === 'backfill' || mode === 'skip-disabled' || mode === 'skip-empty'
+      ? mode
+      : null;
+  const normalizedReason: CaptureFailureReason =
+    reason === 'threw' || reason === 'unserializable' || reason === 'unverified' || reason === 'backfill-unverified' || reason === 'empty-output'
+      ? reason
+      : 'threw';
+  let normalizedDetail: string | null = null;
+  if (detail !== null && detail !== undefined) {
+    try {
+      const text = String(detail);
+      if (text !== '') normalizedDetail = text.length > 500 ? text.slice(0, 500) + '…' : text;
+    } catch {
+      normalizedDetail = null;
+    }
+  }
+  return { stage: normalizedStage, mode: normalizedMode, reason: normalizedReason, detail: normalizedDetail };
+}
+
 /** Training-pair record format version. Bump on any field-shape change. */
-export const TRAINPAIR_SCHEMA_VERSION = 'fa-trainpair-1';
+export const TRAINPAIR_SCHEMA_VERSION = 'fa-trainpair-2';
 
 /** Oversize guard cap over input+output combined (same posture as
  * CHECKPOINT_MAX_RESULT_CHARS, sized for full stage prompts): an over-cap pair is
@@ -299,12 +345,15 @@ export interface TrainingPair {
   schema: string;
   slug: string;
   stage: string;
+  /** ts is the CAPTURE time. On a record with captureMode: 'backfill' that is the RECONSTRUCTION time, NOT the stage's observation time — the original stage's timing lives in that run's .fa-state checkpoint. */
   ts: number | string | null;
   input: string;
   output: string;
   evaluation: TrainingPairEvaluation;
   provenance: TrainingPairProvenance;
   truncated: TrainingPairTruncation | null;
+  captureMode: 'capture' | 'backfill';
+  resumed: boolean;
 }
 
 /** Per-stage JSONL path, relative to the repo root. ONE file per stage. */
@@ -315,7 +364,7 @@ export function trainingPairPath(slug: string, stage: string): string {
 /** README dropped once into the capture dir. The caveat is documented ON DISK because the
  * directory is deliberately not gitignored (explicit owner decision, 2026-08). */
 export const TRAINPAIR_PRIVACY_NOTE =
-  'feature-adr TRAINING PAIRS (backlog 70e0f083): per-stage SFT records - STAGE INPUT (full prompt/context) -> STAGE OUTPUT (artifact/result) -> EVALUATION (QE grade + injected lessons) with model+family provenance; one JSONL file per stage per slug. PRIVACY: pairs may contain TARGET-REPO CODE and full prompts. This directory is NOT gitignored yet by explicit owner decision - review contents before sharing or publishing anything that embeds it.';
+  "feature-adr TRAINING PAIRS (backlog 70e0f083): per-stage SFT records - STAGE INPUT (full prompt/context) -> STAGE OUTPUT (artifact/result) -> EVALUATION (QE grade + injected lessons) with model+family provenance; one JSONL file per stage per slug. PRIVACY: pairs may contain TARGET-REPO CODE and full prompts. This directory is NOT gitignored yet by explicit owner decision - review contents before sharing or publishing anything that embeds it. ts is the CAPTURE time. On a record with captureMode: 'backfill' that is the RECONSTRUCTION time, NOT the stage's observation time — the original stage's timing lives in that run's .fa-state checkpoint.";
 
 /** Coerce a stage input/output to text: strings pass through; objects serialize to JSON;
  * an unserializable value degrades to String(v) — buildTrainingPair NEVER throws (capture
@@ -346,6 +395,8 @@ export function buildTrainingPair(opts: {
   output: unknown;
   evaluation?: Partial<TrainingPairEvaluation> | null;
   provenance?: Partial<TrainingPairProvenance> | null;
+  captureMode?: unknown;
+  resumed?: unknown;
 }): TrainingPair {
   let input = coerceText(opts.input);
   let output = coerceText(opts.output);
@@ -383,6 +434,8 @@ export function buildTrainingPair(opts: {
       minutes: typeof pv.minutes === 'number' && Number.isFinite(pv.minutes) ? pv.minutes : null,
     },
     truncated,
+    captureMode: opts.captureMode === 'backfill' ? 'backfill' : 'capture',
+    resumed: opts.resumed === true,
   };
 }
 
@@ -410,3 +463,49 @@ export function trainingPairAppendCmd(repoAbs: string, slug: string, stage: stri
     " && printf '%s\\n' " + shellQuote(line) + ' >> ' + shellQuote(fileAbs)
   );
 }
+
+/** Readback sentinels for the caller to distinguish an at-most-once write from an existing pair. */
+export const TP_BACKFILL_OK = 'TP-BACKFILL-OK';
+export const TP_BACKFILL_SKIP = 'TP-BACKFILL-SKIP';
+export const TP_BACKFILL_DUP = 'TP-BACKFILL-DUP';
+
+/** Build the deterministic resume-backfill command. The persistent mkdir mark is the atomic
+ * at-most-once primitive; the inner file-absence guard also protects pair files created before
+ * marks existed. The mark is RELEASED when — and only when — the append fails, so a failed backfill
+ * stays retryable. The `[ -f ]` path keeps the mark because the pair genuinely exists.
+ * KNOWN RESIDUAL: a process killed (SIGKILL, sandbox timeout) between the `mkdir` claim and the end
+ * of the append still leaves a poisoned mark. That window is strictly narrower than "any append
+ * failure" and is the same externally-killed class this feature already names for the ledger row.
+ * `TP_BACKFILL_SKIP` means "the per-stage pair file already existed"; `TP_BACKFILL_DUP` means
+ * "another run already owns this content". The two strings are deliberately NON-PREFIXING because
+ * the two producers parse the readback differently — the generated loop compares `===` after
+ * `trim`, while the `feature-adr.js` twin tests an UNANCHORED regex; a prefixed name would be `DUP`
+ * to one parser and `SKIP` to the other from the same bytes. The default `markKey` is per-CONTENT
+ * only; a caller whose line embeds a per-run identifier must pass a run-independent `markKey`.
+ * Marks are deliberately never pruned. */
+export function trainingPairBackfillCmd(repoAbs: string, slug: string, stage: string, lines: readonly string[], markKey?: string): string | null {
+  if (typeof repoAbs !== 'string' || repoAbs === '') return null;
+  if (typeof slug !== 'string' || slug === '') return null;
+  if (typeof stage !== 'string' || stage === '') return null;
+  if (!Array.isArray(lines) || lines.length === 0 || !lines.every(line => typeof line === 'string' && line !== '')) return null;
+
+  const dirAbs = repoAbs + '/.dz/fa-training/' + slug;
+  const readmeAbs = repoAbs + '/.dz/fa-training/README.md';
+  const fileAbs = dirAbs + '/' + stage + '.jsonl';
+  const markDir = repoAbs + '/.dz/fa-training/.backfill-marks';
+  const markStage = stage.replace(/\.\./g, '_').replace(/\//g, '_');
+  const resolvedMarkKey = markKey === undefined ? fnv1a64(stage + '\0' + lines.join('\n')) : markKey;
+  const markPath = markDir + '/' + markStage + '-' + resolvedMarkKey;
+  const appends = lines
+    .map(line => "printf '%s\\n' " + shellQuote(line) + ' >> ' + shellQuote(fileAbs))
+    .join(' && ');
+  return (
+    'mkdir -p ' + shellQuote(dirAbs) +
+    ' && { [ -f ' + shellQuote(readmeAbs) + ' ] || printf \'%s\\n\' ' + shellQuote(TRAINPAIR_PRIVACY_NOTE) + ' > ' + shellQuote(readmeAbs) + '; }' +
+    ' && mkdir -p ' + shellQuote(markDir) +
+    ' && if mkdir ' + shellQuote(markPath) + ' 2>/dev/null; then ' +
+    'if [ -f ' + shellQuote(fileAbs) + ' ]; then echo ' + shellQuote(TP_BACKFILL_SKIP) +
+    '; else { ' + appends + ' && echo ' + shellQuote(TP_BACKFILL_OK) + '; } || { rmdir ' + shellQuote(markPath) + ' 2>/dev/null; false; }; fi' +
+    '; else echo ' + shellQuote(TP_BACKFILL_DUP) + '; fi'
+  );
+}

package/src/index.ts

@@ -127,7 +127,7 @@ export type {
   TeachGuardResult,
 } from './vector-tier.js';
 export { runSetup, generateHooksConfig, generateAgentdbWriter, writerVersionOf, AGENTDB_WRITER_VERSION } from './setup.js';
-export { statuslineData, readFeatureAdrState, writeFeatureAdrState, featureAdrStatePath } from './statusline.js';
+export { statuslineData, readFeatureAdrState, writeFeatureAdrState, featureAdrStateDir, featureAdrStatePath } from './statusline.js';
 export type { StatuslineData, FeatureAdrState, WriteFeatureAdrStateInput } from './statusline.js';
 export { indexPatternsToAgentdb, resolveAgentdbPath, searchAgentdbPatterns, listAgentdbDzIds, resolveAgentdbEmbedder, cosineSimilarity, importVectorsToAgentdb, reindexAgentdbRows, bumpAgentdbUses, clearAgentdbQuarantine, deleteAgentdbByDzIds, readAgentdbRowsByTaskType, DZ_OWNED_TASK_TYPES } from './agentdb-index.js';
 export type { AgentdbSearchHit, AgentdbSearchResult, AgentdbImportRow } from './agentdb-index.js';

package/src/loop-blobs.generated.ts

@@ -41,7 +41,7 @@ export const BLOB_COVERAGE_MANIFEST: { coveredWorkflows: string[] } = {
 export const BLOBS: Record<string, LoopBlob> = {
   "checkpoints": {
     name: "checkpoints",
-    version: "1.0.0",
+    version: "1.1.0",
     contentHash: "aa730483f52a9f6263751138d4514fe9a6a3f4f191897c86d1e035f3da890574",
     sourcePath: "packages/@dzhechkov/harness-core/src/feature-adr-checkpoints.ts",
     requires: [],
@@ -50,12 +50,12 @@ export const BLOBS: Record<string, LoopBlob> = {
   },
   "training-pairs": {
     name: "training-pairs",
-    version: "1.0.0",
-    contentHash: "a28f704ff78227e8254ed075cc7c51fa0c89bcac9fc191ee03ecd6ee1584fc58",
+    version: "1.1.0",
+    contentHash: "740b733d3d995e7031590f1707b442d0f0f9d7d585ada6f37bbf08c5db3351e9",
     sourcePath: "packages/@dzhechkov/harness-core/src/feature-adr-checkpoints.ts",
     requires: ["checkpoints"],
-    exports: ["TRAINPAIR_SCHEMA_VERSION","TRAINPAIR_MAX_IO_CHARS","trainingPairFamily","trainingPairPath","TRAINPAIR_PRIVACY_NOTE","buildTrainingPair","serializeTrainingPair","trainingPairAppendCmd"],
-    code: "const TRAINPAIR_SCHEMA_VERSION = 'fa-trainpair-1';\nconst TRAINPAIR_MAX_IO_CHARS = 48000;\nfunction trainingPairFamily(spec) {\n    return /codex|gpt|openai/i.test(String(spec ?? '')) ? 'codex' : 'claude';\n}\nfunction trainingPairPath(slug, stage) {\n    return '.dz/fa-training/' + slug + '/' + stage + '.jsonl';\n}\nconst TRAINPAIR_PRIVACY_NOTE = 'feature-adr TRAINING PAIRS (backlog 70e0f083): per-stage SFT records - STAGE INPUT (full prompt/context) -> STAGE OUTPUT (artifact/result) -> EVALUATION (QE grade + injected lessons) with model+family provenance; one JSONL file per stage per slug. PRIVACY: pairs may contain TARGET-REPO CODE and full prompts. This directory is NOT gitignored yet by explicit owner decision - review contents before sharing or publishing anything that embeds it.';\nfunction coerceText(v) {\n    if (typeof v === 'string')\n        return v;\n    if (v === null || v === undefined)\n        return '';\n    try {\n        const s = JSON.stringify(v);\n        return typeof s === 'string' ? s : String(v);\n    }\n    catch {\n        return String(v);\n    }\n}\nfunction buildTrainingPair(opts) {\n    let input = coerceText(opts.input);\n    let output = coerceText(opts.output);\n    let truncated = null;\n    if (input.length + output.length > TRAINPAIR_MAX_IO_CHARS) {\n        truncated = { inputChars: input.length, outputChars: output.length, inputHash: fnv1a64(input), outputHash: fnv1a64(output) };\n        const half = Math.floor(TRAINPAIR_MAX_IO_CHARS / 2);\n        let inKeep = input.length;\n        let outKeep = output.length;\n        if (outKeep <= half)\n            inKeep = TRAINPAIR_MAX_IO_CHARS - outKeep;\n        else if (inKeep <= half)\n            outKeep = TRAINPAIR_MAX_IO_CHARS - inKeep;\n        else {\n            inKeep = half;\n            outKeep = TRAINPAIR_MAX_IO_CHARS - half;\n        }\n        if (inKeep < input.length)\n            input = input.slice(0, inKeep) + '\\n…[TRUNCATED ' + (truncated.inputChars - inKeep) + ' chars — full-text fnv1a64=' + truncated.inputHash + ']';\n        if (outKeep < output.length)\n            output = output.slice(0, outKeep) + '\\n…[TRUNCATED ' + (truncated.outputChars - outKeep) + ' chars — full-text fnv1a64=' + truncated.outputHash + ']';\n    }\n    const ev = opts.evaluation || {};\n    const pv = opts.provenance || {};\n    return {\n        schema: TRAINPAIR_SCHEMA_VERSION,\n        slug: opts.slug,\n        stage: opts.stage,\n        ts: opts.ts === undefined ? null : opts.ts,\n        input,\n        output,\n        evaluation: {\n            grade: typeof ev.grade === 'string' && ev.grade.trim() !== '' ? ev.grade : null,\n            gradedBy: typeof ev.gradedBy === 'string' && ev.gradedBy !== '' ? ev.gradedBy : null,\n            lessonsInjected: Array.isArray(ev.lessonsInjected) ? ev.lessonsInjected.filter((s) => typeof s === 'string' && s !== '') : [],\n        },\n        provenance: {\n            model: typeof pv.model === 'string' && pv.model !== '' ? pv.model : 'unknown',\n            family: pv.family === 'claude' || pv.family === 'codex' ? pv.family : trainingPairFamily(pv.model),\n            role: typeof pv.role === 'string' && pv.role !== '' ? pv.role : 'unknown',\n            tokens: typeof pv.tokens === 'number' && Number.isFinite(pv.tokens) ? pv.tokens : null,\n            minutes: typeof pv.minutes === 'number' && Number.isFinite(pv.minutes) ? pv.minutes : null,\n        },\n        truncated,\n    };\n}\nfunction serializeTrainingPair(pair) {\n    try {\n        const line = JSON.stringify(pair);\n        return typeof line === 'string' ? line : null;\n    }\n    catch {\n        return null;\n    }\n}\nfunction trainingPairAppendCmd(repoAbs, slug, stage, line) {\n    const dirAbs = repoAbs + '/.dz/fa-training/' + slug;\n    const readmeAbs = repoAbs + '/.dz/fa-training/README.md';\n    const fileAbs = dirAbs + '/' + stage + '.jsonl';\n    return ('mkdir -p ' + shellQuote(dirAbs) +\n        ' && { [ -f ' + shellQuote(readmeAbs) + ' ] || printf \\'%s\\\\n\\' ' + shellQuote(TRAINPAIR_PRIVACY_NOTE) + ' > ' + shellQuote(readmeAbs) + '; }' +\n        \" && printf '%s\\\\n' \" + shellQuote(line) + ' >> ' + shellQuote(fileAbs));\n}",
+    exports: ["TRAINPAIR_SCHEMA_VERSION","TRAINPAIR_MAX_IO_CHARS","trainingPairFamily","trainingPairPath","TRAINPAIR_PRIVACY_NOTE","buildTrainingPair","serializeTrainingPair","trainingPairAppendCmd","decideCaptureMode","captureFailureRecord","trainingPairBackfillCmd","TP_BACKFILL_OK","TP_BACKFILL_SKIP"],
+    code: "function decideCaptureMode(opts) {\n    if (!opts.enabled)\n        return 'skip-disabled';\n    if (!Number.isInteger(opts.recordCount) || opts.recordCount <= 0)\n        return 'skip-empty';\n    return opts.resumed ? 'backfill' : 'capture';\n}\nfunction captureFailureRecord(stage, mode, reason, detail) {\n    const normalizedStage = typeof stage === 'string' && stage.trim() !== '' ? stage : 'unknown';\n    const normalizedMode = mode === 'capture' || mode === 'backfill' || mode === 'skip-disabled' || mode === 'skip-empty'\n        ? mode\n        : null;\n    const normalizedReason = reason === 'threw' || reason === 'unserializable' || reason === 'unverified' || reason === 'backfill-unverified' || reason === 'empty-output'\n        ? reason\n        : 'threw';\n    let normalizedDetail = null;\n    if (detail !== null && detail !== undefined) {\n        try {\n            const text = String(detail);\n            if (text !== '')\n                normalizedDetail = text.length > 500 ? text.slice(0, 500) + '…' : text;\n        }\n        catch {\n            normalizedDetail = null;\n        }\n    }\n    return { stage: normalizedStage, mode: normalizedMode, reason: normalizedReason, detail: normalizedDetail };\n}\nconst TRAINPAIR_SCHEMA_VERSION = 'fa-trainpair-2';\nconst TRAINPAIR_MAX_IO_CHARS = 48000;\nfunction trainingPairFamily(spec) {\n    return /codex|gpt|openai/i.test(String(spec ?? '')) ? 'codex' : 'claude';\n}\nfunction trainingPairPath(slug, stage) {\n    return '.dz/fa-training/' + slug + '/' + stage + '.jsonl';\n}\nconst TRAINPAIR_PRIVACY_NOTE = \"feature-adr TRAINING PAIRS (backlog 70e0f083): per-stage SFT records - STAGE INPUT (full prompt/context) -> STAGE OUTPUT (artifact/result) -> EVALUATION (QE grade + injected lessons) with model+family provenance; one JSONL file per stage per slug. PRIVACY: pairs may contain TARGET-REPO CODE and full prompts. This directory is NOT gitignored yet by explicit owner decision - review contents before sharing or publishing anything that embeds it. ts is the CAPTURE time. On a record with captureMode: 'backfill' that is the RECONSTRUCTION time, NOT the stage's observation time — the original stage's timing lives in that run's .fa-state checkpoint.\";\nfunction coerceText(v) {\n    if (typeof v === 'string')\n        return v;\n    if (v === null || v === undefined)\n        return '';\n    try {\n        const s = JSON.stringify(v);\n        return typeof s === 'string' ? s : String(v);\n    }\n    catch {\n        return String(v);\n    }\n}\nfunction buildTrainingPair(opts) {\n    let input = coerceText(opts.input);\n    let output = coerceText(opts.output);\n    let truncated = null;\n    if (input.length + output.length > TRAINPAIR_MAX_IO_CHARS) {\n        truncated = { inputChars: input.length, outputChars: output.length, inputHash: fnv1a64(input), outputHash: fnv1a64(output) };\n        const half = Math.floor(TRAINPAIR_MAX_IO_CHARS / 2);\n        let inKeep = input.length;\n        let outKeep = output.length;\n        if (outKeep <= half)\n            inKeep = TRAINPAIR_MAX_IO_CHARS - outKeep;\n        else if (inKeep <= half)\n            outKeep = TRAINPAIR_MAX_IO_CHARS - inKeep;\n        else {\n            inKeep = half;\n            outKeep = TRAINPAIR_MAX_IO_CHARS - half;\n        }\n        if (inKeep < input.length)\n            input = input.slice(0, inKeep) + '\\n…[TRUNCATED ' + (truncated.inputChars - inKeep) + ' chars — full-text fnv1a64=' + truncated.inputHash + ']';\n        if (outKeep < output.length)\n            output = output.slice(0, outKeep) + '\\n…[TRUNCATED ' + (truncated.outputChars - outKeep) + ' chars — full-text fnv1a64=' + truncated.outputHash + ']';\n    }\n    const ev = opts.evaluation || {};\n    const pv = opts.provenance || {};\n    return {\n        schema: TRAINPAIR_SCHEMA_VERSION,\n        slug: opts.slug,\n        stage: opts.stage,\n        ts: opts.ts === undefined ? null : opts.ts,\n        input,\n        output,\n        evaluation: {\n            grade: typeof ev.grade === 'string' && ev.grade.trim() !== '' ? ev.grade : null,\n            gradedBy: typeof ev.gradedBy === 'string' && ev.gradedBy !== '' ? ev.gradedBy : null,\n            lessonsInjected: Array.isArray(ev.lessonsInjected) ? ev.lessonsInjected.filter((s) => typeof s === 'string' && s !== '') : [],\n        },\n        provenance: {\n            model: typeof pv.model === 'string' && pv.model !== '' ? pv.model : 'unknown',\n            family: pv.family === 'claude' || pv.family === 'codex' ? pv.family : trainingPairFamily(pv.model),\n            role: typeof pv.role === 'string' && pv.role !== '' ? pv.role : 'unknown',\n            tokens: typeof pv.tokens === 'number' && Number.isFinite(pv.tokens) ? pv.tokens : null,\n            minutes: typeof pv.minutes === 'number' && Number.isFinite(pv.minutes) ? pv.minutes : null,\n        },\n        truncated,\n        captureMode: opts.captureMode === 'backfill' ? 'backfill' : 'capture',\n        resumed: opts.resumed === true,\n    };\n}\nfunction serializeTrainingPair(pair) {\n    try {\n        const line = JSON.stringify(pair);\n        return typeof line === 'string' ? line : null;\n    }\n    catch {\n        return null;\n    }\n}\nfunction trainingPairAppendCmd(repoAbs, slug, stage, line) {\n    const dirAbs = repoAbs + '/.dz/fa-training/' + slug;\n    const readmeAbs = repoAbs + '/.dz/fa-training/README.md';\n    const fileAbs = dirAbs + '/' + stage + '.jsonl';\n    return ('mkdir -p ' + shellQuote(dirAbs) +\n        ' && { [ -f ' + shellQuote(readmeAbs) + ' ] || printf \\'%s\\\\n\\' ' + shellQuote(TRAINPAIR_PRIVACY_NOTE) + ' > ' + shellQuote(readmeAbs) + '; }' +\n        \" && printf '%s\\\\n' \" + shellQuote(line) + ' >> ' + shellQuote(fileAbs));\n}\nconst TP_BACKFILL_OK = 'TP-BACKFILL-OK';\nconst TP_BACKFILL_SKIP = 'TP-BACKFILL-SKIP';\nconst TP_BACKFILL_DUP = 'TP-BACKFILL-DUP';\nfunction trainingPairBackfillCmd(repoAbs, slug, stage, lines, markKey) {\n    if (typeof repoAbs !== 'string' || repoAbs === '')\n        return null;\n    if (typeof slug !== 'string' || slug === '')\n        return null;\n    if (typeof stage !== 'string' || stage === '')\n        return null;\n    if (!Array.isArray(lines) || lines.length === 0 || !lines.every(line => typeof line === 'string' && line !== ''))\n        return null;\n    const dirAbs = repoAbs + '/.dz/fa-training/' + slug;\n    const readmeAbs = repoAbs + '/.dz/fa-training/README.md';\n    const fileAbs = dirAbs + '/' + stage + '.jsonl';\n    const markDir = repoAbs + '/.dz/fa-training/.backfill-marks';\n    const markStage = stage.replace(/\\.\\./g, '_').replace(/\\//g, '_');\n    const resolvedMarkKey = markKey === undefined ? fnv1a64(stage + '\\0' + lines.join('\\n')) : markKey;\n    const markPath = markDir + '/' + markStage + '-' + resolvedMarkKey;\n    const appends = lines\n        .map(line => \"printf '%s\\\\n' \" + shellQuote(line) + ' >> ' + shellQuote(fileAbs))\n        .join(' && ');\n    return ('mkdir -p ' + shellQuote(dirAbs) +\n        ' && { [ -f ' + shellQuote(readmeAbs) + ' ] || printf \\'%s\\\\n\\' ' + shellQuote(TRAINPAIR_PRIVACY_NOTE) + ' > ' + shellQuote(readmeAbs) + '; }' +\n        ' && mkdir -p ' + shellQuote(markDir) +\n        ' && if mkdir ' + shellQuote(markPath) + ' 2>/dev/null; then ' +\n        'if [ -f ' + shellQuote(fileAbs) + ' ]; then echo ' + shellQuote(TP_BACKFILL_SKIP) +\n        '; else { ' + appends + ' && echo ' + shellQuote(TP_BACKFILL_OK) + '; } || { rmdir ' + shellQuote(markPath) + ' 2>/dev/null; false; }; fi' +\n        '; else echo ' + shellQuote(TP_BACKFILL_DUP) + '; fi');\n}",
   },
   "model-resolver": {
     name: "model-resolver",
@@ -95,12 +95,12 @@ export const BLOBS: Record<string, LoopBlob> = {
   },
   "trace": {
     name: "trace",
-    version: "1.0.0",
-    contentHash: "085ac8d78190d29a6d5068019be40b93ebbe8f8ec8590f2954a1dfa4da5c6803",
+    version: "1.1.0",
+    contentHash: "fc59098bb0deb747c4c1c9a6ba843df70edfe0dc5ef8370c0f7192afc7657890",
     sourcePath: "packages/@dzhechkov/harness-core/src/loop-trace.ts",
     requires: [],
-    exports: ["LOOP_TRACE_SCHEMA_VERSION","TRACE_RUNID_RE","TRACE_KEY_RE","traceShellQuote","traceValidateEvent","traceInit","traceOnDispatch","traceOnSettle","traceClose","traceFlushCmd"],
-    code: "const LOOP_TRACE_SCHEMA_VERSION = 1;\nconst TRACE_RUNID_RE = /^[a-z0-9-]{1,40}$/;\nconst TRACE_KEY_RE = /^[a-z0-9_.:-]{1,64}$/i;\nfunction traceShellQuote(s) {\n    return \"'\" + String(s).replace(/'/g, \"'\\\\''\") + \"'\";\n}\nfunction traceValidateEvent(e) {\n    if (typeof e !== 'object' || e === null || Array.isArray(e))\n        return 'event must be an object';\n    const ev = e;\n    if (ev['v'] !== 1)\n        return 'v must be 1';\n    if (typeof ev['runId'] !== 'string' || !TRACE_RUNID_RE.test(ev['runId']))\n        return 'runId fails its VO regex';\n    if (typeof ev['seq'] !== 'number' || !Number.isInteger(ev['seq']) || ev['seq'] < 1)\n        return 'seq must be a positive integer';\n    const kind = ev['event'];\n    if (kind === 'dispatched') {\n        if (typeof ev['invocationId'] !== 'string' || ev['invocationId'] === '')\n            return 'invocationId required';\n        if (typeof ev['stepId'] !== 'string' || !TRACE_KEY_RE.test(ev['stepId']))\n            return 'stepId fails its VO regex';\n        if (ev['itemKey'] !== null && (typeof ev['itemKey'] !== 'string' || !TRACE_KEY_RE.test(ev['itemKey'])))\n            return 'itemKey fails its VO regex';\n        if (typeof ev['attempt'] !== 'number' || ev['attempt'] < 1)\n            return 'attempt must be >= 1';\n        if (typeof ev['phase'] !== 'string' || ev['phase'] === '')\n            return 'phase required';\n        if (!Array.isArray(ev['causedBy']) || ev['causedBy'].some((n) => typeof n !== 'number'))\n            return 'causedBy must be a number array';\n        return null;\n    }\n    if (kind === 'settled') {\n        if (typeof ev['invocationId'] !== 'string' || ev['invocationId'] === '')\n            return 'invocationId required';\n        if (ev['outcome'] !== 'ok' && ev['outcome'] !== 'null' && ev['outcome'] !== 'error')\n            return 'outcome must be ok|null|error';\n        return null;\n    }\n    if (kind === 'run.opened') {\n        if (typeof ev['planDigest'] !== 'string' || typeof ev['execFp'] !== 'string')\n            return 'run.opened needs planDigest + execFp';\n        return null;\n    }\n    if (kind === 'run.closed') {\n        const c = ev['counts'];\n        if (typeof c !== 'object' || c === null)\n            return 'run.closed needs counts';\n        return null;\n    }\n    return 'unknown event kind';\n}\nfunction traceInit(runId, planDigest, execFp) {\n    if (!TRACE_RUNID_RE.test(runId))\n        throw new Error('loop-trace: runId fails ' + String(TRACE_RUNID_RE));\n    const state = { runId, seq: 0, dispatched: 0, settled: 0, buffer: [] };\n    const opened = { v: 1, runId, seq: ++state.seq, event: 'run.opened', planDigest, execFp };\n    traceBuffer(state, opened);\n    return state;\n}\nfunction traceBuffer(state, e) {\n    const err = traceValidateEvent(e);\n    if (err !== null)\n        throw new Error('loop-trace: refusing non-conforming event (' + err + ') — the authoritative ordering source is never repaired later');\n    state.buffer.push(JSON.stringify(e));\n}\nfunction traceOnDispatch(state, e) {\n    const seq = ++state.seq;\n    state.dispatched++;\n    traceBuffer(state, {\n        v: 1,\n        runId: state.runId,\n        seq,\n        event: 'dispatched',\n        invocationId: e.invocationId,\n        stepId: e.stepId,\n        itemKey: e.itemKey,\n        attempt: e.attempt,\n        phase: e.phase,\n        model: e.model,\n        causedBy: e.causedBy,\n    });\n    return seq;\n}\nfunction traceOnSettle(state, e) {\n    const seq = ++state.seq;\n    state.settled++;\n    traceBuffer(state, { v: 1, runId: state.runId, seq, event: 'settled', invocationId: e.invocationId, outcome: e.outcome });\n    return seq;\n}\nfunction traceClose(state) {\n    const closed = {\n        v: 1,\n        runId: state.runId,\n        seq: ++state.seq,\n        event: 'run.closed',\n        counts: { dispatched: state.dispatched, settled: state.settled },\n    };\n    traceBuffer(state, closed);\n}\nfunction traceFlushCmd(state, traceFileAbs) {\n    if (state.buffer.length === 0)\n        return null;\n    const lines = state.buffer.splice(0, state.buffer.length);\n    const file = traceShellQuote(traceFileAbs);\n    const dir = traceShellQuote(traceFileAbs.replace(/\\/[^/]*$/, ''));\n    const printfs = lines\n        .map((l) => \"printf '%s\\\\n' \" + traceShellQuote(l) + ' | sed \"s/}$/,\\\\\"wallTime\\\\\":\\\\\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\\\\\"}/\" >> ' + file)\n        .join(' && ');\n    return 'mkdir -p ' + dir + ' && ' + printfs;\n}",
+    exports: ["LOOP_TRACE_SCHEMA_VERSION","TRACE_RUNID_RE","TRACE_KEY_RE","traceShellQuote","traceValidateEvent","traceInit","traceOnDispatch","traceOnSettle","traceClose","traceFlushCmd","traceFaRecordCmd","traceLedgerLine","traceLedgerAppendCmd"],
+    code: "const LOOP_TRACE_SCHEMA_VERSION = 1;\nconst TRACE_RUNID_RE = /^[a-z0-9-]{1,40}$/;\nconst TRACE_KEY_RE = /^[a-z0-9_.:-]{1,64}$/i;\nfunction traceShellQuote(s) {\n    return \"'\" + String(s).replace(/'/g, \"'\\\\''\") + \"'\";\n}\nfunction traceValidateEvent(e) {\n    if (typeof e !== 'object' || e === null || Array.isArray(e))\n        return 'event must be an object';\n    const ev = e;\n    if (ev['v'] !== 1)\n        return 'v must be 1';\n    if (typeof ev['runId'] !== 'string' || !TRACE_RUNID_RE.test(ev['runId']))\n        return 'runId fails its VO regex';\n    if (typeof ev['seq'] !== 'number' || !Number.isInteger(ev['seq']) || ev['seq'] < 1)\n        return 'seq must be a positive integer';\n    const kind = ev['event'];\n    if (kind === 'dispatched') {\n        if (typeof ev['invocationId'] !== 'string' || ev['invocationId'] === '')\n            return 'invocationId required';\n        if (typeof ev['stepId'] !== 'string' || !TRACE_KEY_RE.test(ev['stepId']))\n            return 'stepId fails its VO regex';\n        if (ev['itemKey'] !== null && (typeof ev['itemKey'] !== 'string' || !TRACE_KEY_RE.test(ev['itemKey'])))\n            return 'itemKey fails its VO regex';\n        if (typeof ev['attempt'] !== 'number' || ev['attempt'] < 1)\n            return 'attempt must be >= 1';\n        if (typeof ev['phase'] !== 'string' || ev['phase'] === '')\n            return 'phase required';\n        if (!Array.isArray(ev['causedBy']) || ev['causedBy'].some((n) => typeof n !== 'number'))\n            return 'causedBy must be a number array';\n        return null;\n    }\n    if (kind === 'settled') {\n        if (typeof ev['invocationId'] !== 'string' || ev['invocationId'] === '')\n            return 'invocationId required';\n        if (ev['outcome'] !== 'ok' && ev['outcome'] !== 'null' && ev['outcome'] !== 'error')\n            return 'outcome must be ok|null|error';\n        return null;\n    }\n    if (kind === 'run.opened') {\n        if (typeof ev['planDigest'] !== 'string' || typeof ev['execFp'] !== 'string')\n            return 'run.opened needs planDigest + execFp';\n        return null;\n    }\n    if (kind === 'run.closed') {\n        const c = ev['counts'];\n        if (typeof c !== 'object' || c === null)\n            return 'run.closed needs counts';\n        return null;\n    }\n    return 'unknown event kind';\n}\nfunction traceInit(runId, planDigest, execFp) {\n    if (!TRACE_RUNID_RE.test(runId))\n        throw new Error('loop-trace: runId fails ' + String(TRACE_RUNID_RE));\n    const state = { runId, seq: 0, dispatched: 0, settled: 0, buffer: [] };\n    const opened = { v: 1, runId, seq: ++state.seq, event: 'run.opened', planDigest, execFp };\n    traceBuffer(state, opened);\n    return state;\n}\nfunction traceBuffer(state, e) {\n    const err = traceValidateEvent(e);\n    if (err !== null)\n        throw new Error('loop-trace: refusing non-conforming event (' + err + ') — the authoritative ordering source is never repaired later');\n    state.buffer.push(JSON.stringify(e));\n}\nfunction traceOnDispatch(state, e) {\n    const seq = ++state.seq;\n    state.dispatched++;\n    traceBuffer(state, {\n        v: 1,\n        runId: state.runId,\n        seq,\n        event: 'dispatched',\n        invocationId: e.invocationId,\n        stepId: e.stepId,\n        itemKey: e.itemKey,\n        attempt: e.attempt,\n        phase: e.phase,\n        model: e.model,\n        causedBy: e.causedBy,\n    });\n    return seq;\n}\nfunction traceOnSettle(state, e) {\n    const seq = ++state.seq;\n    state.settled++;\n    traceBuffer(state, { v: 1, runId: state.runId, seq, event: 'settled', invocationId: e.invocationId, outcome: e.outcome });\n    return seq;\n}\nfunction traceClose(state) {\n    const closed = {\n        v: 1,\n        runId: state.runId,\n        seq: ++state.seq,\n        event: 'run.closed',\n        counts: { dispatched: state.dispatched, settled: state.settled },\n    };\n    traceBuffer(state, closed);\n}\nfunction traceFlushCmd(state, traceFileAbs) {\n    if (state.buffer.length === 0)\n        return null;\n    const lines = state.buffer.splice(0, state.buffer.length);\n    const file = traceShellQuote(traceFileAbs);\n    const dir = traceShellQuote(traceFileAbs.replace(/\\/[^/]*$/, ''));\n    const printfs = lines\n        .map((l) => \"printf '%s\\\\n' \" + traceShellQuote(l) + ' | sed \"s/}$/,\\\\\"wallTime\\\\\":\\\\\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\\\\\"}/\" >> ' + file)\n        .join(' && ');\n    return 'mkdir -p ' + dir + ' && ' + printfs;\n}\nfunction traceFaRecordCmd(dzBin, slug, stepLabel, projectAbs) {\n    if (typeof slug !== 'string' || slug === ''\n        || typeof stepLabel !== 'string' || stepLabel === ''\n        || typeof projectAbs !== 'string' || projectAbs === '')\n        return null;\n    const bin = typeof dzBin === 'string' && dzBin !== '' ? dzBin : 'dz';\n    const cmd = traceShellQuote(bin) + ' statusline --fa-record --slug ' + traceShellQuote(slug)\n        + ' --step ' + traceShellQuote(stepLabel) + ' --kind loop --project ' + traceShellQuote(projectAbs);\n    return cmd + ' >/dev/null 2>&1';\n}\nfunction traceLedgerLine(opts) {\n    try {\n        if (typeof opts.slug !== 'string' || opts.slug === '')\n            return null;\n        const agents = typeof opts.agents === 'number'\n            && Number.isFinite(opts.agents)\n            && Number.isInteger(opts.agents)\n            && opts.agents >= 0\n            ? opts.agents\n            : 0;\n        const date = typeof opts.date === 'string' && /^\\d{4}-\\d{2}-\\d{2}$/.test(opts.date) ? opts.date : null;\n        const outcome = typeof opts.outcome === 'string' && opts.outcome !== '' ? opts.outcome : 'unknown';\n        const line = JSON.stringify({\n            slug: opts.slug,\n            stage: 'loop-run',\n            tier: null,\n            tokens: null,\n            minutes: null,\n            agents,\n            coder: null,\n            grade: null,\n            date,\n            auto: true,\n            outcome,\n            runId: typeof opts.runId === 'string' ? opts.runId : null,\n            planDigest: typeof opts.planDigest === 'string' ? opts.planDigest : null,\n        });\n        return line.length <= 4000 ? line : null;\n    }\n    catch {\n        return null;\n    }\n}\nfunction traceLedgerAppendCmd(repoAbs, line) {\n    if (typeof repoAbs !== 'string' || repoAbs === '' || typeof line !== 'string' || line === '')\n        return null;\n    const dir = traceShellQuote(repoAbs + '/.dz/feature-adr');\n    const file = traceShellQuote(repoAbs + '/.dz/feature-adr/run-cost-ledger.jsonl');\n    return 'mkdir -p ' + dir\n        + \" && printf '%s' \" + traceShellQuote(line)\n        + ' | sed \"s/\\\\\"date\\\\\":null/\\\\\"date\\\\\":\\\\\"$(date -u +%Y-%m-%d)\\\\\"/\" >> ' + file\n        + \" && printf '\\\\n' >> \" + file\n        + ' && echo LEDGER-OK';\n}\nfunction invocations(run) {\n    const out = new Map();\n    for (const e of run.events) {\n        if (e.event === 'dispatched') {\n            out.set(e.invocationId, {\n                invocationId: e.invocationId,\n                stepId: e.stepId,\n                itemKey: e.itemKey,\n                dispatchSeq: e.seq,\n                settleSeq: null,\n                causedBy: e.causedBy,\n            });\n        }\n        else if (e.event === 'settled') {\n            const inv = out.get(e.invocationId);\n            if (inv)\n                inv.settleSeq = e.seq;\n        }\n    }\n    return [...out.values()];\n}",
   },
   "ha-consult-router": {
     name: "ha-consult-router",

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');