@baique/pi-web-sky 0.1.59 → 0.1.61

package/.next/trace-build

@@ -1 +1 @@
-[{"name":"run-webpack","duration":11699804,"timestamp":191292283381,"id":14,"parentId":1,"tags":{},"startTime":1789900102827,"traceId":"cdfc6ca0ef3552f1"},{"name":"run-typescript","duration":5589684,"timestamp":191303984913,"id":809,"parentId":1,"tags":{},"startTime":1789900114529,"traceId":"cdfc6ca0ef3552f1"},{"name":"static-check","duration":2676964,"timestamp":191309588298,"id":812,"parentId":1,"tags":{},"startTime":1789900120132,"traceId":"cdfc6ca0ef3552f1"},{"name":"static-generation","duration":4034028,"timestamp":191312459363,"id":968,"parentId":1,"tags":{},"startTime":1789900123003,"traceId":"cdfc6ca0ef3552f1"},{"name":"collect-build-traces","duration":28313982,"timestamp":191312267468,"id":965,"parentId":1,"tags":{},"startTime":1789900122811,"traceId":"cdfc6ca0ef3552f1"},{"name":"telemetry-flush","duration":34,"timestamp":191340584252,"id":977,"parentId":1,"tags":{},"startTime":1789900151127,"traceId":"cdfc6ca0ef3552f1"},{"name":"next-build","duration":48482632,"timestamp":191292101660,"id":1,"tags":{"buildMode":"default","version":"16.3.1","bundler":"webpack","has-custom-webpack-config":"false","use-build-worker":"true"},"startTime":1789900102646,"traceId":"cdfc6ca0ef3552f1"}]
+[{"name":"run-webpack","duration":14533465,"timestamp":272072983657,"id":14,"parentId":1,"tags":{},"startTime":1790237349471,"traceId":"80188c259035d77e"},{"name":"run-typescript","duration":13931446,"timestamp":272087518906,"id":824,"parentId":1,"tags":{},"startTime":1790237364006,"traceId":"80188c259035d77e"},{"name":"static-check","duration":3363686,"timestamp":272101465709,"id":827,"parentId":1,"tags":{},"startTime":1790237377953,"traceId":"80188c259035d77e"},{"name":"static-generation","duration":4133250,"timestamp":272105054082,"id":983,"parentId":1,"tags":{},"startTime":1790237381541,"traceId":"80188c259035d77e"},{"name":"collect-build-traces","duration":30667433,"timestamp":272104831548,"id":980,"parentId":1,"tags":{},"startTime":1790237381319,"traceId":"80188c259035d77e"},{"name":"telemetry-flush","duration":38,"timestamp":272135501894,"id":992,"parentId":1,"tags":{},"startTime":1790237411989,"traceId":"80188c259035d77e"},{"name":"next-build","duration":62752361,"timestamp":272072749578,"id":1,"tags":{"buildMode":"default","version":"16.3.1","bundler":"webpack","has-custom-webpack-config":"false","use-build-worker":"true"},"startTime":1790237349237,"traceId":"80188c259035d77e"}]

package/lib/board-types.ts

@@ -40,6 +40,12 @@ export interface RunningSnapshot {
    * 带 ?boardId=&cardIds=：返回这批可见卡的**全量**状态（含 failed/done/not_started），供画布徽章用。
    */
   taskCards: TaskCardRunningState[];
+  /**
+   * 会话列表代次（服务端任何影响列表的写入都自增）。
+   * 前端比对代次：变了就重拉列表——标题/首条消息/最后回复/外部新建会话不必等
+   * 下次本地动作或刷新页面。见 lib/session-list-signal.ts。
+   */
+  listGeneration: number;
 }
 
 /** 任务卡状态（running 快照透传的画布可见卡状态；DB 是唯一真相源，此为展示镜像） */

package/lib/rpc-manager.title.test.mjs

@@ -150,3 +150,131 @@ test("空名字仍然报错（既有校验不变），不碰 pi 也不碰库", a
   assert.deepEqual(nameCalls, []);
   assert.equal(rowOf(db, "sess-name").title, null);
 });
