@holmes-lab/holmes-kit 0.1.13 → 0.1.15

package/CHANGELOG.md

@@ -4,6 +4,50 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+<!-- @implements A-SPEC-209 -->
+## [0.1.15] - 2026-08-23
+
+The stale-install trap, fixed at the root and made visible. A Windows user upgraded holmes-kit but
+their MCP kept launching 0.1.9: `.mcp.json` pinned the global install by absolute path, and `-g`
+upgrades EPERM on Windows so the global never moved.
+
+### Added
+- **npx-pinned MCP wiring (REQ-1404)**: `init` now wires the holmes-kit MCP server as
+  `npx -y @holmes-lab/holmes-kit@<exact-version> holmes-mcp` for installed packages — no global
+  install, no `-g` (no EPERM), no absolute-path drift. It auto-detects: an installed packageRoot
+  (under `node_modules/@holmes-lab/holmes-kit`) wires npx; a source checkout keeps `node` against
+  local `dist`. `--mcp-launcher npx|node` overrides; an unknown value is refused, not defaulted.
+  The pin is the exact version init ran from, so an upgrade happens only on an explicit
+  `npx @holmes-lab/holmes-kit@latest init` — never silently. All three harness wirings
+  (Claude/antigravity/codex) share one launch contract via `mcpEntryForInstall`.
+- **doctor sees MCP version drift, offline (REQ-1405)**: `doctor` reads the version its
+  `.mcp.json` will ACTUALLY launch — from the npx pin, or a node wiring's LOCAL package.json — and
+  WARNs when it differs from the CLI, naming both versions and the `init` fix. No registry call:
+  the zero-outbound stance holds. This is the diagnostic that would have named the 0.1.9 stall.
+
+### Changed
+- `mergeMcpServers(existing, name, entry, specsDir)` takes a computed `{command, args}` entry
+  instead of a bin path — env preservation (A-SPEC-179) is unchanged.
+
+<!-- @implements A-SPEC-209 -->
+## [0.1.14] - 2026-08-23
+
+A defect found by installing 0.1.13 from the registry and driving the shipped HITL cycle:
+`holmes-kit approve --help` printed the whole-CLI usage instead of its own. The approve
+subcommand — the human decision surface — had its help swallowed at its first touch.
+
+### Fixed
+- **`approve --help` reaches APPROVE_USAGE (A-SPEC-171)**: the global `--help` handler fired
+  before approve's dispatch (which carries its own usage) could run, so it printed the top-level
+  usage over it — approve dispatches last only because it was added last. A declarative
+  `SELF_HELP_COMMANDS` set now exempts any subcommand that renders its own usage, so the fix does
+  not depend on dispatch order. Two reproducing tests (RED before, GREEN after).
+- **Repo hygiene: a stray `C:/proj/.ax` was tracked (A-SPEC-237/§25a)**: the Windows path tests
+  pass `projectRoot: 'C:/proj'`, which on POSIX resolves as a relative path into the repo. A
+  pre-§25a residue directory had been committed in 0.1.13 and kept growing on every suite run;
+  removed, with a `.gitignore` guard against drive-letter directories. Verified the §25a
+  enqueue-only-under-existing-.ax guard now prevents recreation — the suite no longer plants it.
+
 <!-- @implements A-SPEC-209 -->
 ## [0.1.13] - 2026-08-23
 

package/dist/.build-id

@@ -1 +1 @@
-0c506c6-mt5buls8
+d6b14ca-mt5ea641

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

