Oko
Oko/Docs

Command reference

oko tasks map

Shows a tree of recorded tasks and defects under each current operator goal, with unlinked and unjudged work as graph debt. Select --place open for the open backlog; it is a filter of this map, not another command.

Invocation#

Command
oko tasks map [--session ID ...] [--place open|waiting|blocked|answered|refused|done|withdrawn] [--origin operator|delegated|automation] [--kind task|defect] [--json] [--full]

Inputs and options#

  • Without --session the map covers every session whose ledger the sweep has built; --session narrows it and may repeat. A narrowed map reads the selected session keys in paged requests for task additions, classifications and allocated origins; only an observed URI-too-long refusal splits the selection. Related task state still follows cross-session relations, and unswept remains a global live-ledger freshness count. --place, --origin and --kind filter the rows listed; the counts describe the selected sessions before those row filters. --full prints each task’s whole text; --json prints the map with its counts and entries.
  • In Oko Desktop, open Task map, enter space-separated session IDs and choose Build map. Leave the field empty for every session. Requested scope stays attached to the response or refusal even if you edit the next request; starting another read clears the previous map and error. The field is disabled during the read. A scoped result displays whole map only for vanished relation ends, while Not swept still covers all live ledgers. Failures retain the core operation's cause.
  • The real tasks-relation-ends journey requires isolated qualification fixtures, not an operator's active task: OKO_TEST_TASK and OKO_TEST_TASK_LOCAL_DEFECT select the task and related defect message used by the invalid-author refusal. No deployment-specific defect is selected by the test. OKO_TEST_SESSION and OKO_TEST_OTHER_SESSION must name distinct sessions with derived tasks. The journey compares the single-session map and the combined repeated --session map against their identities in the whole map, rejects duplicate rows, and requires danglingEnds to remain null for both scoped reads. Set OKO_TEST_SOURCE_REVISION to the exact committed revision; the journey refuses an edited tracked tree and retains source identity, binary and test digests, commands, exit statuses and complete output under .build/tasks/relation-ends. Only a run reaching every assertion writes result.json with passed:true; partial receipts are not a passing result.

Output and state effect#

  • Reads stored messages, annotations, relation edges, current goal snapshots and the defect register. The unfiltered whole map includes stored task objects even when no current ledger derives them; they remain recorded in a goal tree or graph debt, not silently disappear. For --place open, each session's stored messages are read by its recorded reading or addition rather than downloading every operator message in the database; a missing reading is not an open task. The real tasks-map-open journey compares one session's open rows in the whole open map against the same named-session map. Its selected-ledger journey requires two distinct genuine sessions with open tasks (OKO_TEST_LEDGER_FIRST_SESSION and OKO_TEST_LEDGER_SECOND_SESSION), checks their combined and separate maps and the actual selected-query trace, and retains commands, statuses and source revision under .build.
  • Prints the selected-scope counts and one indented tree per goal, then graph debt with its last observed placement refusal. JSON keeps entries, goalTrees and graphDebt; each debt row names its recorded part-of parent when one exists. Plain output distinguishes an unresolved parent from an absent edge. Remove the named old parent with `oko tasks unrelate ITEM part-of OLD_PARENT` before relating the item to a current goal, or use the same controls on Desktop's Task map. A task whose model refused it remains refused; an unlinked item is owed work.
  • Dangling task relation ends are measured only for the whole register. Scoped maps carry null for danglingEnds; a current attached defect message is not dangling. The count does not equate unlinked graph debt with stale source freshness.

Refusals and safe exits#

  • --place, --origin and --kind keep only the rows whose value equals the one given; a value no row carries lists none. Index open failures exit unsuccessfully.
  • A selected ledger query failure names the table and its actual database cause once; a URI-too-long refusal splits only the refused selection, while any other failure refuses the entire map. A returned row outside the requested session keys is refused, not mixed into the result. CLI and native Task map use the same reader; the graphical request retains that core cause.

CLI reference#