@getpaseo/server 0.1.62 → 0.1.65

package/dist/server/server/session.js

@@ -2,13 +2,16 @@ import equal from "fast-deep-equal";
 import { v4 as uuidv4 } from "uuid";
 import { TTLCache } from "@isaacs/ttlcache";
 import pMemoize from "p-memoize";
-import { resolve, sep } from "path";
+import { realpathSync } from "node:fs";
+import { basename, resolve, sep } from "path";
 import { homedir } from "node:os";
 import { z } from "zod";
+import { CLIENT_CAPS } from "../shared/client-capabilities.js";
 import { isLegacyEditorTargetId, serializeAgentStreamEvent, } from "./messages.js";
-import { captureTerminalLines } from "../terminal/terminal.js";
-import { TerminalOutputCoalescer } from "../terminal/terminal-output-coalescer.js";
-import { TerminalStreamOpcode, encodeTerminalSnapshotPayload, encodeTerminalStreamFrame, decodeTerminalResizePayload, } from "../shared/terminal-stream-protocol.js";
+import { TerminalSessionController } from "../terminal/terminal-session-controller.js";
+import { encodeFileTransferFrame, FileTransferOpcode, } from "../shared/binary-frames/index.js";
+import { CursorError } from "./pagination/cursor.js";
+import { SortablePager } from "./pagination/sortable-pager.js";
 import { TTSManager } from "./agent/tts-manager.js";
 import { STTManager } from "./agent/stt-manager.js";
 import { maybePersistTtsDebugAudio } from "./agent/tts-debug.js";
@@ -16,14 +19,15 @@ import { isPaseoDictationDebugEnabled } from "./agent/recordings-debug.js";
 import { listAvailableEditorTargets, openInEditorTarget } from "./editor-targets.js";
 import { DictationStreamManager, } from "./dictation/dictation-stream-manager.js";
 import { createVoiceTurnController, } from "./voice/voice-turn-controller.js";
-import { buildConfigOverrides, extractTimestamps, toAgentPersistenceHandle, } from "./persistence-hooks.js";
+import { buildConfigOverrides, extractTimestamps, isStoredAgentProviderAvailable, toAgentPersistenceHandle, } from "./persistence-hooks.js";
 import { ensureAgentLoaded } from "./agent/agent-loading.js";
 import { sendPromptToAgent, unarchiveAgentState } from "./agent/mcp-shared.js";
 import { experimental_createMCPClient } from "ai";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { buildWorkspaceScriptPayloads } from "./script-status-projection.js";
+import { buildWorkspaceScriptPayloads, readPaseoConfigForProjection, } from "./script-status-projection.js";
 import { deriveProjectSlug } from "./workspace-git-metadata.js";
 import { spawnWorkspaceScript } from "./worktree-bootstrap.js";
+import { applyMutableProviderConfigToOverrides } from "./daemon-config-store.js";
 import { buildProviderRegistry } from "./agent/provider-registry.js";
 import { resolveSnapshotCwd } from "./agent/provider-snapshot-manager.js";
 import { scheduleAgentMetadataGeneration } from "./agent/agent-metadata-generator.js";
@@ -32,12 +36,12 @@ import { MAX_EXPLICIT_AGENT_TITLE_CHARS } from "./agent/agent-title-limits.js";
 import { appendTimelineItemIfAgentKnown, emitLiveTimelineItemIfAgentKnown, } from "./agent/timeline-append.js";
 import { projectTimelineRows, selectTimelineWindowByProjectedLimit, } from "./agent/timeline-projection.js";
 import { DEFAULT_STRUCTURED_GENERATION_PROVIDERS, StructuredAgentFallbackError, StructuredAgentResponseError, generateStructuredAgentResponseWithFallback, } from "./agent/agent-response-loop.js";
-import { checkoutLiteFromGitSnapshot, normalizeWorkspaceId as normalizePersistedWorkspaceId, deriveProjectGroupingName, deriveWorkspaceId, deriveProjectRootPath, deriveProjectKind, deriveWorkspaceKind, deriveWorkspaceDisplayName, buildProjectPlacementForCwd as buildProjectPlacementForCwdStandalone, } from "./workspace-registry-model.js";
+import { checkoutLiteFromGitSnapshot, normalizeWorkspaceId as normalizePersistedWorkspaceId, deriveProjectGroupingName, classifyDirectoryForProjectMembership, deriveWorkspaceDisplayName, } from "./workspace-registry-model.js";
 import { createPersistedProjectRecord, createPersistedWorkspaceRecord, } from "./workspace-registry.js";
 import { buildVoiceModeSystemPrompt, stripVoiceModeSystemPrompt, wrapSpokenInput, } from "./voice-config.js";
 import { isVoicePermissionAllowed } from "./voice-permission-policy.js";
-import { listDirectoryEntries, readExplorerFile, getDownloadableFileInfo, } from "./file-explorer/service.js";
-import { runAsyncWorktreeBootstrap } from "./worktree-bootstrap.js";
+import { listDirectoryEntries, readExplorerFile, readExplorerFileBytes, getDownloadableFileInfo, } from "./file-explorer/service.js";
+import { readPaseoConfigForEdit, writePaseoConfigForEdit, } from "../utils/paseo-config-file.js";
 import { archivePersistedWorkspaceRecord } from "./workspace-archive-service.js";
 import { WorkspaceReconciliationService } from "./workspace-reconciliation-service.js";
 import { checkoutResolvedBranch, commitChanges, mergeToBase, mergeFromBase, pullCurrentBranch, pushCurrentBranch, createPullRequest, } from "../utils/checkout-git.js";
@@ -51,19 +55,104 @@ import { ChatServiceError } from "./chat/chat-service.js";
 import { notifyChatMentions } from "./chat/chat-mentions.js";
 import { execCommand } from "../utils/spawn.js";
 import { createGitHubService, } from "../services/github-service.js";
-import { createPaseoWorktree, } from "./paseo-worktree-service.js";
+import { summarizeFetchWorkspacesEntries, WorkspaceDirectory, } from "./workspace-directory.js";
+import { attemptFirstAgentBranchAutoName, createPaseoWorktree, } from "./paseo-worktree-service.js";
 import { createWorktreeCoreDeps } from "./worktree-core.js";
-import { assertSafeGitRef as assertWorktreeSafeGitRef, buildAgentSessionConfig as buildWorktreeAgentSessionConfig, runWorktreeSetupInBackground as runWorktreeSetupInBackgroundSession, handleCreatePaseoWorktreeRequest as handleCreateWorktreeRequest, handlePaseoWorktreeArchiveRequest as handleWorktreeArchiveRequest, handlePaseoWorktreeListRequest as handleWorktreeListRequest, handleWorkspaceSetupStatusRequest as handleWorkspaceSetupStatusRequestMessage, } from "./worktree-session.js";
-import { killTerminalsUnderPath as killWorktreeTerminalsUnderPath } from "./paseo-worktree-archive-service.js";
+import { assertSafeGitRef as assertWorktreeSafeGitRef, buildAgentSessionConfig as buildWorktreeAgentSessionConfig, createPaseoWorktreeWorkflow as createWorktreeWorkflow, handleCreatePaseoWorktreeRequest as handleCreateWorktreeRequest, handlePaseoWorktreeArchiveRequest as handleWorktreeArchiveRequest, handlePaseoWorktreeListRequest as handleWorktreeListRequest, handleWorkspaceSetupStatusRequest as handleWorkspaceSetupStatusRequestMessage, } from "./worktree-session.js";
 import { toWorktreeWireError } from "./worktree-errors.js";
 const MAX_INITIAL_AGENT_TITLE_CHARS = Math.min(60, MAX_EXPLICIT_AGENT_TITLE_CHARS);
 const WORKSPACE_GIT_WATCH_REMOVED_STATE_KEY = "__removed__";
+async function resolveKnownProjectRootForConfig(input) {
+    const requestedRoot = canonicalizeConfigRoot(input.repoRoot);
+    const projects = await input.projectRegistry.list();
+    for (const project of projects) {
+        if (project.archivedAt !== null) {
+            continue;
+        }
+        const projectRoot = canonicalizeConfigRoot(project.rootPath);
+        if (requestedRoot === projectRoot) {
+            return projectRoot;
+        }
+    }
+    return null;
+}
+function canonicalizeConfigRoot(repoRoot) {
+    const resolved = resolve(repoRoot);
+    try {
+        return stripTrailingPathSeparators(realpathSync(resolved));
+    }
+    catch {
+        return stripTrailingPathSeparators(resolved);
+    }
+}
+function stripTrailingPathSeparators(path) {
+    let normalized = path;
+    while (normalized.length > 1 && normalized.endsWith(sep)) {
+        normalized = normalized.slice(0, -1);
+    }
+    return normalized;
+}
 // 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";
 const MIN_VERSION_FLEXIBLE_EDITOR_IDS = "0.1.50";