@@ -1,3 +1,4 @@
+import { LauncherMode } from './mcp-launcher';
 /**
  * 하네스별 배선물.
  *
@@ -29,6 +30,7 @@ export interface AgentWiringOptions {
     target: string;
     packageRoot: string;
     specsDir: string;
+    launcher?: LauncherMode;
 }
 export interface AgentFile {
     path: string;

package/dist/holmes/cli/agents.js

@@ -38,6 +38,7 @@ exports.agentFiles = agentFiles;
 exports.agentLinks = agentLinks;
 // @implements A-SPEC-193
 const path = __importStar(require("node:path"));
+const mcp_launcher_1 = require("./mcp-launcher");
 /**
  * 하네스별 배선물.
  *
@@ -69,15 +70,21 @@ exports.HARNESS_ENFORCES = {
     codex: false,
 };
 const q = (p) => p;
-const mcpConfig = (packageRoot, specsDir) => `${JSON.stringify({
-    mcpServers: {
-        'holmes-kit': {
-            command: 'node',
-            args: [q(path.join(packageRoot, 'bin', 'holmes-mcp.js'))],
-            env: { HOLMES_SPECS: specsDir },
+// @implements A-SPEC-1404 — same launch contract as the Claude wiring: npx-pin for installed
+// packageRoots, node for source checkouts. Shared via mcpEntryForInstall so all three harnesses
+// move together.
+const mcpConfig = (packageRoot, specsDir, launcher) => {
+    const entry = (0, mcp_launcher_1.mcpEntryForInstall)({
+        packageRoot,
+        mcpBinPath: q(path.join(packageRoot, 'bin', 'holmes-mcp.js')),
+        flag: launcher,
+    });
+    return `${JSON.stringify({
+        mcpServers: {
+            'holmes-kit': { command: entry.command, args: entry.args, env: { HOLMES_SPECS: specsDir } },
         },
-    },
-}, null, 2)}\n`;
+    }, null, 2)}\n`;
+};
 /**
  * Antigravity 훅 배선.
  *
@@ -152,12 +159,12 @@ function agentFiles(agent, opts) {
         case 'antigravity':
             return [
                 { path: path.join(target, '.agents', 'hooks.json'), content: hooksJson(packageRoot) },
-                { path: path.join(target, '.agents', 'mcp_config.json'), content: mcpConfig(packageRoot, specsDir) },
+                { path: path.join(target, '.agents', 'mcp_config.json'), content: mcpConfig(packageRoot, specsDir, opts.launcher) },
                 { path: path.join(target, 'AGENTS.md'), content: AGENTS_MD(exports.HARNESS_ENFORCES.antigravity) },
             ];
         case 'codex':
             return [
-                { path: path.join(target, '.codex', 'mcp_config.json'), content: mcpConfig(packageRoot, specsDir) },
+                { path: path.join(target, '.codex', 'mcp_config.json'), content: mcpConfig(packageRoot, specsDir, opts.launcher) },
                 { path: path.join(target, 'AGENTS.md'), content: AGENTS_MD(exports.HARNESS_ENFORCES.codex) },
             ];
         default:

package/dist/holmes/cli/doctor.js

@@ -50,6 +50,8 @@ 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 mcp_version_1 = require("./mcp-version");
+const mcp_launcher_1 = require("./mcp-launcher");
 const GRAMMARS = [
     'tree-sitter-typescript', 'tree-sitter-python', 'tree-sitter-c-sharp', 'tree-sitter-java',
     'tree-sitter-go', 'tree-sitter-rust', 'tree-sitter-cpp',
@@ -454,6 +456,37 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
         else {
             add('approval channel', 'WARN', '이 프로세스에는 HOLMES_APPROVAL이 있으나 .mcp.json의 서버 환경에는 없습니다 — spec_approve는 서버 환경을 읽습니다', 'settings.local.json의 env가 MCP 서버까지 전달된다는 보장은 없습니다. 그 변수를 설정한 셸에서 Claude Code를 띄우면 자식 서버가 상속합니다.');
         }
+        // @implements A-SPEC-1405 — the version this project's MCP server will ACTUALLY launch, vs this
+        // CLI. The stale-global trap (measured 2026-08-23: .mcp.json pinned a 0.1.9 global while the user
+        // believed they had upgraded) was invisible because nothing compared them. Offline: the launch
+        // version comes from the wiring string, or a node wiring's LOCAL package.json — never the registry.
+        try {
+            const raw = fs.readFileSync(path.join(target, '.mcp.json'), 'utf8');
+            const server = JSON.parse(raw)
+                .mcpServers?.[init_1.SERVER_NAME];
+            const cli = (0, mcp_launcher_1.readPackageVersion)(packageRoot);
+            if (server && typeof server.command === 'string' && Array.isArray(server.args) && cli) {
+                const readPkgVersionAt = (dir) => {
+                    try {
+                        const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+                        return pkg?.name === '@holmes-lab/holmes-kit' && typeof pkg.version === 'string' ? pkg.version : undefined;
+                    }
+                    catch {
+                        return undefined;
+                    }
+                };
+                const launch = (0, mcp_version_1.mcpLaunchVersion)({ command: server.command, args: server.args }, readPkgVersionAt);
+                const verdict = (0, mcp_version_1.versionDriftVerdict)(launch, cli);
+                if (verdict === 'drift') {
+                    add('mcp server version', 'WARN', `이 프로젝트의 MCP 서버는 holmes-kit ${launch} 를 띄우지만 이 CLI 는 ${cli} 입니다 — 재배선 전까지 옛 서버가 계속 뜹니다`, 'npx @holmes-lab/holmes-kit@latest init 을 다시 실행해 .mcp.json 을 최신 버전으로 재배선하십시오 (전역 -g 업그레이드 불필요).');
+                }
+                else if (verdict === 'match') {
+                    add('mcp server version', 'PASS', `MCP 서버 버전 ${launch} 가 이 CLI 와 일치합니다`);
+                }
+                // 'unknown' → 항목 없음: 판정 불능을 결함으로 만들지 않는다.
+            }
+        }
+        catch { /* .mcp.json 부재/파싱 실패 → 이 점검 없이 진행 */ }
         // @implements A-SPEC-193 — 배선된 하네스마다 그 하네스의 배선을 검사한다. 배선되지 않은
         // 하네스는 진단하지 않는다(없는 것을 결함이라 부르면 doctor 가 소음이 된다).
         const agyHooks = path.join(target, '.agents', 'hooks.json');

