Module agent_takeover 

Taking an agent over from another AgentMux instance on this host (docs/specs/SPEC_AGENT_SINGLE_LIVE_INSTANCE_2026_09_24.md Phase 2, §4.6).

Two halves, both behind full auth_key auth:

• POST /api/v1/agent/takeover {block_id} — on the instance the user is in. Its pane was refused because another instance runs the agent; the user confirmed “Take over”. Finds that instance (lease holder, or the compat probe for one that takes no lease), asks it to let go, and waits until the agent is free. The pane then runs its turn as usual.
• POST /agentmux/agent/release {uid} — on the holder. Gracefully stops the CLI process of every pane of this srv that holds uid’s lease, shows “taken over” in those panes, and keeps this srv from re-claiming the agent on its own for a short hold.

Never jekt-drivable (spec I5, D7): a jekt body cannot reach either route. The requester side is reached from the pane’s own Take over action after a confirmation; the holder side authenticates with the holder’s own full auth key, which the requester reads from the host-global shared registry — the same trust cross-channel jekt forwarding already relies on.

Structs

HoldingQuery 🔒

ReleaseRequest 🔒

TakeoverRequest 🔒

Enums

WanTarget 🔒

Who holds agent per the relay, when no local lease or running instance does. Charlie 2026-09-26: a same-computer instance (another channel) held only the relay lease, and Take over looked nowhere else, answered released: false, and the pane was refused again.

Constants

RELEASE_GRACE 🔒

How long the holder lets a turn in flight finish before killing it.

TAKEOVER_WAIT 🔒

How long the requester waits for the agent to become free.

Functions

describe_requester 🔒

handle_agent_holding 🔒

GET /agentmux/agent/holding?uid=… — a LAN peer asking whether this host runs uid (spec §4.4, Phase 4). LAN-key readable, like the agent-name list: it discloses only whether an agent UID is live here, since when, and in which channel/version.

handle_agent_release 🔒

handle_agent_takeover 🔒

kept_relay_hold_error 🔒

Take over reaches instances on this computer only. The instance on this computer let go of the pane but the relay still names it, and the relay wouldn’t move the lease (a relay without /agents/lease/take, or a lease claimed for another account).

other_computer_error 🔒

surface_failure 🔒

Show message in the pane’s recovery row — the same persisted meta and live event a spawn refusal uses.

wan_takeover_target 🔒