How to Avoid Repeating Failed Commands With AxiOwl Telemetry

The fastest way to waste time with agent tooling is to rerun the same failed command without learning why it failed. AxiOwl is built to make that less likely. Its send path records structured evidence, prints receipt boundaries, and exposes log locations so an operator can inspect what happened before trying again.

This does not mean AxiOwl magically prevents every repeated mistake. It means the current C++ implementation gives you concrete telemetry: message IDs, delivery stages, provider names, target resolution results, handoff state, and error text. The useful habit is simple: after a failure, read the receipt and the logs before changing anything.

Start With The Receipt Boundary

The most important AxiOwl telemetry concept is the receipt boundary. A send command can be accepted by AxiOwl before the provider has definitely received, displayed, processed, or answered the message.

The CLI makes that explicit. When a request is accepted by AxiOwl but provider delivery has not been proven, the command prints a handoff receipt with a message ID, delivery state, provider, and a boundary note:

AxiOwl handoff receipt: MCP/CLI request accepted by AxiOwl.
Message ID: <message-id>
Delivery state: accepted_by_axiowl
Provider: <provider>
Receipt boundary: provider delivery, provider wake-up, and provider reply are not implied.
Delivery log: <path-to-delivery.jsonl>

That message is a guardrail against blind repetition. If you see accepted_by_axiowl, the next useful action is not automatically "send it again." The next useful action is to check whether the provider write succeeded, failed, or remained unverified.

The architecture docs describe the same distinction in three layers:

• accepted_by_axiowl means AxiOwl accepted and validated the request and handed it to the delivery layer.
• A provider result such as accepted_by_provider means the provider edge reported acceptance.
• A response over MCP is stronger end-to-end proof because the target provider received the message, acted on it, and replied with provider-owned sender identity.

Keeping those events separate is how operators avoid treating a local handoff as a complete delivery.

Where AxiOwl Writes Telemetry

AxiOwl stores its local state under a state root. On Windows, the implementation uses:

%LOCALAPPDATA%\AxiOwl

On Linux, it uses $XDG_STATE_HOME/axiowl when that variable is set, otherwise:

~/.axiowl

The relevant log files are under the logs directory:

<state-root>\logs\events.jsonl
<state-root>\logs\delivery.jsonl
<state-root>\logs\create-lifecycle.jsonl
<state-root>\logs\activation.jsonl

The axiowl status command prints these paths directly. In the current CLI it reports the state root, registry path, node registry path, evidence log, delivery log, create lifecycle log, activation file, license status, local service endpoint, runtime role, registered agent count, and registered node count. That makes axiowl status the practical first command when you need to orient yourself on a machine.

The evidence logger writes JSON Lines. Each event is appended as one JSON object with an event_type, created_at timestamp, and event-specific fields. Before appending, AxiOwl creates the log directory if needed and rotates oversized log files by renaming the active file to a .1 sibling.

That format matters operationally. JSONL is easy to inspect with a text editor, PowerShell, shell tools, or a script. You do not need a hidden database to answer basic questions such as "Which message ID failed?" or "Which provider edge was selected?"

What A Failed Send Records

The message pipeline records structured events as the request moves through AxiOwl. A send begins by creating a new message ID and a run ID. The delivery log records an initial delivery_stage event with stage accepted and a detail that says the request entered the AxiOwl message pipeline and that provider delivery is not implied.

From there, common failure points are recorded with specific reasons:

• Empty target: send_rejected with reason target is required.
• Empty body: send_rejected with reason message body is empty.
• Missing sender identity: send_rejected explaining that send requires a resolved sender identity.
• Target not found after targeted discovery: send_rejected with a discovery summary.
• Known but unsendable target: send_rejected with the target's last error when available.
• Delivery worker handoff failure: delivery_handoff_failed with method, evidence, and error fields.
• Provider write failure in the background worker: delivery_worker_delivery_result plus a delivery stage such as provider_write_failed.

Those are different failures. Repeating the same command only makes sense after you know which one happened.

For example, if the target is not in the registry, rerunning the send will usually repeat the same failure until discovery or registry repair changes the target state. If sender identity is unresolved, the fix is usually to call AxiOwl from a provider context that supplies metadata or to provide an explicit sender where the command surface supports it. If the provider write failed, the provider-specific evidence is the next thing to read.

Use The Message ID As The Thread Through The Logs

AxiOwl's practical debugging unit is the message ID. The CLI prints it, and the pipeline writes it into the evidence and delivery logs.

When a send fails or looks suspicious, copy the message ID from the receipt and search the log files for that ID. On Windows PowerShell, that usually looks like:

Select-String -Path "$env:LOCALAPPDATA\AxiOwl\logs\*.jsonl" -Pattern "<message-id>"

On Linux:

grep -R "<message-id>" ~/.axiowl/logs

