Peer fleet: two-way serving, heartbeat sync, and live health indicators

.github/workflows/ci.yml

@@ -95,6 +95,13 @@ jobs:
     needs: [build-binary]
     steps:
       - uses: actions/checkout@v7
+        # full history: the #1346 additive-invariants-gate diffs the enroll/guard
+        # set vs `git merge-base HEAD <base>` — a shallow (depth-1) checkout has no
+        # common ancestor, so the merge-base is empty and the gate (correctly)
+        # refuses to pass an UNVERIFIABLE AC1 under INVARIANT_STRICT=1. Full history
+        # lets it actually verify. (#1346)
+        with:
+          fetch-depth: 0
       - uses: pnpm/action-setup@v6   # version pinned by packageManager in package.json
       - uses: actions/setup-node@v7
         with: { node-version: 20, cache: pnpm }
@@ -112,6 +119,16 @@ jobs:
         run: node packages/extension/scripts/assert_packaged_cli.mjs
       - name: fleet-gate — guard + tunnel template sane (#324)
         run: bash packages/extension/scripts/assert_fleet_guard.sh
+      - name: additive-invariants-gate — peer studios stay additive (ADR 0027, #1346)
+        env:
+          INVARIANT_STRICT: "1" # CI must be able to verify AC1 — an unverifiable base is a hard fail
+        run: |
+          # AC1 diffs the enroll/guard set vs the MERGE-BASE with the base branch.
+          # A shallow checkout may not carry the base branch, so fetch it here —
+          # this also persists the ref for the later vitest subprocess in the
+          # `pnpm -r run test` step, which runs the same gate.
+          git fetch --no-tags --quiet origin "${GITHUB_BASE_REF:-feature/free-tier-fleet}" || true
+          bash packages/extension/scripts/assert_additive_invariants.sh
       # Pasqal python provisioning gate, source lane: the SHIPPED connector
       # assets must provision a working interpreter (real venv + pip + SDK
       # import at the pinned version + validator env-guard smoke). Guards the

CONTEXT.md

@@ -175,6 +175,26 @@ source)
 The per-machine stance for where Sessions are served from, in three values. `standalone` — this machine spawns and owns its own chat server, detached and survivable so it outlives an extension-host reload and is re-adopted rather than dying with the editor (the default; the only mode that ever spawns). `server` — this machine runs the Canonical Server as a system service and the panel attaches to it. `client` — this machine never serves; the panel attaches to the Canonical Server through a Managed Tunnel. Determined by `~/.amico/ops/fleet/fleet.json` (no file = standalone). Machine-scoped, never synced.
 _Avoid_: profile, spawn vs attach (as concept names)
 
+**Capability**:
+An orthogonal, open tag describing what a machine is *for* — distinct from its serve-stance (Server mode). Two known, behavior-adjacent tags: `compute` (a solve-target hint — declared-but-inert until a fleet-peer executor exists, an explicit non-goal today) and `roaming` (a transport hint that defaults a machine to Tailscale). Any other tag is a free descriptive label with no behavioral meaning; it round-trips verbatim. A Capability never overrides the guard/tunnel/hub decision — Server mode stays the only serve-stance authority (ADR 0026).
+_Avoid_: role (that is Server mode), type, class
+
+**Roster**:
+The amicode-owned, fleet-wide device list on the Canonical Server (`~/.amico/ops/fleet/roster.json`) — one row per machine, each machine the single writer of its own row (a registry/heartbeat model). A row is `{ machine_id, name, server_mode, capabilities[], sshAlias, transport, last_report, health, device_type? }` with `health ∈ {reachable, degraded, down}`; the UI labels `server_mode` as "role" and `last_report` as "last-seen". Surfaced at `GET /amicode/roster` (read) + `POST /amicode/roster` (self-report), on the proxied `/amicode/*` namespace so a client sees it through the host proxy. Separate from `fleet.json` (untouched — one-parser invariant, ADR 0023) and from the per-machine projection (which carries only this machine's topology). ADR 0026.
+_Avoid_: fleet.json (a different, per-machine file), device table, inventory
+
+**Device identity**:
+The self-reported, human-facing half of a Roster row: the machine's friendly **name** (macOS `scutil` ComputerName / Linux `PRETTY_HOSTNAME` / an explicit `amicode.deviceName` override, else the prettified hostname) and its **device type** (`server | desktop | laptop`, an open set — macOS `system_profiler` model / Linux chassis / an `amicode.deviceType` override, else absent). Derived once by logic shared between the enroll producer and the sidebar self-row so a machine and its peers cannot disagree; absent/undefined values fall back honestly (type → `server_mode`), never fabricated. The Canonical Server self-registers its own device identity keyed by `machine_id = canonical.host`. Refreshed by re-enroll. ADR 0028.
+_Avoid_: hostname (the raw FQDN, not the friendly name), machine_id (the identity key, not the display name)
+
+**Machine**:
+One computer in the Fleet — the unit a Roster row describes and Enroll brings in.
+_Avoid_: device (a Device is a QPU or emulator behind a Connection), node
+
+**Focused machine**:
+The one Machine the window's working surfaces are scoped to, chosen in the FLEET section and defaulting to this machine; a UI selection, never a Roster change.
+_Avoid_: active machine, selected device
+
 **Fleet config**:
 The file at `~/.amico/ops/fleet/fleet.json` that declares this machine's fleet role and the canonical server's coordinates (`host`, `port`, `sshAlias`). No file on disk = standalone. The guard script, extension, and installer all resolve role from this file — never from a hardcoded hostname.
 _Avoid_: fleet.toml, fleet settings (those are VS Code settings, a different thing)
@@ -184,13 +204,17 @@ The one chat server that owns the fleet's Session store — the single writer ev
 _Avoid_: master, primary, host
 
 **Fleet**:
-The user's machines acting as one logical studio: exactly one Canonical Server plus zero-or-more clients, all attaching to the same Session store.
+The user's machines acting as one logical studio. Two topologies, both "the Fleet": the **single-store** shape — exactly one Canonical Server plus zero-or-more clients, all attaching to the same Session store — and the **independent-peer** shape (ADR 0031/0034), where **Peer studios** each own their own Sessions and reach each other by Observe/Control rather than a shared writer. A keeper/canonical coordinate owns roster and bootstrap authority in both.
 _Avoid_: mesh, cluster
 
 **Go Standalone**:
-The user-invoked mode switch from `client` to `standalone` — the machine leaves the fleet and serves itself permanently. Not an escape hatch: a first-class choice. Sessions made locally stay local. Re-enrollment in a fleet is a separate flow (Enroll, deferred).
+The user-invoked mode switch from `client` to `standalone` — the machine leaves the fleet and serves itself permanently. Not an escape hatch: a first-class choice. Sessions made locally stay local. Re-enrollment in a fleet is a separate flow (Enroll).
 _Avoid_: local fallback, offline mode, degraded mode
 
+**Enroll**:
+The idempotent, verifiable flow that brings one machine into a fleet — the inverse of Go Standalone. Server-first, the standard join-token pattern: `amico fleet enroll --as-server` provisions the durable hub service, mints the Fleet token, and emits a **join token** (`{ canonical, fleet_token, transport_hint, pin_version }` — a secret, 0600, never logged). A client redeems it with `amico fleet enroll --join-token`: it rejects a pin-mismatched token before writing anything, then writes `fleet.json` (role + canonical only — capabilities go to the roster row), registers its roster row, sets the transport (`tailscale` when the machine roams, else the token's hint), runs the installer (which installs the never-fork guard), and **verify-attaches** — reporting success only after a live probe of the just-set transport passes. A re-run repairs in place; a failed verify surfaces the specific cause with its fix and never reports a false success. `amico fleet enroll` is a distinct verb from the session registry — it writes membership, not session records.
+_Avoid_: register (as the verb name), pair, handshake
+
 **Fleet token**:
 The shared secret authenticating a client to the Canonical Server's data routes — minted when the fleet server is enabled, stored at 0600, handed to clients during the ssh-based setup flow. The sibling of the per-boot server password (ADR 0002): that guards a spawned server its extension owns; this guards the service no extension spawns.
 _Avoid_: API key, password
@@ -215,6 +239,30 @@ _Avoid_: keepalive, lock, busy flag
 The interval after an extension-host teardown during which a detached standalone server stays alive awaiting re-adoption. On expiry with no adoption and no active-work pin the server self-exits and deletes its handshake; a reload re-adopts well within it, a genuine quit does not.
 _Avoid_: timeout, linger period
 
+**Peer studio**:
+An independent serving peer whose Sessions it owns, observed or controlled from another machine's window. The independent-peer complement to the single-store Canonical Server: Peer studios do **not** share one Session store — each owns its own, and cross-machine access is by Observe/Control, never a shared writer (ADR 0031, 0034).
+_Avoid_: remote server (that is transport), replica, node
+
+**Observe (peer observation)**:
+Read-only visibility into a Peer studio's Sessions from another machine — its session list, one session's history and events. Unlocked by **trust** (a reader token seeded at Enroll), not by a Control grant. A peer-owned session's reads route to the owner with the owner's own reader token; a write never routes on the observation path (#1537).
+_Avoid_: view, mirror, follow, spectate
+
+**Control (peer control)**:
+The authority to *drive* a Peer studio's Session from another machine — send prompts, archive, delete. A strictly higher unlock than Observe, carried by a persisted per-peer **Control grant** (`control` scope) and re-armed each session (never auto-restored). Fails closed: no grant, revoked, transport-down, or observe-only → the write is denied, never served locally.
+_Avoid_: write access, remote admin, takeover
+
+**Enable control**:
+The explicit, per-session act that arms Control on a peer. For a **self-owned** peer with verified management access it is one click on the controlling machine, authorized at Enroll — no target-side prompt, since a headless peer has no window. For a **shared** peer it is the far side of a request→approve handshake routed to the peer's Lifecycle-admin authority.
+_Avoid_: grant (that is the record), connect, claim
+
+**Lifecycle-admin authority**:
+The machine/operator that may mint, revoke, and re-admit a Peer studio's grants — the `lifecycle-admin` scope, **not** a superset of Control. Seeded at Enroll (the enroller is recorded as the peer's `authorityIdentityKey`), so a headless peer's Control can be approved from a UI-bearing machine; the peer itself only *enforces* presented tokens, never rendering approval.
+_Avoid_: owner, root, keeper (keeper is roster/bootstrap coordination, a different authority)
+
+**Driving**:
+The live state in which one window is authoring turns on a Peer studio's Session under active Control, marked by a persistent "driving `<peer>`" banner so control is never ambient.
+_Avoid_: remote session, controlling (as a noun), piloting
+
 ### Surfaces
 
 **Work Column**:
@@ -238,7 +286,7 @@ A sandboxed ES-module card rendered in an iframe within Home. Authored by the ag
 _Avoid_: Card (ambiguous — the UI has many cards), tile (as the concept name — tile is a size class)
 
 **Sidebar**:
-The webview in the VS Code activity bar container, showing project navigation and system status. Contains action buttons (open chat, create project), a session-aware unified project tree (Research Projects with lifecycle metadata expanding into file trees; Dev Projects as plain expandable folders), and a collapsible fleet section (deferred). The sidebar is navigation chrome — it follows the active session's project binding but never drives session switching. Single-clicking a file opens it as a tab in Preview (the multi-document file workspace in the side panel); double-clicking opens a native VS Code editor tab.
+The webview in the VS Code activity bar container, showing project navigation and system status. Contains action buttons (open chat, create project), a session-aware unified project tree (Research Projects with lifecycle metadata expanding into file trees; Dev Projects as plain expandable folders), and a collapsible fleet section that is **read-only** toward the fleet — a glanceable list of Machines from the host-owned Roster (one row per machine: name, `server_mode` labeled "role" + capability chips, a `reachable`/`degraded`/`down` health indicator, and `last_report` labeled "last-seen"), marking the Focused machine. It offers navigation actions only — connect, focus, Troubleshoot, Add machine, Refresh — and never writes fleet config or Roster rows. The section refreshes on posture-change and shows an honest empty/degraded state when the roster host is down — never a fabricated list (#1321, ADR 0026). The sidebar is navigation chrome — it renders state and navigates, never mutating fleet config or driving session switching. Single-clicking a file opens it as a tab in Preview (the multi-document file workspace in the side panel); double-clicking opens a native VS Code editor tab.
 _Avoid_: Explorer (VS Code's native file explorer is separate), Panel (the in-app dismissible drawer is a different concept)
 
 **Preview**: