claude-spotter 1.5.12 → 1.5.13

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 各節はそのversion公開時点の変更記録であり、後続versionにより置換された仕様を含む。
 現行runtime契約は[`docs/00_overview.md`](docs/00_overview.md)から辿る。
 
+## 1.5.13 — 2026-08-23
+
+- **OS依存を`src/platform/`へ集約。** 6ファイルへ重複していたWindowsのcmd.exe /c wrap・
+  `.cmd` shim解決・`windowsHide`強制を[spawn.mjs](src/platform/spawn.mjs)の
+  `windowsCompatibleCommand` / `execFileWindowsSafe`へ一本化し、socket/Named Pipeの
+  path生成・権限・stale socket除去を[ipc.mjs](src/platform/ipc.mjs)へ、パス表記正規化と
+  PATH実行体探索を[paths.mjs](src/platform/paths.mjs)へ移設した。`windows-cli-shim.mjs`は
+  `platform/spawn.mjs`へ吸収した。
+- **ベンダー依存の決定点を`src/host/adapters.mjs`へ集約。** hostごとのtool-db file名と
+  snapshot builder選択をadapter tableで引き、loader / refreshの`if (hostAgent === 'codex')`
+  分岐を業務ロジックから消した。Claude側discovery実装は`investigate-codex.mjs`と対称の
+  [investigate-claude.mjs](src/tool-db/investigate-claude.mjs)へ逐語移設した。
+- **公開契約は変更なし。** 既存のexport名・`{cmd, cmdArgs}` shape・hook/daemon IPC・
+  CLI表面・test fixtureは再exportで維持し、挙動変更ゼロ（`node --test` 593 pass）。
+  配置規約はAGENTS.md「依存の配置規約」として正典化した。
+
 ## 1.5.12 — 2026-08-18
 
 - **Stop未観測の評価turnを次prompt時に採点して閉じる。** 実測でoutcome_missing 2,091件の94%が

package/docs/11_dashboard-operations.md

@@ -1,7 +1,7 @@
 # Spotter評価dashboard運用
 
-現行npm配布版: **v1.5.12**（2026-08-18）。v1.5.12は評価の採点方式と表示名
-（提案適合率（上限））を変更し、dashboardのrouting構成は変更していない。
+現行npm配布版: **v1.5.13**（2026-08-23）。v1.5.13はOS依存・ベンダー依存の内部配置だけを
+変更した挙動同一リファクタで、評価・dashboardのrouting構成は変更していない。
 
 この文書はservice設定の正本であり、各端末に現在installされているnpm versionの台帳ではない。
 端末versionは対象端末で`spotter --version`を実行して確認する。

package/package.json

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

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

@@ -7,7 +7,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 { buildWindowsCompatibleInvocation } from '../platform/spawn.mjs';
 import { codexLastAssistantMessage, readCodexToolUsage } from '../core/codex-transcript.mjs';
 import { readLocal } from '../tool-db/refresh.mjs';
 import { spawnRefreshDetached } from '../hooks/spawn-daemon.mjs';

package/src/cli/doctor.mjs

@@ -8,7 +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';
+import { buildWindowsCompatibleInvocation, execFileWindowsSafe } from '../platform/spawn.mjs';
 
 const execFileP = promisify(execFile);
 
