claude-spotter 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.6.2
+
+**親プロセス watch による孤児 daemon 自動回収**。SessionEnd が発火しない経路 (Claude Code crash, kill -9, IDE reload) で daemon が永久に残る問題への対処。
+
+### 事の発端
+
+実運用で `spotter status` を見ると、現セッション以外に複数の daemon が `process=alive` で残存している状態が頻発していた。今回の観測では 9 個中 8 個が孤児で、手動 `taskkill` + `.pid` ファイル削除で掃除する必要があった。原因は SessionEnd hook が**正常終了経路でしか発火しない**こと。Claude Code の crash、強制終了、VSCode リロード等のいずれかで daemon は親を失っても生き続ける。v0.2 スコープに「孤児 cleanup」と書いてあったが未実装のままだった。
+
+### 変更点
+
+- **[src/daemon/daemon.mjs](src/daemon/daemon.mjs)**: `startDaemon({ parentPid, parentWatchIntervalMs })` を追加。`parentPid` が指定されると 5 秒間隔 (default) で `process.kill(parentPid, 0)` を ping し、ESRCH を検知したら自身を shutdown。`parentWatchIntervalMs` はテスト用に短縮可能。`parentPid !== null && (!Number.isInteger || <= 0)` は TypeError で reject。
+- **[src/cli/daemon-cmd.mjs](src/cli/daemon-cmd.mjs)**: `--parent-pid <N>` 引数をパースして `startDaemon` に渡す。
+- **[src/hooks/session-start.mjs](src/hooks/session-start.mjs)**: daemon spawn 時に `--parent-pid <process.ppid>` を付与。`process.ppid` は SessionStart hook から見た親 = Claude Code 本体。
+- **[test/daemon.test.mjs](test/daemon.test.mjs)**: 子プロセスを fake parent として spawn → daemon 起動 → 子を SIGKILL → daemon の `server.on('close')` が発火することを検証する E2E テストを追加。`parentPid: 0` / `1.5` が TypeError になることのバリデーションテストも追加。
+
+### 効果
+
+- 通常運用 (SessionEnd 発火経路) では従来どおり graceful shutdown
+- 異常終了経路 (crash, kill, reload) では親消滅を最大 5 秒で検知して自殺
+- 観測コスト: `process.kill(pid, 0)` の syscall が 5 秒に 1 回。idle CPU 影響は無視できる程度
+
+### 既知の制約
+
+- 親 PID を持たない経路 (手動 `spotter daemon start --session-id ...`) では watch が動かない (parentPid が null)。これは debug 用なので許容。
+- Claude Code が中間プロセス (cmd.exe / sh wrapper) 越しに hook を起動している場合、`process.ppid` が wrapper を指す可能性あり。今回の Windows 環境では実測で Claude Code 本体を指していたが、将来的に環境差で問題が出れば PID 取得方法を再検討。
+- 5 秒間隔のため、kill 直後の最大 5 秒は孤児状態が残る。これ以上短縮するなら polling コストとのトレードオフ再評価。
+
+## 0.6.1
+
+**v0.6.0 で `src/version.mjs` を更新し忘れた trivia fix**。`spotter --version` が古い `0.5.2` を返していた。挙動差はない。
+
 ## 0.6.0
 
 **Preamble-once: 初回のみ role+schema+catalog を送り、以降は per-turn delta のみ**。v0.5.x で実測した「resumed 呼び出しが first より遅い」問題の原因に手を入れた構造変更。

package/README.md

@@ -1,12 +1,12 @@
 # Spotter
 
-> **v0.4.3 released 2026-04-19**. v0.2.0 で追加した session-scoped Haiku は Spotter 本体プロジェクトでの長時間運用中に role collapse (Haiku が Bell 人格に drift) を起こしたため、v0.4.0 で stateless に回帰。v0.4.2 で stateless 化の副作用として発生した cold-start timeout 問題に対処 (timeout 28s→60s + stateless-safe warmup)、v0.4.3 で過剰になっていたプロンプトを 30-40% 削減。詳細は [CHANGELOG](CHANGELOG.md)。
+> **v0.6.2 released 2026-04-19**. v0.4 で stateless に回帰したが cold-start レイテンシ (毎ターン 30 秒前後の待ち) が運用で問題化したため、v0.5.0 で **session-scoped Haiku を「JSON パース失敗検知 → session renew + silent pass」の事後回復機構付き**で復活。v0.6.0 で **preamble (role + schema + catalog + few-shot) を初回のみ送信** する形 (preamble-once) に変更して `--resume` 経由の resumed 呼び出しが first より遅くなる v0.5.x の逆転現象を解消。v0.6.2 で **親プロセス (Claude Code) の死を 5 秒間隔で検知して daemon を自動 shutdown** する watch を追加し、SessionEnd が発火しない経路 (crash / kill / IDE reload) での孤児 daemon 残存を解消。詳細は [CHANGELOG](CHANGELOG.md)。
 
 **気づく役と実行する役を分離する。** Spotter は Claude Code の横で静かに並走し、Bell (主役の Claude) が**ツールを呼び忘れたとき**に指摘する監査役です。
 
 > Claude には「使えるツールがあるのに、使うべきタイミングで使わない」という構造的な弱点があります。現在時刻を推測で答える、web_search を呼ばずに古い情報で応答する、read_file を使わずにファイルの中身を推測する — 「分からないと自覚できない」から、ツールを取りに行けない。
 
