@hansjm10/volt-coding-agent 0.0.0-bootstrap.0 → 0.1.0

package/docs/tla/PLAN.md

@@ -0,0 +1,240 @@
+# Volt formal specification — full modeling plan
+
+This is the deeper reference behind [`README.md`](README.md): the complete module
+decomposition, the per-module invariant/property catalogs for the modules still to
+be written, and the shared abstraction strategy. Predicates are written in
+near-TLA prose; each ties back to a named prose invariant (I1…I7) or a §4.8 race
+row from the RFC.
+
+> Plain-first: every module below starts from one question a user would
+> recognize ("did my phone reconnect to the right chat?", "why did two things run
+> at once?"). The formal invariants are just those questions written precisely
+> enough for a checker.
+
+---
+
+## 1. Module decomposition
+
+Each module is its own `.tla` + `.cfg`. Shared datatypes (node ids, keys, close
+reasons, handshake selections) will live in a `Common.tla` the others `EXTENDS`.
+Build highest-value-first; `LeaseBroker` is the spine and everything else refers
+to its states and the close reasons it mints.
+
+| # | Module | Plain question it answers | Key state | Bug classes |
+|---|--------|---------------------------|-----------|-------------|
+| 1 | **`LeaseBroker`** | Who's doing the work for this chat, and how does it hand off? | lease state, owner, streamCount, relays, drain, `runtimeEntry`, pendingAttaches | split-brain runtime (I1), runtime/state coherence (I2), stuck hand-off (I5), lost turn (I6), rekey orphan (I7), relays-only-in-tui (I3), grant never settled (I4). **Written — see README.** |
+| 2 | **`RelayViewer`** | While handing off, does the relay token stay single-use and does "watch the turn finish" ever leak or wedge? | relay `{Pending,Active,Invalidated,Settled}` + `used`/`expiresAt`; feed `{Buffering,Truncated,Live,Ended}` + `subscribed`/`seq`/`connId` | lost turn (event after end; silent-cancel emits nothing), token replay/expiry, double-settle, viewer feed leaking to a non-owner, stuck drain. |
+| 3 | **`SessionTarget`** | On connect, does the phone pin the *right* session — never a stale one? | `target ∈ {last_noId,last_withId,new,session}`; `hostSession ∈ {exists,missing,liveMoved}`; wire `selection`; `requestedId?`; client `{Validated,StreamOpened,PinCommitted,RolledBack}` | ghost pin (pinned to requested vs canonical id), rekey without requestedId, requestedId leaking onto created/resumed, `target=session` silently creating a session, producer/validator tuple mismatch. |
+| 4 | **`ClientAuth`** | Can a revoked or stale phone ever get back in? Is a one-time secret really one-time? | `clients`; `revoked[node]`; `pending[secretHash]`; `tomb ∈ {consumed(node),expired}`; logical `clock`; per-hello workspace authz | revoked-client re-entry, one-time secret replayed to a *different* node, expired-secret pairing, workspace-authz cached-at-pairing, check-order regressions. |
+| 5 | **`ClientConn`** | Does the phone reconnect exactly once, never when the user said disconnect, and never confuse abort with detach? | app status; `userRequestedDisconnect`; background flag; per-pin status lattice; closure ledger; monotonic `operationToken`/`reconnectGen`/`attemptId` | ghost reconnect while user-disconnected, double reconnect loop, expected-closure marker mis-consume, abort-conflated-with-detach, stale continuation commit. |
+| 6 | **`PushOrdering`** | Is `register_live_activity` ever accepted before its delivery channel exists? | `pushTarget ∈ {None,Enabled,Disabled}`; `laChannel ∈ {none,pendingAck,confirmed}`; `laReg`; `queuedUnreg` (TTL) | push-ordering violation, stale channel gating a send, reentrant flush dropping a queued unregister, cross-client channel scoping. |
+
+**Build order.** `LeaseBroker` → `RelayViewer` (shares the connection-drop
+trigger; compose the two once each is green solo) → `SessionTarget` → `ClientAuth`
+→ `ClientConn` (largest state space; consumes close reasons from 1–3 as an
+abstract input alphabet) → `PushOrdering`.
+
+---
+
+## 2. `LeaseBroker` (written)
+
+Full detail is in [`README.md`](README.md#the-leasebroker-module) and the header
+comment of `LeaseBroker.tla`. Summary of what it checks:
+
+- **Safety:** `OwnershipUnique` (I1), `RuntimeIffDaemon` (I2), `TuiOwnerWellFormed`
+  (I3a), `DisposePendingOnlyTui`, `RelaysOnlyWhenTui` (I3b), `DrainHasAcquirer`
+  (I4), `StreamingCoherent`, `DrainNoNewTurn` (I6), and the off-by-default
+  `NoStreamLeak` bug detector.
+- **Liveness:** `DrainConverges` (I5), `EventualSettle` (I4), under per-key weak
+  fairness on the drain pump.
+- **Key modeling move:** `runtimeEntry` is an independent variable and the
+  idle-acquire disposal is a two-step `flip → disposeDone/disposeFail`, so the
+  flip-before-dispose split-brain window is a reachable state (otherwise I1/I2 are
+  vacuous). This is the fix the review forced on the first draft.
+
+---
+
+## 3. Invariant & property catalogs — planned modules
+
+Unless noted, assume **weak fairness (WF)** on the daemon's internal steps (drain
+runner, disposal, ack handlers) and on "the environment eventually satisfies the
+network / eventually idles"; revocation and user-disconnect are adversarial (no
+fairness — they are choices, not obligations).
+
+### 3.2 `RelayViewer` — written + verified green
+
+Implemented in `RelayViewer.tla` (207,025 states). The prose below is the design
+intent; the shipped module realizes it with `FeedOwnerSet`, `BufferCoherent`,
+`RelayUsedCoherent` (safety) and `NoEmitAfterEnd`, `EndedIsTerminal`,
+`SeqMonotone`, `RelayNoResurrect`, `FeedConverges`, `RelaySettleConverges`
+(temporal). The daemon-side relay byte pump and the drain trigger are abstracted;
+composition with `LeaseBroker` is future work.
+
+**Safety**
+
+- `RelayTokenRedeemableAtMostOnce` — `admit` succeeds ≤ once per relayId; the
+  shared `used` bit is flipped by both `admit` and `invalidatePending`, so a
+  rekey-invalidate and a concurrent admit cannot both win.
+- `RelayTokenExpiryEnforced` — `admit` rejects `now > expiresAt` at redeem time.
+- `AdmitAtomicityUnderReject` — a failing `admit` mutates neither `pending` nor `active`.
+- `RelaySettleExactlyOnce` — `finish()` settles and deletes exactly once; daemon
+  `closeReason` takes precedence over a socket-derived reason.
+- `NoViewerEventAfterViewerEnd` — once a feed ended, no `viewer_event` is emitted.
+- `ViewerFeedToRequesterOnly` — emit/subscribe/abort check `feed.connId`; the
+  draining transcript never leaks to another connection.
+- `ViewerBufferBounded` — the pre-subscribe buffer is capped; overflow yields
+  exactly one `truncated` marker and no partial transcript.
+- `SilentCancelEmitsNothing` (§4.8 row 2) — if the requester drops between
+  `lease_pending` and `drain_end`, the grant rejects internally and **no** wire
+  frame is sent (distinct from granted/error which do emit). Getting "nothing is
+  sent" wrong is the likely wedge.
+
+**Liveness** — `PendingOfferResolves`, `ActiveRelaySettles`, `ViewerFeedEnds`
+(every started feed reaches granted/cancelled/error; `unsubscribe` doesn't strand it).
+
+### 3.3 `SessionTarget` — written + verified green
+
+Implemented in `SessionTarget.tla` (28 states). Models the daemon producer
+(`session-target.ts` + rekey overlay) and the phone validator as a
+resolve → validate → commit/reject pipeline, checking `NoGhostSession`,
+`CanonicalPinOnly`, `ProducerSubsetOfValidator` (the compatibility proof),
+`RekeyWellFormed`, `SessionResumedMatches`, `RequestedOnlyForRekey`, and
+`HandshakeTerminates`. The prose below is the original design intent.
+
+**Safety**
+
+- `CanonicalPinOnly` — the app commits a pin only against the canonical
+  `metadata.sessionId`, never `requestedSessionId`. The strongest one: TLC must be
+  unable to reach a `PinCommitted` whose id = the requested id on a rekey.
+- `RequestedIdImpliesRekey` — `requestedSessionId` on the wire ⇔ `selection =
+  session_rekeyed` ⇔ `target = session`; no created/resumed carries a requested id.
+- `SessionTargetNoCreate` — `target=session ∧ hostSession=missing ⇒
+  session_unavailable`, never `created_after_missing`.
+- `NewTargetCreatedOnly` — `target=new ⇒ selection=created`.
+- `ProducerSubsetOfValidator` (refinement) — the `(target, selection, requestedId)`
+  tuples the host emits are a subset of what the Swift validator accepts. A genuine
+  cross-language compatibility proof no test gives us.
+
+**Liveness** — `HandshakeTerminates` (every valid target reaches exactly one of
+`PinCommitted` / `RolledBack`; no partial pin persists), `RekeySurfacesToClient`.
+
+### 3.4 `ClientAuth` — written + verified green
+
+Implemented in `ClientAuth.tla` (9,678 states). Models the host authorization
+decision (`authorization.ts`) evolving through pair / revoke / approve-re-pair /
+expire-secret and a clock that moves backwards, checking `NoIllegitimatePairing`
+(covers revoked re-entry, one-time-secret replay by another node, expired-secret
+pairing, and the fail-closed backwards-clock case) and `WorkspacePerRequest`. The
+prose below is the original design intent.
+
+**Safety**
+
+- `AuthoritativeIdentityIsNodeId` — all keying uses the transport `remoteNodeId`;
+  `hello.clientNodeId` is never consulted.
+- `RevokedNeedsApprovedRePair` — a revoked node is rejected unless re-pair approval
+  is active (0 ≤ now−approvedAt ≤ 30min, **fail-closed on negative**) *and* a live,
+  non-consumed, non-expired secret. A generic new ticket alone never re-admits.
+- `ConsumedSecretBindsOneNode` — a `consumed(node)` tombstone rejects any *other*
+  node presenting the same secret hash.
+- `ExpiredSecretNeverPairs` — expiry dominates in check order; re-pair approval
+  can't rescue an expired secret.
+- `WorkspaceAuthzPerRequest` — even a paired client is authz-checked against
+  *current* host state every handshake, never cached at pairing.
+- `CheckOrderPreserved` — outcomes match the load-bearing order (revoked → expired
+  → workspace_unregistered → workspace_unavailable → workspace_authorization_removed
+  → consumed → client_unknown).
+- `RetiredOutcomesUnreachable` — the authorization-state model cannot produce
+  `conversation_in_use` or `workspace_forbidden`; runtime attach may separately
+  emit `conversation_in_use` for incompatible client tool grants.
+
+**Adversarial-clock note.** Model the logical clock as able to move **backward**
+and assert `RevokedNeedsApprovedRePair` still holds — a future-dated approval must
+fail closed. **Liveness** — `PendingTicketResolves`, `TombstonesReclaimed`.
+
+### 3.5 `ClientConn` — written + verified green
+
+Implemented in `ClientConn.tla` (176 states). Models the phone reconnect loop and
+network-path handling, checking `SingleReconnectDial` (the anti-double-loop race:
+a network blip during a dial never spawns a second concurrent dial),
+`UserDiscSuppresses`, `TerminalAbsorbing`, and `AbortKeepsLive`. The generation
+guards, snapshots, and backoff timing are abstracted; the prose below is the fuller
+design intent.
+
+**Safety**
+
+- `UserDisconnectSuppressesAutoReconnect` — while `userRequestedDisconnect`, no
+  automatic reconnect runs; the flag clears only on an explicit user connect. Holds
+  across app-active, network-flap, and background-return.
+- `AbortKeepsStreamOpen` — a successful abort does not close the stream, arm a
+  closure marker, schedule reconnect, or reselect. Abort and detach are disjoint.
+- `ExpectedClosureNeverReportsDisconnect` — an EOF whose `(ws,sid)` marker is in
+  the ledger is consumed exactly once and never reports a disconnect or schedules
+  reconnect. Only `lease_transferred` / `session_rekeyed_reconnect` (+ terminal
+  revoke/workspace-removal) arm markers.
+- `SingleReconnectLoop` — ≤ one live reconnect loop (generation guard);
+  `networkPathStatusDidChange` never clobbers an in-flight dial.
+- `StaleContinuationBails` — any await-resumption whose captured
+  `operationToken`/`reconnectGen`/`attemptId` no longer matches is a no-op.
+- `TerminalIsAbsorbing` — nothing auto-escapes a terminal `Failed` state.
+
+**Suspected bugs to try to break:** closure-marker key collision (ledger keyed by
+`ws` vs `(ws,sid)`); double reconnect across `networkPathStatusDidChange` vs
+`beginForegroundReconnect` when `status=.connecting`; `reconnectGen` orphaning.
+
+**Liveness** — `ReconnectMakesProgress`, `LeaseHandoffSelfHeals` (a
+`lease_transferred` on the selected agent re-establishes a live stream — ties back
+to `LeaseBroker`/`RelayViewer` close reasons), `BoundedRetryLoops` (duplicate ≤5,
+lease_draining ≤3 both terminate).
+
+### 3.6 `PushOrdering` — written + verified green
+
+Implemented in `PushOrdering.tla` (63 states). Models the phone/daemon two-phase
+registration, checking `OrderingGate` (the daemon never registers a Live Activity
+without a matching stored delivery channel), `SendAfterConfirm` (the phone never
+sends the LA registration before its channel is confirmed), and
+`StaleChannelInvalidated`. The prose below is the original design intent.
+
+**Safety**
+
+- `DeliveryChannelPrecedesLiveActivity` — `register_live_activity` is sent only
+  when a confirmed delivery channel exists, and the host accepts it only if it
+  resolves the token hash to a stored channel. No LA registration without a prior
+  acked `register_push_target`.
+- `StaleChannelInvalidated` — a channel change clears confirmed/pending so a stale
+  channel can never gate an LA send.
+- `AuthoritativeClientScoping` — every registration is keyed to the authoritative
+  node id on both the direct and `relay_rpc` paths.
+- `UnregisterIdempotent` — unregister removes exactly the matching
+  `(ws,sid,activityId)` and is a no-op otherwise.
+
+**Liveness** — `RegistrationConverges`, `QueuedUnregisterResolves` (queued
+unregister is sent, re-queued, or dropped at its 24h TTL — never lingers),
+`ReentrantEnqueueNotDropped` (a reentrant enqueue during a flush `await` is merged
+back, not silently dropped).
+
+---
+
+## 4. Abstraction strategy (shared)
+
+**Keep concrete (load-bearing):** the lease states and exact transition guards;
+the relay `used` single-use bit shared across admit/invalidate; relay/viewer state
+labels and the settled/ended guards; the close-reason enum (model the
+control-protocol superset); the handshake `(target, selection, requestedId)` tuple
+space; the auth check order and the four disjoint state sets keyed by node/secret;
+the app anti-race counters as monotonic tokens with a first-class "stale
+continuation bails" step; the push two-phase ack chain.
+
+**Abstract away:** turns → a boolean `isStreaming` with a nondeterministic end;
+the session file → a version counter; the byte relay → an opaque connected/settled
+channel; the viewer buffer → one bounded capacity + a nondeterministic overflow;
+time/TTL → a small logical clock or fireable expire events (clock may move backward
+only in `ClientAuth`); tokens → opaque identities with equality only; transcript
+content, push payloads, model catalog, migrations, audit.
+
+**Symmetry & bounds.** Clients, workspaces, and sessions are interchangeable →
+symmetry sets. Suggested starting CONSTANTS: 2 nodes, 1 workspace, 2 sessions, 1
+TUI + 1 phone connection, `MaxStreamCount=2`, retry bounds 2 (smaller than
+production 5/3 — liveness that holds at 2 holds at N). Add a state constraint to
+cap the logical clock and counters so TLC's graph stays finite. Symmetry is
+unsound with liveness in TLC, so use it for invariant-only runs and drop it (as the
+shipped `LeaseBroker.cfg` does) when checking properties.

package/docs/tla/PushOrdering.cfg

@@ -0,0 +1,17 @@
+\* TLC configuration for PushOrdering.tla
+\*   ./check.sh PushOrdering
+\* Checks the register_push_target -> register_live_activity ordering and stale-
+\* channel invalidation across the phone/daemon two-phase registration.
+
+SPECIFICATION Spec
+
+CONSTANTS
+    Channels = {c1, c2}
+    NONE = NONE
+
+INVARIANT
+    POTypeOK
+    OrderingGate
+    SendAfterConfirm
+    StaleChannelInvalidated
+    RegisteredLAHadStoredChannel

package/docs/tla/PushOrdering.tla

@@ -0,0 +1,183 @@
+------------------------------- MODULE PushOrdering -------------------------------
+\* In plain terms
+\*
+\* A Live Activity (the lock-screen/Dynamic Island progress pill) can only be
+\* delivered if the phone first told the daemon HOW to reach it. So there is a
+\* strict order: the phone registers a push target (which carries the Live
+\* Activity delivery channel) and waits for the ack; only then does it register
+\* the Live Activity. The daemon likewise refuses a Live Activity registration
+\* whose token it can't resolve to a stored channel (`unknown_live_activity_token`).
+\*
+\* The other subtlety: if the delivery channel CHANGES (new token / session), any
+\* previously "confirmed" channel must be thrown away, so a stale confirmation can
+\* never wave through a Live Activity for the wrong channel.
+\*
+\* Source of truth:
+\*   volt-app .../VoltSession+LiveActivity.swift  (phone two-phase send + confirm)
+\*   src/daemon/conversation-commands.ts          (register_live_activity gate)
+\*   src/core/remote/iroh/push.ts                 (host delivery via stored channel)
+\*
+\* Properties: the daemon never registers a Live Activity without a matching
+\* stored delivery channel; the phone never sends the Live Activity registration
+\* before its channel is confirmed; and a confirmed channel always matches the
+\* current one (stale confirmations are invalidated).
+
+EXTENDS Naturals
+
+CONSTANTS
+    Channels,   \* delivery channel identities (symmetric); small, e.g. {c1, c2}
+    NONE        \* sentinel: no channel
+
+ASSUME NONE \notin Channels
+
+ChannelOrNone == Channels \cup {NONE}
+PushPhases    == {"idle", "sent", "confirmed"}
+LAPhases      == {"idle", "sent", "registered"}
+
+VARIABLES
+    currentChannel,    \* the channel the phone currently wants a Live Activity on
+    pushPhase,         \* register_push_target progress
+    pushSentChannel,   \* channel carried by the in-flight push registration
+    confirmedChannel,  \* channel confirmed by a push-target ack (gates the LA send)
+    laPhase,           \* register_live_activity progress
+    laSentChannel,     \* channel of the in-flight LA registration
+    storedChannel,     \* daemon's stored delivery channel (from register_push_target)
+    hostLAChannel,     \* channel of the daemon's accepted LA registration
+    badHostAccept,     \* daemon accepted an LA with no matching stored channel (sticky)
+    badPhoneSend       \* phone sent an LA registration before its channel was confirmed (sticky)
+
+vars == << currentChannel, pushPhase, pushSentChannel, confirmedChannel, laPhase,
+           laSentChannel, storedChannel, hostLAChannel, badHostAccept, badPhoneSend >>
+
+-----------------------------------------------------------------------------
+POTypeOK ==
+    /\ currentChannel \in ChannelOrNone
+    /\ pushPhase \in PushPhases
+    /\ pushSentChannel \in ChannelOrNone
+    /\ confirmedChannel \in ChannelOrNone
+    /\ laPhase \in LAPhases
+    /\ laSentChannel \in ChannelOrNone
+    /\ storedChannel \in ChannelOrNone
+    /\ hostLAChannel \in ChannelOrNone
+    /\ badHostAccept \in BOOLEAN
+    /\ badPhoneSend \in BOOLEAN
+
+Init ==
+    /\ currentChannel = NONE
+    /\ pushPhase = "idle"
+    /\ pushSentChannel = NONE
+    /\ confirmedChannel = NONE
+    /\ laPhase = "idle"
+    /\ laSentChannel = NONE
+    /\ storedChannel = NONE
+    /\ hostLAChannel = NONE
+    /\ badHostAccept = FALSE
+    /\ badPhoneSend = FALSE
+
+-----------------------------------------------------------------------------
+\* The desired channel changes (new token / session, or Live Activity cleared).
+\* resetLiveActivityDeliveryStateIfNeeded: a stale confirmed / pending push
+\* channel is thrown away, and the LA registration is invalidated.
+SetChannel(c) ==
+    /\ c # currentChannel
+    /\ currentChannel'   = c
+    /\ confirmedChannel' = IF confirmedChannel = c THEN confirmedChannel ELSE NONE
+    /\ pushPhase'        = IF pushSentChannel = c THEN pushPhase ELSE "idle"
+    /\ pushSentChannel'  = IF pushSentChannel = c THEN pushSentChannel ELSE NONE
+    /\ laPhase'          = "idle"
+    /\ laSentChannel'    = NONE
+    /\ UNCHANGED << storedChannel, hostLAChannel, badHostAccept, badPhoneSend >>
+
+\* Phone sends register_push_target for the current channel; clears confirmation.
+PhoneSendPush ==
+    /\ currentChannel # NONE
+    /\ pushPhase'        = "sent"
+    /\ pushSentChannel'  = currentChannel
+    /\ confirmedChannel' = NONE
+    /\ UNCHANGED << currentChannel, laPhase, laSentChannel, storedChannel,
+                    hostLAChannel, badHostAccept, badPhoneSend >>
+
+\* Daemon receives register_push_target and stores the delivery channel.
+HostStorePush ==
+    /\ pushPhase = "sent"
+    /\ storedChannel' = pushSentChannel
+    /\ UNCHANGED << currentChannel, pushPhase, pushSentChannel, confirmedChannel,
+                    laPhase, laSentChannel, hostLAChannel, badHostAccept, badPhoneSend >>
+
+\* Phone processes the push-target ack (after the daemon stored it): confirm the
+\* channel only if it still matches what the phone currently wants.
+PhoneAckPush ==
+    /\ pushPhase = "sent"
+    /\ storedChannel = pushSentChannel      \* the ack follows the daemon storing it
+    /\ pushPhase'        = "confirmed"
+    /\ confirmedChannel' = IF pushSentChannel = currentChannel THEN pushSentChannel ELSE NONE
+    /\ pushSentChannel'  = NONE
+    /\ UNCHANGED << currentChannel, laPhase, laSentChannel, storedChannel,
+                    hostLAChannel, badHostAccept, badPhoneSend >>
+
+\* Phone sends register_live_activity -- ONLY when the channel is confirmed.
+PhoneSendLA ==
+    /\ laPhase = "idle"
+    /\ currentChannel # NONE
+    /\ confirmedChannel = currentChannel
+    /\ laPhase'       = "sent"
+    /\ laSentChannel' = currentChannel
+    /\ badPhoneSend'  = badPhoneSend \/ (confirmedChannel # currentChannel)
+    /\ UNCHANGED << currentChannel, pushPhase, pushSentChannel, confirmedChannel,
+                    storedChannel, hostLAChannel, badHostAccept >>
+
+\* Daemon processes register_live_activity: accept iff it has a matching stored
+\* channel, else reject (unknown_live_activity_token).
+HostProcessLA ==
+    /\ laPhase = "sent"
+    /\ IF storedChannel = laSentChannel
+       THEN /\ laPhase' = "registered"
+            /\ hostLAChannel' = laSentChannel
+            /\ badHostAccept' = badHostAccept
+            /\ UNCHANGED laSentChannel
+       ELSE /\ laPhase' = "idle"                 \* rejected
+            /\ laSentChannel' = NONE
+            /\ hostLAChannel' = hostLAChannel
+            /\ badHostAccept' = badHostAccept \/ FALSE
+    /\ UNCHANGED << currentChannel, pushPhase, pushSentChannel, confirmedChannel,
+                    storedChannel, badPhoneSend >>
+
+\* Cleanup: unregister the Live Activity (disable / replace / close / abort).
+Unregister ==
+    /\ laPhase = "registered"
+    /\ laPhase' = "idle"
+    /\ laSentChannel' = NONE
+    /\ hostLAChannel' = NONE
+    /\ UNCHANGED << currentChannel, pushPhase, pushSentChannel, confirmedChannel,
+                    storedChannel, badHostAccept, badPhoneSend >>
+
+Next ==
+    \/ \E c \in ChannelOrNone : SetChannel(c)
+    \/ PhoneSendPush
+    \/ HostStorePush
+    \/ PhoneAckPush
+    \/ PhoneSendLA
+    \/ HostProcessLA
+    \/ Unregister
+
+Spec == Init /\ [][Next]_vars
+
+-----------------------------------------------------------------------------
+\* The daemon never registers a Live Activity without a matching stored delivery
+\* channel (the register_push_target-before-register_live_activity ordering).
+OrderingGate == badHostAccept = FALSE
+
+\* The phone never sends the Live Activity registration before its channel is
+\* confirmed by a push-target ack.
+SendAfterConfirm == badPhoneSend = FALSE
+
+\* A confirmed delivery channel always matches the current one; stale confirmations
+\* are invalidated on a channel change (so they can't gate the wrong Live Activity).
+StaleChannelInvalidated ==
+    (confirmedChannel # NONE) => (confirmedChannel = currentChannel)
+
+\* A daemon-registered Live Activity is always for the currently stored channel at
+\* the time it was accepted (follows from OrderingGate).
+RegisteredLAHadStoredChannel ==
+    (laPhase = "registered") => (hostLAChannel # NONE)
+=============================================================================

package/docs/tla/README.md

@@ -0,0 +1,205 @@
+# Volt live-shared-session — formal (TLA+) specification
+
+## In plain terms
+
+Volt's hardest bugs aren't in any one function — they're in *who owns a
+conversation* as it moves between the desktop terminal, the background daemon,
+and the phone, and in *what order* things get closed and handed off. Those are
+exactly the bugs ordinary tests miss, because they only show up in a specific
+interleaving of events across three programs.
+
+This directory holds a formal model of that behavior. A model is a precise,
+executable description of the rules; a checker (TLC) then explores **every**
+reachable interleaving and reports the first one that breaks a rule. It's a way
+to test the *design* exhaustively before trusting it in code.
+
+All six modules are now written and model-checked green with TLC. The suite spans
+the daemon, the TUI, and the phone; each module is checkable on its own in seconds
+via `./check.sh <Module>`.
+
+> Keep these files beside the RFC (`docs/live-shared-session-daemon-design.md`).
+> When the design changes, change the model first, watch the check break, then
+> change the code. If they drift, the model stops meaning anything.
+
+---
+
+## Status
+
+| Module | What it covers (plain) | State |
+|--------|------------------------|-------|
+| **`LeaseBroker`** | Who holds a conversation (daemon vs terminal) and how it hands off. | **Verified green** (40,804 states). `LeaseBroker.tla` / `.cfg` |
+| **`RelayViewer`** | The relay token + the "watch the turn finish" viewer feed during a hand-off. | **Verified green** (207,025 states). `RelayViewer.tla` / `.cfg` |
+| **`SessionTarget`** | Picking the right session on connect, so a phone never pins the wrong one. | **Verified green** (28 states). `SessionTarget.tla` / `.cfg` |
+| **`ClientAuth`** | Pairing, revoking, and re-pairing a phone. | **Verified green** (9,678 states). `ClientAuth.tla` / `.cfg` |
+| **`ClientConn`** | The phone's own connect / reconnect / detach / abort behavior. | **Verified green** (176 states). `ClientConn.tla` / `.cfg` |
+| **`PushOrdering`** | Push + Live Activity registration must happen in the right order. | **Verified green** (63 states). `PushOrdering.tla` / `.cfg` |
+
+**Running the checker.** `./check.sh` runs TLC on `LeaseBroker` (it auto-downloads
+`tla2tools.jar` on first run; needs a JDK 17+ via `JAVA_HOME` or `java` on PATH).
+The baseline has been **verified green with TLC**: 40,804 distinct states, depth
+27, all invariants and both liveness properties hold. See [How to run](#how-to-run).
+
+---
+
+## What we already found
+
+Modeling `LeaseBroker` surfaced **two real issues** in `lease-broker.ts`, each
+reproduced by TLC as a concrete trace (both invariants ship in `LeaseBroker.tla`,
+off by default so the baseline stays green; add either to the `.cfg` to see it):
+
+**1 — `streamCount` leak (fixed).**
+In `runDrain`'s disposal-error recovery (~L388–408), the cancelled branch dropped
+the lease to `unowned` but **never zeroed `record.streamCount`** — unlike the
+success path (L409). Since `dropIfUnowned` requires `streamCount === 0`, the
+record could never be dropped: a leaked `unowned` ghost that handed a phantom
+stream count to the next acquirer. TLC trace: `CommitDaemonAttach →
+PhoneStreamAttach → RuntimeStartTurn → AcquireDrainStart → DrainRuntimeIdle →
+DrainCancelDisposing → DrainDisposeError`, ending in `unowned` with
+`streamCount = 1`. **Fixed** in `lease-broker.ts` (zero `streamCount` in that catch
+branch) with a regression test; `NoStreamLeak` is now in the baseline `.cfg` so it
+stays fixed.
+
+**2 — turn killed on TUI open after the phone walks away (resolved: intended).**
+`acquireForTui` only *drains* when the state is `daemon-active` (L296). A turn
+keeps running after the last phone detaches (RFC: "the prompt continues on the
+host"), leaving a `daemon-detached` runtime that is still mid-turn; opening the TUI
+then disposes it, killing that turn instead of draining it. The model surfaced this
+(`IdleAcquireOnlyWhenIdle`, TLC trace `RuntimeStartTurn → PhoneStreamDetach →
+AcquireIdleFlip`), and the decision came back: **this is intended** — once no
+device is receiving the turn there is nothing to watch, so it is abandonable (the
+same as closing a TUI mid-turn). Documented in the RFC §4.2 and the
+`lease-broker.ts` comment; `IdleAcquireOnlyWhenIdle` stays off in the baseline as a
+marker of that deliberate choice.
+
+---
+
+## The `LeaseBroker` module
+
+### The five states (who holds the conversation)
+
+`unowned` · `daemon-active` · `daemon-detached` · `daemon-draining` · `tui-owned`,
+keyed on `(workspaceName, sessionId)` — `clientNodeId` is deliberately dropped, so
+two phones are the *same* conversation, not two. See the header comment in
+`LeaseBroker.tla` for the plain-English description of each.
+
+### The one design decision that makes the check meaningful
+
+The RFC's headline invariant is "one live runtime per conversation, and a daemon
+runtime exists **iff** the state is `daemon-*`." The tempting way to model that —
+define "runtime alive" as "state is `daemon-*`" — makes the invariant `X ⇔ X`: it
+passes while proving nothing. (The first draft did exactly this; the review
+caught it.)
+
+The real code flips the lease to `tui-owned` **before** it finishes disposing the
+daemon runtime, so there's a genuine window where the lease says `tui-owned`
+while the daemon runtime is still alive. That window *is* the split-brain the
+invariant is meant to rule out. So the model tracks `runtimeEntry` as an
+**independent** variable (set on attach, cleared only when disposal *completes*)
+and splits the idle-acquire into `flip → disposeDone / disposeFail`. Now the
+window is a reachable state and the invariants can actually fail — which is the
+whole point.
+
+### Invariants checked (safety)
+
+Each maps to a real prose invariant or a §4.8 race row. Names match
+`LeaseBroker.tla` exactly.
+
+| Invariant | Plain meaning |
+|-----------|---------------|
+| `OwnershipUnique` (I1) | The daemon runtime and a serving terminal never both exist for one conversation — no split-brain. |
+| `RuntimeIffDaemon` (I2) | A daemon runtime exists exactly in the daemon states, plus the brief disposal window. |
+| `TuiOwnerWellFormed` (I3a) | A terminal connection is recorded exactly when a terminal holds or is acquiring the lease. |
+| `DisposePendingOnlyTui` | The disposal window only exists under `tui-owned`. |
+| `RelaysOnlyWhenTui` (I3b) | Relays exist only while a terminal holds the lease. |
+| `DrainHasAcquirer` (I4) | A draining conversation always has a waiting acquirer and a live pump. |
+| `StreamingCoherent` | A turn only runs while the daemon owns a live runtime. |
+| `DrainNoNewTurn` (I6) | Once a hand-off is disposing, no new turn can start (the `lease_draining` rejection). |
+| `NoStreamLeak` | a stream count implies a live runtime — guards the finding-1 fix (in the baseline). |
+| `IdleAcquireOnlyWhenIdle` | *(off by default)* an idle-acquire never disposes a mid-turn runtime — intentionally does **not** hold; detached turns are abandonable (RFC §4.2). |
+
+### Properties checked (liveness, needs fairness)
+
+| Property | Plain meaning |
+|----------|---------------|
+| `DrainConverges` (I5) | A hand-off never wedges: a draining conversation always leaves that state. |
+| `EventualSettle` (I4) | The acquirer's grant is always settled (granted, cancelled, or errored) — nobody waits forever. |
+
+Both rely on weak fairness on the drain pump, applied **per key** so one
+conversation's hand-off can't starve another's. The adversarial branches
+(cancel, disposal error) get *no* fairness, so they can't manufacture a fake
+liveness violation.
+
+### What the model deliberately simplifies
+
+A turn is a boolean (`runtimeStreaming`) with a nondeterministic end, not
+token-by-token streaming. The byte relay is a count, not a pump. Time/TTL is a
+fireable event, not a clock. Counts are bounded (`MaxStreams`, `MaxRelays=2`,
+`MaxPending=1`) so the state space is finite. These are the standard
+abstractions; the ownership logic itself is kept exact.
+
+---
+
+## How to run
+
+```bash
+./check.sh                 # LeaseBroker, baseline config (auto-fetches tla2tools.jar)
+./check.sh RelayViewer     # the relay + viewer-feed module
+```
+
+`check.sh` needs a JDK 17+ (via `JAVA_HOME` or `java` on PATH). Equivalently, by hand:
+
+```bash
+java -XX:+UseParallelGC -jar tla2tools.jar -workers auto \
+     -config LeaseBroker.cfg LeaseBroker.tla
+```
+
+A clean run prints `Model checking completed. No error has been found.` To see a
+bug trace instead, uncomment `NoStreamLeak` in `LeaseBroker.cfg` and re-run: TLC
+prints the shortest sequence of states + action names that reaches the leak.
+
+**Reading a counterexample as a Volt bug.** TLC gives you an ordered list of
+states with the action name between each. Translate directly: an
+`OwnershipUnique` trace ending in `tui-owned ∧ runtimeEntry = TRUE` after an
+`AcquireIdleFlip → AcquireIdleDisposeFail` sequence would be a split-brain in the
+idle-acquire revert path; a `NoStreamLeak` trace ending after
+`AcquireDrainStart → DrainRuntimeIdle → DrainCancelDisposing → DrainDisposeError`
+is the stream-count leak, and points at the exact `lease-broker.ts` catch branch.
+
+---
+
+## What a green check does and does not prove
+
+A green run proves that **the model**, at these bounds and abstractions, cannot
+reach a state that breaks the listed invariants and satisfies the liveness
+properties under the stated fairness. That's strong evidence the *design* of the
+hand-off is internally consistent and free of the specific race classes encoded.
+
+It does **not** prove:
+
+- **That the code matches the model.** The TS/Swift isn't generated from the
+  spec; a correct model over a buggy implementation still checks green. The spec
+  is a design artifact — it found the `streamCount` leak because we modeled the
+  code's *intent* and asserted more than the code guarantees, not automatically.
+- **Correctness beyond the bounds.** 2 keys / 2 terminals / small counts is
+  strong evidence via symmetry and small-model reasoning, not a proof for all N.
+- **Anything abstracted away** — byte-level relay framing, real timers, transcript
+  content, full async scheduling beyond the modeled windows.
+- **Freedom from drift.** The biggest risk is the spec rotting as the RFC and code
+  evolve. Cross-reference invariant names both ways (RFC I1–I7 ↔ the names above)
+  and re-run whenever a lease / handshake / close-reason change lands.
+
+---
+
+## Build order for the remaining modules
+
+`LeaseBroker` first (done) — it's the spine, and it mints the close reasons
+(`lease_transferred`, `session_rekeyed_reconnect`) the others consume.
+Then `RelayViewer` (shares the connection-drop trigger; where "lost turn" and
+"stuck drain" actually manifest) → `SessionTarget` (small, high value: the
+wrong-pin class) → `ClientAuth` (self-contained, security-critical) → `ClientConn`
+(largest state space; consumes the close reasons above as inputs) → `PushOrdering`
+(narrowest, orthogonal). Model one at a time; only compose `LeaseBroker` +
+`RelayViewer` once each is green solo.
+
+Full module scope, per-module invariant/property catalogs, and the shared
+abstraction strategy live in [`PLAN.md`](PLAN.md).