@holmes-lab/holmes-kit 0.19.6 → 0.20.1

package/dist/holmes/cli/npx-cache-check.js

@@ -0,0 +1,130 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.npxPinOf = npxPinOf;
+exports.npmCacheRoot = npmCacheRoot;
+exports.checkNpxCache = checkNpxCache;
+// @implements A-SPEC-652.2
+/**
+ * doctor: is the npx cache entry the wiring will run intact?
+ *
+ * Measured 2026-09-15 on Windows: `.mcp.json` wires `npx -y -p @holmes-lab/holmes-kit@0.19.4
+ * holmes-mcp`; npx resolved it to `_npx/a739130c5322c549`, whose root `package.json` had gone, and
+ * died with `npm error ENOENT … package.json` before any handshake. The harness reported only
+ * "Connection closed". Six entries in that cache had the same shape (two of them this package).
+ *
+ * Filesystem only — no npm spawn: the cache root is `npm_config_cache`, else the platform default
+ * (`%LOCALAPPDATA%\npm-cache` on win32, `~/.npm` elsewhere). Only entries holding the PINNED version
+ * of the pinned package are judged; a corrupt entry of another version is not what this wiring runs.
+ */
+const path = __importStar(require("node:path"));
+const NAME = 'npx cache';
+/** The `-p <pkg>@<ver>` pin of the target's holmes-kit wiring, or null when it is not an npx pin. */
+function npxPinOf(target, deps) {
+    const mcpPath = path.join(target, '.mcp.json');
+    if (!deps.exists(mcpPath))
+        return null;
+    let server;
+    try {
+        server = JSON.parse(deps.readFile(mcpPath)).mcpServers?.['holmes-kit'];
+    }
+    catch {
+        return null;
+    }
+    if (!server || !/^npx(\.cmd)?$/i.test(String(server.command ?? '')) || !Array.isArray(server.args))
+        return null;
+    const at = server.args.indexOf('-p');
+    const spec = at >= 0 ? server.args[at + 1] : undefined;
+    const m = spec ? /^(@?[^@]+)@([0-9][^\s]*)$/.exec(spec) : null;
+    return m ? { pkg: m[1], version: m[2] } : null;
+}
+function npmCacheRoot(deps) {
+    const configured = deps.env.npm_config_cache;
+    if (configured && configured.trim() !== '')
+        return configured;
+    if (deps.platform === 'win32') {
+        const local = deps.env.LOCALAPPDATA && deps.env.LOCALAPPDATA.trim() !== '' ? deps.env.LOCALAPPDATA : path.join(deps.homedir, 'AppData', 'Local');
+        return path.join(local, 'npm-cache');
+    }
+    return path.join(deps.homedir, '.npm');
+}
+function checkNpxCache(target, deps) {
+    const pin = npxPinOf(target, deps);
+    if (!pin)
+        return { name: NAME, level: 'PASS', detail: 'the holmes-kit wiring is not an npx pin — nothing cached to judge' };
+    const npxDir = path.join(npmCacheRoot(deps), '_npx');
+    if (!deps.exists(npxDir))
+        return { name: NAME, level: 'PASS', detail: `${pin.pkg}@${pin.version} is not cached yet (${npxDir} absent) — the first launch installs it` };
+    let hashes = [];
+    try {
+        hashes = deps.readdir(npxDir);
+    }
+    catch {
+        return { name: NAME, level: 'PASS', detail: `${npxDir} could not be listed — nothing to judge` };
+    }
+    const matching = [];
+    const corrupt = [];
+    for (const hash of hashes) {
+        const entry = path.join(npxDir, hash);
+        const pkgJson = path.join(entry, 'node_modules', ...pin.pkg.split('/'), 'package.json');
+        if (!deps.exists(pkgJson))
+            continue;
+        let version;
+        try {
+            version = JSON.parse(deps.readFile(pkgJson)).version;
+        }
+        catch {
+            continue;
+        }
+        if (version !== pin.version)
+            continue;
+        matching.push(hash);
+        if (!deps.exists(path.join(entry, 'package.json')))
+            corrupt.push(hash);
+    }
+    if (matching.length === 0)
+        return { name: NAME, level: 'PASS', detail: `${pin.pkg}@${pin.version} is not cached yet under ${npxDir} — the first launch installs it` };
+    if (corrupt.length === 0)
+        return { name: NAME, level: 'PASS', detail: `${matching.length} intact npx cache entr${matching.length === 1 ? 'y' : 'ies'} for ${pin.pkg}@${pin.version}` };
+    const dirs = corrupt.map((h) => path.join(npxDir, h));
+    const remove = deps.platform === 'win32'
+        ? dirs.map((d) => `Remove-Item -Recurse -Force "${d}"`).join('; ')
+        : dirs.map((d) => `rm -rf ${d}`).join(' && ');
+    return {
+        name: NAME, level: 'FAIL',
+        detail: `npx cache entr${corrupt.length === 1 ? 'y' : 'ies'} ${corrupt.join(', ')} for ${pin.pkg}@${pin.version} ${corrupt.length === 1 ? 'is' : 'are'} missing its package.json — the wiring dies with \`npm error ENOENT\` before the handshake and the harness reports only "Connection closed" (${dirs.join(', ')})`,
+        fix: `Delete the corrupt entr${corrupt.length === 1 ? 'y' : 'ies'} and let the next launch reinstall: ${remove}`,
+    };
+}

