Oko
Oko/Docs

Command reference

oko tasks health

What the handover is doing right now, on one screen: every session that owes the operator something — its open tasks, when it last wrote, whether it is working, held by somebody's own window, refused by the model, has answered exactly its list or is due again, how many of its tasks are being diagnosed or blocked — with the totals, the model's refusal when it refuses everyone, and the last control pass with its failures, its stages and the stage it still stands on.

Invocation#

Command
oko tasks health [--session ID ...] [--hours N] [--json]

Inputs and options#

  • --session, repeatable, or --hours for every session touched in the window; with neither, every live session on this machine. --json prints the one document instead of lines.

Output and state effect#

  • Reads only; nothing is written, and Stado is not asked: the fleet's verdicts are read again by the control pass's qualification stage, not by this read.
  • It reads only what it shows. Without --session, only the sessions the shared register holds a reading or an addition for are settled, since no other session holds a task; no handover message, operator history or working directory is built; each transcript is read backwards from its end until its newest prompt, so the turns before it are not read; the last pass is read for `at`, `failures`, `stage` and `stages`, not its whole record.
  • For a person, each owing session is printed on its own line as soon as it is read — `<session> <state> open N diagnosing N blocked N silent Ns last write <time>`, with `refused <status>: <sentence>` when the model refused it, the state being one of refused, working, attended, answered or waiting — and after the last one the totals (`N session(s) owe M open task(s): …`), the automatic route's newest refusal when every observed owing session has a refusal, and `last control pass <time>, stage <stage>` with the stage it still stands on and each failure. Silence never removes a session from this aggregate: an observation without a refusal prevents a fleet-wide refusal claim regardless of transcript age. With --json the same data is one document at the end, which Oko Desktop reads through the native API.
  • `lastPass` is when the newest pass began, `lastPassStage` the stage it is at (`done` once every stage ended, `failed` when one ended in the pass's own failure, else the stage it stands on), `lastPassStages` every stage with its `standing`, `startedAt` and `endedAt`, and `standing` the stage the pass still stands on with `since` and what it stands on, or null once it finished; `failures` are the newest pass's failures.
  • Working includes an actual broker-owned worker between writes and after an answer while maintenance runs, until the broker observes its process completion. An observed external writer also retains ownership regardless of transcript answer records. If a parallel newest-turn reader panics, the refusal names its session and transcript path and retains the string panic payload; a non-string payload is identified as such with its actual type identity. Neither observation failure is an idle or healthy result. CLI and the native Tasks response carry the same refusal for Desktop presentation.
  • The real health_stream qualification includes quiet_nonrefused_session_prevents_a_fleet_wide_provider_refusal. Declare OKO_TEST_SOURCE_REVISION, OKO_TEST_REFUSED_SESSION (an isolated genuine automatic-route refusal still owing work) and OKO_TEST_UNREFUSED_SESSION (a different retained quiet session owing work without a refusal). Run `cargo test --manifest-path rust/Cargo.toml --test health_stream quiet_nonrefused_session_prevents_a_fleet_wide_provider_refusal -- --ignored --nocapture`. It reads the refused session alone, then both sessions through CLI and the native Tasks API, requires the aggregate to disappear without losing the per-session cause, and verifies that the persisted transcripts remain unchanged. The candidate revision, source patch, binary digest, command statuses and native exchanges are retained; missing or changed real fixtures fail rather than substitute provider replies.
  • The health_prints_each_owing_session_before_the_totals journey also requires OKO_TEST_SOURCE_REVISION and a clean matching candidate. It creates its own real session and task, reads health to populate the observation cache, temporarily withholds only that session's transcript, and requires CLI and native health reads to refuse the named missing session with its identity and searched locations rather than report no owing work. It restores the transcript before assertions and records restoration failure separately from a transport failure or panic. The original transcript bytes must remain unchanged. This registered health_stream case does not simulate a transcript or a provider.
  • A retained continuation keeps ownership of the work even when its transcript disappears. Health and handover reads refuse `cannot inspect continuation transcript <path> for session <id>: <OS cause>` instead of returning to the original session's older transcript. Only a session with no recorded continuation uses its original transcript; a metadata check alone does not establish that the runtime is idle.
  • The separate missing_continuation_preserves_ownership_and_refuses case requires OKO_TEST_SOURCE_REVISION, OKO_TEST_CONTINUED_SESSION and OKO_TEST_CONTINUATION_WORKSPACE. Supply a genuine settled handoff fixture in a dedicated directory under the checkout's .build; the journey refuses an original-only transcript, a workspace outside that isolated tree, or observed live writers. It reads the actual retained handoff and native protocol, withholds only the registered continuation, requires CLI/native health and handover to retain the continuation path, session and actual OS cause, restores the transcript, and verifies that ownership still selects the same continuation and that the original bytes did not change. This case consumes a real prepared fixture; it does not create a handoff.
  • Native qualification reports preserve the initiating transport, read or decode failure even when writing that failure report also fails. Cleanup records the actual service stop error, observed exit or child-wait error. An unobserved child exit fails qualification; an unwritable cleanup report also fails qualification, or prints its secondary cause while an earlier failure is already unwinding instead of aborting through a second panic. Inspect the test process result together with report.json and retained output: a previously written passed report alone does not prove successful cleanup.
  • Before the native service starts, preparation failures name the directory, source.patch, candidate executable or stderr.log operation and its actual filesystem cause. Git revision and patch failures distinguish process-start errors from nonzero exit status and preserve Git stderr. Such a preparation failure is not a product behavior verdict; repair the named prerequisite and run the actual journey again.

Refusals and safe exits#

  • `oko tasks health: --hours takes a whole number, got <value>` (exit 2), before anything is read; the shared database refusals; `PTY broker at <socket> is not answering: <cause>` when the Oko service's broker does not answer.
  • An unreadable writer parent refuses with `cannot inspect parent of transcript writer <pid>` and the failed /bin/ps launch, exit status and stderr, or actual malformed parent-id output. The same ownership observation protects the control pass; an inspection failure never becomes an invented parent id or permission to continue the session.
  • Transcript metadata failures refuse as `cannot inspect transcript <path>: <OS cause>` or `cannot read transcript modification time <path>: <OS cause>` through the CLI and native health API. An existing cached turn does not turn an uninspectable transcript into an observed session. These diagnostics do not establish that a parsed transcript is runtime-idle.
  • A named session whose transcript cannot be located refuses with `no live transcript of session <id> on this machine; looked in <declared locations>`. It is not silently dropped from the requested scope or reported as owing nothing.

CLI reference#