What a run leaves behind¶
I leave records another engineer can audit without asking me.
Status: in daily use · checked Oct 26, 2026
In plain terms
This page shows the artifacts the system produces: what a worker is told, what the ledgerThe run ledger: relational records of dispatched runs, with reapers and stall timers. Glossary records, how a task closes, and what the independent reviewerIn the main repositories, a separate agent whose recorded decision is a required pull-request check; only its identity can post it. Glossary writes down. These are synthetic examples using the actual schema; they aren't actual run records.
run)) --> B[The brief
it was given] R --> L[Its row
in the ledger] R --> D(The reviewer's
recorded decision):::guard R --> C[The record that
closes the task]
The brief a worker gets¶
A worker can't see my conversation with the coordinatorThe agent session that triages work, picks a lane, dispatches workers, and verifies results. Glossary, so the briefThe bounded instructions given to a dispatched worker before it edits or runs commands. Glossary is self-contained. This sample is made up for illustration. It is shaped like a real one.
TASK: Add a freshness check to the documentation build.
GOAL
A page whose last-verified date is older than the limit for its
state must fail the build with the page name in the message.
OWNED PATHS (you may change these and nothing else)
scripts/docs/check_freshness.py
tests/docs/test_check_freshness.py
DEFINITION OF DONE (a command whose output proves it)
pytest tests/docs/test_check_freshness.py -> all pass
python scripts/docs/check_freshness.py --self-test
-> the planted stale page is REFUSED, the fresh one passes
DO NOT TOUCH
generated files, the page templates, anything outside OWNED PATHS.
Do not push. Commit in your worktree and report.
REPORT BACK
- the commit id
- the output of both commands above, verbatim
- anything you could not verify, labeled "unverified"
The owned pathsThe files a lane or phase is allowed to change. The runner compares each phase's diff against them afterwards and fails the phase on a stray file. Glossary are what the runner or the reviewer later compares the diff against. The definition of done is a command, so "done" is a result and not a feeling. The exclusions are as important as the goal. And "unverified" has a place in the report, so that "I could not check" isn't the same as "it works".
The shape of a ledger row¶
Every dispatched runA row in the run ledger for a tracked worker run: who launched it, which worktree, state, and last progress. Glossary is a row. The fields, grouped, with what they hold and how well they are filled in:
| Group | What it holds | Filled in |
|---|---|---|
| Identity | a run id, who launched it, which lane, which repository | on every row, by design |
| Isolation | the worktree the worker used | on write lanes, by design |
| Tool and tier | which agent tool ran, which routing tier it resolved to | on every row, by design |
| State | where the run is: running, done, failed, held at closeout, died, wedged | on every row, by design; the vocabulary is on measuring agent reliability |
| Time | when it started and when it last made progress | on every row, by design |
| Result | whether the worker's own terminal result event was seen | on every row, by design; this decides "done" |
| Delegation | the parent run and the depth, if it is a child | only on child runs; only 30 of the 8,047 records in the run-ledger snapshot of Oct 26, 2026 are child runs |
| Cost | the reserved cap for the tree, and the actual cost | the cap is set on most rows; actual-cost coverage: only 134 of the 8,047 records in the run-ledger snapshot of Oct 26, 2026 record an actual cost |
| Tokens | input and output token counts | the fields are in the schema |
Only the delegation, cost and token lines were counted for this page; the rest is how the schema is meant to be used. Cost routing covers the cost controls.
An illustrative record, with values replaced by labels:
run : <id>
lane : courier
tool : <worker tool> tier : default
repository : <repository> worktree : <isolated checkout>
state : done
result event : seen
started : <time> last progress : <time>
parent : none depth : <n>
cost cap : <reserved for tree> cost actual : <empty>
tokens : <empty>
A closeout record¶
Where the closeout mechanism is enabled, closing a task requires a typed record naming the landed change, the checks, the owner and the time. Rollout is still in progress.
task : <task id>
landed : <change id on the main branch>
checks run : <the named set that ran on that exact version>
closed by : <role> at : <time>
The line that carries the weight is "the named set". A change once merged with every check that ran green while other required checks had been skipped, so "CI is green" isn't evidence about a particular closure. Naming the set is. The mechanism is on how agent output is trusted, including how much of it is enforced today and how much is still being staged.
A reviewer decision¶
The independent reviewer writes its decision in its own log first, and only then is anything posted to the pull request. A decision carries:
- the exact version of the change it read, so a later push voids it;
- the checks it saw on that version;
- pass or fail, and the reasons;
- whether it ran the change or only read it. A read-only pass is labeled as such, because a review that only reads the code can miss what running it would catch.
A coded error¶
Service errors carry a code in a fixed format (domain, category, number) and a link to the one runbookAn alert-linked page describing what a rule means and first steps; generated stubs fill gaps without overwriting hand-written pages. Glossary for that code: 20 coded service errors, one to one. An agent that hits one lands on a page that says what the error means, how to confirm it and what to do first.
A page that states its own age¶
Every public page carries a state, a last-verified date and a line saying what it was checked against, at the top of the page source. That is what lets a freshness check fail a stale page, and it is why you can see how old a claim is (documentation that stays true).
What I have not published¶
Real briefs, real run records and real reviewer logs name repositories, hosts and people, so they stay private. What is here is the structure, which is the part that tells you whether the system can be audited. I'd rather show you an example that says it is invented than a real one with the interesting parts blacked out.