package/dist/holmes/cli/playbook-skills.d.ts

@@ -11,12 +11,8 @@
  * Playbooks are ADVISORY. No gate decision reads them, and a user who deletes every one of them
  * still gets identical enforcement — which is why a missing playbook is a doctor WARN, never a FAIL.
  */
-/**
- * Marks a file as OURS. Ownership is decided by this marker and never by the path, because the path
- * is exactly what a user's own skill of the same name would occupy, and overwriting that would be
- * the same class of error as clobbering their settings.
- */
-export declare const PLAYBOOK_SKILL_MARKER = "<!-- installed by holmes-kit; edits will be replaced on upgrade -->";
+import { PLAYBOOK_SKILL_MARKER, carriesMarker, frontmatterEnd } from '../project/installer-markers';
+export { PLAYBOOK_SKILL_MARKER, carriesMarker, frontmatterEnd };
 /**
  * @implements A-SPEC-190 (round 7)
  * The bytes an install writes. The marker used to go FIRST, which put it ahead of the playbook's
@@ -28,22 +24,6 @@ export declare const PLAYBOOK_SKILL_MARKER = "<!-- installed by holmes-kit; edit
  * while doctor certified the layout as `current`. The marker now follows the frontmatter block.
  */
 export declare function installedSkillBytes(body: string): string;
-/**
- * @implements A-SPEC-190 (round 7)
- * Ownership is the marker AT ITS PLACE, not the string anywhere in the file. `includes` made any
- * document that merely QUOTES the marker — documentation about holmes-kit, a review note — read as
- * ours: doctor called it `drifted` and the refresh it advised overwrote the user's file with no
- * backup. A quotation is not a claim of ownership.
- */
-export declare function carriesMarker(content: string): boolean;
-/**
- * @implements A-SPEC-190 (round 8)
- * Where a leading YAML frontmatter block ends, or null. Round-8 measured the shapes the first
- * regex missed — a BOM, an EMPTY block (`---\n---\n`), and a closing fence at end-of-file with no
- * trailing newline — each of which sent the marker back to byte 0, recreating the CRITICAL the
- * round-7 fix existed to remove while doctor certified the result as `current`.
- */
-export declare function frontmatterEnd(content: string): number | null;
 /**
  * @implements A-SPEC-172
  * What the user types to reach a playbook.

package/dist/holmes/cli/playbook-skills.js

@@ -33,10 +33,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PLAYBOOK_SKILL_MARKER = void 0;
+exports.frontmatterEnd = exports.carriesMarker = exports.PLAYBOOK_SKILL_MARKER = void 0;
 exports.installedSkillBytes = installedSkillBytes;
-exports.carriesMarker = carriesMarker;
-exports.frontmatterEnd = frontmatterEnd;
 exports.invocableSkillName = invocableSkillName;
 exports.skillPathFor = skillPathFor;
 exports.installPlaybookSkills = installPlaybookSkills;
@@ -62,12 +60,10 @@ const path = __importStar(require("node:path"));
  * Playbooks are ADVISORY. No gate decision reads them, and a user who deletes every one of them
  * still gets identical enforcement — which is why a missing playbook is a doctor WARN, never a FAIL.
  */
