Commands, exit codes, compiler diagnostics, walker refusal
codes. The contracts behind them live in the repo:
spec/trajectory.schema.json (the compiled plan),
spec/brief.schema.json (the work packet), and
spec/conformance/ (walker behaviour).
Command surface
●●●marionette helpexit 0
$ marionette helpmarionette — compiled project trajectories for AI agentsUsage: marionette compile <plan.mar> [-o out.trajectory.json] Compile to trajectory JSON marionette validate <plan.mar> [--strict] Check only; print diagnostics marionette render <plan.mar|.json> [--state f] [-o out.mmd] [--lr] marionette summarize <plan.mar|.json> [--state f] [-o out.md] marionette brief <plan.mar|.json> [--state f] [--json] Work packet for the executor marionette start <plan.mar|.json> --run <id> [--store dir] [--principal id] [--role agent|human] [--principal-uri uri] marionette stop <plan.mar|.json> --run <id> [--store dir] marionette state init <plan.mar|.json> [--state f] [--force] marionette state show <plan.mar|.json> [--state f] marionette state choose <plan.mar|.json> <choice> --actor <name> --rationale <text> [--state f] marionette state advance <plan.mar|.json> --actor <name> [--rationale <text>] [--state f] marionette state rebind <plan.mar|.json> [--state f] Migrate state onto an edited planOptions: -o, --out <file> Output file ('-' for stdout; default varies by command) --state <file> State file (default: <plan>.state.json) --strict Treat warnings as errors (exit 1) --json Emit the machine-readable form (brief) --lr Render left-to-right instead of top-down --force Overwrite an existing state file on init --actor <name> Who takes the step ("agent" may not pass @human gates) --rationale <text> Why the step was taken (required for choices) --run <id> Run id (required by start/stop) --store <dir> Run store (default: <plan-dir>/.marionette) --create Start a new run; error if it already exists --principal <id> Connection principal id (default: agent) --role <role> Bound connection role: agent or human (default: agent) --principal-uri <u> Optional provenance URI for decision records
Exit codes
Code
Meaning
0
success (warnings allowed unless --strict)
1
validation errors (or warnings with --strict); refused walk operations
2
usage or I/O errors
3
plan/state drift detected — reconcile with state rebind (or state init --force)
Compiler diagnostics
Errors fail the build. Warnings pass unless --strict; zero
errors is the authoring bar, and a plan whose only diagnostics are
expected MAR014 dynamic-fact warnings is a legitimate end
state.
Code
Severity
Meaning
Usual fix
MAR001
error
parse error
fix the line the message points at
MAR002
error
duplicate phase id
rename one of the phases
MAR003
error
undefined divert/choice target
typo — take the did you mean suggestion, or define the phase
MAR004
error
undefined variable in a gate or mutation
declare it with VAR in the preamble
MAR005
error
duplicate variable declaration
remove the extra VAR
MAR006
error
dead end: phase with no choices and no divert
add an exit choice or -> END
MAR007
error
unreachable phase
link it from a real decision, or delete it
MAR008
error
undeclared cycle
if the loop is intentional, add ~loop~ to the returning choice; otherwise re-point the edge
MAR009
error
declared loop with no exit
add a counter-gated or @human sibling exit
MAR010
error
loop exit gate provably unsatisfiable
fix the gate so the counter can actually reach it
MAR011
warning
constant-false gate
the choice can never be taken — fix or remove it
MAR012
error
@human choice with no escalation path
give the choice a -> target
MAR013
warning
~loop~ on an edge that isn't part of a cycle
drop the mark, or point the edge where you meant
MAR014
warning
unverified gate (dynamic fact the compiler can't decide)
expected for real-world facts — review manually, don't churn the plan to silence it
use a listed value; typos fall back to defaults loudly
Walker refusal codes
Refusals are machine-coded so executors can react programmatically, and
a refused operation never mutates state. (The runtime protocol carries its
own error codes on the same principles — e.g. forbidden for an
agent connection at an @human checkpoint,
stale-revision for an outdated expectedRevision —
see spec/runtime-protocol.schema.json.)
Code
Meaning
completed
the plan has already reached END
unknown-node
state points at a node absent from the compiled plan
unknown-choice
no choice matches the given reference
ambiguous-choice
a label prefix matched more than one choice
gate-blocked
the choice's gate is currently false (or failed to evaluate)
once-exhausted
a once-only (*) choice was already taken
human-checkpoint
an agent tried to take an @human choice
rationale-required
the step is missing its auditable rationale
no-divert
advance called on a node without a fallthrough divert
migration-blocked
state cannot be rebound onto the edited plan (current phase gone) — needs a human