millracer 0.3.0

Millrace operations daemon and gateway for structured workspace control.

Millracer

Millracer is the local ops gateway for Millrace OS. It turns structured CLI, Mission Control, typed JSON ops, and operator requests into typed Millrace runtime actions with structured evidence, warnings, and recovery behavior.

Millracer is meant to be usable in four ways:

• as top-level structured CLI commands for common Millrace operations
• as a typed JSON ops boundary for software callers
• as a persistent operator you can talk to directly
• as a one-shot compatibility alias for older automation that still calls run

Requirements

Install these first:

• Python 3.11 or newer
• millrace on PATH
• pi on PATH when using compatibility direct-work or delegated-finalization harness flows
• millrace-cli on PATH only when using the optional rich harness adapter
• model/API credentials configured for the selected runner backend when a runner is used

For local development, install uv as well.

Millrace remains an external runtime dependency. Millracer calls supported Millrace CLI/control surfaces and records structured evidence about those calls; it does not vendor Millrace internals, import source from millrace-agents/, or treat local reference snapshots as install-time product dependencies.

Ecosystem Boundaries

The Millrace tools have separate jobs:

• millrace: durable staged execution runtime and CLI. It owns queue state, run state, stage traces, runtime artifacts, and terminal markers.
• millrace-cli: optional rich interactive coding/operator harness. Millracer can hand selected context to it for conversation and inspection, but structured Millracer operations still own runtime control, queue intake, completion proof, and release authority.
• millracer: local operations daemon and gateway. It owns workspace/session convenience state, typed ops requests, policy checks, adapter calls, health classification, completion evidence summaries, and release handoff inspection.
• millmux: terminal and session orchestration cockpit. Millracer may run under it, but Millracer is not the terminal UI.

ref-repos/ contains local reference snapshots used during planning. It is not packaged, imported, or required by installed Millracer. millrace-agents/ contains Millrace runtime/workspace state and stage artifacts. It is not product source for Millracer and normal Millracer operations must not mutate it directly.

Download

From GitHub:

git clone https://github.com/tim-osterhus/millracer.git
cd millracer

From inside the Millrace development workspace, the repo lives at:

cd /Users/timinator/Desktop/Millrace-Dev/dev/harness/millracer

Install

From PyPI:

pipx install millracer

Or with uv:

uv tool install millracer

For an isolated command-line install from a local checkout:

pipx install .

For editable development:

uv sync --extra dev
uv run millracer --help

You can also run without installing:

uv run --extra dev python -m millracer --help

Direct install from GitHub is:

pipx install git+https://github.com/tim-osterhus/millracer

Structured CLI

Use the top-level commands for common runtime and workspace operations:

millracer status --json --workspace /path/to/workspace
millracer health --json --workspace /path/to/workspace
millracer enqueue --kind task --workspace /path/to/workspace "Fix the failing tests"
millracer release inspect --json --target-operation commit --authority-scope release:commit

The structured commands are status, health, enqueue, pause, resume, diagnose, workspaces, sessions, and release inspect. They dispatch through the same vNext ops service as ops --json; pass --json when callers need the full OpsResult payload.

Workspace Registration

Every operation resolves a Millrace workspace before touching runtime-backed surfaces. Callers can pass --workspace <path> or send workspace_ref in an ops request. Millracer also keeps a small local state file at ~/.millracer/state.json for registered workspaces, aliases, selected workspaces, session selections, default modes, runner hints, tags, display names, warning summaries, and recent request IDs.

List and select registered workspaces with:

millracer workspaces list --json --workspace /path/to/workspace
millracer workspaces select default --session-id local --json --workspace /path/to/workspace

This state is convenience state only. Millracer does not persist queue truth, work-item lifecycle truth, traces, artifacts, approvals, or terminal outcomes as its own authority; Millrace remains the source of truth for runtime state.

Persistent Operator

Use operator for normal Millracer operation:

millracer operator --workspace /path/to/workspace

In a development checkout:

uv run --extra dev python -m millracer operator --workspace /path/to/workspace

This opens a small line prompt:

Millracer operator ready. Type /exit to quit.
millracer>

