@event4u/agent-config 9.34.0 → 9.35.0

package/src/scripts/hooks/turn_end_gate_hook.ts

@@ -9,11 +9,17 @@
  * is deliberately not another reminder. It is a check at the point of
  * delivery that can say no.
  *
- * Two detectors ride on one guard, because building the unsafe part twice
+ * Three 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)
  *   B — language mismatch   (19 measured occurrences, fresh pin present)
+ *   C — unverified edit     (the turn changed a file and ran nothing that could
+ *                            have checked it — verify-before-complete's gate,
+ *                            read off the turn's TOOL CALLS rather than its
+ *                            prose, which is why `readTranscriptTail` collects
+ *                            them: `_messageText` keeps `type === 'text'` blocks
+ *                            only, so tool activity is invisible to A and B.)
  *
  * ## Re-entrancy — the shape, stated before registration
  *
@@ -60,10 +66,11 @@
  * mechanism exists and soaks before it binds" — two prior hook-severity
  * mistakes plus a turn-end blast radius made default-on uninsurable in
  * their reading. Both are satisfied literally: the MASTER switch
- * (`hooks.turn_end_gate.enabled`) is default OFF, and WITHIN it both
- * detectors are default ON. A maintainer who opts in gets both without
+ * (`hooks.turn_end_gate.enabled`) is default OFF, and WITHIN it every
+ * detector is default ON. A maintainer who opts in gets all of them without
  * further configuration; until then this concern is a no-op that costs one
- * settings-cascade read per turn-end.
+ * settings-cascade read per turn-end. Detector C landed under the same rule —
+ * the master switch was NOT flipped when it shipped.
  *
  * CONTRACT: dispatcher-internal exit is 1 (EXIT_BLOCK) on a fire, 0
  * otherwise. `fail_closed: false` — deliberately. A crash in a turn-end
@@ -71,6 +78,16 @@
  * crash to a block is the outage this whole file is arranged to avoid.
  * Every unreadable input, missing transcript, absent pin, or malformed
  * state resolves to silence.
+ *
+ * The severity mapping was re-probed when C landed, because
+ * `dispatch_hook.ts` defines `EXIT_WARN = 2` beside `EXIT_BLOCK = 1` and an
+ * advisory finding delivered on the wrong code becomes a hard deny. Result:
+ * this file emits ONLY 0 and 1 internally, `concern_block_exit_parity` pins the
+ * 1, and the dispatcher translates a stop-slot block to host exit **2** —
+ * which a spawned test in `turn_end_gate_hook.test.ts` asserts, because on the
+ * stop slot exit 1 would let the turn end anyway. C is a refusal like A and B,
+ * not an advisory, so there is no advisory path here to put on the wrong code.
+ * Probed, not assumed.
  */
 import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
@@ -104,7 +121,7 @@ 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';
+export type DetectorId = 'promissory' | 'language' | 'verification';
 
 export interface Finding {
     detector: DetectorId;
@@ -360,6 +377,71 @@ export function detectLanguage(reply: string, pinned: Verdict): Finding | null {
     };
 }
 
