@cocorograph/hub-agent 0.8.23 → 0.8.25

package/README.md

@@ -62,9 +62,7 @@ hub-agent stop                        # 停止方法のヒント表示
 hub-agent install-service [--bin PATH]
 hub-agent uninstall-service
 hub-agent plugins list                # ~/.hub/plugins/ から読み込み済プラグイン
-hub-agent plugins examples            # repo 同梱の install 可能 example
-hub-agent plugins install <name> [--force]
-hub-agent plugins uninstall <name>
+hub-agent plugins uninstall <name>    # ~/.hub/plugins/<prio>-<name>/ を削除
 ```
 
 ## 設定ファイル
@@ -86,7 +84,8 @@ hub-agent/
 │   ├── config.mjs             # ~/.hub/agent.json 管理
 │   ├── enroll.mjs             # enrollment フロー
 │   ├── ws-client.mjs          # outbound WSS + reconnect with jitter
-│   ├── pty-bridge.mjs         # @lydell/node-pty 多重化 (fd leak 回避フォーク)
+│   ├── claude-stream-bridge.mjs # Claude Agent SDK チャット中継
+│   ├── codex-stream-bridge.mjs  # Codex app-server チャット中継
 │   ├── tmux.mjs               # tmux exec/list/create/kill
 │   ├── state.mjs              # session status / context_pct 検知
 │   ├── skills.mjs             # ~/.claude/skills 集計
@@ -98,7 +97,8 @@ hub-agent/
 │   ├── co.cocorograph.hub-agent.plist
 │   └── hub-agent.service
 ├── scripts/
-│   └── fix-node-pty-perms.mjs # @lydell/node-pty spawn-helper +x 修復 (postinstall)
+│   ├── install.sh             # ワンライナーセットアップ (macOS / Linux / WSL)
+│   └── install.ps1            # Windows (WSL2 導入 + Task Scheduler 登録)
 └── test/
 ```
 
@@ -107,21 +107,22 @@ hub-agent/
 - [x] Sprint A: 仕様書 (Hub knowledge id=6080)
 - [x] Sprint B: Hub 側 enrollment API + WS endpoint 雛形
 - [x] Sprint C: 本リポジトリの雛形 + outbound WSS + hook system
-- [x] Sprint D: pty bridge
 - [x] Sprint E: tmux exec/list/create/kill 移植 + auto list UI
 - [x] Sprint F: Hub Browser↔Agent multiplex 中継
 - [x] Sprint G: Hub frontend /user/cockpit/{agents,terminal} ページ
 - [x] Sprint H: skills / state dot / usage badge リレー
 - [x] Sprint I: 接続復旧 (jitter + force reconnect + Celery stale 検知)
 - [x] Sprint J: 本リポジトリ publish 準備 + launchd/systemd 連携
-- [x] Sprint K: remote-ops プラグイン例 (`plugins/10-tailscale-remote/`)
 
-## 同梱プラグイン
+## プラグイン
 
-- [`plugins/10-tailscale-remote`](./plugins/10-tailscale-remote/README.md) — 自宅
-  Mac (hub-agent host) を会社 Mac (`remote_host`) の tmux に対する透過プロキシ化。
-  `hub-agent plugins install 10-tailscale-remote` で `~/.hub/plugins/` にコピー、
-  `config.json` を編集して restart で有効化
+プラグインは利用者が `~/.hub/plugins/<prio>-<name>/plugin.mjs` を自分で置く運用です。
+置けば `plugins list` から読み込まれ、`plugins uninstall <prio>-<name>` で削除できます。
+
+リポジトリ同梱の example プラグインはありません。唯一同梱していた
+`plugins/10-tailscale-remote/` は pty spawn を横取りするプラグインで、pty 中継の撤去と
+同時に削除しました。同梱 example が 0 件になったため、それを配る `plugins examples` /
+`plugins install` と `package.json` の `files` の `plugins/` も外しています。
 
 ## ライセンス
 

package/bin/hub-agent.mjs

@@ -34,12 +34,8 @@ if (!process.env.LC_ALL) process.env.LC_ALL = "C.UTF-8"
 import { hasConfig, readConfig } from "../src/config.mjs"
 import { enroll } from "../src/enroll.mjs"
 import { resolveSyncTargets, syncBundleTargets } from "../src/hub-bundle.mjs"
-import {
-  installPlugin,
-  listInstallableExamples,
-  uninstallPlugin,
-} from "../src/plugin-install.mjs"
 import { loadPlugins } from "../src/plugin-loader.mjs"
+import { uninstallPlugin } from "../src/plugin-uninstall.mjs"
 import {
   installService,
   restartService,
@@ -264,6 +260,11 @@ program
     }
   })
 
