@cjhyy/code-shell-core 0.7.1 → 0.8.0

package/dist/protocol/server.js

@@ -15,10 +15,9 @@
  */
 import { Methods, ErrorCodes, createResponse, createErrorResponse, createNotification, isRequest, } from "./types.js";
 import { diskDefaultsFrom } from "../engine/engine.js";
-import { isProtectedSettingKey } from "../settings/manager.js";
+import { isProtectedSettingKey, SettingsManager } from "../settings/manager.js";
 import { getApprovalRouter, getInteractiveApprovalBackend, } from "../tool-system/permission.js";
-import { getArenaStatus } from "../tool-system/builtin/arena.js";
-import { agentNotificationBus, notificationQueue, buildNotificationMessage, } from "../tool-system/builtin/agent-notifications.js";
+import { agentNotificationBus, notificationQueue, buildNotificationMessage, notificationEnvelopeToLegacyStreamEvent, } from "../tool-system/builtin/agent-notifications.js";
 import { backgroundShellManager } from "../runtime/background-shell.js";
 import { backgroundJobRegistry } from "../tool-system/builtin/background-jobs.js";
 import { listBackgroundWorkForUI } from "../tool-system/builtin/background-work.js";
@@ -27,6 +26,8 @@ import { nanoid } from "nanoid";
 import { assertSafeSessionId, SessionManager } from "../session/session-manager.js";
 import { redactLlmConfig, maskSecretValue } from "./redact.js";
 import { redactSecrets } from "../logging/sanitize-messages.js";
