lark-remote 0.1.4 → 0.1.5

package/dist/router/index.js

@@ -11,8 +11,9 @@ import { activeRunUsage, formatUsageStats } from './utils.js';
 import { markdownDiv, sessionEventPanel } from './card-helpers.js';
 import { MAX_FILE_UPLOAD_SIZE } from '../connector/file-limits.js';
 import { atomicWrite } from '../persistence/atomic-write.js';
+import { checkLatestVersion as defaultCheckLatestVersion, isNewer as defaultIsNewer, runInstallLatest as defaultRunInstallLatest, } from '../update/index.js';
 /** Config card builder - delegates to per-agent builders */
-import { getConfigBuilder, listRegisteredAgents, sortAgentsByAvailability, } from './config/index.js';
+import { getConfigBuilder, listRegisteredAgents } from './config/index.js';
 import { probeAllAgents, getCachedAvailability } from '../runner/probe.js';
 import { buildConfigCardFromTabs } from './config/common/render.js';
 /** Max events to read for auto-resume and /resume cards.
@@ -114,6 +115,12 @@ export class CommandRouter {
      */
     restartSpawner;
     idleTimeoutMs;
+    /** Dev mode flag: --dev means the bridge was started from source (bun src/index.ts). */
+    devMode;
+    /** Cache file for version checks (<configDir>/update-cache.json). */
+    updateCachePath;
+    /** Injected update functions (for testability; defaults to real implementation). */
+    updateFns;
     pendingConfig = null; // /config 卡片编辑暂存区
     /**
      * Monotonic counter minting unique internal keys for order.exec enqueue
@@ -161,6 +168,13 @@ export class CommandRouter {
             this.bridge.setIdleTimeout(this.idleTimeoutMs);
         }
         this.sessionReaderRegistry = opts.sessionReaderRegistry;
+        this.devMode = opts.devMode ?? false;
+        this.updateCachePath = opts.updateCachePath;
+        this.updateFns = {
+            checkLatestVersion: opts.updateFns?.checkLatestVersion ?? defaultCheckLatestVersion,
+            isNewer: opts.updateFns?.isNewer ?? defaultIsNewer,
+            runInstallLatest: opts.updateFns?.runInstallLatest ?? defaultRunInstallLatest,
+        };
     }
     /**
      * Resolve the active session reader for the current defaultAgent.
@@ -322,7 +336,7 @@ export class CommandRouter {
                     }
                     return;
                 }
-                // AGENTS.md red-line: miss paths must reply via bridge.sendResult —
+                // Design constraint: miss paths must reply via bridge.sendResult —
                 // don't silently swallow unknown card actions.
                 getLogger().warn(`[router] unknown card action: ${value.cmd}`);
                 await this.bridge.sendResult({ text: `⚠️ 未知的卡片操作: ${value.cmd}` }, ctx);
@@ -1191,7 +1205,7 @@ export class CommandRouter {
                     this.config = setConfigValues(this.configPath, this.config, updates);
                     // P1-6：运行时传播（idleTimeout / clearRunners / syncAgentChoices /
                     // defaultAgent 切换的 session 处理）抽到共享方法，与文本直写路径共用。
-                    const switchNotice = this.propagateConfigSave(oldDefaultAgent, updates, ctx);
+                    const switchResult = this.propagateConfigSave(oldDefaultAgent, updates, ctx);
                     this.pendingConfig = null;
                     // 原地更新卡片：保存后卡片刷新为已保存状态（2026-07-04）
                     // 2026-08-03: 卡片刷新失败不吞切换通知——保存已成功，仅记录日志，
@@ -1202,14 +1216,15 @@ export class CommandRouter {
                     catch (refreshErr) {
                         getLogger().warn(`[router] config.save 卡片刷新失败（保存已成功）: ${refreshErr.message}`);
                     }
-                    // 2026-08-03: agent 切换时发送持久化消息通知用户（toast 不持久化，
-                    // 聊天记录不可回溯）；发送失败（resolve false，不 throw）时兜底回退
-                    // toast 即时反馈，复用同一个切换文案。
-                    if (switchNotice) {
-                        const sent = await this.bridge.sendResult({ text: switchNotice }, ctx);
+                    // 2026-08-13: agent 切换时发送 Resume 卡片（替代纯文本通知），
+                    // 让用户直观看到新 agent 的会话状态和历史。
+                    // 发送失败（resolve false）时兜底回退 toast 即时反馈。
+                    if (switchResult.notice) {
+                        const switchCard = this.buildConfigSwitchCard(switchResult, ctx);
+                        const sent = await this.bridge.sendResult(switchCard, ctx);
                         if (!sent) {
                             return {
-                                toast: { type: 'info', content: switchNotice },
+                                toast: { type: 'info', content: switchResult.notice },
                             };
                         }
                     }
@@ -1311,7 +1326,7 @@ export class CommandRouter {
      *
      * @param updates 以 config 路径形式给出的变更 key（卡片路径来自 diffConfig；
      *   直写路径传 mapAgentKey(key)，保证 pi./codex./opencode./kimi. 命中 agents.*）。
-     * @returns defaultAgent 切换时的通知文案（未切换返回 undefined）
+     * @returns 结构化切换结果（含 notice 文案 + 新 agent/sessionId 信息）
      */
     propagateConfigSave(oldDefaultAgent, updates, ctx) {
         this.bridge.setConfig(this.config);
@@ -1336,13 +1351,12 @@ export class CommandRouter {
         // 同时清除新 agent 的 sessionId（等效于 /new 命令），
         // 并支持 session 恢复 - 切换回来时如果条件满足则恢复之前的 session。
         let switchNotice;
+        let switchNewAgent;
+        let switchSessionId;
         if (hasDefaultAgentChange) {
             const newAgent = this.config.defaultAgent;
+            switchNewAgent = newAgent;
             // Step 0: 在清空 old 之前计算「用户活动」基线差（arrival 基线）：
-            // arrivalSessions[old] 是用户最近一次经 config.save 切换「到达」该 agent
-            // 时被赋予的 session id（清空到达 = ''）。当前 session 与到达基线不一致
-            // ⇒ 用户在 oldAgent 上产生过用户活动（发消息 /resume /new /cd 等，均
-            // 不更新 arrival），离开时恢复必须被阻断。
             const oldSessionId = this.sessionStore.getSessionId(ctx.userId, oldDefaultAgent);
             const oldArrivalSessionId = this.sessionStore.getArrivalSessionId(ctx.userId, oldDefaultAgent);
             const userChangedOld = (oldSessionId ?? '') !== (oldArrivalSessionId ?? '');
@@ -1352,48 +1366,36 @@ export class CommandRouter {
             }
             // Step 2: 清除旧 agent 的 session（保存后清除，为新会话腾出空间）
             this.sessionStore.clearSessionId(ctx.userId, oldDefaultAgent);
-            // Step 2.5: 显式选择判定——sessions[new] 非空且不等于到达基线 ⇒ 用户经 /resume
-            // 显式改选了 new 的 session（/resume 不更新 arrival），切换时必须让选择存活。
-            // 优先级：显式选择 > 停车恢复 > 清空；newSessionId 为空（防御）不触发本分支。
+            // Step 2.5: 显式选择判定
             const newSessionId = this.sessionStore.getSessionId(ctx.userId, newAgent);
             const newArrivalSessionId = this.sessionStore.getArrivalSessionId(ctx.userId, newAgent);
             const userSelectedNew = !!newSessionId && (newSessionId ?? '') !== (newArrivalSessionId ?? '');
-            // Step 3: 恢复判定——previousSessions[newAgent] 存在 且 用户在 oldAgent 上
-            // 没有用户活动（session 未变于到达基线）。判断方法：arrival 基线差
-            // userChangedOld 为 false 时，oldAgent 的 session 只可能是 config.save
-            // 自动恢复/清空得到的，不构成用户活动，恢复不被阻断。
+            // Step 3: 恢复判定
             const previousSessionId = this.sessionStore.getPreviousSessionId(ctx.userId, newAgent);
             const canRestore = !!previousSessionId && !userChangedOld;
             if (userSelectedNew) {
-                // 显式选择优先于停车恢复与用户活动阻断：保留 sessions[new]（不动），更新
-                // arrival 基线为所选 session；prev[new] 停车位原样保留（下次离开时会被
-                // sessions[new] 覆盖停车）。
                 this.sessionStore.setArrivalSessionId(ctx.userId, newAgent, newSessionId);
                 const newAgentName = agentDisplayName(newAgent);
                 switchNotice = `已切换到 ${newAgentName}，已使用所选 session，sessionId: ${newSessionId}`;
+                switchSessionId = newSessionId;
             }
             else if (canRestore) {
-                // 可以恢复之前的 session
                 this.sessionStore.setSessionId(ctx.userId, newAgent, previousSessionId);
-                // 恢复分支消费 previousSessions，并记录新的到达基线（自动恢复的 session
-                // 不构成用户活动，后续离开时 userChangedOld 仍为 false）
                 this.sessionStore.clearPreviousSessionId(ctx.userId, newAgent);
                 this.sessionStore.setArrivalSessionId(ctx.userId, newAgent, previousSessionId);
                 const newAgentName = agentDisplayName(newAgent);
                 switchNotice = `已切换到 ${newAgentName}，将继续之前的 session，sessionId: ${previousSessionId}`;
+                switchSessionId = previousSessionId;
             }
             else {
-                // Step 4: 清除新 agent 的 session（等效于 /new）
                 this.sessionStore.clearSessionId(ctx.userId, newAgent, { clearSessionCwd: true });
-                // 清空分支不清除 previousSessions[newAgent]（停车语义：被拒绝的恢复
-                // 机会保留，未来无用户活动的返回仍可恢复）；记录清空到达基线
                 this.sessionStore.setArrivalSessionId(ctx.userId, newAgent, '');
                 const newAgentName = agentDisplayName(newAgent);
                 switchNotice = `已切换到 ${newAgentName}，session 已清空，下次消息将启动新对话`;
+                switchSessionId = '';
             }
         }
         // 2026-07-13: 同步 agent 配置到 agentChoices（用于切换 agent 时恢复配置）
-        // 检测是否有当前 agent 的配置变更
         const currentAgent = this.config.defaultAgent;
         const currentAgentConfigKey = `agents.${currentAgent}`;
         const hasCurrentAgentUpdate = Object.keys(updates).some((k) => k === currentAgentConfigKey || k.startsWith(`${currentAgentConfigKey}.`));
@@ -1404,11 +1406,10 @@ export class CommandRouter {
             this.bridge.setConfig(this.config);
         }
         // 2026-07-13: 任何 agent 配置变更或 defaultAgent 切换，都清除 runner 缓存
-        // 否则 runner 仍使用旧配置值
         if (hasDefaultAgentChange || hasAgentConfigChange) {
             this.bridge.clearRunners();
         }
-        return switchNotice;
+        return { notice: switchNotice, newAgent: switchNewAgent, sessionId: switchSessionId };
     }
     async executeCommand(message, ctx) {
         const parts = message.slice(1).split(/\s+/);
@@ -1453,6 +1454,9 @@ export class CommandRouter {
             case 'order':
             case 'o':
                 return this.cmdOrder(args, ctx);
+            case 'update':
+            case 'u':
+                return await this.cmdUpdate(args, ctx);
             default:
                 return { text: `未知命令 /${cmd}，输入 /help 查看可用命令` };
         }
@@ -1472,6 +1476,7 @@ export class CommandRouter {
             { cmd: 'active', label: '/active', desc: '查看所有正在进行中的 session' },
             { cmd: 'exit', label: '/exit /e', desc: '退出 bridge' },
             { cmd: 'restart', label: '/restart', desc: '重启 bridge（新进程，config 不变）' },
+            { cmd: 'update', label: '/update /u', desc: '检查并升级到最新版本' },
             { cmd: 'status', label: '/status /s', desc: '显示当前状态' },
             { cmd: 'reconnect', label: '/reconnect', desc: '重连飞书' },
         ].sort((a, b) => a.label.length - b.label.length || a.cmd.localeCompare(b.cmd));
@@ -1658,6 +1663,61 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
             return { text: `重启失败：${err.message}，旧进程仍在运行` };
         }
     }
