# FAQ

## What is Millrace in one sentence?

Millrace is an open-source, filesystem-backed runtime for long-running autonomous agent work that wraps raw harness execution with durable queues, compiled plans, deterministic routing, and persisted artifacts.

## Is Millrace a model?

No. Millrace is not a model. It is a runtime layer that dispatches stage work into external harness adapters and then applies authoritative state transitions after legal stage results come back.

## Is Millrace an IDE?

No. Millrace is not an IDE or editor surface. Its main operator surfaces are the `millrace` CLI, the `python -m millrace_ai` module entrypoint, and the runtime workspace tree under `<workspace>/millrace-agents/`.

## Does Millrace replace Codex CLI, Claude Code, or Aider?

No. Millrace is not a replacement for those tools. Those are direct harness or editor workflows. Millrace is the runtime and governance layer that can sit around raw harness execution when the work needs durability and explicit control flow.

## What harness adapters ship today?

The shipped built-in adapters are:

- `codex_cli`
- `pi_rpc`

The shipped canonical modes are `default_codex` and `default_pi`. The compatibility alias `standard_plain` resolves to `default_codex`.

## What package surfaces does Millrace expose?

- package name: `millrace-ai`
- import namespace: `millrace_ai`
- installed CLI: `millrace`
- module entrypoint: `python -m millrace_ai`

## Where does runtime state live?

Under the workspace runtime root:

```text
<workspace>/millrace-agents/
```

That tree contains queue documents, runtime snapshot state, compile outputs, mailbox/control files, Arbiter artifacts, and per-run execution artifacts.

## What is canonical queue state?

Canonical queue artifacts are 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`

JSON is still accepted for import, but the canonical long-lived queue artifacts are markdown.

## What are the two runtime planes?

The shipped runtime has:

- an execution plane
- a planning plane

The shipped loop ids are `execution.standard` and `planning.standard`.

## Which execution stages ship today?

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

## Which planning stages ship today?

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

## What does `standard_plain` mean?

It is a compatibility alias, not a separate third mode asset. `standard_plain` resolves to `default_codex` before compile diagnostics, frozen-plan ids, and runtime snapshot state are written.

## What does the compiler do?

The compiler freezes the selected mode plus execution and planning loops into one `CompiledRunPlan` and persists it under `millrace-agents/state/compiled_plan.json`. It also writes `compile_diagnostics.json`.

Use:

- `millrace compile validate`
- `millrace compile show`

to inspect the effective runtime structure.

## What is the runner contract?

Millrace keeps a narrow runtime boundary:

- `StageRunRequest -> RunnerRawResult`

That is what lets the runtime change adapters without changing the orchestration model.

## Where do run artifacts go?

Each run persists under:

```text
millrace-agents/runs/<run-id>/
```

Common artifacts include stage results, prompt files, invocation files, completion files, stdout/stderr files where present, and stage-authored reports such as troubleshooting or Arbiter reports.

## What is Arbiter?

Arbiter is a planning-stage completion path. It does not run as normal queued work. The runtime activates it only when backlog drain and lineage readiness make a closure target eligible.

Arbiter can emit only:

- `ARBITER_COMPLETE`
- `REMEDIATION_NEEDED`
- `BLOCKED`

The runtime owns the consequences of those results.

## When should Millrace be used?

Use Millrace when the work needs:

- survival across pauses, crashes, or context loss
- durable queue state
- deterministic stage progression
- recovery routing
- persisted run artifacts and inspection surfaces
- closure-sensitive completion criteria

## When should Millrace not be used?

Avoid Millrace when the task is small, bounded, likely to finish in one session, and does not need durable governance.

See also:

- `/ai/what-is-millrace.md`
- `/ai/install.md`
- `/ai/arbiter-and-completion.md`