@holmes-lab/holmes-kit 0.19.6 → 0.20.1

package/dist/holmes/cli/doctor-check.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The doctor's verdict shape, in a module of its own.
+ *
+ * Measured 2026-09-16: `npx-cache-check.ts` imported `type Check` from `doctor.ts` while `doctor.ts`
+ * imported the check — an import cycle (A-SPEC-574.3), red on every POSIX run after the Windows
+ * merge. A check module must be able to name the shape it returns without importing the runner.
+ */
+export type Level = 'PASS' | 'WARN' | 'FAIL';
+export interface Check {
+    name: string;
+    level: Level;
+    detail: string;
+    fix?: string;
+    remediate?: () => boolean;
+}

package/dist/holmes/cli/doctor-check.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/holmes/cli/doctor.d.ts

@@ -11,14 +11,8 @@ export declare function resolvesToPackage(filePath: string, packageRoot: string)
  * hooks fail OPEN, so a broken install is silent: governance simply never fires. This command makes
  * that loud. Every check reports PASS/WARN/FAIL plus a concrete remediation.
  */
-export type Level = 'PASS' | 'WARN' | 'FAIL';
-export interface Check {
-    name: string;
-    level: Level;
-    detail: string;
-    fix?: string;
-    remediate?: () => boolean;
-}
+import type { Check, Level } from './doctor-check';
+export type { Check, Level } from './doctor-check';
 export interface DoctorOptions {
     run?: ProbeRunner;
     autoFix?: boolean;

package/dist/holmes/cli/doctor.js

@@ -64,6 +64,7 @@ const install_scripts_policy_1 = require("../project/install-scripts-policy");
 const native_deps_1 = require("./native-deps");
 const tier_1 = require("../semantic/tier");
 const probe_process_1 = require("./probe-process");
+const npx_cache_check_1 = require("./npx-cache-check");
 const path = __importStar(require("node:path"));
 const role_policy_1 = require("../governance/role-policy");
 const blind_spots_1 = require("../guardrail/blind-spots");
@@ -515,6 +516,11 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
     //    before it answers (a false FAIL this check produced on its first run).
     if (built) {
         checks.push(await mcpHandshakeCheck(packageRoot));
+        // @implements A-SPEC-652.2 — the handshake above proves THIS install; the wiring may run a
+        // cached npx copy instead, and a corrupt cache entry dies before any handshake (measured
+        // 2026-09-15: "Connection closed" at session start, npm ENOENT on the entry's package.json).
+        if (target)
+            checks.push((0, npx_cache_check_1.checkNpxCache)(target, { env: process.env, homedir: os.homedir(), platform: process.platform, exists: fs.existsSync, readFile: (p) => fs.readFileSync(p, 'utf8'), readdir: (p) => fs.readdirSync(p) }));
         // @implements A-SPEC-323
         // Every wired harness, actually started. The check above proves THIS INSTALL can serve; these
         // prove the wiring each harness will really run reaches a server. Measured: 367ms for three.
@@ -1340,9 +1346,11 @@ cwd) {
                 return;
             done = true;
             clearTimeout(timer);
-            void (0, probe_process_1.stopProbeProcess)(child).then(released => resolve(released
+            // @implements A-SPEC-651.2 — the platform the spawn was adapted for is the platform the cleanup
+            // is judged on, and an unconfirmed cleanup names its reason (timeout vs refusal vs no close).
+            void (0, probe_process_1.stopProbeProcess)(child, { platform }).then(released => resolve(released
                 ? { name: 'mcp wiring spawn', level, detail, fix }
-                : { name: 'mcp wiring spawn', level: 'FAIL', detail: `${detail}; probe cleanup could not be confirmed`,
+                : { name: 'mcp wiring spawn', level: 'FAIL', detail: `${detail}; probe cleanup could not be confirmed (${(0, probe_process_1.lastProbeStopReason)() ?? 'unknown'})`,
                     fix: `${fix ?? ''} Close the remaining diagnostic process for \`${command}\`, then retry doctor.` }));
         };
         const timer = setTimeout(() => finish('FAIL', `wiring did not answer initialize within ${timeoutMs / 1000}s: \`${quoted}\``, `Re-run \`holmes-kit init\` in the target to rewrite the wiring for \`${command}\`, then re-run doctor.`), timeoutMs);
@@ -1414,9 +1422,10 @@ function mcpHandshakeCheck(packageRoot, timeoutMs = 15000) {
                     removed = true;
                 }
                 catch { /* signal cleanup retains the path for a later attempt */ }
+                const why = !released ? ((0, probe_process_1.lastProbeStopReason)() ?? 'unknown') : 'temp dir not removed';
                 resolve(released && removed
                     ? { name: 'MCP server', level, detail, fix }
-                    : { name: 'MCP server', level: 'FAIL', detail: `${detail}; probe cleanup could not be confirmed`,
+                    : { name: 'MCP server', level: 'FAIL', detail: `${detail}; probe cleanup could not be confirmed (${why})`,
                         fix: 'Close the remaining diagnostic process and retry doctor.' });
             });
         };

package/dist/holmes/cli/gitignore-merge.d.ts

@@ -1,8 +1,3 @@
-/**
- * PURE .gitignore block merge. holmes-kit writes derived state under `.ax/` in the TARGET project
- * (ledger, cpg_cache, reports) that must never be committed. The block is delimited so it can be
- * added, refreshed, and removed exactly — never touching the user's own lines.
- */
 export declare const BEGIN = "# >>> holmes-kit >>>";
 export declare const END = "# <<< holmes-kit <<<";
 /** Derived/runtime paths holmes-kit creates in a target project. */

package/dist/holmes/cli/gitignore-merge.js

@@ -11,8 +11,9 @@ exports.hasGitignoreBlock = hasGitignoreBlock;
  * (ledger, cpg_cache, reports) that must never be committed. The block is delimited so it can be
  * added, refreshed, and removed exactly — never touching the user's own lines.
  */
-exports.BEGIN = '# >>> holmes-kit >>>';
-exports.END = '# <<< holmes-kit <<<';
+const installer_markers_1 = require("../project/installer-markers");
+exports.BEGIN = installer_markers_1.HOLMES_BLOCK_BEGIN; // A-SPEC-646 — the walk that must ignore this block reads the same definition
+exports.END = installer_markers_1.HOLMES_BLOCK_END;
 /** Derived/runtime paths holmes-kit creates in a target project. */
 exports.IGNORE_LINES = [
     // @implements A-SPEC-148
@@ -41,6 +42,9 @@ exports.IGNORE_LINES = [
     // the human saw" — round-14, exact match). Raw-and-local is the only shape that serves both ADR-012
     // and approvals: the file never leaves the machine, and `holmes-kit approve` reads it right there.
     '.ax/approvals/refusals*.jsonl',
+    // @implements A-SPEC-649 — a minted grant is LIVE AUTHORITY for one workspace; committed and
+    // pulled, it would open the same door in every clone (measured: a copied grant sealed elsewhere).
+    '.ax/approvals/grants/',
     // @implements A-SPEC-193 — 하네스 배선물은 이 **설치본의 절대 경로**를 담는다(훅은 hooks.json
     // 이 있는 디렉터리를 cwd 로 돌고, 패키지가 어디 설치됐는지는 기계마다 다르다). 그 경로가
     // VCS 에 들어가면 다른 기계에서 남의 설치를 부르거나 아무것도 부르지 못한다. 팀과 공유하고

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/npx-cache-check.d.ts

@@ -0,0 +1,16 @@
+import type { Check } from './doctor-check';
+export interface NpxCacheDeps {
+    env: NodeJS.ProcessEnv;
+    homedir: string;
+    platform: NodeJS.Platform;
+    exists: (p: string) => boolean;
+    readFile: (p: string) => string;
+    readdir: (p: string) => string[];
+}
+/** The `-p <pkg>@<ver>` pin of the target's holmes-kit wiring, or null when it is not an npx pin. */
+export declare function npxPinOf(target: string, deps: Pick<NpxCacheDeps, 'exists' | 'readFile'>): {
+    pkg: string;
+    version: string;
+} | null;
+export declare function npmCacheRoot(deps: Pick<NpxCacheDeps, 'env' | 'homedir' | 'platform'>): string;
+export declare function checkNpxCache(target: string, deps: NpxCacheDeps): Check;