Skip to content

Where things are in the run package ​

Each path below sits in the run package or the workspace tests that cover it.

app ​

PathWhat it holds
packages/run/src/app/args.tsThe flag parsing for the orc command
packages/run/src/app/dispatch-args.tsThe flag parsing for orc backlog, orc attention, orc beat, orc runner, orc merge and orc heavy
packages/run/src/app/dispatch-cli.tsThe orc backlog, orc attention, orc beat, orc runner, orc merge and orc heavy commands
packages/run/src/app/dispatch-args-runner.tsThe orc runner verb parsing and the shared --json flag and reach split
packages/run/src/app/dispatch-args-heavy.tsThe orc heavy verb parsing
packages/run/src/app/help.tsThe help pages: the overview, the per-command help, the usage error text and the closest-command suggestion
packages/run/src/app/help-format.tsThe help layout: wrapping to 80 columns, the usage block and the name and text tables
packages/run/src/app/help-entries-run.tsThe help entries for orc run, the run history commands, orc chat and orc app
packages/run/src/app/help-entries-backlog.tsThe help entries for orc backlog and its subcommands, orc attention, orc beat and orc merge
packages/run/src/app/help-entries-runner.tsThe help entries for orc runner and orc heavy and their subcommands

widgets/beat ​

PathWhat it holds
packages/run/src/widgets/beat/quota.tsThe quota reading from the configured command and the pick of an account
packages/run/src/widgets/beat/beat.tsThe beat: room, placement, take and start
packages/run/src/widgets/beat/beat-close.tsThe closing of finished runs and the running output time
packages/run/src/widgets/beat/beat-place.tsThe room reading, the placement of each new task and the wait it names
packages/run/src/widgets/beat/beat-origin.tsThe orc backlog origin write of a parked task's machine and run, and its refusals
packages/run/src/widgets/beat/load.tsThe five minute load reading and the overloaded machines
packages/run/src/widgets/beat/stall.tsThe stalled run flag kept in the backlog logs
packages/run/src/widgets/beat/task-events.tsThe stall and PR events the beat records for every task
packages/run/src/widgets/beat/board.tsThe terminal board and the orc.backlog.v1 and orc.beat.v1 JSON
packages/run/src/widgets/beat/upstream.tsThe beat’s read of each project’s upstream contributions and the scout task a change adds
packages/run/src/widgets/beat/beat-attention.tsThe beat attention pass: the actions it reports and queues and the questions the decider owns

features/attention-list ​

PathWhat it holds
packages/run/src/features/attention-list/attention-view.tsThe orc attention table and its orc.attention.v1 JSON

features/backlog-planning ​

PathWhat it holds
packages/run/src/features/backlog-planning/cli-add.tsThe orc backlog add command and the intake split of an over budget request
packages/run/src/features/backlog-planning/backlog-plan.tsThe orc backlog plan view of a parent plan and the drop of a new child
packages/run/src/features/backlog-planning/intake-plan.tsThe planner model ask at intake and its five minute limit
packages/run/src/features/backlog-planning/backlog-depend.tsThe task dependency writes and the refusal when a wait would cycle
packages/run/src/features/backlog-planning/backlog-hold.tsThe task hold writes and the refusal when a task is already held
packages/run/src/features/backlog-planning/backlog-drop.tsThe orc backlog drop close of a new task as dropped and its refusals
packages/run/src/features/backlog-planning/backlog-edit.tsThe orc backlog edit rewrite of a new task's title and body
packages/run/src/features/backlog-planning/backlog-priority.tsThe task priority writes and the refusal when a task is taken, started or closed

features/task-thread ​

PathWhat it holds
packages/run/src/features/task-thread/note.tsThe orc backlog note command and its refusal of a task id the backlog does not hold
packages/run/src/features/task-thread/thread.tsThe orc backlog thread view, built on each read from the task file, its attention items and its notes, and its orc.thread.v1 JSON

features/chat ​

