ak orchestrate stop

Terminate an orchestrated run's live jobs with SIGTERM, a bounded grace period, then SIGKILL — always against a verified worker identity, never guessed from a stale persisted PID.

Use ak orchestrate stop to send SIGTERM to every signal-authorized job in the run's verified process group through the worker's control socket, wait a bounded grace period, then SIGKILL only a job whose group is still alive under the same verified identity. If no live, verified worker is reachable, the command reports that instead of guessing a kill target.

Stop never falls back to signalling from a persisted PID alone. A reused OS PID from a different process is not a valid kill target; the command refuses to signal one and asks the operator to investigate instead.

Usage

ak orchestrate stop <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. Stop honors --yes and --no-interactive for scripted cancellation; the shutdown sequence itself does not prompt.

Shutdown sequence

Verify the worker. Contact the run's control socket and confirm the worker's identity matches the one recorded at start.
SIGTERM the process group. Every signal-authorized job in the verified group receives SIGTERM.
Wait the grace period. The worker gives each job a bounded time to exit cleanly.
SIGKILL survivors. Only a job whose group is still alive under the same verified identity receives SIGKILL.
Persist the outcome. The stop request and its per-job result are written to the run's state file.

If step 1 fails — for example, the worker itself crashed — no signals are sent. Stop reports the unreachable worker and exits 1 rather than signalling a persisted PID that may now belong to a different process.

Filesystem effects

Persists the stop request and its outcome to the run's state file. Does not delete run state, output-<job-id>.log, events.jsonl, or graph.json; those remain for inspection.

Human and JSON output

--json wraps a runVM as kind: "orchestrate.stop" with the shared success envelope (schema_version 1, kind, data):

{
  "schema_version": 1,
  "kind": "orchestrate.stop",
  "data": {
    "run_id": "<opaque>",
    "status": "<run-status>",
    "all_settled": true,
    "revision": 0,
    "events_truncated": false,
    "status_counts": { "failed": 1 },
    "jobs": [
      {
        "job_id": "<job-id>",
        "status": "failed",
        "route_source": "declared-in-graph",
        "terminated_by": "<signal>",
        "output_bytes": 0,
        "output_truncated": false
      }
    ]
  }
}

Do not parse a top-level action, worker_state, signalled, killed, or survived array. Per-job outcome is data.jobs[].status and terminated_by.

Exit behavior

Exit	Meaning	Safe next step
`0`	Every reachable, signal-authorized job was terminated.	Run `ak orchestrate status <run-id>` to verify.
`1`	No live, verified worker was reachable, or a stop step failed.	Investigate; do not force-signal a persisted PID by hand.
`2`	Flag parsing failed.	Correct the flags.
`3`	User cancelled during the shutdown request.	Re-run stop when ready.
`6`	Platform unsupported.	Non-Darwin has no persisted worker to stop.