#7485 feat(workspaces): support explicit local workspaces on shared checkouts

What & why

Projects now appear in the sidebar with zero workspaces. Users explicitly choose Local to share the project's existing checkout or Worktree for an isolated checkout; adding or setting up a project no longer creates or resurrects a special main workspace.

• Migrate host main rows to local, remove the one-per-project restriction and startup ensure loop, and preserve v1 workspace migration.
• Support Local in the composer, CLI, and SDK. Local creation never switches branches or prunes git worktree registrations; SDK retries preserve a client ID without relaunching agents or commands; concurrent default naming is guarded. Local rows follow relocation, and an in-flight create rejects if its checkout moved.
• Delete shared-checkout workspaces as records and terminal sessions only, skipping teardown, file removal, and branch deletion. Path-based protection also covers legacy rows; individual and bulk dialogs explain this behavior.
• Preserve Local identities during adoption and reject Worktree/PR requests for the shared checkout. Local requests use dedicated host endpoints so unsupported hosts fail before creating anything. CLI, SDK, and MCP use the same contract; conflicting cloud checkout flags are rejected.
• Adding a local project opens its composer on this device even when Cloud or a remote host was previously selected. The intended project is selected immediately and submission waits for its project-list entry. Mobile deletion copy explains shared-checkout preservation.
• Place empty projects and new workspaces without revealing explicitly hidden projects. Preserve checkout preference and show the forced Worktree choice for linked PRs. Update mobile consumers, docs, and translations.

Fixes SUPER-2246. Live before-and-after walkthrough covers project creation, checkout selection, shared local workspaces, deletion, and the new composer handoff. Implementation evidence and earlier live checks.

How I tested it

• Full desktop suite: 3,857 tests pass on the merged branch. All 21 other package test tasks pass when desktop and host-service are run separately; the tRPC test preload removes production-secret and test-order dependencies.
• 42 focused host tests and 5 SDK tests pass. Regressions cover both relocation timing windows, Local retry agent/command launches, stable SDK IDs across transport retries, and delayed project-list preselection. SDK create/get/update response types include Local.
• Resolved the CLI merge with main's explicit --session requirement; all 22 workspace-create/cloud-conflict tests pass.
• Reproduced and fixed socket-test event-realm mismatch. Handoff tests use a scoped router provider, and locale tests wait for observable language state. The full desktop suite passes on Bun 1.3.14.
• bun run lint, bun run typecheck (40 packages), bun run check:i18n, and bun run check:plugins pass.
• The broad local host run remains incomplete: it had one terminal-bundle harness failure and later stalled in git-status-store.adversarial3 watcher cleanup. The terminal integration suite passes independently (9 tests). The GitHub Test job now passes on Linux.
• Live CDP follow-up: Cloud composer → create local project selects This device and the new project, preserves the typed prompt, and closes the dialog. Local submission then creates one shared-checkout row through the dedicated enqueue endpoint, with one git checkout. After the final selection fix, the project-row action again opened the composer with the matching project; delayed-list protection is verified by the regression hook test, not a simulated live network delay.

Compatibility notes: project create/setup responses no longer include mainWorkspaceId; local creates still reject detached HEAD. The cloud analytics event retains its existing main enum value.

Checklist

• PR title follows conventional commits (type(scope): subject)
• bun run lint and bun run typecheck pass (CI fails on lint warnings too)
• "Allow edits from maintainers" is checked on fork PRs (not a fork PR)

---

Summary by cubic

Projects now appear in the sidebar with zero workspaces instead of an implicit main workspace. Users explicitly choose Local to reuse the project's existing checkout or Worktree for an isolated checkout. Fixes SUPER-2246.

Behavior changes

• Adding a project now opens the workspace composer, since a new project has no workspaces yet.
• Deleting a local workspace removes only its record and terminal sessions; files, branches, and other workspaces stay.
• Project create/setup responses no longer include mainWorkspaceId; local creation still rejects detached HEAD.
• Empty projects are placed in the sidebar, and background placement no longer reveals explicitly hidden projects.
• The CLI accepts --checkout local and rejects combining it with --branch or --pr; linked PRs always force Worktree, and cloud workspaces reject --checkout.
• Local checkouts use dedicated host endpoints, so unsupported hosts fail before creating anything.
• The cloud analytics event keeps its existing main enum value.

Migration

• Existing main rows are migrated to local automatically; no manual steps.
• The one-main-per-project unique index is dropped, and the startup main-workspace sweep is removed.
• v1 migration creates a local workspace for a workspace on the checkout's current branch instead of adopting a worktree.

Summary by CodeRabbit

• New Features

  • Create workspaces using a shared local checkout or an independent worktree.
  • Rename, close, delete, group, and select local workspaces like other workspace types.
  • Added checkout selection and clearer explanations to the new-workspace flow.
  • Local workspace deletion preserves project files, branches, and sibling workspaces.
  • Imported and newly created projects open automatically after setup.
  • Projects and workspaces are placed in the sidebar without revealing hidden projects.

• Migration

  • Existing main workspaces are converted to local workspaces.

• Documentation

  • Updated CLI reference documentation and localized workspace lifecycle messaging.