operator runs a minimal assistant shell over the structured ops service. It preserves --session-id context for workspace selection and recent request tracking, translates simple operator language into typed ops, and asks for explicit approval before authority-scoped actions such as queue intake, runtime control, or release-sensitive inspection. Prefix the next turn with approve to dispatch an approved action. Type /exit or /quit to close the shell.

Compatibility Run Alias

run remains available for tools that already call it, but it is now a compatibility alias over structured enqueue. New integrations should prefer enqueue or ops --json:

millracer run --workspace /path/to/workspace "Fix the failing tests"

In a development checkout:

uv run --extra dev python -m millracer run \
  --workspace /path/to/workspace \
  "Fix the failing tests"

The command emits a compatibility warning and records compatibility metadata in JSON output. It queues one work item through the structured ops API instead of being the primary product surface.

Ops JSON

Use ops --json when Mission Control or another software caller needs the stable Millrace OS command boundary:

millracer ops --json < request.json

The current ops request/result contract uses schema version millracer.ops.v0.3. Millracer still accepts millracer.ops.v0.2 as an explicit compatibility schema for existing callers:

{
  "schema_version": "millracer.ops.v0.3",
  "request_id": "req-001",
  "workspace_ref": {
    "root_path": "/path/to/workspace",
    "runtime_kind": "local",
    "mode": "learning_codex"
  },
  "source": {
    "kind": "mission_control",
    "surface": "command_panel"
  },
  "action": "status",
  "input": {
    "kind": "structured_action",
    "payload": {}
  },
  "requested_authority": {
    "scopes": ["status:read"],
    "reason": "Read workspace status."
  },
  "options": {}
}

Current structured read actions include status, queue_status, show_work_item, list_runs, show_run, diagnose, list_workspaces, list_sessions, inspect_session, inspect_release, and release_inspect. Release inspection reports generated-artifact ignore coverage, git state, verification evidence, missing checks, unrelated dirty paths, and explicit release authority without committing, pushing, tagging, or publishing. Structured mutation, control, and evidence-input actions include enqueue, pause, resume, select_workspace, record_health_report, and record_completion_evidence. Unsupported actions return machine-readable errors instead of falling through to arbitrary shell execution.

OpsResult includes structured warnings, errors, result, and completion fields. Runtime completion is never inferred from text alone. For scoped delegated work, callers should gate external completion on:

{
  "completion": {
    "scoped_completion": true
  }
}

For v0.3 ops requests and results, scoped work renders as work_item_ref. The v0.2 compatibility schema still accepts and renders scoped_work_item.

--stream-json is reserved for event-frame streaming and currently returns a structured unsupported_transport result.

Health And Completion Evidence

health classifies runtime evidence into these public states: healthy_running, healthy_idle, healthy_completed_scope, paused_expected, paused_unexpected, blocked_recoverable, blocked_hard, spiraling, crashed, stale_lock, and unknown.

Without an input file, health reads live runtime status through the Millrace adapter and records a health report:

millracer health --json --workspace /path/to/workspace

Software callers can also supply captured health evidence:

millracer health --stdin-json --json --workspace /path/to/workspace < health-evidence.json

Completion is evidence-backed. Millracer can summarize runtime status, queue state, run artifacts, terminal markers, scoped-work refs, git state, and verification command output, but it does not accept assistant text alone as completion proof. Scoped delegated work should be treated as complete only when the result includes completion.scoped_completion: true or equivalent structured evidence for the selected work item. A drained daemon without that evidence is incomplete for the scoped caller.

Authority And Release Handoff

Authority-sensitive operations carry explicit requested authority. Queue intake uses enqueue authority, runtime control uses runtime-control authority, and release-sensitive inspection records the release scopes the caller requested. The persistent operator shell asks for approval before dispatching authority-scoped operations.

Release inspection is read-only:

millracer release inspect \
  --json \
  --workspace /path/to/repo \
  --target-operation commit \
  --authority-scope release:commit \
  --verification-json verification-evidence.json \
  --expected-change-path README.md

The report checks generated-artifact ignore coverage, git branch/revision and dirty paths, required verification evidence, unrelated changes, and authority coverage for commit, push, tag, PyPI, and external publishing. It does not commit, push, tag, publish to PyPI, or publish elsewhere; those actions require separate explicit authority and a future operation that performs them.

