@dzhechkov/harness-core 0.4.1 → 0.4.3

package/src/backlog.ts

@@ -91,6 +91,9 @@ export type DedupAction = 'duplicate' | 'related' | 'new';
 /** Pure output of the classifier (04) — consumed by capture. */
 export interface DedupVerdict {
   readonly action: DedupAction;
+  /** Ids excluded from VECTOR candidacy because their text was edited without a re-embed yet. A
+   * consumer must read this before treating a `new` verdict as "compared against everything". */
+  readonly staleExcluded?: string[];
   /** Top-1 raw cosine (ADR-002 — never an RRF score). `-1` when there is nothing to compare against. */
   readonly cosine: number;
   readonly matchedId: string | undefined;
@@ -593,6 +596,160 @@ export function transitionIdeas(
   return { ok: true, dryRun, changes, errors: [], written: true };
 }
 
+/* ── Edit a captured idea's TEXT (idea 1fde7bf6) ─────────────────────────────────────────────
+ *
+ * Why this verb exists at all: editing the store by hand does NOT re-embed the record, so its dedup
+ * vector keeps describing the OLD text and later duplicate checks run against something the record
+ * no longer says. The verb owns the text change; the CALLER owns the re-embed (it is async and needs
+ * the vector tier). Between the two, the record carries `embedStale` — see ADR-001: the guard against
+ * a stale vector lives where the HARM would be (the dedup verdict), not where the failure happened.
+ * ────────────────────────────────────────────────────────────────────────────────────────── */
+
+/** Where an edit's PREVIOUS text is preserved. An edit destroys text and `reopen` cannot undo it the
+ * way it undoes `drop`, so the old text is appended here before the store is rewritten. */
+export function editsLogPath(projectRoot: string): string {
+  return join(projectRoot, '.dz', 'backlog', 'edits.jsonl');
+}
+
+export interface EditReport {
+  readonly ok: boolean;
+  readonly dryRun: boolean;
+  readonly id?: string;
+  readonly previousText?: string;
+  readonly newText?: string;
+  readonly errors: string[];
+  readonly written: boolean;
+}
+
+/**
+ * Replace or extend ONE idea's text. Mirrors `transitionIdeas`' line discipline exactly: the file is
+ * split without discarding anything, every untouched line — including a line the parser cannot read —
+ * goes back BYTE-FOR-BYTE, and only the matched record's line is re-serialised. The store holds
+ * dozens of records; a whole-file JSON round-trip would reformat all of them to change one.
+ */
+export function editIdea(
+  projectRoot: string,
+  prefix: string,
+  opts: { text?: string; append?: string; dryRun?: boolean; nowIso?: string } = {},
+): EditReport {
+  const dryRun = opts.dryRun === true;
+  const hasText = typeof opts.text === 'string' && opts.text !== '';
+  const hasAppend = typeof opts.append === 'string' && opts.append !== '';
+  if (hasText && hasAppend) {
+    return { ok: false, dryRun, errors: ['--text and --append are mutually exclusive — pick one'], written: false };
+  }
+  if (!hasText && !hasAppend) {
+    return { ok: false, dryRun, errors: ['nothing to do: give --text "<new text>" or --append "<more text>"'], written: false };
+  }
+  const path = ideasPath(projectRoot);
+  if (!existsSync(path)) {
+    return { ok: false, dryRun, errors: ['no backlog store — nothing captured yet (dz backlog add "<idea>")'], written: false };
+  }
+  let raw: string;
+  try {
+    raw = readFileSync(path, 'utf-8');
+  } catch (e) {
+    return { ok: false, dryRun, errors: [`cannot read ${path}: ${(e as Error).message}`], written: false };
+  }
+
+  // Same line discipline as transitionIdeas: nothing is discarded, corrupt lines are left alone.
+  const lines = raw.split('\n');
+  const parsed: { index: number; obj: Record<string, unknown>; id: string }[] = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const trimmed = (lines[i] ?? '').trim();
+    if (trimmed === '') continue;
+    try {
+      const obj = JSON.parse(trimmed) as Record<string, unknown>;
+      if (typeof obj.id === 'string' && obj.id !== '') parsed.push({ index: i, obj, id: obj.id });
+    } catch {
+      /* corrupt line — left byte-for-byte as-is */
+    }
+  }
+
+  if (!isSafeId(prefix)) {
+    return { ok: false, dryRun, errors: [`refusing an unsafe idea id: ${JSON.stringify(prefix)}`], written: false };
+  }
+  const res = resolveIdPrefix(parsed.map((p) => p.id), prefix);
+  if (res.kind === 'not-found') {
+    return { ok: false, dryRun, errors: [`no idea matches ${prefix} — run dz backlog list to see the ids`], written: false };
+  }
+  if (res.kind === 'ambiguous') {
+    return { ok: false, dryRun, errors: [`ambiguous prefix ${prefix} — matches ${res.matches.join(', ')}; give more characters`], written: false };
+  }
+  const entries = parsed.filter((p) => p.id === res.id);
+  if (entries.length > 1) {
+    // Deciding on the first line while rewriting one is how the sibling verb grew its twin bug.
+    return { ok: false, dryRun, errors: [`${res.id} appears ${entries.length}× in the store (duplicate lines; resolve the duplicate by hand)`], written: false };
+  }
+  const entry = entries[0]!;
+  const previousText = typeof entry.obj.text === 'string' ? (entry.obj.text as string) : '';
+  const newText = hasText ? (opts.text as string) : `${previousText}${previousText === '' ? '' : ' '}${opts.append as string}`;
+  if (newText === previousText) {
+    return { ok: true, dryRun, id: res.id, previousText, newText, errors: [], written: false };
+  }
+  if (dryRun) {
+    return { ok: true, dryRun, id: res.id, previousText, newText, errors: [], written: false };
+  }
+
+  // Only `text` changes, plus the stale marker. Every other field is carried through untouched.
+  entry.obj.text = newText;
+  entry.obj.embedStale = true;
+  lines[entry.index] = JSON.stringify(entry.obj);
+
+  const nowIso = opts.nowIso ?? new Date().toISOString();
+  const logPath = editsLogPath(projectRoot);
+  try {
+    mkdirSync(join(projectRoot, '.dz', 'backlog'), { recursive: true });
+    appendFileSync(logPath, `${JSON.stringify({ id: res.id, previousText, newText, ts: nowIso })}\n`);
+  } catch (e) {
+    // The trail is the ONLY copy of the previous text. Refuse rather than destroy it untraceably.
+    return { ok: false, dryRun, id: res.id, previousText, newText, errors: [`edit log write failed, store left untouched: ${(e as Error).message}`], written: false };
+  }
+
+  const tmp = `${path}.tmp-${process.pid}`;
+  try {
+    writeFileSync(tmp, lines.join('\n'));
+    renameSync(tmp, path);
+  } catch (e) {
+    try { unlinkSync(tmp); } catch { /* best-effort litter cleanup */ }
+    return { ok: false, dryRun, id: res.id, previousText, newText, errors: [`store write failed: ${(e as Error).message}`], written: false };
+  }
+  return { ok: true, dryRun, id: res.id, previousText, newText, errors: [], written: true };
+}
+
+/** Clear the stale marker after a successful re-embed. Separate from `editIdea` because the re-embed
+ * is async and belongs to the caller; a marker cleared without a re-embed would be a lie. */
+export function clearEmbedStale(projectRoot: string, id: string): boolean {
+  const path = ideasPath(projectRoot);
+  if (!existsSync(path)) return false;
+  let raw: string;
+  try { raw = readFileSync(path, 'utf-8'); } catch { return false; }
+  const lines = raw.split('\n');
+  let touched = false;
+  for (let i = 0; i < lines.length; i += 1) {
+    const trimmed = (lines[i] ?? '').trim();
+    if (trimmed === '') continue;
+    try {
+      const obj = JSON.parse(trimmed) as Record<string, unknown>;
+      if (obj.id === id && obj.embedStale === true) {
+        delete obj.embedStale;
+        lines[i] = JSON.stringify(obj);
+        touched = true;
+      }
+    } catch { /* corrupt line — left alone */ }
+  }
+  if (!touched) return false;
+  const tmp = `${path}.tmp-clear-${process.pid}`;
+  try {
+    writeFileSync(tmp, lines.join('\n'));
+    renameSync(tmp, path);
+    return true;
+  } catch {
+    try { unlinkSync(tmp); } catch { /* best-effort */ }
+    return false;
+  }
+}
+
 /* ── Store privacy (idea ec4cd60d): raw ideas are prompt-class PRIVATE content, like recall-usage.jsonl. ── */
 
 export type GitignoreAction = 'created' | 'appended' | 'already-covered' | 'user-opted-out' | 'skipped';
