@zq-silk/yui 0.14.2 → 0.15.1

package/i18n/README.zh-CN.md

@@ -14,6 +14,9 @@ Yui 不把 Agent 的判断固化成确定性的工作流引擎。核心只负责
 
 当前实现保留实用的 Role/Agent/session 与 CLI 框架，不恢复后期膨胀的数据维护、租约、定时调度和恢复账本体系。
 
+[目标架构手册](../docs/architecture/README.md) 保存了供后续重构使用的
+2026-09-06 版设计基线，不代表当前已实现行为。
+
 ## 核心模型
 
 - `WorkItem`：唯一的有界工作单元，保存目标、验收条件、依赖、状态和精简结果。
@@ -101,7 +104,11 @@ export YUI_HOME=/absolute/path/to/yui-home
 yui setup
 ```
 
-home 中包含 `schema.json`、权威 SQLite 数据库 `yui.db`、Project Catalog、项目知识和 Controller 发现文件。稳定 Project checkout 与受管理 worktree 位于 home 外部的 workspace。运行时只接受当前存储契约：不会回退读取 `state.json`、转换旧 schema 或猜测旧 ID。
+home 中包含权威 SQLite 数据库 `yui.db`、Project Catalog、项目知识和
+Controller 发现文件。稳定 Project checkout 与受管理 worktree 位于 home
+外部的 workspace。旧 `schema.json` 与 `state.json` 只作为历史证据存在，
+不再是版本权威。运行时只接受当前存储契约；支持区间内的早期存储版本只允许
+通过显式升级入口。
 
 所有 Task-owned 记录族都在各自 Task 内分配单调递增的本地 ID。因此，不同
 Task 可以同时拥有 `work-item-1`、`turn-1` 或 `input-1`。受管 Task
@@ -111,8 +118,12 @@ Task 的命令（例如 `task work create`、`task integration start`）仍使
 Task 内的本地子记录 ID。Candidate 只在所属 WorkItem 内递增，并同时保存
 Task 与 WorkItem provenance。
 
-Yui 只支持当前 aggregate-v31 / Task-v7 schema。旧 home 不提供转换、
-双读或历史记录推断；需要使用新版本时初始化全新的 `YUI_HOME`。当前引用契约见
+Yui Home 只有一个存储版本，权威值是 SQLite 中连续且校验和有效的迁移
+ledger 头。CLI 同时公布当前存储版本和最小支持迁移版本。普通运行时代码只读取
+最新结构，不提供双读；`yui upgrade --dry-run` 只显示迁移计划，
+`yui upgrade` 会停住正在运行的 Controller、创建一致性备份、在一个事务中执行
+全部缺失迁移并校验最新结构。处于支持区间内的任意历史 Home 都可以直接跨多个
+版本升级，无需逐个安装中间版本。当前引用契约见
 [Task 本地 ID](../docs/task-local-identity.md)。
 
 ## 快速开始
@@ -611,6 +622,8 @@ Task 生命周期的交互选择只展示有效来源状态：activate 只展示
 
 Session、Activation 与 Turn 是独立身份。Session 可以跨多个 Turn 和客户端连接；Activation 只代表 Yui 当前的连接，而不是对 Provider thread 的独占所有权。每次 Provider 执行对应一个持久 Turn；写入超时或结果不明确会进入 `delivery-unknown`，不会自动重发。Codex 已存在的 active Turn 只会让 Yui 暂时等待，不会导致待投递 Turn 失败；Claude 等独立进程 Provider 继续通过 Yui 的 view/takeover 边界进行人工控制。
 
+恢复只在真的续不下去时被拦住：provider 侧没有可恢复的 Session、换了 Agent 或适配器、换了物理工作区。模型、推理强度、权限策略、Role 说明与 Skill、声明的写范围只决定下一次 activation 用什么，审查轮次、候选 commit、工作区基线这类每轮事实不影响复用。因此当 Role 存在活跃 Session 时，`task role update`、`config role update`、`config agent update` 会先报告该 Session 并要求 `--yes` 确认；需要立刻生效则先停止该 Session。
+
 Turn 是 Role 是否有工作正在执行的唯一持久调度状态，记录可见输入、来源/渠道与最终回复，不复制思考过程或工具调用。所有经 Yui 中转或生成的输入统一使用 `source: yui`；Provider UI 中直接输入的消息使用 `source: user`；显式 Goal continuation 使用 `source: provider`。Provider Turn 终态后 Yui 完成该 Turn，再把下一个 Turn 投递到同一 Session。TaskRole 本身只保存身份和期望启动配置，不再保存可写的运行状态；CLI/Web 展示的 Role 状态由活动 Turn 派生，并叠加 Session/Driver 生命周期事实用于诊断。
 
 Goal 是 Session 级显式 Provider 事实，可以跨越多个 Turn。Codex 通过 Goal API/事件提供，Claude 通过 `active_goal` 提供；Yui 不用静默等待来猜测 Goal 是否完成。Turn 结束不等于 Goal、WorkItem 或 Task 完成，只有 Leader 更新 WorkItem 与 Task 的持久语义。
@@ -627,13 +640,15 @@ yui task role release <task-id> <role>
 
 Codex Role thread 可在 Desktop 中直接查看和操作；Desktop 已有 active Turn 时，Yui 只保留待投递工作并等待，不会失败或重复投递。`view`、`takeover`、`release` 继续作为 Claude 等独立进程 Provider 的人工控制入口。Yui 不写入全局 Hook/config，也不启动、重启或停止共享 daemon；Codex CLI/daemon 故障由 Task 生命周期之外修复。Global Operator 与 global Role 继续使用原生交互式 CLI，不属于受管理 Task Provider 协议；Yui 在内部将 Codex 的 Global TUI 连接到同一个默认 App Server，用户不能通过 Agent 或 Role 参数覆盖该连接，Session Manifest 自带不依赖启动进程环境的 Global Context 命令，因此同一 thread 可直接切换到 Desktop 继续对话。
 
-当新版本需要离线迁移 Home 时，应等待当前 Turn 完成，然后从普通 shell
-执行 `yui session stop --all`，再重新执行 `yui update`。停止命令会先整体预检：
-只要仍有 Session 正在运行或存在未决生命周期工作，就不会开始停止；全部空闲
-时会先阻止新的 Leader 调度，停止并等待 Controller 完全退出，重新检查运行时
-事实后再停止 Task Role 和 global Role Session。成功后 Controller 保持停止，
-应紧接着执行 `yui update`。如果当前安装版本还没有这条命令，应手动退出提示中
-列出的全部 managed Session；新的 staged CLI 不能写入尚待迁移的旧 Home。
+Global Codex 的薄 Host 与原生 TUI 位于同一个 pane，透明转发 App Server 连接，并从该 TUI 自己的 `thread/start` 或 `thread/resume` 成功响应取得 Thread ID。Yui 在首条用户消息之前通过既有启动回执登记身份，不依赖 `notify`、历史目录扫描或 bootstrap 消息；旧的 global `notify` 不能登记或修改 Session 生命周期。连接随 TUI 退出，不依赖 Controller 的持续运行。tmux 窗口存在不等于 Agent 存活：`pane_dead=0` 才是运行中，`pane_dead=1` 是保留的退出现场，读取失败则报错。状态查询不删除现场；显式启动可重建精确的死亡窗口，但不能覆盖身份未知的活 Operator。
+
+`yui update` 会用目标版本先做只读预检，在停住精确的旧 Controller 后自动执行
+所需的离线迁移，再校验并启动新 Controller。若升级前希望结束所有 Agent
+活动，可先执行 `yui session stop --all`；这不是存储版本链的一部分。
+Yui 0.15.0 建立 storage version 1 和迁移下限。更早版本（包括 0.14.2）
+创建的 Home 不在这条兼容链上：应保留给匹配的历史 Yui 版本查看，或者初始化
+新的 Home。从 0.15.0 开始，后续版本必须保留完整迁移链，因此可以由
+`yui update` 直接跨版本升级。
 
 tmux 会在 pane 创建时固定其历史容量。配置该限制之前创建的 Role 会保留原容量；Yui 会在 Terminal attach 和 Web 中提示用户退出并重新进入一次，从而创建具有 100,000 行历史的新 pane。
 
@@ -675,10 +690,10 @@ yui controller restart
 
 `controller restart` 会用当前安装的 Yui 版本替换 Controller 进程及其调度循环、socket 服务，不会停止或重启已受管的 tmux/Agent 会话；普通 Session 命令按协议与存储身份兼容，不要求 Controller 与 CLI 包版本完全相同。
 
-成功的 `setup`、`upgrade` 和 `update` 都会确保当前 Home 有一个运行中的
-Controller；如果之前没有运行，会在完成后启动。只读命令和
-`upgrade --dry-run` 不会启动 Controller。`update` 只有在新二进制健康检查通过后，
-才会替换或启动 Controller。
+成功的 `setup` 和 `update` 会确保当前 Home 有一个运行中的 Controller。
+`upgrade` 只会在迁移前存在 Controller 时恢复它；只读命令和
+`upgrade --dry-run` 不会启动 Controller。`update` 只有在迁移和新二进制健康
+检查都通过后，才会替换或启动 Controller。
 
 恢复 reconciliation 默认每 120 秒执行一次。普通持久状态变化只会将 Task、Role 或 Operator key 放入队列并立即返回；固定 100ms 窗口内到达的 key 会合并触发一次不重叠的定向处理。Operator 呈现使用独立 lane，不会被 Task 的 Git/worktree 操作阻塞；周期 Git/worktree 处理只覆盖仍有持久 Task mailbox 工作的 Task，活动 Role 的存活检查合并为一次 tmux inventory。来自 Provider 原生事件或受支持 Hook 的结构化 Agent Driver observation，会经过精确 fence 后进入持久 runtime inbox。终态 Turn observation 会原子记录精确的 Turn 结果。持久 WorkMailbox 会冻结当前 processing 批次，期间的新事件合并到下一 pending 批次；失败会释放当前批次供恢复。推荐输入与 pending Turn 共用最近 deadline 选择器，不依赖恢复扫描间隔；显式 `task reconcile` 仍会立即请求恢复扫描。保留的闭环为：
 
@@ -724,6 +739,7 @@ Web 端可以通过与 Terminal 相同的持久化 CLI 路径回答 open InputRe
 
 ```sh
 yui update
