claude-spotter 1.4.23 → 1.4.25

package/CHANGELOG.md

@@ -1,11 +1,41 @@
 # Changelog
 
-## 1.4.23 — release candidate (pending)
+## 1.4.25 — 2026-07-14
+
+- **Windows Codex CLI実行経路を修正。** `spotter install`、`spotter doctor`、Codex hook /
+  factory diagnostics、Codex CLI auditorは、Windowsのnpm shim `codex.cmd`を`cmd.exe`経由で
+  実行する。PowerShellから利用可能なCodexを未導入扱いせず、生成後のhook監査まで通す。
+- **timeout時のプロセスツリー終了を追加。** Windowsのshim経由監査は`taskkill /T /F`で
+  子Codexを残さず、終了確認に失敗すれば別codeでfail-loudにする。npm生成shimは
+  検証済みNode entrypointへ解決してから直接起動し、project pathを`cmd.exe`に
+  再解釈させない。Codex Sidecarの診断・監査・workflowも同じ解決契約へ揃える。
+  POSIXと実体`.exe`の直接spawn、stdin prompt、非0終了時のfail-loud診断は維持する。
+- **検証。** 530 tests（528 pass / 2 platform skip）、68-file pack、FOX Windows nativeの
+  tarball仮導入、install、warning 0のdoctor、Codex hooks / catalog、実Codex CLI auditor、
+  codex-sidecar auditor diagnostics、dotagents `verify-install`を通過した。
+
+## 1.4.24 — 2026-07-14
+
+- **installerがruntime error state rootをowner-privateへ正規化。** `spotter install`は
+  Hook・tool DB・daemon stateを作る前に、runtime storeと同じPOSIX uid / modeまたは
+  Windows current-SID-only DACL契約でglobal state rootを準備する。fresh installだけでなく、
+  umaskにより`0755` / `0775`で残っていた既存`~/.spotter`もPOSIXでは`0700`へ修復する。
+- **unsafe pathを修復前に拒否。** POSIXのtype・symlink・owner検証を`chmod`より前へ移し、
+  `~/.spotter`がsymlinkの場合にリンク先のmodeを変えてから失敗する副作用を防いだ。
+  read-timeのmode検証、Windows DACL、collection明示opt-in、network非依存契約は変更しない。
+- **検証・公開。** 519 tests（517 pass / 2 platform skip）、macOS/Linux/Windows ×
+  Node 22.13/22.xのCI run `29274984927`、67-file pack検査、隔離installを通過した。
+  公開commit `52d6086`をnpm `latest`、`v1.4.24` tag、GitHub Releaseへ同期し、Mac、
+  main-server、FOX WSL2のregistry版global install、state root `0700`、runtime snapshot、
+  dotagents Mac BugHub canaryを確認した。
+
+## 1.4.23 — 2026-07-13
 
 - **Factory diagnostics と local runtime error store。** factory diagnostics と
   `spotter diagnostics runtime-errors` の公開候補。収集は canonical dotagents config の
   JSON boolean `collection.enabled: true` が明示された時だけ有効で既定OFF、保存は
-  local-only、network送信は行わない。npm公開、tag、CI、registry由来installの確認は未実施。
+  local-only、network送信は行わない。公開commit `a117a99`、CI `29238199094`、npm
+  `latest`、tag / GitHub Release、registry由来隔離installと診断snapshotを確認済み。
 - **隔離observerのdeadlineを実測へ整合。** 並列full-suite負荷でcold workerとreceipt
   reconcilerが500msに収まらず、commit済みreceiptを`store_unavailable`へ誤分類するraceを
   再現した。絶対deadlineを1.5秒へ広げたうえでreceipt reconcilerを観測workerと

package/README.md

@@ -248,9 +248,9 @@ otherwise the Haiku-compatible path. Codex native hooks automatically select Cod
 
 ## Local runtime error aggregates
 