@@ -741,6 +898,11 @@ export interface DedupCandidate {
   readonly id: string;
   readonly cosine: number;
   readonly containment?: number;
+  /** Set when the record's text was edited but its vector has not been rewritten yet (ADR-001,
+   * idea 1fde7bf6). Such a candidate is excluded from VECTOR candidacy — its cosine describes text
+   * the record no longer has. The exact-text net still applies: the marker degrades SIMILARITY,
+   * never IDENTITY. */
+  readonly embedStale?: boolean;
 }
 
 /**
@@ -762,10 +924,18 @@ export function classifyDedup(
   // HIGH-4: a non-finite cosine (NaN/±Infinity) sorts unpredictably and can shove a real 0.97 duplicate
   // out of the top slot → misclassified NEW. Drop non-finite candidates BEFORE sorting/banding (the
   // recurring repo `Number.isFinite` lesson).
-  const sorted = candidates.filter((c) => Number.isFinite(c.cosine)).sort((a, b) => b.cosine - a.cosine);
+  // A record whose text was edited but whose vector has not been rewritten is EXCLUDED from vector
+  // candidacy — the same treatment a non-finite cosine gets, and for the same reason: the number does
+  // not describe the record. ADR-001: the guard sits where the HARM would be (this verdict, days after
+  // the edit) rather than where the failure happened (the edit's own output, which nobody re-reads).
+  const staleExcluded = candidates.filter((c) => c.embedStale === true).map((c) => c.id);
+  const sorted = candidates
+    .filter((c) => c.embedStale !== true)
+    .filter((c) => Number.isFinite(c.cosine))
+    .sort((a, b) => b.cosine - a.cosine);
   const top = sorted[0];
   const exactTextOnly = opts.exactTextOnly === true;
-  if (top === undefined) return { action: 'new', cosine: -1, matchedId: undefined, topMatchId: undefined, relatedIds: [], exactTextOnly };
+  if (top === undefined) return { action: 'new', cosine: -1, matchedId: undefined, topMatchId: undefined, relatedIds: [], exactTextOnly, staleExcluded };
   const bands = new Map(sorted.map((c) => [c.id, dedupPairBand(c.cosine, c.containment, cfg)]));
   if (bands.get(top.id) === 'duplicate') {
     return {
@@ -775,6 +945,7 @@ export function classifyDedup(
       topMatchId: top.id,
       relatedIds: [],
       exactTextOnly,
+      staleExcluded,
       ...(top.containment !== undefined ? { containment: top.containment } : {}),
     };
   }
@@ -794,6 +965,7 @@ export function classifyDedup(
       topMatchId: top.id,
       relatedIds: [],
       exactTextOnly,
+      staleExcluded,
       subsetMatch: true,
       ...(subset.containment !== undefined ? { containment: subset.containment } : {}),
       ...demoted,
@@ -810,11 +982,12 @@ export function classifyDedup(
       topMatchId: top.id,
       relatedIds: related.map((c) => c.id),
       exactTextOnly,
+      staleExcluded,
       ...topContainment,
       ...demoted,
     };
   }
-  return { action: 'new', cosine: top.cosine, matchedId: undefined, topMatchId: top.id, relatedIds: [], exactTextOnly, ...topContainment };
+  return { action: 'new', cosine: top.cosine, matchedId: undefined, topMatchId: top.id, relatedIds: [], exactTextOnly, ...topContainment , staleExcluded };
 }
 
 /** Injectable deps so the production dedup path is testable without a live agentdb. */

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

