Oko
Oko/Docs

Command reference

oko routines inspect

Reads Stado's actual job state and verifies its canonical Oko result.

Invocation#

Command
oko routines inspect JOB_ID [--json]

Inputs and options#

  • A job ID from a scheduled occurrence or manual submission.
  • HOME must be nonempty and absolute so Oko can locate the installed ~/.stado/bin/stado. An unset, empty or relative HOME is refused with the observed resolution cause; Oko does not search the current directory for a substitute executable.

Output and state effect#

  • Terminal jobs download canonical artifacts under ~/.oko/routines/results/<job-id>. Oko checks Stado's returned job and output directory, requires exactly one routine-result.json inventory entry, and verifies the bytes it reads against that entry's size and SHA-256 before decoding the receipt's job and definition identity. The JSON is decoded from the same bytes that were hashed, not from a second file read.
  • Shows context source states/documents, the autonomy disposition and accepted Pursuit receipt, or the control pass (deliveries proved, started or refused, sessions working, answered and judged); process completion alone is not Oko success.
  • Run `cargo test --manifest-path rust/Cargo.toml --test routines-inspection -- --ignored --nocapture`. Supply OKO_TEST_SOURCE_REVISION, OKO_TEST_ROUTINE_JOB for a genuine completed routine with a retained matching receipt, and OKO_TEST_ROUTINE_ARTIFACT_FAILURE_JOB for a distinct completed routine whose real artifact download fails. The journey compares actual Stado failures with Oko's CLI output, checks a generated absent job identity without creating it, and retains source/binary/test hashes, commands, exit statuses and output under .build/routines/inspection. It never creates or modifies a schedule or manufactures a receipt.
  • The same target requires OKO_TEST_NON_ROUTINE_JOB for a genuine completed Stado job that does not run an Oko routine. It checks the actual CLI refusal against that job's recorded command, then reads the job again to confirm its identity, command and terminal state remain unchanged.
  • Malformed-identity cases exercise the real CLI with the child HOME unset, so their input refusal must precede provider executable resolution. They retain the supplied identity and accepted syntax, without creating a job.

Refusals and safe exits#

  • Malformed job identity fails before Stado is called, naming the supplied value and accepted syntax: job- followed by ASCII letters, digits, underscores or hyphens. A status response for another job names both the returned and requested identities. A job whose command is not an Oko routine is refused with its actual job ID and recorded command; it is not confused with a missing receipt. Missing or mismatched output remains artifactError; JSON inspection retains that report, while plain inspection also exits unsuccessfully. Failed jobs retain Stado's actual error.
  • Machine status and artifact failures are read from Stado's stdout envelope before its result is decoded. The refusal names the exact operation, observed exit status, error code, message and retryable flag, plus any stderr. An unreadable envelope retains its parser cause; ok=false without an error and ok=true without a result are distinct protocol refusals. No retry or substitute job is selected.
  • A downloaded receipt failure names its full local path and actual file, JSON or definition-decoding cause. A missing jobID, another job's receipt, an absent definition and a definition differing from Stado's recorded command are separate refusals. Missing receipt evidence does not claim that the routine never executed.
  • A returned output directory differing from the requested resolved directory, a duplicate receipt entry, a byte-count mismatch and a SHA-256 mismatch are distinct artifactError causes. Directory failures retain the path and OS cause; content mismatches name the receipt path and both observed and reported values. Unverified bytes never become a routine result.
  • Oko Desktop → Automation → Recurring work → Inspect result uses the same inspection operation. Starting another inspection clears that job's previous result; a failed status read retains its cause instead of leaving an older successful receipt on screen. Artifact failures are shown with their full cause beside the job.

CLI reference#