The exact state root can differ, so axiowl status is the safer way to find the paths before searching.

The delivery log is especially useful because it records staged progress. You may see stages such as:

accepted
target_resolved
route_resolved
delivery_worker_handoff_started
provider_write_started
provider_write_succeeded
provider_write_failed
provider_handoff_started_unverified

Those stage names help distinguish "AxiOwl did not know where to send this" from "AxiOwl handed it to the delivery worker" from "the provider edge reported a problem."

Do Not Treat Discovery As Delivery Proof

AxiOwl can repair stale or missing target information with targeted discovery. In the current pipeline, if a target is missing or requires repair, AxiOwl records either registry_target_miss or registry_target_requires_repair, runs targeted discovery once, and then checks the registry again.

That is useful, but it is not the same as delivery proof. Discovery can find or update a candidate provider session. Delivery proof requires the provider path to accept the message, and the strongest proof is still an actual response over MCP with correct sender identity.

This distinction prevents a common loop:

1. A send fails because a provider session is stale.
2. Discovery finds some provider evidence.
3. The operator assumes delivery is fixed.
4. The same send is repeated without checking whether the new row is sendable or whether provider delivery succeeded.

The support docs state the same forensic rule in plain terms: separate install success, accepted_by_axiowl, provider acceptance, and MCP reply received. Do not treat an earlier event as proof of a later event.

Check The Registry Before Repeating Target Failures

The registry is where AxiOwl resolves human-friendly agent names into provider sessions. The architecture docs describe important registry fields including display name, aliases, provider, provider session ID, node ID, sendability, discovery source, last seen time, last verified time, and last error.

That last group is what matters when a command keeps failing. If a target is known but not sendable, the pipeline returns a loud error instead of silently routing somewhere else. If the target row has a last error, AxiOwl includes it in the rejection reason.

Before rerunning a failed send, use:

axiowl list agents
axiowl status

Then inspect the registry files shown by status when needed:

<state-root>\registry\agents.tsv
<state-root>\registry\nodes.tsv

If the target is missing, stale, evidence-only, or not sendable, the better next step is discovery or registry correction, not another identical send.

Understand Delivery Worker Evidence

The current implementation uses a delivery worker path for provider handoff. The message pipeline writes a temporary request file, starts axiowl delivery-worker --request <file>, and records whether the background handoff started.

The delivery worker then validates the request, dispatches the provider edge, prints a parseable JSON result, appends evidence events, and writes delivery stages. When delivery fails, the worker result includes fields such as provider, state, accepted, degraded, method used, evidence, and error.

That is the telemetry you need before changing the command. A provider-specific failure is not the same as a registry failure. A request parse failure is not the same as a provider wake-up failure. A degraded or unverified provider handoff is not the same as a completed MCP reply.

In practical terms, the delivery worker lets you answer:

• Did the request file parse?
• Which provider edge was selected?
• Did the provider edge accept the request?
• Was the handoff verified or unverified?
• What exact error did the worker record?

Only after answering those questions can you decide whether to retry, repair the target, restart a provider session, reinstall an integration, or collect more logs.

A Practical Retry Checklist

Use this sequence after a failed or uncertain send:

1. Read the CLI receipt. Note the message ID, delivery state, provider, and delivery log path.
2. Run axiowl status and confirm the state root, evidence log, delivery log, registry path, runtime role, and registered agent count.
3. Search events.jsonl and delivery.jsonl for the message ID.
4. Identify the last meaningful stage: target resolution, route resolution, delivery worker handoff, provider write, or reply proof.
5. If the failure is target-related, inspect list agents and the registry before sending again.
6. If the failure is provider-related, read the provider error and relevant provider logs before sending again.
7. If the receipt only says accepted_by_axiowl, do not call that a provider success unless later telemetry proves provider acceptance or a reply arrives.

This checklist is intentionally boring. It replaces guessing with a short evidence trail.

Why This Matters For Multi-Agent Work

AxiOwl is designed for messaging between provider sessions, not just single-user CLI convenience. That makes repeated failed commands more costly. A duplicate message can confuse another agent, trigger unnecessary work, or hide the original failure behind a second, slightly different failure.

The telemetry design gives each send a traceable shape. A message ID ties the receipt to JSONL evidence. Delivery stages show how far the message traveled. Registry state explains what AxiOwl believed about the target. Provider results show whether the selected provider edge accepted, failed, degraded, or remained unverified.

The operator value is discipline. AxiOwl does not ask you to trust that a command "probably worked." It records enough local evidence to decide what happened and what to change next.

Closing

Avoiding repeated failed commands is not about never retrying. It is about retrying with a reason. In AxiOwl, that reason should come from telemetry: the receipt boundary, the message ID, the evidence log, the delivery log, the registry, and the provider result.

When a command fails, treat the first failure as information. Read the JSONL trail, identify the failed stage, fix the actual condition, and then send again.