[quickbeard]

What

Reaching Work without a sandbox opened the full Add sandbox form — a name, a folder, an image, and on a Mac a CPU count and a memory size — before anything could happen. It now opens a dialog that asks for none of it.

	Before	Now
Name	typed	codev-sandbox, decided in main
Folder	picked	a placeholder the app makes; never shown
Image	optional	unchanged — still the one question
CPUs / memory (macOS)	typed	unset, so the backend default applies

Settings → Servers keeps DialogAddSandbox exactly as it is, for a second sandbox or one pointed at a particular folder from the start.

The folder question was the worst of the five: at that moment the user has not decided what they want to work on, and getting it wrong is permanent — a sandbox's project folder is fixed for its life. Deciding it for them and asking for a folder afterwards, as a mount, matches what a sandbox actually is: an environment whose reach into the machine is the folders you give it.

The placeholder folder

A sandbox cannot boot without a working directory, so the main process makes one at <app data>/sandbox-workspaces/codev-sandbox. On Windows that root is %LOCALAPPDATA%\CoDev\…, deliberately not the Electron userData path: that resolves under %APPDATA%, which a roaming profile or folder redirection can point at a UNC share, and the WSL backend reaches a project folder through wslpath, which cannot translate one — the sandbox would simply fail to start. validateMountPaths already rejects UNC for the same reason.

It is a dedicated subdirectory rather than the app data root because the guest gets read-write access to whatever it is given, and that root holds the sandbox's own boot.json — and with it the guest server's password.

SandboxConfig gains placeholderProject, persisted rather than derived from the path so that app data moving cannot make the folder reappear. The app uses it in three places, because the folder reaches the UI three ways:

• seedSandboxProjects no longer seeds a project for it, so no sidebar row is created.
• Switching to Work no longer lands on it (tabs.tsx fell back to primaryFolder, which is exactly the folder being hidden).
• sandbox-remove deletes it. destroy() clears the provider's own directories but never a project folder, since the usual one belongs to the user — so without this it would be orphaned in app data on every delete.

removeSandboxWorkspace refuses any path outside the root it owns. It deletes a directory tree, and a folder the user chose must never match.

Asking for the first project

With nothing mounted there is nothing to list, and upstream's empty-projects fallback offers a picker that browses the server it is pointed at — for a sandbox, the guest's own home. The Work sidebar shows a prompt instead, with a button that opens the existing Mount project dialog. Creating a sandbox does not open that dialog by itself: two dialogs in a row is the app deciding what the user does next, and the prompt is there whenever they want it.

That dialog also hides its primary-folder row for a placeholder sandbox — the path is app data the user did not choose and cannot remove, so it would have been the one place they ever met it. A sandbox pointed at a folder the user picked still shows it.

The wording is now "Mount a project" throughout, matching the dialog title and sidebar button, which already said project.

Shared image field

src/sandbox/image-field.tsx now owns the picker, the inspection round-trip and the verdict rendering, used by both dialogs. It is the only field they have in common and the only one with behaviour worth getting wrong twice: a verdict has to belong to the path it was made about (a field edited since is unchecked, not approved), and a picker failure has to be visible rather than leaving an empty field.

sandbox-cancel-default is its own channel rather than cancel(name): the name belongs to the main process, and a sandbox mid-create is not in the list the renderer can see — the controller publishes it only once the create has finished — so there is no name there to cancel by.

Verification

• packages/desktop 113 pass, packages/app 696 pass, packages/codev-sandbox 149 pass / 2 skip. All three typecheck clean.
• New coverage: the workspace root on each platform, including that Windows uses LOCALAPPDATA even when userData is a UNC path, and that an unset LOCALAPPDATA falls back rather than leaving the sandbox with nowhere to boot; ensureDefault being idempotent; and remove refusing both a folder the user chose (asserted by the file still being there) and the root itself. Plus isPlaceholderSandbox against a normal sandbox, a placeholder one, and a non-sandbox server.
• Not exercised: the flow in the running app. Worth watching on the first real run — applying the first mount restarts the sandbox on macOS and Linux.

Note on formatting

prettier --check flags 8 of the files this branch touches — every one of them already fails on main, which has no format script and no CI format check. None of the failures come from this branch, and every file it adds is prettier-clean. Running --write was tried and reverted: it rewrapped unrelated lines (app-sidebar.tsx alone went to 155 changed lines instead of 28), which buries the change and, on upstream-tracked files, adds merge-conflict surface for lines that are not ours. Normalising the repo is worth doing as its own commit.

Docs

• CHANGELOG.md — Unreleased ▸ Sandbox.
• DIVERGENCES.md — a new row covering context/server.tsx, app-sidebar.tsx, i18n/{en,es}.ts and preload/index.ts, including the warning not to "simplify" the placeholder away by pointing the sandbox at the user's home, and that DEFAULT_SANDBOX_NAME is persisted as a sandbox id and a WSL distribution name.

🤖 Generated with Claude Code