@event4u/agent-config 15.0.0 → 16.0.0

package/src/scripts/hooks/review_baseline_hook.ts

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * review-baseline — `session_start` concern
+ * (road-to-a-question-that-survives-the-turn Phase 2).
+ *
+ * WHAT IT DOES, and it is the whole of it: on session start, record how many
+ * non-doc lines were ALREADY dirty, and what HEAD was. `end-review-nudge`
+ * subtracts that at `stop` so a session is charged for its own mutation instead
+ * of for whatever the working tree happened to be carrying.
+ *
+ * THE DEFECT IT CLOSES. `end_review_nudge_hook`'s own header names it: a dirty
+ * tree that predates the session is counted as the session's, and the reason it
+ * was not fixed was "no such baseline exists anywhere a `stop` concern can read
+ * it". That was true of a phase with a one-concern scope, and stale by the time
+ * it mattered — `session_start` is bound on seven hosts carrying fourteen
+ * concerns. The measured consequence of leaving it: on a branch deliberately
+ * accumulating work, the nudge read 1,771 lines of two crashed sessions'
+ * uncommitted work and fired every turn. An advisory that always fires is noise,
+ * and noise is worse than silence because it trains the reader to skip the one
+ * that mattered.
+ *
+ * MEASURED WITH THE READER'S OWN INSTRUMENT. `totalNonDocMutatedLinesWithMeasure`
+ * is imported from the nudge rather than reimplemented, so the two sides cannot
+ * drift on what a "non-doc mutated line" is. A second counting implementation
+ * would produce a baseline in one unit and a measurement in another, and the
+ * subtraction would be silently wrong rather than visibly broken.
+ *
+ * CAPTURE ONLY. It never emits context, never warns, and always returns 0. A
+ * `session_start` concern that could refuse would turn an unreadable git
+ * directory into a session that cannot start, which is a far worse failure than
+ * the noise it is fixing.
+ *
+ * NO PATHS, NO FINGERPRINTS. The record is two numbers and a timestamp. A
+ * path-level change set was the shape the source draft proposed; it is a bigger
+ * object with a bigger privacy surface, and nothing in the nudge consumes one.
+ * The file cannot hold a path, a diff or a file body by construction, which is
+ * the same PII-exclusion-by-construction the telemetry record keeps.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import {
+    baselineStateFile,
+    currentHeadSha,
+    type ReviewBaseline,
+} from '../_lib/review_baseline.js';
+import { deriveSessionKey, totalNonDocMutatedLinesWithMeasure } from './end_review_nudge_hook.js';
+import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
+import { readHookStdin } from './hook_stdin.js';
+import { atomic_write_json } from './state_io.js';
+
+const EXIT_OK = 0;
+
+export function buildBaseline(workspaceRoot: string, now: Date = new Date()): ReviewBaseline {
+    const measured = totalNonDocMutatedLinesWithMeasure(workspaceRoot);
+    return {
+        head_sha: currentHeadSha(workspaceRoot),
+        baseline_lines: measured.lines,
+        // Carried, not discarded. Past `UNTRACKED_FILE_CAP` the count is a
+        // synthetic `THRESHOLD + 1 + tracked` chosen to be over the bar rather
+        // than to be true, and subtracting that from a later exact count is
+        // arithmetic over two different quantities. The consumer refuses the
+        // subtraction when the two measures disagree; it can only do that if the
+        // writer says which one it took.
+        measure: measured.measure,
+        written_at: now.toISOString(),
+    };
+}
+
+export function main(): number {
+    let envelope: JsonObject;
+    let payload: JsonObject;
+    try {
+        [envelope, payload] = unwrap(readHookStdin(), 'claude');
+    } catch {
+        return EXIT_OK;
+    }
+
+    const event = String(envelope['event'] ?? '');
+    if (event !== '' && event !== 'session_start') return EXIT_OK;
+
+    const workspaceRoot =
+        String((envelope['workspace_root'] as JsonValue | undefined) ?? '').trim() || process.cwd();
+
+    // A baseline is written ONCE per session. A host that fires session_start
+    // twice — Cline maps both TaskStart and TaskResume onto it — must not
+    // re-baseline mid-session: the second write would fold everything the
+    // session had already changed into its own baseline and the nudge would go
+    // permanently quiet for that session. Over-writing is the silent failure
+    // direction, so it is the one guarded.
+    const sessionKey = deriveSessionKey(envelope, payload);
+    const file = baselineStateFile(workspaceRoot, sessionKey);
+    try {
+        if (fs.existsSync(file)) return EXIT_OK;
+    } catch {
+        return EXIT_OK;
+    }
+
+    try {
+        // `atomic_write_json` is already `AGENT_CONFIG_REPLAY`-aware, so a
+        // fixture-replay run leaves no baseline behind.
+        atomic_write_json(file, buildBaseline(workspaceRoot) as unknown as JsonObject);
+    } catch {
+        // An unwritable state dir degrades to today's behaviour — the nudge
+        // reads `absent` and does not subtract. Never a failed session start.
+    }
+    return EXIT_OK;
+}
+
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url`.
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) return false;
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/hooks/turn_end_gate_hook.ts

@@ -9,7 +9,7 @@
  * is deliberately not another reminder. It is a check at the point of
  * delivery that can say no.
  *
- * FOUR detectors ride on one guard, because building the unsafe part twice
+ * FIVE detectors ride on one guard, because building the unsafe part twice
  * is how a second detector becomes a second outage:
  *
  *   A — promissory closing  (FC-5, 20 measured occurrences)
@@ -22,11 +22,18 @@
  *                            only, so tool activity is invisible to A and B.)
  *   D — completion claim    (a claim of done carrying no fresh evidence; landed
  *                            under conformance round 7 § Phase 1.)
+ *   E — pending decision    (an earlier reply in the SAME user turn put numbered
+ *                            options to the user and the closing reply carries
+ *                            none — the turn asked and then dropped the ask.
+ *                            Read off `assistantTurnTexts`, which is why that
+ *                            field exists: every other detector reads
+ *                            `lastAssistant` alone and therefore cannot see a
+ *                            question that was asked one reply earlier.)
  *
- * TWO of the four are CONDITIONAL, and saying "unconditional" here would be the
+ * 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 and C run on every turn-end. That
+ * 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()`.
@@ -35,7 +42,7 @@
  * below has carried four since round 7. `DETECTOR_IDS` in
  * `_lib/turn_end_refusals.ts` is read off that union rather than off this
  * comment for exactly that reason, and the count is corrected here rather than
