CLI Reference

The agentxchain CLI is the primary interface for governed multi-agent runs. Every command operates on the repo-local .agentxchain/ directory and respects the constitutional invariants defined by the protocol.

The CLI is the primary shipped runner, not the only possible runner. If you are building CI or hosted execution against the declared library boundary instead of shelling out to commands, use Runner Interface.

Legacy v3 local-orchestration commands such as start, kickoff, watch, claim, and release remain in the binary for compatibility. This page is intentionally scoped to the governed surface and the governed-adjacent command families that extend it: templates, planning-artifact generation, plugins, intake, multi-repo coordination, and the local operator dashboard.

The two commands people confuse

resume vs step

These are not interchangeable. They serve different purposes in the turn lifecycle.

	resume	step
Purpose	Initialize or resume a governed run and assign or re-dispatch one turn without waiting	Run one governed turn end-to-end
Creates a new turn?	Sometimes — yes when the run has no active turn	Yes, unless --resume targets an existing turn
Materializes dispatch bundle?	Yes	Yes
Runs adapter?	No — writes dispatch state and exits	Yes — dispatches, waits, validates, and records outcome
When to use	You want a turn assigned now, or you need to re-dispatch a failed retained turn without waiting for completion	You want the CLI to drive one turn through execution and staged-result handling

resume is the non-waiting path. It can initialize an idle run, resume a paused run that is not waiting on approval, assign a fresh turn when no turn is active, or re-dispatch a retained failed turn. If the pause is carrying pending_phase_transition or pending_run_completion, use agentxchain approve-transition or agentxchain approve-completion instead. If a turn is already active and you need to keep waiting on it, use agentxchain step --resume instead. step is the full lifecycle: it creates or resumes the turn, dispatches to the adapter, waits for a result, validates the staged output, and records the outcome.

Command map

Command	Phase	Description
demo	Setup	Run a complete governed lifecycle demo — no API keys or config required
benchmark	Setup	Run a governed delivery compliance proof in named workloads (baseline, stress, completion-recovery, phase-drift) and use --output <dir> to persist export-proof artifacts for verify export and verify diff
benchmark workloads	Setup	List available benchmark workloads with descriptions and expected signals
init	Setup	Scaffold a governed project with config, state, prompts, and planning docs
config	Setup	Inspect or mutate repo config, including governed project.goal recovery after scaffold
template list	Setup	Inspect the built-in governed scaffold templates (use --phase-templates for workflow-kit phase templates)
template validate	Setup	Prove template registry, project binding, workflow-kit scaffold, planning artifact completeness, and acceptance hint completion
template set	Setup	Apply a template annotation and additive guidance to an existing governed project
generate planning	Setup	Restore scaffold-owned governed planning artifacts without re-running init
phase list	Inspection	List governed phases in routing order with current-phase context
phase show	Inspection	Inspect one governed phase: routing, gate, next roles, and workflow-kit artifact ownership
gate list	Inspection	List all defined gates with phase linkage, predicate summary, and approval requirements
gate show	Inspection	Show a single gate's full contract: predicates, phase linkage, status, last failure, and optional live evaluation
role list	Inspection	List all defined roles with title, authority, and runtime
role show	Inspection	Show detailed information for a single role
turn show	Inspection	Inspect an active turn's dispatch bundle and read selected artifacts without raw file browsing
status	Inspection	Print current run state: phase, pending turn, blocked status, and recent event evidence
export	Inspection	Emit a single JSON audit artifact for the current governed run or coordinator workspace
audit	Inspection	Render the governance audit directly from live repo state
report	Inspection	Render a human-readable governance summary from a verified export artifact
restore	Migration	Restore governed continuity roots from a prior run export into another checkout of the same repo
restart	Turn lifecycle	Restart a governed run from the last checkpoint after a session boundary (terminal close, machine restart, context loss)
resume	Turn lifecycle	Initialize or resume a run and assign or re-dispatch one turn without waiting
unblock	Turn lifecycle	Resolve the current human escalation record and continue the governed run
inject	Intake	Inject a priority work item into the intake queue (composed record + triage + approve)
escalate	Turn lifecycle	Raise an operator escalation intentionally and block the run with a recovery contract
step	Turn lifecycle	Create or resume one turn, dispatch to adapter, wait for result, validate, and record the outcome
run	Turn lifecycle	Drive a governed run to completion: multi-turn execution with adapter dispatch and gate prompting
schedule	Automation	Evaluate repo-local run schedules, execute due governed runs, poll in a local daemon loop, or check daemon health
accept-turn	Turn lifecycle	Accept the staged turn result and commit it to history
checkpoint-turn	Turn lifecycle	Checkpoint the latest accepted turn into git so the next writable turn has a clean baseline
reconcile-state	Turn lifecycle	Accept safe fast-forward operator commits as the new governed baseline after checkpoint drift
reject-turn	Turn lifecycle	Reject the staged turn result with a reason; turn goes back to pending
reissue-turn	Turn lifecycle	Invalidate an active turn and reissue it against current repo state — covers baseline drift, runtime rebinding, authority changes, and operator-initiated redo
approve-transition	Approval	Approve a phase transition gate (e.g., planning to implementation)
approve-completion	Approval	Approve run completion — the final human gate before a run closes
validate	Validation	Validate config, state, or full run integrity
verify turn	Validation	Replay a staged turn's declared machine-evidence commands and compare actual exit codes
replay turn	Validation	Replay an accepted turn's declared machine-evidence commands from history
replay export	Observability	Browse a completed export in the dashboard for offline post-mortem analysis
conformance check	Conformance	Preferred front door for the shipped protocol conformance fixture suite
verify protocol	Conformance	Run the shipped protocol conformance fixture suite against a target implementation
verify export	Conformance	Verify an export artifact against embedded file bytes, hashes, and summary invariants
verify diff	Conformance	Verify two export artifacts, then fail closed on governance regressions between them
migrate	Migration	Migrate state and config from an older protocol version
migrate-intents	Migration	Archive legacy and phantom intents that block continuous mode
plugin	Plugin management	Install, list, upgrade, or remove hook plugins
intake	Continuous delivery	Record repo-native signals, triage intents, authorize and plan governed work, start execution, resolve outcomes, and inspect backlog state
multi	Multi-repo coordination	Bootstrap, inspect, step, approve, and recover coordinator runs across linked repositories
proposal	Proposal management	List, diff, apply, or reject proposed changes from api_proxy agents
history	Observability	Show cross-run history of governed runs in this project
decisions	Governance	Show repo-level decisions that persist across governed runs
diff	Observability	Compare two recorded governed runs or export artifacts and summarize what changed
events	Observability	Show repo-local run lifecycle events with optional streaming
chain latest	Observability	Show the most recent chain report from auto-chained governed runs
chain list	Observability	List all chain reports with summary metadata
chain show	Observability	Show a specific chain report by chain ID
mission start	Observability	Create a single-repo mission artifact above chained runs
mission list	Observability	List mission artifacts with aggregate run, turn, and repo-decision counts
mission show	Observability	Show the latest mission or one mission by ID, including attached chain summaries and latest plan health
mission attach-chain	Observability	Bind a chain report to a mission so long-horizon work has a durable grouping layer
mission plan	Planning	Generate a decomposition plan for a mission using LLM-assisted workstream decomposition
mission plan show	Planning	Show a decomposition plan with workstream details and dependency state
mission plan approve	Planning	Approve the latest proposed mission plan and supersede older active revisions
mission plan launch	Planning	Launch workstream(s) from an approved plan — single --workstream, batch --all-ready, or --retry failed
run --continuous	Continuous delivery	Vision-driven lights-out loop: derive work from VISION.md and execute governed runs until all goals are addressed
mission plan autopilot	Planning	Unattended wave execution of an approved plan — launches dependency waves until plan completes or failure stops execution
mission plan list	Planning	List all plans for a mission, newest first
doctor	Readiness	Check governed project readiness: config validation, runtime prerequisites, state health, schedule daemon, and workflow-kit artifacts
connector capabilities	Readiness	Show the merged capability contract for one runtime or all configured runtimes
connector check	Readiness	Run live connector probes for governed non-manual runtimes before the first turn
connector validate	Readiness	Dispatch one synthetic governed turn through a runtime and prove the staged turn-result contract before the first automated run
workflow-kit describe	Readiness	Show the workflow kit contract — templates, artifacts, semantic validators, gate coverage
serve-mcp	Integration	Start an MCP server exposing governance tools for Claude Code, Cursor, and other MCP clients
dashboard	Visualization	Launch a local web dashboard for observation plus narrow gate approvals

Turn lifecycle commands

benchmark

agentxchain benchmark [--json] [--workload <name>] [--stress] [--output <dir>]

Flag	Default	Description
--json	false	Output the benchmark result as structured JSON
--workload <name>	baseline	Run a named workload: baseline, stress, completion-recovery, or phase-drift
--stress	false	Compatibility alias for --workload stress
--output <dir>	none	Persist durable proof artifacts: metrics.json, run-export.json, verify-export.json, and workload.json

benchmark is a governance proof surface, not a performance test. It runs a temp governed project, drives a full lifecycle, and fails closed if admission control, gates, or export verification fail. Use --output <dir> when you want durable artifacts that can be re-verified or diffed later instead of losing the proof when the temp project is cleaned up.

Those saved benchmark bundles are repo-local run exports today, not coordinator exports. These examples are proving workload and phase-regression behavior, not quietly exercising coordinator repo-status logic.

Built-in workloads:

Workload	What it proves
baseline	Clean one-turn-per-phase lifecycle with no recovery branch
stress	Rejected implementation turn, governed retry, and successful recovery
completion-recovery	Failed final completion gate on a missing required artifact, followed by a repair turn and successful completion
phase-drift	4-phase workflow (planning → design → implementation → qa) producing a different workflow_phase_order; diffing against baseline proves REG-PHASE-ORDER regression detection

Use agentxchain benchmark workloads (or --json) to list all available workloads with descriptions, expected signals, and their phase topology.

Typical use:

# save a baseline proof bundle
agentxchain benchmark --workload baseline --output ./artifacts/benchmark-baseline
agentxchain verify export --input ./artifacts/benchmark-baseline/run-export.json

# compare the happy path against the rejected-turn workload
agentxchain benchmark --workload stress --output ./artifacts/benchmark-stress
agentxchain verify diff \
  ./artifacts/benchmark-baseline/run-export.json \
  ./artifacts/benchmark-stress/run-export.json

# prove final-phase gate recovery on a missing ship-verdict artifact
agentxchain benchmark --workload completion-recovery --output ./artifacts/benchmark-completion-recovery
agentxchain verify diff \
  ./artifacts/benchmark-baseline/run-export.json \
  ./artifacts/benchmark-completion-recovery/run-export.json

# prove phase-order drift detection (4-phase vs 3-phase)
agentxchain benchmark --workload phase-drift --output ./artifacts/benchmark-phase-drift
agentxchain verify diff \
  ./artifacts/benchmark-baseline/run-export.json \
  ./artifacts/benchmark-phase-drift/run-export.json
# → exits 1 with REG-PHASE-ORDER-001 regression (expected)

If you later run verify diff on coordinator exports outside the benchmark flow, keep the same truth boundary explicit: summary.repo_run_statuses remains raw coordinator snapshot metadata, while coordinator repo-status changes and regressions come from authority-first child repo status when nested child exports are readable.

mission

agentxchain mission start --title <text> --goal <text> [--id <mission_id>] [--plan] [--constraint <text>]... [--role-hint <role>]... [--planner-output-file <path>] [--json] [--dir <path>]
agentxchain mission list [--limit <n>] [--json] [--dir <path>]
agentxchain mission show [mission_id] [--json] [--dir <path>]
agentxchain mission attach-chain [chain_id|latest] [--mission <mission_id>] [--json] [--dir <path>]

mission is the single-repo hierarchy layer above chained runs. It exists because AgentXchain already uses initiative for multi-repo coordination. Reusing initiative inside one repo would create split-brain operator language, so the single-repo noun is mission.

Use it when one repo needs a durable long-horizon grouping across multiple chain sessions:

# Create a mission
agentxchain mission start \
  --title "Release hardening" \
  --goal "Eliminate version-surface drift across release tooling"

# Or create the mission plus the first proposed plan in one pass
agentxchain mission start \
  --title "Release hardening" \
  --goal "Eliminate version-surface drift across release tooling" \
  --plan \
  --constraint "Keep release automation idempotent" \
  --role-hint dev \
  --role-hint qa

# Auto-bind chained runs to the mission (preferred)
agentxchain run --chain --mission latest --auto-approve

# Or bind to a specific mission by ID
agentxchain run --chain --mission mission-release-hardening --auto-approve

# Manual attach (fallback for runs not mission-bound at start)
agentxchain run --chain --max-chains 2
agentxchain mission attach-chain latest

# Inspect mission state
agentxchain mission show

The --mission flag on run --chain is the primary operator flow. It auto-attaches the chain report to the specified mission after completion, eliminating the manual mission attach-chain step. Use --mission latest to always bind to the most recent mission, or pass an explicit mission ID. Set run_loop.chain.mission in agentxchain.json for config-driven auto-binding.

mission start --plan is a convenience layer over the shipped planner path, not a governance bypass. It creates the mission first, then writes exactly one proposed plan artifact. mission start --plan --json emits { mission, plan }; the mission-only JSON shape remains unchanged when --plan is absent.

Mission summaries derive aggregate chain count, total runs, total turns, latest chain terminal reason, and active repo-decision count. When a decomposition plan exists, the same summary also includes the latest plan status, completion percentage, and workstream counts so one command can answer basic mission-health questions. That repo-decision field still matters: decisions already carry across chained runs, and the mission surface keeps that continuity visible instead of pretending each chain starts from zero.

mission attach-chain remains available for binding chains from runs that were not mission-bound at start. It defaults to attaching the latest chain report to the latest mission.

For the full operator model, see Missions. That page keeps the repo-local Mission hierarchy explicitly separate from coordinator Initiative, documents the derived mission-status contract, and makes run --chain --mission ... the primary flow instead of the manual repair path.

mission plan