package/dist/holmes/cli/index.js

@@ -69,13 +69,19 @@ function packageRoot() {
  * REQ-144's "cannot decide is not permission", applied to CLI arguments.
  */
 const KNOWN_FLAGS = {
-    init: ['help', 'target', 'mode', 'specs-dir', 'settings', 'matcher', 'dry-run', 'no-mcp', 'remove', 'force', 'agent'],
+    init: ['help', 'target', 'mode', 'specs-dir', 'settings', 'matcher', 'dry-run', 'no-mcp', 'remove', 'force', 'agent', 'mcp-launcher'],
     doctor: ['help', 'target', 'json'],
     skills: ['help', 'target'],
     ci: ['help', 'target', 'specs-dir', 'json'],
     serve: ['help', 'target', 'port'],
     approve: ['help', 'target', 'list', 'grant', 'deny', 'ask', 'reason', 'question', 'ttl', 'rationale'],
 };
+// @implements A-SPEC-171 — subcommands that render their OWN usage on `--help`. A-SPEC-171 governs
+// "help before any side effect"; a command whose usage lives past this handler (approve, whose
+// APPROVE_USAGE is emitted in its own dispatch) must be exempted here or the global handler prints
+// the whole-CLI usage over it. This set is that exemption, kept declarative so a future self-help
+// command is one edit, not a dispatch-order gamble.
+const SELF_HELP_COMMANDS = new Set(['approve']);
 const APPROVE_USAGE = `holmes-kit approve — 승인 대기 요청의 결재 (HITL)
 
   대화형(TTY):        항목마다 [a]승인 [d]거부 [q]질문 [s]건너뛰기
@@ -237,8 +243,10 @@ async function main(argv) {
     }
     // @implements A-SPEC-171
     // BEFORE any side effect. The measured defect was not that help was missing but that the writing
-    // happened first, so the order here is the fix.
-    if (knownFlagsFor(cmd) && flags.help) {
+    // happened first, so the order here is the fix. Measured again on 0.1.13: `approve --help` printed
+    // the whole-CLI usage because this handler fired before approve's dispatch (which carries its own
+    // APPROVE_USAGE) could run — so a command in SELF_HELP_COMMANDS is deferred to, not printed over.
+    if (knownFlagsFor(cmd) && flags.help && !SELF_HELP_COMMANDS.has(cmd)) {
         process.stdout.write(USAGE);
         return 0;
     }
@@ -421,6 +429,16 @@ async function main(argv) {
     }
     if (cmd === 'init') {
         const mode = (typeof flags.mode === 'string' ? flags.mode : 'guardrail');
+        // @implements A-SPEC-1404 — an unknown launch mode is refused, not defaulted: substituting a
+        // default acts where the operator did not point (REQ-144). Only npx|node are wiring modes.
+        let mcpLauncher;
+        if (typeof flags['mcp-launcher'] === 'string') {
+            if (flags['mcp-launcher'] !== 'npx' && flags['mcp-launcher'] !== 'node') {
+                process.stderr.write(`--mcp-launcher must be 'npx' or 'node'\n\n${USAGE}`);
+                return 2;
+            }
+            mcpLauncher = flags['mcp-launcher'];
+        }
         // 형제 열거 오류와 같은 모양(round 7): --settings·--target 은 USAGE 와 함께 exit 2 인데
         // --mode 만 맨몸 exit 1 이었다 — 같은 실수의 진단이 두 벌이면 스크립트가 갈린다.
         if (mode !== 'guardrail' && mode !== 'governed') {
@@ -496,6 +514,7 @@ async function main(argv) {
             force: flags.force === true,
             remove: flags.remove === true,
             approval: readApproval(),
+            mcpLauncher,
         };
         const res = (0, init_1.runInit)(opts);
         for (const m of res.messages)

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

@@ -1,5 +1,6 @@
 import { HookPlan } from './settings-merge';
 import { Agent } from './agents';
+import { LauncherMode } from './mcp-launcher';
 import { Approval } from '../guardrail/risk-gate';
 /**
  * `holmes-kit init` — wire holmes-kit into a TARGET project (the I/O half; all merge logic is pure
@@ -29,6 +30,7 @@ export interface InitOptions {
     approval?: Approval;
     agents?: Agent[];
     allowAdditive?: boolean;
+    mcpLauncher?: LauncherMode;
 }
 export interface FileChange {
     path: string;

package/dist/holmes/cli/init.js

@@ -45,6 +45,7 @@ const settings_merge_2 = require("./settings-merge");
 const playbook_skills_1 = require("./playbook-skills");
 const agents_1 = require("./agents");
 const roles_readme_1 = require("./roles-readme");
+const mcp_launcher_1 = require("./mcp-launcher");
 const pre_tool_use_1 = require("../hooks/pre-tool-use");
 const governed_precondition_1 = require("./governed-precondition");
 const risk_gate_1 = require("../guardrail/risk-gate");
@@ -309,7 +310,10 @@ function runInit(opts) {
             const kept = Object.keys(prevEnv).filter((k) => !settings_merge_2.HOLMES_OWNED_MCP_ENV.includes(k));
             if (kept.length > 0)
                 messages.push(`Preserved your MCP server env: ${kept.join(', ')}`);
-            changes.push({ path: mcpPath, before: m.raw, after: JSON.stringify((0, settings_merge_1.mergeMcpServers)(m.value, exports.SERVER_NAME, mcpBin, opts.specsDir), null, 2) + '\n' });
+            // @implements A-SPEC-1404 — compute the launch entry once (npx-pin for installs, node for source),
+            // then merge; env preservation is unchanged.
+            const mcpEntry = (0, mcp_launcher_1.mcpEntryForInstall)({ packageRoot: opts.packageRoot, mcpBinPath: mcpBin, flag: opts.mcpLauncher });
+            changes.push({ path: mcpPath, before: m.raw, after: JSON.stringify((0, settings_merge_1.mergeMcpServers)(m.value, exports.SERVER_NAME, mcpEntry, opts.specsDir), null, 2) + '\n' });
         }
         changes.push({ path: settingsPath, before: s.raw, after: JSON.stringify(settings, null, 2) + '\n' });
         const gitignoreAfter = (0, gitignore_merge_1.mergeGitignore)(gitignoreBefore);
@@ -357,7 +361,7 @@ function runInit(opts) {
     // 같은 집합을 예고한다(A-SPEC-190 §9 의 규율). Claude 는 위에서 이미 배선했으므로 빈 목록이다.
     if (!opts.remove) {
         for (const agent of opts.agents ?? []) {
-            for (const f of (0, agents_1.agentFiles)(agent, { target: opts.target, packageRoot: opts.packageRoot, specsDir: opts.specsDir })) {
+            for (const f of (0, agents_1.agentFiles)(agent, { target: opts.target, packageRoot: opts.packageRoot, specsDir: opts.specsDir, launcher: opts.mcpLauncher })) {
                 const before = fs.existsSync(f.path) ? fs.readFileSync(f.path, 'utf8') : null;
                 changes.push({ path: f.path, before, after: f.content });
             }

package/dist/holmes/cli/mcp-launcher.d.ts

@@ -0,0 +1,55 @@
+/**
+ * MCP 서버 배선의 launch 방식을 한 곳에서 계산한다.
+ *
+ * 왜 한 곳인가: `.mcp.json`(Claude)·`.agents/mcp_config.json`(antigravity)·`.codex/mcp_config.json`
+ * 세 배선이 같은 서버를 띄운다. 셋이 각자 command/args 를 지으면 하나가 npx 로 옮겨갈 때 나머지가
+ * 절대경로에 남아 어긋난다 — 그 드리프트가 REQ-1404 자체의 출발점이었다.
+ *
+ * 왜 두 모드인가: 최종 사용자는 npm 설치본에서 init 하므로 `npx ...@<정확한버전> holmes-mcp` 가
+ * 옳다 — 전역 설치도 `-g` 도 필요 없고(Windows EPERM 회피), 절대경로 고착이 없다. 그러나 개발
+ * 저장소(소스 체크아웃)는 아직 발행되지 않은 working tree 를 쓰므로 npx 로 레지스트리를 당기면 안
+ * 된다 — 로컬 dist 를 직접 부르는 node 배선이 맞다. 그래서 기본은 packageRoot 성격으로 자동 판별한다.
+ */
+export type LauncherMode = 'npx' | 'node';
+export interface McpServerEntry {
+    command: string;
+    args: string[];
+}
+/** npm 상의 정식 패키지 이름. 핀은 이 이름에 정확한 버전을 붙인다. */
+export declare const MCP_PACKAGE = "@holmes-lab/holmes-kit";
+/**
+ * 배선 entry 를 낸다 — 순수.
+ *
+ * npx 핀은 `version` 을 **그대로** 붙인다(정규화·범위화 없음): 프리릴리스·빌드메타 문자열도
+ * 있는 그대로 핀해야 init 을 실행한 그 버전이 재현된다. `version` 유무 판정은 상위(배선 지점)가
+ * 하고, 여기서는 받은 것을 박기만 한다.
+ */
+export declare function mcpServerEntry(opts: {
+    mode: LauncherMode;
+    version: string;
+    mcpBinPath: string;
+}): McpServerEntry;
+/**
+ * 기본 모드를 정한다 — 순수, 경로 문자열만 본다(파일시스템 조회 없음).
+ *
+ * `flag` 가 명시되면 그대로. 없으면 packageRoot 가 설치본 세그먼트를 포함하면 npx, 아니면 node.
+ * Windows 구분자(`\`)를 `/` 로 정규화해 비교하므로 두 OS 의 설치 경로가 같게 인식된다.
+ */
+export declare function resolveLauncherMode(opts: {
+    flag?: LauncherMode;
+    packageRoot: string;
+}): LauncherMode;
+/** packageRoot/package.json 의 version. 못 읽으면 undefined — 이것이 node 물러남을 부른다. */
+export declare function readPackageVersion(packageRoot: string): string | undefined;
+/**
+ * 세 배선(Claude/antigravity/codex)이 공유하는 조립: 모드 판별 → 버전 읽기 → entry.
+ *
+ * npx 로 판별됐어도 버전을 못 읽으면 node 로 물러난다 — 빈 핀(`@holmes-lab/holmes-kit@`)을 박느니
+ * 로컬 bin 을 부르는 편이 유효하다(A-SPEC-1404 경계). `readVersion` 은 주입 가능해 시험이 fs 없이 돈다.
+ */
+export declare function mcpEntryForInstall(opts: {
+    packageRoot: string;
+    mcpBinPath: string;
+    flag?: LauncherMode;
+    readVersion?: (packageRoot: string) => string | undefined;
+}): McpServerEntry;

package/dist/holmes/cli/mcp-launcher.js

@@ -0,0 +1,96 @@
+"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.MCP_PACKAGE = void 0;
+exports.mcpServerEntry = mcpServerEntry;
+exports.resolveLauncherMode = resolveLauncherMode;
+exports.readPackageVersion = readPackageVersion;
+exports.mcpEntryForInstall = mcpEntryForInstall;
+// @implements A-SPEC-1404
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/** npm 상의 정식 패키지 이름. 핀은 이 이름에 정확한 버전을 붙인다. */
+exports.MCP_PACKAGE = '@holmes-lab/holmes-kit';
+/**
+ * 배선 entry 를 낸다 — 순수.
+ *
+ * npx 핀은 `version` 을 **그대로** 붙인다(정규화·범위화 없음): 프리릴리스·빌드메타 문자열도
+ * 있는 그대로 핀해야 init 을 실행한 그 버전이 재현된다. `version` 유무 판정은 상위(배선 지점)가
+ * 하고, 여기서는 받은 것을 박기만 한다.
+ */
+function mcpServerEntry(opts) {
+    if (opts.mode === 'npx') {
+        return { command: 'npx', args: ['-y', `${exports.MCP_PACKAGE}@${opts.version}`, 'holmes-mcp'] };
+    }
+    return { command: 'node', args: [opts.mcpBinPath] };
+}
+const INSTALLED_SEGMENT = 'node_modules/@holmes-lab/holmes-kit';
+/**
+ * 기본 모드를 정한다 — 순수, 경로 문자열만 본다(파일시스템 조회 없음).
+ *
+ * `flag` 가 명시되면 그대로. 없으면 packageRoot 가 설치본 세그먼트를 포함하면 npx, 아니면 node.
+ * Windows 구분자(`\`)를 `/` 로 정규화해 비교하므로 두 OS 의 설치 경로가 같게 인식된다.
+ */
+function resolveLauncherMode(opts) {
+    if (opts.flag)
+        return opts.flag;
+    const normalized = opts.packageRoot.replace(/\\/g, '/');
+    return normalized.includes(INSTALLED_SEGMENT) ? 'npx' : 'node';
+}
+/** packageRoot/package.json 의 version. 못 읽으면 undefined — 이것이 node 물러남을 부른다. */
+function readPackageVersion(packageRoot) {
+    try {
+        const v = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')).version;
+        return typeof v === 'string' && v.length > 0 ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 세 배선(Claude/antigravity/codex)이 공유하는 조립: 모드 판별 → 버전 읽기 → entry.
+ *
+ * npx 로 판별됐어도 버전을 못 읽으면 node 로 물러난다 — 빈 핀(`@holmes-lab/holmes-kit@`)을 박느니
+ * 로컬 bin 을 부르는 편이 유효하다(A-SPEC-1404 경계). `readVersion` 은 주입 가능해 시험이 fs 없이 돈다.
+ */
+function mcpEntryForInstall(opts) {
+    const mode = resolveLauncherMode({ flag: opts.flag, packageRoot: opts.packageRoot });
+    const read = opts.readVersion ?? readPackageVersion;
+    const version = mode === 'npx' ? read(opts.packageRoot) : undefined;
+    if (mode === 'npx' && !version) {
+        return mcpServerEntry({ mode: 'node', version: '', mcpBinPath: opts.mcpBinPath });
+    }
+    return mcpServerEntry({ mode, version: version ?? '', mcpBinPath: opts.mcpBinPath });
+}

package/dist/holmes/cli/mcp-version.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `.mcp.json` 배선이 **실제로 띄울** holmes-kit 버전을, 네트워크 없이 로컬로 뽑는다.
+ *
+ * 이 판정이 없어서 사용자의 전역 0.1.9 정체를 아무 진단도 보지 못했다(REQ-1405). 레지스트리를
+ * 묻지 않는다 — 배선 문자열과, node 배선인 경우 주입된 로컬 reader 만 본다. reader 를 안 주면 node
+ * 경로는 판정 불능(null)이지 실제 fs 를 더듬지 않는다: 순수성이 [offline] 을 시험 가능하게 한다.
+ */
+export interface McpEntryShape {
+    command: string;
+    args: string[];
+}
+/**
+ * 배선이 띄울 버전, 또는 못 뽑으면 null.
+ *
+ * - npx: args 중 핀 스펙에서 버전 캡처.
+ * - node: args[0] 경로의 dirname 에서 위로 올라가며 `readVersion(dir)` 가 값을 줄 때까지. reader 가
+ *   없으면 null(파일 접근 없음).
+ * - 그 외 command → null.
+ */
+export declare function mcpLaunchVersion(entry: McpEntryShape, readVersion?: (packageDir: string) => string | undefined): string | null;
+export type DriftVerdict = 'match' | 'drift' | 'unknown';
+/** launch 를 못 뽑았으면 unknown(거짓 drift 를 만들지 않는다). 같으면 match, 다르면 drift. */
+export declare function versionDriftVerdict(launchVersion: string | null, cliVersion: string): DriftVerdict;

package/dist/holmes/cli/mcp-version.js

@@ -0,0 +1,82 @@
+"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.mcpLaunchVersion = mcpLaunchVersion;
+exports.versionDriftVerdict = versionDriftVerdict;
+// @implements A-SPEC-1405
+const path = __importStar(require("node:path"));
+/** npx 인자에서 핀 버전을 뽑는 정규식: `@holmes-lab/holmes-kit@<X>` 의 X. `@` 없는 스펙은 안 잡힌다. */
+const NPX_PIN = /^@holmes-lab\/holmes-kit@(.+)$/;
+/**
+ * 배선이 띄울 버전, 또는 못 뽑으면 null.
+ *
+ * - npx: args 중 핀 스펙에서 버전 캡처.
+ * - node: args[0] 경로의 dirname 에서 위로 올라가며 `readVersion(dir)` 가 값을 줄 때까지. reader 가
+ *   없으면 null(파일 접근 없음).
+ * - 그 외 command → null.
+ */
+function mcpLaunchVersion(entry, readVersion) {
+    if (entry.command === 'npx') {
+        for (const a of entry.args) {
+            const m = NPX_PIN.exec(a);
+            if (m)
+                return m[1];
+        }
+        return null;
+    }
+    if (entry.command === 'node') {
+        if (!readVersion || entry.args.length === 0)
+            return null;
+        let dir = path.dirname(entry.args[0]);
+        // Walk up to the filesystem root, asking the reader at each level. `path.dirname('/') === '/'`,
+        // so the loop terminates when dir stops shrinking.
+        for (;;) {
+            const v = readVersion(dir);
+            if (v)
+                return v;
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                return null;
+            dir = parent;
+        }
+    }
+    return null;
+}
+/** launch 를 못 뽑았으면 unknown(거짓 drift 를 만들지 않는다). 같으면 match, 다르면 drift. */
+function versionDriftVerdict(launchVersion, cliVersion) {
+    if (launchVersion === null)
+        return 'unknown';
+    return launchVersion === cliVersion ? 'match' : 'drift';
+}

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

@@ -62,5 +62,8 @@ export declare function disableMcpServer(existing: Settings | undefined, name: s
  * put it there.
  */
 export declare const HOLMES_OWNED_MCP_ENV: readonly ["HOLMES_SPECS"];
-export declare function mergeMcpServers(existing: McpConfig | undefined, name: string, mcpBinPath: string, specsDir: string): McpConfig;
+export declare function mergeMcpServers(existing: McpConfig | undefined, name: string, entry: {
+    command: string;
+    args: string[];
+}, specsDir: string): McpConfig;
 export declare function removeMcpServer(existing: McpConfig | undefined, name: string): McpConfig;

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

@@ -90,7 +90,11 @@ function disableMcpServer(existing, name) {
  * put it there.
  */
 exports.HOLMES_OWNED_MCP_ENV = ['HOLMES_SPECS'];
-function mergeMcpServers(existing, name, mcpBinPath, specsDir) {
+// @implements A-SPEC-1404
+// The server entry (command/args) is COMPUTED by the caller (mcp-launcher: npx-pin for installs,
+// node for source checkouts) rather than assembled here, so all three harness wirings share one
+// launch contract. This merge owns only env preservation, not how the server is launched.
+function mergeMcpServers(existing, name, entry, specsDir) {
     const out = { ...(existing ?? {}) };
     // @implements A-SPEC-179
     // Merge, not replace. Measured 2026-08-13 while previewing `--force` on holmes-kit's own
@@ -104,7 +108,7 @@ function mergeMcpServers(existing, name, mcpBinPath, specsDir) {
     const prev = (prevEntry && typeof prevEntry === 'object' ? prevEntry.env : undefined) ?? {};
     out.mcpServers = {
         ...(out.mcpServers ?? {}),
-        [name]: { command: 'node', args: [mcpBinPath], env: { ...prev, HOLMES_SPECS: specsDir } },
+        [name]: { command: entry.command, args: entry.args, env: { ...prev, HOLMES_SPECS: specsDir } },
     };
     return out;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
   "main": "dist/holmes/mcp/server.js",
   "types": "dist/holmes/mcp/server.d.ts",