# Millrace summary

Millrace is an open-source, filesystem-backed runtime for long-running autonomous agent work. It is not a coding model, not an IDE, and not a hosted autonomous engineer. It sits around raw agent harnesses and gives them durable queue state, compiled runtime plans, deterministic handoffs, recovery routing, operator control surfaces, and persisted audit artifacts.

As shipped today, the importable package namespace is `millrace_ai`, the installed CLI is `millrace`, and the module entrypoint is `python -m millrace_ai`. The runtime bootstraps its working tree under `<workspace>/millrace-agents/`, where it keeps markdown work queues, runtime snapshot state, compiled plans, mailbox/control files, run artifacts, and Arbiter closure artifacts.

The current runtime has two planes:

- execution
- planning

The shipped built-in loop ids are:

- `execution.standard`
- `planning.standard`

The shipped canonical mode ids are:

- `default_codex`
- `default_pi`

The compatibility alias `standard_plain` resolves to `default_codex`.

The shipped execution stages are:

- `builder`
- `checker`
- `fixer`
- `doublechecker`
- `updater`
- `troubleshooter`
- `consultant`

The shipped planning stages are:

- `planner`
- `manager`
- `mechanic`
- `auditor`
- `arbiter`

Millrace keeps canonical work as markdown documents:

- tasks: `millrace-agents/tasks/{queue,active,done,blocked}/*.md`
- specs: `millrace-agents/specs/{queue,active,done,blocked}/*.md`
- incidents: `millrace-agents/incidents/{incoming,active,resolved,blocked}/*.md`

It keeps runtime-owned state and compile outputs under `millrace-agents/state/`, including:

- `runtime_snapshot.json`
- `recovery_counters.json`
- `compiled_plan.json`
- `compile_diagnostics.json`
- `execution_status.md`
- `planning_status.md`

Each stage run persists artifacts under `millrace-agents/runs/<run-id>/`, including stage results plus runner prompt, invocation, completion, and stdout/stderr artifacts where present.

The runner boundary is stable and narrow:

- input: `StageRunRequest`
- output: `RunnerRawResult`

The shipped built-in adapters are:

- `codex_cli`
- `pi_rpc`

Use Millrace when the work must survive pauses, crashes, context loss, retry loops, closure audits, or multi-stage routing. Do not use Millrace for tiny one-shot edits where the runtime overhead would be larger than the work.

See also:

- `/ai/what-is-millrace.md`
- `/ai/architecture.md`
- `/ai/install.md`
- `/ai/cli-reference.md`
- `/ai/modes-and-loops.md`
- `/ai/runner-architecture.md`
- `/ai/arbiter-and-completion.md`
- `/ai/comparisons.md`
- `/ai/faq.md`
- `/ai/glossary.md`