+yui upgrade [--dry-run]
 yui config agent add|list|show|capabilities|update|remove
 yui config role add|list|show|update|remove|bind|unbind
 yui config profile add|list|show|update|remove|reset
@@ -749,9 +765,9 @@ npm test
 npm run lint
 ```
 
-`npm test` 只保留秒级核心 smoke：CLI 启动、正常 SQLite Task、受支持迁移和内置
-Agent Driver。针对当前修改编写的 TDD、异常数据和故障复现仅作为开发期证据，需求完成后
-删除，不累积为常驻回归测试。具体约束见
+`npm test` 只保留秒级核心 smoke：CLI 启动、正常 SQLite Task、存储基线、
+目标驱动更新和内置 Agent Driver。针对当前修改编写的 TDD、异常数据和故障复现
+仅作为开发期证据，需求完成后删除，不累积为常驻回归测试。具体约束见
 [验证策略](../docs/testing/verification-levels.md)。
 
 如需让用户终端使用当前 checkout，可逆地接管用户级 `yui` 命令：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zq-silk/yui",
-  "version": "0.14.2",
+  "version": "0.15.1",
   "description": "Local control plane for long-running native agent CLI sessions backed by tmux.",
   "license": "MIT",
   "private": false,

package/dist/storage/upgrade/recordVersions.js

@@ -1,82 +0,0 @@
-/** Current record-family versions for the single SQLite storage contract. */
-import { CURRENT_AGGREGATE_SCHEMA_VERSION, CURRENT_STORAGE_LAYOUT_VERSION } from "../storageVersions.js";
-import { CURRENT_TURN_SCHEMA_VERSION, CURRENT_AGENT_PROFILE_SCHEMA_VERSION, CURRENT_CAPABILITY_GRANT_SCHEMA_VERSION, CURRENT_CONFIG_SCHEMA_VERSION, CURRENT_CONFIGURED_AGENT_SCHEMA_VERSION, CURRENT_CHANGE_SET_SCHEMA_VERSION, CURRENT_CONTEXT_SNAPSHOT_SCHEMA_VERSION, CURRENT_DECISION_SCHEMA_VERSION, CURRENT_EVENT_SCHEMA_VERSION, CURRENT_GLOBAL_ROLE_SCHEMA_VERSION, CURRENT_GLOBAL_ROLE_SESSION_SET_SCHEMA_VERSION, CURRENT_INPUT_REQUEST_SCHEMA_VERSION, CURRENT_INTEGRATION_ATTEMPT_SCHEMA_VERSION, CURRENT_INTEGRATION_QUEUE_SCHEMA_VERSION, CURRENT_MANAGED_WORKSPACE_SCHEMA_VERSION, CURRENT_MESSAGE_SCHEMA_VERSION, CURRENT_MILESTONE_SCHEMA_VERSION, CURRENT_PUBLICATION_REFERENCE_SCHEMA_VERSION, CURRENT_PROJECT_SCHEMA_VERSION, CURRENT_RELEASE_WORKFLOW_SCHEMA_VERSION, CURRENT_REVIEW_ROUND_SCHEMA_VERSION, CURRENT_TASK_BRIEF_SCHEMA_VERSION, CURRENT_TASK_ROLE_SCHEMA_VERSION, CURRENT_TASK_ROLE_SESSION_SET_SCHEMA_VERSION, CURRENT_TASK_SCHEMA_VERSION, CURRENT_WORK_ITEM_SCHEMA_VERSION, CURRENT_WORK_MAILBOX_SCHEMA_VERSION } from "../taskStore.js";
-import { CURRENT_LEADER_FAILURE_SCHEMA_VERSION } from "../../scheduler/leaderFailure.js";
-import { CURRENT_TASK_WAKE_SCHEMA_VERSION } from "../../scheduler/taskWake.js";
-import { CURRENT_DURABLE_JOB_SCHEMA_VERSION } from "../../job/durableJob.js";
-function descriptor(kind, version) {
-    return Object.freeze({ version, path: `sqlite:${kind}` });
-}
-// Lazy construction avoids the taskStore -> storageSchema -> recordVersions
-// initialization cycle while keeping one canonical family list.
-let currentDescriptors = null;
-function getCurrentRecordDescriptors() {
-    if (currentDescriptors === null) {
-        const versions = {
-            config: CURRENT_CONFIG_SCHEMA_VERSION,
-            configuredAgent: CURRENT_CONFIGURED_AGENT_SCHEMA_VERSION,
-            project: CURRENT_PROJECT_SCHEMA_VERSION,
-            agentProfile: CURRENT_AGENT_PROFILE_SCHEMA_VERSION,
-            globalRole: CURRENT_GLOBAL_ROLE_SCHEMA_VERSION,
-            globalRoleSessionSet: CURRENT_GLOBAL_ROLE_SESSION_SET_SCHEMA_VERSION,
-            task: CURRENT_TASK_SCHEMA_VERSION,
-            taskBrief: CURRENT_TASK_BRIEF_SCHEMA_VERSION,
-            taskRole: CURRENT_TASK_ROLE_SCHEMA_VERSION,
-            managedWorkspace: CURRENT_MANAGED_WORKSPACE_SCHEMA_VERSION,
-            taskRoleSessionSet: CURRENT_TASK_ROLE_SESSION_SET_SCHEMA_VERSION,
-            workItem: CURRENT_WORK_ITEM_SCHEMA_VERSION,
-            contextSnapshot: CURRENT_CONTEXT_SNAPSHOT_SCHEMA_VERSION,
-            turn: CURRENT_TURN_SCHEMA_VERSION,
-            reviewRound: CURRENT_REVIEW_ROUND_SCHEMA_VERSION,
-            changeSet: CURRENT_CHANGE_SET_SCHEMA_VERSION,
-            integrationAttempt: CURRENT_INTEGRATION_ATTEMPT_SCHEMA_VERSION,
-            integrationQueue: CURRENT_INTEGRATION_QUEUE_SCHEMA_VERSION,
-            durableJob: CURRENT_DURABLE_JOB_SCHEMA_VERSION,
-            message: CURRENT_MESSAGE_SCHEMA_VERSION,
-            inputRequest: CURRENT_INPUT_REQUEST_SCHEMA_VERSION,
-            decision: CURRENT_DECISION_SCHEMA_VERSION,
-            milestone: CURRENT_MILESTONE_SCHEMA_VERSION,
-            event: CURRENT_EVENT_SCHEMA_VERSION,
-            taskWake: CURRENT_TASK_WAKE_SCHEMA_VERSION,
-            capabilityGrant: CURRENT_CAPABILITY_GRANT_SCHEMA_VERSION,
-            releaseWorkflow: CURRENT_RELEASE_WORKFLOW_SCHEMA_VERSION,
-            publicationReference: CURRENT_PUBLICATION_REFERENCE_SCHEMA_VERSION,
-            leaderFailure: CURRENT_LEADER_FAILURE_SCHEMA_VERSION,
-            workMailbox: CURRENT_WORK_MAILBOX_SCHEMA_VERSION
-        };
-        currentDescriptors = Object.freeze(Object.fromEntries(Object.entries(versions).map(([kind, version]) => [kind, descriptor(kind, version)])));
-    }
-    return currentDescriptors;
-}
-/** Defensive copy of the current record-family contract. */
-export function currentRecordVersions(candidate = getCurrentRecordDescriptors()) {
-    assertRecordVersionDescriptors(candidate);
-    return { ...candidate };
-}
-/** Reject missing, extra, stale, or non-SQLite record descriptors. */
-export function assertRecordVersionDescriptors(candidate = getCurrentRecordDescriptors()) {
-    const expected = getCurrentRecordDescriptors();
-    const expectedKinds = Object.keys(expected);
-    const mappedKinds = Object.keys(candidate);
-    const missing = expectedKinds.filter((kind) => !Object.hasOwn(candidate, kind));
-    const unexpected = mappedKinds.filter((kind) => !Object.hasOwn(expected, kind));
-    if (missing.length > 0 || unexpected.length > 0) {
-        throw new Error(`Record version map completeness drift: missing=${missing.join(",") || "none"}; `
-            + `unexpected=${unexpected.join(",") || "none"}.`);
-    }
-    for (const kind of expectedKinds) {
-        const wanted = expected[kind];
-        const found = candidate[kind];
-        if (found?.version !== wanted.version || found.path !== wanted.path) {
-            throw new Error(`Record version map drift for ${kind}: expected=${wanted.version}@${wanted.path}; `
-                + `actual=${String(found?.version)}@${String(found?.path)}.`);
-        }
-    }
-}
-export function latestStorageVersionState(recordDescriptors = getCurrentRecordDescriptors()) {
-    return {
-        layout: CURRENT_STORAGE_LAYOUT_VERSION,
-        aggregate: CURRENT_AGGREGATE_SCHEMA_VERSION,
-        record: currentRecordVersions(recordDescriptors)
-    };
-}