Oko
Oko/Docs

Command reference

oko tasks unread

Lists stored operator messages without a reading. Classification coverage is distinct from linking every message to a task.

Invocation#

Command
oko tasks unread [--session-prefix P] [--json]

Inputs and options#

  • --session-prefix keeps the sessions whose id starts with P: the leading hex a harness gives a group of sessions, or a whole id. The database answers it from a pattern-ops index on the session id, so one group is read without the rest.
  • --json selects structured output: count, oldest dated message, undated count and messages, each with its session, number, time and verbatim text.

Output and state effect#

  • Asks the shared database for the signed-in member's stored operator messages in the current organization that no kept reading covers (the view `oko_unread_operator_messages`, which derives each message's identity the way Oko does) and prints them newest first. The request names organization and member before paging by session and message number, matching the table's leading key columns; row security still authorizes every row. Only unread messages are transferred. Nothing is written; `oko tasks kind <session> <number> <KIND> --by <session>` records what one is, after which it no longer appears. Run `oko tasks sweep` first so messages written since the last sweep are stored.
  • Oko Desktop → Tasks → Messages without a reading uses the same native tasks/unread operation. Leave Session prefix empty to read every stored session, or enter a prefix and choose Read uncovered messages. Each row shows the original text, session, message number and recorded time; a failed request shows its concrete cause instead of a zero count. An empty result proves reading coverage only: it does not prove that every classified message is linked to a task or that the tasks are complete.
  • The count is the complete selected-scope unread set. `oldest` names the earliest message with a recorded timestamp, or null if none is dated; `undated` counts messages whose age cannot be compared with it. The native API returns the same fields and Oko Desktop shows the count, oldest dated identity and undated warning above the messages.
  • The Session prefix field is locked while its read is running. Editing the prefix after a read clears the previous count, messages and error; choose Read uncovered messages again for the new scope. A result from one scope must not appear as coverage of another.
  • Before claiming coverage, the shared CLI/native reader checks timestamp allocations and retained reading, addition and task references in the same organization, member and optional session-prefix scope. An unreconciled source refuses with its actual session, message number and retained timestamp, even if an old reading would otherwise hide it. An unallocated retained reference refuses with its actual session, message number, reference kind and identity. Run `oko tasks derive --session <session-id> --write` against the retained original source before reading that scope again. The reader does not allocate identities, bind references or change classifications.
  • The CLI and native Desktop reader reject malformed unread rows instead of inventing an empty session or message. A row-decoding refusal identifies its returned row and parser cause; an invalid recorded timestamp identifies the session and message number. A genuinely absent timestamp remains null, as the stored-message schema allows. Successful output preserves the original timestamp text and orders dated messages newest first, followed by undated messages.
  • The real unread-session-prefix qualification reads a reconciled prefix through the CLI and compares stored row identities. Its global read must either match the stored view or refuse an actual unreconciled source or unallocated reference. Set OKO_UNREAD_SESSION_PREFIX and OKO_TEST_SOURCE_REVISION for the successful read. OKO_UNRECONCILED_SESSION_PREFIX selects a retained read-only unreconciled-source fixture; OKO_UNALLOCATED_SESSION_PREFIX selects a retained read-only reference fixture without a preceding unreconciled-origin refusal. Run `cargo test --manifest-path rust/Cargo.toml --test unread-session-prefix -- --ignored --nocapture`. The refusal cases check actual source or reference coordinates and unchanged allocation or reference state. Invalid prefix coverage remains included. Source and binary digests, commands, exit statuses, elapsed times and case verdicts remain under .build/unread-journeys. A command that cannot start retains its executable, arguments and OS cause in startError before the case fails; it is not given an invented exit status.
  • The same real prefix journey compares each returned message's complete text and timestamp with its stored source, then checks chronological ordering and null timestamps without substituting generated messages. Undated-message coverage requires a retained scope that actually contains undated messages; an empty or entirely dated scope does not prove that boundary.

Refusals and safe exits#

  • A failed shared-database read, including a database that does not hold the view yet, exits unsuccessfully with the database's refusal; it never becomes an empty list.
  • A --session-prefix holding anything but letters, digits, '-' and '_' is refused with `oko tasks unread --session-prefix takes the start of a session id (letters, digits, '-' and '_'); got <value>` and exit status 2, and so is a flag the command does not read.

CLI reference#