@cocorograph/hub-agent 0.8.23 → 0.8.24

package/package.json

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

package/src/claude-stream-bridge.mjs

@@ -33,6 +33,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 +183,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 +460,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 +567,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 +705,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) {
@@ -3353,14 +3540,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 +3581,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 +3644,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 +3667,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 +3681,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
         }

package/src/codex-stream-bridge.mjs

@@ -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/main.mjs

@@ -52,6 +52,7 @@ import { PtyBridge } from "./pty-bridge.mjs"
 import { ClaudeStreamBridge } from "./claude-stream-bridge.mjs"
 import { CodexMcpControl } from "./codex-mcp-control.mjs"
 import { CodexStreamBridge, classifyCodexInputError } from "./codex-stream-bridge.mjs"
+import { enforceTotalLiveBound } from "./warm-bounds-total.mjs"
 import { UploadManager } from "./claude-upload.mjs"
 import { requestSelfUninstall } from "./service-install.mjs"
 import {
@@ -2239,6 +2240,11 @@ export function startStateLoop({ client, plugins, logger, intervalMs, claudeBrid
   // 権威的 stall 判定 (arm 非依存・cap 非依存)。state loop が観測する signal だけで turn の開閉と
   // 無進捗を判定する。旧 lastProgressAtByName + armed ゲートの「フック依存 + cap 140s で消える」死角を解消。
   const stallTracker = new StallTracker({ stallWarnMs: STALL_WARN_MS })
+  // 総 live 上限 M のログ抑制状態。⚠️ **この state loop インスタンスが所有する**（module-global に
+  // 置くと、複数インスタンスや並行テストが互いのログを抑制してしまう）。「超過しているが全部
+  // 保護されていて刈れない」tick は 5 秒ごとに同じ行を出し続けるので、状態が変わったときと
+  // 一定間隔でだけ記録する（warm-bounds-total.mjs の _shouldLog）。
+  const warmBoundsLogState = { lastUnresolved: 0, lastLoggedAtMs: 0 }
   let stopped = false
 
   // RC-8: WS 再接続のたびに差分送信の基準 (lastByName) をクリアし、次 tick で全 session.state を
@@ -2263,8 +2269,10 @@ export function startStateLoop({ client, plugins, logger, intervalMs, claudeBrid
       } catch (err) {
         logger?.warn({ err: err?.message }, "gcDeadTerminals failed")
       }
-      // 子⑤ (T06544): claude 側 warm 境界（per-cwd=1 / N-cwd LRU）。従来 claude は per-session の
-      // softDetach タイマー（7 日）だけで件数上限が無かったため、多数の cwd を渡り歩くと warm な
+      // 子⑤ (T06544): claude 側 warm 境界（per-cwd=K / N-cwd LRU）。K は現行の既定 3
+      // （**旧仕様**は per-cwd=1 で「各 cwd 1 本」だった。1 cwd で複数会話を同時に生かすため
+      // 一般化し、総量は下の総 live 上限 M で押さえる）。従来 claude は per-session の softDetach
+      // タイマー（7 日）だけで件数上限が無かったため、多数の cwd を渡り歩くと warm な
       // SDK 常駐 query が蓄積し得た。codex の reconcileSessions と対で cwd 単位に有界化する。
       try {
         claudeBridge?.reconcileWarmBounds?.()
@@ -2279,6 +2287,18 @@ export function startStateLoop({ client, plugins, logger, intervalMs, claudeBrid
       } catch (err) {
         logger?.warn({ err: err?.message }, "gcAbandonedSessions failed")
       }
+      // 総 live 上限 M（claude + codex 合算、既定 20）。per-cwd を 1 → K（既定 3）へ緩めたぶん、
+      // cwd 単位の境界だけでは総量が膨らむため、cwd をまたいだ天井をここで適用する。
+      // ⚠️ 両 CLI の reconcile が **終わった後**に呼ぶ（cwd 単位で畳んだ結果の生存数で判定する）。
+      try {
+        enforceTotalLiveBound({
+          bridges: [claudeBridge, codexBridge].filter(Boolean),
+          logger,
+          logState: warmBoundsLogState,
+        })
+      } catch (err) {
+        logger?.warn({ err: err?.message }, "enforceTotalLiveBound failed")
+      }
       // 実コンテキスト窓サイズ (1M ベータ等) を反映。contextPctFromUsage の分母を
       // 5s ごとに最新化し、ドーナツが 200k 固定で振り切れるのを防ぐ。
       await refreshContextWindow()

package/src/positive-int-env.mjs

@@ -0,0 +1,81 @@
+/**
+ * 上限 / TTL 系の env を **1 箇所で検証**する共通ヘルパー（cross-review minor 6 対応）。
+ *
+ * 【なぜ必要か】旧実装は `Number(process.env.X) || <既定>` で読み、`Math.max(1, v)` しか
+ * 掛けていなかった。`Number("1.5")` は 1.5 を通し `Math.max(1, 1.5) === 1.5` なので、
+ * その値が **for ループの開始添字**（`for (let i = keepPerCwd; ...)`）に入ると実害が出る:
+ *   - codex: `list[1.5]` が undefined のまま `_isProtected(undefined, now)` へ渡り
+ *     `session.pumping` の参照で TypeError
+ *   - claude: undefined の reap が no-op なのに `reaped` だけ加算され、
+ *     **実際には畳んでいないのに畳んだと報告する**
+ * `Infinity` は `Number("Infinity")` が通るため実質「上限なし」になる。
+ *
+ * 【なぜ Math.floor で丸めないか】設定ミスを黙って別の値に読み替えると、運用者は
+ * 「設定したつもりの値」と「効いている値」がズレたまま気づけない。**既定値へ戻して warn**
+ * に統一し、必ず痕跡が残るようにする。
+ *
+ * 【なぜ「正の安全整数」か】上限（K / M / N）は「何本残すか」の個数、TTL は「何ミリ秒」で、
+ * いずれも 1 未満・非整数・非有限に意味が無い。`Number.isSafeInteger` は NaN / Infinity /
+ * 小数 をまとめて弾ける唯一の述語なので、これ 1 本で判定する。
+ */
+
+/** 正の安全整数（>= 1）か。NaN / Infinity / 小数 / 0 / 負数 はすべて false。 */
+export function isPositiveInt(value) {
+  return Number.isSafeInteger(value) && value >= 1
+}
+
+/** warn の出力先。logger が無い（モジュール読み込み時など）場合は stderr へ落とす。 */
+function warn(logger, fields, message) {
+  if (typeof logger?.warn === "function") {
+    logger.warn(fields, message)
+    return
+  }
+  // eslint-disable-next-line no-console
+  console.warn(`[hub-agent] ${message}`, fields)
+}
+
+/**
+ * env から正の整数を読む。**不正値は既定値へ戻して warn**（黙って丸めない）。
+ *
+ * @param {string|string[]} names 環境変数名。配列なら「先に設定されている方を優先」して順に評価し、
+ *   不正値だった名前は warn したうえで次の候補へ落ちる（後方互換 env を持つ設定のため）。
+ * @param {number} fallback 既定値（正の安全整数であること）
+ * @param {object} [logger]
+ * @returns {number}
+ */
+export function readPositiveIntEnv(names, fallback, logger) {
+  const list = Array.isArray(names) ? names : [names]
+  for (const name of list) {
+    const raw = process.env[name]
+    if (raw === undefined || raw === null || String(raw).trim() === "") continue
+    const parsed = Number(raw)
+    if (isPositiveInt(parsed)) return parsed
+    warn(
+      logger,
+      { env: name, value: String(raw), fallback },
+      "invalid env value (expected a positive integer); falling back to the default",
+    )
+  }
+  return fallback
+}
+
+/**
+ * 実行時に注入された上限値（テスト / 呼び出し側 opts）を検証する。env と同じ規則で、
+ * 不正なら **既定値へ戻して warn** する（env だけ守っても opts 経由で同じ穴が開くため）。
+ *
+ * @param {*} value
+ * @param {number} fallback
+ * @param {{ logger?: object, label?: string }} [opts]
+ * @returns {number}
+ */
+export function sanitizePositiveInt(value, fallback, { logger, label = "bound" } = {}) {
+  if (value === undefined || value === null) return fallback
+  const parsed = typeof value === "number" ? value : Number(value)
+  if (isPositiveInt(parsed)) return parsed
+  warn(
+    logger,
+    { setting: label, value: String(value), fallback },
+    "invalid bound value (expected a positive integer); falling back to the default",
+  )
+  return fallback
+}

package/src/session-seq.mjs

@@ -0,0 +1,22 @@
+/**
+ * **プロセス内で 1 本**のセッション生成順シーケンス（cross-review minor 4 対応）。
+ *
+ * 【なぜ CLI ごとに持ってはいけないか】warm 境界の recency が同値になったときのタイブレークに
+ * seq を使う。cwd 単位の境界（per-cwd=K / N-cwd LRU）は同一 CLI 内でしか比較しないので
+ * CLI ごとのカウンタでも成立したが、**総 live 上限 M（warm-bounds-total.mjs）は claude と codex を
+ * 合算して「古い方から刈る」**ため、別カウンタだと CLI をまたいだ比較が成立しない。
+ * 例: 古い codex が seq=100 / 新しい claude が seq=2 のとき、recency 同値だと **新しい claude が
+ * 先に刈られる**。プロセス内で単一の単調増加にすれば、この比較が常に生成順と一致する。
+ *
+ * cwd 内のタイブレークは「単調増加であること」しか使っていないため、共有化しても挙動は変わらない
+ * （値の絶対値には意味が無い。⚠️ そのためテストで絶対値を assert しないこと。module-global は
+ * テスト間で値が持ち越される）。
+ */
+
+let SESSION_SEQ = 0
+
+/** 次のセッション seq（1 始まりの単調増加）を返す。 */
+export function nextSessionSeq() {
+  SESSION_SEQ += 1
+  return SESSION_SEQ
+}

package/src/warm-bounds-total.mjs

@@ -0,0 +1,150 @@
+/**
+ * 総 live 上限 M（既定 20）: claude / codex を **合算** した live セッション数の天井。
+ *
+ * 【なぜ必要か】per-cwd の上限を 1 → K（既定 3）へ緩めたので、cwd 単位の境界（per-cwd=K ×
+ * N-cwd LRU）だけではマシン全体の総量が K 倍まで膨らみうる。方針は「総量は増やさず配分の
+ * 自由度だけ上げる」なので、cwd をまたいだ総量の天井をここで別に持つ。
+ *
+ * 【なぜ 1 モジュールで合算できるか】claude / codex の両ブリッジは同一プロセスに同居している
+ * （src/main.mjs の agent 起動時に両方 new される）ため、プロセス内で足し合わせれば実際の
+ * リソース消費（1 セッション ≈ 120-140MB）と一致する。
+ *
+ * 【CLI 分岐を持たない設計】各ブリッジが `listWarmCandidates(now)` という **CLI 非依存の共通
+ * アダプタ** を提供し、本モジュールはその配列だけを見る。ここに `kind === 'claude'` のような
+ * 分岐を入れると、CLI が増えるたびに刈り取りロジックが分岐して腐るため入れない。
+ * テストはアダプタ形状の stub 2 本で書ける。
+ */
+import { readPositiveIntEnv, sanitizePositiveInt } from "./positive-int-env.mjs"
+
+/** 総 live 上限 M（claude + codex 合算）。env で調整可能。ブリッジ側に重複定義しないこと。
+ *
+ *  【なぜ 20 か】2026-08-03 の実測で、同時 live は **17 本**（claude 13 / codex 4）だった。
+ *  内訳は distinct な (cwd, 種別) 16 バケットに対しほぼ 1 本ずつで、2 本あるのは 1 バケットのみ。
+ *  つまり資源を消費しているのは「1 cwd に何本開くか（深さ）」ではなく「同時に開いている cwd の
+ *  数（広さ）」である。したがって:
+ *    - K=3（深さ）を許しても今日の使い方の総量は変わらない
+ *    - M=10 にすると **広さを切る**ことになり、導入した瞬間に 7 本が畳まれる（当初案を却下）
+ *  構造上の天井は、**旧 per-cwd=1 時代**が 40 本（cwd 数 N=20 × per-cwd 1 × ブリッジ 2）、
+ *  **本 PR の per-cwd=K=3 では M が無ければ 120 本**（N=20 × K=3 × ブリッジ 2）。M=20 はその
+ *  どちらより小さく、旧天井 40 の半分でありながら実測 17 本を切らない値になる（K を緩めても
+ *  総量は増やさない、という方針がこの M で担保される）。
+ *  ⚠️ 畳んでも会話は消えない（resume で復帰する）が、温まった状態を失って切替が遅くなる。
+ *  この待ち時間は 2026-07-31 に課題として挙がっている論点なので、安易に下げないこと。 */
+export const WARM_TOTAL_MAX = readPositiveIntEnv("HUB_AGENT_WARM_TOTAL_MAX", 20)
+
+/** 「超過しているが保護されていて刈れない」状態を info で出す最小間隔（既定 5 分）。
+ *  state loop は 5 秒周期なので、抑制しないと同じ 1 行が 1 時間に約 720 件出る。 */
+export const UNRESOLVED_LOG_INTERVAL_MS = 5 * 60 * 1000
+
+/**
+ * @typedef {object} WarmCandidate
+ * @property {string} kind    'claude' | 'codex' 等（ログ用。刈り取り判断には使わない）
+ * @property {string} cwd     作業ディレクトリ（ログ用）
+ * @property {number} recency 最終活性（epoch ms。小さいほど古い = 先に刈る）
+ * @property {number} seq     生成順の単調増加値（recency 同値のタイブレーク。小さいほど古い）
+ * @property {boolean} protected 走行中ターン / pending / タスク実行中 等で不可侵か
+ * @property {(reason: string) => void} reap 実際に撤去する
+ */
+
+/**
+ * 総 live 上限を適用する。**保護されているものは刈らない**（全部保護なら上限超過を許容する
+ * = 走行中を殺さない方を優先する。上限は次の tick で改めて試みられる）。
+ *
+ * ⚠️ **M はハードな資源上限ではない**（cross-review round2 minor）。保護（走行中ターン / 実行中の
+ * 背景タスク・コマンド）は必ず skip するので、保護が同時に多数付けば live 総数は M を超えたまま
+ * 増え続けうる。有界なのは **1 エントリあたりの保護時間**（各ブリッジの TTL）だけで、**同時に
+ * 保護されうる件数には K も N も M も効かない**。ここは「一時的な超過を明示的に受容する」設計で、
+ * 実際の超過量は戻り値の `liveTotal` / `unresolved`（と対応する info ログ）で観測する。
+ * 上限を守れているかの運用判断は、M という設定値ではなくその実測値を見ること。
+ *
+ * ⚠️ 将来「保護中でも刈る」ハード上限を足すなら、**実行中の作業を中断するという新しい失敗モード**
+ * が生まれる。ここに暗黙に足さないこと。足すなら victim の選び方・利用者への通知・再開可否を
+ * 別仕様として設計する。
+ *
+ * 【ログの抑制】state loop は 5 秒周期で回るため、「超過しているが全部保護されていて刈れない」
+ * 状態が続くと同じ info が 1 時間に約 720 件出る（旧実装は `reaped > 0 || overflow > 0` という
+ * **常に真の死んだ条件**だったので毎 tick 出ていた。overflow <= 0 は手前で return 済み）。
+ * そこで **実際に reap した tick は従来どおり info**、**unresolved だけの tick は「状態が変わった
+ * とき」か「一定間隔（既定 5 分）」でのみ**出す。
+ *
+ * ⚠️ 抑制の状態は **module-global に置かない**（複数インスタンス・並行テストが互いのログを
+ * 抑制してしまう）。呼び出し側が持つ `logState` オブジェクトに書く。渡さなければ抑制しない。
+ *
+ * @param {{ bridges?: Array<{ listWarmCandidates?: (now: number) => WarmCandidate[] }>,
+ *           max?: number, now?: number, logger?: object,
+ *           logState?: {lastUnresolved?: number, lastLoggedAtMs?: number} }} [opts]
+ * @returns {{reaped: number, unresolved: number, liveTotal: number}}
+ *   reaped=実際に刈った数 / unresolved=保護されて刈れなかった超過ぶん / liveTotal=候補総数
+ */
+export function enforceTotalLiveBound({
+  bridges = [],
+  max,
+  now = Date.now(),
+  logger,
+  logState,
+} = {}) {
+  // ⚠️ 上限は正の整数（1.5 / Infinity / NaN は既定へ戻して warn）。positive-int-env.mjs 参照。
+  const limit = sanitizePositiveInt(max, WARM_TOTAL_MAX, {
+    logger,
+    label: "warmBounds.totalMax",
+  })
+  /** @type {WarmCandidate[]} */
+  const candidates = []
+  for (const bridge of bridges) {
+    if (!bridge || typeof bridge.listWarmCandidates !== "function") continue
+    try {
+      const list = bridge.listWarmCandidates(now)
+      if (Array.isArray(list)) {
+        for (const c of list) if (c) candidates.push(c)
+      }
+    } catch (err) {
+      logger?.warn?.({ err: err?.message }, "listWarmCandidates threw")
+    }
+  }
+  const overflow = candidates.length - limit
+  if (overflow <= 0) {
+    // 超過が解消した = 抑制状態をリセットする。次に新しく超過したときは即座に記録される。
+    if (logState) {
+      logState.lastUnresolved = 0
+      logState.lastLoggedAtMs = 0
+    }
+    return { reaped: 0, unresolved: 0, liveTotal: candidates.length }
+  }
+  // 古い順（recency 昇順、同値は seq 昇順）に、非保護だけを刈る。
+  const evictable = candidates
+    .filter((c) => !c.protected)
+    .sort((a, b) => (a.recency ?? 0) - (b.recency ?? 0) || (a.seq ?? 0) - (b.seq ?? 0))
+  let reaped = 0
+  for (const c of evictable) {
+    if (reaped >= overflow) break
+    try {
+      c.reap("warm-bounds:total")
+      reaped += 1
+    } catch (err) {
+      logger?.warn?.({ err: err?.message, kind: c.kind, cwd: c.cwd }, "total warm bound reap threw")
+    }
+  }
+  // 保護されて刈れなかったぶん（>0 なら一時的に上限超過を許容している）。
+  const unresolved = overflow - reaped
+  if (_shouldLog({ reaped, unresolved, now, logState })) {
+    logger?.info?.(
+      { live_total: candidates.length, max: limit, overflow, reaped, unresolved },
+      "warm bounds: total live limit applied",
+    )
+    if (logState) {
+      logState.lastUnresolved = unresolved
+      logState.lastLoggedAtMs = now
+    }
+  }
+  return { reaped, unresolved, liveTotal: candidates.length }
+}
+
+/** ログを出すか。reap した tick は常に出す。unresolved だけの tick は、状態が変わったときか
+ *  一定間隔が空いたときだけ出す（logState 未指定なら抑制しない）。 */
+function _shouldLog({ reaped, unresolved, now, logState }) {
+  if (reaped > 0) return true
+  if (unresolved <= 0) return false
+  if (!logState) return true
+  if (logState.lastUnresolved !== unresolved) return true
+  return now - (logState.lastLoggedAtMs ?? 0) >= UNRESOLVED_LOG_INTERVAL_MS
+}