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

package/docs/tla/RelayViewer.cfg

@@ -0,0 +1,26 @@
+\* TLC configuration for RelayViewer.tla
+\*   ./check.sh RelayViewer
+\* Models the daemon relay-token lifecycle (relay-stream.ts) and the drain
+\* viewer-feed lifecycle (viewer-feed.ts). Baseline: all invariants + properties.
+
+SPECIFICATION Spec
+
+CONSTANTS
+    Relays = {r1, r2}
+    Feeds  = {f1, f2}
+    Conns  = {c1, c2}
+    NoConn = NoConn
+
+INVARIANT
+    RVTypeOK
+    FeedOwnerSet
+    BufferCoherent
+    RelayUsedCoherent
+
+PROPERTY
+    NoEmitAfterEnd
+    EndedIsTerminal
+    SeqMonotone
+    RelayNoResurrect
+    FeedConverges
+    RelaySettleConverges

package/docs/tla/RelayViewer.tla

@@ -0,0 +1,299 @@
+-------------------------------- MODULE RelayViewer --------------------------------
+(***************************************************************************)
+(* In plain terms                                                          *)
+(*                                                                         *)
+(* This is the plumbing that carries a conversation during a hand-off,     *)
+(* modeling two daemon mechanisms:                                         *)
+(*                                                                         *)
+(*  - RELAY TOKEN: when the terminal owns a conversation, the daemon hands *)
+(*    a phone's stream to the terminal using a one-time token.  The token  *)
+(*    must be redeemable at most once and must expire (10s), so a stale or  *)
+(*    replayed token can never open a second pipe.                         *)
+(*                                                                         *)
+(*  - VIEWER FEED: while a hand-off waits for the current reply to finish, *)
+(*    the acquiring terminal watches that reply read-only.  Events are      *)
+(*    buffered until the terminal subscribes, then flushed and streamed     *)
+(*    live; if too many pile up they are dropped with a "truncated" marker; *)
+(*    and once the feed ends, nothing more may be sent on it.               *)
+(*                                                                         *)
+(* The properties worth proving: a token is redeemed at most once and never *)
+(* after it expired; a viewer feed only ever talks to the terminal that     *)
+(* requested it; no event is sent after the feed ends; sequence numbers only *)
+(* go up; and every started feed / redeemed relay eventually finishes.       *)
+(*                                                                         *)
+(* Source of truth:                                                        *)
+(*   src/daemon/relay-stream.ts   RelayRegistry: mint/admit/invalidate/finish  *)
+(*   src/daemon/viewer-feed.ts    ViewerFeedRegistry: start/subscribe/end      *)
+(*   docs/live-shared-session-daemon-design.md  (RFC 4.3, 5.4, 5.6)         *)
+(*                                                                         *)
+(* The lease drain that starts/ends a feed and mints/closes a relay is the  *)
+(* LeaseBroker module; here that environment is abstracted as free actions. *)
+(* Composition with LeaseBroker is a later step (see PLAN.md).              *)
+(***************************************************************************)
+
+EXTENDS Naturals, TLC
+
+CONSTANTS
+    Relays,   \* relay ids (symmetric); small, e.g. {r1, r2}
+    Feeds,    \* viewer-feed ids (symmetric); small, e.g. {f1, f2}
+    Conns,    \* control-connection ids (a feed is owned by exactly one); e.g. {c1, c2}
+    NoConn    \* sentinel for "no owning connection"
+
+ASSUME NoConn \notin Conns
+
+MaxBuf == 2   \* buffered events before the next one overflows -> truncated
+MaxSeq == 3   \* bound on emitted-event sequence numbers (keeps the model finite)
+
+Symmetry == Permutations(Relays) \cup Permutations(Feeds) \cup Permutations(Conns)
+
+RelayStates == {"none", "pending", "active", "settled", "invalidated"}
+FeedStates  == {"none", "buffering", "truncated", "live", "unsubscribed", "ended"}
+FeedLive    == {"buffering", "truncated", "live", "unsubscribed"}  \* started, not ended
+
+VARIABLES
+    relayState,    \* [Relays -> RelayStates]
+    relayExpired,  \* [Relays -> BOOLEAN]  TTL elapsed while pending
+    feedState,     \* [Feeds  -> FeedStates]
+    feedOwner,     \* [Feeds  -> Conns \cup {NoConn}]  the drain requester
+    feedBuffered,  \* [Feeds  -> 0..MaxBuf]  pre-subscribe buffered events
+    feedSeq,       \* [Feeds  -> 0..MaxSeq]  emitted viewer_event count
+    feedAborted    \* [Feeds  -> BOOLEAN]  viewer_abort seen (non-destructive)
+
+rvvars == << relayState, relayExpired, feedState, feedOwner, feedBuffered, feedSeq, feedAborted >>
+
+-----------------------------------------------------------------------------
+RVTypeOK ==
+    /\ relayState   \in [Relays -> RelayStates]
+    /\ relayExpired \in [Relays -> BOOLEAN]
+    /\ feedState    \in [Feeds  -> FeedStates]
+    /\ feedOwner    \in [Feeds  -> Conns \cup {NoConn}]
+    /\ feedBuffered \in [Feeds  -> 0..MaxBuf]
+    /\ feedSeq      \in [Feeds  -> 0..MaxSeq]
+    /\ feedAborted  \in [Feeds  -> BOOLEAN]
+
+Init ==
+    /\ relayState   = [r \in Relays |-> "none"]
+    /\ relayExpired = [r \in Relays |-> FALSE]
+    /\ feedState    = [f \in Feeds  |-> "none"]
+    /\ feedOwner    = [f \in Feeds  |-> NoConn]
+    /\ feedBuffered = [f \in Feeds  |-> 0]
+    /\ feedSeq      = [f \in Feeds  |-> 0]
+    /\ feedAborted  = [f \in Feeds  |-> FALSE]
+
+-----------------------------------------------------------------------------
+(*                          RELAY TOKEN ACTIONS                             *)
+(* relay-stream.ts RelayRegistry. The shared `used` bit + map delete are    *)
+(* here a single state variable, so admit and invalidate cannot both fire   *)
+(* from `pending`: whichever runs first leaves `pending`, disabling the      *)
+(* other -- exactly the "cannot both win" guarantee.                        *)
+
+\* mint(): a new offer.  (relay-stream.ts L66-84)
+RelayMint(r) ==
+    /\ relayState[r] = "none"
+    /\ relayState'   = [relayState   EXCEPT ![r] = "pending"]
+    /\ relayExpired' = [relayExpired EXCEPT ![r] = FALSE]
+    /\ UNCHANGED << feedState, feedOwner, feedBuffered, feedSeq, feedAborted >>
+
+\* the 10s token TTL elapses while still pending.  (RELAY_TOKEN_TTL_MS)
+RelayExpire(r) ==
+    /\ relayState[r] = "pending"
+    /\ relayExpired[r] = FALSE
+    /\ relayExpired' = [relayExpired EXCEPT ![r] = TRUE]
+    /\ UNCHANGED << relayState, feedState, feedOwner, feedBuffered, feedSeq, feedAborted >>
+
+\* admit(): the TUI redeems the token.  Succeeds only if unused (still pending)
+\* and not expired -- the expiry check at redeem time.  (relay-stream.ts L135-141)
+RelayAdmit(r) ==
+    /\ relayState[r] = "pending"
+    /\ relayExpired[r] = FALSE
+    /\ relayState' = [relayState EXCEPT ![r] = "active"]
+    /\ UNCHANGED << relayExpired, feedState, feedOwner, feedBuffered, feedSeq, feedAborted >>
+
+\* invalidatePending(): rekey / duplicate replacement / expiry cleanup marks the
+\* offer used and drops it.  Allowed regardless of expiry.  (relay-stream.ts L87-94)
+RelayInvalidate(r) ==
+    /\ relayState[r] = "pending"
+    /\ relayState' = [relayState EXCEPT ![r] = "invalidated"]
+    /\ UNCHANGED << relayExpired, feedState, feedOwner, feedBuffered, feedSeq, feedAborted >>
+
+\* finish(): either side closed; settle() runs exactly once (the `settled` guard),
+\* here the single move active -> settled.  (relay-stream.ts L153-170)
+RelaySettle(r) ==
+    /\ relayState[r] = "active"
+    /\ relayState' = [relayState EXCEPT ![r] = "settled"]
+    /\ UNCHANGED << relayExpired, feedState, feedOwner, feedBuffered, feedSeq, feedAborted >>
+
+-----------------------------------------------------------------------------
+(*                          VIEWER FEED ACTIONS                             *)
+(* viewer-feed.ts ViewerFeedRegistry. Events that arrive while truncated or  *)
+(* unsubscribed are simply dropped by the code, so they are NOT modeled as   *)
+(* actions (a dropped event is no state change).                            *)
+
+\* start(): begin capturing the draining runtime's events for connection c.
+\* (viewer-feed.ts L49-69)
+FeedStart(f, c) ==
+    /\ feedState[f] = "none"
+    /\ feedState'    = [feedState    EXCEPT ![f] = "buffering"]
+    /\ feedOwner'    = [feedOwner    EXCEPT ![f] = c]
+    /\ feedBuffered' = [feedBuffered EXCEPT ![f] = 0]
+    /\ feedSeq'      = [feedSeq      EXCEPT ![f] = 0]
+    /\ feedAborted'  = [feedAborted  EXCEPT ![f] = FALSE]
+    /\ UNCHANGED << relayState, relayExpired >>
+
+\* onSessionEvent while buffering, under the cap: buffer it.  (L100-101)
+FeedBufferEvent(f) ==
+    /\ feedState[f] = "buffering"
+    /\ feedBuffered[f] < MaxBuf
+    /\ feedBuffered' = [feedBuffered EXCEPT ![f] = feedBuffered[f] + 1]
+    /\ UNCHANGED << relayState, relayExpired, feedState, feedOwner, feedSeq, feedAborted >>
+
+\* onSessionEvent while buffering, cap exceeded: drop buffer, mark truncated.  (L89-99)
+FeedOverflow(f) ==
+    /\ feedState[f] = "buffering"
+    /\ feedBuffered[f] = MaxBuf
+    /\ feedState'    = [feedState    EXCEPT ![f] = "truncated"]
+    /\ feedBuffered' = [feedBuffered EXCEPT ![f] = 0]
+    /\ UNCHANGED << relayState, relayExpired, feedOwner, feedSeq, feedAborted >>
+
+\* subscribe() from the drain requester while buffering: flush the buffer, go live.
+\* (L118-136)  Only the owning connection may subscribe.
+FeedSubscribeFlush(f, c) ==
+    /\ feedState[f] = "buffering"
+    /\ feedOwner[f] = c
+    /\ feedState'    = [feedState    EXCEPT ![f] = "live"]
+    /\ feedSeq'      = [feedSeq EXCEPT ![f] =
+                          IF feedSeq[f] + feedBuffered[f] > MaxSeq THEN MaxSeq
+                                                                   ELSE feedSeq[f] + feedBuffered[f]]
+    /\ feedBuffered' = [feedBuffered EXCEPT ![f] = 0]
+    /\ UNCHANGED << relayState, relayExpired, feedOwner, feedAborted >>
+
+\* subscribe() while truncated: emit exactly the {truncated} marker, go live.  (L127-128)
+FeedSubscribeTrunc(f, c) ==
+    /\ feedState[f] = "truncated"
+    /\ feedOwner[f] = c
+    /\ feedState' = [feedState EXCEPT ![f] = "live"]
+    /\ feedSeq'   = [feedSeq   EXCEPT ![f] = IF feedSeq[f] + 1 > MaxSeq THEN MaxSeq ELSE feedSeq[f] + 1]
+    /\ UNCHANGED << relayState, relayExpired, feedOwner, feedBuffered, feedAborted >>
+
+\* subscribe() after a prior unsubscribe: no backlog (buffer already null), go live.
+FeedResubscribe(f, c) ==
+    /\ feedState[f] = "unsubscribed"
+    /\ feedOwner[f] = c
+    /\ feedState' = [feedState EXCEPT ![f] = "live"]
+    /\ UNCHANGED << relayState, relayExpired, feedOwner, feedBuffered, feedSeq, feedAborted >>
+
+\* a live session event is forwarded to the subscriber.  (emit(), L104-111)
+FeedLiveEmit(f) ==
+    /\ feedState[f] = "live"
+    /\ feedSeq[f] < MaxSeq
+    /\ feedSeq' = [feedSeq EXCEPT ![f] = feedSeq[f] + 1]
+    /\ UNCHANGED << relayState, relayExpired, feedState, feedOwner, feedBuffered, feedAborted >>
+
+\* unsubscribe(): TUI dismissed the overlay; stop forwarding, keep the feed.  (L140-149)
+FeedUnsubscribe(f, c) ==
+    /\ feedState[f] = "live"
+    /\ feedOwner[f] = c
+    /\ feedState' = [feedState EXCEPT ![f] = "unsubscribed"]
+    /\ UNCHANGED << relayState, relayExpired, feedOwner, feedBuffered, feedSeq, feedAborted >>
+
+\* abort(): viewer_abort stops the turn but leaves the feed intact.  (L152-159)
+FeedAbort(f, c) ==
+    /\ feedState[f] \in FeedLive
+    /\ feedOwner[f] = c
+    /\ feedAborted[f] = FALSE
+    /\ feedAborted' = [feedAborted EXCEPT ![f] = TRUE]
+    /\ UNCHANGED << relayState, relayExpired, feedState, feedOwner, feedBuffered, feedSeq >>
+
+\* end(): the drain terminated (granted/cancelled/error); emit viewer_end and tear down.
+\* (L162-171)  After this, no viewer_event may be emitted for the feed.
+FeedEnd(f) ==
+    /\ feedState[f] \in FeedLive
+    /\ feedState'    = [feedState    EXCEPT ![f] = "ended"]
+    /\ feedBuffered' = [feedBuffered EXCEPT ![f] = 0]
+    /\ UNCHANGED << relayState, relayExpired, feedOwner, feedSeq, feedAborted >>
+
+-----------------------------------------------------------------------------
+\* Everything has finished: a genuine terminal state (no relay pending/active, no
+\* feed live).  Stutter here so TLC's deadlock check does not flag normal
+\* completion.  This fires ONLY when nothing else is enabled, so it masks no bug.
+AllDone ==
+    /\ \A r \in Relays : relayState[r] \in {"settled", "invalidated"}
+    /\ \A f \in Feeds  : feedState[f] = "ended"
+
+Terminating == AllDone /\ UNCHANGED rvvars
+
+Next ==
+    \/ \E r \in Relays : \/ RelayMint(r)
+                         \/ RelayExpire(r)
+                         \/ RelayAdmit(r)
+                         \/ RelayInvalidate(r)
+                         \/ RelaySettle(r)
+    \/ \E f \in Feeds :
+         \/ FeedBufferEvent(f)
+         \/ FeedOverflow(f)
+         \/ FeedLiveEmit(f)
+         \/ FeedEnd(f)
+         \/ \E c \in Conns : \/ FeedStart(f, c)
+                             \/ FeedSubscribeFlush(f, c)
+                             \/ FeedSubscribeTrunc(f, c)
+                             \/ FeedResubscribe(f, c)
+                             \/ FeedUnsubscribe(f, c)
+                             \/ FeedAbort(f, c)
+    \/ Terminating
+
+Spec ==
+    /\ Init
+    /\ [][Next]_rvvars
+    /\ \A f \in Feeds : WF_rvvars(FeedEnd(f))
+    /\ \A r \in Relays : WF_rvvars(RelaySettle(r))
+
+-----------------------------------------------------------------------------
+(*                            SAFETY INVARIANTS                              *)
+
+\* A feed has an owning connection exactly once it has started.
+FeedOwnerSet ==
+    \A f \in Feeds :
+        /\ (feedState[f] # "none") => (feedOwner[f] \in Conns)
+        /\ (feedState[f] = "none") => (feedOwner[f] = NoConn)
+
+\* Truncation drops the buffer; a nonzero buffer only exists while buffering.
+BufferCoherent ==
+    \A f \in Feeds :
+        /\ (feedState[f] = "truncated") => (feedBuffered[f] = 0)
+        /\ (feedBuffered[f] > 0) => (feedState[f] = "buffering")
+
+\* A relay is "used up" (dropped from the pending map) exactly in the post-pending
+\* states -- the single state variable makes admit/invalidate mutually exclusive.
+RelayUsedCoherent ==
+    \A r \in Relays :
+        (relayState[r] \in {"active", "settled", "invalidated"}) => (relayState[r] # "pending")
+
+-----------------------------------------------------------------------------
+(*                          TEMPORAL PROPERTIES                              *)
+
+\* No viewer_event is emitted after the feed has ended (the ended short-circuit).
+NoEmitAfterEnd ==
+    [][ \A f \in Feeds : (feedState[f] = "ended") => (feedSeq'[f] = feedSeq[f]) ]_rvvars
+
+\* "ended" is absorbing: a torn-down feed never comes back.
+EndedIsTerminal ==
+    [][ \A f \in Feeds : (feedState[f] = "ended") => (feedState'[f] = "ended") ]_rvvars
+
+\* Emitted sequence numbers never go backwards (FIFO flush then live).
+SeqMonotone ==
+    [][ \A f \in Feeds : feedSeq'[f] >= feedSeq[f] ]_rvvars
+
+\* A redeemed relay never returns to a redeemable state (token single-use).
+RelayNoResurrect ==
+    [][ \A r \in Relays : (relayState[r] \in {"active", "settled", "invalidated"})
+                            => (relayState'[r] \in {"active", "settled", "invalidated"}) ]_rvvars
+
+\* Every started feed eventually ends (granted/cancelled/error) -- needs WF(FeedEnd).
+FeedConverges ==
+    \A f \in Feeds : (feedState[f] \in FeedLive) ~> (feedState[f] = "ended")
+
+\* Every redeemed relay eventually settles (either side closes) -- needs WF(RelaySettle).
+RelaySettleConverges ==
+    \A r \in Relays : (relayState[r] = "active") ~> (relayState[r] = "settled")
+
+=============================================================================

package/docs/tla/SessionTarget.cfg

@@ -0,0 +1,18 @@
+\* TLC configuration for SessionTarget.tla
+\*   ./check.sh SessionTarget
+\* Checks that the daemon session-target producer and the phone selection
+\* validator agree, and that the phone never commits a ghost / wrong-id pin.
+
+SPECIFICATION Spec
+
+INVARIANT
+    STTypeOK
+    NoGhostSession
+    CanonicalPinOnly
+    ProducerSubsetOfValidator
+    RekeyWellFormed
+    SessionResumedMatches
+    RequestedOnlyForRekey
+
+PROPERTY
+    HandshakeTerminates

package/docs/tla/SessionTarget.tla

@@ -0,0 +1,192 @@
+------------------------------- MODULE SessionTarget -------------------------------
+(***************************************************************************)
+(* In plain terms                                                          *)
+(*                                                                         *)
+(* When the phone connects, the handshake has to agree on WHICH session it *)
+(* is opening. The daemon resolves the phone's request ("resume my last",  *)
+(* "start new", or "open this exact session id") to one concrete, canonical *)
+(* session, and tells the phone what it did. The phone must then pin its    *)
+(* tab to that canonical id -- never to the id it originally asked for,     *)
+(* because the daemon may have created a fresh one or rekeyed to a          *)
+(* replacement. Getting this wrong is a "ghost pin": the tab points at a    *)
+(* session that isn't really there.                                        *)
+(*                                                                         *)
+(* This module models two actors that must agree:                          *)
+(*   - the daemon PRODUCER: session-target.ts resolveIrohRemoteSessionTarget  *)
+(*     plus the live-runtime rekey overlay,                                    *)
+(*   - the phone VALIDATOR: IrohProtocol selection validation + pin commit.    *)
+(*                                                                         *)
+(* Properties worth proving: an explicit "open this session" that doesn't   *)
+(* resolve fails cleanly (no ghost pin); a rekey is only ever signalled for *)
+(* an explicit session target and always changes the id; the phone pins the *)
+(* canonical id, not the requested one; and every tuple the daemon can emit *)
+(* is one the phone accepts (a cross-language compatibility proof).         *)
+(*                                                                         *)
+(* Source of truth:                                                        *)
+(*   src/daemon/session-target.ts               (the producer)             *)
+(*   src/modes/rpc/iroh-remote-agent-runtime.ts (rekey overlay)            *)
+(*   volt-app .../IrohProtocol + VoltSession+AgentSelection (the validator) *)
+(*   docs/iroh-remote-protocol.md "Reconnect and session selection"        *)
+(*                                                                         *)
+(* Ids are modeled as tokens by ROLE, since only equality matters:          *)
+(*   "req"   the id the phone asked for (session target)                    *)
+(*   "last"  the daemon's remembered last-session id                        *)
+(*   "fresh" a newly created session id                                     *)
+(*   "rekey" the canonical replacement after a live-runtime rekey           *)
+(***************************************************************************)
+
+EXTENDS Naturals
+
+Targets   == {"last", "new", "session"}
+Outcomes  == {"pending", "ok", "unavailable"}
+Sels      == {"none", "created", "created_missing_last", "resumed", "session_rekeyed"}
+Ids       == {"none", "fresh", "last", "req", "rekey"}
+Phases    == {"start", "resolved", "validated", "done"}
+
+VARIABLES
+    phase,       \* pipeline position
+    target,      \* what the phone asked for
+    resolvable,  \* daemon can resolve the request to an existing session
+    moved,       \* live runtime rekeyed to a replacement (session target only)
+    outcome,     \* daemon result: ok | unavailable
+    sel,         \* wire selection
+    canonical,   \* canonical session id the daemon returns
+    requested,   \* wire requestedSessionId (present only on rekey)
+    accepted,    \* the phone validator accepted the tuple
+    pin          \* the id the phone committed its tab to ("none" = no pin)
+
+vars == << phase, target, resolvable, moved, outcome, sel, canonical, requested, accepted, pin >>
+
+-----------------------------------------------------------------------------
+STTypeOK ==
+    /\ phase \in Phases
+    /\ target \in Targets
+    /\ resolvable \in BOOLEAN
+    /\ moved \in BOOLEAN
+    /\ outcome \in Outcomes
+    /\ sel \in Sels
+    /\ canonical \in Ids
+    /\ requested \in Ids
+    /\ accepted \in BOOLEAN
+    /\ pin \in Ids
+
+\* Enumerate all valid inputs as initial states; a rekey can only happen for an
+\* explicit session target that actually resolved.
+ValidInputs ==
+    /\ target \in Targets
+    /\ resolvable \in BOOLEAN
+    /\ moved \in BOOLEAN
+    /\ (moved = TRUE) => (target = "session" /\ resolvable = TRUE)
+
+Init ==
+    /\ ValidInputs
+    /\ phase = "start"
+    /\ outcome = "pending"
+    /\ sel = "none"
+    /\ canonical = "none"
+    /\ requested = "none"
+    /\ accepted = FALSE
+    /\ pin = "none"
+
+-----------------------------------------------------------------------------
+(* Daemon producer: session-target.ts + the rekey overlay. Cases are mutually *)
+(* exclusive and cover every valid input.                                     *)
+Resolve ==
+    /\ phase = "start"
+    /\ phase' = "resolved"
+    /\ \/ /\ target = "new"
+          /\ outcome' = "ok" /\ sel' = "created" /\ canonical' = "fresh" /\ requested' = "none"
+       \/ /\ target = "last" /\ resolvable = TRUE
+          /\ outcome' = "ok" /\ sel' = "resumed" /\ canonical' = "last" /\ requested' = "none"
+       \/ /\ target = "last" /\ resolvable = FALSE
+          /\ outcome' = "ok" /\ sel' = "created_missing_last" /\ canonical' = "fresh" /\ requested' = "none"
+       \/ /\ target = "session" /\ resolvable = FALSE
+          \* explicit session that does not resolve -> session_unavailable, no pin
+          /\ outcome' = "unavailable" /\ sel' = "none" /\ canonical' = "none" /\ requested' = "none"
+       \/ /\ target = "session" /\ resolvable = TRUE /\ moved = TRUE
+          /\ outcome' = "ok" /\ sel' = "session_rekeyed" /\ canonical' = "rekey" /\ requested' = "req"
+       \/ /\ target = "session" /\ resolvable = TRUE /\ moved = FALSE
+          /\ outcome' = "ok" /\ sel' = "resumed" /\ canonical' = "req" /\ requested' = "none"
+    /\ UNCHANGED << target, resolvable, moved, accepted, pin >>
+
+\* Phone validator: which (target, selection, ids) tuples it accepts.
+Validate ==
+    /\ phase = "resolved"
+    /\ phase' = "validated"
+    /\ accepted' =
+         (\/ (sel = "created"               /\ target \in {"new", "last"})
+          \/ (sel = "created_missing_last"  /\ target = "last")
+          \/ (sel = "resumed"               /\ (target = "last" \/ (target = "session" /\ canonical = "req")))
+          \/ (sel = "session_rekeyed"       /\ target = "session" /\ requested = "req"
+                                            /\ canonical = "rekey" /\ canonical # requested))
+    /\ UNCHANGED << target, resolvable, moved, outcome, sel, canonical, requested, pin >>
+
+\* Phone commits the pin to the CANONICAL id (never `requested`).
+Commit ==
+    /\ phase = "validated"
+    /\ outcome = "ok"
+    /\ accepted = TRUE
+    /\ pin' = canonical
+    /\ phase' = "done"
+    /\ UNCHANGED << target, resolvable, moved, outcome, sel, canonical, requested, accepted >>
+
+\* Failure (session_unavailable) or a rejected tuple: no pin.
+Reject ==
+    /\ phase = "validated"
+    /\ (outcome = "unavailable" \/ accepted = FALSE)
+    /\ pin' = "none"
+    /\ phase' = "done"
+    /\ UNCHANGED << target, resolvable, moved, outcome, sel, canonical, requested, accepted >>
+
+Done == phase = "done" /\ UNCHANGED vars
+
+Next == Resolve \/ Validate \/ Commit \/ Reject \/ Done
+
+Spec ==
+    /\ Init
+    /\ [][Next]_vars
+    /\ WF_vars(Resolve) /\ WF_vars(Validate) /\ WF_vars(Commit) /\ WF_vars(Reject)
+
+-----------------------------------------------------------------------------
+(*                            SAFETY INVARIANTS                              *)
+
+\* An explicit session target that cannot resolve never produces a pin (no ghost).
+NoGhostSession ==
+    (target = "session" /\ resolvable = FALSE) => (pin = "none")
+
+\* The phone always pins the canonical id, never a stale requested one. In a
+\* rekey, canonical ("rekey") differs from requested ("req"), so the pin is the
+\* replacement, not the id the phone originally asked for.
+CanonicalPinOnly ==
+    (pin # "none") => (pin = canonical)
+
+\* Every tuple the daemon actually emits (outcome ok) is one the phone accepts:
+\* the producer's output space is a subset of the validator's accepted space.
+ProducerSubsetOfValidator ==
+    (phase \in {"validated", "done"} /\ outcome = "ok") => (accepted = TRUE)
+
+\* A rekey is only ever signalled for an explicit session target, always carries
+\* the requested id, and always changes the canonical id (a no-op rekey is a bug).
+RekeyWellFormed ==
+    (sel = "session_rekeyed") =>
+        /\ target = "session"
+        /\ canonical = "rekey"
+        /\ requested = "req"
+        /\ canonical # requested
+
+\* A session that resolved without a rekey pins exactly the id the phone asked for.
+SessionResumedMatches ==
+    (target = "session" /\ sel = "resumed") => (canonical = "req")
+
+\* The wire requestedSessionId field is present exactly on a rekey.
+RequestedOnlyForRekey ==
+    (requested # "none") <=> (sel = "session_rekeyed")
+
+-----------------------------------------------------------------------------
+(*                          TEMPORAL PROPERTY                                *)
+
+\* Every handshake reaches a terminal decision (pin committed or rejected) --
+\* no partial pin is left dangling.
+HandshakeTerminates == <>(phase = "done")
+
+=============================================================================

package/docs/tla/check.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Model-check a TLA+ module in this directory with TLC.
+#
+#   ./check.sh                       # check LeaseBroker (baseline .cfg)
+#   ./check.sh LeaseBroker leak.cfg  # check LeaseBroker with a specific .cfg
+#
+# Requires a Java 17+ runtime (set JAVA_HOME, or have `java` on PATH). Downloads
+# tla2tools.jar into this directory on first run (it is git-ignored).
+set -euo pipefail
+cd "$(dirname "$0")"
+
+MODULE="${1:-LeaseBroker}"
+CONFIG="${2:-$MODULE.cfg}"
+JAR="tla2tools.jar"
+
+if [[ -n "${JAVA_HOME:-}" && -x "$JAVA_HOME/bin/java" ]]; then
+  JAVA="$JAVA_HOME/bin/java"
+elif command -v java >/dev/null 2>&1; then
+  JAVA="java"
+else
+  echo "error: no Java runtime. Install a JDK 17+ (e.g. 'brew install openjdk@17')" >&2
+  echo "       or download Temurin from https://adoptium.net and set JAVA_HOME." >&2
+  exit 1
+fi
+
+if [[ ! -f "$JAR" ]]; then
+  echo "downloading $JAR ..." >&2
+  curl -L -sS --fail -o "$JAR" \
+    "https://github.com/tlaplus/tlaplus/releases/latest/download/tla2tools.jar"
+fi
+
+echo "checking $MODULE.tla with $CONFIG ..." >&2
+exec "$JAVA" -XX:+UseParallelGC -cp "$JAR" tlc2.TLC \
+  -workers auto -config "$CONFIG" "$MODULE.tla"

package/docs/tmux.md

@@ -0,0 +1,63 @@
+# tmux Setup
+
+Volt works inside tmux, but tmux strips modifier information from certain keys by default. Without configuration, `Shift+Enter` and `Ctrl+Enter` are usually indistinguishable from plain `Enter`.
+
+## Recommended Configuration
+
+Add to `~/.tmux.conf`:
+
+```tmux
+set -g extended-keys on
+set -g extended-keys-format csi-u
+```
+
+Then restart tmux fully:
+
+```bash
+tmux kill-server
+tmux
+```
+
+Volt requests extended key reporting automatically when Kitty keyboard protocol is not available. With `extended-keys-format csi-u`, tmux forwards modified keys in CSI-u format, which is the most reliable configuration. The `extended-keys-format` option requires tmux 3.5 or later.
+
+## Why `csi-u` Is Recommended
+
+With only:
+
+```tmux
+set -g extended-keys on
+```
+
+tmux defaults to `extended-keys-format xterm`. When an application requests extended key reporting, modified keys are forwarded in xterm `modifyOtherKeys` format such as:
+
+- `Ctrl+C` → `\x1b[27;5;99~`
+- `Ctrl+D` → `\x1b[27;5;100~`
+- `Ctrl+Enter` → `\x1b[27;5;13~`
+
+With `extended-keys-format csi-u`, the same keys are forwarded as:
+
+- `Ctrl+C` → `\x1b[99;5u`
+- `Ctrl+D` → `\x1b[100;5u`
+- `Ctrl+Enter` → `\x1b[13;5u`
+
+Volt supports both formats, but `csi-u` is the recommended tmux setup.
+
+## What This Fixes
+
+Without tmux extended keys, modified Enter keys collapse to legacy sequences:
+
+| Key | Without extkeys | With `csi-u` |
+|-----|-----------------|--------------|
+| Enter | `\r` | `\r` |
+| Shift+Enter | `\r` | `\x1b[13;2u` |
+| Ctrl+Enter | `\r` | `\x1b[13;5u` |
+| Alt/Option+Enter | `\x1b\r` | `\x1b[13;3u` |
+
+This affects the default keybindings (`Enter` to submit, `Shift+Enter` for newline) and any custom keybindings using modified Enter.
+
+## Requirements
+
+- tmux 3.5 or later for `extended-keys-format csi-u` (run `tmux -V` to check)
+- A terminal emulator that supports extended keys (Ghostty, Kitty, iTerm2, WezTerm, Windows Terminal)
+
+With tmux 3.2 through 3.4, omit `extended-keys-format csi-u`; Volt still supports tmux's default xterm `modifyOtherKeys` format.