claude-spotter 0.4.4 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## 0.5.0
+
+**Session-scoped Haiku 復活 + role-collapse 回復機構 (UX 改善)**。
+
+### 事の発端
+
+v0.4.4 の実運用観測で、**Bell 応答後に Claude の動きが落ち着くまで 30 秒前後かかる**ケースが常態化していることを確認。`claude -p` が毎ターン cold-start を踏んでいるのが支配的要因で、v0.4.x stateless 化 (毎ターン fresh `--session-id`) が原因。ユーザーと「速度と独立性のトレードオフ」を再議論した結果、**v0.4.0 の判断を反転**し session-scoped に戻すことで決定。
+
+### 設計 — trade-off をどう捌いたか
+
+v0.4.0 で session-scoped を捨てた理由は **Haiku role collapse** (Bell 会話履歴を聞き続けた Haiku が persona drift して JSON 契約を破棄する既発バグ)。今回はこれを:
+
+- **構造的予防 (stateless)** ではなく
+- **事後回復 (JSON パース失敗検知 → session renew + silent pass)** で処理する
+
+という方針に切り替えた。role collapse は稀事象であり、構造的予防のために毎ターン cold-start を払うコストに見合わない。JSON スキーマ違反を検知した時点で、その Haiku 出力は既にゴミ (block 判定に使えば誤検出で block される) なので、**silent-pass + 次ターンから新 session** が最も UX 影響の小さい正しい手当て。これは CLAUDE.md §0 の「想定済み異常 = 記録 + 正常リターン」に合致する分類変更であり、silent fallback の新規導入ではない。
+
+差し戻しループ vs 沈黙 vs 遅延の三択で検討したオプション:
+- A (原則通り throw): UserPromptSubmit exit 2 で Bell 沈黙 → UX 最悪 (v0.4.0 で問題視された症状そのもの)
+- B (reset 後 1 回リトライ): 異常時のみ cold-start 2 回分 = 30-60 秒待ち
+- **C (silent pass + reset)**: 今ターンだけ監査スキップ、次ターンから正常復帰 ← 採用
+
+### 変更点
+
+- **[src/daemon/haiku-caller.mjs](src/daemon/haiku-caller.mjs)**:
+  - `createHaikuCaller` を closure で `currentSessionId` と `isFirstCall` を保持する形に再構成。第 1 回は `--session-id <uuid>` のみで spawn、以降は `--session-id <uuid> --resume <uuid>` で同一セッションに reattach。
+  - 返り値の callable に `.reset()` と `.sessionId` を付与 (既存テストの `typeof caller === 'function'` 互換のため function に property を足す形)。
+  - `buildSpawnArgs` を export (session-id/resume のテスト用)。
+  - `buildWarmupPrompt` を削除 (warmup は stateless 対策だった)。
+- **[src/daemon/daemon.mjs](src/daemon/daemon.mjs)**:
+  - `runHaikuJudgment` ヘルパー新設。`parseHaikuResponse` が `E_HAIKU_SCHEMA` を throw したら `callHaiku.reset()` を呼び、`{pass: true, missing_tools: [], reason: 'role_collapse_reset'}` を返す。
+  - `warmup` オプション削除。`haikuCallWindowMs` オプション追加 (テスト時は 0 で 10 秒ウィンドウを無効化)。
+  - `DEFAULT_HAIKU_TIMEOUT_MS` 60s → 30s (session-scoped なら 2 回目以降は cold-start を払わないため短縮可能)。
+- **[src/cli/daemon-cmd.mjs](src/cli/daemon-cmd.mjs)**: `startDaemon` 呼び出しから `warmup: true` 削除。
+- テスト:
+  - `buildWarmupPrompt` テスト削除 (3 件)。
+  - `createHaikuCaller` の戻り値構造テストを session-scoped + reset 期待に書き換え。
+  - `buildSpawnArgs` テスト 2 件追加 (初回 `--session-id` のみ、2 回目以降 `--resume` 付与)。
+  - daemon の role-collapse recovery テスト 2 件追加 (user_input / turn_end 両方)。
+
+### 効果見込み
+
+- **通常時 UX**: 2 回目以降の Haiku 呼び出しで cold-start が消える → 30s 前後の待ちが推論時間 (数秒) だけに短縮される見込み。
+- **異常時 UX**: role collapse を検知しても、当該ターンのみ監査スキップで Bell の応答はそのまま届く。次ターンから fresh session で監査再開。沈黙ゼロ。
+- **品質**: silent pass が発動したら daemon ログに `role collapse detected, session reset` が残るので、頻度を観測して将来の設計判断材料にする。
+
+### 既知のトレードオフ
+
+- Haiku 側の会話履歴に過去の監査が累積する (これが v0.4.0 で問題視された persona drift の源)。構造的には予防しないが、JSON パース失敗が監視ポイントになっているので、drift が顕在化した瞬間に session が切られる。
+- `claude -p --resume` が実際どの程度 spawn コストを削減するかは実測未検証 (プロセス起動・認証自体は毎回発生する可能性)。効果が薄ければ追加検討。
+
+### v0.4.0 の判断反転について
+
+v0.4.0 以降「再度 session-scoped を提案しないこと」を絶対制約としていたが、**「速度問題が実運用で深刻になった」「role collapse は事後回復で足りる」の 2 点から反転**。この判断は感情的でも場当たり的でもなく、以下の条件変化を踏まえたもの:
+
+1. v0.4.2 で入れた warmup + timeout 60s でも 30 秒前後の待ちが残る実測
+2. v0.4.4 で Stop hook が実際に Bell 応答を読むようになり、監査の正確度が上がった → silent pass のコストが下がった
+3. 役割逸脱検知を JSON パース失敗という客観的シグナルで判定できる設計が見えた
+
 ## 0.4.4
 
 **Stop hook が Bell の最終応答を Haiku に正しく渡すよう修正**。

