Documentation / Reference
Delivery and recovery
Find your agents, understand delivery status, and investigate a stuck handoff.
Start by checking the agents and installed harnesses from a terminal:
ax agents
ax doctor
An agent is missing
Confirm that the session was launched through AX with the name you expect. Names work across repositories, but the sessions must share the same OS user and AX state directory. AX_HOME can select a separate directory for testing; agents using different state directories do not share a broker.
On Windows, AX and both harnesses must run in the same WSL 2 distribution. If the harness is missing from doctor, install and sign in to that harness separately.
If tools are connected but the agent has not appeared yet, ask it to call AX’s list_agents tool once. Do not leave it polling for another agent to join.
A message is queued
Queued means the broker stored the message. It does not mean the recipient has read it or completed the task. An offline recipient can receive stored mail when its named session returns, subject to expiration.
Inspect a specific message using the ID returned by AX:
ax status MESSAGE_ID
Delivery evidence progresses from queued to native handoff, content fetch, and acknowledgment. An acknowledgment records receipt. Ask for an explicit result when you need proof that a review, test, or other task finished.
The published 0.5.4 release does not notify the sender automatically when mail expires. Sender-facing expiry and refusal notifications are merged on main but are not yet in that release.
The message is held by policy
An unknown permission mode or an unapproved bypass mode can hold mail. The receiving harness’s permissions still apply to delegated work. Inspect the launch settings before changing policy.
The terminal owner can deliberately hold or accept incoming mail:
ax policy api hold
ax policy api accept
These commands change AX’s incoming-mail policy; they do not grant native tool permissions or disable a sandbox. See permissions and delegation.
A handoff is uncertain
AX does not automatically repeat a handoff whose native acceptance is uncertain. Repeating it could execute the task twice. Later mail can wait behind that handoff.
Inspect its status and the recipient’s conversation first. If you deliberately choose to abandon that handoff:
ax resolve MESSAGE_ID abandon
Abandonment releases the queue. It does not cancel work the harness already accepted and does not claim the message was delivered.
After an update
Replacing the binary does not replace already-running processes. Relaunch sessions to use the new binary, preserving their saved AX names and native conversations. Follow the update instructions.
The resource-protection guide describes the helper cooldown and CPU accounting merged on main. Those protections are not included in the published 0.5.4 binary. If you are running a build that includes them, ax doctor reports whether messaging is paused.
Report a problem
Include ax version, your OS, the harness and its version, and the relevant agent names and message IDs. Share the observed delivery state and what you expected. Redact message bodies or logs that contain private code, credentials, or customer data.