@getpaseo/server 0.1.3 → 0.1.6

package/dist/server/server/session.js

@@ -6,6 +6,7 @@ import { promisify } from "util";
 import { join, resolve, sep } from "path";
 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";
@@ -16,13 +17,16 @@ import { experimental_createMCPClient } from "ai";
 import { buildProviderRegistry } from "./agent/provider-registry.js";
 import { scheduleAgentMetadataGeneration } from "./agent/agent-metadata-generator.js";
 import { toAgentPayload } from "./agent/agent-projections.js";
+import { appendTimelineItemIfAgentKnown, emitLiveTimelineItemIfAgentKnown, } from "./agent/timeline-append.js";
+import { projectTimelineRows } from "./agent/timeline-projection.js";
 import { StructuredAgentResponseError, generateStructuredAgentResponse, } from "./agent/agent-response-loop.js";
 import { isValidAgentProvider, AGENT_PROVIDER_IDS } from "./agent/provider-manifest.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 { createWorktree, runWorktreeSetupCommands, WorktreeSetupError, slugify, validateBranchSlug, listPaseoWorktrees, deletePaseoWorktree, isPaseoOwnedWorktreeCwd, resolvePaseoWorktreeRootForCwd, } from "../utils/worktree.js";
-import { getCheckoutDiff, getCheckoutStatus, getCheckoutStatusLite, NotGitRepoError, MergeConflictError, MergeFromBaseConflictError, commitChanges, mergeToBase, mergeFromBase, pushCurrentBranch, createPullRequest, getPullRequestStatus, } from "../utils/checkout-git.js";
+import { slugify, validateBranchSlug, listPaseoWorktrees, deletePaseoWorktree, isPaseoOwnedWorktreeCwd, resolvePaseoWorktreeRootForCwd, } from "../utils/worktree.js";
+import { createAgentWorktree, runAsyncWorktreeBootstrap, } from "./worktree-bootstrap.js";
+import { getCheckoutDiff, getCheckoutStatus, getCheckoutStatusLite, 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 { ensureLocalSpeechModels, getLocalSpeechModelDir, listLocalSpeechModels, } from "./speech/providers/local/models.js";
@@ -35,10 +39,11 @@ const pendingAgentInitializations = new Map();
 let restartRequested = false;
 const DEFAULT_AGENT_PROVIDER = AGENT_PROVIDER_IDS[0];
 const RESTART_EXIT_DELAY_MS = 250;
-const PROJECT_PLACEMENT_CACHE_TTL_MS = 10000;
-const MAX_AGENTS_PER_PROJECT = 5;
 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;
 /**
  * Default model used for auto-generating commit messages and PR descriptions.
  * Uses Claude Haiku for speed and cost efficiency.
@@ -85,17 +90,17 @@ function deriveRemoteProjectKey(remoteUrl) {
     }
     return `remote:${cleanedHost}/${cleanedPath}`;
 }
-function deriveProjectGroupingKey(cwd, remoteUrl) {
-    const remoteKey = deriveRemoteProjectKey(remoteUrl);
+function deriveProjectGroupingKey(options) {
+    const remoteKey = deriveRemoteProjectKey(options.remoteUrl);
     if (remoteKey) {
         return remoteKey;
     }
     const worktreeMarker = ".paseo/worktrees/";
-    const idx = cwd.indexOf(worktreeMarker);
+    const idx = options.cwd.indexOf(worktreeMarker);
     if (idx !== -1) {
-        return cwd.slice(0, idx).replace(/\/$/, "");
+        return options.cwd.slice(0, idx).replace(/\/$/, "");
     }
-    return cwd;
+    return options.cwd;
 }
 function deriveProjectGroupingName(projectKey) {
     const githubRemotePrefix = "remote:github.com/";
@@ -105,6 +110,13 @@ function deriveProjectGroupingName(projectKey) {
     const segments = projectKey.split(/[\\/]/).filter(Boolean);
     return segments[segments.length - 1] || projectKey;
 }
+class SessionRequestError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "SessionRequestError";
+    }
+}
 const PCM_SAMPLE_RATE = 16000;
 const PCM_CHANNELS = 1;
 const PCM_BITS_PER_SAMPLE = 16;
@@ -116,6 +128,15 @@ const VOICE_INTERNAL_DICTATION_ID_PREFIX = "__voice_turn__:";
 const SAFE_GIT_REF_PATTERN = /^[A-Za-z0-9._\/-]+$/;
 const AgentIdSchema = z.string().uuid();
 const VOICE_MCP_SERVER_NAME = "paseo_voice";
+class VoiceFeatureUnavailableError extends Error {
+    constructor(context) {
+        super(context.message);
+        this.name = "VoiceFeatureUnavailableError";
+        this.reasonCode = context.reasonCode;
+        this.retryable = context.retryable;
+        this.missingModelIds = [...context.missingModelIds];
+    }
+}
 function convertPCMToWavBuffer(pcmBuffer, sampleRate, channels, bitsPerSample) {
     const headerSize = 44;
     const wavBuffer = Buffer.alloc(headerSize + pcmBuffer.length);
@@ -195,18 +216,24 @@ export class Session {
         this.agentTools = null;
         this.unsubscribeAgentEvents = null;
         this.agentUpdatesSubscription = null;
-        this.projectPlacementCache = new Map();
         this.clientActivity = null;
         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.checkoutDiffSubscriptions = new Map();
         this.checkoutDiffTargets = new Map();
         this.voiceModeAgentId = null;
         this.voiceModeBaseConfig = null;
-        const { clientId, onMessage, logger, downloadTokenStore, pushTokenStore, paseoHome, agentManager, agentStorage, createAgentMcpTransport, stt, tts, terminalManager, voice, voiceBridge, dictation, agentProviderRuntimeSettings, } = options;
+        const { clientId, onMessage, onBinaryMessage, logger, downloadTokenStore, pushTokenStore, paseoHome, agentManager, agentStorage, createAgentMcpTransport, stt, tts, terminalManager, voice, voiceBridge, dictation, agentProviderRuntimeSettings, } = options;
         this.clientId = clientId;
         this.sessionId = uuidv4();
         this.onMessage = onMessage;
+        this.onBinaryMessage = onBinaryMessage ?? null;
         this.downloadTokenStore = downloadTokenStore;
         this.pushTokenStore = pushTokenStore;
         this.paseoHome = paseoHome;
@@ -214,6 +241,9 @@ export class Session {
         this.agentStorage = agentStorage;
         this.createAgentMcpTransport = createAgentMcpTransport;
         this.terminalManager = terminalManager;
+        if (this.terminalManager) {
+            this.unsubscribeTerminalsChanged = this.terminalManager.subscribeTerminalsChanged((event) => this.handleTerminalsChanged(event));
+        }
         this.voiceAgentMcpStdio = voice?.voiceAgentMcpStdio ?? null;
         const configuredModelsDir = dictation?.localModels?.modelsDir?.trim();
         this.localSpeechModelsDir =
@@ -230,6 +260,7 @@ export class Session {
         this.unregisterVoiceCallerContext = voiceBridge?.unregisterVoiceCallerContext;
         this.ensureVoiceMcpSocketForAgent = voiceBridge?.ensureVoiceMcpSocketForAgent;
         this.removeVoiceMcpSocketForAgent = voiceBridge?.removeVoiceMcpSocketForAgent;
+        this.getSpeechReadiness = dictation?.getSpeechReadiness;
         this.agentProviderRuntimeSettings = agentProviderRuntimeSettings;
         this.abortController = new AbortController();
         this.sessionLogger = logger.child({
@@ -415,9 +446,7 @@ export class Session {
             }
             // 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 explicit `initialize_agent_request` which emits a
-            // batched `agent_stream_snapshot`.
+            // History catch-up is handled via pull-based `fetch_agent_timeline_request`.
             const activity = this.clientActivity;
             if (activity?.deviceType === "mobile") {
                 if (!activity.focusedAgentId) {
@@ -441,6 +470,8 @@ 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 } : {}),
             };
             this.emit({
                 type: "agent_stream",
@@ -600,26 +631,16 @@ export class Session {
         const checkout = await getCheckoutStatusLite(cwd, { paseoHome: this.paseoHome })
             .then((status) => this.toProjectCheckoutLite(cwd, status))
             .catch(() => this.buildFallbackProjectCheckout(cwd));
-        const projectKey = deriveProjectGroupingKey(cwd, checkout.remoteUrl);
+        const projectKey = deriveProjectGroupingKey({
+            cwd,
+            remoteUrl: checkout.remoteUrl,
+        });
         return {
             projectKey,
             projectName: deriveProjectGroupingName(projectKey),
             checkout,
         };
     }
-    getProjectPlacement(cwd) {
-        const now = Date.now();
-        const cached = this.projectPlacementCache.get(cwd);
-        if (cached && cached.expiresAt > now) {
-            return cached.promise;
-        }
-        const promise = this.buildProjectPlacement(cwd);
-        this.projectPlacementCache.set(cwd, {
-            expiresAt: now + PROJECT_PLACEMENT_CACHE_TTL_MS,
-            promise,
-        });
-        return promise;
-    }
     async forwardAgentUpdate(agent) {
         try {
             const subscription = this.agentUpdatesSubscription;
@@ -629,7 +650,7 @@ export class Session {
             const payload = await this.buildAgentPayload(agent);
             const matches = this.matchesAgentFilter(payload, subscription.filter);
             if (matches) {
-                const project = await this.getProjectPlacement(payload.cwd);
+                const project = await this.buildProjectPlacement(payload.cwd);
                 this.emit({
                     type: "agent_update",
                     payload: { kind: "upsert", agent: payload, project },
@@ -661,10 +682,7 @@ export class Session {
                     this.handleAudioPlayed(msg.id);
                     break;
                 case "fetch_agents_request":
-                    await this.handleFetchAgents(msg.requestId, msg.filter);
-                    break;
-                case "fetch_agents_grouped_by_project_request":
-                    await this.handleFetchAgentsGroupedByProject(msg.requestId, msg.filter);
+                    await this.handleFetchAgents(msg);
                     break;
                 case "fetch_agent_request":
                     await this.handleFetchAgent(msg.agentId, msg.requestId);
@@ -699,6 +717,22 @@ export class Session {
                     await this.handleWaitForFinish(msg.agentId, msg.requestId, msg.timeoutMs);
                     break;
                 case "dictation_stream_start":
+                    {
+                        const unavailable = this.resolveVoiceFeatureUnavailableContext("dictation");
+                        if (unavailable) {
+                            this.emit({
+                                type: "dictation_stream_error",
+                                payload: {
+                                    dictationId: msg.dictationId,
+                                    error: unavailable.message,
+                                    retryable: unavailable.retryable,
+                                    reasonCode: unavailable.reasonCode,
+                                    missingModelIds: unavailable.missingModelIds,
+                                },
+                            });
+                            break;
+                        }
+                    }
                     await this.dictationStreamManager.handleStart(msg.dictationId, msg.format);
                     break;
                 case "dictation_stream_chunk":
@@ -730,8 +764,8 @@ export class Session {
                 case "restart_server_request":
                     await this.handleRestartServerRequest(msg.requestId, msg.reason);
                     break;
-                case "initialize_agent_request":
-                    await this.handleInitializeAgentRequest(msg.agentId, msg.requestId);
+                case "fetch_agent_timeline_request":
+                    await this.handleFetchAgentTimelineRequest(msg);
                     break;
                 case "set_agent_mode_request":
                     await this.handleSetAgentModeRequest(msg.agentId, msg.modeId, msg.requestId);
@@ -751,6 +785,9 @@ export class Session {
                 case "validate_branch_request":
                     await this.handleValidateBranchRequest(msg);
                     break;
+                case "branch_suggestions_request":
+                    await this.handleBranchSuggestionsRequest(msg);
+                    break;
                 case "subscribe_checkout_diff_request":
                     await this.handleSubscribeCheckoutDiffRequest(msg);
                     break;
@@ -830,6 +867,12 @@ export class Session {
                 case "register_push_token":
                     this.handleRegisterPushToken(msg.token);
                     break;
+                case "subscribe_terminals_request":
+                    this.handleSubscribeTerminalsRequest(msg);
+                    break;
+                case "unsubscribe_terminals_request":
+                    this.handleUnsubscribeTerminalsRequest(msg);
+                    break;
                 case "list_terminals_request":
                     await this.handleListTerminalsRequest(msg);
                     break;
@@ -848,6 +891,12 @@ export class Session {
                 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) {
@@ -881,6 +930,58 @@ export class Session {
             });
         }
     }
+    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;
+        }
+    }
+    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 });
+            return;
+        }
+        if (frame.messageType === TerminalBinaryMessageType.Ack) {
+            const binding = this.terminalStreams.get(frame.streamId);
+            if (binding) {
+                if (!Number.isFinite(frame.offset) || frame.offset < 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);
+                }
+            }
+            return;
+        }
+        this.sessionLogger.warn({ streamId: frame.streamId, messageType: frame.messageType }, "Unhandled terminal binary frame");
+    }
     async handleRestartServerRequest(requestId, reason) {
         if (restartRequested) {
             this.sessionLogger.debug("Restart already requested, ignoring duplicate");
@@ -1032,12 +1133,57 @@ export class Session {
             });
         }
     }
+    toVoiceFeatureUnavailableContext(state) {
+        return {
+            reasonCode: state.reasonCode,
+            message: state.message,
+            retryable: state.retryable,
+            missingModelIds: [...state.missingModelIds],
+        };
+    }
+    resolveModeReadinessState(readiness, mode) {
+        if (mode === "voice_mode") {
+            return readiness.realtimeVoice;
+        }
+        return readiness.dictation;
+    }
+    getVoiceFeatureUnavailableResponseMetadata(error) {
+        if (!(error instanceof VoiceFeatureUnavailableError)) {
+            return {};
+        }
+        return {
+            reasonCode: error.reasonCode,
+            retryable: error.retryable,
+            missingModelIds: error.missingModelIds,
+        };
+    }
+    resolveVoiceFeatureUnavailableContext(mode) {
+        const readiness = this.getSpeechReadiness?.();
+        if (!readiness) {
+            return null;
+        }
+        const modeReadiness = this.resolveModeReadinessState(readiness, mode);
+        if (!modeReadiness.enabled) {
+            return this.toVoiceFeatureUnavailableContext(modeReadiness);
+        }
+        if (!readiness.voiceFeature.available) {
+            return this.toVoiceFeatureUnavailableContext(readiness.voiceFeature);
+        }
+        if (!modeReadiness.available) {
+            return this.toVoiceFeatureUnavailableContext(modeReadiness);
+        }
+        return null;
+    }
     /**
      * Handle voice mode toggle
      */
     async handleSetVoiceMode(enabled, agentId, requestId) {
         try {
             if (enabled) {
+                const unavailable = this.resolveVoiceFeatureUnavailableContext("voice_mode");
+                if (unavailable) {
+                    throw new VoiceFeatureUnavailableError(unavailable);
+                }
                 const normalizedAgentId = this.parseVoiceTargetAgentId(agentId ?? "", "set_voice_mode");
                 if (this.isVoiceMode &&
                     this.voiceModeAgentId &&
@@ -1084,6 +1230,7 @@ export class Session {
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : "Failed to set voice mode";
+            const unavailable = this.getVoiceFeatureUnavailableResponseMetadata(error);
             this.sessionLogger.error({
                 err: error,
                 enabled,
@@ -1098,6 +1245,7 @@ export class Session {
                         agentId: this.voiceModeAgentId,
                         accepted: false,
                         error: errorMessage,
+                        ...unavailable,
                     },
                 });
                 return;
@@ -1403,44 +1551,16 @@ export class Session {
         }
         const prompt = this.buildAgentPrompt(text, images);
         try {
-            this.agentManager.recordUserMessage(agentId, text, { messageId });
+            this.agentManager.recordUserMessage(agentId, text, {
+                messageId,
+                emitState: false,
+            });
         }
         catch (error) {
             this.sessionLogger.error({ err: error, agentId }, `Failed to record user message for agent ${agentId}`);
         }
         this.startAgentStream(agentId, prompt, runOptions);
     }
-    /**
-     * Handle on-demand agent initialization request from client
-     */
-    async handleInitializeAgentRequest(agentId, requestId) {
-        try {
-            const snapshot = await this.ensureAgentLoaded(agentId);
-            await this.forwardAgentUpdate(snapshot);
-            // Send timeline snapshot after hydration (if any)
-            const timelineSize = this.emitAgentTimelineSnapshot(snapshot);
-            this.emit({
-                type: "initialize_agent_request",
-                payload: {
-                    agentId,
-                    agentStatus: snapshot.lifecycle,
-                    timelineSize,
-                    requestId,
-                },
-            });
-        }
-        catch (error) {
-            this.sessionLogger.error({ err: error, agentId }, `Failed to initialize agent ${agentId}`);
-            this.emit({
-                type: "initialize_agent_request",
-                payload: {
-                    agentId,
-                    requestId,
-                    error: error?.message ?? "Failed to initialize agent",
-                },
-            });
-        }
-    }
     /**
      * Handle create agent request
      */
@@ -1494,7 +1614,22 @@ export class Session {
                 });
             }
             if (worktreeConfig) {
-                void this.runAsyncWorktreeSetup(snapshot.id, worktreeConfig);
+                void runAsyncWorktreeBootstrap({
+                    agentId: snapshot.id,
+                    worktree: worktreeConfig,
+                    terminalManager: this.terminalManager,
+                    appendTimelineItem: (item) => appendTimelineItemIfAgentKnown({
+                        agentManager: this.agentManager,
+                        agentId: snapshot.id,
+                        item,
+                    }),
+                    emitLiveTimelineItem: (item) => emitLiveTimelineItemIfAgentKnown({
+                        agentManager: this.agentManager,
+                        agentId: snapshot.id,
+                        item,
+                    }),
+                    logger: this.sessionLogger,
+                });
             }
             this.sessionLogger.info({ agentId: snapshot.id, provider: snapshot.provider }, `Created agent ${snapshot.id} (${snapshot.provider})`);
         }
@@ -1541,7 +1676,7 @@ export class Session {
             const snapshot = await this.agentManager.resumeAgentFromPersistence(handle, overrides);
             await this.agentManager.hydrateTimelineFromProvider(snapshot.id);
             await this.forwardAgentUpdate(snapshot);
-            const timelineSize = this.emitAgentTimelineSnapshot(snapshot);
+            const timelineSize = this.agentManager.getTimeline(snapshot.id).length;
             if (requestId) {
                 const agentPayload = await this.getAgentPayloadById(snapshot.id);
                 if (!agentPayload) {
@@ -1600,7 +1735,7 @@ export class Session {
             }
             await this.agentManager.hydrateTimelineFromProvider(agentId);
             await this.forwardAgentUpdate(snapshot);
-            const timelineSize = this.emitAgentTimelineSnapshot(snapshot);
+            const timelineSize = this.agentManager.getTimeline(agentId).length;
             if (requestId) {
                 this.emit({
                     type: "status",
@@ -1664,12 +1799,11 @@ export class Session {
                 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 createdWorktree = await createWorktree({
+            const createdWorktree = await createAgentWorktree({
                 branchName: targetBranch,
                 cwd,
                 baseBranch: normalized.baseBranch,
                 worktreeSlug: normalized.worktreeSlug ?? targetBranch,
-                runSetup: false,
                 paseoHome: this.paseoHome,
             });
             cwd = createdWorktree.worktreePath;
@@ -1693,100 +1827,6 @@ export class Session {
             worktreeConfig,
         };
     }
-    async runAsyncWorktreeSetup(agentId, worktree) {
-        const callId = uuidv4();
-        let results = [];
-        try {
-            const started = await this.safeAppendTimelineItem(agentId, {
-                type: "tool_call",
-                name: "paseo_worktree_setup",
-                callId,
-                status: "running",
-                detail: {
-                    type: "unknown",
-                    input: {
-                        worktreePath: worktree.worktreePath,
-                        branchName: worktree.branchName,
-                    },
-                    output: null,
-                },
-                error: null,
-            });
-            if (!started) {
-                return;
-            }
-            results = await runWorktreeSetupCommands({
-                worktreePath: worktree.worktreePath,
-                branchName: worktree.branchName,
-                cleanupOnFailure: false,
-            });
-            await this.safeAppendTimelineItem(agentId, {
-                type: "tool_call",
-                name: "paseo_worktree_setup",
-                callId,
-                status: "completed",
-                detail: {
-                    type: "unknown",
-                    input: {
-                        worktreePath: worktree.worktreePath,
-                        branchName: worktree.branchName,
-                    },
-                    output: {
-                        worktreePath: worktree.worktreePath,
-                        commands: results.map((result) => ({
-                            command: result.command,
-                            cwd: result.cwd,
-                            exitCode: result.exitCode,
-                            output: `${result.stdout ?? ""}${result.stderr ? `\n${result.stderr}` : ""}`.trim(),
-                        })),
-                    },
-                },
-                error: null,
-            });
-        }
-        catch (error) {
-            if (error instanceof WorktreeSetupError) {
-                results = error.results;
-            }
-            const message = error instanceof Error ? error.message : String(error);
-            await this.safeAppendTimelineItem(agentId, {
-                type: "tool_call",
-                name: "paseo_worktree_setup",
-                callId,
-                status: "failed",
-                detail: {
-                    type: "unknown",
-                    input: {
-                        worktreePath: worktree.worktreePath,
-                        branchName: worktree.branchName,
-                    },
-                    output: {
-                        worktreePath: worktree.worktreePath,
-                        commands: results.map((result) => ({
-                            command: result.command,
-                            cwd: result.cwd,
-                            exitCode: result.exitCode,
-                            output: `${result.stdout ?? ""}${result.stderr ? `\n${result.stderr}` : ""}`.trim(),
-                        })),
-                    },
-                },
-                error: { message },
-            });
-        }
-    }
-    async safeAppendTimelineItem(agentId, item) {
-        try {
-            await this.agentManager.appendTimelineItem(agentId, item);
-            return true;
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            if (message.includes("Unknown agent")) {
-                return false;
-            }
-            throw error;
-        }
-    }
     async handleListProviderModelsRequest(msg) {
         const fetchedAt = new Date().toISOString();
         try {
@@ -2627,6 +2667,31 @@ export class Session {
             });
         }
     }
+    async handleBranchSuggestionsRequest(msg) {
+        const { cwd, query, limit, requestId } = msg;
+        try {
+            const resolvedCwd = expandTilde(cwd);
+            const branches = await listBranchSuggestions(resolvedCwd, { query, limit });
+            this.emit({
+                type: "branch_suggestions_response",
+                payload: {
+                    branches,
+                    error: null,
+                    requestId,
+                },
+            });
+        }
+        catch (error) {
+            this.emit({
+                type: "branch_suggestions_response",
+                payload: {
+                    branches: [],
+                    error: error instanceof Error ? error.message : String(error),
+                    requestId,
+                },
+            });
+        }
+    }
     normalizeCheckoutDiffCompare(compare) {
         if (compare.mode === "uncommitted") {
             return { mode: "uncommitted" };
@@ -2798,30 +2863,42 @@ export class Session {
             latestPayload: null,
             latestFingerprint: null,
         };
-        const watchPaths = new Set([cwd]);
-        if (watchRoot) {
-            watchPaths.add(watchRoot);
-        }
+        const repoWatchPath = watchRoot ?? cwd;
+        const watchPaths = new Set([repoWatchPath]);
         const gitDir = await this.resolveCheckoutGitDir(cwd);
         if (gitDir) {
             watchPaths.add(gitDir);
         }
-        let hasWatchRootCoverage = false;
+        let hasRecursiveRepoCoverage = false;
+        const allowRecursiveRepoWatch = process.platform !== "linux";
         for (const watchPath of watchPaths) {
+            const shouldTryRecursive = watchPath === repoWatchPath && allowRecursiveRepoWatch;
             const createWatcher = (recursive) => watch(watchPath, { recursive }, () => {
                 this.scheduleCheckoutDiffTargetRefresh(target);
             });
             let watcher = null;
+            let watcherIsRecursive = false;
             try {
-                watcher = createWatcher(true);
+                if (shouldTryRecursive) {
+                    watcher = createWatcher(true);
+                    watcherIsRecursive = true;
+                }
+                else {
+                    watcher = createWatcher(false);
+                }
             }
             catch (error) {
-                try {
-                    watcher = createWatcher(false);
-                    this.sessionLogger.warn({ err: error, watchPath, cwd, compare }, "Checkout diff recursive watch unavailable; using non-recursive fallback");
+                if (shouldTryRecursive) {
+                    try {
+                        watcher = createWatcher(false);
+                        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");
+                    }
                 }
-                catch (fallbackError) {
-                    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");
                 }
             }
             if (!watcher) {
@@ -2831,11 +2908,11 @@ export class Session {
                 this.sessionLogger.warn({ err: error, watchPath, cwd, compare }, "Checkout diff watcher error");
             });
             target.watchers.push(watcher);
-            if (watchRoot && watchPath === watchRoot) {
-                hasWatchRootCoverage = true;
+            if (watchPath === repoWatchPath && watcherIsRecursive) {
+                hasRecursiveRepoCoverage = true;
             }
         }
-        const missingRepoCoverage = Boolean(watchRoot) && !hasWatchRootCoverage;
+        const missingRepoCoverage = !hasRecursiveRepoCoverage;
         if (target.watchers.length === 0 || missingRepoCoverage) {
             target.fallbackRefreshInterval = setInterval(() => {
                 this.scheduleCheckoutDiffTargetRefresh(target);
@@ -2846,7 +2923,7 @@ export class Session {
                 intervalMs: CHECKOUT_DIFF_FALLBACK_REFRESH_MS,
                 reason: target.watchers.length === 0
                     ? "no_watchers"
-                    : "missing_repo_root_coverage",
+                    : "missing_recursive_repo_root_coverage",
             }, "Checkout diff watchers unavailable; using timed refresh fallback");
         }
         this.checkoutDiffTargets.set(targetKey, target);
@@ -3523,64 +3600,230 @@ export class Session {
         }
         return this.buildStoredAgentPayload(record);
     }
-    async handleFetchAgents(requestId, filter) {
-        try {
-            const agents = await this.listAgentPayloads(filter);
-            this.emit({
-                type: "fetch_agents_response",
-                payload: { requestId, agents },
-            });
+    normalizeFetchAgentsSort(sort) {
+        const fallback = [
+            { key: "updated_at", direction: "desc" },
+        ];
+        if (!sort || sort.length === 0) {
+            return fallback;
+        }
+        const deduped = [];
+        const seen = new Set();
+        for (const entry of sort) {
+            if (seen.has(entry.key)) {
+                continue;
+            }
+            seen.add(entry.key);
+            deduped.push(entry);
         }
-        catch (error) {
-            this.sessionLogger.error({ err: error }, "Failed to handle fetch_agents_request");
-            this.emit({
-                type: "fetch_agents_response",
-                payload: { requestId, agents: [] },
-            });
+        return deduped.length > 0 ? deduped : fallback;
+    }
+    getStatusPriority(agent) {
+        const requiresAttention = agent.requiresAttention ?? false;
+        const attentionReason = agent.attentionReason ?? null;
+        if (requiresAttention && attentionReason === "permission") {
+            return 0;
         }
+        if (agent.status === "error" || attentionReason === "error") {
+            return 1;
+        }
+        if (agent.status === "running") {
+            return 2;
+        }
+        if (agent.status === "initializing") {
+            return 3;
+        }
+        return 4;
     }
-    async listAgentsGroupedByProjectPayload(filter) {
-        const agents = await this.listAgentPayloads(filter);
-        const visibleAgents = agents
-            .filter((agent) => !agent.archivedAt)
-            .sort((left, right) => Date.parse(right.updatedAt || "") - Date.parse(left.updatedAt || ""));
-        const grouped = new Map();
-        // Warm project placement status for all visible roots up front to avoid serial N+1 latency.
-        for (const agent of visibleAgents) {
-            void this.getProjectPlacement(agent.cwd);
-        }
-        for (const agent of visibleAgents) {
-            const project = await this.getProjectPlacement(agent.cwd);
-            const projectKey = project.projectKey;
-            let group = grouped.get(projectKey);
-            if (!group) {
-                group = {
-                    projectKey,
-                    projectName: project.projectName,
-                    agents: [],
-                };
-                grouped.set(projectKey, group);
+    getFetchAgentsSortValue(entry, key) {
+        switch (key) {
+            case "status_priority":
+                return this.getStatusPriority(entry.agent);
+            case "created_at":
+                return Date.parse(entry.agent.createdAt);
+            case "updated_at":
+                return Date.parse(entry.agent.updatedAt);
+            case "title":
+                return entry.agent.title?.toLocaleLowerCase() ?? "";
+        }
+    }
+    compareSortValues(left, right) {
+        if (left === right) {
+            return 0;
+        }
+        if (left === null) {
+            return -1;
+        }
+        if (right === null) {
+            return 1;
+        }
+        if (typeof left === "number" && typeof right === "number") {
+            return left < right ? -1 : 1;
+        }
+        return String(left).localeCompare(String(right));
+    }
+    compareFetchAgentsEntries(left, right, sort) {
+        for (const spec of sort) {
+            const leftValue = this.getFetchAgentsSortValue(left, spec.key);
+            const rightValue = this.getFetchAgentsSortValue(right, spec.key);
+            const base = this.compareSortValues(leftValue, rightValue);
+            if (base === 0) {
+                continue;
+            }
+            return spec.direction === "asc" ? base : -base;
+        }
+        return left.agent.id.localeCompare(right.agent.id);
+    }
+    encodeFetchAgentsCursor(entry, sort) {
+        const values = {};
+        for (const spec of sort) {
+            values[spec.key] = this.getFetchAgentsSortValue(entry, spec.key);
+        }
+        return Buffer.from(JSON.stringify({
+            sort,
+            values,
+            id: entry.agent.id,
+        }), "utf8").toString("base64url");
+    }
+    decodeFetchAgentsCursor(cursor, sort) {
+        let parsed;
+        try {
+            parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+        }
+        catch {
+            throw new SessionRequestError("invalid_cursor", "Invalid fetch_agents cursor");
+        }
+        if (!parsed || typeof parsed !== "object") {
+            throw new SessionRequestError("invalid_cursor", "Invalid fetch_agents cursor");
+        }
+        const payload = parsed;
+        if (!Array.isArray(payload.sort) || typeof payload.id !== "string") {
+            throw new SessionRequestError("invalid_cursor", "Invalid fetch_agents cursor");
+        }
+        if (!payload.values || typeof payload.values !== "object") {
+            throw new SessionRequestError("invalid_cursor", "Invalid fetch_agents cursor");
+        }
+        const cursorSort = [];
+        for (const item of payload.sort) {
+            if (!item ||
+                typeof item !== "object" ||
+                typeof item.key !== "string" ||
+                typeof item.direction !== "string") {
+                throw new SessionRequestError("invalid_cursor", "Invalid fetch_agents cursor");
+            }
+            const key = item.key;
+            const direction = item.direction;
+            if ((key !== "status_priority" &&
+                key !== "created_at" &&
+                key !== "updated_at" &&
+                key !== "title") ||
+                (direction !== "asc" && direction !== "desc")) {
+                throw new SessionRequestError("invalid_cursor", "Invalid fetch_agents cursor");
             }
-            if (group.agents.length >= MAX_AGENTS_PER_PROJECT) {
+            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");
+        }
+        return {
+            sort: cursorSort,
+            values: payload.values,
+            id: payload.id,
+        };
+    }
+    compareEntryWithCursor(entry, cursor, sort) {
+        for (const spec of sort) {
+            const leftValue = this.getFetchAgentsSortValue(entry, spec.key);
+            const rightValue = cursor.values[spec.key] !== undefined ? cursor.values[spec.key] ?? null : null;
+            const base = this.compareSortValues(leftValue, rightValue);
+            if (base === 0) {
                 continue;
             }
-            group.agents.push({ agent, checkout: project.checkout });
+            return spec.direction === "asc" ? base : -base;
         }
-        return Array.from(grouped.values());
+        return entry.agent.id.localeCompare(cursor.id);
     }
-    async handleFetchAgentsGroupedByProject(requestId, filter) {
+    async listFetchAgentsEntries(request) {
+        const filter = request.filter;
+        const sort = this.normalizeFetchAgentsSort(request.sort);
+        const includeArchived = filter?.includeArchived ?? false;
+        let agents = await this.listAgentPayloads({
+            labels: filter?.labels,
+        });
+        if (!includeArchived) {
+            agents = agents.filter((agent) => !agent.archivedAt);
+        }
+        if (filter?.statuses && filter.statuses.length > 0) {
+            const statuses = new Set(filter.statuses);
+            agents = agents.filter((agent) => statuses.has(agent.status));
+        }
+        if (typeof filter?.requiresAttention === "boolean") {
+            agents = agents.filter((agent) => (agent.requiresAttention ?? false) === filter.requiresAttention);
+        }
+        const placementByCwd = new Map();
+        const getPlacement = (cwd) => {
+            const existing = placementByCwd.get(cwd);
+            if (existing) {
+                return existing;
+            }
+            const placementPromise = this.buildProjectPlacement(cwd);
+            placementByCwd.set(cwd, placementPromise);
+            return placementPromise;
+        };
+        let entries = await Promise.all(agents.map(async (agent) => ({
+            agent,
+            project: await getPlacement(agent.cwd),
+        })));
+        if (filter?.projectKeys && filter.projectKeys.length > 0) {
+            const projectKeys = new Set(filter.projectKeys.filter((item) => item.trim().length > 0));
+            entries = entries.filter((entry) => projectKeys.has(entry.project.projectKey));
+        }
+        entries.sort((left, right) => this.compareFetchAgentsEntries(left, right, sort));
+        const cursorToken = request.page?.cursor;
+        if (cursorToken) {
+            const cursor = this.decodeFetchAgentsCursor(cursorToken, sort);
+            entries = entries.filter((entry) => this.compareEntryWithCursor(entry, cursor, sort) > 0);
+        }
+        const limit = request.page?.limit ?? entries.length;
+        const pagedEntries = entries.slice(0, limit);
+        const hasMore = entries.length > limit;
+        const nextCursor = hasMore && pagedEntries.length > 0
+            ? this.encodeFetchAgentsCursor(pagedEntries[pagedEntries.length - 1], sort)
+            : null;
+        return {
+            entries: pagedEntries,
+            pageInfo: {
+                nextCursor,
+                prevCursor: request.page?.cursor ?? null,
+                hasMore,
+            },
+        };
+    }
+    async handleFetchAgents(request) {
         try {
-            const groups = await this.listAgentsGroupedByProjectPayload(filter);
+            const payload = await this.listFetchAgentsEntries(request);
             this.emit({
-                type: "fetch_agents_grouped_by_project_response",
-                payload: { requestId, groups },
+                type: "fetch_agents_response",
+                payload: {
+                    requestId: request.requestId,
+                    ...payload,
+                },
             });
         }
         catch (error) {
-            this.sessionLogger.error({ err: error }, "Failed to handle fetch_agents_grouped_by_project_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: "fetch_agents_grouped_by_project_response",
-                payload: { requestId, groups: [] },
+                type: "rpc_error",
+                payload: {
+                    requestId: request.requestId,
+                    requestType: request.type,
+                    error: message,
+                    code,
+                },
             });
         }
     }
@@ -3606,6 +3849,77 @@ export class Session {
             payload: { requestId, agent, error: null },
         });
     }
+    async handleFetchAgentTimelineRequest(msg) {
+        const direction = msg.direction ?? (msg.cursor ? "after" : "tail");
+        const projection = msg.projection ?? "projected";
+        const limit = msg.limit ?? (direction === "after" ? 0 : undefined);
+        const cursor = msg.cursor
+            ? {
+                epoch: msg.cursor.epoch,
+                seq: msg.cursor.seq,
+            }
+            : undefined;
+        try {
+            const snapshot = await this.ensureAgentLoaded(msg.agentId);
+            const timeline = this.agentManager.fetchTimeline(msg.agentId, {
+                direction,
+                cursor,
+                limit,
+            });
+            const projected = projectTimelineRows(timeline.rows, snapshot.provider, projection);
+            const firstRow = timeline.rows[0];
+            const lastRow = timeline.rows[timeline.rows.length - 1];
+            const startCursor = firstRow
+                ? { epoch: timeline.epoch, seq: firstRow.seq }
+                : null;
+            const endCursor = lastRow
+                ? { epoch: timeline.epoch, seq: lastRow.seq }
+                : null;
+            this.emit({
+                type: "fetch_agent_timeline_response",
+                payload: {
+                    requestId: msg.requestId,
+                    agentId: msg.agentId,
+                    direction,
+                    projection,
+                    epoch: timeline.epoch,
+                    reset: timeline.reset,
+                    staleCursor: timeline.staleCursor,
+                    gap: timeline.gap,
+                    window: timeline.window,
+                    startCursor,
+                    endCursor,
+                    hasOlder: timeline.hasOlder,
+                    hasNewer: timeline.hasNewer,
+                    entries: projected,
+                    error: null,
+                },
+            });
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, agentId: msg.agentId }, "Failed to handle fetch_agent_timeline_request");
+            this.emit({
+                type: "fetch_agent_timeline_response",
+                payload: {
+                    requestId: msg.requestId,
+                    agentId: msg.agentId,
+                    direction,
+                    projection,
+                    epoch: "",
+                    reset: false,
+                    staleCursor: false,
+                    gap: false,
+                    window: { minSeq: 0, maxSeq: 0, nextSeq: 0 },
+                    startCursor: null,
+                    endCursor: null,
+                    hasOlder: false,
+                    hasNewer: false,
+                    entries: [],
+                    error: error instanceof Error ? error.message : String(error),
+                },
+            });
+        }
+    }
     async handleSendAgentMessageRequest(msg) {
         const resolved = await this.resolveAgentIdentifier(msg.agentId);
         if (!resolved.ok) {
@@ -3625,7 +3939,10 @@ export class Session {
             await this.ensureAgentLoaded(agentId);
             await this.interruptAgentIfRunning(agentId);
             try {
-                this.agentManager.recordUserMessage(agentId, msg.text, { messageId: msg.messageId });
+                this.agentManager.recordUserMessage(agentId, msg.text, {
+                    messageId: msg.messageId,
+                    emitState: false,
+                });
             }
             catch (error) {
                 this.sessionLogger.error({ err: error, agentId }, "Failed to record user message for send_agent_message_request");
@@ -3782,30 +4099,6 @@ export class Session {
             clearTimeout(timeoutHandle);
         }
     }
-    emitAgentTimelineSnapshot(agent) {
-        const timeline = this.agentManager.getTimeline(agent.id);
-        const events = timeline.flatMap((item) => {
-            const serializedEvent = serializeAgentStreamEvent({
-                type: "timeline",
-                provider: agent.provider,
-                item,
-            });
-            if (!serializedEvent) {
-                return [];
-            }
-            return [
-                {
-                    event: serializedEvent,
-                    timestamp: new Date().toISOString(),
-                },
-            ];
-        });
-        this.emit({
-            type: "agent_stream_snapshot",
-            payload: { agentId: agent.id, events },
-        });
-        return timeline.length;
-    }
     /**
      * Handle audio chunk for buffering and transcription
      */
@@ -4257,6 +4550,17 @@ export class Session {
         }
         this.onMessage(msg);
     }
+    emitBinary(frame) {
+        if (!this.onBinaryMessage) {
+            return;
+        }
+        try {
+            this.onBinaryMessage(frame);
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error }, "Failed to emit binary frame");
+        }
+    }
     /**
      * Clean up session resources
      */
@@ -4295,10 +4599,20 @@ export class Session {
         await this.disableVoiceModeForActiveAgent(true);
         this.isVoiceMode = false;
         // Unsubscribe from all terminals
+        if (this.unsubscribeTerminalsChanged) {
+            this.unsubscribeTerminalsChanged();
+            this.unsubscribeTerminalsChanged = null;
+        }
+        this.subscribedTerminalDirectories.clear();
         for (const unsubscribe of this.terminalSubscriptions.values()) {
             unsubscribe();
         }
         this.terminalSubscriptions.clear();
+        for (const unsubscribeExit of this.terminalExitSubscriptions.values()) {
+            unsubscribeExit();
+        }
+        this.terminalExitSubscriptions.clear();
+        this.detachAllTerminalStreams({ emitExit: false });
         for (const target of this.checkoutDiffTargets.values()) {
             this.closeCheckoutDiffWatchTarget(target);
         }
@@ -4308,6 +4622,96 @@ export class Session {
     // ============================================================================
     // Terminal Handlers
     // ============================================================================
+    ensureTerminalExitSubscription(terminal) {
+        if (this.terminalExitSubscriptions.has(terminal.id)) {
+            return;
+        }
+        const unsubscribeExit = terminal.onExit(() => {
+            this.handleTerminalExited(terminal.id);
+        });
+        this.terminalExitSubscriptions.set(terminal.id, unsubscribeExit);
+    }
+    handleTerminalExited(terminalId) {
+        const unsubscribeExit = this.terminalExitSubscriptions.get(terminalId);
+        if (unsubscribeExit) {
+            unsubscribeExit();
+            this.terminalExitSubscriptions.delete(terminalId);
+        }
+        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 });
+        }
+    }
+    emitTerminalsChangedSnapshot(input) {
+        this.emit({
+            type: "terminals_changed",
+            payload: {
+                cwd: input.cwd,
+                terminals: input.terminals,
+            },
+        });
+    }
+    handleTerminalsChanged(event) {
+        if (!this.subscribedTerminalDirectories.has(event.cwd)) {
+            return;
+        }
+        this.emitTerminalsChangedSnapshot({
+            cwd: event.cwd,
+            terminals: event.terminals.map((terminal) => ({
+                id: terminal.id,
+                name: terminal.name,
+            })),
+        });
+    }
+    handleSubscribeTerminalsRequest(msg) {
+        this.subscribedTerminalDirectories.add(msg.cwd);
+        void this.emitInitialTerminalsChangedSnapshot(msg.cwd);
+    }
+    handleUnsubscribeTerminalsRequest(msg) {
+        this.subscribedTerminalDirectories.delete(msg.cwd);
+    }
+    async emitInitialTerminalsChangedSnapshot(cwd) {
+        if (!this.terminalManager || !this.subscribedTerminalDirectories.has(cwd)) {
+            return;
+        }
+        const hadDirectoryBeforeSubscribe = this.terminalManager
+            .listDirectories()
+            .includes(cwd);
+        try {
+            const terminals = await this.terminalManager.getTerminals(cwd);
+            for (const terminal of terminals) {
+                this.ensureTerminalExitSubscription(terminal);
+            }
+            // New directories auto-create Terminal 1, which already emits through
+            // terminal-manager change listeners.
+            if (!hadDirectoryBeforeSubscribe) {
+                return;
+            }
+            if (!this.subscribedTerminalDirectories.has(cwd)) {
+                return;
+            }
+            this.emitTerminalsChangedSnapshot({
+                cwd,
+                terminals: terminals.map((terminal) => ({
+                    id: terminal.id,
+                    name: terminal.name,
+                })),
+            });
+        }
+        catch (error) {
+            this.sessionLogger.warn({ err: error, cwd }, "Failed to emit initial terminal snapshot");
+        }
+    }
     async handleListTerminalsRequest(msg) {
         if (!this.terminalManager) {
             this.emit({
@@ -4322,6 +4726,9 @@ export class Session {
         }
         try {
             const terminals = await this.terminalManager.getTerminals(msg.cwd);
+            for (const terminal of terminals) {
+                this.ensureTerminalExitSubscription(terminal);
+            }
             this.emit({
                 type: "list_terminals_response",
                 payload: {
@@ -4360,6 +4767,7 @@ export class Session {
                 cwd: msg.cwd,
                 name: msg.name,
             });
+            this.ensureTerminalExitSubscription(session);
             this.emit({
                 type: "create_terminal_response",
                 payload: {
@@ -4407,6 +4815,7 @@ export class Session {
             });
             return;
         }
+        this.ensureTerminalExitSubscription(session);
         // Unsubscribe from previous subscription if any
         const existing = this.terminalSubscriptions.get(msg.terminalId);
         if (existing) {
@@ -4452,6 +4861,7 @@ export class Session {
             this.sessionLogger.warn({ terminalId: msg.terminalId }, "Terminal not found for input");
             return;
         }
+        this.ensureTerminalExitSubscription(session);
         session.send(msg.message);
     }
     async handleKillTerminalRequest(msg) {
@@ -4472,6 +4882,10 @@ export class Session {
             unsubscribe();
             this.terminalSubscriptions.delete(msg.terminalId);
         }
+        const streamId = this.terminalStreamByTerminalId.get(msg.terminalId);
+        if (typeof streamId === "number") {
+            this.detachTerminalStream(streamId, { emitExit: true });
+        }
         this.terminalManager.killTerminal(msg.terminalId);
         this.emit({
             type: "kill_terminal_response",
@@ -4482,5 +4896,213 @@ 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;
+        }
+        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;
+        }
+        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") {
+            this.detachTerminalStream(existingStreamId, { emitExit: false });
+        }
+        const streamId = this.allocateTerminalStreamId();
+        const initialOffset = Math.max(0, Math.floor(msg.resumeOffset ?? 0));
+        const binding = {
+            terminalId: msg.terminalId,
+            unsubscribe: () => { },
+            lastOutputOffset: initialOffset,
+            lastAckOffset: initialOffset,
+            pendingChunks: [],
+            pendingBytes: 0,
+        };
+        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: msg.resumeOffset ?? 0 });
+        }
+        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 });
+                return;
+            }
+            binding.pendingChunks.push(chunk);
+            binding.pendingBytes += chunkBytes;
+            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;
+            }
+            binding.pendingChunks.shift();
+            binding.pendingBytes -= this.getTerminalStreamChunkByteLength(next);
+            if (binding.pendingBytes < 0) {
+                binding.pendingBytes = 0;
+            }
+            this.emitTerminalStreamChunk(streamId, binding, next);
+        }
+    }
+    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,
+            },
+        });
+    }
+    detachAllTerminalStreams(options) {
+        for (const streamId of Array.from(this.terminalStreams.keys())) {
+            this.detachTerminalStream(streamId, options);
+        }
+    }
+    detachTerminalStream(streamId, options) {
+        const binding = this.terminalStreams.get(streamId);
+        if (!binding) {
+            return false;
+        }
+        try {
+            binding.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);
+        }
+        if (options?.emitExit) {
+            this.emit({
+                type: "terminal_stream_exit",
+                payload: {
+                    streamId,
+                    terminalId: binding.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;
+        }
+        throw new Error("Unable to allocate terminal stream id");
+    }
 }
 //# sourceMappingURL=session.js.map