@otto-code/server 0.5.0

package/dist/server/server/session.js

@@ -0,0 +1,4763 @@
+import equal from "fast-deep-equal";
+import { v4 as uuidv4 } from "uuid";
+import { stat } from "node:fs/promises";
+import { basename, normalize, resolve, sep } from "path";
+import { homedir } from "node:os";
+import { CLIENT_CAPS } from "@otto-code/protocol/client-capabilities";
+import { serializeAgentStreamEvent, } from "./messages.js";
+import { TerminalSessionController } from "../terminal/terminal-session-controller.js";
+import { CursorError } from "./pagination/cursor.js";
+import { SortablePager } from "./pagination/sortable-pager.js";
+import { EMPTY_SPEECH_SETTINGS_OPTIONS, } from "./speech/speech-settings-options.js";
+import { buildConfigOverrides, extractTimestamps, isStoredAgentProviderAvailable, toAgentPersistenceHandle, } from "./persistence-hooks.js";
+import { ensureAgentLoaded } from "./agent/agent-loading.js";
+import { formatSystemNotificationPrompt, sendPromptToAgent, waitForAgentRunStartWithTimeout, unarchiveAgentState, } from "./agent/agent-prompt.js";
+import { resolveCreateAgentTitles, resolveFirstAgentPromptTitle, } from "./agent/create-agent-title.js";
+import { respondToAgentPermission } from "./agent/permission-response.js";
+import { spawnWorkspaceScript } from "./worktree-bootstrap.js";
+import { createWorkspaceScriptsService, } from "./session/workspace-scripts/workspace-scripts-service.js";
+import { redactDaemonConfigForClient } from "./daemon-config-store.js";
+import { getErrorMessage, getErrorMessageOr } from "@otto-code/protocol/error-utils";
+import { getAgentStatusPriority } from "@otto-code/protocol/agent-state-bucket";
+import { getParentAgentIdFromLabels } from "@otto-code/protocol/agent-labels";
+import { normalizeGitHostingProviderId } from "@otto-code/protocol/messages";
+import { CLIENT_SHUTDOWN_RPC_REASON, normalizeClientRestartRpcReason, } from "./lifecycle-reasons.js";
+import { createAgentCommand } from "./agent/create-agent/create.js";
+import { archiveAgentCommand, cancelAgentRunCommand, closeAgentCommand, detachAgentCommand, setAgentModeCommand, updateAgentCommand, } from "./agent/lifecycle-command.js";
+import { buildStoredAgentPayload, resolveStoredAgentPayloadUpdatedAt, toAgentPayload, } from "./agent/agent-projections.js";
+import { appendTimelineItemIfAgentKnown, emitLiveTimelineItemIfAgentKnown, } from "./agent/timeline-append.js";
+import { projectTimelineRows, selectProjectedTimelinePage, } from "./agent/timeline-projection.js";
+import { buildAgentForkContextAttachment } from "./agent/activity-curator.js";
+import { getAgentStreamEventTurnId, } from "./agent/agent-sdk-types.js";
+import { resolvePersonality, } from "./agent/agent-personalities.js";
+import { ImportSessionsRequestError, importProviderSession, listImportableProviderSessions, normalizeImportAgentRequest, } from "./agent/import-sessions.js";
+import { checkoutLiteFromGitSnapshot, deriveWorkspaceDisplayName, } from "./workspace-registry-model.js";
+import { resolveWorkspaceIdForPath } from "./resolve-workspace-id-for-path.js";
+import { resolveProjectDisplayName, resolveWorkspaceDisplayName, resolveWorkspaceName, } from "./workspace-registry.js";
+import { wrapSpokenInput } from "./voice-config.js";
+import { isVoicePermissionAllowed } from "./voice-permission-policy.js";
+import { VoiceSession } from "./session/voice/voice-session.js";
+import { CheckoutSession } from "./session/checkout/checkout-session.js";
+import { createWorkspaceGitObserverService, } from "./session/workspace-git-observer/workspace-git-observer-service.js";
+import { createAgentStructuredTextGeneration, createGitMetadataGenerator, } from "./session/checkout/git-metadata-generator.js";
+import { ChatScheduleLoopSession } from "./session/chat/chat-schedule-loop-session.js";
+import { ProviderCatalogSession } from "./session/provider/provider-catalog-session.js";
+import { WorkspaceFilesSession } from "./session/files/workspace-files-session.js";
+import { AgentConfigSession } from "./session/agent-config/agent-config-session.js";
+import { ArtifactSession } from "./session/artifact/artifact-session.js";
+import { ArtifactService } from "./artifact/artifact-service.js";
+import { ProjectConfigSession } from "./session/project-config/project-config-session.js";
+import { DaemonSession } from "./session/daemon/daemon-session.js";
+import { readLaunchConfig, LaunchConfigError } from "./preview/launch-config.js";
+import { archivePersistedWorkspaceRecord, archiveWorkspaceContents, } from "./workspace-archive-service.js";
+import { WorkspaceReconciliationService } from "./workspace-reconciliation-service.js";
+import { renameCurrentBranch as renameCurrentBranchDefault } from "../utils/checkout-git.js";
+import { createGitMutationService, } from "./session/git-mutation/git-mutation-service.js";
+import { createWorkspaceProvisioningService, } from "./session/workspace-provisioning/workspace-provisioning-service.js";
+import { createAgentUpdatesService, matchesAgentUpdatesFilter, } from "./session/agent-updates/agent-updates-service.js";
+import { expandTilde } from "../utils/path.js";
+import { searchHomeDirectories, searchWorkspaceEntries } from "../utils/directory-suggestions.js";
+import { createGitHubService } from "../services/github-service.js";
+import { summarizeFetchWorkspacesEntries, workspaceIdsOnCheckout, WorkspaceDirectory, } from "./workspace-directory.js";
+import { shouldEmitPendingBootstrapUpdate } from "./workspace-bootstrap-dedupe.js";
+import { createLocalCheckoutWorkspace, createOttoWorktree, } from "./otto-worktree-service.js";
+import { buildAgentSessionConfig as buildWorktreeAgentSessionConfig, createOttoWorktreeWorkflow as createWorktreeWorkflow, handleCreateOttoWorktreeRequest as handleCreateWorktreeRequest, handleOttoWorktreeArchiveRequest as handleWorktreeArchiveRequest, handleOttoWorktreeListRequest as handleWorktreeListRequest, handleWorkspaceSetupStatusRequest as handleWorkspaceSetupStatusRequestMessage, } from "./worktree-session.js";
+import { archiveByScope } from "./workspace-archive-service.js";
+import { WorktreeRequestError, toWorktreeRequestError, toWorktreeWireError, } from "./worktree-errors.js";
+import { createWorktree } from "../utils/worktree.js";
+import { runGitCommand } from "../utils/run-git-command.js";
+import { CreateAgentLifecycleDispatch } from "./agent/create-agent-lifecycle-dispatch.js";
+// TODO: Remove once all app store clients are on >=0.1.45 and understand arbitrary provider strings.
+// Clients before 0.1.45 validate providers with z.enum(["claude", "codex", "opencode"]) and reject
+// the entire session message if they encounter an unknown provider.
+const LEGACY_PROVIDER_IDS = new Set(["claude", "codex", "opencode"]);
+const MIN_VERSION_ALL_PROVIDERS = "0.1.45";
+function errorToFriendlyMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === "string")
+        return error;
+    return "Unknown error";
+}
+function resolveSubscriptionId(subscribe, requestedSubscriptionId) {
+    if (!subscribe)
+        return null;
+    if (requestedSubscriptionId && requestedSubscriptionId.length > 0) {
+        return requestedSubscriptionId;
+    }
+    return uuidv4();
+}
+function buildWorkspaceCheckout(workspace, project, 
+// The persisted `branch` field is the source of truth, but it is null for
+// records created before branch was lifted to its own field (no migrations,
+// per data-model.md) and for any path that didn't backfill it. Fall back to
+// the live git branch so checkout.currentBranch never regresses to null.
+fallbackBranch) {
+    if (project.kind !== "git") {
+        return {
+            cwd: workspace.cwd,
+            isGit: false,
+            currentBranch: null,
+            remoteUrl: null,
+            worktreeRoot: null,
+            isOttoOwnedWorktree: false,
+            mainRepoRoot: null,
+        };
+    }
+    const currentBranch = workspace.branch ?? fallbackBranch ?? null;
+    if (workspace.kind === "worktree") {
+        return {
+            cwd: workspace.cwd,
+            isGit: true,
+            currentBranch,
+            remoteUrl: null,
+            worktreeRoot: workspace.cwd,
+            isOttoOwnedWorktree: true,
+            mainRepoRoot: project.rootPath,
+        };
+    }
+    return {
+        cwd: workspace.cwd,
+        isGit: true,
+        currentBranch,
+        remoteUrl: null,
+        worktreeRoot: workspace.cwd,
+        isOttoOwnedWorktree: false,
+        mainRepoRoot: null,
+    };
+}
+function isAppVersionAtLeast(appVersion, minVersion) {
+    if (!appVersion)
+        return false;
+    // Strip prerelease suffix: "0.1.45-beta.4" -> "0.1.45"
+    const base = appVersion.replace(/-.*$/, "");
+    const parts = base.split(".").map(Number);
+    const minParts = minVersion.split(".").map(Number);
+    for (let i = 0; i < minParts.length; i++) {
+        const a = parts[i] ?? 0;
+        const b = minParts[i] ?? 0;
+        if (a > b)
+            return true;
+        if (a < b)
+            return false;
+    }
+    return true;
+}
+function clientSupportsAllProviders(appVersion) {
+    return isAppVersionAtLeast(appVersion, MIN_VERSION_ALL_PROVIDERS);
+}
+function beginAgentDeleteIfSupported(agentStorage, agentId) {
+    if ("beginDelete" in agentStorage && typeof agentStorage.beginDelete === "function") {
+        agentStorage.beginDelete(agentId);
+    }
+}
+const FETCH_AGENTS_SORT_KEYS = ["status_priority", "created_at", "updated_at", "title"];
+export function resolveWaitForFinishError(options) {
+    if (options.status !== "error") {
+        return null;
+    }
+    const message = options.final?.lastError;
+    return typeof message === "string" && message.trim().length > 0 ? message : "Agent failed";
+}
+class SessionRequestError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "SessionRequestError";
+    }
+}
+const nodeSessionFileSystem = {
+    async isDirectory(path) {
+        const stats = await stat(path).catch(() => null);
+        return stats?.isDirectory() ?? false;
+    },
+};
+function parseClientCapabilities(capabilities) {
+    if (!capabilities) {
+        return new Set();
+    }
+    const known = new Set(Object.values(CLIENT_CAPS));
+    const result = [];
+    for (const [key, value] of Object.entries(capabilities)) {
+        if (value === true && known.has(key)) {
+            result.push(key);
+        }
+    }
+    return new Set(result);
+}
+function describeRegistryTransition(record) {
+    if (!record) {
+        return "created";
+    }
+    return record.archivedAt ? "unarchived" : "existing";
+}
+/**
+ * Session represents a single connected client session.
+ * It owns all state management, orchestration logic, and message processing.
+ * Session has no knowledge of WebSockets - it only emits and receives messages.
+ */
+export class Session {
+    constructor(options) {
+        this.unsubscribeAgentEvents = null;
+        this.unsubscribeTerminalWorkspaceContributionEvents = null;
+        this.workspaceUpdatesSubscription = null;
+        this.clientActivity = null;
+        this.inflightRequests = 0;
+        this.peakInflightRequests = 0;
+        this.agentsPager = new SortablePager({
+            validKeys: FETCH_AGENTS_SORT_KEYS,
+            defaultSort: [{ key: "updated_at", direction: "desc" }],
+            label: "fetch_agents",
+            getId: (agent) => agent.id,
+            getSortValue: (agent, key) => {
+                switch (key) {
+                    case "status_priority":
+                        return getAgentStatusPriority({
+                            status: agent.status,
+                            pendingPermissionCount: agent.pendingPermissions?.length ?? 0,
+                            requiresAttention: agent.requiresAttention,
+                            attentionReason: agent.attentionReason ?? null,
+                        });
+                    case "created_at":
+                        return Date.parse(agent.createdAt);
+                    case "updated_at":
+                        return Date.parse(agent.updatedAt);
+                    case "title":
+                        return agent.title?.toLocaleLowerCase() ?? "";
+                }
+            },
+        });
+        const { clientId, appVersion, clientCapabilities, onMessage, onBinaryMessage, getTransportBufferedAmount, onLifecycleIntent, logger, downloadTokenStore, pushTokenStore, ottoHome, worktreesRoot, agentManager, agentStorage, projectRegistry, workspaceRegistry, filesystem, chatService, scheduleService, loopService, checkoutDiffManager, github, gitHostingResolver, renameCurrentBranch, workspaceGitService, workspaceAutoName, daemonConfigStore, stt, sttLanguage, tts, terminalManager, previewDevServers, providerSnapshotManager, providerUsageService, serviceProxy, scriptRuntimeStore, workspaceSetupSnapshots, onBranchChanged, getDaemonTcpPort, getDaemonTcpHost, serviceProxyPublicBaseUrl, resolveScriptHealth, voice, voiceBridge, dictation, getSpeechSettingsOptions, previewTts, getPersonalityStats, serverId, daemonVersion, daemonRuntimeConfig, getWebSocketRuntimeMetrics, } = options;
+        this.clientId = clientId;
+        this.getSpeechSettingsOptions = getSpeechSettingsOptions ?? null;
+        this.previewTts = previewTts;
+        this.getPersonalityStats = getPersonalityStats ?? null;
+        this.appVersion = appVersion ?? null;
+        this.clientCapabilities = parseClientCapabilities(clientCapabilities);
+        this.sessionId = uuidv4();
+        this.onMessage = onMessage;
+        this.onBinaryMessage = onBinaryMessage ?? null;
+        this.getTransportBufferedAmount = getTransportBufferedAmount ?? (() => 0);
+        this.onLifecycleIntent = onLifecycleIntent ?? null;
+        this.pushTokenStore = pushTokenStore;
+        this.ottoHome = ottoHome;
+        this.worktreesRoot = worktreesRoot;
+        this.sessionLogger = logger.child({
+            module: "session",
+            clientId: this.clientId,
+            sessionId: this.sessionId,
+        });
+        this.workspaceFilesSession = new WorkspaceFilesSession({
+            host: {
+                emit: (msg) => this.emit(msg),
+                emitBinary: (frame) => this.emitBinary(frame),
+                hasBinaryChannel: () => this.onBinaryMessage !== null,
+            },
+            downloadTokenStore,
+            ottoHome,
+            logger: this.sessionLogger,
+        });
+        this.agentManager = agentManager;
+        this.agentStorage = agentStorage;
+        this.projectRegistry = projectRegistry;
+        this.workspaceRegistry = workspaceRegistry;
+        this.filesystem = filesystem ?? nodeSessionFileSystem;
+        this.github = github ?? createGitHubService();
+        this.gitHostingResolver = gitHostingResolver ?? null;
+        this.renameCurrentBranch = renameCurrentBranch ?? renameCurrentBranchDefault;
+        this.workspaceGitService = workspaceGitService;
+        this.gitMutation = createGitMutationService({
+            workspaceGitService: this.workspaceGitService,
+            github: this.github,
+            logger: this.sessionLogger,
+        });
+        this.workspaceAutoName = workspaceAutoName;
+        this.workspaceProvisioning = createWorkspaceProvisioningService({
+            workspaceRegistry: this.workspaceRegistry,
+            projectRegistry: this.projectRegistry,
+            workspaceGitService: this.workspaceGitService,
+        });
+        this.checkoutSession = new CheckoutSession({
+            host: {
+                emit: (msg) => this.emit(msg),
+                emitWorkspaceUpdateForCwd: (cwd) => this.emitWorkspaceUpdateForCwd(cwd),
+                handleWorkspaceGitBranchSnapshot: (cwd, branchName) => this.workspaceGitObserver.handleBranchSnapshot(cwd, branchName),
+                renameCurrentBranch: (cwd, branch) => this.renameCurrentBranch(cwd, branch),
+            },
+            gitMutation: this.gitMutation,
+            workspaceGitService: this.workspaceGitService,
+            github: this.github,
+            ...(this.gitHostingResolver ? { gitHostingResolver: this.gitHostingResolver } : {}),
+            checkoutDiffManager,
+            gitMetadataGenerator: createGitMetadataGenerator({
+                workspaceGitService: this.workspaceGitService,
+                generation: createAgentStructuredTextGeneration({
+                    agentManager: this.agentManager,
+                    providerSnapshotManager,
+                    readDaemonConfig: () => this.readStructuredGenerationDaemonConfig(),
+                    getFocusedSelection: (cwd) => this.getFocusedAgentSelectionForCwd(cwd),
+                }),
+            }),
+            ottoHome: this.ottoHome,
+            worktreesRoot: this.worktreesRoot,
+            logger: this.sessionLogger,
+        });
+        this.workspaceGitObserver = createWorkspaceGitObserverService({
+            workspaceGitService: this.workspaceGitService,
+            describeWorkspaceRecordWithGitData: (workspace) => this.describeWorkspaceRecordWithGitData(workspace),
+            emitWorkspaceUpdateForCwd: (cwd) => this.emitWorkspaceUpdateForCwd(cwd),
+            emitWorkspaceUpdateForWorkspaceId: (workspaceId) => this.emitWorkspaceUpdateForWorkspaceId(workspaceId),
+            emitStatusUpdate: (cwd, snapshot) => this.checkoutSession.emitStatusUpdate(cwd, snapshot),
+            onBranchChanged,
+            logger: this.sessionLogger,
+        });
+        this.chatScheduleLoopSession = new ChatScheduleLoopSession({
+            host: {
+                emit: (msg) => this.emit(msg),
+                listStoredAgents: () => this.agentStorage.list(),
+                listLiveAgents: () => this.agentManager.listAgents(),
+                resolveAgentIdentifier: (identifier) => this.resolveAgentIdentifier(identifier),
+                sendAgentMessage: async (agentId, text) => {
+                    await sendPromptToAgent({
+                        agentManager: this.agentManager,
+                        agentStorage: this.agentStorage,
+                        agentId,
+                        prompt: formatSystemNotificationPrompt(text),
+                        unarchive: false,
+                        logger: this.sessionLogger,
+                    });
+                },
+            },
+            chatService,
+            scheduleService,
+            loopService,
+            clientId: this.clientId,
+            logger: this.sessionLogger,
+        });
+        this.providerCatalogSession = new ProviderCatalogSession({
+            host: {
+                emit: (msg) => this.emit(msg),
+                isProviderVisibleToClient: (provider) => this.isProviderVisibleToClient(provider),
+                supportsCustomModeIcons: () => this.supports(CLIENT_CAPS.customModeIcons),
+                listProviderAvailability: () => this.agentManager.listProviderAvailability(),
+                listDraftFeatures: (config) => this.agentManager.listDraftFeatures(config),
+            },
+            providerSnapshotManager,
+            providerUsageService,
+            logger: this.sessionLogger,
+        });
+        this.agentConfigSession = new AgentConfigSession({
+            host: {
+                emit: (msg) => this.emit(msg),
+            },
+            operations: {
+                setMode: async (agentId, modeId) => (await setAgentModeCommand({ agentManager }, { agentId, modeId })).notice,
+                setModel: (agentId, modelId) => agentManager.setAgentModel(agentId, modelId),
+                setFeature: (agentId, featureId, value) => agentManager.setAgentFeature(agentId, featureId, value),
+                setThinking: (agentId, thinkingOptionId) => agentManager.setAgentThinkingOption(agentId, thinkingOptionId),
+                setPersonality: async (agentId, personalityId) => {
+                    const snapshot = personalityId === null
+                        ? null
+                        : await this.resolvePersonalitySnapshotForAgent(agentId, personalityId);
+                    return agentManager.setAgentPersonality(agentId, snapshot);
+                },
+            },
+            logger: this.sessionLogger,
+        });
+        this.projectConfigSession = new ProjectConfigSession({
+            host: {
+                emit: (msg) => this.emit(msg),
+            },
+            projectRegistry: this.projectRegistry,
+            logger: this.sessionLogger,
+        });
+        this.daemonSession = new DaemonSession({
+            host: {
+                emit: (msg) => this.emit(msg),
+                emitLifecycleIntent: (intent) => this.emitLifecycleIntent(intent),
+            },
+            clientId: this.clientId,
+            ottoHome: this.ottoHome,
+            serverId,
+            daemonVersion,
+            daemonRuntimeConfig,
+            getWebSocketRuntimeMetrics,
+            listProviderAvailability: () => this.agentManager.listProviderAvailability(),
+            listAgents: () => this.agentManager.listAgents(),
+            listProjects: () => this.projectRegistry.list(),
+            listWorkspaces: () => this.workspaceRegistry.list(),
+            logger: this.sessionLogger,
+        });
+        const artifactService = new ArtifactService({
+            projectCwd: this.ottoHome,
+            logger: this.sessionLogger,
+            agentManager: this.agentManager,
+            providerSnapshotManager,
+            broadcastArtifactUpdate: (metadata) => {
+                this.emit({
+                    type: "artifact.updated.notification",
+                    payload: { artifact: metadata },
+                });
+            },
+        });
+        this.artifactSession = new ArtifactSession({
+            host: {
+                emit: (msg) => this.emit(msg),
+            },
+            artifactService,
+            logger: this.sessionLogger,
+        });
+        this.daemonConfigStore = daemonConfigStore;
+        this.terminalManager = terminalManager;
+        this.previewDevServers = previewDevServers ?? null;
+        this.terminalController = new TerminalSessionController({
+            terminalManager,
+            emit: (msg) => this.emit(msg),
+            emitBinary: (frame) => this.emitBinary(frame),
+            hasBinaryChannel: () => this.onBinaryMessage !== null,
+            isPathWithinRoot: (rootPath, candidatePath) => this.isPathWithinRoot(rootPath, candidatePath),
+            sessionLogger: this.sessionLogger,
+            listTerminalWorkspaceRefs: () => this.listActiveWorkspaceRefs(),
+            clientSupportsWrapReflow: () => this.clientCapabilities.has(CLIENT_CAPS.terminalReflowableSnapshot),
+            getClientBufferedAmount: () => this.getTransportBufferedAmount(),
+        });
+        this.agentUpdates = createAgentUpdatesService({
+            emit: (message) => this.emit(message),
+            buildAgentPayload: (agent) => this.buildAgentPayload(agent),
+            buildStoredAgentPayload: (record) => this.buildStoredAgentPayload(record),
+            isProviderVisibleToClient: (provider) => this.isProviderVisibleToClient(provider),
+            buildProjectPlacementForWorkspaceId: (workspaceId) => this.buildProjectPlacementForWorkspaceId(workspaceId),
+            emitWorkspaceUpdateForWorkspaceId: (workspaceId) => this.emitWorkspaceUpdateForWorkspaceId(workspaceId),
+            logger: this.sessionLogger,
+        });
+        this.createAgentLifecycleDispatch = new CreateAgentLifecycleDispatch({
+            ottoHome: this.ottoHome,
+            worktreesRoot: this.worktreesRoot,
+            agentManager: this.agentManager,
+            agentStorage: this.agentStorage,
+            github: this.github,
+            workspaceGitService: this.workspaceGitService,
+            createOttoWorktreeWorkflow: (input, workflowOptions) => this.createOttoWorktreeWorkflow(input, workflowOptions),
+            archiveAgentForClose: (agentId) => this.archiveAgentForClose(agentId),
+            findWorkspaceIdForCwd: (cwd) => this.findWorkspaceIdForCwd(cwd),
+            listActiveWorkspaces: () => this.listActiveWorkspaceRefs(),
+            archiveWorkspaceRecord: (workspaceId) => this.archiveWorkspaceRecord(workspaceId),
+            emit: (message) => this.emit(message),
+            emitAgentRemove: (agentId) => this.agentUpdates.removeAgent(agentId),
+            emitWorkspaceUpdatesForWorkspaceIds: (workspaceIds) => this.emitWorkspaceUpdatesForWorkspaceIds(workspaceIds),
+            markWorkspaceArchiving: (workspaceIds, archivingAt) => this.markWorkspaceArchiving(workspaceIds, archivingAt),
+            clearWorkspaceArchiving: (workspaceIds) => this.clearWorkspaceArchiving(workspaceIds),
+            killTerminalsForWorkspace: (workspaceId) => this.terminalController.killTerminalsForWorkspace(workspaceId),
+            logger: this.sessionLogger,
+        });
+        this.providerSnapshotManager = providerSnapshotManager;
+        this.serviceProxy = serviceProxy ?? null;
+        this.scriptRuntimeStore = scriptRuntimeStore ?? null;
+        this.workspaceSetupSnapshots = workspaceSetupSnapshots ?? new Map();
+        this.getDaemonTcpPort = getDaemonTcpPort ?? null;
+        this.getDaemonTcpHost = getDaemonTcpHost ?? null;
+        this.serviceProxyPublicBaseUrl = serviceProxyPublicBaseUrl ?? null;
+        this.resolveScriptHealth = resolveScriptHealth ?? null;
+        this.workspaceScripts = createWorkspaceScriptsService({
+            serviceProxy: this.serviceProxy,
+            scriptRuntimeStore: this.scriptRuntimeStore,
+            terminalManager: this.terminalManager,
+            workspaceRegistry: this.workspaceRegistry,
+            workspaceGitService: this.workspaceGitService,
+            getDaemonTcpPort: this.getDaemonTcpPort,
+            getDaemonTcpHost: this.getDaemonTcpHost,
+            serviceProxyPublicBaseUrl: this.serviceProxyPublicBaseUrl,
+            resolveScriptHealth: this.resolveScriptHealth,
+            logger: this.sessionLogger,
+            emit: (message) => this.emit(message),
+            spawnWorkspaceScript,
+        });
+        this.subscribeToOptionalManagers();
+        this.workspaceDirectory = new WorkspaceDirectory({
+            logger: this.sessionLogger,
+            projectRegistry: this.projectRegistry,
+            workspaceRegistry: this.workspaceRegistry,
+            listAgentPayloads: () => this.listAgentPayloads(),
+            listTerminalActivityContributions: () => this.listTerminalActivityContributions(),
+            isProviderVisibleToClient: (provider) => this.isProviderVisibleToClient(provider),
+            buildWorkspaceDescriptor: (input) => this.buildWorkspaceDescriptor(input),
+        });
+        this.voiceSession = new VoiceSession({
+            host: {
+                emit: (msg) => this.emit(msg),
+                loadAgent: (agentId) => ensureAgentLoaded(agentId, {
+                    agentManager: this.agentManager,
+                    agentStorage: this.agentStorage,
+                    logger: this.sessionLogger,
+                }),
+                reloadAgentSession: (agentId, overrides) => this.agentManager.reloadAgentSession(agentId, overrides),
+                sendSpokenInput: async (agentId, text) => {
+                    await this.handleSendAgentMessage(agentId, text, undefined, undefined, undefined, undefined, { spokenInput: true });
+                },
+                interruptAgentIfRunning: (agentId) => this.interruptAgentIfRunning(agentId),
+                hasActiveAgentRun: (agentId) => this.hasActiveAgentRun(agentId),
+            },
+            logger: this.sessionLogger,
+            sessionId: this.sessionId,
+            sttLanguage,
+            tts,
+            stt,
+            voice,
+            voiceBridge,
+            dictation,
+        });
+        this.subscribeToAgentEvents();
+        this.sessionLogger.trace({}, "agent.session.lifecycle.created");
+    }
+    updateAppVersion(appVersion) {
+        if (appVersion && appVersion !== this.appVersion) {
+            this.appVersion = appVersion;
+        }
+    }
+    updateClientCapabilities(capabilities) {
+        this.clientCapabilities = parseClientCapabilities(capabilities);
+    }
+    supports(capability) {
+        return this.clientCapabilities.has(capability);
+    }
+    async syncWorkspaceGitObserverForWorkspace(workspace) {
+        await this.workspaceGitObserver.syncObserverForWorkspace(workspace);
+    }
+    async emitWorkspaceUpdateForWorkspaceId(workspaceId) {
+        await this.emitWorkspaceUpdatesForWorkspaceIds([workspaceId], { skipReconcile: true });
+    }
+    async archiveWorkspaceRecordForExternalMutation(workspaceId) {
+        await this.archiveWorkspaceRecord(workspaceId);
+    }
+    markWorkspaceArchivingForExternalMutation(workspaceIds, archivingAt) {
+        this.markWorkspaceArchiving(workspaceIds, archivingAt);
+    }
+    clearWorkspaceArchivingForExternalMutation(workspaceIds) {
+        this.clearWorkspaceArchiving(workspaceIds);
+    }
+    async emitWorkspaceUpdatesForExternalWorkspaceIds(workspaceIds) {
+        await this.emitWorkspaceUpdatesForWorkspaceIds(workspaceIds);
+    }
+    async warmWorkspaceGitDataForWorkspace(workspace) {
+        await this.workspaceGitObserver.warmGitData(workspace);
+    }
+    /**
+     * Get the client's current activity state
+     */
+    getClientActivity() {
+        return this.clientActivity;
+    }
+    getFocusedAgentSelectionForCwd(cwd) {
+        const focusedAgentId = this.clientActivity?.focusedAgentId;
+        if (!focusedAgentId) {
+            return undefined;
+        }
+        const agent = this.agentManager.getAgent(focusedAgentId);
+        if (!agent || agent.cwd !== cwd) {
+            return undefined;
+        }
+        return {
+            provider: agent.provider,
+            model: agent.runtimeInfo?.model ?? agent.config.model ?? null,
+            thinkingOptionId: agent.runtimeInfo?.thinkingOptionId ?? agent.config.thinkingOptionId ?? null,
+        };
+    }
+    readStructuredGenerationDaemonConfig() {
+        return {
+            metadataGeneration: this.daemonConfigStore.get().metadataGeneration,
+        };
+    }
+    getRuntimeMetrics() {
+        const terminalMetrics = this.terminalController.getMetrics();
+        return {
+            terminalDirectorySubscriptionCount: terminalMetrics.directorySubscriptionCount,
+            terminalSubscriptionCount: terminalMetrics.streamSubscriptionCount,
+            inflightRequests: this.inflightRequests,
+            peakInflightRequests: this.peakInflightRequests,
+        };
+    }
+    emitServerMessage(message) {
+        this.emit(message);
+    }
+    /**
+     * Send initial state to client after connection
+     */
+    async sendInitialState() {
+        // No unsolicited agent list hydration. Callers must use fetch_agents_request.
+    }
+    /**
+     * Normalize a user prompt (with optional image metadata) for AgentManager
+     */
+    buildAgentPrompt(text, images, attachments) {
+        const normalized = text?.trim() ?? "";
+        const hasImages = Boolean(images && images.length > 0);
+        const hasAttachments = Boolean(attachments && attachments.length > 0);
+        if (!hasImages && !hasAttachments) {
+            return normalized;
+        }
+        const blocks = [];
+        if (normalized.length > 0) {
+            blocks.push({ type: "text", text: normalized });
+        }
+        for (const image of images ?? []) {
+            blocks.push({ type: "image", data: image.data, mimeType: image.mimeType });
+        }
+        for (const attachment of attachments ?? []) {
+            blocks.push(attachment);
+        }
+        return blocks;
+    }
+    /**
+     * Interrupt the agent's active run so the next prompt starts a fresh turn.
+     * Returns once the manager confirms the stream has been cancelled.
+     */
+    async interruptAgentIfRunning(agentId) {
+        const snapshot = this.agentManager.getAgent(agentId);
+        if (!snapshot) {
+            this.sessionLogger.trace({ agentId }, "agent.session.interrupt.not_found");
+            throw new Error(`Agent ${agentId} not found`);
+        }
+        const hasInFlightRun = this.agentManager.hasInFlightRun(agentId);
+        if (!hasInFlightRun) {
+            this.sessionLogger.trace({
+                agentId,
+                provider: snapshot.provider,
+                lifecycle: snapshot.lifecycle,
+                hasInFlightRun,
+            }, "agent.session.interrupt.skip_not_running");
+            return;
+        }
+        this.sessionLogger.debug({ agentId, lifecycle: snapshot.lifecycle, hasInFlightRun }, "interruptAgentIfRunning: interrupting");
+        const t0 = Date.now();
+        const cancelled = await this.agentManager.cancelAgentRun(agentId);
+        this.sessionLogger.debug({ agentId, cancelled, durationMs: Date.now() - t0 }, "interruptAgentIfRunning: cancelAgentRun completed");
+        if (!cancelled) {
+            this.sessionLogger.warn({ agentId }, "interruptAgentIfRunning: reported running but no active run was cancelled");
+        }
+    }
+    hasActiveAgentRun(agentId) {
+        if (!agentId) {
+            return false;
+        }
+        return this.agentManager.hasInFlightRun(agentId);
+    }
+    handleAgentRunError(agentId, error, context) {
+        const message = errorToFriendlyMessage(error);
+        this.sessionLogger.error({ err: error, agentId, context }, `${context} for agent ${agentId}`);
+        this.emit({
+            type: "activity_log",
+            payload: {
+                id: uuidv4(),
+                timestamp: new Date(),
+                type: "error",
+                content: `${context}: ${message}`,
+            },
+        });
+    }
+    /**
+     * Subscribe to AgentManager events and forward them to the client
+     */
+    subscribeToOptionalManagers() {
+        this.terminalController.start();
+        if (this.terminalManager) {
+            this.unsubscribeTerminalWorkspaceContributionEvents =
+                this.terminalManager.subscribeTerminalWorkspaceContributionChanged((event) => {
+                    void this.emitWorkspaceUpdateForTerminalContribution(event).catch((error) => {
+                        this.sessionLogger.warn({ err: error, terminalId: event.terminalId }, "Failed to emit workspace update after terminal contribution changed");
+                    });
+                });
+        }
+        this.providerCatalogSession.start();
+    }
+    subscribeToAgentEvents() {
+        if (this.unsubscribeAgentEvents) {
+            this.unsubscribeAgentEvents();
+        }
+        this.unsubscribeAgentEvents = this.agentManager.subscribe((event) => {
+            if (event.type === "agent_state") {
+                this.sessionLogger.trace({
+                    agentId: event.agent.id,
+                    provider: event.agent.provider,
+                    providerSessionId: event.agent.persistence?.sessionId ?? undefined,
+                    turnId: event.agent.activeForegroundTurnId ?? undefined,
+                    lifecycle: event.agent.lifecycle,
+                }, "agent.session.forward_update");
+                void this.agentUpdates.forwardLiveAgent(event.agent);
+                return;
+            }
+            if (event.type === "observed_agent_state") {
+                // Synthetic snapshot for an observed subagent (no ManagedAgent
+                // runtime). Forward through the same filter/placement path as live
+                // agents. See projects/observed-subagents/observed-subagents.md.
+                void this.agentUpdates.forwardLiveAgentPayload(event.payload);
+                return;
+            }
+            if (this.voiceSession.isActiveForAgent(event.agentId) &&
+                event.event.type === "permission_requested" &&
+                isVoicePermissionAllowed(event.event.request)) {
+                const requestId = event.event.request.id;
+                void this.agentManager
+                    .respondToPermission(event.agentId, requestId, {
+                    behavior: "allow",
+                })
+                    .catch((error) => {
+                    this.sessionLogger.warn({
+                        err: error,
+                        agentId: event.agentId,
+                        requestId,
+                    }, "Failed to auto-allow speak tool permission in voice mode");
+                });
+            }
+            const serializedEvent = serializeAgentStreamEvent(event.event);
+            if (!serializedEvent) {
+                return;
+            }
+            this.sessionLogger.trace({
+                agentId: event.agentId,
+                provider: event.event.provider,
+                turnId: getAgentStreamEventTurnId(event.event),
+                seq: event.seq,
+                epoch: event.epoch,
+                event: event.event,
+            }, "agent.session.forward_stream");
+            this.emit({
+                type: "agent_stream",
+                payload: this.buildAgentStreamPayload(event, serializedEvent),
+            });
+            if (event.event.type === "permission_requested") {
+                this.emit({
+                    type: "agent_permission_request",
+                    payload: {
+                        agentId: event.agentId,
+                        request: event.event.request,
+                    },
+                });
+            }
+            else if (event.event.type === "permission_resolved") {
+                this.emit({
+                    type: "agent_permission_resolved",
+                    payload: {
+                        agentId: event.agentId,
+                        requestId: event.event.requestId,
+                        resolution: event.event.resolution,
+                    },
+                });
+            }
+            // Title updates may be applied asynchronously after agent creation.
+        }, { replayState: false });
+    }
+    buildAgentStreamPayload(event, serializedEvent) {
+        return {
+            agentId: event.agentId,
+            event: serializedEvent,
+            timestamp: event.timestamp ?? new Date().toISOString(),
+            ...(typeof event.seq === "number" ? { seq: event.seq } : {}),
+            ...(typeof event.epoch === "string" ? { epoch: event.epoch } : {}),
+        };
+    }
+    async buildAgentPayload(agent) {
+        const storedRecord = await this.agentStorage.get(agent.id);
+        const title = storedRecord?.title ?? null;
+        const payload = toAgentPayload(agent, { title });
+        const storedUpdatedAt = storedRecord ? resolveStoredAgentPayloadUpdatedAt(storedRecord) : null;
+        if (storedUpdatedAt) {
+            const liveUpdatedAt = Date.parse(payload.updatedAt);
+            const persistedUpdatedAt = Date.parse(storedUpdatedAt);
+            if (Number.isNaN(liveUpdatedAt) || persistedUpdatedAt > liveUpdatedAt) {
+                payload.updatedAt = storedUpdatedAt;
+            }
+        }
+        payload.archivedAt = storedRecord?.archivedAt ?? null;
+        return payload;
+    }
+    buildStoredAgentPayload(record, registeredProviderIds = new Set(this.providerSnapshotManager.listRegisteredProviderIds())) {
+        return buildStoredAgentPayload(record, registeredProviderIds);
+    }
+    isProviderVisibleToClient(provider) {
+        if (clientSupportsAllProviders(this.appVersion)) {
+            return true;
+        }
+        return LEGACY_PROVIDER_IDS.has(provider);
+    }
+    async buildProjectPlacementForWorkspace(workspace, projectRecord) {
+        const project = projectRecord ?? (await this.projectRegistry.get(workspace.projectId));
+        if (!project) {
+            throw new Error(`Project not found for workspace ${workspace.workspaceId}`);
+        }
+        const liveBranch = this.workspaceGitService.peekSnapshot(workspace.cwd)?.git.currentBranch ?? null;
+        const checkout = buildWorkspaceCheckout(workspace, project, liveBranch);
+        return {
+            projectKey: project.projectId,
+            projectName: resolveProjectDisplayName(project),
+            workspaceName: resolveWorkspaceDisplayName(workspace),
+            checkout,
+        };
+    }
+    async buildProjectPlacementForWorkspaceId(workspaceId) {
+        const workspace = await this.workspaceRegistry.get(workspaceId);
+        if (!workspace)
+            return null;
+        const project = await this.projectRegistry.get(workspace.projectId);
+        if (!project)
+            return null;
+        return this.buildProjectPlacementForWorkspace(workspace, project);
+    }
+    /**
+     * Main entry point for processing session messages
+     */
+    async handleMessage(msg) {
+        this.inflightRequests++;
+        if (this.inflightRequests > this.peakInflightRequests) {
+            this.peakInflightRequests = this.inflightRequests;
+        }
+        try {
+            this.sessionLogger.trace({
+                messageType: msg.type,
+                payloadBytes: JSON.stringify(msg).length,
+            }, "agent.session.inbound");
+            try {
+                await this.dispatchInboundMessage(msg);
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                this.sessionLogger.error({ err }, "Error handling message");
+                const requestId = "requestId" in msg && typeof msg.requestId === "string" ? msg.requestId : undefined;
+                if (typeof requestId === "string") {
+                    try {
+                        this.emit({
+                            type: "rpc_error",
+                            payload: {
+                                requestId,
+                                requestType: msg.type,
+                                error: `Request failed: ${err.message}`,
+                                code: "handler_error",
+                            },
+                        });
+                    }
+                    catch (emitError) {
+                        this.sessionLogger.error({ err: emitError }, "Failed to emit rpc_error");
+                    }
+                }
+                this.emit({
+                    type: "activity_log",
+                    payload: {
+                        id: uuidv4(),
+                        timestamp: new Date(),
+                        type: "error",
+                        content: `Error: ${err.message}`,
+                    },
+                });
+            }
+        }
+        finally {
+            this.inflightRequests--;
+        }
+    }
+    async dispatchInboundMessage(msg) {
+        const promise = this.dispatchVoiceAndControlMessage(msg) ??
+            this.dispatchAgentRewindMessage(msg) ??
+            this.dispatchAgentPersonalityMessage(msg) ??
+            this.dispatchAgentRelationshipMessage(msg) ??
+            this.dispatchAgentTimelineMessage(msg) ??
+            this.dispatchAgentLifecycleMessage(msg) ??
+            this.dispatchAgentConfigMessage(msg) ??
+            this.dispatchCheckoutMessage(msg) ??
+            this.dispatchPreviewMessage(msg) ??
+            this.dispatchWorkspaceAndProjectMessage(msg) ??
+            this.dispatchWorkspaceFilesMessage(msg) ??
+            this.dispatchProviderMessage(msg) ??
+            this.dispatchTerminalMessage(msg) ??
+            this.dispatchChatScheduleLoopMessage(msg) ??
+            this.dispatchArtifactMessage(msg) ??
+            this.dispatchMiscMessage(msg);
+        if (promise)
+            await promise;
+    }
+    dispatchVoiceAndControlMessage(msg) {
+        switch (msg.type) {
+            case "voice_audio_chunk":
+                return this.voiceSession.handleAudioChunk(msg);
+            case "abort_request":
+                return this.voiceSession.handleAbort();
+            case "audio_played":
+                this.voiceSession.handleAudioPlayed(msg.id);
+                return undefined;
+            case "set_voice_mode":
+                return this.voiceSession.handleSetVoiceMode(msg.enabled, msg.agentId, msg.requestId);
+            case "dictation_stream_start":
+                return this.voiceSession.handleDictationStreamStart(msg);
+            case "dictation_stream_chunk":
+                return this.voiceSession.handleDictationChunk({
+                    dictationId: msg.dictationId,
+                    seq: msg.seq,
+                    audioBase64: msg.audio,
+                    format: msg.format,
+                });
+            case "dictation_stream_finish":
+                return this.voiceSession.handleDictationFinish(msg.dictationId, msg.finalSeq);
+            case "dictation_stream_cancel":
+                this.voiceSession.handleDictationCancel(msg.dictationId);
+                return undefined;
+            case "restart_server_request":
+                return this.handleRestartServerRequest(msg.requestId, msg.reason);
+            case "shutdown_server_request":
+                return this.handleShutdownServerRequest(msg.requestId);
+            case "client_heartbeat":
+                this.handleClientHeartbeat(msg);
+                return undefined;
+            case "ping": {
+                const now = Date.now();
+                this.emit({
+                    type: "pong",
+                    payload: {
+                        requestId: msg.requestId,
+                        clientSentAt: msg.clientSentAt,
+                        serverReceivedAt: now,
+                        serverSentAt: now,
+                    },
+                });
+                return undefined;
+            }
+            default:
+                return undefined;
+        }
+    }
+    dispatchAgentRewindMessage(msg) {
+        switch (msg.type) {
+            case "agent.rewind.request":
+                return this.handleAgentRewindRequest(msg);
+            default:
+                return undefined;
+        }
+    }
+    // Kept out of dispatchAgentConfigMessage only because that switch sits at the
+    // complexity ceiling; the handler itself lives with its config siblings.
+    dispatchAgentPersonalityMessage(msg) {
+        switch (msg.type) {
+            case "agent.personality.set.request":
+                return this.agentConfigSession.handleAgentPersonalitySetRequest(msg);
+            default:
+                return undefined;
+        }
+    }
+    dispatchAgentRelationshipMessage(msg) {
+        switch (msg.type) {
+            case "agent.detach.request":
+                return this.handleDetachAgentRequest(msg.agentId, msg.requestId);
+            case "agent.subagent.stop.request":
+                return this.handleStopObservedSubagentRequest(msg.agentId, msg.requestId);
+            default:
+                return undefined;
+        }
+    }
+    async handleStopObservedSubagentRequest(agentId, requestId) {
+        try {
+            await this.agentManager.stopObservedSubagent(agentId);
+            this.emit({
+                type: "agent.subagent.stop.response",
+                payload: {
+                    requestId,
+                    agentId,
+                    accepted: true,
+                    error: null,
+                },
+            });
+        }
+        catch (error) {
+            const message = getErrorMessageOr(error, "Failed to stop observed subagent");
+            this.sessionLogger.error({ err: error, agentId, requestId }, "Failed to stop observed subagent");
+            this.emit({
+                type: "agent.subagent.stop.response",
+                payload: {
+                    requestId,
+                    agentId,
+                    accepted: false,
+                    error: message,
+                },
+            });
+        }
+    }
+    dispatchAgentTimelineMessage(msg) {
+        switch (msg.type) {
+            case "fetch_agent_timeline_request":
+                return this.handleFetchAgentTimelineRequest(msg);
+            case "agent.fork_context.request":
+                return this.handleAgentForkContextRequest(msg);
+            default:
+                return undefined;
+        }
+    }
+    dispatchAgentLifecycleMessage(msg) {
+        switch (msg.type) {
+            case "fetch_agents_request":
+                return this.handleFetchAgents(msg);
+            case "fetch_agent_history_request":
+                return this.handleFetchAgentHistory(msg);
+            case "fetch_recent_provider_sessions_request":
+                return this.handleFetchRecentProviderSessions(msg);
+            case "fetch_agent_request":
+                return this.handleFetchAgent(msg.agentId, msg.requestId);
+            case "delete_agent_request":
+                return this.handleDeleteAgentRequest(msg.agentId, msg.requestId);
+            case "archive_agent_request":
+                return this.handleArchiveAgentRequest(msg.agentId, msg.requestId);
+            case "close_items_request":
+                return this.handleCloseItemsRequest(msg);
+            case "update_agent_request":
+                return this.handleUpdateAgentRequest(msg.agentId, msg.name, msg.labels, msg.requestId);
+            case "project.rename.request":
+                return this.handleProjectRenameRequest(msg.projectId, msg.customName, msg.requestId);
+            case "send_agent_message_request":
+                return this.handleSendAgentMessageRequest(msg);
+            case "wait_for_finish_request":
+                return this.handleWaitForFinish(msg.agentId, msg.requestId, msg.timeoutMs);
+            case "create_agent_request":
+                return this.handleCreateAgentRequest(msg);
+            case "resume_agent_request":
+                return this.handleResumeAgentRequest(msg);
+            case "import_agent_request":
+                return this.handleImportAgentRequest(msg);
+            case "refresh_agent_request":
+                return this.handleRefreshAgentRequest(msg);
+            case "cancel_agent_request":
+                return this.handleCancelAgentRequest(msg.agentId, msg.requestId);
+            case "agent_permission_response":
+                return this.handleAgentPermissionResponse(msg.agentId, msg.requestId, msg.response);
+            case "clear_agent_attention":
+                return this.handleClearAgentAttention(msg.agentId, msg.requestId);
+            default:
+                return undefined;
+        }
+    }
+    dispatchAgentConfigMessage(msg) {
+        switch (msg.type) {
+            case "set_agent_mode_request":
+                return this.agentConfigSession.handleSetAgentModeRequest(msg);
+            case "set_agent_model_request":
+                return this.agentConfigSession.handleSetAgentModelRequest(msg);
+            case "set_agent_feature_request":
+                return this.agentConfigSession.handleSetAgentFeatureRequest(msg);
+            case "set_agent_thinking_request":
+                return this.agentConfigSession.handleSetAgentThinkingRequest(msg);
+            case "get_daemon_config_request":
+                this.emit({
+                    type: "get_daemon_config_response",
+                    payload: {
+                        requestId: msg.requestId,
+                        config: redactDaemonConfigForClient(this.daemonConfigStore.get()),
+                    },
+                });
+                return undefined;
+            case "daemon.get_status.request":
+                return this.daemonSession.handleGetStatusRequest(msg);
+            case "daemon.get_pairing_offer.request":
+                return this.daemonSession.handleGetPairingOfferRequest(msg);
+            case "diagnostics.request":
+                return this.daemonSession.handleDiagnosticsRequest(msg);
+            case "daemon.update.request":
+                return this.daemonSession.handleUpdateRequest(msg);
+            case "set_daemon_config_request":
+                this.emit({
+                    type: "set_daemon_config_response",
+                    payload: {
+                        requestId: msg.requestId,
+                        config: redactDaemonConfigForClient(this.daemonConfigStore.patch(msg.config)),
+                    },
+                });
+                return undefined;
+            case "speech.settings.get_options.request":
+                this.emit({
+                    type: "speech.settings.get_options.response",
+                    payload: {
+                        requestId: msg.requestId,
+                        options: this.getSpeechSettingsOptions?.() ?? EMPTY_SPEECH_SETTINGS_OPTIONS,
+                    },
+                });
+                return undefined;
+            case "speech.tts.preview.request":
+                this.handleTtsPreviewRequest(msg.requestId, msg.text, msg.voice);
+                return undefined;
+            case "agentPersonalities.get_stats.request": {
+                const statsRequestId = msg.requestId;
+                // The stats store is async (file-backed); resolve then emit.
+                void Promise.resolve(this.getPersonalityStats?.() ?? {}).then((stats) => {
+                    this.emit({
+                        type: "agentPersonalities.get_stats.response",
+                        payload: { requestId: statsRequestId, stats },
+                    });
+                    return undefined;
+                });
+                return undefined;
+            }
+            case "read_project_config_request":
+                return this.projectConfigSession.handleReadProjectConfigRequest(msg);
+            case "write_project_config_request":
+                return this.projectConfigSession.handleWriteProjectConfigRequest(msg);
+            default:
+                return undefined;
+        }
+    }
+    // Synthesize a short preview sample and reply once (or with an error). Async
+    // work is fire-and-forget: the correlated response is emitted from the
+    // promise, mirroring how the get_stats request replies.
+    handleTtsPreviewRequest(requestId, text, voice) {
+        const preview = this.previewTts;
+        if (!preview) {
+            this.emit({
+                type: "speech.tts.preview.response",
+                payload: { requestId, error: "TTS is not configured on this host." },
+            });
+            return;
+        }
+        void preview({ text, voice })
+            .then((result) => {
+            this.emit({
+                type: "speech.tts.preview.response",
+                payload: result
+                    ? { requestId, audio: result.audio, format: result.format }
+                    : { requestId, error: "No audio was produced for this voice." },
+            });
+            return undefined;
+        })
+            .catch((error) => {
+            this.emit({
+                type: "speech.tts.preview.response",
+                payload: {
+                    requestId,
+                    error: error instanceof Error ? error.message : "Voice preview failed.",
+                },
+            });
+        });
+    }
+    // eslint-disable-next-line complexity
+    dispatchCheckoutMessage(msg) {
+        switch (msg.type) {
+            case "checkout_status_request":
+                return this.checkoutSession.handleStatusRequest(msg);
+            case "validate_branch_request":
+                return this.checkoutSession.handleValidateBranchRequest(msg);
+            case "branch_suggestions_request":
+                return this.checkoutSession.handleBranchSuggestionsRequest(msg);
+            case "directory_suggestions_request":
+                return this.handleDirectorySuggestionsRequest(msg);
+            case "subscribe_checkout_diff_request":
+                return this.checkoutSession.handleSubscribeDiffRequest(msg);
+            case "unsubscribe_checkout_diff_request":
+                this.checkoutSession.handleUnsubscribeDiffRequest(msg);
+                return undefined;
+            case "checkout_switch_branch_request":
+                return this.checkoutSession.handleCheckoutSwitchBranchRequest(msg);
+            case "checkout.rename_branch.request":
+                return this.checkoutSession.handleCheckoutRenameBranchRequest(msg);
+            case "checkout_commit_request":
+                return this.checkoutSession.handleCheckoutCommitRequest(msg);
+            case "checkout_merge_request":
+                return this.checkoutSession.handleCheckoutMergeRequest(msg);
+            case "checkout_merge_from_base_request":
+                return this.checkoutSession.handleCheckoutMergeFromBaseRequest(msg);
+            case "checkout_pull_request":
+                return this.checkoutSession.handleCheckoutPullRequest(msg);
+            case "checkout_push_request":
+                return this.checkoutSession.handleCheckoutPushRequest(msg);
+            case "checkout.refresh.request":
+                return this.checkoutSession.handleRefreshRequest(msg);
+            case "checkout_pr_create_request":
+                return this.checkoutSession.handleCheckoutPrCreateRequest(msg);
+            case "checkout_pr_merge_request":
+                return this.checkoutSession.handleCheckoutPrMergeRequest(msg);
+            case "checkout.github.set_auto_merge.request":
+                return this.checkoutSession.handleCheckoutGithubSetAutoMergeRequest(msg);
+            case "checkout.github.get_check_details.request":
+                return this.checkoutSession.handleCheckoutGithubGetCheckDetailsRequest(msg);
+            case "checkout_pr_status_request":
+                return this.checkoutSession.handleCheckoutPrStatusRequest(msg);
+            case "pull_request_timeline_request":
+                return this.checkoutSession.handlePullRequestTimelineRequest(msg);
+            case "github_search_request":
+                return this.checkoutSession.handleGitHubSearchRequest(msg);
+            case "hosting.search.request":
+                return this.checkoutSession.handleHostingSearchRequest(msg);
+            case "hosting.auth_status.request":
+                return this.handleHostingAuthStatusRequest(msg);
+            case "stash_save_request":
+                return this.checkoutSession.handleStashSaveRequest(msg);
+            case "stash_pop_request":
+                return this.checkoutSession.handleStashPopRequest(msg);
+            case "stash_list_request":
+                return this.checkoutSession.handleStashListRequest(msg);
+            default:
+                return undefined;
+        }
+    }
+    // Connection check for the host Git providers settings section: resolves a
+    // provider's host-level credentials and performs a single forced auth probe.
+    // User-initiated only — never called from polling or reconciliation paths.
+    async handleHostingAuthStatusRequest(msg) {
+        const { provider, requestId } = msg;
+        const emitResult = (payload) => {
+            this.emit({
+                type: "hosting.auth_status.response",
+                payload: { provider, requestId, ...payload },
+            });
+        };
+        if (!this.gitHostingResolver) {
+            emitResult({ authenticated: false, error: "Hosting is unavailable" });
+            return;
+        }
+        // The wire provider id is an open string; a request naming a provider this
+        // build doesn't support resolves to no service rather than throwing.
+        const providerId = normalizeGitHostingProviderId(provider);
+        if (!providerId) {
+            emitResult({ authenticated: false, error: null });
+            return;
+        }
+        try {
+            const resolved = this.gitHostingResolver.resolveForProvider(providerId);
+            if (!resolved.service) {
+                emitResult({ authenticated: false, error: null });
+                return;
+            }
+            // gh reads global config; Bitbucket ignores cwd. ottoHome is a stable
+            // directory for a provider-level (non-workspace) auth check.
+            const authenticated = await resolved.service.isAuthenticated({
+                cwd: this.ottoHome,
+                force: true,
+                reason: "hosting-auth-status",
+            });
+            emitResult({ authenticated, error: null });
+        }
+        catch (error) {
+            emitResult({
+                authenticated: false,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    dispatchPreviewMessage(msg) {
+        switch (msg.type) {
+            case "preview.list_config.request":
+                return this.handlePreviewListConfigRequest(msg.cwd, msg.requestId);
+            case "preview.start.request":
+                return this.handlePreviewStartRequest(msg.cwd, msg.name, msg.requestId);
+            case "preview.bind_tab.request":
+                return this.handlePreviewBindTabRequest(msg.serverId, msg.browserId, msg.requestId);
+            case "preview.stop.request":
+                return this.handlePreviewStopRequest(msg.serverId, msg.requestId);
+            default:
+                return undefined;
+        }
+    }
+    dispatchWorkspaceAndProjectMessage(msg) {
+        switch (msg.type) {
+            case "fetch_workspaces_request":
+                return this.handleFetchWorkspacesRequest(msg);
+            case "otto_worktree_list_request":
+                return this.handleOttoWorktreeListRequest(msg);
+            case "otto_worktree_archive_request":
+                return this.handleOttoWorktreeArchiveRequest(msg);
+            case "create_otto_worktree_request":
+                return this.handleCreateOttoWorktreeRequest(msg);
+            case "workspace_setup_status_request":
+                return this.handleWorkspaceSetupStatusRequest(msg);
+            // COMPAT(desktopEditorBridge): added in v0.1.88, remove after 2026-12-03 once old clients no longer call daemon editor RPCs.
+            case "list_available_editors_request":
+                return this.handleLegacyListAvailableEditorsRequest(msg);
+            case "open_in_editor_request":
+                return this.handleLegacyOpenInEditorRequest(msg);
+            case "open_project_request":
+                return this.handleOpenProjectRequest(msg);
+            case "project.add.request":
+                return this.handleProjectAddRequest(msg);
+            case "archive_workspace_request":
+                return this.handleArchiveWorkspaceRequest(msg);
+            case "project.remove.request":
+                return this.handleProjectRemoveRequest(msg);
+            case "workspace.create.request":
+                return this.handleWorkspaceCreateRequest(msg);
+            case "workspace.clear_attention.request":
+                return this.handleWorkspaceClearAttentionRequest(msg);
+            case "workspace.title.set.request":
+                return this.handleWorkspaceTitleSetRequest(msg.workspaceId, msg.title, msg.requestId);
+            default:
+                return undefined;
+        }
+    }
+    dispatchWorkspaceFilesMessage(msg) {
+        switch (msg.type) {
+            case "file_explorer_request":
+                return this.workspaceFilesSession.handleFileExplorerRequest(msg);
+            case "project_icon_request":
+                return this.workspaceFilesSession.handleProjectIconRequest(msg);
+            case "file_download_token_request":
+                return this.workspaceFilesSession.handleFileDownloadTokenRequest(msg);
+            case "file.upload.request":
+                this.workspaceFilesSession.handleFileUploadRequest(msg);
+                return undefined;
+            case "file.write.request":
+                return this.workspaceFilesSession.handleFileWriteRequest(msg);
+            case "file.watch.subscribe.request":
+                return this.workspaceFilesSession.handleFileWatchSubscribeRequest(msg);
+            case "file.watch.unsubscribe.request":
+                this.workspaceFilesSession.handleFileWatchUnsubscribeRequest(msg);
+                return undefined;
+            case "file.search.request":
+                return this.workspaceFilesSession.handleFileSearchRequest(msg);
+            case "file.replace.request":
+                return this.workspaceFilesSession.handleFileReplaceRequest(msg);
+            case "code.list_files.request":
+                return this.workspaceFilesSession.handleCodeListFilesRequest(msg);
+            case "code.symbols.request":
+                return this.workspaceFilesSession.handleCodeSymbolsRequest(msg);
+            case "code.outline.request":
+                return this.workspaceFilesSession.handleCodeOutlineRequest(msg);
+            default:
+                return undefined;
+        }
+    }
+    dispatchProviderMessage(msg) {
+        switch (msg.type) {
+            case "list_provider_models_request":
+                return this.providerCatalogSession.handleListProviderModelsRequest(msg);
+            case "list_provider_modes_request":
+                return this.providerCatalogSession.handleListProviderModesRequest(msg);
+            case "list_provider_features_request":
+                return this.providerCatalogSession.handleListProviderFeaturesRequest(msg);
+            case "list_available_providers_request":
+                return this.providerCatalogSession.handleListAvailableProvidersRequest(msg);
+            case "get_providers_snapshot_request":
+                return this.providerCatalogSession.handleGetProvidersSnapshotRequest(msg);
+            case "refresh_providers_snapshot_request":
+                return this.providerCatalogSession.handleRefreshProvidersSnapshotRequest(msg);
+            case "provider_diagnostic_request":
+                return this.providerCatalogSession.handleProviderDiagnosticRequest(msg);
+            case "provider.usage.list.request":
+                return this.providerCatalogSession.handleProviderUsageListRequest(msg);
+            default:
+                return undefined;
+        }
+    }
+    dispatchTerminalMessage(msg) {
+        if (msg.type === "start_workspace_script_request") {
+            return this.handleStartWorkspaceScriptRequest(msg);
+        }
+        return this.terminalController.dispatch(msg);
+    }
+    // eslint-disable-next-line complexity
+    dispatchChatScheduleLoopMessage(msg) {
+        switch (msg.type) {
+            case "chat/create":
+                return this.chatScheduleLoopSession.handleChatCreateRequest(msg);
+            case "chat/list":
+                return this.chatScheduleLoopSession.handleChatListRequest(msg);
+            case "chat/inspect":
+                return this.chatScheduleLoopSession.handleChatInspectRequest(msg);
+            case "chat/delete":
+                return this.chatScheduleLoopSession.handleChatDeleteRequest(msg);
+            case "chat/post":
+                return this.chatScheduleLoopSession.handleChatPostRequest(msg);
+            case "chat/read":
+                return this.chatScheduleLoopSession.handleChatReadRequest(msg);
+            case "chat/wait":
+                return this.chatScheduleLoopSession.handleChatWaitRequest(msg);
+            case "loop/run":
+                return this.chatScheduleLoopSession.handleLoopRunRequest(msg);
+            case "loop/list":
+                return this.chatScheduleLoopSession.handleLoopListRequest(msg);
+            case "loop/inspect":
+                return this.chatScheduleLoopSession.handleLoopInspectRequest(msg);
+            case "loop/logs":
+                return this.chatScheduleLoopSession.handleLoopLogsRequest(msg);
+            case "loop/stop":
+                return this.chatScheduleLoopSession.handleLoopStopRequest(msg);
+            case "schedule/create":
+                return this.chatScheduleLoopSession.handleScheduleCreateRequest(msg);
+            case "schedule/list":
+                return this.chatScheduleLoopSession.handleScheduleListRequest(msg);
+            case "schedule/inspect":
+                return this.chatScheduleLoopSession.handleScheduleInspectRequest(msg);
+            case "schedule/logs":
+                return this.chatScheduleLoopSession.handleScheduleLogsRequest(msg);
+            case "schedule/pause":
+                return this.chatScheduleLoopSession.handleSchedulePauseRequest(msg);
+            case "schedule/resume":
+                return this.chatScheduleLoopSession.handleScheduleResumeRequest(msg);
+            case "schedule/delete":
+                return this.chatScheduleLoopSession.handleScheduleDeleteRequest(msg);
+            case "schedule/run-once":
+                return this.chatScheduleLoopSession.handleScheduleRunOnceRequest(msg);
+            case "schedule/update":
+                return this.chatScheduleLoopSession.handleScheduleUpdateRequest(msg);
+            default:
+                return undefined;
+        }
+    }
+    dispatchArtifactMessage(msg) {
+        switch (msg.type) {
+            case "artifact.list.request":
+                return this.artifactSession.handleArtifactListRequest(msg);
+            case "artifact.create.request":
+                return this.artifactSession.handleArtifactCreateRequest(msg);
+            case "artifact.update.request":
+                return this.artifactSession.handleArtifactUpdateRequest(msg);
+            case "artifact.regenerate.request":
+                return this.artifactSession.handleArtifactRegenerateRequest(msg);
+            case "artifact.cancel.request":
+                return this.artifactSession.handleArtifactCancelRequest(msg);
+            case "artifact.delete.request":
+                return this.artifactSession.handleArtifactDeleteRequest(msg);
+            case "artifact.star.request":
+                return this.artifactSession.handleArtifactStarRequest(msg);
+            case "artifact.get-content.request":
+                return this.artifactSession.handleArtifactGetContentRequest(msg);
+            default:
+                return undefined;
+        }
+    }
+    async dispatchMiscMessage(msg) {
+        switch (msg.type) {
+            case "list_commands_request":
+                await this.handleListCommandsRequest(msg);
+                return;
+            case "agent.context.get_usage.request":
+                await this.handleAgentContextGetUsageRequest(msg);
+                return;
+            case "register_push_token":
+                this.handleRegisterPushToken(msg.token);
+                return;
+        }
+    }
+    resetPeakInflight() {
+        this.peakInflightRequests = this.inflightRequests;
+    }
+    getSessionId() {
+        return this.sessionId;
+    }
+    async handleBinaryFrame(binaryFrame) {
+        if (binaryFrame.kind === "file_transfer") {
+            await this.workspaceFilesSession.handleFileTransferFrame(binaryFrame.frame);
+            return;
+        }
+        this.terminalController.handleBinaryFrame(binaryFrame.frame);
+    }
+    async handleRestartServerRequest(requestId, reason) {
+        const lifecycleReason = normalizeClientRestartRpcReason(reason);
+        const payload = {
+            status: "restart_requested",
+            clientId: this.clientId,
+        };
+        if (reason && reason.trim().length > 0) {
+            payload.reason = reason;
+        }
+        payload.requestId = requestId;
+        this.sessionLogger.warn({ reason: lifecycleReason }, "Restart requested via websocket");
+        this.emit({
+            type: "status",
+            payload,
+        });
+        this.emitLifecycleIntent({
+            type: "restart",
+            clientId: this.clientId,
+            requestId,
+            reason: lifecycleReason,
+        });
+    }
+    async handleShutdownServerRequest(requestId) {
+        const reason = CLIENT_SHUTDOWN_RPC_REASON;
+        this.sessionLogger.warn({ reason }, "Shutdown requested via websocket");
+        this.emit({
+            type: "status",
+            payload: {
+                status: "shutdown_requested",
+                clientId: this.clientId,
+                requestId,
+            },
+        });
+        this.emitLifecycleIntent({
+            type: "shutdown",
+            clientId: this.clientId,
+            requestId,
+            reason,
+        });
+    }
+    emitLifecycleIntent(intent) {
+        if (!this.onLifecycleIntent) {
+            return;
+        }
+        try {
+            this.onLifecycleIntent(intent);
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, intent }, "Lifecycle intent handler failed");
+        }
+    }
+    async handleDeleteAgentRequest(agentId, requestId) {
+        this.sessionLogger.info({ agentId }, `Deleting agent ${agentId} from registry`);
+        const knownWorkspaceId = this.agentManager.getAgent(agentId)?.workspaceId ??
+            (await this.agentStorage.get(agentId))?.workspaceId ??
+            null;
+        // File-backed storage still needs an early delete fence before closeAgent().
+        beginAgentDeleteIfSupported(this.agentStorage, agentId);
+        try {
+            await closeAgentCommand({ agentManager: this.agentManager }, agentId);
+        }
+        catch (error) {
+            this.sessionLogger.warn({ err: error, agentId }, `Failed to close agent ${agentId} during delete`);
+        }
+        // Drain queued persistence from the just-closed agent before removing its
+        // durable snapshot, otherwise an in-flight background write can recreate it.
+        await this.agentManager.flush();
+        try {
+            await this.agentStorage.remove(agentId);
+            await this.agentManager.deleteCommittedTimeline(agentId);
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, agentId }, `Failed to fully delete agent ${agentId}`);
+        }
+        this.emit({
+            type: "agent_deleted",
+            payload: {
+                agentId,
+                requestId,
+            },
+        });
+        this.agentUpdates.removeAgent(agentId);
+        if (knownWorkspaceId) {
+            await this.emitWorkspaceUpdateForWorkspaceId(knownWorkspaceId);
+        }
+    }
+    async handleArchiveAgentRequest(agentId, requestId) {
+        this.sessionLogger.info({ agentId }, `Archiving agent ${agentId}`);
+        const { archivedAt } = await this.archiveAgentForClose(agentId);
+        this.emit({
+            type: "agent_archived",
+            payload: {
+                agentId,
+                archivedAt,
+                requestId,
+            },
+        });
+    }
+    async archiveAgentForClose(agentId) {
+        const { archivedAt, record: archivedRecord } = await archiveAgentCommand({
+            agentManager: this.agentManager,
+            agentStorage: this.agentStorage,
+            logger: this.sessionLogger,
+        }, agentId);
+        if (this.agentUpdates.hasSubscription()) {
+            const payload = await this.agentUpdates.emitStoredRecord(archivedRecord);
+            if (payload.workspaceId) {
+                await this.emitWorkspaceUpdateForWorkspaceId(payload.workspaceId);
+            }
+        }
+        return { agentId, archivedAt };
+    }
+    async handleDetachAgentRequest(agentId, requestId) {
+        this.sessionLogger.info({ agentId, requestId }, "Detaching agent from parent");
+        try {
+            const result = await detachAgentCommand({ agentManager: this.agentManager }, agentId);
+            const affectedWorkspaceIds = new Set();
+            if (!result.live) {
+                const payload = await this.agentUpdates.emitStoredRecord(result.record);
+                if (payload.workspaceId) {
+                    affectedWorkspaceIds.add(payload.workspaceId);
+                }
+            }
+            else if (result.record.workspaceId) {
+                affectedWorkspaceIds.add(result.record.workspaceId);
+            }
+            if (result.previousParentAgentId) {
+                const rootWorkspaceId = await this.resolveDelegationRootWorkspaceId(result.previousParentAgentId);
+                if (rootWorkspaceId) {
+                    affectedWorkspaceIds.add(rootWorkspaceId);
+                }
+            }
+            await this.emitWorkspaceUpdatesForWorkspaceIds(affectedWorkspaceIds, {
+                skipReconcile: true,
+            });
+            this.emit({
+                type: "agent.detach.response",
+                payload: {
+                    requestId,
+                    agentId,
+                    accepted: true,
+                    error: null,
+                },
+            });
+        }
+        catch (error) {
+            const message = getErrorMessageOr(error, "Failed to detach agent");
+            this.sessionLogger.error({ err: error, agentId, requestId }, "Failed to detach agent");
+            this.emit({
+                type: "agent.detach.response",
+                payload: {
+                    requestId,
+                    agentId,
+                    accepted: false,
+                    error: message,
+                },
+            });
+        }
+    }
+    async handleCloseItemsRequest(msg) {
+        const archiveResults = await Promise.allSettled(msg.agentIds.map((agentId) => this.archiveAgentForClose(agentId)));
+        const agents = [];
+        for (let i = 0; i < archiveResults.length; i += 1) {
+            const result = archiveResults[i];
+            if (result.status === "fulfilled") {
+                agents.push(result.value);
+            }
+            else {
+                this.sessionLogger.warn({ err: result.reason, agentId: msg.agentIds[i], requestId: msg.requestId }, "Failed to archive agent during close_items batch");
+            }
+        }
+        const terminals = [];
+        for (const terminalId of msg.terminalIds) {
+            try {
+                terminals.push(this.terminalController.killTerminalForClose(terminalId));
+            }
+            catch (error) {
+                this.sessionLogger.warn({ err: error, terminalId, requestId: msg.requestId }, "Failed to kill terminal during close_items batch");
+                terminals.push({
+                    terminalId,
+                    success: false,
+                });
+            }
+        }
+        this.emit({
+            type: "close_items_response",
+            payload: {
+                agents,
+                terminals,
+                requestId: msg.requestId,
+            },
+        });
+    }
+    async unarchiveAgentByHandle(handle) {
+        const records = await this.agentStorage.list();
+        const matched = records.find((record) => record.persistence?.provider === handle.provider &&
+            record.persistence?.sessionId === handle.sessionId);
+        if (!matched) {
+            return;
+        }
+        await unarchiveAgentState(this.agentStorage, this.agentManager, matched.id);
+    }
+    async handleUpdateAgentRequest(agentId, name, labels, requestId) {
+        this.sessionLogger.info({
+            agentId,
+            requestId,
+            hasName: typeof name === "string",
+            labelCount: labels ? Object.keys(labels).length : 0,
+        }, "session: update_agent_request");
+        try {
+            const result = await updateAgentCommand({ agentManager: this.agentManager }, { agentId, name, labels });
+            if (!result.accepted) {
+                this.emit({
+                    type: "update_agent_response",
+                    payload: {
+                        requestId,
+                        agentId,
+                        accepted: false,
+                        error: result.error,
+                    },
+                });
+                return;
+            }
+            this.emit({
+                type: "update_agent_response",
+                payload: { requestId, agentId, accepted: true, error: null },
+            });
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, agentId, requestId }, "session: update_agent_request error");
+            this.emit({
+                type: "activity_log",
+                payload: {
+                    id: uuidv4(),
+                    timestamp: new Date(),
+                    type: "error",
+                    content: `Failed to update agent: ${getErrorMessage(error)}`,
+                },
+            });
+            this.emit({
+                type: "update_agent_response",
+                payload: {
+                    requestId,
+                    agentId,
+                    accepted: false,
+                    error: getErrorMessageOr(error, "Failed to update agent"),
+                },
+            });
+        }
+    }
+    async handleProjectRenameRequest(projectId, customName, requestId) {
+        this.sessionLogger.info({ projectId, requestId, hasCustomName: typeof customName === "string" }, "session: project.rename.request");
+        try {
+            const existing = await this.projectRegistry.get(projectId);
+            if (!existing) {
+                this.emit({
+                    type: "project.rename.response",
+                    payload: {
+                        requestId,
+                        projectId,
+                        accepted: false,
+                        customName: null,
+                        error: "Project not found",
+                    },
+                });
+                return;
+            }
+            const trimmed = customName?.trim() ?? "";
+            const nextCustomName = trimmed.length === 0 ? null : trimmed;
+            await this.projectRegistry.upsert({
+                ...existing,
+                customName: nextCustomName,
+                updatedAt: new Date().toISOString(),
+            });
+            this.emit({
+                type: "project.rename.response",
+                payload: {
+                    requestId,
+                    projectId,
+                    accepted: true,
+                    customName: nextCustomName,
+                    error: null,
+                },
+            });
+            // Re-emit descriptors for every workspace under this project so the new
+            // resolved name lands in the UI immediately.
+            const workspaces = await this.workspaceRegistry.list();
+            const affectedWorkspaceIds = workspaces
+                .filter((workspace) => workspace.projectId === projectId)
+                .map((workspace) => workspace.workspaceId);
+            if (affectedWorkspaceIds.length > 0) {
+                await this.emitWorkspaceUpdatesForWorkspaceIds(affectedWorkspaceIds, {
+                    skipReconcile: true,
+                });
+            }
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, projectId, requestId }, "session: project.rename.request error");
+            this.emit({
+                type: "activity_log",
+                payload: {
+                    id: uuidv4(),
+                    timestamp: new Date(),
+                    type: "error",
+                    content: `Failed to rename project: ${getErrorMessage(error)}`,
+                },
+            });
+            this.emit({
+                type: "project.rename.response",
+                payload: {
+                    requestId,
+                    projectId,
+                    accepted: false,
+                    customName: null,
+                    error: getErrorMessageOr(error, "Failed to rename project"),
+                },
+            });
+        }
+    }
+    async handleProjectRemoveRequest(request) {
+        const { projectId, requestId } = request;
+        this.sessionLogger.info({ projectId, requestId }, "session: project.remove.request");
+        try {
+            const projectWorkspaces = (await this.workspaceRegistry.list()).filter((workspace) => workspace.projectId === projectId);
+            const activeWorkspaceIds = projectWorkspaces
+                .filter((workspace) => !workspace.archivedAt)
+                .map((workspace) => workspace.workspaceId);
+            if (activeWorkspaceIds.length > 0) {
+                this.markWorkspaceArchiving(activeWorkspaceIds, new Date().toISOString());
+                await this.emitWorkspaceUpdatesForWorkspaceIds(activeWorkspaceIds, {
+                    skipReconcile: true,
+                });
+            }
+            const removedWorkspaceIds = [];
+            try {
+                for (const workspaceId of activeWorkspaceIds) {
+                    await archiveWorkspaceContents({
+                        agentManager: this.agentManager,
+                        agentStorage: this.agentStorage,
+                        killTerminalsForWorkspace: (id) => this.terminalController.killTerminalsForWorkspace(id),
+                        sessionLogger: this.sessionLogger,
+                    }, workspaceId);
+                    await this.archiveWorkspaceRecord(workspaceId);
+                    removedWorkspaceIds.push(workspaceId);
+                }
+                await this.projectRegistry.remove(projectId);
+            }
+            finally {
+                if (activeWorkspaceIds.length > 0) {
+                    this.clearWorkspaceArchiving(activeWorkspaceIds);
+                }
+            }
+            const updateIds = removedWorkspaceIds.length > 0
+                ? removedWorkspaceIds
+                : [projectWorkspaces[0]?.workspaceId ?? projectId];
+            await this.emitWorkspaceUpdatesForWorkspaceIds(updateIds, {
+                skipReconcile: true,
+                removedProjectId: projectId,
+            });
+            this.emit({
+                type: "project.remove.response",
+                payload: {
+                    requestId,
+                    projectId,
+                    accepted: true,
+                    removedWorkspaceIds,
+                    error: null,
+                },
+            });
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, projectId, requestId }, "session: project.remove.request error");
+            this.emit({
+                type: "activity_log",
+                payload: {
+                    id: uuidv4(),
+                    timestamp: new Date(),
+                    type: "error",
+                    content: `Failed to remove project: ${getErrorMessage(error)}`,
+                },
+            });
+            this.emit({
+                type: "project.remove.response",
+                payload: {
+                    requestId,
+                    projectId,
+                    accepted: false,
+                    removedWorkspaceIds: [],
+                    error: getErrorMessageOr(error, "Failed to remove project"),
+                },
+            });
+        }
+    }
+    async handleWorkspaceTitleSetRequest(workspaceId, title, requestId) {
+        this.sessionLogger.info({ workspaceId, requestId, hasTitle: typeof title === "string" }, "session: workspace.title.set.request");
+        try {
+            const existing = await this.workspaceRegistry.get(workspaceId);
+            if (!existing) {
+                this.emit({
+                    type: "workspace.title.set.response",
+                    payload: {
+                        requestId,
+                        workspaceId,
+                        accepted: false,
+                        title: null,
+                        error: "Workspace not found",
+                    },
+                });
+                return;
+            }
+            const trimmed = title?.trim() ?? "";
+            const nextTitle = trimmed.length === 0 ? null : trimmed;
+            await this.workspaceRegistry.upsert({
+                ...existing,
+                title: nextTitle,
+                updatedAt: new Date().toISOString(),
+            });
+            this.emit({
+                type: "workspace.title.set.response",
+                payload: {
+                    requestId,
+                    workspaceId,
+                    accepted: true,
+                    title: nextTitle,
+                    error: null,
+                },
+            });
+            await this.emitWorkspaceUpdatesForWorkspaceIds([workspaceId], {
+                skipReconcile: true,
+            });
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, workspaceId, requestId }, "session: workspace.title.set.request error");
+            this.emit({
+                type: "activity_log",
+                payload: {
+                    id: uuidv4(),
+                    timestamp: new Date(),
+                    type: "error",
+                    content: `Failed to set workspace title: ${getErrorMessage(error)}`,
+                },
+            });
+            this.emit({
+                type: "workspace.title.set.response",
+                payload: {
+                    requestId,
+                    workspaceId,
+                    accepted: false,
+                    title: null,
+                    error: getErrorMessageOr(error, "Failed to set workspace title"),
+                },
+            });
+        }
+    }
+    /**
+     * UI-initiated preview RPCs behind the Preview toolbar button. Mirrors what
+     * the agent-facing preview_* tools do (packages/server/src/server/preview/preview-tools.ts)
+     * but is driven by the app directly instead of an agent tool call — the
+     * caller creates and places the browser tab itself, then reports the
+     * binding back via preview.bind_tab so a later agent preview_start call
+     * finds the same designated tab.
+     */
+    async handlePreviewListConfigRequest(cwd, requestId) {
+        try {
+            const config = await readLaunchConfig(cwd);
+            // Collect running servers from DevServerManager
+            let runningServers = [];
+            if (this.previewDevServers) {
+                // Reconcile against reality (port probes), not just the in-memory map:
+                // the map is wiped on daemon restart while the detached dev-server child
+                // keeps serving, so a plain list() would report a live preview as "not
+                // started" after every tsx-watch restart in dev. See reconcileRunning.
+                const reconciled = await this.previewDevServers.reconcileRunning({
+                    cwd,
+                    configured: config?.configurations.map((entry) => ({
+                        name: entry.name,
+                        port: entry.port,
+                    })) ?? [],
+                });
+                runningServers = reconciled.map((s) => ({
+                    serverId: s.serverId,
+                    name: s.name,
+                    url: s.url,
+                    port: s.port,
+                    status: s.status,
+                }));
+            }
+            this.emit({
+                type: "preview.list_config.response",
+                payload: {
+                    requestId,
+                    cwd,
+                    configured: config !== null,
+                    servers: config?.configurations.map((entry) => ({ name: entry.name, port: entry.port })) ?? [],
+                    runningServers,
+                    error: null,
+                },
+            });
+        }
+        catch (error) {
+            this.emit({
+                type: "preview.list_config.response",
+                payload: {
+                    requestId,
+                    cwd,
+                    configured: false,
+                    servers: [],
+                    error: error instanceof LaunchConfigError ? error.message : getErrorMessage(error),
+                },
+            });
+        }
+    }
+    async handlePreviewStartRequest(cwd, name, requestId) {
+        if (!this.previewDevServers) {
+            this.emit({
+                type: "preview.start.response",
+                payload: {
+                    requestId,
+                    cwd,
+                    success: false,
+                    server: null,
+                    reused: false,
+                    error: "Preview servers are disabled on this daemon.",
+                },
+            });
+            return;
+        }
+        try {
+            const started = await this.previewDevServers.start({ cwd, name });
+            this.emit({
+                type: "preview.start.response",
+                payload: {
+                    requestId,
+                    cwd,
+                    success: true,
+                    reused: started.reused,
+                    server: {
+                        serverId: started.server.serverId,
+                        name: started.server.name,
+                        url: started.server.url,
+                        port: started.server.port,
+                        status: started.server.status,
+                        boundBrowserId: started.server.boundBrowserId,
+                    },
+                    error: null,
+                },
+            });
+        }
+        catch (error) {
+            this.emit({
+                type: "preview.start.response",
+                payload: {
+                    requestId,
+                    cwd,
+                    success: false,
+                    server: null,
+                    reused: false,
+                    error: getErrorMessage(error),
+                },
+            });
+        }
+    }
+    async handlePreviewBindTabRequest(serverId, browserId, requestId) {
+        if (!this.previewDevServers) {
+            this.emit({
+                type: "preview.bind_tab.response",
+                payload: {
+                    requestId,
+                    success: false,
+                    error: "Preview servers are disabled on this daemon.",
+                },
+            });
+            return;
+        }
+        try {
+            this.previewDevServers.bindTab(serverId, browserId);
+            this.emit({
+                type: "preview.bind_tab.response",
+                payload: { requestId, success: true, error: null },
+            });
+        }
+        catch (error) {
+            this.emit({
+                type: "preview.bind_tab.response",
+                payload: { requestId, success: false, error: getErrorMessage(error) },
+            });
+        }
+    }
+    async handlePreviewStopRequest(serverId, requestId) {
+        if (!this.previewDevServers) {
+            this.emit({
+                type: "preview.stop.response",
+                payload: {
+                    requestId,
+                    success: false,
+                    error: "Preview servers are disabled on this daemon.",
+                },
+            });
+            return;
+        }
+        try {
+            await this.previewDevServers.stop(serverId);
+            this.emit({
+                type: "preview.stop.response",
+                payload: { requestId, success: true, error: null },
+            });
+        }
+        catch (error) {
+            this.emit({
+                type: "preview.stop.response",
+                payload: { requestId, success: false, error: getErrorMessage(error) },
+            });
+        }
+    }
+    /**
+     * Handle text message to agent (with optional image attachments)
+     */
+    async handleSendAgentMessage(agentId, text, messageId, images, attachments, runOptions, options) {
+        this.sessionLogger.info({
+            agentId,
+            textPreview: text.substring(0, 50),
+            imageCount: images?.length ?? 0,
+            attachmentCount: attachments?.length ?? 0,
+        }, `Sending text to agent ${agentId}${images && images.length > 0 ? ` with ${images.length} image attachment(s)` : ""}${attachments && attachments.length > 0
+            ? ` and ${attachments.length} structured attachment(s)`
+            : ""}`);
+        const promptText = options?.spokenInput ? wrapSpokenInput(text) : text;
+        const prompt = this.buildAgentPrompt(promptText, images, attachments);
+        try {
+            await sendPromptToAgent({
+                agentManager: this.agentManager,
+                agentStorage: this.agentStorage,
+                agentId,
+                prompt,
+                messageId,
+                runOptions,
+                logger: this.sessionLogger,
+            });
+            return { ok: true };
+        }
+        catch (error) {
+            this.handleAgentRunError(agentId, error, "Failed to send agent message");
+            return {
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    /**
+     * Handle create agent request
+     */
+    /**
+     * Resolve an optional personality id against the roster + this cwd's provider
+     * snapshot and fold its identity onto the create config. Availability is
+     * re-checked here (the cwd may differ from where the picker resolved it); an
+     * unavailable or unknown personality is skipped with a warning rather than
+     * failing the create — the agent still runs with the chosen brain, just
+     * without personality identity. The brain fields are never overridden; only
+     * `personalitySnapshot` and (when the caller set none) `systemPrompt` are added.
+     */
+    async applyPersonalityIdentityToConfig(config, personalityId) {
+        if (!personalityId) {
+            return config;
+        }
+        const roster = this.daemonConfigStore.get().agentPersonalities?.personalities ?? [];
+        const personality = roster.find((entry) => entry.id === personalityId);
+        if (!personality) {
+            this.sessionLogger.warn({ personalityId }, "create_agent: personality id not found in roster; spawning without personality identity");
+            return config;
+        }
+        const entries = await this.providerSnapshotManager.listProviders({
+            cwd: config.cwd,
+            wait: true,
+        });
+        const resolution = resolvePersonality(personality, entries);
+        if (resolution.status === "unavailable") {
+            this.sessionLogger.warn({ personalityId, reason: resolution.reason }, "create_agent: personality unavailable for cwd; spawning without personality identity");
+            return config;
+        }
+        const snapshot = resolution.snapshot;
+        return {
+            ...config,
+            personalitySnapshot: snapshot,
+            ...(config.systemPrompt === undefined && snapshot.systemPrompt !== undefined
+                ? { systemPrompt: snapshot.systemPrompt }
+                : {}),
+        };
+    }
+    /**
+     * Resolve a roster personality against a *running* agent's cwd for a live
+     * switch (agent.personality.set). Unlike the spawn-time soft-skip above, an
+     * unknown or unavailable personality throws — the RPC rejects with the reason
+     * instead of half-applying.
+     */
+    async resolvePersonalitySnapshotForAgent(agentId, personalityId) {
+        const agent = this.agentManager.getAgent(agentId);
+        if (!agent) {
+            throw new Error(`Agent not found: ${agentId}`);
+        }
+        const roster = this.daemonConfigStore.get().agentPersonalities?.personalities ?? [];
+        const personality = roster.find((entry) => entry.id === personalityId);
+        if (!personality) {
+            throw new Error(`Personality not found: ${personalityId}`);
+        }
+        // Warm only the personality's own provider — a cold workspace snapshot
+        // would otherwise fan out to every registered provider (network probes)
+        // and stall the switch for seconds.
+        const entries = await this.providerSnapshotManager.listProviders({
+            cwd: agent.config.cwd,
+            providers: [personality.provider],
+            wait: true,
+        });
+        const resolution = resolvePersonality(personality, entries);
+        if (resolution.status === "unavailable") {
+            throw new Error(resolution.reason);
+        }
+        return resolution.snapshot;
+    }
+    async handleCreateAgentRequest(msg) {
+        const { config, personality, worktreeName, requestId, initialPrompt, clientMessageId, outputSchema, git, worktree, autoArchive, images, attachments, labels, env, } = msg;
+        this.sessionLogger.info({ cwd: config.cwd, provider: config.provider, worktreeName }, `Creating agent in ${config.cwd} (${config.provider})${worktreeName ? ` with worktree ${worktreeName}` : ""}`);
+        let createdWorktreeForCleanup = null;
+        let createdAgentId = null;
+        try {
+            const trimmedPrompt = initialPrompt?.trim();
+            const { provisionalTitle } = resolveCreateAgentTitles({
+                configTitle: config.title,
+                initialPrompt: trimmedPrompt,
+            });
+            const firstAgentContext = {
+                ...(trimmedPrompt ? { prompt: trimmedPrompt } : {}),
+                ...(attachments && attachments.length > 0 ? { attachments } : {}),
+            };
+            const workspacePromptTitle = resolveFirstAgentPromptTitle(firstAgentContext);
+            const createdWorktree = await this.createAgentLifecycleDispatch.createWorktreeForRequest({
+                cwd: config.cwd,
+                target: worktree,
+                firstAgentContext,
+                hasLegacyGitOptions: Boolean(git),
+            });
+            createdWorktreeForCleanup = createdWorktree;
+            const baseCreateAgentConfig = createdWorktree
+                ? { ...config, cwd: createdWorktree.worktree.worktreePath }
+                : config;
+            // A composer-selected personality arrives by id; resolve it against the
+            // (possibly worktree) cwd and snapshot its identity onto the agent so the
+            // live spinner, voice, and prompt read as that personality. The brain in
+            // `config` (provider/model/mode/effort) is authoritative — hand-deviations
+            // in the picker keep the identity but override the settings.
+            const createAgentConfig = await this.applyPersonalityIdentityToConfig(baseCreateAgentConfig, personality);
+            const workspaceId = await this.workspaceProvisioning.resolveOrCreateWorkspaceIdForCreateAgent({
+                createdWorktree,
+                requestedWorkspaceId: msg.workspaceId,
+                cwd: createAgentConfig.cwd,
+                initialTitle: workspacePromptTitle,
+            });
+            const createdDirectoryWorkspaceForAgent = !createdWorktree && !msg.workspaceId;
+            const { snapshot, liveSnapshot } = await createAgentCommand({
+                agentManager: this.agentManager,
+                agentStorage: this.agentStorage,
+                logger: this.sessionLogger,
+                ottoHome: this.ottoHome,
+                worktreesRoot: this.worktreesRoot,
+                providerSnapshotManager: this.providerSnapshotManager,
+            }, {
+                kind: "session",
+                config: createAgentConfig,
+                workspaceId,
+                worktreeName,
+                initialPrompt,
+                clientMessageId,
+                outputSchema,
+                images,
+                attachments,
+                git,
+                labels,
+                env,
+                provisionalTitle,
+                firstAgentContext,
+                buildSessionConfig: (sessionConfig, gitOptions, legacyWorktreeName, ctx) => this.buildAgentSessionConfig(sessionConfig, gitOptions, legacyWorktreeName, ctx),
+            });
+            createdAgentId = snapshot.id;
+            await this.agentUpdates.forwardLiveAgent(snapshot);
+            if (createdDirectoryWorkspaceForAgent && trimmedPrompt) {
+                this.workspaceAutoName.scheduleForDirectory({
+                    workspaceId,
+                    cwd: createAgentConfig.cwd,
+                    firstAgentContext,
+                }, { currentSelection: this.getFocusedAgentSelectionForCwd(createAgentConfig.cwd) });
+            }
+            this.createAgentLifecycleDispatch.registerAutoArchiveIfRequested({
+                autoArchive,
+                agentId: snapshot.id,
+                createdWorktree,
+            });
+            if (requestId) {
+                const agentPayload = await this.buildAgentPayload(liveSnapshot);
+                this.emit({
+                    type: "status",
+                    payload: {
+                        status: "agent_created",
+                        agentId: liveSnapshot.id,
+                        requestId,
+                        agent: agentPayload,
+                    },
+                });
+            }
+            this.sessionLogger.info({ agentId: snapshot.id, provider: snapshot.provider }, `Created agent ${snapshot.id} (${snapshot.provider})`);
+        }
+        catch (error) {
+            await this.createAgentLifecycleDispatch.cleanupCreatedWorktreeAfterFailedAgentCreate({
+                createdWorktree: createdWorktreeForCleanup,
+                createdAgentId,
+            });
+            const wireError = toWorktreeWireError(error);
+            this.sessionLogger.error({ err: error }, "Failed to create agent");
+            if (requestId) {
+                this.emit({
+                    type: "status",
+                    payload: {
+                        status: "agent_create_failed",
+                        requestId,
+                        error: wireError.message,
+                        errorCode: wireError.code,
+                    },
+                });
+            }
+            this.emit({
+                type: "activity_log",
+                payload: {
+                    id: uuidv4(),
+                    timestamp: new Date(),
+                    type: "error",
+                    content: `Failed to create agent: ${wireError.message}`,
+                },
+            });
+        }
+    }
+    async handleResumeAgentRequest(msg) {
+        const { handle, overrides, requestId } = msg;
+        if (!handle) {
+            this.sessionLogger.warn("Resume request missing persistence handle");
+            if (requestId) {
+                this.emit({
+                    type: "rpc_error",
+                    payload: {
+                        requestId,
+                        requestType: msg.type,
+                        error: "Unable to resume agent: missing persistence handle",
+                        code: "agent_resume_failed",
+                    },
+                });
+            }
+            this.emit({
+                type: "activity_log",
+                payload: {
+                    id: uuidv4(),
+                    timestamp: new Date(),
+                    type: "error",
+                    content: "Unable to resume agent: missing persistence handle",
+                },
+            });
+            return;
+        }
+        this.sessionLogger.info({ sessionId: handle.sessionId, provider: handle.provider }, `Resuming agent ${handle.sessionId} (${handle.provider})`);
+        try {
+            await this.unarchiveAgentByHandle(handle);
+            const snapshot = await this.agentManager.resumeAgentFromPersistence(handle, overrides);
+            await unarchiveAgentState(this.agentStorage, this.agentManager, snapshot.id);
+            await this.agentManager.hydrateTimelineFromProvider(snapshot.id);
+            await this.agentUpdates.forwardLiveAgent(snapshot);
+            const timelineSize = this.agentManager.getTimeline(snapshot.id).length;
+            if (requestId) {
+                const agentPayload = await this.buildAgentPayload(snapshot);
+                this.emit({
+                    type: "status",
+                    payload: {
+                        status: "agent_resumed",
+                        agentId: snapshot.id,
+                        requestId,
+                        timelineSize,
+                        agent: agentPayload,
+                    },
+                });
+            }
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            this.sessionLogger.error({ err: error }, "Failed to resume agent");
+            if (requestId) {
+                this.emit({
+                    type: "rpc_error",
+                    payload: {
+                        requestId,
+                        requestType: msg.type,
+                        error: message,
+                        code: "agent_resume_failed",
+                    },
+                });
+            }
+            this.emit({
+                type: "activity_log",
+                payload: {
+                    id: uuidv4(),
+                    timestamp: new Date(),
+                    type: "error",
+                    content: `Failed to resume agent: ${message}`,
+                },
+            });
+        }
+    }
+    async handleImportAgentRequest(msg) {
+        const normalized = normalizeImportAgentRequest(msg);
+        if ("error" in normalized) {
+            this.emit({
+                type: "status",
+                payload: {
+                    status: "agent_create_failed",
+                    requestId: msg.requestId,
+                    error: normalized.error,
+                },
+            });
+            return;
+        }
+        const { provider, providerHandleId, requestId } = normalized;
+        this.sessionLogger.info({ providerHandleId, provider }, `Importing agent ${providerHandleId} (${provider})`);
+        try {
+            if (!normalized.cwd) {
+                throw new Error("Import requires cwd from the selected provider session");
+            }
+            // An imported agent mints its own workspace; ownership is its workspaceId,
+            // never an existing same-cwd workspace resolved by path.
+            const workspace = await this.workspaceProvisioning.createWorkspaceForDirectory(normalized.cwd);
+            const { snapshot, timelineSize } = await importProviderSession({
+                request: normalized,
+                workspaceId: workspace.workspaceId,
+                agentManager: this.agentManager,
+                agentStorage: this.agentStorage,
+                logger: this.sessionLogger,
+            });
+            await this.registerWorkspaceForImportedAgent(workspace);
+            const agentPayload = await this.buildAgentPayload(snapshot);
+            this.emit({
+                type: "status",
+                payload: {
+                    status: "agent_resumed",
+                    agentId: snapshot.id,
+                    requestId,
+                    timelineSize,
+                    agent: agentPayload,
+                },
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.sessionLogger.error({ err: error }, "Failed to import agent");
+            this.emit({
+                type: "status",
+                payload: {
+                    status: "agent_create_failed",
+                    requestId,
+                    error: message,
+                },
+            });
+            this.emit({
+                type: "activity_log",
+                payload: {
+                    id: uuidv4(),
+                    timestamp: new Date(),
+                    type: "error",
+                    content: `Failed to import agent: ${message}`,
+                },
+            });
+        }
+    }
+    async handleRefreshAgentRequest(msg) {
+        const { agentId, requestId } = msg;
+        this.sessionLogger.info({ agentId }, `Refreshing agent ${agentId} from persistence`);
+        try {
+            await unarchiveAgentState(this.agentStorage, this.agentManager, agentId);
+            await this.unarchiveOwningWorkspaceForAgent(agentId);
+            let snapshot;
+            const existing = this.agentManager.getAgent(agentId);
+            if (existing) {
+                await this.interruptAgentIfRunning(agentId);
+                snapshot = await this.agentManager.reloadAgentSession(agentId, undefined, {
+                    rehydrateFromDisk: true,
+                });
+            }
+            else {
+                const record = await this.agentStorage.get(agentId);
+                if (!record) {
+                    throw new Error(`Agent not found: ${agentId}`);
+                }
+                const registeredProviderIds = this.providerSnapshotManager.listRegisteredProviderIds();
+                if (!isStoredAgentProviderAvailable(record, registeredProviderIds)) {
+                    throw new Error(`Agent ${agentId} references unavailable provider '${record.provider}'`);
+                }
+                const handle = toAgentPersistenceHandle(registeredProviderIds, record.persistence);
+                if (!handle) {
+                    throw new Error(`Agent ${agentId} cannot be refreshed because it lacks persistence`);
+                }
+                snapshot = await this.agentManager.resumeAgentFromPersistence(handle, buildConfigOverrides(record), agentId, extractTimestamps(record));
+            }
+            await this.agentManager.hydrateTimelineFromProvider(agentId);
+            await this.agentUpdates.forwardLiveAgent(snapshot);
+            const timelineSize = this.agentManager.getTimeline(agentId).length;
+            if (requestId) {
+                this.emit({
+                    type: "status",
+                    payload: {
+                        status: "agent_refreshed",
+                        agentId,
+                        requestId,
+                        timelineSize,
+                    },
+                });
+            }
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            this.sessionLogger.error({ err: error, agentId }, `Failed to refresh agent ${agentId}`);
+            if (requestId) {
+                this.emit({
+                    type: "rpc_error",
+                    payload: {
+                        requestId,
+                        requestType: msg.type,
+                        error: message,
+                        code: error instanceof WorktreeRequestError ? error.code : "agent_refresh_failed",
+                    },
+                });
+            }
+            this.emit({
+                type: "activity_log",
+                payload: {
+                    id: uuidv4(),
+                    timestamp: new Date(),
+                    type: "error",
+                    content: `Failed to refresh agent: ${message}`,
+                },
+            });
+        }
+    }
+    async handleCancelAgentRequest(agentId, requestId) {
+        this.sessionLogger.info({ agentId }, `Cancel request received for agent ${agentId}`);
+        try {
+            await cancelAgentRunCommand({ agentManager: this.agentManager, logger: this.sessionLogger }, agentId);
+            if (requestId) {
+                const agent = this.agentManager.getAgent(agentId);
+                const payload = agent ? await this.buildAgentPayload(agent) : null;
+                this.emit({
+                    type: "cancel_agent_response",
+                    payload: {
+                        requestId,
+                        agentId,
+                        agent: payload,
+                    },
+                });
+            }
+        }
+        catch (error) {
+            this.handleAgentRunError(agentId, error, "Failed to cancel running agent on request");
+        }
+    }
+    async handleAgentRewindRequest(msg) {
+        try {
+            await this.agentManager.rewind(msg.agentId, msg.messageId, msg.mode);
+            this.emit({
+                type: "agent.rewind.response",
+                payload: {
+                    requestId: msg.requestId,
+                    agentId: msg.agentId,
+                    ok: true,
+                    error: null,
+                },
+            });
+        }
+        catch (error) {
+            this.emit({
+                type: "agent.rewind.response",
+                payload: {
+                    requestId: msg.requestId,
+                    agentId: msg.agentId,
+                    ok: false,
+                    error: error instanceof Error ? error.message : "Failed to rewind agent",
+                },
+            });
+        }
+    }
+    async buildAgentSessionConfig(config, gitOptions, legacyWorktreeName, firstAgentContext) {
+        return buildWorktreeAgentSessionConfig({
+            ottoHome: this.ottoHome,
+            worktreesRoot: this.worktreesRoot,
+            sessionLogger: this.sessionLogger,
+            workspaceGitService: this.workspaceGitService,
+            createOttoWorktree: (input, serviceOptions) => this.createOttoWorktreeWorkflow(input, {
+                ...serviceOptions,
+                setupContinuation: {
+                    kind: "agent",
+                    terminalManager: this.terminalManager,
+                    appendTimelineItem: ({ agentId, item }) => appendTimelineItemIfAgentKnown({
+                        agentManager: this.agentManager,
+                        agentId,
+                        item,
+                    }),
+                    emitLiveTimelineItem: ({ agentId, item }) => emitLiveTimelineItemIfAgentKnown({
+                        agentManager: this.agentManager,
+                        agentId,
+                        item,
+                    }),
+                    logger: this.sessionLogger,
+                },
+            }),
+            checkoutExistingBranch: (cwd, branch) => this.gitMutation.checkoutExistingBranch(cwd, branch),
+            createBranchFromBase: (params) => this.gitMutation.createBranchFromBase(params),
+            github: this.github,
+        }, config, gitOptions, legacyWorktreeName, firstAgentContext);
+    }
+    isPathWithinRoot(rootPath, candidatePath) {
+        const resolvedRoot = resolve(rootPath);
+        const resolvedCandidate = resolve(candidatePath);
+        if (resolvedCandidate === resolvedRoot) {
+            return true;
+        }
+        return resolvedCandidate.startsWith(resolvedRoot + sep);
+    }
+    /**
+     * Handle clearing agent attention flag
+     */
+    async handleClearAgentAttention(agentId, requestId) {
+        const agentIds = Array.isArray(agentId) ? agentId : [agentId];
+        try {
+            await Promise.all(agentIds.map((id) => this.agentManager.clearAgentAttention(id)));
+            if (requestId) {
+                const agents = (await Promise.all(agentIds.map(async (id) => {
+                    const agent = this.agentManager.getAgent(id);
+                    return agent ? this.buildAgentPayload(agent) : null;
+                }))).filter((payload) => payload !== null);
+                this.emit({
+                    type: "clear_agent_attention_response",
+                    payload: {
+                        requestId,
+                        agentId,
+                        agents,
+                    },
+                });
+            }
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, agentIds }, "Failed to clear agent attention");
+            // Don't throw - this is not critical
+        }
+    }
+    /**
+     * Handle client heartbeat for activity tracking
+     */
+    handleClientHeartbeat(msg) {
+        const focusedTerminalId = msg.focusedTerminalId?.trim() || null;
+        const appVisibilityChangedAt = msg.appVisibilityChangedAt
+            ? new Date(msg.appVisibilityChangedAt)
+            : new Date(msg.lastActivityAt);
+        this.clientActivity = {
+            deviceType: msg.deviceType,
+            focusedAgentId: msg.focusedAgentId,
+            focusedTerminalId,
+            lastActivityAt: new Date(msg.lastActivityAt),
+            appVisible: msg.appVisible,
+            appVisibilityChangedAt,
+        };
+        if (msg.appVisible && focusedTerminalId) {
+            void this.clearFocusedTerminalAttention(focusedTerminalId);
+        }
+    }
+    async clearFocusedTerminalAttention(terminalId) {
+        const terminalManager = this.terminalManager;
+        if (!terminalManager) {
+            return;
+        }
+        try {
+            await terminalManager.clearTerminalAttention(terminalId);
+        }
+        catch (error) {
+            this.sessionLogger.warn({ err: error, terminalId }, "Failed to clear terminal attention");
+        }
+    }
+    /**
+     * Handle push token registration
+     */
+    /**
+     * Per-category context window breakdown for the client's context popup.
+     * `usage: null` (not an error) when the agent is gone, its provider doesn't
+     * implement the read, or the provider has no live handle to report from.
+     */
+    async handleAgentContextGetUsageRequest(msg) {
+        const { agentId, requestId } = msg;
+        try {
+            const agent = this.agentManager.listAgents().find((a) => a.id === agentId);
+            const usage = agent?.session?.getContextUsage ? await agent.session.getContextUsage() : null;
+            this.emit({
+                type: "agent.context.get_usage.response",
+                payload: { requestId, agentId, usage },
+            });
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            this.sessionLogger.error({ err, agentId }, "Failed to get agent context usage");
+            this.emit({
+                type: "rpc_error",
+                payload: {
+                    requestId,
+                    requestType: msg.type,
+                    error: `Failed to get agent context usage: ${err.message}`,
+                    code: "agent_context_get_usage_failed",
+                },
+            });
+        }
+    }
+    handleRegisterPushToken(token) {
+        this.pushTokenStore.addToken(token);
+        this.sessionLogger.info("Registered push token");
+    }
+    /**
+     * Handle list commands request for an agent
+     */
+    async handleListCommandsRequest(msg) {
+        const { agentId, requestId, draftConfig } = msg;
+        this.sessionLogger.debug({ agentId, draftConfig }, `Handling list commands request for agent ${agentId}`);
+        try {
+            const agents = this.agentManager.listAgents();
+            const agent = agents.find((a) => a.id === agentId);
+            if (agent?.session?.listCommands) {
+                const commands = await agent.session.listCommands();
+                this.emit({
+                    type: "list_commands_response",
+                    payload: {
+                        agentId,
+                        commands,
+                        error: null,
+                        requestId,
+                    },
+                });
+                return;
+            }
+            if (!agent && draftConfig) {
+                const sessionConfig = {
+                    provider: draftConfig.provider,
+                    cwd: expandTilde(draftConfig.cwd),
+                    ...(draftConfig.modeId ? { modeId: draftConfig.modeId } : {}),
+                    ...(draftConfig.model ? { model: draftConfig.model } : {}),
+                    ...(draftConfig.thinkingOptionId
+                        ? { thinkingOptionId: draftConfig.thinkingOptionId }
+                        : {}),
+                };
+                const commands = await this.agentManager.listDraftCommands(sessionConfig);
+                this.emit({
+                    type: "list_commands_response",
+                    payload: {
+                        agentId,
+                        commands,
+                        error: null,
+                        requestId,
+                    },
+                });
+                return;
+            }
+            this.emit({
+                type: "list_commands_response",
+                payload: {
+                    agentId,
+                    commands: [],
+                    error: agent ? `Agent does not support listing commands` : `Agent not found: ${agentId}`,
+                    requestId,
+                },
+            });
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, agentId, draftConfig }, "Failed to list commands");
+            this.emit({
+                type: "list_commands_response",
+                payload: {
+                    agentId,
+                    commands: [],
+                    error: getErrorMessage(error),
+                    requestId,
+                },
+            });
+        }
+    }
+    /**
+     * Handle agent permission response from user
+     */
+    async handleAgentPermissionResponse(agentId, requestId, response) {
+        try {
+            await respondToAgentPermission({
+                agentManager: this.agentManager,
+                agentId,
+                requestId,
+                response,
+                logger: this.sessionLogger,
+            });
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, agentId, requestId }, "Failed to respond to permission");
+            this.emit({
+                type: "activity_log",
+                payload: {
+                    id: uuidv4(),
+                    timestamp: new Date(),
+                    type: "error",
+                    content: `Failed to respond to permission: ${getErrorMessage(error)}`,
+                },
+            });
+            throw error;
+        }
+    }
+    async handleDirectorySuggestionsRequest(msg) {
+        const { query, limit, requestId, cwd, includeFiles, includeDirectories, matchMode } = msg;
+        try {
+            const workspaceCwd = cwd?.trim();
+            const entries = workspaceCwd
+                ? await searchWorkspaceEntries({
+                    cwd: expandTilde(workspaceCwd),
+                    query,
+                    limit,
+                    includeFiles,
+                    includeDirectories,
+                    matchMode,
+                })
+                : (await searchHomeDirectories({
+                    homeDir: process.env.HOME ?? homedir(),
+                    query,
+                    limit,
+                })).map((path) => ({ path, kind: "directory" }));
+            const directories = entries
+                .filter((entry) => entry.kind === "directory")
+                .map((entry) => entry.path);
+            this.emit({
+                type: "directory_suggestions_response",
+                payload: {
+                    directories,
+                    entries,
+                    error: null,
+                    requestId,
+                },
+            });
+        }
+        catch (error) {
+            this.emit({
+                type: "directory_suggestions_response",
+                payload: {
+                    directories: [],
+                    entries: [],
+                    error: error instanceof Error ? error.message : String(error),
+                    requestId,
+                },
+            });
+        }
+    }
+    async handleOttoWorktreeListRequest(msg) {
+        return handleWorktreeListRequest({
+            emit: (message) => this.emit(message),
+            ottoHome: this.ottoHome,
+            workspaceGitService: this.workspaceGitService,
+        }, msg);
+    }
+    async handleOttoWorktreeArchiveRequest(msg) {
+        return handleWorktreeArchiveRequest({
+            ottoHome: this.ottoHome,
+            ottoWorktreesBaseRoot: this.worktreesRoot,
+            github: this.github,
+            workspaceGitService: this.workspaceGitService,
+            agentManager: this.agentManager,
+            agentStorage: this.agentStorage,
+            findWorkspaceIdForCwd: (cwd) => this.findWorkspaceIdForCwd(cwd),
+            listActiveWorkspaces: () => this.listActiveWorkspaceRefs(),
+            archiveWorkspaceRecord: (workspaceId) => this.archiveWorkspaceRecord(workspaceId),
+            emit: (message) => this.emit(message),
+            emitWorkspaceUpdatesForWorkspaceIds: (workspaceIds) => this.emitWorkspaceUpdatesForWorkspaceIds(workspaceIds),
+            markWorkspaceArchiving: (workspaceIds, archivingAt) => this.markWorkspaceArchiving(workspaceIds, archivingAt),
+            clearWorkspaceArchiving: (workspaceIds) => this.clearWorkspaceArchiving(workspaceIds),
+            killTerminalsForWorkspace: (workspaceId) => this.terminalController.killTerminalsForWorkspace(workspaceId),
+            sessionLogger: this.sessionLogger,
+        }, msg);
+    }
+    async listTerminalActivityContributions() {
+        const terminalManager = this.terminalManager;
+        if (!terminalManager) {
+            return [];
+        }
+        const directories = terminalManager.listDirectories();
+        const terminalsByDirectory = await Promise.all(directories.map((cwd) => terminalManager.getTerminals(cwd)));
+        return terminalsByDirectory.flat().map((session) => {
+            const contribution = {
+                cwd: session.cwd,
+                activity: session.getActivity(),
+            };
+            if (session.workspaceId) {
+                contribution.workspaceId = session.workspaceId;
+            }
+            return contribution;
+        });
+    }
+    /**
+     * Build the current agent list payload (live + persisted), optionally filtered by labels.
+     */
+    async listAgentPayloads(filter) {
+        const includeArchived = filter?.includeArchived === true;
+        const labelEntries = filter?.labels ? Object.entries(filter.labels) : [];
+        // Get live agents with session modes
+        const agentSnapshots = this.agentManager.listAgents();
+        const liveAgents = await Promise.all(agentSnapshots.map((agent) => this.buildAgentPayload(agent)));
+        // Add persisted agents that have not been lazily initialized yet
+        // (excluding internal agents which are for ephemeral system tasks)
+        const registryRecords = await this.agentStorage.list();
+        const liveIds = new Set(agentSnapshots.map((a) => a.id));
+        const registeredProviderIds = new Set(this.providerSnapshotManager.listRegisteredProviderIds());
+        const persistedAgents = registryRecords
+            .filter((record) => !liveIds.has(record.id) && !record.internal)
+            // Keep raw-record filters ahead of projection; seeded homes can carry thousands of archived agents.
+            .filter((record) => includeArchived || !record.archivedAt)
+            .filter((record) => labelEntries.every(([key, value]) => record.labels?.[key] === value))
+            .filter((record) => filter?.includeUnavailablePersisted === true ||
+            isStoredAgentProviderAvailable(record, registeredProviderIds))
+            .map((record) => this.buildStoredAgentPayload(record, registeredProviderIds));
+        let agents = [...liveAgents, ...persistedAgents];
+        agents = agents.filter((agent) => this.isProviderVisibleToClient(agent.provider));
+        if (!includeArchived) {
+            agents = agents.filter((agent) => !agent.archivedAt);
+        }
+        // Filter by labels if filter provided
+        if (labelEntries.length > 0) {
+            agents = agents.filter((agent) => labelEntries.every(([key, value]) => agent.labels[key] === value));
+        }
+        return agents;
+    }
+    async resolveAgentIdentifier(identifier) {
+        const trimmed = identifier.trim();
+        if (!trimmed) {
+            return { ok: false, error: "Agent identifier cannot be empty" };
+        }
+        // Exact live-agent lookup bypasses the internal-agent exclusion below.
+        // Internal agents (e.g. artifact generation) are deliberately hidden from
+        // the fuzzy prefix/title resolution and general listings further down,
+        // but a caller that already has the literal agentId (not a prefix or
+        // title guess) should still be able to resolve it while it's alive.
+        if (this.agentManager.getAgent(trimmed)) {
+            return { ok: true, agentId: trimmed };
+        }
+        const stored = await this.agentStorage.list();
+        const storedRecords = stored.filter((record) => !record.internal);
+        const knownIds = new Set();
+        for (const record of storedRecords) {
+            knownIds.add(record.id);
+        }
+        for (const agent of this.agentManager.listAgents()) {
+            knownIds.add(agent.id);
+        }
+        if (knownIds.has(trimmed)) {
+            return { ok: true, agentId: trimmed };
+        }
+        const prefixMatches = Array.from(knownIds).filter((id) => id.startsWith(trimmed));
+        if (prefixMatches.length === 1) {
+            return { ok: true, agentId: prefixMatches[0] };
+        }
+        if (prefixMatches.length > 1) {
+            return {
+                ok: false,
+                error: `Agent identifier "${trimmed}" is ambiguous (${prefixMatches
+                    .slice(0, 5)
+                    .map((id) => id.slice(0, 8))
+                    .join(", ")}${prefixMatches.length > 5 ? ", …" : ""})`,
+            };
+        }
+        const titleMatches = storedRecords.filter((record) => record.title === trimmed);
+        if (titleMatches.length === 1) {
+            return { ok: true, agentId: titleMatches[0].id };
+        }
+        if (titleMatches.length > 1) {
+            return {
+                ok: false,
+                error: `Agent title "${trimmed}" is ambiguous (${titleMatches
+                    .slice(0, 5)
+                    .map((r) => r.id.slice(0, 8))
+                    .join(", ")}${titleMatches.length > 5 ? ", …" : ""})`,
+            };
+        }
+        return { ok: false, error: `Agent not found: ${trimmed}` };
+    }
+    async getAgentPayloadById(agentId) {
+        const live = this.agentManager.getAgent(agentId);
+        if (live) {
+            const payload = await this.buildAgentPayload(live);
+            return this.isProviderVisibleToClient(payload.provider) ? payload : null;
+        }
+        const record = await this.agentStorage.get(agentId);
+        if (!record || record.internal) {
+            return null;
+        }
+        const payload = this.buildStoredAgentPayload(record);
+        return this.isProviderVisibleToClient(payload.provider) ? payload : null;
+    }
+    async resolveDelegationRootWorkspaceId(agentId) {
+        const seen = new Set();
+        let currentAgentId = agentId;
+        while (true) {
+            if (seen.has(currentAgentId)) {
+                return null;
+            }
+            seen.add(currentAgentId);
+            const live = this.agentManager.getAgent(currentAgentId);
+            const source = live ?? (await this.agentStorage.get(currentAgentId));
+            if (!source) {
+                return null;
+            }
+            if ("archivedAt" in source && source.archivedAt) {
+                return null;
+            }
+            const parentAgentId = getParentAgentIdFromLabels(source.labels);
+            if (!parentAgentId) {
+                return source.workspaceId ?? null;
+            }
+            currentAgentId = parentAgentId;
+        }
+    }
+    async buildActiveProjectPlacementsByWorkspaceId() {
+        const [persistedWorkspaces, persistedProjects] = await Promise.all([
+            this.workspaceRegistry.list(),
+            this.projectRegistry.list(),
+        ]);
+        const activeProjects = new Map(persistedProjects
+            .filter((project) => !project.archivedAt)
+            .map((project) => [project.projectId, project]));
+        const placementsByWorkspaceId = new Map();
+        const pairs = persistedWorkspaces.flatMap((workspace) => {
+            if (workspace.archivedAt)
+                return [];
+            const project = activeProjects.get(workspace.projectId);
+            if (!project)
+                return [];
+            return [{ workspace, project }];
+        });
+        const placements = await Promise.all(pairs.map(({ workspace, project }) => this.buildProjectPlacementForWorkspace(workspace, project)));
+        for (let i = 0; i < pairs.length; i += 1) {
+            placementsByWorkspaceId.set(pairs[i].workspace.workspaceId, placements[i]);
+        }
+        return placementsByWorkspaceId;
+    }
+    async collectFetchAgentsEntries(params) {
+        const { candidates, limit, getPlacement, filter } = params;
+        const matchedEntries = [];
+        const batchSize = 25;
+        for (let start = 0; start < candidates.length && matchedEntries.length <= limit; start += batchSize) {
+            const batch = candidates.slice(start, start + batchSize);
+            const batchEntries = await Promise.all(batch.map(async (agent) => {
+                const project = await getPlacement(agent.workspaceId);
+                return project ? { agent, project } : null;
+            }));
+            for (const entry of batchEntries) {
+                if (!entry) {
+                    continue;
+                }
+                if (!matchesAgentUpdatesFilter({
+                    agent: entry.agent,
+                    project: entry.project,
+                    filter,
+                })) {
+                    continue;
+                }
+                matchedEntries.push(entry);
+                if (matchedEntries.length > limit) {
+                    break;
+                }
+            }
+        }
+        return matchedEntries;
+    }
+    async listFetchAgentsEntries(request) {
+        const filter = request.type === "fetch_agent_history_request" &&
+            request.filter?.includeArchived === undefined
+            ? { ...request.filter, includeArchived: true }
+            : request.filter;
+        const scope = request.type === "fetch_agents_request" ? request.scope : undefined;
+        const sort = this.agentsPager.normalizeSort(request.sort);
+        let agents = await this.listAgentPayloads({
+            labels: filter?.labels,
+            includeArchived: filter?.includeArchived,
+            includeUnavailablePersisted: request.type === "fetch_agent_history_request",
+        });
+        const activePlacementsByWorkspaceId = scope === "active" ? await this.buildActiveProjectPlacementsByWorkspaceId() : null;
+        if (activePlacementsByWorkspaceId) {
+            agents = agents.filter((agent) => !agent.archivedAt &&
+                agent.workspaceId != null &&
+                activePlacementsByWorkspaceId.has(agent.workspaceId));
+        }
+        const placementByWorkspaceId = new Map();
+        const getPlacement = (workspaceId) => {
+            if (!workspaceId) {
+                return Promise.resolve(null);
+            }
+            if (activePlacementsByWorkspaceId) {
+                return Promise.resolve(activePlacementsByWorkspaceId.get(workspaceId) ?? null);
+            }
+            const existing = placementByWorkspaceId.get(workspaceId);
+            if (existing) {
+                return existing;
+            }
+            const placementPromise = this.buildProjectPlacementForWorkspaceId(workspaceId);
+            placementByWorkspaceId.set(workspaceId, placementPromise);
+            return placementPromise;
+        };
+        let candidates = [...agents];
+        candidates.sort((left, right) => this.agentsPager.compare(left, right, sort));
+        const cursorToken = request.page?.cursor;
+        if (cursorToken) {
+            const cursor = this.decodeAgentCursor(cursorToken, sort);
+            candidates = candidates.filter((agent) => this.agentsPager.compareWithCursor(agent, cursor, sort) > 0);
+        }
+        const limit = request.page?.limit ?? 200;
+        const matchedEntries = await this.collectFetchAgentsEntries({
+            candidates,
+            limit,
+            getPlacement,
+            filter,
+        });
+        const pagedEntries = matchedEntries.slice(0, limit);
+        const hasMore = matchedEntries.length > limit;
+        const nextCursor = hasMore && pagedEntries.length > 0
+            ? this.agentsPager.encode(pagedEntries[pagedEntries.length - 1].agent, sort)
+            : null;
+        return {
+            entries: pagedEntries,
+            pageInfo: {
+                nextCursor,
+                prevCursor: request.page?.cursor ?? null,
+                hasMore,
+            },
+        };
+    }
+    decodeAgentCursor(token, sort) {
+        try {
+            return this.agentsPager.decode(token, sort);
+        }
+        catch (error) {
+            if (error instanceof CursorError) {
+                throw new SessionRequestError("invalid_cursor", error.message);
+            }
+            throw error;
+        }
+    }
+    async describeWorkspaceRecord(workspace, projectRecord) {
+        const resolvedProjectRecord = projectRecord ?? (await this.projectRegistry.get(workspace.projectId));
+        let diffStat = null;
+        const snapshot = this.workspaceGitService.peekSnapshot(workspace.cwd);
+        if (snapshot?.git.diffStat) {
+            diffStat = snapshot.git.diffStat;
+        }
+        return {
+            id: workspace.workspaceId,
+            projectId: workspace.projectId,
+            projectDisplayName: resolvedProjectRecord
+                ? resolveProjectDisplayName(resolvedProjectRecord)
+                : workspace.projectId,
+            projectCustomName: resolvedProjectRecord?.customName ?? null,
+            projectRootPath: resolvedProjectRecord?.rootPath ?? workspace.cwd,
+            workspaceDirectory: workspace.cwd,
+            projectKind: (resolvedProjectRecord?.kind ?? "directory") === "git" ? "git" : "non_git",
+            workspaceKind: workspace.kind,
+            name: resolveWorkspaceDisplayName(workspace),
+            title: workspace.title,
+            archivingAt: null,
+            status: "done",
+            statusEnteredAt: null,
+            activityAt: null,
+            diffStat,
+            scripts: this.buildWorkspaceScriptPayloadSnapshot(workspace.workspaceId, workspace.cwd),
+            ...(resolvedProjectRecord
+                ? {
+                    project: await this.buildProjectPlacementForWorkspace(workspace, resolvedProjectRecord),
+                }
+                : {}),
+        };
+    }
+    buildWorkspaceGitRuntimePayload(snapshot) {
+        if (!snapshot.git.isGit) {
+            return null;
+        }
+        return {
+            currentBranch: snapshot.git.currentBranch,
+            remoteUrl: snapshot.git.remoteUrl,
+            isOttoOwnedWorktree: snapshot.git.isOttoOwnedWorktree,
+            isDirty: snapshot.git.isDirty,
+            aheadBehind: snapshot.git.aheadBehind,
+            aheadOfOrigin: snapshot.git.aheadOfOrigin,
+            behindOfOrigin: snapshot.git.behindOfOrigin,
+        };
+    }
+    buildWorkspaceGitHubRuntimePayload(snapshot) {
+        return {
+            featuresEnabled: snapshot.github.featuresEnabled,
+            pullRequest: snapshot.github.pullRequest,
+            error: snapshot.github.error,
+        };
+    }
+    async describeWorkspaceRecordWithGitData(workspace, projectRecord) {
+        const base = await this.describeWorkspaceRecord(workspace, projectRecord);
+        const snapshot = this.workspaceGitService.peekSnapshot(workspace.cwd);
+        if (!snapshot) {
+            return base;
+        }
+        const checkout = checkoutLiteFromGitSnapshot(workspace.cwd, snapshot.git);
+        const displayName = deriveWorkspaceDisplayName({ cwd: workspace.cwd, checkout });
+        return {
+            ...base,
+            name: resolveWorkspaceName({ title: workspace.title, derivedDisplayName: displayName }),
+            diffStat: snapshot.git.diffStat ?? null,
+            gitRuntime: this.buildWorkspaceGitRuntimePayload(snapshot) ?? undefined,
+            githubRuntime: this.buildWorkspaceGitHubRuntimePayload(snapshot),
+        };
+    }
+    async describeCreatedWorktreeWorkspace(result) {
+        const projectRecord = await this.projectRegistry.get(result.workspace.projectId);
+        return {
+            id: result.workspace.workspaceId,
+            projectId: result.workspace.projectId,
+            projectDisplayName: projectRecord
+                ? resolveProjectDisplayName(projectRecord)
+                : result.workspace.projectId,
+            projectCustomName: projectRecord?.customName ?? null,
+            projectRootPath: projectRecord?.rootPath ?? result.repoRoot,
+            workspaceDirectory: result.workspace.cwd,
+            projectKind: "git",
+            workspaceKind: result.workspace.kind,
+            name: resolveWorkspaceName({
+                title: result.workspace.title,
+                derivedDisplayName: result.worktree.branchName || result.workspace.displayName,
+            }),
+            title: result.workspace.title,
+            archivingAt: null,
+            status: "done",
+            statusEnteredAt: result.workspace.createdAt,
+            activityAt: null,
+            diffStat: { additions: 0, deletions: 0 },
+            scripts: [],
+            gitRuntime: {
+                currentBranch: result.worktree.branchName || null,
+                remoteUrl: null,
+                isOttoOwnedWorktree: true,
+                isDirty: false,
+                aheadBehind: null,
+                aheadOfOrigin: null,
+                behindOfOrigin: null,
+            },
+            githubRuntime: null,
+        };
+    }
+    async buildWorkspaceDescriptor(input) {
+        if (input.includeGitData && input.projectRecord?.kind === "git") {
+            return this.describeWorkspaceRecordWithGitData(input.workspace, input.projectRecord);
+        }
+        return this.describeWorkspaceRecord(input.workspace, input.projectRecord);
+    }
+    markWorkspaceArchiving(workspaceIds, archivingAt) {
+        this.workspaceDirectory.markArchiving(workspaceIds, archivingAt);
+    }
+    clearWorkspaceArchiving(workspaceIds) {
+        this.workspaceDirectory.clearArchiving(workspaceIds);
+    }
+    async buildWorkspaceDescriptorMap(options) {
+        return this.workspaceDirectory.buildDescriptorMap(options);
+    }
+    // external path→workspace adapter, not ownership. Used by archive-by-path flows
+    // where the request carries a worktree path (unique to one workspace) rather
+    // than a workspaceId. This is a directory lookup for an archive target, not a
+    // status/ownership attribution.
+    async findWorkspaceIdForCwd(cwd) {
+        const workspaces = await this.workspaceRegistry.list();
+        return resolveWorkspaceIdForPath(cwd, workspaces);
+    }
+    matchesWorkspaceFilter(input) {
+        return this.workspaceDirectory.matchesFilter(input);
+    }
+    async listFetchWorkspacesEntries(request) {
+        try {
+            return await this.workspaceDirectory.listFetchEntries(request);
+        }
+        catch (error) {
+            if (error instanceof CursorError) {
+                throw new SessionRequestError("invalid_cursor", error.message);
+            }
+            throw error;
+        }
+    }
+    bufferOrEmitWorkspaceUpdate(subscription, payload) {
+        if (subscription.isBootstrapping) {
+            const workspaceId = payload.kind === "upsert" ? payload.workspace.id : payload.id;
+            subscription.pendingUpdatesByWorkspaceId.set(workspaceId, payload);
+            return;
+        }
+        const workspaceId = payload.kind === "upsert" ? payload.workspace.id : payload.id;
+        subscription.lastEmittedByWorkspaceId.set(workspaceId, payload);
+        this.emit({
+            type: "workspace_update",
+            payload,
+        });
+    }
+    flushBootstrappedWorkspaceUpdates(options) {
+        const subscription = this.workspaceUpdatesSubscription;
+        if (!subscription || !subscription.isBootstrapping) {
+            return;
+        }
+        subscription.isBootstrapping = false;
+        const pending = Array.from(subscription.pendingUpdatesByWorkspaceId.values());
+        subscription.pendingUpdatesByWorkspaceId.clear();
+        for (const payload of pending) {
+            if (payload.kind === "upsert") {
+                const snapshot = options?.snapshotByWorkspaceId?.get(payload.workspace.id);
+                const updateActivityAtMs = payload.workspace.activityAt
+                    ? Date.parse(payload.workspace.activityAt)
+                    : null;
+                const shouldEmit = shouldEmitPendingBootstrapUpdate({
+                    snapshot: snapshot
+                        ? {
+                            status: snapshot.status,
+                            statusEnteredAt: snapshot.statusEnteredAt,
+                            activityAtMs: snapshot.activityAtMs,
+                        }
+                        : null,
+                    update: {
+                        status: payload.workspace.status,
+                        statusEnteredAt: payload.workspace.statusEnteredAt ?? null,
+                        activityAtMs: Number.isNaN(updateActivityAtMs) ? null : updateActivityAtMs,
+                    },
+                });
+                if (!shouldEmit) {
+                    continue;
+                }
+            }
+            this.emit({
+                type: "workspace_update",
+                payload,
+            });
+        }
+    }
+    buildProjectDescriptor(project) {
+        return {
+            projectId: project.projectId,
+            projectDisplayName: resolveProjectDisplayName(project),
+            projectCustomName: project.customName ?? null,
+            projectRootPath: project.rootPath,
+            projectKind: project.kind,
+        };
+    }
+    async unarchiveOwningWorkspaceForAgent(agentId) {
+        const record = await this.agentStorage.get(agentId);
+        if (!record?.workspaceId) {
+            return;
+        }
+        const workspace = await this.workspaceRegistry.get(record.workspaceId);
+        if (!workspace?.archivedAt) {
+            return;
+        }
+        const directoryExists = await this.filesystem.isDirectory(record.cwd).catch(() => false);
+        if (!directoryExists) {
+            if (workspace.kind !== "worktree" || !workspace.branch) {
+                return;
+            }
+            // Recreate the worktree directory from its kept branch BEFORE clearing
+            // archivedAt — the reconciler re-archives workspaces whose directory is
+            // missing, so the record must point at a real directory first.
+            await this.recreateOwningWorktreeForRestore(workspace, workspace.branch);
+        }
+        await this.workspaceProvisioning.ensureWorkspaceRecordUnarchived(workspace);
+        await this.emitWorkspaceUpdatesForWorkspaceIds([workspace.workspaceId]);
+    }
+    async recreateOwningWorktreeForRestore(workspace, branch) {
+        const project = await this.projectRegistry.get(workspace.projectId);
+        if (!project) {
+            throw new WorktreeRequestError({
+                code: "unknown",
+                message: `Project ${workspace.projectId} not found for workspace ${workspace.workspaceId}`,
+            });
+        }
+        const projectRootExists = await this.filesystem
+            .isDirectory(project.rootPath)
+            .catch(() => false);
+        if (!projectRootExists) {
+            throw new WorktreeRequestError({
+                code: "unknown",
+                message: `Project root is missing for ${workspace.projectId}: ${project.rootPath}`,
+            });
+        }
+        // Archiving through the default path (scope "workspace", worktreePath only)
+        // resolves repoRoot=null, so deleteOttoWorktree's `git worktree remove`/
+        // `prune` is skipped and the admin registration survives — pinning the
+        // branch as "already checked out". Prune here frees any stale registration
+        // whose working dir is missing (a no-op for live worktrees) so the recreate
+        // below succeeds regardless of how the worktree was archived.
+        try {
+            await runGitCommand(["worktree", "prune"], { cwd: project.rootPath, timeout: 30000 });
+        }
+        catch {
+            // not critical; git will prune lazily
+        }
+        let result;
+        try {
+            result = await createWorktree({
+                cwd: project.rootPath,
+                worktreeSlug: basename(workspace.cwd),
+                source: { kind: "checkout-branch", branchName: branch },
+                runSetup: false,
+                ottoHome: this.ottoHome,
+                worktreesRoot: this.worktreesRoot,
+            });
+        }
+        catch (error) {
+            throw toWorktreeRequestError(error);
+        }
+        if (normalize(result.worktreePath) !== normalize(workspace.cwd)) {
+            throw new WorktreeRequestError({
+                code: "unknown",
+                message: `Recreated worktree diverged from ${workspace.cwd}: ${result.worktreePath}`,
+            });
+        }
+    }
+    async createOttoWorktree(input, options) {
+        const result = await createOttoWorktree(input, {
+            github: this.github,
+            ...(options?.resolveDefaultBranch
+                ? { resolveDefaultBranch: options.resolveDefaultBranch }
+                : {}),
+            projectRegistry: this.projectRegistry,
+            workspaceRegistry: this.workspaceRegistry,
+            workspaceGitService: this.workspaceGitService,
+        });
+        void Promise.all([
+            this.gitMutation.notifyGitMutation(input.cwd, "create-worktree"),
+            this.gitMutation.notifyGitMutation(result.worktree.worktreePath, "create-worktree"),
+        ]).catch((error) => {
+            this.sessionLogger.warn({ err: error, cwd: input.cwd, worktreePath: result.worktree.worktreePath }, "Failed to warm git snapshots after creating worktree");
+        });
+        return result;
+    }
+    async listActiveWorkspaceRefs() {
+        const workspaces = await this.workspaceRegistry.list();
+        return workspaces
+            .filter((workspace) => !workspace.archivedAt)
+            .map((workspace) => ({
+            workspaceId: workspace.workspaceId,
+            cwd: workspace.cwd,
+            kind: workspace.kind,
+        }));
+    }
+    async archiveWorkspaceRecord(workspaceId, archivedAt) {
+        const archiveTimestamp = archivedAt ?? new Date().toISOString();
+        const existingWorkspace = await archivePersistedWorkspaceRecord({
+            workspaceId,
+            archivedAt: archiveTimestamp,
+            workspaceRegistry: this.workspaceRegistry,
+        });
+        if (!existingWorkspace) {
+            this.workspaceGitObserver.removeForWorkspaceId(workspaceId);
+            return;
+        }
+        if (!existingWorkspace.archivedAt) {
+            const activeSiblings = (await this.workspaceRegistry.list()).filter((workspace) => workspace.projectId === existingWorkspace.projectId && !workspace.archivedAt);
+            this.sessionLogger.info({
+                workspaceId,
+                workspaceCwd: existingWorkspace.cwd,
+                projectId: existingWorkspace.projectId,
+                projectArchived: activeSiblings.length === 0,
+                archivedAt: archiveTimestamp,
+            }, "Workspace archived");
+        }
+        await this.teardownArchivedWorkspace({
+            workspaceId: existingWorkspace.workspaceId,
+            cwd: existingWorkspace.cwd,
+        });
+    }
+    // Git watch and subscription state is keyed by directory; the script runtime
+    // store is keyed by the opaque workspace id. Each cleanup uses its own key so an
+    // opaque id is never resolved as a filesystem path.
+    async teardownArchivedWorkspace(input) {
+        this.workspaceGitObserver.removeForCwd(input.cwd);
+        this.scriptRuntimeStore?.removeForWorkspace(input.workspaceId);
+    }
+    async reconcileAndEmitWorkspaceUpdates() {
+        if (!this.workspaceUpdatesSubscription) {
+            return;
+        }
+        try {
+            const changedWorkspaceIds = await this.reconcileActiveWorkspaceRecords();
+            if (changedWorkspaceIds.size === 0) {
+                return;
+            }
+            await this.emitWorkspaceUpdatesForWorkspaceIds(changedWorkspaceIds, {
+                skipReconcile: true,
+            });
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error }, "Background workspace reconciliation failed");
+        }
+    }
+    async reconcileActiveWorkspaceRecords() {
+        const service = new WorkspaceReconciliationService({
+            projectRegistry: this.projectRegistry,
+            workspaceRegistry: this.workspaceRegistry,
+            logger: this.sessionLogger,
+            workspaceGitService: this.workspaceGitService,
+        });
+        const result = await service.runOnce();
+        const changedWorkspaceIds = new Set();
+        const changedProjectIds = new Set();
+        await Promise.all(result.changesApplied.map(async (change) => {
+            switch (change.kind) {
+                case "workspace_archived":
+                    await this.teardownArchivedWorkspace({
+                        workspaceId: change.workspaceId,
+                        cwd: change.directory,
+                    });
+                    changedWorkspaceIds.add(change.workspaceId);
+                    break;
+                case "workspace_updated":
+                    changedWorkspaceIds.add(change.workspaceId);
+                    break;
+                case "project_archived":
+                case "project_updated":
+                    changedProjectIds.add(change.projectId);
+                    break;
+            }
+        }));
+        if (changedProjectIds.size > 0) {
+            for (const workspace of await this.workspaceRegistry.list()) {
+                if (changedProjectIds.has(workspace.projectId)) {
+                    changedWorkspaceIds.add(workspace.workspaceId);
+                }
+            }
+        }
+        return changedWorkspaceIds;
+    }
+    async emitWorkspaceUpdatesForWorkspaceIds(workspaceIds, options) {
+        const subscription = this.workspaceUpdatesSubscription;
+        if (!subscription) {
+            return;
+        }
+        const uniqueWorkspaceIds = new Set(Array.from(workspaceIds));
+        if (uniqueWorkspaceIds.size === 0) {
+            return;
+        }
+        const descriptorsByWorkspaceId = await this.buildWorkspaceDescriptorMap({
+            workspaceIds: uniqueWorkspaceIds,
+            includeGitData: true,
+        });
+        for (const workspaceId of uniqueWorkspaceIds) {
+            const workspace = descriptorsByWorkspaceId.get(workspaceId);
+            const nextWorkspace = workspace && this.matchesWorkspaceFilter({ workspace, filter: subscription.filter })
+                ? workspace
+                : null;
+            if (options?.dedupeGitState &&
+                this.workspaceGitObserver.shouldSkipUpdate(workspaceId, nextWorkspace)) {
+                continue;
+            }
+            this.workspaceGitObserver.recordDescriptorState(workspaceId, nextWorkspace);
+            if (!nextWorkspace) {
+                subscription.lastEmittedByWorkspaceId.delete(workspaceId);
+                this.bufferOrEmitWorkspaceUpdate(subscription, await this.buildWorkspaceRemoveUpdatePayload(workspaceId, options?.removedProjectId));
+                continue;
+            }
+            const nextPayload = {
+                kind: "upsert",
+                workspace: nextWorkspace,
+            };
+            const lastEmitted = subscription.lastEmittedByWorkspaceId.get(workspaceId);
+            if (lastEmitted &&
+                lastEmitted.kind === "upsert" &&
+                equal(lastEmitted.workspace, nextWorkspace)) {
+                continue;
+            }
+            this.bufferOrEmitWorkspaceUpdate(subscription, nextPayload);
+        }
+        if (!options?.skipReconcile) {
+            void this.reconcileAndEmitWorkspaceUpdates();
+        }
+    }
+    async buildWorkspaceRemoveUpdatePayload(workspaceId, removedProjectId) {
+        if (removedProjectId) {
+            return { kind: "remove", id: workspaceId, removedProjectId };
+        }
+        return {
+            kind: "remove",
+            id: workspaceId,
+            ...(await this.resolveProjectWithoutActiveWorkspacesForArchivedWorkspace(workspaceId)),
+        };
+    }
+    // When a workspace is archived its project may have no active workspaces left.
+    // Resolve that project parent so the `remove` update can carry it, keeping the
+    // sidebar in sync without a full re-hydration.
+    async resolveProjectWithoutActiveWorkspacesForArchivedWorkspace(workspaceId) {
+        const archivedWorkspace = await this.workspaceRegistry.get(workspaceId);
+        if (!archivedWorkspace) {
+            return null;
+        }
+        const projectWithoutActiveWorkspaces = (await this.workspaceDirectory.listEmptyProjects()).find((project) => project.projectId === archivedWorkspace.projectId);
+        return projectWithoutActiveWorkspaces ? { emptyProject: projectWithoutActiveWorkspaces } : null;
+    }
+    async emitWorkspaceUpdateForTerminalContribution(event) {
+        // A terminal's activity contributes only to the workspace it carries. A
+        // terminal with no workspaceId attributes to nothing — status is per-id.
+        if (!event.workspaceId) {
+            return;
+        }
+        await this.emitWorkspaceUpdatesForWorkspaceIds([event.workspaceId], {
+            skipReconcile: true,
+        });
+    }
+    // A git fact (branch, diff, dirty, PR) changed at `cwd`. Every workspace whose
+    // OWN cwd is this folder re-derives its git facts from that folder (id → cwd)
+    // and emits its own per-id descriptor. This is a deliberate same-folder fan,
+    // not a cwd → id ownership lookup: git never resolves which workspace owns a
+    // path. See `workspaceIdsOnCheckout`.
+    async emitWorkspaceUpdateForCwd(cwd, options) {
+        const workspaceIds = workspaceIdsOnCheckout(await this.workspaceRegistry.list(), cwd);
+        if (workspaceIds.length === 0) {
+            return;
+        }
+        await this.emitWorkspaceUpdatesForWorkspaceIds(workspaceIds, options);
+    }
+    async handleFetchAgents(request) {
+        const requestedSubscriptionId = request.subscribe?.subscriptionId?.trim();
+        const subscriptionId = resolveSubscriptionId(request.subscribe, requestedSubscriptionId);
+        try {
+            if (subscriptionId) {
+                this.agentUpdates.beginSubscription({
+                    subscriptionId,
+                    filter: request.filter,
+                });
+            }
+            const payload = await this.listFetchAgentsEntries(request);
+            const snapshotUpdatedAtByAgentId = new Map();
+            for (const entry of payload.entries) {
+                const parsedUpdatedAt = Date.parse(entry.agent.updatedAt);
+                if (!Number.isNaN(parsedUpdatedAt)) {
+                    snapshotUpdatedAtByAgentId.set(entry.agent.id, parsedUpdatedAt);
+                }
+            }
+            this.emit({
+                type: "fetch_agents_response",
+                payload: {
+                    requestId: request.requestId,
+                    ...(subscriptionId ? { subscriptionId } : {}),
+                    ...payload,
+                },
+            });
+            if (subscriptionId) {
+                this.agentUpdates.flushBootstrapped(subscriptionId, { snapshotUpdatedAtByAgentId });
+            }
+        }
+        catch (error) {
+            if (subscriptionId) {
+                this.agentUpdates.clearSubscription(subscriptionId);
+            }
+            const code = error instanceof SessionRequestError ? error.code : "fetch_agents_failed";
+            const message = error instanceof Error ? error.message : "Failed to fetch agents";
+            this.sessionLogger.error({ err: error }, "Failed to handle fetch_agents_request");
+            this.emit({
+                type: "rpc_error",
+                payload: {
+                    requestId: request.requestId,
+                    requestType: request.type,
+                    error: message,
+                    code,
+                },
+            });
+        }
+    }
+    async handleFetchAgentHistory(request) {
+        try {
+            const payload = await this.listFetchAgentsEntries(request);
+            this.emit({
+                type: "fetch_agent_history_response",
+                payload: {
+                    requestId: request.requestId,
+                    ...payload,
+                },
+            });
+        }
+        catch (error) {
+            const code = error instanceof SessionRequestError ? error.code : "fetch_agent_history_failed";
+            const message = error instanceof Error ? error.message : "Failed to fetch agent history";
+            this.sessionLogger.error({ err: error }, "Failed to handle fetch_agent_history_request");
+            this.emit({
+                type: "rpc_error",
+                payload: {
+                    requestId: request.requestId,
+                    requestType: request.type,
+                    error: message,
+                    code,
+                },
+            });
+        }
+    }
+    async handleFetchRecentProviderSessions(request) {
+        try {
+            const result = await listImportableProviderSessions({
+                request,
+                agentManager: this.agentManager,
+                agentStorage: this.agentStorage,
+                providerSnapshotManager: this.providerSnapshotManager,
+            });
+            this.emit({
+                type: "fetch_recent_provider_sessions_response",
+                payload: {
+                    requestId: request.requestId,
+                    entries: result.entries,
+                    ...(result.filteredAlreadyImportedCount > 0
+                        ? { filteredAlreadyImportedCount: result.filteredAlreadyImportedCount }
+                        : {}),
+                },
+            });
+        }
+        catch (error) {
+            const code = error instanceof ImportSessionsRequestError
+                ? error.code
+                : "fetch_recent_provider_sessions_failed";
+            const message = error instanceof Error ? error.message : "Failed to fetch recent provider sessions";
+            this.sessionLogger.error({ err: error }, "Failed to handle fetch_recent_provider_sessions_request");
+            this.emit({
+                type: "rpc_error",
+                payload: {
+                    requestId: request.requestId,
+                    requestType: request.type,
+                    error: message,
+                    code,
+                },
+            });
+        }
+    }
+    async handleFetchWorkspacesRequest(request) {
+        const requestedSubscriptionId = request.subscribe?.subscriptionId?.trim();
+        const subscriptionId = resolveSubscriptionId(request.subscribe, requestedSubscriptionId);
+        try {
+            this.sessionLogger.debug({
+                requestId: request.requestId,
+                subscribeRequested: Boolean(request.subscribe),
+                filter: request.filter ?? null,
+                sort: request.sort ?? null,
+                page: request.page ?? null,
+            }, "fetch_workspaces_request_received");
+            if (subscriptionId) {
+                this.workspaceUpdatesSubscription = {
+                    subscriptionId,
+                    filter: request.filter,
+                    isBootstrapping: true,
+                    pendingUpdatesByWorkspaceId: new Map(),
+                    lastEmittedByWorkspaceId: new Map(),
+                };
+            }
+            const payload = await this.listFetchWorkspacesEntries(request);
+            this.workspaceGitObserver.syncObservers(payload.entries);
+            this.sessionLogger.debug({
+                requestId: request.requestId,
+                subscriptionId,
+                pageInfo: payload.pageInfo,
+                payload: summarizeFetchWorkspacesEntries(payload.entries),
+            }, "fetch_workspaces_response_ready");
+            const snapshot = this.buildBootstrapSnapshot(payload.entries);
+            this.emit({
+                type: "fetch_workspaces_response",
+                payload: {
+                    requestId: request.requestId,
+                    ...(subscriptionId ? { subscriptionId } : {}),
+                    ...payload,
+                },
+            });
+            if (subscriptionId && this.workspaceUpdatesSubscription?.subscriptionId === subscriptionId) {
+                this.flushBootstrappedWorkspaceUpdates(snapshot);
+                void this.reconcileAndEmitWorkspaceUpdates();
+            }
+        }
+        catch (error) {
+            if (subscriptionId && this.workspaceUpdatesSubscription?.subscriptionId === subscriptionId) {
+                this.workspaceUpdatesSubscription = null;
+            }
+            const code = error instanceof SessionRequestError ? error.code : "fetch_workspaces_failed";
+            const message = error instanceof Error ? error.message : "Failed to fetch workspaces";
+            this.sessionLogger.error({ err: error }, "Failed to handle fetch_workspaces_request");
+            this.emit({
+                type: "rpc_error",
+                payload: {
+                    requestId: request.requestId,
+                    requestType: request.type,
+                    error: message,
+                    code,
+                },
+            });
+        }
+    }
+    // Build the bootstrap snapshot used by `flushBootstrappedWorkspaceUpdates`
+    // to decide which pending updates to drop. Captures the status,
+    // statusEnteredAt, and activityAt (parsed to ms) for each workspace entry
+    // so a status-only change (e.g. the unmask case), a statusEnteredAt-only
+    // change (e.g. a fresh unmask time), AND a fresher activity all still
+    // ship to the client.
+    buildBootstrapSnapshot(entries) {
+        const snapshotByWorkspaceId = new Map();
+        for (const entry of entries) {
+            const parsedActivity = entry.activityAt ? Date.parse(entry.activityAt) : null;
+            snapshotByWorkspaceId.set(entry.id, {
+                status: entry.status,
+                statusEnteredAt: entry.statusEnteredAt ?? null,
+                activityAtMs: Number.isNaN(parsedActivity) ? null : parsedActivity,
+            });
+        }
+        return { snapshotByWorkspaceId };
+    }
+    async registerWorkspaceForImportedAgent(workspace) {
+        try {
+            await this.syncWorkspaceGitObserverForWorkspace(workspace);
+            await this.describeWorkspaceRecord(workspace);
+            await this.emitWorkspaceUpdateForWorkspaceId(workspace.workspaceId);
+        }
+        catch (error) {
+            this.sessionLogger.warn({ err: error, workspaceId: workspace.workspaceId, cwd: workspace.cwd }, "Failed to register workspace for imported agent");
+        }
+    }
+    async handleWorkspaceCreateRequest(request) {
+        try {
+            if (request.source.kind === "directory") {
+                await this.handleWorkspaceCreateLocal(request);
+                return;
+            }
+            await this.handleWorkspaceCreateWorktree(request);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Failed to create workspace";
+            this.sessionLogger.error({ err: error, sourceKind: request.source.kind, requestId: request.requestId }, "Failed to create workspace");
+            this.emit({
+                type: "workspace.create.response",
+                payload: {
+                    requestId: request.requestId,
+                    workspace: null,
+                    setupTerminalId: null,
+                    error: message,
+                },
+            });
+        }
+    }
+    async handleWorkspaceCreateLocal(request) {
+        if (request.source.kind !== "directory") {
+            return;
+        }
+        const cwd = expandTilde(request.source.path);
+        const directoryExists = await this.filesystem.isDirectory(cwd).catch(() => false);
+        if (!directoryExists) {
+            this.emit({
+                type: "workspace.create.response",
+                payload: {
+                    requestId: request.requestId,
+                    workspace: null,
+                    setupTerminalId: null,
+                    error: `Directory not found: ${cwd}`,
+                    errorCode: "directory_not_found",
+                },
+            });
+            return;
+        }
+        const explicitTitle = request.title?.trim() || null;
+        const promptTitle = resolveFirstAgentPromptTitle(request.firstAgentContext);
+        const workspace = await createLocalCheckoutWorkspace({ cwd, title: explicitTitle ?? promptTitle }, {
+            projectRegistry: this.projectRegistry,
+            workspaceRegistry: this.workspaceRegistry,
+            workspaceGitService: this.workspaceGitService,
+        });
+        await this.syncWorkspaceGitObserverForWorkspace(workspace);
+        const descriptor = await this.describeWorkspaceRecord(workspace);
+        this.emit({
+            type: "workspace.create.response",
+            payload: {
+                requestId: request.requestId,
+                workspace: descriptor,
+                setupTerminalId: null,
+                error: null,
+            },
+        });
+        await this.emitWorkspaceUpdateForWorkspaceId(workspace.workspaceId);
+        void this.workspaceGitService
+            .getSnapshot(workspace.cwd, { force: true, includeGitHub: true, reason: "open_project" })
+            .catch((error) => {
+            this.sessionLogger.warn({ err: error, cwd: workspace.cwd }, "Background snapshot refresh failed after workspace.create");
+        });
+        if (request.firstAgentContext) {
+            const firstAgentContext = request.firstAgentContext;
+            this.workspaceAutoName.scheduleForDirectory({
+                workspaceId: workspace.workspaceId,
+                cwd: workspace.cwd,
+                firstAgentContext,
+            }, { currentSelection: this.getFocusedAgentSelectionForCwd(workspace.cwd) });
+        }
+    }
+    async handleWorkspaceCreateWorktree(request) {
+        if (request.source.kind !== "worktree") {
+            return;
+        }
+        const source = request.source;
+        if (!source.cwd && !source.projectId) {
+            this.emit({
+                type: "workspace.create.response",
+                payload: {
+                    requestId: request.requestId,
+                    workspace: null,
+                    setupTerminalId: null,
+                    error: "cwd or projectId is required for a worktree-backed workspace",
+                    errorCode: "source_required",
+                },
+            });
+            return;
+        }
+        const sourceCwd = await this.resolveWorktreeSourceCwd({
+            cwd: source.cwd,
+            projectId: source.projectId,
+        });
+        const result = await this.createOttoWorktreeWorkflow({
+            cwd: sourceCwd,
+            projectId: source.projectId,
+            worktreeSlug: source.worktreeSlug,
+            action: source.action,
+            refName: source.refName,
+            githubPrNumber: source.githubPrNumber,
+            firstAgentContext: request.firstAgentContext,
+        }, source.baseBranch
+            ? { resolveDefaultBranch: async () => source.baseBranch }
+            : undefined);
+        if (request.title?.trim()) {
+            await this.workspaceRegistry.upsert({
+                ...result.workspace,
+                title: request.title.trim(),
+                updatedAt: new Date().toISOString(),
+            });
+            result.workspace.title = request.title.trim();
+        }
+        const descriptor = await this.describeCreatedWorktreeWorkspace(result);
+        this.emit({
+            type: "workspace.create.response",
+            payload: {
+                requestId: request.requestId,
+                workspace: descriptor,
+                setupTerminalId: null,
+                error: null,
+            },
+        });
+        this.emit({
+            type: "workspace_update",
+            payload: { kind: "upsert", workspace: descriptor },
+        });
+    }
+    async resolveWorktreeSourceCwd(input) {
+        if (input.cwd) {
+            return expandTilde(input.cwd);
+        }
+        const project = await this.projectRegistry.get(input.projectId);
+        if (!project || project.archivedAt) {
+            throw new Error(`Project not found: ${input.projectId}`);
+        }
+        return project.rootPath;
+    }
+    async handleOpenProjectRequest(request) {
+        const requestedCwd = request.cwd;
+        const cwd = expandTilde(requestedCwd);
+        const directoryExists = await this.filesystem.isDirectory(cwd).catch(() => false);
+        if (!directoryExists) {
+            this.sessionLogger.info({ requestedCwd, resolvedCwd: cwd, reason: "directory_not_found" }, "Open project rejected");
+            this.emit({
+                type: "open_project_response",
+                payload: {
+                    requestId: request.requestId,
+                    workspace: null,
+                    error: `Directory not found: ${cwd}`,
+                    errorCode: "directory_not_found",
+                },
+            });
+            return;
+        }
+        try {
+            const projectsBefore = new Map();
+            for (const project of await this.projectRegistry.list()) {
+                projectsBefore.set(project.projectId, project);
+            }
+            const workspacesBefore = new Map();
+            for (const workspaceRecord of await this.workspaceRegistry.list()) {
+                workspacesBefore.set(workspaceRecord.workspaceId, workspaceRecord);
+            }
+            const workspace = await this.workspaceProvisioning.findOrCreateWorkspaceForDirectory(cwd);
+            const project = await this.projectRegistry.get(workspace.projectId);
+            await this.syncWorkspaceGitObserverForWorkspace(workspace);
+            const descriptor = await this.describeWorkspaceRecord(workspace);
+            await this.emitWorkspaceUpdateForWorkspaceId(workspace.workspaceId);
+            this.sessionLogger.info({
+                requestedCwd,
+                resolvedCwd: cwd,
+                workspaceCwd: workspace.cwd,
+                workspaceId: workspace.workspaceId,
+                workspaceKind: workspace.kind,
+                workspaceTransition: describeRegistryTransition(workspacesBefore.get(workspace.workspaceId) ?? null),
+                projectId: workspace.projectId,
+                projectKind: project?.kind ?? null,
+                projectTransition: describeRegistryTransition(projectsBefore.get(workspace.projectId) ?? null),
+            }, "Project opened");
+            this.emit({
+                type: "open_project_response",
+                payload: {
+                    requestId: request.requestId,
+                    workspace: descriptor,
+                    error: null,
+                },
+            });
+            void this.workspaceGitService
+                .getSnapshot(workspace.cwd, {
+                force: true,
+                includeGitHub: true,
+                reason: "open_project",
+            })
+                .catch((error) => {
+                this.sessionLogger.warn({ err: error, cwd: workspace.cwd }, "Background snapshot refresh failed after open_project");
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Failed to open project";
+            this.sessionLogger.error({ err: error, cwd }, "Failed to open project");
+            this.emit({
+                type: "open_project_response",
+                payload: {
+                    requestId: request.requestId,
+                    workspace: null,
+                    error: message,
+                },
+            });
+        }
+    }
+    async handleProjectAddRequest(request) {
+        const requestedCwd = request.cwd;
+        const cwd = expandTilde(requestedCwd);
+        const directoryExists = await this.filesystem.isDirectory(cwd).catch(() => false);
+        if (!directoryExists) {
+            this.sessionLogger.info({ requestedCwd, resolvedCwd: cwd, reason: "directory_not_found" }, "Add project rejected");
+            this.emit({
+                type: "project.add.response",
+                payload: {
+                    requestId: request.requestId,
+                    project: null,
+                    error: `Directory not found: ${cwd}`,
+                    errorCode: "directory_not_found",
+                },
+            });
+            return;
+        }
+        try {
+            const projectsBefore = new Map();
+            for (const project of await this.projectRegistry.list()) {
+                projectsBefore.set(project.projectId, project);
+            }
+            const project = await this.workspaceProvisioning.findOrCreateProjectForDirectory(cwd);
+            this.sessionLogger.info({
+                requestedCwd,
+                resolvedCwd: cwd,
+                projectId: project.projectId,
+                projectKind: project.kind,
+                projectTransition: describeRegistryTransition(projectsBefore.get(project.projectId) ?? null),
+            }, "Project added");
+            this.emit({
+                type: "project.add.response",
+                payload: {
+                    requestId: request.requestId,
+                    project: this.buildProjectDescriptor(project),
+                    error: null,
+                },
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Failed to add project";
+            this.sessionLogger.error({ err: error, cwd }, "Failed to add project");
+            this.emit({
+                type: "project.add.response",
+                payload: {
+                    requestId: request.requestId,
+                    project: null,
+                    error: message,
+                },
+            });
+        }
+    }
+    // Named accessor: the workspace descriptor builder and the git-watch test both read a workspace's
+    // scripts snapshot through here; the workspace-scripts module owns the payload assembly.
+    buildWorkspaceScriptPayloadSnapshot(workspaceId, workspaceDirectory) {
+        return this.workspaceScripts.buildSnapshot(workspaceId, workspaceDirectory);
+    }
+    handleStartWorkspaceScriptRequest(request) {
+        return this.workspaceScripts.start(request);
+    }
+    // COMPAT(desktopEditorBridge): added in v0.1.88, remove after 2026-12-03 once old clients no longer call daemon editor RPCs.
+    async handleLegacyListAvailableEditorsRequest(request) {
+        this.emit({
+            type: "list_available_editors_response",
+            payload: {
+                requestId: request.requestId,
+                editors: [],
+                error: "Editor opening moved to the desktop app and is no longer supported by the daemon",
+            },
+        });
+    }
+    async handleLegacyOpenInEditorRequest(request) {
+        this.emit({
+            type: "open_in_editor_response",
+            payload: {
+                requestId: request.requestId,
+                error: "Editor opening moved to the desktop app and is no longer supported by the daemon",
+            },
+        });
+    }
+    async handleCreateOttoWorktreeRequest(request) {
+        return handleCreateWorktreeRequest({
+            ottoHome: this.ottoHome,
+            worktreesRoot: this.worktreesRoot,
+            describeWorkspaceRecord: (result) => this.describeCreatedWorktreeWorkspace(result),
+            emit: (message) => this.emit(message),
+            sessionLogger: this.sessionLogger,
+            createOttoWorktreeWorkflow: (input) => this.createOttoWorktreeWorkflow(input),
+        }, request);
+    }
+    async createOttoWorktreeWorkflow(input, options) {
+        return createWorktreeWorkflow({
+            ottoHome: this.ottoHome,
+            worktreesRoot: this.worktreesRoot,
+            createOttoWorktree: (workflowInput, serviceOptions) => this.createOttoWorktree(workflowInput, serviceOptions),
+            warmWorkspaceGitData: (workspace) => this.warmWorkspaceGitDataForWorkspace(workspace),
+            autoNameWorkspaceBranchForFirstAgent: (autoNameInput) => this.workspaceAutoName.scheduleForWorktree(autoNameInput, {
+                currentSelection: this.getFocusedAgentSelectionForCwd(autoNameInput.workspace.cwd),
+            }),
+            emitWorkspaceUpdateForWorkspaceId: (workspaceId) => this.emitWorkspaceUpdateForWorkspaceId(workspaceId),
+            cacheWorkspaceSetupSnapshot: (workspaceId, snapshot) => {
+                this.workspaceSetupSnapshots.set(workspaceId, snapshot);
+            },
+            emit: (message) => this.emit(message),
+            sessionLogger: this.sessionLogger,
+            terminalManager: this.terminalManager,
+            archiveWorkspaceRecord: (workspaceId) => this.archiveWorkspaceRecord(workspaceId),
+            serviceProxy: this.serviceProxy,
+            scriptRuntimeStore: this.scriptRuntimeStore,
+            getDaemonTcpPort: this.getDaemonTcpPort,
+            getDaemonTcpHost: this.getDaemonTcpHost,
+            serviceProxyPublicBaseUrl: this.serviceProxyPublicBaseUrl,
+            onScriptsChanged: (workspaceId, workspaceDirectory) => {
+                this.workspaceScripts.emitStatusUpdate(workspaceId, workspaceDirectory);
+            },
+        }, input, options);
+    }
+    async handleWorkspaceSetupStatusRequest(request) {
+        return handleWorkspaceSetupStatusRequestMessage({
+            emit: (message) => this.emit(message),
+            workspaceSetupSnapshots: this.workspaceSetupSnapshots,
+        }, request);
+    }
+    async handleArchiveWorkspaceRequest(request) {
+        try {
+            const existing = await this.workspaceRegistry.get(request.workspaceId);
+            if (!existing) {
+                throw new Error(`Workspace not found: ${request.workspaceId}`);
+            }
+            const gitSnapshot = await this.workspaceGitService
+                .getSnapshot(existing.cwd)
+                .catch(() => null);
+            const repoRoot = gitSnapshot?.git?.repoRoot ?? null;
+            await archiveByScope({
+                ottoHome: this.ottoHome,
+                ottoWorktreesBaseRoot: this.worktreesRoot,
+                github: this.github,
+                workspaceGitService: this.workspaceGitService,
+                agentManager: this.agentManager,
+                agentStorage: this.agentStorage,
+                findWorkspaceIdForCwd: (cwd) => this.findWorkspaceIdForCwd(cwd),
+                listActiveWorkspaces: () => this.listActiveWorkspaceRefs(),
+                archiveWorkspaceRecord: (workspaceId) => this.archiveWorkspaceRecord(workspaceId),
+                emitWorkspaceUpdatesForWorkspaceIds: (workspaceIds) => this.emitWorkspaceUpdatesForWorkspaceIds(workspaceIds),
+                markWorkspaceArchiving: (workspaceIds, archivingAt) => this.markWorkspaceArchiving(workspaceIds, archivingAt),
+                clearWorkspaceArchiving: (workspaceIds) => this.clearWorkspaceArchiving(workspaceIds),
+                killTerminalsForWorkspace: (workspaceId) => this.terminalController.killTerminalsForWorkspace(workspaceId),
+                sessionLogger: this.sessionLogger,
+            }, {
+                scope: { kind: "workspace", workspaceId: existing.workspaceId },
+                repoRoot,
+                ottoWorktreesBaseRoot: this.worktreesRoot,
+                requestId: request.requestId,
+            });
+            const archivedWorkspace = await this.workspaceRegistry.get(request.workspaceId);
+            const archivedAt = archivedWorkspace?.archivedAt ?? new Date().toISOString();
+            this.emit({
+                type: "archive_workspace_response",
+                payload: {
+                    requestId: request.requestId,
+                    workspaceId: request.workspaceId,
+                    archivedAt,
+                    error: null,
+                },
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Failed to archive workspace";
+            this.sessionLogger.error({ err: error, workspaceId: request.workspaceId }, "Failed to archive workspace");
+            this.emit({
+                type: "archive_workspace_response",
+                payload: {
+                    requestId: request.requestId,
+                    workspaceId: request.workspaceId,
+                    archivedAt: null,
+                    error: message,
+                },
+            });
+        }
+    }
+    async handleWorkspaceClearAttentionRequest(request) {
+        const { requestId, workspaceId } = request;
+        const requestedWorkspaceIds = Array.isArray(workspaceId) ? workspaceId : [workspaceId];
+        let agents;
+        try {
+            agents = await this.listAgentPayloads();
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            const results = requestedWorkspaceIds.map((requestedWorkspaceId) => ({
+                workspaceId: requestedWorkspaceId,
+                clearedAgentIds: [],
+                success: false,
+                error: message,
+            }));
+            this.emit({
+                type: "workspace.clear_attention.response",
+                payload: {
+                    requestId,
+                    workspaceId,
+                    clearedAgentIds: [],
+                    results,
+                    success: false,
+                    error: message,
+                },
+            });
+            return;
+        }
+        const results = [];
+        for (const requestedWorkspaceId of requestedWorkspaceIds) {
+            const clearedAgentIds = [];
+            try {
+                const workspace = await this.workspaceRegistry.get(requestedWorkspaceId);
+                if (!workspace || workspace.archivedAt) {
+                    throw new Error(`Workspace not found: ${requestedWorkspaceId}`);
+                }
+                // Clearing attention is scoped to the workspace that OWNS the agent, by
+                // workspaceId — never by comparing cwd strings. A sibling workspace
+                // sharing the same directory keeps its own agents' attention.
+                const clearableAgentIds = agents
+                    .filter((agent) => !agent.archivedAt)
+                    .filter((agent) => agent.workspaceId === workspace.workspaceId)
+                    .filter((agent) => agent.requiresAttention === true)
+                    .filter((agent) => (agent.pendingPermissions?.length ?? 0) === 0)
+                    .filter((agent) => agent.attentionReason !== "permission")
+                    .map((agent) => agent.id);
+                for (const agentId of clearableAgentIds) {
+                    const liveAgent = this.agentManager.getAgent(agentId);
+                    if (liveAgent) {
+                        await this.agentManager.clearAgentAttention(agentId);
+                        clearedAgentIds.push(agentId);
+                        continue;
+                    }
+                    const record = await this.agentStorage.get(agentId);
+                    if (!record ||
+                        record.internal ||
+                        record.archivedAt ||
+                        record.requiresAttention !== true) {
+                        continue;
+                    }
+                    const nextRecord = {
+                        ...record,
+                        updatedAt: new Date().toISOString(),
+                        requiresAttention: false,
+                        attentionReason: null,
+                        attentionTimestamp: null,
+                    };
+                    await this.agentStorage.upsert(nextRecord);
+                    const agent = this.buildStoredAgentPayload(nextRecord);
+                    const project = await this.buildProjectPlacementForWorkspace(workspace);
+                    this.emit({
+                        type: "agent_update",
+                        payload: {
+                            kind: "upsert",
+                            agent,
+                            project,
+                        },
+                    });
+                    clearedAgentIds.push(agentId);
+                }
+                await this.emitWorkspaceUpdateForWorkspaceId(workspace.workspaceId);
+                results.push({
+                    workspaceId: requestedWorkspaceId,
+                    clearedAgentIds,
+                    success: true,
+                    error: null,
+                });
+            }
+            catch (error) {
+                const message = getErrorMessage(error);
+                this.sessionLogger.error({ err: error, workspaceId: requestedWorkspaceId }, "Failed to clear workspace attention");
+                results.push({
+                    workspaceId: requestedWorkspaceId,
+                    clearedAgentIds,
+                    success: false,
+                    error: message,
+                });
+            }
+        }
+        const clearedAgentIds = results.flatMap((result) => result.clearedAgentIds);
+        const failedResults = results.filter((result) => !result.success);
+        this.emit({
+            type: "workspace.clear_attention.response",
+            payload: {
+                requestId,
+                workspaceId,
+                clearedAgentIds,
+                results,
+                success: failedResults.length === 0,
+                error: failedResults.length === 0
+                    ? null
+                    : failedResults
+                        .map((result) => result.error)
+                        .filter((error) => error !== null)
+                        .join("; "),
+            },
+        });
+    }
+    async handleFetchAgent(agentIdOrIdentifier, requestId) {
+        const resolved = await this.resolveAgentIdentifier(agentIdOrIdentifier);
+        if (!resolved.ok) {
+            this.emit({
+                type: "fetch_agent_response",
+                payload: { requestId, agent: null, project: null, error: resolved.error },
+            });
+            return;
+        }
+        const agent = await this.getAgentPayloadById(resolved.agentId);
+        if (!agent) {
+            this.emit({
+                type: "fetch_agent_response",
+                payload: {
+                    requestId,
+                    agent: null,
+                    project: null,
+                    error: `Agent not found: ${resolved.agentId}`,
+                },
+            });
+            return;
+        }
+        const project = agent.workspaceId
+            ? await this.buildProjectPlacementForWorkspaceId(agent.workspaceId)
+            : null;
+        this.emit({
+            type: "fetch_agent_response",
+            payload: { requestId, agent, project, error: null },
+        });
+    }
+    shouldUseFullTimelineForProjectedPage(input) {
+        const { timeline } = input;
+        if (timeline.reset || timeline.rows.length === 0 || !timeline.hasOlder) {
+            return false;
+        }
+        const firstRow = timeline.rows[0];
+        if (firstRow?.item.type === "assistant_message" ||
+            firstRow?.item.type === "reasoning" ||
+            firstRow?.item.type === "tool_call") {
+            return true;
+        }
+        return timeline.rows.some((row) => row.item.type === "tool_call");
+    }
+    selectCanonicalTimelineProjection(input) {
+        const entries = projectTimelineRows({ rows: input.timeline.rows, mode: "canonical" });
+        return {
+            timeline: input.timeline,
+            entries,
+            startSeq: entries[0]?.seqStart ?? null,
+            endSeq: entries[entries.length - 1]?.seqEnd ?? null,
+            hasOlder: input.timeline.hasOlder,
+            hasNewer: input.timeline.hasNewer,
+        };
+    }
+    selectProjectedTimelineProjection(input) {
+        const timeline = this.shouldUseFullTimelineForProjectedPage({
+            timeline: input.controlTimeline,
+        })
+            ? this.agentManager.fetchTimeline(input.agentId, { direction: "tail", limit: 0 })
+            : input.controlTimeline;
+        const page = selectProjectedTimelinePage({
+            rows: timeline.rows,
+            bounds: timeline.window,
+            direction: input.controlTimeline.reset ? "tail" : input.direction,
+            ...(input.cursor ? { cursorSeq: input.cursor.seq } : {}),
+            limit: input.pageLimit,
+        });
+        return {
+            timeline,
+            entries: page.entries,
+            startSeq: page.startSeq,
+            endSeq: page.endSeq,
+            hasOlder: page.hasOlder || (page.startSeq !== null && page.startSeq > timeline.window.minSeq),
+            hasNewer: page.hasNewer,
+        };
+    }
+    selectTimelineProjection(input) {
+        if (input.projection === "canonical") {
+            return this.selectCanonicalTimelineProjection({ timeline: input.controlTimeline });
+        }
+        return this.selectProjectedTimelineProjection(input);
+    }
+    async handleFetchAgentTimelineRequest(msg) {
+        const direction = msg.direction ?? (msg.cursor ? "after" : "tail");
+        const projection = msg.projection ?? "projected";
+        const requestedLimit = msg.limit;
+        const pageLimit = requestedLimit ?? (direction === "after" ? 0 : 200);
+        const cursor = msg.cursor
+            ? {
+                epoch: msg.cursor.epoch,
+                seq: msg.cursor.seq,
+            }
+            : undefined;
+        try {
+            // Observed subagents have no ManagedAgent or stored record; serve their
+            // last emitted snapshot instead. See projects/observed-subagents/observed-subagents.md.
+            const observedPayload = this.agentManager.getObservedSubagentPayload(msg.agentId);
+            const agentPayload = observedPayload ??
+                (await this.buildAgentPayload(await ensureAgentLoaded(msg.agentId, {
+                    agentManager: this.agentManager,
+                    agentStorage: this.agentStorage,
+                    logger: this.sessionLogger,
+                })));
+            const controlTimeline = this.agentManager.fetchTimeline(msg.agentId, {
+                direction,
+                cursor,
+                limit: pageLimit,
+            });
+            const selectedTimeline = this.selectTimelineProjection({
+                agentId: msg.agentId,
+                projection,
+                controlTimeline,
+                direction,
+                ...(cursor ? { cursor } : {}),
+                pageLimit,
+            });
+            const startCursor = selectedTimeline.startSeq !== null
+                ? { epoch: selectedTimeline.timeline.epoch, seq: selectedTimeline.startSeq }
+                : null;
+            const endCursor = selectedTimeline.endSeq !== null
+                ? { epoch: selectedTimeline.timeline.epoch, seq: selectedTimeline.endSeq }
+                : null;
+            this.emit({
+                type: "fetch_agent_timeline_response",
+                payload: {
+                    requestId: msg.requestId,
+                    agentId: msg.agentId,
+                    agent: agentPayload,
+                    direction,
+                    projection,
+                    epoch: selectedTimeline.timeline.epoch,
+                    reset: controlTimeline.reset,
+                    staleCursor: controlTimeline.staleCursor,
+                    gap: controlTimeline.gap,
+                    window: selectedTimeline.timeline.window,
+                    startCursor,
+                    endCursor,
+                    hasOlder: selectedTimeline.hasOlder,
+                    hasNewer: selectedTimeline.hasNewer,
+                    entries: selectedTimeline.entries.map((entry) => ({
+                        provider: agentPayload.provider,
+                        item: entry.item,
+                        timestamp: entry.timestamp,
+                        seqStart: entry.seqStart,
+                        seqEnd: entry.seqEnd,
+                        sourceSeqRanges: entry.sourceSeqRanges,
+                        collapsed: this.supports(CLIENT_CAPS.reasoningMergeEnum)
+                            ? entry.collapsed
+                            : entry.collapsed.filter((value) => value !== "reasoning_merge"),
+                    })),
+                    error: null,
+                },
+            });
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, agentId: msg.agentId }, "Failed to handle fetch_agent_timeline_request");
+            this.emit({
+                type: "fetch_agent_timeline_response",
+                payload: {
+                    requestId: msg.requestId,
+                    agentId: msg.agentId,
+                    agent: null,
+                    direction,
+                    projection,
+                    epoch: "",
+                    reset: false,
+                    staleCursor: false,
+                    gap: false,
+                    window: { minSeq: 0, maxSeq: 0, nextSeq: 0 },
+                    startCursor: null,
+                    endCursor: null,
+                    hasOlder: false,
+                    hasNewer: false,
+                    entries: [],
+                    error: error instanceof Error ? error.message : String(error),
+                },
+            });
+        }
+    }
+    async handleAgentForkContextRequest(msg) {
+        try {
+            const snapshot = await ensureAgentLoaded(msg.agentId, {
+                agentManager: this.agentManager,
+                agentStorage: this.agentStorage,
+                logger: this.sessionLogger,
+            });
+            const agentPayload = await this.buildAgentPayload(snapshot);
+            const rows = this.agentManager.fetchTimeline(msg.agentId, {
+                direction: "tail",
+                limit: 0,
+            }).rows;
+            const forkContext = buildAgentForkContextAttachment({
+                rows,
+                boundaryMessageId: msg.boundaryMessageId,
+                agentTitle: agentPayload.title,
+                cwd: snapshot.cwd,
+            });
+            this.emit({
+                type: "agent.fork_context.response",
+                payload: {
+                    requestId: msg.requestId,
+                    agentId: msg.agentId,
+                    attachment: forkContext.attachment,
+                    itemCount: forkContext.itemCount,
+                    boundaryMessageId: forkContext.boundaryMessageId,
+                    error: null,
+                },
+            });
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, agentId: msg.agentId }, "Failed to handle agent.fork_context.request");
+            this.emit({
+                type: "agent.fork_context.response",
+                payload: {
+                    requestId: msg.requestId,
+                    agentId: msg.agentId,
+                    attachment: null,
+                    itemCount: 0,
+                    boundaryMessageId: msg.boundaryMessageId ?? null,
+                    error: error instanceof Error ? error.message : String(error),
+                },
+            });
+        }
+    }
+    async handleSendAgentMessageRequest(msg) {
+        const resolved = await this.resolveAgentIdentifier(msg.agentId);
+        if (!resolved.ok) {
+            this.emit({
+                type: "send_agent_message_response",
+                payload: {
+                    requestId: msg.requestId,
+                    agentId: msg.agentId,
+                    accepted: false,
+                    error: resolved.error,
+                },
+            });
+            return;
+        }
+        try {
+            const agentId = resolved.agentId;
+            const prompt = this.buildAgentPrompt(msg.text, msg.images, msg.attachments);
+            this.sessionLogger.trace({
+                agentId,
+                messageId: msg.messageId,
+                textPrefix: msg.text.slice(0, 80),
+            }, "agent.session.send_agent_message");
+            let dispatchResult;
+            try {
+                dispatchResult = await sendPromptToAgent({
+                    agentManager: this.agentManager,
+                    agentStorage: this.agentStorage,
+                    agentId,
+                    prompt,
+                    messageId: msg.messageId,
+                    logger: this.sessionLogger,
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                this.handleAgentRunError(agentId, error, "Failed to send agent message");
+                this.emit({
+                    type: "send_agent_message_response",
+                    payload: {
+                        requestId: msg.requestId,
+                        agentId,
+                        accepted: false,
+                        error: message,
+                    },
+                });
+                return;
+            }
+            if (dispatchResult.outOfBand) {
+                this.emit({
+                    type: "send_agent_message_response",
+                    payload: {
+                        requestId: msg.requestId,
+                        agentId,
+                        accepted: true,
+                        error: null,
+                    },
+                });
+                return;
+            }
+            try {
+                await waitForAgentRunStartWithTimeout(this.agentManager, agentId);
+            }
+            catch (error) {
+                this.emit({
+                    type: "send_agent_message_response",
+                    payload: {
+                        requestId: msg.requestId,
+                        agentId,
+                        accepted: false,
+                        error: errorToFriendlyMessage(error),
+                    },
+                });
+                return;
+            }
+            this.emit({
+                type: "send_agent_message_response",
+                payload: {
+                    requestId: msg.requestId,
+                    agentId,
+                    accepted: true,
+                    error: null,
+                },
+            });
+        }
+        catch (error) {
+            this.emit({
+                type: "send_agent_message_response",
+                payload: {
+                    requestId: msg.requestId,
+                    agentId: resolved.agentId,
+                    accepted: false,
+                    error: errorToFriendlyMessage(error),
+                },
+            });
+        }
+    }
+    async handleWaitForFinish(agentIdOrIdentifier, requestId, timeoutMs) {
+        const resolved = await this.resolveAgentIdentifier(agentIdOrIdentifier);
+        if (!resolved.ok) {
+            this.emit({
+                type: "wait_for_finish_response",
+                payload: {
+                    requestId,
+                    status: "error",
+                    final: null,
+                    error: resolved.error,
+                    lastMessage: null,
+                },
+            });
+            return;
+        }
+        const agentId = resolved.agentId;
+        const live = this.agentManager.getAgent(agentId);
+        if (!live) {
+            const record = await this.agentStorage.get(agentId);
+            if (!record || record.internal) {
+                this.emit({
+                    type: "wait_for_finish_response",
+                    payload: {
+                        requestId,
+                        status: "error",
+                        final: null,
+                        error: `Agent not found: ${agentId}`,
+                        lastMessage: null,
+                    },
+                });
+                return;
+            }
+            const final = this.buildStoredAgentPayload(record);
+            let status;
+            if (record.attentionReason === "permission") {
+                status = "permission";
+            }
+            else if (record.lastStatus === "error") {
+                status = "error";
+            }
+            else {
+                status = "idle";
+            }
+            const error = resolveWaitForFinishError({ status, final });
+            this.emit({
+                type: "wait_for_finish_response",
+                payload: { requestId, status, final, error, lastMessage: null },
+            });
+            return;
+        }
+        const abortController = new AbortController();
+        const hasTimeout = typeof timeoutMs === "number" && timeoutMs > 0;
+        const timeoutHandle = hasTimeout
+            ? setTimeout(() => {
+                abortController.abort("timeout");
+            }, timeoutMs)
+            : null;
+        try {
+            let result = await this.agentManager.waitForAgentEvent(agentId, {
+                signal: abortController.signal,
+                waitForActive: true,
+            });
+            let final = await this.getAgentPayloadById(agentId);
+            if (!final) {
+                throw new Error(`Agent ${agentId} disappeared while waiting`);
+            }
+            let status;
+            if (result.permission) {
+                status = "permission";
+            }
+            else if (result.status === "error") {
+                status = "error";
+            }
+            else {
+                status = "idle";
+            }
+            const error = resolveWaitForFinishError({ status, final });
+            this.emit({
+                type: "wait_for_finish_response",
+                payload: { requestId, status, final, error, lastMessage: result.lastMessage },
+            });
+        }
+        catch (error) {
+            const isAbort = error instanceof Error &&
+                (error.name === "AbortError" || error.message.toLowerCase().includes("aborted"));
+            if (!isAbort) {
+                const message = errorToFriendlyMessage(error);
+                this.sessionLogger.error({ err: error, agentId }, "wait_for_finish_request failed");
+                const final = await this.getAgentPayloadById(agentId);
+                this.emit({
+                    type: "wait_for_finish_response",
+                    payload: {
+                        requestId,
+                        status: "error",
+                        final,
+                        error: message,
+                        lastMessage: null,
+                    },
+                });
+                return;
+            }
+            const final = await this.getAgentPayloadById(agentId);
+            if (!final) {
+                throw new Error(`Agent ${agentId} disappeared while waiting`, { cause: error });
+            }
+            this.emit({
+                type: "wait_for_finish_response",
+                payload: { requestId, status: "timeout", final, error: null, lastMessage: null },
+            });
+        }
+        finally {
+            if (timeoutHandle) {
+                clearTimeout(timeoutHandle);
+            }
+        }
+    }
+    /**
+     * Emit a message to the client
+     */
+    emit(msg) {
+        // JSON.stringify(msg) is only computed when trace is enabled — it runs for
+        // every outbound message otherwise, and trace is disabled by default.
+        // Optional-chained because test logger stubs don't implement isLevelEnabled.
+        if (this.sessionLogger.isLevelEnabled?.("trace")) {
+            this.sessionLogger.trace({
+                messageType: msg.type,
+                payloadBytes: JSON.stringify(msg).length,
+            }, "agent.session.outbound");
+        }
+        this.onMessage(msg);
+    }
+    emitBinary(frame) {
+        if (!this.onBinaryMessage) {
+            return;
+        }
+        try {
+            this.onBinaryMessage(frame);
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error }, "Failed to emit binary frame");
+        }
+    }
+    /**
+     * Clean up session resources
+     */
+    async cleanup() {
+        this.sessionLogger.trace({}, "agent.session.lifecycle.cleanup");
+        if (this.unsubscribeAgentEvents) {
+            this.unsubscribeAgentEvents();
+            this.unsubscribeAgentEvents = null;
+        }
+        this.agentUpdates.dispose();
+        if (this.unsubscribeTerminalWorkspaceContributionEvents) {
+            this.unsubscribeTerminalWorkspaceContributionEvents();
+            this.unsubscribeTerminalWorkspaceContributionEvents = null;
+        }
+        this.providerCatalogSession.dispose();
+        await this.voiceSession.cleanup();
+        this.terminalController.dispose();
+        this.checkoutSession.cleanup();
+        this.workspaceGitObserver.dispose();
+        this.workspaceFilesSession.dispose();
+        this.artifactSession.stop();
+    }
+}
+//# sourceMappingURL=session.js.map