hero verdict
Shows the end state of each job Ekamyth Agent OS ran or watched, and what proves it. A job that only finished is never counted as verified done.
What hero verdict does
It answers one question: did each job finish, and is that proven? Each job reaches one end state: succeeded, failed, crashed, abandoned or partial. A job that started and never closed reads as stuck, which is unresolved, not failed.
A verdict is never taken from the agent's own report. Agent OS records what it saw: for a model call through the model gateway, that the provider answered or returned an error; for a tool call at the hook, whether it ran or was refused. Seeing that a job finished proves that it ran, not that it was right, so such a job reads finished, not verified. A job reads verified done only when a check proved its result. For jobs with a done-contract, hero verdict close runs that check: it re-runs each criterion's test and writes a receipt for each one.
- Use it when you want to see which jobs failed, crashed or got stuck, check whether a finished job was verified, drive stuck jobs to an end state, or read a job's receipts.
- Use something else when you want what one session did step by step (
hero trace), whether the record of decisions is intact (hero attest), or what was refused and why (hero govern). - Alias: none.
- Reads or changes:
statusandreceiptread.sweepwrites end states for stuck jobs.closeruns the job's tests and writes receipts.drainrecords pending hook observations.
Limit: it covers the jobs Agent OS runs or watches: model calls through the model gateway, tool calls at the hook, each agent session's end, and hero ask. Each of these counts as a job, so the count is a count of activity. Work that doesn't reach the gateway or the hook isn't seen. See Limits.
Synopsis for hero verdict
hero verdict [status] [--details | --json]
hero verdict sweep
hero verdict sweep --close-absent-as abandoned --i-understand-this-declares-unresolved-work-finished
hero verdict close <job-id> [--fix-commit <sha>]
hero verdict receipt <job-id>
hero verdict drain [--quiet]
hero verdict --help
Run with no subcommand, it behaves as status. Any other flag is refused with verdict has no flag '<flag>' and exit code 2. hero verdict demo needs an examples package that isn't installed, so it isn't documented here.
Subcommands of hero verdict
| Subcommand | What it does | Reads or changes |
|---|---|---|
status | One row per job, newest first, with its end state, what proves it, and its tokens and cost. This is the default. | Reads |
sweep | Drives stuck jobs that Agent OS still tracks to an end state. A stuck job is marked stalled first, and abandoned on a later run once its grace has passed. Jobs listed as pending but no longer tracked are reported as unresolved and left open. | Changes |
close <job-id> | Re-runs the test named by each criterion in the job's done-contract, in a separate process, and writes one receipt per criterion. It succeeds only when every receipt is proof. | Changes |
receipt <job-id> | Prints the job's receipts. Exits 0 only when every receipt is proof. | Reads |
drain | Records hook observations that are waiting to be written, and reports how many. The hook starts this itself as observations build up, so you don't need to run it. | Changes |
Arguments for hero verdict
Arguments for status
| Argument | Type | Required | Default | Allowed values | What it does |
|---|---|---|---|---|---|
--details | Flag | No | Off | None | Prints a count of jobs by end state, with the time of the last job, instead of the table. |
--json | Flag | No | Off | None | Prints every job, not only the ten in the table, as JSON. See Example 3. |
Arguments for sweep
| Argument | Type | Required | Default | Allowed values | What it does |
|---|---|---|---|---|---|
--close-absent-as <state> | Choice | No | Off: absent jobs stay unresolved | abandoned only | Closes jobs that are pending but no longer tracked as abandoned. Needs the acknowledgement flag below, and writes a receipt naming the count. |
--i-understand-this-declares-unresolved-work-finished | Flag | With --close-absent-as | Off | None | Confirms that you're declaring work finished whose outcome isn't known. |
Arguments for close
| Argument | Type | Required | Default | Allowed values | What it does |
|---|---|---|---|---|---|
<job-id> | Job id | Yes | None | A job with a done-contract | The job to close. |
--fix-commit <sha> | Commit id | No | The job's own fix commit, if its done-contract names one | A commit id | The commit whose presence in the running build the close proves. On an installed package, only an exact 40-character match with the build's own stamp proves it. |
Arguments for receipt
| Argument | Type | Required | Default | Allowed values | What it does |
|---|---|---|---|---|---|
<job-id> | Job id | Yes | None | A job id | The job whose receipts to print. |
Arguments for drain
| Argument | Type | Required | Default | Allowed values | What it does |
|---|---|---|---|---|---|
--quiet | Flag | No | Off | None | Prints nothing. Exits 1 if the drain failed, otherwise 0. |
How hero verdict gets its answer
Agent OS records a job each time it runs or watches one: a model call through the model gateway, a tool call at the hook, an agent session's end, or a hero ask. When the job ends, Agent OS records its end state from what it observed. A model call that the provider answered ends as finished but unverified, because the gateway knows only that the provider answered. A tool call that Agent OS refused is counted as refused on the screen, not as a failure.
status first records any hook observations still waiting, then reads the record of jobs on your machine. It reads the newest 16 MiB of that record, and says so when the record is larger.
close reads the job's done-contract, a file that lists the job's acceptance criteria, each naming the test that proves it. It runs each test in a separate process, writes a receipt per criterion, and anchors the receipts to a record kept for that job. No hero command creates a done-contract. See Limits.
Get started with hero verdict
Before you start: Agent OS is installed, hero setup has run, and you've used Claude Code or Codex since. These commands work the same on Mac and Linux.
See your recent jobs.
hero verdictYou should see a headline that starts
Activity:, the lineThis shows work ran, not that it was right., and a table of the newest ten jobs. With no jobs, it printsUse Claude Code or Codex as you normally do — your next session shows up here.See the count by end state.
hero verdict --detailsYou should see
jobs,succeeded, anyfailed,crashed,abandonedorstuck (open)counts, andlast job.If the table shows stuck jobs, drive them to an end state.
This command will:
- mark stuck jobs that Agent OS still tracks as stalled, or as abandoned once their grace has passed;
- leave jobs that are no longer tracked open, and list them as unresolved.
hero verdict sweepYou should see
verdict sweep — driving stuck jobs to a terminal verdict, then one line per job, orno stuck jobs in the live store — every tracked open job is still live ✓. Nohero verdictsubcommand reopens a job, so an abandoned job stays abandoned.
Example output of hero verdict
Output from version 0.1.36rc13. Trimmed where you see …
Verdict · all recorded activity
Activity: 31 · 0 verified done · 21 finished, not verified · 2 failed · 0
stuck · 2 asked you · 6 refused
This shows work ran, not that it was right.
┌──────────────┬──────────┬───────────────┬──────────┬────────────┬──────────┐
│ closed (UTC) │ id │ what │ verdict │ proof │ tokens · │
│ │ │ │ │ │ cost │
├──────────────┼──────────┼───────────────┼──────────┼────────────┼──────────┤
│ 11-06 05:43 │ 1daf5c1f │ gpt-5-codex │ ✓ │ unverified │ 15 · │
│ │ │ │ finished │ │ cost ? │
├──────────────┼──────────┼───────────────┼──────────┼────────────┼──────────┤
│ 11-06 05:43 │ 037676a3 │ claude- │ ✓ │ unverified │ 15 · │
│ │ │ sonnet-4-5 │ finished │ │ ~$0.0001 │
├──────────────┼──────────┼───────────────┼──────────┼────────────┼──────────┤
│ 11-06 05:38 │ hook-378 │ tool call │ ✓ │ unverified │ — │
│ │ │ (hook) │ finished │ │ │
├──────────────┼──────────┼───────────────┼──────────┼────────────┼──────────┤
│ 11-06 05:38 │ remediat │ remediation │ ✓ │ unverified │ — │
│ │ │ │ finished │ │ │
├──────────────┼──────────┼───────────────┼──────────┼────────────┼──────────┤
│ 11-06 05:38 │ remediat │ remediation │ ✓ │ unverified │ — │
│ │ │ │ finished │ │ │
├──────────────┼──────────┼───────────────┼──────────┼────────────┼──────────┤
│ 11-06 05:38 │ hook-c3a │ tool call │ ⏸ asked │ waiting │ — │
│ │ │ (hook) │ you │ for you │ │
├──────────────┼──────────┼───────────────┼──────────┼────────────┼──────────┤
│ 11-06 05:38 │ hook-f8b │ tool call │ ⏸ asked │ waiting │ — │
│ │ │ (hook) │ you │ for you │ │
├──────────────┼──────────┼───────────────┼──────────┼────────────┼──────────┤
│ 11-06 05:32 │ commit-b │ commit │ ✓ │ unverified │ — │
│ │ │ │ finished │ │ │
├──────────────┼──────────┼───────────────┼──────────┼────────────┼──────────┤
│ 11-06 05:32 │ hook-c85 │ tool call │ ✓ │ unverified │ — │
│ │ │ (hook) │ finished │ │ │
├──────────────┼──────────┼───────────────┼──────────┼────────────┼──────────┤
│ 11-06 05:32 │ commit-f │ commit │ ✓ │ unverified │ — │
│ │ │ │ finished │ │ │
└──────────────┴──────────┴───────────────┴──────────┴────────────┴──────────┘
newest 10 of 31 rows · unverified = it finished, but no done-contract checked
the result · observe-only = no check attached, so these can't be verified yet
· sessions: hero trace
Prices in this output are estimated, at public list prices unless you set your own rates.
How to read hero verdict output
The headline
The title is Verdict · all recorded activity, or Verdict · newest activity only when the record is larger than hero verdict reads. The headline line counts every job into one group, so the groups add up to the job count:
| Group | What it means | What to do |
|---|---|---|
verified done | Succeeded, and a check proved the result. | Nothing. |
finished, not verified | The job ran and ended, but nothing checked its result. Every model call through the model gateway lands here when the provider answers. | Nothing, unless the job has a done-contract; then run hero verdict close <job-id>. |
failed | Failed, crashed or abandoned. | For a failed model call, the screen prints Run: hero trace show <id>. Run it. |
stuck | Started and never closed. Unresolved, not failed. | Run hero verdict sweep. |
asked you | A tool call held for your approval. Shown only when there are any. | Decide it in hero inbox. |
refused | A tool call Agent OS refused. This is Agent OS doing its job, not a failure. Shown only when there are any. | See why in hero govern. |
Two more groups appear only when there are any. partial counts jobs whose recorded end state is partial: a job with a done-contract is partial when some of its checks pass and others fail. To act on one, look at the criteria that failed, finish or repair that work, and run the verification again. blocked counts model calls a policy refused before they were sent. To act on one, read the reason in the trace and follow that policy's remedy; a retry or an approval in hero inbox doesn't override every refusal.
The headline also counts log lines it couldn't read, so a skipped line never disappears silently.
The table
| Column | What it shows |
|---|---|
closed (UTC) | When the job closed, or started if it never closed, as month-day hour:minute in UTC. |
id | The first eight characters of the job id. |
what | For a model call, the model. For a tool call, tool call (hook). Rows can also read commit or remediation, as in the output above. A failed job adds its reason. |
verdict | ✓ finished, ✗ failed, ✗ crashed, ✗ abandoned, ! partial, ⏳ stuck, ⏸ asked you, ✗ refused or ⛔ blocked by policy. |
proof | What backs the verdict. unverified: nothing checked it. unresolved: a stuck job. waiting for you: a held call. A checked job shows the strength of its check with ✓ when it succeeded, or checked when it didn't: side-effect (it did something real), shape (the output has the right form) or contract (the output is actually right). |
tokens · cost | For a model call, the tokens and estimated cost. — for other jobs, or when nothing was metered. cost unavailable when the cost record couldn't be read. |
The footer says how many rows are shown, and explains unverified and observe-only: a job with no check attached, which can't be verified.
The --details count
One line each for jobs, succeeded and last job, plus failed, crashed, abandoned and stuck (open) when any are present, each marked ⚠. stuck (open) reads registered but never closed — unresolved, not failed.
More hero verdict examples
Example 1. To close a job against its done-contract
hero verdict close <job-id>
On success it prints the receipts, then close succeeded — <n> receipt(s), every one is proof, and exits 0. If a criterion isn't proven, it prints each reason as refused: <reason> and exits 1. A job with no done-contract is refused with exit 2.
Example 2. To read a job's receipts
hero verdict receipt <job-id>
Each receipt lists its schema, receipt id, criterion ids, exit code, commit, the actor that did the work and the actor that checked it (each with a process fingerprint), its record reference, and its status. A close with no executed proof prints UNVERIFIED — close carries no executed proof.
Example 3. To use the verdicts in a script
hero verdict --json
It prints data.jobs, every job, and data.count. envelope.status is ok, empty, or incomplete while hook observations are still being recorded. envelope also carries skipped_lines, spool_unreadable_lines and window. When the record can't be read, data is null and envelope.status is unavailable.
Example 4. To close jobs that are no longer tracked
Use this only when you know the work is over. Their outcome is unknown, and they enter success-rate counts as abandoned.
hero verdict sweep --close-absent-as abandoned --i-understand-this-declares-unresolved-work-finished
It closes them as abandoned, writes a receipt, and prints ⚠ operator-attested: <n> absent id(s) closed abandoned; receipt written.
Exit codes and errors for hero verdict
| Code | Meaning for this command | Cause | What to do |
|---|---|---|---|
0 | Done | status printed, including with no jobs; sweep ran; close proved every criterion; every receipt is proof. | Nothing. |
1 | A truthful negative result | close couldn't prove a criterion; receipt found no receipts, or one isn't proof; a drain failed. | Read the refused: lines or the receipts. |
2 | Refused | A missing job id, a job with no done-contract, an unknown flag, or a sweep flag used wrongly. | See the errors below. |
3 | The record of jobs can't be read | The record or the hook observations waiting to be written are unreadable or damaged. | Run the Check: line the screen prints. |
| Error | Cause | Fix |
|---|---|---|
usage: hero verdict close <job-id> --fix-commit <sha> | close with no job id. Exit 2. | Name the job. |
error: --fix-commit requires a commit SHA | --fix-commit with no value. Exit 2. | Give the commit id. |
error: '<job-id>': no done-contract attached — observe-only jobs can't be verified yet | The job is recorded but has no done-contract. Exit 2. | None. See Limits. |
error: no job '<job-id>' (expected $HERO_HOME/jobs/<job-id>.json) | No job with that id. Exit 2. | Copy the id from hero verdict. |
error: '<job-id>': its done-contract <path> can't be read (<why>) | The done-contract file exists but isn't readable or isn't valid JSON. Exit 2. | Fix the file. |
refused: <reason> | A criterion wasn't proven by close. When the build can't show it contains the fix, the line says how, and suggests --fix-commit <sha>. Exit 1. | Act on the reason. |
usage: hero verdict receipt <job-id> | receipt with no job id. Exit 2. | Name the job. |
refused: --close-absent-as requires a value (only 'abandoned') | The flag was given no value. Exit 2. | Add abandoned. |
refused: --close-absent-as accepts only 'abandoned' (got '<value>') | Another value. Exit 2. | Use abandoned. |
refused: --close-absent-as declares unresolved work finished. | The acknowledgement flag is missing. The lines after it say why. Exit 2. | Add the acknowledgement flag, only if you mean it. |
✗ the verdict log could not be read — verdicts are unavailable, not zero. | The record of jobs is unreadable. A damaged record prints has <n> line(s) and none is a readable verdict instead. Exit 3. | Run the Check: line it prints. |
verdict has no flag '<flag>' | An unknown flag. Exit 2. | Check the synopsis. |
verdict has no verb '<word>' | An unknown subcommand. The rule line lists the subcommands. Exit 2. | Check the synopsis. |
Files and environment for hero verdict
| Name | Kind | Purpose |
|---|---|---|
HERO_HOME | Environment variable | Root of Agent OS's files on your machine, where jobs and receipts are kept. Default ~/.hero. |
| A job's done-contract | File, read by close | Read by hero verdict close. No hero command attaches one to a job; see Limits. |
Limits of hero verdict
| Limit | Behaviour | Can you change it? | What to do |
|---|---|---|---|
| Which jobs it covers | Only jobs Agent OS runs or watches: model calls through the model gateway, tool calls at the hook, agent session ends, and hero ask. Work outside them, such as what a script does after your agent starts it, isn't seen. | No | See what the hook sees. |
| The job count is activity | Every model call and tool call counts as a job, so the count measures activity, not tasks. | No | Read the groups in the headline, not the total. |
| Verified done needs a done-contract | A job reads verified done only when a check proved it. No hero command attaches a done-contract to a job, so jobs read finished, not verified unless one exists. | No | None. |
| Stuck jobs end only when you sweep | Nothing in this build runs sweep on a schedule. A stuck job is marked stalled on one run and abandoned on a later run, after its grace. | No | Run hero verdict sweep again later. |
| Untracked jobs stay open | A job pending in the record but no longer tracked stays unresolved, since its absence says nothing about its outcome. | Yes, with --close-absent-as abandoned and the acknowledgement flag | See Example 4. |
| Record size | Reads the newest 16 MiB of the record of jobs. Older jobs aren't shown or counted, and the screen says so. | No | None. No command caps the size of this record, and hero prune keeps it. |
| Rows shown | The table shows the newest ten jobs. | No | Use --json for every job, or --details for counts. |
--details count | --details can count jobs that had no completion check as succeeded. | No | Use the default view; its verified done count is the one a check proved. |
| Self-protect refusals | A tool call refused because it would change Agent OS's own files or settings isn't counted here. | No | Replay the session with hero trace show <id>. |
| Proving a fix on an installed package | On an installed package, --fix-commit proves the fix only on an exact 40-character match with the build's stamp. An earlier fix can't be proven from the package alone. | No | Run close inside the repository checkout, as the refusal says. |
Commands related to hero verdict
Checked against Agent OS 0.1.36rc14 (build 599c5e120c18) on 17 Nov 2026.