RFC: Radically slim the Session Task Ledger

[Astro-Han]

RFC: Radically slim the Session Task Ledger

Status: Draft. Scope: task-ledger in core / storage / runtime-host / runtime + desktop panel + docs/session-task-ledger-lifecycle.md.

TL;DR

The ledger exists for one reason: the model's work plan lives in a context that is volatile, private, bounded, and expensive — so it must live outside the conversation, in a persistent, authority-owned, session-scoped state re-injected each turn at bounded cost. That goal needs only three things: a persisted task list, task_create/task_update, and turn-tail injection. In one month the feature grew from 5 fields / 2 tools / one JSON file to 13 fields / 4 tools / event-sourced dual tables + a paginated query protocol. Proposal: cut every element whose removal loses nothing irreversible (code is in git, data stays in place), and keep an explicit restore-on-signal list for what we expect to miss.

1. First principles

Volatile/private/bounded context → plan must be external → session-scoped with stable identity → model needs create/update → transitions validated by a system authority → injection has a hard budget, scale derived from it → writes atomic.

Not derivable from this goal: event sourcing, task trees, subagent ownership, audit, time-based archiving, pagination, revisions, a 5-level trust taxonomy, free-text evidence. Each must justify itself independently.

2. Diagnosis (all verified on current main)

• F1 — resumeTrust is dead. Only production caller classifies with empty refs: 5 levels, 3 reachable; untrusted never occurs, so filterModelVisibleTaskLedgerTasks is the identity function. A corrupt ledger throws on read rather than being classified.
• F2 — the "Goal trust gate" is a status gate. listActionableTaskKeys filters on pending/in_progress only. The belief that trust had a consumer is why it survived.
• F3 — the projections table is written, never read. Every read replays all events; the write path commits events and projection in two transactions and signals before the projection is written.
• F4 — claimAvailable is dead code through 4 layers, zero callers.
• F5 — omittedCount misreports: counts policy-excluded terminal tasks as "omitted", so every turn the model is told "N omitted — use task_list" for tasks that weren't budget-omitted at all.
• F6 — one rule, six authorities. "Completion requires evidence" is enforced in zod, normalize, validate, replay, read-validation, and wire projection. This duplication, more than any field, explains 1092 lines.

3. The criterion

Code is reversible (git). Data is reversible (no DROP). Model contract is reversible (models re-adapt). The only irreversible act is deleting user data. Therefore: cut everything, keep old tables in place read-only.

4. Verdict

Fields (13 → 3)

Field	Verdict	Why
id	keep (uuid → compact random id)	foundation
key	cut (merge into id)	dual identity + dual allocation paths; key is just id's display form
subject	keep	the payload
status	6 → 3 (pending/in_progress/completed)	blocked/failed/cancelled are execution details; top restore candidate
createdAt / updatedAt	cut	insertion order suffices
endedAt	cut	with archiving
parentId	cut	~150 lines of core for a hierarchy the original design said was flat; the one real invariant (parent-before-child) can return standalone
owner	cut	subagent binding belongs to AgentRun, which has no such field — the product never asked for it
blockedReason / failureReason / completionEvidence	cut	model-authored text is a claim, not evidence (real evidence lives in tool results/files/git/tests)
resumeTrust	cut	F1

Mechanisms

Mechanism	Verdict	Why
Event log + projection table	cut → one normalized current-state table	F3; copy becomes a snapshot; audit belongs to RuntimeEvent
Key allocation / backfill	cut	identity merged
7-day archive	cut	cap never freed terminal slots; renderer selector already governs budget
Pagination / cursor / revision_changed / revision	cut	≤2 pages under 200 cap, server does full list + slice anyway, Desktop never uses it
claim / settleAgentOutcome	cut	real regression (production callers exist) but reversible; second goal deserves its own system
claimAvailable	cut	F4
Transition whitelist + explicitReopen + evidence rules	cut	validate enum membership only; system doesn't endorse self-reports either way
task_list / task_get	cut	cap drops to 20 active + 3 terminal, full ledger always fits the tail — "tail makes list redundant" becomes true again
Legacy aliases	cut	one-month-old interface
200-task cap	tighten to 20+3	derived from the 8000-char budget (open question 5)
Paginated task.ledger.query	simplify to one full-read query	shared by Desktop + TUI
turn-tail injection	keep	the feature itself
Redaction / tag stripping	keep	security boundary
Host single-writer + admission gate	keep	this is what authority means, not complexity
Desktop panel	keep, simplify fields	user-visible

Tools: 4 → 2 (task_create, task_update).

5. Target shape

interface Task { id: string; subject: string; status: 'pending'|'in_progress'|'completed'; }
// session_tasks(session_id, task_id, subject, status, seq)
// tail each turn: 20 active + 3 recent terminal, ≤8000 chars, stable tail truncation
// old tables kept in place, no longer written

6. Restore list (what we expect to add back, and the signal)

Cut element	Signal	Cost
blocked	models keep writing "waiting for user" into subjects	1 enum + 1 render line — most likely
completionEvidence	users: "says done, no trace why"	restore as typed refs (runId/toolCallId), not text
claim/settle	the day AgentRun grows a taskId field	design as its own system
Event log	conversation copy needs precise turn history	zero (tables kept)
Revision	TUI stale-response bugs	one integer

7. Migration

No DROP. Import existing tasks (id/subject/status) into the new table. Update operational-state-backup.ts manifest. Panel + lifecycle doc update in the same PRs.

8. Rollout

• P0 — delete dead code, zero behavior change: F1/F4/F5 fixes, pagination, task_get, legacy aliases, archive, endedAt. ~20% of surface, independently reviewable.
• P1 — field convergence: 3 statuses, id/key merge, cut parentId + evidence + owner.
• P2 — storage simplification: single table, copy → snapshot, backup manifest.
• P3 — scale/tools: cap 20+3, cut task_list, unpaginated query.

Each phase = one PR, own verification. Two independent external architecture reviews (one radical, one conservative) were run on this exact question; both confirmed over-design and verified F1–F6. Their conservative positions became §6.

9. Open questions