-Spotter は、ツールカタログを完全に把握した別エージェント (Claude Haiku 4.5) をセッション毎にプロセスとして常駐させ、Bell の発話予定と応答を並走監査します。見落としを検出すると、透明化された指摘として Bell に届け、補正応答を促します。Haiku 呼び出しは毎ターン stateless (fresh `--session-id`) で実行されるため、長時間運用しても会話履歴による persona drift を構造的に防ぎます。
+Spotter は、ツールカタログを完全に把握した別エージェント (Claude Haiku 4.5) をセッション毎にプロセスとして常駐させ、Bell の発話予定と応答を並走監査します。見落としを検出すると、透明化された指摘として Bell に届け、補正応答を促します。Haiku 呼び出しは session-scoped (`--resume`) で同一セッションに再接続して cold-start を削減し、初回のみ preamble を送って以降は per-turn delta だけ送ることで session 肥大化を防ぎます。role collapse (persona drift で JSON 契約破棄) は構造的に予防せず、検知した瞬間に session を切り直して fresh state から再開する事後回復機構で長時間運用に耐えます。
 
 ## インストール
 
@@ -75,7 +75,7 @@ spotter uninstall        # hook 登録を解除 (~/.spotter は残す)
 ## 既知の制約
 
 - Stop hook は Bell の最初の応答が**出力された後**に発火するため、Spotter が Stop で差し戻した場合、ユーザーは「最初の応答 + 補正応答」の 2 連続を見ます (Claude Code の hook 仕様による制約)。UserPromptSubmit 段階での先回り検出を精度の軸にしています
-- JSON スキーマ違反・Haiku timeout はリトライせず即 throw します (§14.1 silent fallback 禁止の帰結)。UserPromptSubmit がブロックされユーザー入力が Bell に届かない症状として顕在化します。cold-start 対策として v0.4.2 で timeout 60s + warmup を導入しましたが、fail-open 化 (timeout を pass 扱い) は §0 改訂とセットで今後検討
+- **JSON スキーマ違反は v0.5.0 以降「想定済み異常」として silent pass + session renew で回復**します (role collapse 検知パス、daemon ログに `role_collapse_reset` を残す)。一方 **Haiku timeout は引き続き throw** され、UserPromptSubmit がブロックされてユーザー入力が Bell に届かない症状として顕在化します (timeout は v0.5.0 で 30s に短縮)。timeout の fail-open 化 (pass 扱い) は §0 改訂とセットで今後検討
 
 ## ライセンス
 

package/package.json

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

package/src/cli/daemon-cmd.mjs

