product(desktop): capture deferred work in a project-aware Work Board #2560

Activity

1. somewan820 commented on Aug 14, 2026

   

   somewan820

   on Aug 14, 2026

   Contributor

   More actions

   Hi, I'd like to take Phase 0 of this issue.

   I'm also the assignee of #2290 (Session Task Ledger), so I want to state the boundary explicitly: Phase 0 would define the BoardItem contract and persistence ownership without depending on the Session Task Ledger. That means:

   • no task_* tools;
   • no task.ledger.query;
   • no reads/writes to workflow_task_ledger_* tables;
   • linked Session status projected from Session / AgentRun / RuntimeEvent / Agent Graph authorities;
   • under the Option 2 proposal in RFC: Radically slim the Session Task Ledger #2290, "start as task" would create a normal Session and may seed a minimal Todo snapshot. That behavior is not final until the RFC: Radically slim the Session Task Ledger #2290 and product(desktop): capture deferred work in a project-aware Work Board #2560 contracts are agreed, and Phase 0 does not depend on it.

   I'll post the BoardItem contract, provenance model, and state-projection boundary here for review before opening a PR. Could you assign me?

   简体中文

   你好，我想接手本 issue 的 Phase 0。

   我也是 #2290（Session Task Ledger）的 assignee，所以先明确边界：Phase 0 将定义 BoardItem 契约和持久化归属，不依赖 Session Task Ledger。具体包括：

   • 不使用 task_* 工具；
   • 不使用 task.ledger.query；
   • 不读写 workflow_task_ledger_* 表；
   • 关联 Session 状态从 Session / AgentRun / RuntimeEvent / Agent Graph 权威投影；
   • 按 RFC: Radically slim the Session Task Ledger #2290 的 Option 2 提议，“start as task”会创建普通 Session，并可能注入极简 Todo 快照。该行为在 RFC: Radically slim the Session Task Ledger #2290 与 product(desktop): capture deferred work in a project-aware Work Board #2560 契约达成前不算最终决定，Phase 0 不依赖它。

   我会先把 BoardItem 契约、provenance 模型和状态投影边界发在这里评审，再开 PR。能把我 assign 上吗？
2. liugddx

   assigned

   somewan820

   on Aug 14, 2026
