@dzhechkov/harness-cli 0.5.0 → 0.5.1

package/src/cli.ts

@@ -7,8 +7,8 @@
 import { appendFileSync, chmodSync, closeSync, cpSync, existsSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, readlinkSync, realpathSync, renameSync, rmdirSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { execFileSync, execSync, spawn } from 'node:child_process';
-import { createHash } from 'node:crypto';
+import { execFileSync, execSync, spawn, type ChildProcess } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
 import { homedir, tmpdir } from 'node:os';
 import { createRequire } from 'node:module';
 
@@ -56,11 +56,36 @@ import {
   runInitGeminiMd,
   runSyncAgentsPolicy,
   runSyncCodexHooks,
+  resolveCodexHome,
+  withNamedLockSync,
+  // dz workflow run (feature dz-workflow-run): the pure scheduler + the dispatch adapters.
+  TRACE_RUNID_RE,
+  WF_RUN_OWNER_HOST,
+  preflight,
+  runWorkflow,
+  makeClaudePDispatcher,
+  makeCodexExecDispatcher,
+  type ChildRunner,
+  type Dispatcher,
+  type DispatchResult,
+  type RunStore,
+  type RunnerInputs,
+  type SchedulerDeps,
+  type WfRunState,
+  NamedLockTimeoutError,
+  NamedLockCompromisedError,
+  type CodexHooksSyncReport,
+  type ParityCell,
+  type ParityFeature,
+  type ParityReportCell,
+  type RuntimeCapability,
   POLICY_SOURCES,
   detectPolicyDrift,
   hasPolicyFence,
   TARGET_NAMES,
   buildParityMatrix,
+  downgradeForStaleEvidence,
+  findStaleTranscriptEvidence,
   TARGET_CAPABILITIES,
   TARGET_SHORT_LABELS,
   WORKFLOW_TEMPLATES_RETIRED_MESSAGE,
@@ -331,6 +356,24 @@ import {
   renderDomainBoostNote,
   renderDomainCutNote,
   parseReqeDebt,
+  // qe-bridge (feature qe-bridge-claude, ADR-001): the pure half of the reverse QE bridge.
+  KNOWN_CLAUDE,
+  isSafeClaudeId,
+  claudeProbeArgs,
+  claudeReviewArgs,
+  interpretClaudeProbe,
+  modelFamily,
+  buildBridgePrompt,
+  parseBridgeOutput,
+  buildBridgeFailureRecord,
+  buildBridgeSignoffRecord,
+  renderBridgeReport,
+  isSafeSlug,
+  hasUnsafePathChars,
+  hasDotDotSegment,
+  type BridgeFamily,
+  type BridgeFailureReason,
+  type NamedExtract,
   buildReqeBrief,
   settleReqeDebt,
   renderReqeList,
@@ -368,7 +411,7 @@ import { scanGitHub, analyzeRepo, generateReport, deepAnalyze, scanAllSources, S
 const USAGE = `dz - DZ cross-platform harness CLI
 
 Usage:
-  dz init   --target <name> [--skills-dir <dir>] [--project <dir>] [--preset <name>] [--select id,id,...] [--force] [--enrich]
+  dz init   --target <name> [--skills-dir <dir>] [--project <dir>] [--preset <name>] [--select id,id,...] [--force] [--enrich] [--no-hooks] [--no-verify]   (--target codex ALSO installs the user-global dz veto+recall hooks and LIVE-verifies them (ADR-001 §8); --no-hooks = skills only; --no-verify skips the live probe and can never report ready)
   dz verify [--skills-dir <dir>] [--target <name>]
   dz sync   [--canonical <dir>] [--project <dir>] [--dry-run] [--force]
   dz update   (alias of sync)
@@ -403,6 +446,7 @@ Usage:
   dz epoch-replay --score <judgments.json> --work-order <file> [--slice <name>] [--json]   (un-blind against the pre-registered assignment → SUPPORTED only when the two 95% Wilson CIs are DISJOINT, else FALSIFIED / INCONCLUSIVE)
   dz score --slug <feature> [--project <dir>] [--json]   (process scorecard for ONE feature-adr run, from its artifacts: ADR confirmation, discrimination, cross-model QE grade, live verification, README-first, learning loop, amendments — descriptive-only, a low score exits 0)
   dz reqe [--slug <feature> [--done --report <f>]] [--json]   (the re-QE debt ledger: a usage-switched run whose Step-8 QE ran on the coder's OWN family records a debt; list debts, print the cross-family review brief, settle FAIL-CLOSED against a graded report — the settlement lands in 08_qe_report.md)
+  dz qe-bridge --family claude --slug <feature> [--coder-family codex|claude] [--model <id>] [--files a,b] [--out <f>] [--timeout <s>] [--allow-same-family] [--json]   (the REVERSE QE bridge: run an INDEPENDENT Claude reviewer over a feature's Step-8 artifacts from ANY host — a Codex session included, plain shell, no Claude agent plane needed — and land a PARSED signoff. The reviewer runs ISOLATED: an EMPTY temp cwd plus --safe-mode --strict-mcp-config --tools '' --no-session-persistence, so no CLAUDE.md/skills/plugins/hooks/MCP load, and the verdict is read from the --output-format json RESULT ENVELOPE — text a session customization printed onto the same stdout can never become a signoff. Probes the model before trusting it; sends SCOPED extracts with a loud 200k-char ceiling (never silent truncation); the grade must AGREE across three LAST-anchored channels (terminal marker line, fenced qe-bridge-signoff JSON, the report's own GRADE line) AND the marker must be the FINAL content — empty, gradeless, self-contradicting or miscounted output is one of 18 NAMED failures with an audit record under features/<slug>/.fa-state/qe-bridge/ (runId, resolved executable + binOverride, prompt sha256, channel offsets, requestedOut, reportWritten, retained raw stdout; 0600 files in a 0700 dir), never a clean review. A --coder-family that contradicts the recorded reqe debt is refused. Writes features/<slug>/08b_reqe_report.md, which dz reqe --done settles unchanged. DISCLOSURE: the extracts you scope are sent to the Claude runtime; the bridge cannot classify secrets. DZ_QE_BRIDGE_CLAUDE_BIN is a TEST SEAM, not a flag. exit 0 signoff parsed (ANY grade — it reports, it does not gate) / 1 named failure / 2 usage)
   dz mutation-gate [--package <dir>] [--registry <file>] [--test-cmd "<cmd>"] [--only <id[,id]>] [--timeout <ms>] [--rebaseline per-entry|final] [--keep-scratch] [--json]   (prove each NAMED protection has a test that DISCRIMINATES: copy the package to a scratch dir, verify the baseline suite is green, apply each registry mutation, run the suite, REQUIRE red, restore. The red must be BEHAVIOURAL: a mutation that no longer parses is MUTATION_UNPARSEABLE; a red run whose OWN output reports a test FILE failing to load (node --test file-level not-ok with exitCode, vitest Failed Suites) is MUTATION_LOAD_FATAL — the signal comes from the same run as the failing count, never from a separate isolated import; red output whose shape matches no known runner is INCONCLUSIVE (a runner-coverage gap, loud, never PROVEN); a count far above the entry's bound is OVER_FAILING; a restored tree that does not reproduce green makes the entry INCONCLUSIVE (flaky). Mutation writes are realpath-contained to the scratch copy: a symlink escape or a node_modules/ target is refused (exit 2), the real tree is never written. A mutation that does not apply, a green suite, or an inconclusive run is a FAILURE — never a skip. exit 0 all proven / 1 gate failed / 2 setup error)
   dz backlog add "<idea>" [--effort 1-5] [--proposal <text>] [--dry-run] [--project <dir>] [--json]   (capture an idea: semantic dedup against existing ideas via the Brain vector engine (DUPLICATE>=0.92 merges, RELATED links, NEW creates) + GoalMap alignment; --dry-run classifies without writing)
   dz backlog list [--status <s>] [--goal <id>] [--project <dir>] [--json]   (list captured ideas, filterable by status/goal)
@@ -417,7 +461,7 @@ Usage:
   dz backlog enrich <id> [--project <dir>] [--json]                        (stage the idea2prd input scaffold in features/<slug>/ and hand off to the idea2prd-manual skill — the CLI never fabricates a PRD)
   dz backlog jira <id> [--project <dir>] [--json]                          (draft a Jira issue via the configurable adapter (backlog.jira.adapter: jira-mcp|copilot-mcp|none); none writes an auditable jira-outbox/<id>.json stub)
   dz backlog harmonize [--apply] [--threshold <0-1>] [--project <dir>] [--json]   (batch semantic dedup of the backlog ideas; --dry-run default, --apply snapshots first)
-  dz setup --target <name> [--preset <name>] [--select id,id,...] [--skills-dir <dir>] [--project <dir>] [--memory agentdb] [--no-memory] [--no-hooks] [--install-driver] [--force] [--enrich]
+  dz setup --target <name> [--preset <name>] [--select id,id,...] [--skills-dir <dir>] [--project <dir>] [--memory agentdb] [--no-memory] [--no-hooks] [--no-verify] [--install-driver] [--force] [--enrich]   (--target codex ALSO installs + LIVE-verifies the codex hooks; an unverified hook exits non-zero WITHOUT aborting the rest of setup)
   dz teach "<pattern>" [--reward <0-1>] [--domain <name>] [--type rule|success-pattern|lesson-learned] [--project <dir>] [--no-mirror]   (--project pins the learned store to <dir>/.dz, not the cwd — pin to a canonical brain)
   dz teach --from-json <file> [--project <dir>] [--no-mirror]   (bulk-import a 'dz recall --all --json' export — share a learned store across machines)
   dz consolidate [--sessions-dir <dir>] [--project <dir>] [--no-mirror] [--prune-noise [--apply]] [--prune-quarantine [--apply]]   (both prunes: DRY-RUN by default; --apply snapshots then deletes; prune-quarantine = expired unproven lessons ONLY, never coupled to noise)
@@ -467,6 +511,18 @@ Usage:
 
 Global: --version | -v [--json]   (prints this CLI's own semver on one line, exit 0; "unknown" + exit 1 when unresolvable)
 
+  dz workflow run <plan.json> [--run-id <id>] [--resume <runId>] [--arg k=v]... [--coder-family codex|claude]
+              [--default-family codex|claude] [--budget <n>] [--max-wall-clock <s>] [--stage-timeout <s>]
+              [--budget-extra <n>] [--wall-clock-extra <s>] [--run-dir <dir>] [--allow-same-family-qe] [--json]
+              (INTERPRET a loop-plan/1 plan host-independently; writes trace/budget/checkpoints under .dz/loop-trace/<runId>/)
+
+EXIT CODES - "workflow run" and "workflow-lint" have DIFFERENT tables, side by side:
+  run   0 completed | 1 failed (named reason) | 2 usage/invalid plan | 75 typed pause (sysexits EX_TEMPFAIL)
+  lint  0 clean     | 1 findings              | 3 inconclusive
+  75 is NOT 3: 3 reads ignorable and collides with lint's inconclusive, while a pause strands resumable work.
+  On a pause the LAST stdout line is a "wf-pause-envelope/1" JSON object; a FAILURE emits none, so a wrapper
+  tells the two apart from stdout + exit code alone, without parsing prose.
+
 Workflows: author loop-plan/1 plans with dz workflow init/validate/render; gate them with dz workflow-lint; read runs with dz workflow-trace (the ADR-005 templates are retired)
 
 Targets: ${TARGET_NAMES.join(', ')}
@@ -730,6 +786,19 @@ async function cmdInit(options: Map<string, string>, flags: Set<string>, cwd: st
     write(`  (searched ${r.dirsSearched} skill directories)`);
   }
   writeMissingSkillsHint(write, r.missing, presetName);
+
+  // Codex-targeted init DELIVERS the hooks and verifies them (ADR-001 §8). Skills alone are not the
+  // target's harness: the veto + recall legs are what `--target codex` promises.
+  // `--no-hooks` is the documented escape for "skills only" (the same flag `dz setup` already
+  // carries): hook delivery writes USER-GLOBAL config, so a command that only wants skills compiled
+  // must be able to say so — and every test that is about skills says it.
+  let codexHooksOk = true;
+  if (target === 'codex' && !flags.has('no-hooks')) {
+    const delivery = deliverCodexHooks({ project: projectRoot, verify: !flags.has('no-verify') }, undefined, 'dz init');
+    codexHooksOk = delivery.ok;
+    for (const line of delivery.stdout) write(line);
+    for (const line of delivery.stderr) writeErr(line);
+  }
   // Skip-and-collect must not become skip-and-SILENCE: a skill that failed to load is
   // named on stderr and the command exits 1 (it exited 1 before too — by throwing).
   if (r.failures.length > 0 || r.applyFailures.length > 0) {
@@ -748,7 +817,7 @@ async function cmdInit(options: Map<string, string>, flags: Set<string>, cwd: st
     for (const line of formatSkillApplyFailures(r.applyFailures)) writeErr(line);
     return 1;
   }
-  return 0;
+  return codexHooksOk ? 0 : 1;
 }
 
 async function cmdVerify(options: Map<string, string>, cwd: string, write: Write, writeErr: WriteErr): Promise<number> {
@@ -4087,6 +4156,17 @@ async function cmdSetup(options: Map<string, string>, flags: Set<string>, cwd: s
     write(`║     (no skills resolved)                              ║`);
   }
 
+  // Step 5 (ADR-001 §8): DELIVER the codex hooks and verify them live. Non-aborting — the rest of
+  // setup has already run and the summary still prints; only the exit code carries the failure.
+  let codexHooksOk = true;
+  if (target === 'codex' && !flags.has('no-hooks')) {
+    write(`║  5. Delivering codex hooks (live verify)...           ║`);
+    const delivery = deliverCodexHooks({ project: projectRoot, verify: !flags.has('no-verify') }, undefined, 'dz setup');
+    codexHooksOk = delivery.ok;
+    for (const line of delivery.stdout) write(line);
+    for (const line of delivery.stderr) writeErr(line);
+  }
+
   write(`╠══════════════════════════════════════════════════════╣`);
   write(`║  Setup: ${String(setupResult.completed).padStart(2)} done, ${String(setupResult.skipped).padStart(2)} skipped                     ║`);
   // Honest label derived from the ACTUAL wiring (runSetup's 'agentdb wiring' invariant check),
@@ -4106,7 +4186,9 @@ async function cmdSetup(options: Map<string, string>, flags: Set<string>, cwd: s
       + (install.dirsSearched > 1 ? `  (searched ${install.dirsSearched} skill dirs)` : ''));
     writeMissingSkillsHint(write, install.missing, selectArg !== undefined ? undefined : preset);
   }
-  return 0;
+  // A hook that was written but never witnessed firing is NOT a completed setup (ADR-002 §5): the
+  // step is reported failed, the process was not aborted.
+  return codexHooksOk ? 0 : 1;
 }
 
 function cmdPretrain(options: Map<string, string>, cwd: string, write: Write): number {
@@ -4841,6 +4923,20 @@ function cmdParity(options: Map<string, string>, flags: Set<string>, write: Writ
   }
 
   const matrix = buildParityMatrix();
+  // EVIDENCE staleness, folded into the report (fix round 2, R2-3). Derived from the records
+  // themselves — no `codex --version`, no subprocess, so `dz parity` stays a deterministic function
+  // of the model. A cell whose deciding form rests on a transcript that is older than the newest
+  // recording for the SAME target is reported `inconclusive`, never `full`: the round-1 gate could
+  // already tell, and nothing a user runs was asking it.
+  const staleEvidence = findStaleTranscriptEvidence();
+  const staleByTarget = new Map<string, RuntimeCapability[]>();
+  for (const s of staleEvidence) staleByTarget.set(s.target, [...(staleByTarget.get(s.target) ?? []), s.capability]);
+  const reportCell = (feature: ParityFeature, t: TargetName, cell: ParityCell): ParityReportCell =>
+    downgradeForStaleEvidence(feature, cell, staleByTarget.get(t) ?? []);
+  const staleNote = (t: TargetName): string[] =>
+    staleEvidence
+      .filter((s) => s.target === t)
+      .map((s) => `  ⚠ ${s.capability}: evidence recorded on ${s.recordedVersion ?? '(no runtime version recorded)'}, newest recording for this target is ${s.probedVersion ?? '(none)'} — INCONCLUSIVE until re-probed (${s.evidence ?? ''})`);
   // Site 8 of the D3 rewiring, closed in fix round 1 (QE F1). It shipped spelling its
   // own bare guard `TARGET_NAMES.includes(...)` and was therefore invisible to the AM-2
   // grep-guard, which searched for the token `isTargetName(` — a PRESENCE check on one
@@ -4866,14 +4962,22 @@ function cmdParity(options: Map<string, string>, flags: Set<string>, write: Writ
   }
 
   if (json) {
-    const rows = matrix.map((r) => ({
-      id: r.feature.id,
-      title: r.feature.title,
-      cells: target !== undefined ? { [target]: r.cells[target] } : r.cells,
-    }));
+    const shown = target !== undefined ? [target] : TARGET_NAMES;
+    const rows = matrix.map((r) => {
+      const cells: Record<string, ParityReportCell> = {};
+      for (const t of shown) cells[t] = reportCell(r.feature, t, r.cells[t]);
+      return { id: r.feature.id, title: r.feature.title, cells };
+    });
     // A filtered response stays internally consistent: capabilities are filtered too (Codex QE gap 9).
     const caps = target !== undefined ? { [target]: TARGET_CAPABILITIES[target] } : TARGET_CAPABILITIES;
-    write(JSON.stringify({ targets: target !== undefined ? [target] : TARGET_NAMES, capabilities: caps, features: rows }, null, 2));
+    write(JSON.stringify({
+      targets: shown,
+      capabilities: caps,
+      // The evidence axis travels WITH the matrix: a consumer that reads `level` must be able to
+      // read why a cell is inconclusive without a second command.
+      staleEvidence: staleEvidence.filter((sv) => shown.includes(sv.target)),
+      features: rows,
+    }, null, 2));
     return 0;
   }
 
@@ -4881,11 +4985,17 @@ function cmdParity(options: Map<string, string>, flags: Set<string>, write: Writ
     const t = target;
     write(`\ndz parity — ${t}  (capabilities: ${TARGET_CAPABILITIES[t].join(', ')})\n`);
     for (const r of matrix) {
-      const c = r.cells[t];
-      const icon = c.level === 'full' ? '✓' : c.level === 'manual' ? '◐' : '—';
-      write(`  ${icon} ${r.feature.title.padEnd(58)} ${c.level === 'none' ? 'not available on this target' : `via ${c.via ?? ''}`}`);
-    }
-    write('\n  ✓ full (the complete experience)   ◐ manual (works, you drive it by hand)   — not available');
+      const c = reportCell(r.feature, t, r.cells[t]);
+      const icon = c.level === 'full' ? '✓' : c.level === 'manual' ? '◐' : c.level === 'inconclusive' ? '?' : '—';
+      const detail = c.level === 'none'
+        ? 'not available on this target'
+        : c.level === 'inconclusive'
+          ? `via ${c.via ?? ''} — INCONCLUSIVE: stale evidence for ${(c.staleEvidence ?? []).join(', ')}`
+          : `via ${c.via ?? ''}`;
+      write(`  ${icon} ${r.feature.title.padEnd(58)} ${detail}`);
+    }
+    write('\n  ✓ full (the complete experience)   ◐ manual (works, you drive it by hand)   ? evidence stale (re-probe)   — not available');
+    for (const line of staleNote(t)) write(line);
     return 0;
   }
 
@@ -4896,8 +5006,8 @@ function cmdParity(options: Map<string, string>, flags: Set<string>, write: Writ
   write(`  ${'feature'.padEnd(52)} ${TARGET_NAMES.map((t) => (short[t] ?? t).padStart(4)).join('')}`);
   for (const r of matrix) {
     const cells = TARGET_NAMES.map((t) => {
-      const c = r.cells[t];
-      return (c.level === 'full' ? '✓' : c.level === 'manual' ? '◐' : '—').padStart(4);
+      const c = reportCell(r.feature, t, r.cells[t]);
+      return (c.level === 'full' ? '✓' : c.level === 'manual' ? '◐' : c.level === 'inconclusive' ? '?' : '—').padStart(4);
     }).join('');
     write(`  ${r.feature.title.slice(0, 52).padEnd(52)} ${cells}`);
   }
@@ -5911,11 +6021,18 @@ function cmdHooksSync(
   }
 
   const codexHome = options.get('codex-home');
-  const report = runSyncCodexHooks({
-    ...(codexHome !== undefined ? { codexHome } : {}),
-    check: flags.has('check'),
-    remove: flags.has('remove'),
-  });
+  const projectOpt = options.get('project');
+  // `--no-verify` wins over `--verify`: an explicit refusal to measure is never overridden by the
+  // flag that asks for a measurement.
+  const report = runSyncCodexHooksGuarded(
+    codexHooksSyncOptions({
+      ...(codexHome !== undefined ? { codexHome } : {}),
+      ...(projectOpt !== undefined ? { project: resolve(cwd, projectOpt) } : {}),
+      check: flags.has('check'),
+      remove: flags.has('remove'),
+      verify: !flags.has('no-verify'),
+    }),
+  );
 
   if (json) {
     write(JSON.stringify({ ...report, exitCode: report.exitCode }));
@@ -5934,18 +6051,193 @@ function cmdHooksSync(
     return report.exitCode;
   }
 
-  // AM-17 / G-G: the success word is reachable ONLY from armed AND trusted. The trust clause is
-  // asserted HERE as well as in the exit map — a read-only `--check` that could not establish trust
-  // once returned exit 0 with `trust: 'unknown'`, and this line printed "ready" for it.
-  if (report.exitCode === 0 && report.trust === 'trusted' && report.installed) {
-    write(`dz hooks-sync: codex hooks installed and ARMED (trust: ${report.trust}) — ready`);
-  } else if (report.installed) {
-    writeErr(`dz hooks-sync: installed, NOT verified — ARMED = NO (trust: ${report.trust}, executable: ${report.executable})`);
-    writeErr('→ open an interactive Codex session in this directory and approve the two dz hooks, then re-run with --verify');
+  // AM-17 / G-G: the success word is reachable ONLY from `report.ready` — armed AND trusted AND
+  // WITNESSED blocking by a live, non-bypassed probe. The pre-fix version printed it off
+  // `exitCode === 0 && trust && installed`, none of which is evidence that the guard fires.
+  const summary = codexHooksSummary(report);
+  for (const line of summary.stdout) write(line);
+  for (const line of summary.stderr) writeErr(line);
+  return report.exitCode;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Codex hook DELIVERY — one implementation, three call sites                  */
+/* -------------------------------------------------------------------------- */
+
+export interface CodexHooksSyncInput {
+  readonly codexHome?: string | undefined;
+  readonly project?: string | undefined;
+  readonly check?: boolean;
+  readonly remove?: boolean;
+  /** `false` = the user's `--no-verify`. Anything else runs the live probe. */
+  readonly verify?: boolean;
+}
+
+/**
+ * The argv → operation mapping, extracted so it can be PINNED.
+ *
+ * It is the mapping that was broken: `--verify`, `--no-verify` and `--project` were parsed,
+ * validated, listed in the usage line — and then never reached `runSyncCodexHooks`, so the CRITICAL
+ * finding (a `ready` with no live proof behind it) lived entirely in three missing object keys.
+ * A function that returns the options object is testable without a codex binary; an inline literal
+ * is not.
+ */
+export function codexHooksSyncOptions(input: CodexHooksSyncInput): Parameters<typeof runSyncCodexHooks>[0] {
+  return {
+    ...(input.codexHome !== undefined ? { codexHome: input.codexHome } : {}),
+    ...(input.project !== undefined ? { project: input.project } : {}),
+    check: input.check === true,
+    remove: input.remove === true,
+    verify: input.verify !== false,
+  };
+}
+
+export interface CodexHooksSummary {
+  readonly ok: boolean;
+  readonly stdout: readonly string[];
+  readonly stderr: readonly string[];
+}
+
+/**
+ * What the user is told about a sync report — the ONE place the success word can be printed.
+ *
+ * `report.ready` is the whole gate: installed ∧ executable ∧ trusted ∧ a live, non-bypassed probe
+ * that WITNESSED our block. Nothing else may print "ready" (AM-17 / G-G), and `--no-verify` never
+ * can, because it never measured.
+ */
+export function codexHooksSummary(report: CodexHooksSyncReport, label = 'dz hooks-sync'): CodexHooksSummary {
+  const stdout: string[] = [];
+  const stderr: string[] = [];
+  if (report.ready) {
+    stdout.push(`${label}: codex hooks installed and ARMED (trust: ${report.trust}) — VERIFIED by a live veto probe — ready`);
+    return { ok: true, stdout, stderr };
+  }
+  if (report.installed) {
+    const verdict = report.verify === null ? 'not verified (no live probe ran)' : `${report.verify.verdict} — ${report.verify.reason}`;
+    // Say what the report ESTABLISHED, not a hopeful summary of it: `installed+trusted` used to
+    // print verbatim even when the same line went on to report `trust: unknown` (the re-QE's
+    // non-closure note). A message that argues with its own parenthesis teaches the reader to skip
+    // the parenthesis.
+    const established = report.trust === 'trusted' ? 'installed+trusted' : `installed, trust ${report.trust}`;
+    stderr.push(`${label}: ${established}, NOT verified — ARMED = NO (trust: ${report.trust}, executable: ${report.executable}, verify: ${verdict})`);
+    stderr.push('→ open an interactive Codex session in this directory, approve the two dz hooks, then re-run `dz hooks-sync --target codex --verify`');
   } else {
-    writeErr('dz hooks-sync: ARMED = NO — the managed entries are not present in the registry');
+    stderr.push(`${label}: ARMED = NO — the managed entries are not present in the registry`);
   }
-  return report.exitCode;
+  return { ok: false, stdout, stderr };
+}
+
+/**
+ * ADR-001 §8: `dz setup` and `dz init --target codex` DELIVER the hooks and verify them.
+ *
+ * Non-aborting by contract (ADR-002 D6): the caller keeps going and folds `ok` into its own exit
+ * code. Before this round no production path called `runSyncCodexHooks` at all — the operation, its
+ * classifier and its exit map existed and were reachable only from the dedicated command
+ * (independent review, finding 2).
+ */
+/**
+ * Serialize dz's own `hooks.json` read-merge-write behind the `codex-hooks` named lock
+ * (feature qe-bridge-claude, ADR-001 D4-A — the exit condition of the accepted degradation in
+ * `architecture/degradations.md`).
+ *
+ * The lock lives BESIDE the registry it guards (`$CODEX_HOME/.dz/locks/codex-hooks.lock`), not in
+ * this repo: two dz processes running from two different worktrees share a `CODEX_HOME`, not a
+ * project root, so a lock under the project would serialize nothing.
+ *
+ * READ-ONLY runs (`--check`) are NOT locked: they write nothing, and a check that can be blocked by
+ * a writer would be a new failure mode in exchange for no guarantee.
+ *
+ * HONEST LIMIT: this is an ADVISORY lock. It serializes dz-side writers only; a foreign installer
+ * (ruvnet-brain ships its own Codex hooks bundle) never takes it. For that case the pre-existing
+ * mitigations remain the backstop — foreign entries preserved byte-for-byte, a timestamped backup
+ * before every modifying write, and atomic temp+rename so no reader sees a partial file.
+ */
+function runSyncCodexHooksLocked(options: Parameters<typeof runSyncCodexHooks>[0] = {}): CodexHooksSyncReport {
+  if (options?.check === true) return runSyncCodexHooks(options);
+  const codexHome = resolveCodexHome(options?.codexHome);
+  // AM-35a is a SHIPPED property with a test: a run that refuses (no `codex` on PATH) must leave
+  // CODEX_HOME untouched — dz does not create user-global state for a runtime that is not there.
+  // Taking the lock creates `<codexHome>/.dz/locks/`, so when the guarded operation turned out to
+  // write nothing, the lock scaffolding is removed again (empty-dir removals only: a directory that
+  // still holds another process's live lock simply refuses to go).
+  const preexisting = existsSync(join(codexHome, '.dz'));
+  const tidyLockScaffold = (report: CodexHooksSyncReport): void => {
+    if (preexisting || report.written || report.writes.length > 0) return;
+    for (const dir of [join(codexHome, '.dz', 'locks'), join(codexHome, '.dz')]) {
+      try {
+        rmdirSync(dir);
+      } catch { /* non-empty (someone else's lock) or gone — leave it */ }
+    }
+  };
+  // ROUND-2 C2: the lock now wraps ONLY the registry read-plan-write transaction, passed in as the
+  // operation's `criticalSection` seam. It used to wrap the WHOLE operation, including a live veto
+  // probe that can block for ~300s — ten times the 30s stale threshold, after which a waiter is
+  // entitled to break the lock and the holder is no longer excluding anyone. The probes mutate
+  // nothing shared, so they run unlocked by design.
+  let lockError: Error | null = null;
+  const report = runSyncCodexHooks({
+    ...options,
+    criticalSection: <T>(fn: () => T): T => {
+      try {
+        return withNamedLockSync(codexHome, 'codex-hooks', fn);
+      } catch (error) {
+        if (error instanceof NamedLockTimeoutError || error instanceof NamedLockCompromisedError) {
+          lockError = error;
+          throw error;
+        }
+        throw error;
+      }
+    },
+  });
+  tidyLockScaffold(report);
+  if (lockError !== null) throw lockError;
+  return report;
+}
+
+/** Wrap the delivery so a lock refusal becomes a REPORT (loud, nothing written), not a stack trace. */
+function runSyncCodexHooksGuarded(options: Parameters<typeof runSyncCodexHooks>[0] = {}): CodexHooksSyncReport {
+  const codexHome = resolveCodexHome(options?.codexHome);
+  try {
+    return runSyncCodexHooksLocked(options);
+  } catch (error) {
+    if (error instanceof NamedLockTimeoutError || error instanceof NamedLockCompromisedError) {
+      const why = error instanceof NamedLockTimeoutError
+        ? `another dz process is writing ${join(codexHome, 'hooks.json')} (${error.message}) — NOTHING was written; retry once it finishes`
+        : `the codex-hooks lock was broken while this run held it (${error.message}) — the registry write may have raced; re-run and re-verify`;
+      return {
+        codexHome,
+        registryPath: join(codexHome, 'hooks.json'),
+        installed: false,
+        executable: false,
+        written: false,
+        removed: 0,
+        foreignPreserved: 0,
+        unattributable: 0,
+        drift: [],
+        trust: 'unknown',
+        codexVersion: null,
+        writes: [],
+        verify: null,
+        verified: false,
+        ready: false,
+        exitCode: 1,
+        warnings: [],
+        errors: [why],
+      };
+    }
+    throw error;
+  }
+}
+
+export function deliverCodexHooks(
+  input: CodexHooksSyncInput,
+  sync: (options: Parameters<typeof runSyncCodexHooks>[0]) => CodexHooksSyncReport = runSyncCodexHooksGuarded,
+  label = 'dz setup',
+): CodexHooksSummary & { readonly report: CodexHooksSyncReport } {
+  const report = sync(codexHooksSyncOptions(input));
+  const summary = codexHooksSummary(report, label);
+  const stderr = [...report.errors.map((e) => `${label}: ${e}`), ...report.warnings.map((w) => `${label}: warning: ${w}`), ...summary.stderr];
+  return { ok: summary.ok, stdout: summary.stdout, stderr, report };
 }
 
 function cmdAgentsSync(
@@ -7939,16 +8231,599 @@ function cmdMutationGate(options: Map<string, string>, flags: Set<string>, cwd:
  * debt); an oversized or non-regular due-file counts as MALFORMED, never a silent skip (QE #8);
  * a debt whose embedded slug differs from its directory is MALFORMED — identity is the directory,
  * the JSON only confirms it (QE #4: an embedded foreign slug must not redirect settlement). */
+/* ── `dz workflow run` — the impure half of the loop-plan executor (feature dz-workflow-run) ──────
+ *
+ * Everything DECIDABLE lives in harness-core's pure scheduler. This half owns exactly four things
+ * core refuses to touch: the filesystem, the lock, the child processes, and the exit code. Keeping
+ * that line sharp is what lets the whole feature be tested without a child process — so anything
+ * added here that could have been a decision belongs upstream instead.
+ */
+
+/** The env TEST SEAM (the `DZ_QE_BRIDGE_CLAUDE_BIN` precedent: an env var, never a flag — a flag
+ * invites production use). Recorded LOUDLY in run-state as `dispatcherOverride: true`, because a
+ * test seam that leaves no trace in the artifact is indistinguishable from a real run. */
+const WF_RUN_DISPATCH_SCRIPT_ENV = 'DZ_WF_RUN_DISPATCH_SCRIPT';
+const WF_RUN_OWNER_FILE = 'run-owner.json';
+const WF_RUN_STATE_FILE = 'run-state.json';
+
+/**
+ * THE ONE PLACE anything in the loop runner is signalled (Step-8 re-QE NEW-C4).
+ *
+ * Round 1 guarded `process.kill(-pid, …)` — the process-GROUP path — and left `child.kill(sig)`
+ * unguarded beside it. A fake child reporting `pid: 0` therefore still received the signal through
+ * the object method, which is the same defect wearing a different call shape. `process.kill(-0, …)`
+ * signals the CALLER'S OWN process group; round 0 of this exact class took down the vitest worker
+ * pool. Two call shapes meant two chances to forget, so now there is one.
+ *
+ * The guard is on the PID, not on the shape: an unsignalable pid (not an integer, or <= 1) reaches
+ * NOTHING — neither `process.kill` nor `child.kill`. Returns whether a signal was actually sent, so
+ * a caller can never mistake "refused" for "delivered".
+ */
+function signalChildSafely(child: { pid?: unknown; kill?: (signal: NodeJS.Signals) => unknown } | undefined, signal: NodeJS.Signals, detached: boolean): boolean {
+  const raw = child?.pid;
+  if (typeof raw !== 'number' || !Number.isInteger(raw) || raw <= 1) return false;
+  try {
+    if (detached) process.kill(-raw, signal);
+    else child?.kill?.(signal);
+    return true;
+  } catch {
+    return false; // already gone, or not ours — both mean nothing more to do
+  }
+}
+
+/** Test seam for the chokepoint: NEW-C4's proof needs to call it with a hostile pid. */
+export function __wfSignalChildTestSeam(child: unknown, signal: string, detached: boolean): boolean {
+  return signalChildSafely(child as { pid?: unknown; kill?: (s: NodeJS.Signals) => unknown }, signal as NodeJS.Signals, detached);
+}
+
+/** Live children, keyed by pid, for the kill-group handlers (AM-10). */
+const wfLiveChildren = new Map<number, ChildProcess>();
+let wfHandlersInstalled = false;
+
+/** Kill the process GROUP of every live child. A detached child leads its own group, so killing the
+ * leader alone would leave whatever it spawned running — that is the orphan class AM-10 closes.
+ * NAMED RESIDUE: a SIGKILL of the runner itself runs no handler, so that case still orphans. */
+function wfKillLiveChildren(signal: NodeJS.Signals = 'SIGTERM'): number[] {
+  const killed: number[] = [];
+  for (const [pid, child] of [...wfLiveChildren.entries()]) {
+    // ONE chokepoint: group first (a detached child leads its own), then the leader. Neither shape
+    // is reachable without the pid guard.
+    if (signalChildSafely(child, signal, true) || signalChildSafely(child, signal, false)) killed.push(pid);
+    wfLiveChildren.delete(pid);
+  }
+  return killed;
+}
+
+function wfInstallKillHandlers(): void {
+  if (wfHandlersInstalled) return;
+  wfHandlersInstalled = true;
+  process.on('exit', () => { wfKillLiveChildren(); });
+  process.on('SIGTERM', () => { wfKillLiveChildren(); process.exit(143); });
+  process.on('SIGINT', () => { wfKillLiveChildren(); process.exit(130); });
+}
+
+/** Exposed for the unit test: the kill set must NAME every live child's pid. */
+export function __wfKillGroupTestSeam(): { register: (pid: number, child: ChildProcess) => void; killAll: () => number[]; size: () => number } {
+  return {
+    register: (pid, child) => { wfLiveChildren.set(pid, child); },
+    killAll: () => wfKillLiveChildren(),
+    size: () => wfLiveChildren.size,
+  };
+}
+
+/** A `ChildRunner` over the generalized wrapper, registering every live child for the kill set. */
+/** A `ChildRunner` bound to ONE family, so its child can only ever receive that family's
+ * credentials (re-QE H9). Two runners, two credential sets, one wrapper. */
+const wfChildRunnerFor = (family: BridgeFamily): ChildRunner => async (bin, argv, opts) =>
+  runChildBridge(bin, argv, {
+    ...opts,
+    // a dispatched model gets a NAMED minimal environment, never the runner's whole one (HIGH-9)
+    envMode: 'allowlist',
+    envExtra: CHILD_ENV_BY_FAMILY[family],
+    onSpawn: (child) => {
+      if (typeof child.pid !== 'number') return;
+      const pid = child.pid;
+      wfLiveChildren.set(pid, child);
+      child.on('close', () => { wfLiveChildren.delete(pid); });
+    },
+  });
+
+/** Build the SCRIPTED dispatcher from the env seam's JSON file (test-only). */
+function wfScriptedDispatcher(scriptPath: string, family: BridgeFamily): Dispatcher {
+  const raw = JSON.parse(readFileSync(scriptPath, 'utf8')) as Record<string, unknown>;
+  const script = (raw['steps'] ?? raw) as Record<string, unknown>;
+  const probeId = typeof raw['probeId'] === 'string' ? (raw['probeId'] as string) : `${family}-scripted`;
+  const consumed = new Map<string, number>();
+  return {
+    probe: async (candidates) => ({ id: raw['probeFails'] === true ? null : probeId, wallMs: 1, detail: `scripted probe (${candidates.join(',') || 'defaults'})` }),
+    dispatch: async (req) => {
+      const key = req.itemKey === null ? req.stepId : `${req.stepId}:${req.itemKey}`;
+      const entry = script[key] ?? script[req.stepId];
+      const n = consumed.get(key) ?? 0;
+      consumed.set(key, n + 1);
+      const picked = Array.isArray(entry) ? (entry[Math.min(n, entry.length - 1)] as Record<string, unknown>) : (entry as Record<string, unknown> | undefined);
+      const base: DispatchResult = {
+        outcome: 'ok',
+        text: `scripted:${key}`,
+        family,
+        modelUsed: req.resolvedModelId,
+        wallMs: 1,
+        tokensIn: null,
+        tokensOut: null,
+        tokensSource: null,
+      };
+      if (picked === undefined || picked === null) return base;
+      // a scripted step may ask the runner to CREATE its declared writes (the landed-barrier leg)
+      if (picked['writes'] === true) {
+        for (const rel of req.expectedWrites) {
+          // the seam re-checks containment too — a test double that could write outside the root
+          // would be a hole in exactly the guard the real path is being tested for (CRITICAL-4)
+          const abs = wfContainedPath(req.cwd, rel);
+          if (abs === null) continue;
+          mkdirSync(dirname(abs), { recursive: true });
+          writeFileSync(abs, `scripted write for ${req.stepId} attempt ${req.attempt}\n`);
+        }
+      }
+      return { ...base, ...(picked as Partial<DispatchResult>) };
+    },
+  };
+}
+
+/** Read a small JSON file, or null. */
+function wfReadJson(path: string): unknown {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Is a recorded pid still alive? `kill(pid, 0)` is the portable liveness probe. */
+function wfPidAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return (e as NodeJS.ErrnoException).code === 'EPERM'; // alive, just not ours
+  }
+}
+
+/** The fs `RunStore`. Every write that must be atomic is temp+rename; every file that must be NEW
+ * is `wx`. Nothing here decides anything. */
+/**
+ * Containment, re-checked at the LAST possible moment (Step-8 CRITICAL-4: "repeat containment
+ * immediately before filesystem access").
+ *
+ * Preflight validated these paths minutes earlier, against a filesystem that has since been written
+ * to — by the very models this run dispatched. A symlink planted between preflight and the probe is
+ * not a hypothetical here; creating files is what the file-deliverable steps DO. Returns the
+ * absolute path, or null when the path no longer resolves inside the root.
+ */
+function wfContainedPath(targetCwd: string, rel: string): string | null {
+  const check = containedUnderRoot(targetCwd, rel);
+  return check.ok ? check.path : null;
+}
+
+function wfMakeStore(runDir: string, repoRoot: string, targetCwd: string): RunStore {
+  const statePath = join(runDir, WF_RUN_STATE_FILE);
+  const tracePath = join(runDir, 'trace.jsonl');
+  const stateDir = join(runDir, '.fa-state');
+  const ckptPath = join(stateDir, 'checkpoints.jsonl');
+  const budgetPath = join(runDir, 'budget.jsonl');
+  const duePath = join(stateDir, 'reqe-due.json');
+  const ledgerPath = join(repoRoot, '.dz', 'feature-adr', 'run-cost-ledger.jsonl');
+  const hashOf = (abs: string): string | null => {
+    try {
+      return createHash('sha256').update(readFileSync(abs)).digest('hex');
+    } catch {
+      return null;
+    }
+  };
+  return {
+    runDirExists: () => existsSync(runDir),
+    hasTrace: () => existsSync(tracePath),
+    readTraceText: () => (existsSync(tracePath) ? readFileSync(tracePath, 'utf8') : null),
+    readRunState: () => wfReadJson(statePath) as WfRunState | null,
+    writeRunState: (s) => {
+      mkdirSync(runDir, { recursive: true });
+      const tmp = statePath + '.tmp';
+      writeFileSync(tmp, JSON.stringify(s, null, 2) + '\n');
+      renameSync(tmp, statePath); // atomic: a half-written state is a foreign run forever
+    },
+    appendTraceLines: (lines) => {
+      if (lines.length === 0) return;
+      mkdirSync(runDir, { recursive: true });
+      appendFileSync(tracePath, lines.join('\n') + '\n');
+    },
+    readCheckpointsText: () => (existsSync(ckptPath) ? readFileSync(ckptPath, 'utf8') : null),
+    appendCheckpointLine: (line) => {
+      mkdirSync(stateDir, { recursive: true });
+      appendFileSync(ckptPath, line + '\n');
+    },
+    appendBudgetRow: (row) => {
+      mkdirSync(runDir, { recursive: true });
+      appendFileSync(budgetPath, JSON.stringify(row) + '\n');
+    },
+    appendLedgerLine: (line) => {
+      try {
+        mkdirSync(dirname(ledgerPath), { recursive: true });
+        appendFileSync(ledgerPath, line + '\n');
+      } catch {
+        /* telemetry is SECONDARY: a ledger failure never fails a run */
+      }
+    },
+    probeArtifact: (rel) => {
+      const abs = wfContainedPath(targetCwd, rel);
+      // a path that no longer resolves inside the root is NOT LANDED, whatever is at the other end
+      return abs !== null && existsSync(abs);
+    },
+    // re-QE R3-A: the same realpath + symlinked-ancestor discipline, for reads AND writes, at the
+    // moment before the dispatch grants filesystem access
+    pathContainmentOk: (rel) => wfContainedPath(targetCwd, rel) !== null,
+    snapshotWrites: (rels) => {
+      const out: Record<string, string | null> = {};
+      for (const rel of rels) {
+        const abs = wfContainedPath(targetCwd, rel);
+        out[rel] = abs === null ? null : hashOf(abs);
+      }
+      return out;
+    },
+    writeReqeDebt: (record) => {
+      mkdirSync(stateDir, { recursive: true });
+      writeFileSync(duePath, JSON.stringify(record, null, 2) + '\n');
+    },
+  };
+}
+
+/**
+ * `dz workflow run <plan.json>` — INTERPRET the plan (ADR-001). Registered inside the existing
+ * `case 'workflow':` branch when `_positional_0 === 'run'`, BEFORE the sync `cmdWorkflow`.
+ *
+ * Exit codes (AM-11): `0` completed · `1` failed (named) · `2` usage / invalid plan ·
+ * `75` typed pause (sysexits EX_TEMPFAIL). NOT `3`: that collides with workflow-lint's
+ * inconclusive and reads ignorable, while a pause strands resumable progress.
+ */
+async function cmdWorkflowRun(
+  options: Map<string, string>,
+  optionLists: Map<string, string[]>,
+  flags: Set<string>,
+  cwd: string,
+  write: Write,
+): Promise<number> {
+  const json = flags.has('json');
+  const usage = 'dz workflow run <plan.json> [--run-id <id>] [--resume <runId>] [--arg k=v]… '
+    + '[--coder-family codex|claude] [--default-family codex|claude] [--budget <n>] [--max-wall-clock <s>] '
+    + '[--stage-timeout <s>] [--budget-extra <n>] [--wall-clock-extra <s>] [--run-dir <dir>] '
+    + '[--allow-same-family-qe] [--json]';
+  const usageError = (message: string): number => {
+    write(json ? JSON.stringify({ ok: false, reason: 'plan-invalid', error: message, exitCode: 2 }) : `dz workflow run: ${message}\n${usage}`);
+    return 2;
+  };
+
+  if (flags.has('help')) {
+    write(usage);
+    write('');
+    write('EXIT CODES — `dz workflow run` and `dz workflow-lint` have DIFFERENT tables (AM-11):');
+    write('  run   0 completed · 1 failed (named reason) · 2 usage/invalid plan · 75 typed pause (EX_TEMPFAIL)');
+    write('  lint  0 clean     · 1 findings            · 3 inconclusive');
+    write('  75 is NOT 3: 3 reads ignorable and collides with lint, while a pause strands resumable work.');
+    write('On a pause the LAST stdout line is a `wf-pause-envelope/1` JSON object; a FAILURE emits none,');
+    write('so a wrapper can tell the two apart from stdout + exit code alone, without parsing prose.');
+    return 0;
+  }
+
+  // ── closed allowlists (the cmdQeBridge discipline: an unknown flag is a usage error, never a
+  // silently-ignored intention) ──
+  const OPTS = new Set(['run-id', 'resume', 'arg', 'coder-family', 'default-family', 'budget', 'max-wall-clock', 'stage-timeout', 'budget-extra', 'wall-clock-extra', 'run-dir', 'project', '_positional_0', '_positional_1']);
+  const FLAGS = new Set(['allow-same-family-qe', 'json', 'help']);
+  for (const k of options.keys()) if (!OPTS.has(k)) return usageError(`unknown option --${k}`);
+  for (const f of flags) if (!FLAGS.has(f)) return usageError(`unknown flag --${f}`);
+
+  // ── SINGLETONS (Step-8 HIGH-8 — the recurring class) ──
+  //
+  // `parseArgs` keeps every occurrence in `optionLists` but the main map is LAST-WINS, so
+  // `--coder-family codex --coder-family claude` was accepted and only `claude` reached preflight.
+  // For a SAFETY option that is a bypass: the same-family guard compares the coder family against a
+  // qe step's family, and whoever supplies the last occurrence chooses the answer. Every option here
+  // is a singleton BY MEANING — a run has one coder family, one budget, one run directory — so a
+  // second occurrence is not a preference, it is an ambiguity, and the only honest answer is to
+  // refuse. `--arg` is deliberately absent: it is the one genuinely repeatable option.
+  const SINGLETON_OPTS = ['run-id', 'resume', 'coder-family', 'default-family', 'budget', 'max-wall-clock', 'stage-timeout', 'budget-extra', 'wall-clock-extra', 'run-dir', 'project'];
+  for (const key of SINGLETON_OPTS) {
+    const occurrences = optionLists.get(key) ?? [];
+    if (occurrences.length > 1) {
+      return usageError(
+        `--${key} was given ${occurrences.length} times (${occurrences.map((v) => JSON.stringify(v)).join(', ')}) — it is a singleton, and a second occurrence is an ambiguity, not a preference. `
+        + 'Stacking a safety option would let the LAST value decide what the first one refused.',
+      );
+    }
+  }
+
+  const planPath = options.get('_positional_1') ?? '';
+  if (planPath === '') return usageError('a plan.json positional is required');
+  const root = resolve(cwd, options.get('project') ?? '.');
+  const absPlan = resolve(cwd, planPath);
+  if (!existsSync(absPlan)) return usageError(`no such plan file: ${absPlan}`);
+
+  let rawPlan: unknown;
+  try {
+    rawPlan = JSON.parse(readFileSync(absPlan, 'utf8'));
+  } catch (e) {
+    return usageError(`unparseable plan JSON — ${e instanceof Error ? e.message : String(e)}`);
+  }
+  const parsed = parsePlan(rawPlan);
+  if (isParseErrors(parsed)) {
+    if (json) write(JSON.stringify({ ok: false, reason: 'plan-invalid', parseErrors: parsed, exitCode: 2 }));
+    else for (const e of parsed) write(`PARSE ${e.path}: ${e.message}`);
+    return 2;
+  }
+  const diags = validatePlan(parsed);
+  if (diags.length > 0) {
+    if (json) write(JSON.stringify({ ok: false, reason: 'plan-invalid', diagnostics: diags, exitCode: 2 }));
+    else for (const d of diags) write(`${d.invariant} ${d.path}: ${d.message}`);
+    return 2;
+  }
+
+  // ── numeric options ride the Number.isFinite clamp (every numeric config clamp needs it) ──
+  const num = (key: string, scale = 1): { ok: true; value: number | null } | { ok: false; why: string } => {
+    const raw = options.get(key);
+    if (raw === undefined) return { ok: true, value: null };
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0) return { ok: false, why: `--${key} must be a finite non-negative number (got ${JSON.stringify(raw)})` };
+    return { ok: true, value: Math.floor(n * scale) };
+  };
+  const nums: Record<string, number | null> = {};
+  for (const [key, scale] of [['budget', 1], ['max-wall-clock', 1000], ['stage-timeout', 1000], ['budget-extra', 1], ['wall-clock-extra', 1000]] as const) {
+    const r = num(key, scale);
+    if (!r.ok) return usageError(r.why);
+    nums[key] = r.value;
+  }
+
+  const familyOpt = (key: string): { ok: true; value: BridgeFamily | null } | { ok: false; why: string } => {
+    const raw = options.get(key);
+    if (raw === undefined) return { ok: true, value: null };
+    if (raw !== 'codex' && raw !== 'openai' && raw !== 'claude') return { ok: false, why: `--${key} must be codex or claude (got ${JSON.stringify(raw)})` };
+    return { ok: true, value: modelFamily(raw) };
+  };
+  const coder = familyOpt('coder-family');
+  if (!coder.ok) return usageError(coder.why);
+  const dflt = familyOpt('default-family');
+  if (!dflt.ok) return usageError(dflt.why);
+
+  const resumeArgs: Record<string, string> = {};
+  for (const kv of optionLists.get('arg') ?? []) {
+    const eq = kv.indexOf('=');
+    if (eq <= 0) return usageError(`--arg must be k=v (got ${JSON.stringify(kv)})`);
+    resumeArgs[kv.slice(0, eq)] = kv.slice(eq + 1);
+  }
+
+  const resumeId = options.get('resume') ?? null;
+  const runId = options.get('run-id') ?? resumeId ?? `${parsed.name}-${randomBytes(2).toString('hex')}`;
+  if (!TRACE_RUNID_RE.test(runId)) return usageError(`runId ${JSON.stringify(runId)} fails ${String(TRACE_RUNID_RE)}`);
+  if (resumeId !== null && options.get('run-id') !== undefined && options.get('run-id') !== resumeId) {
+    return usageError('--run-id and --resume name different runs — a resume continues the run it names');
+  }
+
+  const runDirOpt = options.get('run-dir');
+  let runDir: string;
+  if (runDirOpt !== undefined) {
+    const contained = containedUnderRoot(root, runDirOpt);
+    if (!contained.ok) return usageError(`--run-dir ${contained.why}`);
+    runDir = contained.path;
+  } else {
+    runDir = join(root, '.dz', 'loop-trace', runId); // the addressing `dz workflow-trace --run <id>` already uses
+  }
+
+  // The scripted-seam marker is established BEFORE the first refusal can emit (re-QE MINOR): an
+  // EARLY refusal is still a run that would have dispatched to no real model, and a reader of that
+  // envelope has the same right to know as a reader of a completed one.
+  const seamScriptPath = process.env[WF_RUN_DISPATCH_SCRIPT_ENV];
+  const dispatcherOverride = typeof seamScriptPath === 'string' && seamScriptPath !== '';
+  const emit = (payload: object): void => {
+    write(JSON.stringify(dispatcherOverride ? { ...payload, dispatcherOverride: true } : payload));
+  };
+
+  // ── AM-7 ownership, ATOMICALLY (Step-8 HIGH-6) ──
+  //
+  // The previous shape read the owner marker, decided, and wrote it later — a window in which two
+  // processes both saw "no live owner" and both proceeded. And the write itself was wrapped in a
+  // swallowing try, so a run could execute while its durable claim silently did not exist.
+  //
+  // Now: check and claim happen INSIDE the named lock, the claim is `wx` (create-or-fail, so the
+  // filesystem itself arbitrates), a STALE marker is only replaced under that same lock, and a
+  // failure to claim FAILS THE RUN. One writer per run is not a convention here; it is an atomic
+  // filesystem operation.
+  const ownerPath = join(runDir, WF_RUN_OWNER_FILE);
+  const startedMarker = new Date().toISOString();
+  const RUN_ARTIFACTS = [WF_RUN_STATE_FILE, 'trace.jsonl', 'budget.jsonl', join('.fa-state', 'checkpoints.jsonl')];
+  type Claim = { ok: true } | { ok: false; reason: 'run-exists' | 'run-locked'; detail: string };
+  const claim: Claim = withNamedLockSync(root, `wf-run-${runId}`, (): Claim => {
+    mkdirSync(runDir, { recursive: true });
+    // ORDER MATTERS. A LIVE owner is `run-locked` whichever kind of invocation this is — that is
+    // the precise fact, and it outranks "the directory has files in it". Only then does a FRESH run
+    // refuse a directory that already holds a run's artifacts.
+    const existingOwner = wfReadJson(ownerPath) as { pid?: number; startedMarker?: string } | null;
+    if (existingOwner !== null && typeof existingOwner.pid === 'number' && wfPidAlive(existingOwner.pid)) {
+      return { ok: false, reason: 'run-locked', detail: `another dz workflow run (pid ${existingOwner.pid}, started ${existingOwner.startedMarker ?? 'unknown'}) owns ${runDir} — ONE writer per run, always` };
+    }
+    if (resumeId === null) {
+      // a FRESH run may not write into a directory that already holds ANY artifact of a run — not
+      // merely one with a readable state file (a HALF-written run is exactly the dangerous case).
+      // The owner marker is excluded: a dead one is stale residue, handled by the claim below.
+      const found = RUN_ARTIFACTS.filter((rel) => existsSync(join(runDir, rel)));
+      if (found.length > 0) {
+        return {
+          ok: false,
+          reason: 'run-exists',
+          detail: `run directory ${runDir} already holds ${found.join(', ')} — pass --resume ${runId} to continue it, or choose another --run-id. A fresh run never writes into an existing run's artifacts`,
+        };
+      }
+    }
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        writeFileSync(ownerPath, JSON.stringify({ host: WF_RUN_OWNER_HOST, pid: process.pid, runnerVersion: dzOwnVersion(), startedMarker }, null, 2) + '\n', { flag: 'wx' });
+        return { ok: true };
+      } catch (e) {
+        if ((e as NodeJS.ErrnoException).code !== 'EEXIST') {
+          return { ok: false, reason: 'run-locked', detail: `cannot claim ${ownerPath}: ${e instanceof Error ? e.message : String(e)} — refusing to run without a durable owner record` };
+        }
+        const held = wfReadJson(ownerPath) as { pid?: number; startedMarker?: string } | null;
+        if (held !== null && typeof held.pid === 'number' && wfPidAlive(held.pid)) {
+          return { ok: false, reason: 'run-locked', detail: `another dz workflow run (pid ${held.pid}, started ${held.startedMarker ?? 'unknown'}) owns ${runDir} — ONE writer per run, always` };
+        }
+        // STALE: the recorded owner is gone. Replacing it is safe HERE and only here, because this
+        // whole block holds the named lock, so no concurrent claimant can be mid-decision.
+        try {
+          unlinkSync(ownerPath);
+        } catch {
+          /* someone else just cleared it; the retry's `wx` decides */
+        }
+      }
+    }
+    return { ok: false, reason: 'run-locked', detail: `could not claim ${ownerPath} after replacing a stale marker — another writer is racing for this run` };
+  });
+  if (!claim.ok) {
+    if (json) emit({ schema: 'wf-run-result/1', runId, status: 'failed', reason: claim.reason, exitCode: 1 });
+    else write(`dz workflow run: ${claim.reason} — ${claim.detail}`);
+    return 1;
+  }
+
+  // ── NEW-H (re-QE): from HERE to the end, every exit path — return, throw, or completion — runs
+  // the cleanup. Round 1 opened the try only around `runWorkflow`, so a `usageError` return or a
+  // throw while CONSTRUCTING the dispatchers (a malformed seam file is enough) left `run-owner.json`
+  // behind: a durable claim held by a process that had already exited.
+  try {
+  const targetCwd = root;
+  const inputs: RunnerInputs = {
+    plan: parsed,
+    runId,
+    coderFamily: coder.value ?? 'claude',
+    allowSameFamilyQe: flags.has('allow-same-family-qe'),
+    defaultFamily: dflt.value,
+    budgetOverride: nums['budget'] ?? null,
+    maxWallClockMsOverride: nums['max-wall-clock'] ?? null,
+    stageTimeoutMsOverride: nums['stage-timeout'] ?? null,
+    resume: resumeId,
+    resumeArgs,
+    budgetExtra: nums['budget-extra'] ?? null,
+    wallClockExtraMs: nums['wall-clock-extra'] ?? null,
+    runnerVersion: dzOwnVersion(),
+    cwdRoot: targetCwd,
+  };
+
+  const pre = preflight(inputs, {
+    realpath: (p) => { try { return realpathSync(p); } catch { return null; } },
+    exists: (p) => existsSync(p),
+  });
+  if (!pre.ok) {
+    if (json) emit({ schema: 'wf-run-result/1', runId, status: 'failed', reason: pre.reason, exitCode: 1 });
+    else write(`dz workflow run: ${pre.reason} — ${pre.detail}`);
+    return 1;
+  }
+
+  // ── dispatchers: the real adapters, or the scripted env TEST SEAM ──
+  const scriptPath = seamScriptPath;
+  let dispatchers: Record<BridgeFamily, Dispatcher>;
+  if (dispatcherOverride) {
+    if (!existsSync(scriptPath as string)) return usageError(`${WF_RUN_DISPATCH_SCRIPT_ENV}=${String(scriptPath)} does not exist`);
+    dispatchers = { claude: wfScriptedDispatcher(scriptPath as string, 'claude'), openai: wfScriptedDispatcher(scriptPath as string, 'openai') };
+  } else {
+    wfInstallKillHandlers();
+    const isolated = mkdtempSync(join(tmpdir(), 'dz-wf-run-'));
+    const monotonicMs = (): number => Number(process.hrtime.bigint() / 1000000n);
+    dispatchers = {
+      claude: makeClaudePDispatcher(wfChildRunnerFor('claude'), { isolatedCwd: () => isolated, monotonicMs }),
+      openai: makeCodexExecDispatcher(wfChildRunnerFor('openai'), { isolatedCwd: () => isolated, monotonicMs }),
+    };
+  }
+
+  const store = wfMakeStore(runDir, root, targetCwd);
+  const deps: SchedulerDeps = {
+    store,
+    dispatchers,
+    lock: (fn) => withNamedLockSync(root, `wf-run-${runId}`, fn),
+    now: () => new Date().toISOString(),
+    monotonicMs: () => Number(process.hrtime.bigint() / 1000000n),
+    dispatcherOverride,
+    planPath: relative(root, absPlan) || planPath,
+    slug: parsed.name,
+    // the envelope must point at THIS run's state file and reproduce THIS run's flags (HIGH-7)
+    runStatePath: relative(root, join(runDir, WF_RUN_STATE_FILE)) || join(runDir, WF_RUN_STATE_FILE),
+    runDirArg: runDirOpt ?? null,
+    // the run-state owner records the process that actually holds the claim (HIGH-6) — `pid: 0`
+    // was a durable record of a process that never existed
+    ownerPid: process.pid,
+    ownerStartedMarker: startedMarker,
+  };
+
+  const outcome = await runWorkflow(inputs, pre, deps);
+
+  // A run that dispatched to NO REAL MODEL says so on every channel (Step-8 MEDIUM-11): the
+  // result/pause envelope carries `dispatcherOverride`, and the human line says it in words. A seam
+  // visible only inside a state file is a seam a reader of the output cannot know about.
+  const seamNote = dispatcherOverride ? ' [SCRIPTED DISPATCHER — no real model ran]' : '';
+  if (outcome.kind === 'paused') {
+    if (!json) write(`dz workflow run: PAUSED (${outcome.envelope.pauseState})${seamNote} — resume with: ${outcome.envelope.resumeCmd}`);
+    // the envelope is the LAST stdout line, ALWAYS (AM-16)
+    emit({ ...outcome.envelope, ...(dispatcherOverride ? { dispatcherOverride: true } : {}) });
+    return 75;
+  }
+  if (outcome.kind === 'failed') {
+    if (!json) write(`dz workflow run: ${outcome.reason}${seamNote} — ${outcome.detail}`);
+    emit(outcome.result); // a wf-run-result/1 line — and NEVER a pause envelope
+    return 1;
+  }
+  if (!json) {
+    const terminal = outcome.result.terminalRoute === undefined ? '' : ` via the plan's terminal route ${outcome.result.terminalRoute}`;
+    write(`dz workflow run: completed (${runId})${terminal}${seamNote} — trace at ${join(relative(root, runDir) || '.', 'trace.jsonl')}`);
+  }
+  emit(outcome.result);
+  return 0;
+  } finally {
+    // the claim is released exactly once, on EVERY path out of the claimed region
+    try { unlinkSync(ownerPath); } catch { /* already gone */ }
+    wfKillLiveChildren();
+  }
+}
+
 function scanReqeDebts(root: string): { debts: Array<{ debt: ReqeDebt; duePath: string; dir: string }>; malformed: number } {
   const out: Array<{ debt: ReqeDebt; duePath: string; dir: string }> = [];
   let malformed = 0;
-  const featuresDir = join(root, 'features');
+  /**
+   * TWO scan roots (K1 — feature dz-workflow-run):
+   *   `features/<slug>/.fa-state/` — the feature-adr home, the original root;
+   *   `.dz/loop-trace/<runId>/.fa-state/` — the DEFAULT home of a `dz workflow run` (ADR-003).
+   * Without the second root the ADR-002 waiver promise ("a waived run's debt is surfaced by
+   * `dz reqe`") is FALSE for every default-homed loop run — the record would be written to a
+   * directory nothing ever reads. The scan's own rules are unchanged: symlinked containers are
+   * skipped, an oversize or non-plain file is NAMED as malformed rather than silently dropped, and
+   * a debt whose `slug` disagrees with its directory is malformed too.
+   */
+  const scanRoots: { base: string; keyMatchesDir: boolean }[] = [
+    { base: join(root, 'features'), keyMatchesDir: true },
+    // a loop run's directory is its runId; the debt's `slug` is the PLAN's name, so the two need
+    // not agree — the identity check that applies under features/ does not apply here
+    { base: join(root, '.dz', 'loop-trace'), keyMatchesDir: false },
+  ];
+  for (const scanRoot of scanRoots) scanOneReqeRoot(scanRoot.base, scanRoot.keyMatchesDir, out, (n) => { malformed += n; });
+  return { debts: out, malformed };
+}
+
+/** One scan root's walk — extracted verbatim from the original single-root body (K1). */
+function scanOneReqeRoot(
+  featuresDir: string,
+  keyMatchesDir: boolean,
+  out: Array<{ debt: ReqeDebt; duePath: string; dir: string }>,
+  addMalformed: (n: number) => void,
+): void {
+  let malformed = 0;
   let slugs: string[] = [];
   try {
-    if (lstatSync(featuresDir).isSymbolicLink()) return { debts: [], malformed: 0 }; // r2 #4: features/ itself
+    if (lstatSync(featuresDir).isSymbolicLink()) return; // r2 #4: the container itself
     slugs = readdirSync(featuresDir);
   } catch {
-    return { debts: [], malformed: 0 };
+    return;
   }
   for (const slug of slugs.sort()) {
     const dir = join(featuresDir, slug);
@@ -7971,13 +8846,13 @@ function scanReqeDebts(root: string): { debts: Array<{ debt: ReqeDebt; duePath:
     }
     try {
       const debt = parseReqeDebt(readFileSync(duePath, 'utf-8'));
-      if (debt && debt.slug === slug) out.push({ debt, duePath, dir });
+      if (debt && (!keyMatchesDir || debt.slug === slug)) out.push({ debt, duePath, dir });
       else malformed++;
     } catch {
       malformed++;
     }
   }
-  return { debts: out, malformed };
+  addMalformed(malformed);
 }
 
 /**
@@ -8122,6 +8997,770 @@ function cmdReqe(options: Map<string, string>, flags: Set<string>, cwd: string,
   return 0;
 }
 
+/* -------------------------------------------------------------------------- */
+/* `dz qe-bridge` — the reverse QE bridge (feature qe-bridge-claude, ADR-001)   */
+/* -------------------------------------------------------------------------- */
+
+/** Review timeout default: an adversarial QE pass legitimately takes minutes (NFR-3). */
+const QE_BRIDGE_DEFAULT_TIMEOUT_S = 600;
+const QE_BRIDGE_MIN_TIMEOUT_S = 30;
+const QE_BRIDGE_MAX_TIMEOUT_S = 3600;
+/** Probe timeout — the mirror of `codexProbeCommand`'s `timeout 60`. */
+const QE_BRIDGE_PROBE_TIMEOUT_MS = 60_000;
+
+export interface ClaudeBridgeRun {
+  stdout: string;
+  stderr: string;
+  exitCode: number | null;
+  timedOut: boolean;
+  spawnError: string | null;
+}
+
+/**
+ * Run one `claude` call with the prompt on STDIN. Spawn-injectable, and NEVER throws: a missing
+ * binary, a crash and a hang all come back as DATA, because the taxonomy above them can only name
+ * a failure it is handed. (The first draft of this function let the ENOENT escape as an uncaught
+ * exception and the command never settled — the acid A1 red, quoted in red-green.md.)
+ *
+ * Mirrors `probeContent`'s settled-flag + SIGTERM deadline shape (`cli.ts` probes) and scrubs
+ * `PROBE_SCRUB_ENV`, so a bridge launched from inside a nested Claude session cannot inherit the
+ * parent's session identity (SEC-4).
+ */
+export async function runClaudeBridge(
+  bin: string,
+  argv: string[],
+  promptStdin: string,
+  timeoutMs: number,
+  cwd: string = process.cwd(),
+  spawnImpl: typeof spawn = spawn,
+): Promise<ClaudeBridgeRun> {
+  // A THIN WRAPPER over runChildBridge since the loop runner needed the same machinery with two
+  // extra knobs. This signature is consumed by the qe-bridge suites and MUST NOT change.
+  return runChildBridge(bin, argv, { stdinText: promptStdin, timeoutMs, cwd, detached: false, spawnImpl });
+}
+
+/** How long a child's process group gets to honour SIGTERM before SIGKILL (Step-8 MEDIUM-14). */
+const CHILD_SIGKILL_GRACE_MS = 2000;
+
+/**
+ * The MINIMAL environment a dispatched child gets (Step-8 HIGH-9).
+ *
+ * A deny-list removes what somebody remembered; an allow-list carries what the child needs and
+ * nothing else. The named set is deliberately boring — enough for a binary to find itself, resolve
+ * a home directory, write a temp file and talk to a proxy — plus each runtime's own credential
+ * variables, which are listed because they are REQUIRED, not because they happened to be present.
+ * Anything a future adapter needs is added HERE, visibly, with a reason.
+ */
+const CHILD_ENV_BASE: readonly string[] = [
+  'PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'LANG', 'LC_ALL', 'TZ',
+  'TMPDIR', 'TEMP', 'TMP',
+  'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY', 'http_proxy', 'https_proxy', 'no_proxy',
+  // node itself, for a child that IS node
+  'NODE_EXTRA_CA_CERTS',
+];
+
+/**
+ * CREDENTIALS ARE PER FAMILY (Step-8 re-QE H9 — the round-1 allowlist shipped BOTH sets to BOTH
+ * runtimes, which is a shorter list of the same mistake).
+ *
+ * A codex dispatch has no business holding an Anthropic key, and vice versa. The two runtimes are
+ * separate blast radii precisely because the cross-model rule makes them review each other: if one
+ * is compromised or simply misbehaves, it must not be carrying the other's credentials. The base
+ * above is boring on purpose — enough to find a binary, a home directory and a proxy — and nothing
+ * in it authenticates anything.
+ */
+const CHILD_ENV_BY_FAMILY: Readonly<Record<BridgeFamily, readonly string[]>> = {
+  claude: ['ANTHROPIC_API_KEY', 'CLAUDE_CONFIG_DIR'],
+  openai: ['OPENAI_API_KEY', 'CODEX_HOME'],
+};
+
+function buildAllowlistEnv(extra: readonly string[], parent: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  const out: NodeJS.ProcessEnv = {};
+  for (const key of [...CHILD_ENV_BASE, ...extra]) {
+    const v = parent[key];
+    if (typeof v === 'string') out[key] = v;
+  }
+  return out;
+}
+
+/** Test seam for H9: the exact environment ONE family's child would receive. */
+export function __wfChildEnvTestSeam(family: BridgeFamily, parent: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  return buildAllowlistEnv(CHILD_ENV_BY_FAMILY[family], parent);
+}
+
+/**
+ * THE child-process wrapper both the qe-bridge and the loop runner ride (ADR-002 O1: ONE impure
+ * wrapper, not two). Generalized from `runClaudeBridge` with the same guarantees — a settled flag so
+ * no path resolves twice, a deadline timer that SIGTERMs, the `PROBE_SCRUB_ENV` scrub so a bridge
+ * launched from inside a nested Claude session cannot inherit it, and an injectable `spawnImpl` —
+ * plus the two knobs the generalization adds:
+ *
+ *   • `stdinText: null` ⇒ `stdio[0] = 'ignore'`. MEASURED: codex-cli 0.148.0 prints
+ *     `Reading additional input from stdin...` and WAITS when stdin is left open. Passing an empty
+ *     string is not the same thing as closing it.
+ *   • `detached: true` ⇒ the child leads its OWN process group, so the runner can kill the whole
+ *     group (AM-10). `onSpawn` hands the live child to the caller's registry at the only moment the
+ *     pid is knowable.
+ *
+ * Never throws: a spawn failure resolves with `spawnError` set, exactly like the original.
+ */
+export async function runChildBridge(
+  bin: string,
+  argv: string[],
+  opts: {
+    stdinText: string | null;
+    timeoutMs: number;
+    cwd: string;
+    detached: boolean;
+    spawnImpl?: typeof spawn;
+    onSpawn?: (child: ChildProcess) => void;
+    /**
+     * `'scrub'` (default) — inherit the parent environment minus `PROBE_SCRUB_ENV`. The historical
+     * qe-bridge posture; unchanged so its suites keep their meaning.
+     * `'allowlist'` — build the child's environment from a NAMED list and nothing else
+     * (Step-8 HIGH-9). A deny-list can only remove what somebody thought of; every cloud token,
+     * registry credential and unrelated secret in the parent survived it. The loop runner uses this.
+     */
+    envMode?: 'scrub' | 'allowlist';
+    /** Extra variable names the allowlist should carry (a family's own auth, named by the caller). */
+    envExtra?: readonly string[];
+  },
+): Promise<ClaudeBridgeRun> {
+  const spawnImpl = opts.spawnImpl ?? spawn;
+  return new Promise<ClaudeBridgeRun>((resolveRun) => {
+    const env: NodeJS.ProcessEnv = opts.envMode === 'allowlist'
+      ? buildAllowlistEnv(opts.envExtra ?? [])
+      : { ...process.env };
+    if (opts.envMode !== 'allowlist') for (const key of PROBE_SCRUB_ENV) delete env[key];
+    let out = '';
+    let err = '';
+    let settled = false;
+    let timedOut = false;
+    let child: ReturnType<typeof spawn> | undefined;
+    const finish = (spawnError: string | null, exitCode: number | null): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      // A DETACHED child leads its own group, so kill the GROUP — killing the leader alone leaves
+      // whatever it spawned running (the orphan class AM-10 exists to close). SIGTERM is a REQUEST;
+      // a group that ignores it would outlive the runner, so a bounded grace period later the same
+      // group gets SIGKILL, which is not a request (Step-8 MEDIUM-14).
+      // EVERY termination goes through the one guarded chokepoint (re-QE NEW-C4) — there is no
+      // second call shape here to forget to guard.
+      const sent = signalChildSafely(child, 'SIGTERM', opts.detached);
+      if (sent) {
+        const escalation = setTimeout(() => {
+          signalChildSafely(child, 'SIGKILL', opts.detached);
+        }, CHILD_SIGKILL_GRACE_MS);
+        escalation.unref?.(); // the grace timer must never hold the runner's event loop open
+      }
+      resolveRun({ stdout: out, stderr: err, exitCode, timedOut, spawnError });
+    };
+    const timer = setTimeout(() => {
+      timedOut = true;
+      finish(null, null);
+    }, opts.timeoutMs);
+    try {
+      child = spawnImpl(bin, argv, {
+        cwd: opts.cwd,
+        env,
+        detached: opts.detached,
+        stdio: [opts.stdinText === null ? 'ignore' : 'pipe', 'pipe', 'pipe'],
+      });
+    } catch (error) {
+      finish(`cannot run \`${bin}\`: ${error instanceof Error ? error.message : String(error)}`, null);
+      return;
+    }
+    opts.onSpawn?.(child as ChildProcess);
+    child.on('error', (error: Error) => finish(`cannot run \`${bin}\`: ${error.message}`, null));
+    child.stdout?.on('data', (c: Buffer) => { out += c.toString(); });
+    child.stderr?.on('data', (c: Buffer) => { err += c.toString(); });
+    child.on('close', (code) => finish(null, code));
+    // EPIPE when the child died before reading: already reported through 'error'/'close'.
+    child.stdin?.on('error', () => { /* ignored on purpose */ });
+    if (opts.stdinText !== null) {
+      try {
+        child.stdin?.write(opts.stdinText);
+        child.stdin?.end();
+      } catch {
+        /* the close/error handlers decide the outcome */
+      }
+    }
+  });
+}
+
+/** stderr wording that PROVES a login problem. Anything else stays unclassified: a guessed reason
+ * is a small lie, and the failure record carries the raw evidence instead (ADR-001 D3-A). */
+function classifyClaudeStderr(stderr: string): 'claude-not-logged-in' | 'exit-nonzero' {
+  return /invalid api key|not logged in|please run \/login|unauthorized|authentication (failed|error)|oauth token (has )?expired/i.test(stderr)
+    ? 'claude-not-logged-in'
+    : 'exit-nonzero';
+}
+
+/** Test seam AND escape hatch for a non-standard install: the executable the bridge spawns.
+ * Deliberately an ENV VAR and not a flag — a reviewer's identity should not be something a caller
+ * can redirect with a casual command-line switch, and every record says loudly when it was used
+ * (round-2 M3). */
+const QE_BRIDGE_CLAUDE_BIN_ENV = 'DZ_QE_BRIDGE_CLAUDE_BIN';
+
+/**
+ * CRASH FAILPOINT (round-4 R4-1) — test-only, and the ONLY thing it can do is stop. Set
+ * `DZ_QE_BRIDGE_FAILPOINT=hang-before-rename` and the process blocks after the temp record is
+ * written and before the rename, so a test can SIGKILL it exactly inside the window the atomic
+ * update exists to close. Unset (the normal case) it is one string comparison and no behaviour.
+ * A crash-window property that no test can enter is a claim, not a guarantee.
+ */
+const QE_BRIDGE_FAILPOINT_ENV = 'DZ_QE_BRIDGE_FAILPOINT';
+
+/** Files under `.fa-state/qe-bridge/` may quote reviewed source and reviewer prose: owner-only. */
+const RECORD_FILE_MODE = 0o600;
+const RECORD_DIR_MODE = 0o700;
+
+/**
+ * Write a NEW file, never through a symlink, never over an existing one, and never world-readable.
+ * `wx` gives O_EXCL (no overwrite, no symlink follow at the final component); the explicit chmods
+ * defeat the process umask, which `mode:` alone does not (MEASURED: under umask 022 the round-1
+ * writes landed 0644/0755 — round-2 MAJOR M6).
+ */
+function writeNewFileOrThrow(path: string, content: string, mode: number = RECORD_FILE_MODE): void {
+  const dir = dirname(path);
+  mkdirSync(dir, { recursive: true, mode: RECORD_DIR_MODE });
+  try {
+    chmodSync(dir, RECORD_DIR_MODE);
+  } catch { /* not ours to tighten (a pre-existing shared dir) — the file mode below still applies */ }
+  writeFileSync(path, content, { flag: 'wx', mode });
+  chmodSync(path, mode);
+}
+
+/**
+ * Path containment that survives a symlinked PARENT (round-2 M6). Lexical `startsWith` is not
+ * containment: `features/x/` can be a symlink to `/etc`, and `wx` only refuses a symlink at the
+ * FINAL component. So: walk from the deepest EXISTING ancestor, realpath it, and require the result
+ * to stay under the realpath of the root — and refuse outright if any existing component on the way
+ * is a symlink.
+ */
+function containedUnderRoot(root: string, target: string): { ok: true; path: string } | { ok: false; why: string } {
+  let realRoot: string;
+  try {
+    realRoot = realpathSync(root);
+  } catch {
+    return { ok: false, why: `the project root ${root} does not resolve` };
+  }
+  const abs = resolve(root, target);
+  const rel = relative(realRoot, abs);
+  if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) return { ok: false, why: `${target} resolves outside the project root` };
+
+  // deepest existing ancestor, with every existing component checked for a symlink
+  const parts = rel.split(sep).filter((p) => p !== '');
+  let walked = realRoot;
+  for (const part of parts) {
+    const next = join(walked, part);
+    let st;
+    try {
+      st = lstatSync(next);
+    } catch {
+      break; // this component does not exist yet: nothing below it can be a symlink either
+    }
+    if (st.isSymbolicLink()) return { ok: false, why: `${target} passes through the symlink ${relative(realRoot, next)} — refusing (a symlinked parent can redirect a new file out of the repository)` };
+    walked = next;
+  }
+  let realWalked: string;
+  try {
+    realWalked = realpathSync(walked);
+  } catch {
+    return { ok: false, why: `${target} has an unresolvable parent` };
+  }
+  const realRel = relative(realRoot, realWalked);
+  if (realRel.startsWith('..') || isAbsolute(realRel)) return { ok: false, why: `${target} escapes the project root through its parent directories` };
+  return { ok: true, path: abs };
+}
+
+/**
+ * `dz qe-bridge --family claude` — run a Claude reviewer over Step-8-scoped inputs and land a
+ * PARSED signoff (feature qe-bridge-claude, ADR-001).
+ *
+ * The point of the command: when CODEX hosts the run there is no Claude agent plane to dispatch
+ * from, so the cross-family QE rule has no vehicle — `buildReqeBrief` hands the human a `null`
+ * command template for exactly this case. This is that vehicle, callable from a plain shell.
+ *
+ * ISOLATION (round-2 CRITICAL C1): both calls run from an EMPTY temporary directory with the
+ * runtime's own `--safe-mode --strict-mcp-config --tools '' --no-session-persistence`, and the
+ * verdict is read out of the `--output-format json` result envelope. Without that, the reviewer is a
+ * fully customized session running INSIDE the repository under review, and hooks/plugins can print a
+ * complete signoff onto the same stdout the parser reads (MEASURED — see red-green.md).
+ *
+ * Exit codes: 0 = a signoff was PARSED (any grade — the bridge reports, `dz reqe` gates),
+ * 1 = a NAMED failure (record in `.fa-state/qe-bridge/failed-*.json`, raw output beside it,
+ * never at `--out`), 2 = a usage error (nothing spawned, nothing written).
+ */
+async function cmdQeBridge(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): Promise<number> {
+  const json = flags.has('json');
+  const usage = 'dz qe-bridge --family claude --slug <feature> [--coder-family codex|claude] [--model <id>] [--files a,b] [--out <file>] [--timeout <s>] [--allow-same-family] [--project <dir>] [--json]';
+
+  const usageError = (message: string): number => {
+    write(json ? JSON.stringify({ ok: false, error: message, exitCode: 2 }) : `dz qe-bridge: ${message}\n${usage}`);
+    return 2;
+  };
+
+  if (flags.has('help')) {
+    if (json) {
+      write(JSON.stringify({ help: usage, exitCode: 0 }));
+      return 0;
+    }
+    write(usage);
+    write('  Runs a CLAUDE reviewer over a feature’s Step-8 artifacts from ANY host (a Codex session included)');
+    write('  and writes a parsed SIGNOFF. Exit 0 = a signoff was parsed (ANY grade — the bridge reports, it does');
+    write('  not gate); 1 = a named failure (see features/<slug>/.fa-state/qe-bridge/failed-*.json); 2 = usage.');
+    write('  --family codex is reserved: the forward bridge is `codex exec` (see .claude/rules/feature-adr-conventions.md).');
+    write('  Default report: features/<slug>/08b_reqe_report.md — settle it with');
+    write('    dz reqe --slug <feature> --done --report features/<feature>/08b_reqe_report.md');
+    write('  DISCLOSURE: the bridge sends the extracts you scope (--files, plus the feature’s manifest/ADR/QE report)');
+    write('  to the Claude runtime. It cannot classify secrets — scoping the content you scope is YOUR decision (SEC-5).');
+    return 0;
+  }
+
+  const ALLOWED_FLAGS = new Set(['json', 'help', 'allow-same-family']);
+  for (const flag of flags) {
+    if (!ALLOWED_FLAGS.has(flag)) {
+      return usageError(`unknown option --${flag}` + (['model', 'slug', 'family', 'out', 'files', 'timeout', 'coder-family', 'project'].includes(flag) ? ` (it takes a value: --${flag} <value>)` : ''));
+    }
+  }
+  const ALLOWED_OPTIONS = new Set(['family', 'slug', 'coder-family', 'model', 'files', 'out', 'timeout', 'project']);
+  for (const key of options.keys()) {
+    if (key.startsWith('_positional_')) return usageError(`unexpected argument "${options.get(key)}"`);
+    if (key === 'claude-bin') return usageError(`--claude-bin was removed in favour of the ${QE_BRIDGE_CLAUDE_BIN_ENV} environment variable — a TEST SEAM, recorded loudly in every signoff (binOverride:true). Who reviews is not a casual command-line switch.`);
+    if (!ALLOWED_OPTIONS.has(key)) return usageError(`unknown option --${key}`);
+  }
+
+  // ── family (the reserved codex direction errors with a pointer, never a silent alias) ──
+  const family = options.get('family');
+  if (family === undefined) return usageError('--family claude is required');
+  if (family === 'codex' || family === 'openai') {
+    return usageError('--family codex is reserved — the FORWARD bridge already exists: dispatch `codex exec -m <probed-id> --sandbox read-only "<brief>" < /dev/null` (one bridge per direction; see .claude/rules/feature-adr-conventions.md)');
+  }
+  if (family !== 'claude') return usageError(`unsupported --family ${family} (this leg ships "claude" only)`);
+
+  const slug = options.get('slug') ?? '';
+  if (!isSafeSlug(slug)) return usageError('a kebab-case --slug <feature> is required (no path separators, max 40 chars)');
+
+  const root = resolve(cwd, options.get('project') ?? '.');
+  const featureDir = join(root, 'features', slug);
+  if (!existsSync(featureDir)) return usageError(`no feature directory at features/${slug} — the bridge reviews an existing feature’s artifacts`);
+
+  // ── coder family: the RECORDED DEBT is the authority; the flag may only fill a gap ──
+  //
+  // Round-2 MAJOR M3: round 1 let `--coder-family codex` override a debt that said `claude`, which
+  // turns the loud `--allow-same-family` escape into an optional formality — a Claude-coded feature
+  // could be Claude-reviewed by mis-declaring one flag. The debt is written by the pipeline; the
+  // flag is written by whoever is running the command.
+  let coderFamily: BridgeFamily | null = null;
+  let coderFamilySource = 'flag';
+  let recordedDebtFamily: BridgeFamily | null = null;
+  const duePath = join(featureDir, '.fa-state', 'reqe-due.json');
+  if (existsSync(duePath)) {
+    try {
+      const debt = parseReqeDebt(readFileSync(duePath, 'utf-8'));
+      if (debt) recordedDebtFamily = debt.coderFamily;
+    } catch { /* unreadable debt: treated as absent, and the flag must then be given */ }
+  }
+  const coderOpt = options.get('coder-family');
+  if (coderOpt !== undefined) {
+    // The FLAG surface stays a closed allowlist (the cmdQeBridge discipline — a flag is not a
+    // place to accept whatever parses); the FAMILY behind it comes from the ONE mapper the loop
+    // runner also uses for its same-family comparison (ADR-002 W20/AM-17). A second normalization
+    // here is how a codex-coded run comes to be reviewed by codex under a claude label — the
+    // agreement between the two call sites is pinned by a test, not by care.
+    const asked = coderOpt === 'codex' || coderOpt === 'openai' || coderOpt === 'claude' ? modelFamily(coderOpt) : null;
+    if (asked === null) return usageError(`--coder-family must be codex or claude (got "${coderOpt}")`);
+    if (recordedDebtFamily !== null && recordedDebtFamily !== asked) {
+      return usageError(
+        `--coder-family ${coderOpt} contradicts the recorded debt at features/${slug}/.fa-state/reqe-due.json, which says the coder family was ${recordedDebtFamily}. ` +
+        'The debt is the authority: it was written by the run being reviewed, the flag by whoever is invoking this command. ' +
+        'Refusing rather than letting a flag re-label who wrote the code — that label is what decides whether this review is cross-family. ' +
+        'Fix the flag, or correct the debt file if IT is wrong.',
+      );
+    }
+    coderFamily = asked;
+  } else if (recordedDebtFamily !== null) {
+    coderFamily = recordedDebtFamily;
+    coderFamilySource = 'reqe-due.json';
+  }
+  if (coderFamily === null) {
+    return usageError(`--coder-family codex|claude is required (no readable re-QE debt at features/${slug}/.fa-state/reqe-due.json to read it from) — who WROTE the code decides whether this review is cross-family`);
+  }
+
+  // ── --out: under the repo, no traversal, no control characters, no symlinked parents ──
+  const outOpt = options.get('out') ?? join('features', slug, '08b_reqe_report.md');
+  if (hasUnsafePathChars(outOpt) || hasDotDotSegment(outOpt)) return usageError('--out must not contain control characters or ".." segments');
+  const outCheck = containedUnderRoot(root, outOpt);
+  if (!outCheck.ok) return usageError(`--out ${outCheck.why}`);
+  const outPath = outCheck.path;
+
+  // ── timeouts: Number.isFinite-safe clamp (the numeric-clamp lesson) ──
+  let timeoutS = QE_BRIDGE_DEFAULT_TIMEOUT_S;
+  const timeoutRaw = options.get('timeout');
+  if (timeoutRaw !== undefined) {
+    const n = Number(timeoutRaw);
+    if (!Number.isFinite(n)) return usageError(`--timeout must be a number of seconds (got "${timeoutRaw}")`);
+    timeoutS = Math.min(QE_BRIDGE_MAX_TIMEOUT_S, Math.max(QE_BRIDGE_MIN_TIMEOUT_S, Math.floor(n)));
+  }
+
+  // ── model candidates: an allowlist says a name is spellable, only the probe says it answers ──
+  const modelOpt = options.get('model');
+  if (modelOpt !== undefined && !isSafeClaudeId(modelOpt)) {
+    return usageError(`unsafe --model id "${modelOpt}" — ids must match /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/ (a leading "-" would become an option)`);
+  }
+  const candidates = modelOpt !== undefined ? [modelOpt] : Object.keys(KNOWN_CLAUDE);
+
+  const binRaw = process.env[QE_BRIDGE_CLAUDE_BIN_ENV];
+  const binOverride = typeof binRaw === 'string' && binRaw.trim() !== '';
+  const binOpt = binOverride ? binRaw.trim() : 'claude';
+  if (hasUnsafePathChars(binOpt)) return usageError(`${QE_BRIDGE_CLAUDE_BIN_ENV} must not contain control characters`);
+  let resolvedBin = binOpt;
+  if (binOverride) {
+    try {
+      resolvedBin = realpathSync(binOpt);
+    } catch {
+      resolvedBin = binOpt; // unresolvable: recorded as given, and the spawn will name the failure
+    }
+  }
+
+  // ── extracts: SCOPED, never a repo dump ──
+  const extracts: NamedExtract[] = [];
+  const pushIfPresent = (rel: string, label: string): void => {
+    const p = join(root, rel);
+    try {
+      if (!lstatSync(p).isFile()) return;
+      extracts.push({ label, text: readFileSync(p, 'utf-8') });
+    } catch { /* absent: the brief says so by omission */ }
+  };
+  pushIfPresent(join('features', slug, '07_code_changes', 'change_manifest.md'), `features/${slug}/07_code_changes/change_manifest.md`);
+  const adrDir = join(featureDir, '03_adr');
+  if (existsSync(adrDir)) {
+    for (const f of readdirSync(adrDir).filter((n) => n.endsWith('.md')).sort()) {
+      pushIfPresent(join('features', slug, '03_adr', f), `features/${slug}/03_adr/${f}`);
+    }
+  }
+  pushIfPresent(join('features', slug, '08_qe_report.md'), `features/${slug}/08_qe_report.md (the review ON RECORD — judge it, do not inherit it)`);
+
+  const filesOpt = options.get('files');
+  for (const rel of (filesOpt ?? '').split(',').map((s) => s.trim()).filter((s) => s !== '')) {
+    if (hasUnsafePathChars(rel) || hasDotDotSegment(rel) || isAbsolute(rel)) {
+      return usageError(`--files entry "${rel}" must be a repo-relative path with no ".." segments and no control characters`);
+    }
+    const check = containedUnderRoot(root, rel);
+    if (!check.ok) return usageError(`--files entry "${check.why}"`);
+    let st;
+    try {
+      st = lstatSync(check.path);
+    } catch {
+      return usageError(`--files entry "${rel}" does not exist`);
+    }
+    if (!st.isFile()) return usageError(`--files entry "${rel}" is not a regular file (symlinks are refused)`);
+    extracts.push({ label: rel, text: readFileSync(check.path, 'utf-8') });
+  }
+  if (extracts.length === 0) {
+    return usageError(`nothing to review: features/${slug} has no change manifest, ADR or QE report, and no --files were given`);
+  }
+
+  // ── run identity + the audit bundle (round-2 M7) ──
+  //
+  // R3-2: the state directory is checked with the SAME containment walk as `--out`, BEFORE anything
+  // is created in it. Round 2 contained the record PATHS but not the directory they live in, so a
+  // symlinked `.fa-state/qe-bridge` (or `.fa-state`) silently redirected every write — and every
+  // chmod — outside the repository. A guard that covers the leaves but not the branch is not a guard.
+  const stateDirRel = join('features', slug, '.fa-state', 'qe-bridge');
+  const stateCheck = containedUnderRoot(root, stateDirRel);
+  if (!stateCheck.ok) return usageError(`the audit state directory ${stateCheck.why}`);
+  const stateDir = stateCheck.path;
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const runId = `${stamp}-${randomBytes(4).toString('hex')}`;
+  const requestedOut = relative(root, outPath);
+  const uniquePath = (base: string, ext: string): string => {
+    let candidate = `${base}${ext}`;
+    for (let n = 2; existsSync(candidate); n += 1) candidate = `${base}-${n}${ext}`;
+    return candidate;
+  };
+  /** Retain the raw reviewer stdout. THROWS on failure (R3-3): round 2 swallowed the error and
+   * recorded `rawStdoutFile: null`, which turns "we could not keep the evidence" into a field nobody
+   * reads. On the success path an unretainable stdout fails the run; on a failure path the forensics
+   * are best-effort, because the run is already failing for a named reason. */
+  const retainRaw = (stdout: string, kind: 'signoff' | 'failed'): string | null => {
+    if (stdout === '') return null;
+    const p = uniquePath(join(stateDir, `${kind}-${runId}`), '.stdout.txt');
+    writeNewFileOrThrow(p, stdout);
+    return relative(root, p);
+  };
+  const retainRawBestEffort = (stdout: string, kind: 'signoff' | 'failed'): string | null => {
+    try {
+      return retainRaw(stdout, kind);
+    } catch {
+      return null;
+    }
+  };
+
+  let promptSha256: string | null = null;
+
+  const failRun = (
+    reason: BridgeFailureReason,
+    detail: string,
+    model: string | null,
+    forensics?: { stdout: string; stderr: string },
+  ): number => {
+    const emittedAt = new Date().toISOString();
+    const rawStdoutFile = forensics === undefined ? null : retainRawBestEffort(forensics.stdout, 'failed');
+    const record = buildBridgeFailureRecord(reason, detail, {
+      slug,
+      model,
+      emittedAt,
+      runId,
+      claudeBin: resolvedBin,
+      binOverride,
+      requestedOut,
+      reportWritten: false,
+      rawStdoutFile,
+      promptSha256,
+    });
+    let recordPath = '';
+    try {
+      recordPath = uniquePath(join(stateDir, `failed-${runId}`), '.json');
+      writeNewFileOrThrow(recordPath, `${JSON.stringify(record, null, 2)}\n`);
+      if (forensics && forensics.stderr.trim() !== '') writeNewFileOrThrow(uniquePath(join(stateDir, `failed-${runId}`), '.stderr.txt'), forensics.stderr);
+    } catch (primaryError) {
+      // R3-1: the one condition that breaks the record medium ITSELF (`audit-write-failed`) must
+      // still leave a named record behind, or the closed taxonomy has a member nothing can evidence.
+      // Fall back ONE level up, inside the same per-feature state plane — not to an invented path.
+      try {
+        recordPath = uniquePath(join(featureDir, '.fa-state', `qe-bridge-fallback-${runId}`), '.json');
+        writeNewFileOrThrow(recordPath, `${JSON.stringify({ ...record, fallbackFrom: relative(root, stateDir), fallbackReason: String(primaryError) }, null, 2)}\n`);
+      } catch (fallbackError) {
+        write(json ? JSON.stringify({ ok: false, reason, detail, recordError: String(fallbackError), exitCode: 1 }) : `dz qe-bridge: ${reason} — ${detail}\n  (the failure record could NOT be written: ${String(fallbackError)})`);
+        return 1;
+      }
+    }
+    if (json) write(JSON.stringify({ ok: false, reason, detail, record: relative(root, recordPath), runId, reportWritten: false, requestedOut, exitCode: 1 }));
+    else {
+      write(`dz qe-bridge: FAILED — ${reason}`);
+      write(`  ${detail}`);
+      write(`  record: ${relative(root, recordPath)}`);
+      write(`  no report was written at ${requestedOut} — an unparseable or absent review is never a passing one.`);
+    }
+    return 1;
+  };
+
+  // ── the prompt (built BEFORE any model call: a same-family refusal must cost nothing) ──
+  const built = buildBridgePrompt({ slug, coderFamily, allowSameFamily: flags.has('allow-same-family'), extracts });
+  if (!built.ok) return failRun(built.reason, built.detail, null);
+  const prompt = built.prompt;
+  promptSha256 = createHash('sha256').update(prompt).digest('hex');
+
+  // ── the isolated working directory: an EMPTY dir, so project-scoped discovery finds nothing ──
+  let isolatedCwd: string;
+  try {
+    isolatedCwd = mkdtempSync(join(tmpdir(), 'dz-qe-bridge-iso-'));
+  } catch (error) {
+    return failRun('probe-failed', `could not create an isolated working directory for the reviewer: ${String(error)}`, null);
+  }
+  const cleanupIsolated = (): void => {
+    try {
+      rmSync(isolatedCwd, { recursive: true, force: true });
+    } catch { /* a leftover empty temp dir is not worth failing a review over */ }
+  };
+
+  try {
+    // ── probe: the allowlist is a search order, the probe is the answer ──
+    let probed: string | null = null;
+    const probeNotes: string[] = [];
+    for (const id of candidates) {
+      const probeArgs = claudeProbeArgs(id);
+      if (probeArgs === null) {
+        probeNotes.push(`${id}: unsafe id, never spawned`);
+        continue;
+      }
+      const run = await runClaudeBridge(binOpt, probeArgs, '', QE_BRIDGE_PROBE_TIMEOUT_MS, isolatedCwd);
+      if (run.spawnError !== null) {
+        const enoent = /ENOENT|not found|no such file/i.test(run.spawnError);
+        return failRun(
+          enoent ? 'claude-not-found' : 'probe-failed',
+          enoent
+            ? `\`${binOpt}\` is not runnable (${run.spawnError}) — install/authenticate the Claude CLI, or point ${QE_BRIDGE_CLAUDE_BIN_ENV} at it`
+            : run.spawnError,
+          null,
+        );
+      }
+      if (run.timedOut) {
+        probeNotes.push(`${id}: probe timed out after ${QE_BRIDGE_PROBE_TIMEOUT_MS / 1000}s`);
+        continue;
+      }
+      if (interpretClaudeProbe({ stdout: run.stdout, exitCode: run.exitCode ?? 1 })) {
+        probed = id;
+        break;
+      }
+      const loginish = classifyClaudeStderr(run.stderr) === 'claude-not-logged-in';
+      if (loginish) {
+        return failRun('claude-not-logged-in', `the liveness probe for ${id} failed with a login error: ${run.stderr.trim().split('\n')[0]}`, null, { stdout: run.stdout, stderr: run.stderr });
+      }
+      probeNotes.push(`${id}: exit ${String(run.exitCode)}, no model-authored \`OK\` in the result envelope (${run.stdout.length} chars of stdout)${run.stderr.trim() === '' ? '' : ` (stderr: ${run.stderr.trim().split('\n')[0]})`}`);
+    }
+    if (probed === null) {
+      return failRun('probe-failed', `no candidate model answered the liveness probe — ${probeNotes.join('; ')}`, null);
+    }
+
+    // ── the review call ──
+    const reviewArgs = claudeReviewArgs(probed);
+    if (reviewArgs === null) return failRun('probe-failed', `the probed id ${probed} failed id validation on the review path`, probed);
+    const started = Date.now();
+    const review = await runClaudeBridge(binOpt, reviewArgs, prompt, timeoutS * 1000, isolatedCwd);
+    const elapsedMs = Date.now() - started;
+
+    if (review.spawnError !== null) {
+      const enoent = /ENOENT|not found|no such file/i.test(review.spawnError);
+      return failRun(enoent ? 'claude-not-found' : 'exit-nonzero', review.spawnError, probed, { stdout: review.stdout, stderr: review.stderr });
+    }
+    if (review.timedOut) {
+      return failRun('timeout', `the review call exceeded --timeout ${timeoutS}s and the child was killed (timeout-${timeoutS}s)`, probed, { stdout: review.stdout, stderr: review.stderr });
+    }
+    if (review.exitCode !== 0) {
+      const reason = classifyClaudeStderr(review.stderr);
+      return failRun(
+        reason,
+        `\`${binOpt}\` exited ${String(review.exitCode)}${review.stderr.trim() === '' ? ' with no stderr' : `: ${review.stderr.trim().split('\n')[0]}`}` +
+          (reason === 'exit-nonzero' ? ' — the cause is NOT classified: from outside the process a limit-exhaustion death and a crash look alike, so the raw evidence is saved instead of a guess.' : ''),
+        probed,
+        { stdout: review.stdout, stderr: review.stderr },
+      );
+    }
+    if (review.stdout.trim() === '') {
+      return failRun('empty-output', `the review call exited 0 with no output (${review.stdout.length} chars) — silence is not a clean review`, probed, { stdout: review.stdout, stderr: review.stderr });
+    }
+
+    // ── PARSE, never synthesize ──
+    const emittedAt = new Date().toISOString();
+    const parsed = parseBridgeOutput(review.stdout, { slug, coderFamily, model: probed, elapsedMs, promptSha256, emittedAt });
+    if (!parsed.ok) {
+      // No `?? <some named reason>` fallback: a state the parser did not name is its OWN failure
+      // (round-2 MAJOR M5 — laundering an unknown state into `no-grade-marker` reads like a verdict
+      // about the reviewer's text when it is really a verdict about our own code).
+      const reason: BridgeFailureReason = parsed.reason;
+      return failRun(reason, parsed.detail, probed, { stdout: review.stdout, stderr: review.stderr });
+    }
+    const signoff = parsed.signoff;
+
+    // ── landing (R3-3 ordering): AUDIT FIRST, then the report, then the truth about the report ──
+    //
+    // Round 2 wrote the report BEFORE the record, so a crash between the two left a report on disk
+    // and a record that said `reportWritten:false` — metadata that lies in the direction of "no
+    // review happened" while a review report sits next to it. The order below can only ever
+    // understate: the record exists first saying false, the report lands, then the record is
+    // corrected. A crash at any point leaves a record that is true or pessimistic, never optimistic.
+    let rawStdoutFile: string | null;
+    try {
+      rawStdoutFile = retainRaw(review.stdout, 'signoff');
+    } catch (error) {
+      return failRun(
+        'audit-write-failed',
+        `the review was PARSED (grade ${signoff.grade}) but its raw stdout could not be retained: ${String(error)} — an unauditable success is not a success, so the run FAILS rather than shipping a verdict nobody can re-derive`,
+        probed,
+        { stdout: review.stdout, stderr: review.stderr },
+      );
+    }
+
+    const recordText = (reportWritten: boolean): string => `${JSON.stringify(buildBridgeSignoffRecord(signoff, {
+      runId,
+      claudeBin: resolvedBin,
+      binOverride,
+      requestedOut,
+      reportWritten,
+      rawStdoutFile,
+      promptSha256,
+      ...(parsed.channels === undefined ? {} : { channels: parsed.channels }),
+    }), null, 2)}\n`;
+
+    let signoffPath: string;
+    try {
+      signoffPath = uniquePath(join(stateDir, `signoff-${runId}`), '.json');
+      writeNewFileOrThrow(signoffPath, recordText(false));
+    } catch (error) {
+      return failRun(
+        'audit-write-failed',
+        `the review was PARSED (grade ${signoff.grade}) but the signoff record could not be written: ${String(error)} — the verdict exists and cannot be persisted, so the run FAILS rather than reporting an unrecorded success`,
+        probed,
+        { stdout: review.stdout, stderr: review.stderr },
+      );
+    }
+
+    let reportError: unknown = null;
+    try {
+      writeNewFileOrThrow(outPath, renderBridgeReport(signoff), 0o600);
+    } catch (error) {
+      reportError = error;
+    }
+
+    if (reportError === null) {
+      // the ONLY moment `reportWritten:true` may appear: after the report is on disk
+      try {
+        // ATOMIC (R4-1): write a sibling temp file, then rename() over the original. On the same
+        // filesystem rename is atomic, so a reader — or a crash — sees the OLD complete record or
+        // the NEW complete record, never a truncated one. Round 3 truncated and rewrote in place,
+        // which made the "a crash leaves a record that is true or pessimistic" claim untrue in the
+        // one case it was about.
+        const tmpPath = `${signoffPath}.tmp.${process.pid}`;
+        writeNewFileOrThrow(tmpPath, recordText(true));
+        if (process.env[QE_BRIDGE_FAILPOINT_ENV] === 'hang-before-rename') {
+          // test-only: stop dead INSIDE the window, so a SIGKILL can prove the property
+          Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 600_000);
+        }
+        renameSync(tmpPath, signoffPath);
+        chmodSync(signoffPath, RECORD_FILE_MODE);
+      } catch (error) {
+        return failRun(
+          'audit-write-failed',
+          `the report landed at ${requestedOut} but the signoff record could not be updated to say so: ${String(error)} — the record on disk understates (reportWritten:false); re-run rather than trusting a record that disagrees with the tree`,
+          probed,
+          { stdout: review.stdout, stderr: review.stderr },
+        );
+      }
+    } else {
+      const detail = `the review was PARSED (grade ${signoff.grade}) but ${requestedOut} could not be written: ${String(reportError)} — prior evidence is never overwritten and a symlinked target is never followed; the verdict is preserved at ${relative(root, signoffPath)} with reportWritten:false`;
+      return failRun('report-write-failed', detail, probed, { stdout: '', stderr: '' });
+    }
+
+    if (json) {
+      write(JSON.stringify({
+        ok: true,
+        grade: signoff.grade,
+        gradedBy: signoff.gradedBy,
+        coderFamily: signoff.coderFamily,
+        coderFamilySource,
+        findings: signoff.findings.length,
+        report: requestedOut,
+        reportWritten: true,
+        signoff: relative(root, signoffPath),
+        rawStdout: rawStdoutFile,
+        runId,
+        binOverride,
+        claudeBin: resolvedBin,
+        elapsedMs,
+        promptChars: prompt.length,
+        promptSha256,
+        channels: parsed.channels,
+        exitCode: 0,
+      }));
+    } else {
+      write(`dz qe-bridge: GRADE ${signoff.grade} from claude/${signoff.gradedBy.model} — ${signoff.findings.length} finding(s) in ${Math.round(elapsedMs / 1000)}s`);
+      if (binOverride) write(`  ⚠ reviewer executable OVERRIDDEN via ${QE_BRIDGE_CLAUDE_BIN_ENV}: ${resolvedBin} (recorded as binOverride:true — this signoff does not prove Anthropic's runtime answered)`);
+      write(`  report:  ${requestedOut}`);
+      write(`  signoff: ${relative(root, signoffPath)}`);
+      write(`  settle:  dz reqe --slug ${slug} --done --report ${requestedOut}`);
+      write('  the bridge REPORTS (any grade exits 0); gating stays with dz reqe and the host pipeline.');
+    }
+    return 0;
+  } finally {
+    cleanupIsolated();
+  }
+}
+
+
 function cmdScore(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
   const json = flags.has('json');
   if (flags.has('help')) {
@@ -9873,6 +11512,8 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
       case 'scout':
         return await cmdScout(options, flags, cwd, write);
       case 'workflow':
+        // `run` is ASYNC (it drives child processes); every other subcommand stays sync.
+        if ((options.get('_positional_0') ?? '') === 'run') return await cmdWorkflowRun(options, optionLists, flags, cwd, write);
         return cmdWorkflow(options, flags, cwd, write);
       case 'workflow-lint':
         return cmdWorkflowLint(options, flags, cwd, write);
@@ -9980,6 +11621,8 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
         return cmdScore(options, flags, cwd, write);
       case 'reqe':
         return cmdReqe(options, flags, cwd, write);
+      case 'qe-bridge':
+        return await cmdQeBridge(options, flags, cwd, write);
       case 'backlog':
         return await cmdBacklog(options, flags, cwd, write);
       case 'routing':