@@ -6,18 +6,22 @@ import { join } from 'node:path';
 import { open } from 'node:fs/promises';
 
 function parseArgs(argv) {
-  const out = { sessionId: null };
+  const out = { sessionId: null, parentPid: null };
   for (let i = 0; i < argv.length; i += 1) {
     if (argv[i] === '--session-id') {
       out.sessionId = argv[i + 1];
       i += 1;
+    } else if (argv[i] === '--parent-pid') {
+      const n = parseInt(argv[i + 1], 10);
+      if (Number.isInteger(n) && n > 0) out.parentPid = n;
+      i += 1;
     }
   }
   return out;
 }
 
 export async function runDaemonStart({ argv }) {
-  const { sessionId } = parseArgs(argv);
+  const { sessionId, parentPid } = parseArgs(argv);
   if (!sessionId) {
     process.stderr.write('spotter daemon start: --session-id is required\n');
     process.exit(2);
@@ -37,7 +41,10 @@ export async function runDaemonStart({ argv }) {
     // v0.5.0: no warmup. Session-scoped Haiku (--resume on follow-ups) pays cold-start
     // only on the first real call; warmup added complexity for marginal benefit and is
     // removed along with the stateless regime that required it.
-    running = await startDaemon({ sessionId, logFn: log });
+    // v0.6.2: parentPid (Claude Code PID, captured by SessionStart hook as process.ppid)
+    // is threaded in so the daemon self-terminates when the parent dies without
+    // SessionEnd (crash / kill / IDE reload).
+    running = await startDaemon({ sessionId, parentPid, logFn: log });
   } catch (err) {
     if (err instanceof DaemonAlreadyRunningError) {
       // v0.2 PID-preexist layer: a sibling daemon already serves this session.

package/src/daemon/daemon.mjs

@@ -47,6 +47,11 @@ const DEFAULT_HAIKU_CALL_WINDOW_MS = 10_000;
 // being excessive, and a role-collapse recovery cycle (reset → next call is effectively
 // a cold start again) stays within budget.
 const DEFAULT_HAIKU_TIMEOUT_MS = 30_000;
+// v0.6.2: parent-process watch interval. SessionStart hook passes the Claude Code PID;
+// the daemon polls it so it can self-terminate when Claude Code dies without firing
+// SessionEnd (crash, kill -9, IDE reload). 5s is a balance between responsiveness and
+// idle CPU cost — well below the cost of an orphan daemon staying up indefinitely.
+const DEFAULT_PARENT_WATCH_INTERVAL_MS = 5_000;
 
 export class DaemonAlreadyRunningError extends Error {
   constructor(sessionId, pid) {
@@ -63,10 +68,15 @@ export async function startDaemon({
   haikuCaller,
   logFn = () => {},
   haikuCallWindowMs = DEFAULT_HAIKU_CALL_WINDOW_MS,
+  parentPid = null,
+  parentWatchIntervalMs = DEFAULT_PARENT_WATCH_INTERVAL_MS,
 } = {}) {
   if (!sessionId) {
     throw new TypeError('sessionId is required');
   }
+  if (parentPid !== null && (!Number.isInteger(parentPid) || parentPid <= 0)) {
+    throw new TypeError('parentPid must be a positive integer or null');
+  }
 
   await ensureRuntimeDir();
 
@@ -158,7 +168,7 @@ export async function startDaemon({
       case 'turn_end':
         return handleTurnEnd(envelope.payload ?? {});
       case 'shutdown':
-        setImmediate(() => shutdown(server, sessionId, logFn));
+        setImmediate(() => stop());
         return { stopping: true };
       default: {
         const err = new Error(`unknown event: ${envelope.event}`);
@@ -257,14 +267,53 @@ export async function startDaemon({
   const pidPath = pidFilePath(sessionId);
   await writeFile(pidPath, String(process.pid), 'utf8');
 
+  // v0.6.2: parent-process watch. SessionEnd is a graceful path; if Claude Code dies
+  // without it (crash, kill, IDE reload), nothing else cleans us up. Poll the parent
+  // PID and self-terminate on its disappearance.
+  let parentWatchHandle = null;
+  if (parentPid !== null) {
+    logFn(`watching parent pid=${parentPid} (interval=${parentWatchIntervalMs}ms)`);
+    parentWatchHandle = setInterval(() => {
+      if (!isProcessAlive(parentPid)) {
+        logFn(`parent pid=${parentPid} gone, shutting down`);
+        clearInterval(parentWatchHandle);
+        parentWatchHandle = null;
+        shutdown(server, sessionId, logFn).catch((err) => {
+          logFn(`parent-watch shutdown error: ${err.message}`);
+        });
+      }
+    }, parentWatchIntervalMs);
+    parentWatchHandle.unref();
+  }
+
+  const stop = async () => {
+    if (parentWatchHandle !== null) {
+      clearInterval(parentWatchHandle);
+      parentWatchHandle = null;
+    }
+    return shutdown(server, sessionId, logFn);
+  };
+
   return {
     server,
     path,
     pidPath,
-    stop: () => shutdown(server, sessionId, logFn),
+    stop,
   };
 }
 
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    if (err.code === 'ESRCH') return false;
+    if (err.code === 'EPERM') return true; // exists but owned by another user
+    // Unknown errno — be conservative and assume alive (don't auto-kill on transient).
+    return true;
+  }
+}
+
 async function assertNoLiveDaemon(sessionId) {
   const pidPath = pidFilePath(sessionId);
   let raw;

package/src/hooks/session-start.mjs

@@ -67,12 +67,18 @@ export async function runSessionStart({ argv = process.argv, now = Date.now } =
 
 function spawnDaemon(sessionId, argv) {
   // Invoke `node <spotter-bin> daemon start --session-id ...` detached.
+  // v0.6.2: pass --parent-pid so the daemon can self-terminate when Claude Code dies
+  // without firing SessionEnd. process.ppid here is Claude Code (this hook's parent).
   const spotterBin = resolveSpotterBin(argv);
-  const child = spawn(process.execPath, [spotterBin, 'daemon', 'start', '--session-id', sessionId], {
-    detached: true,
-    stdio: 'ignore',
-    windowsHide: true,
-  });
+  const child = spawn(
+    process.execPath,
+    [spotterBin, 'daemon', 'start', '--session-id', sessionId, '--parent-pid', String(process.ppid)],
+    {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+    }
+  );
   child.on('error', (err) => {
     // best effort: the polling below will fail if the spawn actually didn't work
     process.stderr.write(`spotter-hook: daemon spawn error: ${err.message}\n`);

package/src/version.mjs

@@ -1 +1 @@
-export const version = '0.5.2';
+export const version = '0.6.2';