@getpaseo/server 0.1.4 → 0.1.6

package/dist/server/server/session.js

@@ -17,13 +17,15 @@ 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 { 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";
@@ -37,8 +39,6 @@ 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;
@@ -90,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/";
@@ -110,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;
@@ -209,10 +216,12 @@ 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;
@@ -232,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 =
@@ -619,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;
@@ -648,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 },
@@ -680,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);
@@ -868,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;
@@ -1546,7 +1551,10 @@ 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}`);
@@ -1606,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})`);
         }
@@ -1776,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;
@@ -1805,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 {
@@ -3672,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;
             }
-            if (group.agents.length >= MAX_AGENTS_PER_PROJECT) {
+            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");
+            }
+            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 entry.agent.id.localeCompare(cursor.id);
+    }
+    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);
         }
-        return Array.from(grouped.values());
+        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 handleFetchAgentsGroupedByProject(requestId, filter) {
+    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,
+                },
             });
         }
     }
@@ -3845,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");
@@ -4502,10 +4599,19 @@ 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);
@@ -4516,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({
@@ -4530,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: {
@@ -4568,6 +4767,7 @@ export class Session {
                 cwd: msg.cwd,
                 name: msg.name,
             });
+            this.ensureTerminalExitSubscription(session);
             this.emit({
                 type: "create_terminal_response",
                 payload: {
@@ -4615,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) {
@@ -4660,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) {