@holmes-lab/holmes-kit 0.1.18 → 0.2.1

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

@@ -0,0 +1,79 @@
+"use strict";
+// @implements A-SPEC-263.1
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ELICITABLE_KINDS = void 0;
+exports.buildElicitRequest = buildElicitRequest;
+exports.interpretElicitResult = interpretElicitResult;
+/**
+ * The decision comes INTO the session (REQ-263): an approval-shaped refusal (spec_approve without a
+ * covering HOLMES_APPROVAL) becomes an in-session question when the client advertises the MCP
+ * elicitation capability — the human answers at the point of decision, on the screen they are
+ * already looking at, and the tool call completes in place. No capability, an error, a timeout, or
+ * a dismissed window all degrade LOSSLESSLY to the current refusal + queue hint.
+ *
+ * TRUST MODEL (H-SPEC-263): an elicitation response is produced by the harness UI from a human —
+ * the model cannot forge it through tool arguments (the request travels server→client, off the tool
+ * surface). But the trust boundary sits at the harness, closer than the out-of-band env/grant
+ * channels an operator injects from a shell. Hence: (a) the kind allow-list below is conservative —
+ * soft-governance approvals only, hard-hitl (nonce-opened shell/config-write) stays out and
+ * widening it is a spec revision; (b) every grant is ledgered under an `elicitation:<client>` actor
+ * so audits can tell the channel apart; (c) grants are single-use by construction — the synthesized
+ * approval lives only inside the one call and is never persisted.
+ *
+ * PURE — no SDK import, no I/O. The server wires `Server.elicitInput` around these shapes; handlers
+ * receive an injected callback and never see the server instance, so tests drive every branch with
+ * a fake elicitor.
+ */
+/** 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 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.
+ */
+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);
+    return {
+        message: `[Holmes-Kit 승인 요청] ${flat(req.kind, 40)} — ${flat(req.target, 80)}\n${flat(req.summary, 200)}\n승인(approve) / 거부(deny) / 질문(question) 을 선택하세요. 사유는 선택입니다.`,
+        requestedSchema: {
+            type: 'object',
+            properties: {
+                decision: { type: 'string', enum: ['approve', 'deny', 'question'], description: '승인/거부/질문' },
+                reason: { type: 'string', description: '사유(선택) — 거부·질문이면 에이전트 문면에 실립니다' },
+            },
+            required: ['decision'],
+        },
+    };
+}
+/**
+ * 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,
+ * missing content, a decision outside the enum, a non-string decision) is `null`, the same fallback
+ * as a channel that never answered. `decline` is a human's explicit NO — a decision, not a
+ * fallback — and `cancel` (window dismissed) is no decision at all.
+ */
+function interpretElicitResult(r) {
+    if (!r || typeof r !== 'object')
+        return null;
+    if (r.action === 'decline')
+        return { granted: false, reason: '사람이 세션에서 거절했습니다(decline)' };
+    if (r.action !== 'accept')
+        return null; // cancel, absent, anything else: no decision
+    const content = r.content;
+    if (!content || typeof content !== 'object')
+        return null;
+    const decision = content.decision;
+    const rawReason = content.reason;
+    const reason = typeof rawReason === 'string' && rawReason.trim() !== '' ? rawReason : undefined;
+    if (decision === 'approve')
+        return reason ? { granted: true, reason } : { granted: true };
+    if (decision === 'deny')
+        return { granted: false, reason: reason ?? '사람이 세션에서 거부했습니다(사유 없음)' };
+    if (decision === 'question')
+        return { granted: false, reason: `질문: ${reason ?? '(내용 없음)'} — 답한 뒤 다시 시도하십시오` };
+    return null; // outside the enum / wrong type: never a grant
+}

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

@@ -3,6 +3,7 @@ import { Action } from '../guardrail/phase';
 import { Basis } from './basis';
 import { Finding } from '../review/findings';
 import { Approval, Enforcement } from '../guardrail/risk-gate';