+import { computeEffectiveDisabledLists } from "../capability-control/disabled-lists.js";
+import { describePluginCommands, expandPluginCommandBody, scanPluginCommands, MAX_PLUGIN_COMMAND_ARGUMENT_CHARS, } from "../plugins/pluginCommandsLoader.js";
 function isValidRunAttachment(value) {
     if (!value || typeof value !== "object")
         return false;
@@ -48,6 +49,30 @@ function runInputError(params) {
     if (params.task.trim().length === 0 && !hasAttachment) {
         return "task or a valid attachment is required";
     }
+    if (params.displayText !== undefined &&
+        (typeof params.displayText !== "string" ||
+            params.displayText.trim().length === 0 ||
+            params.displayText.length > 20_000)) {
+        return "displayText must be a non-empty string up to 20000 characters";
+    }
+    if (params.injected !== undefined && typeof params.injected !== "boolean") {
+        return "injected must be a boolean";
+    }
+    if (params.behaviorMode !== undefined &&
+        (typeof params.behaviorMode !== "string" || params.behaviorMode.length === 0)) {
+        return `invalid behavior mode: ${String(params.behaviorMode)}`;
+    }
+    if (params.kind !== undefined && (typeof params.kind !== "string" || params.kind.length === 0)) {
+        return `invalid session kind: ${String(params.kind)}`;
+    }
+    if (params.profileParams !== undefined &&
+        (!params.profileParams ||
+            typeof params.profileParams !== "object" ||
+            Array.isArray(params.profileParams))) {
+        return "profileParams must be an object";
+    }
+    // Domain-specific run-param validation (e.g. behavior-mode vocabularies and
+    // extension-owned param shapes) lives in ExtensionModule.validateRunParams.
     return null;
 }
 const COMPACT_STREAM_STRATEGIES = new Set([
@@ -57,14 +82,146 @@ const COMPACT_STREAM_STRATEGIES = new Set([
     "snip",
     "emergency",
     "compacted",
+    // Range archival (archive_range query) emits its boundary through this map;
+    // without "range" here it would be silently downgraded to "compacted".
+    "range",
 ]);
 function toCompactStreamStrategy(strategy) {
     return COMPACT_STREAM_STRATEGIES.has(strategy)
         ? strategy
         : "compacted";
 }
+const INTERNAL_PENDING_TOOLS = new Set([
+    "__browser_action__",
+    "__credential_action__",
+    "__workspace_action__",
+]);
+function internalCancellation(failure, reason) {
+    return { __internalCancelled: true, failure, reason };
+}
+function asInternalCancellation(value) {
+    return value &&
+        typeof value === "object" &&
+        value.__internalCancelled === true
+        ? value
+        : undefined;
+}
+/** Human-facing tail appended to a host-loopback failure detail. */
+const HOST_LOOPBACK_FAILURE_DETAIL = {
+    denied: "declined by the user",
+    cancelled: "cancelled because the turn was stopped",
+    session_closed: "cancelled because the session closed",
+    owner_lost: "unavailable because the approving client disconnected",
+    timed_out: "timed out waiting for the host",
+    malformed: "returned a malformed result",
+};
+/**
+ * Cap on host-supplied failure text forwarded to the model.
+ *
+ * The rest of the Panel path is carefully bounded (512KB JSON results, 500-char
+ * tool descriptions, ≤16 tools); the failure path must be too. Host text reaches
+ * the model verbatim, so an unbounded echo is both a context-budget hazard and an
+ * injection surface. Collapsed to one line so a multi-line payload can't fake
+ * structure in the tool result.
+ */
+const MAX_HOST_LOOPBACK_DETAIL_CHARS = 500;
+function boundedHostDetail(text) {
+    const oneLine = text.replace(/\s+/gu, " ").trim();
+    return oneLine.length <= MAX_HOST_LOOPBACK_DETAIL_CHARS
+        ? oneLine
+        : `${oneLine.slice(0, MAX_HOST_LOOPBACK_DETAIL_CHARS)}…`;
+}
+/**
+ * Recover the classified failure detail a host-loopback request settled with, if
+ * any. Bridges call this before falling back to "malformed result": a cancelled /
+ * denied / timed-out request is a KNOWN terminal state, and mislabelling it as
+ * malformed blames the host for something the user (or a closing session) did.
+ */
+function hostLoopbackDetail(result) {
+    if (!result || typeof result !== "object")
+        return undefined;
+    const candidate = result;
+    // Take the human-readable text FIRST, and do NOT require `failure` to be
+    // present. Genuine Desktop replies are `{ok:false, panelId?, detail}` and carry
+    // no `failure` key at all (see AgentPanelHostResult) — gating on `failure`
+    // discarded every real host error and relabelled it "malformed result", which
+    // is exactly the mislabelling this whole change exists to prevent.
+    // The bridges also disagree on the key: panel uses `error`, browser `detail`.
+    if (typeof candidate.error === "string" && candidate.error) {
+        return boundedHostDetail(candidate.error);
+    }
+    if (typeof candidate.detail === "string" && candidate.detail) {
+        return boundedHostDetail(candidate.detail);
+    }
+    // Classification only — never the raw string. `failure` arrives from
+    // host-parsed JSON, so echoing an unrecognized value verbatim would let the
+    // host inject arbitrary unbounded text into a tool result.
+    if (typeof candidate.failure === "string") {
+        return HOST_LOOPBACK_FAILURE_DETAIL[candidate.failure];
+    }
+    return undefined;
+}
+/**
+ * Normalize what a host-loopback resolver received into either the parsed host
+ * payload or a classified failure. Shared by all four bridges so their terminal
+ * semantics can't drift apart.
+ *
+ * Accepts `{approved:true, answer:<json>}` (the ApprovalResult shape main replies
+ * with), a bare JSON string, or an InternalPendingCancellation sentinel.
+ */
+function parseHostLoopbackDecision(decision, label) {
+    const cancelled = asInternalCancellation(decision);
+    if (cancelled) {
+        return {
+            ok: false,
+            failure: cancelled.failure,
+            detail: `${label} ${HOST_LOOPBACK_FAILURE_DETAIL[cancelled.failure]}`,
+        };
+    }
+    let raw;
+    if (decision && typeof decision === "object" && "approved" in decision) {
+        const result = decision;
+        raw = result.approved ? result.answer : undefined;
+    }
+    else if (typeof decision === "string") {
+        raw = decision;
+    }
+    if (raw === undefined) {
+        return {
+            ok: false,
+            failure: "denied",
+            detail: `${label} ${HOST_LOOPBACK_FAILURE_DETAIL.denied}`,
+        };
+    }
+    try {
+        return { ok: true, value: JSON.parse(raw) };
+    }
+    catch {
+        // The host answered but garbled it. That is NOT a denial — blaming the user
+        // for a host serialization bug sends the model looking in the wrong place.
+        return {
+            ok: false,
+            failure: "malformed",
+            detail: `${label} ${HOST_LOOPBACK_FAILURE_DETAIL.malformed}`,
+        };
+    }
+}
+function safeApprovalToolName(toolName) {
+    const firstLine = toolName.split(/\r?\n/, 1)[0]?.trim() ?? "";
+    if (/(?:sk|api|token|secret)[-_][a-z0-9_-]{6,}/i.test(firstLine))
+        return "工具";
+    return (firstLine
+        .replace(/[^\p{L}\p{N}_.:@/-]+/gu, " ")
+        .trim()
+        .slice(0, 40) || "工具");
+}
 export class AgentServer {
-    chatManager;
+    /** Host-supplied manager; requests route through the `chatManager` getter. */
+    baseChatManager;
+    /** Identity resolution hook; null → single-manager behavior (today's path). */
+    resolveIdentity;
+    /** Lazily-derived managers keyed by identity (non-base identities only). */
+    identityManagers = new Map();
     legacyEngine;
     globalQueryEngine = null;
     transport;
@@ -72,13 +229,24 @@ export class AgentServer {
     settingsReader;
     /** Disk-only active-goal reader for agent/goalGet on a non-live session. */
     readActiveGoalFromDisk;
+    updateActiveGoalOnDisk;
+    clearActiveGoalOnDisk;
     workspaceBridgeEnabled;
+    panelBridgeEnabled;
     connectionId;
     strictApprovalRouting;
     approvalRouter;
     approvalConnectionUnregister = null;
     disconnected = false;
     pendingApprovalTargets = new Map();
+    /** Extension modules this server consults for protocol-level hooks. */
+    extensionModules;
+    /** Protocol lifecycle observers created by extension modules (registration order). */
+    protocolObservers = [];
+    /** Extension-registered protocol method/query aliases (compat channel). */
+    protocolQueryHandlers = new Map();
+    /** Union of extension hiddenSessionKinds, excluded from generic session lists. */
+    hiddenSessionKinds;
     /**
      * Last per-session EngineConfigSlice supplied by agent/run. Kept even after
      * idle eviction so background-completion wakeups can rebuild the ChatSession
@@ -88,6 +256,8 @@ export class AgentServer {
     lastSliceBySession = new Map();
     /** Lazy disk reader for cold wakeup rehydrate when this process lacks a slice. */
     diskSessionReader = null;
+    /** Sessions dir for diskSessionReader; undefined → default sessions root. */
+    sessionDiskRoot;
     /**
      * Monotonic config-reload version, bumped per reloadSettings request so each
      * Engine.refreshRuntimeConfig can drop out-of-order (stale) deliveries (Q5).
@@ -129,12 +299,40 @@ export class AgentServer {
      */
     bgAgentBusUnsubscribe = null;
     wakeupsInFlight = new Set();
+    /**
+     * Effective session manager for the connection this server serves. Without
+     * a resolveIdentity hook this is exactly the host-supplied manager —
+     * today's single-manager behavior, byte-for-byte. With the hook, requests
+     * route through a lazily-created per-identity manager, so the same
+     * sessionId under two identities resolves to two isolated ChatSessions and
+     * a connection can only list/stream sessions of its own identity.
+     */
+    get chatManager() {
+        if (!this.baseChatManager || !this.resolveIdentity)
+            return this.baseChatManager;
+        const identity = this.resolveIdentity({ connectionId: this.connectionId });
+        if (identity === this.baseChatManager.identity)
+            return this.baseChatManager;
+        let manager = this.identityManagers.get(identity);
+        if (!manager) {
+            // forIdentity validates the identity as a safe path segment and throws
+            // on garbage — the request that triggered routing then fails closed.
+            manager = this.baseChatManager.forIdentity(identity);
+            this.identityManagers.set(identity, manager);
+        }
+        return manager;
+    }
     constructor(options) {
-        this.chatManager = options.chatManager ?? null;
+        this.baseChatManager = options.chatManager ?? null;
+        this.resolveIdentity = options.resolveIdentity ?? null;
+        this.sessionDiskRoot = options.sessionDiskRoot;
         this.legacyEngine = options.engine ?? null;
         this.settingsReader = options.settingsReader ?? null;
         this.readActiveGoalFromDisk = options.readActiveGoalFromDisk ?? null;
+        this.updateActiveGoalOnDisk = options.updateActiveGoalOnDisk ?? null;
+        this.clearActiveGoalOnDisk = options.clearActiveGoalOnDisk ?? null;
         this.workspaceBridgeEnabled = options.workspaceBridge === true;
+        this.panelBridgeEnabled = options.panelBridge === true;
         this.connectionId = options.connectionId ?? "legacy-agent-server";
         this.strictApprovalRouting = options.connectionId !== undefined;
         this.approvalRouter = options.approvalRouter ?? getApprovalRouter();
@@ -142,10 +340,45 @@ export class AgentServer {
             this.approvalRouter.deregister(this.connectionId, "legacy approval host replaced");
         }
         getInteractiveApprovalBackend().clearPromptFn();
-        if (!this.chatManager && !this.legacyEngine) {
+        if (!this.baseChatManager && !this.legacyEngine) {
             throw new Error("AgentServer: either chatManager or engine must be supplied");
         }
         this.transport = options.transport;
+        // Protocol lifecycle observers. Each configured extension module may
+        // attach one; the server calls them at every lifecycle hook point and
+        // isolates per-observer failures. Core default-loads the pet extension
+        // until the pet domain moves out of core (see AgentServerOptions).
+        this.extensionModules = options.extensionModules ?? [];
+        this.hiddenSessionKinds = [
+            ...new Set(this.extensionModules.flatMap((module) => module.hiddenSessionKinds ?? [])),
+        ];
+        const observerHost = {
+            getLiveSessionSnapshot: () => this.chatManager?.getLiveSessionSnapshot().sessions ?? [],
+            projectionGeneration: () => this.workerGeneration(),
+            getSessionKind: (sessionId) => {
+                const session = this.chatManager?.get(sessionId);
+                if (!session)
+                    return undefined;
+                return session.engine
+                    .getSessionManager?.()
+                    .readSessionKind?.(sessionId);
+            },
+            isTransportDisconnected: () => this.disconnected,
+            notify: (method, params) => this.notify(method, params),
+            registerQuery: (type, handler) => {
+                this.protocolQueryHandlers.set(type, handler);
+            },
+        };
+        for (const module of this.extensionModules) {
+            if (!module.createProtocolObserver)
+                continue;
+            try {
+                this.protocolObservers.push(module.createProtocolObserver(observerHost));
+            }
+            catch (err) {
+                logger.warn(`protocol observer init failed for extension ${module.id}: ${err.message}`);
+            }
+        }
         // Wire up incoming messages
         this.transport.onMessage((msg) => {
             if (isRequest(msg)) {
@@ -177,8 +410,11 @@ export class AgentServer {
         // polls (background-jobs.ts). The bus now guarantees a real sessionId
         // (no more legacy-bucket coercion to ""), so we forward whatever sid it
         // hands us.
-        this.bgAgentBusUnsubscribe = agentNotificationBus.subscribe((sessionId, event) => {
-            this.notify(Methods.StreamEvent, { sessionId, event });
+        this.bgAgentBusUnsubscribe = agentNotificationBus.subscribe((envelope) => {
+            const sessionId = envelope.to.sessionId;
+            const event = notificationEnvelopeToLegacyStreamEvent(envelope);
+            if (event)
+                this.notify(Methods.StreamEvent, { sessionId, event });
             // Background work that finishes while the session is IDLE (a
             // run_in_background Bash like a download, a background sub-agent, or a
             // video poll — the engine no longer parks on any of them) would otherwise
@@ -190,7 +426,8 @@ export class AgentServer {
             // (trigger B) drains it at end-of-turn instead. A never-exiting dev server
             // emits no completion, so it never wakes anything (no task/service
             // classification needed).
-            this.maybeWakeIdleSession(sessionId);
+            if (envelope.kind === "result")
+                this.maybeWakeIdleSession(sessionId);
         });
         // Notify client we're ready
         this.notify(Methods.Status, { status: "ready" });
@@ -339,8 +576,8 @@ export class AgentServer {
         if (cached)
             return { ...cached };
         if (!this.diskSessionReader)
-            this.diskSessionReader = new SessionManager();
-        const cwd = this.diskSessionReader.readCwd(sessionId);
+            this.diskSessionReader = new SessionManager(this.sessionDiskRoot);
+        const cwd = this.diskSessionReader.readSessionMainRoot(sessionId);
         if (!cwd)
             return null;
         return {
@@ -357,9 +594,88 @@ export class AgentServer {
         session.engine.setAskUser((question, opts) => this.requestAskUserForSession(session, sid, question, opts));
         session.engine.setBrowserBridge(this.makeBrowserBridge(session, sid));
         session.engine.setInjectCredential((credentialId, credentialScope) => this.requestCredentialInjectForSession(session, sid, credentialId, credentialScope));
+        session.engine.setSessionMessageRouter((input) => this.routeSessionMessage(input));
         if (this.workspaceBridgeEnabled && typeof session.engine.setWorkspaceBridge === "function") {
             session.engine.setWorkspaceBridge(this.makeWorkspaceBridge(session, sid));
         }
+        if (this.panelBridgeEnabled && typeof session.engine.setPanelBridge === "function") {
+            session.engine.setPanelBridge(this.makePanelBridge(session, sid));
+        }
+    }
+    /** Queue a model-sent message as an ordinary user turn in another Session. */
+    async routeSessionMessage(input) {
+        const manager = this.chatManager;
+        if (!manager)
+            throw new Error("cross-Session messaging requires a multi-session host");
+        const targetId = input.target.sessionId;
+        if (manager.isUnavailable(targetId)) {
+            throw new Error(`target Session is closing or closed: ${targetId}`);
+        }
+        const sourceSlice = this.lastSliceBySession.get(input.sourceSessionId);
+        const targetSlice = {
+            cwd: input.target.workspaceRoot,
+            projectTrusted: sourceSlice?.projectTrusted ?? false,
+        };
+        const targetAlreadyExists = manager.sessionExistsOnDisk(targetId, targetSlice);
+        const targetSession = await manager.getOrCreate(targetId, targetSlice);
+        const approvalRegistration = this.approvalRouter.register(targetId, this.connectionId);
+        if (!approvalRegistration.ok) {
+            throw new Error(`target Session ${targetId} is owned by another connection`);
+        }
+        this.rememberSessionSlice(targetId, targetSlice);
+        this.observeSessionAttached(targetId, targetSession.lastActivityAt);
+        this.wireInteractiveSession(targetSession, targetId);
+        const userMessageEvent = {
+            type: "session_user_message",
+            text: input.message,
+        };
+        this.observeSessionStream(targetId, userMessageEvent);
+        this.notify(Methods.StreamEvent, { sessionId: targetId, event: userMessageEvent });
+        const run = targetSession.enqueueTurn(input.message, {
+            cwd: input.target.workspaceRoot,
+            // A planned Session needs its renderer-selected initial profile. Once a
+            // Session exists, omitting this field makes Engine use the target's own
+            // persisted binding, so a stale source catalog cannot switch it back.
+            workspaceProfile: targetAlreadyExists ? undefined : input.target.workspaceProfile,
+            sessionMessageTargets: input.catalog,
+            onStream: (event) => {
+                this.observeSessionStream(targetId, event);
+                this.notify(Methods.StreamEvent, { sessionId: targetId, event });
+            },
+            approvalRouter: this.approvalRouter,
+        });
+        // The turn itself must NOT block the sender — a member's work can take
+        // minutes and the lead has more to dispatch. But a turn that fails to *start*
+        // (most often: the target's digital human is not installed, so run-setup
+        // throws "Workspace profile ... is unavailable") used to be reported only to
+        // the log while SendMessageToSession still answered "has queued the turn".
+        // A real lead then waited two hours and re-sent, never learning the reason.
+        // So: surface an immediate failure to the caller, keep a slow turn detached.
+        let startupError;
+        const tracked = run
+            .then(() => this.maybeWakeIdleSession(targetId))
+            .catch((error) => {
+            startupError = error;
+            logger.warn("session_message.turn_failed", {
+                sourceSessionId: input.sourceSessionId,
+                targetSessionId: targetId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            this.notify(Methods.StreamEvent, {
+                sessionId: targetId,
+                event: {
+                    type: "error",
+                    error: error instanceof Error ? error.message : "cross-Session message failed",
+                },
+            });
+        });
+        // One macrotask is enough for a synchronous-throw path to settle; anything
+        // still running by then is genuine work and stays detached.
+        await Promise.race([tracked, new Promise((resolve) => setTimeout(resolve, 0))]);
+        if (startupError) {
+            throw startupError instanceof Error ? startupError : new Error(String(startupError));
+        }
+        void tracked;
     }
     // ─── Request Dispatch ───────────────────────────────────────────
     async handleRequest(req) {
@@ -368,7 +684,7 @@ export class AgentServer {
                 await this.handleRun(req);
                 break;
             case Methods.ForkSession:
-                this.handleForkSession(req);
+                await this.handleForkSession(req);
                 break;
             case Methods.Approve:
                 this.handleApprove(req);
@@ -397,9 +713,18 @@ export class AgentServer {
             case Methods.ReleaseWorkspace:
                 this.handleReleaseWorkspace(req);
                 break;
+            case Methods.SetWorkspace:
+                this.handleSetWorkspace(req);
+                break;
             case Methods.GoalExtend:
                 this.handleGoalExtend(req);
                 break;
+            case Methods.GoalUpdate:
+                await this.handleGoalUpdate(req);
+                break;
+            case Methods.GoalDelete:
+                this.handleGoalClear(req, true);
+                break;
             case Methods.GoalClear:
                 this.handleGoalClear(req);
                 break;
@@ -412,31 +737,210 @@ export class AgentServer {
             case Methods.BackgroundWork:
                 this.handleBackgroundWork(req);
                 break;
+            case Methods.PluginCommandsList:
+                this.handlePluginCommandsList(req);
+                break;
+            case Methods.PluginCommandExpand:
+                this.handlePluginCommandExpand(req);
+                break;
+            // Compat channel: the wire method name is retained, but the handler is
+            // whatever extension registered it (the pet extension by default).
+            case Methods.GetPetProjectionSnapshot:
+                await this.handleExtensionProtocolMethod(req);
+                break;
             default:
                 this.transport.send(createErrorResponse(req.id, ErrorCodes.MethodNotFound, `Unknown method: ${req.method}`));
         }
     }
+    pluginCommandContext(cwd) {
+        if (typeof cwd !== "string" ||
+            cwd.trim().length === 0 ||
+            cwd.length > 4_096 ||
+            cwd.includes("\0")) {
+            return { error: "cwd must be a non-empty string of at most 4096 characters" };
+        }
+        const disabledPluginNames = new Set(computeEffectiveDisabledLists(new SettingsManager(cwd, "full"), cwd).disabledPlugins);
+        return { cwd, disabledPluginNames };
+    }
+    handlePluginCommandsList(req) {
+        const params = (req.params ?? {});
+        const context = this.pluginCommandContext(params.cwd);
+        if ("error" in context) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, context.error));
+            return;
+        }
+        try {
+            this.transport.send(createResponse(req.id, {
+                commands: describePluginCommands(scanPluginCommands(), context.disabledPluginNames),
+            }));
+        }
+        catch (error) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, error.message));
+        }
+    }
+    handlePluginCommandExpand(req) {
+        const params = (req.params ?? {});
+        const context = this.pluginCommandContext(params.cwd);
+        if ("error" in context) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, context.error));
+            return;
+        }
+        if (typeof params.name !== "string" ||
+            params.name.length === 0 ||
+            params.name.length > 512 ||
+            params.name.includes("\0")) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "name must be a non-empty string of at most 512 characters"));
+            return;
+        }
+        const rawArguments = params.rawArguments ?? "";
+        if (typeof rawArguments !== "string" ||
+            rawArguments.length > MAX_PLUGIN_COMMAND_ARGUMENT_CHARS) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, `rawArguments must be a string of at most ${MAX_PLUGIN_COMMAND_ARGUMENT_CHARS} characters`));
+            return;
+        }
+        const command = scanPluginCommands().find((candidate) => candidate.name === params.name && !context.disabledPluginNames.has(candidate.pluginName));
+        if (!command) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, `plugin command is unavailable: ${params.name}`));
+            return;
+        }
+        try {
+            this.transport.send(createResponse(req.id, {
+                prompt: expandPluginCommandBody(command.body, rawArguments),
+            }));
+        }
+        catch (error) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, error.message));
+        }
+    }
+    /** Route a protocol method to its extension-registered handler, if any. */
+    async handleExtensionProtocolMethod(req) {
+        const handler = this.protocolQueryHandlers.get(req.method);
+        if (!handler) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.MethodNotFound, `Unknown method: ${req.method}`));
+            return;
+        }
+        try {
+            const data = await handler((req.params ?? {}));
+            this.transport.send(createResponse(req.id, data));
+        }
+        catch (err) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, err.message));
+        }
+    }
+    // ─── Protocol observers ─────────────────────────────────────────
+    // Domain-agnostic lifecycle dispatch. Observers run in registration order
+    // and a throwing observer never breaks the protocol path or its peers.
+    forEachObserver(hook, fn) {
+        for (const observer of this.protocolObservers) {
+            try {
+                fn(observer);
+            }
+            catch (err) {
+                logger.warn(`protocol observer ${hook} hook failed: ${err.message}`);
+            }
+        }
+    }
+    observeSessionAttached(sessionId, lastActivityAt) {
+        this.forEachObserver("onSessionAttached", (observer) => observer.onSessionAttached?.(sessionId, lastActivityAt));
+    }
+    observeSessionStream(sessionId, event) {
+        this.forEachObserver("onSessionStream", (observer) => observer.onSessionStream?.(sessionId, event));
+    }
+    observeRunBoundary(sessionId, phase) {
+        this.forEachObserver("onRunBoundary", (observer) => observer.onRunBoundary?.(sessionId, phase));
+    }
+    /** Observers may replace approval metadata (e.g. surfaceable overrides). */
+    observeApprovalCreated(metadata) {
+        for (const observer of this.protocolObservers) {
+            try {
+                const next = observer.onApprovalCreated?.(metadata);
+                if (next)
+                    metadata = next;
+            }
+            catch (err) {
+                logger.warn(`protocol observer onApprovalCreated hook failed: ${err.message}`);
+            }
+        }
+        return metadata;
+    }
+    observeApprovalTransition(metadata, status) {
+        this.forEachObserver("onApprovalTransition", (observer) => observer.onApprovalTransition?.(metadata, status));
+    }
+    observeSessionClosed(sessionId) {
+        this.forEachObserver("onSessionClosed", (observer) => observer.onSessionClosed?.(sessionId));
+    }
+    observeServerClose() {
+        this.forEachObserver("onServerClose", (observer) => observer.onServerClose?.());
+    }
+    /** Generic run-param shape checks plus each extension's domain validation. */
+    validateRunInput(params) {
+        const generic = runInputError(params);
+        if (generic)
+            return generic;
+        for (const module of this.extensionModules) {
+            if (!module.validateRunParams)
+                continue;
+            const error = module.validateRunParams(params);
+            if (error)
+                return error;
+        }
+        return null;
+    }
     // ─── Run ────────────────────────────────────────────────────────
