@cocorograph/hub-agent 0.8.23 → 0.8.25

package/src/codex-stream-bridge.mjs

@@ -11,7 +11,7 @@
  *   claude.input              → input()    (idle は turn/start、生成中は次ターン FIFO)
  *   claude.interrupt          → interrupt() (turn/interrupt)
  *   claude.detach              → detach()   (TTL 付き graceful close)
- *   (codex 固有)               → keepalive() (閲覧中の生存シグナル。pty.resize 相当)
+ *   (codex 固有)               → keepalive() (閲覧中の生存シグナル)
  *   claude.permission.reply    → permissionReply() (client.respond/respondError)
  *   claude.event (生 SDK イベント素通し) → 'event' (生 notification 素通し、同じ思想)
  *   claude.permission.request  → 'permission' (承認/入力要求の生 method+params 素通し)
@@ -52,6 +52,8 @@ import {
   verifyCodexDeliveryAudit,
 } from "./codex-delivery-audit.mjs"
 import { getOrCreateSiblingToken } from "./sibling-token.mjs"
+import { readPositiveIntEnv, sanitizePositiveInt } from "./positive-int-env.mjs"
+import { nextSessionSeq } from "./session-seq.mjs"
 import { codexRolloutPresence, listCodexThreadsFromDisk } from "./usage.mjs"
 
 /**
@@ -92,49 +94,90 @@ function siblingEnvFor(cwd) {
 // これにより意味論は「**閲覧中＝無期限（keepalive で LRU 先頭維持）/ 直近 5 セッションは
 // detach しても 7 日 warm / 上限超過は LRU で 1 個 reap / busy は不可侵 / stuck は救済**」。
 
+// ⚠️ 以下の上限 / TTL 系 env は **すべて readPositiveIntEnv を通す**（positive-int-env.mjs）。
+// 素の `Number(env) || 既定` だと "1.5" や "Infinity" が通り、上限が for の開始添字に入ると
+// `list[1.5]` が undefined になって `_isProtected(undefined)` で TypeError になる。
+// 既定値と意味は従来のまま。不正値は既定へ戻して warn する（黙って丸めない）。
+
 // warm 保持の idle TTL（非 busy がこの時間 無活性なら reap の対象。上限内でも 7 日で頭打ち）。
-const IDLE_DETACH_TTL_MS =
-  Number(process.env.HUB_AGENT_CODEX_IDLE_DETACH_TTL_MS) || 7 * 24 * 60 * 60 * 1000
+const IDLE_DETACH_TTL_MS = readPositiveIntEnv(
+  "HUB_AGENT_CODEX_IDLE_DETACH_TTL_MS",
+  7 * 24 * 60 * 60 * 1000,
+)
 
-// 子⑤ (T06544): warm 保持の上限を「マシン全体の総セッション数」から「各 cwd 1 本 × 同時 warm
+// 子⑤ (T06544): warm 保持の上限を「マシン全体の総セッション数」から「各 cwd K 本 × 同時 warm
 // 保持する cwd 数 N」へ再定義（親 T06539「1 cwd 1 本化」に整合）。旧 WARM_POOL_MAX（総数 LRU=5）は
 // 廃止し、境界を cwd 単位で定義する。1 セッション ≈ 120-140MB（node ラッパー + 本体 + MCP 子）
 // なので既定 20 cwd（~2.4-2.8GB 上限）。端末リソースで無理なら env で下げる。
 // 後方互換: 旧 HUB_AGENT_CODEX_WARM_POOL_MAX を設定していても新 cwd 上限として解釈する。
-const WARM_CWD_MAX =
-  Number(process.env.HUB_AGENT_WARM_CWD_MAX) ||
-  Number(process.env.HUB_AGENT_CODEX_WARM_POOL_MAX) ||
-  20
-
-// 子⑤ (T06544, codex-review round5 Finding 1): warm 境界の「最新 1 本を残す」判定で recency
-// (lastActivityMs) が同一ミリ秒になったときのタイブレーク用の単調増加シーケンス。生成順が後 =
-// 値が大きい = 新しいので、per-cwd=1 のタイでは **必ず新しく attach したセッションを残す**
-// （旧実装は安定ソートの挿入順で旧セッションが残り、新規 attach が即 reap される非決定性があった）。
-let CODEX_SESSION_SEQ = 0
+const WARM_CWD_MAX = readPositiveIntEnv(
+  ["HUB_AGENT_WARM_CWD_MAX", "HUB_AGENT_CODEX_WARM_POOL_MAX"],
+  20,
+)
+
+// 1 cwd あたりの live セッション上限 K（既定 3）。旧仕様の per-cwd=1 を一般化したもので、
+// 「1 cwd で複数会話を同時に生かす」ため。総量は増やさず配分の自由度だけ上げる方針なので、
+// 総 live 上限 M（warm-bounds-total.mjs、claude と合算）とセットで効かせる。
+// ⚠️ 既存 env（HUB_AGENT_WARM_CWD_MAX / HUB_AGENT_CODEX_WARM_POOL_MAX = 同時 warm 保持する
+// cwd 数 N）の意味は変えない。新しい上限は新しい env 名で足す。
+const WARM_PER_CWD_MAX = readPositiveIntEnv("HUB_AGENT_WARM_PER_CWD_MAX", 3)
 
 // stuck turn 検出の閾値。activeTurnId が立っているのに app-server 通知がこの時間途絶えた
 // セッションは「ハングしたターン」とみなし protected から外して reap する（healthy な長ターンは
 // reasoning/output delta で都度 touch されるため該当しない）。旧 `HUB_AGENT_DEAD_TERMINAL_TTL_MS`
 // を後方互換で受ける。既定 1h。
-const STUCK_TURN_TTL_MS =
-  Number(process.env.HUB_AGENT_CODEX_STUCK_TURN_TTL_MS) ||
-  Number(process.env.HUB_AGENT_DEAD_TERMINAL_TTL_MS) ||
-  60 * 60 * 1000
+const STUCK_TURN_TTL_MS = readPositiveIntEnv(
+  ["HUB_AGENT_CODEX_STUCK_TURN_TTL_MS", "HUB_AGENT_DEAD_TERMINAL_TTL_MS"],
+  60 * 60 * 1000,
+)
 
 // 案B (T06542): 死端末 GC の TTL。多端末購読で、応答を返さなくなった（クラッシュ / タブ強制終了で
 // codex.detach を送れなかった）購読端末を購読集合から掃除する閾値。claude-stream-bridge.mjs の
 // DEAD_TERMINAL_TTL_MS（既定 1h）と同型・同既定。stuck turn TTL とは別軸（あちらはターン固着、
 // こちらは端末の無応答）だが既定は揃える。
-const DEAD_TERMINAL_TTL_MS =
-  Number(process.env.HUB_AGENT_CODEX_DEAD_TERMINAL_TTL_MS) ||
-  Number(process.env.HUB_AGENT_DEAD_TERMINAL_TTL_MS) ||
-  60 * 60 * 1000
+const DEAD_TERMINAL_TTL_MS = readPositiveIntEnv(
+  ["HUB_AGENT_CODEX_DEAD_TERMINAL_TTL_MS", "HUB_AGENT_DEAD_TERMINAL_TTL_MS"],
+  60 * 60 * 1000,
+)
+
+// 実行中の背景コマンド（commandExecution）を warm 境界の刈り取りから保護する失効時間（既定 4 時間）。
+//
+// 【なぜ必要か（旧「意図的な非対称」の訂正）】codex-cli 0.145.0 の実測
+// （/tmp/satoru_bgprobe/raw2.jsonl）で、`item/started(commandExecution, status=inProgress)` →
+// `turn/completed` の順に届いたあと **そのコマンドはまだ走っている**（sleep 120 で確認）。
+// つまり activeTurnId（= busy）だけでは実行中の背景コマンドを守れず、claude 側の _liveTasks と
+// 同型の台帳が要る。自然終了でも `item/completed` は届く（sleep 20 の追試で turn/completed の
+// 17 秒後に status=completed。/tmp/satoru_bgprobe/raw4.jsonl）ので、通常は終了で解ける。
+//
+// 【なぜ claude の local_bash と同じ長さか】codex の `item/commandExecution/outputDelta`（鼓動）は
+// **コマンド依存で来ないことがある**（出力の無いコマンドでは 1 件も来ない）。鼓動が保証されない
+// 種別は長い方に揃える、という claude 側と同じ方針。
+//
+// ⚠️ これは**仕様上の最大保護時間**であり、**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 CODEX_EXEC_PROTECT_TTL_MS = readPositiveIntEnv(
+  "HUB_AGENT_CODEX_EXEC_PROTECT_TTL_MS",
+  4 * 60 * 60 * 1000,
+)
 
 // 案B (T06542, codex-review round3 major#2): turn/start RPC 成功後に turn/started 通知が来るのを待つ
 // 上限。これを超えたら「ターンが正しく始まらなかった」とみなし、pump が待機中の queue を reject して
 // 状態を解除する（turn/started/completed/exit が来ないケースで promise が永久宙吊りになるのを防ぐ）。
-const TURN_START_TIMEOUT_MS =
-  Number(process.env.HUB_AGENT_CODEX_TURN_START_TIMEOUT_MS) || 30 * 1000
+const TURN_START_TIMEOUT_MS = readPositiveIntEnv(
+  "HUB_AGENT_CODEX_TURN_START_TIMEOUT_MS",
+  30 * 1000,
+)
 
 // browser が ack を取りこぼしても queue snapshot から受理済みと再確認できるよう、
 // 直近 input_id を bounded ring で保持する (Claude queue_state.accepted と同じ契約)。
@@ -143,8 +186,10 @@ const ACCEPTED_INPUT_ID_RING_MAX = 256
 // sibling-inject の turn RPC が成功した後、app-server が同じ userMessage を
 // item/completed で echo するまで待つ上限。RPC accepted と userMessage delivered を
 // 分離し、旧 stream / 初期化競合で rollout に残らない入力を成功扱いしない。
-const DELIVERY_ECHO_TIMEOUT_MS =
-  Number(process.env.HUB_AGENT_CODEX_DELIVERY_ECHO_TIMEOUT_MS) || 8 * 1000
+const DELIVERY_ECHO_TIMEOUT_MS = readPositiveIntEnv(
+  "HUB_AGENT_CODEX_DELIVERY_ECHO_TIMEOUT_MS",
+  8 * 1000,
+)
 
 const CLIENT_INFO = { name: "cockpit-hub-agent", title: "Cockpit", version: "1.0.0" }
 
@@ -158,9 +203,11 @@ const CLIENT_INFO = { name: "cockpit-hub-agent", title: "Cockpit", version: "1.0
 // が起きる。thread/resume 自体はモデル側の会話コンテキスト復元のため全量が必要だが、
 // **browser へ渡す表示用履歴は末尾 N ターン分に絞る** ことで断崖を回避する。上限は
 // 「item 数」と「概算バイト数」の 2 軸で、末尾から詰めてどちらか先に達したら truncated。
-const HISTORY_MAX_ITEMS = Number(process.env.HUB_AGENT_CODEX_HISTORY_MAX_ITEMS) || 200
-const HISTORY_MAX_BYTES =
-  Number(process.env.HUB_AGENT_CODEX_HISTORY_MAX_BYTES) || 1.5 * 1024 * 1024
+const HISTORY_MAX_ITEMS = readPositiveIntEnv("HUB_AGENT_CODEX_HISTORY_MAX_ITEMS", 200)
+const HISTORY_MAX_BYTES = readPositiveIntEnv(
+  "HUB_AGENT_CODEX_HISTORY_MAX_BYTES",
+  1.5 * 1024 * 1024,
+)
 
 // Slice 6: thread/resume が返す Thread.turns[].items[] を単一の時系列配列へ平坦化する。
 // turns は開始ターン順の配列、各 turn.items も時系列順のため単純結合で会話順を保てる。
@@ -318,6 +365,7 @@ export class CodexStreamBridge extends EventEmitter {
     clientFactory,
     detachTtlMs,
     warmCwdMax,
+    warmPerCwdMax,
     stuckTurnTtlMs,
     deadTerminalTtlMs,
     turnStartTimeoutMs,
@@ -337,9 +385,19 @@ export class CodexStreamBridge extends EventEmitter {
     this._clientFactory = clientFactory || ((opts) => new CodexAppServerClient(opts))
     // Stage 5: warm 保持の idle TTL（既定 7 日）。テストから短縮できるよう注入可能。
     this._detachTtlMs = detachTtlMs ?? IDLE_DETACH_TTL_MS
-    // 子⑤ (T06544): 同時 warm 保持する cwd 数の上限（既定 20）。各 cwd は 1 本に畳む。
-    // テストから小さい値を注入可能。
-    this._warmCwdMax = warmCwdMax ?? WARM_CWD_MAX
+    // 子⑤ (T06544): 同時 warm 保持する cwd 数の上限 N（既定 20）。各 cwd は K 本に畳む。
+    // テストから小さい値を注入可能。⚠️ 正の整数以外（1.5 / Infinity / NaN）は既定へ戻して warn する。
+    // 1.5 が for の開始添字に入ると `list[1.5]` が undefined になり `_isProtected(undefined)` で
+    // TypeError（positive-int-env.mjs 参照）。
+    this._warmCwdMax = sanitizePositiveInt(warmCwdMax, WARM_CWD_MAX, {
+      logger: this.logger,
+      label: "codex.warmCwdMax",
+    })
+    // 1 cwd あたりの live セッション上限 K（既定 3）。テストから 1 を注入すると旧 per-cwd=1 挙動。
+    this._warmPerCwdMax = sanitizePositiveInt(warmPerCwdMax, WARM_PER_CWD_MAX, {
+      logger: this.logger,
+      label: "codex.warmPerCwdMax",
+    })
     // Stage 5: stuck turn 検出 TTL（既定 1h）。テストから短縮可能。
     this._stuckTurnTtlMs = stuckTurnTtlMs ?? STUCK_TURN_TTL_MS
     // 案B (T06542): 死端末 GC の TTL（既定 1h）。テストから短縮可能。
@@ -542,8 +600,10 @@ export class CodexStreamBridge extends EventEmitter {
       // (streamIds が真の購読者集合)。app-server 通知や emit は都度 session.stream_id を読む。
       stream_id,
       // 子⑤ round5 Finding 1: 生成順の単調増加シーケンス（warm 境界のタイブレーク用。値が大きい =
-      // 新しい）。recency 同値時に per-cwd=1 が新しいセッションを残せるようにする。
-      seq: (CODEX_SESSION_SEQ += 1),
+      // 新しい）。recency 同値時に per-cwd=K が新しいセッションを残せるようにする。
+      // ⚠️ カウンタは **claude / codex 共通**（session-seq.mjs）。総 live 上限 M は両 CLI を合算して
+      // 古い順に刈るため、CLI ごとに別カウンタだと CLI をまたいだ比較が成立しない。
+      seq: nextSessionSeq(),
       cwd,
       // 案B (T06542): 多端末購読集合。この live session を購読中の全端末 stream_id。reattach は
       // 「所有権付け替え」ではなく「購読者追加」。detach で当該端末を外し、最後の1台が外れたら
@@ -626,6 +686,24 @@ export class CodexStreamBridge extends EventEmitter {
        *  deliveryId: string, sourceStreamId: string, deliveryPending: boolean,
        *  deliveryPromise: Promise<object>, settleDelivery: Function}>} */
       pendingInjectSources: [],