1. Cut blocked? (lean: yes — top of restore list, but the signal may come fast)
2. Accept losing subagent task-binding for now?
3. Is failed truly redundant once subagent outcomes stop auto-writing?
4. completionEvidence: cut entirely, or keep as typed references?
5. Is 20+3 the right cap? Derive from the 8000-char budget with real renders before merging.
6. Cap change and task_list removal must land atomically (one decision)?

简体中文要点版

RFC：Session Task Ledger 激进瘦身

状态：Draft。范围：core/storage/runtime-host/runtime 的 task-ledger + desktop 面板 + 生命周期文档。

TL;DR

这个特性存在的唯一理由：模型的工作计划在易失、私有、昂贵的上下文里，必须外置成持久、权威、每轮受限预算注入的 session 级状态。 这个目标只需要三样东西：持久化任务列表、task_create/task_update、turn-tail 注入。一个月里它从 5 字段/2 工具/单文件 JSON 长成 13 字段/4 工具/事件溯源双表+分页协议。提议：凡是砍掉后没有不可逆损失的（代码在 git 里、数据原地保留）全部砍掉，并维护"按信号加回"清单。

实测诊断（都在 main 上验证过）

• F1 resumeTrust 是死的：唯一调用点传空 refs，5 档只有 3 档可达，untrusted 永不产生，过滤函数是恒等函数；账本坏了是读不出来而不是被分类。
• F2 "Goal 信任门"实际是状态门：只按 pending/in_progress 过滤，trust 不参与。
• F3 投影表只写不读：每次读都全量重放事件；写入还是两个事务、signal 先于投影。
• F4 claimAvailable 死代码：穿透 4 层，零调用。
• F5 omittedCount 恒定误报：把策略性不选的终态也算省略，每轮怂恿模型调 task_list。
• F6 一条规则六个权威："完成必须带证据"写在 6 处——这比任何字段都更能解释 1092 行。

判据

代码可逆（git）、数据可逆（不 DROP）、模型契约可逆。唯一不可逆的是删用户数据——所以全砍，旧表原地保留只读。

裁决

字段 13→3：保留 id（uuid 换紧凑随机）、subject、status 3 态。砍：key（与 id 合一）、createdAt/updatedAt/endedAt、parentId（~150 行逻辑买一个本应是扁平的设计）、owner（AgentRun 都没有这字段）、三个证据字段（模型写的文本是声明不是证据）、resumeTrust（F1）。

机制：砍事件日志+投影表（换一张规范化当前态表）、key 分配/backfill、7 天归档、分页/revision、claim/settle/claimAvailable、迁移白名单+证据规则、task_list/task_get、legacy 别名；200 上限收紧到 20+3。保留：tail 注入（特性本身）、脱敏（安全）、host 单一权威（权威的真正内容）、Desktop 面板（字段简化）。

工具 4→2：task_create、task_update。

目标形态

interface Task { id: string; subject: string; status: 'pending'|'in_progress'|'completed'; }
// session_tasks(session_id, task_id, subject, status, seq)
// 每轮 tail：20 非终态 + 3 终态，≤8000 字符；旧表保留不再写

加回清单（按信号）

元素	信号	成本
blocked	模型老把"等用户"写进 subject	1 枚举+1 行渲染，最可能
completionEvidence	用户抱怨"说做完了没痕迹"	以强类型引用回归，非文本
claim/settle	AgentRun 长出 taskId 那天	作为独立系统
事件日志	会话分叉要精确历史	零（表没删）
revision	TUI 迟到响应 bug	一个整数

落地

P0 删死代码零行为变化（F1/F4/F5、分页、task_get、别名、归档、endedAt）→ P1 字段收敛 → P2 存储简化（单表、copy 改快照）→ P3 规模/工具（20+3、砍 task_list、无分页查询）。每阶段独立 PR。

做过两次独立外部架构评审（一激进一保守），都确认过度设计并独立验证了 F1–F6；保守方的意见变成了加回清单。

开放问题

1. 砍 blocked？（倾向砍，但它是加回清单榜首）
2. 暂时接受失去子代理任务绑定？
3. 子代理不再自动写回后 failed 还必要吗？
4. completionEvidence 彻底砍还是留强类型引用？
5. 20+3 是正确上限吗（用真实渲染从 8000 字符反推验证）？
6. 上限调整与砍 task_list 必须原子落地？

[somewan820]

I'd like to help take this RFC to implementation, and I'd like to keep
owning this direction (task ledger + task-to-execution evidence) after the
RFC lands.