PathWhat it holds
packages/run/src/features/chat/chat.tsThe orc chat start of Pi on the orchestrator model with the chat tools
packages/run/src/features/chat/chat-tools.tsThe chat tools and the poll that posts each closed task and each event into the chat once
packages/run/src/features/chat/chat-parked.tsThe chat's listing of parked questions, once per start and once per park
packages/run/src/features/chat/chat-board.tsThe chat's decision boards: the cards, the answers they record and the listing at each start
packages/run/src/features/chat/chat-board-page.tsThe decision board page and the record of its cards
packages/run/src/features/chat/chat-lavish.tsThe lavish-axi launcher that opens, reads and ends a board’s session
packages/run/src/features/chat/chat-backlog.tsThe chat view of the backlog: the open and closed task shapes and the held or parked decision a task waits on
packages/run/src/features/chat/chat-board-bind.tsThe binding of waiting decisions to board records and the words a finished card posts
packages/run/src/features/chat/chat-closed.tsThe closed task shape and the line the chat posts for it
packages/run/src/features/chat/chat-command.tsThe shell a chat tool runs through the shared Bun layers
packages/run/src/features/chat/chat-error.tsThe error a chat tool fails with
packages/run/src/features/chat/chat-inputs.tsThe chat tool input shapes for add, hold, priority, edit, answer, board and merge
packages/run/src/features/chat/chat-posts.tsThe backlog read and the walk that delivers each closed task and event once

features/decider ​

PathWhat it holds
packages/run/src/features/decider/decider.tsThe decider: one call per open question it owns with the rules it reads, its reply checked as an answer on a quoted rule, an ask back, a duplicate link or an escalation, and that decision recorded on the item
packages/run/src/features/decider/decider-guard.tsThe fixed list of topics orc never hands the decider, and the words an ask back hands the worker
packages/run/src/features/decider/decider-ask.tsThe decider's call, Pi on models.decider with the policy as its system prompt and no tools

features/heavy-commands ​

PathWhat it holds
packages/run/src/features/heavy-commands/heavy-cli.tsThe orc heavy path, check, watch and watch-once commands
packages/run/src/features/heavy-commands/heavy-watch.tsThe watchdog that reports stalled calls and queue slips
packages/run/src/features/heavy-commands/heavy-watch-slip.tsThe slip search that finds heavy tool processes outside a running heavy task

features/installing-the-app ​

PathWhat it holds
packages/run/src/features/installing-the-app/app-install.tsThe orc app install copy of the built Herdr App mods, layout and keys merge

features/merging-a-pr ​

PathWhat it holds
packages/run/src/features/merging-a-pr/merge.tsThe orc merge guard and squash-merge

features/queueing-a-task ​

PathWhat it holds
packages/run/src/features/queueing-a-task/alert-stream.tsThe one alert stream orc runner start queues in pueue
packages/run/src/features/queueing-a-task/runner.tsThe runner: the start, the kill and the token renewal through pueue
packages/run/src/features/queueing-a-task/runner-instructions.tsThe project instructions a start carries to the machine that queues the run
packages/run/src/features/queueing-a-task/runner-result.tsThe reading of a task's result and the orc.runner.v1 JSON
packages/run/src/features/queueing-a-task/runner-answer.tsorc runner answer: the answers it hands an asking run and the corrected answers it hands a live run, locally or through a machine's command
packages/run/src/features/queueing-a-task/hold.tsorc runner hold: the wait for a live token, the rerun and the folder removal
packages/run/src/features/queueing-a-task/cli-stop.tsThe stop of a started task: the kill, the result read and the close as stopped

features/running-a-task ​

PathWhat it holds
packages/run/src/features/running-a-task/run.tsThe orc run agent step: checkout checks, agent files and the Pi run in the selected sandbox
packages/run/src/features/running-a-task/sandbox-plan.tsThe per-provider preflight: the Pi login check, the model windows and the run's Pi folder
packages/run/src/features/running-a-task/run-record.tsThe terminal run report, its evidence files and the report.md write
packages/run/src/features/running-a-task/run-exec.tsThe sandbox a run opens, the install that prepares the copy and the steps that run in it
packages/run/src/features/running-a-task/run-loop.tsThe implement, check and fix steps of one run
packages/run/src/features/running-a-task/run-finish.tsThe finish of a run after its checks pass: the direct PR or the no-mistakes gate
packages/run/src/features/running-a-task/run-resume.tsThe prior run's session and passed steps a resume starts from
packages/run/src/features/running-a-task/checks.tsThe check commands .no-mistakes.yaml names and their run in the copy
packages/run/src/features/running-a-task/run-folders.tsA run's folders, its copy of the task file and the instructions file --instructions names
packages/run/src/features/running-a-task/history-write.tsThe history checkpoints a run records as each step starts and ends
packages/run/src/features/running-a-task/context-mark.tsThe 150 thousand token compaction mark orc writes into the run’s Pi folder
packages/run/src/features/running-a-task/report-run.tsThe report run: the Pi run that writes a report file instead of opening a PR
packages/run/src/features/running-a-task/run-deliverer.tsThe deliverer a run takes: the direct PR opener or the no-mistakes runner
packages/run/src/features/running-a-task/run-place.tsThe machine name a run records, read from ORC_RUN_MACHINE
packages/run/src/features/running-a-task/worker-question.tsThe end reason of a run stopped on an unanswered orc_ask and the prompt that resumes it with the answers

