@cocorograph/hub-agent 0.8.54 → 0.8.55

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cocorograph/hub-agent",
-  "version": "0.8.54",
+  "version": "0.8.55",
   "description": "Hub Hosted Cockpit のローカル常駐 agent。Hub と outbound WSS で接続し、ローカルの Claude / Codex チャットと tmux セッションを中継する。",
   "type": "module",
   "license": "UNLICENSED",

package/src/codex-stream-bridge.mjs

@@ -235,6 +235,18 @@ const IDLE_DETACH_TTL_MS = readPositiveIntEnv(
   7 * 24 * 60 * 60 * 1000,
 )
 
+// browser が最後に detach してから app-server を warm 保持する猶予。lastActivityMs は
+// sibling inject や app-server 通知でも更新されるため、「画面から離れてどれだけ経ったか」の
+// 判定には使えない。browserDetachedAtMs を独立して持ち、既存の protected 判定が解けた後だけ
+// app-server（MCP 子孫を含む）を回収する。Codex は app-server 配下で MCP 子を eager 起動し、
+// 子 thread / MCP 単体の unload RPC も無いため、画面不在 session を app-server 単位で cold 化する
+// 必要がある。Claude SDK session にはこの eager MCP 子構造が無いので Codex 固有 env とする。
+// 既存の 7 日 idle TTL / warm bounds は別軸で維持する。
+const DETACHED_REAP_TTL_MS = readPositiveIntEnv(
+  "HUB_AGENT_CODEX_DETACHED_REAP_TTL_MS",
+  30 * 60 * 1000,
+)
+
 // 子⑤ (T06544): warm 保持の上限を「マシン全体の総セッション数」から「各 cwd K 本 × 同時 warm
 // 保持する cwd 数 N」へ再定義（親 T06539「1 cwd 1 本化」に整合）。旧 WARM_POOL_MAX（総数 LRU=5）は
 // 廃止し、境界を cwd 単位で定義する。1 セッション ≈ 120-140MB（node ラッパー + 本体 + MCP 子）
@@ -333,6 +345,16 @@ const DELIVERY_ECHO_TIMEOUT_MS = readPositiveIntEnv(
   8 * 1000,
 )
 