-    handleForkSession(req) {
+    async handleForkSession(req) {
         const params = req.params ?? {};
         const sourceSessionId = typeof params.sourceSessionId === "string" ? params.sourceSessionId : "";
         const targetSessionId = typeof params.targetSessionId === "string" ? params.targetSessionId : undefined;
         const throughEventId = typeof params.throughEventId === "string" ? params.throughEventId : undefined;
-        if (!sourceSessionId || params.mode !== "full") {
-            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "forkSession requires sourceSessionId and mode=full"));
+        const fromEventId = typeof params.fromEventId === "string" ? params.fromEventId : undefined;
+        const toEventId = typeof params.toEventId === "string" ? params.toEventId : undefined;
+        const mode = params.mode;
+        const isSideFork = params.forkKind === "side";
+        if (!sourceSessionId || (mode !== "full" && mode !== "summary")) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "forkSession requires sourceSessionId and mode=full|summary"));
             return;
         }
-        if (params.targetSessionId !== undefined && typeof params.targetSessionId !== "string") {
-            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "targetSessionId must be a string"));
+        if (params.targetSessionId !== undefined &&
+            (typeof params.targetSessionId !== "string" || params.targetSessionId.length === 0)) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "targetSessionId must be a non-empty string"));
             return;
         }
         if (params.throughEventId !== undefined && typeof params.throughEventId !== "string") {
             this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "throughEventId must be a string"));
             return;
         }
+        if (mode === "summary" && (!fromEventId || !toEventId)) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "summary fork requires fromEventId and toEventId"));
+            return;
+        }
+        if (mode === "summary" &&
+            (params.throughEventId !== undefined ||
+                params.forkKind !== undefined ||
+                params.quickChatClaimId !== undefined)) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "summary fork only accepts fromEventId/toEventId range fields"));
+            return;
+        }
+        if (mode === "full" && (params.fromEventId !== undefined || params.toEventId !== undefined)) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "full fork does not accept summary range fields"));
+            return;
+        }
+        if (mode === "full" &&
+            params.quickChatClaimId !== undefined &&
+            typeof params.quickChatClaimId !== "string") {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "quickChatClaimId must be a string"));
+            return;
+        }
+        if (params.forkKind !== undefined && !isSideFork) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "forkKind must be side when present"));
+            return;
+        }
+        if (isSideFork && throughEventId !== undefined) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "side fork uses the last completed turn and cannot specify throughEventId"));
+            return;
+        }
         try {
             assertSafeSessionId(sourceSessionId);
-            if (targetSessionId)
+            if (targetSessionId !== undefined)
                 assertSafeSessionId(targetSessionId);
         }
         catch (err) {
@@ -446,12 +950,30 @@ export class AgentServer {
         let source;
         try {
             source = this.chatManager?.get(sourceSessionId);
+            if (!source && this.chatManager) {
+                if (this.chatManager.isUnavailable(sourceSessionId)) {
+                    this.transport.send(createErrorResponse(req.id, ErrorCodes.SessionClosed, `Session is closing or closed: ${sourceSessionId}`));
+                    return;
+                }
+                source =
+                    (await this.chatManager.getOrCreatePersisted(sourceSessionId, this.lastSliceBySession.get(sourceSessionId), mode === "summary")) ?? undefined;
+                if (source) {
+                    this.rememberSessionSlice(sourceSessionId, {
+                        ...this.lastSliceBySession.get(sourceSessionId),
+                        cwd: source.engine.getConfig().cwd,
+                    });
+                }
+            }
         }
         catch (err) {
             this.transport.send(createErrorResponse(req.id, ErrorCodes.Overloaded, err instanceof Error ? err.message : String(err)));
             return;
         }
-        const engine = source?.engine ?? this.legacyEngine ?? this.anyEngine();
+        if (!isSideFork && source && (source.isBusy() || source.queueDepth() > 0)) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.Overloaded, "source session is still producing or has queued turns"));
+            return;
+        }
+        const engine = source?.engine ?? this.legacyEngine;
         if (!engine || !engine.sessionExistsOnDisk(sourceSessionId)) {
             this.transport.send(createErrorResponse(req.id, ErrorCodes.SessionNotFound, `Session not found: ${sourceSessionId}`));
             return;
@@ -461,7 +983,56 @@ export class AgentServer {
             return;
         }
         try {
-            const result = engine.forkSession(sourceSessionId, { targetSessionId, throughEventId });
+            if (mode === "summary") {
+                const sourceRange = { fromEventId: fromEventId, toEventId: toEventId };
+                const packageAndPublish = async (signal) => {
+                    const selected = engine.selectContextPackage(sourceSessionId, sourceRange);
+                    const packaged = await engine.summarizeContextPackage(selected.messages, signal, sourceSessionId);
+                    const result = engine.createSummaryFork(sourceSessionId, {
+                        targetSessionId,
+                        ...sourceRange,
+                        summary: packaged.summary,
+                        sourceEventCount: selected.sourceEventCount,
+                        estimatedTokens: packaged.estimatedTokens,
+                    });
+                    return { selected, packaged, result };
+                };
+                let packagedResult;
+                if (source) {
+                    packagedResult = await source.runExclusive(packageAndPublish);
+                }
+                else {
+                    if (this.running)
+                        throw new Error("source session is still producing or has queued turns");
+                    this.running = true;
+                    this.abortController = new AbortController();
+                    try {
+                        packagedResult = await packageAndPublish(this.abortController.signal);
+                    }
+                    finally {
+                        this.abortController = null;
+                        this.running = false;
+                    }
+                }
+                const { packaged, result } = packagedResult;
+                const workspace = result.bundle.state.workspace ?? {
+                    root: result.bundle.state.cwd,
+                    kind: "main",
+                };
+                this.transport.send(createResponse(req.id, {
+                    sessionId: result.bundle.state.sessionId,
+                    mode: "summary",
+                    summary: packaged.summary,
+                    sourceRange,
+                    estimatedTokens: packaged.estimatedTokens,
+                    forkedFrom: result.lineage,
+                    workspace,
+                }));
+                return;
+            }
+            const result = engine.forkSession(sourceSessionId, isSideFork
+                ? { targetSessionId, snapshotMode: "completed", ephemeral: true }
+                : { targetSessionId, throughEventId });
             const workspace = result.bundle.state.workspace ?? {
                 root: result.bundle.state.cwd,
                 kind: "main",
@@ -478,9 +1049,11 @@ export class AgentServer {
             const message = err instanceof Error ? err.message : String(err);
             const code = /not found/i.test(message)
                 ? ErrorCodes.SessionNotFound
-                : /already exists|invalid|cursor|metadata|unfinished|orphaned|unsupported|malformed/i.test(message)
-                    ? ErrorCodes.InvalidParams
-                    : ErrorCodes.InternalError;
+                : /still producing|queued turns|busy/i.test(message)
+                    ? ErrorCodes.Overloaded
+                    : /already exists|invalid|cursor|metadata|unfinished|orphaned|unsupported|malformed/i.test(message)
+                        ? ErrorCodes.InvalidParams
+                        : ErrorCodes.InternalError;
             this.transport.send(createErrorResponse(req.id, code, message));
         }
     }
@@ -499,7 +1072,7 @@ export class AgentServer {
             this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "sessionId is required"));
             return;
         }