-/**
- * Marks a file as OURS. Ownership is decided by this marker and never by the path, because the path
- * is exactly what a user's own skill of the same name would occupy, and overwriting that would be
- * the same class of error as clobbering their settings.
- */
-exports.PLAYBOOK_SKILL_MARKER = '<!-- installed by holmes-kit; edits will be replaced on upgrade -->';
+const installer_markers_1 = require("../project/installer-markers");
+Object.defineProperty(exports, "PLAYBOOK_SKILL_MARKER", { enumerable: true, get: function () { return installer_markers_1.PLAYBOOK_SKILL_MARKER; } });
+Object.defineProperty(exports, "carriesMarker", { enumerable: true, get: function () { return installer_markers_1.carriesMarker; } });
+Object.defineProperty(exports, "frontmatterEnd", { enumerable: true, get: function () { return installer_markers_1.frontmatterEnd; } });
 /**
  * @implements A-SPEC-190 (round 7)
  * The bytes an install writes. The marker used to go FIRST, which put it ahead of the playbook's
@@ -79,54 +75,14 @@ exports.PLAYBOOK_SKILL_MARKER = '<!-- installed by holmes-kit; edits will be rep
  * while doctor certified the layout as `current`. The marker now follows the frontmatter block.
  */
 function installedSkillBytes(body) {
-    const end = frontmatterEnd(body);
+    const end = (0, installer_markers_1.frontmatterEnd)(body);
     if (end === null)
-        return `${exports.PLAYBOOK_SKILL_MARKER}\n${body}`;
+        return `${installer_markers_1.PLAYBOOK_SKILL_MARKER}\n${body}`;
     // The offset is computed on normalised text; a body with CRLF or a BOM is rewritten normalised so
     // the marker cannot land inside the frontmatter it must follow.
     const text = body.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
     const head = text.slice(0, end);
-    return `${head}${head.endsWith('\n') ? '' : '\n'}${exports.PLAYBOOK_SKILL_MARKER}\n${text.slice(end)}`;
-}
-/**
- * @implements A-SPEC-190 (round 7)
- * Ownership is the marker AT ITS PLACE, not the string anywhere in the file. `includes` made any
- * document that merely QUOTES the marker — documentation about holmes-kit, a review note — read as
- * ours: doctor called it `drifted` and the refresh it advised overwrote the user's file with no
- * backup. A quotation is not a claim of ownership.
- */
-function carriesMarker(content) {
-    // Round-8: judging on raw bytes made ownership brittle in the direction that cannot be repaired.
-    // A CRLF normalisation (a Windows editor, `core.autocrlf`, `.gitattributes eol=crlf`), a BOM, or a
-    // trailing space on the marker line each turned a file the kit itself wrote into `foreign` —
-    // permanently, since install then skips it forever and doctor advises deleting it as "yours".
-    // Whitespace and line endings are not ownership; the marker is.
-    const text = content.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
-    const markerAt = (s) => {
-        const line = s.split('\n', 1)[0];
-        return line.trimEnd() === exports.PLAYBOOK_SKILL_MARKER;
-    };
-    if (markerAt(text))
-        return true; // 옛 배치(마커 먼저) — 우리 것이므로 고칠 수 있다
-    const fm = frontmatterEnd(text);
-    // 빈 줄 하나가 소유를 지우지 않는다(round-9: frontmatter 뒤 개행 하나로 영구 foreign 이 됐다).
-    return fm !== null && markerAt(text.slice(fm).replace(/^\s*\n/, ''));
-}
-/**
- * @implements A-SPEC-190 (round 8)
- * Where a leading YAML frontmatter block ends, or null. Round-8 measured the shapes the first
- * regex missed — a BOM, an EMPTY block (`---\n---\n`), and a closing fence at end-of-file with no
- * trailing newline — each of which sent the marker back to byte 0, recreating the CRITICAL the
- * round-7 fix existed to remove while doctor certified the result as `current`.
- */
-function frontmatterEnd(content) {
-    const text = content.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
-    if (!/^---[ \t]*(\n|$)/.test(text))
-        return null;
-    const m = /\n---[ \t]*(\n|$)/.exec(text.slice(3));
-    if (!m)
-        return null;
-    return 3 + m.index + m[0].length;
+    return `${head}${head.endsWith('\n') ? '' : '\n'}${installer_markers_1.PLAYBOOK_SKILL_MARKER}\n${text.slice(end)}`;
 }
 /**
  * @implements A-SPEC-172
@@ -168,7 +124,7 @@ function playbookNames(packageRoot) {
 }
 const isOurs = (file) => {
     try {
-        return carriesMarker(fs.readFileSync(file, 'utf8'));
+        return (0, installer_markers_1.carriesMarker)(fs.readFileSync(file, 'utf8'));
     }
     catch {
         return false;
@@ -637,7 +593,7 @@ function playbookSkillStates(packageRoot, target) {
             out.push({ name, state: err.code === 'ENOENT' && !lstatPresent ? 'missing' : 'foreign' });
             continue;
         }
-        const state = !carriesMarker(installed) ? 'foreign'
+        const state = !(0, installer_markers_1.carriesMarker)(installed) ? 'foreign'
             : installed === installedSkillBytes(body) ? 'current' : 'drifted';
         out.push({ name, state });
     }

package/dist/holmes/cli/probe-process.d.ts

@@ -1,8 +1,23 @@
-import { type ChildProcess } from 'node:child_process';
+import { execFile as nodeExecFile, type ChildProcess } from 'node:child_process';
 /** Each POSIX probe gets its own process group; Windows taskkill targets only its owned PID. */
 export declare const PROBE_SPAWN_OPTIONS: {
     detached: boolean;
     windowsHide: boolean;
 };
