Add buzz-backend-sprites: a Fly.io Sprites backend provider

[yjc801]

Adds buzz-backend-sprites: a remote-agent backend provider that runs Buzz managed agents in Fly.io Sprites — persistent Linux VMs that hibernate when idle and bill compute per second while awake. One agent, one sprite.

Nothing in the desktop changes. Provider discovery already scans ~/.local/bin for buzz-backend-*, so installing the binary is the whole integration:

cargo build --release -p buzz-backend-sprites
install -m 755 target/release/buzz-backend-sprites ~/.local/bin/

Design, and why

Choices that were forced rather than picked, each documented in the crate's [L3] conformance README:

• A detached TTY session, not a Sprites Service. The service runtime restarts a process that exits and treats even a TERM as a crash, so an owner !shutdown would be resurrected — an I5 violation. Nothing restarts the harness here; an exit ends the session and the sprite hibernates to storage-only billing. For the same reason inactivity_seconds: 0 (indefinite lifetime) is refused: it needs a supervisor that restarts crashes without resurrecting intentional exits, and none exists while the harness clean-exit contract is unpinned (Known Defect 6).
• The task lease is load-bearing, not belt-and-braces. An agent's relay connection is outbound, and sprite idle detection counts only inbound traffic, exec sessions, and tasks — measured: a quiet detached session goes warm in ~30s. A paused agent is unreachable forever, since nothing external would wake it. The launcher holds a 5-minute Tasks-API lease refreshed every 60s and releases it when the harness exits.
• Secrets travel as WebSocket data, never in a URL. The exec API accepts env=K=V query parameters; URLs reach access logs. The resolved environment is streamed as stdin frames into a /dev/shm file (RAM-backed, 0600, named per attempt) that the launcher sources and deletes before execing the harness. Never the sprite's API-readable environment map, never the durable filesystem — that one is continuously synced to object storage and captured by checkpoints. The exec URL builder has no env parameter at all, and a test pins its absence.
• flock is the at-most-one-live-agent fence. Held across exec for exactly the harness's lifetime, so the kernel arbitrates. This replaces the Kubernetes binding's UID+resourceVersion preconditions.
• Zero destructive substrate calls. On a persistent VM every stale property is re-appliable in place, so the rows that delete residue collapse into "reprovision and start". The Substrate trait cannot express a delete and Action has no delete variant. Stated cost: deleting an agent leaves its sprite paused (storage-only billing) until sprite destroy buzz-agent-<12hex>.
• The provision fingerprint lives inside the sprite, written atomically as the last provision step — a checkpoint restore rolls artifacts and their record back together, which a control-plane label could not do. Sprite labels carry identity only (marker, binding version, full 64-hex pubkey — no truncation, since sprite labels have no length cap).

Reused from buzz-backend-kubernetes where the spec is substrate-neutral: the wire contract, nsec-derived identity, the three-tier env builder (clear-then-write authoritative tier, respond-to gate, POSIX key rule), and the pure-classifier + fake-substrate test shape.

Testing

132 tests (128 unit + 4 golden wire fixtures), clippy clean, shellcheck clean. Fixtures drive the built binary over a real pipe with credentials poisoned, so a fixture that reaches the API fails loudly. Live tests are gated on BUZZ_SPRITES_LIVE=1, create one throwaway sprite each, and delete it.

Verified against the real platform through the release binary: cold create → provision → confirmed start (4.2s); a second deploy no-ops in 0.7s with zero writes; TERM then redeploy revives with a fresh generation; a config change against a running agent correctly does nothing (edits land on the next generation); the same change against a stopped agent reprovisions; a harness that exits during startup is reported in-band with the generation that ran and the probe's own tokens.

Three bugs surfaced only on the live path, each now covered by a regression test with the fake made faithful so it cannot hide them again:

1. A fresh sprite polled its full 600s deadline instead of provisioning — probe.sh only exists after provisioning, so waiting for a report was waiting forever.
2. The loser of a create race provisioned the winner's sprite (two tarball extractions into one directory is not convergence). It now observes the winner.
3. install -m 755 /dev/stdin fails when the destination already exists, so every reprovision died where the first install passed. Assets now write-chmod-rename.

Notes

• CI: the crate is added to Justfile:test-unit and scripts/run-tests.sh. Nothing upstream runs workspace-wide tests, so a crate absent from both lists has its suite silently skipped.
• Deliberately not touched: the sidecar bundling lists (release/canary workflows, bundle-sidecars.sh, tauri.conf.json externalBin). v1 distributes via ~/.local/bin; bundling is the upstreaming conversation.
• Credentials are ambient only (spec I2). Prefer an API token from sprites.dev/account exported as SPRITE_TOKEN; the keychain fallback exists for Finder-launched desktops, but on current sprite CLI versions that entry is wrapped and the API rejects it — the client says so and names the source rather than reporting a bare 401.
• Runtime trust delta, stated: with sprig_sha256 set, the runtime is provenance-pinned to that exact artifact. By default each download is verified against the digest the release publishes beside it — transport integrity, with trust rooted in the GitHub release, so a re-published sprig-latest is trusted automatically (there is no provider-baked pin: the rolling tag moves within hours and a baked digest wedges every deploy). The sprite base image is Fly's and upgrades outside this provider's control.

🤖 Generated with Claude Code