claude-spotter 1.4.14 → 1.4.15

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 1.4.15
+
+**codex ログイン失効でサイレントに死に、host の Claude が無反応になる実害バグを根治**。codex auditor の
+ログインが失効 (`token_revoked` / `refresh_token_reused` / `401 Unauthorized`) すると、`spotter install`
+済みプロジェクトで毎ターン入力が消えて「Claude が一切反応しない」状態になっていた。実セッションの daemon
+ログ (`handler error on user_input/turn_end: E_CODEX_CLI_EXIT`) + コード監査 + 公式 hook 仕様の裏取りで
+根本原因を 2 点に特定: (A) codex 異常終了時、stderr/stdout に入っているログイン失効の痕跡を捨てて全部
+`E_CODEX_CLI_EXIT` に潰しており、auth 失敗を区別できていなかった。(B) `UserPromptSubmit` hook が daemon
+エラーを一律 `die(exit 2)` で処理しており、Claude Code は入力時 hook の exit 2 を **ブロッキング扱い =
+プロンプト消去** とするため、失効が永続する限り毎ターン入力が消えていた。
+
+### 変更点
+
+- **編集 [src/core/codex-cli-backend.mjs](src/core/codex-cli-backend.mjs)**: codex の非ゼロ終了時に
+  stdout+stderr をスキャンし、ログイン失効の痕跡があれば新コード `E_CODEX_CLI_AUTH` (対処法
+  「`codex login`」を含むメッセージ) を投げる。痕跡が無ければ従来通り `E_CODEX_CLI_EXIT`。新規 export
+  `isCodexAuthFailure`。分類は非ゼロ終了経路のみ (auth 失敗は <1s で即終了するため timeout 経路は対象外)。
+- **編集 [src/hooks/lib.mjs](src/hooks/lib.mjs)**: `formatSpotterWarning({code,message})` を新設
+  (`[Spotter からの警告]` ブロック、`E_CODEX_CLI_AUTH` は `codex login` を案内、他は理由コード入りの汎用
+  文面)。exit-code 契約コメントを「audit 失敗は loud degradation = exit 0 + additionalContext、exit 2 は
+  malformed envelope 専用」に更新。
+- **編集 [src/hooks/user-prompt.mjs](src/hooks/user-prompt.mjs)**: daemon/transport/resurrect 失敗で
+  `die(exit 2)` する代わりに `degrade()` — 警告を `additionalContext` (drain 済み pending と merge) で出して
+  **exit 0 でプロンプトを通す**。失効に限らずあらゆる監査失敗で host が固まらない。throw 値の `.message`
+  アクセスを optional chaining 化し、非 Error throw が top-level catch (exit 2) に抜ける穴も塞いだ。
+- **編集 [src/hooks/stop.mjs](src/hooks/stop.mjs)**: backend/transport エラーと marker 消失 (TOCTOU) で
+  `die(exit 2 = 継続強制)` をやめ、`status:"degraded"` 記録 + exit 0。pending は積まない (verdict 未生成)。
+  loud な警告は次の `UserPromptSubmit` が配信。
+- **編集 [src/hooks/pre-tool-use.mjs](src/hooks/pre-tool-use.mjs)**: daemon/transport エラーで
+  `die(exit 2 = ツール拒否)` をやめ、`status:"degraded"` 記録 + exit 0 (ツール許可)。記録は best-effort
+  telemetry でありツールを止める理由にならない。
+- **更新 [docs/SPOTTER_CLAUDE_CONTRACT.md](docs/SPOTTER_CLAUDE_CONTRACT.md)**: `UserPromptSubmit` /
+  `PreToolUse` / `Stop` の失敗時 exit-code 契約を新挙動に追従。
+- **追記 [docs/open-issues.md](docs/open-issues.md)**: auth-freeze バグの解決を記録。`Stop` 失敗が
+  セッション最終ターンだと deferred-delivery の性質上サイレントになる残課題を P2 に追記。
+- **テスト 11 件追加** ([test/hooks.test.mjs](test/hooks.test.mjs) /
+  [test/codex-cli-backend.test.mjs](test/codex-cli-backend.test.mjs)): auth 分類 / `formatSpotterWarning` /
+  UserPromptSubmit の loud degrade (auth/汎用/pending merge/resurrect 失敗/非 Error throw) / Stop degrade /
+  PreToolUse degrade。`node --test` 344 pass / 1 skip 緑。
+
+### 検証
+
+実プロジェクトの監査経路 (`createCodexCliAuditorBackend.judge` を実コードで起動) で、再ログイン後に
+`pass` verdict が返ること、および fake spawn でログイン失効 stderr → `E_CODEX_CLI_AUTH` 分類 → hook が
+`[Spotter からの警告]` を additionalContext に出して exit 0 することを確認。多エージェントの敵対的レビュー
+(host-freeze 完全性 / §0 silent-fallback / 分類器精度+docs) で HIGH 2 / MEDIUM 3 を検出し全て反映。
+
 ## 1.4.14
 
 **README 等の公開資産から内部コードネーム "Bell" を撤去**。Spotter の内部設計議論で使われている