+
+/** 假 inner：prompt 提交的接受/拒绝由调用方控制（SDK 通过 preflightResult 同步 ack）。
+ *  `entries` 模拟 transcript 已有内容（判定「是不是真首条」靠它）。 */
+function makePromptWrapper(sessionId, { preflight = "accept", entries = [] } = {}) {
+  const inner = {
+    sessionId,
+    isBashRunning: false,
+    isStreaming: false,
+    isCompacting: false,
+    extensionRunner: {},
+    sessionManager: { getCwd: () => "/tmp", getEntries: () => entries },
+    agent: { state: {} },
+    subscribe() {
+      return () => {};
+    },
+    dispose() {},
+    prompt(_message, options) {
+      if (preflight === "reject") return Promise.reject(new Error("prompt rejected"));
+      options.preflightResult(true);
+      return Promise.resolve();
+    },
+  };
+  const wrapper = new AgentSessionWrapper(inner);
+  wrapper.start();
+  return wrapper;
+}
+
+test("首条用户消息在 prompt 被接受时即落库：标题不必等整轮跑完", async (t) => {
+  const db = freshDb();
+  seedSession(db, "sess-title");
+  const wrapper = makePromptWrapper("sess-title");
+  t.after(() => wrapper.destroy());
+  const generationBefore = globalThis.__piSessionListGeneration ?? 0;
+
+  await wrapper.send({ type: "prompt", message: "  会话标题为什么不及时  " });
+
+  assert.equal(rowOf(db, "sess-title").first_message, "会话标题为什么不及时", "trim 后入库");
+  assert.ok(
+    (globalThis.__piSessionListGeneration ?? 0) > generationBefore,
+    "同一次写库推列表代次：正在看侧栏的客户端 ≤2.5s 内重拉，标题立刻可见",
+  );
+});
+
+test("首条用户消息截断到 300 字符（与扫描器同一上限）", async (t) => {
+  const db = freshDb();
+  seedSession(db, "sess-title");
+  const wrapper = makePromptWrapper("sess-title");
+  t.after(() => wrapper.destroy());
+
+  await wrapper.send({ type: "prompt", message: "长".repeat(500) });
+
+  assert.equal(rowOf(db, "sess-title").first_message.length, 300);
+});
+
+test("prompt 没被接受（preflight 拒绝）：不写 first_message", async (t) => {
+  const db = freshDb();
+  seedSession(db, "sess-title");
+  const wrapper = makePromptWrapper("sess-title", { preflight: "reject" });
+  t.after(() => wrapper.destroy());
+
+  await assert.rejects(() => wrapper.send({ type: "prompt", message: "会被拒绝的提交" }), /prompt rejected/);
+  assert.equal(rowOf(db, "sess-title").first_message, null);
+});
+
+test("prompt 分支接线：await preflight 之后才写 first_message（拒绝的提交不留标题）", async () => {
+  const source = await readFile(new URL("./rpc-manager.ts", import.meta.url), "utf8");
+  const caseSource = caseSourceOf(source, "prompt");
+
+  assert.match(caseSource, /await preflight;[\s\S]*?fillFirstMessageIfEmpty\(/);
+  assert.match(caseSource, /command\.message[\s\S]*?slice\(0, FIRST_MESSAGE_PREVIEW_LENGTH\)/);
+  assert.match(caseSource, /try \{[\s\S]*?fillFirstMessageIfEmpty\([\s\S]*?catch \(error\)/, "库写失败不得冒泡（否则路由把已接受的 prompt 报成 prompt_rejected）");
+});
+
+test("transcript 里已有用户消息（老会话）：prompt 不写 first_message（不把最新消息写成首条）", async (t) => {
+  const db = freshDb();
+  seedSession(db, "sess-title");
+  // 模拟 CLI 建的老会话：transcript 有历史，但 first_message 还空着（扫描器拿不到）
+  const wrapper = makePromptWrapper("sess-title", {
+    entries: [{ type: "message", message: { role: "user", content: [{ type: "text", text: "历史里的真首条消息" }] } }],
+  });
+  t.after(() => wrapper.destroy());
+  const generationBefore = globalThis.__piSessionListGeneration ?? 0;
+
+  await wrapper.send({ type: "prompt", message: "这是这条会话里最新的一句" });
+
+  assert.equal(rowOf(db, "sess-title").first_message, null, "留给 agent_settled/扫描器按真首条回填");
+  assert.equal(globalThis.__piSessionListGeneration ?? 0, generationBefore, "没写库就不推代次");
+});
+
+test("空的 message（图片-only 等）：不写库、不推代次", async (t) => {
+  const db = freshDb();
+  seedSession(db, "sess-title");
+  const wrapper = makePromptWrapper("sess-title");
+  t.after(() => wrapper.destroy());
+  const generationBefore = globalThis.__piSessionListGeneration ?? 0;
+
+  await wrapper.send({ type: "prompt", message: "   ", images: [] });
+
+  assert.equal(rowOf(db, "sess-title").first_message, null);
+  assert.equal(globalThis.__piSessionListGeneration ?? 0, generationBefore);
+});
+
+test("写库失败不拖累 send：命令照常成功响应（库是旁路索引）", async (t) => {
+  const db = freshDb();
+  seedSession(db, "sess-title");
+  const wrapper = makePromptWrapper("sess-title");
+  const errors = [];
+  const original = console.error;
+  t.after(() => {
+    wrapper.destroy();
+    console.error = original;
+    globalThis.__piWebDb = db;
+  });
+  console.error = (...args) => errors.push(args.map(String).join(" "));
+  // 让库写入抛错：stub 掉全局库句柄（真库仍在 db 变量里，未被触碰）
+  globalThis.__piWebDb = {
+    prepare() {
+      throw new Error("database is locked");
+    },
+  };
+
+  const result = await wrapper.send({ type: "prompt", message: "阻塞的库也不能让 prompt 变失败" });
+
+  assert.equal(result, null, "send 正常返回：路由才会写 promptAccepted=true（否则客户端回填草稿、诱导重发）");
+  assert.equal(errors.length, 1, "写库失败必须可见");
+  assert.match(errors[0], /\[pi-web\] 首条消息写库失败/);
+  assert.match(errors[0], /database is locked/);
+});

package/lib/rpc-manager.ts

@@ -333,6 +333,8 @@ export class AgentSessionWrapper {
     }
     recordSessionOutcome(sessionId, effect);
     // 首条用户消息此刻已在内存 entries 里（不读文件，读取路径零扫盘）。
+    // 正常链路上它更早就写好了（prompt 一被接受就写，见 send 的 prompt 分支）；
+    // 这里兑底扩展/外部注入的首条用户消息（那一轮的起点不是 RPC prompt）。
     fillFirstMessageIfEmpty(sessionId, firstUserMessageOf(this.inner.sessionManager.getEntries()));
   }
 
@@ -613,6 +615,29 @@ export class AgentSessionWrapper {
           });
 
           await preflight;
+          // 首条用户消息：prompt 一被接受就落库，**不等整轮跑完**。标题/列表的默认
+          // 展示就是「用户发送的第一句话」（title || first_message），只在 agent_settled
+          // 写的话，长首轮（几分钟~几十分钟）期间刷新页面/换客户端/看板卡上标题一直空着
+          // （-> "(no messages)"）。也不能指望 agent_start：实测那一刻用户消息还没进
+          // 内存 entries（拿不到文本）。
+          // 只在「transcript 里还没有用户消息」时写（= 这才是真首条）：已有历史的会话
+          // （CLI 建的、first_message 还空着）走 agent_settled/扫描器按真实首条回填，
+          // prompt 路径写「这一条最新消息」会被 fill-empty 钉死成永久错值。
+          const promptText = typeof command.message === "string" ? command.message.trim() : "";
+          const sessionId = this.inner.sessionId;
+          if (promptText && sessionId && !firstUserMessageOf(this.inner.sessionManager.getEntries())) {
+            try {
+              fillFirstMessageIfEmpty(sessionId, promptText.slice(0, FIRST_MESSAGE_PREVIEW_LENGTH));
+            } catch (error) {
+              // 库写失败绝不能冒泡：send() 抛出会让路由把「已经接受的 prompt」报成
+              // prompt_rejected（客户端回填草稿、诱导重发，而 agent 其实在跑）。
+              // 这条写只是旁路索引，失败记账即可（同 persistSessionActivity 口径）。
+              console.error(
+                `[pi-web] 首条消息写库失败 session=${sessionId}:`,
+                error instanceof Error ? error.message : String(error),
+              );
+            }
+          }
           return null;
         } finally {
           releaseAdmission();

package/lib/session-index-scanner.test.mjs

@@ -69,6 +69,31 @@ test("runSessionIndexScan：幂等（重复扫描不重复建行）", async () =
   }
 });
 
