@holmes-lab/holmes-kit 0.30.0 → 0.31.0

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 (136) hide show
  1. package/CHANGELOG.md +494 -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 +23 -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 +13 -0
  31. package/dist/holmes/cli/upgrade.js +116 -23
  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.js +3 -1
  134. package/dist/holmes/update/update-notice.d.ts +6 -0
  135. package/dist/holmes/update/update-notice.js +18 -1
  136. 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,3 +1,4 @@
1
+ import { UpgradePlan } from '../update/upgrade-plan';
1
2
  export interface UpgradeIO {
2
3
  dryRun: boolean;
3
4
  yes: boolean;
@@ -5,6 +6,17 @@ export interface UpgradeIO {
5
6
  stderr: (s: string) => void;
6
7
  confirm: (prompt: string) => Promise<boolean>;
7
8
  }
9
+ /** What upgrade does with one registered workspace — decided once, shown in the plan and done in the run. */
10
+ interface RepinDecision {
11
+ target: string;
12
+ agents: string[];
13
+ skip?: string;
14
+ codexLeft?: boolean;
15
+ }
16
+ /** Render the plan for the human, one line per fact — from the same decisions the run carries out (round 24). */
17
+ export declare function renderPlan(plan: Extract<UpgradePlan, {
18
+ kind: 'run';
19
+ }>, decisions: RepinDecision[], installAt: string): string;
8
20
  /**
9
21
  * @implements A-SPEC-543.2
10
22
  * Thin orchestration around the pure `planUpgrade`. Resolves latest from the update cache, plans,
@@ -12,3 +24,4 @@ export interface UpgradeIO {
12
24
  * failure aborts BEFORE any re-pin (never re-pin to a version that did not install).
13
25
  */
14
26
  export declare function runUpgrade(io: UpgradeIO): Promise<number>;
27
+ export {};
@@ -33,9 +33,11 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.renderPlan = renderPlan;
36
37
  exports.runUpgrade = runUpgrade;
37
38
  // @implements A-SPEC-709
38
39
  // @implements A-SPEC-543.2
40
+ // @implements A-SPEC-251.1
39
41
  const fs = __importStar(require("node:fs"));
40
42
  const os = __importStar(require("node:os"));
41
43
  const path = __importStar(require("node:path"));
@@ -45,6 +47,7 @@ const workspaces_1 = require("../update/workspaces");
45
47
  const upgrade_plan_1 = require("../update/upgrade-plan");
46
48
  const session_start_1 = require("../hooks/session-start");
47
49
  const npx_bin_1 = require("../project/npx-bin");
50
+ const codex_oracle_1 = require("./codex-oracle");
48
51
  const PKG = '@holmes-lab/holmes-kit';
49
52
  // Local copy of index.ts's packageRoot (dist/holmes/cli/upgrade.js → 3 up) — avoids a require cycle,
50
53
  // since index.ts lazily requires THIS module.
@@ -61,14 +64,72 @@ function currentVersion(root) {
61
64
  }
62
65
  /** `npm` on POSIX, `npm.cmd` on win32 — the shim a spawn resolves (same binary-name reasoning as npxBin). */
63
66
  function npmBin() { return process.platform === 'win32' ? 'npm.cmd' : 'npm'; }
64
- /** Render the plan for the human, one line per fact. */
65
- function renderPlan(plan) {
67
+ /** A-SPEC-251.1 (round 26): npm's own update check is not upgrade's egress (it raced every npm child — measured). */
68
+ const NPM_QUIET = ['--no-update-notifier'];
69
+ const realOrResolve = (p) => {
70
+ try {
71
+ return fs.realpathSync.native(p);
72
+ }
73
+ catch { /* not there yet */ }
74
+ try {
75
+ return path.join(fs.realpathSync.native(path.dirname(p)), path.basename(p));
76
+ }
77
+ catch {
78
+ return path.resolve(p);
79
+ }
80
+ };
81
+ /**
82
+ * @implements A-SPEC-251.1 (confirmation round 24) — the holmes-kit install a workspace uses, found the way node finds a
83
+ * package: the nearest ancestor `node_modules/@holmes-lab/holmes-kit`. `pending` (the install this upgrade is about to
84
+ * write) counts even before it exists. A path-prefix test re-pinned an independent project nested under the installing
85
+ * one, and every workspace under a stray `~/node_modules` install (measured).
86
+ */
87
+ function installOf(target, pending) {
88
+ let d = realOrResolve(target);
89
+ for (;;) {
90
+ const cand = path.join(d, 'node_modules', PKG);
91
+ const real = realOrResolve(cand);
92
+ if (real === pending || fs.existsSync(path.join(cand, 'package.json')))
93
+ return real;
94
+ const parent = path.dirname(d);
95
+ if (parent === d)
96
+ return null;
97
+ d = parent;
98
+ }
99
+ }
100
+ function decideRepin(w, installMode, pkgDir) {
101
+ const agents = w.agents.length ? w.agents : ['claude'];
102
+ if (!fs.existsSync(w.target))
103
+ return { target: w.target, agents, skip: 'no path' };
104
+ const own = installOf(w.target, pkgDir);
105
+ // local-dep: only the workspaces that resolve to this install. global: all but those resolving to an install of their own.
106
+ if (installMode === 'local-dep' && own === null)
107
+ return { target: w.target, agents, skip: 'not using this install' }; // round 25 wording
108
+ if (installMode === 'local-dep' ? own !== pkgDir : own !== null && own !== pkgDir)
109
+ return { target: w.target, agents, skip: 'its own install' };
110
+ // Round 23: Codex's wiring is user-level, shared by every workspace — a project-local re-pin moved every Codex session
111
+ // onto one project's install (measured). It is left as it is, and said so.
112
+ const kept = installMode === 'local-dep' ? agents.filter((a) => a !== 'codex') : agents;
113
+ if (kept.length === 0)
114
+ return { target: w.target, agents, skip: 'Codex only', codexLeft: true };
115
+ return { target: w.target, agents: kept, ...(kept.length < agents.length ? { codexLeft: true } : {}) };
116
+ }
117
+ /** Render the plan for the human, one line per fact — from the same decisions the run carries out (round 24). */
118
+ function renderPlan(plan, decisions, installAt) {
119
+ // @implements A-SPEC-251.2 (round 46) — a registry value is printed escaped (a newline in a target forged a plan line, an OSC
120
+ // sequence retitled the terminal — measured).
121
+ const shown = (v) => (0, codex_oracle_1.escapeForDisplay)(String(v));
122
+ const repins = decisions.filter((d) => d.skip === undefined);
123
+ const skips = decisions.filter((d) => d.skip !== undefined);
66
124
  const lines = [
67
125
  `Holmes-Kit upgrade: ${plan.current} → ${plan.latest} (install mode: ${plan.installMode})`,
68
- plan.repins.length
69
- ? `Will re-pin ${plan.repins.length} workspace(s):`
70
- : 'No wired workspaces recorded yet — install only.',
71
- ...plan.repins.map((w) => ` • ${w.target} [${w.agents.join(', ')}]`),
126
+ `Install location: ${installAt}`, // round 25: the plan never named where it would install
127
+ repins.length
128
+ ? `Will re-pin ${repins.length} workspace(s):`
129
+ : 'No workspace uses this install — install only.',
130
+ ...repins.map((d) => ` • ${shown(d.target)} [${shown(d.agents.join(', '))}]`),
131
+ ...(skips.length ? [`Will skip ${skips.length}:`, ...skips.map((d) => ` • ${shown(d.target)} (${shown(d.skip)})`)] : []),
132
+ ...(decisions.some((d) => d.codexLeft) ? ["Codex's user-level wiring is shared by every workspace and is left as it is."] : []),
72
133
  ];
73
134
  return lines.join('\n') + '\n';
74
135
  }
@@ -96,15 +157,39 @@ async function runUpgrade(io) {
96
157
  io.stdout(`${plan.reason}\n`);
97
158
  return 0;
98
159
  }
99
- io.stdout(renderPlan(plan));
100
- if (io.dryRun) {
101
- io.stdout('(dry-run — nothing installed or re-pinned)\n');
102
- return 0;
160
+ // @implements A-SPEC-251.1 (round 27) — only a strict semver is installed (`PKG@<latest>`): a cached `9.0.0.tgz` was read
161
+ // by npm as a local file (measured). The cache reader refuses such a value; this is the second line.
162
+ if (!(0, update_notice_1.isStrictSemver)(plan.latest)) {
163
+ io.stderr(`the cached latest version is not a version (${String(plan.latest).slice(0, 80)}); nothing installed or re-pinned.\n`);
164
+ return 1;
103
165
  }
166
+ // Round 25: a source checkout is refused before any plan (its dry run printed "Will re-pin N" — code read).
104
167
  if (plan.installMode === 'source') {
105
168
  io.stderr('source checkout: upgrade via git (git pull && npm run build), not npm install.\n');
106
169
  return 1;
107
170
  }
171
+ // Round 24: where the install goes is known before installing (`npm root` only names the directory), so the plan
172
+ // shown before "Continue?" is the run's own decisions.
173
+ let pkgDir; // compared (real path)
174
+ let pkgPath; // run (as npm names it)
175
+ try {
176
+ const modulesRoot = (0, node_child_process_1.execFileSync)(npmBin(), ['root', ...(plan.installMode === 'global-npx' ? ['-g'] : []), ...NPM_QUIET], { cwd: process.cwd(), encoding: 'utf8', timeout: 30_000 }).trim();
177
+ // Round 25: npm redacts UUID-shaped path segments in its output (`***`) — such a path is no location (measured).
178
+ if (modulesRoot.includes('***'))
179
+ throw new Error(`npm root answered a redacted path (${modulesRoot.slice(0, 200)})`);
180
+ pkgPath = path.join(modulesRoot, PKG);
181
+ pkgDir = realOrResolve(pkgPath);
182
+ }
183
+ catch (e) {
184
+ io.stderr(`the install location could not be resolved (npm root); nothing installed or re-pinned: ${String(e)}\n`);
185
+ return 1;
186
+ }
187
+ const decisions = registry.workspaces.map((w) => decideRepin(w, plan.installMode, pkgDir));
188
+ io.stdout(renderPlan(plan, decisions, pkgPath));
189
+ if (io.dryRun) {
190
+ io.stdout('(dry-run — nothing installed or re-pinned)\n');
191
+ return 0;
192
+ }
108
193
  const go = io.yes || await io.confirm('Continue? [y/N] ');
109
194
  if (!go) {
110
195
  io.stdout(io.yes ? '' : 'aborted — nothing installed or re-pinned.\n');
@@ -117,7 +202,7 @@ async function runUpgrade(io) {
117
202
  const args = plan.installMode === 'global-npx'
118
203
  ? ['i', '-g', `${PKG}@${plan.latest}`]
119
204
  : ['i', '-D', `${PKG}@${plan.latest}`];
120
- (0, node_child_process_1.execFileSync)(npmBin(), args, { stdio: 'inherit', cwd: process.cwd() });
205
+ (0, node_child_process_1.execFileSync)(npmBin(), [...args, ...NPM_QUIET], { stdio: 'inherit', cwd: process.cwd() });
121
206
  }
122
207
  catch {
123
208
  io.stderr(`install failed — nothing re-pinned. Try manually: ${npmBin()} i ${plan.installMode === 'global-npx' ? '-g' : '-D'} ${PKG}@${plan.latest}\n`);
@@ -133,12 +218,10 @@ async function runUpgrade(io) {
133
218
  }
134
219
  }
135
220
  catch { /* cache clear is best-effort */ }
136
- // (3) re-pin every registered workspace that still exists.
221
+ // (3) re-pin the workspaces the decisions name.
137
222
  // Load the newly installed package in a fresh process: the caller already cached old init.
138
- let newCli;
223
+ const newCli = path.join(pkgPath, 'bin', 'holmes-kit.js');
139
224
  try {
140
- const modulesRoot = (0, node_child_process_1.execFileSync)(npmBin(), ['root', ...(plan.installMode === 'global-npx' ? ['-g'] : [])], { cwd: process.cwd(), encoding: 'utf8' }).trim();
141
- newCli = path.join(modulesRoot, PKG, 'bin', 'holmes-kit.js');
142
225
  if (!fs.statSync(newCli).isFile())
143
226
  throw new Error('new CLI is not a file');
144
227
  }
@@ -146,29 +229,39 @@ async function runUpgrade(io) {
146
229
  io.stderr(`Installed package CLI could not be resolved; no workspace re-pinned: ${String(e)}\n`);
147
230
  return 1;
148
231
  }
232
+ // @implements A-SPEC-251.1 (confirmation round 25) — the install at the planned location must be the planned version:
233
+ // from an npm-workspaces member, `npm i -D` installed into the member while `npm root` named the root's old install,
234
+ // and the old CLI re-pinned everything and said "Upgraded" (measured).
235
+ const landed = currentVersion(pkgPath);
236
+ if (landed !== plan.latest) {
237
+ io.stderr(`npm did not install ${plan.latest} at ${pkgPath} (found ${landed}); no workspace re-pinned. Run holmes-kit upgrade from the project whose node_modules holds holmes-kit.\n`);
238
+ return 1;
239
+ }
149
240
  let repinned = 0, skipped = 0, failed = 0;
150
241
  io.stdout('\nRe-pinning workspaces:\n');
151
- for (const w of registry.workspaces) {
152
- if (!fs.existsSync(w.target)) {
153
- io.stdout(` skipped (no path): ${w.target}\n`);
242
+ for (const d of decisions) {
243
+ if (d.skip !== undefined) {
244
+ io.stdout(` skipped (${(0, codex_oracle_1.escapeForDisplay)(String(d.skip))}): ${(0, codex_oracle_1.escapeForDisplay)(d.target)}${d.skip === 'its own install' ? ' — run holmes-kit upgrade from that install' : ''}\n`);
154
245
  skipped++;
155
246
  continue;
156
247
  }
157
248
  try {
158
- const agents = w.agents.length ? w.agents.join(',') : 'claude';
159
- const output = (0, node_child_process_1.execFileSync)(process.execPath, [newCli, 'init', '--target', w.target,
160
- '--agent', agents, '--mode', 'guardrail', '--mcp-launcher', 'npx'], { cwd: process.cwd(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
249
+ const output = (0, node_child_process_1.execFileSync)(process.execPath, [newCli, 'init', '--target', d.target,
250
+ '--agent', d.agents.join(','), '--mode', 'guardrail'], { cwd: process.cwd(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
161
251
  io.stdout(output);
162
- io.stdout(` re-pinned: ${w.target}\n`);
252
+ io.stdout(` re-pinned: ${(0, codex_oracle_1.escapeForDisplay)(d.target)}\n`);
163
253
  repinned++;
164
254
  }
165
255
  catch (e) {
166
256
  const failure = e;
167
- io.stdout(` failed: ${w.target}: ${String(failure.stderr ?? failure.message ?? e)}\n`);
257
+ io.stdout(` failed: ${(0, codex_oracle_1.escapeForDisplay)(d.target)}: ${String(failure.stderr ?? failure.message ?? e).split('\n').map(codex_oracle_1.escapeForDisplay).join('\n ')}\n`);
168
258
  failed++;
169
259
  }
170
260
  }
261
+ const codexLeft = decisions.some((d) => d.codexLeft);
171
262
  io.stdout(`\nUpgraded to ${plan.latest}. re-pinned ${repinned} · skipped ${skipped} · failed ${failed}. A new session's hooks/MCP will read the new wiring.\n`);
263
+ if (codexLeft)
264
+ io.stdout(`Codex's user-level wiring was left as it is: it is shared by every workspace, so it is not moved onto this project's install. Re-wire it by running \`holmes-kit init --agent codex --force\` from the install you mean to share (a global install, outside any project).\n`);
172
265
  io.stdout(`(You can re-wire any individual workspace at any time with ${(0, npx_bin_1.npxBin)()} holmes-kit init --agent <…> --force.)\n`);
173
266
  return failed > 0 ? 1 : 0;
174
267
  }