ߩ^j1dZddlZddlZddlZddlmZmZejeZ dZ dZ GddZ Gdd Z Gd d ZdS) u! Per-session turn lease — serializes the [load history → run → flush] region. Why this exists (#64934): the gateway's busy guards are keyed by ROUTING KEY (``_active_sessions`` in the adapter, ``_running_agents`` in the runner), but the durable transcript is owned by SESSION_ID — and ``switch_session()`` makes the key→id mapping many-to-one (``/resume`` of a named session from a second chat/topic, CLI-continuity rebinding, async-delegation completion pinning, Telegram topic-binding tip-walks). Two routing keys mapped to one session_id run concurrent turns on two different agent objects, so no per-key guard ever sees the collision. The two turns then interleave their flushes on one transcript: rows persist in completion order instead of arrival order, the identity-marker dedup over shared history dicts can swallow a row outright, and the second turn runs on a history base that never saw the first turn's exchange — leaving a permanent ``user;user`` alternation wedge that ``repair_message_sequence`` re-repairs on every request forever. The lease closes that route by serializing per RESOLVED session_id: it is acquired after session resolution is final (post ``switch_session``/tip-walk), immediately before the transcript load, and released in the dispatch layer's ``finally`` on every exit path. Same-key messages never reach the acquisition point while a turn runs (both routing-key guards hold them), so the lock is uncontended everywhere except the alias-key route — where the second turn now waits for the first turn's flush and logs one WARNING naming the session and both routing keys (pairing with the cross-agent tripwire in ``agent/agent_runtime_helpers.note_turn_start``). Safety properties: - **Generation-scoped, identity-checked release.** A token records its owner (routing key, run generation) and release only frees the lease when that exact token is the current holder — a stale unwind can never release a newer turn's lease (the #28686 ownership lesson applied). Release is idempotent. - **Fail-open on timeout.** A stuck holder degrades to today's unserialized behavior with a loud ERROR after the configured wait — never a wedged session. A degraded token holds nothing and releases nothing. - **Bounded registry.** The per-session lease map is size-capped; eviction only ever removes idle (unheld, uncontended) entries, never a live lease. Known limits (deliberate, flagged on #64934): - A CLI process sharing the session via CLI-continuity is outside any in-process lock — that pair needs a DB-level lease (separate design). - Mid-turn compression rotation leaves a small alias window: the tip-walk can resolve a fresh child id while the parent-holding turn is still in flight. The mid-turn binding-sync sites are the right place to alias the lease in a follow-up. N)DictOptionalig @c BeZdZdZdZ d dededededd f d Zdefd Z d S) TurnLeaseTokena Handle returned by :meth:`SessionTurnLeaseRegistry.acquire`. ``degraded`` means the acquire timed out and the turn is proceeding UNSERIALIZED (fail-open); such a token holds nothing and its release is a no-op. ``released`` makes release idempotent.  session_id owner_key generationdegradedreleasedFrr r r returnNcL||_||_||_||_d|_dS)NFr)selfrr r r s 4/home/ice/.hermes/hermes-agent/gateway/turn_lease.py__init__zTurnLeaseToken.__init__Os+%"$   c Xd|jd|jd|jd|jd|jd S)NzTurnLeaseToken(session_id=z , owner_key=z , generation=z , degraded=z , released=)rrs r__repr__zTurnLeaseToken.__repr__\sg C C C C C8< C C  C C26- C C C r)F) __name__ __module__ __qualname____doc__ __slots__strintboolrrrrrrEsRI             #      rrc6eZdZdZddZedefdZdS) _SessionLease)lockholder acquired_at last_usedr Nctj|_d|_d|_t j|_dS)N)asyncioLockr"r#r$timer%rs rrz_SessionLease.__init__gs/LNN 04 rcH|jduo|j S)z?True when this lease can be evicted: nobody holds or awaits it.N)r#r"lockedrs ridlez_SessionLease.idlems'{d"=49+;+;+=+='==rr N)rrrrrpropertyrr-rrrr!r!dsT>I%%%% >d>>>X>>>rr!c eZdZdZefdeddfdZdefdZdede fdZ dd Z dd ded ed ed e e de ef dZde ededefdZde edefdZdS)SessionTurnLeaseRegistryuAsyncio lease per resolved session_id serializing transcript turns. Process-local and single-event-loop by design — the same visibility scope as the routing-key guards it extends. All methods must be called from the gateway's event loop. max_entriesr NcXi|_tdt||_dS)N)_leasesmaxr _max_entries)rr2s rrz!SessionTurnLeaseRegistry.__init__{s)13 3{#3#344rc*t|jSN)lenr5rs r__len__z SessionTurnLeaseRegistry.__len__s4<   rrc|j|}|,|t}||j|<t j|_|Sr9)r5get _evict_idler!r*r%)rrleases r_get_or_createz'SessionTurnLeaseRegistry._get_or_createsU   ,, =      !OOE',DL $)++ rctjjz dz}|dkrdStdjDfd}|d|D]}j|ddS)uDrop oldest idle entries so a new lease fits under the cap. Never evicts a held or contended lease — correctness beats the cap. r4rNc3.K|]\}}|j |VdSr9)r-).0sidr?s r z7SessionTurnLeaseRegistry._evict_idle..s- F FZS%5: FS F F F F F Frc(j|jSr9)r5r%)rDrs rz6SessionTurnLeaseRegistry._evict_idle..sDL-7r)key)r:r5r7sorteditemspop)roverflowidle_idsrDs` rr>z$SessionTurnLeaseRegistry._evict_idles t|$$t'881< q== F F F4<#5#5#7#7 F F F7777   IXI& ( (C L  S$ ' ' ' ' ( (rtimeoutr r rOc K|sdS|r|dkrt|nt}t||t|}||}|jr[|j}t d||||r|j nd|r|j nd|j rtj |j z nd tj|j|d{VnW#tj$rE|j}td|||||r|j nd|r|j ndd|_|cYSwxYw||_tj |_ |j |_|S) uAcquire the turn lease for ``session_id``, waiting if held. Returns a :class:`TurnLeaseToken` — degraded when the wait timed out (fail-open: caller proceeds unserialized). Returns ``None`` for a falsy ``session_id``. Nruturn lease contention on session %s: routing key %s (gen %s) waiting behind in-flight turn held by routing key %s (gen %s, held %.0fs) — two routing keys are mapped to one session_id (#64934); serializing this turn behind the previous turn's flush?grNuturn lease wait timed out after %.0fs on session %s (waiter: routing key %s gen %s; holder: routing key %s gen %s) — failing open: this turn runs UNSERIALIZED against the stuck holder rather than wedging the session; transcript writes may interleaveT)floatDEFAULT_LEASE_WAITrrr@r"r,r#loggerwarningr r r$r*r(wait_foracquire TimeoutErrorerrorr r%) rrr r rOwaittokenr?r#s rrWz SessionTurnLeaseRegistry.acquires 4!(PWq[[uW~~~>Pz9c*ooFF##J// :     \F NN $*3  %+4!!383DN e///$    "5:#5#5#7#7FFF F F F F F F F F#   \F LL( $*3  %+4!!   "ENLLL! $  IKK+ s 3DAEEr[new_session_idc ||js|js |r ||jkrdS|j|j}| |j|urdS|j|}|V||urR|jsK|j}td|j||j |j |r|j nd|r|j nd|dS||j|<tj |_ ||_dS)uAlias a HELD lease onto ``new_session_id`` after mid-turn rotation. Compression can rotate the durable session_id while a turn is in flight (session-hygiene pre-compression, in-agent compression). The turn's flush then targets the NEW id — so the serialization boundary must follow it, or an alias routing key resolving the new id (e.g. a topic tip-walk landing on the fresh child) could start a concurrent turn the lease never sees. This closes the rotation-alias window flagged on #64934. Mechanism: the SAME ``_SessionLease`` object is registered under the new id (the old mapping stays until it goes idle and is evicted), so acquirers on either id serialize against one lock — no lock state is moved, no asyncio internals are touched. Only the current holder can rebind (identity-checked like release), and the token follows to the new id so release frees the shared object. Edge: if the new id already has a live lease of its own (another turn is running on the target session), the two serialization domains cannot be merged mid-wait — log loudly and keep the token on the old id. Fail-open, never deadlock: a holder cannot wait mid-turn. NFuturn lease rebind blocked: session %s rotated to %s mid-turn (holder: routing key %s gen %s) but the target session's lease is already live (holder: routing key %s gen %s) — keeping the lease on the old id; transcript writes on %s may interleave (#64934 rotation-alias edge)rQT) r r rr5r=r#r-rTrUr r r*r%)rr[r\r?existingr#s rrebindzSessionTurnLeaseRegistry.rebinds0 M~ ~ " !1115   !122 =EL555<##N33  HE$9$9(-$9_F NN>   $*3  %+4!!   5', ^$)++)trc||js|jrdSd|_|j|j}|dS|j|ur.t d|j|j|j dSd|_d|_ tj |_ |j r|j dS)ulRelease ``token``'s lease. Idempotent; ownership-checked. Returns True only when this exact token was the current holder and the lock was freed. A degraded token, a re-release, or a stale token whose slot has since been granted to a newer turn are all safe no-ops — a stale unwind can never release a newer turn's lease. NFTzYturn lease release skipped on session %s: token (key %s gen %s) is not the current holderr')r r r5r=rr#rTdebugr r r$r*r%r"r,release)rr[r?s rrbz SessionTurnLeaseRegistry.releases =EN=en=5   !122 =5 rrRrrWrr_rbrrrr1r1ssN+=55C55555!!!!! ( ( ( (*$( ;;;; ;  ; % ; . !;;;;z9H^49c9d9999vXn5$rr1)rr(loggingr*typingrr getLoggerrrTrcrSrr!r1rrrrgs//b !!!!!!!!  8 $ $          > > > > > > > > >{{{{{{{{{{r