Legacy JSON

For callers still using the earlier one-shot compatibility shape, pass task input as JSON on stdin:

printf '{"task":"Fix the project and run the tests","workspace":"/path/to/workspace"}' \
  | millracer run --benchmark-json --output json

The JSON input accepts task, prompt, or instructions, plus an optional workspace and optional intake_kind. The option name is still --benchmark-json for CLI compatibility. New product integrations should use millracer ops --json.

The legacy JSON path maps the request into a vNext enqueue ops request with compatibility metadata and renders an OpsResult-shaped JSON payload.

Adapters for streaming queues should pass exactly one selected item at a time using scoped_work_item:

{
  "task": "Implement the selected queue item only.",
  "workspace": "/path/to/workspace",
  "intake_kind": "probe",
  "scoped_work_item": {
    "item_id": "ITEM-123",
    "title": "Fix the selected failure",
    "source_queue": "/path/to/TASK_QUEUE.md",
    "spec_path": "/path/to/specs/ITEM-123.md",
    "completion_ref": "submit-ITEM-123",
    "constraints": ["Do not implement or submit any other queue item."]
  }
}

Millracer writes this metadata into the Millrace intake task as the scoped-work contract. The delegated agent is told not to batch independent queue items and not to create completion signals for any item other than the selected one. External callers should treat scoped_completion: true as the signal that the selected scoped item completed. A drained daemon without scoped completion evidence returns outcome: "incomplete" and must not be treated as selected item completion.

Intake Kinds

Millracer chooses intake kind for queued work:

• probe: investigation-first intake for uncertain codebase work.
• idea: planning/decomposition intake for clear outcomes that need shaping.
• task: execution intake for already-scoped local work.

Use --intake auto for compatibility run, or enqueue --kind auto for the structured CLI default. Auto selection uses deterministic policy and biases toward probe for large pre-existing codebases with uncertain affected files. Use --intake task, --intake idea, or --intake probe on run, or enqueue --kind task|idea|probe, to force the intake kind exactly.

Millracer dispatches the selected intake kind to the matching Millrace queue command:

• probe -> millrace queue add-probe
• idea -> millrace queue add-idea
• task -> millrace queue add-task

Common Options

• --route auto|direct|millrace: route preference for enqueue and compatibility requests.
• --intake auto|probe|idea|task: compatibility run intake preference. Structured enqueue uses --kind auto|probe|idea|task.
• --workspace <path>: Millrace workspace root and default command working directory.
• --cwd <path>: command working directory when it differs from the workspace.
• --millrace-mode <mode>: Millrace mode for delegated work, default default_pi.
• --thinking <level>: Pi thinking level for optional harness-backed agent flows, default high.
• --provider <name> / --model <name>: optional Pi provider/model selection.
• --skill <path>: load a Millrace operator skill package or SKILL.md.
• --no-default-skills: disable automatic skill discovery.
• --daemon-timeout-seconds <n>: maximum wait for a delegated Millrace run.
• --notify-terminal-stages / --no-notify-terminal-stages: notify the outer Pi session when meaningful terminal stages finish before full run drainage, default enabled.
• --max-daemon-restarts <n>: restart attempts after Millracer sees queued work with a stopped daemon, default 1.
• --json: full OpsResult output for structured CLI commands.
• --output json: machine-readable compatibility run output.

Skill Loading

When this repository lives in the standard Millrace development layout, Millracer automatically loads the repo-local Millrace operator skills from ../../source/millrace/docs/skills/.

Outside that layout, pass skill paths explicitly:

millracer operator \
  --skill /path/to/millrace-autonomous-delegation \
  --skill /path/to/millrace-ops-agent-manual \
  --workspace /path/to/workspace

How It Works

Millracer keeps the outer interface simple:

1. receive a typed ops request or one natural-language task
2. resolve workspace and mode
3. dispatch structured actions directly when no model interpretation is needed
4. use a runner backend for natural-language routing or direct work when needed
5. enqueue probe, idea, or task documents into Millrace when durable staged execution is useful
6. monitor runtime state and synthesize evidence-bearing results

