@getpaseo/server 0.1.15 → 0.1.17

package/dist/server/server/session.js

@@ -17,9 +17,10 @@ import { buildConfigOverrides, buildSessionConfig, extractTimestamps } from './p
 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 { resolveEffectiveThinkingOptionId, toAgentPayload } from './agent/agent-projections.js';
+import { MAX_EXPLICIT_AGENT_TITLE_CHARS } from './agent/agent-title-limits.js';
 import { appendTimelineItemIfAgentKnown, emitLiveTimelineItemIfAgentKnown, } from './agent/timeline-append.js';
-import { projectTimelineRows } from './agent/timeline-projection.js';
+import { projectTimelineRows, selectTimelineWindowByProjectedLimit, } from './agent/timeline-projection.js';
 import { DEFAULT_STRUCTURED_GENERATION_PROVIDERS, StructuredAgentFallbackError, StructuredAgentResponseError, generateStructuredAgentResponseWithFallback, } from './agent/agent-response-loop.js';
 import { isValidAgentProvider, AGENT_PROVIDER_IDS } from './agent/provider-manifest.js';
 import { buildVoiceAgentMcpServerConfig, buildVoiceModeSystemPrompt, stripVoiceModeSystemPrompt, } from './voice-config.js';
@@ -32,20 +33,46 @@ import { getProjectIcon } from '../utils/project-icon.js';
 import { expandTilde } from '../utils/path.js';
 import { searchHomeDirectories, searchWorkspaceEntries } from '../utils/directory-suggestions.js';
 import { ensureLocalSpeechModels, getLocalSpeechModelDir, listLocalSpeechModels, } from './speech/providers/local/models.js';
+import { resolveClientMessageId } from './client-message-id.js';
 const execAsync = promisify(exec);
+const MAX_INITIAL_AGENT_TITLE_CHARS = Math.min(60, MAX_EXPLICIT_AGENT_TITLE_CHARS);
 const READ_ONLY_GIT_ENV = {
     ...process.env,
     GIT_OPTIONAL_LOCKS: '0',
 };
 const pendingAgentInitializations = new Map();
-let restartRequested = false;
 const DEFAULT_AGENT_PROVIDER = AGENT_PROVIDER_IDS[0];
-const RESTART_EXIT_DELAY_MS = 250;
 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;
