Remote bootstrap: push the Linux agent on first connect, hand off on version mismatch #231

Parent

Part of #154 (remote agent sessions). Phase 3. Design doc docs/designs/remote-workrooms.md, Phase 3 "Agent bootstrap over the transport", Distribution Plan, and Next Steps item 4.

What to build

Workroom.app ships the Linux agent (#227) and pushes it on first connect, rather than baking provider images. One source of truth, no image maintenance, and it works for SDK-transport providers with no image concept.

• Detect whether the far side has an agent, which version, and which arch (uname -m), before any service connection.
• Push the matching ELF over the driver's stream and install it where the supervisor (Persistent remote agent: supervised serve, stdio relay and the container fixture #228) starts it from.
• Reconnect to an older agent under the hand-off policy (Agent hand-off: execve upgrade that keeps every shell, local Mac first #230): the running remote agent execves the pushed binary, and the same shells survive the upgrade with their pids and their exit codes.
• Refuse rather than kill. An agent that predates hand-off, or a pushed binary that fails its pre-check, leaves the old agent running, and the app negotiates with it over the versioned envelope.
• The bootstrap pushes a set keyed by driver once the far-side lifecycle shim exists (Distribution Plan). This milestone pushes only the agent. The shim is Phase 4.

Acceptance criteria

• First connect to a container with no agent installs the matching-arch agent and connects to it.
• Reconnecting with a newer app hands off: the same shells survive with the same pids and exit codes, and panes are repainted.
• An agent that predates hand-off, and a pushed binary that fails the pre-check, both leave the old agent running, and the app still connects to it.
• A deliberately crashed restore on the remote host is measured and recorded, as Agent hand-off: execve upgrade that keeps every shell, local Mac first #230 does locally.
• Reconnecting with the same app version pushes nothing.

Blocked by

#227 (the artifact), #229 (the app-side transport), #230 (hand-off).

Filed by Claude Code at the owner's request, 2026-09-24.