@cocorograph/hub-agent 0.6.93 → 0.6.95

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cocorograph/hub-agent",
-  "version": "0.6.93",
+  "version": "0.6.95",
   "description": "Hub Hosted Cockpit のローカル常駐 agent。Hub と outbound WSS で接続し、ローカルの tmux/pty を中継する。",
   "type": "module",
   "license": "UNLICENSED",

package/src/main.mjs

@@ -85,6 +85,12 @@ import {
   recordChatRateLimit,
 } from "./usage.mjs"
 import { clearChatSignal, getChatSignal, recordChatActivity } from "./chat-signals.mjs"
+import {
+  ReadinessTracker,
+  busyChildCount,
+  getPanePid,
+  snapshotProcs,
+} from "./proc-introspect.mjs"
 import { hydrateProcessEnvFromShell } from "./shell-env.mjs"
 
 const logger = pino({ name: "hub-agent" })
@@ -582,17 +588,34 @@ export async function startDaemon({ version, ptyModule, claudeSdk } = {}) {
 
   // 5s 周期で全 tmux session の状態を捕捉し、変化したものだけ session.state を push。
   // browser がフォーカスしていない session でも常時更新するためのバックグラウンド職人。
+  // ready-for-input 判定: claude プロセスの子プロセスを内省し「Stop フック/ツール実行が
+  // 終わって真に入力可能になった」エッジを検出する (proc-introspect.mjs)。capture-pane は
+  // Stop フック実行中を観測できないため、これが「stop の早期消灯/誤フラッシュ」の根治。
+  const readinessTracker = new ReadinessTracker()
   const stateLoop = startStateLoop({
     client,
     plugins,
     logger,
     intervalMs: 5_000,
     claudeBridge,
+    readinessTracker,
   })
   // bundle hook (cockpit_session_event_hook.py) が /tmp/cockpit_session_events/<name>.json
-  // に書き出す UserPromptSubmit / Stop の event を fs.watch で拾って WS push する。
+  // に書き出す UserPromptSubmit / Stop / ready の event を fs.watch で拾って WS push する。
   // text マーカー判定 (detectStatusFromText) より精度が高い「ターン境界」の signal。
-  const sessionEventLoop = await startSessionEventWatcher({ client, logger })
+  // prompt_submit / stop で readinessTracker を arm し、ready の settle 検出に繋ぐ。
+  const sessionEventLoop = await startSessionEventWatcher({
+    client,
+    logger,
+    readinessTracker,
+  })
+  // arm 済みセッションの子プロセスを高速 poll し、baseline 復帰で event ファイルに 'ready'
+  // を書く (既存 watcher が session.event 'ready' を push)。アイドル時は ps を spawn しない。
+  const readinessLoop = startReadinessLoop({
+    logger,
+    tracker: readinessTracker,
+    intervalMs: 700,
+  })
 
   // TUI 権限ブリッジ: 対話 TUI の PreToolUse フックが書く権限要求を fs.watch で
   // 拾い、既存 SDK 経路と同じ `claude.permission.request` として push する。
@@ -660,6 +683,7 @@ export async function startDaemon({ version, ptyModule, claudeSdk } = {}) {
     await runHookBroadcast(plugins, "onAgentStop", ctx)
     stateLoop.stop()
     sessionEventLoop?.stop?.()
+    readinessLoop?.stop?.()
     tuiPermissionBridge.stop()
     tuiViewerRegistry.stop()
     jsonlLiveWatchers.stop()
@@ -832,7 +856,7 @@ async function readSessionEventFile(sessionName) {
  * ディレクトリが無ければ作成し、起動直後に既存ファイルを 1 回読んで初期 push。
  * 以降は変更検知のたびに該当ファイルを読み直して push する。
  */
-async function startSessionEventWatcher({ client, logger }) {
+async function startSessionEventWatcher({ client, logger, readinessTracker }) {
   try {
     await mkdir(SESSION_EVENTS_DIR, { recursive: true })
   } catch (err) {
@@ -851,6 +875,21 @@ async function startSessionEventWatcher({ client, logger }) {
       const text = await readFile(full, "utf-8")
       const data = JSON.parse(text)
       if (!data || typeof data.event !== "string") return
+      // ターン境界 (prompt_submit / stop) で readiness tracker を arm し、子プロセスが
+      // baseline へ復帰したら 'ready' を出す土台にする。'ready' 自身では arm しない
+      // (readiness loop の書込み → 再 arm の無限ループを避ける)。prompt_submit は次ターンの
+      // ready を解禁するため emitted をリセットする。
+      if (readinessTracker) {
+        if (data.event === "prompt_submit") {
+          readinessTracker.arm(sessionName, { newTurn: true })
+        } else if (data.event === "stop" || data.event === "idle_hint") {
+          // stop: ターン論理終了。idle_hint: Notification(idle_prompt) フックの裏取り。
+          // どちらも arm するだけで、実際の 'ready' は proc 内省 (子プロセス baseline 復帰)
+          // が確定させる。これにより Notification が Stop フック完了前に発火しても、
+          // proc が clear するまで誤フラッシュしない (idle_hint→即 ready にはしない)。
+          readinessTracker.arm(sessionName)
+        }
+      }
       client.send({
         type: "session.event",
         session_name: sessionName,
@@ -892,6 +931,88 @@ async function startSessionEventWatcher({ client, logger }) {
   }
 }
 
+/**
+ * arm 済みセッション (prompt_submit / stop を受けた or busy 観測中) の claude プロセスを
+ * 高速 poll し、子プロセスが baseline へ復帰したエッジで event ファイルに 'ready' を書く。
+ * 既存の startSessionEventWatcher がそれを `session.event` 'ready' として push し、frontend は
+ * 「真に入力可能」になった瞬間として消灯 + キューフラッシュする (Stop フック中の誤フラッシュ
+ * 根治)。tracker.getBusy() は state loop が proc_busy レベルとして相乗せする。
+ *
+ * 負荷: アイドル (armed/busy なし) のときは ps を spawn しない。claude pid は TTL キャッシュ。
+ */
+function startReadinessLoop({ tracker, logger, intervalMs = 700 }) {
+  let stopped = false
+  const PANE_PID_TTL_MS = 30_000
+  const panePidByName = new Map() // name → {pid, at}
+  const unresolvedStreak = new Map() // name → 連続解決失敗回数 (SDK チャット等の掃除用)
+
+  // busy 子数のカウント基点は claude 本体 PID ではなく tmux の **pane_pid** にする。
+  // 理由: (1) クロスプラットフォーム安全 — claude を comm 名で同定する方式は Linux/WSL で
+  // claude が `node .../cli.js` として起動し comm が 'node' になり同定に失敗する。pane_pid
+  // 基点なら子孫を数えるだけで claude の同定が不要。(2) /clear 耐性 — claude PID は /clear で
+  // 変わるが pane_pid (ペインの shell) は不変なので再解決が要らない。baseline (rolling-min) が
+  // 「claude 本体 + 常駐 MCP」を吸収するので、基点が pane_pid でも busy=「一過性の子増加」で正しい。
+  const resolvePanePid = async (name, procMap) => {
+    const hit = panePidByName.get(name)
+    if (hit && procMap.has(hit.pid) && Date.now() - hit.at < PANE_PID_TTL_MS) {
+      return hit.pid
+    }
+    const panePid = await getPanePid(name)
+    if (panePid && procMap.has(panePid)) {
+      panePidByName.set(name, { pid: panePid, at: Date.now() })
+      return panePid
+    }
+    panePidByName.delete(name)
+    return null
+  }
+
+  const tick = async () => {
+    if (stopped) return
+    try {
+      const names = []
+      for (const n of tracker.byName.keys()) {
+        if (tracker.isActive(n)) names.push(n)
+      }
+      if (names.length === 0) return
+      const procMap = await snapshotProcs()
+      if (procMap.size === 0) return // ps 失敗時は据え置き (spurious ready 防止)
+      for (const name of names) {
+        const root = await resolvePanePid(name, procMap)
+        if (!root) {
+          // 解決失敗は observe しない (count=0 を注入すると誤って ready が出るため)。
+          // SDK チャット等で tmux セッションが無いものは連続失敗で tracker から忘れる。
+          const k = (unresolvedStreak.get(name) ?? 0) + 1
+          if (k >= 8) {
+            tracker.forget(name)
+            unresolvedStreak.delete(name)
+            panePidByName.delete(name)
+          } else {
+            unresolvedStreak.set(name, k)
+          }
+          continue
+        }
+        unresolvedStreak.delete(name)
+        const count = busyChildCount(root, procMap)
+        const { ready } = tracker.observe(name, count)
+        if (ready) {
+          await writeSessionEventFile(name, "ready", Date.now())
+        }
+      }
+    } catch (err) {
+      logger?.warn({ err: err?.message }, "readiness loop tick failed")
+    }
+  }
+
+  const ti = setInterval(tick, intervalMs)
+  ti.unref?.()
+  return {
+    stop() {
+      stopped = true
+      clearInterval(ti)
+    },
+  }
+}
+
 /**
  * 全 tmux session の状態を定期 capture し、変化したものだけ Hub に push する。
  *
@@ -900,9 +1021,17 @@ async function startSessionEventWatcher({ client, logger }) {
  *   pty.exit 受信時に処理する)
  * - tmux 自体が動いてない場合 (listSessionStates → []) は何も push しない
  */
-function startStateLoop({ client, plugins, logger, intervalMs, claudeBridge }) {
+// (i) 出力フロー検知の有効窓。ペイン出力領域の署名 (output_sig) が直近この時間内に変化して
+// いれば「出力ストリーミング中」とみなし proc_busy に OR する。state loop は 5s 周期なので、
+// 連続生成中は毎 tick 署名が変わり常時 true、出力が止まれば次 tick (≤5s) で署名不変になり
+// 窓経過後に false へ落ちる (ターン終了後のスピナー固着=症状A を悪化させない短さ)。
+const OUTPUT_ACTIVE_MS = Number(process.env.HUB_AGENT_OUTPUT_ACTIVE_MS ?? 8000)
+
+function startStateLoop({ client, plugins, logger, intervalMs, claudeBridge, readinessTracker }) {
   const lastByName = new Map() // session_name → {status, context_pct}
   const lastTurnAtByName = new Map() // session_name → 最後に event ファイル化した turnAt
+  // (i) session_name → {sig, changedAt}: 出力領域署名の最終変化時刻 (出力フロー検知用)。
+  const outputFlowByName = new Map()
   let stopped = false
 
   // RC-8: WS 再接続のたびに差分送信の基準 (lastByName) をクリアし、次 tick で全 session.state を
@@ -969,19 +1098,41 @@ function startStateLoop({ client, plugins, logger, intervalMs, claudeBridge }) {
         // 内容安定で「確実に停止」と判定できたか (frontend が 2 サンプル消灯確認を省いて
         // 即消灯するためのフラグ)。chat 信号で processing へ上書きされた場合は false。
         const stable = status !== "processing" && s.stable === true
+        // プロセス内省由来の busy レベル (Stop フック/ツール実行中=true)。frontend は
+        // これでペイン由来の早期消灯を抑止し、tool/Stop フック中もスピナーを保つ。
+        // 高速 readiness loop が維持する値をそのまま相乗せする (この loop では計算しない)。
+        const childBusy = readinessTracker ? readinessTracker.getBusy(s.session_name) : false
+        // (i) 出力フロー検知: proc 内省は pane_pid 子孫の「プロセス数」で busy を見るため、
+        // ツールを起動しない純テキスト生成 (モデルが出力を流すだけ) を busy として検出できない。
+        // その間に capture-pane のスピナー検出が 1 フレーム取りこぼすと frontend がアイドルと
+        // 誤読してスピナーを消す (生成中なのに消える=症状B)。出力領域の署名が直近変化していれば
+        // 「出力中」とみなし proc_busy に OR する。childBusy=false の純テキスト生成中も
+        // proc_busy=true となり frontend のペイン由来消灯が抑止される。出力が止まれば署名が
+        // 不変になり窓経過後に false へ落ちるので、ターン終了後のスピナー固着は悪化させない。
+        let outputActive = false
+        if (typeof s.output_sig === "string") {
+          const prevFlow = outputFlowByName.get(s.session_name)
+          let changedAt = prevFlow ? prevFlow.changedAt : 0
+          if (!prevFlow || prevFlow.sig !== s.output_sig) changedAt = Date.now()
+          outputFlowByName.set(s.session_name, { sig: s.output_sig, changedAt })
+          outputActive = Date.now() - changedAt < OUTPUT_ACTIVE_MS
+        }
+        const procBusy = childBusy || outputActive
         const prev = lastByName.get(s.session_name)
         if (
           !prev ||
           prev.status !== status ||
           prev.context_pct !== contextPct ||
           prev.permission_mode !== permissionMode ||
-          prev.stable !== stable
+          prev.stable !== stable ||
+          prev.proc_busy !== procBusy
         ) {
           lastByName.set(s.session_name, {
             status,
             context_pct: contextPct,
             permission_mode: permissionMode,
             stable,
+            proc_busy: procBusy,
           })
           client.send({
             type: "session.state",
@@ -990,6 +1141,7 @@ function startStateLoop({ client, plugins, logger, intervalMs, claudeBridge }) {
             context_pct: contextPct,
             permission_mode: permissionMode,
             stable,
+            proc_busy: procBusy,
           })
         }
       }

package/src/proc-introspect.mjs

@@ -0,0 +1,336 @@
+/**
+ * プロセス内省による「入力可能 (ready-for-input)」判定。
+ *
+ * 背景 / なぜ画面スクレイプでなくプロセスを見るのか:
+ *   Cockpit の TUI チャットは tmux 上の対話 `claude` を hub-agent (= 同一ホスト) が
+ *   仲介する。生成中/アイドルの判定はこれまで capture-pane のスピナー文字列 (state.mjs)
+ *   に一本依存していたが、これは「Stop フック実行中」を観測できない致命的な穴がある:
+ *   モデルのターンが終わると claude TUI はスピナー行を消し、アイドルの `❯` プロンプトを
+ *   描く。しかし組織のグローバル Stop フック (memory_update.py 等) はその後ろでまだ
+ *   走っており、入力を受け付けられる状態ではない。capture-pane はアイドルに見えるため、
+ *   frontend がキューを早期フラッシュ → ビジーな TUI に paste → 内部キュー行きで
+ *   バブルと jsonl の位置がズレる事故になっていた。
+ *
+ *   Claude Code は「Stop フックチェーン完了 = 入力可能」を知らせるフックイベントを
+ *   持たず、Stop フックは並列実行のため「最後のフック」で完了を知ることもできない
+ *   (claude-code-guide で確認, 2026-06-18)。そこで、hub-agent が claude と同一ホストに
+ *   居る利点を使い、claude プロセスの子プロセスを直接観測する:
+ *     - Stop フック実行中  → フックスクリプト (python3 等) が claude の子として生存
+ *     - ツール実行中 (Bash) → ツールが claude の子として生存
+ *     - 真のアイドル(入力待ち) → 一過性の子は無い (常駐 MCP stdio サーバーを除く)
+ *
+ * 常駐 MCP の除外 (実機観察 2026-06-18):
+ *   アイドルの claude は安定して 2 個の stdio MCP 子 (chrome-devtools-mcp / pencil) を
+ *   持つ。一過性の tool/hook はこれに上乗せされる。よって busy = 「子孫数 > 直近の
+ *   最小子孫数 (rolling-min ベースライン)」で判定する。ベースラインは自然に常駐 MCP の
+ *   数に収束し、明示的な MCP 同定は不要。
+ *   例外: `caffeinate` は Claude Code がスリープ抑止に spawn する -t 300 の 5 分常駐で、
+ *   ターン後も居残るため busy 判定の子数から除外する (denylist)。
+ */
+import { execFile } from "node:child_process"
+import { promisify } from "node:util"
+
+const execFileP = promisify(execFile)
+
+/**
+ * 「busy とみなさない」background helper の comm 基底名 denylist。
+ * - caffeinate: 生成中のスリープ抑止に spawn される 5 分常駐 (-t 300)。ターン後も残るため
+ *   除外しないと proc_busy がターン後 5 分間 true のままになり ready が遅延する。
+ */
+const BUSY_EXCLUDE_COMM = new Set(["caffeinate"])
+
+/** パス文字列の基底名 (最後の / 以降)。空なら空文字。 */
+export function commBasename(comm) {
+  if (!comm) return ""
+  const s = String(comm).trim()
+  const i = s.lastIndexOf("/")
+  return i >= 0 ? s.slice(i + 1) : s
+}
+
+/**
+ * `ps -axo pid=,ppid=,comm=` を 1 回 spawn してプロセス表を返す。
+ * comm はパスにスペースを含み得る (例: ".../Claude Helper (Renderer)") ため、
+ * 行頭 2 トークンを pid/ppid、残り全部を comm として扱う。
+ *
+ * @returns {Promise<Map<number, {ppid: number, comm: string}>>}
+ */
+export async function snapshotProcs({ psBin = "ps", execFileImpl = execFileP } = {}) {
+  const map = new Map()
+  try {
+    const { stdout } = await execFileImpl(psBin, ["-axo", "pid=,ppid=,comm="])
+    for (const line of stdout.split("\n")) {
+      const t = line.trim()
+      if (!t) continue
+      const m = t.match(/^(\d+)\s+(\d+)\s+(.*)$/)
+      if (!m) continue
+      const pid = Number(m[1])
+      const ppid = Number(m[2])
+      if (!Number.isFinite(pid)) continue
+      map.set(pid, { ppid, comm: m[3] || "" })
+    }
+  } catch {
+    // ps 失敗時は空 Map (呼び出し側は busy 判定を据え置く)。
+  }
+  return map
+}
+
+/** procMap から ppid → 子 pid[] の逆引きを作る。 */
+function buildChildren(procMap) {
+  const children = new Map()
+  for (const [pid, info] of procMap) {
+    const arr = children.get(info.ppid)
+    if (arr) arr.push(pid)
+    else children.set(info.ppid, [pid])
+  }
+  return children
+}
+
+/**
+ * rootPid の子孫 pid を BFS で集める (root 自身は含めない)。循環は visited で防ぐ。
+ * @returns {number[]}
+ */
+export function descendantsOf(rootPid, procMap, children = buildChildren(procMap)) {
+  const out = []
+  const visited = new Set([rootPid])
+  let frontier = children.get(rootPid) || []
+  while (frontier.length) {
+    const next = []
+    for (const pid of frontier) {
+      if (visited.has(pid)) continue
+      visited.add(pid)
+      out.push(pid)
+      const kids = children.get(pid)
+      if (kids) next.push(...kids)
+    }
+    frontier = next
+  }
+  return out
+}
+
+/**
+ * tmux session の pane_pid を取得する (失敗時 null)。
+ */
+export async function getPanePid(sessionName, { tmuxBin = "tmux", execFileImpl = execFileP } = {}) {
+  if (!sessionName || /[/\\]/.test(sessionName)) return null
+  try {
+    const { stdout } = await execFileImpl(tmuxBin, [
+      "display-message",
+      "-p",
+      "-t",
+      `${sessionName}:`,
+      "-F",
+      "#{pane_pid}",
+    ])
+    const n = Number(stdout.trim())
+    return Number.isFinite(n) && n > 0 ? n : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * pane_pid から対話 claude 本体の pid を解決する。
+ * cockpit の tmux ペインは shell (pane_pid) の子として `claude` を起動するため、
+ * pane_pid 自身か、その子孫のうち comm 基底名が 'claude' のものを返す。
+ * @returns {number|null}
+ */
+export function resolveClaudePid(panePid, procMap) {
+  if (!panePid) return null
+  const self = procMap.get(panePid)
+  if (self && commBasename(self.comm) === "claude") return panePid
+  const children = buildChildren(procMap)
+  for (const pid of descendantsOf(panePid, procMap, children)) {
+    const info = procMap.get(pid)
+    if (info && commBasename(info.comm) === "claude") return pid
+  }
+  return null
+}
+
+/**
+ * rootPid (通常は tmux の pane_pid。claude pid でも可) の「busy を示す」子孫数を数える
+ * (denylist の background helper を除外)。常駐 MCP / claude 本体は除外しない
+ * (rolling-min ベースラインが吸収する)。一過性の tool/hook 子だけがカウントを押し上げる。
+ */
+export function busyChildCount(rootPid, procMap) {
+  if (!rootPid) return 0
+  const children = buildChildren(procMap)
+  let n = 0
+  for (const pid of descendantsOf(rootPid, procMap, children)) {
+    const info = procMap.get(pid)
+    if (!info) continue
+    if (BUSY_EXCLUDE_COMM.has(commBasename(info.comm))) continue
+    n += 1
+  }
+  return n
+}
+
+/**
+ * セッション毎の「resident (idle) ベースライン」で busy / ready エッジを判定する純粋ステート。
+ *
+ * ❗ 旧実装の rolling-min (直近 windowMs の最小 count) は致命的なドリフトがあった:
+ *   - 長時間ツール (>windowMs) で idle サンプルが窓から押し出され baseline がツール水準まで
+ *     上昇 → busy=false → 走行中に誤 ready (= 誤フラッシュ)。
+ *   - 遅延起動の常駐 MCP で真の idle が上がっても min は古い低値に張り付き busy 固着。
+ * これを避けるため baseline は「ターン中は凍結 (下げのみ許可)、ターン間 idle で学習」する:
+ *   - 非 armed (ターン間 idle / ready 直後の grace) の observe: baseline = count を学習する。
+ *     遅延起動 MCP 等で resident 水準が上がっても次ターンの baseline に反映される。
+ *   - armed (ターン中) の observe: baseline は **上げない** (一過性ツールが新 idle に化けるのを
+ *     防ぐ)。より低い idle 床を観測したときだけ下げる (bootstrap 汚染の自己補正)。
+ *     busy = count > baseline。よって長時間ツールでも count は baseline を超え続け busy のまま。
+ *   - ready = stopSeen かつ busy=false が debounceSamples 連続したエッジで 1 回だけ true。
+ *     ❗ ready を **stopSeen ゲート** する (= stop/idle_hint を受けた後のみ)。prompt_submit 直後は
+ *     UserPromptSubmit フックの子が走っており初回 observe が baseline を汚染し得るため、ターン中の
+ *     誤 ready (event ファイル上書き → サイドバードット誤反転 / 本物 ready の emitted ラッチ毒)
+ *     を構造的に防ぐ。ready は「ターン終了後の入力可能」のみ意味を持つ。
+ *   - 安全弁 maxActiveSamples: armed のまま settle しない (遅延常駐子で busy 永続 / stop 取り
+ *     こぼし) と isActive=true が続き ps spawn リーク + proc_busy 固着になる。上限で baseline を
+ *     現値へ再学習し disarm する (frontend は 120s net が畳むので表示影響なし。次ターンで再 arm)。
+ *
+ * arm(name): prompt_submit / stop / idle_hint で呼ぶ。newTurn (prompt_submit) は emitted を
+ * リセットし stopSeen=false に戻す。stop/idle_hint は stopSeen=true で ready 発火を解禁する。
+ * busy が一度も観測されなくても (Stop フックが poll 間隔より速い場合)、stop 後なら baseline
+ * 復帰の debounce 後に ready を出す。
+ */
+export class ReadinessTracker {
+  constructor({
+    debounceSamples = 2,
+    graceSamples = 4,
+    // armed のまま settle しない上限サンプル数 (≈ 200×700ms ≈ 140s)。遅延常駐子で busy が
+    // 解けない / stop 取りこぼしで idle のまま等で armed が永続すると、isActive=true が続いて
+    // readiness loop が ps を 700ms 毎に spawn し続けるリーク + proc_busy 固着になる。上限で
+    // baseline を現値へ再学習して disarm し、リーク/固着を解消する。frontend は 120s net が
+    // スピナーを既に畳んでいるため表示影響は無い (次ターンで再 arm)。
+    maxActiveSamples = 200,
+    now = () => Date.now(),
+  } = {}) {
+    this.debounceSamples = Math.max(1, debounceSamples)
+    // ready 後しばらく観測を続けて idle baseline を学習する tick 数 (遅延起動 MCP 反映用)。
+    this.graceSamples = Math.max(0, graceSamples)
+    this.maxActiveSamples = Math.max(1, maxActiveSamples)
+    this._now = now
+    /** @type {Map<string, {baseline:number|null, armed:boolean, busy:boolean, clearStreak:number, emitted:boolean, grace:number, stopSeen:boolean, activeStreak:number}>} */
+    this.byName = new Map()
+  }
+
+  _get(name) {
+    let s = this.byName.get(name)
+    if (!s) {
+      s = {
+        baseline: null,
+        armed: false,
+        busy: false,
+        clearStreak: 0,
+        emitted: false,
+        grace: 0,
+        stopSeen: false,
+        activeStreak: 0,
+      }
+      this.byName.set(name, s)
+    }
+    return s
+  }
+
+  /**
+   * prompt_submit / stop / idle_hint でターン進行を宣言する。
+   * clearStreak を 0 に戻すことで、arm 以降に debounceSamples 回連続でアイドルを観測して
+   * 初めて ready を出す = stop 直後に Stop フックの子が spawn し始めるレースを吸収する。
+   *
+   * newTurn (prompt_submit): 次ターン開始。emitted リセットで ready を解禁し、stopSeen=false に
+   *   戻す (モデルのターンはまだ終わっていない)。baseline はターン間 idle 学習値を引き継ぐ。
+   * それ以外 (stop / idle_hint): モデルのターンが終わった合図。stopSeen=true にして ready 発火を
+   *   解禁する。ready を **stopSeen ゲート**することで、prompt_submit 直後の bootstrap 汚染
+   *   (UserPromptSubmit フックの子を初回 observe が拾い baseline が膨らむ) でターン中に誤 ready が
+   *   出て event ファイルを上書きする退行を防ぐ (ready は「ターン終了後の入力可能」のみ意味を持つ)。
+   */
+  arm(name, { newTurn = false } = {}) {
+    const s = this._get(name)
+    s.armed = true
+    s.clearStreak = 0
+    s.activeStreak = 0
+    s.grace = 0
+    if (newTurn) {
+      s.emitted = false
+      s.stopSeen = false
+    } else {
+      s.stopSeen = true
+    }
+  }
+
+  /** @returns {{busy: boolean, ready: boolean}} */
+  observe(name, count) {
+    const s = this._get(name)
+    if (s.baseline === null) s.baseline = count // bootstrap (初回 ≈ idle)
+    if (!s.armed) {
+      // ターン間 idle / ready 直後の grace: resident baseline を学習 (上下とも追従)。
+      s.busy = false
+      s.baseline = count
+      if (s.grace > 0) s.grace -= 1
+      return { busy: false, ready: false }
+    }
+    s.activeStreak += 1
+    // 安全弁: armed のまま settle しない上限 (≈140s)。baseline を現値へ再学習し disarm して
+    // ps spawn リーク / proc_busy 固着を解消する (遅延常駐子で busy が永続するケース等)。
+    // ⚠️ ここは baseline=count (現 busy 値への引き上げ) であって Math.min ではない。遅延常駐子で
+    // 永続的に上がった count を新 idle として吸収するため上げる必要がある (Math.min にすると
+    // 「遅延常駐子で busy 固着」HIGH バグが再発する)。代償として、cap が長時間ツールで発火した
+    // 場合は次ターン頭で baseline が高めに残り proc_busy を一時的に過少報告し得る (LOW: スピナーが
+    // ツール中に早めに消えるだけで、ready/フラッシュ経路は無傷。次の idle 観測で line の下げ学習が
+    // 自己補正する)。cap 自体が 140s 無 settle という稀な劣化状態の後始末なので許容する。
+    if (s.activeStreak >= this.maxActiveSamples) {
+      s.baseline = count
+      s.busy = false
+      s.armed = false
+      s.grace = this.graceSamples
+      s.clearStreak = 0
+      s.activeStreak = 0
+      // cap = 140s armed のまま settle しない異常状態の後始末。stopSeen 済 (= モデルのターンは
+      // 終わっている) なら、ここで ready を 1 回だけ出して frontend のスピナー固着とキュー詰まり
+      // (ready 不発で turnOverride=true が畳めず drain されない) を解く。ユーザーが Claude 経由で
+      // dev server 等を起動しっぱなしにし、その子プロセスで count>baseline が永続して busy が
+      // 解けないケース (症状A の主因) を救済する。stopSeen=false (stop 取りこぼし or 本当に 140s
+      // 走行中) のときは出さない (生成中への誤フラッシュ防止)。
+      let ready = false
+      if (s.stopSeen && !s.emitted) {
+        ready = true
+        s.emitted = true
+      }
+      return { busy: false, ready }
+    }
+    // ターン中: baseline は上げない (一過性ツールを新 idle に化けさせない)。より低い床は学習。
+    if (count < s.baseline) s.baseline = count
+    const busy = count > s.baseline
+    s.busy = busy
+    if (busy) {
+      s.emitted = false
+      s.clearStreak = 0
+      return { busy: true, ready: false }
+    }
+    s.clearStreak += 1
+    let ready = false
+    // ready は stopSeen (= stop/idle_hint 受信済み = モデルのターン終了) のときだけ発火する。
+    if (s.stopSeen && s.clearStreak >= this.debounceSamples) {
+      if (!s.emitted) {
+        ready = true
+        s.emitted = true
+      }
+      // ready 済み or 今出した → armed を畳んで grace へ (idle baseline 学習を続ける)。
+      s.armed = false
+      s.grace = this.graceSamples
+    }
+    return { busy, ready }
+  }
+
+  getBusy(name) {
+    return this.byName.get(name)?.busy ?? false
+  }
+
+  /** readiness loop が観測対象に含めるべきか (armed / busy / grace 中)。 */
+  isActive(name) {
+    const s = this.byName.get(name)
+    return !!s && (s.armed || s.busy || s.grace > 0)
+  }
+
+  forget(name) {
+    this.byName.delete(name)
+  }
+}

package/src/state.mjs

@@ -46,11 +46,13 @@ export function invalidateSessionCache(sessionName) {
     _captureCache.clear()
     _cwdCache.clear()
     _statusGate.clear()
+    _spinnerFreezeByName.clear()
     return
   }
   _captureCache.delete(sessionName)
   _cwdCache.delete(sessionName)
   _statusGate.delete(sessionName)
+  _spinnerFreezeByName.delete(sessionName)
 }
 
 /**
@@ -185,6 +187,15 @@ function _belowIsOnlyChrome(lines, i) {
  * ペイン最下部の入力欄直上にあるライブのスピナーだけを生成中と判定する (誤点灯防止)。
  */
 function detectWorkingSpinner(text) {
+  return workingSpinnerLine(text) !== null
+}
+
+/**
+ * 作業スピナー行そのもの (経過タイマー込み) を返す。検出ロジックは detectWorkingSpinner と
+ * 同一だが、frozen 判定 (下記) でライブタイマーの変化を見るために行文字列を取り出す。
+ * 見つからなければ null。
+ */
+function workingSpinnerLine(text) {
   const lines = text.split("\n")
   const start = Math.max(0, lines.length - 12)
   for (let i = lines.length - 1; i >= start; i--) {
@@ -192,9 +203,50 @@ function detectWorkingSpinner(text) {
     const isSpinner = SPINNER_LINE_RE.test(line)
     const isTokenFooter =
       /\btokens\b/i.test(line) && /(?:^|[\s(])\d+\s*s\b/.test(line)
-    if ((isSpinner || isTokenFooter) && _belowIsOnlyChrome(lines, i)) return true
+    if ((isSpinner || isTokenFooter) && _belowIsOnlyChrome(lines, i)) {
+      return line.trim()
+    }
   }
-  return false
+  return null
+}
+
+/**
+ * 「スピナーは画面に在るが、アニメ (経過タイマー) が止まっている = 凍結」を検出する。
+ *
+ * claude が異常終了 / ハングするとスピナー行が経過タイマー付きで画面に残るが、タイマーは
+ * 進まない。capture-pane の単フレーム判定 (detectWorkingSpinner) はこれを「生成中」と誤読し、
+ * 三点リーダーが永久に消えない (ユーザー報告の主症状の一つ)。プロセス内省は claude 自体が
+ * 死んでいると ready を出せない (子プロセスも無いが arm もされない) ため、この frozen 判定が
+ * 画面側の最後の保険になる。
+ *
+ * ライブのスピナーはタイマーが毎秒進むため、state loop の各 tick (5s 間隔・capture は都度
+ * 新規) では必ず行文字列が変化する。よって「同一スピナー行が SPINNER_FREEZE_CONFIRM_MS 以上
+ * 不変」なら凍結とみなす。閾値は capture キャッシュ TTL (2.5s) と state loop 周期 (5s) を跨ぐ
+ * 6s に取り、ライブタイマーの 1 サンプル取りこぼしでは誤判定しないようにする。
+ */
+const SPINNER_FREEZE_CONFIRM_MS = Number(
+  process.env.HUB_AGENT_SPINNER_FREEZE_MS ?? 6000,
+)
+/** @type {Map<string, {line: string, at: number}>} session名 → 最初にその行を見た時刻 */
+const _spinnerFreezeByName = new Map()
+
+export function isSpinnerFrozen(sessionName, text, now = Date.now()) {
+  const line = workingSpinnerLine(text)
+  if (!line) {
+    _spinnerFreezeByName.delete(sessionName)
+    return false
+  }
+  const prev = _spinnerFreezeByName.get(sessionName)
+  if (!prev || prev.line !== line) {
+    _spinnerFreezeByName.set(sessionName, { line, at: now })
+    return false
+  }
+  return now - prev.at >= SPINNER_FREEZE_CONFIRM_MS
+}
+
+/** テスト用: 凍結判定の状態を空にする。 */
+export function _resetSpinnerFreeze() {
+  _spinnerFreezeByName.clear()
 }
 
 export function detectStatusFromText(text) {
@@ -479,7 +531,7 @@ const _stabilityByName = new Map() // session_name → { sig, since }
 
 /** ペインの出力領域 (入力欄・揮発フッターを除いた上側) の軽量シグネチャ (FNV-1a 32bit)。
  *  末尾 8 行 (入力欄 + スピナー経過秒/ヒント等) を除くので、idle 中は連続 capture が一致する。 */
-function _outputSignature(text) {
+export function _outputSignature(text) {
   const lines = text.split("\n")
   const body = lines.slice(0, Math.max(0, lines.length - 8)).join("\n")
   let h = 0x811c9dc5
@@ -515,7 +567,18 @@ function _computeStable(sessionName, status, text) {
 
 export async function detectSessionState(sessionName, opts = {}) {
   const text = await capturePane(sessionName, opts)
-  const defaultStatus = detectStatusFromText(text)
+  let defaultStatus = detectStatusFromText(text)
+  // 凍結スピナー対策: スピナーが画面に在るが経過タイマーが進んでいない (claude 異常終了/ハング)
+  // 場合、生成中ではないので processing を取り下げる。"esc to interrupt" がある間は別のライブ
+  // シグナルなので対象外。frozen と判定したらスピナーを無視した素の判定 (❯→waiting / else idle)。
+  if (
+    defaultStatus === "processing" &&
+    !/esc to interrupt/i.test(text) &&
+    isSpinnerFrozen(sessionName, text)
+  ) {
+    defaultStatus =
+      /❯\s/.test(text) || /^>\s/m.test(text) ? "waiting" : "idle"
+  }
   const defaultContextPct = detectContextPctFromText(text)
   const defaultPermissionMode = detectPermissionModeFromText(text)
 
@@ -537,6 +600,10 @@ export async function detectSessionState(sessionName, opts = {}) {
         permission_mode:
           hookResult.result.permission_mode ?? defaultPermissionMode,
         stable: _computeStable(sessionName, status, text),
+        // 出力領域 (揮発フッター除外) の署名。state loop が tick 間で比較し、純テキスト
+        // 生成 (子プロセスを spawn しないため proc 内省が busy=false と見るケース) を
+        // 「出力フロー中=busy」として検出するのに使う。
+        output_sig: _outputSignature(text),
       }
     }
   }
@@ -547,6 +614,7 @@ export async function detectSessionState(sessionName, opts = {}) {
     context_pct: defaultContextPct,
     permission_mode: defaultPermissionMode,
     stable: _computeStable(sessionName, status, text),
+    output_sig: _outputSignature(text),
   }
 }