@cocorograph/hub-agent 0.8.44 → 0.8.46

package/package.json

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

package/src/codex-stream-bridge.mjs

@@ -136,6 +136,14 @@ const STUCK_TURN_TTL_MS = readPositiveIntEnv(
   60 * 60 * 1000,
 )
 
+// 子 turn の停止 handle 台帳を回収できる最短 age（既定 4h）。通常は保護 TTL（既定 1h）を
+// 先に超えて protectionExpiredAtMs が立ち、その後も長時間 heartbeat が無い record だけを回収する。
+// つまり保護 TTL 直後には停止可能性を残し、台帳だけが永久化することも避ける。設定で保護 TTL を
+// 4h 以上へ延ばした場合も、protectionExpiredAtMs が立つまでは active handle を回収しない。
+const SUBAGENT_INTERRUPT_RECORD_TTL_MS = 4 * 60 * 60 * 1000
+/** 個別停止中に後発 descendant を拾う再走査回数。無制限 spawn に応答を占有されない上限。 */
+const SUBAGENT_INTERRUPT_SCAN_ROUNDS = 3
+
 // 案B (T06542): 死端末 GC の TTL。多端末購読で、応答を返さなくなった（クラッシュ / タブ強制終了で
 // codex.detach を送れなかった）購読端末を購読集合から掃除する閾値。claude-stream-bridge.mjs の
 // DEAD_TERMINAL_TTL_MS（既定 1h）と同型・同既定。stuck turn TTL とは別軸（あちらはターン固着、
