How to Read AxiOwl Evidence Logs

How to Read AxiOwl Evidence Logs

AxiOwl evidence logs are the operator's audit trail for what the local coordinator accepted, resolved, rejected, handed off, or proved. They are not generic application noise. They are structured newline-delimited JSON records that let you reconstruct the path of a message or create request across registry resolution, sender identity, provider routing, delivery worker handoff, and related installer or activation state.

The most important habit is to read these logs as boundary evidence, not as a blanket success signal. AxiOwl deliberately separates "AxiOwl accepted the request" from "the provider accepted delivery" and from "the target replied through MCP." That separation is what makes the logs useful during support work.

Where the Logs Live

Run:

axiowl status

The status command prints the state root, registry paths, evidence log path, delivery log path, and create lifecycle log path. On Windows, the state root resolves under:

%LOCALAPPDATA%\AxiOwl

The core log files are:

%LOCALAPPDATA%\AxiOwl\logs\events.jsonl
%LOCALAPPDATA%\AxiOwl\logs\delivery.jsonl
%LOCALAPPDATA%\AxiOwl\logs\create-lifecycle.jsonl
%LOCALAPPDATA%\AxiOwl\logs\activation.jsonl

AxiOwl also keeps related state beside those logs:

%LOCALAPPDATA%\AxiOwl\registry
%LOCALAPPDATA%\AxiOwl\runtime

The support forensics guide calls out those three directories together because logs alone rarely tell the whole story. The registry explains what AxiOwl thought was sendable. Runtime files can show delivery worker handoff state. Provider output channels or CLI stdout/stderr may be needed when the provider edge is the failing layer.

What the Format Means

Each evidence record is one JSON object on one line. The shared evidence writer adds:

{"event_type":"message_accepted_by_axiowl","created_at":"2026-07-08T12:34:56Z"}

Real records include more fields after that. The implementation escapes JSON values, appends records to the active file, creates missing directories, and rotates the file when it reaches the configured cap of 10 MB. Rotation renames the current file to a .1 sibling when possible.

Because the files are JSONL, read them line by line. A single bad-looking event is not the timeline. Filter by message_id, request_id, run_id, target, or provider, then compare the ordered records.

Start With the Receipt Boundary

When you send a message from the CLI, AxiOwl prints a receipt. A typical accepted receipt includes a message id, delivery state, provider, and the delivery log path.

If the state is:

accepted_by_axiowl

that means AxiOwl accepted and validated the request and selected a route. It does not prove provider delivery, provider wake-up, or provider reply. The CLI says that explicitly.

If a path reports provider acceptance, the CLI prints a stronger boundary and points to the delivery log. Even then, a provider acceptance is still not the same as an MCP reply. The architecture docs define the strongest end-to-end proof as a response over MCP from the target provider with provider-owned sender identity.

Read a Send Timeline

For a send, use the message id from the CLI receipt and search both events.jsonl and delivery.jsonl.

In events.jsonl, look for records such as:

registry_target_miss
registry_target_requires_repair
registry_target_found_after_targeted_discovery
registry_sender_requires_repair
registry_sender_found_after_targeted_discovery
send_rejected
message_accepted_by_axiowl
delivery_handoff_started
delivery_handoff_failed
send_rate_limit_delay_started
send_rate_limit_delay_finished

These events describe decisions in the main message pipeline. For example, a registry_target_miss record means AxiOwl did not immediately find the requested target and ran one targeted discovery repair. A later registry_target_found_after_targeted_discovery means that repair found a usable row. A send_rejected event records why the request stopped before a provider handoff.

In delivery.jsonl, look for delivery_stage records with the same message_id or run_id. The delivery-stage log records stages such as request acceptance into the pipeline, target resolution, route resolution, and delivery worker handoff. Fields include provider, target, session id, node, result, and detail.

The important question is not "is there a success-looking line?" The important question is "how far did the request get?"

Know the Common Stopping Points

