Command reference
oko sessions waits
The wait watch: a tool call that waits on something that will not answer by itself is acted on by what it waits on, at once, and every such occurrence is counted on one class defect — no person watching a screen.
Invocation#
oko sessions waits settle [--hours N] [--socket PATH] | class [set DEFECT --by WHO | clear]Inputs and options#
- The waits are the ones every session's processes stand in, as `oko sessions agents` reads them: Stado's register of open waits (`stado waits`) and the wait lines of the tool output. Each carries its kind; three kinds are waits nothing answers by itself: `terminal` (a key or line typed on the terminal the program runs on), `zgoda` (the operator's answer to a grant) and `sesja` (another agent session's work). A program that knows of such a wait it does not perform registers it for the waiting process with `stado waits open --kind … --what … --where … --pid …`.
- settle runs the watch once over the sessions the model policy reads (every live one, every one with a role, and with --hours every one written in the window). The model policy pass (`oko sessions policy run`, and Oko's service on its cron) runs the same watch every pass and keeps what it did under `waits` in its receipt.
- class with no verb shows the declared class defect; `class set DEFECT --by WHO` declares an open registered defect the class every settled wait is counted on, kept in `wait-class.json` in Oko's directory (OKO_WAIT_CLASS moves it); `class clear` removes the declaration. No defect is named in code.
Output and state effect#
- terminal: the call is interrupted in its broker terminal (Escape, as `oko sessions interrupt`) and the session is told, as a submitted message, which program waited at its terminal and where, so it runs the form of it that asks nothing.
- sesja: the call is interrupted and the session is told that the session it waited on does not answer within its turn, so it takes its next open item.
- zgoda: the wait's `what` is the grant's ruling subject (`build` or `build:<product>`). When `oko admit` allows it on a standing ruling, the dialog is answered with Return in the session's broker terminal and the settlement names the ruling and the operator's words. Any other grant is refused like the other waits: the call is interrupted and the session is told `Oko: the grant <subject> this call asked for was refused and the call interrupted: <why>. Do not ask for it again; take the work that needs no grant.`, where <why> is the admission's own reason (no ruling stands, a newer withdrawal, open work held) or that the subject is not one rulings decide; a session outside the broker has its call's processes ended as below. Only a grant a ruling allows for a session outside the broker is left, with the settlement saying so.
- A session outside Oko's broker cannot be typed into: the processes its call started are ended with SIGTERM as `oko sessions interrupt` ends them there ({interrupted: {how: signal, …}, untold: <what would have been typed>}), and only a call that started no process of its own, or outlived an earlier SIGTERM, is put to the operator on his channels (`oko asks`), naming the wait and why Oko could not end it.
- Any other kind (a service, a host, the object store, a database, a lock, a child process) is answered by something that runs, so it is acted on only once the call stands past every completed call measured like it, by the stall settle; the watch counts that occurrence by the kind and place of the wait it stood in. A call the watch interrupted is not interrupted again by the stall settle.
- Each settled wait is kept once, with what was done, in `waits-settled.jsonl` in Oko's directory (OKO_WAITS_SETTLED moves it), and each occurrence is recorded as an intervention on the class defect (`oko defects show` lists them), which raises the defect's priority on repeats. settle prints {examined, waits: [{at, session, wait, by, done, counted}]}; `counted` names the defect, or why the occurrence was not counted (no class declared, or the register's refusal).
- The model policy pass keeps the same settlements under `waits` in its receipt (`oko sessions policy` shows the last one), the native API's sessions domain answers them with the pass, OkoKit reads them as `OkoSessions.WaitSettlement`, and Oko Desktop → Work → Sessions → Agent sessions lists each under Run model policy, for the service's last pass and for a pass run there: the session and its wait, what was done and the defect it was counted on, or why not.
- For example, after `oko sessions waits class set <defect> --by supervisor`, an executor whose `git log` paged into a terminal it never reads, registered as a terminal wait, is interrupted within one pass and told to run it without the pager, and the class defect shows one more interruption.
Refusals and safe exits#
- “oko sessions waits takes settle [--hours N] or class [set <defect> --by <who>|clear]; got <words>” and “oko sessions waits class takes nothing, set <defect> --by <who>, or clear; got <words>” (exit 2); “oko sessions waits class requires --by <text>” (exit 2).
- A class that is not a registered defect is refused by the defect register's own sentence; “defect <id> is closed; occurrences are counted on an open defect”.
- A settled file, class declaration or rulings register that cannot be read is said with the cause in the settlement or the pass receipt; a wait that could not be acted on (no tool call running, a broker refusal) keeps `refused` with the cause and is looked at again on the next pass.
- The real journey in tests/sessions/policy/waits.rs (`STADO_BIN=<built stado> cargo test --manifest-path rust/Cargo.toml --test sessions-lifecycle -- --ignored --nocapture waits`) registers a terminal wait for a call waiting on a pipe with the real `stado waits open` and requires the built service's own pass to interrupt it, tell the session, count it on the declared class defect and keep it, and the refusals above to name their cause.