Oko
Oko/Docs

Command reference

oko tasks state

Records a task’s contract beside the operator’s own words: its name, what it asks for, the checks that decide it is done, how long it is expected to take, its priority and due date, the repositories it may change, which parts of the Jeden task contract apply to it, what blocks it, and whether the operator confirmed it, so a message that points at its turn still describes the work to a later reader and to the judge.

Invocation#

Command
oko tasks state (<session> <number> | <task-id>) [--name TEXT] [--statement TEXT] [--acceptance TEXT ...] [--estimate MINUTES] [--priority high|medium|low] [--due YYYY-MM-DD] [--scope REPO ...] [--surface SURFACE=yes|SURFACE=no:REASON ...] [--blocked CAUSE --failed-operation TEXT --resume-when TEXT | --unblock] [--refused REASON | --unrefuse] [--confirm] --by (operator | <session>)

Inputs and options#

  • <session> and <number> name the task as oko tasks prints it, or <task-id> names it by identity alone; --name gives the task a short title; --statement says what must be done; --acceptance names one check that decides the task is done and repeats for every check; --estimate is the whole number of minutes the work is expected to take; --by names who says so: a session id records that session’s reading, and the literal word operator records words the operator wrote or confirmed. At least one of the flags above or below is required.
  • The number is the message’s place among the session’s stored operator messages — the one oko tasks kind, oko tasks unread and oko tasks map print — and so it is for claim, check and evidence; only a session nothing is stored for, or whose live transcript has grown past the stored copy, is read from its live transcript. A task the map derives from a session whose transcript is no longer on this machine is therefore named by its session and number.
  • --priority is high, medium or low; --due is a calendar day; --scope names a repository the task may change and repeats, replacing the list; --surface declares one part of the Jeden task contract — functionality, diagnostics, cli, gui, documentation, tests or delivery — as applying (`gui=yes`) or not applying with the reason (`gui=no:Stado Desktop has no space screen`), and repeats; --blocked, --failed-operation and --resume-when record why the task cannot proceed, the operation that failed and the condition that lets it resume, all three together; --unblock clears the blocker; --confirm, only with --by operator, confirms the contract as it now stands.
  • --refused REASON, with --by the session that will not do the task, records that its model refuses it and why, for example `oko tasks state task-0000000000000001 --refused "it asks for accounts registered past the platform's bot detection" --by <session>`. The model is not given: Oko reads it from that session's own transcript, the model (and provider, where the harness records one) behind its newest answer, so the record names the model that refused and not one the session claims. --unrefuse takes the refusal back, from the session or the operator (`oko tasks state <task-id> --unrefuse --by operator`).

