ZCode 会话运行时与状态模型

会话运行时负责”多轮产品状态如何接纳、持久化、投影与恢复”。它与 agent-core（一轮工作如何执行）是两条独立边界。

两套事实源

事实源	用途	位置
Session Event Store（append-only + reducer）	live / replay 的顺序事实源	`contracts/src/events/`
SQLite transcript / entries	冷恢复事实源（跨进程重启）	`adapters/src/storage/session-store/migrations.ts`
ProductProjection	面向客户端的可重建视图（snapshot/delta）	`bootstrap/src/zcode-protocol-v4/`

live event store 目前是进程内实现（in-memory-session-event-store.ts:34）：瞬态 streaming/progress 事件按 turn window 淘汰，ModelRequest 驻留副本会瘦身为 messageCount 以控制内存（session-event-retention.ts:9）。

消息模型（SQLite）

migrations.ts:9 定义的表：session、message、part、session_entry、session_input、todo、permission、usage、workflow journal 等。

Message 分为 user / assistant；Part 覆盖（session-store.port.ts:422）：

text, reasoning, file, agent, compaction, timeline,
subtask, retry, step, snapshot, patch, tool

命令接入（CommandInbox）

bootstrap/src/zcode-protocol-v4/command-inbox.ts:107 是已提交输入的串行 admission 权威：

解析、sourceCommandId 幂等
revision / logEpoch CAS（compare-and-swap）
in-flight / live pin / settled 的 LRU
per-key 与 per-session FIFO gate
execute 会持有 session gate 直到 settle()

不变量：每条已提交输入必须且只能处于 queue / guided row / transcript / explicit rejected|failed|discarded 之一。Renderer 只保留未提交草稿与 pending optimistic overlay，Host 只做路由。

Conversation Topic 投影

V4 的核心不是”直接写 UI”，而是：

SessionEvent → ProductProjection → ConversationSnapshot/Delta → TopicFrame

bootstrap/src/zcode-protocol-v4/conversation-topic-publisher.ts:249 的 ConversationTopicPublisher 维护 logEpoch、有界 delta log、订阅者过滤/coalesce/背压和 snapshot/resume 裁决。

ConversationSnapshot 是完整可恢复视图，包含（见 docs/zcode-protocol.md）：

session 元信息与 phase
rows.window 消息/工具/marker 行
queue 与 inputRouting
pending interactions
model、mode、thought、follow-up 配置
usage、goal、background work 与 control availability

客户端只允许按 seq 连续应用 delta；重复/迟到帧静默丢弃；出现 gap 时重新订阅并以 snapshot 收敛。协议细节见 zcode-protocol。

Session Resident Pool

bootstrap/src/zcode-protocol/session-resident-pool.ts:57 用 target/high-water、10 分钟 idle、LRU、operation lease 和 residency facts 回收 runtime。request handler 全程持 lease，避免采样器关掉正在使用的 App。

Resume / Branch / Rewind

Resume 会重建路径、shell、Context/MessageHistory/read-file state，选择 rewind branch，恢复 compact/checkpoint/goal/permission，再发 SessionResumed。详见 agent-core。

ProductProjection 还承载 fork / rewind / retry 等分支语义；renderer 端对应 packages/ui/src/store/ 的 zcodeSessionStore* 与 packages/ui/src/v4/ 组件。

用量可观测（Usage）

ZCode CLI 默认 ~/.zcode/cli/db/db.sqlite 中有独立语义的 model_usage、turn_usage、tool_usage 表（30 天保留），经 usage/stats 协议提供给 Host 和 Renderer。它是本地产品使用统计，不是计费账本。/report 产品埋点、ARMS/RUM、Conversation telemetry、日志基础设施、App Usage 是不同通道，不能合并成一个 telemetry 概念。

权威状态边界（重述）

UI intent → Host service/transport → workspace CLI command inbox
          → Agent runtime + ProductProjection
          ├─ desktop-continuous → Desktop UI
          └─ web-remote-replayable → Mobile UI

CLI runtime / ProductProjection 是 conversation 正文和运行态的权威源。
Task SQLite index 只拥有任务列表元数据，不拥有 session 正文。
Desktop Main 和外部 relay 只做调度、配对和数据透传。

Wiki AI

目录