@junctionpanel/server 0.1.16

package/dist/server/server/session.js

@@ -0,0 +1,4395 @@
+import { v4 as uuidv4 } from 'uuid';
+import { watch } from 'node:fs';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import { resolve, sep, basename, dirname } from 'path';
+import { homedir } from 'node:os';
+import { z } from 'zod';
+import { serializeAgentStreamEvent, } from './messages.js';
+import { BinaryMuxChannel, TerminalBinaryFlags, TerminalBinaryMessageType, } from '../shared/binary-mux.js';
+import { buildConfigOverrides, buildSessionConfig, extractTimestamps, extractTimelineSnapshot, } from './persistence-hooks.js';
+import { experimental_createMCPClient } from 'ai';
+import { buildProviderRegistry } from './agent/provider-registry.js';
+import { scheduleAgentMetadataGeneration } from './agent/agent-metadata-generator.js';
+import { resolveEffectiveThinkingOptionId, toAgentPayload } from './agent/agent-projections.js';
+import { appendTimelineItemIfAgentKnown, emitLiveTimelineItemIfAgentKnown, } from './agent/timeline-append.js';
+import { projectTimelineRows, selectTimelineWindowByProjectedLimit, } from './agent/timeline-projection.js';
+import { DEFAULT_STRUCTURED_GENERATION_PROVIDERS, StructuredAgentFallbackError, StructuredAgentResponseError, generateStructuredAgentResponseWithFallback, } from './agent/agent-response-loop.js';
+import { isValidAgentProvider, AGENT_PROVIDER_IDS } from './agent/provider-manifest.js';
+import { listDirectoryEntries, readExplorerFile, getDownloadableFileInfo, } from './file-explorer/service.js';
+import { slugify, validateBranchSlug, listJunctionWorktrees, deleteJunctionWorktree, isJunctionOwnedWorktreeCwd, resolveJunctionWorktreeRootForCwd, createInRepoWorktree, } from '../utils/worktree.js';
+import { runAsyncWorktreeBootstrap } from './worktree-bootstrap.js';
+import { getCheckoutDiff, getCheckoutStatus, getCheckoutStatusLite, listBranchSuggestions, NotGitRepoError, MergeConflictError, MergeFromBaseConflictError, commitChanges, mergeToBase, mergeFromBase, pushCurrentBranch, createPullRequest, getPullRequestStatus, resolveBaseRef, } from '../utils/checkout-git.js';
+import { getProjectIcon } from '../utils/project-icon.js';
+import { expandTilde } from '../utils/path.js';
+import { searchHomeDirectories, searchWorkspaceEntries, searchGitRepositories, checkIsGitRepo } from '../utils/directory-suggestions.js';
+import { cloneRepository } from '../utils/git-clone.js';
+import { initRepository } from '../utils/git-init.js';
+import { resolveClientMessageId } from './client-message-id.js';
+const execAsync = promisify(exec);
+const READ_ONLY_GIT_ENV = {
+    ...process.env,
+    GIT_OPTIONAL_LOCKS: '0',
+};
+const pendingAgentInitializations = new Map();
+const DEFAULT_AGENT_PROVIDER = AGENT_PROVIDER_IDS[0];
+const CHECKOUT_DIFF_WATCH_DEBOUNCE_MS = 150;
+const CHECKOUT_DIFF_FALLBACK_REFRESH_MS = 5000;
+const TERMINAL_STREAM_WINDOW_BYTES = 256 * 1024;
+const TERMINAL_STREAM_MAX_PENDING_BYTES = 2 * 1024 * 1024;
+const TERMINAL_STREAM_MAX_PENDING_CHUNKS = 2048;
+function deriveRemoteProjectKey(remoteUrl) {
+    if (!remoteUrl) {
+        return null;
+    }
+    const trimmed = remoteUrl.trim();
+    if (!trimmed) {
+        return null;
+    }
+    let host = null;
+    let path = null;
+    const scpLike = trimmed.match(/^[^@]+@([^:]+):(.+)$/);
+    if (scpLike) {
+        host = scpLike[1] ?? null;
+        path = scpLike[2] ?? null;
+    }
+    else if (trimmed.includes('://')) {
+        try {
+            const parsed = new URL(trimmed);
+            host = parsed.hostname || null;
+            path = parsed.pathname ? parsed.pathname.replace(/^\//, '') : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!host || !path) {
+        return null;
+    }
+    let cleanedPath = path.trim().replace(/^\/+/, '').replace(/\/+$/, '');
+    if (cleanedPath.endsWith('.git')) {
+        cleanedPath = cleanedPath.slice(0, -4);
+    }
+    if (!cleanedPath.includes('/')) {
+        return null;
+    }
+    const cleanedHost = host.toLowerCase();
+    if (cleanedHost === 'github.com') {
+        return `remote:github.com/${cleanedPath}`;
+    }
+    return `remote:${cleanedHost}/${cleanedPath}`;
+}
+function deriveProjectGroupingKey(options) {
+    const remoteKey = deriveRemoteProjectKey(options.remoteUrl);
+    if (remoteKey) {
+        return remoteKey;
+    }
+    const worktreeMarker = '.junction/';
+    const idx = options.cwd.indexOf(worktreeMarker);
+    if (idx !== -1) {
+        return options.cwd.slice(0, idx).replace(/\/$/, '');
+    }
+    return options.cwd;
+}
+function deriveProjectGroupingName(projectKey) {
+    const githubRemotePrefix = 'remote:github.com/';
+    if (projectKey.startsWith(githubRemotePrefix)) {
+        return projectKey.slice(githubRemotePrefix.length) || 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 SAFE_GIT_REF_PATTERN = /^[A-Za-z0-9._\/-]+$/;
+function coerceAgentProvider(logger, value, agentId) {
+    if (isValidAgentProvider(value)) {
+        return value;
+    }
+    logger.warn({ value, agentId, defaultProvider: DEFAULT_AGENT_PROVIDER }, `Unknown provider '${value}' for agent ${agentId ?? 'unknown'}; defaulting to '${DEFAULT_AGENT_PROVIDER}'`);
+    return DEFAULT_AGENT_PROVIDER;
+}
+function toAgentPersistenceHandle(logger, handle) {
+    if (!handle) {
+        return null;
+    }
+    const provider = handle.provider;
+    if (!isValidAgentProvider(provider)) {
+        logger.warn({ provider }, `Ignoring persistence handle with unknown provider '${provider}'`);
+        return null;
+    }
+    if (!handle.sessionId) {
+        logger.warn('Ignoring persistence handle missing sessionId');
+        return null;
+    }
+    return {
+        provider,
+        sessionId: handle.sessionId,
+        nativeHandle: handle.nativeHandle,
+        metadata: handle.metadata,
+    };
+}
+/**
+ * Session represents a single connected client session.
+ * It owns all state management, orchestration logic, and message processing.
+ * Session has no knowledge of WebSockets - it only emits and receives messages.
+ */
+export class Session {
+    constructor(options) {
+        // Per-session MCP client and tools
+        this.agentMcpClient = null;
+        this.agentTools = null;
+        this.unsubscribeAgentEvents = null;
+        this.agentUpdatesSubscription = null;
+        this.clientActivity = null;
+        this.MOBILE_BACKGROUND_STREAM_GRACE_MS = 60000;
+        this.subscribedTerminalDirectories = new Set();
+        this.unsubscribeTerminalsChanged = null;
+        this.terminalSubscriptions = new Map();
+        this.terminalExitSubscriptions = new Map();
+        this.terminalStreams = new Map();
+        this.terminalStreamByTerminalId = new Map();
+        this.nextTerminalStreamId = 1;
+        this.checkoutDiffSubscriptions = new Map();
+        this.checkoutDiffTargets = new Map();
+        const { clientId, userId, onMessage, onBinaryMessage, onLifecycleIntent, logger, downloadTokenStore, junctionHome, agentManager, agentStorage, createAgentMcpTransport, terminalManager, agentProviderRuntimeSettings, } = options;
+        this.clientId = clientId;
+        this.userId = userId;
+        this.sessionId = uuidv4();
+        this.onMessage = onMessage;
+        this.onBinaryMessage = onBinaryMessage ?? null;
+        this.onLifecycleIntent = onLifecycleIntent ?? null;
+        this.downloadTokenStore = downloadTokenStore;
+        this.junctionHome = junctionHome;
+        this.agentManager = agentManager;
+        this.agentStorage = agentStorage;
+        this.createAgentMcpTransport = createAgentMcpTransport;
+        this.terminalManager = terminalManager;
+        if (this.terminalManager) {
+            this.unsubscribeTerminalsChanged = this.terminalManager.subscribeTerminalsChanged((event) => this.handleTerminalsChanged(event));
+        }
+        this.agentProviderRuntimeSettings = agentProviderRuntimeSettings;
+        this.abortController = new AbortController();
+        this.sessionLogger = logger.child({
+            module: 'session',
+            clientId: this.clientId,
+            sessionId: this.sessionId,
+        });
+        this.providerRegistry = buildProviderRegistry(this.sessionLogger, {
+            runtimeSettings: this.agentProviderRuntimeSettings,
+        });
+        // Initialize agent MCP client asynchronously
+        void this.initializeAgentMcp();
+        this.subscribeToAgentEvents();
+        this.sessionLogger.trace('Session created');
+    }
+    /**
+     * Get the client's current activity state
+     */
+    getClientActivity() {
+        return this.clientActivity;
+    }
+    /**
+     * Send initial state to client after connection
+     */
+    async sendInitialState() {
+        // No unsolicited agent list hydration. Callers must use fetch_agents_request.
+    }
+    /**
+     * Normalize a user prompt (with optional image metadata) for AgentManager
+     */
+    buildAgentPrompt(text, images) {
+        const normalized = text?.trim() ?? '';
+        if (!images || images.length === 0) {
+            return normalized;
+        }
+        const blocks = [];
+        if (normalized.length > 0) {
+            blocks.push({ type: 'text', text: normalized });
+        }
+        for (const image of images) {
+            blocks.push({ type: 'image', data: image.data, mimeType: image.mimeType });
+        }
+        return blocks;
+    }
+    /**
+     * Interrupt the agent's active run so the next prompt starts a fresh turn.
+     * Returns once the manager confirms the stream has been cancelled.
+     */
+    async interruptAgentIfRunning(agentId) {
+        const snapshot = this.agentManager.getAgent(agentId);
+        if (!snapshot) {
+            throw new Error(`Agent ${agentId} not found`);
+        }
+        if (snapshot.lifecycle !== 'running' && !snapshot.pendingRun) {
+            return;
+        }
+        this.sessionLogger.debug({ agentId, lifecycle: snapshot.lifecycle, pendingRun: Boolean(snapshot.pendingRun) }, 'interruptAgentIfRunning: interrupting');
+        try {
+            const t0 = Date.now();
+            const cancelled = await this.agentManager.cancelAgentRun(agentId);
+            this.sessionLogger.debug({ agentId, cancelled, durationMs: Date.now() - t0 }, 'interruptAgentIfRunning: cancelAgentRun completed');
+            if (!cancelled) {
+                this.sessionLogger.warn({ agentId }, 'interruptAgentIfRunning: reported running but no active run was cancelled');
+            }
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * Start streaming an agent run and forward results via the websocket broadcast
+     */
+    startAgentStream(agentId, prompt, runOptions) {
+        let iterator;
+        try {
+            iterator = this.agentManager.streamAgent(agentId, prompt, runOptions);
+        }
+        catch (error) {
+            this.handleAgentRunError(agentId, error, 'Failed to start agent run');
+            const message = error instanceof Error ? error.message : typeof error === 'string' ? error : 'Unknown error';
+            return { ok: false, error: message };
+        }
+        void (async () => {
+            try {
+                for await (const _ of iterator) {
+                    // Events are forwarded via the session's AgentManager subscription.
+                }
+            }
+            catch (error) {
+                this.handleAgentRunError(agentId, error, 'Agent stream failed');
+            }
+        })();
+        return { ok: true };
+    }
+    handleAgentRunError(agentId, error, context) {
+        const message = error instanceof Error ? error.message : typeof error === 'string' ? error : 'Unknown error';
+        this.sessionLogger.error({ err: error, agentId, context }, `${context} for agent ${agentId}`);
+        this.emit({
+            type: 'activity_log',
+            payload: {
+                id: uuidv4(),
+                timestamp: new Date(),
+                type: 'error',
+                content: `${context}: ${message}`,
+            },
+        });
+    }
+    /**
+     * Initialize Agent MCP client for this session using in-memory transport
+     */
+    async initializeAgentMcp() {
+        try {
+            // Create an in-memory transport connected to the Agent MCP server
+            const transport = await this.createAgentMcpTransport();
+            this.agentMcpClient = await experimental_createMCPClient({
+                transport,
+            });
+            this.agentTools = (await this.agentMcpClient.tools());
+            const agentToolCount = Object.keys(this.agentTools ?? {}).length;
+            this.sessionLogger.trace({ agentToolCount }, `Agent MCP initialized with ${agentToolCount} tools`);
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error }, 'Failed to initialize Agent MCP');
+        }
+    }
+    /**
+     * Subscribe to AgentManager events and forward them to the client
+     */
+    subscribeToAgentEvents() {
+        if (this.unsubscribeAgentEvents) {
+            this.unsubscribeAgentEvents();
+        }
+        this.unsubscribeAgentEvents = this.agentManager.subscribe((event) => {
+            if (event.type === 'agent_state') {
+                void this.forwardAgentUpdate(event.agent);
+                return;
+            }
+            // Reduce bandwidth/CPU on mobile: only forward high-frequency agent stream events
+            // for the focused agent, with a short grace window while backgrounded.
+            // History catch-up is handled via pull-based `fetch_agent_timeline_request`.
+            const activity = this.clientActivity;
+            if (activity?.deviceType === 'mobile') {
+                if (!activity.focusedAgentId) {
+                    return;
+                }
+                if (activity.focusedAgentId !== event.agentId) {
+                    return;
+                }
+                if (!activity.appVisible) {
+                    const hiddenForMs = Date.now() - activity.appVisibilityChangedAt.getTime();
+                    if (hiddenForMs >= this.MOBILE_BACKGROUND_STREAM_GRACE_MS) {
+                        return;
+                    }
+                }
+            }
+            const serializedEvent = serializeAgentStreamEvent(event.event);
+            if (!serializedEvent) {
+                return;
+            }
+            const payload = {
+                agentId: event.agentId,
+                event: serializedEvent,
+                timestamp: new Date().toISOString(),
+                ...(typeof event.seq === 'number' ? { seq: event.seq } : {}),
+                ...(typeof event.epoch === 'string' ? { epoch: event.epoch } : {}),
+            };
+            this.emit({
+                type: 'agent_stream',
+                payload,
+            });
+            if (event.event.type === 'permission_requested') {
+                this.emit({
+                    type: 'agent_permission_request',
+                    payload: {
+                        agentId: event.agentId,
+                        request: event.event.request,
+                    },
+                });
+            }
+            else if (event.event.type === 'permission_resolved') {
+                this.emit({
+                    type: 'agent_permission_resolved',
+                    payload: {
+                        agentId: event.agentId,
+                        requestId: event.event.requestId,
+                        resolution: event.event.resolution,
+                    },
+                });
+            }
+            // Title updates may be applied asynchronously after agent creation.
+        }, { replayState: false });
+    }
+    async buildAgentPayload(agent) {
+        const storedRecord = await this.agentStorage.get(agent.id);
+        const title = storedRecord?.title ?? null;
+        const payload = toAgentPayload(agent, { title });
+        payload.archivedAt = storedRecord?.archivedAt ?? null;
+        return payload;
+    }
+    buildStoredAgentPayload(record) {
+        const defaultCapabilities = {
+            supportsStreaming: false,
+            supportsSessionPersistence: true,
+            supportsDynamicModes: false,
+            supportsMcpServers: false,
+            supportsReasoningStream: false,
+            supportsToolInvocations: true,
+        };
+        const createdAt = new Date(record.createdAt);
+        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,
+            status: record.lastStatus,
+            capabilities: defaultCapabilities,
+            currentModeId: record.lastModeId ?? null,
+            availableModes: [],
+            pendingPermissions: [],
+            persistence: toAgentPersistenceHandle(this.sessionLogger, record.persistence),
+            lastUsage: undefined,
+            lastError: undefined,
+            title: record.title ?? null,
+            requiresAttention: record.requiresAttention ?? false,
+            attentionReason: record.attentionReason ?? null,
+            attentionTimestamp: record.attentionTimestamp ?? null,
+            archivedAt: record.archivedAt ?? null,
+            labels: record.labels,
+        };
+    }
+    async ensureAgentLoaded(agentId) {
+        const existing = this.agentManager.getAgent(agentId);
+        if (existing) {
+            return existing;
+        }
+        const inflight = pendingAgentInitializations.get(agentId);
+        if (inflight) {
+            return inflight;
+        }
+        const initPromise = (async () => {
+            const record = await this.agentStorage.get(agentId);
+            if (!record) {
+                throw new Error(`Agent not found: ${agentId}`);
+            }
+            const handle = toAgentPersistenceHandle(this.sessionLogger, record.persistence);
+            let snapshot;
+            if (handle) {
+                snapshot = await this.agentManager.resumeAgentFromPersistence(handle, buildConfigOverrides(record), agentId, {
+                    ...extractTimestamps(record),
+                    ...extractTimelineSnapshot(record),
+                });
+                this.sessionLogger.info({ agentId, provider: record.provider }, 'Agent resumed from persistence');
+            }
+            else {
+                const config = buildSessionConfig(record);
+                snapshot = await this.agentManager.createAgent(config, agentId, { labels: record.labels });
+                this.sessionLogger.info({ agentId, provider: record.provider }, 'Agent created from stored config');
+            }
+            await this.agentManager.hydrateTimelineFromProvider(agentId);
+            return this.agentManager.getAgent(agentId) ?? snapshot;
+        })();
+        pendingAgentInitializations.set(agentId, initPromise);
+        try {
+            return await initPromise;
+        }
+        finally {
+            const current = pendingAgentInitializations.get(agentId);
+            if (current === initPromise) {
+                pendingAgentInitializations.delete(agentId);
+            }
+        }
+    }
+    matchesAgentFilter(options) {
+        const { agent, project, filter } = options;
+        if (filter?.labels) {
+            const matchesLabels = Object.entries(filter.labels).every(([key, value]) => agent.labels[key] === value);
+            if (!matchesLabels) {
+                return false;
+            }
+        }
+        const includeArchived = filter?.includeArchived ?? false;
+        if (!includeArchived && agent.archivedAt) {
+            return false;
+        }
+        if (filter?.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)) {
+                return false;
+            }
+        }
+        if (typeof filter?.requiresAttention === 'boolean') {
+            const requiresAttention = agent.requiresAttention ?? false;
+            if (requiresAttention !== filter.requiresAttention) {
+                return false;
+            }
+        }
+        if (filter?.projectKeys && filter.projectKeys.length > 0) {
+            const projectKeys = new Set(filter.projectKeys.filter((item) => item.trim().length > 0));
+            if (projectKeys.size > 0 && !projectKeys.has(project.projectKey)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    getAgentUpdateTargetId(update) {
+        return update.kind === 'remove' ? update.agentId : update.agent.id;
+    }
+    bufferOrEmitAgentUpdate(subscription, payload) {
+        if (subscription.isBootstrapping) {
+            subscription.pendingUpdatesByAgentId.set(this.getAgentUpdateTargetId(payload), payload);
+            return;
+        }
+        this.emit({
+            type: 'agent_update',
+            payload,
+        });
+    }
+    flushBootstrappedAgentUpdates(options) {
+        const subscription = this.agentUpdatesSubscription;
+        if (!subscription || !subscription.isBootstrapping) {
+            return;
+        }
+        subscription.isBootstrapping = false;
+        const pending = Array.from(subscription.pendingUpdatesByAgentId.values());
+        subscription.pendingUpdatesByAgentId.clear();
+        for (const payload of pending) {
+            if (payload.kind === 'upsert') {
+                const snapshotUpdatedAt = options?.snapshotUpdatedAtByAgentId?.get(payload.agent.id);
+                if (typeof snapshotUpdatedAt === 'number') {
+                    const updateUpdatedAt = Date.parse(payload.agent.updatedAt);
+                    if (!Number.isNaN(updateUpdatedAt) && updateUpdatedAt <= snapshotUpdatedAt) {
+                        continue;
+                    }
+                }
+            }
+            this.emit({
+                type: 'agent_update',
+                payload,
+            });
+        }
+    }
+    buildFallbackProjectCheckout(cwd) {
+        return {
+            cwd,
+            isGit: false,
+            currentBranch: null,
+            remoteUrl: null,
+            isJunctionOwnedWorktree: false,
+            mainRepoRoot: null,
+        };
+    }
+    toProjectCheckoutLite(cwd, status) {
+        if (!status.isGit) {
+            return this.buildFallbackProjectCheckout(cwd);
+        }
+        if (status.isJunctionOwnedWorktree) {
+            return {
+                cwd,
+                isGit: true,
+                currentBranch: status.currentBranch,
+                remoteUrl: status.remoteUrl,
+                isJunctionOwnedWorktree: true,
+                mainRepoRoot: status.mainRepoRoot,
+            };
+        }
+        return {
+            cwd,
+            isGit: true,
+            currentBranch: status.currentBranch,
+            remoteUrl: status.remoteUrl,
+            isJunctionOwnedWorktree: false,
+            mainRepoRoot: null,
+        };
+    }
+    async buildProjectPlacement(cwd) {
+        const checkout = await getCheckoutStatusLite(cwd, { junctionHome: this.junctionHome })
+            .then((status) => this.toProjectCheckoutLite(cwd, status))
+            .catch(() => this.buildFallbackProjectCheckout(cwd));
+        const projectKey = deriveProjectGroupingKey({
+            cwd,
+            remoteUrl: checkout.remoteUrl,
+        });
+        return {
+            projectKey,
+            projectName: deriveProjectGroupingName(projectKey),
+            checkout,
+        };
+    }
+    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',
+                    agent: payload,
+                    project,
+                });
+                return;
+            }
+            this.bufferOrEmitAgentUpdate(subscription, {
+                kind: 'remove',
+                agentId: payload.id,
+            });
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error }, 'Failed to emit agent update');
+        }
+    }
+    /**
+     * Main entry point for processing session messages
+     */
+    async handleMessage(msg) {
+        try {
+            switch (msg.type) {
+                case 'abort_request':
+                    await this.handleAbort();
+                    break;
+                case 'fetch_agents_request':
+                    await this.handleFetchAgents(msg);
+                    break;
+                case 'fetch_agent_request':
+                    await this.handleFetchAgent(msg.agentId, msg.requestId);
+                    break;
+                case 'delete_agent_request':
+                    await this.handleDeleteAgentRequest(msg.agentId, msg.requestId);
+                    break;
+                case 'archive_agent_request':
+                    await this.handleArchiveAgentRequest(msg.agentId, msg.requestId);
+                    break;
+                case 'update_agent_request':
+                    await this.handleUpdateAgentRequest(msg.agentId, msg.name, msg.labels, msg.requestId);
+                    break;
+                case 'send_agent_message_request':
+                    await this.handleSendAgentMessageRequest(msg);
+                    break;
+                case 'wait_for_finish_request':
+                    await this.handleWaitForFinish(msg.agentId, msg.requestId, msg.timeoutMs);
+                    break;
+                case 'create_agent_request':
+                    await this.handleCreateAgentRequest(msg);
+                    break;
+                case 'resume_agent_request':
+                    await this.handleResumeAgentRequest(msg);
+                    break;
+                case 'refresh_agent_request':
+                    await this.handleRefreshAgentRequest(msg);
+                    break;
+                case 'cancel_agent_request':
+                    await this.handleCancelAgentRequest(msg.agentId);
+                    break;
+                case 'restart_server_request':
+                    await this.handleRestartServerRequest(msg.requestId, msg.reason);
+                    break;
+                case 'shutdown_server_request':
+                    await this.handleShutdownServerRequest(msg.requestId);
+                    break;
+                case 'fetch_agent_timeline_request':
+                    await this.handleFetchAgentTimelineRequest(msg);
+                    break;
+                case 'set_agent_mode_request':
+                    await this.handleSetAgentModeRequest(msg.agentId, msg.modeId, msg.requestId);
+                    break;
+                case 'set_agent_model_request':
+                    await this.handleSetAgentModelRequest(msg.agentId, msg.modelId, msg.requestId);
+                    break;
+                case 'set_agent_thinking_request':
+                    await this.handleSetAgentThinkingRequest(msg.agentId, msg.thinkingOptionId, msg.requestId);
+                    break;
+                case 'agent_permission_response':
+                    await this.handleAgentPermissionResponse(msg.agentId, msg.requestId, msg.response);
+                    break;
+                case 'checkout_status_request':
+                    await this.handleCheckoutStatusRequest(msg);
+                    break;
+                case 'validate_branch_request':
+                    await this.handleValidateBranchRequest(msg);
+                    break;
+                case 'branch_suggestions_request':
+                    await this.handleBranchSuggestionsRequest(msg);
+                    break;
+                case 'directory_suggestions_request':
+                    await this.handleDirectorySuggestionsRequest(msg);
+                    break;
+                case 'git_clone_request':
+                    await this.handleGitCloneRequest(msg);
+                    break;
+                case 'git_init_request':
+                    await this.handleGitInitRequest(msg);
+                    break;
+                case 'subscribe_checkout_diff_request':
+                    await this.handleSubscribeCheckoutDiffRequest(msg);
+                    break;
+                case 'unsubscribe_checkout_diff_request':
+                    this.handleUnsubscribeCheckoutDiffRequest(msg);
+                    break;
+                case 'checkout_commit_request':
+                    await this.handleCheckoutCommitRequest(msg);
+                    break;
+                case 'checkout_merge_request':
+                    await this.handleCheckoutMergeRequest(msg);
+                    break;
+                case 'checkout_merge_from_base_request':
+                    await this.handleCheckoutMergeFromBaseRequest(msg);
+                    break;
+                case 'checkout_push_request':
+                    await this.handleCheckoutPushRequest(msg);
+                    break;
+                case 'checkout_pr_create_request':
+                    await this.handleCheckoutPrCreateRequest(msg);
+                    break;
+                case 'checkout_pr_status_request':
+                    await this.handleCheckoutPrStatusRequest(msg);
+                    break;
+                case 'junction_worktree_list_request':
+                    await this.handleJunctionWorktreeListRequest(msg);
+                    break;
+                case 'junction_worktree_archive_request':
+                    await this.handleJunctionWorktreeArchiveRequest(msg);
+                    break;
+                case 'file_explorer_request':
+                    await this.handleFileExplorerRequest(msg);
+                    break;
+                case 'workspace_file_explorer_request':
+                    await this.handleWorkspaceFileExplorerRequest(msg);
+                    break;
+                case 'project_icon_request':
+                    await this.handleProjectIconRequest(msg);
+                    break;
+                case 'file_download_token_request':
+                    await this.handleFileDownloadTokenRequest(msg);
+                    break;
+                case 'list_provider_models_request':
+                    await this.handleListProviderModelsRequest(msg);
+                    break;
+                case 'list_available_providers_request':
+                    await this.handleListAvailableProvidersRequest(msg);
+                    break;
+                case 'clear_agent_attention':
+                    await this.handleClearAgentAttention(msg.agentId);
+                    break;
+                case 'client_heartbeat':
+                    this.handleClientHeartbeat(msg);
+                    break;
+                case 'ping': {
+                    const now = Date.now();
+                    this.emit({
+                        type: 'pong',
+                        payload: {
+                            requestId: msg.requestId,
+                            clientSentAt: msg.clientSentAt,
+                            serverReceivedAt: now,
+                            serverSentAt: now,
+                        },
+                    });
+                    break;
+                }
+                case 'list_commands_request':
+                    await this.handleListCommandsRequest(msg);
+                    break;
+                case 'subscribe_terminals_request':
+                    this.handleSubscribeTerminalsRequest(msg);
+                    break;
+                case 'unsubscribe_terminals_request':
+                    this.handleUnsubscribeTerminalsRequest(msg);
+                    break;
+                case 'list_terminals_request':
+                    await this.handleListTerminalsRequest(msg);
+                    break;
+                case 'create_terminal_request':
+                    await this.handleCreateTerminalRequest(msg);
+                    break;
+                case 'subscribe_terminal_request':
+                    await this.handleSubscribeTerminalRequest(msg);
+                    break;
+                case 'unsubscribe_terminal_request':
+                    this.handleUnsubscribeTerminalRequest(msg);
+                    break;
+                case 'terminal_input':
+                    this.handleTerminalInput(msg);
+                    break;
+                case 'kill_terminal_request':
+                    await this.handleKillTerminalRequest(msg);
+                    break;
+                case 'attach_terminal_stream_request':
+                    await this.handleAttachTerminalStreamRequest(msg);
+                    break;
+                case 'detach_terminal_stream_request':
+                    this.handleDetachTerminalStreamRequest(msg);
+                    break;
+            }
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            this.sessionLogger.error({ err }, 'Error handling message');
+            const requestId = msg.requestId;
+            if (typeof requestId === 'string') {
+                try {
+                    this.emit({
+                        type: 'rpc_error',
+                        payload: {
+                            requestId,
+                            requestType: msg.type,
+                            error: 'Request failed',
+                            code: 'handler_error',
+                        },
+                    });
+                }
+                catch (emitError) {
+                    this.sessionLogger.error({ err: emitError }, 'Failed to emit rpc_error');
+                }
+            }
+            this.emit({
+                type: 'activity_log',
+                payload: {
+                    id: uuidv4(),
+                    timestamp: new Date(),
+                    type: 'error',
+                    content: `Error: ${err.message}`,
+                },
+            });
+        }
+    }
+    handleBinaryFrame(frame) {
+        switch (frame.channel) {
+            case BinaryMuxChannel.Terminal:
+                this.handleTerminalBinaryFrame(frame);
+                break;
+            default:
+                this.sessionLogger.warn({ channel: frame.channel, messageType: frame.messageType }, 'Unhandled binary mux channel');
+                break;
+        }
+    }
+    handleTerminalBinaryFrame(frame) {
+        if (frame.messageType === TerminalBinaryMessageType.InputUtf8) {
+            const binding = this.terminalStreams.get(frame.streamId);
+            if (!binding) {
+                this.sessionLogger.warn({ streamId: frame.streamId }, 'Terminal stream not found for input');
+                return;
+            }
+            if (!this.terminalManager) {
+                return;
+            }
+            const session = this.terminalManager.getTerminal(binding.terminalId);
+            if (!session) {
+                this.detachTerminalStream(frame.streamId, { emitExit: true });
+                return;
+            }
+            const payload = frame.payload ?? new Uint8Array(0);
+            if (payload.byteLength === 0) {
+                return;
+            }
+            const text = Buffer.from(payload).toString('utf8');
+            if (!text) {
+                return;
+            }
+            session.send({ type: 'input', data: text });
+            return;
+        }
+        if (frame.messageType === TerminalBinaryMessageType.Ack) {
+            const binding = this.terminalStreams.get(frame.streamId);
+            if (binding) {
+                if (!Number.isFinite(frame.offset) || frame.offset < 0) {
+                    return;
+                }
+                const nextAckOffset = Math.max(binding.lastAckOffset, Math.min(Math.floor(frame.offset), binding.lastOutputOffset));
+                if (nextAckOffset > binding.lastAckOffset) {
+                    binding.lastAckOffset = nextAckOffset;
+                    this.flushPendingTerminalStreamChunks(frame.streamId, binding);
+                }
+            }
+            return;
+        }
+        this.sessionLogger.warn({ streamId: frame.streamId, messageType: frame.messageType }, 'Unhandled terminal binary frame');
+    }
+    async handleRestartServerRequest(requestId, reason) {
+        const payload = {
+            status: 'restart_requested',
+            clientId: this.clientId,
+        };
+        if (reason && reason.trim().length > 0) {
+            payload.reason = reason;
+        }
+        payload.requestId = requestId;
+        this.sessionLogger.warn({ reason }, 'Restart requested via websocket');
+        this.emit({
+            type: 'status',
+            payload,
+        });
+        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;
+        }
+        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`);
+        // Prevent the persistence hook from re-creating the record while we close/delete.
+        this.agentStorage.beginDelete(agentId);
+        try {
+            await this.agentManager.closeAgent(agentId);
+        }
+        catch (error) {
+            this.sessionLogger.warn({ err: error, agentId }, `Failed to close agent ${agentId} during delete`);
+        }
+        try {
+            await this.agentStorage.remove(agentId);
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, agentId }, `Failed to remove agent ${agentId} from registry`);
+        }
+        this.emit({
+            type: 'agent_deleted',
+            payload: {
+                agentId,
+                requestId,
+            },
+        });
+        if (this.agentUpdatesSubscription) {
+            this.bufferOrEmitAgentUpdate(this.agentUpdatesSubscription, {
+                kind: 'remove',
+                agentId,
+            });
+        }
+    }
+    async handleArchiveAgentRequest(agentId, requestId) {
+        this.sessionLogger.info({ agentId }, `Archiving agent ${agentId}`);
+        if (this.agentManager.getAgent(agentId)) {
+            await this.interruptAgentIfRunning(agentId);
+        }
+        const archivedAt = new Date().toISOString();
+        const existing = await this.agentStorage.get(agentId);
+        let archivedRecord = existing;
+        if (!archivedRecord) {
+            const liveAgent = this.agentManager.getAgent(agentId);
+            if (!liveAgent) {
+                throw new Error(`Agent not found: ${agentId}`);
+            }
+            await this.agentStorage.applySnapshot(liveAgent, {
+                internal: liveAgent.internal,
+            });
+            archivedRecord = await this.agentStorage.get(agentId);
+            if (!archivedRecord) {
+                throw new Error(`Agent not found in storage after snapshot: ${agentId}`);
+            }
+        }
+        archivedRecord = {
+            ...archivedRecord,
+            archivedAt,
+        };
+        await this.agentStorage.upsert(archivedRecord);
+        this.agentManager.notifyAgentState(agentId);
+        this.emit({
+            type: 'agent_archived',
+            payload: {
+                agentId,
+                archivedAt,
+                requestId,
+            },
+        });
+        await this.maybeArchiveWorktreeAfterLastAgentArchived({
+            archivedAgentId: agentId,
+            archivedAgentCwd: archivedRecord.cwd,
+            requestId,
+        });
+    }
+    async getArchivedAt(agentId) {
+        const record = await this.agentStorage.get(agentId);
+        return record?.archivedAt ?? null;
+    }
+    async handleUpdateAgentRequest(agentId, name, labels, requestId) {
+        this.sessionLogger.info({
+            agentId,
+            requestId,
+            hasName: typeof name === 'string',
+            labelCount: labels ? Object.keys(labels).length : 0,
+        }, 'session: update_agent_request');
+        const normalizedName = name?.trim();
+        const normalizedLabels = labels && Object.keys(labels).length > 0 ? labels : undefined;
+        if (!normalizedName && !normalizedLabels) {
+            this.emit({
+                type: 'update_agent_response',
+                payload: {
+                    requestId,
+                    agentId,
+                    accepted: false,
+                    error: 'Nothing to update (provide name and/or labels)',
+                },
+            });
+            return;
+        }
+        try {
+            const liveAgent = this.agentManager.getAgent(agentId);
+            if (liveAgent) {
+                if (normalizedName) {
+                    await this.agentManager.setTitle(agentId, normalizedName);
+                }
+                if (normalizedLabels) {
+                    await this.agentManager.setLabels(agentId, normalizedLabels);
+                }
+            }
+            else {
+                const existing = await this.agentStorage.get(agentId);
+                if (!existing) {
+                    throw new Error(`Agent not found: ${agentId}`);
+                }
+                await this.agentStorage.upsert({
+                    ...existing,
+                    ...(normalizedName ? { title: normalizedName } : {}),
+                    ...(normalizedLabels ? { labels: { ...existing.labels, ...normalizedLabels } } : {}),
+                });
+            }
+            this.emit({
+                type: 'update_agent_response',
+                payload: { requestId, agentId, accepted: true, error: null },
+            });
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, agentId, requestId }, 'session: update_agent_request error');
+            this.emit({
+                type: 'activity_log',
+                payload: {
+                    id: uuidv4(),
+                    timestamp: new Date(),
+                    type: 'error',
+                    content: `Failed to update agent: ${error.message}`,
+                },
+            });
+            this.emit({
+                type: 'update_agent_response',
+                payload: {
+                    requestId,
+                    agentId,
+                    accepted: false,
+                    error: error?.message ? String(error.message) : 'Failed to update agent',
+                },
+            });
+        }
+    }
+    /**
+     * Handle text message to agent (with optional image attachments)
+     */
+    async handleSendAgentMessage(agentId, text, messageId, images, runOptions) {
+        this.sessionLogger.info({ agentId, textPreview: text.substring(0, 50), imageCount: images?.length ?? 0 }, `Sending text to agent ${agentId}${images && images.length > 0 ? ` with ${images.length} image attachment(s)` : ''}`);
+        try {
+            await this.ensureAgentLoaded(agentId);
+        }
+        catch (error) {
+            this.handleAgentRunError(agentId, error, 'Failed to initialize agent before sending prompt');
+            return;
+        }
+        const archivedAt = await this.getArchivedAt(agentId);
+        if (archivedAt) {
+            this.handleAgentRunError(agentId, new Error(`Agent ${agentId} is archived`), 'Refusing to send prompt to archived agent');
+            return;
+        }
+        try {
+            await this.interruptAgentIfRunning(agentId);
+        }
+        catch (error) {
+            this.handleAgentRunError(agentId, error, 'Failed to interrupt running agent before sending prompt');
+            return;
+        }
+        const prompt = this.buildAgentPrompt(text, images);
+        try {
+            this.agentManager.recordUserMessage(agentId, text, {
+                messageId,
+                emitState: false,
+            });
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, agentId }, `Failed to record user message for agent ${agentId}`);
+        }
+        this.startAgentStream(agentId, prompt, runOptions);
+    }
+    /**
+     * Handle create agent request
+     */
+    async handleCreateAgentRequest(msg) {
+        const { config, worktreeName, requestId, initialPrompt, clientMessageId, outputSchema, git, images, labels, } = msg;
+        this.sessionLogger.info({ cwd: config.cwd, provider: config.provider, worktreeName }, `Creating agent in ${config.cwd} (${config.provider})${worktreeName ? ` with worktree ${worktreeName}` : ''}`);
+        try {
+            const { sessionConfig, worktreeConfig, autoWorkspaceName } = await this.buildAgentSessionConfig(config, git, worktreeName, labels);
+            const mergedLabels = autoWorkspaceName
+                ? { ...labels, 'junction:workspace': autoWorkspaceName }
+                : labels;
+            const snapshot = await this.agentManager.createAgent(sessionConfig, undefined, { labels: mergedLabels });
+            await this.forwardAgentUpdate(snapshot);
+            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,
+                    },
+                });
+            }
+            const trimmedPrompt = initialPrompt?.trim();
+            if (trimmedPrompt) {
+                scheduleAgentMetadataGeneration({
+                    agentManager: this.agentManager,
+                    agentId: snapshot.id,
+                    cwd: snapshot.cwd,
+                    initialPrompt: trimmedPrompt,
+                    explicitTitle: snapshot.config.title,
+                    junctionHome: this.junctionHome,
+                    logger: this.sessionLogger,
+                });
+                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',
+                        payload: {
+                            id: uuidv4(),
+                            timestamp: new Date(),
+                            type: 'error',
+                            content: `Initial prompt failed: ${promptError?.message ?? promptError}`,
+                        },
+                    });
+                });
+            }
+            if (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})`);
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error }, 'Failed to create agent');
+            if (requestId) {
+                this.emit({
+                    type: 'status',
+                    payload: {
+                        status: 'agent_create_failed',
+                        requestId,
+                        error: error?.message ?? String(error),
+                    },
+                });
+            }
+            this.emit({
+                type: 'activity_log',
+                payload: {
+                    id: uuidv4(),
+                    timestamp: new Date(),
+                    type: 'error',
+                    content: `Failed to create agent: ${error.message}`,
+                },
+            });
+        }
+    }
+    async handleResumeAgentRequest(msg) {
+        const { handle, overrides, requestId } = msg;
+        if (!handle) {
+            this.sessionLogger.warn('Resume request missing persistence handle');
+            this.emit({
+                type: 'activity_log',
+                payload: {
+                    id: uuidv4(),
+                    timestamp: new Date(),
+                    type: 'error',
+                    content: 'Unable to resume agent: missing persistence handle',
+                },
+            });
+            return;
+        }
+        this.sessionLogger.info({ sessionId: handle.sessionId, provider: handle.provider }, `Resuming agent ${handle.sessionId} (${handle.provider})`);
+        try {
+            const snapshot = await this.agentManager.resumeAgentFromPersistence(handle, overrides);
+            await this.agentManager.hydrateTimelineFromProvider(snapshot.id);
+            await this.forwardAgentUpdate(snapshot);
+            const timelineSize = this.agentManager.getTimeline(snapshot.id).length;
+            if (requestId) {
+                const agentPayload = await this.getAgentPayloadById(snapshot.id);
+                if (!agentPayload) {
+                    throw new Error(`Agent ${snapshot.id} not found after resume`);
+                }
+                this.emit({
+                    type: 'status',
+                    payload: {
+                        status: 'agent_resumed',
+                        agentId: snapshot.id,
+                        requestId,
+                        timelineSize,
+                        agent: agentPayload,
+                    },
+                });
+            }
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error }, 'Failed to resume agent');
+            this.emit({
+                type: 'activity_log',
+                payload: {
+                    id: uuidv4(),
+                    timestamp: new Date(),
+                    type: 'error',
+                    content: `Failed to resume agent: ${error.message}`,
+                },
+            });
+        }
+    }
+    async handleRefreshAgentRequest(msg) {
+        const { agentId, requestId } = msg;
+        this.sessionLogger.info({ agentId }, `Refreshing agent ${agentId} from persistence`);
+        try {
+            let snapshot;
+            const existing = this.agentManager.getAgent(agentId);
+            if (existing) {
+                await this.interruptAgentIfRunning(agentId);
+                if (existing.persistence) {
+                    snapshot = await this.agentManager.reloadAgentSession(agentId);
+                }
+                else {
+                    snapshot = existing;
+                }
+            }
+            else {
+                const record = await this.agentStorage.get(agentId);
+                if (!record) {
+                    throw new Error(`Agent not found: ${agentId}`);
+                }
+                const handle = toAgentPersistenceHandle(this.sessionLogger, record.persistence);
+                if (!handle) {
+                    throw new Error(`Agent ${agentId} cannot be refreshed because it lacks persistence`);
+                }
+                snapshot = await this.agentManager.resumeAgentFromPersistence(handle, buildConfigOverrides(record), agentId, {
+                    ...extractTimestamps(record),
+                    ...extractTimelineSnapshot(record),
+                });
+            }
+            await this.agentManager.hydrateTimelineFromProvider(agentId);
+            await this.forwardAgentUpdate(snapshot);
+            const timelineSize = this.agentManager.getTimeline(agentId).length;
+            if (requestId) {
+                this.emit({
+                    type: 'status',
+                    payload: {
+                        status: 'agent_refreshed',
+                        agentId,
+                        requestId,
+                        timelineSize,
+                    },
+                });
+            }
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, agentId }, `Failed to refresh agent ${agentId}`);
+            this.emit({
+                type: 'activity_log',
+                payload: {
+                    id: uuidv4(),
+                    timestamp: new Date(),
+                    type: 'error',
+                    content: `Failed to refresh agent: ${error.message}`,
+                },
+            });
+        }
+    }
+    async handleCancelAgentRequest(agentId) {
+        this.sessionLogger.info({ agentId }, `Cancel request received for agent ${agentId}`);
+        try {
+            await this.interruptAgentIfRunning(agentId);
+        }
+        catch (error) {
+            this.handleAgentRunError(agentId, error, 'Failed to cancel running agent on request');
+        }
+    }
+    async buildAgentSessionConfig(config, gitOptions, legacyWorktreeName, _labels) {
+        const cwd = expandTilde(config.cwd);
+        const normalized = this.normalizeGitOptions(gitOptions, legacyWorktreeName);
+        let repoRoot;
+        try {
+            const { stdout } = await execAsync('git rev-parse --path-format=absolute --git-common-dir', {
+                cwd,
+                env: READ_ONLY_GIT_ENV,
+            });
+            const gitCommonDir = stdout.trim();
+            if (!gitCommonDir) {
+                throw new Error('missing git common dir');
+            }
+            repoRoot =
+                basename(gitCommonDir) === '.git'
+                    ? dirname(gitCommonDir)
+                    : gitCommonDir;
+        }
+        catch {
+            throw new Error('Selected project must be a git repository. Junction always creates a new worktree in .junction/.');
+        }
+        const baseBranch = normalized?.baseBranch ?? (await resolveBaseRef(repoRoot));
+        if (!baseBranch) {
+            throw new Error('Unable to determine a base branch for worktree creation');
+        }
+        this.sessionLogger.info({ repoRoot, baseBranch }, 'Creating in-repo worktree for new agent');
+        const createdWorktree = await createInRepoWorktree({
+            repoRoot,
+            baseBranch,
+            runSetup: false,
+        });
+        return {
+            sessionConfig: {
+                ...config,
+                cwd: createdWorktree.worktreePath,
+            },
+            worktreeConfig: createdWorktree,
+            autoWorkspaceName: createdWorktree.slug,
+        };
+    }
+    async handleListProviderModelsRequest(msg) {
+        const fetchedAt = new Date().toISOString();
+        try {
+            const models = await this.providerRegistry[msg.provider].fetchModels({
+                cwd: msg.cwd ? expandTilde(msg.cwd) : undefined,
+            });
+            this.emit({
+                type: 'list_provider_models_response',
+                payload: {
+                    provider: msg.provider,
+                    models,
+                    error: null,
+                    fetchedAt,
+                    requestId: msg.requestId,
+                },
+            });
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, provider: msg.provider }, `Failed to list models for ${msg.provider}`);
+            this.emit({
+                type: 'list_provider_models_response',
+                payload: {
+                    provider: msg.provider,
+                    error: error?.message ?? String(error),
+                    fetchedAt,
+                    requestId: msg.requestId,
+                },
+            });
+        }
+    }
+    async handleListAvailableProvidersRequest(msg) {
+        const fetchedAt = new Date().toISOString();
+        try {
+            const providers = await this.agentManager.listProviderAvailability();
+            this.emit({
+                type: 'list_available_providers_response',
+                payload: {
+                    providers,
+                    error: null,
+                    fetchedAt,
+                    requestId: msg.requestId,
+                },
+            });
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error }, 'Failed to list provider availability');
+            this.emit({
+                type: 'list_available_providers_response',
+                payload: {
+                    providers: [],
+                    error: error?.message ?? String(error),
+                    fetchedAt,
+                    requestId: msg.requestId,
+                },
+            });
+        }
+    }
+    normalizeGitOptions(gitOptions, legacyWorktreeName) {
+        const fallbackOptions = legacyWorktreeName
+            ? {
+                createWorktree: true,
+                createNewBranch: true,
+                newBranchName: legacyWorktreeName,
+                worktreeSlug: legacyWorktreeName,
+            }
+            : undefined;
+        const merged = gitOptions ?? fallbackOptions;
+        if (!merged) {
+            return null;
+        }
+        const baseBranch = merged.baseBranch?.trim() || undefined;
+        const createWorktree = Boolean(merged.createWorktree);
+        const createNewBranch = Boolean(merged.createNewBranch);
+        const normalizedBranchName = merged.newBranchName ? slugify(merged.newBranchName) : undefined;
+        const normalizedWorktreeSlug = merged.worktreeSlug
+            ? slugify(merged.worktreeSlug)
+            : normalizedBranchName;
+        if (!createWorktree && !createNewBranch && !baseBranch) {
+            return null;
+        }
+        if (baseBranch) {
+            this.assertSafeGitRef(baseBranch, 'base branch');
+        }
+        if (createWorktree && !baseBranch) {
+            throw new Error('Base branch is required when creating a worktree');
+        }
+        if (createNewBranch && !baseBranch) {
+            throw new Error('Base branch is required when creating a new branch');
+        }
+        if (createNewBranch) {
+            if (!normalizedBranchName) {
+                throw new Error('New branch name is required');
+            }
+            const validation = validateBranchSlug(normalizedBranchName);
+            if (!validation.valid) {
+                throw new Error(`Invalid branch name: ${validation.error}`);
+            }
+        }
+        if (normalizedWorktreeSlug) {
+            const validation = validateBranchSlug(normalizedWorktreeSlug);
+            if (!validation.valid) {
+                throw new Error(`Invalid worktree name: ${validation.error}`);
+            }
+        }
+        return {
+            baseBranch,
+            createNewBranch,
+            newBranchName: normalizedBranchName,
+            createWorktree,
+            worktreeSlug: normalizedWorktreeSlug,
+        };
+    }
+    assertSafeGitRef(ref, label) {
+        if (!SAFE_GIT_REF_PATTERN.test(ref) || ref.includes('..') || ref.includes('@{')) {
+            throw new Error(`Invalid ${label}: ${ref}`);
+        }
+    }
+    toCheckoutError(error) {
+        if (error instanceof NotGitRepoError) {
+            return { code: 'NOT_GIT_REPO', message: error.message };
+        }
+        if (error instanceof MergeConflictError) {
+            return { code: 'MERGE_CONFLICT', message: error.message };
+        }
+        if (error instanceof MergeFromBaseConflictError) {
+            return { code: 'MERGE_CONFLICT', message: error.message };
+        }
+        if (error instanceof Error) {
+            return { code: 'UNKNOWN', message: error.message };
+        }
+        return { code: 'UNKNOWN', message: String(error) };
+    }
+    isPathWithinRoot(rootPath, candidatePath) {
+        const resolvedRoot = resolve(rootPath);
+        const resolvedCandidate = resolve(candidatePath);
+        if (resolvedCandidate === resolvedRoot) {
+            return true;
+        }
+        return resolvedCandidate.startsWith(resolvedRoot + sep);
+    }
+    async generateCommitMessage(cwd) {
+        const diff = await getCheckoutDiff(cwd, { mode: 'uncommitted', includeStructured: true }, { junctionHome: this.junctionHome });
+        const schema = z.object({
+            message: z
+                .string()
+                .min(1)
+                .max(72)
+                .describe('Concise git commit message, imperative mood, no trailing period.'),
+        });
+        const fileList = diff.structured && diff.structured.length > 0
+            ? [
+                'Files changed:',
+                ...diff.structured.map((file) => {
+                    const changeType = file.isNew ? 'A' : file.isDeleted ? 'D' : 'M';
+                    const status = file.status && file.status !== 'ok' ? ` [${file.status}]` : '';
+                    return `${changeType}\t${file.path}\t(+${file.additions} -${file.deletions})${status}`;
+                }),
+            ].join('\n')
+            : 'Files changed: (unknown)';
+        const maxPatchChars = 120000;
+        const patch = diff.diff.length > maxPatchChars
+            ? `${diff.diff.slice(0, maxPatchChars)}\n\n... (diff truncated to ${maxPatchChars} chars)\n`
+            : diff.diff;
+        const prompt = [
+            'Write a concise git commit message for the changes below.',
+            "Return JSON only with a single field 'message'.",
+            '',
+            fileList,
+            '',
+            patch.length > 0 ? patch : '(No diff available)',
+        ].join('\n');
+        try {
+            const result = await generateStructuredAgentResponseWithFallback({
+                manager: this.agentManager,
+                cwd,
+                prompt,
+                schema,
+                schemaName: 'CommitMessage',
+                maxRetries: 2,
+                providers: DEFAULT_STRUCTURED_GENERATION_PROVIDERS,
+                agentConfigOverrides: {
+                    title: 'Commit generator',
+                    internal: true,
+                },
+            });
+            return result.message;
+        }
+        catch (error) {
+            if (error instanceof StructuredAgentResponseError ||
+                error instanceof StructuredAgentFallbackError) {
+                return 'Update files';
+            }
+            throw error;
+        }
+    }
+    async generatePullRequestText(cwd, baseRef) {
+        const diff = await getCheckoutDiff(cwd, {
+            mode: 'base',
+            baseRef,
+            includeStructured: true,
+        }, { junctionHome: this.junctionHome });
+        const schema = z.object({
+            title: z.string().min(1).max(72),
+            body: z.string().min(1),
+        });
+        const fileList = diff.structured && diff.structured.length > 0
+            ? [
+                'Files changed:',
+                ...diff.structured.map((file) => {
+                    const changeType = file.isNew ? 'A' : file.isDeleted ? 'D' : 'M';
+                    const status = file.status && file.status !== 'ok' ? ` [${file.status}]` : '';
+                    return `${changeType}\t${file.path}\t(+${file.additions} -${file.deletions})${status}`;
+                }),
+            ].join('\n')
+            : 'Files changed: (unknown)';
+        const maxPatchChars = 200000;
+        const patch = diff.diff.length > maxPatchChars
+            ? `${diff.diff.slice(0, maxPatchChars)}\n\n... (diff truncated to ${maxPatchChars} chars)\n`
+            : diff.diff;
+        const prompt = [
+            'Write a pull request title and body for the changes below.',
+            "Return JSON only with fields 'title' and 'body'.",
+            '',
+            fileList,
+            '',
+            patch.length > 0 ? patch : '(No diff available)',
+        ].join('\n');
+        try {
+            return await generateStructuredAgentResponseWithFallback({
+                manager: this.agentManager,
+                cwd,
+                prompt,
+                schema,
+                schemaName: 'PullRequest',
+                maxRetries: 2,
+                providers: DEFAULT_STRUCTURED_GENERATION_PROVIDERS,
+                agentConfigOverrides: {
+                    title: 'PR generator',
+                    internal: true,
+                },
+            });
+        }
+        catch (error) {
+            if (error instanceof StructuredAgentResponseError ||
+                error instanceof StructuredAgentFallbackError) {
+                return {
+                    title: 'Update changes',
+                    body: 'Automated PR generated by Junction.',
+                };
+            }
+            throw error;
+        }
+    }
+    /**
+     * Handle set agent mode request
+     */
+    async handleSetAgentModeRequest(agentId, modeId, requestId) {
+        this.sessionLogger.info({ agentId, modeId, requestId }, 'session: set_agent_mode_request');
+        try {
+            await this.agentManager.setAgentMode(agentId, modeId);
+            this.sessionLogger.info({ agentId, modeId, requestId }, 'session: set_agent_mode_request success');
+            this.emit({
+                type: 'set_agent_mode_response',
+                payload: { requestId, agentId, accepted: true, error: null },
+            });
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, agentId, modeId, requestId }, 'session: set_agent_mode_request error');
+            this.emit({
+                type: 'activity_log',
+                payload: {
+                    id: uuidv4(),
+                    timestamp: new Date(),
+                    type: 'error',
+                    content: `Failed to set agent mode: ${error.message}`,
+                },
+            });
+            this.emit({
+                type: 'set_agent_mode_response',
+                payload: {
+                    requestId,
+                    agentId,
+                    accepted: false,
+                    error: error?.message ? String(error.message) : 'Failed to set agent mode',
+                },
+            });
+        }
+    }
+    async handleSetAgentModelRequest(agentId, modelId, requestId) {
+        this.sessionLogger.info({ agentId, modelId, requestId }, 'session: set_agent_model_request');
+        try {
+            await this.agentManager.setAgentModel(agentId, modelId);
+            this.sessionLogger.info({ agentId, modelId, requestId }, 'session: set_agent_model_request success');
+            this.emit({
+                type: 'set_agent_model_response',
+                payload: { requestId, agentId, accepted: true, error: null },
+            });
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, agentId, modelId, requestId }, 'session: set_agent_model_request error');
+            this.emit({
+                type: 'activity_log',
+                payload: {
+                    id: uuidv4(),
+                    timestamp: new Date(),
+                    type: 'error',
+                    content: `Failed to set agent model: ${error.message}`,
+                },
+            });
+            this.emit({
+                type: 'set_agent_model_response',
+                payload: {
+                    requestId,
+                    agentId,
+                    accepted: false,
+                    error: error?.message ? String(error.message) : 'Failed to set agent model',
+                },
+            });
+        }
+    }
+    async handleSetAgentThinkingRequest(agentId, thinkingOptionId, requestId) {
+        this.sessionLogger.info({ agentId, thinkingOptionId, requestId }, 'session: set_agent_thinking_request');
+        try {
+            await this.agentManager.setAgentThinkingOption(agentId, thinkingOptionId);
+            this.sessionLogger.info({ agentId, thinkingOptionId, requestId }, 'session: set_agent_thinking_request success');
+            this.emit({
+                type: 'set_agent_thinking_response',
+                payload: { requestId, agentId, accepted: true, error: null },
+            });
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, agentId, thinkingOptionId, requestId }, 'session: set_agent_thinking_request error');
+            this.emit({
+                type: 'activity_log',
+                payload: {
+                    id: uuidv4(),
+                    timestamp: new Date(),
+                    type: 'error',
+                    content: `Failed to set agent thinking option: ${error.message}`,
+                },
+            });
+            this.emit({
+                type: 'set_agent_thinking_response',
+                payload: {
+                    requestId,
+                    agentId,
+                    accepted: false,
+                    error: error?.message ? String(error.message) : 'Failed to set agent thinking option',
+                },
+            });
+        }
+    }
+    /**
+     * Handle clearing agent attention flag
+     */
+    async handleClearAgentAttention(agentId) {
+        const agentIds = Array.isArray(agentId) ? agentId : [agentId];
+        try {
+            await Promise.all(agentIds.map((id) => this.agentManager.clearAgentAttention(id)));
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, agentIds }, 'Failed to clear agent attention');
+            // Don't throw - this is not critical
+        }
+    }
+    /**
+     * Handle client heartbeat for activity tracking
+     */
+    handleClientHeartbeat(msg) {
+        const appVisibilityChangedAt = msg.appVisibilityChangedAt
+            ? new Date(msg.appVisibilityChangedAt)
+            : new Date(msg.lastActivityAt);
+        this.clientActivity = {
+            deviceType: msg.deviceType,
+            focusedAgentId: msg.focusedAgentId,
+            lastActivityAt: new Date(msg.lastActivityAt),
+            appVisible: msg.appVisible,
+            appVisibilityChangedAt,
+        };
+    }
+    /**
+     * Handle list commands request for an agent
+     */
+    async handleListCommandsRequest(msg) {
+        const { agentId, requestId, draftConfig } = msg;
+        this.sessionLogger.debug({ agentId, draftConfig }, `Handling list commands request for agent ${agentId}`);
+        try {
+            const agents = this.agentManager.listAgents();
+            const agent = agents.find((a) => a.id === agentId);
+            if (agent?.session?.listCommands) {
+                const commands = await agent.session.listCommands();
+                this.emit({
+                    type: 'list_commands_response',
+                    payload: {
+                        agentId,
+                        commands,
+                        error: null,
+                        requestId,
+                    },
+                });
+                return;
+            }
+            if (!agent && draftConfig) {
+                const sessionConfig = {
+                    provider: draftConfig.provider,
+                    cwd: expandTilde(draftConfig.cwd),
+                    ...(draftConfig.modeId ? { modeId: draftConfig.modeId } : {}),
+                    ...(draftConfig.model ? { model: draftConfig.model } : {}),
+                    ...(draftConfig.thinkingOptionId
+                        ? { thinkingOptionId: draftConfig.thinkingOptionId }
+                        : {}),
+                };
+                const commands = await this.agentManager.listDraftCommands(sessionConfig);
+                this.emit({
+                    type: 'list_commands_response',
+                    payload: {
+                        agentId,
+                        commands,
+                        error: null,
+                        requestId,
+                    },
+                });
+                return;
+            }
+            this.emit({
+                type: 'list_commands_response',
+                payload: {
+                    agentId,
+                    commands: [],
+                    error: agent ? `Agent does not support listing commands` : `Agent not found: ${agentId}`,
+                    requestId,
+                },
+            });
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, agentId, draftConfig }, 'Failed to list commands');
+            this.emit({
+                type: 'list_commands_response',
+                payload: {
+                    agentId,
+                    commands: [],
+                    error: error.message,
+                    requestId,
+                },
+            });
+        }
+    }
+    /**
+     * Handle agent permission response from user
+     */
+    async handleAgentPermissionResponse(agentId, requestId, response) {
+        this.sessionLogger.debug({ agentId, requestId }, `Handling permission response for agent ${agentId}, request ${requestId}`);
+        try {
+            await this.agentManager.respondToPermission(agentId, requestId, response);
+            this.sessionLogger.debug({ agentId }, `Permission response forwarded to agent ${agentId}`);
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, agentId, requestId }, 'Failed to respond to permission');
+            this.emit({
+                type: 'activity_log',
+                payload: {
+                    id: uuidv4(),
+                    timestamp: new Date(),
+                    type: 'error',
+                    content: `Failed to respond to permission: ${error.message}`,
+                },
+            });
+            throw error;
+        }
+    }
+    async handleCheckoutStatusRequest(msg) {
+        const { cwd, requestId } = msg;
+        const resolvedCwd = expandTilde(cwd);
+        try {
+            const status = await getCheckoutStatus(resolvedCwd, { junctionHome: this.junctionHome });
+            if (!status.isGit) {
+                this.emit({
+                    type: 'checkout_status_response',
+                    payload: {
+                        cwd,
+                        isGit: false,
+                        repoRoot: null,
+                        currentBranch: null,
+                        isDirty: null,
+                        baseRef: null,
+                        aheadBehind: null,
+                        aheadOfOrigin: null,
+                        behindOfOrigin: null,
+                        hasRemote: false,
+                        remoteUrl: null,
+                        isJunctionOwnedWorktree: false,
+                        error: null,
+                        requestId,
+                    },
+                });
+                return;
+            }
+            if (status.isJunctionOwnedWorktree) {
+                this.emit({
+                    type: 'checkout_status_response',
+                    payload: {
+                        cwd,
+                        isGit: true,
+                        repoRoot: status.repoRoot ?? null,
+                        mainRepoRoot: status.mainRepoRoot,
+                        currentBranch: status.currentBranch ?? null,
+                        isDirty: status.isDirty ?? null,
+                        baseRef: status.baseRef,
+                        aheadBehind: status.aheadBehind ?? null,
+                        aheadOfOrigin: status.aheadOfOrigin ?? null,
+                        behindOfOrigin: status.behindOfOrigin ?? null,
+                        hasRemote: status.hasRemote,
+                        remoteUrl: status.remoteUrl,
+                        isJunctionOwnedWorktree: true,
+                        error: null,
+                        requestId,
+                    },
+                });
+                return;
+            }
+            this.emit({
+                type: 'checkout_status_response',
+                payload: {
+                    cwd,
+                    isGit: true,
+                    repoRoot: status.repoRoot ?? null,
+                    currentBranch: status.currentBranch ?? null,
+                    isDirty: status.isDirty ?? null,
+                    baseRef: status.baseRef ?? null,
+                    aheadBehind: status.aheadBehind ?? null,
+                    aheadOfOrigin: status.aheadOfOrigin ?? null,
+                    behindOfOrigin: status.behindOfOrigin ?? null,
+                    hasRemote: status.hasRemote,
+                    remoteUrl: status.remoteUrl,
+                    isJunctionOwnedWorktree: false,
+                    error: null,
+                    requestId,
+                },
+            });
+        }
+        catch (error) {
+            this.emit({
+                type: 'checkout_status_response',
+                payload: {
+                    cwd,
+                    isGit: false,
+                    repoRoot: null,
+                    currentBranch: null,
+                    isDirty: null,
+                    baseRef: null,
+                    aheadBehind: null,
+                    aheadOfOrigin: null,
+                    behindOfOrigin: null,
+                    hasRemote: false,
+                    remoteUrl: null,
+                    isJunctionOwnedWorktree: false,
+                    error: this.toCheckoutError(error),
+                    requestId,
+                },
+            });
+        }
+    }
+    async handleValidateBranchRequest(msg) {
+        const { cwd, branchName, requestId } = msg;
+        try {
+            const resolvedCwd = expandTilde(cwd);
+            // Try local branch first
+            try {
+                await execAsync(`git rev-parse --verify ${branchName}`, {
+                    cwd: resolvedCwd,
+                    env: READ_ONLY_GIT_ENV,
+                });
+                this.emit({
+                    type: 'validate_branch_response',
+                    payload: {
+                        exists: true,
+                        resolvedRef: branchName,
+                        isRemote: false,
+                        error: null,
+                        requestId,
+                    },
+                });
+                return;
+            }
+            catch {
+                // Local branch doesn't exist, try remote
+            }
+            // Try remote branch (origin/{branchName})
+            try {
+                await execAsync(`git rev-parse --verify origin/${branchName}`, {
+                    cwd: resolvedCwd,
+                    env: READ_ONLY_GIT_ENV,
+                });
+                this.emit({
+                    type: 'validate_branch_response',
+                    payload: {
+                        exists: true,
+                        resolvedRef: `origin/${branchName}`,
+                        isRemote: true,
+                        error: null,
+                        requestId,
+                    },
+                });
+                return;
+            }
+            catch {
+                // Remote branch doesn't exist either
+            }
+            // Branch not found anywhere
+            this.emit({
+                type: 'validate_branch_response',
+                payload: {
+                    exists: false,
+                    resolvedRef: null,
+                    isRemote: false,
+                    error: null,
+                    requestId,
+                },
+            });
+        }
+        catch (error) {
+            this.emit({
+                type: 'validate_branch_response',
+                payload: {
+                    exists: false,
+                    resolvedRef: null,
+                    isRemote: false,
+                    error: error instanceof Error ? error.message : String(error),
+                    requestId,
+                },
+            });
+        }
+    }
+    async handleBranchSuggestionsRequest(msg) {
+        const { cwd, query, limit, requestId } = msg;
+        try {
+            const resolvedCwd = expandTilde(cwd);
+            const branches = await listBranchSuggestions(resolvedCwd, { query, limit });
+            this.emit({
+                type: 'branch_suggestions_response',
+                payload: {
+                    branches,
+                    error: null,
+                    requestId,
+                },
+            });
+        }
+        catch (error) {
+            this.emit({
+                type: 'branch_suggestions_response',
+                payload: {
+                    branches: [],
+                    error: error instanceof Error ? error.message : String(error),
+                    requestId,
+                },
+            });
+        }
+    }
+    async handleDirectorySuggestionsRequest(msg) {
+        const { query, limit, requestId, cwd, includeFiles, includeDirectories, onlyGitRepos } = msg;
+        try {
+            const workspaceCwd = cwd?.trim();
+            let entries;
+            if (workspaceCwd) {
+                entries = await searchWorkspaceEntries({
+                    cwd: expandTilde(workspaceCwd),
+                    query,
+                    limit,
+                    includeFiles,
+                    includeDirectories,
+                });
+            }
+            else if (onlyGitRepos) {
+                entries = await searchGitRepositories({
+                    homeDir: process.env.HOME ?? homedir(),
+                    query,
+                    limit,
+                });
+            }
+            else {
+                const dirs = await searchHomeDirectories({
+                    homeDir: process.env.HOME ?? homedir(),
+                    query,
+                    limit,
+                });
+                entries = await Promise.all(dirs.map(async (dirPath) => ({
+                    path: dirPath,
+                    kind: 'directory',
+                    isGitRepo: await checkIsGitRepo(dirPath),
+                })));
+            }
+            const directories = entries
+                .filter((entry) => entry.kind === 'directory')
+                .map((entry) => entry.path);
+            this.emit({
+                type: 'directory_suggestions_response',
+                payload: {
+                    directories,
+                    entries,
+                    error: null,
+                    requestId,
+                },
+            });
+        }
+        catch (error) {
+            this.emit({
+                type: 'directory_suggestions_response',
+                payload: {
+                    directories: [],
+                    entries: [],
+                    error: error instanceof Error ? error.message : String(error),
+                    requestId,
+                },
+            });
+        }
+    }
+    async handleGitCloneRequest(msg) {
+        const { url, targetDirectory, requestId } = msg;
+        try {
+            const result = await cloneRepository({
+                url,
+                targetDirectory: expandTilde(targetDirectory),
+                homeDir: process.env.HOME ?? homedir(),
+            });
+            this.emit({
+                type: 'git_clone_response',
+                payload: {
+                    clonedPath: result.clonedPath,
+                    error: null,
+                    requestId,
+                },
+            });
+        }
+        catch (error) {
+            this.emit({
+                type: 'git_clone_response',
+                payload: {
+                    clonedPath: null,
+                    error: error instanceof Error ? error.message : String(error),
+                    requestId,
+                },
+            });
+        }
+    }
+    async handleGitInitRequest(msg) {
+        const { targetDirectory, projectName, requestId } = msg;
+        try {
+            const result = await initRepository({
+                targetDirectory: expandTilde(targetDirectory),
+                projectName,
+                homeDir: process.env.HOME ?? homedir(),
+            });
+            this.emit({
+                type: 'git_init_response',
+                payload: {
+                    createdPath: result.createdPath,
+                    error: null,
+                    requestId,
+                },
+            });
+        }
+        catch (error) {
+            this.emit({
+                type: 'git_init_response',
+                payload: {
+                    createdPath: null,
+                    error: error instanceof Error ? error.message : String(error),
+                    requestId,
+                },
+            });
+        }
+    }
+    normalizeCheckoutDiffCompare(compare) {
+        if (compare.mode === 'uncommitted' || compare.mode === 'staged' || compare.mode === 'unstaged') {
+            return { mode: compare.mode };
+        }
+        const trimmedBaseRef = compare.baseRef?.trim();
+        return trimmedBaseRef ? { mode: 'base', baseRef: trimmedBaseRef } : { mode: 'base' };
+    }
+    buildCheckoutDiffTargetKey(cwd, compare) {
+        return JSON.stringify([
+            cwd,
+            compare.mode,
+            compare.mode === 'base' ? (compare.baseRef ?? '') : '',
+        ]);
+    }
+    closeCheckoutDiffWatchTarget(target) {
+        if (target.debounceTimer) {
+            clearTimeout(target.debounceTimer);
+            target.debounceTimer = null;
+        }
+        if (target.fallbackRefreshInterval) {
+            clearInterval(target.fallbackRefreshInterval);
+            target.fallbackRefreshInterval = null;
+        }
+        for (const watcher of target.watchers) {
+            watcher.close();
+        }
+        target.watchers = [];
+    }
+    removeCheckoutDiffSubscription(subscriptionId) {
+        const subscription = this.checkoutDiffSubscriptions.get(subscriptionId);
+        if (!subscription) {
+            return;
+        }
+        this.checkoutDiffSubscriptions.delete(subscriptionId);
+        const target = this.checkoutDiffTargets.get(subscription.targetKey);
+        if (!target) {
+            return;
+        }
+        target.subscriptions.delete(subscriptionId);
+        if (target.subscriptions.size === 0) {
+            this.closeCheckoutDiffWatchTarget(target);
+            this.checkoutDiffTargets.delete(subscription.targetKey);
+        }
+    }
+    async resolveCheckoutGitDir(cwd) {
+        try {
+            const { stdout } = await execAsync('git rev-parse --absolute-git-dir', {
+                cwd,
+                env: READ_ONLY_GIT_ENV,
+            });
+            const gitDir = stdout.trim();
+            return gitDir.length > 0 ? gitDir : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async resolveCheckoutWatchRoot(cwd) {
+        try {
+            const { stdout } = await execAsync('git rev-parse --path-format=absolute --show-toplevel', {
+                cwd,
+                env: READ_ONLY_GIT_ENV,
+            });
+            const root = stdout.trim();
+            return root.length > 0 ? root : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    scheduleCheckoutDiffTargetRefresh(target) {
+        if (target.debounceTimer) {
+            clearTimeout(target.debounceTimer);
+        }
+        target.debounceTimer = setTimeout(() => {
+            target.debounceTimer = null;
+            void this.refreshCheckoutDiffTarget(target);
+        }, CHECKOUT_DIFF_WATCH_DEBOUNCE_MS);
+    }
+    emitCheckoutDiffUpdate(target, snapshot) {
+        if (target.subscriptions.size === 0) {
+            return;
+        }
+        for (const subscriptionId of target.subscriptions) {
+            this.emit({
+                type: 'checkout_diff_update',
+                payload: {
+                    subscriptionId,
+                    ...snapshot,
+                },
+            });
+        }
+    }
+    checkoutDiffSnapshotFingerprint(snapshot) {
+        return JSON.stringify(snapshot);
+    }
+    async computeCheckoutDiffSnapshot(cwd, compare, options) {
+        const diffCwd = options?.diffCwd ?? cwd;
+        try {
+            const diffResult = await getCheckoutDiff(diffCwd, {
+                mode: compare.mode,
+                baseRef: compare.baseRef,
+                includeStructured: true,
+            }, { junctionHome: this.junctionHome });
+            const files = [...(diffResult.structured ?? [])];
+            files.sort((a, b) => {
+                if (a.path === b.path)
+                    return 0;
+                return a.path < b.path ? -1 : 1;
+            });
+            return {
+                cwd,
+                files,
+                error: null,
+            };
+        }
+        catch (error) {
+            return {
+                cwd,
+                files: [],
+                error: this.toCheckoutError(error),
+            };
+        }
+    }
+    async refreshCheckoutDiffTarget(target) {
+        if (target.refreshPromise) {
+            target.refreshQueued = true;
+            return;
+        }
+        target.refreshPromise = (async () => {
+            do {
+                target.refreshQueued = false;
+                const snapshot = await this.computeCheckoutDiffSnapshot(target.cwd, target.compare, {
+                    diffCwd: target.diffCwd,
+                });
+                target.latestPayload = snapshot;
+                const fingerprint = this.checkoutDiffSnapshotFingerprint(snapshot);
+                if (fingerprint !== target.latestFingerprint) {
+                    target.latestFingerprint = fingerprint;
+                    this.emitCheckoutDiffUpdate(target, snapshot);
+                }
+            } while (target.refreshQueued);
+        })();
+        try {
+            await target.refreshPromise;
+        }
+        finally {
+            target.refreshPromise = null;
+        }
+    }
+    async ensureCheckoutDiffWatchTarget(cwd, compare) {
+        const targetKey = this.buildCheckoutDiffTargetKey(cwd, compare);
+        const existing = this.checkoutDiffTargets.get(targetKey);
+        if (existing) {
+            return existing;
+        }
+        const watchRoot = await this.resolveCheckoutWatchRoot(cwd);
+        const target = {
+            key: targetKey,
+            cwd,
+            diffCwd: watchRoot ?? cwd,
+            compare,
+            subscriptions: new Set(),
+            watchers: [],
+            fallbackRefreshInterval: null,
+            debounceTimer: null,
+            refreshPromise: null,
+            refreshQueued: false,
+            latestPayload: null,
+            latestFingerprint: null,
+        };
+        const repoWatchPath = watchRoot ?? cwd;
+        const watchPaths = new Set([repoWatchPath]);
+        const gitDir = await this.resolveCheckoutGitDir(cwd);
+        if (gitDir) {
+            watchPaths.add(gitDir);
+        }
+        let hasRecursiveRepoCoverage = false;
+        const allowRecursiveRepoWatch = process.platform !== 'linux';
+        for (const watchPath of watchPaths) {
+            const shouldTryRecursive = watchPath === repoWatchPath && allowRecursiveRepoWatch;
+            const createWatcher = (recursive) => watch(watchPath, { recursive }, () => {
+                this.scheduleCheckoutDiffTargetRefresh(target);
+            });
+            let watcher = null;
+            let watcherIsRecursive = false;
+            try {
+                if (shouldTryRecursive) {
+                    watcher = createWatcher(true);
+                    watcherIsRecursive = true;
+                }
+                else {
+                    watcher = createWatcher(false);
+                }
+            }
+            catch (error) {
+                if (shouldTryRecursive) {
+                    try {
+                        watcher = createWatcher(false);
+                        this.sessionLogger.warn({ err: error, watchPath, cwd, compare }, 'Checkout diff recursive watch unavailable; using non-recursive fallback');
+                    }
+                    catch (fallbackError) {
+                        this.sessionLogger.warn({ err: fallbackError, watchPath, cwd, compare }, 'Failed to start checkout diff watcher');
+                    }
+                }
+                else {
+                    this.sessionLogger.warn({ err: error, watchPath, cwd, compare }, 'Failed to start checkout diff watcher');
+                }
+            }
+            if (!watcher) {
+                continue;
+            }
+            watcher.on('error', (error) => {
+                this.sessionLogger.warn({ err: error, watchPath, cwd, compare }, 'Checkout diff watcher error');
+            });
+            target.watchers.push(watcher);
+            if (watchPath === repoWatchPath && watcherIsRecursive) {
+                hasRecursiveRepoCoverage = true;
+            }
+        }
+        const missingRepoCoverage = !hasRecursiveRepoCoverage;
+        if (target.watchers.length === 0 || missingRepoCoverage) {
+            target.fallbackRefreshInterval = setInterval(() => {
+                this.scheduleCheckoutDiffTargetRefresh(target);
+            }, CHECKOUT_DIFF_FALLBACK_REFRESH_MS);
+            this.sessionLogger.warn({
+                cwd,
+                compare,
+                intervalMs: CHECKOUT_DIFF_FALLBACK_REFRESH_MS,
+                reason: target.watchers.length === 0 ? 'no_watchers' : 'missing_recursive_repo_root_coverage',
+            }, 'Checkout diff watchers unavailable; using timed refresh fallback');
+        }
+        this.checkoutDiffTargets.set(targetKey, target);
+        return target;
+    }
+    async handleSubscribeCheckoutDiffRequest(msg) {
+        const cwd = expandTilde(msg.cwd);
+        const compare = this.normalizeCheckoutDiffCompare(msg.compare);
+        this.removeCheckoutDiffSubscription(msg.subscriptionId);
+        const target = await this.ensureCheckoutDiffWatchTarget(cwd, compare);
+        target.subscriptions.add(msg.subscriptionId);
+        this.checkoutDiffSubscriptions.set(msg.subscriptionId, {
+            targetKey: target.key,
+        });
+        const snapshot = target.latestPayload ??
+            (await this.computeCheckoutDiffSnapshot(cwd, compare, {
+                diffCwd: target.diffCwd,
+            }));
+        target.latestPayload = snapshot;
+        target.latestFingerprint = this.checkoutDiffSnapshotFingerprint(snapshot);
+        this.emit({
+            type: 'subscribe_checkout_diff_response',
+            payload: {
+                subscriptionId: msg.subscriptionId,
+                ...snapshot,
+                requestId: msg.requestId,
+            },
+        });
+    }
+    handleUnsubscribeCheckoutDiffRequest(msg) {
+        this.removeCheckoutDiffSubscription(msg.subscriptionId);
+    }
+    scheduleCheckoutDiffRefreshForCwd(cwd) {
+        const resolvedCwd = expandTilde(cwd);
+        for (const target of this.checkoutDiffTargets.values()) {
+            if (target.cwd !== resolvedCwd && target.diffCwd !== resolvedCwd) {
+                continue;
+            }
+            this.scheduleCheckoutDiffTargetRefresh(target);
+        }
+    }
+    async handleCheckoutCommitRequest(msg) {
+        const { cwd, requestId } = msg;
+        try {
+            let message = msg.message?.trim() ?? '';
+            if (!message) {
+                message = await this.generateCommitMessage(cwd);
+            }
+            if (!message) {
+                throw new Error('Commit message is required');
+            }
+            await commitChanges(cwd, {
+                message,
+                addAll: msg.addAll ?? true,
+            });
+            this.scheduleCheckoutDiffRefreshForCwd(cwd);
+            this.emit({
+                type: 'checkout_commit_response',
+                payload: {
+                    cwd,
+                    success: true,
+                    error: null,
+                    requestId,
+                },
+            });
+        }
+        catch (error) {
+            this.emit({
+                type: 'checkout_commit_response',
+                payload: {
+                    cwd,
+                    success: false,
+                    error: this.toCheckoutError(error),
+                    requestId,
+                },
+            });
+        }
+    }
+    async handleCheckoutMergeRequest(msg) {
+        const { cwd, requestId } = msg;
+        try {
+            const status = await getCheckoutStatus(cwd, { junctionHome: this.junctionHome });
+            if (!status.isGit) {
+                try {
+                    await execAsync('git rev-parse --is-inside-work-tree', {
+                        cwd,
+                        env: READ_ONLY_GIT_ENV,
+                    });
+                }
+                catch (error) {
+                    const details = typeof error?.stderr === 'string'
+                        ? String(error.stderr).trim()
+                        : error instanceof Error
+                            ? error.message
+                            : String(error);
+                    throw new Error(`Not a git repository: ${cwd}\n${details}`.trim());
+                }
+            }
+            if (msg.requireCleanTarget) {
+                const { stdout } = await execAsync('git status --porcelain', {
+                    cwd,
+                    env: READ_ONLY_GIT_ENV,
+                });
+                if (stdout.trim().length > 0) {
+                    throw new Error('Working directory has uncommitted changes.');
+                }
+            }
+            let baseRef = msg.baseRef ?? (status.isGit ? status.baseRef : null);
+            if (!baseRef) {
+                throw new Error('Base branch is required for merge');
+            }
+            if (baseRef.startsWith('origin/')) {
+                baseRef = baseRef.slice('origin/'.length);
+            }
+            await mergeToBase(cwd, {
+                baseRef,
+                mode: msg.strategy === 'squash' ? 'squash' : 'merge',
+            }, { junctionHome: this.junctionHome });
+            this.scheduleCheckoutDiffRefreshForCwd(cwd);
+            this.emit({
+                type: 'checkout_merge_response',
+                payload: {
+                    cwd,
+                    success: true,
+                    error: null,
+                    requestId,
+                },
+            });
+        }
+        catch (error) {
+            this.emit({
+                type: 'checkout_merge_response',
+                payload: {
+                    cwd,
+                    success: false,
+                    error: this.toCheckoutError(error),
+                    requestId,
+                },
+            });
+        }
+    }
+    async handleCheckoutMergeFromBaseRequest(msg) {
+        const { cwd, requestId } = msg;
+        try {
+            if (msg.requireCleanTarget ?? true) {
+                const { stdout } = await execAsync('git status --porcelain', {
+                    cwd,
+                    env: READ_ONLY_GIT_ENV,
+                });
+                if (stdout.trim().length > 0) {
+                    throw new Error('Working directory has uncommitted changes.');
+                }
+            }
+            await mergeFromBase(cwd, {
+                baseRef: msg.baseRef,
+                requireCleanTarget: msg.requireCleanTarget ?? true,
+            });
+            this.scheduleCheckoutDiffRefreshForCwd(cwd);
+            this.emit({
+                type: 'checkout_merge_from_base_response',
+                payload: {
+                    cwd,
+                    success: true,
+                    error: null,
+                    requestId,
+                },
+            });
+        }
+        catch (error) {
+            this.emit({
+                type: 'checkout_merge_from_base_response',
+                payload: {
+                    cwd,
+                    success: false,
+                    error: this.toCheckoutError(error),
+                    requestId,
+                },
+            });
+        }
+    }
+    async handleCheckoutPushRequest(msg) {
+        const { cwd, requestId } = msg;
+        try {
+            await pushCurrentBranch(cwd);
+            this.emit({
+                type: 'checkout_push_response',
+                payload: {
+                    cwd,
+                    success: true,
+                    error: null,
+                    requestId,
+                },
+            });
+        }
+        catch (error) {
+            this.emit({
+                type: 'checkout_push_response',
+                payload: {
+                    cwd,
+                    success: false,
+                    error: this.toCheckoutError(error),
+                    requestId,
+                },
+            });
+        }
+    }
+    async handleCheckoutPrCreateRequest(msg) {
+        const { cwd, requestId } = msg;
+        try {
+            let title = msg.title?.trim() ?? '';
+            let body = msg.body?.trim() ?? '';
+            if (!title || !body) {
+                const generated = await this.generatePullRequestText(cwd, msg.baseRef);
+                if (!title)
+                    title = generated.title;
+                if (!body)
+                    body = generated.body;
+            }
+            const result = await createPullRequest(cwd, {
+                title,
+                body,
+                base: msg.baseRef,
+            });
+            this.emit({
+                type: 'checkout_pr_create_response',
+                payload: {
+                    cwd,
+                    url: result.url ?? null,
+                    number: result.number ?? null,
+                    error: null,
+                    requestId,
+                },
+            });
+        }
+        catch (error) {
+            this.emit({
+                type: 'checkout_pr_create_response',
+                payload: {
+                    cwd,
+                    url: null,
+                    number: null,
+                    error: this.toCheckoutError(error),
+                    requestId,
+                },
+            });
+        }
+    }
+    async handleCheckoutPrStatusRequest(msg) {
+        const { cwd, requestId } = msg;
+        try {
+            const prStatus = await getPullRequestStatus(cwd);
+            this.emit({
+                type: 'checkout_pr_status_response',
+                payload: {
+                    cwd,
+                    status: prStatus.status,
+                    githubFeaturesEnabled: prStatus.githubFeaturesEnabled,
+                    error: null,
+                    requestId,
+                },
+            });
+        }
+        catch (error) {
+            this.emit({
+                type: 'checkout_pr_status_response',
+                payload: {
+                    cwd,
+                    status: null,
+                    githubFeaturesEnabled: true,
+                    error: this.toCheckoutError(error),
+                    requestId,
+                },
+            });
+        }
+    }
+    async handleJunctionWorktreeListRequest(msg) {
+        const { requestId } = msg;
+        const cwd = msg.repoRoot ?? msg.cwd;
+        if (!cwd) {
+            this.emit({
+                type: 'junction_worktree_list_response',
+                payload: {
+                    worktrees: [],
+                    error: { code: 'UNKNOWN', message: 'cwd or repoRoot is required' },
+                    requestId,
+                },
+            });
+            return;
+        }
+        try {
+            const worktrees = await listJunctionWorktrees({ cwd, junctionHome: this.junctionHome });
+            this.emit({
+                type: 'junction_worktree_list_response',
+                payload: {
+                    worktrees: worktrees.map((entry) => ({
+                        worktreePath: entry.path,
+                        branchName: entry.branchName ?? null,
+                        head: entry.head ?? null,
+                    })),
+                    error: null,
+                    requestId,
+                },
+            });
+        }
+        catch (error) {
+            this.emit({
+                type: 'junction_worktree_list_response',
+                payload: {
+                    worktrees: [],
+                    error: this.toCheckoutError(error),
+                    requestId,
+                },
+            });
+        }
+    }
+    async maybeArchiveWorktreeAfterLastAgentArchived(options) {
+        try {
+            const ownership = await isJunctionOwnedWorktreeCwd(options.archivedAgentCwd, {
+                junctionHome: this.junctionHome,
+            });
+            if (!ownership.allowed) {
+                return;
+            }
+            const resolvedWorktree = await resolveJunctionWorktreeRootForCwd(options.archivedAgentCwd, {
+                junctionHome: this.junctionHome,
+            });
+            if (!resolvedWorktree) {
+                return;
+            }
+            const records = await this.agentStorage.list();
+            const recordsById = new Map(records.map((record) => [record.id, record]));
+            const targetPath = resolvedWorktree.worktreePath;
+            const hasRemainingNonArchivedRecord = records.some((record) => {
+                if (record.id === options.archivedAgentId || record.archivedAt) {
+                    return false;
+                }
+                return this.isPathWithinRoot(targetPath, record.cwd);
+            });
+            if (hasRemainingNonArchivedRecord) {
+                return;
+            }
+            const hasUnknownLiveAgent = this.agentManager.listAgents().some((agent) => {
+                if (agent.id === options.archivedAgentId) {
+                    return false;
+                }
+                if (!this.isPathWithinRoot(targetPath, agent.cwd)) {
+                    return false;
+                }
+                return !recordsById.has(agent.id);
+            });
+            if (hasUnknownLiveAgent) {
+                return;
+            }
+            const repoRoot = ownership.repoRoot;
+            if (!repoRoot) {
+                this.sessionLogger.warn({ agentId: options.archivedAgentId, worktreePath: targetPath }, 'Unable to resolve repo root for auto-archive after agent archive');
+                return;
+            }
+            await this.archiveJunctionWorktree({
+                targetPath,
+                repoRoot,
+                requestId: options.requestId,
+            });
+        }
+        catch (error) {
+            this.sessionLogger.warn({ err: error, agentId: options.archivedAgentId, cwd: options.archivedAgentCwd }, 'Failed to auto-archive worktree after agent archive');
+        }
+    }
+    async archiveJunctionWorktree(options) {
+        let targetPath = options.targetPath;
+        const resolvedWorktree = await resolveJunctionWorktreeRootForCwd(targetPath, {
+            junctionHome: this.junctionHome,
+        });
+        if (resolvedWorktree) {
+            targetPath = resolvedWorktree.worktreePath;
+        }
+        const removedAgents = new Set();
+        const agents = this.agentManager.listAgents();
+        for (const agent of agents) {
+            if (this.isPathWithinRoot(targetPath, agent.cwd)) {
+                removedAgents.add(agent.id);
+                try {
+                    await this.agentManager.closeAgent(agent.id);
+                }
+                catch {
+                    // ignore cleanup errors
+                }
+                try {
+                    await this.agentStorage.remove(agent.id);
+                }
+                catch {
+                    // ignore cleanup errors
+                }
+            }
+        }
+        const registryRecords = await this.agentStorage.list();
+        for (const record of registryRecords) {
+            if (this.isPathWithinRoot(targetPath, record.cwd)) {
+                removedAgents.add(record.id);
+                try {
+                    await this.agentStorage.remove(record.id);
+                }
+                catch {
+                    // ignore cleanup errors
+                }
+            }
+        }
+        await this.killTerminalsUnderPath(targetPath);
+        await deleteJunctionWorktree({
+            cwd: options.repoRoot,
+            worktreePath: targetPath,
+            junctionHome: this.junctionHome,
+        });
+        for (const agentId of removedAgents) {
+            this.emit({
+                type: 'agent_deleted',
+                payload: {
+                    agentId,
+                    requestId: options.requestId,
+                },
+            });
+        }
+        return Array.from(removedAgents);
+    }
+    async handleJunctionWorktreeArchiveRequest(msg) {
+        const { requestId } = msg;
+        let targetPath = msg.worktreePath;
+        let repoRoot = msg.repoRoot ?? null;
+        try {
+            if (!targetPath) {
+                if (!repoRoot || !msg.branchName) {
+                    throw new Error('worktreePath or repoRoot+branchName is required');
+                }
+                const worktrees = await listJunctionWorktrees({ cwd: repoRoot, junctionHome: this.junctionHome });
+                const match = worktrees.find((entry) => entry.branchName === msg.branchName);
+                if (!match) {
+                    throw new Error(`Junction worktree not found for branch ${msg.branchName}`);
+                }
+                targetPath = match.path;
+            }
+            const ownership = await isJunctionOwnedWorktreeCwd(targetPath, {
+                junctionHome: this.junctionHome,
+            });
+            if (!ownership.allowed) {
+                this.emit({
+                    type: 'junction_worktree_archive_response',
+                    payload: {
+                        success: false,
+                        removedAgents: [],
+                        error: {
+                            code: 'NOT_ALLOWED',
+                            message: 'Worktree is not a Junction-owned worktree',
+                        },
+                        requestId,
+                    },
+                });
+                return;
+            }
+            repoRoot = ownership.repoRoot ?? repoRoot ?? null;
+            if (!repoRoot) {
+                throw new Error('Unable to resolve repo root for worktree');
+            }
+            const removedAgents = await this.archiveJunctionWorktree({
+                targetPath,
+                repoRoot,
+                requestId,
+            });
+            this.emit({
+                type: 'junction_worktree_archive_response',
+                payload: {
+                    success: true,
+                    removedAgents,
+                    error: null,
+                    requestId,
+                },
+            });
+        }
+        catch (error) {
+            this.emit({
+                type: 'junction_worktree_archive_response',
+                payload: {
+                    success: false,
+                    removedAgents: [],
+                    error: this.toCheckoutError(error),
+                    requestId,
+                },
+            });
+        }
+    }
+    /**
+     * Handle read-only file explorer requests scoped to an agent's cwd
+     */
+    async handleFileExplorerRequest(request) {
+        const { agentId, path: requestedPath = '.', mode, requestId } = request;
+        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,
+                    relativePath: requestedPath,
+                });
+                this.emit({
+                    type: 'file_explorer_response',
+                    payload: {
+                        agentId,
+                        path: directory.path,
+                        mode,
+                        directory,
+                        file: null,
+                        error: null,
+                        requestId,
+                    },
+                });
+            }
+            else {
+                const file = await readExplorerFile({
+                    root: agent.cwd,
+                    relativePath: requestedPath,
+                });
+                this.emit({
+                    type: 'file_explorer_response',
+                    payload: {
+                        agentId,
+                        path: file.path,
+                        mode,
+                        directory: null,
+                        file,
+                        error: null,
+                        requestId,
+                    },
+                });
+            }
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, agentId, path: requestedPath }, `Failed to fulfill file explorer request for agent ${agentId}`);
+            this.emit({
+                type: 'file_explorer_response',
+                payload: {
+                    agentId,
+                    path: requestedPath,
+                    mode,
+                    directory: null,
+                    file: null,
+                    error: error.message,
+                    requestId,
+                },
+            });
+        }
+    }
+    /**
+     * Handle read-only file explorer requests scoped to a workspace cwd
+     */
+    async handleWorkspaceFileExplorerRequest(request) {
+        const { cwd, path: requestedPath = '.', mode, requestId } = request;
+        try {
+            const root = expandTilde(cwd);
+            if (mode === 'list') {
+                const directory = await listDirectoryEntries({
+                    root,
+                    relativePath: requestedPath,
+                });
+                this.emit({
+                    type: 'workspace_file_explorer_response',
+                    payload: {
+                        cwd,
+                        path: directory.path,
+                        mode,
+                        directory,
+                        file: null,
+                        error: null,
+                        requestId,
+                    },
+                });
+            }
+            else {
+                const file = await readExplorerFile({
+                    root,
+                    relativePath: requestedPath,
+                });
+                this.emit({
+                    type: 'workspace_file_explorer_response',
+                    payload: {
+                        cwd,
+                        path: file.path,
+                        mode,
+                        directory: null,
+                        file,
+                        error: null,
+                        requestId,
+                    },
+                });
+            }
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, cwd, path: requestedPath }, `Failed to fulfill workspace file explorer request for cwd ${cwd}`);
+            this.emit({
+                type: 'workspace_file_explorer_response',
+                payload: {
+                    cwd,
+                    path: requestedPath,
+                    mode,
+                    directory: null,
+                    file: null,
+                    error: error.message,
+                    requestId,
+                },
+            });
+        }
+    }
+    /**
+     * Handle project icon request for a given cwd
+     */
+    async handleProjectIconRequest(request) {
+        const { cwd, requestId } = request;
+        try {
+            const icon = await getProjectIcon(cwd);
+            this.emit({
+                type: 'project_icon_response',
+                payload: {
+                    cwd,
+                    icon,
+                    error: null,
+                    requestId,
+                },
+            });
+        }
+        catch (error) {
+            this.emit({
+                type: 'project_icon_response',
+                payload: {
+                    cwd,
+                    icon: null,
+                    error: error.message,
+                    requestId,
+                },
+            });
+        }
+    }
+    /**
+     * Handle file download token request scoped to an agent's 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})`);
+        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,
+                relativePath: requestedPath,
+            });
+            const entry = this.downloadTokenStore.issueToken({
+                agentId,
+                path: info.path,
+                absolutePath: info.absolutePath,
+                fileName: info.fileName,
+                mimeType: info.mimeType,
+                size: info.size,
+            });
+            this.emit({
+                type: 'file_download_token_response',
+                payload: {
+                    agentId,
+                    path: info.path,
+                    token: entry.token,
+                    fileName: entry.fileName,
+                    mimeType: entry.mimeType,
+                    size: entry.size,
+                    error: null,
+                    requestId,
+                },
+            });
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, agentId, path: requestedPath }, `Failed to issue download token for agent ${agentId}`);
+            this.emit({
+                type: 'file_download_token_response',
+                payload: {
+                    agentId,
+                    path: requestedPath,
+                    token: null,
+                    fileName: null,
+                    mimeType: null,
+                    size: null,
+                    error: error.message,
+                    requestId,
+                },
+            });
+        }
+    }
+    /**
+     * Build the current agent list payload (live + persisted), optionally filtered by labels.
+     */
+    async listAgentPayloads(filter) {
+        // Get live agents with session modes
+        const agentSnapshots = this.agentManager.listAgents();
+        const liveAgents = await Promise.all(agentSnapshots.map((agent) => this.buildAgentPayload(agent)));
+        // Add persisted agents that have not been lazily initialized yet
+        // (excluding internal agents which are for ephemeral system tasks)
+        const registryRecords = await this.agentStorage.list();
+        const liveIds = new Set(agentSnapshots.map((a) => a.id));
+        const persistedAgents = registryRecords
+            .filter((record) => !liveIds.has(record.id) && !record.internal)
+            .map((record) => this.buildStoredAgentPayload(record));
+        let agents = [...liveAgents, ...persistedAgents];
+        // Filter by labels if filter provided
+        if (filter?.labels) {
+            const filterLabels = filter.labels;
+            agents = agents.filter((agent) => Object.entries(filterLabels).every(([key, value]) => agent.labels[key] === value));
+        }
+        return agents;
+    }
+    async resolveAgentIdentifier(identifier) {
+        const trimmed = identifier.trim();
+        if (!trimmed) {
+            return { ok: false, error: 'Agent identifier cannot be empty' };
+        }
+        const stored = await this.agentStorage.list();
+        const storedRecords = stored.filter((record) => !record.internal);
+        const knownIds = new Set();
+        for (const record of storedRecords) {
+            knownIds.add(record.id);
+        }
+        for (const agent of this.agentManager.listAgents()) {
+            knownIds.add(agent.id);
+        }
+        if (knownIds.has(trimmed)) {
+            return { ok: true, agentId: trimmed };
+        }
+        const prefixMatches = Array.from(knownIds).filter((id) => id.startsWith(trimmed));
+        if (prefixMatches.length === 1) {
+            return { ok: true, agentId: prefixMatches[0] };
+        }
+        if (prefixMatches.length > 1) {
+            return {
+                ok: false,
+                error: `Agent identifier "${trimmed}" is ambiguous (${prefixMatches
+                    .slice(0, 5)
+                    .map((id) => id.slice(0, 8))
+                    .join(', ')}${prefixMatches.length > 5 ? ', …' : ''})`,
+            };
+        }
+        const titleMatches = storedRecords.filter((record) => record.title === trimmed);
+        if (titleMatches.length === 1) {
+            return { ok: true, agentId: titleMatches[0].id };
+        }
+        if (titleMatches.length > 1) {
+            return {
+                ok: false,
+                error: `Agent title "${trimmed}" is ambiguous (${titleMatches
+                    .slice(0, 5)
+                    .map((r) => r.id.slice(0, 8))
+                    .join(', ')}${titleMatches.length > 5 ? ', …' : ''})`,
+            };
+        }
+        return { ok: false, error: `Agent not found: ${trimmed}` };
+    }
+    async getAgentPayloadById(agentId) {
+        const live = this.agentManager.getAgent(agentId);
+        if (live) {
+            return await this.buildAgentPayload(live);
+        }
+        const record = await this.agentStorage.get(agentId);
+        if (!record || record.internal) {
+            return null;
+        }
+        return this.buildStoredAgentPayload(record);
+    }
+    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);
+        }
+        return deduped.length > 0 ? deduped : fallback;
+    }
+    getStatusPriority(agent) {
+        const attentionReason = agent.attentionReason ?? null;
+        const hasPendingPermission = (agent.pendingPermissions?.length ?? 0) > 0;
+        if (hasPendingPermission || 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;
+    }
+    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() ?? '';
+        }
+    }
+    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;
+        }
+        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));
+    }
+    compareFetchAgentsAgents(left, right, sort) {
+        for (const spec of sort) {
+            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.id.localeCompare(right.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,
+        };
+    }
+    compareAgentWithCursor(agent, cursor, sort) {
+        for (const spec of sort) {
+            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) {
+                continue;
+            }
+            return spec.direction === 'asc' ? base : -base;
+        }
+        return agent.id.localeCompare(cursor.id);
+    }
+    async listFetchAgentsEntries(request) {
+        const filter = request.filter;
+        const sort = this.normalizeFetchAgentsSort(request.sort);
+        const agents = await this.listAgentPayloads({
+            labels: filter?.labels,
+        });
+        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 candidates = [...agents];
+        candidates.sort((left, right) => this.compareFetchAgentsAgents(left, right, sort));
+        const cursorToken = request.page?.cursor;
+        if (cursorToken) {
+            const cursor = this.decodeFetchAgentsCursor(cursorToken, sort);
+            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,
+            },
+        };
+    }
+    async handleAbort() {
+        this.sessionLogger.info('Abort request');
+        this.abortController.abort();
+    }
+    async handleFetchAgents(request) {
+        const requestedSubscriptionId = request.subscribe?.subscriptionId?.trim();
+        const subscriptionId = request.subscribe
+            ? requestedSubscriptionId && requestedSubscriptionId.length > 0
+                ? requestedSubscriptionId
+                : uuidv4()
+            : null;
+        try {
+            if (subscriptionId) {
+                this.agentUpdatesSubscription = {
+                    subscriptionId,
+                    filter: request.filter,
+                    isBootstrapping: true,
+                    pendingUpdatesByAgentId: new Map(),
+                };
+            }
+            const payload = await this.listFetchAgentsEntries(request);
+            const snapshotUpdatedAtByAgentId = new Map();
+            for (const entry of payload.entries) {
+                const parsedUpdatedAt = Date.parse(entry.agent.updatedAt);
+                if (!Number.isNaN(parsedUpdatedAt)) {
+                    snapshotUpdatedAtByAgentId.set(entry.agent.id, parsedUpdatedAt);
+                }
+            }
+            this.emit({
+                type: 'fetch_agents_response',
+                payload: {
+                    requestId: request.requestId,
+                    ...(subscriptionId ? { subscriptionId } : {}),
+                    ...payload,
+                },
+            });
+            if (subscriptionId && this.agentUpdatesSubscription?.subscriptionId === subscriptionId) {
+                this.flushBootstrappedAgentUpdates({ snapshotUpdatedAtByAgentId });
+            }
+        }
+        catch (error) {
+            if (subscriptionId && this.agentUpdatesSubscription?.subscriptionId === subscriptionId) {
+                this.agentUpdatesSubscription = null;
+            }
+            const code = error instanceof SessionRequestError ? error.code : 'fetch_agents_failed';
+            const message = error instanceof Error ? error.message : 'Failed to fetch agents';
+            this.sessionLogger.error({ err: error }, 'Failed to handle fetch_agents_request');
+            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, project: null, error: resolved.error },
+            });
+            return;
+        }
+        const agent = await this.getAgentPayloadById(resolved.agentId);
+        if (!agent) {
+            this.emit({
+                type: 'fetch_agent_response',
+                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, project, error: null },
+        });
+    }
+    async handleFetchAgentTimelineRequest(msg) {
+        const direction = msg.direction ?? (msg.cursor ? 'after' : 'tail');
+        const projection = msg.projection ?? 'projected';
+        const requestedLimit = msg.limit;
+        const limit = requestedLimit ?? (direction === 'after' ? 0 : undefined);
+        const shouldLimitByProjectedWindow = projection === 'canonical' &&
+            direction === 'tail' &&
+            typeof requestedLimit === 'number' &&
+            requestedLimit > 0;
+        const cursor = msg.cursor
+            ? {
+                epoch: msg.cursor.epoch,
+                seq: msg.cursor.seq,
+            }
+            : undefined;
+        try {
+            const snapshot = await this.ensureAgentLoaded(msg.agentId);
+            let timeline = this.agentManager.fetchTimeline(msg.agentId, {
+                direction,
+                cursor,
+                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,
+                    direction,
+                    projection,
+                    epoch: timeline.epoch,
+                    reset: timeline.reset,
+                    staleCursor: timeline.staleCursor,
+                    gap: timeline.gap,
+                    window: timeline.window,
+                    startCursor,
+                    endCursor,
+                    hasOlder,
+                    hasNewer,
+                    entries,
+                    error: null,
+                },
+            });
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, agentId: msg.agentId }, 'Failed to handle fetch_agent_timeline_request');
+            this.emit({
+                type: 'fetch_agent_timeline_response',
+                payload: {
+                    requestId: msg.requestId,
+                    agentId: msg.agentId,
+                    direction,
+                    projection,
+                    epoch: '',
+                    reset: false,
+                    staleCursor: false,
+                    gap: false,
+                    window: { minSeq: 0, maxSeq: 0, nextSeq: 0 },
+                    startCursor: null,
+                    endCursor: null,
+                    hasOlder: false,
+                    hasNewer: false,
+                    entries: [],
+                    error: error instanceof Error ? error.message : String(error),
+                },
+            });
+        }
+    }
+    async handleSendAgentMessageRequest(msg) {
+        const resolved = await this.resolveAgentIdentifier(msg.agentId);
+        if (!resolved.ok) {
+            this.emit({
+                type: 'send_agent_message_response',
+                payload: {
+                    requestId: msg.requestId,
+                    agentId: msg.agentId,
+                    accepted: false,
+                    error: resolved.error,
+                },
+            });
+            return;
+        }
+        try {
+            const agentId = resolved.agentId;
+            const archivedAt = await this.getArchivedAt(agentId);
+            if (archivedAt) {
+                this.emit({
+                    type: 'send_agent_message_response',
+                    payload: {
+                        requestId: msg.requestId,
+                        agentId,
+                        accepted: false,
+                        error: `Agent ${agentId} is archived`,
+                    },
+                });
+                return;
+            }
+            await this.ensureAgentLoaded(agentId);
+            await this.interruptAgentIfRunning(agentId);
+            try {
+                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');
+            }
+            const prompt = this.buildAgentPrompt(msg.text, msg.images);
+            const started = this.startAgentStream(agentId, prompt);
+            if (!started.ok) {
+                this.emit({
+                    type: 'send_agent_message_response',
+                    payload: {
+                        requestId: msg.requestId,
+                        agentId,
+                        accepted: false,
+                        error: started.error,
+                    },
+                });
+                return;
+            }
+            const startAbort = new AbortController();
+            const startTimeoutMs = 15000;
+            const startTimeout = setTimeout(() => startAbort.abort('timeout'), startTimeoutMs);
+            try {
+                await this.agentManager.waitForAgentRunStart(agentId, { signal: startAbort.signal });
+            }
+            catch (error) {
+                const message = error instanceof Error
+                    ? error.message
+                    : typeof error === 'string'
+                        ? error
+                        : 'Unknown error';
+                this.emit({
+                    type: 'send_agent_message_response',
+                    payload: {
+                        requestId: msg.requestId,
+                        agentId,
+                        accepted: false,
+                        error: message,
+                    },
+                });
+                return;
+            }
+            finally {
+                clearTimeout(startTimeout);
+            }
+            this.emit({
+                type: 'send_agent_message_response',
+                payload: {
+                    requestId: msg.requestId,
+                    agentId,
+                    accepted: true,
+                    error: null,
+                },
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : typeof error === 'string' ? error : 'Unknown error';
+            this.emit({
+                type: 'send_agent_message_response',
+                payload: {
+                    requestId: msg.requestId,
+                    agentId: resolved.agentId,
+                    accepted: false,
+                    error: message,
+                },
+            });
+        }
+    }
+    async handleWaitForFinish(agentIdOrIdentifier, requestId, timeoutMs) {
+        const resolved = await this.resolveAgentIdentifier(agentIdOrIdentifier);
+        if (!resolved.ok) {
+            this.emit({
+                type: 'wait_for_finish_response',
+                payload: {
+                    requestId,
+                    status: 'error',
+                    final: null,
+                    error: resolved.error,
+                    lastMessage: null,
+                },
+            });
+            return;
+        }
+        const agentId = resolved.agentId;
+        const live = this.agentManager.getAgent(agentId);
+        if (!live) {
+            const record = await this.agentStorage.get(agentId);
+            if (!record || record.internal) {
+                this.emit({
+                    type: 'wait_for_finish_response',
+                    payload: {
+                        requestId,
+                        status: 'error',
+                        final: null,
+                        error: `Agent not found: ${agentId}`,
+                        lastMessage: null,
+                    },
+                });
+                return;
+            }
+            const final = this.buildStoredAgentPayload(record);
+            const status = record.attentionReason === 'permission'
+                ? 'permission'
+                : record.lastStatus === 'error'
+                    ? 'error'
+                    : 'idle';
+            this.emit({
+                type: 'wait_for_finish_response',
+                payload: { requestId, status, final, error: null, lastMessage: null },
+            });
+            return;
+        }
+        const abortController = new AbortController();
+        const hasTimeout = typeof timeoutMs === 'number' && timeoutMs > 0;
+        const timeoutHandle = hasTimeout
+            ? setTimeout(() => {
+                abortController.abort('timeout');
+            }, timeoutMs)
+            : null;
+        try {
+            let result = await this.agentManager.waitForAgentEvent(agentId, {
+                signal: abortController.signal,
+            });
+            let final = await this.getAgentPayloadById(agentId);
+            if (!final) {
+                throw new Error(`Agent ${agentId} disappeared while waiting`);
+            }
+            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 },
+            });
+        }
+        catch (error) {
+            const isAbort = error instanceof Error &&
+                (error.name === 'AbortError' || error.message.toLowerCase().includes('aborted'));
+            if (!isAbort) {
+                const message = error instanceof Error
+                    ? error.message
+                    : typeof error === 'string'
+                        ? error
+                        : 'Unknown error';
+                this.sessionLogger.error({ err: error, agentId }, 'wait_for_finish_request failed');
+                const final = await this.getAgentPayloadById(agentId);
+                this.emit({
+                    type: 'wait_for_finish_response',
+                    payload: {
+                        requestId,
+                        status: 'error',
+                        final,
+                        error: message,
+                        lastMessage: null,
+                    },
+                });
+                return;
+            }
+            const final = await this.getAgentPayloadById(agentId);
+            if (!final) {
+                throw new Error(`Agent ${agentId} disappeared while waiting`);
+            }
+            this.emit({
+                type: 'wait_for_finish_response',
+                payload: { requestId, status: 'timeout', final, error: null, lastMessage: null },
+            });
+        }
+        finally {
+            if (timeoutHandle) {
+                clearTimeout(timeoutHandle);
+            }
+        }
+    }
+    /**
+     * Emit a message to the client
+     */
+    emit(msg) {
+        this.onMessage(msg);
+    }
+    emitBinary(frame) {
+        if (!this.onBinaryMessage) {
+            return;
+        }
+        try {
+            this.onBinaryMessage(frame);
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error }, 'Failed to emit binary frame');
+        }
+    }
+    /**
+     * Clean up session resources
+     */
+    async cleanup() {
+        this.sessionLogger.trace('Cleaning up');
+        if (this.unsubscribeAgentEvents) {
+            this.unsubscribeAgentEvents();
+            this.unsubscribeAgentEvents = null;
+        }
+        // Abort any ongoing operations
+        this.abortController.abort();
+        // Close MCP clients
+        if (this.agentMcpClient) {
+            try {
+                await this.agentMcpClient.close();
+            }
+            catch (error) {
+                this.sessionLogger.error({ err: error }, 'Failed to close Agent MCP client');
+            }
+            this.agentMcpClient = null;
+            this.agentTools = null;
+        }
+        // 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);
+        }
+        this.checkoutDiffTargets.clear();
+        this.checkoutDiffSubscriptions.clear();
+    }
+    // ============================================================================
+    // 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({
+                type: 'list_terminals_response',
+                payload: {
+                    cwd: msg.cwd,
+                    terminals: [],
+                    requestId: msg.requestId,
+                },
+            });
+            return;
+        }
+        try {
+            const terminals = await this.terminalManager.getTerminals(msg.cwd);
+            for (const terminal of terminals) {
+                this.ensureTerminalExitSubscription(terminal);
+            }
+            this.emit({
+                type: 'list_terminals_response',
+                payload: {
+                    cwd: msg.cwd,
+                    terminals: terminals.map((t) => ({ id: t.id, name: t.name })),
+                    requestId: msg.requestId,
+                },
+            });
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, cwd: msg.cwd }, 'Failed to list terminals');
+            this.emit({
+                type: 'list_terminals_response',
+                payload: {
+                    cwd: msg.cwd,
+                    terminals: [],
+                    requestId: msg.requestId,
+                },
+            });
+        }
+    }
+    async handleCreateTerminalRequest(msg) {
+        if (!this.terminalManager) {
+            this.emit({
+                type: 'create_terminal_response',
+                payload: {
+                    terminal: null,
+                    error: 'Terminal manager not available',
+                    requestId: msg.requestId,
+                },
+            });
+            return;
+        }
+        try {
+            const session = await this.terminalManager.createTerminal({
+                cwd: msg.cwd,
+                name: msg.name,
+            });
+            this.ensureTerminalExitSubscription(session);
+            this.emit({
+                type: 'create_terminal_response',
+                payload: {
+                    terminal: { id: session.id, name: session.name, cwd: session.cwd },
+                    error: null,
+                    requestId: msg.requestId,
+                },
+            });
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, cwd: msg.cwd }, 'Failed to create terminal');
+            this.emit({
+                type: 'create_terminal_response',
+                payload: {
+                    terminal: null,
+                    error: error.message,
+                    requestId: msg.requestId,
+                },
+            });
+        }
+    }
+    async handleSubscribeTerminalRequest(msg) {
+        if (!this.terminalManager) {
+            this.emit({
+                type: 'subscribe_terminal_response',
+                payload: {
+                    terminalId: msg.terminalId,
+                    state: null,
+                    error: 'Terminal manager not available',
+                    requestId: msg.requestId,
+                },
+            });
+            return;
+        }
+        const session = this.terminalManager.getTerminal(msg.terminalId);
+        if (!session) {
+            this.emit({
+                type: 'subscribe_terminal_response',
+                payload: {
+                    terminalId: msg.terminalId,
+                    state: null,
+                    error: 'Terminal not found',
+                    requestId: msg.requestId,
+                },
+            });
+            return;
+        }
+        this.ensureTerminalExitSubscription(session);
+        // Unsubscribe from previous subscription if any
+        const existing = this.terminalSubscriptions.get(msg.terminalId);
+        if (existing) {
+            existing();
+        }
+        // Subscribe to terminal updates
+        const unsubscribe = session.subscribe((serverMsg) => {
+            if (serverMsg.type === 'full') {
+                this.emit({
+                    type: 'terminal_output',
+                    payload: {
+                        terminalId: msg.terminalId,
+                        state: serverMsg.state,
+                    },
+                });
+            }
+        });
+        this.terminalSubscriptions.set(msg.terminalId, unsubscribe);
+        // Send initial state
+        this.emit({
+            type: 'subscribe_terminal_response',
+            payload: {
+                terminalId: msg.terminalId,
+                state: session.getState(),
+                error: null,
+                requestId: msg.requestId,
+            },
+        });
+    }
+    handleUnsubscribeTerminalRequest(msg) {
+        const unsubscribe = this.terminalSubscriptions.get(msg.terminalId);
+        if (unsubscribe) {
+            unsubscribe();
+            this.terminalSubscriptions.delete(msg.terminalId);
+        }
+    }
+    handleTerminalInput(msg) {
+        if (!this.terminalManager) {
+            return;
+        }
+        const session = this.terminalManager.getTerminal(msg.terminalId);
+        if (!session) {
+            this.sessionLogger.warn({ terminalId: msg.terminalId }, 'Terminal not found for input');
+            return;
+        }
+        this.ensureTerminalExitSubscription(session);
+        session.send(msg.message);
+    }
+    killTrackedTerminal(terminalId, options) {
+        const unsubscribe = this.terminalSubscriptions.get(terminalId);
+        if (unsubscribe) {
+            unsubscribe();
+            this.terminalSubscriptions.delete(terminalId);
+        }
+        const streamId = this.terminalStreamByTerminalId.get(terminalId);
+        if (typeof streamId === 'number') {
+            this.detachTerminalStream(streamId, { emitExit: options?.emitExit ?? true });
+        }
+        this.terminalManager?.killTerminal(terminalId);
+    }
+    async killTerminalsUnderPath(rootPath) {
+        if (!this.terminalManager) {
+            return;
+        }
+        const cleanupErrors = [];
+        const terminalDirectories = [...this.terminalManager.listDirectories()];
+        for (const terminalCwd of terminalDirectories) {
+            if (!this.isPathWithinRoot(rootPath, terminalCwd)) {
+                continue;
+            }
+            try {
+                const terminals = await this.terminalManager.getTerminals(terminalCwd);
+                for (const terminal of [...terminals]) {
+                    this.killTrackedTerminal(terminal.id, { emitExit: true });
+                }
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                cleanupErrors.push({ cwd: terminalCwd, message });
+                this.sessionLogger.warn({ err: error, cwd: terminalCwd }, 'Failed to clean up worktree terminals during archive');
+            }
+        }
+        if (cleanupErrors.length > 0) {
+            const details = cleanupErrors.map((entry) => `${entry.cwd}: ${entry.message}`).join('; ');
+            throw new Error(`Failed to clean up worktree terminals during archive (${details})`);
+        }
+    }
+    async handleKillTerminalRequest(msg) {
+        if (!this.terminalManager) {
+            this.emit({
+                type: 'kill_terminal_response',
+                payload: {
+                    terminalId: msg.terminalId,
+                    success: false,
+                    requestId: msg.requestId,
+                },
+            });
+            return;
+        }
+        this.killTrackedTerminal(msg.terminalId, { emitExit: true });
+        this.emit({
+            type: 'kill_terminal_response',
+            payload: {
+                terminalId: msg.terminalId,
+                success: true,
+                requestId: msg.requestId,
+            },
+        });
+    }
+    async handleAttachTerminalStreamRequest(msg) {
+        if (!this.terminalManager || !this.onBinaryMessage) {
+            this.emit({
+                type: 'attach_terminal_stream_response',
+                payload: {
+                    terminalId: msg.terminalId,
+                    streamId: null,
+                    replayedFrom: 0,
+                    currentOffset: 0,
+                    earliestAvailableOffset: 0,
+                    reset: true,
+                    error: 'Terminal streaming not available',
+                    requestId: msg.requestId,
+                },
+            });
+            return;
+        }
+        const session = this.terminalManager.getTerminal(msg.terminalId);
+        if (!session) {
+            this.emit({
+                type: 'attach_terminal_stream_response',
+                payload: {
+                    terminalId: msg.terminalId,
+                    streamId: null,
+                    replayedFrom: 0,
+                    currentOffset: 0,
+                    earliestAvailableOffset: 0,
+                    reset: true,
+                    error: 'Terminal not found',
+                    requestId: msg.requestId,
+                },
+            });
+            return;
+        }
+        if (msg.rows || msg.cols) {
+            const state = session.getState();
+            session.send({
+                type: 'resize',
+                rows: msg.rows ?? state.rows,
+                cols: msg.cols ?? state.cols,
+            });
+        }
+        const existingStreamId = this.terminalStreamByTerminalId.get(msg.terminalId);
+        if (typeof existingStreamId === 'number') {
+            // 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 binding = {
+            terminalId: msg.terminalId,
+            unsubscribe: () => { },
+            lastOutputOffset: initialOffset,
+            lastAckOffset: initialOffset,
+            pendingChunks: [],
+            pendingBytes: 0,
+        };
+        this.terminalStreams.set(streamId, binding);
+        this.terminalStreamByTerminalId.set(msg.terminalId, streamId);
+        let rawSub;
+        try {
+            rawSub = session.subscribeRaw((chunk) => {
+                const currentBinding = this.terminalStreams.get(streamId);
+                if (!currentBinding) {
+                    return;
+                }
+                this.enqueueOrEmitTerminalStreamChunk(streamId, currentBinding, {
+                    data: chunk.data,
+                    startOffset: chunk.startOffset,
+                    endOffset: chunk.endOffset,
+                    replay: chunk.replay,
+                });
+            }, { fromOffset: msg.resumeOffset ?? 0 });
+        }
+        catch (error) {
+            this.terminalStreams.delete(streamId);
+            this.terminalStreamByTerminalId.delete(msg.terminalId);
+            throw error;
+        }
+        binding.unsubscribe = rawSub.unsubscribe;
+        binding.lastAckOffset = rawSub.replayedFrom;
+        if (binding.lastOutputOffset < rawSub.replayedFrom) {
+            binding.lastOutputOffset = rawSub.replayedFrom;
+        }
+        this.flushPendingTerminalStreamChunks(streamId, binding);
+        this.emit({
+            type: 'attach_terminal_stream_response',
+            payload: {
+                terminalId: msg.terminalId,
+                streamId,
+                replayedFrom: rawSub.replayedFrom,
+                currentOffset: rawSub.currentOffset,
+                earliestAvailableOffset: rawSub.earliestAvailableOffset,
+                reset: rawSub.reset,
+                error: null,
+                requestId: msg.requestId,
+            },
+        });
+    }
+    getTerminalStreamChunkByteLength(chunk) {
+        return Math.max(0, chunk.endOffset - chunk.startOffset);
+    }
+    canEmitTerminalStreamChunk(binding, chunk) {
+        return chunk.startOffset < binding.lastAckOffset + TERMINAL_STREAM_WINDOW_BYTES;
+    }
+    emitTerminalStreamChunk(streamId, binding, chunk) {
+        const payload = new Uint8Array(Buffer.from(chunk.data, 'utf8'));
+        this.emitBinary({
+            channel: BinaryMuxChannel.Terminal,
+            messageType: TerminalBinaryMessageType.OutputUtf8,
+            streamId,
+            offset: chunk.startOffset,
+            flags: chunk.replay ? TerminalBinaryFlags.Replay : 0,
+            payload,
+        });
+        binding.lastOutputOffset = chunk.endOffset;
+    }
+    enqueueOrEmitTerminalStreamChunk(streamId, binding, chunk) {
+        const chunkBytes = this.getTerminalStreamChunkByteLength(chunk);
+        if (binding.pendingChunks.length > 0 || !this.canEmitTerminalStreamChunk(binding, chunk)) {
+            if (binding.pendingChunks.length >= TERMINAL_STREAM_MAX_PENDING_CHUNKS ||
+                binding.pendingBytes + chunkBytes > TERMINAL_STREAM_MAX_PENDING_BYTES) {
+                this.sessionLogger.warn({
+                    streamId,
+                    pendingChunks: binding.pendingChunks.length,
+                    pendingBytes: binding.pendingBytes,
+                    chunkBytes,
+                }, 'Terminal stream pending buffer overflow; closing stream');
+                this.detachTerminalStream(streamId, { emitExit: true });
+                return;
+            }
+            binding.pendingChunks.push(chunk);
+            binding.pendingBytes += chunkBytes;
+            return;
+        }
+        this.emitTerminalStreamChunk(streamId, binding, chunk);
+    }
+    flushPendingTerminalStreamChunks(streamId, binding) {
+        while (binding.pendingChunks.length > 0) {
+            const next = binding.pendingChunks[0];
+            if (!next || !this.canEmitTerminalStreamChunk(binding, next)) {
+                break;
+            }
+            binding.pendingChunks.shift();
+            binding.pendingBytes -= this.getTerminalStreamChunkByteLength(next);
+            if (binding.pendingBytes < 0) {
+                binding.pendingBytes = 0;
+            }
+            this.emitTerminalStreamChunk(streamId, binding, next);
+        }
+    }
+    handleDetachTerminalStreamRequest(msg) {
+        const success = this.detachTerminalStream(msg.streamId, { emitExit: false });
+        this.emit({
+            type: 'detach_terminal_stream_response',
+            payload: {
+                streamId: msg.streamId,
+                success,
+                requestId: msg.requestId,
+            },
+        });
+    }
+    detachAllTerminalStreams(options) {
+        for (const streamId of Array.from(this.terminalStreams.keys())) {
+            this.detachTerminalStream(streamId, options);
+        }
+    }
+    detachTerminalStream(streamId, options) {
+        const binding = this.terminalStreams.get(streamId);
+        if (!binding) {
+            return false;
+        }
+        try {
+            binding.unsubscribe();
+        }
+        catch (error) {
+            this.sessionLogger.warn({ err: error, streamId }, 'Failed to unsubscribe terminal stream');
+        }
+        this.terminalStreams.delete(streamId);
+        if (this.terminalStreamByTerminalId.get(binding.terminalId) === streamId) {
+            this.terminalStreamByTerminalId.delete(binding.terminalId);
+        }
+        if (options?.emitExit) {
+            this.emit({
+                type: 'terminal_stream_exit',
+                payload: {
+                    streamId,
+                    terminalId: binding.terminalId,
+                },
+            });
+        }
+        return true;
+    }
+    allocateTerminalStreamId() {
+        let attempts = 0;
+        while (attempts < 0xffffffff) {
+            const candidate = this.nextTerminalStreamId >>> 0;
+            this.nextTerminalStreamId = ((this.nextTerminalStreamId + 1) & 0xffffffff) >>> 0;
+            if (candidate === 0) {
+                attempts += 1;
+                continue;
+            }
+            if (!this.terminalStreams.has(candidate)) {
+                return candidate;
+            }
+            attempts += 1;
+        }
+        throw new Error('Unable to allocate terminal stream id');
+    }
+}
+//# sourceMappingURL=session.js.map