docs(sandbox): a box's host-service is as new as its last boot

Closed
SU
15d ago
+855-636

Stacked on #8704. #8704 rewrites the same paragraph in docs/cloud-sandbox-mismatches.md (the clipboard and ingress text), so this branch is built on #8704's head. The base is main; this PR's own change is the last commit. Merge after #8849, which defines the ATTACHMENT_PARTS_MIN_HOST_VERSION it names.

Summary

The docs step of the attachments plan (v6): replace the "frozen host-service" assumption in docs/cloud-sandbox-mismatches.md with how boxes actually update, on cold wake.

Why

On main, the clipboard paragraph says the paste path was "chosen over a new host endpoint because deployed sandboxes never update their baked host-service". #8704 removes that line but adds "a sandbox provisioned before that bundle still has the race", which assumes the same thing. Neither is true today. Design decisions were built on that assumption: the plan's version gate for attachment parts exists because boxes do update, but not all at once.

How it works (what the doc now says)

  • A new Lifecycle entry, "A box's host-service is as new as its last boot":
    • A bundle release repins every live environment (release.ts sets environments.bundleSha).
    • Every wake builds the claim from the environment (wakeCloudWorkspace → buildSandboxClaim).
    • On boot, superset-boot installs the pinned bundle when its hash differs (ensure_bundle).
    • A cold wake, a restart or a new box therefore runs the current host-service. A warm resume, or a box that never sleeps, keeps the one it last booted with.
    • Gate new host features on the reported version, as for a remote host.
  • The ingress paragraph from #8704 now points to that entry: a box gets the body-buffering fix at its next boot, and one that never sleeps keeps the race until it restarts.

I checked each claim against the code on main: packages/sandbox/bundle/rootfs/usr/local/bin/superset-boot (ensure_bundle), packages/trpc/src/lib/sandbox/claim.ts (SUPERSET_BUNDLE_SHA: environment.bundleSha), packages/trpc/src/router/cloud-workspace/wake.ts, and packages/sandbox/src/environments/release.ts (repins all non-archived environments).

Testing

Docs only. No code changes and no tests.

Known limitations

  • The clipboard paragraph still describes #8704's routing (storage for every non-local host). The desktop attachments PR (#8851) changes that routing: a relay-reached host goes back to filesystem.writeFile. That PR updates the paragraph, so the doc changes in the same PR as the behaviour.
  • I did not observe a live box take a new bundle on cold wake in this session. The claim comes from reading the code above.