maka/docs/session-todo-lifecycle.md

SessionTodo Lifecycle

Status: Current. The former Session Task Ledger is Removed: its module, storage, and workflow_task_ledger_events table are gone as of workflow schema 12. SessionTodo is the only Session task surface.

This document answers one question for Runtime, Runtime Host, CLI, and Desktop contributors: who owns a Session's current Todo list, and what must happen to that list as the Session is read, copied, archived, or removed?

Mental model

SessionTodo is one small current-state document attached to one Session. It is closer to replacing a whiteboard checklist than appending to an audit log. todo_read returns the whole ordered list; todo_write atomically replaces the whole ordered list.

For example, this write:

{
  "todos": [
    { "content": "inspect the owner", "status": "completed" },
    { "content": "run focused tests", "status": "in_progress" }
  ]
}

commits exactly those two items in that order. A later write containing only the second item removes the first. There is no item identity, patch operation, revision, history, hierarchy, owner, evidence, cursor, or watermark.

completed is model-reported progress. It is not proof that a command ran, a test passed, or a file changed; AgentRun, RuntimeEvent, tool results, filesystem, and git remain the authorities for those facts.

Authority and data flow

The Runtime Host is the sole interactive authority. Storage owns the durable document and migration transaction; Runtime exposes the model tools; CLI and Desktop only render Host-owned results.

model todo_read / todo_write          Desktop read-only panel
              \                         /
               Runtime Host SessionTodo coordinator
                    | admission + Session presence
                    | commit, then signal-only invalidation
                    v
            SQLite SessionTodo current document

todo_write is an internal Host tool port rather than a public Client mutation operation. Desktop reads through session.todo.query. A successful replacement commits before the Host publishes a todo domain invalidation. Reads and first-read initialization are silent because they do not change the effective current list.

The stored document is canonical product state. Before model or Desktop display, content passes through the shared Unicode sanitization, secret redaction, and <session-todo> tag-neutralization projection. Display safety does not rewrite the stored document.

Document contract

Each item contains only:

• content: non-empty normalized text, at most 200 Unicode code points;
• status: pending, in_progress, or completed.

The document contains at most 200 items and at most 256 KiB of encoded JSON. These bounds keep the complete snapshot below the Runtime Host frame budget, so the operation needs no paging contract.

An initialized empty list is different from no SessionTodo row. That distinction is what makes explicit clearing deterministic.

First read

The first Host read of an uninitialized Session, through either todo_read or session.todo.query, persists an empty document and returns it. The first explicit todo_write writes the requested complete list directly.

Copy and branch semantics

Conversation copy initializes the target Todo inside the Host-owned copy lifecycle, before the target Session is published:

• an ordinary branch whose selected cut includes the latest committed turn copies the source's current Todo;
• a historical cut, before-revision, or side conversation initializes an explicit empty Todo document.

Initialization is one SQLite write transaction. The source's current document is read — an uninitialized source reads as empty, without being written — and the absent target is inserted in the same transaction. Retrying an identical initialization is idempotent; a different or corrupt existing target fails closed instead of being overwritten.

The Runtime Host holds the source and target Session admission lanes during the copy. A failed copy purges the incomplete target's Todo state before discarding the preparing Session.

Archive, removal, backup, and rollback

• Archive retains the current Todo document.
• Remove and incomplete-copy discard purge the Todo document, so a deleted Session cannot show stale work if its identifier is observed again.
• Backup and restore preserve both non-empty and initialized-empty documents.

Rollback across the cutover means restoring a database backup taken before the upgrade. That loses Todo edits made after the backup; running an old binary directly against the upgraded live database is not a supported rollback guarantee.

Upgrading to workflow schema 12 drops workflow_task_ledger_events without migrating it. A workspace last opened by v0.2.0-incubating-rc1 or earlier loses its unfinished Tasks; they are not imported into SessionTodo.

Surface behavior

CLI/TUI renders the settled semantic todo_read or todo_write tool result. It does not present todo_write arguments as committed state, including when a durable transcript is reconstructed after restart.

Desktop renders the same current ordered snapshot as a flat read-only list. Session and request-generation fences reject late responses after navigation; signal-only invalidations trigger a fresh full read rather than client-side merging.

No SessionTodo content is appended to a turn-tail prompt or dynamic system prompt. The model reads it on demand with todo_read.

Code map

• packages/core/src/session-todo.ts: document validation, bounds, and shared display projection.
• packages/storage/src/session-todo-store.ts: SQLite persistence, migration, copy initialization, and purge.
• packages/runtime-host/src/server/session-todo-coordinator.ts: Session admission, presence checks, commit, and invalidation.
• packages/runtime/src/session-todo-tools.ts: model-facing read and whole-document write tools.
• packages/runtime-host/src/server/session-revision-coordinator.ts and session-retirement-coordinator.ts: copy and lifecycle integration.
• apps/desktop/src/main/runtime-host-client.ts: Desktop query adapter and display-safe projection.

The legacy Task codecs, replay, and tables are deleted. Nothing may recreate a second product surface for Session tasks or change this current-document contract.