@getpaseo/server 0.1.61 → 0.1.63

package/dist/server/server/session.js

@@ -2,7 +2,8 @@ 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 { isLegacyEditorTargetId, serializeAgentStreamEvent, } from "./messages.js";
@@ -16,7 +17,7 @@ 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";
@@ -24,6 +25,7 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 import { buildWorkspaceScriptPayloads } 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,11 +34,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 { readPaseoConfigForEdit, writePaseoConfigForEdit, } from "../utils/paseo-config-file.js";
 import { runAsyncWorktreeBootstrap } from "./worktree-bootstrap.js";
 import { archivePersistedWorkspaceRecord } from "./workspace-archive-service.js";
 import { WorkspaceReconciliationService } from "./workspace-reconciliation-service.js";
@@ -57,13 +60,98 @@ import { assertSafeGitRef as assertWorktreeSafeGitRef, buildAgentSessionConfig a
 import { killTerminalsUnderPath as killWorktreeTerminalsUnderPath } from "./paseo-worktree-archive-service.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_FINGERPRINT = "__removed__";
+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;
@@ -119,6 +207,50 @@ export function resolveCreateAgentTitles(options) {
         provisionalTitle,
     };
 }
+function parseFetchWorkspacesCursorSort(raw) {
+    const cursorSort = [];
+    for (const item of raw) {
+        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 });
+    }
+    return cursorSort;
+}
+function parseFetchAgentsCursorSort(raw) {
+    const cursorSort = [];
+    for (const item of raw) {
+        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 });
+    }
+    return cursorSort;
+}
 export function resolveWaitForFinishError(options) {
     if (options.status !== "error") {
         return null;
@@ -292,53 +424,13 @@ 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({
-            logger: this.sessionLogger,
-            sessionId: this.sessionId,
-            emit: (msg) => this.handleDictationManagerMessage(msg),
-            stt: dictation?.stt ?? null,
-            finalTimeoutMs: dictation?.finalTimeoutMs,
-        });
+        this.initializePerSessionManagers({ tts, stt, dictation });
         // Initialize agent MCP client asynchronously
         void this.initializeAgentMcp();
         this.subscribeToAgentEvents();
@@ -349,9 +441,9 @@ export class Session {
             this.appVersion = appVersion;
         }
     }
-    async primeWorkspaceGitWatchFingerprintForWorkspace(workspace) {
+    async syncWorkspaceGitObserverForWorkspace(workspace) {
         const descriptor = await this.describeWorkspaceRecordWithGitData(workspace);
-        await this.primeWorkspaceGitWatchFingerprints([descriptor]);
+        this.syncWorkspaceGitObservers([descriptor]);
     }
     async emitWorkspaceUpdateForWorkspaceId(workspaceId) {
         await this.emitWorkspaceUpdatesForWorkspaceIds([workspaceId], { skipReconcile: true });
@@ -363,7 +455,7 @@ export class Session {
         await this.emitWorkspaceUpdatesForCwds(cwds);
     }
     async warmWorkspaceGitDataForWorkspace(workspace) {
-        await this.primeWorkspaceGitWatchFingerprintForWorkspace(workspace);
+        await this.syncWorkspaceGitObserverForWorkspace(workspace);
         await this.emitWorkspaceUpdateForWorkspaceId(workspace.workspaceId);
     }
     /**
@@ -427,16 +519,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 +551,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 +568,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 +604,50 @@ export class Session {
     /**
      * Subscribe to AgentManager events and forward them to the client
      */
+    subscribeToOptionalManagers() {
+        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);
+            };
+        }
+    }
+    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 +744,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 +770,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 +805,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 +871,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 +970,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,6 +1007,418 @@ export class Session {
             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;
+        }
+    }
+    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;
+        }
+        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 "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;
+        }
+        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) {
+        switch (msg.type) {
+            case "subscribe_terminals_request":
+                this.handleSubscribeTerminalsRequest(msg);
+                return undefined;
+            case "unsubscribe_terminals_request":
+                this.handleUnsubscribeTerminalsRequest(msg);
+                return undefined;
+            case "list_terminals_request":
+                return this.handleListTerminalsRequest(msg);
+            case "create_terminal_request":
+                return this.handleCreateTerminalRequest(msg);
+            case "start_workspace_script_request":
+                return this.handleStartWorkspaceScriptRequest(msg);
+            case "subscribe_terminal_request":
+                return this.handleSubscribeTerminalRequest(msg);
+            case "unsubscribe_terminal_request":
+                this.handleUnsubscribeTerminalRequest(msg);
+                return undefined;
+            case "terminal_input":
+                this.handleTerminalInput(msg);
+                return undefined;
+            case "kill_terminal_request":
+                return this.handleKillTerminalRequest(msg);
+            case "capture_terminal_request":
+                return this.handleCaptureTerminalRequest(msg);
+            default:
+                return undefined;
+        }
+    }
+    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;
     }
@@ -1441,13 +1619,15 @@ 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 = [];
@@ -1529,7 +1709,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",
                 },
             });
         }
@@ -1899,24 +2081,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({
@@ -1975,6 +2148,31 @@ 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,
+            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);
+        }
+    }
     async handleResumeAgentRequest(msg) {
         const { handle, overrides, requestId } = msg;
         if (!handle) {
@@ -2041,7 +2239,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`);
                 }
@@ -2107,13 +2309,32 @@ export class Session {
             github: this.github,
         }, config, gitOptions, legacyWorktreeName, attachments);
     }
+    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);
         const fetchedAt = new Date().toISOString();
         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 +2376,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 +2424,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 +2456,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 +2496,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 +2611,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 +2668,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 +2724,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 +2780,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 +2862,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 +2896,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 +2930,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 +2964,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",
                 },
             });
         }
@@ -3105,9 +3352,9 @@ export class Session {
         this.workspaceGitSubscriptions.get(normalizedCwd)?.();
         this.workspaceGitSubscriptions.delete(normalizedCwd);
     }
-    workspaceGitDescriptorFingerprint(workspace) {
+    workspaceGitDescriptorStateKey(workspace) {
         if (!workspace) {
-            return WORKSPACE_GIT_WATCH_REMOVED_FINGERPRINT;
+            return WORKSPACE_GIT_WATCH_REMOVED_STATE_KEY;
         }
         return JSON.stringify([
             workspace.name,
@@ -3119,34 +3366,30 @@ export class Session {
         if (!target) {
             return false;
         }
-        const nextFingerprint = this.workspaceGitDescriptorFingerprint(workspace);
-        if (target.latestFingerprint === nextFingerprint) {
+        const nextStateKey = this.workspaceGitDescriptorStateKey(workspace);
+        if (target.latestDescriptorStateKey === nextStateKey) {
             return true;
         }
-        target.latestFingerprint = nextFingerprint;
+        target.latestDescriptorStateKey = nextStateKey;
         return false;
     }
-    rememberWorkspaceGitWatchFingerprint(workspaceId, workspace) {
+    rememberWorkspaceGitDescriptorState(workspaceId, workspace) {
         const target = this.workspaceGitWatchTargets.get(workspaceId);
         if (!target) {
             return;
         }
-        target.latestFingerprint = this.workspaceGitDescriptorFingerprint(workspace);
+        target.latestDescriptorStateKey = this.workspaceGitDescriptorStateKey(workspace);
         target.lastBranchName = workspace?.name ?? null;
     }
-    async primeWorkspaceGitWatchFingerprints(workspaces) {
+    syncWorkspaceGitObservers(workspaces) {
         for (const workspace of workspaces) {
-            const persistedWorkspace = await this.workspaceRegistry.get(workspace.id);
-            if (!persistedWorkspace) {
-                continue;
-            }
-            await this.syncWorkspaceGitWatchTarget(persistedWorkspace.cwd, {
+            this.syncWorkspaceGitObserver(workspace.workspaceDirectory, {
                 isGit: workspace.projectKind === "git",
             });
-            this.rememberWorkspaceGitWatchFingerprint(persistedWorkspace.cwd, workspace);
+            this.rememberWorkspaceGitDescriptorState(workspace.workspaceDirectory, workspace);
         }
     }
-    async syncWorkspaceGitWatchTarget(cwd, options) {
+    syncWorkspaceGitObserver(cwd, options) {
         const normalizedCwd = normalizePersistedWorkspaceId(cwd);
         if (!options.isGit) {
             this.removeWorkspaceGitSubscription(normalizedCwd);
@@ -3155,7 +3398,7 @@ export class Session {
         if (this.workspaceGitSubscriptions.has(normalizedCwd)) {
             return;
         }
-        const subscription = await this.workspaceGitService.subscribe({ cwd: normalizedCwd }, (snapshot) => {
+        const subscription = this.workspaceGitService.registerWorkspace({ cwd: normalizedCwd }, (snapshot) => {
             void this.emitWorkspaceUpdateForCwd(normalizedCwd);
             this.emitCheckoutStatusUpdate(normalizedCwd, snapshot);
         });
@@ -3236,6 +3479,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,
@@ -3326,7 +3570,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({
@@ -3344,7 +3590,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({
@@ -3572,7 +3820,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",
@@ -3916,9 +4164,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
@@ -4099,25 +4350,7 @@ export class Session {
         if (!payload.values || typeof payload.values !== "object") {
             throw new SessionRequestError("invalid_cursor", "Invalid fetch_agents 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_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 });
-        }
+        const cursorSort = parseFetchAgentsCursorSort(payload.sort);
         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");
@@ -4149,18 +4382,49 @@ 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
@@ -4170,6 +4434,7 @@ export class Session {
         const sort = this.normalizeFetchAgentsSort(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) {
@@ -4196,31 +4461,12 @@ export class Session {
             candidates = candidates.filter((agent) => this.compareAgentWithCursor(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
@@ -4281,6 +4527,11 @@ export class Session {
                     resolveHealth: this.resolveScriptHealth ?? undefined,
                 })
                 : [],
+            ...(resolvedProjectRecord
+                ? {
+                    project: await this.buildProjectPlacementForWorkspace(workspace, resolvedProjectRecord),
+                }
+                : {}),
         };
     }
     buildWorkspaceGitRuntimePayload(snapshot) {
@@ -4367,16 +4618,14 @@ export class Session {
         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,
-            }));
+        const includedWorkspaces = activeRecords.filter((workspace) => !workspaceIds || workspaceIds.has(workspace.workspaceId));
+        const workspaceDescriptors = await Promise.all(includedWorkspaces.map((workspace) => this.buildWorkspaceDescriptor({
+            workspace,
+            projectRecord: activeProjects.get(workspace.projectId) ?? null,
+            includeGitData: options.includeGitData,
+        })));
+        for (let i = 0; i < includedWorkspaces.length; i += 1) {
+            descriptorsByWorkspaceId.set(includedWorkspaces[i].workspaceId, workspaceDescriptors[i]);
         }
         for (const agent of agents) {
             if (agent.archivedAt) {
@@ -4406,8 +4655,13 @@ export class Session {
         if (exact) {
             return exact.workspaceId;
         }
+        const userHome = homedir();
         let bestMatch = null;
         for (const workspace of workspaces) {
+            if (workspace.cwd === userHome)
+                continue;
+            if (workspace.archivedAt)
+                continue;
             const prefix = workspace.cwd.endsWith(sep) ? workspace.cwd : `${workspace.cwd}${sep}`;
             if (!normalizedCwd.startsWith(prefix)) {
                 continue;
@@ -4492,25 +4746,7 @@ export class Session {
         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 });
-        }
+        const cursorSort = parseFetchWorkspacesCursorSort(payload.sort);
         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");
@@ -4637,41 +4873,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)) {
@@ -4753,7 +5069,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);
@@ -4769,7 +5085,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)) {
@@ -4808,7 +5124,7 @@ export class Session {
                     this.onBranchChanged(workspaceId, watchTarget.lastBranchName, newBranchName);
                 }
             }
-            this.rememberWorkspaceGitWatchFingerprint(workspaceId, nextWorkspace);
+            this.rememberWorkspaceGitDescriptorState(workspaceId, nextWorkspace);
             if (!nextWorkspace) {
                 subscription.lastEmittedByWorkspaceId.delete(workspaceId);
                 this.bufferOrEmitWorkspaceUpdate(subscription, {
@@ -4848,11 +5164,7 @@ export class Session {
     }
     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 = {
@@ -4928,11 +5240,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,
@@ -4951,7 +5259,7 @@ export class Session {
                 };
             }
             const payload = await this.listFetchWorkspacesEntries(request);
-            await this.primeWorkspaceGitWatchFingerprints(payload.entries);
+            this.syncWorkspaceGitObservers(payload.entries);
             this.sessionLogger.debug({
                 requestId: request.requestId,
                 subscriptionId,
@@ -5001,8 +5309,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: {
@@ -5011,6 +5320,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";
@@ -5278,6 +5596,55 @@ export class Session {
             payload: { requestId, agent, project, error: null },
         });
     }
+    loadProjectedTimelineWindow(params) {
+        const { agentId, direction, cursor, requestedLimit, provider } = params;
+        let timeline = params.timeline;
+        const projectedLimit = Math.max(1, Math.floor(requestedLimit));
+        let fetchLimit = projectedLimit;
+        let projectedWindow = selectTimelineWindowByProjectedLimit({
+            rows: timeline.rows,
+            provider,
+            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,
+                provider,
+                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";
@@ -5313,51 +5680,20 @@ 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,
+                    provider: snapshot.provider,
+                    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(projectedResult.selectedRows, snapshot.provider, 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;
                 }
             }
@@ -5465,18 +5801,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;
@@ -5495,18 +5826,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),
                 },
             });
         }
@@ -5544,11 +5870,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",
@@ -5572,11 +5903,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",
@@ -5587,11 +5923,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({
@@ -5608,7 +5940,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",
@@ -5624,44 +5956,7 @@ export class Session {
     /**
      * 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");
+    async ensureAudioBufferForFormat(chunkFormat, isPCMChunk) {
         if (!this.audioBuffer) {
             this.audioBuffer = {
                 chunks: [],
@@ -5669,8 +5964,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,
@@ -5686,19 +5981,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;
         }
@@ -6265,7 +6602,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,
@@ -6615,11 +6952,7 @@ export class Session {
         }
         this.emitTerminalsChangedSnapshot({
             cwd: event.cwd,
-            terminals: this.filterStandaloneTerminals(event.terminals).map((terminal) => ({
-                id: terminal.id,
-                name: terminal.name,
-                ...(terminal.title ? { title: terminal.title } : {}),
-            })),
+            terminals: this.filterStandaloneTerminals(event.terminals).map((terminal) => Object.assign({ id: terminal.id, name: terminal.name }, terminal.title ? { title: terminal.title } : {})),
         });
     }
     handleSubscribeTerminalsRequest(msg) {
@@ -7041,7 +7374,7 @@ export class Session {
         return true;
     }
     disposeTerminalSubscriptions() {
-        for (const terminalId of [...this.terminalIdToSlot.keys()]) {
+        for (const terminalId of Array.from(this.terminalIdToSlot.keys())) {
             this.detachTerminalStream(terminalId, { emitExit: false });
         }
     }