agentxchain mission plan [mission_id|latest] [--constraint <text>]... [--role-hint <role>]... [--planner-output-file <path>] [--json] [--dir <path>]
agentxchain mission plan show [plan_id|latest] [--mission <mission_id>] [--json] [--dir <path>]
agentxchain mission plan approve [plan_id|latest] [--mission <mission_id>] [--dir <path>]
agentxchain mission plan launch [plan_id|latest] --workstream <id> [--mission <mission_id>] [--auto-approve] [--json] [--dir <path>]
agentxchain mission plan launch [plan_id|latest] --workstream <id> --retry [--mission <mission_id>] [--auto-approve] [--json] [--dir <path>]
agentxchain mission plan launch [plan_id|latest] --all-ready [--mission <mission_id>] [--auto-approve] [--json] [--dir <path>]
agentxchain mission plan autopilot [plan_id|latest] [--mission <mission_id>] [--max-waves <n>] [--continue-on-failure] [--cooldown <seconds>] [--auto-approve] [--json] [--dir <path>]
agentxchain mission plan list [--mission <mission_id>] [--limit <n>] [--json] [--dir <path>]

mission plan is the decomposition layer above mission grouping. It turns a mission goal into an operator-reviewed set of workstreams — dependency-ordered delivery slices with roles, phases, and acceptance checks.

Plans are advisory artifacts under .agentxchain/missions/plans/<mission_id>/. They do not modify governed run state or allocate chain IDs before execution. A plan must be explicitly approved before any workstream can launch.

# Generate a decomposition plan for the latest mission
agentxchain mission plan latest --constraint "No protocol changes" --role-hint dev --role-hint qa

# Or supply deterministic/offline planner JSON
agentxchain mission plan latest --planner-output-file ./planner-output.json

# Show the latest plan for the latest mission
agentxchain mission plan show latest

# Approve the latest proposed plan before any workstream launch
agentxchain mission plan approve latest

# Launch and execute a single ready workstream from the approved plan
agentxchain mission plan launch latest --workstream ws-alignment --auto-approve

# Retry a failed workstream (only works for needs_attention status)
agentxchain mission plan launch latest --workstream ws-alignment --retry --auto-approve

# Launch all ready workstreams sequentially (stops on first failure)
agentxchain mission plan launch latest --all-ready --auto-approve

# Unattended execution: autopilot launches dependency waves until plan completes
agentxchain mission plan autopilot latest --auto-approve

# Autopilot with safety limits and failure tolerance
agentxchain mission plan autopilot latest --max-waves 5 --continue-on-failure --cooldown 10

# List all plans for a specific mission
agentxchain mission plan list --mission mission-release-hardening

The planner uses LLM-assisted one-shot generation with strict schema validation. Configure mission_planner or api_proxy in agentxchain.json with base_url and model, or pass --planner-output-file <path> with the same JSON shape the planner would have returned. Malformed planner output fails validation closed — no partially-valid plan artifacts are created.

Plan revision works by supersession: generating a new plan sets supersedes_plan_id to the prior plan. Earlier plans remain durable for auditability. The system never mutates an existing plan artifact.

Approval is latest-only and fail-closed. mission plan approve may approve only the newest proposed plan for a mission. Approving a newer plan supersedes any older active proposed or approved plan artifacts so one approved revision remains current.

Launch supports three modes: single workstream (--workstream <id>), targeted retry (--workstream <id> --retry), and batch (--all-ready). They validate that the plan is approved and that target workstreams have satisfied dependencies. Each launch records a preallocated workstream_id → chain_id launch record and executes through the existing governed run/chaining path. Dependency satisfaction is based on the depended-on chain's latest run status, not only the chain-loop terminal label. --auto-approve passes through to the governed run surface. Successful execution marks the workstream completed and attaches the emitted chain report to the parent mission; failed execution marks the workstream needs_attention and leaves dependent workstreams blocked.

--all-ready launches all currently ready workstreams sequentially. If any workstream fails, remaining workstreams are skipped (fail-closed). Blocked workstreams are never launched — only the set that was ready at invocation time is included. The --workstream and --all-ready flags are mutually exclusive.

--retry re-launches a workstream that has needs_attention status (i.e., a previously failed launch). For single-repo missions, retry creates a new launch record with a new chain ID while preserving the old launch record for audit and returns the plan status from needs_attention to approved. For coordinator-bound missions, retry reissues the failed repo-local turn, appends a new repo_dispatches[] entry (with is_retry / retry_of) to the same coordinator launch record, and marks the original failed dispatch with retried_at / retry_reason — no new launch record or chain ID is created. Coordinator retry is deliberately narrow: one retryable repo failure at a time, fail-closed when a dependent workstream has dispatched since the failure. If the repo-local retry succeeds but immediate coordinator acceptance_projection still cannot be recorded, JSON output includes warnings[], the warning code coordinator_acceptance_projection_incomplete, and reconciliation_required: true; the command still succeeds because the child repo already ran, but the coordinator view needs a follow-up sync. That warning is also persisted as a coordinator_retry_projection_warning event so operators can inspect it later with agentxchain events. --retry requires --workstream and is mutually exclusive with --all-ready. When all workstreams reach completed, the plan auto-transitions to completed.

mission plan autopilot loops through dependency waves until the plan completes, the wave limit is reached, or execution stops. With --continue-on-failure, autopilot keeps launching any remaining ready workstreams, then exits with plan_incomplete once launchable work is exhausted but failed workstreams still need attention.

Plan auto-completion: When all workstreams in a plan reach completed status, the plan automatically transitions to completed. This happens as part of outcome recording — no separate command is needed.

init

agentxchain init --governed [--dir <path>] [--template <id>] [--dev-command <parts...>] [--dev-prompt-transport <mode>] [options]

Flag	Default	Description
--governed	false	Create the governed scaffold with protocol-owned state and prompts
--dir <path>	derived folder	Target directory for the scaffold. Use --dir . for in-place bootstrap inside an existing repo
--template <id>	generic	Governed scaffold template: generic, api-service, cli-tool, library, web-app, full-local-cli, enterprise-app
--dev-command <parts...>	claude --print --dangerously-skip-permissions --bare	Override the scaffolded local-dev.command array for the authoritative dev runtime
--dev-prompt-transport <mode>	stdin	Prompt delivery for the scaffolded local-dev runtime: argv, stdin, or dispatch_bundle_only
--goal <text>	none	Project goal — persisted in project.goal, rendered in every dispatch bundle CONTEXT.md, and surfaced in status, report, and export
-y, --yes	false	Accept all defaults without prompting
--schema-version <version>	governed default	Force a specific schema path when needed

Creates agentxchain.json, .agentxchain/state.json, role prompts, and planning document stubs. In governed mode, the scaffold also includes the decision ledger, dispatch directories, and gate configuration. Non-generic templates add project-type-specific planning artifacts and prompt guidance. The default local-dev runtime is a real local CLI contract, not a placeholder: ["claude", "--print", "--dangerously-skip-permissions", "--bare"] with prompt_transport: "stdin". This is intentional because unattended governed implementation turns need write access and non-interactive auth behavior; plain claude --print can stop at a permission prompt or macOS keychain auth read and never stage a result.

--dir makes the target path explicit instead of relying on the default nested folder. Use --dir . -y when you are bootstrapping an existing repo in place. When you plan to cd into a named directory later, declare it up front with --dir <path> so the path contract stays visible in the command itself.

If you override the dev runtime at scaffold time:

• argv mode requires {prompt} to appear in --dev-command
• stdin and dispatch_bundle_only must not include {prompt}
• a custom --dev-command without either {prompt} or an explicit --dev-prompt-transport is rejected before files are written

Examples:

agentxchain init --governed -y
agentxchain init --governed --dir . -y
agentxchain init --governed --dir my-agentxchain-project -y
agentxchain init --governed --dev-command my-agent run {prompt} -y
agentxchain init --governed --dev-command ./scripts/dev-agent.sh --dev-prompt-transport dispatch_bundle_only -y

See Templates for the full scaffold contract instead of guessing from command help.

If you skipped --goal during scaffold, recover with:

agentxchain config --set project.goal "Build a governed CLI that lints decision logs"

Do not re-run init --governed in place just to add goal context.

config

agentxchain config [--json]
agentxchain config --get <key> [--json]
agentxchain config --set <key> <value...>

Version-aware config editing for both legacy and governed repos. On governed repos, the main operator use is fixing scaffold omissions without hand-editing JSON. The most common example is adding project.goal after the repo already exists:

agentxchain config --set project.goal "Ship a governed web app MVP"

When you need to inspect one value instead of dumping the whole file, use --get:

agentxchain config --get project.goal
agentxchain config --get roles.qa --json

Simple budget repairs use the same path:

agentxchain config --set budget.per_run_max_usd 75

Switch the budget enforcement policy between hard-stop and advisory modes:

agentxchain config --set budget.on_exceed warn
agentxchain config --set budget.on_exceed pause_and_escalate

pause_and_escalate (default) blocks the run when budget is exhausted. warn lets the run continue past budget with observable warnings in status, events, and notifications — useful for lights-out or daemon-scheduled runs where blocking requires human intervention.

Override or add per-model cost rates for budget tracking:

agentxchain config --set budget.cost_rates.deepseek-v3.input_per_1m 0.27
agentxchain config --set budget.cost_rates.deepseek-v3.output_per_1m 1.10

Nested keys use dot paths. Values are parsed as strings by default, with true, false, and numeric literals converted before validation. The command validates the edited config before writing it back, so invalid governed mutations fail closed instead of leaving agentxchain.json in a broken state.

config --get <key> uses the same dot-path traversal. Plain output is script-friendly: scalar values print directly, while object paths print pretty JSON. Add --json when you need JSON output even for scalar values.

Legacy --add-agent and --remove-agent mutations remain available only on v3 repos. Governed repos use roles, runtimes, and other structured fields instead.

template list

agentxchain template list [--json]
agentxchain template list --phase-templates [--json]

Prints the built-in governed templates with their descriptions, planning artifacts, prompt override roles, scaffold blueprint roles when present, and acceptance hints. Use this before template set when you want the exact built-in surface.

Use --phase-templates to list workflow-kit phase templates instead — the reusable artifact bundles you reference via workflow_kit.phases.<phase>.template in agentxchain.json. The output shows each template's ID, description, artifacts, semantics, and required sections.

template validate

agentxchain template validate [--json]

Runs explicit proof for the template and workflow kit layer. It validates the built-in manifest registry, the repo's configured template binding, the governed workflow kit scaffold, planning artifact completeness against the template's required artifact set, and acceptance hint completion in acceptance-matrix.md.

The workflow kit proof is deliberate, not cosmetic. It checks that the scaffold-owned planning files still exist and still expose the minimum structural markers the operator surface depends on:

• .planning/PM_SIGNOFF.md includes Approved:
• .planning/ROADMAP.md includes ## Phases
• .planning/SYSTEM_SPEC.md includes ## Purpose
• .planning/SYSTEM_SPEC.md includes ## Interface
• .planning/SYSTEM_SPEC.md includes ## Acceptance Tests
• .planning/acceptance-matrix.md includes the | Req # | table header
• .planning/ship-verdict.md includes ## Verdict:

That proof is about scaffold integrity, not gate readiness. Governed phase/completion gates additionally require the workflow files to carry truthful operator state: .planning/PM_SIGNOFF.md must say Approved: YES, .planning/SYSTEM_SPEC.md must preserve the baseline spec sections, .planning/acceptance-matrix.md must contain real requirement rows whose final Status values are all passing, and .planning/ship-verdict.md must carry an affirmative ## Verdict: value before the run can transition or complete.

In JSON mode, that proof is exposed under the workflow_kit key so automation can distinguish core scaffold failures from template-specific planning-artifact failures and acceptance-hint warnings.

A missing template field is treated as implicit generic; an unknown configured template fails validation. Missing workflow-kit files, missing workflow-kit markers, and missing planning artifacts are errors. Unchecked acceptance hints are warnings — QA-layer signal, not hard gates.

template set

agentxchain template set <id> [--yes] [--dry-run]

Annotates an existing governed project with a template. This command is additive by design: it updates the config template field, creates missing planning artifacts, appends prompt guidance once, appends template guidance to acceptance-matrix.md once, and records the change in .agentxchain/decision-ledger.jsonl. It does not overwrite operator-authored planning docs or replace existing template-guidance blocks.

Blueprint-backed templates are the explicit exception. template set enterprise-app and template set full-local-cli fail closed because rewriting runtime/team topology inside an existing repo is not an additive mutation. Use init --governed --template enterprise-app or init --governed --template full-local-cli for new repos instead. See Templates for the full mutation semantics.

generate planning

agentxchain generate planning [--dry-run] [--force] [--json]

Restores scaffold-owned .planning/ files for governed repos from the current template binding plus explicit workflow_kit config. Use it when baseline planning docs were deleted, a template artifact is missing, or a custom workflow-kit file such as ARCHITECTURE.md needs to be re-materialized from scaffold rules.

Default behavior is conservative:

• missing scaffold-owned planning files are created
• existing files are preserved byte-for-byte
• --dry-run previews the mutation set without writing files
• --force overwrites scaffold-owned planning files with fresh scaffold content
• --json emits machine-readable created, overwritten, and skipped_existing arrays

generate planning is not a substitute for template set. It restores scaffold-owned files only; it does not append prompt overrides or re-apply template guidance blocks to files that already exist.

role list

agentxchain role list [--json]

Lists all governed roles with their title, write authority, and runtime. Use --json for machine-readable output with all role fields (id, title, mandate, write_authority, runtime).

role show

agentxchain role show <role_id> [--json]

Shows detailed information for a single role: title, mandate, write authority, and runtime. Exits 1 with available role IDs if the requested role does not exist.

role show also exposes the bound runtime capability contract so operators can inspect:

• transport
• file-write mode
• review/manual behavior
• proposal support
• local-binary requirement
• workflow-kit owned_by suitability

--json returns both the base runtime_contract and the role-bound effective_runtime_contract.

turn show

agentxchain turn show [turn_id] [--artifact <name>] [--json]

Inspects the active governed turn and its dispatch bundle under .agentxchain/dispatch/turns/<turn_id>/. If exactly one active turn exists, you can omit turn_id. If multiple active turns exist, pass the turn_id explicitly so the operator target is unambiguous.

