@holmes-lab/holmes-kit 0.3.6 → 0.3.8

package/CHANGELOG.md

@@ -4,6 +4,58 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+<!-- @implements A-SPEC-209 -->
+## [0.3.8] - 2026-09-01
+
+Approval-UX slice pair (REQ-497 완결): the resident CLI surface decides on ONE raw keypress with
+an OS arrival ping, and the in-session dialog lane gets a one-choice form, a finite re-display
+and per-path deadlines.
+
+### Added
+
+- **`approve --watch` single-key TUI + OS notification** (A-SPEC-497.2): a pending item is
+  decided by one raw keypress — `a` approve / `d` deny / `q` one-line question / `s` skip — no
+  Enter, no deadline (a human terminal can wait forever). Unknown keys decide nothing
+  (fail-closed) and Ctrl-C leaves without deciding. Each NEW arrival fires one OS-native
+  notification (macOS `osascript`, Windows WinRT toast; flattened text, every failure swallowed —
+  a dead notifier changes nothing about the queue or the gates).
+- **Elicitation one-choice form, finite re-display, per-path deadlines** (A-SPEC-497.3): the
+  in-session approval dialog asks the DECISION alone (reason moves to a second dialog shown only
+  after deny/question — a question requires text, a deny stands without it); an expired dialog is
+  re-presented exactly once with a visible "재표시 2/2" counter (stale widgets survive on screen —
+  measured); and the deadline differs by path — lock-free `spec-approve` gets 240s, lock-holding
+  `review-resolve` keeps 120s with no re-display (starvation ceiling preserved). Decline, cancel
+  and any answer are never re-asked. Multi-cycle expiry measured end-to-end over the real MCP
+  protocol: two 240s presentations, summed 480s expired refusal, outer call alive.
+
+### Changed
+
+- The `--watch` input path replaces the readline line-reader with a raw-mode key stream; the
+  non-watch interactive surface is unchanged. The elicitation stage-1 form no longer carries a
+  `reason` field (moved to stage 2); silent-path refusal text stays byte-identical
+  (A-SPEC-263.1), and the expiry notice format is unchanged (summed seconds).
+
+<!-- @implements A-SPEC-209 -->
+## [0.3.7] - 2026-09-01
+
+Field-incident hardening: consistency warning lints over the code graph, and an approval queue
+that stops burying the one approval that matters.
+
+### Added
+
+- **Consistency lints, opt-in** (A-SPEC-506.1): `cpg_scan` accepts `lints: true` and adds a
+  warning-signal field (Python, with an honest `limits` envelope): `dynamicRef` — a literal
+  `getattr`/`hasattr` name absent from the scanned symbol census (field incident: 49
+  owner-approved deletions silently no-op'ed against a nonexistent method) — and
+  `asyncBlocking` — a known-blocking call inside an `async def`, unwrapped on its line (field
+  incident: scheduler starvation while the same file's other call sites used `to_thread`). No
+  gate consumes these; the default scan result is unchanged.
+- **Approval-queue staleness** (A-SPEC-507.1): the `approve` list sorts by latest activity and
+  folds entries whose last activity exceeded `--stale-hours` (default 24; `--all` unfolds,
+  `--stale-hours 0` disables) — measured: 51 pending rows, mostly week-old residue, buried the
+  one live approval at [32]. The ledger deletes nothing; a re-filed request revives itself; and
+  gate-path folds take no clock at all (value-identical without the view options).
+
 <!-- @implements A-SPEC-209 -->
 ## [0.3.6] - 2026-09-01
 

package/dist/.build-id

@@ -1 +1 @@
-c3e5866-mthi2ccn
+809f8c3-mthx43ms

package/dist/holmes/cli/approve-watch.d.ts

@@ -1,4 +1,28 @@
+import { readQueue, PendingRequest } from '../governance/approval-queue';
 import { ApproveIO } from './approve';
+/** The raw-mode key source a single-key watch listens to (process.stdin in the shipped CLI). */
+export interface KeyStream {
+    setRawMode?: (raw: boolean) => unknown;
+    resume?: () => unknown;
+    pause?: () => unknown;
+    on(event: 'data', fn: (chunk: Buffer | string) => void): unknown;
+    removeListener(event: 'data', fn: (chunk: Buffer | string) => void): unknown;
+}
+/**
+ * ONE raw keypress decides an item — a/d/q/s; q collects one follow-up line (the question).
+ * Unknown keys decide NOTHING (a typo must not become an approval — fail-closed), and Ctrl-C
+ * rejects with AbortError: leaving is not deciding. No deadline anywhere: the MAIN LANE's whole
+ * point is that a human terminal can wait forever (H-SPEC-497).
+ */
+export declare function decideByKey(stream: KeyStream, _item: Pick<PendingRequest, 'id'>): Promise<'granted' | 'denied' | 'skipped' | {
+    question: string;
+}>;
+/**
+ * Present each pending item and apply the single-key decision. The item summary goes through the
+ * SAME escaped cells the list uses (agent-controlled text never owns a line), and a denial gets a
+ * canned-but-visible reason — the agent must still see that a human said no.
+ */
+export declare function presentByKey(root: string, io: ApproveIO, actor: string, stream: KeyStream, state: ReturnType<typeof readQueue>): Promise<void>;
 /** The idle line, printed once on entering idle (not on every poll — flood is the template's enemy). */
 export declare const WATCH_IDLE = "\u25C6 \uC2B9\uC778 \uB300\uAE30 \uC911\u2026 (Ctrl-C \uB85C \uC885\uB8CC)";
 /** Default idle poll cadence. The reaction DEADLINE is a tested judgment (T-SPEC), not this number. */
@@ -13,6 +37,14 @@ export interface WatchOpts {
      * Must resolve early if `signal` aborts, so an idle watch shuts down at once.
      */
     waitIdle?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /**
+     * @implements A-SPEC-497.2
+     * When present, NEW items are presented via the single-key surface (presentByKey) instead of
+     * runInteractive — the shipped CLI passes raw-mode stdin here. Absent: legacy path, byte-for-byte.
+     */
+    keyStream?: KeyStream;
+    /** Called once per NEW pending item (lastPresented dedup) — a throwing notifier is swallowed. */
+    notify?: (item: PendingRequest) => void;
 }
 /** Exported for test: the shipped idle wait must resolve at once on abort, not after the timer. */
 export declare function defaultWaitIdle(ms: number, signal?: AbortSignal): Promise<void>;

package/dist/holmes/cli/approve-watch.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_POLL_MS = exports.WATCH_IDLE = void 0;
+exports.decideByKey = decideByKey;
+exports.presentByKey = presentByKey;
 exports.defaultWaitIdle = defaultWaitIdle;
 exports.runWatch = runWatch;
 // @implements A-SPEC-262.2
@@ -14,6 +16,92 @@ exports.runWatch = runWatch;
 // existing runInteractive, and waits between polls when the queue is empty.
 const approval_queue_1 = require("../governance/approval-queue");
 const approve_1 = require("./approve");
+// @implements A-SPEC-497.2
+/**
+ * ONE raw keypress decides an item — a/d/q/s; q collects one follow-up line (the question).
+ * Unknown keys decide NOTHING (a typo must not become an approval — fail-closed), and Ctrl-C
+ * rejects with AbortError: leaving is not deciding. No deadline anywhere: the MAIN LANE's whole
+ * point is that a human terminal can wait forever (H-SPEC-497).
+ */
+function decideByKey(stream, _item) {
+    return new Promise((resolve, reject) => {
+        let questionMode = false;
+        let line = '';
+        const onData = (chunk) => {
+            const s = chunk.toString();
+            for (const ch of s) {
+                if (ch === '') {
+                    cleanup();
+                    const e = new Error('operator left');
+                    e.name = 'AbortError';
+                    reject(e);
+                    return;
+                }
+                if (questionMode) {
+                    if (ch === '\r' || ch === '\n') {
+                        cleanup();
+                        resolve({ question: line });
+                        return;
+                    }
+                    if (ch === '' || ch === '\b') {
+                        line = line.slice(0, -1);
+                        continue;
+                    }
+                    line += ch;
+                    continue;
+                }
+                if (ch === 'a') {
+                    cleanup();
+                    resolve('granted');
+                    return;
+                }
+                if (ch === 'd') {
+                    cleanup();
+                    resolve('denied');
+                    return;
+                }
+                if (ch === 's') {
+                    cleanup();
+                    resolve('skipped');
+                    return;
+                }
+                if (ch === 'q') {
+                    questionMode = true;
+                    continue;
+                }
+                // any other key: not a decision — keep listening
+            }
+        };
+        const cleanup = () => { stream.removeListener('data', onData); };
+        stream.on('data', onData);
+    });
+}
+// @implements A-SPEC-497.2
+/**
+ * Present each pending item and apply the single-key decision. The item summary goes through the
+ * SAME escaped cells the list uses (agent-controlled text never owns a line), and a denial gets a
+ * canned-but-visible reason — the agent must still see that a human said no.
+ */
+async function presentByKey(root, io, actor, stream, state) {
+    for (const p of state.pending) {
+        io.print(`\n─ ${(0, approve_1.subjectCells)('─  ', p)}`);
+        io.print('[a]승인  [d]거부  [q]질문  [s]건너뜀 > ');
+        const d = await decideByKey(stream, p);
+        if (d === 'granted') {
+            const r = (0, approve_1.grantRequest)(root, p.id, { actor });
+            io.print(r.ok ? `✓ 승인 — ${(0, approve_1.subjectCells)('✓ 승인 — ', p)}` : `✗ ${r.reason}`);
+        }
+        else if (d === 'denied') {
+            const r = (0, approve_1.denyRequest)(root, p.id, '운영자가 watch에서 단일 키로 거부(사유 즉답 생략)', actor);
+            io.print(r.ok ? `✗ 거부 — ${(0, approve_1.subjectCells)('✗ 거부 — ', p)}` : `✗ ${r.reason}`);
+        }
+        else if (typeof d === 'object') {
+            const r = (0, approve_1.holdRequest)(root, p.id, d.question, actor);
+            io.print(r.ok ? `? 보류 — 질문이 다음 거부 문면에 실립니다` : `✗ ${r.reason}`);
+        }
+        // skipped: leave it pending, silently
+    }
+}
 /** The idle line, printed once on entering idle (not on every poll — flood is the template's enemy). */
 exports.WATCH_IDLE = '◆ 승인 대기 중… (Ctrl-C 로 종료)';
 /** Default idle poll cadence. The reaction DEADLINE is a tested judgment (T-SPEC), not this number. */
@@ -60,9 +148,24 @@ async function runWatch(root, io, actor, opts = {}) {
         const hasNew = state.pending.some((p) => !lastPresented.has(p.id));
         if (state.pending.length > 0 && hasNew) {
             idleAnnounced = false;
+            // @implements A-SPEC-497.2 — one notification per NEW item, and never a lever: a throwing
+            // notifier is swallowed (the same doctrine as the queue writer's own failures).
+            if (opts.notify) {
+                for (const p of state.pending) {
+                    if (lastPresented.has(p.id))
+                        continue;
+                    try {
+                        opts.notify(p);
+                    }
+                    catch { /* fire-and-forget */ }
+                }
+            }
             const shown = new Set(state.pending.map((p) => p.id)); // what this pass presents
             try {
-                await (0, approve_1.runInteractive)(root, io, actor);
+                if (opts.keyStream)
+                    await presentByKey(root, io, actor, opts.keyStream, state);
+                else
+                    await (0, approve_1.runInteractive)(root, io, actor);
             }
             catch (e) {
                 // The operator leaving mid-decision (Ctrl-C / EOF) surfaces as AbortError through the

package/dist/holmes/cli/approve.d.ts

@@ -21,7 +21,19 @@ export declare function holdRequest(root: string, id: string, question: string,
  * when, and any standing question. Deliberately NO scope grammar anywhere — the moment the screen
  * teaches syntax, humans start typing it.
  */
-export declare function renderPending(state: QueueState): string;
+/**
+ * The list-view stale flags, parsed once: `--stale-hours <h>` (default 24; 0 disables folding —
+ * `--ttl` was already taken by the grant-lifetime flag) and `--all` to unfold. Returning null
+ * means "no clock": readQueue is then called without opts and the fold stays value-identical.
+ */
+export declare function staleView(flags: Record<string, unknown>): {
+    ttlMs: number;
+    showAll: boolean;
+} | null;
+export declare function renderPending(state: QueueState, view?: {
+    staleHours: number;
+    showAll: boolean;
+}): string;
 /**
  * @implements A-SPEC-262.1
  * What a decision line must say. Round-1: `✓ 승인 — <expires> 까지 유효` named NOTHING, so an index

package/dist/holmes/cli/approve.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.grantRequest = grantRequest;
 exports.denyRequest = denyRequest;
 exports.holdRequest = holdRequest;
+exports.staleView = staleView;
 exports.renderPending = renderPending;
 exports.subjectCells = subjectCells;
 exports.subjectRoom = subjectRoom;
@@ -236,7 +237,20 @@ function holdRequest(root, id, question, actor) {
  * when, and any standing question. Deliberately NO scope grammar anywhere — the moment the screen
  * teaches syntax, humans start typing it.
  */
-function renderPending(state) {
+// @implements A-SPEC-507.1
+/**
+ * The list-view stale flags, parsed once: `--stale-hours <h>` (default 24; 0 disables folding —
+ * `--ttl` was already taken by the grant-lifetime flag) and `--all` to unfold. Returning null
+ * means "no clock": readQueue is then called without opts and the fold stays value-identical.
+ */
+function staleView(flags) {
+    const raw = flags['stale-hours'];
+    const hours = typeof raw === 'string' ? Number(raw) : 24;
+    if (!Number.isFinite(hours) || hours <= 0)
+        return null;
+    return { ttlMs: hours * 3_600_000, showAll: flags.all === true };
+}
+function renderPending(state, view) {
     if (state.pending.length === 0) {
         // Round-7: this early return made the malformed-line row below UNREACHABLE in exactly the case
         // it exists for — a wholly corrupted queue printed "no requests waiting" and exited 0, which is
@@ -249,7 +263,13 @@ function renderPending(state) {
         return '승인 대기 중인 요청이 없습니다.';
     }
     const lines = [`◆ 승인 대기 ${state.pending.length}건`, ''];
-    state.pending.forEach((p, i) => {
+    // @implements A-SPEC-507.1 — the LIST VIEW sorts newest-activity-first and folds stale entries
+    // (C4: 51 rows, mostly week-old residue, buried the one live approval at [32]). Only when a view
+    // is passed: callers without one keep the legacy insertion order byte-for-byte.
+    const shown = view
+        ? [...state.pending].sort((a, b) => (Date.parse(b.lastTs) || 0) - (Date.parse(a.lastTs) || 0))
+        : state.pending;
+    shown.forEach((p, i) => {
         // @implements A-SPEC-262.1 — every field here is AGENT-CONTROLLED (the target is the command it
         // was blocked on). Round-1 forged two extra rows and hid the real ones behind an ANSI conceal,
         // and the operator granted a `curl … | sh` they never saw. The template owns the line structure.
@@ -266,6 +286,19 @@ function renderPending(state) {
         lines.push(`    id: ${(0, screen_safe_1.rowField)(p.id, 40)}`);
         lines.push('');
     });
+    if (view && state.expired.length > 0) {
+        if (view.showAll) {
+            // Folding is not concealment: --all shows every expired entry under a template-owned prefix.
+            for (const p of state.expired) {
+                lines.push(`[만료] ${subjectCells('[만료]  ', p)}`);
+                lines.push(`    마지막 활동: ${(0, screen_safe_1.rowField)(p.lastTs, 28)} · id: ${(0, screen_safe_1.rowField)(p.id, 40)}`);
+                lines.push('');
+            }
+        }
+        else {
+            lines.push(`⏳ 만료로 접힘 ${state.expired.length}건 (마지막 활동 ${view.staleHours}h 초과) — --all 로 표시`);
+        }
+    }
     if (state.malformedLines > 0)
         lines.push(`(큐에 읽을 수 없는 줄 ${state.malformedLines}건 — 손상 여부를 확인하십시오)`);
     return lines.join('\n');

package/dist/holmes/cli/index.js

@@ -787,8 +787,14 @@ async function main(argv) {
             process.stdout.write(r.ok ? `✓ 보류 — ${ref.subject('✓ 보류 — ')}\n${ref.detail('질문은 다음 거부 문면에')}\n` : `✗ ${r.reason}\n`);
             return r.ok ? 0 : 1;
         }
+        // @implements A-SPEC-507.1 — stale folding is a LIST-VIEW judgment: the clock enters only
+        // here, never on gate-path folds. `--stale-hours 0` disables it; `--all` unfolds.
+        const { staleView } = require('./approve');
+        const stale = staleView(flags);
+        const queueOpts = stale ? { now: Date.now(), ttlMs: stale.ttlMs } : undefined;
+        const listView = stale ? { staleHours: stale.ttlMs / 3_600_000, showAll: stale.showAll } : undefined;
         if (flags.list) {
-            process.stdout.write(renderPending(readQueue(root)) + '\n');
+            process.stdout.write(renderPending(readQueue(root, queueOpts), listView) + '\n');
             return 0;
         }
         // @implements A-SPEC-262.2 — the RESIDENT surface. Validate --poll-ms first (so a bad value is
@@ -808,17 +814,27 @@ async function main(argv) {
                 process.stderr.write('✗ 대화형 상주 모드(--watch)는 TTY 가 필요합니다 — 스크립트에서는 --list 를 쓰십시오\n');
                 return 1;
             }
+            // @implements A-SPEC-497.2 — the resident surface decides on ONE raw keypress (a/d/q/s, no
+            // Enter, no deadline) and pings the OS on each new arrival. Raw mode is restored on the way
+            // out whatever happens; Ctrl-C arrives as \x03 through decideByKey and ends the loop.
             const { runWatch } = require('./approve-watch');
-            const rl = require('node:readline/promises').createInterface({ input: process.stdin, output: process.stdout });
+            const { notifyQueueArrival } = require('./os-notify');
             const ac = new AbortController();
-            rl.once('close', () => ac.abort());
             const onSig = () => ac.abort();
             process.once('SIGINT', onSig);
+            const stdin = process.stdin;
             try {
+                stdin.setRawMode?.(true);
+                stdin.resume();
                 await runWatch(root, {
                     print: (t) => process.stdout.write(t + '\n'),
-                    ask: (q) => rl.question(q, { signal: ac.signal }),
-                }, actor, { signal: ac.signal, ...(pollMs !== undefined ? { pollMs } : {}) });
+                    ask: async () => '', // unused on the key surface; kept for the ApproveIO shape
+                }, actor, {
+                    signal: ac.signal,
+                    keyStream: stdin,
+                    notify: (p) => notifyQueueArrival(p),
+                    ...(pollMs !== undefined ? { pollMs } : {}),
+                });
             }
             catch (e) {
                 if (e?.name !== 'AbortError')
@@ -826,16 +842,17 @@ async function main(argv) {
             }
             finally {
                 process.removeListener('SIGINT', onSig);
-                rl.close();
+                stdin.setRawMode?.(false);
+                stdin.pause();
             }
             return 0;
         }
         // @implements A-SPEC-260 — the implicit non-TTY fallback tells the operator the next command,
         // with the real pending id filled in; the explicit --list above stays script-clean.
         if (!process.stdin.isTTY) {
-            const state = readQueue(root);
+            const state = readQueue(root, queueOpts);
             const hint = renderNonTtyHint(state);
-            process.stdout.write(renderPending(state) + (hint ? '\n\n' + hint : '') + '\n');
+            process.stdout.write(renderPending(state, listView) + (hint ? '\n\n' + hint : '') + '\n');
             return 0;
         }
         // @implements A-SPEC-262.1

package/dist/holmes/cli/os-notify.d.ts

@@ -0,0 +1,19 @@
+/**
+ * OS-native arrival notification for the approval queue — the MAIN LANE's "you are needed" ping.
+ * Fire-and-forget by doctrine: a notification failure must change NOTHING about the watch loop,
+ * the gate verdicts or the queue (the same swallow rule enqueueApprovalRequest lives by — the
+ * moment a dead notifier could change behavior, killing it becomes a lever).
+ *
+ * kind/target are AGENT-CONTROLLED text, so both are flattened before they reach a notification
+ * body: no control bytes, no forged lines in the notification center.
+ */
+import { ChildProcess } from 'node:child_process';
+import type { PendingRequest } from '../governance/approval-queue';
+export interface NotifyDeps {
+    platform: NodeJS.Platform;
+    spawn: (cmd: string, args: string[], opts?: {
+        stdio: 'ignore';
+        detached?: boolean;
+    }) => Pick<ChildProcess, 'unref' | 'on'>;
+}
+export declare function notifyQueueArrival(item: Pick<PendingRequest, 'kind' | 'target'>, deps?: NotifyDeps): void;

package/dist/holmes/cli/os-notify.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.notifyQueueArrival = notifyQueueArrival;
+// @implements A-SPEC-497.2
+/**
+ * OS-native arrival notification for the approval queue — the MAIN LANE's "you are needed" ping.
+ * Fire-and-forget by doctrine: a notification failure must change NOTHING about the watch loop,
+ * the gate verdicts or the queue (the same swallow rule enqueueApprovalRequest lives by — the
+ * moment a dead notifier could change behavior, killing it becomes a lever).
+ *
+ * kind/target are AGENT-CONTROLLED text, so both are flattened before they reach a notification
+ * body: no control bytes, no forged lines in the notification center.
+ */
+const node_child_process_1 = require("node:child_process");
+const screen_safe_1 = require("./screen-safe");
+function notifyQueueArrival(item, deps = { platform: process.platform, spawn: (cmd, args) => (0, node_child_process_1.spawn)(cmd, args, { stdio: 'ignore', detached: false }) }) {
+    try {
+        const kind = (0, screen_safe_1.flattenField)(item.kind, 40);
+        const target = (0, screen_safe_1.flattenField)(item.target, 80);
+        const body = `${kind} — ${target} · 결정: holmes approve`;
+        let cmd;
+        let args;
+        if (deps.platform === 'darwin') {
+            // AppleScript strings escape only backslash and double-quote; flatten already removed the rest.
+            const esc = body.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+            cmd = 'osascript';
+            args = ['-e', `display notification "${esc}" with title "Holmes-Kit 승인 요청"`];
+        }
+        else if (deps.platform === 'win32') {
+            // Toast via the WinRT bridge; single-quoted PowerShell literal with quotes doubled.
+            const esc = body.replace(/'/g, "''");
+            cmd = 'powershell.exe';
+            args = ['-NoProfile', '-Command',
+                `[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] > $null; ` +
+                    `$x = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02); ` +
+                    `$t = $x.GetElementsByTagName('text'); $t.Item(0).AppendChild($x.CreateTextNode('Holmes-Kit 승인 요청')) > $null; ` +
+                    `$t.Item(1).AppendChild($x.CreateTextNode('${esc}')) > $null; ` +
+                    `[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('holmes-kit').Show([Windows.UI.Notifications.ToastNotification]::new($x))`];
+        }
+        else {
+            return; // unsupported platform: silent pass-through, by contract
+        }
+        const child = deps.spawn(cmd, args, { stdio: 'ignore', detached: false });
+        child.on?.('error', () => { });
+        child.unref?.();
+    }
+    catch { /* a notification must never take the loop down with it */ }
+}

package/dist/holmes/cpg/consistency-lints.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Consistency lints over what the repo already KNOWS — two field incidents, one gap:
+ *
+ * P-G  `getattr(mem, "delete_fact", None)` referenced a symbol no class defines; the optional
+ *      default hid the absence and 49 owner-approved deletions silently no-op'ed. The symbol
+ *      census (CPG scan) had the answer all along — nobody asked it.
+ * P-J  an `async def` body called sqlite directly and starved the scheduler, while the SAME
+ *      file's other call sites wrapped the call in `to_thread` — the correct convention was one
+ *      screen away.
+ *
+ * WARNING SIGNALS ONLY: no gate consumes these (association proposes, determinism judges — the
+ * standing principle). Text heuristics with honest limits (LINT_LIMITS): literal names only,
+ * same-line wrapping exemption only, Python only — both incidents were Python; extensions need
+ * their own field evidence, like every pattern list in this repository.
+ */
+export declare const LINT_LIMITS: readonly string[];
+/** P-G: literal getattr/hasattr names absent from the repo's symbol census. */
+export declare function dynamicRefFindings(code: string, defined: ReadonlySet<string>): Array<{
+    name: string;
+    line: number;
+}>;
+/** P-J: known-blocking calls inside an async def's indentation block, unwrapped on their line. */
+export declare function asyncBlockingFindings(code: string): Array<{
+    pattern: string;
+    line: number;
+}>;

package/dist/holmes/cpg/consistency-lints.js

@@ -0,0 +1,67 @@
+"use strict";
+// @implements A-SPEC-506.1
+/**
+ * Consistency lints over what the repo already KNOWS — two field incidents, one gap:
+ *
+ * P-G  `getattr(mem, "delete_fact", None)` referenced a symbol no class defines; the optional
+ *      default hid the absence and 49 owner-approved deletions silently no-op'ed. The symbol
+ *      census (CPG scan) had the answer all along — nobody asked it.
+ * P-J  an `async def` body called sqlite directly and starved the scheduler, while the SAME
+ *      file's other call sites wrapped the call in `to_thread` — the correct convention was one
+ *      screen away.
+ *
+ * WARNING SIGNALS ONLY: no gate consumes these (association proposes, determinism judges — the
+ * standing principle). Text heuristics with honest limits (LINT_LIMITS): literal names only,
+ * same-line wrapping exemption only, Python only — both incidents were Python; extensions need
+ * their own field evidence, like every pattern list in this repository.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LINT_LIMITS = void 0;
+exports.dynamicRefFindings = dynamicRefFindings;
+exports.asyncBlockingFindings = asyncBlockingFindings;
+exports.LINT_LIMITS = [
+    '리터럴 이름 인자만 판정한다 — getattr(obj, 변수)는 판정 불가로 건너뛴다',
+    '차단 패턴 목록은 실사고·명백성 기반 최소 집합이다(time.sleep·requests.동사·sqlite3.·subprocess.run·urllib.request.urlopen) — 확장은 새 실측으로만',
+    'to_thread/run_in_executor 면제는 같은 행에서만 인식한다 — 여러 줄 래핑은 오탐될 수 있다',
+    '.py 텍스트 휴리스틱이다 — 비파이썬 언어와 문자열 속 코드는 보지 않는다',
+];
+const DYNAMIC_REF_RE = /\b(?:getattr|hasattr)\(\s*[^,()]+,\s*['"](\w+)['"]/g;
+/** P-G: literal getattr/hasattr names absent from the repo's symbol census. */
+function dynamicRefFindings(code, defined) {
+    const out = [];
+    for (const m of code.matchAll(DYNAMIC_REF_RE)) {
+        const name = m[1];
+        if (defined.has(name))
+            continue;
+        out.push({ name, line: code.slice(0, m.index).split('\n').length });
+    }
+    return out;
+}
+const BLOCKING = ['time.sleep(', 'requests.get(', 'requests.post(', 'requests.put(',
+    'requests.delete(', 'requests.request(', 'sqlite3.', 'subprocess.run(', 'urllib.request.urlopen'];
+const EXEMPT_RE = /to_thread|run_in_executor/;
+/** P-J: known-blocking calls inside an async def's indentation block, unwrapped on their line. */
+function asyncBlockingFindings(code) {
+    const out = [];
+    const lines = code.split('\n');
+    let asyncIndent = null; // indentation of the enclosing `async def`, when inside one
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const indent = line.length - line.trimStart().length;
+        const isBlank = line.trim() === '';
+        if (asyncIndent !== null && !isBlank && indent <= asyncIndent)
+            asyncIndent = null; // dedent ends the block
+        const def = /^(\s*)async\s+def\b/.exec(line);
+        if (def) {
+            asyncIndent = def[1].length;
+            continue;
+        }
+        if (asyncIndent === null || isBlank || EXEMPT_RE.test(line))
+            continue;
+        for (const pattern of BLOCKING) {
+            if (line.includes(pattern))
+                out.push({ pattern, line: i + 1 });
+        }
+    }
+    return out;
+}

package/dist/holmes/governance/approval-queue.d.ts

@@ -31,6 +31,14 @@ export interface PendingRequest {
 }
 export interface QueueState {
     pending: PendingRequest[];
+    /**
+     * @implements A-SPEC-507.1
+     * Pending entries whose last activity exceeded the caller's TTL — populated ONLY when the fold
+     * was given a clock ({now, ttlMs}), so gate-path folds never depend on when you look. C4
+     * measured the harm of agelessness: 51 entries, mostly week-old residue, buried the one live
+     * approval at [32]. Expiry is a display-layer judgment; the ledger keeps every event.
+     */
+    expired: PendingRequest[];
     /** Broken lines are counted, never swallowed: an empty-looking queue must be distinguishable from a corrupted one. */
     malformedLines: number;
     /**
@@ -64,7 +72,10 @@ export declare function approvalRequestId(kind: string, target: string): string;
  * entry's pending state: an old CLI reading a new queue must not silently mis-report what is
  * waiting.
  */
-export declare function foldQueue(lines: string[]): QueueState;
+export declare function foldQueue(lines: string[], opts?: {
+    now: number;
+    ttlMs: number;
+}): QueueState;
 /**
  * Append a request event. Fire-and-forget.
  *
@@ -79,7 +90,10 @@ export declare function enqueueApprovalRequest(root: string, req: {
     why: string;
 }): boolean;
 /** Read and fold the queue on disk. A missing file is an empty queue, not an error. */
-export declare function readQueue(root: string): QueueState;
+export declare function readQueue(root: string, opts?: {
+    now: number;
+    ttlMs: number;
+}): QueueState;
 /**
  * The refusal-message suffix pointing the operator at the review CLI.
  *

package/dist/holmes/governance/approval-queue.js

@@ -83,7 +83,7 @@ function approvalRequestId(kind, target) {
  * entry's pending state: an old CLI reading a new queue must not silently mis-report what is
  * waiting.
  */
-function foldQueue(lines) {
+function foldQueue(lines, opts) {
     const pending = new Map();
     const decisions = {};
     let malformedLines = 0;
@@ -155,7 +155,18 @@ function foldQueue(lines) {
                 break;
         }
     }
-    return { pending: [...pending.values()], malformedLines, decisions };
+    const all = [...pending.values()];
+    if (!opts)
+        return { pending: all, expired: [], malformedLines, decisions };
+    // @implements A-SPEC-507.1 — strict excess only, and an unparseable lastTs stays ACTIVE: a
+    // clockless entry must never be silently hidden by a clock it does not carry.
+    const expired = [];
+    const active = [];
+    for (const p of all) {
+        const last = Date.parse(p.lastTs);
+        (Number.isFinite(last) && last + opts.ttlMs < opts.now ? expired : active).push(p);
+    }
+    return { pending: active, expired, malformedLines, decisions };
 }
 /**
  * Append a request event. Fire-and-forget.
@@ -223,7 +234,7 @@ function isPlainFile(file) {
     }
 }
 /** Read and fold the queue on disk. A missing file is an empty queue, not an error. */
-function readQueue(root) {
+function readQueue(root, opts) {
     const file = path.join(root, exports.QUEUE_RELPATH);
     try {
         // TYPE BEFORE READ. `readFileSync` on a FIFO blocks inside open(2) forever — no throw, no
@@ -232,12 +243,12 @@ function readQueue(root) {
         // hook, the stop hook and the MCP handlers, not just the CLI. `approve-context.ts` has guarded
         // this since the 2026-08-24 hang; the queue reader, which far more code depends on, did not.
         if (!fs.lstatSync(file).isFile())
-            return { pending: [], malformedLines: 1, decisions: {} };
+            return { pending: [], expired: [], malformedLines: 1, decisions: {} };
         const raw = fs.readFileSync(file, 'utf8');
-        return foldQueue(raw.split('\n'));
+        return foldQueue(raw.split('\n'), opts);
     }
     catch {
-        return { pending: [], malformedLines: 0, decisions: {} };
+        return { pending: [], expired: [], malformedLines: 0, decisions: {} };
     }
 }
 /**

package/dist/holmes/mcp/elicit-approval.d.ts

@@ -48,42 +48,75 @@ export type ElicitOutcome = {
     kind: 'silent';
 };
 export type Elicitor = (req: ElicitApprovalRequest) => Promise<ElicitOutcome>;
-/** The one timeout truth: the SDK option, the dialog forewarning and `waitedMs` all derive from it. */
+/**
+ * The lock-holding path's timeout truth (and the stage-2 reason dialog's): review-resolve holds
+ * the findings-ledger lock while the dialog waits, so its ceiling never grows (REQ-497 기아 방지).
+ */
 export declare const ELICIT_TIMEOUT_MS = 120000;
+/**
+ * Per-path dialog deadline — the ONE number the ⏱ forewarning, the SDK timeout option and the
+ * summed `waitedMs` all derive from. Lock-free kinds (spec-approve) get 240s: nothing starves
+ * while that dialog waits, and the operator complaint being fixed was expiry-too-soon. The
+ * lock-holding kind keeps 120s (see ELICIT_TIMEOUT_MS above).
+ */
+export declare function elicitTimeoutMsFor(kind: string): number;
+/**
+ * Finite re-display: first presentation + exactly ONE re-presentation, lock-free kinds only.
+ * Only EXPIRY re-presents — decline, cancel and any answer end the flow at once (a human NO is
+ * never re-asked). Client measurement 2026-08-31: stale dialogs stay on screen after
+ * notifications/cancelled, so the re-display carries a visible attempt counter instead of
+ * pretending the old widget is gone.
+ */
+export declare const MAX_PRESENTATIONS = 2;
 /**
  * Classify an elicitInput rejection. Only the exact SDK timeout code — on a real Error — is
  * `expired`; a message that merely SAYS "timed out", a near-miss code, or a code on a non-Error
  * is `silent`, because the expiry face carries friendlier guidance and must not be spoofable.
  */
-export declare function classifyElicitError(e: unknown): ElicitOutcome;
+export declare function classifyElicitError(e: unknown, timeoutMs?: number): ElicitOutcome;
 /**
  * The expiry notice that LEADS an expired refusal: what happened (the session dialog expired),
  * where the request went (the approval queue), and where the decision still lives (the CLI).
  * Template-owned text with no interpolated attacker data.
  */
 export declare function expiredNotice(waitedMs: number): string;
-/**
- * The question form. Decisions only (REQ-263 Out): the single free-text field is `reason`, and it
- * is subordinate to the decision — this channel never collects arbitrary input.
- */
-export declare function buildElicitRequest(req: ElicitApprovalRequest): {
+export interface ElicitForm {
     message: string;
     requestedSchema: {
         type: 'object';
-        properties: {
-            decision: {
-                type: 'string';
-                enum: string[];
-                description: string;
-            };
-            reason: {
-                type: 'string';
-                description: string;
-            };
-        };
+        properties: Record<string, {
+            type: 'string';
+            enum?: string[];
+            description: string;
+        }>;
         required: string[];
     };
-};
+}
+/**
+ * Stage-1 form: the DECISION alone, so approving is one choice (S-497.3's 1-key promise). The
+ * reason field moved to stage 2 — it exists only after deny/question (decisions only, REQ-263 Out:
+ * this channel never collects arbitrary input). A re-presentation (attempt 2) leads with a
+ * template-owned counter line, so the human can tell the live dialog from the stale one their
+ * client left on screen (measured 2026-08-31: widgets survive notifications/cancelled).
+ */
+export declare function buildDecisionForm(req: ElicitApprovalRequest, attempt: number, timeoutMs: number): ElicitForm;
+/**
+ * Stage-2 form: the reason alone, asked only after deny/question. A question without text is
+ * useless, so `reason` is required there; a deny stands on its own, so there it is optional.
+ */
+export declare function buildReasonForm(decision: 'deny' | 'question', timeoutMs: number): ElicitForm;
+/** The SDK call, one layer thin — the only impure seam. Expiry arrives as a rejection. */
+export type RawElicit = (form: ElicitForm, timeoutMs: number) => Promise<{
+    action?: unknown;
+    content?: unknown;
+} | null | undefined>;
+/**
+ * The two-stage flow. Fates preserved exactly (H-SPEC-497 Interfaces): the return is the same
+ * discriminated union handlers already consume, so nothing above this seam changes. Only EXPIRY
+ * of stage 1 re-presents (once, lock-free kinds only); a stage-2 failure of ANY kind never erases
+ * the stage-1 decision — un-deciding a human is the one thing this channel must not do.
+ */
+export declare function runElicitFlow(raw: RawElicit, req: ElicitApprovalRequest): Promise<ElicitOutcome>;
 /**
  * Map a client's ElicitResult to a decision — FAIL-CLOSED: only the exact shape
  * `{action:'accept', content:{decision:'approve'}}` grants; every malformed shape (missing action,

package/dist/holmes/mcp/elicit-approval.js

@@ -1,10 +1,13 @@
 "use strict";
 // @implements A-SPEC-263.1
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ELICIT_TIMEOUT_MS = exports.ELICITABLE_KINDS = void 0;
+exports.MAX_PRESENTATIONS = exports.ELICIT_TIMEOUT_MS = exports.ELICITABLE_KINDS = void 0;
+exports.elicitTimeoutMsFor = elicitTimeoutMsFor;
 exports.classifyElicitError = classifyElicitError;
 exports.expiredNotice = expiredNotice;
-exports.buildElicitRequest = buildElicitRequest;
+exports.buildDecisionForm = buildDecisionForm;
+exports.buildReasonForm = buildReasonForm;
+exports.runElicitFlow = runElicitFlow;
 exports.interpretElicitResult = interpretElicitResult;
 /**
  * The decision comes INTO the session (REQ-263): an approval-shaped refusal (spec_approve without a
@@ -28,8 +31,30 @@ exports.interpretElicitResult = interpretElicitResult;
  */
 /** Approval kinds that may ask in-session. Widening this set is a spec revision, not a drive-by. */
 exports.ELICITABLE_KINDS = new Set(['spec-approve', 'review-resolve']);
-/** The one timeout truth: the SDK option, the dialog forewarning and `waitedMs` all derive from it. */
+/**
+ * The lock-holding path's timeout truth (and the stage-2 reason dialog's): review-resolve holds
+ * the findings-ledger lock while the dialog waits, so its ceiling never grows (REQ-497 기아 방지).
+ */
 exports.ELICIT_TIMEOUT_MS = 120_000;
+// @implements A-SPEC-497.3
+/**
+ * Per-path dialog deadline — the ONE number the ⏱ forewarning, the SDK timeout option and the
+ * summed `waitedMs` all derive from. Lock-free kinds (spec-approve) get 240s: nothing starves
+ * while that dialog waits, and the operator complaint being fixed was expiry-too-soon. The
+ * lock-holding kind keeps 120s (see ELICIT_TIMEOUT_MS above).
+ */
+function elicitTimeoutMsFor(kind) {
+    return kind === 'review-resolve' ? exports.ELICIT_TIMEOUT_MS : 240_000;
+}
+// @implements A-SPEC-497.3
+/**
+ * Finite re-display: first presentation + exactly ONE re-presentation, lock-free kinds only.
+ * Only EXPIRY re-presents — decline, cancel and any answer end the flow at once (a human NO is
+ * never re-asked). Client measurement 2026-08-31: stale dialogs stay on screen after
+ * notifications/cancelled, so the re-display carries a visible attempt counter instead of
+ * pretending the old widget is gone.
+ */
+exports.MAX_PRESENTATIONS = 2;
 // This module is PURE (no SDK import — the doctrine above), so the SDK's ErrorCode.RequestTimeout
 // lives here as a pinned constant; elicit-expiry.test.ts asserts parity against the real enum.
 const MCP_REQUEST_TIMEOUT_CODE = -32001;
@@ -38,9 +63,9 @@ const MCP_REQUEST_TIMEOUT_CODE = -32001;
  * `expired`; a message that merely SAYS "timed out", a near-miss code, or a code on a non-Error
  * is `silent`, because the expiry face carries friendlier guidance and must not be spoofable.
  */
-function classifyElicitError(e) {
+function classifyElicitError(e, timeoutMs = exports.ELICIT_TIMEOUT_MS) {
     return e instanceof Error && e.code === MCP_REQUEST_TIMEOUT_CODE
-        ? { kind: 'expired', waitedMs: exports.ELICIT_TIMEOUT_MS }
+        ? { kind: 'expired', waitedMs: timeoutMs }
         : { kind: 'silent' };
 }
 /**
@@ -51,32 +76,115 @@ function classifyElicitError(e) {
 function expiredNotice(waitedMs) {
     return `[세션 승인 다이얼로그 만료 — ${Math.round(waitedMs / 1000)}초 무응답] 요청은 승인 큐로 회송되었습니다. 결정: npx holmes-kit approve. `;
 }
+// FLATTEN attacker-influenced text (round-1): the model chooses spec titles and finding ids, and
+// interpolating them raw let a crafted title inject fake lines ("[시스템] … approve.") into the
+// ONE human-trust surface this feature introduces. Line structure is fixed by this template, never
+// by the data: newlines and control characters collapse to spaces, and each field is length-capped.
+const flat = (s, max) => s.replace(/[\u0000-\u001f\u007f\u0085\u2028\u2029\u200b-\u200f\u202a-\u202e\u2066-\u2069\ufeff]+/g, ' ')
+    .replace(/\s{2,}/g, ' ').trim().slice(0, max);
+// @implements A-SPEC-497.3
 /**
- * The question form. Decisions only (REQ-263 Out): the single free-text field is `reason`, and it
- * is subordinate to the decision — this channel never collects arbitrary input.
+ * Stage-1 form: the DECISION alone, so approving is one choice (S-497.3's 1-key promise). The
+ * reason field moved to stage 2 — it exists only after deny/question (decisions only, REQ-263 Out:
+ * this channel never collects arbitrary input). A re-presentation (attempt 2) leads with a
+ * template-owned counter line, so the human can tell the live dialog from the stale one their
+ * client left on screen (measured 2026-08-31: widgets survive notifications/cancelled).
  */
-function buildElicitRequest(req) {
-    // FLATTEN attacker-influenced text (round-1): the model chooses spec titles and finding ids, and
-    // interpolating them raw let a crafted title inject fake lines ("[시스템] … approve.") into the
-    // ONE human-trust surface this feature introduces. Line structure is fixed by this template, never
-    // by the data: newlines and control characters collapse to spaces, and each field is length-capped.
-    const flat = (s, max) => s.replace(/[\u0000-\u001f\u007f\u0085\u2028\u2029\u200b-\u200f\u202a-\u202e\u2066-\u2069\ufeff]+/g, ' ')
-        .replace(/\s{2,}/g, ' ').trim().slice(0, max);
+function buildDecisionForm(req, attempt, timeoutMs) {
+    const redisplay = attempt > 1 ? `⚠ 재표시 ${attempt}/${exports.MAX_PRESENTATIONS} — 이전 다이얼로그는 만료되어 무효입니다\n` : '';
     return {
         // @implements A-SPEC-497.1 — the forewarning is the LAST line and template-owned: it survives a
         // cap-filling summary (appended after the caps) and tells the human, before the clock runs out,
         // where an undecided request goes and where the decision still lives.
-        message: `[Holmes-Kit 승인 요청] ${flat(req.kind, 40)} — ${flat(req.target, 80)}\n${flat(req.summary, 200)}\n승인(approve) / 거부(deny) / 질문(question) 을 선택하세요. 사유는 선택입니다.\n⏱ ${exports.ELICIT_TIMEOUT_MS / 1000}초 내 미결정 시 승인 큐로 회송됩니다(운영자: npx holmes-kit approve).`,
+        message: `${redisplay}[Holmes-Kit 승인 요청] ${flat(req.kind, 40)} — ${flat(req.target, 80)}\n${flat(req.summary, 200)}\n승인(approve) / 거부(deny) / 질문(question) 을 선택하세요. 사유는 거부·질문을 고르면 이어서 묻습니다.\n⏱ ${timeoutMs / 1000}초 내 미결정 시 승인 큐로 회송됩니다(운영자: npx holmes-kit approve).`,
         requestedSchema: {
             type: 'object',
             properties: {
                 decision: { type: 'string', enum: ['approve', 'deny', 'question'], description: '승인/거부/질문' },
-                reason: { type: 'string', description: '사유(선택) — 거부·질문이면 에이전트 문면에 실립니다' },
             },
             required: ['decision'],
         },
     };
 }
+// @implements A-SPEC-497.3
+/**
+ * Stage-2 form: the reason alone, asked only after deny/question. A question without text is
+ * useless, so `reason` is required there; a deny stands on its own, so there it is optional.
+ */
+function buildReasonForm(decision, timeoutMs) {
+    const ask = decision === 'question'
+        ? '질문 내용을 입력하세요 — 에이전트 거부 문면에 실립니다.'
+        : '거부 사유를 입력하세요(선택) — 에이전트 거부 문면에 실립니다.';
+    return {
+        message: `[Holmes-Kit] ${ask}\n⏱ ${timeoutMs / 1000}초 내 미입력 시 결정은 그대로 확정됩니다.`,
+        requestedSchema: {
+            type: 'object',
+            properties: {
+                reason: { type: 'string', description: decision === 'question' ? '질문 내용' : '거부 사유(선택)' },
+            },
+            required: decision === 'question' ? ['reason'] : [],
+        },
+    };
+}
+// @implements A-SPEC-497.3
+/**
+ * The two-stage flow. Fates preserved exactly (H-SPEC-497 Interfaces): the return is the same
+ * discriminated union handlers already consume, so nothing above this seam changes. Only EXPIRY
+ * of stage 1 re-presents (once, lock-free kinds only); a stage-2 failure of ANY kind never erases
+ * the stage-1 decision — un-deciding a human is the one thing this channel must not do.
+ */
+async function runElicitFlow(raw, req) {
+    const timeoutMs = elicitTimeoutMsFor(req.kind);
+    const presentations = req.kind === 'review-resolve' ? 1 : exports.MAX_PRESENTATIONS;
+    let waitedMs = 0;
+    for (let attempt = 1; attempt <= presentations; attempt++) {
+        let r;
+        try {
+            r = await raw(buildDecisionForm(req, attempt, timeoutMs), timeoutMs);
+        }
+        catch (e) {
+            const fate = classifyElicitError(e, timeoutMs);
+            if (fate.kind !== 'expired')
+                return fate;
+            waitedMs += timeoutMs;
+            continue; // expiry — and ONLY expiry — earns a re-presentation
+        }
+        if (r && typeof r === 'object' && r.action === 'decline') {
+            return { kind: 'answered', decision: interpretElicitResult({ action: 'decline' }) };
+        }
+        const decision = stage1DecisionOf(r);
+        if (decision === null)
+            return { kind: 'silent' }; // cancel / malformed: no decision, no re-ask
+        if (decision === 'approve') {
+            return { kind: 'answered', decision: interpretElicitResult({ action: 'accept', content: { decision } }) };
+        }
+        // deny | question — collect the reason in stage 2, then map through the ONE interpreter so the
+        // refusal wording keeps a single source of truth.
+        const reason = await collectReason(raw, decision);
+        return { kind: 'answered', decision: interpretElicitResult({ action: 'accept', content: { decision, reason } }) };
+    }
+    return { kind: 'expired', waitedMs };
+}
+/** Stage-1 result → decision token, fail-closed: only accept + an in-enum string counts. */
+function stage1DecisionOf(r) {
+    if (!r || typeof r !== 'object' || r.action !== 'accept')
+        return null;
+    const d = r.content && typeof r.content === 'object' ? r.content.decision : undefined;
+    return d === 'approve' || d === 'deny' || d === 'question' ? d : null;
+}
+/** Stage-2 reason, or undefined on ANY failure — the stage-1 decision stands either way. */
+async function collectReason(raw, decision) {
+    try {
+        const r = await raw(buildReasonForm(decision, exports.ELICIT_TIMEOUT_MS), exports.ELICIT_TIMEOUT_MS);
+        if (!r || typeof r !== 'object' || r.action !== 'accept')
+            return undefined;
+        const reason = r.content && typeof r.content === 'object' ? r.content.reason : undefined;
+        return typeof reason === 'string' && reason.trim() !== '' ? reason : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Map a client's ElicitResult to a decision — FAIL-CLOSED: only the exact shape
  * `{action:'accept', content:{decision:'approve'}}` grants; every malformed shape (missing action,

package/dist/holmes/mcp/handlers.d.ts

@@ -272,6 +272,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
     }>;
     cpg_scan(a: {
         root: string;
+        lints?: boolean;
     }): Promise<{
         files: number;
         symbols: number;
@@ -280,6 +281,27 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
             reason: string;
         }[];
         skippedCount: number;
+    } | {
+        lints: {
+            dynamicRef: {
+                file: string;
+                name: string;
+                line: number;
+            }[];
+            asyncBlocking: {
+                file: string;
+                pattern: string;
+                line: number;
+            }[];
+            limits: string[];
+        };
+        files: number;
+        symbols: number;
+        skipped: {
+            file: string;
+            reason: string;
+        }[];
+        skippedCount: number;
     }>;
     /**
      * @implements A-SPEC-138

package/dist/holmes/mcp/handlers.js

@@ -131,6 +131,7 @@ const risk_classifier_1 = require("../guardrail/risk-classifier");
 const risk_gate_1 = require("../guardrail/risk-gate");
 const elicit_approval_1 = require("./elicit-approval");
 const anchor_comment_1 = require("../rtm/anchor-comment");
+const consistency_lints_1 = require("../cpg/consistency-lints");
 const approval_queue_1 = require("../governance/approval-queue");
 const approval_grants_1 = require("../governance/approval-grants");
 const spec_digest_1 = require("../spec/spec-digest");
@@ -1633,7 +1634,37 @@ function makeRawHandlers(store, opts) {
             // with casualties" by counts alone. Bounded listing (50), complete count.
             const { scanned, skipped } = cachedScanWithReport(root);
             const symbols = scanned.reduce((n, f) => n + f.symbols.length, 0);
-            return { files: scanned.length, symbols, skipped: skipped.slice(0, 50), skippedCount: skipped.length };
+            const base = { files: scanned.length, symbols, skipped: skipped.slice(0, 50), skippedCount: skipped.length };
+            if (!a.lints)
+                return base;
+            // @implements A-SPEC-506.1 — opt-in consistency lints (P-G/P-J field incidents): WARNING
+            // signals only, additive field only, Python only; the default path above is byte-identical.
+            const defined = new Set();
+            for (const f of scanned)
+                for (const s of f.symbols) {
+                    defined.add(s.name);
+                    const last = s.name.split('.').pop();
+                    if (last)
+                        defined.add(last);
+                }
+            const dynamicRef = [];
+            const asyncBlocking = [];
+            for (const f of scanned) {
+                if (!f.sourcePath.endsWith('.py'))
+                    continue;
+                let code;
+                try {
+                    code = fs.readFileSync(path.join(root, f.sourcePath), 'utf8');
+                }
+                catch {
+                    continue;
+                }
+                for (const hit of (0, consistency_lints_1.dynamicRefFindings)(code, defined))
+                    dynamicRef.push({ file: f.sourcePath, ...hit });
+                for (const hit of (0, consistency_lints_1.asyncBlockingFindings)(code))
+                    asyncBlocking.push({ file: f.sourcePath, ...hit });
+            }
+            return { ...base, lints: { dynamicRef, asyncBlocking, limits: [...consistency_lints_1.LINT_LIMITS] } };
         },
         /**
          * @implements A-SPEC-138

package/dist/holmes/mcp/server.js

@@ -18,17 +18,19 @@ const store = new spec_store_1.LocalMarkdownRepository(process.env.HOLMES_SPECS
 // failure — no capability, transport error, malformed answer — folds to `silent`, whose refusal
 // stays byte-identical to the pre-elicitation one. Diagnostics, if ever needed, go to stderr only
 // (stdout is the protocol channel).
-const { ELICIT_TIMEOUT_MS, buildElicitRequest, classifyElicitError, interpretElicitResult } = require('./elicit-approval');
+// @implements A-SPEC-497.3 — the wiring shrinks to ONE impure seam (rawElicit): the two-stage
+// form, the finite re-display and the per-path deadline all live in the pure runElicitFlow, so
+// every branch is test-driven without a client. runElicitFlow classifies its own errors; the outer
+// catch is a belt for faults outside the flow (capability probe, transport construction).
+const { runElicitFlow } = require('./elicit-approval');
 const elicit = async (req) => {
     try {
         if (!server.getClientCapabilities()?.elicitation)
             return { kind: 'silent' };
-        const r = await server.elicitInput(buildElicitRequest(req), { timeout: ELICIT_TIMEOUT_MS });
-        const d = interpretElicitResult(r);
-        return d === null ? { kind: 'silent' } : { kind: 'answered', decision: d };
+        return await runElicitFlow((form, timeoutMs) => server.elicitInput(form, { timeout: timeoutMs }), req);
     }
-    catch (e) {
-        return classifyElicitError(e);
+    catch {
+        return { kind: 'silent' };
     }
 };
 const handlers = (0, handlers_1.makeHandlers)(store, {

package/dist/holmes/mcp/tool-schemas.js

@@ -171,10 +171,10 @@ exports.TOOL_SCHEMAS = {
         },
     },
     cpg_scan: {
-        description: 'Scan the repository tree with tree-sitter across the 8 supported languages; returns { files, symbols } counts plus the skip report ({ skipped, skippedCount }) naming any claimed file the scan could not ingest — an empty report distinguishes a clean tree from one with casualties.',
+        description: 'Scan the repository tree with tree-sitter across the 8 supported languages; returns { files, symbols } counts plus the skip report ({ skipped, skippedCount }) naming any claimed file the scan could not ingest — an empty report distinguishes a clean tree from one with casualties. Pass lints:true to ALSO receive opt-in consistency WARNING signals (Python only, additive `lints` field with its own `limits`): dynamicRef (a literal getattr/hasattr name absent from the scanned symbol census) and asyncBlocking (a known-blocking call inside an async def, unwrapped on its line). Signals route a review; no gate consumes them.',
         inputSchema: {
             type: 'object',
-            properties: { root: ROOT },
+            properties: { root: ROOT, lints: { type: 'boolean', description: 'Include the consistency-lint warning signals (default false — the base result is unchanged without it).' } },
             required: ['root'],
         },
     },

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
   "main": "dist/holmes/mcp/server.js",
   "types": "dist/holmes/mcp/server.d.ts",