I wrote the original durable lifecycle events (#567) and the hierarchical
task workflow (#956), so I have first-hand context on why the ledger grew to
its current shape — and I've verified F1–F6 against current main. I agree
with the diagnosis. I also checked #2889, which already removed the legacy
PascalCase aliases, so my P0 builds on that and focuses on what remains.

My proposal is to follow your rollout plan as four independent PRs:

• P0 — dead-code removal, zero behavior change (remaining slice).
  Remove claimAvailable (F4), fix the omittedCount accounting (F5), and
  drop task_get, 7-day archiving, endedAt, pagination, and the revision
  cursor from the task.ledger.query protocol. Legacy alias removal is
  already covered by refactor(runtime): remove task tool compatibility seams #2889. Old tables stay in place; no user data is
  touched.
• P1 — field convergence. Three statuses, id/key merge, remove
  parentId, evidence text fields, owner, and resumeTrust (F1/F2/F6).
• P2 — storage simplification. One normalized current-state table;
  conversation copy becomes a snapshot; keep legacy tables read-only.
• P3 — scale and tools. Cap 20 active + 3 terminal, drop task_list,
  make the query unpaginated (this must land atomically with the cap change).

After the slimming lands, I'd like to take the restore-list follow-up in the
same direction: typed evidence references (run / tool-call / artifact /
verifier) projected from existing authorities, so completion semantics live
in the runtime/evidence layer instead of growing back into the ledger. #2310
is a good data point for that: the refusal bug showed that text evidence is
hard for the model to attach correctly, which supports typed references over
free-text fields.

I'd like to start with the P0 PR now: it is the smallest, independently
reviewable slice. Two open questions I'd prefer to settle before P1:

1. blocked status — I lean keep it, per your restore list, but only after
   we see whether models write "waiting for user" into subjects.
2. completionEvidence — I'd like to design the restore path as typed
   references, not model-authored text.

Would you prefer I open the P0 PR directly, or should we settle the P0 scope
here first?

简体中文版

我想帮助把这个 RFC 推进到实现，并且希望在这个方向（Task Ledger + task → execution evidence）继续长期维护下去。

我写过最初的 durable lifecycle events（#567）和 hierarchical task workflow（#956），所以对 Task Ledger 为什么会变成现在这样有第一手了解。我已在当前 main 上核对过 F1–F6，同意这份
诊断。我也看了 #2889，它已经移除了遗留的 PascalCase 别名，所以我的 P0 会在此基础上继续，只做剩余部分。

我的建议是完全按 rollout 计划拆成 4 个独立 PR：

• P0 — 死代码清理，零行为变化（剩余部分）。 删除 claimAvailable（F4）、修复 omittedCount 统计（F5），并从 task.ledger.query 协议中移除 task_get、7 天归档、endedAt、
  分页和 revision cursor。遗留别名清理已由 refactor(runtime): remove task tool compatibility seams #2889 完成。旧表原地保留，不碰任何用户数据。
• P1 — 字段收敛。 3 个状态、id/key 合并、删除 parentId、evidence 文本字段、owner 和 resumeTrust（F1/F2/F6）。
• P2 — 存储简化。 一张规范化的当前状态表；conversation copy 改为 snapshot；旧表保留只读。
• P3 — 规模与工具。 上限收紧到 20 active + 3 terminal，删除 task_list，查询改为无分页（这一步必须与上限调整一起原子落地）。

瘦身落地后，我想沿着 restore list 继续做 typed evidence references（run / tool-call / artifact / verifier），从现有权威投影出来，让完成语义回到 runtime / evidence 层，而不是再长
回 ledger 里。#2310 正好是支持这个方向的数据点：那个拒绝文案 bug 说明模型很难正确填写文本证据，强类型引用比自由文本字段更可靠。

我想现在就开始 P0 PR：它是最小、可以独立 review 的切片。P1 之前我想先确认两个开放问题：

1. blocked 状态——按 restore list 我倾向保留，但想先观察模型是否会把“等待用户”写进 subject；
2. completionEvidence——我倾向把恢复路径设计成强类型引用，而不是模型写的自由文本。

你希望我直接开 P0 PR，还是先在这里把 P0 范围定下来？

[Astro-Han]

Assigned! It is still a RFC, so it is best we discuss how it is shaped further before implement it, but I'm glad that you lead the direction as the function is implemented orgininally by you.

[somewan820]

Thanks for the assignment and the feedback. Agreed — since this is still an
RFC, let's settle the shape before any implementation, and I won't open a PR
until we've converged.

My next step is to gather real usage data from local sessions (task
lifecycle, hierarchy, subagent/blocked paths, completion evidence), then post
a decision summary covering Q1–Q6 plus the storage questions (event log vs
single table, copy → snapshot, pagination/revision). Each item will state:
current behavior, evidence, my recommendation, and what would change my mind.

I'll come back here with that before writing any code.

[somewan820]

Following up on the discussion: this is design-only for now. I understand the
project is in a stabilization window ahead of the Apache release, so I will
not open PRs until it ends; I'll keep the design discussion here and prepare
the implementation plan so it can land quickly once the freeze lifts.

To ground Q1–Q6, I ran 5 scripted sessions on the dev build (current main).
Aggregate stats only, no session content.

Dataset: 5 sessions, 19 tasks, 62 task-ledger events.

• Tool calls: task_create 7, task_update 42, task_list 4, task_get 0.
  task_update status arguments: completed 20, in_progress 19, blocked 3.
• Current status distribution: 16 completed, 1 in_progress, 1 pending,
  1 blocked (blocked carries a reason).
• Hierarchy: 3/19 tasks have parentId, all in one session.
• Evidence: 16/16 completed tasks carry completionEvidence; 62/62 task
  events carry refs (runId/turnId/toolCallId).
• Subagent binding: 3 agent_spawn calls, all with task_id; 3 child-agent
  settle events (system source); 2 tasks are currently owned by a child
  agent and completed. No waiting_for_user → child-agent blocked path
  occurred in this sample.
• Interrupted session: after restart, the ledger preserved 1 in_progress
  and 1 pending task; resumeTrust is computed on read, not stored.

Implications:

1. Q1 (blocked) — keep. It is used in real sessions (3 blocked
   task_update calls, 1 current blocked with reason, one blocked →
   completed recovery), and the code has a second consumer that did not fire
   here: settleAgentOutcome maps a child agent's waiting_for_user to
   blocked, and the Goal gate only treats pending/in_progress as
   actionable. Cutting it would turn "waiting on the user" into an
   agent-actionable state. This is a data point against the RFC's initial
   lean-to-cut.

2. Q2 (subagent binding) — do not cut claim/settle in P0. The
   agent_spawn(task_id=...) → claim → settleAgentOutcome path is live:
   it fired 3 times and left 2 child-owned completed tasks. claimAvailable
   is genuinely dead (agree with F4), but the general claim/settle path is a
   working production surface. If we cut it, we need a typed-references
   replacement before removing it, not after.

3. Q3 (failed/cancelled) — no signal in this sample. Neither
   occurred. Cutting them in P1 is cheap; restoring them later is cheap too.

4. Q4 (completionEvidence) — cut the free-text field in P1; restore as
   typed references. All completions carry text only because validation
   requires it, the text is never authoritative, and every task event already
   records machine-checkable refs. The natural restore path is a pure
   projection over those refs (run/tool-call/artifact/verifier), not a new
   field on the task model.

5. Q5/Q6 (20+3 cap and task_list) — agree, and land them atomically.
   The largest session here had 5 tasks, far under 20; task_get had 0 real
   calls, supporting removal; task_list was called 4 times, which makes
   sense while the tail still reports a misleading omittedCount (F5). Once
   the cap and tail fit are in place, dropping task_list is consistent with
   this data.

6. Storage (event log vs single table). The event log is what carries
   the refs that typed evidence would project from, and it is what makes
   conversation copy possible. A single current-state table (P2) is fine, but
   I'd keep the event log as the copy/evidence source rather than deleting it.

This is a small n (5 sessions), so treat it as directional, not statistical.
Happy to iterate on any of these here. Once the stabilization window ends,
the first implementation slice I'd take is the remaining P0 bug-fix items
(F4/F5), then P1–P3 per the agreed shape.

简体中文版

接着上面的讨论：目前只做设计，不开实现。我理解项目在 Apache 发布前的稳定化窗口内不会接受 feature 合并，所以在此之前我不会开 PR；我会继续在这里做设计讨论，并把实现计划准备好，等冻
结解除后快速落地。

为了用真实数据支撑 Q1–Q6，我在 dev build（当前 main）上跑了 5 个脚本化会话。只贴聚合统计，不含会话内容。

数据： 5 个会话、19 个任务、62 条 task 事件。

• 工具调用：task_create 7 次、task_update 42 次、task_list 4 次、task_get 0 次。task_update 的状态参数：completed 20、in_progress 19、blocked 3。
• 当前状态分布：completed 16、in_progress 1、pending 1、blocked 1（带原因）。
• 层级：19 个任务里有 3 个带 parentId，全部集中在一个会话。
• 证据：16/16 个 completed 任务都带 completionEvidence；62/62 条 task 事件都带 refs（runId/turnId/toolCallId）。
• 子代理绑定：3 次 agent_spawn，全部带 task_id；3 条 child-agent settle 事件（system source）；2 个任务当前由子代理持有且已完成。本次样本没有触发 waiting_for_user → 子代理
  blocked 路径。
• 中断会话：重启后 ledger 保留了 1 个 in_progress 和 1 个 pending 任务；resumeTrust 是读取时计算，不持久化。

结论：

1. Q1（blocked）— 保留。 真实会话里确实在用（3 次 blocked 的 task_update、1 个当前 blocked 且带原因、一次 blocked → completed 恢复），而且代码里还有本次没触发的消费者：
   settleAgentOutcome 会把子代理的 waiting_for_user 映射为 blocked，Goal 门禁也只把 pending/in_progress 视为可行动。砍掉它会把“在等用户”变成“agent 应继续行动”。这是对 RFC
   初始倾向（lean: cut）的一个数据反例。

2. Q2（子代理绑定）— P0 不要砍 claim/settle。 agent_spawn(task_id=...) → claim → settleAgentOutcome 是活的：本次触发 3 次，留下 2 个 child-owned 且 completed 的任务。
   claimAvailable 确实是死代码（同意 F4），但 claim/settle 主路径是真实生产面。如果砍，需要先有 typed-references 替代，而不是砍掉后再补。

3. Q3（failed/cancelled）— 本次没有信号。 都没有出现。P1 砍掉成本低，以后加回来也低。

4. Q4（completionEvidence）— P1 砍自由文本，恢复时用强类型引用。 所有 completed 都带文本只是因为校验强制要求；文本从来不是权威；而每条 task 事件已经记录了机器可查的 refs。自
   然的恢复路径是这些 refs 的纯投影（run / tool-call / artifact / verifier），不是给 Task 模型加新字段。

5. Q5/Q6（20+3 上限和 task_list）— 同意，并且必须一起原子落地。 本数据里最大的会话只有 5 个任务，远低于 20；task_get 真实调用 0 次，支持删除；task_list 被调用 4 次，和当
   前 tail 的 omittedCount 误报（F5）相符。上限和 tail 容量落地后，删 task_list 与数据一致。

6. 存储（事件日志 vs 单表）。 事件日志正是 typed evidence 要投影的 refs 来源，也是 conversation copy 的基础。P2 改成单张当前状态表没问题，但事件日志应保留为 copy/evidence 来
   源，而不是删掉。

样本只有 5 个会话，属于方向性证据，不是统计结论。欢迎大家在这里继续讨论。稳定化窗口结束后，我第一个要实现的切片是剩余 P0 的 bug 修复项（F4/F5），然后按共识推进 P1–P3。

[likun666661]

One step back from the field-by-field slimming: I think we should first challenge the premise that Maka still needs a separate durable Task entity at all.

Define the problem before the mechanism

A Task Ledger is justified only if it owns an observable invariant that no existing authority owns. Today “task” conflates four different facts:

Fact	Existing authority
Why the system should continue	Goal
What work was durably scheduled, to whom, with which inputs/dependencies	Agent Graph
What actually ran and what result occurred	AgentRun / RuntimeEvent
What the main model intends to do next locally	Context / working memory

The current ledger grew because it crossed all four boundaries: it is a model checklist, binds child execution, records outcome/evidence claims, and gates Goal continuation.

What Graph already covers

For graph/swarm work, Agent Graph already has stable work identities, instructions, inputs, target ownership, stop/replace/finish decisions, operator/run lifecycle, waits/failures, committed result records, and restart-safe admission. That is the real durable work authority.

At the moment graph supervisors still receive the default task_* tools as well as the Graph tools (default tool composition). This asks the model to maintain two overlapping descriptions of the same work, with no invariant keeping them consistent.

Graph does not currently represent one thing: private local steps the root agent has not scheduled to an operator. Every Graph work item has an agent/preset/operator target (schedule contract). But that missing piece is working memory, not a second workflow authority.

Occam verdict

My current lean is:

• do not keep the current Task Ledger as an independent authority;
• in graph/swarm mode, Graph is the only durable work authority and task_* should not be present;
• one-shot agent_spawn results already belong to RuntimeEvent; durable ownership/coordination should use Graph rather than task_id binding;
• Goal continuation should be decided by Goal evaluation, not a second model-authored task status;
• only keep a separate mechanism if ordinary/default sessions explicitly promise exact recovery of unfinished local steps after compaction or restart.

If that last promise is a real product requirement, the minimum mechanism is not a Task Ledger. It is a context sidecar such as:

interface SessionWorkingSet {
  items: string[]; // unfinished local steps only
}

One replace/clear operation, one current-state row, bounded turn-tail injection. No terminal history, status machine, owner, evidence, hierarchy, event sourcing, pagination, or workflow UI. Completed work disappears from the working set; execution truth remains in RuntimeEvent.

If ordinary sessions do not make that exact-resumption promise, even this sidecar is unnecessary and context projection/compaction should own the problem.

So before deciding 13 fields → 3, I suggest resolving one product question:

Without Graph enabled, must an ordinary session precisely remember its unfinished internal steps across context compaction or process restart?

• No: remove the Task Ledger entirely.
• Yes: keep a minimal context-owned Working Set, not another task/workflow system.

This also changes the rollout shape: P0 can still remove verified dead code/fix omittedCount, but P1 should first decide whether the Task entity survives at all.

[somewan820]

This framing makes sense to me, and I'd suggest moving the decision to authority first rather than entity: for each kind of work fact, who owns the source of truth? Once that's answered, the question of whether the Task Ledger entity survives mostly answers itself.

I checked the wiring: in graph/swarm mode, Agent Graph is the durable work authority and task_* shouldn't be there; but buildDefaultHostTools currently adds the task tools to the default composition unconditionally, so the overlap is real.

A few observations from the 5-session run are directly relevant:

• In the interrupted default session, 1 in_progress + 1 pending task survived the restart. That makes the Task Ledger the only durable record of unfinished local steps in a normal session today. That's observable behavior, but whether it's a product promise is exactly what we should answer before P1.
• Usage is task_create 7 / task_update 42 / task_list 4 / task_get 0. The model writes far more than it reads, which makes the ledger look like a model-written scratchpad; the durable value is mostly system recovery, not model retrieval. That points toward a system-derived Working Set rather than a model-owned ledger.
• waiting_for_user / blocked appeared 3 times, and the code maps a child agent's waiting_for_user outcome to blocked. It's a real continuation semantic — "I know the next step but can't continue until external input" — which is different from "unfinished". If we remove it, that should be an explicit decision, not an accidental loss.
• Every task event already carries runId / turnId / toolCallId, so a Working Set can be projected from RuntimeEvent facts instead of being another model-authored state.

So my suggestion is: don't decide the entity first. First answer the product question — does a normal Session promise exact recovery of unfinished local steps across compaction/restart?

• If yes: B is the option most consistent with Maka's authority/projection model today. And B should be exactly the minimal mechanism proposed here: SessionWorkingSet { items: string[] }, one replace/clear, one current-state row, bounded turn-tail injection; no lifecycle, owner, evidence, hierarchy, event sourcing, pagination, or workflow UI, with RuntimeEvent remaining the execution truth.
• If no: C (remove it entirely) is simpler.
• A (slim Task Ledger) reads to me as a transition/compatibility option, not the final architecture direction.

Separately, waiting_for_user needs its own explicit decision either way: move it into Goal/Session continuation semantics, or consciously drop it.

P0 (dead code + omittedCount fix) is independent and can proceed.

简体中文版

这个框架我同意，而且我建议把决策先放回 authority，而不是先定实体：每一种工作事实由谁拥有 source of truth，答案清楚了，task 实体去留自然就清楚了。

我核对了一下，graph/swarm 模式下 Agent Graph 是 durable work authority，task_* 确实不应该存在；但 buildDefaultHostTools 目前仍然把 task 工具无条件加进默认组合，所以这个重叠是真实的。

5 个会话跑下来，有几个观察直接相关：

• 中断的普通会话里，1 个 in_progress + 1 个 pending 任务在重启后仍然存在。也就是说，Task Ledger 现在是普通会话里唯一跨重启保存“未完成本地步骤”的东西。这是今天可见的行为，但它算不算产品承诺，正是 P1 之前要回答的问题。
• 使用量是 task_create 7 次 / task_update 42 次 / task_list 4 次 / task_get 0 次。模型基本只写不读，说明它更像一个 scratchpad；持久化的价值主要在系统恢复，而不是模型检索。这更支持“系统推导的 Working Set”，而不是“模型拥有的 ledger”。
• waiting_for_user / blocked 用了 3 次，而且代码会把子代理的 waiting_for_user 映射为 blocked。这是真实的 continuation 语义：我知道下一步，但必须等外部输入，和“未完成”不是一回事。如果删掉，应该是显式决定，而不是顺手丢失。
• task 事件本身都带 runId / turnId / toolCallId，所以 Working Set 完全可以从 RuntimeEvent 投影出来，不需要再建一个模型自述状态。

所以我的建议是：先别决定实体，先回答产品问题——普通 Session 是否承诺跨 compaction/restart 精确恢复未完成本地步骤？

• 如果承诺：B 是目前最符合 Maka authority / projection 模型的方案。而且 B 应该就是这里说的最小机制：SessionWorkingSet { items: string[] }，一次 replace/clear、一行 current-state、有边界的 turn-tail 注入；不引入 lifecycle、owner、evidence、hierarchy、event sourcing、pagination 或 workflow UI，RuntimeEvent 继续作为 execution truth。
• 如果不承诺：C（直接移除）更简单。
• A（瘦身 Task Ledger）我理解为过渡/兼容选项，不是最终架构方向。

另外，waiting_for_user 不管最后走 B 还是 C，都需要单独定它的去留：要么显式移进 Goal/Session continuation 语义，要么明确放弃。

P0（死代码 + omittedCount 修复）和这个决策独立，可以先推进。

[Astro-Han]

Thanks — the authority-first framing changes the decision for me. I no longer think “13-field Task → 3-field Task” is necessarily the right target.

We should not justify the lightweight Task/Todo mechanism as a model-capability feature: we do not currently have evidence that it improves task completion. A heavier Task design may still be worth evaluating separately, but that experiment should not determine the production architecture here.

I see two coherent end states.

Option 1 — remove the Task Ledger entirely

Choose this if an ordinary Session does not explicitly promise a persistent user-facing progress list.

Remove:

• the Task entity and all task_* tools;
• turn-tail task injection;
• Task persistence and projection;
• Goal gating based on task state;
• child-agent task_id, ownership, claim, and outcome settlement;
• Task query/pagination/revision protocol;
• the Desktop Task panel.

Agent Graph remains the durable work/progress authority for Graph/Swarm sessions. AgentRun and RuntimeEvent remain the execution truth. Existing Task tables stay in place and are not dropped, but the runtime stops reading and writing them.

This is my default recommendation unless we explicitly choose the product promise below.

Option 2 — keep only a user-facing Todo progress snapshot

Choose this only if we explicitly want ordinary Sessions to show the model’s current plan and self-reported progress across compaction and restart.

The complete model-facing contract would be:

todo_write({
  todos: Array<{
    content: string;
    status: 'pending' | 'in_progress' | 'completed';
  }>;
})

Semantics:

• every call replaces the complete current Todo list;
• the list is bounded and persisted per Session;
• the same complete snapshot is re-injected after compaction/restart;
• the Desktop shows it as a read-only checklist;
• users can see all items in the current snapshot but cannot edit or complete them;
• the panel is hidden when the list is empty;
• Graph/Swarm sessions do not expose todo_write, because Agent Graph already owns their progress;
• completed is a model-authored progress claim, not verified execution evidence.

Explicitly absent:

• stable Todo IDs;
• per-item create/update/get/list tools;
• hierarchy, owner, priority, reasons, evidence, timestamps, or transition rules;
• child-agent coordination;
• Goal continuation semantics;
• event sourcing or a workflow audit log;
• pagination or a Task-style workflow UI.

RuntimeEvent continues to own execution history. It may record successful todo_write snapshots for conversation-copy reconstruction, but ordinary execution events cannot infer the model’s private unfinished intentions.

What the usage data means

The fact that models currently use blocked, hierarchy, or child-task binding proves that removing them changes behavior. It does not prove those behaviors belong in this component or are worth preserving. Under both options above, execution coordination remains outside Todo/Task state.

Rollout implication

I suggest holding the proposed P0 rather than modifying code that may be removed immediately. If the architecture decision or implementation will be delayed materially, the omittedCount bug can be fixed independently because it affects current model behavior. The remaining dead-code and protocol cleanup should follow the chosen end state.

So the product question is now narrow:

Do we explicitly want to maintain a persistent, read-only progress checklist for ordinary Sessions?

• If no, choose Option 1 and delete the Task Ledger.
• If yes, choose Option 2 and replace it with the minimal todo_write snapshot above.

I would not keep a slim Task entity as the final architecture.

简体中文对照

从 authority 出发重新审视这个问题后，我的判断发生了变化。我不再认为“13 字段 Task → 3 字段 Task”必然是正确目标。

我们不应把轻量 Task/Todo 机制描述为模型能力特性：目前没有证据表明它能提高任务完成率。重度 Task 设计仍可作为独立实验继续验证，但该实验不应预先决定这里的生产架构。

我认为现在有两个自洽的最终方案。

方案一——完全删除 Task Ledger

如果普通 Session 不明确承诺提供持久的用户可见进度列表，就选择该方案。

删除：

• Task 实体及全部 task_* 工具；
• turn-tail Task 注入；
• Task 持久化和投影；
• 基于 Task 状态的 Goal 门禁；
• 子 Agent 的 task_id、owner、claim 和 outcome settlement；
• Task 查询、分页和 revision 协议；
• Desktop Task 面板。

Graph/Swarm Session 继续由 Agent Graph 持有持久工作和进度状态；AgentRun 与 RuntimeEvent 继续持有真实执行记录。已有 Task 数据表保留，不执行 DROP，但运行时不再读写。

除非我们明确选择下面的产品承诺，否则这是我的默认建议。

方案二——只保留面向用户的 Todo 进度快照

只有当我们明确希望普通 Session 在 context compaction 和重启后，仍向用户展示模型当前计划及其自报进度时，才选择该方案。

完整的模型工具契约是：

todo_write({
  todos: Array<{
    content: string;
    status: 'pending' | 'in_progress' | 'completed';
  }>;
})

语义：

• 每次调用整体替换当前完整 Todo 列表；
• 列表有明确上限，并按 Session 持久化；
• compaction 或重启后重新注入同一份完整快照；
• Desktop 将其展示为只读 checklist；
• 用户能查看当前快照中的全部事项，但不能编辑或点击完成；
• 列表为空时隐藏面板；
• Graph/Swarm Session 不提供 todo_write，因为 Agent Graph 已经持有其进度；
• completed 只是模型自报的进度，不是经过验证的执行证据。

明确不包含：

• 稳定 Todo ID；
• 逐项 create/update/get/list 工具；
• 层级、owner、priority、原因、证据、时间戳或状态转换规则；
• 子 Agent 执行协调；
• Goal continuation 语义；
• event sourcing 或 workflow 审计日志；
• 分页或 Task 风格的 workflow UI。

RuntimeEvent 继续持有执行历史。它可以记录成功的 todo_write 快照，用于 conversation copy 的历史状态恢复；但普通执行事件无法自动推断模型尚未完成的私人意图。

如何理解现有使用数据

模型当前确实使用了 blocked、层级或 child-task binding，这只能证明删除它们会改变行为，不能证明这些行为属于该组件或值得保留。无论选择上述哪个方案，执行协调都不再属于 Todo/Task 状态。

对 rollout 的影响

我建议暂缓原定 P0，避免先修改一批很快可能被整体删除的代码。如果架构决定或实现会明显延后，可以单独修复 omittedCount，因为它正在影响当前模型行为。其余死代码和协议清理应跟随最终方案一起完成。

因此现在只剩一个明确的产品问题：

我们是否明确希望普通 Session 持有一份持久、只读的用户进度 checklist？

• 如果不需要，选择方案一，完全删除 Task Ledger。
• 如果需要，选择方案二，用上面的最小 todo_write 快照替代它。

我不建议把精简后的 Task 实体作为最终架构。

AI assistance disclosure: Codex helped structure and draft this comment. I reviewed the issue discussion and own the final position.

[somewan820]

Proposal: adopt Option 2 — a Session-local Todo projection — as the end state, coordinated with #2560 and #2595

This comment distinguishes repository facts, observations, and proposals. I am not treating the proposal as already settled.

What I verified in the current code

• Task Ledger limits today are TASK_LEDGER_MAX_TASKS = 200, TASK_LEDGER_PROMPT_MAX_CHARS = 8_000, TASK_LEDGER_PROMPT_RECENT_TERMINAL = 3 (packages/core/src/task-ledger.ts:18-29). There is no current 20 active cap; that was a proposal in this RFC.
• The Goal gate only treats pending / in_progress tasks as actionable (packages/runtime/src/goal-task-gate-policy.ts:22, packages/runtime-host/src/server/execution-composition.ts:1125). resumeTrust is not part of that filter.
• Session and AgentRun already carry lifecycle states including waiting_for_user and blocked (packages/runtime-host/src/protocol/session-continuity.ts:31-52, packages/core/src/agent-run.ts:25-31, packages/runtime/src/session-projection-helpers.ts:96-103).
• agent_spawn accepts an optional task_id (packages/runtime/src/subagent-tools.ts:81,123), and Task Ledger owns claimAvailable / settleAgentOutcome (packages/storage/src/task-ledger-store.ts:386,468).
• Desktop reads the ledger through the paginated task.ledger.query protocol (apps/desktop/src/main/runtime-host-client.ts:1075), and the turn tail is injected by renderTaskLedgerTail (packages/runtime-host/src/server/interactive-run-composer.ts:669).

Observation

In my 5 tested sessions, the Task Ledger was the mechanism that preserved unfinished local steps across restart (1 in_progress + 1 pending survived). This is an observation with n=5, not a repository-wide proof that no other persistence surface plays that role.

Recommendation

I recommend Option 2, but framed as a projection rather than a second authority:

Session continuation state (existing authority)
        ↓ projection / snapshot
SessionTodo (user-visible, Session-local)

SessionTodo would not be an execution authority or a continuation authority. If Session continuation state can carry the model's pending local steps, SessionTodo should be derived from it rather than stored in parallel. Whether Session continuation already owns those facts is an open question I want maintainers to confirm.

Target contract (proposal)

todo_write({
  todos: Array<{
    content: string;
    status: 'pending' | 'in_progress' | 'completed';
  }>
})

Proposed semantics:

• every call replaces the complete list;
• persisted per Session, or derived from Session continuation state; bounded; re-injected after compaction/restart;
• Desktop shows a read-only checklist; hidden when empty;
• Graph/Swarm sessions do not expose todo_write, because Agent Graph already owns their progress;
• completed is a model-authored progress claim.

To prevent future conflation:

Todo.completed      = "the model believes this step is done"
AgentRun completed  = "the execution produced a terminal outcome"
Completion Packet   = "the result satisfies the completion contract"  (proposed in #2469)

Answers to the open questions

1. blocked — I propose it should be owned by Session/AgentRun continuation semantics rather than represented as a Todo status. This needs to align with roadmap(product): evolve Maka into a durable Agent workspace #2469 and the Session contract; I am not deciding it unilaterally. The child-agent waiting_for_user → blocked mapping must be preserved at that boundary.
2. Subagent binding — remove task_id / claim / settle from the Task Ledger. Delegation ownership belongs to Agent Graph. A graph-scoped signal (see Design discussion: graph-scoped agent signals and general inter-agent communication #2595) may communicate coordination state, but it is not itself an ownership protocol.
3. failed / cancelled — remove from Todo. Execution outcomes live in AgentRun / RuntimeEvent.
4. completionEvidence — remove from Todo. Today, execution facts live in RuntimeEvent; a Completion Packet is a roadmap(product): evolve Maka into a durable Agent workspace #2469 roadmap item and is not yet implemented in main. The safe dependency is: completion semantics would be projected from RuntimeEvent facts, with the Completion Packet as the proposed vehicle, pending roadmap(product): evolve Maka into a durable Agent workspace #2469.
5. Cap — the Todo surface must be bounded. 20 active + 3 terminal is an initial proposal only; the current code has 200 total / 8000 chars / 3 recent terminal, so any new cap must be confirmed by render/context-budget measurements.
6. task_list / task_get — they become unnecessary as Task Ledger APIs because SessionTodo would be exposed as current Session state rather than a queryable task collection. Whether a read-only observation tool is still needed is a separate open question.

Relationship to #2560 and #2595

Neither issue depends on the Task Ledger; I am not making design decisions for them. I am stating proposed boundaries so their scopes cannot accidentally inherit ledger semantics:

• product(desktop): capture deferred work in a project-aware Work Board #2560 — Phase 0 would not read/write Task Ledger tables, use task.ledger.query, or use task_* tools; it would project status from Session / AgentRun / RuntimeEvent / Agent Graph. Under Option 2, "start as task" would create a Session and may seed a Todo snapshot; that behavior is not final until both contracts agree.
• Design discussion: graph-scoped agent signals and general inter-agent communication #2595 — a signal contract would use Graph operator/edge and RuntimeEvent identities only, with no task_id / claim / settle dependency. Ownership, lease, retry, and settlement semantics would remain in Agent Graph.

Revised rollout

• P0: only the omittedCount fix now (it affects current model behavior). Hold the rest of the cleanup until Option 2 is confirmed.
• P1: decide whether SessionTodo is a persisted snapshot or a projection of Session continuation state, then define the contract and single current-state table.
• P2: remove task_* tools, task.ledger.query, claim / settle / claimAvailable, resumeTrust, parentId, evidence fields, and the Desktop Task panel; migrate waiting_for_user to Session continuation semantics; keep old tables read-only to reduce migration risk.
• P3: integrate with product(desktop): capture deferred work in a project-aware Work Board #2560 Phase 3 and Design discussion: graph-scoped agent signals and general inter-agent communication #2595 once their contracts land.

What I need from maintainers

1. Do you accept Option 2 as the target, with SessionTodo framed as a projection rather than a second authority?
2. Does Session continuation state currently own pending local steps, or should SessionTodo be a persisted snapshot?
3. Can I proceed with the omittedCount fix as an independent PR now?
4. Should product(desktop): capture deferred work in a project-aware Work Board #2560 Phase 0 and the Design discussion: graph-scoped agent signals and general inter-agent communication #2595 design discussion proceed in parallel as ledger-independent work?

简体中文

方案：采用 Option 2 —— Session-local Todo projection 作为最终形态，并与 #2560/#2595 对齐

本条评论区分了仓库事实、观察和提议，不把提议当成已经定案。

我在当前代码中核实的内容

• 当前 Task Ledger 上限是 TASK_LEDGER_MAX_TASKS = 200、TASK_LEDGER_PROMPT_MAX_CHARS = 8000、TASK_LEDGER_PROMPT_RECENT_TERMINAL = 3（packages/core/src/task-ledger.ts:18-29）。当前没有“20 active”上限，那是 RFC 里的提议。
• Goal gate 只把 pending / in_progress 视为 actionable（goal-task-gate-policy.ts:22、execution-composition.ts:1125），resumeTrust 不参与该过滤。
• Session 与 AgentRun 已经有 waiting_for_user / blocked 生命周期状态（session-continuity.ts:31-52、agent-run.ts:25-31、session-projection-helpers.ts:96-103）。
• agent_spawn 有可选 task_id（subagent-tools.ts:81,123），Task Ledger 持有 claimAvailable / settleAgentOutcome（task-ledger-store.ts:386,468）。
• Desktop 通过分页的 task.ledger.query 读取（runtime-host-client.ts:1075），turn tail 由 renderTaskLedgerTail 注入（interactive-run-composer.ts:669）。

观察

在我的 5 个测试会话中，Task Ledger 是保存未完成本地步骤跨重启的机制（1 个 in_progress + 1 个 pending 存活）。这是 n=5 的观察，不是“没有其他持久化面承担该职责”的仓库级证明。

建议

我推荐 Option 2，但定位为 projection 而不是第二 authority：

Session continuation state（现有权威）
        ↓ projection / snapshot
SessionTodo（用户可见、Session-local）

SessionTodo 不是执行权威，也不是 continuation 权威。如果 Session continuation state 能携带模型的 pending local steps，SessionTodo 应从它派生，而不是平行存储。Session continuation 目前是否拥有这些事实，是需要 maintainer 确认的开放问题。

目标契约（提议）

todo_write({
  todos: Array<{
    content: string;
    status: 'pending' | 'in_progress' | 'completed';
  }>
})

提议语义：

• 每次调用整体替换完整列表；
• 按 Session 持久化，或从 Session continuation state 派生；有上限；compaction/重启后重新注入；
• Desktop 以只读 checklist 展示，为空时隐藏；
• Graph/Swarm Session 不暴露 todo_write，因为 Agent Graph 已持有其进度；
• completed 只是模型自报的进度声明。

防止后续混淆：

Todo.completed      = "模型认为这步做完了"
AgentRun completed  = "执行产生了终态结果"
Completion Packet   = "结果满足完成契约"（#2469 中的提议）

开放问题回答

1. blocked —— 我提议由 Session/AgentRun continuation 语义持有，而不是作为 Todo 状态。这需要与 roadmap(product): evolve Maka into a durable Agent workspace #2469 和 Session contract 对齐，不是在这里单方面决定；子代理 waiting_for_user → blocked 映射必须保留。
2. 子代理绑定 —— 从 Task Ledger 移除 task_id / claim / settle。委派归属属于 Agent Graph。Graph-scoped signal（见 Design discussion: graph-scoped agent signals and general inter-agent communication #2595）可以传递协调状态，但它本身不是 ownership 协议。
3. failed / cancelled —— 从 Todo 移除。执行结果由 AgentRun / RuntimeEvent 持有。
4. completionEvidence —— 从 Todo 移除。当前执行事实在 RuntimeEvent；Completion Packet 是 roadmap(product): evolve Maka into a durable Agent workspace #2469 的 roadmap 项，main 尚未实现。安全表述是：完成语义从 RuntimeEvent facts 投影，Completion Packet 是提议载体，依赖 roadmap(product): evolve Maka into a durable Agent workspace #2469。
5. 上限 —— Todo 必须有界。20 active + 3 terminal 只是初始提议；当前代码是 200 total / 8000 chars / 3 recent terminal，新上限必须由渲染/上下文预算测量确认。
6. task_list / task_get —— 它们作为 Task Ledger API 不再必要，因为 SessionTodo 会是当前 Session state 而不是可查询任务集合。是否仍需要只读观察工具是独立开放问题。

与 #2560/#2595 的关系

两个 issue 都不依赖 Task Ledger；我不为它们做设计决定，只声明提议边界，防止它们意外继承 ledger 语义：

• product(desktop): capture deferred work in a project-aware Work Board #2560 —— Phase 0 不读写 Task Ledger 表、不使用 task.ledger.query 或 task_* 工具；状态从 Session / AgentRun / RuntimeEvent / Agent Graph 投影。按 Option 2，“start as task”会创建 Session 并可能注入 Todo 快照；该行为在两个契约达成前不算最终决定。
• Design discussion: graph-scoped agent signals and general inter-agent communication #2595 —— 信号契约只使用 Graph operator/edge 和 RuntimeEvent 身份，不依赖 task_id / claim / settle；ownership、lease、retry、settlement 语义留在 Agent Graph。

修订后的执行计划

• P0：现在只做 omittedCount 修复（它影响当前模型行为）。其余清理等 Option 2 确认。
• P1：先决定 SessionTodo 是持久化快照还是 Session continuation state 的 projection，再定义契约和单张 current-state 表。
• P2：移除 task_* 工具、task.ledger.query、claim / settle / claimAvailable、resumeTrust、parentId、evidence 字段和 Desktop Task 面板；迁移 waiting_for_user 到 Session continuation 语义；旧表只读以降低迁移风险。
• P3：在 product(desktop): capture deferred work in a project-aware Work Board #2560 Phase 3 和 Design discussion: graph-scoped agent signals and general inter-agent communication #2595 契约落地后集成。

需要 maintainer 确认

1. 是否接受 Option 2，并把 SessionTodo 定位为 projection 而非第二权威？
2. Session continuation state 目前是否拥有 pending local steps，还是 SessionTodo 需要持久化快照？
3. 我现在是否可以独立提交 omittedCount 修复 PR？
4. product(desktop): capture deferred work in a project-aware Work Board #2560 Phase 0 和 Design discussion: graph-scoped agent signals and general inter-agent communication #2595 设计讨论是否可以并行推进，且不依赖 Task Ledger？