feat(native): add Studio desktop app with a local Rust runtime

[vibegui]

What is this contribution about?

Adds the macOS-first version of Studio as a Tauri v2 app in apps/native. This is not the earlier hosted multi-org launcher: the app mounts the existing production apps/web router and shell, while an in-process Rust runtime replaces the local half of bunx decocms link.

• Same Studio UI, minimal shared-code churn: org switching, settings, connections, chat, and project views remain shared with the web app. The apps/web diff is deliberately small and mostly additive — a second Vite entry, a lib/desktop/ transport layer, and desktop-only screens. Shared components the desktop needed to behave differently were pushed back onto main's version and the difference absorbed in Rust instead.
• Hybrid local/upstream runtime: ordinary Studio data is proxied to the configured upstream deployment, while native transport gates route local threads, Claude Code/Codex dispatch, sandboxes, previews, and process execution to Rust.
• Native authentication: OAuth 2.1/PKCE and Better Auth bridge desktop sign-in to macOS Keychain. Credential auth uses the shared login UI; social/SSO providers complete in the system browser.
• MCP connection OAuth: connecting an MCP server (GitHub, Google, …) also completes in the system browser, because window.open cannot work inside a webview. See the dedicated section below.
• Local agents: detects and runs the user's installed, authenticated claude and codex CLIs, translates their streams for the existing chat UI, and handles cancellation/process-tree cleanup. The agent CLIs are not bundled — they are resolved from an env override or PATH, so the user's own installation and its credentials are what run. rclone is the only third-party binary this app ships (see below).
• Durable local chats: native-owned SQLite stores local threads, ordered messages, turn queues, cancellation state, and crash recovery. These chats intentionally remain device-local in v1.
• Durable sandboxes: Rust implements the filesystem, bash, Git, tasks, setup, SSE, HTTP/WebSocket preview, and editor-integration surfaces previously provided by the link daemon. sandboxes.sqlite persists identity and lifecycle state so Stop, Restart, and backend/app restart recovery address the same sandbox.
• Worktree-backed repositories: one bare clone per upstream repository lives in a shared store (repos/<host>/<owner>/<repo>), and each sandbox is a git worktree of it at sandboxes/<handle>/repo. N threads on one repository no longer pay N copies of the object store.
• Organization filesystem: the org's shared volumes (home, public, uploads, outputs) are mounted so agents can read them with ordinary filesystem calls. See the dedicated section below.
• RAM-bounded terminal replay: clone, install, and dev-server output is written to capped files and tail-replayed into xterm, so late mounts and restarts recover output without permanent per-task RAM buffers.

Organization filesystem

bunx decocms link mounted the org's volumes into every sandbox; the Rust runtime originally shipped only a config relay that mounted nothing. Restoring it is the newest part of this PR, and its design and rationale are documented in apps/native/docs/org-fs-plan.md.