+      /** 実行中の背景コマンド（commandExecution）の台帳。claude 側 `_liveTasks` と同型。
+       *  key = `item.id`（`item/started` / `item/completed` の両方に載る唯一の安定 ID）、
+       *  value = { threadId, startedAt, lastSeenAt }。
+       *
+       *  ⚠️ `turn/completed` の後もコマンドは走り続ける（実測 /tmp/satoru_bgprobe/raw2.jsonl）ので、
+       *  activeTurnId（busy）だけでは守れない。この台帳で `_isProtected` を延長する。
+       *
+       *  ⚠️ **コマンド本文（`item.command`）は保持しない**。台帳に載せると失効 warn 等のログ経由で
+       *  `~/.hub/agent.log`（launchd の StandardOutPath で 0644 のまま長期保存される）へ本文が流れ、
+       *  Bearer トークン・API キー・個人情報が引数や heredoc ごと永続化される。会話 UI に流れること
+       *  （認可された閲覧者だけが見る）と、永続ログに長期保存されることは境界が違う。
+       *  ⚠️ ハッシュ化で代替しないこと。コマンド行はエントロピーが低く辞書で復元できるため、
+       *  「本文を出さない」の代わりにならない。診断は item_id / thread_id で辿る。
+       *
+       *  ⚠️ threadId は**記録するだけ**で判定には使わない（帰属ガードは本 PR のスコープ外）。
+       * @type {Map<string, {threadId: string|null,
+       *  startedAt: number, lastSeenAt: number}>} */
+      liveExecItems: new Map(),
     }
     session.ready = new Promise((resolve) => {
       settleReady = resolve
@@ -752,8 +830,8 @@ export class CodexStreamBridge extends EventEmitter {
         total_ms: Date.now() - attachStartedAt,
         timing,
       })
-      // 子⑤ (T06544): genuine attach で 1 本増えたので warm 境界（per-cwd=1 / N-cwd LRU）を即時
-      // 適用する（次の reconnect まで ~5s 待たず、同一 cwd の重複や cwd 数超過が居座るのを防ぐ）。
+      // 子⑤ (T06544): genuine attach で 1 本増えたので warm 境界（per-cwd=K / N-cwd LRU）を即時
+      // 適用する（次の reconnect まで ~5s 待たず、cwd 内の K 本超過や cwd 数超過が居座るのを防ぐ）。
       // 新セッションはたった今 touch 済み = 各判定で最新なので退避対象にならず、最も古い非 protected
       // が落ちる。
       this._reconcileWarmBounds(Date.now(), "warm-bounds-on-attach")
@@ -1345,12 +1423,111 @@ export class CodexStreamBridge extends EventEmitter {
     if (this.sessions.get(session.stream_id) === session) this.sessions.delete(session.stream_id)
   }
 
+  /**
+   * app-server 通知を観測して、実行中の背景コマンド台帳（`session.liveExecItems`）を更新する。
+   *
+   * 呼び出しは `_onNotification` の先頭 1 箇所だけ（claude 側 `_observeTaskEvent` と同じ理由で、
+   * switch の中に散らさない）。実測（codex-cli 0.145.0 / /tmp/satoru_bgprobe/raw2.jsonl, raw4.jsonl）
+   * に基づく扱い:
+   *   - `item/started` + `item.type === "commandExecution"` + `item.status === "inProgress"` → 登録
+   *   - `item/completed` + `item.type === "commandExecution"` → `item.id` で削除（冪等）
+   *   - `item/commandExecution/outputDelta`（`params.itemId`）→ **既存エントリがあるときだけ**延命。
+   *     新規作成しない（完了後に遅れて届いた delta で蘇らせない。claude の task_progress と同じ）
+   *
+   * ⚠️ `item.type` であって `item_type` ではない（実測のフィールド名）。
+   * ⚠️ 対象は `commandExecution` に限る。`mcpToolCall` も長時間化しうるが「turn/completed の後も
+   *    走り続けるか」を**実測していない**ため含めない（未実測のものを保護に入れると、逆に
+   *    解除されない保護を作りかねない）。実測できたら同じ台帳に足せばよい。
+   * ⚠️ 例外を外へ投げないこと。`_onNotification` は全通知が通るので、ここで throw すると
+   *    ストリーム全体が壊れる。
+   *
+   * @param {object} session
+   * @param {object} msg app-server 通知（{ method, params }）
+   * @param {number} [now] 時刻（テストから注入可能）
+   */
+  _observeExecItem(session, msg, now = Date.now()) {
+    try {
+      const method = msg?.method
+      if (typeof method !== "string" || !method) return
+      const ledger = session?.liveExecItems
+      if (!ledger) return
+      const params = msg.params
+      if (method === "item/started" || method === "item/completed") {
+        const item = params?.item
+        if (!item || item.type !== "commandExecution") return
+        const id = item.id
+        if (typeof id !== "string" || !id) return
+        if (method === "item/completed") {
+          ledger.delete(id)
+          return
+        }
+        if (item.status !== "inProgress") return
+        ledger.set(id, {
+          // 帰属判定には使わない（記録のみ）。別件で子スレッド起因を切り分けたくなったとき用。
+          threadId: typeof params?.threadId === "string" ? params.threadId : null,
+          // ⚠️ `item.command`（コマンド本文）はここで**捨てる**。台帳へ持つと失効 warn 経由で
+          //    永続ログ（~/.hub/agent.log）に本文が残り、秘密情報が長期保存される。
+          startedAt: now,
+          lastSeenAt: now,
+        })
+        return
+      }
+      if (method === "item/commandExecution/outputDelta") {
+        const itemId = params?.itemId
+        if (typeof itemId !== "string" || !itemId) return
+        const entry = ledger.get(itemId)
+        if (entry) entry.lastSeenAt = now
+      }
+    } catch (err) {
+      this.logger?.warn?.(
+        { err: err?.message, stream_id: session?.stream_id },
+        "codex observe exec item threw",
+      )
+    }
+  }
+
+  /** 実行中の背景コマンドを持つか（warm 境界の保護判定用）。**先に失効エントリを掃除してから**
+   *  判定する。失効は「最後に生存を確認してから CODEX_EXEC_PROTECT_TTL_MS」。
+   *  ⚠️ 失効させる = そのセッションは kill されうる、という意味なので必ず warn を残す
+   *  （黙って kill 可能にしない）。
+   *  ⚠️ warn に**コマンド本文を載せない**（この warn は永続ログへ出る。理由は liveExecItems の
+   *  コメント参照）。診断は `item_id` と 2 つの thread id で辿る:
+   *    - `thread_id`     … セッションの root スレッド（`session.threadId`）。**意味を変えないこと**
+   *      （既存のログ集計がこのキーで root を前提にしている）
+   *    - `exec_thread_id`… その commandExecution の通知に載っていた `params.threadId`（子スレッド
+   *      起因かを切り分けたいとき用。root を上書きせず**別名**で出す） */
+  _hasLiveExec(session, now = Date.now()) {
+    const ledger = session?.liveExecItems
+    if (!ledger || ledger.size === 0) return false
+    for (const [itemId, entry] of ledger) {
+      const elapsed = now - (entry?.lastSeenAt ?? 0)
+      if (elapsed <= CODEX_EXEC_PROTECT_TTL_MS) continue
+      ledger.delete(itemId)
+      this.logger?.warn?.(
+        {
+          stream_id: session?.stream_id,
+          thread_id: session?.threadId ?? null,
+          item_id: itemId,
+          exec_thread_id: entry?.threadId ?? null,
+          elapsed_s: Math.round(elapsed / 1000),
+          ttl_ms: CODEX_EXEC_PROTECT_TTL_MS,
+        },
+        "codex exec protection expired (session is reapable again; a still-running command would be killed)",
+      )
+    }
+    return ledger.size > 0
+  }
+
   _onNotification(session, msg) {
     const { stream_id } = session
     // app-server からの通知 = ターンが進行している証跡。これで touch することで、
     // 正常に走っているターンは reaper に回収されず、通知が途絶えたスタックターンだけが
     // 放棄セッションとして回収される。
     this._touch(session)
+    // 実行中の背景コマンド台帳の更新は **ここ 1 箇所** で行う（switch の中に散らさない）。
+    // 全通知がこの関数を通るので、ここが唯一の合流点になる（経路ごとに配線すると、method を
+    // 足したときに無言で観測漏れする）。claude 側の `_emit` → `_observeTaskEvent` と同じ設計。
+    this._observeExecItem(session, msg)
     // 連携カード種別 (Phase 2, cross-review round1 major#2): タグ判定を switch より前に行い、
     // **history にもタグ済み item を積む**。旧実装は未タグの msg.params.item を history へ入れてから
     // ライブ emit だけタグしていたため、cwd reattach で historyItems が返ると連携カードが通常の青い
@@ -2289,6 +2466,9 @@ export class CodexStreamBridge extends EventEmitter {
    * - healthy running turn: `activeTurnId` が立ち、app-server 通知が STUCK_TTL 以内に届いている。
    *   activeTurnId 固着で通知が STUCK_TTL 途絶えたもの（stuck/ハング）は protected から外し reap
    *   対象にする（プロセスリーク・固着の救済）。
+   * - 実行中の背景コマンド（`liveExecItems` が非空）: `turn/completed` の後も走り続ける
+   *   commandExecution を守る（実測 /tmp/satoru_bgprobe/raw2.jsonl）。claude 側のタスク保護
+   *   （`_hasLiveTask`）と対になる仕組みで、失効時間つきなので終了通知を落としても永久化しない。
    * @param {object} session
    * @param {number} now
    * @returns {boolean}
@@ -2301,6 +2481,12 @@ export class CodexStreamBridge extends EventEmitter {
     // turn RPC accepted 後、対応 userMessage echo を待っている間も protected。
     // ここを外すと別 attach の per-cwd reconcile が ACK 先を配達確認前に reap できる。
     if (session.pendingInjectSources?.some((entry) => entry.deliveryPending)) return true
+    // 実行中の背景コマンド（commandExecution）を保護する。**この 1 箇所**で足すことで、reap の
+    // 3 経路（per-cwd / N-cwd LRU / idle-TTL・stuck）と総 live 上限 M のすべてに同時に効く
+    // （経路ごとに書くと、経路が増えたときに片方だけ守られる非対称が生まれる）。
+    // ⚠️ activeTurnId の判定より **前** に置くこと。背景コマンドが残るのは turn/completed の
+    //    後（= activeTurnId が null に戻った後）なので、下の early return を通すと届かない。
+    if (this._hasLiveExec(session, now)) return true
     if (!session.activeTurnId) return false
     return now - (session.lastActivityMs ?? now) <= this._stuckTurnTtlMs
   }
@@ -2341,24 +2527,46 @@ export class CodexStreamBridge extends EventEmitter {
   }
 
   /**
-   * 子⑤ (T06544): warm 保持を「各 cwd 1 本 × 同時 warm 保持する cwd 数 N（既定 20）」で有界化する。
-   * 旧 `_evictWarmPoolOverflow`（マシン全体の総セッション数 LRU=5）を置換し、境界を「総数」ではなく
-   * 「cwd 単位」で定義する（親 T06539「1 cwd 1 本化」に整合）。
-   *   Phase 1 (per-cwd=1): 同一 cwd に 2 本以上の live session があれば、最終活性が最新の 1 本を残し
-   *     残りの **非 protected** を reap する（WS 再接続や別スレッド開始で一時的に増えた重複を畳む）。
+   * 総 live 上限 M（warm-bounds-total.mjs）用の **CLI 非依存アダプタ**。live セッションを
+   * `{ kind, cwd, recency, seq, protected, reap }` の共通形へ包んで返すだけ（新しい判断は持たない）。
+   * 多端末購読は _liveSessions() で dedup 済み。
+   * @param {number} [now]
+   * @returns {Array<object>}
+   */
+  listWarmCandidates(now = Date.now()) {
+    return this._liveSessions().map((s) => ({
+      kind: "codex",
+      cwd: s.cwd,
+      recency: s.lastActivityMs ?? 0,
+      seq: s.seq ?? 0,
+      protected: this._isProtected(s, now),
+      reap: (reason) => this._reapSession(s, now, reason),
+    }))
+  }
+
+  /**
+   * 子⑤ (T06544): warm 保持を「各 cwd K 本（既定 3）× 同時 warm 保持する cwd 数 N（既定 20）」で
+   * 有界化する。旧 `_evictWarmPoolOverflow`（マシン全体の総セッション数 LRU=5）を置換し、境界を
+   * 「総数」ではなく「cwd 単位」で定義する。
+   *   Phase 1 (per-cwd=K): 同一 cwd に K 本を超える live session があれば、最終活性が新しい順に
+   *     先頭 K 本を残し、それ以降の **非 protected** を reap する（K=1 なら旧挙動。総量は Phase 2 と
+   *     総 live 上限 M（warm-bounds-total.mjs）で押さえる）。
    *   Phase 2 (N-cwd LRU): live session を持つ distinct cwd 数が warmCwdMax を超えたら、cwd の最終活性
    *     が最も古い cwd から、その cwd の非 protected session を reap して cwd 数を上限まで戻す。
    * protected（healthy running turn / stuck 未満）は Phase 1/2 いずれでも reap しない（busy 不可侵）。
    * 全 cwd が busy 等で上限に収められないときは一時的に超過を許容する（走行中ターンを絶対に殺さない）。
    * 多端末購読は 1 session に集約されるため（_liveSessions で dedup）、purely な多端末利用では
-   * per-cwd=1 は自動的に満たされ、Phase 1 は「同一 cwd に別 app-server が 2 本以上できたとき」だけ発火する。
+   * per-cwd=K は自動的に満たされ、Phase 1 は「同一 cwd に別 app-server が K 本を超えてできたとき」
+   * だけ発火する（旧 per-cwd=1 では「2 本以上できたとき」だった）。
    * genuine attach 直後と reconcile の両方から呼ぶ。
    * @param {number} now
    * @returns {number} reap した数
    */
   _reconcileWarmBounds(now, reason = "warm-bounds") {
     let evicted = 0
-    // Phase 1: per-cwd=1。cwd ごとに最終活性が新しい順へ並べ、先頭（最新）以外の非 protected を reap。
+    // Phase 1: per-cwd=K。cwd ごとに最終活性が新しい順へ並べ、先頭 K 本以外の非 protected を reap。
+    // K はコンストラクタで正の整数へ検証済み（不正値は既定へ戻して warn 済み）。
+    const keepPerCwd = this._warmPerCwdMax
     const byCwd = new Map()
     for (const s of this._liveSessions()) {
       const list = byCwd.get(s.cwd)
@@ -2366,13 +2574,13 @@ export class CodexStreamBridge 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) =>
           (b.lastActivityMs ?? 0) - (a.lastActivityMs ?? 0) || (b.seq ?? 0) - (a.seq ?? 0),
       )
-      for (let i = 1; i < list.length; i += 1) {
+      for (let i = keepPerCwd; i < list.length; i += 1) {
         if (this._isProtected(list[i], now)) continue // busy は残す（一時的に >1 を許容）
         this._reapSession(list[i], now, `${reason}:per-cwd`)
         evicted += 1
@@ -2402,7 +2610,8 @@ export class CodexStreamBridge extends EventEmitter {
       for (const info of evictableCwds) {
         if (cwdsEvicted >= overflow) break
         for (const s of info.sessions) {
-          // per-cwd 畳み込み後は各 cwd 1 本のはずだが、念のため非 protected のみ reap。
+          // per-cwd 畳み込み後も各 cwd に**最大 K 本**残る（旧 per-cwd=1 の「1 本」ではない）ので、
+          // cwd 内の全 session を回して非 protected だけを reap する。
           if (this._isProtected(s, now)) continue
           this._reapSession(s, now, `${reason}:cwd-lru`)
           evicted += 1
@@ -2426,8 +2635,11 @@ export class CodexStreamBridge extends EventEmitter {
    *   1. **stuck turn**: activeTurnId 固着だが app-server 通知が STUCK_TTL 途絶えた（ハング）→ reap
    *      （healthy な長ターンは reasoning/output delta で touch されるため該当しない）。
    *   2. **long idle**: 非 busy が idle TTL（既定 7 日）無活性 → reap（warm 保持の期限切れ）。
-   *   3. **warm 境界**（子⑤ T06544）: `_reconcileWarmBounds` で「各 cwd 1 本 × 同時 warm cwd 数 N
-   *      （既定 20）」に有界化。同一 cwd の重複は最新 1 本へ畳み、cwd 数超過は最古 cwd から reap。
+   *   3. **warm 境界**（子⑤ T06544）: `_reconcileWarmBounds` で「各 cwd **K 本（現行の既定 3）**
+   *      × 同時 warm cwd 数 N（既定 20）」に有界化。cwd 内で K 本を超えたぶんは最終活性が古い方から
+   *      reap し、cwd 数超過は最古 cwd から reap する。
+   *      （**旧仕様**は per-cwd=1 ＝「同一 cwd の重複は最新 1 本へ畳む」だった。1 cwd で複数会話を
+   *      同時に生かすため K へ一般化し、総量は総 live 上限 M（warm-bounds-total.mjs）で押さえる。）
    * busy（healthy running turn）は 1〜3 いずれの対象にもならない（走行中ターンを絶対に殺さない）。
    *
    * 旧 `gcAbandonedSessions`（1h 無活性一律 reap）を置換。detach 済み warm セッションを 1h で
@@ -2455,7 +2667,7 @@ export class CodexStreamBridge extends EventEmitter {
         reaped += 1
       }
     }
-    // 3: warm 境界（per-cwd=1 / N-cwd LRU）を適用（stuck/idle reap 後の生存数で判定）。
+    // 3: warm 境界（per-cwd=K / N-cwd LRU）を適用（stuck/idle reap 後の生存数で判定）。
     reaped += this._reconcileWarmBounds(now, "warm-bounds")
     return reaped
   }

package/src/hooks.mjs

@@ -17,7 +17,6 @@
 export const HOOK_NAMES = Object.freeze([
   "onAgentStart",
   "onAgentStop",
-  "interceptPtySpawn",
   "interceptTmuxExec",
   "interceptSessionCreate",
   "interceptSessionKill",
@@ -26,21 +25,6 @@ export const HOOK_NAMES = Object.freeze([
   "transformStatusDetection",
 ])
 
-/**
- * @typedef {Object} PtySpawnArgs
- * @property {string} sessionName
- * @property {number} cols
- * @property {number} rows
- * @property {Record<string, string>} env
- */
-
-/**
- * @typedef {Object} PtySpawnDecision
- * @property {string} command
- * @property {string[]} args
- * @property {Record<string, string>} [env]
- */
-
 /**
  * @typedef {Object} TmuxExecArgs
  * @property {string[]} args
@@ -60,7 +44,6 @@ export const HOOK_NAMES = Object.freeze([
  * @property {{
  *   onAgentStart?: (ctx: HookContext) => Promise<void>,
  *   onAgentStop?: (ctx: HookContext) => Promise<void>,
- *   interceptPtySpawn?: (ctx: HookContext & PtySpawnArgs) => Promise<PtySpawnDecision | null>,
  *   interceptTmuxExec?: (ctx: HookContext & TmuxExecArgs) => Promise<TmuxExecDecision | null>,
  * }} hooks
  */