@getpaseo/server 0.1.97-beta.3 → 0.1.98

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 { resolve, sep } from "path";
+import { basename, normalize, resolve, sep } from "path";
 import { homedir } from "node:os";
 import { z } from "zod";
 import { CLIENT_CAPS } from "@getpaseo/protocol/client-capabilities";
@@ -32,9 +32,10 @@ import { deriveProjectSlug } from "./workspace-git-metadata.js";
 import { spawnWorkspaceScript } from "./worktree-bootstrap.js";
 import { getErrorMessage, getErrorMessageOr } from "@getpaseo/protocol/error-utils";
 import { getAgentStatusPriority } from "@getpaseo/protocol/agent-state-bucket";
+import { getParentAgentIdFromLabels } from "@getpaseo/protocol/agent-labels";
 import { resolveSnapshotCwd } from "./agent/provider-snapshot-manager.js";
 import { createAgentCommand } from "./agent/create-agent/create.js";
-import { archiveAgentCommand, cancelAgentRunCommand, closeAgentCommand, setAgentModeCommand, updateAgentCommand, } from "./agent/lifecycle-command.js";
+import { archiveAgentCommand, cancelAgentRunCommand, closeAgentCommand, detachAgentCommand, setAgentModeCommand, updateAgentCommand, } from "./agent/lifecycle-command.js";
 import { buildStoredAgentPayload, resolveEffectiveThinkingOptionId, resolveStoredAgentPayloadUpdatedAt, toAgentPayload, } from "./agent/agent-projections.js";
 import { appendTimelineItemIfAgentKnown, emitLiveTimelineItemIfAgentKnown, } from "./agent/timeline-append.js";
 import { projectTimelineRows, selectProjectedTimelinePage, } from "./agent/timeline-projection.js";
@@ -50,7 +51,7 @@ import { isVoicePermissionAllowed } from "./voice-permission-policy.js";
 import { listDirectoryEntries, readExplorerFile, readExplorerFileBytes, getDownloadableFileInfo, } from "./file-explorer/service.js";
 import { readPaseoConfigForEdit, writePaseoConfigForEdit, } from "../utils/paseo-config-file.js";
 import { buildMetadataPrompt } from "../utils/build-metadata-prompt.js";
-import { archivePersistedWorkspaceRecord } from "./workspace-archive-service.js";
+import { archivePersistedWorkspaceRecord, archiveWorkspaceContents, } from "./workspace-archive-service.js";
 import { WorkspaceReconciliationService } from "./workspace-reconciliation-service.js";
 import { checkoutResolvedBranch, commitChanges, mergeToBase, mergeFromBase, pullCurrentBranch, pushCurrentBranch, createPullRequest, renameCurrentBranch as renameCurrentBranchDefault, } from "../utils/checkout-git.js";
 import { validateBranchSlug } from "@getpaseo/protocol/branch-slug";
@@ -70,7 +71,9 @@ import { attemptFirstAgentBranchAutoName, createLocalCheckoutWorkspace, createPa
 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 { WorktreeRequestError, toWorktreeRequestError, toWorktreeWireError, } from "./worktree-errors.js";
+import { createWorktree } from "../utils/worktree.js";
+import { runGitCommand } from "../utils/run-git-command.js";
 import { CreateAgentLifecycleDispatch } from "./agent/create-agent-lifecycle-dispatch.js";
 const WORKSPACE_GIT_WATCH_REMOVED_STATE_KEY = "__removed__";
 async function resolveKnownProjectRootForConfig(input) {
@@ -223,7 +226,7 @@ const PCM_BITS_PER_SAMPLE = 16;
 const PCM_BYTES_PER_MS = (PCM_SAMPLE_RATE * PCM_CHANNELS * (PCM_BITS_PER_SAMPLE / 8)) / 1000;
 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 AgentIdSchema = z.guid();
 const nodeSessionFileSystem = {
     async isDirectory(path) {
         const stats = await stat(path).catch(() => null);
@@ -340,7 +343,7 @@ export class Session {
                 }
             },
         });
-        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;
+        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, providerUsageService, 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);
@@ -382,12 +385,7 @@ export class Session {
             hasBinaryChannel: () => this.onBinaryMessage !== null,
             isPathWithinRoot: (rootPath, candidatePath) => this.isPathWithinRoot(rootPath, candidatePath),
             sessionLogger: this.sessionLogger,
-            listTerminalWorkspaceRoots: async () => {
-                const workspaces = await this.workspaceRegistry.list();
-                return workspaces
-                    .filter((workspace) => !workspace.archivedAt)
-                    .map((workspace) => workspace.cwd);
-            },
+            listTerminalWorkspaceRefs: () => this.listActiveWorkspaceRefs(),
             clientSupportsWrapReflow: () => this.clientCapabilities.has(CLIENT_CAPS.terminalReflowableSnapshot),
             getClientBufferedAmount: () => this.getTransportBufferedAmount(),
         });