@@ -23,13 +23,9 @@ export async function runDoctor() {
   mark(okNode, `Node.js ${nodeVersion}`, 'need >= 22.13');
   if (!okNode) failures += 1;
 
-  // claude CLI — on Windows the entry is `claude.cmd`; route through cmd.exe /c
-  // rather than shell:true (DEP0190 on Node 24+).
+  // claude CLI — Windows の .cmd shim 解決は src/platform/spawn.mjs が所有する。
   try {
-    const opts = { timeout: 5_000, windowsHide: true };
-    const { stdout } = process.platform === 'win32'
-      ? await execFileP('cmd.exe', ['/c', 'claude', '--version'], opts)
-      : await execFileP('claude', ['--version'], opts);
+    const { stdout } = await execFileWindowsSafe('claude', ['--version'], { timeout: 5_000 });
     mark(true, `claude CLI: ${stdout.trim()}`);
   } catch (err) {
     mark(false, 'claude CLI', `not found or failed: ${err.message}`);

package/src/cli/install.mjs

@@ -15,7 +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 { buildWindowsCompatibleInvocation } from '../platform/spawn.mjs';
 import { homedir } from 'node:os';
 import { join, resolve, dirname, delimiter, extname } from 'node:path';
 import { fileURLToPath } from 'node:url';

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

@@ -1,9 +1,5 @@
-import { statSync } from 'node:fs';
-import { posix, win32 } from 'node:path';
-
 // Configuration-time (synchronous) check for whether `codex` is on PATH.
-// No subprocess is spawned. The function walks env.PATH and tests each candidate
-// with `fs.statSync`; PATHEXT-equivalent extensions are added on Windows.
+// No subprocess is spawned. OS依存のPATH walkは src/platform/paths.mjs が所有する。
 //
 // This is consumed by `selectByPolicy` in auditor-backend.mjs to choose the
 // Claude-host primary auditor: when codex is reachable, the daemon prefers
@@ -11,41 +7,16 @@ import { posix, win32 } from 'node:path';
 // throw `AuditorBackendError` — selection-time availability does not become a
 // runtime fallback.
 
-const WINDOWS_EXTS = ['.cmd', '.exe', '.bat'];
+import { isExecutableOnPath } from '../platform/paths.mjs';
 
 export function isCodexCliAvailable({
   env = process.env,
   platform = process.platform,
-  fileExists = defaultFileExists,
+  fileExists,
 } = {}) {
-  const pathVar = pickPathVar(env, platform);
-  if (typeof pathVar !== 'string' || pathVar.length === 0) return false;
-  const sep = platform === 'win32' ? ';' : ':';
-  const join = platform === 'win32' ? win32.join : posix.join;
-  const candidates = platform === 'win32'
-    ? WINDOWS_EXTS.map((ext) => `codex${ext}`)
-    : ['codex'];
-  for (const rawDir of pathVar.split(sep)) {
-    const dir = rawDir.trim();
-    if (dir.length === 0) continue;
-    for (const candidate of candidates) {
-      if (fileExists(join(dir, candidate))) return true;
-    }
-  }
-  return false;
-}
-
-function pickPathVar(env, platform) {
-  if (platform === 'win32') {
-    return env?.Path ?? env?.PATH ?? env?.path ?? '';
-  }
-  return env?.PATH ?? '';
-}
-
-function defaultFileExists(p) {
-  try {
-    return statSync(p).isFile();
-  } catch {
-    return false;
-  }
+  return isExecutableOnPath('codex', {
+    env,
+    platform,
+    ...(fileExists ? { fileExists } : {}),
+  });
 }

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

@@ -10,7 +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';
+import { buildWindowsCompatibleInvocation, terminateProcessTree } from '../platform/spawn.mjs';
 
 const DEFAULT_CODEX_CLI_TIMEOUT_MS = 45_000;
 const DEFAULT_CODEX_CLI_MODEL = CODEX_AUDITOR_MODEL_POLICY.production.model;

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

@@ -6,7 +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';
+import { buildWindowsCompatibleInvocation } from '../platform/spawn.mjs';
 
 const execFileP = promisify(execFile);
 const DEFAULT_CODEX_SIDECAR_AUDITOR_TIMEOUT_MS = 45_000;

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

@@ -16,7 +16,7 @@ import {
   createSidecarResultRecord,
   spotterFindingsToSidecarContextBlocks,
 } from './sidecar-context.mjs';
-import { buildWindowsCompatibleInvocation } from './windows-cli-shim.mjs';
+import { buildWindowsCompatibleInvocation } from '../platform/spawn.mjs';
 
 const execFileP = promisify(execFile);
 const WORKFLOW_MAP = {

package/src/daemon/daemon.mjs

@@ -483,7 +483,7 @@ export async function startDaemon({
   } catch (error) {
     await observeFailure('daemon_persistence');
     await new Promise((resolve) => server.close(resolve)).catch(() => {});
-    if (process.platform !== 'win32') await unlink(path).catch(() => {});
+    await removeStaleSocketFile(path).catch(() => {});
     throw error;
   }
 
@@ -538,14 +538,10 @@ async function shutdown(server, sessionId, logFn, evaluationStore = null) {
   } catch (err) {
     logFn(`shutdown: server.close failed: ${err.message}`);
   }
-  if (process.platform !== 'win32') {
-    try {
-      await unlink(socketPath(sessionId));
-    } catch (err) {
-      if (err.code !== 'ENOENT') {
-        logFn(`shutdown: unlink socket failed: ${err.message}`);
-      }
-    }
+  try {
+    await removeStaleSocketFile(socketPath(sessionId));
+  } catch (err) {
+    logFn(`shutdown: unlink socket failed: ${err.message}`);
   }
   try {
     await unlink(pidFilePath(sessionId));

package/src/daemon/haiku-caller.mjs

@@ -14,6 +14,7 @@
 // puts the catalog only in the first turn's user message; the session retains it for free.
 
 import { spawn } from 'node:child_process';
+import { windowsCompatibleCommand } from '../platform/spawn.mjs';
 import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { mkdir, writeFile, unlink, open } from 'node:fs/promises';
@@ -241,9 +242,7 @@ export async function preparePromptFile(wirePrompt) {
   };
 }
 
-// On Windows, the `claude` entry is typically a .cmd shim which Node's spawn cannot locate
-// without going through the shell. We use cmd.exe /c explicitly rather than spawn({ shell:
-// true }) because the latter triggers DEP0190 on Node 24+.
+// Windows の .cmd shim 解決 (cmd.exe /c wrap) は src/platform/spawn.mjs が所有する。
 //
 // v1.3.0: `--strict-mcp-config --mcp-config <empty>` を必ず付けて MCP load を無効化する。
 // `mcpConfigPath` は呼び出し側 (createHaikuCaller) が必ず渡す前提。テストで shape を pin。
@@ -255,10 +254,8 @@ export function buildSpawnArgs({ claudeBin, model, sessionId, resume, mcpConfigP
     ? ['-p', '--resume', sessionId, '--model', model]
     : ['-p', '--session-id', sessionId, '--model', model];
   const args = [...baseArgs, '--strict-mcp-config', '--mcp-config', mcpConfigPath];
-  if (process.platform === 'win32') {
-    return { cmd: 'cmd.exe', cmdArgs: ['/c', claudeBin, ...args] };
-  }
-  return { cmd: claudeBin, cmdArgs: args };
+  const invocation = windowsCompatibleCommand(claudeBin, args);
+  return { cmd: invocation.command, cmdArgs: invocation.args };
 }
 
 // Invoke `claude -p` in the isolated workdir. Returns raw stdout.

package/src/daemon/transport.mjs

@@ -4,54 +4,11 @@
 
 import net from 'node:net';
 import { randomUUID } from 'node:crypto';
-import { chmod, mkdir, unlink } from 'node:fs/promises';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { socketPath } from '../platform/ipc.mjs';
 
-const RUNTIME_DIR = join(homedir(), '.spotter', 'runtime');
-
-export function socketPath(sessionId) {
-  if (!sessionId || typeof sessionId !== 'string') {
-    throw new TypeError('sessionId must be a non-empty string');
-  }
-  if (process.platform === 'win32') {
-    return `\\\\.\\pipe\\spotter-${sessionId}`;
-  }
-  return join(RUNTIME_DIR, `session-${sessionId}.sock`);
-}
-
-export async function ensureRuntimeDir() {
-  await mkdir(RUNTIME_DIR, { recursive: true, mode: 0o700 });
-  if (process.platform !== 'win32') {
-    await chmod(RUNTIME_DIR, 0o700);
-  }
-  return RUNTIME_DIR;
-}
-
-export async function secureSocketFile(path) {
-  if (process.platform === 'win32') return;
-  await chmod(path, 0o600);
-}
-
-// Remove a Unix domain socket file left behind by a daemon that died ungracefully (SIGKILL,
-// crash, or machine sleep before SessionEnd ran stop()'s cleanup). stop() unlinks the socket only
-// on graceful shutdown, so an orphan file persists otherwise. The CALLER MUST have already
-// confirmed no live daemon owns this session (assertNoLiveDaemon) — only then is the file known to
-// be stale. Without removing it, server.listen(path) fails with EADDRINUSE and the daemon dies
-// before "daemon listening", so every resurrect attempt crash-loops and the session is never
-// audited again (observed: Kikoeru session 83d7aa04 — 5 failed restarts, all stuck at backend
-// selection). ENOENT is the normal first-run / no-stale-file case and is ignored; any other error
-// is rethrown (§0: no silent swallow). No-op on Windows — a Named Pipe vanishes when its owning
-// process exits, so there is no filesystem artifact to remove.
-export async function removeStaleSocketFile(path) {
-  if (process.platform === 'win32') return;
-  try {
-    await unlink(path);
-  } catch (err) {
-    if (err?.code === 'ENOENT') return;
-    throw err;
-  }
-}
+// OS依存のsocket/pipe面 (path生成・権限・stale socket除去) は src/platform/ipc.mjs が
+// 所有する。既存importerのためここから同名で再exportする。
+export { socketPath, ensureRuntimeDir, secureSocketFile, removeStaleSocketFile } from '../platform/ipc.mjs';
 
 // Request/response over a single connection. Used by hooks.
 export function sendRequest({ sessionId, event, payload, timeoutMs }) {

package/src/host/adapters.mjs

@@ -0,0 +1,53 @@
+// AIベンダー（host agent）依存の決定点の唯一の置き場。
+// 「どのhostがどのtool-db fileを持ち、どのdiscovery経路でsnapshotを作るか」は
+// このtableだけが知る。呼び出し側（loader / refresh / CLI）は adapter を引いて
+// 使うだけで、`if (hostAgent === 'codex')` 分岐を業務ロジックに書かない。
+//
+// ベンダー固有の実装本体は従来どおり investigate-claude.mjs / investigate-codex.mjs
+// が持つ。片方のhostのrefreshがもう片方のDBをprune / overwriteしない契約
+// （AGENTS.md「ツールカタログはhost-local tool-db」）はこの分離が担保する。
+
+import { buildInvestigationSnapshot } from '../tool-db/investigate-claude.mjs';
+import { buildCodexInvestigationSnapshot } from '../tool-db/investigate-codex.mjs';
+
+const CLAUDE_ADAPTER = Object.freeze({
+  hostAgent: 'claude',
+  toolDbFileName: 'tool-db.json',
+  buildSnapshot: ({ logFn, claudeBin, projectRoot }) =>
+    buildInvestigationSnapshot({ logFn, claudeBin, projectRoot }),
+});
+
+const CODEX_ADAPTER = Object.freeze({
+  hostAgent: 'codex',
+  toolDbFileName: 'tool-db.codex.json',
+  buildSnapshot: ({ logFn, codexBin, projectRoot }) =>
+    buildCodexInvestigationSnapshot({ logFn, codexBin, projectRoot }),
+});
+
+// automation (CI等) は従来からClaude経路のdiscoveryを使い、DB fileだけ分離する。
+const AUTOMATION_ADAPTER = Object.freeze({
+  hostAgent: 'automation',
+  toolDbFileName: 'tool-db.automation.json',
+  buildSnapshot: ({ logFn, claudeBin, projectRoot }) =>
+    buildInvestigationSnapshot({ logFn, claudeBin, projectRoot }),
+});
+
+const ADAPTERS = Object.freeze({
+  claude: CLAUDE_ADAPTER,
+  codex: CODEX_ADAPTER,
+  automation: AUTOMATION_ADAPTER,
+});
+
+export function normalizeToolDbHostAgent(hostAgent = 'claude') {
+  if (hostAgent === undefined || hostAgent === null || hostAgent === '') {
+    return 'claude';
+  }
+  if (Object.hasOwn(ADAPTERS, hostAgent)) {
+    return hostAgent;
+  }
+  throw new TypeError(`tool-db hostAgent must be claude, codex, or automation; got ${hostAgent}`);
+}
+
+export function getHostAdapter(hostAgent = 'claude') {
+  return ADAPTERS[normalizeToolDbHostAgent(hostAgent)];
+}

package/src/platform/ipc.mjs

@@ -0,0 +1,52 @@
+// OS依存のhook⇄daemon IPC面の唯一の置き場。
+// Unix domain socket (macOS/Linux) と Named Pipe (Windows) の差はこのファイルが
+// 所有し、呼び出し側 (transport / daemon) は process.platform を見ない。
+
+import { chmod, mkdir, unlink } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const RUNTIME_DIR = join(homedir(), '.spotter', 'runtime');
+
+export function socketPath(sessionId) {
+  if (!sessionId || typeof sessionId !== 'string') {
+    throw new TypeError('sessionId must be a non-empty string');
+  }
+  if (process.platform === 'win32') {
+    return `\\\\.\\pipe\\spotter-${sessionId}`;
+  }
+  return join(RUNTIME_DIR, `session-${sessionId}.sock`);
+}
+
+export async function ensureRuntimeDir() {
+  await mkdir(RUNTIME_DIR, { recursive: true, mode: 0o700 });
+  if (process.platform !== 'win32') {
+    await chmod(RUNTIME_DIR, 0o700);
+  }
+  return RUNTIME_DIR;
+}
+
+export async function secureSocketFile(path) {
+  if (process.platform === 'win32') return;
+  await chmod(path, 0o600);
+}
+
+// Remove a Unix domain socket file left behind by a daemon that died ungracefully (SIGKILL,
+// crash, or machine sleep before SessionEnd ran stop()'s cleanup). stop() unlinks the socket only
+// on graceful shutdown, so an orphan file persists otherwise. The CALLER MUST have already
+// confirmed no live daemon owns this session (assertNoLiveDaemon) — only then is the file known to
+// be stale. Without removing it, server.listen(path) fails with EADDRINUSE and the daemon dies
+// before "daemon listening", so every resurrect attempt crash-loops and the session is never
+// audited again (observed: Kikoeru session 83d7aa04 — 5 failed restarts, all stuck at backend
+// selection). ENOENT is the normal first-run / no-stale-file case and is ignored; any other error
+// is rethrown (§0: no silent swallow). No-op on Windows — a Named Pipe vanishes when its owning
+// process exits, so there is no filesystem artifact to remove.
+export async function removeStaleSocketFile(path) {
+  if (process.platform === 'win32') return;
+  try {
+    await unlink(path);
+  } catch (err) {
+    if (err?.code === 'ENOENT') return;
+    throw err;
+  }
+}

package/src/platform/paths.mjs

@@ -0,0 +1,60 @@
+// OS依存のパス表記・PATH探索の唯一の置き場。
+
+import { statSync } from 'node:fs';
+import { posix, win32 } from 'node:path';
+
+// Synchronous PATH walk: is `command` reachable as an executable file on PATH?
+// No subprocess is spawned. Windows adds PATHEXT-equivalent extensions and reads
+// PATH case-insensitively (Path / PATH / path).
+export function isExecutableOnPath(command, {
+  env = process.env,
+  platform = process.platform,
+  windowsExtensions = ['.cmd', '.exe', '.bat'],
+  fileExists = defaultFileExists,
+} = {}) {
+  const pathVar = platform === 'win32'
+    ? (env?.Path ?? env?.PATH ?? env?.path ?? '')
+    : (env?.PATH ?? '');
+  if (typeof pathVar !== 'string' || pathVar.length === 0) return false;
+  const sep = platform === 'win32' ? ';' : ':';
+  const join = platform === 'win32' ? win32.join : posix.join;
+  const candidates = platform === 'win32'
+    ? windowsExtensions.map((ext) => `${command}${ext}`)
+    : [command];
+  for (const rawDir of pathVar.split(sep)) {
+    const dir = rawDir.trim();
+    if (dir.length === 0) continue;
+    for (const candidate of candidates) {
+      if (fileExists(join(dir, candidate))) return true;
+    }
+  }
+  return false;
+}
+
+function defaultFileExists(p) {
+  try {
+    return statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+// Normalize an absolute project path for matching against config keys (e.g.
+// `~/.claude.json` `projects[]`). Representation can drift across:
+//   - separator: `\` on Windows vs `/`
+//   - drive-letter case: `C:\` vs `c:\` on Windows
+//   - trailing slash: `/foo/bar` vs `/foo/bar/`
+// On Windows we canonicalize to forward slashes and lower-case (case-insensitive
+// filesystem). On POSIX, `\` is a legal filename character — collapsing it to `/`
+// would conflate genuinely distinct paths (e.g. literal `C:\Users\u\proj` vs the
+// hypothetical POSIX path `C:/Users/u/proj`), and case stays significant. POSIX
+// only normalizes the trailing slash.
+export function normalizeProjectPath(p) {
+  if (typeof p !== 'string' || p.length === 0) return '';
+  let s = p;
+  if (process.platform === 'win32') {
+    s = s.replace(/\\/g, '/').toLowerCase();
+  }
+  s = s.replace(/\/+$/, '');
+  return s;
+}

package/src/{core/windows-cli-shim.mjs → platform/spawn.mjs}

@@ -1,6 +1,49 @@
-import { spawn } from 'node:child_process';
+// OS依存のプロセス起動プリミティブの唯一の置き場。
+// Windows の .cmd shim 解決・cmd.exe /c wrap・windowsHide・process tree 終了は
+// すべてこのファイルが所有し、呼び出し側は process.platform を見ない。
+//
+// 2 種類の Windows コマンド解決を提供する:
+//   - windowsCompatibleCommand: 素朴な cmd.exe /c wrap (.exe は直接起動)。
+//     bare 名 / .cmd shim を PATHEXT 経由で起動する高頻度経路用。
+//   - buildWindowsCompatibleInvocation: npm shim の実体 (.cjs/.mjs/.js) を
+//     解決して node で直接起動する精密経路。cmd.exe を避けたい場合に使う。
+
+import { execFile, spawn } from 'node:child_process';
 import { readFileSync, statSync } from 'node:fs';
 import { win32 } from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileP = promisify(execFile);
+
+// On Windows, npm-global CLI tools (e.g. `claude`, `codex`, `claude-mermaid`) ship as
+// `<name>.cmd` batch wrappers. Node's `child_process` without `shell: true` calls
+// Windows `CreateProcess`, which only directly executes `.exe` files — it does NOT
+// search PATHEXT for `.cmd`/`.bat` shims when given a bare command name, so
+// `spawn('claude', ...)` fails with ENOENT even though `claude.cmd` is on PATH.
+//
+// We route any non-`.exe` command through `cmd.exe /c` on Windows, which makes
+// PATHEXT lookup apply and runs both `.cmd` shims and bare names transparently.
+// Absolute `.exe` paths stay un-wrapped because (a) they spawn correctly as-is and
+// (b) wrapping them through `cmd.exe /c "<path with spaces>" args` runs into
+// cmd.exe's quoting rules for paths containing spaces, which add risk for zero
+// benefit. We use `cmd.exe /c` explicitly rather than `spawn({ shell: true })`
+// because the latter triggers DEP0190 on Node 24+ and re-introduces
+// argument-quoting risks (caveat:
+// `windows-node-spawn-claude-fails-with-enoent-because-claude-is-a-cmd-wrapper`).
+export function windowsCompatibleCommand(command, args = [], { platform = process.platform } = {}) {
+  if (platform !== 'win32' || /\.exe$/i.test(command)) {
+    return { command, args };
+  }
+  return { command: 'cmd.exe', args: ['/c', command, ...args] };
+}
+
+// execFile を windowsCompatibleCommand + windowsHide 強制で実行する。
+// `windowsHide: true` はこの層で強制する — 無いと Windows で cmd.exe の console
+// window が毎回 flash して入力フォーカスを奪う (v1.1.5 の実被弾)。
+export async function execFileWindowsSafe(command, args = [], opts = {}) {
+  const invocation = windowsCompatibleCommand(command, args);
+  return execFileP(invocation.command, invocation.args, { ...opts, windowsHide: true });
+}
 
 // Windows の npm global CLI は多くが `<name>.cmd` shim であり、Node の shell:false
 // 直接 spawn では PATHEXT 解決されない。cmd.exe を明示して Node 24 の shell:true

package/src/tool-db/investigate-claude.mjs

@@ -0,0 +1,71 @@
+// Claude-native catalog investigation (investigate-codex.mjs の Claude 対称)。
+// `claude mcp list` + Claude skills / sub-agents から (name → description) snapshot を作る。
+
+import { listMcpToolsAll, listMcpServers, bellVisibleName } from './investigate-mcp.mjs';
+import { getClaudeAiBaselineByServer } from './claude-ai-baseline.mjs';
+import { listSkillsAll } from './investigate-skills.mjs';
+import { listAgentsAll } from './investigate-agents.mjs';
+
+// Pure filter: returns the subset of the claude.ai baseline whose server name is
+// present in `presentServerNames`. Accepts a Set for O(1) membership. Extracted as
+// a named export so it can be unit-tested without a live `claude` CLI.
+export function filterClaudeAiBaseline(presentServerNames) {
+  const out = new Map();
+  for (const [serverName, tools] of getClaudeAiBaselineByServer()) {
+    if (!presentServerNames.has(serverName)) continue;
+    for (const [toolName, description] of Object.entries(tools)) {
+      out.set(toolName, description);
+    }
+  }
+  return out;
+}
+
+// Build the (name → description) map for an investigation pass across all sources:
+//   - claude.ai MCP baseline (Gmail / Calendar / Drive — OAuth, not locally introspectable)
+//   - MCP servers via stdio + HTTP/SSE (user + project .mcp.json, live fetched)
+//   - Skills from user scope, project scope, and enabled plugins
+//   - Sub-agents from user scope, project scope, and enabled plugins
+//
+// Returns an in-memory snapshot the caller can use as the investigate() backend.
+export async function buildInvestigationSnapshot({ logFn = () => {}, claudeBin = 'claude', projectRoot } = {}) {
+  const snapshot = new Map();
+
+  // Anthropic-provided `claude.ai ...` MCP servers. Hardcoded because the OAuth proxy
+  // is not reachable without reading ~/.claude/.credentials.json (deliberately avoided).
+  // Injected only for servers actually present in `claude mcp list` — otherwise phantom
+  // tools (Gmail/Calendar/Drive) leak into environments where those servers are not
+  // connected. See filterClaudeAiBaseline above.
+  const servers = await listMcpServers({ claudeBin, projectRoot });
+  const presentServerNames = new Set(servers.map((s) => s.name));
+  const baseline = filterClaudeAiBaseline(presentServerNames);
+  for (const [name, description] of baseline) {
+    snapshot.set(name, description);
+  }
+  if (baseline.size > 0) {
+    logFn(`claude.ai baseline injected: ${baseline.size} tools from ${[...presentServerNames].filter((n) => n.startsWith('claude.ai ')).join(', ')}`);
+  }
+
+  // MCP servers (stdio + user-registered HTTP/SSE). projectRoot forwards for
+  // project-scope `.mcp.json` merge (see mcp-config.mjs).
+  const mcp = await listMcpToolsAll({ logFn, claudeBin, projectRoot });
+  for (const [serverName, tools] of mcp.entries()) {
+    for (const tool of tools) {
+      if (!tool.description || tool.description.length === 0) continue;
+      snapshot.set(bellVisibleName(serverName, tool.name), tool.description);
+    }
+  }
+
+  // Skills (plugin-namespaced as `<plugin>:<name>`, or bare for user/project scope).
+  const skills = await listSkillsAll({ logFn, projectRoot });
+  for (const [name, description] of skills) {
+    snapshot.set(name, description);
+  }
+
+  // Sub-agents (bare name; project > user > plugin precedence resolved internally).
+  const agents = await listAgentsAll({ logFn, projectRoot });
+  for (const [name, description] of agents) {
+    snapshot.set(name, description);
+  }
+
+  return snapshot;
+}

package/src/tool-db/investigate-codex.mjs

@@ -4,22 +4,16 @@
 // discovery path. Codex and Claude expose different MCP servers and skills, so a
 // Codex refresh must build a separate snapshot and write it to tool-db.codex.json.
 
-import { execFile } from 'node:child_process';
 import { readdir, readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { promisify } from 'node:util';
+import { execFileWindowsSafe } from '../platform/spawn.mjs';
 import { bellVisibleName, listMcpToolsOne, splitArgs } from './investigate-mcp.mjs';
 import { readFrontmatter } from './frontmatter.mjs';
 
-const execFileP = promisify(execFile);
-
+// Windows の .cmd shim 解決と windowsHide 強制は src/platform/spawn.mjs が所有する。
 async function execCodex(codexBin, args, opts) {
-  const execOpts = { ...opts, windowsHide: true };
-  if (process.platform === 'win32') {
-    return execFileP('cmd.exe', ['/c', codexBin, ...args], execOpts);
-  }
-  return execFileP(codexBin, args, execOpts);
+  return execFileWindowsSafe(codexBin, args, opts);
 }
 
 export async function buildCodexInvestigationSnapshot({

package/src/tool-db/investigate-mcp.mjs

@@ -10,29 +10,17 @@
 //   5. ← tools/list result   (response with tools[] each having {name, description})
 
 import { spawn } from 'node:child_process';
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
+import { execFileWindowsSafe, windowsCompatibleCommand } from '../platform/spawn.mjs';
 import { listToolsHttp } from './investigate-mcp-http.mjs';
 import { readMcpServers, describeServer } from './mcp-config.mjs';
 import { version as SPOTTER_VERSION } from '../version.mjs';
 
-const execFileP = promisify(execFile);
-
 const PROTOCOL_VERSION = '2025-03-26'; // MCP protocol version we claim to speak.
 const HANDSHAKE_TIMEOUT_MS = 10_000;
 
-// On Windows, `claude` is a .cmd shim; Node's execFile cannot locate it directly without
-// going through cmd.exe. Matches the pattern in src/daemon/haiku-caller.mjs buildSpawnArgs.
-// We use cmd.exe /c rather than shell:true to avoid DEP0190 on Node 24+.
-// `windowsHide: true` is forced at this layer so every caller (listMcpServers,
-// getStdioConfig, etc.) is silent — without it a cmd.exe console window flashes on every
-// refresh, and those flashes steal keyboard focus on Windows.
+// Windows の .cmd shim 解決と windowsHide 強制は src/platform/spawn.mjs が所有する。
 async function execClaude(claudeBin, args, opts) {
-  const execOpts = { ...opts, windowsHide: true };
-  if (process.platform === 'win32') {
-    return execFileP('cmd.exe', ['/c', claudeBin, ...args], execOpts);
-  }
-  return execFileP(claudeBin, args, execOpts);
+  return execFileWindowsSafe(claudeBin, args, opts);
 }
 
 export class McpInvestigationError extends Error {
@@ -257,36 +245,11 @@ export function splitArgs(s) {
   return out;
 }
 
-// On Windows, npm-global CLI tools (e.g. `claude-mermaid`) ship as `<name>.cmd`
-// batch wrappers. Node's `child_process.spawn` without `shell: true` calls Windows
-// `CreateProcess`, which only directly executes `.exe` files — it does NOT search
-// PATHEXT for `.cmd`/`.bat` shims when given a bare command name. So
-// `spawn('claude-mermaid', ...)` fails with ENOENT even though `claude-mermaid.cmd`
-// is on PATH.
-//
-// Until v1.2.1 this function only wrapped commands whose name literally ended in
-// `.cmd`/`.bat`, which missed the common case where the registered command is a
-// bare name (the CLI as installed). v1.2.2 routes any non-`.exe` command through
-// `cmd.exe /c` on Windows, which makes PATHEXT lookup apply and runs both `.cmd`
-// shims and bare names transparently.
-//
-// We keep absolute `.exe` paths un-wrapped because (a) they spawn correctly as-is
-// and (b) wrapping them through `cmd.exe /c "<path with spaces>" args` runs into
-// cmd.exe's quoting rules for paths containing spaces, which add risk for zero
-// benefit.
-//
-// We use `cmd.exe /c` explicitly rather than `spawn({ shell: true })` because the
-// latter triggers DEP0190 on Node 24+ and re-introduces argument-quoting risks
-// (matches the rationale in haiku-caller's buildSpawnArgs and the caveat
-// `windows-node-spawn-claude-fails-with-enoent-because-claude-is-a-cmd-wrapper`).
+// Windows の cmd.exe /c wrap 規則 (.exe は直接起動) は src/platform/spawn.mjs が所有する。
+// 歴史的な {cmd, cmdArgs} shape は既存呼び出し・test 契約のため維持する。
 export function buildStdioSpawn(command, args) {
-  if (process.platform !== 'win32') {
-    return { cmd: command, cmdArgs: args };
-  }
-  if (/\.exe$/i.test(command)) {
-    return { cmd: command, cmdArgs: args };
-  }
-  return { cmd: 'cmd.exe', cmdArgs: ['/c', command, ...args] };
+  const invocation = windowsCompatibleCommand(command, args);
+  return { cmd: invocation.command, cmdArgs: invocation.args };
 }
 
 async function spawnAndQuery({ command, args, env = {} }, serverName) {

package/src/tool-db/loader.mjs

@@ -23,26 +23,16 @@ export class ToolDbSchemaError extends Error {
   }
 }
 
+// host別のDB file名と正規化は src/host/adapters.mjs が所有する。
+import { getHostAdapter } from '../host/adapters.mjs';
+export { normalizeToolDbHostAgent } from '../host/adapters.mjs';
+
 export function globalDbPath(hostAgent = 'claude') {
-  const host = normalizeToolDbHostAgent(hostAgent);
-  const file = host === 'claude' ? 'tool-db.json' : `tool-db.${host}.json`;
-  return join(homedir(), '.spotter', file);
+  return join(homedir(), '.spotter', getHostAdapter(hostAgent).toolDbFileName);
 }
 
 export function localDbPath(projectRoot, hostAgent = 'claude') {
-  const host = normalizeToolDbHostAgent(hostAgent);
-  const file = host === 'claude' ? 'tool-db.json' : `tool-db.${host}.json`;
-  return join(projectRoot, '.spotter', file);
-}
-
-export function normalizeToolDbHostAgent(hostAgent = 'claude') {
-  if (hostAgent === undefined || hostAgent === null || hostAgent === '') {
-    return 'claude';
-  }
-  if (hostAgent === 'claude' || hostAgent === 'codex' || hostAgent === 'automation') {
-    return hostAgent;
-  }
-  throw new TypeError(`tool-db hostAgent must be claude, codex, or automation; got ${hostAgent}`);
+  return join(projectRoot, '.spotter', getHostAdapter(hostAgent).toolDbFileName);
 }
 
 // Load a DB file. Missing file → returns empty db (this is normal, not an error).

package/src/tool-db/mcp-config.mjs

@@ -87,25 +87,10 @@ async function readMcpServersFile(path) {
   return (data.mcpServers && typeof data.mcpServers === 'object') ? data.mcpServers : {};
 }
 
-// Normalize a project path for matching against `~/.claude.json` `projects[]` keys.
-// Claude stores absolute paths verbatim, but representation can drift across:
-//   - separator: `\` on Windows vs `/`
-//   - drive-letter case: `C:\` vs `c:\` on Windows
-//   - trailing slash: `/foo/bar` vs `/foo/bar/`
-// On Windows we canonicalize to forward slashes and lower-case (case-insensitive
-// filesystem). On POSIX, `\` is a legal filename character — collapsing it to `/`
-// would conflate genuinely distinct paths (e.g. literal `C:\Users\u\proj` vs the
-// hypothetical POSIX path `C:/Users/u/proj`), and case stays significant. POSIX
-// only normalizes the trailing slash.
-export function normalizeProjectPath(p) {
-  if (typeof p !== 'string' || p.length === 0) return '';
-  let s = p;
-  if (process.platform === 'win32') {
-    s = s.replace(/\\/g, '/').toLowerCase();
-  }
-  s = s.replace(/\/+$/, '');
-  return s;
-}
+// OS依存のパス表記正規化は src/platform/paths.mjs が所有する。
+// `~/.claude.json` `projects[]` キー照合の用途と正規化ルールの根拠はそちらを参照。
+import { normalizeProjectPath } from '../platform/paths.mjs';
+export { normalizeProjectPath };
 
 // Extract user-scope `mcpServers` from a parsed `~/.claude.json` object.
 export function extractUserScopeServers(claudeJson) {

package/src/tool-db/refresh.mjs

@@ -11,76 +11,13 @@
 // sub-agents.
 
 import { resolveAll } from './lookup.mjs';
-import { listMcpToolsAll, listMcpServers, bellVisibleName } from './investigate-mcp.mjs';
-import { getClaudeAiBaselineByServer } from './claude-ai-baseline.mjs';
-import { buildCodexInvestigationSnapshot } from './investigate-codex.mjs';
-import { listSkillsAll } from './investigate-skills.mjs';
-import { listAgentsAll } from './investigate-agents.mjs';
-import { localDbPath, globalDbPath, normalizeToolDbHostAgent } from './loader.mjs';
+import { getHostAdapter } from '../host/adapters.mjs';
+import { localDbPath, globalDbPath } from './loader.mjs';
 
-// Pure filter: returns the subset of the claude.ai baseline whose server name is
-// present in `presentServerNames`. Accepts a Set for O(1) membership. Extracted as
-// a named export so it can be unit-tested without a live `claude` CLI.
-export function filterClaudeAiBaseline(presentServerNames) {
-  const out = new Map();
-  for (const [serverName, tools] of getClaudeAiBaselineByServer()) {
-    if (!presentServerNames.has(serverName)) continue;
-    for (const [toolName, description] of Object.entries(tools)) {
-      out.set(toolName, description);
-    }
-  }
-  return out;
-}
-
-// Build the (name → description) map for an investigation pass across all sources:
-//   - claude.ai MCP baseline (Gmail / Calendar / Drive — OAuth, not locally introspectable)
-//   - MCP servers via stdio + HTTP/SSE (user + project .mcp.json, live fetched)
-//   - Skills from user scope, project scope, and enabled plugins
-//   - Sub-agents from user scope, project scope, and enabled plugins
-//
-// Returns an in-memory snapshot the caller can use as the investigate() backend.
-export async function buildInvestigationSnapshot({ logFn = () => {}, claudeBin = 'claude', projectRoot } = {}) {
-  const snapshot = new Map();
-
-  // Anthropic-provided `claude.ai ...` MCP servers. Hardcoded because the OAuth proxy
-  // is not reachable without reading ~/.claude/.credentials.json (deliberately avoided).
-  // Injected only for servers actually present in `claude mcp list` — otherwise phantom
-  // tools (Gmail/Calendar/Drive) leak into environments where those servers are not
-  // connected. See filterClaudeAiBaseline above.
-  const servers = await listMcpServers({ claudeBin, projectRoot });
-  const presentServerNames = new Set(servers.map((s) => s.name));
-  const baseline = filterClaudeAiBaseline(presentServerNames);
-  for (const [name, description] of baseline) {
-    snapshot.set(name, description);
-  }
-  if (baseline.size > 0) {
-    logFn(`claude.ai baseline injected: ${baseline.size} tools from ${[...presentServerNames].filter((n) => n.startsWith('claude.ai ')).join(', ')}`);
-  }
-
-  // MCP servers (stdio + user-registered HTTP/SSE). projectRoot forwards for
-  // project-scope `.mcp.json` merge (see mcp-config.mjs).
-  const mcp = await listMcpToolsAll({ logFn, claudeBin, projectRoot });
-  for (const [serverName, tools] of mcp.entries()) {
-    for (const tool of tools) {
-      if (!tool.description || tool.description.length === 0) continue;
-      snapshot.set(bellVisibleName(serverName, tool.name), tool.description);
-    }
-  }
-
-  // Skills (plugin-namespaced as `<plugin>:<name>`, or bare for user/project scope).
-  const skills = await listSkillsAll({ logFn, projectRoot });
-  for (const [name, description] of skills) {
-    snapshot.set(name, description);
-  }
-
-  // Sub-agents (bare name; project > user > plugin precedence resolved internally).
-  const agents = await listAgentsAll({ logFn, projectRoot });
-  for (const [name, description] of agents) {
-    snapshot.set(name, description);
-  }
-
-  return snapshot;
-}
+// ベンダー別のsnapshot builderと実装本体は investigate-claude.mjs /
+// investigate-codex.mjs へ移設し、選択は src/host/adapters.mjs が所有する。
+// 既存importer・test契約のため同名で再exportする。
+export { buildInvestigationSnapshot, filterClaudeAiBaseline } from './investigate-claude.mjs';
 
 // Refresh the tool-db. Discovers all currently available tools, resolves each via the
 // 3-tier lookup, writes through. Returns the resolved Map.
@@ -91,17 +28,15 @@ export async function refresh({
   codexBin = 'codex',
   hostAgent = 'claude',
 } = {}) {
-  const toolDbHostAgent = normalizeToolDbHostAgent(hostAgent);
-  const snapshot = toolDbHostAgent === 'codex'
-    ? await buildCodexInvestigationSnapshot({ logFn, codexBin, projectRoot })
-    : await buildInvestigationSnapshot({ logFn, claudeBin, projectRoot });
+  const adapter = getHostAdapter(hostAgent);
+  const snapshot = await adapter.buildSnapshot({ logFn, claudeBin, codexBin, projectRoot });
   const toolNames = Array.from(snapshot.keys());
   const investigate = async (name) => snapshot.get(name) ?? null;
 
   return resolveAll({
     toolNames,
-    localPath: localDbPath(projectRoot, toolDbHostAgent),
-    globalPath: globalDbPath(toolDbHostAgent),
+    localPath: localDbPath(projectRoot, adapter.hostAgent),
+    globalPath: globalDbPath(adapter.hostAgent),
     investigate,
     logFn,
   });