@holmes-lab/holmes-kit 0.30.0 → 0.31.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (139) hide show
  1. package/CHANGELOG.md +505 -0
  2. package/README.md +10 -1
  3. package/bin/holmes-hook-antigravity.js +4 -0
  4. package/bin/holmes-kit.js +4 -0
  5. package/bin/holmes-pre-push.js +3 -0
  6. package/bin/holmes-stop-antigravity.js +4 -0
  7. package/dist/.build-id +1 -1
  8. package/dist/holmes/cli/agents.d.ts +41 -0
  9. package/dist/holmes/cli/agents.js +382 -2
  10. package/dist/holmes/cli/attest.d.ts +2 -0
  11. package/dist/holmes/cli/attest.js +66 -15
  12. package/dist/holmes/cli/ci-gate.js +16 -1
  13. package/dist/holmes/cli/claude-switches.d.ts +95 -0
  14. package/dist/holmes/cli/claude-switches.js +967 -0
  15. package/dist/holmes/cli/codex-hooks.d.ts +77 -0
  16. package/dist/holmes/cli/codex-hooks.js +802 -0
  17. package/dist/holmes/cli/codex-oracle.d.ts +194 -0
  18. package/dist/holmes/cli/codex-oracle.js +1245 -0
  19. package/dist/holmes/cli/codex-toml.d.ts +35 -0
  20. package/dist/holmes/cli/codex-toml.js +321 -52
  21. package/dist/holmes/cli/doctor.d.ts +98 -8
  22. package/dist/holmes/cli/doctor.js +1328 -94
  23. package/dist/holmes/cli/index.js +26 -11
  24. package/dist/holmes/cli/init.d.ts +11 -0
  25. package/dist/holmes/cli/init.js +736 -44
  26. package/dist/holmes/cli/mcp-launcher.d.ts +64 -6
  27. package/dist/holmes/cli/mcp-launcher.js +189 -6
  28. package/dist/holmes/cli/mcp-version.js +13 -2
  29. package/dist/holmes/cli/settings-merge.js +8 -2
  30. package/dist/holmes/cli/upgrade.d.ts +18 -0
  31. package/dist/holmes/cli/upgrade.js +129 -24
  32. package/dist/holmes/cli/workspace-scope.d.ts +22 -0
  33. package/dist/holmes/cli/workspace-scope.js +375 -0
  34. package/dist/holmes/cpg/cpg-scanner.d.ts +29 -0
  35. package/dist/holmes/cpg/cpg-scanner.js +403 -3
  36. package/dist/holmes/cpg/cycle-detect.js +2 -1
  37. package/dist/holmes/cpg/forbidden-edges.js +9 -2
  38. package/dist/holmes/cpg/required-calls.js +8 -1
  39. package/dist/holmes/governance/constitution-debt.js +3 -2
  40. package/dist/holmes/governance/constitution.js +15 -3
  41. package/dist/holmes/governance/provenance-chain.js +3 -2
  42. package/dist/holmes/governance/push-gate-runner.js +4 -3
  43. package/dist/holmes/guardrail/dependency-delta.js +4 -3
  44. package/dist/holmes/guardrail/linear-match.d.ts +57 -0
  45. package/dist/holmes/guardrail/linear-match.js +256 -0
  46. package/dist/holmes/guardrail/risk-classifier.d.ts +6 -7
  47. package/dist/holmes/guardrail/risk-classifier.js +931 -44
  48. package/dist/holmes/guardrail/risk-types.d.ts +6 -0
  49. package/dist/holmes/guardrail/scope-judgment.d.ts +4 -24
  50. package/dist/holmes/guardrail/scope-judgment.js +100 -23
  51. package/dist/holmes/guardrail/shell-words.d.ts +42 -0
  52. package/dist/holmes/guardrail/shell-words.js +1720 -0
  53. package/dist/holmes/guardrail/write-target.d.ts +168 -3
  54. package/dist/holmes/guardrail/write-target.js +2379 -87
  55. package/dist/holmes/hooks/adapters/antigravity.d.ts +3 -1
  56. package/dist/holmes/hooks/adapters/antigravity.js +115 -11
  57. package/dist/holmes/hooks/pre-tool-use.d.ts +32 -6
  58. package/dist/holmes/hooks/pre-tool-use.js +923 -87
  59. package/dist/holmes/hooks/rtm-refresh-child.js +3 -1
  60. package/dist/holmes/hooks/rtm-refresh.js +8 -4
  61. package/dist/holmes/hooks/session-start.d.ts +10 -0
  62. package/dist/holmes/hooks/session-start.js +31 -7
  63. package/dist/holmes/hooks/stop.d.ts +2 -1
  64. package/dist/holmes/hooks/stop.js +197 -91
  65. package/dist/holmes/mcp/approval-commit.d.ts +5 -6
  66. package/dist/holmes/mcp/approval-commit.js +18 -2
  67. package/dist/holmes/mcp/elicit-approval.js +4 -2
  68. package/dist/holmes/mcp/handlers/graph-operations.js +3 -2
  69. package/dist/holmes/mcp/handlers/maintenance-analysis.js +11 -5
  70. package/dist/holmes/mcp/handlers/maintenance-evidence.js +3 -2
  71. package/dist/holmes/mcp/handlers/phase-queries.d.ts +22 -7
  72. package/dist/holmes/mcp/handlers/phase-queries.js +81 -2
  73. package/dist/holmes/mcp/handlers/requirement-triage.js +5 -3
  74. package/dist/holmes/mcp/handlers/review-evidence.js +8 -2
  75. package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +11 -0
  76. package/dist/holmes/mcp/handlers/slice-orchestration.js +115 -16
  77. package/dist/holmes/mcp/handlers/spec-approval.d.ts +9 -0
  78. package/dist/holmes/mcp/handlers/spec-approval.js +110 -17
  79. package/dist/holmes/mcp/handlers/spec-authoring.js +17 -2
  80. package/dist/holmes/mcp/handlers/spec-queries.d.ts +39 -3
  81. package/dist/holmes/mcp/handlers/spec-queries.js +114 -7
  82. package/dist/holmes/mcp/handlers/test-execution.js +9 -3
  83. package/dist/holmes/mcp/handlers.d.ts +81 -9
  84. package/dist/holmes/mcp/handlers.js +70 -23
  85. package/dist/holmes/mcp/harness-attestation.d.ts +20 -0
  86. package/dist/holmes/mcp/harness-attestation.js +179 -0
  87. package/dist/holmes/mcp/requirement-triage-evidence.d.ts +36 -0
  88. package/dist/holmes/mcp/requirement-triage-evidence.js +160 -4
  89. package/dist/holmes/mcp/server.js +20 -1
  90. package/dist/holmes/mcp/tool-schemas.js +26 -9
  91. package/dist/holmes/mcp/validate-args.js +12 -0
  92. package/dist/holmes/project/bounded-io.d.ts +102 -0
  93. package/dist/holmes/project/bounded-io.js +212 -0
  94. package/dist/holmes/project/change-source.js +3 -1
  95. package/dist/holmes/project/ci-runs.js +3 -2
  96. package/dist/holmes/project/ignore.d.ts +31 -2
  97. package/dist/holmes/project/ignore.js +409 -50
  98. package/dist/holmes/project/regular-file-guard.d.ts +13 -0
  99. package/dist/holmes/project/regular-file-guard.js +149 -0
  100. package/dist/holmes/project/root.js +12 -3
  101. package/dist/holmes/reverse/anchor.js +4 -3
  102. package/dist/holmes/reverse/scan.js +6 -2
  103. package/dist/holmes/review/commit-text.js +3 -2
  104. package/dist/holmes/review/condition-hunk-replay.js +3 -2
  105. package/dist/holmes/review/failed-test-names.js +13 -10
  106. package/dist/holmes/review/findings.js +3 -1
  107. package/dist/holmes/review/kills-check.js +6 -1
  108. package/dist/holmes/review/point-in-time-replay.js +5 -4
  109. package/dist/holmes/review/replay-corpus.js +5 -4
  110. package/dist/holmes/review/run-replay.js +3 -2
  111. package/dist/holmes/review/temporal-prior.js +3 -2
  112. package/dist/holmes/review/test-evidence.js +3 -2
  113. package/dist/holmes/review/test-outcomes.js +3 -2
  114. package/dist/holmes/review/test-runner.d.ts +6 -0
  115. package/dist/holmes/review/test-runner.js +36 -15
  116. package/dist/holmes/rtm/advisory-outcomes.js +3 -2
  117. package/dist/holmes/rtm/anchor-ids.js +42 -2
  118. package/dist/holmes/rtm/file-anchors.js +4 -1
  119. package/dist/holmes/rtm/ftt-fulfilment.js +8 -3
  120. package/dist/holmes/rtm/git-changes.js +3 -1
  121. package/dist/holmes/rtm/graph-store.js +3 -2
  122. package/dist/holmes/rtm/test-scope.js +9 -4
  123. package/dist/holmes/spec/compat-impact.d.ts +25 -4
  124. package/dist/holmes/spec/compat-impact.js +682 -11
  125. package/dist/holmes/spec/entity-git-snapshot.js +3 -2
  126. package/dist/holmes/spec/entity-integration.js +3 -2
  127. package/dist/holmes/spec/entity-renumber-transaction.d.ts +19 -0
  128. package/dist/holmes/spec/entity-renumber-transaction.js +79 -6
  129. package/dist/holmes/spec/remote-spec-refs.js +3 -2
  130. package/dist/holmes/spec/renumber.js +25 -10
  131. package/dist/holmes/spec/spec-parser.js +9 -3
  132. package/dist/holmes/spec/yaml-scalar.js +2 -2
  133. package/dist/holmes/update/refresh.d.ts +5 -0
  134. package/dist/holmes/update/refresh.js +26 -1
  135. package/dist/holmes/update/update-notice.d.ts +6 -0
  136. package/dist/holmes/update/update-notice.js +18 -1
  137. package/dist/holmes/update/upgrade-plan.d.ts +28 -0
  138. package/dist/holmes/update/upgrade-plan.js +31 -2
  139. package/package.json +11 -4