-        const inputError = runInputError(params);
+        const inputError = this.validateRunInput(params);
         if (inputError) {
             this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, inputError));
             return;
@@ -512,7 +1085,7 @@ export class AgentServer {
                 : undefined,
         };
         if (params.requireExisting === true && !cm.get(params.sessionId)) {
-            let existsOnDisk = false;
+            let existsOnDisk;
             try {
                 existsOnDisk = cm.sessionExistsOnDisk(params.sessionId, sessionConfig);
             }
@@ -536,6 +1109,7 @@ export class AgentServer {
             return;
         }
         const sid = params.sessionId;
+        this.observeSessionAttached(sid, session.lastActivityAt);
         const approvalRegistration = this.approvalRouter.register(sid, this.connectionId);
         if (!approvalRegistration.ok) {
             this.transport.send(createErrorResponse(req.id, ErrorCodes.Overloaded, `Session ${sid} is owned by another connection`));
@@ -560,27 +1134,56 @@ export class AgentServer {
         // these host callbacks must be installed after every create/recreate.
         this.wireInteractiveSession(session, sid);
         try {
+            const displayText = typeof params.displayText === "string" ? params.displayText.trim() : "";
+            if (displayText) {
+                const userMessageEvent = {
+                    type: "session_user_message",
+                    text: displayText,
+                    ...(typeof params.clientMessageId === "string"
+                        ? { clientMessageId: params.clientMessageId }
+                        : {}),
+                };
+                this.observeSessionStream(sid, userMessageEvent);
+                this.notify(Methods.StreamEvent, { sessionId: sid, event: userMessageEvent });
+            }
             const run = session.enqueueTurn(params.task, {
                 cwd: params.cwd,
+                displayText: displayText || undefined,
+                injected: params.injected === true,
                 attachments: Array.isArray(params.attachments) ? params.attachments : undefined,
                 goal: typeof params.goal === "string" ||
                     (params.goal != null && typeof params.goal === "object")
                     ? params.goal
                     : undefined,
-                onStream: (event) => this.notify(Methods.StreamEvent, { sessionId: sid, event }),
+                onStream: (event) => {
+                    this.observeSessionStream(sid, event);
+                    this.notify(Methods.StreamEvent, { sessionId: sid, event });
+                },
                 clientMessageId: typeof params.clientMessageId === "string" ? params.clientMessageId : undefined,
                 permissionMode: params.permissionMode,
                 planMode: params.planMode,
+                behaviorMode: params.behaviorMode,
+                profileParams: params.profileParams,
+                workspaceProfile: params.workspaceProfile,
+                sessionBrief: params.sessionBrief,
+                sessionMessageTargets: params.sessionMessageTargets,
+                petRuntimeContext: params.petRuntimeContext,
+                petWorkspaces: params.petWorkspaces,
+                kind: params.kind,
                 approvalRouter: this.approvalRouter,
             });
             this.notify(Methods.RunAccepted, { requestId: req.id, sessionId: sid });
+            this.observeRunBoundary(sid, "start");
             const result = await run;
+            this.observeRunBoundary(sid, "end");
             const runResult = {
                 text: result.text,
                 reason: result.reason,
                 sessionId: result.sessionId ?? sid,
                 turnCount: result.turnCount,
                 usage: result.usage,
+                ...(result.extensions ? { extensions: result.extensions } : {}),
+                petWorkDelegation: result.petWorkDelegation,
             };
             this.transport.send(createResponse(req.id, runResult));
             // Run-boundary re-check (trigger B): the session is idle now. If a
@@ -591,6 +1194,7 @@ export class AgentServer {
             this.maybeWakeIdleSession(sid);
         }
         catch (err) {
+            this.observeRunBoundary(sid, "error");
             this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, err.message));
             // Even on a failed run the session goes idle — re-check so a background
             // completion that landed during the failed run isn't orphaned.
@@ -603,7 +1207,7 @@ export class AgentServer {
             return;
         }
         const params = (req.params ?? {});
-        const inputError = runInputError(params);
+        const inputError = this.validateRunInput(params);
         if (inputError) {
             this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, inputError));
             return;
@@ -656,6 +1260,16 @@ export class AgentServer {
         // `signal.aborted` below it's already gone.
         const runController = this.abortController;
         try {
+            const displayText = typeof params.displayText === "string" ? params.displayText.trim() : "";
+            if (displayText) {
+                streamToClient({
+                    type: "session_user_message",
+                    text: displayText,
+                    ...(typeof params.clientMessageId === "string"
+                        ? { clientMessageId: params.clientMessageId }
+                        : {}),
+                });
+            }
             this.notify(Methods.RunAccepted, {
                 requestId: req.id,
                 sessionId: params.sessionId ?? "",
@@ -663,6 +1277,8 @@ export class AgentServer {
             const result = await this.legacyEngine.run(params.task, {
                 cwd: params.cwd,
                 sessionId: params.sessionId,
+                displayText: displayText || undefined,
+                injected: params.injected === true,
                 signal: runController.signal,
                 onStream: streamToClient,
                 clientMessageId: typeof params.clientMessageId === "string" ? params.clientMessageId : undefined,
@@ -671,6 +1287,16 @@ export class AgentServer {
                     (params.goal != null && typeof params.goal === "object")
                     ? params.goal
                     : undefined,
+                permissionMode: params.permissionMode,
+                planMode: params.planMode,
+                behaviorMode: params.behaviorMode,
+                profileParams: params.profileParams,
+                workspaceProfile: params.workspaceProfile,
+                sessionBrief: params.sessionBrief,
+                sessionMessageTargets: params.sessionMessageTargets,
+                petRuntimeContext: params.petRuntimeContext,
+                petWorkspaces: params.petWorkspaces,
+                kind: params.kind,
             });
             const runResult = {
                 text: result.text,
@@ -678,6 +1304,8 @@ export class AgentServer {
                 sessionId: result.sessionId,
                 turnCount: result.turnCount,
                 usage: result.usage,
+                ...(result.extensions ? { extensions: result.extensions } : {}),
+                petWorkDelegation: result.petWorkDelegation,
             };
             this.transport.send(createResponse(req.id, runResult));
         }
@@ -735,18 +1363,19 @@ export class AgentServer {
                 this.transport.send(createErrorResponse(req.id, ErrorCodes.SessionClosed, `No such session: ${params.sessionId}`));
                 return;
             }
-            const resolve = s.pendingApprovals.get(params.requestId);
-            if (!resolve) {
+            const entry = s.pendingApprovals.get(params.requestId);
+            if (!entry) {
                 this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, `No pending approval for session ${params.sessionId}: ${params.requestId}`));
                 return;
             }
             s.pendingApprovals.delete(params.requestId);
+            this.observeApprovalTransition(entry.metadata, "resolved");
             this.pendingApprovalTargets.delete(params.requestId);
             // Cancel the pending timeout for requests that arm one (browser actions,
             // credential injection, and tool approvals). AskUserQuestion does not use
             // a timeout; this is harmless for those request ids.
             this.clearApprovalTimer(params.requestId);
-            resolve(params.decision);
+            entry.resolve(params.decision);
             this.transport.send(createResponse(req.id, { ok: true }));
             return;
         }
@@ -838,37 +1467,260 @@ export class AgentServer {
         }
         this.transport.send(createResponse(req.id, { ok: true, limits: result }));
     }
+    /** Reject destructive Goal controls owned by a different TCP connection. */
+    authorizeGoalControl(req, sessionId) {
+        if (!this.strictApprovalRouting)
+            return true;
+        const owner = this.approvalRouter.current(sessionId);
+        if (!owner || owner.connectionId === this.connectionId)
+            return true;
+        this.transport.send(createErrorResponse(req.id, ErrorCodes.Overloaded, `Session ${sessionId} is owned by another connection`));
+        return false;
+    }
+    /** Start a fully rebuilt Goal run for an idle or goal-less in-flight session. */
+    async queueGoalResumeTurn(sessionId, goal, existing) {
+        if (!this.chatManager)
+            return null;
+        let session = existing;
+        if (!session) {
+            // Let ChatSessionManager probe through its configured Engine factory so
+            // custom sessionStorageDir roots stay aligned with the host. The generic
+            // background-wakeup helper's default SessionManager probe is not safe for
+            // this cold-resume path.
+            session =
+                (await this.chatManager.getOrCreatePersisted(sessionId, {
+                    projectTrusted: false,
+                })) ?? undefined;
+            if (!session)
+                return null;
+            this.wireInteractiveSession(session, sessionId);
+        }
+        if (session.engine.isHeadless())
+            return null;
+        return {
+            completion: session.enqueueGoalResumeTurn(goal, {
+                onStream: (event) => this.notify(Methods.StreamEvent, { sessionId, event }),
+                approvalRouter: this.approvalRouter,
+            }),
+        };
+    }
+    reconcileFailedGoalResume(sessionId, goal, claimedOwner, error) {
+        const patch = {
+            paused: true,
+            expectedGoalId: goal.goalId,
+            expectedRevision: goal.revision,
+        };
+        const live = this.chatManager?.get(sessionId);
+        const rolledBack = live
+            ? live.updateGoal(patch)
+            : this.updateActiveGoalOnDisk?.(sessionId, patch);
+        const authoritative = rolledBack ?? live?.getGoal() ?? this.readActiveGoalFromDisk?.(sessionId);
+        if (authoritative) {
+            this.notify(Methods.StreamEvent, {
+                sessionId,
+                event: {
+                    type: "goal_updated",
+                    goalId: authoritative.goalId,
+                    revision: authoritative.revision,
+                    objective: authoritative.objective,
+                    paused: authoritative.paused === true,
+                },
+            });
+        }
+        if (rolledBack && claimedOwner && this.approvalRouter.matches(claimedOwner)) {
+            this.approvalRouter.release(sessionId, this.connectionId, "goal resume turn was not queued");
+        }
+        logger.warn("goal.resume_turn_not_queued", {
+            sessionId,
+            goalId: goal.goalId,
+            revision: goal.revision,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        this.notify(Methods.StreamEvent, {
+            sessionId,
+            event: {
+                type: "error",
+                error: rolledBack
+                    ? "Goal resume could not start; the Goal was paused again"
+                    : "Goal resume could not start; Goal state changed before rollback",
+            },
+        });
+    }
+    /** Edit or pause/resume a persisted goal without replacing its identity. */
+    async handleGoalUpdate(req) {
+        const params = (req.params ?? {});
+        if (typeof params.sessionId !== "string" || !params.sessionId) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "sessionId is required"));
+            return;
+        }
+        if (params.objective === undefined && params.paused === undefined) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "objective or paused is required"));
+            return;
+        }
+        if (params.objective !== undefined && typeof params.objective !== "string") {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "objective must be a string"));
+            return;
+        }
+        if (params.objective !== undefined && !params.objective.trim()) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "objective must not be blank"));
+            return;
+        }
+        if (params.paused !== undefined && typeof params.paused !== "boolean") {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "paused must be boolean"));
+            return;
+        }
+        if (typeof params.expectedGoalId !== "string" || !params.expectedGoalId) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "expectedGoalId is required and must be a non-empty string"));
+            return;
+        }
+        if (typeof params.expectedRevision !== "number" ||
+            !Number.isInteger(params.expectedRevision) ||
+            params.expectedRevision < 1) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "expectedRevision is required and must be a positive integer"));
+            return;
+        }
+        const patch = {
+            objective: params.objective,
+            paused: params.paused,
+            expectedGoalId: params.expectedGoalId,
+            expectedRevision: params.expectedRevision,
+        };
+        const session = this.chatManager?.get(params.sessionId);
+        const beforeGoal = session?.getGoal?.() ??
+            this.legacyEngine?.getGoal(params.sessionId) ??
+            this.readActiveGoalFromDisk?.(params.sessionId);
+        const resumeInPlace = session?.canResumeGoalInPlace?.() === true;
+        // `paused:false` is also an explicit kick for an unpaused-but-idle Goal
+        // left behind by ESC, a model failure, or worker restart. A live Goal run
+        // consumes the update in place and must not enqueue a duplicate turn.
+        const driveRequested = !!beforeGoal && params.paused === false && !resumeInPlace;
+        if (!this.authorizeGoalControl(req, params.sessionId))
+            return;
+        if (driveRequested && !this.chatManager) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "Goal resume requires a multi-session host that can schedule a continuation turn"));
+            return;
+        }
+        let claimedResumeOwner = null;
+        if (this.strictApprovalRouting &&
+            driveRequested &&
+            !this.approvalRouter.current(params.sessionId)) {
+            const registration = this.approvalRouter.register(params.sessionId, this.connectionId);
+            if (!registration.ok) {
+                this.transport.send(createErrorResponse(req.id, ErrorCodes.Overloaded, `Session ${params.sessionId} is owned by another connection`));
+                return;
+            }
+            claimedResumeOwner = registration.target;
+        }
+        const goal = session
+            ? session.updateGoal(patch)
+            : this.legacyEngine
+                ? this.legacyEngine.updateGoal(params.sessionId, patch)
+                : this.updateActiveGoalOnDisk?.(params.sessionId, patch);
+        if (!goal) {
+            if (claimedResumeOwner && this.approvalRouter.matches(claimedResumeOwner)) {
+                this.approvalRouter.release(params.sessionId, this.connectionId, "goal resume CAS did not apply");
+            }
+            // A missing/stale goal is an ordinary optimistic-concurrency miss, not a
+            // malformed request. Keep it in the result channel so Desktop, TUI and
+            // the no-worker fallback share one contract.
+            this.transport.send(createResponse(req.id, { ok: true, updated: false }));
+            return;
+        }
+        this.notify(Methods.StreamEvent, {
+            sessionId: params.sessionId,
+            event: {
+                type: "goal_updated",
+                ...(goal.goalId ? { goalId: goal.goalId } : {}),
+                ...(goal.revision ? { revision: goal.revision } : {}),
+                objective: goal.objective,
+                paused: goal.paused === true,
+            },
+        });
+        this.transport.send(createResponse(req.id, {
+            ok: true,
+            updated: true,
+            goal: goal.objective,
+            ...(goal.goalId ? { goalId: goal.goalId } : {}),
+            ...(goal.revision ? { revision: goal.revision } : {}),
+            paused: goal.paused === true,
+        }));
+        if (driveRequested) {
+            void this.queueGoalResumeTurn(params.sessionId, goal, session)
+                .then((ticket) => {
+                if (!ticket) {
+                    this.reconcileFailedGoalResume(params.sessionId, goal, claimedResumeOwner, "session is unavailable or headless");
+                    return;
+                }
+                void ticket.completion.catch((err) => {
+                    this.reconcileFailedGoalResume(params.sessionId, goal, claimedResumeOwner, err);
+                });
+            })
+                .catch((err) => {
+                this.reconcileFailedGoalResume(params.sessionId, goal, claimedResumeOwner, err);
+            });
+        }
+    }
     /**
      * Clear a session's persisted active goal (CC /goal clear). Routes to the
      * named session, falling back to the legacy single engine (mirrors
      * handleGoalExtend / handleCancel's dual path). Returns { ok, cleared }.
      */
