@event4u/agent-config 16.0.0 → 16.2.0

package/src/scripts/hooks/turn_end_gate_hook.ts

@@ -32,11 +32,11 @@
  *
  * TWO of the five are CONDITIONAL, and saying "unconditional" here would be the
  * same stale-header defect this block corrects below. A and D are the
- * completion-adjacent pair an open subagent dispatch excuses, so `main()` runs
- * them only when `dispatchOpen` is false; B, C and E run on every turn-end. That
- * narrowing is deliberate (Phase 3 Step 2, narrowed again by R2 round 2) and is
- * the third allow path, alongside the two re-entrancy layers — see the
- * per-detector list in `main()`.
+ * completion-adjacent pair an open subagent dispatch excuses, so `runDetectors()`
+ * runs them only when `dispatchOpen` is false; B, C and E run on every turn-end.
+ * That narrowing is deliberate (Phase 3 Step 2, narrowed again by R2 round 2) and
+ * is the third allow path, alongside the two re-entrancy layers — see the
+ * per-detector list in `runDetectors()`.
  *
  * This block said "Three" and listed A/B/C until 2026-08-18, while `DetectorId`
  * below has carried four since round 7. `DETECTOR_IDS` in
@@ -154,7 +154,6 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import {
     classify,
     hasStableSessionId,
-    isSyntheticPrompt,
     statePathFor as languageStatePathFor,
     type Verdict,
 } from '../language_mirror_hook.js';
