Module wan_lease 

One live instance per agent across the WAN — the client side (docs/specs/SPEC_AGENT_SINGLE_LIVE_INSTANCE_2026_09_24.md Phase 5, §4.5).

The muxbus relay holds one lease per agent. This instance claims it for every agent it polls jekts for, renews it while the agent stays registered, and releases it when the agent goes away. While another instance holds it, the relay answers this instance’s pending pulls with 409 — so it cannot consume the other instance’s jekts — and this module reports the agent as held elsewhere, which fences the local holder (the newcomer yields, D1).

Fails open everywhere (D2): a relay without the lease routes (404), an unreachable relay or a transient error never stops delivery or spawning.

Structs

Entry 🔒

Enums

Holder 🔒

The relay’s answer to “which install holds agent’s lease?” — GET /agents/lease/:agent_id (docs/plans/PLAN_JEKT_LOCAL_FIRST_ROUTING_2026_10_02.md §7.1). Asked by a sender about a message’s target, so it never touches this instance’s own lease state (record, admission): a read only.

Outcome 🔒

Constants

HELD_ELSEWHERE_FRESH 🔒

How long a “held elsewhere” answer stays good enough to refuse a spawn without asking again.

HOLDER_FRESH 🔒

How long an answer is reused. Shorter than the lease TTL (60 s), so a lease that lapsed or moved is seen within a renewal or two.

RENEW_EVERY 🔒

How often a held lease is renewed. The relay’s TTL is 60 s.

THIS_COMPUTER 🔒

UNSUPPORTED_BACKOFF 🔒

A relay answering 404 on the lease routes predates them: stop asking for this long.

Statics

HOLDER_CACHE 🔒

HOLDER_UNSUPPORTED_UNTIL 🔒

OPS 🔒

One claim, renewal or release at a time per agent. Without it a release still in flight (the RemoveAgent arm’s runs detached, after a token refresh) could land after the agent was subscribed and claimed again, and release that fresh claim (Codex P2 on #3897).

STATE 🔒

UNSUPPORTED_UNTIL 🔒

Functions

call 🔒

POST path for agent_id; (status, json body) or None on transport error.

claim_outcome 🔒

describe_holder 🔒

Describe the relay’s held_by for a refusal: “computer X, channel Y, vZ”.

ensure 🔒

Claim or renew agent_id’s WAN lease, at most every RENEW_EVERY. base is the relay’s REST base URL (super::relay::rest_base_url).

forget_elsewhere 🔒

Drop a cached “held elsewhere” answer for agent — after a Take over freed it, so the retried turn isn’t refused from the cache for up to HELD_ELSEWHERE_FRESH (Codex P1 on #3899).

held_elsewhere 🔒

Some(where) when a recent answer said another instance holds agent. The early admission check refuses on it without a network round trip.

held_on_another_computer 🔒

Where the holder is when a recent relay answer put agent on another computer (a describe_holder description), else None.

held_on_this_computer_by 🔒

The channel of another instance on this computer that, per a recent relay answer, holds agent — what Take over needs to find it.

holder 🔒

Ask the relay who holds agent’s lease, as caller (the message’s sender, whose credential token is). Cached for HOLDER_FRESH; “unreachable” is never cached.

holder_from 🔒

holder_on_this_computer 🔒

Is a describe_holder description about this computer (another AgentMux instance on the same host, e.g. a second channel)?

instance_id 🔒

This AgentMux instance’s id at the relay: host + channel. Stable across restarts of the same install, distinct between two installs on one host.

is_held 🔒

Whether this instance currently records agent_id’s lease as held.

key 🔒

note_not_holder_since 🔒

[note_not_holder] for a request that started at started: None (nothing recorded, and the caller must not fence) when a Take over cleared the refusal after the request started — its 409 predates the holder letting go (Codex P1 on #3908). Pulls and acks don’t take the op lock, so ordering by start time is what keeps them from restoring it.

op_lock 🔒

post 🔒

POST body to path, with X-Agent-ID: agent_id when there is one; (status, json body) or None on transport error.

record 🔒

release 🔒

Release agent_id’s lease (best effort) and forget it — unless still_gone says it was subscribed again by the time this runs, in which case this returns false (it did not let go).

renew_held_batch 🔒

Renew, in one request (POST /agents/lease/renew-batch), the lease of every agent in agents this instance holds and is due to renew, instead of one request per agent every RENEW_EVERY. Returns each renewed agent’s outcome, keyed by its lowercased name. An agent it leaves out (not held, not due, fewer than two due, a relay without the route, a failed request, an unavailable answer) is the caller’s to ensure on its own, exactly as before.

take_over 🔒

Take over’s relay step, after the holder answered its release request: claim agent_id’s lease now, and if the relay still names an instance on this computer, move it with POST /agents/lease/take (the relay allows that only within one account). A holder older than #3899 answers the release but keeps renewing the lease for as long as it runs, so without this the new pane is fenced seconds after it starts (docs/investigations/INVESTIGATION_TAKE_OVER_OLD_HOLDER_RELAY_LEASE_2026_09_27.md). Another computer is never taken from: Take over only works on this one.