+    /**
+     * /update: check for newer version and upgrade if available.
+     * /update check: only check, don't upgrade.
+     *
+     * Flow: check version → if newer, install → spawn replacement bridge → exit.
+     * Reuses /restart's restartSpawner + pendingExit mechanism.
+     */
+    async cmdUpdate(args, ctx) {
+        const checkOnly = args[0] === 'check';
+        // 1. Version query（/update check 始终绕过缓存，/update 用 TTL 缓存）
+        let current;
+        let latest;
+        try {
+            const result = await this.updateFns.checkLatestVersion({
+                cachePath: this.updateCachePath,
+                bypassCache: checkOnly,
+            });
+            current = result.current;
+            latest = result.latest;
+        }
+        catch (err) {
+            return { text: `❌ 版本检查失败: ${err.message}` };
+        }
+        if (!this.updateFns.isNewer(current, latest)) {
+            return { text: `✅ 已是最新版本 ${current}` };
+        }
+        if (checkOnly) {
+            return { text: `📦 有新版本 ${latest} 可用（当前 ${current}），发送 /update 升级` };
+        }
+        // 2. Dev mode guard
+        if (this.devMode) {
+            return { text: '⚠️ 开发模式不支持自更新，请 git pull 后重新构建' };
+        }
+        // 3. Install (send intermediate status before the blocking operation)
+        await this.bridge.sendResult({ text: `⬆️ 正在升级 ${current} → ${latest} ...` }, ctx);
+        const installResult = await this.updateFns.runInstallLatest();
+        if (!installResult.success) {
+            return { text: `❌ 升级失败: ${installResult.error}` };
+        }
+        // 4. Restart (reuse /restart's restartSpawner + pendingExit)
+        if (!this.restartSpawner) {
+            return { text: `✅ 已升级到 ${latest}，请手动 /restart 重启 bridge` };
+        }
+        try {
+            const pid = this.restartSpawner();
+            this.pendingExit = true;
+            return { text: `✅ 升级成功 (${current} → ${latest})，正在重启（新进程 pid ${pid}）…` };
+        }
+        catch (err) {
+            getLogger().error('[router] update restart spawn failed:', err);
+            return {
+                text: `✅ 已升级到 ${latest}，但重启失败：${err.message}，请手动 /restart`,
+            };
+        }
+    }
     cmdNew(ctx) {
         // 只清 sessionId 保留 cwd — 否则 /new 之后 /resume 会提示"请先 /cd
         // 设置工作目录"，但用户的 workspace 还在。2026-06-21 复盘：用户
@@ -1840,6 +1900,136 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
         };
         return { card };
     }
