wave-code 1.2.0 → 1.4.0

package/src/stdio/agentBridge.ts

@@ -36,6 +36,8 @@ import {
   type PartialHookConfiguration,
   isValidHookEvent,
   listSessions,
+  listAllSessions,
+  setSessionCustomTitle,
   searchFiles,
   generateRandomName,
   getDefaultRemoteBranch,
@@ -49,30 +51,61 @@ import {
   loadWaveConfigFromFile,
   getUserConfigPaths,
   getProjectConfigPaths,
+  readUserPreferenceView,
+  updateUserPreferenceSettings,
+  type UserPreferenceSettings,
+  type UserPreferenceSettingsView,
   type SubagentConfiguration,
   type SkillMetadata,
+  type PluginReloadResult,
+  type RemoteControlSnapshot,
+  normalizeEntrypoint,
 } from "wave-agent-sdk";
 import {
+  type ClientNotificationMethod,
   type JsonRpcError,
+  type RequestMethod,
+  type ServerNotificationMethod,
   INVALID_PARAMS as PROTOCOL_INVALID_PARAMS,
   INTERNAL_ERROR as PROTOCOL_INTERNAL_ERROR,
   METHOD_NOT_FOUND as PROTOCOL_METHOD_NOT_FOUND,
 } from "./protocol.js";
 import { execFileSync } from "node:child_process";
-import { mkdirSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  mkdirSync,
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  readdirSync,
+  realpathSync,
+} from "node:fs";
 import { mkdir, open, readFile, writeFile } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
 import { basename, dirname, extname, join } from "node:path";
 import {
   createWorktree,
+  deriveWorktreeInfo,
   getWorktreeChanges,
   removeWorktree,
 } from "../utils/worktree.js";
 import { logger } from "../utils/logger.js";
+import {
+  InvalidMessageWindowError,
+  sliceMessageWindow,
+  type MessageWindowResult,
+} from "../remote/messageWindow.js";
+import {
+  percentOf,
+  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 type { RemoteControlController } from "../remote/remoteControlService.js";
 
 export type NotificationEmitter = (
-  method: string,
+  method: ServerNotificationMethod,
   params: unknown,
   sessionId?: string,
 ) => void;
@@ -84,6 +117,17 @@ export interface AgentBridgeOptions {
    * down its socket and exits. stdio mode leaves it unset, so `shutdown` is
    * "Method not found" there. */
   onShutdownRequest?: () => void;
+  /** Daemon transport only. Remote control is a daemon-level concern (it owns
+   * an outbound socket and a relay session); the bridge owns nothing here and
+   * only routes the three `remoteControl*` RPCs to it, exactly as it routes
+   * `shutdown` to `onShutdownRequest`. Unset ⇒ those RPCs report that remote
+   * control is not enabled, which is the state on every stdio-mode process.
+   *
+   * Resolved on demand rather than passed as an object: the controller needs
+   * this bridge to route the phone's requests back in, so the two are built in
+   * a circle. Reading it when an RPC arrives — long after both exist — keeps
+   * that circle from having to be broken with a placeholder. */
+  remoteControl?: () => RemoteControlController | undefined;
 }
 
 interface InitializeParams {
@@ -95,7 +139,6 @@ interface InitializeParams {
   defaultHeaders?: Record<string, string>;
   model?: string;
   fastModel?: string;
-  language?: string;
   permissionMode?: PermissionMode;
   tools?: string[];
   allowedTools?: string[];
@@ -104,11 +147,18 @@ interface InitializeParams {
   mcpServers?: Record<string, McpServerConfig>;
   worktreeName?: string;
   isNewWorktree?: boolean;
-  /** Settings-page auto-memory toggle/frequency (session-level override). */
-  autoMemoryEnabled?: boolean;
-  autoMemoryFrequency?: number;
+  /**
+   * Which host the session belongs to → the `app.entrypoint` attribute. A raw
+   * string: it arrives over the wire, from hosts this process does not compile
+   * against (the JetBrains plugin builds its own frames). Narrowed to the known
+   * table below before it reaches the SDK.
+   */
+  entrypoint?: string;
 }
 
+// 会话级覆盖项：用户偏好（语言 / 上下文长度 / 自动记忆开关与频率）不在此层——
+// 它们落用户级 ~/.wave/settings.json 经实时重载生效（getUserSettings /
+// updateUserSettings），走覆盖层会永久遮蔽 settings.json 的实时值。
 interface UpdateConfigParams {
   apiKey?: string;
   baseURL?: string;
@@ -116,10 +166,6 @@ interface UpdateConfigParams {
   defaultHeaders?: Record<string, string>;
   model?: string;
   fastModel?: string;
-  language?: string;
-  /** Settings-page auto-memory toggle/frequency (session-level override). */
-  autoMemoryEnabled?: boolean;
-  autoMemoryFrequency?: number;
 }
 
 interface SearchFilesParams {
@@ -141,6 +187,24 @@ interface SessionEntry {
    * header when the session is re-attached from disk after a daemon restart.
    */
   createdWorkdir: 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
+   * does not look deleted to a `wait` that is blocked on it) but has no usable
+   * agent. Two consequences, both deliberate:
+   *
+   * - `listDaemonSessions` reports it as `isLoading: true`. The teardown aborts
+   *   the in-flight turn, so the outgoing agent reads `isLoading: false` while the
+   *   rebuild is still running; reporting that would let a `wait` print an idle
+   *   snapshot for a session whose agent is mid-replacement. A waiter that keeps
+   *   waiting is never wrong here — the rebuild is bounded, and if it fails the
+   *   entry is dropped, so the waiter then gets a clear "no longer exists".
+   * - State-changing RPCs refuse it (`requireSession`); a message sent to the
+   *   outgoing agent would be silently lost. Read-only RPCs still work
+   *   (`requireSessionForRead`) and see the outgoing agent's data, which is this
+   *   same session's transcript.
+   */
+  transitioning?: boolean;
 }
 
 /**
@@ -169,14 +233,26 @@ export class AgentBridge {
     }
   >();
   private permissionCounter = 0;
+  /**
+   * In-flight completion calls, keyed by envelope sessionId. Completion answers
+   * 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: 同一时刻只允许一个补全请求在途).
+   */
+  private inFlightCompletions = new Map<string, AbortController>();
   private emit: NotificationEmitter;
   private onShutdownRequest: (() => void) | undefined;
+  private remoteControl:
+    | (() => RemoteControlController | undefined)
+    | undefined;
   private pluginCore: PluginCore | undefined;
   private pluginCoreWorkdir: string | undefined;
 
   constructor(options: AgentBridgeOptions) {
     this.emit = options.emit;
     this.onShutdownRequest = options.onShutdownRequest;
+    this.remoteControl = options.remoteControl;
     // Mirror the user-level settings env WAVE_SERVER_URL into process.env
     // before any agent initializes. getAuthStatus (webviewReady →
     // pushInitialState) can run before the first agent, and AuthService falls
@@ -191,7 +267,7 @@ export class AgentBridge {
   // ── Public API ────────────────────────────────────────────────
 
   async handleRequest(
-    method: string,
+    method: RequestMethod,
     params: unknown,
     sessionId?: string,
   ): Promise<unknown> {
@@ -201,11 +277,28 @@ export class AgentBridge {
       case "initialize":
         return this.initialize(p as unknown as InitializeParams);
       case "destroy":
-        return this.destroy(sessionId);
+        return this.destroy(sessionId, {
+          removeWorktree: p.removeWorktree === true,
+        });
       case "restoreSession":
         return this.restoreSession(p.sessionId as string, sessionId);
       case "listSessions":
         return this.listSessions(p.workdir as string | undefined, sessionId);
+      case "listAllSessions":
+        // Every project on this host (no session required) — the desktop's
+        // /resume picker lists sessions the app never created, so it cannot use
+        // the per-workdir listSessions.
+        return this.listAllSessions();
+      case "renameSession":
+        // Host-level like listAllSessions: the target session may have no live
+        // agent (the desktop renames sessions straight from its sidebar, and a
+        // restored one is not running), so the id/workdir come from the caller
+        // instead of the bound session.
+        return this.renameSession(
+          p.sessionId as string,
+          p.workdir as string,
+          p.title as string,
+        );
       case "getSessionInfo":
         return this.getSessionInfo(sessionId);
       case "listPendingPermissions":
@@ -233,6 +326,15 @@ export class AgentBridge {
       case "setModel":
         return this.setModel(p.model as string, sessionId);
 
+      // ── User preferences (global — user-level ~/.wave/settings.json) ──
+      // 设置页保存路径：用户偏好写文件后由 SDK 实时重载在各会话下一轮生效，
+      // 不经 updateConfig 当 AgentOptions 覆盖层下发（见 protocol.ts 注释）。
+      // 读回的是**生效值**（可能来自 Remote 组织下发/环境变量）+ 每键来源层。
+      case "getUserSettings":
+        return this.userSettingsView();
+      case "updateUserSettings":
+        return this.updateUserSettings(p as UserPreferenceSettings);
+
       // ── Messages ──
       case "sendMessage":
         return this.sendMessage(
@@ -267,10 +369,21 @@ export class AgentBridge {
       case "deleteQueuedMessageById":
         return this.deleteQueuedMessageById(p.id as string, sessionId);
       case "getMessages":
-        return this.getMessages(sessionId);
+        return this.getMessages(sessionId, {
+          before: p.before as string | undefined,
+          since: p.since 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.
+      case "remoteControlStatus":
+      case "remoteControlConnect":
+      case "remoteControlDisconnect":
+        return this.remoteControlRequest(method, p);
+
       // ── Permissions ──
       case "setPermissionMode":
         return this.setPermissionMode(p.mode as PermissionMode, sessionId);
@@ -346,6 +459,8 @@ export class AgentBridge {
         return this.login(p.serverUrl as string | undefined);
       case "logout":
         return this.logout();
+      case "installGitCredentialHelper":
+        return installGitCredentialHelper();
 
       // ── Memory files (settings UI — user-level ~/.wave/AGENTS.md and
       //    project-level <workdir>/AGENTS.md) ──
@@ -376,6 +491,7 @@ export class AgentBridge {
       case "uninstallPlugin":
         return this.uninstallPlugin(
           p.pluginId as string,
+          p.scope as Scope | undefined,
           p.workdir as string | undefined,
           sessionId,
         );
@@ -424,11 +540,25 @@ export class AgentBridge {
           p.workdir as string | undefined,
           sessionId,
         );
+      case "setPluginScope":
+        return this.setPluginScope(
+          p.pluginId as string,
+          p.scope as Scope,
+          p.workdir as string | undefined,
+          sessionId,
+        );
+      case "reloadPlugins":
+        return this.reloadPlugins();
       case "listMarketplaces":
         return this.listMarketplaces(
           p.workdir as string | undefined,
           sessionId,
         );
+      case "refreshMarketplaces":
+        return this.refreshMarketplaces(
+          p.workdir as string | undefined,
+          sessionId,
+        );
       case "addMarketplace":
         return this.addMarketplace(
           p.input as string,
@@ -468,7 +598,9 @@ export class AgentBridge {
       case "stopWorkflowRun":
         return this.stopWorkflowRun(p.runId as string, sessionId);
 
-      // ── Git / worktree (global — no session required) ──
+      // ── Filesystem / Git / worktree (global — no session required) ──
+      case "listDirectories":
+        return this.listDirectories(p.dir as string | undefined);
       case "listGitBranches":
         return this.listGitBranches(p.workdir as string | undefined);
       case "createWorktree":
@@ -483,6 +615,8 @@ export class AgentBridge {
         return this.getWorktreeChanges(
           p as unknown as { path?: string; baseBranch?: string },
         );
+      case "getSessionWorktreeChanges":
+        return this.getSessionWorktreeChanges(sessionId);
       case "removeWorktree":
         return this.removeWorktreeSession(
           p as unknown as {
@@ -492,16 +626,42 @@ export class AgentBridge {
             hookBased?: boolean;
           },
         );
+      case "getWorkspaceDiff":
+        return this.getWorkspaceDiff(
+          p.workdir as string | undefined,
+          p.commit as string | undefined,
+          p.scope as string | undefined,
+        );
+      case "getCompletion":
+        return this.getCompletion(
+          p as unknown as {
+            prefix?: string;
+            suffix?: string;
+            language?: string;
+            filePath?: string;
+          },
+          sessionId,
+        );
 
-      default:
+      default: {
+        // Type-level exhaustiveness, both directions: a union member without a
+        // `case` lands here as a non-`never` and fails to compile, and a `case`
+        // naming something outside the union fails to compile at the `case`
+        // itself. Runtime behaviour is unchanged — `method` can still be an
+        // arbitrary string once the transport boundary cast it.
+        const _exhaustive: never = method;
+        // Kept referenced so the witness isn't an unused-variable lint error;
+        // it is never read at runtime.
+        void _exhaustive;
         throw new RpcError(
           PROTOCOL_METHOD_NOT_FOUND,
           `Method not found: ${method}`,
         );
+      }
     }
   }
 
-  handleNotification(method: string, params: unknown): void {
+  handleNotification(method: ClientNotificationMethod, params: unknown): void {
     if (method === "permissionResponse") {
       const p = params as {
         requestId: string;
@@ -542,6 +702,16 @@ export class AgentBridge {
     const ctx: SessionContext = {};
     const callbacks = this.createCallbacks(ctx);
 
+    const entrypoint = normalizeEntrypoint(params.entrypoint);
+    if (params.entrypoint !== undefined && entrypoint === undefined) {
+      // A host that ships a value this version does not know (an older client,
+      // a hand-written frame) is treated as if it had declared nothing: an
+      // unrecognised value must not mint a series of its own.
+      logger?.warn(
+        `Unknown entrypoint: ${String(params.entrypoint)}, ignoring`,
+      );
+    }
+
     const options: AgentOptions = {
       callbacks,
       logger,
@@ -552,9 +722,6 @@ export class AgentBridge {
       defaultHeaders: params.defaultHeaders,
       model: params.model,
       fastModel: params.fastModel,
-      language: params.language,
-      autoMemoryEnabled: params.autoMemoryEnabled,
-      autoMemoryFrequency: params.autoMemoryFrequency,
       permissionMode: params.permissionMode,
       tools: params.tools,
       allowedTools: params.allowedTools,
@@ -563,6 +730,7 @@ export class AgentBridge {
       mcpServers: params.mcpServers,
       worktreeName: params.worktreeName,
       isNewWorktree: params.isNewWorktree,
+      entrypoint,
       canUseTool: (context: ToolPermissionContext) =>
         this.canUseTool(context, ctx),
     };
@@ -604,15 +772,133 @@ export class AgentBridge {
     };
   }
 
-  private async destroy(sessionId?: string): Promise<null> {
+  /**
+   * Destroy one hosted session (idempotent: an unknown id is a no-op).
+   *
+   * `params.removeWorktree` (optional, default false) additionally removes the
+   * git worktree the session was **created** in — the intent the remote page
+   * sends when the user confirms 「删除会话与工作树」. Two rules make it safe to
+   * offer over the remote channel, where the caller must never be able to name a
+   * path:
+   *
+   * 1. The worktree is resolved here, from `entry.createdWorkdir` — the same
+   *    anchor `wave daemon destroy --remove-worktree` resolves from (and for the
+   *    same reason: an in-session `cd` must not move the target). Nothing in the
+   *    request is trusted as a path, which is why the raw `removeWorktree`
+   *    method stays off the remote whitelist.
+   * 2. It runs **after** `agent.destroy()` resolves. The agent's cwd is the
+   *    worktree path and destroy flushes the session file (resolving that path
+   *    via realpath); deleting the directory first makes the save fail ENOENT
+   *    and drops the trailing messages — the desktop host carries the identical
+   *    ordering note in `handleDeleteSession`.
+   *
+   * "Cannot resolve a worktree" is never a reason to fail the delete: the
+   * session is still destroyed and the reply says `worktreeRemoved: false`. That
+   * covers a plain (non-worktree) session, a worktree that is already gone, and
+   * 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.
+   */
+  private async destroy(
+    sessionId?: string,
+    params?: { removeWorktree?: boolean },
+  ): Promise<{ worktreeRemoved: boolean }> {
+    let createdWorkdir: string | undefined;
     if (sessionId) {
       const entry = this.sessions.get(sessionId);
       if (entry) {
-        await entry.agent.destroy();
+        if (entry.transitioning) {
+          // A rebuild owns this entry (updateConfig): destroying it here would
+          // race the rebuild, which would then re-register a replacement for a
+          // session the caller just destroyed. Refuse loudly instead — the
+          // caller can retry once the reload settles.
+          throw new RpcError(
+            PROTOCOL_INTERNAL_ERROR,
+            `Session ${sessionId} is being reconfigured (config reload in progress), retry shortly`,
+          );
+        }
+        // Drop the registry entry BEFORE awaiting the teardown. Agent.destroy()
+        // aborts the in-flight turn, which pushes `loadingChange:false` — the
+        // exact notification a finished turn pushes — and the teardown itself is
+        // not instant (transcript save, subagent/mcp cleanup, auto-memory drain).
+        // A client blocked in `wait` that is woken by that push re-reads the
+        // registry for the verdict: with the entry still listed (isLoading now
+        // false) it settles as exit 0 on an intermediate snapshot — a false
+        // "finished" for a session that is being removed. With the entry gone the
+        // existence check wins and it reports "no longer exists" (exit 1).
+        // Removed first also means a throwing teardown cannot leave a
+        // half-destroyed agent listed (destroyAll() below clears the map first
+        // for the same reason).
         this.sessions.delete(sessionId);
+        createdWorkdir = entry.createdWorkdir;
+        await entry.agent.destroy();
       }
     }
-    return null;
+
+    let worktreeRemoved = false;
+    if (params?.removeWorktree === true && createdWorkdir) {
+      worktreeRemoved = await this.removeSessionWorktree(createdWorkdir);
+    }
+    return { worktreeRemoved };
+  }
+
+  /**
+   * Remove the linked worktree a session was created in. Returns whether the
+   * directory is actually gone (not whether we asked): `removeWorktree` is
+   * best-effort and leaves the directory behind when git and the fs fallback
+   * 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.
+   */
+  private async removeSessionWorktree(sessionDir: string): Promise<boolean> {
+    const worktree = deriveWorktreeInfo(sessionDir);
+    if (!worktree) return false;
+    try {
+      await removeWorktree({
+        name: "",
+        path: worktree.path,
+        branch: worktree.branch,
+        repoRoot: worktree.repoRoot,
+        hasUncommittedChanges: false,
+        hasNewCommits: false,
+        isNew: false,
+        hookBased: worktree.hookBased,
+      });
+    } catch (e) {
+      logger.warn(
+        `removeSessionWorktree: failed to remove ${worktree.path}: ${(e as Error).message}`,
+      );
+      return false;
+    }
+    return !existsSync(worktree.path);
+  }
+
+  /**
+   * What deleting a session's worktree would throw away (uncommitted files and
+   * commits not on the base branch) — the counts the delete confirmation names
+   * on the remote page.
+   *
+   * Session-scoped on purpose: the path comes from the session's own
+   * `createdWorkdir`, never from the caller. The remote channel carries this
+   * instead of the path-taking `getWorktreeChanges`, for the same reason it
+   * carries `destroy {removeWorktree}` instead of `removeWorktree` — a phone may
+   * only name a session it was given, not an arbitrary directory on the machine.
+   *
+   * `null` means "could not inspect" (not a worktree, already deleted, git
+   * failed), which the page renders as the generic warning rather than as
+   * "clean".
+   */
+  private async getSessionWorktreeChanges(
+    sessionId?: string,
+  ): Promise<{ files: number; commits: number } | null> {
+    const entry = this.requireSessionForRead(sessionId);
+    const worktree = deriveWorktreeInfo(entry.createdWorkdir);
+    if (!worktree) return null;
+    return getWorktreeChanges(worktree.path);
   }
 
   /**
@@ -633,15 +919,25 @@ export class AgentBridge {
     restoreId: string,
     sessionId?: string,
   ): Promise<null> {
-    const entry = this.requireSession(sessionId);
+    const entry = this.requireSessionForRead(sessionId);
     // Re-attach to a live session: the SDK restore would no-op (target is
-    // already current). Emit the current messages so the freshly attached
-    // client — whose router registered only after initialize returned and so
-    // missed any earlier notifications — gets a snapshot without replay.
+    // already current). Re-send the state the freshly attached client missed —
+    // its router registered only after initialize returned.
+    //
+    // `messagesChange` carries **no payload here, only the fact that the list
+    // changed**. Nobody ever read a full snapshot from it: the remote relay
+    // needs the emission to produce the phone's signal and then the phone pulls
+    // `getMessages({ since })` itself, while every IDE host ignores the method
+    // and calls `getMessages` after restore. So building one — a multi-MB list
+    // on a long session, serialized on a hot re-attach path — was pure cost, and
+    // this is why the bridge sends the signal shape instead.
+    //
+    // This is also the ONLY place the bridge emits `messagesChange`, and only on
+    // this re-attach branch — never as the message stream progresses.
     if (entry.agent.sessionId === restoreId) {
       this.emit(
         "messagesChange",
-        { messages: entry.agent.displayMessages },
+        remoteWire.messagesChangeSignal(),
         entry.agent.sessionId,
       );
       // The re-attached client also missed the loading state that settled
@@ -665,6 +961,18 @@ export class AgentBridge {
       this.emitContextUsage(entry.agent);
       return null;
     }
+    // The replay branch above is safe during an `updateConfig` transition (it
+    // only re-pushes the outgoing agent's own state, which is this session's
+    // transcript). A REAL restore is not: it would load another conversation
+    // into the agent that is about to be destroyed and replaced, so the call
+    // would be silently thrown away together with the outgoing agent. Refuse it
+    // with the same retryable error the mutating RPCs use.
+    if (entry.transitioning) {
+      throw new RpcError(
+        PROTOCOL_INTERNAL_ERROR,
+        `Session ${sessionId} is being reconfigured (config reload in progress), retry shortly`,
+      );
+    }
     await entry.agent.restoreSession(restoreId);
     // A real restore must also re-emit the usage unconditionally: the SDK
     // only fires onLatestTotalTokensChange on a VALUE CHANGE, so restoring a
@@ -685,9 +993,14 @@ export class AgentBridge {
    * usage to report; the host keeps the empty ring until the first push.
    */
   private emitContextUsage(agent: Agent): void {
-    const percent = this.contextUsagePercentOf(agent);
-    if (percent !== undefined) {
-      this.emit("contextUsage", { percent }, agent.sessionId);
+    const tokens = agent.latestTotalTokens;
+    const max = agent.getMaxInputTokens();
+    if (tokens > 0 && max > 0) {
+      this.emit(
+        "contextUsage",
+        remoteWire.contextUsage(tokens, max),
+        agent.sessionId,
+      );
     }
   }
 
@@ -702,7 +1015,7 @@ export class AgentBridge {
     const tokens = agent.latestTotalTokens;
     const max = agent.getMaxInputTokens();
     if (tokens > 0 && max > 0) {
-      return Math.min(100, Math.round((tokens / max) * 100));
+      return percentOf(tokens, max);
     }
     return undefined;
   }
@@ -717,8 +1030,84 @@ export class AgentBridge {
     return { sessions };
   }
 
+  /**
+   * All main sessions across every project directory of this host, newest
+   * first (deduplicated by session id). Each entry carries the session's real
+   * `workdir`, which is what a caller needs to resume it.
+   */
+  private async listAllSessions(): Promise<{ sessions: SessionMetadata[] }> {
+    const sessions = await listAllSessions();
+    return { sessions };
+  }
+
+  /**
+   * Set a session's user-visible title. Works for any session on this host —
+   * the target does not need to be the bound one, or even live.
+   */
+  private async renameSession(
+    sessionId: string,
+    workdir: string,
+    title: string,
+  ): Promise<void> {
+    // A session this host is running keeps the title in memory and writes it
+    // back at its next flush point (exit, compaction, resume, rewind), so a
+    // file-only write here would be clobbered by the stale in-memory value.
+    // Route through the agent; fall back to the file for sessions that are not
+    // bound to this host's process.
+    const bound = this.sessions.get(sessionId)?.agent;
+    if (bound) {
+      await bound.renameSession(title);
+      return;
+    }
+    await setSessionCustomTitle(sessionId, workdir, title);
+  }
+
   // ── Git / worktree ────────────────────────────────────────────
 
+  /**
+   * List the subdirectories of a directory on the machine this CLI runs on —
+   * host-agnostic like `listGitBranches`: whichever wave process receives the
+   * request lists its own filesystem. Serves the new-session directory pickers
+   * (the desktop's remote host browser and the Web page now share this one
+   * implementation; the desktop's ssh shell one-liner retires into it).
+   *
+   * `~` / `~/…` expand against the service process user's home. `resolvedPath`
+   * is the realpath so the picker shows where the user actually is (symlinked
+   * parents normalized). Symlinked subdirectories are NOT listed — the shell
+   * `find -type d` this replaces didn't list them either, and the two paths
+   * must stay interchangeable. A missing or unreadable directory is an explicit
+   * error, never an empty list (an empty list would read as "no subdirs" and
+   * strand the user on a path they can't leave).
+   */
+  private listDirectories(dir?: string): {
+    resolvedPath: string;
+    dirs: string[];
+  } {
+    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;
+    try {
+      resolvedPath = realpathSync(expanded);
+    } catch {
+      throw new RpcError(PROTOCOL_INTERNAL_ERROR, `目录不存在或不可读：${dir}`);
+    }
+    let dirs: string[];
+    try {
+      dirs = readdirSync(resolvedPath, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name)
+        .sort((a, b) => a.localeCompare(b));
+    } catch {
+      // realpath succeeded (the path exists) but reading it didn't — same
+      // verdict as missing: the picker cannot descend into either.
+      throw new RpcError(PROTOCOL_INTERNAL_ERROR, `目录不存在或不可读：${dir}`);
+    }
+    return { resolvedPath, dirs };
+  }
+
   private listGitBranches(workdir?: string): {
     branches: string[];
     current: string | null;
@@ -765,6 +1154,66 @@ export class AgentBridge {
     return { branches, current };
   }
 
+  /**
+   * Read-only workspace diff for the desktop diff panel. Runs wherever this
+   * CLI runs, so a remote session answers it inside the remote daemon instead
+   * of the desktop shelling out over ssh per git command.
+   *
+   * `scope` selects the viewing range: omitted / "all" = the fork-point base,
+   * "uncommitted" = `HEAD` (the panel's "未提交改动"). A `commit` outranks it.
+   */
+  private getWorkspaceDiff(workdir?: string, commit?: string, scope?: string) {
+    if (!workdir) {
+      throw new RpcError(PROTOCOL_INTERNAL_ERROR, "workdir is required");
+    }
+    return getWorkspaceDiff(workdir, {
+      ...(commit ? { commit } : {}),
+      ...(scope === "uncommitted" ? { uncommitted: true } : {}),
+    });
+  }
+
+  /**
+   * One inline (ghost-text) completion for the editor plugins.
+   *
+   * Session-scoped on purpose: the completion model and the gateway credentials
+   * are resolved inside that session (the CLI owns the model configuration —
+   * the plugin never holds a second source of truth). Read-only, so it keeps
+   * working while `updateConfig` is rebuilding the session.
+   */
+  private async getCompletion(
+    params: {
+      prefix?: string;
+      suffix?: string;
+      language?: string;
+      filePath?: string;
+    },
+    sessionId?: string,
+  ): Promise<{ text: string; model: string }> {
+    const entry = this.requireSessionForRead(sessionId);
+    const key = sessionId as string;
+
+    // Supersede the session's previous request: its answer would land at a
+    // cursor position that no longer exists.
+    this.inFlightCompletions.get(key)?.abort();
+    const controller = new AbortController();
+    this.inFlightCompletions.set(key, controller);
+
+    try {
+      return await entry.agent.getCompletion({
+        prefix: params.prefix ?? "",
+        suffix: params.suffix ?? "",
+        ...(params.language ? { language: params.language } : {}),
+        ...(params.filePath ? { filePath: params.filePath } : {}),
+        abortSignal: controller.signal,
+      });
+    } finally {
+      // Only clear our own slot — a newer request may already own it.
+      if (this.inFlightCompletions.get(key) === controller) {
+        this.inFlightCompletions.delete(key);
+      }
+    }
+  }
+
   private async createWorktreeSession(params: {
     workdir: string;
     baseBranch?: string;
@@ -850,14 +1299,19 @@ export class AgentBridge {
     return { ok: true };
   }
 
-  private getSessionInfo(sessionId?: string): {
+  private async getSessionInfo(sessionId?: string): Promise<{
     sessionId: string;
     workingDirectory: string;
     latestTotalTokens: number;
     permissionMode: PermissionMode;
     availableTools: string[];
-  } {
-    const entry = this.requireSession(sessionId);
+    tasks: Task[];
+    isCompacting: boolean;
+    isCommandRunning: boolean;
+    queuedMessages: QueuedMessage[];
+    backgroundTasks: BackgroundTaskSummary[];
+  }> {
+    const entry = this.requireSessionForRead(sessionId);
     return {
       sessionId: entry.agent.sessionId,
       // The recorded creation workdir, not the live agent.workingDirectory:
@@ -867,6 +1321,23 @@ export class AgentBridge {
       latestTotalTokens: entry.agent.latestTotalTokens,
       permissionMode: entry.agent.getPermissionMode(),
       availableTools: entry.agent.getAvailableToolNames(),
+      // The session-state family the remote page re-reads (spec
+      // remote-control「Web 页作为第五种宿主」场景 26): the todo list —
+      // file-backed in the SDK, hence the await — plus compaction, command
+      // running and the outbound queue, all read off the agent itself so the
+      // reply is the current value, never a transition the page may have
+      // missed.
+      tasks: await entry.agent.getTasks(),
+      isCompacting: entry.agent.isCompacting,
+      isCommandRunning: entry.agent.isCommandRunning,
+      queuedMessages: entry.agent.queuedMessages,
+      // Background tasks join the family for the same reason the todo list is
+      // here: the phone's `/tasks` dialog opens on whatever the machine holds, and
+      // `backgroundTasksChange` only reports *changes* — a task that started
+      // before the page attached would otherwise be invisible until it finished.
+      backgroundTasks: toBackgroundTaskSummaries(
+        entry.agent.getBackgroundTasks(),
+      ),
     };
   }
 
@@ -878,76 +1349,108 @@ export class AgentBridge {
     const currentSessionId = entry.agent.sessionId;
     // Merge new config into stored config
     entry.storedConfig = { ...entry.storedConfig, ...params };
-    // Destroy and recreate within the same session slot
-    await entry.agent.destroy();
-    this.sessions.delete(currentSessionId);
-
+    // The entry is NOT removed while the agent is replaced: dropping it would
+    // make a `wait` blocked on this session report "no longer exists" (exit 1)
+    // for a session that is alive and merely reloading — a false error, the same
+    // family as the false idle this whole change is about. Instead the entry is
+    // flagged `transitioning` for the whole destroy + recreate, which
+    // `listDaemonSessions` reports as `isLoading: true` (so no reader can see the
+    // "listed + not busy" combination a waiter would settle on) while
+    // state-changing RPCs refuse it (`requireSession`) instead of talking to the
+    // outgoing, dying agent. Read-only RPCs keep working off that agent.
+    entry.transitioning = true;
     const ctx: SessionContext = {};
-    const callbacks = this.createCallbacks(ctx);
-    const options: AgentOptions = {
-      callbacks,
-      workdir: entry.storedConfig.workdir,
-      restoreSessionId: currentSessionId,
-      apiKey: entry.storedConfig.apiKey,
-      baseURL: entry.storedConfig.baseURL,
-      defaultHeaders: entry.storedConfig.defaultHeaders,
-      model: entry.storedConfig.model,
-      fastModel: entry.storedConfig.fastModel,
-      language: entry.storedConfig.language,
-      autoMemoryEnabled: entry.storedConfig.autoMemoryEnabled,
-      autoMemoryFrequency: entry.storedConfig.autoMemoryFrequency,
-      permissionMode: entry.storedConfig.permissionMode,
-      tools: entry.storedConfig.tools,
-      allowedTools: entry.storedConfig.allowedTools,
-      disallowedTools: entry.storedConfig.disallowedTools,
-      plugins: entry.storedConfig.pluginDirs?.map((p) => ({
-        type: "local",
-        path: p,
-      })),
-      mcpServers: entry.storedConfig.mcpServers,
-      // Keep worktree context (permission safety) across recreation, but never
-      // re-fire WorktreeCreate — the hook ran at initial creation.
-      worktreeName: entry.storedConfig.worktreeName,
-      canUseTool: (context: ToolPermissionContext) =>
-        this.canUseTool(context, ctx),
-    };
-
-    let agent: Agent;
     try {
-      agent = await Agent.create(options);
-    } catch (createError) {
-      // The old entry was already destroyed and removed above. If the session
-      // file is missing or unrecoverable (fresh session, cleared chat, or a
-      // never-persisted empty session), fail soft: recreate WITHOUT
-      // restoreSessionId so this session slot keeps working. Without this the
-      // client's sessionId still points at the destroyed entry and every later
-      // request fails with "Session not found" until the window is reloaded.
-      // Non-session errors (bad baseURL/apiKey/config) must surface unchanged.
-      if (!options.restoreSessionId || !isSessionRecoveryError(createError)) {
-        throw createError;
+      // Destroy and recreate within the same session slot. The destroy comes
+      // first so the outgoing agent stops writing the transcript before the
+      // replacement loads it.
+      await entry.agent.destroy();
+
+      const callbacks = this.createCallbacks(ctx);
+      const options: AgentOptions = {
+        callbacks,
+        workdir: entry.storedConfig.workdir,
+        restoreSessionId: currentSessionId,
+        apiKey: entry.storedConfig.apiKey,
+        baseURL: entry.storedConfig.baseURL,
+        defaultHeaders: entry.storedConfig.defaultHeaders,
+        model: entry.storedConfig.model,
+        fastModel: entry.storedConfig.fastModel,
+        permissionMode: entry.storedConfig.permissionMode,
+        tools: entry.storedConfig.tools,
+        allowedTools: entry.storedConfig.allowedTools,
+        disallowedTools: entry.storedConfig.disallowedTools,
+        plugins: entry.storedConfig.pluginDirs?.map((p) => ({
+          type: "local",
+          path: p,
+        })),
+        mcpServers: entry.storedConfig.mcpServers,
+        // Keep worktree context (permission safety) across recreation, but never
+        // re-fire WorktreeCreate — the hook ran at initial creation.
+        worktreeName: entry.storedConfig.worktreeName,
+        // The declaration outlives the rebuild: an `updateConfig` replaces the
+        // agent, not the host that asked for the session.
+        entrypoint: normalizeEntrypoint(entry.storedConfig.entrypoint),
+        canUseTool: (context: ToolPermissionContext) =>
+          this.canUseTool(context, ctx),
+      };
+
+      let agent: Agent;
+      try {
+        agent = await Agent.create(options);
+      } catch (createError) {
+        // The old agent is already destroyed. If the session file is missing or
+        // unrecoverable (fresh session, cleared chat, or a never-persisted empty
+        // session), fail soft: recreate WITHOUT restoreSessionId so this session
+        // slot keeps working. Without this the client's sessionId still points at
+        // the destroyed entry and every later request fails with "Session not
+        // found" until the window is reloaded. Non-session errors (bad
+        // baseURL/apiKey/config) must surface unchanged.
+        if (!options.restoreSessionId || !isSessionRecoveryError(createError)) {
+          throw createError;
+        }
+        logger?.warn(
+          `updateConfig: failed to restore session ${currentSessionId}, recreating as a fresh session:`,
+          createError,
+        );
+        agent = await Agent.create({ ...options, restoreSessionId: undefined });
       }
-      logger?.warn(
-        `updateConfig: failed to restore session ${currentSessionId}, recreating as a fresh session:`,
-        createError,
-      );
-      agent = await Agent.create({ ...options, restoreSessionId: undefined });
+      ctx.agent = agent;
+      ctx.registeredSessionId = agent.sessionId;
+      entry.agent = agent;
+      // A recovery-recreated session gets a NEW id: move the registry key with it.
+      // (The entry object is reused, so the flag and the recorded creation workdir
+      // survive either way.) Announced with the OLD id as the envelope — same
+      // contract as `onSessionIdChange` — so a client blocked on this session can
+      // rebind to the new id instead of concluding it disappeared.
+      if (agent.sessionId !== currentSessionId) {
+        this.emit(
+          "sessionIdChange",
+          { sessionId: agent.sessionId },
+          currentSessionId,
+        );
+        this.sessions.delete(currentSessionId);
+        this.sessions.set(agent.sessionId, entry);
+      }
+      entry.transitioning = false;
+      return { sessionId: agent.sessionId };
+    } catch (teardownError) {
+      // Nothing usable is left: the outgoing agent is torn down (fully or
+      // partially) and no replacement was built. Leaving the entry listed would
+      // be a "half-dead" session — reachable through the registry but with no
+      // working agent — so it is dropped, exactly like a failing `destroy`: a
+      // waiter then reports "no longer exists" (exit 1) instead of hanging or
+      // settling. The error surfaces to the caller unchanged.
+      this.sessions.delete(currentSessionId);
+      throw teardownError;
     }
-    ctx.agent = agent;
-    ctx.registeredSessionId = agent.sessionId;
-    this.sessions.set(agent.sessionId, {
-      agent,
-      storedConfig: { ...entry.storedConfig },
-      createdWorkdir: entry.createdWorkdir,
-    });
-
-    return { sessionId: agent.sessionId };
   }
 
   private getConfiguredModels(sessionId?: string): {
     models: string[];
     currentModel: string | undefined;
   } {
-    const entry = this.requireSession(sessionId);
+    const entry = this.requireSessionForRead(sessionId);
     return {
       models: entry.agent.getConfiguredModels(),
       currentModel: entry.agent.getModelConfig().model,
@@ -956,7 +1459,7 @@ export class AgentBridge {
 
   private async setModel(model: string, sessionId?: string): Promise<null> {
     const entry = this.requireSession(sessionId);
-    entry.agent.setModel(model);
+    await entry.agent.setModel(model);
     // Keep storedConfig in sync: updateConfig recreates the agent from
     // storedConfig, so without this a later config save would revert the
     // model chosen here.
@@ -964,6 +1467,47 @@ export class AgentBridge {
     return null;
   }
 
+  // ── User preferences ──────────────────────────────────────────
+
+  /**
+   * 设置页保存路径：写用户级 `~/.wave/settings.json` 后，**显式重载本进程内
+   * 全部会话**的实时配置。
+   *
+   * 不能只依赖文件监视：会话启动时该文件（乃至 `~/.wave` 目录）通常还不存在，
+   * 监视要靠在父目录链存在的前提下补发事件；而这个文件正是被本次保存**创建**
+   * 出来的最常见场景（全新安装的第一次保存，spec core/agent-config.md
+   * 「设置实时重载」场景 7）。写完即重载使「保存 ⇒ 下一轮生效」与监视是否就绪
+   * 无关；监视若也命中，重载是幂等的（并发重载按 `reloadInProgress` 去重）。
+   *
+   * 空载荷（无差异保存、只回读）不落盘，也不重载。
+   *
+   * 回包是**生效视图**（同 `getUserSettings`）：设置页在保存后仍须看到「被组织
+   * 配置覆盖」的键的生效值与来源，而不是回退成用户文件里的值。
+   */
+  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();
+  }
+
+  /**
+   * 用户偏好的**生效视图**：生效值 + 每键来源层（用户级文件 / Remote 组织下发 /
+   * 机器环境变量 / 默认）。设置页据此把「由组织配置管理」的键显示为生效值 +
+   * 置灰（spec core/agent-config.md 边界说明「用户偏好的层与来源」）。
+   */
+  private userSettingsView(): UserPreferenceSettingsView {
+    const { values, sources } = readUserPreferenceView();
+    return { ...values, preferenceSources: sources };
+  }
+
   // ── Messages ──────────────────────────────────────────────────
 
   private async sendMessage(
@@ -1104,7 +1648,7 @@ export class AgentBridge {
   private async listRewindCheckpoints(sessionId?: string): Promise<{
     checkpoints: Array<{ id: string; content: string }>;
   }> {
-    const entry = this.requireSession(sessionId);
+    const entry = this.requireSessionForRead(sessionId);
     const { messages } = await entry.agent.getFullMessageThread();
     // 压缩 append-only 后同 id 消息在磁盘完整线程中重复出现（压缩前历史 +
     // 压缩后 append 的重复）。按 id 去重并保留最后一次出现（与折叠后的
@@ -1147,22 +1691,71 @@ export class AgentBridge {
     return null;
   }
 
-  private getMessages(sessionId?: string): {
+  /**
+   * Read a session's display messages.
+   *
+   * With no window this returns the whole list — that is the contract every
+   * existing host relies on (VS Code / JetBrains / desktop call `getMessages`
+   * with no parameters and must keep seeing the full thread, byte for byte).
+   * The window exists for remote clients on a phone, which only ever want the
+   * tail of a long conversation and must not be handed 13 MB on every cold
+   * start:
+   *
+   * - `limit`  — page size.
+   * - `before` — the page that ends immediately before the given message id
+   *              (paging *backwards* into history).
+   * - `since`  — everything appended after the given message id (catching up
+   *              after a reconnect).
+   *
+   * `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 the tail instead of guessing.
+   *
+   * Ids can repeat in the display list (a compacted message is re-added), so
+   * anchors are resolved to their **last** occurrence: "after `since`" means
+   * after the newest copy the caller could have seen.
+   */
+  private getMessages(
+    sessionId?: string,
+    window?: { before?: string; since?: string; limit?: number },
+  ): {
     messages: Message[];
     contextUsagePercent?: number;
+    /** Older messages exist before the returned page. */
+    hasMore?: boolean;
+    /** The `since` anchor is gone — rebuild from the tail. */
+    reset?: boolean;
+    /** Total display messages held for the session. */
+    total?: number;
   } {
-    const entry = this.requireSession(sessionId);
-    return {
-      messages: entry.agent.displayMessages,
-      contextUsagePercent: this.contextUsagePercentOf(entry.agent),
-    };
+    const entry = this.requireSessionForRead(sessionId);
+    const all = entry.agent.displayMessages;
+    const contextUsagePercent = this.contextUsagePercentOf(entry.agent);
+
+    // The slicing is shared with the CLI front end (`RemoteControlCliHost`): the
+    // phone's reconciliation rules belong to the wire contract, not to this
+    // registry, and the two hosts must answer identically.
+    let sliced: MessageWindowResult | undefined;
+    try {
+      sliced = sliceMessageWindow(all, window);
+    } catch (err) {
+      if (err instanceof InvalidMessageWindowError) {
+        throw new RpcError(PROTOCOL_INVALID_PARAMS, err.message);
+      }
+      throw err;
+    }
+    if (!sliced) return { messages: all, contextUsagePercent };
+    return { ...sliced, contextUsagePercent };
   }
 
   private async getFullMessageThread(sessionId?: string): Promise<{
     messages: Message[];
     sessionIds: string[];
   }> {
-    const entry = this.requireSession(sessionId);
+    const entry = this.requireSessionForRead(sessionId);
     return entry.agent.getFullMessageThread();
   }
 
@@ -1181,7 +1774,7 @@ export class AgentBridge {
     taskId: string,
     sessionId?: string,
   ): { output: ReturnType<Agent["getBackgroundTaskOutput"]> } {
-    const entry = this.requireSession(sessionId);
+    const entry = this.requireSessionForRead(sessionId);
     return { output: entry.agent.getBackgroundTaskOutput(taskId) };
   }
 
@@ -1203,7 +1796,7 @@ export class AgentBridge {
   private async getWorkflowRuns(
     sessionId?: string,
   ): Promise<{ runs: SerializableWorkflowRun[] }> {
-    const entry = this.requireSession(sessionId);
+    const entry = this.requireSessionForRead(sessionId);
     const runs = await entry.agent.getWorkflowRuns();
     return {
       runs: runs.map((r) => {
@@ -1235,7 +1828,7 @@ export class AgentBridge {
   }
 
   private getPermissionMode(sessionId?: string): { mode: PermissionMode } {
-    const entry = this.requireSession(sessionId);
+    const entry = this.requireSessionForRead(sessionId);
     return { mode: entry.agent.getPermissionMode() };
   }
 
@@ -1249,7 +1842,7 @@ export class AgentBridge {
     path: string | null;
     content: string | null;
   }> {
-    const entry = this.requireSession(sessionId);
+    const entry = this.requireSessionForRead(sessionId);
     const agent = entry.agent;
     const planPath =
       agent.getPlanFilePath() ?? (await agent.awaitPlanFilePath());
@@ -1268,7 +1861,7 @@ export class AgentBridge {
   // ── MCP ───────────────────────────────────────────────────────
 
   private getMcpServers(sessionId?: string): { servers: McpServerStatus[] } {
-    const entry = this.requireSession(sessionId);
+    const entry = this.requireSessionForRead(sessionId);
     return { servers: entry.agent.getMcpServers() };
   }
 
@@ -1304,7 +1897,7 @@ export class AgentBridge {
     userPath: string | null;
     projectPath: string | null;
   } {
-    const entry = this.requireSession(sessionId);
+    const entry = this.requireSessionForRead(sessionId);
     return {
       userPath: entry.agent.getUserMcpConfigPath(),
       projectPath: entry.agent.getProjectMcpConfigPath(),
@@ -1314,19 +1907,19 @@ export class AgentBridge {
   // ── Commands ──────────────────────────────────────────────────
 
   private getSlashCommands(sessionId?: string): { commands: SlashCommand[] } {
-    const entry = this.requireSession(sessionId);
+    const entry = this.requireSessionForRead(sessionId);
     return { commands: entry.agent.getSlashCommands() };
   }
 
   private getSubagentConfigurations(sessionId?: string): {
     configurations: SubagentConfiguration[];
   } {
-    const entry = this.requireSession(sessionId);
+    const entry = this.requireSessionForRead(sessionId);
     return { configurations: entry.agent.getSubagentConfigurations() };
   }
 
   private getSkillMetadata(sessionId?: string): { skills: SkillMetadata[] } {
-    const entry = this.requireSession(sessionId);
+    const entry = this.requireSessionForRead(sessionId);
     return { skills: entry.agent.getSkillMetadata() };
   }
 
@@ -1355,7 +1948,7 @@ export class AgentBridge {
     hooks: Partial<Record<string, unknown[]>>;
     configPath: string | null;
   }> {
-    const entry = this.requireSession(sessionId);
+    const entry = this.requireSessionForRead(sessionId);
     const hooks = await entry.agent.getHooksByScope(scope);
     // 回带该 scope 钩子所在 settings.json 的绝对路径（宿主 GUI 打开文件用；
     // plugin 钩子来自代码而非配置文件 → null）。
@@ -1462,7 +2055,7 @@ export class AgentBridge {
       });
       this.emit(
         "permissionRequest",
-        { requestId, context },
+        remoteWire.permissionRequest(requestId, context),
         ctx.registeredSessionId,
       );
     });
@@ -1492,27 +2085,156 @@ export class AgentBridge {
   /** Daemon list: expose the in-memory session registry (live sessions only,
    * not disk-scanning). Registration order is preserved. The working directory
    * shown is the session's recorded creation workdir (stable identity), not the
-   * live value that drifts with in-session `cd`. */
+   * live value that drifts with in-session `cd`.
+   *
+   * A session mid-rebuild (`transitioning`, see `SessionEntry`) reports
+   * `isLoading: true`: its outgoing agent has already been aborted by the
+   * teardown, so its own flag reads false while the replacement is still being
+   * built — reporting that would hand a `wait` the "listed + not busy"
+   * combination it settles on. "Not idle" is the honest reading of "this session
+   * has no agent right now", and it can only make a waiter wait.
+   *
+   * `hasRunningBackgroundWork` / `hasPendingMessages` are the other two halves of
+   * the idle predicate `wait` / `status` share with `wave -p` (print mode): a
+   * session whose foreground turn has ended can still own a running background
+   * bash task or subagent, and the last such task flips to `completed` before its
+   * completion notification is enqueued for the main agent's follow-up turn —
+   * reading only `isLoading` reports "done" in both cases. They are read from the
+   * live agent here rather than tracked separately, and mirror it as-is: the
+   * rebuild window above is already covered by `isLoading`, so there is no need
+   * to also claim a `transitioning` session owns background work it doesn't.
+   *
+   * The three label fields are additive (an older CLI simply ignores them) and
+   * exist for the remote-control page: it lists **this process's** sessions —
+   * the only ones it can actually open — and cannot read the machine's disk, so
+   * the title material and the ordering key have to come off the live agent
+   * rather than from `listSessions`, which reads jsonl and would offer it
+   * sessions that are not loaded here (spec remote-control「Web 页作为第五种宿主」
+   * 场景 2）。 */
   private listDaemonSessions(): {
     sessions: Array<{
       sessionId: string;
       workingDirectory: string;
       isLoading: boolean;
+      hasRunningBackgroundWork: boolean;
+      hasPendingMessages: boolean;
       messageCount: number;
+      /** User-set title; wins over `firstMessage` in the UI. */
+      customTitle?: string;
+      /** First real user message — the label when no custom title is set. */
+      firstMessage?: string;
+      /** Last display message's timestamp: the session list's ordering key. */
+      lastActiveAt?: string;
+      /**
+       * The linked git worktree this session was created in, when it was.
+       * Present only for worktree sessions — absent means "not a worktree, or
+       * cannot tell", and the remote page reads it as "deleting this session
+       * will not touch a worktree". Change counts are deliberately NOT here:
+       * they cost git calls per row, and the list is rebuilt on every reconnect
+       * / snapshot / page open. The page asks for them on demand instead, via
+       * `getSessionWorktreeChanges`.
+       */
+      worktree?: {
+        path: string;
+        branch: string;
+        repoRoot: string;
+        hookBased: boolean;
+      };
     }>;
   } {
     return {
-      sessions: [...this.sessions.entries()].map(([sessionId, entry]) => ({
-        sessionId,
-        workingDirectory: entry.createdWorkdir,
-        isLoading: entry.agent.isLoading,
-        messageCount: entry.agent.displayMessages.length,
-      })),
+      sessions: [...this.sessions.entries()].map(([sessionId, entry]) => {
+        const messages = entry.agent.displayMessages;
+        const customTitle = entry.agent.customTitle;
+        const firstMessage = firstUserText(messages);
+        const lastActiveAt = messages[messages.length - 1]?.timestamp;
+        // Derived from the creation workdir (not the live one) and fs-only —
+        // see `deriveWorktreeInfo` for why this must not shell out to git.
+        const worktree = deriveWorktreeInfo(entry.createdWorkdir);
+        return {
+          sessionId,
+          workingDirectory: entry.createdWorkdir,
+          isLoading: entry.transitioning === true || entry.agent.isLoading,
+          hasRunningBackgroundWork: entry.agent.hasRunningBackgroundWork,
+          hasPendingMessages: entry.agent.hasPendingMessages,
+          messageCount: messages.length,
+          ...(customTitle ? { customTitle } : {}),
+          ...(firstMessage ? { firstMessage } : {}),
+          ...(lastActiveAt ? { lastActiveAt } : {}),
+          ...(worktree ? { worktree } : {}),
+        };
+      }),
     };
   }
 
-  // ── Auth (global) ────────────────────────────────────────────
+  /**
+   * Route the `remoteControl*` RPCs to the daemon's controller.
+   *
+   * `connect` / `disconnect` change the relay session; all three return the
+   * same snapshot so a caller can render the result without a second round
+   * trip (and a caller that only wanted to read gets `remoteControlStatus`).
+   *
+   * `connect` carries the optional label the user gave this machine
+   * (`wave remote-control on <name>`), which the relay hands to the phone so
+   * its computer list can tell two of the user's computers apart.
+   */
+  private remoteControlRequest(
+    method: string,
+    params: Record<string, unknown>,
+  ): RemoteControlSnapshot {
+    const controller = this.remoteControl?.();
+    if (!controller) {
+      throw new RpcError(
+        PROTOCOL_INVALID_PARAMS,
+        "Remote control is not enabled on this process (set enableRemoteControl: true).",
+      );
+    }
+    if (method === "remoteControlConnect") {
+      const name = typeof params.name === "string" ? params.name : undefined;
+      controller.connect(name);
+    } else if (method === "remoteControlDisconnect") {
+      controller.disconnect();
+    }
+    return controller.getSnapshot();
+  }
+
+  /**
+   * Per-session status for the remote-control signal.
+   *
+   * The relay forwards bytes without looking inside them, so it can never
+   * discover that somebody is waiting on an approval — and "push to the phone
+   * when a session is stuck on the user" is the whole point of the feature.
+   * The machine therefore reports one word per session, carrying no content:
+   * ids and a status, nothing else.
+   *
+   * `running` includes background work: read from a phone there is no terminal
+   * to glance at, so "something is still in flight" is the useful meaning of
+   * busy rather than the narrower "a model turn is streaming".
+   */
+  listSessionStatuses(): Array<{
+    sessionId: string;
+    status: "running" | "idle" | "requires_action";
+  }> {
+    const awaiting = new Set<string>();
+    for (const entry of this.pendingPermissions.values()) {
+      if (entry.sessionId) awaiting.add(entry.sessionId);
+    }
+    return [...this.sessions.entries()].map(([sessionId, entry]) => {
+      let status: "running" | "idle" | "requires_action" = "idle";
+      if (awaiting.has(sessionId)) {
+        status = "requires_action";
+      } else if (
+        entry.transitioning === true ||
+        entry.agent.isLoading ||
+        entry.agent.hasRunningBackgroundWork
+      ) {
+        status = "running";
+      }
+      return { sessionId, status };
+    });
+  }
 
+  // ── Auth (global) ────────────────────────────────────────────
   private async getAuthStatus(): Promise<{
     isAuthenticated: boolean;
     user: { id: string; email?: string } | undefined;
@@ -1528,7 +2250,12 @@ export class AgentBridge {
   }
 
   private async getAccountInfo(): Promise<{
-    plan?: { monthlyQuota: number; months: number; used: number } | null;
+    /**
+     * 计费结论（套餐两根条 + 到期日 + 降级原因），形状见 codechat `GET /api/v1/account` → `billing`
+     * （判定出自与 proxy 扣费同一份代码）。本层只转发、不解析；具体形状由 wave-webview-fixtures
+     * 的 AccountBillingInfo 在宿主/卡片侧约束。
+     */
+    billing?: unknown;
     apiQuota?: { limit: number | null; used: number } | null;
   }> {
     const authService = AuthService.getInstance();
@@ -1547,7 +2274,7 @@ export class AgentBridge {
       throw new Error(`Account query failed (${response.status})`);
     }
     return (await response.json()) as {
-      plan?: { monthlyQuota: number; months: number; used: number } | null;
+      billing?: unknown;
       apiQuota?: { limit: number | null; used: number } | null;
     };
   }
@@ -1678,6 +2405,7 @@ export class AgentBridge {
           marketplace: p.marketplace,
           installed: p.installed,
           version: p.version,
+          latestVersion: p.latestVersion,
           enabled: mergedEnabled[pluginId] !== false,
           scope: p.scope,
         };
@@ -1699,10 +2427,14 @@ export class AgentBridge {
 
   private async uninstallPlugin(
     pluginId: string,
+    scope?: Scope,
     workdir?: string,
     sessionId?: string,
   ) {
-    await this.getPluginCore(workdir, sessionId).uninstallPlugin(pluginId);
+    await this.getPluginCore(workdir, sessionId).uninstallPlugin(
+      pluginId,
+      scope,
+    );
     return null;
   }
 
@@ -1727,6 +2459,21 @@ export class AgentBridge {
     );
   }
 
+  /**
+   * `/reload-plugins`：把磁盘上的插件状态就地换装进**本进程内全部活跃会话**
+   * （spec ecosystem/plugin.md「插件变更的就地重载」）。不重建会话、sessionId
+   * 不变；没有活跃会话时也返回成功——新会话创建时会按磁盘状态自然装载。
+   *
+   * 每个会话读的是同一份磁盘状态，因此取任一份结果汇报即可（各会话的差异只体现
+   * 在各自注册表的可见性上）。失败不回滚，原样回传给宿主提示。
+   */
+  private async reloadPlugins(): Promise<PluginReloadResult> {
+    const results = await Promise.all(
+      [...this.sessions.values()].map((entry) => entry.agent.reloadPlugins()),
+    );
+    return results[0] ?? { plugins: [], failures: [] };
+  }
+
   private async getProjectSettings(
     workdir?: string,
     sessionId?: string,
@@ -1839,10 +2586,36 @@ export class AgentBridge {
     return this.getPluginCore(workdir, sessionId).updatePlugin(pluginId);
   }
 
+  /**
+   * 更换已安装插件的安装作用域（设置页插件市场）：清掉各作用域的启用记录后
+   * 在目标作用域启用，因此旧作用域不再保留该插件。
+   */
+  private async setPluginScope(
+    pluginId: string,
+    scope: Scope,
+    workdir?: string,
+    sessionId?: string,
+  ) {
+    return this.getPluginCore(workdir, sessionId).setPluginScope(
+      pluginId,
+      scope,
+    );
+  }
+
   private async listMarketplaces(workdir?: string, sessionId?: string) {
     return this.getPluginCore(workdir, sessionId).listMarketplaces();
   }
 
+  /**
+   * 刷新各已注册市场的检出（不装插件），供「打开插件市场界面」时后台调用
+   * （spec 插件市场 A-013 场景 5）。市场级错误在 SDK 内静默记录，宿主侧失败
+   * 也不打断界面（场景 9）。
+   */
+  private async refreshMarketplaces(workdir?: string, sessionId?: string) {
+    await this.getPluginCore(workdir, sessionId).refreshMarketplaces();
+    return null;
+  }
+
   private async addMarketplace(
     input: string,
     scope?: Scope,
@@ -1867,8 +2640,16 @@ export class AgentBridge {
     workdir?: string,
     sessionId?: string,
   ) {
-    await this.getPluginCore(workdir, sessionId).updateMarketplace(name);
-    return null;
+    // 这个通道只服务 GUI 的「批量更新插件」按钮：按当前清单升级、不拉检出
+    // （清单刷新由打开视图时的 refreshMarketplaces 承担，spec 插件市场 A-013/
+    // 场景 14）。
+    const updated = await this.getPluginCore(
+      workdir,
+      sessionId,
+    ).updateMarketplacePlugins(name);
+    // 实际升级的插件数回给宿主：0 = 该市场已是最新（宿主据此提示，
+    // spec 插件市场场景 13）。
+    return { updated };
   }
 
   // ── Callbacks → Notifications ─────────────────────────────────
@@ -1893,26 +2674,29 @@ export class AgentBridge {
             ctx.registeredSessionId,
           );
       },
+      onAssistantMessageDiscarded: (messageId: string) => {
+        // A streamed attempt died mid-body and was re-issued without streaming,
+        // so its half message is void: tell the host to drop it instead of
+        // leaving a partial answer above the real one (spec: 流式响应正文中途
+        // 断连时降级为非流式重发).
+        this.emit(
+          "assistantMessageDiscarded",
+          { messageId },
+          ctx.registeredSessionId,
+        );
+      },
       onAssistantContentUpdated: (params) => {
         // Wire carries only the delta; consumers accumulate (spec: 流式通知纯增量负载).
         this.emit(
           "assistantContentUpdated",
-          {
-            messageId: params.messageId,
-            chunk: params.chunk,
-            stage: params.stage,
-          },
+          remoteWire.assistantContentUpdated(params),
           ctx.registeredSessionId,
         );
       },
       onAssistantReasoningUpdated: (params) => {
         this.emit(
           "assistantReasoningUpdated",
-          {
-            messageId: params.messageId,
-            chunk: params.chunk,
-            stage: params.stage,
-          },
+          remoteWire.assistantReasoningUpdated(params),
           ctx.registeredSessionId,
         );
       },
@@ -1920,21 +2704,23 @@ export class AgentBridge {
         // Streaming stages carry only the parametersChunk delta; start/running
         // (one-time snapshots) and end (authoritative full value) keep
         // `parameters` (spec: 流式通知纯增量负载).
-        const { parameters, ...rest } = params;
-        void parameters;
-        const wireParams = params.stage === "streaming" ? rest : params;
-        this.emit("toolBlockUpdated", wireParams, ctx.registeredSessionId);
+        this.emit(
+          "toolBlockUpdated",
+          remoteWire.toolBlockUpdated(params),
+          ctx.registeredSessionId,
+        );
       },
       onErrorBlockAdded: (error: string) => {
-        this.emit("errorBlockAdded", { error }, ctx.registeredSessionId);
+        this.emit(
+          "errorBlockAdded",
+          remoteWire.errorBlockAdded(error),
+          ctx.registeredSessionId,
+        );
       },
       onLoadingChange: (loading: boolean) => {
         this.emit(
           "loadingChange",
-          {
-            loading,
-            latestTotalTokens: ctx.agent?.latestTotalTokens,
-          },
+          remoteWire.loadingChange(loading, ctx.agent?.latestTotalTokens),
           ctx.registeredSessionId,
         );
       },
@@ -1946,8 +2732,11 @@ export class AgentBridge {
         // aligned with the CLI, which reads the same callback (spec 场景 5/6).
         const max = ctx.agent?.getMaxInputTokens() ?? 0;
         if (max > 0) {
-          const percent = Math.min(100, Math.round((tokens / max) * 100));
-          this.emit("contextUsage", { percent }, ctx.registeredSessionId);
+          this.emit(
+            "contextUsage",
+            remoteWire.contextUsage(tokens, max),
+            ctx.registeredSessionId,
+          );
         }
       },
       onCommandRunningChange: (running: boolean) => {
@@ -1964,21 +2753,9 @@ export class AgentBridge {
         this.emit("tasksChange", { tasks }, ctx.registeredSessionId);
       },
       onBackgroundTasksChange: (tasks: BackgroundTask[]) => {
-        const summaries: BackgroundTaskSummary[] = tasks.map((t) => ({
-          id: t.id,
-          type: t.type,
-          status: t.status,
-          startTime: t.startTime,
-          endTime: t.endTime,
-          command: t.command,
-          description: t.description,
-          exitCode: t.exitCode,
-          runtime: t.runtime,
-          outputPath: t.outputPath,
-        }));
         this.emit(
           "backgroundTasksChange",
-          { tasks: summaries },
+          { tasks: toBackgroundTaskSummaries(tasks) },
           ctx.registeredSessionId,
         );
       },
@@ -1997,7 +2774,11 @@ export class AgentBridge {
         ctx.registeredSessionId = newSessionId;
       },
       onPermissionModeChange: (mode: PermissionMode) => {
-        this.emit("permissionModeChange", { mode }, ctx.registeredSessionId);
+        this.emit(
+          "permissionModeChange",
+          remoteWire.permissionModeChange(mode),
+          ctx.registeredSessionId,
+        );
       },
       onWorkdirChange: (newCwd: string) => {
         this.emit(
@@ -2010,7 +2791,11 @@ export class AgentBridge {
         this.emit("mcpServersChange", { servers }, ctx.registeredSessionId);
       },
       onNotificationMessageAdded: (params) => {
-        const msg = ctx.agent?.displayMessages.find(
+        // 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
+        // mid-run, then notifies again when it finishes), and this callback
+        // fires for the message that was just appended — the newest one.
+        const matches = (ctx.agent?.displayMessages ?? []).filter(
           (m) =>
             m.role === "user" &&
             m.blocks.some(
@@ -2019,14 +2804,19 @@ export class AgentBridge {
                 (b as { taskId: string }).taskId === params.taskId,
             ),
         );
+        const msg = matches[matches.length - 1];
         this.emit(
           "notificationMessageAdded",
           { ...params, message: msg },
           ctx.registeredSessionId,
         );
       },
-      onCompactBlockAdded: (content: string) => {
-        this.emit("compactBlockAdded", { content }, ctx.registeredSessionId);
+      onCompactBlockAdded: (content: string, message?: Message) => {
+        this.emit(
+          "compactBlockAdded",
+          { content, message },
+          ctx.registeredSessionId,
+        );
       },
       onCompactionStateChange: (isCompacting: boolean) => {
         this.emit(
@@ -2042,6 +2832,9 @@ export class AgentBridge {
           ctx.registeredSessionId,
         );
       },
+      onPlanFileUpdated: (content: string) => {
+        this.emit("planFileUpdated", { content }, ctx.registeredSessionId);
+      },
     };
   }
 
@@ -2052,7 +2845,34 @@ export class AgentBridge {
 
   // ── Utils ─────────────────────────────────────────────────────
 
+  /**
+   * The session entry for a request that CHANGES session state. A session whose
+   * agent is mid-rebuild (`updateConfig` → `SessionEntry.transitioning`) has no
+   * usable agent: its outgoing one is being torn down, so a message injected into
+   * it would be lost and a config write would be overwritten by the rebuild's own
+   * stored config. Those requests are refused with a retryable error instead.
+   * Read-only requests use `requireSessionForRead` and stay available.
+   */
   private requireSession(sessionId?: string): SessionEntry {
+    const entry = this.requireSessionForRead(sessionId);
+    if (entry.transitioning) {
+      throw new RpcError(
+        PROTOCOL_INTERNAL_ERROR,
+        `Session ${sessionId} is being reconfigured (config reload in progress), retry shortly`,
+      );
+    }
+    return entry;
+  }
+
+  /**
+   * The session entry for a request that only READS. During a rebuild the entry
+   * holds the outgoing agent: its messages are this same session's transcript and
+   * its config is the pre-reload one, both of which are the best answer available
+   * for the few hundred milliseconds the rebuild takes. Refusing reads instead
+   * would turn a config reload into a burst of errors in whatever host happens to
+   * be polling (`getMcpServers`, `getSlashCommands`, …).
+   */
+  private requireSessionForRead(sessionId?: string): SessionEntry {
     if (!sessionId) {
       throw new RpcError(
         PROTOCOL_INTERNAL_ERROR,
@@ -2103,6 +2923,22 @@ function isSessionRecoveryError(error: unknown): boolean {
   );
 }
 
+/**
+ * The label a session list shows when no custom title is set: the first real
+ * user message. Same rule as the webview's `firstUserMessageText` — meta messages
+ * (task notifications and other injected turns) are skipped, because they are not
+ * what the user typed — so the phone labels a conversation the way the IDE hosts
+ * do.
+ */
+function firstUserText(messages: Message[]): string | undefined {
+  for (const message of messages) {
+    if (message.role !== "user" || message.isMeta) continue;
+    const text = getMessageContent(message).trim();
+    if (text) return text;
+  }
+  return undefined;
+}
+
 /** Read a text file, returning "" when it does not exist. */
 async function readTextFileSafe(filePath: string): Promise<string> {
   try {