本技能是一份 ZCode 会话管理改造前的设计约束说明，定位为“为什么”和“怎么不踩坑”，不重复权威 spec 的具体设计。当改动命中会话任务索引、任务同步适配、侧栏与项目树、CLI session store、sessions-index 协议、workspace 与 project、roots 数据结构或两库 migration 时适用。
一、核心原则 会话事实归 CLI，组织态归 Host；每个字段只有一个写者。CLI 库保存会话存在性（软删除 time_deleted）、标题及来源、创建与更新时间、最近结果、正文、goal、fork、trace；Host 的任务索引保存 project_id、pinned、archived、unread_at、sort_order、projects/roots/hosts 及定时与闲时信息，控制端另存跨设备分组成员与顺序。cli_* 列是 CLI 事实的只读镜像，唯一写者为 taskIndexSyncer。禁止 CLI 写应用库、Host 写 CLI 库，也禁止 Host 对任何 cli_* 列写入 Date.now() 或从快照推导的值。原因在于重构前大量标题与状态 Bug 来自 Host 替 CLI 写会话事实、CLI 替 Host 决定行集合，导致排序跳动、手动标题不一致、历史任务消失和已删会话复活。
二、不变量 文档列出 17 条改动前需逐条对照的不变量，包括：workspaceKey 只表达身份隔离，执行路径始终使用 workspacePath 或 root_path；session 绑定目录创建后不变，项目移动只改 project_id；附加 roots 仅作 additionalDirectories，AGENTS.md、settings、MCP、hooks、plugins、memory、permissions 只按绑定目录链解析；CLI 不感知项目；行集合由应用库决定，sessions-index 只补实时字段；排序时间只取 CLI 创建与活动时间镜像，pin、archive、rename、未读不改时间；未读使用 CAS；标题按用户覆盖、模型生成、首条 prompt、占位的优先级，快照不覆盖用户覆盖；删除为 CLI 软删除，冷种子与列表必须过滤；两库 schema 只加不删；派生目录 hash 不迁移；远控 bridge 只用 workspaceKey；Host 组织态只存原列并启动对账；快照缺席不等于删除；恢复 CLI 库备份需关闭外键并校验；附加目录由 Host 统一解析；空归属 session 只在首次发现时判定一次。每条都附有违反时的典型症状。
三、关键裁决 侧栏结构为全局置顶区、项目区、任务区；筛选支持按项目、按分组、最近更新。项目本地可含多个同 host roots 与一个主要目录，远程恰好一个固定目录；同一目录可属多个项目；新建 session 的 cwd 为主要目录。本地及在线远端权威项目删除为软删除容器，会话保留归属；远程离线删除只移除本机入口与缓存。移除 root 或更换主要目录不影响已创建 session、定时任务、闲时任务与 Bots，变更对运行中 session 下次 resume 生效。分组由控制端 Host 唯一持有，不改变 cwd、项目、CLI 时间、配置或权限。展示偏好优先新版 view。远程项目与组织态留在远端应用库，本机只持久化连接记录、入口与基础缓存；host 上限 20，重连只刷新仍存在的入口。
四、数据与迁移纪律 两库共用版本化 migration runner，schema_migration 记录 id、checksum、app_version；每条 migration 显式声明 touchedTables，仅备份这些表用于失败恢复；需验证前后全部表内容哈希，只允许 touchedTables 变化；schema.baseline.sql 由 CI 做只增 diff。兼容退场分三阶段：只读新列、停双写、物理删退场列。降级依靠加法 schema，首次迁移遗留、旧版本新增或 CLI 首次发现的未归属 session 只判定一次归属。project_id IS NULL 是合法的未归类状态。迁移复用同一 SQL 与 Repo，迁移事务提交后发布 ready，失败 fail-closed。
五、改动前检查 文档给出检查清单，包括：确认字段唯一写者；时间戳必须来自 CLI 事件而非 Date.now()；不允许 sessions-index 决定行存在；身份判等远程必须带 workspaceIdentity；新增列需可空或带默认并更新 schema.baseline.sql 与 touchedTables；additionalDirectories 只允许在 skills、subagents、路径策略三处消费；标题、状态、未读、归档、删除的变更需覆盖桌面与手机远控、本地与 SSH/WSL 交叉 e2e；schema 改动需跑旧 fixture 升级、旧代码读写、再升级的 e2e；删除与标题代码保持意图位、惰性交接、镜像回写三段。
六、参考文档 文档列出现状事实、历史决策、当前分组与视图以及已废弃文档的路径，供进一步查阅。