@@ -774,6 +782,8 @@ export class CodexStreamBridge extends EventEmitter {
       subagentInterruptRegistry: new Map(),
       /** dynamicToolCall(spawn_agent) の item.id -> 表示メタデータ。 */
       subagentSpawnMetadata: new Map(),
+      /** invalid background の同一 item 再送で warn を重複させない bounded set。 */
+      subagentInvalidBackgroundWarned: new Set(),
       /** live subAgentActivity の spawn metadata miss を child thread/read で補完する
        * single-flight 台帳。key = agentThreadId, value = 進行中 Promise。 */
       subagentRoleReads: new Map(),
@@ -1668,8 +1678,12 @@ export class CodexStreamBridge extends EventEmitter {
       description:
         metadata?.description || previous?.description || subagentFallbackName(agentPath),
       prompt: metadata?.prompt || previous?.prompt || "",
-      // background は spawn 時に確定する属性。後続通知に metadata が無くても true を失わない。
-      background: metadata?.background === true || previous?.background === true,
+      // metadata に明示 boolean があるときは後着値を権威とする。metadata miss は spawn の
+      // background 省略既定と同じ true に倒し、明示 false だけが訂正する。
+      background:
+        typeof metadata?.background === "boolean"
+          ? metadata.background
+          : previous?.background ?? true,
       atMs: transitionAtMs,
       startedAtMs:
         phase === "started" && terminalSubagentPhase(previous?.phase)
@@ -1791,12 +1805,35 @@ export class CodexStreamBridge extends EventEmitter {
       if (!args) return
       const agent = typeof args.agent_type === "string" ? args.agent_type.trim() : ""
       const agentExplicit = agent.length > 0
+      // 現行 Codex schema は background を送らず spawn は非同期で返るため、省略・非 boolean は
+      // 背景扱いにする。invalid 値は本文を永続ログへ出さず、型と item id だけを記録する。
+      const hasBackground = Object.prototype.hasOwnProperty.call(args, "background")
+      const background = typeof args.background === "boolean" ? args.background : true
+      if (hasBackground && typeof args.background !== "boolean") {
+        if (!session.subagentInvalidBackgroundWarned.has(item.id)) {
+          session.subagentInvalidBackgroundWarned.add(item.id)
+          while (session.subagentInvalidBackgroundWarned.size > 256) {
+            session.subagentInvalidBackgroundWarned.delete(
+              session.subagentInvalidBackgroundWarned.values().next().value,
+            )
+          }
+          const backgroundType = Array.isArray(args.background)
+            ? "array"
+            : args.background === null
+              ? "null"
+              : typeof args.background
+          this.logger?.warn?.(
+            { item_id: item.id, background_type: backgroundType },
+            "codex subagent spawn background must be boolean; defaulting to background",
+          )
+        }
+      }
       const metadata = {
         agent: agentExplicit ? agent : null,
         agentExplicit,
         description: typeof args.task_name === "string" && args.task_name ? args.task_name : null,
         prompt: typeof args.message === "string" ? args.message : null,
-        background: args.background === true,
+        background,
       }
       session.subagentSpawnMetadata.set(item.id, metadata)
       while (session.subagentSpawnMetadata.size > 256) {
@@ -1892,32 +1929,52 @@ export class CodexStreamBridge extends EventEmitter {
     }
     const { parentThreadId, ownerTurnId, ...mutableFields } = fields
     Object.assign(record, mutableFields, { lastSeenAtMs: now })
+    delete record.protectionExpiredAtMs
     if (!record.parentThreadId && typeof parentThreadId === "string" && parentThreadId) {
       record.parentThreadId = parentThreadId
     }
     if (!record.ownerTurnId && typeof ownerTurnId === "string" && ownerTurnId) {
       record.ownerTurnId = ownerTurnId
     }
-    const expiredBefore = now - 4 * 60 * 60 * 1000
+    this._sweepSubagentInterruptRegistry(session, now)
+    return record
+  }
+
+  /** delta hot path。対象 record だけを更新し、全台帳 sweep/sort は行わない。 */
+  _heartbeatSubagentInterruptRecord(session, threadId, now = Date.now()) {
+    const record = session?.subagentInterruptRegistry?.get(threadId)
+    if (!record) return null
+    record.lastSeenAtMs = now
+    delete record.protectionExpiredAtMs
+    return record
+  }
+
+  /** lifecycle 更新時だけ、完了済みまたは保護失効済みの古い停止 record と上限超過を回収する。 */
+  _sweepSubagentInterruptRegistry(session, now = Date.now()) {
+    const registry = session?.subagentInterruptRegistry
+    if (!registry) return
+    const expiredBefore = now - SUBAGENT_INTERRUPT_RECORD_TTL_MS
     for (const [id, candidate] of session.subagentInterruptRegistry) {
-      if (candidate.turnId === null && candidate.lastSeenAtMs < expiredBefore) {
+      const evictable = candidate.turnId === null || candidate.protectionExpiredAtMs !== undefined
+      if (evictable && candidate.lastSeenAtMs < expiredBefore) {
         this._evictSubagentInterruptRecord(session, id, candidate)
       }
     }
-    while (session.subagentInterruptRegistry.size > 256) {
-      const oldest = [...session.subagentInterruptRegistry.entries()]
-        .filter(([, candidate]) => candidate.turnId === null)
+    while (registry.size > 256) {
+      const oldest = [...registry.entries()]
+        .filter(([, candidate]) => (
+          candidate.turnId === null || candidate.protectionExpiredAtMs !== undefined
+        ))
         .sort((a, b) => a[1].lastSeenAtMs - b[1].lastSeenAtMs)[0]
       if (!oldest) {
         this.logger?.warn?.(
-          { size: session.subagentInterruptRegistry.size, limit: 256 },
+          { size: registry.size, limit: 256 },
           "codex subagent interrupt registry exceeds limit with all records active",
         )
         break
       }
       this._evictSubagentInterruptRecord(session, oldest[0], oldest[1])
     }
-    return record
   }
 
   _evictSubagentInterruptRecord(session, threadId, record) {
@@ -1927,25 +1984,50 @@ export class CodexStreamBridge extends EventEmitter {
     session.subagentInterruptRegistry.delete(threadId)
   }
 
+  /**
+   * 子 record から root までの所有チェーンを辿る。cycle は呼び出し側が停止対象から除外する。
+   * @returns {{ownerRootTurnId:string|null, hasBackgroundAncestor:boolean, lineage:string[], cycle:boolean}}
+   */
   _subagentOwnership(session, record) {
     const visited = new Set()
+    const lineage = []
     let current = record
     let hasBackgroundAncestor = false
     while (current) {
-      if (visited.has(current.threadId)) return { ownerRootTurnId: null, hasBackgroundAncestor }
+      if (visited.has(current.threadId)) {
+        return { ownerRootTurnId: null, hasBackgroundAncestor, lineage, cycle: true }
+      }
       visited.add(current.threadId)
+      lineage.push(current.threadId)
+      // background は表示台帳の省略既定を含む。親チェーン上の背景 root を一度検出したら、
+      // capability 対応 browser の root interrupt では部分木全体を残す。
       if (session.subagents.get(current.threadId)?.background === true) {
         hasBackgroundAncestor = true
       }
       if (current.parentThreadId === session.threadId) {
-        return { ownerRootTurnId: current.ownerTurnId || null, hasBackgroundAncestor }
+        return {
+          ownerRootTurnId: current.ownerTurnId || null,
+          hasBackgroundAncestor,
+          lineage,
+          cycle: false,
+        }
       }
       current = session.subagentInterruptRegistry.get(current.parentThreadId)
     }
-    return { ownerRootTurnId: null, hasBackgroundAncestor }
+    return { ownerRootTurnId: null, hasBackgroundAncestor, lineage, cycle: false }
   }
 
-  async _interruptSubagent(session, record, targetRootTurnId) {
+  async _interruptSubagent(
+    session,
+    record,
+    targetRootTurnId,
+    {
+      allowBackground = false,
+      requireRootOwnership = true,
+      expectedDelegationId = null,
+      expectedAncestorThreadId = null,
+    } = {},
+  ) {
     const displayed = session.subagents.get(record.threadId)
     const backgroundKnown = displayed ? typeof displayed.background === "boolean" : false
     const background = backgroundKnown ? displayed.background : null
@@ -1957,11 +2039,21 @@ export class CodexStreamBridge extends EventEmitter {
       const mismatch = parseTurnMismatch(reason)
       const latestRecord = session.subagentInterruptRegistry.get(record.threadId)
       const latestOwnership = latestRecord ? this._subagentOwnership(session, latestRecord) : null
+      const latestDisplayed = session.subagents.get(record.threadId)
+      const lineageStillMatches = !expectedAncestorThreadId || (
+        latestOwnership &&
+        !latestOwnership.cycle &&
+        latestOwnership.lineage.includes(expectedAncestorThreadId)
+      )
       if (
         mismatch &&
         latestRecord?.turnId === mismatch.found &&
-        latestOwnership?.ownerRootTurnId === targetRootTurnId &&
-        !latestOwnership.hasBackgroundAncestor
+        (!expectedDelegationId || latestDisplayed?.delegationId === expectedDelegationId) &&
+        lineageStillMatches &&
+        (!requireRootOwnership || (
+          latestOwnership?.ownerRootTurnId === targetRootTurnId &&
+          (allowBackground || !latestOwnership.hasBackgroundAncestor)
+        ))
       ) {
         try {
           await session.client.request("turn/interrupt", {
@@ -1986,6 +2078,15 @@ export class CodexStreamBridge extends EventEmitter {
           }
         }
       }
+      if (mismatch && latestRecord?.turnId === mismatch.found && !lineageStillMatches) {
+        this.logger?.warn?.(
+          {
+            thread_id: record.threadId,
+            expected_ancestor_thread_id: expectedAncestorThreadId,
+          },
+          "codex subagent interrupt retry skipped after ownership changed",
+        )
+      }
       return {
         threadId: record.threadId,
         turnId: record.turnId,
@@ -1997,6 +2098,111 @@ export class CodexStreamBridge extends EventEmitter {
     }
   }
 
+  /**
+   * 対象子と active descendants を停止する。対象 RPC 待ちや子停止中に増えた descendant も
+   * 最大3ラウンド再走査する。上限後の未処理 active turn は skipped へ明示し、無限 spawn に
+   * WebSocket 応答を占有されないようにする。
+   * @returns {Promise<object>} targetOutcome/targetReason は対象自身、outcome は部分木全体の結果。
+   */
+  async interruptSubagent({ stream_id, delegation_id, agent_thread_id }) {
+    const session = this._require(stream_id)
+    this._touch(session, stream_id)
+    const displayed = session.subagents.get(agent_thread_id)
+    if (!displayed || displayed.delegationId !== delegation_id) {
+      return { outcome: "failed", reason: "subagent_not_found", children: [], skipped: [] }
+    }
+    const record = session.subagentInterruptRegistry.get(agent_thread_id)
+    const result = record?.turnId
+      ? await this._interruptSubagent(session, { ...record }, null, {
+          allowBackground: true,
+          requireRootOwnership: false,
+          expectedDelegationId: delegation_id,
+        })
+      : { outcome: "no_active_turn", reason: "subagent_not_active" }
+    const children = []
+    const processedTurns = new Set()
+    const warnedCycleThreads = new Set()
+    const turnKey = (candidate) => `${candidate.threadId}\u0000${candidate.turnId}`
+    const activeDescendants = () => [...session.subagentInterruptRegistry.values()]
+      .filter((candidate) => {
+        if (!candidate?.turnId || candidate.threadId === agent_thread_id) return false
+        const ownership = this._subagentOwnership(session, candidate)
+        if (ownership.cycle) {
+          if (!warnedCycleThreads.has(candidate.threadId)) {
+            warnedCycleThreads.add(candidate.threadId)
+            this.logger?.warn?.(
+              { thread_id: candidate.threadId },
+              "codex subagent descendant skipped because ownership chain is cyclic",
+            )
+          }
+          return false
+        }
+        return ownership.lineage.includes(agent_thread_id)
+      })
+
+    for (let round = 0; round < SUBAGENT_INTERRUPT_SCAN_ROUNDS; round += 1) {
+      const descendants = activeDescendants()
+        .filter((candidate) => !processedTurns.has(turnKey(candidate)))
+        .map((candidate) => ({ ...candidate }))
+      if (descendants.length === 0) break
+      for (const descendant of descendants) {
+        const key = turnKey(descendant)
+        // 同じ round の先行 RPC 待ち中にも lineage/turn は動き得るため、送信直前にも live 台帳で確認する。
+        const current = session.subagentInterruptRegistry.get(descendant.threadId)
+        const ownership = current ? this._subagentOwnership(session, current) : null
+        if (
+          !current?.turnId ||
+          current.turnId !== descendant.turnId ||
+          ownership?.cycle ||
+          !ownership?.lineage.includes(agent_thread_id)
+        ) {
+          this.logger?.warn?.(
+            { thread_id: descendant.threadId, round: round + 1 },
+            "codex subagent descendant skipped after ownership changed before interrupt",
+          )
+          continue
+        }
+        processedTurns.add(key)
+        const childResult = await this._interruptSubagent(session, { ...current }, null, {
+          allowBackground: true,
+          requireRootOwnership: false,
+          expectedAncestorThreadId: agent_thread_id,
+        })
+        children.push(childResult)
+        if (childResult?.threadId && childResult?.turnId) {
+          processedTurns.add(turnKey(childResult))
+        }
+      }
+    }
+    const targetOutcome = result.outcome
+    const descendantInterrupted = children.some((child) => child.outcome === "interrupted")
+    const outcome =
+      targetOutcome === "no_active_turn" && descendantInterrupted
+        ? "interrupted"
+        : targetOutcome
+    const response = {
+      ...result,
+      outcome,
+      targetOutcome,
+      delegationId: displayed.delegationId,
+      agentThreadId: displayed.agentThreadId,
+      children,
+      skipped: activeDescendants()
+        .filter((candidate) => !processedTurns.has(turnKey(candidate)))
+        .map((candidate) => ({
+          threadId: candidate.threadId,
+          turnId: candidate.turnId,
+          reason: "spawned_during_interrupt",
+        })),
+    }
+    // 部分木として成功した応答に failure 用 reason を残さない。対象単体の理由は別軸で保持する。
+    if (outcome === "interrupted" && result.reason) {
+      delete response.reason
+      response.targetReason = result.reason
+    }
+    return response
+  }
+
   _subagentSnapshots(session, history = session?.historyItems) {
     const items = Array.isArray(history) ? history : []
     const startedIndexByThread = new Map()
@@ -2077,21 +2283,47 @@ export class CodexStreamBridge extends EventEmitter {
               { agentPath: record.agentPath, metadata, atMs: lastTurnAtMs },
               { emit: false },
             )
-          } else if (
-            thread?.status?.type === "active" &&
-            (!lastTurn || lastTurn.status === "inProgress")
-          ) {
-            this._setSubagentPhase(
-              session,
-              record.agentThreadId,
-              "started",
-              {
-                agentPath: record.agentPath,
-                metadata,
-                atMs: record.startedAtMs,
-              },
-              { emit: false },
-            )
+          } else if (thread?.status?.type === "active") {
+            if (
+              lastTurn?.status === "inProgress" &&
+              typeof lastTurn.id === "string" &&
+              lastTurn.id
+            ) {
+              this._setSubagentPhase(
+                session,
+                record.agentThreadId,
+                "started",
+                {
+                  agentPath: record.agentPath,
+                  metadata,
+                  atMs: record.startedAtMs,
+                },
+                { emit: false },
+              )
+              this._touchSubagentInterruptRecord(session, record.agentThreadId, {
+                turnId: lastTurn.id,
+                startedAtMs: lastTurnAtMs,
+              })
+            } else {
+              // active 表示なのに停止 RPC に必要な turn ID が無い。running と表示すると停止可能な
+              // capability を偽るため、cold snapshot は正直な terminal へ倒す。
+              this._setSubagentPhase(
+                session,
+                record.agentThreadId,
+                "failed",
+                { agentPath: record.agentPath, metadata, atMs: lastTurnAtMs },
+                { emit: false },
+              )
+              this.logger?.warn?.(
+                {
+                  thread_id: session.threadId,
+                  subagent_thread_id: record.agentThreadId,
+                  child_status: thread?.status?.type || null,
+                  last_turn_status: lastTurn?.status || null,
+                },
+                "codex active subagent resume lacked an interruptible turn id; marked failed",
+              )
+            }
           } else {
             session.subagents.delete(record.agentThreadId)
           }
@@ -2168,6 +2400,14 @@ export class CodexStreamBridge extends EventEmitter {
     // ※ hub-agent 再起動 (cold resume) では historyItems が揮発するため青バブルへ戻る (claude の
     //    jsonl at-rest と同じ許容範囲。source 永続マップは TTL/ID 再利用の複雑さに見合わないため不採用)。
     const eventThreadId = msg?.params?.threadId
+    if (
+      typeof eventThreadId === "string" &&
+      eventThreadId !== session.threadId &&
+      session.subagentInterruptRegistry.has(eventThreadId)
+    ) {
+      // lifecycle 以外の message/reasoning/tool delta も子 turn の生存証跡。root 通知は更新しない。
+      this._heartbeatSubagentInterruptRecord(session, eventThreadId)
+    }
     const taggedParams = this._tagInjectSourceOnItem(session, msg)
     let effectiveParams = taggedParams || msg.params
     const childRecord =
@@ -2350,6 +2590,7 @@ export class CodexStreamBridge extends EventEmitter {
 
   _onClientExit(session, info) {
     if (session.dead) return
+    this._markRunningSubagentsKilled(session)
     session.dead = true
     // round3: app-server が死んだら barrier を解除し queue を reject する（promise 宙吊り防止）。
     this._settleTurnActiveWaiter(session)
@@ -2614,15 +2855,17 @@ export class CodexStreamBridge extends EventEmitter {
 
   /**
    * @returns {Promise<
-   *   | { outcome: "interrupted", turnId: string, corrected: boolean }
-   *   | { outcome: "no_active_turn" }
-   *   | { outcome: "failed", reason: string }
+   *   ({children: object[], skipped: object[]} & (
+   *     | { outcome: "interrupted", turnId: string, corrected: boolean }
+   *     | { outcome: "no_active_turn" }
+   *     | { outcome: "failed", reason: string }
+   *   ))
    * >}
    */
-  async interrupt({ stream_id }) {
+  async interrupt({ stream_id, preserve_background_subagents = false }) {
     const session = this._require(stream_id)
     this._touch(session, stream_id)
-    if (!session.activeTurnId) return { outcome: "no_active_turn", children: [] }
+    if (!session.activeTurnId) return { outcome: "no_active_turn", children: [], skipped: [] }
 
     const turnId = session.activeTurnId
     let attemptedRootTurnId = turnId
@@ -2665,13 +2908,35 @@ export class CodexStreamBridge extends EventEmitter {
     const children = []
     const targetRootTurnId = attemptedRootTurnId
     const interruptSnapshot = [...session.subagentInterruptRegistry.values()].map((record) => ({ ...record }))
+    // skipped は「今回の owner turn の停止候補」ではなく、応答時点で実際に継続中の
+    // root 直下 background 一覧。frontend の「継続中」表示と一致させるため owner に依存しない。
+    const skipped = preserve_background_subagents === true
+      ? interruptSnapshot.flatMap((record) => {
+          const displayed = session.subagents.get(record.threadId)
+          if (
+            !record.turnId ||
+            record.parentThreadId !== session.threadId ||
+            displayed?.background !== true
+          ) return []
+          return [{
+            threadId: record.threadId,
+            delegationId: displayed.delegationId,
+            reason: "background",
+          }]
+        })
+      : []
     for (const record of interruptSnapshot) {
       if (!record.turnId) continue
       const ownership = this._subagentOwnership(session, record)
-      if (ownership.ownerRootTurnId !== targetRootTurnId || ownership.hasBackgroundAncestor) continue
-      children.push(await this._interruptSubagent(session, { ...record }, targetRootTurnId))
+      if (preserve_background_subagents === true && ownership.hasBackgroundAncestor) {
+        continue
+      }
+      if (ownership.ownerRootTurnId !== targetRootTurnId) continue
+      children.push(await this._interruptSubagent(session, { ...record }, targetRootTurnId, {
+        allowBackground: preserve_background_subagents !== true,
+      }))
     }
-    return { ...result, children }
+    return { ...result, children, skipped }
   }
 
   /** サーバー発の承認/入力要求への応答。result の shape は method ごとに呼び出し側が組み立てる。 */
@@ -3298,13 +3563,57 @@ export class CodexStreamBridge extends EventEmitter {
     // ⚠️ activeTurnId の判定より **前** に置くこと。背景コマンドが残るのは turn/completed の
     //    後（= activeTurnId が null に戻った後）なので、下の early return を通すと届かない。
     if (this._hasLiveExec(session, now)) return true
+    if (this._hasLiveSubagentTurn(session, now)) return true
     if (!session.activeTurnId) return false
     return now - (session.lastActivityMs ?? now) <= this._stuckTurnTtlMs
   }
 
+  _hasLiveSubagentTurn(session, now = Date.now()) {
+    const registry = session?.subagentInterruptRegistry
+    if (!registry || registry.size === 0) return false
+    let active = false
+    for (const record of registry.values()) {
+      if (!record?.turnId) continue
+      const elapsed = now - (record.lastSeenAtMs ?? 0)
+      if (elapsed <= this._stuckTurnTtlMs) {
+        active = true
+        continue
+      }
+      // TTL は warm-session 保護だけを失効させる。停止 RPC に必要な turnId は破壊しない。
+      // 長時間無出力の正常な子でも、明示停止を受けたときに同じ handle を利用できるようにする。
+      if (record.protectionExpiredAtMs === undefined) {
+        record.protectionExpiredAtMs = now
+        this.logger?.warn?.(
+          {
+            stream_id: session.stream_id,
+            thread_id: record.threadId,
+            turn_id: record.turnId,
+            elapsed_ms: elapsed,
+            ttl_ms: this._stuckTurnTtlMs,
+          },
+          "codex subagent turn protection expired",
+        )
+      }
+    }
+    return active
+  }
+
+  _markRunningSubagentsKilled(session, atMs = Date.now()) {
+    for (const record of session?.subagents?.values?.() || []) {
+      if (record.phase !== "started") continue
+      this._setSubagentPhase(
+        session,
+        record.agentThreadId,
+        "killed",
+        { agentPath: record.agentPath, atMs },
+      )
+    }
+  }
+
   /** 実際に app-server を止めてセッションを撤去し exit を emit する（reconcile 共通処理）。 */
   _reapSession(session, now, reason) {
     if (session.dead) return
+    this._markRunningSubagentsKilled(session, now)
     session.dead = true
     // round3: reap した session の barrier を解除し queue を reject する（promise 宙吊り防止）。
     this._settleTurnActiveWaiter(session)
@@ -3492,6 +3801,7 @@ export class CodexStreamBridge extends EventEmitter {
   shutdown() {
     // 案B: distinct session で走査（多対一 Map の重複 stop を避ける）。
     for (const session of this._liveSessions()) {
+      this._markRunningSubagentsKilled(session)
       session.dead = true
       // round3: shutdown で barrier を解除し queue 入力を reject（promise 宙吊り防止）。
       this._settleTurnActiveWaiter(session)

package/src/main.mjs

@@ -2123,6 +2123,9 @@ export function buildCodexReadyPayload(streamId, info, queueState) {
     thread_status: info?.threadStatus || null,
     last_turn_status: info?.lastTurnStatus || null,
     queue_state: queueState,
+    // Browser は旧 hub-agent との混在期間、この明示 capability が true のときだけ
+    // 子 thread の個別停止 UI を有効化する。省略は未対応を意味する。
+    supports_subagent_interrupt: true,
   }
   if (Array.isArray(info?.subagents)) {
     payload.subagents = info.subagents.map((subagent) => ({
@@ -3249,26 +3252,69 @@ export function handleCodexChatInput(msg, ctx) {
   return p
 }
 
+/**
+ * codex.interrupt を root / individual へ振り分ける。
+ * - delegation_id と agent_thread_id が非空文字列なら individual（request_id 必須・echo する）
+ * - 両 ID が欠落または null なら root（現 frontend 契約。request_id は相関に使わず常に null）
+ * - 片方だけ、または非 null の不正値が混ざれば individual ID validation error
+ */
 export async function handleCodexInterrupt(msg, ctx) {
   let result
-  if (!ctx.codexBridge) {
-    result = { outcome: "failed", reason: "bridge_unavailable", children: [] }
+  const hasDelegationId = typeof msg.delegation_id === "string" && msg.delegation_id.length > 0
+  const hasAgentThreadId = typeof msg.agent_thread_id === "string" && msg.agent_thread_id.length > 0
+  const hasEitherId = msg.delegation_id != null || msg.agent_thread_id != null
+  const isSubagentInterrupt = hasDelegationId && hasAgentThreadId
+  const hasRequestId = typeof msg.request_id === "string" && msg.request_id.length > 0
+  if (hasEitherId && !(hasDelegationId && hasAgentThreadId)) {
+    result = { outcome: "failed", reason: "invalid_subagent_interrupt_ids", children: [], skipped: [] }
+  } else if (isSubagentInterrupt && !hasRequestId) {
+    result = { outcome: "failed", reason: "invalid_subagent_interrupt_request_id", children: [], skipped: [] }
+  } else if (!ctx.codexBridge) {
+    result = { outcome: "failed", reason: "bridge_unavailable", children: [], skipped: [] }
   } else {
     try {
-      result = await ctx.codexBridge.interrupt({ stream_id: msg.stream_id })
-      if (result.outcome === "failed") {
+      const bridgeResult = hasDelegationId
+        ? await ctx.codexBridge.interruptSubagent({
+            stream_id: msg.stream_id,
+            delegation_id: msg.delegation_id,
+            agent_thread_id: msg.agent_thread_id,
+          })
+        : await ctx.codexBridge.interrupt({
+            stream_id: msg.stream_id,
+            preserve_background_subagents: msg.preserve_background_subagents === true,
+          })
+      const validOutcome = ["interrupted", "failed", "no_active_turn"].includes(
+        bridgeResult?.outcome,
+      )
+      if (!bridgeResult || typeof bridgeResult !== "object" || Array.isArray(bridgeResult) || !validOutcome) {
+        ctx.logger?.warn?.(
+          {
+            bridge_result_type: Array.isArray(bridgeResult) ? "array" : typeof bridgeResult,
+            bridge_outcome: typeof bridgeResult?.outcome === "string" ? bridgeResult.outcome : null,
+          },
+          "codex.interrupt bridge returned an invalid result",
+        )
+        result = { outcome: "failed", reason: "invalid_bridge_result", children: [], skipped: [] }
+      } else {
+        result = {
+          ...bridgeResult,
+          children: Array.isArray(bridgeResult.children) ? bridgeResult.children : [],
+          skipped: Array.isArray(bridgeResult.skipped) ? bridgeResult.skipped : [],
+        }
+      }
+      if (result.outcome === "failed" && result.reason !== "invalid_bridge_result") {
         ctx.logger?.warn?.({ err: result.reason }, "codex.interrupt failed")
       }
     } catch (err) {
       const reason = err?.message || String(err)
       ctx.logger?.warn?.({ err: reason }, "codex.interrupt failed")
-      result = { outcome: "failed", reason, children: [] }
+      result = { outcome: "failed", reason, children: [], skipped: [] }
     }
   }
   ctx.client.send({
     type: "codex.interrupt.response",
     stream_id: msg.stream_id,
-    request_id: msg.request_id ?? null,
+    request_id: isSubagentInterrupt && hasRequestId ? msg.request_id : null,
     ...result,
   })
 }

package/src/usage.mjs

@@ -1482,6 +1482,41 @@ function threadIdFromRolloutFilename(fp) {
 const CODEX_ROLLOUT_HEAD_CHUNK_BYTES = 32 * 1024
 const CODEX_ROLLOUT_PREVIEW_MAX_BYTES = 1024 * 1024
 
+// sessionsDir ごとの派生インデックス。rollout 自体が正本なので永続化は不要。
+// _codexTokenCountMemo と同じ mtime+size 無効化規約で、変更ファイルだけを再解析する。
+// 共通 helper 化は usage 集計側への回帰範囲を広げるため、一覧用 index として独立させる。
+const _codexThreadListIndex = new Map() // base → Map<fp, {mtimeMs,size,lastSeenAt,meta}>
+const _codexThreadListLastWarnAt = new Map() // base → wall-clock ms
+const CODEX_THREAD_LIST_LOG_INTERVAL_MS = 5 * 60 * 1000
+const CODEX_THREAD_LIST_STALE_ENTRY_MS = 24 * 60 * 60 * 1000
+const CODEX_ROLLOUT_PARSE_IO_ERROR = Symbol("codex-rollout-parse-io-error")
+
+function sameCodexThreadListFingerprint(a, b) {
+  return a?.mtimeMs === b?.mtimeMs && a?.size === b?.size
+}
+
+function codexThreadListMetaRank(meta) {
+  if (meta?.preview_complete && meta.cwd && meta.preview) return 3
+  if (meta?.preview_complete) return 2
+  return meta ? 1 : 0
+}
+
+// observed 後に別呼び出しが新 fingerprint / complete meta を置いた場合は降格させない。
+function commitCodexThreadListEntry(index, fp, observed, next) {
+  const current = index.get(fp)
+  if (current === observed) {
+    index.set(fp, next)
+    return
+  }
+  if (!current || !sameCodexThreadListFingerprint(current, next)) return
+  const meta =
+    codexThreadListMetaRank(next.meta) > codexThreadListMetaRank(current.meta)
+      ? next.meta
+      : current.meta
+  const merged = { ...current, lastSeenAt: Math.max(current.lastSeenAt, next.lastSeenAt), meta }
+  index.set(fp, merged)
+}
+
 /**
  * rollout の先頭から一覧用メタ (thread_id / cwd / preview) を取り出す。
  *
@@ -1492,9 +1527,9 @@ const CODEX_ROLLOUT_PREVIEW_MAX_BYTES = 1024 * 1024
  *
  * @param {string} fp
  * @param {string} expectedCwd cwd-scoped 一覧の対象。別 cwd は session_meta 読み取り後に早期終了。
- * @returns {Promise<{thread_id:string,cwd:string,preview:string}|null>}
+ * @returns {Promise<{thread_id:string,cwd:string,preview:string,preview_complete:boolean}|null|symbol>}
  */
-async function parseCodexRolloutHead(fp, expectedCwd = "") {
+async function parseCodexRolloutHead(fp, expectedCwd = "", testHooks = null) {
   let thread_id = threadIdFromRolloutFilename(fp)
   let cwd = ""
   let preview = ""
@@ -1502,6 +1537,7 @@ async function parseCodexRolloutHead(fp, expectedCwd = "") {
   const decoder = new StringDecoder("utf8")
   let pending = ""
   let offset = 0
+  let result
 
   const parseLine = (line) => {
     if (!line) return
@@ -1528,8 +1564,13 @@ async function parseCodexRolloutHead(fp, expectedCwd = "") {
   }
 
   try {
+    if (testHooks?.beforeHeaderOpen) await testHooks.beforeHeaderOpen(fp)
+    testHooks?.onHeaderOpen?.(fp)
+    if (testHooks?.failHeaderOpen?.(fp)) {
+      throw Object.assign(new Error("injected header open failure"), { code: "EIO" })
+    }
     fh = await fs.open(fp, "r")
-    while (offset < CODEX_ROLLOUT_PREVIEW_MAX_BYTES) {
+    scan: while (offset < CODEX_ROLLOUT_PREVIEW_MAX_BYTES) {
       const readSize = Math.min(
         CODEX_ROLLOUT_HEAD_CHUNK_BYTES,
         CODEX_ROLLOUT_PREVIEW_MAX_BYTES - offset,
@@ -1550,12 +1591,14 @@ async function parseCodexRolloutHead(fp, expectedCwd = "") {
         pending = pending.slice(newline + 1)
         parseLine(line)
         // session_meta は先頭行にある。別 workspace の候補に対して巨大な初期コンテキストを
-        // 読み進めないことで、maxScan が大きい場合も一覧走査コストを抑える。
+        // 読み進めないことで、初回の派生インデックス構築コストを抑える。
         if (cwd && expectedCwd && cwd !== expectedCwd) {
-          return thread_id ? { thread_id, cwd, preview } : null
+          result = thread_id ? { thread_id, cwd, preview, preview_complete: false } : null
+          break scan
         }
         if (cwd && preview) {
-          return thread_id ? { thread_id, cwd, preview } : null
+          result = thread_id ? { thread_id, cwd, preview, preview_complete: true } : null
+          break scan
         }
       }
 
@@ -1567,8 +1610,11 @@ async function parseCodexRolloutHead(fp, expectedCwd = "") {
         break
       }
     }
+    if (result === undefined) {
+      result = thread_id ? { thread_id, cwd, preview, preview_complete: true } : null
+    }
   } catch {
-    return null
+    result = CODEX_ROLLOUT_PARSE_IO_ERROR
   } finally {
     try {
       await fh?.close()
@@ -1577,20 +1623,22 @@ async function parseCodexRolloutHead(fp, expectedCwd = "") {
     }
   }
 
-  if (!thread_id) return null
-  return { thread_id, cwd, preview }
+  if (result !== CODEX_ROLLOUT_PARSE_IO_ERROR && testHooks?.afterHeaderParse) {
+    await testHooks.afterHeaderParse(fp, result)
+  }
+  return result
 }
 
 /**
  * cwd 配下の Codex thread 一覧を rollout の disk 走査だけで作る (app-server を spawn しない)。
  * 直近 lookbackDays の日付シャードから rollout-*.jsonl を集め、mtime 降順に並べ、header を
- * 読んで cwd 一致分を limit 件まで返す。返り値の shape は旧 listThreads と同一:
+ * 派生インデックスを更新してから cwd 一致分を limit 件まで返す。返り値の shape は旧 listThreads と同一:
  *   {thread_id, cwd, preview, updated_at_ms}[]
  *
  * ⚠️ rollout は「作成日」シャードに置かれ以後追記される。作成が lookbackDays より前で今日
  * resume された長寿命スレッドは窓外で拾えない (findCodexRolloutFile の高速パスと同じ限界)。
- * 一覧 (picker) 用途では直近が支配的なので許容。header 読み取り件数は maxScan で上限を掛け、
- * 打ち切ったら logger.warn で可視化する (silent truncation を避ける)。
+ * 一覧 (picker) 用途では直近が支配的なので許容。maxScan は既存 API 互換のため受け取っても
+ * 無視し、cwd ごとの一覧欠落を起こすグローバル走査上限には使わない。
  *
  * @returns {Promise<Array<{thread_id:string, cwd:string, preview:string, updated_at_ms:number}>>}
  */
@@ -1598,10 +1646,11 @@ export async function listCodexThreadsFromDisk({
   cwd,
   limit,
   lookbackDays = 180,
-  maxScan = 800,
   now = Date.now(),
   logger,
   sessionsDir,
+  // テスト専用。production 呼び出しでは指定しない。
+  _testHooks,
 } = {}) {
   // cwd-scoped picker 用。cwd 未指定なら「全 workspace を返す」ではなく空を返す (cross-review
   // major3: 空 cwd で全 workspace の rollout が混入するのを防ぐ。呼び出し側 frontend は常に cwd を
@@ -1610,13 +1659,16 @@ export async function listCodexThreadsFromDisk({
   // sessionsDir は self-describing read (Read-plane 案C ①) で呼び出し側が
   // 「リクエストの profile_id から解決した読み取り先」を明示注入する経路。
   // 未指定なら従来どおり env 由来の active (codexSessionsDir) にフォールバックする。
-  const base = sessionsDir || codexSessionsDir()
-  // 1. lookback 窓内の全 rollout を stat して {fp, mtimeMs} を集める。
+  const base = path.resolve(sessionsDir || codexSessionsDir())
+  const seenAt = _testHooks?.nowMs?.() ?? Date.now()
+  // 1. lookback 窓内の全 rollout を stat して {fp, mtimeMs, size} を集める。
   //    ⚠️ updated_at_ms (= mtime) 降順の契約を守るには「どれが更新新しいか」を知る必要があり、
   //    それには窓内の全 stat が要る (cross-review round2: 収集を作成日 shard 順で打ち切ると、
   //    作成が古く更新が新しい長寿命 rollout を落として mtime 降順に反する)。stat は 1 syscall で
-  //    安価かつ lookbackDays で有界。高コストな header open+read の方を maxScan で上限化する。
-  const candidates = [] // {fp, mtimeMs}
+  //    安価かつ lookbackDays で有界。header open+read は下の派生インデックスで変更分だけに抑える。
+  const candidates = [] // {fp, mtimeMs, size}
+  const discovered = new Set() // readdir で存在を確認できた fp (stat 一時失敗でも削除扱いにしない)
+  const scannedDirs = new Set()
   for (let i = 0; i < lookbackDays; i++) {
     const d = new Date(now - i * 24 * 60 * 60 * 1000)
     const y = String(d.getFullYear())
@@ -1625,27 +1677,97 @@ export async function listCodexThreadsFromDisk({
     const dir = path.join(base, y, m, day)
     const files = await fs.readdir(dir).catch(() => null)
     if (!files) continue
+    scannedDirs.add(dir)
     for (const f of files) {
       if (!f.startsWith("rollout-") || !f.endsWith(".jsonl")) continue
       const fp = path.join(dir, f)
+      discovered.add(fp)
       const st = await fs.stat(fp).catch(() => null)
-      if (st) candidates.push({ fp, mtimeMs: st.mtimeMs })
+      if (st) candidates.push({ fp, mtimeMs: st.mtimeMs, size: st.size })
     }
   }
-  // 2. 更新が新しい順 (mtime desc)。
+  // 2. 更新が新しい順 (mtime desc)。候補一覧自体は毎回取り直し、削除も検出する。
   candidates.sort((a, b) => b.mtimeMs - a.mtimeMs)
-  // 3. mtime 新しい順に header を読み、cwd 一致分を limit まで集める。header 読み (open+read) は
-  //    maxScan で上限化する。上限打ち切りは mtime 新しい側から読むので、直近のスレッドが優先的に残る。
+  let index = _codexThreadListIndex.get(base)
+  if (!index) {
+    index = new Map()
+    _codexThreadListIndex.set(base, index)
+  }
+  for (const fp of index.keys()) {
+    // 今回実際に走査できた shard 内の不在だけを削除扱いにする。短い lookback や別 now の
+    // 呼び出しが、走査範囲外の cache を消して互いに再openを誘発しないようにする。
+    if (scannedDirs.has(path.dirname(fp)) && !discovered.has(fp)) {
+      index.delete(fp)
+      _testHooks?.onIndexPrune?.(fp)
+    } else {
+      const entry = index.get(fp)
+      if (!discovered.has(fp) && seenAt - entry.lastSeenAt >= CODEX_THREAD_LIST_STALE_ENTRY_MS) {
+        index.delete(fp)
+        _testHooks?.onIndexPrune?.(fp)
+      }
+    }
+  }
+
+  // 3. 呼び出しローカル snapshot を候補取得時点の cache から作る。以後、並行呼び出しが
+  //    global index を prune / 更新しても、この呼び出しの出力は snapshot から安定して作れる。
+  const snapshot = new Map()
+  for (const { fp, mtimeMs, size } of candidates) {
+    const cached = index.get(fp)
+    if (cached && cached.mtimeMs === mtimeMs && cached.size === size) {
+      const seen = { ...cached, lastSeenAt: seenAt }
+      commitCodexThreadListEntry(index, fp, cached, seen)
+      // snapshot はこの呼び出しが観測した候補を正本にし、並行書戻しの成否に依存させない。
+      snapshot.set(fp, seen)
+    } else if (
+      cached?.meta?.preview_complete &&
+      cached.meta.cwd &&
+      cached.meta.preview &&
+      size > cached.size &&
+      mtimeMs >= cached.mtimeMs
+    ) {
+      // rollout は append-only。preview まで確定済みなら末尾追記で header は変わらないため、
+      // fingerprint だけ進める。truncate / mtime 巻戻し / preview 未完了は下で再解析する。
+      const appended = { mtimeMs, size, lastSeenAt: seenAt, meta: cached.meta }
+      commitCodexThreadListEntry(index, fp, cached, appended)
+      snapshot.set(fp, appended)
+    }
+  }
+
+  // 4. 新規・変更分だけ header を解析する。別 cwd は session_meta を得た時点で止め、
+  //    その cwd が後で要求された時に一度だけ preview まで補完する。一時 I/O 失敗は cache せず、
+  //    次 poll で再試行する。解析済み不正 header (meta=null) は fingerprint 不変なら再解析しない。
+  let parsedHeaders = 0
+  const headerParseStartedAt = Date.now()
+  for (const { fp, mtimeMs, size } of candidates) {
+    if (snapshot.has(fp)) continue
+    const observed = index.get(fp)
+    parsedHeaders++
+    const meta = await parseCodexRolloutHead(fp, cwd, _testHooks)
+    if (meta === CODEX_ROLLOUT_PARSE_IO_ERROR) continue
+    const entry = { mtimeMs, size, lastSeenAt: seenAt, meta }
+    commitCodexThreadListEntry(index, fp, observed, entry)
+    snapshot.set(fp, entry)
+  }
+
+  // 5. cwd で絞ってから mtime 降順・limit を適用する。グローバル候補数には左右されない。
   const out = []
-  let opened = 0
-  for (const { fp, mtimeMs } of candidates) {
+  let completedPreviews = 0
+  for (const { fp, mtimeMs, size } of candidates) {
     if (limit && out.length >= limit) break
-    if (opened >= maxScan) break
-    opened++
-    const meta = await parseCodexRolloutHead(fp, cwd)
+    const entry = snapshot.get(fp)
+    let meta = entry?.meta
     if (!meta) continue
-    // header の cwd が一致するものだけ (cwd 未読/不一致は除外 = 無関係スレッドの混入防止)。
     if (meta.cwd !== cwd) continue
+    if (!meta.preview_complete) {
+      const observed = index.get(fp)
+      completedPreviews++
+      meta = await parseCodexRolloutHead(fp, "", _testHooks)
+      if (meta === CODEX_ROLLOUT_PARSE_IO_ERROR) continue
+      const completeEntry = { mtimeMs, size, lastSeenAt: seenAt, meta }
+      commitCodexThreadListEntry(index, fp, observed, completeEntry)
+      snapshot.set(fp, completeEntry)
+      if (!meta || meta.cwd !== cwd) continue
+    }
     out.push({
       thread_id: meta.thread_id,
       cwd: meta.cwd,
@@ -1653,12 +1775,28 @@ export async function listCodexThreadsFromDisk({
       updated_at_ms: mtimeMs,
     })
   }
-  if (opened >= maxScan && (!limit || out.length < limit)) {
-    logger?.warn?.(
-      { opened, total: candidates.length, cwd, matched: out.length },
-      "listCodexThreadsFromDisk: maxScan で header 走査を打ち切り (mtime が更に古い側の一部が一覧に出ない可能性)",
+
+  const elapsedMs = Date.now() - headerParseStartedAt
+  const wallNow = Date.now()
+  const lastWarnAt = _codexThreadListLastWarnAt.get(base)
+  if (
+    typeof logger?.warn === "function" &&
+    (parsedHeaders + completedPreviews > 200 || elapsedMs > 1000) &&
+    (lastWarnAt === undefined || wallNow - lastWarnAt >= CODEX_THREAD_LIST_LOG_INTERVAL_MS)
+  ) {
+    _codexThreadListLastWarnAt.set(base, wallNow)
+    logger.warn(
+      {
+        cwd,
+        parsed_headers: parsedHeaders,
+        completed_previews: completedPreviews,
+        total_candidates: candidates.length,
+        elapsed_ms: elapsedMs,
+      },
+      "listCodexThreadsFromDisk: 派生インデックスの header 解析負荷が閾値超過",
     )
   }
+
   return out
 }
 

package/src/ws-client.mjs

@@ -143,6 +143,7 @@ export class WsClient extends EventEmitter {
     this.bundleStatus = {}
     this.bundleManifestPath = opts.bundleManifestPath || null
     this.bundleWatcher = null
+    this.bundleWatcherConnectionMeta = null
     this.bundleWatchDebounceTimer = null
     this.hostname = opts.hostname || os.hostname()
     this.platform = opts.platform || "unknown"
@@ -171,6 +172,10 @@ export class WsClient extends EventEmitter {
     this.lastRecvAt = 0
     // heartbeat tick の直前実発火時刻。スリープ復帰のジャンプ検知に使う。
     this.lastTickAt = 0
+    // close ログを接続世代ごとに完結させる。古い socket の close が遅れて届いても、
+    // 新しい接続の診断状態や timer を壊さないよう socket のクロージャに保持する。
+    this.connectionGeneration = 0
+    this.connectionMeta = this._newConnectionMeta(0)
   }
 
   /** WSS 接続を開始する。`stop()` まで自動で reconnect 続行。 */
@@ -183,14 +188,21 @@ export class WsClient extends EventEmitter {
       Authorization: `Bearer ${this.config.agent_id}:${this.config.agent_token}`,
     }
     const ws = new WebSocket(wsUrl, { headers })
+    const connectionMeta = this._newConnectionMeta(++this.connectionGeneration)
     this.ws = ws
+    this.connectionMeta = connectionMeta
 
-    ws.on("open", () => this._onOpen())
+    ws.on("open", () => {
+      if (!this._isActiveConnection(ws, connectionMeta)) return
+      this._onOpen(connectionMeta)
+    })
 
     ws.on("message", (data) => {
+      if (!this._isActiveConnection(ws, connectionMeta)) return
       // 何かを受信した = TCP は生きている。zombie 検知の鮮度を更新する
       // (parse 失敗でも「届いた」事実は生存の証拠なので先に記録する)。
       this.lastRecvAt = Date.now()
+      connectionMeta.lastRecvAt = this.lastRecvAt
       let msg
       try {
         msg = JSON.parse(data.toString("utf-8"))
@@ -202,13 +214,7 @@ export class WsClient extends EventEmitter {
     })
 
     ws.on("close", (code, reason) => {
-      this._clearStreamsSyncBarrier()
-      this._clearStableReset()
-      this._stopHeartbeat()
-      this._stopBundleWatcher()
-      this.logger?.info({ code, reason: reason?.toString() }, "ws close")
-      this.emit("close", { code, reason })
-      if (!this.stopped) this._scheduleReconnect()
+      this._onSocketClose(ws, connectionMeta, code, reason)
     })
 
     ws.on("error", (err) => {
@@ -216,7 +222,10 @@ export class WsClient extends EventEmitter {
       // Upgrade で CF/origin が 5xx を返した場合 (典型: "Unexpected server
       // response: 502") は、次回 reconnect の最低 backoff を引き上げる。
       // CF が 5xx を short-cache するため、1s 連発リトライは逆に詰まる。
-      if (/Unexpected server response: 5\d\d/.test(err?.message || "")) {
+      if (
+        this._isActiveConnection(ws, connectionMeta) &&
+        /Unexpected server response: 5\d\d/.test(err?.message || "")
+      ) {
         this.lastCloseWas5xx = true
       }
       this.emit("error", err)
@@ -235,14 +244,23 @@ export class WsClient extends EventEmitter {
    * test からも直接呼べるように method として切り出している (`ws.on("open")`
    * のクロージャだと spy しづらい)。
    */
-  _onOpen() {
+  _onOpen(connectionMeta = this.connectionMeta) {
     // open 自体が生存の証拠。直前接続の古い lastRecvAt で開幕直後に zombie 誤検知
     // しないようリセットする。⚠️ _armStableReset() の armedAt 捕捉より「前」に設定すること。
     // ack ベース判定 (lastRecvAt > armedAt) を初期状態で偽にするため (順序を逆にすると
     // armedAt < lastRecvAt となり「inbound 受信済み」と誤判定し、half-open でも backoff を
     // リセットしてしまう)。
-    this.lastRecvAt = Date.now()
-    this.lastTickAt = Date.now()
+    const now = Date.now()
+    this.lastRecvAt = now
+    this.lastTickAt = now
+    connectionMeta.openedAt = now
+    connectionMeta.lastRecvAt = 0
+    connectionMeta.lastTickAt = now
+    connectionMeta.lastTickGapMs = null
+    connectionMeta.lastHeartbeatAt = 0
+    connectionMeta.lastHeartbeatOk = null
+    connectionMeta.forceReconnectReason = null
+    connectionMeta.closeInitiator = null
     // backoff の即時リセットはしない。接続が STABLE_CONNECTION_MS 維持 + inbound 受信できてから
     // _armStableReset() でリセットする (open→即 close フラッピング時の再接続ストロボ対策)。
     // すぐ切れた / half-open の接続では backoff がリセットされず指数バックオフが効き続けるため、
@@ -275,8 +293,8 @@ export class WsClient extends EventEmitter {
       request_id: streamsSyncRequestId,
     })
     this._armStreamsSyncBarrier(streamsSyncRequestId)
-    this._startHeartbeat()
-    this._startBundleWatcher()
+    this._startHeartbeat(connectionMeta)
+    this._startBundleWatcher(connectionMeta)
     this.emit("open")
   }
 
@@ -419,6 +437,7 @@ export class WsClient extends EventEmitter {
     }
     if (this.ws) {
       try {
+        this.connectionMeta.closeInitiator = "client_stop"
         this.ws.close(1000, "client_stop")
       } catch {
         /* ignore */
@@ -430,6 +449,66 @@ export class WsClient extends EventEmitter {
   // internals
   // ------------------------------------------------------------
 
+  _newConnectionMeta(id) {
+    return {
+      id,
+      openedAt: 0,
+      lastRecvAt: 0,
+      lastTickAt: 0,
+      lastTickGapMs: null,
+      lastHeartbeatAt: 0,
+      lastHeartbeatOk: null,
+      forceReconnectReason: null,
+      closeInitiator: null,
+    }
+  }
+
+  _isActiveConnection(ws, connectionMeta) {
+    return this.ws === ws && this.connectionMeta === connectionMeta
+  }
+
+  _onSocketClose(ws, connectionMeta, code, reason) {
+    const now = Date.now()
+    const isActive = this._isActiveConnection(ws, connectionMeta)
+    this.logger?.info(
+      {
+        code,
+        reason: reason?.toString(),
+        connection_id: connectionMeta.id,
+        dur_s: connectionMeta.openedAt
+          ? Math.max(0, Math.round((now - connectionMeta.openedAt) / 100) / 10)
+          : null,
+        since_recv_s: connectionMeta.lastRecvAt
+          ? Math.max(0, Math.round((now - connectionMeta.lastRecvAt) / 100) / 10)
+          : null,
+        received_inbound: connectionMeta.lastRecvAt > 0,
+        last_heartbeat_at: connectionMeta.lastHeartbeatAt
+          ? new Date(connectionMeta.lastHeartbeatAt).toISOString()
+          : null,
+        last_heartbeat_ok: connectionMeta.lastHeartbeatOk,
+        last_tick_at: connectionMeta.lastTickAt
+          ? new Date(connectionMeta.lastTickAt).toISOString()
+          : null,
+        last_tick_gap_s: connectionMeta.lastTickGapMs == null
+          ? null
+          : Math.max(0, Math.round(connectionMeta.lastTickGapMs / 100) / 10),
+        force_reconnect_reason: connectionMeta.forceReconnectReason,
+        close_initiator: connectionMeta.closeInitiator,
+        stale_generation: !isActive,
+      },
+      "ws close",
+    )
+    // terminate 後の close は次世代の connect/open より遅れて届くことがある。
+    // 旧世代から現世代の heartbeat・barrier・watcher・reconnect を変更しない。
+    if (!isActive) return
+    this._clearStreamsSyncBarrier()
+    this._clearStableReset()
+    this._stopHeartbeat()
+    this._stopBundleWatcher()
+    this.emit("close", { code, reason })
+    if (!this.stopped) this._scheduleReconnect()
+  }
+
   _buildWsUrl() {
     const hub = this.config.hub_url.replace(/\/+$/, "")
     const scheme = hub.startsWith("https:") ? "wss:" : "ws:"
@@ -447,22 +526,39 @@ export class WsClient extends EventEmitter {
     }
   }
 
-  _startHeartbeat() {
+  _sendHeartbeat(connectionMeta, heartbeatAt = Date.now()) {
+    if (connectionMeta !== this.connectionMeta) return null
+    const ok = this._sendJson({
+      type: "heartbeat",
+      uptime_sec: Math.floor((Date.now() - this.startedAt) / 1000),
+      bundle_version: this.bundleVersion,
+      ...this.bundleStatus,
+    })
+    connectionMeta.lastHeartbeatAt = heartbeatAt
+    connectionMeta.lastHeartbeatOk = ok
+    return ok
+  }
+
+  _startHeartbeat(connectionMeta = this.connectionMeta) {
     this._stopHeartbeat()
     this.lastTickAt = Date.now()
+    connectionMeta.lastTickAt = this.lastTickAt
     this.heartbeatTimer = setInterval(() => {
+      if (connectionMeta !== this.connectionMeta) return
       const now = Date.now()
       // スリープ復帰検知: スリープ中はプロセスごと止まり、setInterval の実発火間隔が
       // 大きく開く。復帰直後の TCP は half-open でほぼ確実に死んでいるのに send は
       // 成功扱いになるため、鮮度判定 (受信側) を待たず即座に再接続へ倒す。
       const tickGap = this.lastTickAt > 0 ? now - this.lastTickAt : 0
       this.lastTickAt = now
+      connectionMeta.lastTickAt = now
+      connectionMeta.lastTickGapMs = tickGap
       if (tickGap > TICK_JUMP_MS) {
         this.logger?.warn(
           { tickGapMs: tickGap },
           "heartbeat tick jump detected (likely sleep wake), forcing reconnect",
         )
-        this._forceReconnect()
+        this._forceReconnect("sleep_tick_jump", connectionMeta)
         return
       }
       // zombie WS 検知 (inbound 鮮度): backend は heartbeat のたびに ack を返すため、
@@ -475,7 +571,7 @@ export class WsClient extends EventEmitter {
           { sinceLastRecvMs: now - this.lastRecvAt },
           "ws liveness timeout (zombie suspected), forcing reconnect",
         )
-        this._forceReconnect()
+        this._forceReconnect("liveness_timeout", connectionMeta)
         return
       }
       // heartbeat 都度 provider 経由で bundle version / CLI 別ステータスを最新化する。
@@ -485,15 +581,11 @@ export class WsClient extends EventEmitter {
       // 送信失敗 (= ws not OPEN) を検知したら即時 close + reconnect 発火。
       // setInterval を放置すると死んだコネクションに heartbeat を投げ続けて
       // 30s 間気付かないので、close を強制トリガーする。
-      const ok = this._sendJson({
-        type: "heartbeat",
-        uptime_sec: Math.floor((Date.now() - this.startedAt) / 1000),
-        bundle_version: this.bundleVersion,
-        ...this.bundleStatus,
-      })
+      const ok = this._sendHeartbeat(connectionMeta, now)
+      if (ok == null) return
       if (!ok) {
         this.logger?.warn("heartbeat send failed, forcing reconnect")
-        this._forceReconnect()
+        this._forceReconnect("heartbeat_send_failed", connectionMeta)
       }
     }, HEARTBEAT_INTERVAL_MS)
     // unref して node プロセスが timer 1 個で抜けられなくならないように
@@ -549,13 +641,16 @@ export class WsClient extends EventEmitter {
    * Cockpit UI への反映ラグを 30s heartbeat 周期から ~15s (UI poll) に短縮する。
    * fs.watch の起動に失敗しても heartbeat 都度 refresh が保険として動くので no-op。
    */
-  _startBundleWatcher() {
-    if (!this.bundleManifestPath || this.bundleWatcher) return
+  _startBundleWatcher(connectionMeta = this.connectionMeta) {
+    if (!this.bundleManifestPath) return
+    if (this.bundleWatcher && this.bundleWatcherConnectionMeta === connectionMeta) return
+    if (this.bundleWatcher) this._stopBundleWatcher()
     try {
+      this.bundleWatcherConnectionMeta = connectionMeta
       this.bundleWatcher = fs.watch(
         this.bundleManifestPath,
         { persistent: false },
-        () => this._onBundleManifestChange(),
+        () => this._onBundleManifestChange(connectionMeta),
       )
       this.bundleWatcher.on("error", (err) => {
         this.logger?.warn(
@@ -568,6 +663,7 @@ export class WsClient extends EventEmitter {
         "bundle manifest watcher started",
       )
     } catch (err) {
+      this.bundleWatcherConnectionMeta = null
       this.logger?.warn(
         { err: err.message, path: this.bundleManifestPath },
         "bundle manifest watcher failed to start",
@@ -588,43 +684,46 @@ export class WsClient extends EventEmitter {
       }
       this.bundleWatcher = null
     }
+    this.bundleWatcherConnectionMeta = null
   }
 
   /**
    * fs.watch のコールバック。同一書き込みで多重 fire することがある (macOS) ため
    * デバウンスしてから refresh + 即時 heartbeat する。
    */
-  _onBundleManifestChange() {
+  _onBundleManifestChange(connectionMeta = this.connectionMeta) {
+    if (connectionMeta !== this.connectionMeta) return
     if (this.bundleWatchDebounceTimer) {
       clearTimeout(this.bundleWatchDebounceTimer)
     }
     this.bundleWatchDebounceTimer = setTimeout(() => {
       this.bundleWatchDebounceTimer = null
+      if (connectionMeta !== this.connectionMeta) return
       const changed = this._refreshBundleVersion()
       if (!changed) return
       this._refreshBundleStatus()
-      const ok = this._sendJson({
-        type: "heartbeat",
-        uptime_sec: Math.floor((Date.now() - this.startedAt) / 1000),
-        bundle_version: this.bundleVersion,
-        ...this.bundleStatus,
-      })
+      const ok = this._sendHeartbeat(connectionMeta)
+      if (ok == null) return
       if (!ok) {
         this.logger?.warn("bundle-change heartbeat send failed, forcing reconnect")
-        this._forceReconnect()
+        this._forceReconnect("bundle_heartbeat_send_failed", connectionMeta)
       }
     }, BUNDLE_WATCH_DEBOUNCE_MS)
     this.bundleWatchDebounceTimer.unref?.()
   }
 
-  _forceReconnect() {
+  // reason の既定値は、将来の呼出漏れを無情報の null にせずログで検知する fail-soft。
+  _forceReconnect(reason = "unspecified", connectionMeta = this.connectionMeta) {
     // 現在の ws を強制 close。close ハンドラが _scheduleReconnect を呼ぶので
     // それ以上の処理は不要。stopped 中は no-op。
     // ws 実装によって terminate (ws npm package) と close (browser WebSocket
     // 互換) どちらが生えているか異なるので両対応する。
+    if (connectionMeta !== this.connectionMeta) return
     if (this.stopped) return
     if (!this.ws) return
     if (this.ws.readyState === WebSocket.CLOSED) return
+    connectionMeta.forceReconnectReason = reason
+    connectionMeta.closeInitiator = "agent_reconnect"
     try {
       if (typeof this.ws.terminate === "function") {
         this.ws.terminate()
@@ -682,7 +781,7 @@ export class WsClient extends EventEmitter {
           { sinceArmedMs: Date.now() - armedAt },
           "ws stable window elapsed with no inbound (half-open suspected), forcing reconnect",
         )
-        this._forceReconnect()
+        this._forceReconnect("stable_no_inbound")
       }
     }, STABLE_CONNECTION_MS)
     this.stableResetTimer.unref?.()