Headless Mode

copair --headless runs a single task non-interactively: a prompt goes in, a structured JSON result comes out on stdout, and no TTY / REPL is ever started. It is the surface that automation and the benchmark harness drive.

copair --headless "fix the failing test in src/foo.ts" --model qwen-7b

The machine-readable contracts are committed as JSON Schema (draft 2020-12) and versioned independently of the package:

Both versions are currently 1. A breaking change to either shape bumps its version; consumers should pin against a specific version.

Flags

Headless mode is enabled by --headless. The task positional and the flags marked headless-only below are rejected with exit 1 if passed without --headless (they never silently no-op).

--max-tool-calls and --max-tokens must be positive integers; a non-integer or <= 0 value fails with exit 1 before the run starts.

Task resolution

The task prompt is resolved in this precedence order; the first non-empty source wins:

1. the [task] positional argument
2. -f, --file <path> (file contents)
3. stdin — read only when stdin is piped (not a TTY)

If none of the three yields a non-empty string, the run is never started: it writes an error to stderr and exits 1.

echo "summarize src/index.ts" | copair --headless --model qwen-7b
copair --headless -f task.md --model qwen-7b

Output streams

The three streams are strictly separated:

• stdout — exactly one JSON result document, newline-terminated, written once at exit. Nothing else is ever written to stdout. Parse stdout as a single JSON object.
• stderr — the model's streaming text (unless --quiet), plus operational notes, pre-result error messages, and any --verbose / --debug diagnostic logging. --quiet suppresses only the model-text stream; operational notes, logs, and error messages are still written. Nothing here ever reaches stdout.
• --events <path> — the mechanism-event JSONL stream (see Event stream). Omitted when --events is not passed; the result document's events_file is then null.

Exit codes

The exit code is binary and reflects whether a result document was produced:

A 1 is produced by (in order of where it can occur):

• an illegal flag combination (a headless-only flag without --headless, or a non-positive-integer --max-tool-calls / --max-tokens)
• --cwd pointing at a directory that cannot be entered
• no task provided
• a config load/validation error
• model / provider resolution failure (including an unknown model)

Result document (stdout)

Validated against headless-result.schema.json. Fields:

resolved_config

The post-resolution view of what the run used:

Termination reasons

termination_reason (in the result) and the final run_terminated.reason (in the event stream) draw from one enum:

Event stream

When --events <path> is set, every mechanism event is appended as one JSON line (JSONL). The file is truncated at the start of the run, and each line is flushed synchronously — so a kill -9 mid-run still leaves a valid, parseable partial stream. Validated against headless-event.schema.json.

Every event carries an envelope: v (schema version), seq (monotonic, starting at 0), and ts (ISO-8601). The event field discriminates the type:

Turn boundaries are driven by usage: each provider response opens a turn (turn_started), and the next response (or run end) closes it (turn_completed). The stream always ends with run_terminated, which is preceded by the close of any open turn.

Counting semantics

tool_call_parsed is emitted once per parse attempt. Format-validity is valid ÷ attempts, and a format-repair retry adds another attempt.

Approvals

Headless never prompts. The approval policy is decided entirely by the --auto-approve flag — the config permissions.mode does not govern headless tool decisions.

• Default (terminate-mode) — every approval request is denied. An approval_required event is emitted, the run ends, and termination_reason is approval-required. resolved_config.permissions is headless-terminate.
• --auto-approve — every request is approved (per request, including always-ask carve-outs such as web search and cross-repo access). resolved_config.permissions is headless-auto-approve.

Two interactive callbacks are also short-circuited so a run can never block:

• a context-limit decision resolves to abort (→ context-exhausted); headless never compacts.
• an interactive input request is answered with an empty string, and a note is written to stderr.

Config resolution

Config layers are deep-merged in precedence order (later wins), and the layers that contributed are reported in the result's resolved_config.config_sources.

Normal:

defaults  →  ~/.copair/config.yaml (global)  →  <cwd>/.copair/config.yaml (project)  →  -c <path>

config_sources example: ["defaults","global","project"], or ["defaults","global","project","-c:/abs/path"] when -c is also supplied.

--isolated:

defaults  →  -c <path>   (global + project are ignored)

config_sources example: ["defaults"], or ["defaults","-c:/abs/path"].

Environment-variable interpolation (e.g. ${OPENAI_API_KEY}) is applied to the merged config.

Toggling harness features (ablation)

The small-model harness features are configured under small_models (see the Configuration Reference). There are two ways to flip a toggle for a run, with different reproducibility guarantees.

Overlay (quick, not isolated). A -c file layers on top of your global + project config, so the model stays resolvable from your existing config and only the toggle changes:

# ablate-no-loop-guard.yaml
version: 1
small_models:
  enable_loop_guard: false

copair --headless -c ablate-no-loop-guard.yaml \
  --events run.jsonl --model qwen-7b "…task…"

config_sources will then include global / project — your ambient config also contributed, so this is convenient but not a clean, reproducible run.

Isolated (reproducible). --isolated ignores global + project config, so the -c file must be self-contained: it has to define the providers entry for the model — and, because the strict-unknowns guard also runs without your config, any model_overrides the alias needs.

# ablate-no-loop-guard.isolated.yaml
version: 1
default_model: qwen-7b
providers:
  ollama:
    type: openai-compatible
    base_url: http://localhost:11434/v1
    models:
      qwen-7b:
        id: qwen2.5:7b
        supports_tool_calling: false
        context_window: 131072
model_overrides:       # required when the alias isn't a built-in family
  qwen-7b:
    tier: small
    preferred_format: qwen-xml
    context_window: 131072
    max_tokens: 4096
    native_tool_calling: unreliable
small_models:
  enable_loop_guard: false   # the ablation

copair --headless --isolated -c ablate-no-loop-guard.isolated.yaml \
  --events run.jsonl --model qwen-7b "…task…"

config_sources is then ["defaults","-c:<abs path>"] — nothing ambient contributed. This is the form a reproducible benchmark run should use.

The config-driven toggles and their defaults:

resolved_config.toggles echoes back which features took effect, so a consumer can confirm a -c override actually applied.

Schema versioning

The result and event shapes each carry a version (schema_version / v), both currently 1. The committed schema artifacts are generated from the source schemas and are guarded against drift in CI. Pin against a version; a breaking change bumps it.