arc: the files

This page covers the files arc keeps; the commands are in arc, the scheduling loop is in arc/loop, and the gate and its failures are in arc/gate.

config.toml#

init writes config.toml and every other subcommand reads it. Unknown keys are refused by name, and schema_version must be 1. A key you leave out takes its default.

gate.profiles.<name> above is written out as gate.profiles.default in the file init writes. A stage may be listed once per profile: a profile that lists a stage twice, or that lists integration, is refused by name. A per-task field of the same name overrides a [limits] value for that task; a plan budget adds to the task budgets.

An attempt's worker session id is decided by its claim, which writes it to attempts/<task>/<attempt>/start.json; the wrapper writes the session it used to identity.json when it spawns the worker and to execution.json when it ends. A reader takes the first of those records that names one: execution.json, then identity.json, then start.json. With worker.rework_session = "fresh" it is <task>-<attempt>; with resume it is the task id. radian arc show prints it as session_id (known from the claim on, not only after the attempt ends), and radian attach <session id> opens that session's journal.

The same records name the worker the attempt runs: the claim writes the worker it decided on (the worker field; worker.command takes effect at the next claim), and the wrapper writes the worker it started when it spawns it and when it ends. A reader takes the first of those records that names one, in the same order, so a running attempt keeps its kind when config.toml changes; the arc TUI's conversation tab uses that record, not the current configuration, to choose between a journal and a command worker's stdout.

Every review run of an attempt has a session of its own, named <attempt id>-review-<run>. When a journal of that name already exists (a gate was started again for the same attempt), the stage uses <attempt id>-review-<run>-<k> with the smallest free k and writes the run's logs as review-<run>-<k>.jsonl and review-<run>-<k>.stderr.log under the attempt's logs/; the review verdict's review_session_ids lists the ids it used.

worker-brief.md#

<repository>/.radian/arc/worker-brief.md is the repository's standing worker instructions. It is optional. radian arc init writes it with this default when the file does not exist, and never overwrites a file you edited:

Work only on the current branch.
Commit everything that belongs to the change, and end with `git status --short` printing nothing.
Put scratch files only under `.radian/`.
Never change `.radian/arc/`.
While iterating, run only the tests being changed, and run each named crate in full once at the end; never the whole workspace.
In a `MUTATIONS.md`, add a new section at the end of the file, with one blank line before its `##` heading.
End with a short report: the commits, the tests you ran, the decisions you made, and any open questions.

When the file exists and is not empty after trimming, every brief a worker receives ends with its content: after the merge-main conflict section, the hand-off section of a fresh rework, and the task's own brief. That covers a first attempt, a rework (fresh or resume), and a follow-up task arc wrote. The wrapper reads the file when it composes an attempt's brief, so an edit takes effect at the next attempt; no restart is needed. A missing file and one that is empty after trimming change nothing.

A file over 32 KiB (32,768 bytes), a file that is not UTF-8, a path that is not a regular file (a FIFO, a directory, a device), and a read error are not appended: the attempt runs without the section, its record carries one line worker-brief.md skipped: <reason>, and radian arc show prints it as attempt_note. The worker never reads the file itself: its sandbox denies .radian/arc/, and the wrapper puts the content on the worker's stdin.

A brief that points at a file under .radian/arc/runs/ gets a copy as well: when the wrapper composes the brief, it copies the file into the worker's worktree at .radian/arc-verdicts/<task>/<attempt>/<file> and puts that worktree-relative path in the brief, so the worker reads the copy and the sandbox rule does not change. The task file keeps the absolute path. A file that is missing, is not a regular file, is larger than 1 MiB, or cannot be copied stays in the brief as the path it already had, and the attempt record carries verdict copy skipped: <path>: <reason> in its notes, next to the worker-brief.md skipped: line.

Plan and task files#

A plan file is plans/<id>.md; a task file is tasks/<id>.md. Both are front matter between two --- lines, then a body. arc is the only writer; you change them with the radian arc subcommands, and adopt after a hand edit.

An id is a prefix of 1 to 4 uppercase ASCII letters, a four-digit number, a dash, and a slug (PL0001-first, TK0001-work). [ids] plan_prefix (default PL) and [ids] task_prefix (default TK) set the two prefixes; they must differ, and a prefix that is empty, not 1 to 4 uppercase letters, or equal to the other is refused by name when config.toml is read. Plans and tasks count in separate number sequences: a new id takes the next free number above the highest number any item of that kind (a file or a ledger entry) uses, whatever prefix that item carries, and the number is never reused while its ledger entry exists. An id without a prefix is not an id (exit 2). Any prefix of 1 to 4 uppercase letters is a well-formed id, and the kind comes from the directory it is looked up in (plans/ or tasks/), not from the prefix: an item created under an earlier prefix keeps working after the prefix changes. The id is the file name and never changes. An id names one item: show, adopt, reset-budget, cancel, and the MCP show tool refuse an id that names both a plan file and a task file with exit 3 (the MCP tool: a tool error), name both files, and change nothing.

Plan fields#

The body is the request text, then a ## Change records section. Each change record is a ### <UTC time> line (the shape YYYY-MM-DDTHH:MM:SSZ), a blank line, and the text of the change. A confirmed plan gains records only; a draft plan may have its request text replaced, which keeps the records below it. A cancelled plan takes no change record: it is final. priority is written only once you set it with radian arc priority; until then the field is absent and the plan reads as P3, so an older plan file is written back unchanged.

Task fields#

The body is the original brief, then zero or more ## Rework <n> sections, then the ## Changes section. The MCP update_task tool replaces the original brief and keeps every rework section and the change records below it. ## Changes holds one line per successful update_task call, in the order they happened: - <UTC time> update_task: <the fields the call gave, comma-separated>, where the time has the shape YYYY-MM-DDTHH:MM:SSZ; the first call creates the section.

States and phases#

A new task is todo / ready. A todo / retry_wait task is claimed at once by radian arc start, without waiting for its retry_at; the scheduling loop waits for retry_at (see radian arc start). A task the lead adds to a confirmed plan (MCP add_task) or arc proposes as the plan's review follow-up is todo / proposed: the scheduling loop never claims it and start refuses it until you run radian arc confirm <task>. A plan is done when all of its tasks are merged; done is not a stored plan status. A cancelled plan is final: radian arc cancel <plan> sets it after ending every task cancel accepts in the plan (see radian arc cancel). No command confirms it, adds a task to it, changes its auto or priority, resets its budget, or starts, reverifies or gates its tasks, and list hides it unless --all.

The review states#

A task leaves doing for review.verifying when a pushed attempt ends.

The .radian/arc/ layout#

Everything arc stores for one repository is in <repository>/.radian/arc/:

Every change is one transaction under state.lock: take the lock (waiting up to 5 seconds, then exit 4), compare the file with the ledger, write a temporary file, flush it to disk, rename it over the old one, flush the directory, record the new version and hash in the ledger, release.

Search skips worktrees/ and gates/: grep, glob, skill discovery, and @ completion do not enter them. Both are full checkouts of the tree, so searching them would return every file once per task and once per gate stage. They skipped .radian-worktrees/ for the same reason. A worker never reads the rest of .radian/arc/ from inside its checkout: the worker wrapper denies every entry except worktrees/.