Metadata-Version: 2.4
Name: millracer
Version: 0.3.0
Summary: Millrace operations daemon and gateway for structured workspace control.
Project-URL: Homepage, https://github.com/tim-osterhus/millracer
Project-URL: Repository, https://github.com/tim-osterhus/millracer
Project-URL: Issues, https://github.com/tim-osterhus/millracer/issues
Author: Tim Osterhus
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# 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:

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

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

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

## Install

From PyPI:

```bash
pipx install millracer
```

Or with uv:

```bash
uv tool install millracer
```

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

```bash
pipx install .
```

For editable development:

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

You can also run without installing:

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

Direct install from GitHub is:

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

## Structured CLI

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

```bash
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:

```bash
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:

```bash
millracer operator --workspace /path/to/workspace
```

In a development checkout:

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

This opens a small line prompt:

```text
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`:

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

In a development checkout:

```bash
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:

```bash
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:

```json
{
  "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:

```json
{
  "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:

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

Software callers can also supply captured health evidence:

```bash
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:

```bash
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:

```bash
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`:

```json
{
  "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:

```bash
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.

```bash
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.
