@holmes-lab/holmes-kit 0.3.7 → 0.3.8

package/CHANGELOG.md

@@ -4,6 +4,37 @@ 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
 

package/dist/.build-id

@@ -1 +1 @@
-eb3164c-mthu5jwj
+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/index.js

@@ -814,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')
@@ -832,7 +842,8 @@ async function main(argv) {
             }
             finally {
                 process.removeListener('SIGINT', onSig);
-                rl.close();
+                stdin.setRawMode?.(false);
+                stdin.pause();
             }
             return 0;
         }

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/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/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/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.3.7",
+  "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",