<appRoot>/orgs/<slug>/{home,public,uploads,outputs}   ← the only real mounts, one set per ORG
<appRoot>/sandboxes/<handle>/
├── repo/    ← git worktree (the agent's cwd)
└── org/     ← per-sandbox symlinks into the org mounts

• Mounted, not synced, so org/home is live and browsable rather than a point-in-time copy. A bundled rclone re-serves a loopback WebDAV surface (/_sandbox/orgfs/:org/:volume/**) as NFS, which macOS attaches with its built-in client — no macFUSE, no kernel extension.
• Shared per organization, not per sandbox. Every sandbox links into one set of mounts, so the process count is a function of orgs visited, not of agents or threads.
• Warmed on org switch, not on sandbox start, so the mounts are up before an agent needs them; sandbox provisioning then waits at most 2s and reports the result in the setup transcript.
• org is a sibling of repo, never inside it, so a stalled network mount cannot wedge bun install, the dev server, or any git operation.
• Agents are told where it is. The desktop CLIs receive no system prompt of their own, so an organization-filesystem block is appended (--append-system-prompt for claude, -c developer_instructions= for codex) — gated on the directory actually existing.
• rclone is bundled (78 MB per architecture) but not committed: beforeBuildCommand fetches it and verifies it against the release's published SHA256SUMS, and CI caches it. Tauri signs it with the app bundle automatically.

MCP connection OAuth

window.open returns null unconditionally in a Tauri webview — WKWebView has no popup or tab concept and Tauri spawns no webview for it — so the shared MCP OAuth flow failed both its popup and its new-tab attempt and threw "Popup was blocked" before the user ever saw a consent screen.

Consent now happens in the user's real browser. That is also what keeps working as more providers are connected: Google rejects embedded webviews outright (disallowed_useragent), so an in-app webview would have fixed GitHub and then broken on the next connector.

Once consent moves to another browser process, neither of the flow's return channels can carry the result home — window.opener is unreachable across processes and the storage event needs a shared localStorage — so the local API supplies the missing one:

Route	Called by	Guard
GET /_auth/mcp-callback	the system browser	outside — it has no per-launch session cookie and cannot be given one
GET|DELETE /_auth/mcp-callback/result	the webview	inside — a parked authorization code is only readable by a caller that proved it is this app

That asymmetry is the security-relevant part; inverting it would let any local process read a live authorization code off localhost. Leaving the write unauthenticated is safe because it is not the boundary: state is a crypto.randomUUID() the webview keeps in memory and still verifies. Reads are destructive, so a code is never replayed, and a flow clears the slot before it starts so an abandoned callback cannot surface as a bogus CSRF error.

• Rust stays a dumb relay. state is handed back verbatim, leaving the provider-specific unwrapping (deco.cx base64-wraps it) and the CSRF comparison in the one place that already implements them.
• The SDK takes an injected adapter rather than importing the desktop bridge, so no Tauri binding reaches the plain web build and the browser flow is unchanged. The apps/web diff is one optional hook plus one desktop-only file.
• The opener capability now allows https. The authorize URL belongs to whatever authorization server a connection's MCP server advertises, so the set is open-ended and cannot be enumerated ahead of time. Plaintext http beyond loopback stays denied — an authorize URL served over it would be a downgrade.
• Browser-facing pages share Studio's chrome. Sign-in and this callback both serve dead-end pages into a browser that is not the app; they now share upstream::browser_page (design-system tokens keyed off prefers-color-scheme, inlined brand mark, everything self-contained so an offline tab still renders). The callback page takes only a success flag, never the provider's error_description, so it cannot be made to relay arbitrary text.

Screenshots / demonstration

The desktop app intentionally renders the production Studio shell rather than a parallel desktop layout. Manual acceptance covers sign-in, org switching, local agent chat, clone/install/dev output in xterm, Stop/Restart, iframe preview, editor opening, and sandbox recovery after an app/backend restart.

The organization filesystem was verified end to end against a real org: all four volumes mounted, real content readable through the agent's own ls, writes round-tripping, public rejecting writes, and four rclone processes holding steady across four sandboxes on two different agents and across an app restart, with no orphaned or zombie processes.

MCP connection OAuth was verified against a real GitHub connection (deco-sites/faststore-fila), which went from "Needs authorization" to serving 47 tools. The guard was checked directly: the browser's write returns 200 without a cookie, an unauthenticated read of a parked code returns 401, and a second read returns pending rather than replaying the code.

How to test

# One-time setup per macOS development machine
bun run --cwd=apps/native dev:signing:setup

# Start Vite HMR + the Tauri app
bun run --cwd=apps/native dev

Then:

1. Sign in and switch organizations to confirm the shared production shell is active.
2. Open a git-backed chat, select a detected Claude Code or Codex tier, and send a message.
3. Open the sandbox drawer and verify setup xterm replay, live dev output, iframe preview, and Open in VSCode/Cursor.
4. Use Stop and Restart and confirm the Rust lifecycle and terminal state update.
5. Ask the agent what it can see in the organization home folder; it should read real org content by absolute path.
6. Quit and relaunch; authentication, local chats, and sandbox metadata should recover, an intact sandbox should restart without recloning, and mount | grep nfs should show one set of volumes per org with no orphans.

Automated gates

bun run check
bun run lint
bun test

The dedicated native CI also runs the local-API black-box contract, dispatch differential, and Tauri build/boot smoke. See apps/native/README.md for the full commands.

Migration and release notes

• v1 targets macOS. Sandboxes are bare child processes running as the current OS user, not containers or VMs.
• Local chats do not synchronize with the hosted thread store. Desktop v1 supports the user's Claude Code/Codex CLIs; it does not add local Decopilot inference.
• Native SQLite schemas are app-owned and migrate independently from Studio's Postgres schema.
• The organization filesystem depends on mount_nfs, which is incompatible with App Sandbox. This rules out Mac App Store distribution; Developer ID + notarization is unaffected.
• Existing bunx decocms link users are not forced across immediately; retirement remains staged after parity and dogfooding.
• Production distribution still needs Apple Developer ID/notarization credentials, updater keys and artifact hosting. The self-signed development identity is only for stable local Keychain access during rebuilds.

Review guide

The highest-value review areas are:

1. apps/native/crates/local-api — auth boundary, route parity, sandbox lifecycle, process cleanup, and log replay.
2. apps/native/crates/local-api/src/sandbox/org_*.rs and routes/webdav/ — the organization filesystem: mount lifecycle, process ownership, and the read-only boundary on shared volumes.
3. apps/native/crates/local-api/src/routes/mcp_callback.rs and the router's registration of it — the split authority between the unauthenticated browser landing point and the guarded read.
4. apps/native/crates/upstream — OAuth refresh and Keychain durability.
5. apps/native/crates/harness — CLI detection, PTY execution, and stream translation.
6. The apps/web diff — it should read as additive desktop wiring, with shared components unchanged.

Review checklist

• Title and description match the implemented native architecture
• Existing production Studio UI is reused, with a deliberately small shared-code diff
• No web-facing rollout surface: the desktop download CTA was removed from apps/web entirely, so there is nothing to gate
• Documentation and release runbooks are included
• Automated and manual native acceptance paths are documented
• Organization filesystem verified end to end against a real organization