A run ​
A run is one attempt at one task by orc run, from a task file to a pull request or a report. The beat starts most runs through the runner, and you can start one by hand in any clean checkout with orc run <task-file>.
flowchart TD
copy[Copy the project to a<br/>worktree on a new branch]
prepare[Run the prepare command]
pi[Pi works and commits,<br/>then prints ORC_COMPLETE]
checks{The project's checks}
fix[A fixer Pi repairs<br/>what failed]
deliver[Deliver: review,<br/>push and pull request]
record[(The run folder:<br/>logs, session, report)]
copy --> prepare
prepare --> pi
pi --> checks
checks -- red, up to 3 fixes --> fix
fix --> checks
checks -- green --> deliver
deliver --> record
An isolated copy ​
Orc refuses a checkout with uncommitted changes. It then makes a git worktree of the project on a new branch under ~/.orc/worktrees, so the agent never touches your own checkout. Before Pi starts, orc runs the prepare command from the project's .no-mistakes.yaml, such as an install.
The agent ​
Orc runs only the Pi agent, and it starts Pi itself. A run you start by hand works inside the nono sandbox by default, and --sandbox none runs it on the host. The agent file implementer.md holds Pi's instructions, and config.json names the model. The prompt is the task, and it asks Pi to print ORC_COMPLETE on its own line once the work is committed.
Orc watches Pi while it works.
- It stops a Pi that has printed nothing for 45 minutes with no tool running.
- When Pi fails one command 3 times in a row, orc tells you through the attention queue.
- When Pi fails one command 6 times in a row, orc stops Pi and asks you whether to continue.
- Pi can ask you a question mid-run with its
orc_asktool instead of guessing.
When a run counts as done ​
A ship run records success only when all of these hold.
- Pi's final reply stopped cleanly with
ORC_COMPLETEon its own line. - The branch holds at least one new commit.
- The project's checks pass.
- The pull request is open, and on a
no-mistakesrun CI is green.
A scout or task run makes no branch and no pull request. It counts as done once Pi wrote agent-report.md into the run folder.
The record ​
Each run keeps its task, its logs, its Pi session and its report.md in ~/.orc/runs/<run-id>. orc runs lists the runs, orc show <run-id> shows one step by step, and orc log <run-id> <step-id> prints one step's output.
Stopping and resuming ​
A run that stops can resume on its branch with orc run --branch <name>. Orc skips the steps the record marks passed, and Pi resumes its earlier session. A run whose session reaches 300 turns or 5 compactions writes handover.md, so the next run on the branch starts from that note.