+import { Elicitor } from './elicit-approval';
 import { RiskAction } from '../guardrail/risk-types';
 /**
  * @implements A-SPEC-189 §7 (round 10)
@@ -31,7 +32,11 @@ import { AnchorMapping } from '../reverse/anchor';
  * precisely how the surface came to answer confidently with nothing backing it. The coverage test
  * walks the tool list for the same reason.
  */
-export declare function makeHandlers(store: SpecStore): RawHandlers & {
+export interface ElicitOpts {
+    elicit?: Elicitor;
+    clientName?: () => string;
+}
+export declare function makeHandlers(store: SpecStore, opts?: ElicitOpts): RawHandlers & {
     basis_detail(a: {
         root?: string;
     }): Promise<Basis & {
@@ -39,7 +44,7 @@ export declare function makeHandlers(store: SpecStore): RawHandlers & {
     }>;
 };
 type RawHandlers = ReturnType<typeof makeRawHandlers>;
-declare function makeRawHandlers(store: SpecStore): {
+declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
     spec_create(a: any): Promise<{
         ok: boolean;
         reason: string;

package/dist/holmes/mcp/handlers.js

@@ -99,6 +99,7 @@ const findings_1 = require("../review/findings");
 const package_1 = require("../review/package");
 const risk_classifier_1 = require("../guardrail/risk-classifier");
 const risk_gate_1 = require("../guardrail/risk-gate");
+const elicit_approval_1 = require("./elicit-approval");
 const approval_queue_1 = require("../governance/approval-queue");
 const approval_grants_1 = require("../governance/approval-grants");
 const spec_digest_1 = require("../spec/spec-digest");
@@ -415,15 +416,8 @@ async function deriveChangedContext(store, rootArg, a, toolName) {
  * information, and mtime would manufacture divergence on a checkout or a copy.
  */
 const LOADED_BUILD = (0, basis_1.loadedBuildId)(path.resolve(__dirname, '..', '..', '..'));
-/**
- * @implements A-SPEC-156
- * Basis is attached HERE, in one place, rather than inside each handler. Measured reasoning: 25
- * handlers edited by hand is 25 chances to forget, and the one that forgets is invisible — which is
- * precisely how the surface came to answer confidently with nothing backing it. The coverage test
- * walks the tool list for the same reason.
- */
-function makeHandlers(store) {
-    const raw = makeRawHandlers(store);
+function makeHandlers(store, opts) {
+    const raw = makeRawHandlers(store, opts);
     const wrapped = {};
     for (const [name, fn] of Object.entries(raw)) {
         wrapped[name] = (0, basis_1.withBasis)(fn, (a) => basisFor(a?.root));
@@ -471,8 +465,33 @@ function basisFor(root, withDisk = false) {
     }
     return (0, basis_1.collectBasis)(ctx);
 }
-function makeRawHandlers(store) {
+function makeRawHandlers(store, opts) {
     const resolver = (specs) => (id) => specs.find((s) => s.id === id) ?? null;
+    // @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.
+    const tryElicit = async (kind, target, summary) => {
+        if (!opts?.elicit || !elicit_approval_1.ELICITABLE_KINDS.has(kind))
+            return null;
+        try {
+            return await opts.elicit({ kind, target, summary });
+        }
+        catch {
+            return null;
+        }
+    };
+    // A granted answer becomes a synthesized Approval that rides the EXISTING seal path unchanged —
+    // the ledger's authorizationRef then honestly names the channel (`elicitation:<client>`), and
+    // single-use is structural: the object exists only inside this call, persisted nowhere.
+    const elicitApproval = (reason) => ({
+        actor: `elicitation:${opts?.clientName?.() ?? 'unknown'}`,
+        token: crypto.randomUUID(),
+        rationale: reason ?? 'elicitation grant',
+    });
     /**
      * Where the audit record for a governance act belongs — resolved BEFORE the act writes anything.
      *
@@ -894,7 +913,29 @@ function makeRawHandlers(store) {
             // covers, not merely well-formed (round-3 escalation: a token scoped to review-resolve — or
             // expired outright — completed a FULL SEAL here, so A-SPEC-133's narrowing was decorative at
             // the most consequential consumer). Unscoped {actor,token,rationale} stays the session key.
-            const approveResolved = resolveHandlerApproval(a.root, store, approval, { kind: 'spec-approve', target: a.id }, new Date().toISOString());
+            let approveResolved = resolveHandlerApproval(a.root, store, approval, { kind: 'spec-approve', target: a.id }, new Date().toISOString());
+            // @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).
+            if (approveResolved === undefined) {
+                const target = await store.read(a.id).catch(() => null);
+                if (target) {
+                    const resealing = typeof target.spec.frontmatter.approved_digest === 'string';
+                    // 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' };
+                    }
+                    else if (d) {
+                        // 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 ?? '(사유 없음)'}. 사유를 해소한 뒤 다시 시도하십시오.` };
+                    }
+                    // d === null: 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)'
                         + refusalQueueHint(a.root, store, { kind: 'spec-approve', target: a.id, why: '스펙 봉인 승인' }) };
@@ -1427,7 +1468,9 @@ function makeRawHandlers(store) {
             let baseline;
             if (verified) {
                 baseline = a.mark ?? DEFAULT_BASELINE;
-                (0, baseline_1.writeBaseline)(root, baseline, (0, change_source_1.hashTree)(root, { isIgnored: (p) => (0, ignore_1.loadIgnore)(root).isIgnored(p) }));
+                // A-SPEC-256.2 round-4 — surfaced to the report below
+                const ig = (0, ignore_1.loadIgnore)(root); // parse .gitignore ONCE, not per file (round-10)
+                (0, baseline_1.writeBaseline)(root, baseline, (0, change_source_1.hashTree)(root, { isIgnored: (p) => ig.isIgnored(p) }));
             }
             return { tier: testScope.tier, mode: result.mode, passed: result.passed, skipped: result.skipped,
                 ranFiles: result.ranFiles, executedByAspec, tail: result.tail,
@@ -1631,10 +1674,56 @@ function makeRawHandlers(store) {
             // cross-process TOCTOU — two sessions both recorded open under the same id, silencing an
             // open critical at both readers; consumeNonceExclusively already earned this discipline).
             const findingsFile = boundFindingsLedger(store, a.root);
+            // @implements A-SPEC-263.1 — elicitation happens BEFORE the lock: the human may take up to
+            // the wiring's timeout to answer, and holding the findings ledger lock for that long starves
+            // every other writer (the lock callback is synchronous by design). This is a best-effort
+            // PRE-SCAN over an unlocked snapshot: for each finding that LOOKS like an open-critical lift
+            // not covered by env/grant, ask now and carry the grant into the lock as data. TOCTOU folds
+            // fail-closed — state moved so the lift is no longer needed → the grant is simply unused;
+            // state moved so a lift IS needed that the snapshot missed → no grant → the standard refusal.
+            const elicitGrants = new Map();
+            // A DENY at pre-scan is carried as data too (round-1): throwing here judged a stale snapshot —
+            // a finding concurrently resolved by someone else no longer needs a lift inside the lock, and
+            // 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();
+            if (opts?.elicit) {
+                try {
+                    const snapshot = new Map();
+                    for (const f of new findings_1.FindingsLedger(findingsFile).list())
+                        snapshot.set(f.id, f);
+                    for (const f of a.findings) {
+                        const last = snapshot.get(f.id);
+                        if (!(f.status === 'resolved' && last?.status === 'open' && last.severity === 'critical'))
+                            continue;
+                        const raw0 = process.env.HOLMES_APPROVAL;
+                        let env0;
+                        try {
+                            env0 = raw0 ? JSON.parse(raw0) : undefined;
+                        }
+                        catch {
+                            env0 = undefined;
+                        }
+                        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 ?? '(사유 없음)');
+                    }
+                }
+                catch {
+                    // A pre-scan failure is never worse than no channel: fall through with no grants.
+                }
+            }
             (0, ledger_lock_1.withLedgerLock)(findingsFile, () => {
                 const ledger = new findings_1.FindingsLedger(findingsFile);
                 const latest = new Map();
                 const liftedCriticals = [];
+                const envLiftedCriticals = []; // lifts the ENV approval authorized (round-1: nonce charges only these)
+                const grantConsumptions = []; // spent AFTER the batch validates (round-2)
+                const elicitationLifts = []; // ledgered per lift (round-5: the promised audit trace)
                 for (const f of ledger.list())
                     latest.set(f.id, f);
                 for (const f of a.findings) {
@@ -1655,6 +1744,15 @@ function makeRawHandlers(store) {
                         throw new HandlerRefusal(`review_record: id ${f.id} 는 이미 미해소(open) 상태입니다 — 다른 발견이면 새 id 를 쓰고, 같은 발견의 갱신이면 먼저 resolved 를 기록한 뒤 재기록하십시오 (id 충돌이 남의 critical 을 침묵시키는 것을 막는 문입니다)`);
                     }
                     if (f.status === 'resolved' && last?.status === 'open' && last.severity === 'critical') {
+                        // @implements A-SPEC-191 §11 — checked BEFORE any approval is resolved or consumed
+                        // (round-2): with the guard after resolution, a single-use elicitation grant (or grant
+                        // file) was spent on the FIRST lift, so the second occurrence saw "no approval" and
+                        // surfaced a bogus set-HOLMES_APPROVAL message plus a queue entry for an act a human
+                        // already decided. The double-lift is named honestly on EVERY channel, and nothing
+                        // single-use is touched by a batch that dies here.
+                        if (liftedCriticals.includes(f.id)) {
+                            throw new HandlerRefusal(`review_record: 한 배치에서 같은 발견(${f.id})의 치명 해소를 두 번 들 수 없습니다 — 승인은 행위마다 필요합니다`);
+                        }
                         const raw = process.env.HOLMES_APPROVAL;
                         let approval;
                         try {
@@ -1667,21 +1765,45 @@ function makeRawHandlers(store) {
                         // not a master key — an EXPIRED or elsewhere-scoped approval must not lift a critical.
                         // An unscoped {actor,token,rationale} stays the operator's session key (unchanged).
                         const nowTs = new Date().toISOString();
-                        const rrResolved = resolveHandlerApproval(a.root, store, approval, { kind: 'review-resolve', target: f.id }, nowTs);
+                        let rrResolved = resolveHandlerApproval(a.root, store, approval, { kind: 'review-resolve', target: f.id }, nowTs);
+                        // @implements A-SPEC-263.1 — the second (and last) elicitable kind. The HUMAN was asked
+                        // BEFORE the lock (pre-scan above — a lock must not wait on a person); in here the grant
+                        // is plain data, consumed synchronously and at most once per id.
+                        if (rrResolved === undefined) {
+                            const g = elicitGrants.get(f.id);
+                            if (g) {
+                                elicitGrants.delete(f.id);
+                                rrResolved = { approval: g, source: 'elicitation' };
+                                elicitationLifts.push({ id: f.id, approval: g });
+                            }
+                        }
                         if (rrResolved === undefined) {
+                            // A pre-scan DENY surfaces HERE — only when the lift is genuinely needed at lock time
+                            // (round-1). The human decided, so the answer is the message and nothing is queued.
+                            const denied = elicitDenials.get(f.id);
+                            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") 를 서버 환경에 설정하고 다시 기록하십시오`
                                 + 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
+                        // single-use file when a LATER finding in the batch failed validation — nothing was
+                        // recorded, yet the operator's legitimate grant was gone and the retry refused. Same
+                        // harm class the env nonce fixed in its round-4; collected now, spent only once the
+                        // whole batch has validated (directly before the append, like the nonce block).
                         if (rrResolved.source === 'grant' && rrResolved.root && rrResolved.approval.nonce) {
-                            (0, approval_grants_1.consumeGrantFile)(rrResolved.root, rrResolved.approval.nonce);
-                        }
-                        // @implements A-SPEC-191 §11 — 한 배치가 같은 id 를 다시 열고 다시 닫으면 lift 는 두 번
-                        // 일어난다. 소비는 호출당 1회이므로, 세 번의 호출이면 거부됐을 일이 한 배치에서는
-                        // 통과했다(실측: 최종 상태와 게이트 판정이 갈렸다).
-                        if (liftedCriticals.includes(f.id)) {
-                            throw new HandlerRefusal(`review_record: 한 배치에서 같은 발견(${f.id})의 치명 해소를 두 번 들 수 없습니다 — 승인은 행위마다 필요합니다`);
+                            grantConsumptions.push({ root: rrResolved.root, nonce: rrResolved.approval.nonce });
                         }
                         liftedCriticals.push(f.id);
+                        // The nonce block below enforces single-use on the ENV approval — so it must key on the
+                        // lifts the ENV approval actually authorized (round-1): before elicitation existed,
+                        // reaching it implied env/grant coverage, but an elicitation-authorized lift flows past
+                        // it with a possibly unrelated env token in the environment. Charging THAT token burned
+                        // an innocent nonce, misattributed the ledger line, and a stale env nonce made a
+                        // human-approved lift permanently refusable.
+                        if (rrResolved.source === 'env')
+                            envLiftedCriticals.push(f.id);
                     }
                     latest.set(f.id, f); // 한 배치 안의 순서도 기록 순서다
                 }
@@ -1691,7 +1813,44 @@ function makeRawHandlers(store) {
                 // an act that never happened, the retry was refused, and two resolves in one batch would
                 // have double-spent). Consumption directly precedes the append; the only failure between
                 // them is the append itself, which throws loudly.
-                if (liftedCriticals.length > 0) {
+                // ONE NONCE, ONE ACT — on the grant channel too (round-4): the round-2 deferral removed the
+                // arity the in-loop spend had accidentally enforced, so a wide-scoped single-use grant
+                // backed N lifts in one batch while the same lifts split across calls refused after the
+                // first (the §13 batch-shape dependence). Checked BEFORE anything is spent (round-3 order
+                // doctrine: every throwable validation precedes every single-use spend).
+                {
+                    const liftsPerNonce = new Map();
+                    for (const g of grantConsumptions)
+                        liftsPerNonce.set(g.nonce, (liftsPerNonce.get(g.nonce) ?? 0) + 1);
+                    for (const [, n] of liftsPerNonce) {
+                        if (n > 1) {
+                            throw new HandlerRefusal(`review_record: 단일 사용 승인(grant)은 한 건의 치명 해소만 authorize 합니다 — 이 배치는 한 grant 로 ${n}건을 듭니다. 한 건씩 보내십시오`);
+                        }
+                    }
+                }
+                // The elicitation channel's AUDIT TRACE (round-5, repositioned round-6): the trust model
+                // admits review-resolve at a boundary closer than env/grant BECAUSE every grant is ledgered
+                // under an `elicitation:<client>` actor. This append is throwable I/O (chain lock
+                // contention, disk faults), so it stands BEFORE every single-use spend — round-5 placed it
+                // between the env-nonce spend and the findings append, and a lock-contended mixed batch
+                // burned the operator's env nonce with nothing recorded (the §7 doctrine regression). A
+                // failure HERE burns nothing; an orphaned event left when a LATER step throws stays honest,
+                // because it records the AUTHORIZATION, which already happened at pre-scan.
+                if (elicitationLifts.length > 0) {
+                    const chain = new ledger_store_1.FileLedgerStore(path.join(projectRootOf(a.root), '.ax', 'ledger'));
+                    for (const lift of elicitationLifts) {
+                        chain.append({
+                            ts: new Date().toISOString(), actor: lift.approval.actor, kind: 'review-resolve-authorized',
+                            summary: `elicitation grant authorized lifting open critical ${lift.id}`.slice(0, 200),
+                            inputs: [lift.id], rationale: lift.approval.rationale,
+                            authorization: (0, provenance_chain_1.authorizationRef)(lift.approval.actor, lift.approval.token),
+                        });
+                    }
+                }
+                // Keyed on the lifts the ENV approval AUTHORIZED, not on the ambient env var (round-1):
+                // an elicitation- or grant-authorized lift must not charge — or be blocked by — an env
+                // token that never covered the act. When env authorized nothing, its nonce is untouched.
+                if (envLiftedCriticals.length > 0) {
                     const raw = process.env.HOLMES_APPROVAL;
                     let approval;
                     try {
@@ -1706,8 +1865,8 @@ function makeRawHandlers(store) {
                     // @implements A-SPEC-191 §13 — 1회용 승인은 한 번의 행위를 authorize 한다. 9라운드
                     // 실측: 서로 다른 id 의 치명 해소 N 건이 한 배치에서 nonce 한 장으로 통과했고,
                     // 같은 세 건을 세 호출로 나누면 두 번째부터 거부됐다 — 판정이 묶음 방식에 의존했다.
-                    if ((0, provenance_chain_1.nonceDeclared)(approval?.nonce) && liftedCriticals.length > 1) {
-                        throw new HandlerRefusal(`review_record: 단일 사용 승인(nonce)은 한 건의 치명 해소만 authorize 합니다 — 이 배치는 ${liftedCriticals.length}건(${liftedCriticals.join(', ')})을 듭니다. 한 건씩 보내십시오`);
+                    if ((0, provenance_chain_1.nonceDeclared)(approval?.nonce) && envLiftedCriticals.length > 1) {
+                        throw new HandlerRefusal(`review_record: 단일 사용 승인(nonce)은 한 건의 치명 해소만 authorize 합니다 — 이 배치는 ${envLiftedCriticals.length}건(${envLiftedCriticals.join(', ')})을 듭니다. 한 건씩 보내십시오`);
                     }
                     if ((0, provenance_chain_1.nonceDeclared)(approval?.nonce)) {
                         // @implements A-SPEC-191 §10 — the same bound anchor as risk_check: two consumers must
@@ -1718,7 +1877,7 @@ function makeRawHandlers(store) {
                         }
                         const won = (0, provenance_chain_1.consumeNonceExclusively)(String(approval.nonce), ledgerFile, {
                             ts: new Date().toISOString(), actor: approval.actor, kind: 'nonce-consumed',
-                            summary: `consumed single-use approval for: review-resolve ${liftedCriticals.join(', ')}`.slice(0, 200),
+                            summary: `consumed single-use approval for: review-resolve ${envLiftedCriticals.join(', ')}`.slice(0, 200),
                             inputs: [(0, provenance_chain_1.nonceFingerprint)(String(approval.nonce))], rationale: approval.rationale,
                             authorization: (0, provenance_chain_1.authorizationRef)(approval.actor, approval.token),
                         });
@@ -1727,6 +1886,13 @@ function makeRawHandlers(store) {
                         }
                     }
                 }
+                // Deferred single-use spends — LAST, after every throwable validation including the
+                // env-nonce block above (round-3: placed before it, a mixed batch's env-nonce refusal
+                // burned the grant with nothing recorded — the exact harm the round-2 deferral was written
+                // to fix, reintroduced through the env throw path). Only the append itself follows, and it
+                // fails loudly.
+                for (const g of grantConsumptions)
+                    (0, approval_grants_1.consumeGrantFile)(g.root, g.nonce);
                 // @implements A-SPEC-157 — the server's OWN observation, not anything the caller sent.
                 // @implements A-SPEC-160 — the ONLY caller that reads the on-disk build, so the divergence
                 // marker can be sealed. Append INSIDE the same lock as the guard (round-6 TOCTOU).

package/dist/holmes/mcp/server.js

@@ -11,7 +11,32 @@ Object.defineProperty(exports, "HOOK_ENFORCED_TOOLS", { enumerable: true, get: f
 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');
-const handlers = (0, handlers_1.makeHandlers)(store);
+// @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');
+const elicit = async (req) => {
+    try {
+        if (!server.getClientCapabilities()?.elicitation)
+            return null;
+        const r = await server.elicitInput(buildElicitRequest(req), { timeout: 120_000 });
+        return interpretElicitResult(r);
+    }
+    catch {
+        return null;
+    }
+};
+const handlers = (0, handlers_1.makeHandlers)(store, {
+    elicit,
+    clientName: () => { try {
+        return server.getClientVersion()?.name ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    } },
+});
 // @implements A-SPEC-259 — the advertised version is the package's own, not a literal that froze at
 // 0.1.0: a hardcoded serverInfo.version blinds any client-side drift diagnosis.
 const PKG_VERSION = (() => {

package/dist/holmes/spec/id-collision.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Distributed id-preemption detection (REQ-254): two disconnected workspaces each see the same local
+ * max and issue the same spec number, and the collision is silent at create AND at push — the
+ * 2026-08-23 incident surfaced only as a rebase add/add conflict, and the bare-vs-dotted family
+ * variant (`A-SPEC-220` on one side, `A-SPEC-220.1~3` on the other) produced no git conflict at all.
+ * Prevention would demand central reservation, which the local-first principle forbids; where
+ * prevention is impossible, detection must be mechanical.
+ *
+ * The judgment key is (id, seal digest), NOT the id string (REQ-254 Constraints): files sharing an
+ * id AND an `approved_digest` are normal replication of one sealed spec — only differing digests
+ * mean two different specs are squatting one number. Unsealed drafts have no seal, so the content
+ * digest stands in: two workspaces both drafting the same number collide iff the drafts differ.
+ *
+ * PURE — list in, list out, no filesystem, no git. The I/O (walking the store, hashing bytes,
+ * reading frontmatter) belongs to the caller (doctor's collection layer), so tests exercise the
+ * judgment directly with fixture lists.
+ */
+export interface IdCollisionEntry {
+    /** Store-relative path, '/'-separated — reported verbatim so the finding is actionable. */
+    file: string;
+    id: string;
+    /** The seal (`approved_digest` frontmatter), absent on drafts — a SIGNAL, never the identity. */
+    approvedDigest?: string;
+    /**
+     * The canonical spec identity: specDigest of the parsed spec (CRLF-folded, SEAL_FIELDS excluded).
+     * NOT raw file bytes (round-1: raw bytes made a CRLF checkout difference read as a collision) and
+     * NOT the seal (round-1: a stale/forged seal hid a differing-content squat).
+     */
+    contentDigest: string;
+}
+export interface IdCollisionIssue {
+    kind: 'id-collision' | 'family-coexistence';
+    /** The colliding id, or the bare id of the coexisting family. */
+    id: string;
+    /** Every involved file, sorted — a pair for the classic case, more when replicas pile up. */
+    files: string[];
+    detail: string;
+}
+export declare function detectIdCollisions(entries: IdCollisionEntry[]): IdCollisionIssue[];

package/dist/holmes/spec/id-collision.js

@@ -0,0 +1,86 @@
+"use strict";
+// @implements A-SPEC-254.1
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectIdCollisions = detectIdCollisions;
+// Only A-SPEC and T-SPEC may carry dot sub-numbers (the engine enforces this), so only they can
+// have a bare/dotted family split. REQ/H-SPEC ids are structurally exempt.
+const DOTTED = /^([AT]-SPEC-\d+)\.\d+$/;
+function detectIdCollisions(entries) {
+    const issues = [];
+    // --- id-collision: same id, differing judgment keys ---
+    const byId = new Map();
+    for (const en of entries) {
+        const g = byId.get(en.id);
+        if (g)
+            g.push(en);
+        else
+            byId.set(en.id, [en]);
+    }
+    for (const [id, group] of byId) {
+        if (group.length < 2)
+            continue;
+        // IDENTITY IS THE CANONICAL CONTENT DIGEST, not the seal (round-1 adversarial finding): the
+        // `approved_digest` is a self-declared frontmatter string nobody verifies here, so trusting it
+        // let a post-approval edit — or a seal pasted onto a different spec — pass as "normal
+        // replication" while the bodies differed (the exact squat this module exists to expose). The
+        // caller supplies contentDigest as the canonical spec identity (specDigest: CRLF-folded,
+        // SEAL_FIELDS excluded), so a seal-stripped copy of the same spec is replication and a CRLF-only
+        // byte difference never fabricates a collision. The seal is kept as a SIGNAL: one seal value
+        // shared by differing contents is named in the detail (post-approval edit or copied seal).
+        const keys = new Set(group.map((en) => en.contentDigest));
+        if (keys.size < 2)
+            continue; // all copies carry the same spec content — replication, not a collision
+        const byKey = new Map();
+        for (const en of group) {
+            const g = byKey.get(en.contentDigest);
+            if (g)
+                g.push(en);
+            else
+                byKey.set(en.contentDigest, [en]);
+        }
+        const sealContents = new Map(); // seal value -> distinct contents claiming it
+        for (const en of group) {
+            if (!en.approvedDigest)
+                continue;
+            const s = sealContents.get(en.approvedDigest);
+            if (s)
+                s.add(en.contentDigest);
+            else
+                sealContents.set(en.approvedDigest, new Set([en.contentDigest]));
+        }
+        const sharedSeals = [...sealContents.entries()].filter(([, cs]) => cs.size > 1).map(([s]) => s).sort();
+        const parts = [...byKey.entries()].sort().map(([k, ens]) => `${k}[seal=${[...new Set(ens.map((en) => en.approvedDigest ?? '없음'))].sort().join('|')}] ← ${ens.map((en) => en.file).sort().join(', ')}`);
+        issues.push({
+            kind: 'id-collision',
+            id,
+            files: group.map((en) => en.file).sort(),
+            detail: parts.join(' / ')
+                + (sharedSeals.length > 0 ? ` — 같은 approved_digest 를 서로 다른 내용이 공유(${sharedSeals.join(', ')}): post-approval edit 또는 봉인 복사 의심` : ''),
+        });
+    }
+    // --- family-coexistence: a bare A/T-SPEC id alongside its own dot-suffix family ---
+    const ids = new Set(entries.map((en) => en.id));
+    const familyFiles = new Map(); // bare id -> dotted member files
+    for (const en of entries) {
+        const m = DOTTED.exec(en.id);
+        if (!m)
+            continue;
+        const f = familyFiles.get(m[1]);
+        if (f)
+            f.push(en.file);
+        else
+            familyFiles.set(m[1], [en.file]);
+    }
+    for (const [bare, dotted] of familyFiles) {
+        if (!ids.has(bare))
+            continue; // dotted-only families are the normal multi-slice shape
+        const bareFiles = entries.filter((en) => en.id === bare).map((en) => en.file);
+        issues.push({
+            kind: 'family-coexistence',
+            id: bare,
+            files: [...dotted, ...bareFiles].sort(),
+            detail: `bare ${bare} (${bareFiles.sort().join(', ')}) coexists with its dot-suffix family (${dotted.sort().join(', ')})`,
+        });
+    }
+    return issues.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : a.kind < b.kind ? -1 : 1));
+}

package/dist/holmes/spec/spec-store.js

@@ -101,8 +101,12 @@ function unreadableSpecFiles(specsDir) {
             if (!e.name.endsWith('.md'))
                 continue;
             let ok = false;
+            // TYPE before READ: readFileSync's open(2) blocks forever on a FIFO with no writer (measured
+            // 2026-08-24 — it hung doctor outright). A non-regular *.md IS an unreadable spec file, so it
+            // lands in this report without ever being opened; a dangling link throws and lands here too.
             try {
-                ok = (0, spec_parser_1.parseSpec)(fs.readFileSync(p, 'utf8')).id !== '';
+                if (fs.statSync(p).isFile())
+                    ok = (0, spec_parser_1.parseSpec)(fs.readFileSync(p, 'utf8')).id !== '';
             }
             catch {
                 ok = false;
@@ -226,6 +230,8 @@ class LocalMarkdownRepository {
                 }
                 else if (e.name.endsWith('.md')) {
                     try {
+                        if (!fs.statSync(p).isFile())
+                            continue; // a FIFO/device would hang open(2) — never read a non-regular file
                         const spec = (0, spec_parser_1.parseSpec)(fs.readFileSync(p, 'utf8'));
                         if (spec.id === id) {
                             result = p;
@@ -251,6 +257,8 @@ class LocalMarkdownRepository {
                     walk(p);
                 else if (e.name.endsWith('.md')) {
                     try {
+                        if (!fs.statSync(p).isFile())
+                            continue; // a FIFO/device would hang open(2) — never read a non-regular file
                         const spec = (0, spec_parser_1.parseSpec)(fs.readFileSync(p, 'utf8'));
                         // Only include valid specs with non-empty id
                         if (spec.id) {

package/package.json

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