akougkas.io

Why CLIO Coder, part 4 of 5: bounded workers, sealed receipts

CLIO Coder sends work to bounded worker agents that declare their read and write scope before they run, verifies the result on the host, and seals a receipt every time. Delegation you can watch and audit, tested at v0.5.2.

Published
Reading
8 min read
Topics
agents, systems, building

September 27, 2026: Later releases changed worker authority and simplified new receipts, including removal of the receipt attestation field. Older receipts still verify. See the current product guides and release history.

A spinner is not accountability. When an agent farms work out to a second agent, the interesting question is not whether the second one finished but what it was allowed to touch, what was checked afterwards, and who can read that back a week later. CLIO Coder, the terminal coding agent I create and maintain inside CLIO, answers all three with the same mechanism: a dispatch declares its scope before it runs, the orchestrator verifies the result itself, and every run seals a receipt. CLIO Coder v0.5.2, released September 21, 2026, is the reference here.

A dispatch declares its scope before it runs

Delegation in CLIO Coder is a typed call, not a paragraph of instructions. A request carries an intent object with read_roots, write_roots, relevant_paths, expected_outputs, and a list of verification checks. Paths are normalized into sorted, duplicate-free repository-relative POSIX entries under entry and byte caps; an absolute, escaping, or malformed entry fails before the approval step, not halfway through the work.

The declaration is authoritative. Five containment checks share one path grammar, where a trailing slash means a subtree and its absence means an exact file, so admission reasons about the same scope the worker will be held to. A declared write scope is the scope; a path that prose inference would have contributed but the declaration omits is reported to the operator by name rather than quietly added.

A verification entry names a check id, never a command. Admission resolves it through the same declared-check projection the verify tool reads, which is your package scripts and .clio-coder/verifiers.yaml, so model text never becomes argv. The resolved argv, working directory, and timeout are frozen into the execution snapshot and into the plan hash the approval renders. When the worker reports success, the orchestrator runs each check itself through the code-step runner, with no shell and a closed environment allowlist, and seals the result. A rejected check turns the run into host_verification_rejected, an outcome that suppresses automatic retry, because the tree is what failed, not the worker’s luck.

The same worker, one SSH hop away

A worker is a process that reads one JSON specification on stdin and writes newline-delimited events to stdout. A remote worker is that exact protocol tunneled through ssh -T, so distance changes nothing about prompts, safety, receipts, or telemetry. Fleet nodes are declared under fleet.nodes with a host, labels, and a per-node worker cap; the implicit local node always exists.

Before its first model call, every native worker announces itself on a structured control lane and attests its protocol version, process group, host, settings fingerprint, its own computed digest of the specification it received, runtime and target ids, endpoint identity hash, wire model id, tool signature, and bounded node facts. Drift from the approved identity kills the whole process group. Placement and admission stay separate: pins restrict the eligible node set and fail closed rather than falling back, unpinned placement prefers the node with lower durable lease usage, and one cross-process lock over a shared lease file is the final capacity authority. A run records the node its worker process ran on, which is not the node serving the model.

The dispatch loop: a session sends typed intent, a worker runs on a fleet node, the orchestrator runs host verification, the run seals a receipt, an evidence bundle is written to disk, and the command clio-coder evidence list reads it back. session typed intent fleet worker host checks sealed receipt evidence clio-coder evidence list
The path a dispatched run takes, from the session's typed intent through a worker on a fleet node, host verification, the sealed receipt, and the evidence bundle a later command reads back.

Every run seals a receipt

The receipt is the unit of accountability. It carries one current integrity version, 20, which authenticates the complete receipt against reconstructed ledger provenance; a receipt sealed under a lower version is reported as retired, is never migrated, and is never read as evidence. Under that digest sit the node the worker ran on, failover hops, the plan hash and cost ceiling, the byte count and hash of the briefing without the briefing prose, the normalized intent, the host-verification evidence with argv, exit codes, and a bounded output tail, and the terminal outcome code.

When a dispatched run finalizes, an evidence bundle is compiled under the data directory and a compact row lands in a sidecar index. The bundle holds an overview, a readable transcript, raw and cleaned trace rows, tool events, linked audit rows, the receipt, gate decisions, a per-run trust projection, protected-artifact state, and findings in both machine and human form. Attribution is recorded rather than guessed: an entry stamped with a run id at write time is marked exact, and an entry falling inside more than one concurrent run’s window appears in every candidate bundle with a null run id and the candidate list, never dropped and never claimed as exact.

