ancha explain

ancha explain reads a finished run and prints, for each failed trial, what went wrong and the evidence behind it. Read it before changing the agent.

ancha explain [options] <run>

Argument	Description
`run`	Run id (run_…) or “latest”

Option	Description
`--scene <id>`	Only this scene
`--trial <n>`	Only this trial
`--out <dir>`	Where run directories are (default: .ancha/runs)

Example

ancha explain latest

Output

starter  trial 1  ✗ pagerduty_access
  expected: agent calls * /services*
  actual:   never called; agent made 3 call(s)
  why:      The agent never made a call matching "* /services*". Its calls were: GET /api/conversations.list, GET /repos/acme/starter, GET /api/v1/dashboard.
  trace:
    #1 agent GET /api/conversations.list -> 200
    #2 agent GET /repos/acme/starter -> 200
    #3 agent GET /api/v1/dashboard -> 200

environment: 72 variables from this shell were withheld from the agent. If it needs one (a provider key, say), pass it with --pass-env NAME or list it under agent.pass_env in ancha.yaml.

Patterns are "<METHOD> <PATH>" matched against the service-relative path, and * is a wildcard.

next: ancha baseline save before --from run_20261031-234205_7570556079db03cd, then fix the agent, then ancha run --compare before

It reports, in order:

Harness issues: a part of Ancha failed, so the trial is invalid and does not count as an agent failure.

Agents that crashed or timed out, with the end of agent.log:

Output

starter  trial 1  ✗ agent exited with code 3 after 81ms
  log:  /path/to/project/.ancha/runs/run_20261031-234929_56e8ff2edbb29618/trial-starter-1/agent.log, last 2 line(s):
    starting
    boom: something broke

Each failed check: what was expected, what happened, and the agent’s calls behind it.

Coverage gaps, with or without --strict: calls to endpoints a replica does not implement, with the replica’s answer. The agent’s call may be right; check ancha twins coverage <tool> before changing it.

Output

starter  coverage gap: the agent called POST /api/chat.scheduleMessage, which the slack twin doesn't implement; it answered unknown_method in the vendor's error shape. The agent's call may be right: see ancha twins coverage slack

How many of your shell’s variables were withheld from the agent, when it ran on this computer. If it needs one, such as a provider key, pass it with --pass-env NAME or agent.pass_env. See ancha run.

A run with nothing to explain prints no failed checks to explain.

JSON output

ancha explain latest --json prints one object:

Field	Contents
`runId`	The run.
`failures`	One entry per failed check: `sceneId`, `trial`, `check`, `expected`, `actual`, `explanation` and `traceExcerpt` (the agent’s calls with `seq`, `source`, `method`, `path`, `status`).
`agentIssues`	Crashes, non-zero exits and timeouts, with `exit`, `exitCode`, `realMs`, `log` and `logTail`.
`harnessIssues`	Problems Ancha itself had during a trial.
`coverageGaps`	Each with `service`, `method`, `path`, `count`, the replica’s `status` and `error`, and a `hint`.
`agentEnvironment`	`target` (`host`, `container` or `external`), and for this computer `inherited` and `withheld` counts.
`gradingWarnings`	Present when a check produced a warning.
`next`	The commands to run next, such as `fix the agent` and `ancha run --compare before`.

ancha schema explain prints the schema.

Exit codes

explain exits 0 whenever it can read the run, even if the run failed. Use the exit code of ancha run for the verdict. An unknown run ID exits 2:

Output

error[USAGE]: unknown run "run_nope"
hint: see .ancha/runs/

Where to look next

explain shows the calls behind a failure. For request and response bodies, open trace.jsonl in the trial’s directory; for the final records, state.json. Both paths are in the run summary under trialsDetail[].dir.

Get started

Guides

Concepts

Tools

CLI

Reference

Cloud

Help

ancha explain

Example

JSON output

Exit codes

Where to look next

​Example

​JSON output

​Exit codes

​Where to look next

Example

JSON output

Exit codes

Where to look next