+// プラグインは利用者が `~/.hub/plugins/<prio>-<name>/` へ自分で配置する運用なので、
+// CLI が提供するのは利用者配置分の管理 (list / uninstall) だけ。リポ同梱 example を配る
+// `examples` / `install` は、唯一の example (`plugins/10-tailscale-remote/`) が pty spawn を
+// 横取りするプラグインで pty 撤去と同時に削除され、同梱 example が 0 件になったため撤去した
+// (あわせて package.json の files から `plugins/` を外している)。
 const plugins = program.command("plugins").description("プラグイン管理")
 plugins
   .command("list")
@@ -279,40 +280,9 @@ plugins
     }
   })
 
-plugins
-  .command("examples")
-  .description("リポ同梱の install 可能 example プラグイン一覧")
-  .action(async () => {
-    const list = await listInstallableExamples()
-    if (list.length === 0) {
-      console.log("(no examples bundled)")
-      return
-    }
-    for (const name of list) {
-      console.log(`- ${name}`)
-    }
-  })
-
-plugins
-  .command("install <name>")
-  .description("repo plugins/<name>/ を ~/.hub/plugins/<name>/ にコピー (config.json は温存)")
-  .option("--force", "既存ディレクトリを上書きする")
-  .action(async (name, opts) => {
-    try {
-      const r = await installPlugin(name, { force: !!opts.force })
-      console.log(`installed: ${r.dest}`)
-      console.log("次のステップ:")
-      console.log(`  $EDITOR ${r.dest}/config.json    # 既存なら温存、新規なら example をコピー`)
-      console.log(`  hub-agent restart (launchctl kickstart / systemctl restart)`)
-    } catch (err) {
-      console.error(`plugins install failed: ${err.message}`)
-      process.exit(1)
-    }
-  })
-
 plugins
   .command("uninstall <name>")
