claude-spotter 1.4.24 → 1.4.26

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 1.4.26 — 2026-07-20
+
+- **SessionEnd cleanupを冪等化。** daemonが未起動または既に停止済みの`E_UNREACHABLE`は
+  `already-stopped`として記録し、正常な終了状態をstderr warningへ誤分類しない。他のcleanup
+  failureは従来どおりwarningと構造eventを残す。
+- **Windows native Codex hookをPowerShell実行可能に修正。** quoted Node commandの先頭へ
+  Windowsだけcall operator `&`を付ける。installerのownership判定は新旧両形式を認識し、
+  再installで旧形式をcanonicalへ更新、uninstallでも除去できる。
+- **Windows runtime error storeのACL処理を安定化。** 混雑したWindows runnerでも
+  PowerShellによるprivate ACL設定が誤ってtimeoutしないよう、上限を15秒へ拡張した。
+
+## 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`を通過した。公開commit
+  `65bccf8`をnpm `latest`、`v1.4.25` tag、GitHub Releaseへ同期し、Mac、main-server、
+  FOX WSL2、FOX Windows nativeのregistry版global installとwarning 0のdoctorを確認した。
+
 ## 1.4.24 — 2026-07-14
 
 - **installerがruntime error state rootをowner-privateへ正規化。** `spotter install`は
@@ -9,6 +36,11 @@
 - **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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-spotter",
-  "version": "1.4.24",
+  "version": "1.4.26",
   "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';
@@ -463,11 +464,11 @@ export async function runCodexHookDiagnosticsCommand({
   writeOutput(JSON.stringify(result, null, 2) + '\n');
 }
 
-export async function installCodexHooks({ codexHome = defaultCodexHome(), nodePath = resolveCodexHookNodePath(), spotterBin = SPOTTER_BIN } = {}) {
+export async function installCodexHooks({ codexHome = defaultCodexHome(), nodePath = resolveCodexHookNodePath(), spotterBin = SPOTTER_BIN, platform = process.platform } = {}) {
   const hooksPath = join(codexHome, 'hooks.json');
   const configPath = join(codexHome, 'config.toml');
   const current = await loadJson(hooksPath);
-  const next = mergeCodexHooks(current, { nodePath, spotterBin });
+  const next = mergeCodexHooks(current, { nodePath, spotterBin, platform });
   const hooksChanged = JSON.stringify(current) !== JSON.stringify(next);
   if (hooksChanged) {
     await mkdir(dirname(hooksPath), { recursive: true });
@@ -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;
@@ -868,14 +879,15 @@ async function loadJson(path) {
   }
 }
 
-function mergeCodexHooks(current, { nodePath, spotterBin }) {
+function mergeCodexHooks(current, { nodePath, spotterBin, platform = process.platform }) {
   const next = structuredClone(current ?? {});
   next.hooks = next.hooks ?? {};
-  addCodexHook(next, 'SessionStart', `${quoteArg(nodePath)} ${quoteArg(spotterBin)} codex-hook session-start`, {
+  const prefix = platform === 'win32' ? '& ' : '';
+  addCodexHook(next, 'SessionStart', `${prefix}${quoteArg(nodePath)} ${quoteArg(spotterBin)} codex-hook session-start`, {
     timeout: 5,
   });
-  addCodexHook(next, 'UserPromptSubmit', `${quoteArg(nodePath)} ${quoteArg(spotterBin)} codex-hook user-prompt-submit`);
-  addCodexHook(next, 'Stop', `${quoteArg(nodePath)} ${quoteArg(spotterBin)} codex-hook stop`);
+  addCodexHook(next, 'UserPromptSubmit', `${prefix}${quoteArg(nodePath)} ${quoteArg(spotterBin)} codex-hook user-prompt-submit`);
+  addCodexHook(next, 'Stop', `${prefix}${quoteArg(nodePath)} ${quoteArg(spotterBin)} codex-hook stop`);
   return next;
 }
 
@@ -932,7 +944,7 @@ function isSpotterCodexHook(hook) {
 }
 
 function isSpotterCodexCommand(command, event = null) {
-  const match = command.match(/^(?:"((?:\\.|[^"\\])*)"|(\S+))\s+(?:"((?:\\.|[^"\\])*)"|(\S+))\s+codex-hook\s+(session-start|user-prompt-submit|stop)\s*$/);
+  const match = command.match(/^(?:&\s+)?(?:"((?:\\.|[^"\\])*)"|(\S+))\s+(?:"((?:\\.|[^"\\])*)"|(\S+))\s+codex-hook\s+(session-start|user-prompt-submit|stop)\s*$/);
   if (!match) return false;
   const nodePath = unescapeQuotedCommandToken(match[1] ?? match[2]);
   const spotterPath = unescapeQuotedCommandToken(match[3] ?? match[4]);

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';
@@ -278,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

@@ -635,7 +635,7 @@ async function runWindowsAcl(path, { directory }, options) {
   const executable = options.powerShellPath ?? 'powershell.exe';
   const script = buildWindowsAclPowerShell({ directory });
   await spawnForExit(executable, ['-NoProfile', '-NonInteractive', '-Command', script], {
-    timeoutMs: options.aclTimeoutMs ?? 3_000,
+    timeoutMs: options.aclTimeoutMs ?? 15_000,
     env: { ...process.env, SPOTTER_ACL_PATH: path },
   });
 }

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 ''; }
+}

package/src/hooks/session-end.mjs

@@ -20,6 +20,7 @@ export async function runSessionEnd({
   readInput = readStdinJson,
   sendRequestFn = sendRequest,
   recordHookEventFn = recordClaudeHookEvent,
+  writeError = (text) => process.stderr.write(text),
 } = {}) {
   if (isChildCall()) return;
   const input = await readInput();
@@ -41,6 +42,13 @@ export async function runSessionEnd({
       event: { hook: 'SessionEnd', status: 'shutdown', durationMs: Date.now() - startedAt },
     });
   } catch (err) {
+    if (err?.code === 'E_UNREACHABLE') {
+      await recordHookEventFn({
+        projectRoot,
+        event: { hook: 'SessionEnd', status: 'already-stopped', durationMs: Date.now() - startedAt },
+      });
+      return;
+    }
     await recordHookEventFn({
       projectRoot,
       event: {
@@ -51,8 +59,7 @@ export async function runSessionEnd({
       },
     });
     // §14.1 exception — don't fail the Claude Code session just because cleanup failed.
-    process.stderr.write(`spotter-hook: session-end shutdown warning: ${err.code ?? '?'}: ${err.message}\n`);
-    process.exit(0);
+    writeError(`spotter-hook: session-end shutdown warning: ${err.code ?? '?'}: ${err.message}\n`);
   }
 }