wave-code 1.5.1 → 1.6.1

package/src/stdio/agentBridge.ts

@@ -39,7 +39,9 @@ import {
   listAllSessions,
   readRecentWorkdirs,
   rememberRecentWorkdir,
+  forgetRecentWorkdir,
   setSessionCustomTitle,
+  readSessionWorkdir,
   searchFiles,
   generateRandomName,
   getDefaultRemoteBranch,
@@ -58,6 +60,7 @@ import {
   updateUserPreferenceSettings,
   type UserPreferenceSettings,
   type UserPreferenceSettingsView,
+  type AccountCredential,
   type SubagentConfiguration,
   type SkillMetadata,
   type PluginReloadResult,
@@ -74,6 +77,7 @@ import {
   revokeArtifact,
   searchArtifactMembers,
   type ArtifactShareMode,
+  type UserImage,
 } from "wave-agent-sdk";
 import {
   type ClientNotificationMethod,
@@ -95,7 +99,7 @@ import {
   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 {
@@ -103,6 +107,8 @@ import {
   deriveWorktreeInfo,
   getWorktreeChanges,
   removeWorktree,
+  worktreeCreationBranch,
+  type DerivedWorktree,
 } from "../utils/worktree.js";
 import { logger } from "../utils/logger.js";
 import {
@@ -118,6 +124,8 @@ import {
 } from "../remote/remoteNotifications.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 +217,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
@@ -280,6 +302,10 @@ function direntType(parentDir: string, dirent: Dirent): "dir" | "file" | 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). */
@@ -297,13 +323,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.
    */
@@ -407,7 +433,7 @@ export class AgentBridge {
         return this.sendMessage(
           p as unknown as {
             text: string;
-            images?: Array<{ path: string; mimeType: string }>;
+            images?: UserImage[];
             force?: boolean;
           },
           sessionId,
@@ -430,7 +456,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":
@@ -459,6 +485,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":
@@ -701,6 +740,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":
@@ -794,6 +839,25 @@ export class AgentBridge {
       if (entry) {
         this.pendingPermissions.delete(p.requestId);
         entry.resolve(p.decision);
+        // 不带反馈的拒绝 = 用户关掉了确认卡（关闭键 / Esc），本轮在用户这边就
+        // 结束：与桌面端 / VS Code / JetBrains 的 `denied → abortMessage()` 是
+        // 同一条语义，也与 Claude Code 的 `cancelAndAbort`（无 feedback 直接
+        // abort 整轮）一致。**带 message 的拒绝不中断**——那是用户给出理由后
+        // 拒绝这一次工具调用，模型要照反馈继续或改问（spec
+        // ui/confirm-ui.md 场景 2 / 5、remote/remote-web.md 场景 24）。
+        // 中断本身不阻塞回包，失败（会话正被重建 / 已销毁）也不影响这次拒绝
+        // 已经生效，因此静默。
+        const rejectionFeedback = p.decision?.message?.trim();
+        if (
+          p.decision?.behavior === "deny" &&
+          !rejectionFeedback &&
+          entry.sessionId
+        ) {
+          const session = this.sessions.get(entry.sessionId);
+          if (session && !session.transitioning) {
+            void session.agent.abortMessage();
+          }
+        }
       }
     }
   }
@@ -834,7 +898,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,
@@ -860,30 +929,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)
+    );
   }
 
   /**
@@ -906,6 +1051,9 @@ 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;
@@ -915,7 +1063,6 @@ export class AgentBridge {
     permissionMode: PermissionMode;
     latestTotalTokens: number;
   } {
-    const worktree = deriveWorktreeInfo(sessionCwd);
     return {
       sessionId: agent.sessionId,
       currentWorkdir: agent.currentWorkdir,
@@ -957,16 +1104,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) {
@@ -994,15 +1160,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 };
   }
 
   /**
@@ -1012,15 +1206,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,
@@ -1153,11 +1365,12 @@ export class AgentBridge {
    */
   private emitContextUsage(agent: Agent): void {
     const tokens = agent.latestTotalTokens;
-    const max = agent.getMaxInputTokens();
+    const max = agent.getContextWindow();
+    const maxOutput = agent.getMaxOutputTokens?.() ?? 32_000;
     if (tokens > 0 && max > 0) {
       this.emit(
         "contextUsage",
-        remoteWire.contextUsage(tokens, max),
+        remoteWire.contextUsage(tokens, max, maxOutput),
         agent.sessionId,
       );
     }
@@ -1172,9 +1385,10 @@ export class AgentBridge {
    */
   private contextUsagePercentOf(agent: Agent): number | undefined {
     const tokens = agent.latestTotalTokens;
-    const max = agent.getMaxInputTokens();
+    const max = agent.getContextWindow();
+    const maxOutput = agent.getMaxOutputTokens?.() ?? 32_000;
     if (tokens > 0 && max > 0) {
-      return percentOf(tokens, max);
+      return percentOf(tokens, max, maxOutput);
     }
     return undefined;
   }
@@ -1337,6 +1551,7 @@ export class AgentBridge {
       cwd: workdir,
       encoding: "utf8" as const,
       stdio: ["ignore", "pipe", "pipe"] as ["ignore", "pipe", "pipe"],
+      windowsHide: true,
     };
     let branchesRaw: string;
     try {
@@ -1538,12 +1753,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) {
@@ -1560,7 +1781,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,
@@ -1570,12 +1791,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[];
@@ -1592,6 +1814,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(),
@@ -1761,15 +1988,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;
   }
 
   /**
@@ -1787,7 +2024,7 @@ export class AgentBridge {
   private async sendMessage(
     params: {
       text: string;
-      images?: Array<{ path: string; mimeType: string }>;
+      images?: UserImage[];
       force?: boolean;
     },
     sessionId?: string,
@@ -1827,15 +2064,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;
@@ -1849,7 +2088,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;
@@ -1949,7 +2188,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);
@@ -2573,20 +2812,77 @@ export class AgentBridge {
   }
 
   // ── Auth (global) ────────────────────────────────────────────
+  /**
+   * 认证状态 + **凭据形态**（spec desktop-account.md「账户卡片 · 认证方式」）。
+   *
+   * `isAuthenticated` 只回答「有没有 SSO token」；宿主据此渲染卡片与发送入口会
+   * 把「key 写在 settings.json 里」的人判成没有凭据（卡片显示登录按钮、输入框
+   * 被锁）。故同一次查询里一并给出 `credential`，优先级与 SDK 的
+   * `resolveGatewayConfig` 对齐：企业账号 > 自定义网关 > 无凭据。
+   */
   private async getAuthStatus(): Promise<{
     isAuthenticated: boolean;
+    credential: AccountCredential;
     user: { id: string; email?: string } | undefined;
     serverUrl: string;
   }> {
     const authService = AuthService.getInstance();
     await authService.checkAndRefreshTokenIfNeeded();
+    const isAuthenticated = authService.isSSOAuthenticated();
     return {
-      isAuthenticated: authService.isSSOAuthenticated(),
+      isAuthenticated,
+      credential: this.resolveCredential(isAuthenticated),
       user: authService.getAuthUser(),
       serverUrl: authService.getServerUrl(),
     };
   }
 
+  /**
+   * 凭据形态。**判据只有这一处**——消费方（宿主 / webview）不得自己读配置推断。
+   *
+   * 网关层的取值顺序与 `resolveGatewayConfig` 一致：
+   * - 无 SSO：先问一个活着的会话的 `getGatewayConfig()`（与真实请求同源，已合并
+   *   用户 / 项目 / 远端三层 `env`），没有会话时退回「用户级 settings.json 的
+   *   `env`（`loadUserConfigEnv`）→ OS 环境变量」。
+   * - 有 SSO：**不能**用 `getGatewayConfig()`（它此时返回 SSO 凭据），回落的那份
+   *   网关只能从配置层读——卡片要靠它给「退出登录」项写后果。
+   *
+   * 注意 `setEnvironmentVars` 只把 `WAVE_SERVER_URL` 镜像进 `process.env`，网关
+   * 凭据留在会话快照里，所以只看 `process.env` 会把配好的人判成无凭据。
+   */
+  private resolveCredential(isAuthenticated: boolean): AccountCredential {
+    const gateway = isAuthenticated
+      ? this.configuredGatewayCredential()
+      : (this.sessionGatewayCredential() ?? this.configuredGatewayCredential());
+    if (isAuthenticated) {
+      // 企业账号生效中；`gateway` 仅表示「退出登录后会落到的那份」。
+      return gateway ? { kind: "sso", gateway } : { kind: "sso" };
+    }
+    return gateway ? { kind: "gateway", gateway } : { kind: "none" };
+  }
+
+  /** 活着的会话真正解析出来的网关配置（无 SSO 时它就是要发出去的那一份）。 */
+  private sessionGatewayCredential(): { host: string | null } | null {
+    for (const entry of this.sessions.values()) {
+      const gateway = entry.agent.getGatewayConfig();
+      if (gateway.apiKey) return { host: hostOfBaseUrl(gateway.baseURL) };
+    }
+    return null;
+  }
+
+  /**
+   * 配置层的网关凭据：用户级 settings.json 的 `env` 优先于 OS 环境变量（与
+   * `resolveGatewayConfig` 的 `env（settings.json）> process.env` 同序）。
+   */
+  private configuredGatewayCredential(): { host: string | null } | null {
+    const userEnv = loadUserConfigEnv();
+    const pick = (key: "WAVE_API_KEY" | "WAVE_BASE_URL"): string | undefined =>
+      userEnv[key]?.trim() || process.env[key]?.trim() || undefined;
+    const apiKey = pick("WAVE_API_KEY");
+    if (!apiKey) return null;
+    return { host: hostOfBaseUrl(pick("WAVE_BASE_URL")) };
+  }
+
   private async getAccountInfo(): Promise<{
     /**
      * 计费结论（套餐两根条 + 到期日 + 降级原因），形状见 codechat `GET /api/v1/account` → `billing`
@@ -3048,10 +3344,10 @@ export class AgentBridge {
           ctx.registeredSessionId,
         );
       },
-      onErrorBlockAdded: (error: string) => {
+      onNoticeAdded: (notice) => {
         this.emit(
-          "errorBlockAdded",
-          remoteWire.errorBlockAdded(error),
+          "noticeAdded",
+          remoteWire.noticeAdded(notice),
           ctx.registeredSessionId,
         );
       },
@@ -3068,11 +3364,12 @@ export class AgentBridge {
         // request (fresh total) and on session restore (the persisted total),
         // so the webview button shows real usage without waiting for a turn —
         // aligned with the CLI, which reads the same callback (spec 场景 5/6).
-        const max = ctx.agent?.getMaxInputTokens() ?? 0;
+        const max = ctx.agent?.getContextWindow() ?? 0;
+        const maxOutput = ctx.agent?.getMaxOutputTokens?.() ?? 32_000;
         if (max > 0) {
           this.emit(
             "contextUsage",
-            remoteWire.contextUsage(tokens, max),
+            remoteWire.contextUsage(tokens, max, maxOutput),
             ctx.registeredSessionId,
           );
         }
@@ -3138,6 +3435,13 @@ export class AgentBridge {
       onMcpServersChange: (servers: McpServerStatus[]) => {
         this.emit("mcpServersChange", { servers }, ctx.registeredSessionId);
       },
+      onQuotaHeaders: (headers: Record<string, string>) => {
+        // 额度响应头（codechat proxy 每次模型调用都发，spec:
+        // desktop/desktop-account.md「额度响应头」）：桌面端宿主据此刷新账户卡片的
+        // 用量读数，是 60s 轮询删除后的主要刷新源。原样透传 —— 字段解析与映射都
+        // 在消费方。不进 remoteWire：远程页不渲染账户卡片。
+        this.emit("quotaHeaders", { headers }, ctx.registeredSessionId);
+      },
       onNotificationMessageAdded: (params) => {
         // The LAST matching message, not the first: one task can notify more
         // than once under the same task id (a workflow warns about its size
@@ -3271,6 +3575,19 @@ function isSessionRecoveryError(error: unknown): boolean {
   );
 }
 
+/**
+ * `baseURL` → 网关主机名（`api.example.com`）。缺省 / 不可解析一律 null（卡片读
+ * 「默认端点」）——这里只做展示，不做任何可用性判断。
+ */
+function hostOfBaseUrl(baseURL: string | undefined): string | null {
+  if (!baseURL) return null;
+  try {
+    return new URL(baseURL).host || null;
+  } catch {
+    return null;
+  }
+}
+
 /** Read a text file, returning "" when it does not exist. */
 async function readTextFileSafe(filePath: string): Promise<string> {
   try {
@@ -3283,26 +3600,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)
@@ -3310,14 +3638,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 {};
   }
 }