Skip to content

Inspecting state

board is the source of truth the web app and IDE read. It returns the project's live state as JSON and exposes the actions the panels' buttons call, so the IDE stays a thin view over the engine. verifier reads and labels the gate results that back a verdict; mcp-context exposes the same state to agents over MCP.

board

mini-ork board [<verb>] [<run_id>] [<target>] [options]

With no verb, board prints the whole project document: runs, learnings, automations, recipes, workspaces, scheduler, and an errors map for any section that failed to compute. Each section is computed independently — one broken source does not blank the board.

Verbs

Verb Arguments What it does
show [<run_id>] Whole project document, or one run
run <run_id> One run's card as markdown, plus its open workspace
runs [--query TEXT] [--limit N] Paged run list; whitespace-separated terms are ANDed
merge <run_id> Merge a finished run's workspace
discard <run_id> Discard a run's workspace
race-keep <winner> [--discard ID ...] Merge the winner and discard the runners-up
stop <run_id> Soft-stop a running run
kill <run_id> SIGTERM, then SIGKILL after two seconds
resume <run_id> Resume a cost-paused run
retry <run_id> Spawn a recovery for a failed run (see below)
gate approve\|reject <inbox_id> Resolve a review-gate row, with --note
page <key> [--tab T] [--arg k=v] One IDE page as data
node <run_id> <node_id> One node's detail (choose a --view)
steer <run_id> --role R --severity S --text T Inject a steering message into a live run
answer <run_id> --text T [--for Q ...] Answer a question the run asked
checkpoints <run_id> Per-node git checkpoints for a run
restore <run_id> <node> Restore the run's worktree to a checkpoint
start --kickoff <path> Launch a run from a kickoff file, detached
dismiss <run_id> [--undo] Hide a run from the inbox without stopping it
not-needed <run_id> [--undo] Close a run as not needed

Global options

Flag Meaning
--home <dir> Project home (default $MINI_ORK_HOME or ./.mini-ork)
--json Emit JSON (the default shape for most verbs)
--shell Project to the IDE shell's keys only: version, project, home, generated_at, header, runs, counts, errors
--view <name> Node detail view: stream, output, prompt, telemetry, learning, changes, overview, artifacts, harness
--offset N Stream view: start at this line
--limit N runs page size (default 50, max 200)
--query TEXT runs full-text filter
--force retry: bypass the retryable=false gate; race-keep: supply the operator's merge approval
--dry-run retry: return the hint only; race-keep: print the plan, change nothing
--ack-change retry: acknowledge the hint's needs_change block
--lane <alias>=<lane> retry: pin a lane for the spawned recovery (repeatable)
--undo dismiss / not-needed: reverse the close
--note TEXT gate: reason attached to the decision

start mirrors the corresponding run flags: --kickoff, --recipe, --workspace worktree|in-place, --set K=V (repeatable), --run-id <id>, --init, --dry-run.

Examples

mini-ork board --json | jq '.runs[0]'
mini-ork board runs --query "changelog" --limit 10
mini-ork board node <run-id> implement --view stream --offset 40
mini-ork board gate approve <inbox-id> --note "scope verified"
mini-ork board retry <run-id> --dry-run
mini-ork board start --kickoff ./kickoff.md --recipe code-fix

retry refuses to spawn when the failure hint says the code — not the environment — must change, unless --ack-change is passed; --force bypasses the retryable=false gate. Prefer retry over re-running from scratch: it carries the run's evidence forward.

Exit codes

0 success, 1 failure, 2 usage. A malformed verb or a missing required positional is a usage error, not a failed run.

verifier

Inspect and label gate results — the calibration ground truth for the oracle.

mini-ork verifier list [--run <run_id>] [--unannotated] [--limit N] [--json]
mini-ork verifier annotate --result-id <vr-…> --kind <false_positive|false_negative>
                           [--annotator NAME] [--notes TEXT]
Flag Meaning
--run <run_id> Restrict to one run
--unannotated Only results with no operator label
--limit N Maximum rows (default 50)
--json Emit JSON instead of a table
--result-id The vr-… id printed by list
--kind false_positive or false_negative
--annotator Who labelled it (default $USER)
--notes Free-text rationale

Annotations are how the abstain gate is calibrated. Label a PROVEN verdict that was wrong a false_positive; a REFUTED verdict on a correct change a false_negative.

version

mini-ork version
# mini-ork 0.9.0 (universal task loop runtime)

For the engine commit and the home's migrated version, use mini-ork doctor.

mcp-context

mini-ork mcp-context [--control]

Runs a stdio MCP server exposing runs, learnings, cost and the lane map to agents — for example inside Zed. By default only read-only tools are exposed. --control (or MO_MCP_CONTROL=1) additionally exposes list_recipes, start_run, run_status, wait_for_run, stop_run and certify. The server runs until stdin closes.