- * left as a stale header the next reader has to disbelieve.
+ * left as a stale header the next reader has to disbelieve. E made it five.
  *
  * ## Removal condition
  *
@@ -157,6 +164,23 @@ import {
 // 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';
+// 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
+// there.
+//
+// WHAT KEEPS IT FROM RUNNING ON IMPORT, stated precisely because the obvious
+// answer is wrong: that module is `_isCliEntry`-guarded, but WITHOUT the
+// `__AGENT_CONFIG_BUNDLE__` early-out this file carries. Inside
+// `dist/hooks/dispatch.js` every module shares one `import.meta.url`, so the
+// guard alone would not settle it; what does is the `.__direct__` argv rewrite
+// in the `build:hooks` banner. Named here so a future change to that banner
+// does not silently start running a lint's `main()` on every hook dispatch.
+// 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';
+
+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';
@@ -190,7 +214,13 @@ const EXIT_ALLOW = 0;
 export const TRANSCRIPT_READ_MAX_BYTES = 8 * 1024 * 1024; // 8 MB
 
 /** Detector identity, used in the state marker and the refusal text. */
-export type DetectorId = 'promissory' | 'language' | 'verification' | 'completion';
+export type DetectorId =
+    | 'promissory'
+    | 'language'
+    | 'verification'
+    | 'completion'
+    | 'pending-decision'
+    | 'untested';
 
 export interface Finding {
     detector: DetectorId;
@@ -723,6 +753,110 @@ export function detectUnverifiedEdit(toolCalls: readonly ToolCall[]): Finding |
     };
 }
 
