@holmes-lab/holmes-kit 0.3.7 → 0.3.9

package/dist/holmes/governance/push-gate.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PUSH_HOOK_SIGNATURE = void 0;
+exports.judgePush = judgePush;
+exports.parsePushLines = parsePushLines;
+/** Identifies OUR installed hook — the single truth doctor and re-install both key on. */
+exports.PUSH_HOOK_SIGNATURE = 'HOLMES-KIT PUSH GATE v1';
+/** Prose that CLAIMS a test success — a surfacing pattern, never a judgment input. */
+const SUCCESS_CLAIM_RE = /초록|green|pass(es|ed)?\b|✅/i;
+// @implements A-SPEC-509.1
+function judgePush(input) {
+    if (!input.hasGovernance)
+        return { allow: true, notices: [] }; // un-adopted: never coerce adoption
+    const notices = [];
+    const ev = input.evidence;
+    // Claim cross-check first — it rides allow AND deny alike.
+    for (const c of input.claimCommits) {
+        if (!SUCCESS_CLAIM_RE.test(c.subject))
+            continue;
+        if (ev && ev.head === c.sha)
+            continue; // the ledger backs this claim
+        notices.push(`[Holmes-Kit] 커밋 ${c.sha.slice(0, 7)}의 메시지가 테스트 성공을 주장하지만 test_run 원장이 그 커밋을 뒷받침하지 않습니다: "${flatSubject(c.subject)}"`);
+    }
+    if (!ev) {
+        // Adopted but no ledger yet: pass honestly, say how to activate. A broken ledger folds here
+        // too — the gate is a default-safener, not a security boundary, so it must not dead-lock a
+        // repo whose ledger file was corrupted.
+        notices.push('[Holmes-Kit] test-evidence 원장이 없어 push 증빙 대조를 건너뜁니다 — test_run을 실행하면 다음 push부터 대조가 활성화됩니다');
+        return { allow: true, notices };
+    }
+    const executed = Object.values(ev.executedByAspec).reduce((a, b) => a + b, 0);
+    if (ev.head === input.pushedHead && ev.passed === true && executed > 0) {
+        return { allow: true, notices };
+    }
+    const why = ev.head !== input.pushedHead
+        ? `원장 head ${ev.head.slice(0, 7)} ≠ push head ${input.pushedHead.slice(0, 7)} — 증빙 이후 커밋이 있습니다`
+        : ev.passed !== true
+            ? `원장이 붉은 실행(passed: false)입니다 — 붉은 스위트는 기준선이 될 수 없습니다`
+            : `원장이 아무것도 실행하지 않았습니다(executed 0) — no-op 초록은 증빙이 아닙니다`;
+    return {
+        allow: false,
+        reason: `[Holmes-Kit push 게이트] ${why}. 복구: 현재 HEAD에서 test_run(또는 전체 스위트)을 초록으로 실행해 원장을 갱신한 뒤 다시 push하십시오. 의도적 우회는 git push --no-verify.`,
+        notices,
+    };
+}
+/** One control-character-free line of a commit subject for interpolation into gate text. */
+function flatSubject(s) {
+    return s.replace(/[\u0000-\u001f\u007f]+/g, ' ').replace(/\s{2,}/g, ' ').trim().slice(0, 80);
+}
+/**
+ * The pre-push stdin format: `<local ref> <local sha> <remote ref> <remote sha>` per line.
+ * A deletion push (all-zero local sha) deletes a remote ref — there is nothing to vouch for.
+ */
+function parsePushLines(stdinText) {
+    const out = [];
+    for (const line of stdinText.split('\n')) {
+        const parts = line.trim().split(/\s+/);
+        if (parts.length !== 4)
+            continue;
+        const [, localSha, , remoteSha] = parts;
+        if (!/^[0-9a-f]{40}$/.test(localSha))
+            continue;
+        if (/^0{40}$/.test(localSha))
+            continue; // deletion: not judged
+        out.push({ localSha, remoteSha });
+    }
+    return out;
+}