@@ -419,6 +417,7 @@ export class Session {
             logger: this.sessionLogger,
         });
         this.providerSnapshotManager = providerSnapshotManager;
+        this.providerUsageService = providerUsageService;
         this.serviceProxy = serviceProxy ?? null;
         this.scriptRuntimeStore = scriptRuntimeStore ?? null;
         this.workspaceSetupSnapshots = workspaceSetupSnapshots ?? new Map();
@@ -863,6 +862,39 @@ export class Session {
             payload,
         });
     }
+    async emitStoredAgentUpdate(record) {
+        const payload = this.buildStoredAgentPayload(record);
+        const subscription = this.agentUpdatesSubscription;
+        if (!subscription) {
+            return payload;
+        }
+        const project = payload.workspaceId
+            ? await this.buildProjectPlacementForWorkspaceId(payload.workspaceId)
+            : null;
+        if (!project) {
+            this.bufferOrEmitAgentUpdate(subscription, {
+                kind: "remove",
+                agentId: payload.id,
+            });
+            return payload;
+        }
+        const matches = this.matchesAgentFilter({
+            agent: payload,
+            project,
+            filter: subscription.filter,
+        });
+        this.bufferOrEmitAgentUpdate(subscription, matches
+            ? {
+                kind: "upsert",
+                agent: payload,
+                project,
+            }
+            : {
+                kind: "remove",
+                agentId: payload.id,
+            });
+        return payload;
+    }
     flushBootstrappedAgentUpdates(options) {
         const subscription = this.agentUpdatesSubscription;
         if (!subscription || !subscription.isBootstrapping) {
@@ -911,6 +943,7 @@ export class Session {
         return {
             projectKey: project.projectId,
             projectName: resolveProjectDisplayName(project),
+            workspaceName: resolveWorkspaceDisplayName(workspace),
             checkout,
         };
     }
@@ -920,6 +953,15 @@ export class Session {
             return null;
         return this.buildProjectPlacementForWorkspace(workspace);
     }
+    async buildProjectPlacementForExistingWorkspaceProject(workspaceId) {
+        const workspace = await this.workspaceRegistry.get(workspaceId);
+        if (!workspace)
+            return null;
+        const project = await this.projectRegistry.get(workspace.projectId);
+        if (!project)
+            return null;
+        return this.buildProjectPlacementForWorkspace(workspace, project);
+    }
     async forwardAgentUpdate(agent) {
         try {
             const subscription = this.agentUpdatesSubscription;
@@ -1019,6 +1061,7 @@ export class Session {
     async dispatchInboundMessage(msg) {
         const promise = this.dispatchVoiceAndControlMessage(msg) ??
             this.dispatchAgentRewindMessage(msg) ??
+            this.dispatchAgentRelationshipMessage(msg) ??
             this.dispatchAgentLifecycleMessage(msg) ??
             this.dispatchAgentConfigMessage(msg) ??
             this.dispatchCheckoutMessage(msg) ??
@@ -1087,6 +1130,14 @@ export class Session {
                 return undefined;
         }
     }
+    dispatchAgentRelationshipMessage(msg) {
+        switch (msg.type) {
+            case "agent.detach.request":
+                return this.handleDetachAgentRequest(msg.agentId, msg.requestId);
+            default:
+                return undefined;
+        }
+    }
     async handleDictationStreamStart(msg) {
         const unavailable = this.resolveVoiceFeatureUnavailableContext("dictation");
         if (unavailable) {
@@ -1343,8 +1394,12 @@ export class Session {
                 return this.handleLegacyOpenInEditorRequest(msg);
             case "open_project_request":
                 return this.handleOpenProjectRequest(msg);
+            case "project.add.request":
+                return this.handleProjectAddRequest(msg);
             case "archive_workspace_request":
                 return this.handleArchiveWorkspaceRequest(msg);
+            case "project.remove.request":
+                return this.handleProjectRemoveRequest(msg);
             case "workspace.create.request":
                 return this.handleWorkspaceCreateRequest(msg);
             case "workspace.clear_attention.request":
@@ -1380,6 +1435,8 @@ export class Session {
                 return this.handleRefreshProvidersSnapshotRequest(msg);
             case "provider_diagnostic_request":
                 return this.handleProviderDiagnosticRequest(msg);
+            case "provider.usage.list.request":
+                return this.handleProviderUsageListRequest(msg);
             default:
                 return undefined;
         }
@@ -1571,39 +1628,60 @@ export class Session {
             logger: this.sessionLogger,
         }, agentId);
         if (this.agentUpdatesSubscription) {
-            const payload = this.buildStoredAgentPayload(archivedRecord);
-            const project = payload.workspaceId
-                ? await this.buildProjectPlacementForWorkspaceId(payload.workspaceId)
-                : null;
-            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,
-                });
-            }
+            const payload = await this.emitStoredAgentUpdate(archivedRecord);
             if (payload.workspaceId) {
                 await this.emitWorkspaceUpdateForWorkspaceId(payload.workspaceId);
             }
         }
         return { agentId, archivedAt };
     }
+    async handleDetachAgentRequest(agentId, requestId) {
+        this.sessionLogger.info({ agentId, requestId }, "Detaching agent from parent");
+        try {
+            const result = await detachAgentCommand({ agentManager: this.agentManager }, agentId);
+            const affectedWorkspaceIds = new Set();
+            if (!result.live) {
+                const payload = await this.emitStoredAgentUpdate(result.record);
+                if (payload.workspaceId) {
+                    affectedWorkspaceIds.add(payload.workspaceId);
+                }
+            }
+            else if (result.record.workspaceId) {
+                affectedWorkspaceIds.add(result.record.workspaceId);
+            }
+            if (result.previousParentAgentId) {
+                const rootWorkspaceId = await this.resolveDelegationRootWorkspaceId(result.previousParentAgentId);
+                if (rootWorkspaceId) {
+                    affectedWorkspaceIds.add(rootWorkspaceId);
+                }
+            }
+            await this.emitWorkspaceUpdatesForWorkspaceIds(affectedWorkspaceIds, {
+                skipReconcile: true,
+            });
+            this.emit({
+                type: "agent.detach.response",
+                payload: {
+                    requestId,
+                    agentId,
+                    accepted: true,
+                    error: null,
+                },
+            });
+        }
+        catch (error) {
+            const message = getErrorMessageOr(error, "Failed to detach agent");
+            this.sessionLogger.error({ err: error, agentId, requestId }, "Failed to detach agent");
+            this.emit({
+                type: "agent.detach.response",
+                payload: {
+                    requestId,
+                    agentId,
+                    accepted: false,
+                    error: message,
+                },
+            });
+        }
+    }
     async handleCloseItemsRequest(msg) {
         const archiveResults = await Promise.allSettled(msg.agentIds.map((agentId) => this.archiveAgentForClose(agentId)));
         const agents = [];
@@ -1764,6 +1842,80 @@ export class Session {
             });
         }
     }
+    async handleProjectRemoveRequest(request) {
+        const { projectId, requestId } = request;
+        this.sessionLogger.info({ projectId, requestId }, "session: project.remove.request");
+        try {
+            const projectWorkspaces = (await this.workspaceRegistry.list()).filter((workspace) => workspace.projectId === projectId);
+            const activeWorkspaceIds = projectWorkspaces
+                .filter((workspace) => !workspace.archivedAt)
+                .map((workspace) => workspace.workspaceId);
+            if (activeWorkspaceIds.length > 0) {
+                this.markWorkspaceArchiving(activeWorkspaceIds, new Date().toISOString());
+                await this.emitWorkspaceUpdatesForWorkspaceIds(activeWorkspaceIds, {
+                    skipReconcile: true,
+                });
+            }
+            const removedWorkspaceIds = [];
+            try {
+                for (const workspaceId of activeWorkspaceIds) {
+                    await archiveWorkspaceContents({
+                        agentManager: this.agentManager,
+                        agentStorage: this.agentStorage,
+                        killTerminalsForWorkspace: (id) => this.terminalController.killTerminalsForWorkspace(id),
+                        sessionLogger: this.sessionLogger,
+                    }, workspaceId);
+                    await this.archiveWorkspaceRecord(workspaceId);
+                    removedWorkspaceIds.push(workspaceId);
+                }
+                await this.projectRegistry.remove(projectId);
+            }
+            finally {
+                if (activeWorkspaceIds.length > 0) {
+                    this.clearWorkspaceArchiving(activeWorkspaceIds);
+                }
+            }
+            const updateIds = removedWorkspaceIds.length > 0
+                ? removedWorkspaceIds
+                : [projectWorkspaces[0]?.workspaceId ?? projectId];
+            await this.emitWorkspaceUpdatesForWorkspaceIds(updateIds, {
+                skipReconcile: true,
+                removedProjectId: projectId,
+            });
+            this.emit({
+                type: "project.remove.response",
+                payload: {
+                    requestId,
+                    projectId,
+                    accepted: true,
+                    removedWorkspaceIds,
+                    error: null,
+                },
+            });
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, projectId, requestId }, "session: project.remove.request error");
+            this.emit({
+                type: "activity_log",
+                payload: {
+                    id: uuidv4(),
+                    timestamp: new Date(),
+                    type: "error",
+                    content: `Failed to remove project: ${getErrorMessage(error)}`,
+                },
+            });
+            this.emit({
+                type: "project.remove.response",
+                payload: {
+                    requestId,
+                    projectId,
+                    accepted: false,
+                    removedWorkspaceIds: [],
+                    error: getErrorMessageOr(error, "Failed to remove project"),
+                },
+            });
+        }
+    }
     async handleWorkspaceTitleSetRequest(workspaceId, title, requestId) {
         this.sessionLogger.info({ workspaceId, requestId, hasTitle: typeof title === "string" }, "session: workspace.title.set.request");
         try {
@@ -2412,6 +2564,7 @@ export class Session {
         this.sessionLogger.info({ agentId }, `Refreshing agent ${agentId} from persistence`);
         try {
             await unarchiveAgentState(this.agentStorage, this.agentManager, agentId);
+            await this.unarchiveOwningWorkspaceForAgent(agentId);
             let snapshot;
             const existing = this.agentManager.getAgent(agentId);
             if (existing) {
@@ -2460,7 +2613,7 @@ export class Session {
                         requestId,
                         requestType: msg.type,
                         error: message,
-                        code: "agent_refresh_failed",
+                        code: error instanceof WorktreeRequestError ? error.code : "agent_refresh_failed",
                     },
                 });
             }
@@ -2991,6 +3144,32 @@ export class Session {
             });
         }
     }