@@ -163,7 +162,15 @@ import {
 // write" is only true while the two agree, and importing a constant made that
 // agreement invisible when the producer's layout moved. A builder makes the move
 // a type error.
-import { statePathFor as ciStatePathFor } from '../before_complete_hook.js';
+import {
+    statePathFor as ciStatePathFor,
+    readTurnRunState,
+    type TurnRunState,
+} from '../before_complete_hook.js';
+// Re-exported: two test files address `readTurnRunState` at this path, and a
+// reader arriving at detector C should find the reader where the detector uses
+// it. The DEFINITION lives with the producer of the shape it reads.
+export { readTurnRunState };
 // The spec-backed options-block reading, imported rather than re-derived:
 // `user-interaction` Iron Law 1's definition of an ask — a block PLUS its
 // recommendation line — lives in exactly one place and detector E reads it from
@@ -179,9 +186,18 @@ import { statePathFor as ciStatePathFor } from '../before_complete_hook.js';
 // Detector E, extracted to `_lib` where its prose costs no ratchet debt.
 // Re-exported so every existing importer of this module is unchanged.
 import { detectDroppedDecision } from '../_lib/dropped_decision.js';
+import { isVerificationCommand } from '../_lib/verification_command.js';
+// Round 8 — the record path detector C prefers over its own regex. The regex
+// reads a command's TEXT and `echo test` matches it; these read what the run
+// exited with and what it printed.
+import {
+    NO_RED_EVIDENCE_REASON,
+    describeRecordFinding as recordReason,
+    hasRedThenGreen,
+    readRunEvidence,
+} from '../_lib/verification_evidence.js';
 
 export { detectDroppedDecision };
-import { isSafeTranscriptPath } from './end_review_nudge_hook.js';
 import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
 import { readHookStdin } from './hook_stdin.js';
 import {
@@ -193,18 +209,23 @@ import { openRecordStats } from './subagent_ledger_hook.js';
 import {
     deriveSessionKey,
     foldRefusal,
+    foldShadow,
     parseRecord,
+    parseShadowRecord,
     readInstallBoundary,
     sessionRefusalFile,
+    sessionShadowFile,
     type RefusalRecord,
+    type ShadowLayer,
+    type ShadowRecord,
 } from '../_lib/turn_end_refusals.js';
+import { EXIT_ALLOW, EXIT_BLOCK } from './exit_codes.js';
 
 /** Dispatcher-internal block code. Pinned to 1 by `concern_block_exit_parity`. */
-const EXIT_BLOCK = 1;
-const EXIT_ALLOW = 0;
 
 /**
- * Transcript-read ceiling for this hook, passed at the call site in `main()`.
+ * Transcript-read ceiling for this hook, passed at its one production call
+ * site, `assembleDetectorInputs()`.
  * Deliberately well under `isSafeTranscriptPath`'s own 50 MB refusal: the
  * ordinal is a count over every entry, so the whole file is walked once per
  * turn-end, and a session file grows for the life of the session. Past this the
@@ -227,6 +248,18 @@ export interface Finding {
     /** The span that triggered it — quoted back so the refusal is actionable. */
     evidence: string;
     reason: string;
+    /**
+     * Which evidence path produced this finding, where a detector has two.
+     *
+     * Detectors C and F set it — the sentence here read "Only detector C" while
+     * F set it two functions below, which an independent review caught.
+     * `record` means a persisted run record was read;
+     * `transcript` means the recorder left nothing for this turn and the
+     * command-text scan answered instead — the mode a replay through
+     * `measure_turn_end_gate` / `check_detector_corpus` always runs in, so a
+     * corpus reading stays reproducible after the record path landed.
+     */
+    mode?: 'record' | 'transcript';
 }
 
 // ---------------------------------------------------------------------------
@@ -487,6 +520,7 @@ export function readCiSettled(
     return { seen: false, settled: false };
 }
 
+
 /**
  * A completion claim in the delivered reply. Deliberately narrow: the German and
  * English closings the corpus actually produced, anchored to a line so a mid-reply
@@ -656,62 +690,14 @@ export function detectLanguage(reply: string, pinned: Verdict): Finding | null {
 const _EDIT_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
 
 /**
- * Shell commands that count as verification.
- *
- * A positive list, and deliberately narrow. The alternative — treating any
- * `Bash` call as verification — was rejected because `ls` would then clear an
- * unverified edit, which is the failure mode `verify-before-complete` names
- * ("relying on partial verification"). The cost of narrowness is a MISSED
- * detection when a project verifies by some command not listed here, and that is
- * the safe direction for a gate that can refuse a turn: a false negative costs
- * one unguarded turn, a false positive teaches the user to switch the gate off.
- *
- * ## Audited 2026-08-17 — `road-to-stop-gate-honesty` step 2.2
- *
- * 52 commands this project's own surface actually produces (its `package.json`
- * scripts, its `Taskfile` targets, `./scripts-run`, `./agent-config`, and the
- * PHP / Python / Go / Rust toolchains) were run through
- * `isVerificationCommand`. The table of every one, with its verdict, is
- * `turn_end_verify_allowlist.test.ts`; that file is the fixture step 2.2
- * requires, and every addition below has its own row in it.
- *
- * The draft that opened the roadmap expected to add `phpunit` and `pest`. Claim
- * 4 had already overtaken that — both matched before this audit, as did
- * `composer test` and `php artisan test` — so what the audit actually found was
- * two different gaps:
- *
- *   · `phpstan` — a static analyser of exactly the class already listed
- *     (`mypy`, `pyright`, `clippy`). Added.
- *   · `lint` followed by a WORD character — `lint_persistence`,
- *     `lint_provenance`, and every other `lint_*` script in `src/scripts/`
- *     missed, because `\blint\b` needs a boundary and `_` is a word character.
- *     `lint[-_:a-z]*` is the exact mirror of the `check[-_:a-z]*` this list
- *     already carried, which is why it is the narrow fix rather than a new idea.
+ * Re-exported, not re-derived: the selector moved to `_lib/verification_command.ts`
+ * so the evidence classifier can read it without a hook<->lib import cycle.
  *
- * Four further misses were found and deliberately NOT added, because Risk 2 of
- * that roadmap is that every addition is a way to satisfy the gate without
- * verifying anything:
- *
- *   · `npm run prepack` — a lifecycle hook whose content is per-project. Here it
- *     validates; elsewhere it copies files. Recognising it would clear an
- *     unverified edit in any repo whose prepack is a build step.
- *   · `task sync` / `task generate-tools` / `agent-config roadmap:progress` —
- *     GENERATORS. They rewrite the tree; they check nothing. A generator that
- *     cleared the gate would be the rubber stamp in its purest form.
- *   · `agent-config gates --all` — enumerates gates, runs none.
- *   · `vendor/bin/rector process --dry-run` — a refactoring tool. Its dry run
- *     prints a diff; it does not assert anything holds.
- *
- * `psalm` is the obvious sibling of `phpstan` and is also NOT added: nothing in
- * the audited surface runs it, and "the team actually runs" is the step's own
- * standard. It is named here so the next audit does not re-derive the question.
+ * The name stays exported HERE because two test files pin it at this path and
+ * because a reader arriving at detector C should find the selector where the
+ * detector uses it, not have to know it was relocated.
  */
-const _VERIFY_RE =
-    /\b(test|tests|vitest|jest|pytest|phpunit|pest|tsc|eslint|ruff|mypy|pyright|clippy|phpstan|typecheck|lint[-_:a-z]*|build|ci|preflight|smoke[-_:a-z]*|check[-_:a-z]*|validate[-_:a-z]*)\b|\b(task|npm|pnpm|yarn|composer|cargo|go|make|php artisan|bun)\s+(run\s+)?\S*(test|check|lint|build|ci|typecheck)/i;
-
-export function isVerificationCommand(command: string): boolean {
-    return _VERIFY_RE.test(command);
-}
+export { isVerificationCommand };
 
 /**
  * Fire when the turn changed a file and then ran nothing that could have
@@ -728,28 +714,55 @@ export function isVerificationCommand(command: string): boolean {
  * no claim to verify, and refusing one would make the gate fire on the majority
  * of turns, which is how a guard gets disabled.
  */
-export function detectUnverifiedEdit(toolCalls: readonly ToolCall[]): Finding | null {
+export function detectUnverifiedEdit(
+    toolCalls: readonly ToolCall[],
+    runState: TurnRunState | null = null,
+): Finding | null {
     let lastEdit = -1;
     for (let i = 0; i < toolCalls.length; i += 1) {
         if (_EDIT_TOOLS.has(toolCalls[i]!.name)) lastEdit = i;
     }
     if (lastEdit === -1) return null;
+    const edited = toolCalls[lastEdit]!.path ?? toolCalls[lastEdit]!.name;
+
+    // THE RECORD PATH. Preferred whenever the recorder demonstrably witnessed
+    // this turn — see `readTurnRunState`, which returns null otherwise. The
+    // regex path below stays reachable and is not deprecated: it is the only
+    // path a transcript replay has, and it is what a host that binds no
+    // `post_tool_use` slot keeps.
+    if (runState !== null) {
+        const reading = readRunEvidence(runState);
+        if (reading.passed) return null;
+        // An instrument gap is never refused on (Risk 1 of the plan): the host
+        // surfaced no exit code, or wrote a record nothing can place, and
+        // neither is a fact about the operator's work. The transcript answer
+        // stands in, which is exactly the behavior before this path existed.
+        if (!reading.instrumentGap) {
+            return {
+                detector: 'verification',
+                evidence: edited,
+                reason: recordReason(reading.failed, reading.reasons),
+                mode: 'record',
+            };
+        }
+    }
+
     for (let i = lastEdit + 1; i < toolCalls.length; i += 1) {
         const c = toolCalls[i]!;
         if (c.name === 'Bash' && c.command !== undefined && isVerificationCommand(c.command)) {
             return null;
         }
     }
-    const edited = toolCalls[lastEdit]!.path;
     return {
         detector: 'verification',
         // The path, never the diff: the evidence span is quoted into a refusal,
         // and `ToolCall` is shaped so a file body cannot reach it.
-        evidence: edited ?? toolCalls[lastEdit]!.name,
+        evidence: edited,
         reason:
             'this turn changed a file and then ran no verification command — ' +
             'no test, type-check, lint or build call follows the last edit ' +
             '(verify-before-complete: a claim without a fresh run is unverified)',
+        mode: 'transcript',
     };
 }
 
@@ -827,13 +840,55 @@ function _isProductionSource(p: string): boolean {
  * turn; drop the second and it fires on a turn that did its job; drop the third
  * and it fires mid-cycle on the red step of red-green-refactor.
  */
-export function detectUntestedChange(reply: string, toolCalls: readonly ToolCall[]): Finding | null {
+export function detectUntestedChange(
+    reply: string,
+    toolCalls: readonly ToolCall[],
+    runState: TurnRunState | null = null,
+): Finding | null {
     const edited = toolCalls
         .filter((c) => _EDIT_TOOLS.has(c.name) && c.path !== undefined)
         .map((c) => c.path as string);
     const source = edited.filter(_isProductionSource);
     if (source.length === 0) return null;
-    if (edited.some(_isTestPath)) return null;
+
+    // THE TEST-FILE ESCAPE, and why step 5.1 narrowed it rather than removed it.
+    //
+    // "A test file was touched somewhere in the turn" is satisfied by a file
+    // containing `it('works', () => expect(true).toBe(true))`. A test never seen
+    // red has unknown sensitivity — it may assert nothing the change could
+    // break — so the escape as written accepted the shape of evidence instead of
+    // evidence.
+    //
+    // With records available, the escape asks for the cheapest observable proof
+    // that the assertion discriminates: the same target red, then green after
+    // the last edit. Without records it stays exactly as it was, because the
+    // transcript cannot see an exit code and a detector that refused on a
+    // transcript-only host would refuse every honest turn there.
+    // A NEW test file, not any test edit. Step 5.1 says "accepts a NEW test file
+    // only with that pair present", and `edited.some(_isTestPath)` is any
+    // test-path edit — so adjusting an assertion in an existing test alongside a
+    // production change and running it green once was refused. New-vs-existing
+    // is not decidable from a transcript; `Write` on a test path is the usable
+    // proxy, because `Edit` and `MultiEdit` presuppose a file that already
+    // existed. Narrowing here can only ALLOW turns the previous line refused.
+    const wroteNewTest = toolCalls.some(
+        (c) => c.name === 'Write' && c.path !== undefined && _isTestPath(c.path),
+    );
+    let noRedEvidence = false;
+    if (edited.some(_isTestPath)) {
+        // An EXISTING test adjusted alongside a production change keeps the old
+        // escape untouched — `Edit` and `MultiEdit` presuppose a file that was
+        // already there, so nothing new was claimed and there is no new
+        // assertion whose sensitivity is unknown.
+        if (!wroteNewTest) return null;
+        if (runState === null) return null;
+        if (hasRedThenGreen(runState)) return null;
+        // An instrument gap is not a missing red. Same rule as detector C: the
+        // host surfaced no exit code, so nothing about the operator's work is
+        // known, and the pre-record behavior stands in.
+        if (readRunEvidence(runState).instrumentGap) return null;
+        noRedEvidence = true;
+    }
 
     // The claim gate, reusing detector D's pair rather than a second dialect of
     // "done" — two lists of completion phrasings would drift, and the negation
@@ -844,8 +899,21 @@ export function detectUntestedChange(reply: string, toolCalls: readonly ToolCall
     if (_NEGATED_CLAIM_RE.test(_lineAround(prose, m.index))) return null;
 
     const shown = source.slice(0, 3).join(', ');
+    if (noRedEvidence) {
+        return {
+            detector: 'untested',
+            evidence: shown + (source.length > 3 ? ` (+${String(source.length - 3)} more)` : ''),
+            mode: 'record',
+            reason: NO_RED_EVIDENCE_REASON,
+        };
+    }
+    // `transcript` unconditionally: no record contributed to THIS verdict — it
+    // is reached because the turn touched no test file at all, which is read off
+    // the tool calls. Labelling it `record` because a run state happened to be
+    // available would misattribute the evidence.
     return {
         detector: 'untested',
+        mode: 'transcript',
         evidence: shown + (source.length > 3 ? ` (+${String(source.length - 3)} more)` : ''),
         reason:
             'a completion claim over production code this turn changed, with NO test file ' +
@@ -984,199 +1052,20 @@ function markRefusedTurn(
 // Transcript
 // ---------------------------------------------------------------------------
 
-/**
- * One tool call the assistant made, reduced to what a detector can reason
- * about: the tool's name, the shell command when it is a shell call, and the
- * target path when it is a file write.
- *
- * Nothing else is kept. A tool input can hold a whole file body, and this
- * struct is what a refusal quotes back — so it is shaped to be INCAPABLE of
- * carrying one, the same PII-exclusion-by-construction discipline
- * `domain-safety-pii` § Surface 2 asks for in a log line.
- */
-export interface ToolCall {
-    name: string;
-    /** `Bash` only — the command line, so "did anything verify" is answerable. */
-    command?: string;
-    /** Edit/Write only — the file the turn changed, used as the evidence span. */
-    path?: string;
-}
-
-export interface TranscriptTail {
-    lastAssistant: string;
-    /**
-     * Every assistant text of the CURRENT turn, in order — reset at each genuine
-     * user prompt exactly like `toolCalls`, and for the same reason: a question
-     * asked three turns ago was answered, a question asked earlier in THIS turn
-     * was not. Detector E reads it; the other four read `lastAssistant`, which is
-     * always the last element when this is non-empty.
-     *
-     * A tool-only assistant entry contributes NOTHING here. `_messageText`
-     * returns null for it and the collector skips it, so the ordinary shape of a
-     * working turn — prose, tool call, prose — produces two elements and not
-     * three. That is the whole false-positive surface of detector E, and it is
-     * closed here rather than in the detector.
-     */
-    assistantTurnTexts: string[];
-    /**
-     * How many GENUINE user prompts the transcript carries — harness-injected
-     * user-role entries excluded via `isSyntheticPrompt`. This is the turn's
-     * identity; see `alreadyRefusedTurn` for why the prompt's text is not.
-     */
-    turnOrdinal: number;
-    /**
-     * The tool calls of the CURRENT turn, in order — reset at every genuine user
-     * prompt, so a verification from three turns ago cannot vouch for an edit
-     * made now. `_messageText` keeps only `type === 'text'` blocks, which is why
-     * this needed its own extraction rather than a reading of `lastAssistant`:
-     * tool activity is not in the prose at all.
-     */
-    toolCalls: ToolCall[];
-}
-
-/**
- * The last assistant text, plus the turn ordinal, from a Claude JSONL
- * transcript. Mirrors `chat_history._extract_claude_transcript_response` for
- * the assistant half.
- *
- * `isSyntheticPrompt` is applied to every user-role entry — the same filter
- * `language_mirror_hook` uses, and for the same reason it was added there
- * (round-5 § 6.5): a background-task notification and a `<system-reminder>`
- * both occupy the user role without being chat messages. Counting them would
- * move the turn ordinal mid-turn, which is R2 finding 3.
- */
-export function readTranscriptTail(
-    transcriptPath: string,
-    opts: { homeDir?: string; maxBytes?: number } = {},
-): TranscriptTail {
-    const empty: TranscriptTail = {
-        lastAssistant: '',
-        turnOrdinal: 0,
-        toolCalls: [],
-        assistantTurnTexts: [],
-    };
-    if (!transcriptPath || !isSafeTranscriptPath(transcriptPath, opts)) return empty;
-    let lines: string[];
-    try {
-        // R2 finding 12: `maxBytes` was accepted in the options type and never
-        // used, so the declared cap was decoration. It is enforced here as well
-        // as inside `isSafeTranscriptPath`, because this is the read it bounds.
-        // The whole file still has to be walked — the turn ordinal is a count
-        // over all entries, not something a tail can answer — so the cap is the
-        // guard, not an optimisation.
-        if (opts.maxBytes !== undefined && fs.statSync(transcriptPath).size > opts.maxBytes) {
-            return empty;
-        }
-        lines = fs.readFileSync(transcriptPath, 'utf-8').split('\n');
-    } catch {
-        return empty;
-    }
-    let lastAssistant = '';
-    let turnOrdinal = 0;
-    let toolCalls: ToolCall[] = [];
-    let assistantTurnTexts: string[] = [];
-    for (const rawLine of lines) {
-        const line = rawLine.trim();
-        if (!line) continue;
-        let obj: unknown;
-        try {
-            obj = JSON.parse(line);
-        } catch {
-            continue;
-        }
-        if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) continue;
-        const entry = obj as Record<string, unknown>;
-        // Sidechain entries are a SUBAGENT's conversation recorded in the same
-        // JSONL. A subagent prompt is a genuine-looking user-role text entry
-        // appended mid-turn, so counting it moves the ordinal within the turn —
-        // finding 3's failure class in a new shape (R2 round 2, finding 3).
-        if (entry['isSidechain'] === true) continue;
-        const role = entry['type'];
-        if (role !== 'assistant' && role !== 'user') continue;
-        const msg = entry['message'];
-        if (typeof msg !== 'object' || msg === null || Array.isArray(msg)) continue;
-        const content = (msg as Record<string, unknown>)['content'];
-        // Tool calls are read BEFORE the text guard: an assistant entry that is
-        // only a tool_use block has no text at all, so `continue`-ing on a null
-        // text would drop exactly the entries this detector exists to see.
-        if (role === 'assistant') {
-            toolCalls.push(...extractToolCalls(content));
-        }
-        const text = _messageText(content);
-        if (text === null) continue;
-        if (role === 'assistant') {
-            lastAssistant = text;
-            assistantTurnTexts.push(text);
-        } else if (!isSyntheticPrompt(text)) {
-            turnOrdinal += 1;
-            // A genuine user prompt starts a new turn, so the previous turn's
-            // tool activity stops counting. Without this reset, a verification
-            // run three turns ago would vouch for an edit made now — the
-            // "fresh" in edit-without-FRESH-verification is this line.
-            toolCalls = [];
-            // Same boundary, same reason, for detector E: an options block the
-            // user has since replied to is answered, not dropped. Resetting on
-            // the identical line is what makes "in the SAME user turn" true of
-            // the array rather than merely intended.
-            assistantTurnTexts = [];
-        }
-    }
-    return {
-        lastAssistant: lastAssistant.trim(),
-        turnOrdinal,
-        toolCalls,
-        assistantTurnTexts,
-    };
-}
-
-/**
- * Extract this entry's tool calls, keeping only name, shell command and target
- * path. A tool input can hold a whole file body; nothing but those three fields
- * is carried forward.
- *
- * Exported because `measure_turn_end_gate` scores detectors C and E over a real
- * transcript corpus and therefore has to rebuild the same `ToolCall[]` the gate
- * sees. A second extractor there would be a second dialect of "what the turn
- * did", and the measurement would then be of that dialect rather than of the
- * shipped gate — the exact population-parity defect that script's own header
- * documents twice.
- */
-export function extractToolCalls(content: unknown): ToolCall[] {
-    if (!Array.isArray(content)) return [];
-    const out: ToolCall[] = [];
-    for (const blk of content) {
-        if (typeof blk !== 'object' || blk === null || Array.isArray(blk)) continue;
-        const b = blk as Record<string, unknown>;
-        if (b['type'] !== 'tool_use') continue;
-        const name = b['name'];
-        if (typeof name !== 'string') continue;
-        const input = b['input'];
-        const call: ToolCall = { name };
-        if (typeof input === 'object' && input !== null && !Array.isArray(input)) {
-            const inp = input as Record<string, unknown>;
-            const cmd = inp['command'];
-            if (typeof cmd === 'string') call.command = cmd;
-            const p = inp['file_path'] ?? inp['path'] ?? inp['notebook_path'];
-            if (typeof p === 'string') call.path = p;
-        }
-        out.push(call);
-    }
-    return out;
-}
-
-function _messageText(content: unknown): string | null {
-    if (typeof content === 'string') return content;
-    if (!Array.isArray(content)) return null;
-    const parts: string[] = [];
-    for (const blk of content) {
-        if (typeof blk !== 'object' || blk === null || Array.isArray(blk)) continue;
-        const b = blk as Record<string, unknown>;
-        if (b['type'] !== 'text') continue;
-        const t = b['text'];
-        if (typeof t === 'string') parts.push(t);
-    }
-    return parts.length > 0 ? parts.join('\n') : null;
-}
+// Extracted to `_lib/turn_end_transcript.ts` — same move, same reason, as
+// detector E above: `_lib` is where the prose costs no ratchet debt, and
+// this file hit its 1,500-line source budget when the shadow read landed.
+// Re-exported so every existing importer of this module is unchanged;
+// `tests/scripts/turn_end_gate_hook.test.ts` addresses all three names at
+// this path.
+import { readTranscriptTail, type ToolCall } from '../_lib/turn_end_transcript.js';
+
+export {
+    extractToolCalls,
+    readTranscriptTail,
+    type ToolCall,
+    type TranscriptTail,
+} from '../_lib/turn_end_transcript.js';
 
 // ---------------------------------------------------------------------------
 // main
@@ -1186,18 +1075,41 @@ function str(v: JsonValue | undefined): string {
     return typeof v === 'string' ? v : '';
 }
 
-export function main(): number {
-    let envelope: JsonObject;
-    let payload: JsonObject;
-    try {
-        [envelope, payload] = unwrap(readHookStdin(), 'claude');
-    } catch {
-        return EXIT_ALLOW;
-    }
-
-    // Layer 1 — the host's own answer to "did I already refuse this turn?".
-    if (payload['stop_hook_active'] === true) return EXIT_ALLOW;
+/**
+ * Everything the detectors read, assembled once per stop event.
+ *
+ * Extracted for step 2.1 of `road-to-a-stop-that-holds`, and the extraction —
+ * not the shadow write — is the load-bearing half. The contract's Q1 asks how
+ * often a turn the gate ALLOWS on a re-entrancy layer would have been refused
+ * again, which needs the detectors to run on the allow path. There were two
+ * ways to get them there: call them from a second assembly written beside the
+ * first, or assemble once and call from both. `obligation_settle_hook.ts`'s
+ * header already rules out the first — "a detector whose shadow measurement
+ * and live behaviour come from different code measures nothing" — so this
+ * function exists so that there is exactly one assembly and exactly one
+ * detector list, read by the live verdict and by the shadow alike.
+ *
+ * `null` means the turn has no assistant text, which is `main()`'s existing
+ * allow and is not a detector input the shadow could have measured either.
+ */
+interface DetectorInputs {
+    workspaceRoot: string;
+    rawSessionId: string;
+    sessionKey: string;
+    turnOrdinal: number;
+    promptId: string;
+    lastAssistant: string;
+    toolCalls: ToolCall[];
+    turnTexts: string[];
+    closingFromPayload: boolean;
+    dispatchOpen: boolean;
+    runState: TurnRunState | null;
+}
 
+function assembleDetectorInputs(
+    envelope: JsonObject,
+    payload: JsonObject,
+): DetectorInputs | null {
     const workspaceRoot = str(envelope['workspace_root'] as JsonValue | undefined) || process.cwd();
 
     // Layer 1b — an open subagent dispatch is an EXPLICIT allow
@@ -1219,7 +1131,8 @@ export function main(): number {
     // suppressed ALL FOUR detectors. A pending dispatch explains a promissory
     // closing (A) and an unsettled completion claim (D); it explains nothing
     // about a language mismatch (B) or an unverified edit (C), and silencing
-    // those was scope Step 2 never asked for. Applied per detector below.
+    // those was scope Step 2 never asked for. Applied per detector in
+    // `runDetectors`.
     //
     // R2 round 2, finding 1: the count is TTL-filtered inside
     // `openRecordStats`. A leaked record from a dispatch that never returned
@@ -1252,7 +1165,7 @@ export function main(): number {
         transcriptPath,
         { maxBytes: TRANSCRIPT_READ_MAX_BYTES },
     );
-    if (!lastAssistant) return EXIT_ALLOW;
+    if (!lastAssistant) return null;
 
     // The closing reply comes from the field the host hands us when it supplies
     // one, not only from a file the host writes asynchronously. The transcript
@@ -1272,42 +1185,57 @@ export function main(): number {
         ? [...assistantTurnTexts, payloadClosing]
         : assistantTurnTexts;
 
-    // Layer 2 — keyed on the turn's ORDINAL, never on the prompt's text.
-    // A host that sends no `session_id` shares one bucket AND one small-integer
-    // ordinal namespace, so an unrelated session whose ordinal matches a stored
-    // `refused_turn` reads as already-refused and goes unguarded. R2 round 2,
-    // finding 16: the sibling hook documents its own bucket as degrading rather
-    // than colliding, and this one collides. It is named here rather than
-    // papered over — the degradation is toward UNDER-refusing, which is the safe
-    // direction, and layer 1 still covers the host that sends the flag.
+    // The host's own id for the prompt being processed. Recorded beside the
+    // ordinal in the refusal marker — never used as the guard key. The
+    // ordinal's drift is what both re-entrancy layers exist for, so a later
+    // reading needs the pair to tell a drifted ordinal from a second prompt.
+    const promptId = str((payload['prompt_id'] ?? payload['promptId']) as JsonValue | undefined);
     // RAW id, kept beside the derived key rather than replaced by it:
     // `readLanguagePin` addresses the producer's own per-session file, and the
-    // producer keys that on the raw `session_id`. Passing `sessionKey` here would
-    // read a path nothing writes — the same shape as the STATE_FILE break this
-    // parameter exists to close.
-    // The host's own id for the prompt being processed. Read here and recorded
-    // beside the ordinal in the refusal marker — never used as the guard key.
-    // The ordinal's drift is what both re-entrancy layers exist for, so a later
-    // reading needs the pair to tell a drifted ordinal from a second prompt.
-    const promptId = str(
-        (payload['prompt_id'] ?? payload['promptId']) as JsonValue | undefined,
-    );
+    // producer keys that on the raw `session_id`. Passing `sessionKey` there
+    // would read a path nothing writes — the same shape as the STATE_FILE break
+    // this pairing exists to close.
     const rawSessionId = str(envelope['session_id'] as JsonValue | undefined) || '';
     const sessionKey = deriveSessionKey(rawSessionId || 'unknown-session');
-    if (alreadyRefusedTurn(workspaceRoot, sessionKey, turnOrdinal)) return EXIT_ALLOW;
-
-    // B and C run on every turn-end; A and D run only when no dispatch is open
-    // (the ternaries below). For the detectors that DO run, the gating is INSIDE
-    // each one — no promise, no pin mismatch, no unverified edit, no unsettled
-    // completion claim ⇒ no finding ⇒ the turn ends. That is the whole of "fires
-    // when it is warranted"; there is no second, configurable notion of warranted
-    // layered on top of it.
+
+    // ONE read of the recorder's state, shared by detectors C and F. Two reads
+    // would be two file opens on the stop slot for one answer, and — worse —
+    // could disagree if a post-tool event landed between them.
     //
-    // This said "Every detector runs on every turn-end" and enumerated three of
-    // four, three lines above the two `dispatchOpen` ternaries that refute it.
-    // Corrected 2026-08-19 with the header block at the top of this file: a reader
-    // arriving here met the false claim first, and the D comment below deferred to
-    // "the note at the top of this loop" — which was this sentence.
+    // It used to sit AFTER the Layer-2 allow, with a comment saying "a retry
+    // pays no file read it immediately discards". Step 2.1 makes that false
+    // rather than leaving the comment to rot: a retry now RUNS the detectors
+    // to record whether it would have been refused again, so the read is
+    // consumed on that path too. The cost is one `readFileSync` per retry,
+    // which is the budget line 2.1 pre-registers.
+    const runState = readTurnRunState(workspaceRoot, rawSessionId);
+
+    return {
+        workspaceRoot,
+        rawSessionId,
+        sessionKey,
+        turnOrdinal,
+        promptId,
+        lastAssistant,
+        toolCalls,
+        turnTexts,
+        closingFromPayload,
+        dispatchOpen,
+        runState,
+    };
+}
+
+/**
+ * Run every detector over one assembled input set.
+ *
+ * The one list, called by the live verdict and by the shadow read. Its
+ * ordering and its `dispatchOpen` ternaries are the gate's behaviour; nothing
+ * about the shadow may change them, which is why the shadow calls this rather
+ * than carrying a copy.
+ */
+function runDetectors(inputs: DetectorInputs): Finding[] {
+    const { dispatchOpen, lastAssistant, workspaceRoot, rawSessionId, toolCalls, runState } =
+        inputs;
     const findings: Finding[] = [];
     for (const f of [
         // A and D are the completion-adjacent pair a pending dispatch excuses
@@ -1315,17 +1243,14 @@ export function main(): number {
         // excused by anything about a dispatch and run unchanged.
         dispatchOpen ? null : detectPromissory(lastAssistant),
         detectLanguage(lastAssistant, readLanguagePin(workspaceRoot, rawSessionId)),
-        detectUnverifiedEdit(toolCalls),
-        // Round 7 § Phase 1 — detector D. It is NOT unconditional, and this
-        // comment said it was while sitting one line above the `dispatchOpen`
-        // ternary that conditions it: A and D are both excused by an open
-        // dispatch, per the note at the top of this loop. Corrected 2026-08-18.
-        // It shipped with its own settings flag one commit earlier
-        // and that flag is gone: `hooks.turn_end_gate.*` was deleted on
-        // 2026-08-12 because a default-off safety gate is an absent one. Its
-        // gating is where the comment above says gating belongs — inside the
-        // detector: no CI observed, or a settled read, or no completion claim
-        // ⇒ no finding.
+        detectUnverifiedEdit(toolCalls, runState),
+        // Round 7 § Phase 1 — detector D. It is NOT unconditional: A and D are
+        // both excused by an open dispatch, per the note above. It shipped with
+        // its own settings flag one commit earlier and that flag is gone:
+        // `hooks.turn_end_gate.*` was deleted on 2026-08-12 because a
+        // default-off safety gate is an absent one. Its gating is where the
+        // note above says gating belongs — inside the detector: no CI observed,
+        // or a settled read, or no completion claim ⇒ no finding.
         dispatchOpen
             ? null
             : detectCompletionClaim(lastAssistant, readCiSettled(workspaceRoot, rawSessionId)),
@@ -1337,25 +1262,113 @@ export function main(): number {
         // that produced the measured failure — IS the continuation that drops
         // the decision, so narrowing E the same way would silence it in exactly
         // the case it exists for.
-        detectDroppedDecision(turnTexts, closingFromPayload),
+        detectDroppedDecision(inputs.turnTexts, inputs.closingFromPayload),
         // Detector F takes the OTHER side of that same question, and the two
         // sitting adjacent is the clearest place to say why. E fires on a
         // question already asked, which an open dispatch cannot excuse. F fires
         // on a completion CLAIM, and a turn waiting on a subagent has not
         // finished — so its closing is not the claim F is about. Same slot,
         // opposite trigger, opposite treatment of `dispatchOpen`.
-        dispatchOpen ? null : detectUntestedChange(lastAssistant, toolCalls),
+        dispatchOpen ? null : detectUntestedChange(lastAssistant, toolCalls, runState),
     ]) {
         if (f) findings.push(f);
     }
+    return findings;
+}
+
+/**
+ * Record what this retry WOULD have been refused for, then let it end.
+ *
+ * Never changes a verdict: every caller returns `EXIT_ALLOW` whatever happens
+ * here, and the whole body is wrapped because a retry that crashed on its own
+ * instrument would be a new failure mode on a path that previously did no work
+ * at all. A retry with no findings still lands, as `retries_observed` without a
+ * row — that is the only way Q1 can read below 1.
+ */
+function recordShadow(inputs: DetectorInputs, layer: ShadowLayer): void {
+    if (is_replay_mode()) return;
+    try {
+        const findings = runDetectors(inputs);
+        const file = sessionShadowFile(inputs.workspaceRoot, inputs.sessionKey);
+        let prev: ShadowRecord | null = null;
+        try {
+            prev = parseShadowRecord(fs.readFileSync(file, 'utf-8'));
+        } catch {
+            // Absent or unreadable prior state starts a fresh record.
+        }
+        atomic_write_json(
+            file,
+            foldShadow(prev, {
+                detectors: findings.map((f) => f.detector),
+                turnOrdinal: inputs.turnOrdinal,
+                at: new Date().toISOString(),
+                layer,
+            }) as unknown as Record<string, unknown>,
+        );
+    } catch {
+        // An instrument is never a reason to change what the gate does.
+    }
+}
+
+export function main(): number {
+    let envelope: JsonObject;
+    let payload: JsonObject;
+    try {
+        [envelope, payload] = unwrap(readHookStdin(), 'claude');
+    } catch {
+        return EXIT_ALLOW;
+    }
+
+    // Layer 1 — the host's own answer to "did I already refuse this turn?".
+    //
+    // Still an unconditional allow. What changed in step 2.1 is that the turn
+    // is MEASURED on the way out: the detectors run once against the same
+    // inputs the live path would have built, and a finding becomes a
+    // `would_refuse_again` row. The verdict is byte-identical to the version
+    // that returned here immediately.
+    if (payload['stop_hook_active'] === true) {
+        try {
+            const retryInputs = assembleDetectorInputs(envelope, payload);
+            if (retryInputs !== null) recordShadow(retryInputs, 'stop_hook_active');
+        } catch {
+            // Assembly is throw-safe by construction today; the guard is here
+            // because this path did NO work before 2.1, so a regression in any
+            // reader it now calls must not turn a clean retry into a crash.
+        }
+        return EXIT_ALLOW;
+    }
+
+    const inputs = assembleDetectorInputs(envelope, payload);
+    if (inputs === null) return EXIT_ALLOW;
+
+    // Layer 2 — keyed on the turn's ORDINAL, never on the prompt's text.
+    // A host that sends no `session_id` shares one bucket AND one small-integer
+    // ordinal namespace, so an unrelated session whose ordinal matches a stored
+    // `refused_turn` reads as already-refused and goes unguarded. R2 round 2,
+    // finding 16: the sibling hook documents its own bucket as degrading rather
+    // than colliding, and this one collides. It is named here rather than
+    // papered over — the degradation is toward UNDER-refusing, which is the safe
+    // direction, and layer 1 still covers the host that sends the flag.
+    if (alreadyRefusedTurn(inputs.workspaceRoot, inputs.sessionKey, inputs.turnOrdinal)) {
+        recordShadow(inputs, 'refused_turn');
+        return EXIT_ALLOW;
+    }
+
+    // B and C run on every turn-end; A and D run only when no dispatch is open.
+    // For the detectors that DO run, the gating is INSIDE each one — no promise,
+    // no pin mismatch, no unverified edit, no unsettled completion claim ⇒ no
+    // finding ⇒ the turn ends. That is the whole of "fires when it is
+    // warranted"; there is no second, configurable notion of warranted layered
+    // on top of it.
+    const findings = runDetectors(inputs);
     if (findings.length === 0) return EXIT_ALLOW;
 
     markRefusedTurn(
-        workspaceRoot,
-        sessionKey,
-        turnOrdinal,
+        inputs.workspaceRoot,
+        inputs.sessionKey,
+        inputs.turnOrdinal,
         findings.map((f) => f.detector),
-        promptId,
+        inputs.promptId,
     );
 
     const lines = findings.map(