@getpaseo/server 0.1.58 → 0.1.60

package/dist/server/server/session.js

@@ -1,13 +1,13 @@
 import equal from "fast-deep-equal";
 import { v4 as uuidv4 } from "uuid";
-import { stat } from "fs/promises";
-import { exec } from "node:child_process";
-import { promisify } from "util";
+import { TTLCache } from "@isaacs/ttlcache";
+import pMemoize from "p-memoize";
 import { resolve, sep } from "path";
 import { homedir } from "node:os";
 import { z } from "zod";
 import { isLegacyEditorTargetId, serializeAgentStreamEvent, } from "./messages.js";
 import { captureTerminalLines } from "../terminal/terminal.js";
+import { TerminalOutputCoalescer } from "../terminal/terminal-output-coalescer.js";
 import { TerminalStreamOpcode, encodeTerminalSnapshotPayload, encodeTerminalStreamFrame, decodeTerminalResizePayload, } from "../shared/terminal-stream-protocol.js";
 import { TTSManager } from "./agent/tts-manager.js";
 import { STTManager } from "./agent/stt-manager.js";
@@ -21,32 +21,43 @@ import { ensureAgentLoaded } from "./agent/agent-loading.js";
 import { sendPromptToAgent, unarchiveAgentState } from "./agent/mcp-shared.js";
 import { experimental_createMCPClient } from "ai";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { buildWorkspaceScriptPayloads } from "./script-status-projection.js";
+import { deriveProjectSlug } from "./workspace-git-metadata.js";
+import { spawnWorkspaceScript } from "./worktree-bootstrap.js";
 import { buildProviderRegistry } from "./agent/provider-registry.js";
+import { resolveSnapshotCwd } from "./agent/provider-snapshot-manager.js";
 import { scheduleAgentMetadataGeneration } from "./agent/agent-metadata-generator.js";
 import { buildStoredAgentPayload, resolveEffectiveThinkingOptionId, resolveStoredAgentPayloadUpdatedAt, toAgentPayload, } from "./agent/agent-projections.js";
 import { MAX_EXPLICIT_AGENT_TITLE_CHARS } from "./agent/agent-title-limits.js";
 import { appendTimelineItemIfAgentKnown, emitLiveTimelineItemIfAgentKnown, } from "./agent/timeline-append.js";
 import { projectTimelineRows, selectTimelineWindowByProjectedLimit, } from "./agent/timeline-projection.js";
 import { DEFAULT_STRUCTURED_GENERATION_PROVIDERS, StructuredAgentFallbackError, StructuredAgentResponseError, generateStructuredAgentResponseWithFallback, } from "./agent/agent-response-loop.js";
-import { buildProjectPlacementForCwd, checkoutLiteFromGitSnapshot, detectStaleWorkspaces, deriveProjectKind, deriveProjectRootPath, deriveWorkspaceId, deriveWorkspaceDisplayName, deriveWorkspaceKind, normalizeWorkspaceId as normalizePersistedWorkspaceId, } from "./workspace-registry-model.js";
+import { checkoutLiteFromGitSnapshot, normalizeWorkspaceId as normalizePersistedWorkspaceId, deriveProjectGroupingName, deriveWorkspaceId, deriveProjectRootPath, deriveProjectKind, deriveWorkspaceKind, deriveWorkspaceDisplayName, buildProjectPlacementForCwd as buildProjectPlacementForCwdStandalone, } from "./workspace-registry-model.js";
 import { createPersistedProjectRecord, createPersistedWorkspaceRecord, } from "./workspace-registry.js";
 import { buildVoiceModeSystemPrompt, stripVoiceModeSystemPrompt, wrapSpokenInput, } from "./voice-config.js";
 import { isVoicePermissionAllowed } from "./voice-permission-policy.js";
 import { listDirectoryEntries, readExplorerFile, getDownloadableFileInfo, } from "./file-explorer/service.js";
 import { runAsyncWorktreeBootstrap } from "./worktree-bootstrap.js";
-import { getCheckoutDiff, getCheckoutStatus, listBranchSuggestions, commitChanges, mergeToBase, mergeFromBase, pullCurrentBranch, pushCurrentBranch, createPullRequest, } from "../utils/checkout-git.js";
+import { archivePersistedWorkspaceRecord } from "./workspace-archive-service.js";
+import { WorkspaceReconciliationService } from "./workspace-reconciliation-service.js";
+import { checkoutResolvedBranch, commitChanges, mergeToBase, mergeFromBase, pullCurrentBranch, pushCurrentBranch, createPullRequest, } from "../utils/checkout-git.js";
 import { getProjectIcon } from "../utils/project-icon.js";
 import { expandTilde } from "../utils/path.js";
 import { searchHomeDirectories, searchWorkspaceEntries } from "../utils/directory-suggestions.js";
-import { READ_ONLY_GIT_ENV, toCheckoutError } from "./checkout-git-utils.js";
+import { toCheckoutError } from "./checkout-git-utils.js";
 import { toResolver } from "./speech/provider-resolver.js";
 import { resolveClientMessageId } from "./client-message-id.js";
 import { ChatServiceError } from "./chat/chat-service.js";
 import { notifyChatMentions } from "./chat/chat-mentions.js";
 import { execCommand } from "../utils/spawn.js";
-import { assertSafeGitRef as assertWorktreeSafeGitRef, buildAgentSessionConfig as buildWorktreeAgentSessionConfig, runWorktreeSetupInBackground as runWorktreeSetupInBackgroundSession, handleCreatePaseoWorktreeRequest as handleCreateWorktreeRequest, handlePaseoWorktreeArchiveRequest as handleWorktreeArchiveRequest, handlePaseoWorktreeListRequest as handleWorktreeListRequest, killTerminalsUnderPath as killWorktreeTerminalsUnderPath, registerPendingWorktreeWorkspace as registerPendingWorktreeWorkspaceSession, } from "./worktree-session.js";
-const execAsync = promisify(exec);
+import { createGitHubService, } from "../services/github-service.js";
+import { createPaseoWorktree, } from "./paseo-worktree-service.js";
+import { createWorktreeCoreDeps } from "./worktree-core.js";
+import { assertSafeGitRef as assertWorktreeSafeGitRef, buildAgentSessionConfig as buildWorktreeAgentSessionConfig, runWorktreeSetupInBackground as runWorktreeSetupInBackgroundSession, handleCreatePaseoWorktreeRequest as handleCreateWorktreeRequest, handlePaseoWorktreeArchiveRequest as handleWorktreeArchiveRequest, handlePaseoWorktreeListRequest as handleWorktreeListRequest, handleWorkspaceSetupStatusRequest as handleWorkspaceSetupStatusRequestMessage, } from "./worktree-session.js";
+import { killTerminalsUnderPath as killWorktreeTerminalsUnderPath } from "./paseo-worktree-archive-service.js";
+import { toWorktreeWireError } from "./worktree-errors.js";
 const MAX_INITIAL_AGENT_TITLE_CHARS = Math.min(60, MAX_EXPLICIT_AGENT_TITLE_CHARS);
+const WORKSPACE_GIT_WATCH_REMOVED_FINGERPRINT = "__removed__";
 // TODO: Remove once all app store clients are on >=0.1.45 and understand arbitrary provider strings.
 // Clients before 0.1.45 validate providers with z.enum(["claude", "codex", "opencode"]) and reject
 // the entire session message if they encounter an unknown provider.
