Oko
Oko/Docs

Command reference

oko sessions digest

What a session did since a moment, read from its own transcript, for the supervisor that has to read it rather than look at its state.

Invocation#

Command
oko sessions digest ID --since TIME [--socket PATH] [--plain]

Inputs and options#

  • ID is the session id; --since is an RFC 3339 time such as 2026-01-01T08:00:00Z. Only the records written at or after it are read, from the end of the transcript back. The answer is JSON; --plain prints the same document as lines.

Output and state effect#

  • Prints {placement, session, transcript, since, from, until, records, places, prompts, commands, commits, files, failed, waits, decisions, toOperator, turns, harnessGaps, harnessUnread, unread}: the prompts the session was given, every tool call with the first line of its input, every commit git reported in a tool's result (branch, revision, subject) and the files each changed (read with git show in the directory the call names, else the session's), the calls whose result the harness marked an error, the waits every Wisent program announced, what it said while calling tools, what it said when it ended a turn, and each turn with its seconds. Every entry carries its place {id, at, record, call}: id is the record's id where the harness gives one, else its time, and places lists each id once — the places a reading cites. from is the first record read.
  • harnessGaps names what a live session runs without (Tama's hooks, its inbox reader, or an inbox reader that could not be read) and the command that continues it under the extensions installed now; harnessUnread says why the live sessions could not be listed. placement is where `oko sessions role adopt` put the session in the tree and why. Oko Desktop reads the same digest through the native API's digest action.
  • posts lists every message kept for the session or sent by it since --since, each with where it is (`oko sessions posts`). roleDivergence {recorded, wroteToIt} names the supervisors that wrote to it from outside the chain the role register records above it, so a register that no longer names who supervises it shows. reading {at, until, stale} is its last kept reading (`oko sessions read`), stale naming why a supervisor can no longer cite it.
  • interruptions lists every call or answer of the session the loop interrupted (Escape in its broker terminal) or ended (its processes signalled) since --since, as the interruptions register keeps them ({at, session, by, how, tool, input, since, seconds, shape, norm, …}), so the digest says what happened to the session beside what it did; an interruption kept with no readable time refuses the digest naming it.

Refusals and safe exits#

  • “oko sessions digest requires <id>”, “oko sessions digest requires --since <text>” and “oko sessions digest --since takes an RFC 3339 time such as 2026-01-01T08:00:00Z; <value> is not one: <error>” (exit 2).
  • “no transcript of session <id> is on this machine (looked in <roots>); `oko sessions agents --hours N` lists the sessions it holds” and “the end of the transcript <path> cannot be read: <error>” (exit 1). A commit that cannot be read is named under unread (“commit <rev>: …”, with git's own words or why no directory names it), and the rest of the digest stands.

CLI reference#