@holmes-lab/holmes-kit 0.19.6 → 0.20.0

package/dist/holmes/cli/index.js

@@ -37,7 +37,8 @@ exports.isBrokenPipe = void 0;
 exports.packageRoot = packageRoot;
 exports.main = main;
 exports.installPipeGuard = installPipeGuard;
-// @implements A-SPEC-591
+// @implements A-SPEC-591, A-SPEC-626
+const cli_execution_1 = require("./cli-execution");
 // @implements A-SPEC-100.2
 // @implements A-SPEC-213
 // @implements A-SPEC-215
@@ -79,7 +80,7 @@ const KNOWN_FLAGS = {
     skills: ['help', 'target'],
     ci: ['help', 'target', 'specs-dir', 'json'],
     serve: ['help', 'target', 'port'],
-    approve: ['help', 'target', 'list', 'refusals', 'grant', 'deny', 'ask', 'reason', 'question', 'ttl', 'rationale', 'watch', 'poll-ms'],
+    approve: ['help', 'target', 'list', 'status', 'refusals', 'grant', 'deny', 'ask', 'revoke', 'reason', 'question', 'ttl', 'rationale', 'watch', 'poll-ms'], // A-SPEC-649: --revoke · A-SPEC-650: --status
     ledger: ['help', 'target', 'ref', 'dry-run'],
     // @implements A-SPEC-477 — the human's opt-in act for the cloud semantic tier.
     'semantic-key': ['help'],
@@ -101,10 +102,12 @@ const APPROVE_USAGE = `holmes-kit approve — decide pending approval requests (
   interactive (TTY):  per item [a] approve [e] approve with reason/duration [v] details [d] deny [q] ask [s] skip [A] approve all remaining
   --watch             resident mode — decide as requests arrive, wait when the queue is empty (Ctrl-C to exit, --poll-ms <ms>)
   --list              print the pending list only
+  --status            the whole picture: workspace, delegation, who asked and how risky, recent outcomes
   --grant <ref>       issue a narrow grant for that request (--ttl <minutes>, --rationale <text>)
                       ref = list number (1,2,…) | id | id prefix — no need to retype a long id
   --deny <id> --reason <text>     deny — the reason rides the agent's next refusal
   --ask <id> --question <text>    leave a question and hold — the agent relays it to the user
+  --revoke <id> --reason <text>   withdraw a live grant — the request must be decided again
   --target <dir>      project root (default: current directory)
 `;
 class UnknownFlagError extends Error {
@@ -115,7 +118,7 @@ class UnknownFlagError extends Error {
  * what you'd do" spelling performed a REAL write (round-3 HIGH; same class inverted --remove and
  * --force). A boolean flag must never consume a token.
  */
-const BOOLEAN_FLAGS = new Set(['help', 'dry-run', 'no-mcp', 'remove', 'force', 'json', 'list', 'watch', 'autonomy', 'no-autonomy']);
+const BOOLEAN_FLAGS = new Set(['help', 'dry-run', 'no-mcp', 'remove', 'force', 'json', 'list', 'status', 'watch', 'autonomy', 'no-autonomy']); // A-SPEC-650: --status
 function parseFlags(argv, known) {
     const flags = {};
     const positionals = [];
@@ -209,9 +212,11 @@ const USAGE = `holmes-kit — deterministic ASE governance for a project
   holmes-kit approve           review pending approval requests (HITL)
     (no flags, TTY)            interactive: [a]approve [e]approve-with-terms [v]details [d]deny [q]ask [s]skip [A]approve-all
     --list                     print the pending queue and exit
+    --status                   workspace · delegation · per-request risk/run/subject · recent outcomes
     --grant <ref> [--ttl <min>] [--rationale <text>]  mint the narrow grant for one request
     --deny <ref> --reason <text>                      record a denial the agent will see
     --ask <ref> --question <text>                     hold with a question the agent relays
+    --revoke <id> --reason <text>                     withdraw a live grant (full id or unique prefix)
     <ref>                      list index (1,2,…), full id, or a unique id prefix
     --target <dir>             project root (default: cwd)
 
@@ -331,13 +336,15 @@ async function main(argv) {
         const { runAutonomy } = await Promise.resolve().then(() => __importStar(require('./autonomy')));
         const root = path.resolve(typeof flags.target === 'string' ? flags.target : process.cwd());
         const forStr = typeof flags.for === 'string' ? flags.for : undefined;
-        const r = runAutonomy(root, positionals[0], forStr, {
-            now: new Date().toISOString(),
-            isTTY: !!process.stdin.isTTY && !!process.stdout.isTTY,
-            approval: readApproval(),
+        return (0, cli_execution_1.runOperatorExecution)(root, () => {
+            const r = runAutonomy(root, positionals[0], forStr, {
+                now: new Date().toISOString(),
+                isTTY: !!process.stdin.isTTY && !!process.stdout.isTTY,
+                approval: readApproval(),
+            });
+            process[r.ok ? 'stdout' : 'stderr'].write(`${r.message}\n`);
+            return r.exitCode;
         });
-        process[r.ok ? 'stdout' : 'stderr'].write(`${r.message}\n`);
-        return r.exitCode;
     }
     if (cmd === 'doctor') {
         // A nonexistent target read as "healthy but unwired" and both advised remedies then refused it
@@ -799,158 +806,188 @@ async function main(argv) {
             process.stdout.write(APPROVE_USAGE);
             return 0;
         }
-        if (typeof flags.grant === 'string') {
-            const opts = { actor };
-            if (typeof flags.ttl === 'string')
-                opts.ttlMinutes = Number(flags.ttl);
-            if (typeof flags.rationale === 'string')
-                opts.rationale = flags.rationale;
-            const ref = resolveRef(flags.grant);
-            if ('refusal' in ref) {
-                process.stdout.write(`\u2717 ${ref.refusal}\n`);
-                return 1;
+        return (0, cli_execution_1.runOperatorExecution)(root, async () => {
+            if (typeof flags.grant === 'string') {
+                const opts = { actor };
+                if (typeof flags.ttl === 'string')
+                    opts.ttlMinutes = Number(flags.ttl);
+                if (typeof flags.rationale === 'string')
+                    opts.rationale = flags.rationale;
+                const ref = resolveRef(flags.grant);
+                if ('refusal' in ref) {
+                    process.stdout.write(`\u2717 ${ref.refusal}\n`);
+                    return 1;
+                }
+                const r = grantRequest(root, ref.id, opts);
+                process.stdout.write(r.ok ? `✓ approved — ${ref.subject('✓ approved — ')}\n${ref.detail(`valid until ${r.expires}`)}\n` : `✗ ${r.reason}\n`);
+                return r.ok ? 0 : 1;
             }
-            const r = grantRequest(root, ref.id, opts);
-            process.stdout.write(r.ok ? `✓ approved — ${ref.subject('✓ approved — ')}\n${ref.detail(`valid until ${r.expires}`)}\n` : `✗ ${r.reason}\n`);
-            return r.ok ? 0 : 1;
-        }
-        if (typeof flags.deny === 'string') {
-            const reason = typeof flags.reason === 'string' ? flags.reason.trim() : '';
-            if (reason === '') {
-                process.stderr.write('✗ --deny requires --reason — a denial with no reason is invisible to the agent\n');
-                return 1;
+            if (typeof flags.deny === 'string') {
+                const reason = typeof flags.reason === 'string' ? flags.reason.trim() : '';
+                if (reason === '') {
+                    process.stderr.write('✗ --deny requires --reason — a denial with no reason is invisible to the agent\n');
+                    return 1;
+                }
+                const ref = resolveRef(flags.deny);
+                if ('refusal' in ref) {
+                    process.stdout.write(`\u2717 ${ref.refusal}\n`);
+                    return 1;
+                }
+                const r = denyRequest(root, ref.id, reason, actor);
+                process.stdout.write(r.ok ? `✓ denied — ${ref.subject('✓ denied — ')}\n${ref.detail('the denial was recorded')}\n` : `✗ ${r.reason}\n`);
+                return r.ok ? 0 : 1;
             }
-            const ref = resolveRef(flags.deny);
-            if ('refusal' in ref) {
-                process.stdout.write(`\u2717 ${ref.refusal}\n`);
-                return 1;
+            // @implements A-SPEC-649 — the operator withdraws a live grant. A granted id is no longer
+            // pending, so it resolves against the DECIDED ids (full id or a unique prefix), never a list index.
+            if (typeof flags.revoke === 'string') {
+                const reason = typeof flags.reason === 'string' ? flags.reason.trim() : '';
+                if (reason === '') {
+                    process.stderr.write('✗ --revoke requires --reason — a revocation with no reason is invisible to the agent\n');
+                    return 1;
+                }
+                const { revokeGrant } = require('./approve');
+                const ref = String(flags.revoke).trim();
+                const granted = Object.entries(readQueue(root, { includeAllKinds: true }).decisions).filter(([, d]) => d.event === 'granted').map(([id]) => id);
+                const matches = granted.includes(ref) ? [ref] : granted.filter((id) => id.startsWith(ref));
+                if (matches.length !== 1) {
+                    process.stdout.write(`\u2717 ${matches.length === 0 ? `no granted request matches ${ref}` : `${ref} matches ${matches.length} granted requests — use the full id`}\n`);
+                    return 1;
+                }
+                const r = revokeGrant(root, matches[0], reason, actor);
+                process.stdout.write(r.ok ? `✓ revoked — ${matches[0]}\n   the grant is withdrawn; the agent's next attempt is refused and re-filed\n` : `✗ ${r.reason}\n`);
+                return r.ok ? 0 : 1;
             }
-            const r = denyRequest(root, ref.id, reason, actor);
-            process.stdout.write(r.ok ? `✓ denied — ${ref.subject('✓ denied — ')}\n${ref.detail('the denial was recorded')}\n` : `✗ ${r.reason}\n`);
-            return r.ok ? 0 : 1;
-        }
-        if (typeof flags.ask === 'string') {
-            const question = typeof flags.question === 'string' ? flags.question.trim() : '';
-            if (question === '') {
-                process.stderr.write('✗ --ask requires --question\n');
-                return 1;
+            if (typeof flags.ask === 'string') {
+                const question = typeof flags.question === 'string' ? flags.question.trim() : '';
+                if (question === '') {
+                    process.stderr.write('✗ --ask requires --question\n');
+                    return 1;
+                }
+                const ref = resolveRef(flags.ask);
+                if ('refusal' in ref) {
+                    process.stdout.write(`\u2717 ${ref.refusal}\n`);
+                    return 1;
+                }
+                const r = holdRequest(root, ref.id, question, actor);
+                process.stdout.write(r.ok ? `✓ held — ${ref.subject('✓ held — ')}\n${ref.detail('the question rides the next refusal')}\n` : `✗ ${r.reason}\n`);
+                return r.ok ? 0 : 1;
             }
-            const ref = resolveRef(flags.ask);
-            if ('refusal' in ref) {
-                process.stdout.write(`\u2717 ${ref.refusal}\n`);
-                return 1;
+            // @implements A-SPEC-507.1 — stale folding is a LIST-VIEW judgment: the clock enters only
+            // here, never on gate-path folds. `--stale-hours 0` disables it; `--all` unfolds.
+            const { staleView } = require('./approve');
+            const stale = staleView(flags);
+            const queueOpts = stale ? { now: Date.now(), ttlMs: stale.ttlMs } : undefined;
+            const listView = stale ? { staleHours: stale.ttlMs / 3_600_000, showAll: stale.showAll } : undefined;
+            if (flags.list) {
+                process.stdout.write(renderPending(readQueue(root, queueOpts), listView) + '\n');
+                return 0;
             }
-            const r = holdRequest(root, ref.id, question, actor);
-            process.stdout.write(r.ok ? `✓ held — ${ref.subject('✓ held — ')}\n${ref.detail('the question rides the next refusal')}\n` : `✗ ${r.reason}\n`);
-            return r.ok ? 0 : 1;
-        }
-        // @implements A-SPEC-507.1 — stale folding is a LIST-VIEW judgment: the clock enters only
-        // here, never on gate-path folds. `--stale-hours 0` disables it; `--all` unfolds.
-        const { staleView } = require('./approve');
-        const stale = staleView(flags);
-        const queueOpts = stale ? { now: Date.now(), ttlMs: stale.ttlMs } : undefined;
-        const listView = stale ? { staleHours: stale.ttlMs / 3_600_000, showAll: stale.showAll } : undefined;
-        if (flags.list) {
-            process.stdout.write(renderPending(readQueue(root, queueOpts), listView) + '\n');
-            return 0;
-        }
-        // @implements A-SPEC-563.2 — the read-only refusal view (local log; raw targets stay on-screen).
-        if (flags.refusals !== undefined) {
-            const { renderRefusals } = require('./approve');
-            const { readRefusals } = require('../governance/approval-queue');
-            const limit = typeof flags.refusals === 'string' ? Number(flags.refusals) : 20;
-            if (!Number.isInteger(limit) || limit <= 0) {
-                process.stderr.write(`✗ --refusals expects a positive integer count — received: ${flags.refusals}\n`);
-                return 1;
+            // @implements A-SPEC-650 — the whole picture, read-only; the list above stays script-clean.
+            if (flags.status) {
+                const { renderStatus, statusContext } = require('./approve-status');
+                process.stdout.write(renderStatus(readQueue(root), statusContext(root)) + '\n');
+                return 0;
             }
-            process.stdout.write(renderRefusals(readRefusals(root), limit) + '\n');
-            return 0;
-        }
-        // @implements A-SPEC-262.2 — the RESIDENT surface. Validate --poll-ms first (so a bad value is
-        // named even on a non-TTY), then refuse a non-TTY (a resident interactive loop needs a terminal),
-        // then run the loop. SIGINT and readline close both abort it — the operator leaving, either way,
-        // ends the watch at once and exit 0; pending items stay in the queue.
-        if (flags.watch === true) {
-            let pollMs;
-            if (typeof flags['poll-ms'] === 'string') {
-                pollMs = Number(flags['poll-ms']);
-                if (!Number.isInteger(pollMs) || pollMs <= 0) {
-                    process.stderr.write(`✗ --poll-ms must be a positive integer (milliseconds) — received: ${flags['poll-ms']}\n`);
+            // @implements A-SPEC-563.2 — the read-only refusal view (local log; raw targets stay on-screen).
+            if (flags.refusals !== undefined) {
+                const { renderRefusals } = require('./approve');
+                const { readRefusals } = require('../governance/approval-queue');
+                const limit = typeof flags.refusals === 'string' ? Number(flags.refusals) : 20;
+                if (!Number.isInteger(limit) || limit <= 0) {
+                    process.stderr.write(`✗ --refusals expects a positive integer count — received: ${flags.refusals}\n`);
+                    return 1;
+                }
+                process.stdout.write(renderRefusals(readRefusals(root), limit) + '\n');
+                return 0;
+            }
+            // @implements A-SPEC-262.2 — the RESIDENT surface. Validate --poll-ms first (so a bad value is
+            // named even on a non-TTY), then refuse a non-TTY (a resident interactive loop needs a terminal),
+            // then run the loop. SIGINT and readline close both abort it — the operator leaving, either way,
+            // ends the watch at once and exit 0; pending items stay in the queue.
+            if (flags.watch === true) {
+                let pollMs;
+                if (typeof flags['poll-ms'] === 'string') {
+                    pollMs = Number(flags['poll-ms']);
+                    if (!Number.isInteger(pollMs) || pollMs <= 0) {
+                        process.stderr.write(`✗ --poll-ms must be a positive integer (milliseconds) — received: ${flags['poll-ms']}\n`);
+                        return 1;
+                    }
+                }
+                if (!process.stdin.isTTY) {
+                    process.stderr.write('✗ interactive resident mode (--watch) requires a TTY — use --list in scripts\n');
                     return 1;
                 }
+                // @implements A-SPEC-497.2 — the resident surface decides on ONE raw keypress (a/d/q/s, no
+                // Enter, no deadline) and pings the OS on each new arrival. Raw mode is restored on the way
+                // out whatever happens; Ctrl-C arrives as \x03 through decideByKey and ends the loop.
+                const { runWatch } = require('./approve-watch');
+                const { notifyQueueArrival } = require('./os-notify');
+                const ac = new AbortController();
+                const onSig = () => ac.abort();
+                process.once('SIGINT', onSig);
+                const stdin = process.stdin;
+                try {
+                    stdin.setRawMode?.(true);
+                    stdin.resume();
+                    await runWatch(root, {
+                        print: (t) => process.stdout.write(t + '\n'),
+                        ask: async () => '', // unused on the key surface; kept for the ApproveIO shape
+                    }, actor, {
+                        signal: ac.signal,
+                        keyStream: stdin,
+                        notify: (p) => notifyQueueArrival(p),
+                        // @implements A-SPEC-650 — the status header before each new-item pass.
+                        status: () => { const { renderStatus, statusContext } = require('./approve-status'); return renderStatus(readQueue(root), statusContext(root)); },
+                        ...(pollMs !== undefined ? { pollMs } : {}),
+                    });
+                }
+                catch (e) {
+                    if (e?.name !== 'AbortError')
+                        throw e;
+                }
+                finally {
+                    process.removeListener('SIGINT', onSig);
+                    stdin.setRawMode?.(false);
+                    stdin.pause();
+                }
+                return 0;
             }
+            // @implements A-SPEC-260 — the implicit non-TTY fallback tells the operator the next command,
+            // with the real pending id filled in; the explicit --list above stays script-clean.
             if (!process.stdin.isTTY) {
-                process.stderr.write('✗ interactive resident mode (--watch) requires a TTY — use --list in scripts\n');
-                return 1;
+                const state = readQueue(root, queueOpts);
+                const hint = renderNonTtyHint(state);
+                process.stdout.write(renderPending(state, listView) + (hint ? '\n\n' + hint : '') + '\n');
+                return 0;
             }
-            // @implements A-SPEC-497.2 — the resident surface decides on ONE raw keypress (a/d/q/s, no
-            // Enter, no deadline) and pings the OS on each new arrival. Raw mode is restored on the way
-            // out whatever happens; Ctrl-C arrives as \x03 through decideByKey and ends the loop.
-            const { runWatch } = require('./approve-watch');
-            const { notifyQueueArrival } = require('./os-notify');
+            // @implements A-SPEC-262.1
+            // AWAITED, not fire-and-forget. Measured 2026-08-25 against the shipped bin with a real pty: the
+            // prompt printed and the session ended with zero grants, because `void runInteractive(...)`
+            // returned 0 immediately and bin/holmes-kit.js turns that into `process.exit(0)` — killing the
+            // loop before the first keypress. The decision surface REQ-246 shipped had never run for a real
+            // operator; every test called `runInteractive` directly and so never crossed this seam.
+            const rl = require('node:readline/promises').createInterface({ input: process.stdin, output: process.stdout });
+            // EOF is the operator LEAVING (Ctrl-D, a closed pipe). Node leaves a pending `question`
+            // unsettled when the interface closes, so without this the awaited loop would hang the command
+            // forever — measured 2026-08-25, a pty probe hung for five minutes. The abort ends the session
+            // the way the operator asked: quietly, exit 0, nothing decided that was not decided.
             const ac = new AbortController();
-            const onSig = () => ac.abort();
-            process.once('SIGINT', onSig);
-            const stdin = process.stdin;
+            rl.once('close', () => ac.abort());
             try {
-                stdin.setRawMode?.(true);
-                stdin.resume();
-                await runWatch(root, {
+                await runInteractive(root, {
                     print: (t) => process.stdout.write(t + '\n'),
-                    ask: async () => '', // unused on the key surface; kept for the ApproveIO shape
-                }, actor, {
-                    signal: ac.signal,
-                    keyStream: stdin,
-                    notify: (p) => notifyQueueArrival(p),
-                    ...(pollMs !== undefined ? { pollMs } : {}),
-                });
+                    ask: (q) => rl.question(q, { signal: ac.signal }),
+                }, actor);
             }
             catch (e) {
                 if (e?.name !== 'AbortError')
                     throw e;
             }
             finally {
-                process.removeListener('SIGINT', onSig);
-                stdin.setRawMode?.(false);
-                stdin.pause();
+                rl.close();
             }
             return 0;
-        }
-        // @implements A-SPEC-260 — the implicit non-TTY fallback tells the operator the next command,
-        // with the real pending id filled in; the explicit --list above stays script-clean.
-        if (!process.stdin.isTTY) {
-            const state = readQueue(root, queueOpts);
-            const hint = renderNonTtyHint(state);
-            process.stdout.write(renderPending(state, listView) + (hint ? '\n\n' + hint : '') + '\n');
-            return 0;
-        }
-        // @implements A-SPEC-262.1
-        // AWAITED, not fire-and-forget. Measured 2026-08-25 against the shipped bin with a real pty: the
-        // prompt printed and the session ended with zero grants, because `void runInteractive(...)`
-        // returned 0 immediately and bin/holmes-kit.js turns that into `process.exit(0)` — killing the
-        // loop before the first keypress. The decision surface REQ-246 shipped had never run for a real
-        // operator; every test called `runInteractive` directly and so never crossed this seam.
-        const rl = require('node:readline/promises').createInterface({ input: process.stdin, output: process.stdout });
-        // EOF is the operator LEAVING (Ctrl-D, a closed pipe). Node leaves a pending `question`
-        // unsettled when the interface closes, so without this the awaited loop would hang the command
-        // forever — measured 2026-08-25, a pty probe hung for five minutes. The abort ends the session
-        // the way the operator asked: quietly, exit 0, nothing decided that was not decided.
-        const ac = new AbortController();
-        rl.once('close', () => ac.abort());
-        try {
-            await runInteractive(root, {
-                print: (t) => process.stdout.write(t + '\n'),
-                ask: (q) => rl.question(q, { signal: ac.signal }),
-            }, actor);
-        }
-        catch (e) {
-            if (e?.name !== 'AbortError')
-                throw e;
-        }
-        finally {
-            rl.close();
-        }
-        return 0;
+        });
     }
     if (cmd === 'serve') {
         if (typeof flags.target === 'string') {

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/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';