fix(native): Fast Preview is authoritative over the sandbox interceptor

[tlgimenes]

Stacked on #6054.

The bug

In the desktop app, a Fast Preview project's /git/status was answered from a local sandbox clone, not from the GitHub API. Symptoms seen while testing #6054:

• the toolbar stuck on Loading… forever after a branch switch, with SandboxGitError: repository not initialized and fetchStatus: "paused" — the query had failed and stopped retrying
• git/status reporting head 6abff372 while /decofile (which the editor writes through) reported 64cf81af — two different repositories for the same branch
• working-tree files (.deco/generate.digests.json) in a payload the GitHub-backed shim can never produce, since it hardcodes modified: []

Why

intercept/sandbox_ops.rs's is_handled matches ["git", _] unconditionally, and try_intercept is the upstream proxy's first decision — so the request never reaches the cloud, and sandbox-proxy.ts:213's Fast Preview branch is never evaluated in the native app.

grep -rn "fastPreview\|fast_preview" apps/native/crates/ returns zero hits. The desktop app has no concept of Fast Preview.

sandbox_ops already declines when no local worktree exists, and its comment names sandbox-less Fast Preview as a case that falls through there. It doesn't, because the worktree handle is derived from the repository: a sandbox left over from vibecoding on the same repo claims the route for a branch it has never checked out, and routes/git.rs:329 then answers not_ready("repository not initialized").

Inference can't work here. The flag has to be declared.

The fix

The webview sets x-deco-fast-preview on its sandbox git calls; try_intercept declines every /sandbox/* path carrying it, before any interceptor runs.

A routing hint, not a trust boundary — it only decides whether to answer locally, and the API re-derives the flag from the vMCP's own metadata before serving anything. A wrong or forged value can only route the request to the authority, never around it.

Declining at try_intercept rather than per-interceptor is what makes it authoritative: Fast Preview is sandbox-less by definition, so nothing under /sandbox/* is ours to serve.

apps/api needed no change

resolveVmClaim returns next() before resolveSandboxProvider is ever called (sandbox-proxy.ts:229), so a Fast Preview project never resolves a runner and daemon-backed routes 503 via requireRunner. It was already authoritative — it was being bypassed.

Testing

• New unit test for the header predicate, documenting the repository-derived-handle regression.
• cargo test -p local-api --lib routes::intercept — 69 pass.
• cargo check, cargo clippy, cargo fmt --check clean.
• Web: bun test 214 pass, bun run lint 0 errors, bun run fmt clean.

Follow-up not in scope

Only the two calls the CMS toolbar makes (fetchGitStatus, rebaseGitBranch) send the header today. PublishDialog's calls still go through the old path — they run on explicit user action and fail visibly rather than silently spinning, but they should carry it too.

🤖 Generated with Claude Code

---

Summary by cubic

Make Fast Preview authoritative for desktop sandbox git routes to prevent local interception. Previously the native app served /api/:org/sandbox/*/git/* from a local sandbox, causing mismatched HEADs and “repository not initialized”; now Fast Preview-marked calls always go to the cloud API.

• Native (apps/native): define x-deco-fast-preview and predicate; try_intercept now receives headers and returns None for any /sandbox/* when the header is "1" or "true"; upstream proxy passes headers; adds a unit test for the predicate/regression.
• Web (apps/web): send x-deco-fast-preview in fetchGitStatus and rebaseGitBranch; add FAST_PREVIEW_HEADER and SandboxGitCallOptions; plumb via sandboxFetch when { fastPreview: true } is set.
• Routing: header is a hint only; the API re-derives Fast Preview from vMCP metadata. A wrong/forged header can only route to the authority, never around it.
• Rollout: no migrations. The header is a no-op on older desktop builds; the bug persists until the native app is updated.

^{Written for commit edbbfb6. Summary will update on new commits.}