-    handleGoalClear(req) {
+    handleGoalClear(req, deleteAlias = false) {
         const params = (req.params ?? {});
+        if (typeof params.sessionId !== "string" || !params.sessionId) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "sessionId is required"));
+            return;
+        }
+        if (deleteAlias &&
+            (typeof params.expectedGoalId !== "string" ||
+                !params.expectedGoalId ||
+                typeof params.expectedRevision !== "number" ||
+                !Number.isInteger(params.expectedRevision) ||
+                params.expectedRevision < 1)) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "goalDelete requires expectedGoalId and a positive expectedRevision"));
+            return;
+        }
+        if (!this.authorizeGoalControl(req, params.sessionId))
+            return;
+        const expected = deleteAlias
+            ? { goalId: params.expectedGoalId, revision: params.expectedRevision }
+            : undefined;
         const session = this.chatManager && typeof params.sessionId === "string"
             ? this.chatManager.get(params.sessionId)
             : undefined;
-        if (!session && !this.legacyEngine) {
+        if (!session && !this.legacyEngine && !this.clearActiveGoalOnDisk) {
             this.transport.send(createErrorResponse(req.id, ErrorCodes.SessionClosed, params.sessionId ? `No such session: ${params.sessionId}` : "sessionId is required"));
             return;
         }
+        const clearingGoal = session
+            ? session.getGoal?.()
+            : params.sessionId
+                ? (this.legacyEngine?.getGoal(params.sessionId) ??
+                    this.readActiveGoalFromDisk?.(params.sessionId))
+                : undefined;
         const cleared = session
-            ? session.clearGoal()
+            ? session.clearGoal(expected)
             : params.sessionId
-                ? (this.legacyEngine.clearGoal(params.sessionId) ?? false)
+                ? (this.legacyEngine?.clearGoal(params.sessionId, expected) ??
+                    this.clearActiveGoalOnDisk?.(params.sessionId, expected) ??
+                    false)
                 : false;
         if (cleared && typeof params.sessionId === "string" && params.sessionId.length > 0) {
             this.notify(Methods.StreamEvent, {
                 sessionId: params.sessionId,
-                event: { type: "goal_cleared" },
+                event: {
+                    type: "goal_cleared",
+                    ...(clearingGoal?.goalId ? { goalId: clearingGoal.goalId } : {}),
+                    ...(clearingGoal?.revision ? { revision: clearingGoal.revision } : {}),
+                },
             });
         }
-        this.transport.send(createResponse(req.id, { ok: true, cleared }));
+        this.transport.send(createResponse(req.id, deleteAlias ? { ok: true, deleted: cleared } : { ok: true, cleared }));
     }
     /**
      * Read a session's persisted active goal so the host can re-surface the goal
      * block + Cancel button on session load. A persistent goal lives only in
-     * state.activeGoal and is never replayed from the transcript, so a reloaded
+     * state.goalLifecycle and is never replayed from the transcript, so a reloaded
      * (or disk-rebuilt) session has no other way to learn it. Prefers a live
      * chatManager session, else falls through to a disk read (readActiveGoalFromDisk
      * in worker mode, or the legacy engine's disk read in single-engine mode) — the
@@ -897,7 +1749,13 @@ export class AgentServer {
             : (this.readActiveGoalFromDisk?.(params.sessionId) ??
                 this.legacyEngine?.getGoal(params.sessionId) ??
                 undefined);
-        this.transport.send(createResponse(req.id, { ok: true, goal: goal ? goal.objective : null }));
+        this.transport.send(createResponse(req.id, {
+            ok: true,
+            goal: goal ? goal.objective : null,
+            ...(goal?.goalId ? { goalId: goal.goalId } : {}),
+            ...(goal?.revision ? { revision: goal.revision } : {}),
+            paused: goal?.paused === true,
+        }));
     }
     /**
      * Query/control a session's background shells for the desktop UI panel (TODO
@@ -974,10 +1832,11 @@ export class AgentServer {
         if (this.chatManager) {
             const session = this.chatManager.get(params.sessionId);
             if (session) {
-                this.cancelSessionApprovals(session, "session closed");
+                this.cancelSessionApprovals(session, "session closed", "cancelled", "session_closed");
             }
             this.approvalRouter.release(params.sessionId, this.connectionId, "session closed");
             await this.chatManager.close(params.sessionId);
+            this.observeSessionClosed(params.sessionId);
         }
         // Explicit session teardown — reap that session's background shells
         // (design §6 "session 被显式删除 → killSession"). This is the RPC path
@@ -1012,6 +1871,33 @@ export class AgentServer {
         const workspace = engine?.releaseSessionWorkspace?.(params.sessionId) ?? null;
         this.transport.send(createResponse(req.id, { ok: true, workspace }));
     }
+    handleSetWorkspace(req) {
+        const params = (req.params ?? {});
+        if (typeof params.sessionId !== "string" || params.sessionId.length === 0) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "sessionId is required"));
+            return;
+        }
+        if (!params.workspace ||
+            typeof params.workspace !== "object" ||
+            typeof params.workspace.root !== "string" ||
+            params.workspace.root.length === 0 ||
+            (params.workspace.kind !== "main" && params.workspace.kind !== "worktree")) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "valid workspace is required"));
+            return;
+        }
+        const engine = this.chatManager
+            ? this.chatManager.get(params.sessionId)?.engine
+            : this.legacyEngine;
+        if (!engine) {
+            this.transport.send(createResponse(req.id, { ok: true, workspace: null }));
+            return;
+        }
+        const workspace = engine.setSessionWorkspace?.(params.sessionId, params.workspace);
+        this.transport.send(createResponse(req.id, {
+            ok: workspace !== undefined && workspace !== null,
+            workspace: workspace ?? null,
+        }));
+    }
     // ─── Configure ──────────────────────────────────────────────────
     handleConfigure(req) {
         const params = (req.params ?? {});
@@ -1177,6 +2063,51 @@ export class AgentServer {
         this.transport.send(createResponse(req.id, { ok: true }));
     }
     // ─── Query ──────────────────────────────────────────────────────
+    /**
+     * Resolve the Engine that owns a session-scoped query (compact, archive_range,
+     * …). With a chatManager: materialize a persisted-but-not-live session on
+     * demand, or borrow any live engine when no sessionId is given. Sends the
+     * appropriate error response and returns null when the session is
+     * closing/closed, unknown, or no engine is available; `label` names the query
+     * in the "no engine" message. Domain-neutral — no query-specific literals.
+     */
+    async resolveEngineForSessionQuery(req, sessionId, fallbackEngine, label) {
+        let resolved = fallbackEngine;
+        if (this.chatManager) {
+            if (sessionId) {
+                if (this.chatManager.isUnavailable(sessionId)) {
+                    this.transport.send(createErrorResponse(req.id, ErrorCodes.SessionClosed, `Session is closing or closed: ${sessionId}`));
+                    return null;
+                }
+                let session = this.chatManager.get(sessionId);
+                if (!session) {
+                    const probeEngine = this.anyEngine();
+                    if (!probeEngine?.sessionExistsOnDisk(sessionId)) {
+                        this.transport.send(createErrorResponse(req.id, ErrorCodes.SessionNotFound, `Session not found: ${sessionId}`));
+                        return null;
+                    }
+                    try {
+                        session = await this.chatManager.getOrCreate(sessionId, {
+                            cwd: probeEngine.getSessionManager().readSessionMainRoot(sessionId),
+                        });
+                    }
+                    catch (err) {
+                        this.transport.send(createErrorResponse(req.id, err.code ?? ErrorCodes.InternalError, err.message));
+                        return null;
+                    }
+                }
+                resolved = session.engine;
+            }
+            else {
+                resolved = this.anyEngine();
+            }
+        }
+        if (!resolved) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, `No engine available for ${label} query`));
+            return null;
+        }
+        return resolved;
+    }
     async handleQuery(req) {
         const params = (req.params ?? {});
         // For query operations we prefer the legacyEngine; if absent borrow any
@@ -1199,20 +2130,14 @@ export class AgentServer {
             }
             case "sessions": {
                 if (this.chatManager) {
-                    // Return the ChatSessionManager's live sessions
-                    const sessions = [];
-                    this.chatManager.forEachSession((s) => {
-                        sessions.push({
-                            sessionId: s.id,
-                            busy: s.isBusy(),
-                            queueDepth: s.queueDepth(),
-                            lastActivityAt: s.lastActivityAt,
-                        });
-                    });
+                    // Pet projection and the legacy query share this one live-state builder.
+                    const { sessions } = this.chatManager.getLiveSessionSnapshot();
                     this.transport.send(createResponse(req.id, { type: "sessions", data: sessions }));
                 }
                 else if (engine) {
-                    const sessions = engine.getSessionManager().list();
+                    const sessions = engine
+                        .getSessionManager()
+                        .list(undefined, { excludeKinds: this.hiddenSessionKinds });
                     this.transport.send(createResponse(req.id, { type: "sessions", data: sessions }));
                 }
                 else {
@@ -1274,40 +2199,9 @@ export class AgentServer {
                 const compactSessionId = typeof params.sessionId === "string" && params.sessionId.length > 0
                     ? params.sessionId
                     : undefined;
-                let compactEngine = engine;
-                if (this.chatManager) {
-                    if (compactSessionId) {
-                        if (this.chatManager.isUnavailable(compactSessionId)) {
-                            this.transport.send(createErrorResponse(req.id, ErrorCodes.SessionClosed, `Session is closing or closed: ${compactSessionId}`));
-                            return;
-                        }
-                        let session = this.chatManager.get(compactSessionId);
-                        if (!session) {
-                            const probeEngine = this.anyEngine();
-                            if (!probeEngine?.sessionExistsOnDisk(compactSessionId)) {
-                                this.transport.send(createErrorResponse(req.id, ErrorCodes.SessionNotFound, `Session not found: ${compactSessionId}`));
-                                return;
-                            }
-                            try {
-                                session = await this.chatManager.getOrCreate(compactSessionId, {
-                                    cwd: probeEngine.getSessionManager().readCwd(compactSessionId),
-                                });
-                            }
-                            catch (err) {
-                                this.transport.send(createErrorResponse(req.id, err.code ?? ErrorCodes.InternalError, err.message));
-                                return;
-                            }
-                        }
-                        compactEngine = session.engine;
-                    }
-                    else {
-                        compactEngine = this.anyEngine();
-                    }
-                }
-                if (!compactEngine) {
-                    this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, "No engine available for compact query"));
+                const compactEngine = await this.resolveEngineForSessionQuery(req, compactSessionId, engine, "compact");
+                if (!compactEngine)
                     return;
-                }
                 try {
                     const result = await compactEngine.forceCompact(compactSessionId);
                     if (result.before > result.after) {
@@ -1332,6 +2226,45 @@ export class AgentServer {
                 }
                 break;
             }
+            case "archive_range": {
+                const archiveSessionId = typeof params.sessionId === "string" && params.sessionId.length > 0
+                    ? params.sessionId
+                    : undefined;
+                const start = Number(params.start);
+                const end = Number(params.end);
+                if (!archiveSessionId || !Number.isFinite(start) || !Number.isFinite(end)) {
+                    this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "archive_range requires sessionId, start and end"));
+                    return;
+                }
+                const archiveEngine = await this.resolveEngineForSessionQuery(req, archiveSessionId, engine, "archive_range");
+                if (!archiveEngine)
+                    return;
+                try {
+                    const result = await archiveEngine.archiveTurnRange(archiveSessionId, { start, end });
+                    if (result.before > result.after) {
+                        const event = {
+                            type: "context_compact",
+                            // Range archival has its own tier; "range" must be in
+                            // COMPACT_STREAM_STRATEGIES or it degrades to "compacted".
+                            strategy: toCompactStreamStrategy("range"),
+                            before: result.before,
+                            after: result.after,
+                        };
+                        this.notify(Methods.StreamEvent, {
+                            sessionId: archiveSessionId,
+                            event,
+                        });
+                    }
+                    this.transport.send(createResponse(req.id, {
+                        type: "archive_range",
+                        data: result,
+                    }));
+                }
+                catch (err) {
+                    this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, err.message));
+                }
+                break;
+            }
             case "models": {
                 if (!engine) {
                     this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, "No engine available for models query"));