v0.4.4 closed the gap this all exists to close, which is a turn that talks its way past its own finish contract. A turn that could not verify something now records that through a limitation tool call whose receipt has to land inside the same window as the mutation scan; the seven prose patterns that used to satisfy the gate are gone, so wording alone no longer passes it. The decide tool records a design choice with the alternatives the model rejected, and dispatch seals every active decision reference onto the request, the envelope, and the receipt. Verifier catalogs gained two executable check kinds beside a plain command, one judging JSON numbers against a reference file under named tolerances and one judging wall time against a budget or a recorded baseline, and host verification runs and seals those judgements too.

None of it is worth much if only the terminal can see it. Behavioral results carry an execution envelope binding prompt fragment ids, versions, content hashes, and a composition hash to the recipe, route, tool surface, autonomy, and policy hashes, so a comparison across releases marks a row incomparable instead of averaging over a prompt that moved underneath it. Hosts speaking the Agent Client Protocol can opt into an accountability.evidenceReady event carrying the run id, evidence id, first-pass success, finding count, and tags, once per run whose bundle and index row landed; bundle prose never crosses the wire, and a failed build sends nothing. In the terminal, /tree walks the session tree and /fork branches from an assistant turn, so the history a receipt is filed against stays navigable. CLIO Coder is experimental by design and pre-1.0; the receipt chain is the part I would defend hardest.

Try it

Dispatch one worker explicitly and let it come back with an answer and a receipt:

clio-coder run --agent coder "Find the main build, test, and lint commands."

The same harness runs headless, streaming newline-delimited JSON events instead of prose:

clio-coder run --json "Investigate the failing parser test and report the evidence."

Then read what happened, without asking the agent to characterize its own work:

clio-coder trace runs --limit 10
clio-coder evidence list
clio-coder evidence inspect run-<runId> --json

You will see the bundle for each finished run, and inside it the sealed receipt with the node, the frozen check argv, the exit codes, and the trust projection for that run. In the interactive session the equivalent is /run coder <task> for the dispatch and /view verify <runId> for the receipt.

What is left for you

The mechanism is in place; the vocabulary of what counts as proof is not finished. Two tags in the evidence taxonomy keep me up: proxy-validation, a check that only confirmed a file exists, and no-validation, a run that succeeded and ran nothing. Both are honest labels for a weak result, and the interesting work is in how a project declares what a strong one would have been. The verifier catalog is where that declaration lives, and a numeric tolerance or a performance budget from your own domain is a more useful contribution than another opinion about agents. The source, the changelog, and the architecture documents behind every claim here are at github.com/iowarp/clio-coder; the GPU tutorial has the install depth.

Next in the series Part 5: Decisions without prose

Sources, code, and records

  1. source

    CLIO Coder v0.5.2 release

    The release of September 21, 2026, that this part describes.

  2. source

    CLIO Coder v0.4.4 release

    The trust spine, September 5, 2026: typed claims, executable validation, and decision provenance.

  3. source

    CLIO Coder v0.3.7 release

    Typed dispatch intent and host-run verification, August 24, 2026.

  4. source

    CLIO Coder on GitHub

    The source, the changelog, and the architecture documents behind every claim here.

  5. source

    Can an agent run be a scientific record?

    What a sealed run record proves and what it cannot.

  • 2023–present
    active

    CLIO Coder

    A local-first coding agent with typed tools, bounded workers, and receipts

  • 2025–present
    active

    CLIO

    A context layer for scientific AI agents and workflows

More on CLIO Coder

  1. essay

    Reliable work from unreliable agents

    A coding agent is a system built around one brilliant, persuasive, unreliable component. The argument of my November 9, 2026 lecture on agentic engineering: five ideas for building trustworthy work around that component, what they could do for science, and the problems still open.

    14 min
  2. essay

    CLIO as the entry point

    CLIO should become the single place a developer starts with IOWarp, built as an application SDK with deployment profiles rather than an umbrella package or a gateway service. This is the direction for 2027; the API and the scope are still open.

    6 min
  3. essay

    A capable model in a capable harness

    Claude 3.5 Sonnet brought me back to writing code. A capable model still needs a harness that makes its progress checkable and its cost visible, and CLIO Coder is the one I built around models that many people can afford to use.

    4 min