Repository navigation
Slice 2: boot-time build parity assertion + smoke-gated hub swaps #295
Description
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
Activity
aarontrowbridge commentedon Sep 5, 2026
Status: implementation complete and gate-verified (PR #298) but HELD — same fork-retirement disposition as #294.