@holmes-lab/holmes-kit 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -4,6 +4,40 @@ 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.1] - 2026-08-31
+
+Approval-dialog expiry made visible (REQ-497 slice .1), plus the first Windows field validation.
+
+### Added
+
+- **Elicitation outcome taxonomy** (A-SPEC-497.1): the in-session approval channel now tells its
+  three fates apart — answered / expired / silent. An expired dialog (the MCP SDK's 120s
+  RequestTimeout, which previously died as an anonymous refusal while the client showed a dead,
+  orphaned dialog) now LEADS the refusal with what happened and where the decision still lives:
+  `[세션 승인 다이얼로그 만료 — 120초 무응답] 요청은 승인 큐로 회송되었습니다. 결정: npx holmes-kit approve`.
+  Applies to both elicitable paths (`spec_approve`, `review_record` critical lifts).
+- **Timeout forewarning in the dialog itself**: every approval dialog's message now ends with a
+  template-owned line announcing the 120s deadline and the queue fallback, so an expiry is never
+  a surprise. The line survives cap-filling summaries and control-character injection.
+- Windows field validation (user machine, PowerShell, node v24): registry install, doctor
+  11 PASS / 0 FAIL (natives incl. better-sqlite3 + 7 tree-sitter grammars, both gates, MCP
+  handshake 30 tools), interactive raw-mode init menu renders and confirms.
+
+### Unchanged by design
+
+- The silent fates (no capability, transport error, malformed answer, dismissed window) keep
+  their refusal byte-identical to the pre-elicitation text (A-SPEC-263.1's lossless degradation,
+  now pinned by a full-value comparison test). The timeout value and its rationale (ledger-lock
+  starvation, headless hangs) are untouched — only the message learned to speak.
+
+### Known (registered, not yet fixed)
+
+- REQ-498 (draft): init asks the harness menu BEFORE emitting known refusals (governed-without-
+  specs, --force-without-approval — two field reproductions); no doctor warning when a stale
+  global shim shadows the local version (measured: dual global roots on Windows); npx one-shot
+  onboarding undocumented.
+
 <!-- @implements A-SPEC-209 -->
 ## [0.3.0] - 2026-08-31
 

package/dist/.build-id

@@ -1 +1 @@
-503a295-mth8qak7
+9dd2f60-mthaxwnr

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

@@ -26,12 +26,42 @@ export interface ElicitApprovalRequest {
     /** Human-facing one-liner: what is being approved (id, title, sealed-or-not). */
     summary: string;
 }
-/** The human's decision. `null` from an elicitor means "the channel gave no answer — fall back". */
+/** The human's decision. `null` from interpretElicitResult means "no answer in this shape". */
 export interface ElicitDecision {
     granted: boolean;
     reason?: string;
 }