AxiOwl fails loudly for several useful reasons.

If the target is empty, the pipeline records a rejection with:

target is required

If the body is empty, it records:

message body is empty

If sender identity cannot be resolved, the send is rejected before provider dispatch. For final-visible relay bodies, AxiOwl requires resolved sender identity. For ordinary sends, the current CLI surface supports explicit sender fields such as --from and --from-node, while provider MCP paths can supply identity through provider metadata or patches.

If the target exists but is not sendable, the error starts with:

target is known but not sendable

That record may include the registry row's last error. This distinction matters. "Known" means discovery or manual registration produced a row. "Sendable" means AxiOwl currently believes that row can receive a message. A stale or evidence-only row can be visible in inventory and still be an invalid delivery target.

Compare Logs With the Registry

The registry is the durable map of agents, aliases, providers, provider session ids, node ids, sendability, source, verification time, and last error. If a log says target resolution failed or a row was not sendable, inspect:

%LOCALAPPDATA%\AxiOwl\registry\agents.tsv
%LOCALAPPDATA%\AxiOwl\registry\nodes.tsv

The architecture docs call out these registry fields as especially important:

display_name
aliases
provider
provider_session_id
node_id
sendable
source
last_seen_at
last_verified_at
last_error

When a provider path breaks, the registry often explains whether AxiOwl was targeting the intended session, a stale session, an evidence-only row, or the wrong node.

Read Create Lifecycle Logs Separately

Create and rename flows write to:

%LOCALAPPDATA%\AxiOwl\logs\create-lifecycle.jsonl

Create lifecycle records use a request_id, provider, requested name, status, method used, provider session id, provider title, registry display name, correlation state, evidence, and error. The initial message is represented by a hash rather than dumping the full body into the lifecycle record.

That makes create-lifecycle.jsonl the right place to answer questions like:

Do not diagnose create behavior only from the general event log. The lifecycle log is the purpose-built timeline for that workflow.

Include Installer and Provider Evidence When Needed

A successful MSI install proves selected installer actions completed. It does not prove every provider message path works. For install and provider issues, collect:

%LOCALAPPDATA%\AxiOwl\logs
%LOCALAPPDATA%\AxiOwl\registry
%LOCALAPPDATA%\AxiOwl\runtime

Then add the relevant external evidence: MSI verbose log, VS Code AxiOwl Bridge output channel, Cursor AxiOwl Cursor Bridge output channel, provider CLI stdout/stderr, and safe provider session files where appropriate.

This is especially important for editor-backed providers. AxiOwl can show that it prepared a request and handed it to a bridge, while the editor output channel or provider session files explain whether the editor extension activated, selected the right window, or had the expected command surface available.

A Practical Reading Order

When a send fails or behaves strangely, use this order:

  1. Run axiowl status and note the exact log and registry paths.
  2. Copy the Message ID from the CLI receipt, if one was printed.
  3. Search events.jsonl for that message_id.
  4. Search delivery.jsonl for the same message_id or run_id.
  5. Check whether the last meaningful event is target resolution, route resolution, delivery worker handoff, provider acceptance, or rejection.
  6. If target or sender resolution is involved, inspect agents.tsv and nodes.tsv.
  7. If the workflow was create or rename, inspect create-lifecycle.jsonl.
  8. If the provider was an editor or CLI integration, add provider output logs before assigning root cause.

That order keeps the investigation honest. It prevents treating install success as message success, treating AxiOwl acceptance as provider proof, or treating provider acceptance as a completed reply.

Why This Matters

AxiOwl coordinates multiple provider surfaces: local Windows providers, registry-backed sessions, MCP calls, CLI commands, remote nodes, and delivery worker handoffs. Without structured evidence, a failed message could look like one vague "agent did not answer" problem.

The evidence logs turn that into specific questions:

Reading AxiOwl logs well means respecting those boundaries. The logs are designed to show exactly where confidence stops and where the next piece of proof must come from.

Tagged , , , , , , ,