features/seeing-runs ​

PathWhat it holds
packages/run/src/features/seeing-runs/show.tsThe orc show reading of one run from the history
packages/run/src/features/seeing-runs/run-history-view.tsThe orc runs table and its orc.runs.v1 JSON
packages/run/src/features/seeing-runs/run-facts.tsThe facts orc runs --json reads beside each run: its title, latest step and open questions
packages/run/src/features/seeing-runs/step-log.tsThe orc log reading of one step's output file
packages/run/src/features/seeing-runs/run-scores.tsThe orc score step score writes: the 1 to 5 check, the note and the unknown run and step errors
packages/run/src/features/seeing-runs/other-machines.tsThe other dispatch machines' runs orc runs --json adds, and the machines it names for those that fail

entities/agent ​

PathWhat it holds
packages/run/src/entities/agent/pi.tsThe Pi prompt and the check of its final reply
packages/run/src/entities/agent/pi-run.tsThe Pi process in JSON mode: its event lines, the agent log, the session file and the idle stop
packages/run/src/entities/agent/agents.tsThe agent file parsing and lookup
packages/run/src/entities/agent/long-session.tsThe long session watch: the turn and compaction counts, the handover note and the handover prompt
packages/run/src/entities/agent/orc-ask-extension.tsThe Pi extension orc copies into the run's Pi folder, which adds the orc_ask tool
packages/run/src/entities/agent/worker-ask.tsThe orc side of orc_ask: the ask-<n> ids, the asking.json it writes, the answers it hands back, the corrected answers it hands on after Pi's next tool call and the 10 minute wait

entities/attention &ZeroWidthSpace;

PathWhat it holds
packages/run/src/entities/attention/beat-action.tsThe beat actions each beat step reports
packages/run/src/entities/attention/attention.tsThe attention queue under attention/: one file per item, its open and close and withdraw, the items of one task, and the review questions, run events and overdue waits routed into it
packages/run/src/entities/attention/attention-overdue.tsThe age of an attention item and whether an open item is overdue
packages/run/src/entities/attention/attention-item.tsThe item file shape, the decider's decisions it records and their text
packages/run/src/entities/attention/failing-command.tsThe failing-command items of running runs whose command keeps failing

entities/backlog &ZeroWidthSpace;

PathWhat it holds
packages/run/src/entities/backlog/backlog.tsThe backlog folders, the id reservation and the atomic take of a task
packages/run/src/entities/backlog/task-record.tsThe task file and its frontmatter
packages/run/src/entities/backlog/task-dependency.tsThe child counts and the waits on dependencies and merged siblings
packages/run/src/entities/backlog/split.tsThe orc.split.v1 planner document and the parent with vertical slice children it applies
packages/run/src/entities/backlog/backlog-write.tsThe backlog file helpers: the error, the scratch publish, the folder paths and the file take
packages/run/src/entities/backlog/runner-label.tsThe task branch names, the run labels and the file keys the runner files use
packages/run/src/entities/backlog/task-kind.tsThe task, run and report kinds, the agent report file name and the run folder
packages/run/src/entities/backlog/task-record-render.tsThe task file rendering from a task record
packages/run/src/entities/backlog/task-record-answer.tsThe answer to a parked question: the captain's or the decider's, and the decider's answer the captain's replaced
packages/run/src/entities/backlog/notes.tsThe task notes under notes/: one <task-id>.jsonl file per task, each note one appended line with its time, writer and text

