Fleet Panel: setup wizard + fleet lifecycle (create/add/remove/dismantle) #354

Acceptance Criteria

Create Fleet

• "Create Fleet" button visible when standalone; launches the wizard
• Topology choice: "This machine is the server" or "A remote machine is the server"
• SSH target input: text input for SSH alias or user@host; validates connectivity
  with a test command (ssh <target> echo ok)
• Pre-flight checklist (rendered live, step by step):
  • SSH reachable (green check or red X with error)
  • Opencode binary present on remote (if missing: offer to SCP it)
  • Target port available on remote (lsof check)
• Remote configuration (over SSH):
  • Writes ~/.amico/ops/fleet/fleet.json with role: "server"
  • Installs guard script to ~/.local/bin/
  • Starts canonical server as launchd service (macOS) or systemd (Linux)
  • Generates fleet token, stores at 0600
• Local configuration:
  • Writes fleet.json with role: "client" + canonical coordinates
  • Installs guard + tunnel plist
  • Stores fleet token locally
• End-to-end validation: tunnel connects, health probe passes, topology graph
  updates to show two nodes with solid connection line
• Failure handling: any step failure shows specific error + suggested fix; wizard
  does not proceed past a failed step; user can retry or cancel

Add Machine

• "Add Machine" button in topology section (visible when fleet exists)
• Same SSH validation + pre-flight as Create, but skips server setup
• Configures new machine as client; node appears in graph on success

Remove Machine

• Node popover → "Remove from Fleet" action
• SSHs into target, writes {"role": "standalone"} to fleet.json, unloads
  tunnel/guard; node disappears from graph
• Cannot remove the server node (shows explanation: dismantle instead)

Dismantle Fleet

• Offered when removing the last client, or via overflow menu
• Stops canonical server on remote, reverts all machines to standalone
• Removes canonical from fleet.json (not just sets role to standalone) — this is
  what distinguishes "dismantled" from "disconnected"
• Topology graph returns to single-node standalone state with "Create Fleet" button

Reconnect Fleet

• When fleet.json has role: "standalone" BUT canonical coordinates are present
  (user went standalone but the fleet still exists), panel shows "Reconnect Fleet"
  button instead of "Create Fleet"
• One click: validates SSH/tunnel connectivity to the stored canonical, switches role
  back to client, reinstalls tunnel, validates end-to-end
• If validation fails: shows error with option to retry or dismantle (remove canonical)

Reconfigure

• Edit canonical coordinates (host, port, SSH alias) from the panel
• Validates new connection before committing the change
• Updates fleet.json on both machines; restarts tunnel

Testing Decisions

• Unit test: fleet_wizard.test.ts — mock SSH execution (child_process.spawn), verify
  correct command sequences for each flow (create, add, remove, dismantle)
• Unit test: pre-flight check logic — given SSH success/failure, binary present/absent,
  port available/taken → correct checklist state
• Integration test: full wizard flow with mocked SSH → fleet.json written correctly on
  both sides, topology message emitted to webview
• Manual verification (HITL): test against a real remote machine before merge

Key Decisions

Constraints & Invariants

• Server survives client disconnect: the canonical server is a system service
  (launchd/systemd) with NO dependency on any client or editor being connected. Sessions
  and solves continue running when all clients close. Zero connected clients is normal.
• SSH commands MUST use the user's SSH config (-F ~/.ssh/config or default) — never
  bypass their key/host setup
• Wizard MUST NOT store SSH passwords or private keys — it uses whatever auth the user
  has configured
• Fleet token generated with crypto.randomBytes(32).toString("hex"); stored at 0600
• All remote file writes use atomic tmp+mv pattern (same as fleet_registry.ts)

Additional Acceptance Criteria: Server Independence

• Canonical server installed as a system service (launchd on macOS, systemd on
  Linux) — NOT as a child process of any VS Code instance or editor session
• Sessions and solves launched on the server continue running when ALL clients
  disconnect (close laptop, quit VS Code, lose network)
• On client reconnect, the panel/dropdown reflect the current state of sessions that
  ran while disconnected (completed solves show results, running sessions show progress)
• The server process has NO dependency on any client being connected — zero clients
  connected is a normal operating state

Source

Part of #350
Blocked by #352, #353
ADR 0007: docs/adr/0007-fleet-panel-and-profile-ui.md