lark-remote 0.5.12 → 0.5.14

package/dist/runner/pi/rpc/translator.js

@@ -10,6 +10,7 @@
  *     `result` from that response.
  *   - `agent_settled` is ignored for compaction turns (no double result).
  */
+import { makeTurnStartedEvent } from '../../common/turn-started.js';
 export class PiRpcTranslator {
     content = [];
     currentContentIndex = -1;
@@ -135,13 +136,7 @@ export class PiRpcTranslator {
     /** Self-produced turn_started (no wire equivalent). */
     produceTurnStarted(sessionId, turnId) {
         this.sessionId = sessionId;
-        return {
-            type: 'turn_started',
-            threadId: sessionId,
-            turnId,
-            operationKind: this.operationKind === 'compact' ? 'compaction' : 'turn',
-            timestamp: new Date().toISOString(),
-        };
+        return makeTurnStartedEvent(sessionId, turnId, this.operationKind);
     }
     /** Result for a completed normal turn (agent_settled). */
     produceResultFromSettled() {

package/dist/runner/probe.d.ts

@@ -17,7 +17,7 @@
  *   does PATH + X_OK on posix (same semantics) and PATH × PATHEXT on win32,
  *   with no child process at all.
  */
-import type { AgentKind } from './types.js';
+import type { AgentKind } from '../agent-kinds.js';
 /**
  * Probe a single agent, using cache when fresh.
  * Updates cache on completion.

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
@@ -14,28 +15,9 @@ import type { AgentKind, Runner } from './index.js';
  */
 export declare class AgentRegistry {
     private readonly factories;
-    private readonly displayNames;
     /** Container for runtime config updates (pi provider dynamic reload). */
     private configContainer?;
     register(kind: AgentKind, factory: (cwd: string) => Runner): void;
-    /**
-     * 注册 agent 的显示名。应在 register(kind, factory) 后调用。
-     * 用于 agentDisplayName 等全局查询，实现单点真相。
-     */
-    registerDisplayName(kind: AgentKind, displayName: string): void;
-    /**
-     * 获取 agent 显示名。未注册时返回原始 kind。
-     */
-    getDisplayName(kind: AgentKind): string;
-    /**
-     * 设置全局 registry 实例，供 agentDisplayName 等全局函数使用。
-     * 在 index.ts 初始化所有 agents 后调用。
-     */
-    static setGlobalInstance(reg: AgentRegistry | undefined): void;
-    /**
-     * 获取全局 registry 实例。
-     */
-    static getGlobalInstance(): AgentRegistry | undefined;
     /**
      * Set config container reference. Call after bridge config is updated.
      * Factory functions can read latest config from here.

package/dist/runner/registry.js

@@ -1,8 +1,3 @@
-/**
- * 单例 registry 实例，供 agentDisplayName 等全局查询使用。
- * 在 index.ts 初始化后设置。
- */
-let globalRegistry;
 /**
  * Registry of agent factories, keyed by `AgentKind`. `index.ts` registers one
  * factory per available agent at startup; `Bridge.getRunner(cwd)` looks
@@ -18,38 +13,11 @@ let globalRegistry;
  */
 export class AgentRegistry {
     factories = new Map();
-    displayNames = new Map();
     /** Container for runtime config updates (pi provider dynamic reload). */
     configContainer;
     register(kind, factory) {
         this.factories.set(kind, factory);
     }
-    /**
-     * 注册 agent 的显示名。应在 register(kind, factory) 后调用。
-     * 用于 agentDisplayName 等全局查询，实现单点真相。
-     */
-    registerDisplayName(kind, displayName) {
-        this.displayNames.set(kind, displayName);
-    }
-    /**
-     * 获取 agent 显示名。未注册时返回原始 kind。
-     */
-    getDisplayName(kind) {
-        return this.displayNames.get(kind) ?? kind;
-    }
-    /**
-     * 设置全局 registry 实例，供 agentDisplayName 等全局函数使用。
-     * 在 index.ts 初始化所有 agents 后调用。
-     */
-    static setGlobalInstance(reg) {
-        globalRegistry = reg;
-    }
-    /**
-     * 获取全局 registry 实例。
-     */
-    static getGlobalInstance() {
-        return globalRegistry;
-    }
     /**
      * Set config container reference. Call after bridge config is updated.
      * Factory functions can read latest config from here.

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';
@@ -263,6 +266,22 @@ export interface AssistantEvent {
         content: AssistantContent[];
     };
 }
+/**
+ * Authoritative final answer from an agent protocol.
+ *
+ * This is deliberately separate from ordinary assistant text: progress
+ * narration and tool-loop messages have lower display priority than the answer
+ * the user actually asked for. Agents without an explicit protocol marker
+ * promote their last text block when the turn finishes.
+ */
+export interface FinalAnswerEvent {
+    type: 'final_answer';
+    text: string;
+    /** Source item id, used to remove the streamed progress copy of the answer. */
+    itemId?: string;
+    complete?: boolean;
+    timestamp?: string;
+}
 export interface UserEvent {
     type: 'user';
     timestamp?: string;
@@ -470,7 +489,7 @@ export interface TurnDiffEvent {
 export type RunnerLifetime = 'turn' | 'workspace';
 /** 工具渲染 hint：runner 自愿声明，渲染层只消费不推断。 */
 export type ToolHint = 'shell' | 'file' | 'search' | 'web' | 'patch';
-export type AgentEvent = SystemInitEvent | SystemCompactEvent | ApprovalRequestedEvent | ApprovalResolvedEvent | ApprovalViewUpdatedEvent | ApprovalExpiredEvent | AssistantEvent | UserEvent | ResultEvent | PlanEvent | FileChangeEvent | TurnStartedEvent | TurnDiffEvent | NoticeEvent | SessionInfoEvent | RunStatusEvent | BackgroundJobsEvent | GoalStateEvent;
+export type AgentEvent = SystemInitEvent | SystemCompactEvent | ApprovalRequestedEvent | ApprovalResolvedEvent | ApprovalViewUpdatedEvent | ApprovalExpiredEvent | AssistantEvent | FinalAnswerEvent | UserEvent | ResultEvent | PlanEvent | FileChangeEvent | TurnStartedEvent | TurnDiffEvent | NoticeEvent | SessionInfoEvent | RunStatusEvent | BackgroundJobsEvent | GoalStateEvent;
 export interface SpawnOptions {
     cwd: string;
     sessionId?: string;
@@ -536,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 能力声明（运行时门控的能力清单，编译期强制完整）。
  *
@@ -563,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
@@ -716,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 {
@@ -730,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();
@@ -277,14 +299,16 @@ export class SessionIndex {
                 if (!st.isDirectory())
                     continue;
             }
-            catch {
+            catch (err) {
+                getLogger().debug(`[session-index] skipped unreadable project dir ${subdir}: ${err?.message ?? String(err)}`);
                 continue;
             }
             let files;
             try {
                 files = fs.readdirSync(subdir).filter((f) => f.endsWith('.jsonl'));
             }
-            catch {
+            catch (err) {
+                getLogger().debug(`[session-index] skipped unreadable project subdir ${subdir}: ${err?.message ?? String(err)}`);
                 continue;
             }
             for (const f of files) {

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