+test("runSessionIndexScan：列表代次只在本轮真变更时自增（有变更推一次，空轮不推）", async () => {
+  freshDb();
+  const { root, projDir } = makeRoot();
+  try {
+    const generation = () => globalThis.__piSessionListGeneration ?? 0;
+    const before = generation();
+
+    await runSessionIndexScan(root); // 磁盘空：无变更
+    assert.equal(generation(), before, "空轮不推代次（否则每 30s 白刷一次前端列表）");
+
+    writeFileSync(join(projDir, "2026-01-01T00-00-00-000Z_aaa.jsonl"), sessionFileLines("aaa", "/home/u/project/alpha"));
+    await runSessionIndexScan(root);
+    assert.equal(generation(), before + 1, "外部/CLI 新建的会话入索引 → 推一次（侧栏 ≤2.5s 就能看到它）");
+
+    const afterInsert = generation();
+    await runSessionIndexScan(root); // 再扫：幂等无变更
+    assert.equal(generation(), afterInsert, "幂等轮不推");
+
+    await indexSessionFileNow(join(projDir, "2026-01-01T00-00-00-000Z_aaa.jsonl"), null, null);
+    assert.equal(generation(), afterInsert + 1, "单文件立即索引 → 也推一次（fork/引用分支当场进列表）");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
 test("runSessionIndexScan：mtime 变化刷 modified + 回填 first_message（文件是内容事实源）", async () => {
   freshDb();
   const { root, projDir } = makeRoot();

package/lib/session-index-scanner.ts

@@ -34,6 +34,7 @@ import { getDb } from "./sqlite-db";
 import { projectIdentityKey } from "./project-identity";
 import { sessionPathKey } from "./session-path";
 import { scanOneSessionHead, scanSessionFileMeta, readSessionTail, type SessionFileMeta } from "./session-scanner";
+import { markSessionListChanged } from "./session-list-signal";
 import { resolveProject } from "./worktree";
 
 /** 一轮扫描的变更摘要（日志/测试断言用）。 */
@@ -97,6 +98,8 @@ export async function indexSessionFileNow(
       head.created.getTime(),
       Date.now(),
     );
+  // 行已落库 → 列表可能变了（会话当场出现在列表/派生列被补上）。
+  markSessionListChanged();
 }
 
 /** 一轮全量扫描。`sessionsDir` 仅在测试注入（默认走 agentDir）。 */
@@ -319,6 +322,12 @@ export async function runSessionIndexScan(
     }
   }
 
+  // 本轮真改了什么 → 通知列表读者（外部/CLI 新建的会话、首条消息/最后回复回填、
+  // 删除都走这里；无变更不 mark，避免每 30s 空推一次前端重拉）。
+  if (summary.inserted > 0 || summary.updated > 0 || summary.deleted > 0) {
+    markSessionListChanged();
+  }
+
   return summary;
 }
 

package/lib/session-list-signal.test.mjs

@@ -0,0 +1,50 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import test from "node:test";
+import { createJiti } from "jiti";
+
+const jiti = createJiti(import.meta.url, { interopDefault: true, moduleCache: false });
+const { markSessionListChanged, getSessionListGeneration } = await jiti.import("./session-list-signal.ts");
+
+const routeSource = await readFile(new URL("../app/api/agent/running/route.ts", import.meta.url), "utf8");
+const sidebarSource = await readFile(new URL("../components/SessionSidebar.tsx", import.meta.url), "utf8");
+const readerSource = await readFile(new URL("./session-reader.ts", import.meta.url), "utf8");
+const sessionsRouteSource = await readFile(new URL("../app/api/sessions/route.ts", import.meta.url), "utf8");
+
+test("mark 自增代次，get 读同一处（globalThis：热重载后仍是同一个计数器）", () => {
+  const before = getSessionListGeneration();
+  markSessionListChanged();
+  markSessionListChanged();
+  assert.equal(getSessionListGeneration(), before + 2);
+  assert.equal(globalThis.__piSessionListGeneration, before + 2);
+});
+
+test("接线：写路径 invalidateSessionListCache 委托 mark（改名/pin/新建/事件写库都算列表变更）", () => {
+  assert.match(
+    readerSource,
+    /export function invalidateSessionListCache\(\): void \{\n  markSessionListChanged\(\);/,
+  );
+  assert.match(readerSource, /from "\.\/session-list-signal"/);
+});
+
+test("接线：running 快照把代次带给前端（侧栏本来就在轮询它，不新增请求）", () => {
+  assert.match(routeSource, /listGeneration: getSessionListGeneration\(\)/);
+  assert.match(routeSource, /from "@\/lib\/session-list-signal"/);
+});
+
+test("接线：侧栏轮询见代次变化就全量刷新；首个快照只做种子（挂载时已拉过列表，不空刷）", () => {
+  assert.match(
+    sidebarSource,
+    /if \(shouldRefreshForListGeneration\(listGenerationRef\.current, generation\)\) \{\n\s+onRefreshRef\.current\?\.\(\);/,
+  );
+  // 列表响应把自己的代次记下来（不靠轮询的「首个快照」去猜）。
+  assert.match(sidebarSource, /if \(typeof data\.listGeneration === "number"\) listGenerationRef\.current = data\.listGeneration;/);
+});
+
+test("接线：/api/sessions 两份列表响应都带上自己的代次（作为「我的列表对应哪个代次」的种子）", () => {
+  assert.match(sessionsRouteSource, /sessions: \[\.\.\.persisted, \.\.\.extraRuntime\],[\s\S]*?listGeneration: getSessionListGeneration\(\),/);
+  assert.match(
+    sessionsRouteSource,
+    /\{ sessions, runningSessionIds: getRunningRpcSessionIds\(\), listGeneration: getSessionListGeneration\(\) \}/,
+  );
+});

package/lib/session-list-signal.ts

@@ -0,0 +1,32 @@
+// ============================================================================
+// 会话列表「已变更」信号
+//
+// 谁需要知道：列表不再有服务端缓存（每次读取 = 一次单表查询），但**前端**的列表
+// 只在挂载/项目切换/本地动作（新建、删除、改名、拖拽）时重拉——服务端写进去的
+// 新标题、首条消息、最后回复、外部（CLI）新建的会话，都要等下一次重拉才现身。
+//
+// 机制：任何影响列表读取的写路径都 mark 一次（自增计数器），`/api/agent/running`
+// 的轮询把它带给前端（侧栏本来就每 2.5s 拉一次），前端见变化就重拉列表。
+//
+// **进程内计数器**（与库同进程的写入才可见）：同时跑多个 pi-web 实例、共用一个
+// `pi-web.db` 时，A 进程的写不会推给 B 进程的侧栏——B 只能靠自己的 30s 扫描器按
+// 文件 mtime 收敛。跨进程唯一可靠的事实源是库本身（真要做就是库里的代次行）。
+//
+// 单独成文件只为打断循环依赖：`session-reader` 已经 import 扫描器（ensureSessionIndexReady），
+// 扫描器不能再反向 import `session-reader` 的 invalidateSessionListCache。globalThis
+// 存活热重载（模块级变量不会）。
+// ============================================================================
+
+declare global {
+  var __piSessionListGeneration: number | undefined;
+}
+
+/** 列表内容已变（标题/首条消息/最后回复/排序/新建/删除）。写路径调用，幂等无副作用。 */
+export function markSessionListChanged(): void {
+  globalThis.__piSessionListGeneration = (globalThis.__piSessionListGeneration ?? 0) + 1;
+}
+
+/** 当前代次：前端比对「我上次看到的」与「这次拿到的」，不等即重拉列表。 */
+export function getSessionListGeneration(): number {
+  return globalThis.__piSessionListGeneration ?? 0;
+}

package/lib/session-reader.ts

@@ -16,6 +16,7 @@ import { projectIdentityKey } from "./project-identity";
 import { sessionPathKey } from "./session-path";
 import { resolveProject, type ProjectInfo } from "./worktree";
 import { scanOneSessionFile } from "./session-scanner";
+import { markSessionListChanged } from "./session-list-signal";
 import { ensureSessionIndexReady } from "./session-index-scanner";
 import type { TurnIndexItem } from "./api-types";
 
@@ -264,17 +265,15 @@ export async function loadTaskSessionsPage(
 declare global {
   var __piSessionPathCache: Map<string, string> | undefined;
   var __piPathToSessionIdCache: Map<string, string> | undefined;
-  var __piSessionListGeneration: number | undefined;
 }
 
 /** 写路径的「数据变了」信号：归属/pin/改名/新建/删除/事件都会调它。
  *
- *  列表已无缓存（读取 = 每次一次单表查询），所以目前**没有生产读者**：这里只保留
- *  generation 自增的既有行为（T1–T4b 的写路径与 auto-name / patch-write-failure 的
- *  断言都依赖调用本身）。若要连函数一起删，需要同时改掉全部调用方与那两处断言——
- *  属待清理项，本次不动。 */
+ *  计数器本体在 `session-list-signal`（扫描器也要 mark，不能反向 import 本模块）；
+ *  读者是 `/api/agent/running` 的 `listGeneration` —— 侧栏 2.5s 轮询见代次变化就
+ *  重拉列表，标题/首条消息/最后回复/外部新建会话因此能在几秒内现身。 */
 export function invalidateSessionListCache(): void {
-  globalThis.__piSessionListGeneration = (globalThis.__piSessionListGeneration ?? 0) + 1;
+  markSessionListChanged();
 }
 
 function getPathCache(): Map<string, string> {

package/lib/task-store.ts

@@ -613,14 +613,16 @@ export function recordSessionOutcome(sessionId: string, outcome: { lastReply: st
   invalidateSessionListCache();
 }
 
-/** 首条用户消息回填（读取路径不再读文件，改由事件补齐；只补空行）。 */
+/** 首条用户消息回填（读取路径不再读文件，改由事件补齐；只补空行）。
+ *  只在真的改了行时推列表代次：这个函数在一条会话的一生里会被调多次（每次 prompt 一次），
+ *  无变化的空推会让前端白刷一轮会话/任务/看板。「空轮不推」与扫描器同一口径。 */
 export function fillFirstMessageIfEmpty(sessionId: string, firstMessage: string): void {
   const text = firstMessage.trim();
   if (!text) return;
-  getDb()
+  const result = getDb()
     .prepare(
       "UPDATE session_meta SET first_message = ? WHERE session_id = ? AND (first_message IS NULL OR first_message = '')",
     )
     .run(text, sessionId);
-  invalidateSessionListCache();
+  if (Number(result.changes) > 0) invalidateSessionListCache();
 }

package/lib/transcript.test.mjs

@@ -0,0 +1,186 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createJiti } from "jiti";
+
+const jiti = createJiti(import.meta.url);
+const {
+  createTranscriptState,
+  transcriptReducer,
+  transcriptMessages,
+  transcriptEntryIds,
+} = await jiti.import("./transcript.ts");
+
+/** 造一条用户消息（提交时客户端自己的形态）。 */
+const user = (text, timestamp) => ({ role: "user", content: [{ type: "text", text }], timestamp });
+const assistant = (text, timestamp) => ({ role: "assistant", content: [{ type: "text", text }], timestamp });
+const system = (text, timestamp) => ({ role: "system", content: text, timestamp });
+
+/** 服务端窗口里的一条 entry。 */
+const entry = (entryId, message, parentId = null) => ({ entryId, parentId, message });
+
+const reduce = (state, ...actions) => actions.reduce(transcriptReducer, state);
+
+test("提交把消息作为 pending 条目放进列表，并给出稳定的客户端 id", () => {
+  const state = reduce(
+    createTranscriptState(),
+    { type: "submit", id: "c1", message: user("你好", 100), runId: 1, submittedAt: 100 },
+  );
+  assert.equal(state.items.length, 1);
+  assert.deepEqual(
+    { id: state.items[0].id, state: state.items[0].state, serverEntryId: state.items[0].serverEntryId },
+    { id: "c1", state: "pending", serverEntryId: null },
+  );
+  assert.deepEqual(transcriptMessages(state).map((m) => m.role), ["user"]);
+});
+
+// 回归：当前实现里 message_end(user) 只有在"乐观气泡刚好还在末尾"时才认它；
+// 中间夹一条别的 message_end 就会改走追加分支 → 界面上两个一样的用户气泡。
+test("回声到达时原地升级，绝不新增条目（即使前面先夹了一条 system）", () => {
+  let state = reduce(
+    createTranscriptState(),
+    { type: "submit", id: "c1", message: user("重复测试", 100), runId: 1, submittedAt: 100 },
+  );
+  // pi 先推一条 system（历史上就是把乐观气泡挤出末尾的那条）
+  state = reduce(state, { type: "server", message: system("system prompt 更新", 101) });
+  // 紧接着才是这条用户消息的回声
+  state = reduce(state, { type: "echo", runId: 1, message: user("重复测试", 102) });
+
+  assert.equal(state.items.filter((i) => i.message.role === "user").length, 1, "用户消息必须只有一条");
+  assert.equal(state.items[0].id, "c1", "必须是同一条目（id 不变 → 渲染不重挂）");
+  assert.equal(state.items[0].state, "confirmed");
+  assert.equal(state.items[0].serverEntryId, null, "回声不带 entryId，等合并时补");
+});
+
+test("合并服务端整表：同一位置沿用原条目 id，不新增、不重挂", () => {
+  let state = reduce(
+    createTranscriptState(),
+    { type: "submit", id: "c1", message: user("合并测试", 100), runId: 1, submittedAt: 100 },
+    { type: "echo", runId: 1, message: user("合并测试", 102) },
+    { type: "server", message: assistant("收到", 110) },
+  );
+  const idsBefore = state.items.map((i) => i.id);
+
+  state = reduce(state, {
+    type: "mergeTail",
+    entries: [
+      entry("e1", user("更早的问题", 10)),
+      entry("e2", assistant("更早的回答", 20)),
+      entry("e3", user("合并测试", 102), "e2"),
+      entry("e4", assistant("收到", 110), "e3"),
+    ],
+  });
+
+  assert.equal(state.items.filter((i) => i.message.role === "user").length, 2, "用户消息两条：历史一条 + 本次一条");
+  // 已存在的条目沿用原 id（命中位置不重挂），更早的历史作为新条目补在前面
+  assert.deepEqual(state.items.map((i) => i.id).slice(-2), idsBefore, "已存在的条目 id 一个都不能变");
+  assert.deepEqual(transcriptEntryIds(state), ["e1", "e2", "e3", "e4"]);
+  assert.ok(state.items.every((i) => i.state === "confirmed"));
+});
+
+// 回归：当前实现里 loadSession 整表替换会把还没落盘的乐观气泡抹掉（"消息消失、AI 直接开始回复"）。
+test("确认前合并：服务端还没有这一条，pending 条目原位保留", () => {
+  let state = reduce(
+    createTranscriptState(),
+    { type: "submit", id: "c1", message: user("还没落盘", 100), runId: 1, submittedAt: 100 },
+  );
+  state = reduce(state, {
+    type: "mergeTail",
+    entries: [entry("e1", user("历史问题", 10)), entry("e2", assistant("历史回答", 20))],
+  });
+
+  assert.equal(state.items.filter((i) => i.message.role === "user").length, 2);
+  const pending = state.items.find((i) => i.id === "c1");
+  assert.equal(pending?.state, "pending", "未确认的条目必须还在");
+  assert.equal(state.items[state.items.length - 1].id, "c1", "pending 排在末尾");
+});
+
+test("合并时空窗口不清空列表（避免瞬态空响应把界面刷白）", () => {
+  let state = reduce(
+    createTranscriptState(),
+    { type: "mergeTail", entries: [entry("e1", user("已有", 10))] },
+  );
+  state = reduce(state, { type: "mergeTail", entries: [] });
+  assert.equal(state.items.length, 1);
+});
+
+test("同文本两条 steer：各自认领，不互相替换、不丢", () => {
+  let state = reduce(
+    createTranscriptState(),
+    { type: "submit", id: "c1", message: user("同样的话", 100), runId: 1, submittedAt: 100 },
+  );
+  state = reduce(
+    state,
+    { type: "echo", runId: 1, message: user("同样的话", 102) },
+    { type: "submit", id: "c2", message: user("同样的话", 200), runId: 1, submittedAt: 200 },
+    { type: "echo", runId: 1, message: user("同样的话", 202) },
+  );
+  assert.deepEqual(state.items.map((i) => i.id), ["c1", "c2"]);
+  assert.equal(state.items.filter((i) => i.message.role === "user").length, 2);
+});
+
+test("没有本地回显的服务端用户消息（别的客户端/扩展发的）作为新条目追加", () => {
+  const state = reduce(
+    createTranscriptState(),
+    { type: "echo", runId: 3, message: user("来自别处", 500) },
+  );
+  assert.equal(state.items.length, 1);
+  assert.equal(state.items[0].state, "confirmed");
+});
+
+test("提交被拒：按 id 移除 pending，别的条目不受影响", () => {
+  let state = reduce(
+    createTranscriptState(),
+    { type: "mergeTail", entries: [entry("e1", assistant("历史", 10))] },
+    { type: "submit", id: "c1", message: user("被拒的消息", 100), runId: 1, submittedAt: 100 },
+  );
+  state = reduce(state, { type: "fail", id: "c1" });
+  assert.deepEqual(state.items.map((i) => i.id), [state.items[0].id]);
+  assert.equal(state.items.length, 1);
+  assert.equal(transcriptMessages(state)[0].role, "assistant");
+});
+
+test("更早一页 prepend：重复 prepend 同一页只算一次", () => {
+  let state = reduce(
+    createTranscriptState(),
+    { type: "mergeTail", entries: [entry("e3", user("最新", 30))] },
+  );
+  const older = [entry("e1", user("最早", 10)), entry("e2", assistant("中间", 20))];
+  state = reduce(state, { type: "prependOlder", entries: older });
+  const once = state.items.map((i) => i.serverEntryId);
+  state = reduce(state, { type: "prependOlder", entries: older });
+  assert.deepEqual(state.items.map((i) => i.serverEntryId), once, "同一页重复加载不得重复插入");
+  assert.equal(state.items.length, 3);
+});
+
+// 回归：回退（navigate_tree）/「编辑从此处」会把 leaf 移到更早的 entry，服务端窗口随之变短。
+// 旧的 loadSession 是整表替换，落在窗口之外的条目会消失；合并实现里必须同样把它们判为"离开当前分支"丢弃，
+// 否则回退后旧消息仍然留在消息流里。
+test("回退到更早的 leaf：窗口之外的已落盘条目必须消失，pending 保留", () => {
+  const e1 = entry("e1", user("第一问", 10));
+  const e2 = entry("e2", assistant("第一答", 20), "e1");
+  const e3 = entry("e3", user("第二问", 30), "e2");
+  const e4 = entry("e4", assistant("第二答", 40), "e3");
+
+  let state = reduce(
+    createTranscriptState(),
+    { type: "mergeTail", entries: [e1, e2, e3, e4] },
+    { type: "submit", id: "c1", message: user("新提交还没落盘", 500), runId: 2, submittedAt: 500 },
+  );
+  assert.equal(state.items.length, 5);
+
+  // 回退到 e2：服务端窗口只到 e2
+  state = reduce(state, { type: "mergeTail", entries: [e1, e2] });
+
+  assert.deepEqual(transcriptEntryIds(state).filter(Boolean), ["e1", "e2"], "离分支的 e3/e4 必须移除");
+  assert.deepEqual(state.items.map((i) => i.id).filter((id) => id.startsWith("srv")), ["srv:e1", "srv:e2"]);
+  assert.deepEqual(state.items.filter((i) => i.state === "pending").map((i) => i.id), ["c1"], "未落盘的提交不能被顺手丢掉");
+});
+
+test("切分支 reset：显式清空（唯一允许清空列表的动作）", () => {
+  let state = reduce(
+    createTranscriptState(),
+    { type: "submit", id: "c1", message: user("旧分支", 100), runId: 1, submittedAt: 100 },
+  );
+  state = reduce(state, { type: "reset" });
+  assert.equal(state.items.length, 0);
+});