Oko
Oko/Docs

Command reference

oko blockers roots

Answers the root causes of one item: every item its recorded waits lead to that waits on nothing, each with the chain from the item to it. A symptom (Brama refuses every model call) waits on a cause, which waits on another; each cause is recorded once as a waiting relation or a blocker's --waits-on, and this reads the chain instead of every session tracing it again. Only a root's repair moves the symptom.

Invocation#

Command
oko blockers roots ID [--json]

Inputs and options#

  • ID is a defect id whole or short, an open blocker id, or a node id as `oko blockers graph` prints it. The waits are the same edges `oko blockers graph` reads: waiting relations (`oko tasks relate A blocked-by B`), releases, and recorded refusals.

Output and state effect#

  • Prints each root as `root cause <id> <kind> <label>` with ` chain: <item> -> … -> <id>`, or `loop of waits <id> …` when the waits close on themselves (nothing in the loop moves until one wait is broken); an item that waits on nothing prints `<id> waits on nothing recorded: it is its own root cause; repair it`.
  • --json prints {item, isRoot, roots: [{node: {id, kind, label}, chain, cycle}]}; the native API's blockers domain answers the same to roots {item}, and Oko Desktop's Blockers screen shows it under Root causes, with a field naming the item.
  • `oko blockers record --waits-on <defect>` reads the same walk first: a wait on a recorded defect that itself waits on others is refused, naming its roots and chains, so a wait is recorded where the work is. A wait on an item that is not a recorded defect (a repository, a release, an operation in the blocker's own words) is recorded as given. Real test: tests/blockers/roots.rs (`cargo test --test rulings-mechanism blockers_roots`).

Refusals and safe exits#

  • `oko blockers roots does not take <flag>` and a missing ID (exit 2); the naming refusals of `oko blockers graph --from`.
  • From `oko blockers record`: `<defect> is not a root cause: it waits on others, so a wait recorded on it is rediscovered by every session that meets it; record the wait on its root instead: <chain>; …` (exit 1, nothing recorded).

CLI reference#