package/package.json

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

package/src/cli/daemon-cmd.mjs

@@ -34,10 +34,10 @@ export async function runDaemonStart({ argv }) {
 
   let running;
   try {
-    // v0.4.2: warmup=true — fire-and-forget throwaway Haiku call to pre-warm the
-    // Claude CLI / connection pool / prompt cache. Unit tests keep warmup=false
-    // (the default) to avoid spurious haikuCaller calls.
-    running = await startDaemon({ sessionId, logFn: log, warmup: true });
+    // 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 });
   } catch (err) {
     if (err instanceof DaemonAlreadyRunningError) {
       // v0.2 PID-preexist layer: a sibling daemon already serves this session.

package/src/daemon/daemon.mjs

@@ -1,13 +1,14 @@
 // Session-scoped daemon — receives hook events, dispatches to handlers,
 // calls Haiku on user_input / turn_end, keeps used_tools in process memory.
 //
-// v0.4: Haiku calls are STATELESS. Each call is an independent claude -p invocation with
-//       full system prompt + catalog. There is no session-scoped Haiku conversation
-//       (§18.5 is reverted). The daemon still keeps per-turn state (used_tools, lastUserInput)
-//       in its own memory; what was removed is the *Haiku-side* conversation persistence
-//       introduced in v0.2.0. This matches the CLAUDE.md core design
-//       ("Claude 呼び出しは毎回 stateless") and prevents role collapse caused by Haiku
-//       accumulating Bell conversation history across turns.
+// v0.5.0: Haiku calls are session-scoped at the claude -p layer (--session-id + --resume).
+// The daemon holds one Haiku caller for the session's lifetime; the first call establishes
+// the claude -p session and every subsequent call reattaches, avoiding cold-start spawn.
+// Role collapse (Haiku drifting into Bell's persona, previously the reason v0.4.0 reverted
+// to stateless) is handled by a recovery mechanism rather than structural prevention:
+// E_HAIKU_SCHEMA → haikuCaller.reset() + silent-pass the offending turn. This is the §0
+// "想定済み異常 = 記録 + 正常リターン" classification.
+//
 // §5.7: event dispatch follows the envelope contract.
 // §14:  unexpected errors are thrown; hooks convert them to exit codes.
 //
@@ -25,9 +26,9 @@ import { createServer, ensureRuntimeDir, socketPath } from './transport.mjs';
 import {
   buildFirstStagePrompt,
   buildFinalStagePrompt,
-  buildWarmupPrompt,
   parseHaikuResponse,
   createHaikuCaller,
+  HaikuError,
 } from './haiku-caller.mjs';
 import { loadCatalog } from '../catalog/loader.mjs';
 import { homedir } from 'node:os';
@@ -35,12 +36,12 @@ import { join } from 'node:path';
 import { writeFile, unlink } from 'node:fs/promises';
 
 const DEFAULT_CATALOG_PATH = join(homedir(), '.spotter', 'tool-catalog', 'tools.yaml');
-const HAIKU_CALL_WINDOW_MS = 10_000;
-// v0.4.2: bumped 28s → 60s. Stateless calls mean every turn pays cold-start cost
-// (Claude CLI boot, Anthropic round-trip, prompt-cache warm-up). 28s was not enough
-// under observed load — E_HAIKU_TIMEOUT then blocked UserPromptSubmit (exit 2)
-// and silenced Bell. Warmup below also helps but cannot eliminate every cold start.
-const DEFAULT_HAIKU_TIMEOUT_MS = 60_000;
+const DEFAULT_HAIKU_CALL_WINDOW_MS = 10_000;
+// v0.5.0: lowered 60s → 30s. Session-scoped (--resume) means the first call still pays
+// cold-start but subsequent calls skip it. 30s covers the first-call cold path without
+// 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;
 
 export class DaemonAlreadyRunningError extends Error {
   constructor(sessionId, pid) {
@@ -56,7 +57,7 @@ export async function startDaemon({
   catalogPath = DEFAULT_CATALOG_PATH,
   haikuCaller,
   logFn = () => {},
-  warmup = false,
+  haikuCallWindowMs = DEFAULT_HAIKU_CALL_WINDOW_MS,
 } = {}) {
   if (!sessionId) {
     throw new TypeError('sessionId is required');
@@ -82,6 +83,7 @@ export async function startDaemon({
 
   // 10-second recursion-guard bookkeeping. Every Haiku spawn updates this; incoming
   // Haiku-invoking events within the window are treated as recursive noise and passed.
+  // Tests may pass haikuCallWindowMs: 0 to disable this guard.
   let lastHaikuCallAt = 0;
 
   const callHaikuTracked = async (prompt) => {
@@ -89,6 +91,25 @@ export async function startDaemon({
     return callHaiku(prompt);
   };
 
+  // v0.5.0: shared Haiku-invocation + parse helper. On E_HAIKU_SCHEMA (role collapse),
+  // rotates the Haiku session-id and silent-passes the turn (reason: role_collapse_reset).
+  // Other Haiku errors (timeout, spawn failure) still propagate — §14 unexpected → throw.
+  const runHaikuJudgment = async (stage, prompt) => {
+    const raw = await callHaikuTracked(prompt);
+    try {
+      return parseHaikuResponse(raw);
+    } catch (err) {
+      if (err instanceof HaikuError && err.code === 'E_HAIKU_SCHEMA') {
+        logFn(`${stage}: role collapse detected, session reset: ${err.message}`);
+        if (typeof callHaiku.reset === 'function') {
+          callHaiku.reset();
+        }
+        return { pass: true, missing_tools: [], reason: 'role_collapse_reset' };
+      }
+      throw err;
+    }
+  };
+
   const handler = async (envelope) => {
     if (!envelope || typeof envelope !== 'object') {
       const err = new Error('invalid envelope');
@@ -105,7 +126,12 @@ export async function startDaemon({
     // claude -p spawn are likely recursive noise; pass them quietly.
     const needsHaiku = envelope.event === 'user_input' || envelope.event === 'turn_end';
     const sinceLast = Date.now() - lastHaikuCallAt;
-    if (needsHaiku && lastHaikuCallAt > 0 && sinceLast < HAIKU_CALL_WINDOW_MS) {
+    if (
+      needsHaiku &&
+      haikuCallWindowMs > 0 &&
+      lastHaikuCallAt > 0 &&
+      sinceLast < haikuCallWindowMs
+    ) {
       logFn(`${envelope.event} skipped: within ${sinceLast}ms of own haiku call`);
       return { pass: true, missing_tools: [], reason: 'within_haiku_call_window' };
     }
@@ -140,9 +166,12 @@ export async function startDaemon({
     state.lastUserInput = userInput;
     state.usedTools = []; // reset tools for this turn
 
-    const raw = await callHaikuTracked(buildFirstStagePrompt({ catalog, userInput }));
-    const parsed = parseHaikuResponse(raw);
-    logFn(`user_input: pass=${parsed.pass}, missing=${parsed.missing_tools.map((m) => m.name).join(',')}`);
+    const parsed = await runHaikuJudgment('user_input', buildFirstStagePrompt({ catalog, userInput }));
+    logFn(
+      `user_input: pass=${parsed.pass}, missing=${parsed.missing_tools.map((m) => m.name).join(',')}${
+        parsed.reason ? `, reason=${parsed.reason}` : ''
+      }`
+    );
     return parsed;
   }
 
@@ -178,7 +207,8 @@ export async function startDaemon({
 
     const savedUserInput = state.lastUserInput;
     const savedUsedTools = state.usedTools.slice();
-    const raw = await callHaikuTracked(
+    const parsed = await runHaikuJudgment(
+      'turn_end',
       buildFinalStagePrompt({
         catalog,
         userInput: savedUserInput,
@@ -186,8 +216,11 @@ export async function startDaemon({
         finalResponse,
       })
     );
-    const parsed = parseHaikuResponse(raw);
-    logFn(`turn_end: pass=${parsed.pass}, missing=${parsed.missing_tools.map((m) => m.name).join(',')}`);
+    logFn(
+      `turn_end: pass=${parsed.pass}, missing=${parsed.missing_tools.map((m) => m.name).join(',')}${
+        parsed.reason ? `, reason=${parsed.reason}` : ''
+      }`
+    );
 
     state.usedTools = [];
     state.lastUserInput = null;
@@ -213,35 +246,6 @@ export async function startDaemon({
   const pidPath = pidFilePath(sessionId);
   await writeFile(pidPath, String(process.pid), 'utf8');
 
-  // v0.4.2: stateless-safe warmup.
-  // Spawns a single throwaway Haiku call with the full system-prompt + catalog prefix
-  // (same as real calls). Goal: pre-load the Claude CLI binary, warm the Anthropic
-  // connection pool, and populate the prompt cache for the shared prefix, so the
-  // first real user_input does not pay full cold-start cost.
-  //
-  // Important: we bypass callHaikuTracked to avoid setting lastHaikuCallAt. If the
-  // 10-second recursion window activated, a legitimate user_input arriving within
-  // 10s of warmup would be silent-passed (the v0.2.1 bug this mirrors).
-  //
-  // Fire-and-forget: warmup MUST NOT block readiness or real traffic. Failure is
-  // logged but not thrown — at worst, the first real call pays the cold-start cost
-  // we were trying to avoid, same as the pre-warmup baseline.
-  if (warmup) {
-    const warmupPrompt = buildWarmupPrompt({ catalog });
-    callHaiku(warmupPrompt)
-      .then((raw) => {
-        try {
-          parseHaikuResponse(raw);
-          logFn('warmup: ok');
-        } catch (err) {
-          logFn(`warmup: schema failed: ${err.code ?? 'E_INTERNAL'}: ${err.message}`);
-        }
-      })
-      .catch((err) => {
-        logFn(`warmup: call failed: ${err.code ?? 'E_INTERNAL'}: ${err.message}`);
-      });
-  }
-
   return {
     server,
     path,

package/src/daemon/haiku-caller.mjs

@@ -1,13 +1,17 @@
 // claude -p --model claude-haiku-4-5-* wrapper.
 // §5.5: structured JSON I/O, no retries, schema violations throw.
 //
-// v0.4: each Haiku invocation is STATELESS — no --resume, no session-scoped conversation.
-// Every call is an isolated --session-id <fresh UUID> with the full system prompt + catalog.
-// This reverts the v0.2.0 session-scoped optimisation, which caused role-collapse on long
-// sessions: Haiku, having listened to the accumulating Bell conversation, eventually drifted
-// into Bell's persona and abandoned the JSON contract ("Spotter のロールは正式に終了します"),
-// producing E_HAIKU_SCHEMA and silencing the user via hook exit 1.
-// Stateless calls prevent that drift structurally — each call starts from zero context.
+// v0.5.0: session-scoped Haiku is back. Each daemon holds a single Haiku session-id for
+// the life of the Bell session; the first call uses --session-id only, subsequent calls
+// use --session-id + --resume to reattach to the same claude -p conversation, avoiding
+// per-turn cold-start spawn (observed 20–50s in v0.4.x stateless mode).
+//
+// Role-collapse (Haiku drifting into Bell's persona over long sessions — the failure mode
+// v0.4.0 reverted to stateless to avoid) is now handled by a recovery mechanism instead of
+// structural prevention: if the daemon detects a schema violation (E_HAIKU_SCHEMA) from
+// parseHaikuResponse, it calls reset() on the caller to renew the session-id, then silent-
+// passes the offending turn. See daemon.mjs for the catch site. This makes role collapse a
+// "想定済み異常" (CLAUDE.md §0) — recorded, recovered from, never bubbled up as exit 2.
 
 import { spawn } from 'node:child_process';
 import { homedir } from 'node:os';
@@ -32,12 +36,9 @@ export async function ensureWorkdir() {
   return WORKDIR;
 }
 
-// v0.4.3 minimization:
-//   The prompt was getting bigger each iteration (role-guard enumeration, tag injection defence,
-//   triple restatement of "JSON only"). For a solo project there is no adversarial prompt-
-//   injection threat, and persona drift is already structurally prevented by stateless calls.
-//   So we trim aggressively. Shorter prompts → the judgment-anchoring instruction at the tail
-//   is relatively more prominent → JSON compliance tends to improve, not worsen.
+// v0.4.3 minimization (retained in v0.5.0):
+//   Aggressive trim — no adversarial prompt-injection list, no 【最重要】 tags, no triple
+//   restatement. The judgment-anchoring instruction at the tail stays prominent.
 //
 // Shared header (role + schema + few-shot) is identical between first/final stages, which
 // keeps the Anthropic prompt-cache prefix stable across calls of the same stage.
@@ -106,19 +107,6 @@ function projectCatalog(catalog) {
   }));
 }
 
-// Build a lightweight warmup prompt — pre-loads the Claude CLI, network pool,
-// and Anthropic prompt cache (system rules + catalog prefix is identical to real calls).
-// The user_input is a sentinel that should cleanly return pass:true.
-// v0.4.2: stateless-safe. Uses the same buildFirstStagePrompt path, with its own
-// fresh --session-id at spawn time (like every other stateless call).
-// No conversation state survives the warmup.
-export function buildWarmupPrompt({ catalog }) {
-  return buildFirstStagePrompt({
-    catalog,
-    userInput: '__spotter_warmup_ping__',
-  });
-}
-
 // Parse Haiku's response. Throws HaikuError on schema violation.
 export function parseHaikuResponse(raw) {
   const trimmed = raw.trim();
@@ -176,15 +164,16 @@ function truncate(s, n = 300) {
   return s.slice(0, n) + '...';
 }
 
-// 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+.
+// 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+.
 //
-// v0.4: stateless — each call spawns with a fresh --session-id so no conversation history
-// carries over. We keep the flag (rather than omitting) so each call has an explicit,
-// loggable session id, which aids debugging when something goes wrong.
-function buildSpawnArgs(claudeBin, model) {
-  const args = ['-p', '--session-id', randomUUID(), '--model', model];
+// v0.5.0: session-scoped. First call of a given session id uses --session-id only; every
+// subsequent call adds --resume so claude -p re-attaches to that session, skipping cold
+// start. buildSpawnArgs is exported so tests can assert the flag wiring without spawning.
+export function buildSpawnArgs({ claudeBin, model, sessionId, resume }) {
+  const args = ['-p', '--session-id', sessionId, '--model', model];
+  if (resume) args.push('--resume', sessionId);
   if (process.platform === 'win32') {
     return { cmd: 'cmd.exe', cmdArgs: ['/c', claudeBin, ...args] };
   }
@@ -192,20 +181,30 @@ function buildSpawnArgs(claudeBin, model) {
 }
 
 // Invoke `claude -p` in the isolated workdir. Returns raw stdout.
-// §5.5: no retry on failure. §14.1: silent fallback forbidden.
+// §5.5: no retry on failure. §14.1: silent fallback forbidden (role-collapse recovery in
+// daemon.mjs is an explicit §0 exception, not silent fallback).
 //
-// v0.4: STATELESS. Each call is a fresh --session-id; no --resume, no warmup.
-// SPOTTER_PARENT_PID is injected so hooks firing inside the spawned claude exit early
-// via isChildCall() (prevents daemon-spawn recursion).
+// v0.5.0: session-scoped. The caller keeps one session-id for the session's lifetime, and
+// exposes a reset() method that rotates the session-id (used by daemon on E_HAIKU_SCHEMA
+// to recover from role collapse). The returned value is a function (so existing tests that
+// check `typeof caller === 'function'` still pass) with `reset` and `sessionId` attached.
 export function createHaikuCaller({ timeoutMs, claudeBin = 'claude', model = HAIKU_MODEL, env = process.env }) {
   if (typeof timeoutMs !== 'number' || timeoutMs <= 0) {
     throw new TypeError('timeoutMs must be a positive number');
   }
 
-  return async function callHaiku(prompt) {
+  let currentSessionId = randomUUID();
+  let isFirstCall = true;
+
+  const callHaiku = async function (prompt) {
     await ensureWorkdir();
     return new Promise((resolve, reject) => {
-      const { cmd, cmdArgs } = buildSpawnArgs(claudeBin, model);
+      const { cmd, cmdArgs } = buildSpawnArgs({
+        claudeBin,
+        model,
+        sessionId: currentSessionId,
+        resume: !isFirstCall,
+      });
       const child = spawn(cmd, cmdArgs, {
         cwd: WORKDIR,
         env: { ...env, SPOTTER_PARENT_PID: String(process.pid) },
@@ -241,10 +240,26 @@ export function createHaikuCaller({ timeoutMs, claudeBin = 'claude', model = HAI
           reject(new HaikuError('E_INTERNAL', `haiku exited with code ${code}: ${truncate(stderr)}`));
           return;
         }
+        // Flip isFirstCall only after a successful spawn — a failed first call should
+        // still be treated as "session not yet established" so the next attempt uses
+        // --session-id only (not --resume against a non-existent session).
+        isFirstCall = false;
         resolve(stdout);
       });
 
       child.stdin.end(prompt, 'utf8');
     });
   };
+
+  callHaiku.reset = () => {
+    currentSessionId = randomUUID();
+    isFirstCall = true;
+  };
+
+  Object.defineProperty(callHaiku, 'sessionId', {
+    get: () => currentSessionId,
+    enumerable: true,
+  });
+
+  return callHaiku;
 }

package/src/version.mjs

@@ -1 +1 @@
-export const version = '0.4.4';
+export const version = '0.5.0';