Make workspace IDs opaque, independent of the filesystem path (#1503)

* Make workspace IDs opaque, independent of the filesystem path

Workspace IDs were the resolved checkout/worktree path, so code could
treat an ID as a path: prefix matching, deriving directories from it,
falling back to a path when a lookup missed. IDs are now opaque -
compared only by exact equality and never used as a path. Anything
path-shaped resolves the workspace record first and reads its cwd.

New workspaces get a generated `wks_` ID; existing path-shaped IDs are
read from disk and never regenerated, so there is no migration and no
change to the wire or persisted schemas. Groundwork for running
multiple workspaces in a single directory.

* Keep attachment scope key stable and align refetch test

The attachment scope key keeps `workspace=` instead of `wsid=` so existing
persisted drafts are not orphaned; the rename was cosmetic. The SDK refetch
test no longer asserts a filter, matching refetch fetching one page and
selecting by id client-side.

* Fix live agent updates in directories without a registered workspace

The opaque-ID work removed buildProjectPlacementForCwd's directory
fallback, so an agent running in a folder with no registered workspace
(e.g. a fresh non-git dir) produced a null placement. forwardAgentUpdate
then threw "Workspace not found", the error was swallowed by its catch,
and no agent_update was emitted — live model/thinking switches and status
updates silently stopped. Caught by the live-preferences e2e suite.

The fallback builds a directory-scoped project placement keyed by the
path. That key is a project grouping key (non-git projects group by
path), not a workspace id, so it stays within the opaque-id rule.

* Always run server worktree archive, even without a resolved workspace

Archiving bailed out entirely when the workspace was not found in the
client store, so a race or stale state could make "archive" do nothing
server-side with only a console.warn. The server archive is keyed by
worktreePath, which is always available, so it now runs regardless; only
the optimistic client-side updates (keyed by workspace id) are gated on
the workspace being resolved.

* Expect a directory-scoped placement for unregistered agent dirs

This unit test asserted the no-placement behavior reverted in the live
agent-update fix, which had broken live model/thinking switching. Update
it to expect the directory-scoped placement now emitted for an agent in a
directory with no registered workspace.

* Fix opaque workspace routing in app E2E

* Preserve workspace IDs during partial bootstrap

* Fix archive flows for opaque workspace IDs

* Stop treating opaque workspace IDs as filesystem paths

Workspace IDs are opaque (wks_<hex>), but several call sites still passed
the id where a directory was expected, which broke those flows for opaque
IDs. The branch switcher sent the id as a cwd to branch/stash/checkout git
operations, and server archive/reconcile cleanup keyed git-watch and
subscription teardown by id, leaking that state.

Git and filesystem operations now take the workspace directory; the opaque
id is used only for identity and cache keys. Archive/reconcile cleanup
routes through a single teardownArchivedWorkspace helper that keeps the key
split explicit: runtime store by id, git watch and subscription by cwd.
Path-derived grouping keys are renamed to directory keys, and the helpers
are split into workspace-identity and workspace-directory so the id-vs-path
boundary is obvious.

packages/app/src/stores/last-workspace-selection.ts

@@ -59,6 +59,7 @@ export function createLastWorkspaceSelectionStore(storage: LastWorkspaceSelectio
     selection = normalized;
     revision += 1;
     notifyListeners();
+    // workspaceId is opaque; do not parse this persisted selection back into a path.
     void storage.write(JSON.stringify(normalized)).catch(() => {});
   }
 

packages/app/src/stores/navigation-active-workspace-store/navigation.ts

@@ -6,9 +6,9 @@ import {
   parseHostWorkspaceRouteFromPathname,
 } from "@/utils/host-routes";
 import {
-  resolveWorkspaceIdByExecutionDirectory,
+  resolveWorkspaceIdByDirectory,
   resolveWorkspaceMapKeyByIdentity,
-} from "@/utils/workspace-execution";
+} from "@/utils/workspace-identity";
 import type { ActiveWorkspaceSelection } from "@/stores/last-workspace-selection";
 
 export interface RouteSelectionInput {
@@ -77,7 +77,7 @@ export function navigateToWorkspace(
   const workspaceAgents = resolvedWorkspaceId
     ? Array.from(deps.getSessionAgents(serverId)).filter(
         (agent) =>
-          resolveWorkspaceIdByExecutionDirectory({
+          resolveWorkspaceIdByDirectory({
             workspaces: workspaces?.values(),
             workspaceDirectory: agent.cwd,
           }) === resolvedWorkspaceId,

packages/app/src/stores/session-store-hooks/index.ts

@@ -9,8 +9,8 @@ import {
   selectRecommendedProjectPaths,
   selectResolveWorkspaceIdByCwd,
   selectWorkspace,
+  selectWorkspaceDirectory,
   selectWorkspaceExists,
-  selectWorkspaceExecutionAuthority,
   selectWorkspaceFields,
   selectWorkspaceKeys,
   selectWorkspaceOrderByScopeForServer,
@@ -20,7 +20,6 @@ import {
   type WorkspaceStructure,
 } from "./selectors";
 import { useSessionStore, type WorkspaceDescriptor } from "../session-store";
-import type { WorkspaceExecutionAuthorityResult } from "@/utils/workspace-execution";
 import type { DesktopBadgeWorkspaceStatus } from "@/utils/desktop-badge-state";
 
 // These are the ONLY supported ways to read workspaces from the session store.
@@ -72,14 +71,14 @@ export function useHasHydratedWorkspaces(serverId: string | null): boolean {
   );
 }
 
-export function useWorkspaceExecutionAuthority(
+export function useWorkspaceDirectory(
   serverId: string | null,
   workspaceId: string | null,
-): WorkspaceExecutionAuthorityResult | null {
+): string | null {
   return useStoreWithEqualityFn(
     useSessionStore,
-    (state) => selectWorkspaceExecutionAuthority(state, serverId, workspaceId),
-    workspaceEqualityFns.deep,
+    (state) => selectWorkspaceDirectory(state, serverId, workspaceId),
+    workspaceEqualityFns.identity,
   );
 }
 

packages/app/src/stores/session-store-hooks/selectors.test.ts

@@ -8,7 +8,7 @@ import {
   selectRecommendedProjectPaths,
   selectResolveWorkspaceIdByCwd,
   selectWorkspace,
-  selectWorkspaceExecutionAuthority,
+  selectWorkspaceDirectory,
   selectWorkspaceFields,
   selectWorkspaceKeys,
   selectWorkspaceOrderByScopeForServer,
@@ -142,34 +142,30 @@ describe("selectWorkspace", () => {
   });
 });
 
-describe("selectWorkspaceExecutionAuthority", () => {
-  it("preserves the old missing-workspace message with the requested id", () => {
+describe("selectWorkspaceDirectory", () => {
+  it("returns the workspace directory, never the opaque workspace id", () => {
+    const workspace = createWorkspace({
+      id: "wks_3f9a2b1c",
+      workspaceDirectory: "/Users/dev/project",
+    });
+    initializeWorkspaces([workspace]);
+
+    const directory = selectWorkspaceDirectory(
+      useSessionStore.getState(),
+      SERVER_ID,
+      "wks_3f9a2b1c",
+    );
+
+    expect(directory).toBe("/Users/dev/project");
+    expect(directory).not.toBe("wks_3f9a2b1c");
+  });
+
+  it("returns null when the workspace is missing", () => {
     initializeWorkspaces([]);
 
     expect(
-      selectWorkspaceExecutionAuthority(useSessionStore.getState(), SERVER_ID, "missing-id"),
-    ).toMatchObject({
-      ok: false,
-      message: "Workspace not found: missing-id",
-    });
-  });
-
-  it("keeps deep-equal authority references under unrelated workspace updates", () => {
-    const workspaceA = createWorkspace({ id: "workspace-a", name: "A" });
-    const workspaceB = createWorkspace({ id: "workspace-b", name: "B" });
-    initializeWorkspaces([workspaceA, workspaceB]);
-
-    const tracked = trackSelector(
-      useSessionStore,
-      (state) => selectWorkspaceExecutionAuthority(state, SERVER_ID, workspaceA.id),
-      workspaceEqualityFns.deep,
-    );
-    const before = tracked.current;
-
-    useSessionStore.getState().mergeWorkspaces(SERVER_ID, [{ ...workspaceB, status: "running" }]);
-    expect(tracked.current).toBe(before);
-
-    tracked.stop();
+      selectWorkspaceDirectory(useSessionStore.getState(), SERVER_ID, "missing-id"),
+    ).toBeNull();
   });
 });
 

packages/app/src/stores/session-store-hooks/selectors.ts

@@ -6,11 +6,9 @@ import {
 } from "@/projects/workspace-structure";
 import type { DesktopBadgeWorkspaceStatus } from "@/utils/desktop-badge-state";
 import {
-  getWorkspaceExecutionAuthority,
-  resolveWorkspaceIdByExecutionDirectory,
+  resolveWorkspaceIdByDirectory,
   resolveWorkspaceMapKeyByIdentity,
-  type WorkspaceExecutionAuthorityResult,
-} from "@/utils/workspace-execution";
+} from "@/utils/workspace-identity";
 import type { WorkspaceDescriptor } from "../session-store";
 
 export type { DesktopBadgeWorkspaceStatus } from "@/utils/desktop-badge-state";
@@ -113,6 +111,14 @@ export function selectWorkspaceFields<T>(
   return workspace ? project(workspace) : null;
 }
 
+export function selectWorkspaceDirectory(
+  state: SessionsSnapshot,
+  serverId: string | null,
+  workspaceId: string | null,
+): string | null {
+  return selectWorkspace(state, serverId, workspaceId)?.workspaceDirectory || null;
+}
+
 export function selectWorkspaceExists(
   state: SessionsSnapshot,
   serverId: string | null,
@@ -128,20 +134,6 @@ export function selectHasHydratedWorkspaces(
   return serverId ? (state.sessions[serverId]?.hasHydratedWorkspaces ?? false) : false;
 }
 
-export function selectWorkspaceExecutionAuthority(
-  state: SessionsSnapshot,
-  serverId: string | null,
-  workspaceId: string | null,
-): WorkspaceExecutionAuthorityResult | null {
-  if (serverId === null || workspaceId === null) {
-    return null;
-  }
-  return getWorkspaceExecutionAuthority({
-    workspaces: state.sessions[serverId]?.workspaces,
-    workspaceId,
-  });
-}
-
 export function selectWorkspaceStructureProjects(
   state: SessionsSnapshot,
   serverId: string | null,
@@ -257,7 +249,7 @@ export function selectResolveWorkspaceIdByCwd(
     return null;
   }
   const workspaces = state.sessions[serverId]?.workspaces;
-  return resolveWorkspaceIdByExecutionDirectory({
+  return resolveWorkspaceIdByDirectory({
     workspaces: workspaces?.values(),
     workspaceDirectory: cwd,
   });

packages/app/src/stores/session-store.test.ts

@@ -99,6 +99,44 @@ describe("normalizeWorkspaceDescriptor", () => {
     expect(workspace.scripts).not.toBe(scripts);
   });
 
+  it("canonicalizes the workspace directory and treats a blank one as empty", () => {
+    const canonical = normalizeWorkspaceDescriptor({
+      id: "1",
+      projectId: "1",
+      projectDisplayName: "Project 1",
+      projectRootPath: "/repo",
+      workspaceDirectory: "/repo/app/",
+      projectKind: "git",
+      workspaceKind: "checkout",
+      name: "main",
+      archivingAt: null,
+      status: "done",
+      statusEnteredAt: null,
+      activityAt: null,
+      diffStat: null,
+      scripts: [],
+    });
+    expect(canonical.workspaceDirectory).toBe("/repo/app");
+
+    const blank = normalizeWorkspaceDescriptor({
+      id: "1",
+      projectId: "1",
+      projectDisplayName: "Project 1",
+      projectRootPath: "/repo",
+      workspaceDirectory: "   ",
+      projectKind: "git",
+      workspaceKind: "checkout",
+      name: "main",
+      archivingAt: null,
+      status: "done",
+      statusEnteredAt: null,
+      activityAt: null,
+      diffStat: null,
+      scripts: [],
+    });
+    expect(blank.workspaceDirectory).toBe("");
+  });
+
   it("defaults missing scripts to an empty array", () => {
     const payload = {
       id: "1",

packages/app/src/stores/session-store.ts

@@ -27,8 +27,11 @@ import type {
   ServerCapabilities,
   WorkspaceDescriptorPayload,
 } from "@getpaseo/protocol/messages";
-import { normalizeWorkspaceOpaqueId } from "@/utils/workspace-identity";
-import { resolveWorkspaceMapKeyByIdentity } from "@/utils/workspace-execution";
+import {
+  normalizeWorkspaceOpaqueId,
+  normalizeWorkspacePath,
+  resolveWorkspaceMapKeyByIdentity,
+} from "@/utils/workspace-identity";
 import {
   createAgentLastActivityCoalescer,
   type AgentLastActivityCommitter,
@@ -149,7 +152,10 @@ export function normalizeWorkspaceDescriptor(
     projectDisplayName: payload.projectDisplayName,
     projectCustomName: payload.projectCustomName ?? null,
     projectRootPath: payload.projectRootPath,
-    workspaceDirectory: payload.workspaceDirectory,
+    // Canonicalize the workspace directory once, at the store boundary, so every
+    // consumer can read workspace.workspaceDirectory directly. Empty means "no
+    // usable directory" (older daemons may omit it; the wire field is optional).
+    workspaceDirectory: normalizeWorkspacePath(payload.workspaceDirectory) ?? "",
     projectKind: payload.projectKind,
     workspaceKind: payload.workspaceKind,
     name: payload.name,

packages/app/src/stores/workspace-tabs-store/state.ts

@@ -59,6 +59,7 @@ export function buildWorkspaceTabPersistenceKey(input: {
   if (!serverId || !workspaceId) {
     return null;
   }
+  // workspaceId is opaque; do not parse this key back into a path.
   return `${serverId}:${workspaceId}`;
 }