+/**
+ * A-SPEC-651.2 — budgets measured, not guessed. taskkill /T /F finished in 0.56–0.67 s on a quiet
+ * box (2026-09-14); the old 2.5 s budget, spent once, read "cleanup could not be confirmed" on a
+ * healthy install in 1 of 4 quiet doctor runs and 2 of 3 loaded ones. 8 s each, and a timed-out
+ * taskkill gets exactly one more try — a refused one does not (A-SPEC-592: a failed tree kill is never
+ * success).
+ */
+export declare const PROBE_KILL_TIMEOUT_MS = 8000;
+export declare const PROBE_CLOSE_TIMEOUT_MS = 8000;
+export interface ProbeStopDeps {
+    platform?: NodeJS.Platform;
+    execFile?: typeof nodeExecFile;
+}
+/** Why the most recent stopProbeProcess answered false; undefined after a confirmed cleanup. */
+export declare function lastProbeStopReason(): string | undefined;
 export declare function trackProbeProcess(child: ChildProcess): void;
-export declare function stopProbeProcess(child?: ChildProcess): Promise<boolean>;
+export declare function stopProbeProcess(child?: ChildProcess, deps?: ProbeStopDeps): Promise<boolean>;

package/dist/holmes/cli/probe-process.js

@@ -1,13 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PROBE_SPAWN_OPTIONS = void 0;
+exports.PROBE_CLOSE_TIMEOUT_MS = exports.PROBE_KILL_TIMEOUT_MS = exports.PROBE_SPAWN_OPTIONS = void 0;
+exports.lastProbeStopReason = lastProbeStopReason;
 exports.trackProbeProcess = trackProbeProcess;
 exports.stopProbeProcess = stopProbeProcess;
 // @implements A-SPEC-592
+// @implements A-SPEC-651.2
 const node_child_process_1 = require("node:child_process");
 /** Each POSIX probe gets its own process group; Windows taskkill targets only its owned PID. */
 exports.PROBE_SPAWN_OPTIONS = { detached: process.platform !== 'win32', windowsHide: true };
+/**
+ * A-SPEC-651.2 — budgets measured, not guessed. taskkill /T /F finished in 0.56–0.67 s on a quiet
+ * box (2026-09-14); the old 2.5 s budget, spent once, read "cleanup could not be confirmed" on a
+ * healthy install in 1 of 4 quiet doctor runs and 2 of 3 loaded ones. 8 s each, and a timed-out
+ * taskkill gets exactly one more try — a refused one does not (A-SPEC-592: a failed tree kill is never
+ * success).
+ */
+exports.PROBE_KILL_TIMEOUT_MS = 8000;
+exports.PROBE_CLOSE_TIMEOUT_MS = 8000;
 const states = new WeakMap();