+// ---------------------------------------------------------------------------
+// Detector F — a completion claim over production code no test accompanies
+// ---------------------------------------------------------------------------
+
+/**
+ * WHY THIS EXISTS, and why detector C did not already cover it.
+ *
+ * Detector C asks "did ANY verification command run after the last edit". It is
+ * satisfied by `eslint`. That is deliberate — see `isVerificationCommand`, which
+ * is narrow about what counts as a command and says nothing about what the
+ * command COVERS. So a turn can write four hundred lines of feature code, run
+ * the linter, claim done, and pass every guard in this file.
+ *
+ * Measured consequence, reported by the maintainer 2026-09-11 about a consumer
+ * project: a feature shipped whose detail view crashed on open, whose flyouts
+ * were broken, and for which the maintainer then had to hand-enumerate what
+ * should have been exercised — every view, every CRUD path, drag-and-drop,
+ * mobile, filters. Their words: *"Solche Fehler können nur auftreten, weil Du
+ * nicht TDD gearbeitet ... hast."* Nothing in the suite refused that turn,
+ * because nothing in the suite asks whether the change is TESTED — only whether
+ * something ran.
+ *
+ * THE SIGNAL, and why it is this one. "Is the change covered" is undecidable
+ * from a transcript: coverage lives in the consumer's tooling, which this hook
+ * cannot run. What IS decidable is the cheapest possible proxy, and it happens
+ * to be the exact shape of the reported failure — **production source changed,
+ * no test file touched, done claimed**. A proxy is worth shipping here precisely
+ * because the population it flags is small and the failure it catches is total:
+ * a feature with zero new test lines is not under-tested, it is untested.
+ *
+ * WHY IT IS GATED ON THE CLAIM rather than on the edit. Firing on every edit
+ * would refuse the first turn of every red-green-refactor cycle — the discipline
+ * it exists to encourage — and a guard that fires on the majority of turns is a
+ * guard that gets switched off. The obligation belongs to the CLAIM, which is
+ * also where `verify-before-complete` puts it and where detector D already sits.
+ *
+ * WHAT IT CANNOT DO. It cannot tell a good test from a token one: a turn that
+ * touches any test file clears it. That is a deliberate floor rather than an
+ * oversight — `testing-anti-patterns` owns assertion quality, and a guard that
+ * tried to judge it from a path would be judging something it cannot see. The
+ * honest claim is narrow: this refuses the case where the agent wrote NO test at
+ * all and said it was finished.
+ */
+
+/** Extensions that carry behaviour a test can be owed for. */
+const _SOURCE_RE = /\.(?:ts|tsx|js|jsx|mjs|cjs|vue|svelte|php|py|rb|go|rs|java|kt|swift|cs|scala|ex|exs)$/i;
+
+/**
+ * Paths that ARE tests, across the conventions this suite's stacks use.
+ *
+ * Deliberately generous: a false NEGATIVE here (calling a test file a test) only
+ * silences the detector, while a false positive would refuse a turn that did
+ * write its tests — the direction that gets a guard disabled.
+ */
+const _TEST_PATH_RE =
+    /(?:^|\/)(?:tests?|specs?|__tests__|__specs__|e2e|cypress|playwright|features)\//i;
+const _TEST_FILE_RE =
+    /(?:\.(?:test|spec)\.[a-z]+$)|(?:_test\.[a-z]+$)|(?:(?:^|\/)test_[^/]+$)|(?:Test\.php$)|(?:Spec\.php$)|(?:\.feature$)/i;
+
+function _isTestPath(p: string): boolean {
+    return _TEST_PATH_RE.test(p) || _TEST_FILE_RE.test(p);
+}
+
+function _isProductionSource(p: string): boolean {
+    return _SOURCE_RE.test(p) && !_isTestPath(p);
+}
+
+/**
+ * Fire when the turn changed production code, touched no test, and said done.
+ *
+ * All three conditions are load-bearing. Drop the first and it fires on a docs
+ * 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 {
+    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 claim gate, reusing detector D's pair rather than a second dialect of
+    // "done" — two lists of completion phrasings would drift, and the negation
+    // check is what keeps an honest "noch nicht fertig" from being refused.
+    const prose = visibleProse(reply);
+    const m = _COMPLETION_RE.exec(prose);
+    if (!m) return null;
+    if (_NEGATED_CLAIM_RE.test(_lineAround(prose, m.index))) return null;
+
+    const shown = source.slice(0, 3).join(', ');
+    return {
+        detector: 'untested',
+        evidence: shown + (source.length > 3 ? ` (+${String(source.length - 3)} more)` : ''),
+        reason:
+            'a completion claim over production code this turn changed, with NO test file ' +
+            'touched anywhere in the turn — running a linter is not evidence the change ' +
+            'works. Write the test that would have caught the failure, and enumerate the ' +
+            'states the change actually has (every view, every CRUD path, the empty and ' +
+            'error states) rather than the happy one. If a test genuinely does not belong ' +
+            'here, say which file carries the coverage instead',
+    };
+}
+
 // ---------------------------------------------------------------------------
 // Re-entrancy — the guard, keyed on the turn, not on the reply
 // ---------------------------------------------------------------------------
@@ -811,6 +945,7 @@ function markRefusedTurn(
     sessionKey: string,
     turnOrdinal: number,
     detectors: readonly DetectorId[],
+    promptId: string,
 ): void {
     if (is_replay_mode()) return;
     const file = sessionStateFile(workspaceRoot, sessionKey);
@@ -835,6 +970,7 @@ function markRefusedTurn(
                 turnOrdinal,
                 at: new Date().toISOString(),
                 version,
+                promptId,
             }) as unknown as Record<string, unknown>,
         );
     } catch {
@@ -868,6 +1004,20 @@ export interface ToolCall {
 
 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
@@ -899,7 +1049,12 @@ export function readTranscriptTail(
     transcriptPath: string,
     opts: { homeDir?: string; maxBytes?: number } = {},
 ): TranscriptTail {
-    const empty: TranscriptTail = { lastAssistant: '', turnOrdinal: 0, toolCalls: [] };
+    const empty: TranscriptTail = {
+        lastAssistant: '',
+        turnOrdinal: 0,
+        toolCalls: [],
+        assistantTurnTexts: [],
+    };
     if (!transcriptPath || !isSafeTranscriptPath(transcriptPath, opts)) return empty;
     let lines: string[];
     try {
@@ -919,6 +1074,7 @@ export function readTranscriptTail(
     let lastAssistant = '';
     let turnOrdinal = 0;
     let toolCalls: ToolCall[] = [];
+    let assistantTurnTexts: string[] = [];
     for (const rawLine of lines) {
         const line = rawLine.trim();
         if (!line) continue;
@@ -944,12 +1100,13 @@ export function readTranscriptTail(
         // 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(..._toolCalls(content));
+            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
@@ -957,17 +1114,34 @@ export function readTranscriptTail(
             // 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 };
+    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.
  */
