pi-web-ui 0.28.2 → 0.29.1

package/dist/server/agent-service.js

@@ -16,14 +16,30 @@ import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, createBashTool, createLocalBashOperations, defineTool, getAgentDir, ModelRuntime, SessionManager, VERSION, } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { BgServerTracker } from "./bg-servers.js";
+import { SettingsService } from "./settings-service.js";
+import { GoalService } from "./goal-service.js";
+import { SlashCommandsService, parseSlash } from "./slash-commands.js";
+import { ModelAdminService } from "./model-admin.js";
+import { FilesService, workspacePath } from "./files-service.js";
+import { extensionKey, ClientStateStore, } from "./client-state.js";
+import { saveUpload } from "./uploads.js";
+import { makePersistentTerminalTools } from "./terminals.js";
+import { WebUIContext } from "./webui-context.js";
+import { buildAttachmentMessages, parseModelSpec, } from "./attachments.js";
 import { serializeMessage, serializeStreamingMessage, } from "./serialize.js";
 import { loadCommands, saveCommandsFile, TerminalManager, } from "./terminals.js";
-import { buildVisionBridgePrompt, findVisionModels, SYSTEM_PROMPT, transcribeImages, } from "./vision-bridge.js";
+import { buildVisionBridgePrompt, SYSTEM_PROMPT, transcribeImages, } from "./vision-bridge.js";
 const SNAPSHOT_INTERVAL_MS = 60;
+/** While assistant deltas are flowing, live rendering is carried by
+ *  message_delta — full snapshots become pure reconciliation checkpoints, so
+ *  send them on a slow event-driven cadence (see flushSnapshot call-sites:
+ *  agent_end / tool_execution_end always checkpoint immediately). */
+const STREAMING_SNAPSHOT_INTERVAL_MS = 2000;
+/** Deltas newer than this keep the streaming (low-frequency) snapshot cadence. */
+const DELTA_ACTIVE_WINDOW_MS = 1500;
 const WIDGET_REFRESH_MS = 2000;
-const WIDGET_WIDTH = 80;
 /** Preview panel cap: only the first 512KB of a file is ever read/sent. */