@@ -5,10 +5,13 @@
5
5
  * (codex, TOML `[mcp_servers.holmes-kit]` — A-SPEC-266) 세 배선이 같은 서버를 띄운다. 셋이 각자 command/args 를 지으면 하나가 npx 로 옮겨갈 때 나머지가
6
6
  * 절대경로에 남아 어긋난다 — 그 드리프트가 REQ-251 자체의 출발점이었다.
7
7
  *
8
- * 왜 두 모드인가: 최종 사용자는 npm 설치본에서 init 하므로 `npx ...@<정확한버전> holmes-mcp` 가
9
- * 옳다 — 전역 설치도 `-g` 도 필요 없고(Windows EPERM 회피), 절대경로 고착이 없다. 그러나 개발
10
- * 저장소(소스 체크아웃)는 아직 발행되지 않은 working tree 를 쓰므로 npx 로 레지스트리를 당기면 안
11
- * 된다 — 로컬 dist 를 직접 부르는 node 배선이 맞다. 그래서 기본은 packageRoot 성격으로 자동 판별한다.
8
+ * 왜 두 모드인가: 0.31.0 전까지 npm 설치본은 `npx ...@<정확한버전> holmes-mcp` 로 배선됐다 — 전역 설치도
9
+ * `-g` 도 필요 없고(Windows EPERM 회피), 절대경로 고착이 없었다. 그러나 npx 는 하네스가 여는 작업공간마다
10
+ * npm 을 돌리고, npm 은 그 작업공간의 `.npmrc`(node-options, registry)와 `node_modules` 를 읽는다 — 저장소의
11
+ * `.npmrc` 한 줄이나 같은 버전으로 심은 패키지가 게이트 서버 자리에서 돌았다(실측, 2026-09-25/26).
12
+ * @implements A-SPEC-251.1 (0.31.0) — 그래서 안정된 설치 경로가 있으면(전역, 프로젝트 로컬, 소스 체크아웃)
13
+ * `node <설치>/bin/holmes-mcp.js`, 곧 지워질 임시 실행 캐시에서만 npx 핀을 쓴다. 고착은 doctor 의 버전
14
+ * 드리프트 점검(A-SPEC-251.2)이 드러낸다.
12
15
  */
