源码快照 @ 2026-09-01 (source-only, 剔除非源码素材)

docs/session-todo-lifecycle.md

@@ -0,0 +1,170 @@
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# 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:
+
+```json
+{
+  "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.
+
+```text
+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.