+    async handleProviderUsageListRequest(msg) {
+        try {
+            const usage = await this.providerUsageService.listUsage();
+            this.emit({
+                type: "provider.usage.list.response",
+                payload: {
+                    requestId: msg.requestId,
+                    fetchedAt: usage.fetchedAt,
+                    providers: usage.providers,
+                },
+            });
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            this.sessionLogger.error({ err }, "Failed to list provider usage");
+            this.emit({
+                type: "rpc_error",
+                payload: {
+                    requestId: msg.requestId,
+                    requestType: msg.type,
+                    error: `Failed to list provider usage: ${err.message}`,
+                    code: "provider_usage_list_failed",
+                },
+            });
+        }
+    }
     assertSafeGitRef(ref, label) {
         if (!/^[A-Za-z0-9._/-]+$/.test(ref)) {
             throw new Error(`Invalid ${label}: ${ref}`);
@@ -3225,11 +3404,11 @@ export class Session {
     async handleSetAgentModeRequest(agentId, modeId, requestId) {
         this.sessionLogger.info({ agentId, modeId, requestId }, "session: set_agent_mode_request");
         try {
-            await setAgentModeCommand({ agentManager: this.agentManager }, { agentId, modeId });
+            const result = await setAgentModeCommand({ agentManager: this.agentManager }, { agentId, modeId });
             this.sessionLogger.info({ agentId, modeId, requestId }, "session: set_agent_mode_request success");
             this.emit({
                 type: "set_agent_mode_response",
-                payload: { requestId, agentId, accepted: true, error: null },
+                payload: { requestId, agentId, accepted: true, error: null, notice: result.notice },
             });
         }
         catch (error) {
@@ -3321,11 +3500,11 @@ export class Session {
     async handleSetAgentThinkingRequest(agentId, thinkingOptionId, requestId) {
         this.sessionLogger.info({ agentId, thinkingOptionId, requestId }, "session: set_agent_thinking_request");
         try {
-            await this.agentManager.setAgentThinkingOption(agentId, thinkingOptionId);
+            const notice = await this.agentManager.setAgentThinkingOption(agentId, thinkingOptionId);
             this.sessionLogger.info({ agentId, thinkingOptionId, requestId }, "session: set_agent_thinking_request success");
             this.emit({
                 type: "set_agent_thinking_response",
-                payload: { requestId, agentId, accepted: true, error: null },
+                payload: { requestId, agentId, accepted: true, error: null, notice },
             });
         }
         catch (error) {
@@ -4880,6 +5059,29 @@ export class Session {
         const payload = this.buildStoredAgentPayload(record);
         return this.isProviderVisibleToClient(payload.provider) ? payload : null;
     }
+    async resolveDelegationRootWorkspaceId(agentId) {
+        const seen = new Set();
+        let currentAgentId = agentId;
+        while (true) {
+            if (seen.has(currentAgentId)) {
+                return null;
+            }
+            seen.add(currentAgentId);
+            const live = this.agentManager.getAgent(currentAgentId);
+            const source = live ?? (await this.agentStorage.get(currentAgentId));
+            if (!source) {
+                return null;
+            }
+            if ("archivedAt" in source && source.archivedAt) {
+                return null;
+            }
+            const parentAgentId = getParentAgentIdFromLabels(source.labels);
+            if (!parentAgentId) {
+                return source.workspaceId ?? null;
+            }
+            currentAgentId = parentAgentId;
+        }
+    }
     async buildActiveProjectPlacementsByWorkspaceId() {
         const [persistedWorkspaces, persistedProjects] = await Promise.all([
             this.workspaceRegistry.list(),
@@ -4962,7 +5164,9 @@ export class Session {
             if (existing) {
                 return existing;
             }
-            const placementPromise = this.buildProjectPlacementForWorkspaceId(workspaceId);
+            const placementPromise = request.type === "fetch_agent_history_request"
+                ? this.buildProjectPlacementForExistingWorkspaceProject(workspaceId)
+                : this.buildProjectPlacementForWorkspaceId(workspaceId);
             placementByWorkspaceId.set(workspaceId, placementPromise);
             return placementPromise;
         };
@@ -5285,6 +5489,26 @@ export class Session {
         await this.workspaceRegistry.upsert(workspaceRecord);
         return workspaceRecord;
     }
+    async findOrCreateProjectForDirectory(cwd) {
+        const normalizedCwd = resolve(cwd);
+        const checkout = await this.workspaceGitService.getCheckout(normalizedCwd);
+        const membership = classifyDirectoryForProjectMembership({ cwd: normalizedCwd, checkout });
+        const projectRecord = await this.resolveProjectRecordForPlacement({
+            membership,
+            timestamp: new Date().toISOString(),
+        });
+        await this.projectRegistry.upsert(projectRecord);
+        return projectRecord;
+    }
+    buildProjectDescriptor(project) {
+        return {
+            projectId: project.projectId,
+            projectDisplayName: resolveProjectDisplayName(project),
+            projectCustomName: project.customName ?? null,
+            projectRootPath: project.rootPath,
+            projectKind: project.kind,
+        };
+    }
     async reclassifyOrUnarchiveWorkspaceForDirectory(input) {
         const checkout = await this.workspaceGitService.getCheckout(input.cwd);
         const membership = classifyDirectoryForProjectMembership({ cwd: input.cwd, checkout });
@@ -5299,6 +5523,9 @@ export class Session {
         if (input.workspace.projectId === projectId &&
             input.workspace.kind === kind &&
             input.workspace.displayName === displayName) {
+            if (!input.project) {
+                await this.projectRegistry.upsert(projectRecord);
+            }
             return this.ensureWorkspaceRecordUnarchived(input.workspace);
         }
         await this.projectRegistry.upsert(projectRecord);
@@ -5340,6 +5567,78 @@ export class Session {
             updatedAt: input.timestamp,
         };
     }
+    async unarchiveOwningWorkspaceForAgent(agentId) {
+        const record = await this.agentStorage.get(agentId);
+        if (!record?.workspaceId) {
+            return;
+        }
+        const workspace = await this.workspaceRegistry.get(record.workspaceId);
+        if (!workspace?.archivedAt) {
+            return;
+        }
+        const directoryExists = await this.filesystem.isDirectory(record.cwd).catch(() => false);
+        if (!directoryExists) {
+            if (workspace.kind !== "worktree" || !workspace.branch) {
+                return;
+            }
+            // Recreate the worktree directory from its kept branch BEFORE clearing
+            // archivedAt — the reconciler re-archives workspaces whose directory is
+            // missing, so the record must point at a real directory first.
+            await this.recreateOwningWorktreeForRestore(workspace, workspace.branch);
+        }
+        await this.ensureWorkspaceRecordUnarchived(workspace);
+        await this.emitWorkspaceUpdatesForWorkspaceIds([workspace.workspaceId]);
+    }
+    async recreateOwningWorktreeForRestore(workspace, branch) {
+        const project = await this.projectRegistry.get(workspace.projectId);
+        if (!project) {
+            throw new WorktreeRequestError({
+                code: "unknown",
+                message: `Project ${workspace.projectId} not found for workspace ${workspace.workspaceId}`,
+            });
+        }
+        const projectRootExists = await this.filesystem
+            .isDirectory(project.rootPath)
+            .catch(() => false);
+        if (!projectRootExists) {
+            throw new WorktreeRequestError({
+                code: "unknown",
+                message: `Project root is missing for ${workspace.projectId}: ${project.rootPath}`,
+            });
+        }
+        // Archiving through the default path (scope "workspace", worktreePath only)
+        // resolves repoRoot=null, so deletePaseoWorktree's `git worktree remove`/
+        // `prune` is skipped and the admin registration survives — pinning the
+        // branch as "already checked out". Prune here frees any stale registration
+        // whose working dir is missing (a no-op for live worktrees) so the recreate
+        // below succeeds regardless of how the worktree was archived.
+        try {
+            await runGitCommand(["worktree", "prune"], { cwd: project.rootPath, timeout: 30000 });
+        }
+        catch {
+            // not critical; git will prune lazily
+        }
+        let result;
+        try {
+            result = await createWorktree({
+                cwd: project.rootPath,
+                worktreeSlug: basename(workspace.cwd),
+                source: { kind: "checkout-branch", branchName: branch },
+                runSetup: false,
+                paseoHome: this.paseoHome,
+                worktreesRoot: this.worktreesRoot,
+            });
+        }
+        catch (error) {
+            throw toWorktreeRequestError(error);
+        }
+        if (normalize(result.worktreePath) !== normalize(workspace.cwd)) {
+            throw new WorktreeRequestError({
+                code: "unknown",
+                message: `Recreated worktree diverged from ${workspace.cwd}: ${result.worktreePath}`,
+            });
+        }
+    }
     async ensureWorkspaceRecordUnarchived(workspace) {
         const project = await this.projectRegistry.get(workspace.projectId);
         if (!workspace.archivedAt && (!project || !project.archivedAt)) {
@@ -5501,21 +5800,10 @@ export class Session {
                 this.shouldSkipWorkspaceGitWatchUpdate(workspaceId, nextWorkspace)) {
                 continue;
             }
-            const watchTarget = this.resolveWorkspaceGitWatchTarget(workspaceId);
-            if (watchTarget && this.onBranchChanged) {
-                const newBranchName = nextWorkspace?.name ?? null;
-                if (newBranchName !== watchTarget.lastBranchName) {
-                    this.onBranchChanged(workspaceId, watchTarget.lastBranchName, newBranchName);
-                }
-            }
-            this.rememberWorkspaceGitDescriptorState(workspaceId, nextWorkspace);
+            this.recordWorkspaceGitDescriptorState(workspaceId, nextWorkspace);
             if (!nextWorkspace) {
                 subscription.lastEmittedByWorkspaceId.delete(workspaceId);
-                this.bufferOrEmitWorkspaceUpdate(subscription, {
-                    kind: "remove",
-                    id: workspaceId,
-                    ...(await this.resolveEmptyProjectForArchivedWorkspace(workspaceId)),
-                });
+                this.bufferOrEmitWorkspaceUpdate(subscription, await this.buildWorkspaceRemoveUpdatePayload(workspaceId, options?.removedProjectId));
                 continue;
             }
             const nextPayload = {
@@ -5534,16 +5822,36 @@ 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) {
+    recordWorkspaceGitDescriptorState(workspaceId, nextWorkspace) {
+        const watchTarget = this.resolveWorkspaceGitWatchTarget(workspaceId);
+        if (watchTarget && this.onBranchChanged) {
+            const newBranchName = nextWorkspace?.name ?? null;
+            if (newBranchName !== watchTarget.lastBranchName) {
+                this.onBranchChanged(workspaceId, watchTarget.lastBranchName, newBranchName);
+            }
+        }
+        this.rememberWorkspaceGitDescriptorState(workspaceId, nextWorkspace);
+    }
+    async buildWorkspaceRemoveUpdatePayload(workspaceId, removedProjectId) {
+        if (removedProjectId) {
+            return { kind: "remove", id: workspaceId, removedProjectId };
+        }
+        return {
+            kind: "remove",
+            id: workspaceId,
+            ...(await this.resolveProjectWithoutActiveWorkspacesForArchivedWorkspace(workspaceId)),
+        };
+    }
+    // When a workspace is archived its project may have no active workspaces left.
+    // Resolve that project parent so the `remove` update can carry it, keeping the
+    // sidebar in sync without a full re-hydration.
+    async resolveProjectWithoutActiveWorkspacesForArchivedWorkspace(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;
+        const projectWithoutActiveWorkspaces = (await this.workspaceDirectory.listEmptyProjects()).find((project) => project.projectId === archivedWorkspace.projectId);
+        return projectWithoutActiveWorkspaces ? { emptyProject: projectWithoutActiveWorkspaces } : null;
     }
     async emitWorkspaceUpdateForTerminalContribution(event) {
         // A terminal's activity contributes only to the workspace it carries. A
@@ -5989,6 +6297,58 @@ export class Session {
             });
         }
     }
+    async handleProjectAddRequest(request) {
+        const requestedCwd = request.cwd;
+        const cwd = expandTilde(requestedCwd);
+        const directoryExists = await this.filesystem.isDirectory(cwd).catch(() => false);
+        if (!directoryExists) {
+            this.sessionLogger.info({ requestedCwd, resolvedCwd: cwd, reason: "directory_not_found" }, "Add project rejected");
+            this.emit({
+                type: "project.add.response",
+                payload: {
+                    requestId: request.requestId,
+                    project: null,
+                    error: `Directory not found: ${cwd}`,
+                    errorCode: "directory_not_found",
+                },
+            });
+            return;
+        }
+        try {
+            const projectsBefore = new Map();
+            for (const project of await this.projectRegistry.list()) {
+                projectsBefore.set(project.projectId, project);
+            }
+            const project = await this.findOrCreateProjectForDirectory(cwd);
+            this.sessionLogger.info({
+                requestedCwd,
+                resolvedCwd: cwd,
+                projectId: project.projectId,
+                projectKind: project.kind,
+                projectTransition: describeRegistryTransition(projectsBefore.get(project.projectId) ?? null),
+            }, "Project added");
+            this.emit({
+                type: "project.add.response",
+                payload: {
+                    requestId: request.requestId,
+                    project: this.buildProjectDescriptor(project),
+                    error: null,
+                },
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Failed to add project";
+            this.sessionLogger.error({ err: error, cwd }, "Failed to add project");
+            this.emit({
+                type: "project.add.response",
+                payload: {
+                    requestId: request.requestId,
+                    project: null,
+                    error: message,
+                },
+            });
+        }
+    }
     buildWorkspaceScriptPayloadSnapshot(workspaceId, workspaceDirectory) {
         if (!this.serviceProxy || !this.scriptRuntimeStore) {
             return [];