entities/events &ZeroWidthSpace;

PathWhat it holds
packages/run/src/entities/events/events.tsThe chat events under events/, their posted marks and the alert fires the backlog lists
packages/run/src/entities/events/alert-events.tsThe reading of each alerts.jsonl line as one alert fire
packages/run/src/entities/events/chat-event.tsThe chat event shape: its key, time and text
packages/run/src/entities/events/pr-state.tsThe PR state the beat records under pr-state/: its read and write

entities/heavy-queue &ZeroWidthSpace;

PathWhat it holds
packages/run/src/entities/heavy-queue/heavy.tsThe heavy settings, the stand in folder and the default heavy tool list
packages/run/src/entities/heavy-queue/heavy-setup.tsThe reading of the heavy settings and the writing of the stand in folder
packages/run/src/entities/heavy-queue/heavy-standin.tsThe three line stand in launchers that start the helper for each heavy tool
packages/run/src/entities/heavy-queue/heavy-classify.tsThe per tool decision of which calls queue and which targeted calls take priority
packages/run/src/entities/heavy-queue/heavy-standin-main.tsThe helper a stand in launcher starts by the real bun path, and the waiter a queued pueue task starts
packages/run/src/entities/heavy-queue/heavy-standin-exec.tsThe helper's run of a call: the classify probe, the real tool as a child, the through command and the queued call waiter
packages/run/src/entities/heavy-queue/heavy-standin-runtime.tsThe stand in runtime: the helper command, the real tool lookup, the bypass event, the plan of a call and the queue wait
packages/run/src/entities/heavy-queue/heavy-process-tree.tsThe process tree walk that finds a call inside a held slot or under the through command
packages/run/src/entities/heavy-queue/heavy-pueue-task.tsThe reading of pueue status and log JSON for the queue wait and the exit code

entities/orc-rules &ZeroWidthSpace;

PathWhat it holds
packages/run/src/entities/orc-rules/orc-rules.tsThe reading of <ORC_HOME>/orchestrator.md and the projects' instructions files that the chat and the decider load

entities/parked-runs &ZeroWidthSpace;

PathWhat it holds
packages/run/src/entities/parked-runs/parked.tsParking a run's task on its questions, and the answer to a hold or a question

entities/pull-request &ZeroWidthSpace;

PathWhat it holds
packages/run/src/entities/pull-request/pr-view.tsThe gh pr view reading of a task's PR and its check verdicts
packages/run/src/entities/pull-request/merge-basis.tsThe captain-word and yolo-green bases orc merge takes
packages/run/src/entities/pull-request/direct-pr.tsThe direct PR opener: the push, the existing check and the create, and the opened or failed record

entities/review-gate &ZeroWidthSpace;

PathWhat it holds
packages/run/src/entities/review-gate/no-mistakes.tsThe no-mistakes step: the gate answers, the refusals and the findings it records
packages/run/src/entities/review-gate/answer-wait.tsThe wait at a no-mistakes gate for the captain’s answers in the run folder
packages/run/src/entities/review-gate/no-mistakes-drive-log.tsThe no-mistakes drive log: the run record it keeps and the ending it reports
packages/run/src/entities/review-gate/no-mistakes-gate.tsThe no-mistakes gate output parsing: the findings, the open questions, the gate answers and the respond arguments

entities/run-history &ZeroWidthSpace;

PathWhat it holds
packages/run/src/entities/run-history/report.tsThe report.md shape and the signal facts it carries
packages/run/src/entities/run-history/run-history.tsThe records home, the SQLite run history and orc runs
packages/run/src/entities/run-history/gate-refusals.tsThe gate and rule parse from a failed check’s output, the refusal history signals and orc refusals
packages/run/src/entities/run-history/history-resume.tsThe resume reads from the run history: the latest run for a branch, its steps, its check rounds and its fixes

entities/task-copy &ZeroWidthSpace;

