fix(sandbox): emit gone for orphaned thread sandboxes on shared scope

[pedrofrxncx]

Summary

Opening a thread whose sandbox has been reaped leaves the Preview pinned on "Reserving sandbox" forever. Reproduced in prod on fila/0ced73dc… — reproduces for the thread owner too, so this is not the read-only/teammate gate.

Reading the SSE stream live from the page:

GET /api/fila/sandbox/decopilot_…/thread%3A0ced73dc…%2Fconn_u3zc…/events
→ event: phase  data: {"kind":"claiming","since":…}
   …then nothing, forever

claiming maps to CLAIM_PHASE_COPY.claiming = "Reserving sandbox". After 90s (NO_CLAIM_MAX_MS) emitLifecycle gives up silently (settle(false), no gone), the stream ends, EventSource reconnects, gets claiming again.

Root cause

providerKind === "agent-sandbox" ⇒ sharedSandboxId ⇒ scope === "shared", and that branch resolved vmEntry only from agent_sandbox_sessions. A thread-scoped sandbox (load_repo) is recorded on the thread while agent-sandbox truth lives in the session registry (resolve-provider.ts:152 — "Legacy hosted metadata is deliberately ignored"), so a reap leaves the thread entry orphaned with no session row to reconcile it.

Verified in prod PG for this thread:

• threads.metadata.sandboxMap[owner][branch]["agent-sandbox"].sandboxHandle = conn-u3zc-li4kbjlk1xzqlm-d6f02ea54cdba440
• agent_sandbox_sessions — no row for the branch
• no sandboxclaim in the cluster for that handle (reaped)

So vmEntry came back null, the stale-handle probe at the vmEntry?.sandboxHandle === claimName gate was skipped, and gone was never emitted. The gate would have fired — computeClaimHandle yields exactly the handle sitting in thread metadata. This is precisely the loop the file header (:85-89) says the thread fallback exists to prevent; that fallback was only reachable from the user-scoped else branch.

Three client recovery paths all key off state this never produced, which is why nothing recovers (no SANDBOX_START in the network log across a full page load):

path	gate	why it never fires
auto-start	!vmEntry	orphan entry grafted from thread metadata ⇒ vmEntry non-null
self-heal	events.notFound	set only by gone
overlay dismissal	resolvePreviewDisplay needs progressStatus !== "doing"	claimPhase: "claiming" keeps it "doing"

Changes

• Fall back to the thread sandboxMap in the shared branch when there is no session row at all — a session mid-transition (provisioning/stopping) is live state the thread map must not override.
• resolveSharedThreadVm scans every user key. A shared claim handle derives from the projectRef and carries no userId, so the entry may sit under the thread owner's key when a teammate opens the thread; keying on the viewer would skip the probe and loop on claiming.
• Clear the thread's sandboxMap entry in cleanupStaleEntry regardless of scope. The shared reap path returns early when there's no session row, which would leave the dangling handle in metadata and make every SSE reconnect re-enter the stale path (the 404 flood the existing comment warns about).

After this, the reaped handle probes dead → gone → notFound → self-heal fires SANDBOX_START → fresh sandbox.

Testing

• apps/api/src/api/routes/sandbox-events-handler.test.ts — 4 unit tests on the pure resolveSharedThreadVm, including the teammate-key case that caused the regression. Pure logic, no mocks (tier 1 per TESTING.md).
• bun run fmt, bun run --cwd apps/api check (tsc clean), bun run lint (0 errors; 14 pre-existing warnings, none in changed files).
• bun test apps/api/src/api apps/api/src/tools/sandbox apps/api/src/sandbox: 112 fail with the change vs 113 fail on the same tree without it — all pre-existing integration tests needing real Postgres/NATS, none related.

Follow-ups (not in this PR)

• load-repo.ts:217 claims "ensureSandbox already persisted the sandbox record on the thread (provisionSandbox → setThreadSandboxMapEntry — the single writer)". False for agent-sandbox — start.ts:749 only calls it in the non-shared else branch. It then streams a data-open-preview carrying an agent-sandbox sandboxMap the server deliberately ignores, which chat-context.tsx:945 patches into the client thread row. That mismatch is what mints these orphans.
• emitLifecycle's 90s no-claim timeout ends the stream silently, making "no claim ever appeared" indistinguishable from "still waiting". Worth considering gone there as a backstop.

---

Summary by cubic

Fixes the preview hanging on “Reserving sandbox” for shared agent-sandbox threads by detecting orphaned entries, emitting gone, and letting the client self-heal with SANDBOX_START.

• Bug Fixes
  • In shared scope, when no agent_sandbox_sessions row exists, fall back to the thread sandboxMap to probe the stale handle and emit gone.
  • Scan all user keys via resolveSharedThreadVm so teammates opening a thread can detect the stale shared handle.
  • Always clear the thread sandboxMap entry during cleanup to prevent reconnect loops and 404 floods.
  • Added unit tests for resolveSharedThreadVm covering the teammate-key scenario.

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