claude-spotter 0.11.1 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 0.13.0
+
+**Stop 判定軸を「要請充足チェック」から「ツール適用機会の監査」に転換**。v0.12.x 以前の `stage=turn_end` は `<user_input>` + `<used_tools>` + `<final_response>` を Haiku に渡し、「ユーザー要請されたツールが使われたか」を判定していた。この軸では Bell が Stop 到達後にすべき動作 — 事実断定の裏付け / 新知見の記録 / 既知情報の照会 — を拾えない。実セッションで Haiku が応答「判明: A モジュールは B に依存」に対し `caveat_record` を推奨する、といった本来期待される指摘が構造的に出ない状態だった (ユーザーが [この議論](https://github.com/kitepon-rgb/Spotter) で指摘)。
+
+### 新軸: ツール適用機会の監査
+
+- **入力**: `<used_tools>` + `<final_response>` のみ (user_input は削除)
+- **問い**: 「この応答で、カタログ上のツールが役立つ箇所ないか？」
+- **3 カテゴリ**: 検証 (Read/Grep/Bash/WebFetch 等) / 登録 (memory/caveat 等) / 照会 (search/list 等)
+- **非対称**: 指摘ゼロは歓迎、`used_tools` 既含は再指摘しない、迷ったら pass:true
+
+挨拶ターンの早期 pass は daemon 側の `state.lastUserInput === null` 分岐で従来通り機能する (user_input が来ていないターンは turn_end で `reason=no_user_input` で pass)。Stop hook の入力契約 (`final_response` のみを daemon に送信) は v0.4.4 時点で user_input を送っていないので hook 側の変更なし。
+
+### 変更点
+
+- **編集 [src/daemon/haiku-caller.mjs](src/daemon/haiku-caller.mjs)**: `SHARED_HEADER` の stage=turn_end 説明を書き換え、few-shot を 4 件 (検証/登録/照会/pass) に拡張。`buildFinalStagePrompt` から `userInput` 引数を削除、`<user_input>` タグも削除
+- **編集 [src/daemon/daemon.mjs](src/daemon/daemon.mjs)**: `handleTurnEnd` の `buildFinalStagePrompt` 呼び出しから `userInput` 引数削除、`savedUserInput` 変数削除。`state.lastUserInput` は `no_user_input` pass 分岐用に保持継続 (コメントで意図明記)
+- **編集 [test/haiku-caller.test.mjs](test/haiku-caller.test.mjs)**: `buildFinalStagePrompt` の 3 テストから `userInput:` 引数削除、`<user_input>` タグ包含アサートを非包含アサートに反転
+- **編集 [test/daemon.test.mjs](test/daemon.test.mjs)**: turn_end の per-turn prompt に `<user_input>` タグも user 発言原文も含まれないことを確認するテストを 1 件追加
+- **編集 [CLAUDE.md](CLAUDE.md)**: Product Concept に「判定軸 (v0.13.0 で 2 軸化)」セクションを追加、user_input=要請充足チェック / turn_end=ツール適用機会の監査 を明記
+
+### 非互換
+
+- **判定挙動の意味論変更**: v0.12.x までの「user_input 要請に対応するツール」しか指摘しなかった Stop hook が、v0.13.0 からは user_input 非依存で「応答に対する適用機会」を指摘する。false positive / false negative の方向性も変わるため、過検出率 / pass 率の再計測が必要 ([docs/open-issues.md](docs/open-issues.md) P0 に観測タスクを追加)
+- **API 変更**: `buildFinalStagePrompt({ userInput, usedTools, finalResponse })` → `buildFinalStagePrompt({ usedTools, finalResponse })`。外部から直接呼ばれる API ではない (daemon 内部) ため影響範囲は Spotter 本体のみ
+
+## 0.12.0
+
+**親 PID watch を heartbeat 方式に置換 + UserPromptSubmit auto-resurrect**。v0.6.2 で導入した `--parent-pid` watch (Claude Code 本体 PID を `process.kill(pid, 0)` で 5 秒間隔 ping) が VSCode native extension 環境で誤爆する問題を解消。`process.ppid` は extension host から spawn される短命ラッパーを指していて、5 秒で ESRCH → daemon 自死していた (`~/.spotter/logs/ppid-probe.log` の env dump で実測: hook の ppid が毎回 (55692, 46020 等) 変わるのに対し `VSCODE_PID=39964` は固定、CLAUDE_* 系には PID 系 env なし)。
+
+### 設計
+
+- **heartbeat 方式 (b 案)**: daemon が envelope を受信するたびに `setTimeout(selfShutdown, 30min)` を `clearTimeout` + 再 set。ポーリングではなく event-driven で CPU 負荷ゼロ、検出は精密。30 分を超える Claude Code 沈黙は通常の使用では発生しない閾値
+- **OS / 環境依存ゼロ**: VSCODE_PID / CLAUDE_*_PID 等の探索が不要、CLI / native extension / 将来の他クライアント全てで同一挙動
+- **auto-resurrect**: UserPromptSubmit hook が `E_UNREACHABLE` (socket 不在) を検出したら spawn + readiness 待ち + retry。daemon が 30 分 timeout で死んでも crash していても、次のユーザー入力で自動復活する。「daemon が死んでたら pass」(§0 silent fallback 違反) ではなく「daemon が死んでたら起こす」で対処
+- **PreToolUse / Stop は復活させない**: turn の途中で daemon が居なかった場合、used_tools 欠落・preamble 未送信の歪んだ状態で監査再開すると誤検出が増える。次の UserPromptSubmit (新 turn の起点) で復活する設計
+
+### 変更点
+
+- **編集 [src/daemon/daemon.mjs](src/daemon/daemon.mjs)**: parent-pid watch (`setInterval` + `process.kill(pid, 0)`) を削除、`heartbeatTimeoutMs` パラメータ + `resetHeartbeat()` (clearTimeout + setTimeout の per-envelope re-arm) に置換。`isProcessAlive` も削除 (status.mjs に独立コピー有り)
+- **編集 [src/cli/daemon-cmd.mjs](src/cli/daemon-cmd.mjs)**: `--parent-pid` パース削除、`startDaemon` 呼び出しから `parentPid` 削除
+- **新規 [src/hooks/spawn-daemon.mjs](src/hooks/spawn-daemon.mjs)**: spawn detached + readiness poll を session-start / user-prompt の両方から使えるように共通化
+- **編集 [src/hooks/session-start.mjs](src/hooks/session-start.mjs)**: spawn ロジックを spawn-daemon.mjs に委譲、`--parent-pid` 渡し削除
+- **編集 [src/hooks/user-prompt.mjs](src/hooks/user-prompt.mjs)**: `sendRequest` が `E_UNREACHABLE` で失敗したら `spawnDaemonAndWaitReady` を呼んで retry (1 回のみ)
+- **削除 [src/hooks/ppid-probe.mjs]**: env dump 用の調査 hook、役目終了
+- **編集 [.claude/settings.json](.claude/settings.json)**: probe hook 登録撤去
+- **編集 [test/daemon.test.mjs](test/daemon.test.mjs)**: parent-watch test 2 件を削除、heartbeat timeout / heartbeat reset / heartbeatTimeoutMs validation の 3 件を追加
+
+### 非互換
+
+- `startDaemon({parentPid, parentWatchIntervalMs})` → `startDaemon({heartbeatTimeoutMs})`: API 変更。CLI の `--parent-pid` 引数も廃止 (受け取らなくなる)。Spotter は hook + daemon を同一 npm package で配布するため `npm install -g claude-spotter@latest` で一括更新すれば混在は起きない
+
 ## 0.11.1
 
 **hotfix: `src/version.mjs` を `package.json` から読み取る**。0.11.0 は package.json を 0.11.0 に bump したが `src/version.mjs` のハードコード文字列 (`'0.10.0'`) を上げ忘れていたため、`spotter --version` が `0.10.0` のまま表示される不整合があった。同じミスを防ぐため ESM JSON import (`import pkg from '../package.json' with { type: 'json' }`) で package.json から動的に引くよう変更。以降は package.json の version を bump するだけで CLI 出力も追従する。

package/package.json

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

package/src/cli/daemon-cmd.mjs

@@ -6,15 +6,11 @@ import { join } from 'node:path';
 import { open } from 'node:fs/promises';
 
 function parseArgs(argv) {
-  const out = { sessionId: null, parentPid: null, projectRoot: null };
+  const out = { sessionId: null, projectRoot: 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;
     } else if (argv[i] === '--project-root') {
       out.projectRoot = argv[i + 1];
       i += 1;
@@ -24,7 +20,7 @@ function parseArgs(argv) {
 }
 
 export async function runDaemonStart({ argv }) {
-  const { sessionId, parentPid, projectRoot } = parseArgs(argv);
+  const { sessionId, projectRoot } = parseArgs(argv);
   if (!sessionId) {
     process.stderr.write('spotter daemon start: --session-id is required\n');
     process.exit(2);
@@ -48,11 +44,9 @@ 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.
-    // 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).
     // v0.7.0: projectRoot drives tool-db loading (replaces the old tools.yaml catalog).
-    running = await startDaemon({ sessionId, projectRoot, parentPid, logFn: log });
+    // v0.12.0: orphan-cleanup is heartbeat-based inside startDaemon (no parent-PID arg).
+    running = await startDaemon({ sessionId, projectRoot, 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

@@ -16,6 +16,12 @@
 // §5.7: event dispatch follows the envelope contract.
 // §14:  unexpected errors are thrown; hooks convert them to exit codes.
 //
+// v0.12.0: orphan-cleanup is now heartbeat-based instead of parent-PID watch. Every
+// envelope (including readiness) resets a setTimeout; if no hook event arrives within
+// HEARTBEAT_TIMEOUT_MS (30 min), the daemon self-shuts. Replaces v0.6.2's --parent-pid
+// scheme, which mis-fired in VSCode native-extension environments where process.ppid
+// pointed at a short-lived wrapper. UserPromptSubmit hook auto-resurrects a dead daemon.
+//
 // v0.2 defence layers against daemon proliferation (see plan §18) — still active:
 //   - SPOTTER_PARENT_PID env var (set by haiku-caller when spawning claude -p; hooks skip on presence)
 //   - agent_id gate (subagent hooks exit 0 before reaching the daemon)
@@ -45,11 +51,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;
+// v0.12.0: heartbeat-based orphan cleanup. Every envelope resets a setTimeout; if no
+// hook event arrives within this window, the daemon self-shuts. 30 min is the longest
+// silence we expect from a live Claude Code session. UserPromptSubmit auto-resurrects
+// a dead daemon, so over-aggressive timeout would just cause a visible re-spawn.
+const DEFAULT_HEARTBEAT_TIMEOUT_MS = 30 * 60 * 1000;
 
 export class DaemonAlreadyRunningError extends Error {
   constructor(sessionId, pid) {
@@ -67,14 +73,13 @@ export async function startDaemon({
   haikuCaller,
   logFn = () => {},
   haikuCallWindowMs = DEFAULT_HAIKU_CALL_WINDOW_MS,
-  parentPid = null,
-  parentWatchIntervalMs = DEFAULT_PARENT_WATCH_INTERVAL_MS,
+  heartbeatTimeoutMs = DEFAULT_HEARTBEAT_TIMEOUT_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');
+  if (!Number.isFinite(heartbeatTimeoutMs) || heartbeatTimeoutMs <= 0) {
+    throw new TypeError('heartbeatTimeoutMs must be a positive number');
   }
 
   await ensureRuntimeDir();
@@ -141,7 +146,24 @@ export async function startDaemon({
     }
   };
 
+  // v0.12.0: heartbeat. Reset on every envelope; if no event arrives within
+  // heartbeatTimeoutMs the daemon self-shuts. Replaces v0.6.2 parent-PID watch.
+  // The timer itself is created after server.listen() succeeds (see below).
+  let heartbeatHandle = null;
+  const resetHeartbeat = () => {
+    if (heartbeatHandle !== null) clearTimeout(heartbeatHandle);
+    heartbeatHandle = setTimeout(() => {
+      heartbeatHandle = null;
+      logFn(`heartbeat timeout (${heartbeatTimeoutMs}ms), shutting down`);
+      shutdown(server, sessionId, logFn).catch((err) => {
+        logFn(`heartbeat shutdown error: ${err.message}`);
+      });
+    }, heartbeatTimeoutMs);
+    heartbeatHandle.unref();
+  };
+
   const handler = async (envelope) => {
+    resetHeartbeat();
     if (!envelope || typeof envelope !== 'object') {
       const err = new Error('invalid envelope');
       err.code = 'E_INTERNAL';
@@ -236,12 +258,13 @@ export async function startDaemon({
       return { pass: true, missing_tools: [], reason: 'no_user_input' };
     }
 
-    const savedUserInput = state.lastUserInput;
+    // v0.13.0: state.lastUserInput は turn_end の Haiku 判定には渡さない (新軸は
+    // final_response + used_tools のみで判定)。ただし「挨拶ターン (user_input が来て
+    // いない) は早期 pass」の分岐は上で使うので保存は引き続き必要。
     const savedUsedTools = state.usedTools.slice();
     const { parsed, meta } = await runHaikuJudgment(
       'turn_end',
       buildFinalStagePrompt({
-        userInput: savedUserInput,
         usedTools: savedUsedTools,
         finalResponse,
       })
@@ -276,29 +299,15 @@ 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();
-  }
+  // Start the heartbeat. The first hook event (typically SessionStart's readiness
+  // ping moments later) will reset it; if nothing arrives in heartbeatTimeoutMs we self-shut.
+  logFn(`heartbeat armed (timeout=${heartbeatTimeoutMs}ms)`);
+  resetHeartbeat();
 
   const stop = async () => {
-    if (parentWatchHandle !== null) {
-      clearInterval(parentWatchHandle);
-      parentWatchHandle = null;
+    if (heartbeatHandle !== null) {
+      clearTimeout(heartbeatHandle);
+      heartbeatHandle = null;
     }
     return shutdown(server, sessionId, logFn);
   };
@@ -311,18 +320,6 @@ export async function startDaemon({
   };
 }
 
-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/daemon/haiku-caller.mjs

@@ -38,6 +38,11 @@ export async function ensureWorkdir() {
 
 // Shared header covers BOTH stages — the preamble documents stage=user_input and
 // stage=turn_end so per-turn prompts only need to announce which stage they are.
+//
+// v0.13.0: stage=turn_end の判定軸を「要請充足チェック」から「ツール適用機会の監査」に転換。
+// 旧軸は <user_input> に対し used_tools が足りているかをチェックしていた。新軸は
+// <final_response> の内容 (事実断定 / 記録すべき新情報 / 既知情報の参照) に対し、カタログ
+// 上のツール (検証 / 登録 / 照会) を差し込める余地を探す。非対称 (指摘ゼロ歓迎) 設計。
 const SHARED_HEADER = [
   'あなたは Spotter。Bell (主役の Claude) が呼び忘れるツールを検出する監査役です。',
   'ユーザーへの会話文は生成せず、必ず下記 JSON のみを返します。',
@@ -49,13 +54,32 @@ const SHARED_HEADER = [
   '',
   '## 判定対象',
   '各ターン、以下いずれかの stage で判定リクエストを受けます:',
-  '- stage=user_input: <user_input> のみ届く。when_to_use に明確に該当するツールを列挙',
-  '- stage=turn_end: <user_input> + <used_tools> + <final_response> が届く。既使用を除き Bell が呼び忘れたツールを列挙',
-  'どちらも推測禁止。該当なしなら pass:true。',
+  '',
+  '### stage=user_input',
+  '<user_input> のみ届く。when_to_use に明確に該当するツールを列挙。',
+  '推測禁止。該当なしなら pass:true。',
+  '',
+  '### stage=turn_end  (ツール適用機会の監査)',
+  '<final_response> + <used_tools> が届く。',
+  'Bell の応答に含まれる動作 — 事実の断定 / 記録すべき新情報 / 既知情報の参照 —',
+  'それぞれについて、カタログに役立つツールがあれば提示する。',
+  '検証 (Read/Grep/Bash/WebFetch 等) / 登録 (memory/caveat 等) / 照会 (search/list 等) のいずれも対象。',
+  '<used_tools> に既に含まれるツールは再指摘しない。',
+  '指摘ゼロは歓迎。迷ったら pass:true。',
   '',
   '## 例',
-  '- stage=user_input "今何時?" → {"pass":false,"missing_tools":[{"name":"current_time","reason":"時刻の直接質問"}]}',
-  '- stage=user_input "ありがとう" → {"pass":true,"missing_tools":[]}',
+  '- stage=user_input "今何時?"',
+  '  → {"pass":false,"missing_tools":[{"name":"current_time","reason":"時刻の直接質問"}]}',
+  '- stage=user_input "ありがとう"',
+  '  → {"pass":true,"missing_tools":[]}',
+  '- stage=turn_end 応答「この関数は配列長を返します」(used:なし) ← 検証',
+  '  → {"pass":false,"missing_tools":[{"name":"Read","reason":"関数実装の断定は実ファイル読取で裏付けるべき"}]}',
+  '- stage=turn_end 応答「判明: A モジュールは B に依存」(used:Grep) ← 登録',
+  '  → {"pass":false,"missing_tools":[{"name":"mcp__caveat__caveat_record","reason":"新発見の依存関係は記録して次回参照可能にすべき"}]}',
+  '- stage=turn_end 応答「この話題は前にも議論したはず」(used:なし) ← 照会',
+  '  → {"pass":false,"missing_tools":[{"name":"mcp__caveat__caveat_search","reason":"過去の議論参照は検索して裏付けるべき"}]}',
+  '- stage=turn_end 応答「作業完了しました」(used:Read,Edit,Bash) ← pass',
+  '  → {"pass":true,"missing_tools":[]}',
 ].join('\n');
 
 // Preamble — sent exactly once per Haiku session (first call). Contains the role,
@@ -92,13 +116,13 @@ export function buildFirstStagePrompt({ userInput }) {
 }
 
 // Per-turn prompt — Stop hook stage.
-export function buildFinalStagePrompt({ userInput, usedTools, finalResponse }) {
+// v0.13.0: user_input は渡さない。判定軸が「ユーザー要請の充足」から「final_response に
+// ツール適用機会があるか」に変わったため。挨拶ターンの早期 pass は daemon 側の
+// state.lastUserInput === null 分岐 (handleTurnEnd) で処理する。
+export function buildFinalStagePrompt({ usedTools, finalResponse }) {
   const usedList = usedTools.length > 0 ? usedTools.map((t) => `- ${t}`).join('\n') : '(なし)';
   return [
     'stage=turn_end',
-    '<user_input>',
-    userInput,
-    '</user_input>',
     '<used_tools>',
     usedList,
     '</used_tools>',

package/src/hooks/session-start.mjs

@@ -11,31 +11,21 @@
 // v0.3 gate:
 //   - isOutsideSpotterProject: cwd has no .spotter/marker.json above it → exit 0
 //     (Throughline workdir etc. — `claude -p` from tools outside any installed project)
+//
+// v0.12.0: spawn + readiness-poll moved to spawn-daemon.mjs (shared with auto-resurrect
+// in user-prompt.mjs). The --parent-pid scheme from v0.6.2 is gone; orphan cleanup is
+// now heartbeat-based inside the daemon.
 
-import { spawn } from 'node:child_process';
-import { setTimeout as delay } from 'node:timers/promises';
-import { fileURLToPath } from 'node:url';
-import { dirname, resolve } from 'node:path';
 import { readStdinJson, requireString, die, isChildCall, isSubagentCall, isOutsideSpotterProject, findSpotterMarker } from './lib.mjs';
-import { sendRequest, TransportError } from '../daemon/transport.mjs';
-
-const READINESS_TIMEOUT_MS = 3_000;
-const POLL_INTERVAL_MS = 100;
+import { spawnDaemonAndWaitReady } from './spawn-daemon.mjs';
 
-export async function runSessionStart({ argv = process.argv, now = Date.now } = {}) {
-  // Gate 1 (pre-stdin): Spotter's own claude -p subprocess — exit without reading stdin.
+export async function runSessionStart({ now = Date.now } = {}) {
   if (isChildCall()) return;
 
   const input = await readStdinJson();
 
-  // Gate 2: Task subagent — skip audit.
   if (isSubagentCall(input)) return;
-
-  // Gate 3: non-startup sources (resume/compact/clear) don't spawn a new daemon.
   if (input.source !== 'startup') return;
-
-  // Gate 4 (v0.3): cwd is not inside any project that has been `spotter install`-ed.
-  // Other tools (Throughline etc.) launching `claude -p` in unrelated workdirs land here.
   if (isOutsideSpotterProject(input)) return;
 
   const sessionId = requireString(input, 'session_id');
@@ -44,66 +34,9 @@ export async function runSessionStart({ argv = process.argv, now = Date.now } =
     die(`SessionStart: failed to locate project root from cwd=${input.cwd}`, 2);
   }
 
-  spawnDaemon(sessionId, projectRoot, argv);
-
-  const deadline = now() + READINESS_TIMEOUT_MS;
-  while (now() < deadline) {
-    try {
-      const resp = await sendRequest({
-        sessionId,
-        event: 'readiness',
-        timeoutMs: 500,
-      });
-      if (resp.ok === true && resp.result && resp.result.ready === true) {
-        return; // success — exit 0 implicitly
-      }
-    } catch (err) {
-      if (!(err instanceof TransportError) || err.code !== 'E_UNREACHABLE') {
-        // E_TIMEOUT or internal errors while daemon is booting — keep polling.
-        // E_UNREACHABLE means the socket file/pipe doesn't exist yet — also retryable.
-      }
-    }
-    await delay(POLL_INTERVAL_MS);
-  }
-
-  die(`daemon did not reach readiness within ${READINESS_TIMEOUT_MS}ms for session ${sessionId}`, 2);
-}
-
-function spawnDaemon(sessionId, projectRoot, 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).
-  // v0.7.0: pass --project-root for tool-db loading.
-  const spotterBin = resolveSpotterBin(argv);
-  const child = spawn(
-    process.execPath,
-    [
-      spotterBin, 'daemon', 'start',
-      '--session-id', sessionId,
-      '--parent-pid', String(process.ppid),
-      '--project-root', projectRoot,
-    ],
-    {
-      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`);
-  });
-  child.unref();
-}
-
-function resolveSpotterBin(argv) {
-  // argv[1] is the path to the currently running script (bin/spotter.mjs when invoked via CLI,
-  // or src/hooks/session-start.mjs in tests). Walk up to the package root.
-  const here = dirname(fileURLToPath(import.meta.url));
-  return resolve(here, '..', '..', 'bin', 'spotter.mjs');
+  await spawnDaemonAndWaitReady({ sessionId, projectRoot, now });
 }
 
-// Direct-execution entry — used when called as `node session-start.mjs`.
 if (import.meta.url === `file://${process.argv[1]?.replace(/\\/g, '/')}`) {
   runSessionStart().catch((err) => die(err.message, err.exitCode ?? 2));
 }

package/src/hooks/spawn-daemon.mjs

@@ -0,0 +1,72 @@
+// Shared daemon-spawn + readiness-poll plumbing.
+//
+// Used by:
+//   - session-start.mjs (initial daemon for a fresh session)
+//   - user-prompt.mjs   (auto-resurrect when a heartbeat-killed or crashed daemon
+//                        is detected at the start of a new turn — v0.12.0)
+//
+// The hook caller is responsible for the v0.2 gates (isChildCall / isSubagentCall /
+// isOutsideSpotterProject) and for resolving sessionId + projectRoot before invoking
+// this. We keep this module narrowly focused on "spawn detached + poll until ready".
+
+import { spawn } from 'node:child_process';
+import { setTimeout as delay } from 'node:timers/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { sendRequest, TransportError } from '../daemon/transport.mjs';
+
+const READINESS_TIMEOUT_MS = 3_000;
+const POLL_INTERVAL_MS = 100;
+
+export async function spawnDaemonAndWaitReady({ sessionId, projectRoot, now = Date.now }) {
+  spawnDaemon(sessionId, projectRoot);
+
+  const deadline = now() + READINESS_TIMEOUT_MS;
+  while (now() < deadline) {
+    try {
+      const resp = await sendRequest({
+        sessionId,
+        event: 'readiness',
+        timeoutMs: 500,
+      });
+      if (resp.ok === true && resp.result && resp.result.ready === true) {
+        return;
+      }
+    } catch (err) {
+      if (!(err instanceof TransportError) || err.code !== 'E_UNREACHABLE') {
+        // E_TIMEOUT or internal errors while daemon is booting — keep polling.
+      }
+    }
+    await delay(POLL_INTERVAL_MS);
+  }
+
+  const err = new Error(`daemon did not reach readiness within ${READINESS_TIMEOUT_MS}ms for session ${sessionId}`);
+  err.exitCode = 2;
+  throw err;
+}
+
+function spawnDaemon(sessionId, projectRoot) {
+  const spotterBin = resolveSpotterBin();
+  const child = spawn(
+    process.execPath,
+    [
+      spotterBin, 'daemon', 'start',
+      '--session-id', sessionId,
+      '--project-root', projectRoot,
+    ],
+    {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+    }
+  );
+  child.on('error', (err) => {
+    process.stderr.write(`spotter-hook: daemon spawn error: ${err.message}\n`);
+  });
+  child.unref();
+}
+
+function resolveSpotterBin() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return resolve(here, '..', '..', 'bin', 'spotter.mjs');
+}

package/src/hooks/user-prompt.mjs

@@ -1,5 +1,11 @@
 // UserPromptSubmit hook — send user_input to daemon, inject additionalContext (§12.2 transparent).
 // v0.2 gates: see src/hooks/session-start.mjs comment.
+//
+// v0.12.0: auto-resurrect. If sendRequest fails with E_UNREACHABLE (daemon was
+// heartbeat-killed for 30 min idle, crashed, or was never spawned because SessionStart
+// fired in a context we skipped), we spawn a fresh daemon and retry once. This is the
+// natural recovery point — the start of a new turn — so the user's prompt is still
+// audited even after long pauses or daemon failures.
 
 import {
   readStdinJson,
@@ -10,8 +16,10 @@ import {
   isChildCall,
   isSubagentCall,
   isOutsideSpotterProject,
+  findSpotterMarker,
 } from './lib.mjs';
-import { sendRequest } from '../daemon/transport.mjs';
+import { sendRequest, TransportError } from '../daemon/transport.mjs';
+import { spawnDaemonAndWaitReady } from './spawn-daemon.mjs';
 
 const TIMEOUT_MS = 30_000;
 const SHORT_PROMPT_MAX_CHARS = 10;
@@ -25,22 +33,43 @@ export async function runUserPrompt() {
   const sessionId = requireString(input, 'session_id');
   const prompt = requireString(input, 'prompt');
 
-  // Short prompts (<=10 codepoints after trim) are almost never tool-required
-  // (greetings, acknowledgements, short questions). Skip Haiku entirely —
-  // daemon keeps lastUserInput=null, so the next turn_end passes with reason=no_user_input.
   if ([...prompt.trim()].length <= SHORT_PROMPT_MAX_CHARS) return;
 
-  let response;
-  try {
-    response = await sendRequest({
+  const sendUserInput = () =>
+    sendRequest({
       sessionId,
       event: 'user_input',
       payload: { user_input: prompt },
       timeoutMs: TIMEOUT_MS,
     });
+
+  let response;
+  try {
+    response = await sendUserInput();
   } catch (err) {
-    die(`user-prompt transport failure: ${err.code ?? '?'}: ${err.message}`, exitCodeFor(err));
-    return;
+    if (err instanceof TransportError && err.code === 'E_UNREACHABLE') {
+      // v0.12.0: daemon is gone (heartbeat shutdown, crash, missing). Resurrect and retry.
+      const projectRoot = findSpotterMarker(input.cwd);
+      if (!projectRoot) {
+        die(`user-prompt: cannot resurrect daemon — no .spotter/marker.json above cwd=${input.cwd}`, 2);
+        return;
+      }
+      try {
+        await spawnDaemonAndWaitReady({ sessionId, projectRoot });
+      } catch (spawnErr) {
+        die(`user-prompt: daemon resurrect failed: ${spawnErr.message}`, spawnErr.exitCode ?? 2);
+        return;
+      }
+      try {
+        response = await sendUserInput();
+      } catch (retryErr) {
+        die(`user-prompt transport failure after resurrect: ${retryErr.code ?? '?'}: ${retryErr.message}`, exitCodeFor(retryErr));
+        return;
+      }
+    } else {
+      die(`user-prompt transport failure: ${err.code ?? '?'}: ${err.message}`, exitCodeFor(err));
+      return;
+    }
   }
 
   if (response.ok !== true) {
@@ -50,7 +79,7 @@ export async function runUserPrompt() {
 
   const result = response.result;
   if (result.pass === true) {
-    return; // no additionalContext to inject
+    return;
   }
 
   const additionalContext = formatTransparentContext(result.missing_tools);