@@ -1066,7 +1113,7 @@ Haiku 突然死 (shutdown ログなしで daemon 再起動する事象、v0.12.0
 
 ### 事の発端
 
-v0.8.0 の `spotter db refresh` 実測で x-api (HTTP MCP) が 401 Unauthorized で落ちていた。`claude mcp list` では `x-api: https://kitepon.dynv6.net/mcp (HTTP)` と表示され URL は拾えるが、Spotter の refresh プロセスから叩くと認証情報がないため拒否。ユーザーの指摘で `.mcp.json` を直接 cat したところ、実態は **stdio** で `env: {X_BEARER_TOKEN: "..."}` を持つ設定だった。CLI 表示と actual config が食い違っていた (CLI の cache の古さと思われる)。
+v0.8.0 の `spotter db refresh` 実測で x-api (HTTP MCP) が 401 Unauthorized で落ちていた。`claude mcp list` では `x-api: https://kitepon.dev/mcp (HTTP)` と表示され URL は拾えるが、Spotter の refresh プロセスから叩くと認証情報がないため拒否。ユーザーの指摘で `.mcp.json` を直接 cat したところ、実態は **stdio** で `env: {X_BEARER_TOKEN: "..."}` を持つ設定だった。CLI 表示と actual config が食い違っていた (CLI の cache の古さと思われる)。
 
 判明した設計上の転換点:
 

package/package.json

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

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

@@ -12,6 +12,37 @@ const DEFAULT_CODEX_CLI_REASONING_EFFORT = 'low';
 const STDERR_LIMIT = 32 * 1024;
 const STDOUT_LIMIT = 64 * 1024;
 
+// codex prints auth/login failures to BOTH stdout (the JSON error stream, e.g.
+// {"type":"error","message":"...sign in again..."}) and stderr (codex_login::auth::manager,
+// e.g. "401 Unauthorized ... token_revoked"). We scan the combined text for these markers so a
+// revoked/expired login is classified as the distinct, actionable E_CODEX_CLI_AUTH instead of
+// being collapsed into the generic E_CODEX_CLI_EXIT. Conservative case-insensitive substring
+// match keyed on the wording codex actually emits; if codex changes its wording the generic
+// path still degrades loudly (the hook no longer freezes the host on either code). Classification
+// runs only on the nonzero-exit path below — auth failures are observed to exit immediately
+// (<1s), so the timeout path is not expected to see them; if codex ever starts hanging on auth,
+// the timeout would surface as the generic E_CODEX_CLI_TIMEOUT rather than E_CODEX_CLI_AUTH.
+const CODEX_AUTH_FAILURE_MARKERS = [
+  'token_revoked',
+  'refresh_token_reused',
+  'refresh token was already used',
+  'refresh token has already been used',
+  'invalidated oauth token',
+  '401 unauthorized',
+  'sign in again',
+  'sign back in',
+  'log out and sign in',
+  'not logged in',
+  'please log in',
+  'please login',
+];
+
+export function isCodexAuthFailure(text) {
+  if (typeof text !== 'string' || text.length === 0) return false;
+  const haystack = text.toLowerCase();
+  return CODEX_AUTH_FAILURE_MARKERS.some((marker) => haystack.includes(marker));
+}
+
 export const CODEX_AUDITOR_SCHEMA = {
   type: 'object',
   additionalProperties: false,
@@ -295,9 +326,17 @@ async function runCodexExec({
     child.on('close', (code) => {
       settle(() => {
         if (code !== 0) {
+          const diag = { ...diagnostics(), exitCode: code };
+          if (isCodexAuthFailure(`${diag.stdout}\n${diag.stderr}`)) {
+            reject(new AuditorBackendError('E_CODEX_CLI_AUTH', 'codex-cli auth failed — codex login required (run `codex login`)', {
+              backend: 'codex-cli',
+              diagnostics: diag,
+            }));
+            return;
+          }
           reject(new AuditorBackendError('E_CODEX_CLI_EXIT', `codex-cli exited with code ${code}`, {
             backend: 'codex-cli',
-            diagnostics: { ...diagnostics(), exitCode: code },
+            diagnostics: diag,
           }));
           return;
         }

package/src/hooks/lib.mjs

@@ -1,11 +1,18 @@
 // Shared hook plumbing — stdin read, error → exit-code mapping per §14.3 / §14.4.
 //
 // Exit code contract (§14.3 / §14.4):
-//   0 = success (normal flow)
-//   1 = expected abnormal (daemon unreachable; user should restart daemon)
-//   2 = unexpected (propagate to Claude Code transcript)
+//   0 = success (normal flow), OR a LOUD degradation: the audit could not run but the failure
+//       is surfaced in-band via a `[Spotter からの警告]` additionalContext block, so the host
+//       stays responsive and the user's prompt is never erased. UserPromptSubmit uses this for
+//       any daemon / auditor-backend failure (e.g. codex login expired) — see user-prompt.mjs.
+//   1 = expected abnormal, non-blocking (Claude Code proceeds; first stderr line shown to user).
+//   2 = unexpected protocol/contract violation (malformed Claude Code envelope, missing required
+//       field). Reserved for cases where there is no real user prompt worth preserving — a
+//       UserPromptSubmit exit 2 BLOCKS and erases the prompt, so audit failures must NOT use it.
 //
-// Silent fallback (exit 0 with missing behaviour) is forbidden. See §14.1.
+// A loud degradation (visible warning naming the cause + remedy) is NOT a silent fallback: the
+// user is explicitly told the audit did not run. The forbidden pattern (§14.1) is the SILENT
+// exit-0 that leaves the user believing they are protected when they are not.
 //
 // v0.2 gate helpers (plan §18 / C:\Users\kite_\.claude\plans\10-cuddly-codd.md):
 // - isChildCall(): env-var gate for Spotter's own child backend invocations
@@ -114,15 +121,6 @@ export function optionalString(input, key) {
   return value;
 }
 
-// Map a TransportError / HaikuError into an exit code.
-export function exitCodeFor(err) {
-  if (err && typeof err.code === 'string') {
-    if (err.code === 'E_UNREACHABLE') return 1;
-    return 2;
-  }
-  return 2;
-}
-
 export function die(message, exitCode = 2) {
   process.stderr.write(`spotter-hook: ${message}\n`);
   process.exit(exitCode);
@@ -162,3 +160,25 @@ export function formatTransparentBlockReason(missingTools) {
     ...lines,
   ].join('\n');
 }
+
+// Loud degradation notice (§0 / §14.1): the auditor could not run this turn. Surfaced via the
+// same additionalContext channel as findings so the host stays responsive AND the user is told
+// they are temporarily unprotected (and, for an expired codex login, exactly how to recover).
+// This is the opposite of a silent fallback.
+export function formatSpotterWarning({ code, message } = {}) {
+  const header = '[Spotter からの警告]';
+  if (code === 'E_CODEX_CLI_AUTH') {
+    return [
+      header,
+      'Spotter の監査エンジン (codex) のログインが失効しているため、今回の入力は監査できませんでした。',
+      'この応答を続ける前に、ユーザーに「端末で `codex login` を実行して再ログインすれば Spotter の監査が復旧する」ことを伝えてください。',
+    ].join('\n');
+  }
+  const lines = [
+    header,
+    `Spotter は今回の入力を監査できませんでした (理由コード: ${code ?? 'unknown'})。この応答は監査されていません。`,
+    'この応答を続ける前に、ユーザーに Spotter の監査が一時的に無効になっていることを伝えてください。',
+  ];
+  if (typeof message === 'string' && message.length > 0) lines.push(`詳細: ${message}`);
+  return lines.join('\n');
+}

package/src/hooks/pre-tool-use.mjs

@@ -7,7 +7,6 @@
 import {
   readStdinJson,
   requireString,
-  exitCodeFor,
   die,
   isChildCall,
   isSubagentCall,
@@ -23,7 +22,6 @@ export async function runPreToolUse({
   readInput = readStdinJson,
   sendRequestFn = sendRequest,
   recordHookEventFn = recordClaudeHookEvent,
-  dieFn = die,
 } = {}) {
   if (isChildCall()) return;
   const input = await readInput();
@@ -43,17 +41,21 @@ export async function runPreToolUse({
       timeoutMs: TIMEOUT_MS,
     });
     if (response.ok !== true) {
+      // Recording is best-effort telemetry, not an audit verdict. On a daemon-side error, allow
+      // the tool (exit 0) — a PreToolUse exit 2 would DENY the tool, which must never happen
+      // just because Spotter could not record it. The audit at user_input/turn_end still warns
+      // loudly if the backend is down.
       await recordHookEventFn({
         projectRoot,
         event: {
           hook: 'PreToolUse',
-          status: 'error',
+          status: 'degraded',
           toolName,
           code: response.error?.code ?? 'E_INTERNAL',
+          reason: 'daemon_error',
           durationMs: Date.now() - startedAt,
         },
       });
-      dieFn(`daemon error on tool_used: ${response.error?.code ?? '?'}: ${response.error?.message ?? ''}`, 2);
       return;
     }
     await recordHookEventFn({
@@ -66,17 +68,18 @@ export async function runPreToolUse({
       },
     });
   } catch (err) {
+    // Transport failure during best-effort recording: allow the tool (no exit 2 deny).
     await recordHookEventFn({
       projectRoot,
       event: {
         hook: 'PreToolUse',
-        status: 'error',
+        status: 'degraded',
         toolName,
         code: err?.code ?? 'E_INTERNAL',
+        reason: 'transport',
         durationMs: Date.now() - startedAt,
       },
     });
-    dieFn(`pre-tool-use transport failure: ${err.code ?? '?'}: ${err.message}`, exitCodeFor(err));
   }
 }
 

package/src/hooks/stop.mjs

@@ -10,8 +10,11 @@
 // queue and folds the entries into `additionalContext`, so Bell receives the audit finding
 // alongside the next user input. The original A reply stays as the turn's final message.
 //
-// `decision:"block"` is no longer emitted from this hook. Backend / transport errors still
-// exit with code 1 + stderr (silent fallback is forbidden — see lib.mjs).
+// `decision:"block"` is no longer emitted from this hook. Backend / transport errors do NOT
+// force a continuation (a Stop exit 2 would block stopping = harmful noise on a Spotter-side
+// failure); they are recorded as `degraded` and exit 0. The next UserPromptSubmit surfaces the
+// loud `[Spotter からの警告]`. No verdict is produced on failure, so nothing is queued — this is
+// still not a silent "all clear" (the surfacing just moves to the next turn — see lib.mjs).
 // `stop_hook_active:true` is still observed: the daemon early-passes on it, so we just
 // receive `pass:true` and return without writing pending context.
 //
@@ -20,7 +23,6 @@
 import {
   readStdinJson,
   requireString,
-  exitCodeFor,
   die,
   findSpotterMarker,
   formatTransparentBlockReason,
@@ -41,7 +43,6 @@ export async function runStop({
   appendPendingContextFn = appendPendingContext,
   getLastAssistantTextFn = getLastAssistantText,
   recordHookEventFn = recordClaudeHookEvent,
-  dieFn = die,
 } = {}) {
   if (isChildCall()) return;
   const input = await readInput();
@@ -71,30 +72,36 @@ export async function runStop({
       timeoutMs: TIMEOUT_MS,
     });
   } catch (err) {
+    // Spotter-side failure (daemon unreachable, etc.): record + exit 0. Do NOT force the model to
+    // continue (a Stop exit 2 blocks stopping). The next UserPromptSubmit surfaces the loud
+    // warning; no pending is written, so this is not a silent "all clear" — there was no verdict.
     await recordHookEventFn({
       projectRoot,
       event: {
         hook: 'Stop',
-        status: 'error',
+        status: 'degraded',
         code: err?.code ?? 'E_INTERNAL',
+        reason: 'transport',
         durationMs: Date.now() - startedAt,
       },
     });
-    dieFn(`stop transport failure: ${err.code ?? '?'}: ${err.message}`, exitCodeFor(err));
     return;
   }
 
   if (response.ok !== true) {
+    // Auditor backend failed (e.g. codex login expired): record + exit 0. Forcing a continuation
+    // (exit 2) on a Spotter-side failure is harmful; the loud warning is delivered by the next
+    // UserPromptSubmit. No verdict was produced, so nothing is queued.
     await recordHookEventFn({
       projectRoot,
       event: {
         hook: 'Stop',
-        status: 'error',
+        status: 'degraded',
         code: response.error?.code ?? 'E_INTERNAL',
+        reason: 'daemon_error',
         durationMs: Date.now() - startedAt,
       },
     });
-    dieFn(`daemon error on turn_end: ${response.error?.code ?? '?'}: ${response.error?.message ?? ''}`, 2);
     return;
   }
 
@@ -117,9 +124,10 @@ export async function runStop({
   // decision:"block". Using the same transparent block-reason wording keeps the user-facing
   // text identical to the prior block flow.
   if (!projectRoot) {
-    // Marker walk-up returns null only when isOutsideSpotterProject would have early-returned
-    // above. Reaching here implies the marker disappeared mid-turn; treat as unexpected.
-    dieFn(`stop: cannot queue pending context — no .spotter/marker.json above cwd=${input.cwd}`, 2);
+    // TOCTOU: the marker disappeared between the isOutsideSpotterProject guard and now. We cannot
+    // persist the finding (no project dir to write into), but a Stop exit 2 would force the model
+    // to continue — the harmful pattern this hook avoids. Drop the unpersistable finding and exit
+    // 0; the next UserPromptSubmit re-audits from a fresh marker walk.
     return;
   }
   const text = formatTransparentBlockReason(result.missing_tools);

package/src/hooks/user-prompt.mjs

@@ -16,9 +16,9 @@
 import {
   readStdinJson,
   requireString,
-  exitCodeFor,
   die,
   formatTransparentContext,
+  formatSpotterWarning,
   isChildCall,
   isSubagentCall,
   isOutsideSpotterProject,
@@ -39,7 +39,6 @@ export async function runUserPrompt({
   drainPendingContextsFn = drainPendingContexts,
   recordHookEventFn = recordClaudeHookEvent,
   writeOutput = (text) => process.stdout.write(text),
-  dieFn = die,
 } = {}) {
   if (isChildCall()) return;
   const input = await readInput();
@@ -58,6 +57,26 @@ export async function runUserPrompt({
     ? await drainPendingContextsFn({ projectRoot, sessionId })
     : [];
 
+  // Loud degradation (§0 / §14.1): the audit could not run, but the user's prompt is valid.
+  // Surface a visible [Spotter からの警告] (merged with any drained pending context) and exit 0
+  // so the prompt reaches the host — never erase it with a blocking exit 2.
+  const degrade = async ({ code, message, reason }) => {
+    const contexts = pendingContexts.slice();
+    contexts.push(formatSpotterWarning({ code, message }));
+    emitAdditionalContext(writeOutput, contexts);
+    await recordHookEventFn({
+      projectRoot,
+      event: {
+        hook: 'UserPromptSubmit',
+        status: 'degraded',
+        code: code ?? 'E_INTERNAL',
+        reason,
+        pendingContextCount: pendingContexts.length,
+        durationMs: Date.now() - startedAt,
+      },
+    });
+  };
+
   if ([...prompt.trim()].length <= SHORT_PROMPT_MAX_CHARS) {
     if (pendingContexts.length > 0) {
       emitAdditionalContext(writeOutput, pendingContexts);
@@ -88,67 +107,31 @@ export async function runUserPrompt({
     response = await sendUserInput();
   } catch (err) {
     if (err instanceof TransportError && err.code === 'E_UNREACHABLE') {
-      // v0.12.0: daemon is gone (heartbeat shutdown, crash, missing). Resurrect and retry.
-      if (!projectRoot) {
-        dieFn(`user-prompt: cannot resurrect daemon — no .spotter/marker.json above cwd=${input.cwd}`, 2);
-        return;
-      }
+      // v0.12.0: daemon is gone (heartbeat shutdown, crash, missing). Resurrect and retry once.
+      // projectRoot is guaranteed non-null here (isOutsideSpotterProject early-returned otherwise).
       try {
         await spawnDaemonAndWaitReadyFn({ sessionId, projectRoot });
-      } catch (spawnErr) {
-        await recordHookEventFn({
-          projectRoot,
-          event: {
-            hook: 'UserPromptSubmit',
-            status: 'error',
-            code: spawnErr?.code ?? 'E_RESURRECT_FAILED',
-            durationMs: Date.now() - startedAt,
-          },
-        });
-        dieFn(`user-prompt: daemon resurrect failed: ${spawnErr.message}`, spawnErr.exitCode ?? 2);
-        return;
-      }
-      try {
         response = await sendUserInput();
-      } catch (retryErr) {
-        await recordHookEventFn({
-          projectRoot,
-          event: {
-            hook: 'UserPromptSubmit',
-            status: 'error',
-            code: retryErr?.code ?? 'E_INTERNAL',
-            durationMs: Date.now() - startedAt,
-          },
+      } catch (recoverErr) {
+        await degrade({
+          code: recoverErr?.code ?? 'E_RESURRECT_FAILED',
+          message: recoverErr?.message ?? '',
+          reason: 'resurrect_failed',
         });
-        dieFn(`user-prompt transport failure after resurrect: ${retryErr.code ?? '?'}: ${retryErr.message}`, exitCodeFor(retryErr));
         return;
       }
     } else {
-      await recordHookEventFn({
-        projectRoot,
-        event: {
-          hook: 'UserPromptSubmit',
-          status: 'error',
-          code: err?.code ?? 'E_INTERNAL',
-          durationMs: Date.now() - startedAt,
-        },
-      });
-      dieFn(`user-prompt transport failure: ${err.code ?? '?'}: ${err.message}`, exitCodeFor(err));
+      await degrade({ code: err?.code ?? 'E_INTERNAL', message: err?.message ?? '', reason: 'transport' });
       return;
     }
   }
 
   if (response.ok !== true) {
-    await recordHookEventFn({
-      projectRoot,
-      event: {
-        hook: 'UserPromptSubmit',
-        status: 'error',
-        code: response.error?.code ?? 'E_INTERNAL',
-        durationMs: Date.now() - startedAt,
-      },
+    await degrade({
+      code: response.error?.code ?? 'E_INTERNAL',
+      message: response.error?.message ?? '',
+      reason: 'daemon_error',
     });
-    dieFn(`daemon error on user_input: ${response.error?.code ?? '?'}: ${response.error?.message ?? ''}`, 2);
     return;
   }