Oko
Oko/Docs

Command reference

oko sessions supervision

The standing Stado pass settles stalled calls and stopped turns, then decides the executor count and model mix from observed subscription capacity, independent checkout work, measured repair throughput and overload. It retains both actions and refusals.

Invocation#

Command
oko sessions supervision [plan|run] [--socket PATH] [--json]

Inputs and options#

  • With no verb, reads the last retained receipt in ~/.oko/supervision-pass.json. plan reads the live broker sessions, Brama subscription pool and leases, open unrepaired defects per checkout and the cited scorecard; it changes no session. run invokes the same model policy pass that `oko sessions waits settle` uses and acts on that pass's capacity decision.
  • Start with `oko sessions role set SUPERVISOR supervisor --by WHO` for the supervising session, and record product defects through `oko defects record`. For example, `oko sessions supervision plan --json` shows which independent checkout has claimable work, the free subscription slots and the measured models before `oko sessions supervision run --json` makes a pass. The installed standing routine invokes the same run on Stado's schedule; no operator polling is required.
  • A model is eligible only with cited scorecard `defects_repaired`, `repair_success_rate` and repair-duration observations. Brama supplies usable members, their lease counts and the operator-declared limit per subscription; Oko invents no executor quota. An unmeasured model is not silently selected. Starts also require a measured baseline for model-only turns: without one, missing overload names the failed measurement and the decision is undecided rather than treating load as healthy. A stalled call past its measured norm prevents starts.
  • A start requires reconciled Stado compiler receipts and source-backed repair credits. The scorecard must have a measured commit denominator, no unread build or unresolved attribution, and readable claim and completion evidence. The model mix ranks charged standing (verified repair points minus distinct broken commits) first, then lower broken-commit rate, then measured throughput and success. Each selected model carries its verified repairs, factor sources, standing, rate and blamed commits in measured. No source or denominator means no start, not an assumed clean history.

Output and state effect#

  • plan prints {decidedAt, decision, executors, wanted, start, retire, reason, missing, streams, free, stalled}. Streams identify product defects, unowned work, defects assigned to observed stopped executors with no process, and live executors in the checkout. Free identifies usable subscriptions, carried leases and remaining slots per provider. Each start names its model and provider, count and source-cited repair throughput and success. The wanted count is independently claimable product streams bounded by live executors and free Brama slots; a missing input makes the decision undecided with its cause.
  • Even when the live count equals the wanted count, a stopped duplicate or idle executor can be retired to make room for claimable work in another checkout. Its owed work and process state are rechecked before the role is cleared; a refusal stays on the pass instead of moving a live executor.
  • Each overloaded session names its observed cause in stalled[].reason: the running tool and measured norm, model-only turns above the measured fleet norm, or the registered open wait. The CLI line and Desktop card show that reason rather than a generic stalled badge.
  • run first retains the model policy's wait, stall and stopped-turn decisions. Stopped executors receive their own open defect, then atomically claim unowned work, then an owed task linked to an open defect. With no such work, a fresh successor audits a repaired defect in the same checkout, comparing revision, tests, docs and changelog, and records its intervention on that defect. It then starts a fresh broker executor for each eligible independent checkout, assigns its defect atomically after its role is recorded, and records an intervention. A stopped executor with no owed task or owned defect can be retired only after its process has ended; a pending termination retains its role. The receipt in ~/.oko/supervision-pass.json carries policy, capacity, actions and refusals. Oko Desktop → Work → Sessions → Agent sessions shows the same receipt, plan, source evidence, overload and refusals, and offers Plan and Run through the native API.
  • A successor, whether it audits a repaired defect or takes over a stopped executor's work, starts in the harness that continues the executor's runtime (continuingRuntimes in handover.json), the same one `oko sessions resume` continues it in: an OMP executor's successor runs on Jeden, and only `oko sessions start --harness omp` still starts a new OMP session. `oko sessions agents` then lists the successor with runtime jeden.

Refusals and safe exits#

  • A verb other than plan or run, or an unsupported option, exits 2 with the accepted syntax. Without a retained pass the read names its absent path. A missing or ambiguous recorded supervisor refuses assignment and preserves the cause in supervisorRefused.
  • Brama's failed endpoint, HTTP status, malformed response or unstated provider limit leaves `free` missing with its cause. An unreadable defect register, or a defect assigned to an owner absent from the observed session inventory or lacking process/alive observations, leaves `work` missing and names that owner and failed observation; it never hides the assigned stream as idle. Missing cited repair throughput or success for the required model mix leaves `measured` missing. A scorecard without a completed model-only baseline leaves `overload` missing. The capacity decision is undecided, never a guessed count. An unknown checkout or shortage of claimable defects refuses a proposed start and is retained as capacityRefused.
  • Unreadable compiler receipts, unresolved source blame or transcript attribution, unreadable credit inputs, and a model without measured commits leave `measured` missing with their exact causes. Reported repair throughput alone cannot mask a history of broken main; unsupported repair claims earn no credits.
  • Each start or retirement refusal appears in actions and refusals with the defect or session. Before a replacement claims a defect assigned to a stopped executor, the routine rereads process holders and the broker, verifies that the recorded executor has no process, and atomically compares the old owner under the defect register lock. A missing observation, a revived owner or a concurrent assignment refuses the replacement and ends its newly started terminal. A retirement with owed work is refused, not silently removed. A ruling that prohibits the prompt refuses the start before delivery. A policy-pass failure is retained as policyRefused and no capacity action follows.
  • The real CLI journey under tests/supervision/ uses a live broker, Brama and registered work to inspect a retained pass and its external state; until it runs against the built revision, the source change is not a verified product outcome.

CLI reference#