Update when agents finish: deferred self-update for web/VPS and desktop

[SawyerHood]

Fixes #477

bb running unattended (VPS via npx bb-app, or the desktop app with an owned local runtime) can now apply updates without interrupting running agents: schedule the update from the toast, and it applies at the first moment no agents have been running for a 45s quiet period.

Web / VPS (npx bb-app)

• The "bb-app update available" toast forks on live agent activity. At rest: a single Update now (the server skips the quiet period when provably at rest — no busy threads and no queued follow-ups awaiting the auto-send sweep). While agents work: Update when agents finish (defers) alongside Update now (mode now: applies straight after staging, interrupting agents at the user's explicit request; also escalates an already-waiting schedule) (when the server runs under a capable launcher; otherwise the current "restart bb-app" copy is unchanged). While scheduled, a persistent toast shows the target version with Cancel update; after the swap, a "bb is now running vX" toast confirms.
• POST/DELETE /api/v1/system/update/schedule + selfUpdate state on /system/version. The intent lives server-side, so closing the browser tab doesn't lose it.
• The server stages npm install bb-app@<latest> under <dataDir>/self-update/ while agents keep running (a staging failure surfaces as an error toast before anything restarts), writes a sentinel file, and — once threads.status IN ('starting','active','stopping') stays empty for 45s — exits with a reserved code (75).
• The bb-app launcher, seeing that exit code plus a valid sentinel, stops the daemon and restarts both children from the staged package root (~5s downtime, verified e2e). The sentinel is consumed one-shot; if the staged version fails to become healthy, the launcher tears it down and restarts the current version.
• Safety gating: the launcher advertises the protocol via BB_SELF_UPDATE_PROTOCOL=1 only in the supervised full-stack path — never for dev servers, standalone bb-server, old launchers, or desktop-owned runtimes (electron-updater owns those). A pending schedule survives server crashes (resumed from the sentinel on boot); stale staged installs are pruned on boot.

Desktop

• "Desktop update ready" offers Relaunch when agents finish (primary) / Relaunch now only while agents are busy on a shell-owned runtime; at rest (or attached to a remote server) it keeps the plain Relaunch. Scheduled state shows as a toast with Cancel update.
• The Electron main process polls the new GET /api/v1/system/agents/activity endpoint (same busy-thread definition as the server-side watcher, shared via agent-activity.ts) and defers quitAndInstall() until the quiet period passes. Unreachable server counts as busy; the deferral auto-cancels if the downloaded update goes away; quitting the app still installs on quit as before.
• Contract changes are backward compatible: new BbDesktopInfo fields and API methods are optional, so a new SPA against an old shell degrades to today's behavior.

Verified

• Live e2e of the full VPS loop: local build labeled 0.0.1 → schedule → staged install of the real published bb-app@0.0.27 → 45s quiet → launcher swap → back up as 0.0.27 in ~5s, sentinel consumed. The e2e also exercised the failed-swap rollback and boot-time staging cleanup, and caught two real bugs now fixed with regression tests: npm_execpath poisoned by pnpm, and symlinked staged paths (/tmp → /private/tmp) silently killing the daemon's argv-gated entrypoint.
• New tests: 9 self-update service tests (in-memory SQLite, injected installer/clock), 3 launcher supervision swap tests, 5 desktop deferred-install controller tests, agent-activity route test, npm-resolution unit test. Full repo typecheck passes.
• Desktop deferred relaunch is unit-tested but not e2e'd (needs a packaged shell + update feed); the only untested seam is electron-updater's own quitAndInstall, which the existing Relaunch button already exercises.

🤖 Generated with Claude Code

[SawyerHood]

Handoff notes (state as of 350c1ffdd)

Everything through the quiet-period cut and blank-page mitigations is committed and pushed. One investigation is unresolved:

Open: blank page after the post-update auto-reload

Reproduced twice in a real browser (Playwright against the tarball e2e setup: local build labeled 0.0.1 updating to the published 0.0.27):

• After the swap, the tab auto-reloads and lands blank: fresh index.html served (200), the module asset 200s when re-fetched later, but #root never mounts and module scripts don't retry — stuck until a manual reload, which then works every time.
• Best evidence from the instrumented run: the page went mounted=true → mounted=false ~30s after the swap with only one load event recorded — i.e. the teardown/navigation began but the new document never finished loading. No console errors, no ≥400 responses captured at that moment.
• Two mitigations landed in eedbda554/350c1ffdd but did not fix the e2e repro: a pre-reload probe (fetch("/") until ok) and a one-shot boot watchdog in index.html (reload if #root empty after 10s). Important caveat: in the e2e the post-swap frontend is the published 0.0.27, which doesn't contain the watchdog — so the watchdog is untestable in this setup and may well be sufficient for real forward updates. The published-server logs also show listDueAutomations schema errors (old code on the branch's newer DB — a downgrade artifact of the test trick, not a real-update condition; possibly related to the blank load).

Next steps when picking this up: re-run the browser repro with the same build on both sides (e.g. two locally-built tarballs 0.0.1→0.0.2 via a local registry or BB_UPDATE_REGISTRY_URL-style override) to remove the downgrade artifacts; if it still reproduces, capture the network waterfall of the failing document load itself.

Repro harness: build + pack bb-app, npm install the tarball to a prefix, set its package.json version to 0.0.1, run with BB_DATA_DIR=/tmp/... BB_SERVER_PORT=4990 BB_HOST_DAEMON_PORT=4991, click "Update now" in the toast.

Everything else is verified

Server 995/995, launcher 46/46, app 1282/1282, desktop controller 5/5, typecheck 40/40. The swap itself (staging → exit 75 → launcher swap → rollback-on-failure → crash resume) is e2e-verified in the terminal; the blank page only concerns the browser tab's landing after completion.

🤖 Generated with Claude Code