@getpaseo/server 0.1.30 → 0.1.33

package/dist/src/server/session.js

@@ -1,56 +1,58 @@
-import { v4 as uuidv4 } from 'uuid';
-import { watch } from 'node:fs';
-import { stat } from 'fs/promises';
-import { exec } from 'child_process';
-import { promisify } from 'util';
-import { join, resolve, sep } from 'path';
-import { homedir } from 'node:os';
-import { z } from 'zod';
-import { serializeAgentStreamEvent, } from './messages.js';
-import { BinaryMuxChannel, TerminalBinaryFlags, TerminalBinaryMessageType, } from '../shared/binary-mux.js';
-import { TTSManager } from './agent/tts-manager.js';
-import { STTManager } from './agent/stt-manager.js';
-import { maybePersistTtsDebugAudio } from './agent/tts-debug.js';
-import { isPaseoDictationDebugEnabled } from './agent/recordings-debug.js';
-import { DictationStreamManager, } from './dictation/dictation-stream-manager.js';
-import { createVoiceTurnController, } from './voice/voice-turn-controller.js';
-import { buildConfigOverrides, buildSessionConfig, extractTimestamps } from './persistence-hooks.js';
-import { experimental_createMCPClient } from 'ai';
-import { buildProviderRegistry } from './agent/provider-registry.js';
-import { scheduleAgentMetadataGeneration } from './agent/agent-metadata-generator.js';
-import { resolveEffectiveThinkingOptionId, toAgentPayload } from './agent/agent-projections.js';
-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 { isValidAgentProvider, AGENT_PROVIDER_IDS } from './agent/provider-manifest.js';
-import { buildProjectPlacementForCwd, deriveProjectKind, deriveProjectRootPath, deriveWorkspaceDisplayName, deriveWorkspaceKind, normalizeWorkspaceId as normalizePersistedWorkspaceId, } from './workspace-registry-model.js';
-import { createPersistedProjectRecord, createPersistedWorkspaceRecord, } from './workspace-registry.js';
-import { buildVoiceAgentMcpServerConfig, buildVoiceModeSystemPrompt, stripVoiceModeSystemPrompt, } from './voice-config.js';
-import { isVoicePermissionAllowed } from './voice-permission-policy.js';
-import { listDirectoryEntries, readExplorerFile, getDownloadableFileInfo, } from './file-explorer/service.js';
-import { slugify, validateBranchSlug, listPaseoWorktrees, deletePaseoWorktree, isPaseoOwnedWorktreeCwd, resolvePaseoWorktreeRootForCwd, } from '../utils/worktree.js';
-import { createAgentWorktree, runAsyncWorktreeBootstrap } from './worktree-bootstrap.js';
-import { getCheckoutDiff, getCheckoutShortstat, getCheckoutStatus, listBranchSuggestions, NotGitRepoError, MergeConflictError, MergeFromBaseConflictError, commitChanges, mergeToBase, mergeFromBase, pushCurrentBranch, createPullRequest, getPullRequestStatus, } from '../utils/checkout-git.js';
-import { getProjectIcon } from '../utils/project-icon.js';
-import { expandTilde } from '../utils/path.js';
-import { searchHomeDirectories, searchWorkspaceEntries } from '../utils/directory-suggestions.js';
-import { ensureLocalSpeechModels, getLocalSpeechModelDir, listLocalSpeechModels, } from './speech/providers/local/models.js';
-import { toResolver } from './speech/provider-resolver.js';
-import { resolveClientMessageId } from './client-message-id.js';
+import { v4 as uuidv4 } from "uuid";
+import { watch } from "node:fs";
+import { readFile, stat } from "fs/promises";
+import { exec } from "child_process";
+import { promisify } from "util";
+import { join, resolve, sep } from "path";
+import { homedir } from "node:os";
+import { z } from "zod";
+import { serializeAgentStreamEvent, } from "./messages.js";
+import { TerminalStreamOpcode, encodeTerminalSnapshotPayload, encodeTerminalStreamFrame, decodeTerminalResizePayload, } from "../shared/terminal-stream-protocol.js";
+import { TTSManager } from "./agent/tts-manager.js";
+import { STTManager } from "./agent/stt-manager.js";
+import { maybePersistTtsDebugAudio } from "./agent/tts-debug.js";
+import { isPaseoDictationDebugEnabled } from "./agent/recordings-debug.js";
+import { DictationStreamManager, } from "./dictation/dictation-stream-manager.js";
+import { createVoiceTurnController, } from "./voice/voice-turn-controller.js";
+import { buildConfigOverrides, buildSessionConfig, extractTimestamps, } from "./persistence-hooks.js";
+import { experimental_createMCPClient } from "ai";
+import { buildProviderRegistry } from "./agent/provider-registry.js";
+import { scheduleAgentMetadataGeneration } from "./agent/agent-metadata-generator.js";
+import { resolveEffectiveThinkingOptionId, toAgentPayload } from "./agent/agent-projections.js";
+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 { isValidAgentProvider, AGENT_PROVIDER_IDS } from "./agent/provider-manifest.js";
+import { buildProjectPlacementForCwd, detectStaleWorkspaces, deriveProjectKind, deriveProjectRootPath, deriveWorkspaceDisplayName, deriveWorkspaceKind, normalizeWorkspaceId as normalizePersistedWorkspaceId, } from "./workspace-registry-model.js";
+import { createPersistedProjectRecord, createPersistedWorkspaceRecord, } from "./workspace-registry.js";
+import { buildVoiceAgentMcpServerConfig, buildVoiceModeSystemPrompt, stripVoiceModeSystemPrompt, } from "./voice-config.js";
+import { isVoicePermissionAllowed } from "./voice-permission-policy.js";
+import { listDirectoryEntries, readExplorerFile, getDownloadableFileInfo, } from "./file-explorer/service.js";
+import { computeWorktreePath, getWorktreeSetupCommands, resolveWorktreeRuntimeEnv, slugify, validateBranchSlug, listPaseoWorktrees, deletePaseoWorktree, isPaseoOwnedWorktreeCwd, resolvePaseoWorktreeRootForCwd, } from "../utils/worktree.js";
+import { createAgentWorktree, runAsyncWorktreeBootstrap } from "./worktree-bootstrap.js";
+import { getCheckoutDiff, getCheckoutShortstat, getCheckoutStatus, getCheckoutStatusLite, listBranchSuggestions, NotGitRepoError, MergeConflictError, MergeFromBaseConflictError, commitChanges, mergeToBase, mergeFromBase, pushCurrentBranch, createPullRequest, getPullRequestStatus, resolveRepositoryDefaultBranch, } from "../utils/checkout-git.js";
+import { getProjectIcon } from "../utils/project-icon.js";
+import { expandTilde } from "../utils/path.js";
+import { searchHomeDirectories, searchWorkspaceEntries } from "../utils/directory-suggestions.js";
+import { ensureLocalSpeechModels, getLocalSpeechModelDir, listLocalSpeechModels, } from "./speech/providers/local/models.js";
+import { toResolver } from "./speech/provider-resolver.js";
+import { resolveClientMessageId } from "./client-message-id.js";
 const execAsync = promisify(exec);
 const MAX_INITIAL_AGENT_TITLE_CHARS = Math.min(60, MAX_EXPLICIT_AGENT_TITLE_CHARS);
 const READ_ONLY_GIT_ENV = {
     ...process.env,
-    GIT_OPTIONAL_LOCKS: '0',
+    GIT_OPTIONAL_LOCKS: "0",
 };
 const pendingAgentInitializations = new Map();
 const DEFAULT_AGENT_PROVIDER = AGENT_PROVIDER_IDS[0];
 const CHECKOUT_DIFF_WATCH_DEBOUNCE_MS = 150;
 const CHECKOUT_DIFF_FALLBACK_REFRESH_MS = 5000;