PathWhat it holds
packages/run/src/entities/task-copy/checkout.tsThe checks on the checkout a run starts from: its git root, refused markers, uncommitted changes and branch name
packages/run/src/entities/task-copy/worktree-excludes.tsThe registered worktrees inside a checkout that its clean check leaves out
packages/run/src/entities/task-copy/task-copy.tsThe task copy under $ORC_HOME/worktrees, keyed by the project folder's name, a hash of its real path and the branch, its reuse and removal, and the agent's git identity
packages/run/src/entities/task-copy/refresh.tsThe fast-forward of the checkout's default branch when a run starts

entities/token &ZeroWidthSpace;

PathWhat it holds
packages/run/src/entities/token/token.tsThe orc.token.v1 document, the token command and the Claude credentials reading
packages/run/src/entities/token/held-token.tsThe owner-only token folder a run on another machine reads

shared/config &ZeroWidthSpace;

PathWhat it holds
packages/run/src/shared/config/orc-config.tsThe reading of config.json: the providers, the heavy queue tuning and the implementer, fixer, orchestrator, planner and decider models
packages/run/src/shared/config/json-file.tsThe JSON config file reading and its ConfigError
packages/run/src/shared/config/model-route.tsThe choice of the configured provider for the agent models and the check of a token file
packages/run/src/shared/config/dispatch-config.tsThe reading of dispatch.json and projects.json
packages/run/src/shared/config/machine-reach.tsThe sweep ownership check and the remote command prefix
packages/run/src/shared/config/delivery.tsThe delivery modes and the run delivery a project and its tasks take

shared/lib &ZeroWidthSpace;

PathWhat it holds
packages/run/src/shared/lib/run-session.tsThe OrcRunError a run fails with
packages/run/src/shared/lib/toon.tsThe reading of the TOON output no-mistakes prints
packages/run/src/shared/lib/table.tsThe table formatter the runs and refusals listings share
packages/run/src/shared/lib/run-id.tsThe new run id from the timestamp and a random part

shared/process &ZeroWidthSpace;

PathWhat it holds
packages/run/src/shared/process/git-run.tsThe git calls orc makes on the host with the operator's git config hidden
packages/run/src/shared/process/runner-error.tsThe runner's error
packages/run/src/shared/process/pueue-status.tsThe pueue status shapes and the held-task lookup the runner reads
packages/run/src/shared/process/runner-exec.tsThe process running helpers: the quiet spawn, the output capture, the pueue call, the JSON reads and the group setup

shared/sandbox &ZeroWidthSpace;

PathWhat it holds
packages/run/src/shared/sandbox/sandbox-kind.tsThe sandbox kinds a run takes
packages/run/src/shared/sandbox/nono.tsThe nono sandbox environment, its roots and the nono why check of a rendered profile
packages/run/src/shared/sandbox/nono-exec.tsThe opening of the nono sandbox a run's commands go through: the runtimes, the shims and the checked profile
packages/run/src/shared/sandbox/standin-dir.tsThe stand in folder suffix nono strips from the host path
packages/run/src/shared/sandbox/agent-exec.tsThe one way a run starts Pi and the checks, in nono run or on the host, with the environment built from an allow list
packages/run/src/shared/sandbox/host.tsThe host-side processes and tools orc runs outside nono, and the guard on host git
packages/run/src/shared/sandbox/nono-profile.tsThe nono profile that lets a command write only the copy, its git data, the Pi session folder and the run's sessions folder, and routes the model credential
packages/run/src/shared/sandbox/git-config.tsThe git config parsing that finds the credentials, includes and submodules a checkout carries

Entry point &ZeroWidthSpace;

PathWhat it holds
packages/run/src/bin.tsThe orc entry point

Package files &ZeroWidthSpace;

PathWhat it holds
packages/run/agentsThe bundled agent files
packages/run/agents/decider-policy.mdThe written policy the decider answers under

Tests and workspace &ZeroWidthSpace;

PathWhat it holds
tests/unitThe in-process unit tests at the workspace root
tests/e2eThe tests that run packages/run/src/bin.ts, git or nono as a process, with a live Pi run through ORC_PI_E2E=1, at the workspace root
tests/fixtures/runner/pueueThe pueue 4 status JSON the runner tests read
tests/liveThe tests that run a real nono sandbox with ORC_NONO_E2E=1 set, or the host's Pi, through the test:live script at the workspace root
.no-mistakes.yamlThe check commands no-mistakes and CI run at the workspace root