-function _toolCalls(content: unknown): ToolCall[] {
+export function extractToolCalls(content: unknown): ToolCall[] {
     if (!Array.isArray(content)) return [];
     const out: ToolCall[] = [];
     for (const blk of content) {
@@ -1074,11 +1248,30 @@ export function main(): number {
     // in production while its comment claimed it was enforced — the same
     // fixed-the-definition-not-the-caller shape as two other findings in that
     // round, which is why this line exists rather than a default parameter.
-    const { lastAssistant, turnOrdinal, toolCalls } = readTranscriptTail(transcriptPath, {
-        maxBytes: TRANSCRIPT_READ_MAX_BYTES,
-    });
+    const { lastAssistant, turnOrdinal, toolCalls, assistantTurnTexts } = readTranscriptTail(
+        transcriptPath,
+        { maxBytes: TRANSCRIPT_READ_MAX_BYTES },
+    );
     if (!lastAssistant) return EXIT_ALLOW;
 
+    // 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
+    // may lag the in-memory conversation, and a tail that is one assistant entry
+    // short is silence for `detectDroppedDecision`, whose early return needs two
+    // texts — i.e. the detector goes quiet in exactly the shape it exists for.
+    // `suggestion_capture_hook.ts` reads the same field for the same reason.
+    // Appended, never substituted: `lastAssistant` and the four other detectors
+    // are untouched, and a host that supplies no such field is unchanged.
+    const payloadClosing = str(
+        (payload['last_assistant_message'] ?? payload['lastAssistantMessage']) as
+            | JsonValue
+            | undefined,
+    );
+    const closingFromPayload = payloadClosing !== '' && !assistantTurnTexts.includes(payloadClosing);
+    const turnTexts = closingFromPayload
+        ? [...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
@@ -1092,6 +1285,13 @@ export function main(): number {
     // 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,
+    );
     const rawSessionId = str(envelope['session_id'] as JsonValue | undefined) || '';
     const sessionKey = deriveSessionKey(rawSessionId || 'unknown-session');
     if (alreadyRefusedTurn(workspaceRoot, sessionKey, turnOrdinal)) return EXIT_ALLOW;
@@ -1129,6 +1329,22 @@ export function main(): number {
         dispatchOpen
             ? null
             : detectCompletionClaim(lastAssistant, readCiSettled(workspaceRoot, rawSessionId)),
+        // Detector E is UNCONDITIONAL, and that is the opposite choice from A
+        // and D one line above rather than an oversight. An open dispatch
+        // excuses a promissory closing because the work is genuinely still
+        // running; it excuses nothing about a question the user was already
+        // asked. Worse: a dispatch — or the `end-review-nudge` stop concern
+        // 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),
+        // 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),
     ]) {
         if (f) findings.push(f);
     }
@@ -1139,6 +1355,7 @@ export function main(): number {
         sessionKey,
         turnOrdinal,
         findings.map((f) => f.detector),
+        promptId,
     );
 
     const lines = findings.map(
@@ -1147,8 +1364,9 @@ export function main(): number {
     process.stderr.write(
         `turn-end-gate: REFUSED — this turn is not finished.\n${lines.join('\n')}\n` +
             '  Do the promised work now, correct the language, run the ' +
-            'verification the edit needs, or read the CI verdict before claiming ' +
-            'it — then end the turn.\n' +
+            'verification the edit needs, read the CI verdict before claiming ' +
+            'it, or re-present the options block this turn dropped — then end ' +
+            'the turn.\n' +
             '  This turn will not be refused a second time.\n',
     );
     return EXIT_BLOCK;

package/src/scripts/hooks_doctor.ts

@@ -40,6 +40,7 @@ import * as hooks_status from "./hooks_status.js";
 import {
   DETECTOR_IDS,
   collectRefusalStats,
+  emptyCounts,
   readInstallBoundary,
   type InstallBoundary,
   type RefusalStats,
@@ -268,7 +269,9 @@ export function collect(
     turn_end_refusals = {
       sessionsWithRefusals: 0,
       total: 0,
-      byDetector: { promissory: 0, language: 0, verification: 0, completion: 0 },
+      // Derived, never a literal: a fifth detector made the old four-key object
+      // a type error here and a silent `NaN` in the aggregator it mirrors.
+      byDetector: emptyCounts(),
       byPeriod: [],
       legacyRecords: 0,
       unversionedRecords: 0,

package/src/scripts/install.ts

@@ -1920,7 +1920,7 @@ const _CLAUDE_SKILL_BUNDLE: ReadonlyArray<readonly [string, string]> = [
     ['dist/agent-src/personas', 'personas'],
 ];
 
-const GLOBAL_DEPLOY_SOURCES: Record<string, ReadonlyArray<readonly [string, string]>> = {
+export const GLOBAL_DEPLOY_SOURCES: Record<string, ReadonlyArray<readonly [string, string]>> = {
     'claude-code': _CLAUDE_SKILL_BUNDLE,
     augment: [
         ['dist/agent-src/rules', 'rules'],

package/src/scripts/interruption_report.ts

@@ -495,8 +495,14 @@ export function buildReport(root: string, windowRequested: number): Report {
     const notes: string[] = [];
     if (ledger.length === 0) {
         notes.push(
-            'interruptions.jsonl is empty or absent — the contact axis has no observations yet. ' +
-                'The Phase 0 concern records on `stop`; a baseline needs sessions to have run since it landed.',
+            'interruptions.jsonl is empty or absent — the contact axis has no observations ' +
+                'IN THIS CHECKOUT. The Phase 0 concern records on `stop`; a baseline needs ' +
+                'sessions to have run since it landed. Before reading this as the instrument ' +
+                'having no data: `agents/runtime/` is gitignored and therefore per-checkout, ' +
+                'so a fresh worktree always reports zero here however full the ledger is ' +
+                'elsewhere. Re-run with `--root <path-to-a-checkout-with-runtime-state>` ' +
+                'before recording an absence — a reading taken in an empty worktree was once ' +
+                'parked as a measured null while the ledger already held three weeks of records.',
         );
     }
     if (bySession.size === 0) {

package/src/scripts/janitor.ts

@@ -62,7 +62,7 @@ const TTL_CONFIG: ReadonlyArray<{
     },
     // ── Session-scoped runtime state (Step 4.1) ────────────────────────────
     //
-    // These four directories accrete ONE entry per session behind a
+    // These five directories accrete ONE entry per session behind a
     // once-per-session latch, and nothing in the tree removed them: writers
     // and readers existed, no reaper did. They are named INDIVIDUALLY rather
     // than sweeping `agents/runtime/state` as a whole, and that is the
@@ -101,6 +101,13 @@ const TTL_CONFIG: ReadonlyArray<{
         owner: 'maintainer',
         reviewBy: '2026-11-10',
     },
+    {
+        dir: 'agents/runtime/state/review-baseline',
+        ttlDays: 7,
+        description: 'Per-session start-of-session mutation baseline (one file per session)',
+        owner: 'maintainer',
+        reviewBy: '2026-11-10',
+    },
 ];
 
 // Directories that must NEVER be auto-swept