-export type Elicitor = (req: ElicitApprovalRequest) => Promise<ElicitDecision | null>;
+/**
+ * The three fates of an elicitation, told apart. The old `Elicitor` returned decision-or-null, and
+ * the wiring's `catch { return null }` erased the SDK's RequestTimeout — so an expired dialog (the
+ * human saw dead arrows) and an absent capability (the human saw nothing at all) wore the same
+ * refusal. Only `expired` earns a name in the message; `silent` stays byte-identical to the
+ * pre-elicitation refusal (A-SPEC-263.1's lossless-degradation promise, kept).
+ */
+export type ElicitOutcome = {
+    kind: 'answered';
+    decision: ElicitDecision;
+} | {
+    kind: 'expired';
+    waitedMs: number;
+} | {
+    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. */
+export declare const ELICIT_TIMEOUT_MS = 120000;
+/**
+ * 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;
+/**
+ * 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.

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

@@ -1,7 +1,9 @@
 "use strict";
 // @implements A-SPEC-263.1
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ELICITABLE_KINDS = void 0;
+exports.ELICIT_TIMEOUT_MS = exports.ELICITABLE_KINDS = void 0;
+exports.classifyElicitError = classifyElicitError;
+exports.expiredNotice = expiredNotice;
 exports.buildElicitRequest = buildElicitRequest;
 exports.interpretElicitResult = interpretElicitResult;
 /**
@@ -26,6 +28,29 @@ 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. */
+exports.ELICIT_TIMEOUT_MS = 120_000;
+// 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;
+/**
+ * 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.
+ */
+function classifyElicitError(e) {
+    return e instanceof Error && e.code === MCP_REQUEST_TIMEOUT_CODE
+        ? { kind: 'expired', waitedMs: exports.ELICIT_TIMEOUT_MS }
+        : { kind: 'silent' };
+}
+/**
+ * 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.
+ */
+function expiredNotice(waitedMs) {
+    return `[세션 승인 다이얼로그 만료 — ${Math.round(waitedMs / 1000)}초 무응답] 요청은 승인 큐로 회송되었습니다. 결정: npx holmes-kit approve. `;
+}
 /**
  * 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.
@@ -38,7 +63,10 @@ function buildElicitRequest(req) {
     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);
     return {
-        message: `[Holmes-Kit 승인 요청] ${flat(req.kind, 40)} — ${flat(req.target, 80)}\n${flat(req.summary, 200)}\n승인(approve) / 거부(deny) / 질문(question) 을 선택하세요. 사유는 선택입니다.`,
+        // @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).`,
         requestedSchema: {
             type: 'object',
             properties: {

package/dist/holmes/mcp/handlers.js

@@ -643,18 +643,20 @@ function makeRawHandlers(store, opts) {
     // @implements A-SPEC-263.1
     // The in-session approval channel: ask ONLY when (a) an elicitor was injected (the server wires
     // one iff the client advertised the elicitation capability — handlers never see the server), and
-    // (b) the kind is in the conservative allow-list. Every failure mode (throw, timeout folded to
-    // null by the wiring, malformed answers folded to null by interpretElicitResult) returns null,
-    // which callers treat as "the channel gave no answer" — the refusal that follows is byte-identical
-    // to the pre-elicitation one, so nothing is ever worse than before the channel existed.
+    // (b) the kind is in the conservative allow-list.
+    // @implements A-SPEC-497.1 — the outcome taxonomy rides through unchanged: `answered` carries the
+    // human's decision, `expired` carries the timeout so the refusal can say a dialog died, and every
+    // other failure mode (no channel, wrong kind, a throwing elicitor) is `silent`, whose refusal
+    // stays byte-identical to the pre-elicitation one — nothing is ever worse than before the
+    // channel existed.
     const tryElicit = async (kind, target, summary) => {
         if (!opts?.elicit || !elicit_approval_1.ELICITABLE_KINDS.has(kind))
-            return null;
+            return { kind: 'silent' };
         try {
             return await opts.elicit({ kind, target, summary });
         }
         catch {
-            return null;
+            return { kind: 'silent' };
         }
     };
     // A granted answer becomes a synthesized Approval that rides the EXISTING seal path unchanged —
@@ -1126,6 +1128,7 @@ function makeRawHandlers(store, opts) {
             // @implements A-SPEC-263.1 — asked ONLY after the existing channels failed to cover (an open
             // door never summons a human), and only about a spec that exists (a question about a missing
             // id helps no one — the standard refusal handles it).
+            let elicitExpiredMs;
             if (approveResolved === undefined) {
                 const target = await store.read(a.id).catch(() => null);
                 if (target) {
@@ -1133,20 +1136,27 @@ function makeRawHandlers(store, opts) {
                     // The MODEL text is capped BEFORE the server markers are appended (round-2): a ~185+ char
                     // title pushed '(재봉인)' past the dialog's 200-char summary cap, dressing a re-seal (the
                     // more consequential act) as a first approval. The cap cuts the title, never the marker.
-                    const d = await tryElicit('spec-approve', a.id, `${a.id} — ${target.spec.title.slice(0, 120)}${resealing ? ' (재봉인)' : ''}`);
-                    if (d?.granted) {
-                        approveResolved = { approval: elicitApproval(d.reason), source: 'elicitation' };
+                    const out = await tryElicit('spec-approve', a.id, `${a.id} — ${target.spec.title.slice(0, 120)}${resealing ? ' (재봉인)' : ''}`);
+                    if (out.kind === 'answered' && out.decision.granted) {
+                        approveResolved = { approval: elicitApproval(out.decision.reason), source: 'elicitation' };
                     }
-                    else if (d) {
+                    else if (out.kind === 'answered') {
                         // The human ANSWERED (deny/question/decline): the answer is the message, and no queue
                         // entry is filed — a decided request is not a pending one (REQ-246 visibility).
-                        return { ok: false, reason: `spec_approve: 세션에서 거부됨 — ${d.reason ?? '(사유 없음)'}. 사유를 해소한 뒤 다시 시도하십시오.` };
+                        return { ok: false, reason: `spec_approve: 세션에서 거부됨 — ${out.decision.reason ?? '(사유 없음)'}. 사유를 해소한 뒤 다시 시도하십시오.` };
+                    }
+                    else if (out.kind === 'expired') {
+                        // @implements A-SPEC-497.1 — only the expiry earns a name: the notice LEADS the same
+                        // fail-closed refusal + queue path, so the semantics stay refusal+queue and only the
+                        // message learned to say what happened.
+                        elicitExpiredMs = out.waitedMs;
                     }
-                    // d === null: the channel gave no answer — fall through to the byte-identical refusal.
+                    // silent: the channel gave no answer — fall through to the byte-identical refusal.
                 }
             }
             if (approveResolved === undefined) {
-                return { ok: false, reason: 'spec_approve requires an out-of-band HOLMES_APPROVAL that COVERS this act — a request-payload approval is not a channel, and an expired or elsewhere-scoped token does not open this door (scoped approvals need kind "spec-approve"). (fail-closed)'
+                return { ok: false, reason: (elicitExpiredMs !== undefined ? (0, elicit_approval_1.expiredNotice)(elicitExpiredMs) : '')
+                        + 'spec_approve requires an out-of-band HOLMES_APPROVAL that COVERS this act — a request-payload approval is not a channel, and an expired or elsewhere-scoped token does not open this door (scoped approvals need kind "spec-approve"). (fail-closed)'
                         + refusalQueueHint(a.root, store, { kind: 'spec-approve', target: a.id, why: '스펙 봉인 승인' }) };
             }
             // @implements A-SPEC-188 — destination BEFORE seal.
@@ -2228,6 +2238,10 @@ function makeRawHandlers(store, opts) {
             // the human's "no" must not abort a batch that never needed the question. The deny bites only
             // at the in-lock site, and only if the lift is ACTUALLY needed there.
             const elicitDenials = new Map();
+            // @implements A-SPEC-497.1 — an expiry is carried as data like a denial: it bites only at the
+            // in-lock refusal site, where it prefixes the standard message so the agent can tell the user
+            // a session dialog died (instead of the anonymous "no approval" the old null-fold produced).
+            const elicitExpiries = new Map();
             if (opts?.elicit) {
                 try {
                     const snapshot = new Map();
@@ -2247,11 +2261,13 @@ function makeRawHandlers(store, opts) {
                         }
                         if (resolveHandlerApproval(a.root, store, env0, { kind: 'review-resolve', target: f.id }, new Date().toISOString()) !== undefined)
                             continue; // an open door never summons a human
-                        const d = await tryElicit('review-resolve', f.id, `열린 치명 발견 ${f.id} 의 해소 기록`);
-                        if (d?.granted)
-                            elicitGrants.set(f.id, elicitApproval(d.reason));
-                        else if (d)
-                            elicitDenials.set(f.id, d.reason ?? '(사유 없음)');
+                        const out = await tryElicit('review-resolve', f.id, `열린 치명 발견 ${f.id} 의 해소 기록`);
+                        if (out.kind === 'answered' && out.decision.granted)
+                            elicitGrants.set(f.id, elicitApproval(out.decision.reason));
+                        else if (out.kind === 'answered')
+                            elicitDenials.set(f.id, out.decision.reason ?? '(사유 없음)');
+                        else if (out.kind === 'expired')
+                            elicitExpiries.set(f.id, out.waitedMs);
                     }
                 }
                 catch {
@@ -2325,7 +2341,11 @@ function makeRawHandlers(store, opts) {
                             if (denied !== undefined) {
                                 throw new HandlerRefusal(`review_record: 세션에서 거부됨 — ${denied}. 사유를 해소한 뒤 다시 기록하십시오.`);
                             }
-                            throw new HandlerRefusal(`review_record: id ${f.id} 의 열린 치명 발견을 해소하는 기록은 이 행위를 덮는 유효한 대역외 승인이 필요합니다 — 차단당한 쪽이 스스로 이빨을 뽑을 수 없어야 하고, 만료·다른 범위의 승인은 덮지 않습니다. HOLMES_APPROVAL='{"actor":"<you>","token":"<any>","rationale":"<why fixed>"}' (범위를 쓰면 kind "review-resolve") 를 서버 환경에 설정하고 다시 기록하십시오`
+                            // @implements A-SPEC-497.1 — an expired dialog leads the refusal by name; silence
+                            // keeps the pre-elicitation face.
+                            const expiredMs = elicitExpiries.get(f.id);
+                            throw new HandlerRefusal((expiredMs !== undefined ? (0, elicit_approval_1.expiredNotice)(expiredMs) : '')
+                                + `review_record: id ${f.id} 의 열린 치명 발견을 해소하는 기록은 이 행위를 덮는 유효한 대역외 승인이 필요합니다 — 차단당한 쪽이 스스로 이빨을 뽑을 수 없어야 하고, 만료·다른 범위의 승인은 덮지 않습니다. HOLMES_APPROVAL='{"actor":"<you>","token":"<any>","rationale":"<why fixed>"}' (범위를 쓰면 kind "review-resolve") 를 서버 환경에 설정하고 다시 기록하십시오`
                                 + refusalQueueHint(a.root, store, { kind: 'review-resolve', target: f.id, why: '열린 치명 발견의 해소 기록' }));
                         }
                         // Grant-file consumption is DEFERRED past the loop (round-2): consuming here burned the

package/dist/holmes/mcp/server.js

@@ -12,20 +12,23 @@ const validate_args_1 = require("./validate-args");
 // @implements A-SPEC-100.2
 const store = new spec_store_1.LocalMarkdownRepository(process.env.HOLMES_SPECS ?? '.ax/specs');
 // @implements A-SPEC-263.1 — the elicitation approval channel's wiring. The capability arrives at
-// initialize, AFTER this factory runs, so it is consulted lazily at CALL time: no capability (or
-// any transport error/timeout) folds to null, which the handlers treat as "the channel gave no
-// answer" — the refusal that follows is byte-identical to the pre-elicitation one. Diagnostics, if
-// ever needed, go to stderr only (stdout is the protocol channel).
-const { buildElicitRequest, interpretElicitResult } = require('./elicit-approval');
+// initialize, AFTER this factory runs, so it is consulted lazily at CALL time.
+// @implements A-SPEC-497.1 — the three fates, told apart at THIS seam (the only place the SDK error
+// is visible): a RequestTimeout rejection is `expired` and earns a name in the refusal; every other
+// 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');
 const elicit = async (req) => {
     try {
         if (!server.getClientCapabilities()?.elicitation)
-            return null;
-        const r = await server.elicitInput(buildElicitRequest(req), { timeout: 120_000 });
-        return interpretElicitResult(r);
+            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 };
     }
-    catch {
-        return null;
+    catch (e) {
+        return classifyElicitError(e);
     }
 };
 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.0",
+  "version": "0.3.1",
   "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",