Slice 2: boot-time build parity assertion + smoke-gated hub swaps

[aarontrowbridge]

Spec: spec-20260905-045114-session-device-lifecycle (D3). Label: afk.

Important

Problem — A hub ran a stale build for two days while fixed releases
existed; a silent change in session-list query semantics between builds made
correct queries return empty. Nothing asserts build currency at boot, and the
only guard against a bad hub swap is human memory.
Approach — Every client and the hub assert their build (tag + sha) against
the release channel at boot, recording a distinct three-outcome result
(parity-ok | parity-drift | channel-unreachable — fail-open, but an assertion
that never ran is never mistaken for one that passed). The DB-snapshot boot
smoke becomes the only road to a hub swap: a staged swap without a passing
smoke run is refused.
Approaches considered — Forced auto-upgrade: rejected, a solo user may run
anything; the check is base, enforcement of upgrading is advisory. Premium-only
drift surfacing: rejected by the boundary test — incident happened on a solo
hub; drift awareness is needed before paying.
Scope — in: boot assertion (hub + clients), three-outcome record,
smoke-gate adoption as the swap precondition. · out: fleet posture surfacing
and alerting (slice 4), hub wedge root-cause (#775).

Acceptance Criteria

• Every boot (hub and client) records exactly one of parity-ok / parity-drift / channel-unreachable in its log
• Channel unreachable at boot fails open, logged as channel-unreachable, never as parity-ok
• A hub swap attempt without a passing smoke run is refused (and the refusal names the missing gate)
• A swap with a passing smoke run proceeds through the rename-only path with the hub never left down

Testing Decisions

Extend the smoke harness for the refusal path; a boot-assertion test with the
release channel mocked up / drifted / down (H2 family).

Key Decisions

• The smoke gate is base ops tooling — it guards base correctness, so it lives
  in the base, not the fleet overlay.
• Check vs enforcement are separate: the check always runs; forced upgrades
  never happen to solo users.

Constraints & Invariants

• The hub is never left down by any lifecycle operation (rename-only swaps,
  single-verb restart, ensure-up on every exit path).

Prior Art

ops restart/swap tooling (the 2026-08-30 incident contract); the DB-snapshot
smoke harness; the release-only gate and swap-archive asks in amicode#776.

Source

spec-20260905-045114-session-device-lifecycle (D3) · slice 2 of 4

[aarontrowbridge]

Status: implementation complete and gate-verified (PR #298) but HELD — same fork-retirement disposition as #294.