-const TERMINAL_STREAM_WINDOW_BYTES = 256 * 1024;
-const TERMINAL_STREAM_MAX_PENDING_BYTES = 2 * 1024 * 1024;
-const TERMINAL_STREAM_MAX_PENDING_CHUNKS = 2048;
+const WORKSPACE_GIT_WATCH_DEBOUNCE_MS = 500;
+const WORKSPACE_GIT_WATCH_REMOVED_FINGERPRINT = "__removed__";
+const TERMINAL_STREAM_HIGH_WATER_BYTES = 256 * 1024;
+const TERMINAL_STREAM_LOW_WATER_BYTES = 16 * 1024;
+const MAX_TERMINAL_STREAM_SLOTS = 256;
 function deriveInitialAgentTitle(prompt) {
     const firstContentLine = prompt
         .split(/\r?\n/)
@@ -59,7 +61,7 @@ function deriveInitialAgentTitle(prompt) {
     if (!firstContentLine) {
         return null;
     }
-    const normalized = firstContentLine.replace(/\s+/g, ' ').trim();
+    const normalized = firstContentLine.replace(/\s+/g, " ").trim();
     if (!normalized) {
         return null;
     }
@@ -67,7 +69,7 @@ function deriveInitialAgentTitle(prompt) {
     return clamped.length > 0 ? clamped : null;
 }
 export function resolveCreateAgentTitles(options) {
-    const explicitTitle = typeof options.configTitle === 'string' && options.configTitle.trim().length > 0
+    const explicitTitle = typeof options.configTitle === "string" && options.configTitle.trim().length > 0
         ? options.configTitle.trim()
         : null;
     const trimmedPrompt = options.initialPrompt?.trim();
@@ -81,7 +83,7 @@ class SessionRequestError extends Error {
     constructor(code, message) {
         super(message);
         this.code = code;
-        this.name = 'SessionRequestError';
+        this.name = "SessionRequestError";
     }
 }
 const PCM_SAMPLE_RATE = 16000;
@@ -92,12 +94,12 @@ const MIN_STREAMING_SEGMENT_DURATION_MS = 1000;
 const MIN_STREAMING_SEGMENT_BYTES = Math.round(PCM_BYTES_PER_MS * MIN_STREAMING_SEGMENT_DURATION_MS);
 const SAFE_GIT_REF_PATTERN = /^[A-Za-z0-9._\/-]+$/;
 const AgentIdSchema = z.string().uuid();
-const VOICE_MCP_SERVER_NAME = 'paseo_voice';
+const VOICE_MCP_SERVER_NAME = "paseo_voice";
 const VOICE_INTERRUPT_CONFIRMATION_MS = 500;
 class VoiceFeatureUnavailableError extends Error {
     constructor(context) {
         super(context.message);
-        this.name = 'VoiceFeatureUnavailableError';
+        this.name = "VoiceFeatureUnavailableError";
         this.reasonCode = context.reasonCode;
         this.retryable = context.retryable;
         this.missingModelIds = [...context.missingModelIds];
@@ -108,10 +110,10 @@ function convertPCMToWavBuffer(pcmBuffer, sampleRate, channels, bitsPerSample) {
     const wavBuffer = Buffer.alloc(headerSize + pcmBuffer.length);
     const byteRate = (sampleRate * channels * bitsPerSample) / 8;
     const blockAlign = (channels * bitsPerSample) / 8;
-    wavBuffer.write('RIFF', 0);
+    wavBuffer.write("RIFF", 0);
     wavBuffer.writeUInt32LE(36 + pcmBuffer.length, 4);
-    wavBuffer.write('WAVE', 8);
-    wavBuffer.write('fmt ', 12);
+    wavBuffer.write("WAVE", 8);
+    wavBuffer.write("fmt ", 12);
     wavBuffer.writeUInt32LE(16, 16);
     wavBuffer.writeUInt16LE(1, 20);
     wavBuffer.writeUInt16LE(channels, 22);
@@ -119,7 +121,7 @@ function convertPCMToWavBuffer(pcmBuffer, sampleRate, channels, bitsPerSample) {
     wavBuffer.writeUInt32LE(byteRate, 28);
     wavBuffer.writeUInt16LE(blockAlign, 32);
     wavBuffer.writeUInt16LE(bitsPerSample, 34);
-    wavBuffer.write('data', 36);
+    wavBuffer.write("data", 36);
     wavBuffer.writeUInt32LE(pcmBuffer.length, 40);
     pcmBuffer.copy(wavBuffer, 44);
     return wavBuffer;
@@ -128,7 +130,7 @@ function coerceAgentProvider(logger, value, agentId) {
     if (isValidAgentProvider(value)) {
         return value;
     }
-    logger.warn({ value, agentId, defaultProvider: DEFAULT_AGENT_PROVIDER }, `Unknown provider '${value}' for agent ${agentId ?? 'unknown'}; defaulting to '${DEFAULT_AGENT_PROVIDER}'`);
+    logger.warn({ value, agentId, defaultProvider: DEFAULT_AGENT_PROVIDER }, `Unknown provider '${value}' for agent ${agentId ?? "unknown"}; defaulting to '${DEFAULT_AGENT_PROVIDER}'`);
     return DEFAULT_AGENT_PROVIDER;
 }
 function toAgentPersistenceHandle(logger, handle) {
@@ -141,7 +143,7 @@ function toAgentPersistenceHandle(logger, handle) {
         return null;
     }
     if (!handle.sessionId) {
-        logger.warn('Ignoring persistence handle missing sessionId');
+        logger.warn("Ignoring persistence handle missing sessionId");
         return null;
     }
     return {
@@ -158,7 +160,7 @@ function toAgentPersistenceHandle(logger, handle) {
  */
 export class Session {
     constructor(options) {
-        this.processingPhase = 'idle';
+        this.processingPhase = "idle";
         // Voice mode state
         this.isVoiceMode = false;
         this.speechInProgress = false;
@@ -184,13 +186,13 @@ export class Session {
         this.MOBILE_BACKGROUND_STREAM_GRACE_MS = 60000;
         this.subscribedTerminalDirectories = new Set();
         this.unsubscribeTerminalsChanged = null;
-        this.terminalSubscriptions = new Map();
         this.terminalExitSubscriptions = new Map();
-        this.terminalStreams = new Map();
-        this.terminalStreamByTerminalId = new Map();
-        this.nextTerminalStreamId = 1;
+        this.activeTerminalStreams = new Map();
+        this.terminalIdToSlot = new Map();
+        this.nextTerminalSlot = 0;
         this.checkoutDiffSubscriptions = new Map();
         this.checkoutDiffTargets = new Map();
+        this.workspaceGitWatchTargets = new Map();
         this.voiceModeAgentId = null;
         this.voiceModeBaseConfig = null;
         this.workspaceStatePriority = {
@@ -200,11 +202,12 @@ export class Session {
             attention: 3,
             done: 4,
         };
-        const { clientId, onMessage, onBinaryMessage, onLifecycleIntent, logger, downloadTokenStore, pushTokenStore, paseoHome, agentManager, agentStorage, projectRegistry, workspaceRegistry, createAgentMcpTransport, stt, tts, terminalManager, voice, voiceBridge, dictation, agentProviderRuntimeSettings, } = options;
+        const { clientId, onMessage, onBinaryMessage, getBinaryBufferedAmount, onLifecycleIntent, logger, downloadTokenStore, pushTokenStore, paseoHome, agentManager, agentStorage, projectRegistry, workspaceRegistry, createAgentMcpTransport, stt, tts, terminalManager, voice, voiceBridge, dictation, agentProviderRuntimeSettings, } = options;
         this.clientId = clientId;
         this.sessionId = uuidv4();
         this.onMessage = onMessage;
         this.onBinaryMessage = onBinaryMessage ?? null;
+        this.getBinaryBufferedAmount = getBinaryBufferedAmount ?? null;
         this.onLifecycleIntent = onLifecycleIntent ?? null;
         this.downloadTokenStore = downloadTokenStore;
         this.pushTokenStore = pushTokenStore;
@@ -224,11 +227,11 @@ export class Session {
         this.localSpeechModelsDir =
             configuredModelsDir && configuredModelsDir.length > 0
                 ? configuredModelsDir
-                : join(this.paseoHome, 'models', 'local-speech');
+                : join(this.paseoHome, "models", "local-speech");
         this.defaultLocalSpeechModelIds =
             dictation?.localModels?.defaultModelIds && dictation.localModels.defaultModelIds.length > 0
                 ? [...new Set(dictation.localModels.defaultModelIds)]
-                : ['parakeet-tdt-0.6b-v2-int8', 'kokoro-en-v0_19'];
+                : ["parakeet-tdt-0.6b-v2-int8", "kokoro-en-v0_19"];
         this.registerVoiceSpeakHandler = voiceBridge?.registerVoiceSpeakHandler;
         this.unregisterVoiceSpeakHandler = voiceBridge?.unregisterVoiceSpeakHandler;
         this.registerVoiceCallerContext = voiceBridge?.registerVoiceCallerContext;
@@ -239,7 +242,7 @@ export class Session {
         this.agentProviderRuntimeSettings = agentProviderRuntimeSettings;
         this.abortController = new AbortController();
         this.sessionLogger = logger.child({
-            module: 'session',
+            module: "session",
             clientId: this.clientId,
             sessionId: this.sessionId,
         });
@@ -259,7 +262,7 @@ export class Session {
         // Initialize agent MCP client asynchronously
         void this.initializeAgentMcp();
         this.subscribeToAgentEvents();
-        this.sessionLogger.trace('Session created');
+        this.sessionLogger.trace("Session created");
     }
     /**
      * Get the client's current activity state
@@ -282,8 +285,7 @@ export class Session {
             checkoutDiffWatcherCount,
             checkoutDiffFallbackRefreshTargetCount,
             terminalDirectorySubscriptionCount: this.subscribedTerminalDirectories.size,
-            terminalSubscriptionCount: this.terminalSubscriptions.size,
-            terminalStreamCount: this.terminalStreams.size,
+            terminalSubscriptionCount: this.activeTerminalStreams.size,
         };
     }
     /**
@@ -296,16 +298,16 @@ export class Session {
      * Normalize a user prompt (with optional image metadata) for AgentManager
      */
     buildAgentPrompt(text, images) {
-        const normalized = text?.trim() ?? '';
+        const normalized = text?.trim() ?? "";
         if (!images || images.length === 0) {
             return normalized;
         }
         const blocks = [];
         if (normalized.length > 0) {
-            blocks.push({ type: 'text', text: normalized });
+            blocks.push({ type: "text", text: normalized });
         }
         for (const image of images) {
-            blocks.push({ type: 'image', data: image.data, mimeType: image.mimeType });
+            blocks.push({ type: "image", data: image.data, mimeType: image.mimeType });
         }
         return blocks;
     }
@@ -316,20 +318,20 @@ export class Session {
     async interruptAgentIfRunning(agentId) {
         const snapshot = this.agentManager.getAgent(agentId);
         if (!snapshot) {
-            this.sessionLogger.trace({ agentId }, 'interruptAgentIfRunning: agent not found');
+            this.sessionLogger.trace({ agentId }, "interruptAgentIfRunning: agent not found");
             throw new Error(`Agent ${agentId} not found`);
         }
-        if (snapshot.lifecycle !== 'running' && !snapshot.pendingRun) {
-            this.sessionLogger.trace({ agentId, lifecycle: snapshot.lifecycle, pendingRun: Boolean(snapshot.pendingRun) }, 'interruptAgentIfRunning: skipping because agent is not running');
+        if (snapshot.lifecycle !== "running" && !snapshot.pendingRun) {
+            this.sessionLogger.trace({ agentId, lifecycle: snapshot.lifecycle, pendingRun: Boolean(snapshot.pendingRun) }, "interruptAgentIfRunning: skipping because agent is not running");
             return;
         }
-        this.sessionLogger.debug({ agentId, lifecycle: snapshot.lifecycle, pendingRun: Boolean(snapshot.pendingRun) }, 'interruptAgentIfRunning: interrupting');
+        this.sessionLogger.debug({ agentId, lifecycle: snapshot.lifecycle, pendingRun: Boolean(snapshot.pendingRun) }, "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');
+            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');
+                this.sessionLogger.warn({ agentId }, "interruptAgentIfRunning: reported running but no active run was cancelled");
             }
         }
         catch (error) {
@@ -344,7 +346,7 @@ export class Session {
         if (!snapshot) {
             return false;
         }
-        return snapshot.lifecycle === 'running' || Boolean(snapshot.pendingRun);
+        return snapshot.lifecycle === "running" || Boolean(snapshot.pendingRun);
     }
     /**
      * Start streaming an agent run and forward results via the websocket broadcast
@@ -352,21 +354,25 @@ export class Session {
     startAgentStream(agentId, prompt, runOptions) {
         this.sessionLogger.trace({
             agentId,
-            promptType: typeof prompt === 'string' ? 'string' : 'structured',
+            promptType: typeof prompt === "string" ? "string" : "structured",
             hasRunOptions: Boolean(runOptions),
-        }, 'startAgentStream: requested');
+        }, "startAgentStream: requested");
         let iterator;
         try {
             const snapshot = this.agentManager.getAgent(agentId);
-            const shouldReplace = Boolean(snapshot && (snapshot.lifecycle === 'running' || snapshot.pendingRun));
+            const shouldReplace = Boolean(snapshot && (snapshot.lifecycle === "running" || snapshot.pendingRun));
             iterator = shouldReplace
                 ? this.agentManager.replaceAgentRun(agentId, prompt, runOptions)
                 : this.agentManager.streamAgent(agentId, prompt, runOptions);
-            this.sessionLogger.trace({ agentId, shouldReplace }, 'startAgentStream: agent iterator returned');
+            this.sessionLogger.trace({ agentId, shouldReplace }, "startAgentStream: agent iterator returned");
         }
         catch (error) {
-            this.handleAgentRunError(agentId, error, 'Failed to start agent run');
-            const message = error instanceof Error ? error.message : typeof error === 'string' ? error : 'Unknown 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 };
         }
         void (async () => {
@@ -374,24 +380,24 @@ export class Session {
                 for await (const _ of iterator) {
                     // Events are forwarded via the session's AgentManager subscription.
                 }
-                this.sessionLogger.trace({ agentId }, 'startAgentStream: iterator drained');
+                this.sessionLogger.trace({ agentId }, "startAgentStream: iterator drained");
             }
             catch (error) {
-                this.sessionLogger.trace({ agentId, err: error }, 'startAgentStream: iterator threw');
-                this.handleAgentRunError(agentId, error, 'Agent stream failed');
+                this.sessionLogger.trace({ agentId, err: error }, "startAgentStream: iterator threw");
+                this.handleAgentRunError(agentId, error, "Agent stream failed");
             }
         })();
         return { ok: true };
     }
     handleAgentRunError(agentId, error, context) {
-        const message = error instanceof Error ? error.message : typeof error === 'string' ? error : 'Unknown error';
+        const message = error instanceof Error ? error.message : typeof error === "string" ? error : "Unknown error";
         this.sessionLogger.error({ err: error, agentId, context }, `${context} for agent ${agentId}`);
         this.emit({
-            type: 'activity_log',
+            type: "activity_log",
             payload: {
                 id: uuidv4(),
                 timestamp: new Date(),
-                type: 'error',
+                type: "error",
                 content: `${context}: ${message}`,
             },
         });
@@ -411,7 +417,7 @@ export class Session {
             this.sessionLogger.trace({ agentToolCount }, `Agent MCP initialized with ${agentToolCount} tools`);
         }
         catch (error) {
-            this.sessionLogger.error({ err: error }, 'Failed to initialize Agent MCP');
+            this.sessionLogger.error({ err: error }, "Failed to initialize Agent MCP");
         }
     }
     /**
@@ -422,32 +428,32 @@ export class Session {
             this.unsubscribeAgentEvents();
         }
         this.unsubscribeAgentEvents = this.agentManager.subscribe((event) => {
-            if (event.type === 'agent_state') {
+            if (event.type === "agent_state") {
                 void this.forwardAgentUpdate(event.agent);
                 return;
             }
             if (this.isVoiceMode &&
                 this.voiceModeAgentId === event.agentId &&
-                event.event.type === 'permission_requested' &&
+                event.event.type === "permission_requested" &&
                 isVoicePermissionAllowed(event.event.request)) {
                 const requestId = event.event.request.id;
                 void this.agentManager
                     .respondToPermission(event.agentId, requestId, {
-                    behavior: 'allow',
+                    behavior: "allow",
                 })
                     .catch((error) => {
                     this.sessionLogger.warn({
                         err: error,
                         agentId: event.agentId,
                         requestId,
-                    }, 'Failed to auto-allow speak tool permission in voice mode');
+                    }, "Failed to auto-allow speak tool permission in voice mode");
                 });
             }
             // Reduce bandwidth/CPU on mobile: only forward high-frequency agent stream events
             // for the focused agent, with a short grace window while backgrounded.
             // History catch-up is handled via pull-based `fetch_agent_timeline_request`.
             const activity = this.clientActivity;
-            if (activity?.deviceType === 'mobile') {
+            if (activity?.deviceType === "mobile") {
                 if (!activity.focusedAgentId) {
                     return;
                 }
@@ -469,25 +475,25 @@ export class Session {
                 agentId: event.agentId,
                 event: serializedEvent,
                 timestamp: new Date().toISOString(),
-                ...(typeof event.seq === 'number' ? { seq: event.seq } : {}),
-                ...(typeof event.epoch === 'string' ? { epoch: event.epoch } : {}),
+                ...(typeof event.seq === "number" ? { seq: event.seq } : {}),
+                ...(typeof event.epoch === "string" ? { epoch: event.epoch } : {}),
             };
             this.emit({
-                type: 'agent_stream',
+                type: "agent_stream",
                 payload,
             });
-            if (event.event.type === 'permission_requested') {
+            if (event.event.type === "permission_requested") {
                 this.emit({
-                    type: 'agent_permission_request',
+                    type: "agent_permission_request",
                     payload: {
                         agentId: event.agentId,
                         request: event.event.request,
                     },
                 });
             }
-            else if (event.event.type === 'permission_resolved') {
+            else if (event.event.type === "permission_resolved") {
                 this.emit({
-                    type: 'agent_permission_resolved',
+                    type: "agent_permission_resolved",
                     payload: {
                         agentId: event.agentId,
                         requestId: event.event.requestId,
@@ -522,13 +528,13 @@ export class Session {
             ? {
                 provider: coerceAgentProvider(this.sessionLogger, record.runtimeInfo.provider, record.id),
                 sessionId: record.runtimeInfo.sessionId,
-                ...(Object.prototype.hasOwnProperty.call(record.runtimeInfo, 'model')
+                ...(Object.prototype.hasOwnProperty.call(record.runtimeInfo, "model")
                     ? { model: record.runtimeInfo.model ?? null }
                     : {}),
-                ...(Object.prototype.hasOwnProperty.call(record.runtimeInfo, 'thinkingOptionId')
+                ...(Object.prototype.hasOwnProperty.call(record.runtimeInfo, "thinkingOptionId")
                     ? { thinkingOptionId: record.runtimeInfo.thinkingOptionId ?? null }
                     : {}),
-                ...(Object.prototype.hasOwnProperty.call(record.runtimeInfo, 'modeId')
+                ...(Object.prototype.hasOwnProperty.call(record.runtimeInfo, "modeId")
                     ? { modeId: record.runtimeInfo.modeId ?? null }
                     : {}),
                 ...(record.runtimeInfo.extra ? { extra: record.runtimeInfo.extra } : {}),
@@ -582,12 +588,12 @@ export class Session {
             let snapshot;
             if (handle) {
                 snapshot = await this.agentManager.resumeAgentFromPersistence(handle, buildConfigOverrides(record), agentId, extractTimestamps(record));
-                this.sessionLogger.info({ agentId, provider: record.provider }, 'Agent resumed from persistence');
+                this.sessionLogger.info({ agentId, provider: record.provider }, "Agent resumed from persistence");
             }
             else {
                 const config = buildSessionConfig(record);
                 snapshot = await this.agentManager.createAgent(config, agentId, { labels: record.labels });
-                this.sessionLogger.info({ agentId, provider: record.provider }, 'Agent created from stored config');
+                this.sessionLogger.info({ agentId, provider: record.provider }, "Agent created from stored config");
             }
             await this.agentManager.hydrateTimelineFromProvider(agentId);
             return this.agentManager.getAgent(agentId) ?? snapshot;
@@ -634,7 +640,7 @@ export class Session {
                 return false;
             }
         }
-        if (typeof filter?.requiresAttention === 'boolean') {
+        if (typeof filter?.requiresAttention === "boolean") {
             const requiresAttention = agent.requiresAttention ?? false;
             if (requiresAttention !== filter.requiresAttention) {
                 return false;
@@ -649,7 +655,7 @@ export class Session {
         return true;
     }
     getAgentUpdateTargetId(update) {
-        return update.kind === 'remove' ? update.agentId : update.agent.id;
+        return update.kind === "remove" ? update.agentId : update.agent.id;
     }
     bufferOrEmitAgentUpdate(subscription, payload) {
         if (subscription.isBootstrapping) {
@@ -657,7 +663,7 @@ export class Session {
             return;
         }
         this.emit({
-            type: 'agent_update',
+            type: "agent_update",
             payload,
         });
     }
@@ -670,9 +676,9 @@ export class Session {
         const pending = Array.from(subscription.pendingUpdatesByAgentId.values());
         subscription.pendingUpdatesByAgentId.clear();
         for (const payload of pending) {
-            if (payload.kind === 'upsert') {
+            if (payload.kind === "upsert") {
                 const snapshotUpdatedAt = options?.snapshotUpdatedAtByAgentId?.get(payload.agent.id);
-                if (typeof snapshotUpdatedAt === 'number') {
+                if (typeof snapshotUpdatedAt === "number") {
                     const updateUpdatedAt = Date.parse(payload.agent.updatedAt);
                     if (!Number.isNaN(updateUpdatedAt) && updateUpdatedAt <= snapshotUpdatedAt) {
                         continue;
@@ -680,7 +686,7 @@ export class Session {
                 }
             }
             this.emit({
-                type: 'agent_update',
+                type: "agent_update",
                 payload,
             });
         }
@@ -730,6 +736,9 @@ export class Session {
         const normalizedWorkspaceId = normalizePersistedWorkspaceId(workspaceId);
         const existing = await this.workspaceRegistry.get(normalizedWorkspaceId);
         const placement = await this.buildProjectPlacement(normalizedWorkspaceId);
+        await this.syncWorkspaceGitWatchTarget(normalizedWorkspaceId, {
+            isGit: placement.checkout.isGit,
+        });
         const now = new Date().toISOString();
         const nextProjectCreatedAt = existing?.createdAt ?? now;
         const nextWorkspaceCreatedAt = existing?.createdAt ?? now;
@@ -764,9 +773,7 @@ export class Session {
         }
         await this.projectRegistry.upsert(nextProjectRecord);
         await this.workspaceRegistry.upsert(nextWorkspaceRecord);
-        if (existing &&
-            !existing.archivedAt &&
-            existing.projectId !== nextWorkspaceRecord.projectId) {
+        if (existing && !existing.archivedAt && existing.projectId !== nextWorkspaceRecord.projectId) {
             await this.archiveProjectRecordIfEmpty(existing.projectId, now);
         }
         return {
@@ -777,7 +784,30 @@ export class Session {
     async reconcileActiveWorkspaceRecords() {
         const changedWorkspaceIds = new Set();
         const activeWorkspaces = (await this.workspaceRegistry.list()).filter((workspace) => !workspace.archivedAt);
+        const staleWorkspaceIds = await detectStaleWorkspaces({
+            activeWorkspaces,
+            agentRecords: (await this.agentStorage.list()).map((agent) => ({
+                cwd: agent.cwd,
+                archivedAt: agent.archivedAt ?? null,
+            })),
+            checkDirectoryExists: async (cwd) => {
+                try {
+                    await stat(cwd);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            },
+        });
+        for (const workspaceId of staleWorkspaceIds) {
+            await this.archiveWorkspaceRecord(workspaceId);
+            changedWorkspaceIds.add(workspaceId);
+        }
         for (const workspace of activeWorkspaces) {
+            if (staleWorkspaceIds.has(workspace.workspaceId)) {
+                continue;
+            }
             const result = await this.reconcileWorkspaceRecord(workspace.workspaceId);
             if (result.changed) {
                 changedWorkspaceIds.add(result.workspace.workspaceId);
@@ -799,14 +829,14 @@ export class Session {
                 });
                 if (matches) {
                     this.bufferOrEmitAgentUpdate(subscription, {
-                        kind: 'upsert',
+                        kind: "upsert",
                         agent: payload,
                         project,
                     });
                 }
                 else {
                     this.bufferOrEmitAgentUpdate(subscription, {
-                        kind: 'remove',
+                        kind: "remove",
                         agentId: payload.id,
                     });
                 }
@@ -814,7 +844,7 @@ export class Session {
             await this.emitWorkspaceUpdateForCwd(payload.cwd);
         }
         catch (error) {
-            this.sessionLogger.error({ err: error }, 'Failed to emit agent update');
+            this.sessionLogger.error({ err: error }, "Failed to emit agent update");
         }
     }
     /**
@@ -823,48 +853,48 @@ export class Session {
     async handleMessage(msg) {
         try {
             switch (msg.type) {
-                case 'voice_audio_chunk':
+                case "voice_audio_chunk":
                     await this.handleAudioChunk(msg);
                     break;
-                case 'abort_request':
+                case "abort_request":
                     await this.handleAbort();
                     break;
-                case 'audio_played':
+                case "audio_played":
                     this.handleAudioPlayed(msg.id);
                     break;
-                case 'fetch_agents_request':
+                case "fetch_agents_request":
                     await this.handleFetchAgents(msg);
                     break;
-                case 'fetch_workspaces_request':
+                case "fetch_workspaces_request":
                     await this.handleFetchWorkspacesRequest(msg);
                     break;
-                case 'fetch_agent_request':
+                case "fetch_agent_request":
                     await this.handleFetchAgent(msg.agentId, msg.requestId);
                     break;
-                case 'delete_agent_request':
+                case "delete_agent_request":
                     await this.handleDeleteAgentRequest(msg.agentId, msg.requestId);
                     break;
-                case 'archive_agent_request':
+                case "archive_agent_request":
                     await this.handleArchiveAgentRequest(msg.agentId, msg.requestId);
                     break;
-                case 'update_agent_request':
+                case "update_agent_request":
                     await this.handleUpdateAgentRequest(msg.agentId, msg.name, msg.labels, msg.requestId);
                     break;
-                case 'set_voice_mode':
+                case "set_voice_mode":
                     await this.handleSetVoiceMode(msg.enabled, msg.agentId, msg.requestId);
                     break;
-                case 'send_agent_message_request':
+                case "send_agent_message_request":
                     await this.handleSendAgentMessageRequest(msg);
                     break;
-                case 'wait_for_finish_request':
+                case "wait_for_finish_request":
                     await this.handleWaitForFinish(msg.agentId, msg.requestId, msg.timeoutMs);
                     break;
-                case 'dictation_stream_start':
+                case "dictation_stream_start":
                     {
-                        const unavailable = this.resolveVoiceFeatureUnavailableContext('dictation');
+                        const unavailable = this.resolveVoiceFeatureUnavailableContext("dictation");
                         if (unavailable) {
                             this.emit({
-                                type: 'dictation_stream_error',
+                                type: "dictation_stream_error",
                                 payload: {
                                     dictationId: msg.dictationId,
                                     error: unavailable.message,
@@ -878,7 +908,7 @@ export class Session {
                     }
                     await this.dictationStreamManager.handleStart(msg.dictationId, msg.format);
                     break;
-                case 'dictation_stream_chunk':
+                case "dictation_stream_chunk":
                     await this.dictationStreamManager.handleChunk({
                         dictationId: msg.dictationId,
                         seq: msg.seq,
@@ -886,124 +916,127 @@ export class Session {
                         format: msg.format,
                     });
                     break;
-                case 'dictation_stream_finish':
+                case "dictation_stream_finish":
                     await this.dictationStreamManager.handleFinish(msg.dictationId, msg.finalSeq);
                     break;
-                case 'dictation_stream_cancel':
+                case "dictation_stream_cancel":
                     this.dictationStreamManager.handleCancel(msg.dictationId);
                     break;
-                case 'create_agent_request':
+                case "create_agent_request":
                     await this.handleCreateAgentRequest(msg);
                     break;
-                case 'resume_agent_request':
+                case "resume_agent_request":
                     await this.handleResumeAgentRequest(msg);
                     break;
-                case 'refresh_agent_request':
+                case "refresh_agent_request":
                     await this.handleRefreshAgentRequest(msg);
                     break;
-                case 'cancel_agent_request':
+                case "cancel_agent_request":
                     await this.handleCancelAgentRequest(msg.agentId);
                     break;
-                case 'restart_server_request':
+                case "restart_server_request":
                     await this.handleRestartServerRequest(msg.requestId, msg.reason);
                     break;
-                case 'shutdown_server_request':
+                case "shutdown_server_request":
                     await this.handleShutdownServerRequest(msg.requestId);
                     break;
-                case 'fetch_agent_timeline_request':
+                case "fetch_agent_timeline_request":
                     await this.handleFetchAgentTimelineRequest(msg);
                     break;
-                case 'set_agent_mode_request':
+                case "set_agent_mode_request":
                     await this.handleSetAgentModeRequest(msg.agentId, msg.modeId, msg.requestId);
                     break;
-                case 'set_agent_model_request':
+                case "set_agent_model_request":
                     await this.handleSetAgentModelRequest(msg.agentId, msg.modelId, msg.requestId);
                     break;
-                case 'set_agent_thinking_request':
+                case "set_agent_thinking_request":
                     await this.handleSetAgentThinkingRequest(msg.agentId, msg.thinkingOptionId, msg.requestId);
                     break;
-                case 'agent_permission_response':
+                case "agent_permission_response":
                     await this.handleAgentPermissionResponse(msg.agentId, msg.requestId, msg.response);
                     break;
-                case 'checkout_status_request':
+                case "checkout_status_request":
                     await this.handleCheckoutStatusRequest(msg);
                     break;
-                case 'validate_branch_request':
+                case "validate_branch_request":
                     await this.handleValidateBranchRequest(msg);
                     break;
-                case 'branch_suggestions_request':
+                case "branch_suggestions_request":
                     await this.handleBranchSuggestionsRequest(msg);
                     break;
-                case 'directory_suggestions_request':
+                case "directory_suggestions_request":
                     await this.handleDirectorySuggestionsRequest(msg);
                     break;
-                case 'subscribe_checkout_diff_request':
+                case "subscribe_checkout_diff_request":
                     await this.handleSubscribeCheckoutDiffRequest(msg);
                     break;
-                case 'unsubscribe_checkout_diff_request':
+                case "unsubscribe_checkout_diff_request":
                     this.handleUnsubscribeCheckoutDiffRequest(msg);
                     break;
-                case 'checkout_commit_request':
+                case "checkout_commit_request":
                     await this.handleCheckoutCommitRequest(msg);
                     break;
-                case 'checkout_merge_request':
+                case "checkout_merge_request":
                     await this.handleCheckoutMergeRequest(msg);
                     break;
-                case 'checkout_merge_from_base_request':
+                case "checkout_merge_from_base_request":
                     await this.handleCheckoutMergeFromBaseRequest(msg);
                     break;
-                case 'checkout_push_request':
+                case "checkout_push_request":
                     await this.handleCheckoutPushRequest(msg);
                     break;
-                case 'checkout_pr_create_request':
+                case "checkout_pr_create_request":
                     await this.handleCheckoutPrCreateRequest(msg);
                     break;
-                case 'checkout_pr_status_request':
+                case "checkout_pr_status_request":
                     await this.handleCheckoutPrStatusRequest(msg);
                     break;
-                case 'paseo_worktree_list_request':
+                case "paseo_worktree_list_request":
                     await this.handlePaseoWorktreeListRequest(msg);
                     break;
-                case 'paseo_worktree_archive_request':
+                case "paseo_worktree_archive_request":
                     await this.handlePaseoWorktreeArchiveRequest(msg);
                     break;
-                case 'open_project_request':
+                case "create_paseo_worktree_request":
+                    await this.handleCreatePaseoWorktreeRequest(msg);
+                    break;
+                case "open_project_request":
                     await this.handleOpenProjectRequest(msg);
                     break;
-                case 'archive_workspace_request':
+                case "archive_workspace_request":
                     await this.handleArchiveWorkspaceRequest(msg);
                     break;
-                case 'file_explorer_request':
+                case "file_explorer_request":
                     await this.handleFileExplorerRequest(msg);
                     break;
-                case 'project_icon_request':
+                case "project_icon_request":
                     await this.handleProjectIconRequest(msg);
                     break;
-                case 'file_download_token_request':
+                case "file_download_token_request":
                     await this.handleFileDownloadTokenRequest(msg);
                     break;
-                case 'list_provider_models_request':
+                case "list_provider_models_request":
                     await this.handleListProviderModelsRequest(msg);
                     break;
-                case 'list_available_providers_request':
+                case "list_available_providers_request":
                     await this.handleListAvailableProvidersRequest(msg);
                     break;
-                case 'speech_models_list_request':
+                case "speech_models_list_request":
                     await this.handleSpeechModelsListRequest(msg);
                     break;
-                case 'speech_models_download_request':
+                case "speech_models_download_request":
                     await this.handleSpeechModelsDownloadRequest(msg);
                     break;
-                case 'clear_agent_attention':
+                case "clear_agent_attention":
                     await this.handleClearAgentAttention(msg.agentId);
                     break;
-                case 'client_heartbeat':
+                case "client_heartbeat":
                     this.handleClientHeartbeat(msg);
                     break;
-                case 'ping': {
+                case "ping": {
                     const now = Date.now();
                     this.emit({
-                        type: 'pong',
+                        type: "pong",
                         payload: {
                             requestId: msg.requestId,
                             clientSentAt: msg.clientSentAt,
@@ -1013,160 +1046,136 @@ export class Session {
                     });
                     break;
                 }
-                case 'list_commands_request':
+                case "list_commands_request":
                     await this.handleListCommandsRequest(msg);
                     break;
-                case 'register_push_token':
+                case "register_push_token":
                     this.handleRegisterPushToken(msg.token);
                     break;
-                case 'subscribe_terminals_request':
+                case "subscribe_terminals_request":
                     this.handleSubscribeTerminalsRequest(msg);
                     break;
-                case 'unsubscribe_terminals_request':
+                case "unsubscribe_terminals_request":
                     this.handleUnsubscribeTerminalsRequest(msg);
                     break;
-                case 'list_terminals_request':
+                case "list_terminals_request":
                     await this.handleListTerminalsRequest(msg);
                     break;
-                case 'create_terminal_request':
+                case "create_terminal_request":
                     await this.handleCreateTerminalRequest(msg);
                     break;
-                case 'subscribe_terminal_request':
+                case "subscribe_terminal_request":
                     await this.handleSubscribeTerminalRequest(msg);
                     break;
-                case 'unsubscribe_terminal_request':
+                case "unsubscribe_terminal_request":
                     this.handleUnsubscribeTerminalRequest(msg);
                     break;
-                case 'terminal_input':
+                case "terminal_input":
                     this.handleTerminalInput(msg);
                     break;
-                case 'kill_terminal_request':
+                case "kill_terminal_request":
                     await this.handleKillTerminalRequest(msg);
                     break;
-                case 'attach_terminal_stream_request':
-                    await this.handleAttachTerminalStreamRequest(msg);
-                    break;
-                case 'detach_terminal_stream_request':
-                    this.handleDetachTerminalStreamRequest(msg);
-                    break;
             }
         }
         catch (error) {
             const err = error instanceof Error ? error : new Error(String(error));
-            this.sessionLogger.error({ err }, 'Error handling message');
+            this.sessionLogger.error({ err }, "Error handling message");
             const requestId = msg.requestId;
-            if (typeof requestId === 'string') {
+            if (typeof requestId === "string") {
                 try {
                     this.emit({
-                        type: 'rpc_error',
+                        type: "rpc_error",
                         payload: {
                             requestId,
                             requestType: msg.type,
-                            error: 'Request failed',
-                            code: 'handler_error',
+                            error: `Request failed: ${err.message}`,
+                            code: "handler_error",
                         },
                     });
                 }
                 catch (emitError) {
-                    this.sessionLogger.error({ err: emitError }, 'Failed to emit rpc_error');
+                    this.sessionLogger.error({ err: emitError }, "Failed to emit rpc_error");
                 }
             }
             this.emit({
-                type: 'activity_log',
+                type: "activity_log",
                 payload: {
                     id: uuidv4(),
                     timestamp: new Date(),
-                    type: 'error',
+                    type: "error",
                     content: `Error: ${err.message}`,
                 },
             });
         }
     }
     handleBinaryFrame(frame) {
-        switch (frame.channel) {
-            case BinaryMuxChannel.Terminal:
-                this.handleTerminalBinaryFrame(frame);
-                break;
-            default:
-                this.sessionLogger.warn({ channel: frame.channel, messageType: frame.messageType }, 'Unhandled binary mux channel');
-                break;
+        const activeStream = this.activeTerminalStreams.get(frame.slot);
+        if (!activeStream || !this.terminalManager) {
+            return;
         }
-    }
-    handleTerminalBinaryFrame(frame) {
-        if (frame.messageType === TerminalBinaryMessageType.InputUtf8) {
-            const binding = this.terminalStreams.get(frame.streamId);
-            if (!binding) {
-                this.sessionLogger.warn({ streamId: frame.streamId }, 'Terminal stream not found for input');
-                return;
-            }
-            if (!this.terminalManager) {
-                return;
-            }
-            const session = this.terminalManager.getTerminal(binding.terminalId);
-            if (!session) {
-                this.detachTerminalStream(frame.streamId, { emitExit: true });
-                return;
-            }
-            const payload = frame.payload ?? new Uint8Array(0);
-            if (payload.byteLength === 0) {
-                return;
-            }
-            const text = Buffer.from(payload).toString('utf8');
-            if (!text) {
-                return;
-            }
-            session.send({ type: 'input', data: text });
+        const terminal = this.terminalManager.getTerminal(activeStream.terminalId);
+        if (!terminal) {
+            this.detachTerminalStream(activeStream.terminalId, { emitExit: true });
             return;
         }
-        if (frame.messageType === TerminalBinaryMessageType.Ack) {
-            const binding = this.terminalStreams.get(frame.streamId);
-            if (binding) {
-                if (!Number.isFinite(frame.offset) || frame.offset < 0) {
+        switch (frame.opcode) {
+            case TerminalStreamOpcode.Input: {
+                if (frame.payload.byteLength === 0) {
                     return;
                 }
-                const nextAckOffset = Math.max(binding.lastAckOffset, Math.min(Math.floor(frame.offset), binding.lastOutputOffset));
-                if (nextAckOffset > binding.lastAckOffset) {
-                    binding.lastAckOffset = nextAckOffset;
-                    this.flushPendingTerminalStreamChunks(frame.streamId, binding);
+                const text = Buffer.from(frame.payload).toString("utf8");
+                if (!text) {
+                    return;
                 }
+                terminal.send({ type: "input", data: text });
+                return;
             }
-            return;
+            case TerminalStreamOpcode.Resize: {
+                const resize = decodeTerminalResizePayload(frame.payload);
+                if (!resize) {
+                    return;
+                }
+                terminal.send({ type: "resize", rows: resize.rows, cols: resize.cols });
+                return;
+            }
+            default:
+                return;
         }
-        this.sessionLogger.warn({ streamId: frame.streamId, messageType: frame.messageType }, 'Unhandled terminal binary frame');
     }
     async handleRestartServerRequest(requestId, reason) {
         const payload = {
-            status: 'restart_requested',
+            status: "restart_requested",
             clientId: this.clientId,
         };
         if (reason && reason.trim().length > 0) {
             payload.reason = reason;
         }
         payload.requestId = requestId;
-        this.sessionLogger.warn({ reason }, 'Restart requested via websocket');
+        this.sessionLogger.warn({ reason }, "Restart requested via websocket");
         this.emit({
-            type: 'status',
+            type: "status",
             payload,
         });
         this.emitLifecycleIntent({
-            type: 'restart',
+            type: "restart",
             clientId: this.clientId,
             requestId,
             ...(reason ? { reason } : {}),
         });
     }
     async handleShutdownServerRequest(requestId) {
-        this.sessionLogger.warn('Shutdown requested via websocket');
+        this.sessionLogger.warn("Shutdown requested via websocket");
         this.emit({
-            type: 'status',
+            type: "status",
             payload: {
-                status: 'shutdown_requested',
+                status: "shutdown_requested",
                 clientId: this.clientId,
                 requestId,
             },
         });
         this.emitLifecycleIntent({
-            type: 'shutdown',
+            type: "shutdown",
             clientId: this.clientId,
             requestId,
         });
@@ -1179,7 +1188,7 @@ export class Session {
             this.onLifecycleIntent(intent);
         }
         catch (error) {
-            this.sessionLogger.error({ err: error, intent }, 'Lifecycle intent handler failed');
+            this.sessionLogger.error({ err: error, intent }, "Lifecycle intent handler failed");
         }
     }
     async handleDeleteAgentRequest(agentId, requestId) {
@@ -1202,7 +1211,7 @@ export class Session {
             this.sessionLogger.error({ err: error, agentId }, `Failed to remove agent ${agentId} from registry`);
         }
         this.emit({
-            type: 'agent_deleted',
+            type: "agent_deleted",
             payload: {
                 agentId,
                 requestId,
@@ -1210,7 +1219,7 @@ export class Session {
         });
         if (this.agentUpdatesSubscription) {
             this.bufferOrEmitAgentUpdate(this.agentUpdatesSubscription, {
-                kind: 'remove',
+                kind: "remove",
                 agentId,
             });
         }
@@ -1222,7 +1231,7 @@ export class Session {
         this.sessionLogger.info({ agentId }, `Archiving agent ${agentId}`);
         const { archivedAt } = await this.archiveAgentState(agentId);
         this.emit({
-            type: 'agent_archived',
+            type: "agent_archived",
             payload: {
                 agentId,
                 archivedAt,
@@ -1251,8 +1260,8 @@ export class Session {
                 throw new Error(`Agent not found in storage after snapshot: ${agentId}`);
             }
         }
-        const normalizedStatus = archivedRecord.lastStatus === 'running' || archivedRecord.lastStatus === 'initializing'
-            ? 'idle'
+        const normalizedStatus = archivedRecord.lastStatus === "running" || archivedRecord.lastStatus === "initializing"
+            ? "idle"
             : archivedRecord.lastStatus;
         const nextRecord = {
             ...archivedRecord,
@@ -1263,7 +1272,17 @@ export class Session {
             attentionTimestamp: null,
         };
         await this.agentStorage.upsert(nextRecord);
-        this.agentManager.notifyAgentState(agentId);
+        // Unload the agent from memory — the storage record is the source of truth now.
+        // This tears down the provider session and drops the hydrated timeline,
+        // freeing memory. ensureAgentLoaded will re-initialize if needed later.
+        if (this.agentManager.getAgent(agentId)) {
+            try {
+                await this.agentManager.closeAgent(agentId);
+            }
+            catch (error) {
+                this.sessionLogger.warn({ err: error, agentId }, "Failed to close agent during archive");
+            }
+        }
         return { archivedAt, archivedRecord: nextRecord };
     }
     async unarchiveAgentState(agentId) {
@@ -1291,19 +1310,19 @@ export class Session {
         this.sessionLogger.info({
             agentId,
             requestId,
-            hasName: typeof name === 'string',
+            hasName: typeof name === "string",
             labelCount: labels ? Object.keys(labels).length : 0,
-        }, 'session: update_agent_request');
+        }, "session: update_agent_request");
         const normalizedName = name?.trim();
         const normalizedLabels = labels && Object.keys(labels).length > 0 ? labels : undefined;
         if (!normalizedName && !normalizedLabels) {
             this.emit({
-                type: 'update_agent_response',
+                type: "update_agent_response",
                 payload: {
                     requestId,
                     agentId,
                     accepted: false,
-                    error: 'Nothing to update (provide name and/or labels)',
+                    error: "Nothing to update (provide name and/or labels)",
                 },
             });
             return;
@@ -1330,28 +1349,28 @@ export class Session {
                 });
             }
             this.emit({
-                type: 'update_agent_response',
+                type: "update_agent_response",
                 payload: { requestId, agentId, accepted: true, error: null },
             });
         }
         catch (error) {
-            this.sessionLogger.error({ err: error, agentId, requestId }, 'session: update_agent_request error');
+            this.sessionLogger.error({ err: error, agentId, requestId }, "session: update_agent_request error");
             this.emit({
-                type: 'activity_log',
+                type: "activity_log",
                 payload: {
                     id: uuidv4(),
                     timestamp: new Date(),
-                    type: 'error',
+                    type: "error",
                     content: `Failed to update agent: ${error.message}`,
                 },
             });
             this.emit({
-                type: 'update_agent_response',
+                type: "update_agent_response",
                 payload: {
                     requestId,
                     agentId,
                     accepted: false,
-                    error: error?.message ? String(error.message) : 'Failed to update agent',
+                    error: error?.message ? String(error.message) : "Failed to update agent",
                 },
             });
         }
@@ -1365,7 +1384,7 @@ export class Session {
         };
     }
     resolveModeReadinessState(readiness, mode) {
-        if (mode === 'voice_mode') {
+        if (mode === "voice_mode") {
             return readiness.realtimeVoice;
         }
         return readiness.dictation;
@@ -1403,13 +1422,13 @@ export class Session {
     async handleSetVoiceMode(enabled, agentId, requestId) {
         const startedAt = Date.now();
         try {
-            this.sessionLogger.info({ enabled, requestedAgentId: agentId ?? null, requestId: requestId ?? null }, 'set_voice_mode started');
+            this.sessionLogger.info({ enabled, requestedAgentId: agentId ?? null, requestId: requestId ?? null }, "set_voice_mode started");
             if (enabled) {
-                const unavailable = this.resolveVoiceFeatureUnavailableContext('voice_mode');
+                const unavailable = this.resolveVoiceFeatureUnavailableContext("voice_mode");
                 if (unavailable) {
                     throw new VoiceFeatureUnavailableError(unavailable);
                 }
-                const normalizedAgentId = this.parseVoiceTargetAgentId(agentId ?? '', 'set_voice_mode');
+                const normalizedAgentId = this.parseVoiceTargetAgentId(agentId ?? "", "set_voice_mode");
                 if (this.isVoiceMode &&
                     this.voiceModeAgentId &&
                     this.voiceModeAgentId !== normalizedAgentId) {
@@ -1417,26 +1436,26 @@ export class Session {
                         previousAgentId: this.voiceModeAgentId,
                         nextAgentId: normalizedAgentId,
                         elapsedMs: Date.now() - startedAt,
-                    }, 'set_voice_mode disabling previous active voice agent');
+                    }, "set_voice_mode disabling previous active voice agent");
                     await this.disableVoiceModeForActiveAgent(true);
                 }
                 if (!this.isVoiceMode || this.voiceModeAgentId !== normalizedAgentId) {
-                    this.sessionLogger.info({ agentId: normalizedAgentId, elapsedMs: Date.now() - startedAt }, 'set_voice_mode enabling voice for agent');
+                    this.sessionLogger.info({ agentId: normalizedAgentId, elapsedMs: Date.now() - startedAt }, "set_voice_mode enabling voice for agent");
                     const refreshedAgentId = await this.enableVoiceModeForAgent(normalizedAgentId);
                     this.voiceModeAgentId = refreshedAgentId;
-                    this.sessionLogger.info({ agentId: refreshedAgentId, elapsedMs: Date.now() - startedAt }, 'set_voice_mode agent enable complete');
+                    this.sessionLogger.info({ agentId: refreshedAgentId, elapsedMs: Date.now() - startedAt }, "set_voice_mode agent enable complete");
                 }
-                this.sessionLogger.info({ agentId: this.voiceModeAgentId, elapsedMs: Date.now() - startedAt }, 'set_voice_mode starting voice turn controller');
+                this.sessionLogger.info({ agentId: this.voiceModeAgentId, elapsedMs: Date.now() - startedAt }, "set_voice_mode starting voice turn controller");
                 await this.startVoiceTurnController();
-                this.sessionLogger.info({ agentId: this.voiceModeAgentId, elapsedMs: Date.now() - startedAt }, 'set_voice_mode voice turn controller started');
+                this.sessionLogger.info({ agentId: this.voiceModeAgentId, elapsedMs: Date.now() - startedAt }, "set_voice_mode voice turn controller started");
                 this.isVoiceMode = true;
                 this.sessionLogger.info({
                     agentId: this.voiceModeAgentId,
                     elapsedMs: Date.now() - startedAt,
-                }, 'Voice mode enabled for existing agent');
+                }, "Voice mode enabled for existing agent");
                 if (requestId) {
                     this.emit({
-                        type: 'set_voice_mode_response',
+                        type: "set_voice_mode_response",
                         payload: {
                             requestId,
                             enabled: true,
@@ -1448,13 +1467,13 @@ export class Session {
                 }
                 return;
             }
-            this.sessionLogger.info({ agentId: this.voiceModeAgentId, elapsedMs: Date.now() - startedAt }, 'set_voice_mode disabling active voice mode');
+            this.sessionLogger.info({ agentId: this.voiceModeAgentId, elapsedMs: Date.now() - startedAt }, "set_voice_mode disabling active voice mode");
             await this.disableVoiceModeForActiveAgent(true);
             this.isVoiceMode = false;
-            this.sessionLogger.info({ elapsedMs: Date.now() - startedAt }, 'Voice mode disabled');
+            this.sessionLogger.info({ elapsedMs: Date.now() - startedAt }, "Voice mode disabled");
             if (requestId) {
                 this.emit({
-                    type: 'set_voice_mode_response',
+                    type: "set_voice_mode_response",
                     payload: {
                         requestId,
                         enabled: false,
@@ -1466,17 +1485,17 @@ export class Session {
             }
         }
         catch (error) {
-            const errorMessage = error instanceof Error ? error.message : 'Failed to set voice mode';
+            const errorMessage = error instanceof Error ? error.message : "Failed to set voice mode";
             const unavailable = this.getVoiceFeatureUnavailableResponseMetadata(error);
             this.sessionLogger.error({
                 err: error,
                 enabled,
                 requestedAgentId: agentId ?? null,
                 elapsedMs: Date.now() - startedAt,
-            }, 'set_voice_mode failed');
+            }, "set_voice_mode failed");
             if (requestId) {
                 this.emit({
-                    type: 'set_voice_mode_response',
+                    type: "set_voice_mode_response",
                     payload: {
                         requestId,
                         enabled: this.isVoiceMode,
@@ -1507,7 +1526,7 @@ export class Session {
     buildVoiceModeMcpServers(existing, socketPath) {
         const mcpStdio = this.voiceAgentMcpStdio;
         if (!mcpStdio) {
-            throw new Error('Voice MCP stdio bridge is not configured');
+            throw new Error("Voice MCP stdio bridge is not configured");
         }
         return {
             ...(existing ?? {}),
@@ -1523,14 +1542,14 @@ export class Session {
         const startedAt = Date.now();
         const ensureVoiceSocket = this.ensureVoiceMcpSocketForAgent;
         if (!ensureVoiceSocket) {
-            throw new Error('Voice MCP socket bridge is not configured');
+            throw new Error("Voice MCP socket bridge is not configured");
         }
-        this.sessionLogger.info({ agentId }, 'enableVoiceModeForAgent.ensureAgentLoaded.start');
+        this.sessionLogger.info({ agentId }, "enableVoiceModeForAgent.ensureAgentLoaded.start");
         const existing = await this.ensureAgentLoaded(agentId);
-        this.sessionLogger.info({ agentId, elapsedMs: Date.now() - startedAt }, 'enableVoiceModeForAgent.ensureAgentLoaded.done');
-        this.sessionLogger.info({ agentId }, 'enableVoiceModeForAgent.ensureVoiceSocket.start');
+        this.sessionLogger.info({ agentId, elapsedMs: Date.now() - startedAt }, "enableVoiceModeForAgent.ensureAgentLoaded.done");
+        this.sessionLogger.info({ agentId }, "enableVoiceModeForAgent.ensureVoiceSocket.start");
         const socketPath = await ensureVoiceSocket(agentId);
-        this.sessionLogger.info({ agentId, socketPath, elapsedMs: Date.now() - startedAt }, 'enableVoiceModeForAgent.ensureVoiceSocket.done');
+        this.sessionLogger.info({ agentId, socketPath, elapsedMs: Date.now() - startedAt }, "enableVoiceModeForAgent.ensureVoiceSocket.done");
         this.registerVoiceBridgeForAgent(agentId);
         const baseConfig = {
             systemPrompt: stripVoiceModeSystemPrompt(existing.config.systemPrompt),
@@ -1542,9 +1561,9 @@ export class Session {
             mcpServers: this.buildVoiceModeMcpServers(baseConfig.mcpServers, socketPath),
         };
         try {
-            this.sessionLogger.info({ agentId, elapsedMs: Date.now() - startedAt }, 'enableVoiceModeForAgent.reloadAgentSession.start');
+            this.sessionLogger.info({ agentId, elapsedMs: Date.now() - startedAt }, "enableVoiceModeForAgent.reloadAgentSession.start");
             const refreshed = await this.agentManager.reloadAgentSession(agentId, refreshOverrides);
-            this.sessionLogger.info({ agentId, refreshedAgentId: refreshed.id, elapsedMs: Date.now() - startedAt }, 'enableVoiceModeForAgent.reloadAgentSession.done');
+            this.sessionLogger.info({ agentId, refreshedAgentId: refreshed.id, elapsedMs: Date.now() - startedAt }, "enableVoiceModeForAgent.reloadAgentSession.done");
             return refreshed.id;
         }
         catch (error) {
@@ -1565,7 +1584,7 @@ export class Session {
         this.unregisterVoiceSpeakHandler?.(agentId);
         this.unregisterVoiceCallerContext?.(agentId);
         await this.removeVoiceMcpSocketForAgent?.(agentId).catch((error) => {
-            this.sessionLogger.warn({ err: error, agentId }, 'Failed to remove voice MCP socket bridge on disable');
+            this.sessionLogger.warn({ err: error, agentId }, "Failed to remove voice MCP socket bridge on disable");
         });
         if (restoreAgentConfig && this.voiceModeBaseConfig) {
             const baseConfig = this.voiceModeBaseConfig;
@@ -1576,7 +1595,7 @@ export class Session {
                 });
             }
             catch (error) {
-                this.sessionLogger.warn({ err: error, agentId }, 'Failed to restore agent config while disabling voice mode');
+                this.sessionLogger.warn({ err: error, agentId }, "Failed to restore agent config while disabling voice mode");
             }
         }
         this.voiceModeBaseConfig = null;
@@ -1587,16 +1606,16 @@ export class Session {
     }
     async startVoiceTurnController() {
         if (this.voiceTurnController) {
-            this.sessionLogger.info('startVoiceTurnController skipped: already running');
+            this.sessionLogger.info("startVoiceTurnController skipped: already running");
             return;
         }
         const turnDetection = this.resolveVoiceTurnDetection();
         if (!turnDetection) {
-            throw new Error('Voice turn detection is not configured');
+            throw new Error("Voice turn detection is not configured");
         }
-        this.sessionLogger.info({ providerId: turnDetection.id }, 'startVoiceTurnController creating controller');
+        this.sessionLogger.info({ providerId: turnDetection.id }, "startVoiceTurnController creating controller");
         const controller = createVoiceTurnController({
-            logger: this.sessionLogger.child({ component: 'voice-turn-controller' }),
+            logger: this.sessionLogger.child({ component: "voice-turn-controller" }),
             turnDetection,
             utteranceSink: {
                 submitUtterance: async ({ pcm16, format, sampleRate, startedAt, endedAt }) => {
@@ -1606,7 +1625,7 @@ export class Session {
                         startedAt,
                         endedAt,
                         durationMs: Math.max(0, endedAt - startedAt),
-                    }, 'Submitting detected voice utterance');
+                    }, "Submitting detected voice utterance");
                     await this.processCompletedAudio(pcm16, format);
                 },
             },
@@ -1618,20 +1637,20 @@ export class Session {
                     this.handleVoiceSpeechStopped();
                 },
                 onError: (error) => {
-                    this.sessionLogger.error({ err: error }, 'Voice turn controller failed');
+                    this.sessionLogger.error({ err: error }, "Voice turn controller failed");
                 },
             },
         });
-        this.sessionLogger.info('startVoiceTurnController connecting controller');
+        this.sessionLogger.info("startVoiceTurnController connecting controller");
         await controller.start();
         this.voiceTurnController = controller;
-        this.sessionLogger.info('startVoiceTurnController connected');
+        this.sessionLogger.info("startVoiceTurnController connected");
     }
     async stopVoiceTurnController() {
         if (!this.voiceTurnController) {
             return;
         }
-        this.clearPendingVoiceSpeechStart('turn-controller-stop');
+        this.clearPendingVoiceSpeechStart("turn-controller-stop");
         const controller = this.voiceTurnController;
         this.voiceTurnController = null;
         await controller.stop();
@@ -1642,7 +1661,7 @@ export class Session {
             this.pendingVoiceSpeechTimer = null;
         }
         if (this.pendingVoiceSpeechStartAt !== null) {
-            this.sessionLogger.debug({ reason }, 'Clearing provisional voice speech start');
+            this.sessionLogger.debug({ reason }, "Clearing provisional voice speech start");
             this.pendingVoiceSpeechStartAt = null;
         }
     }
@@ -1652,16 +1671,16 @@ export class Session {
         }
         const startedAt = Date.now();
         this.pendingVoiceSpeechStartAt = startedAt;
-        this.sessionLogger.info({ confirmationMs: VOICE_INTERRUPT_CONFIRMATION_MS }, 'Silero VAD provisional speech_started');
+        this.sessionLogger.info({ confirmationMs: VOICE_INTERRUPT_CONFIRMATION_MS }, "Silero VAD provisional speech_started");
         this.pendingVoiceSpeechTimer = setTimeout(() => {
             this.pendingVoiceSpeechTimer = null;
             if (this.pendingVoiceSpeechStartAt !== startedAt || this.speechInProgress) {
                 return;
             }
             this.pendingVoiceSpeechStartAt = null;
-            this.sessionLogger.info('voice_input_state emitting isSpeaking=true');
+            this.sessionLogger.info("voice_input_state emitting isSpeaking=true");
             this.emit({
-                type: 'voice_input_state',
+                type: "voice_input_state",
                 payload: {
                     isSpeaking: true,
                 },
@@ -1672,13 +1691,13 @@ export class Session {
     handleVoiceSpeechStopped() {
         if (this.pendingVoiceSpeechStartAt !== null) {
             const durationMs = Date.now() - this.pendingVoiceSpeechStartAt;
-            this.clearPendingVoiceSpeechStart('speech-stopped-before-confirmation');
-            this.sessionLogger.info({ durationMs, confirmationMs: VOICE_INTERRUPT_CONFIRMATION_MS }, 'Ignoring provisional voice speech start that ended before confirmation');
+            this.clearPendingVoiceSpeechStart("speech-stopped-before-confirmation");
+            this.sessionLogger.info({ durationMs, confirmationMs: VOICE_INTERRUPT_CONFIRMATION_MS }, "Ignoring provisional voice speech start that ended before confirmation");
             return;
         }
-        this.sessionLogger.info('voice_input_state emitting isSpeaking=false');
+        this.sessionLogger.info("voice_input_state emitting isSpeaking=false");
         this.emit({
-            type: 'voice_input_state',
+            type: "voice_input_state",
             payload: {
                 isSpeaking: false,
             },
@@ -1688,13 +1707,13 @@ export class Session {
      * Handle text message to agent (with optional image attachments)
      */
     async handleSendAgentMessage(agentId, text, messageId, images, runOptions) {
-        this.sessionLogger.info({ agentId, textPreview: text.substring(0, 50), imageCount: images?.length ?? 0 }, `Sending text to agent ${agentId}${images && images.length > 0 ? ` with ${images.length} image attachment(s)` : ''}`);
+        this.sessionLogger.info({ agentId, textPreview: text.substring(0, 50), imageCount: images?.length ?? 0 }, `Sending text to agent ${agentId}${images && images.length > 0 ? ` with ${images.length} image attachment(s)` : ""}`);
         await this.unarchiveAgentState(agentId);
         try {
             await this.ensureAgentLoaded(agentId);
         }
         catch (error) {
-            this.handleAgentRunError(agentId, error, 'Failed to initialize agent before sending prompt');
+            this.handleAgentRunError(agentId, error, "Failed to initialize agent before sending prompt");
             return;
         }
         try {
@@ -1714,7 +1733,7 @@ export class Session {
      */
     async handleCreateAgentRequest(msg) {
         const { config, worktreeName, requestId, initialPrompt, clientMessageId, outputSchema, git, images, labels, } = msg;
-        this.sessionLogger.info({ cwd: config.cwd, provider: config.provider, worktreeName }, `Creating agent in ${config.cwd} (${config.provider})${worktreeName ? ` with worktree ${worktreeName}` : ''}`);
+        this.sessionLogger.info({ cwd: config.cwd, provider: config.provider, worktreeName }, `Creating agent in ${config.cwd} (${config.provider})${worktreeName ? ` with worktree ${worktreeName}` : ""}`);
         try {
             const trimmedPrompt = initialPrompt?.trim();
             const { explicitTitle, provisionalTitle } = resolveCreateAgentTitles({
@@ -1735,9 +1754,9 @@ export class Session {
                     throw new Error(`Agent ${snapshot.id} not found after creation`);
                 }
                 this.emit({
-                    type: 'status',
+                    type: "status",
                     payload: {
-                        status: 'agent_created',
+                        status: "agent_created",
                         agentId: snapshot.id,
                         requestId,
                         agent: agentPayload,
@@ -1757,11 +1776,11 @@ export class Session {
                 void this.handleSendAgentMessage(snapshot.id, trimmedPrompt, resolveClientMessageId(clientMessageId), images, outputSchema ? { outputSchema } : undefined).catch((promptError) => {
                     this.sessionLogger.error({ err: promptError, agentId: snapshot.id }, `Failed to run initial prompt for agent ${snapshot.id}`);
                     this.emit({
-                        type: 'activity_log',
+                        type: "activity_log",
                         payload: {
                             id: uuidv4(),
                             timestamp: new Date(),
-                            type: 'error',
+                            type: "error",
                             content: `Initial prompt failed: ${promptError?.message ?? promptError}`,
                         },
                     });
@@ -1788,23 +1807,23 @@ export class Session {
             this.sessionLogger.info({ agentId: snapshot.id, provider: snapshot.provider }, `Created agent ${snapshot.id} (${snapshot.provider})`);
         }
         catch (error) {
-            this.sessionLogger.error({ err: error }, 'Failed to create agent');
+            this.sessionLogger.error({ err: error }, "Failed to create agent");
             if (requestId) {
                 this.emit({
-                    type: 'status',
+                    type: "status",
                     payload: {
-                        status: 'agent_create_failed',
+                        status: "agent_create_failed",
                         requestId,
                         error: error?.message ?? String(error),
                     },
                 });
             }
             this.emit({
-                type: 'activity_log',
+                type: "activity_log",
                 payload: {
                     id: uuidv4(),
                     timestamp: new Date(),
-                    type: 'error',
+                    type: "error",
                     content: `Failed to create agent: ${error.message}`,
                 },
             });
@@ -1813,14 +1832,14 @@ export class Session {
     async handleResumeAgentRequest(msg) {
         const { handle, overrides, requestId } = msg;
         if (!handle) {
-            this.sessionLogger.warn('Resume request missing persistence handle');
+            this.sessionLogger.warn("Resume request missing persistence handle");
             this.emit({
-                type: 'activity_log',
+                type: "activity_log",
                 payload: {
                     id: uuidv4(),
                     timestamp: new Date(),
-                    type: 'error',
-                    content: 'Unable to resume agent: missing persistence handle',
+                    type: "error",
+                    content: "Unable to resume agent: missing persistence handle",
                 },
             });
             return;
@@ -1839,9 +1858,9 @@ export class Session {
                     throw new Error(`Agent ${snapshot.id} not found after resume`);
                 }
                 this.emit({
-                    type: 'status',
+                    type: "status",
                     payload: {
-                        status: 'agent_resumed',
+                        status: "agent_resumed",
                         agentId: snapshot.id,
                         requestId,
                         timelineSize,
@@ -1851,13 +1870,13 @@ export class Session {
             }
         }
         catch (error) {
-            this.sessionLogger.error({ err: error }, 'Failed to resume agent');
+            this.sessionLogger.error({ err: error }, "Failed to resume agent");
             this.emit({
-                type: 'activity_log',
+                type: "activity_log",
                 payload: {
                     id: uuidv4(),
                     timestamp: new Date(),
-                    type: 'error',
+                    type: "error",
                     content: `Failed to resume agent: ${error.message}`,
                 },
             });
@@ -1895,9 +1914,9 @@ export class Session {
             const timelineSize = this.agentManager.getTimeline(agentId).length;
             if (requestId) {
                 this.emit({
-                    type: 'status',
+                    type: "status",
                     payload: {
-                        status: 'agent_refreshed',
+                        status: "agent_refreshed",
                         agentId,
                         requestId,
                         timelineSize,
@@ -1908,11 +1927,11 @@ export class Session {
         catch (error) {
             this.sessionLogger.error({ err: error, agentId }, `Failed to refresh agent ${agentId}`);
             this.emit({
-                type: 'activity_log',
+                type: "activity_log",
                 payload: {
                     id: uuidv4(),
                     timestamp: new Date(),
-                    type: 'error',
+                    type: "error",
                     content: `Failed to refresh agent: ${error.message}`,
                 },
             });
@@ -1924,7 +1943,7 @@ export class Session {
             await this.interruptAgentIfRunning(agentId);
         }
         catch (error) {
-            this.handleAgentRunError(agentId, error, 'Failed to cancel running agent on request');
+            this.handleAgentRunError(agentId, error, "Failed to cancel running agent on request");
         }
     }
     async buildAgentSessionConfig(config, gitOptions, legacyWorktreeName, _labels) {
@@ -1946,20 +1965,21 @@ export class Session {
             }
             else {
                 // Resolve current branch name from HEAD
-                const { stdout } = await execAsync('git rev-parse --abbrev-ref HEAD', {
+                const { stdout } = await execAsync("git rev-parse --abbrev-ref HEAD", {
                     cwd,
                     env: READ_ONLY_GIT_ENV,
                 });
                 targetBranch = stdout.trim();
             }
             if (!targetBranch) {
-                throw new Error('A branch name is required when creating a worktree.');
+                throw new Error("A branch name is required when creating a worktree.");
             }
             this.sessionLogger.info({ worktreeSlug: normalized.worktreeSlug ?? targetBranch, branch: targetBranch }, `Creating worktree '${normalized.worktreeSlug ?? targetBranch}' for branch ${targetBranch}`);
+            const baseBranch = normalized.baseBranch ?? (await this.resolveGitCreateBaseBranch(cwd));
             const createdWorktree = await createAgentWorktree({
                 branchName: targetBranch,
                 cwd,
-                baseBranch: normalized.baseBranch,
+                baseBranch,
                 worktreeSlug: normalized.worktreeSlug ?? targetBranch,
                 paseoHome: this.paseoHome,
             });
@@ -1967,9 +1987,10 @@ export class Session {
             worktreeConfig = createdWorktree;
         }
         else if (normalized.createNewBranch) {
+            const baseBranch = normalized.baseBranch ?? (await this.resolveGitCreateBaseBranch(cwd));
             await this.createBranchFromBase({
                 cwd,
-                baseBranch: normalized.baseBranch,
+                baseBranch,
                 newBranchName: normalized.newBranchName,
             });
         }
@@ -1991,7 +2012,7 @@ export class Session {
                 cwd: msg.cwd ? expandTilde(msg.cwd) : undefined,
             });
             this.emit({
-                type: 'list_provider_models_response',
+                type: "list_provider_models_response",
                 payload: {
                     provider: msg.provider,
                     models,
@@ -2004,7 +2025,7 @@ export class Session {
         catch (error) {
             this.sessionLogger.error({ err: error, provider: msg.provider }, `Failed to list models for ${msg.provider}`);
             this.emit({
-                type: 'list_provider_models_response',
+                type: "list_provider_models_response",
                 payload: {
                     provider: msg.provider,
                     error: error?.message ?? String(error),
@@ -2019,7 +2040,7 @@ export class Session {
         try {
             const providers = await this.agentManager.listProviderAvailability();
             this.emit({
-                type: 'list_available_providers_response',
+                type: "list_available_providers_response",
                 payload: {
                     providers,
                     error: null,
@@ -2029,9 +2050,9 @@ export class Session {
             });
         }
         catch (error) {
-            this.sessionLogger.error({ err: error }, 'Failed to list provider availability');
+            this.sessionLogger.error({ err: error }, "Failed to list provider availability");
             this.emit({
-                type: 'list_available_providers_response',
+                type: "list_available_providers_response",
                 payload: {
                     providers: [],
                     error: error?.message ?? String(error),
@@ -2071,7 +2092,7 @@ export class Session {
             };
         }));
         this.emit({
-            type: 'speech_models_list_response',
+            type: "speech_models_list_response",
             payload: {
                 modelsDir,
                 models,
@@ -2086,11 +2107,11 @@ export class Session {
         const invalid = modelIdsRaw.filter((id) => !allModelIds.has(id));
         if (invalid.length > 0) {
             this.emit({
-                type: 'speech_models_download_response',
+                type: "speech_models_download_response",
                 payload: {
                     modelsDir,
                     downloadedModelIds: [],
-                    error: `Unknown speech model id(s): ${invalid.join(', ')}`,
+                    error: `Unknown speech model id(s): ${invalid.join(", ")}`,
                     requestId: msg.requestId,
                 },
             });
@@ -2104,7 +2125,7 @@ export class Session {
                 logger: this.sessionLogger,
             });
             this.emit({
-                type: 'speech_models_download_response',
+                type: "speech_models_download_response",
                 payload: {
                     modelsDir,
                     downloadedModelIds: modelIds,
@@ -2114,9 +2135,9 @@ export class Session {
             });
         }
         catch (error) {
-            this.sessionLogger.error({ err: error, modelIds }, 'Failed to download speech models');
+            this.sessionLogger.error({ err: error, modelIds }, "Failed to download speech models");
             this.emit({
-                type: 'speech_models_download_response',
+                type: "speech_models_download_response",
                 payload: {
                     modelsDir,
                     downloadedModelIds: [],
@@ -2150,17 +2171,11 @@ export class Session {
             return null;
         }
         if (baseBranch) {
-            this.assertSafeGitRef(baseBranch, 'base branch');
-        }
-        if (createWorktree && !baseBranch) {
-            throw new Error('Base branch is required when creating a worktree');
-        }
-        if (createNewBranch && !baseBranch) {
-            throw new Error('Base branch is required when creating a new branch');
+            this.assertSafeGitRef(baseBranch, "base branch");
         }
         if (createNewBranch) {
             if (!normalizedBranchName) {
-                throw new Error('New branch name is required');
+                throw new Error("New branch name is required");
             }
             const validation = validateBranchSlug(normalizedBranchName);
             if (!validation.valid) {
@@ -2182,24 +2197,36 @@ export class Session {
         };
     }
     assertSafeGitRef(ref, label) {
-        if (!SAFE_GIT_REF_PATTERN.test(ref) || ref.includes('..') || ref.includes('@{')) {
+        if (!SAFE_GIT_REF_PATTERN.test(ref) || ref.includes("..") || ref.includes("@{")) {
             throw new Error(`Invalid ${label}: ${ref}`);
         }
     }
+    async resolveGitCreateBaseBranch(cwd) {
+        const checkout = await getCheckoutStatusLite(cwd, { paseoHome: this.paseoHome });
+        if (!checkout.isGit) {
+            throw new Error("Cannot create a worktree outside a git repository");
+        }
+        const repoRoot = checkout.isPaseoOwnedWorktree ? checkout.mainRepoRoot : cwd;
+        const baseBranch = await resolveRepositoryDefaultBranch(repoRoot);
+        if (!baseBranch) {
+            throw new Error("Unable to resolve repository default branch");
+        }
+        return baseBranch;
+    }
     toCheckoutError(error) {
         if (error instanceof NotGitRepoError) {
-            return { code: 'NOT_GIT_REPO', message: error.message };
+            return { code: "NOT_GIT_REPO", message: error.message };
         }
         if (error instanceof MergeConflictError) {
-            return { code: 'MERGE_CONFLICT', message: error.message };
+            return { code: "MERGE_CONFLICT", message: error.message };
         }
         if (error instanceof MergeFromBaseConflictError) {
-            return { code: 'MERGE_CONFLICT', message: error.message };
+            return { code: "MERGE_CONFLICT", message: error.message };
         }
         if (error instanceof Error) {
-            return { code: 'UNKNOWN', message: error.message };
+            return { code: "UNKNOWN", message: error.message };
         }
-        return { code: 'UNKNOWN', message: String(error) };
+        return { code: "UNKNOWN", message: String(error) };
     }
     isPathWithinRoot(rootPath, candidatePath) {
         const resolvedRoot = resolve(rootPath);
@@ -2210,47 +2237,47 @@ export class Session {
         return resolvedCandidate.startsWith(resolvedRoot + sep);
     }
     async generateCommitMessage(cwd) {
-        const diff = await getCheckoutDiff(cwd, { mode: 'uncommitted', includeStructured: true }, { paseoHome: this.paseoHome });
+        const diff = await getCheckoutDiff(cwd, { mode: "uncommitted", includeStructured: true }, { paseoHome: this.paseoHome });
         const schema = z.object({
             message: z
                 .string()
                 .min(1)
                 .max(72)
-                .describe('Concise git commit message, imperative mood, no trailing period.'),
+                .describe("Concise git commit message, imperative mood, no trailing period."),
         });
         const fileList = diff.structured && diff.structured.length > 0
             ? [
-                'Files changed:',
+                "Files changed:",
                 ...diff.structured.map((file) => {
-                    const changeType = file.isNew ? 'A' : file.isDeleted ? 'D' : 'M';
-                    const status = file.status && file.status !== 'ok' ? ` [${file.status}]` : '';
+                    const changeType = file.isNew ? "A" : file.isDeleted ? "D" : "M";
+                    const status = file.status && file.status !== "ok" ? ` [${file.status}]` : "";
                     return `${changeType}\t${file.path}\t(+${file.additions} -${file.deletions})${status}`;
                 }),
-            ].join('\n')
-            : 'Files changed: (unknown)';
+            ].join("\n")
+            : "Files changed: (unknown)";
         const maxPatchChars = 120000;
         const patch = diff.diff.length > maxPatchChars
             ? `${diff.diff.slice(0, maxPatchChars)}\n\n... (diff truncated to ${maxPatchChars} chars)\n`
             : diff.diff;
         const prompt = [
-            'Write a concise git commit message for the changes below.',
+            "Write a concise git commit message for the changes below.",
             "Return JSON only with a single field 'message'.",
-            '',
+            "",
             fileList,
-            '',
-            patch.length > 0 ? patch : '(No diff available)',
-        ].join('\n');
+            "",
+            patch.length > 0 ? patch : "(No diff available)",
+        ].join("\n");
         try {
             const result = await generateStructuredAgentResponseWithFallback({
                 manager: this.agentManager,
                 cwd,
                 prompt,
                 schema,
-                schemaName: 'CommitMessage',
+                schemaName: "CommitMessage",
                 maxRetries: 2,
                 providers: DEFAULT_STRUCTURED_GENERATION_PROVIDERS,
                 agentConfigOverrides: {
-                    title: 'Commit generator',
+                    title: "Commit generator",
                     internal: true,
                 },
             });
@@ -2259,14 +2286,14 @@ export class Session {
         catch (error) {
             if (error instanceof StructuredAgentResponseError ||
                 error instanceof StructuredAgentFallbackError) {
-                return 'Update files';
+                return "Update files";
             }
             throw error;
         }
     }
     async generatePullRequestText(cwd, baseRef) {
         const diff = await getCheckoutDiff(cwd, {
-            mode: 'base',
+            mode: "base",
             baseRef,
             includeStructured: true,
         }, { paseoHome: this.paseoHome });
@@ -2276,37 +2303,37 @@ export class Session {
         });
         const fileList = diff.structured && diff.structured.length > 0
             ? [
-                'Files changed:',
+                "Files changed:",
                 ...diff.structured.map((file) => {
-                    const changeType = file.isNew ? 'A' : file.isDeleted ? 'D' : 'M';
-                    const status = file.status && file.status !== 'ok' ? ` [${file.status}]` : '';
+                    const changeType = file.isNew ? "A" : file.isDeleted ? "D" : "M";
+                    const status = file.status && file.status !== "ok" ? ` [${file.status}]` : "";
                     return `${changeType}\t${file.path}\t(+${file.additions} -${file.deletions})${status}`;
                 }),
-            ].join('\n')
-            : 'Files changed: (unknown)';
+            ].join("\n")
+            : "Files changed: (unknown)";
         const maxPatchChars = 200000;
         const patch = diff.diff.length > maxPatchChars
             ? `${diff.diff.slice(0, maxPatchChars)}\n\n... (diff truncated to ${maxPatchChars} chars)\n`
             : diff.diff;
         const prompt = [
-            'Write a pull request title and body for the changes below.',
+            "Write a pull request title and body for the changes below.",
             "Return JSON only with fields 'title' and 'body'.",
-            '',
+            "",
             fileList,
-            '',
-            patch.length > 0 ? patch : '(No diff available)',
-        ].join('\n');
+            "",
+            patch.length > 0 ? patch : "(No diff available)",
+        ].join("\n");
         try {
             return await generateStructuredAgentResponseWithFallback({
                 manager: this.agentManager,
                 cwd,
                 prompt,
                 schema,
-                schemaName: 'PullRequest',
+                schemaName: "PullRequest",
                 maxRetries: 2,
                 providers: DEFAULT_STRUCTURED_GENERATION_PROVIDERS,
                 agentConfigOverrides: {
-                    title: 'PR generator',
+                    title: "PR generator",
                     internal: true,
                 },
             });
@@ -2315,8 +2342,8 @@ export class Session {
             if (error instanceof StructuredAgentResponseError ||
                 error instanceof StructuredAgentFallbackError) {
                 return {
-                    title: 'Update changes',
-                    body: 'Automated PR generated by Paseo.',
+                    title: "Update changes",
+                    body: "Automated PR generated by Paseo.",
                 };
             }
             throw error;
@@ -2325,12 +2352,12 @@ export class Session {
     async ensureCleanWorkingTree(cwd) {
         const dirty = await this.isWorkingTreeDirty(cwd);
         if (dirty) {
-            throw new Error('Working directory has uncommitted changes. Commit or stash before switching branches.');
+            throw new Error("Working directory has uncommitted changes. Commit or stash before switching branches.");
         }
     }
     async isWorkingTreeDirty(cwd) {
         try {
-            const { stdout } = await execAsync('git status --porcelain', {
+            const { stdout } = await execAsync("git status --porcelain", {
                 cwd,
                 env: READ_ONLY_GIT_ENV,
             });
@@ -2341,14 +2368,14 @@ export class Session {
         }
     }
     async checkoutExistingBranch(cwd, branch) {
-        this.assertSafeGitRef(branch, 'branch');
+        this.assertSafeGitRef(branch, "branch");
         try {
             await execAsync(`git rev-parse --verify ${branch}`, { cwd });
         }
         catch (error) {
             throw new Error(`Branch not found: ${branch}`);
         }
-        const { stdout } = await execAsync('git rev-parse --abbrev-ref HEAD', {
+        const { stdout } = await execAsync("git rev-parse --abbrev-ref HEAD", {
             cwd,
         });
         const current = stdout.trim();
@@ -2360,7 +2387,7 @@ export class Session {
     }
     async createBranchFromBase(params) {
         const { cwd, baseBranch, newBranchName } = params;
-        this.assertSafeGitRef(baseBranch, 'base branch');
+        this.assertSafeGitRef(baseBranch, "base branch");
         try {
             await execAsync(`git rev-parse --verify ${baseBranch}`, { cwd });
         }
@@ -2391,97 +2418,97 @@ export class Session {
      * Handle set agent mode request
      */
     async handleSetAgentModeRequest(agentId, modeId, requestId) {
-        this.sessionLogger.info({ agentId, modeId, requestId }, 'session: set_agent_mode_request');
+        this.sessionLogger.info({ agentId, modeId, requestId }, "session: set_agent_mode_request");
         try {
             await this.agentManager.setAgentMode(agentId, modeId);
-            this.sessionLogger.info({ agentId, modeId, requestId }, 'session: set_agent_mode_request success');
+            this.sessionLogger.info({ agentId, modeId, requestId }, "session: set_agent_mode_request success");
             this.emit({
-                type: 'set_agent_mode_response',
+                type: "set_agent_mode_response",
                 payload: { requestId, agentId, accepted: true, error: null },
             });
         }
         catch (error) {
-            this.sessionLogger.error({ err: error, agentId, modeId, requestId }, 'session: set_agent_mode_request error');
+            this.sessionLogger.error({ err: error, agentId, modeId, requestId }, "session: set_agent_mode_request error");
             this.emit({
-                type: 'activity_log',
+                type: "activity_log",
                 payload: {
                     id: uuidv4(),
                     timestamp: new Date(),
-                    type: 'error',
+                    type: "error",
                     content: `Failed to set agent mode: ${error.message}`,
                 },
             });
             this.emit({
-                type: 'set_agent_mode_response',
+                type: "set_agent_mode_response",
                 payload: {
                     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",
                 },
             });
         }
     }
     async handleSetAgentModelRequest(agentId, modelId, requestId) {
-        this.sessionLogger.info({ agentId, modelId, requestId }, 'session: set_agent_model_request');
+        this.sessionLogger.info({ agentId, modelId, requestId }, "session: set_agent_model_request");
         try {
             await this.agentManager.setAgentModel(agentId, modelId);
-            this.sessionLogger.info({ agentId, modelId, requestId }, 'session: set_agent_model_request success');
+            this.sessionLogger.info({ agentId, modelId, requestId }, "session: set_agent_model_request success");
             this.emit({
-                type: 'set_agent_model_response',
+                type: "set_agent_model_response",
                 payload: { requestId, agentId, accepted: true, error: null },
             });
         }
         catch (error) {
-            this.sessionLogger.error({ err: error, agentId, modelId, requestId }, 'session: set_agent_model_request error');
+            this.sessionLogger.error({ err: error, agentId, modelId, requestId }, "session: set_agent_model_request error");
             this.emit({
-                type: 'activity_log',
+                type: "activity_log",
                 payload: {
                     id: uuidv4(),
                     timestamp: new Date(),
-                    type: 'error',
+                    type: "error",
                     content: `Failed to set agent model: ${error.message}`,
                 },
             });
             this.emit({
-                type: 'set_agent_model_response',
+                type: "set_agent_model_response",
                 payload: {
                     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",
                 },
             });
         }
     }
     async handleSetAgentThinkingRequest(agentId, thinkingOptionId, requestId) {
-        this.sessionLogger.info({ agentId, thinkingOptionId, requestId }, 'session: set_agent_thinking_request');
+        this.sessionLogger.info({ agentId, thinkingOptionId, requestId }, "session: set_agent_thinking_request");
         try {
             await this.agentManager.setAgentThinkingOption(agentId, thinkingOptionId);
-            this.sessionLogger.info({ agentId, thinkingOptionId, requestId }, 'session: set_agent_thinking_request success');
+            this.sessionLogger.info({ agentId, thinkingOptionId, requestId }, "session: set_agent_thinking_request success");
             this.emit({
-                type: 'set_agent_thinking_response',
+                type: "set_agent_thinking_response",
                 payload: { requestId, agentId, accepted: true, error: null },
             });
         }
         catch (error) {
-            this.sessionLogger.error({ err: error, agentId, thinkingOptionId, requestId }, 'session: set_agent_thinking_request error');
+            this.sessionLogger.error({ err: error, agentId, thinkingOptionId, requestId }, "session: set_agent_thinking_request error");
             this.emit({
-                type: 'activity_log',
+                type: "activity_log",
                 payload: {
                     id: uuidv4(),
                     timestamp: new Date(),
-                    type: 'error',
+                    type: "error",
                     content: `Failed to set agent thinking option: ${error.message}`,
                 },
             });
             this.emit({
-                type: 'set_agent_thinking_response',
+                type: "set_agent_thinking_response",
                 payload: {
                     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",
                 },
             });
         }
@@ -2495,7 +2522,7 @@ export class Session {
             await Promise.all(agentIds.map((id) => this.agentManager.clearAgentAttention(id)));
         }
         catch (error) {
-            this.sessionLogger.error({ err: error, agentIds }, 'Failed to clear agent attention');
+            this.sessionLogger.error({ err: error, agentIds }, "Failed to clear agent attention");
             // Don't throw - this is not critical
         }
     }
@@ -2519,7 +2546,7 @@ export class Session {
      */
     handleRegisterPushToken(token) {
         this.pushTokenStore.addToken(token);
-        this.sessionLogger.info('Registered push token');
+        this.sessionLogger.info("Registered push token");
     }
     /**
      * Handle list commands request for an agent
@@ -2533,7 +2560,7 @@ export class Session {
             if (agent?.session?.listCommands) {
                 const commands = await agent.session.listCommands();
                 this.emit({
-                    type: 'list_commands_response',
+                    type: "list_commands_response",
                     payload: {
                         agentId,
                         commands,
@@ -2555,7 +2582,7 @@ export class Session {
                 };
                 const commands = await this.agentManager.listDraftCommands(sessionConfig);
                 this.emit({
-                    type: 'list_commands_response',
+                    type: "list_commands_response",
                     payload: {
                         agentId,
                         commands,
@@ -2566,7 +2593,7 @@ export class Session {
                 return;
             }
             this.emit({
-                type: 'list_commands_response',
+                type: "list_commands_response",
                 payload: {
                     agentId,
                     commands: [],
@@ -2576,9 +2603,9 @@ export class Session {
             });
         }
         catch (error) {
-            this.sessionLogger.error({ err: error, agentId, draftConfig }, 'Failed to list commands');
+            this.sessionLogger.error({ err: error, agentId, draftConfig }, "Failed to list commands");
             this.emit({
-                type: 'list_commands_response',
+                type: "list_commands_response",
                 payload: {
                     agentId,
                     commands: [],
@@ -2598,13 +2625,13 @@ export class Session {
             this.sessionLogger.debug({ agentId }, `Permission response forwarded to agent ${agentId}`);
         }
         catch (error) {
-            this.sessionLogger.error({ err: error, agentId, requestId }, 'Failed to respond to permission');
+            this.sessionLogger.error({ err: error, agentId, requestId }, "Failed to respond to permission");
             this.emit({
-                type: 'activity_log',
+                type: "activity_log",
                 payload: {
                     id: uuidv4(),
                     timestamp: new Date(),
-                    type: 'error',
+                    type: "error",
                     content: `Failed to respond to permission: ${error.message}`,
                 },
             });
@@ -2618,7 +2645,7 @@ export class Session {
             const status = await getCheckoutStatus(resolvedCwd, { paseoHome: this.paseoHome });
             if (!status.isGit) {
                 this.emit({
-                    type: 'checkout_status_response',
+                    type: "checkout_status_response",
                     payload: {
                         cwd,
                         isGit: false,
@@ -2640,7 +2667,7 @@ export class Session {
             }
             if (status.isPaseoOwnedWorktree) {
                 this.emit({
-                    type: 'checkout_status_response',
+                    type: "checkout_status_response",
                     payload: {
                         cwd,
                         isGit: true,
@@ -2662,7 +2689,7 @@ export class Session {
                 return;
             }
             this.emit({
-                type: 'checkout_status_response',
+                type: "checkout_status_response",
                 payload: {
                     cwd,
                     isGit: true,
@@ -2683,7 +2710,7 @@ export class Session {
         }
         catch (error) {
             this.emit({
-                type: 'checkout_status_response',
+                type: "checkout_status_response",
                 payload: {
                     cwd,
                     isGit: false,
@@ -2714,7 +2741,7 @@ export class Session {
                     env: READ_ONLY_GIT_ENV,
                 });
                 this.emit({
-                    type: 'validate_branch_response',
+                    type: "validate_branch_response",
                     payload: {
                         exists: true,
                         resolvedRef: branchName,
@@ -2735,7 +2762,7 @@ export class Session {
                     env: READ_ONLY_GIT_ENV,
                 });
                 this.emit({
-                    type: 'validate_branch_response',
+                    type: "validate_branch_response",
                     payload: {
                         exists: true,
                         resolvedRef: `origin/${branchName}`,
@@ -2751,7 +2778,7 @@ export class Session {
             }
             // Branch not found anywhere
             this.emit({
-                type: 'validate_branch_response',
+                type: "validate_branch_response",
                 payload: {
                     exists: false,
                     resolvedRef: null,
@@ -2763,7 +2790,7 @@ export class Session {
         }
         catch (error) {
             this.emit({
-                type: 'validate_branch_response',
+                type: "validate_branch_response",
                 payload: {
                     exists: false,
                     resolvedRef: null,
@@ -2780,7 +2807,7 @@ export class Session {
             const resolvedCwd = expandTilde(cwd);
             const branches = await listBranchSuggestions(resolvedCwd, { query, limit });
             this.emit({
-                type: 'branch_suggestions_response',
+                type: "branch_suggestions_response",
                 payload: {
                     branches,
                     error: null,
@@ -2790,7 +2817,7 @@ export class Session {
         }
         catch (error) {
             this.emit({
-                type: 'branch_suggestions_response',
+                type: "branch_suggestions_response",
                 payload: {
                     branches: [],
                     error: error instanceof Error ? error.message : String(error),
@@ -2815,12 +2842,12 @@ export class Session {
                     homeDir: process.env.HOME ?? homedir(),
                     query,
                     limit,
-                })).map((path) => ({ path, kind: 'directory' }));
+                })).map((path) => ({ path, kind: "directory" }));
             const directories = entries
-                .filter((entry) => entry.kind === 'directory')
+                .filter((entry) => entry.kind === "directory")
                 .map((entry) => entry.path);
             this.emit({
-                type: 'directory_suggestions_response',
+                type: "directory_suggestions_response",
                 payload: {
                     directories,
                     entries,
@@ -2831,7 +2858,7 @@ export class Session {
         }
         catch (error) {
             this.emit({
-                type: 'directory_suggestions_response',
+                type: "directory_suggestions_response",
                 payload: {
                     directories: [],
                     entries: [],
@@ -2842,17 +2869,17 @@ export class Session {
         }
     }
     normalizeCheckoutDiffCompare(compare) {
-        if (compare.mode === 'uncommitted') {
-            return { mode: 'uncommitted' };
+        if (compare.mode === "uncommitted") {
+            return { mode: "uncommitted" };
         }
         const trimmedBaseRef = compare.baseRef?.trim();
-        return trimmedBaseRef ? { mode: 'base', baseRef: trimmedBaseRef } : { mode: 'base' };
+        return trimmedBaseRef ? { mode: "base", baseRef: trimmedBaseRef } : { mode: "base" };
     }
     buildCheckoutDiffTargetKey(cwd, compare) {
         return JSON.stringify([
             cwd,
             compare.mode,
-            compare.mode === 'base' ? (compare.baseRef ?? '') : '',
+            compare.mode === "base" ? (compare.baseRef ?? "") : "",
         ]);
     }
     closeCheckoutDiffWatchTarget(target) {
@@ -2887,7 +2914,7 @@ export class Session {
     }
     async resolveCheckoutGitDir(cwd) {
         try {
-            const { stdout } = await execAsync('git rev-parse --absolute-git-dir', {
+            const { stdout } = await execAsync("git rev-parse --absolute-git-dir", {
                 cwd,
                 env: READ_ONLY_GIT_ENV,
             });
@@ -2898,9 +2925,150 @@ export class Session {
             return null;
         }
     }
+    async resolveWorkspaceGitRefsRoot(gitDir) {
+        try {
+            const commonDir = (await readFile(join(gitDir, "commondir"), "utf8")).trim();
+            if (commonDir.length > 0) {
+                return resolve(gitDir, commonDir);
+            }
+        }
+        catch {
+            // Regular repos do not have a commondir file.
+        }
+        return gitDir;
+    }
+    closeWorkspaceGitWatchTarget(target) {
+        if (target.debounceTimer) {
+            clearTimeout(target.debounceTimer);
+            target.debounceTimer = null;
+        }
+        for (const watcher of target.watchers) {
+            watcher.close();
+        }
+        target.watchers = [];
+    }
+    removeWorkspaceGitWatchTarget(cwd) {
+        const workspaceId = normalizePersistedWorkspaceId(cwd);
+        const target = this.workspaceGitWatchTargets.get(workspaceId);
+        if (!target) {
+            return;
+        }
+        this.closeWorkspaceGitWatchTarget(target);
+        this.workspaceGitWatchTargets.delete(workspaceId);
+    }
+    workspaceGitDescriptorFingerprint(workspace) {
+        if (!workspace) {
+            return WORKSPACE_GIT_WATCH_REMOVED_FINGERPRINT;
+        }
+        return JSON.stringify([
+            workspace.name,
+            workspace.diffStat ? [workspace.diffStat.additions, workspace.diffStat.deletions] : null,
+        ]);
+    }
+    shouldSkipWorkspaceGitWatchUpdate(workspaceId, workspace) {
+        const target = this.workspaceGitWatchTargets.get(workspaceId);
+        if (!target) {
+            return false;
+        }
+        const nextFingerprint = this.workspaceGitDescriptorFingerprint(workspace);
+        if (target.latestFingerprint === nextFingerprint) {
+            return true;
+        }
+        target.latestFingerprint = nextFingerprint;
+        return false;
+    }
+    rememberWorkspaceGitWatchFingerprint(workspaceId, workspace) {
+        const target = this.workspaceGitWatchTargets.get(workspaceId);
+        if (!target) {
+            return;
+        }
+        target.latestFingerprint = this.workspaceGitDescriptorFingerprint(workspace);
+    }
+    primeWorkspaceGitWatchFingerprints(workspaces) {
+        for (const workspace of workspaces) {
+            this.rememberWorkspaceGitWatchFingerprint(workspace.id, workspace);
+        }
+    }
+    scheduleWorkspaceGitWatchRefresh(target) {
+        if (target.debounceTimer) {
+            clearTimeout(target.debounceTimer);
+        }
+        target.debounceTimer = setTimeout(() => {
+            target.debounceTimer = null;
+            void this.refreshWorkspaceGitWatchTarget(target);
+        }, WORKSPACE_GIT_WATCH_DEBOUNCE_MS);
+    }
+    async refreshWorkspaceGitWatchTarget(target) {
+        if (target.refreshPromise) {
+            target.refreshQueued = true;
+            return;
+        }
+        target.refreshPromise = (async () => {
+            do {
+                target.refreshQueued = false;
+                await this.emitWorkspaceUpdateForCwd(target.cwd, {
+                    dedupeGitState: true,
+                });
+            } while (target.refreshQueued);
+        })();
+        try {
+            await target.refreshPromise;
+        }
+        finally {
+            target.refreshPromise = null;
+        }
+    }
+    async ensureWorkspaceGitWatchTarget(cwd) {
+        const workspaceId = normalizePersistedWorkspaceId(cwd);
+        if (this.workspaceGitWatchTargets.has(workspaceId)) {
+            return;
+        }
+        const gitDir = await this.resolveCheckoutGitDir(cwd);
+        if (!gitDir) {
+            return;
+        }
+        const refsRoot = await this.resolveWorkspaceGitRefsRoot(gitDir);
+        const target = {
+            cwd: workspaceId,
+            watchers: [],
+            debounceTimer: null,
+            refreshPromise: null,
+            refreshQueued: false,
+            latestFingerprint: null,
+        };
+        for (const watchPath of new Set([join(gitDir, "HEAD"), join(refsRoot, "refs", "heads")])) {
+            let watcher = null;
+            try {
+                watcher = watch(watchPath, { recursive: false }, () => {
+                    this.scheduleWorkspaceGitWatchRefresh(target);
+                });
+            }
+            catch (error) {
+                this.sessionLogger.warn({ err: error, cwd, watchPath }, "Failed to start workspace git watcher");
+            }
+            if (!watcher) {
+                continue;
+            }
+            watcher.on("error", (error) => {
+                this.sessionLogger.warn({ err: error, cwd, watchPath }, "Workspace git watcher error");
+            });
+            target.watchers.push(watcher);
+        }
+        if (target.watchers.length === 0) {
+            return;
+        }
+        this.workspaceGitWatchTargets.set(workspaceId, target);
+    }
+    async syncWorkspaceGitWatchTarget(cwd, options) {
+        if (!options.isGit) {
+            this.removeWorkspaceGitWatchTarget(cwd);
+            return;
+        }
+        await this.ensureWorkspaceGitWatchTarget(cwd);
+    }
     async resolveCheckoutWatchRoot(cwd) {
         try {
-            const { stdout } = await execAsync('git rev-parse --path-format=absolute --show-toplevel', {
+            const { stdout } = await execAsync("git rev-parse --path-format=absolute --show-toplevel", {
                 cwd,
                 env: READ_ONLY_GIT_ENV,
             });
@@ -2926,7 +3094,7 @@ export class Session {
         }
         for (const subscriptionId of target.subscriptions) {
             this.emit({
-                type: 'checkout_diff_update',
+                type: "checkout_diff_update",
                 payload: {
                     subscriptionId,
                     ...snapshot,
@@ -3019,7 +3187,7 @@ export class Session {
             watchPaths.add(gitDir);
         }
         let hasRecursiveRepoCoverage = false;
-        const allowRecursiveRepoWatch = process.platform !== 'linux';
+        const allowRecursiveRepoWatch = process.platform !== "linux";
         for (const watchPath of watchPaths) {
             const shouldTryRecursive = watchPath === repoWatchPath && allowRecursiveRepoWatch;
             const createWatcher = (recursive) => watch(watchPath, { recursive }, () => {
@@ -3040,21 +3208,21 @@ export class Session {
                 if (shouldTryRecursive) {
                     try {
                         watcher = createWatcher(false);
-                        this.sessionLogger.warn({ err: error, watchPath, cwd, compare }, 'Checkout diff recursive watch unavailable; using non-recursive fallback');
+                        this.sessionLogger.warn({ err: error, watchPath, cwd, compare }, "Checkout diff recursive watch unavailable; using non-recursive fallback");
                     }
                     catch (fallbackError) {
-                        this.sessionLogger.warn({ err: fallbackError, watchPath, cwd, compare }, 'Failed to start checkout diff watcher');
+                        this.sessionLogger.warn({ err: fallbackError, watchPath, cwd, compare }, "Failed to start checkout diff watcher");
                     }
                 }
                 else {
-                    this.sessionLogger.warn({ err: error, watchPath, cwd, compare }, 'Failed to start checkout diff watcher');
+                    this.sessionLogger.warn({ err: error, watchPath, cwd, compare }, "Failed to start checkout diff watcher");
                 }
             }
             if (!watcher) {
                 continue;
             }
-            watcher.on('error', (error) => {
-                this.sessionLogger.warn({ err: error, watchPath, cwd, compare }, 'Checkout diff watcher error');
+            watcher.on("error", (error) => {
+                this.sessionLogger.warn({ err: error, watchPath, cwd, compare }, "Checkout diff watcher error");
             });
             target.watchers.push(watcher);
             if (watchPath === repoWatchPath && watcherIsRecursive) {
@@ -3070,8 +3238,8 @@ export class Session {
                 cwd,
                 compare,
                 intervalMs: CHECKOUT_DIFF_FALLBACK_REFRESH_MS,
-                reason: target.watchers.length === 0 ? 'no_watchers' : 'missing_recursive_repo_root_coverage',
-            }, 'Checkout diff watchers unavailable; using timed refresh fallback');
+                reason: target.watchers.length === 0 ? "no_watchers" : "missing_recursive_repo_root_coverage",
+            }, "Checkout diff watchers unavailable; using timed refresh fallback");
         }
         this.checkoutDiffTargets.set(targetKey, target);
         return target;
@@ -3092,7 +3260,7 @@ export class Session {
         target.latestPayload = snapshot;
         target.latestFingerprint = this.checkoutDiffSnapshotFingerprint(snapshot);
         this.emit({
-            type: 'subscribe_checkout_diff_response',
+            type: "subscribe_checkout_diff_response",
             payload: {
                 subscriptionId: msg.subscriptionId,
                 ...snapshot,
@@ -3115,12 +3283,12 @@ export class Session {
     async handleCheckoutCommitRequest(msg) {
         const { cwd, requestId } = msg;
         try {
-            let message = msg.message?.trim() ?? '';
+            let message = msg.message?.trim() ?? "";
             if (!message) {
                 message = await this.generateCommitMessage(cwd);
             }
             if (!message) {
-                throw new Error('Commit message is required');
+                throw new Error("Commit message is required");
             }
             await commitChanges(cwd, {
                 message,
@@ -3128,7 +3296,7 @@ export class Session {
             });
             this.scheduleCheckoutDiffRefreshForCwd(cwd);
             this.emit({
-                type: 'checkout_commit_response',
+                type: "checkout_commit_response",
                 payload: {
                     cwd,
                     success: true,
@@ -3139,7 +3307,7 @@ export class Session {
         }
         catch (error) {
             this.emit({
-                type: 'checkout_commit_response',
+                type: "checkout_commit_response",
                 payload: {
                     cwd,
                     success: false,
@@ -3155,13 +3323,13 @@ export class Session {
             const status = await getCheckoutStatus(cwd, { paseoHome: this.paseoHome });
             if (!status.isGit) {
                 try {
-                    await execAsync('git rev-parse --is-inside-work-tree', {
+                    await execAsync("git rev-parse --is-inside-work-tree", {
                         cwd,
                         env: READ_ONLY_GIT_ENV,
                     });
                 }
                 catch (error) {
-                    const details = typeof error?.stderr === 'string'
+                    const details = typeof error?.stderr === "string"
                         ? String(error.stderr).trim()
                         : error instanceof Error
                             ? error.message
@@ -3170,28 +3338,28 @@ export class Session {
                 }
             }
             if (msg.requireCleanTarget) {
-                const { stdout } = await execAsync('git status --porcelain', {
+                const { stdout } = await execAsync("git status --porcelain", {
                     cwd,
                     env: READ_ONLY_GIT_ENV,
                 });
                 if (stdout.trim().length > 0) {
-                    throw new Error('Working directory has uncommitted changes.');
+                    throw new Error("Working directory has uncommitted changes.");
                 }
             }
             let baseRef = msg.baseRef ?? (status.isGit ? status.baseRef : null);
             if (!baseRef) {
-                throw new Error('Base branch is required for merge');
+                throw new Error("Base branch is required for merge");
             }
-            if (baseRef.startsWith('origin/')) {
-                baseRef = baseRef.slice('origin/'.length);
+            if (baseRef.startsWith("origin/")) {
+                baseRef = baseRef.slice("origin/".length);
             }
             await mergeToBase(cwd, {
                 baseRef,
-                mode: msg.strategy === 'squash' ? 'squash' : 'merge',
+                mode: msg.strategy === "squash" ? "squash" : "merge",
             }, { paseoHome: this.paseoHome });
             this.scheduleCheckoutDiffRefreshForCwd(cwd);
             this.emit({
-                type: 'checkout_merge_response',
+                type: "checkout_merge_response",
                 payload: {
                     cwd,
                     success: true,
@@ -3202,7 +3370,7 @@ export class Session {
         }
         catch (error) {
             this.emit({
-                type: 'checkout_merge_response',
+                type: "checkout_merge_response",
                 payload: {
                     cwd,
                     success: false,
@@ -3216,12 +3384,12 @@ export class Session {
         const { cwd, requestId } = msg;
         try {
             if (msg.requireCleanTarget ?? true) {
-                const { stdout } = await execAsync('git status --porcelain', {
+                const { stdout } = await execAsync("git status --porcelain", {
                     cwd,
                     env: READ_ONLY_GIT_ENV,
                 });
                 if (stdout.trim().length > 0) {
-                    throw new Error('Working directory has uncommitted changes.');
+                    throw new Error("Working directory has uncommitted changes.");
                 }
             }
             await mergeFromBase(cwd, {
@@ -3230,7 +3398,7 @@ export class Session {
             });
             this.scheduleCheckoutDiffRefreshForCwd(cwd);
             this.emit({
-                type: 'checkout_merge_from_base_response',
+                type: "checkout_merge_from_base_response",
                 payload: {
                     cwd,
                     success: true,
@@ -3241,7 +3409,7 @@ export class Session {
         }
         catch (error) {
             this.emit({
-                type: 'checkout_merge_from_base_response',
+                type: "checkout_merge_from_base_response",
                 payload: {
                     cwd,
                     success: false,
@@ -3256,7 +3424,7 @@ export class Session {
         try {
             await pushCurrentBranch(cwd);
             this.emit({
-                type: 'checkout_push_response',
+                type: "checkout_push_response",
                 payload: {
                     cwd,
                     success: true,
@@ -3267,7 +3435,7 @@ export class Session {
         }
         catch (error) {
             this.emit({
-                type: 'checkout_push_response',
+                type: "checkout_push_response",
                 payload: {
                     cwd,
                     success: false,
@@ -3280,8 +3448,8 @@ export class Session {
     async handleCheckoutPrCreateRequest(msg) {
         const { cwd, requestId } = msg;
         try {
-            let title = msg.title?.trim() ?? '';
-            let body = msg.body?.trim() ?? '';
+            let title = msg.title?.trim() ?? "";
+            let body = msg.body?.trim() ?? "";
             if (!title || !body) {
                 const generated = await this.generatePullRequestText(cwd, msg.baseRef);
                 if (!title)
@@ -3295,7 +3463,7 @@ export class Session {
                 base: msg.baseRef,
             });
             this.emit({
-                type: 'checkout_pr_create_response',
+                type: "checkout_pr_create_response",
                 payload: {
                     cwd,
                     url: result.url ?? null,
@@ -3307,7 +3475,7 @@ export class Session {
         }
         catch (error) {
             this.emit({
-                type: 'checkout_pr_create_response',
+                type: "checkout_pr_create_response",
                 payload: {
                     cwd,
                     url: null,
@@ -3323,7 +3491,7 @@ export class Session {
         try {
             const prStatus = await getPullRequestStatus(cwd);
             this.emit({
-                type: 'checkout_pr_status_response',
+                type: "checkout_pr_status_response",
                 payload: {
                     cwd,
                     status: prStatus.status,
@@ -3335,7 +3503,7 @@ export class Session {
         }
         catch (error) {
             this.emit({
-                type: 'checkout_pr_status_response',
+                type: "checkout_pr_status_response",
                 payload: {
                     cwd,
                     status: null,
@@ -3351,10 +3519,10 @@ export class Session {
         const cwd = msg.repoRoot ?? msg.cwd;
         if (!cwd) {
             this.emit({
-                type: 'paseo_worktree_list_response',
+                type: "paseo_worktree_list_response",
                 payload: {
                     worktrees: [],
-                    error: { code: 'UNKNOWN', message: 'cwd or repoRoot is required' },
+                    error: { code: "UNKNOWN", message: "cwd or repoRoot is required" },
                     requestId,
                 },
             });
@@ -3363,7 +3531,7 @@ export class Session {
         try {
             const worktrees = await listPaseoWorktrees({ cwd, paseoHome: this.paseoHome });
             this.emit({
-                type: 'paseo_worktree_list_response',
+                type: "paseo_worktree_list_response",
                 payload: {
                     worktrees: worktrees.map((entry) => ({
                         worktreePath: entry.path,
@@ -3378,7 +3546,7 @@ export class Session {
         }
         catch (error) {
             this.emit({
-                type: 'paseo_worktree_list_response',
+                type: "paseo_worktree_list_response",
                 payload: {
                     worktrees: [],
                     error: this.toCheckoutError(error),
@@ -3443,7 +3611,7 @@ export class Session {
         }
         for (const agentId of removedAgents) {
             this.emit({
-                type: 'agent_deleted',
+                type: "agent_deleted",
                 payload: {
                     agentId,
                     requestId: options.requestId,
@@ -3460,7 +3628,7 @@ export class Session {
         try {
             if (!targetPath) {
                 if (!repoRoot || !msg.branchName) {
-                    throw new Error('worktreePath or repoRoot+branchName is required');
+                    throw new Error("worktreePath or repoRoot+branchName is required");
                 }
                 const worktrees = await listPaseoWorktrees({ cwd: repoRoot, paseoHome: this.paseoHome });
                 const match = worktrees.find((entry) => entry.branchName === msg.branchName);
@@ -3474,13 +3642,13 @@ export class Session {
             });
             if (!ownership.allowed) {
                 this.emit({
-                    type: 'paseo_worktree_archive_response',
+                    type: "paseo_worktree_archive_response",
                     payload: {
                         success: false,
                         removedAgents: [],
                         error: {
-                            code: 'NOT_ALLOWED',
-                            message: 'Worktree is not a Paseo-owned worktree',
+                            code: "NOT_ALLOWED",
+                            message: "Worktree is not a Paseo-owned worktree",
                         },
                         requestId,
                     },
@@ -3489,7 +3657,7 @@ export class Session {
             }
             repoRoot = ownership.repoRoot ?? repoRoot ?? null;
             if (!repoRoot) {
-                throw new Error('Unable to resolve repo root for worktree');
+                throw new Error("Unable to resolve repo root for worktree");
             }
             const removedAgents = await this.archivePaseoWorktree({
                 targetPath,
@@ -3497,7 +3665,7 @@ export class Session {
                 requestId,
             });
             this.emit({
-                type: 'paseo_worktree_archive_response',
+                type: "paseo_worktree_archive_response",
                 payload: {
                     success: true,
                     removedAgents,
@@ -3508,7 +3676,7 @@ export class Session {
         }
         catch (error) {
             this.emit({
-                type: 'paseo_worktree_archive_response',
+                type: "paseo_worktree_archive_response",
                 payload: {
                     success: false,
                     removedAgents: [],
@@ -3522,31 +3690,31 @@ export class Session {
      * Handle read-only file explorer requests scoped to a workspace cwd
      */
     async handleFileExplorerRequest(request) {
-        const { cwd: workspaceCwd, path: requestedPath = '.', mode, requestId } = request;
+        const { cwd: workspaceCwd, path: requestedPath = ".", mode, requestId } = request;
         const cwd = workspaceCwd.trim();
         if (!cwd) {
             this.emit({
-                type: 'file_explorer_response',
+                type: "file_explorer_response",
                 payload: {
                     cwd: workspaceCwd,
                     path: requestedPath,
                     mode,
                     directory: null,
                     file: null,
-                    error: 'cwd is required',
+                    error: "cwd is required",
                     requestId,
                 },
             });
             return;
         }
         try {
-            if (mode === 'list') {
+            if (mode === "list") {
                 const directory = await listDirectoryEntries({
                     root: cwd,
                     relativePath: requestedPath,
                 });
                 this.emit({
-                    type: 'file_explorer_response',
+                    type: "file_explorer_response",
                     payload: {
                         cwd,
                         path: directory.path,
@@ -3564,7 +3732,7 @@ export class Session {
                     relativePath: requestedPath,
                 });
                 this.emit({
-                    type: 'file_explorer_response',
+                    type: "file_explorer_response",
                     payload: {
                         cwd,
                         path: file.path,
@@ -3580,7 +3748,7 @@ export class Session {
         catch (error) {
             this.sessionLogger.error({ err: error, cwd, path: requestedPath }, `Failed to fulfill file explorer request for workspace ${cwd}`);
             this.emit({
-                type: 'file_explorer_response',
+                type: "file_explorer_response",
                 payload: {
                     cwd,
                     path: requestedPath,
@@ -3601,7 +3769,7 @@ export class Session {
         try {
             const icon = await getProjectIcon(cwd);
             this.emit({
-                type: 'project_icon_response',
+                type: "project_icon_response",
                 payload: {
                     cwd,
                     icon,
@@ -3612,7 +3780,7 @@ export class Session {
         }
         catch (error) {
             this.emit({
-                type: 'project_icon_response',
+                type: "project_icon_response",
                 payload: {
                     cwd,
                     icon: null,
@@ -3630,7 +3798,7 @@ export class Session {
         const cwd = workspaceCwd.trim();
         if (!cwd) {
             this.emit({
-                type: 'file_download_token_response',
+                type: "file_download_token_response",
                 payload: {
                     cwd: workspaceCwd,
                     path: requestedPath,
@@ -3638,7 +3806,7 @@ export class Session {
                     fileName: null,
                     mimeType: null,
                     size: null,
-                    error: 'cwd is required',
+                    error: "cwd is required",
                     requestId,
                 },
             });
@@ -3658,7 +3826,7 @@ export class Session {
                 size: info.size,
             });
             this.emit({
-                type: 'file_download_token_response',
+                type: "file_download_token_response",
                 payload: {
                     cwd,
                     path: info.path,
@@ -3674,7 +3842,7 @@ export class Session {
         catch (error) {
             this.sessionLogger.error({ err: error, cwd, path: requestedPath }, `Failed to issue download token for workspace ${cwd}`);
             this.emit({
-                type: 'file_download_token_response',
+                type: "file_download_token_response",
                 payload: {
                     cwd,
                     path: requestedPath,
@@ -3713,7 +3881,7 @@ export class Session {
     async resolveAgentIdentifier(identifier) {
         const trimmed = identifier.trim();
         if (!trimmed) {
-            return { ok: false, error: 'Agent identifier cannot be empty' };
+            return { ok: false, error: "Agent identifier cannot be empty" };
         }
         const stored = await this.agentStorage.list();
         const storedRecords = stored.filter((record) => !record.internal);
@@ -3737,7 +3905,7 @@ export class Session {
                 error: `Agent identifier "${trimmed}" is ambiguous (${prefixMatches
                     .slice(0, 5)
                     .map((id) => id.slice(0, 8))
-                    .join(', ')}${prefixMatches.length > 5 ? ', …' : ''})`,
+                    .join(", ")}${prefixMatches.length > 5 ? ", …" : ""})`,
             };
         }
         const titleMatches = storedRecords.filter((record) => record.title === trimmed);
@@ -3750,7 +3918,7 @@ export class Session {
                 error: `Agent title "${trimmed}" is ambiguous (${titleMatches
                     .slice(0, 5)
                     .map((r) => r.id.slice(0, 8))
-                    .join(', ')}${titleMatches.length > 5 ? ', …' : ''})`,
+                    .join(", ")}${titleMatches.length > 5 ? ", …" : ""})`,
             };
         }
         return { ok: false, error: `Agent not found: ${trimmed}` };
@@ -3767,7 +3935,7 @@ export class Session {
         return this.buildStoredAgentPayload(record);
     }
     normalizeFetchAgentsSort(sort) {
-        const fallback = [{ key: 'updated_at', direction: 'desc' }];
+        const fallback = [{ key: "updated_at", direction: "desc" }];
         if (!sort || sort.length === 0) {
             return fallback;
         }
@@ -3785,42 +3953,42 @@ export class Session {
     getStatusPriority(agent) {
         const attentionReason = agent.attentionReason ?? null;
         const hasPendingPermission = (agent.pendingPermissions?.length ?? 0) > 0;
-        if (hasPendingPermission || attentionReason === 'permission') {
+        if (hasPendingPermission || attentionReason === "permission") {
             return 0;
         }
-        if (agent.status === 'error' || attentionReason === 'error') {
+        if (agent.status === "error" || attentionReason === "error") {
             return 1;
         }
-        if (agent.status === 'running') {
+        if (agent.status === "running") {
             return 2;
         }
-        if (agent.status === 'initializing') {
+        if (agent.status === "initializing") {
             return 3;
         }
         return 4;
     }
     getFetchAgentsSortValue(entry, key) {
         switch (key) {
-            case 'status_priority':
+            case "status_priority":
                 return this.getStatusPriority(entry.agent);
-            case 'created_at':
+            case "created_at":
                 return Date.parse(entry.agent.createdAt);
-            case 'updated_at':
+            case "updated_at":
                 return Date.parse(entry.agent.updatedAt);
-            case 'title':
-                return entry.agent.title?.toLocaleLowerCase() ?? '';
+            case "title":
+                return entry.agent.title?.toLocaleLowerCase() ?? "";
         }
     }
     getFetchAgentsSortValueFromAgent(agent, key) {
         switch (key) {
-            case 'status_priority':
+            case "status_priority":
                 return this.getStatusPriority(agent);
-            case 'created_at':
+            case "created_at":
                 return Date.parse(agent.createdAt);
-            case 'updated_at':
+            case "updated_at":
                 return Date.parse(agent.updatedAt);
-            case 'title':
-                return agent.title?.toLocaleLowerCase() ?? '';
+            case "title":
+                return agent.title?.toLocaleLowerCase() ?? "";
         }
     }
     compareSortValues(left, right) {
@@ -3833,7 +4001,7 @@ export class Session {
         if (right === null) {
             return 1;
         }
-        if (typeof left === 'number' && typeof right === 'number') {
+        if (typeof left === "number" && typeof right === "number") {
             return left < right ? -1 : 1;
         }
         return String(left).localeCompare(String(right));
@@ -3846,7 +4014,7 @@ export class Session {
             if (base === 0) {
                 continue;
             }
-            return spec.direction === 'asc' ? base : -base;
+            return spec.direction === "asc" ? base : -base;
         }
         return left.id.localeCompare(right.id);
     }
@@ -3859,48 +4027,48 @@ export class Session {
             sort,
             values,
             id: entry.agent.id,
-        }), 'utf8').toString('base64url');
+        }), "utf8").toString("base64url");
     }
     decodeFetchAgentsCursor(cursor, sort) {
         let parsed;
         try {
-            parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+            parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
         }
         catch {
-            throw new SessionRequestError('invalid_cursor', 'Invalid fetch_agents cursor');
+            throw new SessionRequestError("invalid_cursor", "Invalid fetch_agents cursor");
         }
-        if (!parsed || typeof parsed !== 'object') {
-            throw new SessionRequestError('invalid_cursor', 'Invalid fetch_agents cursor');
+        if (!parsed || typeof parsed !== "object") {
+            throw new SessionRequestError("invalid_cursor", "Invalid fetch_agents cursor");
         }
         const payload = parsed;
-        if (!Array.isArray(payload.sort) || typeof payload.id !== 'string') {
-            throw new SessionRequestError('invalid_cursor', 'Invalid fetch_agents cursor');
+        if (!Array.isArray(payload.sort) || typeof payload.id !== "string") {
+            throw new SessionRequestError("invalid_cursor", "Invalid fetch_agents cursor");
         }
-        if (!payload.values || typeof payload.values !== 'object') {
-            throw new SessionRequestError('invalid_cursor', 'Invalid fetch_agents cursor');
+        if (!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');
+                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');
+            if ((key !== "status_priority" &&
+                key !== "created_at" &&
+                key !== "updated_at" &&
+                key !== "title") ||
+                (direction !== "asc" && direction !== "desc")) {
+                throw new SessionRequestError("invalid_cursor", "Invalid fetch_agents cursor");
             }
             cursorSort.push({ key, direction });
         }
         if (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');
+            throw new SessionRequestError("invalid_cursor", "fetch_agents cursor does not match current sort");
         }
         return {
             sort: cursorSort,
@@ -3916,7 +4084,7 @@ export class Session {
             if (base === 0) {
                 continue;
             }
-            return spec.direction === 'asc' ? base : -base;
+            return spec.direction === "asc" ? base : -base;
         }
         return agent.id.localeCompare(cursor.id);
     }
@@ -3982,19 +4150,19 @@ export class Session {
     }
     deriveWorkspaceStateBucket(agent) {
         const pendingPermissionCount = agent.pendingPermissions?.length ?? 0;
-        if (pendingPermissionCount > 0 || agent.attentionReason === 'permission') {
-            return 'needs_input';
+        if (pendingPermissionCount > 0 || agent.attentionReason === "permission") {
+            return "needs_input";
         }
-        if (agent.status === 'error' || agent.attentionReason === 'error') {
-            return 'failed';
+        if (agent.status === "error" || agent.attentionReason === "error") {
+            return "failed";
         }
-        if (agent.status === 'running' || agent.status === 'initializing') {
-            return 'running';
+        if (agent.status === "running" || agent.status === "initializing") {
+            return "running";
         }
         if (agent.requiresAttention) {
-            return 'attention';
+            return "attention";
         }
-        return 'done';
+        return "done";
     }
     accumulateLatestActivityAt(current, agent) {
         const candidateRaw = agent.lastUserMessageAt ?? agent.updatedAt;
@@ -4036,10 +4204,10 @@ export class Session {
             projectId: workspace.projectId,
             projectDisplayName: resolvedProjectRecord?.displayName ?? workspace.projectId,
             projectRootPath: resolvedProjectRecord?.rootPath ?? workspace.cwd,
-            projectKind: resolvedProjectRecord?.kind ?? 'non_git',
+            projectKind: resolvedProjectRecord?.kind ?? "non_git",
             workspaceKind: workspace.kind,
             name: displayName,
-            status: 'done',
+            status: "done",
             activityAt: null,
             diffStat,
         };
@@ -4080,7 +4248,7 @@ export class Session {
         return this.listWorkspaceDescriptorsSnapshot();
     }
     normalizeFetchWorkspacesSort(sort) {
-        const fallback = [{ key: 'activity_at', direction: 'desc' }];
+        const fallback = [{ key: "activity_at", direction: "desc" }];
         if (!sort || sort.length === 0) {
             return fallback;
         }
@@ -4097,13 +4265,13 @@ export class Session {
     }
     getFetchWorkspacesSortValue(workspace, key) {
         switch (key) {
-            case 'status_priority':
+            case "status_priority":
                 return this.workspaceStatePriority[workspace.status];
-            case 'activity_at':
+            case "activity_at":
                 return workspace.activityAt ? Date.parse(workspace.activityAt) : null;
-            case 'name':
+            case "name":
                 return workspace.name.toLocaleLowerCase();
-            case 'project_id':
+            case "project_id":
                 return workspace.projectId.toLocaleLowerCase();
         }
     }
@@ -4115,7 +4283,7 @@ export class Session {
             if (base === 0) {
                 continue;
             }
-            return spec.direction === 'asc' ? base : -base;
+            return spec.direction === "asc" ? base : -base;
         }
         return left.id.localeCompare(right.id);
     }
@@ -4128,48 +4296,48 @@ export class Session {
             sort,
             values,
             id: entry.id,
-        }), 'utf8').toString('base64url');
+        }), "utf8").toString("base64url");
     }
     decodeFetchWorkspacesCursor(cursor, sort) {
         let parsed;
         try {
-            parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+            parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
         }
         catch {
-            throw new SessionRequestError('invalid_cursor', 'Invalid fetch_workspaces cursor');
+            throw new SessionRequestError("invalid_cursor", "Invalid fetch_workspaces cursor");
         }
-        if (!parsed || typeof parsed !== 'object') {
-            throw new SessionRequestError('invalid_cursor', 'Invalid fetch_workspaces cursor');
+        if (!parsed || typeof parsed !== "object") {
+            throw new SessionRequestError("invalid_cursor", "Invalid fetch_workspaces cursor");
         }
         const payload = parsed;
-        if (!Array.isArray(payload.sort) || typeof payload.id !== 'string') {
-            throw new SessionRequestError('invalid_cursor', 'Invalid fetch_workspaces cursor');
+        if (!Array.isArray(payload.sort) || typeof payload.id !== "string") {
+            throw new SessionRequestError("invalid_cursor", "Invalid fetch_workspaces cursor");
         }
-        if (!payload.values || typeof payload.values !== 'object') {
-            throw new SessionRequestError('invalid_cursor', 'Invalid fetch_workspaces cursor');
+        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');
+                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');
+            if ((key !== "status_priority" &&
+                key !== "activity_at" &&
+                key !== "name" &&
+                key !== "project_id") ||
+                (direction !== "asc" && direction !== "desc")) {
+                throw new SessionRequestError("invalid_cursor", "Invalid fetch_workspaces cursor");
             }
             cursorSort.push({ key, direction });
         }
         if (cursorSort.length !== sort.length ||
             cursorSort.some((entry, index) => entry.key !== sort[index]?.key || entry.direction !== sort[index]?.direction)) {
-            throw new SessionRequestError('invalid_cursor', 'fetch_workspaces cursor does not match current sort');
+            throw new SessionRequestError("invalid_cursor", "fetch_workspaces cursor does not match current sort");
         }
         return {
             sort: cursorSort,
@@ -4185,7 +4353,7 @@ export class Session {
             if (base === 0) {
                 continue;
             }
-            return spec.direction === 'asc' ? base : -base;
+            return spec.direction === "asc" ? base : -base;
         }
         return workspace.id.localeCompare(cursor.id);
     }
@@ -4241,12 +4409,12 @@ export class Session {
     }
     bufferOrEmitWorkspaceUpdate(subscription, payload) {
         if (subscription.isBootstrapping) {
-            const workspaceId = payload.kind === 'upsert' ? payload.workspace.id : payload.id;
+            const workspaceId = payload.kind === "upsert" ? payload.workspace.id : payload.id;
             subscription.pendingUpdatesByWorkspaceId.set(workspaceId, payload);
             return;
         }
         this.emit({
-            type: 'workspace_update',
+            type: "workspace_update",
             payload,
         });
     }
@@ -4259,19 +4427,20 @@ export class Session {
         const pending = Array.from(subscription.pendingUpdatesByWorkspaceId.values());
         subscription.pendingUpdatesByWorkspaceId.clear();
         for (const payload of pending) {
-            if (payload.kind === 'upsert') {
+            if (payload.kind === "upsert") {
                 const snapshotLatestActivity = options?.snapshotLatestActivityByWorkspaceId?.get(payload.workspace.id);
-                if (typeof snapshotLatestActivity === 'number') {
+                if (typeof snapshotLatestActivity === "number") {
                     const updateLatestActivity = payload.workspace.activityAt
                         ? Date.parse(payload.workspace.activityAt)
                         : Number.NEGATIVE_INFINITY;
-                    if (!Number.isNaN(updateLatestActivity) && updateLatestActivity <= snapshotLatestActivity) {
+                    if (!Number.isNaN(updateLatestActivity) &&
+                        updateLatestActivity <= snapshotLatestActivity) {
                         continue;
                     }
                 }
             }
             this.emit({
-                type: 'workspace_update',
+                type: "workspace_update",
                 payload,
             });
         }
@@ -4280,19 +4449,62 @@ export class Session {
         const workspaceId = normalizePersistedWorkspaceId(cwd);
         return (await this.reconcileWorkspaceRecord(workspaceId)).workspace;
     }
+    async registerPendingWorktreeWorkspace(options) {
+        const workspaceId = normalizePersistedWorkspaceId(options.worktreePath);
+        const basePlacement = await this.buildProjectPlacement(options.repoRoot);
+        const placement = {
+            ...basePlacement,
+            checkout: {
+                cwd: workspaceId,
+                isGit: true,
+                currentBranch: options.branchName,
+                remoteUrl: basePlacement.checkout.remoteUrl,
+                isPaseoOwnedWorktree: true,
+                mainRepoRoot: options.repoRoot,
+            },
+        };
+        const now = new Date().toISOString();
+        const existingWorkspace = await this.workspaceRegistry.get(workspaceId);
+        const existingProject = await this.projectRegistry.get(placement.projectKey);
+        const nextProjectRecord = this.buildPersistedProjectRecord({
+            workspaceId,
+            placement,
+            createdAt: existingProject?.createdAt ?? now,
+            updatedAt: now,
+        });
+        const nextWorkspaceRecord = this.buildPersistedWorkspaceRecord({
+            workspaceId,
+            placement,
+            createdAt: existingWorkspace?.createdAt ?? now,
+            updatedAt: now,
+        });
+        await this.projectRegistry.upsert(nextProjectRecord);
+        await this.workspaceRegistry.upsert(nextWorkspaceRecord);
+        await this.syncWorkspaceGitWatchTarget(workspaceId, {
+            isGit: placement.checkout.isGit,
+        });
+        if (existingWorkspace &&
+            !existingWorkspace.archivedAt &&
+            existingWorkspace.projectId !== nextWorkspaceRecord.projectId) {
+            await this.archiveProjectRecordIfEmpty(existingWorkspace.projectId, now);
+        }
+        return nextWorkspaceRecord;
+    }
     async archiveWorkspaceRecord(workspaceId, archivedAt) {
         const existing = await this.workspaceRegistry.get(workspaceId);
         if (!existing || existing.archivedAt) {
+            this.removeWorkspaceGitWatchTarget(workspaceId);
             return;
         }
         const nextArchivedAt = archivedAt ?? new Date().toISOString();
         await this.workspaceRegistry.archive(workspaceId, nextArchivedAt);
+        this.removeWorkspaceGitWatchTarget(workspaceId);
         const siblingWorkspaces = (await this.workspaceRegistry.list()).filter((workspace) => workspace.projectId === existing.projectId && !workspace.archivedAt);
         if (siblingWorkspaces.length === 0) {
             await this.projectRegistry.archive(existing.projectId, nextArchivedAt);
         }
     }
-    async emitWorkspaceUpdateForCwd(cwd) {
+    async emitWorkspaceUpdateForCwd(cwd, options) {
         const subscription = this.workspaceUpdatesSubscription;
         if (!subscription) {
             return;
@@ -4304,16 +4516,24 @@ export class Session {
         const workspaceIdsToEmit = new Set([workspaceId, ...changedWorkspaceIds]);
         for (const nextWorkspaceId of workspaceIdsToEmit) {
             const workspace = descriptorsByWorkspaceId.get(nextWorkspaceId);
-            if (!workspace || !this.matchesWorkspaceFilter({ workspace, filter: subscription.filter })) {
+            const nextWorkspace = workspace && this.matchesWorkspaceFilter({ workspace, filter: subscription.filter })
+                ? workspace
+                : null;
+            if (options?.dedupeGitState &&
+                this.shouldSkipWorkspaceGitWatchUpdate(nextWorkspaceId, nextWorkspace)) {
+                continue;
+            }
+            this.rememberWorkspaceGitWatchFingerprint(nextWorkspaceId, nextWorkspace);
+            if (!nextWorkspace) {
                 this.bufferOrEmitWorkspaceUpdate(subscription, {
-                    kind: 'remove',
+                    kind: "remove",
                     id: nextWorkspaceId,
                 });
                 continue;
             }
             this.bufferOrEmitWorkspaceUpdate(subscription, {
-                kind: 'upsert',
-                workspace,
+                kind: "upsert",
+                workspace: nextWorkspace,
             });
         }
     }
@@ -4335,16 +4555,20 @@ export class Session {
         const descriptorsByWorkspaceId = new Map(all.map((entry) => [entry.id, entry]));
         for (const workspaceId of uniqueWorkspaceCwds) {
             const workspace = descriptorsByWorkspaceId.get(workspaceId);
-            if (!workspace || !this.matchesWorkspaceFilter({ workspace, filter: subscription.filter })) {
+            const nextWorkspace = workspace && this.matchesWorkspaceFilter({ workspace, filter: subscription.filter })
+                ? workspace
+                : null;
+            this.rememberWorkspaceGitWatchFingerprint(workspaceId, nextWorkspace);
+            if (!nextWorkspace) {
                 this.bufferOrEmitWorkspaceUpdate(subscription, {
-                    kind: 'remove',
+                    kind: "remove",
                     id: workspaceId,
                 });
                 continue;
             }
             this.bufferOrEmitWorkspaceUpdate(subscription, {
-                kind: 'upsert',
-                workspace,
+                kind: "upsert",
+                workspace: nextWorkspace,
             });
         }
     }
@@ -4373,7 +4597,7 @@ export class Session {
                 }
             }
             this.emit({
-                type: 'fetch_agents_response',
+                type: "fetch_agents_response",
                 payload: {
                     requestId: request.requestId,
                     ...(subscriptionId ? { subscriptionId } : {}),
@@ -4388,11 +4612,11 @@ export class Session {
             if (subscriptionId && this.agentUpdatesSubscription?.subscriptionId === subscriptionId) {
                 this.agentUpdatesSubscription = null;
             }
-            const code = error instanceof SessionRequestError ? error.code : 'fetch_agents_failed';
-            const message = error instanceof Error ? error.message : 'Failed to fetch agents';
-            this.sessionLogger.error({ err: error }, 'Failed to handle fetch_agents_request');
+            const code = error instanceof SessionRequestError ? error.code : "fetch_agents_failed";
+            const message = error instanceof Error ? error.message : "Failed to fetch agents";
+            this.sessionLogger.error({ err: error }, "Failed to handle fetch_agents_request");
             this.emit({
-                type: 'rpc_error',
+                type: "rpc_error",
                 payload: {
                     requestId: request.requestId,
                     requestType: request.type,
@@ -4419,6 +4643,7 @@ export class Session {
                 };
             }
             const payload = await this.listFetchWorkspacesEntries(request);
+            this.primeWorkspaceGitWatchFingerprints(payload.entries);
             const snapshotLatestActivityByWorkspaceId = new Map();
             for (const entry of payload.entries) {
                 const parsedLatestActivity = entry.activityAt
@@ -4429,7 +4654,7 @@ export class Session {
                 }
             }
             this.emit({
-                type: 'fetch_workspaces_response',
+                type: "fetch_workspaces_response",
                 payload: {
                     requestId: request.requestId,
                     ...(subscriptionId ? { subscriptionId } : {}),
@@ -4444,11 +4669,11 @@ export class Session {
             if (subscriptionId && this.workspaceUpdatesSubscription?.subscriptionId === subscriptionId) {
                 this.workspaceUpdatesSubscription = null;
             }
-            const code = error instanceof SessionRequestError ? error.code : 'fetch_workspaces_failed';
-            const message = error instanceof Error ? error.message : 'Failed to fetch workspaces';
-            this.sessionLogger.error({ err: error }, 'Failed to handle fetch_workspaces_request');
+            const code = error instanceof SessionRequestError ? error.code : "fetch_workspaces_failed";
+            const message = error instanceof Error ? error.message : "Failed to fetch workspaces";
+            this.sessionLogger.error({ err: error }, "Failed to handle fetch_workspaces_request");
             this.emit({
-                type: 'rpc_error',
+                type: "rpc_error",
                 payload: {
                     requestId: request.requestId,
                     requestType: request.type,
@@ -4464,7 +4689,7 @@ export class Session {
             await this.emitWorkspaceUpdateForCwd(workspace.cwd);
             const descriptor = await this.describeWorkspaceRecord(workspace);
             this.emit({
-                type: 'open_project_response',
+                type: "open_project_response",
                 payload: {
                     requestId: request.requestId,
                     workspace: descriptor,
@@ -4473,10 +4698,10 @@ export class Session {
             });
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : 'Failed to open project';
-            this.sessionLogger.error({ err: error, cwd: request.cwd }, 'Failed to open project');
+            const message = error instanceof Error ? error.message : "Failed to open project";
+            this.sessionLogger.error({ err: error, cwd: request.cwd }, "Failed to open project");
             this.emit({
-                type: 'open_project_response',
+                type: "open_project_response",
                 payload: {
                     requestId: request.requestId,
                     workspace: null,
@@ -4485,20 +4710,123 @@ export class Session {
             });
         }
     }
+    async handleCreatePaseoWorktreeRequest(request) {
+        try {
+            const checkout = await getCheckoutStatusLite(request.cwd, { paseoHome: this.paseoHome });
+            if (!checkout.isGit) {
+                throw new Error("Create worktree requires a git repository");
+            }
+            const repoRoot = checkout.isPaseoOwnedWorktree ? checkout.mainRepoRoot : request.cwd;
+            const baseBranch = await resolveRepositoryDefaultBranch(repoRoot);
+            if (!baseBranch) {
+                throw new Error("Unable to resolve repository default branch");
+            }
+            const normalizedSlug = request.worktreeSlug ? slugify(request.worktreeSlug) : uuidv4();
+            const validation = validateBranchSlug(normalizedSlug);
+            if (!validation.valid) {
+                throw new Error(`Invalid worktree name: ${validation.error}`);
+            }
+            const worktreePath = await computeWorktreePath(repoRoot, normalizedSlug, this.paseoHome);
+            const workspace = await this.registerPendingWorktreeWorkspace({
+                repoRoot,
+                worktreePath,
+                branchName: normalizedSlug,
+            });
+            const descriptor = await this.describeWorkspaceRecord(workspace);
+            this.emit({
+                type: "create_paseo_worktree_response",
+                payload: {
+                    workspace: descriptor,
+                    error: null,
+                    setupTerminalId: null,
+                    requestId: request.requestId,
+                },
+            });
+            void this.createPaseoWorktreeInBackground({
+                requestCwd: request.cwd,
+                repoRoot,
+                baseBranch,
+                slug: normalizedSlug,
+                worktreePath,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Failed to create worktree";
+            this.sessionLogger.error({ err: error, cwd: request.cwd, worktreeSlug: request.worktreeSlug }, "Failed to create worktree");
+            this.emit({
+                type: "create_paseo_worktree_response",
+                payload: {
+                    workspace: null,
+                    error: message,
+                    setupTerminalId: null,
+                    requestId: request.requestId,
+                },
+            });
+        }
+    }
+    async createPaseoWorktreeInBackground(options) {
+        let setupTerminalId = null;
+        try {
+            await createAgentWorktree({
+                cwd: options.repoRoot,
+                branchName: options.slug,
+                baseBranch: options.baseBranch,
+                worktreeSlug: options.slug,
+                paseoHome: this.paseoHome,
+            });
+            const setupCommands = getWorktreeSetupCommands(options.worktreePath);
+            if (setupCommands.length > 0 && this.terminalManager) {
+                const runtimeEnv = await resolveWorktreeRuntimeEnv({
+                    worktreePath: options.worktreePath,
+                    branchName: options.slug,
+                    repoRootPath: options.repoRoot,
+                });
+                this.terminalManager.registerCwdEnv({
+                    cwd: options.worktreePath,
+                    env: runtimeEnv,
+                });
+                const terminal = await this.terminalManager.createTerminal({
+                    cwd: options.worktreePath,
+                    name: `setup-${options.slug}`,
+                    env: runtimeEnv,
+                });
+                setupTerminalId = terminal.id;
+                for (const command of setupCommands) {
+                    terminal.send({
+                        type: "input",
+                        data: `${command}\r`,
+                    });
+                }
+            }
+        }
+        catch (error) {
+            this.sessionLogger.error({
+                err: error,
+                cwd: options.requestCwd,
+                repoRoot: options.repoRoot,
+                worktreeSlug: options.slug,
+                worktreePath: options.worktreePath,
+                setupTerminalId,
+            }, "Background worktree creation failed");
+        }
+        finally {
+            await this.emitWorkspaceUpdateForCwd(options.worktreePath);
+        }
+    }
     async handleArchiveWorkspaceRequest(request) {
         try {
             const existing = await this.workspaceRegistry.get(request.workspaceId);
             if (!existing) {
                 throw new Error(`Workspace not found: ${request.workspaceId}`);
             }
-            if (existing.kind === 'worktree') {
-                throw new Error('Use worktree archive for Paseo worktrees');
+            if (existing.kind === "worktree") {
+                throw new Error("Use worktree archive for Paseo worktrees");
             }
             const archivedAt = new Date().toISOString();
             await this.archiveWorkspaceRecord(request.workspaceId, archivedAt);
             await this.emitWorkspaceUpdateForCwd(existing.cwd);
             this.emit({
-                type: 'archive_workspace_response',
+                type: "archive_workspace_response",
                 payload: {
                     requestId: request.requestId,
                     workspaceId: request.workspaceId,
@@ -4508,10 +4836,10 @@ export class Session {
             });
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : 'Failed to archive workspace';
-            this.sessionLogger.error({ err: error, workspaceId: request.workspaceId }, 'Failed to archive workspace');
+            const message = error instanceof Error ? error.message : "Failed to archive workspace";
+            this.sessionLogger.error({ err: error, workspaceId: request.workspaceId }, "Failed to archive workspace");
             this.emit({
-                type: 'archive_workspace_response',
+                type: "archive_workspace_response",
                 payload: {
                     requestId: request.requestId,
                     workspaceId: request.workspaceId,
@@ -4525,7 +4853,7 @@ export class Session {
         const resolved = await this.resolveAgentIdentifier(agentIdOrIdentifier);
         if (!resolved.ok) {
             this.emit({
-                type: 'fetch_agent_response',
+                type: "fetch_agent_response",
                 payload: { requestId, agent: null, project: null, error: resolved.error },
             });
             return;
@@ -4533,7 +4861,7 @@ export class Session {
         const agent = await this.getAgentPayloadById(resolved.agentId);
         if (!agent) {
             this.emit({
-                type: 'fetch_agent_response',
+                type: "fetch_agent_response",
                 payload: {
                     requestId,
                     agent: null,
@@ -4545,18 +4873,18 @@ export class Session {
         }
         const project = await this.buildProjectPlacement(agent.cwd);
         this.emit({
-            type: 'fetch_agent_response',
+            type: "fetch_agent_response",
             payload: { requestId, agent, project, error: null },
         });
     }
     async handleFetchAgentTimelineRequest(msg) {
-        const direction = msg.direction ?? (msg.cursor ? 'after' : 'tail');
-        const projection = msg.projection ?? 'projected';
+        const direction = msg.direction ?? (msg.cursor ? "after" : "tail");
+        const projection = msg.projection ?? "projected";
         const requestedLimit = msg.limit;
-        const limit = requestedLimit ?? (direction === 'after' ? 0 : undefined);
-        const shouldLimitByProjectedWindow = projection === 'canonical' &&
-            direction === 'tail' &&
-            typeof requestedLimit === 'number' &&
+        const limit = requestedLimit ?? (direction === "after" ? 0 : undefined);
+        const shouldLimitByProjectedWindow = projection === "canonical" &&
+            direction === "tail" &&
+            typeof requestedLimit === "number" &&
             requestedLimit > 0;
         const cursor = msg.cursor
             ? {
@@ -4570,7 +4898,7 @@ export class Session {
             let timeline = this.agentManager.fetchTimeline(msg.agentId, {
                 direction,
                 cursor,
-                limit: shouldLimitByProjectedWindow && typeof requestedLimit === 'number'
+                limit: shouldLimitByProjectedWindow && typeof requestedLimit === "number"
                     ? Math.max(1, Math.floor(requestedLimit))
                     : limit,
             });
@@ -4596,7 +4924,7 @@ export class Session {
                     const startsAtLoadedBoundary = firstLoadedRow != null &&
                         firstSelectedRow != null &&
                         firstSelectedRow.seq === firstLoadedRow.seq;
-                    const boundaryIsAssistantChunk = startsAtLoadedBoundary && firstLoadedRow.item.type === 'assistant_message';
+                    const boundaryIsAssistantChunk = startsAtLoadedBoundary && firstLoadedRow.item.type === "assistant_message";
                     if (!needsMoreProjectedEntries && !boundaryIsAssistantChunk) {
                         break;
                     }
@@ -4636,7 +4964,7 @@ export class Session {
                 entries = projectTimelineRows(timeline.rows, snapshot.provider, projection);
             }
             this.emit({
-                type: 'fetch_agent_timeline_response',
+                type: "fetch_agent_timeline_response",
                 payload: {
                     requestId: msg.requestId,
                     agentId: msg.agentId,
@@ -4658,16 +4986,16 @@ export class Session {
             });
         }
         catch (error) {
-            this.sessionLogger.error({ err: error, agentId: msg.agentId }, 'Failed to handle fetch_agent_timeline_request');
+            this.sessionLogger.error({ err: error, agentId: msg.agentId }, "Failed to handle fetch_agent_timeline_request");
             this.emit({
-                type: 'fetch_agent_timeline_response',
+                type: "fetch_agent_timeline_response",
                 payload: {
                     requestId: msg.requestId,
                     agentId: msg.agentId,
                     agent: null,
                     direction,
                     projection,
-                    epoch: '',
+                    epoch: "",
                     reset: false,
                     staleCursor: false,
                     gap: false,
@@ -4686,7 +5014,7 @@ export class Session {
         const resolved = await this.resolveAgentIdentifier(msg.agentId);
         if (!resolved.ok) {
             this.emit({
-                type: 'send_agent_message_response',
+                type: "send_agent_message_response",
                 payload: {
                     requestId: msg.requestId,
                     agentId: msg.agentId,
@@ -4707,13 +5035,13 @@ export class Session {
                 });
             }
             catch (error) {
-                this.sessionLogger.error({ err: error, agentId }, 'Failed to record user message for send_agent_message_request');
+                this.sessionLogger.error({ err: error, agentId }, "Failed to record user message for send_agent_message_request");
             }
             const prompt = this.buildAgentPrompt(msg.text, msg.images);
             const started = this.startAgentStream(agentId, prompt);
             if (!started.ok) {
                 this.emit({
-                    type: 'send_agent_message_response',
+                    type: "send_agent_message_response",
                     payload: {
                         requestId: msg.requestId,
                         agentId,
@@ -4725,18 +5053,18 @@ export class Session {
             }
             const startAbort = new AbortController();
             const startTimeoutMs = 15000;
-            const startTimeout = setTimeout(() => startAbort.abort('timeout'), startTimeoutMs);
+            const startTimeout = setTimeout(() => startAbort.abort("timeout"), startTimeoutMs);
             try {
                 await this.agentManager.waitForAgentRunStart(agentId, { signal: startAbort.signal });
             }
             catch (error) {
                 const message = error instanceof Error
                     ? error.message
-                    : typeof error === 'string'
+                    : typeof error === "string"
                         ? error
-                        : 'Unknown error';
+                        : "Unknown error";
                 this.emit({
-                    type: 'send_agent_message_response',
+                    type: "send_agent_message_response",
                     payload: {
                         requestId: msg.requestId,
                         agentId,
@@ -4750,7 +5078,7 @@ export class Session {
                 clearTimeout(startTimeout);
             }
             this.emit({
-                type: 'send_agent_message_response',
+                type: "send_agent_message_response",
                 payload: {
                     requestId: msg.requestId,
                     agentId,
@@ -4760,9 +5088,13 @@ export class Session {
             });
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : typeof error === 'string' ? error : 'Unknown error';
+            const message = error instanceof Error
+                ? error.message
+                : typeof error === "string"
+                    ? error
+                    : "Unknown error";
             this.emit({
-                type: 'send_agent_message_response',
+                type: "send_agent_message_response",
                 payload: {
                     requestId: msg.requestId,
                     agentId: resolved.agentId,
@@ -4776,10 +5108,10 @@ export class Session {
         const resolved = await this.resolveAgentIdentifier(agentIdOrIdentifier);
         if (!resolved.ok) {
             this.emit({
-                type: 'wait_for_finish_response',
+                type: "wait_for_finish_response",
                 payload: {
                     requestId,
-                    status: 'error',
+                    status: "error",
                     final: null,
                     error: resolved.error,
                     lastMessage: null,
@@ -4793,10 +5125,10 @@ export class Session {
             const record = await this.agentStorage.get(agentId);
             if (!record || record.internal) {
                 this.emit({
-                    type: 'wait_for_finish_response',
+                    type: "wait_for_finish_response",
                     payload: {
                         requestId,
-                        status: 'error',
+                        status: "error",
                         final: null,
                         error: `Agent not found: ${agentId}`,
                         lastMessage: null,
@@ -4805,22 +5137,22 @@ export class Session {
                 return;
             }
             const final = this.buildStoredAgentPayload(record);
-            const status = record.attentionReason === 'permission'
-                ? 'permission'
-                : record.lastStatus === 'error'
-                    ? 'error'
-                    : 'idle';
+            const status = record.attentionReason === "permission"
+                ? "permission"
+                : record.lastStatus === "error"
+                    ? "error"
+                    : "idle";
             this.emit({
-                type: 'wait_for_finish_response',
+                type: "wait_for_finish_response",
                 payload: { requestId, status, final, error: null, lastMessage: null },
             });
             return;
         }
         const abortController = new AbortController();
-        const hasTimeout = typeof timeoutMs === 'number' && timeoutMs > 0;
+        const hasTimeout = typeof timeoutMs === "number" && timeoutMs > 0;
         const timeoutHandle = hasTimeout
             ? setTimeout(() => {
-                abortController.abort('timeout');
+                abortController.abort("timeout");
             }, timeoutMs)
             : null;
         try {
@@ -4831,28 +5163,32 @@ 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 = result.permission
+                ? "permission"
+                : result.status === "error"
+                    ? "error"
+                    : "idle";
             this.emit({
-                type: 'wait_for_finish_response',
+                type: "wait_for_finish_response",
                 payload: { requestId, status, final, error: null, lastMessage: result.lastMessage },
             });
         }
         catch (error) {
             const isAbort = error instanceof Error &&
-                (error.name === 'AbortError' || error.message.toLowerCase().includes('aborted'));
+                (error.name === "AbortError" || error.message.toLowerCase().includes("aborted"));
             if (!isAbort) {
                 const message = error instanceof Error
                     ? error.message
-                    : typeof error === 'string'
+                    : typeof error === "string"
                         ? error
-                        : 'Unknown error';
-                this.sessionLogger.error({ err: error, agentId }, 'wait_for_finish_request failed');
+                        : "Unknown error";
+                this.sessionLogger.error({ err: error, agentId }, "wait_for_finish_request failed");
                 const final = await this.getAgentPayloadById(agentId);
                 this.emit({
-                    type: 'wait_for_finish_response',
+                    type: "wait_for_finish_response",
                     payload: {
                         requestId,
-                        status: 'error',
+                        status: "error",
                         final,
                         error: message,
                         lastMessage: null,
@@ -4865,8 +5201,8 @@ export class Session {
                 throw new Error(`Agent ${agentId} disappeared while waiting`);
             }
             this.emit({
-                type: 'wait_for_finish_response',
-                payload: { requestId, status: 'timeout', final, error: null, lastMessage: null },
+                type: "wait_for_finish_response",
+                payload: { requestId, status: "timeout", final, error: null, lastMessage: null },
             });
         }
         finally {
@@ -4880,31 +5216,30 @@ export class Session {
      */
     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');
+            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';
+        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');
+                throw new Error("Voice mode is enabled but the voice turn controller is not running");
             }
-            const chunkBytes = Buffer.byteLength(msg.audio, 'base64');
+            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');
+                }, "Received first voice_audio_chunk for active voice mode");
             }
             const now = Date.now();
-            if (this.voiceInputChunkCount % 50 === 0 ||
-                now - this.voiceInputWindowStartedAt >= 1000) {
+            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');
+                }, "Voice input chunk summary");
                 this.voiceInputWindowStartedAt = now;
                 this.voiceInputChunkCount = 0;
                 this.voiceInputBytes = 0;
@@ -4915,8 +5250,8 @@ export class Session {
             });
             return;
         }
-        const chunkBuffer = Buffer.from(msg.audio, 'base64');
-        const isPCMChunk = chunkFormat.toLowerCase().includes('pcm');
+        const chunkBuffer = Buffer.from(msg.audio, "base64");
+        const isPCMChunk = chunkFormat.toLowerCase().includes("pcm");
         if (!this.audioBuffer) {
             this.audioBuffer = {
                 chunks: [],
@@ -4928,7 +5263,7 @@ export class Session {
         // 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,
+                oldFormat: this.audioBuffer.isPCM ? "pcm" : this.audioBuffer.format,
                 newFormat: chunkFormat,
             }, `Audio format changed mid-stream, flushing current buffer`);
             const finalized = this.finalizeBufferedAudio();
@@ -4984,7 +5319,7 @@ export class Session {
             const wavBuffer = convertPCMToWavBuffer(pcmBuffer, PCM_SAMPLE_RATE, PCM_CHANNELS, PCM_BITS_PER_SAMPLE);
             return {
                 audio: wavBuffer,
-                format: 'audio/wav',
+                format: "audio/wav",
             };
         }
         return {
@@ -4993,7 +5328,7 @@ export class Session {
         };
     }
     async processCompletedAudio(audio, format) {
-        if (this.processingPhase === 'transcribing') {
+        if (this.processingPhase === "transcribing") {
             this.sessionLogger.debug({ phase: this.processingPhase, segmentCount: this.pendingAudioSegments.length + 1 }, `Buffering audio segment (phase: ${this.processingPhase})`);
             this.pendingAudioSegments.push({
                 audio,
@@ -5019,7 +5354,7 @@ export class Session {
         await this.processAudio(audio, format);
     }
     async flushPendingAudioSegments(reason) {
-        if (this.processingPhase === 'transcribing' || this.pendingAudioSegments.length === 0) {
+        if (this.processingPhase === "transcribing" || this.pendingAudioSegments.length === 0) {
             return;
         }
         const pendingSegments = [...this.pendingAudioSegments];
@@ -5034,21 +5369,21 @@ export class Session {
      * Process audio through STT and then LLM
      */
     async processAudio(audio, format) {
-        this.setPhase('transcribing');
+        this.setPhase("transcribing");
         this.emit({
-            type: 'activity_log',
+            type: "activity_log",
             payload: {
                 id: uuidv4(),
                 timestamp: new Date(),
-                type: 'system',
-                content: 'Transcribing audio...',
+                type: "system",
+                content: "Transcribing audio...",
             },
         });
         try {
             const requestId = uuidv4();
             const result = await this.sttManager.transcribe(audio, format, {
                 requestId,
-                label: this.isVoiceMode ? 'voice' : 'buffered',
+                label: this.isVoiceMode ? "voice" : "buffered",
             });
             const transcriptText = result.text.trim();
             this.sessionLogger.info({
@@ -5056,7 +5391,7 @@ export class Session {
                 isVoiceMode: this.isVoiceMode,
                 transcriptLength: transcriptText.length,
                 transcript: transcriptText,
-            }, 'Transcription result');
+            }, "Transcription result");
             await this.handleTranscriptionResultPayload({
                 text: result.text,
                 language: result.language,
@@ -5070,15 +5405,15 @@ export class Session {
             });
         }
         catch (error) {
-            this.setPhase('idle');
-            this.clearSpeechInProgress('transcription error');
-            await this.flushPendingAudioSegments('transcription error');
+            this.setPhase("idle");
+            this.clearSpeechInProgress("transcription error");
+            await this.flushPendingAudioSegments("transcription error");
             this.emit({
-                type: 'activity_log',
+                type: "activity_log",
                 payload: {
                     id: uuidv4(),
                     timestamp: new Date(),
-                    type: 'error',
+                    type: "error",
                     content: `Transcription error: ${error.message}`,
                 },
             });
@@ -5088,7 +5423,7 @@ export class Session {
     async handleTranscriptionResultPayload(result) {
         const transcriptText = result.text.trim();
         this.emit({
-            type: 'transcription_result',
+            type: "transcription_result",
             payload: {
                 text: result.text,
                 ...(result.language ? { language: result.language } : {}),
@@ -5104,21 +5439,21 @@ export class Session {
             },
         });
         if (!transcriptText) {
-            this.sessionLogger.debug('Empty transcription (false positive), not aborting');
-            this.setPhase('idle');
-            this.clearSpeechInProgress('empty transcription');
-            await this.flushPendingAudioSegments('empty transcription');
+            this.sessionLogger.debug("Empty transcription (false positive), not aborting");
+            this.setPhase("idle");
+            this.clearSpeechInProgress("empty transcription");
+            await this.flushPendingAudioSegments("empty transcription");
             return;
         }
         // Has content - abort any in-progress stream now
         this.createAbortController();
         if (result.debugRecordingPath) {
             this.emit({
-                type: 'activity_log',
+                type: "activity_log",
                 payload: {
                     id: uuidv4(),
                     timestamp: new Date(),
-                    type: 'system',
+                    type: "system",
                     content: `Saved input audio: ${result.debugRecordingPath}`,
                     metadata: {
                         recordingPath: result.debugRecordingPath,
@@ -5129,11 +5464,11 @@ export class Session {
             });
         }
         this.emit({
-            type: 'activity_log',
+            type: "activity_log",
             payload: {
                 id: uuidv4(),
                 timestamp: new Date(),
-                type: 'transcript',
+                type: "transcript",
                 content: result.text,
                 metadata: {
                     ...(result.language ? { language: result.language } : {}),
@@ -5141,23 +5476,23 @@ export class Session {
                 },
             },
         });
-        this.clearSpeechInProgress('transcription complete');
-        this.setPhase('idle');
+        this.clearSpeechInProgress("transcription complete");
+        this.setPhase("idle");
         if (!this.isVoiceMode) {
-            this.sessionLogger.debug({ requestId: result.requestId }, 'Skipping voice agent processing because voice mode is disabled');
-            await this.flushPendingAudioSegments('voice mode disabled');
+            this.sessionLogger.debug({ requestId: result.requestId }, "Skipping voice agent processing because voice mode is disabled");
+            await this.flushPendingAudioSegments("voice mode disabled");
             return;
         }
         const agentId = this.voiceModeAgentId;
         if (!agentId) {
-            this.sessionLogger.warn({ requestId: result.requestId }, 'Skipping voice agent processing because no agent is currently voice-enabled');
-            await this.flushPendingAudioSegments('no active voice agent');
+            this.sessionLogger.warn({ requestId: result.requestId }, "Skipping voice agent processing because no agent is currently voice-enabled");
+            await this.flushPendingAudioSegments("no active voice agent");
             return;
         }
         // Route voice utterances through the same send path as regular text input:
         // interrupt-if-running, record message, then start a new stream.
         await this.handleSendAgentMessage(agentId, result.text);
-        await this.flushPendingAudioSegments('transcription complete');
+        await this.flushPendingAudioSegments("transcription complete");
     }
     registerVoiceBridgeForAgent(agentId) {
         this.registerVoiceSpeakHandler?.(agentId, async ({ text, signal }) => {
@@ -5165,16 +5500,16 @@ export class Session {
                 agentId,
                 textLength: text.length,
                 preview: text.slice(0, 160),
-            }, 'Voice speak tool call received by session handler');
+            }, "Voice speak tool call received by session handler");
             const abortSignal = signal ?? this.abortController.signal;
             await this.ttsManager.generateAndWaitForPlayback(text, (msg) => this.emit(msg), abortSignal, true);
-            this.sessionLogger.info({ agentId, textLength: text.length }, 'Voice speak tool call finished playback');
+            this.sessionLogger.info({ agentId, textLength: text.length }, "Voice speak tool call finished playback");
             this.emit({
-                type: 'activity_log',
+                type: "activity_log",
                 payload: {
                     id: uuidv4(),
                     timestamp: new Date(),
-                    type: 'assistant',
+                    type: "assistant",
                     content: text,
                 },
             });
@@ -5191,24 +5526,24 @@ export class Session {
     async handleAbort() {
         this.sessionLogger.info({ phase: this.processingPhase }, `Abort request, phase: ${this.processingPhase}`);
         this.abortController.abort();
-        this.ttsManager.cancelPendingPlaybacks('abort request');
+        this.ttsManager.cancelPendingPlaybacks("abort request");
         // Voice abort should always interrupt active agent output immediately.
         if (this.isVoiceMode && this.voiceModeAgentId) {
             try {
                 await this.interruptAgentIfRunning(this.voiceModeAgentId);
             }
             catch (error) {
-                this.sessionLogger.warn({ err: error, agentId: this.voiceModeAgentId }, 'Failed to interrupt active voice-mode agent on abort');
+                this.sessionLogger.warn({ err: error, agentId: this.voiceModeAgentId }, "Failed to interrupt active voice-mode agent on abort");
             }
         }
-        if (this.processingPhase === 'transcribing') {
+        if (this.processingPhase === "transcribing") {
             // Still in STT phase - we'll buffer the next audio
-            this.sessionLogger.debug('Will buffer next audio (currently transcribing)');
+            this.sessionLogger.debug("Will buffer next audio (currently transcribing)");
             // Phase stays as 'transcribing', handleAudioChunk will handle buffering
             return;
         }
         // Reset phase to idle and clear pending non-voice buffers.
-        this.setPhase('idle');
+        this.setPhase("idle");
         this.pendingAudioSegments = [];
         this.clearBufferTimeout();
     }
@@ -5229,20 +5564,20 @@ export class Session {
         const phaseBeforeAbort = this.processingPhase;
         const hadActiveStream = this.hasActiveAgentRun(this.voiceModeAgentId);
         this.speechInProgress = true;
-        this.sessionLogger.debug('Voice speech detected – aborting playback and active agent run');
+        this.sessionLogger.debug("Voice speech detected – aborting playback and active agent run");
         if (this.pendingAudioSegments.length > 0) {
             this.sessionLogger.debug({ segmentCount: this.pendingAudioSegments.length }, `Dropping ${this.pendingAudioSegments.length} buffered audio segment(s) due to voice speech`);
             this.pendingAudioSegments = [];
         }
         if (this.audioBuffer) {
-            this.sessionLogger.debug({ chunks: this.audioBuffer.chunks.length, pcmBytes: this.audioBuffer.totalPCMBytes }, `Clearing partial audio buffer (${this.audioBuffer.chunks.length} chunk(s)${this.audioBuffer.isPCM ? `, ${this.audioBuffer.totalPCMBytes} PCM bytes` : ''})`);
+            this.sessionLogger.debug({ chunks: this.audioBuffer.chunks.length, pcmBytes: this.audioBuffer.totalPCMBytes }, `Clearing partial audio buffer (${this.audioBuffer.chunks.length} chunk(s)${this.audioBuffer.isPCM ? `, ${this.audioBuffer.totalPCMBytes} PCM bytes` : ""})`);
             this.audioBuffer = null;
         }
         this.clearBufferTimeout();
         this.abortController.abort();
         await this.handleAbort();
         const latencyMs = Date.now() - chunkReceivedAt;
-        this.sessionLogger.debug({ latencyMs, phaseBeforeAbort, hadActiveStream }, '[Telemetry] barge_in.llm_abort_latency');
+        this.sessionLogger.debug({ latencyMs, phaseBeforeAbort, hadActiveStream }, "[Telemetry] barge_in.llm_abort_latency");
     }
     /**
      * Clear speech-in-progress flag once the user turn has completed
@@ -5277,9 +5612,9 @@ export class Session {
     setBufferTimeout() {
         this.clearBufferTimeout();
         this.bufferTimeout = setTimeout(async () => {
-            this.sessionLogger.debug('Buffer timeout reached, processing pending segments');
-            if (this.processingPhase === 'transcribing') {
-                this.sessionLogger.debug({ segmentCount: this.pendingAudioSegments.length }, 'Buffer timeout deferred because transcription is still in progress');
+            this.sessionLogger.debug("Buffer timeout reached, processing pending segments");
+            if (this.processingPhase === "transcribing") {
+                this.sessionLogger.debug({ segmentCount: this.pendingAudioSegments.length }, "Buffer timeout deferred because transcription is still in progress");
                 this.setBufferTimeout();
                 return;
             }
@@ -5305,15 +5640,15 @@ export class Session {
      * Emit a message to the client
      */
     emit(msg) {
-        if (msg.type === 'audio_output' &&
+        if (msg.type === "audio_output" &&
             (process.env.TTS_DEBUG_AUDIO_DIR || isPaseoDictationDebugEnabled()) &&
             msg.payload.groupId &&
-            typeof msg.payload.audio === 'string') {
+            typeof msg.payload.audio === "string") {
             const groupId = msg.payload.groupId;
             const existing = this.ttsDebugStreams.get(groupId) ??
                 { format: msg.payload.format, chunks: [] };
             try {
-                existing.chunks.push(Buffer.from(msg.payload.audio, 'base64'));
+                existing.chunks.push(Buffer.from(msg.payload.audio, "base64"));
                 existing.format = msg.payload.format;
                 this.ttsDebugStreams.set(groupId, existing);
             }
@@ -5328,11 +5663,11 @@ export class Session {
                         const recordingPath = await maybePersistTtsDebugAudio(Buffer.concat(final.chunks), { sessionId: this.sessionId, groupId, format: final.format }, this.sessionLogger);
                         if (recordingPath) {
                             this.onMessage({
-                                type: 'activity_log',
+                                type: "activity_log",
                                 payload: {
                                     id: uuidv4(),
                                     timestamp: new Date(),
-                                    type: 'system',
+                                    type: "system",
                                     content: `Saved TTS audio: ${recordingPath}`,
                                     metadata: { recordingPath, format: final.format, groupId },
                                 },
@@ -5352,14 +5687,14 @@ export class Session {
             this.onBinaryMessage(frame);
         }
         catch (error) {
-            this.sessionLogger.error({ err: error }, 'Failed to emit binary frame');
+            this.sessionLogger.error({ err: error }, "Failed to emit binary frame");
         }
     }
     /**
      * Clean up session resources
      */
     async cleanup() {
-        this.sessionLogger.trace('Cleaning up');
+        this.sessionLogger.trace("Cleaning up");
         if (this.unsubscribeAgentEvents) {
             this.unsubscribeAgentEvents();
             this.unsubscribeAgentEvents = null;
@@ -5382,7 +5717,7 @@ export class Session {
                 await this.agentMcpClient.close();
             }
             catch (error) {
-                this.sessionLogger.error({ err: error }, 'Failed to close Agent MCP client');
+                this.sessionLogger.error({ err: error }, "Failed to close Agent MCP client");
             }
             this.agentMcpClient = null;
             this.agentTools = null;
@@ -5395,20 +5730,20 @@ export class Session {
             this.unsubscribeTerminalsChanged = null;
         }
         this.subscribedTerminalDirectories.clear();
-        for (const unsubscribe of this.terminalSubscriptions.values()) {
-            unsubscribe();
-        }
-        this.terminalSubscriptions.clear();
         for (const unsubscribeExit of this.terminalExitSubscriptions.values()) {
             unsubscribeExit();
         }
         this.terminalExitSubscriptions.clear();
-        this.detachAllTerminalStreams({ emitExit: false });
+        this.disposeTerminalSubscriptions();
         for (const target of this.checkoutDiffTargets.values()) {
             this.closeCheckoutDiffWatchTarget(target);
         }
         this.checkoutDiffTargets.clear();
         this.checkoutDiffSubscriptions.clear();
+        for (const target of this.workspaceGitWatchTargets.values()) {
+            this.closeWorkspaceGitWatchTarget(target);
+        }
+        this.workspaceGitWatchTargets.clear();
     }
     // ============================================================================
     // Terminal Handlers
@@ -5428,24 +5763,11 @@ export class Session {
             unsubscribeExit();
             this.terminalExitSubscriptions.delete(terminalId);
         }
-        const unsubscribe = this.terminalSubscriptions.get(terminalId);
-        if (unsubscribe) {
-            try {
-                unsubscribe();
-            }
-            catch (error) {
-                this.sessionLogger.warn({ err: error, terminalId }, 'Failed to unsubscribe terminal after process exit');
-            }
-            this.terminalSubscriptions.delete(terminalId);
-        }
-        const streamId = this.terminalStreamByTerminalId.get(terminalId);
-        if (typeof streamId === 'number') {
-            this.detachTerminalStream(streamId, { emitExit: true });
-        }
+        this.detachTerminalStream(terminalId, { emitExit: true });
     }
     emitTerminalsChangedSnapshot(input) {
         this.emit({
-            type: 'terminals_changed',
+            type: "terminals_changed",
             payload: {
                 cwd: input.cwd,
                 terminals: input.terminals,
@@ -5492,13 +5814,13 @@ export class Session {
             });
         }
         catch (error) {
-            this.sessionLogger.warn({ err: error, cwd }, 'Failed to emit initial terminal snapshot');
+            this.sessionLogger.warn({ err: error, cwd }, "Failed to emit initial terminal snapshot");
         }
     }
     async handleListTerminalsRequest(msg) {
         if (!this.terminalManager) {
             this.emit({
-                type: 'list_terminals_response',
+                type: "list_terminals_response",
                 payload: {
                     cwd: msg.cwd,
                     terminals: [],
@@ -5513,7 +5835,7 @@ export class Session {
                 this.ensureTerminalExitSubscription(terminal);
             }
             this.emit({
-                type: 'list_terminals_response',
+                type: "list_terminals_response",
                 payload: {
                     cwd: msg.cwd,
                     terminals: terminals.map((t) => ({ id: t.id, name: t.name })),
@@ -5522,9 +5844,9 @@ export class Session {
             });
         }
         catch (error) {
-            this.sessionLogger.error({ err: error, cwd: msg.cwd }, 'Failed to list terminals');
+            this.sessionLogger.error({ err: error, cwd: msg.cwd }, "Failed to list terminals");
             this.emit({
-                type: 'list_terminals_response',
+                type: "list_terminals_response",
                 payload: {
                     cwd: msg.cwd,
                     terminals: [],
@@ -5536,10 +5858,10 @@ export class Session {
     async handleCreateTerminalRequest(msg) {
         if (!this.terminalManager) {
             this.emit({
-                type: 'create_terminal_response',
+                type: "create_terminal_response",
                 payload: {
                     terminal: null,
-                    error: 'Terminal manager not available',
+                    error: "Terminal manager not available",
                     requestId: msg.requestId,
                 },
             });
@@ -5552,7 +5874,7 @@ export class Session {
             });
             this.ensureTerminalExitSubscription(session);
             this.emit({
-                type: 'create_terminal_response',
+                type: "create_terminal_response",
                 payload: {
                     terminal: { id: session.id, name: session.name, cwd: session.cwd },
                     error: null,
@@ -5561,9 +5883,9 @@ export class Session {
             });
         }
         catch (error) {
-            this.sessionLogger.error({ err: error, cwd: msg.cwd }, 'Failed to create terminal');
+            this.sessionLogger.error({ err: error, cwd: msg.cwd }, "Failed to create terminal");
             this.emit({
-                type: 'create_terminal_response',
+                type: "create_terminal_response",
                 payload: {
                     terminal: null,
                     error: error.message,
@@ -5575,11 +5897,10 @@ export class Session {
     async handleSubscribeTerminalRequest(msg) {
         if (!this.terminalManager) {
             this.emit({
-                type: 'subscribe_terminal_response',
+                type: "subscribe_terminal_response",
                 payload: {
                     terminalId: msg.terminalId,
-                    state: null,
-                    error: 'Terminal manager not available',
+                    error: "Terminal manager not available",
                     requestId: msg.requestId,
                 },
             });
@@ -5588,52 +5909,44 @@ export class Session {
         const session = this.terminalManager.getTerminal(msg.terminalId);
         if (!session) {
             this.emit({
-                type: 'subscribe_terminal_response',
+                type: "subscribe_terminal_response",
                 payload: {
                     terminalId: msg.terminalId,
-                    state: null,
-                    error: 'Terminal not found',
+                    error: "Terminal not found",
                     requestId: msg.requestId,
                 },
             });
             return;
         }
         this.ensureTerminalExitSubscription(session);
-        // Unsubscribe from previous subscription if any
-        const existing = this.terminalSubscriptions.get(msg.terminalId);
-        if (existing) {
-            existing();
+        const slot = this.bindActiveTerminalStream(session);
+        if (slot === null) {
+            this.sessionLogger.warn({
+                terminalId: msg.terminalId,
+                activeTerminalStreamCount: this.activeTerminalStreams.size,
+            }, "Terminal stream slot exhaustion");
+            this.emit({
+                type: "subscribe_terminal_response",
+                payload: {
+                    terminalId: msg.terminalId,
+                    error: "No terminal stream slots available",
+                    requestId: msg.requestId,
+                },
+            });
+            return;
         }
-        // Subscribe to terminal updates
-        const unsubscribe = session.subscribe((serverMsg) => {
-            if (serverMsg.type === 'full') {
-                this.emit({
-                    type: 'terminal_output',
-                    payload: {
-                        terminalId: msg.terminalId,
-                        state: serverMsg.state,
-                    },
-                });
-            }
-        });
-        this.terminalSubscriptions.set(msg.terminalId, unsubscribe);
-        // Send initial state
         this.emit({
-            type: 'subscribe_terminal_response',
+            type: "subscribe_terminal_response",
             payload: {
                 terminalId: msg.terminalId,
-                state: session.getState(),
+                slot,
                 error: null,
                 requestId: msg.requestId,
             },
         });
     }
     handleUnsubscribeTerminalRequest(msg) {
-        const unsubscribe = this.terminalSubscriptions.get(msg.terminalId);
-        if (unsubscribe) {
-            unsubscribe();
-            this.terminalSubscriptions.delete(msg.terminalId);
-        }
+        this.detachTerminalStream(msg.terminalId, { emitExit: false });
     }
     handleTerminalInput(msg) {
         if (!this.terminalManager) {
@@ -5641,22 +5954,20 @@ export class Session {
         }
         const session = this.terminalManager.getTerminal(msg.terminalId);
         if (!session) {
-            this.sessionLogger.warn({ terminalId: msg.terminalId }, 'Terminal not found for input');
+            this.sessionLogger.warn({ terminalId: msg.terminalId }, "Terminal not found for input");
             return;
         }
         this.ensureTerminalExitSubscription(session);
+        if (msg.message.type === "resize") {
+            const currentSize = session.getSize();
+            if (currentSize.rows === msg.message.rows && currentSize.cols === msg.message.cols) {
+                return;
+            }
+        }
         session.send(msg.message);
     }
     killTrackedTerminal(terminalId, options) {
-        const unsubscribe = this.terminalSubscriptions.get(terminalId);
-        if (unsubscribe) {
-            unsubscribe();
-            this.terminalSubscriptions.delete(terminalId);
-        }
-        const streamId = this.terminalStreamByTerminalId.get(terminalId);
-        if (typeof streamId === 'number') {
-            this.detachTerminalStream(streamId, { emitExit: options?.emitExit ?? true });
-        }
+        this.detachTerminalStream(terminalId, { emitExit: options?.emitExit ?? true });
         this.terminalManager?.killTerminal(terminalId);
     }
     async killTerminalsUnderPath(rootPath) {
@@ -5678,18 +5989,18 @@ export class Session {
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
                 cleanupErrors.push({ cwd: terminalCwd, message });
-                this.sessionLogger.warn({ err: error, cwd: terminalCwd }, 'Failed to clean up worktree terminals during archive');
+                this.sessionLogger.warn({ err: error, cwd: terminalCwd }, "Failed to clean up worktree terminals during archive");
             }
         }
         if (cleanupErrors.length > 0) {
-            const details = cleanupErrors.map((entry) => `${entry.cwd}: ${entry.message}`).join('; ');
+            const details = cleanupErrors.map((entry) => `${entry.cwd}: ${entry.message}`).join("; ");
             throw new Error(`Failed to clean up worktree terminals during archive (${details})`);
         }
     }
     async handleKillTerminalRequest(msg) {
         if (!this.terminalManager) {
             this.emit({
-                type: 'kill_terminal_response',
+                type: "kill_terminal_response",
                 payload: {
                     terminalId: msg.terminalId,
                     success: false,
@@ -5700,7 +6011,7 @@ export class Session {
         }
         this.killTrackedTerminal(msg.terminalId, { emitExit: true });
         this.emit({
-            type: 'kill_terminal_response',
+            type: "kill_terminal_response",
             payload: {
                 terminalId: msg.terminalId,
                 success: true,
@@ -5708,219 +6019,150 @@ export class Session {
             },
         });
     }
-    async handleAttachTerminalStreamRequest(msg) {
-        if (!this.terminalManager || !this.onBinaryMessage) {
-            this.emit({
-                type: 'attach_terminal_stream_response',
-                payload: {
-                    terminalId: msg.terminalId,
-                    streamId: null,
-                    replayedFrom: 0,
-                    currentOffset: 0,
-                    earliestAvailableOffset: 0,
-                    reset: true,
-                    error: 'Terminal streaming not available',
-                    requestId: msg.requestId,
-                },
-            });
-            return;
+    bindActiveTerminalStream(terminal) {
+        if (!this.onBinaryMessage) {
+            return null;
         }
-        const session = this.terminalManager.getTerminal(msg.terminalId);
-        if (!session) {
-            this.emit({
-                type: 'attach_terminal_stream_response',
-                payload: {
-                    terminalId: msg.terminalId,
-                    streamId: null,
-                    replayedFrom: 0,
-                    currentOffset: 0,
-                    earliestAvailableOffset: 0,
-                    reset: true,
-                    error: 'Terminal not found',
-                    requestId: msg.requestId,
-                },
-            });
-            return;
+        const existingSlot = this.terminalIdToSlot.get(terminal.id);
+        if (typeof existingSlot === "number") {
+            const existingStream = this.activeTerminalStreams.get(existingSlot);
+            if (existingStream) {
+                existingStream.needsSnapshot = true;
+                this.trySendTerminalSnapshot(existingStream);
+                return existingSlot;
+            }
+            this.terminalIdToSlot.delete(terminal.id);
+        }
+        const slot = this.allocateTerminalSlot();
+        if (slot === null) {
+            return null;
         }
-        if (msg.rows || msg.cols) {
-            const state = session.getState();
-            session.send({
-                type: 'resize',
-                rows: msg.rows ?? state.rows,
-                cols: msg.cols ?? state.cols,
-            });
-        }
-        const existingStreamId = this.terminalStreamByTerminalId.get(msg.terminalId);
-        if (typeof existingStreamId === 'number') {
-            // Replacing an active stream can happen when multiple UI surfaces attach to the
-            // same terminal. Emit exit for the replaced stream so stale listeners reconnect
-            // instead of continuing to send input to an invalid stream id.
-            this.detachTerminalStream(existingStreamId, { emitExit: true });
-        }
-        const streamId = this.allocateTerminalStreamId();
-        const requestedResumeOffset = typeof msg.resumeOffset === 'number'
-            ? msg.resumeOffset
-            : 0;
-        const initialOffset = Math.max(0, Math.floor(requestedResumeOffset));
-        const binding = {
-            terminalId: msg.terminalId,
+        const activeStream = {
+            terminalId: terminal.id,
+            slot,
             unsubscribe: () => { },
-            lastOutputOffset: initialOffset,
-            lastAckOffset: initialOffset,
-            pendingChunks: [],
-            pendingBytes: 0,
+            needsSnapshot: true,
+            snapshotRetryTimer: null,
         };
-        this.terminalStreams.set(streamId, binding);
-        this.terminalStreamByTerminalId.set(msg.terminalId, streamId);
-        let rawSub;
-        try {
-            rawSub = session.subscribeRaw((chunk) => {
-                const currentBinding = this.terminalStreams.get(streamId);
-                if (!currentBinding) {
-                    return;
-                }
-                this.enqueueOrEmitTerminalStreamChunk(streamId, currentBinding, {
-                    data: chunk.data,
-                    startOffset: chunk.startOffset,
-                    endOffset: chunk.endOffset,
-                    replay: chunk.replay,
-                });
-            }, { fromOffset: requestedResumeOffset });
-        }
-        catch (error) {
-            this.terminalStreams.delete(streamId);
-            this.terminalStreamByTerminalId.delete(msg.terminalId);
-            throw error;
-        }
-        binding.unsubscribe = rawSub.unsubscribe;
-        binding.lastAckOffset = rawSub.replayedFrom;
-        if (binding.lastOutputOffset < rawSub.replayedFrom) {
-            binding.lastOutputOffset = rawSub.replayedFrom;
-        }
-        this.flushPendingTerminalStreamChunks(streamId, binding);
-        this.emit({
-            type: 'attach_terminal_stream_response',
-            payload: {
-                terminalId: msg.terminalId,
-                streamId,
-                replayedFrom: rawSub.replayedFrom,
-                currentOffset: rawSub.currentOffset,
-                earliestAvailableOffset: rawSub.earliestAvailableOffset,
-                reset: rawSub.reset,
-                error: null,
-                requestId: msg.requestId,
-            },
-        });
-    }
-    getTerminalStreamChunkByteLength(chunk) {
-        return Math.max(0, chunk.endOffset - chunk.startOffset);
-    }
-    canEmitTerminalStreamChunk(binding, chunk) {
-        return chunk.startOffset < binding.lastAckOffset + TERMINAL_STREAM_WINDOW_BYTES;
-    }
-    emitTerminalStreamChunk(streamId, binding, chunk) {
-        const payload = new Uint8Array(Buffer.from(chunk.data, 'utf8'));
-        this.emitBinary({
-            channel: BinaryMuxChannel.Terminal,
-            messageType: TerminalBinaryMessageType.OutputUtf8,
-            streamId,
-            offset: chunk.startOffset,
-            flags: chunk.replay ? TerminalBinaryFlags.Replay : 0,
-            payload,
-        });
-        binding.lastOutputOffset = chunk.endOffset;
-    }
-    enqueueOrEmitTerminalStreamChunk(streamId, binding, chunk) {
-        const chunkBytes = this.getTerminalStreamChunkByteLength(chunk);
-        if (binding.pendingChunks.length > 0 || !this.canEmitTerminalStreamChunk(binding, chunk)) {
-            if (binding.pendingChunks.length >= TERMINAL_STREAM_MAX_PENDING_CHUNKS ||
-                binding.pendingBytes + chunkBytes > TERMINAL_STREAM_MAX_PENDING_BYTES) {
-                this.sessionLogger.warn({
-                    streamId,
-                    pendingChunks: binding.pendingChunks.length,
-                    pendingBytes: binding.pendingBytes,
-                    chunkBytes,
-                }, 'Terminal stream pending buffer overflow; closing stream');
-                this.detachTerminalStream(streamId, { emitExit: true });
+        this.activeTerminalStreams.set(slot, activeStream);
+        this.terminalIdToSlot.set(terminal.id, slot);
+        activeStream.unsubscribe = terminal.subscribe((message) => {
+            if (this.activeTerminalStreams.get(slot) !== activeStream) {
+                return;
+            }
+            if (message.type === "snapshot") {
+                this.trySendTerminalSnapshot(activeStream);
+                return;
+            }
+            if (activeStream.needsSnapshot || message.data.length === 0) {
+                return;
+            }
+            if (this.getCurrentBinaryBufferedAmount() >= TERMINAL_STREAM_HIGH_WATER_BYTES) {
+                this.markAllActiveTerminalStreamsForSnapshot();
                 return;
             }
-            binding.pendingChunks.push(chunk);
-            binding.pendingBytes += chunkBytes;
+            this.emitBinary(encodeTerminalStreamFrame({
+                opcode: TerminalStreamOpcode.Output,
+                slot,
+                payload: new Uint8Array(Buffer.from(message.data, "utf8")),
+            }));
+            if (this.getCurrentBinaryBufferedAmount() >= TERMINAL_STREAM_HIGH_WATER_BYTES) {
+                this.markAllActiveTerminalStreamsForSnapshot();
+            }
+        });
+        this.trySendTerminalSnapshot(activeStream);
+        return slot;
+    }
+    trySendTerminalSnapshot(activeStream) {
+        if (this.activeTerminalStreams.get(activeStream.slot) !== activeStream ||
+            !activeStream.needsSnapshot) {
             return;
         }
-        this.emitTerminalStreamChunk(streamId, binding, chunk);
-    }
-    flushPendingTerminalStreamChunks(streamId, binding) {
-        while (binding.pendingChunks.length > 0) {
-            const next = binding.pendingChunks[0];
-            if (!next || !this.canEmitTerminalStreamChunk(binding, next)) {
-                break;
+        if (this.getCurrentBinaryBufferedAmount() > TERMINAL_STREAM_LOW_WATER_BYTES) {
+            if (!activeStream.snapshotRetryTimer) {
+                activeStream.snapshotRetryTimer = setTimeout(() => {
+                    activeStream.snapshotRetryTimer = null;
+                    this.trySendTerminalSnapshot(activeStream);
+                }, 33);
             }
-            binding.pendingChunks.shift();
-            binding.pendingBytes -= this.getTerminalStreamChunkByteLength(next);
-            if (binding.pendingBytes < 0) {
-                binding.pendingBytes = 0;
-            }
-            this.emitTerminalStreamChunk(streamId, binding, next);
+            return;
         }
+        if (activeStream.snapshotRetryTimer) {
+            clearTimeout(activeStream.snapshotRetryTimer);
+            activeStream.snapshotRetryTimer = null;
+        }
+        const terminal = this.terminalManager?.getTerminal(activeStream.terminalId);
+        if (!terminal) {
+            this.detachTerminalStream(activeStream.terminalId, { emitExit: true });
+            return;
+        }
+        activeStream.needsSnapshot = false;
+        this.emitBinary(encodeTerminalStreamFrame({
+            opcode: TerminalStreamOpcode.Snapshot,
+            slot: activeStream.slot,
+            payload: encodeTerminalSnapshotPayload(terminal.getState()),
+        }));
     }
-    handleDetachTerminalStreamRequest(msg) {
-        const success = this.detachTerminalStream(msg.streamId, { emitExit: false });
-        this.emit({
-            type: 'detach_terminal_stream_response',
-            payload: {
-                streamId: msg.streamId,
-                success,
-                requestId: msg.requestId,
-            },
-        });
+    markAllActiveTerminalStreamsForSnapshot() {
+        for (const activeStream of this.activeTerminalStreams.values()) {
+            activeStream.needsSnapshot = true;
+            this.trySendTerminalSnapshot(activeStream);
+        }
     }
-    detachAllTerminalStreams(options) {
-        for (const streamId of Array.from(this.terminalStreams.keys())) {
-            this.detachTerminalStream(streamId, options);
+    allocateTerminalSlot() {
+        for (let attempt = 0; attempt < MAX_TERMINAL_STREAM_SLOTS; attempt += 1) {
+            const slot = (this.nextTerminalSlot + attempt) % MAX_TERMINAL_STREAM_SLOTS;
+            if (this.activeTerminalStreams.has(slot)) {
+                continue;
+            }
+            this.nextTerminalSlot = (slot + 1) % MAX_TERMINAL_STREAM_SLOTS;
+            return slot;
         }
+        return null;
     }
-    detachTerminalStream(streamId, options) {
-        const binding = this.terminalStreams.get(streamId);
-        if (!binding) {
+    detachTerminalStream(terminalId, options) {
+        const slot = this.terminalIdToSlot.get(terminalId);
+        if (typeof slot !== "number") {
             return false;
         }
+        const activeStream = this.activeTerminalStreams.get(slot);
+        if (!activeStream) {
+            this.terminalIdToSlot.delete(terminalId);
+            return false;
+        }
+        this.activeTerminalStreams.delete(slot);
+        this.terminalIdToSlot.delete(terminalId);
+        if (activeStream.snapshotRetryTimer) {
+            clearTimeout(activeStream.snapshotRetryTimer);
+            activeStream.snapshotRetryTimer = null;
+        }
         try {
-            binding.unsubscribe();
+            activeStream.unsubscribe();
         }
         catch (error) {
-            this.sessionLogger.warn({ err: error, streamId }, 'Failed to unsubscribe terminal stream');
-        }
-        this.terminalStreams.delete(streamId);
-        if (this.terminalStreamByTerminalId.get(binding.terminalId) === streamId) {
-            this.terminalStreamByTerminalId.delete(binding.terminalId);
+            this.sessionLogger.warn({ err: error }, "Failed to unsubscribe terminal stream");
         }
         if (options?.emitExit) {
             this.emit({
-                type: 'terminal_stream_exit',
+                type: "terminal_stream_exit",
                 payload: {
-                    streamId,
-                    terminalId: binding.terminalId,
+                    terminalId: activeStream.terminalId,
                 },
             });
         }
         return true;
     }
-    allocateTerminalStreamId() {
-        let attempts = 0;
-        while (attempts < 0xffffffff) {
-            const candidate = this.nextTerminalStreamId >>> 0;
-            this.nextTerminalStreamId = ((this.nextTerminalStreamId + 1) & 0xffffffff) >>> 0;
-            if (candidate === 0) {
-                attempts += 1;
-                continue;
-            }
-            if (!this.terminalStreams.has(candidate)) {
-                return candidate;
-            }
-            attempts += 1;
+    disposeTerminalSubscriptions() {
+        for (const terminalId of [...this.terminalIdToSlot.keys()]) {
+            this.detachTerminalStream(terminalId, { emitExit: false });
+        }
+    }
+    getCurrentBinaryBufferedAmount() {
+        const bufferedAmount = this.getBinaryBufferedAmount?.() ?? 0;
+        if (!Number.isFinite(bufferedAmount) || bufferedAmount < 0) {
+            return 0;
         }
-        throw new Error('Unable to allocate terminal stream id');
+        return Math.floor(bufferedAmount);
     }
 }
 //# sourceMappingURL=session.js.map