Output and state effect#

  • A task is listed by its name. The operator’s sentence is what he said, not what the task is called: listings, oko tasks map and Oko Desktop’s Tasks screen print the name on the task’s row and the sentence under it as “said: …”; oko tasks show prints “name: …” first; JSON carries `contract.name`. An unnamed task’s row reads “(no name yet)”, and an open one adds “name: nobody has named <task-id>” with the exact command. Giving --name again replaces the name.
  • Writes the statement beside the ledger, keyed by the task’s identity, with the recording session and the hour, and prints it above the operator’s unchanged sentence. The operator’s text is never replaced. A session’s reading is marked everywhere it is shown: listings print “asks for (unconfirmed, read by session …)” and show prints “stated by: session …”, while the operator’s own words print plain and “stated by: the operator”. Every listing prints “asks for” under the task, oko tasks show adds “asks for” and “stated by”, and JSON carries `statement`. The statement follows the identity when the number moves, and re-recording replaces it.
  • Acceptance checks print as “accepted when #n [unchecked]: …”, one per line, under the task in every listing and in oko tasks show; oko tasks check turns [unchecked] into [met] or [not met] with the evidence after a dash. Giving --acceptance again replaces the list and clears every check’s result; omitting it keeps both. The estimate prints as “estimate: N min, written once” and afterwards as “time: estimate N min, so far M min” while the task is open or “elapsed M min” once it is settled. Oko measures elapsed time itself, from the operator’s message to the accepted result, so nobody reports it.
  • The rest of the contract prints under the checks: “priority P, due YYYY-MM-DD”, “scope: repo, repo”, “surface <name>: applies” or “surface <name>: not applicable — <reason>”, and “surfaces not declared: …” naming every part of the Jeden task contract nobody has declared yet (“surfaces: none declared yet” when none is), then “blocked: <cause>; failed: <operation>; resume when: <condition>”. The last line says “contract confirmed by the operator <time>” or “contract not confirmed by the operator (written by <who>)”. The operator’s confirmation holds until a session changes the contract; any such change withdraws it and says so in the history. Tama’s `task scope set --task <id>` reads the scope from here when it is given no --repository, and writes the repositories it is given back into the contract.
  • A refusal is kept in the contract's terms as `refused` (`reason`, `model`, `recordedBy`, `recordedAt`) and gives the task the status `refused` with the reason “refused by <model> in session <session>: <reason>”; oko tasks show prints “refused by <model> (session <session>, <time>): <reason>” and oko tasks map places it under refused. A refused task is not handed back to any session by the control pass, Tama's stop and assignment gates do not count it as open work, and a task related to it does not wait on it. It stays refused until the refusal is taken back or a defect is reported on the task after it, which reopens it. Oko Desktop's Tasks screen shows the same line in the task's contract with a Take the refusal back button, the same write as --unrefuse --by operator.
  • Every change to a contract — name, checks, estimate, a check’s result, surfaces, scope, priority, due date, blocker, refusal, confirmation — is kept, oldest first, and oko tasks show prints one “history <time> <by>: <change>” line for each, such as “priority: none -> high” or “operator's confirmation withdrawn by this change”. JSON carries `contract` with `acceptance`, `estimateMinutes`, `recordedBy`, `recordedAt` and `terms` (`results`, `surfaces`, `scope`, `priority`, `due`, `blocked`, `refused`, `confirmedAt`), `elapsedMinutes` on a settled task, and `history` in oko tasks show --json. Oko Desktop’s Tasks screen shows the same lines under the task’s statement, with a Confirm contract button while the contract is unconfirmed; the button records the operator’s confirmation exactly as --confirm --by operator does and shows the same refusal. The task lookup lists the history.

Refusals and safe exits#

  • Refuses without a task and --by, or with no contract flag at all, and prints the usage; an empty or blank statement or name refuses the same way; an estimate that is not a whole number of minutes above zero refuses with “<value> is not an estimate”; a second, different estimate refuses with “already has an estimate of N minutes”, because an estimate revised after the work starts measures nothing; “<value> is not a priority; one of high, medium, low”; “<value> is not a date; --due takes YYYY-MM-DD”; “<value> is not a surface; one of functionality, diagnostics, cli, gui, documentation, tests, delivery”; a surface marked as not applying without a reason refuses with “surface <name> is declared as not applying without a reason; write <name>=no:REASON”; a blocker missing any of its three parts refuses with “a blocker needs --blocked CAUSE, --failed-operation TEXT and --resume-when TEXT together”; --confirm from a session refuses with “only the operator confirms a task's contract: --confirm needs --by operator”; confirming a task without acceptance checks refuses with “task <id> has no acceptance checks, so there is no contract to confirm”. A malformed value refuses before anything is written, and a refused contract change writes nothing to the contract. A number the ledger does not hold refuses by session and number; an identity nobody recorded refuses as oko tasks show does. A task identity the session's current ledger no longer derives — its message is read as something else now — refuses with “cannot record against <id>: session <S>'s current ledger contains no task with that identity (recorded origin message #<n>), so the message is no longer read as a task; nothing was written”, naming `oko tasks show <id>` for how the message is read now and `oko tasks kind <S> <n> task --by <session>` to read it as a task again, the same for check and evidence.
  • A refusal refuses with “--refused takes the reason the model will not do the task; it was empty” for a blank reason; with “a refusal is the refusing session's own record; the operator takes a task back with oko tasks verdict --outcome withdrawn” for --by operator; with “a refusal is recorded by the session that refuses; no transcript of session <id> on this machine says which model it runs” when the --by session's transcript is not here; with “the transcript <path> of session <id> records no model at /message/model or /payload/model, so the refusal cannot say which model refused” when its harness wrote no model; and with “--refused records a refusal and --unrefuse takes it back; give one” when both are given.

CLI reference#