fix(sandbox): stop trusting legacy agent-sandbox entries on the agent row

[pedrofrxncx]

Summary

A preview hangs for exactly one member while a teammate opening the same thread provisions normally. Reported on clovis/3934190e…: stuck for @Tavano (the thread's own author), instant for another member. Tavano's read — "acho que o meu browser não rodou SANDBOX_START" — was exactly right.

Root cause

The agent row is not authoritative for agent-sandbox:

• Server resolves that kind exclusively from agent_sandbox_sessions and deliberately ignores metadata.sandboxMap — readRecordedKinds, apps/api/src/sandbox/resolve-provider.ts:151-155.
• Nothing writes it there anymore — SANDBOX_START only calls setSandboxMapEntry in the non-shared else branch (start.ts:749).

Every such entry is a leftover from before the kind became org-shared. The client still read them (agent-shell-layout/index.tsx passed entity?.metadata?.sandboxMap straight into parseBranchMap(sandboxMap[userId][branch])).

Evidence from prod for branch tavano-vgfdyxrm:

source	handle	live?
connections.metadata.sandboxMap[tavano][tavano-vgfdyxrm]["agent-sandbox"]	tavano-vgfdyxrm-77c242b4e71f6488	404 — reaped
agent_sandbox_sessions	tavano-vgfdyxrm-5e9d9abaf97aabe0	200 — live

The session row's created_at is the moment the other member opened the thread, with their id as created_by — it did not exist while Tavano was stuck.

A leftover entry makes vmEntry non-null for whichever user key holds it, so shouldAutoStart returns false (!args.vmEntry) and no SANDBOX_START is ever issued for that member. Meanwhile previewUrl points at the reaped sandbox and there is nothing to self-heal from: the direct-daemon probe only treats HTTP 404 as gone (isDirectDaemonEventsGoneStatus), and a dead hostname throws and is swallowed to false. A member whose key is simply absent from the map gets vmEntry === null, hits the ownership gate, acknowledges, and provisions. The asymmetry is decided purely by which user key the leftover happens to sit under.

Changes

• withoutLegacyAgentSandboxEntries — strips agent-sandbox from the agent-row sandboxMap in VmEventsBridge, leaving the session registry as the only source for that kind. Mirrors the server rule.
• Also strips the legacy cluster spelling, which parseBranchMap normalizes to agent-sandbox and would otherwise reintroduce the bug through the back door. (0 rows in prod today, and storage normalizes on read — cheap guard against a row slipping through.)
• Returns the input reference unchanged when there's nothing to strip.

Behaviour-neutral otherwise: when a session row exists, its graft in VmEventsBridge already overwrites the stripped entry. With no session row, vmEntry goes null → auto-start fires → sandbox provisions, which is what should have happened for Tavano.

The thread-map graft is deliberately left alone — that one is a live feature (read-only view of a teammate's running sandbox), not legacy.

Scale

agent-sandbox sandboxMap entries with no matching session row:
  1789 entries · 320 agents · 112 users

Each was a latent "preview never starts, for one member, on one branch." This makes them inert — no data migration needed.

Relationship to #5219

Same root disease (a client trusting agent-sandbox state the server declared dead), different store. #5219 covers a leftover on the thread row and is gated on threadIdFromBranch(branch), which needs a thread: prefix. "tavano-vgfdyxrm" returns null, so #5219 does not help here. The two are independent and can merge in either order.

Testing

• apps/web/src/lib/agent-sandbox-map.test.ts — 6 unit tests: the exact regression, the cluster spelling, user-desktop siblings preserved, sibling branches/users untouched, reference identity, undefined passthrough. Pure logic, no mocks (tier 1 per TESTING.md).
• bun run fmt, bun run --cwd apps/web check (tsc clean), bun run lint (0 errors; 14 pre-existing warnings, none in changed files).
• bun test apps/web/src/components/sandbox apps/web/src/lib: 574 pass / 6 fail — the same 6 fail on the same tree without this change (clearPersistedQueryCache, readCachedOrg/writeCachedOrg; localStorage readonly-property issues in the bun env).

Note

This particular thread already healed itself: the other member's open created the session row, whose graft now overwrites the stale entry. It will not reproduce there anymore — the 1789 other entries are where the remaining risk is.

---

Summary by cubic

Stops trusting legacy agent-row agent-sandbox entries so previews start reliably for everyone. The client now resolves agent-sandbox only from the session registry, preventing stale map entries from blocking auto-start or pointing to reaped sandboxes.

• Bug Fixes
  • Filter agent-sandbox and legacy cluster keys out of the agent-row sandboxMap via withoutLegacyAgentSandboxEntries in VmEventsBridge.
  • Keep the thread sandbox map unchanged (it’s a live read-only view).
  • Behavior: if no session row exists, auto-start fires; if a session exists, its graft stays authoritative.
  • Makes 1,789 stale entries inert; no migration needed.

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