ak orchestrate

Coordinate and inspect agent jobs. External process supervision is Darwin-only; observation and runtime discovery do not claim process-control support.

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.

External process supervision in ak orchestrate v1 supports Darwin only (macOS). start, resume, and stop return exit code 6 on every other GOOS. Plan commands that spawn CLI jobs require Darwin for that dispatch; failures from those commands map to exit code 1, not 6. Historical observation (events, output, diagnose) and runtime discovery (probe) do not claim process-control support. Callers on Linux or Windows should not treat those read paths as proof that jobs can be supervised on that 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).