ak orchestrate

Coordinate and inspect agent jobs. Only external process supervision is Darwin-only; plan commands and in-session internal jobs work on every platform.

Use ak orchestrate to start, resume, check, and stop a graph of external CLI jobs, and to inspect durable events, redacted output, and installed runtimes. The worker owns each job's process group, persists durable run state under AGENTKIT_HOME, and survives the launching client or coordinator exiting. This is the process-lifecycle and observation layer that the /ak:orchestrate skill delegates to when supervising CLI job graphs.

Only external process supervision in ak orchestrate requires Darwin (macOS). probe, prepare, advance, accept, and plan-status work on every platform, and so do in-session runtime: internal jobs. Off Darwin, start, status, resume, and stop return the unsupported-platform exit code; advance reports an unsupported platform for a supervised CLI or Pi job and leaves it uncertain; and a job with executable verification: checks stays awaiting-accept. events, output, and diagnose read only runs recorded on a supervising host, so they are not proof that jobs can be supervised on the current host.

Usage

ak orchestrate

The bare group command prints help. Use one of the subcommands to act on a run.

Choose an orchestrate subcommand

Goal	Command	Effect
Launch a new run from a validated job graph	`ak orchestrate start <job-graph.json>`	Validates the graph, generates a fresh opaque run ID, spawns a detached worker that owns every job's process group, blocks until the worker durably persists run state and proves readiness, then prints the run ID and initial status. Darwin only.
Reconnect after a client or coordinator crash	`ak orchestrate resume <run-id> <job-graph.json>`	Confirms the graph's digest still matches the running record and reports its current state — never relaunches jobs or creates a second process tree. Falls back to read-only reclassification when the worker itself crashed.
Report a run's current lifecycle state	`ak orchestrate status <run-id>`	Reaches the run's live worker through its verified control socket when reachable, otherwise reconciles persisted state against a fresh identity probe. Reports PID/PGID, heartbeat, last-output time, and per-job current-command labels.
Cancel a run's live jobs	`ak orchestrate stop <run-id>`	Sends SIGTERM to every signal-authorized job in the verified process group, waits a bounded grace period, then SIGKILLs only a job whose group is still alive under the same verified identity. Never guesses a kill target from persisted state. Darwin only.
Page durable run events	`ak orchestrate events <run-id>`	Read-only replay of persisted observations. `--after` is the sequence cursor (default `0`); `--limit` is `1`–`1000` (default `100`). Missing or truncated observations are not proof of progress.
Page redacted job output	`ak orchestrate output <run-id> <job-id>`	Read-only bounded capture by `--offset` (default `0`) and a `--limit` byte target (`1`–`65536`, default `16384`). A page can end early or run over to keep a released secret value whole; follow `next_offset`. Does not open private invocation files.
Export a diagnosis bundle	`ak orchestrate diagnose <run-id>`	Read-only redacted snapshot plus a bounded event/output budget. Redirect `--json` to save it. Never a substitute for private graph or job-spec files.
Discover installed coding runtimes	`ak orchestrate probe`	Runs version/help only, optional `--path runtime=executable`, `--runtime` filter, `--refresh`, `--timeout` (default `10s`, max `30s`). Writes an owned metadata cache. Does not install runtimes, read credentials, prove authentication, or invoke inference.
Persist a resolved plan	`ak orchestrate prepare <jobs.yaml> <run-dir>`	Validates and writes private plan state. CLI dispatch that follows requires Darwin; internal harness dispatch does not.
Dispatch dependency-ready jobs	`ak orchestrate advance <run-dir>`	Reconciles attempts and may copy declared artifacts and spawn CLI jobs. Do not bypass an uncertain attempt by calling `start` manually.
Accept a settled attempt	`ak orchestrate accept <run-dir> <job-id> --attempt <id> --result <receipt.json>`	Verifies one attempt's artifact receipt. Mutating.
Inspect plan state	`ak orchestrate plan-status <run-dir>`	Inspects persisted plan state and may invalidate stale evidence.

Filesystem and privacy boundary

Each run writes private state, bounded redacted logs, events, and a launch graph under AGENTKIT_HOME/orchestrate/runs/<run-id>/. The launch graph retains argv and environment for recovery. Keep credentials out of job specs. Do not export invocation files or graph.json in diagnostic bundles; use ak orchestrate diagnose <run-id> --json instead. Bounded stdout/stderr capture is redacted and reports truncation. Values that the secrets vault released are replaced with [redacted:secret:<NAME>] markers.

The launch graph digest is bound to the run ID at start. resume verifies this digest against the graph file supplied to it; a mismatch is refused with exit code 1 rather than silently continuing under a different graph.

Job graph shape

The graph file is a JSON document listing jobs by id, command, args, work_dir, env, and depends_on. Full schema and validation rules live under the /ak:orchestrate skill's job specification; this reference page covers only the ak orchestrate binary's process-lifecycle semantics.

Output modes

Mode	Trigger
`pretty`	Default on a TTY (colors, ASCII markers).
`plain`	Auto when stdout is piped or `--no-interactive` is set.
`json`	`--json` (single-object envelope, NDJSON-safe).

Shared flags (--json, --no-interactive, --quiet, --verbose, --yes) are described in CLI conventions. --json implies --no-interactive.

Exit behavior

Exit	Meaning
`0`	The requested subcommand succeeded.
`1`	Runtime error (state I/O, launch failure, signal failure, graph digest mismatch, run not found, corrupt state).
`2`	Flag parsing failed.
`3`	User cancelled (SIGINT, prompt-cancel).
`6`	Unsupported platform (v1 requires Darwin).