Oko
Oko/Docs

Command reference

oko sessions role

Records which agent session supervises and which sessions execute under it, so the role is a fact Oko shows and acts on instead of a sentence in a brief.

Invocation#

Command
oko sessions role set ID supervisor --by WHO; oko sessions role set ID executor --supervisor ID --by WHO; oko sessions role show ID; oko sessions role clear ID; oko sessions role list [--json]

Inputs and options#

  • ID is the session id, as `oko sessions agents` prints it; set and show need a transcript of it on this machine. supervisor and executor are the two roles; an executor names, with --supervisor, a session already recorded as a supervisor.
  • --by is operator, or the id of the session on this machine that records the role (a supervisor recording its executor).
  • --json prints the answer as JSON; without it the same answer is printed as lines for a person.

Output and state effect#

  • set writes the current role to ~/.oko/session-roles.json under ~/.oko/session-roles.lock and prints {session, role, supervisor, executors, recordedBy, recordedAt}; replacing a role first closes its dated interval in ~/.oko/session-role-history.json. show reads the current role, with role null when none is recorded; list prints {roles: [...]} for current roles. clear closes the interval before removing the current role and prints {session, cleared}. Past supervisor attribution remains available to reflection after a clear; it is not an active executor assignment.
  • `oko sessions agents` and Oko Desktop's Agent sessions show each session's role; the Role menu there marks a session as supervisor, as executor of a recorded supervisor, or clears its role, through the native API's sessions domain (role_set, role_clear, role_show, roles), recorded by operator.
  • The control pass's handover tells a session recorded as a supervisor, before its tasks, that it does not do them itself — no code edits, builds, tests or commits — but hands each one to an executor session it supervises with `oko sessions resume`, records new executors with `oko sessions role set <id> executor --supervisor <its id>`, follows them with `oko sessions agents`, and names its executors. An executor's handover names the session that supervises it.
  • Current and closed roles are kept on the machine whose transcripts they describe. Reflection compares each Lake event time to the recorded role interval, not to the session's present role; an event outside any recorded interval has no claimed supervisor. `oko sessions agents` answers current roles without waiting on a service.

Refusals and safe exits#

  • “oko sessions role takes set, show, clear or list; got <verb>”, “oko sessions role set requires <id> and a role: …”, “oko sessions role set acts on one <id> and one role; it was also given <word>, which it would not read”, “oko sessions role set requires --by <text>”, “oko sessions role set: the role is supervisor or executor; got <word>”, “oko sessions role set <id> executor requires --supervisor <id>, the supervisor the session works under”, “oko sessions role set <id> supervisor does not take --supervisor; a supervisor works under nobody”, “oko sessions role set: session <id> cannot be its own supervisor”, “oko sessions role set: --by is operator or the id of a session on this machine; no transcript of session <id> on this machine: …”, “oko sessions role show requires <id>” and “oko sessions role <verb> does not take <flag>; it takes …” (exit 2).
  • “no transcript of session <id> on this machine: no live transcript root holds a file named for it; `oko sessions agents --hours N` lists the sessions this machine holds”.
  • “session <id> is not recorded as a supervisor (it has no role | it is an executor under <id>); record it first with `oko sessions role set <id> supervisor --by <who>`”.
  • “session <id> supervises <ids>; it cannot become an executor while they work under it: …” and “session <id> supervises <ids>; it cannot lose its role while they work under it: …”, naming `oko sessions role set <id> executor --supervisor <id> --by <who>` to move them.
  • “session <id> has no role recorded in <path>; `oko sessions role list` shows every recorded role”.
  • “another oko is writing the session roles: <lock> is locked (<error>); run the command again once it has finished”, “the session roles in <path> cannot be read: <error>; …” and “HOME is not set, so the session roles file $HOME/.oko/session-roles.json has no place”. A failed read or write of ~/.oko/session-role-history.json refuses the role change before the current role is removed; the path and underlying cause are retained. All of these exit 1.

CLI reference#