@holmes-lab/holmes-kit 0.1.0

package/dist/holmes/cli/doctor.js

@@ -0,0 +1,625 @@
+"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.STRIPPED_FOR_PROBE = void 0;
+exports.probeEnv = probeEnv;
+exports.runDoctor = runDoctor;
+exports.formatChecks = formatChecks;
+// @implements A-SPEC-100.2
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const role_policy_1 = require("../governance/role-policy");
+const blind_spots_1 = require("../guardrail/blind-spots");
+const node_child_process_1 = require("node:child_process");
+const os = __importStar(require("node:os"));
+const settings_merge_1 = require("./settings-merge");
+const playbook_skills_1 = require("./playbook-skills");
+const init_1 = require("./init");
+const GRAMMARS = [
+    'tree-sitter-typescript', 'tree-sitter-python', 'tree-sitter-c-sharp', 'tree-sitter-java',
+    'tree-sitter-go', 'tree-sitter-rust', 'tree-sitter-cpp',
+];
+/**
+ * Environment variables removed before spawning a probe.
+ *
+ * @implements A-SPEC-143
+ * `HOLMES_APPROVAL` grants permission, so a probe that inherits one measures the GRANT rather than
+ * the gate. `HOLMES_SPECS` redirects the spec root, so a probe reading another project's specs
+ * answers a different question than the one asked. `HOLMES_LEDGER_KEY` is deliberately NOT here: it
+ * changes how the ledger is signed, not whether the gate enforces, and stripping it could mask a
+ * real key-related failure.
+ */
+exports.STRIPPED_FOR_PROBE = ['HOLMES_APPROVAL', 'HOLMES_SPECS'];
+/** The parent environment minus the variables that legitimately change a gate decision. Pure. */
+function probeEnv(parent) {
+    const out = { ...parent };
+    for (const k of exports.STRIPPED_FOR_PROBE)
+        delete out[k];
+    return out;
+}
+/**
+ * The settings file this target is actually wired through.
+ *
+ * @implements A-SPEC-190 §14 (round 12) — round 11 replaced a hardcoded `settings.local.json` with
+ * "local if that file EXISTS", which is a different wrong answer: Claude Code writes its own
+ * `settings.local.json` for unrelated reasons, and the moment it appears a target wired with
+ * `--settings project` is declared unwired again — with the sibling `hook matcher` check, reading
+ * the same way, reporting PASS. Presence is not wiring. Ask which file carries holmes commands, and
+ * fall back to the layout only when neither does.
+ */
+function wiredSettingsPath(target) {
+    const carries = (which) => {
+        try {
+            const s = JSON.parse(fs.readFileSync((0, init_1.settingsPathOf)(target, which), 'utf8'));
+            return Object.values(s.hooks ?? {}).some((groups) => (groups ?? []).some((g) => (g.hooks ?? []).some((h) => (0, settings_merge_1.isHolmesCommand)(h.command))));
+        }
+        catch {
+            return false;
+        }
+    };
+    if (carries('local'))
+        return (0, init_1.settingsPathOf)(target, 'local');
+    if (carries('project'))
+        return (0, init_1.settingsPathOf)(target, 'project');
+    return (0, init_1.settingsPathOf)(target, fs.existsSync((0, init_1.settingsPathOf)(target, 'local')) ? 'local' : 'project');
+}
+async function runDoctor(packageRoot, target, opts) {
+    const checks = [];
+    const add = (name, level, detail, fix) => checks.push({ name, level, detail, fix });
+    // 1. Build output — also the "prepare didn't run" detector.
+    const serverJs = path.join(packageRoot, 'dist', 'holmes', 'mcp', 'server.js');
+    const hookJs = path.join(packageRoot, 'dist', 'holmes', 'hooks', 'pre-tool-use.js');
+    const stopJs = path.join(packageRoot, 'dist', 'holmes', 'hooks', 'stop.js');
+    const built = fs.existsSync(serverJs) && fs.existsSync(hookJs) && fs.existsSync(stopJs);
+    add('build output', built ? 'PASS' : 'FAIL', built ? `compiled output present under ${path.join(packageRoot, 'dist')}` : `missing ${serverJs}`, 
+    // @implements A-SPEC-190 §16 (round 12) — the old remedy named a `prepare` script package.json
+    // never declared (build/mcp/release/test/typecheck only); dist/ ships because `files` lists it.
+    built ? undefined : '이 패키지는 컴파일된 dist/ 를 함께 배포합니다 — 저장소에서 쓰는 중이라면 `npm run build`, 설치본이라면 재설치하십시오.');
+    // 2. Node version vs better-sqlite3's declared range (WARN only — a mismatch still often works).
+    let sqliteRange = '(unknown)';
+    try {
+        sqliteRange = JSON.parse(fs.readFileSync(path.join(packageRoot, 'node_modules', 'better-sqlite3', 'package.json'), 'utf8')).engines?.node ?? '(none)';
+    }
+    catch { /* not resolvable from here */ }
+    add('node version', 'PASS', `node ${process.version}; better-sqlite3 declares engines.node=${sqliteRange}`, 'If a native module fails to load after a Node major upgrade, reinstall holmes-kit.');
+    // 3. tree-sitter + EACH grammar. language-parser.ts require.resolve's all of them at module scope,
+    //    so ONE missing grammar kills MCP server startup entirely — report them individually.
+    try {
+        require('tree-sitter');
+        const missing = GRAMMARS.filter((g) => { try {
+            require.resolve(g);
+            return false;
+        }
+        catch {
+            return true;
+        } });
+        if (missing.length === 0)
+            add('tree-sitter grammars', 'PASS', `tree-sitter + ${GRAMMARS.length} grammars resolve`);
+        else
+            add('tree-sitter grammars', 'FAIL', `missing: ${missing.join(', ')}`, 'A single missing grammar prevents the MCP server from starting. Reinstall; if a native build failed, ensure a C++ toolchain is available.');
+    }
+    catch (e) {
+        add('tree-sitter grammars', 'FAIL', `tree-sitter failed to load: ${e.message}`, 'Native module build failed. Install Xcode Command Line Tools (macOS) or build-essential, then reinstall.');
+    }
+    // 4. better-sqlite3 — ABI-locked (not N-API), the most fragile dependency.
+    try {
+        const Database = require('better-sqlite3');
+        const db = new Database(':memory:');
+        db.prepare('SELECT 1 AS ok').get();
+        db.close();
+        add('better-sqlite3', 'PASS', 'loads and executes against :memory:');
+    }
+    catch (e) {
+        add('better-sqlite3', 'FAIL', e.message, 'better-sqlite3 is ABI-locked to the Node version. Reinstall holmes-kit after any Node major change; a source build needs a C++ toolchain.');
+    }
+    // 5. Hooks actually gate — prove it with a live allow AND a live deny (exit 2).
+    if (built) {
+        // @implements A-SPEC-143
+        // HERMETIC. The probe asks "does this INSTALLATION enforce?", so it must not inherit variables
+        // that legitimately change a gate decision. Measured on a real tarball install: with a valid
+        // HOLMES_APPROVAL exported — the very thing `init` prints as the way to run governed mode — the
+        // catastrophic command was correctly ALLOWED, and this check read that as "the guardrail is not
+        // enforcing" and told the operator to reinstall a working install.
+        const env = probeEnv(process.env);
+        // @implements A-SPEC-143
+        // Injectable so the WIRING is verified deterministically. Calling the real spawn from a unit test
+        // made it load-sensitive — measured, it failed roughly 1 full-suite run in 8 by exceeding the
+        // 20s timeout, and a verification harness whose green is probabilistic is not verification.
+        // The realistic path stays covered by the external check (pack → install → doctor).
+        const runner = opts?.run ?? ((script, payload, childEnv) => 
+        // ISOLATED cwd (round-5 HIGH): the probed hooks write REAL governance state relative to
+        // their cwd — every doctor run appended a synthetic 'rm -rf /' gate-deny to the PROJECT's
+        // tamper-evident ledger (measured: 8,393 forged entries) and minted .ax state in empty dirs.
+        // A probe must observe the gate, never feed its audit trail.
+        (() => {
+            const probeCwd = fs.mkdtempSync(path.join(os.tmpdir(), 'holmes-doctor-probe-'));
+            cleanupOnSignal(probeCwd); // round-9: 인터럽트 사망에서도 남지 않는다
+            try {
+                return (0, node_child_process_1.spawnSync)(process.execPath, [script], { input: JSON.stringify(payload), encoding: 'utf8', timeout: 20000, env: childEnv, cwd: probeCwd });
+            }
+            finally {
+                // The probe minted synthetic gate state in there — leaving it accumulated 1,665 dirs on
+                // one machine (round-6), each holding a forged gate-deny ledger.
+                try {
+                    fs.rmSync(probeCwd, { recursive: true, force: true });
+                }
+                catch { /* tmp cleaner's job */ }
+            }
+        })());
+        const run = (script, payload) => runner(script, payload, env);
+        const allow = run(hookJs, { tool_name: 'Bash', tool_input: { command: 'ls' } });
+        const denyCmd = ['rm', '-rf', '/'].join(' ');
+        const deny = run(hookJs, { tool_name: 'Bash', tool_input: { command: denyCmd } });
+        const ok = allow.status === 0 && deny.status === 2 && /\[Holmes-Kit\]/.test(`${deny.stderr ?? ''}${deny.stdout ?? ''}`);
+        // Say so when we excluded something the operator deliberately set: a diagnostic that silently
+        // disagrees with someone's mental model is how a correct answer still gets distrusted.
+        const excluded = exports.STRIPPED_FOR_PROBE.filter((k) => process.env[k] !== undefined);
+        const note = excluded.length ? ` (probe excluded ${excluded.join(', ')} — an approval legitimately allows what this check expects denied)` : '';
+        add('PreToolUse gate', ok ? 'PASS' : 'FAIL', ok ? `allows a benign command; denies a catastrophic delete (exit 2)${note}` : `allow exit=${allow.status}, deny exit=${deny.status}${note}`, ok ? undefined : 'The guardrail is not enforcing. Re-check the build output and reinstall.');
+        const stop = run(stopJs, { session_id: 'doctor' });
+        add('Stop gate', stop.status === 0 ? 'PASS' : 'WARN', `exit=${stop.status}${stop.stderr ? ` — ${String(stop.stderr).slice(0, 160)}` : ''}`);
+    }
+    // 6. MCP server handshake — initialize, THEN tools/list. This must be async: the protocol is a
+    //    round-trip, and a spawnSync that writes everything and closes stdin makes the server exit
+    //    before it answers (a false FAIL this check produced on its first run).
+    if (built) {
+        checks.push(await mcpHandshakeCheck(packageRoot));
+    }
+    // 7. Target wiring — do the configured commands point at THIS installed package and exist?
+    if (target) {
+        // @implements A-SPEC-190 §13 (round 11) — `init --settings project` wires `.claude/settings.json`,
+        // and this check read only `settings.local.json`: a correctly wired target got WARN plus "Run
+        // `holmes-kit init` in the target", while the `hook matcher` check ten lines below — asking the
+        // same file the same way through `settingsPathOf` — reported PASS. One diagnosis contradicting
+        // itself is worse than either verdict alone, because the remedy it prints re-runs a completed
+        // install. Both checks now read the file the target actually uses.
+        const sp = wiredSettingsPath(target);
+        try {
+            const settings = JSON.parse(fs.readFileSync(sp, 'utf8'));
+            const cmds = [];
+            for (const groups of Object.values(settings.hooks ?? {})) {
+                for (const g of groups ?? [])
+                    for (const h of g.hooks ?? [])
+                        if ((0, settings_merge_1.isHolmesCommand)(h.command))
+                            cmds.push(h.command);
+            }
+            if (cmds.length === 0)
+                add('target wiring', 'WARN', `no holmes hooks found in ${sp}`, 'Run `holmes-kit init` in the target.');
+            else {
+                const stale = cmds.filter((c) => {
+                    const p = (0, settings_merge_1.hookScriptPath)(c);
+                    return !p || !fs.existsSync(p) || !path.resolve(p).startsWith(path.resolve(packageRoot) + path.sep);
+                });
+                add('target wiring', stale.length === 0 ? 'PASS' : 'FAIL', stale.length === 0 ? `${cmds.length} holmes hook(s) resolve to this install` : `stale/foreign command(s): ${stale.join(' | ')}`, stale.length === 0 ? undefined : 'Re-run `holmes-kit init --force` in the target to refresh the absolute paths.');
+            }
+        }
+        catch {
+            add('target wiring', 'WARN', `could not read ${sp}`, 'Run `holmes-kit init` in the target.');
+        }
+    }
+    // @implements A-SPEC-142
+    // Recovery layer. WARN and never FAIL: no gate decision reads a playbook, so their absence changes
+    // no enforcement — and a check that FAILs on something harmless trains an operator to ignore
+    // doctor output, which is how the checks that DO matter stop being read.
+    if (target) {
+        // @implements A-SPEC-190
+        // Judged by CONTENT, not count: an installed skill whose bytes differ from what install would
+        // write today still counted as installed, so a target teaching abolished conventions reported
+        // "3 of 3 … PASS" (measured in this repository — all three had drifted). Foreign files break
+        // the all-current PASS too (the count check never counted them either), but the wording keeps
+        // ownership distinct and never promises that init will fix what init deliberately skips.
+        const skillsDir = path.join(target, '.claude', 'skills');
+        const states = (0, playbook_skills_1.playbookSkillStates)(packageRoot, target);
+        const of = (s) => states.filter((x) => x.state === s).map((x) => (0, playbook_skills_1.invocableSkillName)(x.name));
+        // Orphan rows already carry the RAW directory name (round-6: re-prefixing a case-variant
+        // produced the CURRENT skill's name in a delete instruction).
+        const orphaned = states.filter((x) => x.state === 'orphaned').map((x) => x.name);
+        const [drifted, missing, foreign] = [of('drifted'), of('missing'), of('foreign')];
+        // @implements A-SPEC-190 (round 7) — the PACKAGE's own damage, distinguished from the target's:
+        // an unreadable shipped playbook used to disappear from this report entirely.
+        const sourceUnreadable = of('source-unreadable');
+        const aliased = of('aliased');
+        // Counted EXPLICITLY, not by subtraction: a future fifth state must land in the WARN branch,
+        // not silently pass as current (round-1 finding).
+        const current = states.filter((x) => x.state === 'current').length;
+        if (states.length === 0) {
+            // No playbooks shipped. The first number stays TRUE to the target — a hardcoded "0 of 0"
+            // lied about targets that still hold installed skills (round-1 finding).
+            // round-8: the first number came from installedPlaybookCount, which counts marker-owned
+            // installs of SHIPPED names — provably 0 whenever nothing is shipped. It read as data.
+            add('recovery skills', 'WARN', `this package ships no playbooks; nothing to compare under ${skillsDir}`, 
+            // No playbooks shipped means the PACKAGE is broken — init/refresh would install nothing
+            // (round-3: the old init hint was both a refusal loop on wired targets and a no-op here).
+            'This holmes-kit package ships no playbooks — reinstall or upgrade holmes-kit itself.');
+        }
+        else if (current === states.length) {
+            add('recovery skills', 'PASS', `${states.length} recovery skill(s) current under ${skillsDir}`);
+        }
+        else {
+            const KNOWN_STATES = new Set(['current', 'drifted', 'missing', 'foreign', 'orphaned', 'source-unreadable', 'aliased']);
+            const unknown = states.filter((x) => !KNOWN_STATES.has(x.state)).map((x) => `${(0, playbook_skills_1.invocableSkillName)(x.name)} (${x.state})`);
+            const parts = [
+                drifted.length ? `drifted: ${drifted.join(', ')}` : '',
+                missing.length ? `missing: ${missing.join(', ')}` : '',
+                foreign.length ? `not provably ours (untouched): ${foreign.join(', ')}` : '',
+                orphaned.length ? `orphaned (no longer shipped): ${orphaned.join(', ')}` : '',
+                sourceUnreadable.length ? `unreadable in this package: ${sourceUnreadable.join(', ')}` : '',
+                aliased.length ? `two skills resolve to one file: ${aliased.join(', ')}` : '',
+                // A state this doctor does not know still NAMES the skill — a dangling separator and an
+                // empty fix threw away the one fact the operator needed (round-3).
+                unknown.length ? `unrecognized state: ${unknown.join(', ')}` : '',
+            ].filter(Boolean).join('; ');
+            // The remedy must actually WORK: `init --target` on a wired target exits 2 (self-disarm
+            // guard) and --force demands governance approval — a refusal loop for three advisory files
+            // (round-1 HIGH). `skills refresh` touches only marker-owned skills, never wiring.
+            const fixes = [
+                drifted.length + missing.length > 0
+                    ? `Run \`holmes-kit skills refresh --target ${target}\` to refresh the skills holmes-kit owns.` : '',
+                foreign.length > 0 && drifted.length + missing.length === 0
+                    ? `A file holmes-kit cannot prove it owns occupies it (no readable marker); holmes-kit leaves it untouched — if it is not yours, restore permissions or remove it and re-run \`holmes-kit skills refresh --target ${target}\`.` : '',
+                orphaned.length > 0
+                    ? 'holmes-kit no longer ships it; delete the directory if you no longer want it.' : '',
+                sourceUnreadable.length > 0
+                    ? 'holmes-kit cannot read its own shipped playbook — reinstall or upgrade holmes-kit itself; `skills refresh` will fail on the same file.' : '',
+                aliased.length > 0
+                    ? 'A link makes two skill files the same file; refresh refuses rather than let one body overwrite the other — remove the link, then refresh.' : '',
+                unknown.length > 0
+                    ? 'A state this doctor does not recognize — upgrade holmes-kit so doctor and skills agree.' : '',
+            ].filter(Boolean).join(' ');
+            add('recovery skills', 'WARN', `${current} of ${states.length} recovery skill(s) current under ${skillsDir} — ${parts}`, fixes);
+        }
+    }
+    else {
+        // @implements A-SPEC-190 (round 7) — without --target this check simply did not appear, so the
+        // whole drift report was invisible to the operator who typed the shorter command and read a
+        // clean doctor as 'my recovery layer is fine'. Absence of a check is now itself reported.
+        add('recovery skills', 'WARN', 'not checked — this check is per-project and needs a target', `Run \`holmes-kit doctor --target ${process.cwd()}\` (or another project) to see recovery-skill drift.`);
+    }
+    // 8. Environment — presence only, never values (these hold out-of-band secrets).
+    const present = ['HOLMES_SPECS', 'HOLMES_APPROVAL', 'HOLMES_LEDGER_KEY', 'HOLMES_MCP_PROFILE']
+        .map((k) => `${k}=${process.env[k] ? 'set' : 'unset'}`).join(' ');
+    // @implements A-SPEC-153
+    // Reports, never judges. Not having roles on is a choice, not a defect; a FAIL here would teach
+    // operators that doctor's failures are noise, which costs more than this check is worth.
+    if (target) {
+        const rs = (0, role_policy_1.rolePolicyStatus)(target);
+        add('role policy', 'PASS', rs.state === 'absent' ? 'not configured (optional)'
+            : rs.state === 'inactive' ? 'guidance present, no policy — roles are off (see .ax/roles/README.md)'
+                : `active — ${rs.roles.length} role(s): ${rs.roles.join(', ')}; default=${rs.default ?? '(none — unspecified is refused)'}`);
+    }
+    // @implements A-SPEC-165
+    // The boundary, told to the user rather than left in a document nobody opens. PASS, not FAIL: a
+    // limit is not a defect, and marking harmless facts as failures teaches operators to skip doctor
+    // entirely — the judgement REQ-153 already made for the role-policy report.
+    // @implements A-SPEC-168
+    // Existing children under unapproved parents are NOT violations — the obligation is on the act of
+    // approving, so this repo does not brick. But they must stay visible: what nobody can see, nobody
+    // fixes, and the state becomes permanent.
+    if (target) {
+        try {
+            const { LocalMarkdownRepository } = require('../spec/spec-store');
+            const all = await new LocalMarkdownRepository(path.join(target, '.ax', 'specs')).list();
+            const byId = new Map(all.map((s) => [s.id, s]));
+            const orphaned = all.filter((s) => s.status === 'approved'
+                && (s.dependsOn ?? []).some((p) => byId.get(p) && byId.get(p).status !== 'approved'));
+            // @implements A-SPEC-177
+            // Measured 2026-08-12: a duplicated id flips an anchored write to deny — correctly, the gate
+            // takes the unapproved side either way, so there is no forgery route. But the refusal says the
+            // spec "is not approved" while the author is looking at a file that says it is, and `spec chain`
+            // answered PASS. `rtm_check` reported it; nothing the author was looking at did.
+            // The detection is QUOTED, not re-implemented: two answers to "is this a duplicate" drift, and
+            // on the day they disagree the user cannot tell which tool to believe.
+            const { rtmCheck } = require('../rtm/rtm-check');
+            const dups = rtmCheck(all).filter((i) => i.kind === 'duplicate-id');
+            add('duplicate spec ids', dups.length === 0 ? 'PASS' : 'WARN', dups.length === 0
+                ? '같은 id를 가진 스펙 파일이 없습니다'
+                : `같은 id의 스펙 파일이 둘 이상: ${dups.map((d) => d.id).join(', ')}`, dups.length === 0 ? undefined
+                : '게이트는 승인되지 않은 쪽으로 판정합니다 — 남길 파일 하나만 두고 사본을 지우세요.');
+            add('spec chain', 'PASS', orphaned.length === 0
+                ? '승인된 스펙의 상위가 모두 approved입니다'
+                : `상위가 approved가 아닌 승인 스펙 ${orphaned.length}건: ${orphaned.map((s) => s.id).slice(0, 5).join(', ')}`);
+        }
+        catch { /* an unreadable corpus is doctor's other checks' business, not this one's */ }
+    }
+    // @implements A-SPEC-176
+    // `list()` drops any file it cannot parse, which is correct for a gate but leaves the author
+    // reading "that spec does not exist" while looking at it — measured with a CRLF-saved A-SPEC, whose
+    // approved anchor then denied every write. WARN, not FAIL: this changes no enforcement, and a FAIL
+    // on something that changes nothing teaches an operator to stop reading doctor at all.
+    if (target) {
+        const { unreadableSpecFiles } = require('../spec/spec-store');
+        const unreadable = unreadableSpecFiles(path.join(target, '.ax', 'specs'));
+        add('spec readability', unreadable.length === 0 ? 'PASS' : 'WARN', unreadable.length === 0
+            ? '스펙 디렉터리의 모든 .md가 파싱됩니다'
+            : `파싱되지 않아 스펙으로 취급되지 않는 파일 ${unreadable.length}건: ${unreadable.slice(0, 5).join(', ')}`, unreadable.length === 0 ? undefined : '해당 파일의 프론트매터를 확인하세요 — 존재하지만 게이트에는 보이지 않습니다.');
+    }
+    // @implements A-SPEC-178
+    // Two checks that report the wiring a USER will meet, not what this process happens to see.
+    //
+    // Measured 2026-08-13 in holmes-kit's own workspace: `environment` said `HOLMES_APPROVAL=set`
+    // (true of doctor's process) while `spec_approve` over MCP refused fail-closed, because the
+    // variable lives in `.claude/settings.local.json` and the server is spawned from `.mcp.json`.
+    // And `target wiring` said PASS while the matcher was `Bash|Write|Edit` against a shipped default
+    // of `.*` — the matcher decides whether the hook is CALLED, so a tool whose name does not match
+    // never reaches the correct decision inside it.
+    //
+    // Deliberately NOT probed by spawning a server: that child would inherit doctor's environment and
+    // answer "reachable" no matter what Claude Code does. An inference dressed as a measurement is the
+    // defect being fixed; a better-looking one is not the cure. Only decidable facts are stated.
+    if (target) {
+        let mcpApproval = false;
+        try {
+            const raw = fs.readFileSync(path.join(target, '.mcp.json'), 'utf8');
+            const env = JSON.parse(raw)
+                .mcpServers?.[init_1.SERVER_NAME]?.env;
+            mcpApproval = !!env && 'HOLMES_APPROVAL' in env;
+        }
+        catch {
+            mcpApproval = false;
+        } // absent or unreadable is "not guaranteed", which is the point
+        const procApproval = !!process.env.HOLMES_APPROVAL;
+        if (mcpApproval) {
+            add('approval channel', 'PASS', '승인 변수가 .mcp.json의 서버 환경에 있습니다 — spec_approve가 도달합니다');
+        }
+        else if (!procApproval) {
+            // A project that has not started approving is healthy. Warning here would put a permanent line
+            // on every install, and a line that is always there is one nobody reads (REQ-153's judgement).
+            add('approval channel', 'PASS', '승인 변수가 설정되어 있지 않습니다 — 승인이 필요할 때 설정하세요');
+        }
+        else {
+            add('approval channel', 'WARN', '이 프로세스에는 HOLMES_APPROVAL이 있으나 .mcp.json의 서버 환경에는 없습니다 — spec_approve는 서버 환경을 읽습니다', 'settings.local.json의 env가 MCP 서버까지 전달된다는 보장은 없습니다. 그 변수를 설정한 셸에서 Claude Code를 띄우면 자식 서버가 상속합니다.');
+        }
+        // @implements A-SPEC-193 — 배선된 하네스마다 그 하네스의 배선을 검사한다. 배선되지 않은
+        // 하네스는 진단하지 않는다(없는 것을 결함이라 부르면 doctor 가 소음이 된다).
+        const agyHooks = path.join(target, '.agents', 'hooks.json');
+        if (fs.existsSync(agyHooks)) {
+            try {
+                const h = JSON.parse(fs.readFileSync(agyHooks, 'utf8'));
+                const entry = h['holmes-kit'];
+                const pre = entry?.PreToolUse?.[0];
+                const preCmd = pre?.hooks?.[0]?.command ?? '';
+                const stopCmd = entry?.Stop?.[0]?.command ?? '';
+                const stale = [preCmd, stopCmd].filter((c) => {
+                    const p2 = (0, settings_merge_1.hookScriptPath)(c);
+                    return !p2 || !fs.existsSync(p2) || !path.resolve(p2).startsWith(path.resolve(packageRoot) + path.sep);
+                });
+                if (entry === undefined) {
+                    add('antigravity wiring', 'WARN', `${agyHooks} 에 holmes-kit 항목이 없습니다`, 'holmes-kit init --target <dir> --agent antigravity');
+                }
+                else if (stale.length > 0) {
+                    add('antigravity wiring', 'FAIL', `이 설치본을 가리키지 않는 명령: ${stale.join(' | ')}`, 'holmes-kit init --target <dir> --agent antigravity --force 로 절대 경로를 갱신하십시오.');
+                }
+                else if ((pre?.matcher ?? '') !== '*') {
+                    // 매처가 좁으면 그 밖의 도구가 게이트를 지나간다 — 조용한 구멍이므로 말한다.
+                    add('antigravity wiring', 'WARN', `PreToolUse 매처가 '${pre?.matcher ?? ''}' 입니다 — '*' 가 아니면 그 밖의 도구는 게이트에 닿지 않습니다`, "matcher 를 '*' 로 되돌리십시오.");
+                }
+                else {
+                    add('antigravity wiring', 'PASS', 'PreToolUse·Stop 이 이 설치본을 가리킵니다');
+                }
+            }
+            catch {
+                add('antigravity wiring', 'FAIL', `${agyHooks} 를 읽을 수 없습니다(JSON 아님)`, '파일을 고치거나 지우고 다시 배선하십시오.');
+            }
+            // 스킬이 그 하네스에 보이는가 — 링크가 끊기면 스킬은 조용히 사라진다.
+            const agySkills = path.join(target, '.agents', 'skills');
+            add('antigravity skills', fs.existsSync(agySkills) ? 'PASS' : 'WARN', fs.existsSync(agySkills) ? `${agySkills} 가 스킬을 가리킵니다` : `${agySkills} 가 없습니다 — 이 하네스는 스킬을 보지 못합니다`, fs.existsSync(agySkills) ? undefined : `${path.join('..', '.claude', 'skills')} 로 링크하거나 복사하십시오.`);
+        }
+        try {
+            const sp = wiredSettingsPath(target);
+            const st = JSON.parse(fs.readFileSync(sp, 'utf8'));
+            const wired = (st.hooks?.PreToolUse ?? [])
+                .filter((g) => (g.hooks ?? []).some((h) => (0, settings_merge_1.isHolmesCommand)(h.command ?? '')))
+                .map((g) => g.matcher ?? '');
+            const drifted = wired.filter((m) => m !== init_1.MATCHERS.guardrail);
+            add('hook matcher', drifted.length === 0 ? 'PASS' : 'WARN', drifted.length === 0
+                ? `배선된 매처가 출하 기본값과 같습니다 (${init_1.MATCHERS.guardrail})`
+                : `배선 ${drifted.join(' | ')} / 출하 기본값 ${init_1.MATCHERS.guardrail} — 매처에 걸리지 않는 도구는 훅에 도달하지 않습니다`, drifted.length === 0 ? undefined : 'holmes-kit init --target <dir> --force 로 갱신하고 Claude Code를 재시작하세요.');
+        }
+        catch { /* an unreadable settings file is `target wiring`'s business, not this check's */ }
+    }
+    add('gate blind spots', 'PASS', (0, blind_spots_1.blindSpotSummary)());
+    add('environment', 'PASS', present);
+    return checks;
+}
+/**
+ * @implements A-SPEC-192 (round 9)
+ * Temp cwds doctor creates must not outlive doctor, including on Ctrl-C. `finish()` is unreachable
+ * on signal death, so an interrupted run stranded one directory per run — measured 14 of 14
+ * interrupted runs, at BOTH mkdtemp sites (the gate probe's and the handshake's).
+ */
+const DOCTOR_TEMP_DIRS = new Set();
+let signalHooked = false;
+function cleanupOnSignal(dir) {
+    DOCTOR_TEMP_DIRS.add(dir);
+    if (signalHooked)
+        return;
+    signalHooked = true;
+    const sweep = () => {
+        for (const d of DOCTOR_TEMP_DIRS) {
+            try {
+                fs.rmSync(d, { recursive: true, force: true });
+            }
+            catch { /* tmp cleaner's job */ }
+        }
+        DOCTOR_TEMP_DIRS.clear();
+    };
+    process.on('exit', sweep);
+    for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+        process.on(sig, () => { sweep(); process.exit(130); });
+    }
+}
+/**
+ * Drive a real MCP stdio handshake: initialize -> initialized -> tools/list, with a timeout.
+ * Async by necessity — the protocol is a ROUND TRIP, so a spawnSync that writes everything at once
+ * and closes stdin makes the server exit before answering (a false FAIL this check produced on its
+ * very first run against a healthy server).
+ */
+function mcpHandshakeCheck(packageRoot, timeoutMs = 15000) {
+    return new Promise((resolve) => {
+        const mcpCwd = fs.mkdtempSync(path.join(os.tmpdir(), 'holmes-doctor-mcp-'));
+        const child = (0, node_child_process_1.spawn)(process.execPath, [path.join(packageRoot, 'bin', 'holmes-mcp.js')], { stdio: ['pipe', 'pipe', 'pipe'], cwd: mcpCwd });
+        let pending = ''; // the unterminated tail of the stdout stream, never the whole history
+        let err = '';
+        let done = false;
+        let initialized = false; // LATCH (round-9): the second leg was re-sent once per stdout CHUNK,
+        // because the trigger tested the CUMULATIVE buffer. A strict server
+        // answered the duplicate tools/list with an error and doctor reported
+        // FAIL — with 'reinstall' guidance — on a perfectly healthy install.
+        const finish = (level, detail, fix) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            // Escalate (round-9): SIGTERM alone leaves a wedged server running with doctor's pipes open.
+            child.kill();
+            // round-10: an unref'd timer never fires in a doctor run that ends in ~0.4s, so the escalation
+            // was decoration. The timer holds the loop for its 500ms and is cleared the moment the child
+            // actually exits, so a healthy run pays nothing.
+            const hard = setTimeout(() => { try {
+                child.kill('SIGKILL');
+            }
+            catch { /* already gone */ } }, 500);
+            child.once('exit', () => clearTimeout(hard));
+            child.stdout.destroy();
+            child.stderr.destroy();
+            child.stdin.destroy();
+            child.unref?.();
+            // Cleanup HERE, not on 'close' — doctor's process can exit before a close handler runs,
+            // stranding the isolated cwd (round-6 §7e measured the leak). A signal death still strands it;
+            // `cleanupOnSignal` below covers that (round-9).
+            try {
+                fs.rmSync(mcpCwd, { recursive: true, force: true });
+            }
+            catch { /* tmp cleaner's job */ }
+            resolve({ name: 'MCP server', level, detail, fix });
+        };
+        cleanupOnSignal(mcpCwd);
+        // EPIPE arrives as an ASYNC 'error' event, not a synchronous throw — the try/catch below never
+        // sees it, and an unhandled stream error would crash doctor itself (round-1 REQ-192).
+        child.stdin.on('error', () => { });
+        // Fast path (round-4): a dead-on-arrival server made doctor (and its tests) sit out the full
+        // 15s timeout — the child's stdio closing IS the answer.
+        child.on('close', () => {
+            // round-10: a server whose last line lacked a trailing newline was reported as 'died before
+            // answering' although it had answered. Flush what is pending before judging.
+            const tail = pending.trim();
+            pending = '';
+            if (tail.startsWith('{')) {
+                try {
+                    const msg = JSON.parse(tail);
+                    const tools = msg.result?.tools;
+                    if (Array.isArray(tools) && tools.length > 0) {
+                        finish('PASS', `handshake ok, ${tools.length} tools advertised`);
+                        return;
+                    }
+                }
+                catch { /* not a complete message after all */ }
+            }
+            finish('FAIL', `MCP server exited before answering (stderr: ${err.slice(0, 160)})`, 'The MCP server did not start. A missing tree-sitter grammar is the usual cause (see above).');
+        });
+        const send = (o) => { try {
+            child.stdin.write(JSON.stringify(o) + '\n');
+        }
+        catch { /* server gone */ } };
+        const timer = setTimeout(() => finish('FAIL', `no tools/list response within ${timeoutMs}ms (stderr: ${err.slice(0, 160)})`, 'The MCP server did not start. A missing tree-sitter grammar is the usual cause (see above).'), timeoutMs);
+        // Line-oriented and stateful. The old shape re-scanned the whole accumulated buffer on every
+        // chunk (quadratic, and it re-fired past triggers) and judged `tools` by
+        // `typeof result.tools.length === 'number'` — which a NON-ARRAY or an EMPTY list satisfies, so a
+        // server advertising nothing passed (round-9).
+        child.stdout.on('data', (d) => {
+            pending += String(d);
+            // round-10: slicing from the FRONT cut a large tools/list answer mid-JSON, so a healthy server
+            // with many tools parsed as garbage and waited out the full timeout with a tree-sitter
+            // misdiagnosis. A protocol line is dropped WHOLE (and said so), never trimmed into nonsense.
+            if (pending.length > 4_000_000 && !pending.includes('\n')) {
+                pending = '';
+                finish('FAIL', 'MCP server sent a single line larger than 4MB without a newline', 'The server is not speaking line-delimited JSON-RPC — check the installed version.');
+                return;
+            }
+            const lines = pending.split('\n');
+            pending = lines.pop() ?? '';
+            for (const line of lines) {
+                if (!line.trim())
+                    continue;
+                let msg;
+                try {
+                    msg = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                } // 서버의 로그 줄은 프로토콜이 아니다
+                if (msg.error && (msg.id === 1 || msg.id === 2)) {
+                    finish('FAIL', `MCP server answered ${msg.id === 1 ? 'initialize' : 'tools/list'} with an error: ${String(msg.error.message ?? msg.error.code)}`, 'The server started but refused the handshake — check the installed version against this package.');
+                    return;
+                }
+                // A server may SEND requests of its own; one that happens to use id 2 is not our answer.
+                // Only a message carrying `result` (or `error`, handled above) is a response.
+                if (msg.result === undefined)
+                    continue;
+                if (msg.id === 2 || msg.result?.tools !== undefined) {
+                    const tools = msg.result?.tools;
+                    if (!Array.isArray(tools)) {
+                        finish('FAIL', `tools/list did not answer with a list (got ${typeof tools})`, 'The server answered, but not with a tool list — check the installed version against this package.');
+                        return;
+                    }
+                    if (tools.length === 0) {
+                        finish('FAIL', 'handshake ok but the server advertises ZERO tools', 'A server with no tools cannot serve this project — reinstall or upgrade holmes-kit.');
+                        return;
+                    }
+                    finish('PASS', `handshake ok, ${tools.length} tools advertised`);
+                    return;
+                }
+                if (!initialized && msg.result?.serverInfo !== undefined) {
+                    initialized = true;
+                    send({ jsonrpc: '2.0', method: 'notifications/initialized' });
+                    send({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} });
+                }
+            }
+        });
+        child.stderr.on('data', (d) => { err = (err + String(d)).slice(-4096); });
+        child.on('error', (e) => finish('FAIL', `could not spawn the MCP server: ${e.message}`, 'Check the install — the bin shim must resolve to this package.'));
+        send({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'holmes-doctor', version: '1' } } });
+    });
+}
+function formatChecks(checks) {
+    const lines = checks.map((c) => {
+        const head = `${c.level.padEnd(4)} ${c.name} — ${c.detail}`;
+        return c.fix && c.level !== 'PASS' ? `${head}\n     fix: ${c.fix}` : head;
+    });
+    const fails = checks.filter((c) => c.level === 'FAIL').length;
+    const warns = checks.filter((c) => c.level === 'WARN').length;
+    lines.push(`\n${checks.length - fails - warns} pass, ${warns} warn, ${fails} fail`);
+    return lines.join('\n');
+}