wave-code 1.5.0 → 1.6.0

package/src/stdio/agentBridge.ts

@@ -39,11 +39,12 @@ import {
   listAllSessions,
   readRecentWorkdirs,
   rememberRecentWorkdir,
+  forgetRecentWorkdir,
   setSessionCustomTitle,
+  readSessionWorkdir,
   searchFiles,
   generateRandomName,
   getDefaultRemoteBranch,
-  getMessageContent,
   PromptHistoryManager,
   AuthService,
   PluginCore,
@@ -75,6 +76,7 @@ import {
   revokeArtifact,
   searchArtifactMembers,
   type ArtifactShareMode,
+  type UserImage,
 } from "wave-agent-sdk";
 import {
   type ClientNotificationMethod,
@@ -87,14 +89,16 @@ import {
 } from "./protocol.js";
 import { execFileSync } from "node:child_process";
 import {
+  type Dirent,
   mkdirSync,
   existsSync,
   readFileSync,
   writeFileSync,
   readdirSync,
   realpathSync,
+  statSync,
 } from "node:fs";
-import { mkdir, open, readFile, writeFile } from "node:fs/promises";
+import { mkdir, open, readFile, stat, writeFile } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
 import { basename, dirname, extname, join } from "node:path";
 import {
@@ -102,6 +106,8 @@ import {
   deriveWorktreeInfo,
   getWorktreeChanges,
   removeWorktree,
+  worktreeCreationBranch,
+  type DerivedWorktree,
 } from "../utils/worktree.js";
 import { logger } from "../utils/logger.js";
 import {
@@ -115,9 +121,10 @@ import {
   remoteWire,
   toBackgroundTaskSummaries,
 } from "../remote/remoteNotifications.js";
-import { isUserCheckpointMessage } from "../utils/rewindCheckpoints.js";
 import { getWorkspaceDiff } from "../utils/workspaceDiff.js";
 import { installGitCredentialHelper } from "../utils/gitCredentialHelper.js";
+import { readImagePreview } from "../remote/imagePreview.js";
+import { readTextPreview } from "../remote/textPreview.js";
 import type { RemoteControlController } from "../remote/remoteControlService.js";
 import {
   hostSlashCommandsFor,
@@ -209,6 +216,20 @@ interface SessionEntry {
    * header when the session is re-attached from disk after a daemon restart.
    */
   createdWorkdir: string;
+  /**
+   * The branch the worktree in `createdWorkdir` was CREATED on
+   * (`worktree-<name>`), recorded once at initialize alongside it. Undefined
+   * when the session was not created in a linked git worktree.
+   *
+   * Removal needs this snapshot because the worktree itself stops being a
+   * record of it: `deriveWorktreeInfo` reads the worktree's HEAD, which an
+   * in-session `git checkout <other-branch>` moves to a branch that belongs to
+   * the user (and may hold commits reachable from nowhere else). Deleting that
+   * one is the bug this snapshot prevents, and it is unrecoverable once
+   * deleted — `git worktree list` has no memory of the original checkout
+   * either (it reports each worktree's current HEAD too).
+   */
+  createdWorktreeBranch?: string;
   /**
    * True while `updateConfig` is tearing the session's agent down and rebuilding
    * it from the updated config — the entry stays in the registry (so the session
@@ -241,8 +262,49 @@ interface SessionContext {
   registeredSessionId?: string;
 }
 
+/**
+ * Entries the file panel's directory tree never shows (spec
+ * desktop-file-panel.md「文件面板工作区目录树」scenario 3). A deny-list, not
+ * "hide dotfiles": `.github/`, `.env`, `.wave/` are content the user browses
+ * for. Only machine noise and VCS internals.
+ */
+const DIR_ENTRY_JUNK = new Set([
+  ".git",
+  ".svn",
+  ".hg",
+  ".DS_Store",
+  "Thumbs.db",
+  "desktop.ini",
+]);
+
+/** Per-level cap for the tree (scenario 3: the rest collapses into one row). */
+const DIR_ENTRY_MAX_PER_LEVEL = 200;
+
+/**
+ * Classify one directory entry as dir/file. Symlinks are followed so a linked
+ * directory stays browsable; an entry we cannot stat (dangling link, vanished
+ * between readdir and stat) returns null and is dropped — better a missing row
+ * than a row that fails on every click.
+ */
+function direntType(parentDir: string, dirent: Dirent): "dir" | "file" | null {
+  if (dirent.isDirectory()) return "dir";
+  if (dirent.isFile()) return "file";
+  if (!dirent.isSymbolicLink()) return null;
+  try {
+    return statSync(join(parentDir, dirent.name)).isDirectory()
+      ? "dir"
+      : "file";
+  } catch {
+    return null;
+  }
+}
+
 export class AgentBridge {
   private sessions = new Map<string, SessionEntry>();
+  /** 用户偏好写盘的串行队列（`updateUserSettings`）：stdio 请求是并发处理的，而写盘
+   * 是「同步读 → await 异步写」的读-改-写，两笔并发写会互相覆盖（丢键）。见该方法
+   * 的注释与 spec core/agent-config.md「设置页控件的保存时机」场景 9。 */
+  private userSettingsWriteQueue: Promise<unknown> = Promise.resolve();
   /** Pending approval requests, keyed by requestId. Stored with the resolve +
    * context so a re-attached client can list and respond to them (daemon mode:
    * approvals outlive any single connection). */
@@ -260,13 +322,13 @@ export class AgentBridge {
    * a keystroke pause, so a newer request makes the previous one worthless —
    * superseding it here is what keeps "one in-flight request per editor" true
    * even when the host cannot cancel (spec
-   * docs/specs/ui/code-completion.md: 同一时刻只允许一个补全请求在途).
+   * docs/specs/ide/code-completion.md: 同一时刻只允许一个补全请求在途).
    */
   private inFlightCompletions = new Map<string, AbortController>();
   /**
    * In-flight next-edit calls, same one-per-session rule and same reason as
    * completions. It also participates in the cross-capability exclusion from
-   * `docs/specs/ui/next-edit-suggestion.md`: completion and next-edit never hold
+   * `docs/specs/ide/next-edit-suggestion.md`: completion and next-edit never hold
    * an in-flight request at the same time, so one of them cannot answer into a
    * buffer the other has already rewritten.
    */
@@ -370,7 +432,7 @@ export class AgentBridge {
         return this.sendMessage(
           p as unknown as {
             text: string;
-            images?: Array<{ path: string; mimeType: string }>;
+            images?: UserImage[];
             force?: boolean;
           },
           sessionId,
@@ -393,7 +455,7 @@ export class AgentBridge {
         return this.updateQueuedMessage(
           p.id as string,
           p.text as string,
-          p.images as Array<{ path: string; mimeType: string }> | undefined,
+          p.images as UserImage[] | undefined,
           sessionId,
         );
       case "deleteQueuedMessageById":
@@ -401,10 +463,12 @@ export class AgentBridge {
       case "getMessages":
         return this.getMessages(sessionId, {
           since: p.since as string | undefined,
+          // 上翻取更早的锚点。漏了这一行，SDK 会退回「首屏」分支——每次都答
+          // 同一份内存尾部，页面永远接不上更早的页（真机上表现为上翻到底反复
+          // 要同一页、翻不动，压缩之前的历史一条都翻不出来）。
+          before: p.before as string | undefined,
           limit: p.limit as number | undefined,
         });
-      case "getFullMessageThread":
-        return this.getFullMessageThread(sessionId);
 
       // ── Remote control (daemon-level) ──
       // The daemon owns the outbound relay socket; the bridge only routes.
@@ -420,6 +484,19 @@ export class AgentBridge {
         return this.getPermissionMode(sessionId);
       case "getPlanFile":
         return this.getPlanFile(sessionId);
+      // 远控页按需取图（spec「点消息里的图片路径看原图」）：路径来自消息正文、
+      // 由用户在页面上点出来。会话在这里只用来确认调用方已经握手到某条活会话；
+      // 判型（按解码后的真实容器）与压到单帧预算内都在 `imagePreview.ts` 里做，
+      // 前台 CLI 那个宿主共用同一份实现。
+      case "getImagePreview":
+        this.requireSessionForRead(sessionId);
+        return readImagePreview(typeof p.path === "string" ? p.path : "");
+
+      case "getTextPreview":
+        // 点消息里的文件路径看内容（spec remote/remote-web.md「点消息里的文件
+        // 路径看内容」）：与取图同一条按需读取通道，判型换成「读出来是不是文本」。
+        this.requireSessionForRead(sessionId);
+        return readTextPreview(typeof p.path === "string" ? p.path : "");
 
       // ── MCP ──
       case "getMcpServers":
@@ -652,6 +729,8 @@ export class AgentBridge {
       // ── Filesystem / Git / worktree (global — no session required) ──
       case "listDirectories":
         return this.listDirectories(p.dir as string | undefined);
+      case "listDirectoryEntries":
+        return this.listDirectoryEntries(p.dir as string | undefined);
       // ── 最近打开的工作目录（spec core/recent-workdirs.md）──
       // 机器级、与会话无关：文件就在这台机器上，谁问就回谁的。桌面端按主机
       // 各问一次，远控 Web 页问它连着的那个进程。
@@ -660,6 +739,12 @@ export class AgentBridge {
       case "rememberRecentWorkdir":
         rememberRecentWorkdir(p.workdir as string);
         return null;
+      // 移除（桌面端最近目录项上的「从列表移除」）。页面没有这个入口，所以它
+      // 不在远控白名单里；桌面端移除时走自己的 stdio/隧道，落在这台机器上，
+      // 否则下一次 `getRecentWorkdirs` 会把条目带回来。
+      case "forgetRecentWorkdir":
+        forgetRecentWorkdir(p.workdir as string);
+        return null;
       case "listGitBranches":
         return this.listGitBranches(p.workdir as string | undefined);
       case "createWorktree":
@@ -793,7 +878,12 @@ export class AgentBridge {
     const options: AgentOptions = {
       callbacks,
       logger,
-      workdir: params.workdir,
+      // Only a restore can name a directory other than the caller's, and the
+      // lookup must stay off the fresh-session path: hosts expect
+      // `Agent.create` to be under way as soon as `initialize` is entered.
+      workdir: params.restoreSessionId
+        ? await this.restoreWorkdirFor(params, params.restoreSessionId)
+        : params.workdir,
       restoreSessionId: params.restoreSessionId,
       apiKey: params.apiKey,
       baseURL: params.baseURL,
@@ -819,30 +909,106 @@ export class AgentBridge {
 
     // Record where the session was created (see SessionEntry.createdWorkdir).
     // A fresh session's initialize workdir IS the creation dir. A from-disk
-    // re-attach (the daemon was restarted — killed / CLI 升级重启 / reboot —
-    // then status/send re-hosts the session) instead passes the re-attaching
-    // client's cwd — the transcript header (`{"type":"metadata","workdir":...}`, append-only since session
-    // creation) restores the original value when the agent's transcript is
-    // readable; otherwise the client cwd is the best available anchor.
+    // re-attach was already anchored on the session's own directory by
+    // `restoreWorkdirFor` when the agent was created just above, so the agent's
+    // transcript is the recorded one: the header read here confirms it and
+    // supplies the creation branch.
     let createdWorkdir: string;
+    let transcriptBranch: string | undefined;
     if (params.restoreSessionId) {
-      createdWorkdir =
-        (await readTranscriptWorkdir(agent.sessionFilePath)) ??
-        params.workdir ??
-        agent.currentWorkdir;
+      const header = await readTranscriptHeader(agent.sessionFilePath);
+      createdWorkdir = header.workdir ?? agent.currentWorkdir;
+      transcriptBranch = header.gitBranch;
     } else {
       createdWorkdir = params.workdir ?? agent.currentWorkdir;
     }
 
+    const worktree = deriveWorktreeInfo(createdWorkdir);
+    const createdWorktreeBranch = this.creationBranchOf(worktree, {
+      transcriptBranch,
+      restored: Boolean(params.restoreSessionId),
+    });
+
     this.sessions.set(agent.sessionId, {
       agent,
       // Keep storedConfig.workdir in sync: updateConfig rebuilds the agent from
       // storedConfig, so the rebuild must stay anchored on the creation dir too.
       storedConfig: { ...params, workdir: createdWorkdir },
       createdWorkdir,
+      createdWorktreeBranch,
     });
 
-    return this.initializeReply(agent, createdWorkdir);
+    return this.initializeReply(agent, createdWorkdir, worktree);
+  }
+
+  /**
+   * The directory a session being restored belongs to.
+   *
+   * `initialize`'s `workdir` is the **client's** directory, not the session's.
+   * For a fresh session the two are the same by definition, but a from-disk
+   * re-attach (daemon restarted — killed / CLI 升级重启 / reboot — then
+   * `status`/`send`/`wait` re-hosts the session) sends whatever cwd the
+   * re-attaching client happens to run in. Anchoring the agent there silently
+   * drops the session's own directory: a `create --worktree` session keeps the
+   * cwd of whoever attached first, its next turn (and its Bash tool) runs in the
+   * host repo instead of the worktree, and `destroy --remove-worktree` then
+   * resolves the wrong tree.
+   *
+   * The transcript's `metadata` header records the creation dir and is
+   * append-only (a Bash `cd`, an EnterWorktree and a re-host from another cwd
+   * all leave it alone), so it wins whenever it is readable **and** the
+   * directory still exists. A directory that is gone (worktree deleted by hand,
+   * project moved) is reported and the caller's directory is used instead —
+   * degenerate, but it is the only anchor left and must not abort the attach.
+   */
+  private async restoreWorkdirFor(
+    params: InitializeParams,
+    restoreSessionId: string,
+  ): Promise<string | undefined> {
+    const callerWorkdir = params.workdir ?? process.cwd();
+    const recorded = await readSessionWorkdir(restoreSessionId, callerWorkdir);
+    if (!recorded || recorded === callerWorkdir) {
+      return params.workdir;
+    }
+    if (!(await isDirectory(recorded))) {
+      logger?.warn(
+        `Session ${restoreSessionId} was created in ${recorded}, which no longer exists; restoring it in ${callerWorkdir} instead`,
+      );
+      return params.workdir;
+    }
+    return recorded;
+  }
+
+  /**
+   * The branch the session's worktree was created on — recorded once, at
+   * initialize (see `SessionEntry.createdWorktreeBranch`).
+   *
+   * Only a session created inside a linked git worktree has one: a session in
+   * the main working tree returns undefined, and so does a WorktreeCreate
+   * hook-managed worktree (its branches are not git's).
+   *
+   * Records, best first:
+   *
+   * 1. the transcript header's `gitBranch` — the creation-time record a
+   *    re-attached session recovers after a daemon restart;
+   * 2. the path layout `<repoRoot>/.wave/worktrees/<name>`
+   *    (`worktreeCreationBranch`) — the same answer, from the one thing that
+   *    always survives;
+   * 3. the worktree's HEAD — fresh sessions only, where nothing has had the
+   *    chance to check anything else out yet. Never for a re-attach: by then
+   *    HEAD may be a branch the user checked out, and that is the branch
+   *    removal must leave alone.
+   */
+  private creationBranchOf(
+    worktree: DerivedWorktree | undefined,
+    options: { transcriptBranch?: string; restored: boolean },
+  ): string | undefined {
+    if (!worktree || worktree.hookBased) return undefined;
+    return (
+      options.transcriptBranch ||
+      worktreeCreationBranch(worktree) ||
+      (options.restored ? undefined : worktree.branch || undefined)
+    );
   }
 
   /**
@@ -865,19 +1031,27 @@ export class AgentBridge {
   private initializeReply(
     agent: Agent,
     sessionCwd: string,
+    // Derived once by the caller: this reply and the creation-branch snapshot
+    // both need it, and it reads config files.
+    worktree = deriveWorktreeInfo(sessionCwd),
   ): {
     sessionId: string;
     currentWorkdir: string;
     sessionCwd: string;
+    workspaceRoot: string;
     repoRoot?: string;
     permissionMode: PermissionMode;
     latestTotalTokens: number;
   } {
-    const worktree = deriveWorktreeInfo(sessionCwd);
     return {
       sessionId: agent.sessionId,
       currentWorkdir: agent.currentWorkdir,
       sessionCwd,
+      // Which working tree the session works in right now — differs from
+      // `sessionCwd` only after a mid-session EnterWorktree, and hosts use it
+      // for the surfaces that follow the user's workspace (diff panel, file
+      // tree, `@` search).
+      workspaceRoot: agent.workspaceRoot,
       ...(worktree ? { repoRoot: worktree.repoRoot } : {}),
       permissionMode: agent.getPermissionMode(),
       latestTotalTokens: agent.latestTotalTokens,
@@ -910,16 +1084,35 @@ export class AgentBridge {
    * a removal that threw — the caller only ever needs to know whether the
    * directory is gone.
    *
-   * The return shape grew from `null` to `{worktreeRemoved}`; callers that pass
-   * no params (the CLI's own `wave daemon destroy`) read nothing and are
-   * unaffected. The CLI's `--remove-worktree` keeps its own client-side path
-   * (getSessionInfo + removeWorktree + destroy) — deliberately unchanged.
+   * **The worktree removal is not awaited** (2026-11-04). The reply goes out
+   * once the registry entry is gone and `agent.destroy()` has settled; removing
+   * the directory then runs in the background and the reply says
+   * `worktreeRemoval: "pending"`. Reason: the remote page times every request
+   * out at 20s (`REQUEST_TIMEOUT_MS` in `remote/shim.js`), while deleting a
+   * worktree that contains `node_modules` on Windows is a **minute-scale**
+   * operation — `git worktree remove` cannot delete pnpm's junctions (it exits
+   * 0 and leaves the directory), so it falls back to a recursive `fs.rmSync`.
+   * Awaiting that made every phone-side delete report a timeout even though the
+   * session was already gone. The desktop host has always worked this way
+   * (`handleDeleteSession` fire-and-forgets both steps and refreshes the UI
+   * immediately). The ordering above still holds: the background removal hangs
+   * off `agent.destroy()`'s promise, it is not concurrent with it.
+   *
+   * The return shape grew from `null` to `{worktreeRemoved}` to
+   * `{worktreeRemoved, worktreeRemoval}`; callers that pass no params (the
+   * CLI's own `wave daemon destroy`) read nothing and are unaffected. The CLI's
+   * `--remove-worktree` keeps its own client-side path (getSessionInfo +
+   * removeWorktree + destroy) — deliberately unchanged.
    */
   private async destroy(
     sessionId?: string,
     params?: { removeWorktree?: boolean },
-  ): Promise<{ worktreeRemoved: boolean }> {
+  ): Promise<{
+    worktreeRemoved: boolean;
+    worktreeRemoval: "none" | "pending";
+  }> {
     let createdWorkdir: string | undefined;
+    let createdWorktreeBranch: string | undefined;
     if (sessionId) {
       const entry = this.sessions.get(sessionId);
       if (entry) {
@@ -947,15 +1140,43 @@ export class AgentBridge {
         // for the same reason).
         this.sessions.delete(sessionId);
         createdWorkdir = entry.createdWorkdir;
+        createdWorktreeBranch = entry.createdWorktreeBranch;
         await entry.agent.destroy();
       }
     }
 
-    let worktreeRemoved = false;
-    if (params?.removeWorktree === true && createdWorkdir) {
-      worktreeRemoved = await this.removeSessionWorktree(createdWorkdir);
+    let worktreeRemoval: "none" | "pending" = "none";
+    if (
+      params?.removeWorktree === true &&
+      createdWorkdir &&
+      // fs-only and cheap (no git): deciding "is there a worktree at all" before
+      // the reply is what keeps `none` honest for plain sessions instead of
+      // reporting a removal that was never going to happen.
+      deriveWorktreeInfo(createdWorkdir)
+    ) {
+      // Backgrounded, not awaited: see the note above. The `.then` is the
+      // ordering guarantee — `removeSessionWorktree` starts only once
+      // `agent.destroy()` (awaited above) settled.
+      worktreeRemoval = "pending";
+      void this.removeSessionWorktree(createdWorkdir, createdWorktreeBranch)
+        .then((removed) => {
+          if (!removed) {
+            logger.warn(
+              `destroy: session ${sessionId ?? "(none)"} deleted, but its ` +
+                `worktree at ${createdWorkdir} survived removal`,
+            );
+          }
+        })
+        .catch((e: unknown) => {
+          logger.warn(
+            `destroy: background worktree removal failed for ` +
+              `${createdWorkdir}: ${(e as Error).message}`,
+          );
+        });
     }
-    return { worktreeRemoved };
+    // Pending means "the directory may still be there when this reply lands, and
+    // that is not a failure" — the caller must not read it as "removal failed".
+    return { worktreeRemoved: false, worktreeRemoval };
   }
 
   /**
@@ -965,15 +1186,33 @@ export class AgentBridge {
    * both fail, and for a hook-based worktree with no WorktreeRemove hook it
    * deliberately leaves it in place. Never throws — the caller has already
    * deleted the session.
+   *
+   * `createdBranch` is the branch the worktree was created on, snapshotted by
+   * the caller. It is **not** `worktree.branch`: that field is the worktree's
+   * current HEAD, which an in-session `git checkout` moves to a branch the user
+   * owns. Falls back to the path layout (`worktreeCreationBranch`) — a
+   * candidate only, `removeWorktree` confirms it against git — and to deleting
+   * no branch at all when neither can name one.
    */
-  private async removeSessionWorktree(sessionDir: string): Promise<boolean> {
+  private async removeSessionWorktree(
+    sessionDir: string,
+    createdBranch?: string,
+  ): Promise<boolean> {
     const worktree = deriveWorktreeInfo(sessionDir);
     if (!worktree) return false;
+    const branch = createdBranch || worktreeCreationBranch(worktree) || "";
+    if (!branch) {
+      logger.warn(
+        `removeSessionWorktree: cannot tell which branch ${worktree.path} was ` +
+          `created on — keeping every branch instead of deleting the one it ` +
+          `has checked out (${worktree.branch || "detached"})`,
+      );
+    }
     try {
       await removeWorktree({
         name: "",
         path: worktree.path,
-        branch: worktree.branch,
+        branch,
         repoRoot: worktree.repoRoot,
         hasUncommittedChanges: false,
         hasNewCommits: false,
@@ -1220,6 +1459,65 @@ export class AgentBridge {
     return { resolvedPath, dirs };
   }
 
+  /**
+   * One level of the file panel's directory tree (spec
+   * desktop-file-panel.md「文件面板工作区目录树」scenario 3): direct children
+   * only. Expansion is lazy per level, so this never walks a subtree.
+   *
+   * Serves **both** hosts: the desktop reaches this bridge through the local
+   * stdio client and, for a remote session, through the remote daemon tunnel.
+   * So the tree needs no ssh code of its own, and local vs remote cannot drift
+   * on ordering, filtering or the entry cap. It also keeps the tree on the same
+   * machine view as `searchFiles`, which the panel's filter box uses.
+   *
+   * Ordering, the junk deny-list and the cap live here rather than in the
+   * webview: "dirs first, then files, each by name" is one rule with one owner.
+   * The deny-list is a list of *known junk*, not "hide dotfiles" — `.github/`
+   * and `.env` are real project content the user browses for.
+   *
+   * `total` counts post-filter entries, so `total > entries.length` is exactly
+   * the 「还有 N 项未显示」 row the webview renders. A directory of 50k files
+   * would otherwise be shipped whole on every expansion.
+   */
+  private listDirectoryEntries(dir?: string): {
+    resolvedPath: string;
+    entries: Array<{ name: string; type: "dir" | "file" }>;
+    total: number;
+  } {
+    if (!dir) {
+      throw new RpcError(PROTOCOL_INTERNAL_ERROR, "dir is required");
+    }
+    const expanded =
+      dir === "~" || dir.startsWith("~/") ? join(homedir(), dir.slice(1)) : dir;
+    let resolvedPath: string;
+    let dirents: Dirent[];
+    try {
+      resolvedPath = realpathSync(expanded);
+      dirents = readdirSync(resolvedPath, { withFileTypes: true });
+    } catch {
+      // Missing and unreadable get the same verdict: the tree cannot descend
+      // into either, and an empty list would read as 「空目录」.
+      throw new RpcError(PROTOCOL_INTERNAL_ERROR, `目录不存在或不可读：${dir}`);
+    }
+    const entries = dirents
+      .filter((e) => !DIR_ENTRY_JUNK.has(e.name))
+      .map((e) => ({ name: e.name, type: direntType(resolvedPath, e) }))
+      .filter(
+        (e): e is { name: string; type: "dir" | "file" } => e.type !== null,
+      )
+      .sort(
+        (a, b) =>
+          // Directories first, then files — the tree's fixed order.
+          (a.type === b.type ? 0 : a.type === "dir" ? -1 : 1) ||
+          a.name.localeCompare(b.name),
+      );
+    return {
+      resolvedPath,
+      entries: entries.slice(0, DIR_ENTRY_MAX_PER_LEVEL),
+      total: entries.length,
+    };
+  }
+
   private listGitBranches(workdir?: string): {
     branches: string[];
     current: string | null;
@@ -1231,6 +1529,7 @@ export class AgentBridge {
       cwd: workdir,
       encoding: "utf8" as const,
       stdio: ["ignore", "pipe", "pipe"] as ["ignore", "pipe", "pipe"],
+      windowsHide: true,
     };
     let branchesRaw: string;
     try {
@@ -1432,12 +1731,18 @@ export class AgentBridge {
     return getWorktreeChanges(params.path, params.baseBranch);
   }
 
+  /**
+   * `removed` answers "is the directory gone", not "did we ask": removal is
+   * best-effort and leaves the directory (and its branch) behind when git and
+   * the fs fallback both fail — the one thing a caller may not do is print a
+   * success line for that. Callers that ignore it are unaffected.
+   */
   private async removeWorktreeSession(params: {
     path: string;
     branch: string;
     repoRoot: string;
     hookBased?: boolean;
-  }): Promise<{ ok: true }> {
+  }): Promise<{ ok: true; removed: boolean }> {
     // Hook-based worktrees are owned by the WorktreeRemove hook; the git-root
     // containment check does not apply to them.
     if (!params.hookBased) {
@@ -1454,7 +1759,7 @@ export class AgentBridge {
     // removeWorktree is best-effort/idempotent: already-removed worktrees or
     // branches only log, never throw. Hook-based worktrees go through the
     // WorktreeRemove hook inside removeWorktree.
-    await removeWorktree({
+    const removed = await removeWorktree({
       name: "",
       path: params.path,
       branch: params.branch,
@@ -1464,12 +1769,13 @@ export class AgentBridge {
       isNew: false,
       hookBased: params.hookBased,
     });
-    return { ok: true };
+    return { ok: true, removed };
   }
 
   private async getSessionInfo(sessionId?: string): Promise<{
     sessionId: string;
     sessionCwd: string;
+    worktreeBranch?: string;
     latestTotalTokens: number;
     permissionMode: PermissionMode;
     availableTools: string[];
@@ -1486,6 +1792,11 @@ export class AgentBridge {
       // destroy --remove-worktree resolves the session's worktree from this
       // value, and it must not drift when the session cd'd out of the worktree.
       sessionCwd: entry.createdWorkdir,
+      // Same reason one level down: the branch to delete is the one the
+      // worktree was CREATED on, not the one it has checked out now.
+      ...(entry.createdWorktreeBranch
+        ? { worktreeBranch: entry.createdWorktreeBranch }
+        : {}),
       latestTotalTokens: entry.agent.latestTotalTokens,
       permissionMode: entry.agent.getPermissionMode(),
       availableTools: entry.agent.getAvailableToolNames(),
@@ -1655,15 +1966,25 @@ export class AgentBridge {
   private async updateUserSettings(
     patch: UserPreferenceSettings,
   ): Promise<UserPreferenceSettingsView> {
-    await updateUserPreferenceSettings(patch);
-    if (!Object.values(patch).every((value) => value === undefined)) {
-      await Promise.all(
-        [...this.sessions.values()].map((entry) =>
-          entry.agent.reloadConfiguration(),
-        ),
-      );
-    }
-    return this.userSettingsView();
+    // 串行执行（spec core/agent-config.md「设置页控件的保存时机」场景 9）：
+    // `updateUserPreferenceSettings` 是「同步读 → await 异步写」的读-改-写，而 stdio
+    // 请求是并发处理的（`jsonRpcConnection` 的 line 回调不 await `handleLine`）。设置页
+    // 改成「改一下就写一次」之后，快速连拨两个开关就是两笔并发写：后一笔读到的是前
+    // 一笔落盘之前的文件，前一笔的键会被整包覆盖掉。排队即可，代价是一次写盘的时长。
+    const write = this.userSettingsWriteQueue.then(async () => {
+      await updateUserPreferenceSettings(patch);
+      if (!Object.values(patch).every((value) => value === undefined)) {
+        await Promise.all(
+          [...this.sessions.values()].map((entry) =>
+            entry.agent.reloadConfiguration(),
+          ),
+        );
+      }
+      return this.userSettingsView();
+    });
+    // 队列本身不因某一次失败而断掉：错误交给本次调用方（原 promise）回给宿主。
+    this.userSettingsWriteQueue = write.catch(() => undefined);
+    return write;
   }
 
   /**
@@ -1681,7 +2002,7 @@ export class AgentBridge {
   private async sendMessage(
     params: {
       text: string;
-      images?: Array<{ path: string; mimeType: string }>;
+      images?: UserImage[];
       force?: boolean;
     },
     sessionId?: string,
@@ -1721,15 +2042,17 @@ export class AgentBridge {
 
   /**
    * Webview hosts (desktop/vscode/jetbrains) send pasted images as inline
-   * data URLs — there is no local file behind them. Persist each to a temp
-   * file so the model gets a real path it can reference with tools (aligned
-   * with Claude Code's `[Image source: <path>]` metadata). Real paths pass
-   * through untouched; unparseable data URLs pass through as-is and are
-   * skipped by the SDK rather than blocking the message.
+   * data URLs — there is no local file behind them. Write each to a temp file
+   * so the model gets a real path it can reference with tools (aligned with
+   * Claude Code's `[Image source: <path>]` metadata), and **keep the data URL
+   * as the image's value**: the bytes stay in the message block (and therefore
+   * in memory and in the transcript), so any GUI can preview the picture
+   * without asking its host for a file (spec ui/image-pasting.md「已发送图片的
+   * 标签点开就能看」). Real paths pass through untouched; unparseable data URLs
+   * pass through as-is and are skipped by the SDK rather than blocking the
+   * message.
    */
-  private persistDataUrlImages(
-    images?: Array<{ path: string; mimeType: string }>,
-  ): Array<{ path: string; mimeType: string }> | undefined {
+  private persistDataUrlImages(images?: UserImage[]): UserImage[] | undefined {
     if (!images || images.length === 0) return images;
     return images.map((img) => {
       if (!img.path.startsWith("data:")) return img;
@@ -1743,7 +2066,7 @@ export class AgentBridge {
           `wave-image-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.${ext}`,
         );
         writeFileSync(filePath, Buffer.from(match[2], "base64"));
-        return { path: filePath, mimeType };
+        return { ...img, mimeType, filePath };
       } catch (error) {
         logger.warn("Failed to persist pasted image to temp file:", error);
         return img;
@@ -1805,43 +2128,33 @@ export class AgentBridge {
     inputContent: string;
   }> {
     const entry = this.requireSession(sessionId);
-    const { messages } = await entry.agent.getFullMessageThread();
-    // 压缩是 append-only：同 id 消息（压缩前历史 + 压缩后 append 的重复）会
-    // 在磁盘完整线程中出现多次。用户看到的折叠视图对应最后一次出现，
-    // 因此匹配最后一个而非第一个，避免回滚时连压缩摘要一起删掉。
-    const index = messages.map((m) => m.id).lastIndexOf(messageId);
-    if (index === -1) {
+    // 扫转录按 id 定位（同 id 多次出现取最后一次），不读整份线程：这条路上
+    // 需要的只是「在完整线程里的位置」与「那段文本」。
+    const target = await entry.agent.findRewindTarget(messageId);
+    if (!target) {
       throw new RpcError(
         PROTOCOL_INTERNAL_ERROR,
         `Message not found: ${messageId}`,
       );
     }
-    const message = messages[index];
-    const textBlock = message.blocks.find((b) => b.type === "text") as
-      | { content?: string }
-      | undefined;
-    await entry.agent.truncateHistory(index);
-    return { inputContent: textBlock?.content || "" };
+    await entry.agent.truncateHistory(target.index);
+    return { inputContent: target.content };
   }
 
   private async listRewindCheckpoints(sessionId?: string): Promise<{
     checkpoints: Array<{ id: string; content: string }>;
   }> {
     const entry = this.requireSessionForRead(sessionId);
-    const { messages } = await entry.agent.getFullMessageThread();
-    // 压缩 append-only 后同 id 消息在磁盘完整线程中重复出现（压缩前历史 +
-    // 压缩后 append 的重复）。按 id 去重并保留最后一次出现（与折叠后的
-    // UI/内存视图一致），避免弹窗把同一条用户消息显示两遍。
-    const checkpointMap = new Map<string, { id: string; content: string }>();
-    for (const m of messages) {
-      if (isUserCheckpointMessage(m) && m.id) {
-        checkpointMap.set(m.id, {
-          id: m.id,
-          content: getMessageContent(m).replace(/\s+/g, " ").trim(),
-        });
-      }
-    }
-    return { checkpoints: Array.from(checkpointMap.values()) };
+    // 检查点表由 SDK 扫转录投影出来（`{id, content, index}`），这里只为页面
+    // 摘掉它用不到的 `index`：回滚是另一次 `rewindToMessage` 调用，页面不需要
+    // 位置。压缩 append-only 的同 id 去重也在 SDK 那侧做完了。
+    const checkpoints = await entry.agent.getRewindCheckpoints();
+    return {
+      checkpoints: checkpoints.map(({ id, content }) => ({
+        id,
+        content: content.replace(/\s+/g, " ").trim(),
+      })),
+    };
   }
 
   private deleteQueuedMessage(index: number, sessionId?: string): null {
@@ -1853,7 +2166,7 @@ export class AgentBridge {
   private updateQueuedMessage(
     id: string,
     text: string,
-    images: Array<{ path: string; mimeType: string }> | undefined,
+    images: UserImage[] | undefined,
     sessionId?: string,
   ): { ok: boolean } {
     const entry = this.requireSession(sessionId);
@@ -1874,22 +2187,23 @@ export class AgentBridge {
    * Read a session's display messages.
    *
    * With no parameters this returns the whole list the agent holds, read once
-   * and cached nowhere (spec ui/message-rendering-system.md「首屏就是整份列表，
-   * 不分页」). Two parameters narrow it, both for the remote page:
+   * and cached nowhere. The parameters pick one page instead
+   * (spec ui/message-rendering-system.md「首屏一页，上翻按需取更早」):
    *
-   * - `limit` — the newest `limit` messages (that page's frame budget).
+   * - `limit` — the newest `limit` messages (首屏；远控页按单帧预算给 100).
+   * - `before` — the page just above that id, read from the transcript
+   *             (上翻取更早；压缩之前的历史走这条). Comes back with `hasMore`
+   *             so the page knows when it reached the start of the session.
    * - `since` — everything appended after the given message id (catching up
    *             after a reconnect).
    *
-   * The list starts at the last compaction, so its earliest entry is the
-   * earliest any UI can reach; there is nothing older to read back.
-   *
-   * `since` is a position, not a version number: message ids are stable, so a
-   * caller can name its last known message without the list carrying a
-   * sequence number. The one failure that matters is the anchor having been
-   * truncated away (rewind / clear) — there is no seq/version in the store that
-   * could detect it otherwise — and that comes back as `reset: true` so the
-   * caller re-pulls instead of guessing.
+   * `since` / `before` are positions, not version numbers: message ids are
+   * stable, so a caller can name its last known message without the list
+   * carrying a sequence number. The one failure that matters is the anchor
+   * having been truncated away (rewind / clear) — there is no seq/version in
+   * the store that could detect it otherwise — and that comes back as
+   * `reset: true` (for `since`) or `anchorLost: true` (for `before`) so the
+   * caller re-pulls / retries instead of guessing.
    *
    * Ids can repeat (old transcripts re-appended the preserved rounds at each
    * compact point), so anchors are resolved to their **last** occurrence:
@@ -1932,7 +2246,7 @@ export class AgentBridge {
         threadSummary,
       };
     }
-    const page = entry.agent.getMessagePage(normalized);
+    const page = await entry.agent.getMessagePage(normalized);
     return {
       ...page,
       messages: messagesForUi(page.messages),
@@ -1941,15 +2255,6 @@ export class AgentBridge {
     };
   }
 
-  private async getFullMessageThread(sessionId?: string): Promise<{
-    messages: Message[];
-    sessionIds: string[];
-  }> {
-    const entry = this.requireSessionForRead(sessionId);
-    const thread = await entry.agent.getFullMessageThread();
-    return { ...thread, messages: messagesForUi(thread.messages) };
-  }
-
   private async compact(
     customInstructions: string | undefined,
     sessionId?: string,
@@ -2960,10 +3265,10 @@ export class AgentBridge {
           ctx.registeredSessionId,
         );
       },
-      onErrorBlockAdded: (error: string) => {
+      onNoticeAdded: (notice) => {
         this.emit(
-          "errorBlockAdded",
-          remoteWire.errorBlockAdded(error),
+          "noticeAdded",
+          remoteWire.noticeAdded(notice),
           ctx.registeredSessionId,
         );
       },
@@ -3037,6 +3342,16 @@ export class AgentBridge {
           ctx.registeredSessionId,
         );
       },
+      onWorkspaceRootChange: (workspaceRoot: string) => {
+        // EnterWorktree / ExitWorktree only: the conversation now works in
+        // another working tree, so the host re-points the surfaces that follow
+        // the user's workspace (a Bash `cd` never lands here).
+        this.emit(
+          "workspaceRootChange",
+          { workspaceRoot },
+          ctx.registeredSessionId,
+        );
+      },
       onMcpServersChange: (servers: McpServerStatus[]) => {
         this.emit("mcpServersChange", { servers }, ctx.registeredSessionId);
       },
@@ -3185,26 +3500,37 @@ async function readTextFileSafe(filePath: string): Promise<string> {
   }
 }
 
+/** Whether `path` exists and is a directory (a missing path simply answers false). */
+async function isDirectory(dirPath: string): Promise<boolean> {
+  try {
+    return (await stat(dirPath)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
 /**
- * Read the creation-time workdir from a session transcript's metadata header —
+ * Read the creation-time facts from a session transcript's metadata header —
  * the first line `{"type":"metadata","workdir":...,"createdAt":...,"gitBranch":...}`
  * the SDK writes once at session creation. The header is append-only, so it
  * records where the session was created even after the live working directory
  * drifted (in-session `cd`) or after a daemon restart re-anchored the agent at
- * a client's cwd. Returns undefined when the file is missing, legacy (no
+ * a client's cwd, and its `gitBranch` records the branch that directory was on
+ * at creation. Returns an empty object when the file is missing, legacy (no
  * header), or unreadable. Only the header line is read (transcripts can grow
  * large); a 4KiB read covers any realistic header.
  */
-async function readTranscriptWorkdir(
-  transcriptPath?: string,
-): Promise<string | undefined> {
-  if (!transcriptPath) return undefined;
+async function readTranscriptHeader(transcriptPath?: string): Promise<{
+  workdir?: string;
+  gitBranch?: string;
+}> {
+  if (!transcriptPath) return {};
   try {
     const handle = await open(transcriptPath, "r");
     try {
       const buffer = Buffer.alloc(4096);
       const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
-      if (bytesRead === 0) return undefined;
+      if (bytesRead === 0) return {};
       const newline = buffer.indexOf(0x0a);
       const firstLine = buffer
         .subarray(0, newline === -1 ? bytesRead : newline)
@@ -3212,14 +3538,21 @@ async function readTranscriptWorkdir(
       const header = JSON.parse(firstLine) as {
         type?: string;
         workdir?: unknown;
+        gitBranch?: unknown;
+      };
+      if (header.type !== "metadata") return {};
+      return {
+        workdir:
+          typeof header.workdir === "string" ? header.workdir : undefined,
+        gitBranch:
+          typeof header.gitBranch === "string" && header.gitBranch
+            ? header.gitBranch
+            : undefined,
       };
-      return header.type === "metadata" && typeof header.workdir === "string"
-        ? header.workdir
-        : undefined;
     } finally {
       await handle.close();
     }
   } catch {
-    return undefined;
+    return {};
   }
 }