@@ -1400,11 +2333,6 @@ export class AgentServer {
                 }
                 break;
             }
-            case "arena_status": {
-                const status = getArenaStatus();
-                this.transport.send(createResponse(req.id, { type: "arena_status", data: status }));
-                break;
-            }
             case "config_set": {
                 if (!engine) {
                     this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, "No engine available for config_set"));
@@ -1593,8 +2521,16 @@ export class AgentServer {
                 }
                 break;
             }
-            default:
+            default: {
+                const capability = engine
+                    ? await engine.queryCapability(params.type, params)
+                    : { handled: false };
+                if (capability.handled) {
+                    this.transport.send(createResponse(req.id, { type: params.type, data: capability.data }));
+                    break;
+                }
                 this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, `Unknown query type: ${params.type}`));
+            }
         }
     }
     // ─── Inject ─────────────────────────────────────────────────────
@@ -1708,9 +2644,21 @@ export class AgentServer {
                 return;
             }
             if (session) {
-                session.pendingApprovals.set(requestId, (decision) => {
-                    resolve(decision);
-                });
+                const internal = INTERNAL_PENDING_TOOLS.has(request.toolName);
+                const toolName = safeApprovalToolName(request.toolName);
+                this.registerSessionApproval(session, {
+                    sessionId,
+                    requestId,
+                    routeGeneration: effectiveRoute.generation,
+                    workerGeneration: this.workerGeneration(),
+                    kind: internal ? "internal" : "tool_approval",
+                    title: internal ? "内部操作等待" : `等待批准 ${toolName}`,
+                    toolName,
+                    riskLevel: request.riskLevel,
+                    createdAt: Date.now(),
+                    expiresAt: Date.now() + AgentServer.APPROVAL_TIMEOUT_MS,
+                    surfaceable: !internal,
+                }, (decision) => resolve(decision));
             }
             else {
                 this.pendingApprovals.set(requestId, resolve);
@@ -1719,7 +2667,12 @@ export class AgentServer {
             const timer = setTimeout(() => {
                 const pending = session?.pendingApprovals ?? this.pendingApprovals;
                 if (pending.has(requestId)) {
-                    pending.delete(requestId);
+                    if (session) {
+                        this.takeSessionApproval(session, requestId, "expired");
+                    }
+                    else {
+                        pending.delete(requestId);
+                    }
                     this.pendingApprovalTargets.delete(requestId);
                     this.approvalTimers.delete(requestId);
                     resolve({ approved: false, reason: "approval timed out" });
@@ -1753,7 +2706,17 @@ export class AgentServer {
     requestAskUserForSession(session, sessionId, question, opts) {
         return new Promise((resolve) => {
             const requestId = nanoid(12);
-            session.pendingApprovals.set(requestId, (decision) => {
+            const routeEnvelope = this.approvalRouteEnvelope(sessionId, requestId);
+            this.registerSessionApproval(session, {
+                sessionId,
+                requestId,
+                routeGeneration: "generation" in routeEnvelope ? routeEnvelope.generation : undefined,
+                workerGeneration: this.workerGeneration(),
+                kind: "ask_user",
+                title: "需要用户回答",
+                createdAt: Date.now(),
+                surfaceable: true,
+            }, (decision) => {
                 this.clearApprovalTimer(requestId);
                 const result = decision;
                 if (result && typeof result === "object" && "approved" in result) {
@@ -1776,7 +2739,7 @@ export class AgentServer {
             if (opts?.optionsOnly !== undefined)
                 args.optionsOnly = opts.optionsOnly;
             this.notify(Methods.ApprovalRequest, {
-                ...this.approvalRouteEnvelope(sessionId, requestId),
+                ...routeEnvelope,
                 request: {
                     toolName: "__ask_user__",
                     args,
@@ -1801,12 +2764,11 @@ export class AgentServer {
             }
             if (goalActive) {
                 const timer = setTimeout(() => {
-                    const resolveFn = session.pendingApprovals.get(requestId);
-                    if (resolveFn) {
-                        session.pendingApprovals.delete(requestId);
+                    const entry = this.takeSessionApproval(session, requestId, "expired");
+                    if (entry) {
                         this.pendingApprovalTargets.delete(requestId);
                         this.approvalTimers.delete(requestId);
-                        resolveFn("(用户未在限定时间内回答;目标运行中请自行做出合理假设并继续推进。)");
+                        entry.resolve("(用户未在限定时间内回答;目标运行中请自行做出合理假设并继续推进。)");
                         // Tell every client the ask is resolved (nobody answered) so the
                         // stale AskUserQuestion card is dismissed instead of lingering as
                         // if still waiting. Reuses the same envelope shape the desktop main
@@ -1833,7 +2795,7 @@ export class AgentServer {
             type: (ref, text) => call("type", { ref, text }),
             navigate: (url) => call("navigate", { url }),
             scroll: (dir, amount) => call("scroll", { dir, amount }),
-            readContent: () => call("readContent", {}),
+            readContent: (options) => call("readContent", { ...(options ?? {}) }),
             extractLinks: () => call("extractLinks", {}),
             waitForLoad: (timeoutMs) => call("waitForLoad", { timeoutMs }),
             hover: (ref) => call("hover", { ref }),
@@ -1848,40 +2810,31 @@ export class AgentServer {
     requestBrowserActionForSession(session, sessionId, action, payload) {
         return new Promise((resolve) => {
             const requestId = nanoid(12);
-            session.pendingApprovals.set(requestId, (decision) => {
+            const routeEnvelope = this.approvalRouteEnvelope(sessionId, requestId);
+            this.registerSessionApproval(session, this.internalPendingMetadata(sessionId, requestId, routeEnvelope, "__browser_action__"), (decision) => {
                 this.clearApprovalTimer(requestId);
                 // Main replies with { approved:true, answer:<json string> } (reusing the
                 // ApprovalResult shape) or a raw json string. Parse → typed result.
-                let raw;
-                if (decision && typeof decision === "object" && "approved" in decision) {
-                    const r = decision;
-                    raw = r.approved ? r.answer : undefined;
-                }
-                else if (typeof decision === "string") {
-                    raw = decision;
-                }
-                if (raw === undefined) {
-                    resolve({ ok: false, detail: "browser action declined or unavailable" });
-                    return;
-                }
-                try {
-                    resolve(JSON.parse(raw));
-                }
-                catch {
-                    resolve({ ok: false, detail: "malformed browser action result" });
-                }
+                const parsed = parseHostLoopbackDecision(decision, "browser action");
+                resolve(parsed.ok
+                    ? parsed.value
+                    : { ok: false, failure: parsed.failure, detail: parsed.detail });
             });
             const timer = setTimeout(() => {
                 if (session.pendingApprovals.has(requestId)) {
-                    session.pendingApprovals.delete(requestId);
+                    this.takeSessionApproval(session, requestId, "expired");
                     this.pendingApprovalTargets.delete(requestId);
                     this.approvalTimers.delete(requestId);
-                    resolve({ ok: false, detail: "browser action timed out" });
+                    resolve({
+                        ok: false,
+                        failure: "timed_out",
+                        detail: `browser action ${HOST_LOOPBACK_FAILURE_DETAIL.timed_out}`,
+                    });
                 }
             }, AgentServer.APPROVAL_TIMEOUT_MS);
             this.approvalTimers.set(requestId, timer);
             this.notify(Methods.ApprovalRequest, {
-                ...this.approvalRouteEnvelope(sessionId, requestId),
+                ...routeEnvelope,
                 request: {
                     toolName: "__browser_action__",
                     args: { action, ...payload },
@@ -1900,38 +2853,28 @@ export class AgentServer {
     requestCredentialInjectForSession(session, sessionId, credentialId, credentialScope = "full") {
         return new Promise((resolve) => {
             const requestId = nanoid(12);
-            session.pendingApprovals.set(requestId, (decision) => {
+            const routeEnvelope = this.approvalRouteEnvelope(sessionId, requestId);
+            this.registerSessionApproval(session, this.internalPendingMetadata(sessionId, requestId, routeEnvelope, "__credential_action__"), (decision) => {
                 this.clearApprovalTimer(requestId);
-                let raw;
-                if (decision && typeof decision === "object" && "approved" in decision) {
-                    const r = decision;
-                    raw = r.approved ? r.answer : undefined;
-                }
-                else if (typeof decision === "string") {
-                    raw = decision;
-                }
-                if (raw === undefined) {
-                    resolve({ ok: false, error: "credential inject declined or unavailable" });
-                    return;
-                }
-                try {
-                    resolve(JSON.parse(raw));
-                }
-                catch {
-                    resolve({ ok: false, error: "malformed credential inject result" });
-                }
+                const parsed = parseHostLoopbackDecision(decision, "credential inject");
+                resolve(parsed.ok
+                    ? parsed.value
+                    : { ok: false, error: parsed.detail });
             });
             const timer = setTimeout(() => {
                 if (session.pendingApprovals.has(requestId)) {
-                    session.pendingApprovals.delete(requestId);
+                    this.takeSessionApproval(session, requestId, "expired");
                     this.pendingApprovalTargets.delete(requestId);
                     this.approvalTimers.delete(requestId);
-                    resolve({ ok: false, error: "credential inject timed out" });
+                    resolve({
+                        ok: false,
+                        error: `credential inject ${HOST_LOOPBACK_FAILURE_DETAIL.timed_out}`,
+                    });
                 }
             }, AgentServer.APPROVAL_TIMEOUT_MS);
             this.approvalTimers.set(requestId, timer);
             this.notify(Methods.ApprovalRequest, {
-                ...this.approvalRouteEnvelope(sessionId, requestId),
+                ...routeEnvelope,
                 request: {
                     toolName: "__credential_action__",
                     args: { action: "injectCookie", credentialId, credentialScope },
@@ -1946,46 +2889,145 @@ export class AgentServer {
             switch: (target) => this.requestWorkspaceSwitchForSession(session, sessionId, target),
         };
     }
+    makePanelBridge(session, sessionId) {
+        return {
+            list: async () => {
+                const result = (await this.requestPanelActionForSession(session, sessionId, "list", {}));
+                if (result?.ok === true && Array.isArray(result.panels)) {
+                    return {
+                        items: result.panels,
+                    };
+                }
+                // Never report a failed discovery as an empty host. "(no panels
+                // available)" is an affirmative claim that makes the model give up.
+                return { items: [], failed: hostLoopbackDetail(result) ?? "panel list failed" };
+            },
+            open: async (panelId) => {
+                const result = (await this.requestPanelActionForSession(session, sessionId, "open", {
+                    panelId,
+                }));
+                // Gate on SUCCESS, not merely on shape. A real failure reply is
+                // `{ok:false, panelId, detail}` (AgentPanelHost) — it satisfies a
+                // shape-only `result?.panelId` check and would return verbatim, skipping
+                // both the classification recovery and the length bound below. Every
+                // failure must fall through here.
+                if (result?.ok === true && result?.panelId)
+                    return result;
+                // A classified terminal failure (cancelled / denied / timed out) must
+                // survive this normalization — reporting it as "malformed" would tell the
+                // model the HOST misbehaved when in fact the user stopped the turn.
+                return {
+                    ok: false,
+                    panelId: result?.panelId ?? panelId,
+                    detail: hostLoopbackDetail(result) ?? "panel host returned a malformed result",
+                };
+            },
+            tools: async (panelId) => {
+                const result = (await this.requestPanelActionForSession(session, sessionId, "tools", {
+                    panelId,
+                }));
+                if (result?.ok === true && Array.isArray(result.tools)) {
+                    return {
+                        items: result.tools,
+                    };
+                }
+                return { items: [], failed: hostLoopbackDetail(result) ?? "panel tools query failed" };
+            },
+            invoke: async (panelId, toolName, args) => {
+                const result = (await this.requestPanelActionForSession(session, sessionId, "invoke", {
+                    panelId,
+                    toolName,
+                    arguments: args,
+                }));
+                // Success-gated for the same reason as `open` above. Note a real failure
+                // reply carries `panelId` but usually NOT `toolName` (AgentPanelHost emits
+                // `{ok:false, panelId, detail}`), so the shape check alone was less
+                // frequently bypassed here than for `open` — but `ok === true` is the
+                // property that actually matters, and it also keeps a Panel App's raw
+                // `error.message` from reaching the model unbounded.
+                if (result?.ok === true && result?.panelId && result?.toolName)
+                    return result;
+                return {
+                    ok: false,
+                    panelId: result?.panelId ?? panelId,
+                    toolName: result?.toolName ?? toolName,
+                    detail: hostLoopbackDetail(result) ?? "panel host returned a malformed result",
+                };
+            },
+        };
+    }
+    requestPanelActionForSession(session, sessionId, action, payload) {
+        return new Promise((resolve) => {
+            const requestId = nanoid(12);
+            const routeEnvelope = this.approvalRouteEnvelope(sessionId, requestId);
+            this.registerSessionApproval(session, this.internalPendingMetadata(sessionId, requestId, routeEnvelope, "__panel_action__"), (decision) => {
+                this.clearApprovalTimer(requestId);
+                const parsed = parseHostLoopbackDecision(decision, "panel action");
+                resolve(parsed.ok ? parsed.value : { ok: false, failure: parsed.failure, error: parsed.detail });
+            });
+            const timer = setTimeout(() => {
+                if (session.pendingApprovals.has(requestId)) {
+                    this.takeSessionApproval(session, requestId, "expired");
+                    this.pendingApprovalTargets.delete(requestId);
+                    this.approvalTimers.delete(requestId);
+                    resolve({
+                        ok: false,
+                        failure: "timed_out",
+                        error: `panel action ${HOST_LOOPBACK_FAILURE_DETAIL.timed_out}`,
+                    });
+                }
+            }, AgentServer.APPROVAL_TIMEOUT_MS);
+            this.approvalTimers.set(requestId, timer);
+            this.notify(Methods.ApprovalRequest, {
+                ...routeEnvelope,
+                request: {
+                    toolName: "__panel_action__",
+                    args: { action, ...payload },
+                    description: `panel:${action}`,
+                    riskLevel: "low",
+                },
+            });
+        });
+    }
     requestWorkspaceSwitchForSession(session, sessionId, target) {
         return new Promise((resolve, reject) => {
             const requestId = nanoid(12);
-            session.pendingApprovals.set(requestId, (decision) => {
+            const routeEnvelope = this.approvalRouteEnvelope(sessionId, requestId);
+            this.registerSessionApproval(session, this.internalPendingMetadata(sessionId, requestId, routeEnvelope, "__workspace_action__"), (decision) => {
                 this.clearApprovalTimer(requestId);
-                let raw;
-                if (decision && typeof decision === "object" && "approved" in decision) {
-                    const r = decision;
-                    raw = r.approved ? r.answer : undefined;
-                }
-                else if (typeof decision === "string") {
-                    raw = decision;
-                }
-                if (raw === undefined) {
-                    reject(new Error("workspace switch declined or unavailable"));
+                const outcome = parseHostLoopbackDecision(decision, "workspace switch");
+                if (!outcome.ok) {
+                    reject(new Error(outcome.detail));
                     return;
                 }
-                try {
-                    const parsed = JSON.parse(raw);
-                    if ("ok" in parsed && parsed.ok === false) {
-                        reject(new Error(parsed.error ?? "workspace switch failed"));
-                        return;
-                    }
-                    resolve(parsed);
+                const parsed = outcome.value;
+                // A workspace is always an object. Reject any other JSON shape rather
+                // than resolving it: `null` / a bare number / a string would otherwise
+                // be handed to setSessionWorkspace as if the switch had succeeded,
+                // rebasing the session onto a non-workspace. (Previously a `"ok" in
+                // parsed` TypeError happened to be caught and turned into a rejection;
+                // this states the requirement instead of relying on that.)
+                if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                    reject(new Error(`workspace switch ${HOST_LOOPBACK_FAILURE_DETAIL.malformed}`));
+                    return;
                 }
-                catch {
-                    reject(new Error("malformed workspace switch result"));
+                if ("ok" in parsed && parsed.ok === false) {
+                    reject(new Error(parsed.error ?? "workspace switch failed"));
+                    return;
                 }
+                resolve(parsed);
             });
             const timer = setTimeout(() => {
                 if (session.pendingApprovals.has(requestId)) {
-                    session.pendingApprovals.delete(requestId);
+                    this.takeSessionApproval(session, requestId, "expired");
                     this.pendingApprovalTargets.delete(requestId);
                     this.approvalTimers.delete(requestId);
-                    reject(new Error("workspace switch timed out"));
+                    reject(new Error(`workspace switch ${HOST_LOOPBACK_FAILURE_DETAIL.timed_out}`));
                 }
             }, AgentServer.APPROVAL_TIMEOUT_MS);
             this.approvalTimers.set(requestId, timer);
             this.notify(Methods.ApprovalRequest, {
-                ...this.approvalRouteEnvelope(sessionId, requestId),
+                ...routeEnvelope,
                 request: {
                     toolName: "__workspace_action__",
                     args: { action: "switch", target },
@@ -2059,6 +3101,7 @@ export class AgentServer {
     }
     // ─── Lifecycle ──────────────────────────────────────────────────
     close() {
+        this.observeServerClose();
         this.disconnect("server closing");
         // Detach the bg-agent bus subscription first so a final flurry of
         // completions during shutdown can't race the `shutdown` status
@@ -2073,11 +3116,17 @@ export class AgentServer {
             }
             this.bgAgentBusUnsubscribe = null;
         }
-        if (this.chatManager) {
-            this.chatManager.forEachSession((session) => {
-                this.cancelSessionApprovals(session, "server closing");
-            });
-            this.chatManager.closeAll();
+        // Close the host-supplied manager plus every identity-derived manager
+        // this server lazily created (the map is empty without a resolveIdentity
+        // hook, so the default path closes exactly the base manager as before).
+        if (this.baseChatManager) {
+            const managers = [this.baseChatManager, ...this.identityManagers.values()];
+            for (const manager of managers) {
+                manager.forEachSession((session) => {
+                    this.cancelSessionApprovals(session, "server closing", "cancelled", "session_closed");
+                });
+                manager.closeAll();
+            }
         }
         // Legacy path cleanup
         if (this.abortController) {
@@ -2108,6 +3157,47 @@ export class AgentServer {
             this.approvalRouter.deregister(this.connectionId, reason);
         }
     }
+    /** Resolver-free metadata view for extension projections and protocol snapshots. */
+    getPendingDecisionSnapshot() {
+        const entries = [];
+        this.forEachObserver("snapshotPendingDecisions", (observer) => {
+            const snapshot = observer.snapshotPendingDecisions?.();
+            if (snapshot)
+                entries.push(...snapshot);
+        });
+        return entries;
+    }
+    /** Host lifecycle generation stamped onto pending-approval metadata. */
+    workerGeneration() {
+        return this.chatManager?.getLiveSessionSnapshot().generation ?? 0;
+    }
+    registerSessionApproval(session, metadata, resolve) {
+        metadata = this.observeApprovalCreated(metadata);
+        session.pendingApprovals.set(metadata.requestId, { resolve, metadata });
+    }
+    takeSessionApproval(session, requestId, status) {
+        const entry = session.pendingApprovals.get(requestId);
+        if (!entry)
+            return undefined;
+        session.pendingApprovals.delete(requestId);
+        this.observeApprovalTransition(entry.metadata, status);
+        return entry;
+    }
+    internalPendingMetadata(sessionId, requestId, route, toolName) {
+        const createdAt = Date.now();
+        return {
+            sessionId,
+            requestId,
+            routeGeneration: "generation" in route ? route.generation : undefined,
+            workerGeneration: this.workerGeneration(),
+            kind: "internal",
+            title: "内部操作等待",
+            toolName,
+            createdAt,
+            expiresAt: createdAt + AgentServer.APPROVAL_TIMEOUT_MS,
+            surfaceable: false,
+        };
+    }
     clearApprovalTimer(requestId) {
         const timer = this.approvalTimers.get(requestId);
         if (timer) {
@@ -2122,15 +3212,52 @@ export class AgentServer {
      * the tool hanging. Bounded request types have same-keyed timer entries;
      * AskUserQuestion does not.
      */
-    cancelSessionApprovals(session, reason = "cancelled") {
-        for (const [requestId, resolve] of session.pendingApprovals) {
-            this.clearApprovalTimer(requestId);
-            this.pendingApprovalTargets.delete(requestId);
-            try {
-                resolve({ approved: false, reason });
-            }
-            catch {
-                /* a resolver must never break cancel cleanup */
+    cancelSessionApprovals(session, reason = "cancelled", status = "cancelled", failure = "cancelled") {
+        // Two kinds of entry share this map and they must NOT settle the same way.
+        //
+        //  - kind "tool_approval": a real permission prompt. `{approved:false}` is
+        //    the correct terminal value — the tool call does not proceed.
+        //  - kind "internal": an in-flight host-loopback request (Panel / Browser /
+        //    workspace / credential). `{approved:false}` here is a lie: it makes a
+        //    Stop or a session close indistinguishable from the user pressing Deny,
+        //    and the model is told its Panel operation was refused. These get a
+        //    cancellation sentinel carrying the real cause instead.
+        //
+        // Internal entries settle FIRST: they need no user interaction and have a
+        // determinate outcome, and draining them before the map is emptied keeps
+        // every resolver reachable.
+        //
+        // Drain in a loop rather than over one snapshot. A resolver — or the
+        // observeApprovalTransition hook called synchronously below — may register a
+        // NEW pending entry while we are cancelling. Iterating a snapshot and then
+        // clear()ing would delete that newcomer without ever settling it, leaving its
+        // awaiting tool hung until an outer timeout (its own timer is already gone).
+        // The `settled` guard keeps this terminating even if a resolver re-registers
+        // the same requestId, and the iteration cap stops a pathological resolver
+        // that registers a fresh id every time from spinning forever.
+        const settled = new Set();
+        for (let pass = 0; session.pendingApprovals.size > 0 && pass < 1000; pass += 1) {
+            const entries = [...session.pendingApprovals].filter(([id]) => !settled.has(id));
+            if (entries.length === 0)
+                break;
+            const ordered = [
+                ...entries.filter(([, entry]) => entry.metadata.kind === "internal"),
+                ...entries.filter(([, entry]) => entry.metadata.kind !== "internal"),
+            ];
+            for (const [requestId, entry] of ordered) {
+                settled.add(requestId);
+                session.pendingApprovals.delete(requestId);
+                this.clearApprovalTimer(requestId);
+                this.pendingApprovalTargets.delete(requestId);
+                this.observeApprovalTransition(entry.metadata, status);
+                try {
+                    entry.resolve(entry.metadata.kind === "internal"
+                        ? internalCancellation(failure, reason)
+                        : { approved: false, reason });
+                }
+                catch {
+                    /* a resolver must never break cancel cleanup */
+                }
             }
         }
         session.pendingApprovals.clear();
@@ -2139,7 +3266,7 @@ export class AgentServer {
         for (const target of targets) {
             const session = this.chatManager?.get(target.sessionId);
             if (session) {
-                this.cancelSessionApprovals(session, reason);
+                this.cancelSessionApprovals(session, reason, "owner-lost", "owner_lost");
                 continue;
             }
             for (const [requestId, pending] of this.pendingApprovalTargets) {