@getpaseo/server 0.1.95 → 0.1.97-beta.1

package/dist/server/server/session.js

@@ -2,7 +2,7 @@ import equal from "fast-deep-equal";
 import { v4 as uuidv4 } from "uuid";
 import { realpathSync } from "node:fs";
 import { stat } from "node:fs/promises";
-import { basename, resolve, sep } from "path";
+import { resolve, sep } from "path";
 import { homedir } from "node:os";
 import { z } from "zod";
 import { CLIENT_CAPS } from "@getpaseo/protocol/client-capabilities";
@@ -42,8 +42,9 @@ import { StructuredAgentFallbackError, StructuredAgentResponseError, generateStr
 import { resolveStructuredGenerationProviders, } from "./agent/structured-generation-providers.js";
 import { getAgentStreamEventTurnId, } from "./agent/agent-sdk-types.js";
 import { ImportSessionsRequestError, importProviderSession, listImportableProviderSessions, normalizeImportAgentRequest, } from "./agent/import-sessions.js";
-import { checkoutLiteFromGitSnapshot, normalizeWorkspaceId as normalizePersistedWorkspaceId, deriveProjectGroupingName, classifyDirectoryForProjectMembership, deriveWorkspaceDisplayName, } from "./workspace-registry-model.js";
-import { createPersistedProjectRecord, createPersistedWorkspaceRecord, resolveProjectDisplayName, } from "./workspace-registry.js";
+import { checkoutLiteFromGitSnapshot, classifyDirectoryForProjectMembership, deriveWorkspaceDisplayName, generateWorkspaceId, } from "./workspace-registry-model.js";
+import { resolveWorkspaceIdForPath } from "./resolve-workspace-id-for-path.js";
+import { createPersistedProjectRecord, createPersistedWorkspaceRecord, resolveProjectDisplayName, resolveWorkspaceDisplayName, resolveWorkspaceName, } from "./workspace-registry.js";
 import { buildVoiceModeSystemPrompt, stripVoiceModeSystemPrompt, wrapSpokenInput, } from "./voice-config.js";
 import { isVoicePermissionAllowed } from "./voice-permission-policy.js";
 import { listDirectoryEntries, readExplorerFile, readExplorerFileBytes, getDownloadableFileInfo, } from "./file-explorer/service.js";
@@ -51,7 +52,7 @@ import { readPaseoConfigForEdit, writePaseoConfigForEdit, } from "../utils/paseo
 import { buildMetadataPrompt } from "../utils/build-metadata-prompt.js";
 import { archivePersistedWorkspaceRecord } from "./workspace-archive-service.js";
 import { WorkspaceReconciliationService } from "./workspace-reconciliation-service.js";
-import { checkoutResolvedBranch, commitChanges, mergeToBase, mergeFromBase, pullCurrentBranch, pushCurrentBranch, createPullRequest, renameCurrentBranch, } from "../utils/checkout-git.js";
+import { checkoutResolvedBranch, commitChanges, mergeToBase, mergeFromBase, pullCurrentBranch, pushCurrentBranch, createPullRequest, renameCurrentBranch as renameCurrentBranchDefault, } from "../utils/checkout-git.js";
 import { validateBranchSlug } from "@getpaseo/protocol/branch-slug";
 import { getProjectIcon } from "../utils/project-icon.js";
 import { expandTilde } from "../utils/path.js";
@@ -63,11 +64,12 @@ import { ChatServiceError, parseMentionAgentIds, } from "./chat/chat-service.js"
 import { notifyChatMentions, prepareChatMentionFanout } from "./chat/chat-mentions.js";
 import { execCommand } from "../utils/spawn.js";
 import { assertPullRequestAutoMergeDisableReady, assertPullRequestAutoMergeEnableReady, createGitHubService, } from "../services/github-service.js";
-import { summarizeFetchWorkspacesEntries, WorkspaceDirectory, } from "./workspace-directory.js";
+import { summarizeFetchWorkspacesEntries, workspaceIdsOnCheckout, WorkspaceDirectory, } from "./workspace-directory.js";
 import { shouldEmitPendingBootstrapUpdate } from "./workspace-bootstrap-dedupe.js";
-import { attemptFirstAgentBranchAutoName, createPaseoWorktree, } from "./paseo-worktree-service.js";
-import { generateBranchNameFromFirstAgentContext } from "./worktree-branch-name-generator.js";
+import { attemptFirstAgentBranchAutoName, createLocalCheckoutWorkspace, createPaseoWorktree, } from "./paseo-worktree-service.js";
+import { generateBranchNameFromFirstAgentContext, } from "./worktree-branch-name-generator.js";
 import { assertSafeGitRef as assertWorktreeSafeGitRef, buildAgentSessionConfig as buildWorktreeAgentSessionConfig, createPaseoWorktreeWorkflow as createWorktreeWorkflow, handleCreatePaseoWorktreeRequest as handleCreateWorktreeRequest, handlePaseoWorktreeArchiveRequest as handleWorktreeArchiveRequest, handlePaseoWorktreeListRequest as handleWorktreeListRequest, handleWorkspaceSetupStatusRequest as handleWorkspaceSetupStatusRequestMessage, } from "./worktree-session.js";
+import { archiveByScope } from "./workspace-archive-service.js";
 import { toWorktreeWireError } from "./worktree-errors.js";
 import { CreateAgentLifecycleDispatch } from "./agent/create-agent-lifecycle-dispatch.js";
 const WORKSPACE_GIT_WATCH_REMOVED_STATE_KEY = "__removed__";
@@ -136,7 +138,12 @@ function diffChangeTypeFor(file) {
         return "D";
     return "M";
 }
-function buildWorkspaceCheckout(workspace, project) {
+function buildWorkspaceCheckout(workspace, project, 
+// The persisted `branch` field is the source of truth, but it is null for
+// records created before branch was lifted to its own field (no migrations,
+// per data-model.md) and for any path that didn't backfill it. Fall back to
+// the live git branch so checkout.currentBranch never regresses to null.
+fallbackBranch) {
     if (project.kind !== "git") {
         return {
             cwd: workspace.cwd,
@@ -148,11 +155,12 @@ function buildWorkspaceCheckout(workspace, project) {
             mainRepoRoot: null,
         };
     }
+    const currentBranch = workspace.branch ?? fallbackBranch ?? null;
     if (workspace.kind === "worktree") {
         return {
             cwd: workspace.cwd,
             isGit: true,
-            currentBranch: workspace.displayName,
+            currentBranch,
             remoteUrl: null,
             worktreeRoot: workspace.cwd,
             isPaseoOwnedWorktree: true,
@@ -162,7 +170,7 @@ function buildWorkspaceCheckout(workspace, project) {
     return {
         cwd: workspace.cwd,
         isGit: true,
-        currentBranch: workspace.displayName,
+        currentBranch,
         remoteUrl: null,
         worktreeRoot: workspace.cwd,
         isPaseoOwnedWorktree: false,
@@ -296,6 +304,7 @@ export class Session {
         this.agentMcpClient = null;
         this.agentTools = null;
         this.unsubscribeAgentEvents = null;
+        this.unsubscribeTerminalWorkspaceContributionEvents = null;
         this.agentUpdatesSubscription = null;
         this.workspaceUpdatesSubscription = null;
         this.clientActivity = null;
@@ -331,13 +340,14 @@ export class Session {
                 }
             },
         });
-        const { clientId, appVersion, clientCapabilities, onMessage, onBinaryMessage, onLifecycleIntent, logger, downloadTokenStore, pushTokenStore, paseoHome, worktreesRoot, agentManager, agentStorage, projectRegistry, workspaceRegistry, filesystem, chatService, scheduleService, loopService, checkoutDiffManager, github, workspaceGitService, daemonConfigStore, mcpBaseUrl, stt, sttLanguage, tts, terminalManager, providerSnapshotManager, serviceProxy, scriptRuntimeStore, workspaceSetupSnapshots, onBranchChanged, getDaemonTcpPort, getDaemonTcpHost, serviceProxyPublicBaseUrl, resolveScriptHealth, voice, voiceBridge, dictation, serverId, daemonVersion, daemonRuntimeConfig, } = options;
+        const { clientId, appVersion, clientCapabilities, onMessage, onBinaryMessage, getTransportBufferedAmount, onLifecycleIntent, logger, downloadTokenStore, pushTokenStore, paseoHome, worktreesRoot, agentManager, agentStorage, projectRegistry, workspaceRegistry, filesystem, chatService, scheduleService, loopService, checkoutDiffManager, github, renameCurrentBranch, generateWorkspaceName, workspaceGitService, daemonConfigStore, mcpBaseUrl, stt, sttLanguage, tts, terminalManager, providerSnapshotManager, serviceProxy, scriptRuntimeStore, workspaceSetupSnapshots, onBranchChanged, getDaemonTcpPort, getDaemonTcpHost, serviceProxyPublicBaseUrl, resolveScriptHealth, voice, voiceBridge, dictation, serverId, daemonVersion, daemonRuntimeConfig, } = options;
         this.clientId = clientId;
         this.appVersion = appVersion ?? null;
         this.clientCapabilities = parseClientCapabilities(clientCapabilities);
         this.sessionId = uuidv4();
         this.onMessage = onMessage;
         this.onBinaryMessage = onBinaryMessage ?? null;
+        this.getTransportBufferedAmount = getTransportBufferedAmount ?? (() => 0);
         this.onLifecycleIntent = onLifecycleIntent ?? null;
         this.downloadTokenStore = downloadTokenStore;
         this.pushTokenStore = pushTokenStore;
@@ -359,6 +369,8 @@ export class Session {
         this.loopService = loopService;
         this.checkoutDiffManager = checkoutDiffManager;
         this.github = github ?? createGitHubService();
+        this.renameCurrentBranch = renameCurrentBranch ?? renameCurrentBranchDefault;
+        this.generateWorkspaceName = generateWorkspaceName ?? generateBranchNameFromFirstAgentContext;
         this.workspaceGitService = workspaceGitService;
         this.daemonConfigStore = daemonConfigStore;
         this.mcpBaseUrl = mcpBaseUrl ?? null;
@@ -377,6 +389,7 @@ export class Session {
                     .map((workspace) => workspace.cwd);
             },
             clientSupportsWrapReflow: () => this.clientCapabilities.has(CLIENT_CAPS.terminalReflowableSnapshot),
+            getClientBufferedAmount: () => this.getTransportBufferedAmount(),
         });
         this.createAgentLifecycleDispatch = new CreateAgentLifecycleDispatch({
             paseoHome: this.paseoHome,
@@ -387,6 +400,8 @@ export class Session {
             workspaceGitService: this.workspaceGitService,
             createPaseoWorktreeWorkflow: (input, workflowOptions) => this.createPaseoWorktreeWorkflow(input, workflowOptions),
             archiveAgentForClose: (agentId) => this.archiveAgentForClose(agentId),
+            findWorkspaceIdForCwd: (cwd) => this.findWorkspaceIdForCwd(cwd),
+            listActiveWorkspaces: () => this.listActiveWorkspaceRefs(),
             archiveWorkspaceRecord: (workspaceId) => this.archiveWorkspaceRecord(workspaceId),
             emit: (message) => this.emit(message),
             emitAgentRemove: (agentId) => {
@@ -400,8 +415,7 @@ export class Session {
             emitWorkspaceUpdatesForWorkspaceIds: (workspaceIds) => this.emitWorkspaceUpdatesForWorkspaceIds(workspaceIds),
             markWorkspaceArchiving: (workspaceIds, archivingAt) => this.markWorkspaceArchiving(workspaceIds, archivingAt),
             clearWorkspaceArchiving: (workspaceIds) => this.clearWorkspaceArchiving(workspaceIds),
-            isPathWithinRoot: (rootPath, candidatePath) => this.isPathWithinRoot(rootPath, candidatePath),
-            killTerminalsUnderPath: (rootPath) => this.terminalController.killTerminalsUnderPath(rootPath),
+            killTerminalsForWorkspace: (workspaceId) => this.terminalController.killTerminalsForWorkspace(workspaceId),
             logger: this.sessionLogger,
         });
         this.providerSnapshotManager = providerSnapshotManager;
@@ -425,6 +439,7 @@ export class Session {
             projectRegistry: this.projectRegistry,
             workspaceRegistry: this.workspaceRegistry,
             listAgentPayloads: () => this.listAgentPayloads(),
+            listTerminalActivityContributions: () => this.listTerminalActivityContributions(),
             isProviderVisibleToClient: (provider) => this.isProviderVisibleToClient(provider),
             buildWorkspaceDescriptor: (input) => this.buildWorkspaceDescriptor(input),
         });
@@ -477,9 +492,6 @@ export class Session {
     async emitWorkspaceUpdatesForExternalWorkspaceIds(workspaceIds) {
         await this.emitWorkspaceUpdatesForWorkspaceIds(workspaceIds);
     }
-    async emitWorkspaceUpdatesForExternalCwds(cwds) {
-        await Promise.all(Array.from(cwds, (cwd) => this.emitWorkspaceUpdateForCwd(cwd)));
-    }
     async warmWorkspaceGitDataForWorkspace(workspace) {
         await this.syncWorkspaceGitObserverForWorkspace(workspace);
         await this.emitWorkspaceUpdateForWorkspaceId(workspace.workspaceId);
@@ -626,6 +638,14 @@ export class Session {
      */
     subscribeToOptionalManagers() {
         this.terminalController.start();
+        if (this.terminalManager) {
+            this.unsubscribeTerminalWorkspaceContributionEvents =
+                this.terminalManager.subscribeTerminalWorkspaceContributionChanged((event) => {
+                    void this.emitWorkspaceUpdateForTerminalContribution(event).catch((error) => {
+                        this.sessionLogger.warn({ err: error, terminalId: event.terminalId }, "Failed to emit workspace update after terminal contribution changed");
+                    });
+                });
+        }
         const handleProviderSnapshotChange = (entries, cwd) => {
             // COMPAT(providersSnapshot): keep provider visibility gating for older clients.
             const visibleEntries = entries.filter((entry) => this.isProviderVisibleToClient(entry.provider));
@@ -763,7 +783,7 @@ export class Session {
         payload.archivedAt = storedRecord?.archivedAt ?? null;
         return payload;
     }
-    buildStoredAgentPayload(record, registeredProviderIds = this.providerSnapshotManager.listRegisteredProviderIds()) {
+    buildStoredAgentPayload(record, registeredProviderIds = new Set(this.providerSnapshotManager.listRegisteredProviderIds())) {
         return buildStoredAgentPayload(record, registeredProviderIds);
     }
     isProviderVisibleToClient(provider) {
@@ -867,61 +887,37 @@ export class Session {
             });
         }
     }
-    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;
-    }
     async findExactWorkspaceByDirectory(cwd, options) {
         const normalizedCwd = await this.resolveWorkspaceDirectory(cwd, options);
         const workspaces = await this.workspaceRegistry.list();
         return workspaces.find((workspace) => workspace.cwd === normalizedCwd) ?? null;
     }
     async resolveWorkspaceDirectory(cwd, options) {
-        const normalizedCwd = normalizePersistedWorkspaceId(cwd);
+        const normalizedCwd = resolve(cwd);
         if (options?.refreshGit === false) {
             const snapshot = this.workspaceGitService.peekSnapshot(normalizedCwd);
-            return normalizePersistedWorkspaceId(snapshot?.git.repoRoot ?? normalizedCwd);
+            return resolve(snapshot?.git.repoRoot ?? normalizedCwd);
         }
         const checkout = await this.workspaceGitService.getCheckout(normalizedCwd);
-        return normalizePersistedWorkspaceId(checkout.worktreeRoot ?? normalizedCwd);
+        return resolve(checkout.worktreeRoot ?? 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 = buildWorkspaceCheckout(workspace, project);
+        const liveBranch = this.workspaceGitService.peekSnapshot(workspace.cwd)?.git.currentBranch ?? null;
+        const checkout = buildWorkspaceCheckout(workspace, project, liveBranch);
         return {
             projectKey: project.projectId,
             projectName: resolveProjectDisplayName(project),
             checkout,
         };
     }
-    async buildProjectPlacementForCwd(cwd, options) {
-        const workspace = await this.findWorkspaceByDirectory(cwd, {
-            refreshGit: options?.refreshGit,
-        });
-        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,
-                },
-            };
-        }
+    async buildProjectPlacementForWorkspaceId(workspaceId) {
+        const workspace = await this.workspaceRegistry.get(workspaceId);
+        if (!workspace)
+            return null;
         return this.buildProjectPlacementForWorkspace(workspace);
     }
     async forwardAgentUpdate(agent) {
@@ -929,33 +925,41 @@ export class Session {
             const subscription = this.agentUpdatesSubscription;
             const payload = await this.buildAgentPayload(agent);
             if (subscription) {
-                const project = await this.buildProjectPlacementForCwd(payload.cwd, {
-                    refreshGit: false,
-                    fallback: true,
-                });
+                const project = payload.workspaceId
+                    ? await this.buildProjectPlacementForWorkspaceId(payload.workspaceId)
+                    : null;
                 if (!project) {
-                    throw new Error(`Workspace not found for agent ${payload.id}`);
-                }
-                const matches = this.matchesAgentFilter({
-                    agent: payload,
-                    project,
-                    filter: subscription.filter,
-                });
-                if (matches) {
                     this.bufferOrEmitAgentUpdate(subscription, {
-                        kind: "upsert",
-                        agent: payload,
-                        project,
+                        kind: "remove",
+                        agentId: payload.id,
                     });
                 }
                 else {
-                    this.bufferOrEmitAgentUpdate(subscription, {
-                        kind: "remove",
-                        agentId: payload.id,
+                    const matches = this.matchesAgentFilter({
+                        agent: payload,
+                        project,
+                        filter: subscription.filter,
                     });
+                    if (matches) {
+                        this.bufferOrEmitAgentUpdate(subscription, {
+                            kind: "upsert",
+                            agent: payload,
+                            project,
+                        });
+                    }
+                    else {
+                        this.bufferOrEmitAgentUpdate(subscription, {
+                            kind: "remove",
+                            agentId: payload.id,
+                        });
+                    }
                 }
             }
-            await this.emitWorkspaceUpdateForCwd(payload.cwd);
+            // A lifecycle change updates exactly the agent's owning workspace, never
+            // every workspace sharing its cwd. Ownership is the agent's workspaceId.
+            if (payload.workspaceId) {
+                await this.emitWorkspaceUpdateForWorkspaceId(payload.workspaceId);
+            }
         }
         catch (error) {
             this.sessionLogger.error({ err: error }, "Failed to emit agent update");
@@ -1341,8 +1345,12 @@ export class Session {
                 return this.handleOpenProjectRequest(msg);
             case "archive_workspace_request":
                 return this.handleArchiveWorkspaceRequest(msg);
+            case "workspace.create.request":
+                return this.handleWorkspaceCreateRequest(msg);
             case "workspace.clear_attention.request":
                 return this.handleWorkspaceClearAttentionRequest(msg);
+            case "workspace.title.set.request":
+                return this.handleWorkspaceTitleSetRequest(msg.workspaceId, msg.title, msg.requestId);
             case "file_explorer_request":
                 return this.handleFileExplorerRequest(msg);
             case "project_icon_request":
@@ -1506,8 +1514,8 @@ export class Session {
     }
     async handleDeleteAgentRequest(agentId, requestId) {
         this.sessionLogger.info({ agentId }, `Deleting agent ${agentId} from registry`);
-        const knownCwd = this.agentManager.getAgent(agentId)?.cwd ??
-            (await this.agentStorage.get(agentId))?.cwd ??
+        const knownWorkspaceId = this.agentManager.getAgent(agentId)?.workspaceId ??
+            (await this.agentStorage.get(agentId))?.workspaceId ??
             null;
         // File-backed storage still needs an early delete fence before closeAgent().
         beginAgentDeleteIfSupported(this.agentStorage, agentId);
@@ -1540,8 +1548,8 @@ export class Session {
                 agentId,
             });
         }
-        if (knownCwd) {
-            await this.emitWorkspaceUpdateForCwd(knownCwd);
+        if (knownWorkspaceId) {
+            await this.emitWorkspaceUpdateForWorkspaceId(knownWorkspaceId);
         }
     }
     async handleArchiveAgentRequest(agentId, requestId) {
@@ -1564,7 +1572,9 @@ export class Session {
         }, agentId);
         if (this.agentUpdatesSubscription) {
             const payload = this.buildStoredAgentPayload(archivedRecord);
-            const project = await this.buildProjectPlacementForCwd(payload.cwd);
+            const project = payload.workspaceId
+                ? await this.buildProjectPlacementForWorkspaceId(payload.workspaceId)
+                : null;
             if (project) {
                 const matches = this.matchesAgentFilter({
                     agent: payload,
@@ -1588,7 +1598,9 @@ export class Session {
                     agentId,
                 });
             }
-            await this.emitWorkspaceUpdateForCwd(payload.cwd);
+            if (payload.workspaceId) {
+                await this.emitWorkspaceUpdateForWorkspaceId(payload.workspaceId);
+            }
         }
         return { agentId, archivedAt };
     }
@@ -1752,6 +1764,67 @@ export class Session {
             });
         }
     }
+    async handleWorkspaceTitleSetRequest(workspaceId, title, requestId) {
+        this.sessionLogger.info({ workspaceId, requestId, hasTitle: typeof title === "string" }, "session: workspace.title.set.request");
+        try {
+            const existing = await this.workspaceRegistry.get(workspaceId);
+            if (!existing) {
+                this.emit({
+                    type: "workspace.title.set.response",
+                    payload: {
+                        requestId,
+                        workspaceId,
+                        accepted: false,
+                        title: null,
+                        error: "Workspace not found",
+                    },
+                });
+                return;
+            }
+            const trimmed = title?.trim() ?? "";
+            const nextTitle = trimmed.length === 0 ? null : trimmed;
+            await this.workspaceRegistry.upsert({
+                ...existing,
+                title: nextTitle,
+                updatedAt: new Date().toISOString(),
+            });
+            this.emit({
+                type: "workspace.title.set.response",
+                payload: {
+                    requestId,
+                    workspaceId,
+                    accepted: true,
+                    title: nextTitle,
+                    error: null,
+                },
+            });
+            await this.emitWorkspaceUpdatesForWorkspaceIds([workspaceId], {
+                skipReconcile: true,
+            });
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, workspaceId, requestId }, "session: workspace.title.set.request error");
+            this.emit({
+                type: "activity_log",
+                payload: {
+                    id: uuidv4(),
+                    timestamp: new Date(),
+                    type: "error",
+                    content: `Failed to set workspace title: ${getErrorMessage(error)}`,
+                },
+            });
+            this.emit({
+                type: "workspace.title.set.response",
+                payload: {
+                    requestId,
+                    workspaceId,
+                    accepted: false,
+                    title: null,
+                    error: getErrorMessageOr(error, "Failed to set workspace title"),
+                },
+            });
+        }
+    }
     toVoiceFeatureUnavailableContext(state) {
         return {
             reasonCode: state.reasonCode,
@@ -2088,7 +2161,7 @@ export class Session {
         let createdAgentId = null;
         try {
             const trimmedPrompt = initialPrompt?.trim();
-            const { explicitTitle, provisionalTitle } = resolveCreateAgentTitles({
+            const { provisionalTitle } = resolveCreateAgentTitles({
                 configTitle: config.title,
                 initialPrompt: trimmedPrompt,
             });
@@ -2106,19 +2179,23 @@ export class Session {
             const createAgentConfig = createdWorktree
                 ? { ...config, cwd: createdWorktree.worktree.worktreePath }
                 : config;
+            // Ownership comes from an explicit id (worktree or request). An agent
+            // created with no explicit workspace mints a fresh one — we never resolve
+            // an existing workspace by cwd, because many workspaces may share a cwd.
+            const workspaceId = createdWorktree?.workspace.workspaceId ??
+                msg.workspaceId ??
+                (await this.createWorkspaceForDirectory(createAgentConfig.cwd)).workspaceId;
             const { snapshot, liveSnapshot } = await createAgentCommand({
                 agentManager: this.agentManager,
                 agentStorage: this.agentStorage,
                 logger: this.sessionLogger,
                 paseoHome: this.paseoHome,
                 worktreesRoot: this.worktreesRoot,
-                workspaceGitService: this.workspaceGitService,
                 providerSnapshotManager: this.providerSnapshotManager,
-                daemonConfig: this.readStructuredGenerationDaemonConfig(),
             }, {
                 kind: "session",
                 config: createAgentConfig,
-                workspaceId: msg.workspaceId,
+                workspaceId,
                 worktreeName,
                 initialPrompt,
                 clientMessageId,
@@ -2129,13 +2206,18 @@ export class Session {
                 labels,
                 env,
                 provisionalTitle,
-                explicitTitle,
                 firstAgentContext,
                 buildSessionConfig: (sessionConfig, gitOptions, legacyWorktreeName, ctx) => this.buildAgentSessionConfig(sessionConfig, gitOptions, legacyWorktreeName, ctx),
-                resolveWorkspace: ({ cwd, workspaceId }) => this.resolveCreateAgentWorkspace(cwd, workspaceId),
             });
             createdAgentId = snapshot.id;
             await this.forwardAgentUpdate(snapshot);
+            if (!createdWorktree && trimmedPrompt) {
+                await this.scheduleAutoNameLocalWorkspaceTitleForFirstAgent({
+                    workspaceId,
+                    cwd: createAgentConfig.cwd,
+                    firstAgentContext,
+                });
+            }
             this.createAgentLifecycleDispatch.registerAutoArchiveIfRequested({
                 autoArchive,
                 agentId: snapshot.id,
@@ -2184,16 +2266,6 @@ export class Session {
             });
         }
     }
-    async resolveCreateAgentWorkspace(cwd, workspaceId) {
-        const resolvedWorkspace = workspaceId
-            ? await this.workspaceRegistry.get(workspaceId)
-            : ((await this.findWorkspaceByDirectory(cwd)) ??
-                (await this.findOrCreateWorkspaceForDirectory(cwd)));
-        if (!resolvedWorkspace) {
-            throw new Error(`Workspace not found: ${workspaceId}`);
-        }
-        return { workspaceId: resolvedWorkspace.workspaceId };
-    }
     async handleResumeAgentRequest(msg) {
         const { handle, overrides, requestId } = msg;
         if (!handle) {
@@ -2283,17 +2355,20 @@ export class Session {
         const { provider, providerHandleId, requestId } = normalized;
         this.sessionLogger.info({ providerHandleId, provider }, `Importing agent ${providerHandleId} (${provider})`);
         try {
+            if (!normalized.cwd) {
+                throw new Error("Import requires cwd from the selected provider session");
+            }
+            // An imported agent mints its own workspace; ownership is its workspaceId,
+            // never an existing same-cwd workspace resolved by path.
+            const workspace = await this.createWorkspaceForDirectory(normalized.cwd);
             const { snapshot, timelineSize } = await importProviderSession({
                 request: normalized,
+                workspaceId: workspace.workspaceId,
                 agentManager: this.agentManager,
                 agentStorage: this.agentStorage,
-                workspaceGitService: this.workspaceGitService,
-                providerSnapshotManager: this.providerSnapshotManager,
-                daemonConfig: this.readStructuredGenerationDaemonConfig(),
-                paseoHome: this.paseoHome,
                 logger: this.sessionLogger,
             });
-            await this.registerWorkspaceForImportedAgent(snapshot.cwd);
+            await this.registerWorkspaceForImportedAgent(workspace);
             const agentPayload = await this.buildAgentPayload(snapshot);
             this.emit({
                 type: "status",
@@ -2472,18 +2547,20 @@ export class Session {
         }, config, gitOptions, legacyWorktreeName, firstAgentContext);
     }
     scheduleAutoNameWorkspaceBranchForFirstAgent(input) {
-        setTimeout(() => {
-            void this.maybeAutoNameWorkspaceBranchForFirstAgent(input).catch((error) => {
-                this.sessionLogger.warn({ err: error, cwd: input.workspace.cwd }, "Failed to auto-name worktree branch");
-            });
-        }, 0);
+        this.scheduleWorkspaceNaming(() => this.maybeAutoNameWorkspaceBranchForFirstAgent(input), {
+            cwd: input.workspace.cwd,
+            message: "Failed to auto-name worktree branch",
+        });
     }
     async maybeAutoNameWorkspaceBranchForFirstAgent(input) {
+        // Capture the generated title from the generator callback so we can write
+        // title := generated title after the branch rename completes.
+        let generatedTitle = null;
         const result = await attemptFirstAgentBranchAutoName({
             cwd: input.workspace.cwd,
             firstAgentContext: input.firstAgentContext,
             generateBranchNameFromContext: ({ cwd, firstAgentContext }) => {
-                return generateBranchNameFromFirstAgentContext({
+                return this.generateWorkspaceName({
                     agentManager: this.agentManager,
                     cwd,
                     workspaceGitService: this.workspaceGitService,
@@ -2492,21 +2569,80 @@ export class Session {
                     currentSelection: this.getFocusedAgentSelectionForCwd(cwd),
                     firstAgentContext,
                     logger: this.sessionLogger,
+                }).then((r) => {
+                    generatedTitle = r?.title ?? null;
+                    return r?.branch ?? null;
                 });
             },
         });
-        if (!result.renamed || !result.branchName) {
-            return input.workspace;
+        if (!result.renamed || !generatedTitle) {
+            return;
         }
-        const updatedWorkspace = {
-            ...input.workspace,
-            displayName: result.branchName,
-            updatedAt: new Date().toISOString(),
-        };
-        await this.workspaceRegistry.upsert(updatedWorkspace);
+        // K4: re-read from the registry before writing so any concurrent upsert
+        // that happened between workspace creation and this async path is not clobbered.
+        // The first-agent rename renamed the git branch too, so persist the new branch
+        // alongside the title — both are this path's own fields.
+        await this.applyGeneratedWorkspaceTitle(input.workspace.workspaceId, {
+            title: generatedTitle,
+            branch: result.branchName,
+        });
         await this.notifyGitMutation(input.workspace.cwd, "rename-branch");
         await this.emitWorkspaceUpdateForCwd(input.workspace.cwd);
-        return updatedWorkspace;
+    }
+    // applyGeneratedWorkspaceTitle fills the generated title only while the
+    // workspace is still untitled. It re-reads the current record from the
+    // registry so concurrent upserts that happened after workspace creation are
+    // not clobbered, while still persisting branch metadata from the rename path.
+    async applyGeneratedWorkspaceTitle(workspaceId, input) {
+        const current = await this.workspaceRegistry.get(workspaceId);
+        if (!current) {
+            return;
+        }
+        await this.workspaceRegistry.upsert({
+            ...current,
+            title: current.title || input.title,
+            ...(input.branch ? { branch: input.branch } : {}),
+            updatedAt: new Date().toISOString(),
+        });
+    }
+    // Wraps the injected workspace-name generator for a directory workspace.
+    async generateWorkspaceTitleFromContext(input) {
+        return this.generateWorkspaceName({
+            agentManager: this.agentManager,
+            cwd: input.cwd,
+            workspaceGitService: this.workspaceGitService,
+            providerSnapshotManager: this.providerSnapshotManager,
+            daemonConfig: this.readStructuredGenerationDaemonConfig(),
+            currentSelection: this.getFocusedAgentSelectionForCwd(input.cwd),
+            firstAgentContext: input.firstAgentContext,
+            logger: this.sessionLogger,
+        });
+    }
+    // Generates a human title for a directory workspace from the firstAgentContext
+    // prompt and writes it as displayName. No branch rename — directory workspaces
+    // have no worktree git state.
+    // TODO(K7): same-dir directory-workspace display disambiguation not yet implemented.
+    async maybeAutoNameDirectoryWorkspaceTitle(input) {
+        const generated = await this.generateWorkspaceTitleFromContext({
+            cwd: input.cwd,
+            firstAgentContext: input.firstAgentContext,
+        });
+        const title = generated?.title ?? null;
+        if (!title) {
+            return;
+        }
+        // K4: applyGeneratedWorkspaceTitle re-reads from the registry before writing.
+        // Directory workspaces have no branch — write only the title.
+        await this.applyGeneratedWorkspaceTitle(input.workspaceId, { title });
+        await this.emitWorkspaceUpdateForWorkspaceId(input.workspaceId);
+    }
+    async scheduleAutoNameLocalWorkspaceTitleForFirstAgent(input) {
+        const workspaceId = input.workspaceId;
+        this.scheduleWorkspaceNaming(() => this.maybeAutoNameDirectoryWorkspaceTitle({
+            workspaceId,
+            cwd: input.cwd,
+            firstAgentContext: input.firstAgentContext,
+        }), { cwd: input.cwd, message: "Failed to auto-name local workspace title" });
     }
     emitProviderDisabledResponse(kind, provider, requestId, fetchedAt) {
         const payload = {
@@ -2719,6 +2855,7 @@ export class Session {
                 relayPublicEndpoint: relay?.publicEndpoint,
                 relayUseTls: relay?.useTls,
                 relayPublicUseTls: relay?.publicUseTls,
+                appBaseUrl: this.daemonRuntimeConfig?.appBaseUrl,
                 includeQr: true,
                 logger: this.sessionLogger,
             });
@@ -3211,16 +3348,33 @@ export class Session {
      * Handle client heartbeat for activity tracking
      */
     handleClientHeartbeat(msg) {
+        const focusedTerminalId = msg.focusedTerminalId?.trim() || null;
         const appVisibilityChangedAt = msg.appVisibilityChangedAt
             ? new Date(msg.appVisibilityChangedAt)
             : new Date(msg.lastActivityAt);
         this.clientActivity = {
             deviceType: msg.deviceType,
             focusedAgentId: msg.focusedAgentId,
+            focusedTerminalId,
             lastActivityAt: new Date(msg.lastActivityAt),
             appVisible: msg.appVisible,
             appVisibilityChangedAt,
         };
+        if (msg.appVisible && focusedTerminalId) {
+            void this.clearFocusedTerminalAttention(focusedTerminalId);
+        }
+    }
+    async clearFocusedTerminalAttention(terminalId) {
+        const terminalManager = this.terminalManager;
+        if (!terminalManager) {
+            return;
+        }
+        try {
+            await terminalManager.clearTerminalAttention(terminalId);
+        }
+        catch (error) {
+            this.sessionLogger.warn({ err: error, terminalId }, "Failed to clear terminal attention");
+        }
     }
     /**
      * Handle push token registration
@@ -3542,7 +3696,7 @@ export class Session {
         target.watchers.length = 0;
     }
     async removeWorkspaceGitWatchTarget(cwd) {
-        const normalizedCwd = normalizePersistedWorkspaceId(cwd);
+        const normalizedCwd = resolve(cwd);
         const target = this.workspaceGitWatchTargets.get(normalizedCwd);
         if (target) {
             this.closeWorkspaceGitWatchTarget(target);
@@ -3550,7 +3704,7 @@ export class Session {
         }
     }
     removeWorkspaceGitSubscription(cwd) {
-        const normalizedCwd = normalizePersistedWorkspaceId(cwd);
+        const normalizedCwd = resolve(cwd);
         const target = this.workspaceGitWatchTargets.get(normalizedCwd);
         if (target) {
             const unsubscribeFetch = this.workspaceGitFetchSubscriptions.get(normalizedCwd);
@@ -3571,8 +3725,16 @@ export class Session {
             workspace.diffStat ? [workspace.diffStat.additions, workspace.diffStat.deletions] : null,
         ]);
     }
+    resolveWorkspaceGitWatchTarget(workspaceId) {
+        for (const target of this.workspaceGitWatchTargets.values()) {
+            if (target.workspaceId === workspaceId) {
+                return target;
+            }
+        }
+        return null;
+    }
     shouldSkipWorkspaceGitWatchUpdate(workspaceId, workspace) {
-        const target = this.workspaceGitWatchTargets.get(workspaceId);
+        const target = this.resolveWorkspaceGitWatchTarget(workspaceId);
         if (!target) {
             return false;
         }
@@ -3584,7 +3746,7 @@ export class Session {
         return false;
     }
     rememberWorkspaceGitDescriptorState(workspaceId, workspace) {
-        const target = this.workspaceGitWatchTargets.get(workspaceId);
+        const target = this.resolveWorkspaceGitWatchTarget(workspaceId);
         if (!target) {
             return;
         }
@@ -3592,7 +3754,7 @@ export class Session {
         target.lastBranchName = workspace?.name ?? null;
     }
     handleWorkspaceGitBranchSnapshot(cwd, branchName) {
-        const target = this.workspaceGitWatchTargets.get(normalizePersistedWorkspaceId(cwd));
+        const target = this.workspaceGitWatchTargets.get(resolve(cwd));
         if (!target) {
             return;
         }
@@ -3613,7 +3775,7 @@ export class Session {
         }
     }
     syncWorkspaceGitObserver(cwd, options) {
-        const normalizedCwd = normalizePersistedWorkspaceId(cwd);
+        const normalizedCwd = resolve(cwd);
         if (!options.isGit) {
             this.removeWorkspaceGitSubscription(normalizedCwd);
             return;
@@ -3634,7 +3796,9 @@ export class Session {
         this.workspaceGitWatchTargets.set(normalizedCwd, target);
         const subscription = this.workspaceGitService.registerWorkspace({ cwd: normalizedCwd }, (snapshot) => {
             this.handleWorkspaceGitBranchSnapshot(normalizedCwd, snapshot.git.currentBranch ?? null);
-            void this.emitWorkspaceUpdateForCwd(normalizedCwd);
+            void this.emitWorkspaceUpdateForCwd(normalizedCwd).catch((error) => {
+                this.sessionLogger.warn({ err: error, cwd: normalizedCwd }, "Failed to emit workspace update after git branch snapshot");
+            });
             this.emitCheckoutStatusUpdate(normalizedCwd, snapshot);
         });
         this.workspaceGitSubscriptions.set(normalizedCwd, subscription.unsubscribe);
@@ -3739,10 +3903,14 @@ export class Session {
             return;
         }
         try {
-            const result = await renameCurrentBranch(cwd, branch);
+            const result = await this.renameCurrentBranch(cwd, branch);
             await this.notifyGitMutation(cwd, "rename-branch", { invalidateGithub: true });
             this.checkoutDiffManager.scheduleRefreshForCwd(cwd);
             this.handleWorkspaceGitBranchSnapshot(cwd, result.currentBranch);
+            // Branch is a git fact derived per-descriptor from each workspace's own
+            // live git snapshot (id → cwd); the reconciliation pass re-persists the
+            // `branch` field per workspace from its own cwd. No cwd → ids fan-out here.
+            // TODO(K10): PR-binding on branch rename is deferred — see plan K10.
             // Push a workspace_update immediately so the sidebar/header reflect
             // the new branch name without waiting for the background git watcher.
             await this.emitWorkspaceUpdateForCwd(cwd);
@@ -4348,18 +4516,19 @@ export class Session {
     async handlePaseoWorktreeArchiveRequest(msg) {
         return handleWorktreeArchiveRequest({
             paseoHome: this.paseoHome,
-            worktreesRoot: this.worktreesRoot,
+            paseoWorktreesBaseRoot: this.worktreesRoot,
             github: this.github,
             workspaceGitService: this.workspaceGitService,
             agentManager: this.agentManager,
             agentStorage: this.agentStorage,
+            findWorkspaceIdForCwd: (cwd) => this.findWorkspaceIdForCwd(cwd),
+            listActiveWorkspaces: () => this.listActiveWorkspaceRefs(),
             archiveWorkspaceRecord: (workspaceId) => this.archiveWorkspaceRecord(workspaceId),
             emit: (message) => this.emit(message),
             emitWorkspaceUpdatesForWorkspaceIds: (workspaceIds) => this.emitWorkspaceUpdatesForWorkspaceIds(workspaceIds),
             markWorkspaceArchiving: (workspaceIds, archivingAt) => this.markWorkspaceArchiving(workspaceIds, archivingAt),
             clearWorkspaceArchiving: (workspaceIds) => this.clearWorkspaceArchiving(workspaceIds),
-            isPathWithinRoot: (rootPath, candidatePath) => this.isPathWithinRoot(rootPath, candidatePath),
-            killTerminalsUnderPath: (rootPath) => this.terminalController.killTerminalsUnderPath(rootPath),
+            killTerminalsForWorkspace: (workspaceId) => this.terminalController.killTerminalsForWorkspace(workspaceId),
             sessionLogger: this.sessionLogger,
         }, msg);
     }
@@ -4569,10 +4738,30 @@ export class Session {
             });
         }
     }
+    async listTerminalActivityContributions() {
+        const terminalManager = this.terminalManager;
+        if (!terminalManager) {
+            return [];
+        }
+        const directories = terminalManager.listDirectories();
+        const terminalsByDirectory = await Promise.all(directories.map((cwd) => terminalManager.getTerminals(cwd)));
+        return terminalsByDirectory.flat().map((session) => {
+            const contribution = {
+                cwd: session.cwd,
+                activity: session.getActivity(),
+            };
+            if (session.workspaceId) {
+                contribution.workspaceId = session.workspaceId;
+            }
+            return contribution;
+        });
+    }
     /**
      * Build the current agent list payload (live + persisted), optionally filtered by labels.
      */
     async listAgentPayloads(filter) {
+        const includeArchived = filter?.includeArchived === true;
+        const labelEntries = filter?.labels ? Object.entries(filter.labels) : [];
         // Get live agents with session modes
         const agentSnapshots = this.agentManager.listAgents();
         const liveAgents = await Promise.all(agentSnapshots.map((agent) => this.buildAgentPayload(agent)));
@@ -4580,18 +4769,23 @@ export class Session {
         // (excluding internal agents which are for ephemeral system tasks)
         const registryRecords = await this.agentStorage.list();
         const liveIds = new Set(agentSnapshots.map((a) => a.id));
-        const registeredProviderIds = this.providerSnapshotManager.listRegisteredProviderIds();
+        const registeredProviderIds = new Set(this.providerSnapshotManager.listRegisteredProviderIds());
         const persistedAgents = registryRecords
             .filter((record) => !liveIds.has(record.id) && !record.internal)
+            // Keep raw-record filters ahead of projection; seeded homes can carry thousands of archived agents.
+            .filter((record) => includeArchived || !record.archivedAt)
+            .filter((record) => labelEntries.every(([key, value]) => record.labels?.[key] === value))
             .filter((record) => filter?.includeUnavailablePersisted === true ||
             isStoredAgentProviderAvailable(record, registeredProviderIds))
             .map((record) => this.buildStoredAgentPayload(record, registeredProviderIds));
         let agents = [...liveAgents, ...persistedAgents];
         agents = agents.filter((agent) => this.isProviderVisibleToClient(agent.provider));
+        if (!includeArchived) {
+            agents = agents.filter((agent) => !agent.archivedAt);
+        }
         // Filter by labels if filter provided
-        if (filter?.labels) {
-            const filterLabels = filter.labels;
-            agents = agents.filter((agent) => Object.entries(filterLabels).every(([key, _value]) => agent.labels[key] === filterLabels[key]));
+        if (labelEntries.length > 0) {
+            agents = agents.filter((agent) => labelEntries.every(([key, value]) => agent.labels[key] === value));
         }
         return agents;
     }
@@ -4653,7 +4847,7 @@ export class Session {
         const payload = this.buildStoredAgentPayload(record);
         return this.isProviderVisibleToClient(payload.provider) ? payload : null;
     }
-    async buildActiveProjectPlacementsByWorkspaceCwd() {
+    async buildActiveProjectPlacementsByWorkspaceId() {
         const [persistedWorkspaces, persistedProjects] = await Promise.all([
             this.workspaceRegistry.list(),
             this.projectRegistry.list(),
@@ -4661,7 +4855,7 @@ export class Session {
         const activeProjects = new Map(persistedProjects
             .filter((project) => !project.archivedAt)
             .map((project) => [project.projectId, project]));
-        const placementsByCwd = new Map();
+        const placementsByWorkspaceId = new Map();
         const pairs = persistedWorkspaces.flatMap((workspace) => {
             if (workspace.archivedAt)
                 return [];
@@ -4672,9 +4866,9 @@ export class Session {
         });
         const placements = await Promise.all(pairs.map(({ workspace, project }) => this.buildProjectPlacementForWorkspace(workspace, project)));
         for (let i = 0; i < pairs.length; i += 1) {
-            placementsByCwd.set(normalizePersistedWorkspaceId(pairs[i].workspace.cwd), placements[i]);
+            placementsByWorkspaceId.set(pairs[i].workspace.workspaceId, placements[i]);
         }
-        return placementsByCwd;
+        return placementsByWorkspaceId;
     }
     async collectFetchAgentsEntries(params) {
         const { candidates, limit, getPlacement, filter } = params;
@@ -4683,7 +4877,7 @@ export class Session {
         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) => {
-                const project = await getPlacement(agent.cwd);
+                const project = await getPlacement(agent.workspaceId);
                 return project ? { agent, project } : null;
             }));
             for (const entry of batchEntries) {
@@ -4714,23 +4908,29 @@ export class Session {
         const sort = this.agentsPager.normalizeSort(request.sort);
         let agents = await this.listAgentPayloads({
             labels: filter?.labels,
+            includeArchived: filter?.includeArchived,
             includeUnavailablePersisted: request.type === "fetch_agent_history_request",
         });
-        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 activePlacementsByWorkspaceId = scope === "active" ? await this.buildActiveProjectPlacementsByWorkspaceId() : null;
+        if (activePlacementsByWorkspaceId) {
+            agents = agents.filter((agent) => !agent.archivedAt &&
+                agent.workspaceId != null &&
+                activePlacementsByWorkspaceId.has(agent.workspaceId));
+        }
+        const placementByWorkspaceId = new Map();
+        const getPlacement = (workspaceId) => {
+            if (!workspaceId) {
+                return Promise.resolve(null);
             }
-            const existing = placementByCwd.get(cwd);
+            if (activePlacementsByWorkspaceId) {
+                return Promise.resolve(activePlacementsByWorkspaceId.get(workspaceId) ?? null);
+            }
+            const existing = placementByWorkspaceId.get(workspaceId);
             if (existing) {
                 return existing;
             }
-            const placementPromise = this.buildProjectPlacementForCwd(cwd);
-            placementByCwd.set(cwd, placementPromise);
+            const placementPromise = this.buildProjectPlacementForWorkspaceId(workspaceId);
+            placementByWorkspaceId.set(workspaceId, placementPromise);
             return placementPromise;
         };
         let candidates = [...agents];
@@ -4790,7 +4990,8 @@ export class Session {
             workspaceDirectory: workspace.cwd,
             projectKind: (resolvedProjectRecord?.kind ?? "directory") === "git" ? "git" : "non_git",
             workspaceKind: workspace.kind,
-            name: workspace.displayName,
+            name: resolveWorkspaceDisplayName(workspace),
+            title: workspace.title,
             archivingAt: null,
             status: "done",
             statusEnteredAt: null,
@@ -4847,7 +5048,7 @@ export class Session {
         const displayName = deriveWorkspaceDisplayName({ cwd: workspace.cwd, checkout });
         return {
             ...base,
-            name: displayName,
+            name: resolveWorkspaceName({ title: workspace.title, derivedDisplayName: displayName }),
             diffStat: snapshot.git.diffStat ?? null,
             gitRuntime: this.buildWorkspaceGitRuntimePayload(snapshot) ?? undefined,
             githubRuntime: this.buildWorkspaceGitHubRuntimePayload(snapshot),
@@ -4866,10 +5067,14 @@ export class Session {
             workspaceDirectory: result.workspace.cwd,
             projectKind: "git",
             workspaceKind: result.workspace.kind,
-            name: result.worktree.branchName || result.workspace.displayName,
+            name: resolveWorkspaceName({
+                title: result.workspace.title,
+                derivedDisplayName: result.worktree.branchName || result.workspace.displayName,
+            }),
+            title: result.workspace.title,
             archivingAt: null,
             status: "done",
-            statusEnteredAt: null,
+            statusEnteredAt: result.workspace.createdAt,
             activityAt: null,
             diffStat: { additions: 0, deletions: 0 },
             scripts: [],
@@ -4900,8 +5105,13 @@ export class Session {
     async buildWorkspaceDescriptorMap(options) {
         return this.workspaceDirectory.buildDescriptorMap(options);
     }
-    resolveRegisteredWorkspaceIdForCwd(cwd, workspaces) {
-        return this.workspaceDirectory.resolveRegisteredWorkspaceIdForCwd(cwd, workspaces);
+    // external path→workspace adapter, not ownership. Used by archive-by-path flows
+    // where the request carries a worktree path (unique to one workspace) rather
+    // than a workspaceId. This is a directory lookup for an archive target, not a
+    // status/ownership attribution.
+    async findWorkspaceIdForCwd(cwd) {
+        const workspaces = await this.workspaceRegistry.list();
+        return resolveWorkspaceIdForPath(cwd, workspaces);
     }
     matchesWorkspaceFilter(input) {
         return this.workspaceDirectory.matchesFilter(input);
@@ -4969,7 +5179,7 @@ export class Session {
         }
     }
     async findOrCreateWorkspaceForDirectory(cwd) {
-        const inputCwd = normalizePersistedWorkspaceId(cwd);
+        const inputCwd = resolve(cwd);
         const normalizedCwd = await this.resolveWorkspaceDirectory(cwd);
         const existingWorkspace = await this.findExactWorkspaceByDirectory(normalizedCwd, {
             refreshGit: false,
@@ -4977,22 +5187,26 @@ export class Session {
         if (existingWorkspace) {
             if (existingWorkspace.archivedAt && inputCwd !== normalizedCwd) {
                 const timestamp = new Date().toISOString();
-                const displayName = basename(inputCwd) || inputCwd;
-                const projectRecord = createPersistedProjectRecord({
-                    projectId: inputCwd,
-                    rootPath: inputCwd,
-                    kind: "non_git",
-                    displayName,
-                    createdAt: timestamp,
-                    updatedAt: timestamp,
+                const checkout = checkoutLiteFromGitSnapshot(inputCwd, {
+                    isGit: false,
+                    currentBranch: null,
+                    remoteUrl: null,
+                    repoRoot: null,
+                    isPaseoOwnedWorktree: false,
+                    mainRepoRoot: null,
+                });
+                const membership = classifyDirectoryForProjectMembership({ cwd: inputCwd, checkout });
+                const projectRecord = await this.resolveProjectRecordForPlacement({
+                    membership,
+                    timestamp,
                 });
                 await this.projectRegistry.upsert(projectRecord);
                 const workspaceRecord = createPersistedWorkspaceRecord({
-                    workspaceId: inputCwd,
+                    workspaceId: generateWorkspaceId(),
                     projectId: projectRecord.projectId,
                     cwd: inputCwd,
-                    kind: "directory",
-                    displayName,
+                    kind: membership.workspaceKind,
+                    displayName: membership.workspaceDisplayName,
                     createdAt: timestamp,
                     updatedAt: timestamp,
                 });
@@ -5017,7 +5231,7 @@ export class Session {
         });
         await this.projectRegistry.upsert(projectRecord);
         const workspaceRecord = createPersistedWorkspaceRecord({
-            workspaceId: membership.workspaceId,
+            workspaceId: generateWorkspaceId(),
             projectId: projectRecord.projectId,
             cwd,
             kind: membership.workspaceKind,
@@ -5039,8 +5253,7 @@ export class Session {
         const projectId = projectRecord.projectId;
         const kind = membership.workspaceKind;
         const displayName = membership.workspaceDisplayName;
-        if (input.workspace.workspaceId === membership.workspaceId &&
-            input.workspace.projectId === projectId &&
+        if (input.workspace.projectId === projectId &&
             input.workspace.kind === kind &&
             input.workspace.displayName === displayName) {
             return this.ensureWorkspaceRecordUnarchived(input.workspace);
@@ -5048,7 +5261,7 @@ export class Session {
         await this.projectRegistry.upsert(projectRecord);
         const nextWorkspace = {
             ...input.workspace,
-            workspaceId: membership.workspaceId,
+            workspaceId: input.workspace.workspaceId,
             projectId,
             cwd: input.cwd,
             kind,
@@ -5122,16 +5335,28 @@ export class Session {
         });
         return result;
     }
+    async listActiveWorkspaceRefs() {
+        const workspaces = await this.workspaceRegistry.list();
+        return workspaces
+            .filter((workspace) => !workspace.archivedAt)
+            .map((workspace) => ({
+            workspaceId: workspace.workspaceId,
+            cwd: workspace.cwd,
+            kind: workspace.kind,
+        }));
+    }
     async archiveWorkspaceRecord(workspaceId, archivedAt) {
         const archiveTimestamp = archivedAt ?? new Date().toISOString();
         const existingWorkspace = await archivePersistedWorkspaceRecord({
             workspaceId,
             archivedAt: archiveTimestamp,
             workspaceRegistry: this.workspaceRegistry,
-            projectRegistry: this.projectRegistry,
         });
         if (!existingWorkspace) {
-            this.removeWorkspaceGitSubscription(workspaceId);
+            const watchTarget = this.resolveWorkspaceGitWatchTarget(workspaceId);
+            if (watchTarget) {
+                this.removeWorkspaceGitSubscription(watchTarget.cwd);
+            }
             return;
         }
         if (!existingWorkspace.archivedAt) {
@@ -5144,9 +5369,18 @@ export class Session {
                 archivedAt: archiveTimestamp,
             }, "Workspace archived");
         }
-        await this.removeWorkspaceGitWatchTarget(existingWorkspace.cwd);
-        this.scriptRuntimeStore?.removeForWorkspace(existingWorkspace.cwd);
-        this.removeWorkspaceGitSubscription(workspaceId);
+        await this.teardownArchivedWorkspace({
+            workspaceId: existingWorkspace.workspaceId,
+            cwd: existingWorkspace.cwd,
+        });
+    }
+    // Git watch and subscription state is keyed by directory; the script runtime
+    // store is keyed by the opaque workspace id. Each cleanup uses its own key so an
+    // opaque id is never resolved as a filesystem path.
+    async teardownArchivedWorkspace(input) {
+        await this.removeWorkspaceGitWatchTarget(input.cwd);
+        this.scriptRuntimeStore?.removeForWorkspace(input.workspaceId);
+        this.removeWorkspaceGitSubscription(input.cwd);
     }
     async reconcileAndEmitWorkspaceUpdates() {
         if (!this.workspaceUpdatesSubscription) {
@@ -5178,9 +5412,10 @@ export class Session {
         await Promise.all(result.changesApplied.map(async (change) => {
             switch (change.kind) {
                 case "workspace_archived":
-                    await this.removeWorkspaceGitWatchTarget(change.directory);
-                    this.scriptRuntimeStore?.removeForWorkspace(change.directory);
-                    this.removeWorkspaceGitSubscription(change.workspaceId);
+                    await this.teardownArchivedWorkspace({
+                        workspaceId: change.workspaceId,
+                        cwd: change.directory,
+                    });
                     changedWorkspaceIds.add(change.workspaceId);
                     break;
                 case "workspace_updated":
@@ -5223,7 +5458,7 @@ export class Session {
                 this.shouldSkipWorkspaceGitWatchUpdate(workspaceId, nextWorkspace)) {
                 continue;
             }
-            const watchTarget = this.workspaceGitWatchTargets.get(workspaceId);
+            const watchTarget = this.resolveWorkspaceGitWatchTarget(workspaceId);
             if (watchTarget && this.onBranchChanged) {
                 const newBranchName = nextWorkspace?.name ?? null;
                 if (newBranchName !== watchTarget.lastBranchName) {
@@ -5236,6 +5471,7 @@ export class Session {
                 this.bufferOrEmitWorkspaceUpdate(subscription, {
                     kind: "remove",
                     id: workspaceId,
+                    ...(await this.resolveEmptyProjectForArchivedWorkspace(workspaceId)),
                 });
                 continue;
             }
@@ -5255,10 +5491,38 @@ export class Session {
             void this.reconcileAndEmitWorkspaceUpdates();
         }
     }
+    // When a workspace is archived its project may become empty. Resolve the
+    // now-empty project parent so the `remove` update can carry it, keeping the
+    // sidebar's empty project row in sync without a full re-hydration.
+    async resolveEmptyProjectForArchivedWorkspace(workspaceId) {
+        const archivedWorkspace = await this.workspaceRegistry.get(workspaceId);
+        if (!archivedWorkspace) {
+            return null;
+        }
+        const emptyProject = (await this.workspaceDirectory.listEmptyProjects()).find((project) => project.projectId === archivedWorkspace.projectId);
+        return emptyProject ? { emptyProject } : null;
+    }
+    async emitWorkspaceUpdateForTerminalContribution(event) {
+        // A terminal's activity contributes only to the workspace it carries. A
+        // terminal with no workspaceId attributes to nothing — status is per-id.
+        if (!event.workspaceId) {
+            return;
+        }
+        await this.emitWorkspaceUpdatesForWorkspaceIds([event.workspaceId], {
+            skipReconcile: true,
+        });
+    }
+    // A git fact (branch, diff, dirty, PR) changed at `cwd`. Every workspace whose
+    // OWN cwd is this folder re-derives its git facts from that folder (id → cwd)
+    // and emits its own per-id descriptor. This is a deliberate same-folder fan,
+    // not a cwd → id ownership lookup: git never resolves which workspace owns a
+    // path. See `workspaceIdsOnCheckout`.
     async emitWorkspaceUpdateForCwd(cwd, options) {
-        const workspaces = await this.workspaceRegistry.list();
-        const workspaceId = this.resolveRegisteredWorkspaceIdForCwd(cwd, workspaces);
-        await this.emitWorkspaceUpdatesForWorkspaceIds([workspaceId], options);
+        const workspaceIds = workspaceIdsOnCheckout(await this.workspaceRegistry.list(), cwd);
+        if (workspaceIds.length === 0) {
+            return;
+        }
+        await this.emitWorkspaceUpdatesForWorkspaceIds(workspaceIds, options);
     }
     async handleFetchAgents(request) {
         const requestedSubscriptionId = request.subscribe?.subscriptionId?.trim();
@@ -5450,16 +5714,162 @@ export class Session {
         }
         return { snapshotByWorkspaceId };
     }
-    async registerWorkspaceForImportedAgent(cwd) {
+    async registerWorkspaceForImportedAgent(workspace) {
         try {
-            const workspace = await this.findOrCreateWorkspaceForDirectory(cwd);
             await this.syncWorkspaceGitObserverForWorkspace(workspace);
             await this.describeWorkspaceRecord(workspace);
-            await this.emitWorkspaceUpdateForCwd(workspace.cwd);
+            await this.emitWorkspaceUpdateForWorkspaceId(workspace.workspaceId);
         }
         catch (error) {
-            this.sessionLogger.warn({ err: error, cwd }, "Failed to register workspace for imported agent");
+            this.sessionLogger.warn({ err: error, workspaceId: workspace.workspaceId, cwd: workspace.cwd }, "Failed to register workspace for imported agent");
+        }
+    }
+    async handleWorkspaceCreateRequest(request) {
+        try {
+            if (request.source.kind === "directory") {
+                await this.handleWorkspaceCreateLocal(request);
+                return;
+            }
+            await this.handleWorkspaceCreateWorktree(request);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Failed to create workspace";
+            this.sessionLogger.error({ err: error, sourceKind: request.source.kind, requestId: request.requestId }, "Failed to create workspace");
+            this.emit({
+                type: "workspace.create.response",
+                payload: {
+                    requestId: request.requestId,
+                    workspace: null,
+                    setupTerminalId: null,
+                    error: message,
+                },
+            });
+        }
+    }
+    async handleWorkspaceCreateLocal(request) {
+        if (request.source.kind !== "directory") {
+            return;
+        }
+        const cwd = expandTilde(request.source.path);
+        const directoryExists = await this.filesystem.isDirectory(cwd).catch(() => false);
+        if (!directoryExists) {
+            this.emit({
+                type: "workspace.create.response",
+                payload: {
+                    requestId: request.requestId,
+                    workspace: null,
+                    setupTerminalId: null,
+                    error: `Directory not found: ${cwd}`,
+                    errorCode: "directory_not_found",
+                },
+            });
+            return;
+        }
+        const workspace = await createLocalCheckoutWorkspace({ cwd, title: request.title ?? null }, {
+            projectRegistry: this.projectRegistry,
+            workspaceRegistry: this.workspaceRegistry,
+            workspaceGitService: this.workspaceGitService,
+        });
+        await this.syncWorkspaceGitObserverForWorkspace(workspace);
+        const descriptor = await this.describeWorkspaceRecord(workspace);
+        this.emit({
+            type: "workspace.create.response",
+            payload: {
+                requestId: request.requestId,
+                workspace: descriptor,
+                setupTerminalId: null,
+                error: null,
+            },
+        });
+        await this.emitWorkspaceUpdateForWorkspaceId(workspace.workspaceId);
+        void this.workspaceGitService
+            .getSnapshot(workspace.cwd, { force: true, includeGitHub: true, reason: "open_project" })
+            .catch((error) => {
+            this.sessionLogger.warn({ err: error, cwd: workspace.cwd }, "Background snapshot refresh failed after workspace.create");
+        });
+        if (request.firstAgentContext) {
+            const firstAgentContext = request.firstAgentContext;
+            this.scheduleWorkspaceNaming(() => this.maybeAutoNameDirectoryWorkspaceTitle({
+                workspaceId: workspace.workspaceId,
+                cwd: workspace.cwd,
+                firstAgentContext,
+            }), { cwd: workspace.cwd, message: "Failed to auto-name directory workspace title" });
+        }
+    }
+    // Schedules a background workspace-naming write off the request path. The
+    // setTimeout(0) keeps the LLM call off the hot path.
+    scheduleWorkspaceNaming(run, context) {
+        setTimeout(() => {
+            void run().catch((error) => {
+                this.sessionLogger.warn({ err: error, cwd: context.cwd }, context.message);
+            });
+        }, 0);
+    }
+    async handleWorkspaceCreateWorktree(request) {
+        if (request.source.kind !== "worktree") {
+            return;
+        }
+        const source = request.source;
+        if (!source.cwd && !source.projectId) {
+            this.emit({
+                type: "workspace.create.response",
+                payload: {
+                    requestId: request.requestId,
+                    workspace: null,
+                    setupTerminalId: null,
+                    error: "cwd or projectId is required for a worktree-backed workspace",
+                    errorCode: "source_required",
+                },
+            });
+            return;
+        }
+        const sourceCwd = await this.resolveWorktreeSourceCwd({
+            cwd: source.cwd,
+            projectId: source.projectId,
+        });
+        const result = await this.createPaseoWorktreeWorkflow({
+            cwd: sourceCwd,
+            projectId: source.projectId,
+            worktreeSlug: source.worktreeSlug,
+            action: source.action,
+            refName: source.refName,
+            githubPrNumber: source.githubPrNumber,
+            firstAgentContext: request.firstAgentContext,
+        }, source.baseBranch
+            ? { resolveDefaultBranch: async () => source.baseBranch }
+            : undefined);
+        if (request.title?.trim()) {
+            await this.workspaceRegistry.upsert({
+                ...result.workspace,
+                title: request.title.trim(),
+                updatedAt: new Date().toISOString(),
+            });
+            result.workspace.title = request.title.trim();
         }
+        const descriptor = await this.describeCreatedWorktreeWorkspace(result);
+        this.emit({
+            type: "workspace.create.response",
+            payload: {
+                requestId: request.requestId,
+                workspace: descriptor,
+                setupTerminalId: null,
+                error: null,
+            },
+        });
+        this.emit({
+            type: "workspace_update",
+            payload: { kind: "upsert", workspace: descriptor },
+        });
+    }
+    async resolveWorktreeSourceCwd(input) {
+        if (input.cwd) {
+            return expandTilde(input.cwd);
+        }
+        const project = await this.projectRegistry.get(input.projectId);
+        if (!project || project.archivedAt) {
+            throw new Error(`Project not found: ${input.projectId}`);
+        }
+        return project.rootPath;
     }
     async handleOpenProjectRequest(request) {
         const requestedCwd = request.cwd;
@@ -5491,7 +5901,7 @@ export class Session {
             const project = await this.projectRegistry.get(workspace.projectId);
             await this.syncWorkspaceGitObserverForWorkspace(workspace);
             const descriptor = await this.describeWorkspaceRecord(workspace);
-            await this.emitWorkspaceUpdateForCwd(workspace.cwd);
+            await this.emitWorkspaceUpdateForWorkspaceId(workspace.workspaceId);
             this.sessionLogger.info({
                 requestedCwd,
                 resolvedCwd: cwd,
@@ -5664,7 +6074,7 @@ export class Session {
             createPaseoWorktree: (workflowInput, serviceOptions) => this.createPaseoWorktree(workflowInput, serviceOptions),
             warmWorkspaceGitData: (workspace) => this.warmWorkspaceGitDataForWorkspace(workspace),
             autoNameWorkspaceBranchForFirstAgent: (autoNameInput) => this.scheduleAutoNameWorkspaceBranchForFirstAgent(autoNameInput),
-            emitWorkspaceUpdateForCwd: (cwd, emitOptions) => this.emitWorkspaceUpdateForCwd(cwd, emitOptions),
+            emitWorkspaceUpdateForWorkspaceId: (workspaceId) => this.emitWorkspaceUpdateForWorkspaceId(workspaceId),
             cacheWorkspaceSetupSnapshot: (workspaceId, snapshot) => {
                 this.workspaceSetupSnapshots.set(workspaceId, snapshot);
             },
@@ -5694,12 +6104,33 @@ export class Session {
             if (!existing) {
                 throw new Error(`Workspace not found: ${request.workspaceId}`);
             }
-            if (existing.kind === "worktree") {
-                throw new Error("Use worktree archive for Paseo worktrees");
-            }
-            const archivedAt = new Date().toISOString();
-            await this.archiveWorkspaceRecord(existing.workspaceId, archivedAt);
-            await this.emitWorkspaceUpdateForCwd(existing.cwd);
+            const gitSnapshot = await this.workspaceGitService
+                .getSnapshot(existing.cwd)
+                .catch(() => null);
+            const repoRoot = gitSnapshot?.git?.repoRoot ?? null;
+            await archiveByScope({
+                paseoHome: this.paseoHome,
+                paseoWorktreesBaseRoot: this.worktreesRoot,
+                github: this.github,
+                workspaceGitService: this.workspaceGitService,
+                agentManager: this.agentManager,
+                agentStorage: this.agentStorage,
+                findWorkspaceIdForCwd: (cwd) => this.findWorkspaceIdForCwd(cwd),
+                listActiveWorkspaces: () => this.listActiveWorkspaceRefs(),
+                archiveWorkspaceRecord: (workspaceId) => this.archiveWorkspaceRecord(workspaceId),
+                emitWorkspaceUpdatesForWorkspaceIds: (workspaceIds) => this.emitWorkspaceUpdatesForWorkspaceIds(workspaceIds),
+                markWorkspaceArchiving: (workspaceIds, archivingAt) => this.markWorkspaceArchiving(workspaceIds, archivingAt),
+                clearWorkspaceArchiving: (workspaceIds) => this.clearWorkspaceArchiving(workspaceIds),
+                killTerminalsForWorkspace: (workspaceId) => this.terminalController.killTerminalsForWorkspace(workspaceId),
+                sessionLogger: this.sessionLogger,
+            }, {
+                scope: { kind: "workspace", workspaceId: existing.workspaceId },
+                repoRoot,
+                paseoWorktreesBaseRoot: this.worktreesRoot,
+                requestId: request.requestId,
+            });
+            const archivedWorkspace = await this.workspaceRegistry.get(request.workspaceId);
+            const archivedAt = archivedWorkspace?.archivedAt ?? new Date().toISOString();
             this.emit({
                 type: "archive_workspace_response",
                 payload: {
@@ -5760,10 +6191,12 @@ export class Session {
                 if (!workspace || workspace.archivedAt) {
                     throw new Error(`Workspace not found: ${requestedWorkspaceId}`);
                 }
-                const workspaceCwd = normalizePersistedWorkspaceId(workspace.cwd);
+                // Clearing attention is scoped to the workspace that OWNS the agent, by
+                // workspaceId — never by comparing cwd strings. A sibling workspace
+                // sharing the same directory keeps its own agents' attention.
                 const clearableAgentIds = agents
                     .filter((agent) => !agent.archivedAt)
-                    .filter((agent) => normalizePersistedWorkspaceId(agent.cwd) === workspaceCwd)
+                    .filter((agent) => agent.workspaceId === workspace.workspaceId)
                     .filter((agent) => agent.requiresAttention === true)
                     .filter((agent) => (agent.pendingPermissions?.length ?? 0) === 0)
                     .filter((agent) => agent.attentionReason !== "permission")
@@ -5791,7 +6224,7 @@ export class Session {
                     };
                     await this.agentStorage.upsert(nextRecord);
                     const agent = this.buildStoredAgentPayload(nextRecord);
-                    const project = await this.buildProjectPlacementForCwd(agent.cwd);
+                    const project = await this.buildProjectPlacementForWorkspace(workspace);
                     this.emit({
                         type: "agent_update",
                         payload: {
@@ -5862,7 +6295,9 @@ export class Session {
             });
             return;
         }
-        const project = await this.buildProjectPlacementForCwd(agent.cwd);
+        const project = agent.workspaceId
+            ? await this.buildProjectPlacementForWorkspaceId(agent.workspaceId)
+            : null;
         this.emit({
             type: "fetch_agent_response",
             payload: { requestId, agent, project, error: null },
@@ -6651,10 +7086,15 @@ export class Session {
      * Emit a message to the client
      */
     emit(msg) {
-        this.sessionLogger.trace({
-            messageType: msg.type,
-            payloadBytes: JSON.stringify(msg).length,
-        }, "agent.session.outbound");
+        // JSON.stringify(msg) is only computed when trace is enabled — it runs for
+        // every outbound message otherwise, and trace is disabled by default.
+        // Optional-chained because test logger stubs don't implement isLevelEnabled.
+        if (this.sessionLogger.isLevelEnabled?.("trace")) {
+            this.sessionLogger.trace({
+                messageType: msg.type,
+                payloadBytes: JSON.stringify(msg).length,
+            }, "agent.session.outbound");
+        }
         if (msg.type === "audio_output" &&
             (process.env.TTS_DEBUG_AUDIO_DIR || isPaseoDictationDebugEnabled()) &&
             msg.payload.groupId &&
@@ -6714,6 +7154,10 @@ export class Session {
             this.unsubscribeAgentEvents();
             this.unsubscribeAgentEvents = null;
         }
+        if (this.unsubscribeTerminalWorkspaceContributionEvents) {
+            this.unsubscribeTerminalWorkspaceContributionEvents();
+            this.unsubscribeTerminalWorkspaceContributionEvents = null;
+        }
         if (this.unsubscribeProviderSnapshotEvents) {
             this.unsubscribeProviderSnapshotEvents();
             this.unsubscribeProviderSnapshotEvents = null;