@cocorograph/hub-agent 0.8.50 → 0.8.52

package/package.json

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

package/src/codex-stream-bridge.mjs

@@ -368,16 +368,17 @@ const HISTORY_MAX_BYTES = readPositiveIntEnv(
   "HUB_AGENT_CODEX_HISTORY_MAX_BYTES",
   1.5 * 1024 * 1024,
 )
+const HISTORY_SNAPSHOT_CACHE_TTL_MS = readPositiveIntEnv(
+  "HUB_AGENT_CODEX_HISTORY_SNAPSHOT_TTL_MS",
+  30_000,
+)
 
 // Slice 6: thread/resume が返す Thread.turns[].items[] を単一の時系列配列へ平坦化する。
 // turns は開始ターン順の配列、各 turn.items も時系列順のため単純結合で会話順を保てる。
 //
-// T06499: 末尾から maxItems / maxBytes の budget 内に収め、超過分は落として truncated=true を
-// 返す。末尾優先なのは「直近の会話が最も価値が高く、古い履歴は resume されたモデル側が保持して
-// いる」ため。budget を末尾から積むので、20MB スレッドでも全 item を stringify せず早期に打ち切る
-// (kept が budget に達した時点で残りの巨大な古い item には触れない)。
-// @returns {{items: object[], truncated: boolean, total: number}}
-function flattenThreadItems(thread, { maxItems = HISTORY_MAX_ITEMS, maxBytes = HISTORY_MAX_BYTES } = {}) {
+// 全 parent thread item を時系列順に平坦化する。item/byte budget はこの段階では適用せず、
+// pageThreadItems が requested cursor ごとに適用する。返却配列の index が start/total/before の座標系。
+function flattenAllThreadItems(thread) {
   const turns = Array.isArray(thread?.turns) ? thread.turns : []
   const all = []
   for (const turn of turns) {
@@ -403,36 +404,41 @@ function flattenThreadItems(thread, { maxItems = HISTORY_MAX_ITEMS, maxBytes = H
       all.push(atMs != null && item && typeof item === "object" ? { ...item, at_ms: atMs } : item)
     }
   }
+  return all
+}
+
+// before の直前から古い側へ、item 数と概算 byte 数の両予算で 1 page を切り出す。
+// @returns {{items: object[], start: number, truncated: boolean, total: number}}
+function pageThreadItems(
+  all,
+  { before = all.length, maxItems = HISTORY_MAX_ITEMS, maxBytes = HISTORY_MAX_BYTES } = {},
+) {
   const total = all.length
+  const end = Math.min(Math.max(0, before), total)
+  const firstCandidate = Math.max(0, end - maxItems)
   const kept = []
   let bytes = 0
-  let truncated = false
-  // 末尾 (最新) から詰める。budget 超過で打ち切り、truncated を立てる。
-  for (let i = all.length - 1; i >= 0; i--) {
-    if (kept.length >= maxItems) {
-      truncated = true
-      break
-    }
+  let start = end
+  for (let i = end - 1; i >= firstCandidate; i--) {
     const item = all[i]
-    let size = 0
-    try {
-      size = JSON.stringify(item)?.length || 0
-    } catch {
-      size = 0
-    }
-    // 最低 1 件は必ず入れる (単一 item が maxBytes を超えても末尾 1 件は見せる)。
+    const size = estimateItemBytes(item)
     if (kept.length > 0 && bytes + size > maxBytes) {
-      truncated = true
       break
     }
     kept.push(item)
     bytes += size
+    start = i
   }
-  kept.reverse() // 末尾から積んだので時系列順へ戻す。
-  return { items: kept, truncated, total }
+  kept.reverse()
+  return { items: kept, start, truncated: start > 0, total }
+}
+
+function flattenThreadItems(thread, { maxItems = HISTORY_MAX_ITEMS, maxBytes = HISTORY_MAX_BYTES } = {}) {
+  const all = flattenAllThreadItems(thread)
+  return pageThreadItems(all, { before: all.length, maxItems, maxBytes })
 }
 
-/** 履歴 item の概算 byte 数 (flattenThreadItems の budget 判定と同じ JSON 長ベース)。 */
+/** 履歴 item の概算 byte 数 (pageThreadItems の budget 判定と同じ JSON 長ベース)。 */
 function estimateItemBytes(item) {
   try {
     return JSON.stringify(item)?.length || 0
@@ -607,6 +613,7 @@ export class CodexStreamBridge extends EventEmitter {
     listThreadsFromDisk,
     historyMaxItems,
     historyMaxBytes,
+    historySnapshotCacheTtlMs,
     listThreadsCacheTtlMs,
     accountRateLimitsCacheTtlMs,
     workspaceDependenciesCacheTtlMs,
@@ -719,6 +726,7 @@ export class CodexStreamBridge extends EventEmitter {
       maxItems: historyMaxItems ?? HISTORY_MAX_ITEMS,
       maxBytes: historyMaxBytes ?? HISTORY_MAX_BYTES,
     }
+    this._historySnapshotCacheTtlMs = historySnapshotCacheTtlMs ?? HISTORY_SNAPSHOT_CACHE_TTL_MS
     /** @type {Map<string, object>} stream_id -> session record */
     this.sessions = new Map()
     this._accountRateLimitsByProfile = new Map()
@@ -751,7 +759,8 @@ export class CodexStreamBridge extends EventEmitter {
    * なければ、通常の attach (thread/start | thread/resume) にフォールスルーする。
    *
    * @returns {Promise<{resuming: boolean, threadId: string, history: object[],
-   *   historyTruncated: boolean, threadStatus: string|null, lastTurnStatus: string|null,
+   *   historyTruncated: boolean, historyStart?: number, historyTotal?: number,
+   *   threadStatus: string|null, lastTurnStatus: string|null,
    *   turnActive: boolean}>}
    */
   async attach({ stream_id, cwd, model, effort, approvalPolicy, sandbox, resumeThreadId, attachId }) {
@@ -860,6 +869,14 @@ export class CodexStreamBridge extends EventEmitter {
             // 由来で表示がリセットされ得るため、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),
           }
         }
@@ -984,6 +1001,18 @@ export class CodexStreamBridge extends EventEmitter {
       // 生データ（ツールカードが粗い）ではなく app-server 整形済みの高忠実度履歴を維持する。
       historyItems: [],
       historyTruncated: false,
+      historyStart: 0,
+      historyTotal: 0,
+      // reattach 表示履歴には child item も含むが cursor は parent item だけを数える。
+      // historyItems/historyCursorWeights は常に同長。weight は 1=parent / 0=child で、trim 時の
+      // start 前進量を決める。ready の start/total はこの cursor 専用で配列 index ではない。
+      // childだけがtrimされた事実はcursorへ残らず、warm reattachでのchild本文復元はbest-effort。
+      historyCursorWeights: [],
+      historySnapshotCache: new AsyncTtlCache({ ttlMs: this._historySnapshotCacheTtlMs }),
+      historySnapshotReleaseTimer: null,
+      historySnapshotComparable: false,
+      historyAttachInProgress: true,
+      historyItemArrivedDuringAttach: false,
       // major#2: ライブ追記でも cold flatten と同じ「item 数＋概算 byte」二重上限を課すため、
       // 蓄積済み履歴の概算 byte 合計を保持する (再計算を避け O(1) で trim 判定)。
       historyBytes: 0,
@@ -1136,7 +1165,7 @@ export class CodexStreamBridge extends EventEmitter {
       // T06499: 巨大スレッドは末尾 N ターンに絞る (truncated=true なら browser がバナー表示)。
       const flat = resuming
         ? flattenThreadItems(result?.thread, this._historyLimits)
-        : { items: [], truncated: false, total: 0 }
+        : { items: [], start: 0, truncated: false, total: 0 }
       // hub-agent 側の履歴整形コスト (巨大スレッドで効く)。thread_op_ms とは別勘定にする。
       timing.history_flatten_ms = lap()
       const history = flat.items
@@ -1147,6 +1176,11 @@ export class CodexStreamBridge extends EventEmitter {
       session.historyItems = history.slice()
       session.historyBytes = history.reduce((n, it) => n + estimateItemBytes(it), 0)
       session.historyTruncated = historyTruncated
+      session.historyStart = flat.start
+      session.historyTotal = flat.total
+      session.historyCursorWeights = history.map(() => 1)
+      session.historyAttachInProgress = false
+      session.historySnapshotComparable = session.historyItemArrivedDuringAttach !== true
       if (resuming) await this._restoreSubagentsFromHistory(session, history)
       // 案C: 権威的なターン状態を resume 応答から取り出してフロントへ渡す。
       // これによりフロントは会話末尾からの推測をやめ、Thread.status で turnActive を
@@ -1204,6 +1238,8 @@ export class CodexStreamBridge extends EventEmitter {
         threadId: session.threadId,
         history,
         historyTruncated,
+        historyStart: flat.start,
+        historyTotal: flat.total,
         subagents: this._subagentSnapshots(session, history),
         threadStatus: turnState.threadStatus,
         lastTurnStatus: turnState.lastTurnStatus,
@@ -1212,6 +1248,7 @@ export class CodexStreamBridge extends EventEmitter {
     } catch (err) {
       this.sessions.delete(stream_id)
       this._settleAllPendingApprovals(session, { respond: false })
+      this._disposeHistorySnapshot(session)
       client.stop()
       settleReady(null) // reattach 待ちへ「失敗」を通知 (reject しない)
       // 失敗も 1 行に落とす。**_classifyAttachFailure より前**に出す (分類は rollout の disk 走査を
@@ -1306,15 +1343,40 @@ export class CodexStreamBridge extends EventEmitter {
    * 表示用バブル時刻 at_ms は completedAtMs (ms epoch) を採る（flattenThreadItems と同じ ms 単位。
    * userMessage はライブでも completedAtMs=ターン冒頭で届くため整合する）。長い会話で無限成長させ
    * ないよう cold flatten と同じ **item 数 (maxItems) ＋ 概算 byte 数 (maxBytes) の二重上限** を課し、
-   * 超過分は先頭 (最古) から捨て truncated を立てる (major#2: 巨大ツール出力で reattach payload が
-   * 肥大化し T06499 で防いだメモリ増・WS 転送・ブラウザフリーズが再発するのを防ぐ)。
+   * 超過分は先頭 (最古) から捨て、parent cursor が前進した場合だけ truncated を立てる
+   * (major#2: 巨大ツール出力で reattach payload が肥大化し T06499 で防いだメモリ増・WS 転送・
+   * ブラウザフリーズが再発するのを防ぐ)。
    */
-  _appendHistoryItem(session, item, completedAtMs) {
+  _appendHistoryItem(session, item, completedAtMs, { countsForCursor = true } = {}) {
     if (!session || !item || typeof item !== "object") return
+    if (session.historyAttachInProgress === true) session.historyItemArrivedDuringAttach = true
     if (!Array.isArray(session.historyItems)) session.historyItems = []
     if (typeof session.historyBytes !== "number") session.historyBytes = 0
+    // 旧/遅延初期化 session でも同長不変条件を回復する。既存 item の由来を失っている場合は
+    // parent として安全側に数え、以降の child item だけを明示的に 0 とする。
+    if (
+      !Array.isArray(session.historyCursorWeights) ||
+      session.historyCursorWeights.length !== session.historyItems.length
+    ) {
+      this.logger?.warn?.(
+        {
+          thread_id: session.threadId,
+          history_items: session.historyItems.length,
+          cursor_weights: Array.isArray(session.historyCursorWeights)
+            ? session.historyCursorWeights.length
+            : null,
+        },
+        "codex history cursor weights rebuilt to match retained items",
+      )
+      session.historyCursorWeights = session.historyItems.map(() => 1)
+    }
     const entry = typeof completedAtMs === "number" ? { ...item, at_ms: completedAtMs } : item
     session.historyItems.push(entry)
+    const cursorWeight = countsForCursor ? 1 : 0
+    session.historyCursorWeights.push(cursorWeight)
+    session.historyTotal = (Number.isInteger(session.historyTotal) ? session.historyTotal : 0) + cursorWeight
+    // 古い page は同じ snapshot 座標内なら順序が壊れないため cache は clear しない。
+    // child 更新は parent thread/read snapshot にも無関係。TTL 後の再取得で自然に追随する。
     session.historyBytes += estimateItemBytes(entry)
     const maxItems = this._historyLimits.maxItems
     const maxBytes = this._historyLimits.maxBytes
@@ -1325,9 +1387,140 @@ export class CodexStreamBridge extends EventEmitter {
         (typeof maxBytes === "number" && session.historyBytes > maxBytes))
     ) {
       const dropped = session.historyItems.shift()
+      const droppedCursorWeight = session.historyCursorWeights.shift() || 0
       session.historyBytes -= estimateItemBytes(dropped)
       if (session.historyBytes < 0) session.historyBytes = 0
-      session.historyTruncated = true
+      session.historyStart =
+        (Number.isInteger(session.historyStart) ? session.historyStart : 0) + droppedCursorWeight
+    }
+    // child だけが表示上限から落ちても parent cursor の古い側は欠けていない。
+    session.historyTruncated = (Number.isInteger(session.historyStart) ? session.historyStart : 0) > 0
+  }
+
+  _scheduleHistorySnapshotRelease(session) {
+    if (session.historySnapshotReleaseTimer) clearTimeout(session.historySnapshotReleaseTimer)
+    const cache = session.historySnapshotCache
+    if (!cache?.hasValue) {
+      session.historySnapshotReleaseTimer = null
+      return
+    }
+    const release = () => {
+      if (session.historySnapshotReleaseTimer !== timer) return
+      // TTL境界で次buildが始まっている場合、そのbuildをclear世代変更で再実行させない。
+      // build完了後の _scheduleHistorySnapshotRelease がこの短い繰延timerを張り替える。
+      if (cache.inFlight) {
+        const retryDelayMs = Math.max(10, Math.min(1_000, this._historySnapshotCacheTtlMs))
+        const retryTimer = setTimeout(release, retryDelayMs)
+        retryTimer.unref?.()
+        session.historySnapshotReleaseTimer = retryTimer
+        timer = retryTimer
+        return
+      }
+      session.historySnapshotReleaseTimer = null
+      cache.clear()
+    }
+    const delayMs = Math.max(0, cache.expiresAt - Date.now())
+    let timer = setTimeout(release, delayMs)
+    timer.unref?.()
+    session.historySnapshotReleaseTimer = timer
+  }
+
+  _disposeHistorySnapshot(session) {
+    if (!session) return
+    if (session.historySnapshotReleaseTimer) clearTimeout(session.historySnapshotReleaseTimer)
+    session.historySnapshotReleaseTimer = null
+    session.historySnapshotCache?.clear?.()
+  }
+
+  async _historySnapshot(session) {
+    // この reader は既存の別責務の thread/read と統合しない。要求した root thread と応答の
+    // thread id が一致することを、この履歴取得経路自身で必ず検証する。
+    const cache = session.historySnapshotCache
+    const items = await cache.get(async () => {
+      // session破棄時の cache.clear() で進行中callerが新世代buildへ合流し直しても、停止済み
+      // clientへ2本目のthread/readを送らない。
+      if (session.dead) throw new Error("stream_id is not attached")
+      const result = await session.client.request("thread/read", {
+        threadId: session.threadId,
+        includeTurns: true,
+      })
+      if (result?.thread?.id !== session.threadId) {
+        throw new Error("thread/read returned a different thread")
+      }
+      const items = flattenAllThreadItems(result.thread)
+      if (
+        session.historySnapshotComparable === true &&
+        Number.isInteger(session.historyTotal) &&
+        items.length !== session.historyTotal
+      ) {
+        this.logger?.warn?.(
+          {
+            thread_id: session.threadId,
+            snapshot_items: items.length,
+            live_history_total: session.historyTotal,
+          },
+          "codex history snapshot item count differs from live parent cursor",
+        )
+      }
+      session.historyTotal = Math.max(
+        items.length,
+        Number.isInteger(session.historyTotal) ? session.historyTotal : 0,
+      )
+      return items
+    })
+    this._scheduleHistorySnapshotRelease(session)
+    return items
+  }
+
+  /**
+   * live session の parent thread から古い履歴 page を読む。
+   * before は全 parent item 座標上の exclusive cursor で、返却は [historyStart, before) 相当。
+   * ready.history は child item を含み得るため、その配列 index とこの cursor は同一ではない。
+   * この read-only RPC 自体は session の liveness を延長しない。閲覧中の生存は keepalive が担う。
+   */
+  async history({ stream_id, thread_id, before, limit }) {
+    const session = this.sessions.get(stream_id)
+    if (!session || session.dead) throw new Error("stream_id is not attached")
+    if (typeof thread_id !== "string" || !thread_id || thread_id !== session.threadId) {
+      throw new Error("thread_id does not match stream session")
+    }
+    if (!Number.isInteger(before) || before < 0) {
+      throw new Error("before must be a non-negative integer")
+    }
+    if (limit != null && (!Number.isInteger(limit) || limit <= 0)) {
+      throw new Error("limit must be a positive integer")
+    }
+    if (before > (Number.isInteger(session.historyTotal) ? session.historyTotal : 0)) {
+      throw new Error("before exceeds live history total")
+    }
+    let all = await this._historySnapshot(session)
+    // readyが広告した正当cursorへTTL snapshotが追いついていない場合だけ、このrequest内で最大1回
+    // 強制再buildする。再帰/loopは使わず、なお短ければerrorへ固定する。
+    if (before > all.length) {
+      this._disposeHistorySnapshot(session)
+      all = await this._historySnapshot(session)
+    }
+    if (before > all.length) {
+      throw new Error("before exceeds history snapshot total")
+    }
+    const maxItems = this._historyLimits.maxItems
+    const pageLimit = limit == null ? maxItems : Math.min(maxItems, limit)
+    const page = pageThreadItems(all, {
+      before,
+      maxItems: pageLimit,
+      maxBytes: this._historyLimits.maxBytes,
+    })
+    return {
+      threadId: session.threadId,
+      history: page.items,
+      historyStart: page.start,
+      historyTotal: page.total,
+      historyTruncated: page.truncated,
+      requestBefore: before,
+      appliedLimit: pageLimit,
+      // subagents は意図的に省略する。古い page から復元すると child thread/read と session 台帳変更が
+      // 発生し、read-only fastpath ではなくなるため。wire 契約上、省略時は in-memory 台帳が無い
+      // subagent を通常の簡易履歴表示へ fallback させ、推測で別 thread の snapshot を混ぜない。
     }
   }
 
@@ -2794,7 +2987,15 @@ export class CodexStreamBridge extends EventEmitter {
       case "item/completed":
         // 完了した ThreadItem を高忠実度履歴に追記する（cwd reattach で返す用）。
         // attribution/source 済み item (effectiveParams.item) を積み、emit と同じ clone を使う。
-        this._appendHistoryItem(session, effectiveParams?.item, effectiveParams?.completedAtMs)
+        this._appendHistoryItem(
+          session,
+          effectiveParams?.item,
+          effectiveParams?.completedAtMs,
+          {
+            countsForCursor:
+              typeof eventThreadId !== "string" || eventThreadId === session.threadId,
+          },
+        )
         break
       default:
         break
@@ -2973,6 +3174,7 @@ export class CodexStreamBridge extends EventEmitter {
     if (session.dead) return
     this._markRunningSubagentsKilled(session)
     session.dead = true
+    this._disposeHistorySnapshot(session)
     // round3: app-server が死んだら barrier を解除し queue を reject する（promise 宙吊り防止）。
     this._settleTurnActiveWaiter(session)
     this._drainRejectQueue(session, { reason: "queue_dead" })
@@ -4007,6 +4209,7 @@ export class CodexStreamBridge extends EventEmitter {
     if (session.dead) return
     this._markRunningSubagentsKilled(session, now)
     session.dead = true
+    this._disposeHistorySnapshot(session)
     // round3: reap した session の barrier を解除し queue を reject する（promise 宙吊り防止）。
     this._settleTurnActiveWaiter(session)
     this._drainRejectQueue(session, { reason: "queue_dead" })
@@ -4196,6 +4399,7 @@ export class CodexStreamBridge extends EventEmitter {
     for (const session of this._liveSessions()) {
       this._markRunningSubagentsKilled(session)
       session.dead = true
+      this._disposeHistorySnapshot(session)
       // round3: shutdown で barrier を解除し queue 入力を reject（promise 宙吊り防止）。
       this._settleTurnActiveWaiter(session)
       this._drainRejectQueue(session, { reason: "queue_dead" })

package/src/main.mjs

@@ -412,6 +412,7 @@ export function isReadOnlyRpc(type) {
     type === "claude.history.request" ||
     type === "claude.sessions.request" ||
     type === "codex.sessions.request" ||
+    type === "codex.history.request" ||
     type === "profile.list" ||
     type === "codex.profile.list" ||
     type === "chat.sidebar_snapshot.request" ||
@@ -2288,8 +2289,10 @@ export function buildClaudeSessionOptionsResultPayload(
 }
 
 /** codex.ready の wire payload を組み立てる。history は同じ配列参照を保持し、
- * started_history_index が指す位置を main 側の加工でずらさない。表示を保持する reconnect
- * (`info.subagents` 未定義) では subagents キー自体を省略し、空 snapshot で既存表示を消さない。 */
+ * started_history_index が指す位置を main 側の加工でずらさない。history_start/history_total は
+ * parent item cursor 専用で、child item を含み得る history 配列 index とは別座標。表示を保持する
+ * reconnect (`info.subagents` 未定義) では subagents キー自体を省略し、空 snapshot で既存表示を消さない。
+ * retained上限で落ちたchild本文はcursorに痕跡を持たず、warm reattachでの復元はbest-effort。 */
 export function buildCodexReadyPayload(streamId, info, queueState) {
   const history = Array.isArray(info?.history) ? info.history : []
   const payload = {
@@ -2307,6 +2310,8 @@ export function buildCodexReadyPayload(streamId, info, queueState) {
     // 子 thread の個別停止 UI を有効化する。省略は未対応を意味する。
     supports_subagent_interrupt: true,
   }
+  if (Number.isInteger(info?.historyStart)) payload.history_start = info.historyStart
+  if (Number.isInteger(info?.historyTotal)) payload.history_total = info.historyTotal
   if (Array.isArray(info?.subagents)) {
     payload.subagents = info.subagents.map((subagent) => ({
       // 現契約では delegation_id と agent_thread_id は同じ child thread ID の alias。
@@ -4762,6 +4767,43 @@ export async function dispatch(msg, ctx) {
         }
         return
       }
+      case "codex.history.request": {
+        const stream_id = msg.stream_id
+        const thread_id = msg.thread_id
+        const empty = {
+          type: "codex.history.response",
+          stream_id,
+          thread_id,
+          history: [],
+          ...(Number.isInteger(msg.before) ? { request_before: msg.before } : {}),
+        }
+        if (!ctx.codexBridge) {
+          ctx.client.send({ ...empty, error: "codex_unavailable: bridge is not initialized" })
+          return
+        }
+        try {
+          const result = await ctx.codexBridge.history({
+            stream_id,
+            thread_id,
+            before: msg.before,
+            limit: msg.limit,
+          })
+          ctx.client.send({
+            type: "codex.history.response",
+            stream_id,
+            thread_id: result.threadId,
+            history: result.history,
+            history_start: result.historyStart,
+            history_total: result.historyTotal,
+            history_truncated: result.historyTruncated === true,
+            request_before: result.requestBefore,
+            applied_limit: result.appliedLimit,
+          })
+        } catch (err) {
+          ctx.client.send({ ...empty, error: err?.message || String(err) })
+        }
+        return
+      }
       case "claude.history.request": {
         // Sprint G 0.6.1: ~/.claude/projects/<cwd-encoded>/<session_id>.jsonl を読んで
         // 過去メッセージを返す。ChatView の re-mount 時の UI 復元用。

package/src/usage.mjs

@@ -1528,12 +1528,13 @@ function commitCodexThreadListEntry(index, fp, observed, next) {
  *
  * @param {string} fp
  * @param {string} expectedCwd cwd-scoped 一覧の対象。別 cwd は session_meta 読み取り後に早期終了。
- * @returns {Promise<{thread_id:string,cwd:string,preview:string,preview_complete:boolean}|null|symbol>}
+ * @returns {Promise<{thread_id:string,cwd:string,preview:string,preview_complete:boolean,is_subagent:boolean}|null|symbol>}
  */
 async function parseCodexRolloutHead(fp, expectedCwd = "", testHooks = null) {
   let thread_id = threadIdFromRolloutFilename(fp)
   let cwd = ""
   let preview = ""
+  let is_subagent = false
   let fh
   const decoder = new StringDecoder("utf8")
   let pending = ""
@@ -1553,6 +1554,13 @@ async function parseCodexRolloutHead(fp, expectedCwd = "", testHooks = null) {
       if (typeof o.payload.session_id === "string" && o.payload.session_id) {
         thread_id = o.payload.session_id
       }
+      const subagent = o.payload.source?.subagent
+      // 実 rollout で観測済みの thread_spawn キー自体を marker とする。値の shape は問わず、
+      // 後続 session_meta に source が無くても一度立った子判定は戻さない。
+      is_subagent ||=
+        subagent != null &&
+        typeof subagent === "object" &&
+        Object.prototype.hasOwnProperty.call(subagent, "thread_spawn")
     } else if (
       !preview &&
       o.type === "event_msg" &&
@@ -1594,11 +1602,15 @@ async function parseCodexRolloutHead(fp, expectedCwd = "", testHooks = null) {
         // session_meta は先頭行にある。別 workspace の候補に対して巨大な初期コンテキストを
         // 読み進めないことで、初回の派生インデックス構築コストを抑える。
         if (cwd && expectedCwd && cwd !== expectedCwd) {
-          result = thread_id ? { thread_id, cwd, preview, preview_complete: false } : null
+          result = thread_id
+            ? { thread_id, cwd, preview, preview_complete: false, is_subagent }
+            : null
           break scan
         }
         if (cwd && preview) {
-          result = thread_id ? { thread_id, cwd, preview, preview_complete: true } : null
+          result = thread_id
+            ? { thread_id, cwd, preview, preview_complete: true, is_subagent }
+            : null
           break scan
         }
       }
@@ -1612,7 +1624,9 @@ async function parseCodexRolloutHead(fp, expectedCwd = "", testHooks = null) {
       }
     }
     if (result === undefined) {
-      result = thread_id ? { thread_id, cwd, preview, preview_complete: true } : null
+      result = thread_id
+        ? { thread_id, cwd, preview, preview_complete: true, is_subagent }
+        : null
     }
   } catch {
     result = CODEX_ROLLOUT_PARSE_IO_ERROR
@@ -1770,6 +1784,10 @@ export async function listCodexThreadsFromDisk({
     let meta = entry?.meta
     if (!meta) continue
     if (meta.cwd !== cwd) continue
+    // Native sub-agent rollout は payload.session_id に親 thread ID を持つため、そのまま返すと
+    // 親セッションが重複表示される。既知の thread_spawn 形式だけを除外し、未知 source は残す。
+    // 親が lookback 窓外でも子を proxy として残さず、親一覧は既存の lookback 契約に従う。
+    if (meta.is_subagent) continue
     if (!meta.preview_complete) {
       const observed = index.get(fp)
       completedPreviews++