@dzhechkov/harness-core 0.5.0 → 0.5.2

package/src/codex-hooks-assets.ts

@@ -50,9 +50,17 @@ const ERROR_LOG = path.join(CODEX_HOME, 'dz-hooks', 'helper-errors.jsonl');
  * surfaces a hook's stderr in the transcript ONLY when the hook exits 2 — an exit-0 hook's stderr is
  * swallowed. So a warn that lived only on stderr would be unobservable, and "the guard is live but
  * not blocking" (G-J) would be unprovable. This file is where it is observable.
+ *
+ * The log is 0600 inside a 0700 directory, ENFORCED on every write rather than assumed at creation:
+ * \`mkdir -p\` never relaxes an existing directory's mode, so a helper dir that predates dz (or a
+ * permissive umask) would leave the record world-readable (independent review, finding 8).
  */
 function note(stage, err, extra) {
   try {
+    try { fs.mkdirSync(path.dirname(ERROR_LOG), { recursive: true, mode: 0o700 }); } catch (_) { /* exists */ }
+    try { fs.chmodSync(path.dirname(ERROR_LOG), 0o700); } catch (_) { /* not ours to tighten */ }
+    try { if (!fs.existsSync(ERROR_LOG)) fs.writeFileSync(ERROR_LOG, '', { mode: 0o600 }); } catch (_) { /* raced */ }
+    try { fs.chmodSync(ERROR_LOG, 0o600); } catch (_) { /* not ours to tighten */ }
     fs.appendFileSync(
       ERROR_LOG,
       JSON.stringify(Object.assign(
@@ -63,6 +71,35 @@ function note(stage, err, extra) {
   } catch (_) { /* the note is best-effort; it must never become the failure */ }
 }
 
+/**
+ * What a note may say about a COMMAND: its hash, its program name, and a probe nonce if one is
+ * embedded — never the line itself.
+ *
+ * A veto fires on exactly the commands most likely to carry a credential (\`ssh\`, \`curl -u\`,
+ * \`psql\`), and the note is a durable file in the user's home. It recorded the full line
+ * (independent review, finding 8). The hash keeps the record useful — two notes are the same
+ * command iff their hashes match — and \`probeNonce\` keeps the live probe gradeable, because the
+ * probe's own correlator is a purpose-built token (\`dzprobe-…\` / \`dzverify-…\`) and not a secret.
+ */
+function commandFacts(command) {
+  var facts = {};
+  try {
+    facts.commandSha256 = require('node:crypto').createHash('sha256').update(String(command), 'utf8').digest('hex');
+  } catch (_) { /* hashing is best-effort too */ }
+  try {
+    // The first token is a BINARY NAME or nothing. \`SECRET=xyz ssh …\` puts a credential in the
+    // first token, and a synopsis is not worth one byte of it (fix round 2, R2-8): anything that is
+    // not a plain program name — in particular anything carrying \`=\` — is redacted outright.
+    var first = String(command).trim().split(/\\s+/)[0] || '';
+    facts.commandSynopsis = /^[A-Za-z0-9._\\/-]+$/.test(first) ? first.slice(0, 40) : '(redacted)';
+  } catch (_) { /* ignore */ }
+  try {
+    var m = String(command).match(/dz(?:probe|verify)-[0-9a-zA-Z-]+/);
+    if (m) facts.probeNonce = m[0];
+  } catch (_) { /* ignore */ }
+  return facts;
+}
+
 function readPayload() {
   try {
     const raw = fs.readFileSync(0, 'utf8');
@@ -162,14 +199,14 @@ function main() {
 
   if (mode === 'block') {
     process.stderr.write('DZ-VETO: ' + hit.rule + ' — ' + hit.reason + ' — command: ' + command + '\\n');
-    note('veto-block', null, { marker: 'DZ-VETO', rule: hit.rule, command: command, mode: mode });
+    note('veto-block', null, Object.assign({ marker: 'DZ-VETO', rule: hit.rule, mode: mode }, commandFacts(command)));
     return 2;
   }
   const warnLine = 'DZ-VETO-WARN: ' + hit.rule + ' — ' + hit.reason + ' — command: ' + command;
   process.stderr.write(warnLine + '\\n');
   // Codex swallows an exit-0 hook's stderr (MEASURED), so the warn is ALSO recorded where it can be
   // read back — otherwise the shipped default would be live-but-unobservable.
-  note('veto-warn', null, { marker: 'DZ-VETO-WARN', rule: hit.rule, command: command, mode: mode });
+  note('veto-warn', null, Object.assign({ marker: 'DZ-VETO-WARN', rule: hit.rule, mode: mode }, commandFacts(command)));
   return 0;
 }
 

package/src/codex-hooks-verify.ts

@@ -46,8 +46,29 @@ export interface VetoProbeEvidence {
   readonly transcript: string;
   /** Per-run nonce embedded in the probe command; guards against grading a stale transcript. */
   readonly nonce: string;
-  /** Did the sentinel side effect land? `true` ⇒ the command RAN. */
-  readonly sentinelPresent: boolean;
+  /**
+   * Did the sentinel side effect land? `true` ⇒ the command RAN.
+   *
+   * `null` ⇒ the state could NOT be established (the stat failed, or a transcript carried no
+   * sentinel header). ADR-002 §2 row `sentinelExists === null` ⇒ `inconclusive`: the QE fix round
+   * found the probe parser DEFAULTING a missing header to `false`, which is the difference between
+   * "the command was blocked" and "we did not look" (independent review, finding 4).
+   */
+  readonly sentinelPresent: boolean | null;
+  /**
+   * Did the `codex` invocation COMPLETE? `false` ⇒ inconclusive whatever the transcript says
+   * (ADR-002 §2). `null` ⇒ the caller LOOKED and could not tell ⇒ also inconclusive. Absent ⇒ the
+   * caller did not report completion at all; the other evidence still decides.
+   *
+   * The three-way split is the fix-round-2 correction (R2-4): a recorder that cannot find its own
+   * completion fields must say so EXPLICITLY, and an explicit "unknown" must not be graded like a
+   * caller who simply never spoke about completion.
+   */
+  readonly ran?: boolean | null | undefined;
+  /** The invocation's exit status. `null` ⇒ the process died / was killed / unrecorded ⇒ inconclusive. */
+  readonly exitCode?: number | null | undefined;
+  /** The invocation hit its timeout. `null` ⇒ recorded as unknown ⇒ inconclusive. */
+  readonly timedOut?: boolean | null | undefined;
   /** Did the transcript show the model actually attempting the shell command? */
   readonly shellAttempted: boolean;
   /** Was `--dangerously-bypass-hook-trust` in play? `true` can never yield a pass. */
@@ -96,6 +117,38 @@ export function classifyVetoProbe(e: VetoProbeEvidence): VetoProbeResult {
 
   const trust = classifyTrust(e.trustStatus);
 
+  // 1b. COMPLETION (ADR-002 §2, row "invocation did not complete"). A transcript from a run that
+  //     died, timed out, or never finished is a partial reading, and the marker can appear in a
+  //     partial reading. Decided before any transcript evidence is weighed (fix-round finding 4).
+  if (e.timedOut === true) {
+    return { verdict: 'inconclusive', trust, reason: 'the probe invocation TIMED OUT: a partial transcript is a failed observation, not a clean run' };
+  }
+  if (e.timedOut === null) {
+    return { verdict: 'inconclusive', trust, reason: 'completion evidence incomplete: the timeout state was recorded as UNKNOWN — a run that may have been cut short cannot witness a block' };
+  }
+  if (e.ran === null) {
+    return { verdict: 'inconclusive', trust, reason: 'completion evidence incomplete: whether the probe invocation completed was recorded as UNKNOWN' };
+  }
+  if (e.ran === false) {
+    return {
+      verdict: 'inconclusive',
+      trust,
+      reason:
+        e.sentinelPresent === true
+          ? 'contradictory evidence: the invocation is reported as never completed, yet the sentinel side effect landed'
+          : 'the probe invocation did not complete — there is nothing to grade',
+    };
+  }
+  if (e.exitCode === null) {
+    return { verdict: 'inconclusive', trust, reason: 'the probe process died without an exit status (signal or kill) — evidence is missing, not clean' };
+  }
+
+  // 1c. An UNKNOWN sentinel state cannot be graded: "absent" is half of the two-sided witness, and
+  //     "we did not look" must never be spelled the same way (finding 4).
+  if (e.sentinelPresent !== true && e.sentinelPresent !== false) {
+    return { verdict: 'inconclusive', trust, reason: 'the sentinel side-effect state could not be established — evidence is missing, not clean' };
+  }
+
   // 2. Stale facts are not facts (AM-10).
   const recorded = e.recordedCodexVersion;
   const probed = e.probedCodexVersion;

package/src/codex-hooks.ts

@@ -28,8 +28,16 @@ import { join } from 'node:path';
 
 import { mergeManagedHookEntries } from './managed-hooks.js';
 
-/** Bump when a helper BODY changes: a changed body changes codex's `currentHash` ⇒ re-trust. */
-export const DZ_HOOK_HELPER_VERSION = 1;
+/**
+ * Bump when a helper BODY changes: a changed body changes codex's `currentHash` ⇒ re-trust.
+ *
+ * 2 — the independent-QE fix round: the veto note stopped persisting the raw command line and the
+ * notes log/dir modes are now enforced on every write (finding 8).
+ * 3 — fix round 2: the note's `commandSynopsis` is a binary NAME or `(redacted)` — an
+ * env-assignment first token (`SECRET=xyz ssh …`) carried the credential the redaction removed
+ * everywhere else (R2-8).
+ */
+export const DZ_HOOK_HELPER_VERSION = 3;
 
 /** Seconds. Probe-proven (spike S2): `timeout` is honored, the unset default is 600 s. */
 export const DZ_HOOK_TIMEOUT_SECONDS = 5;
@@ -264,6 +272,29 @@ export function isDzManagedEntry(entry: unknown, manifest: CodexHookManifest | u
   return entryCommands(entry).some((cmd) => cmd !== '' && known.has(codexHookSha256(cmd)));
 }
 
+/**
+ * Rebuild an OWNED entry from only the handlers that are NOT ours — per-HANDLER attribution.
+ *
+ * ADR-001 §5 promises that dz deletes only what it can prove it wrote. Attribution was applied to a
+ * whole MATCHER GROUP: a group holding one dz handler and one of the user's was removed (or
+ * replaced) wholesale, so a foreign handler was deleted by a rule written to protect it
+ * (independent review, finding 6). One dz handler in the group must cost exactly that handler.
+ *
+ * Returns `null` when every handler in the entry was ours (the entry itself is then dropped), and
+ * a rebuilt entry — same keys, same order, minus our handlers — when something foreign survives.
+ * A legacy FLAT entry (`{type, command}`) is one handler and has nothing to salvage.
+ */
+export function retainForeignHandlers(entry: unknown, manifest: CodexHookManifest | undefined): unknown | null {
+  if (manifest === undefined) return entry;
+  const known = new Set(manifest.entries.map((e) => e.commandSha256));
+  const isOurs = (cmd: unknown): boolean => typeof cmd === 'string' && cmd !== '' && known.has(codexHookSha256(cmd));
+  const e = entry as { hooks?: unknown };
+  if (!Array.isArray(e?.hooks)) return null; // flat shape: the entry IS the handler
+  const kept = (e.hooks as { command?: unknown }[]).filter((h) => !isOurs(h?.command));
+  if (kept.length === 0) return null;
+  return { ...(entry as Record<string, unknown>), hooks: kept };
+}
+
 /** Cheap resemblance test — drives the `unattributable` COUNT only, never a deletion. */
 export function looksLikeDzEntry(entry: unknown): boolean {
   return entryCommands(entry).some(
@@ -309,7 +340,17 @@ export function parseCodexRegistry(text: string | undefined): ParseRegistryResul
   }
   const hooks: Record<string, unknown[]> = {};
   for (const [event, value] of Object.entries((rawHooks ?? {}) as Record<string, unknown>)) {
-    hooks[event] = Array.isArray(value) ? [...value] : [];
+    // REFUSE, never coerce. `Array.isArray(value) ? [...value] : []` silently turned a foreign
+    // event whose value dz does not understand into an EMPTY list, and the next write persisted
+    // that emptiness — configuration loss dressed as a merge (independent review, finding 5). An
+    // unparseable shape is the same class of fact as unparseable JSON: refuse before planning.
+    if (!Array.isArray(value)) {
+      return {
+        ok: false,
+        error: `hooks.json event ${JSON.stringify(event)} must be an array of entries (found ${value === null ? 'null' : typeof value}) — dz refuses to rewrite a registry it cannot read without losing it`,
+      };
+    }
+    hooks[event] = [...value];
   }
   const rest: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(obj)) if (k !== 'hooks') rest[k] = v;
@@ -363,6 +404,10 @@ export function planCodexHooks(
   const plan = mergeManagedHookEntries(parsed.registry.hooks, managedByEvent(input.entries), {
     isManaged: (entry) => isDzManagedEntry(entry, selfManifest),
     looksLikeOurs: (entry) => looksLikeDzEntry(entry) && !isDzManagedEntry(entry, selfManifest),
+    // Per-HANDLER salvage (finding 6): an owned entry that also carries the user's own handler is
+    // rebuilt without ours, never dropped whole. The Claude path passes no salvage and is
+    // byte-identical to before (AM-3).
+    retainForeign: (entry) => retainForeignHandlers(entry, selfManifest),
     reportLabel: 'codex',
   });
   const registry: CodexRegistry = { rest: parsed.registry.rest, hooks: plan.hooks };
@@ -402,14 +447,19 @@ export function removeCodexHooks(
   let removed = 0;
   let unattributable = 0;
   for (const [event, entries] of Object.entries(parsed.registry.hooks)) {
-    const kept = entries.filter((entry) => {
+    const kept: unknown[] = [];
+    for (const entry of entries) {
       if (isDzManagedEntry(entry, manifest)) {
         removed += 1;
-        return false;
+        // Per-HANDLER removal (finding 6): a mixed matcher group keeps every handler that is not
+        // ours. Removing dz's guard must never remove the user's alongside it.
+        const salvaged = retainForeignHandlers(entry, manifest);
+        if (salvaged !== null) kept.push(salvaged);
+        continue;
       }
       if (looksLikeDzEntry(entry)) unattributable += 1;
-      return true;
-    });
+      kept.push(entry);
+    }
     hooks[event] = kept;
   }
   const registry: CodexRegistry = { rest: parsed.registry.rest, hooks };
@@ -482,6 +532,25 @@ export function trustEventName(event: CodexHookEvent): string {
   return event === 'PreToolUse' ? 'pre_tool_use' : 'user_prompt_submit';
 }
 
+/**
+ * Compare two event spellings the way the runtime actually spells them.
+ *
+ * MEASURED, both on this machine, on the SAME response shape:
+ * - the trust KEY embeds `pre_tool_use` / `user_prompt_submit` (snake_case);
+ * - `hooks/list`'s `eventName` FIELD is `preToolUse` / `userPromptSubmit` on **codex-cli 0.148.0**
+ *   (reproducer: `listCodexHooks(<temp home>)` after an install — the rows are printed verbatim in
+ *   `07_code_changes/probe-results/fixround/trust-diagnosis.txt`).
+ *
+ * Pinning either spelling alone silently drops every row: the fix round's first cut compared the
+ * field against the KEY spelling, `hooks/list` matched 0 of 2 entries, trust was never written, and
+ * the live probe's ARMED leg stopped blocking. Case and separators are therefore normalised away —
+ * the spelling is the runtime's cosmetic choice, the EVENT is the fact.
+ */
+export function sameHookEvent(a: string, b: string): boolean {
+  const norm = (v: string): string => v.toLowerCase().replace(/[-_\s]/g, '');
+  return norm(a) === norm(b);
+}
+
 /**
  * The trust key codex uses: `<sourcePath>:<snake_event>:<groupIndex>:<hookIndex>`.
  *
@@ -498,6 +567,26 @@ export function expectedTrustKey(
   return `${registryPath}:${trustEventName(event)}:${groupIndex}:${hookIndex}`;
 }
 
+/**
+ * Split a `hooks/list` trust key into its parts, or `null` when it is not one.
+ *
+ * MEASURED shape: `<sourcePath>:<snake_event>:<groupIndex>:<hookIndex>`. The path may itself carry
+ * a colon, so the split is anchored at the END — the last two fields are the indices and the third
+ * from the end is the event.
+ *
+ * The INDICES are deliberately not predicted: they are positions inside the user's registry, and a
+ * foreign entry shifts them. What IS ours to require is the rest — this key names OUR registry and
+ * OUR event (fix round 2, R2-7: a row carrying an arbitrary key was selected on path+event+command
+ * alone, and the key is what dz then writes trust against).
+ */
+export function parseTrustKey(
+  key: string,
+): { readonly sourcePath: string; readonly event: string; readonly groupIndex: number; readonly hookIndex: number } | null {
+  const m = /^(.*):([A-Za-z_][A-Za-z_]*):(\d+):(\d+)$/.exec(key);
+  if (m === null) return null;
+  return { sourcePath: m[1] ?? '', event: m[2] ?? '', groupIndex: Number(m[3]), hookIndex: Number(m[4]) };
+}
+
 export interface HookTrustRow {
   readonly key: string;
   readonly trustedHash: string;
@@ -527,18 +616,51 @@ export function renderTrustBlock(rows: readonly HookTrustRow[]): string {
   return `${DZ_TRUST_BEGIN}\n${body}\n${DZ_TRUST_END}\n`;
 }
 
-/** Replace (or append) dz's managed trust block, leaving every other byte of config.toml alone. */
-export function upsertTrustBlock(configToml: string, rows: readonly HookTrustRow[]): string {
+export type TrustBlockResult = { readonly ok: true; readonly text: string } | { readonly ok: false; readonly error: string };
+
+function countOccurrences(haystack: string, needle: string): number {
+  let n = 0;
+  let i = haystack.indexOf(needle);
+  while (i >= 0) {
+    n += 1;
+    i = haystack.indexOf(needle, i + needle.length);
+  }
+  return n;
+}
+
+/**
+ * Replace (or append) dz's managed trust block, leaving every other byte of config.toml alone.
+ *
+ * The fence must be **exactly one well-ordered pair**, or dz refuses (independent review, finding
+ * 9). The old `indexOf`-pair logic was satisfiable by a damaged file in three ways, and each one
+ * eats the user's TOML on the NEXT sync: a lone BEGIN made the rewrite append a second block, so
+ * the following run's `begin…end` window spanned everything between the orphan marker and the new
+ * block's END; a reversed pair did the same; duplicate pairs left an orphan block behind. Refusing
+ * costs one manual edit — the alternative silently deletes `[projects."…"]` trust rows.
+ */
+export function upsertTrustBlock(configToml: string, rows: readonly HookTrustRow[]): TrustBlockResult {
   const block = renderTrustBlock(rows);
-  const begin = configToml.indexOf(DZ_TRUST_BEGIN);
-  const end = configToml.indexOf(DZ_TRUST_END);
-  if (begin >= 0 && end > begin) {
+  const begins = countOccurrences(configToml, DZ_TRUST_BEGIN);
+  const ends = countOccurrences(configToml, DZ_TRUST_END);
+  const heal = `heal by hand: leave exactly one ${JSON.stringify(DZ_TRUST_BEGIN)} … ${JSON.stringify(DZ_TRUST_END)} pair (or delete both markers) and re-run`;
+  if (begins > 1 || ends > 1) {
+    return { ok: false, error: `config.toml carries ${begins} dz trust BEGIN and ${ends} END markers — dz refuses to guess which block is its own. ${heal}` };
+  }
+  if (begins !== ends) {
+    return { ok: false, error: `config.toml carries an UNPAIRED dz trust marker (${begins} BEGIN, ${ends} END) — rewriting it would consume unrelated TOML. ${heal}` };
+  }
+  if (begins === 1) {
+    const begin = configToml.indexOf(DZ_TRUST_BEGIN);
+    const end = configToml.indexOf(DZ_TRUST_END);
+    if (end < begin) {
+      return { ok: false, error: `config.toml carries the dz trust END marker BEFORE its BEGIN — the fence is inverted and the span between them is not dz's. ${heal}` };
+    }
     const before = configToml.slice(0, begin);
     const after = configToml.slice(end + DZ_TRUST_END.length).replace(/^\n/, '');
