wave-code 1.1.5 → 1.3.0

package/src/stdio/agentBridge.ts

@@ -31,8 +31,13 @@ import {
   type QueuedMessage,
   type SessionMetadata,
   type McpServerConfig,
+  type McpConfig,
   type Scope,
+  type PartialHookConfiguration,
+  isValidHookEvent,
   listSessions,
+  listAllSessions,
+  setSessionCustomTitle,
   searchFiles,
   generateRandomName,
   getDefaultRemoteBranch,
@@ -43,8 +48,16 @@ import {
   validateWorktreeRemovalPath,
   type SlashCommand,
   loadUserConfigEnv,
+  loadWaveConfigFromFile,
+  getUserConfigPaths,
+  getProjectConfigPaths,
+  readUserPreferenceView,
+  updateUserPreferenceSettings,
+  type UserPreferenceSettings,
+  type UserPreferenceSettingsView,
   type SubagentConfiguration,
   type SkillMetadata,
+  type PluginReloadResult,
 } from "wave-agent-sdk";
 import {
   type JsonRpcError,
@@ -53,10 +66,15 @@ import {
   METHOD_NOT_FOUND as PROTOCOL_METHOD_NOT_FOUND,
 } from "./protocol.js";
 import { execFileSync } from "node:child_process";
-import { mkdirSync, existsSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { basename, extname, join } from "node:path";
-import { createWorktree, removeWorktree } from "../utils/worktree.js";
+import { mkdirSync, existsSync, readFileSync, writeFileSync } 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,
+  getWorktreeChanges,
+  removeWorktree,
+} from "../utils/worktree.js";
 import { logger } from "../utils/logger.js";
 import { isUserCheckpointMessage } from "../utils/rewindCheckpoints.js";
 
@@ -68,6 +86,11 @@ export type NotificationEmitter = (
 
 export interface AgentBridgeOptions {
   emit: NotificationEmitter;
+  /** Daemon transport only (`wave daemon stop`/`restart`): invoked by the
+   * `shutdown` RPC after every session has been destroyed — the server tears
+   * down its socket and exits. stdio mode leaves it unset, so `shutdown` is
+   * "Method not found" there. */
+  onShutdownRequest?: () => void;
 }
 
 interface InitializeParams {
@@ -79,7 +102,6 @@ interface InitializeParams {
   defaultHeaders?: Record<string, string>;
   model?: string;
   fastModel?: string;
-  language?: string;
   permissionMode?: PermissionMode;
   tools?: string[];
   allowedTools?: string[];
@@ -90,6 +112,9 @@ interface InitializeParams {
   isNewWorktree?: boolean;
 }
 
+// 会话级覆盖项：用户偏好（语言 / 上下文长度 / 自动记忆开关与频率）不在此层——
+// 它们落用户级 ~/.wave/settings.json 经实时重载生效（getUserSettings /
+// updateUserSettings），走覆盖层会永久遮蔽 settings.json 的实时值。
 interface UpdateConfigParams {
   apiKey?: string;
   baseURL?: string;
@@ -97,7 +122,6 @@ interface UpdateConfigParams {
   defaultHeaders?: Record<string, string>;
   model?: string;
   fastModel?: string;
-  language?: string;
 }
 
 interface SearchFilesParams {
@@ -109,6 +133,34 @@ interface SearchFilesParams {
 interface SessionEntry {
   agent: Agent;
   storedConfig: Partial<InitializeParams>;
+  /**
+   * The workdir the session was CREATED in — an immutable identity, unlike the
+   * live `agent.workingDirectory`, which drifts as the session `cd`s (bash tool
+   * / worktree switches). Hosted-session consumers (destroy --remove-worktree's
+   * worktree resolution, list) read this instead of the live value so a session
+   * that moved out of its worktree into the main repo is still cleaned up at
+   * the right place. Recovered from the transcript's creation-time metadata
+   * 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;
 }
 
 /**
@@ -138,11 +190,13 @@ export class AgentBridge {
   >();
   private permissionCounter = 0;
   private emit: NotificationEmitter;
+  private onShutdownRequest: (() => void) | undefined;
   private pluginCore: PluginCore | undefined;
   private pluginCoreWorkdir: string | undefined;
 
   constructor(options: AgentBridgeOptions) {
     this.emit = options.emit;
+    this.onShutdownRequest = options.onShutdownRequest;
     // 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
@@ -172,12 +226,41 @@ export class AgentBridge {
         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":
         return this.listPendingPermissions();
       case "listDaemonSessions":
         return this.listDaemonSessions();
+      case "shutdown":
+        // Daemon-level graceful exit (`wave daemon stop` / `restart`): destroy
+        // every session first (each agent saves its transcript and drains
+        // auto-memory), then hand the process exit to the transport owner.
+        // Only the daemon registers the hook — stdio has no such concept.
+        if (!this.onShutdownRequest) {
+          throw new RpcError(
+            PROTOCOL_METHOD_NOT_FOUND,
+            "Method not found: shutdown",
+          );
+        }
+        await this.destroyAll();
+        this.onShutdownRequest();
+        return null;
       case "updateConfig":
         return this.updateConfig(p as unknown as UpdateConfigParams, sessionId);
       case "getConfiguredModels":
@@ -185,6 +268,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(
@@ -228,6 +320,8 @@ export class AgentBridge {
         return this.setPermissionMode(p.mode as PermissionMode, sessionId);
       case "getPermissionMode":
         return this.getPermissionMode(sessionId);
+      case "getPlanFile":
+        return this.getPlanFile(sessionId);
 
       // ── MCP ──
       case "getMcpServers":
@@ -236,6 +330,14 @@ export class AgentBridge {
         return this.connectMcpServer(p.serverName as string, sessionId);
       case "disconnectMcpServer":
         return this.disconnectMcpServer(p.serverName as string, sessionId);
+      case "removeMcpServer":
+        return this.removeMcpServer(
+          p.scope as "user" | "project",
+          p.serverName as string,
+          sessionId,
+        );
+      case "getMcpConfigPaths":
+        return this.getMcpConfigPaths(sessionId);
 
       // ── Commands ──
       case "getSlashCommands":
@@ -244,6 +346,21 @@ export class AgentBridge {
         return this.getSubagentConfigurations(sessionId);
       case "getSkillMetadata":
         return this.getSkillMetadata(sessionId);
+      case "deleteSkill":
+        return this.deleteSkill(p.name as string, sessionId);
+      case "deleteSubagent":
+        return this.deleteSubagent(p.name as string, sessionId);
+      case "getHooksByScope":
+        return this.getHooksByScope(
+          p.scope as "user" | "project" | "plugin",
+          sessionId,
+        );
+      case "deleteHook":
+        return this.deleteHook(
+          p.scope as "user" | "project",
+          p.hookName as string,
+          sessionId,
+        );
 
       // ── File / History (global — no session required) ──
       case "searchFiles":
@@ -267,11 +384,29 @@ export class AgentBridge {
       // ── Auth (global — no session required) ──
       case "getAuthStatus":
         return this.getAuthStatus();
+      case "getAccountInfo":
+        return this.getAccountInfo();
       case "login":
         return this.login(p.serverUrl as string | undefined);
       case "logout":
         return this.logout();
 
+      // ── Memory files (settings UI — user-level ~/.wave/AGENTS.md and
+      //    project-level <workdir>/AGENTS.md) ──
+      case "getAgentsContent":
+        return this.getAgentsContent(
+          p.scope as "user" | "project",
+          p.workdir as string | undefined,
+          sessionId,
+        );
+      case "setAgentsContent":
+        return this.setAgentsContent(
+          p.scope as "user" | "project",
+          p.content as string,
+          p.workdir as string | undefined,
+          sessionId,
+        );
+
       // ── Plugins (global — no session required) ──
       case "listPlugins":
         return this.listPlugins(p.workdir as string | undefined, sessionId);
@@ -285,6 +420,7 @@ export class AgentBridge {
       case "uninstallPlugin":
         return this.uninstallPlugin(
           p.pluginId as string,
+          p.scope as Scope | undefined,
           p.workdir as string | undefined,
           sessionId,
         );
@@ -307,6 +443,18 @@ export class AgentBridge {
           p.workdir as string | undefined,
           sessionId,
         );
+      case "getHooksConfig":
+        return this.getHooksConfig(
+          p.scope as "user" | "project" | undefined,
+          p.workdir as string | undefined,
+          sessionId,
+        );
+      case "getMcpConfig":
+        return this.getMcpConfig(
+          p.scope as "user" | "project" | undefined,
+          p.workdir as string | undefined,
+          sessionId,
+        );
       case "setBuiltinPluginEnabled":
         return this.setBuiltinPluginEnabled(
           p.pluginId as string,
@@ -321,11 +469,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,
@@ -376,6 +538,10 @@ export class AgentBridge {
             name?: string;
           },
         );
+      case "getWorktreeChanges":
+        return this.getWorktreeChanges(
+          p as unknown as { path?: string; baseBranch?: string },
+        );
       case "removeWorktree":
         return this.removeWorktreeSession(
           p as unknown as {
@@ -445,7 +611,6 @@ export class AgentBridge {
       defaultHeaders: params.defaultHeaders,
       model: params.model,
       fastModel: params.fastModel,
-      language: params.language,
       permissionMode: params.permissionMode,
       tools: params.tools,
       allowedTools: params.allowedTools,
@@ -462,9 +627,29 @@ export class AgentBridge {
     ctx.agent = agent;
     ctx.registeredSessionId = agent.sessionId;
 
+    // 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.
+    let createdWorkdir: string;
+    if (params.restoreSessionId) {
+      createdWorkdir =
+        (await readTranscriptWorkdir(agent.sessionFilePath)) ??
+        params.workdir ??
+        agent.workingDirectory;
+    } else {
+      createdWorkdir = params.workdir ?? agent.workingDirectory;
+    }
+
     this.sessions.set(agent.sessionId, {
       agent,
-      storedConfig: { ...params },
+      // 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,
     });
 
     return {
@@ -479,34 +664,35 @@ export class AgentBridge {
     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);
+        await entry.agent.destroy();
       }
     }
     return null;
   }
 
-  /**
-   * True when every hosted session has settled: not generating, nothing queued,
-   * and no background work (background bash / subagents / workflows) — the same
-   * condition `wave -p` waits on before exiting (print-cli.ts). Pending
-   * permission approvals keep the owning agent's isLoading true, so they are
-   * covered without an explicit check.
-   */
-  public isIdle(): boolean {
-    for (const entry of this.sessions.values()) {
-      const agent = entry.agent;
-      if (
-        agent.isLoading ||
-        agent.hasPendingMessages ||
-        agent.hasRunningBackgroundWork
-      ) {
-        return false;
-      }
-    }
-    return true;
-  }
-
   /**
    * Destroy every hosted session agent. Each Agent.destroy() saves its
    * transcript, drains in-flight auto-memory extraction, and cleans up
@@ -525,7 +711,7 @@ 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
@@ -533,7 +719,7 @@ export class AgentBridge {
     if (entry.agent.sessionId === restoreId) {
       this.emit(
         "messagesChange",
-        { messages: entry.agent.messages },
+        { messages: entry.agent.displayMessages },
         entry.agent.sessionId,
       );
       // The re-attached client also missed the loading state that settled
@@ -548,12 +734,69 @@ export class AgentBridge {
         },
         entry.agent.sessionId,
       );
+      // Same story for the context-usage indicator: the SDK's restore-time
+      // onLatestTotalTokensChange fired inside initialize — before this
+      // client's router registered — so replay the current usage or the
+      // webview keeps the previous session's (or no) percentage until the
+      // next turn pushes a fresh value (spec desktop-app 上下文用量指示器
+      // 场景 6: 恢复即显示该会话上次用量).
+      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
+    // conversation whose persisted total equals the agent's current one
+    // suppresses the change-push and the webview — which cleared the previous
+    // session's number on the switch — keeps a blank ring until the next turn
+    // (the change-push, when it does fire inside restoreSession, already
+    // delivered the same value; re-emitting is idempotent).
+    this.emitContextUsage(entry.agent);
     return null;
   }
 
+  /**
+   * Push the session's current context-usage percentage to the client. Shared
+   * by every restore path so a conversation the client just switched to always
+   * shows its usage right away instead of waiting for the next token change
+   * (spec desktop-app 上下文用量指示器 场景 6). A zero total means no real
+   * 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);
+    }
+  }
+
+  /**
+   * Current context-usage percentage of a session, or undefined when there is
+   * nothing to report yet (no tokens) or the model exposes no limit. Shared by
+   * the change-driven push and the getMessages response, so a host whose
+   * webview was re-created long after the last token change can still restore
+   * the ring without a per-host cache.
+   */
+  private contextUsagePercentOf(agent: Agent): number | undefined {
+    const tokens = agent.latestTotalTokens;
+    const max = agent.getMaxInputTokens();
+    if (tokens > 0 && max > 0) {
+      return Math.min(100, Math.round((tokens / max) * 100));
+    }
+    return undefined;
+  }
+
   private async listSessions(
     workdir?: string,
     sessionId?: string,
@@ -564,6 +807,38 @@ 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 ────────────────────────────────────────────
 
   private listGitBranches(workdir?: string): {
@@ -647,6 +922,21 @@ export class AgentBridge {
     }
   }
 
+  /**
+   * What a worktree deletion would throw away (uncommitted files and commits
+   * not on the base branch), so the caller can warn before deleting. Returns
+   * null when the worktree cannot be inspected.
+   */
+  private async getWorktreeChanges(params: {
+    path?: string;
+    baseBranch?: string;
+  }): Promise<{ files: number; commits: number } | null> {
+    if (!params.path) {
+      throw new RpcError(PROTOCOL_INTERNAL_ERROR, "path is required");
+    }
+    return getWorktreeChanges(params.path, params.baseBranch);
+  }
+
   private async removeWorktreeSession(params: {
     path: string;
     branch: string;
@@ -689,10 +979,13 @@ export class AgentBridge {
     permissionMode: PermissionMode;
     availableTools: string[];
   } {
-    const entry = this.requireSession(sessionId);
+    const entry = this.requireSessionForRead(sessionId);
     return {
       sessionId: entry.agent.sessionId,
-      workingDirectory: entry.agent.workingDirectory,
+      // The recorded creation workdir, not the live agent.workingDirectory:
+      // 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.
+      workingDirectory: entry.createdWorkdir,
       latestTotalTokens: entry.agent.latestTotalTokens,
       permissionMode: entry.agent.getPermissionMode(),
       availableTools: entry.agent.getAvailableToolNames(),
@@ -707,73 +1000,105 @@ 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,
-      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,
+        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 },
-    });
-
-    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,
@@ -782,7 +1107,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.
@@ -790,6 +1115,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(
@@ -930,7 +1296,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 去重并保留最后一次出现（与折叠后的
@@ -973,16 +1339,22 @@ export class AgentBridge {
     return null;
   }
 
-  private getMessages(sessionId?: string): { messages: Message[] } {
-    const entry = this.requireSession(sessionId);
-    return { messages: entry.agent.messages };
+  private getMessages(sessionId?: string): {
+    messages: Message[];
+    contextUsagePercent?: number;
+  } {
+    const entry = this.requireSessionForRead(sessionId);
+    return {
+      messages: entry.agent.displayMessages,
+      contextUsagePercent: this.contextUsagePercentOf(entry.agent),
+    };
   }
 
   private async getFullMessageThread(sessionId?: string): Promise<{
     messages: Message[];
     sessionIds: string[];
   }> {
-    const entry = this.requireSession(sessionId);
+    const entry = this.requireSessionForRead(sessionId);
     return entry.agent.getFullMessageThread();
   }
 
@@ -1001,7 +1373,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) };
   }
 
@@ -1023,7 +1395,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) => {
@@ -1055,14 +1427,40 @@ export class AgentBridge {
   }
 
   private getPermissionMode(sessionId?: string): { mode: PermissionMode } {
-    const entry = this.requireSession(sessionId);
+    const entry = this.requireSessionForRead(sessionId);
     return { mode: entry.agent.getPermissionMode() };
   }
 
+  /**
+   * Returns the current plan file path and its contents for the session.
+   * When the path generation is still in flight (e.g. the host just switched
+   * to plan mode via setPermissionMode), awaits it so the caller can read the
+   * plan before triggering a query (the plan mode reminder needs the path).
+   */
+  private async getPlanFile(sessionId?: string): Promise<{
+    path: string | null;
+    content: string | null;
+  }> {
+    const entry = this.requireSessionForRead(sessionId);
+    const agent = entry.agent;
+    const planPath =
+      agent.getPlanFilePath() ?? (await agent.awaitPlanFilePath());
+    if (!planPath) {
+      return { path: null, content: null };
+    }
+    try {
+      const content = await readFile(planPath, "utf8");
+      return { path: planPath, content };
+    } catch (error) {
+      logger?.warn("Failed to read plan file", error);
+      return { path: planPath, content: null };
+    }
+  }
+
   // ── MCP ───────────────────────────────────────────────────────
 
   private getMcpServers(sessionId?: string): { servers: McpServerStatus[] } {
-    const entry = this.requireSession(sessionId);
+    const entry = this.requireSessionForRead(sessionId);
     return { servers: entry.agent.getMcpServers() };
   }
 
@@ -1084,25 +1482,90 @@ export class AgentBridge {
     return { success };
   }
 
+  private async removeMcpServer(
+    scope: "user" | "project",
+    serverName: string,
+    sessionId?: string,
+  ): Promise<{ success: boolean }> {
+    const entry = this.requireSession(sessionId);
+    const success = await entry.agent.removeMcpServer(scope, serverName);
+    return { success };
+  }
+
+  private getMcpConfigPaths(sessionId?: string): {
+    userPath: string | null;
+    projectPath: string | null;
+  } {
+    const entry = this.requireSessionForRead(sessionId);
+    return {
+      userPath: entry.agent.getUserMcpConfigPath(),
+      projectPath: entry.agent.getProjectMcpConfigPath(),
+    };
+  }
+
   // ── 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() };
   }
 
+  private async deleteSkill(
+    name: string,
+    sessionId?: string,
+  ): Promise<{ success: boolean }> {
+    const entry = this.requireSession(sessionId);
+    const success = await entry.agent.deleteSkill(name);
+    return { success };
+  }
+
+  private async deleteSubagent(
+    name: string,
+    sessionId?: string,
+  ): Promise<{ success: boolean }> {
+    const entry = this.requireSession(sessionId);
+    const success = await entry.agent.deleteSubagent(name);
+    return { success };
+  }
+
+  private async getHooksByScope(
+    scope: "user" | "project" | "plugin",
+    sessionId?: string,
+  ): Promise<{
+    hooks: Partial<Record<string, unknown[]>>;
+    configPath: string | null;
+  }> {
+    const entry = this.requireSessionForRead(sessionId);
+    const hooks = await entry.agent.getHooksByScope(scope);
+    // 回带该 scope 钩子所在 settings.json 的绝对路径（宿主 GUI 打开文件用；
+    // plugin 钩子来自代码而非配置文件 → null）。
+    const configPath =
+      scope === "plugin" ? null : entry.agent.getHookConfigPath(scope);
+    return { hooks, configPath };
+  }
+
+  private async deleteHook(
+    scope: "user" | "project",
+    hookName: string,
+    sessionId?: string,
+  ): Promise<{ success: boolean }> {
+    const entry = this.requireSession(sessionId);
+    await entry.agent.deleteHook(scope, hookName);
+    return { success: true };
+  }
+
   // ── File / History (global) ───────────────────────────────────
 
   private async searchFiles(
@@ -1219,21 +1682,44 @@ export class AgentBridge {
   }
 
   /** Daemon list: expose the in-memory session registry (live sessions only,
-   * not disk-scanning). Registration order is preserved. */
+   * 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`.
+   *
+   * 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. */
   private listDaemonSessions(): {
     sessions: Array<{
       sessionId: string;
       workingDirectory: string;
       isLoading: boolean;
+      hasRunningBackgroundWork: boolean;
+      hasPendingMessages: boolean;
       messageCount: number;
     }>;
   } {
     return {
       sessions: [...this.sessions.entries()].map(([sessionId, entry]) => ({
         sessionId,
-        workingDirectory: entry.agent.workingDirectory,
-        isLoading: entry.agent.isLoading,
-        messageCount: entry.agent.messages.length,
+        workingDirectory: entry.createdWorkdir,
+        isLoading: entry.transitioning === true || entry.agent.isLoading,
+        hasRunningBackgroundWork: entry.agent.hasRunningBackgroundWork,
+        hasPendingMessages: entry.agent.hasPendingMessages,
+        messageCount: entry.agent.displayMessages.length,
       })),
     };
   }
@@ -1254,6 +1740,36 @@ export class AgentBridge {
     };
   }
 
+  private async getAccountInfo(): Promise<{
+    /**
+     * 计费结论（套餐两根条 + 到期日 + 降级原因），形状见 codechat `GET /api/v1/account` → `billing`
+     * （判定出自与 proxy 扣费同一份代码）。本层只转发、不解析；具体形状由 wave-webview-fixtures
+     * 的 AccountBillingInfo 在宿主/卡片侧约束。
+     */
+    billing?: unknown;
+    apiQuota?: { limit: number | null; used: number } | null;
+  }> {
+    const authService = AuthService.getInstance();
+    await authService.checkAndRefreshTokenIfNeeded();
+    if (!authService.isSSOAuthenticated()) return {};
+    const token = authService.getSSOToken();
+    if (!token) return {};
+    const response = await fetch(
+      `${authService.getServerUrl()}/api/v1/account`,
+      {
+        headers: { Authorization: `Bearer ${token}` },
+      },
+    );
+    if (!response.ok) {
+      // 401 / 5xx — 让调用方（desktop host）保留上次成功数据（spec 场景 9）。
+      throw new Error(`Account query failed (${response.status})`);
+    }
+    return (await response.json()) as {
+      billing?: unknown;
+      apiQuota?: { limit: number | null; used: number } | null;
+    };
+  }
+
   private async login(
     serverUrl?: string,
   ): Promise<{ user: { id: string; email?: string } | undefined }> {
@@ -1273,6 +1789,88 @@ export class AgentBridge {
     return null;
   }
 
+  // ── Memory files (settings UI) ───────────────────────────────
+
+  /**
+   * Read an AGENTS.md file for the settings UI: user-level reads
+   * ~/.wave/AGENTS.md, project-level reads <workdir>/AGENTS.md. Prefers the
+   * live agent (clears its caches on write) and falls back to direct file
+   * access when no session is bound (e.g. desktop before any session exists).
+   */
+  private async getAgentsContent(
+    scope: "user" | "project",
+    workdir?: string,
+    sessionId?: string,
+  ): Promise<{ content: string; path?: string }> {
+    const agent = this.sessions.get(sessionId ?? "")?.agent;
+    if (scope === "user") {
+      if (agent) {
+        return { content: await agent.readUserMemoryContent() };
+      }
+      const path = this.getUserMemoryFilePath();
+      return { content: await readTextFileSafe(path), path };
+    }
+    const resolvedWorkdir =
+      workdir || (agent?.workingDirectory as string | undefined);
+    if (!resolvedWorkdir) {
+      throw new RpcError(
+        PROTOCOL_INVALID_PARAMS,
+        "Project-scope AGENTS.md requires a workdir",
+      );
+    }
+    if (agent) {
+      return {
+        content: await agent.readProjectMemoryContent(resolvedWorkdir),
+      };
+    }
+    const path = join(resolvedWorkdir, "AGENTS.md");
+    return { content: await readTextFileSafe(path), path };
+  }
+
+  /**
+   * Write an AGENTS.md file from the settings UI: user-level writes
+   * ~/.wave/AGENTS.md, project-level writes <workdir>/AGENTS.md. Goes through
+   * the live agent when available so its memory caches are invalidated.
+   */
+  private async setAgentsContent(
+    scope: "user" | "project",
+    content: string,
+    workdir?: string,
+    sessionId?: string,
+  ): Promise<{ ok: boolean; path?: string }> {
+    const agent = this.sessions.get(sessionId ?? "")?.agent;
+    if (scope === "user") {
+      if (agent) {
+        await agent.writeUserMemoryContent(content);
+      } else {
+        const path = this.getUserMemoryFilePath();
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, content, "utf-8");
+      }
+      return { ok: true };
+    }
+    const resolvedWorkdir =
+      workdir || (agent?.workingDirectory as string | undefined);
+    if (!resolvedWorkdir) {
+      throw new RpcError(
+        PROTOCOL_INVALID_PARAMS,
+        "Project-scope AGENTS.md requires a workdir",
+      );
+    }
+    if (agent) {
+      await agent.writeProjectMemoryContent(resolvedWorkdir, content);
+    } else {
+      const path = join(resolvedWorkdir, "AGENTS.md");
+      await mkdir(dirname(path), { recursive: true });
+      await writeFile(path, content, "utf-8");
+    }
+    return { ok: true };
+  }
+
+  private getUserMemoryFilePath(): string {
+    return join(homedir(), ".wave", "AGENTS.md");
+  }
+
   // ── Plugins (global) ─────────────────────────────────────────
 
   private getPluginCore(workdir?: string, sessionId?: string): PluginCore {
@@ -1298,6 +1896,7 @@ export class AgentBridge {
           marketplace: p.marketplace,
           installed: p.installed,
           version: p.version,
+          latestVersion: p.latestVersion,
           enabled: mergedEnabled[pluginId] !== false,
           scope: p.scope,
         };
@@ -1319,10 +1918,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;
   }
 
@@ -1347,6 +1950,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,
@@ -1359,6 +1977,81 @@ export class AgentBridge {
     };
   }
 
+  /**
+   * Read the hooks fragment from a single config scope (user or project), for
+   * the settings page read-only hooks view. Hooks come from settings.json
+   * (user: ~/.wave/settings.json; project: .wave/settings.json +
+   * settings.local.json merged, append per event).
+   */
+  private async getHooksConfig(
+    scope: "user" | "project" | undefined,
+    workdir?: string,
+    sessionId?: string,
+  ): Promise<{ hooks: PartialHookConfiguration | undefined }> {
+    const resolvedScope = scope ?? "user";
+
+    if (resolvedScope === "user") {
+      const config = loadWaveConfigFromFile(getUserConfigPaths()[0]);
+      return { hooks: config?.hooks };
+    }
+
+    const resolvedWorkdir =
+      workdir || this.getSessionWorkdir(sessionId) || process.cwd();
+    const [localPath, jsonPath] = getProjectConfigPaths(resolvedWorkdir);
+    const hooks: PartialHookConfiguration = {};
+    for (const config of [
+      loadWaveConfigFromFile(jsonPath),
+      loadWaveConfigFromFile(localPath),
+    ]) {
+      if (!config?.hooks) continue;
+      for (const [event, eventConfigs] of Object.entries(config.hooks)) {
+        if (!isValidHookEvent(event)) continue;
+        hooks[event] = [...(hooks[event] ?? []), ...(eventConfigs ?? [])];
+      }
+    }
+    return { hooks: Object.keys(hooks).length > 0 ? hooks : undefined };
+  }
+
+  /**
+   * Read the mcpServers fragment from a single config scope (user or project),
+   * for the settings page read-only MCP view. MCP servers come from mcp.json
+   * (user: ~/.wave/mcp.json; project: <workdir>/.mcp.json). Runtime status
+   * (connect/disconnect/tools) is served by the existing getMcpServers RPC.
+   */
+  private async getMcpConfig(
+    scope: "user" | "project" | undefined,
+    workdir?: string,
+    sessionId?: string,
+  ): Promise<{ mcpServers: Record<string, McpServerConfig> }> {
+    const resolvedScope = scope ?? "user";
+
+    if (resolvedScope === "user") {
+      return {
+        mcpServers: this.readMcpServersFile(
+          join(homedir(), ".wave", "mcp.json"),
+        ),
+      };
+    }
+
+    const resolvedWorkdir =
+      workdir || this.getSessionWorkdir(sessionId) || process.cwd();
+    return {
+      mcpServers: this.readMcpServersFile(join(resolvedWorkdir, ".mcp.json")),
+    };
+  }
+
+  private readMcpServersFile(
+    filePath: string,
+  ): Record<string, McpServerConfig> {
+    try {
+      if (!existsSync(filePath)) return {};
+      const raw = JSON.parse(readFileSync(filePath, "utf-8")) as McpConfig;
+      return raw.mcpServers ?? {};
+    } catch {
+      return {};
+    }
+  }
+
   private async setBuiltinPluginEnabled(
     pluginId: string,
     enabled: boolean,
@@ -1384,10 +2077,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,
@@ -1412,8 +2131,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 ─────────────────────────────────
@@ -1483,6 +2210,18 @@ export class AgentBridge {
           ctx.registeredSessionId,
         );
       },
+      onLatestTotalTokensChange: (tokens: number) => {
+        // Batch 2 压缩上下文 button: push the context usage percentage on
+        // every token-count change. The SDK fires this on each finished
+        // 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;
+        if (max > 0) {
+          const percent = Math.min(100, Math.round((tokens / max) * 100));
+          this.emit("contextUsage", { percent }, ctx.registeredSessionId);
+        }
+      },
       onCommandRunningChange: (running: boolean) => {
         this.emit("commandRunningChange", { running }, ctx.registeredSessionId);
       },
@@ -1542,29 +2281,8 @@ export class AgentBridge {
       onMcpServersChange: (servers: McpServerStatus[]) => {
         this.emit("mcpServersChange", { servers }, ctx.registeredSessionId);
       },
-      onAddBangMessage: (command, messageId) => {
-        this.emit(
-          "bangMessageAdded",
-          { command, messageId },
-          ctx.registeredSessionId,
-        );
-      },
-      onUpdateBangMessage: (command, output, messageId) => {
-        this.emit(
-          "bangMessageUpdated",
-          { command, output, messageId },
-          ctx.registeredSessionId,
-        );
-      },
-      onCompleteBangMessage: (command, exitCode, messageId, output) => {
-        this.emit(
-          "bangMessageCompleted",
-          { command, exitCode, messageId, output },
-          ctx.registeredSessionId,
-        );
-      },
       onNotificationMessageAdded: (params) => {
-        const msg = ctx.agent?.messages.find(
+        const msg = ctx.agent?.displayMessages.find(
           (m) =>
             m.role === "user" &&
             m.blocks.some(
@@ -1596,6 +2314,9 @@ export class AgentBridge {
           ctx.registeredSessionId,
         );
       },
+      onPlanFileUpdated: (content: string) => {
+        this.emit("planFileUpdated", { content }, ctx.registeredSessionId);
+      },
     };
   }
 
@@ -1606,7 +2327,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,
@@ -1656,3 +2404,54 @@ function isSessionRecoveryError(error: unknown): boolean {
     message.startsWith("Session not found:")
   );
 }
+
+/** Read a text file, returning "" when it does not exist. */
+async function readTextFileSafe(filePath: string): Promise<string> {
+  try {
+    return await readFile(filePath, "utf-8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return "";
+    }
+    throw error;
+  }
+}
+
+/**
+ * Read the creation-time workdir 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
+ * 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;
+  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;
+      const newline = buffer.indexOf(0x0a);
+      const firstLine = buffer
+        .subarray(0, newline === -1 ? bytesRead : newline)
+        .toString("utf8");
+      const header = JSON.parse(firstLine) as {
+        type?: string;
+        workdir?: unknown;
+      };
+      return header.type === "metadata" && typeof header.workdir === "string"
+        ? header.workdir
+        : undefined;
+    } finally {
+      await handle.close();
+    }
+  } catch {
+    return undefined;
+  }
+}