@holmes-lab/holmes-kit 0.1.18 → 0.2.0

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

@@ -43,6 +43,7 @@ exports.queueHint = queueHint;
 const node_crypto_1 = require("node:crypto");
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
+const screen_safe_1 = require("../cli/screen-safe");
 /**
  * The approval request queue — the review list a human batches decisions over.
  *
@@ -183,6 +184,22 @@ function enqueueApprovalRequest(root, req) {
             why: req.why,
             ts: new Date().toISOString(),
         };
+        // TYPE BEFORE WRITE, for the same reason as the read (round-7): `appendFileSync` on a FIFO with
+        // no reader blocks in open(2) forever. Guarding only the reader left the GATE wedged — measured:
+        // `queueHint` never returned, and every refusal in the pre-tool-use hook, the stop hook and the
+        // MCP handlers goes through it. A queue that cannot be appended to is a queue that cannot be
+        // used; say so by returning false, which is already the "no queue here" answer.
+        // lstat, not stat (round-8): `statSync` follows symlinks, so a link planted at the queue path
+        // made the gate append its JSON line into whatever the link pointed at — a shell rc file, in the
+        // probe. The queue is a file this project owns or it is not a queue.
+        //
+        // Round-11: `existsSync` FOLLOWS the link, so on a DANGLING symlink it returns false, the `&&`
+        // short-circuits before lstat runs, and `appendFileSync` then CREATES the link's target outside
+        // the project. `lstat` unconditionally instead: it stats the link itself, which exists and is
+        // not a regular file, so a link — dangling or not — is refused. A path that truly does not exist
+        // throws ENOENT and is created, which is the ordinary first-write case.
+        if (!isPlainFile(file))
+            return false;
         fs.appendFileSync(file, JSON.stringify(event) + '\n');
         return true;
     }
@@ -190,10 +207,33 @@ function enqueueApprovalRequest(root, req) {
         return false;
     }
 }
+/**
+ * Is `file` a REGULAR FILE this project may write, judged by the link itself — never what it points
+ * at? `lstat` does not follow the symlink, so a link (dangling or live), a FIFO or a directory is
+ * refused; a path that does not exist yet throws and is treated as writable (it will be created).
+ * Round-11: `existsSync` here would follow the link and let a dangling one through (it resolves to
+ * "does not exist"), and the write would then create the target outside the project.
+ */
+function isPlainFile(file) {
+    try {
+        return fs.lstatSync(file).isFile();
+    }
+    catch {
+        return true;
+    }
+}
 /** Read and fold the queue on disk. A missing file is an empty queue, not an error. */
 function readQueue(root) {
+    const file = path.join(root, exports.QUEUE_RELPATH);
     try {
-        const raw = fs.readFileSync(path.join(root, exports.QUEUE_RELPATH), 'utf8');
+        // TYPE BEFORE READ. `readFileSync` on a FIFO blocks inside open(2) forever — no throw, no
+        // timeout, nothing a caller can interrupt. Round-7 measured it: `approve --list` hung, and so
+        // did `queueHint`, which every gate refusal calls — so a named pipe here wedges the pre-tool-use
+        // hook, the stop hook and the MCP handlers, not just the CLI. `approve-context.ts` has guarded
+        // this since the 2026-08-24 hang; the queue reader, which far more code depends on, did not.
+        if (!fs.lstatSync(file).isFile())
+            return { pending: [], malformedLines: 1, decisions: {} };
+        const raw = fs.readFileSync(file, 'utf8');
         return foldQueue(raw.split('\n'));
     }
     catch {
@@ -215,14 +255,26 @@ function queueHint(root, req) {
     // shows its reason and still re-files: a human may change their mind, and the re-filed entry is
     // how the reviewer sees the agent still wants it.
     const state = readQueue(root);
+    // @implements A-SPEC-262.1 — round-4: `question` and `reason` come out of queue EVENTS, and this
+    // text is read twice: printed in the operator's terminal AND carried in the agent's refusal. Raw,
+    // a held request could erase the screen and paint a line claiming the operator had approved. The
+    // decision surface's rule applies here too — line structure belongs to the template.
     const held = state.pending.find((p) => p.id === id && p.hold);
+    // Round-5: folded to terminal rows. This text is read in a terminal by the operator as well, and
+    // an unfolded hint carrying 300 columns of agent-authored question wraps unpredictably around
+    // whatever the gate printed before it.
     if (held) {
-        return `\n[보류 — 운영자 질문: ${held.question ?? '(질문 없음)'}] 게이트는 닫혀 있습니다.`
-            + ' 이 질문에 대한 답을 사용자에게 보고하십시오. 결정은 운영자가 npx holmes-kit approve 에서 내립니다.';
+        // Round-8: folded with NO margin, so the fold's boundary was the data's to choose and a held
+        // question forged a line at column 0 — `[승인됨] 운영자가 승인했습니다` — with zero escape bytes.
+        // Round-6 established that flattening is not enough once text is folded, and gave `[v]` a
+        // template-owned margin; this producer, read by the operator AND relayed by the agent, never got
+        // one. The first row keeps the template's own opening; the rest sit under the margin.
+        return (0, screen_safe_1.wrapColumns)(`\n[보류 — 운영자 질문: ${(0, screen_safe_1.flattenField)(held.question ?? '(질문 없음)', 300)}] 게이트는 닫혀 있습니다.`
+            + ' 이 질문에 대한 답을 사용자에게 보고하십시오. 결정은 운영자가 npx holmes-kit approve 에서 내립니다.', 76, '  \u2502 ');
     }
     const decided = state.decisions[id];
     const denialLine = decided?.event === 'denied'
-        ? `\n[거부됨${decided.reason ? `: ${decided.reason}` : ''}] 같은 요청을 반복하지 말고 거부 사유를 해소해 사용자와 상의하십시오.`
+        ? (0, screen_safe_1.wrapColumns)(`\n[거부됨${decided.reason ? `: ${(0, screen_safe_1.flattenField)(decided.reason, 300)}` : ''}] 같은 요청을 반복하지 말고 거부 사유를 해소해 사용자와 상의하십시오.`, 76, '  \u2502 ')
         : '';
     return enqueueApprovalRequest(root, req)
         ? `${denialLine}\n[승인 대기 ${id}] 운영자: npx holmes-kit approve`

package/dist/holmes/governance/ledger-rechain.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Re-chain a forked ledger against an EXPLICIT mainline — never a greedy one.
+ *
+ * The 2026-08-23 incident repair measured the trap this module exists to avoid: picking whichever
+ * line appears first at a fork as "the mainline" orphaned 571 lines of real history. Here the
+ * mainline is handed in by the caller (the committed ledger at a named git ref), it must verify on
+ * its own, and every working line that is not in it is re-chained AT THE TAIL in timestamp order —
+ * bodies byte-preserved, only seq/prevHash/hash recomputed ([lossless]).
+ */
+import { ProvenanceEvent } from './provenance-chain';
+/**
+ * Is this event list acceptable as a MAINLINE? [현재 키로 검증] 또는 [keyed-looking 줄이 없고
+ * keyless로 검증] — 키 채택 이전의 keyless 이력은 유효한 정본이다(round-3). This arm is for
+ * COMMITTED candidates only; the working copy never gets it (round-4 — a keyless re-signed
+ * replacement would certify itself). ONE source, shared with the CLI's walk.
+ */
+export declare function acceptsAsMainline(events: ProvenanceEvent[], key: string | undefined): boolean;
+export type RechainResult = {
+    events: ProvenanceEvent[];
+    orphanCount: number;
+    alreadyVerified: boolean;
+} | {
+    refused: string;
+};
+export declare function rechainLedger(mainline: ProvenanceEvent[], working: ProvenanceEvent[], key?: string): RechainResult;

package/dist/holmes/governance/ledger-rechain.js

@@ -0,0 +1,95 @@
+"use strict";
+// @implements A-SPEC-256.1
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.acceptsAsMainline = acceptsAsMainline;
+exports.rechainLedger = rechainLedger;
+/**
+ * Re-chain a forked ledger against an EXPLICIT mainline — never a greedy one.
+ *
+ * The 2026-08-23 incident repair measured the trap this module exists to avoid: picking whichever
+ * line appears first at a fork as "the mainline" orphaned 571 lines of real history. Here the
+ * mainline is handed in by the caller (the committed ledger at a named git ref), it must verify on
+ * its own, and every working line that is not in it is re-chained AT THE TAIL in timestamp order —
+ * bodies byte-preserved, only seq/prevHash/hash recomputed ([lossless]).
+ */
+const provenance_chain_1 = require("./provenance-chain");
+/**
+ * Is this event list acceptable as a MAINLINE? [현재 키로 검증] 또는 [keyed-looking 줄이 없고
+ * keyless로 검증] — 키 채택 이전의 keyless 이력은 유효한 정본이다(round-3). This arm is for
+ * COMMITTED candidates only; the working copy never gets it (round-4 — a keyless re-signed
+ * replacement would certify itself). ONE source, shared with the CLI's walk.
+ */
+function acceptsAsMainline(events, key) {
+    return (0, provenance_chain_1.verifyChain)(events, key).ok
+        || (key !== undefined && !(0, provenance_chain_1.hasKeyedLookingEvents)(events) && (0, provenance_chain_1.verifyChain)(events, undefined).ok);
+}
+// The identity of a line is its BODY, not its position in the chain — serialized via bodyCanon,
+// the ONE canonicalization for a body (a divergent second field list once destroyed records).
+const bodyKeyOf = (e) => (0, provenance_chain_1.bodyCanon)(e);
+// @implements A-SPEC-256.1 (round-7) — [lossless] means the ORIGINAL bytes: strip only the chain
+// position (seq/prevHash/hash) and keep every other field EXACTLY as it was, including the ABSENCE
+// of an optional field. `bodyOf` used to normalize (`?? ''`), so an event that omitted
+// `authorization` (recordStaleBreak does) came back with `authorization:""` — a byte difference the
+// hash tolerated but the on-disk line did not. chainNext hashes via canonicalize (same `?? ''`), so
+// the hash is unchanged; only the serialized bytes are now faithful.
+const bodyOf = (e) => {
+    const { seq: _s, prevHash: _p, hash: _h, ...body } = e;
+    return body;
+};
+function rechainLedger(mainline, working, key) {
+    // The working file is ALREADY-VERIFIED only when it verifies under the current key AND carries
+    // the mainline as a hash-prefix (round-4): the adoption arm belongs to COMMITTED mainline
+    // candidates only — applied to the working copy it certified a keyless re-signed replacement as
+    // "no change" (reproduced forgery), and a rolled-back verifying prefix as "no change" (leaving
+    // committed history unrestored — the working copy shorter than the committed mainline).
+    const mainlineIsPrefixOfWorking = mainline.length <= working.length
+        && mainline.every((e, i) => working[i] !== undefined && working[i].hash === e.hash && working[i].seq === e.seq);
+    if ((0, provenance_chain_1.verifyChain)(working, key).ok && mainlineIsPrefixOfWorking) {
+        return { events: working, orphanCount: 0, alreadyVerified: true };
+    }
+    if (!acceptsAsMainline(mainline, key)) {
+        const vm = (0, provenance_chain_1.verifyChain)(mainline, key);
+        return { refused: `본선이 스스로 검증되지 않습니다(brokenAt=${vm.brokenAt ?? '?'}: ${vm.detail ?? ''}) — 깨진 본선 위의 재연쇄는 정본을 위조합니다` };
+    }
+    // MULTISET difference, not set difference (round-1 adversarial finding): a body present once in
+    // the mainline and twice in the working copy carries a second, REAL occurrence — a set filter
+    // deleted it while the output still verified. Each mainline occurrence cancels exactly one
+    // working occurrence; everything beyond that count is an orphan: [lossless].
+    const mainCount = new Map();
+    for (const e of mainline) {
+        const k = bodyKeyOf(e);
+        mainCount.set(k, (mainCount.get(k) ?? 0) + 1);
+    }
+    const orphans = working.filter((e) => {
+        const k = bodyKeyOf(e);
+        const left = mainCount.get(k) ?? 0;
+        if (left > 0) {
+            mainCount.set(k, left - 1);
+            return false;
+        }
+        return true;
+    });
+    // @implements A-SPEC-256.1 (round-6) — on a KEYED ledger, a legitimate fork is made by a
+    // key-holding process, so its orphans are KEYED. A keyless-self-consistent orphan under a
+    // configured key is content inserted WITHOUT the key — a forgery verifyChain flags as
+    // 'keyless/tampered AFTER key adoption'. Re-signing it would launder the forgery into a valid
+    // keyed event, so we refuse rather than sign. (On a keyless ledger, keyless orphans are normal.)
+    // Only once the mainline itself has adopted a key: a keyless orphan there is content inserted
+    // after adoption WITHOUT the key (a forgery). If the mainline is entirely keyless (pre-adoption
+    // history), a keyless orphan is a legitimate legacy line and must NOT be refused (round-7).
+    if (key !== undefined && (0, provenance_chain_1.hasKeyedLookingEvents)(mainline)) {
+        // "Legitimate keyed fork" = VALIDLY SIGNED UNDER THE CURRENT KEY (round-12): keylessSelfConsistent
+        // only caught keyless forgeries, so a garbage-hash or foreign-key body slipped past and got
+        // re-signed with the real key. An orphan not keyed-self-consistent under this key is refused.
+        const forged = orphans.filter((o) => !(0, provenance_chain_1.keyedSelfConsistent)(o, key));
+        if (forged.length > 0) {
+            return { refused: `keyed 원장에 키 없이 삽입된 고아 ${forged.length}건이 있습니다 — 재서명하면 위조를 유효한 keyed 이벤트로 세탁합니다. 이 줄들을 조사·제거한 뒤 다시 실행하십시오(예: '${forged[0].summary}').` };
+        }
+    }
+    // Timestamp order, stable for ties (Array#sort is stable): the tail reads chronologically.
+    orphans.sort((a, b) => (a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : 0));
+    const events = [...mainline];
+    for (const o of orphans)
+        events.push((0, provenance_chain_1.chainNext)(events, bodyOf(o), key));
+    return { events, orphanCount: orphans.length, alreadyVerified: false };
+}

package/dist/holmes/governance/provenance-chain.d.ts

@@ -93,6 +93,36 @@ export declare function approvalMarkers(approval: {
     expires?: string;
     nonce?: string;
 } | undefined): string;
+/** Is this event signed WITHOUT a key? Recomputed over its OWN prevHash field, so it answers for
+ *  the line itself, independent of chain linkage — a forked keyless chain is all self-consistent
+ *  lines with broken linkage, while a keyed line fails this recompute. What fails it is
+ *  keyed-or-tampered: either way, rewriting it without the key would be forgery. */
+export declare function keylessSelfConsistent(e: ProvenanceEvent): boolean;
+/** True iff any line looks keyed (or tampered) — the refusal predicate for keyless rewriters. */
+export declare function hasKeyedLookingEvents(events: ProvenanceEvent[]): boolean;
+/** Is this event VALIDLY SIGNED under the given key — its own hash recomputed over its own prevHash
+ *  and body with that key? This is the true "legitimate on a keyed ledger" test (round-12): a
+ *  keyless-self-consistent line, a foreign-key line, and a garbage-hash line ALL fail it, so it is
+ *  the correct refusal predicate for orphans on a keyed history — not `keylessSelfConsistent`, which
+ *  a garbage hash silently slips past. */
+export declare function keyedSelfConsistent(e: ProvenanceEvent, key: string): boolean;
+/** The canonical BODY serialization (all seven fields, seq excluded) — the ONE identity of a ledger
+ *  line, shared by the rechain engine's orphan detection. */
+export declare function bodyCanon(b: Omit<ProvenanceBody, 'seq'>): string;
+/**
+ * Parse the JSONL ledger lines — the ONE parser shared by `load()` and the CLI's rechain (round-9).
+ *
+ * Tolerance is for a TORN TAIL ONLY: the file's last non-empty line may be a half-written record (a
+ * crash mid-append), and that is dropped. A parse failure on ANY EARLIER line, or a line that parses
+ * to a non-object (`123`, `"x"`, `[…]` — which would otherwise be laundered into a content-less event
+ * that still verifies), is CORRUPTION, not a torn tail: it throws rather than silently vanish, because
+ * a rechain that drops a mid-file line then 'repairs' the seq gap makes the loss permanent and
+ * invisible to verify(). `throwOnCorruption:false` restores best-effort leniency for readers that
+ * must degrade rather than abort (verify() then surfaces the resulting seam).
+ */
+export declare function parseLedgerLines(raw: string, file?: string, opts?: {
+    throwOnCorruption?: boolean;
+}): ProvenanceEvent[];
 export declare class ProvenanceChain {
     private readonly file;
     constructor(file: string);
@@ -116,12 +146,9 @@ export declare class ProvenanceChain {
     private appendUnlocked;
     /**
      * Records a broken stale hold into the chain itself. Bound so it can be handed to the lock layer,
-     * which must not import this module (the lock is the lower layer).
-     *
-     * Written WITHOUT re-entering the lock: this fires from inside the acquire loop, where the hold has
-     * just been released and not yet re-taken, so calling `append()` here would deadlock against the
-     * budget. The event may therefore race a concurrent writer, which is acceptable for a diagnostic —
-     * a missing note is better than a wedged harness, and `verify()` still reports any resulting seam.
+     * which must not import this module (the lock is the lower layer). Written WITHOUT re-entering the
+     * lock: this fires from inside the acquire loop, so calling `append()` here would deadlock against
+     * the budget. The event may race a concurrent writer, acceptable for a diagnostic.
      */
     staleBreakRecorder(): NonNullable<LockOptions['onStaleBreak']>;
     private recordStaleBreak;

package/dist/holmes/governance/provenance-chain.js

@@ -44,6 +44,11 @@ exports.blankNonce = blankNonce;
 exports.nonceDeclared = nonceDeclared;
 exports.nonceFingerprint = nonceFingerprint;
 exports.approvalMarkers = approvalMarkers;
+exports.keylessSelfConsistent = keylessSelfConsistent;
+exports.hasKeyedLookingEvents = hasKeyedLookingEvents;
+exports.keyedSelfConsistent = keyedSelfConsistent;
+exports.bodyCanon = bodyCanon;
+exports.parseLedgerLines = parseLedgerLines;
 exports.consumeNonceExclusively = consumeNonceExclusively;
 // @implements A-SPEC-125.2
 const crypto = __importStar(require("node:crypto"));
@@ -245,6 +250,85 @@ function approvalMarkers(approval) {
     const nonce = nonceDeclared(approval?.nonce) ? 'single-use' : 'no-nonce';
     return `approval[scope=${scope}; expiry=${expiry}; nonce=${nonce}]`;
 }
+// @implements A-SPEC-256.1 / A-SPEC-256.2
+/** Is this event signed WITHOUT a key? Recomputed over its OWN prevHash field, so it answers for
+ *  the line itself, independent of chain linkage — a forked keyless chain is all self-consistent
+ *  lines with broken linkage, while a keyed line fails this recompute. What fails it is
+ *  keyed-or-tampered: either way, rewriting it without the key would be forgery. */
+function keylessSelfConsistent(e) {
+    return computeHash(e.prevHash, e) === e.hash;
+}
+/** True iff any line looks keyed (or tampered) — the refusal predicate for keyless rewriters. */
+function hasKeyedLookingEvents(events) {
+    return events.some((e) => !keylessSelfConsistent(e));
+}
+/** Is this event VALIDLY SIGNED under the given key — its own hash recomputed over its own prevHash
+ *  and body with that key? This is the true "legitimate on a keyed ledger" test (round-12): a
+ *  keyless-self-consistent line, a foreign-key line, and a garbage-hash line ALL fail it, so it is
+ *  the correct refusal predicate for orphans on a keyed history — not `keylessSelfConsistent`, which
+ *  a garbage hash silently slips past. */
+function keyedSelfConsistent(e, key) {
+    return computeHash(e.prevHash, e, key) === e.hash;
+}
+/** The canonical BODY serialization (all seven fields, seq excluded) — the ONE identity of a ledger
+ *  line, shared by the rechain engine's orphan detection. */
+function bodyCanon(b) {
+    return JSON.stringify({
+        ts: b.ts, actor: b.actor, kind: b.kind, summary: b.summary,
+        inputs: b.inputs ?? [], rationale: b.rationale ?? '', authorization: b.authorization ?? '',
+    });
+}
+/**
+ * Parse the JSONL ledger lines — the ONE parser shared by `load()` and the CLI's rechain (round-9).
+ *
+ * Tolerance is for a TORN TAIL ONLY: the file's last non-empty line may be a half-written record (a
+ * crash mid-append), and that is dropped. A parse failure on ANY EARLIER line, or a line that parses
+ * to a non-object (`123`, `"x"`, `[…]` — which would otherwise be laundered into a content-less event
+ * that still verifies), is CORRUPTION, not a torn tail: it throws rather than silently vanish, because
+ * a rechain that drops a mid-file line then 'repairs' the seq gap makes the loss permanent and
+ * invisible to verify(). `throwOnCorruption:false` restores best-effort leniency for readers that
+ * must degrade rather than abort (verify() then surfaces the resulting seam).
+ */
+function parseLedgerLines(raw, file = '<ledger>', opts = {}) {
+    const throwOnCorruption = opts.throwOnCorruption !== false;
+    const lines = raw.split('\n');
+    let lastNonEmpty = -1;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        if (lines[i].trim()) {
+            lastNonEmpty = i;
+            break;
+        }
+    }
+    const out = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!line.trim())
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            if (i === lastNonEmpty)
+                continue; // torn tail — tolerated
+            if (throwOnCorruption)
+                throw new Error(`ledger ${file}: unparseable line ${i + 1} (mid-file corruption, not a torn tail)`);
+            continue;
+        }
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            // The LAST non-empty line is a torn tail regardless of whether it failed to parse or parsed to
+            // a non-object (a truncation can leave either) — tolerated consistently (round-12). Earlier
+            // non-object lines are corruption and throw in strict mode.
+            if (i === lastNonEmpty)
+                continue;
+            if (throwOnCorruption)
+                throw new Error(`ledger ${file}: line ${i + 1} is not a ledger event object (${Array.isArray(parsed) ? 'array' : typeof parsed})`);
+            continue;
+        }
+        out.push(parsed);
+    }
+    return out;
+}
 class ProvenanceChain {
     file;
     constructor(file) {
@@ -261,16 +345,10 @@ class ProvenanceChain {
                 return [];
             throw err;
         }
-        const out = [];
-        for (const line of raw.split('\n')) {
-            if (!line.trim())
-                continue;
-            try {
-                out.push(JSON.parse(line));
-            }
-            catch { /* torn tail line tolerated; verify() exposes real tampering */ }
-        }
-        return out;
+        // Readers degrade rather than abort: a dropped mid-file line leaves a seq gap that verify()
+        // reports. The rechain path parses STRICTLY (throwOnCorruption) because it repairs seq gaps and
+        // would otherwise make the drop permanent (round-9).
+        return parseLedgerLines(raw, this.file, { throwOnCorruption: false });
     }
     /** Append a new event chained onto the CURRENT on-disk tail. Returns the appended event.
      *  The signing key comes from HOLMES_LEDGER_KEY (out-of-band env, never tool-settable in-session).
@@ -300,12 +378,9 @@ class ProvenanceChain {
     }
     /**
      * Records a broken stale hold into the chain itself. Bound so it can be handed to the lock layer,
-     * which must not import this module (the lock is the lower layer).
-     *
-     * Written WITHOUT re-entering the lock: this fires from inside the acquire loop, where the hold has
-     * just been released and not yet re-taken, so calling `append()` here would deadlock against the
-     * budget. The event may therefore race a concurrent writer, which is acceptable for a diagnostic —
-     * a missing note is better than a wedged harness, and `verify()` still reports any resulting seam.
+     * which must not import this module (the lock is the lower layer). Written WITHOUT re-entering the
+     * lock: this fires from inside the acquire loop, so calling `append()` here would deadlock against
+     * the budget. The event may race a concurrent writer, acceptable for a diagnostic.
      */
     staleBreakRecorder() { return this.recordStaleBreak; }
     recordStaleBreak = (info) => {

package/dist/holmes/governance/provenance-ledger.d.ts

@@ -35,6 +35,13 @@ export interface LedgerVerifyResult {
         brokenAt?: number;
     }[];
 }
+/**
+ * Is `name` a LIVE ledger file this store owns — the legacy `provenance.jsonl` or a canonical replica
+ * `provenance.<id>.jsonl` (no dots in <id>)? This is the ONE definition of "a ledger file"; the
+ * `ledger rechain` CLI reused a hand-copied regex that drifted once (a loose `.*` swept in backups
+ * like `provenance.bak.jsonl`), so both now share this single source (round-16).
+ */
+export declare function isLedgerFilename(name: string): boolean;
 export declare class ProvenanceLedger {
     private readonly dir;
     /**

package/dist/holmes/governance/provenance-ledger.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ProvenanceLedger = void 0;
+exports.isLedgerFilename = isLedgerFilename;
 // @implements A-SPEC-206
 // @implements A-SPEC-148
 const fs = __importStar(require("node:fs"));
@@ -42,6 +43,15 @@ const provenance_chain_1 = require("./provenance-chain");
 const replica_id_1 = require("./replica-id");
 const LEGACY = 'provenance.jsonl';
 const REPLICA_FILE = /^provenance\.([^.]+)\.jsonl$/;
+/**
+ * Is `name` a LIVE ledger file this store owns — the legacy `provenance.jsonl` or a canonical replica
+ * `provenance.<id>.jsonl` (no dots in <id>)? This is the ONE definition of "a ledger file"; the
+ * `ledger rechain` CLI reused a hand-copied regex that drifted once (a loose `.*` swept in backups
+ * like `provenance.bak.jsonl`), so both now share this single source (round-16).
+ */
+function isLedgerFilename(name) {
+    return name === LEGACY || REPLICA_FILE.test(name);
+}
 /**
  * The project root that owns a ledger directory.
  *

package/dist/holmes/guardrail/risk-gate.d.ts

@@ -4,10 +4,20 @@ export interface Approval {
     actor: string;
     token: string;
     rationale: string;
-    /** If present, the approval authorizes ONLY actions matching some entry (deny-by-default within). */
+    /**
+     * If present, the approval authorizes ONLY actions matching some entry (deny-by-default within).
+     * `exact` (round-14): the pattern is a LITERAL target, compared by equality — `*` and a trailing
+     * `/` are ordinary characters, not wildcards. A grant DERIVED from a queue target (a real command
+     * the operator read on the decision row) sets this, because that target is a literal string, not a
+     * glob: without it, approving `rm -rf *` minted a grant that authorized `rm -rf /any/path` — the
+     * agent's choice within the wildcard, never the command the operator saw (round-3's doctrine, "the
+     * grant is for what the human saw", violated in the scope layer). Absent = glob, unchanged, for
+     * operator-authored patterns (the HOLMES_APPROVAL session key) where a `*` is intended.
+     */
     scope?: {
         kind: string;
         pattern: string;
+        exact?: boolean;
     }[];
     /** ISO 8601. If present, the approval is dead once the action timestamp passes it. */
     expires?: string;

package/dist/holmes/guardrail/risk-gate.js

@@ -56,6 +56,16 @@ function approvalCovers(a, action, now) {
             return false;
         if (s.kind !== '*' && s.kind !== action.kind)
             return false;
+        // A literal-target scope matches by equality — no wildcard, no directory prefix (round-14).
+        // A PRESENT `exact` that is not a strict boolean is malformed, and a malformed narrowing flag
+        // fails CLOSED — the entry matches nothing (round-15). Falling through to glob would be the
+        // wrong direction: `{pattern:'rm -rf *', exact:'true'}` would then authorize `rm -rf /any`, the
+        // exact widening round-14 closed, resurrected by a typed-wrong flag. This is the module's own
+        // doctrine ("a deadline we cannot read is one we assume passed") applied to authority width.
+        if (s.exact !== undefined && typeof s.exact !== 'boolean')
+            return false;
+        if (s.exact === true)
+            return s.pattern === action.target;
         return patternMatches(s.pattern, action.target);
     });
 }

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

@@ -0,0 +1,67 @@
+/**
+ * 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. */
+export declare const ELICITABLE_KINDS: ReadonlySet<string>;
+export interface ElicitApprovalRequest {
+    kind: string;
+    target: string;
+    /** 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". */
+export interface ElicitDecision {
+    granted: boolean;
+    reason?: string;
+}
+export type Elicitor = (req: ElicitApprovalRequest) => Promise<ElicitDecision | null>;
+/**
+ * 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): {
+    message: string;
+    requestedSchema: {
+        type: 'object';
+        properties: {
+            decision: {
+                type: 'string';
+                enum: string[];
+                description: string;
+            };
+            reason: {
+                type: 'string';
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+/**
+ * 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.
+ */
+export declare function interpretElicitResult(r: {
+    action?: unknown;
+    content?: unknown;
+} | null | undefined): ElicitDecision | null;

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
+}