Skip to content

mini-ork run

The recipe runner: resolve a recipe (or classify one), then walk the lifecycle classify → plan → execute → verify, with deadline soft-gates between stages. This is the command most users call.

Usage

mini-ork run <kickoff.md>
mini-ork run <recipe-name> <kickoff.md>
mini-ork run --resume <run-id> [--checkpoint-id <step-id>]

With no recipe, the kickoff is classified against the seeded task classes and the matching recipe is resolved. With a recipe name, classification is skipped and that recipe is used.

Options

Flag Default Meaning
--set K=V — Repeatable environment override for this run. Premium feature knobs are dropped unless MO_ACCEPT_PREMIUM=1, and the run continues with the survivors
--workspace worktree\|in-place policy-dependent Where edits happen. Default: worktree when the review policy requires approval before merge, otherwise in-place. MO_WORKSPACE_MODE sets the same default
--resume <run-id> — Re-bind this invocation to an existing run and replay its checkpoints
--checkpoint-id <step-id> — Rewind the resume to an earlier checkpoint: steps up to and including step-id are treated as succeeded
--deadline <seconds> unset Wall-clock soft gate between lifecycle stages
--placement local\|remote MO_PLACEMENT Run the workflow on a remote node
--env <profile> MO_NODE_ENV Environment profile for --placement remote (required with it)
--json off After the run, emit one mini_ork_result={...} line for machine callers

--resume and --checkpoint-id may appear in either order and accept both --flag value and --flag=value.

What the phases print

[classify]  task_class=code_fix  risk=medium  confidence=0.96
[plan]      steps: 1  estimated_lines_changed: 5
[plan]      success_check: grep -A3 "## [Unreleased]" CHANGELOG.md returns ≥1 bullet
[implement] files_changed: CHANGELOG.md
[verify]    gates: 4/4 passed
[verdict]   PROVEN

Each phase is a separate process on the same run context. --json appends one stable object describing the run (id, verdict, return code, artifact paths) so a caller parses a line instead of scraping the human output.

Where artifacts land

<home>/runs/<run-id>/
  plan.json
  nodes/<node-id>/
  execute.log
  verifier-*.log
  run-verdict.json

<home> is MINI_ORK_HOME, defaulting to <cwd>/.mini-ork.

Resume semantics

Resume is checkpoint-driven, not a restart:

  • succeeded nodes are skipped and keep their persisted outputs;
  • failed, errored or never-ran nodes are re-dispatched;
  • one [mini-ork-resume] line is printed before execution, naming the skip set and the dispatch set — and nothing else is written to stdout by the resume layer;
  • --checkpoint-id moves the boundary earlier: everything recorded up to and including that step counts as succeeded;
  • an unknown run id is a hard error. There is no silent fresh-start fallback.

The skip/dispatch decision reads the (run_id, step_id) ledger; the run directory must exist even if the ledger is empty (an interrupted run may have written a plan but no checkpoints).

Exit codes and their meanings

Code Constant Meaning
0 RC_OK Run completed
2 RC_USAGE Malformed invocation, or a run-level usage error
64 RC_UNKNOWN_RUN --resume named a run that does not exist
65 RC_CORRUPT A checkpoint row exists but cannot be read
70 RC_INTERNAL Unexpected lookup or I/O failure

Note that 2 covers two different things: argparse-style usage errors and the resume layer's own usage errors. 64 is the one to branch on for "wrong id".

Examples

# Classifier picks the recipe
mini-ork run ./kickoff.md

# Force a recipe
mini-ork run code-fix ./kickoff.md

# Isolate edits in a worktree and cap the clock
mini-ork run code-fix ./kickoff.md --workspace worktree --deadline 1800

# Resume after a provider timeout
mini-ork run --resume run-1792249139-6289

# Resume from an earlier checkpoint
mini-ork run --resume run-1792249139-6289 --checkpoint-id 3

# Run on a remote node profile
mini-ork run code-fix ./kickoff.md --placement remote --env staging

# Machine-readable tail
mini-ork run ./kickoff.md --json | tail -1

Flags that are accepted only through --set

Some operator knobs are environment variables rather than CLI flags. Use --set so they apply to this run and its children:

mini-ork run ./kickoff.md --set MO_REVIEW_BEFORE_MERGE=required
mini-ork run ./kickoff.md --set MO_ACCEPT_PREMIUM=1 --set SOME_PREMIUM_FLAG=1

A blocked premium knob produces one warning and the run continues.