业务存储、凭据、generation 与清理

使用入口：备份与恢复。对话事实的写入链见历史与 Worker。

#两类数据，两个权威来源

业务 SQLite 保存任务标题、目录、项目/分组、置顶、归档、模型选择、草稿、队列、设置和运行意图。JSONL 保存对话事实。不能通过修改 UI 投影反写一份替代 transcript，也不能从旧 transcript 覆盖更新过的任务字段。

TaskState 的 SQL 归属/顺序列是权威，附加 JSON 必须验证。revision 针对持久任务字段变化，不随每个流 delta、草稿或队列更新而增长。删除通过 tombstone 阻止迟到 upsert 复活。

#当前数据库结构

使用 Node 24 的 node:sqlite DatabaseSync，启用 WAL、FULL 同步、foreign keys 和 5000 ms busy timeout。新数据库在一个事务中创建当前 schema 4；已有数据库只接受当前版本，不进行升级，也没有 schema_migrations 账本。

打开前只读验证表、索引等定义。未知版本或被修改的权威结构直接报错；state.sqlite 不创建历史索引表；history.sqlite 的派生索引可按当前 JSONL 重建。应用设置只接受 version 5，凭据只接受 version 4，记忆状态只接受 version 2，会话插件快照只接受 pluginsVersion 3。

有关联的业务状态在事务内更新，凭据不允许出现在普通 JSON 字段中。历史格式转换工具不进入源码、构建或启动流程。

#generation 发布

active-generation.json 指向 storage/<generationId>，目标必须有匹配的 ready.json 与有效 state.sqlite。marker 的 format=2、schemaVersion=1、transcriptVersion=2 与业务数据库 schema 版本是不同概念，不能混写。

生成新数据先在独立目录准备和验证，再持久化指针；旧 generation 保留到可安全清理。JSON 使用独占临时文件、fsync、rename；目录同步在平台支持时执行，Windows 不通过 Node 目录 fsync 模拟同等保证。

#单写者锁

.storage-lock.sqlite 的 BEGIN IMMEDIATE 提供进程锁，进程退出后由操作系统释放。释放函数可重复调用，不维护 PID 文件或历史 owner 标记。

#凭据

API key 和 OAuth token 放在独立加密凭据存储，不进入 StateStore、transcript 或 UI 快照。系统加密不可用时会话内存可持有凭据，但不能把明文假装成已安全持久化。业务设置与凭据文件并非跨文件原子事务，恢复需要承认断电边界。

OAuth 刷新先持久化轮换结果，再完成可能失败的身份验证，防止旧 refresh token 已失效却丢掉新 token。并发和断开竞争见登录与刷新。

#删除和后台清理

业务 tombstone 与 cleanup pending 在事务中记录；文件删除可失败并在下次启动重试。清理校验 generation、任务标识和路径，不碰当前有效数据、归档关联或尚在进行的操作。显式删除且归属已确认的损坏日志可以清理；身份不匹配的文件保留诊断。

切换 generation 后旧目录的清理按安全时机排队。清空记忆有额外 writer 和水位协调，见记忆。

源码：StateStore、当前 schema、generation、清理、设置/凭据。回归：generation、schema 与状态、清理。