Without --artifact, the command prints turn metadata plus the dispatch paths for ASSIGNMENT.json, PROMPT.md, CONTEXT.md, and MANIFEST.json. This is the first-party inspection path for the live turn contract; operators should not have to browse raw repo paths just to answer "what was this turn told?" or "where is the staged result supposed to go?"

When the active turn has timing metadata, the summary also shows when the turn started and how long it has been running so operators can spot stuck or slow turns without opening raw state files.

Use --artifact to print one artifact directly:

• assignment — machine-readable turn envelope
• prompt — generated PROMPT.md
• context — generated CONTEXT.md
• manifest — dispatch bundle manifest with file hashes and sizes

Allowed artifact ids are assignment, prompt, context, or manifest.

Examples:

agentxchain turn show
agentxchain turn show turn_1234abcd --artifact prompt
agentxchain turn show --artifact assignment --json

--json returns structured turn metadata by default, including started_at and live elapsed_ms when available. When combined with --artifact assignment or --artifact manifest, it returns the parsed JSON artifact content instead of raw filesystem output.

phase list / phase show

agentxchain phase list [--json]
agentxchain phase show [phase] [--json]

These commands expose the governed workflow contract directly instead of forcing operators to reverse-engineer routing and workflow_kit through raw config dumps.

phase list prints phases in routing order and marks the current phase when governed state is available. Each row summarizes the entry role, exit gate, next phase, and workflow artifact count.

phase show prints one phase in detail:

• entry role
• exit gate and current gate status when available
• next phase
• allowed next roles
• per-phase timeout override and max concurrent turns when configured
• workflow-kit source (default, explicit, or not_declared)
• explicit workflow-kit template id when declared
• workflow artifacts with owner, ownership resolution, enforcement status, required/optional status, semantics, and filesystem presence

Ownership enforcement boundary: Only explicit owned_by fields are enforced at gate evaluation. When ownership is inferred from entry_role, phase show labels it as a display-only hint (ownership_enforced: false in JSON, "(hint, not enforced)" in text). This prevents operators from assuming inferred ownership will block phase advancement when it will not.

If phase is omitted, phase show defaults to the current governed phase from state. If no current phase is available, it falls back to the first routing phase.

This matters because the normalized default workflow-kit is real product behavior even when raw workflow_kit is absent. Operators should be able to inspect that default workflow contract explicitly instead of guessing from scaffold files.

gate list / gate show

agentxchain gate list [--json]
agentxchain gate show <gate_id> [--json] [--evaluate]

These commands expose the governed gate contract — the predicate definitions, phase linkage, approval requirements, and runtime status — without forcing operators to spelunk through raw config.gates JSON.

gate list prints all defined gates with their linked phase, effective artifact count, verification requirement, human-approval flag, and current status when available.

gate show <gate_id> prints a single gate in detail:

• linked phase (which routing phase references this gate as its exit_gate)
• human-approval requirement
• verification-pass requirement
• current status (pending, passed, failed, or none)
• effective artifacts list
• workflow-kit additive artifacts merged into the gate contract when the linked phase declares them
• last gate failure details when available (type, phase, timestamp, reasons, missing files)

The --evaluate flag adds live runtime gate semantics: it checks the merged artifact contract the runtime actually enforces, including workflow-kit additive artifacts, path-based semantic validators, artifact ownership participation in the linked phase, and requires_verification_pass against the latest accepted turn in that phase. This is a read-only snapshot, not a gate transition attempt.

When a human-approval gate is pending for the current phase and no pending_phase_transition object is prepared, gate show prints a Recovery hint pointing at agentxchain unblock <hesc_id> for open escalations and agentxchain approve-transition for post-resolution approval. This mirrors the diagnostic emitted by approve-transition itself and keeps the two surfaces consistent.

# List all gates
agentxchain gate list

# Inspect a specific gate
agentxchain gate show planning_signoff

# Live-evaluate gate readiness
agentxchain gate show planning_signoff --evaluate --json

status

agentxchain status [options]

Flag	Default	Description
-j, --json	false	Output structured JSON instead of human-readable text

Prints the current run state: active phase, pending turn (if any), blocked status, and recent lifecycle evidence. Governed status also surfaces the selected template in both modes: human-readable status prints Template: <id>, while status --json exposes a top-level template field plus config.template. When project.goal is set, human-readable status prints Goal: <text> under the project name and status --json exposes a top-level additive project_goal field.

Governed status also surfaces repo-decision carryover for the current governed repo:

• human-readable status prints compact Repo decisions and Carryover summary lines when durable .agentxchain/repo-decisions.jsonl history exists
• status --json keeps raw additive repo_decisions and adds top-level additive repo_decision_summary
• the summary is reconstructed from durable repo-decision history, so overridden-only history remains visible instead of disappearing when no active carryover constraints remain

When cross-session continuity artifacts exist, governed status also exposes a Continuity section:

• checkpoint session id, reason, time, last turn, and last role from .agentxchain/session.json
• a stale-checkpoint warning when session.json and state.json disagree on run_id
• the exact next continuity command under additive continuity.recommended_command
  • agentxchain approve-transition when a phase gate is pending
  • agentxchain approve-completion when run completion is pending
  • agentxchain restart only when restart is the truthful next continuity action
• checkpoint drift state from baseline_ref under additive continuity.drift_detected and continuity.drift_warnings
• the .agentxchain/SESSION_RECOVERY.md path when a recovery report already exists

status --json mirrors that data under a top-level additive continuity object. Does not modify state.

Governed status now also exposes additive connector/runtime diagnostics for non-manual runtimes:

• human-readable status prints a Connectors: section with runtime id, connector type, configured target, derived state, active turn ids, and last observed error or success
• status --json exposes the same data under top-level additive connector_health.connectors[]
• this is not a live ping surface; reachability is derived from accepted turns plus staged retry/error artifacts, so reachable is evidence-backed (yes, no, or unknown) instead of guessed

Governed status also shows current-phase workflow-kit artifact ownership when workflow_kit.phases is configured:

• human-readable status prints an Artifacts: section showing each artifact's path, owner role, ownership resolution (explicit vs entry_role), required/optional status, and exists/missing indicator
• status --json exposes the same data under top-level additive workflow_kit_artifacts with phase, artifacts[] (each with path, owned_by, owner_resolution, required, semantics, exists)

Governed status now also exposes additive recent-event evidence from repo-local .agentxchain/events.jsonl:

• human-readable status prints a Recent events: summary line plus the latest event summary and timestamp
• status --json exposes the same digest under top-level additive recent_event_summary
• this is intentionally a digest, not an inline event stream; use agentxchain events when you need the full lifecycle log

export

agentxchain export [--format json] [--output <path>]

Flag	Default	Description
--format <format>	json	Export format. Only json is supported in this slice
--output <path>	stdout	Write the export artifact to a file instead of stdout

Exports the repo-native audit surface into one JSON artifact. When run from a governed project (agentxchain.json), the export includes config, governed state, history, decision ledger, dispatch bundles, staging artifacts, hook audit surfaces, and intake artifacts when present. When run from a coordinator workspace (agentxchain-multi.json), the export includes coordinator state, barriers, history, decision ledger, and recursively embeds the full governed export of each child repo under the repos key. If a child repo export fails, the coordinator export still succeeds with the failure recorded per-repo. Governed projects take detection priority over coordinator workspaces. Without --output, the JSON is printed to stdout by default.

Each exported file entry includes parsed data plus content_base64, the original raw file bytes encoded for transport. That is what lets agentxchain verify export recompute bytes and sha256 instead of trusting the artifact's own summary blindly.

Run exports also include workspace.git portability metadata: source HEAD, dirty paths, and whether the export is safe to restore into another checkout of the same repo. That restore path is intentionally narrow. If the source workspace had dirty product files outside the exported governed roots, the artifact is still valid for audit/reporting but restore will refuse to treat it as a portable continuity bundle.

Partial coordinator artifacts are intentional, not broken. When repos.<repoId>.ok === false, downstream audit / report surfaces keep the failed repo row plus error and preserve repo_ok_count / repo_error_count export-health visibility, but they do not invent turn, decision, gate, hook, or recovery drill-down for the missing child export.

For the actual JSON field contract, use Export Schema Reference instead of reverse-engineering export.js.

audit

agentxchain audit [--format text|json|markdown|html]

Flag	Default	Description
--format <format>	text	Output format: text, json, markdown, or html

audit is the fast path for the repo you are standing in right now. It reads live repo state, builds the same governed or coordinator export artifact that agentxchain export would build, verifies that freshly built artifact, and immediately renders the same governance report contract that agentxchain report uses. audit does not accept --input; it is the live-state inspection path, not the offline artifact reader. The output includes a Cost Summary section with per-run totals, per-role cost breakdown, per-phase cost breakdown, and token counts when cost data is available. It also carries the same recent-event digests that report does: governed runs expose recent_event_summary, while coordinator workspaces expose separate coordinator and child-repo recent-event summaries. Coordinator report/audit status breakdowns also stay authority-first: subject.run.repo_status_counts comes from child repo authority when readable, subject.run.repo_status_drifts exposes coordinator-vs-repo disagreements, and linkage labels like linked / initialized stay metadata rather than primary repo truth. When a completed coordinator audit still shows child repo drift, audit keeps that drift visible, exposes subject.run.terminal_observability_note, and does not invent Next Actions for a terminal coordinator.

That same rule applies when the freshly built coordinator artifact is partial. audit keeps repo_ok_count / repo_error_count export-health totals plus the failed repo row and error visible, but it does not fabricate child turn timelines, decisions, gate outcomes, hook activity, or recovery details for a repo whose nested export failed.

That boundary matters:

• audit is for live local inspection of the current repo/workspace
• report is for a previously created export artifact passed via --input <path> or stdin

Do not blur those two commands. If you need a portable artifact for handoff, restore, or offline review, use export and keep the artifact. If you need an immediate governance audit for the current repo, use audit. If you already have an artifact and want the derived summary, report verifies that existing artifact first and fails closed on invalid input.

For the stable output contract, use Governance Audit Reference. report remains the export-artifact path, documented at Governance Report Reference.

report

agentxchain report [--input <path>|-] [--format text|json|markdown|html]

Flag	Default	Description
--input <path>	-	Read the export artifact from a file, or pass - to read from stdin
--format <format>	text	Output format: text, json, markdown, or html

report turns a verified export artifact into a concise governance summary for operators, reviewers, and release surfaces. It verifies the export artifact first and fails closed on invalid artifacts instead of pretending an untrusted JSON blob is audit evidence. Governed run reports summarize project identity, run status, phase, blocked state, turn counts, budget, evidence counts, and recent lifecycle evidence from exported .agentxchain/events.jsonl as subject.run.recent_event_summary. When a governed project has project.goal, text/markdown report output renders Goal: <text> in the header and --format json exposes the same value at subject.project.goal. Reports include a Governance Events section when the decision ledger contains operational governance events — policy escalations, conflict detections/rejections/resolutions, operator escalations, and escalation resolutions. These events are extracted from decision-ledger.jsonl, sorted chronologically, and rendered in all three formats with type-specific detail (violation rules, conflicting files, resolution methods). Coordinator reports summarize workspace identity, repo/workstream/barrier counts, authority-first repo status breakdown, per-repo export health, coordinator-level governance events from .agentxchain/multirepo/decision-ledger.jsonl, and separate recent-event digests for coordinator history vs aggregated child repo activity. They also expose subject.run.repo_status_drifts so coordinator-vs-repo status disagreement stays explicit instead of being buried inside stale summary labels. When a completed coordinator export still shows child repo drift, report keeps that drift visible and exposes subject.run.terminal_observability_note instead of inventing recovery commands for a terminal coordinator.

Partial coordinator artifacts stay readable here too. report keeps repo_ok_count / repo_error_count export-health totals plus the failed repo row and error visible, and in text, markdown, and html it still renders the successful child repo drill-down sections that actually exist. What it does not do is invent child drill-down for the failed repo when no nested export was captured.

Use --format markdown when you want a paste-ready summary for a PR, release, or ticket. Use --format json when another tool wants the derived report surface instead of the raw export artifact. Use --format html when you need a portable, self-contained report for compliance stakeholders — it includes inline CSS with dark mode and print styles.

If you want the same report contract from live repo state instead of an existing export file, use agentxchain audit.

For the stable report output contract, use Governance Report Reference. For the raw artifact schema, use Export Schema Reference.

restore

agentxchain restore --input <path>

Flag	Default	Description
--input <path>	required	Path to a prior run export artifact

Restores governed continuity roots from a prior run export into another checkout of the same repo at the same git HEAD. This is the first cross-machine continuity slice: export state on machine A, restore it on machine B, then continue the same run_id with agentxchain resume.

Even though agentxchain export supports both governed run exports and coordinator workspace exports, restore accepts only the governed run export branch. Coordinator exports remain valid for report, audit, verify export, verify diff, and replay export, but they are not restore inputs in this slice.

The command fails closed unless all of these are true:

• the input artifact verifies successfully
• the artifact is a run export, not a coordinator export
• workspace.git.restore_supported is true
• the target checkout is a governed project rooted by agentxchain.json
• the target repo is git-backed and clean before restore
• the target HEAD matches the exported workspace.git.head_sha
• the target project.id matches the export's project.id