+function deriveInitialAgentTitle(prompt) {
+    const firstContentLine = prompt
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .find((line) => line.length > 0);
+    if (!firstContentLine) {
+        return null;
+    }
+    const normalized = firstContentLine.replace(/\s+/g, ' ').trim();
+    if (!normalized) {
+        return null;
+    }
+    const clamped = normalized.slice(0, MAX_INITIAL_AGENT_TITLE_CHARS).trim();
+    return clamped.length > 0 ? clamped : null;
+}
+export function resolveCreateAgentTitles(options) {
+    const explicitTitle = typeof options.configTitle === 'string' && options.configTitle.trim().length > 0
+        ? options.configTitle.trim()
+        : null;
+    const trimmedPrompt = options.initialPrompt?.trim();
+    const provisionalTitle = explicitTitle ?? (trimmedPrompt ? deriveInitialAgentTitle(trimmedPrompt) : null);
+    return {
+        explicitTitle,
+        provisionalTitle,
+    };
+}
 function deriveRemoteProjectKey(remoteUrl) {
     if (!remoteUrl) {
         return null;
@@ -92,10 +119,9 @@ function deriveProjectGroupingKey(options) {
     if (remoteKey) {
         return remoteKey;
     }
-    const worktreeMarker = '.paseo/worktrees/';
-    const idx = options.cwd.indexOf(worktreeMarker);
-    if (idx !== -1) {
-        return options.cwd.slice(0, idx).replace(/\/$/, '');
+    const mainRepoRoot = options.mainRepoRoot?.trim();
+    if (options.isPaseoOwnedWorktree && mainRepoRoot) {
+        return mainRepoRoot;
     }
     return options.cwd;
 }
@@ -213,6 +239,7 @@ export class Session {
         this.agentTools = null;
         this.unsubscribeAgentEvents = null;
         this.agentUpdatesSubscription = null;
+        this.workspaceUpdatesSubscription = null;
         this.clientActivity = null;
         this.MOBILE_BACKGROUND_STREAM_GRACE_MS = 60000;
         this.subscribedTerminalDirectories = new Set();
@@ -226,11 +253,19 @@ export class Session {
         this.checkoutDiffTargets = new Map();
         this.voiceModeAgentId = null;
         this.voiceModeBaseConfig = null;
-        const { clientId, onMessage, onBinaryMessage, logger, downloadTokenStore, pushTokenStore, paseoHome, agentManager, agentStorage, createAgentMcpTransport, stt, tts, terminalManager, voice, voiceBridge, dictation, agentProviderRuntimeSettings, } = options;
+        this.workspaceStatePriority = {
+            needs_input: 0,
+            failed: 1,
+            running: 2,
+            attention: 3,
+            done: 4,
+        };
+        const { clientId, onMessage, onBinaryMessage, onLifecycleIntent, 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.onLifecycleIntent = onLifecycleIntent ?? null;
         this.downloadTokenStore = downloadTokenStore;
         this.pushTokenStore = pushTokenStore;
         this.paseoHome = paseoHome;
@@ -296,6 +331,25 @@ export class Session {
     getClientActivity() {
         return this.clientActivity;
     }
+    getRuntimeMetrics() {
+        let checkoutDiffWatcherCount = 0;
+        let checkoutDiffFallbackRefreshTargetCount = 0;
+        for (const target of this.checkoutDiffTargets.values()) {
+            checkoutDiffWatcherCount += target.watchers.length;
+            if (target.fallbackRefreshInterval) {
+                checkoutDiffFallbackRefreshTargetCount += 1;
+            }
+        }
+        return {
+            checkoutDiffTargetCount: this.checkoutDiffTargets.size,
+            checkoutDiffSubscriptionCount: this.checkoutDiffSubscriptions.size,
+            checkoutDiffWatcherCount,
+            checkoutDiffFallbackRefreshTargetCount,
+            terminalDirectorySubscriptionCount: this.subscribedTerminalDirectories.size,
+            terminalSubscriptionCount: this.terminalSubscriptions.size,
+            terminalStreamCount: this.terminalStreams.size,
+        };
+    }
     /**
      * Send initial state to client after connection
      */
@@ -326,10 +380,11 @@ export class Session {
     async interruptAgentIfRunning(agentId) {
         const snapshot = this.agentManager.getAgent(agentId);
         if (!snapshot) {
+            this.sessionLogger.trace({ agentId }, 'interruptAgentIfRunning: agent not found');
             throw new Error(`Agent ${agentId} not found`);
         }
         if (snapshot.lifecycle !== 'running' && !snapshot.pendingRun) {
-            this.sessionLogger.debug({ agentId, lifecycle: snapshot.lifecycle, pendingRun: Boolean(snapshot.pendingRun) }, 'interruptAgentIfRunning: not running, skipping');
+            this.sessionLogger.trace({ agentId, lifecycle: snapshot.lifecycle, pendingRun: Boolean(snapshot.pendingRun) }, 'interruptAgentIfRunning: skipping because agent is not running');
             return;
         }
         this.sessionLogger.debug({ agentId, lifecycle: snapshot.lifecycle, pendingRun: Boolean(snapshot.pendingRun) }, 'interruptAgentIfRunning: interrupting');
@@ -359,10 +414,15 @@ export class Session {
      * Start streaming an agent run and forward results via the websocket broadcast
      */
     startAgentStream(agentId, prompt, runOptions) {
-        this.sessionLogger.info({ agentId }, `Starting agent stream for ${agentId}`);
+        this.sessionLogger.trace({
+            agentId,
+            promptType: typeof prompt === 'string' ? 'string' : 'structured',
+            hasRunOptions: Boolean(runOptions),
+        }, 'startAgentStream: requested');
         let iterator;
         try {
             iterator = this.agentManager.streamAgent(agentId, prompt, runOptions);
+            this.sessionLogger.trace({ agentId }, 'startAgentStream: streamAgent returned iterator');
         }
         catch (error) {
             this.handleAgentRunError(agentId, error, 'Failed to start agent run');
@@ -374,8 +434,10 @@ export class Session {
                 for await (const _ of iterator) {
                     // Events are forwarded via the session's AgentManager subscription.
                 }
+                this.sessionLogger.trace({ agentId }, 'startAgentStream: iterator drained');
             }
             catch (error) {
+                this.sessionLogger.trace({ agentId, err: error }, 'startAgentStream: iterator threw');
                 this.handleAgentRunError(agentId, error, 'Agent stream failed');
             }
         })();
@@ -498,7 +560,7 @@ export class Session {
     }
     async buildAgentPayload(agent) {
         const storedRecord = await this.agentStorage.get(agent.id);
-        const title = storedRecord?.title ?? null;
+        const title = storedRecord?.title ?? storedRecord?.config?.title ?? null;
         const payload = toAgentPayload(agent, { title });
         payload.archivedAt = storedRecord?.archivedAt ?? null;
         return payload;
@@ -516,12 +578,33 @@ export class Session {
         const updatedAt = new Date(record.lastActivityAt ?? record.updatedAt);
         const lastUserMessageAt = record.lastUserMessageAt ? new Date(record.lastUserMessageAt) : null;
         const provider = coerceAgentProvider(this.sessionLogger, record.provider, record.id);
+        const runtimeInfo = record.runtimeInfo
+            ? {
+                provider: coerceAgentProvider(this.sessionLogger, record.runtimeInfo.provider, record.id),
+                sessionId: record.runtimeInfo.sessionId,
+                ...(Object.prototype.hasOwnProperty.call(record.runtimeInfo, 'model')
+                    ? { model: record.runtimeInfo.model ?? null }
+                    : {}),
+                ...(Object.prototype.hasOwnProperty.call(record.runtimeInfo, 'thinkingOptionId')
+                    ? { thinkingOptionId: record.runtimeInfo.thinkingOptionId ?? null }
+                    : {}),
+                ...(Object.prototype.hasOwnProperty.call(record.runtimeInfo, 'modeId')
+                    ? { modeId: record.runtimeInfo.modeId ?? null }
+                    : {}),
+                ...(record.runtimeInfo.extra ? { extra: record.runtimeInfo.extra } : {}),
+            }
+            : undefined;
         return {
             id: record.id,
             provider,
             cwd: record.cwd,
             model: record.config?.model ?? null,
             thinkingOptionId: record.config?.thinkingOptionId ?? null,
+            effectiveThinkingOptionId: resolveEffectiveThinkingOptionId({
+                runtimeInfo,
+                configuredThinkingOptionId: record.config?.thinkingOptionId ?? null,
+            }),
+            ...(runtimeInfo ? { runtimeInfo } : {}),
             createdAt: createdAt.toISOString(),
             updatedAt: updatedAt.toISOString(),
             lastUserMessageAt: lastUserMessageAt ? lastUserMessageAt.toISOString() : null,
@@ -533,7 +616,7 @@ export class Session {
             persistence: toAgentPersistenceHandle(this.sessionLogger, record.persistence),
             lastUsage: undefined,
             lastError: undefined,
-            title: record.title ?? null,
+            title: record.title ?? record.config?.title ?? null,
             requiresAttention: record.requiresAttention ?? false,
             attentionReason: record.attentionReason ?? null,
             attentionTimestamp: record.attentionTimestamp ?? null,
@@ -592,6 +675,19 @@ export class Session {
         if (!includeArchived && agent.archivedAt) {
             return false;
         }
+        if (filter?.thinkingOptionId !== undefined) {
+            const expectedThinkingOptionId = resolveEffectiveThinkingOptionId({
+                configuredThinkingOptionId: filter.thinkingOptionId ?? null,
+            });
+            const resolvedThinkingOptionId = agent.effectiveThinkingOptionId ??
+                resolveEffectiveThinkingOptionId({
+                    runtimeInfo: agent.runtimeInfo,
+                    configuredThinkingOptionId: agent.thinkingOptionId ?? null,
+                });
+            if (resolvedThinkingOptionId !== expectedThinkingOptionId) {
+                return false;
+            }
+        }
         if (filter?.statuses && filter.statuses.length > 0) {
             const statuses = new Set(filter.statuses);
             if (!statuses.has(agent.status)) {
@@ -689,6 +785,8 @@ export class Session {
         const projectKey = deriveProjectGroupingKey({
             cwd,
             remoteUrl: checkout.remoteUrl,
+            isPaseoOwnedWorktree: checkout.isPaseoOwnedWorktree,
+            mainRepoRoot: checkout.mainRepoRoot,
         });
         return {
             projectKey,
@@ -699,28 +797,29 @@ export class Session {
     async forwardAgentUpdate(agent) {
         try {
             const subscription = this.agentUpdatesSubscription;
-            if (!subscription) {
-                return;
-            }
             const payload = await this.buildAgentPayload(agent);
-            const project = await this.buildProjectPlacement(payload.cwd);
-            const matches = this.matchesAgentFilter({
-                agent: payload,
-                project,
-                filter: subscription.filter,
-            });
-            if (matches) {
-                this.bufferOrEmitAgentUpdate(subscription, {
-                    kind: 'upsert',
+            if (subscription) {
+                const project = await this.buildProjectPlacement(payload.cwd);
+                const matches = this.matchesAgentFilter({
                     agent: payload,
                     project,
+                    filter: subscription.filter,
                 });
-                return;
+                if (matches) {
+                    this.bufferOrEmitAgentUpdate(subscription, {
+                        kind: 'upsert',
+                        agent: payload,
+                        project,
+                    });
+                }
+                else {
+                    this.bufferOrEmitAgentUpdate(subscription, {
+                        kind: 'remove',
+                        agentId: payload.id,
+                    });
+                }
             }
-            this.bufferOrEmitAgentUpdate(subscription, {
-                kind: 'remove',
-                agentId: payload.id,
-            });
+            await this.emitWorkspaceUpdateForCwd(payload.cwd);
         }
         catch (error) {
             this.sessionLogger.error({ err: error }, 'Failed to emit agent update');
@@ -744,6 +843,9 @@ export class Session {
                 case 'fetch_agents_request':
                     await this.handleFetchAgents(msg);
                     break;
+                case 'fetch_workspaces_request':
+                    await this.handleFetchWorkspacesRequest(msg);
+                    break;
                 case 'fetch_agent_request':
                     await this.handleFetchAgent(msg.agentId, msg.requestId);
                     break;
@@ -813,6 +915,9 @@ export class Session {
                 case 'restart_server_request':
                     await this.handleRestartServerRequest(msg.requestId, msg.reason);
                     break;
+                case 'shutdown_server_request':
+                    await this.handleShutdownServerRequest(msg.requestId);
+                    break;
                 case 'fetch_agent_timeline_request':
                     await this.handleFetchAgentTimelineRequest(msg);
                     break;
@@ -1032,11 +1137,6 @@ export class Session {
         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');
-            return;
-        }
-        restartRequested = true;
         const payload = {
             status: 'restart_requested',
             clientId: this.clientId,
@@ -1050,19 +1150,45 @@ export class Session {
             type: 'status',
             payload,
         });
-        if (typeof process.send === 'function') {
-            process.send({
-                type: 'paseo:restart',
-                ...(reason ? { reason } : {}),
-            });
+        this.emitLifecycleIntent({
+            type: 'restart',
+            clientId: this.clientId,
+            requestId,
+            ...(reason ? { reason } : {}),
+        });
+    }
+    async handleShutdownServerRequest(requestId) {
+        this.sessionLogger.warn('Shutdown requested via websocket');
+        this.emit({
+            type: 'status',
+            payload: {
+                status: 'shutdown_requested',
+                clientId: this.clientId,
+                requestId,
+            },
+        });
+        this.emitLifecycleIntent({
+            type: 'shutdown',
+            clientId: this.clientId,
+            requestId,
+        });
+    }
+    emitLifecycleIntent(intent) {
+        if (!this.onLifecycleIntent) {
             return;
         }
-        setTimeout(() => {
-            process.exit(0);
-        }, RESTART_EXIT_DELAY_MS);
+        try {
+            this.onLifecycleIntent(intent);
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, intent }, 'Lifecycle intent handler failed');
+        }
     }
     async handleDeleteAgentRequest(agentId, requestId) {
         this.sessionLogger.info({ agentId }, `Deleting agent ${agentId} from registry`);
+        const knownCwd = this.agentManager.getAgent(agentId)?.cwd ??
+            (await this.agentStorage.get(agentId))?.cwd ??
+            null;
         // Prevent the persistence hook from re-creating the record while we close/delete.
         this.agentStorage.beginDelete(agentId);
         try {
@@ -1090,9 +1216,32 @@ export class Session {
                 agentId,
             });
         }
+        if (knownCwd) {
+            await this.emitWorkspaceUpdateForCwd(knownCwd);
+        }
     }
     async handleArchiveAgentRequest(agentId, requestId) {
         this.sessionLogger.info({ agentId }, `Archiving agent ${agentId}`);
+        const { archivedAt, archivedRecord } = await this.archiveAgentState(agentId);
+        this.emit({
+            type: 'agent_archived',
+            payload: {
+                agentId,
+                archivedAt,
+                requestId,
+            },
+        });
+        await this.maybeArchiveWorktreeAfterLastAgentArchived({
+            archivedAgentId: agentId,
+            archivedAgentCwd: archivedRecord.cwd,
+            requestId,
+        });
+    }
+    async archiveAgentState(agentId) {
+        if (this.agentManager.getAgent(agentId)) {
+            await this.interruptAgentIfRunning(agentId);
+            await this.agentManager.clearAgentAttention(agentId).catch(() => undefined);
+        }
         const archivedAt = new Date().toISOString();
         const existing = await this.agentStorage.get(agentId);
         let archivedRecord = existing;
@@ -1102,7 +1251,6 @@ export class Session {
                 throw new Error(`Agent not found: ${agentId}`);
             }
             await this.agentStorage.applySnapshot(liveAgent, {
-                title: liveAgent.config.title ?? null,
                 internal: liveAgent.internal,
             });
             archivedRecord = await this.agentStorage.get(agentId);
@@ -1110,25 +1258,41 @@ export class Session {
                 throw new Error(`Agent not found in storage after snapshot: ${agentId}`);
             }
         }
-        archivedRecord = {
+        const normalizedStatus = archivedRecord.lastStatus === 'running' || archivedRecord.lastStatus === 'initializing'
+            ? 'idle'
+            : archivedRecord.lastStatus;
+        const nextRecord = {
             ...archivedRecord,
             archivedAt,
+            lastStatus: normalizedStatus,
+            requiresAttention: false,
+            attentionReason: null,
+            attentionTimestamp: null,
         };
-        await this.agentStorage.upsert(archivedRecord);
+        await this.agentStorage.upsert(nextRecord);
         this.agentManager.notifyAgentState(agentId);
-        this.emit({
-            type: 'agent_archived',
-            payload: {
-                agentId,
-                archivedAt,
-                requestId,
-            },
-        });
-        await this.maybeArchiveWorktreeAfterLastAgentArchived({
-            archivedAgentId: agentId,
-            archivedAgentCwd: archivedRecord.cwd,
-            requestId,
+        return { archivedAt, archivedRecord: nextRecord };
+    }
+    async unarchiveAgentState(agentId) {
+        const record = await this.agentStorage.get(agentId);
+        if (!record || !record.archivedAt) {
+            return false;
+        }
+        await this.agentStorage.upsert({
+            ...record,
+            archivedAt: null,
         });
+        this.agentManager.notifyAgentState(agentId);
+        return true;
+    }
+    async unarchiveAgentByHandle(handle) {
+        const records = await this.agentStorage.list();
+        const matched = records.find((record) => record.persistence?.provider === handle.provider &&
+            record.persistence?.sessionId === handle.sessionId);
+        if (!matched) {
+            return;
+        }
+        await this.unarchiveAgentState(matched.id);
     }
     async handleUpdateAgentRequest(agentId, name, labels, requestId) {
         this.sessionLogger.info({
@@ -1601,6 +1765,7 @@ export class Session {
      */
     async handleSendAgentMessage(agentId, text, messageId, images, runOptions) {
         this.sessionLogger.info({ agentId, textPreview: text.substring(0, 50), imageCount: images?.length ?? 0 }, `Sending text to agent ${agentId}${images && images.length > 0 ? ` with ${images.length} image attachment(s)` : ''}`);
+        await this.unarchiveAgentState(agentId);
         try {
             await this.ensureAgentLoaded(agentId);
         }
@@ -1631,27 +1796,47 @@ export class Session {
      * Handle create agent request
      */
     async handleCreateAgentRequest(msg) {
-        const { config, worktreeName, requestId, initialPrompt, outputSchema, git, images, labels } = msg;
+        const { config, worktreeName, requestId, initialPrompt, clientMessageId, outputSchema, git, images, labels, } = msg;
         this.sessionLogger.info({ cwd: config.cwd, provider: config.provider, worktreeName }, `Creating agent in ${config.cwd} (${config.provider})${worktreeName ? ` with worktree ${worktreeName}` : ''}`);
         try {
-            const { sessionConfig, worktreeConfig } = await this.buildAgentSessionConfig(config, git, worktreeName, labels);
+            const trimmedPrompt = initialPrompt?.trim();
+            const { explicitTitle, provisionalTitle } = resolveCreateAgentTitles({
+                configTitle: config.title,
+                initialPrompt: trimmedPrompt,
+            });
+            const resolvedConfig = {
+                ...config,
+                ...(provisionalTitle ? { title: provisionalTitle } : {}),
+            };
+            const { sessionConfig, worktreeConfig } = await this.buildAgentSessionConfig(resolvedConfig, git, worktreeName, labels);
             const snapshot = await this.agentManager.createAgent(sessionConfig, undefined, { labels });
             await this.forwardAgentUpdate(snapshot);
-            const trimmedPrompt = initialPrompt?.trim();
+            if (requestId) {
+                const agentPayload = await this.getAgentPayloadById(snapshot.id);
+                if (!agentPayload) {
+                    throw new Error(`Agent ${snapshot.id} not found after creation`);
+                }
+                this.emit({
+                    type: 'status',
+                    payload: {
+                        status: 'agent_created',
+                        agentId: snapshot.id,
+                        requestId,
+                        agent: agentPayload,
+                    },
+                });
+            }
             if (trimmedPrompt) {
                 scheduleAgentMetadataGeneration({
                     agentManager: this.agentManager,
                     agentId: snapshot.id,
                     cwd: snapshot.cwd,
                     initialPrompt: trimmedPrompt,
-                    explicitTitle: snapshot.config.title,
+                    explicitTitle,
                     paseoHome: this.paseoHome,
                     logger: this.sessionLogger,
                 });
-                try {
-                    await this.handleSendAgentMessage(snapshot.id, trimmedPrompt, uuidv4(), images, outputSchema ? { outputSchema } : undefined);
-                }
-                catch (promptError) {
+                void this.handleSendAgentMessage(snapshot.id, trimmedPrompt, resolveClientMessageId(clientMessageId), images, outputSchema ? { outputSchema } : undefined).catch((promptError) => {
                     this.sessionLogger.error({ err: promptError, agentId: snapshot.id }, `Failed to run initial prompt for agent ${snapshot.id}`);
                     this.emit({
                         type: 'activity_log',
@@ -1662,21 +1847,6 @@ export class Session {
                             content: `Initial prompt failed: ${promptError?.message ?? promptError}`,
                         },
                     });
-                }
-            }
-            if (requestId) {
-                const agentPayload = await this.getAgentPayloadById(snapshot.id);
-                if (!agentPayload) {
-                    throw new Error(`Agent ${snapshot.id} not found after creation`);
-                }
-                this.emit({
-                    type: 'status',
-                    payload: {
-                        status: 'agent_created',
-                        agentId: snapshot.id,
-                        requestId,
-                        agent: agentPayload,
-                    },
                 });
             }
             if (worktreeConfig) {
@@ -1739,7 +1909,9 @@ export class Session {
         }
         this.sessionLogger.info({ sessionId: handle.sessionId, provider: handle.provider }, `Resuming agent ${handle.sessionId} (${handle.provider})`);
         try {
+            await this.unarchiveAgentByHandle(handle);
             const snapshot = await this.agentManager.resumeAgentFromPersistence(handle, overrides);
+            await this.unarchiveAgentState(snapshot.id);
             await this.agentManager.hydrateTimelineFromProvider(snapshot.id);
             await this.forwardAgentUpdate(snapshot);
             const timelineSize = this.agentManager.getTimeline(snapshot.id).length;
@@ -1777,6 +1949,7 @@ export class Session {
         const { agentId, requestId } = msg;
         this.sessionLogger.info({ agentId }, `Refreshing agent ${agentId} from persistence`);
         try {
+            await this.unarchiveAgentState(agentId);
             let snapshot;
             const existing = this.agentManager.getAgent(agentId);
             if (existing) {
@@ -2400,7 +2573,6 @@ export class Session {
      */
     async handleClearAgentAttention(agentId) {
         const agentIds = Array.isArray(agentId) ? agentId : [agentId];
-        this.sessionLogger.debug({ agentIds }, `Clearing attention for ${agentIds.length} agent(s): ${agentIds.join(', ')}`);
         try {
             await Promise.all(agentIds.map((id) => this.agentManager.clearAgentAttention(id)));
         }
@@ -3277,6 +3449,7 @@ export class Session {
                 payload: {
                     worktrees: worktrees.map((entry) => ({
                         worktreePath: entry.path,
+                        createdAt: entry.createdAt,
                         branchName: entry.branchName ?? null,
                         head: entry.head ?? null,
                     })),
@@ -3358,10 +3531,12 @@ export class Session {
             targetPath = resolvedWorktree.worktreePath;
         }
         const removedAgents = new Set();
+        const affectedWorkspaceCwds = new Set([targetPath]);
         const agents = this.agentManager.listAgents();
         for (const agent of agents) {
             if (this.isPathWithinRoot(targetPath, agent.cwd)) {
                 removedAgents.add(agent.id);
+                affectedWorkspaceCwds.add(agent.cwd);
                 try {
                     await this.agentManager.closeAgent(agent.id);
                 }
@@ -3380,6 +3555,7 @@ export class Session {
         for (const record of registryRecords) {
             if (this.isPathWithinRoot(targetPath, record.cwd)) {
                 removedAgents.add(record.id);
+                affectedWorkspaceCwds.add(record.cwd);
                 try {
                     await this.agentStorage.remove(record.id);
                 }
@@ -3403,6 +3579,7 @@ export class Session {
                 },
             });
         }
+        await this.emitWorkspaceUpdatesForCwds(affectedWorkspaceCwds);
         return Array.from(removedAgents);
     }
     async handlePaseoWorktreeArchiveRequest(msg) {
@@ -3471,38 +3648,36 @@ export class Session {
         }
     }
     /**
-     * Handle read-only file explorer requests scoped to an agent's cwd
+     * Handle read-only file explorer requests scoped to a workspace cwd
      */
     async handleFileExplorerRequest(request) {
-        const { agentId, path: requestedPath = '.', mode, requestId } = request;
-        this.sessionLogger.debug({ agentId, mode, path: requestedPath }, `Handling file explorer request for agent ${agentId} (${mode} ${requestedPath})`);
+        const { cwd: workspaceCwd, path: requestedPath = '.', mode, requestId } = request;
+        const cwd = workspaceCwd.trim();
+        if (!cwd) {
+            this.emit({
+                type: 'file_explorer_response',
+                payload: {
+                    cwd: workspaceCwd,
+                    path: requestedPath,
+                    mode,
+                    directory: null,
+                    file: null,
+                    error: 'cwd is required',
+                    requestId,
+                },
+            });
+            return;
+        }
         try {
-            const agents = this.agentManager.listAgents();
-            const agent = agents.find((a) => a.id === agentId);
-            if (!agent) {
-                this.emit({
-                    type: 'file_explorer_response',
-                    payload: {
-                        agentId,
-                        path: requestedPath,
-                        mode,
-                        directory: null,
-                        file: null,
-                        error: `Agent not found: ${agentId}`,
-                        requestId,
-                    },
-                });
-                return;
-            }
             if (mode === 'list') {
                 const directory = await listDirectoryEntries({
-                    root: agent.cwd,
+                    root: cwd,
                     relativePath: requestedPath,
                 });
                 this.emit({
                     type: 'file_explorer_response',
                     payload: {
-                        agentId,
+                        cwd,
                         path: directory.path,
                         mode,
                         directory,
@@ -3514,13 +3689,13 @@ export class Session {
             }
             else {
                 const file = await readExplorerFile({
-                    root: agent.cwd,
+                    root: cwd,
                     relativePath: requestedPath,
                 });
                 this.emit({
                     type: 'file_explorer_response',
                     payload: {
-                        agentId,
+                        cwd,
                         path: file.path,
                         mode,
                         directory: null,
@@ -3532,11 +3707,11 @@ export class Session {
             }
         }
         catch (error) {
-            this.sessionLogger.error({ err: error, agentId, path: requestedPath }, `Failed to fulfill file explorer request for agent ${agentId}`);
+            this.sessionLogger.error({ err: error, cwd, path: requestedPath }, `Failed to fulfill file explorer request for workspace ${cwd}`);
             this.emit({
                 type: 'file_explorer_response',
                 payload: {
-                    agentId,
+                    cwd,
                     path: requestedPath,
                     mode,
                     directory: null,
@@ -3577,36 +3752,34 @@ export class Session {
         }
     }
     /**
-     * Handle file download token request scoped to an agent's cwd
+     * Handle file download token request scoped to a workspace cwd
      */
     async handleFileDownloadTokenRequest(request) {
-        const { agentId, path: requestedPath, requestId } = request;
-        this.sessionLogger.debug({ agentId, path: requestedPath }, `Handling file download token request for agent ${agentId} (${requestedPath})`);
+        const { cwd: workspaceCwd, path: requestedPath, requestId } = request;
+        const cwd = workspaceCwd.trim();
+        if (!cwd) {
+            this.emit({
+                type: 'file_download_token_response',
+                payload: {
+                    cwd: workspaceCwd,
+                    path: requestedPath,
+                    token: null,
+                    fileName: null,
+                    mimeType: null,
+                    size: null,
+                    error: 'cwd is required',
+                    requestId,
+                },
+            });
+            return;
+        }
+        this.sessionLogger.debug({ cwd, path: requestedPath }, `Handling file download token request for workspace ${cwd} (${requestedPath})`);
         try {
-            const agents = this.agentManager.listAgents();
-            const agent = agents.find((a) => a.id === agentId);
-            if (!agent) {
-                this.emit({
-                    type: 'file_download_token_response',
-                    payload: {
-                        agentId,
-                        path: requestedPath,
-                        token: null,
-                        fileName: null,
-                        mimeType: null,
-                        size: null,
-                        error: `Agent not found: ${agentId}`,
-                        requestId,
-                    },
-                });
-                return;
-            }
             const info = await getDownloadableFileInfo({
-                root: agent.cwd,
+                root: cwd,
                 relativePath: requestedPath,
             });
             const entry = this.downloadTokenStore.issueToken({
-                agentId,
                 path: info.path,
                 absolutePath: info.absolutePath,
                 fileName: info.fileName,
@@ -3616,7 +3789,7 @@ export class Session {
             this.emit({
                 type: 'file_download_token_response',
                 payload: {
-                    agentId,
+                    cwd,
                     path: info.path,
                     token: entry.token,
                     fileName: entry.fileName,
@@ -3628,11 +3801,11 @@ export class Session {
             });
         }
         catch (error) {
-            this.sessionLogger.error({ err: error, agentId, path: requestedPath }, `Failed to issue download token for agent ${agentId}`);
+            this.sessionLogger.error({ err: error, cwd, path: requestedPath }, `Failed to issue download token for workspace ${cwd}`);
             this.emit({
                 type: 'file_download_token_response',
                 payload: {
-                    agentId,
+                    cwd,
                     path: requestedPath,
                     token: null,
                     fileName: null,
@@ -3739,9 +3912,9 @@ export class Session {
         return deduped.length > 0 ? deduped : fallback;
     }
     getStatusPriority(agent) {
-        const requiresAttention = agent.requiresAttention ?? false;
         const attentionReason = agent.attentionReason ?? null;
-        if (requiresAttention && attentionReason === 'permission') {
+        const hasPendingPermission = (agent.pendingPermissions?.length ?? 0) > 0;
+        if (hasPendingPermission || attentionReason === 'permission') {
             return 0;
         }
         if (agent.status === 'error' || attentionReason === 'error') {
@@ -3767,6 +3940,18 @@ export class Session {
                 return entry.agent.title?.toLocaleLowerCase() ?? '';
         }
     }
+    getFetchAgentsSortValueFromAgent(agent, key) {
+        switch (key) {
+            case 'status_priority':
+                return this.getStatusPriority(agent);
+            case 'created_at':
+                return Date.parse(agent.createdAt);
+            case 'updated_at':
+                return Date.parse(agent.updatedAt);
+            case 'title':
+                return agent.title?.toLocaleLowerCase() ?? '';
+        }
+    }
     compareSortValues(left, right) {
         if (left === right) {
             return 0;
@@ -3782,17 +3967,17 @@ export class Session {
         }
         return String(left).localeCompare(String(right));
     }
-    compareFetchAgentsEntries(left, right, sort) {
+    compareFetchAgentsAgents(left, right, sort) {
         for (const spec of sort) {
-            const leftValue = this.getFetchAgentsSortValue(left, spec.key);
-            const rightValue = this.getFetchAgentsSortValue(right, spec.key);
+            const leftValue = this.getFetchAgentsSortValueFromAgent(left, spec.key);
+            const rightValue = this.getFetchAgentsSortValueFromAgent(right, spec.key);
             const base = this.compareSortValues(leftValue, rightValue);
             if (base === 0) {
                 continue;
             }
             return spec.direction === 'asc' ? base : -base;
         }
-        return left.agent.id.localeCompare(right.agent.id);
+        return left.id.localeCompare(right.id);
     }
     encodeFetchAgentsCursor(entry, sort) {
         const values = {};
@@ -3852,9 +4037,9 @@ export class Session {
             id: payload.id,
         };
     }
-    compareEntryWithCursor(entry, cursor, sort) {
+    compareAgentWithCursor(agent, cursor, sort) {
         for (const spec of sort) {
-            const leftValue = this.getFetchAgentsSortValue(entry, spec.key);
+            const leftValue = this.getFetchAgentsSortValueFromAgent(agent, spec.key);
             const rightValue = cursor.values[spec.key] !== undefined ? (cursor.values[spec.key] ?? null) : null;
             const base = this.compareSortValues(leftValue, rightValue);
             if (base === 0) {
@@ -3862,7 +4047,7 @@ export class Session {
             }
             return spec.direction === 'asc' ? base : -base;
         }
-        return entry.agent.id.localeCompare(cursor.id);
+        return agent.id.localeCompare(cursor.id);
     }
     async listFetchAgentsEntries(request) {
         const filter = request.filter;
@@ -3880,26 +4065,293 @@ export class Session {
             placementByCwd.set(cwd, placementPromise);
             return placementPromise;
         };
-        let entries = await Promise.all(agents.map(async (agent) => ({
-            agent,
-            project: await getPlacement(agent.cwd),
-        })));
-        entries = entries.filter((entry) => this.matchesAgentFilter({
-            agent: entry.agent,
-            project: entry.project,
-            filter,
-        }));
-        entries.sort((left, right) => this.compareFetchAgentsEntries(left, right, sort));
+        let candidates = [...agents];
+        candidates.sort((left, right) => this.compareFetchAgentsAgents(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);
+            candidates = candidates.filter((agent) => this.compareAgentWithCursor(agent, cursor, sort) > 0);
+        }
+        const limit = request.page?.limit ?? 200;
+        const matchedEntries = [];
+        const batchSize = 25;
+        for (let start = 0; start < candidates.length && matchedEntries.length <= limit; start += batchSize) {
+            const batch = candidates.slice(start, start + batchSize);
+            const batchEntries = await Promise.all(batch.map(async (agent) => ({
+                agent,
+                project: await getPlacement(agent.cwd),
+            })));
+            for (const entry of batchEntries) {
+                if (!this.matchesAgentFilter({
+                    agent: entry.agent,
+                    project: entry.project,
+                    filter,
+                })) {
+                    continue;
+                }
+                matchedEntries.push(entry);
+                if (matchedEntries.length > limit) {
+                    break;
+                }
+            }
+        }
+        const pagedEntries = matchedEntries.slice(0, limit);
+        const hasMore = matchedEntries.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,
+            },
+        };
+    }
+    normalizeWorkspaceId(cwd) {
+        const trimmed = cwd.trim();
+        if (!trimmed) {
+            return cwd;
         }
-        const limit = request.page?.limit ?? entries.length;
+        return resolve(trimmed);
+    }
+    deriveWorkspaceStateBucket(agent) {
+        const pendingPermissionCount = agent.pendingPermissions?.length ?? 0;
+        if (pendingPermissionCount > 0 || agent.attentionReason === 'permission') {
+            return 'needs_input';
+        }
+        if (agent.status === 'error' || agent.attentionReason === 'error') {
+            return 'failed';
+        }
+        if (agent.status === 'running' || agent.status === 'initializing') {
+            return 'running';
+        }
+        if (agent.requiresAttention) {
+            return 'attention';
+        }
+        return 'done';
+    }
+    deriveWorkspaceDirectoryName(cwd) {
+        const normalized = cwd.replace(/\\/g, '/');
+        const segments = normalized.split('/').filter(Boolean);
+        return segments[segments.length - 1] ?? cwd;
+    }
+    deriveWorkspaceName(input) {
+        const branch = input.checkout.currentBranch?.trim() ?? null;
+        if (branch && branch.toUpperCase() !== 'HEAD') {
+            return branch;
+        }
+        return this.deriveWorkspaceDirectoryName(input.cwd);
+    }
+    accumulateLatestActivityAt(current, agent) {
+        const candidateRaw = agent.lastUserMessageAt ?? agent.updatedAt;
+        const candidateMs = Date.parse(candidateRaw);
+        if (Number.isNaN(candidateMs)) {
+            return current;
+        }
+        if (!current) {
+            return new Date(candidateMs).toISOString();
+        }
+        const currentMs = Date.parse(current);
+        if (Number.isNaN(currentMs) || candidateMs > currentMs) {
+            return new Date(candidateMs).toISOString();
+        }
+        return current;
+    }
+    async listWorkspaceDescriptors() {
+        const agents = await this.listAgentPayloads();
+        const descriptorsByWorkspaceId = new Map();
+        const placementByWorkspaceId = new Map();
+        const getPlacement = (workspaceCwd) => {
+            const key = this.normalizeWorkspaceId(workspaceCwd);
+            const existing = placementByWorkspaceId.get(key);
+            if (existing) {
+                return existing;
+            }
+            const next = this.buildProjectPlacement(workspaceCwd);
+            placementByWorkspaceId.set(key, next);
+            return next;
+        };
+        for (const agent of agents) {
+            if (agent.archivedAt) {
+                continue;
+            }
+            const workspaceId = this.normalizeWorkspaceId(agent.cwd);
+            const placement = await getPlacement(workspaceId);
+            const existing = descriptorsByWorkspaceId.get(workspaceId);
+            if (!existing) {
+                const bucket = this.deriveWorkspaceStateBucket(agent);
+                descriptorsByWorkspaceId.set(workspaceId, {
+                    id: workspaceId,
+                    projectId: placement.projectKey,
+                    name: this.deriveWorkspaceName({
+                        cwd: workspaceId,
+                        checkout: placement.checkout,
+                    }),
+                    status: bucket,
+                    activityAt: this.accumulateLatestActivityAt(null, agent),
+                });
+                continue;
+            }
+            const bucket = this.deriveWorkspaceStateBucket(agent);
+            if (this.workspaceStatePriority[bucket] < this.workspaceStatePriority[existing.status]) {
+                existing.status = bucket;
+            }
+            existing.activityAt = this.accumulateLatestActivityAt(existing.activityAt, agent);
+        }
+        return Array.from(descriptorsByWorkspaceId.values());
+    }
+    normalizeFetchWorkspacesSort(sort) {
+        const fallback = [{ key: 'activity_at', direction: 'desc' }];
+        if (!sort || sort.length === 0) {
+            return fallback;
+        }
+        const deduped = [];
+        const seen = new Set();
+        for (const entry of sort) {
+            if (seen.has(entry.key)) {
+                continue;
+            }
+            seen.add(entry.key);
+            deduped.push(entry);
+        }
+        return deduped.length > 0 ? deduped : fallback;
+    }
+    getFetchWorkspacesSortValue(workspace, key) {
+        switch (key) {
+            case 'status_priority':
+                return this.workspaceStatePriority[workspace.status];
+            case 'activity_at':
+                return workspace.activityAt ? Date.parse(workspace.activityAt) : null;
+            case 'name':
+                return workspace.name.toLocaleLowerCase();
+            case 'project_id':
+                return workspace.projectId.toLocaleLowerCase();
+        }
+    }
+    compareFetchWorkspacesEntries(left, right, sort) {
+        for (const spec of sort) {
+            const leftValue = this.getFetchWorkspacesSortValue(left, spec.key);
+            const rightValue = this.getFetchWorkspacesSortValue(right, spec.key);
+            const base = this.compareSortValues(leftValue, rightValue);
+            if (base === 0) {
+                continue;
+            }
+            return spec.direction === 'asc' ? base : -base;
+        }
+        return left.id.localeCompare(right.id);
+    }
+    encodeFetchWorkspacesCursor(entry, sort) {
+        const values = {};
+        for (const spec of sort) {
+            values[spec.key] = this.getFetchWorkspacesSortValue(entry, spec.key);
+        }
+        return Buffer.from(JSON.stringify({
+            sort,
+            values,
+            id: entry.id,
+        }), 'utf8').toString('base64url');
+    }
+    decodeFetchWorkspacesCursor(cursor, sort) {
+        let parsed;
+        try {
+            parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+        }
+        catch {
+            throw new SessionRequestError('invalid_cursor', 'Invalid fetch_workspaces cursor');
+        }
+        if (!parsed || typeof parsed !== 'object') {
+            throw new SessionRequestError('invalid_cursor', 'Invalid fetch_workspaces cursor');
+        }
+        const payload = parsed;
+        if (!Array.isArray(payload.sort) || typeof payload.id !== 'string') {
+            throw new SessionRequestError('invalid_cursor', 'Invalid fetch_workspaces cursor');
+        }
+        if (!payload.values || typeof payload.values !== 'object') {
+            throw new SessionRequestError('invalid_cursor', 'Invalid fetch_workspaces cursor');
+        }
+        const cursorSort = [];
+        for (const item of payload.sort) {
+            if (!item ||
+                typeof item !== 'object' ||
+                typeof item.key !== 'string' ||
+                typeof item.direction !== 'string') {
+                throw new SessionRequestError('invalid_cursor', 'Invalid fetch_workspaces cursor');
+            }
+            const key = item.key;
+            const direction = item.direction;
+            if ((key !== 'status_priority' &&
+                key !== 'activity_at' &&
+                key !== 'name' &&
+                key !== 'project_id') ||
+                (direction !== 'asc' && direction !== 'desc')) {
+                throw new SessionRequestError('invalid_cursor', 'Invalid fetch_workspaces cursor');
+            }
+            cursorSort.push({ key, direction });
+        }
+        if (cursorSort.length !== sort.length ||
+            cursorSort.some((entry, index) => entry.key !== sort[index]?.key || entry.direction !== sort[index]?.direction)) {
+            throw new SessionRequestError('invalid_cursor', 'fetch_workspaces cursor does not match current sort');
+        }
+        return {
+            sort: cursorSort,
+            values: payload.values,
+            id: payload.id,
+        };
+    }
+    compareWorkspaceWithCursor(workspace, cursor, sort) {
+        for (const spec of sort) {
+            const leftValue = this.getFetchWorkspacesSortValue(workspace, spec.key);
+            const rightValue = cursor.values[spec.key] !== undefined ? (cursor.values[spec.key] ?? null) : null;
+            const base = this.compareSortValues(leftValue, rightValue);
+            if (base === 0) {
+                continue;
+            }
+            return spec.direction === 'asc' ? base : -base;
+        }
+        return workspace.id.localeCompare(cursor.id);
+    }
+    matchesWorkspaceFilter(input) {
+        const { workspace, filter } = input;
+        if (!filter) {
+            return true;
+        }
+        if (filter.projectId && filter.projectId.trim().length > 0) {
+            if (workspace.projectId !== filter.projectId.trim()) {
+                return false;
+            }
+        }
+        if (filter.idPrefix && filter.idPrefix.trim().length > 0) {
+            if (!workspace.id.startsWith(filter.idPrefix.trim())) {
+                return false;
+            }
+        }
+        if (filter.query && filter.query.trim().length > 0) {
+            const query = filter.query.trim().toLocaleLowerCase();
+            const haystacks = [workspace.name, workspace.projectId, workspace.id];
+            if (!haystacks.some((value) => value.toLocaleLowerCase().includes(query))) {
+                return false;
+            }
+        }
+        return true;
+    }
+    async listFetchWorkspacesEntries(request) {
+        const filter = request.filter;
+        const sort = this.normalizeFetchWorkspacesSort(request.sort);
+        let entries = await this.listWorkspaceDescriptors();
+        entries = entries.filter((workspace) => this.matchesWorkspaceFilter({ workspace, filter }));
+        entries.sort((left, right) => this.compareFetchWorkspacesEntries(left, right, sort));
+        const cursorToken = request.page?.cursor;
+        if (cursorToken) {
+            const cursor = this.decodeFetchWorkspacesCursor(cursorToken, sort);
+            entries = entries.filter((workspace) => this.compareWorkspaceWithCursor(workspace, cursor, sort) > 0);
+        }
+        const limit = request.page?.limit ?? 200;
         const pagedEntries = entries.slice(0, limit);
         const hasMore = entries.length > limit;
         const nextCursor = hasMore && pagedEntries.length > 0
-            ? this.encodeFetchAgentsCursor(pagedEntries[pagedEntries.length - 1], sort)
+            ? this.encodeFetchWorkspacesCursor(pagedEntries[pagedEntries.length - 1], sort)
             : null;
         return {
             entries: pagedEntries,
@@ -3910,6 +4362,86 @@ export class Session {
             },
         };
     }
+    bufferOrEmitWorkspaceUpdate(subscription, payload) {
+        if (subscription.isBootstrapping) {
+            const workspaceId = payload.kind === 'upsert' ? payload.workspace.id : payload.id;
+            subscription.pendingUpdatesByWorkspaceId.set(workspaceId, payload);
+            return;
+        }
+        this.emit({
+            type: 'workspace_update',
+            payload,
+        });
+    }
+    flushBootstrappedWorkspaceUpdates(options) {
+        const subscription = this.workspaceUpdatesSubscription;
+        if (!subscription || !subscription.isBootstrapping) {
+            return;
+        }
+        subscription.isBootstrapping = false;
+        const pending = Array.from(subscription.pendingUpdatesByWorkspaceId.values());
+        subscription.pendingUpdatesByWorkspaceId.clear();
+        for (const payload of pending) {
+            if (payload.kind === 'upsert') {
+                const snapshotLatestActivity = options?.snapshotLatestActivityByWorkspaceId?.get(payload.workspace.id);
+                if (typeof snapshotLatestActivity === 'number') {
+                    const updateLatestActivity = payload.workspace.activityAt
+                        ? Date.parse(payload.workspace.activityAt)
+                        : Number.NEGATIVE_INFINITY;
+                    if (!Number.isNaN(updateLatestActivity) && updateLatestActivity <= snapshotLatestActivity) {
+                        continue;
+                    }
+                }
+            }
+            this.emit({
+                type: 'workspace_update',
+                payload,
+            });
+        }
+    }
+    async emitWorkspaceUpdateForCwd(cwd) {
+        const subscription = this.workspaceUpdatesSubscription;
+        if (!subscription) {
+            return;
+        }
+        const workspaceId = this.normalizeWorkspaceId(cwd);
+        const all = await this.listWorkspaceDescriptors();
+        const workspace = all.find((entry) => entry.id === workspaceId);
+        if (!workspace) {
+            this.bufferOrEmitWorkspaceUpdate(subscription, {
+                kind: 'remove',
+                id: workspaceId,
+            });
+            return;
+        }
+        if (!this.matchesWorkspaceFilter({ workspace, filter: subscription.filter })) {
+            this.bufferOrEmitWorkspaceUpdate(subscription, {
+                kind: 'remove',
+                id: workspaceId,
+            });
+            return;
+        }
+        this.bufferOrEmitWorkspaceUpdate(subscription, {
+            kind: 'upsert',
+            workspace,
+        });
+    }
+    async emitWorkspaceUpdatesForCwds(cwds) {
+        if (!this.workspaceUpdatesSubscription) {
+            return;
+        }
+        const uniqueWorkspaceCwds = new Set();
+        for (const cwd of cwds) {
+            const normalized = this.normalizeWorkspaceId(cwd);
+            if (!normalized) {
+                continue;
+            }
+            uniqueWorkspaceCwds.add(normalized);
+        }
+        for (const workspaceCwd of uniqueWorkspaceCwds) {
+            await this.emitWorkspaceUpdateForCwd(workspaceCwd);
+        }
+    }
     async handleFetchAgents(request) {
         const requestedSubscriptionId = request.subscribe?.subscriptionId?.trim();
         const subscriptionId = request.subscribe
@@ -3964,12 +4496,68 @@ export class Session {
             });
         }
     }
+    async handleFetchWorkspacesRequest(request) {
+        const requestedSubscriptionId = request.subscribe?.subscriptionId?.trim();
+        const subscriptionId = request.subscribe
+            ? requestedSubscriptionId && requestedSubscriptionId.length > 0
+                ? requestedSubscriptionId
+                : uuidv4()
+            : null;
+        try {
+            if (subscriptionId) {
+                this.workspaceUpdatesSubscription = {
+                    subscriptionId,
+                    filter: request.filter,
+                    isBootstrapping: true,
+                    pendingUpdatesByWorkspaceId: new Map(),
+                };
+            }
+            const payload = await this.listFetchWorkspacesEntries(request);
+            const snapshotLatestActivityByWorkspaceId = new Map();
+            for (const entry of payload.entries) {
+                const parsedLatestActivity = entry.activityAt
+                    ? Date.parse(entry.activityAt)
+                    : Number.NEGATIVE_INFINITY;
+                if (!Number.isNaN(parsedLatestActivity)) {
+                    snapshotLatestActivityByWorkspaceId.set(entry.id, parsedLatestActivity);
+                }
+            }
+            this.emit({
+                type: 'fetch_workspaces_response',
+                payload: {
+                    requestId: request.requestId,
+                    ...(subscriptionId ? { subscriptionId } : {}),
+                    ...payload,
+                },
+            });
+            if (subscriptionId && this.workspaceUpdatesSubscription?.subscriptionId === subscriptionId) {
+                this.flushBootstrappedWorkspaceUpdates({ snapshotLatestActivityByWorkspaceId });
+            }
+        }
+        catch (error) {
+            if (subscriptionId && this.workspaceUpdatesSubscription?.subscriptionId === subscriptionId) {
+                this.workspaceUpdatesSubscription = null;
+            }
+            const code = error instanceof SessionRequestError ? error.code : 'fetch_workspaces_failed';
+            const message = error instanceof Error ? error.message : 'Failed to fetch workspaces';
+            this.sessionLogger.error({ err: error }, 'Failed to handle fetch_workspaces_request');
+            this.emit({
+                type: 'rpc_error',
+                payload: {
+                    requestId: request.requestId,
+                    requestType: request.type,
+                    error: message,
+                    code,
+                },
+            });
+        }
+    }
     async handleFetchAgent(agentIdOrIdentifier, requestId) {
         const resolved = await this.resolveAgentIdentifier(agentIdOrIdentifier);
         if (!resolved.ok) {
             this.emit({
                 type: 'fetch_agent_response',
-                payload: { requestId, agent: null, error: resolved.error },
+                payload: { requestId, agent: null, project: null, error: resolved.error },
             });
             return;
         }
@@ -3977,19 +4565,30 @@ export class Session {
         if (!agent) {
             this.emit({
                 type: 'fetch_agent_response',
-                payload: { requestId, agent: null, error: `Agent not found: ${resolved.agentId}` },
+                payload: {
+                    requestId,
+                    agent: null,
+                    project: null,
+                    error: `Agent not found: ${resolved.agentId}`,
+                },
             });
             return;
         }
+        const project = await this.buildProjectPlacement(agent.cwd);
         this.emit({
             type: 'fetch_agent_response',
-            payload: { requestId, agent, error: null },
+            payload: { requestId, agent, project, 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 requestedLimit = msg.limit;
+        const limit = requestedLimit ?? (direction === 'after' ? 0 : undefined);
+        const shouldLimitByProjectedWindow = projection === 'canonical' &&
+            direction === 'tail' &&
+            typeof requestedLimit === 'number' &&
+            requestedLimit > 0;
         const cursor = msg.cursor
             ? {
                 epoch: msg.cursor.epoch,
@@ -3998,21 +4597,81 @@ export class Session {
             : undefined;
         try {
             const snapshot = await this.ensureAgentLoaded(msg.agentId);
-            const timeline = this.agentManager.fetchTimeline(msg.agentId, {
+            const agentPayload = await this.buildAgentPayload(snapshot);
+            let 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;
+                limit: shouldLimitByProjectedWindow && typeof requestedLimit === 'number'
+                    ? Math.max(1, Math.floor(requestedLimit))
+                    : limit,
+            });
+            let hasOlder = timeline.hasOlder;
+            let hasNewer = timeline.hasNewer;
+            let startCursor = null;
+            let endCursor = null;
+            let entries;
+            if (shouldLimitByProjectedWindow) {
+                const projectedLimit = Math.max(1, Math.floor(requestedLimit));
+                let fetchLimit = projectedLimit;
+                let projectedWindow = selectTimelineWindowByProjectedLimit({
+                    rows: timeline.rows,
+                    provider: snapshot.provider,
+                    direction,
+                    limit: projectedLimit,
+                    collapseToolLifecycle: false,
+                });
+                while (timeline.hasOlder) {
+                    const needsMoreProjectedEntries = projectedWindow.projectedEntries.length < projectedLimit;
+                    const firstLoadedRow = timeline.rows[0];
+                    const firstSelectedRow = projectedWindow.selectedRows[0];
+                    const startsAtLoadedBoundary = firstLoadedRow != null &&
+                        firstSelectedRow != null &&
+                        firstSelectedRow.seq === firstLoadedRow.seq;
+                    const boundaryIsAssistantChunk = startsAtLoadedBoundary && firstLoadedRow.item.type === 'assistant_message';
+                    if (!needsMoreProjectedEntries && !boundaryIsAssistantChunk) {
+                        break;
+                    }
+                    const maxRows = Math.max(0, timeline.window.maxSeq - timeline.window.minSeq + 1);
+                    const nextFetchLimit = Math.min(maxRows, fetchLimit * 2);
+                    if (nextFetchLimit <= fetchLimit) {
+                        break;
+                    }
+                    fetchLimit = nextFetchLimit;
+                    timeline = this.agentManager.fetchTimeline(msg.agentId, {
+                        direction,
+                        cursor,
+                        limit: fetchLimit,
+                    });
+                    projectedWindow = selectTimelineWindowByProjectedLimit({
+                        rows: timeline.rows,
+                        provider: snapshot.provider,
+                        direction,
+                        limit: projectedLimit,
+                        collapseToolLifecycle: false,
+                    });
+                }
+                const selectedRows = projectedWindow.selectedRows;
+                entries = projectTimelineRows(selectedRows, snapshot.provider, projection);
+                if (projectedWindow.minSeq !== null && projectedWindow.maxSeq !== null) {
+                    startCursor = { epoch: timeline.epoch, seq: projectedWindow.minSeq };
+                    endCursor = { epoch: timeline.epoch, seq: projectedWindow.maxSeq };
+                    hasOlder = projectedWindow.minSeq > timeline.window.minSeq;
+                    hasNewer = false;
+                }
+            }
+            else {
+                const firstRow = timeline.rows[0];
+                const lastRow = timeline.rows[timeline.rows.length - 1];
+                startCursor = firstRow ? { epoch: timeline.epoch, seq: firstRow.seq } : null;
+                endCursor = lastRow ? { epoch: timeline.epoch, seq: lastRow.seq } : null;
+                entries = projectTimelineRows(timeline.rows, snapshot.provider, projection);
+            }
             this.emit({
                 type: 'fetch_agent_timeline_response',
                 payload: {
                     requestId: msg.requestId,
                     agentId: msg.agentId,
+                    agent: agentPayload,
                     direction,
                     projection,
                     epoch: timeline.epoch,
@@ -4022,9 +4681,9 @@ export class Session {
                     window: timeline.window,
                     startCursor,
                     endCursor,
-                    hasOlder: timeline.hasOlder,
-                    hasNewer: timeline.hasNewer,
-                    entries: projected,
+                    hasOlder,
+                    hasNewer,
+                    entries,
                     error: null,
                 },
             });
@@ -4036,6 +4695,7 @@ export class Session {
                 payload: {
                     requestId: msg.requestId,
                     agentId: msg.agentId,
+                    agent: null,
                     direction,
                     projection,
                     epoch: '',
@@ -4069,6 +4729,7 @@ export class Session {
         }
         try {
             const agentId = resolved.agentId;
+            await this.unarchiveAgentState(agentId);
             await this.ensureAgentLoaded(agentId);
             await this.interruptAgentIfRunning(agentId);
             try {
@@ -4188,19 +4849,21 @@ export class Session {
             return;
         }
         const abortController = new AbortController();
-        const effectiveTimeoutMs = timeoutMs ?? 600000; // 10 minutes default
-        const timeoutHandle = setTimeout(() => {
-            abortController.abort('timeout');
-        }, effectiveTimeoutMs);
+        const hasTimeout = typeof timeoutMs === 'number' && timeoutMs > 0;
+        const timeoutHandle = hasTimeout
+            ? setTimeout(() => {
+                abortController.abort('timeout');
+            }, timeoutMs)
+            : null;
         try {
-            const result = await this.agentManager.waitForAgentEvent(agentId, {
+            let result = await this.agentManager.waitForAgentEvent(agentId, {
                 signal: abortController.signal,
             });
-            const final = await this.getAgentPayloadById(agentId);
+            let final = await this.getAgentPayloadById(agentId);
             if (!final) {
                 throw new Error(`Agent ${agentId} disappeared while waiting`);
             }
-            const status = result.permission ? 'permission' : result.status === 'error' ? 'error' : 'idle';
+            let status = result.permission ? 'permission' : result.status === 'error' ? 'error' : 'idle';
             this.emit({
                 type: 'wait_for_finish_response',
                 payload: { requestId, status, final, error: null, lastMessage: result.lastMessage },
@@ -4239,7 +4902,9 @@ export class Session {
             });
         }
         finally {
-            clearTimeout(timeoutHandle);
+            if (timeoutHandle) {
+                clearTimeout(timeoutHandle);
+            }
         }
     }
     /**
@@ -4512,7 +5177,7 @@ export class Session {
             });
         });
         this.registerVoiceCallerContext?.(agentId, {
-            childAgentDefaultLabels: { ui: 'true' },
+            childAgentDefaultLabels: {},
             allowCustomCwd: false,
             enableVoiceTools: true,
         });
@@ -4736,7 +5401,6 @@ export class Session {
         if (this.agentMcpClient) {
             try {
                 await this.agentMcpClient.close();
-                this.sessionLogger.debug('Agent MCP client closed');
             }
             catch (error) {
                 this.sessionLogger.error({ err: error }, 'Failed to close Agent MCP client');
@@ -4832,17 +5496,11 @@ export class Session {
         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;
             }
@@ -5115,10 +5773,16 @@ export class Session {
         }
         const existingStreamId = this.terminalStreamByTerminalId.get(msg.terminalId);
         if (typeof existingStreamId === 'number') {
-            this.detachTerminalStream(existingStreamId, { emitExit: false });
+            // Replacing an active stream can happen when multiple UI surfaces attach to the
+            // same terminal. Emit exit for the replaced stream so stale listeners reconnect
+            // instead of continuing to send input to an invalid stream id.
+            this.detachTerminalStream(existingStreamId, { emitExit: true });
         }
         const streamId = this.allocateTerminalStreamId();
-        const initialOffset = Math.max(0, Math.floor(msg.resumeOffset ?? 0));
+        const requestedResumeOffset = typeof msg.resumeOffset === 'number'
+            ? msg.resumeOffset
+            : session.getOutputOffset();
+        const initialOffset = Math.max(0, Math.floor(requestedResumeOffset));
         const binding = {
             terminalId: msg.terminalId,
             unsubscribe: () => { },
@@ -5142,7 +5806,7 @@ export class Session {
                     endOffset: chunk.endOffset,
                     replay: chunk.replay,
                 });
-            }, { fromOffset: msg.resumeOffset ?? 0 });
+            }, { fromOffset: requestedResumeOffset });
         }
         catch (error) {
             this.terminalStreams.delete(streamId);