-const MAX_PREVIEW_BYTES = 512 * 1024;
 /** Thrown when the service is quiesced (draining) and the request is NEW work
  *  the admission controller refuses: a brand-new client attach, a prompt,
  *  a fork, a session resume, or a goal wizard start. index.ts closes the
@@ -36,237 +52,13 @@ export class QuiesceRejectedError extends Error {
         this.name = "QuiesceRejectedError";
     }
 }
-const PREVIEW_IMAGE_EXTS = new Set([
-    "png",
-    "jpg",
-    "jpeg",
-    "gif",
-    "webp",
-    "svg",
-    "bmp",
-    "ico",
-    "avif",
-    "jfif",
-    "tif",
-    "tiff",
-]);
-const PREVIEW_VIDEO_EXTS = new Set([
-    "mp4",
-    "webm",
-    "mov",
-    "mkv",
-    "avi",
-    "m4v",
-    "ogv",
-    "mpg",
-    "mpeg",
-    "wmv",
-    "flv",
-]);
-const PREVIEW_TEXT_EXTS = new Set([
-    // code
-    "ts",
-    "tsx",
-    "js",
-    "jsx",
-    "mjs",
-    "cjs",
-    "jsm",
-    "es6",
-    "vue",
-    "svelte",
-    "py",
-    "pyw",
-    "ipynb",
-    "go",
-    "rs",
-    "c",
-    "h",
-    "cpp",
-    "hpp",
-    "cc",
-    "cxx",
-    "hh",
-    "csh",
-    "java",
-    "kt",
-    "kts",
-    "scala",
-    "sc",
-    "cs",
-    "fs",
-    "fsx",
-    "fsi",
-    "sh",
-    "bash",
-    "zsh",
-    "fish",
-    "bat",
-    "cmd",
-    "ps1",
-    "psd1",
-    "psm1",
-    "rb",
-    "php",
-    "pl",
-    "pm",
-    "tcl",
-    "lua",
-    "r",
-    "rmd",
-    "sql",
-    "swift",
-    "dart",
-    "groovy",
-    "gradle",
-    "tf",
-    "tfvars",
-    "hcl",
-    "nim",
-    "zig",
-    "v",
-    "vala",
-    "d",
-    "clj",
-    "cljs",
-    "cljc",
-    "edn",
-    "ex",
-    "exs",
-    "erl",
-    "hrl",
-    "ml",
-    "mli",
-    // markup / config / data
-    "json",
-    "jsonc",
-    "json5",
-    "jsonl",
-    "md",
-    "mdx",
-    "markdown",
-    "html",
-    "htm",
-    "xhtml",
-    "css",
-    "scss",
-    "sass",
-    "less",
-    "styl",
-    "xml",
-    "dtd",
-    "yaml",
-    "yml",
-    "toml",
-    "ini",
-    "cfg",
-    "conf",
-    "properties",
-    "env",
-    "log",
-    "txt",
-    "text",
-    "csv",
-    "tsv",
-    "lock",
-    "sqlite",
-    "graphql",
-    "gql",
-    "proto",
-    "prisma",
-    "asm",
-    "s",
-]);
-/**
- * Classify a file name into its preview category. Files with no extension
- * (README, Makefile, .gitignore, …) are treated as text. Everything not in an
- * allowlist (exe, jar, dll, zip, …) is "none" — never previewed.
- */
-export function previewKind(name) {
-    const dot = name.lastIndexOf(".");
-    // A leading dot with nothing after it (.gitignore, .env) counts as no ext.
-    const ext = dot > 0 ? name.slice(dot + 1).toLowerCase() : "";
-    if (PREVIEW_IMAGE_EXTS.has(ext))
-        return "image";
-    if (PREVIEW_VIDEO_EXTS.has(ext))
-        return "video";
-    if (ext === "" || PREVIEW_TEXT_EXTS.has(ext))
-        return "text";
-    return "none";
-}
-/**
- * Content sniff for the preview: any data that has no NUL bytes and no
- * meaningful control-char ratio is treated as text — so files with unknown
- * or absent extensions (jsonl, .log.1, …) still open as text. NULs catch
- * zip/sqlite/png/… even when the extension claims text.
- */
-function looksLikeText(buf) {
-    if (buf.length === 0)
-        return true;
-    if (buf.includes(0))
-        return false;
-    const text = buf.toString("utf8");
-    let control = 0;
-    for (const ch of text) {
-        const c = ch.charCodeAt(0);
-        // Keep \t \n \r \f (and \b); everything else < 0x20 is binary-ish.
-        if (c < 0x20 && c !== 9 && c !== 10 && c !== 12 && c !== 13)
-            control++;
-    }
-    return control / Math.max(text.length, 1) < 0.02;
-}
-/** Decode bytes: strict UTF-8 first, falling back to GBK (Windows legacy
- *  Chinese files), then latin1 as a last resort — so previews and inline
- *  attachments never show mojibake for GBK/GB2312 encoded files. */
-function decodeText(buf) {
-    try {
-        return new TextDecoder("utf-8", { fatal: true }).decode(buf);
-    }
-    catch {
-        try {
-            return new TextDecoder("gbk").decode(buf);
-        }
-        catch {
-            return buf.toString("latin1");
-        }
-    }
-}
-/** Sniff an image MIME type from magic bytes (extension is only a hint).
- *  Returns null when the bytes don't look like a known raster format —
- *  callers keep such files as plain path references. */
-function sniffImageMime(buf, ext) {
-    if (buf.length >= 8 &&
-        buf[0] === 0x89 &&
-        buf[1] === 0x50 &&
-        buf[2] === 0x4e &&
-        buf[3] === 0x47) {
-        return "image/png";
-    }
-    if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) {
-        return "image/jpeg";
-    }
-    const head = buf.slice(0, 6).toString("ascii");
-    if (head === "GIF87a" || head === "GIF89a")
-        return "image/gif";
-    if (buf.length >= 12 &&
-        buf.slice(0, 4).toString("ascii") === "RIFF" &&
-        buf.slice(8, 12).toString("ascii") === "WEBP") {
-        return "image/webp";
-    }
-    if (buf.length >= 2 && buf[0] === 0x42 && buf[1] === 0x4d)
-        return "image/bmp";
-    // Unknown but raster-looking extension — trust the extension so existing
-    // image attachments keep working.
-    const known = {
-        ".png": "image/png",
-        ".jpg": "image/jpeg",
-        ".jpeg": "image/jpeg",
-        ".gif": "image/gif",
-        ".webp": "image/webp",
-        ".bmp": "image/bmp",
-    };
-    return known[ext] ?? null;
-}
+// ---------------------------------------------------------------------------
+// Preview kind classification. The preview panel only opens image / video /
+// text-editable files; everything else (exe, jar, archives, …) is refused so
+// it is never read or sent to the browser. Media files are served over the
+// /api/file HTTP endpoint instead of the WebSocket, so they are classified
+// here but never read into the snapshot path.
+// ---------------------------------------------------------------------------
 /** Windows persona appendix — appended to the SDK system prompt on win32 only.
  *  Two failure modes it guards against: (1) the SDK bash tool has NO default
  *  timeout, so a long-running command hangs the whole conversation forever;
@@ -321,87 +113,6 @@ function makeKillableBashTool(cwd, kills) {
         execute: (toolCallId, params, signal, onUpdate) => tool.execute(toolCallId, params, signal, onUpdate),
     };
 }
-/**
- * Snapshot currently LISTENING TCP ports → owning pid. Windows: netstat;
- * POSIX: lsof. Used to detect servers the agent started in the background
- * (the bash tool itself exits, leaving e.g. `npm run dev &` listening).
- */
-async function snapshotListeningPorts() {
-    const m = new Map();
-    try {
-        const { execFile } = await import("node:child_process");
-        if (process.platform === "win32") {
-            const out = await new Promise((resolve, reject) => execFile("netstat", ["-ano", "-p", "tcp"], { windowsHide: true, timeout: 8000 }, (err, stdout) => (err ? reject(err) : resolve(stdout))));
-            for (const line of out.split(/\r?\n/)) {
-                const p = line.trim().split(/\s+/);
-                // TCP 0.0.0.0:5173 0.0.0.0:0 LISTENING 12345
-                if (p.length >= 5 && p[0] === "TCP" && p[3] === "LISTENING") {
-                    const port = Number(p[1].split(":").pop());
-                    const pid = Number(p[4]);
-                    if (Number.isFinite(port) && Number.isFinite(pid))
-                        m.set(port, pid);
-                }
-            }
-        }
-        else {
-            const out = await new Promise((resolve, reject) => execFile("lsof", ["-iTCP", "-sTCP:LISTEN", "-P", "-n"], { timeout: 8000 }, (err, stdout) => (err ? reject(err) : resolve(stdout))));
-            for (const line of out.split(/\r?\n/).slice(1)) {
-                const p = line.trim().split(/\s+/);
-                if (p.length >= 9) {
-                    // NAME column tail: "*:5173 (LISTEN)" or "[::1]:5173 (LISTEN)"
-                    const mm = (p[p.length - 1] ?? "").match(/(\d+)\)?\s*$/);
-                    const port = mm ? Number(mm[1]) : NaN;
-                    const pid = Number(p[1]);
-                    if (Number.isFinite(port) && Number.isFinite(pid))
-                        m.set(port, pid);
-                }
-            }
-        }
-    }
-    catch {
-        // best effort — snapshot failure just means no tracking this round
-    }
-    return m;
-}
-/** Kill a pid and its whole process tree (cross-platform). */
-function killPidTree(pid) {
-    try {
-        if (process.platform === "win32") {
-            void import("node:child_process").then(({ spawn }) => {
-                spawn("taskkill", ["/F", "/T", "/PID", String(pid)], {
-                    stdio: "ignore",
-                    detached: true,
-                    windowsHide: true,
-                }).unref();
-            });
-        }
-        else {
-            process.kill(-pid, "SIGKILL");
-        }
-    }
-    catch {
-        // already dead
-    }
-}
-/** Best-effort process name for a pid (tasklist on win32, ps on POSIX).
- *  Returns undefined when the process is gone or the lookup fails. */
-async function lookupProcessName(pid) {
-    try {
-        const { execFile } = await import("node:child_process");
-        if (process.platform === "win32") {
-            const out = await new Promise((resolve, reject) => execFile("tasklist", ["/FI", `PID eq ${pid}`, "/FO", "CSV", "/NH"], { windowsHide: true, timeout: 4000 }, (err, stdout) => (err ? reject(err) : resolve(stdout))));
-            // CSV: "node.exe","12345",...
-            const m = out.match(/"([^"]+)"/);
-            return m ? m[1] : undefined;
-        }
-        const out = await new Promise((resolve, reject) => execFile("ps", ["-o", "comm=", "-p", String(pid)], { timeout: 4000 }, (err, stdout) => (err ? reject(err) : resolve(stdout))));
-        const name = out.trim();
-        return name || undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
 /**
  * Cheap per-message discriminator for the serialization cache key. Persisted
  * message content never changes, so this is stable across snapshots, while
@@ -412,23 +123,6 @@ async function lookupProcessName(pid) {
  * payloads by data length (identical lengths within the same ms are far too
  * unlikely to matter).
  */
-/** System prompt for the goal-wizard session. The wizard asks the user a few
- *  questions (via its goal_ask tool) to scope a raw requirement into a precise,
- *  reviewable goal, then emits ONLY the final goal text as its last message. */
-function wizardPrompt(draft) {
-    return [
-        `You are a goal-clarification wizard. The user has stated a raw requirement. Your job is to turn it into ONE precise, actionable goal that a coding agent can fully satisfy and that can be strictly reviewed.`, // eslint-disable-line max-len
-        ``,
-        `# User's raw requirement`, // eslint-disable-line no-regex-spaces
-        draft,
-        ``,
-        `Use your goal_ask tool to ask the user focused questions to pin down the essential, ambiguous details. Keep it concise — usually 2 to 4 questions: what exactly to build/do, scope boundaries (what NOT to do), acceptance criteria / done-definition, and any constraints (style, performance, environment).`, // eslint-disable-line max-len
-        `Prefer multiple-choice (goal_ask with options) when you can offer clear choices; use open questions only for things that genuinely need free text.`, // eslint-disable-line max-len
-        `Once you have enough to write an unambiguous, reviewable goal, STOP asking and reply with EXACTLY this format and nothing else (no preamble, no bullets):`, // eslint-disable-line max-len
-        `GOAL: <one concrete, verifiable sentence describing the deliverable and its acceptance criteria>`, // eslint-disable-line max-len
-        `If the user cancels or stops answering (the tool reports a cancellation), still produce a sensible best-effort goal from what you already know.`, // eslint-disable-line max-len
-    ].join("\n");
-}
 function contentFingerprint(m) {
     const content = m.content;
     if (!Array.isArray(content) || content.length === 0)
@@ -445,283 +139,12 @@ function contentFingerprint(m) {
     }
     return `txt:${h.toString(36)}:${text.length}`;
 }
-/** First few KB of binary data as a classic hex + ASCII dump (preview only). */
-function hexDump(buf, maxBytes = 4096) {
-    const data = buf.subarray(0, Math.min(buf.length, maxBytes));
-    const rows = [];
-    for (let off = 0; off < data.length; off += 16) {
-        const chunk = data.subarray(off, off + 16);
-        const hex = [...chunk]
-            .map((b) => b.toString(16).padStart(2, "0"))
-            .join(" ");
-        const ascii = [...chunk]
-            .map((b) => (b >= 0x20 && b < 0x7f ? String.fromCharCode(b) : "."))
-            .join("");
-        rows.push(`${off.toString(16).padStart(8, "0")}  ${hex.padEnd(47, " ")}  ${ascii}`);
-    }
-    return rows.join("\n");
-}
 // ---------------------------------------------------------------------------
 // Web UI context adapter — bridges extension UI calls (setWidget/notify) to the
 // browser. Extensions like rpiv-todo render a TUI widget via
 // `ui.setWidget(key, (tui, theme) => comp)`; we capture the component, render it
 // with a mock theme to plain text lines, and push them to the client.
 // ---------------------------------------------------------------------------
-/** Mock theme: TUI color functions degrade to identity so widget text survives. */
-const mockTheme = new Proxy({
-    fg: (_color, text) => text,
-    bold: (text) => text,
-    strikethrough: (text) => text,
-    dim: (text) => text,
-}, {
-    get(target, prop) {
-        if (prop in target)
-            return target[prop];
-        // Unknown theme methods → no-op passthrough.
-        return (_arg, text) => text !== undefined ? text : "";
-    },
-});
-/** Mock TUI: any method call is a safe no-op. */
-const mockTui = new Proxy({
-    requestRender: () => { },
-    render: () => { },
-}, {
-    get(target, prop) {
-        if (prop in target)
-            return target[prop];
-        return () => { };
-    },
-});
-/**
- * Implements the subset of ExtensionUIContext that makes sense for a web UI.
- * TUI-only affordances (select/confirm/input dialogs, terminal input, custom
- * footer) are inert: dialogs resolve to cancellation instead of blocking.
- */
-export class WebUIContext {
-    theme = mockTheme;
-    widgets = new Map();
-    lastLines = new Map();
-    emit;
-    constructor(emit) {
-        this.emit = emit;
-    }
-    // -- widgets -------------------------------------------------------------
-    /** Matches ExtensionUIContext's overloaded setWidget exactly. */
-    setWidget = (key, content, options) => {
-        void options;
-        if (content === undefined) {
-            this.widgets.delete(key);
-            this.lastLines.delete(key);
-            this.push();
-            return;
-        }
-        if (typeof content === "function") {
-            let comp;
-            try {
-                // Mock TUI/theme: extensions only read a handful of theme helpers;
-                // everything else is a no-op, so the widget renders to plain text.
-                comp = content(mockTui, mockTheme);
-            }
-            catch {
-                comp = undefined;
-            }
-            this.widgets.set(key, {
-                render: (w) => comp?.render?.(w),
-                dispose: comp?.dispose,
-            });
-        }
-        else {
-            this.widgets.set(key, { render: () => content });
-        }
-        this.push();
-    };
-    /** Re-render all widgets and push when content changed (polled + on demand). */
-    refresh() {
-        let changed = false;
-        for (const [key, w] of this.widgets) {
-            let lines;
-            try {
-                lines = w.render(WIDGET_WIDTH);
-            }
-            catch {
-                lines = undefined;
-            }
-            const prev = this.lastLines.get(key);
-            if (JSON.stringify(lines ?? null) !== JSON.stringify(prev ?? null)) {
-                this.lastLines.set(key, lines ?? []);
-                changed = true;
-            }
-        }
-        if (changed)
-            this.push();
-    }
-    push() {
-        const widgets = this.snapshot();
-        this.emit({ type: "widgets", widgets });
-    }
-    /** Render all widgets to their current text lines (without emitting). */
-    snapshot() {
-        return [...this.widgets.entries()].map(([key, w]) => {
-            let lines;
-            try {
-                lines = w.render(WIDGET_WIDTH);
-            }
-            catch {
-                lines = undefined;
-            }
-            this.lastLines.set(key, lines ?? []);
-            return { key, lines: lines ?? [] };
-        });
-    }
-    // -- notifications --------------------------------------------------------
-    notify(message, type) {
-        this.emit({ type: "notice", level: type ?? "info", text: message });
-    }
-    // -- footer status (pi-lens "LSP Inactive", pi-cache-optimizer cache stats) --
-    statuses = new Map();
-    setStatus(key, text) {
-        if (text === undefined || text === "") {
-            this.statuses.delete(key);
-        }
-        else {
-            this.statuses.set(key, text);
-        }
-        this.pushStatuses();
-    }
-    pushStatuses() {
-        this.emit({
-            type: "statuses",
-            statuses: [...this.statuses.entries()].map(([k, v]) => ({
-                key: k,
-                text: v,
-            })),
-        });
-    }
-    /** Current footer status entries (for replay on socket attach). */
-    statusSnapshot() {
-        return [...this.statuses.entries()].map(([k, v]) => ({ key: k, text: v }));
-    }
-    // -- dialogs (select/confirm/input bridged to the browser) ---------------
-    dialogSeq = 0;
-    pendingDialogs = new Map();
-    select = (title, options) => this.openDialog("select", title, [options]);
-    confirm = (title, message) => this.openDialog("confirm", title, [message]);
-    input = (title, placeholder) => this.openDialog("input", title, [placeholder ?? ""]);
-    openDialog(kind, title, args) {
-        return new Promise((resolve) => {
-            const id = ++this.dialogSeq;
-            this.pendingDialogs.set(id, resolve);
-            this.emit({ type: "dialog", id, kind, title, args });
-        });
-    }
-    /** Resolve a pending dialog with the user's choice (called from the client). */
-    resolveDialog(id, value) {
-        const resolve = this.pendingDialogs.get(id);
-        if (resolve) {
-            this.pendingDialogs.delete(id);
-            resolve(value);
-            this.emit({ type: "dialog_closed", id });
-        }
-    }
-    /** Close every pending dialog as cancelled (used when a goal wizard aborts —
-     *  its unanswered browser dialogs must vanish, not linger). */
-    cancelPendingDialogs() {
-        for (const [id, resolve] of this.pendingDialogs) {
-            this.pendingDialogs.delete(id);
-            resolve(null);
-            this.emit({ type: "dialog_closed", id });
-        }
-    }
-    // -- inert TUI-only affordances ------------------------------------------
-    onTerminalInput = () => () => { };
-    setWorkingMessage = () => { };
-    setWorkingVisible = () => { };
-    setWorkingIndicator = () => { };
-    setHiddenThinkingLabel = () => { };
-    setFooter = () => { };
-    setHeader = () => { };
-    setTitle = () => { };
-    custom = (_factory, _done) => new Promise(() => { });
-    pasteToEditor = () => { };
-    setEditorText = () => { };
-    getEditorText = () => "";
-    editor = async () => undefined;
-    addAutocompleteProvider = () => { };
-    setEditorComponent = () => { };
-    getEditorComponent = () => undefined;
-    getAllThemes = () => [];
-    getTheme = () => undefined;
-    setTheme = () => ({ success: false });
-    getToolsExpanded = () => false;
-    setToolsExpanded = () => { };
-    /** Dispose all widgets (extension reload / session teardown). */
-    dispose() {
-        for (const w of this.widgets.values()) {
-            try {
-                w.dispose?.();
-            }
-            catch {
-                // best effort
-            }
-        }
-        this.widgets.clear();
-        this.lastLines.clear();
-        // Cancel any pending dialogs.
-        for (const [id, resolve] of this.pendingDialogs) {
-            resolve(null);
-            this.emit({ type: "dialog_closed", id });
-        }
-        this.pendingDialogs.clear();
-    }
-}
-const IS_WIN32 = process.platform === "win32";
-// mac/linux: hide build & dependency noise (original behavior).
-const IGNORED_ENTRIES = new Set([
-    "node_modules",
-    ".git",
-    ".svn",
-    ".hg",
-    "dist",
-    ".next",
-    ".nuxt",
-    ".cache",
-    ".venv",
-    "venv",
-    "__pycache__",
-    "coverage",
-    ".pi-web",
-    ".DS_Store",
-    "Thumbs.db",
-]);
-// Windows: the file tree is the primary way to navigate a project, so only
-// hide what would flood or destabilize the panel (dependency trees, VCS
-// internals, session data) plus pure junk. Build output (dist/.next/…) and
-// local env dirs (venv/__pycache__/…) stay visible — "所有文件可查看".
-const IGNORED_ENTRIES_WIN = new Set([
-    "node_modules",
-    ".git",
-    ".pi-web",
-    ".DS_Store",
-    "Thumbs.db",
-    "desktop.ini",
-]);
-/** The ignore set for the current platform — keeps win/posix lists separate. */
-function ignoredEntries() {
-    return IS_WIN32 ? IGNORED_ENTRIES_WIN : IGNORED_ENTRIES;
-}
-function countLines(buf) {
-    if (buf.length === 0)
-        return 0;
-    const hasTrailingNewline = buf[buf.length - 1] === 10; /* \n */
-    let lines = 0;
-    for (let i = 0; i < buf.length; i++) {
-        if (buf[i] === 10)
-            lines++;
-    }
-    // A trailing newline terminates the last line instead of starting an empty
-    // one — matches the client preview's split-based line numbering.
-    return hasTrailingNewline ? lines : lines + 1;
-}
 function extractPartialText(partial) {
     const content = partial
         ?.content;
@@ -735,222 +158,7 @@ function extractPartialText(partial) {
     }
     return null;
 }
-/**
- * Resolve a workspace-relative path against a root, refusing traversal
- * (".." escapes). Returns { abs, rel } — rel is normalized and slash-
- * separated — or null when the path leaves the workspace.
- */
-export function workspacePath(root, raw) {
-    const abs = resolve(root, raw);
-    const rawRel = relative(root, abs);
-    if (rawRel.startsWith("..") || rawRel.includes(`${sep}..`))
-        return null;
-    // Normalize to forward slashes: the wire protocol and the frontend always
-    // use "/", but relative() returns "\\" on Windows.
-    return { abs, rel: rawRel.split(sep).join("/") };
-}
-/**
- * Read a directory for the file panel. The two platforms intentionally use
- * different strategies — do NOT unify them:
- *
- * darwin/linux (posix): original behavior — hide build/dependency noise,
- * small cap, hard error notice when the directory itself is unreadable.
- *
- * win32: stability and completeness first, preview second. ACL-protected
- * system dirs (C:\$Recycle.Bin, Program Files internals, OneDrive placeholders)
- * throw EPERM/EACCES on open — that must not kill the panel, so it degrades
- * to an empty listing plus a warning. Directory symlinks/junctions are
- * followed so mklink /D folders stay navigable; broken links still show as
- * files instead of vanishing. The cap is 4x posix and truncation is reported
- * via `truncated` instead of happening silently.
- */
-async function readDirForUI(abs, rel) {
-    const fs = await import("node:fs/promises");
-    const ignored = ignoredEntries();
-    const MAX = IS_WIN32 ? 2000 : 500;
-    let dirents;
-    try {
-        dirents = await fs.readdir(abs, { withFileTypes: true });
-    }
-    catch (err) {
-        if (!IS_WIN32)
-            throw err;
-        // Windows ACL-protected/system dirs throw EPERM/EACCES on open —
-        // degrade to an empty listing; listFiles turns this into a warning.
-        return { entries: [], truncated: false, error: err.message };
-    }
-    const out = [];
-    for (const d of dirents) {
-        if (ignored.has(d.name))
-            continue;
-        let type;
-        if (IS_WIN32 && d.isSymbolicLink()) {
-            // mklink /D symlinks and junctions are reparse points — libuv
-            // classifies them as links, so isDirectory() is false. Follow the
-            // target so folder links stay navigable; broken links still show.
-            try {
-                const st = await fs.stat(join(abs, d.name));
-                type = st.isDirectory() ? "dir" : "file";
-            }
-            catch {
-                type = "file";
-            }
-        }
-        else {
-            type = d.isDirectory() ? "dir" : "file";
-        }
-        const entry = {
-            name: d.name,
-            path: rel === "" ? d.name : `${rel}/${d.name}`,
-            type,
-        };
-        if (type === "file")
-            entry.kind = previewKind(d.name);
-        out.push(entry);
-    }
-    out.sort((a, b) => a.type === b.type
-        ? a.name.localeCompare(b.name)
-        : a.type === "dir"
-            ? -1
-            : 1);
-    const truncated = out.length > MAX;
-    if (truncated)
-        out.length = MAX;
-    return { entries: out, truncated };
-}
-/** Stable identity of an extension for the enable/disable toggle: the npm
- *  spec for packages (survives version bumps), the resolved entry path
- *  otherwise. */
-function extensionKey(e) {
-    const src = e.sourceInfo;
-    if (src?.origin === "package" && src.source)
-        return src.source;
-    return src?.path ?? e.path;
-}
-/**
- * Persists which workspace each browser client last used + which workspaces it
- * has opened, so a server restart / page reload restores the same project and
- * the UI can offer a one-click recent-project list. File I/O is best-effort:
- * persistence problems must never crash the server or block a session.
- */
-class ClientStateStore {
-    filePath;
-    cache = null;
-    constructor(filePath) {
-        this.filePath = filePath;
-    }
-    load() {
-        if (this.cache)
-            return this.cache;
-        try {
-            const parsed = JSON.parse(readFileSync(this.filePath, "utf8"));
-            this.cache = parsed && typeof parsed === "object" ? parsed : {};
-        }
-        catch {
-            this.cache = {};
-        }
-        return this.cache;
-    }
-    save() {
-        try {
-            mkdirSync(dirname(this.filePath), { recursive: true });
-            writeFileSync(this.filePath, JSON.stringify(this.cache, null, 2) + "\n");
-        }
-        catch {
-            // best effort
-        }
-    }
-    get(clientId) {
-        return this.load()[clientId] ?? { projects: [] };
-    }
-    /** Remember which workspace a client last used; bumps its project entry. */
-    remember(clientId, cwd) {
-        const all = this.load();
-        const state = (all[clientId] ??= { projects: [] });
-        state.lastCwd = cwd;
-        const now = Date.now();
-        state.projects = [
-            { path: cwd, lastUsed: now },
-            ...state.projects.filter((p) => p.path !== cwd),
-        ].slice(0, 30);
-        this.save();
-    }
-    /** Last-used goal/review prefs for a client, or undefined if never set. */
-    getGoalPrefs(clientId) {
-        const s = this.load()[clientId];
-        if (!s?.goalPrefs)
-            return undefined;
-        return {
-            reviewModel: s.goalPrefs.reviewModel ?? null,
-            maxRounds: s.goalPrefs.maxRounds ?? 0,
-            locked: s.goalPrefs.locked ?? true,
-        };
-    }
-    /** Persist the client's goal/review preferences (model choice, rounds, lock). */
-    saveGoalPrefs(clientId, prefs) {
-        const all = this.load();
-        const state = (all[clientId] ??= { projects: [] });
-        state.goalPrefs = {
-            reviewModel: prefs?.reviewModel ?? null,
-            maxRounds: prefs?.maxRounds ?? 0,
-            locked: prefs?.locked ?? true,
-        };
-        this.save();
-    }
-    /** Last-used settings-panel state for a client, or defaults. */
-    getSettings(clientId) {
-        const s = this.load()[clientId];
-        return {
-            promptMode: s?.settings?.promptMode === "replace" ? "replace" : "append",
-            customSystemPrompt: s?.settings?.customSystemPrompt ?? "",
-            disabledSkills: s?.settings?.disabledSkills ?? [],
-            disabledExtensions: s?.settings?.disabledExtensions ?? [],
-            visionBridgeEnabled: s?.settings?.visionBridgeEnabled ?? true,
-            visionBridgeModel: s?.settings?.visionBridgeModel ?? null,
-            visionBridgePromptMode: s?.settings?.visionBridgePromptMode === "replace" ? "replace" : "append",
-            visionBridgePrompt: s?.settings?.visionBridgePrompt ?? "",
-            reviewPrompt: s?.settings?.reviewPrompt ?? "",
-            reviewDisabledSkills: s?.settings?.reviewDisabledSkills ?? [],
-        };
-    }
-    /** Persist the client's settings-panel state (partial merge). */
-    saveSettings(clientId, settings) {
-        const all = this.load();
-        const state = (all[clientId] ??= { projects: [] });
-        const cur = state.settings ?? {};
-        state.settings = {
-            promptMode: settings.promptMode ?? cur.promptMode ?? "append",
-            customSystemPrompt: settings.customSystemPrompt ?? cur.customSystemPrompt ?? "",
-            disabledSkills: settings.disabledSkills ?? cur.disabledSkills ?? [],
-            disabledExtensions: settings.disabledExtensions ?? cur.disabledExtensions ?? [],
-            visionBridgeEnabled: settings.visionBridgeEnabled ?? cur.visionBridgeEnabled ?? true,
-            visionBridgeModel: settings.visionBridgeModel ?? cur.visionBridgeModel ?? null,
-            visionBridgePromptMode: settings.visionBridgePromptMode ??
-                cur.visionBridgePromptMode ??
-                "append",
-            visionBridgePrompt: settings.visionBridgePrompt ?? cur.visionBridgePrompt ?? "",
-            reviewPrompt: settings.reviewPrompt ?? cur.reviewPrompt ?? "",
-            reviewDisabledSkills: settings.reviewDisabledSkills ?? cur.reviewDisabledSkills ?? [],
-        };
-        this.save();
-    }
-    /** Named settings presets for a client (empty if never saved). */
-    getPresets(clientId) {
-        return (this.load()[clientId]?.presets ?? []).map((p) => ({
-            ...p,
-            // Older client-state files predate review settings.
-            reviewPrompt: p.reviewPrompt ?? "",
-            reviewDisabledSkills: p.reviewDisabledSkills ?? [],
-        }));
-    }
-    /** Persist the client's named settings presets. */
-    savePresets(clientId, presets) {
-        const all = this.load();
-        const state = (all[clientId] ??= { projects: [] });
-        state.presets = presets;
-        this.save();
-    }
-}
+export { workspacePath };
 /** Hard cap on how long ONE tool call may run before the watchdog aborts the
  *  session. The SDK bash tool has NO default timeout, so a command that never
  *  finishes (servers, watchers, infinite loops) would otherwise hang the whole
@@ -964,102 +172,6 @@ const TOOL_WATCHDOG_TIMEOUT_MS = (() => {
  *  runtime alive; conversations of other projects keep their own lists). */
 const MAX_OPEN_CONVERSATIONS = 8;
 const DEFAULT_CONV_TITLE = "新对话";
-/** Build the agent-facing persistent terminal tools for one conversation. */
-export function makePersistentTerminalTools(terminals, cwd) {
-    const result = (text, details = {}) => ({ content: [{ type: "text", text }], details });
-    const failIf = (error) => {
-        if (error)
-            throw new Error(error);
-    };
-    return [
-        defineTool({
-            name: "terminal_create",
-            label: "Create terminal",
-            description: "Create a named persistent interactive PTY in the current workspace. Use terminal_input or terminal_key to interact with it and terminal_read to inspect incremental output.",
-            promptSnippet: "create persistent interactive PTY terminals",
-            parameters: Type.Object({
-                terminalId: Type.String({ description: "Stable terminal name" }),
-                cwd: Type.Optional(Type.String({ description: "Workspace-relative directory" })),
-                cols: Type.Optional(Type.Integer({ minimum: 2, maximum: 500 })),
-                rows: Type.Optional(Type.Integer({ minimum: 2, maximum: 200 })),
-            }),
-            execute: async (_id, p) => {
-                const info = terminals.create(p.terminalId, p.cwd ?? cwd, p.cols ?? 120, p.rows ?? 40, cwd, p.terminalId);
-                if (!info)
-                    throw new Error(`创建终端失败：${p.terminalId}`);
-                return result(`终端已创建：${JSON.stringify(info)}`, info);
-            },
-        }),
-        defineTool({
-            name: "terminal_list",
-            label: "List terminals",
-            description: "List all persistent PTY terminals owned by this conversation.",
-            promptSnippet: "list persistent terminals",
-            parameters: Type.Object({}),
-            execute: async () => result(JSON.stringify(terminals.list()), terminals.list()),
-        }),
-        defineTool({
-            name: "terminal_close",
-            label: "Close terminal",
-            description: "Close a persistent PTY and terminate its process tree.",
-            parameters: Type.Object({ terminalId: Type.String() }),
-            execute: async (_id, p) => {
-                if (!terminals.has(p.terminalId))
-                    throw new Error(`终端不存在：${p.terminalId}`);
-                terminals.kill(p.terminalId);
-                return result(`终端已关闭：${p.terminalId}`);
-            },
-        }),
-        defineTool({
-            name: "terminal_input",
-            label: "Send terminal input",
-            description: "Send arbitrary text to a persistent PTY. Include newline when a command should be submitted.",
-            parameters: Type.Object({ terminalId: Type.String(), data: Type.String() }),
-            execute: async (_id, p) => {
-                failIf(terminals.inputChecked(p.terminalId, p.data));
-                return result(`已发送 ${p.data.length} 个字符到 ${p.terminalId}`);
-            },
-        }),
-        defineTool({
-            name: "terminal_key",
-            label: "Send terminal key",
-            description: "Send Enter, Tab, arrows, function keys, or Ctrl/Alt combinations to a persistent PTY.",
-            parameters: Type.Object({
-                terminalId: Type.String(),
-                key: Type.String({ description: "Enter, Tab, ArrowUp, c, etc." }),
-                modifiers: Type.Optional(Type.Object({
-                    ctrl: Type.Optional(Type.Boolean()),
-                    alt: Type.Optional(Type.Boolean()),
-                    shift: Type.Optional(Type.Boolean()),
-                })),
-            }),
-            execute: async (_id, p) => {
-                failIf(terminals.key(p.terminalId, p.key, p.modifiers));
-                return result(`已发送按键 ${p.key} 到 ${p.terminalId}`);
-            },
-        }),
-        defineTool({
-            name: "terminal_read",
-            label: "Read terminal output",
-            description: "Read incremental output from a persistent PTY. Keep the returned cursor and pass it on the next read; optionally wait for new output or process exit.",
-            parameters: Type.Object({
-                terminalId: Type.String(),
-                cursor: Type.Optional(Type.Integer({ minimum: 0 })),
-                maxBytes: Type.Optional(Type.Integer({ minimum: 1, maximum: 100000 })),
-                waitMs: Type.Optional(Type.Integer({ minimum: 0, maximum: 120000 })),
-            }),
-            execute: async (_id, p, signal) => {
-                const cursor = p.cursor ?? 0;
-                if (p.waitMs)
-                    await terminals.waitForOutput(p.terminalId, cursor, p.waitMs, signal);
-                const read = terminals.read(p.terminalId, cursor, p.maxBytes ?? 20000);
-                if (!read)
-                    throw new Error(`终端不存在：${p.terminalId}`);
-                return result(JSON.stringify(read), read);
-            },
-        }),
-    ];
-}
 /** First user text in a session, truncated for the conversation list. */
 function conversationTitle(session) {
     try {
@@ -1114,55 +226,14 @@ export class ClientSession {
      *  the first conversation and reused by later ones. */
     sharedModelRuntime;
     // -----------------------------------------------------------------------
-    // Goal / review state. When a goal is active, every finished agent run
-    // (agent_end) is checked by an ISOLATED reviewer agent; a failing review
-    // injects its feedback back into the main session to revise. All goal
-    // mutation goes through setGoal/clearGoal so UI state stays consistent.
+    // Goal / review / wizard —— 自包含模块，见 goal-service.ts。每个对话有独立
+    // 的 GoalStatus，审查可并发；宿主回调在构造函数里接入。
     // -----------------------------------------------------------------------
-    /** Defaults remembered for newly-created conversations. Each conversation
-     * receives its own GoalStatus, so reviews can run concurrently. */
-    goalReviewPrefs = {
-        reviewModel: null,
-        maxRounds: 0,
-        locked: true,
-    };
-    /** Goal state exposed by the goal bar for the ACTIVE conversation. */
-    get goal() {
-        return this.conv.goal;
-    }
-    /** The browser has one dialog at a time, so wizard UI plumbing remains
-     * client-wide; review execution itself is per conversation. */
-    /** Settings-panel state (system prompt + disabled skills/extensions). The
-     *  resource-loader overrides in makeRuntimeFactory() read this at every
-     *  reload(), so session.reload() applies changes to the running runtime. */
-    settings;
-    /** Named settings presets (saved combos the user can re-apply). */
-    presets = [];
-    /** Settings changed while the run was streaming — the runtime reload is
-     *  deferred to the next agent_end so an in-flight run is never torn down. */
-    pendingSettingsReload = false;
-    /** Full (incl. disabled) skill/extension lists seen so far — disabled
-     *  entries disappear from the loader after reload, so this cache keeps them
-     *  visible (and re-enableable) in the settings panel. */
-    knownSkills = new Map();
-    knownExtensions = new Map();
-    /** Aborts the currently-running goal wizard (user clicked ✗ / timed out). Drives
-     *  the in-flight goal_ask dialog to resolve as cancelled and (via the run
-     *  signal) stops the wizard session's agent run. Recreated per wizard. */
-    wizardAbort = null;
-    /** The wizard's AgentSession while it runs — lets clearGoal truly terminate it
-     *  (abort the run), not just flip a flag. */
-    wizardSession = null;
-    /** Conversation that owns the one browser wizard currently in flight. */
-    wizardOwnerId = null;
-    /** True when the wizard was cancelled externally (✗ / clear_goal / timeout) —
-     *  startGoalWizard reads this after the run to avoid setting a goal. */
-    wizardCancelled = false;
-    /** Idle-timeout for the wizard: if no answer arrives within this window (a
-     *  dialog is up but the user doesn't respond), the wizard is auto-cancelled. */
-    static WIZARD_IDLE_TIMEOUT_MS = 5 * 60_000;
-    /** Absolute deadline for the whole wizard session (model latency guard). */
-    static WIZARD_MAX_TOTAL_MS = 20 * 60_000;
+    goalSvc;
+    /** Settings-panel state (system prompt + disabled skills/extensions) —
+     *  自包含模块，见 settings-service.ts。resource-loader overrides 在每次
+     *  reload() 时读 current 的最新值，session.reload() 即可应用到运行中 runtime。 */
+    settingsSvc; // 构造函数里创建（需要 clientId/stateStore）
     /** How long a hard abort waits for session.abort() to make the run idle
      *  before force-resetting the conversation (model streams that ignore the
      *  abort signal would otherwise leave the chat stuck forever). */
@@ -1174,19 +245,20 @@ export class ClientSession {
     /** Live AbortControllers of THIS client's running bash tool calls — aborting
      *  them kills only the command (agent run and conversation continue). */
     bashKills = new Set();
-    /** LISTENING-port snapshot taken when the current bash tool started — the
-     *  end-of-execution diff reveals servers the agent left running in the
-     *  background (e.g. `npm run dev &`). Keyed by port → pid. */
-    bashListenBefore = null;
-    /** Background servers the agent started (port → pid). Managed from the
-     *  后台任务 panel: each can be stopped individually or all at once. The
-     *  map lives on the CLIENT (not a conversation), so it survives
-     *  conversation switches/ends and only empties when a task is stopped or
-     *  its process exits on its own (pruned by refreshBgServers). */
-    bgServers = new Map();
-    /** Periodic pruner: re-snapshots listening ports and drops tracked entries
-     *  whose process died on its own, keeping the panel honest. */
-    bgTimer = null;
+    /** Background-server tracking (port snapshots + 后台任务 panel state) —
+     *  自包含模块，见 bg-servers.ts。列表按 CLIENT 存活，不随对话切换/结束消失。 */
+    /** 文件树 / 预览读写 / SCM 查询 / watcher —— 自包含模块，见 files-service.ts。 */
+    files = new FilesService({
+        emit: (msg) => this.emit(msg),
+        isDisposed: () => this.disposed,
+        getCwd: () => this.cwd,
+        getActiveCwd: () => this.conv?.cwd ?? this.cwd,
+    });
+    bg = new BgServerTracker({
+        emit: (msg) => this.emit(msg),
+        flushSnapshot: () => this.flushSnapshot(),
+        isDisposed: () => this.disposed,
+    });
     /** The active conversation (all session operations target it). */
     get conv() {
         const conv = this.convs.get(this.activeId);
@@ -1247,7 +319,6 @@ export class ClientSession {
      * prompt with the same images skips the vision API call entirely — editing
      * a question doesn't re-burn tokens on re-transcribing identical screenshots.
      */
-    visionBridgeCache = new Map();
     /** Most recent built-in (default) system prompt observed by the
      *  resource-loader override — surfaced via settings_state so the
      *  replace-mode editor can show the prompt it would otherwise replace.
@@ -1279,6 +350,9 @@ export class ClientSession {
     sinks = new Set();
     pendingNotices = [];
     snapshotTimer = null;
+    /** Timestamp of the most recent message_delta push — while fresh, snapshots
+     *  use the slower STREAMING_SNAPSHOT_INTERVAL_MS cadence. */
+    lastDeltaAt = 0;
     sessionsTimer = null;
     version = 0;
     /**
@@ -1296,31 +370,67 @@ export class ClientSession {
      *  filesystem — failures silently fall back to the poll. */
     fsWatcher = null;
     watchPath = null;
+    /** fs.watch on the active repo's git dir — external changes (CLI commit,
+     *  IDE branch switch) push `scm_changed` so the panel refreshes itself.
+     *  One watcher per client session, re-targeted when the queried cwd
+     *  changes; failures (bare repo, unsupported fs) silently disable it. */
+    gitWatcher = null;
+    gitWatchCwd = null;
+    gitDirtyTimer = null;
     watchTimer = null;
     constructor(clientId, cwd, agentDir, stateStore) {
         this.clientId = clientId;
         this.cwd = cwd;
         this.agentDir = agentDir;
         this.stateStore = stateStore;
-        this.settings = stateStore.getSettings(clientId);
-        this.presets = stateStore.getPresets(clientId);
+        this.settingsSvc = new SettingsService({
+            clientId,
+            stateStore,
+            emit: (msg) => this.emit(msg),
+            flushSnapshot: () => this.flushSnapshot(),
+            isDisposed: () => this.disposed,
+            getSession: () => this.session,
+            isStreaming: () => this.session.isStreaming,
+            reloadSession: async () => {
+                await this.session.reload();
+                await this.pushSlashCommands();
+            },
+            effectiveDefaultSystemPrompt: () => this.effectiveDefaultSystemPrompt(),
+        });
+        this.goalSvc = new GoalService({
+            clientId,
+            agentDir,
+            stateStore,
+            webUi: this.webUi,
+            emit: (msg) => this.emit(msg),
+            flushSnapshot: () => this.flushSnapshot(),
+            isDisposed: () => this.disposed,
+            quiesceBlocked: () => this.quiesceBlocked(),
+            activeConvId: () => this.activeId,
+            activeConv: () => this.conv,
+            getConv: (id) => this.convs.get(id),
+            cwd: () => this.cwd,
+            reviewSettings: () => this.settingsSvc.reviewPrefs,
+            gitDiff: (dir) => this.gitDiff(dir),
+        });
+        this.modelAdmin = new ModelAdminService({
+            agentDir,
+            emit: (msg) => this.emit(msg),
+            flushSnapshot: () => this.flushSnapshot(),
+            isDisposed: () => this.disposed,
+            modelRuntime: () => this.runtime.services.modelRuntime,
+            invalidatePiConfig: () => {
+                this.piCheckCache = null;
+            },
+            pushModels: async () => this.listModels(),
+        });
         // Prune dead background tasks every 30s (only spawns netstat/lsof while
         // the list is non-empty). unref: must not keep the process alive.
-        this.bgTimer = setInterval(() => void this.refreshBgServers(), 30_000);
-        this.bgTimer.unref?.();
+        this.bg.start();
     }
     static async create(clientId, cwd, stateStore) {
         const agentDir = process.env.PI_CODING_AGENT_DIR ?? getAgentDir();
         const cs = new ClientSession(clientId, cwd, agentDir, stateStore);
-        // Restore last-used goal/review preferences so model & rounds survive reload.
-        const gPrefs = stateStore.getGoalPrefs(clientId);
-        if (gPrefs) {
-            cs.goalReviewPrefs = {
-                reviewModel: gPrefs.reviewModel,
-                maxRounds: gPrefs.maxRounds,
-                locked: gPrefs.locked,
-            };
-        }
         const conversationId = cs.nextConversationId();
         const terminals = cs.makeTerminalManager(conversationId, cwd);
         const runtime = await createAgentSessionRuntime(cs.makeRuntimeFactory(terminals), {
@@ -1371,15 +481,15 @@ export class ClientSession {
                         if (typeof base === "string" && base) {
                             this.lastBaseSystemPrompt = base;
                         }
-                        return this.settings.promptMode === "replace" &&
-                            this.settings.customSystemPrompt.trim()
-                            ? this.settings.customSystemPrompt
+                        return this.settingsSvc.current.promptMode === "replace" &&
+                            this.settingsSvc.current.customSystemPrompt.trim()
+                            ? this.settingsSvc.current.customSystemPrompt
                             : base;
                     },
                     appendSystemPromptOverride: (base) => {
                         const out = [...base];
-                        const custom = this.settings.customSystemPrompt.trim();
-                        if (this.settings.promptMode === "append" && custom) {
+                        const custom = this.settingsSvc.current.customSystemPrompt.trim();
+                        if (this.settingsSvc.current.promptMode === "append" && custom) {
                             out.push(custom);
                         }
                         if (process.platform === "win32") {
@@ -1393,12 +503,12 @@ export class ClientSession {
                     // 技能开关：禁用的技能从系统提示词和 /skill: 目录中剔除。
                     skillsOverride: (res) => ({
                         ...res,
-                        skills: res.skills.filter((s) => !this.settings.disabledSkills.includes(s.name)),
+                        skills: res.skills.filter((s) => !this.settingsSvc.current.disabledSkills.includes(s.name)),
                     }),
                     // 插件开关：禁用的扩展整个卸载（工具 / 命令随之消失）。
                     extensionsOverride: (res) => ({
                         ...res,
-                        extensions: res.extensions.filter((e) => !this.settings.disabledExtensions.includes(extensionKey(e))),
+                        extensions: res.extensions.filter((e) => !this.settingsSvc.current.disabledExtensions.includes(extensionKey(e))),
                     }),
                 },
             });
@@ -1422,25 +532,7 @@ export class ClientSession {
     /** Create independent goal state for one conversation. Preferences are
      * client-wide defaults, while goal text/review progress is not shared. */
     makeGoalStatus() {
-        return {
-            conversationId: null,
-            goal: null,
-            reviewModel: this.goalReviewPrefs.reviewModel,
-            maxRounds: this.goalReviewPrefs.maxRounds,
-            locked: this.goalReviewPrefs.locked,
-            reviewing: false,
-            round: 0,
-            status: "",
-            verdict: "pending",
-            wizard: {
-                active: false,
-                draft: "",
-                model: null,
-                step: 0,
-                maxSteps: 6,
-                status: "",
-            },
-        };
+        return this.goalSvc.makeGoalStatus();
     }
     /** Allocate a stable conversation id before constructing its runtime/tools. */
     nextConversationId() {
@@ -1464,6 +556,7 @@ export class ClientSession {
             goalGeneration: 0,
             goalReviewGeneration: 0,
             wizardRunning: false,
+            deltaSeq: 0,
             terminals,
             msgIds: new Map(),
             nextMsgId: 1,
@@ -1500,13 +593,13 @@ export class ClientSession {
         void this.pushSlashCommands();
         // Reconnect: push the remembered goal prefs (model choice, rounds cap,
         // locked) so the goal bar restores them on reload — "全局记忆".
-        this.emitGoalStatus();
+        this.goalSvc.emitGoalStatus();
         // Reconnect: push the settings panel state (prompt text/mode, skill &
         // extension toggles, saved presets).
         this.pushSettings();
         // Reconnect: push the background-task list — it must survive reconnects
         // and outlive the conversation that started the tasks.
-        this.emitBgServers();
+        this.bg.push();
         // PTYs are conversation-owned and survive a socket reconnect.
         this.pushTerminals();
     }
@@ -1516,7 +609,7 @@ export class ClientSession {
         // conversation and can be inspected after reconnecting. Only conversation
         // disposal or server shutdown kills them.
         if (this.sinks.size === 0) {
-            this.unwatchDir();
+            this.files.unwatchDir();
         }
     }
     /** Broadcast to every connected socket of this client. */
@@ -1596,6 +689,8 @@ export class ClientSession {
                 if (event.id) {
                     this.emit({
                         type: "tool_delta",
+                        conversationId: conv.id,
+                        seq: ++conv.deltaSeq,
                         toolCallId: event.id,
                         toolName: "bash",
                         delta: event.delta,
@@ -1610,9 +705,7 @@ export class ClientSession {
                 // Snapshot listeners before a bash run — the post-run diff catches
                 // servers the agent started in the background.
                 if (event.toolName === "bash") {
-                    void snapshotListeningPorts().then((m) => {
-                        this.bashListenBefore = m;
-                    });
+                    this.bg.snapshotBefore();
                 }
                 this.armToolWatchdog(conv, event.toolCallId);
                 break;
@@ -1624,7 +717,7 @@ export class ClientSession {
                 // Bash finished — wait briefly for background servers to bind their
                 // ports, then diff against the pre-run snapshot and record them.
                 if (event.toolName === "bash")
-                    void this.trackBackgroundServers();
+                    void this.bg.trackAfterBash();
                 const durationMs = startedAt !== undefined ? Date.now() - startedAt : undefined;
                 // The bash tool does not put its exit code in result.details — on
                 // failure it throws "Command exited with code N" and the agent
@@ -1667,6 +760,8 @@ export class ClientSession {
                 if (text) {
                     this.emit({
                         type: "tool_delta",
+                        conversationId: conv.id,
+                        seq: ++conv.deltaSeq,
                         toolCallId: event.toolCallId,
                         toolName: event.toolName,
                         delta: text,
@@ -1682,7 +777,6 @@ export class ClientSession {
             // (new chat + first message, completed turns, compaction, etc.).
             case "agent_end": {
                 this.scheduleSessionsRefresh();
-                const g = conv.goal;
                 // Manual interrupt (Stop button / abort): the last assistant message
                 // carries stopReason "aborted". A half-finished run should NOT be
                 // reviewed (it would fail and inject a revision, only to be stopped
@@ -1693,38 +787,19 @@ export class ClientSession {
                     return a.role === "assistant" && a.stopReason === "aborted";
                 });
                 if (aborted) {
-                    if (g.goal && g.conversationId === conv.id) {
-                        conv.goalGeneration += 1;
-                        g.conversationId = null;
-                        g.goal = null;
-                        g.reviewing = false;
-                        g.verdict = "pending";
-                        g.feedback = undefined;
-                        g.status = "已手动停止，目标审查已中止";
-                        this.emitGoalStatus();
-                        this.emit({
-                            type: "notice",
-                            level: "warning",
-                            text: "⏹ 已手动停止，目标审查已中止（想继续可重新设定目标）",
-                        });
+                    const stopNotice = this.goalSvc.onAgentEnd(conv, true);
+                    if (stopNotice) {
+                        this.emit({ type: "notice", level: "warning", text: stopNotice });
                     }
                     break;
                 }
-                // Goal review hook: after the run finished normally, if a goal is
-                // active (and it belonged to the ACTIVE conversation) and we're not
-                // already mid-review, spawn the isolated reviewer.
-                if (g.goal &&
-                    g.conversationId === conv.id &&
-                    !g.reviewing &&
-                    !conv.wizardRunning &&
-                    !this.disposed) {
-                    void this.runGoalReview(conv);
-                }
+                // Goal review hook lives in GoalService.onAgentEnd(conv, false).
+                this.goalSvc.onAgentEnd(conv, false);
                 // Deferred settings reload: settings (system prompt / skills /
                 // extensions) changed while the run was streaming — applying now
                 // would have torn down the in-flight run.
-                if (this.pendingSettingsReload && !this.disposed) {
-                    this.pendingSettingsReload = false;
+                if (this.settingsSvc.hasPendingReload() && !this.disposed) {
+                    this.settingsSvc.consumePendingReload();
                     void this.applySettingsReload();
                 }
                 break;
@@ -1732,10 +807,57 @@ export class ClientSession {
             case "entry_appended":
                 this.scheduleSessionsRefresh();
                 break;
+            case "message_update": {
+                // Live assistant-message increment, deliberately OUTSIDE the snapshot
+                // channel: send() drops snapshots under backpressure (big sessions),
+                // but this small message must always get through or the UI freezes on
+                // stale state. Only the ACTIVE conversation streams to the browser —
+                // background conversations would clobber the streaming view; their
+                // state arrives via snapshot when switched to.
+                if (conv.id !== this.conv.id)
+                    break;
+                const ame = event.assistantMessageEvent;
+                const m = event.message;
+                this.lastDeltaAt = Date.now();
+                this.emit({
+                    type: "message_delta",
+                    conversationId: conv.id,
+                    seq: ++conv.deltaSeq,
+                    // Must match serializeStreamingMessage()'s stable id so deltas
+                    // patch onto the snapshot's streamingMessage and reconcile.
+                    messageId: `stream-${m?.timestamp ?? 0}`,
+                    usage: (() => {
+                        try {
+                            const t = this.session.getSessionStats().tokens;
+                            return t ? { input: t.input, output: t.output, total: t.total } : null;
+                        }
+                        catch {
+                            return null;
+                        }
+                    })(),
+                    // Strip `partial` (the cumulative message): re-serializing it per
+                    // token is exactly what we're trying to avoid. The next snapshot
+                    // carries the authoritative full message anyway.
+                    assistantMessageEvent: {
+                        type: ame.type,
+                        contentIndex: "contentIndex" in ame ? ame.contentIndex : undefined,
+                        delta: "delta" in ame ? ame.delta : undefined,
+                    },
+                });
+                break;
+            }
             default:
                 break;
         }
-        this.scheduleSnapshot();
+        // Snapshot checkpoint policy: deltas carry live rendering during streaming;
+        // full snapshots are reconciliation checkpoints taken immediately at
+        // run/tool boundaries and on a slow timer otherwise.
+        if (event.type === "agent_end" || event.type === "tool_execution_end") {
+            this.flushSnapshot();
+        }
+        else {
+            this.scheduleSnapshot();
+        }
     }
     /** Debounced push of the persisted session list + open conversations. */
     scheduleSessionsRefresh() {
@@ -1748,6 +870,7 @@ export class ClientSession {
             this.emitConversations();
             void this.pushSessions();
         }, 800);
+        // pushSessions no-ops unless the client opted in via list_sessions.
     }
     /** Serialize a persisted message with a STABLE id + cached object reference. */
     serializeCached(m) {
@@ -2147,727 +1270,73 @@ export class ClientSession {
         }
         this.flushSnapshot();
     }
-    /** Persist an api-key credential for a provider (auth.json) and apply it now. */
-    async setProviderApiKey(provider, apiKey) {
-        const key = apiKey.trim();
-        if (!provider.trim()) {
-            this.emit({ type: "notice", level: "error", text: "请填写服务商 ID" });
-            return;
-        }
-        if (!key) {
-            this.emit({ type: "notice", level: "error", text: "请填写 API 密钥" });
-            return;
-        }
-        try {
-            // Persist to auth.json (auth.json shape: { <provider>: { type: "api_key", key } }).
-            const authPath = join(this.agentDir, "auth.json");
-            mkdirSync(this.agentDir, { recursive: true });
-            let data = {};
-            try {
-                data = JSON.parse(readFileSync(authPath, "utf8"));
-            }
-            catch {
-                // no file yet / unparsable — start fresh
-            }
-            data[provider.trim()] = { type: "api_key", key };
-            writeFileSync(authPath, JSON.stringify(data, null, 2) + "\n");
-            // Apply immediately for this session (runtime credentials are cached), then
-            // refresh models. allowNetwork downloads the provider's official model
-            // catalog (openai/anthropic/… are dynamic providers with no built-in list).
-            const mr = this.runtime.services.modelRuntime;
-            await mr.setRuntimeApiKey(provider.trim(), key);
-            await mr.refresh({ allowNetwork: true });
-            this.piCheckCache = null;
-            this.emit({
-                type: "notice",
-                level: "info",
-                text: `✅ 已保存 ${provider.trim()} 的 API 密钥并刷新模型列表`,
-            });
-            await this.listModels();
-            await this.listProviders();
-        }
-        catch (err) {
-            this.emit({
-                type: "notice",
-                level: "error",
-                text: `保存 API 密钥失败：${err.message}`,
-            });
+    /** Send a snapshot immediately (cancels any pending throttled one). */
+    flushSnapshot() {
+        if (this.snapshotTimer) {
+            clearTimeout(this.snapshotTimer);
+            this.snapshotTimer = null;
         }
-        this.flushSnapshot();
+        if (!this.disposed)
+            this.emit({ type: "snapshot", state: this.snapshot() });
     }
-    /** Enumerate pi's built-in providers with auth status (key-only config). */
-    async listProviders() {
-        const mr = this.runtime.services.modelRuntime;
-        let providers;
-        try {
-            providers = mr.getProviders().map((p) => {
-                try {
-                    const st = mr.getProviderAuthStatus(p.id);
-                    return {
-                        id: p.id,
-                        name: p.name,
-                        configured: st?.configured ?? false,
-                        source: st?.source,
-                    };
-                }
-                catch {
-                    // One odd provider must not blank the whole list.
-                    return { id: p.id, name: p.name, configured: false };
-                }
-            });
-        }
-        catch (err) {
-            this.emit({
-                type: "notice",
-                level: "error",
-                text: `获取服务商列表失败：${err.message}`,
-            });
+    scheduleSnapshot() {
+        if (this.snapshotTimer || this.disposed)
             return;
-        }
-        if (providers.length === 0) {
-            this.emit({
-                type: "notice",
-                level: "warning",
-                text: "服务商列表为空——pi 运行时未注册任何提供商",
-            });
-        }
-        this.emit({ type: "providers_status", providers });
-    }
-    // ---------------------------------------------------------------------------
-    // Custom model config (agentDir/models.json)
-    // ---------------------------------------------------------------------------
-    modelsConfigPath() {
-        return join(this.agentDir, "models.json");
-    }
-    /** Strip // and /* *\/ comments without touching string literals (URLs contain //). */
-    static stripJsonComments(src) {
-        let out = "";
-        let inString = false;
-        let i = 0;
-        while (i < src.length) {
-            const c = src[i];
-            const next = src[i + 1];
-            if (inString) {
-                out += c;
-                if (c === "\\") {
-                    out += next ?? "";
-                    i += 2;
-                    continue;
-                }
-                if (c === '"')
-                    inString = false;
-                i++;
-                continue;
-            }
-            if (c === '"') {
-                inString = true;
-                out += c;
-                i++;
-                continue;
-            }
-            if (c === "/" && next === "/") {
-                while (i < src.length && src[i] !== "\n")
-                    i++;
-                continue;
-            }
-            if (c === "/" && next === "*") {
-                i += 2;
-                while (i < src.length && !(src[i] === "*" && src[i + 1] === "/"))
-                    i++;
-                i += 2;
-                continue;
-            }
-            out += c;
-            i++;
-        }
-        return out;
-    }
-    /** Read + parse models.json (tolerating // and /* *\/ comments like the SDK). */
-    readModelsConfig() {
-        const path = this.modelsConfigPath();
-        try {
-            const raw = readFileSync(path, "utf8");
-            const parsed = JSON.parse(ClientSession.stripJsonComments(raw));
-            return { providers: parsed?.providers ?? {} };
-        }
-        catch {
-            return { providers: {} };
-        }
-    }
-    /** Send the current models.json custom providers to the client. */
-    async listModelsConfig() {
-        const { providers } = this.readModelsConfig();
-        const list = Object.entries(providers).map(([providerId, p]) => {
-            const models = Array.isArray(p.models)
-                ? p.models.map((m) => ({
-                    id: String(m.id ?? ""),
-                    name: m.name,
-                    reasoning: m.reasoning,
-                    input: Array.isArray(m.input) ? m.input : undefined,
-                    contextWindow: m.contextWindow,
-                    maxTokens: m.maxTokens,
-                }))
-                : [];
-            return {
-                providerId,
-                name: p.name,
-                api: p.api,
-                baseUrl: p.baseUrl,
-                apiKey: p.apiKey,
-                authHeader: p.authHeader,
-                // headers are intentionally NOT sent to the browser — they may
-                // contain Authorization / API-key values; kept server-side only.
-                models,
-            };
-        });
-        this.emit({ type: "models_config", providers: list });
-    }
-    /** Numeric metadata value (NaN/string "unknown" → undefined). */
-    static numMeta(v) {
-        return typeof v === "number" && Number.isFinite(v) ? v : undefined;
-    }
-    static boolMeta(v) {
-        return typeof v === "boolean" ? v : undefined;
-    }
-    static strArrMeta(v) {
-        return Array.isArray(v)
-            ? v.filter((x) => typeof x === "string")
-            : undefined;
-    }
-    /** Best-effort extraction of model metadata from an OpenAI-compatible
-     *  /models `data[]` item. Most endpoints only return `{ id }` — the extra
-     *  fields (context_window / max_model_len / modalities / supports_vision /
-     *  reasoning / display_name) come from vLLM and other extended
-     *  implementations, and are filled into the form when present. */
-    static parseOpenAiModel(m) {
-        const r = (m ?? {});
-        const id = typeof r.id === "string" ? r.id : "";
-        const name = (typeof r.name === "string" && r.name.trim() ? r.name : undefined) ??
-            (typeof r.display_name === "string" && r.display_name.trim()
-                ? r.display_name
-                : undefined);
-        const modalities = ClientSession.strArrMeta(r.modalities) ??
-            ClientSession.strArrMeta(r.input_modalities);
-        const vision = modalities?.includes("image") === true ||
-            ClientSession.boolMeta(r.supports_vision) === true ||
-            ClientSession.boolMeta(r.vision) === true ||
-            ClientSession.strArrMeta(r.input)?.includes("image") === true;
-        const reasoning = ClientSession.boolMeta(r.reasoning) === true ||
-            ClientSession.boolMeta(r.supports_reasoning) === true ||
-            modalities?.includes("reasoning") === true;
-        const contextWindow = ClientSession.numMeta(r.context_window) ??
-            ClientSession.numMeta(r.context_length) ??
-            ClientSession.numMeta(r.max_model_len) ??
-            ClientSession.numMeta(r.max_context_length);
-        const maxTokens = ClientSession.numMeta(r.max_tokens) ??
-            ClientSession.numMeta(r.max_output_tokens) ??
-            ClientSession.numMeta(r.max_completion_tokens);
-        return {
-            id,
-            ...(name ? { name } : {}),
-            ...(reasoning ? { reasoning: true } : {}),
-            ...(vision ? { input: ["text", "image"] } : {}),
-            ...(contextWindow ? { contextWindow } : {}),
-            ...(maxTokens ? { maxTokens } : {}),
-        };
-    }
-    /** google-generative-ai /models shape:
-     *  { models: [{ name: "models/gemini-flash", displayName, inputTokenLimit,
-     *               outputTokenLimit, supportedGenerationMethods }] } */
-    static parseGoogleModel(m) {
-        const r = (m ?? {});
-        const rawName = typeof r.name === "string" ? r.name : "";
-        const id = rawName.replace(/^models\//, "");
-        const displayName = typeof r.displayName === "string" ? r.displayName : undefined;
-        return {
-            id,
-            ...(displayName && displayName !== id ? { name: displayName } : {}),
-            ...(ClientSession.numMeta(r.inputTokenLimit)
-                ? { contextWindow: ClientSession.numMeta(r.inputTokenLimit) }
-                : {}),
-            ...(ClientSession.numMeta(r.outputTokenLimit)
-                ? { maxTokens: ClientSession.numMeta(r.outputTokenLimit) }
-                : {}),
-        };
+        // During active streaming the deltas carry live rendering — full snapshots
+        // are just a periodic reconciliation checkpoint, so send them far less
+        // often (they serialize the whole session; big sessions made this path OOM).
+        const interval = Date.now() - this.lastDeltaAt < DELTA_ACTIVE_WINDOW_MS
+            ? STREAMING_SNAPSHOT_INTERVAL_MS
+            : SNAPSHOT_INTERVAL_MS;
+        this.snapshotTimer = setTimeout(() => {
+            this.snapshotTimer = null;
+            if (!this.disposed)
+                this.emit({ type: "snapshot", state: this.snapshot() });
+        }, interval);
+    }
+    /** Slash-command catalog + native command execution — 自包含模块，见
+     *  slash-commands.ts（内置命令拦截 + 扩展/模板/技能目录推送）。 */
+    slash = new SlashCommandsService({
+        emit: (msg) => this.emit(msg),
+        cwd: () => this.cwd,
+        getSession: () => this.session,
+        newChat: () => this.newChat(),
+        setModel: (id) => this.setModel(id),
+        setCwd: (path) => this.setCwd(path),
+        setThinking: (level) => this.setThinking(level),
+        refreshSessions: () => this.refreshSessions(),
+        onQuit: () => this.onQuit?.() ?? false,
+    });
+    /** Catalog push — index.ts get_commands / attach / cwd 切换等都会调用。 */
+    pushSlashCommands() {
+        return this.slash.push();
     }
-    /** Probe a custom provider's OpenAI-compatible /models endpoint (server-side
-     *  because the baseUrl is often a LAN/loopback host the browser can't reach
-     *  cross-origin) and return the advertised models. reqId is echoed back
-     *  in fetch_models_result so the UI can match concurrent requests. */
-    async fetchModelsList(reqId, baseUrl, apiKey, authHeader, api) {
-        const emitError = (error) => this.emit({ type: "fetch_models_result", reqId, ok: false, error });
-        const base = (baseUrl ?? "").trim().replace(/\/+$/, "");
-        if (!base)
-            return emitError("请先填写 baseUrl");
-        let url;
-        try {
-            url = new URL(base);
-        }
-        catch {
-            return emitError(`baseUrl 无效：${base}`);
-        }
-        if (url.protocol !== "http:" && url.protocol !== "https:") {
-            return emitError("baseUrl 仅支持 http/https");
-        }
-        const headers = {};
-        // Per-api auth conventions (mirror pi's built-in provider configs):
-        //   openai-*:      Authorization: Bearer <key>
-        //   anthropic:     x-api-key + anthropic-version
-        //   google:        x-goog-api-key
-        // authHeader=false → no auth header at all (custom gateways).
-        if (apiKey?.trim() && authHeader !== false) {
-            const key = apiKey.trim();
-            if (api === "anthropic-messages") {
-                headers["x-api-key"] = key;
-                headers["anthropic-version"] = "2023-06-01";
-            }
-            else if (api === "google-generative-ai") {
-                headers["x-goog-api-key"] = key;
-            }
-            else {
-                headers["Authorization"] = `Bearer ${key}`;
-            }
-        }
-        const tryFetch = async (u) => {
-            const ac = new AbortController();
-            const timer = setTimeout(() => ac.abort(), 15000);
-            try {
-                return await fetch(u, { headers, signal: ac.signal });
-            }
-            catch (err) {
-                if (err.name === "AbortError") {
-                    emitError("请求超时（15 秒）");
-                }
-                else {
-                    emitError(`请求失败：${err.message}`);
-                }
-                return null;
-            }
-            finally {
-                clearTimeout(timer);
-            }
-        };
-        let res = await tryFetch(`${base}/models`);
-        // BaseUrls that omit the /v1 prefix (e.g. https://api.openai.com) 404 on
-        // the bare path — retry under /v1.
-        if (res && res.status === 404 && !/\/v\d+[a-z-]*$/.test(base)) {
-            res = await tryFetch(`${base}/v1/models`);
-        }
-        if (!res)
-            return;
-        if (!res.ok) {
-            let detail = "";
-            try {
-                detail = (await res.text()).slice(0, 200);
-            }
-            catch {
-                // response body already consumed / not text — ignore
-            }
-            return emitError(`接口返回 HTTP ${res.status}${detail ? `：${detail}` : ""}`);
-        }
-        let models = [];
-        try {
-            const json = (await res.json());
-            const data = Array.isArray(json.data) ? json.data : null;
-            if (data) {
-                // OpenAI-compatible: { data: [{ id, context_window, modalities, … }] }
-                models = data
-                    .map((m) => ClientSession.parseOpenAiModel(m))
-                    .filter((m) => m.id);
-            }
-            else if (Array.isArray(json.models)) {
-                // Google: { models: [{ name: "models/…", displayName, … }] }
-                models = json.models
-                    .map((m) => ClientSession.parseGoogleModel(m))
-                    .filter((m) => m.id);
-            }
-        }
-        catch {
-            return emitError("响应不是有效的 JSON");
-        }
-        // Dedupe by id (keep the first, most complete entry) and sort by id.
-        const seen = new Set();
-        models = models
-            .filter((m) => (seen.has(m.id) ? false : (seen.add(m.id), true)))
-            .sort((a, b) => a.id.localeCompare(b.id));
-        if (models.length === 0)
-            return emitError("接口未返回任何模型");
-        this.emit({ type: "fetch_models_result", reqId, ok: true, models });
+    /** 模型/服务商配置管理 —— 自包含模块，见 model-admin.ts。 */
+    modelAdmin;
+    /** Persist an api-key credential for a provider (auth.json). */
+    setProviderApiKey(provider, apiKey) {
+        return this.modelAdmin.setProviderApiKey(provider, apiKey);
     }
-    /** Upsert one provider into models.json and hot-reload the model runtime. */
-    async saveModelConfig(providerId, config) {
-        const pid = providerId.trim();
-        if (!pid || !/^[\w.-]+$/.test(pid)) {
-            this.emit({
-                type: "notice",
-                level: "error",
-                text: "服务商 ID 无效（仅字母/数字/._-）",
-            });
-            return;
-        }
-        const models = (config.models ?? [])
-            .filter((m) => m.id && m.id.trim())
-            .map((m) => ({
-            id: m.id.trim(),
-            ...(m.name?.trim() ? { name: m.name.trim() } : {}),
-            ...(m.reasoning ? { reasoning: true } : {}),
-            ...(m.input?.length ? { input: m.input } : {}),
-            ...(m.contextWindow ? { contextWindow: Number(m.contextWindow) } : {}),
-            ...(m.maxTokens ? { maxTokens: Number(m.maxTokens) } : {}),
-        }));
-        if (models.length === 0) {
-            this.emit({ type: "notice", level: "error", text: "至少需要一个模型" });
-            return;
-        }
-        try {
-            const { providers } = this.readModelsConfig();
-            // headers never reach the browser, so the incoming config can't carry
-            // them — preserve the previously stored values when they are absent.
-            const prevHeaders = providers[pid]?.headers;
-            providers[pid] = {
-                ...(config.name?.trim() ? { name: config.name.trim() } : {}),
-                ...(config.api?.trim() ? { api: config.api.trim() } : {}),
-                ...(config.baseUrl?.trim() ? { baseUrl: config.baseUrl.trim() } : {}),
-                ...(config.apiKey?.trim() ? { apiKey: config.apiKey.trim() } : {}),
-                ...(config.authHeader ? { authHeader: true } : {}),
-                ...(prevHeaders && Object.keys(prevHeaders).length > 0
-                    ? { headers: prevHeaders }
-                    : {}),
-                models,
-            };
-            mkdirSync(this.agentDir, { recursive: true });
-            writeFileSync(this.modelsConfigPath(), JSON.stringify({ providers }, null, 2) + "\n");
-            // Allow a custom models.json entry to reuse the provider credential
-            // already stored in auth.json.  Seed the shared runtime too, because
-            // older pi-ai versions did not always fall back to stored credentials
-            // for a newly-created custom provider.  Never copy the secret into
-            // models.json.
-            try {
-                const auth = JSON.parse(readFileSync(join(this.agentDir, "auth.json"), "utf8"));
-                const credential = auth[pid];
-                if (credential &&
-                    typeof credential === "object" &&
-                    "key" in credential &&
-                    typeof credential.key === "string" &&
-                    credential.key.trim()) {
-                    await this.runtime.services.modelRuntime.setRuntimeApiKey(pid, credential.key);
-                }
-            }
-            catch {
-                // auth.json is optional; models.json can still use its own apiKey.
-            }
-            await this.runtime.services.modelRuntime.refresh();
-            await this.listModelsConfig();
-            await this.listModels();
-            this.emit({
-                type: "notice",
-                level: "info",
-                text: `✅ 已保存服务商 ${pid}（${models.length} 个模型）并刷新模型列表`,
-            });
-        }
-        catch (err) {
-            this.emit({
-                type: "notice",
-                level: "error",
-                text: `保存模型配置失败：${err.message}`,
-            });
-        }
-        this.flushSnapshot();
+    clearProviderApiKey(provider) {
+        return this.modelAdmin.clearProviderApiKey(provider);
     }
-    /** Remove a provider from models.json and hot-reload. */
-    async deleteModelConfig(providerId) {
-        try {
-            const { providers } = this.readModelsConfig();
-            if (!(providerId in providers)) {
-                this.emit({
-                    type: "notice",
-                    level: "info",
-                    text: `服务商 ${providerId} 不存在`,
-                });
-                return;
-            }
-            delete providers[providerId];
-            writeFileSync(this.modelsConfigPath(), JSON.stringify({ providers }, null, 2) + "\n");
-            await this.runtime.services.modelRuntime.refresh();
-            await this.listModelsConfig();
-            await this.listModels();
-            this.emit({
-                type: "notice",
-                level: "info",
-                text: `🗑  已删除服务商 ${providerId}`,
-            });
-        }
-        catch (err) {
-            this.emit({
-                type: "notice",
-                level: "error",
-                text: `删除模型配置失败：${err.message}`,
-            });
-        }
-        this.flushSnapshot();
+    listProviders() {
+        return this.modelAdmin.listProviders();
     }
-    /** Send a snapshot immediately (cancels any pending throttled one). */
-    flushSnapshot() {
-        if (this.snapshotTimer) {
-            clearTimeout(this.snapshotTimer);
-            this.snapshotTimer = null;
-        }
-        if (!this.disposed)
-            this.emit({ type: "snapshot", state: this.snapshot() });
+    listModelsConfig() {
+        return this.modelAdmin.listModelsConfig();
     }
-    scheduleSnapshot() {
-        if (this.snapshotTimer || this.disposed)
-            return;
-        this.snapshotTimer = setTimeout(() => {
-            this.snapshotTimer = null;
-            if (!this.disposed)
-                this.emit({ type: "snapshot", state: this.snapshot() });
-        }, SNAPSHOT_INTERVAL_MS);
+    fetchModelsList(reqId, baseUrl, apiKey, authHeader, api) {
+        return this.modelAdmin.fetchModelsList(reqId, baseUrl, apiKey, authHeader, api);
     }
-    // ---------------------------------------------------------------------------
-    // Slash commands
-    // ---------------------------------------------------------------------------
-    /**
-     * Slash commands implemented natively by the web server (the pi CLI's built-in
-     * interactive commands like /model and /new are NOT handled by the SDK's
-     * prompt() — without this they'd be sent to the model as plain text). Keep in
-     * sync with execNativeCommand(). /help and /copy are client-side UI actions
-     * (they never reach the server) but stay listed so the picker shows them.
-     */
-    static NATIVE_COMMANDS = [
-        { name: "new", description: "新建对话", descriptionEn: "New chat" },
-        { name: "model", description: "切换模型", descriptionEn: "Switch model", argumentHint: "[名称]", argumentHintEn: "[name]" },
-        { name: "compact", description: "压缩上下文", descriptionEn: "Compact context", argumentHint: "[说明]", argumentHintEn: "[instructions]" },
-        { name: "cwd", description: "切换工作目录", descriptionEn: "Switch workspace", argumentHint: "<路径>", argumentHintEn: "<path>" },
-        {
-            name: "thinking",
-            description: "设置思考强度",
-            descriptionEn: "Set thinking level",
-            argumentHint: "<off|low|medium|high|xhigh|max>",
-            argumentHintEn: "<off|low|medium|high|xhigh|max>",
-        },
-        { name: "resume", description: "刷新会话列表", descriptionEn: "Refresh session list" },
-        { name: "reload", description: "重新加载扩展、技能与模板", descriptionEn: "Reload extensions, skills & templates" },
-        { name: "help", description: "显示全部命令", descriptionEn: "Show all commands" },
-        { name: "copy", description: "复制上一条助手回复", descriptionEn: "Copy last assistant reply" },
-        { name: "pi-web-ui:quit", description: "退出服务", descriptionEn: "Quit server (supervisor will restart)" },
-    ];
-    /** Parse a prompt into "/command args" — returns null when it isn't one. */
-    parseSlash(text) {
-        const trimmed = text.trim();
-        if (!trimmed.startsWith("/"))
-            return null;
-        const m = trimmed.match(/^\/([^\s]+)\s*([\s\S]*)$/);
-        if (!m || !m[1])
-            return null;
-        return { name: m[1], args: m[2].trim() };
+    refreshProviderModels(providerId, reqId) {
+        return this.modelAdmin.refreshProviderModels(providerId, reqId);
     }
-    /** Run a native slash command (see NATIVE_COMMANDS). Returns false when the
-     *  name is not a native command (the prompt falls through to the SDK). */
-    async execNativeCommand(name, args) {
-        switch (name) {
-            case "new":
-                await this.newChat();
-                return true;
-            case "model": {
-                if (!args) {
-                    const current = this.session.model;
-                    this.emit({
-                        type: "notice",
-                        level: "info",
-                        text: current
-                            ? `当前模型：${current.name}（${current.provider}/${current.id}）。用法：/model <名称>`
-                            : `用法：/model <名称>`,
-                    });
-                    return true;
-                }
-                const query = args.toLowerCase();
-                const available = await this.session.modelRuntime.getAvailable();
-                // Prefer an exact "provider/id" match, else id/name substring.
-                const exact = available.find((m) => m.provider + "/" + m.id === args.trim());
-                const matches = exact
-                    ? [exact]
-                    : available.filter((m) => m.id.toLowerCase().includes(query) ||
-                        m.name.toLowerCase().includes(query) ||
-                        m.provider.toLowerCase().includes(query));
-                if (matches.length === 0) {
-                    this.emit({
-                        type: "notice",
-                        level: "error",
-                        text: `没有匹配到模型：${args}（可用模型见顶栏模型列表）`,
-                    });
-                    return true;
-                }
-                const pick = matches[0];
-                if (matches.length > 1) {
-                    this.emit({
-                        type: "notice",
-                        level: "warning",
-                        text: `找到 ${matches.length} 个匹配模型，已选用：${pick.name}（精确匹配请用 provider/id）`,
-                    });
-                }
-                await this.setModel(`${pick.provider}/${pick.id}`);
-                return true;
-            }
-            case "compact":
-                try {
-                    await this.session.compact(args || undefined);
-                }
-                catch (err) {
-                    this.emit({
-                        type: "notice",
-                        level: "error",
-                        text: `压缩上下文失败：${err.message}`,
-                    });
-                }
-                return true;
-            case "cwd":
-                if (!args) {
-                    this.emit({
-                        type: "notice",
-                        level: "info",
-                        text: `当前工作目录：${this.cwd}。用法：/cwd <路径>`,
-                    });
-                }
-                else {
-                    await this.setCwd(args);
-                }
-                return true;
-            case "thinking": {
-                const ALIAS = {
-                    off: "off",
-                    minimal: "minimal",
-                    low: "low",
-                    medium: "medium",
-                    high: "high",
-                    xhigh: "xhigh",
-                    max: "max",
-                    关闭: "off",
-                    极简: "minimal",
-                    低: "low",
-                    中: "medium",
-                    高: "high",
-                    极高: "xhigh",
-                    最大: "max",
-                };
-                const level = ALIAS[args.trim().toLowerCase()];
-                if (!level) {
-                    this.emit({
-                        type: "notice",
-                        level: "error",
-                        text: `无效的思考强度：${args || "（空）"}。可用：off / minimal / low / medium / high / xhigh / max`,
-                    });
-                    return true;
-                }
-                this.setThinking(level);
-                return true;
-            }
-            case "resume":
-                await this.refreshSessions();
-                this.emit({
-                    type: "notice",
-                    level: "info",
-                    text: "会话列表已刷新，请在左侧「历史对话」中选择",
-                });
-                return true;
-            case "reload":
-                try {
-                    // Re-discovers extensions / skills / prompt templates from disk and
-                    // re-pushes the picker catalog (the CLI's /reload semantics).
-                    await this.session.reload();
-                    await this.pushSlashCommands();
-                    this.emit({
-                        type: "notice",
-                        level: "info",
-                        text: "已重新加载扩展、技能与提示模板",
-                    });
-                }
-                catch (err) {
-                    this.emit({
-                        type: "notice",
-                        level: "error",
-                        text: `重新加载失败：${err.message}`,
-                    });
-                }
-                return true;
-            case "pi-web-ui:quit": {
-                this.emit({
-                    type: "notice",
-                    level: "info",
-                    text: "正在退出 pi-web-ui… supervisor 将自动重启服务",
-                });
-                setTimeout(() => {
-                    const didSchedule = this.onQuit?.() ?? false;
-                    if (!didSchedule) {
-                        setTimeout(() => process.exit(0), 100);
-                    }
-                }, 300);
-                return true;
-            }
-            case "help":
-            case "copy":
-                // Client-side UI actions — the client handles them before sending;
-                // swallow here so the SDK never sees them as plain prompt text.
-                return true;
-            default:
-                return false;
-        }
+    saveModelConfig(providerId, config) {
+        return this.modelAdmin.saveModelConfig(providerId, config);
     }
-    /**
-     * Catalog of slash commands for the chat input: web-native builtins first,
-     * then the SDK's invokable commands for the ACTIVE conversation (extension
-     * commands, prompt templates, skills) — the same set the SDK expands when a
-     * prompt text starts with "/" (see AgentSession.prompt).
-     */
-    async pushSlashCommands() {
-        const commands = [];
-        const seen = new Set();
-        for (const c of ClientSession.NATIVE_COMMANDS) {
-            commands.push({ ...c, source: "builtin" });
-            seen.add(c.name);
-        }
-        try {
-            const s = this.session;
-            // Extension commands — the SDK already suffixes collisions with builtin
-            // names ("new:2"), and those still reach the SDK since execNativeCommand
-            // only intercepts the exact native names.
-            for (const cmd of s.extensionRunner.getRegisteredCommands()) {
-                if (seen.has(cmd.invocationName))
-                    continue;
-                commands.push({
-                    name: cmd.invocationName,
-                    description: cmd.description,
-                    source: "extension",
-                });
-                seen.add(cmd.invocationName);
-            }
-            // Prompt templates: /templatename args
-            for (const t of s.promptTemplates) {
-                if (seen.has(t.name))
-                    continue;
-                commands.push({
-                    name: t.name,
-                    description: t.description,
-                    source: "prompt",
-                });
-                seen.add(t.name);
-            }
-            // Skills: /skill:name args
-            for (const skill of s.resourceLoader.getSkills().skills) {
-                const name = `skill:${skill.name}`;
-                if (seen.has(name))
-                    continue;
-                commands.push({
-                    name,
-                    description: skill.description,
-                    source: "skill",
-                });
-            }
-        }
-        catch {
-            // Session not ready yet — native-only catalog still serves the picker.
-        }
-        this.emit({ type: "slash_commands", commands });
+    deleteModelConfig(providerId) {
+        return this.modelAdmin.deleteModelConfig(providerId);
     }
     // ---------------------------------------------------------------------------
     // Settings (system prompt / skills / extensions / presets)
@@ -2876,231 +1345,31 @@ export class ClientSession {
      *  with enabled flags + saved presets). Pushed on attach and after every
      *  settings change. */
     pushSettings() {
-        const disabledSkills = new Set(this.settings.disabledSkills);
-        const reviewDisabledSkills = new Set(this.settings.reviewDisabledSkills);
-        const disabledExts = new Set(this.settings.disabledExtensions);
-        try {
-            // Refresh the cache with the CURRENTLY loaded set (post-filter).
-            for (const s of this.session.resourceLoader.getSkills().skills) {
-                this.knownSkills.set(s.name, {
-                    name: s.name,
-                    description: s.description,
-                    enabled: true,
-                });
-            }
-            for (const e of this.session.resourceLoader.getExtensions().extensions) {
-                const id = extensionKey(e);
-                const p = e.sourceInfo?.path ?? e.path;
-                this.knownExtensions.set(id, {
-                    id,
-                    name: e.sourceInfo?.origin === "package" && e.sourceInfo.source
-                        ? e.sourceInfo.source
-                        : basename(p),
-                    path: p,
-                    enabled: true,
-                });
-            }
-        }
-        catch {
-            // Session not ready yet — keep whatever we already know.
-        }
-        // Disabled entries are filtered out of the loader — keep them in the
-        // panel (with the last-known description) so they can be re-enabled.
-        for (const name of this.settings.disabledSkills) {
-            if (!this.knownSkills.has(name)) {
-                this.knownSkills.set(name, { name, description: "", enabled: false });
-            }
-        }
-        for (const id of this.settings.disabledExtensions) {
-            if (!this.knownExtensions.has(id)) {
-                this.knownExtensions.set(id, {
-                    id,
-                    name: id.startsWith("npm:") ? id : basename(id),
-                    path: "",
-                    enabled: false,
-                });
-            }
-        }
-        const skills = [...this.knownSkills.values()]
-            .map((s) => ({ ...s, enabled: !disabledSkills.has(s.name) }))
-            .sort((a, b) => a.name.localeCompare(b.name));
-        const reviewSkills = [...this.knownSkills.values()]
-            .map((s) => ({ ...s, enabled: !reviewDisabledSkills.has(s.name) }))
-            .sort((a, b) => a.name.localeCompare(b.name));
-        const extensions = [...this.knownExtensions.values()]
-            .map((e) => ({ ...e, enabled: !disabledExts.has(e.id) }))
-            .sort((a, b) => a.name.localeCompare(b.name));
-        this.emit({
-            type: "settings_state",
-            settings: {
-                promptMode: this.settings.promptMode,
-                customSystemPrompt: this.settings.customSystemPrompt,
-                visionBridgeEnabled: this.settings.visionBridgeEnabled,
-                visionBridgeModel: this.settings.visionBridgeModel,
-                visionBridgePromptMode: this.settings.visionBridgePromptMode,
-                visionBridgePrompt: this.settings.visionBridgePrompt,
-                reviewPrompt: this.settings.reviewPrompt,
-                reviewDisabledSkills: [...this.settings.reviewDisabledSkills],
-                // The built-in prompts, so the replace-mode editors can prefill the
-                // text they would otherwise replace (empty until the resource-loader
-                // has run once for the system prompt).
-                defaultSystemPrompt: this.effectiveDefaultSystemPrompt(),
-                visionBridgeDefaultPrompt: SYSTEM_PROMPT,
-                visionModels: this.collectVisionModels(),
-                disabledSkills: [...this.settings.disabledSkills],
-                disabledExtensions: [...this.settings.disabledExtensions],
-                skills,
-                reviewSkills,
-                extensions,
-                presets: this.presets.map((p) => ({ ...p })),
-            },
-        });
-    }
-    /** Vision-capable configured models, for the settings-panel picker. */
-    collectVisionModels() {
-        try {
-            return findVisionModels(this.session.modelRuntime).map((m) => ({
-                provider: m.provider,
-                id: m.id,
-                label: m.label,
-            }));
-        }
-        catch {
-            // Session not ready yet — the picker stays empty until next push.
-            return [];
-        }
+        this.settingsSvc.push();
     }
     /** Persist + apply a partial settings update (prompt text/mode, toggles). */
     async setSettings(partial) {
-        const needsReload = partial.promptMode !== undefined ||
-            partial.customSystemPrompt !== undefined ||
-            partial.disabledSkills !== undefined ||
-            partial.disabledExtensions !== undefined;
-        if (partial.promptMode !== undefined)
-            this.settings.promptMode = partial.promptMode;
-        if (partial.customSystemPrompt !== undefined) {
-            this.settings.customSystemPrompt = partial.customSystemPrompt;
-        }
-        if (partial.disabledSkills !== undefined) {
-            this.settings.disabledSkills = partial.disabledSkills;
-        }
-        if (partial.disabledExtensions !== undefined) {
-            this.settings.disabledExtensions = partial.disabledExtensions;
-        }
-        if (partial.visionBridgeEnabled !== undefined) {
-            this.settings.visionBridgeEnabled = partial.visionBridgeEnabled;
-        }
-        if (partial.visionBridgeModel !== undefined) {
-            this.settings.visionBridgeModel = partial.visionBridgeModel ?? null;
-        }
-        if (partial.visionBridgePromptMode !== undefined) {
-            this.settings.visionBridgePromptMode = partial.visionBridgePromptMode;
-        }
-        if (partial.visionBridgePrompt !== undefined) {
-            this.settings.visionBridgePrompt = partial.visionBridgePrompt;
-        }
-        if (partial.reviewPrompt !== undefined) {
-            this.settings.reviewPrompt = partial.reviewPrompt;
-        }
-        if (partial.reviewDisabledSkills !== undefined) {
-            this.settings.reviewDisabledSkills = partial.reviewDisabledSkills;
-        }
-        this.stateStore.saveSettings(this.clientId, this.settings);
-        this.pushSettings();
-        if (needsReload)
-            await this.applyRuntimeSettings();
+        await this.settingsSvc.set(partial);
     }
     /** Save the CURRENT settings as a named preset (overwrites if exists). */
     async savePreset(name) {
-        const n = name.trim();
-        if (!n) {
-            this.emit({ type: "notice", level: "error", text: "预设名称不能为空" });
-            return;
-        }
-        const preset = {
-            name: n,
-            promptMode: this.settings.promptMode,
-            customSystemPrompt: this.settings.customSystemPrompt,
-            disabledSkills: [...this.settings.disabledSkills],
-            disabledExtensions: [...this.settings.disabledExtensions],
-            reviewPrompt: this.settings.reviewPrompt,
-            reviewDisabledSkills: [...this.settings.reviewDisabledSkills],
-        };
-        const existing = this.presets.findIndex((p) => p.name === n);
-        if (existing >= 0)
-            this.presets[existing] = preset;
-        else
-            this.presets.push(preset);
-        this.stateStore.savePresets(this.clientId, this.presets);
-        this.pushSettings();
+        return this.settingsSvc.savePreset(name);
     }
     /** Replace the current settings with the named preset and apply it. */
     async applyPreset(name) {
-        const p = this.presets.find((x) => x.name === name);
-        if (!p) {
-            this.emit({ type: "notice", level: "error", text: `预设不存在：${name}` });
-            return;
-        }
-        this.settings = {
-            promptMode: p.promptMode,
-            customSystemPrompt: p.customSystemPrompt,
-            disabledSkills: [...p.disabledSkills],
-            disabledExtensions: [...p.disabledExtensions],
-            reviewPrompt: p.reviewPrompt ?? this.settings.reviewPrompt,
-            reviewDisabledSkills: [
-                ...(p.reviewDisabledSkills ?? this.settings.reviewDisabledSkills),
-            ],
-            // Presets don't capture vision-bridge prefs — keep the current ones.
-            visionBridgeEnabled: this.settings.visionBridgeEnabled,
-            visionBridgeModel: this.settings.visionBridgeModel,
-            visionBridgePromptMode: this.settings.visionBridgePromptMode,
-            visionBridgePrompt: this.settings.visionBridgePrompt,
-        };
-        this.stateStore.saveSettings(this.clientId, this.settings);
-        this.pushSettings();
-        await this.applyRuntimeSettings();
+        return this.settingsSvc.applyPreset(name);
     }
     /** Remove a named preset. */
     async deletePreset(name) {
-        this.presets = this.presets.filter((p) => p.name !== name);
-        this.stateStore.savePresets(this.clientId, this.presets);
-        this.pushSettings();
+        return this.settingsSvc.deletePreset(name);
     }
-    /**
-     * Make settings changes effective in the running runtime. The resource-loader
-     * overrides read this.settings at call time, so a reload re-applies them.
-     * Reloading mid-stream would tear down the in-flight run — defer instead.
-     */
+    /** Make settings effective in the running runtime（流式中则延迟到 agent_end）。 */
     async applyRuntimeSettings() {
-        if (this.disposed)
-            return;
-        if (this.session.isStreaming) {
-            this.pendingSettingsReload = true;
-            this.emit({
-                type: "notice",
-                level: "info",
-                text: "当前回复进行中，设置将在回复结束后自动应用",
-            });
-            return;
-        }
-        await this.applySettingsReload();
+        return this.settingsSvc.applyRuntime();
     }
-    /** session.reload() + refresh the slash-command catalog + push state. */
     async applySettingsReload() {
-        try {
-            await this.session.reload();
-            await this.pushSlashCommands();
-            this.pushSettings();
-            this.flushSnapshot();
-            this.emit({ type: "notice", level: "info", text: "设置已应用" });
-        }
-        catch (err) {
-            this.emit({
-                type: "notice",
-                level: "error",
-                text: `设置应用失败：${err.message}`,
-            });
-        }
+        // 兼容旧入口：reload + 刷目录在宿主回调里完成
+        return this.settingsSvc.applyRuntime();
     }
     // ---------------------------------------------------------------------------
     // Commands
@@ -3149,695 +1418,88 @@ export class ClientSession {
      * after the WHOLE run finishes (补充 button — "AI 生成结束才发送").
      * false/undefined = steer: the pi CLI Enter semantic — injected right
      * after the current turn settles, skipping remaining planned tool calls.
-     */
-    queue = false) {
-        try {
-            const s = this.session;
-            // Native slash commands (see NATIVE_COMMANDS) are executed here and
-            // never reach the SDK. Extension / skill / template commands fall
-            // through — AgentSession.prompt() handles those itself.
-            const slash = this.parseSlash(text);
-            if (slash && (await this.execNativeCommand(slash.name, slash.args))) {
-                this.flushSnapshot();
-                return;
-            }
-            // Native commands above are pure config tweaks (no tokens) — allow them
-            // even while quiesced. Everything that reaches the SDK is NEW work and
-            // is refused until admission reopens.
-            if (this.quiesceBlocked())
-                return;
-            // Attach files as independent nextTurn context messages (asides) so the
-            // user message stays clean; they render as separate attachment cards.
-            const asides = await this.buildAttachmentMessages(attachments);
-            for (const aside of asides) {
-                await s.sendCustomMessage(aside.message, { deliverAs: "nextTurn" });
-            }
-            if (s.isStreaming) {
-                // queue=true (补充 button) → followUp: the message is delivered only
-                // after the whole run finishes — the agent finishes what it started,
-                // then responds to the queued message. queue=false/undefined
-                // (plain Enter) → steer: interrupts the current run — the message
-                // is delivered right after the current assistant turn settles
-                // (remaining planned tool calls are skipped) and the agent
-                // immediately responds to it. This is the pi CLI
-                // Enter-during-streaming semantic (docs/usage: Enter queues a
-                // steering message); followUp would wait for the whole run
-                // to finish, which users perceive as ordinary queueing.
-                await s.prompt(text, {
-                    streamingBehavior: queue ? "followUp" : "steer",
-                });
-            }
-            else {
-                await s.prompt(text);
-            }
-        }
-        catch (err) {
-            this.emit({
-                type: "notice",
-                level: "error",
-                text: `提示发送失败：${err.message}`,
-            });
-        }
-        // Name the conversation after its first user prompt.
-        const conv = this.conv;
-        if (conv.title === DEFAULT_CONV_TITLE && text.trim()) {
-            const trimmed = text.trim().replace(/\s+/g, " ");
-            conv.title = trimmed.length > 30 ? `${trimmed.slice(0, 30)}…` : trimmed;
-            this.emitConversations();
-        }
-        // The active conversation has been continued since it was opened — it
-        // must not be dismissed when the user switches away. (Also bumps the
-        // per-project "most recently active" order used by set_cwd.)
-        conv.promptedSinceActive = true;
-        conv.lastActiveAt = Date.now();
-        this.flushSnapshot();
-    }
-    /**
-     * Turn attached files into custom-message payloads.
-     *
-     * Text files are size-aware: small files are inlined into the message so the
-     * model sees them immediately; large files are passed as a <file path="...">
-     * reference and the model reads them on demand with its read tool (which has
-     * built-in truncation). Images are always passed as image content. Mode
-     * "lines" inlines only a 1-based inclusive line range of the file. Raw
-     * pasted/dropped/uploaded images (attachment.imageData) skip the workspace
-     * path entirely and go straight to the model as image content. Raw uploaded
-     * files (attachment.fileData) are persisted under <dataDir>/uploads/ and
-     * attached as absolute-path references (small text ones are inlined).
-     */
-    async buildAttachmentMessages(attachments) {
-        if (!attachments || attachments.length === 0)
-            return [];
-        const fs = await import("node:fs/promises");
-        const { resolve, sep, relative, extname, join } = await import("node:path");
-        const root = resolve(this.cwd);
-        const MAX_ATTACHMENT_BYTES = 200 * 1024;
-        // Files at or below this size are inlined; larger files are referenced by
-        // path only (the model reads them on demand — saves tokens for small edits).
-        const MAX_INLINE_BYTES = Number(process.env.PI_WEB_INLINE_FILE_MAX ?? 12 * 1024);
-        const IMAGE_EXT = new Set([
-            ".png",
-            ".jpg",
-            ".jpeg",
-            ".gif",
-            ".webp",
-            ".bmp",
-            ".svg",
-        ]);
-        const MIME = {
-            ".png": "image/png",
-            ".jpg": "image/jpeg",
-            ".jpeg": "image/jpeg",
-            ".gif": "image/gif",
-            ".webp": "image/webp",
-            ".bmp": "image/bmp",
-            ".svg": "image/svg+xml",
-        };
-        const out = [];
-        // -- Vision bridge ------------------------------------------------------
-        // When the active model can't accept images (DeepSeek, GLM, …), pasted
-        // images are transcribed by a configured vision model first and the
-        // transcript is fed to the text-only model as text evidence (see
-        // vision-bridge.ts — any model in models.json whose input includes
-        // "image" works, zero extra config). Vision-capable main models keep
-        // the raw image-content path untouched.
-        const mainModel = this.session.model;
-        const mainSupportsVision = mainModel?.input?.includes("image") ?? false;
-        const bridgedImages = [];
-        /** Raw image bytes for path-referenced image files (idx → info), pre-read
-         *  so the loop below doesn't re-read them. SVG stays a plain text file —
-         *  the model reads its source, far more useful than a rasterized blob. */
-        const pathImageData = new Map();
-        /** Cap for path images (fully read + base64'd); larger ones fall back to
-         *  a plain path reference (the model can still attempt to read them). */
-        const MAX_PATH_IMAGE_BYTES = 5 * 1024 * 1024;
-        for (const [idx, att] of attachments.entries()) {
-            if (att.imageData) {
-                const raw = att.imageData.replace(/^data:[^;]*;base64,/, "");
-                const mimeType = att.mimeType?.startsWith("image/")
-                    ? att.mimeType
-                    : "image/png";
-                const bytes = Buffer.byteLength(raw, "base64");
-                // Only images that would actually be sent (non-empty, under the cap).
-                if (bytes > 0 && bytes <= 2 * 1024 * 1024) {
-                    if (!mainSupportsVision) {
-                        bridgedImages.push({ idx, att, raw, mimeType, bytes });
-                    }
-                }
-                continue;
-            }
-            if (att.fileData || !att.path)
-                continue;
-            const ext = extname(att.path).toLowerCase();
-            if (!IMAGE_EXT.has(ext) || ext === ".svg")
-                continue;
-            const abs = resolve(root, att.path);
-            const rawRel = relative(root, abs);
-            if (rawRel.startsWith("..") || rawRel.includes(`${sep}..`))
-                continue;
-            let st;
-            try {
-                st = await fs.stat(abs);
-            }
-            catch {
-                continue;
-            }
-            if (!st.isFile() || st.size === 0 || st.size > MAX_PATH_IMAGE_BYTES) {
-                continue;
-            }
-            const buf = await fs.readFile(abs);
-            const mime = sniffImageMime(buf, ext);
-            if (!mime)
-                continue;
-            const raw = buf.toString("base64");
-            pathImageData.set(idx, { raw, mimeType: mime, bytes: st.size });
-            if (!mainSupportsVision) {
-                bridgedImages.push({ idx, att, raw, mimeType: mime, bytes: st.size });
-            }
-        }
-        /** Transcript per attachment index (filled below, keyed by bridgedImages idx). */
-        const bridgeTranscripts = new Map();
-        if (bridgedImages.length > 0) {
-            if (!this.settings.visionBridgeEnabled) {
-                this.emit({
-                    type: "notice",
-                    level: "warning",
-                    text: `当前模型（${mainModel?.name ?? mainModel?.id ?? "未知"}）不支持识图，且视觉桥已在设置中关闭：图片将原样发送、可能被忽略。`,
-                });
-            }
-            else {
-                const visionModels = findVisionModels(this.session.modelRuntime);
-                // Preferred model from settings ("provider/id") — validated to exist
-                // and actually accept images; falls back to the first auto-detected.
-                let chosen = visionModels[0] ?? null;
-                const pref = this.settings.visionBridgeModel;
-                if (pref) {
-                    const spec = this.resolveReviewModel(pref);
-                    if (spec) {
-                        const pm = this.session.modelRuntime.getModel(spec.provider, spec.id);
-                        if (pm?.input?.includes("image")) {
-                            chosen = {
-                                provider: spec.provider,
-                                id: spec.id,
-                                label: `${pm.name ?? pm.id} (${spec.provider})`,
-                            };
-                        }
-                    }
-                }
-                if (!chosen) {
-                    this.emit({
-                        type: "notice",
-                        level: "warning",
-                        text: `当前模型（${mainModel?.name ?? mainModel?.id ?? "未知"}）不支持识图，且未找到可用的视觉模型：图片将原样发送、可能被忽略。在模型配置里添加任意支持图片的模型（如 qwen-vl、GLM-4V、Gemini）即可自动启用视觉桥转写。`,
-                    });
-                }
-                else {
-                    // Batch hash so re-sending identical images (edit & re-ask) reuses
-                    // the transcript instead of re-burning tokens on the vision API.
-                    // The active transcription prompt is part of the key: changing
-                    // the custom prompt must invalidate cached transcripts made with
-                    // the old prompt.
-                    const batchHash = bridgedImages
-                        .map((b) => `${b.att.name ?? "img"}:${b.raw.slice(0, 48)}`)
-                        .join("|") +
-                        "::" +
-                        buildVisionBridgePrompt(this.settings.visionBridgePromptMode, this.settings.visionBridgePrompt);
-                    let transcript = this.visionBridgeCache.get(batchHash);
-                    if (transcript === undefined) {
-                        this.emit({
-                            type: "notice",
-                            level: "info",
-                            text: `当前模型不支持识图，正在用视觉桥（${chosen.label}）转写 ${bridgedImages.length} 张图片…`,
-                        });
-                        try {
-                            const chosenModel = this.session.modelRuntime.getModel(chosen.provider, chosen.id);
-                            transcript = await transcribeImages(this.session.modelRuntime, bridgedImages.map((b) => ({
-                                data: b.raw,
-                                mimeType: b.mimeType,
-                                name: b.att.name,
-                            })), {
-                                model: chosenModel ?? undefined,
-                                systemPrompt: buildVisionBridgePrompt(this.settings.visionBridgePromptMode, this.settings.visionBridgePrompt),
-                            });
-                            this.visionBridgeCache.set(batchHash, transcript);
-                            this.emit({
-                                type: "notice",
-                                level: "info",
-                                text: `✅ 图片已由视觉桥转写完成（${chosen.label}）`,
-                            });
-                        }
-                        catch (err) {
-                            transcript = "";
-                            this.emit({
-                                type: "notice",
-                                level: "error",
-                                text: `图片转写失败（${chosen.label}）：${err.message}。图片将原样发送、可能被忽略。`,
-                            });
-                        }
-                    }
-                    for (const b of bridgedImages)
-                        bridgeTranscripts.set(b.idx, transcript ?? "");
-                }
-            }
-        }
-        /** Cap for reading a file in "lines" mode (selected slice is inlined). */
-        const MAX_LINES_READ_BYTES = 2 * 1024 * 1024;
-        for (const [idx, att] of attachments.entries()) {
-            // Raw pasted/dropped/uploaded image — no workspace path involved (the
-            // browser downscales client-side; this guard only prevents abuse).
-            if (att.imageData) {
-                const raw = att.imageData.replace(/^data:[^;]*;base64,/, "");
-                const mimeType = att.mimeType?.startsWith("image/") ? att.mimeType : "image/png";
-                const bytes = Buffer.byteLength(raw, "base64");
-                const MAX_PASTED_IMAGE_BYTES = 2 * 1024 * 1024;
-                if (bytes === 0) {
-                    this.emit({
-                        type: "notice",
-                        level: "error",
-                        text: `图片数据为空，已跳过`,
-                    });
-                    continue;
-                }
-                if (bytes > MAX_PASTED_IMAGE_BYTES) {
-                    this.emit({
-                        type: "notice",
-                        level: "warning",
-                        text: `图片过大已跳过（>2MB）：${att.name ?? "粘贴图片"}`,
-                    });
-                    continue;
-                }
-                const transcript = bridgeTranscripts.get(idx);
-                if (transcript) {
-                    // Bridged: the text-only main model can't see images, so it gets the
-                    // vision model's transcript as text evidence; the image block is
-                    // kept so the card still shows the original thumbnail.
-                    out.push({
-                        message: {
-                            customType: "file",
-                            content: [
-                                {
-                                    type: "text",
-                                    text: `\n<vision-bridge>\n${transcript}\n</vision-bridge>`,
-                                },
-                                { type: "image", data: raw, mimeType },
-                            ],
-                            display: true,
-                            details: {
-                                name: att.name ?? "image.png",
-                                path: undefined,
-                                mode: "bridged",
-                                size: bytes,
-                            },
-                        },
-                    });
-                    continue;
-                }
-                out.push({
-                    message: {
-                        customType: "file",
-                        content: [{ type: "image", data: raw, mimeType }],
-                        display: true,
-                        details: {
-                            name: att.name ?? "image.png",
-                            // No workspace path — the card renders without the path line.
-                            path: undefined,
-                            mode: "image",
-                            size: bytes,
-                        },
-                    },
-                });
-                continue;
-            }
-            // Raw uploaded file (base64) — no workspace path involved. The bytes are
-            // persisted under <dataDir>/uploads/<clientId>/ so the model can read
-            // them on demand with its read tool (absolute path, no traversal guard
-            // needed — the path is server-generated). Small text uploads are inlined
-            // so the model sees them immediately; everything else becomes a path
-            // reference.
-            if (att.fileData) {
-                const buf = Buffer.from(att.fileData, "base64");
-                const MAX_UPLOAD_BYTES = 20 * 1024 * 1024;
-                if (buf.length === 0) {
-                    this.emit({
-                        type: "notice",
-                        level: "error",
-                        text: `文件数据为空，已跳过`,
-                    });
-                    continue;
-                }
-                if (buf.length > MAX_UPLOAD_BYTES) {
-                    this.emit({
-                        type: "notice",
-                        level: "warning",
-                        text: `文件过大已跳过（>20MB）：${att.name ?? "上传文件"}`,
-                    });
-                    continue;
-                }
-                // Uploaded files live in a GLOBAL per-user dir (not inside the project
-                // or the per-client session store) so browsing a repo never picks up
-                // uploaded junk: <home>/.pi-web/uploads/<clientId>/.
-                const { homedir } = await import("node:os");
-                const uploadsDir = join(homedir(), ".pi-web", "uploads", this.clientId);
-                const safeName = (att.name ?? "file")
-                    .replace(/[\\/:*?"<>|\x00-\x1f]/g, "_")
-                    .slice(0, 80);
-                const abs = join(uploadsDir, `${Date.now()}-${safeName}`);
-                await fs.mkdir(uploadsDir, { recursive: true });
-                await fs.writeFile(abs, buf);
-                // Wire format: forward-slash absolute path (the read tool accepts
-                // absolute paths; Windows uses "C:/..." — safe inside the XML-ish tag).
-                const wirePath = abs.split(sep).join("/");
-                if (buf.length <= MAX_INLINE_BYTES && looksLikeText(buf)) {
-                    const lines = countLines(buf);
-                    out.push({
-                        message: {
-                            customType: "file",
-                            content: [
-                                {
-                                    type: "text",
-                                    text: `\n<file path="${wirePath}">\n\`\`\`\n${decodeText(buf)}\n\`\`\`\n</file>`,
-                                },
-                            ],
-                            display: true,
-                            details: {
-                                name: safeName,
-                                path: wirePath,
-                                mode: "inline",
-                                size: buf.length,
-                                lines,
-                            },
-                        },
-                    });
-                }
-                else {
-                    out.push({
-                        message: {
-                            customType: "file",
-                            content: [
-                                {
-                                    type: "text",
-                                    text: `<file path="${wirePath}" size="${buf.length}" />`,
-                                },
-                            ],
-                            display: true,
-                            details: {
-                                name: safeName,
-                                path: wirePath,
-                                mode: "reference",
-                                size: buf.length,
-                            },
-                        },
-                    });
-                }
-                continue;
-            }
-            const abs = resolve(root, att.path);
-            const rawRel = relative(root, abs);
-            if (rawRel.startsWith("..") || rawRel.includes(`${sep}..`)) {
-                this.emit({
-                    type: "notice",
-                    level: "warning",
-                    text: `附件路径超出工作区：${att.path}`,
-                });
-                continue;
-            }
-            // Normalize to forward slashes (relative() returns "\\" on Windows);
-            // <file path> and details.path must use the wire format.
-            const rel = rawRel.split(sep).join("/");
-            let stat;
-            try {
-                stat = await fs.stat(abs);
-            }
-            catch {
-                this.emit({
-                    type: "notice",
-                    level: "error",
-                    text: `附件不存在：${att.path}`,
-                });
-                continue;
-            }
-            const name = att.path.split(/[\\/]/).pop() ?? att.path;
-            // Folders can't be inlined — always a path reference the model browses
-            // on demand with its own tools (ls/read).
-            if (stat.isDirectory()) {
-                out.push({
-                    message: {
-                        customType: "file",
-                        content: [{ type: "text", text: `<folder path="${rel}" />` }],
-                        display: true,
-                        details: {
-                            name,
-                            path: rel,
-                            mode: "reference",
-                            type: "folder",
-                        },
-                    },
-                });
-                continue;
-            }
-            if (!stat.isFile()) {
-                this.emit({
-                    type: "notice",
-                    level: "warning",
-                    text: `跳过非文件附件：${att.path}`,
-                });
-                continue;
-            }
-            const ext = extname(att.path).toLowerCase();
-            if (IMAGE_EXT.has(ext) && ext !== ".svg") {
-                const pathImg = pathImageData.get(idx);
-                const transcript = bridgeTranscripts.get(idx);
-                if (transcript) {
-                    // Text-only main model: the vision bridge transcribed this image —
-                    // the model gets the transcript as text evidence (+ thumbnail).
-                    out.push({
-                        message: {
-                            customType: "file",
-                            content: [
-                                {
-                                    type: "text",
-                                    text: `
-<vision-bridge>
-${transcript}
-</vision-bridge>`,
-                                },
-                                ...(pathImg
-                                    ? ([{
-                                            type: "image",
-                                            data: pathImg.raw,
-                                            mimeType: pathImg.mimeType,
-                                        }])
-                                    : []),
-                            ],
-                            display: true,
-                            details: {
-                                name,
-                                path: rel,
-                                mode: "bridged",
-                                size: stat.size,
-                            },
-                        },
-                    });
-                    continue;
-                }
-                if (pathImg) {
-                    // Vision-capable main model (or bridge failed): send the raw image
-                    // content straight from the pre-read bytes.
-                    out.push({
-                        message: {
-                            customType: "file",
-                            content: [
-                                {
-                                    type: "image",
-                                    data: pathImg.raw,
-                                    mimeType: pathImg.mimeType,
-                                },
-                            ],
-                            display: true,
-                            details: { name, path: rel, mode: "image", size: stat.size },
-                        },
-                    });
-                    continue;
-                }
-                // Pre-read failed (unsupported sniff / too large): fall back to the
-                // legacy inline-cap behavior.
-                if (stat.size > MAX_ATTACHMENT_BYTES) {
-                    this.emit({
-                        type: "notice",
-                        level: "warning",
-                        text: `图片附件过大已跳过（>200KB）：${att.path}`,
-                    });
-                    continue;
-                }
-                const data = await fs.readFile(abs, "base64");
-                out.push({
-                    message: {
-                        customType: "file",
-                        content: [
-                            { type: "image", data, mimeType: MIME[ext] ?? "image/png" },
-                        ],
-                        display: true,
-                        details: { name, path: rel, mode: "image", size: stat.size },
-                    },
-                });
-                continue;
-            }
-            const makeReference = () => ({
-                message: {
-                    customType: "file",
-                    content: [
-                        {
-                            type: "text",
-                            text: `<file path="${rel}" size="${stat.size}" />`,
-                        },
-                    ],
-                    display: true,
-                    details: { name, path: rel, mode: "reference", size: stat.size },
-                },
-            });
-            const makeInline = (buf) => {
-                const lines = countLines(buf);
-                return {
-                    message: {
-                        customType: "file",
-                        content: [
-                            {
-                                type: "text",
-                                text: `\n<file path="${rel}">\n\`\`\`\n${decodeText(buf)}\n\`\`\`\n</file>`,
-                            },
-                        ],
-                        display: true,
-                        details: {
-                            name,
-                            path: rel,
-                            mode: "inline",
-                            size: stat.size,
-                            lines,
-                        },
-                    },
-                };
-            };
-            // Reference mode is always honored and never reads the file.
-            if (att.mode === "reference") {
-                out.push(makeReference());
-                continue;
-            }
-            // Line-range mode: inline only the selected 1-based inclusive range.
-            // Reading is capped so a huge file can't exhaust memory even though
-            // the selected slice is small.
-            if (att.mode === "lines") {
-                const range = att.lines;
-                if (!range || range.start < 1 || range.end < range.start) {
-                    this.emit({
-                        type: "notice",
-                        level: "warning",
-                        text: `行范围无效，已改为仅引用：${att.path}`,
-                    });
-                    out.push(makeReference());
-                    continue;
-                }
-                if (stat.size > MAX_LINES_READ_BYTES) {
-                    this.emit({
-                        type: "notice",
-                        level: "warning",
-                        text: `文件过大，已改为仅引用：${att.path}`,
-                    });
-                    out.push(makeReference());
-                    continue;
-                }
-                const buf = await fs.readFile(abs);
-                if (buf.includes(0)) {
-                    this.emit({
-                        type: "notice",
-                        level: "warning",
-                        text: `二进制文件已改为仅引用：${att.path}`,
-                    });
-                    out.push(makeReference());
-                    continue;
-                }
-                const parts = decodeText(buf).split("\n");
-                // A trailing newline yields an empty phantom line — drop it so line
-                // numbers match the preview panel.
-                if (parts.length > 0 && parts[parts.length - 1] === "")
-                    parts.pop();
-                const start = Math.min(range.start, parts.length);
-                const end = Math.min(range.end, parts.length);
-                if (start < 1 || end < start) {
-                    this.emit({
-                        type: "notice",
-                        level: "warning",
-                        text: `选中行超出文件范围，已改为仅引用：${att.path}`,
-                    });
-                    out.push(makeReference());
-                    continue;
-                }
-                const selected = parts.slice(start - 1, end).join("\n");
-                out.push({
-                    message: {
-                        customType: "file",
-                        content: [
-                            {
-                                type: "text",
-                                text: `\n<file path="${rel}" lines="${start}-${end}">\n\`\`\`\n${selected}\n\`\`\`\n</file>`,
-                            },
-                        ],
-                        display: true,
-                        details: {
-                            name,
-                            path: rel,
-                            mode: "lines",
-                            size: stat.size,
-                            lines: end - start + 1,
-                            startLine: start,
-                            endLine: end,
-                        },
-                    },
-                });
-                continue;
-            }
-            // Forced inline has a hard cap to protect the model context.
-            if (att.mode === "inline") {
-                if (stat.size > MAX_INLINE_BYTES) {
-                    this.emit({
-                        type: "notice",
-                        level: "warning",
-                        text: `文件过大，已改为仅引用：${att.path}`,
-                    });
-                    out.push(makeReference());
-                    continue;
-                }
-                const buf = await fs.readFile(abs);
-                if (buf.includes(0)) {
-                    this.emit({
-                        type: "notice",
-                        level: "warning",
-                        text: `二进制文件已改为仅引用：${att.path}`,
-                    });
-                    out.push(makeReference());
-                    continue;
-                }
-                out.push(makeInline(buf));
-                continue;
+     */
+    queue = false) {
+        try {
+            const s = this.session;
+            // Native slash commands (see NATIVE_COMMANDS) are executed here and
+            // never reach the SDK. Extension / skill / template commands fall
+            // through — AgentSession.prompt() handles those itself.
+            const slash = parseSlash(text);
+            if (slash && (await this.slash.exec(slash.name, slash.args))) {
+                this.flushSnapshot();
+                return;
             }
-            // Auto: small files inline, large files reference by path.
-            if (stat.size > MAX_INLINE_BYTES) {
-                out.push(makeReference());
-                continue;
+            // Native commands above are pure config tweaks (no tokens) — allow them
+            // even while quiesced. Everything that reaches the SDK is NEW work and
+            // is refused until admission reopens.
+            if (this.quiesceBlocked())
+                return;
+            // Attach files as independent nextTurn context messages (asides) so the
+            // user message stays clean; they render as separate attachment cards.
+            const asides = await buildAttachmentMessages({
+                cwd: this.cwd,
+                clientId: this.clientId,
+                emit: (msg) => this.emit(msg),
+                settings: this.settingsSvc.current,
+                session: this.session,
+            }, attachments);
+            for (const aside of asides) {
+                await s.sendCustomMessage(aside.message, { deliverAs: "nextTurn" });
             }
-            const buf = await fs.readFile(abs);
-            if (buf.includes(0)) {
-                this.emit({
-                    type: "notice",
-                    level: "warning",
-                    text: `二进制文件已跳过（仅引用路径）：${att.path}`,
+            if (s.isStreaming) {
+                // queue=true (补充 button) → followUp: the message is delivered only
+                // after the whole run finishes — the agent finishes what it started,
+                // then responds to the queued message. queue=false/undefined
+                // (plain Enter) → steer: interrupts the current run — the message
+                // is delivered right after the current assistant turn settles
+                // (remaining planned tool calls are skipped) and the agent
+                // immediately responds to it. This is the pi CLI
+                // Enter-during-streaming semantic (docs/usage: Enter queues a
+                // steering message); followUp would wait for the whole run
+                // to finish, which users perceive as ordinary queueing.
+                await s.prompt(text, {
+                    streamingBehavior: queue ? "followUp" : "steer",
                 });
-                out.push(makeReference());
-                continue;
             }
-            out.push(makeInline(buf));
+            else {
+                await s.prompt(text);
+            }
+        }
+        catch (err) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `提示发送失败：${err.message}`,
+            });
+        }
+        // Name the conversation after its first user prompt.
+        const conv = this.conv;
+        if (conv.title === DEFAULT_CONV_TITLE && text.trim()) {
+            const trimmed = text.trim().replace(/\s+/g, " ");
+            conv.title = trimmed.length > 30 ? `${trimmed.slice(0, 30)}…` : trimmed;
+            this.emitConversations();
         }
-        return out;
+        // The active conversation has been continued since it was opened — it
+        // must not be dismissed when the user switches away. (Also bumps the
+        // per-project "most recently active" order used by set_cwd.)
+        conv.promptedSinceActive = true;
+        conv.lastActiveAt = Date.now();
+        this.flushSnapshot();
     }
+    /**
+     * Turn attached files into custom-message payloads.
+     *
+     * Text files are size-aware: small files are inlined into the message so the
+     * model sees them immediately; large files are passed as a <file path="...">
+     * reference and the model reads them on demand with its read tool (which has
+     * built-in truncation). Images are always passed as image content. Mode
+     * "lines" inlines only a 1-based inclusive line range of the file. Raw
+     * pasted/dropped/uploaded images (attachment.imageData) skip the workspace
+     * path entirely and go straight to the model as image content. Raw uploaded
+     * files (attachment.fileData) are persisted under <dataDir>/uploads/ and
+     * attached as absolute-path references (small text ones are inlined).
+     */
     /**
      * Hard-abort the running agent (Stop button / global 中断). Tries
      * session.abort() first; if the run is not idle within
@@ -3852,112 +1514,17 @@ ${transcript}
         await this.interruptRun(this.conv, "已停止");
         this.flushSnapshot();
     }
-    /** After a bash tool run, wait briefly for background servers to bind,
-     *  then diff the listening-port snapshot against the pre-run one and
-     *  remember anything new — those are servers the agent left running. */
-    async trackBackgroundServers() {
-        const before = this.bashListenBefore;
-        this.bashListenBefore = null;
-        if (!before)
-            return;
-        await new Promise((r) => setTimeout(r, 1500));
-        const after = await snapshotListeningPorts();
-        let added = false;
-        for (const [port, pid] of after) {
-            if (!before.has(port) && !this.bgServers.has(port)) {
-                this.bgServers.set(port, { pid, since: Date.now() });
-                added = true;
-                // Best-effort process name so the panel shows something readable.
-                void lookupProcessName(pid).then((name) => {
-                    const cur = this.bgServers.get(port);
-                    if (cur && cur.pid === pid && name) {
-                        cur.name = name;
-                        this.emitBgServers();
-                    }
-                });
-                this.emit({
-                    type: "notice",
-                    level: "info",
-                    text: `检测到 AI 启动的后台服务：端口 ${port}（pid ${pid}）——可在顶栏「后台任务」里单独停止或全部关闭`,
-                });
-            }
-        }
-        if (added)
-            this.emitBgServers();
-    }
-    /** The current background-server list, oldest first. */
-    bgServerList() {
-        return [...this.bgServers.entries()]
-            .map(([port, v]) => ({
-            port,
-            pid: v.pid,
-            since: v.since,
-            ...(v.name ? { name: v.name } : {}),
-        }))
-            .sort((a, b) => a.since - b.since);
-    }
-    /** Push the current background-task list to every connected socket. */
-    emitBgServers() {
-        this.emit({ type: "bg_servers", servers: this.bgServerList() });
-    }
-    /** Re-snapshot listening ports and drop tracked entries that are no longer
-     *  listening — the process exited on its own, so it must leave the panel.
-     *  Port AND pid must both match: a port reused by an unrelated process is
-     *  not our server anymore. Silent (the list just updates). */
-    async refreshBgServers() {
-        if (this.disposed || this.bgServers.size === 0)
-            return;
-        const now = await snapshotListeningPorts();
-        let changed = false;
-        for (const [port, v] of [...this.bgServers]) {
-            if (now.get(port) !== v.pid) {
-                this.bgServers.delete(port);
-                changed = true;
-            }
-        }
-        if (changed)
-            this.emitBgServers();
-    }
     /** Re-push the current list on request (panel opened); prunes dead entries first. */
     async listBgServers() {
-        await this.refreshBgServers();
-        this.emitBgServers();
+        await this.bg.listAndPush();
     }
     /** Kill ONE background server (by port); returns whether anything was killed. */
     async killBackgroundServer(port) {
-        const entry = this.bgServers.get(port);
-        if (!entry) {
-            this.emit({
-                type: "notice",
-                level: "info",
-                text: `端口 ${port} 不在后台任务列表中`,
-            });
-            this.flushSnapshot();
-            return false;
-        }
-        killPidTree(entry.pid);
-        this.bgServers.delete(port);
-        this.emitBgServers();
-        this.emit({
-            type: "notice",
-            level: "info",
-            text: `已停止后台任务：端口 ${port}（pid ${entry.pid}）`,
-        });
-        this.flushSnapshot();
-        return true;
+        return this.bg.killOne(port);
     }
     /** Kill every background server the agent started; returns the freed ports. */
     async killAllBackgroundServers() {
-        if (this.bgServers.size === 0)
-            return [];
-        const killed = [];
-        for (const [port, { pid }] of [...this.bgServers]) {
-            killPidTree(pid);
-            killed.push(String(port));
-        }
-        this.bgServers.clear();
-        this.emitBgServers();
-        return killed;
+        return this.bg.killAll();
     }
     /** Kill only the running bash command(s) — the agent run itself continues
      *  (the bash tool returns an aborted error and the model moves on). Uses
@@ -4131,7 +1698,7 @@ ${transcript}
                 this.removeConversation(displaced.id);
             await this.bindSession();
             this.emitConversations();
-            this.emitGoalStatus();
+            this.goalSvc.emitGoalStatus();
             this.pushTerminals();
             // The new runtime re-discovered skills/templates — refresh the catalog
             // so the picker stops showing the previous runtime's list.
@@ -4209,7 +1776,7 @@ ${transcript}
         this.conv.lastActiveAt = Date.now();
         this.webUi.refresh();
         this.emitConversations();
-        this.emitGoalStatus();
+        this.goalSvc.emitGoalStatus();
         this.pushTerminals();
         // The switched-to conversation has its own runtime (own resource cache).
         void this.pushSlashCommands();
@@ -4247,11 +1814,20 @@ ${transcript}
         });
     }
     /** List persisted sessions for this client, newest first. */
+    /** The client asked for the session list at least once (lazy loading) —
+     *  background refreshes only re-push when this is true, so a mobile
+     *  client that never opened the panel never pays the disk scan. */
+    sessionsRequested = false;
     /** Push the persisted session list to the client (client-requested). */
     async refreshSessions() {
+        this.sessionsRequested = true;
         await this.pushSessions();
     }
     async pushSessions() {
+        if (!this.sessionsRequested)
+            return;
+        if (!this.sessionsRequested)
+            return;
         try {
             // Sessions live in the SDK default per-project dir
             // (<agentDir>/sessions/--<cwd>--/), the same files the pi CLI/TUI
@@ -4268,7 +1844,9 @@ ${transcript}
                     source: "web",
                 });
             }
-            const sorted = [...sessions.values()].sort((a, b) => b.modified - a.modified);
+            const sorted = [...sessions.values()]
+                .sort((a, b) => b.modified - a.modified)
+                .slice(0, 200); // newest first — the panel shows recent history
             this.emit({ type: "sessions", sessions: sorted });
         }
         catch {
@@ -4354,310 +1932,87 @@ ${transcript}
             this.emit({
                 type: "notice",
                 level: "error",
-                text: "找不到要编辑的消息（可能已被压缩或不在当前分支）",
-            });
-            this.flushSnapshot();
-            return;
-        }
-        try {
-            const result = await this.runtime.fork(entryId);
-            if (result.cancelled) {
-                this.emit({
-                    type: "notice",
-                    level: "info",
-                    text: "已取消编辑重问",
-                });
-                this.flushSnapshot();
-                return;
-            }
-            await this.bindSession();
-            await this.prompt(trimmed);
-            this.emit({
-                type: "notice",
-                level: "info",
-                text: "已从该问题重新提问（原对话保留在会话列表中）",
-            });
-        }
-        catch (err) {
-            this.emit({
-                type: "notice",
-                level: "error",
-                text: `编辑重问失败：${err.message}`,
-            });
-        }
-        this.flushSnapshot();
-    }
-    /**
-     * Push the recent-project list (persisted per client, merged with every cwd
-     * that has persisted sessions in this client's session store — so workspaces
-     * opened before the recent-list feature existed still show up).
-     */
-    async pushProjects() {
-        try {
-            const saved = this.stateStore.get(this.clientId);
-            const map = new Map();
-            for (const p of saved.projects)
-                map.set(p.path, p.lastUsed);
-            const all = await SessionManager.listAll();
-            for (const s of all) {
-                if (s.cwd) {
-                    const t = s.modified.getTime();
-                    const prev = map.get(s.cwd);
-                    if (prev === undefined || t > prev)
-                        map.set(s.cwd, t);
-                }
-            }
-            // Only keep directories that still exist — a deleted/unmounted workspace
-            // is useless in the picker.
-            const projects = [...map.entries()]
-                .filter(([path]) => existsSync(path))
-                .map(([path, lastUsed]) => ({ path, lastUsed }))
-                .sort((a, b) => b.lastUsed - a.lastUsed)
-                .slice(0, 20);
-            this.emit({ type: "projects", projects });
-        }
-        catch {
-            this.emit({ type: "projects", projects: [] });
-        }
-    }
-    /** List a workspace directory (relative to the configured cwd). */
-    async listFiles(relPath) {
-        try {
-            const { resolve, sep, relative } = await import("node:path");
-            const root = resolve(this.cwd);
-            const target = relPath ? resolve(root, relPath) : root;
-            const rawRel = relative(root, target);
-            if (rawRel.startsWith("..") || rawRel.includes(`${sep}..`)) {
-                this.emit({
-                    type: "notice",
-                    level: "warning",
-                    text: `路径超出工作区：${relPath ?? ""}`,
-                });
-                return;
-            }
-            // Normalize to forward slashes: the wire protocol and the frontend
-            // always use "/", but relative() returns "\\" on Windows.
-            const rel = rawRel.split(sep).join("/");
-            const { entries, truncated, error } = await readDirForUI(target, rel);
-            // Watch the listed directory (only after a successful read — a missing
-            // dir throws above and must not create a watcher on a phantom path).
-            this.watchDir(target, rel);
-            if (error) {
-                // Windows-only: unreadable system dirs degrade to an empty list
-                // with a warning instead of a hard error — the panel stays usable.
-                this.emit({
-                    type: "notice",
-                    level: "warning",
-                    text: `目录不可读：${error}`,
-                });
-            }
-            this.emit({
-                type: "files",
-                path: rel === "" ? "" : rel,
-                parent: rel === ""
-                    ? null
-                    : rel.includes("/")
-                        ? rel.slice(0, rel.lastIndexOf("/"))
-                        : "",
-                entries,
-                truncated,
-            });
-        }
-        catch (err) {
-            this.emit({
-                type: "notice",
-                level: "error",
-                text: `读取目录失败：${err.message}`,
-            });
-        }
-    }
-    /** Watch a directory for changes so the file panel refreshes instantly
-     *  instead of waiting for the 10s poll. Watches the directory exactly as
-     *  listed (one level); navigating re-watches the new target. fs.watch is
-     *  unavailable on some platforms/filesystems — failures silently fall back
-     *  to the poll. */
-    watchDir(absPath, rel) {
-        if (this.disposed || this.watchPath === rel)
-            return;
-        this.unwatchDir();
-        this.watchPath = rel;
-        try {
-            // persistent: false — the watcher must not keep the process alive.
-            this.fsWatcher = watch(absPath, { persistent: false }, () => {
-                // Burst events (npm install, git ops, editor save→rename) are
-                // debounced into a single refresh.
-                if (this.watchTimer)
-                    return;
-                this.watchTimer = setTimeout(() => {
-                    this.watchTimer = null;
-                    this.emit({ type: "file_changed", path: this.watchPath ?? "" });
-                }, 400);
-            });
-            this.fsWatcher.on("error", () => {
-                // Directory deleted / unsupported fs — stop watching; the poll (or
-                // the next navigation) restores things.
-                this.unwatchDir();
-            });
-        }
-        catch {
-            // fs.watch unsupported (some network mounts, containers) — poll covers it.
-            this.fsWatcher = null;
-            this.watchPath = null;
-        }
-    }
-    unwatchDir() {
-        if (this.watchTimer) {
-            clearTimeout(this.watchTimer);
-            this.watchTimer = null;
-        }
-        if (this.fsWatcher) {
-            try {
-                this.fsWatcher.close();
-            }
-            catch {
-                // already closed
-            }
-            this.fsWatcher = null;
-        }
-        this.watchPath = null;
-    }
-    /** Read a workspace file for the preview panel (size-capped, binary-safe). */
-    async readFile(relPath) {
-        try {
-            const fs = await import("node:fs/promises");
-            const root = resolve(this.cwd);
-            const wp = workspacePath(root, relPath);
-            if (!wp) {
-                this.emit({
-                    type: "notice",
-                    level: "warning",
-                    text: `路径超出工作区：${relPath}`,
-                });
-                return;
-            }
-            const { abs, rel } = wp;
-            const stat = await fs.stat(abs);
-            if (!stat.isFile()) {
-                this.emit({
-                    type: "notice",
-                    level: "warning",
-                    text: `不是文件：${relPath}`,
-                });
-                return;
-            }
-            const name = relPath.split(/[\\/]/).pop() ?? relPath;
-            const kind = previewKind(name);
-            // Media previews stream over the /api/file HTTP endpoint, so only
-            // metadata is sent here — the raw bytes never touch the socket.
-            if (kind === "image" || kind === "video") {
-                this.emit({
-                    type: "file_content",
-                    path: rel,
-                    name,
-                    text: "",
-                    truncated: false,
-                    binary: true,
-                    kind,
-                    lines: 0,
-                    size: stat.size,
-                });
-                return;
-            }
-            // Everything else: read a capped prefix and sniff the content.
-            // Anything that looks like text previews as text regardless of its
-            // extension (jsonl, .log.1, weird suffixes, …); binary content gets
-            // a hex dump of the first few KB instead of being refused.
-            const handle = await fs.open(abs, "r");
-            try {
-                const buf = Buffer.alloc(Math.min(stat.size, MAX_PREVIEW_BYTES));
-                const { bytesRead } = await handle.read(buf, 0, buf.length, 0);
-                const data = buf.subarray(0, bytesRead);
-                if (looksLikeText(data)) {
-                    this.emit({
-                        type: "file_content",
-                        path: rel,
-                        name,
-                        text: decodeText(data),
-                        truncated: bytesRead < stat.size,
-                        binary: false,
-                        kind: "text",
-                        lines: countLines(data),
-                        size: stat.size,
-                    });
-                }
-                else {
-                    this.emit({
-                        type: "file_content",
-                        path: rel,
-                        name,
-                        text: hexDump(data),
-                        truncated: bytesRead < stat.size,
-                        binary: true,
-                        kind: kind === "text" ? "text" : "none",
-                        lines: 0,
-                        size: stat.size,
-                    });
-                }
-            }
-            finally {
-                await handle.close();
-            }
-        }
-        catch (err) {
-            this.emit({
-                type: "notice",
-                level: "error",
-                text: `读取文件失败：${err.message}`,
-            });
-        }
-    }
-    /** Save text from the file preview panel within the active workspace. */
-    async writeFile(relPath, text) {
-        try {
-            const root = resolve(this.cwd);
-            const wp = workspacePath(root, relPath);
-            if (!wp) {
-                this.emit({
-                    type: "notice",
-                    level: "warning",
-                    text: `路径超出工作区：${relPath}`,
-                });
-                return;
-            }
-            if (Buffer.byteLength(text, "utf8") > 2 * 1024 * 1024) {
-                this.emit({
-                    type: "notice",
-                    level: "warning",
-                    text: "文件内容过大，无法保存（上限 2MB）",
-                });
-                return;
-            }
-            const stat = statSync(wp.abs);
-            if (!stat.isFile()) {
+                text: "找不到要编辑的消息（可能已被压缩或不在当前分支）",
+            });
+            this.flushSnapshot();
+            return;
+        }
+        try {
+            const result = await this.runtime.fork(entryId);
+            if (result.cancelled) {
                 this.emit({
                     type: "notice",
-                    level: "warning",
-                    text: `不是文件：${relPath}`,
+                    level: "info",
+                    text: "已取消编辑重问",
                 });
+                this.flushSnapshot();
                 return;
             }
-            writeFileSync(wp.abs, text, "utf8");
+            await this.bindSession();
+            await this.prompt(trimmed);
             this.emit({
                 type: "notice",
                 level: "info",
-                text: `已保存：${wp.rel}`,
+                text: "已从该问题重新提问（原对话保留在会话列表中）",
             });
-            // Re-read through the same path as the preview request so the client
-            // gets the canonical content, line count and file size after saving.
-            await this.readFile(wp.rel);
         }
         catch (err) {
             this.emit({
                 type: "notice",
                 level: "error",
-                text: `保存文件失败：${err.message}`,
+                text: `编辑重问失败：${err.message}`,
             });
         }
+        this.flushSnapshot();
+    }
+    /**
+     * Push the recent-project list (persisted per client, merged with every cwd
+     * that has persisted sessions in this client's session store — so workspaces
+     * opened before the recent-list feature existed still show up).
+     */
+    async pushProjects() {
+        try {
+            const saved = this.stateStore.get(this.clientId);
+            const map = new Map();
+            for (const p of saved.projects)
+                map.set(p.path, p.lastUsed);
+            const all = await SessionManager.listAll();
+            for (const s of all) {
+                if (s.cwd) {
+                    const t = s.modified.getTime();
+                    const prev = map.get(s.cwd);
+                    if (prev === undefined || t > prev)
+                        map.set(s.cwd, t);
+                }
+            }
+            // Only keep directories that still exist — a deleted/unmounted workspace
+            // is useless in the picker.
+            const projects = [...map.entries()]
+                .filter(([path]) => existsSync(path))
+                .map(([path, lastUsed]) => ({ path, lastUsed }))
+                .sort((a, b) => b.lastUsed - a.lastUsed)
+                .slice(0, 20);
+            this.emit({ type: "projects", projects });
+        }
+        catch {
+            this.emit({ type: "projects", projects: [] });
+        }
+    }
+    /** List a workspace directory (relative to the configured cwd). */
+    async listFiles(relPath) {
+        return this.files.listFiles(relPath);
+    }
+    /** SCM 只读查询（结构化 JSON，reqId 匹配）。 */
+    async scmQuery(kind, reqId, arg) {
+        return this.files.scmQuery(kind, reqId, arg);
+    }
+    /** Read a workspace file for the preview panel (size-capped, binary-safe). */
+    async readFile(relPath) {
+        return this.files.readFile(relPath);
+    }
+    /** Save text from the file preview panel within the active workspace. */
+    async writeFile(relPath, text) {
+        return this.files.writeFile(relPath, text);
     }
     async cycleModel() {
         try {
@@ -4677,78 +2032,12 @@ ${transcript}
      * directory, and return prefix matches (dirs first, capped).
      */
     async completePath(input) {
-        const empty = () => this.emit({ type: "path_completions", completions: [] });
-        try {
-            const fs = await import("node:fs/promises");
-            const { resolve, sep, isAbsolute } = await import("node:path");
-            const { homedir } = await import("node:os");
-            const home = homedir();
-            // Expand ~ and relative inputs to an absolute path. Windows users type
-            // backslashes (P:\agent) and ~\ — handle both separator styles.
-            let expanded = input.trim();
-            if (expanded === "") {
-                empty();
-                return;
-            }
-            if (expanded === "~" || expanded === "~\\") {
-                expanded = home;
-            }
-            else if (expanded.startsWith("~/") || expanded.startsWith("~\\")) {
-                expanded = home + sep + expanded.slice(2);
-            }
-            else if (!isAbsolute(expanded)) {
-                expanded = resolve(this.cwd, expanded);
-            }
-            // Split into parent dir + prefix on the LAST separator of either style
-            // (Windows accepts both / and \, so P:\agent/de must work too).
-            const lastSlash = Math.max(expanded.lastIndexOf("/"), expanded.lastIndexOf("\\"));
-            const dirPart = lastSlash >= 0 ? expanded.slice(0, lastSlash + 1) : "";
-            const prefix = lastSlash >= 0 ? expanded.slice(lastSlash + 1) : expanded;
-            const dirents = await fs
-                .readdir(dirPart, { withFileTypes: true })
-                .catch(() => null);
-            if (!dirents) {
-                empty();
-                return;
-            }
-            const completions = dirents
-                .filter((d) => d.name.startsWith(prefix) && !ignoredEntries().has(d.name))
-                .map((d) => ({
-                name: d.name,
-                // Windows users type backslashes — normalize the completion to the
-                // wire format ("/") so the picked path round-trips cleanly.
-                path: IS_WIN32
-                    ? join(dirPart, d.name).split(sep).join("/")
-                    : dirPart + d.name,
-                type: (d.isDirectory() ? "dir" : "file"),
-            }))
-                .sort((a, b) => {
-                const aHidden = a.name.startsWith(".");
-                const bHidden = b.name.startsWith(".");
-                if (aHidden !== bHidden)
-                    return aHidden ? 1 : -1;
-                if (a.type !== b.type)
-                    return a.type === "dir" ? -1 : 1;
-                return a.name.localeCompare(b.name);
-            })
-                .slice(0, 30);
-            this.emit({ type: "path_completions", completions });
-        }
-        catch {
-            empty();
-        }
+        return this.files.completePath(input);
     }
-    /**
-     * Switch the agent's working directory by switching the ACTIVE conversation
-     * to the target project's own most recently active conversation (creating a
-     * fresh one that resumes that project's most recent session on first
-     * visit). Conversations of other projects keep running untouched in their
-     * own per-project lists — nothing is rebuilt, so titles/cwds never leak
-     * between projects.
-     */
     async setCwd(newCwd) {
         try {
             const { resolve } = await import("node:path");
+            this.files.unwatchGit(); // stale repo's watcher must not fire across projects
             const fs = await import("node:fs/promises");
             const abs = resolve(newCwd);
             const st = await fs.stat(abs);
@@ -4813,7 +2102,7 @@ ${transcript}
             void this.pushProjects();
             this.webUi.refresh();
             this.emitConversations();
-            this.emitGoalStatus();
+            this.goalSvc.emitGoalStatus();
             // Skills / prompt templates are project-bound — refresh the catalog.
             void this.pushSlashCommands();
             this.emit({
@@ -4860,526 +2149,18 @@ ${transcript}
     // ---------------------------------------------------------------------------
     // Goal / review
     // ---------------------------------------------------------------------------
-    /** Push the active conversation's goal status to the client (the goal bar
-     * UI). Conversations without an active goal reflect the client's remembered
-     * defaults; an existing goal keeps its own review settings. */
-    emitGoalStatus() {
-        const goal = this.goal;
-        if (!goal.goal && !goal.reviewing && !goal.wizard.active) {
-            goal.reviewModel = this.goalReviewPrefs.reviewModel;
-            goal.maxRounds = this.goalReviewPrefs.maxRounds;
-            goal.locked = this.goalReviewPrefs.locked;
-        }
-        this.emit({ type: "goal_status", status: { ...goal } });
-    }
-    /**
-     * Set (or clear) the active goal. `goal === ""` clears it. The goal is
-     * applied to the CURRENT active conversation of this project; reviews check
-     * whatever run finishes next (agent_end).
-     */
+    /** Goal family delegates to GoalService (see goal-service.ts). */
     async setGoal(goalText, opts) {
-        const text = (goalText ?? "").trim();
-        if (!text) {
-            await this.clearGoal();
-            return;
-        }
-        // A goal is scoped to the conversation that is active when it is set.
-        // This prevents an agent_end from a newly-created/switched conversation
-        // from consuming the previous conversation's goal.
-        const goalConversationId = this.activeId;
-        this.conv.goalGeneration += 1;
-        this.goal.reviewing = false;
-        this.goal.conversationId = goalConversationId;
-        this.goal.goal = text;
-        // Model & rounds preference semantics ("全局记忆"):
-        //  - reviewModel undefined → keep the remembered choice; empty → main model.
-        //  - maxRounds 0 = unlimited (default); >0 = finite cap (clamped to 50).
-        if (opts?.reviewModel !== undefined)
-            this.goal.reviewModel = opts.reviewModel || null;
-        if (typeof opts?.maxRounds === "number") {
-            const mr = Math.round(opts.maxRounds);
-            this.goal.maxRounds = mr >= 1 ? Math.min(mr, 50) : 0;
-        }
-        if (opts?.locked !== undefined)
-            this.goal.locked = opts.locked;
-        this.goalReviewPrefs = {
-            reviewModel: this.goal.reviewModel,
-            maxRounds: this.goal.maxRounds,
-            locked: this.goal.locked,
-        };
-        // Persist the chosen preferences so they survive reload.
-        this.stateStore.saveGoalPrefs(this.clientId, {
-            reviewModel: this.goal.reviewModel,
-            maxRounds: this.goal.maxRounds,
-            locked: this.goal.locked,
-        });
-        // Reset the loop for a freshly-set goal (single-shot goals start at 0).
-        this.goal.round = 0;
-        this.goal.reviewing = false;
-        this.goal.verdict = "pending";
-        this.goal.feedback = undefined;
-        this.goal.wizard.active = false;
-        this.goal.wizard.status = "";
-        this.goal.status = "目标已设，等待生成…";
-        this.emitGoalStatus();
-        this.emit({
-            type: "notice",
-            level: "info",
-            text: `🎯 已设目标：${text.slice(0, 80)}${text.length > 80 ? "…" : ""}`,
-        });
-        // Auto-start generation right after setting the goal (unless this setGoal is
-        // the wizard's internal one, which kicks off itself). This makes the direct
-        // goal-bar path behave like the AI-提炼 path: set a target → agent begins.
-        if (opts?.autoStart !== false) {
-            try {
-                const s = this.conv.session;
-                await s.sendUserMessage(`【目标已设定】\n\n${text}\n\n请现在开始实现这个目标。`, { deliverAs: s.isStreaming ? "steer" : "followUp" });
-            }
-            catch {
-                // Best-effort; the user can still prompt manually.
-            }
-            this.flushSnapshot();
-        }
+        return this.goalSvc.setGoal(goalText, opts);
     }
-    /**
-     * Collaborative target wizard. Turns a raw user requirement into a refined
-     * goal by spinning up an ISOLATED wizard session (own fresh ModelRuntime +
-     * in-memory session, so its model choice is its own) that questions the user
-     * via `goal_ask` (multiple-choice + free-text, bridged to the browser through
-     * the existing select/input dialog), converging on a goal, then auto-sets it.
-     * Mutually exclusive with the review loop of the same conversation.
-     */
     async startGoalWizard(text, opts) {
-        if (this.quiesceBlocked())
-            return;
-        const draft = (text ?? "").trim();
-        if (!draft)
-            return;
-        // The wizard and its progress cards belong to the conversation that
-        // launched it. If the user switches away, do not later set a goal on the
-        // new active conversation while the wizard is still finishing.
-        const wizardConversationId = this.activeId;
-        const wizardConversation = this.conv;
-        if (wizardConversation.wizardRunning || this.wizardOwnerId !== null) {
-            this.emit({
-                type: "notice",
-                level: "warning",
-                text: "已有目标调研进行中，请等它完成…",
-            });
-            return;
-        }
-        if (wizardConversation.goal.reviewing) {
-            this.emit({
-                type: "notice",
-                level: "warning",
-                text: "正在审查中，无法开始目标调研，请稍等…",
-            });
-            return;
-        }
-        // Questions are NOT capped (调研不限制) — the wizard converges on its own;
-        // the idle- and total-timeouts are the only guards. maxSteps is purely a
-        // soft UI indicator, not a hard stop.
-        const maxSteps = 20;
-        wizardConversation.wizardRunning = true;
-        this.wizardOwnerId = wizardConversationId;
-        this.wizardCancelled = false;
-        this.wizardAbort = new AbortController();
-        this.wizardSession = null;
-        wizardConversation.goal.wizard.active = true;
-        wizardConversation.goal.wizard.draft = draft;
-        wizardConversation.goal.wizard.model = opts?.wizardModel ?? null;
-        // Remember the model choice (and persist rounds/lock) — global memory.
-        if (opts?.wizardModel !== undefined && opts.wizardModel !== null)
-            wizardConversation.goal.reviewModel = opts.wizardModel || null;
-        if (typeof opts?.maxRounds === "number") {
-            const mr = Math.round(opts.maxRounds);
-            wizardConversation.goal.maxRounds = mr >= 1 ? Math.min(mr, 50) : 0;
-        }
-        if (opts?.locked !== undefined)
-            wizardConversation.goal.locked = opts.locked;
-        this.goalReviewPrefs = {
-            reviewModel: wizardConversation.goal.reviewModel,
-            maxRounds: wizardConversation.goal.maxRounds,
-            locked: wizardConversation.goal.locked,
-        };
-        this.stateStore.saveGoalPrefs(this.clientId, {
-            reviewModel: wizardConversation.goal.reviewModel,
-            maxRounds: wizardConversation.goal.maxRounds,
-            locked: wizardConversation.goal.locked,
-        });
-        wizardConversation.goal.wizard.step = 0;
-        wizardConversation.goal.wizard.maxSteps = maxSteps;
-        wizardConversation.goal.wizard.status = "调研中…";
-        wizardConversation.goal.status = "目标调研中…";
-        this.emitGoalStatus();
-        // Idle-timeout: cancel the wizard if no question is answered within the
-        // window (a stale dialog with no user response must not run forever). A
-        // fresh timer is armed for each question; cleared once the run ends.
-        const ac = this.wizardAbort;
-        let idleTimer = null;
-        const armIdle = () => {
-            if (idleTimer)
-                clearTimeout(idleTimer);
-            idleTimer = setTimeout(() => {
-                if (!ac.signal.aborted) {
-                    this.wizardCancelled = true;
-                    ac.abort(new Error("目标调研超时（等待回答过久）"));
-                }
-            }, ClientSession.WIZARD_IDLE_TIMEOUT_MS);
-            idleTimer.unref?.();
-        };
-        const clearIdle = () => {
-            if (idleTimer) {
-                clearTimeout(idleTimer);
-                idleTimer = null;
-            }
-        };
-        armIdle();
-        // Total-duration guard: hard cap on the whole wizard session (model
-        // latency / unexpected loops must not run forever).
-        const totalTimer = setTimeout(() => {
-            if (!ac.signal.aborted) {
-                this.wizardCancelled = true;
-                ac.abort(new Error("目标调研超过总时长上限"));
-            }
-        }, ClientSession.WIZARD_MAX_TOTAL_MS);
-        totalTimer.unref?.();
-        this.emit({
-            type: "notice",
-            level: "info",
-            text: `🔍 正在围绕需求展开调研：${draft.slice(0, 60)}${draft.length > 60 ? "…" : ""}`,
-        });
-        // The main conversation to show wizard progress cards in.
-        const mainSession = wizardConversation.session;
-        let refinedGoal = "";
-        try {
-            const wmSpec = opts?.wizardModel
-                ? this.resolveReviewModel(opts.wizardModel)
-                : null; // reuse the honest "provider/id" parser
-            const services = await createAgentSessionServices({
-                cwd: wizardConversation.cwd,
-                agentDir: this.agentDir,
-                modelRuntime: await ModelRuntime.create({
-                    authPath: join(this.agentDir, "auth.json"),
-                    modelsPath: join(this.agentDir, "models.json"),
-                }),
-            });
-            let model;
-            if (wmSpec)
-                model = services.modelRuntime.getModel(wmSpec.provider, wmSpec.id);
-            if (!model) {
-                const mainModel = mainSession.model;
-                if (mainModel?.provider && mainModel.id)
-                    model = services.modelRuntime.getModel(mainModel.provider, mainModel.id);
-            }
-            // The wizard asks the user questions via this tool; each call bridges one
-            // select/input dialog to the browser and returns the user's answer.
-            let qStep = 0;
-            const goalAsk = defineTool({
-                name: "goal_ask",
-                label: "Ask the user",
-                description: "Ask the user ONE question at a time to scope down the goal. Provide a clear question and 2-4 concise options; or ask an open question. Returns the user's chosen answer.",
-                parameters: Type.Object({
-                    question: Type.String({ description: "The question to ask" }),
-                    options: Type.Optional(Type.Array(Type.String())),
-                }),
-                // ONE question at a time. Sequential execution prevents the agent from
-                // firing parallel goal_ask calls whose dialogs would overwrite each other
-                // in the single browser modal (leaving earlier ones deadlocked — the
-                // reported "调研卡住").
-                executionMode: "sequential",
-                execute: async (_id, params, _sig, _onUpdate, ctx) => {
-                    qStep += 1;
-                    if (qStep > maxSteps) {
-                        return {
-                            content: [
-                                {
-                                    type: "text",
-                                    text: "(达到最大提问数，请直接给出收敛后的目标文本作为最终答案)",
-                                },
-                            ],
-                            details: {},
-                        };
-                    }
-                    // Show the question in the main flow BEFORE blocking on the dialog, so
-                    // the user sees the wizard working even before answering.
-                    wizardConversation.goal.wizard.step = qStep;
-                    wizardConversation.goal.wizard.status = `调研中：请回答第 ${qStep} 题`;
-                    this.emitGoalStatus();
-                    try {
-                        armIdle();
-                        const isChoice = !!(params.options && params.options.length > 0);
-                        await this.pushWizardCard(mainSession, `🔍 第 ${qStep} 题：${params.question}${isChoice ? `【${params.options.join(" / ")}】` : ""}`, { question: params.question });
-                        // Resolve the pending dialog as cancelled if the wizard is aborted.
-                        let aborted = false;
-                        const onAbort = () => {
-                            aborted = true;
-                        };
-                        ac.signal.addEventListener("abort", onAbort, { once: true });
-                        const choose = isChoice
-                            ? ctx.ui.select(`🔍 第 ${qStep} 题：${params.question}`, params.options)
-                            : ctx.ui.input(`🔍 第 ${qStep} 题：${params.question}`);
-                        const ans = (await choose);
-                        ac.signal.removeEventListener("abort", onAbort);
-                        if (aborted || ac.signal.aborted) {
-                            return {
-                                content: [
-                                    {
-                                        type: "text",
-                                        text: "(调研已取消，请不要继续提问，直接结束对话)",
-                                    },
-                                ],
-                                details: {},
-                            };
-                        }
-                        if (ans === undefined || ans === null || ans === false || ans === "") {
-                            return {
-                                content: [
-                                    {
-                                        type: "text",
-                                        text: "(用户已取消调研，请直接给出你当前收敛的目标文本作为最终答案)",
-                                    },
-                                ],
-                                details: {},
-                            };
-                        }
-                        // Record the answer in the flow too (instant append, main session idle).
-                        await this.pushWizardCard(mainSession, `↳ 您的回答：${ans}`, { question: params.question, answer: String(ans) });
-                        return {
-                            content: [{ type: "text", text: `用户回答：${ans}` }],
-                            details: {},
-                        };
-                    }
-                    catch (err) {
-                        return {
-                            content: [
-                                {
-                                    type: "text",
-                                    text: ac.signal.aborted
-                                        ? "(调研已取消，请不要继续提问，直接结束对话)"
-                                        : `提问失败：${err.message}`,
-                                },
-                            ],
-                            details: {},
-                        };
-                    }
-                },
-            });
-            const srv = await createAgentSessionFromServices({
-                services,
-                sessionManager: SessionManager.inMemory(this.cwd),
-                customTools: [goalAsk],
-                ...(model ? { model } : {}),
-            });
-            const wizard = srv.session;
-            this.wizardSession = wizard;
-            await wizard.bindExtensions({ mode: "rpc", uiContext: this.webUi });
-            // Cancel watcher: when the user ✗s / idle-timeout fires, truly stop the
-            // wizard's agent run (not just mark it).
-            if (!ac.signal.aborted) {
-                ac.signal.addEventListener("abort", () => {
-                    void wizard.abort().catch(() => { });
-                    // Close the unanswered browser dialog(s) the wizard may have up.
-                    this.webUi.cancelPendingDialogs();
-                }, { once: true });
-            }
-            await wizard.prompt(wizardPrompt(draft));
-            refinedGoal = wizard.getLastAssistantText()?.trim() ?? "";
-            // The wizard is prompted to emit "GOAL: <text>". Parse past the marker;
-            // if it didn't follow, strip a leading preamble line and keep the rest.
-            const goalMatch = refinedGoal.match(/GOAL\s*[:：]\s*([\s\S]*)/i);
-            if (goalMatch) {
-                refinedGoal = goalMatch[1].trim();
-            }
-            else {
-                const lines = refinedGoal.split("\n").filter((l) => l.trim());
-                if (lines.length > 1 && !/[。.!?？]\s*$/.test(lines[0])) {
-                    // First line looks like preamble (no sentence-ending punctuation).
-                    refinedGoal = lines.slice(1).join(" ").trim();
-                }
-            }
-            await srv.session.dispose();
-        }
-        catch (err) {
-            this.emit({
-                type: "notice",
-                level: "error",
-                text: `目标调研失败：${err.message}`,
-            });
-        }
-        finally {
-            clearIdle();
-            clearTimeout(totalTimer);
-            wizardConversation.wizardRunning = false;
-            if (this.wizardOwnerId === wizardConversationId)
-                this.wizardOwnerId = null;
-            wizardConversation.goal.wizard.active = false;
-            wizardConversation.goal.wizard.step = 0;
-            wizardConversation.goal.wizard.status = "";
-            this.wizardSession = null;
-            this.emitGoalStatus();
-        }
-        // Aborted externally (✗ / clear_goal / idle-timeout): do NOT set a goal.
-        if (ac.signal.aborted || this.wizardCancelled) {
-            this.emit({
-                type: "notice",
-                level: "info",
-                text: `目标调研已取消${ac.signal.reason ? `：${String(ac.signal.reason?.message ?? ac.signal.reason)}` : ""}`,
-            });
-            this.wizardAbort = null;
-            return;
-        }
-        if (!refinedGoal.trim()) {
-            this.emit({
-                type: "notice",
-                level: "warning",
-                text: "调研未产出有效目标，请重试",
-            });
-            return;
-        }
-        if (this.activeId !== wizardConversationId) {
-            this.emit({
-                type: "notice",
-                level: "info",
-                text: "已切换对话，目标调研结果已丢弃",
-            });
-            return;
-        }
-        // Auto-set the refined goal. The wizard workflow implies "set a goal and
-        // work until it passes", so default LOCKED=true unless the user explicitly
-        // turned the lock off (a lock lets the review loop keep revising to pass;
-        // without it the review is single-shot).
-        const wantLocked = opts?.locked === undefined ? true : opts.locked;
-        await this.setGoal(refinedGoal, {
-            reviewModel: wizardConversation.goal.reviewModel ?? undefined,
-            maxRounds: opts?.maxRounds,
-            locked: wantLocked,
-            // The wizard kicks off generation itself below — avoid a double kick.
-            autoStart: false,
-        });
-        const g2 = wizardConversation.goal;
-        this.wizardCancelled = false;
-        this.wizardAbort = null;
-        this.emit({
-            type: "notice",
-            level: "info",
-            text: `🎯 调研完成，目标已设为：${refinedGoal.slice(0, 80)}${refinedGoal.length > 80 ? "…" : ""}`,
-        });
-        // Kick the main agent into generating right away (no manual "开始吧").
-        // The kick-off is a user message so it appears in the flow and triggers a
-        // normal turn; the finishing agent_end then runs the review loop.
-        try {
-            await mainSession.sendUserMessage(`【目标已设定】\n\n${g2.goal}\n\n请现在开始实现这个目标。`, { deliverAs: mainSession.isStreaming ? "steer" : "followUp" });
-        }
-        catch {
-            // Generation kick-off is best-effort; the user can still prompt manually.
-        }
+        return this.goalSvc.startGoalWizard(text, opts);
     }
-    /** Persist goal/review preference defaults (model, rounds cap, locked) without
-     *  touching the active goal — so changes in the goal bar are remembered across
-     *  reloads. maxRounds 0 = unlimited. Emits goal_status so the UI stays synced. */
     async setGoalPrefs(opts) {
-        if (opts?.reviewModel !== undefined)
-            this.goal.reviewModel = opts.reviewModel || null;
-        if (typeof opts?.maxRounds === "number") {
-            const mr = Math.round(opts.maxRounds);
-            this.goal.maxRounds = mr >= 1 ? Math.min(mr, 50) : 0;
-        }
-        if (opts?.locked !== undefined)
-            this.goal.locked = opts.locked;
-        this.goalReviewPrefs = {
-            reviewModel: this.goal.reviewModel,
-            maxRounds: this.goal.maxRounds,
-            locked: this.goal.locked,
-        };
-        this.stateStore.saveGoalPrefs(this.clientId, {
-            reviewModel: this.goal.reviewModel,
-            maxRounds: this.goal.maxRounds,
-            locked: this.goal.locked,
-        });
-        this.emitGoalStatus();
+        return this.goalSvc.setGoalPrefs(opts);
     }
-    /** Clear the active goal (cancels the review loop AND aborts a running
-     *  goal wizard — truly terminating its in-flight dialog + agent run). */
     async clearGoal() {
-        this.conv.goalGeneration += 1;
-        this.goal.reviewing = false;
-        this.goal.conversationId = null;
-        this.goal.goal = null;
-        this.goal.reviewing = false;
-        this.goal.verdict = "pending";
-        this.goal.feedback = undefined;
-        this.goal.wizard.active = false;
-        this.goal.wizard.status = "";
-        this.goal.status = "";
-        this.emitGoalStatus();
-        // Abort a running wizard for real (✗ in the goal bar while scoping).
-        if (this.wizardOwnerId === this.activeId) {
-            this.wizardCancelled = true;
-            this.webUi.cancelPendingDialogs();
-            this.wizardAbort?.abort();
-            const ws2 = this.wizardSession;
-            this.wizardSession = null;
-            if (ws2) {
-                await ws2.abort().catch(() => { });
-                ws2.dispose();
-            }
-            this.wizardAbort = null;
-        }
-    }
-    /** Build a "provider/id" or null for the reviewer model, validating it exists. */
-    resolveReviewModel(spec) {
-        if (!spec)
-            return null;
-        const slash = spec.indexOf("/");
-        if (slash <= 0 || slash === spec.length - 1)
-            return null;
-        return { provider: spec.slice(0, slash), id: spec.slice(slash + 1), spec };
-    }
-    /**
-     * The whitelisted reviewer plan — tell the reviewer what to decide and how
-     * to report, regardless of which model it runs on.
-     */
-    reviewerPrompt(goal, round, maxRounds, output, gitDiff, customPrompt = "") {
-        return [
-            `You are a strict, independent goal-reviewer. Your ONLY job is to judge whether the agent's work fully satisfies the stated goal, by checking the agent's final output and, when present, its git diff.`, // eslint-disable-line max-len
-            ``,
-            `# Goal`, // eslint-disable-line no-regex-spaces
-            goal,
-            ``,
-            `# Agent's final output`, // eslint-disable-line no-regex-spaces
-            output.length > 0 ? output : "(the agent produced no text — inspect the diff)", // eslint-disable-line max-len
-            ``,
-            `# Git diff (if any)`, // eslint-disable-line no-regex-spaces
-            gitDiff.length > 0 ? gitDiff : "(no staged/committed changes detected)", // eslint-disable-line max-len
-            ``,
-            `This is review round ${round}${maxRounds > 0 ? ` of up to ${maxRounds}` : " (no round cap — keep revising until it passes)"}.`, // eslint-disable-line max-len
-            ...(customPrompt.trim()
-                ? [``, `# Additional reviewer instructions`, customPrompt.trim()]
-                : []),
-            ``,
-            `Decide: does the work satisfy the goal? If yes, respond with ONLY a JSON object with this exact shape (no markdown fences, no extra text):`, // eslint-disable-line max-len
-            `{"verdict":"pass","feedback":"<one short sentence: what was satisfied>"}`, // eslint-disable-line max-len
-            `If NO, respond with ONLY: {"verdict":"fail","feedback":"<concise, actionable list of what the agent must fix to satisfy the goal>"}`, // eslint-disable-line max-len
-            `The feedback for a fail must be specific enough that the agent can act on it directly.`, // eslint-disable-line max-len
-        ].join("\n");
-    }
-    /** Insert a wizard progress card into the MAIN conversation flow and render it
-     *  IMMEDIATELY (the main session is idle while the wizard runs in its own
-     *  session, so — unlike nextTurn, which queues until the next user prompt —
-     *  sending without a delivery option appends + persists + emits at once). */
-    async pushWizardCard(sess, text, details) {
-        try {
-            await sess.sendCustomMessage({
-                customType: "goal-wizard",
-                content: [{ type: "text", text }],
-                display: true,
-                details: { type: "goal-wizard", ...details },
-            });
-        }
-        catch {
-            // Non-fatal
-        }
+        return this.goalSvc.clearGoal();
     }
     /** Run a git diff (unstaged + staged) in a conversation's workspace, or
      * "" when not a repo. */
@@ -5394,228 +2175,6 @@ ${transcript}
             return "";
         }
     }
-    /**
-     * The review loop: build an ISOLATED reviewer session (own fresh
-     * AgentSession + own ModelRuntime so the reviewer truly runs on a different
-     * model without touching the main session), ask it to judge the goal, then:
-     *   - pass  → set status "已通过", insert a verdict card, end the loop;
-     *   - fail  → inject the feedback as a user message into the main session
-     *             to steer a revision; the next agent_end re-reviews with the
-     *             same round budget.
-     * Guarded per conversation so separate conversations can review concurrently.
-     */
-    isCurrentGoalReview(conv, goalGeneration, reviewGeneration) {
-        return (!this.disposed &&
-            this.convs.get(conv.id) === conv &&
-            conv.goal.conversationId === conv.id &&
-            conv.goalGeneration === goalGeneration &&
-            conv.goalReviewGeneration === reviewGeneration &&
-            !!conv.goal.goal);
-    }
-    /** Drop the result of a review that became stale while it was awaiting the
-     * reviewer model (most commonly because the user switched conversations). */
-    discardStaleGoalReview(conv, goalGeneration, reviewGeneration) {
-        if (conv.goalReviewGeneration !== reviewGeneration)
-            return;
-        if (conv.goalGeneration === goalGeneration &&
-            conv.goal.conversationId === conv.id) {
-            conv.goal.reviewing = false;
-            conv.goal.status = "审查已中止，目标已更新或取消";
-            this.emitGoalStatus();
-        }
-    }
-    async runGoalReview(conv) {
-        // The review is bound to the conversation that just ran. Capture both the
-        // owner and a generation so a later switch/set/clear cannot let an old,
-        // asynchronous reviewer mutate the new conversation's goal state.
-        const mainConv = this.convs.get(conv.id) ?? conv;
-        const mainSession = mainConv.session;
-        const g = conv.goal;
-        if (!g.goal ||
-            g.conversationId !== conv.id ||
-            g.reviewing ||
-            conv.wizardRunning ||
-            this.disposed)
-            return;
-        const goalGeneration = conv.goalGeneration;
-        const reviewGeneration = ++conv.goalReviewGeneration;
-        // Narrowed copy — TS control-flow can't narrow `g.goal` (a mutable shared
-        // object field) through the entire async body, so capture it here.
-        const goalText = g.goal;
-        // Capture review-only settings for this run. Changing settings while a
-        // review is in flight affects the next review, never this one.
-        const reviewPrompt = this.settings.reviewPrompt;
-        const reviewDisabledSkills = new Set(this.settings.reviewDisabledSkills);
-        // Cap rounds: single-shot (locked=false) always exactly one review.
-        // For locked goals, maxRounds 0 = unlimited (keep revising until pass).
-        const budget = g.locked ? (g.maxRounds > 0 ? g.maxRounds : Infinity) : 1;
-        if (g.locked && g.maxRounds > 0 && g.round >= budget) {
-            g.status = `已达最大轮数（${budget}），停止审查`;
-            g.reviewing = false;
-            this.emitGoalStatus();
-            return;
-        }
-        g.reviewing = true;
-        g.round += 1;
-        g.verdict = "pending";
-        g.feedback = undefined;
-        g.status = `审查中（第 ${g.round} 轮）…`;
-        this.emitGoalStatus();
-        // Collect the review inputs.
-        let finalText = "";
-        try {
-            finalText = mainSession.getLastAssistantText() ?? "";
-        }
-        catch {
-            finalText = "";
-        }
-        const diff = await this.gitDiff(mainConv.cwd);
-        if (!this.isCurrentGoalReview(conv, goalGeneration, reviewGeneration)) {
-            this.discardStaleGoalReview(conv, goalGeneration, reviewGeneration);
-            return;
-        }
-        let reviewerVerdict = "fail";
-        let reviewerFeedback = "（审查无法完成）";
-        try {
-            const rmSpec = this.resolveReviewModel(g.reviewModel);
-            const services = await createAgentSessionServices({
-                cwd: mainConv.cwd,
-                agentDir: this.agentDir,
-                // The reviewer has its own skill allow/deny list. It deliberately does
-                // not reuse the main session's disabledSkills setting.
-                resourceLoaderOptions: {
-                    skillsOverride: (res) => ({
-                        ...res,
-                        skills: res.skills.filter((s) => !reviewDisabledSkills.has(s.name)),
-                    }),
-                },
-                // A FRESH ModelRuntime for the reviewer — isolated from the shared
-                // one used by the main conversations, so its model choice is its own.
-                modelRuntime: await ModelRuntime.create({
-                    authPath: join(this.agentDir, "auth.json"),
-                    modelsPath: join(this.agentDir, "models.json"),
-                }),
-            });
-            // Model resolution: explicit reviewer model, else the main session's
-            // current model (so a goal works even when no reviewer model is given).
-            let model;
-            if (rmSpec) {
-                model = services.modelRuntime.getModel(rmSpec.provider, rmSpec.id);
-            }
-            if (!model) {
-                const mainModel = mainSession.model;
-                if (mainModel?.provider && mainModel.id) {
-                    model = services.modelRuntime.getModel(mainModel.provider, mainModel.id);
-                }
-            }
-            const srv = await createAgentSessionFromServices({
-                services,
-                sessionManager: SessionManager.inMemory(mainConv.cwd),
-                ...(model ? { model } : {}),
-            });
-            const reviewCap = g.locked && g.maxRounds > 0 ? g.maxRounds : 0; // 0 = no cap
-            const reviewer = srv.session;
-            await reviewer.prompt(this.reviewerPrompt(goalText, g.round, reviewCap, finalText, diff, reviewPrompt));
-            // Parse the reviewer's final output (expected to be a JSON object).
-            const raw = reviewer.getLastAssistantText() ?? "";
-            const m = raw.match(/\{\s*"verdict"\s*:\s*"(pass|fail)"[^}]*\}/);
-            if (m) {
-                reviewerVerdict = m[1];
-                const fm = raw.match(/"feedback"\s*:\s*"([^"]*)"/);
-                reviewerFeedback = fm?.[1] ?? "";
-            }
-            else {
-                // No JSON — assume fail with the raw output as feedback.
-                reviewerVerdict = "fail";
-                reviewerFeedback = raw.slice(0, 2000);
-            }
-            await srv.session.dispose();
-        }
-        catch (err) {
-            reviewerVerdict = "fail";
-            reviewerFeedback = `审查过程中出错：${err.message}`;
-        }
-        // The user may have switched chats or replaced/cleared the goal while the
-        // isolated reviewer was running. Never apply a stale verdict or inject it
-        // into the old session after that point.
-        if (!this.isCurrentGoalReview(conv, goalGeneration, reviewGeneration)) {
-            this.discardStaleGoalReview(conv, goalGeneration, reviewGeneration);
-            return;
-        }
-        g.reviewing = false;
-        g.verdict = reviewerVerdict;
-        g.feedback = reviewerFeedback;
-        const round = g.round;
-        // Display cap: 0 means "unlimited" (keep revising until pass).
-        const budgetForCard = g.locked ? (Number.isFinite(budget) ? budget : 0) : 1;
-        const verdict = reviewerVerdict;
-        const feedback = reviewerFeedback;
-        /** Format "round/cap" for user-facing strings; cap 0 → 不限. */
-        const capFmt = (cap) => cap > 0 ? `第 ${round}/${cap} 轮` : `第 ${round} 轮（不限）`;
-        if (verdict === "pass") {
-            g.status = "✅ 已通过目标审查";
-            this.emit({ type: "notice", level: "info", text: "✅ 目标已通过审查" });
-            g.conversationId = null;
-            g.goal = null; // a passed goal is done and cleared
-            this.emitGoalStatus();
-            // Pass = the review result goes straight into the conversation as an
-            // ordinary user message (NO separate goal-review card). It both tells the
-            // USER the outcome and hands the main agent back out of "goal mode", so a
-            // follow-up instruction like "发布" is a normal request — not a confirm echo.
-            try {
-                await mainSession.sendUserMessage(`✅ 目标已达成并通过审查（第 ${round} 轮）。\n\n目标：${goalText}\n\n${feedback}\n\n（目标模式已解除，接下来按你的普通指令响应。）`, { deliverAs: mainSession.isStreaming ? "steer" : "followUp" });
-            }
-            catch {
-                // Best-effort.
-            }
-            this.flushSnapshot();
-            return;
-        }
-        // Failure: if rounds remain, steer a revision; else report the loop done.
-        // For unlimited (budget=0) isLastRound is always false → keeps revising.
-        const isLastRound = !g.locked ? true : g.maxRounds > 0 && g.round >= g.maxRounds;
-        if (!isLastRound) {
-            g.status = `本轮不通过，正在把意见交给 agent 修改（${capFmt(budgetForCard)}）…`;
-            this.emit({
-                type: "notice",
-                level: "warning",
-                text: `目标审查第 ${g.round}/${budgetForCard > 0 ? budgetForCard : "不限"} 轮未通过，把意见交给 agent 修改…`,
-            });
-            // Inject the reviewer's feedback into the main session to revise (this IS
-            // the fail review result, as an ordinary user message — no separate card).
-            try {
-                const steerText = `【目标审查：第 ${g.round}/${budgetForCard > 0 ? budgetForCard : "不限"} 轮未通过】\n\n目标：${goalText}\n\n` +
-                    `审查意见：${feedback}\n\n请根据以上意见修改你的成果，使其完全满足目标。`;
-                await mainSession.sendUserMessage(steerText, {
-                    deliverAs: mainSession.isStreaming ? "steer" : "followUp",
-                });
-            }
-            catch (err) {
-                g.status = `意见注入失败：${err.message}`;
-            }
-            this.emitGoalStatus();
-            this.flushSnapshot();
-            return;
-        }
-        // Rounds exhausted (finite cap reached / single-shot failed). Deliver the
-        // fail result as an ordinary user message (no separate card), like the pass
-        // and revise paths — the review result always lands in the conversation.
-        g.status =
-            g.locked && g.maxRounds > 0
-                ? `已达最大轮数（${g.maxRounds}），目标仍未通过`
-                : `目标未通过（${capFmt(budgetForCard)}）`;
-        try {
-            await mainSession.sendUserMessage(`❌ 目标未通过审查（第 ${round}/${budgetForCard > 0 ? budgetForCard : "不限"} 轮）。\n\n目标：${goalText}\n\n审查意见：${feedback}`, { deliverAs: mainSession.isStreaming ? "steer" : "followUp" });
-        }
-        catch {
-            // Best-effort.
-        }
-        this.emit({ type: "notice", level: "warning", text: "目标未通过审查（已达最大轮数）" });
-        g.conversationId = null;
-        g.goal = null; // loop exhausted — clear the active goal
-        this.emitGoalStatus();
-        this.flushSnapshot();
-    }
     /** Switch to a specific model by "provider/id" (e.g. "anthropic/claude-sonnet-5"). */
     async setModel(modelId) {
         try {
@@ -5701,12 +2260,10 @@ ${transcript}
             clearInterval(this.widgetsTimer);
             this.widgetsTimer = null;
         }
-        this.unwatchDir();
+        this.files.unwatchDir();
+        this.files.unwatchGit();
         this.webUi.dispose();
-        if (this.bgTimer) {
-            clearInterval(this.bgTimer);
-            this.bgTimer = null;
-        }
+        this.bg.stop();
         for (const conv of this.convs.values()) {
             this.clearAllToolWatchdogs(conv);
             conv.unsubscribe?.();