package/dist/holmes/guardrail/scope-judgment.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The de-amplified scope judgment — PURE (no fs, no git; the hook gathers, this decides).
+ *
+ * Field basis (2026-08-23, jarvis): one test-class addition to an ALREADY-ANCHORED file cost
+ * >=3 human interventions, because the old model re-checked Files-to-Touch on every edit of an
+ * anchored file (double registration: the anchor said "this file belongs to X" and FtT had to
+ * say it again), while its matcher quietly widened every FILE token to the file's whole parent
+ * directory (`src/a/x.ts` covered all of `src/a/`). Both directions were amplification.
+ *
+ * The model here splits TENURE from ADMISSION:
+ *  - TENURE: a file already anchored ON DISK is in its specs' scope — editing it is free. The
+ *    entitlement comes from the fact that the file passed admission when it first joined (gated
+ *    writes are the only way anchors legitimately reach disk), or was deliberately grandfathered
+ *    at adoption (REQ-508's explicit acceptance of the 252-file reality).
+ *  - ADMISSION: joining a file to a spec — a new file's payload anchors, or a re-anchor bringing
+ *    an id the disk does not carry — must pass a gate: an FtT glob match, or the test-file
+ *    dispensation (coverage growth is what ART-4 ASKS for), or the caller's out-of-band
+ *    code-write approval (judged by the hook, not here).
+ *
+ * Anchor DELETION never blocks (un-anchoring may be legitimate refactoring) but is surfaced as
+ * a warning — silent RTM loss is the failure mode C12 taught us to fear.
+ */
+/** Repo test conventions — the single census every dispensation consumer shares. */
+export declare function isTestPath(relPath: string): boolean;
+/**
+ * One FtT token against one repo-relative path. `**` crosses separators, `*` does not; a literal
+ * token with an extension names EXACTLY that file (the parent-directory widening is gone); a
+ * literal directory token covers its subtree. The regex build is linear — each glob char maps to
+ * one bounded fragment, so no ReDoS surface.
+ */
+export declare function matchesFtt(token: string, relPath: string): boolean;
+/** Concrete path-like tokens of a Files-to-Touch section (globs included) — prose yields none. */
+export declare function fttPathTokens(fttText: string): string[];
+export interface ScopeInput {
+    relPath: string;
+    isNewFile: boolean;
+    /** All @implements A-SPEC ids found ON DISK (string-literal-stripped) — the full set, not the first. */
+    diskAnchorIds: string[];
+    /** All A-SPEC ids the write payload carries (content / new_string, stripped). */
+    payloadAnchorIds: string[];
+    approvedIds: ReadonlySet<string>;
+    fttTokensOf: (id: string) => string[];
+    /** Disk anchors this edit deliberately removes (hook-computed: anchors(old)−anchors(new)). */
+    removedAnchorIds?: string[];
+}
+export interface ScopeVerdict {
+    decision: 'in-scope' | 'admission-required';
+    failedAdmissions: Array<{
+        id: string;
+        reason: string;
+    }>;
+    warnings: string[];
+}
+export declare function judgeScope(input: ScopeInput): ScopeVerdict;

package/dist/holmes/guardrail/scope-judgment.js

@@ -0,0 +1,106 @@
+"use strict";
+// @implements A-SPEC-508.1
+/**
+ * The de-amplified scope judgment — PURE (no fs, no git; the hook gathers, this decides).
+ *
+ * Field basis (2026-08-23, jarvis): one test-class addition to an ALREADY-ANCHORED file cost
+ * >=3 human interventions, because the old model re-checked Files-to-Touch on every edit of an
+ * anchored file (double registration: the anchor said "this file belongs to X" and FtT had to
+ * say it again), while its matcher quietly widened every FILE token to the file's whole parent
+ * directory (`src/a/x.ts` covered all of `src/a/`). Both directions were amplification.
+ *
+ * The model here splits TENURE from ADMISSION:
+ *  - TENURE: a file already anchored ON DISK is in its specs' scope — editing it is free. The
+ *    entitlement comes from the fact that the file passed admission when it first joined (gated
+ *    writes are the only way anchors legitimately reach disk), or was deliberately grandfathered
+ *    at adoption (REQ-508's explicit acceptance of the 252-file reality).
+ *  - ADMISSION: joining a file to a spec — a new file's payload anchors, or a re-anchor bringing
+ *    an id the disk does not carry — must pass a gate: an FtT glob match, or the test-file
+ *    dispensation (coverage growth is what ART-4 ASKS for), or the caller's out-of-band
+ *    code-write approval (judged by the hook, not here).
+ *
+ * Anchor DELETION never blocks (un-anchoring may be legitimate refactoring) but is surfaced as
+ * a warning — silent RTM loss is the failure mode C12 taught us to fear.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTestPath = isTestPath;
+exports.matchesFtt = matchesFtt;
+exports.fttPathTokens = fttPathTokens;
+exports.judgeScope = judgeScope;
+/** Repo test conventions — the single census every dispensation consumer shares. */
+function isTestPath(relPath) {
+    const base = relPath.split('/').at(-1) ?? '';
+    if (/\.(test|spec)\.[^.]+$/.test(base))
+        return true; // x.test.ts / x.spec.tsx
+    if (/^test_[^/]*\.py$/.test(base))
+        return true; // pytest collection default
+    if (/_test\.(py|go)$/.test(base))
+        return true; // pytest alt / go test
+    const segs = relPath.split('/').slice(0, -1);
+    return segs.some((s) => s === 'tests' || s === '__tests__' || s === 'test');
+}
+/**
+ * One FtT token against one repo-relative path. `**` crosses separators, `*` does not; a literal
+ * token with an extension names EXACTLY that file (the parent-directory widening is gone); a
+ * literal directory token covers its subtree. The regex build is linear — each glob char maps to
+ * one bounded fragment, so no ReDoS surface.
+ */
+function matchesFtt(token, relPath) {
+    const tok = token.replace(/\/+$/, '');
+    if (tok === '')
+        return false;
+    if (tok.includes('*')) {
+        const rx = tok.split(/(\*\*|\*)/).map((part) => {
+            if (part === '**')
+                return '.*';
+            if (part === '*')
+                return '[^/]*';
+            return part.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+        }).join('');
+        return new RegExp(`^${rx}$`).test(relPath);
+    }
+    if (/\.[A-Za-z0-9]+$/.test(tok))
+        return relPath === tok; // file literal: that file only
+    return relPath === tok || relPath.startsWith(tok + '/'); // dir literal: its subtree
+}
+/** Concrete path-like tokens of a Files-to-Touch section (globs included) — prose yields none. */
+function fttPathTokens(fttText) {
+    return fttText.match(/[\w@.*-]+(?:\/[\w@.*-]+)+/g) ?? [];
+}
+// @implements A-SPEC-508.1
+function judgeScope(input) {
+    const disk = new Set(input.diskAnchorIds);
+    const warnings = (input.removedAnchorIds ?? [])
+        .filter((id) => disk.has(id))
+        .map((id) => `이 편집은 ${id} 앵커를 제거합니다 — RTM 추적 연결이 끊깁니다(커버리지·그래프·게이트가 이 파일을 더는 ${id}에 귀속시키지 않음). 의도한 재구성이면 진행하고, 아니면 앵커를 보존하십시오`);
+    // NEW CLAIMS are the only thing admission ever judges: a new file's anchors, or a re-anchor
+    // bringing an id the disk does not carry. An existing file that claims nothing new is in scope
+    // by tenure — including the vacuous cases (no anchors at all, draft-only anchors): the gates
+    // that own those questions (No-Spec-No-Code, stale-seal) run on their own lanes.
+    const newClaims = input.payloadAnchorIds.filter((id) => !disk.has(id));
+    if (!input.isNewFile && newClaims.length === 0) {
+        return { decision: 'in-scope', failedAdmissions: [], warnings };
+    }
+    const claims = input.isNewFile ? input.payloadAnchorIds : newClaims;
+    const failedAdmissions = [];
+    for (const id of claims) {
+        const tokens = input.fttTokensOf(id);
+        if (tokens.length === 0)
+            continue; // prose-only imposes nothing
+        if (tokens.some((t) => matchesFtt(t, input.relPath)))
+            continue; // FtT glob admits
+        if (isTestPath(input.relPath) && input.approvedIds.has(id))
+            continue; // coverage dispensation
+        failedAdmissions.push({
+            id,
+            reason: input.isNewFile
+                ? `${id}의 'Files to Touch' 밖이고 테스트 특례에도 해당하지 않습니다`
+                : `재앵커(이관): ${id}는 이 파일의 디스크 앵커가 아니며, 'Files to Touch' 관문과 테스트 특례 모두 통과하지 못했습니다`,
+        });
+    }
+    return {
+        decision: failedAdmissions.length > 0 ? 'admission-required' : 'in-scope',
+        failedAdmissions,
+        warnings,
+    };
+}

package/dist/holmes/hooks/pre-tool-use.d.ts

@@ -138,6 +138,7 @@ export declare function evaluateHook(input: {
         file_path?: string;
         notebook_path?: string;
         content?: string;
+        old_string?: string;
         new_string?: string;
         command?: string;
     };

package/dist/holmes/hooks/pre-tool-use.js

@@ -1218,11 +1218,10 @@ function evaluateHook(input, specsDir, opts) {
     const payloadAnchor = ANCHOR_RE.exec([input.tool_input.content ?? '', input.tool_input.new_string ?? ''].join('\n'));
     const diskAnchor = ANCHOR_RE.exec(onDiskContent);
     const m = diskAnchor ?? payloadAnchor;
-    // RE-ANCHORING must be scope-checked against the NEW spec (review C6: on-disk precedence meant an
-    // edit that rewrites the anchor line was judged under the OLD spec, so a file could be re-attributed
-    // to any spec without that spec's Files-to-Touch ever being consulted — which then mis-credits
-    // coverage evidence). Both the current and the incoming anchor must accept the path.
-    const anchorsToScope = [m?.[1], payloadAnchor?.[1] !== m?.[1] ? payloadAnchor?.[1] : undefined].filter(Boolean);
+    // RE-ANCHORING scope (review C6) moved into judgeScope below (S-508.1): every payload anchor the
+    // disk does not carry is an ADMISSION, judged against the incoming spec's gate — the C6 property
+    // (a rewrite of the anchor line is judged under the NEW spec) is preserved there, now for the
+    // FULL anchor set instead of the first match.
     // @implements A-SPEC-132
     // Stale-aware gate (rev.1): a target A-SPEC whose seal is PRESENT and BROKEN (edited after
     // approval) or STALE (a parent moved) is not a trustworthy approval, so code must not be written
@@ -1307,33 +1306,46 @@ function evaluateHook(input, specsDir, opts) {
                 + (lost ? `\n${governance_history_1.GOVERNANCE_LOST_HINT}` : ''),
         };
     }
-    // Marker self-attestation mitigation: an @implements anchor is a claim the writer makes. When the
-    // anchored A-SPEC's `Files to Touch` names CONCRETE paths, the file must fall under one of them —
-    // so anchoring evil.ts (or an unrelated edit) to a random approved spec fails when that spec scoped
-    // its files. Applies to EVERY governed code Write/Edit, not just new files: the earlier new-file-only
-    // scoping left "create it some other way, then edit freely" open, and a stale anchor blessed
-    // unrelated edits forever. The legitimate flow is to extend the spec's Files-to-Touch FIRST
-    // (editing an approved spec's sections is allowed; only the approval transition is gated).
-    // Still bounded: only when concrete paths are listed (a prose/TODO section imposes nothing), and a
-    // valid out-of-band approval overrides. Verified 0/93 violations across this repo's anchored files.
-    for (const anchorId of anchorsToScope) {
-        const aspec = specs.find((s) => s.id === anchorId);
-        const ftt = aspec?.sections['Files to Touch'] ?? '';
-        const listed = ftt.match(/[\w@.-]+(?:\/[\w@.*-]+)+/g) ?? []; // concrete path-like tokens only
-        if (listed.length === 0)
-            continue; // prose-only section imposes nothing
-        const rel = relPath;
-        const covered = listed.some((t) => {
-            const tok = t.replace(/\/?\*+$/, ''); // dir/** -> dir
-            const dir = /\.[A-Za-z0-9]+$/.test(tok) ? tok.replace(/\/[^/]*$/, '') : tok; // file -> its dir
-            return rel === tok || rel.startsWith(tok + '/') || rel.startsWith(dir + '/');
-        });
-        if (!covered && !codeWriteCovered) { // @implements A-SPEC-133 — same code-write coverage as the stale gate
-            return {
-                permissionDecision: 'deny',
-                permissionDecisionReason: `[Holmes-Kit] ${rel} is anchored to ${anchorId} but falls outside its 'Files to Touch' scope — extend that section first (spec edit is allowed) or supply out-of-band approval`,
-            };
-        }
+    // @implements A-SPEC-508.1
+    // De-amplified scope: TENURE vs ADMISSION (S-508.1 replaced the per-edit FtT re-check that made
+    // one test-class addition cost >=3 human interventions, and the file-token→parent-directory
+    // widening that quietly covered whole sibling trees). A file already anchored on disk is in its
+    // specs' scope — editing it is free and silent. Only NEW CLAIMS (a new file's anchors, or a
+    // re-anchor bringing an id the disk does not carry) pass admission: FtT glob, or the test-file
+    // dispensation (ART-4 asks for coverage — the gate must not refuse it), or the out-of-band
+    // code-write approval. Anchor deletion never blocks but rides the allow as a warning — silent
+    // RTM loss is the C12 failure mode, made audible.
+    const { judgeScope, fttPathTokens: fttTokens } = require('../guardrail/scope-judgment');
+    const { anchorSpecIds, stripStringLiterals } = require('../rtm/anchor-ids');
+    const oldStr = input.tool_input.old_string ?? '';
+    const newPayload = [input.tool_input.content ?? '', input.tool_input.new_string ?? ''].join('\n');
+    // Deletion intent: a WRITE replaces the whole file, so disk→content is the comparison; an EDIT
+    // only proves a deletion when its old_string carried the anchor (a fragment NOT containing an
+    // anchor says nothing about it — no evidence, no warning). Discriminate by TOOL NAME, not by
+    // which payload fields exist: the antigravity adapter aliases `content` alongside `new_string`
+    // for its fragment-replace tool, and field-based detection read that as a whole-file wipe of
+    // every disk anchor (14 false warnings, caught by the A-SPEC-338 spawn-parity pin).
+    const isWholeFileWrite = input.tool_name.toLowerCase() === 'write';
+    const beforeIds = anchorSpecIds(stripStringLiterals(isWholeFileWrite ? onDiskContent : oldStr));
+    const afterIds = new Set(anchorSpecIds(stripStringLiterals(newPayload)));
+    const scopeVerdict = judgeScope({
+        relPath,
+        isNewFile: onDiskContent === '' && !fs.existsSync(p),
+        diskAnchorIds: anchorSpecIds(stripStringLiterals(onDiskContent)),
+        payloadAnchorIds: anchorSpecIds(stripStringLiterals(newPayload)),
+        approvedIds: new Set(specs.filter((s) => s.status === 'approved').map((s) => s.id)),
+        fttTokensOf: (id) => fttTokens(specs.find((s) => s.id === id)?.sections['Files to Touch'] ?? ''),
+        removedAnchorIds: beforeIds.filter((id) => !afterIds.has(id)),
+    });
+    const scopeWarnings = scopeVerdict.warnings.map((w) => `[Holmes-Kit] ${w}`).join('\n');
+    if (scopeVerdict.decision === 'admission-required' && !codeWriteCovered) { // @implements A-SPEC-133 — same code-write coverage as the stale gate
+        const failed = scopeVerdict.failedAdmissions
+            .map((f) => `${relPath} is anchored to ${f.id} but falls outside its 'Files to Touch' scope (${f.reason})`).join('; ');
+        return {
+            permissionDecision: 'deny',
+            permissionDecisionReason: `[Holmes-Kit] ${failed} — extend that section first (spec edit is allowed), add it as a test under the anchored spec, or supply out-of-band approval`
+                + (scopeWarnings ? `\n${scopeWarnings}` : ''),
+        };
     }
     // @implements A-SPEC-278
     // Pre-edit impact evidence, deliberately the LAST gate on this path.
@@ -1361,9 +1373,19 @@ function evaluateHook(input, specsDir, opts) {
             declaredDigest: process.env.HOLMES_EVIDENCE?.trim() || null,
             currentHead: evidenceHead,
         });
-        if (evidenceDecision)
+        if (evidenceDecision) {
+            // @implements A-SPEC-508.1 — an allow-with-reason from the evidence gate must not swallow
+            // the anchor-deletion warning: both ride the same reason field, newline-joined.
+            if (scopeWarnings && evidenceDecision.permissionDecision === 'allow') {
+                return { ...evidenceDecision, permissionDecisionReason: [evidenceDecision.permissionDecisionReason, scopeWarnings].filter(Boolean).join('\n') };
+            }
             return evidenceDecision;
+        }
     }
+    // @implements A-SPEC-508.1 — anchor-deletion warnings ride the allow (allow-with-reason, the
+    // same channel A-SPEC-278 uses): the write proceeds, but the RTM loss is on the record.
+    if (scopeWarnings)
+        return { permissionDecision: 'allow', permissionDecisionReason: scopeWarnings };
     return { permissionDecision: 'allow' };
 }
 // Synchronous spec loader for hook context (fail-open: directory read errors are skipped)

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,