+// ---------------------------------------------------------------------------
+// Detector 3 — an edit the turn never verified
+// ---------------------------------------------------------------------------
+
+/** Tools that CHANGE the tree. The three write tools, nothing inferred. */
+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.
+ */
+const _VERIFY_RE =
+    /\b(test|tests|vitest|jest|pytest|phpunit|pest|tsc|eslint|ruff|mypy|pyright|clippy|typecheck|lint|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);
+}
+
+/**
+ * Fire when the turn changed a file and then ran nothing that could have
+ * checked it.
+ *
+ * The window is "after the LAST edit", not "anywhere in the turn": a test run
+ * before the final edit demonstrably did not exercise it, which is the same
+ * freshness argument `verify-before-complete` makes about trusting an earlier
+ * run ("no verification command run in this message → you cannot claim it
+ * passes"). Ordering is the only thing that distinguishes the two, so the
+ * detector reads the sequence rather than a pair of counts.
+ *
+ * Silent when the turn edited nothing — a read-only or conversational turn has
+ * 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 {
+    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;
+    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,
+        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)',
+    };
+}
+
 // ---------------------------------------------------------------------------
 // Re-entrancy — the guard, keyed on the turn, not on the reply
 // ---------------------------------------------------------------------------
@@ -450,6 +532,24 @@ 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;
     /**
@@ -458,6 +558,14 @@ export interface TranscriptTail {
      * 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[];
 }
 
 /**
@@ -475,7 +583,7 @@ export function readTranscriptTail(
     transcriptPath: string,
     opts: { homeDir?: string; maxBytes?: number } = {},
 ): TranscriptTail {
-    const empty: TranscriptTail = { lastAssistant: '', turnOrdinal: 0 };
+    const empty: TranscriptTail = { lastAssistant: '', turnOrdinal: 0, toolCalls: [] };
     if (!transcriptPath || !isSafeTranscriptPath(transcriptPath, opts)) return empty;
     let lines: string[];
     try {
@@ -494,6 +602,7 @@ export function readTranscriptTail(
     }
     let lastAssistant = '';
     let turnOrdinal = 0;
+    let toolCalls: ToolCall[] = [];
     for (const rawLine of lines) {
         const line = rawLine.trim();
         if (!line) continue;
@@ -514,15 +623,55 @@ export function readTranscriptTail(
         if (role !== 'assistant' && role !== 'user') continue;
         const msg = entry['message'];
         if (typeof msg !== 'object' || msg === null || Array.isArray(msg)) continue;
-        const text = _messageText((msg as Record<string, unknown>)['content']);
+        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(..._toolCalls(content));
+        }
+        const text = _messageText(content);
         if (text === null) continue;
         if (role === 'assistant') {
             lastAssistant = 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 = [];
+        }
+    }
+    return { lastAssistant: lastAssistant.trim(), turnOrdinal, toolCalls };
+}
+
+/**
+ * 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.
+ */
+function _toolCalls(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 { lastAssistant: lastAssistant.trim(), turnOrdinal };
+    return out;
 }
 
 function _messageText(content: unknown): string | null {
@@ -547,6 +696,7 @@ export interface GateSettings {
     enabled: boolean;
     promissory: boolean;
     language: boolean;
+    verification: boolean;
 }
 
 /**
@@ -581,7 +731,12 @@ function _isOn(v: unknown): boolean | null {
  * a turn-end outranks one settings read per turn-end.
  */
 export function readGateSettings(workspaceRoot: string): GateSettings {
-    const off: GateSettings = { enabled: false, promissory: true, language: true };
+    const off: GateSettings = {
+        enabled: false,
+        promissory: true,
+        language: true,
+        verification: true,
+    };
     let settings: Record<string, unknown>;
     try {
         settings = load_agent_settings({ cwd: workspaceRoot }) as Record<string, unknown>;
@@ -601,6 +756,7 @@ export function readGateSettings(workspaceRoot: string): GateSettings {
         enabled: flag('enabled', false),
         promissory: flag('promissory', true),
         language: flag('language', true),
+        verification: flag('verification', true),
     };
 }
 
@@ -644,7 +800,7 @@ 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 } = readTranscriptTail(transcriptPath, {
+    const { lastAssistant, turnOrdinal, toolCalls } = readTranscriptTail(transcriptPath, {
         maxBytes: TRANSCRIPT_READ_MAX_BYTES,
     });
     if (!lastAssistant) return EXIT_ALLOW;
@@ -671,6 +827,10 @@ export function main(): number {
         const f = detectLanguage(lastAssistant, readLanguagePin(workspaceRoot));
         if (f) findings.push(f);
     }
+    if (settings.verification) {
+        const f = detectUnverifiedEdit(toolCalls);
+        if (f) findings.push(f);
+    }
     if (findings.length === 0) return EXIT_ALLOW;
 
     markRefusedTurn(workspaceRoot, sessionKey, turnOrdinal, findings[0]!.detector);
@@ -680,7 +840,8 @@ 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, or correct the language, then end the turn.\n' +
+            '  Do the promised work now, correct the language, or run the ' +
+            'verification the edit needs, then end the turn.\n' +
             '  This turn will not be refused a second time.\n' +
             '  Disable: hooks.turn_end_gate.enabled: false in .agent-settings.yml\n',
     );

package/src/scripts/lint_framework_leakage.ts

@@ -299,14 +299,21 @@ interface AllowlistEntry {
     file?: string;
     lines?: number[] | '*';
     /**
-     * Content anchor — a substring of the exempted line.
+     * Content anchor — a substring of the exempted line. The only per-line key.
      *
-     * Position-keyed entries (`lines: [100]`) are drift-fragile by
-     * construction: inserting a paragraph above line 100 silently re-fires the
-     * ratchet on an entry nobody touched, which this repository has recorded as
-     * a real cost. An anchor keys the exemption to what is actually being
-     * exempted, so the entry survives the edit that moves it. Prefer it for new
-     * entries; `lines` stays supported for the existing ones.
+     * Position keying (`lines: [100]`) is retired, not merely discouraged.
+     * Inserting a paragraph above line 100 re-fires the ratchet on an entry
+     * nobody touched — recorded twice in one pull request — and, worse, it rots
+     * in silence: the migration that introduced this comment found three shipped
+     * entries that had stopped exempting anything, one naming line 100 of a
+     * 68-line file and two naming blank lines. Nothing reported it, because a
+     * drifted position key still parses.
+     *
+     * An anchor keys the exemption to the content being exempted, so it survives
+     * the edit that moves it and fails loudly when that content is gone.
+     * `validate_allowlist` additionally requires it to match exactly one line:
+     * `includes` is file-scoped, so a too-short anchor would silently exempt a
+     * second line nobody reviewed.
      */
     anchor?: string;
     reason?: string;
@@ -328,35 +335,124 @@ function _load_allowlist(): Allowlist {
     }
 }
 
-function _allowlisted(
+/**
+ * Every allowlist entry must still exempt something, and exactly one thing.
+ *
+ * A position-keyed entry rots in silence: the line it names drifts, the entry
+ * keeps parsing, and nothing reports that an exemption stopped exempting. This
+ * repository shipped three such entries — one naming line 100 of a 68-line file,
+ * two naming blank lines — and the rot was invisible until the whole set was read
+ * at once. An anchor cannot drift, but it can over-reach: `includes` is
+ * file-scoped, so an anchor occurring twice silently exempts a second line nobody
+ * reviewed.
+ *
+ * Both failures are decidable from the file, so they are checked rather than
+ * trusted. `lines: '*'` stays legal — a deliberate whole-file exemption is a
+ * different thing from a position key, and it cannot drift.
+ */
+/**
+ * The exact text `_allowlisted` compares an anchor against.
+ *
+ * The matcher sees `Hit.snippet`, not the raw line — trimmed and cut at 160
+ * chars. A validator reading the raw line would clear an anchor copied with its
+ * indentation, or drawn from past column 160, and the gate would then fail to
+ * suppress a hit the maintainer was told is exempt. One function, both callers.
+ */
+export function anchor_haystack(line: string): string {
+    return line.trim().slice(0, 160);
+}
+
+export function validate_allowlist(allowlist: Allowlist, repo_root?: string): string[] {
+    // Default to the MUTABLE root, not the real one: the scan resolves entry
+    // paths against `REPO_ROOT`, and a validator resolving them anywhere else
+    // would report every entry missing the moment a caller redirects the tree.
+    const root = repo_root ?? REPO_ROOT;
+    const problems: string[] = [];
+    for (const entry of allowlist.entries ?? []) {
+        const file = entry.file;
+        if (typeof file !== 'string' || file === '') {
+            problems.push('entry without a `file`');
+            continue;
+        }
+        if (Array.isArray(entry.lines)) {
+            problems.push(
+                `${file}: position-keyed (\`lines: [${entry.lines.join(', ')}]\`) — ` +
+                    'use `anchor` with a substring of the exempted line; a line number ' +
+                    'drifts out from under its own exemption on any edit above it',
+            );
+            continue;
+        }
+        if (entry.lines === '*') {
+            // A whole-file exemption never consults the anchor, so validating one
+            // here would stop every scan for a field the matcher does not read.
+            continue;
+        }
+        const anchor = entry.anchor;
+        if (typeof anchor !== 'string' || anchor === '') {
+            problems.push(`${file}: neither an \`anchor\` nor \`lines: "*"\``);
+            continue;
+        }
+        const abs = path.join(root, file);
+        if (!_isFile(abs)) {
+            problems.push(`${file}: anchored entry names a file that does not exist`);
+            continue;
+        }
+        const matches = fs
+            .readFileSync(abs, 'utf-8')
+            .split('\n')
+            .filter((l) => anchor_haystack(l).includes(anchor)).length;
+        if (matches === 0) {
+            problems.push(
+                `${file}: anchor matches no line — the exempted content is gone, so the ` +
+                    `entry exempts nothing: ${JSON.stringify(anchor.slice(0, 50))}`,
+            );
+        } else if (matches > 1) {
+            problems.push(
+                `${file}: anchor matches ${matches} lines — it would exempt more than the ` +
+                    `reviewed one; lengthen it: ${JSON.stringify(anchor.slice(0, 50))}`,
+            );
+        }
+    }
+    return problems;
+}
+
+/**
+ * Index of the entry that exempts this hit, or `-1`.
+ *
+ * Returns the index rather than a boolean so the run can report which
+ * exemptions were never used. An entry that suppresses nothing is the failure
+ * this gate shipped: three had rotted under position keys, and re-keying them to
+ * anchors preserved the rot, because an anchor resolving to a line says nothing
+ * about that line producing a hit.
+ */
+function _allowlist_index(
     rel_path: string,
     line_no: number,
     allowlist: Allowlist,
     line_text = '',
-): boolean {
+): number {
     const logical = strip_source_prefix(rel_path);
-    for (const entry of allowlist.entries ?? []) {
+    const entries = allowlist.entries ?? [];
+    for (let i = 0; i < entries.length; i += 1) {
+        const entry = entries[i] as AllowlistEntry;
         const entry_file = entry.file;
         const entry_logical =
             typeof entry_file === 'string' ? strip_source_prefix(entry_file) : null;
         if (entry_file !== rel_path && (logical === null || entry_logical !== logical)) {
             continue;
         }
-        const lines = entry.lines;
-        if (lines === '*') {
-            return true;
+        if (entry.lines === '*') {
+            return i;
         }
-        // Content anchor before line number: an anchored entry keeps matching
-        // after an insertion moves the line, which a position key cannot.
+        // Content anchor, and nothing else. A numeric `lines` entry never reaches
+        // this point — `validate_allowlist` stops the run on one — so matching it
+        // here would be a branch that only fires for input the gate rejects.
         const anchor = entry.anchor;
         if (typeof anchor === 'string' && anchor !== '' && line_text.includes(anchor)) {
-            return true;
-        }
-        if (Array.isArray(lines) && lines.includes(line_no)) {
-            return true;
+            return i;
         }
     }
-    return false;
+    return -1;
 }
 
 function _families_in_window(lines: string[], idx: number, radius = 10): Set<string> {
@@ -502,7 +598,12 @@ function* iter_md_files(paths: Iterable<string>): Generator<string> {
     }
 }
 
-function parse_args(argv: readonly string[]): { json: boolean; quiet: boolean; paths: string[] } {
+function parse_args(argv: readonly string[]): {
+    json: boolean;
+    quiet: boolean;
+    narrowed: boolean;
+    paths: string[];
+} {
     let json = false;
     let quiet = false;
     const paths: string[] = [];
@@ -535,16 +636,26 @@ function parse_args(argv: readonly string[]): { json: boolean; quiet: boolean; p
             process.exit(2);
         }
     }
-    return { json, quiet, paths: paths.length > 0 ? paths : _default_paths() };
+    // `narrowed` distinguishes an explicit `--paths` from the default full set.
+    // `paths.length === 0` cannot: the default is three subdirectories, so a full
+    // run also arrives here with a non-empty list — which silently disabled the
+    // unused-exemption check the first time it was written against that test.
+    return {
+        json,
+        quiet,
+        narrowed: paths.length > 0,
+        paths: paths.length > 0 ? paths : _default_paths(),
+    };
 }
 
 /**
  * The allowlist entry that would silence one finding, ready to paste.
  *
- * Anchored on the matched token rather than on the line number: a
- * position-keyed entry re-fires the moment an insertion above moves the line,
- * on an entry nobody touched, which `check_suppression_hygiene` counts every
- * run until the existing 18 migrate.
+ * Anchored on the matched token rather than on the line number: a position key
+ * re-fires the moment an insertion above moves the line, on an entry nobody
+ * touched. The form is no longer merely discouraged — `validate_allowlist`
+ * refuses it, and the last 18 position-keyed entries were migrated to anchors
+ * in the change that introduced the refusal.
  */
 export function suppressionKey(rel: string, hit: Hit): string {
     const anchor = hit.snippet.trim().slice(0, 60);
@@ -613,7 +724,19 @@ export function main(argv?: readonly string[]): number {
     const args = parse_args(raw);
 
     const allowlist = _load_allowlist();
+    // Judge the exemptions before judging any file. A rotted entry produces a
+    // green run that means nothing, which is the one failure mode a gate must
+    // not have. Structural problems are collected here and reported at the end,
+    // NOT returned on early: an early return skipped the `scanned:` line the
+    // gate-coverage collector consumes and left `--json` emitting nothing, so a
+    // consumer parsing the envelope threw on exactly the runs where the gate
+    // reports itself unusable.
+    const allowlist_problems = validate_allowlist(allowlist);
     const file_hits: Array<[string, Hit[]]> = [];
+    // Which exemptions actually suppressed something. Only meaningful over a full
+    // scan: with `--paths` narrowing the tree, an entry for a file outside the
+    // scope is unused for a reason that says nothing about the entry.
+    const used_entries = new Set<number>();
     let total_hits = 0;
     let allowlisted_total = 0;
     // Every enumerated file is planned up front, so the five exemption branches
@@ -661,7 +784,9 @@ export function main(argv?: readonly string[]): number {
             if (h.cross_stack) {
                 continue;
             }
-            if (_allowlisted(rel, h.line, allowlist, h.snippet)) {
+            const idx = _allowlist_index(rel, h.line, allowlist, h.snippet);
+            if (idx >= 0) {
+                used_entries.add(idx);
                 h.allowlisted = true;
                 allowlisted_total += 1;
                 continue;
@@ -679,10 +804,31 @@ export function main(argv?: readonly string[]): number {
         }
     }
 
+    // An exemption that suppressed nothing over a FULL scan exempts nothing at
+    // all — the rot the anchor migration was supposed to end, and which anchoring
+    // alone does not end: an anchor resolving to a line says nothing about that
+    // line producing a hit. Only checked on a full scan, because `--paths` makes
+    // "unused" mean "out of scope" instead.
+    if (!args.narrowed) {
+        const entries = allowlist.entries ?? [];
+        for (let i = 0; i < entries.length; i += 1) {
+            if (used_entries.has(i)) {
+                continue;
+            }
+            const e = entries[i] as AllowlistEntry;
+            allowlist_problems.push(
+                `${String(e.file)}: exemption suppressed nothing this run — the line it names ` +
+                    'produces no leakage hit, so it exempts nothing: ' +
+                    JSON.stringify(String(e.anchor ?? e.lines).slice(0, 50)),
+            );
+        }
+    }
+
     const summary = {
         total_hits,
         files: file_hits.length,
         allowlisted: allowlisted_total,
+        allowlist_problems: allowlist_problems.length,
     };
 
     // Finalize before either output branch: an unaccounted target must throw
@@ -696,10 +842,11 @@ export function main(argv?: readonly string[]): number {
                 hits.map((h) => ({ file: relToRepo(p), ...h })),
             ),
             summary,
+            allowlist_problems,
             ledger: tally,
         };
         process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
-        return total_hits ? 1 : 0;
+        return total_hits || allowlist_problems.length ? 1 : 0;
     }
 
     if (!args.quiet) {
@@ -731,6 +878,26 @@ export function main(argv?: readonly string[]): number {
     // judged) and is the same "reading M as coverage" trap the human summary
     // carries. The ledger makes the honest number the cheap one to publish.
     process.stderr.write(`scanned: ${String(tally.completed + tally.failed)}\n`);
+
+    // Reported AFTER the ledger and the `scanned:` line, so a broken allowlist
+    // still produces both output contracts. An exemption problem fails the run
+    // on its own: a gate that scans cleanly through unusable exemptions is
+    // reporting on a question nobody asked.
+    if (allowlist_problems.length > 0) {
+        process.stderr.write(
+            `\n❌  ${allowlist_problems.length} unusable allowlist entr` +
+                `${allowlist_problems.length === 1 ? 'y' : 'ies'}:\n`,
+        );
+        for (const p of allowlist_problems) {
+            process.stderr.write(`  · ${p}\n`);
+        }
+        process.stderr.write(
+            '  An exemption that names nothing, suppresses nothing, or reaches further\n' +
+                '  than the line it was reviewed for is not an exemption. Remove it or\n' +
+                '  re-anchor it to the content it is meant to cover.\n',
+        );
+        return 1;
+    }
     return total_hits ? 1 : 0;
 }