+// sibling delivery が「受理済みで再送不要」と判断できる status。delivered は echo 確認済み、
+// delivery_queued は FIFO 受理済み、delivery_unconfirmed は RPC 受理後に echo だけ未確認であり、
+// いずれも画面不在中の実 traffic として cold 化窓を更新する。turn RPC 前に失敗して再送可能な
+// delivery_failed は含めない。
+const DELIVERY_WINDOW_REFRESH_STATUSES = new Set([
+  "delivered",
+  "delivery_queued",
+  "delivery_unconfirmed",
+])
+
 const CLIENT_INFO = { name: "cockpit-hub-agent", title: "Cockpit", version: "1.0.0" }
 const WORKSPACE_DEPENDENCIES_CACHE_TTL_MS = 30_000
 const WORKSPACE_DEPENDENCIES_FAILURE_TTL_MS = readPositiveIntEnv(
@@ -601,6 +623,7 @@ export class CodexStreamBridge extends EventEmitter {
     logger,
     clientFactory,
     detachTtlMs,
+    detachedReapTtlMs,
     warmCwdMax,
     warmPerCwdMax,
     stuckTurnTtlMs,
@@ -692,6 +715,8 @@ export class CodexStreamBridge extends EventEmitter {
       || preflightCodexArtifactTemplatePicker
     // Stage 5: warm 保持の idle TTL（既定 7 日）。テストから短縮できるよう注入可能。
     this._detachTtlMs = detachTtlMs ?? IDLE_DETACH_TTL_MS
+    // browser の最終 detach を起点にした短期 warm TTL（既定 30 分）。内部配送の活性では解除しない。
+    this._detachedReapTtlMs = detachedReapTtlMs ?? DETACHED_REAP_TTL_MS
     // 子⑤ (T06544): 同時 warm 保持する cwd 数の上限 N（既定 20）。各 cwd は K 本に畳む。
     // テストから小さい値を注入可能。⚠️ 正の整数以外（1.5 / Infinity / NaN）は既定へ戻して warn する。
     // 1.5 が for の開始添字に入ると `list[1.5]` が undefined になり `_isProtected(undefined)` で
@@ -760,8 +785,10 @@ export class CodexStreamBridge extends EventEmitter {
    *
    * @returns {Promise<{resuming: boolean, threadId: string, history: object[],
    *   historyTruncated: boolean, historyStart?: number, historyTotal?: number,
+   *   subagents?: object[],
    *   threadStatus: string|null, lastTurnStatus: string|null,
    *   turnActive: boolean}>}
+   * `subagents` の省略は snapshot 未提供（既存 UI 状態を維持）を意味し、空配列は権威的に0件を意味する。
    */
   async attach({ stream_id, cwd, model, effort, approvalPolicy, sandbox, resumeThreadId, attachId }) {
     if (this.sessions.has(stream_id)) {
@@ -791,6 +818,7 @@ export class CodexStreamBridge extends EventEmitter {
         const r = await this._tryReattach(existing, stream_id)
         timing.reattach_wait_ms = (timing.reattach_wait_ms ?? 0) + lap()
         if (r.status === "reattached") {
+          const snapshot = this._warmReattachSnapshot(existing, r.info)
           this._logAttachTiming({
             stream_id,
             cwd,
@@ -800,11 +828,12 @@ export class CodexStreamBridge extends EventEmitter {
             ok: true,
             resuming: true,
             thread_op: null,
-            history_items: 0,
+            history_items: snapshot.history.length,
+            history_truncated: snapshot.historyTruncated,
             total_ms: Date.now() - attachStartedAt,
             timing,
           })
-          return r.info
+          return snapshot
         }
         if (r.status === "superseded") {
           this._logAttachTiming({
@@ -848,7 +877,7 @@ export class CodexStreamBridge extends EventEmitter {
         const r = await this._tryReattach(existing, stream_id)
         timing.reattach_wait_ms = (timing.reattach_wait_ms ?? 0) + lap()
         if (r.status === "reattached") {
-          const history = Array.isArray(existing.historyItems) ? existing.historyItems.slice() : []
+          const snapshot = this._warmReattachSnapshot(existing, r.info)
           this._logAttachTiming({
             stream_id,
             cwd,
@@ -858,27 +887,12 @@ export class CodexStreamBridge extends EventEmitter {
             ok: true,
             resuming: true,
             thread_op: null,
-            history_items: history.length,
-            history_truncated: existing.historyTruncated === true,
+            history_items: snapshot.history.length,
+            history_truncated: snapshot.historyTruncated,
             total_ms: Date.now() - attachStartedAt,
             timing,
           })
-          return {
-            ...r.info,
-            // 案1: reattach は履歴を返さない設計 (r.info.history=[]) だが、cwd reattach は remount
-            // 由来で表示がリセットされ得るため、live セッションが保持する高忠実度履歴を返す。
-            history,
-            historyTruncated: existing.historyTruncated === true,
-            ...(history.length > 0
-              ? {
-                  historyStart: Number.isInteger(existing.historyStart) ? existing.historyStart : 0,
-                  historyTotal: Number.isInteger(existing.historyTotal)
-                    ? existing.historyTotal
-                    : history.length,
-                }
-              : {}),
-            subagents: this._subagentSnapshots(existing, history),
-          }
+          return snapshot
         }
         if (r.status === "superseded") {
           this._logAttachTiming({
@@ -983,6 +997,13 @@ export class CodexStreamBridge extends EventEmitter {
       // （busy/stuck）で決める。detach してもすぐには殺さず warm 保持する。
       // ask-sibling 注入 (sendToCwd) は「新しい持ち主が付いた」とみなして false に戻す。
       detachRequested: false,
+      // 最後の browser subscriber が detach した時刻。実 browser reattach だけが null へ戻す。
+      // sibling inject 等の内部配送では残し、画面不在の app-server を短期 TTL 後に回収できるようにする。
+      browserDetachedAtMs: null,
+      // 明示 codex.detach 後に同 stream の古い interval callback が到着しても、実 attach 前に
+      // browser 復帰扱いへ戻さないための最小フラグ。死端末 GC 起因では false のままなので、
+      // 本当に生存していた browser の keepalive は復帰シグナルとして使える。
+      explicitBrowserDetachPendingAttach: false,
       dead: false,
       // Stage 5 reconcile（LRU / idle TTL / stuck）用の最終活性時刻。browser 入力と app-server
       // 通知 (ターン進捗) の両方で更新する。LRU は「最終活性が最も古い非 protected」を退避する。
@@ -1180,6 +1201,8 @@ export class CodexStreamBridge extends EventEmitter {
       // T06541 案1: cold attach で得た高忠実度履歴をセッションに保持する。以降ライブ item
       // 完了ごとに追記し、cwd reattach 時にこれを返す（新プロセス thread/resume を再実行しない）。
       // major#2: byte 予算判定を O(1) にするため概算 byte 合計も持つ (flatten は既に byte 上限適用済み)。
+      // app-server reap 後の cold resume は rollout が正本になるため、未 rollout の空 fresh session や
+      // in-memory の sibling source タグは復元できない。空 session の滞留を避けるため fresh 例外は作らない。
       session.historyItems = history.slice()
       session.historyBytes = history.reduce((n, it) => n + estimateItemBytes(it), 0)
       session.historyTruncated = historyTruncated
@@ -1347,6 +1370,39 @@ export class CodexStreamBridge extends EventEmitter {
     return null
   }
 
+  /** attach-id / cwd の warm reattach ready payload を同じ shape で組み立てる。 */
+  _warmReattachSnapshot(session, baseInfo) {
+    // historyItems 自体が既存の item/byte 上限内なので、attach-id reconnect でも payload 上限を
+    // 新たに広げない。frontend reducer は uuid で重複排除し、hidden 中の item 欠損だけを補う。
+    const history = Array.isArray(session.historyItems) ? session.historyItems.slice() : []
+    return {
+      ...baseInfo,
+      history,
+      historyTruncated: session.historyTruncated === true,
+      ...(history.length > 0
+        ? {
+            historyStart: Number.isInteger(session.historyStart) ? session.historyStart : 0,
+            historyTotal: Number.isInteger(session.historyTotal)
+              ? session.historyTotal
+              : history.length,
+          }
+        : {}),
+      ...this._completeSubagentSnapshotField(session, history),
+    }
+  }
+
+  /**
+   * warm ready の subagents 三値契約。session.subagents が表示台帳の正本で、空なら権威的な []。
+   * 1件でも started anchor が trim 等で history 外なら部分 snapshot を返さず、キー自体を省略して
+   * frontend の既存表示を維持させる。全 record を表現できる場合だけ配列を返す。
+   */
+  _completeSubagentSnapshotField(session, history) {
+    const recordCount = session?.subagents?.size ?? 0
+    if (recordCount === 0) return { subagents: [] }
+    const snapshots = this._subagentSnapshots(session, history)
+    return snapshots.length === recordCount ? { subagents: snapshots } : {}
+  }
+
   /**
    * T06541 案1: 完了 ThreadItem を高忠実度履歴 (session.historyItems) に追記する。
    * 表示用バブル時刻 at_ms は completedAtMs (ms epoch) を採る（flattenThreadItems と同じ ms 単位。
@@ -1777,6 +1833,8 @@ export class CodexStreamBridge extends EventEmitter {
     this.sessions.set(newStreamId, session)
     session.stream_id = newStreamId
     session.detachRequested = false
+    session.browserDetachedAtMs = null
+    session.explicitBrowserDetachPendingAttach = false
     session.lastActivityMs = now
     this.logger?.info?.(
       {
@@ -1793,15 +1851,16 @@ export class CodexStreamBridge extends EventEmitter {
     // 出したカードは remount/端末切替で失われ、応答が来ないとターンが永久 pending になる。新 stream へ
     // 再 emit してカードを復元させる (frontend は request_id で重複排除するので二重化しない)。
     this._replayPendingApprovals(session)
-    // 履歴は返さない: reconnect では frontend が表示を保持している (resetDisplay=false) ため
-    // 再 hydrate 不要。turnActive は session が保持する activeTurnId から権威的に決める。
+    // ここでは購読・権威状態だけを返す。呼び出し元 attach() が attach-id / cwd のどちらにも
+    // _warmReattachSnapshot() を適用し、保持履歴・subagent snapshot を同じ ready shape へ揃える。
+    // turnActive は session が保持する activeTurnId から権威的に決める。
     return {
       status: "reattached",
       info: {
         resuming: true,
         threadId,
         history: [],
-        // reconnect の in-memory reattach は表示を保持しているので履歴を返さない = 常に非 truncated。
+        // placeholder。保持履歴と cursor metadata は呼び出し元の共通 snapshot helper が上書きする。
         historyTruncated: false,
         threadStatus: session.activeTurnId ? "active" : "idle",
         lastTurnStatus: null,
@@ -3760,19 +3819,36 @@ export class CodexStreamBridge extends EventEmitter {
   /**
    * ブラウザ閲覧中の生存シグナル (codex.keepalive)。frontend が Codex チャットを開いて
    * いる間だけ定期送信するため、これが届く = 「人が見ている」の観測可能な証跡になる。
+   * frontend は ready 後に codex.keepalive の interval を開始する（現行60秒。WS pingの25秒とは別）。
    * Stage 5: touch で lastActivityMs を更新すると LRU 先頭に留まるため、**閲覧中のセッションは
    * 上限超過の LRU 退避対象にならず、長 idle TTL でも殺されない**（= 実質無期限）。ブラウザを
    * 閉じれば keepalive も止まり、以降は detach 済み warm として LRU / 7 日 idle TTL に従う。
    *
-   * @returns {boolean} 生きているセッションを touch できたら true (未知 stream は false)。
+   * 明示 detach 後は実 attach まで同 stream の残留 keepalive を false で無視する。一方、死端末 GC
+   * 由来の detachRequested は live keepalive を復帰シグナルとして受け入れる。
+   * @returns {boolean} セッションを touch できたら true（未知/dead/明示detach待ちは false）。
    */
   keepalive({ stream_id }) {
     const session = this.sessions.get(stream_id)
     if (!session || session.dead) return false
+    // 明示 detach の直前に既に timer queue へ入った callback は、detach 後にも同じ stream_id で
+    // 到着し得る。クライアント契約では再表示時に必ず attach するため、その attach がこのフラグを
+    // 解除するまでは古い keepalive として無視する。GC 起因の detach はフラグを立てない。
+    if (session.explicitBrowserDetachPendingAttach) return false
+    // keepalive は実 browser が閲覧中という証跡なので、detach 不達/遅延で残った warm 状態も解除する。
+    // app-server 通知や sibling inject が通る _touch() ではこの browser 専用状態を解除しない。
+    session.detachRequested = false
+    session.browserDetachedAtMs = null
     this._touch(session, stream_id)
     return true
   }
 
+  /** accepted済みの新規 sibling traffic だけ browser-detached の cold 化窓を更新する。 */
+  _shouldRefreshDetachWindow(result) {
+    return result?.accepted_via !== "duplicate"
+      && DELIVERY_WINDOW_REFRESH_STATUSES.has(result?.status)
+  }
+
   /**
    * グレースフル切断（Stage 5 + 案B T06542）。**すぐには reap しない**。
    *
@@ -3812,6 +3888,8 @@ export class CodexStreamBridge extends EventEmitter {
     // 最後の 1 台が外れた: key / streamIds は残したまま（reconcile 到達性のため）warm 保持し、
     // detachRequested を立てる。以降は周期 reconcile（LRU 上限 / 長 idle TTL / stuck）が reap を判断する。
     session.detachRequested = true
+    session.explicitBrowserDetachPendingAttach = true
+    if (session.browserDetachedAtMs == null) session.browserDetachedAtMs = Date.now()
     this.logger?.info?.(
       {
         stream_id,
@@ -3826,10 +3904,10 @@ export class CodexStreamBridge extends EventEmitter {
   /**
    * 案B (T06542): 死端末 GC。多端末購読で、クラッシュ / タブ強制終了で codex.detach を送れずに
    * 消えた購読端末（一定期間 input/permission/interrupt/keepalive の活性が無い stream_id）を購読集合
-   * から掃除する。claude-stream-bridge.mjs の gcDeadTerminals と同型。複数端末が購読するセッション
-   * のみ対象（1 台しか居なければ reconcile の idle TTL / LRU に任せる）。全端末が死端末で空になったら
-   * detachRequested を立て warm 保持へ落とす。reconcileSessions の先頭から呼ばれる（main.mjs の
-   * state loop 経由）ほか、テストから直接も呼べる。
+   * から掃除する。claude-stream-bridge.mjs の gcDeadTerminals と同型。最後の 1 key は routing / reconcile
+   * 到達性のため消さず、単端末を含め stale なら detachRequested と browserDetachedAtMs を立てる。
+   * codex.detach 不達時の実効回収時間は dead-terminal TTL + detached reap TTL になる。
+   * reconcileSessions の先頭から呼ばれる（main.mjs の state loop 経由）ほか、テストから直接も呼べる。
    * @param {number} [ttlMs] 死端末とみなす無活性閾値（テスト用に上書き可）。
    * @returns {number} GC した端末キー数。
    */
@@ -3837,8 +3915,6 @@ export class CodexStreamBridge extends EventEmitter {
     const now = Date.now()
     let removed = 0
     for (const session of this._liveSessions()) {
-      // 複数端末が購読しているセッションのみ対象（1 台なら reconcile の idle TTL / LRU に任せる）。
-      if (session.streamIds.size <= 1) continue
       for (const sid of Array.from(session.streamIds)) {
         // ⚠️ 不変条件: live session は常に stream key を 1 つ以上残す（reconcile 到達性）。全端末が
         // 死端末でも最後の 1 個は消さず、下で detachRequested を立てて idle TTL reap に委ねる。
@@ -3862,7 +3938,10 @@ export class CodexStreamBridge extends EventEmitter {
       if (session.streamIds.size === 1) {
         const [onlySid] = session.streamIds
         const last = session.lastActivityByStream.get(onlySid) ?? 0
-        if (now - last >= ttlMs) session.detachRequested = true
+        if (now - last >= ttlMs) {
+          session.detachRequested = true
+          if (session.browserDetachedAtMs == null) session.browserDetachedAtMs = now
+        }
       }
     }
     return removed
@@ -4002,17 +4081,23 @@ export class CodexStreamBridge extends EventEmitter {
       return { status: "ambiguous", candidates }
     }
     const best = tier[0]
-    // detach 済み warm セッションでも、ask-sibling が使うなら「新しい持ち主が付いた」とみなして
-    // detachRequested を解除し touch する（LRU 先頭へ）。this.input が改めて _touch するが、注入前に
-    // 明示しておく。ターン実行中は healthy busy = protected なので reconcile で kill されない。
+    // detachRequested=false は「内部配送先として現役」の routing 状態。browser 不在は
+    // browserDetachedAtMs で別管理する。過去の 5 分 reap と違い、成功した sibling traffic ごとに
+    // 30 分窓を更新し、その間の root/FIFO/delivery/command/subagent は _isProtected で守る。
+    // 完全無活動が 30 分続いた後だけ app-server を cold 化する。not_found 時の cold 自動起動はしない。
     best.detachRequested = false
     this._touch(best)
-    return this._deliverInjection(best, text, source, {
+    const result = await this._deliverInjection(best, text, source, {
       cwd,
       selection: "sole-candidate",
       candidates: this.describeLiveSessions(cwd).length,
       request_id: requestId,
     })
+    // await 中に実 browser attach が入れば timestamp は null になる。その場合は再刻印しない。
+    if (best.browserDetachedAtMs != null && this._shouldRefreshDetachWindow(result)) {
+      best.browserDetachedAtMs = Date.now()
+    }
+    return result
   }
 
   /**
@@ -4066,16 +4151,21 @@ export class CodexStreamBridge extends EventEmitter {
       target = byThread[0] || null
     }
     if (!target) return { status: "not_found" }
-    // detach 済み warm セッションでも、明示指定で使うなら「新しい持ち主が付いた」とみなす
-    // (sendToCwd と同じ扱い)。
+    // detachRequested は内部配送の routing 状態、browserDetachedAtMs は画面不在の cold 化窓。
+    // 成功した sibling traffic だけ後者を更新する（sendToCwd と同じ扱い）。
     target.detachRequested = false
     this._touch(target)
-    return this._deliverInjection(target, text, source, {
+    const result = await this._deliverInjection(target, text, source, {
       cwd,
       requested_id: id,
       selection: bySid ? "stream_id" : "thread_id",
       request_id: requestId,
     })
+    // await 中に実 browser attach が入れば timestamp は null になる。その場合は再刻印しない。
+    if (target.browserDetachedAtMs != null && this._shouldRefreshDetachWindow(result)) {
+      target.browserDetachedAtMs = Date.now()
+    }
+    return result
   }
 
   /**
@@ -4451,6 +4541,9 @@ export class CodexStreamBridge extends EventEmitter {
         cwd: session.cwd,
         reason,
         idle_ms: now - (session.lastActivityMs ?? now),
+        browser_detached_for_ms: session.browserDetachedAtMs == null
+          ? null
+          : Math.max(0, now - session.browserDetachedAtMs),
         live_after: this._liveSessions().length,
       },
       "codex session reaped",
@@ -4572,13 +4665,16 @@ export class CodexStreamBridge extends EventEmitter {
    * Stage 5: セッションの周期 reconcile（state loop から ~5s 毎に実行）。以下を 1 パスで行う:
    *   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 **K 本（現行の既定 3）**
+   *   2. **browser detached**: 最後の browser 離脱（または死端末 GC）後、短期 TTL（既定30分）を
+   *      超えた非 protected session → app-server ごと reap。成功した sibling traffic は窓を更新する。
+   *   3. **long idle**: 非 busy が idle TTL（既定 7 日）無活性 → reap（warm 保持の期限切れ）。
+   *   4. **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 いずれの対象にもならない（走行中ターンを絶対に殺さない）。
+   * protected session は 1〜4 いずれの通常回収対象にもならない。ただし stuck turn は保護失効後、
+   * browser-detached TTL より先に stuck-turn 理由で回収し、既存の診断意味を維持する。
    *
    * 旧 `gcAbandonedSessions`（1h 無活性一律 reap）を置換。detach 済み warm セッションを 1h で
    * 殺していた挙動を廃し、上限＋長 TTL に一本化した。main.mjs の state loop 呼び出しは
@@ -4597,15 +4693,21 @@ export class CodexStreamBridge extends EventEmitter {
     for (const session of this._liveSessions()) {
       if (this._isProtected(session, now)) continue
       const idle = now - (session.lastActivityMs ?? now)
+      const browserDetachedFor = session.browserDetachedAtMs == null
+        ? null
+        : now - session.browserDetachedAtMs
       if (session.activeTurnId && idle > this._stuckTurnTtlMs) {
         this._reapSession(session, now, "stuck-turn")
         reaped += 1
+      } else if (browserDetachedFor !== null && browserDetachedFor > this._detachedReapTtlMs) {
+        this._reapSession(session, now, "browser-detached-ttl")
+        reaped += 1
       } else if (!session.activeTurnId && idle > this._detachTtlMs) {
         this._reapSession(session, now, "idle-ttl")
         reaped += 1
       }
     }
-    // 3: warm 境界（per-cwd=K / N-cwd LRU）を適用（stuck/idle reap 後の生存数で判定）。
+    // 4: warm 境界（per-cwd=K / N-cwd LRU）を適用（stuck/idle reap 後の生存数で判定）。
     reaped += this._reconcileWarmBounds(now, "warm-bounds")
     return reaped
   }

package/src/main.mjs

@@ -4702,7 +4702,8 @@ export async function dispatch(msg, ctx) {
       case "codex.keepalive":
         // ブラウザが Codex チャットを開いている間の生存シグナル。
         // 閲覧中に gcAbandonedSessions (既定 1h 無通信) が
-        // 誤爆するのを防ぐ。未知 stream_id は false が返るだけ (無害な no-op)。
+        // 誤爆するのを防ぐ。未知/dead stream_id と、明示 detach 後に残った旧 interval callback は
+        // attach まで false（無害な no-op）。死端末 GC 起因の detach は live keepalive で復帰できる。
         if (!ctx.codexBridge) return
         ctx.codexBridge.keepalive({ stream_id: msg.stream_id })
         return