@@ -34,6 +34,7 @@ export * from './operations.js';
 export * from './workflows.js';
 // loop-designer (feature loop-designer): loop-plan/1 schema + generator + lint + trace planes.
 export * from './loop-plan.js';
+export * from './loop-plan-graph.js';
 export * from './loop-render.js';
 // loop-lint: EXPLICIT export list (QE round-2 G14) — `dominators`, the deliberately-WEAKER
 // analysis kept in src/loop-lint.ts solely as AM-1's mutation seam, is NOT part of the published
@@ -53,6 +54,7 @@ export {
   type LintOptions,
 } from './loop-lint.js';
 export * from './loop-trace.js';
+export * from './trace-bundle.js';
 export { BLOBS as LOOP_BLOBS, LOOP_BLOB_NAMES, BLOB_COVERAGE_MANIFEST } from './loop-blobs.generated.js';
 export type { LoopBlob } from './loop-blobs.generated.js';
 export * from './sign.js';
@@ -127,7 +129,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';
@@ -491,6 +493,7 @@ export * from './session-retro.js';
 export * from './feature-adr-setup.js';
 export * from './challenge-panel.js';
 export * from './routing-outcomes.js';
+export * from './model-recommender.js';
 export * from './bto-optimize.js';
 export * from './discrimination-gate.js';
 export * from './guard.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",