-  .description("~/.hub/plugins/<name>/ を削除")
+  .description("~/.hub/plugins/<prio>-<name>/ を削除する")
   .action(async (name) => {
     try {
       const r = await uninstallPlugin(name)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cocorograph/hub-agent",
-  "version": "0.8.23",
-  "description": "Hub Hosted Cockpit のローカル常駐 agent。Hub と outbound WSS で接続し、ローカルの tmux/pty を中継する。",
+  "version": "0.8.25",
+  "description": "Hub Hosted Cockpit のローカル常駐 agent。Hub と outbound WSS で接続し、ローカルの Claude / Codex チャットと tmux セッションを中継する。",
   "type": "module",
   "license": "UNLICENSED",
   "private": false,
@@ -19,7 +19,6 @@
   "scripts": {
     "start": "node bin/hub-agent.mjs start",
     "test": "node --test test/*.test.mjs",
-    "postinstall": "node scripts/fix-node-pty-perms.mjs",
     "check:publish-on-main": "node scripts/check-publish-on-main.mjs",
     "prepublishOnly": "node scripts/check-publish-on-main.mjs && npm test"
   },
@@ -28,13 +27,11 @@
     "src/",
     "scripts/",
     "templates/",
-    "plugins/",
     "README.md",
     "LICENSE"
   ],
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.158",
-    "@lydell/node-pty": "1.2.0-beta.12",
     "commander": "^12.1.0",
     "pino": "^9.0.0",
     "ws": "^8.18.0"

package/scripts/install.sh

@@ -518,10 +518,10 @@ _install_node_lts_linux() {
 }
 
 # ネイティブアドオンのビルドに必要な make / g++ / python3 を導入する。
-# PTY backend は @lydell/node-pty に移行済みで全 OS の prebuild を同梱するため通常は
-# native ビルド不要だが、prebuild が当たらない環境では node-gyp rebuild に
-# フォールバックする。クリーンな Ubuntu には build-essential が無く
-# `gyp ERR! not found: make` で失敗する (WSL クリーン Ubuntu で発覚) ため保険で導入する。
+# 現在の依存はすべて純 JS で通常は native ビルド不要だが、optional な native 依存
+# (ws の bufferutil 等) が prebuild なしで拾われると node-gyp rebuild にフォールバック
+# する。クリーンな Ubuntu には build-essential が無く `gyp ERR! not found: make` で
+# 失敗する (WSL クリーン Ubuntu で発覚) ため保険で導入する。
 # macOS は Xcode CLT 前提なので何もしない。
 ensure_build_tools() {
   [[ "$(uname)" == "Darwin" ]] && return 0
@@ -812,7 +812,7 @@ macos_perm_guidance() {
   cat <<EOF
 
 📣 macOS の権限ダイアログについて
-  hub-agent は tmux/pty を中継するため、初回起動時に macOS から
+  hub-agent は tmux セッションとローカルの CLI (Claude / Codex) を中継するため、初回起動時に macOS から
   「node がローカルネットワーク上の機器を検出することを求めています」
   「node がアクセシビリティを制御することを求めています」
   「node がほかのアプリからのデータへのアクセス権を求めています」

package/src/claude-stream-bridge.mjs

@@ -15,8 +15,7 @@
  * - これは Claude CLI の `claude --resume <id> -p "<msg>"` を毎ターン叩くのと同じ
  *   モデルで、SDK の挙動と素直に噛み合う
  *
- * PtyBridge と並走させる設計。`pty.*` 系メッセージは無傷で、新規 `claude.*` のみ
- * 受け持つ。テスト時は SDK を `{ query }` shape で stub 注入する。
+ * `claude.*` 系メッセージを受け持つ。テスト時は SDK を `{ query }` shape で stub 注入する。
  */
 import { EventEmitter } from "node:events"
 import { randomUUID } from "node:crypto"
@@ -33,6 +32,8 @@ import {
 } from "./tool-result-mask.mjs"
 import { getOrCreateSiblingToken } from "./sibling-token.mjs"
 import { recordInjectSourcePersistent } from "./inject-source-store.mjs"
+import { readPositiveIntEnv, sanitizePositiveInt } from "./positive-int-env.mjs"
+import { nextSessionSeq } from "./session-seq.mjs"
 
 /**
  * sibling-inject (2026-07-04) 用: spawn する claude プロセス自身の環境変数に、
@@ -181,20 +182,87 @@ function readNeedsAuthCacheNames() {
  *  sessions に stream_id が永久残留し、最後の 1 台が外れないと idle softDetach が起動しない。
  *  正常に開いている端末は input が無くても WS heartbeat 等で活性更新されないため、閾値は
  *  長め (既定 1 時間) にして「明らかに死んだ」端末のみを掃除する。env で調整可能。 */
-const DEAD_TERMINAL_TTL_MS =
-  Number(process.env.HUB_AGENT_DEAD_TERMINAL_TTL_MS) || 60 * 60 * 1000
+const DEAD_TERMINAL_TTL_MS = readPositiveIntEnv(
+  "HUB_AGENT_DEAD_TERMINAL_TTL_MS",
+  60 * 60 * 1000,
+)
 
-/** 子⑤ (T06544): warm 保持を「各 cwd 1 本 × 同時 warm 保持する cwd 数 N（既定 20）」で有界化する
+/** 子⑤ (T06544): warm 保持を「各 cwd K 本 × 同時 warm 保持する cwd 数 N（既定 20）」で有界化する
  *  上限（codex-stream-bridge.mjs の WARM_CWD_MAX と対）。claude は従来 per-session の softDetach
  *  タイマー（7 日）だけで件数上限が無かったため、多数の cwd を渡り歩くと warm セッション（= SDK
  *  常駐 query プロセス）が N 個を超えて蓄積し得た。cwd 単位の LRU で最古 cwd から早期 reap する。
  *  env HUB_AGENT_WARM_CWD_MAX で調整可能（codex と共有）。 */
-const WARM_CWD_MAX = Number(process.env.HUB_AGENT_WARM_CWD_MAX) || 20
+const WARM_CWD_MAX = readPositiveIntEnv("HUB_AGENT_WARM_CWD_MAX", 20)
+
+/** 1 cwd あたりの live セッション上限 K（既定 3）。旧仕様の per-cwd=1 を一般化したもの。
+ *  「総量は増やさず配分の自由度だけ上げる」ため、総 live 上限 M（warm-bounds-total.mjs）と
+ *  セットで効かせる。⚠️ 既存 env（HUB_AGENT_WARM_CWD_MAX = 同時 warm 保持する cwd 数 N）の
+ *  意味は変えない。新しい上限は新しい env 名で足す（codex 側の WARM_PER_CWD_MAX と対）。 */
+const WARM_PER_CWD_MAX = readPositiveIntEnv("HUB_AGENT_WARM_PER_CWD_MAX", 3)
+
+/** タスク実行中セッションを warm 境界の刈り取りから保護する際の**失効時間**（**鼓動が観測できる
+ *  種別**用。既定 30 分）。「最後に生存を確認してから」の相対時間で、`task_progress` が届くたびに
+ *  先送りされる。実測（/tmp/bgprobe/raw2.jsonl）で `local_agent`（Agent ツールのサブエージェント）
+ *  は task_progress の鼓動が届くため、この短い TTL で十分に走行中を守れる。
+ *  ⚠️ これは**仕様上の最大保護時間**であり、これを超えて鼓動が途絶えたタスクは保護されない
+ *  （終了イベントを取りこぼしたときに保護が永久化しないための上限として必須）。 */
+const TASK_PROTECT_TTL_MS = readPositiveIntEnv(
+  "HUB_AGENT_TASK_PROTECT_TTL_MS",
+  30 * 60 * 1000,
+)
 
-/** 子⑤ (T06544, codex-review round5 Finding 1): warm 境界の「最新 1 本を残す」判定で recency が
- *  同一ミリ秒になったときのタイブレーク用の単調増加シーケンス（codex 側 CODEX_SESSION_SEQ と対）。
- *  生成順が後 = 値が大きい = 新しいので、per-cwd=1 のタイでは必ず新しいセッションを残す。 */
-let CLAUDE_SESSION_SEQ = 0
+/** **鼓動が来ない種別**（`local_bash` = run_in_background の Bash、および未知の task_type）用の
+ *  失効時間（既定 4 時間）。
+ *
+ *  【なぜ分けるか】実測で `local_bash` は task_progress が **1 件も来ない**（40 秒でも 240 秒でも
+ *  0 件。/tmp/bgprobe/raw2.jsonl, raw4.jsonl）。全種別を共通 TTL にすると lastSeenAt が開始時刻から
+ *  動かず、実質「開始から 30 分」になり、**30 分を超える正常な背景コマンド（ビルド・同期・
+ *  サーバー等）が実行中なのに保護を失う**。終了イベント（task_updated / task_notification）は
+ *  240 秒後でも確実に届くことを実測済みなので、TTL を延ばしても通常は終了で解ける。
+ *
+ *  【未知の task_type もこちら】鼓動が来るか分からないものを短い TTL で切ると実行中を刈る。
+ *  「未知の status を終端扱いしない」（TASK_TERMINAL_STATUSES）と同じく安全側へ倒す。
+ *
+ *  ⚠️ これも**仕様上の最大保護時間**で、**4 時間を超える背景コマンドは保護されない**。
+ *
+ *  【有界なのは「時間」だけで、「件数」ではない】(cross-review round2 minor)
+ *  1 エントリあたりの保護時間は TTL で有界（4 時間で必ず頭打ち）。一方で **同時に保護されうる
+ *  セッション数には K（per-cwd）も N（cwd 数）も M（総 live 上限、warm-bounds-total.mjs）も効かない**。
+ *  すべての境界が protected を skip する設計なので、4 時間以内に別セッションで背景コマンドを
+ *  増やせば、保護中の合計は M を超えて増え続ける。これは「走行中を絶対に殺さない」を優先した
+ *  **明示的な超過受容**であり、**M をハードな資源上限と読んではいけない**。
+ *  超過量は warm-bounds-total.mjs が返す `liveTotal` / `unresolved` のログで観測できる
+ *  （運用判断はその実測値を見る）。
+ *
+ *  ⚠️ 将来ハード上限（保護中でも刈る）を足すなら、**実行中タスクを中断するという新しい失敗モード**
+ *  が生まれる。この TTL 設計の延長で暗黙に足さないこと。足すなら victim の選び方・利用者への通知・
+ *  再開可否を別仕様として設計する。 */
+const BG_COMMAND_PROTECT_TTL_MS = readPositiveIntEnv(
+  "HUB_AGENT_BG_COMMAND_PROTECT_TTL_MS",
+  4 * 60 * 60 * 1000,
+)
+
+/** `task_progress` の鼓動が届くと**実測で確認済み**の task_type。ここに無い種別（`local_bash` /
+ *  未知）は鼓動が来ない前提で長い TTL（BG_COMMAND_PROTECT_TTL_MS）を適用する。 */
+const HEARTBEAT_TASK_TYPES = new Set(["local_agent"])
+
+/** task_type に応じた保護の失効時間を返す。未知の種別は**長い方**（安全側）。 */
+function taskProtectTtlFor(taskType) {
+  return HEARTBEAT_TASK_TYPES.has(taskType) ? TASK_PROTECT_TTL_MS : BG_COMMAND_PROTECT_TTL_MS
+}
+
+/** SDK の `system:task_updated` が patch.status に載せる**終端**ステータス。
+ *  出典: node_modules/@anthropic-ai/claude-agent-sdk/sdk.d.ts の `SDKTaskUpdatedMessage`
+ *  （`status?: 'pending' | 'running' | 'completed' | 'failed' | 'killed' | 'paused'`, sdk.d.ts:4101）。
+ *  ⚠️ `paused` は終端に含めない（再開しうるため）。ここに載っていない未知の値は「まだ走行中かも
+ *  しれない」とみなして保護を解除しない（未知の状態を勝手に終端扱いして走行中タスクを刈らない
+ *  ため。保護の上限は失効時間が保証する）。
+ *  ⚠️ SDK 更新で union が変わったら test/claude-task-status-drift.test.mjs が落ちる。 */
+export const TASK_TERMINAL_STATUSES = new Set(["completed", "failed", "killed"])
+
+/** 上と対になる**非終端**ステータス（同じ union の残り全部）。分類の網羅性をテストで検査するために
+ *  明示的に持つ（SDK に未知の値が増えたら「どちらでもない」ものとして検出できる）。 */
+export const TASK_NONTERMINAL_STATUSES = new Set(["pending", "running", "paused"])
 
 /**
  * モデル能力レジストリ (2026-07-11): モデル名 → { supportsEffort, supportsXhighEffort }。
@@ -391,8 +459,10 @@ export class ClaudeStreamSession {
      *  使った時刻」が残り、最古 cwd から LRU reap できる。 */
     this._lastActivityMs = Date.now()
     /** 子⑤ round5 Finding 1: 生成順の単調増加シーケンス（warm 境界のタイブレーク用。値が大きい =
-     *  新しい）。recency 同値時に per-cwd=1 が新しいセッションを残せるようにする。 */
-    this._seq = CLAUDE_SESSION_SEQ += 1
+     *  新しい）。recency 同値時に per-cwd=K が新しいセッションを残せるようにする。
+     *  ⚠️ カウンタは **claude / codex 共通**（session-seq.mjs）。総 live 上限 M は両 CLI を合算して
+     *  古い順に刈るため、CLI ごとに別カウンタだと CLI をまたいだ比較が成立しない。 */
+    this._seq = nextSessionSeq()
     this.cwd = cwd
     this.model = model || null
     this.permissionMode = permissionMode || null
@@ -496,6 +566,20 @@ export class ClaudeStreamSession {
      *  本文一致で _emit が消費してタグ付けする。人間の実入力や tool_result は本 set に無いので
      *  タグされない (誤タグ防止)。echo が来ない稀ケースの無限成長は上限で古い順に切る。 */
     this._pendingInjectSources = []
+
+    /** 走行中タスク（Agent ツールのサブエージェント / 背景 Bash コマンド）の台帳。
+     *  key = SDK の `task_id`、value = { toolUseId, taskType, startedAt, lastSeenAt }。
+     *
+     *  ⚠️ key を `tool_use_id` にしてはいけない: 終了イベントの片方（`system:task_updated`）は
+     *  `tool_use_id` を持たず `task_id` しか載せないため、tool_use_id を鍵にすると終了を
+     *  取りこぼして保護が居座る（実測ログ /tmp/bgprobe/raw2.jsonl で確認）。
+     *
+     *  ⚠️ 前面 / 背景を区別しない（確定した設計判断）。前面実行中はそもそも `_busy` で保護される
+     *  ので区別しても挙動は変わらず、区別するには tool_use の `run_in_background` と突き合わせる
+     *  第 2 の仕組みが要る。一方、背景コマンドの終了イベントは**ターン終了後**に届く（実測:
+     *  `result` の 14 秒後）ため、背景は保護対象に含める必要がある。 */
+    this._liveTasks = new Map()
+
     /** ultracode (0.6.28): 常駐 query へ現在適用済みの ultracode 状態。ターン単位の
      *  ワンショット適用を applyFlagSettings で reconcile する際の差分判定に使う。
      *  query を (再)起動すると flag settings は既定に戻るため、_runResidentQuery 冒頭で
@@ -620,7 +704,109 @@ export class ClaudeStreamSession {
     if (idx !== -1) this._pendingInjectSources.splice(idx, 1)
   }
 
+  /**
+   * SDK の `system:task_*` を観測して走行中タスク台帳（_liveTasks）を更新する。
+   *
+   * 呼び出しは `_emit` の先頭 1 箇所だけ。常駐ループ・per-message ループ・jsonl watcher の
+   * 3 経路が必ず `_emit` を通るため、ここが唯一の合流点になる（経路ごとに配線すると、
+   * どれか 1 本を足したときに無言で観測漏れする）。
+   *
+   * 実測（/tmp/bgprobe/raw2.jsonl, raw3.jsonl）に基づく扱い:
+   *   - `task_started`      : 新規登録（前面 / 背景の両方が出す）
+   *   - `task_progress`     : **既存エントリがあるときだけ** lastSeenAt を延ばす。エントリが
+   *                           無ければ新規作成しない（終了後に遅れて届いた進捗でよみがえるのを
+   *                           防ぐ）。⚠️ ここは「安全側」ではない（cross-review round2 nit）:
+   *                           開始イベント（task_started）を本当に取りこぼしていた場合、実行中
+   *                           なのに保護が付かず reap されうる。**過剰保護と終了後の復活を避ける
+   *                           ため、旧挙動（保護しない）へ fail-open している**というトレードオフ。
+   *                           ⚠️ この記述を根拠に「未知の progress から新規登録する」実装へ
+   *                           変えないこと。それをやると遅延イベントで保護が復活する。
+   *   - `task_updated`      : patch.status が終端なら削除。**未知の値なら削除せず lastSeenAt 更新**
+   *   - `task_notification` : status によらず削除（冪等。同一 task_id が複数回来ても壊れない）
+   *
+   * ⚠️ 例外を外へ投げないこと。`_emit` は全メッセージが通る経路なので、ここで throw すると
+   *    ストリーム全体が壊れる。すべて握って logger?.warn に留める。
+   * @param {object} msg SDK メッセージ
+   * @param {number} [now] 時刻（テストから注入可能）
+   */
+  _observeTaskEvent(msg, now = Date.now()) {
+    try {
+      if (!msg || msg.type !== "system") return
+      const subtype = msg.subtype
+      if (
+        subtype !== "task_started" &&
+        subtype !== "task_progress" &&
+        subtype !== "task_updated" &&
+        subtype !== "task_notification"
+      ) {
+        return
+      }
+      const taskId = msg.task_id
+      if (typeof taskId !== "string" || !taskId) return
+      if (subtype === "task_started") {
+        this._liveTasks.set(taskId, {
+          toolUseId: typeof msg.tool_use_id === "string" ? msg.tool_use_id : null,
+          taskType: typeof msg.task_type === "string" ? msg.task_type : null,
+          startedAt: now,
+          lastSeenAt: now,
+        })
+        return
+      }
+      if (subtype === "task_notification") {
+        this._liveTasks.delete(taskId)
+        return
+      }
+      if (subtype === "task_updated") {
+        const status = msg.patch?.status
+        if (typeof status === "string" && TASK_TERMINAL_STATUSES.has(status)) {
+          this._liveTasks.delete(taskId)
+          return
+        }
+        // 未知 / 非終端の status: 走行中とみなして生存を更新する（失効時間が上限を保証する）。
+        const entry = this._liveTasks.get(taskId)
+        if (entry) entry.lastSeenAt = now
+        return
+      }
+      // task_progress: 生存の鼓動。既存エントリのみ延命する（新規作成はしない）。
+      const entry = this._liveTasks.get(taskId)
+      if (entry) entry.lastSeenAt = now
+    } catch (err) {
+      this.logger?.warn(
+        { err: err?.message, stream_id: this.stream_id },
+        "observe task event threw",
+      )
+    }
+  }
+
+  /** 走行中タスクを持つか（warm 境界の保護判定用）。失効したエントリを掃除してから判定する。
+   *  失効は「最後に生存を確認してから」の相対時間で、**task_type ごとに TTL が違う**
+   *  （鼓動が来る local_agent は 30 分 / 鼓動が来ない local_bash・未知は 4 時間）。
+   *  ⚠️ 失効させて保護を落とす = そのセッションは kill されうる、という意味なので、**必ず warn を
+   *  残す**（黙って kill 可能にしない。後から「なぜ実行中に畳まれたのか」を追えるようにする）。 */
+  _hasLiveTask(now = Date.now()) {
+    if (!this._liveTasks || this._liveTasks.size === 0) return false
+    for (const [taskId, entry] of this._liveTasks) {
+      const ttl = taskProtectTtlFor(entry?.taskType)
+      const elapsed = now - (entry?.lastSeenAt ?? 0)
+      if (elapsed <= ttl) continue
+      this._liveTasks.delete(taskId)
+      this.logger?.warn?.(
+        {
+          stream_id: this.stream_id,
+          task_id: taskId,
+          task_type: entry?.taskType ?? null,
+          elapsed_s: Math.round(elapsed / 1000),
+          ttl_ms: ttl,
+        },
+        "task protection expired (session is reapable again; a still-running task would be killed)",
+      )
+    }
+    return this._liveTasks.size > 0
+  }
+
   _emit(event) {
+    // 走行中タスクの観測は全経路の合流点であるここで 1 回だけ行う（例外は内部で握る）。
+    this._observeTaskEvent(event)
     if (!this.onEvent) return
     let out = event
     if (MASK_ENABLED) {
@@ -2240,7 +2426,7 @@ export class ClaudeStreamBridge extends EventEmitter {
   /**
    * 指定 cwd / session_id に紐づく SDK セッションを**即停止**する (T04784 TUI bind 用)。
    *
-   * TUI モードに切り替えた session は対話 TUI (tmux/PTY) の claude が write を担うため、
+   * TUI モードに切り替えた session は tmux ペインの対話 claude が write を担うため、
    * SDK セッションを生かしたままだと同一 cwd の jsonl を二重ホストして競合する
    * (DESIGN.md C7)。soft-detach (7 日 resident) では止まらないので、ここで明示 close する。
    *
@@ -3353,14 +3539,26 @@ export class ClaudeStreamBridge extends EventEmitter {
    *  セッションも保護する（reap すると未処理入力が失われる）。
    *  R1(c) 多ウィンドウ相互 reap 抑止: 2 端末以上が現在ライブ購読中の多端末共有セッション
    *  (T06542) も保護する。同一 cwd で別 session_id を開いた新規 1 本を残すために、複数
-   *  ウィンドウが見ている共有セッションを per-cwd=1 / cwd-LRU が刈ってしまう事故を防ぐ
-   *  (単端末の重複セッション collapse は従来どおり働く: 単端末は count=1 で非保護)。 */
-  _isSessionProtected(session) {
+   *  ウィンドウが見ている共有セッションを per-cwd / cwd-LRU が刈ってしまう事故を防ぐ
+   *  (単端末の重複セッション collapse は従来どおり働く: 単端末は count=1 で非保護)。
+   *  タスク実行中 (_hasLiveTask) も保護する: 背景サブエージェント / 背景コマンドはターン終了後も
+   *  走り続ける（実測で終了イベントは result の 14 秒後）ため、_busy だけでは守れない。保護は
+   *  失効時間つきで、終了イベントを取りこぼしても永久化しない。
+   *  ⚠️ 旧コメントは「codex 側には対応物を置いていない（意図的な非対称）」としていたが、これは
+   *  **事実として誤り**だったので訂正する。codex-cli 0.145.0 の実測（/tmp/satoru_bgprobe/raw2.jsonl,
+   *  raw4.jsonl）では `item/started(commandExecution, status=inProgress)` → `turn/completed` の順に
+   *  届き、**turn/completed の後もそのコマンドは走り続ける**（sleep 120 で確認）。自然終了でも
+   *  `item/completed` は届く（sleep 20 の追試で turn/completed の 17 秒後）。したがって codex 側にも
+   *  対応物（`liveExecItems` 台帳 + `_hasLiveExec`）を置いた（codex-stream-bridge.mjs）。
+   *  観測は **通知の台帳**で行い、権威照会 `thread/backgroundTerminals/list` は使わない
+   *  （実験 API の有効化が要るうえ、threadId ごとの照会なので子スレッドの背景コマンドを取りこぼす）。 */
+  _isSessionProtected(session, now = Date.now()) {
     if (!session) return false
     if (session._busy) return true
     if (Array.isArray(session._pendingMessages) && session._pendingMessages.length > 0) {
       return true
     }
+    if (session._hasLiveTask?.(now)) return true
     return this._liveTerminalCount(session) >= 2
   }
 
@@ -3382,26 +3580,62 @@ export class ClaudeStreamBridge extends EventEmitter {
   }
 
   /**
-   * 子⑤ (T06544): warm 保持を「各 cwd 1 本 × 同時 warm 保持する cwd 数 N（既定 20）」で有界化する
+   * 総 live 上限 M（warm-bounds-total.mjs）用の **CLI 非依存アダプタ**。live セッションを
+   * `{ kind, cwd, recency, seq, protected, reap }` の共通形へ包んで返すだけ（新しい判断は持たない）。
+   * warm セッションは this.sessions から外れ _liveBySession に残るため union を dedup して走査する。
+   * @param {number} [now]
+   * @returns {Array<object>}
+   */
+  listWarmCandidates(now = Date.now()) {
+    const out = []
+    const seen = new Set()
+    for (const s of [...this.sessions.values(), ...this._liveBySession.values()]) {
+      if (!s || s._closed || seen.has(s)) continue
+      seen.add(s)
+      out.push({
+        kind: "claude",
+        cwd: s.cwd,
+        recency: this._sessionRecency(s),
+        seq: s._seq ?? 0,
+        protected: this._isSessionProtected(s, now),
+        reap: (reason) => this._reapForWarmBounds(s, reason),
+      })
+    }
+    return out
+  }
+
+  /**
+   * 子⑤ (T06544): warm 保持を「各 cwd K 本 × 同時 warm 保持する cwd 数 N（既定 20）」で有界化する
    * （codex-stream-bridge.mjs の `_reconcileWarmBounds` と対）。state loop から周期実行する。
-   *   Phase 1 (per-cwd=1): 同一 cwd に 2 本以上の live session があれば最終活性が最新の 1 本を残し、
-   *     残りの **非 busy** を reap する（WS 再接続は購読者追加=同一 session なので通常は発火せず、
-   *     別会話を同一 cwd で開始した等で 2 本目の SDK query ができたときだけ畳む）。
+   *   Phase 1 (per-cwd=K): 同一 cwd に K 本を超える live session があれば最終活性が新しい順に
+   *     先頭 K 本を残し、それ以降の **非 busy** を reap する（K の既定は 3。旧仕様の per-cwd=1 を
+   *     一般化したもので、1 cwd で複数会話を同時に生かすため。総量は Phase 2 と総 live 上限 M
+   *     （warm-bounds-total.mjs）で押さえる）。
    *   Phase 2 (N-cwd LRU): live session を持つ distinct cwd 数が上限を超えたら、cwd の最終活性が
    *     最も古い cwd から、その cwd の非 busy session を reap して cwd 数を上限まで戻す。
    * busy（走行中ターン）は Phase 1/2 いずれでも reap しない（完走を待つ）。warm セッションは
    * this.sessions から外れ _liveBySession に残るため、両索引の union を dedup して走査する。
-   * @param {{ maxCwds?: number, now?: number }} [opts] テストから上限/時刻を注入可能。
+   * @param {{ maxCwds?: number, maxPerCwd?: number, now?: number }} [opts] テストから上限/時刻を注入可能。
    * @returns {number} reap 数
    */
-  reconcileWarmBounds({ maxCwds = WARM_CWD_MAX, now = Date.now() } = {}) {
-    void now // recency 比較は相対値のため now は将来の拡張用（署名の対称性維持）。
+  reconcileWarmBounds({ maxCwds, maxPerCwd, now = Date.now() } = {}) {
+    // ⚠️ 上限は **正の整数**でなければならない。1.5 のような値が for の開始添字に入ると、
+    //    undefined の reap が no-op なのに reaped だけ加算され「畳んでいないのに畳んだと報告する」。
+    //    不正値は既定へ戻して warn（黙って floor しない。positive-int-env.mjs 参照）。
+    const cwdLimit = sanitizePositiveInt(maxCwds, WARM_CWD_MAX, {
+      logger: this.logger,
+      label: "claude.warmBounds.maxCwds",
+    })
+    const keepPerCwd = sanitizePositiveInt(maxPerCwd, WARM_PER_CWD_MAX, {
+      logger: this.logger,
+      label: "claude.warmBounds.maxPerCwd",
+    })
     const liveSessions = () =>
       Array.from(new Set([...this.sessions.values(), ...this._liveBySession.values()])).filter(
         (s) => s && !s._closed,
       )
     let reaped = 0
-    // Phase 1: per-cwd=1。cwd ごとに最終活性が新しい順へ並べ、先頭（最新）以外の非 busy を reap。
+    // Phase 1: per-cwd=K。cwd ごとに最終活性が新しい順へ並べ、先頭 K 本以外の非 busy を reap。
     const byCwd = new Map()
     for (const s of liveSessions()) {
       const list = byCwd.get(s.cwd)
@@ -3409,14 +3643,14 @@ export class ClaudeStreamBridge extends EventEmitter {
       else byCwd.set(s.cwd, [s])
     }
     for (const list of byCwd.values()) {
-      if (list.length <= 1) continue
+      if (list.length <= keepPerCwd) continue
       // 新しい順。recency 同値は _seq（生成順）で必ず新しい方を先頭（= 残す）にする（round5 Finding 1）。
       list.sort(
         (a, b) =>
           this._sessionRecency(b) - this._sessionRecency(a) || (b._seq ?? 0) - (a._seq ?? 0),
       )
-      for (let i = 1; i < list.length; i += 1) {
-        if (this._isSessionProtected(list[i])) continue // 走行中/pending は不可侵（一時的に >1 を許容）
+      for (let i = keepPerCwd; i < list.length; i += 1) {
+        if (this._isSessionProtected(list[i], now)) continue // 走行中/pending/タスク実行中は不可侵（一時的に >K を許容）
         this._reapForWarmBounds(list[i], "warm-bounds:per-cwd")
         reaped += 1
       }
@@ -3432,10 +3666,10 @@ export class ClaudeStreamBridge extends EventEmitter {
       const r = this._sessionRecency(s)
       if (r > info.recency) info.recency = r
       if ((s._seq ?? 0) > info.seq) info.seq = s._seq ?? 0 // round5 Finding 1: cwd タイブレーク用
-      if (this._isSessionProtected(s)) info.hasProtected = true
+      if (this._isSessionProtected(s, now)) info.hasProtected = true
       info.sessions.push(s)
     }
-    const overflow = cwdInfo.size - maxCwds
+    const overflow = cwdInfo.size - cwdLimit
     if (overflow > 0) {
       // protected（走行中/pending）を含む cwd は退避対象外（上限にカウントはするが reap しない）。
       // 最古 recency の cwd から。recency 同値は seq（新しさ）で必ず新しい cwd を残す。
@@ -3446,7 +3680,7 @@ export class ClaudeStreamBridge extends EventEmitter {
       for (const info of evictableCwds) {
         if (cwdsEvicted >= overflow) break
         for (const s of info.sessions) {
-          if (this._isSessionProtected(s)) continue
+          if (this._isSessionProtected(s, now)) continue
           this._reapForWarmBounds(s, "warm-bounds:cwd-lru")
           reaped += 1
         }