13
16
  export type LauncherMode = 'npx' | 'node';
14
17
  export interface McpServerEntry {
@@ -29,11 +32,23 @@ export declare function mcpServerEntry(opts: {
29
32
  version: string;
30
33
  mcpBinPath: string;
31
34
  }): McpServerEntry;
35
+ /**
36
+ * 설치 없이 실행한 임시 실행 캐시인가 — 순수, 경로 문자열만 본다. 그런 경로는 곧 지워지므로 절대경로로 박을 수 없다.
37
+ * Windows 구분자(`\`)는 `/` 로 정규화한다.
38
+ * @implements A-SPEC-251.1 (확인 라운드 22) — 세그먼트 이름이 아니라 캐시의 **모양**: `/mnt/xfs-data/…`, `/home/dlx/…`,
39
+ * `/src/dlx/holmes-kit` 가 임시 캐시로 읽혀 npx 로 배선됐다(실측).
40
+ * - npm: `…/_npx/<hex>/node_modules/…` (npm 7+; 이 기기 npm 11.17.0 의 `~/.npm/_npx/<16 hex>/` 실측)
41
+ * - pnpm: `…/pnpm…/dlx/<id>/…`
42
+ * - bunx: `…/bunx-<uid>-<pkg>@<ver>/node_modules/…`, bun 의 `…/.bun/install/cache/…`; pnpm 7/8: `…/dlx-<pid>/node_modules/…`
43
+ * - yarn: `…/xfs-<8 hex>/dlx-<n>/…`
44
+ */
45
+ export declare function isEphemeralInstall(packageRoot: string): boolean;
46
+ /** init 이 npx 로 배선했을 때 한 번 출력하는 안내(A-SPEC-251.1, 0.31.0). 원인을 단정하지 않는다(확인 라운드 22). */
47
+ export declare const NPX_WIRING_NOTE = "The MCP server is wired through npx (holmes-kit ran from a temporary exec cache, or --mcp-launcher npx asked for it). npx runs npm in each session workspace, and that workspace's .npmrc (node-options, registry) and node_modules can replace the Holmes server. Install holmes-kit (npm install -g @holmes-lab/holmes-kit, or as a devDependency), then re-run holmes-kit init --force from that install to wire node <install>/bin/holmes-mcp.js.";
32
48
  /**
33
49
  * 기본 모드를 정한다 — 순수, 경로 문자열만 본다(파일시스템 조회 없음).
34
50
  *
35
- * `flag` 가 명시되면 그대로. 없으면 packageRoot 가 설치본 세그먼트를 포함하면 npx, 아니면 node.
36
- * Windows 구분자(`\`)를 `/` 로 정규화해 비교하므로 두 OS 의 설치 경로가 같게 인식된다.
51
+ * `flag` 가 명시되면 그대로. 없으면 임시 실행 캐시만 npx, 나머지(전역·프로젝트 로컬 설치, 소스 체크아웃)는 node.
37
52
  */
38
53
  export declare function resolveLauncherMode(opts: {
39
54
  flag?: LauncherMode;
@@ -53,3 +68,46 @@ export declare function mcpEntryForInstall(opts: {
53
68
  flag?: LauncherMode;
54
69
  readVersion?: (packageRoot: string) => string | undefined;
55
70
  }): McpServerEntry;
71
+ /**
72
+ * @implements A-SPEC-251.2 (round 30; round 46: shared with init) — where the launcher, started in `cwd`, finds a bare command: POSIX walks PATH in
73
+ * order (a relative or empty entry from `cwd` — a `.` entry ran the target's own `node`, measured); win32 looks in `cwd`
74
+ * first (libuv and cmd both do — code reading, not measured on Windows), then PATH.
75
+ */
76
+ export declare function launcherLookup(cwd: string, word: string, platform?: NodeJS.Platform, envPath?: string, pathExt?: string): string | null;
77
+ /**
78
+ * @implements A-SPEC-251.2 (round 47) — the hit and how it was found: `relative` when the directory it was found in depends on
79
+ * where the command runs (the directory itself on win32, a relative or empty PATH entry). win32 tries the `PATHEXT` extensions
80
+ * and no extensionless file (cmd runs `node.vbs` from the directory before PATH's `node.exe` — code reading, not measured on
81
+ * Windows).
82
+ */
83
+ export declare function launcherFind(cwd: string, word: string, platform?: NodeJS.Platform, envPath?: string, pathExt?: string, cwdFirst?: boolean): {
84
+ file: string;
85
+ relative: boolean;
86
+ } | null;
87
+ /**
88
+ * @implements A-SPEC-251.2 (round 47) — the gate's `node` where the harness runs its hooks: found through the directory or a
89
+ * relative PATH entry it is whatever that directory holds (FAIL); found through an absolute entry but inside the workspace it
90
+ * may be the workspace's own toolchain (nodeenv, `node_modules/.bin/node`) — not confirmed (WARN; round 46 read FAIL).
91
+ */
92
+ export declare function gateNodeFinding(cwd: string, inside: (real: string) => boolean, cwdFirst?: boolean): {
93
+ level: 'FAIL' | 'WARN';
94
+ file: string;
95
+ missing?: true;
96
+ } | null;
97
+ export declare function launcherPlaces(file: string): string[] | null;
98
+ /** Whether a found file, anywhere on its link chain, is inside (a chain past the bound is read as inside). */
99
+ export declare function launcherFoundInside(file: string, inside: (place: string) => boolean): boolean;
100
+ /**
101
+ * @implements A-SPEC-251.2 (round 52, owner decision 2026-09-28) — the environment doctor starts its wiring probes in: the
102
+ * directory of the node that runs doctor leads PATH, so what a probe starts is doctor's own node and what stands beside it,
103
+ * not what the workspace put on PATH. Deciding whether to run by reading PATH as the launcher does was passed wave after
104
+ * wave (a PATH entry's `..` folded as text, a shim without an interpreter skipped by the OS, a directory-link hop, the home
105
+ * exemption read as leave to run). The PATH key keeps the spelling the environment has (`Path` on Windows).
106
+ */
107
+ export declare function probePathOf(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, own?: string, keep?: (entry: string) => boolean): string;
108
+ export declare function probeEnv(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, keep?: (entry: string) => boolean): NodeJS.ProcessEnv;
109
+ /** @implements A-SPEC-251.2 (round 50) — what doctor and init say about a gate `node` that is not confirmed. */
110
+ export declare function gateNodeUnconfirmed(hit: {
111
+ file: string;
112
+ missing?: true;
113
+ }, clip: (s: string) => string): string;
@@ -33,11 +33,20 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.MCP_PACKAGE = void 0;
36
+ exports.NPX_WIRING_NOTE = exports.MCP_PACKAGE = void 0;
37
37
  exports.mcpServerEntry = mcpServerEntry;
38
+ exports.isEphemeralInstall = isEphemeralInstall;
38
39
  exports.resolveLauncherMode = resolveLauncherMode;
39
40
  exports.readPackageVersion = readPackageVersion;
40
41
  exports.mcpEntryForInstall = mcpEntryForInstall;
42
+ exports.launcherLookup = launcherLookup;
43
+ exports.launcherFind = launcherFind;
44
+ exports.gateNodeFinding = gateNodeFinding;
45
+ exports.launcherPlaces = launcherPlaces;
46
+ exports.launcherFoundInside = launcherFoundInside;
47
+ exports.probePathOf = probePathOf;
48
+ exports.probeEnv = probeEnv;
49
+ exports.gateNodeUnconfirmed = gateNodeUnconfirmed;
41
50
  // @implements A-SPEC-251.1
42
51
  const fs = __importStar(require("node:fs"));
43
52
  const path = __importStar(require("node:path"));
@@ -61,18 +70,38 @@ function mcpServerEntry(opts) {
61
70
  }
62
71
  return { command: 'node', args: [opts.mcpBinPath] };
63
72
  }
64
- const INSTALLED_SEGMENT = 'node_modules/@holmes-lab/holmes-kit';
73
+ /**
74
+ * 설치 없이 실행한 임시 실행 캐시인가 — 순수, 경로 문자열만 본다. 그런 경로는 곧 지워지므로 절대경로로 박을 수 없다.
75
+ * Windows 구분자(`\`)는 `/` 로 정규화한다.
76
+ * @implements A-SPEC-251.1 (확인 라운드 22) — 세그먼트 이름이 아니라 캐시의 **모양**: `/mnt/xfs-data/…`, `/home/dlx/…`,
77
+ * `/src/dlx/holmes-kit` 가 임시 캐시로 읽혀 npx 로 배선됐다(실측).
78
+ * - npm: `…/_npx/<hex>/node_modules/…` (npm 7+; 이 기기 npm 11.17.0 의 `~/.npm/_npx/<16 hex>/` 실측)
79
+ * - pnpm: `…/pnpm…/dlx/<id>/…`
80
+ * - bunx: `…/bunx-<uid>-<pkg>@<ver>/node_modules/…`, bun 의 `…/.bun/install/cache/…`; pnpm 7/8: `…/dlx-<pid>/node_modules/…`
81
+ * - yarn: `…/xfs-<8 hex>/dlx-<n>/…`
82
+ */
83
+ function isEphemeralInstall(packageRoot) {
84
+ const p = `${packageRoot.replace(/\\/g, '/')}/`;
85
+ return /\/_npx\/[0-9a-f]{8,}\/node_modules\//i.test(p)
86
+ || /\/pnpm[^/]*\/dlx\/[^/]+\//.test(p)
87
+ || /\/bunx-\d+-(?:@[^/]+\/)?[^/]+@[^/]+\/node_modules\//.test(p) // bunx-<uid>-<pkg>@<ver> (round 23: `bunx-2024-demo` is an install)
88
+ // pnpm 7/8: $TMPDIR/dlx-<pid> (round 23) — only directly under a temporary directory (round 25: the round-24
89
+ // text said so and the code did not; `/Users/me/code/dlx-2/…` was wired with npx — measured)
90
+ || /\/(?:tmp|T|Temp)\/dlx-\d+\/node_modules\//i.test(p)
91
+ || /\/\.bun\/install\/cache\//.test(p)
92
+ || /\/xfs-[0-9a-f]{8}\/dlx-\d+\//.test(p);
93
+ }
94
+ /** init 이 npx 로 배선했을 때 한 번 출력하는 안내(A-SPEC-251.1, 0.31.0). 원인을 단정하지 않는다(확인 라운드 22). */
95
+ exports.NPX_WIRING_NOTE = 'The MCP server is wired through npx (holmes-kit ran from a temporary exec cache, or --mcp-launcher npx asked for it). npx runs npm in each session workspace, and that workspace\'s .npmrc (node-options, registry) and node_modules can replace the Holmes server. Install holmes-kit (npm install -g @holmes-lab/holmes-kit, or as a devDependency), then re-run holmes-kit init --force from that install to wire node <install>/bin/holmes-mcp.js.';
65
96
  /**
66
97
  * 기본 모드를 정한다 — 순수, 경로 문자열만 본다(파일시스템 조회 없음).
67
98
  *
68
- * `flag` 가 명시되면 그대로. 없으면 packageRoot 가 설치본 세그먼트를 포함하면 npx, 아니면 node.
69
- * Windows 구분자(`\`)를 `/` 로 정규화해 비교하므로 두 OS 의 설치 경로가 같게 인식된다.
99
+ * `flag` 가 명시되면 그대로. 없으면 임시 실행 캐시만 npx, 나머지(전역·프로젝트 로컬 설치, 소스 체크아웃)는 node.
70
100
  */
71
101
  function resolveLauncherMode(opts) {
72
102
  if (opts.flag)
73
103
  return opts.flag;
74
- const normalized = opts.packageRoot.replace(/\\/g, '/');
75
- return normalized.includes(INSTALLED_SEGMENT) ? 'npx' : 'node';
104
+ return isEphemeralInstall(opts.packageRoot) ? 'npx' : 'node';
76
105
  }
77
106
  /** packageRoot/package.json 의 version. 못 읽으면 undefined — 이것이 node 물러남을 부른다. */
78
107
  function readPackageVersion(packageRoot) {
@@ -99,3 +128,157 @@ function mcpEntryForInstall(opts) {
99
128
  }
100
129
  return mcpServerEntry({ mode, version: version ?? '', mcpBinPath: opts.mcpBinPath });
101
130
  }
131
+ /**
132
+ * @implements A-SPEC-251.2 (round 30; round 46: shared with init) — where the launcher, started in `cwd`, finds a bare command: POSIX walks PATH in
133
+ * order (a relative or empty entry from `cwd` — a `.` entry ran the target's own `node`, measured); win32 looks in `cwd`
134
+ * first (libuv and cmd both do — code reading, not measured on Windows), then PATH.
135
+ */
136
+ function launcherLookup(cwd, word, platform = process.platform, envPath = process.env.PATH ?? process.env.Path ?? '', pathExt = process.env.PATHEXT ?? WIN32_PATHEXT) {
137
+ return launcherFind(cwd, word, platform, envPath, pathExt)?.file ?? null;
138
+ }
139
+ /** cmd's default `PATHEXT`. */
140
+ const WIN32_PATHEXT = '.COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC';
141
+ /**
142
+ * @implements A-SPEC-251.2 (round 47) — the hit and how it was found: `relative` when the directory it was found in depends on
143
+ * where the command runs (the directory itself on win32, a relative or empty PATH entry). win32 tries the `PATHEXT` extensions
144
+ * and no extensionless file (cmd runs `node.vbs` from the directory before PATH's `node.exe` — code reading, not measured on
145
+ * Windows).
146
+ */
147
+ function launcherFind(cwd, word, platform = process.platform, envPath = process.env.PATH ?? process.env.Path ?? '', pathExt = process.env.PATHEXT ?? WIN32_PATHEXT, cwdFirst = true) {
148
+ if (platform === 'win32') {
149
+ // Round 48: an empty PATHEXT is cmd's default list. Round 49: so is one that filters to nothing (`;`).
150
+ const usable = (list) => list.split(';').map((e) => e.trim().toLowerCase()).filter((e) => /^\.[^\\/]{1,16}$/.test(e)).slice(0, 64);
151
+ const exts = usable(pathExt).length > 0 ? usable(pathExt) : usable(WIN32_PATHEXT);
152
+ const absolute = (e) => /^(?:[A-Za-z]:[\\/]|[\\/]{2})/.test(e) || path.isAbsolute(e);
153
+ // @implements A-SPEC-251.2 (round 49) — the directory first is cmd's and libuv's rule (agy runs hooks through `cmd /c`);
154
+ // Claude runs them through bash or PowerShell, which find `node` on PATH: `cwdFirst: false` (a `node.js` in the workspace
155
+ // root read FAIL for an untouched Claude wiring — platform argument, not measured on Windows).
156
+ for (const dir of [...(cwdFirst ? [{ at: cwd, relative: true }] : []),
157
+ // Round 50: cmd reads an entry in double quotes without them (`"C:\tools"` was resolved under the directory and skipped).
158
+ ...envPath.split(';').map((e) => e.replace(/^"(.*)"$/, '$1')).filter((e) => e !== '').map((e) => ({ at: path.resolve(cwd, e), relative: !absolute(e) }))]) {
159
+ for (const ext of exts) {
160
+ const c = path.join(dir.at, word + ext);
161
+ try {
162
+ if (fs.statSync(c).isFile())
163
+ return { file: c, relative: dir.relative };
164
+ }
165
+ catch { /* not here */ }
166
+ }
167
+ }
168
+ return null;
169
+ }
170
+ for (const entry of envPath.split(':')) {
171
+ // Round 52: the entry as written, not folded — the kernel walks `L/..` on disk (`<out>/L/../bin` with `L` a directory link
172
+ // into the workspace is the workspace's `bin`; folded as text it read as `<out>/bin`).
173
+ const c = `${entry === '' ? cwd : path.isAbsolute(entry) ? entry : `${cwd}${path.sep}${entry}`}${path.sep}${word}`;
174
+ // Round 51: a file THIS user can execute — the shell skips one it cannot and runs the next entry's (execute bits for
175
+ // others only read as the hit, and doctor started the workspace's `node` behind it — measured).
176
+ try {
177
+ const st = fs.statSync(c);
178
+ if (st.isFile() && (st.mode & 0o111) !== 0) {
179
+ fs.accessSync(c, fs.constants.X_OK);
180
+ return { file: c, relative: !path.isAbsolute(entry) };
181
+ }
182
+ }
183
+ catch { /* not here */ }
184
+ }
185
+ return null;
186
+ }
187
+ /**
188
+ * @implements A-SPEC-251.2 (round 47) — the gate's `node` where the harness runs its hooks: found through the directory or a
189
+ * relative PATH entry it is whatever that directory holds (FAIL); found through an absolute entry but inside the workspace it
190
+ * may be the workspace's own toolchain (nodeenv, `node_modules/.bin/node`) — not confirmed (WARN; round 46 read FAIL).
191
+ */
192
+ function gateNodeFinding(cwd, inside, cwdFirst = true) {
193
+ const hit = launcherFind(cwd, 'node', process.platform, process.env.PATH ?? process.env.Path ?? '', process.env.PATHEXT ?? WIN32_PATHEXT, cwdFirst);
194
+ // @implements A-SPEC-251.2 (round 50) — no `node` anywhere on PATH: the hook command cannot start (read PASS and "enforced").
195
+ if (hit === null)
196
+ return { level: 'WARN', file: '', missing: true };
197
+ if (hit.relative)
198
+ return { level: 'FAIL', file: hit.file };
199
+ // Round 50: where the file LIES counts as well as what it is — a workspace link `node_modules/.bin/node -> /usr/bin/true`
200
+ // read PASS because only its destination was judged. Round 51: every place on the link chain.
201
+ return launcherFoundInside(hit.file, inside) ? { level: 'WARN', file: hit.file } : null;
202
+ }
203
+ /**
204
+ * @implements A-SPEC-251.2 (round 51) — the places a found file passes through on its way to the real file: as spelled, its
205
+ * directory's real path with its name, and where each link points next (a PATH entry `<ws>/ext` that is a directory link to
206
+ * the outside, and `<outside>/node -> <ws>/hop -> node`, read PASS — measured). Null past 40 places.
207
+ * The next place is where the KERNEL lands: the directory part of a link's text is resolved on disk (`x/L/../node2` with `L`
208
+ * a directory link: `..` is the parent of what `L` points at — folded as text it read "outside" and doctor started the
209
+ * workspace's file, a regression of this round's first form found before it was committed). The last place is the real file.
210
+ */
211
+ const LAUNCHER_PLACES_MAX = 40;
212
+ function launcherPlaces(file) {
213
+ const places = [];
214
+ let at = path.isAbsolute(file) ? file : path.resolve(file);
215
+ for (let i = 0; i <= LAUNCHER_PLACES_MAX; i++) {
216
+ // Round 52 (fourth repair): the spelling folded as text — a place is asked "inside?" by walking up its directories, and
217
+ // an unfolded `<ws>/../out/bin/node` walks up through the workspace it only passes (an untouched wiring read "not
218
+ // confirmed" — measured). Where the kernel lands through a link is the real-path place below.
219
+ places.push(path.resolve(at));
220
+ let lies = at;
221
+ try {
222
+ lies = path.join(fs.realpathSync.native(path.dirname(at)), path.basename(at));
223
+ if (lies !== at)
224
+ places.push(lies);
225
+ }
226
+ catch { /* as spelled */ }
227
+ let next;
228
+ try {
229
+ if (!fs.lstatSync(lies).isSymbolicLink())
230
+ return places;
231
+ next = fs.readlinkSync(lies);
232
+ }
233
+ catch {
234
+ return places;
235
+ }
236
+ const raw = path.isAbsolute(next) ? next : path.join(path.dirname(lies), next);
237
+ const asText = path.resolve(path.dirname(lies), next);
238
+ try {
239
+ at = path.join(fs.realpathSync.native(path.dirname(path.isAbsolute(next) ? next : `${path.dirname(lies)}${path.sep}${next}`)), path.basename(raw));
240
+ }
241
+ catch {
242
+ at = asText;
243
+ }
244
+ if (at !== asText)
245
+ places.push(asText);
246
+ }
247
+ return null;
248
+ }
249
+ /** Whether a found file, anywhere on its link chain, is inside (a chain past the bound is read as inside). */
250
+ function launcherFoundInside(file, inside) {
251
+ const places = launcherPlaces(file);
252
+ return places === null || places.some((p) => inside(p));
253
+ }
254
+ /**
255
+ * @implements A-SPEC-251.2 (round 52, owner decision 2026-09-28) — the environment doctor starts its wiring probes in: the
256
+ * directory of the node that runs doctor leads PATH, so what a probe starts is doctor's own node and what stands beside it,
257
+ * not what the workspace put on PATH. Deciding whether to run by reading PATH as the launcher does was passed wave after
258
+ * wave (a PATH entry's `..` folded as text, a shim without an interpreter skipped by the OS, a directory-link hop, the home
259
+ * exemption read as leave to run). The PATH key keeps the spelling the environment has (`Path` on Windows).
260
+ */
261
+ function probePathOf(env = process.env, platform = process.platform, own = path.dirname(process.execPath), keep = () => true) {
262
+ const key = Object.keys(env).find((k) => (platform === 'win32' ? k.toUpperCase() === 'PATH' : k === 'PATH'));
263
+ const delimiter = platform === 'win32' ? ';' : ':';
264
+ const absolute = (e) => (platform === 'win32' ? /^(?:[A-Za-z]:[\\/]|[\\/]{2})/.test(e) : e.startsWith('/'));
265
+ // Third repair (owner decision 2026-09-28): relative and empty entries are dropped, and absolute ones the caller does not
266
+ // keep (those inside the workspace) — a probe's child looks its own helpers up through PATH (npm starts `sh`), and a
267
+ // workspace directory on PATH chose them (measured with stand-ins).
268
+ const rest = (key === undefined ? '' : env[key] ?? '').split(delimiter).filter((e) => e !== '' && absolute(e) && keep(e));
269
+ // A directory holding the delimiter would split into entries (a colon made a relative entry): it is not put in front.
270
+ return [...(own.includes(delimiter) ? [] : [own]), ...rest].join(delimiter);
271
+ }
272
+ function probeEnv(env = process.env, platform = process.platform, keep = () => true) {
273
+ const key = Object.keys(env).find((k) => (platform === 'win32' ? k.toUpperCase() === 'PATH' : k === 'PATH')) ?? 'PATH';
274
+ // Round 52 (fifth repair): a probe starts no supervisor — with HOLMES_MCP_AUTORELOAD the server's supervisor starts the
275
+ // bare word `node`, found through what is left of PATH where doctor's node is not the `node` of its directory, and waits on
276
+ // children that die silently (doctor took 31.7 s — measured).
277
+ const kept = Object.fromEntries(Object.entries(env).filter(([k]) => (platform === 'win32' ? k.toUpperCase() : k) !== 'HOLMES_MCP_AUTORELOAD'));
278
+ return { ...kept, [key]: probePathOf(env, platform, undefined, keep) };
279
+ }
280
+ /** @implements A-SPEC-251.2 (round 50) — what doctor and init say about a gate `node` that is not confirmed. */
281
+ function gateNodeUnconfirmed(hit, clip) {
282
+ return hit.missing === true ? '"node" is not found on PATH, so the hook command cannot start from here — whether the harness finds one is not confirmed'
283
+ : `"node" is found as ${clip(hit.file)}, a file inside this workspace — whether it is node is not confirmed`;
284
+ }
@@ -39,6 +39,9 @@ exports.versionDriftVerdict = versionDriftVerdict;
39
39
  const path = __importStar(require("node:path"));
40
40
  /** npx 인자에서 핀 버전을 뽑는 정규식: `@holmes-lab/holmes-kit@<X>` 의 X. `@` 없는 스펙은 안 잡힌다. */
41
41
  const NPX_PIN = /^@holmes-lab\/holmes-kit@(.+)$/;
42
+ /** Round 23: the bounds on a node wiring's version walk (PATH_MAX; levels above the bin). */
43
+ const MAX_WIRING_PATH = 4096;
44
+ const MAX_WIRING_LEVELS = 64;
42
45
  /**
43
46
  * 배선이 띄울 버전, 또는 못 뽑으면 null.
44
47
  *
@@ -50,6 +53,8 @@ const NPX_PIN = /^@holmes-lab\/holmes-kit@(.+)$/;
50
53
  function mcpLaunchVersion(entry, readVersion) {
51
54
  if (entry.command === 'npx') {
52
55
  for (const a of entry.args) {
56
+ if (typeof a !== 'string' || a.length > 512)
57
+ continue;
53
58
  const m = NPX_PIN.exec(a);
54
59
  if (m)
55
60
  return m[1];
@@ -57,12 +62,17 @@ function mcpLaunchVersion(entry, readVersion) {
57
62
  return null;
58
63
  }
59
64
  if (entry.command === 'node') {
60
- if (!readVersion || entry.args.length === 0)
65
+ if (!readVersion || entry.args.length === 0 || typeof entry.args[0] !== 'string')
66
+ return null;
67
+ // @implements A-SPEC-251.2 (confirmation round 23) — a wiring file is repository input: a path no system opens is
68
+ // not judged, and the walk stops after 64 levels (each level joins the whole path — a 64 KB path took 11.9 s
69
+ // in doctor, and SessionStart's drift nudge calls this too — measured).
70
+ if (entry.args[0].length > MAX_WIRING_PATH)
61
71
  return null;
62
72
  let dir = path.dirname(entry.args[0]);
63
73
  // Walk up to the filesystem root, asking the reader at each level. `path.dirname('/') === '/'`,
64
74
  // so the loop terminates when dir stops shrinking.
65
- for (;;) {
75
+ for (let level = 0; level < MAX_WIRING_LEVELS; level++) {
66
76
  const v = readVersion(dir);
67
77
  if (v)
68
78
  return v;
@@ -71,6 +81,7 @@ function mcpLaunchVersion(entry, readVersion) {
71
81
  return null;
72
82
  dir = parent;
73
83
  }
84
+ return null;
74
85
  }
75
86
  return null;
76
87
  }
@@ -58,8 +58,14 @@ function removeHooks(existing) {
58
58
  return out;
59
59
  const hooks = {};
60
60
  for (const [event, groups] of Object.entries(out.hooks)) {
61
- const kept = (groups ?? [])
62
- .map((g) => ({ ...g, hooks: (g.hooks ?? []).filter((h) => !isHolmesCommand(h.command)) }))
61
+ // A-SPEC-251.1 round 34: a key beside the events that Claude drops (`"matcher": "x"`) is kept as it is.
62
+ if (!Array.isArray(groups)) {
63
+ if (groups !== null && groups !== undefined)
64
+ hooks[event] = groups;
65
+ continue;
66
+ }
67
+ const kept = groups
68
+ .map((g) => ({ ...g, hooks: (Array.isArray(g?.hooks) ? g.hooks : []).filter((h) => !isHolmesCommand(h?.command)) }))
63
69
  .filter((g) => g.hooks.length > 0);
64
70
  if (kept.length > 0)
65
71
  hooks[event] = kept;
@@ -1,10 +1,27 @@
1
+ import { UpgradePlan } from '../update/upgrade-plan';
1
2
  export interface UpgradeIO {
2
3
  dryRun: boolean;
3
4
  yes: boolean;
4
5
  stdout: (s: string) => void;
5
6
  stderr: (s: string) => void;
6
7
  confirm: (prompt: string) => Promise<boolean>;
8
+ /**
9
+ * A-SPEC-543.2 (amendment 2026-09-29) — asks the registry for latest; the CLI passes `queryRegistryLatest`. A caller
10
+ * that passes nothing makes no query and the update cache decides.
11
+ */
12
+ queryLatest?: () => Promise<string | null>;
7
13
  }
14
+ /** What upgrade does with one registered workspace — decided once, shown in the plan and done in the run. */
15
+ interface RepinDecision {
16
+ target: string;
17
+ agents: string[];
18
+ skip?: string;
19
+ codexLeft?: boolean;
20
+ }
21
+ /** Render the plan for the human, one line per fact — from the same decisions the run carries out (round 24). */
22
+ export declare function renderPlan(plan: Extract<UpgradePlan, {
23
+ kind: 'run';
24
+ }>, decisions: RepinDecision[], installAt: string): string;
8
25
  /**
9
26
  * @implements A-SPEC-543.2
10
27
  * Thin orchestration around the pure `planUpgrade`. Resolves latest from the update cache, plans,
@@ -12,3 +29,4 @@ export interface UpgradeIO {
12
29
  * failure aborts BEFORE any re-pin (never re-pin to a version that did not install).
13
30
  */
14
31
  export declare function runUpgrade(io: UpgradeIO): Promise<number>;
32
+ export {};