feat(box): deliberate user-triggered box image update

[pythonlearner1025]

A user can now click a button in My machine to deliberately update their
box to the deployment's current image. Three layers, one PR.

Two live bugs found on blitzos-dev while building this made the flag a dead
letter on canary; both are fixed here.

1. The host updater could never update a canary box

The emitted updater refused every https ref outright — "a tarball ref cannot
be pulled in place". Canary pins BOX_IMAGE_REF to an https R2
manifest.json, so no canary box could ever update in place.

The first boot already knew how to install that image, so the updater was
about to carry a second copy of the same pipeline: download every part, check
each digest, concatenate, check the whole, docker load. Two copies of a
verification pipeline are two chances to verify differently. So the pipeline
became one host script, /usr/local/sbin/blitz-box-image, written once by the
bootstrap and invoked by both callers. Its exit codes are the interface —
10 download, 11 digest, 12 load, 13 bad manifest — and the updater
turns them into the contract's outcomes.

The pull-first invariant now holds on both paths and is pinned on both: the
image is acquired and verified before the running container is touched, so
every acquire failure leaves the workspace exactly as it was. A new image that
will not start still rolls back.

2. The updater could not keep its own credential fresh

A box access token lives 15 minutes (ACCESS_LIFETIME_MS) and the timer runs
every 5, but nothing on the VM keeps /var/lib/blitz/box-credential.json
fresh. The Go client inside the container rotates only in reaction to its own
401, which needs somebody to run blitz-cred. On a quiet box the on-disk token
expires and every later poll 401s for good.

Measured live: file mtime 02:03, 401 invalid box access token on every poll
from 02:20 onward, while blitz-cred and the gateway kept working — because
blitz-cred self-heals on its own 401 and the gateway never reads the
credential at all.

The updater now spends the refresh token itself against POST /oauth/token,
under the same flock (box-credential.lock) the Go client takes, and writes
the rotation back. It must be able to do this while the container it is
about to replace is broken — which is exactly when nothing inside the box can
help. Writing the file also keeps it fresh for every other reader on the
machine as a side effect.

3. Contract, route, UI

Contract (box config v1, fixtures + both conformance suites together).
Three outcomes for the stages the manifest path can fail at —
download-failed, digest-mismatch, load-failed — an optional tag on the
update result, and boxImageSha256 on the config.

tag is the load-bearing addition. Under a manifest pin the ref is
byte-identical across rebakes while the tag inside it moves, so comparing
refs would read every box as current forever. tag is the CONCRETE image the
container runs once the attempt settled — which is the OLD image whenever the
attempt changed nothing.

boxImageSha256 closes a gap I found on the way: the updater was checking the
archive against the digest the manifest declares, which is self-certifying —
whoever serves the manifest serves the digest beside it. The first boot never
had that weakness, because its digest is baked in from the control plane. Now
the updater gets the same pin over the same separate connection and passes it
to the installer as the fourth argument the first boot already used. An archive
that is internally consistent and still not the image this deployment pinned is
refused, container untouched.

One subtlety that bit: the parsed config moved from a tab-separated line to one
field per line. TAB is IFS whitespace, so read -r collapses an empty column —
and boxImageSha256 is empty on every registry deployment, which silently
shifted the origin and the update flag one field left. Caught by the host
suite, and it is why that suite runs real bash.

Route. POST /machines/:machineId/box-update, the machine-verb shape and
gate of the lifecycle verbs beside it (core/machine-access.ts, scope own).
It names ONE machine whoever calls it. The existing
POST /workspaces/:id/box-update stays the deliberate admin fan-out — a user
who clicked a button in their own machine dialog did not ask to restart a
colleague's work, and this route can never become that by accident.

MachineView gains boxImage, boxImageTarget, boxUpdateRequested and
boxUpdateOutcome. Migration 0046 adds the two columns, and armPhoneHome
seeds the image at every VM provision — the one moment the answer is known
exactly, since the same runtime.vars renders the user-data that boot
installs. Without it, a machine nobody had ever asked to update would have no
reported image, and the button's own label would have no answer.

UI. A Box image section in the My machine dialog: settings-surface cfg-
classes only, no new CSS. It shows both images so "update available" is
checkable rather than asserted, then one status line and one button that
confirms first — "This restarts your machine. Running terminals and agents
stop."

The judgement is a pure module (src/box-update-state.ts) rather than markup,
because the interesting part is which of seven things is true. Telling a user
"up to date" about a machine that is behind, or handing a button to a host that
can never install an image, is worse than telling them nothing.

Honest limitations

• Existing VMs keep their old emitted updater. The script is baked into
  user-data at create time. Only machines created after this deploy can
  self-update. Every pre-existing canary box, blitzos-dev included, answers
  unsupported to the first request it is given — and the UI renders that
  verdict rather than hiding it: "This machine's host cannot update in place.
  Recreate it to move to the new image." The flag, the route and the UI work
  against old boxes today; that message is what they get.
• The user-data budget got tighter. Hetzner caps cloud-init user-data at a
  hard 32 KiB and does not compress. A heavy manifest-mode create was 25.4 KiB
  and is now 30.4 KiB — 2.4 KiB of headroom, down from 7.3 KiB.
  test/bootstrap.test.ts pins a 2 KiB floor so the next feature that emits
  bash finds out there rather than as a 413 on a real create. Buying the
  headroom back means shipping the host scripts in the box image instead of in
  user-data (plans/MEMBER-MACHINES.md §5a) — a box-image change and a
  rebake, so it is the next step and not this one.
• No microVM path. packages/microvm-host/ has its own guest lifecycle and
  no update path; this is the cloud-VM providers only.

Tests

test/box-update-host.test.mjs runs the emitted updater and the emitted
installer in real bash, against a real control plane over real curl, with a
scripted docker and a stand-in R2 serving a real gzip archive split into
digest-checked parts. New cases: the manifest happy path (asserting the exact
bytes that reach docker load), a part whose digest does not match, a part
that 404s, a docker load that refuses, an image already in the store, and
both credential-rotation paths, and an archive that passes its own manifest but
not the deployment's pin.

test/box-update-conformance.test.mjs additionally pins that exactly one copy
of the manifest parser is emitted and that both callers reach it by one path.

Gates

npm run typecheck ✅ · npm run lint:gate ✅ (74 findings, baseline 74) ·
npm test ✅ — control-plane 672 passed, webapp 707 passed.

Caveat worth naming: on a contended box, four packages/webapp Lody suites
time out in startLodyHarness (beforeAll), which is the known daemon-suite
flake. Re-run isolated they pass or skip; this branch touches nothing under
webapp/src/lody.

🤖 Generated with Claude Code

https://claude.ai/code/session_013voh4zgczP2jmPrS2ERrav