@dzhechkov/harness-core 0.8.10 → 0.8.20

package/src/discrimination-gate.ts

@@ -137,12 +137,182 @@ export interface ClassifyResultRow {
   readonly tipEvidence?: ExecutionEvidence;
 }
 
+/** A CLOSED runner selection derived from the target package, never a command copied from package.json. */
+export type RunnerSelection =
+  | {
+      readonly kind: 'vitest';
+      readonly command: 'npx vitest run';
+      readonly runnerName: 'vitest';
+      readonly how: 'scripts.test' | 'dev-dependency';
+      /** Сегменты составного `scripts.test`, которые НЕ будут выполнены. См. `selectRunner`. */
+      readonly skippedPreparation?: readonly string[];
+    }
+  | {
+      readonly kind: 'node-test';
+      readonly command: 'node --test';
+      readonly runnerName: 'node --test';
+      readonly how: 'scripts.test';
+      readonly skippedPreparation?: readonly string[];
+    }
+  | {
+      readonly kind: 'unsupported';
+      readonly runnerName: string;
+      readonly scriptsTest: string | null;
+    };
+
+export type PlannedRunnerSelection =
+  | RunnerSelection
+  | {
+      readonly kind: 'explicit';
+      readonly command: string;
+      readonly runnerName: string;
+      readonly how: 'explicit-flag';
+    };
+
+export interface BaseRefResolution {
+  readonly requestedRef: string;
+  readonly resolvedRef: string;
+  /**
+   * WHERE THE BASE CAME FROM, and it is part of the evidence, not decoration.
+   *
+   * `explicit-ref` is a claim about a HUMAN action — someone typed `--base <ref>`. It used to be
+   * written for a HEAD the tool had chosen by itself, so a receipt could not distinguish a base
+   * that was audited from one that was defaulted (MEASURED 2026-09-04:
+   * `resolveDiscriminationBaseRef('HEAD')` and `resolveDiscriminationBaseRef('abc123^')` returned
+   * the same `how`). This gate's whole output is cited later as proof; a receipt that overstates
+   * how its base was chosen forges the provenance of that proof.
+   */
+  readonly how: 'explicit-ref' | 'merge-base' | 'default-ref';
+}
+
+/**
+ * Select one of the two runner families this instrument can measure honestly.
+ *
+ * The package script is used only for classification. Its flags and shell text are never spliced
+ * into a command: a wrapper or a third runner family is an explicit unsupported result. Vitest in
+ * devDependencies is the sole tie-break when scripts.test is absent; it still maps to the fixed
+ * command template below.
+ */
+export function selectRunner(scriptsTest: string | null, devDeps: readonly string[]): RunnerSelection {
+  const script = typeof scriptsTest === 'string' && scriptsTest.trim() ? scriptsTest.trim() : null;
+  const tokens = script?.split(/\s+/) ?? [];
+
+  /**
+   * СОСТАВНОЙ СКРИПТ — НЕ НЕПОДДЕРЖИВАЕМЫЙ РАННЁР (правка 2026-09-04).
+   *
+   * Пакет, добавивший в `scripts.test` предварительный шаг (`tsc -p … && vitest run`), ТИХО
+   * терял эту заставу целиком: `&&` попадал под общий запрет управляющих символов, и гейт
+   * отказывался с `unsupported-runner:tsc`. ИЗМЕРЕНО 2026-09-04 на этом дереве: 33 простых
+   * скрипта и один составной — и это ровно тот пакет, куда в ту же ночь добавили заставу типов.
+   * То есть починка в одном месте молча выключала проверку в другом.
+   *
+   * ЧТО ПРИ ЭТОМ НЕ ОСЛАБЛЕНО: скрипт ПО-ПРЕЖНЕМУ НИКОГДА НЕ ИСПОЛНЯЕТСЯ. Из него только
+   * ОПОЗНАЁТСЯ раннёр, а запускается наша собственная КОНСТАНТНАЯ команда (`npx vitest run` /
+   * `node --test`). Поэтому разрешён ровно один разделитель — `&&`; любой другой управляющий
+   * символ (`;`, `|`, `$`, обратная кавычка, перенаправление, подоболочка) отказывает как раньше.
+   */
+  const SEGMENT_SEPARATOR = /\s*&&\s*/;
+  const hasForbiddenControl = script !== null && /[\0`$;|<>()\n\r]/.test(script);
+  const hasSingleAmp = script !== null && /(^|[^&])&([^&]|$)/.test(script);
+
+  if (!hasForbiddenControl && !hasSingleAmp) {
+    const segments = (script ?? '').split(SEGMENT_SEPARATOR).map((seg) => seg.trim()).filter(Boolean);
+    const recognised: RunnerSelection[] = [];
+    const skipped: string[] = [];
+    for (const seg of segments) {
+      const t = seg.split(/\s+/);
+      const vitestOffset =
+        t[0] === 'vitest'
+          ? 0
+          : t[0] === 'npx' && t[1] === 'vitest'
+            ? 1
+            : t[0] === 'pnpm' && t[1] === 'exec' && t[2] === 'vitest'
+              ? 2
+              : -1;
+      if (vitestOffset >= 0) {
+        recognised.push({ kind: 'vitest', command: 'npx vitest run', runnerName: 'vitest', how: 'scripts.test' });
+      } else if (t[0] === 'node' && t[1] === '--test') {
+        recognised.push({ kind: 'node-test', command: 'node --test', runnerName: 'node --test', how: 'scripts.test' });
+      } else {
+        skipped.push(seg);
+      }
+    }
+    // Два разных раннёра в одном скрипте — не выбор, а неопределённость: угадывать который из них
+    // «настоящий» значило бы измерять не то, что думает автор.
+    const kinds = new Set(recognised.map((r) => r.kind));
+    const first = recognised[0];
+    if (first !== undefined && kinds.size === 1) {
+      // ПРОПУЩЕННЫЕ ШАГИ НАЗЫВАЮТСЯ, А НЕ ЗАМАЛЧИВАЮТСЯ. Скрипт вида `npm run build && vitest run`
+      // опознаётся, но сборка НЕ выполняется — и если тесты без неё не грузятся, красное будет
+      // СТРУКТУРНЫМ. Гейт такое красное и так не засчитывает за дискриминацию
+      // (`classifyRunFailure` → 'file-load'), но читатель квитанции обязан видеть причину, а не
+      // гадать. Молчаливый пропуск подготовки — это ровно тот «успех из тишины», от которого весь
+      // этот механизм и защищает.
+      return (skipped.length > 0 && (first.kind === 'vitest' || first.kind === 'node-test'))
+        ? { ...first, skippedPreparation: skipped }
+        : first;
+    }
+  }
+
+  const deps = Array.isArray(devDeps) ? devDeps : [];
+  if (script === null && deps.some((dep) => dep === 'vitest')) {
+    return { kind: 'vitest', command: 'npx vitest run', runnerName: 'vitest', how: 'dev-dependency' };
+  }
+
+  return { kind: 'unsupported', runnerName: tokens[0] ?? 'none', scriptsTest: script };
+}
+
+/**
+ * Resolve an audited pre-feature ref supplied by the executor. HEAD never wins over a merge-base.
+ *
+ * `supplied` says whether a human passed `--base`. When it is UNKNOWN, a bare `HEAD` is labelled
+ * `default-head`: the fail-safe direction is to UNDERSTATE provenance, never to overstate it — a
+ * receipt claiming human audit is the one a later reader will cite as proof.
+ */
+export function resolveDiscriminationBaseRef(
+  requestedRef: string,
+  mergeBaseRef?: string,
+  supplied?: boolean,
+): BaseRefResolution {
+  const requested = typeof requestedRef === 'string' ? requestedRef.trim() : '';
+  const mergeBase = typeof mergeBaseRef === 'string' ? mergeBaseRef.trim() : '';
+  if (requested === 'HEAD' && mergeBase) {
+    return { requestedRef: requested, resolvedRef: mergeBase, how: 'merge-base' };
+  }
+  // The label follows the PROVENANCE, not the spelling of the ref. The first version keyed the
+  // downgrade off `requested === 'HEAD'`, and cross-family QE produced the breaker:
+  // `resolveDiscriminationBaseRef('main', undefined, false)` — a ref we KNOW nobody supplied —
+  // came back `explicit-ref`. That is the overstatement this whole change exists to remove, so
+  // keying on the ref was an assumption about callers dressed as a property.
+  if (supplied === true) return { requestedRef: requested, resolvedRef: requested, how: 'explicit-ref' };
+  if (supplied === false) return { requestedRef: requested, resolvedRef: requested, how: 'default-ref' };
+  // Provenance UNKNOWN — and only here is anything inferred, from the one ref that is ever a
+  // default. A real ref had to be typed by someone; `HEAD` is what a tool falls back to. The
+  // inference errs toward understating, which is the direction that cannot forge evidence.
+  if (requested === 'HEAD') return { requestedRef: requested, resolvedRef: requested, how: 'default-ref' };
+  return { requestedRef: requested, resolvedRef: requested, how: 'explicit-ref' };
+}
+
 export interface DiscriminationPlanInput {
   /** the git ref of pre-feature HEAD — the "base" the property test must fail against. */
   readonly baseRef: string;
+  /**
+   * Did a human pass `--base`? Carried so the receipt can say WHERE the base came from. Absent
+   * reads as "not supplied" for a bare HEAD, which understates provenance rather than claiming an
+   * audit that may not have happened.
+   */
+  readonly baseRefSupplied?: boolean;
+  /** merge-base already measured by the executor; mandatory to displace a sweeping HEAD. */
+  readonly mergeBaseRef?: string;
   /** property test(s) mapped from the ADR Confirmation. Empty ⇒ CANNOT_ISOLATE. */
   readonly propertyTests: readonly PropertyTestRef[];
-  /** test-runner command template; sanitized. Default `npx vitest run`. */
+  /** repo-relative directory owning the TARGET package.json; `.` when the repository root owns it. */
+  readonly packageDir?: string;
+  /** TARGET package.json scripts.test. It is classified, never executed verbatim. */
+  readonly packageTestScript?: string | null;
+  /** TARGET package devDependency names, used only for the documented vitest tie-break. */
+  readonly packageDevDependencies?: readonly string[];
+  /** explicit safe escape hatch. Absence derives from packageTestScript; unsafe input refuses. */
   readonly runner?: string;
 }
 
@@ -151,19 +321,33 @@ export interface DiscriminationPlan {
   readonly runnable: boolean;
   /** why not runnable, when `runnable` is false. */
   readonly reason?: string;
+  /** Plan-time state. REFUSE is non-passing; PENDING says execution evidence is still required. */
+  readonly verdict: 'PENDING' | 'REFUSE';
+  /** A plan alone has measured nothing; in particular every refusal is false. */
+  readonly measurementValid: false;
+  readonly primaryAction: PrimaryAction;
   /** the sanitized base ref actually used. */
   readonly baseRef: string;
+  readonly baseRefResolution: BaseRefResolution;
+  readonly runnerSelection: PlannedRunnerSelection;
+  readonly packageDir: string;
   /** the accepted, sanitized targets. */
   readonly targets: readonly PropertyTestRef[];
   /** refs rejected by sanitation, with the reason — surfaced so a rejection is never silent. */
   readonly rejected: readonly { readonly file: string; readonly reason: string }[];
   /**
-   * Ordered shell steps the caller runs: add a detached worktree at baseRef, copy each NEW property test
-   * file into it (they do not exist at base), run the runner over the targets, then remove the worktree.
+   * Ordered shell steps the caller runs: add the complete detached revision at baseRef, run the selected
+   * package-scoped command over positional targets, then remove the worktree. No lone-file tree is valid.
    * `{{WORKTREE}}` is a placeholder the caller substitutes with a fresh temp dir path it owns — the engine
    * never invents a filesystem path. Commands use only sanitized tokens.
    */
   readonly commands: readonly string[];
+  /** The detached worktree itself supplies the complete revision; no lone-file copy is an isolation tree. */
+  readonly isolation: {
+    readonly materialization: 'full-revision-tree';
+    readonly revision: string;
+    readonly overlays: readonly string[];
+  };
 }
 
 export interface ClassifyInput {
@@ -228,7 +412,6 @@ const SAFE_REF = /^[A-Za-z0-9_][A-Za-z0-9_./~^@{}-]{0,199}$/;
  * relative file, and anything exotic is safer rejected (and surfaced) than quoted-and-hoped.
  */
 const UNSAFE_PATH = /(^\/)|(^[A-Za-z]:)|(^~)|(^-)|(\/-)|(\.\.(\/|\\|$))|[\0`$;&|<>*?"'\n\r\t \\]/;
-const DEFAULT_RUNNER = 'npx vitest run';
 /** a runner must be a plain command with flags — no shell metacharacters that could chain a second command. */
 const UNSAFE_RUNNER = /[\0`$;&|<>()\n\r]/;
 
@@ -244,15 +427,42 @@ function sanitizeName(name: string): string | null {
  * ordered worktree commands. Returns `runnable:false` with a reason when there is nothing safe to run.
  */
 export function planDiscriminationCheck(input: DiscriminationPlanInput): DiscriminationPlan {
-  const baseRef = typeof input.baseRef === 'string' ? input.baseRef.trim() : '';
+  const requestedBaseRef = typeof input.baseRef === 'string' ? input.baseRef.trim() : '';
+  const baseRefResolution = resolveDiscriminationBaseRef(requestedBaseRef, input.mergeBaseRef, input.baseRefSupplied);
+  const baseRef = baseRefResolution.resolvedRef;
+  const packageDirRaw = typeof input.packageDir === 'string' ? input.packageDir.trim().replace(/\/$/, '') : '.';
+  const packageDir = packageDirRaw || '.';
   const rejected: { file: string; reason: string }[] = [];
+  const explicitRunner = typeof input.runner === 'string' && input.runner.trim() ? input.runner.trim() : null;
+  const runnerName = explicitRunner?.split(/\s+/)[0] ?? 'none';
+  const runnerSelection: PlannedRunnerSelection = explicitRunner
+    ? { kind: 'explicit', command: explicitRunner, runnerName, how: 'explicit-flag' }
+    : selectRunner(input.packageTestScript ?? null, input.packageDevDependencies ?? []);
+  const isolation = { materialization: 'full-revision-tree', revision: baseRef, overlays: [] } as const;
+
+  const refuse = (reason: string, action: PrimaryAction = 'fix-runner-invocation'): DiscriminationPlan => ({
+    runnable: false,
+    reason,
+    verdict: 'REFUSE',
+    measurementValid: false,
+    primaryAction: action,
+    baseRef,
+    baseRefResolution,
+    runnerSelection,
+    packageDir,
+    targets: [],
+    rejected,
+    commands: [],
+    isolation,
+  });
 
-  if (!SAFE_REF.test(baseRef)) {
-    return { runnable: false, reason: 'unsafe-or-missing-base-ref', baseRef, targets: [], rejected, commands: [] };
+  if (!SAFE_REF.test(requestedBaseRef) || !SAFE_REF.test(baseRef)) {
+    return refuse('unsafe-or-missing-base-ref');
   }
 
-  const runnerRaw = typeof input.runner === 'string' && input.runner.trim() ? input.runner.trim() : DEFAULT_RUNNER;
-  const runner = UNSAFE_RUNNER.test(runnerRaw) ? DEFAULT_RUNNER : runnerRaw;
+  if (packageDir !== '.' && UNSAFE_PATH.test(packageDir)) {
+    return refuse('unsafe-package-dir');
+  }
 
   const targets: PropertyTestRef[] = [];
   const seen = new Set<string>();
@@ -260,6 +470,10 @@ export function planDiscriminationCheck(input: DiscriminationPlanInput): Discrim
     const file = t && typeof t.file === 'string' ? t.file.trim() : '';
     if (!file) { rejected.push({ file: String(t?.file ?? ''), reason: 'empty-path' }); continue; }
     if (UNSAFE_PATH.test(file)) { rejected.push({ file, reason: 'unsafe-path' }); continue; }
+    if (packageDir !== '.' && !file.startsWith(`${packageDir}/`)) {
+      rejected.push({ file, reason: 'outside-target-package' });
+      continue;
+    }
     const name = t && typeof t.name === 'string' ? sanitizeName(t.name) : null;
     if (t && typeof t.name === 'string' && name === null) { rejected.push({ file, reason: 'unsafe-test-name' }); continue; }
     const key = `${file}|${name ?? ''}`;
@@ -269,22 +483,51 @@ export function planDiscriminationCheck(input: DiscriminationPlanInput): Discrim
   }
 
   if (targets.length === 0) {
-    return { runnable: false, reason: 'no-isolable-test', baseRef, targets, rejected, commands: [] };
+    const plan = refuse('no-isolable-test', 'map-a-test');
+    return { ...plan, targets };
+  }
+
+  if (explicitRunner !== null && UNSAFE_RUNNER.test(explicitRunner)) {
+    const plan = refuse(`unsafe-runner:${runnerName}`);
+    return { ...plan, targets };
+  }
+
+  if (runnerSelection.kind === 'unsupported') {
+    const plan = refuse(`unsupported-runner:${runnerSelection.runnerName}`);
+    return { ...plan, targets };
   }
 
   // `{{WORKTREE}}` is substituted by the caller with a temp dir IT owns; the engine never invents a path.
-  // Paths are already metacharacter-free (UNSAFE_PATH), but quote them + use `--` so a leading-dash or spaced
-  // path can never become a runner option or split a word — belt-and-suspenders over the sanitation above.
+  // `git worktree add` materialises the complete base revision. No lone property-test copy is emitted:
+  // a copied test without its sibling source/config tree is not an isolated revision and cannot measure.
   const commands: string[] = [`git worktree add --detach {{WORKTREE}} ${baseRef}`];
-  for (const t of targets) {
-    commands.push(`mkdir -p "{{WORKTREE}}/$(dirname -- '${t.file}')" && cp -- '${t.file}' "{{WORKTREE}}/${t.file}"`);
-  }
-  const fileArgs = [...new Set(targets.map((t) => t.file))].map((f) => `'${f}'`).join(' ');
-  const nameFilters = targets.filter((t) => t.name).map((t) => `-t '${t.name}'`).join(' ');
-  commands.push(`( cd {{WORKTREE}} && ${runner}${nameFilters ? ' ' + nameFilters : ''} -- ${fileArgs} )`);
+  const relativeToPackage = (file: string): string => (packageDir === '.' ? file : file.slice(packageDir.length + 1));
+  const fileArgs = [...new Set(targets.map((t) => relativeToPackage(t.file)))].map((f) => `'${f}'`).join(' ');
+  const testNames = targets.filter((t) => t.name).map((t) => t.name as string);
+  const nameFilters =
+    runnerSelection.kind === 'node-test'
+      ? testNames.map((name) => `--test-name-pattern '${name}'`).join(' ')
+      : testNames.map((name) => `-t '${name}'`).join(' ');
+  const runner = runnerSelection.command;
+  const runnerArgs = `${runner}${nameFilters ? ` ${nameFilters}` : ''} ${fileArgs}`;
+  const worktreePackageDir = packageDir === '.' ? '{{WORKTREE}}' : `{{WORKTREE}}/${packageDir}`;
+  commands.push(`( cd "${worktreePackageDir}" && ${runnerArgs} )`);
   commands.push(`git worktree remove --force {{WORKTREE}}`);
 
-  return { runnable: true, baseRef, targets, rejected, commands };
+  return {
+    runnable: true,
+    verdict: 'PENDING',
+    measurementValid: false,
+    primaryAction: 'none',
+    baseRef,
+    baseRefResolution,
+    runnerSelection,
+    packageDir,
+    targets,
+    rejected,
+    commands,
+    isolation,
+  };
 }
 
 

package/src/event-chain.ts

@@ -224,6 +224,47 @@ export function readTailInfo(tailText: string, opts: { readonly partial?: boolea
 /** An empty log — what an appender assumes when the file is absent. */
 export const EMPTY_LOG_TAIL: LogTail = { lastLine: undefined, endsWithNewline: true, unreadable: false };
 
+/**
+ * ONE journal whose records are hash-chained, and the decision that rests on it.
+ *
+ * `decides` is not documentation garnish: it is the reason integrity matters HERE and not
+ * everywhere. A chain costs nothing to read and something to maintain, so a journal earns one by
+ * being the basis of a verdict — where a lost or duplicated record is a WRONG ANSWER WITH NO
+ * SYMPTOM. A journal nobody decides on does not need a chain, and saying so keeps the registry from
+ * growing into a list of every file we happen to append to.
+ */
+export interface ChainedJournal {
+  /** Path relative to the project root. */
+  readonly rel: string;
+  /** The verdict that would silently go wrong if a record were lost or duplicated. */
+  readonly decides: string;
+}
+
+/**
+ * THE registry of chained journals — the single list every verification surface reads.
+ *
+ * Why this exists (backlog `bc4ee35c`, W0-chain): the chain machinery was built, and then each
+ * consumer grew its OWN private list of which files carry a chain — `dz doctor` had a two-element
+ * array inline, the score aggregate checked its own file, and nothing checked the rest. Three
+ * surfaces, three lists, and no way to ask "are all the chained journals intact?" So a journal
+ * could be given a chain and STILL be checked by nobody: the mechanism present, the coverage
+ * absent, and no red anywhere to say so.
+ *
+ * MEASURED 2026-09-01: of eight append-only journals under `.dz/`, exactly two carry a chain
+ * (probe: `tail -1 <file>` for a `seq` field). Adding the third must be one line HERE, not one line
+ * in each surface — which is the whole point of a registry, and what its test pins.
+ */
+export const CHAINED_JOURNALS: readonly ChainedJournal[] = [
+  {
+    rel: '.dz/recall-usage.jsonl',
+    decides: 'dz compounding — whether a taught lesson is actually paying off',
+  },
+  {
+    rel: '.dz/guard-audit.jsonl',
+    decides: 'dz guard promote — whether a lesson has won twice and may become a rule',
+  },
+];
+
 /**
  * The exact text to append for a run of records: chained, newline-terminated, and preceded by a
  * newline when the file ends mid-line. THE one place that knows how to extend one of these logs —

package/src/feature-adr-routing.ts

@@ -490,31 +490,220 @@ export function qeShouldUseCodex(env: RoutingEnv): boolean {
  *   4. `code`/`qe` `null` sentinels resolve via the coder / cross-model rules
  */
 export function resolveStageModel(stage: string, env: RoutingEnv): StageOpts {
+  return resolveStageDecision(stage, env).opts;
+}
+
+/**
+ * The CLOSED vocabulary of the stage announcement line (historical feature name
+ * stage-line-before-dispatch, ADR-001). Exported as a VALUE so a widened union fails a test rather than passing silently — a
+ * type-only union is invisible at runtime. TWENTY members in three groups:
+ *
+ *  1-8   RESOLVER BRANCHES — the branch of `resolveStageDecision` that chose the spec.
+ *  9-10  SPEC DEGRADATIONS — the two ways `specToOpts` cannot use what a branch chose (an unknown
+ *        codex id substituted for `CODEX_MODEL`; an unrecognised name falling back to
+ *        session-inherited). They evaluate LAST and therefore WIN the label: that the model named
+ *        by the branch is not the model that will run is the one fact the line must never hide.
+ *  11-20 DISPATCH OVERRIDES — facts a PURE resolve cannot know, emitted only by the workflow at the
+ *        dispatch site, and the reason the count grew from ten (cross-family review of 3fc406db):
+ *          `coder-fallback`                — the codex-fallback LADDER, not the resolver, decides
+ *            which family runs first: the resolver picks Codex, the runtime tries Claude first and
+ *            only reaches Codex if Claude returns null. Each rung is a real dispatch and gets its
+ *            own line, so the reader is never told Codex is running while Claude is.
+ *          `codex-unsupported-at-dispatch` — the stage refuses the codex wrapper outright (a
+ *            data-returning stage; the wrapper stubs, per the codex-routing-honesty ADR), so a
+ *            resolved codex spec is discarded and the dispatch runs Claude.
+ *          `fallback-after-no-deliverable`  — a previous RUNG of this stage ran and produced nothing
+ *            usable (a Codex plan/design artifact that never landed; a Codex reviewer that returned
+ *            no verdict), so the next rung dispatches. Each rung is a real dispatch and is announced
+ *            on its own, because `modelsUsed` was already being rewritten there and the line was not.
+ *          `precision-second-pass`          — the optional A-normal L/XL Claude precision reviewer that
+ *            runs AFTER the recall-oriented primary QE pass. It is a separate dispatch with its own
+ *            `modelsUsed.qe2` entry, chosen by `qePrecisionPassSpec`, not by the stage resolver.
+ *          `qe-same-family-degraded`         — the QE branch resolved a reviewer of the SAME family as
+ *            the coder. It happens when the coder is Claude and codex is unavailable: `resolveQeSpec`
+ *            falls back to Claude `opus` rather than blocking, so cross-family review is LOST at that
+ *            moment. The branch used to emit `qe-cross-family` regardless, and the line then claimed
+ *            "the coder never self-reviews" about a Claude-on-Claude review. The reason is now DERIVED
+ *            from the resolved families, never assumed from the branch.
+ *          `challenge-panel`                — the Step-6 adversarial plan gate. Its adversary is chosen
+ *            as the OTHER family than the plan's AUTHOR, and its cross-validator re-checks the
+ *            findings; both are substantive model reviews that decide the gate's verdict, not probes.
+ *          `codex-refused-before-dispatch`   — an id ANSWERED the probe, but the rung then declined to
+ *            build a dispatch at all: an unusable review scope ref (`codexReviewCommand` returns
+ *            `cmd:null`), an unsafe id at command-build time, or a declined exec plan. No agent ran,
+ *            so the next rung is NOT a `fallback-after-no-deliverable` — that reason asserts a rung
+ *            RAN and produced nothing, which is a false dispatch claim. Rounds 16-17 modelled this
+ *            outcome with a BOOLEAN `probeFailed`, whose else-branch swallowed every non-probe
+ *            refusal into the "it ran" bucket; the outcome is three-valued and is now carried as such.
+ *          `codex-probe-failed`             — a DIRECT `agent()` dispatch resolved to codex, but no id
+ *            answered the probe. `safeCodexAgent` refuses by returning null; a direct path has no
+ *            wrapper to return from, so it falls back to Claude and says so rather than dispatching
+ *            an unprobed spec while the line claims a model nothing verified.
+ *          `fallback-rung`                  — the CURRENT attempt is a fallback. The prior attempt's
+ *            exact outcome is emitted on that prior rung's outcome line and is never copied into
+ *            this attempt's intent.
+ *          `auto-cost`                      — learned-cost routing chose this model. `resolveAutoCost`
+ *            REWRITES `args.models[stage]` from the `auto-cost` token to the selected concrete model
+ *            BEFORE the resolver runs, so the explicit-models branch fires and the line would credit
+ *            an operator who never named that model. The selection is recovered from the run's own
+ *            auto-cost ledger, so the line reports the branch that actually decided.
+ *        `resolveStageDecision` NEVER returns ANY of these ten — asserted by its own test. A resolver
+ *        that could emit them would be claiming resolver authority over a runtime fact.
+ */
+export const STAGE_DECISION_REASONS: readonly StageDecisionReason[] = [
+  'usage-override',
+  'explicit-models',
+  'routing-not-requested',
+  'coder-knob-codex',
+  'planner-knob-codex',
+  'qe-cross-family',
+  'budget-table-cell',
+  'default-models',
+  'codex-id-substituted',
+  'spec-unrecognised',
+  'coder-fallback',
+  'codex-unsupported-at-dispatch',
+  'fallback-after-no-deliverable',
+  'precision-second-pass',
+  'auto-cost',
+  'qe-same-family-degraded',
+  'challenge-panel',
+  'codex-probe-failed',
+  'codex-refused-before-dispatch',
+  'fallback-rung',
+];
+
+export type StageDecisionReason =
+  | 'usage-override'
+  | 'explicit-models'
+  | 'routing-not-requested'
+  | 'coder-knob-codex'
+  | 'planner-knob-codex'
+  | 'qe-cross-family'
+  | 'budget-table-cell'
+  | 'default-models'
+  | 'codex-id-substituted'
+  | 'spec-unrecognised'
+  | 'coder-fallback'
+  | 'codex-unsupported-at-dispatch'
+  | 'fallback-after-no-deliverable'
+  | 'precision-second-pass'
+  | 'auto-cost'
+  | 'qe-same-family-degraded'
+  | 'challenge-panel'
+  | 'codex-probe-failed'
+  | 'codex-refused-before-dispatch'
+  | 'fallback-rung';
+
+/** What the resolver decided AND why. `spec` is the EFFECTIVE spec (derived from `opts`), never the
+ * requested-but-substituted one — a line naming a model the run did not use would be worse than no
+ * line at all. */
+export interface StageDecision {
+  readonly opts: StageOpts;
+  readonly spec: string | null;
+  readonly reason: StageDecisionReason;
+}
+
+/** The model FAMILY a resolved spec belongs to. */
+export function specFamily(spec: string | null | undefined): 'codex' | 'claude' {
+  return (spec && String(spec).split(':')[0] === 'codex') ? 'codex' : 'claude';
+}
+
+/**
+ * The QE branch's reason, DERIVED from the families that actually resolved rather than assumed from
+ * the branch. `resolveQeSpec` degrades to a Claude reviewer when codex is unavailable (it must never
+ * block), and a Claude coder then gets a Claude reviewer — cross-family review is lost, and saying
+ * otherwise would assert the one property that just failed.
+ */
+export function qeReasonForFamilies(coderCodex: boolean, qeSpec: string | null | undefined): StageDecisionReason {
+  if (specFamily(qeSpec) === (coderCodex ? 'codex' : 'claude')) return 'qe-same-family-degraded';
+  return 'qe-cross-family';
+}
+
+/** The compact spec that `opts` actually represents. Inverse of `specToOpts` over the applied opts. */
+export function effectiveSpec(opts: StageOpts): string | null {
+  if (opts && opts.agentType === 'codex:codex-rescue') return 'codex:' + opts.codexModel + ':' + opts._reasoning;
+  if (opts && opts.model) return opts.model;
+  return null;
+}
+
+/**
+ * Did `specToOpts` DEGRADE this spec? It NAMES what specToOpts already did — it changes nothing.
+ *
+ * The codex arm compares the EFFECTIVE id against the REQUESTED one rather than re-deriving the
+ * condition. MEASURED 2026-09-05: re-deriving claimed a substitution whenever the requested id was
+ * unknown — but `specToOpts` replaces it with `CODEX_MODEL`, and when that default is ITSELF unknown
+ * the replacement is the same string. A sweep over 11 stages x 4 specs x 4 defaults found 22 such
+ * outcomes, each announcing a substitution while dispatching the very id the operator asked for.
+ * Comparing the applied value cannot make that mistake.
+ */
+function specDegradation(spec: string | null | undefined, opts: StageOpts, env: RoutingEnv): StageDecisionReason | null {
+  if (!spec) return null;
+  const parts = String(spec).split(':');
+  const head = parts[0] || '';
+  if (head === 'codex') {
+    const requested = parts[1] || env.CODEX_MODEL;
+    if (opts.codexModel !== requested) return 'codex-id-substituted';
+    return null;
+  }
+  if (!CLAUDE_NAMES[head]) return 'spec-unrecognised';
+  return null;
+}
+
+/** Wrap resolved opts into a decision, letting a spec DEGRADATION rename the branch (see above). */
+function decisionFor(base: StageDecisionReason, spec: string | null | undefined, opts: StageOpts, env: RoutingEnv): StageDecision {
+  const deg = specDegradation(spec, opts, env);
+  if (deg !== null) return { opts: opts, spec: effectiveSpec(opts), reason: deg };
+  return { opts: opts, spec: effectiveSpec(opts), reason: base };
+}
+
+/** The two `null` SENTINEL fall-throughs (`code`/`qe` whose chosen spec is `null` ⇒ derive it),
+ * shared by the explicit-models and table paths so the branch that CHOSE the spec keeps the label. */
+function decideFromSpec(base: StageDecisionReason, stage: string, spec: string | null | undefined, env: RoutingEnv): StageDecision {
+  if (stage === 'code' && (spec === null || spec === undefined)) {
+    const s = resolveCoderSpec(env);
+    return decisionFor(base, s, specToOpts(s, env), env);
+  }
+  if (stage === 'qe' && (spec === null || spec === undefined)) {
+    const s = resolveQeSpec(env);
+    return decisionFor(base, s, specToOpts(s, env), env);
+  }
+  return decisionFor(base, spec, specToOpts(spec, env), env);
+}
+
+/**
+ * Resolve a stage to its `agent()` opts fragment AND the branch that decided it (ADR-001: the
+ * reason lives where the decision is made — otherwise it is a copy, and copies drift).
+ * `resolveStageModel` is now a thin wrapper over `.opts`, so the opts are byte-identical by
+ * construction, not by a second reading of the same rules.
+ */
+export function resolveStageDecision(stage: string, env: RoutingEnv): StageDecision {
   if (env.usageOverride) {
     const r = (env.usageReasoning && env.usageReasoning[stage]) || STAGE_EFFORT.override[stage] || 'medium';
-    const o = specToOpts('codex:' + topCodexId(env) + ':' + r, env);
+    const s = 'codex:' + topCodexId(env) + ':' + r;
+    const o = specToOpts(s, env);
     o._usageSwitched = true;
-    return o;
+    return decisionFor('usage-override', s, o, env);
   }
-  let spec = env.MODELS[stage];
-  if (spec === undefined) {
-    if (!routingRequested(env)) return {};
-    if (stage === 'code' && (env.CODER === 'codex' || env.CODER === 'codex-fallback')) {
-      return specToOpts(resolveCoderSpec(env), env);
-    }
-    if (stage === 'plan' && env.PLANNER === 'codex') {
-      return specToOpts('codex:' + env.CODEX_MODEL + ':high', env);
-    }
-    if (stage === 'qe') {
-      return specToOpts(resolveQeSpec(env), env);
-    }
-    const resolvedPrimary = env.primary || 'claude';
-    const cell = budgetTable(resolvedPrimary, resolveBudgetMode(env.budget), env)[stage];
-    spec = cell !== undefined ? cell : DEFAULT_MODELS[stage];
+  const spec = env.MODELS[stage];
+  if (spec !== undefined) return decideFromSpec('explicit-models', stage, spec, env);
+  if (!routingRequested(env)) return { opts: {}, spec: null, reason: 'routing-not-requested' };
+  if (stage === 'code' && (env.CODER === 'codex' || env.CODER === 'codex-fallback')) {
+    const s = resolveCoderSpec(env);
+    return decisionFor('coder-knob-codex', s, specToOpts(s, env), env);
+  }
+  if (stage === 'plan' && env.PLANNER === 'codex') {
+    const s = 'codex:' + env.CODEX_MODEL + ':high';
+    return decisionFor('planner-knob-codex', s, specToOpts(s, env), env);
   }
-  if (stage === 'code' && (spec === null || spec === undefined)) return specToOpts(resolveCoderSpec(env), env);
-  if (stage === 'qe' && (spec === null || spec === undefined)) return specToOpts(resolveQeSpec(env), env);
-  return specToOpts(spec, env);
+  if (stage === 'qe') {
+    const s = resolveQeSpec(env);
+    return decisionFor(qeReasonForFamilies(coderIsCodex(env), s), s, specToOpts(s, env), env);
+  }
+  const resolvedPrimary = env.primary || 'claude';
+  const cell = budgetTable(resolvedPrimary, resolveBudgetMode(env.budget), env)[stage];
+  if (cell !== undefined) return decideFromSpec('budget-table-cell', stage, cell, env);
+  return decideFromSpec('default-models', stage, DEFAULT_MODELS[stage], env);
 }
 
 /**
@@ -1484,9 +1673,18 @@ export function codexExecPlan(input: CodexExecPlanInput): CodexExecPlanResult {
   return { mode: 'exec', reason: 'codex exec on ' + input.probedId };
 }
 
-/** A model id is user input (`args.codexModel`) and lands in a shell command. Shell-safe ids only. */
+/**
+ * A model id is user input (`args.codexModel`) and lands in a shell command. Shell-safe ids only.
+ *
+ * The `typeof` guard is LOAD-BEARING, not defensive noise (MEASURED 2026-09-05 while building the
+ * concurrent-probe test): `RegExp.test` coerces, so `test(null)` tested the string `'null'` — which
+ * matches this very pattern. `safeCodexAgent` passes `null` for the default `codexModel: 'auto'`, so
+ * the probe ladder collapsed from `[flagship, gpt-5.5]` to the single literal id `"null"`, asked for
+ * a model that cannot exist, and reported Codex UNAVAILABLE on the default path. Every 'auto' codex
+ * route silently degraded to Claude, for a reason nothing in the run could show.
+ */
 export function isSafeCodexId(id: string): boolean {
-  return /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(id);
+  return typeof id === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(id);
 }
 
 /**