+let lastReason;
+/** Why the most recent stopProbeProcess answered false; undefined after a confirmed cleanup. */
+function lastProbeStopReason() { return lastReason; }
 function trackProbeProcess(child) {
     if (states.has(child))
         return;
@@ -15,30 +29,45 @@ function trackProbeProcess(child) {
     states.set(child, state);
     child.once('close', () => { state.closed = true; });
 }
-async function stopProbeProcess(child) {
+const isTimeout = (error) => {
+    const e = error;
+    return !!e && (e.killed === true || e.code === null || e.code === undefined);
+};
+async function stopProbeProcess(child, deps = {}) {
+    lastReason = undefined;
     if (!child)
         return true;
     trackProbeProcess(child);
+    const platform = deps.platform ?? process.platform;
+    const execFile = deps.execFile ?? node_child_process_1.execFile;
     let closed = states.get(child).closed;
     let onClose = () => { };
     let closeTimer;
     const closure = new Promise(resolve => {
         onClose = () => { closed = true; clearTimeout(closeTimer); resolve(true); };
         child.once('close', onClose);
-        closeTimer = setTimeout(() => resolve(false), 3000);
+        closeTimer = setTimeout(() => resolve(false), exports.PROBE_CLOSE_TIMEOUT_MS);
         if (closed || !child.pid)
             onClose();
     });
     let stopped = true;
+    let stopReason;
     try {
-        if (child.pid && process.platform === 'win32' && !closed) {
-            stopped = await new Promise(resolve => {
-                (0, node_child_process_1.execFile)('taskkill.exe', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true, timeout: 2500 }, error => {
-                    resolve(!error);
-                });
+        if (child.pid && platform === 'win32' && !closed) {
+            const taskkill = () => new Promise(resolve => {
+                execFile('taskkill.exe', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true, timeout: exports.PROBE_KILL_TIMEOUT_MS }, error => resolve(error ?? null));
             });
+            let error = await taskkill();
+            if (error && isTimeout(error))
+                error = await taskkill(); // one retry, for a timeout only
+            if (error) {
+                stopped = false;
+                stopReason = isTimeout(error)
+                    ? `taskkill timed out twice (${exports.PROBE_KILL_TIMEOUT_MS} ms each)`
+                    : `taskkill exited ${String(error.code)}`;
+            }
         }
-        else if (child.pid && process.platform !== 'win32') {
+        else if (child.pid && platform !== 'win32') {
             const signalGroup = (signal) => {
                 try {
                     process.kill(-child.pid, signal);
@@ -56,8 +85,9 @@ async function stopProbeProcess(child) {
             signalGroup('SIGKILL');
         }
     }
-    catch {
+    catch (error) {
         stopped = false;
+        stopReason = `kill failed: ${error.message}`;
     }
     // Terminate the tree before closing stdin: an EOF could make the wrapper exit first,
     // leaving Windows taskkill with no parent from which to enumerate its descendants.
@@ -69,5 +99,8 @@ async function stopProbeProcess(child) {
     child.removeListener('close', onClose);
     if (!released)
         child.unref();
-    return stopped && released;
+    const ok = stopped && released;
+    if (!ok)
+        lastReason = stopReason ?? `child never closed within ${exports.PROBE_CLOSE_TIMEOUT_MS} ms`;
+    return ok;
 }

package/dist/holmes/governance/approval-grants.d.ts

@@ -33,6 +33,27 @@ export declare function readGrants(root: string): {
     grants: Approval[];
     ignored: number;
 };
+/**
+ * @implements A-SPEC-649
+ * A minted grant may carry its BINDING: the workspace it was minted in and the digest of the subject
+ * the operator read. Neither is part of the guardrail's `Approval` (an operator's env token has no
+ * binding); both are optional so legacy grant files keep covering exactly as before (stated).
+ */
+export type BoundGrant = Approval & {
+    workspace?: string;
+    subject?: string;
+    requestedBy?: string;
+};
+export type BindingRefusal = 'foreign-workspace' | 'stale-subject';
+/** @implements A-SPEC-649 — the grants that WOULD cover this action but are refused by their binding, by name. */
+export declare function refusedGrantReasons(root: string, action: {
+    kind: string;
+    target: string;
+    subject?: string;
+}, now: string): Array<{
+    nonce: string;
+    reason: BindingRefusal;
+}>;
 /** First grant that covers the action — judged by `approvalCovers` and nothing else. Pure. */
 export declare function pickCoveringGrant(grants: Approval[], action: {
     kind: string;
@@ -48,6 +69,7 @@ export declare function pickCoveringGrant(grants: Approval[], action: {
 export declare function resolveApproval(root: string, envApproval: Approval | undefined, action: {
     kind: string;
     target: string;
+    subject?: string;
 }, now: string): {
     approval: Approval;
     source: 'env' | 'grant';

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

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GRANTS_RELDIR = void 0;
 exports.readGrants = readGrants;
+exports.refusedGrantReasons = refusedGrantReasons;
 exports.pickCoveringGrant = pickCoveringGrant;
 exports.resolveApproval = resolveApproval;
 exports.consumeGrantFile = consumeGrantFile;
@@ -42,6 +43,8 @@ exports.consumeGrantFile = consumeGrantFile;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const risk_gate_1 = require("../guardrail/risk-gate");
+const workspace_identity_1 = require("../project/workspace-identity");
+const approval_queue_1 = require("./approval-queue");
 /**
  * The grant file channel — approval delivery with no file editing and no reconnect.
  *
@@ -102,6 +105,47 @@ function readGrants(root) {
     }
     return { grants, ignored };
 }
+/** The current workspace id, or undefined for a legacy workspace / an unreadable identity. */
+function currentWorkspaceId(root) {
+    try {
+        const id = (0, workspace_identity_1.workspaceIdentity)(root, 'status');
+        return id.state === 'legacy' ? undefined : id.workspaceId;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Why this grant must NOT cover this action here, or null. Measured 2026-09-14 on the shipped dist:
+ * a grant file copied into another workspace with the same request id sealed there, and a grant
+ * read against one spec body sealed a different one. A grant that names a workspace is refused in
+ * any other (or in a workspace with no identity to compare); a grant that names a subject is
+ * refused when the action NAMES a subject and it differs. An action that names no subject is
+ * judged by its consumer at the point where the subject is known: `spec_approve` compares the
+ * grant's subject with the digest of its ONE versioned read (an extra read here to learn the
+ * subject moved the optimistic-write window and let an external edit be sealed — measured by the
+ * A-SPEC-188 TOCTOU pin), and every other decision kind carries a content-addressed target.
+ */
+function bindingRefusal(grant, action, workspace) {
+    if (typeof grant.workspace === 'string' && grant.workspace !== '' && grant.workspace !== workspace)
+        return 'foreign-workspace';
+    if (typeof grant.subject === 'string' && grant.subject !== '' && action.subject !== undefined && grant.subject !== action.subject)
+        return 'stale-subject';
+    return null;
+}
+/** @implements A-SPEC-649 — the grants that WOULD cover this action but are refused by their binding, by name. */
+function refusedGrantReasons(root, action, now) {
+    const workspace = currentWorkspaceId(root);
+    const out = [];
+    for (const g of readGrants(root).grants) {
+        if (!(0, risk_gate_1.approvalCovers)(g, action, now))
+            continue;
+        const reason = bindingRefusal(g, action, workspace);
+        if (reason && typeof g.nonce === 'string')
+            out.push({ nonce: g.nonce, reason });
+    }
+    return out;
+}
 /** First grant that covers the action — judged by `approvalCovers` and nothing else. Pure. */
 function pickCoveringGrant(grants, action, now) {
     for (const g of Array.isArray(grants) ? grants : []) {
@@ -120,7 +164,9 @@ function pickCoveringGrant(grants, action, now) {
 function resolveApproval(root, envApproval, action, now) {
     if ((0, risk_gate_1.approvalCovers)(envApproval, action, now))
         return { approval: envApproval, source: 'env' };
-    const grant = pickCoveringGrant(readGrants(root).grants, action, now);
+    // @implements A-SPEC-649 — a bound grant is a candidate only in its own workspace and for its own subject.
+    const workspace = currentWorkspaceId(root);
+    const grant = pickCoveringGrant(readGrants(root).grants.filter((g) => bindingRefusal(g, action, workspace) === null), action, now);
     return grant ? { approval: grant, source: 'grant' } : undefined;
 }
 /**
@@ -157,6 +203,14 @@ function consumeGrantFile(root, nonce) {
         // No directory, or it cannot be read: there is nothing to spend, which is an ordinary state.
         return;
     }
+    // @implements A-SPEC-649 — the spend is a queue event too, so the decision surface can show the
+    // grant's outcome without reading the provenance ledger. Best-effort, like the removal itself.
+    if (removed > 0) {
+        try {
+            (0, approval_queue_1.appendQueueEvent)(root, { event: 'consumed', id: wanted });
+        }
+        catch { /* fire-and-forget */ }
+    }
     if (removed === 0) {
         // Consumption runs AFTER the act succeeded, so this must never throw — but it must not be silent
         // either: an unspent single-use grant is still spendable, and nobody would know.

package/dist/holmes/governance/approval-queue.d.ts

@@ -1,3 +1,4 @@
+import { ExecutionContext } from '../project/execution-context';
 /**
  * The approval request queue — the review list a human batches decisions over.
  *
@@ -53,6 +54,17 @@ export interface PendingRequest {
      * reads it, so an absent or wrong value can never change a verdict.
      */
     replica?: string;
+    /**
+     * @implements A-SPEC-649
+     * What the FIRST `requested` event of this id said about itself: the execution that asked
+     * (workspace/replica/run — absent for the CLI, hooks and legacy events), the digest of the subject
+     * the human will read (`spec-approve`: `specDigest` of the spec as read), and the risk grade. A
+     * grant minted from this entry copies `subject` so a seal of DIFFERENT content is refused — measured
+     * 2026-09-14: a grant read against "Original title" sealed "CHANGED after the grant".
+     */
+    execution?: ExecutionContext;
+    subject?: string;
+    risk?: string;
 }
 export interface QueueState {
     pending: PendingRequest[];
@@ -75,10 +87,24 @@ export interface QueueState {
      * An invisible decision cannot stop a retry loop.
      */
     decisions: Record<string, {
-        event: 'granted' | 'denied';
+        event: 'granted' | 'denied' | 'revoked';
         reason?: string;
         ts: string;
         covered?: number;
+        execution?: ExecutionContext;
+        consumedTs?: string;
+        expires?: string;
+        actor?: string;
+    }>;
+    /**
+     * @implements A-SPEC-650
+     * kind/target per request id, for EVERY `requested` event the fold saw (first wins) — the decision
+     * surface names what a past decision was about without re-reading the file. Present only when at
+     * least one request was seen, so the empty-state pins (A-SPEC-244) keep their exact shape.
+     */
+    subjects?: Record<string, {
+        kind: string;
+        target: string;
     }>;
     /**
      * @implements A-SPEC-563.2
@@ -89,6 +115,7 @@ export interface QueueState {
     holds: Record<string, {
         question?: string;
         ts: string;
+        execution?: ExecutionContext;
     }>;
 }
 /**
@@ -121,12 +148,17 @@ export declare function foldQueue(lines: string[], opts?: {
  * dead queue could change a verdict, killing the queue becomes a way to manipulate the gate. The
  * caller uses the boolean only to decide whether to print the review hint.
  */
+/** @implements A-SPEC-649 — what a request may say about its subject and risk, beyond kind/target/why. */
+export interface RequestDetails {
+    subject?: string;
+    risk?: string;
+}
 export declare function enqueueApprovalRequest(root: string, req: {
     kind: string;
     target: string;
     why: string;
     reasonBytes?: number;
-}): boolean;
+} & RequestDetails): boolean;
 /**
  * The same act, told in full: what happened and why.
  *
@@ -140,10 +172,17 @@ export declare function enqueueApprovalRequestDetailed(root: string, req: {
     target: string;
     why: string;
     reasonBytes?: number;
-}): {
+} & RequestDetails): {
     written: boolean;
     reason: 'written' | 'duplicate' | 'no-project' | 'unwritable';
 };
+/**
+ * @implements A-SPEC-649
+ * Append a lifecycle event (`consumed`, `revoked`) to the tracked queue: `.ax` must exist, the
+ * queue must be a plain file, the timestamp is this write's, and the active execution (if any) is
+ * attached — the same discipline as the CLI's decision writer. Fire-and-forget: `false` on failure.
+ */
+export declare function appendQueueEvent(root: string, event: Record<string, unknown>): boolean;
 /** Read and fold the queue on disk. A missing file is an empty queue, not an error. */
 export declare function readQueue(root: string, opts?: {
     now?: number;
@@ -160,6 +199,6 @@ export declare function queueHint(root: string, req: {
     kind: string;
     target: string;
     why: string;
-}, opts?: {
+} & RequestDetails, opts?: {
     baseReasonBytes?: number;
 }): string;