The goal is a dedicated Millrace-equipped operator that is still easy to drive from automation. Product surfaces should use the structured CLI commands or ops --json; external compatibility callers can use run; humans and longer operator sessions can use persistent operator.

By default, Millracer uses:

• millrace as the runtime CLI
• default_pi as the Millrace mode for delegated work
• pi as the current runner backend when model-backed interpretation or finalization is needed
• high thinking for that runner
• a persistent assistant shell session for operator workflows
• Pi RPC as an optional harness adapter for compatibility direct-work and delegated-finalization flows
• millrace-cli as an optional rich harness adapter for conversation and inspection handoff only; runtime control, queue intake, completion proof, and release authority stay in structured Millracer operations

The package also exposes thin scheduler hooks for health checks, stale daemon detection, release-readiness follow-ups, and completion handoff reports. These hooks compose existing evidence services and are not a persistent scheduler or broad gateway platform.

Deferred Surfaces

MCP, HTTP, channel adapters, durable memory beyond local session convenience state, container execution, a persistent scheduler, and broad personal assistant behavior are optional future surfaces. The first stable core is the typed Millrace operations gateway: workspace resolution, policy, runtime adapter calls, health and completion evidence, release handoff inspection, and assistant-addressable structured operations.

The automatic decision turn can flag that a custom Millrace loop appears necessary. Millracer preserves that signal in JSON output and emits a text-mode warning, but it still delegates with the selected --millrace-mode. Pass a custom mode explicitly when one is available.

Workspace And Sessions

OpsRequest.workspace_ref can identify a workspace by workspace_id or root_path. Resolution prefers request fields, then CLI workspace defaults, then selected session context, registered workspace defaults, and finally the current working directory when available.

Millracer may persist local state such as registered workspace records, aliases, default mode or runner hints, workspace kind, tags, display names, selected workspace, selected mode, recent request IDs, and warning codes/summaries. It does not persist queue truth, work-item lifecycle truth, traces, artifacts, approvals, or terminal outcomes as session state. The Millrace runtime remains authoritative.

Routes

Structured enqueue and compatibility run preserve --route as a route preference for callers that already send it. The current structured CLI enqueue path creates Millrace queue items through the ops service. Use operator for assistant-language structured operations in a persistent session.

python -m millracer enqueue --route millrace --kind task "Implement the pending refactor spec"
python -m millracer run --route millrace "Implement the pending refactor spec"

Use --json for structured CLI automation and --output json for compatibility run callers.

Delegation Semantics

For compatibility agent-driven delegated work, the daemon monitor is synchronous inside one delegated task. During that task, Millracer waits for a terminal Millrace event before returning to the caller. The optional outer Pi harness session remains persistent across the decision, daemon-completion notification, and finalization turns. The operator command itself is an assistant shell over structured ops and preserves assistant session context across turns.

Millracer does not automatically retry blocked Millrace runs or fall back to direct execution. It reports those events to the final Pi turn so output reflects the real delegated run rather than hiding failures.

If Millracer sees queued work while the daemon is stopped, it classifies that as restart_needed, clears stale Millrace state when needed, and restarts the daemon up to --max-daemon-restarts. This is a lifecycle repair only; it does not change the queued task or silently switch to direct execution.

For delegated work, Millracer writes an intake document under .millracer/intake/ and passes that file to millrace queue add-probe, millrace queue add-idea, or millrace queue add-task. Millrace accepts arbitrary readable markdown paths there and copies the parsed document into its managed queue.

For dynamic queues, the caller should select one available item, load that item's instructions, and call Millracer with scoped_work_item. Do not pass a whole continuous-agent operating prompt as one broad task unless broad batching is explicitly the requested work.

Terminal-stage notifications are default-on. Updater UPDATE_COMPLETE is a progress event when other queues or closure targets remain; it is not treated as global run closure. Arbiter completion is scoped completion evidence. Full daemon idle without that evidence is a terminal idle_no_work event with an incomplete outcome.

The current finalization turn combines two jobs: notification that a daemon reached a terminal event and production of the final answer. The MonitorEvent boundary keeps the hook explicit so a later version can chain follow-up delegations before finalizing.