@dzhechkov/harness-cli 0.5.0 → 0.5.2

package/dist/cli.js

@@ -7,16 +7,20 @@ import { appendFileSync, chmodSync, closeSync, cpSync, existsSync, fstatSync, ls
 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 { createHash, randomBytes } from 'node:crypto';
 import { homedir, tmpdir } from 'node:os';
 import { createRequire } from 'node:module';
-import { createSkill, getSkillInfo, listSkillsDetailed, formatSkillLoadFailures, formatSkillApplyFailures, resolveTargetName, formatTargetProblem, formatTargetAliasNote, TARGET_NAMES_SORTED, runDoctor, runInit, resolvePackageSkillRoots, PACKAGE_SKILL_LAYOUTS, benchmarkSkill, benchmarkSkills, scanMcp, reconcileCapabilities, RECONCILE_BANNER, buildRegistry, discoverSkillPackDirs, checkUpstream, compareSkills, checkAllUpstream, sweepSkillDrift, syncCanonicalSkill, checkUpgrades, discoverPackages, discoverSourcePackages, fetchAllDownloads, filterByCategory, pretrain, recommend, generatePlugin, publishPackages, runSetup, runMigrate, searchRegistry, runSync, runVerify, runInitAgentsMd, runInitGeminiMd, runSyncAgentsPolicy, runSyncCodexHooks, POLICY_SOURCES, detectPolicyDrift, hasPolicyFence, TARGET_NAMES, buildParityMatrix, TARGET_CAPABILITIES, TARGET_SHORT_LABELS, WORKFLOW_TEMPLATES_RETIRED_MESSAGE, parsePlan, isParseErrors, validatePlan, normalizePlan, planDigest, toTraceProjection, renderPlan, mergeRender, lint, lintExitCode, LOOP_BLOBS, parseTrace, assembleTimeline, runInvariants, renderTimelineHtml, importEcc, recordPattern, resolveLearningBackend, storeStats, consolidateSessions, pruneNoisePatterns, lessonDeltaReport, removePatternsByIds, snapshotStore, recallHybrid, teachGuard, mirrorPatternsToVector, mirrorEntriesToVector, patternVectorEntry, readMemoryLearningConfig, promotePatterns, quarantineExpiryCandidates, pruneQuarantinePatterns, clearAgentdbQuarantine, vectorMirrorEnabled, vectorTierStatus, resolveVectorEngine, reindexVectorStore, harmonizeVectorStore, importRvfCheckpoint, statuslineData, writeFeatureAdrState, computeUsage, deriveCostLedger, renderCostLedger, verifyCostLedgerReport, writeCostLedgerJsonl, COST_LEDGER_SCOPE, deriveUsageCalibration, normalizeClaudeUsageModelKey, readUsageLimits, parseWeeklyResetAnchor, claimCheck, summarize, queryBookKnowledge, loadStorePatternsSync, patternRecordId, loadStoreRecords, recordToPattern, bundleSkills, brainHome, listBrain, promoteProjectToBrain, updateBrainSource, queryBrain, groundPrompt, expandKu, reindexBrainVectors, buildPrimer, exportBrainSlice, importBrainSlice, registerKusToBrain, RECALL_USAGE_LOG_RELATIVE, RECALL_USAGE_LOG_MAX_BYTES, parseRecallUsageLog, buildRecallUsageReport, EVENT_CHAIN_TAIL_BYTES, EMPTY_LOG_TAIL, readTailInfo, appendChainedLines, verifyEventChainText, buildManifest, buildSbom, resolveTrustRoot, decideVerifyPolicy, generateSigningKeypair, evaluateGuard, resolveRules, auditRecord, guardExitCode, DEFAULT_RULES, parsePnpmLockImporters, scannableStubPath, 
+import { createSkill, getSkillInfo, listSkillsDetailed, formatSkillLoadFailures, formatSkillApplyFailures, resolveTargetName, formatTargetProblem, formatTargetAliasNote, TARGET_NAMES_SORTED, runDoctor, runInit, resolvePackageSkillRoots, PACKAGE_SKILL_LAYOUTS, benchmarkSkill, benchmarkSkills, scanMcp, reconcileCapabilities, RECONCILE_BANNER, buildRegistry, discoverSkillPackDirs, checkUpstream, compareSkills, checkAllUpstream, sweepSkillDrift, syncCanonicalSkill, checkUpgrades, discoverPackages, discoverSourcePackages, fetchAllDownloads, filterByCategory, pretrain, recommend, generatePlugin, publishPackages, runSetup, runMigrate, searchRegistry, runSync, runVerify, runInitAgentsMd, 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, NamedLockTimeoutError, NamedLockCompromisedError, POLICY_SOURCES, detectPolicyDrift, hasPolicyFence, TARGET_NAMES, buildParityMatrix, downgradeForStaleEvidence, findStaleTranscriptEvidence, TARGET_CAPABILITIES, TARGET_SHORT_LABELS, WORKFLOW_TEMPLATES_RETIRED_MESSAGE, parsePlan, isParseErrors, validatePlan, normalizePlan, planDigest, toTraceProjection, renderPlan, mergeRender, lint, lintExitCode, LOOP_BLOBS, parseTrace, assembleTimeline, runInvariants, deriveAttestation, stampAttestation, corroborate, NOT_WITNESSED, renderTimelineHtml, importEcc, recordPattern, resolveLearningBackend, storeStats, consolidateSessions, pruneNoisePatterns, lessonDeltaReport, removePatternsByIds, snapshotStore, recallHybrid, teachGuard, mirrorPatternsToVector, mirrorEntriesToVector, patternVectorEntry, readMemoryLearningConfig, promotePatterns, quarantineExpiryCandidates, pruneQuarantinePatterns, clearAgentdbQuarantine, vectorMirrorEnabled, vectorTierStatus, resolveVectorEngine, reindexVectorStore, harmonizeVectorStore, importRvfCheckpoint, statuslineData, writeFeatureAdrState, computeUsage, deriveCostLedger, renderCostLedger, verifyCostLedgerReport, writeCostLedgerJsonl, COST_LEDGER_SCOPE, deriveUsageCalibration, normalizeClaudeUsageModelKey, readUsageLimits, parseWeeklyResetAnchor, claimCheck, summarize, queryBookKnowledge, loadStorePatternsSync, patternRecordId, loadStoreRecords, recordToPattern, bundleSkills, brainHome, listBrain, promoteProjectToBrain, updateBrainSource, queryBrain, groundPrompt, expandKu, reindexBrainVectors, buildPrimer, exportBrainSlice, importBrainSlice, registerKusToBrain, RECALL_USAGE_LOG_RELATIVE, RECALL_USAGE_LOG_MAX_BYTES, parseRecallUsageLog, buildRecallUsageReport, EVENT_CHAIN_TAIL_BYTES, EMPTY_LOG_TAIL, readTailInfo, appendChainedLines, verifyEventChainText, buildManifest, buildSbom, resolveTrustRoot, decideVerifyPolicy, generateSigningKeypair, evaluateGuard, resolveRules, auditRecord, guardExitCode, DEFAULT_RULES, parsePnpmLockImporters, scannableStubPath, 
 // guard-promotion (feature guard-promotion, scout idea #1)
 assembleCandidates, renderPromotionReport, renderPromotionAdr, normalizePromotionState, nextPromotionState, globMatch, promotionAdrRelPath, DEFAULT_WINDOW_DAYS, DEFAULT_PERIODS, MAX_CONTENT_FETCHES, BUILTIN_COVERAGE, decideProvenance, isInsideTree, signManifest, verifyManifest, listSignablePackFiles, assertKeyOutsideTree, decidePublishGate, collectPackageFacts, planReleaseGates, selectAffectedPackages, classifyGateExecutions, buildFailureIssue, buildReleaseNotes, releaseTagName, firstOutputLine, formatPublishError, MANIFEST_NAME, SBOM_NAME, buildArchitectureMap, renderMapHuman, findArchitectureDrift, renderDriftReport, scanWorkspacePackages, loadSubsystemManifest, loadProductVision, checkFeatureAgainstArchitecture, renderArchCheck, planProjectSkills, guidanceForStage, renderInjectionReport, analyzeCorpus, renderRakeReport, renderCriticSection, rakeAsLesson, rakeReward, DEFAULT_RAKE_THRESHOLDS, streamSessionEvents, findLatestTranscript, detectProcessRakes, buildRetro, renderRetro, retroLessonText, PROCESS_SIGNATURES, RETRO_DOMAIN, scanForSetup, buildSetupPlan, scaffoldFromSpec, renderScaffoldPreview, readExistingForScaffold, assembleChallengeContext, buildChallengeBrief, planDiscriminationCheck, classifyDiscrimination, classifyExecutionEvidence, pickAdversaryModel, CHALLENGE_QUESTIONS, loadOutcomes, renderOutcomes, statsForKey, selectAutoCost, recordProvisional, finalizeOutcome, harvestStageOutcomes, recommendModels, planFeed, GRADE_SUCCESS_FLOOR, COST_LADDER, splitScenarios, budgetPlan, selectWinner, proseScopeOk, renderProseDiff, readScenarioIds, DEFAULT_MAX_JUDGE_RUNS, collectDeliveryFacts, planDeliveryCheck, renderDeliveryBrief, classifyDelivery, isUsablePlaneResult, renderDeliveryReview, scanSkillsLayout, declaredPluginSurface, parseInitFacts, verifyRegistration, buildContentProbePrompt, classifyContentProbe, renderContentProbe, findNonRegistrableSkillDirs, assembleCompoundingReport, 
 // Cold-vs-warm EPOCH RUNNER (feature epoch-replay) — orchestrates + scores, never calls a model.
 replayableInstances, buildWorkOrder, buildJudgePrompts, unblindJudgments, verifyWorkOrder, isValidMargin, DIGEST_HONEST_SCOPE, scoreEpochReplay, generateMockOutcomes, renderEpochReplayResult, renderWorkOrderSummary, renderJudgePromptsSummary, WORK_ORDER_KIND, DEFAULT_MOCK_N, DEFAULT_MOCK_SEED, scoreRun, renderScorecard, renderCompoundingReport, readReinforcementState, readQuarantineState, registrationExitCode, renderRegistrationReport, 
 // Smart Backlog (feature smart-backlog) — goal-directed idea pipeline over the Brain vector engine.
-readBacklogConfig, readIdeas, writeIdeas, ideaId, dedupIdea, readGoalMap, readGoalMapDetailed, parseEffort, ensureBacklogGitignored, isSafeId, alignIdea, mirrorIdeaVector, ensureBacklogEmbedForm, readBacklogEmbedFormVersion, recordAbsorption, DEDUP_EMBED_FORM_VERSION, snapshotIdeas, spinRoulette, rankRoulette, seededRng, eligibleIdeas, stageEnrichment, buildJiraDraft, resolveJiraAdapter, makeBacklogIO, harmonizeBacklog, transitionIdeas, editIdea, clearEmbedStale, BACKLOG_BACKENDS, applyDomainBoost, DZ_OWNED_TASK_TYPES, applyExportHoldout, DEFAULT_HELD_OUT_DOMAINS, canonicalDomainKey, readAgentdbRowsByTaskType, heldOutAfterOptIn, renderHoldoutNote, renderSharedStoreAdvice, decideVectorExport, countDisplacedByCut, renderDomainBoostNote, renderDomainCutNote, parseReqeDebt, buildReqeBrief, settleReqeDebt, renderReqeList, REQE_SCOPE, 
+readBacklogConfig, readIdeas, writeIdeas, ideaId, dedupIdea, readGoalMap, readGoalMapDetailed, parseEffort, ensureBacklogGitignored, isSafeId, alignIdea, mirrorIdeaVector, ensureBacklogEmbedForm, readBacklogEmbedFormVersion, recordAbsorption, DEDUP_EMBED_FORM_VERSION, snapshotIdeas, spinRoulette, rankRoulette, seededRng, eligibleIdeas, stageEnrichment, buildJiraDraft, resolveJiraAdapter, makeBacklogIO, harmonizeBacklog, transitionIdeas, editIdea, clearEmbedStale, BACKLOG_BACKENDS, applyDomainBoost, DZ_OWNED_TASK_TYPES, applyExportHoldout, DEFAULT_HELD_OUT_DOMAINS, canonicalDomainKey, readAgentdbRowsByTaskType, heldOutAfterOptIn, renderHoldoutNote, renderSharedStoreAdvice, decideVectorExport, countDisplacedByCut, 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, buildReqeBrief, settleReqeDebt, renderReqeList, REQE_SCOPE, 
 // Mutation gate (feature ha-mutation-gate) — break each named protection, run the suite, require red.
 parseMutationRegistry, applyMutationToText, countFailingTests, classifyBaseline, classifyRunFailure, classifyMutationOutcome, mutationGateExitCode, summarizeMutationResults, renderMutationReport, TRACE_BUNDLE_LEDGER_PATH, TRACE_BUNDLE_SCHEMA, TRACE_BUNDLE_RUN_META_FILE, buildBundle, serializeBundle, parseBundle, planImport, } from '@dzhechkov/harness-core';
 import { getPreset, PRESET_NAMES } from '@dzhechkov/harness-presets';
@@ -24,7 +28,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)
@@ -38,7 +42,7 @@ Usage:
   dz workflow render <plan.json> --o <script.js> [--check] [--force]   (plan → region-delimited loop script; USER regions preserved)
   dz workflow blobs [--check]                               (list/self-check the subsystem blob registry)
   dz workflow-lint <script.js> [--plan <plan.json>] [--require-plan|--legacy] [--json]   (layer-1 gate; exit 0/1/3 — inconclusive is never a pass)
-  dz workflow-trace <runDir|--slug <s>|--run <id>> [--invariants <plan.json>] [--html <out.html>] [--json]   (timeline + SEQ invariant runner)
+  dz workflow-trace <runDir|--slug <s>|--run <id>> [--invariants <plan.json>] [--corroborate <hostRunDir>] [--html <out.html>] [--json]   (timeline + SEQ invariant runner; ALWAYS reports who attested the trace — instrument|agent|unknown — and --corroborate checks the Claude host's own records for the half they can witness)
   dz workflow-trace export <run> --o <file> [--include-pairs --yes] [--strict]   (one run's telemetry as ONE movable file: events, not aggregates; degradation is typed and LOUD, --strict fails closed)
   dz workflow-trace import <bundle> --into <root> [--force] [--with-pairs]       (reconstruct that run under an explicit root; FAIL-CLOSED — never writes over a run that already has content)
   dz install <npm-pkg> [--target <name>] [--project <dir>] [--force]
@@ -59,6 +63,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)
@@ -73,7 +78,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)
@@ -123,6 +128,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(', ')}
@@ -307,6 +324,20 @@ async function cmdInit(options, flags, cwd, write, writeErr) {
         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) {
@@ -329,7 +360,7 @@ async function cmdInit(options, flags, cwd, write, writeErr) {
             writeErr(line);
         return 1;
     }
-    return 0;
+    return codexHooksOk ? 0 : 1;
 }
 async function cmdVerify(options, cwd, write, writeErr) {
     const skillsDir = resolve(cwd, options.get('skills-dir') ?? '.claude/skills');
@@ -1115,6 +1146,58 @@ function cmdWorkflowTrace(options, flags, cwd, write) {
     const ckptFile = join(runDir, '.fa-state', 'checkpoints.jsonl');
     const ledgerFile = resolve(cwd, '.dz', 'feature-adr', 'run-cost-ledger.jsonl');
     const journalFile = join(runDir, 'journal.jsonl');
+    // ── provenance (feature honest-trace-provenance) ──────────────────────────────────────────────
+    // The attestation is DERIVED here, from run-state.json — an artifact the sandboxed rendered
+    // script cannot write. It is never read out of the trace itself (ADR-001).
+    const parsedRun = parseTrace(traceText);
+    const runStateFile = join(runDir, 'run-state.json');
+    const runStateForAttestation = existsSync(runStateFile)
+        ? (() => {
+            try {
+                return JSON.parse(readFileSync(runStateFile, 'utf8'));
+            }
+            catch {
+                return null; // an unreadable state binds nothing — the reader will say `unknown`
+            }
+        })()
+        : null;
+    const attestation = deriveAttestation(parsedRun, runStateForAttestation, {
+        sha256: createHash('sha256').update(traceText, 'utf8').digest('hex'),
+        lines: traceText.split('\n').filter((l) => l.trim() !== '').length,
+    });
+    const ATTESTATION_SENTENCE = {
+        instrument: 'ATTESTATION instrument — the bytes read match the identifiers, hash and line count asserted by the co-located run-state.json. That is NOT proof that dz historically wrote them, nor that this is the directory it wrote them in.',
+        agent: 'ATTESTATION agent — this trace was appended by an AGENT asked to run the flush command, not by an instrument. Treat every verdict below as testimony.',
+        unknown: 'ATTESTATION unknown — no binding run-state.json and no emitter declaration. Not instrument; treat as testimony.',
+    };
+    // ── corroboration (ADR-002, opt-in) ───────────────────────────────────────────────────────────
+    // The host's OWN records, for the half they can witness. Directory containment is the ONLY
+    // binding available — trace and journal.jsonl share no identifier — and every result says so.
+    const corroborateDir = options.get('corroborate');
+    let corroboration = null;
+    if (corroborateDir !== undefined) {
+        const hostDir = resolve(cwd, corroborateDir);
+        const jf = join(hostDir, 'journal.jsonl');
+        const transcripts = {};
+        try {
+            for (const f of readdirSync(hostDir)) {
+                const m = /^agent-(.+)\.jsonl$/.exec(f);
+                if (m)
+                    transcripts[m[1]] = readFileSync(join(hostDir, f), 'utf8');
+            }
+        }
+        catch {
+            /* an unreadable host dir is INCONCLUSIVE, decided by corroborate() below — never a throw */
+        }
+        // The trace side, projected: the agent ids the trace claims took part, in seq order. The trace
+        // has no agentId of its own, so the invocationId is what we can offer — and that is exactly why
+        // the binding is by-directory and the verdict is scoped.
+        const claimed = [];
+        for (const e of parsedRun.events)
+            if (e.event === 'dispatched')
+                claimed.push(e.invocationId);
+        corroboration = corroborate({ agentIds: claimed }, { journal: existsSync(jf) ? readFileSync(jf, 'utf8') : null, agentTranscripts: transcripts }, hostDir);
+    }
     const timeline = assembleTimeline({
         trace: traceText,
         checkpoints: existsSync(ckptFile) ? readFileSync(ckptFile, 'utf8') : null,
@@ -1137,7 +1220,7 @@ function cmdWorkflowTrace(options, flags, cwd, write) {
             return 1;
         }
         projection = toTraceProjection(parsed);
-        verdicts = runInvariants(projection, parseTrace(traceText));
+        verdicts = stampAttestation(runInvariants(projection, parsedRun), attestation);
     }
     const htmlOut = options.get('html');
     if (htmlOut !== undefined) {
@@ -1146,9 +1229,14 @@ function cmdWorkflowTrace(options, flags, cwd, write) {
         write(`dz workflow-trace: wrote ${absHtml} (self-contained: mermaid topology + HTML waterfall)`);
     }
     if (flags.has('json')) {
-        write(JSON.stringify({ timeline, verdicts }, null, 2));
+        write(JSON.stringify({ timeline, attestation, corroboration, verdicts }, null, 2));
         return verdicts.some((v) => v.status === 'fail') ? 1 : 0;
     }
+    write(ATTESTATION_SENTENCE[attestation]);
+    if (corroboration !== null) {
+        write(`CORROBORATION ${corroboration.verdict} (binding: ${corroboration.binding}, ${corroboration.hostDir}) — ${corroboration.detail}`);
+        write(`  witnessed: ${corroboration.witnessed.join(', ')}   NOT witnessed: ${NOT_WITNESSED.join(', ')}`);
+    }
     write(`run ${timeline.runId ?? '(unknown)'}${timeline.incomplete ? ' — INCOMPLETE (no run.closed; unflushed tail may be lost)' : ''}; sources: ${timeline.sources.join(', ')}`);
     for (const r of timeline.rows.filter((x) => x.kind === 'trace')) {
         write(`  ${String(r.seq).padStart(5)}  ${r.label}  ${r.detail}${r.wallTime ? `  [wall ${r.wallTime} — diagnostic only]` : ''}`);
@@ -1197,6 +1285,16 @@ function cmdRoam(options, flags, cwd, write) {
         write('dz roam: not a git repository');
         return 1;
     }
+    // The roam archive is its OWN git repository (owner decision 2026-08-20), so `git rev-parse` run
+    // from inside it resolves to the archive, not the project. Left unguarded that computes
+    // `<repo>/roam/roam/claude-state` and, with --apply, creates a symlink under a fabricated slug.
+    // Detect the nested archive by its own shape rather than by its name alone: a directory called
+    // `roam` that CONTAINS `claude-state` is the archive, wherever it lives.
+    if (basename(repoRoot) === 'roam' && existsSync(join(repoRoot, 'claude-state'))) {
+        write('dz roam: this is the roam ARCHIVE, not the project — its git root is its own.');
+        write(`  Run from the project root instead: cd ${dirname(repoRoot)} && dz roam`);
+        return 1;
+    }
     const roamDir = join(repoRoot, 'roam', 'claude-state');
     const claudeProjectsDir = process.env['CLAUDE_PROJECTS_DIR'] ?? join(homedir(), '.claude', 'projects');
     // Slug: replace every : \ / with -
@@ -3654,6 +3752,18 @@ async function cmdSetup(options, flags, cwd, write, writeErr) {
     else {
         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),
@@ -3672,7 +3782,9 @@ async function cmdSetup(options, flags, cwd, write, writeErr) {
             + (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, cwd, write) {
     const projectRoot = resolve(cwd, options.get('project') ?? '.');
@@ -4399,6 +4511,19 @@ function cmdParity(options, flags, write, writeErr) {
         }
     }
     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();
+    for (const s of staleEvidence)
+        staleByTarget.set(s.target, [...(staleByTarget.get(s.target) ?? []), s.capability]);
+    const reportCell = (feature, t, cell) => downgradeForStaleEvidence(feature, cell, staleByTarget.get(t) ?? []);
+    const staleNote = (t) => 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
@@ -4426,25 +4551,41 @@ function cmdParity(options, flags, write, writeErr) {
             writeErr(formatTargetAliasNote('dz parity', targetOpt, target));
     }
     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 = {};
+            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;
     }
     if (target !== undefined) {
         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;
     }
     // Grid: one column per target, short header, one row per feature. Computed, never hand-written;
@@ -4454,8 +4595,8 @@ function cmdParity(options, flags, write, writeErr) {
     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}`);
     }
@@ -5475,11 +5616,16 @@ function cmdHooksSync(options, flags, cwd, write, writeErr) {
         return 1;
     }
     const codexHome = options.get('codex-home');
-    const report = runSyncCodexHooks({
+    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 }));
         return report.exitCode;
@@ -5496,20 +5642,174 @@ function cmdHooksSync(options, flags, cwd, write, writeErr) {
         write(`dz hooks-sync: removed ${report.removed} managed entr(ies) from ${report.registryPath}`);
         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;
+}
+/**
+ * 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) {
+    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,
+    };
+}
+/**
+ * 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, label = 'dz hooks-sync') {
+    const stdout = [];
+    const stderr = [];
+    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 = {}) {
+    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) => {
+        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 = null;
+    const report = runSyncCodexHooks({
+        ...options,
+        criticalSection: (fn) => {
+            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 = {}) {
+    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, sync = runSyncCodexHooksGuarded, label = 'dz setup') {
+    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(options, flags, cwd, write, writeErr) {
     const json = flags.has('json');
@@ -7661,18 +7961,619 @@ function cmdMutationGate(options, flags, cwd, write) {
  * 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, signal, detached) {
+    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, signal, detached) {
+    return signalChildSafely(child, signal, detached);
+}
+/** Live children, keyed by pid, for the kill-group handlers (AM-10). */
+const wfLiveChildren = new Map();
+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 = 'SIGTERM') {
+    const killed = [];
+    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() {
+    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() {
+    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) => 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, family) {
+    const raw = JSON.parse(readFileSync(scriptPath, 'utf8'));
+    const script = (raw['steps'] ?? raw);
+    const probeId = typeof raw['probeId'] === 'string' ? raw['probeId'] : `${family}-scripted`;
+    const consumed = new Map();
+    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)] : entry;
+            const base = {
+                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 };
+        },
+    };
+}
+/** Read a small JSON file, or null. */
+function wfReadJson(path) {
+    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) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.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, rel) {
+    const check = containedUnderRoot(targetCwd, rel);
+    return check.ok ? check.path : null;
+}
+function wfMakeStore(runDir, repoRoot, targetCwd) {
+    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) => {
+        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),
+        // The CONTENT half of the attestation binding. Hashes the file AS IT STANDS, so it must be
+        // called after the final flush — the scheduler's stampTraceBinding is the single caller.
+        measureTrace: () => {
+            if (!existsSync(tracePath))
+                return null;
+            const text = readFileSync(tracePath, 'utf8');
+            return { sha256: createHash('sha256').update(text, 'utf8').digest('hex'), lines: text.split('\n').filter((l) => l.trim() !== '').length };
+        },
+        readRunState: () => wfReadJson(statePath),
+        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 = {};
+            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, optionLists, flags, cwd, write) {
+    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) => {
+        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;
+    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, scale = 1) => {
+        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 = {};
+    for (const [key, scale] of [['budget', 1], ['max-wall-clock', 1000], ['stage-timeout', 1000], ['budget-extra', 1], ['wall-clock-extra', 1000]]) {
+        const r = num(key, scale);
+        if (!r.ok)
+            return usageError(r.why);
+        nums[key] = r.value;
+    }
+    const familyOpt = (key) => {
+        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 = {};
+    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;
+    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) => {
+        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')];
+    const claim = withNamedLockSync(root, `wf-run-${runId}`, () => {
+        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);
+        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.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);
+                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 = {
+            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;
+        if (dispatcherOverride) {
+            if (!existsSync(scriptPath))
+                return usageError(`${WF_RUN_DISPATCH_SCRIPT_ENV}=${String(scriptPath)} does not exist`);
+            dispatchers = { claude: wfScriptedDispatcher(scriptPath, 'claude'), openai: wfScriptedDispatcher(scriptPath, 'openai') };
+        }
+        else {
+            wfInstallKillHandlers();
+            const isolated = mkdtempSync(join(tmpdir(), 'dz-wf-run-'));
+            const monotonicMs = () => 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 = {
+            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) {
     const out = [];
     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: 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, keyMatchesDir, out, addMalformed) {
+    let malformed = 0;
     let slugs = [];
     try {
         if (lstatSync(featuresDir).isSymbolicLink())
-            return { debts: [], malformed: 0 }; // r2 #4: features/ itself
+            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);
@@ -7698,7 +8599,7 @@ function scanReqeDebts(root) {
         }
         try {
             const debt = parseReqeDebt(readFileSync(duePath, 'utf-8'));
-            if (debt && debt.slug === slug)
+            if (debt && (!keyMatchesDir || debt.slug === slug))
                 out.push({ debt, duePath, dir });
             else
                 malformed++;
@@ -7707,7 +8608,7 @@ function scanReqeDebts(root) {
             malformed++;
         }
     }
-    return { debts: out, malformed };
+    addMalformed(malformed);
 }
 /**
  * `dz reqe` — the re-QE debt ledger (backlog 6b40e667): list usage-switched same-family QE debts,
@@ -7863,6 +8764,711 @@ function cmdReqe(options, flags, cwd, write) {
     write(json ? JSON.stringify({ settled: true, grade: settlement.grade, exitCode: 0 }) : `dz reqe: ${okMsg}`);
     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;
+/**
+ * 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, argv, promptStdin, timeoutMs, cwd = process.cwd(), spawnImpl = spawn) {
+    // 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 = [
+    '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 = {
+    claude: ['ANTHROPIC_API_KEY', 'CLAUDE_CONFIG_DIR'],
+    openai: ['OPENAI_API_KEY', 'CODEX_HOME'],
+};
+function buildAllowlistEnv(extra, parent = process.env) {
+    const out = {};
+    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, parent) {
+    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, argv, opts) {
+    const spawnImpl = opts.spawnImpl ?? spawn;
+    return new Promise((resolveRun) => {
+        const env = 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;
+        const finish = (spawnError, exitCode) => {
+            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);
+        child.on('error', (error) => finish(`cannot run \`${bin}\`: ${error.message}`, null));
+        child.stdout?.on('data', (c) => { out += c.toString(); });
+        child.stderr?.on('data', (c) => { 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', () => { });
+        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) {
+    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, content, mode = RECORD_FILE_MODE) {
+    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, target) {
+    let realRoot;
+    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;
+    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, flags, cwd, write) {
+    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) => {
+        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 = null;
+    let coderFamilySource = 'flag';
+    let recordedDebtFamily = 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 = [];
+    const pushIfPresent = (rel, label) => {
+        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, ext) => {
+        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, kind) => {
+        if (stdout === '')
+            return null;
+        const p = uniquePath(join(stateDir, `${kind}-${runId}`), '.stdout.txt');
+        writeNewFileOrThrow(p, stdout);
+        return relative(root, p);
+    };
+    const retainRawBestEffort = (stdout, kind) => {
+        try {
+            return retainRaw(stdout, kind);
+        }
+        catch {
+            return null;
+        }
+    };
+    let promptSha256 = null;
+    const failRun = (reason, detail, model, forensics) => {
+        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;
+    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 = () => {
+        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 = null;
+        const probeNotes = [];
+        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 = 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;
+        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) => `${JSON.stringify(buildBridgeSignoffRecord(signoff, {
+            runId,
+            claudeBin: resolvedBin,
+            binOverride,
+            requestedOut,
+            reportWritten,
+            rawStdoutFile,
+            promptSha256,
+            ...(parsed.channels === undefined ? {} : { channels: parsed.channels }),
+        }), null, 2)}\n`;
+        let signoffPath;
+        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 = 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, flags, cwd, write) {
     const json = flags.has('json');
     if (flags.has('help')) {
@@ -9722,6 +11328,9 @@ export async function runCli(argv, io = {}) {
             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);
@@ -9829,6 +11438,8 @@ export async function runCli(argv, io = {}) {
                 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':