ak orchestrate status

Report an orchestrated run's current lifecycle state through the verified control socket, falling back to fresh identity probes rather than trusting a stale record as still running.

Use ak orchestrate status to report a run's current lifecycle state. The command reaches the run's live worker through its verified control socket when reachable; otherwise it reconciles persisted state against a fresh identity probe. A stale record alone is never reported as still running.

Usage

ak orchestrate status <run-id>

Supply exactly one positional argument — the run ID printed by ak orchestrate start.

Command flags

Shared flags (--json, --no-interactive, --quiet, --verbose, --yes) are described in CLI conventions. --json returns a single-object envelope safe for scripted polling.

Reported fields

For each job the command reports:

State — queued, running, completed, failed, orphaned, or unknown.
PID / PGID — the verified identity when the worker is reachable.
Heartbeat — the last time the worker reported activity for the job.
Last output time — the last write to output-<job-id>.log.
Current command label — the graph-declared label the worker was running when the state was recorded.

A job whose original worker died mid-run is reported as orphaned, not running. Trusting a persisted PID without a fresh identity probe would risk reporting a reused OS PID from a different process as still supervised work; the command explicitly refuses to do that.

Filesystem effects

Read-only, with one exception: a fresh reclassification (for example, the worker crashed since the last check) is persisted so subsequent commands see the same reality.

Human and JSON output

--json wraps a runVM as kind: "orchestrate.status":

{
  "schema_version": 1,
  "kind": "orchestrate.status",
  "data": {
    "run_id": "<opaque>",
    "status": "<run-status>",
    "all_settled": false,
    "revision": 0,
    "events_truncated": false,
    "status_counts": { "running": 1 },
    "jobs": [
      {
        "job_id": "<job-id>",
        "status": "running",
        "route_source": "declared-in-graph",
        "pid": 12345,
        "pgid": 12345,
        "heartbeat": "<rfc3339>",
        "last_output_at": "<rfc3339>",
        "command_label": "<graph-label>",
        "output_bytes": 0,
        "output_truncated": false
      }
    ]
  }
}

Do not parse a top-level action, worker_state, or job id/state pair. Human output prints one job per row from the same runVM.

Exit behavior

Exit	Meaning	Safe next step
`0`	Status was reported successfully.	Consume `data.status` and per-job `status`; do not infer `running` from a `pid` alone.
`1`	Run ID not found or run state corrupt/unsupported.	Do not retry the same input; investigate the persisted record.
`2`	Flag parsing failed.	Correct the flags.
`3`	Interrupted.	Re-run status.
`6`	Platform unsupported.	Non-Darwin has no persisted worker to query.