+    /**
+     * Build card for config.save agent switch.
+     * When the new agent has a restored session, renders a Resume card (mirrors
+     * buildAutoResumeCard) with session history + stop/new buttons.
+     * When the session was cleared, renders a compact notice card instead.
+     */
+    buildConfigSwitchCard(switchResult, ctx) {
+        const newAgent = switchResult.newAgent;
+        const agentName = agentDisplayName(newAgent);
+        const cwd = this.sessionStore.getCwd(ctx.userId);
+        const sessionId = switchResult.sessionId;
+        // No cwd or no session → compact notice card
+        if (!cwd || !sessionId) {
+            const elements = [markdownDiv(switchResult.notice)];
+            // New session button
+            elements.push({
+                tag: 'column_set',
+                columns: [
+                    {
+                        tag: 'column',
+                        width: 'auto',
+                        elements: [newSessionButton()],
+                    },
+                ],
+            });
+            return {
+                card: {
+                    schema: '2.0',
+                    config: { wide_screen_mode: true },
+                    header: {
+                        title: { tag: 'plain_text', content: `🔀 切换到 ${agentName}` },
+                    },
+                    body: { elements },
+                },
+            };
+        }
+        // Has session → Resume card (mirrors buildAutoResumeCard)
+        // Guard: if the session reader for the new agent is not available (e.g. agent
+        // not registered), fall back to compact notice card to avoid NPE.
+        const readerForNewAgent = newAgent === this.config.defaultAgent
+            ? this.sessionReader
+            : this.sessionReaderRegistry.get(newAgent);
+        if (!readerForNewAgent) {
+            // Fallback: compact notice card with the notice text
+            const elements = [markdownDiv(switchResult.notice)];
+            elements.push({
+                tag: 'column_set',
+                columns: [
+                    {
+                        tag: 'column',
+                        width: 'auto',
+                        elements: [newSessionButton()],
+                    },
+                ],
+            });
+            return {
+                card: {
+                    schema: '2.0',
+                    config: { wide_screen_mode: true },
+                    header: { title: { tag: 'plain_text', content: `🔀 切换到 ${agentName}` } },
+                    body: { elements },
+                },
+            };
+        }
+        const { events: content, usage, isActive, aiTitle, recap, displayTitle, activeRunRunId, } = this.readSessionDisplayState(sessionId, cwd, {
+            agentKind: newAgent,
+            maxEvents: AUTO_RESUME_MAX_EVENTS,
+        });
+        let header = `📂 \`${cwd}\`\n已恢复会话: **${sessionId}**`;
+        const sections = [];
+        if (displayTitle) {
+            const label = aiTitle ? 'AI 标题' : '最近输入';
+            sections.push(`🏷️ **${label}**\n${displayTitle}`);
+        }
+        if (recap) {
+            const recapPreview = recap.length > 200 ? recap.slice(0, 197) + '...' : recap;
+            sections.push(`📝 **Recap**\n${recapPreview}`);
+        }
+        if (sections.length > 0) {
+            header += '\n\n' + sections.join('\n\n──\n\n');
+        }
+        const elements = [markdownDiv(header), { tag: 'hr' }];
+        if (content.length === 0) {
+            elements.push(markdownDiv('_该会话暂无新消息可显示（最后一条为用户输入）_'));
+        }
+        else {
+            content.forEach((ev, i) => {
+                elements.push(sessionEventPanel(ev, i, content.length, 2, newAgent));
+            });
+        }
+        if (usage) {
+            const usageStr = formatUsageStats(usage, { showResult: true, result: 'success' });
+            elements.push(markdownDiv(usageStr));
+        }
+        if (elements.length > 0 && elements[elements.length - 1].tag === 'hr') {
+            elements.pop();
+        }
+        // Action buttons
+        const actions = [];
+        if (isActive) {
+            actions.push({
+                tag: 'button',
+                text: { tag: 'plain_text', content: '⏹ 终止' },
+                type: 'danger',
+                behaviors: [{ type: 'callback', value: { cmd: 'stop', runId: activeRunRunId, cwd } }],
+            });
+        }
+        actions.push(newSessionButton());
+        elements.push({
+            tag: 'column_set',
+            columns: actions.map((btn) => ({
+                tag: 'column',
+                width: 'auto',
+                elements: [btn],
+            })),
+        });
+        return {
+            card: {
+                schema: '2.0',
+                config: { wide_screen_mode: true },
+                header: {
+                    title: {
+                        tag: 'plain_text',
+                        content: `${isActive ? '⏳ 切换 Agent（完成中）' : '🔀 切换 Agent'} · ${agentName}`,
+                    },
+                },
+                body: { elements },
+            },
+        };
+    }
     static LS_PAGE_SIZE = 30;
     cmdLs(args, ctx, offset = 0) {
         const cwd = this.sessionStore.getCwd(ctx.userId);
@@ -2906,8 +3096,14 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                 // clearRunners / syncAgentChoices / defaultAgent 切换）。key 经 mapAgentKey
                 // 归一化，pi./codex./opencode./kimi. 命中 agents.* 判定；claude. 与
                 // defaultAgent 不再漏判。
-                this.propagateConfigSave(oldDefaultAgent, { [mapAgentKey(key)]: value }, ctx);
+                const switchResult = this.propagateConfigSave(oldDefaultAgent, { [mapAgentKey(key)]: value }, ctx);
                 this.pendingConfig = null; // 命令式写盘后清空暂存，避免不一致
+                // 2026-08-13: agent 切换时额外发送 Resume 卡片
+                if (switchResult.notice) {
+                    const switchCard = this.buildConfigSwitchCard(switchResult, ctx);
+                    // 文本路径返回 config card，Resume card 通过 bridge 异步发送
+                    void this.bridge.sendResult(switchCard, ctx);
+                }
                 const card = this.buildConfigCard();
                 if (discarded > 0 && card.card && typeof card.card === 'object') {
                     const body = card.card.body;
@@ -2942,9 +3138,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
         // Direct inline construction (not via ConfigField) so that text (display label)
         // and value (agentKind for config storage) can differ — uninstalled agents get
         // a "⚠️ (未安装)" suffix in the label while the value stays clean.
-        // Uninstalled agents sink to the bottom; installed ones keep registration
-        // order (claude → codex → pi → opencode → kimi).
-        const allAgents = sortAgentsByAvailability(listRegisteredAgents(), getCachedAvailability);
+        const allAgents = listRegisteredAgents();
         const agentOptions = allAgents.map((kind) => {
             const available = getCachedAvailability(kind);
             const label = available === false ? `${agentDisplayName(kind)} ⚠️ (未安装)` : agentDisplayName(kind);

package/dist/runner/codex/argv.d.ts

@@ -5,7 +5,7 @@
  * - `approval_policy="never"` eliminates the approval handshake (root cause ①).
  * - Prompt goes via stdin (`-` flag) to avoid argv escaping issues.
  * - `--skip-git-repo-check`: lark-remote's cwd may not be a git repo.
- * - User's `~/.codex/config.toml` and AGENTS.md/CLAUDE.md rules are preserved
+ * - User's `~/.codex/config.toml` and project rules are preserved
  *   (no `--ignore-user-config` / `--ignore-rules`).
  */
 interface BuildCodexExecArgsInput {

package/dist/runner/codex/argv.js

@@ -5,7 +5,7 @@
  * - `approval_policy="never"` eliminates the approval handshake (root cause ①).
  * - Prompt goes via stdin (`-` flag) to avoid argv escaping issues.
  * - `--skip-git-repo-check`: lark-remote's cwd may not be a git repo.
- * - User's `~/.codex/config.toml` and AGENTS.md/CLAUDE.md rules are preserved
+ * - User's `~/.codex/config.toml` and project rules are preserved
  *   (no `--ignore-user-config` / `--ignore-rules`).
  */
 /**

package/dist/runner/common/runner-utils.d.ts

@@ -11,6 +11,18 @@ export declare function pipeAllStdio(): ('ignore' | 'pipe')[];
  * rather than argv.
  */
 export declare function endStdinWithPrompt(proc: ChildProcess, message: string): void;
+/**
+ * Build a synthetic system.init event for pre-spawn failure paths.
+ *
+ * When the runner exits before spawning a process (validateBeforeRun failure,
+ * ENOENT spawn failure), no real system.init arrives from stdout. Without a
+ * synthetic init, the bridge's pre-init result guard (§9.22) and the run-state
+ * reducer's sessionId check would silently drop the error result, leaving the
+ * card showing "输出流已结束，但未收到 result 事件" instead of the actual
+ * error message. The synthetic init satisfies both guards so the real error
+ * result is processed normally.
+ */
+export declare function syntheticInitEvent(sessionId?: string): AgentEvent;
 /**
  * Build a standardized auth/error result event for yield.
  *

package/dist/runner/common/runner-utils.js

@@ -46,6 +46,27 @@ export function endStdinWithPrompt(proc, message) {
         }
     }
 }
+/**
+ * Build a synthetic system.init event for pre-spawn failure paths.
+ *
+ * When the runner exits before spawning a process (validateBeforeRun failure,
+ * ENOENT spawn failure), no real system.init arrives from stdout. Without a
+ * synthetic init, the bridge's pre-init result guard (§9.22) and the run-state
+ * reducer's sessionId check would silently drop the error result, leaving the
+ * card showing "输出流已结束，但未收到 result 事件" instead of the actual
+ * error message. The synthetic init satisfies both guards so the real error
+ * result is processed normally.
+ */
+export function syntheticInitEvent(sessionId = '') {
+    return {
+        type: 'system',
+        subtype: 'init',
+        session_id: sessionId,
+        cwd: '',
+        model: '',
+        timestamp: new Date().toISOString(),
+    };
+}
 /**
  * Build a standardized auth/error result event for yield.
  *

package/dist/runner/common/spawning-runner.js

@@ -6,7 +6,7 @@ import { getLogger } from '../../logger/index.js';
 import { ProcessStopper } from './process-stopper.js';
 import { SpawnHeartbeat } from './spawn-heartbeat.js';
 import { createJSONLStream } from './jsonl-stream.js';
-import { authErrorEvent } from './runner-utils.js';
+import { authErrorEvent, syntheticInitEvent } from './runner-utils.js';
 import { DEFAULT_STOP_GRACE_MS } from '../../config/index.js';
 /**
  * Magic-number constants (Clean Code P3-1, G25 Replace Magic Numbers with
@@ -255,6 +255,11 @@ export class SpawningRunner {
         // Pre-spawn validation hook (e.g. codex API key check)
         const validationError = this.validateBeforeRun(opts);
         if (validationError) {
+            // §9.22: yield synthetic init so the bridge's pre-init result guard and
+            // the run-state reducer's sessionId check don't silently drop the error
+            // result. Without init, the card would show a generic "输出流已结束"
+            // instead of the specific validation error message.
+            yield syntheticInitEvent(opts.sessionId);
             yield validationError;
             return;
         }
@@ -287,6 +292,9 @@ export class SpawningRunner {
             // so the user is not misdiagnosed into reinstalling the binary.
             const baseMsg = `${this.binary} 命令不可用（未找到或不可执行），请检查是否已安装或在 PATH 中`;
             const msg = spawnErr ? `${baseMsg}：${spawnErr.message}` : baseMsg;
+            // §9.22: yield synthetic init before the error result so bridge/run-state
+            // guards don't silently drop it (same rationale as validateBeforeRun).
+            yield syntheticInitEvent(opts.sessionId);
             yield authErrorEvent(msg);
             return;
         }

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

@@ -0,0 +1,93 @@
+import { type ContentBlockMapping } from '../common/content-blocks.js';
+export interface SessionIndexEntry {
+    sessionId: string;
+    path: string;
+    fingerprint: string;
+    mtimeMs: number;
+    summary: string;
+    cwdSet: Set<string>;
+}
+export interface SessionIndexOptions {
+    /** Minimum interval between refresh scans (ms). Default 5000. */
+    refreshIntervalMs?: number;
+}
+/** Claude-specific field-name mapping for content block extraction. */
+export declare const CLAUDE_MAPPING: ContentBlockMapping;
+/**
+ * Detect Claude CLI sub-agent completion notification text.
+ * Claude CLI injects a `type:"user"` record with string content starting
+ * with `<task-notification>` when a sub-agent (Agent tool) finishes.
+ * These must be excluded from displayTitle/summary — they are machine
+ * injections, not real user input. Primary criterion: extracted text
+ * starts with `<task-notification` (works for both string and array
+ * content since `extractText` is called first). Secondary (optional):
+ * `origin.kind === 'task-notification'` (not all CLI versions write it).
+ */
+export declare function isTaskNotificationText(text: string): boolean;
+/**
+ * Extract first text from a user message.
+ * Used by parseSessionJsonl and sessions.ts readSessionContent.
+ */
+export declare function extractText(content: unknown): string | null;
+export interface ParsedSession {
+    cwdSet: Set<string>;
+    summary: string;
+}
+/**
+ * Unified parser: single streaming scan of a JSONL file producing both
+ * the complete set of cwd values AND the first real user message summary.
+ * Replaces the split readCwdFromJsonl (first-cwd) + jsonlContainsCwd (any-cwd).
+ */
+export declare function parseSessionJsonl(filePath: string): ParsedSession;
+/**
+ * Build a fingerprint string from file stat metadata.
+ * Uses `size + mtimeNs + ctimeNs + dev + ino` (bigint stat).
+ * `size`/`mtime` are required; the rest are best-effort.
+ */
+export declare function buildFingerprint(filePath: string): string;
+/**
+ * In-memory session index with three query views:
+ *   byPath:      path → entry
+ *   bySessionId: sessionId → Set<path>
+ *   byCwd:       cwd → Set<path>
+ *
+ * Build once, refresh on demand (throttled). Single-file parse failure
+ * doesn't affect other files; readdir failure preserves old index.
+ */
+export declare class SessionIndex {
+    private readonly projectsDir;
+    private readonly refreshIntervalMs;
+    private readonly byPath;
+    private readonly bySessionId;
+    private readonly byCwd;
+    private lastRefreshAt;
+    private built;
+    /** Test-only: count of parseSessionJsonl calls since creation */
+    parseCount: number;
+    /** Test-only: count of directory scan operations */
+    scanCount: number;
+    constructor(projectsDir: string, opts?: SessionIndexOptions);
+    /** Whether a full scan has ever completed successfully (readdir succeeded). */
+    get isBuilt(): boolean;
+    build(): void;
+    refresh(): void;
+    listByCwd(cwd: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): SessionIndexEntry[];
+    /**
+     * Find a session entry by sessionId and cwd.
+     * Re-stats the file to verify fingerprint before returning (拍板 3):
+     *   - fingerprint unchanged → trust index cwdSet
+     *   - fingerprint changed → re-parse that one file, update index, re-check
+     * Returns undefined if not found or cwd doesn't match.
+     *
+     * Note: we re-stat ALL paths for the sessionId regardless of the old cwdSet,
+     * because a fingerprint change may have added the target cwd to the set.
+     */
+    findBySessionIdAndCwd(sessionId: string, cwd: string): SessionIndexEntry | undefined;
+    private fullScan;
+    private updateEntry;
+    private removeEntry;
+    private removeCrossRefs;
+}