@holmes-lab/holmes-kit 0.1.17 → 0.1.18

package/CHANGELOG.md

@@ -5,6 +5,15 @@ 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.18] - 2026-08-23
+
+### Fixed
+- **The npx MCP wiring actually starts the server (REQ-259)**: `init` on an npm-installed package wrote `npx -y @holmes-lab/holmes-kit@<ver> holmes-mcp`, which npx resolves to the package-name-matching *default* binary (`holmes-kit`) with `holmes-mcp` as its argument — exit 1, so **every npm-installed wiring since the 0.1.15 npx pin launched a dead MCP server** (`CONNECTION_CLOSED` in the harness). The wiring now rides `-p` (`npx -y -p <pkg>@<ver> holmes-mcp`), the launcher test spawns the generated form against a locally packed tarball (with the pre-fix form kept as a failing control), and `doctor` gains **`mcp wiring spawn`** — it runs the target's `.mcp.json` command verbatim inside a 30s bound and names a dead wiring FAIL with the re-init remediation. Existing projects: re-run `holmes-kit init` (doctor will point at the dead wiring).
+- **`serverInfo.version` reports the real package version** — it was hardcoded to `0.1.0`, blinding client-side drift diagnosis.
+
+### Changed
+- **`approve` without a TTY names the next command (REQ-260)**: the implicit non-TTY fallback (e.g. Claude Code's `!` shell) used to print the pending list and exit 0 silently; it now appends runnable `--grant` / `--deny` / `--ask` examples carrying the first real pending id. Explicit `--list` output is unchanged for scripts.
+
 ## [0.1.17] - 2026-08-23
 
 The two `main` lines — the Windows-compatibility line (12 commits, verified on Windows 11 and

package/dist/.build-id

@@ -1 +1 @@
-e6199ca-mt5qbc5d
+f8c9769-mt5t8gnu

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

@@ -30,6 +30,17 @@ export declare function holdRequest(root: string, id: string, question: string,
  * teaches syntax, humans start typing it.
  */
 export declare function renderPending(state: QueueState): string;
+/**
+ * The non-TTY fallback's next-command hint. Pure.
+ *
+ * @implements A-SPEC-260
+ * Without a TTY the interactive loop cannot run, and the silent list-then-exit-0 left the operator
+ * with no idea what to type (measured 2026-08-23 — Claude Code's `!` runs with a non-TTY stdin).
+ * The examples carry the FIRST pending id read from the queue, never a placeholder the operator
+ * must transcribe: [noguess]. An empty queue yields an empty hint — nothing to act on, nothing to
+ * advise. `renderPending` itself stays hint-free: the explicit `--list` output is for scripts.
+ */
+export declare function renderNonTtyHint(state: QueueState): string;
 export interface ApproveIO {
     print: (s: string) => void;
     /** Ask one question, resolve with the raw answer. Injected so tests script the conversation. */

package/dist/holmes/cli/approve.js

@@ -37,6 +37,7 @@ exports.grantRequest = grantRequest;
 exports.denyRequest = denyRequest;
 exports.holdRequest = holdRequest;
 exports.renderPending = renderPending;
+exports.renderNonTtyHint = renderNonTtyHint;
 exports.runInteractive = runInteractive;
 // @implements A-SPEC-246
 const fs = __importStar(require("node:fs"));
@@ -154,6 +155,27 @@ function renderPending(state) {
         lines.push(`(큐에 읽을 수 없는 줄 ${state.malformedLines}건 — 손상 여부를 확인하십시오)`);
     return lines.join('\n');
 }
+/**
+ * The non-TTY fallback's next-command hint. Pure.
+ *
+ * @implements A-SPEC-260
+ * Without a TTY the interactive loop cannot run, and the silent list-then-exit-0 left the operator
+ * with no idea what to type (measured 2026-08-23 — Claude Code's `!` runs with a non-TTY stdin).
+ * The examples carry the FIRST pending id read from the queue, never a placeholder the operator
+ * must transcribe: [noguess]. An empty queue yields an empty hint — nothing to act on, nothing to
+ * advise. `renderPending` itself stays hint-free: the explicit `--list` output is for scripts.
+ */
+function renderNonTtyHint(state) {
+    if (state.pending.length === 0)
+        return '';
+    const id = state.pending[0].id;
+    return [
+        '대화형 결정은 TTY에서만 동작합니다 — 이 셸에서는 아래 비대화형 명령을 사용하십시오:',
+        `  holmes-kit approve --grant ${id}`,
+        `  holmes-kit approve --deny ${id} --reason "<사유>"`,
+        `  holmes-kit approve --ask ${id} --question "<질문>"`,
+    ].join('\n');
+}
 /**
  * The interactive loop — one entry at a time, one letter per decision.
  *

package/dist/holmes/cli/doctor.js

@@ -487,6 +487,38 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
             }
         }
         catch { /* .mcp.json 부재/파싱 실패 → 이 점검 없이 진행 */ }
+        // @implements A-SPEC-259 — the wiring is judged by SPAWNING it. String comparison is exactly how
+        // the dead `npx -y <pkg>@<ver> holmes-mcp` form (npx resolves the default bin and hands
+        // `holmes-mcp` to it as an argument) passed the launcher test, this doctor's own handshake check
+        // (which starts the server directly, not through the wiring), and the release tarball probe —
+        // measured 2026-08-23. A node wiring is judged on path existence (a source checkout must not pay
+        // a spawn), an absent .mcp.json is skipped by name, and the spawn is BOUNDED: it succeeds or
+        // fails inside its deadline, never hangs (REQ-258's lesson, applied from this check onward).
+        {
+            const mcpPath = path.join(target, '.mcp.json');
+            if (!fs.existsSync(mcpPath)) {
+                add('mcp wiring spawn', 'PASS', 'skipped — no .mcp.json in the target: an absent wiring is not a dead one');
+            }
+            else {
+                try {
+                    const server = JSON.parse(fs.readFileSync(mcpPath, 'utf8'))
+                        .mcpServers?.[init_1.SERVER_NAME];
+                    if (!server || typeof server.command !== 'string' || !Array.isArray(server.args)) {
+                        add('mcp wiring spawn', 'WARN', `.mcp.json carries no runnable ${init_1.SERVER_NAME} entry`, 'Run `holmes-kit init` in the target to write the wiring.');
+                    }
+                    else if (server.command === 'node') {
+                        const bin = server.args[0] ?? '';
+                        add('mcp wiring spawn', fs.existsSync(bin) ? 'PASS' : 'FAIL', fs.existsSync(bin) ? `node wiring resolves: ${bin}` : `node wiring points at a missing file: ${bin}`, fs.existsSync(bin) ? undefined : 'Run `holmes-kit init` in the target to rewire the absolute path.');
+                    }
+                    else {
+                        checks.push(await wiringSpawnCheck(server.command, server.args));
+                    }
+                }
+                catch {
+                    add('mcp wiring spawn', 'WARN', 'could not read .mcp.json', 'Run `holmes-kit init` in the target to rewrite the wiring.');
+                }
+            }
+        }
         // @implements A-SPEC-193 — 배선된 하네스마다 그 하네스의 배선을 검사한다. 배선되지 않은
         // 하네스는 진단하지 않는다(없는 것을 결함이라 부르면 doctor 가 소음이 된다).
         const agyHooks = path.join(target, '.agents', 'hooks.json');
@@ -616,6 +648,54 @@ function cleanupOnSignal(dir) {
  * and closes stdin makes the server exit before answering (a false FAIL this check produced on its
  * very first run against a healthy server).
  */
+// @implements A-SPEC-259
+// Spawn the TARGET's wiring verbatim and require initialize inside the deadline. Unlike
+// `mcpHandshakeCheck` below (which proves this INSTALL can serve), this proves the WIRING the
+// harness will actually run reaches a server — the gap the dead npx form lived in.
+function wiringSpawnCheck(command, args, timeoutMs = 30000) {
+    const quoted = `${command} ${args.join(' ')}`;
+    return new Promise((resolve) => {
+        let done = false;
+        let out = '';
+        let child;
+        const finish = (level, detail, fix) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            try {
+                child.kill();
+            }
+            catch { /* already gone */ }
+            resolve({ name: 'mcp wiring spawn', level, detail, fix });
+        };
+        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, then re-run doctor.'), timeoutMs);
+        try {
+            child = (0, node_child_process_1.spawn)(command, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+        }
+        catch (e) {
+            finish('FAIL', `wiring could not be spawned: \`${quoted}\` — ${e.message}`, 'Re-run `holmes-kit init` in the target to rewrite the wiring.');
+            return;
+        }
+        child.on('error', (e) => finish('FAIL', `wiring could not be spawned: \`${quoted}\` — ${e.message}`, 'Re-run `holmes-kit init` in the target to rewrite the wiring.'));
+        child.on('exit', (code) => finish('FAIL', `wiring exited (code ${code}) before answering initialize: \`${quoted}\``, 'Re-run `holmes-kit init` in the target to rewrite the wiring.'));
+        child.stdin?.on('error', () => { });
+        child.stdout?.on('data', (d) => {
+            out += String(d);
+            for (const line of out.split('\n')) {
+                try {
+                    const m = JSON.parse(line);
+                    if (m?.result?.serverInfo) {
+                        finish('PASS', `wiring reaches a live server (v${m.result.serverInfo.version ?? '?'}): \`${quoted}\``);
+                        return;
+                    }
+                }
+                catch { /* partial line */ }
+            }
+        });
+        child.stdin?.write(JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'holmes-doctor', version: '1' } } }) + '\n');
+    });
+}
 function mcpHandshakeCheck(packageRoot, timeoutMs = 15000) {
     return new Promise((resolve) => {
         const mcpCwd = fs.mkdtempSync(path.join(os.tmpdir(), 'holmes-doctor-mcp-'));

package/dist/holmes/cli/index.js

@@ -359,7 +359,7 @@ async function main(argv) {
         // @implements A-SPEC-246 — the surface where a human decides. Interactive on a TTY with no
         // decision flags; every interactive decision has a flag equivalent so a CI or remote operator
         // is never locked out.
-        const { grantRequest, denyRequest, holdRequest, renderPending, runInteractive } = require('./approve');
+        const { grantRequest, denyRequest, holdRequest, renderPending, renderNonTtyHint, runInteractive } = require('./approve');
         const { readQueue } = require('../governance/approval-queue');
         const root = typeof flags.target === 'string' ? path.resolve(flags.target) : process.cwd();
         const actor = (() => { try {
@@ -402,10 +402,18 @@ async function main(argv) {
             process.stdout.write(r.ok ? '✓ 보류 — 질문이 다음 거부 문면에 실립니다\n' : `✗ ${r.reason}\n`);
             return r.ok ? 0 : 1;
         }
-        if (flags.list || !process.stdin.isTTY) {
+        if (flags.list) {
             process.stdout.write(renderPending(readQueue(root)) + '\n');
             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);
+            const hint = renderNonTtyHint(state);
+            process.stdout.write(renderPending(state) + (hint ? '\n\n' + hint : '') + '\n');
+            return 0;
+        }
         const rl = require('node:readline/promises').createInterface({ input: process.stdin, output: process.stdout });
         void runInteractive(root, {
             print: (t) => process.stdout.write(t + '\n'),

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

@@ -52,7 +52,12 @@ exports.MCP_PACKAGE = '@holmes-lab/holmes-kit';
  */
 function mcpServerEntry(opts) {
     if (opts.mode === 'npx') {
-        return { command: 'npx', args: ['-y', `${exports.MCP_PACKAGE}@${opts.version}`, 'holmes-mcp'] };
+        // @implements A-SPEC-259 — the package must ride `-p` with the command named separately.
+        // `npx <pkg> holmes-mcp` runs the package-name-matching DEFAULT bin (holmes-kit) and hands
+        // `holmes-mcp` to it as an argument: measured 2026-08-23, exit 1 "unknown command" — every
+        // npm-installed wiring since the npx pin was a dead server. The `-p` form is the one that
+        // reached initialize in the same measurement.
+        return { command: 'npx', args: ['-y', '-p', `${exports.MCP_PACKAGE}@${opts.version}`, 'holmes-mcp'] };
     }
     return { command: 'node', args: [opts.mcpBinPath] };
 }

package/dist/holmes/mcp/server.js

@@ -12,7 +12,19 @@ const validate_args_1 = require("./validate-args");
 // @implements A-SPEC-100.2
 const store = new spec_store_1.LocalMarkdownRepository(process.env.HOLMES_SPECS ?? '.ax/specs');
 const handlers = (0, handlers_1.makeHandlers)(store);
-const server = new index_js_1.Server({ name: 'holmes-kit', version: '0.1.0' }, { capabilities: { tools: {} } });
+// @implements A-SPEC-259 — the advertised version is the package's own, not a literal that froze at
+// 0.1.0: a hardcoded serverInfo.version blinds any client-side drift diagnosis.
+const PKG_VERSION = (() => {
+    try {
+        // dist/holmes/mcp/server.js → three levels up is the package root, same as the source layout.
+        const raw = require('node:fs').readFileSync(require('node:path').join(__dirname, '..', '..', '..', 'package.json'), 'utf8');
+        return JSON.parse(raw).version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+})();
+const server = new index_js_1.Server({ name: 'holmes-kit', version: PKG_VERSION }, { capabilities: { tools: {} } });
 const fullProfile = process.env.HOLMES_MCP_PROFILE === 'full';
 // Register each handler as a tool with its real typed inputSchema so MCP
 // clients can marshal complex (array/object) arguments; fall back to a

package/dist/holmes/server/dashboard.js

@@ -765,7 +765,7 @@ function renderDashboardHtml() {
         items.forEach(s => { statuses[s.status] = (statuses[s.status] || 0) + 1; });
         const statusSummary = Object.keys(statuses).map(k => escapeHtml(k) + ' × ' + statuses[k]).join(' · ');
         html += '<div class="req-card" style="margin-bottom:20px;">'
-          + '<div class="req-header" onclick="toggleAccordion(\'legacy-body-' + escapeHtml(kind) + '\')">'
+          + '<div class="req-header" onclick="toggleAccordion(\\'legacy-body-' + escapeHtml(kind) + '\\')">'
           + '<div class="req-title-group"><span class="req-id-badge">' + escapeHtml(kind) + '</span>'
           + '<span class="req-title">' + items.length + ' unmapped document' + (items.length === 1 ? '' : 's') + '</span>'
           + '<span class="neighbor-rel badge-unmeasured">' + statusSummary + '</span></div>'
@@ -851,7 +851,7 @@ function renderDashboardHtml() {
       if (!label) {
         return '<td class="' + cls + ' stage-missing" title="No artifact for this stage">' + arrow + '— missing</td>';
       }
-      const onclick = jumpId ? ' onclick="focusSpecInGraph(\'' + escapeHtml(String(jumpId)) + '\')"' : '';
+      const onclick = jumpId ? ' onclick="focusSpecInGraph(\\'' + escapeHtml(String(jumpId)) + '\\')"' : '';
       return '<td class="' + cls + '"' + onclick + '>' + arrow + icon + ' ' + escapeHtml(String(label)) + '</td>';
     }
     // REQ-Grouped Structured 6-Stage Pipeline Heatmap Matrix Renderer

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "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",