-**v1.4.23 は release candidate（公開待ち）です。** 以下の factory diagnostics と
-local runtime error aggregate は collection が既定OFFで、公開・tag・CI・registry由来
-installの確認はいずれも未完了です。
+**v1.4.23 は2026-07-13に公開済みです。** 以下の factory diagnostics と local runtime
+error aggregate は collection が既定OFFです。npm `latest`、tag / GitHub Release、
+公開CI、registry由来installを確認済みです。
 
 Spotter collects fixed-code runtime failures only when the canonical dotagents factory reporter
 configuration contains the JSON boolean `collection.enabled: true`. Missing, malformed, and disabled

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-spotter",
-  "version": "1.4.23",
+  "version": "1.4.25",
   "description": "Audit agent running alongside Claude Code that catches missed tool calls — 気づく役と実行する役の分離",
   "type": "module",
   "bin": {

package/src/cli/codex-hook-cmd.mjs

@@ -6,6 +6,7 @@ import { delimiter, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createAuditorBackend, selectAuditorBackend } from '../core/auditor-backend.mjs';
 import { resolveCodexAuditorModelSelection } from '../core/codex-auditor-model-policy.mjs';
+import { buildWindowsCompatibleInvocation } from '../core/windows-cli-shim.mjs';
 import { codexLastAssistantMessage, readCodexToolUsage } from '../core/codex-transcript.mjs';
 import { readLocal } from '../tool-db/refresh.mjs';
 import { spawnRefreshDetached } from '../hooks/spawn-daemon.mjs';
@@ -549,13 +550,23 @@ export async function codexHookDiagnostics({
   projectRoot = null,
   env = process.env,
   spawnSyncFn = spawnSync,
+  platform = process.platform,
   resolveModelSelectionFn = resolveCodexAuditorModelSelection,
 } = {}) {
   const auditorBackend = resolveCodexHookAuditorBackend({ env });
   const auditorModelSelection = auditorBackend === 'codex-cli'
     ? resolveModelSelectionFn({ env })
     : null;
-  const features = spawnSyncFn('codex', ['features', 'list'], { encoding: 'utf8', maxBuffer: 1024 * 1024 });
+  const invocation = buildWindowsCompatibleInvocation({
+    command: 'codex',
+    args: ['features', 'list'],
+    platform,
+  });
+  const features = spawnSyncFn(invocation.command, invocation.args, {
+    encoding: 'utf8',
+    maxBuffer: 1024 * 1024,
+    windowsHide: true,
+  });
   const featureOutput = [features.stdout, features.stderr].filter(Boolean).join('\n');
   const hooks = await loadJson(join(codexHome, 'hooks.json'));
   const evidence = featureOutput.split('\n').find((line) => isEnabledCodexHookFeatureLine(line)) ?? null;

package/src/cli/doctor.mjs

@@ -8,6 +8,7 @@ import { promisify } from 'node:util';
 import { loadDb, globalDbPath, localDbPath } from '../tool-db/loader.mjs';
 import { findSpotterMarker } from '../hooks/lib.mjs';
 import { codexHookDiagnostics } from './codex-hook-cmd.mjs';
+import { buildWindowsCompatibleInvocation } from '../core/windows-cli-shim.mjs';
 
 const execFileP = promisify(execFile);
 
@@ -51,8 +52,8 @@ export async function runDoctor() {
   // Codex native readiness. These are warnings because Claude-backed installs may
   // still be valid, but Codex-first tuning needs the signal in one place.
   try {
-    const { stdout } = await execFileP('codex', ['--version'], { timeout: 5_000, windowsHide: true });
-    mark(true, `codex CLI: ${stdout.trim()}`);
+    const version = await inspectCodexCliVersion();
+    mark(true, `codex CLI: ${version}`);
   } catch (err) {
     mark(false, 'codex CLI', `not found or failed: ${err.message}`);
     warnings += 1;
@@ -115,6 +116,23 @@ export async function runDoctor() {
   console.log(`result: OK (${warnings} warnings)`);
 }
 
+export async function inspectCodexCliVersion({
+  codexBin = 'codex',
+  platform = process.platform,
+  execFileFn = execFileP,
+} = {}) {
+  const invocation = buildWindowsCompatibleInvocation({
+    command: codexBin,
+    args: ['--version'],
+    platform,
+  });
+  const { stdout } = await execFileFn(invocation.command, invocation.args, {
+    timeout: 5_000,
+    windowsHide: true,
+  });
+  return stdout.trim();
+}
+
 export async function inspectCodexHookConfiguration({ projectRoot = null, diagnosticsFn = codexHookDiagnostics } = {}) {
   const diagnostics = await diagnosticsFn({ projectRoot });
   const issues = Object.entries(diagnostics.validation ?? {})
@@ -209,7 +227,13 @@ async function codexSidecarAuditorReadiness(projectRoot) {
   const cmd = cliPath ? process.execPath : 'codex-sidecar';
   const finalArgs = cliPath ? [cliPath, ...args] : args;
   try {
-    const { stdout } = await execFileP(cmd, finalArgs, {
+    const invocation = buildWindowsCompatibleInvocation({
+      command: cmd,
+      args: finalArgs,
+      env: process.env,
+      allowCmdFallback: false,
+    });
+    const { stdout } = await execFileP(invocation.command, invocation.args, {
       timeout: 15_000,
       windowsHide: true,
       maxBuffer: 1024 * 1024,

package/src/cli/install.mjs

@@ -15,6 +15,7 @@
 import { mkdir, writeFile, readFile, access, realpath } from 'node:fs/promises';
 import { constants as fsConstants } from 'node:fs';
 import { spawnSync } from 'node:child_process';
+import { buildWindowsCompatibleInvocation } from '../core/windows-cli-shim.mjs';
 import { homedir } from 'node:os';
 import { join, resolve, dirname, delimiter, extname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -23,6 +24,7 @@ import { version as SPOTTER_VERSION } from '../version.mjs';
 import { refresh } from '../tool-db/refresh.mjs';
 import { localDbPath, globalDbPath } from '../tool-db/loader.mjs';
 import { installCodexHooks } from './codex-hook-cmd.mjs';
+import { prepareRuntimeErrorStoreDirectory } from '../core/runtime-error-store.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = resolve(HERE, '..', '..');
@@ -58,6 +60,7 @@ export async function runInstall({
   refreshFn = refresh,
   codexCliPresentFn = isCodexCliPresent,
   installCodexHooksFn = installCodexHooks,
+  prepareRuntimeErrorStoreDirectoryFn = prepareRuntimeErrorStoreDirectory,
   auditorContext,
   resolveDefaultAuditorContextFn = resolveDefaultAuditorContext,
 } = {}) {
@@ -70,6 +73,7 @@ export async function runInstall({
   console.log(`  settings: ${settingsPath}`);
 
   // 1. create directories
+  await prepareRuntimeErrorStoreDirectoryFn();
   await mkdir(SPOTTER_HOME, { recursive: true });
   await mkdir(join(SPOTTER_HOME, 'runtime'), { recursive: true });
   await mkdir(join(SPOTTER_HOME, 'workdir'), { recursive: true });
@@ -275,8 +279,17 @@ async function exists(path) {
   }
 }
 
-function isCodexCliPresent() {
-  const result = spawnSync('codex', ['--version'], {
+export function isCodexCliPresent({
+  platform = process.platform,
+  spawnSyncFn = spawnSync,
+  codexBin = 'codex',
+} = {}) {
+  const invocation = buildWindowsCompatibleInvocation({
+    command: codexBin,
+    args: ['--version'],
+    platform,
+  });
+  const result = spawnSyncFn(invocation.command, invocation.args, {
     encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'pipe'],
     timeout: 5_000,

package/src/core/codex-cli-backend.mjs

@@ -10,6 +10,7 @@ import {
   resolveCodexAuditorModelSelection,
 } from './codex-auditor-model-policy.mjs';
 import { serializeAuditorPromptData, validateRecentContext } from './auditor-prompt-data.mjs';
+import { buildWindowsCompatibleInvocation, terminateProcessTree } from './windows-cli-shim.mjs';
 
 const DEFAULT_CODEX_CLI_TIMEOUT_MS = 45_000;
 const DEFAULT_CODEX_CLI_MODEL = CODEX_AUDITOR_MODEL_POLICY.production.model;
@@ -129,6 +130,8 @@ export function createCodexCliAuditorBackend({
   codexBin = 'codex',
   modelProfile = null,
   resolveModelSelectionFn = resolveCodexAuditorModelSelection,
+  platform = process.platform,
+  terminateChildFn = terminateProcessTree,
 } = {}) {
   if (!Array.isArray(catalog)) {
     throw new TypeError('createCodexCliAuditorBackend: catalog must be an array');
@@ -168,6 +171,8 @@ export function createCodexCliAuditorBackend({
           spawnFn,
           timeoutMs,
           modelSelection,
+          platform,
+          terminateChildFn,
         });
         let rawFinal;
         try {
@@ -321,6 +326,8 @@ async function runCodexExec({
   spawnFn,
   timeoutMs,
   modelSelection,
+  platform,
+  terminateChildFn,
 }) {
   const args = buildCodexExecArgs({
     schemaPath,
@@ -330,10 +337,36 @@ async function runCodexExec({
     reasoningEffort: modelSelection.effectiveReasoningEffort,
   });
   const options = buildCodexCliSpawnOptions({ projectRoot, env });
+  let invocation;
+  try {
+    invocation = buildWindowsCompatibleInvocation({
+      command: codexBin,
+      args,
+      platform,
+      env,
+      allowCmdFallback: false,
+    });
+  } catch (err) {
+    throw new AuditorBackendError('E_CODEX_CLI_SPAWN', `failed to resolve ${codexBin}: ${err.message}`, {
+      backend: 'codex-cli',
+      stage,
+      diagnostics: {
+        durationMs: 0,
+        processCount: 0,
+        processCountMethod: 'resolve_failed',
+        stdout: '',
+        stderr: '',
+        stdoutTruncated: false,
+        stderrTruncated: false,
+        modelSelection,
+      },
+      cause: err,
+    });
+  }
   const startedAt = Date.now();
   let child;
   try {
-    child = spawnFn(codexBin, args, options);
+    child = spawnFn(invocation.command, invocation.args, options);
   } catch (err) {
     throw new AuditorBackendError('E_CODEX_CLI_SPAWN', `failed to spawn ${codexBin}: ${err.message}`, {
       backend: 'codex-cli',
@@ -368,8 +401,21 @@ async function runCodexExec({
     const timer = setTimeout(() => {
       settle(async () => {
         const completed = await readSchemaValidLastMessage({ lastMessagePath, stage });
+        try {
+          await terminateChildFn(child, { platform });
+        } catch (cause) {
+          reject(new AuditorBackendError('E_CODEX_CLI_TERMINATION', 'codex-cli process tree termination could not be verified', {
+            backend: 'codex-cli',
+            stage,
+            diagnostics: {
+              ...diagnostics(),
+              lastMessageCheck: completed.reason,
+            },
+            cause,
+          }));
+          return;
+        }
         if (completed.ok) {
-          if (typeof child.kill === 'function') child.kill();
           resolve({
             diagnostics: {
               ...diagnostics(),
@@ -379,7 +425,6 @@ async function runCodexExec({
           });
           return;
         }
-        if (typeof child.kill === 'function') child.kill();
         reject(new AuditorBackendError('E_CODEX_CLI_TIMEOUT', `codex-cli did not respond within ${timeoutMs}ms`, {
           backend: 'codex-cli',
           stage,

package/src/core/codex-sidecar-auditor-backend.mjs

@@ -6,6 +6,7 @@ import { promisify } from 'node:util';
 import { toSpotterJudgment } from './judgment.mjs';
 import { filterCatalogMisses } from './auditor-response.mjs';
 import { AuditorBackendError } from './auditor-error.mjs';
+import { buildWindowsCompatibleInvocation } from './windows-cli-shim.mjs';
 
 const execFileP = promisify(execFile);
 const DEFAULT_CODEX_SIDECAR_AUDITOR_TIMEOUT_MS = 45_000;
@@ -18,6 +19,7 @@ export function createCodexSidecarAuditorBackend({
   projectRoot,
   env = process.env,
   execFileFn = execFileP,
+  buildInvocationFn = buildWindowsCompatibleInvocation,
   timeoutMs = DEFAULT_CODEX_SIDECAR_AUDITOR_TIMEOUT_MS,
 } = {}) {
   if (!Array.isArray(catalog)) {
@@ -47,6 +49,7 @@ export function createCodexSidecarAuditorBackend({
           contextFilePath,
           env,
           execFileFn,
+          buildInvocationFn,
           timeoutMs,
         });
         const parsed = parseCodexSidecarAuditorResult(run.value, { stage });
@@ -166,14 +169,27 @@ function buildExecOptions({ projectRoot, env, timeoutMs }) {
   };
 }
 
-async function runCodexSidecarAuditor({ projectRoot, contextFilePath, env, execFileFn, timeoutMs }) {
+async function runCodexSidecarAuditor({
+  projectRoot,
+  contextFilePath,
+  env,
+  execFileFn,
+  buildInvocationFn,
+  timeoutMs,
+}) {
   const { cmd, args } = buildCodexSidecarAuditorCommand({ projectRoot, contextFilePath, env, timeoutMs });
   const options = buildExecOptions({ projectRoot, env, timeoutMs });
+  const invocation = buildInvocationFn({
+    command: cmd,
+    args,
+    env,
+    allowCmdFallback: false,
+  });
   const startedAt = Date.now();
   let stdout = '';
   let stderr = '';
   try {
-    const result = await execFileFn(cmd, args, options);
+    const result = await execFileFn(invocation.command, invocation.args, options);
     stdout = result.stdout ?? '';
     stderr = result.stderr ?? '';
   } catch (err) {

package/src/core/codex-sidecar-runner.mjs

@@ -16,6 +16,7 @@ import {
   createSidecarResultRecord,
   spotterFindingsToSidecarContextBlocks,
 } from './sidecar-context.mjs';
+import { buildWindowsCompatibleInvocation } from './windows-cli-shim.mjs';
 
 const execFileP = promisify(execFile);
 const WORKFLOW_MAP = {
@@ -36,6 +37,7 @@ export async function runCodexReadOnlyWorkflow({
   save = true,
   outPath = null,
   execFileFn = execFileP,
+  buildInvocationFn = buildWindowsCompatibleInvocation,
   gitStatusFn = execFileP,
   env = process.env,
   now = () => new Date(),
@@ -54,6 +56,7 @@ export async function runCodexReadOnlyWorkflow({
   const effectiveHostAgent = detectHostAgent({ explicitHostAgent: hostAgent, env });
   const contextBlocks = spotterFindingsToSidecarContextBlocks(findings);
   const spawnOptions = buildSidecarSpawnOptions({ projectRoot, env });
+  spawnOptions.buildInvocationFn = buildInvocationFn;
   const diagnostics = await runDiagnostics({ projectRoot, preset: workflowSpec.preset, execFileFn, spawnOptions });
   const availability = classifySidecarAvailability({ diagnostics });
   const decision = decideCodexSidecarUse({
@@ -129,6 +132,7 @@ export async function runCodexWork({
   save = true,
   outPath = null,
   execFileFn = execFileP,
+  buildInvocationFn = buildWindowsCompatibleInvocation,
   gitStatusFn = execFileP,
   env = process.env,
   now = () => new Date(),
@@ -163,6 +167,7 @@ export async function runCodexWork({
     gitStatusFn,
   });
   const spawnOptions = buildSidecarSpawnOptions({ projectRoot, env, marker: 'codex-work' });
+  spawnOptions.buildInvocationFn = buildInvocationFn;
   const diagnostics = dirtyScope.ok
     ? await runDiagnostics({ projectRoot, preset: workflowSpec.preset, execFileFn, spawnOptions })
     : null;
@@ -481,10 +486,13 @@ function execPortable(execFileFn, cmd, args, spawnOptions) {
     windowsHide: true,
     maxBuffer: 10 * 1024 * 1024,
   };
-  if (process.platform === 'win32' && cmd !== process.execPath) {
-    return execFileFn('cmd.exe', ['/c', cmd, ...args], options);
-  }
-  return execFileFn(cmd, args, options);
+  const invocation = spawnOptions.buildInvocationFn({
+    command: cmd,
+    args,
+    env: spawnOptions.env,
+    allowCmdFallback: false,
+  });
+  return execFileFn(invocation.command, invocation.args, options);
 }
 
 function parseJsonOutput(stdout) {

package/src/core/runtime-error-store.mjs

@@ -90,6 +90,11 @@ export function defaultRuntimeErrorStorePath({
   return join(homeDir, '.spotter', 'runtime-errors-v1.json');
 }
 
+export async function prepareRuntimeErrorStoreDirectory(options = {}) {
+  const storePath = options.storePath ?? defaultRuntimeErrorStorePath(options);
+  await ensurePrivateDirectory(dirname(storePath), options);
+}
+
 export function runtimeErrorFingerprint(definition) {
   validateDefinition(definition);
   const canonical = [
@@ -578,22 +583,29 @@ async function enforcePrivatePath(path, options, { directory, repair }) {
     if (repair) await runWindowsAcl(path, { directory }, options);
     return;
   }
+  const initialInfo = await lstat(path);
+  validatePrivateIdentity(initialInfo, options, { directory, platform });
   if (repair) await chmod(path, directory ? 0o700 : 0o600);
   const info = await lstat(path);
   validatePrivateStat(info, options, { directory, platform });
 }
 
-function validatePrivateStat(info, options, { directory, platform }) {
+function validatePrivateIdentity(info, options, { directory, platform }) {
   if ((directory ? !info.isDirectory() : !info.isFile()) || info.isSymbolicLink()) {
     throw storeError('runtime error path type is unsafe');
   }
   if (platform === 'win32') return;
-  const expectedMode = directory ? 0o700 : 0o600;
-  if ((info.mode & 0o777) !== expectedMode) throw storeError('runtime error path mode is unsafe');
   const getuid = options.getuidFn ?? process.getuid?.bind(process);
   if (typeof getuid === 'function' && info.uid !== getuid()) throw storeError('runtime error path owner is unsafe');
 }
 
+function validatePrivateStat(info, options, { directory, platform }) {
+  validatePrivateIdentity(info, options, { directory, platform });
+  if (platform === 'win32') return;
+  const expectedMode = directory ? 0o700 : 0o600;
+  if ((info.mode & 0o777) !== expectedMode) throw storeError('runtime error path mode is unsafe');
+}
+
 export function buildWindowsAclPowerShell({ directory }) {
   const securityType = directory ? 'DirectorySecurity' : 'FileSecurity';
   const ioType = directory ? 'Directory' : 'File';

package/src/core/windows-cli-shim.mjs

@@ -0,0 +1,162 @@
+import { spawn } from 'node:child_process';
+import { readFileSync, statSync } from 'node:fs';
+import { win32 } from 'node:path';
+
+// Windows の npm global CLI は多くが `<name>.cmd` shim であり、Node の shell:false
+// 直接 spawn では PATHEXT 解決されない。cmd.exe を明示して Node 24 の shell:true
+// deprecation を避けつつ、POSIX と実体 .exe は従来どおり直接起動する。
+export function buildWindowsCompatibleInvocation({
+  command,
+  args = [],
+  platform = process.platform,
+  env = process.env,
+  processExecPath = process.execPath,
+  fileExistsFn = defaultFileExists,
+  readFileFn = defaultReadFile,
+  allowCmdFallback = true,
+} = {}) {
+  if (typeof command !== 'string' || command.length === 0) {
+    throw new TypeError('buildWindowsCompatibleInvocation: command must be a non-empty string');
+  }
+  if (!Array.isArray(args) || args.some((arg) => typeof arg !== 'string')) {
+    throw new TypeError('buildWindowsCompatibleInvocation: args must be an array of strings');
+  }
+  if (platform !== 'win32' || /\.exe$/i.test(command)) {
+    return { command, args };
+  }
+  const direct = resolveWindowsNpmShim({
+    command,
+    args,
+    env,
+    processExecPath,
+    fileExistsFn,
+    readFileFn,
+  });
+  if (direct) return direct;
+  if (!allowCmdFallback) {
+    const error = new Error(`Windows CLI shim could not be resolved safely: ${command}`);
+    error.code = 'E_WINDOWS_CLI_SHIM_UNRESOLVED';
+    throw error;
+  }
+  return {
+    command: 'cmd.exe',
+    args: ['/d', '/s', '/c', command, ...args],
+  };
+}
+
+export function resolveWindowsNpmShim({
+  command,
+  args = [],
+  env = process.env,
+  processExecPath = process.execPath,
+  fileExistsFn = defaultFileExists,
+  readFileFn = defaultReadFile,
+} = {}) {
+  const pathValue = env?.Path ?? env?.PATH ?? env?.path ?? '';
+  const hasPathSeparator = /[\\/]/.test(command);
+  const candidates = [];
+  if (hasPathSeparator) {
+    candidates.push(command);
+    if (!/\.[^\\/]+$/.test(command)) candidates.push(`${command}.exe`, `${command}.cmd`);
+  } else {
+    for (const rawDir of String(pathValue).split(';')) {
+      const dir = rawDir.trim();
+      if (!dir) continue;
+      candidates.push(win32.join(dir, `${command}.exe`), win32.join(dir, `${command}.cmd`));
+    }
+  }
+
+  for (const candidate of candidates) {
+    if (!fileExistsFn(candidate)) continue;
+    if (/\.exe$/i.test(candidate)) return { command: candidate, args };
+    if (!/\.cmd$/i.test(candidate)) continue;
+    const script = npmShimEntryPath(readFileFn(candidate), win32.dirname(candidate));
+    if (!script || !fileExistsFn(script)) continue;
+    const bundledNode = win32.join(win32.dirname(candidate), 'node.exe');
+    return {
+      command: fileExistsFn(bundledNode) ? bundledNode : processExecPath,
+      args: [script, ...args],
+    };
+  }
+  return null;
+}
+
+export function npmShimEntryPath(source, shimDir) {
+  if (typeof source !== 'string') return null;
+  const match = source.match(/"%dp0%\\(node_modules\\[^"\r\n]+\.(?:cjs|mjs|js))"\s+%\*\s*$/im);
+  if (!match) return null;
+  const segments = match[1].split(/[\\/]/);
+  if (segments.some((segment) => !segment || segment === '.' || segment === '..')) return null;
+  return win32.join(shimDir, ...segments);
+}
+
+// cmd.exe shim のみ kill すると孫の CLI が残り得るため、Windows は process tree を
+// taskkill で終了する。taskkill 自体の起動・終了に失敗した時だけ direct kill へ戻す。
+export function terminateProcessTree(child, {
+  platform = process.platform,
+  spawnFn = spawn,
+  timeoutMs = 5_000,
+} = {}) {
+  if (!child || typeof child.kill !== 'function') return Promise.resolve();
+  if (platform !== 'win32' || !Number.isSafeInteger(child.pid) || child.pid <= 0) {
+    child.kill();
+    return Promise.resolve();
+  }
+
+  const fallback = () => {
+    try { child.kill(); } catch { /* process may already have exited */ }
+  };
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (error = null) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (error) {
+        fallback();
+        reject(error);
+      } else {
+        resolve();
+      }
+    };
+    const timer = setTimeout(() => {
+      const error = new Error(`taskkill did not finish within ${timeoutMs}ms`);
+      error.code = 'E_PROCESS_TREE_TERMINATION_TIMEOUT';
+      finish(error);
+    }, timeoutMs);
+    try {
+      const killer = spawnFn('taskkill.exe', ['/pid', String(child.pid), '/T', '/F'], {
+        stdio: 'ignore',
+        windowsHide: true,
+      });
+      killer.once('error', (cause) => {
+        const error = new Error(`taskkill failed to start: ${cause.message}`);
+        error.code = 'E_PROCESS_TREE_TERMINATION';
+        error.cause = cause;
+        finish(error);
+      });
+      killer.once('close', (code) => {
+        if (code === 0) {
+          finish();
+          return;
+        }
+        const error = new Error(`taskkill exited with code ${code}`);
+        error.code = 'E_PROCESS_TREE_TERMINATION';
+        finish(error);
+      });
+    } catch (cause) {
+      const error = new Error(`taskkill spawn failed: ${cause.message}`);
+      error.code = 'E_PROCESS_TREE_TERMINATION';
+      error.cause = cause;
+      finish(error);
+    }
+  });
+}
+
+function defaultFileExists(path) {
+  try { return statSync(path).isFile(); } catch { return false; }
+}
+
+function defaultReadFile(path) {
+  try { return readFileSync(path, 'utf8'); } catch { return ''; }
+}