keyrelay/.agents/phases/todo/03_session_takeover/02_takeover_funnel.md

Task 02 — X: hand the bridge over through the funnel

Phase: 03_session_takeover · Source: TODO.md:6 — "Need to be able to take control if another session is connected…" Story: n/a

Objective

One authenticated frame from the pending claim — X — takes the bridge: the incumbent is told (E12), the release funnel runs, the board ends up disarmed, and only then is the claimant adopted as the controller. The handover is a link change that the rest of the firmware recognises, not a silent substitution of one socket for another.

Work

1. src/proto.h — Cmd::Takeover for a lone X, documented in the header comment's direction table: c -> d X claim this bridge for myself; requires authentication, and nothing else is honoured on a claim socket. proto::formatError unchanged; add kErrTakenOver = 12 to control_server.h ("your session was taken over by another controller") and name it in the error list comment.
2. src/control_server.cpp — the handover, in this order and no other:
   1. sendError(12, "session taken over") on the incumbent socket, so its page can say why it stopped. It is best-effort: an unreadable incumbent must not block the handover.
   2. closeLink("taken over") on the incumbent — the existing funnel. closeLink() already disarms and releases for anything that reached the WebSocket phase (that is bug 10's fix; do not re-narrow it here) and calls _onLinkChange(false), which in main.cpp runs releaseEverything(). This must happen before adoption, so the newcomer can never inherit a held key or an armed bridge.
   3. Promote the claim: move its conn into the controller slot, _phase = WebSocket, _authed = true, _controllerSeen = true, _lastInboundMs = millis(), _connectedAtMs = nowMs, reset the controller's reader, then OK + sendStatus() and _onLinkChange(true).
   4. Clear the claim slot completely (_claimAuthed = false, reader reset, buffers zeroed) so a stale claim cannot be promoted twice.
   • arm() is not called, and nothing on this path can reach it. State that in a comment at the top of the handover function and make the function's name say it too (handOverClaim() or similar — not takeover() which reads like an arm).
   • If the incumbent is already gone by the time X arrives, the promotion still runs through the same steps (the funnel is a no-op when disarmed), so there is only one path.
   • _rejected keeps meaning "a socket was turned away", and a successful takeover gets its own counter (_takeovers), reported in the status frame (task 03) — counters only, never addresses or identities (invariant 4).
3. src/main.cpp — onMessage() handles Cmd::Takeover for the case where an existing controller sends X (a no-op with OK, documented: you already hold it) — do not let it fall through to E6 — and fillStatus() publishes the counter.
4. src/config.h — nothing new; kClaimTimeoutMs from task 01 bounds the claim's life.

• ASSUMPTION: X is honoured only on a claim socket (or is a no-op from the controller). It is not a general command, so a controller cannot use it to reset its own session.
• ASSUMPTION: the incumbent gets no warning window and no veto. Its operator is by definition absent — that is the situation the TODO describes — and a veto held by an absent tab is the lockout we are removing. The protection is that the claimant needed the passphrase, and that the board lands disarmed.
• ASSUMPTION: E12 is a new code rather than reusing E3. E3 means "you were refused"; E12 means "you were dropped". One of those should be alarming on the incumbent's screen and the other should not.

Testing & Quality

• tests/test_proto.cpp: X parses to Cmd::Takeover; X with trailing bytes is Cmd::Bad; E12 formats; the render/parse round trip covers it; the existing 2 327 checks around chord labels and state specs stay exactly as they are.
• tests/test_relayctl.py — the three source pins named in the phase overview: funnel before adoption, no arm() reachable from the X path, no promotion without _authed. Written the way the existing pins are written (a named assertion per sentence, with the sentence in the output) so the suite says out loud what it checked.
• Device (best effort, one attempt): arm on tab A, hold a key, take over from tab B — watch_target.py shows the key-up and the board reports armed:0; tab A shows E12. Record the transcript in .agents/HW_VERIFICATION.md or skipped (no device).

Completion Criteria

• X from an authenticated claim drops the incumbent with E12 and adopts the claim.
• The board is disarmed immediately after every takeover, observed or recorded as unobserved-with-commands — never asserted without a mechanism.
• The three source pins exist and each one fails when its sentence is broken (shown, then reverted).
• bash .agents/validate.sh green; _takeovers counter visible; full test suite green.