3. somewan820 commented on Aug 14, 2026

   

   somewan820

   on Aug 14, 2026

   Contributor

   More actions

   Phase 0 — BoardItem contract, provenance model, and state-projection boundary

   This is the Phase 0 review post I promised: define the minimal BoardItem contract and lifecycle, decide the local persistence owner and mutation boundary, define typed provenance references and project/global scope, and specify how linked Session status is projected without copying Runtime state. No PR is opened yet — I'll wait for review convergence (and the current stabilization window) before writing code.

   ---

   1. Repository facts I verified on main

   • Session statuses are active / running / waiting_for_user / blocked / review / done / archived / aborted (packages/core/src/session.ts, packages/runtime-host/src/protocol/session-continuity.ts).
   • AgentRun statuses are created / running / waiting_for_user / completed / failed / cancelled (packages/core/src/agent-run.ts).
   • Projects have a stable catalog identity (ProjectRecord.id) in the operational-state database (packages/storage/src/project-catalog.ts).
   • Side chats are temporary forks with a parent Session id and durable message ids; the fork is deleted when the panel closes (docs/side-conversation.md).
   • The operational-state database (runtime.sqlite, OPERATIONAL_STATE_DATABASE_NAME) is the shared local authority for session metadata, project catalog, scheduled tasks, task ledger, and related workflow state. createOperationalStateBackup snapshots the whole database, so a new table in that DB is automatically covered by the existing backup/restore story.
   • The workflow schema is currently version 8 and uses additive CREATE TABLE IF NOT EXISTS migrations with record_json rows (packages/storage/src/sqlite-workflow-schema.ts).
   • The Desktop task panel already follows the pattern I'd reuse: main process owns the store, the renderer reads a projection through IPC, and store changes emit a signal-only change event that makes the renderer reload (docs/session-task-ledger-lifecycle.md).

   ---

   2. BoardItem contract (proposal)

   export const WORK_BOARD_ITEM_SCHEMA_VERSION = 1;
   
   // Proposed bounds (numbers are placeholders to verify during P1 rendering):
   export const WORK_BOARD_TITLE_MAX_CHARS = 240;
   export const WORK_BOARD_NOTES_MAX_CHARS = 4_000;
   export const WORK_BOARD_MAX_ITEMS = 1_000;
   export const WORK_BOARD_MAX_LINKED_SESSIONS = 16;
   
   export type WorkBoardScope =
     | { kind: 'inbox' }
     | { kind: 'project'; projectId: string };
   
   // User-owned intent state only. "Inbox" is a scope, not a status (Q1 below).
   export type WorkBoardItemState = 'todo' | 'in_progress' | 'done';
   
   export type WorkBoardCreator =
     | { kind: 'user' }
     | { kind: 'agent_suggestion'; confirmedAt: number };
   
   export type WorkBoardProvenance =
     | { kind: 'manual' }
     | {
         kind: 'conversation';
         origin: 'main' | 'side_chat';
         sessionId: string;
         parentSessionId?: string; // side_chat only
         messageId: string;
         runId?: string;
         turnId?: string;
         capturedAt: number;
         excerpt: string; // bounded snapshot so the item survives side-chat deletion
       };
   
   export interface WorkBoardLinkedSessionRef {
     sessionId: string;
     linkKind: 'started_task';
     linkedAt: number;
   }
   
   // Phase 4 will map Completion Packet deliverables (#2469) into this union.
   export type WorkBoardResultRef =
     | { kind: 'runtime_event'; sessionId: string; runId: string; turnId: string; toolCallId?: string }
     | { kind: 'artifact'; sessionId: string; artifactId: string }
     | { kind: 'completion_packet'; sessionId: string; packetRef: string }; // reserved
   
   export interface WorkBoardItem {
     schemaVersion: typeof WORK_BOARD_ITEM_SCHEMA_VERSION;
     id: string; // durable UUID, never rewritten
     scope: WorkBoardScope;
     title: string;
     notes?: string;
     state: WorkBoardItemState;
     archived: boolean;
     archivedAt?: number;
     createdAt: number;
     updatedAt: number;
     creator: WorkBoardCreator;
     provenance: WorkBoardProvenance;
     linkedSessions: WorkBoardLinkedSessionRef[];
     resultRefs: WorkBoardResultRef[];
   }

   Lifecycle decisions in this proposal:

   • scope and state are separate axes. Inbox is a bucket; an Inbox item still has a user state. The board UI may render Inbox as a column, but the contract does not overload "inbox" into a status.

   • Allowed state transitions (user-confirmed only):

     todo -> in_progress
     in_progress -> todo        (user reopen/manual)
     in_progress -> done        (user-confirmed completion, never automatic)
     done -> todo | in_progress (reopen)
     

   • archived is a logical hide flag, not a state. Storage keeps the row; reads exclude archived items unless explicitly requested. No hard delete in v1 (Q5).

   • Scope changes (inbox <-> project) are allowed in any state and do not reset the user state.

   • done is user intent, never derived from a Session. Completing or failing a linked Session only updates the projected chip; the user confirms completion or reopens the item.

   • No task_* tools, no task.ledger.query, and no workflow_task_ledger_* reads/writes anywhere in this feature.

   ---

   3. Provenance model

   • Provenance is a typed union, not free text. Conversation capture stores sessionId, messageId, and (when available) runId / turnId. Side-chat capture also stores parentSessionId.
   • A bounded excerpt is snapshotted into the item at capture time. This is what makes a side-chat item survive the temporary fork's deletion; the typed refs are best-effort links, not hard dependencies.
   • Manual items have provenance.kind = 'manual'.
   • Agent suggestions are not silently created: creator.kind = 'agent_suggestion' requires confirmedAt, and creation only happens through an explicit user action or unambiguous instruction. The board never writes itself.
   • resultRefs is part of the contract shape now, but population happens in Phase 3/4. Phase 0 only fixes validation and the union.

   ---

   4. Persistence owner and mutation boundary

   Proposal:

   • Owner: a new WorkBoardStore in packages/storage, backed by the operational-state database (runtime.sqlite), following the existing record_json pattern.

   • Table (additive migration, workflow schema 8 → 9):

     CREATE TABLE IF NOT EXISTS workflow_work_board_items (
       item_id TEXT PRIMARY KEY,
       created_at INTEGER NOT NULL,
       updated_at INTEGER NOT NULL,
       scope_kind TEXT NOT NULL CHECK (scope_kind IN ('inbox', 'project')),
       project_id TEXT,
       record_json TEXT NOT NULL
     );
     
     CREATE INDEX IF NOT EXISTS workflow_work_board_items_scope_order
       ON workflow_work_board_items(scope_kind, project_id, updated_at DESC, item_id);

   • Single writer: the Desktop main process. The renderer gets a read-only projection through IPC and reloads on a signal-only change event (same pattern as the task panel). Runtime Host is not involved; there are no model-visible tools; the board is never injected into model context or the turn tail.

   • Backup/migration: because the table lives in runtime.sqlite, the existing createOperationalStateBackup covers it without manifest changes. Migration is additive only, no DROP, no data loss; the migration test inventory is updated.

   • CLI/TUI can read the same store later through a shared projection, but v1 mutation is Desktop-only (Q8).

   ---

   5. State-projection boundary

   The stored item never carries execution state. A linked Session's status is projected at read time from existing authorities:

   export interface WorkBoardExecutionProjection {
     sessionId: string;
     sessionStatus: SessionStatus | 'missing';
     latestRunStatus?: AgentRunStatus;
     activeTurnId?: string;
     activeRunId?: string;
     recoveryState?:
       | 'safe_retry'
       | 'safe_continue'
       | 'needs_revalidation'
       | 'unknown_side_effects'
       | 'requires_decision';
     graphState?: {
       graphId: string;
       workId?: string;
       operatorId?: string;
     };
   }

   • Sources: SessionContinuitySnapshot (session lifecycle), AgentRun headers (latest run), RuntimeEvent (execution facts), and Agent Graph (delegated work) — exactly the authorities listed in RFC: Radically slim the Session Task Ledger #2290's boundary comment.
   • This is a pure read projection: it never writes to the board, never copies runtime state into record_json, and never mutates a Session.
   • "Waiting / blocked / recoverable" wording in the UI is derived from the projection above, not from a second manually maintained board status.
   • The projection is recomputed on each render/load; it is not persisted.

   ---

   6. Phase 0 contract tests (proposed)

   • work-board-item.test.ts: decode/validate the item schema; state transition whitelist; scope/provenance invariants; field and array bounds; archive idempotency.
   • work-board-store.test.ts: create/rename/move/complete/reopen/archive; persistence across store reopen; filtering by inbox/project and archived; additive migration from schema 8.
   • work-board-backup.test.ts: a board item survives createOperationalStateBackup → restore.
   • work-board-projection.test.ts: given fixture Session/AgentRun/RuntimeEvent/Graph facts, the projection returns the expected chip without writing anything.

   ---

   7. Open questions for maintainers

   1. Inbox: scope or status? I propose scope. The issue lists "Inbox" under minimal states, so I want explicit confirmation before P1.
   2. Persistence owner: operational-state database in the Desktop main process — acceptable, or do you want a separate local-first store?
   3. Event log vs single current-state table: I propose a single current-state table (no event sourcing for the board; audit remains RuntimeEvent's job). OK?
   4. Archive vs delete: I propose archive-only in v1, with no hard delete. OK?
   5. resultRefs in Phase 0: keep the union shape now (validated, unused until Phase 3/4), or move it entirely to Phase 4?
   6. Projection precedence: when Session continuity and the latest AgentRun disagree (e.g., Session done but last run failed), I propose showing both raw facts without synthesizing a verdict. Agree?
   7. Bounds: 240 title chars, 4_000 notes chars, 1_000 items, 16 linked sessions are placeholders — should they be tightened or confirmed during P1?
   8. Mutation scope: Desktop-only writer in v1, with CLI/TUI as read-only consumers later. Agree?

   Once these converge, I'll open the Phase 0 PR: contract types + validation, additive migration, store, projection tests, and backup test — still without any UI or Runtime Host changes.

   简体中文

   Phase 0 — BoardItem 契约、来源模型与状态投影边界

   这是我在 #2560 里承诺的 Phase 0 评审稿：定义最小 BoardItem 契约与生命周期、确定本地持久化归属和写入边界、定义强类型来源引用与项目/全局范围，并说明如何从现有权威投影关联 Session 状态，而不复制 Runtime 状态。暂不开 PR，等 review 收敛（以及当前稳定化窗口）后再写代码。

   已核实的仓库事实

   • Session 状态：active / running / waiting_for_user / blocked / review / done / archived / aborted。
   • AgentRun 状态：created / running / waiting_for_user / completed / failed / cancelled。
   • 项目有稳定 catalog identity（ProjectRecord.id）。
   • 侧边栏对话是临时 fork，有父 Session id 和持久 message id，关闭面板时删除。
   • runtime.sqlite 是共享本地权威库（session metadata、project catalog、scheduled tasks、task ledger 等都在这里）；现有备份会整体快照该库，因此新表自动纳入备份。
   • workflow schema 当前为 v8，采用增量 CREATE TABLE IF NOT EXISTS + record_json 模式。
   • Desktop task 面板已采用「主进程持 store、渲染层经 IPC 读投影、变更只发 signal 后重载」的模式，Work Board 直接复用。

   BoardItem 契约（提议）

   type WorkBoardScope =
     | { kind: 'inbox' }
     | { kind: 'project'; projectId: string };
   
   type WorkBoardItemState = 'todo' | 'in_progress' | 'done';
   
   type WorkBoardCreator =
     | { kind: 'user' }
     | { kind: 'agent_suggestion'; confirmedAt: number };
   
   type WorkBoardProvenance =
     | { kind: 'manual' }
     | {
         kind: 'conversation';
         origin: 'main' | 'side_chat';
         sessionId: string;
         parentSessionId?: string;
         messageId: string;
         runId?: string;
         turnId?: string;
         capturedAt: number;
         excerpt: string; // 有界快照，侧边栏删除后事项仍可读
       };
   
   interface WorkBoardLinkedSessionRef {
     sessionId: string;
     linkKind: 'started_task';
     linkedAt: number;
   }
   
   interface WorkBoardItem {
     schemaVersion: 1;
     id: string;
     scope: WorkBoardScope;
     title: string;
     notes?: string;
     state: WorkBoardItemState;
     archived: boolean;
     archivedAt?: number;
     createdAt: number;
     updatedAt: number;
     creator: WorkBoardCreator;
     provenance: WorkBoardProvenance;
     linkedSessions: WorkBoardLinkedSessionRef[];
     resultRefs: WorkBoardResultRef[]; // Phase 4 再填充，Phase 0 只定形状
   }

   关键决定：

   • Inbox 是 scope，不是 status；UI 可以把它渲染成一列，但契约不把「inbox」重载成状态。
   • 状态转换只有用户确认：todo -> in_progress、in_progress -> todo/done、done -> todo/in_progress（reopen）。完成态不会由 Session 自动推导。
   • archived 是逻辑隐藏标记，v1 不做硬删除。
   • 来源是强类型 union，不是自由文本；对话捕获保存 sessionId/messageId（有则含 runId/turnId），侧边栏另存 parentSessionId；同时落一份有界 excerpt 快照。
   • Agent 建议必须 confirmedAt 且由用户明确确认，绝不静默创建。
   • 全功能不使用 task_* 工具、task.ledger.query，不读写 workflow_task_ledger_*。

   持久化归属与写入边界

   • 新增 packages/storage 的 WorkBoardStore，落在 runtime.sqlite，沿用 record_json 模式。
   • 新表 workflow_work_board_items（item_id PK + created_at/updated_at/scope_kind/project_id/record_json），workflow schema 8 → 9 增量迁移，不 DROP、不删数据。
   • 唯一写入方是 Desktop 主进程；渲染层经 IPC 只读投影，变更后重载。Runtime Host 不参与、无模型工具、不注入模型上下文。
   • 备份：整库快照自动覆盖，无 manifest 改动。

   状态投影边界

   • 存储层永不保存执行状态。关联 Session 状态在读取时从 SessionContinuitySnapshot、AgentRun、RuntimeEvent、Agent Graph 纯投影：

   interface WorkBoardExecutionProjection {
     sessionId: string;
     sessionStatus: SessionStatus | 'missing';
     latestRunStatus?: AgentRunStatus;
     activeTurnId?: string;
     activeRunId?: string;
     recoveryState?: 'safe_retry' | 'safe_continue' | 'needs_revalidation' | 'unknown_side_effects' | 'requires_decision';
     graphState?: { graphId: string; workId?: string; operatorId?: string };
   }

   • 投影是纯读操作：不写看板、不复制 Runtime 状态、不改 Session。「等待 / 阻塞 / 可恢复」等 UI 文案全部来自投影，不是第二套手工状态。

   Phase 0 测试

   • 契约编解码与状态转换白名单；
   • store 的增改/移动/完成/重开/归档、重开持久化、过滤、迁移；
   • 备份/恢复后事项仍在；
   • 投影纯函数测试：给定 Session/AgentRun/RuntimeEvent/Graph 夹具，只返回结果、不产生任何写入。

   开放问题

   1. Inbox 是 scope 还是 status？（我提议 scope）
   2. 持久化放 operational-state DB、由 Desktop 主进程写入，是否可以？
   3. 看板用单张当前状态表、不做事件溯源，是否可以？
   4. v1 只归档不硬删，是否可以？
   5. resultRefs 现在只定形状、Phase 3/4 再填充，还是整体推到 Phase 4？
   6. Session 与最新 AgentRun 状态不一致时（如 Session done、run failed），投影同时展示两个原始事实、不做合成结论，是否可以？
   7. 各项上限（240 标题 / 4000 备注 / 1000 事项 / 16 关联 Session）是否合理？
   8. v1 只允许 Desktop 写入，CLI/TUI 后续只读，是否可以？

   以上收敛后我会开 Phase 0 PR：契约类型 + 校验、增量迁移、store、投影测试和备份测试，不含 UI 与 Runtime Host 改动。

   ---

   AI assistance disclosure: Codex helped structure and draft this comment. I reviewed the issue discussion and the repository facts above, and I own the final position.
4. liugddx commented on Aug 14, 2026

   

   liugddx

   on Aug 14, 2026

   MemberAuthor

   More actions

   Thanks for taking the time to investigate this issue so thoroughly and for writing down the authority boundary before opening a PR. The main direction is sound, especially the separation from the Session Task Ledger, keeping execution state as a projection, using the operational-state database, and requiring explicit user confirmation for agent suggestions.

   I would support Phase 0 after the following contract issues are resolved:

   1. The 1,000-item limit conflicts with archive-only retention. If archived rows count toward the limit, a user eventually becomes permanently unable to create items. If they do not count, storage remains unbounded. Phase 0 should define whether the limit applies to active items, each scope, or the whole database, and what happens at the limit. My preference is no total-item hard cap in Phase 0: bound page/query size instead, and allow permanent deletion of archived items.

   2. The lifecycle should allow todo -> done. A Work Board item represents user intent, not proof of execution. Users should be able to complete an item without first starting a Session or moving it through in_progress. Suggested transitions:

      todo <-> in_progress
      todo -> done
      in_progress -> done
      done -> todo | in_progress
      

   3. The execution projection is broader than the stable authority currently exposed. latestRunStatus, the proposed synthetic recoveryState, and graphState are not all directly available from one current canonical projection. Recomputing them from Session, AgentRun, RuntimeEvent, and Agent Graph on every list load also leaves query cost and consistency undefined, particularly with up to 1,000 items and 16 links per item.

      Please keep Phase 0 to facts directly available from the current continuity contract, for example:

      interface WorkBoardLinkedSessionProjection {
        sessionId: string;
        sessionStatus: SessionStatus | 'missing';
        currentTurn?: {
          turnId: string;
          runId: string;
          status: TurnStatus;
        };
      }

      Add recovery or graph-derived fields only after a canonical read interface and an actual UI requirement exist. The board should not invent a second recovery verdict while trying to avoid a second execution authority.

   4. Move resultRefs entirely to Phase 4. The proposed union prematurely fixes artifact identity, Completion Packet identity, and RuntimeEvent addressing before their consumers and contracts have converged. A reserved but persisted field is still a compatibility commitment. Adding an optional field in a later schema is safer than guessing the future reference model now.

   5. Encode provenance invariants in the type. The current shape permits both a main-conversation provenance with parentSessionId and a side-chat provenance without it. Please split those into distinct discriminated variants so parentSessionId is required only for side_chat.

      Likewise, enforce the archive invariant: active items must not have archivedAt, while archived items must have it. This can be represented as a union or enforced by the decoder.

   6. Enforce scope/project consistency in SQLite. The proposed table currently permits an Inbox row with a project id and a project-scoped row without one. Please add a constraint equivalent to:

      CHECK (
        (scope_kind = 'inbox' AND project_id IS NULL)
        OR
        (scope_kind = 'project' AND project_id IS NOT NULL)
      )

      Reads should also reject disagreement between indexed columns and record_json.scope, otherwise they become competing authorities.

   7. Define mutation concurrency explicitly. updatedAt is not a revision: multiple changes may occur in the same millisecond, and a stale renderer projection could overwrite newer state. The main process should accept semantic patch commands rather than replacement records, serialize/transactionalize mutations, and preferably expose a monotonic revision or CAS contract. Please include a test proving concurrent rename/move/archive operations do not lose updates.

   The following decisions look good and should remain:

   • Inbox is a scope, not a status.
   • Work Board does not read or write Session Task Ledger state.
   • runtime.sqlite owns local persistence.
   • A current-state table is sufficient; no event sourcing is needed.
   • Desktop main is the v1 mutation owner.
   • Runtime state is projected rather than copied into record_json.
   • Side-chat capture retains a bounded excerpt.
   • Agent suggestions require explicit confirmation.
   • Migration, reopen persistence, and backup/restore receive contract tests.

   My suggested minimal Phase 0 is therefore: the strict item/provenance contract, SQLite migration and store, semantic mutations with concurrency behavior, paginated queries, archive/delete behavior, backup/restore tests, and only the smallest linked-session projection supported directly by existing authorities. Defer resultRefs, composite recovery/graph projection, and placeholder total-count limits.

   Overall, this is a strong proposal with the right architectural boundary, but it should be reduced before implementation so Phase 0 remains genuinely minimal.

   中文评审意见

   感谢你认真关注并深入调查这个 Issue，也感谢你在开 PR 前先明确权威边界。方案的主方向是正确的，尤其是与 Session Task Ledger 隔离、运行状态只做投影、使用 operational-state 数据库，以及 Agent 建议必须经过用户明确确认。

   我建议解决以下契约问题后再认可 Phase 0：

   1. 1,000 项上限与只归档不删除冲突。 如果归档项计入上限，用户最终会永久无法创建事项；如果不计入，存储仍然无界。建议 Phase 0 不设总事项硬上限，只限制分页/查询大小，并允许永久删除已归档事项。

   2. 生命周期应允许 todo -> done。 Work Board 表达用户意图，不是执行证明。用户应当能够直接完成尚未启动 Session 的事项，不必先经过 in_progress。

   3. 执行投影超出了当前稳定权威直接提供的范围。 latestRunStatus、综合 recoveryState 和 graphState 并非来自一个现有规范投影；每次列表加载跨 Session、AgentRun、RuntimeEvent、Agent Graph 重算，也没有定义成本和一致性。Phase 0 应只保留当前 continuity contract 直接提供的 Session 状态和当前 turn/run 事实，恢复或图状态等有规范读取接口和真实 UI 需求后再增加。

   4. resultRefs 整体推迟到 Phase 4。 当前 union 提前固定了 Artifact、Completion Packet 和 RuntimeEvent 的引用身份。即使标记为 reserved，只要进入持久化 schema 就成为兼容性承诺。未来按真实契约添加可选字段更安全。

   5. 用类型编码 provenance 不变量。 当前类型允许 main conversation 带 parentSessionId，也允许 side chat 缺少它。应拆成两个 discriminated variants。归档状态也应保证 active 时没有 archivedAt，archived 时必须有。

   6. SQLite 应约束 scope/project 一致性。 Inbox 必须没有 project_id，project scope 必须有。读取时还应验证索引列与 record_json.scope 一致，避免形成两个冲突的事实源。

   7. 明确 mutation 并发契约。 updatedAt 不是 revision，同一毫秒可能发生多次更新，旧 renderer projection 也可能覆盖新状态。主进程应接收语义化 patch command，而不是整个旧 record；mutation 应串行化并置于事务中，最好提供单调 revision 或 CAS，并测试并发 rename/move/archive 不丢更新。

   以下决定可以保留：

   • Inbox 是 scope，不是 status；
   • Work Board 不读写 Session Task Ledger；
   • runtime.sqlite 负责本地持久化；
   • 使用当前状态表，不做事件溯源；
   • Desktop main 是 v1 唯一写入方；
   • Runtime 状态只投影，不复制到 record_json；
   • side chat 保存有界 excerpt；
   • Agent suggestion 必须明确确认；
   • 覆盖迁移、重开持久化和备份恢复测试。

   建议将 Phase 0 收缩为：严格的 item/provenance 契约、SQLite migration 与 store、具有并发语义的命令式 mutation、分页查询、归档/删除行为、备份恢复测试，以及现有权威直接支持的最小 linked-session projection。推迟 resultRefs、综合 recovery/graph 投影和占位性质的总量上限。

   总体而言，这是一份架构边界正确的扎实方案，但实现前还需要继续做减法，确保 Phase 0 真正最小。
5. somewan820 commented on Aug 14, 2026

   

   somewan820

   on Aug 14, 2026

   Contributor

   More actions

   Thanks for the review. I accept all seven points, and I'll narrow Phase 0 accordingly. Revised contract and scope:

   1. No total item cap. Only bound page/query size (default 50, max 100). Archived items can be permanently deleted, and deletion requires archiving first.
   2. Lifecycle: todo <-> in_progress, todo -> done, in_progress -> done, done -> todo | in_progress. Completion is always user intent and is never derived automatically.
   3. Projection stays limited to facts the current continuity contract directly exposes:

   interface WorkBoardLinkedSessionProjection {
     sessionId: string;
     sessionStatus: SessionStatus | 'missing';
     currentTurn?: {
       turnId: string;
       runId: string;
       status: TurnStatus;
     };
   }

   recoveryState / graphState stay out until a canonical read interface and a real UI requirement exist.
   4. resultRefs moves entirely to Phase 4. The Phase 0 schema does not contain the field.
   5. Provenance becomes three discriminated variants: manual / main_conversation / side_conversation. main_conversation rejects parentSessionId; side_conversation requires it. The archive invariant is enforced both in the type and by the decoder (active items have no archivedAt; archived items must have it).
   6. SQLite gains a scope/project CHECK constraint (inbox rows must have project_id IS NULL; project rows must have one). Reads validate that the indexed columns agree with record_json.scope, treating disagreement as corrupt_record.
   7. Mutations are semantic patches (independent title / notes / scope / state fields; notes: null clears), never full-record replacement. Writes are serialized and transactional, each item has a monotonic revision, and mutations accept an optional expectedRevision CAS. A concurrency test proves rename/move/archive do not lose updates.

   Phase 0 deliverables (no UI, no Runtime Host, no model tools):

   • packages/core: BoardItem contract, provenance, lifecycle validation, paginated query;
   • packages/storage: additive workflow schema 8→9 migration (workflow_work_board_items + CHECK + index), WorkBoardStore (create / update / archive / unarchive / remove / paginated list + CAS);
   • a pure linked-session projection function (read-only, writes nothing);
   • tests: contract, migration, reopen persistence, pagination, archive/delete, concurrent CAS, backup/restore, and projection.

   Once this converges, I'll open the Phase 0 PR.

   简体中文

   感谢评审，7 点我都接受，Phase 0 按你的意见收窄。修订后的契约和范围：

   1. 不设总量上限，只做分页/查询上限（默认 50、最大 100）；已归档事项允许永久删除，删除前必须已归档。
   2. 状态转换：todo <-> in_progress、todo -> done、in_progress -> done、done -> todo | in_progress。完成始终是用户意图，不自动推导。
   3. 投影只保留现有 continuity 直接支持的事实：

   interface WorkBoardLinkedSessionProjection {
     sessionId: string;
     sessionStatus: SessionStatus | 'missing';
     currentTurn?: {
       turnId: string;
       runId: string;
       status: TurnStatus;
     };
   }

   recoveryState / graphState 等，等有规范读取接口和真实 UI 需求后再加。
   4. resultRefs 整体移到 Phase 4，Phase 0 schema 不含该字段。
   5. provenance 拆成三个 discriminated variants：manual / main_conversation / side_conversation；main 禁止 parentSessionId，side 必须有；归档不变量用类型 + decoder 双重保证（active 无 archivedAt，archived 必有）。
   6. SQLite 加 scope/project CHECK 约束（inbox 必须无 project_id，project 必须有）；读取时校验索引列与 record_json.scope 一致，不一致按 corrupt_record 处理。
   7. mutation 全部是语义化 patch（title/notes/scope/state 独立字段，notes: null 清除），不替换整条旧记录；写入串行化并事务化；每项有单调 revision，支持 expectedRevision CAS；补并发 rename/move/archive 不丢更新的测试。

   Phase 0 交付范围（不含 UI / Runtime Host / 模型工具）：

   • packages/core：BoardItem 契约、provenance、生命周期校验、分页 query；
   • packages/storage：workflow schema 8→9 增量迁移（workflow_work_board_items + CHECK + 索引）、WorkBoardStore（create / update / archive / unarchive / remove / 分页 list + CAS）；
   • 纯 linked-session 投影函数（只读，不写任何状态）；
   • 测试：契约、迁移、重开持久化、分页、归档/删除、并发 CAS、备份/恢复、投影。

   以上收敛后我再开 Phase 0 PR。

   ---

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

   👍React with 👍1Reacted by Guangdong Liu
6. somewan820 commented on Aug 15, 2026

   

   somewan820

   on Aug 15, 2026

   Last edited by somewan820

   Contributor

   More actions

   Thanks for the review. Phase 0 is now implemented and the PR is ready for review:PR #3028

   The implementation follows the maintainer-approved Phase 0 contract discussed in this issue.

   The latest review also confirmed:

   • All seven Phase 0 contract points remain satisfied.
   • The previously identified P1 around notes: undefined has been fixed.
   • notes patch semantics are now explicitly covered:
     • omitted / undefined → unchanged
     • null / "" / whitespace-only → clear
     • non-empty string → replace
   • Same-millisecond mutations still produce strictly increasing revisions.
   • Malformed record_json fails closed.
   • SQLite scope/project invariants are enforced at the database level and validated on read.
   • No Task Ledger, Runtime Host, model-visible tools, automatic completion, recoveryState, graphState, or resultRefs were introduced.

   The relevant core/storage tests, typechecks, builds, and Biome checks all pass.

   Ready for review. Thanks!

   简体中文

   感谢之前的评审。Phase 0 现在已经完成，并已提交 PR，欢迎 review：PR #3028

   本次实现遵循了这个 Issue 中 maintainer 已确认的 Phase 0 contract。

   最新一轮 review 也确认：

   • 7 项 Phase 0 contract 均保持满足。
   • 之前发现的 notes: undefined P1 已修复。
   • notes 的 patch 语义现在有完整测试覆盖：
     • 缺省 / undefined → 保持不变
     • null / "" / 纯空白字符串 → 清除
     • 非空字符串 → 替换
   • 即使多个 mutation 使用完全相同的毫秒时间戳，revision 仍然严格递增。
   • malformed record_json 会 fail closed。
   • SQLite scope/project invariant 由数据库 CHECK 约束保证，同时读取时也会进行一致性校验。
   • 没有引入 Task Ledger、Runtime Host、model-visible tools、自动完成、recoveryState、graphState 或 resultRefs。

   相关的 core/storage tests、typecheck、build 和 Biome checks 均通过。

   现在可以进行 review 了，谢谢！
7. somewan820 commented on Aug 15, 2026

   

   somewan820

   on Aug 15, 2026

   Contributor

   More actions

   Hi liugddx — PR #3028 (Work Board Phase 0) is ready for review, but Astro-Han's review on the PR raised a product-scope question that I think only you can close, so I am posting the same reconciliation here before pushing any further commits.

   Implementation status (all three findings from Astro-Han's review, fixed in 476eb218b):

   1. Revision CAS — read/check/write is now a single BEGIN IMMEDIATE transaction for update / archive / unarchive / remove, closing the cross-process overwrite race while keeping the in-process write queue.

   2. Linked-session projection — the projector (module, test, and package export) was removed. It was a parallel DTO using Core TurnStatus, which cannot represent waiting_for_user / cancelled from the canonical continuity contract. It will be rebuilt beside the real Runtime Host / Desktop continuity adapter when Phase 3 has a consumer.

   3. Indexes — schema v9 now ships (scope_kind, project_id, updated_at DESC, item_id DESC) and (updated_at DESC, item_id DESC). EXPLAIN QUERY PLAN on populated data confirms no full-table scan or temporary sort for unscoped, scoped, and cursor queries.

   4. Migration test — now builds a schema-8 database from the released v0.1.6 operational-state fixture plus the exact v8 workflow DDL, then runs the real 8→9 migration path.

   On scope: every semantic in PR #3028 maps to your 7-point review (#2560 (comment)) and the accepted revision (#2560 (comment)). #2290's Option 2 governs SessionTodo, not Work Board, and #2290 explicitly allows Phase 0 to proceed independently (#2290 (comment)).

   The only Phase 0 item with no consumer today is linkedSessions: the field exists in the schema, but Phase 0 has no mutation path that writes it and no UI or runtime caller reads it; Phase 3 "start as task" is the intended consumer.

   Could you confirm:

   (a) Phase 0 remains the approved contract after #2290 Option 2, or should it be re-scoped to capture / list / complete / delete with optional project and source context?

   (b) linkedSessions stays in schema v1, or moves to Phase 3 via a future additive migration?

   (c) The linked-session projection is formally deferred, or should Phase 0 include an implementation based on the canonical SessionContinuitySnapshot / TurnSnapshot?

   Once you confirm, I will either keep the PR as-is or apply the narrow change before requesting merge.

   简体中文

   你好 liugddx —— PR #3028（Work Board Phase 0）已经可以 review，但 Astro-Han 在 PR 上提出的产品范围问题，我认为只有你能收口，所以在 push 任何新 commit 之前，把同样的对齐说明发在这里。

   实现状态（Astro-Han review 的三个 finding 已在 476eb218b 修复）：

   1. Revision CAS：update / archive / unarchive / remove 现在是同一个 BEGIN IMMEDIATE 事务内完成 read/check/write，关闭跨进程覆盖竞争，同时保留进程内 write queue。

   2. Linked-session projection：projector（模块、测试、package export）已删除。它是一套平行 DTO，使用 Core TurnStatus，无法表达 canonical continuity 中的 waiting_for_user / cancelled。等 Phase 3 有真实消费者后，再放到 Runtime Host / Desktop continuity adapter 旁边实现。

   3. 索引：schema v9 现在包含 (scope_kind, project_id, updated_at DESC, item_id DESC) 和 (updated_at DESC, item_id DESC)。用真实填充数据跑 EXPLAIN QUERY PLAN 确认：unscoped、scoped 和 cursor 查询都不再全表扫描或临时排序。

   4. Migration 测试：现在用发布的 v0.1.6 operational-state fixture + 精确的 v8 workflow DDL 构造 schema-8 库，走真实 8→9 迁移路径。

   关于范围：PR #3028 的每个 semantic 都能对应你的 7 点 review（https://github.com/maka-agent/maka-agent/issues/2560#issuecomment-5294753604）和已接受的修订版（https://github.com/maka-agent/maka-agent/issues/2560#issuecomment-5294956443）。#2290 的 Option 2 约束的是 SessionTodo，不是 Work Board；#2290 也明确允许 Phase 0 独立推进（https://github.com/maka-agent/maka-agent/issues/2290#issuecomment-5298957426）。

   Phase 0 里唯一今天没有消费者的是 linkedSessions：字段在 schema 里，但 Phase 0 没有任何 mutation 路径写入它，也没有 UI 或 runtime 调用方读取；Phase 3 “start as task” 才是消费者。

   能否确认：

   (a) #2290 Option 2 之后，Phase 0 是否仍然以已批准契约为准，还是收缩为 capture / list / complete / delete + 可选的 project/source context？

   (b) linkedSessions 留在 schema v1，还是移到 Phase 3（未来 additive migration）？

   (c) linked-session projection 是否正式推迟，还是 Phase 0 就要基于 canonical SessionContinuitySnapshot / TurnSnapshot 实现？

   你确认后，我会保持 PR 现状，或先做这个收窄改动再请求 merge。
8. somewan820

   added a commit that references this issue on Aug 15, 2026

   fix(core,storage): defer linkedSessions to Phase 3 and bound active-l…

   ...

   833481e
9. somewan820 commented on Aug 15, 2026

   

   somewan820

   on Aug 15, 2026

   Contributor

   More actions

   Following up on your decisions — PR #3028 now matches the confirmed Phase 0 scope:

   • linkedSessions is deferred to Phase 3 and removed from the Phase 0 contract/store/tests; the Phase 0 contract rejects the field in create input and stored records.
   • The linked-session projection is deferred to Phase 3 and will be implemented against the canonical SessionContinuitySnapshot / TurnSnapshot beside the real continuity adapter.
   • Active-row partial indexes bound the default archived = 0 list queries under archive-heavy data, with regression coverage in the store and migration tests.

   PR #3028 has been updated (commit 833481e64) and is ready for review. Once it passes, Phase 3 can pick up linkedSessions and the projection adapter.

   简体中文

   跟进你的决定——PR #3028 现在与确认后的 Phase 0 范围一致：

   • linkedSessions 推迟到 Phase 3，已从 Phase 0 契约/store/测试中移除；Phase 0 契约会在 create input 和已存记录里拒绝该字段。
   • linked-session projection 推迟到 Phase 3，将在真实 continuity adapter 旁边基于 canonical SessionContinuitySnapshot / TurnSnapshot 实现。
   • 新增 active-row partial index，限制 archive-heavy 数据下默认 archived = 0 list 查询的扫描成本，并已在 store 与 migration 测试中覆盖。

   PR #3028 已更新（commit 833481e64）并 ready for review。通过后，Phase 3 可以接手 linkedSessions 和投影 adapter。
10. liugddx

    added a commit that references this issue on Aug 17, 2026

    feat(core,storage): add Work Board Phase 0 contract and store (#3028)

    ...

    18c526c
11. somewan820 commented on Aug 17, 2026

    

    somewan820

    on Aug 17, 2026

    Contributor

    More actions

    Phase 0 complete — PR #3028 merged

    Work Board Phase 0 has landed via PR #3028 (squash commit 18c526c5a, merged 2026-08-17, approved by both liugddx and Astro-Han).

    What landed:

    • Core: BoardItem contract with discriminated provenance (manual / main_conversation / side_conversation), user-owned lifecycle (todo / in_progress / done), archive invariant, exact-shape validation, and semantic patch semantics.
    • Storage: additive workflow schema 8→9 migration; WorkBoardStore with BEGIN IMMEDIATE transactional writes, monotonic revision + expectedRevision CAS, keyset pagination bound to the query filters, archive-before-delete, active-row partial indexes, and fail-closed corruption detection.
    • Tests: contract, real schema-8→9 migration fixture, backup/restore, archive-heavy index coverage, cross-connection CAS, cursor size/filter regressions.
    • Docs: docs/work-board-contract.md records the boundary, mutation contract, and deferrals.

    Maintainer-confirmed deferrals remain in place: linkedSessions → Phase 3, linked-session projection → Phase 3 (beside the canonical continuity adapter), resultRefs → Phase 4. No Runtime Host, model-visible tools, or turn-tail injection were introduced.

    Next step is Phase 1 (separate kickoff comment follows).

    简体中文

    Phase 0 已完成 — PR #3028 已合并

    Work Board Phase 0 已通过 PR #3028 落地（squash commit 18c526c5a，2026-08-17 合并，liugddx 与 Astro-Han 均已 approve）。

    落地内容：

    • Core：BoardItem 契约（discriminated provenance：manual / main_conversation / side_conversation、用户拥有的三态生命周期 todo / in_progress / done、归档不变量、exact-shape 校验、semantic patch）。
    • Storage：additive 的 workflow schema 8→9 迁移；WorkBoardStore 采用 BEGIN IMMEDIATE 事务、单调 revision + expectedRevision CAS、绑定查询过滤条件的 keyset 分页、先归档后删除、active-row partial index、fail-closed 损坏检测。
    • 测试：契约、真实 schema-8→9 迁移 fixture、备份/恢复、archive-heavy 索引覆盖、跨连接 CAS、cursor 长度与 filter 回归。
    • 文档：docs/work-board-contract.md 记录了边界、mutation 契约与 deferral。

    maintainer 确认的 deferral 保持不变：linkedSessions → Phase 3、linked-session projection → Phase 3（放到 canonical continuity adapter 旁边）、resultRefs → Phase 4。没有引入 Runtime Host、模型可见工具或 turn-tail 注入。

    下一步是 Phase 1（kickoff 评论随后发布）。
12. somewan820 commented on Aug 17, 2026

    

    somewan820

    on Aug 17, 2026

    Contributor

    More actions

    Phase 1 kickoff — Work Board capture/list MVP

    Phase 0 is merged (see previous comment). Per the delivery plan, I'm starting Phase 1: a compact Work Board surface in the existing task/workbar area, with global Inbox + current-project filtering, manual create / rename / move / complete / reopen / archive, and empty / loading / error / offline-local states.

    Implementation slices: main-process WorkBoardStore + IPC → preload bridge → workbar panel. No Runtime Host involvement, no model-visible tools, no turn-tail injection.

    If the panel placement or the Inbox/project filter behavior should differ from the issue, let me know before I wire the UI; otherwise I'll post the Phase 1 PR here when it's ready.

    简体中文

    Phase 1 kickoff — Work Board capture/list MVP

    Phase 0 已合并（见上一条评论）。按 delivery plan，我开始 Phase 1：在现有 task/workbar 区域做紧凑的 Work Board 面，支持全局 Inbox + 当前项目过滤，手工新增 / 改名 / 移动 / 完成 / 重开 / 归档，以及 empty / loading / error / 本地离线状态。

    实现切片：main 进程 WorkBoardStore + IPC → preload bridge → workbar 面板。不涉及 Runtime Host、模型可见工具、turn-tail 注入。

    如果面板位置或 Inbox/项目过滤行为和 issue 描述有出入，请在 UI 接线前告诉我；否则 Phase 1 PR 就绪后我会贴在这里。
13. somewan820 commented on Aug 17, 2026

    

    somewan820

    on Aug 17, 2026

    Contributor

    More actions

    Phase 1 PR ready for review — Work Board capture/list MVP

    PR #3135 implements the Phase 1 capture/list MVP from the delivery plan, on top of the merged Phase 0 contract/store.

    What it adds:

    • A compact Work Board tab in the session workbar (next to Tasks).
    • Global Inbox and current-project filtering.
    • Manual create, rename, move (Inbox <-> project), complete / reopen, archive / restore, and delete.
    • Empty / loading / error states.
    • Desktop main process owns WorkBoardStore; the renderer is a read-only IPC projection that reloads on the workBoard:changed signal.

    Boundary unchanged: no Runtime Host involvement, no model-visible tools, no turn-tail injection; linkedSessions and the linked-session projection remain deferred to Phase 3.

    Verification: desktop main/preload builds pass, full desktop typecheck passes, Work Board IPC tests pass. Full desktop suite runs in CI.

    简体中文

    Phase 1 PR 已就绪 — Work Board capture/list MVP

    PR #3135 实现了 delivery plan 中的 Phase 1 capture/list MVP，基于已合并的 Phase 0 契约/store。

    新增内容：

    • session workbar 中新增紧凑的 Work Board tab（紧挨 Tasks）。
    • 全局 Inbox 与当前项目过滤。
    • 手工新增、改名、移动（Inbox ↔ 项目）、完成 / 重开、归档 / 恢复、删除。
    • empty / loading / error 状态。
    • Desktop main 进程持有 WorkBoardStore；renderer 是只读 IPC 投影，收到 workBoard:changed 信号后重载。

    边界不变：不涉及 Runtime Host、模型可见工具、turn-tail 注入；linkedSessions 和 linked-session projection 仍推迟到 Phase 3。

    验证：desktop main/preload build 通过，desktop 全量 typecheck 通过，Work Board IPC 测试通过；全量 desktop 测试由 CI 运行。
14. Astro-Han

    added

    enhancementNew feature or requestNew feature or request

    on Aug 20, 2026
15. somewan820 commented on Aug 24, 2026

    

    somewan820

    on Aug 24, 2026

    Contributor

    More actions

    Phase 1 merged — proposed next planning checkpoint

    PR #3135 has merged as 863d7ae2c. Phase 0 and the Phase 1 capture/list MVP are now complete.

    Following @liugddx's review and the sequencing recorded in the Phase 1 doc, I will not start Phase 2 next. I propose that the next PR be a deliberately thin, default-off Phase 3 validation spike whose only goal is to test whether users return to the board and start work from it:

    • expose one narrow Start task happy path for an existing project-scoped board item;
    • create an ordinary Maka Session in that item's project/workspace, using only a concise title/summary plus typed source references and the bounded provenance excerpt — never the full conversation;
    • link the created Session back to the item and navigate to the new Session;
    • keep the existing authority boundary: no Session Task Ledger mutation, no model-visible Work Board tools, no turn-tail injection, no copied Runtime execution state, and no automatic item completion;
    • exclude side-chat capture, Inbox project selection, status projection polish, result/evidence refs, prioritization, and board redesign from this spike;
    • add focused behavior coverage for correct project/workspace selection, concise initial context, link-back, and the active Session plan remaining unchanged.

    Before implementation, could maintainers confirm these three choices?

    1. Initial scope: project-scoped items only, with Start task unavailable for Inbox items until an explicit project picker exists. This avoids silently choosing a workspace.
    2. Link durability: should the spike already add the smallest persistent linkedSessions contract/migration, while continuing to read execution status only from the canonical continuity authority? I recommend a persistent link because an in-memory link cannot validate the “return later” loop across restart. If that is still too much machinery for the spike, I can keep the link experiment-only and defer the schema change.
    3. Validation signal: because Maka is local-first and should not add telemetry for this experiment, is explicit maintainer/contributor dogfooding feedback recorded on this issue sufficient for the go/stop decision? Phase 2 and Phase 4 would remain paused until that evidence produces an explicit go decision.

    Once these are confirmed, I will turn the answer into a bounded technical slice and open the spike PR before doing any Phase 2 or Phase 4 work.

    简体中文

    Phase 1 已合并 — 下一步规划确认

    PR #3135 已通过 863d7ae2c 合并，Phase 0 与 Phase 1 capture/list MVP 已完成。

    按照 @liugddx 的 review 和 Phase 1 文档中确认的顺序，我不会直接开始 Phase 2。下一 PR 建议先做一个默认关闭、严格收窄的 Phase 3 验证 spike，只验证“用户是否会回到看板并从事项启动任务”：

    • 只为已有的 project-scoped item 打通一条最窄的 Start task happy path；
    • 在该事项所属项目/工作区创建普通 Maka Session，初始上下文仅包含精简标题/摘要、强类型来源引用和已有的有界 provenance excerpt，不灌入整段对话；
    • 把新 Session 关联回事项并跳转过去；
    • 保持现有权威边界：不改 Session Task Ledger、不增加模型可见 Work Board 工具、不注入 turn-tail、不复制 Runtime 执行状态、不自动完成事项；
    • 本次不做 side-chat capture、Inbox 项目选择、状态投影打磨、结果/证据引用、优先级和看板重设计；
    • 增加聚焦行为测试，覆盖正确项目/工作区、精简初始上下文、Session 回链，以及当前 Session plan 不被修改。

    实现前请 maintainer 确认三点：

    1. 首期范围：只支持 project-scoped item；Inbox 在有明确项目选择器前不提供 Start task，避免静默选择工作区。
    2. 关联是否持久化：spike 是否现在就增加最小的持久化 linkedSessions 契约/迁移，同时执行状态仍只从 canonical continuity authority 读取？我倾向持久化，因为纯内存关联无法验证重启后的“稍后回来”闭环；如果对 spike 来说仍然过重，也可以先做仅实验可见的关联，把 schema 变更继续延后。
    3. 验证信号：Maka 是 local-first，本实验不应为了验证而新增 telemetry。由 maintainer/contributor 实际 dogfood，并在 issue 记录明确反馈，是否足够作为 go/stop 依据？在得到明确 go 结论前，Phase 2 与 Phase 4 继续暂停。

    这些边界确认后，我会把结论整理成一个有界技术切片，先提交 spike PR，再考虑任何 Phase 2/Phase 4 工作。

    ---

    AI assistance disclosure: Codex helped inspect the merged PR and issue history and draft this planning checkpoint. I reviewed it and own the proposed scope and follow-up.
16. Astro-Han

    added the

    Feature

    issue type on Aug 29, 2026
17. somewan820 commented on Sep 2, 2026

    

    somewan820

    on Sep 2, 2026

    Last edited by somewan820

    Contributor

    More actions

    Hi @liugddx, just following up on the Phase 3 validation spike proposal above.

    PR #3135 is merged, and I am keeping implementation paused until the three scope questions are confirmed:

    1. Project-scoped items only for the initial Start task path
    2. Persistent linkedSessions in the spike, or defer that schema change
    3. Maintainer/contributor dogfooding feedback recorded on this issue as the go/stop signal

    If the proposal is approved as written, a short confirmation is enough and I will prepare the default-off spike PR. Please let me know if any of the three points should be changed.

    No rush — I just wanted to make sure this did not get lost in the issue queue. Thanks!
18. liugddx commented on Sep 2, 2026

    

    liugddx

    on Sep 2, 2026

    MemberAuthor

    More actions

    Thanks for following up. I rechecked the merged Phase 0/1 contracts and the current task-entry/session-creation path on main@72eb982d5. The sequencing is still right: validate the capture -> revisit -> start loop before Phase 2 or Phase 4. I approve a thin default-off spike, with the following scope corrections.

    1. Project-scoped only: yes, but the target must be Host-scoped. A persisted Work Board scope currently contains only projectId, while task creation actually targets (profileId, hostId, projectId). Do not infer a Runtime Host from the project id or silently use whichever project is currently selected. Enable Start task only when the current Task Entry catalog resolves the item through an explicit DesktopNewTaskTarget, including project aliases, to an available and non-archived project. Otherwise disable it with an actionable reason. Inbox remains unsupported until it has an explicit target picker.

    2. Reuse the existing first-send owner. session.create creates an empty Session; Composer first-send currently owns readiness, the initial message, optimistic presentation, and cleanup when create/send fails. The Work Board must not add a parallel create Session -> send message IPC flow. For the spike, the smallest path is: select the resolved Task Entry target, open the new-task surface, seed a bounded draft, and let the normal first-send path create/start the Session. Persist the link only after the normal submission has produced the durable Session/Turn outcome. The initial draft should use fields that have a production producer today: title plus optional notes. Do not invent a new provider-visible typed-reference format for conversation provenance before Phase 2 supplies that capture path.

    3. The link must be persistent in this spike. An experiment-only in-memory link cannot test the reason the store exists: returning after navigation/restart. Add a semantic, idempotent linkSession mutation owned by WorkBoardStore; do not expose whole-array replacement to the renderer and do not copy Session status into the item. The durable reference must be Host-scoped rather than a bare sessionId, so a later reader can locate the Session on the correct Runtime Host. If Session creation succeeds and link persistence fails, retry must attach the same Session rather than create a duplicate, and the failure must remain visible/actionable. The board item's user-owned state must not change automatically.

    4. Dogfooding is sufficient for the go/stop decision; product telemetry is not required. Please define the evidence checklist before implementation: whether the item existed before the action, whether the user completed the normal first send, whether the link survives restart and reopens the correct Host/Session, and whether any duplicate/orphan Session or manual repair was needed. Record the results here and make the go/stop decision explicit. The flag should be temporary experiment wiring, not a new persisted setting or public contract.

    So the approved spike is narrower than a new Work Board execution subsystem: existing project item -> explicitly resolved Host/project target -> normal new-task draft/first-send -> durable idempotent link -> reopen after restart. Keep side-chat capture, Inbox target selection, execution-status projection, evidence/result refs, automatic completion, prioritization, and board redesign out. Phase 2 and Phase 4 remain paused until this produces a clear go decision.

    简体中文

    谢谢跟进。我基于已合并的 Phase 0/1 契约和当前 main@72eb982d5 的 Task Entry / Session 创建链路重新核对过。顺序仍然正确：先验证 捕获 -> 回看 -> 启动 闭环，再决定是否继续 Phase 2/4。可以做 default-off 的薄 spike，但需要收紧以下边界：

    1. 首期只支持 project item 可以，但目标必须带 Runtime Host 作用域。 Work Board 当前只持久化 projectId，实际创建任务需要 (profileId, hostId, projectId)。不能只凭 project id 推断 Host，也不能静默使用当前选中的项目。只有 Task Entry catalog 能把事项解析成明确、可用、未归档的 DesktopNewTaskTarget 时才显示/启用 Start task；需要兼容 project alias。Inbox 继续禁用，等明确的 target picker。

    2. 复用现有 first-send 权威。 session.create 只创建空 Session；readiness、首条消息、乐观展示和失败清理由 Composer first-send 负责。Work Board 不应再造一套 创建 Session -> 发送消息 IPC。最小 spike 应切换到解析后的 Task Entry target，打开新任务面并写入有界 draft，由正常 first-send 创建和启动 Session；只有正常提交产生了持久 Session/Turn 后才写回关联。首期 draft 只使用当前已有真实生产入口的 title + 可选 notes；Phase 2 尚未提供对话捕获，不要提前发明新的 provider-visible typed reference 格式。

    3. 关联必须持久化。 纯内存关联无法验证“稍后回来”和重启后的闭环。新增由 WorkBoardStore 持有的语义化、幂等 linkSession mutation，不允许 renderer 整体替换 linkedSessions，也不复制 Session 状态。持久引用必须是 Host-scoped，不能只有裸 sessionId。如果 Session 已创建但回链失败，重试必须关联同一个 Session，不能再建一个；失败必须可见、可操作。事项的用户状态不能自动变化。

    4. Dogfood 足够作为 go/stop 信号，不需要产品 telemetry。 实现前先固定记录项：事项是否早于启动动作存在、用户是否完成正常 first send、重启后是否能重新打开正确 Host/Session、是否产生重复/孤儿 Session 或需要手工修复。结果写回本 Issue，并明确做 go/stop 决定。flag 只用于临时实验，不新增持久设置或公开契约。

    因此批准的 spike 是：已有 project item -> 明确解析 Host/project target -> 正常 new-task draft/first-send -> 持久且幂等的回链 -> 重启后可重新打开。side-chat capture、Inbox 选项目、执行状态投影、result/evidence refs、自动完成、优先级和看板重设计继续排除。得到明确 go 结论前，Phase 2/4 保持暂停。
19. somewan820 commented on Sep 3, 2026

    

    somewan820

    on Sep 3, 2026

    Contributor

    More actions

    Hi @liugddx — PR #4598 (Work Board Phase 3 start-task spike) has been rebased onto the latest main (b9748a773) and the conflicts are resolved. Could you please review when you get a chance?

    What the rebase did:

    • Dropped the merge commit; the branch is now a clean linear history on top of current main.
    • The rebase now builds on top of fix(desktop): 既有会话发送不再报告已解析会话 (onSessionResolved 契约) #4630's onSessionResolved contract: an existing-Session send never reports a resolved Session, so the Work Board link path only binds a task to a Session whose first message actually projected (onNewTaskSessionResolved → linkWorkBoardSession).
    • Regenerated the Astryx surface inventory and renderer architecture ledger against the final tree.

    Local verification on the updated head (in progress / results):

    • @maka/desktop typecheck: 0 errors
    • desktop main-process test suite: 2046 passed, 0 failed
    • core/storage work-board suites: 36 passed, 0 failed
    • biome + git diff --check: clean

    The test CI check is queued/running on the updated head.
20. somewan820 commented on Sep 4, 2026

    

    somewan820

    on Sep 4, 2026

    Contributor

    More actions

    已按 #4598 的 review 意见（3 个 P1 + 2 个 P2）完成修复并推送到 PR（新增 commit 18904be75）：

    • P1-1 待处理 claim 绑定到 new-task surface 的 draftKey，其它 surface 的首次发送不再误链接
    • P1-2 仅当 linkSession 成功后才清除 claim；失败保留 Session id，同一 item 再次 Start 复用同一 Session 重试，不再创建重复 Session
    • P1-3 workBoard:linkSession 校验 board item 的 project 所有权，Host validator 收到 expectedProjectId 并比对 Session 目标 project，跨 project 链接被拒绝
    • P2-1 linkedSessions 改为单链接契约（新链接替换旧链接），不再无限追加；读取路径对旧多条目保持容错
    • P2-2 start-task 开关同时要求 DEV 环境，生产构建即使设置 flag 也不暴露实验路径

    新增 7 个测试覆盖上述场景；桌面 main-process 套件 2074 passed / 0 failed，typecheck / biome / 架构检查均通过。

    @liugddx 麻烦有空再 review 一下，谢谢！
21. somewan820 commented on Sep 4, 2026

    

    somewan820

    on Sep 4, 2026

    Contributor

    More actions

    感谢第二轮 review！已按新意见（2 个 P1 + 1 个 P2）修复并推送（commit 07065c5f2）：

    • P1 surface 身份：draftKey 只是 target-scoped draft bucket，已改为 app-shell 在每次打开 New Task surface 时递增 owner nonce（newTaskSurfaceNonceRef），claim 绑定 nonce。同 Host/project 重开 surface（相同 draftKey）是不同实例，首次发送不再误消费 claim——已补同 target 回归测试
    • P1 TOCTOU：workBoard:linkSession 现在把校验前读到的 item.revision 作为 expectedRevision 传入 store.linkSession，store 在写事务内 CAS（不匹配抛 operation_conflict）。并发 move 无法再写入错误 project 的 Session——已补 revision CAS fail-closed 测试，cross-project 测试改为 production 形状的 Session workspace 投影
    • P2 retry 持久性：按 review 允许的边界收窄——pending-link claim 保留在当前 renderer 生命周期内（失败重试复用同 Session）；renderer 重启/重开导致 claim 丢失是已记录的 spike 限制（docs/work-board-contract.md 已注明，持久化 pending-link intent 留待后续阶段）

    新增测试全绿：桌面 main-process 2076 passed / 0 failed，typecheck / biome / 架构检查通过。CI 正在跑（含先前 flaky prompt-rail e2e 的重跑验证）。

    @liugddx 再麻烦看一眼，谢谢！
22. somewan820 commented on Sep 28, 2026

    

    somewan820

    on Sep 28, 2026

    Last edited by somewan820

    Contributor

    More actions

    Phase 3 dogfooding update (PR #5775)

    I updated the Phase 3 documentation in b4f08a9. The repository now records this as a mechanism-level result, rather than a contributor-declared final GO.

    This comment is the contributor evidence/request; no maintainer go/stop decision is recorded here yet. The decision remains pending on this issue.

    Recorded run (2026-09-28, local development renderer with VITE_MAKA_WORK_BOARD_START_TASK=1):

    • The item Phase 3 dogfood fixed did not pre-exist. It was created and then revisited in the same sitting.
    • Task Entry resolved profile local, Host ceeaf9c96959c19f67f044adc9e05ba959f4810d576ff13498922e2da1ecaffe, and project cf023c18-e57a-4dbc-9a47-fbe277892e63 (maka).
    • Start task opened the normal New Task surface with the bounded title draft; the first send streamed and completed normally in approximately 2 minutes 35 seconds.
    • After an app restart, the item and Session reopened with the same title and transcript, and Open session resolved Session 9a5a1cd1-c0a1-4be0-9510-97cef234db28.
    • The successful link path produced revision 2 with one Host-scoped link; no manual repair was needed.
    • The build and the six-file targeted command passed 106/0. The direct SQLite check read workflow_work_board_items.record_json. These are contributor-run observations; CI did not perform the manual renderer run.

    Limits and proposed status:

    • Because creation and revisit happened in one sitting, this run does not establish the Phase 1 delayed return-use assumption. No additional Phase 3 run is documented in the current repository or issue record.
    • The successful link path was exercised, but the documented restart-between-failed-link-and-retry limitation was not. That path can still create a second Session and leave the first unlinked.
    • Phase 2 and Phase 4 remain paused.

    This verifies the mechanism: project item -> resolved Host/project target -> normal first send -> durable link -> restart/reopen. Please record the maintainer go/stop decision here; the proposed current status is mechanism verified, delayed return-use pending.

    简体中文

    本次记录已将结论收窄为“机制已验证”，不再由贡献者自行宣布最终 GO。由于事项是在同一次操作中创建并回看，尚未验证隔一段时间后用户是否会回到 Work Board；Phase 2 和 Phase 4 继续暂停，等待这里的维护者 go/stop 决策以及 delayed return-use 证据。

    AI assistance disclosure: Codex helped structure this update from the
    contributor-provided run record and review feedback. The contributor verified
    the observations and owns the final status.
23. liugddx commented on Sep 28, 2026

    

    liugddx

    on Sep 28, 2026

    MemberAuthor

    More actions

    Phase 3 decision: GO for the start-task mechanism; Phase 2 and Phase 4 stay paused

    Thanks @somewan820 for the run record and for narrowing the conclusion in #5775. I checked the record against the code at b4f08a9, and the six-file targeted command reproduces at 106/0.

    Decision: GO for the mechanism. The run shows that the Phase 3 start-task path works end to end:

    • a project item resolves to an explicit Host/project target;
    • the normal first send creates and starts the Session;
    • the link persists as one Host-scoped entry;
    • the Session reopens correctly after a restart.

    I accept this path as the Phase 3 mechanism.

    What this unlocks. A follow-up PR may expose Start task outside development builds as an opt-in, default-off experimental entry, provided it:

    1. closes, or makes visible and actionable, the documented restart-between-failed-link-and-retry case, which can currently leave an unlinked second Session (work-board-contract.md, retry durability). Persisting the pending-link intent is the straightforward fix;
    2. adds a test that pins the entry gate, so that "production keeps the entry hidden" (or, later, "shown only when opted in") is tested rather than asserted.

    What stays paused. The Phase 1 assumption is that users return to the board and start tasks from it, and this run doesn't establish that: the item was created and started in the same sitting. Phase 2 and Phase 4 remain paused until this thread has at least one run where the item was created on one day and started from the board on a later day. Record it with the same checklist fields, including any failed or repaired runs. I'll revisit Phase 2/4 on that evidence.

    Status: mechanism verified (GO); delayed return-use pending; Phase 2/4 paused.

    简体中文

    决定：机制层面 GO。 这次试用证明了 Phase 3 "开始任务"链路端到端可靠：

    • 事项能解析到明确的 Host/项目；
    • 正常的首次发送能创建并启动会话；
    • 关联以单条 Host 作用域链接持久保存；
    • 重启后能正确打开原会话。

    我认可这条链路作为 Phase 3 的机制。

    放行内容。 后续 PR 可以把"开始任务"作为需要用户主动开启、默认关闭的实验入口，开放到非开发构建，前提是：

    1. 解决文档已记录的"关联失败后重启再重试，会留下一个未关联的重复会话"问题，或者让这个失败可见、可处理。推荐的做法是把待关联意图持久化；
    2. 补一个测试，把入口门控固定下来，让"生产环境不显示入口"这件事有测试保证，而不只是口头声明。

    继续暂停。 Phase 1 的前提是"用户会回到看板来开始任务"，这次试用没能证明：事项是在同一次操作里创建并启动的。Phase 2 和 Phase 4 继续暂停，直到本 issue 里至少有一次"事项在某天创建、隔天之后才从看板启动"的试用记录。记录时使用同一份检查清单，失败或做过修复的试用也要一并记录。有了这类证据，我再重新评估 Phase 2/4。

    状态：机制已验证（GO）；延迟回访待验证；Phase 2/4 暂停。
24. liugddx

    added a commit that references this issue on Sep 28, 2026

    docs(work-board): record Phase 3 dogfooding evidence (#5775)

    ...

    e0f96fe
25. somewan820 commented on Sep 30, 2026

    

    somewan820

    on Sep 30, 2026

    Contributor

    More actions

    Phase 3 delayed return-use follow-up (contributor evidence)

    This is a contributor evidence update and request for re-evaluation; it is not a
    maintainer go/stop decision. The follow-up branch records the run in
    docs/work-board-phase3.md at 10b743823.

    Run: 2026-09-30 local development renderer

    • Item/pre-existence: 看下明天天气
      (c250ba05-764b-4dcc-9a96-f6ca5061d578) pre-existed the run. The read-only
      record was created at 2026-09-21T17:01:44.823Z, last updated before the run
      at 2026-09-22T07:36:59.279Z, and had an empty linkedSessions array.
    • Resolved target: profile local, Host
      ceeaf9c96959c19f67f044adc9e05ba959f4810d576ff13498922e2da1ecaffe, project
      cf023c18-e57a-4dbc-9a47-fbe277892e63 (maka).
    • Renderer: ran with VITE_MAKA_WORK_BOARD_START_TASK=1 using the Vite
      development renderer and Electron at http://127.0.0.1:5174/.
    • First send: Start task from Current project opened the normal New
      Task surface with the bounded item title. The send streamed and completed in
      1 minute 19 seconds after one city clarification (Shanghai). A sandboxed Bash
      weather lookup failed, then the normal web-fetch fallback completed; this was
      not a Session-link failure and needed no manual repair.
    • Restart/reopen: after quitting and relaunching the same development app,
      the completed conversation reopened with the same prompt and transcript.
      Current project showed Open session, which returned to that same
      conversation.
    • Link/duplicate/orphan check: read-only SQLite inspection of
      workflow_work_board_items.record_json found revision 9, exactly one
      Host-scoped link to Session
      0215bc49-ab13-43b3-afff-19be12cb42f6, and updatedAt
      2026-09-30T07:05:44.657Z. A read-only session_create_claims query over the
      surrounding one-minute window returned exactly that one claim. No duplicate
      or orphan Session was observed on this successful path.
    • Failed-link/retry and repair: no failed-link/restart/retry was induced,
      because doing so would require mutating the local runtime database. The
      documented spike limitation therefore remains; manual repair was none.

    Verification

    • npm --workspace @maka/runtime-host run build — passed.
    • npm --workspace @maka/desktop run build:renderer — passed.
    • node --test apps/desktop/dist/main/__tests__/work-board-panel.test.js apps/desktop/dist/main/__tests__/work-board-start-task-gate.test.js — 8 passed, 0 failed.
    • The broader seven-file Work Board/controller suite — 122 passed, 0 failed.
    • git diff --check and npm run check:asf-headers — passed.
    • The root npm run build remains blocked in the pre-existing runtime
      Experimental_OpenResponsesBareExtension API mismatch in
      packages/runtime/src/deepseek-web-search-codec.ts; the manual renderer run
      and SQLite inspection were not performed by CI.

    The later-day run now supplies the delayed return-use evidence requested in the
    maintainer decision. Until a maintainer updates the decision, the recorded
    status remains mechanism verified (GO); delayed return-use pending; Phase 2/4
    paused. Please record whether this evidence changes that status.

    简体中文

    这是贡献者的延迟回访证据和复评请求，不是维护者决定。事项在更早日期已存在，9 月 30 日从看板启动；首发完成，重启后从看板打开同一会话，SQLite 中只有一个 Host 作用域关联和一个创建 claim。成功路径没有重复/孤儿会话，也没有手工修复；关联失败后重启再重试仍未覆盖，原有 spike 限制保留。

    在维护者更新决定前，状态继续保持：机制已验证（GO）；延迟回访待定；Phase 2/4 暂停。

    AI assistance disclosure: OpenAI Codex helped structure this update from the
    contributor-verified renderer and SQLite observations. The contributor owns the
    final status.
26. somewan820 commented on Sep 30, 2026

    

    somewan820

    on Sep 30, 2026

    Contributor

    More actions

    Correction to the verification note above

    The dogfood checkout's @maka/runtime-host build passed before I rebased the
    follow-up branch onto the current origin/main. On the exact rebased head
    (e23dd7f15), that build now stops at the baseline TS2367 comparison in
    packages/runtime-host/src/server/canonical-turn-snapshot.ts, introduced by
    the current mainline handoff change (#5853); no runtime-host files are changed
    by this follow-up. The root build also remains blocked by the existing
    Experimental_OpenResponsesBareExtension mismatch in
    packages/runtime/src/deepseek-web-search-codec.ts.

    The renderer build still passes, and the final-head Work Board/controller
    focused suite passes 122/122 when run with the required local cache
    permissions. The docs now distinguish the historical dogfood build result from
    the current-main baseline blockers.