+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 diffChangeTypeFor(file) {
+    if (file.isNew)
+        return "A";
+    if (file.isDeleted)
+        return "D";
+    return "M";
+}
+function buildWorkspaceCheckout(workspace, project) {
+    if (project.kind !== "git") {
+        return {
+            cwd: workspace.cwd,
+            isGit: false,
+            currentBranch: null,
+            remoteUrl: null,
+            worktreeRoot: null,
+            isPaseoOwnedWorktree: false,
+            mainRepoRoot: null,
+        };
+    }
+    if (workspace.kind === "worktree") {
+        return {
+            cwd: workspace.cwd,
+            isGit: true,
+            currentBranch: workspace.displayName,
+            remoteUrl: null,
+            worktreeRoot: workspace.cwd,
+            isPaseoOwnedWorktree: true,
+            mainRepoRoot: project.rootPath,
+        };
+    }
+    return {
+        cwd: workspace.cwd,
+        isGit: true,
+        currentBranch: workspace.displayName,
+        remoteUrl: null,
+        worktreeRoot: workspace.cwd,
+        isPaseoOwnedWorktree: false,
+        mainRepoRoot: null,
+    };
+}
 function isAppVersionAtLeast(appVersion, minVersion) {
     if (!appVersion)
         return false;
@@ -87,7 +176,6 @@ function clientSupportsAllProviders(appVersion) {
 function clientSupportsFlexibleEditorIds(appVersion) {
     return isAppVersionAtLeast(appVersion, MIN_VERSION_FLEXIBLE_EDITOR_IDS);
 }
-const MAX_TERMINAL_STREAM_SLOTS = 256;
 function beginAgentDeleteIfSupported(agentStorage, agentId) {
     if ("beginDelete" in agentStorage && typeof agentStorage.beginDelete === "function") {
         agentStorage.beginDelete(agentId);
@@ -119,6 +207,19 @@ export function resolveCreateAgentTitles(options) {
         provisionalTitle,
     };
 }
+function getFirstUserMessageText(timeline) {
+    for (const item of timeline) {
+        if (item.type !== "user_message") {
+            continue;
+        }
+        const text = item.text.trim();
+        if (text) {
+            return text;
+        }
+    }
+    return null;
+}
+const FETCH_AGENTS_SORT_KEYS = ["status_priority", "created_at", "updated_at", "title"];
 export function resolveWaitForFinishError(options) {
     if (options.status !== "error") {
         return null;
@@ -126,27 +227,6 @@ export function resolveWaitForFinishError(options) {
     const message = options.final?.lastError;
     return typeof message === "string" && message.trim().length > 0 ? message : "Agent failed";
 }
-function summarizeFetchWorkspacesEntries(entries) {
-    const workspaces = Array.from(entries, (entry) => ({
-        id: entry.id,
-        projectId: entry.projectId,
-        projectDisplayName: entry.projectDisplayName,
-        name: entry.name,
-        status: entry.status,
-        workspaceKind: entry.workspaceKind,
-        activityAt: entry.activityAt,
-    }));
-    const statusCounts = new Map();
-    for (const workspace of workspaces) {
-        statusCounts.set(workspace.status, (statusCounts.get(workspace.status) ?? 0) + 1);
-    }
-    return {
-        count: workspaces.length,
-        projectIds: [...new Set(workspaces.map((workspace) => workspace.projectId))],
-        statusCounts: Object.fromEntries(statusCounts),
-        workspaces,
-    };
-}
 class SessionRequestError extends Error {
     constructor(code, message) {
         super(message);
@@ -173,6 +253,31 @@ class VoiceFeatureUnavailableError extends Error {
         this.missingModelIds = [...context.missingModelIds];
     }
 }
+function buildImportPersistenceHandle(input) {
+    const cwd = input.cwd ?? process.cwd();
+    return {
+        provider: input.provider,
+        sessionId: input.sessionId,
+        nativeHandle: input.sessionId,
+        metadata: {
+            provider: input.provider,
+            cwd,
+        },
+    };
+}
+function applyImportCwdOverride(handle, cwd) {
+    if (!cwd) {
+        return handle;
+    }
+    return {
+        ...handle,
+        metadata: {
+            ...handle.metadata,
+            provider: handle.provider,
+            cwd,
+        },
+    };
+}
 function convertPCMToWavBuffer(pcmBuffer, sampleRate, channels, bitsPerSample) {
     const headerSize = 44;
     const wavBuffer = Buffer.alloc(headerSize + pcmBuffer.length);
@@ -194,6 +299,13 @@ function convertPCMToWavBuffer(pcmBuffer, sampleRate, channels, bitsPerSample) {
     pcmBuffer.copy(wavBuffer, 44);
     return wavBuffer;
 }
+function parseClientCapabilities(capabilities) {
+    if (!capabilities) {
+        return new Set();
+    }
+    const known = new Set(Object.values(CLIENT_CAPS));
+    return new Set(Object.entries(capabilities).flatMap(([key, value]) => value === true && known.has(key) ? [key] : []));
+}
 /**
  * Session represents a single connected client session.
  * It owns all state management, orchestration logic, and message processing.
@@ -226,12 +338,6 @@ export class Session {
         this.clientActivity = null;
         this.MOBILE_BACKGROUND_STREAM_GRACE_MS = 60000;
         this.unsubscribeProviderSnapshotEvents = null;
-        this.subscribedTerminalDirectories = new Set();
-        this.unsubscribeTerminalsChanged = null;
-        this.terminalExitSubscriptions = new Map();
-        this.activeTerminalStreams = new Map();
-        this.terminalIdToSlot = new Map();
-        this.nextTerminalSlot = 0;
         this.inflightRequests = 0;
         this.peakInflightRequests = 0;
         this.availableEditorTargetsCache = new TTLCache({
@@ -249,16 +355,28 @@ export class Session {
         this.workspaceGitSubscriptions = new Map();
         this.voiceModeAgentId = null;
         this.voiceModeBaseConfig = null;
-        this.workspaceStatePriority = {
-            needs_input: 0,
-            failed: 1,
-            running: 2,
-            attention: 3,
-            done: 4,
-        };
-        const { clientId, appVersion, onMessage, onBinaryMessage, onLifecycleIntent, logger, downloadTokenStore, pushTokenStore, paseoHome, agentManager, agentStorage, projectRegistry, workspaceRegistry, chatService, scheduleService, loopService, checkoutDiffManager, github, workspaceGitService, daemonConfigStore, mcpBaseUrl, stt, tts, terminalManager, providerSnapshotManager, scriptRouteStore, scriptRuntimeStore, workspaceSetupSnapshots, onBranchChanged, getDaemonTcpPort, getDaemonTcpHost, resolveScriptHealth, voice, voiceBridge, dictation, agentProviderRuntimeSettings, providerOverrides, isDev, } = options;
+        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 this.getStatusPriority(agent);
+                    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, onLifecycleIntent, logger, downloadTokenStore, pushTokenStore, paseoHome, agentManager, agentStorage, projectRegistry, workspaceRegistry, chatService, scheduleService, loopService, checkoutDiffManager, github, workspaceGitService, daemonConfigStore, mcpBaseUrl, stt, tts, terminalManager, providerSnapshotManager, scriptRouteStore, scriptRuntimeStore, workspaceSetupSnapshots, onBranchChanged, getDaemonTcpPort, getDaemonTcpHost, resolveScriptHealth, voice, voiceBridge, dictation, agentProviderRuntimeSettings, providerOverrides, isDev, } = options;
         this.clientId = clientId;
         this.appVersion = appVersion ?? null;
+        this.clientCapabilities = parseClientCapabilities(clientCapabilities);
         this.sessionId = uuidv4();
         this.onMessage = onMessage;
         this.onBinaryMessage = onBinaryMessage ?? null;
@@ -284,6 +402,14 @@ export class Session {
         this.daemonConfigStore = daemonConfigStore;
         this.mcpBaseUrl = mcpBaseUrl ?? null;
         this.terminalManager = terminalManager;
+        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,
+        });
         this.providerSnapshotManager = providerSnapshotManager ?? null;
         this.scriptRouteStore = scriptRouteStore ?? null;
         this.scriptRuntimeStore = scriptRuntimeStore ?? null;
@@ -292,53 +418,21 @@ export class Session {
         this.getDaemonTcpPort = getDaemonTcpPort ?? null;
         this.getDaemonTcpHost = getDaemonTcpHost ?? null;
         this.resolveScriptHealth = resolveScriptHealth ?? null;
-        if (this.terminalManager) {
-            this.unsubscribeTerminalsChanged = this.terminalManager.subscribeTerminalsChanged((event) => this.handleTerminalsChanged(event));
-        }
-        if (this.providerSnapshotManager) {
-            const handleProviderSnapshotChange = (entries, cwd) => {
-                // COMPAT(providersSnapshot): keep provider visibility gating for older clients.
-                const visibleEntries = entries.filter((entry) => this.isProviderVisibleToClient(entry.provider));
-                this.emit({
-                    type: "providers_snapshot_update",
-                    payload: {
-                        cwd,
-                        entries: visibleEntries,
-                        generatedAt: new Date().toISOString(),
-                    },
-                });
-            };
-            this.providerSnapshotManager.on("change", handleProviderSnapshotChange);
-            this.unsubscribeProviderSnapshotEvents = () => {
-                this.providerSnapshotManager?.off("change", handleProviderSnapshotChange);
-            };
-        }
-        this.resolveVoiceTurnDetection = toResolver(voice?.turnDetection ?? null);
-        this.registerVoiceSpeakHandler = voiceBridge?.registerVoiceSpeakHandler;
-        this.unregisterVoiceSpeakHandler = voiceBridge?.unregisterVoiceSpeakHandler;
-        this.registerVoiceCallerContext = voiceBridge?.registerVoiceCallerContext;
-        this.unregisterVoiceCallerContext = voiceBridge?.unregisterVoiceCallerContext;
-        this.getSpeechReadiness = dictation?.getSpeechReadiness;
+        this.subscribeToOptionalManagers();
+        this.bindVoiceBridges({ voice, voiceBridge, dictation });
         this.agentProviderRuntimeSettings = agentProviderRuntimeSettings;
         this.providerOverrides = providerOverrides;
         this.isDev = isDev === true;
         this.abortController = new AbortController();
-        this.providerRegistry = buildProviderRegistry(this.sessionLogger, {
-            runtimeSettings: this.agentProviderRuntimeSettings,
-            providerOverrides: this.providerOverrides,
-            workspaceGitService: this.workspaceGitService,
-            isDev: this.isDev,
-        });
-        // Initialize per-session managers
-        this.ttsManager = new TTSManager(this.sessionId, this.sessionLogger, tts);
-        this.sttManager = new STTManager(this.sessionId, this.sessionLogger, stt);
-        this.dictationStreamManager = new DictationStreamManager({
+        this.workspaceDirectory = new WorkspaceDirectory({
             logger: this.sessionLogger,
-            sessionId: this.sessionId,
-            emit: (msg) => this.handleDictationManagerMessage(msg),
-            stt: dictation?.stt ?? null,
-            finalTimeoutMs: dictation?.finalTimeoutMs,
+            projectRegistry: this.projectRegistry,
+            workspaceRegistry: this.workspaceRegistry,
+            listAgentPayloads: () => this.listAgentPayloads(),
+            isProviderVisibleToClient: (provider) => this.isProviderVisibleToClient(provider),
+            buildWorkspaceDescriptor: (input) => this.buildWorkspaceDescriptor(input),
         });
+        this.initializePerSessionManagers({ tts, stt, dictation });
         // Initialize agent MCP client asynchronously
         void this.initializeAgentMcp();
         this.subscribeToAgentEvents();
@@ -349,6 +443,12 @@ export class Session {
             this.appVersion = appVersion;
         }
     }
+    updateClientCapabilities(capabilities) {
+        this.clientCapabilities = parseClientCapabilities(capabilities);
+    }
+    supports(capability) {
+        return this.clientCapabilities.has(capability);
+    }
     async syncWorkspaceGitObserverForWorkspace(workspace) {
         const descriptor = await this.describeWorkspaceRecordWithGitData(workspace);
         this.syncWorkspaceGitObservers([descriptor]);
@@ -359,8 +459,17 @@ export class Session {
     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 emitWorkspaceUpdatesForExternalCwds(cwds) {
-        await this.emitWorkspaceUpdatesForCwds(cwds);
+        await Promise.all(Array.from(cwds, (cwd) => this.emitWorkspaceUpdateForCwd(cwd)));
     }
     async warmWorkspaceGitDataForWorkspace(workspace) {
         await this.syncWorkspaceGitObserverForWorkspace(workspace);
@@ -373,9 +482,10 @@ export class Session {
         return this.clientActivity;
     }
     getRuntimeMetrics() {
+        const terminalMetrics = this.terminalController.getMetrics();
         return {
-            terminalDirectorySubscriptionCount: this.subscribedTerminalDirectories.size,
-            terminalSubscriptionCount: this.activeTerminalStreams.size,
+            terminalDirectorySubscriptionCount: terminalMetrics.directorySubscriptionCount,
+            terminalSubscriptionCount: terminalMetrics.streamSubscriptionCount,
             inflightRequests: this.inflightRequests,
             peakInflightRequests: this.peakInflightRequests,
         };
@@ -427,16 +537,11 @@ export class Session {
             return;
         }
         this.sessionLogger.debug({ agentId, lifecycle: snapshot.lifecycle, hasInFlightRun }, "interruptAgentIfRunning: interrupting");
-        try {
-            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");
-            }
-        }
-        catch (error) {
-            throw error;
+        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) {
@@ -464,12 +569,7 @@ export class Session {
         }
         catch (error) {
             this.handleAgentRunError(agentId, error, "Failed to start agent run");
-            const message = error instanceof Error
-                ? error.message
-                : typeof error === "string"
-                    ? error
-                    : "Unknown error";
-            return { ok: false, error: message };
+            return { ok: false, error: errorToFriendlyMessage(error) };
         }
         void (async () => {
             try {
@@ -486,7 +586,7 @@ export class Session {
         return { ok: true };
     }
     handleAgentRunError(agentId, error, context) {
-        const message = error instanceof Error ? error.message : typeof error === "string" ? error : "Unknown error";
+        const message = errorToFriendlyMessage(error);
         this.sessionLogger.error({ err: error, agentId, context }, `${context} for agent ${agentId}`);
         this.emit({
             type: "activity_log",
@@ -522,6 +622,48 @@ export class Session {
     /**
      * Subscribe to AgentManager events and forward them to the client
      */
+    subscribeToOptionalManagers() {
+        this.terminalController.start();
+        if (this.providerSnapshotManager) {
+            const handleProviderSnapshotChange = (entries, cwd) => {
+                // COMPAT(providersSnapshot): keep provider visibility gating for older clients.
+                const visibleEntries = entries.filter((entry) => this.isProviderVisibleToClient(entry.provider));
+                this.emit({
+                    type: "providers_snapshot_update",
+                    payload: {
+                        cwd,
+                        entries: visibleEntries,
+                        generatedAt: new Date().toISOString(),
+                    },
+                });
+            };
+            this.providerSnapshotManager.on("change", handleProviderSnapshotChange);
+            this.unsubscribeProviderSnapshotEvents = () => {
+                this.providerSnapshotManager?.off("change", handleProviderSnapshotChange);
+            };
+        }
+    }
+    bindVoiceBridges(params) {
+        const { voice, voiceBridge, dictation } = params;
+        this.resolveVoiceTurnDetection = toResolver(voice?.turnDetection ?? null);
+        this.registerVoiceSpeakHandler = voiceBridge?.registerVoiceSpeakHandler;
+        this.unregisterVoiceSpeakHandler = voiceBridge?.unregisterVoiceSpeakHandler;
+        this.registerVoiceCallerContext = voiceBridge?.registerVoiceCallerContext;
+        this.unregisterVoiceCallerContext = voiceBridge?.unregisterVoiceCallerContext;
+        this.getSpeechReadiness = dictation?.getSpeechReadiness;
+    }
+    initializePerSessionManagers(params) {
+        const { tts, stt, dictation } = params;
+        this.ttsManager = new TTSManager(this.sessionId, this.sessionLogger, tts);
+        this.sttManager = new STTManager(this.sessionId, this.sessionLogger, stt);
+        this.dictationStreamManager = new DictationStreamManager({
+            logger: this.sessionLogger,
+            sessionId: this.sessionId,
+            emit: (msg) => this.handleDictationManagerMessage(msg),
+            stt: dictation?.stt ?? null,
+            finalTimeoutMs: dictation?.finalTimeoutMs,
+        });
+    }
     subscribeToAgentEvents() {
         if (this.unsubscribeAgentEvents) {
             this.unsubscribeAgentEvents();
@@ -618,8 +760,19 @@ export class Session {
         payload.archivedAt = storedRecord?.archivedAt ?? null;
         return payload;
     }
-    buildStoredAgentPayload(record) {
-        return buildStoredAgentPayload(record, this.providerRegistry, this.sessionLogger);
+    getProviderRegistry() {
+        return buildProviderRegistry(this.sessionLogger, {
+            runtimeSettings: this.agentProviderRuntimeSettings,
+            providerOverrides: applyMutableProviderConfigToOverrides(this.providerOverrides, this.daemonConfigStore.get().providers),
+            workspaceGitService: this.workspaceGitService,
+            isDev: this.isDev,
+        });
+    }
+    getRegisteredProviderIds() {
+        return Object.keys(this.getProviderRegistry());
+    }
+    buildStoredAgentPayload(record, registeredProviderIds = this.getRegisteredProviderIds()) {
+        return buildStoredAgentPayload(record, registeredProviderIds);
     }
     isProviderVisibleToClient(provider) {
         if (clientSupportsAllProviders(this.appVersion)) {
@@ -633,44 +786,34 @@ export class Session {
         }
         return editors.filter((editor) => isLegacyEditorTargetId(editor.id));
     }
-    matchesAgentFilter(options) {
-        const { agent, project, filter } = options;
-        if (filter?.labels) {
-            const matchesLabels = Object.entries(filter.labels).every(([key, value]) => agent.labels[key] === value);
-            if (!matchesLabels) {
-                return false;
-            }
-        }
-        const includeArchived = filter?.includeArchived ?? false;
-        if (!includeArchived && agent.archivedAt) {
-            return false;
+    agentThinkingOptionMatchesFilter(agent, filter) {
+        if (filter.thinkingOptionId === undefined) {
+            return true;
         }
-        if (filter?.thinkingOptionId !== undefined) {
-            const expectedThinkingOptionId = resolveEffectiveThinkingOptionId({
-                configuredThinkingOptionId: filter.thinkingOptionId ?? null,
+        const expectedThinkingOptionId = resolveEffectiveThinkingOptionId({
+            configuredThinkingOptionId: filter.thinkingOptionId ?? null,
+        });
+        const resolvedThinkingOptionId = agent.effectiveThinkingOptionId ??
+            resolveEffectiveThinkingOptionId({
+                runtimeInfo: agent.runtimeInfo,
+                configuredThinkingOptionId: agent.thinkingOptionId ?? null,
             });
-            const resolvedThinkingOptionId = agent.effectiveThinkingOptionId ??
-                resolveEffectiveThinkingOptionId({
-                    runtimeInfo: agent.runtimeInfo,
-                    configuredThinkingOptionId: agent.thinkingOptionId ?? null,
-                });
-            if (resolvedThinkingOptionId !== expectedThinkingOptionId) {
-                return false;
-            }
-        }
-        if (filter?.statuses && filter.statuses.length > 0) {
+        return resolvedThinkingOptionId === expectedThinkingOptionId;
+    }
+    matchesAgentStructuralFilter(agent, project, filter) {
+        if (filter.statuses && filter.statuses.length > 0) {
             const statuses = new Set(filter.statuses);
             if (!statuses.has(agent.status)) {
                 return false;
             }
         }
-        if (typeof filter?.requiresAttention === "boolean") {
+        if (typeof filter.requiresAttention === "boolean") {
             const requiresAttention = agent.requiresAttention ?? false;
             if (requiresAttention !== filter.requiresAttention) {
                 return false;
             }
         }
-        if (filter?.projectKeys && filter.projectKeys.length > 0) {
+        if (filter.projectKeys && filter.projectKeys.length > 0) {
             const projectKeys = new Set(filter.projectKeys.filter((item) => item.trim().length > 0));
             if (projectKeys.size > 0 && !projectKeys.has(project.projectKey)) {
                 return false;
@@ -678,6 +821,26 @@ export class Session {
         }
         return true;
     }
+    matchesAgentFilter(options) {
+        const { agent, project, filter } = options;
+        if (filter?.labels) {
+            const matchesLabels = Object.entries(filter.labels).every(([key, value]) => agent.labels[key] === value);
+            if (!matchesLabels) {
+                return false;
+            }
+        }
+        const includeArchived = filter?.includeArchived ?? false;
+        if (!includeArchived && agent.archivedAt) {
+            return false;
+        }
+        if (filter && !this.agentThinkingOptionMatchesFilter(agent, filter)) {
+            return false;
+        }
+        if (filter && !this.matchesAgentStructuralFilter(agent, project, filter)) {
+            return false;
+        }
+        return true;
+    }
     getAgentUpdateTargetId(update) {
         return update.kind === "remove" ? update.agentId : update.agent.id;
     }
@@ -724,54 +887,26 @@ export class Session {
         const workspaceId = this.resolveRegisteredWorkspaceIdForCwd(normalizedCwd, workspaces);
         return workspaces.find((workspace) => workspace.workspaceId === workspaceId) ?? null;
     }
+    async findExactWorkspaceByDirectory(cwd, options) {
+        const normalizedCwd = await this.resolveWorkspaceDirectory(cwd, options);
+        const workspaces = await this.workspaceRegistry.list();
+        return workspaces.find((workspace) => workspace.cwd === normalizedCwd) ?? null;
+    }
     async resolveWorkspaceDirectory(cwd, options) {
         const normalizedCwd = normalizePersistedWorkspaceId(cwd);
         if (options?.refreshGit === false) {
             const snapshot = this.workspaceGitService.peekSnapshot(normalizedCwd);
             return normalizePersistedWorkspaceId(snapshot?.git.repoRoot ?? normalizedCwd);
         }
-        try {
-            const snapshot = await this.workspaceGitService.getSnapshot(normalizedCwd);
-            return normalizePersistedWorkspaceId(snapshot.git.repoRoot ?? normalizedCwd);
-        }
-        catch {
-            return normalizedCwd;
-        }
+        const checkout = await this.workspaceGitService.getCheckout(normalizedCwd);
+        return normalizePersistedWorkspaceId(checkout.worktreeRoot ?? normalizedCwd);
     }
     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 checkout = project.kind !== "git"
-            ? {
-                cwd: workspace.cwd,
-                isGit: false,
-                currentBranch: null,
-                remoteUrl: null,
-                worktreeRoot: null,
-                isPaseoOwnedWorktree: false,
-                mainRepoRoot: null,
-            }
-            : workspace.kind === "worktree"
-                ? {
-                    cwd: workspace.cwd,
-                    isGit: true,
-                    currentBranch: workspace.displayName,
-                    remoteUrl: null,
-                    worktreeRoot: workspace.cwd,
-                    isPaseoOwnedWorktree: true,
-                    mainRepoRoot: project.rootPath,
-                }
-                : {
-                    cwd: workspace.cwd,
-                    isGit: true,
-                    currentBranch: workspace.displayName,
-                    remoteUrl: null,
-                    worktreeRoot: workspace.cwd,
-                    isPaseoOwnedWorktree: false,
-                    mainRepoRoot: null,
-                };
+        const checkout = buildWorkspaceCheckout(workspace, project);
         return {
             projectKey: project.projectId,
             projectName: project.displayName,
@@ -851,360 +986,7 @@ export class Session {
         try {
             this.sessionLogger.trace({ messageType: msg.type, payloadBytes: JSON.stringify(msg).length }, "inbound message");
             try {
-                switch (msg.type) {
-                    case "voice_audio_chunk":
-                        await this.handleAudioChunk(msg);
-                        break;
-                    case "abort_request":
-                        await this.handleAbort();
-                        break;
-                    case "audio_played":
-                        this.handleAudioPlayed(msg.id);
-                        break;
-                    case "fetch_agents_request":
-                        await this.handleFetchAgents(msg);
-                        break;
-                    case "fetch_agent_history_request":
-                        await this.handleFetchAgentHistory(msg);
-                        break;
-                    case "fetch_workspaces_request":
-                        await this.handleFetchWorkspacesRequest(msg);
-                        break;
-                    case "fetch_agent_request":
-                        await this.handleFetchAgent(msg.agentId, msg.requestId);
-                        break;
-                    case "delete_agent_request":
-                        await this.handleDeleteAgentRequest(msg.agentId, msg.requestId);
-                        break;
-                    case "archive_agent_request":
-                        await this.handleArchiveAgentRequest(msg.agentId, msg.requestId);
-                        break;
-                    case "close_items_request":
-                        await this.handleCloseItemsRequest(msg);
-                        break;
-                    case "update_agent_request":
-                        await this.handleUpdateAgentRequest(msg.agentId, msg.name, msg.labels, msg.requestId);
-                        break;
-                    case "set_voice_mode":
-                        await this.handleSetVoiceMode(msg.enabled, msg.agentId, msg.requestId);
-                        break;
-                    case "send_agent_message_request":
-                        await this.handleSendAgentMessageRequest(msg);
-                        break;
-                    case "wait_for_finish_request":
-                        await this.handleWaitForFinish(msg.agentId, msg.requestId, msg.timeoutMs);
-                        break;
-                    case "get_daemon_config_request":
-                        this.emit({
-                            type: "get_daemon_config_response",
-                            payload: {
-                                requestId: msg.requestId,
-                                config: this.daemonConfigStore.get(),
-                            },
-                        });
-                        break;
-                    case "set_daemon_config_request":
-                        this.emit({
-                            type: "set_daemon_config_response",
-                            payload: {
-                                requestId: msg.requestId,
-                                config: this.daemonConfigStore.patch(msg.config),
-                            },
-                        });
-                        break;
-                    case "dictation_stream_start":
-                        {
-                            const unavailable = this.resolveVoiceFeatureUnavailableContext("dictation");
-                            if (unavailable) {
-                                this.emit({
-                                    type: "dictation_stream_error",
-                                    payload: {
-                                        dictationId: msg.dictationId,
-                                        error: unavailable.message,
-                                        retryable: unavailable.retryable,
-                                        reasonCode: unavailable.reasonCode,
-                                        missingModelIds: unavailable.missingModelIds,
-                                    },
-                                });
-                                break;
-                            }
-                        }
-                        await this.dictationStreamManager.handleStart(msg.dictationId, msg.format);
-                        break;
-                    case "dictation_stream_chunk":
-                        await this.dictationStreamManager.handleChunk({
-                            dictationId: msg.dictationId,
-                            seq: msg.seq,
-                            audioBase64: msg.audio,
-                            format: msg.format,
-                        });
-                        break;
-                    case "dictation_stream_finish":
-                        await this.dictationStreamManager.handleFinish(msg.dictationId, msg.finalSeq);
-                        break;
-                    case "dictation_stream_cancel":
-                        this.dictationStreamManager.handleCancel(msg.dictationId);
-                        break;
-                    case "create_agent_request":
-                        await this.handleCreateAgentRequest(msg);
-                        break;
-                    case "resume_agent_request":
-                        await this.handleResumeAgentRequest(msg);
-                        break;
-                    case "refresh_agent_request":
-                        await this.handleRefreshAgentRequest(msg);
-                        break;
-                    case "cancel_agent_request":
-                        await this.handleCancelAgentRequest(msg.agentId, msg.requestId);
-                        break;
-                    case "restart_server_request":
-                        await this.handleRestartServerRequest(msg.requestId, msg.reason);
-                        break;
-                    case "shutdown_server_request":
-                        await this.handleShutdownServerRequest(msg.requestId);
-                        break;
-                    case "fetch_agent_timeline_request":
-                        await this.handleFetchAgentTimelineRequest(msg);
-                        break;
-                    case "set_agent_mode_request":
-                        await this.handleSetAgentModeRequest(msg.agentId, msg.modeId, msg.requestId);
-                        break;
-                    case "set_agent_model_request":
-                        await this.handleSetAgentModelRequest(msg.agentId, msg.modelId, msg.requestId);
-                        break;
-                    case "set_agent_feature_request":
-                        await this.handleSetAgentFeatureRequest(msg.agentId, msg.featureId, msg.value, msg.requestId);
-                        break;
-                    case "set_agent_thinking_request":
-                        await this.handleSetAgentThinkingRequest(msg.agentId, msg.thinkingOptionId, msg.requestId);
-                        break;
-                    case "agent_permission_response":
-                        await this.handleAgentPermissionResponse(msg.agentId, msg.requestId, msg.response);
-                        break;
-                    case "checkout_status_request":
-                        await this.handleCheckoutStatusRequest(msg);
-                        break;
-                    case "validate_branch_request":
-                        await this.handleValidateBranchRequest(msg);
-                        break;
-                    case "branch_suggestions_request":
-                        await this.handleBranchSuggestionsRequest(msg);
-                        break;
-                    case "directory_suggestions_request":
-                        await this.handleDirectorySuggestionsRequest(msg);
-                        break;
-                    case "subscribe_checkout_diff_request":
-                        await this.handleSubscribeCheckoutDiffRequest(msg);
-                        break;
-                    case "unsubscribe_checkout_diff_request":
-                        this.handleUnsubscribeCheckoutDiffRequest(msg);
-                        break;
-                    case "checkout_switch_branch_request":
-                        await this.handleCheckoutSwitchBranchRequest(msg);
-                        break;
-                    case "stash_save_request":
-                        await this.handleStashSaveRequest(msg);
-                        break;
-                    case "stash_pop_request":
-                        await this.handleStashPopRequest(msg);
-                        break;
-                    case "stash_list_request":
-                        await this.handleStashListRequest(msg);
-                        break;
-                    case "checkout_commit_request":
-                        await this.handleCheckoutCommitRequest(msg);
-                        break;
-                    case "checkout_merge_request":
-                        await this.handleCheckoutMergeRequest(msg);
-                        break;
-                    case "checkout_merge_from_base_request":
-                        await this.handleCheckoutMergeFromBaseRequest(msg);
-                        break;
-                    case "checkout_pull_request":
-                        await this.handleCheckoutPullRequest(msg);
-                        break;
-                    case "checkout_push_request":
-                        await this.handleCheckoutPushRequest(msg);
-                        break;
-                    case "checkout_pr_create_request":
-                        await this.handleCheckoutPrCreateRequest(msg);
-                        break;
-                    case "checkout_pr_status_request":
-                        await this.handleCheckoutPrStatusRequest(msg);
-                        break;
-                    case "pull_request_timeline_request":
-                        await this.handlePullRequestTimelineRequest(msg);
-                        break;
-                    case "github_search_request":
-                        await this.handleGitHubSearchRequest(msg);
-                        break;
-                    case "paseo_worktree_list_request":
-                        await this.handlePaseoWorktreeListRequest(msg);
-                        break;
-                    case "paseo_worktree_archive_request":
-                        await this.handlePaseoWorktreeArchiveRequest(msg);
-                        break;
-                    case "create_paseo_worktree_request":
-                        await this.handleCreatePaseoWorktreeRequest(msg);
-                        break;
-                    case "workspace_setup_status_request":
-                        await this.handleWorkspaceSetupStatusRequest(msg);
-                        break;
-                    case "list_available_editors_request":
-                        await this.handleListAvailableEditorsRequest(msg);
-                        break;
-                    case "open_in_editor_request":
-                        await this.handleOpenInEditorRequest(msg);
-                        break;
-                    case "open_project_request":
-                        await this.handleOpenProjectRequest(msg);
-                        break;
-                    case "archive_workspace_request":
-                        await this.handleArchiveWorkspaceRequest(msg);
-                        break;
-                    case "file_explorer_request":
-                        await this.handleFileExplorerRequest(msg);
-                        break;
-                    case "project_icon_request":
-                        await this.handleProjectIconRequest(msg);
-                        break;
-                    case "file_download_token_request":
-                        await this.handleFileDownloadTokenRequest(msg);
-                        break;
-                    case "list_provider_models_request":
-                        await this.handleListProviderModelsRequest(msg);
-                        break;
-                    case "list_provider_modes_request":
-                        await this.handleListProviderModesRequest(msg);
-                        break;
-                    case "list_provider_features_request":
-                        await this.handleListProviderFeaturesRequest(msg);
-                        break;
-                    case "list_available_providers_request":
-                        await this.handleListAvailableProvidersRequest(msg);
-                        break;
-                    case "get_providers_snapshot_request":
-                        await this.handleGetProvidersSnapshotRequest(msg);
-                        break;
-                    case "refresh_providers_snapshot_request":
-                        await this.handleRefreshProvidersSnapshotRequest(msg);
-                        break;
-                    case "provider_diagnostic_request":
-                        await this.handleProviderDiagnosticRequest(msg);
-                        break;
-                    case "clear_agent_attention":
-                        await this.handleClearAgentAttention(msg.agentId, msg.requestId);
-                        break;
-                    case "client_heartbeat":
-                        this.handleClientHeartbeat(msg);
-                        break;
-                    case "ping": {
-                        const now = Date.now();
-                        this.emit({
-                            type: "pong",
-                            payload: {
-                                requestId: msg.requestId,
-                                clientSentAt: msg.clientSentAt,
-                                serverReceivedAt: now,
-                                serverSentAt: now,
-                            },
-                        });
-                        break;
-                    }
-                    case "list_commands_request":
-                        await this.handleListCommandsRequest(msg);
-                        break;
-                    case "register_push_token":
-                        this.handleRegisterPushToken(msg.token);
-                        break;
-                    case "subscribe_terminals_request":
-                        this.handleSubscribeTerminalsRequest(msg);
-                        break;
-                    case "unsubscribe_terminals_request":
-                        this.handleUnsubscribeTerminalsRequest(msg);
-                        break;
-                    case "list_terminals_request":
-                        await this.handleListTerminalsRequest(msg);
-                        break;
-                    case "create_terminal_request":
-                        await this.handleCreateTerminalRequest(msg);
-                        break;
-                    case "start_workspace_script_request":
-                        await this.handleStartWorkspaceScriptRequest(msg);
-                        break;
-                    case "subscribe_terminal_request":
-                        await this.handleSubscribeTerminalRequest(msg);
-                        break;
-                    case "unsubscribe_terminal_request":
-                        this.handleUnsubscribeTerminalRequest(msg);
-                        break;
-                    case "terminal_input":
-                        this.handleTerminalInput(msg);
-                        break;
-                    case "kill_terminal_request":
-                        await this.handleKillTerminalRequest(msg);
-                        break;
-                    case "capture_terminal_request":
-                        await this.handleCaptureTerminalRequest(msg);
-                        break;
-                    case "chat/create":
-                        await this.handleChatCreateRequest(msg);
-                        break;
-                    case "chat/list":
-                        await this.handleChatListRequest(msg);
-                        break;
-                    case "chat/inspect":
-                        await this.handleChatInspectRequest(msg);
-                        break;
-                    case "chat/delete":
-                        await this.handleChatDeleteRequest(msg);
-                        break;
-                    case "chat/post":
-                        await this.handleChatPostRequest(msg);
-                        break;
-                    case "chat/read":
-                        await this.handleChatReadRequest(msg);
-                        break;
-                    case "chat/wait":
-                        await this.handleChatWaitRequest(msg);
-                        break;
-                    case "schedule/create":
-                        await this.handleScheduleCreateRequest(msg);
-                        break;
-                    case "schedule/list":
-                        await this.handleScheduleListRequest(msg);
-                        break;
-                    case "schedule/inspect":
-                        await this.handleScheduleInspectRequest(msg);
-                        break;
-                    case "schedule/logs":
-                        await this.handleScheduleLogsRequest(msg);
-                        break;
-                    case "schedule/pause":
-                        await this.handleSchedulePauseRequest(msg);
-                        break;
-                    case "schedule/resume":
-                        await this.handleScheduleResumeRequest(msg);
-                        break;
-                    case "schedule/delete":
-                        await this.handleScheduleDeleteRequest(msg);
-                        break;
-                    case "loop/run":
-                        await this.handleLoopRunRequest(msg);
-                        break;
-                    case "loop/list":
-                        await this.handleLoopListRequest(msg);
-                        break;
-                    case "loop/inspect":
-                        await this.handleLoopInspectRequest(msg);
-                        break;
-                    case "loop/logs":
-                        await this.handleLoopLogsRequest(msg);
-                        break;
-                    case "loop/stop":
-                        await this.handleLoopStopRequest(msg);
-                        break;
-                }
+                await this.dispatchInboundMessage(msg);
             }
             catch (error) {
                 const err = error instanceof Error ? error : new Error(String(error));
@@ -1241,43 +1023,402 @@ export class Session {
             this.inflightRequests--;
         }
     }
-    resetPeakInflight() {
-        this.peakInflightRequests = this.inflightRequests;
+    async dispatchInboundMessage(msg) {
+        const promise = this.dispatchVoiceAndControlMessage(msg) ??
+            this.dispatchAgentLifecycleMessage(msg) ??
+            this.dispatchAgentConfigMessage(msg) ??
+            this.dispatchCheckoutMessage(msg) ??
+            this.dispatchWorkspaceAndProjectMessage(msg) ??
+            this.dispatchProviderMessage(msg) ??
+            this.dispatchTerminalMessage(msg) ??
+            this.dispatchChatScheduleLoopMessage(msg) ??
+            this.dispatchMiscMessage(msg);
+        if (promise)
+            await promise;
+    }
+    dispatchVoiceAndControlMessage(msg) {
+        switch (msg.type) {
+            case "voice_audio_chunk":
+                return this.handleAudioChunk(msg);
+            case "abort_request":
+                return this.handleAbort();
+            case "audio_played":
+                this.handleAudioPlayed(msg.id);
+                return undefined;
+            case "set_voice_mode":
+                return this.handleSetVoiceMode(msg.enabled, msg.agentId, msg.requestId);
+            case "dictation_stream_start":
+                return this.handleDictationStreamStart(msg);
+            case "dictation_stream_chunk":
+                return this.dictationStreamManager.handleChunk({
+                    dictationId: msg.dictationId,
+                    seq: msg.seq,
+                    audioBase64: msg.audio,
+                    format: msg.format,
+                });
+            case "dictation_stream_finish":
+                return this.dictationStreamManager.handleFinish(msg.dictationId, msg.finalSeq);
+            case "dictation_stream_cancel":
+                this.dictationStreamManager.handleCancel(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;
+        }
     }
-    handleBinaryFrame(frame) {
-        const activeStream = this.activeTerminalStreams.get(frame.slot);
-        if (!activeStream || !this.terminalManager) {
+    async handleDictationStreamStart(msg) {
+        const unavailable = this.resolveVoiceFeatureUnavailableContext("dictation");
+        if (unavailable) {
+            this.emit({
+                type: "dictation_stream_error",
+                payload: {
+                    dictationId: msg.dictationId,
+                    error: unavailable.message,
+                    retryable: unavailable.retryable,
+                    reasonCode: unavailable.reasonCode,
+                    missingModelIds: unavailable.missingModelIds,
+                },
+            });
             return;
         }
-        const terminal = this.terminalManager.getTerminal(activeStream.terminalId);
-        if (!terminal) {
-            this.detachTerminalStream(activeStream.terminalId, { emitExit: true });
+        await this.dictationStreamManager.handleStart(msg.dictationId, msg.format);
+    }
+    dispatchAgentLifecycleMessage(msg) {
+        switch (msg.type) {
+            case "fetch_agents_request":
+                return this.handleFetchAgents(msg);
+            case "fetch_agent_history_request":
+                return this.handleFetchAgentHistory(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 "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 "fetch_agent_timeline_request":
+                return this.handleFetchAgentTimelineRequest(msg);
+            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.handleSetAgentModeRequest(msg.agentId, msg.modeId, msg.requestId);
+            case "set_agent_model_request":
+                return this.handleSetAgentModelRequest(msg.agentId, msg.modelId, msg.requestId);
+            case "set_agent_feature_request":
+                return this.handleSetAgentFeatureRequest(msg.agentId, msg.featureId, msg.value, msg.requestId);
+            case "set_agent_thinking_request":
+                return this.handleSetAgentThinkingRequest(msg.agentId, msg.thinkingOptionId, msg.requestId);
+            case "get_daemon_config_request":
+                this.emit({
+                    type: "get_daemon_config_response",
+                    payload: { requestId: msg.requestId, config: this.daemonConfigStore.get() },
+                });
+                return undefined;
+            case "set_daemon_config_request":
+                this.emit({
+                    type: "set_daemon_config_response",
+                    payload: {
+                        requestId: msg.requestId,
+                        config: this.daemonConfigStore.patch(msg.config),
+                    },
+                });
+                return undefined;
+            case "read_project_config_request":
+                return this.handleReadProjectConfigRequest(msg);
+            case "write_project_config_request":
+                return this.handleWriteProjectConfigRequest(msg);
+            default:
+                return undefined;
+        }
+    }
+    async handleReadProjectConfigRequest(msg) {
+        const repoRoot = await resolveKnownProjectRootForConfig({
+            repoRoot: msg.repoRoot,
+            projectRegistry: this.projectRegistry,
+        });
+        if (!repoRoot) {
+            this.emitProjectConfigReadFailure(msg, { code: "project_not_found" });
             return;
         }
-        switch (frame.opcode) {
-            case TerminalStreamOpcode.Input: {
-                if (frame.payload.byteLength === 0) {
-                    return;
-                }
-                const text = Buffer.from(frame.payload).toString("utf8");
-                if (!text) {
-                    return;
-                }
-                terminal.send({ type: "input", data: text });
-                return;
-            }
-            case TerminalStreamOpcode.Resize: {
-                const resize = decodeTerminalResizePayload(frame.payload);
-                if (!resize) {
-                    return;
-                }
-                terminal.send({ type: "resize", rows: resize.rows, cols: resize.cols });
-                return;
-            }
+        const result = readPaseoConfigForEdit(repoRoot);
+        if (!result.ok) {
+            this.sessionLogger.warn({ repoRoot, requestId: msg.requestId, outcome: result.error.code }, "Failed to read project config");
+            this.emitProjectConfigReadFailure(msg, result.error, repoRoot);
+            return;
+        }
+        if (result.config === null) {
+            this.sessionLogger.debug({ repoRoot, requestId: msg.requestId, outcome: "missing_project_config" }, "Project config missing");
+        }
+        this.emit({
+            type: "read_project_config_response",
+            payload: {
+                requestId: msg.requestId,
+                repoRoot,
+                ok: true,
+                config: result.config,
+                revision: result.revision,
+            },
+        });
+    }
+    async handleWriteProjectConfigRequest(msg) {
+        const repoRoot = await resolveKnownProjectRootForConfig({
+            repoRoot: msg.repoRoot,
+            projectRegistry: this.projectRegistry,
+        });
+        if (!repoRoot) {
+            this.emitProjectConfigWriteFailure(msg, { code: "project_not_found" });
+            return;
+        }
+        this.sessionLogger.debug({ repoRoot, requestId: msg.requestId, outcome: "write_attempt" }, "Writing project config");
+        const result = writePaseoConfigForEdit({
+            repoRoot,
+            config: msg.config,
+            expectedRevision: msg.expectedRevision,
+        });
+        if (!result.ok) {
+            this.sessionLogger.debug({ repoRoot, requestId: msg.requestId, outcome: result.error.code }, "Project config write did not complete");
+            this.emitProjectConfigWriteFailure(msg, result.error, repoRoot);
+            return;
+        }
+        this.sessionLogger.debug({ repoRoot, requestId: msg.requestId, outcome: "written" }, "Project config written");
+        this.emit({
+            type: "write_project_config_response",
+            payload: {
+                requestId: msg.requestId,
+                repoRoot,
+                ok: true,
+                config: result.config,
+                revision: result.revision,
+            },
+        });
+    }
+    emitProjectConfigReadFailure(msg, error, repoRoot = msg.repoRoot) {
+        this.emit({
+            type: "read_project_config_response",
+            payload: {
+                requestId: msg.requestId,
+                repoRoot,
+                ok: false,
+                error,
+            },
+        });
+    }
+    emitProjectConfigWriteFailure(msg, error, repoRoot = msg.repoRoot) {
+        this.emit({
+            type: "write_project_config_response",
+            payload: {
+                requestId: msg.requestId,
+                repoRoot,
+                ok: false,
+                error,
+            },
+        });
+    }
+    dispatchCheckoutMessage(msg) {
+        switch (msg.type) {
+            case "checkout_status_request":
+                return this.handleCheckoutStatusRequest(msg);
+            case "validate_branch_request":
+                return this.handleValidateBranchRequest(msg);
+            case "branch_suggestions_request":
+                return this.handleBranchSuggestionsRequest(msg);
+            case "directory_suggestions_request":
+                return this.handleDirectorySuggestionsRequest(msg);
+            case "subscribe_checkout_diff_request":
+                return this.handleSubscribeCheckoutDiffRequest(msg);
+            case "unsubscribe_checkout_diff_request":
+                this.handleUnsubscribeCheckoutDiffRequest(msg);
+                return undefined;
+            case "checkout_switch_branch_request":
+                return this.handleCheckoutSwitchBranchRequest(msg);
+            case "stash_save_request":
+                return this.handleStashSaveRequest(msg);
+            case "stash_pop_request":
+                return this.handleStashPopRequest(msg);
+            case "stash_list_request":
+                return this.handleStashListRequest(msg);
+            case "checkout_commit_request":
+                return this.handleCheckoutCommitRequest(msg);
+            case "checkout_merge_request":
+                return this.handleCheckoutMergeRequest(msg);
+            case "checkout_merge_from_base_request":
+                return this.handleCheckoutMergeFromBaseRequest(msg);
+            case "checkout_pull_request":
+                return this.handleCheckoutPullRequest(msg);
+            case "checkout_push_request":
+                return this.handleCheckoutPushRequest(msg);
+            case "checkout_pr_create_request":
+                return this.handleCheckoutPrCreateRequest(msg);
+            case "checkout_pr_status_request":
+                return this.handleCheckoutPrStatusRequest(msg);
+            case "pull_request_timeline_request":
+                return this.handlePullRequestTimelineRequest(msg);
+            case "github_search_request":
+                return this.handleGitHubSearchRequest(msg);
+            default:
+                return undefined;
+        }
+    }
+    dispatchWorkspaceAndProjectMessage(msg) {
+        switch (msg.type) {
+            case "fetch_workspaces_request":
+                return this.handleFetchWorkspacesRequest(msg);
+            case "paseo_worktree_list_request":
+                return this.handlePaseoWorktreeListRequest(msg);
+            case "paseo_worktree_archive_request":
+                return this.handlePaseoWorktreeArchiveRequest(msg);
+            case "create_paseo_worktree_request":
+                return this.handleCreatePaseoWorktreeRequest(msg);
+            case "workspace_setup_status_request":
+                return this.handleWorkspaceSetupStatusRequest(msg);
+            case "list_available_editors_request":
+                return this.handleListAvailableEditorsRequest(msg);
+            case "open_in_editor_request":
+                return this.handleOpenInEditorRequest(msg);
+            case "open_project_request":
+                return this.handleOpenProjectRequest(msg);
+            case "archive_workspace_request":
+                return this.handleArchiveWorkspaceRequest(msg);
+            case "file_explorer_request":
+                return this.handleFileExplorerRequest(msg);
+            case "project_icon_request":
+                return this.handleProjectIconRequest(msg);
+            case "file_download_token_request":
+                return this.handleFileDownloadTokenRequest(msg);
             default:
+                return undefined;
+        }
+    }
+    dispatchProviderMessage(msg) {
+        switch (msg.type) {
+            case "list_provider_models_request":
+                return this.handleListProviderModelsRequest(msg);
+            case "list_provider_modes_request":
+                return this.handleListProviderModesRequest(msg);
+            case "list_provider_features_request":
+                return this.handleListProviderFeaturesRequest(msg);
+            case "list_available_providers_request":
+                return this.handleListAvailableProvidersRequest(msg);
+            case "get_providers_snapshot_request":
+                return this.handleGetProvidersSnapshotRequest(msg);
+            case "refresh_providers_snapshot_request":
+                return this.handleRefreshProvidersSnapshotRequest(msg);
+            case "provider_diagnostic_request":
+                return this.handleProviderDiagnosticRequest(msg);
+            default:
+                return undefined;
+        }
+    }
+    dispatchTerminalMessage(msg) {
+        if (msg.type === "start_workspace_script_request") {
+            return this.handleStartWorkspaceScriptRequest(msg);
+        }
+        return this.terminalController.dispatch(msg);
+    }
+    dispatchChatScheduleLoopMessage(msg) {
+        switch (msg.type) {
+            case "chat/create":
+                return this.handleChatCreateRequest(msg);
+            case "chat/list":
+                return this.handleChatListRequest(msg);
+            case "chat/inspect":
+                return this.handleChatInspectRequest(msg);
+            case "chat/delete":
+                return this.handleChatDeleteRequest(msg);
+            case "chat/post":
+                return this.handleChatPostRequest(msg);
+            case "chat/read":
+                return this.handleChatReadRequest(msg);
+            case "chat/wait":
+                return this.handleChatWaitRequest(msg);
+            case "schedule/create":
+                return this.handleScheduleCreateRequest(msg);
+            case "schedule/list":
+                return this.handleScheduleListRequest(msg);
+            case "schedule/inspect":
+                return this.handleScheduleInspectRequest(msg);
+            case "schedule/logs":
+                return this.handleScheduleLogsRequest(msg);
+            case "schedule/pause":
+                return this.handleSchedulePauseRequest(msg);
+            case "schedule/resume":
+                return this.handleScheduleResumeRequest(msg);
+            case "schedule/delete":
+                return this.handleScheduleDeleteRequest(msg);
+            case "loop/run":
+                return this.handleLoopRunRequest(msg);
+            case "loop/list":
+                return this.handleLoopListRequest(msg);
+            case "loop/inspect":
+                return this.handleLoopInspectRequest(msg);
+            case "loop/logs":
+                return this.handleLoopLogsRequest(msg);
+            case "loop/stop":
+                return this.handleLoopStopRequest(msg);
+            default:
+                return undefined;
+        }
+    }
+    async dispatchMiscMessage(msg) {
+        switch (msg.type) {
+            case "list_commands_request":
+                await this.handleListCommandsRequest(msg);
+                return;
+            case "register_push_token":
+                this.handleRegisterPushToken(msg.token);
                 return;
         }
     }
+    resetPeakInflight() {
+        this.peakInflightRequests = this.inflightRequests;
+    }
+    handleBinaryFrame(frame) {
+        this.terminalController.handleBinaryFrame(frame);
+    }
     async handleRestartServerRequest(requestId, reason) {
         const payload = {
             status: "restart_requested",
@@ -1441,19 +1582,21 @@ export class Session {
         return { agentId, archivedAt: archivedRecord.archivedAt };
     }
     async handleCloseItemsRequest(msg) {
+        const archiveResults = await Promise.allSettled(msg.agentIds.map((agentId) => this.archiveAgentForClose(agentId)));
         const agents = [];
-        for (const agentId of msg.agentIds) {
-            try {
-                agents.push(await this.archiveAgentForClose(agentId));
+        for (let i = 0; i < archiveResults.length; i += 1) {
+            const result = archiveResults[i];
+            if (result.status === "fulfilled") {
+                agents.push(result.value);
             }
-            catch (error) {
-                this.sessionLogger.warn({ err: error, agentId, requestId: msg.requestId }, "Failed to archive agent during close_items batch");
+            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.killTerminalForClose(terminalId));
+                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");
@@ -1529,7 +1672,9 @@ export class Session {
                     requestId,
                     agentId,
                     accepted: false,
-                    error: error?.message ? String(error.message) : "Failed to update agent",
+                    error: error?.message
+                        ? String(error.message)
+                        : "Failed to update agent",
                 },
             });
         }
@@ -1882,14 +2027,22 @@ export class Session {
                 ...config,
                 ...(provisionalTitle ? { title: provisionalTitle } : {}),
             };
-            const { sessionConfig, worktreeBootstrap } = await this.buildAgentSessionConfig(resolvedConfig, git, worktreeName, attachments);
-            const resolvedWorkspace = msg.workspaceId
+            const firstAgentContext = {
+                ...(trimmedPrompt ? { prompt: trimmedPrompt } : {}),
+                ...(attachments && attachments.length > 0 ? { attachments } : {}),
+            };
+            const { sessionConfig, setupContinuation } = await this.buildAgentSessionConfig(resolvedConfig, git, worktreeName, firstAgentContext);
+            let resolvedWorkspace = msg.workspaceId
                 ? await this.workspaceRegistry.get(msg.workspaceId)
                 : ((await this.findWorkspaceByDirectory(sessionConfig.cwd)) ??
                     (await this.findOrCreateWorkspaceForDirectory(sessionConfig.cwd)));
             if (!resolvedWorkspace) {
                 throw new Error(`Workspace not found: ${msg.workspaceId}`);
             }
+            resolvedWorkspace = await this.maybeAutoNameWorkspaceBranchForFirstAgent({
+                workspace: resolvedWorkspace,
+                firstAgentContext,
+            });
             const snapshot = await this.agentManager.createAgent({
                 ...sessionConfig,
                 cwd: resolvedWorkspace.cwd,
@@ -1899,24 +2052,15 @@ export class Session {
                 initialPrompt: trimmedPrompt,
             });
             await this.forwardAgentUpdate(snapshot);
-            if (trimmedPrompt || (images?.length ?? 0) > 0 || (attachments?.length ?? 0) > 0) {
-                scheduleAgentMetadataGeneration({
-                    agentManager: this.agentManager,
-                    agentId: snapshot.id,
-                    cwd: snapshot.cwd,
-                    initialPrompt: trimmedPrompt,
-                    explicitTitle,
-                    paseoHome: this.paseoHome,
-                    logger: this.sessionLogger,
-                    deps: {
-                        workspaceGitService: this.workspaceGitService,
-                    },
-                });
-                const started = await this.handleSendAgentMessage(snapshot.id, trimmedPrompt || "", resolveClientMessageId(clientMessageId), images, attachments, outputSchema ? { outputSchema } : undefined);
-                if (!started.ok) {
-                    throw new Error(started.error);
-                }
-            }
+            await this.sendInitialCreateAgentPrompt({
+                snapshot,
+                trimmedPrompt,
+                images,
+                attachments,
+                clientMessageId,
+                outputSchema,
+                explicitTitle,
+            });
             if (requestId) {
                 const agentPayload = await this.buildAgentPayload(snapshot);
                 this.emit({
@@ -1929,25 +2073,9 @@ export class Session {
                     },
                 });
             }
-            if (worktreeBootstrap) {
-                void runAsyncWorktreeBootstrap({
-                    agentId: snapshot.id,
-                    worktree: worktreeBootstrap.worktree,
-                    shouldBootstrap: worktreeBootstrap.shouldBootstrap,
-                    terminalManager: this.terminalManager,
-                    appendTimelineItem: (item) => appendTimelineItemIfAgentKnown({
-                        agentManager: this.agentManager,
-                        agentId: snapshot.id,
-                        item,
-                    }),
-                    emitLiveTimelineItem: (item) => emitLiveTimelineItemIfAgentKnown({
-                        agentManager: this.agentManager,
-                        agentId: snapshot.id,
-                        item,
-                    }),
-                    logger: this.sessionLogger,
-                });
-            }
+            setupContinuation?.startAfterAgentCreate({
+                agentId: snapshot.id,
+            });
             this.sessionLogger.info({ agentId: snapshot.id, provider: snapshot.provider }, `Created agent ${snapshot.id} (${snapshot.provider})`);
         }
         catch (error) {
@@ -1975,6 +2103,28 @@ export class Session {
             });
         }
     }
+    async sendInitialCreateAgentPrompt(params) {
+        const { snapshot, trimmedPrompt, images, attachments, clientMessageId, outputSchema } = params;
+        const hasPrompt = Boolean(trimmedPrompt);
+        const hasImages = (images?.length ?? 0) > 0;
+        const hasAttachments = (attachments?.length ?? 0) > 0;
+        if (!hasPrompt && !hasImages && !hasAttachments) {
+            return;
+        }
+        scheduleAgentMetadataGeneration({
+            agentManager: this.agentManager,
+            agentId: snapshot.id,
+            cwd: snapshot.cwd,
+            initialPrompt: trimmedPrompt,
+            explicitTitle: params.explicitTitle,
+            paseoHome: this.paseoHome,
+            logger: this.sessionLogger,
+        });
+        const started = await this.handleSendAgentMessage(snapshot.id, trimmedPrompt || "", resolveClientMessageId(clientMessageId), images, attachments, outputSchema ? { outputSchema } : undefined);
+        if (!started.ok) {
+            throw new Error(started.error);
+        }
+    }
     async handleResumeAgentRequest(msg) {
         const { handle, overrides, requestId } = msg;
         if (!handle) {
@@ -2025,6 +2175,83 @@ export class Session {
             });
         }
     }
+    async handleImportAgentRequest(msg) {
+        const { provider, sessionId, cwd, labels, requestId } = msg;
+        this.sessionLogger.info({ sessionId, provider }, `Importing agent ${sessionId} (${provider})`);
+        try {
+            const descriptor = await this.agentManager.findPersistedAgent(provider, sessionId);
+            if (!descriptor && provider === "opencode" && !cwd) {
+                throw new Error("OpenCode sessions require --cwd when the session cannot be found in persisted agents");
+            }
+            const handle = descriptor
+                ? applyImportCwdOverride(descriptor.persistence, cwd)
+                : buildImportPersistenceHandle({ provider, sessionId, cwd });
+            const overrides = cwd ? { cwd } : undefined;
+            await this.unarchiveAgentByHandle(handle);
+            const snapshot = await this.agentManager.resumeAgentFromPersistence(handle, overrides, undefined, {
+                labels,
+            });
+            await unarchiveAgentState(this.agentStorage, this.agentManager, snapshot.id);
+            await this.agentManager.hydrateTimelineFromProvider(snapshot.id);
+            await this.applyImportedAgentTitle(snapshot);
+            await this.forwardAgentUpdate(snapshot);
+            const timelineSize = this.agentManager.getTimeline(snapshot.id).length;
+            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 applyImportedAgentTitle(snapshot) {
+        const initialPrompt = getFirstUserMessageText(this.agentManager.getTimeline(snapshot.id));
+        if (!initialPrompt) {
+            return;
+        }
+        const { explicitTitle, provisionalTitle } = resolveCreateAgentTitles({
+            configTitle: snapshot.config.title,
+            initialPrompt,
+        });
+        if (!explicitTitle && provisionalTitle) {
+            await this.agentManager.setTitle(snapshot.id, provisionalTitle);
+        }
+        scheduleAgentMetadataGeneration({
+            agentManager: this.agentManager,
+            agentId: snapshot.id,
+            cwd: snapshot.cwd,
+            initialPrompt,
+            explicitTitle,
+            paseoHome: this.paseoHome,
+            logger: this.sessionLogger,
+        });
+    }
     async handleRefreshAgentRequest(msg) {
         const { agentId, requestId } = msg;
         this.sessionLogger.info({ agentId }, `Refreshing agent ${agentId} from persistence`);
@@ -2041,7 +2268,11 @@ export class Session {
                 if (!record) {
                     throw new Error(`Agent not found: ${agentId}`);
                 }
-                const handle = toAgentPersistenceHandle(this.sessionLogger, this.providerRegistry, record.persistence);
+                const providerRegistry = this.getProviderRegistry();
+                if (!isStoredAgentProviderAvailable(record, Object.keys(providerRegistry))) {
+                    throw new Error(`Agent ${agentId} references unavailable provider '${record.provider}'`);
+                }
+                const handle = toAgentPersistenceHandle(providerRegistry, record.persistence);
                 if (!handle) {
                     throw new Error(`Agent ${agentId} cannot be refreshed because it lacks persistence`);
                 }
@@ -2096,16 +2327,67 @@ export class Session {
             this.handleAgentRunError(agentId, error, "Failed to cancel running agent on request");
         }
     }
-    async buildAgentSessionConfig(config, gitOptions, legacyWorktreeName, attachments) {
+    async buildAgentSessionConfig(config, gitOptions, legacyWorktreeName, firstAgentContext) {
         return buildWorktreeAgentSessionConfig({
             paseoHome: this.paseoHome,
             sessionLogger: this.sessionLogger,
             workspaceGitService: this.workspaceGitService,
-            createPaseoWorktree: (input, serviceOptions) => this.createPaseoWorktree(input, serviceOptions),
+            createPaseoWorktree: (input, serviceOptions) => this.createPaseoWorktreeWorkflow(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.checkoutExistingBranch(cwd, branch),
             createBranchFromBase: (params) => this.createBranchFromBase(params),
             github: this.github,
-        }, config, gitOptions, legacyWorktreeName, attachments);
+        }, config, gitOptions, legacyWorktreeName, firstAgentContext);
+    }
+    async maybeAutoNameWorkspaceBranchForFirstAgent(input) {
+        const coreDeps = createWorktreeCoreDeps(this.github);
+        const result = await attemptFirstAgentBranchAutoName({
+            cwd: input.workspace.cwd,
+            firstAgentContext: input.firstAgentContext,
+            generateBranchName: coreDeps.generateBranchName,
+        });
+        if (!result.renamed || !result.branchName) {
+            return input.workspace;
+        }
+        const updatedWorkspace = {
+            ...input.workspace,
+            displayName: result.branchName,
+            updatedAt: new Date().toISOString(),
+        };
+        await this.workspaceRegistry.upsert(updatedWorkspace);
+        await this.notifyGitMutation(input.workspace.cwd, "rename-branch");
+        await this.emitWorkspaceUpdateForCwd(input.workspace.cwd);
+        return updatedWorkspace;
+    }
+    emitProviderDisabledResponse(kind, provider, requestId, fetchedAt) {
+        const payload = {
+            provider,
+            error: `Provider ${provider} is disabled`,
+            fetchedAt,
+            requestId,
+        };
+        if (kind === "models") {
+            this.emit({ type: "list_provider_models_response", payload });
+        }
+        else {
+            this.emit({ type: "list_provider_modes_response", payload });
+        }
     }
     async handleListProviderModelsRequest(msg) {
         const cwd = resolveSnapshotCwd(msg.cwd ? expandTilde(msg.cwd) : undefined);
@@ -2113,7 +2395,12 @@ export class Session {
         const manager = this.providerSnapshotManager;
         if (!manager) {
             try {
-                const models = await this.providerRegistry[msg.provider].fetchModels({
+                const definition = this.getProviderRegistry()[msg.provider];
+                if (!definition.enabled) {
+                    this.emitProviderDisabledResponse("models", msg.provider, msg.requestId, fetchedAt);
+                    return;
+                }
+                const models = await definition.fetchModels({
                     cwd,
                     force: false,
                 });
@@ -2155,6 +2442,10 @@ export class Session {
             });
             return;
         }
+        if (!entry.enabled) {
+            this.emitProviderDisabledResponse("models", msg.provider, msg.requestId, fetchedAt);
+            return;
+        }
         if (entry.status === "ready") {
             this.emit({
                 type: "list_provider_models_response",
@@ -2199,6 +2490,10 @@ export class Session {
                 });
                 return;
             }
+            if (!entry.enabled) {
+                this.emitProviderDisabledResponse("modes", msg.provider, msg.requestId, fetchedAt);
+                return;
+            }
             if (entry.status === "ready") {
                 this.emit({
                     type: "list_provider_modes_response",
@@ -2227,7 +2522,12 @@ export class Session {
             return;
         }
         try {
-            const modes = await this.providerRegistry[msg.provider].fetchModes({
+            const definition = this.getProviderRegistry()[msg.provider];
+            if (!definition.enabled) {
+                this.emitProviderDisabledResponse("modes", msg.provider, msg.requestId, fetchedAt);
+                return;
+            }
+            const modes = await definition.fetchModes({
                 cwd,
                 force: false,
             });
@@ -2262,6 +2562,9 @@ export class Session {
         }
         const findEntry = () => manager.getSnapshot(cwd).find((candidate) => candidate.provider === provider);
         let entry = findEntry();
+        if (entry && !entry.enabled) {
+            return entry;
+        }
         if (!entry || entry.status === "loading") {
             // Awaits the in-flight warmup (deduped per-cwd) so old clients still get
             // a resolved answer rather than a loading placeholder.
@@ -2374,7 +2677,7 @@ export class Session {
     }
     async handleProviderDiagnosticRequest(msg) {
         try {
-            const client = this.providerRegistry[msg.provider].createClient(this.sessionLogger);
+            const client = this.getProviderRegistry()[msg.provider].createClient(this.sessionLogger);
             const diagnostic = client.getDiagnostic
                 ? (await client.getDiagnostic()).diagnostic
                 : "No diagnostic available for this provider.";
@@ -2431,7 +2734,7 @@ export class Session {
             ? [
                 "Files changed:",
                 ...diff.structured.map((file) => {
-                    const changeType = file.isNew ? "A" : file.isDeleted ? "D" : "M";
+                    const changeType = diffChangeTypeFor(file);
                     const status = file.status && file.status !== "ok" ? ` [${file.status}]` : "";
                     return `${changeType}\t${file.path}\t(+${file.additions} -${file.deletions})${status}`;
                 }),
@@ -2487,7 +2790,7 @@ export class Session {
             ? [
                 "Files changed:",
                 ...diff.structured.map((file) => {
-                    const changeType = file.isNew ? "A" : file.isDeleted ? "D" : "M";
+                    const changeType = diffChangeTypeFor(file);
                     const status = file.status && file.status !== "ok" ? ` [${file.status}]` : "";
                     return `${changeType}\t${file.path}\t(+${file.additions} -${file.deletions})${status}`;
                 }),
@@ -2543,7 +2846,9 @@ export class Session {
             return snapshot.git.isDirty === true;
         }
         catch (error) {
-            throw new Error(`Unable to inspect git status for ${cwd}: ${error.message}`);
+            throw new Error(`Unable to inspect git status for ${cwd}: ${error.message}`, {
+                cause: error,
+            });
         }
     }
     async checkoutExistingBranch(cwd, branch) {
@@ -2623,7 +2928,9 @@ export class Session {
                     requestId,
                     agentId,
                     accepted: false,
-                    error: error?.message ? String(error.message) : "Failed to set agent mode",
+                    error: error?.message
+                        ? String(error.message)
+                        : "Failed to set agent mode",
                 },
             });
         }
@@ -2655,7 +2962,9 @@ export class Session {
                     requestId,
                     agentId,
                     accepted: false,
-                    error: error?.message ? String(error.message) : "Failed to set agent model",
+                    error: error?.message
+                        ? String(error.message)
+                        : "Failed to set agent model",
                 },
             });
         }
@@ -2687,7 +2996,9 @@ export class Session {
                     requestId,
                     agentId,
                     accepted: false,
-                    error: error?.message ? String(error.message) : "Failed to set agent feature",
+                    error: error?.message
+                        ? String(error.message)
+                        : "Failed to set agent feature",
                 },
             });
         }
@@ -2719,7 +3030,9 @@ export class Session {
                     requestId,
                     agentId,
                     accepted: false,
-                    error: error?.message ? String(error.message) : "Failed to set agent thinking option",
+                    error: error?.message
+                        ? String(error.message)
+                        : "Failed to set agent thinking option",
                 },
             });
         }
@@ -3232,6 +3545,7 @@ export class Session {
             cwd,
             isGit: true,
             repoRoot: snapshot.git.repoRoot,
+            mainRepoRoot: snapshot.git.mainRepoRoot,
             currentBranch: snapshot.git.currentBranch ?? null,
             isDirty: snapshot.git.isDirty,
             baseRef: snapshot.git.baseRef ?? null,
@@ -3322,7 +3636,9 @@ export class Session {
             const message = branchLabel
                 ? `${Session.PASEO_STASH_PREFIX} ${branchLabel}`
                 : `${Session.PASEO_STASH_PREFIX} unnamed`;
-            await execCommand("git", ["stash", "push", "--include-untracked", "-m", message], { cwd });
+            await execCommand("git", ["stash", "push", "--include-untracked", "-m", message], {
+                cwd,
+            });
             await this.notifyGitMutation(cwd, "stash-push");
             this.checkoutDiffManager.scheduleRefreshForCwd(cwd);
             this.emit({
@@ -3340,7 +3656,9 @@ export class Session {
     async handleStashPopRequest(msg) {
         const { cwd, stashIndex, requestId } = msg;
         try {
-            await execCommand("git", ["stash", "pop", `stash@{${stashIndex}}`], { cwd });
+            await execCommand("git", ["stash", "pop", `stash@{${stashIndex}}`], {
+                cwd,
+            });
             await this.notifyGitMutation(cwd, "stash-pop");
             this.checkoutDiffManager.scheduleRefreshForCwd(cwd);
             this.emit({
@@ -3568,7 +3886,7 @@ export class Session {
                 title,
                 body,
                 base: msg.baseRef,
-            }, this.github, this.workspaceGitService);
+            }, this.github);
             await this.notifyGitMutation(cwd, "create-pr", { invalidateGithub: true });
             this.emit({
                 type: "checkout_pr_create_response",
@@ -3718,16 +4036,13 @@ export class Session {
             workspaceGitService: this.workspaceGitService,
             agentManager: this.agentManager,
             agentStorage: this.agentStorage,
-            archiveWorkspaceRecord: async (workspaceDirectory) => {
-                const workspace = await this.findWorkspaceByDirectory(workspaceDirectory);
-                if (workspace) {
-                    await this.archiveWorkspaceRecord(workspace.workspaceId);
-                }
-            },
+            archiveWorkspaceRecord: (workspaceId) => this.archiveWorkspaceRecord(workspaceId),
             emit: (message) => this.emit(message),
-            emitWorkspaceUpdatesForCwds: (cwds) => this.emitWorkspaceUpdatesForCwds(cwds),
+            emitWorkspaceUpdatesForWorkspaceIds: (workspaceIds) => this.emitWorkspaceUpdatesForWorkspaceIds(workspaceIds),
+            markWorkspaceArchiving: (workspaceIds, archivingAt) => this.markWorkspaceArchiving(workspaceIds, archivingAt),
+            clearWorkspaceArchiving: (workspaceIds) => this.clearWorkspaceArchiving(workspaceIds),
             isPathWithinRoot: (rootPath, candidatePath) => this.isPathWithinRoot(rootPath, candidatePath),
-            killTerminalsUnderPath: (rootPath) => this.killTerminalsUnderPath(rootPath),
+            killTerminalsUnderPath: (rootPath) => this.terminalController.killTerminalsUnderPath(rootPath),
             sessionLogger: this.sessionLogger,
         }, msg);
     }
@@ -3772,22 +4087,49 @@ export class Session {
                 });
             }
             else {
-                const file = await readExplorerFile({
-                    root: cwd,
-                    relativePath: requestedPath,
-                });
-                this.emit({
-                    type: "file_explorer_response",
-                    payload: {
-                        cwd,
-                        path: file.path,
-                        mode,
-                        directory: null,
-                        file,
-                        error: null,
+                if (request.acceptBinary && this.onBinaryMessage) {
+                    const file = await readExplorerFileBytes({
+                        root: cwd,
+                        relativePath: requestedPath,
+                    });
+                    this.emitBinary(encodeFileTransferFrame({
+                        opcode: FileTransferOpcode.FileBegin,
                         requestId,
-                    },
-                });
+                        metadata: {
+                            mime: file.mimeType,
+                            size: file.size,
+                            encoding: file.encoding,
+                            modifiedAt: file.modifiedAt,
+                        },
+                    }));
+                    this.emitBinary(encodeFileTransferFrame({
+                        opcode: FileTransferOpcode.FileChunk,
+                        requestId,
+                        payload: file.bytes,
+                    }));
+                    this.emitBinary(encodeFileTransferFrame({
+                        opcode: FileTransferOpcode.FileEnd,
+                        requestId,
+                    }));
+                }
+                else {
+                    const file = await readExplorerFile({
+                        root: cwd,
+                        relativePath: requestedPath,
+                    });
+                    this.emit({
+                        type: "file_explorer_response",
+                        payload: {
+                            cwd,
+                            path: file.path,
+                            mode,
+                            directory: null,
+                            file,
+                            error: null,
+                            requestId,
+                        },
+                    });
+                }
             }
         }
         catch (error) {
@@ -3912,9 +4254,12 @@ export class Session {
         // (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 = this.getRegisteredProviderIds();
         const persistedAgents = registryRecords
             .filter((record) => !liveIds.has(record.id) && !record.internal)
-            .map((record) => this.buildStoredAgentPayload(record));
+            .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));
         // Filter by labels if filter provided
@@ -3982,159 +4327,22 @@ export class Session {
         const payload = this.buildStoredAgentPayload(record);
         return this.isProviderVisibleToClient(payload.provider) ? payload : null;
     }
-    normalizeFetchAgentsSort(sort) {
-        const fallback = [{ key: "updated_at", direction: "desc" }];
-        if (!sort || sort.length === 0) {
-            return fallback;
-        }
-        const deduped = [];
-        const seen = new Set();
-        for (const entry of sort) {
-            if (seen.has(entry.key)) {
-                continue;
-            }
-            seen.add(entry.key);
-            deduped.push(entry);
-        }
-        return deduped.length > 0 ? deduped : fallback;
-    }
     getStatusPriority(agent) {
         const attentionReason = agent.attentionReason ?? null;
         const hasPendingPermission = (agent.pendingPermissions?.length ?? 0) > 0;
-        if (hasPendingPermission || attentionReason === "permission") {
-            return 0;
-        }
-        if (agent.status === "error" || attentionReason === "error") {
-            return 1;
-        }
-        if (agent.status === "running") {
-            return 2;
-        }
-        if (agent.status === "initializing") {
-            return 3;
-        }
-        return 4;
-    }
-    getFetchAgentsSortValue(entry, key) {
-        switch (key) {
-            case "status_priority":
-                return this.getStatusPriority(entry.agent);
-            case "created_at":
-                return Date.parse(entry.agent.createdAt);
-            case "updated_at":
-                return Date.parse(entry.agent.updatedAt);
-            case "title":
-                return entry.agent.title?.toLocaleLowerCase() ?? "";
-        }
-    }
-    getFetchAgentsSortValueFromAgent(agent, key) {
-        switch (key) {
-            case "status_priority":
-                return this.getStatusPriority(agent);
-            case "created_at":
-                return Date.parse(agent.createdAt);
-            case "updated_at":
-                return Date.parse(agent.updatedAt);
-            case "title":
-                return agent.title?.toLocaleLowerCase() ?? "";
-        }
-    }
-    compareSortValues(left, right) {
-        if (left === right) {
-            return 0;
-        }
-        if (left === null) {
-            return -1;
-        }
-        if (right === null) {
-            return 1;
-        }
-        if (typeof left === "number" && typeof right === "number") {
-            return left < right ? -1 : 1;
-        }
-        return String(left).localeCompare(String(right));
-    }
-    compareFetchAgentsAgents(left, right, sort) {
-        for (const spec of sort) {
-            const leftValue = this.getFetchAgentsSortValueFromAgent(left, spec.key);
-            const rightValue = this.getFetchAgentsSortValueFromAgent(right, spec.key);
-            const base = this.compareSortValues(leftValue, rightValue);
-            if (base === 0) {
-                continue;
-            }
-            return spec.direction === "asc" ? base : -base;
-        }
-        return left.id.localeCompare(right.id);
-    }
-    encodeFetchAgentsCursor(entry, sort) {
-        const values = {};
-        for (const spec of sort) {
-            values[spec.key] = this.getFetchAgentsSortValue(entry, spec.key);
-        }
-        return Buffer.from(JSON.stringify({
-            sort,
-            values,
-            id: entry.agent.id,
-        }), "utf8").toString("base64url");
-    }
-    decodeFetchAgentsCursor(cursor, sort) {
-        let parsed;
-        try {
-            parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
-        }
-        catch {
-            throw new SessionRequestError("invalid_cursor", "Invalid fetch_agents cursor");
-        }
-        if (!parsed || typeof parsed !== "object") {
-            throw new SessionRequestError("invalid_cursor", "Invalid fetch_agents cursor");
-        }
-        const payload = parsed;
-        if (!Array.isArray(payload.sort) || typeof payload.id !== "string") {
-            throw new SessionRequestError("invalid_cursor", "Invalid fetch_agents cursor");
-        }
-        if (!payload.values || typeof payload.values !== "object") {
-            throw new SessionRequestError("invalid_cursor", "Invalid fetch_agents cursor");
+        if (hasPendingPermission || attentionReason === "permission") {
+            return 0;
         }
-        const cursorSort = [];
-        for (const item of payload.sort) {
-            if (!item ||
-                typeof item !== "object" ||
-                typeof item.key !== "string" ||
-                typeof item.direction !== "string") {
-                throw new SessionRequestError("invalid_cursor", "Invalid fetch_agents cursor");
-            }
-            const key = item.key;
-            const direction = item.direction;
-            if ((key !== "status_priority" &&
-                key !== "created_at" &&
-                key !== "updated_at" &&
-                key !== "title") ||
-                (direction !== "asc" && direction !== "desc")) {
-                throw new SessionRequestError("invalid_cursor", "Invalid fetch_agents cursor");
-            }
-            cursorSort.push({ key, direction });
+        if (agent.status === "error" || attentionReason === "error") {
+            return 1;
         }
-        if (cursorSort.length !== sort.length ||
-            cursorSort.some((entry, index) => entry.key !== sort[index]?.key || entry.direction !== sort[index]?.direction)) {
-            throw new SessionRequestError("invalid_cursor", "fetch_agents cursor does not match current sort");
+        if (agent.status === "running") {
+            return 2;
         }
-        return {
-            sort: cursorSort,
-            values: payload.values,
-            id: payload.id,
-        };
-    }
-    compareAgentWithCursor(agent, cursor, sort) {
-        for (const spec of sort) {
-            const leftValue = this.getFetchAgentsSortValueFromAgent(agent, spec.key);
-            const rightValue = cursor.values[spec.key] !== undefined ? (cursor.values[spec.key] ?? null) : null;
-            const base = this.compareSortValues(leftValue, rightValue);
-            if (base === 0) {
-                continue;
-            }
-            return spec.direction === "asc" ? base : -base;
+        if (agent.status === "initializing") {
+            return 3;
         }
-        return agent.id.localeCompare(cursor.id);
+        return 4;
     }
     async buildActiveProjectPlacementsByWorkspaceCwd() {
         const [persistedWorkspaces, persistedProjects] = await Promise.all([
@@ -4145,27 +4353,59 @@ export class Session {
             .filter((project) => !project.archivedAt)
             .map((project) => [project.projectId, project]));
         const placementsByCwd = new Map();
-        for (const workspace of persistedWorkspaces) {
-            if (workspace.archivedAt) {
-                continue;
-            }
+        const pairs = persistedWorkspaces.flatMap((workspace) => {
+            if (workspace.archivedAt)
+                return [];
             const project = activeProjects.get(workspace.projectId);
-            if (!project) {
-                continue;
-            }
-            placementsByCwd.set(normalizePersistedWorkspaceId(workspace.cwd), await this.buildProjectPlacementForWorkspace(workspace, project));
+            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) {
+            placementsByCwd.set(normalizePersistedWorkspaceId(pairs[i].workspace.cwd), placements[i]);
         }
         return placementsByCwd;
     }
+    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.cwd);
+                return project ? { agent, project } : null;
+            }));
+            for (const entry of batchEntries) {
+                if (!entry) {
+                    continue;
+                }
+                if (!this.matchesAgentFilter({
+                    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.normalizeFetchAgentsSort(request.sort);
+        const sort = this.agentsPager.normalizeSort(request.sort);
         let agents = await this.listAgentPayloads({
             labels: filter?.labels,
+            includeUnavailablePersisted: request.type === "fetch_agent_history_request",
         });
         const activePlacementsByCwd = scope === "active" ? await this.buildActiveProjectPlacementsByWorkspaceCwd() : null;
         if (activePlacementsByCwd) {
@@ -4185,42 +4425,23 @@ export class Session {
             return placementPromise;
         };
         let candidates = [...agents];
-        candidates.sort((left, right) => this.compareFetchAgentsAgents(left, right, sort));
+        candidates.sort((left, right) => this.agentsPager.compare(left, right, sort));
         const cursorToken = request.page?.cursor;
         if (cursorToken) {
-            const cursor = this.decodeFetchAgentsCursor(cursorToken, sort);
-            candidates = candidates.filter((agent) => this.compareAgentWithCursor(agent, cursor, sort) > 0);
+            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 = [];
-        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.cwd);
-                return project ? { agent, project } : null;
-            }));
-            for (const entry of batchEntries) {
-                if (!entry) {
-                    continue;
-                }
-                if (!this.matchesAgentFilter({
-                    agent: entry.agent,
-                    project: entry.project,
-                    filter,
-                })) {
-                    continue;
-                }
-                matchedEntries.push(entry);
-                if (matchedEntries.length > limit) {
-                    break;
-                }
-            }
-        }
+        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.encodeFetchAgentsCursor(pagedEntries[pagedEntries.length - 1], sort)
+            ? this.agentsPager.encode(pagedEntries[pagedEntries.length - 1].agent, sort)
             : null;
         return {
             entries: pagedEntries,
@@ -4231,21 +4452,16 @@ export class Session {
             },
         };
     }
-    deriveWorkspaceStateBucket(agent) {
-        const pendingPermissionCount = agent.pendingPermissions?.length ?? 0;
-        if (pendingPermissionCount > 0 || agent.attentionReason === "permission") {
-            return "needs_input";
-        }
-        if (agent.status === "error" || agent.attentionReason === "error") {
-            return "failed";
-        }
-        if (agent.status === "running") {
-            return "running";
+    decodeAgentCursor(token, sort) {
+        try {
+            return this.agentsPager.decode(token, sort);
         }
-        if (agent.requiresAttention) {
-            return "attention";
+        catch (error) {
+            if (error instanceof CursorError) {
+                throw new SessionRequestError("invalid_cursor", error.message);
+            }
+            throw error;
         }
-        return "done";
     }
     async describeWorkspaceRecord(workspace, projectRecord) {
         const resolvedProjectRecord = projectRecord ?? (await this.projectRegistry.get(workspace.projectId));
@@ -4263,6 +4479,7 @@ export class Session {
             projectKind: (resolvedProjectRecord?.kind ?? "directory") === "git" ? "git" : "non_git",
             workspaceKind: workspace.kind,
             name: workspace.displayName,
+            archivingAt: null,
             status: "done",
             activityAt: null,
             diffStat,
@@ -4270,6 +4487,7 @@ export class Session {
                 ? buildWorkspaceScriptPayloads({
                     workspaceId: workspace.workspaceId,
                     workspaceDirectory: workspace.cwd,
+                    paseoConfig: readPaseoConfigForProjection(workspace.cwd, this.sessionLogger),
                     routeStore: this.scriptRouteStore,
                     runtimeStore: this.scriptRuntimeStore,
                     daemonPort: this.getDaemonTcpPort?.() ?? null,
@@ -4277,6 +4495,11 @@ export class Session {
                     resolveHealth: this.resolveScriptHealth ?? undefined,
                 })
                 : [],
+            ...(resolvedProjectRecord
+                ? {
+                    project: await this.buildProjectPlacementForWorkspace(workspace, resolvedProjectRecord),
+                }
+                : {}),
         };
     }
     buildWorkspaceGitRuntimePayload(snapshot) {
@@ -4327,6 +4550,7 @@ export class Session {
             projectKind: "git",
             workspaceKind: result.workspace.kind,
             name: result.worktree.branchName || result.workspace.displayName,
+            archivingAt: null,
             status: "done",
             activityAt: null,
             diffStat: { additions: 0, deletions: 0 },
@@ -4349,248 +4573,31 @@ export class Session {
         }
         return this.describeWorkspaceRecord(input.workspace, input.projectRecord);
     }
-    async buildWorkspaceDescriptorMap(options) {
-        const [agents, persistedWorkspaces, persistedProjects] = await Promise.all([
-            this.listAgentPayloads(),
-            this.workspaceRegistry.list(),
-            this.projectRegistry.list(),
-        ]);
-        const activeProjects = new Map(persistedProjects
-            .filter((project) => !project.archivedAt)
-            .map((project) => [project.projectId, project]));
-        const archivedProjectIds = new Set(persistedProjects.filter((project) => project.archivedAt).map((project) => project.projectId));
-        const activeRecords = persistedWorkspaces.filter((workspace) => !workspace.archivedAt && !archivedProjectIds.has(workspace.projectId));
-        const descriptorsByWorkspaceId = new Map();
-        const workspaceIds = options.workspaceIds ? new Set(options.workspaceIds) : null;
-        const workspaceIdsByDirectory = new Map(activeRecords.map((workspace) => [normalizePersistedWorkspaceId(workspace.cwd), workspace.workspaceId]));
-        for (const workspace of activeRecords) {
-            if (workspaceIds && !workspaceIds.has(workspace.workspaceId)) {
-                continue;
-            }
-            const projectRecord = activeProjects.get(workspace.projectId) ?? null;
-            descriptorsByWorkspaceId.set(workspace.workspaceId, await this.buildWorkspaceDescriptor({
-                workspace,
-                projectRecord,
-                includeGitData: options.includeGitData,
-            }));
-        }
-        for (const agent of agents) {
-            if (agent.archivedAt) {
-                continue;
-            }
-            if (!this.isProviderVisibleToClient(agent.provider)) {
-                continue;
-            }
-            const workspaceId = workspaceIdsByDirectory.get(normalizePersistedWorkspaceId(agent.cwd));
-            if (workspaceId === undefined) {
-                continue;
-            }
-            const existing = descriptorsByWorkspaceId.get(workspaceId);
-            if (!existing) {
-                continue;
-            }
-            const bucket = this.deriveWorkspaceStateBucket(agent);
-            if (this.workspaceStatePriority[bucket] < this.workspaceStatePriority[existing.status]) {
-                existing.status = bucket;
-            }
-        }
-        return descriptorsByWorkspaceId;
+    markWorkspaceArchiving(workspaceIds, archivingAt) {
+        this.workspaceDirectory.markArchiving(workspaceIds, archivingAt);
     }
-    resolveRegisteredWorkspaceIdForCwd(cwd, workspaces) {
-        const normalizedCwd = normalizePersistedWorkspaceId(cwd);
-        const exact = workspaces.find((workspace) => workspace.cwd === normalizedCwd);
-        if (exact) {
-            return exact.workspaceId;
-        }
-        let bestMatch = null;
-        for (const workspace of workspaces) {
-            const prefix = workspace.cwd.endsWith(sep) ? workspace.cwd : `${workspace.cwd}${sep}`;
-            if (!normalizedCwd.startsWith(prefix)) {
-                continue;
-            }
-            if (!bestMatch || workspace.cwd.length > bestMatch.cwd.length) {
-                bestMatch = workspace;
-            }
-        }
-        return bestMatch?.workspaceId ?? normalizedCwd;
+    clearWorkspaceArchiving(workspaceIds) {
+        this.workspaceDirectory.clearArchiving(workspaceIds);
     }
-    async listWorkspaceDescriptors() {
-        return Array.from((await this.buildWorkspaceDescriptorMap({
-            includeGitData: true,
-        })).values());
+    async buildWorkspaceDescriptorMap(options) {
+        return this.workspaceDirectory.buildDescriptorMap(options);
     }
-    normalizeFetchWorkspacesSort(sort) {
-        const fallback = [{ key: "activity_at", direction: "desc" }];
-        if (!sort || sort.length === 0) {
-            return fallback;
-        }
-        const deduped = [];
-        const seen = new Set();
-        for (const entry of sort) {
-            if (seen.has(entry.key)) {
-                continue;
-            }
-            seen.add(entry.key);
-            deduped.push(entry);
-        }
-        return deduped.length > 0 ? deduped : fallback;
-    }
-    getFetchWorkspacesSortValue(workspace, key) {
-        switch (key) {
-            case "status_priority":
-                return this.workspaceStatePriority[workspace.status];
-            case "activity_at":
-                return workspace.activityAt ? Date.parse(workspace.activityAt) : null;
-            case "name":
-                return workspace.name.toLocaleLowerCase();
-            case "project_id":
-                return workspace.projectId.toLocaleLowerCase();
-        }
-    }
-    compareFetchWorkspacesEntries(left, right, sort) {
-        for (const spec of sort) {
-            const leftValue = this.getFetchWorkspacesSortValue(left, spec.key);
-            const rightValue = this.getFetchWorkspacesSortValue(right, spec.key);
-            const base = this.compareSortValues(leftValue, rightValue);
-            if (base === 0) {
-                continue;
-            }
-            return spec.direction === "asc" ? base : -base;
-        }
-        return left.id.localeCompare(right.id);
+    resolveRegisteredWorkspaceIdForCwd(cwd, workspaces) {
+        return this.workspaceDirectory.resolveRegisteredWorkspaceIdForCwd(cwd, workspaces);
     }
-    encodeFetchWorkspacesCursor(entry, sort) {
-        const values = {};
-        for (const spec of sort) {
-            values[spec.key] = this.getFetchWorkspacesSortValue(entry, spec.key);
-        }
-        return Buffer.from(JSON.stringify({
-            sort,
-            values,
-            id: entry.id,
-        }), "utf8").toString("base64url");
+    matchesWorkspaceFilter(input) {
+        return this.workspaceDirectory.matchesFilter(input);
     }
-    decodeFetchWorkspacesCursor(cursor, sort) {
-        let parsed;
+    async listFetchWorkspacesEntries(request) {
         try {
-            parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
-        }
-        catch {
-            throw new SessionRequestError("invalid_cursor", "Invalid fetch_workspaces cursor");
-        }
-        if (!parsed || typeof parsed !== "object") {
-            throw new SessionRequestError("invalid_cursor", "Invalid fetch_workspaces cursor");
-        }
-        const payload = parsed;
-        if (!Array.isArray(payload.sort) || typeof payload.id !== "string") {
-            throw new SessionRequestError("invalid_cursor", "Invalid fetch_workspaces cursor");
+            return await this.workspaceDirectory.listFetchEntries(request);
         }
-        if (!payload.values || typeof payload.values !== "object") {
-            throw new SessionRequestError("invalid_cursor", "Invalid fetch_workspaces cursor");
-        }
-        const cursorSort = [];
-        for (const item of payload.sort) {
-            if (!item ||
-                typeof item !== "object" ||
-                typeof item.key !== "string" ||
-                typeof item.direction !== "string") {
-                throw new SessionRequestError("invalid_cursor", "Invalid fetch_workspaces cursor");
-            }
-            const key = item.key;
-            const direction = item.direction;
-            if ((key !== "status_priority" &&
-                key !== "activity_at" &&
-                key !== "name" &&
-                key !== "project_id") ||
-                (direction !== "asc" && direction !== "desc")) {
-                throw new SessionRequestError("invalid_cursor", "Invalid fetch_workspaces cursor");
-            }
-            cursorSort.push({ key, direction });
-        }
-        if (cursorSort.length !== sort.length ||
-            cursorSort.some((entry, index) => entry.key !== sort[index]?.key || entry.direction !== sort[index]?.direction)) {
-            throw new SessionRequestError("invalid_cursor", "fetch_workspaces cursor does not match current sort");
-        }
-        return {
-            sort: cursorSort,
-            values: payload.values,
-            id: String(payload.id),
-        };
-    }
-    compareWorkspaceWithCursor(workspace, cursor, sort) {
-        for (const spec of sort) {
-            const leftValue = this.getFetchWorkspacesSortValue(workspace, spec.key);
-            const rightValue = cursor.values[spec.key] !== undefined ? (cursor.values[spec.key] ?? null) : null;
-            const base = this.compareSortValues(leftValue, rightValue);
-            if (base === 0) {
-                continue;
-            }
-            return spec.direction === "asc" ? base : -base;
-        }
-        return workspace.id.localeCompare(cursor.id);
-    }
-    matchesWorkspaceFilter(input) {
-        const { workspace, filter } = input;
-        if (!filter) {
-            return true;
-        }
-        if (filter.projectId && filter.projectId.trim().length > 0) {
-            if (workspace.projectId !== filter.projectId.trim()) {
-                return false;
-            }
-        }
-        if (filter.idPrefix && filter.idPrefix.trim().length > 0) {
-            if (!String(workspace.id).startsWith(filter.idPrefix.trim())) {
-                return false;
-            }
-        }
-        if (filter.query && filter.query.trim().length > 0) {
-            const query = filter.query.trim().toLocaleLowerCase();
-            const haystacks = [workspace.name, String(workspace.projectId), String(workspace.id)];
-            if (!haystacks.some((value) => value.toLocaleLowerCase().includes(query))) {
-                return false;
+        catch (error) {
+            if (error instanceof CursorError) {
+                throw new SessionRequestError("invalid_cursor", error.message);
             }
+            throw error;
         }
-        return true;
-    }
-    async listFetchWorkspacesEntries(request) {
-        const filter = request.filter;
-        const sort = this.normalizeFetchWorkspacesSort(request.sort);
-        let entries = await this.listWorkspaceDescriptors();
-        const listedCount = entries.length;
-        entries = entries.filter((workspace) => this.matchesWorkspaceFilter({ workspace, filter }));
-        const filteredCount = entries.length;
-        entries.sort((left, right) => this.compareFetchWorkspacesEntries(left, right, sort));
-        const cursorToken = request.page?.cursor;
-        if (cursorToken) {
-            const cursor = this.decodeFetchWorkspacesCursor(cursorToken, sort);
-            entries = entries.filter((workspace) => this.compareWorkspaceWithCursor(workspace, cursor, sort) > 0);
-        }
-        const limit = request.page?.limit ?? 200;
-        const pagedEntries = entries.slice(0, limit);
-        const hasMore = entries.length > limit;
-        const nextCursor = hasMore && pagedEntries.length > 0
-            ? this.encodeFetchWorkspacesCursor(pagedEntries[pagedEntries.length - 1], sort)
-            : null;
-        this.sessionLogger.debug({
-            requestId: request.requestId,
-            filter: request.filter ?? null,
-            sort,
-            page: request.page ?? null,
-            listedCount,
-            filteredCount,
-            returnedCount: pagedEntries.length,
-            hasMore,
-            nextCursor,
-        }, "fetch_workspaces_entries_listed");
-        return {
-            entries: pagedEntries,
-            pageInfo: {
-                nextCursor,
-                prevCursor: request.page?.cursor ?? null,
-                hasMore,
-            },
-        };
     }
     bufferOrEmitWorkspaceUpdate(subscription, payload) {
         if (subscription.isBootstrapping) {
@@ -4633,41 +4640,121 @@ export class Session {
         }
     }
     async findOrCreateWorkspaceForDirectory(cwd) {
+        const inputCwd = normalizePersistedWorkspaceId(cwd);
         const normalizedCwd = await this.resolveWorkspaceDirectory(cwd);
-        const existingWorkspace = await this.findWorkspaceByDirectory(normalizedCwd);
+        const existingWorkspace = await this.findExactWorkspaceByDirectory(normalizedCwd, {
+            refreshGit: false,
+        });
         if (existingWorkspace) {
-            return this.ensureWorkspaceRecordUnarchived(existingWorkspace);
+            if (existingWorkspace.archivedAt && inputCwd !== normalizedCwd) {
+                const timestamp = new Date().toISOString();
+                const displayName = basename(inputCwd) || inputCwd;
+                const projectRecord = createPersistedProjectRecord({
+                    projectId: inputCwd,
+                    rootPath: inputCwd,
+                    kind: "non_git",
+                    displayName,
+                    createdAt: timestamp,
+                    updatedAt: timestamp,
+                });
+                await this.projectRegistry.upsert(projectRecord);
+                const workspaceRecord = createPersistedWorkspaceRecord({
+                    workspaceId: inputCwd,
+                    projectId: projectRecord.projectId,
+                    cwd: inputCwd,
+                    kind: "directory",
+                    displayName,
+                    createdAt: timestamp,
+                    updatedAt: timestamp,
+                });
+                await this.workspaceRegistry.upsert(workspaceRecord);
+                return workspaceRecord;
+            }
+            return this.reclassifyOrUnarchiveWorkspaceForDirectory({
+                workspace: existingWorkspace,
+                project: await this.projectRegistry.get(existingWorkspace.projectId),
+                cwd: normalizedCwd,
+            });
         }
-        const placement = await buildProjectPlacementForCwdStandalone({
-            cwd: normalizedCwd,
-            workspaceGitService: this.workspaceGitService,
-        });
-        const workspaceId = deriveWorkspaceId(normalizedCwd, placement.checkout);
+        return this.createWorkspaceForDirectory(normalizedCwd);
+    }
+    async createWorkspaceForDirectory(cwd) {
+        const checkout = await this.workspaceGitService.getCheckout(cwd);
+        const membership = classifyDirectoryForProjectMembership({ cwd, checkout });
         const timestamp = new Date().toISOString();
-        const projectRecord = createPersistedProjectRecord({
-            projectId: placement.projectKey,
-            rootPath: deriveProjectRootPath({ cwd: normalizedCwd, checkout: placement.checkout }),
-            kind: deriveProjectKind(placement.checkout),
-            displayName: placement.projectName,
-            createdAt: timestamp,
-            updatedAt: timestamp,
+        const projectRecord = await this.resolveProjectRecordForPlacement({
+            membership,
+            timestamp,
         });
         await this.projectRegistry.upsert(projectRecord);
         const workspaceRecord = createPersistedWorkspaceRecord({
-            workspaceId,
-            projectId: placement.projectKey,
-            cwd: normalizedCwd,
-            kind: deriveWorkspaceKind(placement.checkout),
-            displayName: deriveWorkspaceDisplayName({
-                cwd: normalizedCwd,
-                checkout: placement.checkout,
-            }),
+            workspaceId: membership.workspaceId,
+            projectId: projectRecord.projectId,
+            cwd,
+            kind: membership.workspaceKind,
+            displayName: membership.workspaceDisplayName,
             createdAt: timestamp,
             updatedAt: timestamp,
         });
         await this.workspaceRegistry.upsert(workspaceRecord);
         return workspaceRecord;
     }
+    async reclassifyOrUnarchiveWorkspaceForDirectory(input) {
+        const checkout = await this.workspaceGitService.getCheckout(input.cwd);
+        const membership = classifyDirectoryForProjectMembership({ cwd: input.cwd, checkout });
+        const timestamp = new Date().toISOString();
+        const projectRecord = await this.resolveProjectRecordForPlacement({
+            membership,
+            timestamp,
+        });
+        const projectId = projectRecord.projectId;
+        const kind = membership.workspaceKind;
+        const displayName = membership.workspaceDisplayName;
+        if (input.workspace.workspaceId === membership.workspaceId &&
+            input.workspace.projectId === projectId &&
+            input.workspace.kind === kind &&
+            input.workspace.displayName === displayName) {
+            return this.ensureWorkspaceRecordUnarchived(input.workspace);
+        }
+        await this.projectRegistry.upsert(projectRecord);
+        const nextWorkspace = {
+            ...input.workspace,
+            workspaceId: membership.workspaceId,
+            projectId,
+            cwd: input.cwd,
+            kind,
+            displayName,
+            archivedAt: null,
+            updatedAt: timestamp,
+        };
+        await this.workspaceRegistry.upsert(nextWorkspace);
+        return nextWorkspace;
+    }
+    async resolveProjectRecordForPlacement(input) {
+        const rootPath = input.membership.projectRootPath;
+        const kind = input.membership.projectKind;
+        const projects = await this.projectRegistry.list();
+        const existingProject = projects.find((project) => !project.archivedAt && project.rootPath === rootPath) ??
+            projects.find((project) => project.rootPath === rootPath) ??
+            null;
+        if (!existingProject) {
+            return createPersistedProjectRecord({
+                projectId: input.membership.projectKey,
+                rootPath,
+                kind,
+                displayName: input.membership.projectName,
+                createdAt: input.timestamp,
+                updatedAt: input.timestamp,
+            });
+        }
+        return {
+            ...existingProject,
+            rootPath,
+            kind,
+            archivedAt: null,
+            updatedAt: input.timestamp,
+        };
+    }
     async ensureWorkspaceRecordUnarchived(workspace) {
         const project = await this.projectRegistry.get(workspace.projectId);
         if (!workspace.archivedAt && (!project || !project.archivedAt)) {
@@ -4749,7 +4836,7 @@ export class Session {
         const result = await service.runOnce();
         const changedWorkspaceIds = new Set();
         const changedProjectIds = new Set();
-        for (const change of result.changesApplied) {
+        await Promise.all(result.changesApplied.map(async (change) => {
             switch (change.kind) {
                 case "workspace_archived":
                     await this.removeWorkspaceGitWatchTarget(change.directory);
@@ -4765,7 +4852,7 @@ export class Session {
                     changedProjectIds.add(change.projectId);
                     break;
             }
-        }
+        }));
         if (changedProjectIds.size > 0) {
             for (const workspace of await this.workspaceRegistry.list()) {
                 if (changedProjectIds.has(workspace.projectId)) {
@@ -4834,21 +4921,9 @@ export class Session {
         const workspaceId = this.resolveRegisteredWorkspaceIdForCwd(cwd, workspaces);
         await this.emitWorkspaceUpdatesForWorkspaceIds([workspaceId], options);
     }
-    async emitWorkspaceUpdatesForCwds(cwds) {
-        const workspaces = await this.workspaceRegistry.list();
-        const uniqueWorkspaceIds = new Set();
-        for (const cwd of cwds) {
-            uniqueWorkspaceIds.add(this.resolveRegisteredWorkspaceIdForCwd(cwd, workspaces));
-        }
-        await this.emitWorkspaceUpdatesForWorkspaceIds(uniqueWorkspaceIds);
-    }
     async handleFetchAgents(request) {
         const requestedSubscriptionId = request.subscribe?.subscriptionId?.trim();
-        const subscriptionId = request.subscribe
-            ? requestedSubscriptionId && requestedSubscriptionId.length > 0
-                ? requestedSubscriptionId
-                : uuidv4()
-            : null;
+        const subscriptionId = resolveSubscriptionId(request.subscribe, requestedSubscriptionId);
         try {
             if (subscriptionId) {
                 this.agentUpdatesSubscription = {
@@ -4924,11 +4999,7 @@ export class Session {
     }
     async handleFetchWorkspacesRequest(request) {
         const requestedSubscriptionId = request.subscribe?.subscriptionId?.trim();
-        const subscriptionId = request.subscribe
-            ? requestedSubscriptionId && requestedSubscriptionId.length > 0
-                ? requestedSubscriptionId
-                : uuidv4()
-            : null;
+        const subscriptionId = resolveSubscriptionId(request.subscribe, requestedSubscriptionId);
         try {
             this.sessionLogger.debug({
                 requestId: request.requestId,
@@ -4997,8 +5068,9 @@ export class Session {
     async handleOpenProjectRequest(request) {
         try {
             const workspace = await this.findOrCreateWorkspaceForDirectory(request.cwd);
+            await this.syncWorkspaceGitObserverForWorkspace(workspace);
+            const descriptor = await this.describeWorkspaceRecord(workspace);
             await this.emitWorkspaceUpdateForCwd(workspace.cwd);
-            const descriptor = await this.describeWorkspaceRecordWithGitData(workspace);
             this.emit({
                 type: "open_project_response",
                 payload: {
@@ -5007,6 +5079,15 @@ export class Session {
                     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";
@@ -5028,6 +5109,7 @@ export class Session {
         return buildWorkspaceScriptPayloads({
             workspaceId,
             workspaceDirectory,
+            paseoConfig: readPaseoConfigForProjection(workspaceDirectory, this.sessionLogger),
             routeStore: this.scriptRouteStore,
             runtimeStore: this.scriptRuntimeStore,
             daemonPort: this.getDaemonTcpPort?.() ?? null,
@@ -5178,15 +5260,15 @@ export class Session {
             paseoHome: this.paseoHome,
             describeWorkspaceRecord: (result) => this.describeCreatedWorktreeWorkspace(result),
             emit: (message) => this.emit(message),
-            createPaseoWorktree: (input) => this.createPaseoWorktree(input),
-            warmWorkspaceGitData: (workspace) => this.warmWorkspaceGitDataForWorkspace(workspace),
             sessionLogger: this.sessionLogger,
-            runWorktreeSetupInBackground: (options) => this.runWorktreeSetupInBackground(options),
+            createPaseoWorktreeWorkflow: (input) => this.createPaseoWorktreeWorkflow(input),
         }, request);
     }
-    async runWorktreeSetupInBackground(options) {
-        return runWorktreeSetupInBackgroundSession({
+    async createPaseoWorktreeWorkflow(input, options) {
+        return createWorktreeWorkflow({
             paseoHome: this.paseoHome,
+            createPaseoWorktree: (workflowInput, serviceOptions) => this.createPaseoWorktree(workflowInput, serviceOptions),
+            warmWorkspaceGitData: (workspace) => this.warmWorkspaceGitDataForWorkspace(workspace),
             emitWorkspaceUpdateForCwd: (cwd, emitOptions) => this.emitWorkspaceUpdateForCwd(cwd, emitOptions),
             cacheWorkspaceSetupSnapshot: (workspaceId, snapshot) => {
                 this.workspaceSetupSnapshots.set(workspaceId, snapshot);
@@ -5202,7 +5284,7 @@ export class Session {
             onScriptsChanged: (workspaceId, workspaceDirectory) => {
                 this.emitWorkspaceScriptStatusUpdate(workspaceId, workspaceDirectory);
             },
-        }, options);
+        }, input, options);
     }
     async handleWorkspaceSetupStatusRequest(request) {
         return handleWorkspaceSetupStatusRequestMessage({
@@ -5274,6 +5356,53 @@ export class Session {
             payload: { requestId, agent, project, error: null },
         });
     }
+    loadProjectedTimelineWindow(params) {
+        const { agentId, direction, cursor, requestedLimit } = params;
+        let timeline = params.timeline;
+        const projectedLimit = Math.max(1, Math.floor(requestedLimit));
+        let fetchLimit = projectedLimit;
+        let projectedWindow = selectTimelineWindowByProjectedLimit({
+            rows: timeline.rows,
+            direction,
+            limit: projectedLimit,
+            collapseToolLifecycle: false,
+        });
+        while (timeline.hasOlder) {
+            const needsMoreProjectedEntries = projectedWindow.projectedEntries.length < projectedLimit;
+            const firstLoadedRow = timeline.rows[0];
+            const firstSelectedRow = projectedWindow.selectedRows[0];
+            const startsAtLoadedBoundary = firstLoadedRow != null &&
+                firstSelectedRow != null &&
+                firstSelectedRow.seq === firstLoadedRow.seq;
+            const boundaryIsAssistantChunk = startsAtLoadedBoundary && firstLoadedRow.item.type === "assistant_message";
+            if (!needsMoreProjectedEntries && !boundaryIsAssistantChunk) {
+                break;
+            }
+            const maxRows = Math.max(0, timeline.window.maxSeq - timeline.window.minSeq + 1);
+            const nextFetchLimit = Math.min(maxRows, fetchLimit * 2);
+            if (nextFetchLimit <= fetchLimit) {
+                break;
+            }
+            fetchLimit = nextFetchLimit;
+            timeline = this.agentManager.fetchTimeline(agentId, {
+                direction,
+                cursor,
+                limit: fetchLimit,
+            });
+            projectedWindow = selectTimelineWindowByProjectedLimit({
+                rows: timeline.rows,
+                direction,
+                limit: projectedLimit,
+                collapseToolLifecycle: false,
+            });
+        }
+        return {
+            timeline,
+            selectedRows: projectedWindow.selectedRows,
+            minSeq: projectedWindow.minSeq,
+            maxSeq: projectedWindow.maxSeq,
+        };
+    }
     async handleFetchAgentTimelineRequest(msg) {
         const direction = msg.direction ?? (msg.cursor ? "after" : "tail");
         const projection = msg.projection ?? "projected";
@@ -5309,51 +5438,19 @@ export class Session {
             let endCursor = null;
             let entries;
             if (shouldLimitByProjectedWindow) {
-                const projectedLimit = Math.max(1, Math.floor(requestedLimit));
-                let fetchLimit = projectedLimit;
-                let projectedWindow = selectTimelineWindowByProjectedLimit({
-                    rows: timeline.rows,
-                    provider: snapshot.provider,
+                const projectedResult = this.loadProjectedTimelineWindow({
+                    agentId: msg.agentId,
                     direction,
-                    limit: projectedLimit,
-                    collapseToolLifecycle: false,
+                    cursor,
+                    requestedLimit,
+                    timeline,
                 });
-                while (timeline.hasOlder) {
-                    const needsMoreProjectedEntries = projectedWindow.projectedEntries.length < projectedLimit;
-                    const firstLoadedRow = timeline.rows[0];
-                    const firstSelectedRow = projectedWindow.selectedRows[0];
-                    const startsAtLoadedBoundary = firstLoadedRow != null &&
-                        firstSelectedRow != null &&
-                        firstSelectedRow.seq === firstLoadedRow.seq;
-                    const boundaryIsAssistantChunk = startsAtLoadedBoundary && firstLoadedRow.item.type === "assistant_message";
-                    if (!needsMoreProjectedEntries && !boundaryIsAssistantChunk) {
-                        break;
-                    }
-                    const maxRows = Math.max(0, timeline.window.maxSeq - timeline.window.minSeq + 1);
-                    const nextFetchLimit = Math.min(maxRows, fetchLimit * 2);
-                    if (nextFetchLimit <= fetchLimit) {
-                        break;
-                    }
-                    fetchLimit = nextFetchLimit;
-                    timeline = this.agentManager.fetchTimeline(msg.agentId, {
-                        direction,
-                        cursor,
-                        limit: fetchLimit,
-                    });
-                    projectedWindow = selectTimelineWindowByProjectedLimit({
-                        rows: timeline.rows,
-                        provider: snapshot.provider,
-                        direction,
-                        limit: projectedLimit,
-                        collapseToolLifecycle: false,
-                    });
-                }
-                const selectedRows = projectedWindow.selectedRows;
-                entries = projectTimelineRows(selectedRows, snapshot.provider, projection);
-                if (projectedWindow.minSeq !== null && projectedWindow.maxSeq !== null) {
-                    startCursor = { epoch: timeline.epoch, seq: projectedWindow.minSeq };
-                    endCursor = { epoch: timeline.epoch, seq: projectedWindow.maxSeq };
-                    hasOlder = projectedWindow.minSeq > timeline.window.minSeq;
+                timeline = projectedResult.timeline;
+                entries = projectTimelineRows({ rows: projectedResult.selectedRows, mode: projection });
+                if (projectedResult.minSeq !== null && projectedResult.maxSeq !== null) {
+                    startCursor = { epoch: timeline.epoch, seq: projectedResult.minSeq };
+                    endCursor = { epoch: timeline.epoch, seq: projectedResult.maxSeq };
+                    hasOlder = projectedResult.minSeq > timeline.window.minSeq;
                     hasNewer = false;
                 }
             }
@@ -5362,7 +5459,7 @@ export class Session {
                 const lastRow = timeline.rows[timeline.rows.length - 1];
                 startCursor = firstRow ? { epoch: timeline.epoch, seq: firstRow.seq } : null;
                 endCursor = lastRow ? { epoch: timeline.epoch, seq: lastRow.seq } : null;
-                entries = projectTimelineRows(timeline.rows, snapshot.provider, projection);
+                entries = projectTimelineRows({ rows: timeline.rows, mode: projection });
             }
             this.emit({
                 type: "fetch_agent_timeline_response",
@@ -5381,7 +5478,17 @@ export class Session {
                     endCursor,
                     hasOlder,
                     hasNewer,
-                    entries,
+                    entries: entries.map((entry) => ({
+                        provider: snapshot.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,
                 },
             });
@@ -5461,18 +5568,13 @@ export class Session {
                 await this.agentManager.waitForAgentRunStart(agentId, { signal: startAbort.signal });
             }
             catch (error) {
-                const message = error instanceof Error
-                    ? error.message
-                    : typeof error === "string"
-                        ? error
-                        : "Unknown error";
                 this.emit({
                     type: "send_agent_message_response",
                     payload: {
                         requestId: msg.requestId,
                         agentId,
                         accepted: false,
-                        error: message,
+                        error: errorToFriendlyMessage(error),
                     },
                 });
                 return;
@@ -5491,18 +5593,13 @@ export class Session {
             });
         }
         catch (error) {
-            const message = error instanceof Error
-                ? error.message
-                : typeof error === "string"
-                    ? error
-                    : "Unknown error";
             this.emit({
                 type: "send_agent_message_response",
                 payload: {
                     requestId: msg.requestId,
                     agentId: resolved.agentId,
                     accepted: false,
-                    error: message,
+                    error: errorToFriendlyMessage(error),
                 },
             });
         }
@@ -5540,11 +5637,16 @@ export class Session {
                 return;
             }
             const final = this.buildStoredAgentPayload(record);
-            const status = record.attentionReason === "permission"
-                ? "permission"
-                : record.lastStatus === "error"
-                    ? "error"
-                    : "idle";
+            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",
@@ -5568,11 +5670,16 @@ export class Session {
             if (!final) {
                 throw new Error(`Agent ${agentId} disappeared while waiting`);
             }
-            let status = result.permission
-                ? "permission"
-                : result.status === "error"
-                    ? "error"
-                    : "idle";
+            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",
@@ -5583,11 +5690,7 @@ export class Session {
             const isAbort = error instanceof Error &&
                 (error.name === "AbortError" || error.message.toLowerCase().includes("aborted"));
             if (!isAbort) {
-                const message = error instanceof Error
-                    ? error.message
-                    : typeof error === "string"
-                        ? error
-                        : "Unknown error";
+                const message = errorToFriendlyMessage(error);
                 this.sessionLogger.error({ err: error, agentId }, "wait_for_finish_request failed");
                 const final = await this.getAgentPayloadById(agentId);
                 this.emit({
@@ -5604,7 +5707,7 @@ export class Session {
             }
             const final = await this.getAgentPayloadById(agentId);
             if (!final) {
-                throw new Error(`Agent ${agentId} disappeared while waiting`);
+                throw new Error(`Agent ${agentId} disappeared while waiting`, { cause: error });
             }
             this.emit({
                 type: "wait_for_finish_response",
@@ -5614,50 +5717,13 @@ export class Session {
         finally {
             if (timeoutHandle) {
                 clearTimeout(timeoutHandle);
-            }
-        }
-    }
-    /**
-     * Handle audio chunk for buffering and transcription
-     */
-    async handleAudioChunk(msg) {
-        if (!this.isVoiceMode) {
-            this.sessionLogger.warn("Received voice_audio_chunk while voice mode is disabled; transcript will be emitted but voice assistant turn is skipped");
-        }
-        const chunkFormat = msg.format || "audio/wav";
-        if (this.isVoiceMode) {
-            if (!this.voiceTurnController) {
-                throw new Error("Voice mode is enabled but the voice turn controller is not running");
-            }
-            const chunkBytes = Buffer.byteLength(msg.audio, "base64");
-            this.voiceInputChunkCount += 1;
-            this.voiceInputBytes += chunkBytes;
-            if (this.voiceInputChunkCount === 1) {
-                this.sessionLogger.info({
-                    format: chunkFormat,
-                    audioBytes: chunkBytes,
-                }, "Received first voice_audio_chunk for active voice mode");
-            }
-            const now = Date.now();
-            if (this.voiceInputChunkCount % 50 === 0 || now - this.voiceInputWindowStartedAt >= 1000) {
-                this.sessionLogger.info({
-                    chunkCount: this.voiceInputChunkCount,
-                    audioBytes: this.voiceInputBytes,
-                    windowMs: now - this.voiceInputWindowStartedAt,
-                    format: chunkFormat,
-                }, "Voice input chunk summary");
-                this.voiceInputWindowStartedAt = now;
-                this.voiceInputChunkCount = 0;
-                this.voiceInputBytes = 0;
-            }
-            await this.voiceTurnController.appendClientChunk({
-                audioBase64: msg.audio,
-                format: chunkFormat,
-            });
-            return;
+            }
         }
-        const chunkBuffer = Buffer.from(msg.audio, "base64");
-        const isPCMChunk = chunkFormat.toLowerCase().includes("pcm");
+    }
+    /**
+     * Handle audio chunk for buffering and transcription
+     */
+    async ensureAudioBufferForFormat(chunkFormat, isPCMChunk) {
         if (!this.audioBuffer) {
             this.audioBuffer = {
                 chunks: [],
@@ -5665,8 +5731,8 @@ export class Session {
                 isPCM: isPCMChunk,
                 totalPCMBytes: 0,
             };
+            return this.audioBuffer;
         }
-        // If the format changes mid-stream, flush what we have first
         if (this.audioBuffer.isPCM !== isPCMChunk) {
             this.sessionLogger.debug({
                 oldFormat: this.audioBuffer.isPCM ? "pcm" : this.audioBuffer.format,
@@ -5682,19 +5748,61 @@ export class Session {
                 isPCM: isPCMChunk,
                 totalPCMBytes: 0,
             };
+            return this.audioBuffer;
         }
-        else if (!this.audioBuffer.isPCM) {
-            // Keep latest format info for non-PCM blobs
+        if (!this.audioBuffer.isPCM) {
             this.audioBuffer.format = chunkFormat;
         }
-        this.audioBuffer.chunks.push(chunkBuffer);
-        if (this.audioBuffer.isPCM) {
-            this.audioBuffer.totalPCMBytes += chunkBuffer.length;
+        return this.audioBuffer;
+    }
+    async forwardAudioChunkToVoiceTurn(msg, chunkFormat) {
+        if (!this.voiceTurnController) {
+            throw new Error("Voice mode is enabled but the voice turn controller is not running");
+        }
+        const chunkBytes = Buffer.byteLength(msg.audio, "base64");
+        this.voiceInputChunkCount += 1;
+        this.voiceInputBytes += chunkBytes;
+        if (this.voiceInputChunkCount === 1) {
+            this.sessionLogger.info({
+                format: chunkFormat,
+                audioBytes: chunkBytes,
+            }, "Received first voice_audio_chunk for active voice mode");
+        }
+        const now = Date.now();
+        if (this.voiceInputChunkCount % 50 === 0 || now - this.voiceInputWindowStartedAt >= 1000) {
+            this.sessionLogger.info({
+                chunkCount: this.voiceInputChunkCount,
+                audioBytes: this.voiceInputBytes,
+                windowMs: now - this.voiceInputWindowStartedAt,
+                format: chunkFormat,
+            }, "Voice input chunk summary");
+            this.voiceInputWindowStartedAt = now;
+            this.voiceInputChunkCount = 0;
+            this.voiceInputBytes = 0;
+        }
+        await this.voiceTurnController.appendClientChunk({
+            audioBase64: msg.audio,
+            format: chunkFormat,
+        });
+    }
+    async handleAudioChunk(msg) {
+        if (!this.isVoiceMode) {
+            this.sessionLogger.warn("Received voice_audio_chunk while voice mode is disabled; transcript will be emitted but voice assistant turn is skipped");
+        }
+        const chunkFormat = msg.format || "audio/wav";
+        if (this.isVoiceMode) {
+            await this.forwardAudioChunkToVoiceTurn(msg, chunkFormat);
+            return;
+        }
+        const chunkBuffer = Buffer.from(msg.audio, "base64");
+        const isPCMChunk = chunkFormat.toLowerCase().includes("pcm");
+        const buffer = await this.ensureAudioBufferForFormat(chunkFormat, isPCMChunk);
+        buffer.chunks.push(chunkBuffer);
+        if (buffer.isPCM) {
+            buffer.totalPCMBytes += chunkBuffer.length;
         }
         // In non-voice mode, use streaming threshold to process chunks
-        const reachedStreamingThreshold = !this.isVoiceMode &&
-            this.audioBuffer.isPCM &&
-            this.audioBuffer.totalPCMBytes >= MIN_STREAMING_SEGMENT_BYTES;
+        const reachedStreamingThreshold = !this.isVoiceMode && buffer.isPCM && buffer.totalPCMBytes >= MIN_STREAMING_SEGMENT_BYTES;
         if (!msg.isLast && reachedStreamingThreshold) {
             return;
         }
@@ -6133,17 +6241,7 @@ export class Session {
         }
         await this.disableVoiceModeForActiveAgent(true);
         this.isVoiceMode = false;
-        // Unsubscribe from all terminals
-        if (this.unsubscribeTerminalsChanged) {
-            this.unsubscribeTerminalsChanged();
-            this.unsubscribeTerminalsChanged = null;
-        }
-        this.subscribedTerminalDirectories.clear();
-        for (const unsubscribeExit of this.terminalExitSubscriptions.values()) {
-            unsubscribeExit();
-        }
-        this.terminalExitSubscriptions.clear();
-        this.disposeTerminalSubscriptions();
+        this.terminalController.dispose();
         for (const unsubscribe of this.checkoutDiffSubscriptions.values()) {
             unsubscribe();
         }
@@ -6153,26 +6251,6 @@ export class Session {
         }
         this.workspaceGitSubscriptions.clear();
     }
-    // ----------------------------------------------------------------------------
-    // Terminal Handlers
-    // ----------------------------------------------------------------------------
-    ensureTerminalExitSubscription(terminal) {
-        if (this.terminalExitSubscriptions.has(terminal.id)) {
-            return;
-        }
-        const unsubscribeExit = terminal.onExit(() => {
-            this.handleTerminalExited(terminal.id);
-        });
-        this.terminalExitSubscriptions.set(terminal.id, unsubscribeExit);
-    }
-    handleTerminalExited(terminalId) {
-        const unsubscribeExit = this.terminalExitSubscriptions.get(terminalId);
-        if (unsubscribeExit) {
-            unsubscribeExit();
-            this.terminalExitSubscriptions.delete(terminalId);
-        }
-        this.detachTerminalStream(terminalId, { emitExit: true });
-    }
     emitChatRpcError(request, error) {
         const message = error instanceof Error ? error.message : "Chat request failed";
         const code = error instanceof ChatServiceError ? error.code : "chat_request_failed";
@@ -6261,7 +6339,7 @@ export class Session {
     async handleChatPostRequest(request) {
         try {
             const authorAgentId = request.authorAgentId?.trim() || this.clientId;
-            const message = await this.chatService.postMessage({
+            const message = await this.chatService.dispatchMessage({
                 room: request.room,
                 authorAgentId,
                 body: request.body,
@@ -6585,462 +6663,6 @@ export class Session {
             this.emitLoopRpcError(request, error);
         }
     }
-    emitTerminalsChangedSnapshot(input) {
-        this.emit({
-            type: "terminals_changed",
-            payload: {
-                cwd: input.cwd,
-                terminals: input.terminals,
-            },
-        });
-    }
-    filterStandaloneTerminals(terminals) {
-        return terminals;
-    }
-    toTerminalInfo(terminal) {
-        const title = terminal.getTitle();
-        return {
-            id: terminal.id,
-            name: terminal.name,
-            ...(title ? { title } : {}),
-        };
-    }
-    handleTerminalsChanged(event) {
-        if (!this.subscribedTerminalDirectories.has(event.cwd)) {
-            return;
-        }
-        this.emitTerminalsChangedSnapshot({
-            cwd: event.cwd,
-            terminals: this.filterStandaloneTerminals(event.terminals).map((terminal) => ({
-                id: terminal.id,
-                name: terminal.name,
-                ...(terminal.title ? { title: terminal.title } : {}),
-            })),
-        });
-    }
-    handleSubscribeTerminalsRequest(msg) {
-        this.subscribedTerminalDirectories.add(msg.cwd);
-        void this.emitInitialTerminalsChangedSnapshot(msg.cwd);
-    }
-    handleUnsubscribeTerminalsRequest(msg) {
-        this.subscribedTerminalDirectories.delete(msg.cwd);
-    }
-    async emitInitialTerminalsChangedSnapshot(cwd) {
-        if (!this.terminalManager || !this.subscribedTerminalDirectories.has(cwd)) {
-            return;
-        }
-        try {
-            const terminals = this.filterStandaloneTerminals(await this.terminalManager.getTerminals(cwd));
-            for (const terminal of terminals) {
-                this.ensureTerminalExitSubscription(terminal);
-            }
-            if (!this.subscribedTerminalDirectories.has(cwd)) {
-                return;
-            }
-            this.emitTerminalsChangedSnapshot({
-                cwd,
-                terminals: terminals.map((terminal) => this.toTerminalInfo(terminal)),
-            });
-        }
-        catch (error) {
-            this.sessionLogger.warn({ err: error, cwd }, "Failed to emit initial terminal snapshot");
-        }
-    }
-    async handleListTerminalsRequest(msg) {
-        if (!this.terminalManager) {
-            this.emit({
-                type: "list_terminals_response",
-                payload: {
-                    ...(msg.cwd ? { cwd: msg.cwd } : {}),
-                    terminals: [],
-                    requestId: msg.requestId,
-                },
-            });
-            return;
-        }
-        try {
-            const terminals = this.filterStandaloneTerminals(typeof msg.cwd === "string"
-                ? await this.terminalManager.getTerminals(msg.cwd)
-                : await this.getAllTerminalSessions());
-            for (const terminal of terminals) {
-                this.ensureTerminalExitSubscription(terminal);
-            }
-            this.emit({
-                type: "list_terminals_response",
-                payload: {
-                    ...(msg.cwd ? { cwd: msg.cwd } : {}),
-                    terminals: terminals.map((terminal) => this.toTerminalInfo(terminal)),
-                    requestId: msg.requestId,
-                },
-            });
-        }
-        catch (error) {
-            this.sessionLogger.error({ err: error, cwd: msg.cwd }, "Failed to list terminals");
-            this.emit({
-                type: "list_terminals_response",
-                payload: {
-                    ...(msg.cwd ? { cwd: msg.cwd } : {}),
-                    terminals: [],
-                    requestId: msg.requestId,
-                },
-            });
-        }
-    }
-    async getAllTerminalSessions() {
-        if (!this.terminalManager) {
-            return [];
-        }
-        const directories = this.terminalManager.listDirectories();
-        const terminalsByDirectory = await Promise.all(directories.map((cwd) => this.terminalManager.getTerminals(cwd)));
-        return terminalsByDirectory.flat();
-    }
-    async handleCreateTerminalRequest(msg) {
-        if (!this.terminalManager) {
-            this.emit({
-                type: "create_terminal_response",
-                payload: {
-                    terminal: null,
-                    error: "Terminal manager not available",
-                    requestId: msg.requestId,
-                },
-            });
-            return;
-        }
-        try {
-            if (msg.agentId) {
-                this.emit({
-                    type: "create_terminal_response",
-                    payload: {
-                        terminal: null,
-                        error: `Agent-backed terminals are no longer supported for agent ${msg.agentId}`,
-                        requestId: msg.requestId,
-                    },
-                });
-                return;
-            }
-            const session = await this.terminalManager.createTerminal({
-                cwd: msg.cwd,
-                name: msg.name,
-                command: msg.command,
-                args: msg.args,
-            });
-            this.ensureTerminalExitSubscription(session);
-            this.emit({
-                type: "create_terminal_response",
-                payload: {
-                    terminal: {
-                        id: session.id,
-                        name: session.name,
-                        cwd: session.cwd,
-                        ...(session.getTitle() ? { title: session.getTitle() } : {}),
-                    },
-                    error: null,
-                    requestId: msg.requestId,
-                },
-            });
-        }
-        catch (error) {
-            this.sessionLogger.error({ err: error, cwd: msg.cwd }, "Failed to create terminal");
-            this.emit({
-                type: "create_terminal_response",
-                payload: {
-                    terminal: null,
-                    error: error.message,
-                    requestId: msg.requestId,
-                },
-            });
-        }
-    }
-    async handleSubscribeTerminalRequest(msg) {
-        if (!this.terminalManager) {
-            this.emit({
-                type: "subscribe_terminal_response",
-                payload: {
-                    terminalId: msg.terminalId,
-                    error: "Terminal manager not available",
-                    requestId: msg.requestId,
-                },
-            });
-            return;
-        }
-        const session = this.terminalManager.getTerminal(msg.terminalId);
-        if (!session) {
-            this.emit({
-                type: "subscribe_terminal_response",
-                payload: {
-                    terminalId: msg.terminalId,
-                    error: "Terminal not found",
-                    requestId: msg.requestId,
-                },
-            });
-            return;
-        }
-        this.ensureTerminalExitSubscription(session);
-        const slot = this.bindActiveTerminalStream(session);
-        if (slot === null) {
-            this.sessionLogger.warn({
-                terminalId: msg.terminalId,
-                activeTerminalStreamCount: this.activeTerminalStreams.size,
-            }, "Terminal stream slot exhaustion");
-            this.emit({
-                type: "subscribe_terminal_response",
-                payload: {
-                    terminalId: msg.terminalId,
-                    error: "No terminal stream slots available",
-                    requestId: msg.requestId,
-                },
-            });
-            return;
-        }
-        this.emit({
-            type: "subscribe_terminal_response",
-            payload: {
-                terminalId: msg.terminalId,
-                slot,
-                error: null,
-                requestId: msg.requestId,
-            },
-        });
-        const activeStream = this.activeTerminalStreams.get(slot);
-        if (activeStream) {
-            this.trySendTerminalSnapshot(activeStream);
-        }
-    }
-    handleUnsubscribeTerminalRequest(msg) {
-        this.detachTerminalStream(msg.terminalId, { emitExit: false });
-    }
-    handleTerminalInput(msg) {
-        if (!this.terminalManager) {
-            return;
-        }
-        const session = this.terminalManager.getTerminal(msg.terminalId);
-        if (!session) {
-            this.sessionLogger.warn({ terminalId: msg.terminalId }, "Terminal not found for input");
-            return;
-        }
-        this.ensureTerminalExitSubscription(session);
-        if (msg.message.type === "resize") {
-            const currentSize = session.getSize();
-            if (currentSize.rows === msg.message.rows && currentSize.cols === msg.message.cols) {
-                return;
-            }
-        }
-        session.send(msg.message);
-    }
-    killTrackedTerminal(terminalId, options) {
-        this.detachTerminalStream(terminalId, { emitExit: options?.emitExit ?? true });
-        this.terminalManager?.killTerminal(terminalId);
-    }
-    async killTerminalsUnderPath(rootPath) {
-        return killWorktreeTerminalsUnderPath({
-            isPathWithinRoot: (pathRoot, candidatePath) => this.isPathWithinRoot(pathRoot, candidatePath),
-            killTrackedTerminal: (terminalId, options) => this.killTrackedTerminal(terminalId, options),
-            detachTerminalStream: (terminalId, options) => void this.detachTerminalStream(terminalId, options),
-            sessionLogger: this.sessionLogger,
-            terminalManager: this.terminalManager,
-        }, rootPath);
-    }
-    async handleKillTerminalRequest(msg) {
-        const result = this.killTerminalForClose(msg.terminalId);
-        this.emit({
-            type: "kill_terminal_response",
-            payload: {
-                terminalId: result.terminalId,
-                success: result.success,
-                requestId: msg.requestId,
-            },
-        });
-    }
-    killTerminalForClose(terminalId) {
-        if (!this.terminalManager) {
-            return {
-                terminalId,
-                success: false,
-            };
-        }
-        this.killTrackedTerminal(terminalId, { emitExit: true });
-        return {
-            terminalId,
-            success: true,
-        };
-    }
-    async handleCaptureTerminalRequest(msg) {
-        if (!this.terminalManager) {
-            this.emit({
-                type: "capture_terminal_response",
-                payload: {
-                    terminalId: msg.terminalId,
-                    lines: [],
-                    totalLines: 0,
-                    requestId: msg.requestId,
-                },
-            });
-            return;
-        }
-        const session = this.terminalManager.getTerminal(msg.terminalId);
-        if (!session) {
-            this.emit({
-                type: "capture_terminal_response",
-                payload: {
-                    terminalId: msg.terminalId,
-                    lines: [],
-                    totalLines: 0,
-                    requestId: msg.requestId,
-                },
-            });
-            return;
-        }
-        this.ensureTerminalExitSubscription(session);
-        try {
-            const capture = captureTerminalLines(session, {
-                start: msg.start,
-                end: msg.end,
-                stripAnsi: msg.stripAnsi,
-            });
-            this.emit({
-                type: "capture_terminal_response",
-                payload: {
-                    terminalId: msg.terminalId,
-                    lines: capture.lines,
-                    totalLines: capture.totalLines,
-                    requestId: msg.requestId,
-                },
-            });
-        }
-        catch (error) {
-            this.sessionLogger.error({ err: error, terminalId: msg.terminalId }, "Failed to capture terminal");
-            this.emit({
-                type: "capture_terminal_response",
-                payload: {
-                    terminalId: msg.terminalId,
-                    lines: [],
-                    totalLines: 0,
-                    requestId: msg.requestId,
-                },
-            });
-        }
-    }
-    bindActiveTerminalStream(terminal) {
-        if (!this.onBinaryMessage) {
-            return null;
-        }
-        const existingSlot = this.terminalIdToSlot.get(terminal.id);
-        if (typeof existingSlot === "number") {
-            const existingStream = this.activeTerminalStreams.get(existingSlot);
-            if (existingStream) {
-                existingStream.needsSnapshot = true;
-                return existingSlot;
-            }
-            this.terminalIdToSlot.delete(terminal.id);
-        }
-        const slot = this.allocateTerminalSlot();
-        if (slot === null) {
-            return null;
-        }
-        const activeStream = {
-            terminalId: terminal.id,
-            slot,
-            unsubscribe: () => { },
-            needsSnapshot: true,
-            outputCoalescer: new TerminalOutputCoalescer({
-                timers: { setTimeout, clearTimeout },
-                onFlush: ({ payload }) => {
-                    if (this.activeTerminalStreams.get(slot) !== activeStream) {
-                        return;
-                    }
-                    this.emitBinary(encodeTerminalStreamFrame({
-                        opcode: TerminalStreamOpcode.Output,
-                        slot,
-                        payload,
-                    }));
-                },
-            }),
-        };
-        this.activeTerminalStreams.set(slot, activeStream);
-        this.terminalIdToSlot.set(terminal.id, slot);
-        activeStream.unsubscribe = terminal.subscribe((message) => {
-            if (this.activeTerminalStreams.get(slot) !== activeStream) {
-                return;
-            }
-            if (message.type === "snapshot") {
-                activeStream.outputCoalescer.flush();
-                activeStream.needsSnapshot = true;
-                this.trySendTerminalSnapshot(activeStream);
-                return;
-            }
-            if (message.type === "titleChange") {
-                return;
-            }
-            if (activeStream.needsSnapshot || message.data.length === 0) {
-                return;
-            }
-            activeStream.outputCoalescer.handle(message.data);
-        });
-        return slot;
-    }
-    trySendTerminalSnapshot(activeStream) {
-        if (this.activeTerminalStreams.get(activeStream.slot) !== activeStream ||
-            !activeStream.needsSnapshot) {
-            return;
-        }
-        const terminal = this.terminalManager?.getTerminal(activeStream.terminalId);
-        if (!terminal) {
-            this.detachTerminalStream(activeStream.terminalId, { emitExit: true });
-            return;
-        }
-        activeStream.outputCoalescer.flush();
-        activeStream.needsSnapshot = false;
-        this.emitBinary(encodeTerminalStreamFrame({
-            opcode: TerminalStreamOpcode.Snapshot,
-            slot: activeStream.slot,
-            payload: encodeTerminalSnapshotPayload(terminal.getState()),
-        }));
-    }
-    allocateTerminalSlot() {
-        for (let attempt = 0; attempt < MAX_TERMINAL_STREAM_SLOTS; attempt += 1) {
-            const slot = (this.nextTerminalSlot + attempt) % MAX_TERMINAL_STREAM_SLOTS;
-            if (this.activeTerminalStreams.has(slot)) {
-                continue;
-            }
-            this.nextTerminalSlot = (slot + 1) % MAX_TERMINAL_STREAM_SLOTS;
-            return slot;
-        }
-        return null;
-    }
-    detachTerminalStream(terminalId, options) {
-        const slot = this.terminalIdToSlot.get(terminalId);
-        if (typeof slot !== "number") {
-            return false;
-        }
-        const activeStream = this.activeTerminalStreams.get(slot);
-        if (!activeStream) {
-            this.terminalIdToSlot.delete(terminalId);
-            return false;
-        }
-        activeStream.outputCoalescer.flush();
-        this.activeTerminalStreams.delete(slot);
-        this.terminalIdToSlot.delete(terminalId);
-        try {
-            activeStream.unsubscribe();
-        }
-        catch (error) {
-            this.sessionLogger.warn({ err: error }, "Failed to unsubscribe terminal stream");
-        }
-        if (options?.emitExit) {
-            this.emit({
-                type: "terminal_stream_exit",
-                payload: {
-                    terminalId: activeStream.terminalId,
-                },
-            });
-        }
-        return true;
-    }
-    disposeTerminalSubscriptions() {
-        for (const terminalId of [...this.terminalIdToSlot.keys()]) {
-            this.detachTerminalStream(terminalId, { emitExit: false });
-        }
-    }
 }
 // ---------------------------------------------------------------------------
 // Stash handlers