lark-remote 0.5.13 → 0.5.14

package/dist/runner/probe.js

@@ -18,6 +18,7 @@
  *   with no child process at all.
  */
 import { resolveExecutable } from '../platform/command.js';
+import { TtlCache } from '../common/ttl-cache.js';
 /** Map from AgentKind to its CLI binary name. */
 const BINARY_MAP = {
     claude: 'claude',
@@ -30,8 +31,11 @@ const BINARY_MAP = {
     dsh: '',
 };
 const CACHE_TTL_MS = 5 * 60_000;
-/** Module-level cache, survives across calls within the process. */
-const cache = new Map();
+/**
+ * Module-level cache, survives across calls within the process. 键集就是
+ * AgentKind（有界），因此不设条目上限；共享 `TtlCache` 与 session readers 同语义。
+ */
+const cache = new TtlCache(CACHE_TTL_MS);
 /**
  * Probe a single agent's availability (pure PATH lookup; dsh has no CLI
  * binary and is always unavailable here).
@@ -49,10 +53,10 @@ async function probeOne(kind) {
  */
 export async function probeAgentAvailability(kind) {
     const cached = cache.get(kind);
-    if (cached && Date.now() - cached.ts < CACHE_TTL_MS)
-        return cached.ok;
+    if (cached !== undefined)
+        return cached;
     const ok = await probeOne(kind);
-    cache.set(kind, { ts: Date.now(), ok });
+    cache.set(kind, ok);
     return ok;
 }
 /**
@@ -76,10 +80,7 @@ export async function probeAllAgents() {
  * Used by synchronous code paths (e.g. buildConfigCard) that cannot await.
  */
 export function getCachedAvailability(kind) {
-    const cached = cache.get(kind);
-    if (!cached || Date.now() - cached.ts >= CACHE_TTL_MS)
-        return undefined;
-    return cached.ok;
+    return cache.get(kind);
 }
 /** Clear all cache entries. Exported for test use only (cache auto-expires via TTL). */
 export function _clearCacheForTest() {

package/dist/runner/registry.d.ts

@@ -1,4 +1,5 @@
-import type { AgentKind, Runner } from './index.js';
+import type { AgentKind } from '../agent-kinds.js';
+import type { Runner } from './index.js';
 /**
  * Registry of agent factories, keyed by `AgentKind`. `index.ts` registers one
  * factory per available agent at startup; `Bridge.getRunner(cwd)` looks

package/dist/runner/types.d.ts

@@ -3,7 +3,10 @@
  *
  * 本文件包含所有 Agent 相关的类型定义，从 runner/index.ts 提取。
  * 所有下游模块应从本文件 import 类型，而非直接依赖实现。
+ * （例外：`AgentKind` 住在 `src/agent-kinds.ts`，见文件底部说明。）
  */
+import type { AgentKind } from '../agent-kinds.js';
+import type { AgentSessionReader } from '../session-contract.js';
 export interface SystemInitEvent {
     type: 'system';
     subtype: 'init';
@@ -552,18 +555,7 @@ export interface Runner {
      */
     unregisterExitHandlers?(): void;
 }
-/**
- * Agent 名单单源（运行时数组 + 类型同源，二者不可能漂移）。
- *
- * 历史上这份名单被手抄成多份（router 的 VALID_AGENTS、bridge 的 resume.compact
- * 校验、各 agent 的 config builder…），漂移过：dsh 加入后 bridge 的
- * resume.compact 仍只有 5 个，带 dsh 的 resume 卡片会静默退回 defaultAgent。
- * 新增 agent 只改这里。
- */
-export declare const AGENT_KINDS: readonly ["claude", "codex", "opencode", "pi", "kimi", "dsh"];
-export type AgentKind = (typeof AGENT_KINDS)[number];
-/** 用户可见 agent 显示名单源：启动注册与无 registry 的回退路径共用。 */
-export declare const AGENT_DISPLAY_NAMES: Record<AgentKind, string>;
+export { AGENT_DISPLAY_NAMES } from '../agent-kinds.js';
 /**
  * Compact 能力声明（运行时门控的能力清单，编译期强制完整）。
  *
@@ -579,147 +571,6 @@ export declare const AGENT_DISPLAY_NAMES: Record<AgentKind, string>;
 export declare const COMPACT_CAPABILITY: Readonly<Record<AgentKind, boolean>>;
 /** 该 agent 是否声明支持 compact（渲染门控与执行门控共用的唯一判据）。 */
 export declare function supportsCompact(kind: AgentKind): boolean;
-/** Unified session descriptor returned by every AgentSessionReader. */
-export interface AgentSession {
-    sessionId: string;
-    summary: string;
-    mtime: number;
-    /** DSH：session 创建时固定的 preset；其他 agent 无此概念（undefined）。 */
-    agentPreset?: string;
-    /**
-     * 服务端投影已有的会话标题（DSH `projections.values.title`）。
-     *
-     * 与 `summary` 的区别：`summary` 是「首条用户输入」的兜底口径（claude /
-     * codex / pi / kimi 无标题字段），`title` 是 agent 自己起的标题。列表卡
-     * 用它决定标签文案（标题 / 会话摘要），缺省时回退 `summary`。
-     */
-    title?: string;
-    /**
-     * 最后一轮用户输入（服务端投影，单行预览）。
-     *
-     * 只给「列表响应里已顺带返回」的 reader 用（DSH 的 `turnOutline` 末条），
-     * 目的是让列表卡不必为每行做一次全量内容读取。
-     */
-    lastUserMessage?: string;
-    /** 最后一轮助手输出（服务端投影已截断，单行预览）。 */
-    lastAssistantMessage?: string;
-}
-/** A single renderable event from session history. */
-export interface AgentSessionContentEvent {
-    type: string;
-    /** 正文（展开后的面板内容）。 */
-    content: string;
-    /**
-     * 面板标题（可选，覆盖 reader 的默认标签）。
-     *
-     * 折叠面板默认只显示标题：工具调用这种"标题即全部信息"的事件必须把
-     * `bash — npm test` 这类摘要放进标题，否则折叠态只剩 `🔧 工具调用`。
-     */
-    title?: string;
-    timestamp?: string;
-}
-export interface AgentSessionUsage {
-    inputTokens: number;
-    outputTokens: number;
-    contextLength: number;
-    /** Agent 上报的当前模型 context window 上限（codex token_count.info.model_context_window）。
-     *  仅 codex 提供；缺省时卡片只显示绝对量、不显示百分比。 */
-    contextLimit?: number;
-    /** Claude auto-compact 次数（数 compact_boundary 事件）；codex/opencode 无此概念，留 undefined。 */
-    compactCount?: number;
-    /** 压缩前上下文水位（codex compact 后从会话 jsonl 读取，仅会话以压缩收尾时有值）。 */
-    compactPreContextLength?: number;
-    /** 从缓存读取的 token 数（节省的费用）。 */
-    cacheReadTokens?: number;
-    /** 新建缓存的 token 数。 */
-    cacheCreationTokens?: number;
-    /** Agent 声明的总量；展示用 max(total, 分项和)。 */
-    totalTokens?: number;
-    /** 会话累计 total token（所有 run 之和，含本次）。用于 Run 卡片"累计"展示。 */
-    cumulativeTotalTokens?: number;
-    /** 会话累计 input token（所有 run 之和，含本次）。用于 Run 卡片"累计"展示。 */
-    cumulativeInputTokens?: number;
-    /** 会话累计 output token（所有 run 之和，含本次）。 */
-    cumulativeOutputTokens?: number;
-    /** 会话累计 cache read token（所有 run 之和）。用于 Run 卡片展示累计缓存命中。 */
-    cumulativeCacheReadTokens?: number;
-    /** 会话累计 cache creation token（所有 run 之和）。 */
-    cumulativeCacheCreationTokens?: number;
-}
-/** Unified session content payload returned by every AgentSessionReader. */
-export interface SessionContent {
-    events: AgentSessionContentEvent[];
-    usage?: AgentSessionUsage;
-    aiTitle?: string;
-    recap?: string;
-    displayTitle?: string;
-}
-/**
- * Lightweight session summary used by `/resume` list prefetch.
- *
- * Carries only the display fields (title / recap / usage) — **no `events`
- * array**. Readers that can extract these without constructing the full event
- * list (e.g. codex, which would otherwise JSON.parse every response_item and
- * build an `events[]` that the prefetch immediately discards) implement the
- * optional `readSessionSummary` on `AgentSessionReader`.
- */
-export interface SessionSummary {
-    aiTitle?: string;
-    recap?: string;
-    displayTitle?: string;
-    usage?: AgentSessionUsage;
-}
-/**
- * Reads an agent's session history. Each agent implements its own (Claude reads
- * `~/.claude/projects/`, Codex calls `thread/list`, OpenCode calls `GET /session`).
- *
- * Q-C decision: `projectsDir` and other agent-specific path config live on the
- * concrete reader's constructor, NOT on these method opts. The router/bridge
- * depend only on this interface and never pass path config.
- */
-export interface AgentSessionReader {
-    /**
-     * List sessions for a cwd, newest first by mtime.
-     *
-     * `sessions` is the page `[offset, offset+limit)` of the full set ordered
-     * by mtime desc, with same-mtime ties broken by a deterministic secondary
-     * key (sessionId/file path) so ordering is stable across calls. When
-     * `limit` is omitted, codex/pi/kimi return their default-sized page
-     * (default 20); claude/opencode return the full remaining set from
-     * `offset`. `total` is ALWAYS the size of the full cwd-matched set before
-     * pagination — never the truncated page length. A negative `offset` is
-     * clamped to 0 (first page).
-     */
-    listSessions(cwd: string, opts?: {
-        limit?: number;
-        offset?: number;
-    }): {
-        sessions: AgentSession[];
-        total: number;
-    };
-    getNewestSession(cwd: string): AgentSession | null;
-    readSessionContent(sessionId: string, cwd: string, opts?: {
-        maxEvents?: number;
-    }): SessionContent;
-    /**
-     * Optional lightweight summary for list-prefetch.
-     *
-     * Returns only the display fields (aiTitle/recap/displayTitle/usage) without
-     * constructing the full `events` array. When absent, callers fall back to
-     * `readSessionContent` and take the needed fields.
-     */
-    readSessionSummary?(sessionId: string, cwd: string): SessionSummary;
-    /**
-     * Whether a session is still active (process may still be running).
-     *
-     * Dormant API: no production caller reads this today — the router decides
-     * "is an agent running" via the in-memory `bridge.isBusyFor(cwd)` (see
-     * `cmdPs`), not by probing session files. Retained on the reader contract
-     * because all 5 readers implement it and it is the natural hook if a
-     * file-based liveness check is ever needed; not wired into the bridge.
-     */
-    isSessionActive(sessionId: string, cwd: string): boolean;
-}
 /**
  * AgentRunner extends Runner with agent identity and a session reader.
  * Bridge/Router depend on this interface so adding a new agent is
@@ -732,6 +583,22 @@ export interface AgentRunner extends Runner {
     getStatusInfo(): AgentStatusInfo;
     /** Whether this runner provides live usage data (vs. file-based). */
     getUsageAuthority?(): 'live' | 'jsonl';
+    /**
+     * 回传审批决策（codex thread/permissions、ACP elicitation、DSH approval
+     * resolve）。未实现的 agent 由协调器按「无人应答」超时收尾。
+     */
+    respondApproval?(requestId: number | string, response: unknown): Promise<void>;
+    /**
+     * 停止 agent 侧的一个后台任务（DSH 的 background job）。只有支持后台任务的
+     * agent 实现；调用方按能力存在与否门控。
+     */
+    killJob?(sessionId: string, jobId: string): Promise<boolean>;
+    /**
+     * 热更审批模式/权限预设（config.save 后推给在跑的 runner，不必重启会话）。
+     * 各家 settings 词表不同（codex: approvalPolicy/sandbox；kimi: permissionMode；
+     * opencode: mode；dsh: permissionPreset），故为开放载荷。
+     */
+    updateApprovalMode?(settings: Record<string, unknown>): Promise<void>;
 }
 /** Agent self-describing status info for /status display. */
 export interface AgentStatusInfo {
@@ -746,4 +613,3 @@ export interface AgentStatusInfo {
     /** Agent-specific extra fields (e.g. codex.sandbox). */
     extras?: Record<string, string>;
 }
-export {};

package/dist/runner/types.js

@@ -1,30 +1,10 @@
-/**
- * Runner 模块类型定义
- *
- * 本文件包含所有 Agent 相关的类型定义，从 runner/index.ts 提取。
- * 所有下游模块应从本文件 import 类型，而非直接依赖实现。
- */
 // =============================================================================
 // Multi-Agent Adapter Types
 // =============================================================================
-/**
- * Agent 名单单源（运行时数组 + 类型同源，二者不可能漂移）。
- *
- * 历史上这份名单被手抄成多份（router 的 VALID_AGENTS、bridge 的 resume.compact
- * 校验、各 agent 的 config builder…），漂移过：dsh 加入后 bridge 的
- * resume.compact 仍只有 5 个，带 dsh 的 resume 卡片会静默退回 defaultAgent。
- * 新增 agent 只改这里。
- */
-export const AGENT_KINDS = ['claude', 'codex', 'opencode', 'pi', 'kimi', 'dsh'];
-/** 用户可见 agent 显示名单源：启动注册与无 registry 的回退路径共用。 */
-export const AGENT_DISPLAY_NAMES = {
-    claude: 'Claude',
-    codex: 'Codex',
-    opencode: 'Opencode',
-    pi: 'Pi',
-    kimi: 'Kimi',
-    dsh: 'DSH',
-};
+// Agent 名单与显示名住在 `src/agent-kinds.ts`（中立层，config/session/card 都
+// 要用）；本模块只 import `AgentKind` 类型来签名 runner 契约。保留旧路径的
+// re-export 兼容调用方，但值仍只由 agent-kinds.ts 定义。
+export { AGENT_DISPLAY_NAMES } from '../agent-kinds.js';
 /**
  * Compact 能力声明（运行时门控的能力清单，编译期强制完整）。
  *

package/dist/session/claude/session-index.d.ts

@@ -74,15 +74,22 @@ export declare class SessionIndex {
     private readonly byCwd;
     private lastRefreshAt;
     private built;
+    private scanError?;
     constructor(projectsDir: string, opts?: SessionIndexOptions);
     /** Whether a full scan has ever completed successfully (readdir succeeded). */
     get isBuilt(): boolean;
+    /**
+     * 最近一次全量扫描的非 ENOENT 失败（undefined = 上次扫描正常）。
+     * list 路径用它把「读不到」与「真的没有」区分开。
+     */
+    get lastScanError(): unknown;
     build(): void;
     refresh(): void;
-    listByCwd(cwd: string, opts?: {
-        limit?: number;
-        offset?: number;
-    }): SessionIndexEntry[];
+    /**
+     * 该 cwd 的全部会话（newest first）。分页不在这里：`listSessions` 的
+     * offset/limit 契约由 reader 用共享 `paginate()` 完成，索引只负责有序全集。
+     */
+    listByCwd(cwd: string): SessionIndexEntry[];
     /**
      * Find a session entry by sessionId and cwd.
      * Re-stats the file to verify fingerprint before returning (拍板 3):

package/dist/session/claude/session-index.js

@@ -83,6 +83,7 @@ export function parseSessionJsonl(filePath) {
     });
     // If file couldn't be opened, return empty result
     if (!ok) {
+        getLogger().debug(`[session-index] unreadable session file ${filePath}, treating as empty`);
         return { cwdSet: new Set(), summary: '(无摘要)' };
     }
     return { cwdSet, summary };
@@ -98,7 +99,12 @@ export function buildFingerprint(filePath) {
     try {
         st = fs.statSync(filePath, { bigint: true });
     }
-    catch {
+    catch (err) {
+        // ENOENT = 文件在扫描间隙被删除（正常竞态）。其余（EACCES/EBUSY…）留痕，
+        // 否则该会话会静默从 /resume 列表里消失。
+        if (err.code !== 'ENOENT') {
+            getLogger().warn(`[session-index] cannot stat ${filePath}: ${err?.message ?? String(err)}`);
+        }
         return '';
     }
     const parts = [String(st.size), String(st.mtimeNs)];
@@ -153,6 +159,7 @@ export class SessionIndex {
     byCwd = new Map();
     lastRefreshAt = 0;
     built = false;
+    scanError;
     constructor(projectsDir, opts = {}) {
         this.projectsDir = projectsDir;
         this.refreshIntervalMs = opts.refreshIntervalMs ?? 5000;
@@ -162,6 +169,13 @@ export class SessionIndex {
     get isBuilt() {
         return this.built;
     }
+    /**
+     * 最近一次全量扫描的非 ENOENT 失败（undefined = 上次扫描正常）。
+     * list 路径用它把「读不到」与「真的没有」区分开。
+     */
+    get lastScanError() {
+        return this.scanError;
+    }
     // ── Build (initial full scan) ───────────────────────────
     build() {
         this.fullScan();
@@ -177,7 +191,11 @@ export class SessionIndex {
         this.lastRefreshAt = now;
     }
     // ── Query: listByCwd ────────────────────────────────────
-    listByCwd(cwd, opts = {}) {
+    /**
+     * 该 cwd 的全部会话（newest first）。分页不在这里：`listSessions` 的
+     * offset/limit 契约由 reader 用共享 `paginate()` 完成，索引只负责有序全集。
+     */
+    listByCwd(cwd) {
         const paths = this.byCwd.get(pathKey(cwd, { platform: this.platform }));
         if (!paths || paths.size === 0)
             return [];
@@ -194,10 +212,7 @@ export class SessionIndex {
         }
         const sorted = [...byId.values()];
         sortByRecencyDesc(sorted, (s) => s.mtimeMs, (s) => s.sessionId);
-        const offset = opts.offset ?? 0;
-        const limit = opts.limit;
-        const sliced = limit === undefined ? sorted.slice(offset) : sorted.slice(offset, offset + limit);
-        return sliced;
+        return sorted;
     }
     // ── Query: findBySessionIdAndCwd ────────────────────────
     /**
@@ -261,11 +276,18 @@ export class SessionIndex {
         try {
             entries = fs.readdirSync(this.projectsDir);
         }
-        catch {
+        catch (err) {
             // readdir failure → preserve old index, degrade to fallback
-            getLogger().warn('[session-index] readdir failed, preserving old index');
+            if (err.code === 'ENOENT') {
+                // projectsDir 不存在 = 全新环境（真空态），不是故障。
+                this.scanError = undefined;
+                return;
+            }
+            this.scanError = err;
+            getLogger().warn(`[session-index] readdir ${this.projectsDir} failed, preserving old index: ${err?.message ?? String(err)}`);
             return;
         }
+        this.scanError = undefined;
         // readdir succeeded → the snapshot is authoritative for what we could read.
         this.built = true;
         const currentPaths = new Set();

package/dist/session/claude/session-reader.d.ts

@@ -1,4 +1,4 @@
-import type { AgentSession, AgentSessionReader, SessionContent } from '../../runner/index.js';
+import type { AgentSession, AgentSessionReader, SessionContent } from '../../session-contract.js';
 /**
  * Adapter that exposes Claude Code's session-reading functions through the
  * unified `AgentSessionReader` interface. This lets `SessionReaderRegistry`

package/dist/session/claude/sessions.d.ts

@@ -1,4 +1,4 @@
-import type { AgentSession, AgentSessionContentEvent, AgentSessionUsage } from '../../runner/index.js';
+import type { AgentSession, AgentSessionContentEvent, AgentSessionUsage } from '../../session-contract.js';
 /**
  * List Claude Code sessions for a given cwd, newest first. Each entry has
  * the sessionId (= jsonl filename stem), a one-line summary extracted from
@@ -15,7 +15,7 @@ export declare function getNewestSession(cwd: string, opts?: {
 }): AgentSession | undefined;
 /**
  * Check if a Claude session (by sessionId + cwd) is still active.
- * Public wrapper around the internal `isSessionActive(filePath, mtimeMs, now)`
+ * Public wrapper around the internal `hasRecentFileActivity(filePath, mtimeMs, now)`
  * for use by `ClaudeSessionReader` and the multi-agent adapter layer.
  *
  * Resolves the jsonl path via `projectDirForCwd`, stats it for mtime, then

package/dist/session/claude/sessions.js

@@ -6,6 +6,7 @@ import { isStale } from '../common/constants.js';
 import { samePath, encodeProjectDirName } from '../../platform/path.js';
 import { extractContentBlocks } from '../common/content-blocks.js';
 import { scanJsonlOnce, tailOffsetAfter, scanTailEvents } from '../common/two-pass.js';
+import { getLogger } from '../../logger/index.js';
 import { UsageAccumulator, contextWindowOccupancy, cumulativeUsageFields, } from '../common/usage-accumulator.js';
 import { SessionIndex, extractText, isTaskNotificationText, CLAUDE_MAPPING, } from './session-index.js';
 /**
@@ -61,7 +62,10 @@ function findSessionFileInProjects(sessionId, projectsDir, cwd) {
     try {
         entries = fs.readdirSync(projectsDir);
     }
-    catch {
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            getLogger().debug(`[claude-session-reader] cannot read projects dir ${projectsDir}: ${err?.message ?? String(err)}`);
+        }
         return undefined;
     }
     const name = `${sessionId}.jsonl`;
@@ -123,6 +127,13 @@ export function listClaudeSessions(cwd, opts = {}) {
         summary: e.summary,
         mtime: e.mtimeMs,
     }));
+    // 空列表 + 上次扫描是非 ENOENT 失败 → 是「读不到」而非「真的没有」。
+    // 与 opencode/kimi/pi 同口径：router 显示「列表失败」，别假装空态。
+    if (sessions.length === 0 && index.lastScanError !== undefined) {
+        const err = index.lastScanError;
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`claude session list 读取失败: ${msg}`, { cause: err });
+    }
     return limit === undefined ? sessions : sessions.slice(0, limit);
 }
 /** Get the newest session for a given cwd. Returns undefined if none exist. */
@@ -145,7 +156,15 @@ export function getNewestSession(cwd, opts = {}) {
  *
  * Override `now` for tests.
  */
-function isSessionActive(filePath, mtimeMs, now = Date.now()) {
+/** 末行是这些类型之一 = 会话已收尾（模块级：逐文件判定不必每次重建 Set）。 */
+const CLAUDE_TERMINAL_TYPES = new Set(['result', 'last-prompt', 'mode', 'permission-mode']);
+/**
+ * 文件侧的活跃判定：mtime 新鲜 + 末行没有终态标记。
+ *
+ * 刻意不叫 `isSessionActive`——那是 reader 契约上的方法名，语义各家自己定；
+ * 本函数只看这一个文件，两者同名不同义曾让人把「最近有写入」当成「turn 在跑」。
+ */
+function hasRecentFileActivity(filePath, mtimeMs, now = Date.now()) {
     // Hard signal: file untouched for over an hour → can't be from a live process
     if (isStale(mtimeMs, now))
         return false;
@@ -158,8 +177,7 @@ function isSessionActive(filePath, mtimeMs, now = Date.now()) {
         // `last-prompt` / `mode` (no `result` event) to mark turn end, so a
         // 24-minute-old session with a last-prompt tail is already done
         // (regression 2026-06-21: previously falsely reported as active).
-        const TERMINAL_TYPES = new Set(['result', 'last-prompt', 'mode', 'permission-mode']);
-        if (typeof obj.type === 'string' && TERMINAL_TYPES.has(obj.type))
+        if (typeof obj.type === 'string' && CLAUDE_TERMINAL_TYPES.has(obj.type))
             return false;
     }
     catch {
@@ -167,9 +185,18 @@ function isSessionActive(filePath, mtimeMs, now = Date.now()) {
     }
     return true;
 }
+/**
+ * stat 失败：ENOENT = 文件在两次查询之间消失（正常竞态）；其余 errno 必须留痕，
+ * 否则「文件不可读」会被当成「会话不活跃」。
+ */
+function logStatFailure(filePath, err) {
+    if (err.code === 'ENOENT')
+        return;
+    getLogger().debug(`[claude-session-reader] stat ${filePath} failed: ${err?.message ?? String(err)}`);
+}
 /**
  * Check if a Claude session (by sessionId + cwd) is still active.
- * Public wrapper around the internal `isSessionActive(filePath, mtimeMs, now)`
+ * Public wrapper around the internal `hasRecentFileActivity(filePath, mtimeMs, now)`
  * for use by `ClaudeSessionReader` and the multi-agent adapter layer.
  *
  * Resolves the jsonl path via `projectDirForCwd`, stats it for mtime, then
@@ -187,9 +214,10 @@ export function isClaudeSessionActive(sessionId, cwd, opts = {}) {
         if (entry) {
             try {
                 const st = fs.statSync(entry.path);
-                return isSessionActive(entry.path, st.mtimeMs);
+                return hasRecentFileActivity(entry.path, st.mtimeMs);
             }
-            catch {
+            catch (err) {
+                logStatFailure(entry.path, err);
                 return false;
             }
         }
@@ -210,9 +238,10 @@ export function isClaudeSessionActive(sessionId, cwd, opts = {}) {
             return false;
         try {
             const st = fs.statSync(filePath);
-            return isSessionActive(filePath, st.mtimeMs);
+            return hasRecentFileActivity(filePath, st.mtimeMs);
         }
-        catch {
+        catch (err) {
+            logStatFailure(filePath, err);
             return false;
         }
     }
@@ -411,23 +440,9 @@ export function readSessionContent(sessionId, cwd, opts = {}) {
             return { events: [] };
         }
     }
-    // First pass STREAMS the file once via
-    // `scanJsonlLines` (no `string[]` materialized), parsing each line once to
-    // collect scalars (usage, tailOffset, aiTitle, recap, lastUserMessage)
-    // while retaining NO parsed objects and NO whole-file line array. The
-    // tailOffset is the byte offset where the tail begins (start of the line
-    // after the last user message). A second pass re-reads ONLY the tail from
-    // that offset via `readJsonlLinesFromOffset` and re-parses it for events —
-    // O(tail) memory for both raw line strings and parsed objects, instead of
-    // O(whole file).
-    //
-    // Parse ratio: ≈1.0–1.5× line count when a user message exists (streaming
-    // full-file scan + tail re-parse of the usually-short post-user lines).
-    // When the session has NO user message, tailOffset stays -1 and the tail
-    // IS the whole file → scan(N) + tail(N) = 2.0× — the known asymptotic
-    // upper bound of the body's two-phase design (still better than pre-'s
-    // ~3×). Total parse count adds the index-miss fallback guard's fixed
-    // early-stop overhead (~2 parses, independent of line count).
+    // Two-pass 扫描（pass 1 流式收标量 + pass 2 只重读 tail）的口径与解析比
+    // 见 `src/session/common/two-pass.ts` 头注释；claude 侧只多一项：索引 miss
+    // 时的 fallback 守卫另有固定 ~2 次早停解析，与行数无关。
     const scan = scalarScan(filePath);
     // 有 usage 即返回：非累计字段已是末轮 scope，命中判定用 session 累计兜底
     // （末轮可能 input/output 为 0 而仍有 cacheRead，累计口径不会被末轮遮挡）。

package/dist/session/codex/rollout-reader.d.ts

@@ -23,7 +23,7 @@
  * Note: This handles the **rollout file format** (historical logging), NOT the
  * `codex exec --json` stdout format（已随 exec 模式移除）。
  */
-import type { AgentSessionContentEvent, SessionContent, SessionSummary, AgentSessionUsage } from '../../runner/index.js';
+import type { AgentSessionContentEvent, AgentSessionUsage, SessionContent, SessionSummary } from '../../session-contract.js';
 interface CodexRolloutEntry {
     threadId: string;
     cwd: string;

package/dist/session/codex/rollout-reader.js

@@ -32,6 +32,7 @@ import { paginate, capEvents } from '../common/pagination.js';
 import { sortByRecencyDesc } from '../common/recency.js';
 import { getLogger } from '../../logger/index.js';
 import { isRecord, stringValue } from '../../common/guards.js';
+import { TtlCache } from '../../common/ttl-cache.js';
 import { resolveCodexHome } from '../../config/codex-config.js';
 /** Field-wise difference (total - previous) for cumulative->incremental. */
 function subtractRawUsage(a, b) {
@@ -623,7 +624,12 @@ function safeIsDir(p) {
     }
 }
 const INDEX_TTL_MS = 5_000; // 5 seconds — covers a single /resume flow
-const sessionIndexCache = new Map();
+/**
+ * codexHome → 会话索引。共享 `TtlCache`（TTL 由写入时间判定 + LRU 上限），
+ * 与 kimi/pi/opencode 三个 reader 同一套语义。生产侧 `CodexSessionReader`
+ * 构造时就把 codexHome 解析定死，实际只会用到 1 个键；上限是防漏的界。
+ */
+const sessionIndexCache = new TtlCache(INDEX_TTL_MS, 4);
 /**
  * Build or return cached session index for a given resolved codexHome.
  * The index maps sessionId → {filePath, cwd, mtimeMs}.
@@ -635,19 +641,14 @@ const sessionIndexCache = new Map();
  *                           AFTER the cache was built — but still within the
  *                           5s TTL — is found without waiting for expiry.
  *
- * Cache shape note: `sessionIndexCache` is module-level and keyed by the
- * resolved codexHome string. In production `CodexSessionReader` resolves
- * codexHome once in its constructor and reuses it for every call, so a single
- * bridge instance produces exactly one cache entry — the Map does NOT grow
- * unbounded. The TTL refreshes the value on each rebuild; entries are never
- * evicted, but there is effectively just one.
+ * Cache shape note: the cache is module-level and keyed by the resolved
+ * codexHome string; `TtlCache` caps entries (LRU) so a caller that injects
+ * many distinct codexHomes cannot grow memory without bound.
  */
 function getSessionIndex(resolvedCodexHome, forceRefresh = false) {
-    const cacheKey = resolvedCodexHome;
-    const cached = sessionIndexCache.get(cacheKey);
-    if (!forceRefresh && cached && Date.now() - cached.builtAt < INDEX_TTL_MS) {
-        return cached.index;
-    }
+    const cached = forceRefresh ? undefined : sessionIndexCache.get(resolvedCodexHome);
+    if (cached)
+        return cached;
     const sessionsDir = path.join(resolvedCodexHome, 'sessions');
     const files = walkRolloutFiles(sessionsDir);
     const index = new Map();
@@ -704,7 +705,7 @@ function getSessionIndex(resolvedCodexHome, forceRefresh = false) {
             continue;
         }
     }
-    sessionIndexCache.set(cacheKey, { index, builtAt: Date.now() });
+    sessionIndexCache.set(resolvedCodexHome, index);
     return index;
 }
 /** Clear the session index cache. Exposed for tests. */

package/dist/session/codex/sessions.d.ts

@@ -1,4 +1,4 @@
-import type { AgentSession, SessionContent, SessionSummary, AgentSessionReader } from '../../runner/index.js';
+import type { AgentSession, AgentSessionReader, SessionContent, SessionSummary } from '../../session-contract.js';
 interface CodexSessionReaderOptions {
     codexHome?: string;
 }