-    return `${before}${block}${after}`;
+    return { ok: true, text: `${before}${block}${after}` };
   }
   const base = configToml === '' || configToml.endsWith('\n') ? configToml : `${configToml}\n`;
-  return `${base}${base === '' ? '' : '\n'}${block}`;
+  return { ok: true, text: `${base}${base === '' ? '' : '\n'}${block}` };
 }
 
 export interface HooksListHookMetadata {
@@ -553,19 +675,49 @@ export interface HooksListHookMetadata {
   readonly timeoutSec: number;
 }
 
+export interface SelectOwnHookOptions {
+  /** The registry file dz wrote. A row from any other source path is not dz's row. */
+  readonly registryPath: string;
+}
+
 /**
- * Pick, from a `hooks/list` response, the metadata of the entries WE wrote — matched on the exact
- * command string, so a third party's entry can never inherit dz's trust write.
+ * Pick, from a `hooks/list` response, the metadata of the entries WE wrote.
+ *
+ * The match is on THREE facts, not one (independent review, finding 7): the row's `sourcePath` is
+ * the registry dz wrote, its `eventName` is the event dz registered the entry under, and the
+ * command string is byte-equal. Command alone was not enough — a project-scoped
+ * `<repo>/.codex/hooks.json` DOES load on codex 0.148 (MEASURED, see ADR-004's addendum), so a
+ * shadow copy of dz's own command line could supply the `trusted` row that armed the user-global
+ * entry nobody had approved.
+ *
+ * AMBIGUITY IS REFUSED, not resolved: two rows claiming the same entry drop BOTH, because the one
+ * dz would arm is then a coin flip and the trust write is keyed by the row it picked.
  */
 export function selectOwnHookMetadata(
   hooks: readonly HooksListHookMetadata[],
   entries: readonly ManagedEntry[],
+  options: SelectOwnHookOptions,
 ): { readonly id: CodexHookId; readonly meta: HooksListHookMetadata }[] {
-  const byCommand = new Map(entries.map((e) => [e.command, e.id] as const));
-  const out: { id: CodexHookId; meta: HooksListHookMetadata }[] = [];
+  const byCommand = new Map(entries.map((e) => [e.command, e] as const));
+  const claims = new Map<CodexHookId, { id: CodexHookId; meta: HooksListHookMetadata }[]>();
   for (const meta of hooks) {
-    const id = typeof meta.command === 'string' ? byCommand.get(meta.command) : undefined;
-    if (id !== undefined) out.push({ id, meta });
+    if (typeof meta.command !== 'string') continue;
+    const entry = byCommand.get(meta.command);
+    if (entry === undefined) continue;
+    if (meta.sourcePath !== options.registryPath) continue;
+    if (!sameHookEvent(meta.eventName, trustEventName(entry.event))) continue;
+    // The KEY is the thing dz writes trust against, so it — not just the row's other fields — has
+    // to be the key our entry would own (R2-7). An arbitrary or foreign key is ambiguous by
+    // construction: arming it would persist trust for something we cannot identify.
+    const parsedKey = typeof meta.key === 'string' ? parseTrustKey(meta.key) : null;
+    if (parsedKey === null) continue;
+    if (parsedKey.sourcePath !== options.registryPath) continue;
+    if (!sameHookEvent(parsedKey.event, trustEventName(entry.event))) continue;
+    (claims.get(entry.id) ?? claims.set(entry.id, []).get(entry.id)!).push({ id: entry.id, meta });
+  }
+  const out: { id: CodexHookId; meta: HooksListHookMetadata }[] = [];
+  for (const rows of claims.values()) {
+    if (rows.length === 1) out.push(rows[0]!);
   }
   return out;
 }

package/src/feature-adr-routing.ts

@@ -1479,3 +1479,58 @@ export function checkArtifactRoot(root: string): string | null {
   if (hasDotDotSegment(root)) return 'artifact root contains a ".." segment: ' + root;
   return null;
 }
+
+
+// ── K2 plan-completeness gate (feature fa-plan-gate-wiring) ────────────────────────────────────
+// Step 7 must not start on an incomplete plan. The gate is a SCRIPT the pipeline shells out to;
+// these two pure halves build its command and PARSE its verdict. The workflow inlines byte-equivalent
+// copies (drift-guarded), because the workflow sandbox cannot import.
+
+/** The one path the pipeline calls. Repo-relative — the command `cd`s into the repo root first. */
+export const PLAN_GATE_SCRIPT = '.claude/skills/feature-adr/scripts/check-plan-completeness.mjs';
+
+export interface PlanGateVerdict {
+  /** 'pass' ONLY when the script's own last line AND its exit code agree on PASS. */
+  verdict: 'pass' | 'fail' | 'not-established';
+  /** The script's exit code as reported by the `K2_EXIT=` trailer, or null when unparseable. */
+  exit: number | null;
+  reason: string;
+  output: string;
+}
+
+/**
+ * The EXACT command the gate agent runs. `2>&1` folds stderr in (a crash must be visible, not
+ * silently empty) and the `K2_EXIT=` trailer carries the exit code back through an agent that can
+ * only return text.
+ */
+export function planCompletenessGateCmd(repo: string, featureDir: string, tier?: string | null): string {
+  const q = (s: string) => "'" + String(s).replace(/'/g, "'\\''") + "'"
+  const t = (typeof tier === 'string' && tier !== '') ? ' --tier=' + q(tier) : ''
+  return 'cd ' + q(repo) + ' && node ' + q(PLAN_GATE_SCRIPT) + ' ' + q(featureDir) + t + ' 2>&1; echo K2_EXIT=$?'
+}
+
+/**
+ * PARSE-NEVER-SYNTHESIZE. An empty reply, a reply with no verdict line, a missing/unknown exit code,
+ * or a verdict line that DISAGREES with the exit code are all `not-established` — never a pass. The
+ * quiet failure this forecloses: a dead or chatty agent reading as a clean gate.
+ */
+export function parsePlanGateVerdict(raw: string | null | undefined): PlanGateVerdict {
+  const text = String(raw === null || raw === undefined ? '' : raw)
+  const output = text.slice(0, 2000)
+  if (text.trim() === '') return { verdict: 'not-established', exit: null, reason: 'empty-agent-reply', output: output }
+  // G-F1 (reproduced by execution): the checker ECHOES plan-controlled content, so a forged verdict
+  // line and a forged K2_EXIT trailer can appear EARLIER in this stream. The script always writes its
+  // own verdict LAST, so both halves anchor to the LAST match — a first-match read let a planted
+  // 'K2 plan-completeness: PASS (0) K2_EXIT=0' target line forge a pass on a genuine FAIL/1 run.
+  const exitAll = text.match(/K2_EXIT=(\d+)/g)
+  const lastExit = exitAll === null ? null : /K2_EXIT=(\d+)/.exec(String(exitAll[exitAll.length - 1]))
+  const exitCode = lastExit === null ? null : Number(lastExit[1])
+  const verdictAll = text.match(/K2 plan-completeness:\s*(PASS|FAIL|NOT-ESTABLISHED)/g)
+  if (verdictAll === null) return { verdict: 'not-established', exit: exitCode, reason: 'no-verdict-line', output: output }
+  const lastVerdict = String(verdictAll[verdictAll.length - 1])
+  const byName = lastVerdict.indexOf('PASS') >= 0 ? 'pass' : (lastVerdict.indexOf('FAIL') >= 0 ? 'fail' : 'not-established')
+  const byExit = exitCode === 0 ? 'pass' : (exitCode === 1 ? 'fail' : (exitCode === 3 ? 'not-established' : null))
+  if (byExit === null) return { verdict: 'not-established', exit: exitCode, reason: 'unknown-exit-code', output: output }
+  if (byExit !== byName) return { verdict: 'not-established', exit: exitCode, reason: 'verdict-exit-mismatch', output: output }
+  return { verdict: byName, exit: exitCode, reason: 'script-verdict', output: output }
+}

package/src/index.ts

@@ -26,8 +26,11 @@ export {
   buildParityMatrix,
   CAPABILITY_EVIDENCE,
   findUnbackedCapabilities,
+  findStaleTranscriptEvidence,
+  newestRecordedRuntimeVersion,
+  downgradeForStaleEvidence,
 } from './parity.js';
-export type { RuntimeCapability, FeatureForm, ParityFeature, ParityCell, ParityMatrixRow, CapabilityEvidence, UnbackedCapability } from './parity.js';
+export type { RuntimeCapability, FeatureForm, ParityFeature, ParityCell, ParityReportCell, ParityMatrixRow, CapabilityEvidence, UnbackedCapability, ProbedRuntimeVersions } from './parity.js';
 export * from './operations.js';
 // workflows.ts: the ADR-005 templates are RETIRED (feature loop-designer, AM-6) — the module is a
 // deprecation shim (empty WORKFLOW_NAMES). BREAKING for external harness-core consumers of
@@ -37,7 +40,13 @@ 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';
+// loop-run-semantics: the ONE home of the enactment DECISIONS both enactors use — the generated
+// Claude-host script (via the always-on `loop-semantics` blob) and `dz workflow run` (by import).
+export * from './loop-run-semantics.js';
 export * from './loop-render.js';
+// dz workflow run (feature dz-workflow-run): the pure scheduler + the dispatcher seam.
+export * from './workflow-run.js';
+export * from './workflow-run-dispatch.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
 // API surface; the in-package tests reach it via the module path directly.
@@ -56,6 +65,7 @@ export {
   type LintOptions,
 } from './loop-lint.js';
 export * from './loop-trace.js';
+export * from './trace-corroborate.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';
@@ -78,6 +88,30 @@ export { pretrain } from './pretrain.js';
 export { loadPatterns, loadSessions, computePatternBoost, readLearningConfig, readMemoryLearningConfig, BOOST_CAP, recordPattern, loadStorePatternsSync, loadStoreRecords, patternToRecord, recordToPattern, patternRecordId, patternIdentityOf, dreamRecordId, isMirrorableLearning, consolidateSessions, recallPatterns, pruneNoisePatterns, removePatternsByIds, snapshotStore, readReinforcementState, encodeReinforcementState, reinforcePattern, updateReinforcementState, storeStats, lessonDeltaReport, lessonDeltaMap, readQuarantineState, encodeQuarantineState, promotePatterns, quarantineExpiryCandidates, pruneQuarantinePatterns } from './patterns.js';
 export { withStoreLock, withStoreLockSync, storeLockPath, StoreLockTimeoutError, StoreLockCompromisedError, STALE_LOCK_MS, LOCK_TIMEOUT_MS } from './store-lock.js';
 export type { StoreLockOptions } from './store-lock.js';
+export { withNamedLockSync, namedLockPath, isSafeLockName, NamedLockNameError, NamedLockTimeoutError, NamedLockCompromisedError } from './named-lock.js';
+export {
+  QE_BRIDGE_SCHEMA,
+  QE_BRIDGE_FAILURE_SCHEMA,
+  CLAUDE_BRIDGE_PROMPT_CEILING_CHARS,
+  KNOWN_CLAUDE,
+  BRIDGE_MARKER,
+  BRIDGE_FENCE_LABEL,
+  BRIDGE_EXTRACT_END,
+  isSafeClaudeId,
+  CLAUDE_ISOLATION_ARGS,
+  BRIDGE_FAILURE_REASONS,
+  extractClaudeResult,
+  buildBridgeSignoffRecord,
+  claudeProbeArgs,
+  interpretClaudeProbe,
+  claudeReviewArgs,
+  defangSignoffEchoes,
+  buildBridgePrompt,
+  parseBridgeOutput,
+  buildBridgeFailureRecord,
+  renderBridgeReport,
+} from './qe-bridge.js';
+export type { BridgeFamily, BridgeFailureReason, BridgeFinding, BridgeSignoff, BridgeParse, BridgeParseOk, BridgeParseFail, BridgeChannels, BridgeAudit, ClaudeResultExtraction, NamedExtract, BridgePromptInput } from './qe-bridge.js';
 export type { PatternRecord, SessionRecord, LearningConfig, MemoryLearningConfig, LoadOptions, ConsolidateResult, ConsolidateOptions, SqliteBackendMode, RecallHit, SessionsSource, PruneNoiseResult, RemovePatternsResult, SnapshotStoreResult, ReinforcementState, ReinforcePatternResult, StoreStats, LessonDeltaReport, LessonDeltaRow, QuarantineState, PromoteResult, QuarantineExpiryCandidate } from './patterns.js';
 export { DEFAULT_REINFORCE_THRESHOLD, NoopLearningBackend, NativeReinforcementBackend, resolveLearningBackend, isLearningSignalBackend } from './learning-backend.js';
 export type { LearningSignalBackend, LearningSignalStats, LearningSample, SignalCandidate, EnhanceContext, TrainingResult, LearningBackendMode } from './learning-backend.js';
@@ -519,6 +553,16 @@ export {
   CODE_LANDING_PREDICATES,
   parseLandingSignal,
   codeLandingProbeCmd,
+  // fa-plan-gate-wiring: the K2 plan-completeness gate halves. NAMED here on purpose — an omission
+  // silently drops them from the published package (the ADR-002 Confirmation-1 lesson).
+  PLAN_GATE_SCRIPT,
+  planCompletenessGateCmd,
+  parsePlanGateVerdict,
+  // qe-bridge-claude: the bridge's path/slug hygiene reuses these rather than minting a second
+  // definition of "safe" (ADR-001 D5-A).
+  isSafeSlug,
+  hasUnsafePathChars,
+  hasDotDotSegment,
 } from './feature-adr-routing.js';
 export type {
   StageOpts,
@@ -538,6 +582,7 @@ export type {
   BaselineVerification,
   ParsedBaselineCapture,
   ParsedLandingSignal,
+  PlanGateVerdict,
 } from './feature-adr-routing.js';
 export {
   CLAUDE_USAGE_MODELS,

package/src/loop-blobs.generated.ts

@@ -25,7 +25,7 @@ export interface LoopBlob {
   code: string;
 }
 
-export const LOOP_BLOB_NAMES = ["checkpoints","training-pairs","model-resolver","usage-probes","codex-dispatch","challenge-panel","trace","ha-consult-router"] as const;
+export const LOOP_BLOB_NAMES = ["checkpoints","training-pairs","model-resolver","usage-probes","codex-dispatch","challenge-panel","trace","loop-semantics","ha-consult-router"] as const;
 
 /** Workflow files the regen-diff gate covers TODAY (AM-5 honest scope): exactly the files
  * carrying BEGIN BLOB markers. Stage B (whole-file regeneration of feature-adr.js) is a
@@ -97,11 +97,20 @@ export const BLOBS: Record<string, LoopBlob> = {
   "trace": {
     name: "trace",
     version: "1.1.0",
-    contentHash: "fc59098bb0deb747c4c1c9a6ba843df70edfe0dc5ef8370c0f7192afc7657890",
+    contentHash: "1270f9aac5fbe5693af8bcc26af55e81aeb41ef4b911dbda72c23ea248072344",
     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","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}",
+    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        const ep = ev['emitterPath'];\n        if (ep !== undefined && ep !== 'dz-process' && ep !== 'rendered-script')\n            return 'emitterPath must be dz-process|rendered-script';\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, emitterPath) {\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, emitterPath };\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}",
+  },
+  "loop-semantics": {
+    name: "loop-semantics",
+    version: "1.0.0",
+    contentHash: "d918ba8d29d9dc20e2467ddb0ba126d537bc9e4560547e2ae52d28979ee6ea9c",
+    sourcePath: "packages/@dzhechkov/harness-core/src/loop-run-semantics.ts",
+    requires: [],
+    exports: ["errText","causeChain","errSnap","classifyFailure","gateVerdict","joinRegion"],
+    code: "function errText(err) {\n    try {\n        if (err !== null && typeof err === 'object') {\n            const m = err.message;\n            if (typeof m === 'string')\n                return m;\n        }\n        return String(err);\n    }\n    catch (_e) {\n        try {\n            return Object.prototype.toString.call(err);\n        }\n        catch (_e2) {\n            return '[unrenderable error]';\n        }\n    }\n}\nfunction causeChain(err) {\n    const chain = [];\n    let cur = err;\n    for (let d = 0; d < 5; d++) {\n        if (cur === null || cur === undefined)\n            break;\n        if (chain.indexOf(cur) !== -1)\n            break;\n        chain.push(cur);\n        try {\n            cur = typeof cur === 'object' ? cur.cause : undefined;\n        }\n        catch (_e) {\n            cur = undefined;\n        }\n    }\n    return chain.length > 0 ? chain : [err];\n}\nfunction errSnap(err) {\n    const chain = causeChain(err);\n    const snap = [];\n    for (let ci = 0; ci < chain.length; ci++) {\n        let code = null;\n        try {\n            const c = chain[ci] !== null && typeof chain[ci] === 'object' ? chain[ci].code : null;\n            code = typeof c === 'string' ? c.toUpperCase() : null;\n        }\n        catch (_e) {\n            code = null;\n        }\n        let name = null;\n        try {\n            const n = chain[ci] !== null && typeof chain[ci] === 'object' ? chain[ci].name : null;\n            name = typeof n === 'string' ? n : null;\n        }\n        catch (_e) {\n            name = null;\n        }\n        snap.push({ code: code, name: name, text: errText(chain[ci]) });\n    }\n    return snap;\n}\nfunction classifyFailure(outcome, snap) {\n    if (outcome === 'null')\n        return 'transport';\n    const links = Array.isArray(snap) ? snap : [];\n    for (let ci = 0; ci < links.length; ci++) {\n        const code = links[ci].code;\n        if (code === 'ETIMEDOUT' || code === 'ECONNRESET' || code === 'ECONNREFUSED' || code === 'ENOTFOUND' || code === 'EPIPE' || code === 'ECONNABORTED' || code === 'EAI_AGAIN')\n            return 'transport';\n    }\n    for (let ci = 0; ci < links.length; ci++) {\n        if (links[ci].name === 'SyntaxError')\n            return 'malformed-output';\n    }\n    let msg = '';\n    for (let ci = 0; ci < links.length; ci++)\n        msg += (ci > 0 ? '\\n' : '') + links[ci].text;\n    msg = msg.toLowerCase();\n    if (/\\btransport\\b|\\beconnreset\\b|\\beconnrefused\\b|\\benotfound\\b|\\bepipe\\b|\\betimedout\\b|\\bsocket hang up\\b|\\bnetwork error\\b|\\brate[ -]?limit(ed|ing|s)?\\b|\\boverloaded\\b|\\bhttp 5[0-9][0-9]\\b/.test(msg))\n        return 'transport';\n    if (/\\bpolicy\\b|\\brefus(e|ed|es|al|ing)\\b|\\bdeclin(e|ed|es|ing)\\b|\\bcontent filter\\b|\\bsafety block\\b/.test(msg))\n        return 'policy-refusal';\n    if (/\\bmalformed\\b|\\bunparseable\\b|\\bparse error\\b|\\binvalid json\\b|\\bunexpected token\\b|\\bunexpected end of json\\b|\\bschema mismatch\\b/.test(msg))\n        return 'malformed-output';\n    if (/\\btimeout\\b|\\btimed out\\b/.test(msg))\n        return 'timeout';\n    return null;\n}\nfunction gateVerdict(reply) {\n    if (typeof reply !== 'string')\n        return 'invalid';\n    const vLines = reply.split('\\n');\n    const vRe = /^\\s*GATE:\\s*(PASS|FAIL)\\s*$/;\n    let vCount = 0;\n    let vLast = '';\n    for (let i = 0; i < vLines.length; i++) {\n        if (vRe.test(vLines[i]))\n            vCount++;\n        if (vLines[i].trim() !== '')\n            vLast = vLines[i];\n    }\n    const vEnd = vRe.exec(vLast);\n    if (vCount !== 1 || vEnd === null)\n        return 'invalid';\n    return vEnd[1] === 'PASS' ? 'pass' : 'fail';\n}\nfunction joinRegion(results, o) {\n    const policy = o && o.policy ? o.policy : 'all-activated';\n    const failures = [];\n    for (let i = 0; i < results.length; i++) {\n        if (results[i] === null || results[i] === undefined)\n            failures.push(i);\n    }\n    if (policy === 'any') {\n        if (failures.length === results.length)\n            throw new Error('join ' + o.region + ': every branch failed (policy any)');\n        return { ok: true, values: results, failures: failures };\n    }\n    const quorum = /^quorum:([1-9][0-9]*)$/.exec(policy);\n    if (quorum) {\n        const okN = results.length - failures.length;\n        if (okN < Number(quorum[1]))\n            throw new Error('join ' + o.region + ': quorum ' + quorum[1] + ' not met (' + okN + ' ok)');\n        return { ok: true, values: results, failures: failures };\n    }\n    if (failures.length > 0)\n        throw new Error('join ' + o.region + ': ' + failures.length + ' dispatched branch(es) failed under policy ' + policy + ' — a dispatched branch is never skippable');\n    return { ok: true, values: results, failures: [] };\n}",
   },
   "ha-consult-router": {
     name: "ha-consult-router",