@cocorograph/hub-agent 0.8.51 → 0.8.53

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cocorograph/hub-agent",
-  "version": "0.8.51",
+  "version": "0.8.53",
   "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,25 @@ export class CodexStreamBridge extends EventEmitter {
       // 生データ（ツールカードが粗い）ではなく app-server 整形済みの高忠実度履歴を維持する。
       historyItems: [],
       historyTruncated: false,
+      historyStart: 0,
+      historyTotal: 0,
+      // cold resume が確定した parent cursor の基準件数と、それ以降の root live 追記数。
+      // thread/read の短縮が「先頭 compaction」か「末尾反映待ち」かを区別する。
+      historyColdBaseTotal: 0,
+      historyLiveCursorAdditions: 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,
+      historySnapshotBuildSeq: 0,
+      historySnapshotReturnedBuildSeq: 0,
+      historySnapshotFreshOperations: new Set(),
+      historySnapshotComparable: false,
+      historyAttachInProgress: true,
+      historyItemArrivedDuringAttach: false,
       // major#2: ライブ追記でも cold flatten と同じ「item 数＋概算 byte」二重上限を課すため、
       // 蓄積済み履歴の概算 byte 合計を保持する (再計算を避け O(1) で trim 判定)。
       historyBytes: 0,
@@ -1136,7 +1172,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 +1183,13 @@ 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.historyColdBaseTotal = flat.total
+      session.historyLiveCursorAdditions = 0
+      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 +1247,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 +1257,7 @@ export class CodexStreamBridge extends EventEmitter {
     } catch (err) {
       this.sessions.delete(stream_id)
       this._settleAllPendingApprovals(session, { respond: false })
+      this._disposeSessionHistory(session)
       client.stop()
       settleReady(null) // reattach 待ちへ「失敗」を通知 (reject しない)
       // 失敗も 1 行に落とす。**_classifyAttachFailure より前**に出す (分類は rollout の disk 走査を
@@ -1306,15 +1352,46 @@ 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
+    if (cursorWeight === 1 && session.historyAttachInProgress !== true) {
+      session.historyLiveCursorAdditions =
+        (Number.isInteger(session.historyLiveCursorAdditions)
+          ? session.historyLiveCursorAdditions
+          : 0) + 1
+    }
+    // 古い 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 +1402,347 @@ 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?.()
+  }
+
+  _abortFreshHistorySnapshot(session) {
+    if (!session) return
+    // clear() は進行中AsyncTtlCache buildを切り離して新世代buildを許すため、fresh operationも
+    // 一時的に複数並走し得る。finally deleteとの競合を避け、snapshot配列を全件abort→stopする。
+    const operations = [...(session.historySnapshotFreshOperations || [])]
+    for (const operation of operations) {
+      operation.abort?.()
+      try {
+        operation.stop?.()
+      } catch (error) {
+        this.logger?.warn?.(
+          {
+            error_code: codexHostCapabilityErrorCode(
+              error,
+              "CODEX_HISTORY_SNAPSHOT_STOP_FAILED",
+            ),
+          },
+          "codex history snapshot client stop failed",
+        )
+      }
+    }
+  }
+
+  _disposeSessionHistory(session) {
+    this._abortFreshHistorySnapshot(session)
+    this._disposeHistorySnapshot(session)
+  }
+
+  async _resumeFullHistorySnapshot(
+    session,
+    advertisedTotal,
+    requiredTotal,
+    liveItems,
+    coldBaseTotal,
+    additionsAtRequest,
+  ) {
+    const client = this._clientFactory({
+      cwd: session.cwd,
+      codexCmd: this.codexCmd,
+      logger: this.logger,
+      env: siblingEnvFor(session.cwd),
+    })
+    client.on("error", (error) => {
+      this.logger?.warn?.(
+        {
+          error_code: codexHostCapabilityErrorCode(
+            error,
+            "CODEX_HISTORY_SNAPSHOT_CLIENT_ERROR",
+          ),
+        },
+        "codex history snapshot client error",
+      )
+    })
+    const startedAt = Date.now()
+    let stopped = false
+    const stopClient = () => {
+      if (stopped) return
+      stopped = true
+      client.stop()
+    }
+    let rejectAbort
+    const aborted = new Promise((_, reject) => {
+      rejectAbort = reject
+    })
+    const abort = () => {
+      const error = new Error("stream_id is not attached")
+      error.code = "CODEX_HISTORY_SNAPSHOT_FALLBACK_ABORTED"
+      rejectAbort(error)
+    }
+    const operation = { client, abort, stop: stopClient }
+    session.historySnapshotFreshOperations.add(operation)
+    this.logger?.info?.(
+      {
+        thread_id: session.threadId,
+        advertised_total: advertisedTotal,
+        required_total: requiredTotal,
+        live_items: liveItems,
+        cold_base_total: coldBaseTotal,
+        additions_at_request: additionsAtRequest,
+      },
+      "codex history snapshot fallback started",
+    )
+    try {
+      const items = await Promise.race([
+        (async () => {
+          client.start()
+          await client.request("initialize", {
+            clientInfo: CLIENT_INFO,
+            capabilities: {
+              experimentalApi: true,
+              mcpServerOpenaiFormElicitation: true,
+            },
+          })
+          client.notify("initialized", {})
+          const result = await client.request("thread/resume", {
+            cwd: session.cwd,
+            threadId: session.threadId,
+          })
+          if (result?.thread?.id !== session.threadId) {
+            throw new Error("fresh thread/resume returned a different thread")
+          }
+          const resumedItems = flattenAllThreadItems(result.thread)
+          if (resumedItems.length < requiredTotal) {
+            throw new Error("fresh history snapshot is shorter than required prefix total")
+          }
+          return resumedItems
+        })(),
+        aborted,
+      ])
+      this.logger?.info?.(
+        {
+          thread_id: session.threadId,
+          advertised_total: advertisedTotal,
+          required_total: requiredTotal,
+          live_items: liveItems,
+          cold_base_total: coldBaseTotal,
+          additions_at_request: additionsAtRequest,
+          elapsed_ms: Date.now() - startedAt,
+        },
+        "codex history snapshot fallback completed",
+      )
+      return items
+    } catch (error) {
+      const isAborted = error?.code === "CODEX_HISTORY_SNAPSHOT_FALLBACK_ABORTED"
+      this.logger?.[isAborted ? "info" : "warn"]?.(
+        {
+          thread_id: session.threadId,
+          advertised_total: advertisedTotal,
+          required_total: requiredTotal,
+          live_items: liveItems,
+          cold_base_total: coldBaseTotal,
+          additions_at_request: additionsAtRequest,
+          elapsed_ms: Date.now() - startedAt,
+          error_code: codexHostCapabilityErrorCode(
+            error,
+            "CODEX_HISTORY_SNAPSHOT_FALLBACK_FAILED",
+          ),
+        },
+        isAborted
+          ? "codex history snapshot fallback aborted"
+          : "codex history snapshot fallback failed",
+      )
+      throw error
+    } finally {
+      stopClient()
+      session.historySnapshotFreshOperations.delete(operation)
+    }
+  }
+
+  async _historySnapshot(session) {
+    // この reader は既存の別責務の thread/read と統合しない。要求した root thread と応答の
+    // thread id が一致することを、この履歴取得経路自身で必ず検証する。
+    const cache = session.historySnapshotCache
+    const snapshot = await cache.get(async () => {
+      const buildSeq = (Number.isInteger(session.historySnapshotBuildSeq)
+        ? session.historySnapshotBuildSeq
+        : 0) + 1
+      session.historySnapshotBuildSeq = buildSeq
+      // session破棄時の cache.clear() で進行中callerが新世代buildへ合流し直しても、停止済み
+      // clientへ2本目のthread/readを送らない。
+      if (session.dead) throw new Error("stream_id is not attached")
+      const additionsAtRequest = Number.isInteger(session.historyLiveCursorAdditions)
+        ? session.historyLiveCursorAdditions
+        : 0
+      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")
+      }
+      if (session.dead) throw new Error("stream_id is not attached")
+      let items = flattenAllThreadItems(result.thread)
+      const coldBaseTotal = Number.isInteger(session.historyColdBaseTotal)
+        ? session.historyColdBaseTotal
+        : 0
+      const liveCursorAdditions = Number.isInteger(session.historyLiveCursorAdditions)
+        ? session.historyLiveCursorAdditions
+        : 0
+      const advertisedTotal = Math.max(
+        Number.isInteger(session.historyTotal) ? session.historyTotal : 0,
+        coldBaseTotal + liveCursorAdditions,
+      )
+      const knownPrefixAtRequest = coldBaseTotal + additionsAtRequest
+      if (
+        session.historySnapshotComparable === true &&
+        items.length !== advertisedTotal
+      ) {
+        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",
+        )
+      }
+      let usedFresh = false
+      // read開始時点で既知だったroot cursor prefixより短い場合だけcompactionと判定する。
+      // read発行前に観測した加算はread応答に含まれる前提。await中のlive追加はknownPrefixへ
+      // 含めず末尾lagとして許容し、この前提が破れた可能性はfallbackログで観測する。
+      if (items.length < knownPrefixAtRequest) {
+        const requiredTotal = coldBaseTotal > 0 ? coldBaseTotal : knownPrefixAtRequest
+        items = await this._resumeFullHistorySnapshot(
+          session,
+          advertisedTotal,
+          requiredTotal,
+          items.length,
+          coldBaseTotal,
+          additionsAtRequest,
+        )
+        usedFresh = true
+        // このbridgeはthread/rollback・thread/forkを呼ばず単調threadだけを扱うため、fresh
+        // thread/resumeのitemsは先頭からのdurable prefix。fresh成功時だけbaseを単調に引上げ、
+        // 並行live追加は差分として残す。
+        session.historyColdBaseTotal = Math.max(
+          Number.isInteger(session.historyColdBaseTotal) ? session.historyColdBaseTotal : 0,
+          items.length,
+        )
+        const newBase = session.historyColdBaseTotal
+        session.historyLiveCursorAdditions = Math.max(
+          0,
+          (Number.isInteger(session.historyTotal) ? session.historyTotal : 0) - newBase,
+        )
+      }
+      if (session.dead) throw new Error("stream_id is not attached")
+      session.historyTotal = Math.max(
+        items.length,
+        Number.isInteger(session.historyTotal) ? session.historyTotal : 0,
+      )
+      return { items, usedFresh, buildSeq }
+    })
+    if (session.dead) throw new Error("stream_id is not attached")
+    session.historySnapshotReturnedBuildSeq = Math.max(
+      Number.isInteger(session.historySnapshotReturnedBuildSeq)
+        ? session.historySnapshotReturnedBuildSeq
+        : 0,
+      snapshot.buildSeq,
+    )
+    this._scheduleHistorySnapshotRelease(session)
+    return snapshot
+  }
+
+  /**
+   * 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")
+    }
+    const maxItems = this._historyLimits.maxItems
+    const pageLimit = limit == null ? maxItems : Math.min(maxItems, limit)
+    const seqAtCall = Number.isInteger(session.historySnapshotReturnedBuildSeq)
+      ? session.historySnapshotReturnedBuildSeq
+      : 0
+    let snapshot = await this._historySnapshot(session)
+    // readyが広告した正当cursorへlive-only snapshotが追いついていない場合だけ、このrequest内で
+    // 最大1回再buildする。fresh済みsnapshotは同一requestで2本目を起動せず即errorへ固定する。
+    const usedFreshDuringCall = snapshot.usedFresh === true && snapshot.buildSeq > seqAtCall
+    if (before > snapshot.items.length && !usedFreshDuringCall) {
+      this._disposeHistorySnapshot(session)
+      snapshot = await this._historySnapshot(session)
+    }
+    if (before > snapshot.items.length) {
+      throw new Error("before exceeds history snapshot total")
+    }
+    const page = pageThreadItems(snapshot.items, {
+      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 +3209,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 +3396,7 @@ export class CodexStreamBridge extends EventEmitter {
     if (session.dead) return
     this._markRunningSubagentsKilled(session)
     session.dead = true
+    this._disposeSessionHistory(session)
     // round3: app-server が死んだら barrier を解除し queue を reject する（promise 宙吊り防止）。
     this._settleTurnActiveWaiter(session)
     this._drainRejectQueue(session, { reason: "queue_dead" })
@@ -4007,6 +4431,7 @@ export class CodexStreamBridge extends EventEmitter {
     if (session.dead) return
     this._markRunningSubagentsKilled(session, now)
     session.dead = true
+    this._disposeSessionHistory(session)
     // round3: reap した session の barrier を解除し queue を reject する（promise 宙吊り防止）。
     this._settleTurnActiveWaiter(session)
     this._drainRejectQueue(session, { reason: "queue_dead" })
@@ -4196,6 +4621,7 @@ export class CodexStreamBridge extends EventEmitter {
     for (const session of this._liveSessions()) {
       this._markRunningSubagentsKilled(session)
       session.dead = true
+      this._disposeSessionHistory(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 復元用。