@@ -56,7 +67,7 @@ const MIN_VERSION_FLEXIBLE_EDITOR_IDS = "0.1.50";
 function isAppVersionAtLeast(appVersion, minVersion) {
     if (!appVersion)
         return false;
-    // Strip RC/prerelease suffix: "0.1.45-rc.4" → "0.1.45"
+    // Strip prerelease suffix: "0.1.45-beta.4" -> "0.1.45"
     const base = appVersion.replace(/-.*$/, "");
     const parts = base.split(".").map(Number);
     const minParts = minVersion.split(".").map(Number);
@@ -77,6 +88,11 @@ function clientSupportsFlexibleEditorIds(appVersion) {
     return isAppVersionAtLeast(appVersion, MIN_VERSION_FLEXIBLE_EDITOR_IDS);
 }
 const MAX_TERMINAL_STREAM_SLOTS = 256;
+function beginAgentDeleteIfSupported(agentStorage, agentId) {
+    if ("beginDelete" in agentStorage && typeof agentStorage.beginDelete === "function") {
+        agentStorage.beginDelete(agentId);
+    }
+}
 function deriveInitialAgentTitle(prompt) {
     const firstContentLine = prompt
         .split(/\r?\n/)
@@ -146,6 +162,8 @@ const MIN_STREAMING_SEGMENT_DURATION_MS = 1000;
 const MIN_STREAMING_SEGMENT_BYTES = Math.round(PCM_BYTES_PER_MS * MIN_STREAMING_SEGMENT_DURATION_MS);
 const AgentIdSchema = z.string().uuid();
 const VOICE_INTERRUPT_CONFIRMATION_MS = 500;
+const AVAILABLE_EDITOR_TARGETS_CACHE_TTL_MS = 60000;
+const AVAILABLE_EDITOR_TARGETS_CACHE_KEY = "available";
 class VoiceFeatureUnavailableError extends Error {
     constructor(context) {
         super(context.message);
@@ -216,7 +234,18 @@ export class Session {
         this.nextTerminalSlot = 0;
         this.inflightRequests = 0;
         this.peakInflightRequests = 0;
+        this.availableEditorTargetsCache = new TTLCache({
+            ttl: AVAILABLE_EDITOR_TARGETS_CACHE_TTL_MS,
+            max: 1,
+            checkAgeOnGet: true,
+        });
+        this.getMemoizedAvailableEditorTargets = pMemoize(async () => this.resolveAvailableEditorTargets(), {
+            cache: this.availableEditorTargetsCache,
+            cacheKey: () => AVAILABLE_EDITOR_TARGETS_CACHE_KEY,
+        });
         this.checkoutDiffSubscriptions = new Map();
+        this.workspaceGitWatchTargets = new Map();
+        this.workspaceGitFetchSubscriptions = new Map();
         this.workspaceGitSubscriptions = new Map();
         this.voiceModeAgentId = null;
         this.voiceModeBaseConfig = null;
@@ -227,9 +256,9 @@ export class Session {
             attention: 3,
             done: 4,
         };
-        const { clientId, appVersion, onMessage, onBinaryMessage, onLifecycleIntent, logger, downloadTokenStore, pushTokenStore, paseoHome, agentManager, agentStorage, projectRegistry, workspaceRegistry, chatService, scheduleService, loopService, checkoutDiffManager, workspaceGitService, daemonConfigStore, mcpBaseUrl, stt, tts, terminalManager, providerSnapshotManager, voice, voiceBridge, dictation, agentProviderRuntimeSettings, providerOverrides, } = options;
+        const { clientId, appVersion, onMessage, onBinaryMessage, onLifecycleIntent, logger, downloadTokenStore, pushTokenStore, paseoHome, agentManager, agentStorage, projectRegistry, workspaceRegistry, chatService, scheduleService, loopService, checkoutDiffManager, github, workspaceGitService, daemonConfigStore, mcpBaseUrl, stt, tts, terminalManager, providerSnapshotManager, scriptRouteStore, scriptRuntimeStore, workspaceSetupSnapshots, onBranchChanged, getDaemonTcpPort, getDaemonTcpHost, resolveScriptHealth, voice, voiceBridge, dictation, agentProviderRuntimeSettings, providerOverrides, isDev, } = options;
         this.clientId = clientId;
-        this.appVersion = appVersion;
+        this.appVersion = appVersion ?? null;
         this.sessionId = uuidv4();
         this.onMessage = onMessage;
         this.onBinaryMessage = onBinaryMessage ?? null;
@@ -237,6 +266,11 @@ export class Session {
         this.downloadTokenStore = downloadTokenStore;
         this.pushTokenStore = pushTokenStore;
         this.paseoHome = paseoHome;
+        this.sessionLogger = logger.child({
+            module: "session",
+            clientId: this.clientId,
+            sessionId: this.sessionId,
+        });
         this.agentManager = agentManager;
         this.agentStorage = agentStorage;
         this.projectRegistry = projectRegistry;
@@ -245,11 +279,19 @@ export class Session {
         this.scheduleService = scheduleService;
         this.loopService = loopService;
         this.checkoutDiffManager = checkoutDiffManager;
+        this.github = github ?? createGitHubService();
         this.workspaceGitService = workspaceGitService;
         this.daemonConfigStore = daemonConfigStore;
         this.mcpBaseUrl = mcpBaseUrl ?? null;
         this.terminalManager = terminalManager;
         this.providerSnapshotManager = providerSnapshotManager ?? null;
+        this.scriptRouteStore = scriptRouteStore ?? null;
+        this.scriptRuntimeStore = scriptRuntimeStore ?? null;
+        this.workspaceSetupSnapshots = workspaceSetupSnapshots ?? new Map();
+        this.onBranchChanged = onBranchChanged;
+        this.getDaemonTcpPort = getDaemonTcpPort ?? null;
+        this.getDaemonTcpHost = getDaemonTcpHost ?? null;
+        this.resolveScriptHealth = resolveScriptHealth ?? null;
         if (this.terminalManager) {
             this.unsubscribeTerminalsChanged = this.terminalManager.subscribeTerminalsChanged((event) => this.handleTerminalsChanged(event));
         }
@@ -279,15 +321,13 @@ export class Session {
         this.getSpeechReadiness = dictation?.getSpeechReadiness;
         this.agentProviderRuntimeSettings = agentProviderRuntimeSettings;
         this.providerOverrides = providerOverrides;
+        this.isDev = isDev === true;
         this.abortController = new AbortController();
-        this.sessionLogger = logger.child({
-            module: "session",
-            clientId: this.clientId,
-            sessionId: this.sessionId,
-        });
         this.providerRegistry = buildProviderRegistry(this.sessionLogger, {
             runtimeSettings: this.agentProviderRuntimeSettings,
             providerOverrides: this.providerOverrides,
+            workspaceGitService: this.workspaceGitService,
+            isDev: this.isDev,
         });
         // Initialize per-session managers
         this.ttsManager = new TTSManager(this.sessionId, this.sessionLogger, tts);
@@ -309,6 +349,23 @@ export class Session {
             this.appVersion = appVersion;
         }
     }
+    async primeWorkspaceGitWatchFingerprintForWorkspace(workspace) {
+        const descriptor = await this.describeWorkspaceRecordWithGitData(workspace);
+        await this.primeWorkspaceGitWatchFingerprints([descriptor]);
+    }
+    async emitWorkspaceUpdateForWorkspaceId(workspaceId) {
+        await this.emitWorkspaceUpdatesForWorkspaceIds([workspaceId], { skipReconcile: true });
+    }
+    async archiveWorkspaceRecordForExternalMutation(workspaceId) {
+        await this.archiveWorkspaceRecord(workspaceId);
+    }
+    async emitWorkspaceUpdatesForExternalCwds(cwds) {
+        await this.emitWorkspaceUpdatesForCwds(cwds);
+    }
+    async warmWorkspaceGitDataForWorkspace(workspace) {
+        await this.primeWorkspaceGitWatchFingerprintForWorkspace(workspace);
+        await this.emitWorkspaceUpdateForWorkspaceId(workspace.workspaceId);
+    }
     /**
      * Get the client's current activity state
      */
@@ -323,6 +380,9 @@ export class Session {
             peakInflightRequests: this.peakInflightRequests,
         };
     }
+    emitServerMessage(message) {
+        this.emit(message);
+    }
     /**
      * Send initial state to client after connection
      */
@@ -332,18 +392,23 @@ export class Session {
     /**
      * Normalize a user prompt (with optional image metadata) for AgentManager
      */
-    buildAgentPrompt(text, images) {
+    buildAgentPrompt(text, images, attachments) {
         const normalized = text?.trim() ?? "";
-        if (!images || images.length === 0) {
+        const hasImages = Boolean(images && images.length > 0);
+        const hasAttachments = Boolean(attachments && attachments.length > 0);
+        if (!hasImages && !hasAttachments) {
             return normalized;
         }
         const blocks = [];
         if (normalized.length > 0) {
             blocks.push({ type: "text", text: normalized });
         }
-        for (const image of images) {
+        for (const image of images ?? []) {
             blocks.push({ type: "image", data: image.data, mimeType: image.mimeType });
         }
+        for (const attachment of attachments ?? []) {
+            blocks.push(attachment);
+        }
         return blocks;
     }
     /**
@@ -546,8 +611,7 @@ export class Session {
         if (storedUpdatedAt) {
             const liveUpdatedAt = Date.parse(payload.updatedAt);
             const persistedUpdatedAt = Date.parse(storedUpdatedAt);
-            if (!Number.isNaN(persistedUpdatedAt) &&
-                (Number.isNaN(liveUpdatedAt) || persistedUpdatedAt > liveUpdatedAt)) {
+            if (Number.isNaN(liveUpdatedAt) || persistedUpdatedAt > liveUpdatedAt) {
                 payload.updatedAt = storedUpdatedAt;
             }
         }
@@ -557,10 +621,10 @@ export class Session {
     buildStoredAgentPayload(record) {
         return buildStoredAgentPayload(record, this.providerRegistry, this.sessionLogger);
     }
-    // TODO: Remove once all app store clients are on >=0.1.45.
     isProviderVisibleToClient(provider) {
-        if (clientSupportsAllProviders(this.appVersion))
+        if (clientSupportsAllProviders(this.appVersion)) {
             return true;
+        }
         return LEGACY_PROVIDER_IDS.has(provider);
     }
     filterEditorsForClient(editors) {
@@ -618,7 +682,6 @@ export class Session {
         return update.kind === "remove" ? update.agentId : update.agent.id;
     }
     bufferOrEmitAgentUpdate(subscription, payload) {
-        // TODO: Remove once all app store clients are on >=0.1.45.
         if (payload.kind === "upsert" && !this.isProviderVisibleToClient(payload.agent.provider)) {
             return;
         }
@@ -655,156 +718,103 @@ export class Session {
             });
         }
     }
-    async buildProjectPlacement(cwd) {
-        return buildProjectPlacementForCwd({
-            cwd,
-            workspaceGitService: this.workspaceGitService,
-        });
-    }
-    buildPersistedProjectRecord(input) {
-        return createPersistedProjectRecord({
-            projectId: input.placement.projectKey,
-            rootPath: deriveProjectRootPath({
-                cwd: input.workspaceId,
-                checkout: input.placement.checkout,
-            }),
-            kind: deriveProjectKind(input.placement.checkout),
-            displayName: input.placement.projectName,
-            createdAt: input.createdAt,
-            updatedAt: input.updatedAt,
-            archivedAt: null,
-        });
+    async findWorkspaceByDirectory(cwd, options) {
+        const normalizedCwd = await this.resolveWorkspaceDirectory(cwd, options);
+        const workspaces = await this.workspaceRegistry.list();
+        const workspaceId = this.resolveRegisteredWorkspaceIdForCwd(normalizedCwd, workspaces);
+        return workspaces.find((workspace) => workspace.workspaceId === workspaceId) ?? null;
     }
-    buildPersistedWorkspaceRecord(input) {
-        return createPersistedWorkspaceRecord({
-            workspaceId: input.workspaceId,
-            projectId: input.placement.projectKey,
-            cwd: input.workspaceId,
-            kind: deriveWorkspaceKind(input.placement.checkout),
-            displayName: deriveWorkspaceDisplayName({
-                cwd: input.workspaceId,
-                checkout: input.placement.checkout,
-            }),
-            createdAt: input.createdAt,
-            updatedAt: input.updatedAt,
-            archivedAt: null,
-        });
-    }
-    async archiveProjectRecordIfEmpty(projectId, archivedAt) {
-        const siblingWorkspaces = (await this.workspaceRegistry.list()).filter((workspace) => workspace.projectId === projectId && !workspace.archivedAt);
-        if (siblingWorkspaces.length === 0) {
-            await this.projectRegistry.archive(projectId, archivedAt);
-        }
-    }
-    async reconcileWorkspaceRecord(workspaceId) {
-        const normalizedCwd = normalizePersistedWorkspaceId(workspaceId);
-        const placement = await this.buildProjectPlacement(normalizedCwd);
-        const resolvedWorkspaceId = deriveWorkspaceId(normalizedCwd, placement.checkout);
-        const staleWorkspace = resolvedWorkspaceId === normalizedCwd
-            ? null
-            : await this.workspaceRegistry.get(normalizedCwd);
-        const existing = (await this.workspaceRegistry.get(resolvedWorkspaceId)) ?? staleWorkspace;
-        await this.syncWorkspaceGitWatchTarget(resolvedWorkspaceId, {
-            isGit: placement.checkout.isGit,
-        });
-        const now = new Date().toISOString();
-        const nextProjectCreatedAt = existing?.createdAt ?? now;
-        const nextWorkspaceCreatedAt = existing?.createdAt ?? now;
-        const currentProjectRecord = await this.projectRegistry.get(placement.projectKey);
-        const nextProjectRecord = this.buildPersistedProjectRecord({
-            workspaceId: resolvedWorkspaceId,
-            placement,
-            createdAt: currentProjectRecord?.createdAt ?? nextProjectCreatedAt,
-            updatedAt: now,
-        });
-        const nextWorkspaceRecord = this.buildPersistedWorkspaceRecord({
-            workspaceId: resolvedWorkspaceId,
-            placement,
-            createdAt: nextWorkspaceCreatedAt,
-            updatedAt: now,
-        });
-        const needsWorkspaceUpdate = !existing ||
-            existing.archivedAt ||
-            existing.projectId !== nextWorkspaceRecord.projectId ||
-            existing.kind !== nextWorkspaceRecord.kind ||
-            existing.displayName !== nextWorkspaceRecord.displayName;
-        const needsProjectUpdate = !currentProjectRecord ||
-            currentProjectRecord.archivedAt ||
-            currentProjectRecord.rootPath !== nextProjectRecord.rootPath ||
-            currentProjectRecord.kind !== nextProjectRecord.kind ||
-            currentProjectRecord.displayName !== nextProjectRecord.displayName;
-        const needsStaleWorkspaceCleanup = !!staleWorkspace &&
-            !staleWorkspace.archivedAt &&
-            staleWorkspace.workspaceId !== resolvedWorkspaceId;
-        let removedWorkspaceId = null;
-        if (needsStaleWorkspaceCleanup) {
-            await this.workspaceRegistry.archive(staleWorkspace.workspaceId, now);
-            this.removeWorkspaceGitSubscription(staleWorkspace.workspaceId);
-            removedWorkspaceId = staleWorkspace.workspaceId;
-        }
-        if (!needsWorkspaceUpdate && !needsProjectUpdate && !needsStaleWorkspaceCleanup) {
-            return {
-                workspace: existing,
-                changed: false,
-                removedWorkspaceId: null,
-            };
+    async resolveWorkspaceDirectory(cwd, options) {
+        const normalizedCwd = normalizePersistedWorkspaceId(cwd);
+        if (options?.refreshGit === false) {
+            const snapshot = this.workspaceGitService.peekSnapshot(normalizedCwd);
+            return normalizePersistedWorkspaceId(snapshot?.git.repoRoot ?? normalizedCwd);
         }
-        await this.projectRegistry.upsert(nextProjectRecord);
-        await this.workspaceRegistry.upsert(nextWorkspaceRecord);
-        if (existing && existing.workspaceId !== resolvedWorkspaceId) {
-            await this.workspaceRegistry.archive(existing.workspaceId, now);
-            this.removeWorkspaceGitSubscription(existing.workspaceId);
-            removedWorkspaceId ?? (removedWorkspaceId = existing.workspaceId);
+        try {
+            const snapshot = await this.workspaceGitService.getSnapshot(normalizedCwd);
+            return normalizePersistedWorkspaceId(snapshot.git.repoRoot ?? normalizedCwd);
         }
-        if (existing && !existing.archivedAt && existing.projectId !== nextWorkspaceRecord.projectId) {
-            await this.archiveProjectRecordIfEmpty(existing.projectId, now);
+        catch {
+            return normalizedCwd;
         }
+    }
+    async buildProjectPlacementForWorkspace(workspace, projectRecord) {
+        const project = projectRecord ?? (await this.projectRegistry.get(workspace.projectId));
+        if (!project) {
+            throw new Error(`Project not found for workspace ${workspace.workspaceId}`);
+        }
+        const checkout = project.kind !== "git"
+            ? {
+                cwd: workspace.cwd,
+                isGit: false,
+                currentBranch: null,
+                remoteUrl: null,
+                worktreeRoot: null,
+                isPaseoOwnedWorktree: false,
+                mainRepoRoot: null,
+            }
+            : workspace.kind === "worktree"
+                ? {
+                    cwd: workspace.cwd,
+                    isGit: true,
+                    currentBranch: workspace.displayName,
+                    remoteUrl: null,
+                    worktreeRoot: workspace.cwd,
+                    isPaseoOwnedWorktree: true,
+                    mainRepoRoot: project.rootPath,
+                }
+                : {
+                    cwd: workspace.cwd,
+                    isGit: true,
+                    currentBranch: workspace.displayName,
+                    remoteUrl: null,
+                    worktreeRoot: workspace.cwd,
+                    isPaseoOwnedWorktree: false,
+                    mainRepoRoot: null,
+                };
         return {
-            workspace: nextWorkspaceRecord,
-            changed: true,
-            removedWorkspaceId,
+            projectKey: project.projectId,
+            projectName: project.displayName,
+            checkout,
         };
     }
-    async reconcileActiveWorkspaceRecords() {
-        const changedWorkspaceIds = new Set();
-        const activeWorkspaces = (await this.workspaceRegistry.list()).filter((workspace) => !workspace.archivedAt);
-        const staleWorkspaceIds = await detectStaleWorkspaces({
-            activeWorkspaces,
-            checkDirectoryExists: async (cwd) => {
-                try {
-                    await stat(cwd);
-                    return true;
-                }
-                catch {
-                    return false;
-                }
-            },
+    async buildProjectPlacementForCwd(cwd, options) {
+        const workspace = await this.findWorkspaceByDirectory(cwd, {
+            refreshGit: options?.refreshGit,
         });
-        for (const workspaceId of staleWorkspaceIds) {
-            await this.archiveWorkspaceRecord(workspaceId);
-            changedWorkspaceIds.add(workspaceId);
-        }
-        for (const workspace of activeWorkspaces) {
-            if (staleWorkspaceIds.has(workspace.workspaceId)) {
-                continue;
-            }
-            const result = await this.reconcileWorkspaceRecord(workspace.workspaceId);
-            if (result.changed) {
-                changedWorkspaceIds.add(result.workspace.workspaceId);
-                if (result.removedWorkspaceId) {
-                    changedWorkspaceIds.add(result.removedWorkspaceId);
-                }
+        if (!workspace) {
+            if (!options?.fallback) {
+                return null;
             }
+            const normalizedCwd = normalizePersistedWorkspaceId(cwd);
+            return {
+                projectKey: normalizedCwd,
+                projectName: deriveProjectGroupingName(normalizedCwd),
+                checkout: {
+                    cwd: normalizedCwd,
+                    isGit: false,
+                    currentBranch: null,
+                    remoteUrl: null,
+                    worktreeRoot: null,
+                    isPaseoOwnedWorktree: false,
+                    mainRepoRoot: null,
+                },
+            };
         }
-        return changedWorkspaceIds;
+        return this.buildProjectPlacementForWorkspace(workspace);
     }
     async forwardAgentUpdate(agent) {
         try {
-            await this.ensureWorkspaceRegistered(agent.cwd);
             const subscription = this.agentUpdatesSubscription;
             const payload = await this.buildAgentPayload(agent);
             if (subscription) {
-                const project = await this.buildProjectPlacement(payload.cwd);
+                const project = await this.buildProjectPlacementForCwd(payload.cwd, {
+                    refreshGit: false,
+                    fallback: true,
+                });
+                if (!project) {
+                    throw new Error(`Workspace not found for agent ${payload.id}`);
+                }
                 const matches = this.matchesAgentFilter({
                     agent: payload,
                     project,
@@ -854,6 +864,9 @@ export class Session {
                     case "fetch_agents_request":
                         await this.handleFetchAgents(msg);
                         break;
+                    case "fetch_agent_history_request":
+                        await this.handleFetchAgentHistory(msg);
+                        break;
                     case "fetch_workspaces_request":
                         await this.handleFetchWorkspacesRequest(msg);
                         break;
@@ -1019,6 +1032,12 @@ export class Session {
                     case "checkout_pr_status_request":
                         await this.handleCheckoutPrStatusRequest(msg);
                         break;
+                    case "pull_request_timeline_request":
+                        await this.handlePullRequestTimelineRequest(msg);
+                        break;
+                    case "github_search_request":
+                        await this.handleGitHubSearchRequest(msg);
+                        break;
                     case "paseo_worktree_list_request":
                         await this.handlePaseoWorktreeListRequest(msg);
                         break;
@@ -1028,6 +1047,9 @@ export class Session {
                     case "create_paseo_worktree_request":
                         await this.handleCreatePaseoWorktreeRequest(msg);
                         break;
+                    case "workspace_setup_status_request":
+                        await this.handleWorkspaceSetupStatusRequest(msg);
+                        break;
                     case "list_available_editors_request":
                         await this.handleListAvailableEditorsRequest(msg);
                         break;
@@ -1107,6 +1129,9 @@ export class Session {
                     case "create_terminal_request":
                         await this.handleCreateTerminalRequest(msg);
                         break;
+                    case "start_workspace_script_request":
+                        await this.handleStartWorkspaceScriptRequest(msg);
+                        break;
                     case "subscribe_terminal_request":
                         await this.handleSubscribeTerminalRequest(msg);
                         break;
@@ -1306,19 +1331,23 @@ export class Session {
         const knownCwd = this.agentManager.getAgent(agentId)?.cwd ??
             (await this.agentStorage.get(agentId))?.cwd ??
             null;
-        // Prevent the persistence hook from re-creating the record while we close/delete.
-        this.agentStorage.beginDelete(agentId);
+        // File-backed storage still needs an early delete fence before closeAgent().
+        beginAgentDeleteIfSupported(this.agentStorage, agentId);
         try {
             await this.agentManager.closeAgent(agentId);
         }
         catch (error) {
             this.sessionLogger.warn({ err: error, agentId }, `Failed to close agent ${agentId} during delete`);
         }
+        // Drain queued persistence from the just-closed agent before removing its
+        // durable snapshot, otherwise an in-flight background write can recreate it.
+        await this.agentManager.flush();
         try {
             await this.agentStorage.remove(agentId);
+            await this.agentManager.deleteCommittedTimeline(agentId);
         }
         catch (error) {
-            this.sessionLogger.error({ err: error, agentId }, `Failed to remove agent ${agentId} from registry`);
+            this.sessionLogger.error({ err: error, agentId }, `Failed to fully delete agent ${agentId}`);
         }
         this.emit({
             type: "agent_deleted",
@@ -1338,12 +1367,13 @@ export class Session {
         }
     }
     async handleArchiveAgentRequest(agentId, requestId) {
-        const result = await this.archiveAgentForClose(agentId);
+        this.sessionLogger.info({ agentId }, `Archiving agent ${agentId}`);
+        const { archivedAt } = await this.archiveAgentForClose(agentId);
         this.emit({
             type: "agent_archived",
             payload: {
-                agentId: result.agentId,
-                archivedAt: result.archivedAt,
+                agentId,
+                archivedAt,
                 requestId,
             },
         });
@@ -1360,22 +1390,10 @@ export class Session {
             };
         }
         const archivedAt = new Date().toISOString();
-        const normalizedStatus = existing.lastStatus === "running" || existing.lastStatus === "initializing"
-            ? "idle"
-            : existing.lastStatus;
-        await this.agentStorage.upsert({
-            ...existing,
-            archivedAt,
-            updatedAt: archivedAt,
-            lastStatus: normalizedStatus,
-            requiresAttention: false,
-            attentionReason: null,
-            attentionTimestamp: null,
-        });
+        await this.agentManager.archiveSnapshot(agentId, archivedAt);
         return { agentId, archivedAt };
     }
     async archiveAgentForClose(agentId) {
-        this.sessionLogger.info({ agentId }, `Archiving agent ${agentId}`);
         const liveAgent = this.agentManager.getAgent(agentId);
         if (liveAgent) {
             await this.interruptAgentIfRunning(agentId);
@@ -1391,22 +1409,30 @@ export class Session {
         }
         if (this.agentUpdatesSubscription) {
             const payload = this.buildStoredAgentPayload(archivedRecord);
-            const project = await this.buildProjectPlacement(payload.cwd);
-            const matches = this.matchesAgentFilter({
-                agent: payload,
-                project,
-                filter: this.agentUpdatesSubscription.filter,
-            });
-            this.bufferOrEmitAgentUpdate(this.agentUpdatesSubscription, matches
-                ? {
-                    kind: "upsert",
+            const project = await this.buildProjectPlacementForCwd(payload.cwd);
+            if (project) {
+                const matches = this.matchesAgentFilter({
                     agent: payload,
                     project,
-                }
-                : {
+                    filter: this.agentUpdatesSubscription.filter,
+                });
+                this.bufferOrEmitAgentUpdate(this.agentUpdatesSubscription, matches
+                    ? {
+                        kind: "upsert",
+                        agent: payload,
+                        project,
+                    }
+                    : {
+                        kind: "remove",
+                        agentId,
+                    });
+            }
+            else {
+                this.bufferOrEmitAgentUpdate(this.agentUpdatesSubscription, {
                     kind: "remove",
                     agentId,
                 });
+            }
             await this.emitWorkspaceUpdateForCwd(payload.cwd);
         }
         if (!archivedRecord.archivedAt) {
@@ -1477,26 +1503,10 @@ export class Session {
             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 } } : {}),
-                });
-            }
+            await this.agentManager.updateAgentMetadata(agentId, {
+                ...(normalizedName ? { title: normalizedName } : {}),
+                ...(normalizedLabels ? { labels: normalizedLabels } : {}),
+            });
             this.emit({
                 type: "update_agent_response",
                 payload: { requestId, agentId, accepted: true, error: null },
@@ -1824,10 +1834,17 @@ export class Session {
     /**
      * Handle text message to agent (with optional image attachments)
      */
-    async handleSendAgentMessage(agentId, text, messageId, images, runOptions, options) {
-        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)` : ""}`);
+    async handleSendAgentMessage(agentId, text, messageId, images, attachments, runOptions, options) {
+        this.sessionLogger.info({
+            agentId,
+            textPreview: text.substring(0, 50),
+            imageCount: images?.length ?? 0,
+            attachmentCount: attachments?.length ?? 0,
+        }, `Sending text to agent ${agentId}${images && images.length > 0 ? ` with ${images.length} image attachment(s)` : ""}${attachments && attachments.length > 0
+            ? ` and ${attachments.length} structured attachment(s)`
+            : ""}`);
         const promptText = options?.spokenInput ? wrapSpokenInput(text) : text;
-        const prompt = this.buildAgentPrompt(promptText, images);
+        const prompt = this.buildAgentPrompt(promptText, images, attachments);
         try {
             await sendPromptToAgent({
                 agentManager: this.agentManager,
@@ -1853,7 +1870,7 @@ export class Session {
      * Handle create agent request
      */
     async handleCreateAgentRequest(msg) {
-        const { config, worktreeName, requestId, initialPrompt, clientMessageId, outputSchema, git, images, labels, } = msg;
+        const { config, worktreeName, requestId, initialPrompt, clientMessageId, outputSchema, git, images, attachments, 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 trimmedPrompt = initialPrompt?.trim();
@@ -1865,11 +1882,24 @@ export class Session {
                 ...config,
                 ...(provisionalTitle ? { title: provisionalTitle } : {}),
             };
-            const { sessionConfig, worktreeConfig } = await this.buildAgentSessionConfig(resolvedConfig, git, worktreeName, labels);
-            await this.ensureWorkspaceRegistered(sessionConfig.cwd);
-            const snapshot = await this.agentManager.createAgent(sessionConfig, undefined, { labels });
+            const { sessionConfig, worktreeBootstrap } = await this.buildAgentSessionConfig(resolvedConfig, git, worktreeName, attachments);
+            const resolvedWorkspace = msg.workspaceId
+                ? await this.workspaceRegistry.get(msg.workspaceId)
+                : ((await this.findWorkspaceByDirectory(sessionConfig.cwd)) ??
+                    (await this.findOrCreateWorkspaceForDirectory(sessionConfig.cwd)));
+            if (!resolvedWorkspace) {
+                throw new Error(`Workspace not found: ${msg.workspaceId}`);
+            }
+            const snapshot = await this.agentManager.createAgent({
+                ...sessionConfig,
+                cwd: resolvedWorkspace.cwd,
+            }, undefined, {
+                labels,
+                workspaceId: resolvedWorkspace.workspaceId,
+                initialPrompt: trimmedPrompt,
+            });
             await this.forwardAgentUpdate(snapshot);
-            if (trimmedPrompt) {
+            if (trimmedPrompt || (images?.length ?? 0) > 0 || (attachments?.length ?? 0) > 0) {
                 scheduleAgentMetadataGeneration({
                     agentManager: this.agentManager,
                     agentId: snapshot.id,
@@ -1878,17 +1908,17 @@ export class Session {
                     explicitTitle,
                     paseoHome: this.paseoHome,
                     logger: this.sessionLogger,
+                    deps: {
+                        workspaceGitService: this.workspaceGitService,
+                    },
                 });
-                const started = await this.handleSendAgentMessage(snapshot.id, trimmedPrompt, resolveClientMessageId(clientMessageId), images, outputSchema ? { outputSchema } : undefined);
+                const started = await this.handleSendAgentMessage(snapshot.id, trimmedPrompt || "", resolveClientMessageId(clientMessageId), images, attachments, outputSchema ? { outputSchema } : undefined);
                 if (!started.ok) {
                     throw new Error(started.error);
                 }
             }
             if (requestId) {
-                const agentPayload = await this.getAgentPayloadById(snapshot.id);
-                if (!agentPayload) {
-                    throw new Error(`Agent ${snapshot.id} not found after creation`);
-                }
+                const agentPayload = await this.buildAgentPayload(snapshot);
                 this.emit({
                     type: "status",
                     payload: {
@@ -1899,10 +1929,11 @@ export class Session {
                     },
                 });
             }
-            if (worktreeConfig) {
+            if (worktreeBootstrap) {
                 void runAsyncWorktreeBootstrap({
                     agentId: snapshot.id,
-                    worktree: worktreeConfig,
+                    worktree: worktreeBootstrap.worktree,
+                    shouldBootstrap: worktreeBootstrap.shouldBootstrap,
                     terminalManager: this.terminalManager,
                     appendTimelineItem: (item) => appendTimelineItemIfAgentKnown({
                         agentManager: this.agentManager,
@@ -1920,6 +1951,7 @@ export class Session {
             this.sessionLogger.info({ agentId: snapshot.id, provider: snapshot.provider }, `Created agent ${snapshot.id} (${snapshot.provider})`);
         }
         catch (error) {
+            const wireError = toWorktreeWireError(error);
             this.sessionLogger.error({ err: error }, "Failed to create agent");
             if (requestId) {
                 this.emit({
@@ -1927,7 +1959,8 @@ export class Session {
                     payload: {
                         status: "agent_create_failed",
                         requestId,
-                        error: error?.message ?? String(error),
+                        error: wireError.message,
+                        errorCode: wireError.code,
                     },
                 });
             }
@@ -1937,7 +1970,7 @@ export class Session {
                     id: uuidv4(),
                     timestamp: new Date(),
                     type: "error",
-                    content: `Failed to create agent: ${error.message}`,
+                    content: `Failed to create agent: ${wireError.message}`,
                 },
             });
         }
@@ -1966,10 +1999,7 @@ export class Session {
             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`);
-                }
+                const agentPayload = await this.buildAgentPayload(snapshot);
                 this.emit({
                     type: "status",
                     payload: {
@@ -2066,50 +2096,140 @@ export class Session {
             this.handleAgentRunError(agentId, error, "Failed to cancel running agent on request");
         }
     }
-    async buildAgentSessionConfig(config, gitOptions, legacyWorktreeName, _labels) {
+    async buildAgentSessionConfig(config, gitOptions, legacyWorktreeName, attachments) {
         return buildWorktreeAgentSessionConfig({
             paseoHome: this.paseoHome,
             sessionLogger: this.sessionLogger,
             workspaceGitService: this.workspaceGitService,
+            createPaseoWorktree: (input, serviceOptions) => this.createPaseoWorktree(input, serviceOptions),
             checkoutExistingBranch: (cwd, branch) => this.checkoutExistingBranch(cwd, branch),
             createBranchFromBase: (params) => this.createBranchFromBase(params),
-        }, config, gitOptions, legacyWorktreeName, _labels);
+            github: this.github,
+        }, config, gitOptions, legacyWorktreeName, attachments);
     }
     async handleListProviderModelsRequest(msg) {
+        const cwd = resolveSnapshotCwd(msg.cwd ? expandTilde(msg.cwd) : undefined);
         const fetchedAt = new Date().toISOString();
-        try {
-            const models = await this.providerRegistry[msg.provider].fetchModels({
-                cwd: msg.cwd ? expandTilde(msg.cwd) : undefined,
-            });
+        const manager = this.providerSnapshotManager;
+        if (!manager) {
+            try {
+                const models = await this.providerRegistry[msg.provider].fetchModels({
+                    cwd,
+                    force: false,
+                });
+                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,
+                    },
+                });
+            }
+            return;
+        }
+        const entry = await this.getProviderSnapshotEntryForRead(cwd, msg.provider);
+        if (!entry) {
             this.emit({
                 type: "list_provider_models_response",
                 payload: {
                     provider: msg.provider,
-                    models,
-                    error: null,
+                    error: `Unknown provider: ${msg.provider}`,
                     fetchedAt,
                     requestId: msg.requestId,
                 },
             });
+            return;
         }
-        catch (error) {
-            this.sessionLogger.error({ err: error, provider: msg.provider }, `Failed to list models for ${msg.provider}`);
+        if (entry.status === "ready") {
             this.emit({
                 type: "list_provider_models_response",
                 payload: {
                     provider: msg.provider,
-                    error: error?.message ?? String(error),
-                    fetchedAt,
+                    models: entry.models ?? [],
+                    error: null,
+                    fetchedAt: entry.fetchedAt ?? fetchedAt,
                     requestId: msg.requestId,
                 },
             });
+            return;
         }
+        const errorMessage = entry.status === "error"
+            ? (entry.error ?? `Failed to list models for ${msg.provider}`)
+            : `Provider ${msg.provider} is not available`;
+        this.emit({
+            type: "list_provider_models_response",
+            payload: {
+                provider: msg.provider,
+                error: errorMessage,
+                fetchedAt,
+                requestId: msg.requestId,
+            },
+        });
     }
     async handleListProviderModesRequest(msg) {
         const fetchedAt = new Date().toISOString();
+        const cwd = resolveSnapshotCwd(msg.cwd ? expandTilde(msg.cwd) : undefined);
+        const manager = this.providerSnapshotManager;
+        if (manager) {
+            const entry = await this.getProviderSnapshotEntryForRead(cwd, msg.provider);
+            if (!entry) {
+                this.emit({
+                    type: "list_provider_modes_response",
+                    payload: {
+                        provider: msg.provider,
+                        error: `Unknown provider: ${msg.provider}`,
+                        fetchedAt,
+                        requestId: msg.requestId,
+                    },
+                });
+                return;
+            }
+            if (entry.status === "ready") {
+                this.emit({
+                    type: "list_provider_modes_response",
+                    payload: {
+                        provider: msg.provider,
+                        modes: entry.modes ?? [],
+                        error: null,
+                        fetchedAt: entry.fetchedAt ?? fetchedAt,
+                        requestId: msg.requestId,
+                    },
+                });
+                return;
+            }
+            const errorMessage = entry.status === "error"
+                ? (entry.error ?? `Failed to list modes for ${msg.provider}`)
+                : `Provider ${msg.provider} is not available`;
+            this.emit({
+                type: "list_provider_modes_response",
+                payload: {
+                    provider: msg.provider,
+                    error: errorMessage,
+                    fetchedAt,
+                    requestId: msg.requestId,
+                },
+            });
+            return;
+        }
         try {
             const modes = await this.providerRegistry[msg.provider].fetchModes({
-                cwd: msg.cwd ? expandTilde(msg.cwd) : undefined,
+                cwd,
+                force: false,
             });
             this.emit({
                 type: "list_provider_modes_response",
@@ -2135,6 +2255,21 @@ export class Session {
             });
         }
     }
+    async getProviderSnapshotEntryForRead(cwd, provider) {
+        const manager = this.providerSnapshotManager;
+        if (!manager) {
+            return undefined;
+        }
+        const findEntry = () => manager.getSnapshot(cwd).find((candidate) => candidate.provider === provider);
+        let entry = findEntry();
+        if (!entry || entry.status === "loading") {
+            // Awaits the in-flight warmup (deduped per-cwd) so old clients still get
+            // a resolved answer rather than a loading placeholder.
+            await manager.warmUpSnapshotForCwd({ cwd, providers: [provider] });
+            entry = findEntry();
+        }
+        return entry;
+    }
     buildDraftAgentSessionConfig(draftConfig) {
         return {
             provider: draftConfig.provider,
@@ -2177,9 +2312,7 @@ export class Session {
     async handleListAvailableProvidersRequest(msg) {
         const fetchedAt = new Date().toISOString();
         try {
-            let providers = await this.agentManager.listProviderAvailability();
-            // TODO: Remove once all app store clients are on >=0.1.45.
-            providers = providers.filter((p) => this.isProviderVisibleToClient(p.provider));
+            const providers = (await this.agentManager.listProviderAvailability()).filter((provider) => this.isProviderVisibleToClient(provider.provider));
             this.emit({
                 type: "list_available_providers_response",
                 payload: {
@@ -2220,10 +2353,17 @@ export class Session {
         });
     }
     async handleRefreshProvidersSnapshotRequest(msg) {
-        await this.providerSnapshotManager?.refresh({
-            cwd: msg.cwd ? expandTilde(msg.cwd) : undefined,
-            providers: msg.providers,
-        });
+        if (msg.cwd) {
+            await this.providerSnapshotManager?.refreshSnapshotForCwd({
+                cwd: expandTilde(msg.cwd),
+                providers: msg.providers,
+            });
+        }
+        else {
+            await this.providerSnapshotManager?.refreshSettingsSnapshot({
+                providers: msg.providers,
+            });
+        }
         this.emit({
             type: "refresh_providers_snapshot_response",
             payload: {
@@ -2276,7 +2416,10 @@ export class Session {
         return resolvedCandidate.startsWith(resolvedRoot + sep);
     }
     async generateCommitMessage(cwd) {
-        const diff = await getCheckoutDiff(cwd, { mode: "uncommitted", includeStructured: true }, { paseoHome: this.paseoHome });
+        const diff = await this.workspaceGitService.getCheckoutDiff(cwd, {
+            mode: "uncommitted",
+            includeStructured: true,
+        });
         const schema = z.object({
             message: z
                 .string()
@@ -2331,11 +2474,11 @@ export class Session {
         }
     }
     async generatePullRequestText(cwd, baseRef) {
-        const diff = await getCheckoutDiff(cwd, {
+        const diff = await this.workspaceGitService.getCheckoutDiff(cwd, {
             mode: "base",
             baseRef,
             includeStructured: true,
-        }, { paseoHome: this.paseoHome });
+        });
         const schema = z.object({
             title: z.string().min(1).max(72),
             body: z.string().min(1),
@@ -2396,11 +2539,8 @@ export class Session {
     }
     async isWorkingTreeDirty(cwd) {
         try {
-            const { stdout } = await execAsync("git status --porcelain", {
-                cwd,
-                env: READ_ONLY_GIT_ENV,
-            });
-            return stdout.trim().length > 0;
+            const snapshot = await this.workspaceGitService.getSnapshot(cwd);
+            return snapshot.git.isDirty === true;
         }
         catch (error) {
             throw new Error(`Unable to inspect git status for ${cwd}: ${error.message}`);
@@ -2408,30 +2548,24 @@ export class Session {
     }
     async checkoutExistingBranch(cwd, branch) {
         this.assertSafeGitRef(branch, "branch");
-        try {
-            await execCommand("git", ["rev-parse", "--verify", branch], { cwd });
-        }
-        catch (error) {
+        const resolution = await this.workspaceGitService.validateBranchRef(cwd, branch);
+        if (resolution.kind === "not-found") {
             throw new Error(`Branch not found: ${branch}`);
         }
-        const { stdout } = await execAsync("git rev-parse --abbrev-ref HEAD", {
+        await this.ensureCleanWorkingTree(cwd);
+        const result = await checkoutResolvedBranch({
             cwd,
+            resolution,
         });
-        const current = stdout.trim();
-        if (current === branch) {
-            return;
-        }
-        await this.ensureCleanWorkingTree(cwd);
-        await execCommand("git", ["checkout", branch], { cwd });
+        await this.notifyGitMutation(cwd, "switch-branch", { invalidateGithub: true });
+        return result;
     }
     async createBranchFromBase(params) {
         const { cwd, baseBranch, newBranchName } = params;
         this.assertSafeGitRef(baseBranch, "base branch");
         this.assertSafeGitRef(newBranchName, "new branch");
-        try {
-            await execCommand("git", ["rev-parse", "--verify", baseBranch], { cwd });
-        }
-        catch (error) {
+        const baseResolution = await this.workspaceGitService.validateBranchRef(cwd, baseBranch);
+        if (baseResolution.kind === "not-found") {
             throw new Error(`Base branch not found: ${baseBranch}`);
         }
         const exists = await this.doesLocalBranchExist(cwd, newBranchName);
@@ -2442,17 +2576,21 @@ export class Session {
         await execCommand("git", ["checkout", "-b", newBranchName, baseBranch], {
             cwd,
         });
+        await this.notifyGitMutation(cwd, "create-branch");
     }
     async doesLocalBranchExist(cwd, branch) {
         this.assertSafeGitRef(branch, "branch");
+        return this.workspaceGitService.hasLocalBranch(cwd, branch);
+    }
+    async notifyGitMutation(cwd, reason, options) {
+        if (options?.invalidateGithub) {
+            this.github.invalidate({ cwd });
+        }
         try {
-            await execCommand("git", ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], {
-                cwd,
-            });
-            return true;
+            await this.workspaceGitService.getSnapshot(cwd, { force: true, reason });
         }
         catch (error) {
-            return false;
+            this.sessionLogger.warn({ err: error, cwd, reason }, "Failed to force-refresh workspace git snapshot after mutation");
         }
     }
     /**
@@ -2658,7 +2796,15 @@ export class Session {
                 return;
             }
             if (!agent && draftConfig) {
-                const sessionConfig = this.buildDraftAgentSessionConfig(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",
@@ -2725,70 +2871,14 @@ export class Session {
         const { cwd, requestId } = msg;
         const resolvedCwd = expandTilde(cwd);
         try {
-            const status = await getCheckoutStatus(resolvedCwd, { paseoHome: this.paseoHome });
-            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,
-                        isPaseoOwnedWorktree: false,
-                        error: null,
-                        requestId,
-                    },
-                });
-                return;
-            }
-            if (status.isPaseoOwnedWorktree) {
-                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,
-                        isPaseoOwnedWorktree: true,
-                        error: null,
-                        requestId,
-                    },
-                });
-                return;
-            }
+            const snapshot = await this.workspaceGitService.getSnapshot(resolvedCwd);
             this.emit({
                 type: "checkout_status_response",
-                payload: {
+                payload: this.buildCheckoutStatusPayloadFromSnapshot({
                     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,
-                    isPaseoOwnedWorktree: false,
-                    error: null,
                     requestId,
-                },
+                    snapshot,
+                }),
             });
         }
         catch (error) {
@@ -2818,55 +2908,76 @@ export class Session {
         try {
             const resolvedCwd = expandTilde(cwd);
             this.assertSafeGitRef(branchName, "branch");
-            // Try local branch first
-            try {
-                await execCommand("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 execCommand("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
+            const resolution = await this.workspaceGitService.validateBranchRef(resolvedCwd, branchName);
+            switch (resolution.kind) {
+                case "local":
+                    this.emit({
+                        type: "validate_branch_response",
+                        payload: {
+                            exists: true,
+                            resolvedRef: resolution.name,
+                            isRemote: false,
+                            error: null,
+                            requestId,
+                        },
+                    });
+                    return;
+                case "remote-only":
+                    this.emit({
+                        type: "validate_branch_response",
+                        payload: {
+                            exists: true,
+                            resolvedRef: resolution.remoteRef,
+                            isRemote: true,
+                            error: null,
+                            requestId,
+                        },
+                    });
+                    return;
+                case "not-found":
+                    this.emit({
+                        type: "validate_branch_response",
+                        payload: {
+                            exists: false,
+                            resolvedRef: null,
+                            isRemote: false,
+                            error: null,
+                            requestId,
+                        },
+                    });
+                    return;
+                default: {
+                    const exhaustiveCheck = resolution;
+                    throw new Error(`Unhandled branch resolution: ${exhaustiveCheck}`);
+                }
             }
-            // Branch not found anywhere
+        }
+        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 branchDetails = await this.workspaceGitService.suggestBranchesForCwd(resolvedCwd, {
+                query,
+                limit,
+            });
+            this.emit({
+                type: "branch_suggestions_response",
+                payload: {
+                    branches: branchDetails.map((branch) => branch.name),
+                    branchDetails,
                     error: null,
                     requestId,
                 },
@@ -2874,26 +2985,31 @@ export class Session {
         }
         catch (error) {
             this.emit({
-                type: "validate_branch_response",
+                type: "branch_suggestions_response",
                 payload: {
-                    exists: false,
-                    resolvedRef: null,
-                    isRemote: false,
+                    branches: [],
+                    branchDetails: [],
                     error: error instanceof Error ? error.message : String(error),
                     requestId,
                 },
             });
         }
     }
-    async handleBranchSuggestionsRequest(msg) {
-        const { cwd, query, limit, requestId } = msg;
+    async handleGitHubSearchRequest(msg) {
+        const { cwd, query, limit, kinds, requestId } = msg;
         try {
             const resolvedCwd = expandTilde(cwd);
-            const branches = await listBranchSuggestions(resolvedCwd, { query, limit });
+            const result = await this.github.searchIssuesAndPrs({
+                cwd: resolvedCwd,
+                query,
+                limit,
+                kinds,
+            });
             this.emit({
-                type: "branch_suggestions_response",
+                type: "github_search_response",
                 payload: {
-                    branches,
+                    items: result.items,
+                    githubFeaturesEnabled: result.githubFeaturesEnabled,
                     error: null,
                     requestId,
                 },
@@ -2901,9 +3017,10 @@ export class Session {
         }
         catch (error) {
             this.emit({
-                type: "branch_suggestions_response",
+                type: "github_search_response",
                 payload: {
-                    branches: [],
+                    items: [],
+                    githubFeaturesEnabled: true,
                     error: error instanceof Error ? error.message : String(error),
                     requestId,
                 },
@@ -2952,24 +3069,97 @@ export class Session {
             });
         }
     }
+    closeWorkspaceGitWatchTarget(target) {
+        if (target.debounceTimer) {
+            clearTimeout(target.debounceTimer);
+            target.debounceTimer = null;
+        }
+        for (const watcher of target.watchers) {
+            try {
+                watcher.close();
+            }
+            catch {
+                // Ignore watcher close errors
+            }
+        }
+        target.watchers.length = 0;
+    }
+    async removeWorkspaceGitWatchTarget(cwd) {
+        const normalizedCwd = normalizePersistedWorkspaceId(cwd);
+        const target = this.workspaceGitWatchTargets.get(normalizedCwd);
+        if (target) {
+            this.closeWorkspaceGitWatchTarget(target);
+            this.workspaceGitWatchTargets.delete(normalizedCwd);
+        }
+    }
     removeWorkspaceGitSubscription(cwd) {
-        const workspaceId = normalizePersistedWorkspaceId(cwd);
-        this.workspaceGitSubscriptions.get(workspaceId)?.();
-        this.workspaceGitSubscriptions.delete(workspaceId);
+        const normalizedCwd = normalizePersistedWorkspaceId(cwd);
+        const target = this.workspaceGitWatchTargets.get(normalizedCwd);
+        if (target) {
+            const unsubscribeFetch = this.workspaceGitFetchSubscriptions.get(normalizedCwd);
+            unsubscribeFetch?.();
+            this.workspaceGitFetchSubscriptions.delete(normalizedCwd);
+            this.closeWorkspaceGitWatchTarget(target);
+            this.workspaceGitWatchTargets.delete(normalizedCwd);
+        }
+        this.workspaceGitSubscriptions.get(normalizedCwd)?.();
+        this.workspaceGitSubscriptions.delete(normalizedCwd);
+    }
+    workspaceGitDescriptorFingerprint(workspace) {
+        if (!workspace) {
+            return WORKSPACE_GIT_WATCH_REMOVED_FINGERPRINT;
+        }
+        return JSON.stringify([
+            workspace.name,
+            workspace.diffStat ? [workspace.diffStat.additions, workspace.diffStat.deletions] : null,
+        ]);
+    }
+    shouldSkipWorkspaceGitWatchUpdate(workspaceId, workspace) {
+        const target = this.workspaceGitWatchTargets.get(workspaceId);
+        if (!target) {
+            return false;
+        }
+        const nextFingerprint = this.workspaceGitDescriptorFingerprint(workspace);
+        if (target.latestFingerprint === nextFingerprint) {
+            return true;
+        }
+        target.latestFingerprint = nextFingerprint;
+        return false;
+    }
+    rememberWorkspaceGitWatchFingerprint(workspaceId, workspace) {
+        const target = this.workspaceGitWatchTargets.get(workspaceId);
+        if (!target) {
+            return;
+        }
+        target.latestFingerprint = this.workspaceGitDescriptorFingerprint(workspace);
+        target.lastBranchName = workspace?.name ?? null;
+    }
+    async primeWorkspaceGitWatchFingerprints(workspaces) {
+        for (const workspace of workspaces) {
+            const persistedWorkspace = await this.workspaceRegistry.get(workspace.id);
+            if (!persistedWorkspace) {
+                continue;
+            }
+            await this.syncWorkspaceGitWatchTarget(persistedWorkspace.cwd, {
+                isGit: workspace.projectKind === "git",
+            });
+            this.rememberWorkspaceGitWatchFingerprint(persistedWorkspace.cwd, workspace);
+        }
     }
     async syncWorkspaceGitWatchTarget(cwd, options) {
-        const workspaceId = normalizePersistedWorkspaceId(cwd);
+        const normalizedCwd = normalizePersistedWorkspaceId(cwd);
         if (!options.isGit) {
-            this.removeWorkspaceGitSubscription(workspaceId);
+            this.removeWorkspaceGitSubscription(normalizedCwd);
             return;
         }
-        if (this.workspaceGitSubscriptions.has(workspaceId)) {
+        if (this.workspaceGitSubscriptions.has(normalizedCwd)) {
             return;
         }
-        const subscription = await this.workspaceGitService.subscribe({ cwd: workspaceId }, () => {
-            void this.emitWorkspaceUpdateForCwd(workspaceId);
+        const subscription = await this.workspaceGitService.subscribe({ cwd: normalizedCwd }, (snapshot) => {
+            void this.emitWorkspaceUpdateForCwd(normalizedCwd);
+            this.emitCheckoutStatusUpdate(normalizedCwd, snapshot);
         });
-        this.workspaceGitSubscriptions.set(workspaceId, subscription.unsubscribe);
+        this.workspaceGitSubscriptions.set(normalizedCwd, subscription.unsubscribe);
     }
     async handleSubscribeCheckoutDiffRequest(msg) {
         const cwd = expandTilde(msg.cwd);
@@ -2998,10 +3188,108 @@ export class Session {
         this.checkoutDiffSubscriptions.get(msg.subscriptionId)?.();
         this.checkoutDiffSubscriptions.delete(msg.subscriptionId);
     }
+    buildCheckoutStatusPayloadFromSnapshot({ cwd, requestId, snapshot, }) {
+        if (!snapshot.git.isGit) {
+            return {
+                cwd,
+                isGit: false,
+                repoRoot: null,
+                currentBranch: null,
+                isDirty: null,
+                baseRef: null,
+                aheadBehind: null,
+                aheadOfOrigin: null,
+                behindOfOrigin: null,
+                hasRemote: false,
+                remoteUrl: null,
+                isPaseoOwnedWorktree: false,
+                error: null,
+                requestId,
+            };
+        }
+        if (snapshot.git.repoRoot === null || snapshot.git.isDirty === null) {
+            throw new Error("Workspace git snapshot is missing required checkout status fields");
+        }
+        if (snapshot.git.isPaseoOwnedWorktree) {
+            if (snapshot.git.mainRepoRoot === null || snapshot.git.baseRef === null) {
+                throw new Error("Workspace git snapshot is missing required worktree status fields");
+            }
+            return {
+                cwd,
+                isGit: true,
+                repoRoot: snapshot.git.repoRoot,
+                mainRepoRoot: snapshot.git.mainRepoRoot,
+                currentBranch: snapshot.git.currentBranch ?? null,
+                isDirty: snapshot.git.isDirty,
+                baseRef: snapshot.git.baseRef,
+                aheadBehind: snapshot.git.aheadBehind ?? null,
+                aheadOfOrigin: snapshot.git.aheadOfOrigin ?? null,
+                behindOfOrigin: snapshot.git.behindOfOrigin ?? null,
+                hasRemote: snapshot.git.hasRemote,
+                remoteUrl: snapshot.git.remoteUrl,
+                isPaseoOwnedWorktree: true,
+                error: null,
+                requestId,
+            };
+        }
+        return {
+            cwd,
+            isGit: true,
+            repoRoot: snapshot.git.repoRoot,
+            currentBranch: snapshot.git.currentBranch ?? null,
+            isDirty: snapshot.git.isDirty,
+            baseRef: snapshot.git.baseRef ?? null,
+            aheadBehind: snapshot.git.aheadBehind ?? null,
+            aheadOfOrigin: snapshot.git.aheadOfOrigin ?? null,
+            behindOfOrigin: snapshot.git.behindOfOrigin ?? null,
+            hasRemote: snapshot.git.hasRemote,
+            remoteUrl: snapshot.git.remoteUrl,
+            isPaseoOwnedWorktree: false,
+            error: null,
+            requestId,
+        };
+    }
+    buildCheckoutPrStatusPayloadFromSnapshot({ cwd, requestId, snapshot, }) {
+        return {
+            cwd,
+            status: normalizeCheckoutPrStatusPayload(snapshot.github.pullRequest),
+            githubFeaturesEnabled: snapshot.github.featuresEnabled,
+            error: snapshot.github.error
+                ? {
+                    code: "UNKNOWN",
+                    message: snapshot.github.error.message,
+                }
+                : null,
+            requestId,
+        };
+    }
+    emitCheckoutStatusUpdate(cwd, snapshot) {
+        try {
+            const requestId = `subscription:${cwd}`;
+            this.emit({
+                type: "checkout_status_update",
+                payload: {
+                    ...this.buildCheckoutStatusPayloadFromSnapshot({
+                        cwd,
+                        requestId,
+                        snapshot,
+                    }),
+                    prStatus: this.buildCheckoutPrStatusPayloadFromSnapshot({
+                        cwd,
+                        requestId,
+                        snapshot,
+                    }),
+                },
+            });
+        }
+        catch (error) {
+            this.sessionLogger.warn({ err: error, cwd }, "Failed to emit workspace checkout status update");
+        }
+    }
     async handleCheckoutSwitchBranchRequest(msg) {
         const { cwd, branch, requestId } = msg;
         try {
-            await this.checkoutExistingBranch(cwd, branch);
+            const checkoutResult = await this.checkoutExistingBranch(cwd, branch);
             this.checkoutDiffManager.scheduleRefreshForCwd(cwd);
             // Push a workspace_update immediately so the sidebar/header reflect
             // the new branch name without waiting for the background git watcher.
@@ -3012,6 +3300,7 @@ export class Session {
                     cwd,
                     success: true,
                     branch,
+                    source: checkoutResult.source,
                     error: null,
                     requestId,
                 },
@@ -3038,6 +3327,7 @@ export class Session {
                 ? `${Session.PASEO_STASH_PREFIX} ${branchLabel}`
                 : `${Session.PASEO_STASH_PREFIX} unnamed`;
             await execCommand("git", ["stash", "push", "--include-untracked", "-m", message], { cwd });
+            await this.notifyGitMutation(cwd, "stash-push");
             this.checkoutDiffManager.scheduleRefreshForCwd(cwd);
             this.emit({
                 type: "stash_save_response",
@@ -3055,6 +3345,7 @@ export class Session {
         const { cwd, stashIndex, requestId } = msg;
         try {
             await execCommand("git", ["stash", "pop", `stash@{${stashIndex}}`], { cwd });
+            await this.notifyGitMutation(cwd, "stash-pop");
             this.checkoutDiffManager.scheduleRefreshForCwd(cwd);
             this.emit({
                 type: "stash_pop_response",
@@ -3072,31 +3363,7 @@ export class Session {
         const { cwd, requestId } = msg;
         const paseoOnly = msg.paseoOnly !== false;
         try {
-            const { stdout } = await execAsync("git stash list --format=%gd%x00%s", {
-                cwd,
-                env: READ_ONLY_GIT_ENV,
-            });
-            const lines = stdout.trim().split("\n").filter(Boolean);
-            const entries = [];
-            for (const line of lines) {
-                const sepIdx = line.indexOf("\0");
-                if (sepIdx < 0)
-                    continue;
-                const refPart = line.slice(0, sepIdx);
-                const subject = line.slice(sepIdx + 1);
-                const indexMatch = refPart.match(/\{(\d+)\}/);
-                if (!indexMatch)
-                    continue;
-                const index = Number(indexMatch[1]);
-                const prefixIdx = subject.indexOf(Session.PASEO_STASH_PREFIX);
-                const isPaseo = prefixIdx >= 0;
-                const branch = isPaseo
-                    ? subject.slice(prefixIdx + Session.PASEO_STASH_PREFIX.length).trim() || null
-                    : null;
-                if (paseoOnly && !isPaseo)
-                    continue;
-                entries.push({ index, message: subject, branch, isPaseo });
-            }
+            const entries = await this.workspaceGitService.listStashes(cwd, { paseoOnly });
             this.emit({
                 type: "stash_list_response",
                 payload: { cwd, entries, error: null, requestId },
@@ -3123,6 +3390,7 @@ export class Session {
                 message,
                 addAll: msg.addAll ?? true,
             });
+            await this.notifyGitMutation(cwd, "commit-changes");
             this.checkoutDiffManager.scheduleRefreshForCwd(cwd);
             this.emit({
                 type: "checkout_commit_response",
@@ -3149,43 +3417,30 @@ export class Session {
     async handleCheckoutMergeRequest(msg) {
         const { cwd, requestId } = msg;
         try {
-            const status = await getCheckoutStatus(cwd, { paseoHome: this.paseoHome });
-            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());
-                }
+            const snapshot = await this.workspaceGitService.getSnapshot(cwd);
+            if (!snapshot.git.isGit) {
+                throw new Error(`Not a git repository: ${cwd}`);
             }
             if (msg.requireCleanTarget) {
-                const { stdout } = await execAsync("git status --porcelain", {
-                    cwd,
-                    env: READ_ONLY_GIT_ENV,
-                });
-                if (stdout.trim().length > 0) {
+                if (snapshot.git.isDirty) {
                     throw new Error("Working directory has uncommitted changes.");
                 }
             }
-            let baseRef = msg.baseRef ?? (status.isGit ? status.baseRef : null);
+            let baseRef = msg.baseRef ?? snapshot.git.baseRef;
             if (!baseRef) {
                 throw new Error("Base branch is required for merge");
             }
             if (baseRef.startsWith("origin/")) {
                 baseRef = baseRef.slice("origin/".length);
             }
-            await mergeToBase(cwd, {
+            const mutatedCwd = await mergeToBase(cwd, {
                 baseRef,
                 mode: msg.strategy === "squash" ? "squash" : "merge",
             }, { paseoHome: this.paseoHome });
+            await Promise.all([
+                this.notifyGitMutation(mutatedCwd, "merge-to-base", { invalidateGithub: true }),
+                ...(mutatedCwd !== cwd ? [this.notifyGitMutation(cwd, "merge-to-base")] : []),
+            ]);
             this.checkoutDiffManager.scheduleRefreshForCwd(cwd);
             this.emit({
                 type: "checkout_merge_response",
@@ -3213,11 +3468,8 @@ export class Session {
         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) {
+                const snapshot = await this.workspaceGitService.getSnapshot(cwd);
+                if (snapshot.git.isDirty) {
                     throw new Error("Working directory has uncommitted changes.");
                 }
             }
@@ -3225,6 +3477,7 @@ export class Session {
                 baseRef: msg.baseRef,
                 requireCleanTarget: msg.requireCleanTarget ?? true,
             });
+            await this.notifyGitMutation(cwd, "merge-from-base", { invalidateGithub: true });
             this.checkoutDiffManager.scheduleRefreshForCwd(cwd);
             this.emit({
                 type: "checkout_merge_from_base_response",
@@ -3252,6 +3505,7 @@ export class Session {
         const { cwd, requestId } = msg;
         try {
             await pullCurrentBranch(cwd);
+            await this.notifyGitMutation(cwd, "pull", { invalidateGithub: true });
             this.checkoutDiffManager.scheduleRefreshForCwd(cwd);
             this.emit({
                 type: "checkout_pull_response",
@@ -3279,6 +3533,7 @@ export class Session {
         const { cwd, requestId } = msg;
         try {
             await pushCurrentBranch(cwd);
+            await this.notifyGitMutation(cwd, "push", { invalidateGithub: true });
             this.emit({
                 type: "checkout_push_response",
                 payload: {
@@ -3317,7 +3572,8 @@ export class Session {
                 title,
                 body,
                 base: msg.baseRef,
-            });
+            }, this.github, this.workspaceGitService);
+            await this.notifyGitMutation(cwd, "create-pr", { invalidateGithub: true });
             this.emit({
                 type: "checkout_pr_create_response",
                 payload: {
@@ -3350,7 +3606,7 @@ export class Session {
                 type: "checkout_pr_status_response",
                 payload: {
                     cwd,
-                    status: snapshot.github.pullRequest,
+                    status: normalizeCheckoutPrStatusPayload(snapshot.github.pullRequest),
                     githubFeaturesEnabled: snapshot.github.featuresEnabled,
                     error: snapshot.github.error
                         ? {
@@ -3375,22 +3631,108 @@ export class Session {
             });
         }
     }
+    async handlePullRequestTimelineRequest(msg) {
+        const { cwd, prNumber, repoOwner, repoName, requestId } = msg;
+        if (!isValidPullRequestTimelineIdentity({ prNumber, repoOwner, repoName })) {
+            this.emit({
+                type: "pull_request_timeline_response",
+                payload: {
+                    cwd,
+                    prNumber,
+                    items: [],
+                    truncated: false,
+                    error: {
+                        kind: "unknown",
+                        message: "Pull request timeline request has invalid PR identity",
+                    },
+                    requestId,
+                    githubFeaturesEnabled: true,
+                },
+            });
+            return;
+        }
+        const githubFeaturesEnabled = await this.github.isAuthenticated({ cwd });
+        if (!githubFeaturesEnabled) {
+            this.emit({
+                type: "pull_request_timeline_response",
+                payload: {
+                    cwd,
+                    prNumber,
+                    items: [],
+                    truncated: false,
+                    error: {
+                        kind: "unknown",
+                        message: "GitHub CLI is unavailable or not authenticated",
+                    },
+                    requestId,
+                    githubFeaturesEnabled: false,
+                },
+            });
+            return;
+        }
+        try {
+            const timeline = await this.github.getPullRequestTimeline({
+                cwd,
+                prNumber,
+                repoOwner,
+                repoName,
+            });
+            this.emit({
+                type: "pull_request_timeline_response",
+                payload: {
+                    cwd,
+                    prNumber: timeline.prNumber,
+                    items: timeline.items.map(toPullRequestTimelinePayloadItem),
+                    truncated: timeline.truncated,
+                    error: timeline.error,
+                    requestId,
+                    githubFeaturesEnabled: true,
+                },
+            });
+        }
+        catch (error) {
+            this.emit({
+                type: "pull_request_timeline_response",
+                payload: {
+                    cwd,
+                    prNumber,
+                    items: [],
+                    truncated: false,
+                    error: {
+                        kind: "unknown",
+                        message: error instanceof Error ? error.message : String(error),
+                    },
+                    requestId,
+                    githubFeaturesEnabled: true,
+                },
+            });
+        }
+    }
     async handlePaseoWorktreeListRequest(msg) {
         return handleWorktreeListRequest({
             emit: (message) => this.emit(message),
             paseoHome: this.paseoHome,
+            workspaceGitService: this.workspaceGitService,
         }, msg);
     }
     async handlePaseoWorktreeArchiveRequest(msg) {
         return handleWorktreeArchiveRequest({
             paseoHome: this.paseoHome,
+            github: this.github,
+            workspaceGitService: this.workspaceGitService,
             agentManager: this.agentManager,
             agentStorage: this.agentStorage,
-            archiveWorkspaceRecord: (workspaceId) => this.archiveWorkspaceRecord(workspaceId),
+            archiveWorkspaceRecord: async (workspaceDirectory) => {
+                const workspace = await this.findWorkspaceByDirectory(workspaceDirectory);
+                if (workspace) {
+                    await this.archiveWorkspaceRecord(workspace.workspaceId);
+                }
+            },
             emit: (message) => this.emit(message),
             emitWorkspaceUpdatesForCwds: (cwds) => this.emitWorkspaceUpdatesForCwds(cwds),
             isPathWithinRoot: (rootPath, candidatePath) => this.isPathWithinRoot(rootPath, candidatePath),
             killTerminalsUnderPath: (rootPath) => this.killTerminalsUnderPath(rootPath),
+            sessionLogger: this.sessionLogger,
         }, msg);
     }
     /**
@@ -3578,6 +3920,7 @@ export class Session {
             .filter((record) => !liveIds.has(record.id) && !record.internal)
             .map((record) => this.buildStoredAgentPayload(record));
         let agents = [...liveAgents, ...persistedAgents];
+        agents = agents.filter((agent) => this.isProviderVisibleToClient(agent.provider));
         // Filter by labels if filter provided
         if (filter?.labels) {
             const filterLabels = filter.labels;
@@ -3633,13 +3976,15 @@ export class Session {
     async getAgentPayloadById(agentId) {
         const live = this.agentManager.getAgent(agentId);
         if (live) {
-            return await this.buildAgentPayload(live);
+            const payload = await this.buildAgentPayload(live);
+            return this.isProviderVisibleToClient(payload.provider) ? payload : null;
         }
         const record = await this.agentStorage.get(agentId);
         if (!record || record.internal) {
             return null;
         }
-        return this.buildStoredAgentPayload(record);
+        const payload = this.buildStoredAgentPayload(record);
+        return this.isProviderVisibleToClient(payload.provider) ? payload : null;
     }
     normalizeFetchAgentsSort(sort) {
         const fallback = [{ key: "updated_at", direction: "desc" }];
@@ -3795,19 +4140,51 @@ export class Session {
         }
         return agent.id.localeCompare(cursor.id);
     }
+    async buildActiveProjectPlacementsByWorkspaceCwd() {
+        const [persistedWorkspaces, persistedProjects] = await Promise.all([
+            this.workspaceRegistry.list(),
+            this.projectRegistry.list(),
+        ]);
+        const activeProjects = new Map(persistedProjects
+            .filter((project) => !project.archivedAt)
+            .map((project) => [project.projectId, project]));
+        const placementsByCwd = new Map();
+        for (const workspace of persistedWorkspaces) {
+            if (workspace.archivedAt) {
+                continue;
+            }
+            const project = activeProjects.get(workspace.projectId);
+            if (!project) {
+                continue;
+            }
+            placementsByCwd.set(normalizePersistedWorkspaceId(workspace.cwd), await this.buildProjectPlacementForWorkspace(workspace, project));
+        }
+        return placementsByCwd;
+    }
     async listFetchAgentsEntries(request) {
-        const filter = request.filter;
+        const filter = request.type === "fetch_agent_history_request" &&
+            request.filter?.includeArchived === undefined
+            ? { ...request.filter, includeArchived: true }
+            : request.filter;
+        const scope = request.type === "fetch_agents_request" ? request.scope : undefined;
         const sort = this.normalizeFetchAgentsSort(request.sort);
-        const agents = await this.listAgentPayloads({
+        let agents = await this.listAgentPayloads({
             labels: filter?.labels,
         });
+        const activePlacementsByCwd = scope === "active" ? await this.buildActiveProjectPlacementsByWorkspaceCwd() : null;
+        if (activePlacementsByCwd) {
+            agents = agents.filter((agent) => !agent.archivedAt && activePlacementsByCwd.has(normalizePersistedWorkspaceId(agent.cwd)));
+        }
         const placementByCwd = new Map();
         const getPlacement = (cwd) => {
+            if (activePlacementsByCwd) {
+                return Promise.resolve(activePlacementsByCwd.get(normalizePersistedWorkspaceId(cwd)) ?? null);
+            }
             const existing = placementByCwd.get(cwd);
             if (existing) {
                 return existing;
             }
-            const placementPromise = this.buildProjectPlacement(cwd);
+            const placementPromise = this.buildProjectPlacementForCwd(cwd);
             placementByCwd.set(cwd, placementPromise);
             return placementPromise;
         };
@@ -3823,11 +4200,14 @@ export class Session {
         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),
-            })));
+            const batchEntries = await Promise.all(batch.map(async (agent) => {
+                const project = await getPlacement(agent.cwd);
+                return project ? { agent, project } : null;
+            }));
             for (const entry of batchEntries) {
+                if (!entry) {
+                    continue;
+                }
                 if (!this.matchesAgentFilter({
                     agent: entry.agent,
                     project: entry.project,
@@ -3873,17 +4253,34 @@ export class Session {
     }
     async describeWorkspaceRecord(workspace, projectRecord) {
         const resolvedProjectRecord = projectRecord ?? (await this.projectRegistry.get(workspace.projectId));
+        let diffStat = null;
+        const snapshot = this.workspaceGitService.peekSnapshot(workspace.cwd);
+        if (snapshot?.git.diffStat) {
+            diffStat = snapshot.git.diffStat;
+        }
         return {
             id: workspace.workspaceId,
             projectId: workspace.projectId,
-            projectDisplayName: resolvedProjectRecord?.displayName ?? workspace.projectId,
+            projectDisplayName: resolvedProjectRecord?.displayName ?? String(workspace.projectId),
             projectRootPath: resolvedProjectRecord?.rootPath ?? workspace.cwd,
-            projectKind: resolvedProjectRecord?.kind ?? "non_git",
+            workspaceDirectory: workspace.cwd,
+            projectKind: (resolvedProjectRecord?.kind ?? "directory") === "git" ? "git" : "non_git",
             workspaceKind: workspace.kind,
             name: workspace.displayName,
             status: "done",
             activityAt: null,
-            diffStat: null,
+            diffStat,
+            scripts: this.scriptRouteStore && this.scriptRuntimeStore
+                ? buildWorkspaceScriptPayloads({
+                    workspaceId: workspace.workspaceId,
+                    workspaceDirectory: workspace.cwd,
+                    routeStore: this.scriptRouteStore,
+                    runtimeStore: this.scriptRuntimeStore,
+                    daemonPort: this.getDaemonTcpPort?.() ?? null,
+                    gitMetadata: this.resolveWorkspaceScriptGitMetadata(workspace.cwd),
+                    resolveHealth: this.resolveScriptHealth ?? undefined,
+                })
+                : [],
         };
     }
     buildWorkspaceGitRuntimePayload(snapshot) {
@@ -3905,17 +4302,12 @@ export class Session {
             featuresEnabled: snapshot.github.featuresEnabled,
             pullRequest: snapshot.github.pullRequest,
             error: snapshot.github.error,
-            refreshedAt: snapshot.github.refreshedAt,
         };
     }
     async describeWorkspaceRecordWithGitData(workspace, projectRecord) {
         const base = await this.describeWorkspaceRecord(workspace, projectRecord);
-        let snapshot;
-        try {
-            snapshot = await this.workspaceGitService.getSnapshot(workspace.cwd);
-        }
-        catch (error) {
-            this.sessionLogger.warn({ err: error, cwd: workspace.cwd }, "Failed to load git snapshot for workspace");
+        const snapshot = this.workspaceGitService.peekSnapshot(workspace.cwd);
+        if (!snapshot) {
             return base;
         }
         const checkout = checkoutLiteFromGitSnapshot(workspace.cwd, snapshot.git);
@@ -3924,10 +4316,37 @@ export class Session {
             ...base,
             name: displayName,
             diffStat: snapshot.git.diffStat ?? null,
-            gitRuntime: this.buildWorkspaceGitRuntimePayload(snapshot),
+            gitRuntime: this.buildWorkspaceGitRuntimePayload(snapshot) ?? undefined,
             githubRuntime: this.buildWorkspaceGitHubRuntimePayload(snapshot),
         };
     }
+    async describeCreatedWorktreeWorkspace(result) {
+        const projectRecord = await this.projectRegistry.get(result.workspace.projectId);
+        return {
+            id: result.workspace.workspaceId,
+            projectId: result.workspace.projectId,
+            projectDisplayName: projectRecord?.displayName ?? String(result.workspace.projectId),
+            projectRootPath: projectRecord?.rootPath ?? result.repoRoot,
+            workspaceDirectory: result.workspace.cwd,
+            projectKind: "git",
+            workspaceKind: result.workspace.kind,
+            name: result.worktree.branchName || result.workspace.displayName,
+            status: "done",
+            activityAt: null,
+            diffStat: { additions: 0, deletions: 0 },
+            scripts: [],
+            gitRuntime: {
+                currentBranch: result.worktree.branchName || null,
+                remoteUrl: null,
+                isPaseoOwnedWorktree: true,
+                isDirty: false,
+                aheadBehind: null,
+                aheadOfOrigin: null,
+                behindOfOrigin: null,
+            },
+            githubRuntime: null,
+        };
+    }
     async buildWorkspaceDescriptor(input) {
         if (input.includeGitData && input.projectRecord?.kind === "git") {
             return this.describeWorkspaceRecordWithGitData(input.workspace, input.projectRecord);
@@ -3940,14 +4359,14 @@ export class Session {
             this.workspaceRegistry.list(),
             this.projectRegistry.list(),
         ]);
-        const activeRecords = persistedWorkspaces.filter((workspace) => !workspace.archivedAt);
         const activeProjects = new Map(persistedProjects
             .filter((project) => !project.archivedAt)
             .map((project) => [project.projectId, project]));
+        const archivedProjectIds = new Set(persistedProjects.filter((project) => project.archivedAt).map((project) => project.projectId));
+        const activeRecords = persistedWorkspaces.filter((workspace) => !workspace.archivedAt && !archivedProjectIds.has(workspace.projectId));
         const descriptorsByWorkspaceId = new Map();
-        const workspaceIds = options.workspaceIds
-            ? new Set(Array.from(options.workspaceIds, (workspaceId) => normalizePersistedWorkspaceId(workspaceId)))
-            : null;
+        const workspaceIds = options.workspaceIds ? new Set(options.workspaceIds) : null;
+        const workspaceIdsByDirectory = new Map(activeRecords.map((workspace) => [normalizePersistedWorkspaceId(workspace.cwd), workspace.workspaceId]));
         for (const workspace of activeRecords) {
             if (workspaceIds && !workspaceIds.has(workspace.workspaceId)) {
                 continue;
@@ -3963,7 +4382,13 @@ export class Session {
             if (agent.archivedAt) {
                 continue;
             }
-            const workspaceId = this.resolveRegisteredWorkspaceIdForCwd(agent.cwd, activeRecords);
+            if (!this.isProviderVisibleToClient(agent.provider)) {
+                continue;
+            }
+            const workspaceId = workspaceIdsByDirectory.get(normalizePersistedWorkspaceId(agent.cwd));
+            if (workspaceId === undefined) {
+                continue;
+            }
             const existing = descriptorsByWorkspaceId.get(workspaceId);
             if (!existing) {
                 continue;
@@ -3977,19 +4402,17 @@ export class Session {
     }
     resolveRegisteredWorkspaceIdForCwd(cwd, workspaces) {
         const normalizedCwd = normalizePersistedWorkspaceId(cwd);
-        const exact = workspaces.find((workspace) => workspace.workspaceId === normalizedCwd);
+        const exact = workspaces.find((workspace) => workspace.cwd === normalizedCwd);
         if (exact) {
             return exact.workspaceId;
         }
         let bestMatch = null;
         for (const workspace of workspaces) {
-            const prefix = workspace.workspaceId.endsWith(sep)
-                ? workspace.workspaceId
-                : `${workspace.workspaceId}${sep}`;
+            const prefix = workspace.cwd.endsWith(sep) ? workspace.cwd : `${workspace.cwd}${sep}`;
             if (!normalizedCwd.startsWith(prefix)) {
                 continue;
             }
-            if (!bestMatch || workspace.workspaceId.length > bestMatch.workspaceId.length) {
+            if (!bestMatch || workspace.cwd.length > bestMatch.cwd.length) {
                 bestMatch = workspace;
             }
         }
@@ -4095,7 +4518,7 @@ export class Session {
         return {
             sort: cursorSort,
             values: payload.values,
-            id: payload.id,
+            id: String(payload.id),
         };
     }
     compareWorkspaceWithCursor(workspace, cursor, sort) {
@@ -4121,13 +4544,13 @@ export class Session {
             }
         }
         if (filter.idPrefix && filter.idPrefix.trim().length > 0) {
-            if (!workspace.id.startsWith(filter.idPrefix.trim())) {
+            if (!String(workspace.id).startsWith(filter.idPrefix.trim())) {
                 return false;
             }
         }
         if (filter.query && filter.query.trim().length > 0) {
             const query = filter.query.trim().toLocaleLowerCase();
-            const haystacks = [workspace.name, workspace.projectId, workspace.id];
+            const haystacks = [workspace.name, String(workspace.projectId), String(workspace.id)];
             if (!haystacks.some((value) => value.toLocaleLowerCase().includes(query))) {
                 return false;
             }
@@ -4213,32 +4636,95 @@ export class Session {
             });
         }
     }
-    async ensureWorkspaceRegistered(cwd) {
-        return (await this.reconcileWorkspaceRecord(cwd)).workspace;
-    }
-    async registerPendingWorktreeWorkspace(options) {
-        return registerPendingWorktreeWorkspaceSession({
-            buildPersistedProjectRecord: (input) => this.buildPersistedProjectRecord(input),
-            buildPersistedWorkspaceRecord: (input) => this.buildPersistedWorkspaceRecord(input),
-            buildProjectPlacement: (cwd) => this.buildProjectPlacement(cwd),
+    async findOrCreateWorkspaceForDirectory(cwd) {
+        const normalizedCwd = await this.resolveWorkspaceDirectory(cwd);
+        const existingWorkspace = await this.findWorkspaceByDirectory(normalizedCwd);
+        if (existingWorkspace) {
+            return this.ensureWorkspaceRecordUnarchived(existingWorkspace);
+        }
+        const placement = await buildProjectPlacementForCwdStandalone({
+            cwd: normalizedCwd,
+            workspaceGitService: this.workspaceGitService,
+        });
+        const workspaceId = deriveWorkspaceId(normalizedCwd, placement.checkout);
+        const timestamp = new Date().toISOString();
+        const projectRecord = createPersistedProjectRecord({
+            projectId: placement.projectKey,
+            rootPath: deriveProjectRootPath({ cwd: normalizedCwd, checkout: placement.checkout }),
+            kind: deriveProjectKind(placement.checkout),
+            displayName: placement.projectName,
+            createdAt: timestamp,
+            updatedAt: timestamp,
+        });
+        await this.projectRegistry.upsert(projectRecord);
+        const workspaceRecord = createPersistedWorkspaceRecord({
+            workspaceId,
+            projectId: placement.projectKey,
+            cwd: normalizedCwd,
+            kind: deriveWorkspaceKind(placement.checkout),
+            displayName: deriveWorkspaceDisplayName({
+                cwd: normalizedCwd,
+                checkout: placement.checkout,
+            }),
+            createdAt: timestamp,
+            updatedAt: timestamp,
+        });
+        await this.workspaceRegistry.upsert(workspaceRecord);
+        return workspaceRecord;
+    }
+    async ensureWorkspaceRecordUnarchived(workspace) {
+        const project = await this.projectRegistry.get(workspace.projectId);
+        if (!workspace.archivedAt && (!project || !project.archivedAt)) {
+            return workspace;
+        }
+        const timestamp = new Date().toISOString();
+        let unarchivedWorkspace = workspace;
+        if (workspace.archivedAt) {
+            unarchivedWorkspace = { ...workspace, archivedAt: null, updatedAt: timestamp };
+            await this.workspaceRegistry.upsert(unarchivedWorkspace);
+        }
+        if (project?.archivedAt) {
+            await this.projectRegistry.upsert({
+                ...project,
+                archivedAt: null,
+                updatedAt: timestamp,
+            });
+        }
+        return unarchivedWorkspace;
+    }
+    async createPaseoWorktree(input, options) {
+        const coreDeps = createWorktreeCoreDeps(this.github);
+        const result = await createPaseoWorktree(input, {
+            ...coreDeps,
+            ...(options?.resolveDefaultBranch
+                ? { resolveDefaultBranch: options.resolveDefaultBranch }
+                : {}),
             projectRegistry: this.projectRegistry,
             workspaceRegistry: this.workspaceRegistry,
-            archiveProjectRecordIfEmpty: (projectId, archivedAt) => this.archiveProjectRecordIfEmpty(projectId, archivedAt),
-        }, options);
+            workspaceGitService: this.workspaceGitService,
+        });
+        void Promise.all([
+            this.notifyGitMutation(input.cwd, "create-worktree"),
+            this.notifyGitMutation(result.worktree.worktreePath, "create-worktree"),
+        ]).catch((error) => {
+            this.sessionLogger.warn({ err: error, cwd: input.cwd, worktreePath: result.worktree.worktreePath }, "Failed to warm git snapshots after creating worktree");
+        });
+        return result;
     }
     async archiveWorkspaceRecord(workspaceId, archivedAt) {
-        const existing = await this.workspaceRegistry.get(workspaceId);
-        if (!existing || existing.archivedAt) {
+        const existingWorkspace = await archivePersistedWorkspaceRecord({
+            workspaceId,
+            archivedAt,
+            workspaceRegistry: this.workspaceRegistry,
+            projectRegistry: this.projectRegistry,
+        });
+        if (!existingWorkspace) {
             this.removeWorkspaceGitSubscription(workspaceId);
             return;
         }
-        const nextArchivedAt = archivedAt ?? new Date().toISOString();
-        await this.workspaceRegistry.archive(workspaceId, nextArchivedAt);
+        await this.removeWorkspaceGitWatchTarget(existingWorkspace.cwd);
+        this.scriptRuntimeStore?.removeForWorkspace(existingWorkspace.cwd);
         this.removeWorkspaceGitSubscription(workspaceId);
-        const siblingWorkspaces = (await this.workspaceRegistry.list()).filter((workspace) => workspace.projectId === existing.projectId && !workspace.archivedAt);
-        if (siblingWorkspaces.length === 0) {
-            await this.projectRegistry.archive(existing.projectId, nextArchivedAt);
-        }
     }
     async reconcileAndEmitWorkspaceUpdates() {
         if (!this.workspaceUpdatesSubscription) {
@@ -4257,12 +4743,48 @@ export class Session {
             this.sessionLogger.error({ err: error }, "Background workspace reconciliation failed");
         }
     }
+    async reconcileActiveWorkspaceRecords() {
+        const service = new WorkspaceReconciliationService({
+            projectRegistry: this.projectRegistry,
+            workspaceRegistry: this.workspaceRegistry,
+            logger: this.sessionLogger,
+            workspaceGitService: this.workspaceGitService,
+        });
+        const result = await service.runOnce();
+        const changedWorkspaceIds = new Set();
+        const changedProjectIds = new Set();
+        for (const change of result.changesApplied) {
+            switch (change.kind) {
+                case "workspace_archived":
+                    await this.removeWorkspaceGitWatchTarget(change.directory);
+                    this.scriptRuntimeStore?.removeForWorkspace(change.directory);
+                    this.removeWorkspaceGitSubscription(change.workspaceId);
+                    changedWorkspaceIds.add(change.workspaceId);
+                    break;
+                case "workspace_updated":
+                    changedWorkspaceIds.add(change.workspaceId);
+                    break;
+                case "project_archived":
+                case "project_updated":
+                    changedProjectIds.add(change.projectId);
+                    break;
+            }
+        }
+        if (changedProjectIds.size > 0) {
+            for (const workspace of await this.workspaceRegistry.list()) {
+                if (changedProjectIds.has(workspace.projectId)) {
+                    changedWorkspaceIds.add(workspace.workspaceId);
+                }
+            }
+        }
+        return changedWorkspaceIds;
+    }
     async emitWorkspaceUpdatesForWorkspaceIds(workspaceIds, options) {
         const subscription = this.workspaceUpdatesSubscription;
         if (!subscription) {
             return;
         }
-        const uniqueWorkspaceIds = new Set(Array.from(workspaceIds, (workspaceId) => normalizePersistedWorkspaceId(workspaceId)));
+        const uniqueWorkspaceIds = new Set(Array.from(workspaceIds));
         if (uniqueWorkspaceIds.size === 0) {
             return;
         }
@@ -4275,6 +4797,18 @@ export class Session {
             const nextWorkspace = workspace && this.matchesWorkspaceFilter({ workspace, filter: subscription.filter })
                 ? workspace
                 : null;
+            if (options?.dedupeGitState &&
+                this.shouldSkipWorkspaceGitWatchUpdate(workspaceId, nextWorkspace)) {
+                continue;
+            }
+            const watchTarget = this.workspaceGitWatchTargets.get(workspaceId);
+            if (watchTarget && this.onBranchChanged) {
+                const newBranchName = nextWorkspace?.name ?? null;
+                if (newBranchName !== watchTarget.lastBranchName) {
+                    this.onBranchChanged(workspaceId, watchTarget.lastBranchName, newBranchName);
+                }
+            }
+            this.rememberWorkspaceGitWatchFingerprint(workspaceId, nextWorkspace);
             if (!nextWorkspace) {
                 subscription.lastEmittedByWorkspaceId.delete(workspaceId);
                 this.bufferOrEmitWorkspaceUpdate(subscription, {
@@ -4300,15 +4834,15 @@ export class Session {
         }
     }
     async emitWorkspaceUpdateForCwd(cwd, options) {
-        const activeWorkspaces = (await this.workspaceRegistry.list()).filter((workspace) => !workspace.archivedAt);
-        const workspaceId = this.resolveRegisteredWorkspaceIdForCwd(cwd, activeWorkspaces);
+        const workspaces = await this.workspaceRegistry.list();
+        const workspaceId = this.resolveRegisteredWorkspaceIdForCwd(cwd, workspaces);
         await this.emitWorkspaceUpdatesForWorkspaceIds([workspaceId], options);
     }
     async emitWorkspaceUpdatesForCwds(cwds) {
-        const activeWorkspaces = (await this.workspaceRegistry.list()).filter((workspace) => !workspace.archivedAt);
+        const workspaces = await this.workspaceRegistry.list();
         const uniqueWorkspaceIds = new Set();
         for (const cwd of cwds) {
-            uniqueWorkspaceIds.add(this.resolveRegisteredWorkspaceIdForCwd(cwd, activeWorkspaces));
+            uniqueWorkspaceIds.add(this.resolveRegisteredWorkspaceIdForCwd(cwd, workspaces));
         }
         await this.emitWorkspaceUpdatesForWorkspaceIds(uniqueWorkspaceIds);
     }
@@ -4329,8 +4863,6 @@ export class Session {
                 };
             }
             const payload = await this.listFetchAgentsEntries(request);
-            // TODO: Remove once all app store clients are on >=0.1.45.
-            payload.entries = payload.entries.filter((entry) => this.isProviderVisibleToClient(entry.agent.provider));
             const snapshotUpdatedAtByAgentId = new Map();
             for (const entry of payload.entries) {
                 const parsedUpdatedAt = Date.parse(entry.agent.updatedAt);
@@ -4368,6 +4900,32 @@ export class Session {
             });
         }
     }
+    async handleFetchAgentHistory(request) {
+        try {
+            const payload = await this.listFetchAgentsEntries(request);
+            this.emit({
+                type: "fetch_agent_history_response",
+                payload: {
+                    requestId: request.requestId,
+                    ...payload,
+                },
+            });
+        }
+        catch (error) {
+            const code = error instanceof SessionRequestError ? error.code : "fetch_agent_history_failed";
+            const message = error instanceof Error ? error.message : "Failed to fetch agent history";
+            this.sessionLogger.error({ err: error }, "Failed to handle fetch_agent_history_request");
+            this.emit({
+                type: "rpc_error",
+                payload: {
+                    requestId: request.requestId,
+                    requestType: request.type,
+                    error: message,
+                    code,
+                },
+            });
+        }
+    }
     async handleFetchWorkspacesRequest(request) {
         const requestedSubscriptionId = request.subscribe?.subscriptionId?.trim();
         const subscriptionId = request.subscribe
@@ -4393,6 +4951,7 @@ export class Session {
                 };
             }
             const payload = await this.listFetchWorkspacesEntries(request);
+            await this.primeWorkspaceGitWatchFingerprints(payload.entries);
             this.sessionLogger.debug({
                 requestId: request.requestId,
                 subscriptionId,
@@ -4441,10 +5000,8 @@ export class Session {
     }
     async handleOpenProjectRequest(request) {
         try {
-            const workspace = await this.ensureWorkspaceRegistered(request.cwd);
-            await this.emitWorkspaceUpdateForCwd(workspace.cwd, {
-                skipReconcile: true,
-            });
+            const workspace = await this.findOrCreateWorkspaceForDirectory(request.cwd);
+            await this.emitWorkspaceUpdateForCwd(workspace.cwd);
             const descriptor = await this.describeWorkspaceRecordWithGitData(workspace);
             this.emit({
                 type: "open_project_response",
@@ -4468,12 +5025,105 @@ export class Session {
             });
         }
     }
+    buildWorkspaceScriptPayloadSnapshot(workspaceId, workspaceDirectory) {
+        if (!this.scriptRouteStore || !this.scriptRuntimeStore) {
+            return [];
+        }
+        return buildWorkspaceScriptPayloads({
+            workspaceId,
+            workspaceDirectory,
+            routeStore: this.scriptRouteStore,
+            runtimeStore: this.scriptRuntimeStore,
+            daemonPort: this.getDaemonTcpPort?.() ?? null,
+            gitMetadata: this.resolveWorkspaceScriptGitMetadata(workspaceDirectory),
+            resolveHealth: this.resolveScriptHealth ?? undefined,
+        });
+    }
+    resolveWorkspaceScriptGitMetadata(workspaceDirectory) {
+        const snapshot = this.workspaceGitService.peekSnapshot(workspaceDirectory);
+        if (!snapshot) {
+            return undefined;
+        }
+        return {
+            projectSlug: deriveProjectSlug(workspaceDirectory, snapshot.git.isGit ? snapshot.git.remoteUrl : null),
+            currentBranch: snapshot.git.currentBranch,
+        };
+    }
+    emitWorkspaceScriptStatusUpdate(workspaceId, workspaceDirectory) {
+        this.emit({
+            type: "script_status_update",
+            payload: {
+                workspaceId,
+                scripts: this.buildWorkspaceScriptPayloadSnapshot(workspaceId, workspaceDirectory),
+            },
+        });
+    }
+    async resolveAvailableEditorTargets() {
+        return listAvailableEditorTargets();
+    }
     async getAvailableEditorTargets() {
-        return this.filterEditorsForClient(await listAvailableEditorTargets());
+        return this.filterEditorsForClient(await this.getMemoizedAvailableEditorTargets());
     }
     async openEditorTarget(options) {
         await openInEditorTarget(options);
     }
+    async handleStartWorkspaceScriptRequest(request) {
+        try {
+            if (!this.terminalManager || !this.scriptRouteStore || !this.scriptRuntimeStore) {
+                throw new Error("Workspace scripts are not available on this daemon");
+            }
+            const workspace = await this.workspaceRegistry.get(request.workspaceId);
+            if (!workspace) {
+                throw new Error(`Workspace not found: ${request.workspaceId}`);
+            }
+            const gitMetadata = await this.workspaceGitService.getWorkspaceGitMetadata(workspace.cwd);
+            const serviceResult = await spawnWorkspaceScript({
+                repoRoot: workspace.cwd,
+                workspaceId: workspace.workspaceId,
+                projectSlug: gitMetadata.projectSlug,
+                branchName: gitMetadata.currentBranch,
+                scriptName: request.scriptName,
+                daemonPort: this.getDaemonTcpPort?.() ?? null,
+                daemonListenHost: this.getDaemonTcpHost?.() ?? null,
+                routeStore: this.scriptRouteStore,
+                runtimeStore: this.scriptRuntimeStore,
+                terminalManager: this.terminalManager,
+                logger: this.sessionLogger,
+                onLifecycleChanged: () => {
+                    this.emitWorkspaceScriptStatusUpdate(workspace.workspaceId, workspace.cwd);
+                },
+            });
+            this.emitWorkspaceScriptStatusUpdate(workspace.workspaceId, workspace.cwd);
+            this.emit({
+                type: "start_workspace_script_response",
+                payload: {
+                    requestId: request.requestId,
+                    workspaceId: request.workspaceId,
+                    scriptName: request.scriptName,
+                    terminalId: serviceResult.terminalId,
+                    error: null,
+                },
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Failed to start workspace script";
+            this.sessionLogger.error({
+                err: error,
+                workspaceId: request.workspaceId,
+                scriptName: request.scriptName,
+            }, "Failed to start workspace script");
+            this.emit({
+                type: "start_workspace_script_response",
+                payload: {
+                    requestId: request.requestId,
+                    workspaceId: request.workspaceId,
+                    scriptName: request.scriptName,
+                    terminalId: null,
+                    error: message,
+                },
+            });
+        }
+    }
     async handleListAvailableEditorsRequest(request) {
         try {
             const editors = await this.getAvailableEditorTargets();
@@ -4530,11 +5180,10 @@ export class Session {
     async handleCreatePaseoWorktreeRequest(request) {
         return handleCreateWorktreeRequest({
             paseoHome: this.paseoHome,
-            workspaceGitService: this.workspaceGitService,
-            describeWorkspaceRecord: (workspace) => this.describeWorkspaceRecordWithGitData(workspace),
+            describeWorkspaceRecord: (result) => this.describeCreatedWorktreeWorkspace(result),
             emit: (message) => this.emit(message),
-            registerPendingWorktreeWorkspace: (options) => this.registerPendingWorktreeWorkspace(options),
-            syncWorkspaceGitWatchTarget: (cwd, syncOptions) => this.syncWorkspaceGitWatchTarget(cwd, syncOptions),
+            createPaseoWorktree: (input) => this.createPaseoWorktree(input),
+            warmWorkspaceGitData: (workspace) => this.warmWorkspaceGitDataForWorkspace(workspace),
             sessionLogger: this.sessionLogger,
             runWorktreeSetupInBackground: (options) => this.runWorktreeSetupInBackground(options),
         }, request);
@@ -4542,11 +5191,29 @@ export class Session {
     async runWorktreeSetupInBackground(options) {
         return runWorktreeSetupInBackgroundSession({
             paseoHome: this.paseoHome,
-            emitWorkspaceUpdateForCwd: (cwd) => this.emitWorkspaceUpdateForCwd(cwd),
+            emitWorkspaceUpdateForCwd: (cwd, emitOptions) => this.emitWorkspaceUpdateForCwd(cwd, emitOptions),
+            cacheWorkspaceSetupSnapshot: (workspaceId, snapshot) => {
+                this.workspaceSetupSnapshots.set(workspaceId, snapshot);
+            },
+            emit: (message) => this.emit(message),
             sessionLogger: this.sessionLogger,
             terminalManager: this.terminalManager,
+            archiveWorkspaceRecord: (workspaceId) => this.archiveWorkspaceRecord(workspaceId),
+            scriptRouteStore: this.scriptRouteStore,
+            scriptRuntimeStore: this.scriptRuntimeStore,
+            getDaemonTcpPort: this.getDaemonTcpPort,
+            getDaemonTcpHost: this.getDaemonTcpHost,
+            onScriptsChanged: (workspaceId, workspaceDirectory) => {
+                this.emitWorkspaceScriptStatusUpdate(workspaceId, workspaceDirectory);
+            },
         }, options);
     }
+    async handleWorkspaceSetupStatusRequest(request) {
+        return handleWorkspaceSetupStatusRequestMessage({
+            emit: (message) => this.emit(message),
+            workspaceSetupSnapshots: this.workspaceSetupSnapshots,
+        }, request);
+    }
     async handleArchiveWorkspaceRequest(request) {
         try {
             const existing = await this.workspaceRegistry.get(request.workspaceId);
@@ -4557,7 +5224,7 @@ export class Session {
                 throw new Error("Use worktree archive for Paseo worktrees");
             }
             const archivedAt = new Date().toISOString();
-            await this.archiveWorkspaceRecord(request.workspaceId, archivedAt);
+            await this.archiveWorkspaceRecord(existing.workspaceId, archivedAt);
             await this.emitWorkspaceUpdateForCwd(existing.cwd);
             this.emit({
                 type: "archive_workspace_response",
@@ -4605,7 +5272,7 @@ export class Session {
             });
             return;
         }
-        const project = await this.buildProjectPlacement(agent.cwd);
+        const project = await this.buildProjectPlacementForCwd(agent.cwd);
         this.emit({
             type: "fetch_agent_response",
             payload: { requestId, agent, project, error: null },
@@ -4764,7 +5431,7 @@ export class Session {
         }
         try {
             const agentId = resolved.agentId;
-            const prompt = this.buildAgentPrompt(msg.text, msg.images);
+            const prompt = this.buildAgentPrompt(msg.text, msg.images, msg.attachments);
             this.sessionLogger.trace({ agentId, messageId: msg.messageId, textPrefix: msg.text.slice(0, 80) }, "send_agent_message_request: dispatching shared sendPromptToAgent");
             try {
                 await sendPromptToAgent({
@@ -5232,9 +5899,7 @@ export class Session {
             await this.flushPendingAudioSegments("no active voice agent");
             return;
         }
-        await this.handleSendAgentMessage(agentId, result.text, undefined, undefined, undefined, {
-            spokenInput: true,
-        });
+        await this.handleSendAgentMessage(agentId, result.text, undefined, undefined, undefined, undefined, { spokenInput: true });
         await this.flushPendingAudioSegments("transcription complete");
     }
     registerVoiceBridgeForAgent(agentId) {
@@ -5492,9 +6157,9 @@ export class Session {
         }
         this.workspaceGitSubscriptions.clear();
     }
-    // ============================================================================
+    // ----------------------------------------------------------------------------
     // Terminal Handlers
-    // ============================================================================
+    // ----------------------------------------------------------------------------
     ensureTerminalExitSubscription(terminal) {
         if (this.terminalExitSubscriptions.has(terminal.id)) {
             return;
@@ -5933,15 +6598,27 @@ export class Session {
             },
         });
     }
+    filterStandaloneTerminals(terminals) {
+        return terminals;
+    }
+    toTerminalInfo(terminal) {
+        const title = terminal.getTitle();
+        return {
+            id: terminal.id,
+            name: terminal.name,
+            ...(title ? { title } : {}),
+        };
+    }
     handleTerminalsChanged(event) {
         if (!this.subscribedTerminalDirectories.has(event.cwd)) {
             return;
         }
         this.emitTerminalsChangedSnapshot({
             cwd: event.cwd,
-            terminals: event.terminals.map((terminal) => ({
+            terminals: this.filterStandaloneTerminals(event.terminals).map((terminal) => ({
                 id: terminal.id,
                 name: terminal.name,
+                ...(terminal.title ? { title: terminal.title } : {}),
             })),
         });
     }
@@ -5957,7 +6634,7 @@ export class Session {
             return;
         }
         try {
-            const terminals = await this.terminalManager.getTerminals(cwd);
+            const terminals = this.filterStandaloneTerminals(await this.terminalManager.getTerminals(cwd));
             for (const terminal of terminals) {
                 this.ensureTerminalExitSubscription(terminal);
             }
@@ -5966,10 +6643,7 @@ export class Session {
             }
             this.emitTerminalsChangedSnapshot({
                 cwd,
-                terminals: terminals.map((terminal) => ({
-                    id: terminal.id,
-                    name: terminal.name,
-                })),
+                terminals: terminals.map((terminal) => this.toTerminalInfo(terminal)),
             });
         }
         catch (error) {
@@ -5989,9 +6663,9 @@ export class Session {
             return;
         }
         try {
-            const terminals = typeof msg.cwd === "string"
+            const terminals = this.filterStandaloneTerminals(typeof msg.cwd === "string"
                 ? await this.terminalManager.getTerminals(msg.cwd)
-                : await this.getAllTerminalSessions();
+                : await this.getAllTerminalSessions());
             for (const terminal of terminals) {
                 this.ensureTerminalExitSubscription(terminal);
             }
@@ -5999,7 +6673,7 @@ export class Session {
                 type: "list_terminals_response",
                 payload: {
                     ...(msg.cwd ? { cwd: msg.cwd } : {}),
-                    terminals: terminals.map((t) => ({ id: t.id, name: t.name })),
+                    terminals: terminals.map((terminal) => this.toTerminalInfo(terminal)),
                     requestId: msg.requestId,
                 },
             });
@@ -6037,15 +6711,33 @@ export class Session {
             return;
         }
         try {
+            if (msg.agentId) {
+                this.emit({
+                    type: "create_terminal_response",
+                    payload: {
+                        terminal: null,
+                        error: `Agent-backed terminals are no longer supported for agent ${msg.agentId}`,
+                        requestId: msg.requestId,
+                    },
+                });
+                return;
+            }
             const session = await this.terminalManager.createTerminal({
                 cwd: msg.cwd,
                 name: msg.name,
+                command: msg.command,
+                args: msg.args,
             });
             this.ensureTerminalExitSubscription(session);
             this.emit({
                 type: "create_terminal_response",
                 payload: {
-                    terminal: { id: session.id, name: session.name, cwd: session.cwd },
+                    terminal: {
+                        id: session.id,
+                        name: session.name,
+                        cwd: session.cwd,
+                        ...(session.getTitle() ? { title: session.getTitle() } : {}),
+                    },
                     error: null,
                     requestId: msg.requestId,
                 },
@@ -6147,6 +6839,7 @@ export class Session {
         return killWorktreeTerminalsUnderPath({
             isPathWithinRoot: (pathRoot, candidatePath) => this.isPathWithinRoot(pathRoot, candidatePath),
             killTrackedTerminal: (terminalId, options) => this.killTrackedTerminal(terminalId, options),
+            detachTerminalStream: (terminalId, options) => void this.detachTerminalStream(terminalId, options),
             sessionLogger: this.sessionLogger,
             terminalManager: this.terminalManager,
         }, rootPath);
@@ -6253,6 +6946,19 @@ export class Session {
             slot,
             unsubscribe: () => { },
             needsSnapshot: true,
+            outputCoalescer: new TerminalOutputCoalescer({
+                timers: { setTimeout, clearTimeout },
+                onFlush: ({ payload }) => {
+                    if (this.activeTerminalStreams.get(slot) !== activeStream) {
+                        return;
+                    }
+                    this.emitBinary(encodeTerminalStreamFrame({
+                        opcode: TerminalStreamOpcode.Output,
+                        slot,
+                        payload,
+                    }));
+                },
+            }),
         };
         this.activeTerminalStreams.set(slot, activeStream);
         this.terminalIdToSlot.set(terminal.id, slot);
@@ -6261,17 +6967,18 @@ export class Session {
                 return;
             }
             if (message.type === "snapshot") {
+                activeStream.outputCoalescer.flush();
+                activeStream.needsSnapshot = true;
                 this.trySendTerminalSnapshot(activeStream);
                 return;
             }
+            if (message.type === "titleChange") {
+                return;
+            }
             if (activeStream.needsSnapshot || message.data.length === 0) {
                 return;
             }
-            this.emitBinary(encodeTerminalStreamFrame({
-                opcode: TerminalStreamOpcode.Output,
-                slot,
-                payload: new Uint8Array(Buffer.from(message.data, "utf8")),
-            }));
+            activeStream.outputCoalescer.handle(message.data);
         });
         return slot;
     }
@@ -6285,6 +6992,7 @@ export class Session {
             this.detachTerminalStream(activeStream.terminalId, { emitExit: true });
             return;
         }
+        activeStream.outputCoalescer.flush();
         activeStream.needsSnapshot = false;
         this.emitBinary(encodeTerminalStreamFrame({
             opcode: TerminalStreamOpcode.Snapshot,
@@ -6313,6 +7021,7 @@ export class Session {
             this.terminalIdToSlot.delete(terminalId);
             return false;
         }
+        activeStream.outputCoalescer.flush();
         this.activeTerminalStreams.delete(slot);
         this.terminalIdToSlot.delete(terminalId);
         try {
@@ -6341,4 +7050,37 @@ export class Session {
 // Stash handlers
 // ---------------------------------------------------------------------------
 Session.PASEO_STASH_PREFIX = "paseo-auto-stash:";
+export function normalizeCheckoutPrStatusPayload(status) {
+    if (!status) {
+        return null;
+    }
+    return {
+        number: status.number,
+        url: status.url,
+        title: status.title,
+        state: status.state,
+        repoOwner: status.repoOwner,
+        repoName: status.repoName,
+        baseRefName: status.baseRefName,
+        headRefName: status.headRefName,
+        isMerged: status.isMerged,
+        isDraft: status.isDraft ?? false,
+        checks: status.checks ?? [],
+        checksStatus: status.checksStatus,
+        reviewDecision: status.reviewDecision,
+    };
+}
+function isValidPullRequestTimelineIdentity(options) {
+    if (!Number.isInteger(options.prNumber) || options.prNumber <= 0) {
+        return false;
+    }
+    return isValidGitHubRepoSegment(options.repoOwner) && isValidGitHubRepoSegment(options.repoName);
+}
+function isValidGitHubRepoSegment(value) {
+    return /^[A-Za-z0-9._-]+$/.test(value);
+}
+function toPullRequestTimelinePayloadItem(item) {
+    const { authorUrl: _authorUrl, ...payload } = item;
+    return payload;
+}
 //# sourceMappingURL=session.js.map