restore is deliberately not a general sync engine. It does not migrate arbitrary product source files. If the source export depends on dirty files outside the governed continuity roots (agentxchain.json, .agentxchain/**, .planning/**, TALK.md), restore will tell you exactly which paths made the bundle unsafe.

restart

agentxchain restart [--role <role>]

Flag	Default	Description
--role <role>	routing default	Override the next role assignment

Restarts a governed run from the last automatic checkpoint after a session boundary: terminal close, machine restart, agent context window exhaustion, or any situation where in-memory session state was lost.

Unlike resume (which assumes the caller already has session context), restart assumes no session context and reconstructs everything from durable state on disk (.agentxchain/state.json and .agentxchain/session.json).

The runtime automatically writes checkpoint markers at six governance boundaries: turn assignment, turn acceptance, phase approval, run completion, blocked state, and restart reconnect. When restart runs, it:

1. Reads the last checkpoint and current state
2. Validates the run is resumable (not completed, failed, or blocked)
3. Checks for pending gates — if a phase transition or run completion is pending approval, restart surfaces the approval command (approve-transition or approve-completion) and does not reactivate the run or assign a new turn. This prevents restart from bypassing governance approval gates.
4. Detects repo drift — compares the checkpoint's baseline_ref (git HEAD, branch, workspace dirty status) against the current workspace. If the repo has changed since the last checkpoint, restart warns about the drift in both console output and the recovery report.
5. Reactivates the run if paused (and no pending gates exist)
6. Assigns the next turn from routing (or reconnects to an abandoned active turn)
7. Writes .agentxchain/SESSION_RECOVERY.md — a briefing document for the new session with run identity, checkpoint state, recent decisions, repo-drift warnings, pending gates, and turn history

This is the cross-session continuity primitive for long-horizon governed runs.

resume

agentxchain resume [options]

Flag	Default	Description
--role <role>	(phase entry role)	Override the target role for the next assignment or re-dispatch
--turn <id>	(selected retained turn)	Target a specific retained turn when multiple blocked, failed, or retrying turns exist
--no-intent	false	Ignore approved injected intents for this dispatch and keep the existing routing/default charter

Initializes or resumes a governed run and then assigns or re-dispatches one turn without waiting for completion. Use it when you want a fresh dispatch bundle now, or when a retained turn must be re-dispatched after a failed, retrying, or operator-escalated blocked state. If a turn is already active and you need to continue waiting on it, use agentxchain step --resume instead.

unblock

agentxchain unblock <escalation-id>

No flags.

Resolves the current open human escalation record from .agentxchain/human-escalations.jsonl, updates HUMAN_TASKS.md, and continues the governed run through the same recovery path resume would use. This is the operator-focused command when status shows a concrete human task id such as hesc_abcd1234.

For phase-gate escalations, unblock reconciles the gate before re-dispatching. If the gate is now satisfied, it marks the gate passed, advances to the next phase, clears stale retained turns from the phase being exited, emits phase_cleanup, and dispatches the new phase's entry role.

inject

agentxchain inject "<description>" [options]

Flag	Default	Description
--priority <level>	p0	Priority level: p0, p1, p2, p3
--template <id>	generic	Governed template for the injected work
--charter <text>	(description)	Delivery charter — defaults to the description
--acceptance <text>	(description)	Comma-separated acceptance criteria
--approver <name>	human	Approver identity recorded on the intent
--no-approve	false	Stop at triaged instead of auto-approving
-j, --json	false	Output as JSON

Injects a priority work item into the intake queue in one atomic operation. Composes intake record + intake triage + intake approve so the operator can express "do this next" without running three separate commands.

When priority is p0, a preemption marker is written to .agentxchain/intake/injected-priority.json. The run loop checks for this marker at the top of each iteration. If present and no turns are active, the current run yields with stop_reason: "priority_preempted" so the scheduler or continuous loop can pick up the injected work next. On the repo-local path, schedule daemon now consumes that marker by planning and starting the injected intent, then clears the marker after the injected governed turn is assigned. Non-p0 injections enter the queue for normal priority ordering without triggering preemption.

agentxchain status shows a prominent "Priority injection pending" banner when a preemption marker exists.

escalate

agentxchain escalate --reason <reason> [--detail <detail>] [--action <action>] [--turn <id>]

Flag	Default	Description
--reason <reason>	required	Operator escalation summary persisted to state and the decision ledger
--detail <detail>	reason text	Longer escalation detail surfaced in status and recovery metadata
--action <action>	derived	Override the default recovery action string
--turn <id>	(auto when one active turn)	Target a specific active turn when multiple turns exist

Raises an operator-controlled escalation and moves the run to status = blocked. This command is active-run-only. If exactly one active turn exists, that turn is retained automatically. Retained manual turns recover with agentxchain resume; retained non-manual turns recover with agentxchain step --resume. If no turn is active, the escalation blocks the run at the run level and the default recovery action becomes agentxchain resume. If multiple active turns exist, --turn is required so the operator is explicit about which turn the escalation is retaining, and the suggested recovery command includes that --turn target.

The escalation is recorded in both .agentxchain/state.json and .agentxchain/decision-ledger.jsonl with decision = "operator_escalated". When step or resume clears the blocked escalation, the ledger records decision = "escalation_resolved".

step

agentxchain step [options]

Flag	Default	Description
--role <role>	(phase entry role)	Override the target role for this turn
--resume	false	Resume waiting for an already-active turn instead of creating a new one
--turn <id>	(current active)	Target a specific active turn (required with --resume when multiple turns exist)
--no-intent	false	Ignore approved injected intents for this dispatch and keep the existing routing/default charter
--poll <seconds>	2	Polling interval for the manual adapter
--stream	false	Stream live subprocess output to the terminal (alias for --verbose)
--verbose	false	Stream local_cli subprocess output while the turn is running
--auto-reject	false	Auto-reject and retry on validation failure

The primary command for advancing a run. Creates a turn, writes the dispatch bundle, invokes the adapter, waits for a staged result, validates the result schema, and records it. If validation fails, the turn is marked failed with a retained disposition. That retained validation-failure path exits non-zero so automation can distinguish "turn accepted" from "turn needs operator recovery". On a valid staged result, step auto-accepts the turn immediately unless a configured acceptance policy blocks or escalates the commit. Use accept-turn directly when you are fixing a retained failed or conflicted turn, or when you intentionally interrupted a manual step before the CLI detected the staged result.

run

agentxchain run [options]

Flag	Default	Description
--role <role>	(config-driven)	Override the initial role for the first turn only
--max-turns <n>	50	Maximum turns before stopping
--auto-approve	false	Auto-approve all gates (non-interactive mode)
--verbose	false	Stream adapter subprocess output
--dry-run	false	Print dispatch plan without executing
--continue-from <run_id>	—	Continue from a prior terminal run (sets trigger=continuation provenance)
--recover-from <run_id>	—	Recover from a prior blocked run (sets trigger=recovery provenance)
--inherit-context	false	Inherit read-only summary context from the parent run (requires --continue-from or --recover-from)
--continuous	false	Enable continuous vision-driven loop: derive work from VISION.md and run until satisfied
--vision <path>	.planning/VISION.md	Path to VISION.md (project-relative or absolute)
--max-runs <n>	100	Maximum consecutive governed runs in continuous mode
--poll-seconds <n>	30	Seconds between idle-detection cycles in continuous mode
--max-idle-cycles <n>	3	Stop after N consecutive idle cycles with no derivable work
--on-idle <mode>	"exit"	Idle policy after --max-idle-cycles: exit, perpetual, or human_review
--session-budget <usd>	null	Cumulative session-level budget cap in USD for continuous mode. Stops the session cleanly when total spend across all runs reaches this limit

Drives a governed run to completion using the runLoop library. Continuously assigns turns, dispatches to adapters, handles gate approvals, and manages rejection/retry until the run reaches a terminal state (completed, blocked, or max_turns_reached). The manual adapter is not supported — use step for manual dispatch workflows. When a gate pause is reached, the command prompts interactively on stdin unless --auto-approve is set. In non-TTY environments (e.g., CI), gates fail closed unless --auto-approve is explicitly passed. If project.goal is set in agentxchain.json, every dispatched turn's CONTEXT.md includes a ## Project Goal section so agents know what the project is trying to accomplish.

Terminal-state behavior: if the last repo-local run is completed, agentxchain run starts a fresh manual run instead of reusing the terminal run. If the last repo-local run is blocked, agentxchain run keeps that run blocked; use agentxchain resume to continue the same run, or --continue-from / --recover-from to start a fresh run linked to a prior terminal parent.

Provenance flags: --continue-from and --recover-from are mutually exclusive. Both validate that the referenced run exists in run-history.jsonl and is in a terminal state (completed or blocked). If the current repo state is terminal, the command bootstraps a fresh run envelope before initializing the new run. The new run's state.json will carry the provenance metadata linking it to the parent run. These flags are metadata — they do not copy phase state or alter routing.

Context inheritance: Add --inherit-context to either --continue-from or --recover-from to carry a read-only summary of the selected parent run into the child run. The inherited summary includes the parent's terminal status, phases completed, roles used, terminal retrospective, recent decisions, and recent accepted-turn summaries from that parent run's recorded run-history.jsonl snapshot. The child run remains a fresh run — no phase state, gate approvals, or mutable state is copied. The inherited summary is rendered in the first turn's CONTEXT.md, exposed in status --json, report, and export, and persists in state.json as inherited_context. If you target an older parent run recorded before inheritance snapshots existed, inheritance degrades to metadata-only with warnings instead of reading today's repo-global history and pretending it came from that parent.

Continuous vision-driven mode: --continuous enables a lights-out loop where the only human-supplied input is VISION.md. The loop derives candidate intents from unaddressed vision goals, records them through the intake pipeline, and executes governed runs automatically. Each run's provenance traces back to a specific vision section (trigger: "vision_scan"). The loop stops on --max-runs, --session-budget (when cumulative spend exceeds the cap), SIGINT, or a human-blocking escalation. After --max-idle-cycles empty scans, --on-idle exit stops with idle_exit, --on-idle perpetual dispatches a PM idle-expansion turn through the intake pipeline, and --on-idle human_review pauses with idle_human_review_required. Configure triage_approval: "human" in run_loop.continuous config to require operator approval for vision-derived intents instead of auto-approving. Use agentxchain status to view the continuous session and current vision-derived objective. VISION.md is project-relative — each governed project has its own VISION.md, never the agentxchain.dev repo's VISION.md.

Perpetual mode reads run_loop.continuous.idle_expansion:

{
  "run_loop": {
    "continuous": {
      "on_idle": "perpetual",
      "idle_expansion": {
        "sources": [".planning/VISION.md", ".planning/ROADMAP.md", ".planning/SYSTEM_SPEC.md"],
        "max_expansions": 5,
        "role": "pm",
        "malformed_retry_limit": 1
      }
    }
  }
}

The PM expansion turn must return one idle_expansion_result: kind: "new_intake_intent" with a concrete intake charter and acceptance contract, or kind: "vision_exhausted" with per-heading classification. New governed projects include .agentxchain/prompts/pm-idle-expansion.md as the reviewable prompt scaffold. per_session_max_usd is checked before idle expansion, and idle_expansion.max_expansions stops repeated unproductive expansion as vision_expansion_exhausted.

Startup and stale-turn watchdogs: local CLI turns now use two distinct watchdogs. run_loop.startup_watchdog_ms controls how long AgentXchain waits for real startup proof (worker attach plus first output or an equivalent staged result) before retaining the turn as failed_start; the default is 180 seconds. When one local runtime is slower than the others, set runtimes.<id>.startup_watchdog_ms to override the global startup watchdog for that runtime only. run_loop.stale_turn_threshold_ms controls how long a turn that already produced startup proof may go silent before it is retained as stalled; the default is 10 minutes for local_cli turns and 5 minutes for api_proxy turns. Operators should tune these through config, not code edits: agentxchain config --set run_loop.startup_watchdog_ms 180000, agentxchain config --set runtimes.local-qa.startup_watchdog_ms 180000, and agentxchain config --set run_loop.stale_turn_threshold_ms 600000.

schedule

agentxchain schedule list [--schedule <id>] [--at <iso8601>] [--json]
agentxchain schedule run-due [--schedule <id>] [--at <iso8601>] [--json]
agentxchain schedule daemon [--schedule <id>] [--poll-seconds <n>] [--max-cycles <n>] [--json]
agentxchain schedule status [--json]

Repo-local run scheduling is the narrow first step from "tool you invoke" to "system that runs itself." Schedules live in agentxchain.json under a top-level schedules object:

{
  "schedules": {
    "nightly_governed_run": {
      "enabled": true,
      "every_minutes": 60,
      "auto_approve": true,
      "max_turns": 10,
      "initial_role": "pm",
      "trigger_reason": "Nightly governed run"
    }
  }
}

Field	Default	Meaning
enabled	true	Whether the schedule is eligible to run
every_minutes	required	Fixed interval cadence in minutes
auto_approve	true	Whether scheduled runs auto-approve gates
max_turns	50	Safety limit passed to the governed run
initial_role	config-driven	Optional first-turn role override
trigger_reason	schedule:<id>	Human-readable provenance reason
continuous.enabled	false	Opt the schedule into vision-driven continuous mode
continuous.vision_path	—	Required when enabled. Project-relative path to VISION.md
continuous.max_runs	50	Max governed runs before the continuous session exits
continuous.max_idle_cycles	5	Max polls with no derivable work before idle exit
continuous.on_idle	"exit"	exit, perpetual, or human_review after the idle threshold
continuous.idle_expansion.sources	VISION, ROADMAP, SYSTEM_SPEC	Source files for PM idle-expansion when on_idle is perpetual
continuous.idle_expansion.max_expansions	5	Max consecutive PM idle-expansion attempts before vision_expansion_exhausted
continuous.idle_expansion.role	"pm"	Role assigned to the PM idle-expansion turn
continuous.idle_expansion.malformed_retry_limit	1	Reserved retry budget for malformed idle-expansion outputs
continuous.triage_approval	"auto"	"auto" or "human" for vision-derived intent approval
continuous.per_session_max_usd	null	Cumulative session-level budget cap in USD. Session stops cleanly when total spend reaches this limit

Behavior contract:

• schedule list shows due status, next due time, and last run/skip metadata from .agentxchain/schedule-state.json
• schedule run-due evaluates configured schedules once and runs only the ones currently due
• schedule daemon repeats that same due-run path on a fixed local poll interval and, after the operator clears a blocked schedule-owned run with the surfaced recovery action (agentxchain unblock <id> for needs_human, agentxchain reissue-turn --reason ghost for BUG-51 ghost startup, agentxchain reissue-turn --reason stale for BUG-47 stale turns), continues the same schedule-owned run on the next poll
• when a running schedule-owned turn yields with priority_preempted, schedule daemon consumes the injected p0 intent, plans it if needed, starts it into the same schedule-owned run, and continues that run on the next poll
• scheduled runs use trigger: "schedule" provenance instead of pretending they were started manually
• scheduled runs start only from missing (no state file yet), idle, or completed
• scheduled runs do not attach to an existing active or paused run
• scheduled runs do not auto-recover a blocked run

The skip behavior is deliberate. If a repo is already active, paused on a gate, or blocked for operator recovery, the scheduler records a skip reason and exits cleanly. It does not invent a second run and it does not hijack the current one. The only continuation exception is explicit operator recovery: if a scheduled run blocks, the daemon stays alive, and once the operator runs the surfaced recovery action (agentxchain unblock <id>, agentxchain reissue-turn --reason ghost, agentxchain reissue-turn --reason stale, or whatever status / schedule daemon --json reports), the next daemon poll continues that same reactivated run instead of leaving it stranded in active.

Daemon health

schedule daemon writes a heartbeat file at .agentxchain/schedule-daemon.json on every cycle. schedule status reads this file and reports daemon health:

Status	Meaning
running	Heartbeat is recent (within poll_seconds * 3 or 30s, whichever is greater)
stale	Heartbeat file exists but is older than the staleness threshold
not_running	State file exists but is malformed or missing heartbeat data
never_started	No daemon state file found

Use schedule status --json for machine-readable output including pid, started_at, last_heartbeat_at, last_cycle_result, poll_seconds, and stale_after_seconds.

accept-turn

agentxchain accept-turn [options]

Flag	Default	Description
--turn <id>	(current active)	Target a specific active turn when multiple turns exist
--resolution <mode>	standard	Conflict resolution mode for conflicted turns: standard or human_merge
--checkpoint	false	Automatically checkpoint (git commit) the accepted turn's artifacts after successful acceptance
--normalize-artifact-type <type>	(none)	Normalize an empty workspace artifact to a safe artifact type before acceptance. Currently supports review
--normalize-staged-result	false	Run known-safe staged-result field normalization before acceptance

Accepts the most recent staged turn result. The result is committed to .agentxchain/history.jsonl and the decision ledger is updated. If the turn included a phase_transition_request, the run enters a blocked:gate state pending approve-transition.

Use --checkpoint to atomically commit the accepted turn's files_changed to git after acceptance, so the next authoritative turn starts from a clean baseline without manual git commit.

checkpoint-turn

agentxchain checkpoint-turn [--turn <id>]

Flag	Default	Description
--turn <id>	(latest accepted)	Checkpoint a specific accepted turn from history

Commits the accepted turn's declared files_changed to git with a structured commit message including turn provenance (turn_id, role, phase, intent_id). Records checkpoint_sha and checkpointed_at in history and state. Idempotent — running on an already-checkpointed turn is a no-op.

Use this when an authoritative turn was accepted but not yet committed, and the next writable turn is blocked with a checkpoint_required error. In continuous mode (run --continuous), auto-checkpoint is enabled by default so this command is only needed for manual recovery.

reconcile-state

agentxchain reconcile-state --accept-operator-head

Flag	Default	Description
--accept-operator-head	required	Accept safe fast-forward operator commits on top of the last checkpoint as the new governed baseline

Use this when status reports Git HEAD has moved since checkpoint after an intentional operator commit. The command verifies that the previous checkpoint is an ancestor of HEAD, rejects commits that modify .agentxchain/, rejects deletion of critical governed evidence, updates accepted_integration_ref, refreshes session.json.baseline_ref, and emits state_reconciled_operator_commits.

reject-turn

agentxchain reject-turn [options]

Flag	Default	Description
--turn <id>	(current active)	Target a specific active turn when multiple turns exist
--reason <reason>	""	Operator reason for the rejection
--reassign	false	Immediately re-dispatch a conflicted turn with conflict context

Rejects the staged turn result. The turn returns to pending status and can be re-dispatched via resume or replaced by a new step. The rejection reason is recorded in the decision ledger.

Approval commands

approve-transition

agentxchain approve-transition [--dry-run]

Approves a pending phase transition gate. The run must be in blocked:gate state with a pending phase_transition_request. On approval, the phase advances (e.g., planning to implementation, implementation to verification).

If the current phase's exit gate is pending but no pending_phase_transition object exists, approve-transition fails closed and prints the gate mismatch. Use agentxchain unblock <hesc_id> when the gate is tied to an open human escalation, or agentxchain gate show <gate_id> --evaluate to inspect the missing evidence.

Flag	Description
--dry-run	Preview configured gate actions without executing them or mutating state

If the gate has gate_actions configured, they execute sequentially after approval hooks pass. A failing gate action blocks the run while preserving the pending gate for retry. See Gate Actions for the config contract, dry-run semantics, and retry model.

Blocked state model:

Blocked state	Trigger	Resolution
blocked:gate	A turn's phase_transition_request was accepted	approve-transition
blocked:completion	A turn's run_completion_request was accepted	approve-completion
blocked:conflict	State file conflict detected	Resolve with reject-turn --reassign or accept-turn --resolution human_merge

approve-completion

agentxchain approve-completion [--dry-run]

Approves run completion. This is the final human gate. The run transitions to completed status and no further turns can be created. The ship verdict (.planning/ship-verdict.md) should be reviewed before approval, and the runtime only opens this gate when that file carries an affirmative ## Verdict: value.

Flag	Description
--dry-run	Preview configured gate actions without executing them or mutating state

If the gate has gate_actions configured, they execute sequentially after approval hooks pass. A failing gate action blocks the run while preserving the pending gate for retry. See Gate Actions for the config contract, dry-run semantics, and retry model.

Validation

validate

agentxchain validate [options]

Flag	Default	Description
--mode <mode>	full	Validation mode: kickoff, turn, or full
--agent <id>	—	Expected agent for last history entry (turn mode)
-j, --json	false	Output as JSON

Validation modes:

Mode	What it checks
kickoff	Config schema, role definitions, adapter configuration, prompt files exist
turn	Current staged turn result schema, required fields, objection presence, decision ID uniqueness
full	Everything in kickoff + turn, plus history integrity, decision ledger consistency, phase sequence validity, and state file coherence

For governed projects, validate also checks template-registry integrity, the current project's configured template binding, and admission-control dead ends before the first turn runs. Admission control fails closed on impossible file-gated topologies such as:

• a gated phase with no routed file producer
• a required owned_by artifact whose owner is not routed into the phase
• a required owned_by artifact whose owner is routed but still cannot write (for example review_only on a non-manual runtime)

Human-approval topology with no in-config manual runtime remains advisory only. validate reports that as a warning because external approval through the CLI, dashboard, or webhook is a legitimate operating model.

Returns exit code 0 on success, 1 on validation failure with details.

For governed repos, the output keeps the version axes separate instead of flattening them into one number:

• protocol version: v7
• config generation: v4
• governed config schema: 1.0

validate --json exposes these as protocol_version, config_generation, and config_schema_version. The older version field remains as a compatibility alias for config generation.

verify turn

agentxchain verify turn [turn_id] [--json] [--timeout <ms>]

Flag	Default	Description
--json	false	Output structured replay results
--timeout <ms>	30000	Per-command replay timeout in milliseconds

validate --mode turn proves the staged result is structurally acceptable. verify turn answers the next question: does the staged turn's declared verification evidence still reproduce in the current workspace?

The command is intentionally narrow:

• it only works on governed config-generation v4 repos
• it targets active turns only, using the staged result at .agentxchain/staging/<turn_id>/turn-result.json
• it validates the staged result before replaying anything
• it replays only verification.machine_evidence[].command
• it compares actual exit codes to declared verification.machine_evidence[].exit_code
• it does not compare stdout/stderr text
• it does not mutate state, gate status, history, or ledgers

verification.commands and verification.evidence_summary are not executable proof on their own. If machine_evidence is absent, the command exits non-zero with overall: "not_reproducible" instead of pretending the turn was verified.

Typical use:

# active turn only
agentxchain verify turn

# target one retained turn explicitly
agentxchain verify turn turn_abc123 --json

Exit codes:

Exit code	Meaning
0	Every replayed command exited with the declared exit code (overall: "match")
1	Replay drifted, timed out, errored, or the staged turn had no replayable machine_evidence
2	Command/input/config error

This is a current-workspace reproducibility check, not a historical time machine. A mismatch can come from false agent reporting, later repo drift, or environment drift. The contract is still useful because the staged turn only records command strings plus exit codes.

If you want reproducibility to become an acceptance requirement instead of a manual check, add the require_reproducible_verification rule under top-level policies in agentxchain.json. That reuses the same replay contract during accept-turn, step, and run.

Replay is not a sandbox. AgentXchain executes the staged verification.machine_evidence[].command strings in the repo root shell, so this surface assumes staged turn data is trusted agent-authored execution intent.

replay turn

agentxchain replay turn [turn_id] [--json] [--timeout <ms>]

Flag	Default	Description
--json	false	Output structured replay results
--timeout <ms>	30000	Per-command replay timeout in milliseconds

replay turn is the historical counterpart to verify turn.

• verify turn replays the staged active turn before acceptance
• replay turn replays an already accepted turn from .agentxchain/history.jsonl

The command is intentionally narrow:

• it only works on governed config-generation v4 repos
• it targets accepted turns from repo-local history, not coordinator workspaces
• it defaults to the most recent accepted turn when no turn_id is provided
• it accepts full accepted-turn ids or unique prefixes and fails closed on ambiguity
• it replays only verification.machine_evidence[].command
• it compares actual exit codes to declared verification.machine_evidence[].exit_code
• it does not compare stdout/stderr text
• it does not mutate state, gate status, history, or ledgers

verification.commands and verification.evidence_summary are still not executable proof on their own. If the accepted turn recorded no machine_evidence, the command exits non-zero with overall: "not_reproducible".

Typical use:

# replay the latest accepted turn
agentxchain replay turn

# replay one accepted turn explicitly
agentxchain replay turn turn_abc123 --json

Exit codes:

Exit code	Meaning
0	Every replayed command exited with the declared exit code (overall: "match")
1	Replay drifted, timed out, errored, or the accepted turn had no replayable machine_evidence
2	Command/input/config error

This is still a current-workspace reproducibility check, not a time machine. A mismatch can mean the original acceptance was wrong, or that the repo/environment has drifted since the turn was accepted. The historical acceptance-time verification_replay summary, when present, is shown for comparison but does not control the current command result.

Replay is not a sandbox. AgentXchain executes the accepted turn's verification.machine_evidence[].command strings in the repo root shell, so this surface assumes accepted turn history is trusted governed execution intent.

replay export

agentxchain replay export <export-file> [--port <port>] [--json] [--no-open]

Flag	Default	Description
--port <port>	3847	Dashboard server port
--json	false	Output structured session info instead of interactive output
--no-open	false	Do not auto-open browser

replay export starts the dashboard bridge-server serving a completed export's state for offline post-mortem analysis. The dashboard is fully read-only: no gate approval and no live mutation path.

Unlike restore, replay export is an observability surface, not a continuity surface. That is why it accepts both governed run exports and coordinator exports, restores them into a temporary workspace, and never treats the replayed files as the new live repo state.

The command reads an export artifact produced by agentxchain export, restores the embedded file bytes from the artifact's content_base64 fields into a temporary workspace, and starts the dashboard against that workspace. When the server stops (Ctrl+C), the temporary workspace is cleaned up automatically.

Both export kinds are supported:

• Run exports rehydrate the governed repo snapshot so /api/state, /api/history, /api/events, and related dashboard views work against the replayed files.
• Coordinator exports rehydrate the coordinator workspace plus every successful embedded child repo export under its declared repo path so /api/coordinator/* surfaces, including aggregated child-repo events, work offline.

If a coordinator export contains a failed child repo export (ok: false), replay still starts. AgentXchain restores a minimal placeholder governed repo at that path so coordinator dashboard validation remains readable even though the nested repo artifact was unavailable.

Do not collapse replay export into the other artifact surfaces:

• audit is for the live current repo/workspace.
• report --input is for an existing export artifact when you want text, json, markdown, or html output.
• replay export is for an existing export artifact when you want the read-only dashboard instead of a derived report document.

That same distinction survives partial coordinator artifacts. report --input keeps repo_ok_count / repo_error_count plus the failed repo row and error, while replay export restores a placeholder governed repo for the failed child path. Neither command fabricates a nested child export that was never captured.

# browse a completed run export in the dashboard
agentxchain replay export ./my-run-export.json

# start on a specific port without opening a browser
agentxchain replay export ./my-run-export.json --port 4000 --no-open

# get session info as JSON (useful for CI/automation)
agentxchain replay export ./my-run-export.json --json --no-open

In replay mode, the dashboard session endpoint reports replay_mode: true and capabilities.approve_gate: false. Any POST to /api/actions/approve-gate returns HTTP 403 with code: "replay_mode".

Protocol conformance

conformance check

agentxchain conformance check [options]

# compatibility alias
agentxchain verify protocol [options]

Flag	Default	Description
--tier <tier>	1	Maximum conformance tier to verify: 1, 2, or 3. Runs all fixtures up to and including the specified tier (e.g. --tier 2 runs both tier 1 and tier 2 fixtures)
--surface <surface>	all surfaces in tier	Restrict the run to one surface such as state_machine, dispatch_manifest, or coordinator. If capabilities.json includes a surfaces map, the verifier rejects requests for surfaces not explicitly claimed in that map
--target <path>	.	Root containing .agentxchain-conformance/capabilities.json
--remote <url>	none	Remote HTTP conformance endpoint base URL. Mutually exclusive with --target
--token <token>	none	Bearer token for remote verification. Valid only with --remote
--timeout <ms>	30000	Per-fixture remote HTTP timeout in milliseconds. Valid only with --remote
--format <format>	text	Output format: text or json

conformance check is the preferred front door for protocol implementors. verify protocol remains supported as a compatibility alias over the same verifier.

The repo ships a first-party conformance corpus under .agentxchain-conformance/. The verifier runs those fixtures against either:

• a local implementation that exposes a stdio-fixture-v1 adapter and declares supported tiers and surfaces in .agentxchain-conformance/capabilities.json
• a remote HTTP implementation that exposes GET /conform/capabilities and POST /conform/execute with adapter.protocol: "http-fixture-v1"

Typical use:

# self-validate the reference CLI
agentxchain conformance check --tier 3 --target .

# isolate one surface and emit CI-friendly JSON
agentxchain conformance check --tier 2 --surface dispatch_manifest --target . --format json

# verify a remote implementation over HTTP
agentxchain conformance check --tier 1 --remote https://example.com/agentxchain --format json

Progressive conformance: Adapters may return not_implemented (exit code 3 from the adapter process) for fixtures they do not yet support. The verifier treats not_implemented as non-failing — the overall exit code remains 0 if all other fixtures pass. This allows implementations to adopt conformance progressively: pass lower tiers first while marking higher-tier or optional surfaces as not yet ready.

Exit codes:

Exit code	Meaning
0	All selected fixtures passed (including any marked not_implemented)
1	One or more fixtures failed
2	Verifier or adapter error (malformed response, invocation problem, unsupported target, or unclaimed surface)

Valid adapter response statuses: pass (exit 0), fail (exit 1), error (exit 2), not_implemented (exit 3).

Use this command in CI if you fork the runner or build an alternative implementation. "Open protocol" without continuous conformance proof is marketing, not governance.

Export verification

verify export

agentxchain verify export [--input <path>|-] [--format text|json]

Flag	Default	Description
--input <path>	-	Read the export JSON from a file, or pass - to read from stdin
--format <format>	text	Output format: text or json

verify export proves that an audit artifact still matches itself after it has been written, copied, uploaded, or attached somewhere else. It supports both agentxchain_run_export and agentxchain_coordinator_export.

The verifier does three things:

1. Decodes each file entry's content_base64
2. Recomputes bytes and sha256
3. Checks that the decoded content matches the exported data and that run/coordinator summary fields still match the exported file set

For coordinator exports, that includes summary.aggregated_events when present. The verifier reconstructs the child-repo event timeline from embedded successful repo exports and fails closed if the summary claims events from a repo whose nested export was not embedded.

When summary.workflow_phase_order is present, verify export also enforces the phase-order summary invariants: the array must be non-empty, contain unique trimmed phase names, and include the current summary.phase value. The comparison path stays conservative: diff --export only infers backward phase movement when both exports declare the same phase order, and emits an explicit phase-order drift warning otherwise.

Typical use:

# verify a saved artifact
agentxchain export --output artifacts/run-export.json
agentxchain verify export --input artifacts/run-export.json

# verify a pipeline artifact without touching disk
agentxchain export | agentxchain verify export

Exit codes:

Exit code	Meaning
0	Export artifact verification passed
1	Export artifact parsed but failed integrity or structural verification
2	Command or input error

verify diff

agentxchain verify diff <left_export.json> <right_export.json> [--format text|json]

Flag	Default	Description
--format <format>	text	Output format: text or json

verify diff is the fail-closed operator shortcut for comparing two export artifacts safely. It verifies both export artifacts first using the same contract as verify export, then builds the normalized export diff and surfaces governance regressions when both artifacts are trustworthy.

This matters because regression detection on unverified exports is theater. If either artifact has drifted, been truncated, or has an internal summary mismatch, the command skips the diff entirely if either artifact fails verification instead of pretending the regression output is reliable.

For coordinator exports, verify diff keeps the repo-status truth boundary explicit. Repo-status changes and coordinator repo-status regressions come from authority-first child repo status when nested child exports are readable. summary.repo_run_statuses remains raw coordinator snapshot metadata and can stay visible in JSON output, but it must not create a false repo-status change or regression by itself.

Typical use:

# compare two saved artifacts safely
agentxchain verify diff ./artifacts/run-before.json ./artifacts/run-after.json

# CI-friendly JSON output
agentxchain verify diff ./artifacts/run-before.json ./artifacts/run-after.json --format json

When both artifacts verify, the command reports:

• whether the exports changed structurally
• whether governance regressions exist
• the concrete regression entries (status, budget, gate, decisions, delegation, and coordinator-only repo/barrier/event regressions)
• for coordinator exports, authority-first child repo status changes alongside preserved coordinator snapshot metadata when present

When either artifact fails verification, verify diff reports the left/right verification failures and skips the diff entirely if either artifact fails verification.

Exit codes:

Exit code	Meaning
0	Both exports verify and no governance regressions are detected
1	Export verification fails or governance regressions are detected
2	Command or input error (for example missing file or mismatched export kinds)

Migration

migrate

agentxchain migrate [options]

Flag	Default	Description
-y, --yes	false	Skip confirmation prompts
-j, --json	false	Output migration report as JSON

Migrates state and config from an older protocol version to the current version (v7). Handles schema changes in agentxchain.json, state.json, and history entries.

migrate-intents

agentxchain migrate-intents [options]

Flag	Default	Description
-j, --json	false	Output as JSON
--dry-run	false	List legacy intents without modifying them

One-shot repair command for repos with stuck intents that block continuous mode. Handles two classes:

1. Legacy intents (approved_run_id: null): pre-BUG-34 format intents archived with status: "archived_migration".
2. Phantom intents (BUG-42): intents bound to the current run whose planning artifacts already exist on disk. These would fail with "existing planning artifacts would be overwritten" if dispatched. Marked status: "superseded".

Safe to run multiple times — idempotent. Use this when continuous mode aborts due to stale intents that were never cleaned up by the automatic startup path.

Readiness

doctor

agentxchain doctor [--json]

Flag	Default	Description
--json	false	Output structured JSON with all check results

Checks governed project readiness for running turns. doctor is a static readiness check, not a live transport probe. On governed config-generation v4 projects, it runs these checks:

Check	ID	Description
Config validation	config_valid	Loads agentxchain.json and validates against the governed schema
Roles defined	roles_defined	At least one role exists in the config
Runtime prerequisites	runtime_<id>	Per-runtime: local binaries found, required API key env vars set, remote endpoints noted as unverifiable, plus runtime capability contract and bound-role ownership summary
State directory	state_dir	.agentxchain/ exists
State health	state_health	state.json parses with a recognized schema version
Schedule health	schedule_health	Daemon status when schedules are configured (skipped otherwise)
Workflow-kit artifacts	workflow_kit	Required artifacts for the current phase exist on disk
Admission control	admission_control	Static dead-end detection for impossible gated workflows, unreachable owned_by artifacts, and advisory human-approval topology
Plugin health	plugin_<name>	Per-plugin: install path exists, manifest valid, hook files present, config env vars set (skipped when no plugins installed)

Each check produces pass, warn, or fail. Exit code 0 when all checks pass or only warn. Exit code 1 when any check fails.

For runtime checks, doctor --json now includes:

• runtime_contract with transport, write-path class, proposal support, binary requirement, and workflow-artifact ownership contract
• bound_roles[] with per-role effective write path and workflow-artifact ownership suitability

Use agentxchain connector check when you want a real live probe against configured API, MCP HTTP, or remote-agent endpoints before the first governed turn.

When doctor sees runtimes that still need live probing beyond static readiness (api_proxy, remote_agent, MCP streamable_http), it exposes that handoff explicitly:

• text mode prints a next-step hint to run agentxchain connector check after readiness passes
• --json adds connector_probe_recommended, connector_probe_runtime_ids, and connector_probe_detail

doctor --json also reports the same versioning split explicitly:

• protocol_version: "v7"
• config_generation: 4
• config_schema_version: "1.0"

The older config_version field remains as a compatibility alias for config generation.

On legacy v3 projects, runs the legacy environment checks (Cursor, jq, osascript, watch process, trigger file, PM signoff).

connector check

agentxchain connector check [runtime_id] [--json] [--timeout <ms>]

Flag	Default	Description
[runtime_id]	all non-manual runtimes	Probe one configured runtime only
--json	false	Output structured JSON instead of text
--timeout <ms>	8000	Per-probe timeout in milliseconds

Runs active connector probes for governed non-manual runtimes. Unlike doctor, this command makes real probe attempts where the transport allows it:

• local_cli and MCP stdio: command presence on PATH
• api_proxy: live minimal API request using the configured provider/model/auth
• MCP streamable_http and remote_agent: live HTTP probe to the configured endpoint

Text output prints a Probing <runtime_id>... line before each check starts so slow endpoints do not leave the terminal looking hung. Use --timeout to lower or raise the per-connector wait budget when debugging reachability problems.

Successful probes return exit code 0. Any connector failure returns exit code 1. Command or project-boundary errors return exit code 2.

connector capabilities

agentxchain connector capabilities [runtime_id] [--all] [--json]

Flag	Default	Description
[runtime_id]	none	Show one configured runtime's merged capability contract
--all	false	Show all configured runtimes
--json	false	Emit machine-readable JSON instead of text

Use connector capabilities when you need the structured capability handshake, not a live probe. This surface resolves:

• declared_capabilities from raw agentxchain.json
• merged_contract after type defaults and declarations are combined
• declaration_warnings for known-incompatible declarations
• role_bindings showing each bound role's effective write path and workflow-artifact ownership

This is the correct machine-readable surface for connector portability work. External tooling should not scrape doctor or role show to reconstruct the same contract.

The output shape is governed by a JSON Schema artifact at agentxchain/schemas/connector-capabilities-output. Third-party tooling can validate both the input config (agentxchain/schemas/agentxchain-config) and the handshake output against published schemas.

connector validate

agentxchain connector validate <runtime_id> [--role <role_id>] [--json] [--timeout <ms>] [--keep-artifacts]

Flag	Default	Description
<runtime_id>	required	Validate one configured non-manual runtime
--role <role_id>	first role bound to the runtime	Validate a specific runtime+role binding
--json	false	Output structured JSON instead of text
--timeout <ms>	120000	Synthetic dispatch timeout in milliseconds
--keep-artifacts	false	Keep the scratch validation workspace even on success

Use connector validate when reachability is not enough and you want one bounded proof that a configured runtime can actually stage a protocol-valid governed turn result. This command is stricter than connector check:

• connector check proves transport reachability
• connector validate proves one runtime+role binding can survive dispatch and validator acceptance

The command runs in a scratch copy of the repo so local_cli validation does not mutate your real workspace. On failure, the scratch workspace is kept automatically and surfaced in the output so you can inspect the exact dispatch bundle, adapter logs, and staged artifact that failed.

This validation can incur real spend for live runtimes such as api_proxy, remote_agent, or MCP connectors backed by real model services. That is why the command validates one runtime at a time instead of silently dispatching every configured connector.

In --json mode, the result includes schema_contract, which cross-checks the selected runtime+role binding against the published config and handshake artifacts before dispatch:

• agentxchain/schemas/agentxchain-config
• agentxchain/schemas/connector-capabilities-output

Workflow Kit

workflow-kit describe

agentxchain workflow-kit describe [--json]

Flag	Default	Description
--json	false	Output structured JSON instead of text

Inspect the workflow kit contract for the current governed project. Returns the active phase templates, workflow artifacts, semantic validators, and gate artifact coverage.

The --json output includes:

• workflow_kit_version — contract version
• source — default, explicit, or mixed
• phase_templates — available and in-use template IDs
• phases — per-phase template, source, and artifact details with existence status
• semantic_validators — the full list of content-aware validators
• gate_artifact_coverage — which gates reference which artifacts and which phases link to those gates

The output shape is governed by a published JSON Schema at agentxchain/schemas/workflow-kit-output. See the Workflow Kit page for the full operating model.

Dashboard

history

agentxchain history [--json] [--limit <n>] [--status completed|blocked] [--lineage <run_id>] [--dir <path>]

Flag	Default	Description
--json	false	Output as JSON array
--limit <n>	20	Number of recent runs to show
--status <status>	—	Filter by terminal status: completed or blocked
--lineage <run_id>	—	Show the lineage chain for a specific run by walking parent_run_id links
--dir <path>	.	Project directory

Shows a persistent cross-run history of governed runs in this project. Each terminal governed run appends a summary record to .agentxchain/run-history.jsonl with run ID, status, phases, turns, cost, duration, connector metadata, and a deterministic terminal retrospective used for later inheritance handoff. The file persists across runs and is not reset when a new run starts.

The default table includes a Trigger column when provenance metadata is available on the recorded run, an Outcome column with a compact derived operator label (clean, follow-on, operator, blocked, unknown), a Ctx column showing whether the run has a usable inheritance snapshot for --inherit-context child runs (✓ = usable snapshot, — = metadata-only lineage), and a Headline column with the terminal retrospective summary for quick operator review. When a run recorded a follow-on hint or next operator action, the text view prints a single indented next: line below that row instead of forcing operators to open a report. Older history entries created before provenance recording show legacy instead of inventing a trigger value retroactively.

Use --json for machine-readable output. Each entry includes a computed inheritable boolean so scripts can tell whether a run has a usable inheritance snapshot without inspecting the raw inheritance_snapshot arrays manually, plus an outcome_summary object carrying the same derived label and any next action digest shown in text mode.

Lineage view: --lineage <run_id> walks the parent_run_id chain backwards through run-history.jsonl and prints the ancestor tree (oldest first). Each entry shows the terminal retrospective headline (truncated) so operators can see what each ancestor accomplished without switching to --json. Entries with usable inheritance snapshots are marked with [ctx]. If a parent reference points to a run that no longer exists in history, the chain terminates with a [broken link] sentinel. Combine with --json for machine-readable lineage output.

Use --status completed to see only successful runs. Use --limit 5 to see the last 5 runs.

decisions

agentxchain decisions [--json] [--all] [--show <DEC-NNN>] [--dir <path>]

Flag	Default	Description
--json	false	Output as JSON array
--all	false	Include overridden repo decisions instead of only active binding ones
--show <id>	—	Show one decision in detail
--dir <path>	.	Project directory

Shows repo-level decisions recorded in .agentxchain/repo-decisions.jsonl. These are the cross-run decisions that remain binding for future governed runs until explicitly overridden. The default view stays list-shaped, but it now surfaces the operator signals people actually need before drill-down:

• how many decisions are currently binding
• category spread for active decisions
• whether override history exists outside the current filtered view
• highest active decision authority when the config declares decision_authority

Text mode then prints one compact row per decision with status, category, statement, override lineage, origin role/run, and authority when it can be resolved truthfully from the current config.

Use --all when you need the historical override chain instead of only the active binding set. Use --show DEC-042 when you need the full decision record (rationale, phase, turn, supersession metadata, and authority detail).

--json remains array-shaped for automation. Each entry includes the recorded decision fields plus compact derived metadata such as binding_state, authority_level, and authority_source.

diff

agentxchain diff <left_ref> <right_ref> [--json] [--dir <path>]
agentxchain diff <left_export.json> <right_export.json> --export [--json]

Flag	Default	Description
--json	false	Output structured comparison JSON
--export	false	Compare two export artifacts instead of two run-history entries
--dir <path>	.	Project directory

By default, diff compares two recorded terminal runs from .agentxchain/run-history.jsonl. The command accepts full run IDs or unique prefixes; ambiguous prefixes fail closed instead of guessing. That matters because operators usually copy the first 10-12 characters from history, and silently resolving the wrong run would make the comparison useless.

Text mode starts with a Comparison Summary section before the detailed field deltas:

• Outcome: unchanged | improved | changed | regressed | mixed
• Risk: none | low | medium | high
• Highlights: up to three prioritized changes or regressions

The detailed sections still highlight the changed operator-facing fields instead of dumping raw JSON: status, trigger, template, connector, model, blocked reason, next action, retrospective headline, inheritance-snapshot availability, turns, decisions, cost, budget, duration, phases added/removed, roles added/removed, and per-gate status changes.

--export switches the command into artifact comparison mode. In that mode, the positional inputs are file paths to two exported audit artifacts, both artifacts must have the same export_kind, and the command compares normalized export summaries instead of raw embedded file blobs. Run exports surface run/status/phase/goal/dashboard/delegation/repo-decision drift; coordinator exports surface barrier, authority-first child repo-status, nested-export, and aggregated-event drift. When a nested child export is readable, repo-status comparison follows authority-first child repo status instead of stale coordinator linkage labels like linked / initialized, and summary.repo_run_statuses stays raw coordinator snapshot metadata only. JSON output preserves those raw coordinator linkage labels separately as coordinator_repo_statuses when you need to inspect both views.

Governance regression detection: when comparing two exports, the diff automatically detects semantic regressions — governance quality degradations, not just structural changes. Detected regressions include: status downgrades (completed → failed), phase regressions (backward movement in the workflow phase order, phase information lost, or explicit phase-order drift between exports), budget overruns (warn_mode or exhausted flipping to true), gate failures (a gate that was passed/approved becoming failed/blocked), decision override increases, delegation contract regressions (new missing_decision_ids on delegated work), and for coordinator exports: child repo status/export regressions, barrier count decreases, and event loss. Phase regression detection is powered by workflow_phase_order embedded in the export summary — the actual phase ordering from the project's routing config. Directional backward/forward inference only runs when both exports declare the same phase order; if the order itself changes, the diff emits an explicit warning and skips guessing. When both compared coordinator exports are already completed, child repo drift stays visible in the repo-change sections but does not count as a governance regression; terminal drift is observability, not a new operator action contract. In that terminal-only case, the Comparison Summary stays changed / low instead of regressed, and text mode does not append a Governance Regressions: section. Each regression is classified by category, severity (error or warning), and includes the specific field and values. In text mode, a Governance Regressions: section is appended when regressions exist. In JSON mode, the output includes regressions (array), regression_count, and has_regressions fields.

Use --json when you want automation to compare reruns, recoveries, continuation chains, or two portable export artifacts without scraping terminal output. JSON output includes the same top-level summary object (outcome, risk_level, highlights) rendered by the text-mode Comparison Summary.

events

agentxchain events [--follow] [--type <type>] [--since <timestamp>] [--json] [--limit <n>] [--dir <path>]

Flag	Default	Description
--follow, -f	false	Stream events as they occur (tail -f behavior)
--type <type>	—	Filter by event type (comma-separated)
--since <timestamp>	—	Show events after ISO-8601 timestamp
--json	false	Output raw JSONL
--limit <n>	50	Max events to show (0 = all)
--dir <path>	.	Project directory

Shows local lifecycle events from .agentxchain/events.jsonl for governed repos and coordinator workspaces. Events are emitted automatically during governed runs at key lifecycle transitions: run_started, phase_entered, turn_dispatched, turn_accepted, turn_rejected, turn_conflicted, conflict_resolved, acceptance_failed, turn_reissued, turn_stalled, turn_start_failed, runtime_spawn_failed, stdout_attach_failed, turn_checkpointed, coordinator_retry, coordinator_retry_projection_warning, run_blocked, run_completed, escalation_raised, escalation_resolved, gate_pending, gate_approved, gate_failed, budget_exceeded_warn, human_escalation_raised, human_escalation_resolved, dispatch_progress.

Use --follow to stream events in real-time as they occur. Use --type run_blocked,run_completed to filter by event type. Use --json for machine-readable output.

turn_conflicted text entries include the conflicting files, overlap percentage, detection count, accepted-since turn IDs, and run blocked when the run has exhausted conflict retries. That gives operators a first-glance CLI view of overlap severity without opening the dashboard or digging through .agentxchain/state.json.

conflict_resolved text entries show the conflicting files, the chosen resolution mode, and the overlap percentage that was resolved, so operators can verify that a human_merge completed without diffing state files manually.

turn_rejected text entries include the rejection reason inline and append the failed stage when it is known, so operators can see why a turn failed without cross-referencing .agentxchain/state.json.

coordinator_retry_projection_warning text entries show the affected workstream, repo, warning code, and that reconciliation is still required because immediate coordinator acceptance projection did not land. Use agentxchain events --type coordinator_retry_projection_warning when a targeted coordinator retry succeeded but you need to inspect the durable warning after the command exits.

turn_start_failed records the retained ghost-turn failure, while runtime_spawn_failed and stdout_attach_failed split the startup class: the subprocess never spawned vs the worker attached but no first-byte output channel materialized inside the startup watchdog window.

phase_entered text entries show the transition as from → to (trigger), where trigger distinguishes direct automatic gate passes, auto-approved policy transitions, and explicit human approvals. gate_failed text entries show the blocked transition plus the first failure reason and gate ID inline, so operators can diagnose a rejected phase change without digging into .agentxchain/decision-ledger.jsonl.

Unlike webhook notifications (configured in agentxchain.json), the event log requires no external infrastructure — events are written locally as part of normal governed operation.

chain

agentxchain chain latest [--json] [--dir <path>]
agentxchain chain list [--json] [--limit <n>] [--dir <path>]
agentxchain chain show <chain_id> [--json] [--dir <path>]

Flag	Default	Description
--json	false	Output as JSON
--limit <n>	20	Max chain reports to show (list only)
--dir <path>	.	Project directory

Inspect chain reports produced by agentxchain run --chain. When auto-chaining is enabled, each chain session writes a report to .agentxchain/reports/chain-*.json containing the chain ID, terminal reason, per-run lineage, inherited context summaries, and aggregate turn/duration totals.

• chain latest shows the most recent chain report with a per-run breakdown including run ID, status, provenance trigger, parent run ID, inherited context summary counts (roles, phases, decisions, turns), and duration.
• chain list shows a summary table of all chain reports sorted newest-first with chain ID, run count, total turns, terminal reason, duration, and start time.
• chain show <chain_id> renders the same detail view as latest for a specific chain report by ID.

Terminal reasons: chain_limit_reached (max chains exhausted), non_chainable_status (terminal status not in chain_on), operator_abort (SIGINT during chain), parent_validation_failed (parent run validation failed), completed, blocked.

dashboard

agentxchain dashboard [options]

Flag	Default	Description
--port <port>	3847	Port for the local bridge server
--daemon	false	Start the dashboard in the background and print the live PID + URL
--no-open	false	Do not auto-open the browser

Launches a local web dashboard with live updates via WebSocket plus a 60-second visible-tab heartbeat for time-based surfaces. The bridge binds locally to 127.0.0.1 and prints a http://localhost:<port> URL for convenience.

When --daemon is used, the dashboard writes .agentxchain-dashboard.pid and .agentxchain-dashboard.json in the project root after the bridge is actually listening. Stop the background dashboard with agentxchain stop.

agentxchain dashboard is the live current repo/workspace dashboard. It does not open an export artifact from disk. If you want the read-only dashboard for an existing artifact, use agentxchain replay export <export.json> instead. Keep the artifact boundaries explicit: audit inspects the live repo/workspace, report --input renders a derived document from an existing verified artifact, and replay export opens that existing artifact in the read-only dashboard.

That distinction survives partial coordinator artifacts. report --input keeps repo_ok_count / repo_error_count plus the failed repo row and error without inventing nested child sections. replay export keeps the same artifact readable in the dashboard, but restores a placeholder governed repo for the failed child path so coordinator layout validation still works. dashboard itself never reads the saved artifact; it reads the current local repo/workspace state.

The shipped dashboard surface has these top-level views:

View	Description
Initiative	First-glance multi-repo coordinator summary: authority-first child repo status, pending gate, blocked state, compact Cross-Run Constraints for decision-constrained barriers, barrier snapshot, and one primary recovery action; full blocker diagnostics stay in the Blockers view sourced from /api/coordinator/blockers
Cross-Repo	Coordinator event timeline across linked repos and workstreams, plus a live freshness banner showing websocket connection state, last dashboard refresh, and the last coordinator event seen
Timeline	Run timeline with continuity status, connector health, a conflict panel sourced from /api/events?type=turn_conflicted, active turns with live elapsed time, accepted history with per-turn duration and acceptance timestamp, a live freshness banner showing websocket connection state, last dashboard refresh, and the last repo-local run event seen, and expandable turn-level hook evidence; in coordinator workspaces the turn detail panel renders coordinator hook audit and annotations from /api/coordinator/hooks/audit and /api/coordinator/hooks/annotations alongside repo-local hook data
Delegations	Repo-local delegation visibility: live delegation_queue, pending delegation review, and completed delegation chains reconstructed from accepted history metadata
Decisions	Filterable decision ledger for governed turns; when repo-level cross-run decisions exist it also shows a compact carryover summary from /api/repo-decisions-summary, and in coordinator workspaces it renders the coordinator decision ledger from /api/coordinator/ledger instead of a false empty state
Hooks	Hook audit log plus persisted hook annotations; in coordinator workspaces it renders coordinator hook audit from /api/coordinator/hooks/audit and coordinator hook annotations from /api/coordinator/hooks/annotations alongside repo-local hook data
Notifications	Configured webhook targets plus recent delivery truth from /api/notifications — attempts, failures, timeouts, approval SLA reminder config, and newest-first rows from .agentxchain/notification-audit.jsonl
Blocked	Current blocked state, runtime guidance, ordered next actions, recent audit context, and the exact recovery command to run next
Gates	Pending phase-transition or completion review with aggregated evidence, an approve button, and the exact CLI fallback command
Blockers	Computed coordinator gate blockers from /api/coordinator/blockers — shows mode, gate context, blocker codes, ordered next actions, and repo_run_id_mismatch diagnostics with expected vs actual run_id values
Artifacts	Live workflow-kit artifact status for the current phase — path, required/optional, semantics, owner with resolution, and exists/missing status from /api/workflow-kit-artifacts
Mission	Repo-local single-repo hierarchy above chains from /api/missions and /api/plans — latest mission identity, goal, derived status, aggregate chain/run/turn counts, active repo-decision count, attached-chain lineage summaries, latest decomposition plan with per-workstream launch status and launch records, and newest-first recent missions without colliding with coordinator Initiative
Chain	Latest chain report plus recent chain sessions from /api/chain-reports — latest chain report summary, per-run lineage with status, provenance trigger, parent run id, and inherited-context summary, plus newest-first recent chain history
Run History	Cross-run history showing status, outcome, trigger, context inheritance availability, phases, turns, cost, duration, retrospective headline, and compact next: cues for follow-on/operator action from /api/run-history
Watch	Watch Mode intake audit from /api/watch-results — recent webhook, event-file, and event-directory results with route status, delivery ID, event/intent IDs, run/role details, deduplication state, and errors from .agentxchain/watch-results/*.json
Timeouts	Live timeout pressure and persisted timeout events from /api/timeouts — config summary, exceeded/warning indicators, per-turn identity for active turn pressure, and ledger event history
Coordinator Timeouts	Multi-repo timeout status from /api/coordinator/timeouts — aggregate repo counts, coordinator timeout events, and per-repo timeout config/live pressure/event history with child-turn identity, authority-first child repo status, and coordinator linkage/drift metadata

Dashboard Event API

The dashboard bridge server exposes a GET /api/events HTTP endpoint that serves the same events as the events CLI command, with query parameter filtering:

Parameter	Description
type	Comma-separated event types (e.g., turn_accepted,phase_entered)
since	ISO-8601 timestamp — only events after this
limit	Max events (default 50, from end of log; 0 = all)
run_id	Filter by run ID

WebSocket clients connected to /ws receive real-time event-data push messages alongside the existing invalidation messages:

{ "type": "event", "event": { "event_id": "evt_abc123", "event_type": "turn_accepted", ... } }

Clients can optionally send a subscribe message to filter which event types they receive:

{ "type": "subscribe", "event_types": ["turn_accepted", "phase_entered"] }

By default, all events are pushed to all connected clients.

The dashboard is not a general write surface. It supports exactly one authenticated mutation family: local gate approval over HTTP. Pending repo-local and coordinator gates can be approved in the Gates view, while the UI still shows the exact CLI fallback command for transparency:

• agentxchain approve-transition
• agentxchain approve-completion
• agentxchain multi approve-gate

The bridge issues a per-process local mutation token from GET /api/session, and gate approvals must send that token in X-AgentXchain-Token. This is a local anti-CSRF boundary, not a multi-user auth system.

The bridge also exposes GET /api/poll, a narrow heartbeat endpoint used by the browser shell. While the dashboard tab is visible, the shell calls it immediately on connect and then every 60 seconds so time-based dashboard surfaces stay truthful. Its only allowed side effect is lazy approval-SLA reminder evaluation; it does not mutate governed state.

For repo-local workspaces, the bridge also exposes GET /api/chain-reports. The Chain view reads newest-first chain reports from .agentxchain/reports/chain-*.json, renders the latest chain report at the top, and preserves per-run lineage details including provenance trigger, parent run id, and inherited-context summary counts so operators can audit chained continuation without opening raw JSON.

For repo-local workspaces, the bridge also exposes GET /api/missions. The Mission view reads .agentxchain/missions/*.json, joins them with attached chain reports plus repo-decision carryover counts, and shows the latest mission as the repo-local hierarchy above chain sessions. This surface is intentionally separate from coordinator Initiative: mission is single-repo long-horizon grouping, while initiative remains multi-repo coordination.

For repo-local workspaces, the bridge also exposes GET /api/plans (with optional ?mission=<id> filter). The Mission view reads .agentxchain/missions/plans/<mission_id>/*.json and renders the latest decomposition plan inline — including plan status, per-workstream launch status table, launch records with chain linkage, and previous plans. Plan file changes use recursive watching under missions/plans/ and invalidate both /api/plans and /api/missions.

For repo-local governed runs, the bridge also exposes GET /api/watch-results (with optional ?limit=<n> filter, where 0 means all). The Watch view reads .agentxchain/watch-results/*.json, skips malformed files while counting them as corrupt, and renders newest-first intake outcomes from agentxchain watch --listen, --event-file, and --event-dir: route status, GitHub delivery ID, event ID, intent ID, run/role details, deduplication state, and errors. File changes under watch-results/ invalidate /api/watch-results through the dashboard watcher.

For coordinator workspaces, the bridge also exposes GET /api/coordinator/blockers, a computed read-only endpoint that returns the active coordinator gate context plus ordered next actions for pending_gate, repo_run_id_mismatch, and multi resync drift cases. Those next actions derive from the same authority-first child repo status contract used by the coordinator repo rows, so coordinator linkage labels like linked / initialized stay detail metadata instead of silently changing blocker recovery guidance. Structured blockers such as repo_run_id_mismatch still include expected vs actual child run_id values. This exists so the dashboard can explain blocked multi-repo state without forcing operators to diff raw JSON files by hand or guess which recovery command comes next.

The bridge also exposes GET /api/coordinator/repo-status for dashboard repo rows. That endpoint resolves child repo .agentxchain/state.json as primary truth when available, then keeps coordinator linkage labels like linked and initialized as metadata instead of presenting them as repo status.

For repo-local governed runs, the shared Decisions view also reads GET /api/repo-decisions-summary so cross-run repo decisions surface first-glance binding, authority, and lineage signals without replacing the main turn-decision ledger.

For repo-local governed runs, the dashboard also exposes GET /api/notifications. The Notifications view reads current notifications.webhooks / notifications.approval_sla config plus recent .agentxchain/notification-audit.jsonl entries so operators can see delivery failures and timeout patterns without tailing the audit file manually. In replay mode this endpoint is intentionally live-only: it returns replay_mode: true with a short message instead of historical audit rows, because delivery attempts are operational telemetry rather than replay-actionable dashboard state.

For coordinator workspaces, the shared Decisions view also reads GET /api/coordinator/ledger so coordinator-level decisions remain visible in the dashboard instead of disappearing behind a repo-local-only ledger view.

For coordinator workspaces, the bridge also exposes GET /api/coordinator/timeouts, a computed read-only endpoint that aggregates timeout visibility across child repos. The Coordinator Timeouts view keeps the same authority-first child repo status contract as Initiative and Blocked: child repo status, phase, and run_id come from repo-local state when readable, while coordinator linkage remains detail metadata and expected run drift stays visible on the timeout card alongside timeout config/live pressure and coordinator ledger timeout events.

For coordinator workspaces, the bridge also exposes GET /api/coordinator/events, which merges lifecycle events from all child repos into a single time-ordered stream. Each event is tagged with a repo_id field identifying the source repo:

Parameter	Description
type	Comma-separated event types
since	ISO-8601 timestamp — only events after this
limit	Max events (default 100, from end; 0 = all)
repo_id	Filter to events from a single child repo

WebSocket clients also receive real-time coordinator_event messages when child repo events change:

{ "type": "coordinator_event", "repo_id": "api", "event": { "event_id": "evt_abc", "event_type": "turn_accepted", ... } }

Clients can include "coordinator_event" in their subscribe filter to receive only coordinator-aggregated events.

The dashboard app uses those websocket messages as a live observer surface, not just hidden transport. Timeline and Cross-Repo render a freshness banner showing whether the feed is live, stale, or disconnected, the last successful dashboard refresh time, and the latest relevant websocket event seen. Cross-Repo also refreshes itself on coordinator_event so child-repo progress becomes visible without manual reload archaeology.

For repo-local runs, the bridge also exposes GET /api/continuity, a computed read-only endpoint that mirrors the status --json continuity contract: checkpoint metadata, stale-checkpoint warning state, SESSION_RECOVERY.md presence, exact recommended continuity command, and checkpoint-drift state. The Timeline view renders that continuity panel directly instead of forcing operators back to the terminal.

For repo-local runs, the bridge also exposes GET /api/connectors, a computed read-only endpoint that mirrors the status --json connector_health contract for non-manual runtimes. The Timeline view renders that Connector Health panel directly instead of forcing operators to inspect .agentxchain/staging/ by hand.

Everything else remains CLI-only. The dashboard does not execute arbitrary commands and does not perform blocked-state recovery actions such as:

• agentxchain step --resume
• agentxchain resume --role ...

For repo-local runs, the Timeline, Decisions, Hooks, Blocked, Gates, and Artifacts views render governed runtime state from .agentxchain/ and agentxchain.json. If only coordinator state exists, the dashboard opens on Initiative first and uses the coordinator-specific views. Coordinator repo rows stay authority-first there too: child repo status/phase/run come from repo-local state when readable, while coordinator linkage remains detail metadata.

For repo-local runs with delegation chains, accepted turns now preserve delegations_issued, delegation_context, and delegation_review metadata in .agentxchain/history.jsonl. The Delegations view uses that additive history truth to reconstruct completed chains instead of pretending delegation visibility only exists while the queue is live.

Continuous delivery intake

intake

agentxchain intake <subcommand> [options]

The intake command family is the repo-native entrypoint for continuous governed delivery. It records signals under .agentxchain/intake/, turns them into governed intents, and then either starts repo-local governed execution or hands planned work into a coordinator workstream without bypassing human authority.

Subcommand	Purpose	Key contract
record	Record one delivery trigger event and create a detected intent	Accepts inline, file, or stdin payloads. Supported sources: manual, ci_failure, git_ref_change, schedule, vision_scan, vision_idle_expansion
triage	Turn a detected intent into governed work, or suppress/reject it	Sets priority, template, charter, and acceptance contract for real work
approve	Authorize a triaged or re-reviewed blocked intent for planning	Approval is an explicit gate. It does not start a governed run
plan	Materialize template-backed planning artifacts and move approved -> planned	Generates .planning/ artifacts and fails on conflicts unless --force is supplied
start	Hand one planned intent into the governed execution engine	This is the explicit planned -> executing bridge. It assigns a governed run and turn, records target_run and target_turn, and is not triggered automatically from raw signals
handoff	Link one planned intent to a coordinator workstream	Writes a run-bound handoff ref, records target_workstream.super_run_id, and leaves dispatch to explicit multi step
resolve	Read governed run or coordinator outcome back into intake state	Maps repo-local or coordinator-backed blocked, completed, and failed outcomes back onto the linked intent; active and paused remain no_change
scan	Ingest a deterministic source snapshot through the same event-recording path	Supported scan sources are ci_failure, git_ref_change, and schedule. manual is intentionally excluded
status	Inspect intake backlog summary or one intent in detail	Summary mode reports counts and recent intents; --intent shows the linked event and transition history

The command family is intentionally staged:

• record and scan ingest signals only
• approve authorizes but does not start execution
• plan prepares artifacts but does not start execution
• start creates repo-local governed execution for one planned intent by recording target_run and target_turn
• handoff creates coordinator-managed execution for one planned intent by recording target_workstream and its super_run_id
• resolve closes the loop by reading governed outcome state back into intake truth

Intake is repo-local. Run it inside a governed project rooted by agentxchain.json. If you are standing in a coordinator workspace rooted by agentxchain-multi.json, use multi there and run intake inside the child repo that owns the signal. handoff is explicit operator escalation, not automatic coordinator intake.

Use Continuous Delivery Intake for the full artifact layout, state-machine transitions, deduplication contract, and lifecycle details. The CLI reference should help you find the command family quickly, not become a second hand-maintained copy of the entire intake spec.

Plugin management

plugin

agentxchain plugin <subcommand> [options]

Subcommand	Description
install <source>	Install a plugin from a built-in short name, local directory, archive, or npm package
list	List all installed plugins with version and hook count
list-available	List built-in plugins available for installation
upgrade <name> [source]	Upgrade an installed plugin atomically, rolling back on failure
remove <name>	Remove an installed plugin and its hooks

plugin install flags

Flag	Description
--config <json>	Inline JSON plugin config validated against config_schema
--config-file <path>	Read plugin config JSON from a file
-j, --json	Output as JSON

--config and --config-file are mutually exclusive.

plugin list flags

Flag	Description
-j, --json	Output as JSON

plugin list-available flags

Flag	Description
-j, --json	Output as JSON

Built-in plugins can be installed by short name: agentxchain plugin install slack-notify.

plugin upgrade flags

Flag	Description
--config <json>	Inline JSON plugin config validated against config_schema
--config-file <path>	Read plugin config JSON from a file
-j, --json	Output as JSON

The optional [source] positional argument specifies a local directory, archive, or npm package to upgrade from. If omitted, the plugin is upgraded from its original source.

plugin remove flags

Flag	Description
-j, --json	Output as JSON

See Plugins for full details on authoring and managing plugins.

Multi-repo coordinator

multi

agentxchain multi <subcommand> [options]

The multi command family orchestrates governed runs across linked repositories. It requires an agentxchain-multi.json configuration at the workspace root that declares the repos, workstreams, routing, and coordination gates. See Multi-Repo Coordination for the full config contract and coordinator artifact layout.

Subcommand	Purpose	Flags
init	Bootstrap a coordinator run, link repo runs, and write initial coordinator state	--json
status	Show coordinator status: super-run state, elapsed time, blocked reason, repo-run snapshots, phase gates, and barriers	--json
step	Reconcile repo truth, select the next workstream, and dispatch a coordinator turn	--json
resume	Clear a blocked coordinator after the operator fixes the cause and restore the next truthful status	--json
approve-gate	Approve a pending phase transition or completion gate across the coordinated run	--json
resync	Detect divergence between coordinator state and repo authority, and rebuild if needed	--json, --dry-run

The typical coordinator flow is:

1. multi init — reads agentxchain-multi.json, initializes or links repo-level governed runs, and writes coordinator state
2. multi step — checks for divergence first, auto-resyncs from repo authority when safe, then selects the next workstream assignment, dispatches a coordinator turn, and fires hooks
3. multi resume — after the operator fixes a blocked coordinator cause, this command runs a resync and restores coordinator status to active or paused
4. multi approve-gate — when a gate is pending (phase transition or completion), the human approves it through this command
5. multi resync — explicit divergence rebuild from repo authority. Use --dry-run to detect divergence without modifying state.

multi resync and multi resume are not interchangeable:

• multi resync reconciles coordinator state with repo truth
• multi resume is the blocked-state recovery command after the operator resolves the cause

If multi resume restores the coordinator to active, it prints agentxchain multi step as the next action. If it restores to paused with a coherent pending_gate, it prints the same canonical Pending Gate detail rows used by multi status (Type, Gate, Current Phase, Target Phase, Required Repos, Approval State, and Human Barriers when present) before the ordered next actions.

multi status renders coordinator observability with the same depth as single-repo status: elapsed time for active runs, blocked reason with ordered recovery guidance when the coordinator is blocked, canonical Pending Gate detail rows (Type, Gate, Current Phase, Target Phase, Required Repos, Approval State, and Human Barriers when present), phase gate pass/pending status, and a completion marker with timestamp when the run finishes. Its repo rows are authority-first when coordinator config is readable: they show repo-authority status/phase/run first, then relegate coordinator linkage bookkeeping to metadata such as coordinator: initialized or coordinator: linked. That means raw coordinator labels like linked / initialized no longer masquerade as the repo's primary status, and run-identity drift can show the actual repo run plus expected run directly in the row. If multi step is run while a coordinator gate is already pending, it fails closed and prints the same canonical Pending Gate detail rows before the ordered next actions instead of collapsing the gate to a one-line name. If multi step reaches gate evaluation with no assignable workstream, it prints the gate blocker list after the assignment failure; typed run-identity blockers, when they appear, reuse the same canonical Repo, Expected, and Actual detail labels as the dashboard and resync surfaces instead of private lowercase rows. multi resync --dry-run prints typed mismatch rows for coordinator/repo drift, and run-identity drift uses the same canonical Repo, Expected, and Actual detail labels as the dashboard blocker surfaces instead of private ad hoc formatting. A successful multi resync prints the preserved Pending Gate detail rows when applicable and then the ordered next actions for the post-resync state; a blocked multi resync prints the same typed mismatch rows plus the ordered recovery next actions. Successful multi approve-gate follows the same operator-handoff contract as the dashboard gate action: phase-transition approvals print the success message plus ordered next actions (typically agentxchain multi step), while run-completion approvals stop at the completion message and do not invent a synthetic follow-up command. In --json mode, multi status, multi resume, successful multi approve-gate, and multi resync all expose next_action/next_actions alongside their command-specific state fields.

The dashboard Initiative and Cross-Repo views visualize coordinator state. When only coordinator state exists (no repo-local run), the dashboard opens on Initiative first.

Common sequences

Manual planning turn

# 1. Start the PM turn
agentxchain step --role pm

# 2. Human writes PM_SIGNOFF.md, ROADMAP.md, stages turn result
#    (work happens outside the CLI)

# 3. step detects the staged result, validates it, and auto-accepts it
#    If the PM requested implementation, the run pauses on planning_signoff

# 4. Human approves the pending phase transition gate
agentxchain approve-transition

Recover a conflicted turn

# 1. Check what went wrong
agentxchain status --json

# 2. If the turn is conflicted, choose an explicit resolution path

# Option A: reject and immediately re-dispatch with conflict context
agentxchain reject-turn --turn <turn_id> --reassign

# Option B: accept the current staged result as the authoritative merge in one command
agentxchain accept-turn --turn <turn_id> --resolution human_merge

Continue after a retained failed turn

# 1. A step failed validation — turn is retained with status: failed
agentxchain status
# Output: Turn turn_abc123 — status: failed (retained), reason: missing objections

# 2. Fix the staged result
#    Edit .agentxchain/staging/<turn_id>/turn-result.json to add objections

# 3. Re-validate
agentxchain validate --mode turn

# 4. Accept the fixed turn
agentxchain accept-turn