@zq-silk/yui 0.15.8 → 0.15.11

package/docs/release-workflow.zh-CN.md

@@ -0,0 +1,266 @@
+<p align="right"><a href="./release-workflow.md">English</a> | <strong>简体中文</strong></p>
+
+# 获授权的发布操作
+
+发布工作流是一段被显式选择、获授权的外部发布效果序列——pull request、CI 确认、
+合并、版本 tag、npm 发布、全新安装冒烟、CLI 更新、Controller 替换、Project 迁移和
+后置验证。它是一个专用的外部效果设施，而不是 Yui 的 Task 规划或 Agent 执行模型。
+Agent 选择一个预先声明的计划，设施从持久状态驱动该计划：每次转换都在下一次外部调用
+之前持久化，因此崩溃、超时或被撤销的 grant 都不会让发布陷入猜测。
+
+两个 Task 级记录族支撑它：
+
+- **CapabilityGrant**（`capability-grant-N`）——权威。一个具名的授权者把 grant
+  限定到若干动作、参数边界、一个过期时间、一个使用次数和一个不可逆上限。
+- **ReleaseWorkflow**（`release-workflow-N`）——计划及其进展：一个确切来源（仓库 +
+  钉住的 commit，可选一个 artifact）、一份不可变的有序步骤计划，以及每步一条持久记录。
+
+引擎（`src/release/releaseWorkflowEngine.ts`）是一个纯库；`yui task workflow` 和
+`yui task grant` 命令驱动它。每个外部系统都位于 `ReleaseWorkflowPorts`
+（`src/release/releaseWorkflowPorts.ts`）之后，因此整个工作流可以用确定性的 fake
+测试，不产生任何真实的 GitHub、npm、git、Controller 或进程副作用。
+
+## 授权模型
+
+每一次（再）提交一个步骤，都在外部调用**之前**通过 `checkGrant(grant, request, now)`
+（`src/grant/capabilityGrant.ts`）。步骤 kind 就是 grant 动作：一个 grant 列出它授权的
+步骤 kind，例如 `--action npm-publish --action version-tag`。该判定是 fail-closed
+的——每个拒绝都带一个机器可读原因并停止这次运行：
+
+| 原因 | 含义 |
+| --- | --- |
+| `grant-missing` | 没有 grant 记录绑定到该工作流（引擎级）。 |
+| `grant-revoked` | 该 grant 已被 operator 撤销。 |
+| `grant-expired` | 墙钟已过该 grant 的 `expiresAt`。 |
+| `grant-uses-exhausted` | 该 grant 的 `maxUses` 已被消耗。 |
+| `grant-action-not-allowed` | 步骤 kind 不在该 grant 的动作中。 |
+| `grant-parameter-missing` | 步骤缺少一个受约束参数。 |
+| `grant-parameter-value-not-allowed` | 一个受约束参数的取值越界。 |
+| `grant-irreversibility-exceeds-ceiling` | 该步骤比 grant 的上限更不可逆。 |
+
+附加规则：
+
+- **每次获授权提交消耗一次。** 引擎在成功判定与外部调用之间记录一次 grant 使用，
+  因此一个 `maxUses` grant 会在那次将要超额的尝试上 fail closed。
+- **不可逆步骤需要一个已确认的前缀。** 一个标记为 `irreversible` 的步骤额外要求此前
+  每个步骤都是 `succeeded`；否则该步骤以 `prerequisite-not-confirmed` 失败并停止运行。
+  这正是让 `npm-publish` 不会跟在一个失败的 PR 之后运行的机制。
+- **拒绝会被记录。** 当一个待处理步骤被拒绝时，引擎会启动并把该步骤失败，日志里带上
+  这次拒绝，因此 `workflow status` 能准确显示授权在哪里停下。
+- **重新绑定。** 一个被撤销、过期或过窄的 grant 不会让工作流走进死胡同。签发一个新
+  grant 并用 `yui task workflow resume <task> <workflow> --grant <new-grant>` 恢复；
+  跨越这次重新绑定，计划、来源和所有已确认的步骤证据都不可变。
+
+## 稳定的 Task-final Review 合同
+
+兼容的 CLI 包更新和 Controller 替换不改变一个活动 Task 的 final-review 能力。受管
+Session 使用普通的 `yui` 命令，兼容性由协议和存储身份检查，一个替换 Leader 呈现由
+持久 Task 证据已确立的合同。不需要任何版本感知的 Operator 动作。Candidate 和
+Task-final 的 ReviewRound 记录必须全部携带那唯一的合同。冲突的记录 fail closed；
+不存在重新绑定事件、恢复命令或第二套合同状态机。
+
+## 常驻 Agent Host 升级兼容
+
+存活 Host 保持原 Endpoint 实现，先把准确的 Session/attempt/nativeTurn 事实写入现有
+持久 Inbox，再联系 Controller。只有当前 Controller 解析 Run 归属、校验权限、工作区、
+生命周期与历史关联并提交结果。Inbox 文件不代表接受；提交后才确认消费，断线或丢失
+ACK 不会重放用户输入或模型工作。
+
+启动事实从已兑现的 launch payload 取得准确 Run 身份，不把 Run 固定到长期 Session
+环境。即使冻结的 Run 工作区不同于 Role 默认值，登记前的证据也能保留；后续活动和
+终态仍只按各自的原生输入身份解析归属。
+
+支持边界为控制协议 `yui-agent-host/v5`、事件来源协议 `yui-agent-host-events/v1`、
+Controller RPC 版本 4。声明 `storage=controller-owned` 的 Host 不打开 Home 数据库，
+包括进程归属、原生账号位置和执行环境校验。Home 22 声明 Inbox 的新增来源字段，
+不改写有效历史事实与业务记录。后续版本要么保留该线协议，要么在修改存储前拒绝不兼容
+的存活生产者。刷新 Session CLI wrapper 或新 `doctor` 成功都不能证明旧 Host 兼容。
+
+`upgrade`、`update` 的目标版本预检及 release activation 独立检查存活 Host。
+没有此能力的 legacy Host（包括 idle）以及兼容响应不确定的 Host 都阻止采用；
+在既有隔离/静默交接边界再次检查，先于迁移或发布切换。检查不会 kill、替换或 reload
+Host。先让原有工作结束并保留原始未决输入/结果证据，再由获授权的 Operator 在安全
+边界选择 Session 替换或清理，之后重试。安装新代码不能修改已加载的 legacy Host 内存，
+也不能回收它从未持久投递过的终态。
+
+`task role status`、`task role list` 和 `task role session inspect` 在持久 Run 状态旁
+显示 Host 上报观测。原生结果待落库或已知上报故障需要关注，但不代表 Provider 失败、
+Run 已结束或业务已验收。Host 诊断只检查自己已投递文件的身份是否存在，不解析或隔离
+其他生产者的新格式事件。
+
+## CLI 与 Controller 发布边界
+
+全局 `yui` 命令是稳定的用户与受管 Session 接口。对普通命令，它不跟随
+`runtime/active-release.json`：那个指针选择的是 Controller 发布，而不是 CLI 包。这让
+CLI、Operator Session 和 Controller 替换保持兼容，而不必把每个命令钉在一个不可变构建上。
+
+一个源码 checkout 或以其他方式未经验证的本地 CLI 不是这个已发布接口。当 `YUI_HOME`
+已经命名了一个活动发布时，这样的 CLI 会在打开存储之前失败，并报告它的构建/来源、
+持久的 Home 身份以及它的调用类别。`make install-local` 仍默认使用 checkout 隔离的
+`output/dev/home`；把那个 launcher 显式指向一个发布拥有的 Home 会被拒绝。
+
+一个显式的 `yui release activate <release-id|build-id>` 是唯一的例外。全局 CLI 校验
+已安装的目标发布及其匹配的冒烟回执，然后把未改动的激活参数委派给那个目标的
+`dist/cli.js`。因此目标发布拥有完整的交接协议和超时层级。一次无目标的激活、help、
+`--json` 以及其他每个命令都留在全局 CLI 上。激活不新增另一条普通 CLI 路由路径。
+
+## 步骤目录
+
+计划是一个固定、预先声明的操作子集。每个计划条目有一个 id（工作流内唯一）、一个
+kind、可选 params，以及一个可选的不可逆级别（`none` | `reversible` | `irreversible`）。
+
+| Kind | 外部效果 | 权威身份 |
+| --- | --- | --- |
+| `pr-create-or-reuse` | 创建发布 PR，或复用一个针对该 head 的开放 PR。 | `pull-request` 号 |
+| `ci-confirm` | 读取该来源 ref 的 CI 结论；仅在 `success` 时成功。 | — |
+| `merge` | 合并具名 PR（默认 squash）。 | — |
+| `version-tag` | 创建并推送带注释的版本 tag。 | `git-tag` 名 |
+| `npm-publish` | 把 tarball 发布到 registry。 | `npm-package` 版本 |
+| `fresh-install-smoke` | 从 registry 安装并运行已发布的包。 | — |
+| `cli-update` | 通过既有更新编排器更新 Yui CLI/Controller home。 | `controller-home` |
+| `controller-replace` | 停止并重启 file-task Controller。 | — |
+| `project-migrate` | 通过既有的 project 命令运行 Project 迁移。 | — |
+| `post-verify` | 运行一个任意的验证命令。 | — |
+
+步骤可以引用更早的证据：一个 param 值为 `$externalId:<step-id>` 时，会在运行时解析为
+被引用步骤已确认的 external id，因此一个 `merge` 步骤可以消费 `pr` 步骤产生的 PR 号，
+而 operator 事先并不需要知道它。对一个未确认步骤的引用会让运行失败，而不是猜测。
+
+## 恢复与 resume 语义
+
+一次运行总是从 **resume 游标**开始：第一个状态非终态（`succeeded` 或 `skipped`）的
+计划步骤。没有“从头再来”——已确认的步骤绝不重跑。
+
+因为每次状态转换都在下一次外部调用之前持久化，所以任意一点的进程退出都是可恢复的：
+重新调用 `run`（或 `resume`），引擎就从第一个未确认步骤继续。`--max-steps <n>` 限定
+单次运行；一次在工作流中途耗尽预算的运行返回 `budget-exhausted`，下一次调用继续。
+
+在途步骤通过**权威身份查询**解决，绝不盲目重新提交：
+
+- 一个留在 `running` 或 `unknown` 的步骤，先按其记录的 `externalIdentity` 查询。
+  - `exists` → 该步骤到达 `succeeded`，且**没有第二次提交**（`unknown` 被确认，
+    `running` 被完成）。
+  - `unknown` → 运行以结果 `unknown` 停止；在其命运不可知期间，该步骤绝不被重新提交。
+  - `absent` → 效果从未落地，因此该步骤被重试（一个 `running` 步骤会记录这次恢复尝试）。
+- 一个**没有** external identity 的 `running` 步骤在记录提交结果之前就崩溃了。一个
+  不可逆步骤无论如何都通过端口查询（适配器咨询其持久幂等存储）:`exists` 不经第二次
+  提交确认该步骤，`unknown` 以 `unconfirmed` 停止，只有权威的 `absent` 才恰好重试该
+  步骤一次。一个可逆步骤总是落到重试，并沿用同一个幂等键。
+- 一次**没有** external identity 的超时把该步骤标记为 `unknown`（unconfirmed），因此
+  它绝不被盲目重新提交；在 resume 时它以 `unconfirmed` fail closed。
+- 一个 `failed` 步骤在下一次运行时被重试；它的 `attempts` 计数和日志按尝试增长。
+
+运行结果：`succeeded`、`failed`、`unknown`、`unauthorized`、`unconfirmed`、
+`budget-exhausted`。每个都带一个机器可读的 `stopReason`（例如 `unknown:publish`、
+`unauthorized:grant-revoked`、`budget-exhausted:verify`）以及该次运行尝试过的步骤 id
+列表。
+
+## 幂等键合同
+
+每个步骤的幂等键在**创建时预先声明**且永不改变：
+
+```text
+<taskId>/<workflowId>/<stepId>
+```
+
+该键被传给该步骤的每一次 `executeStep` 调用，包括在一次确认为 absent 的超时之后的
+重试。端口合同要求 `executeStep` 在同一键下是幂等的：一次重试尝试不得产生第二次
+副作用。引擎侧的合同更严格——它绝不为一个已标记 `unknown` 的步骤调用 `executeStep`,
+而是按记录的身份重新查询。fake 记录每一个键，因此测试套件直接证明至多一次执行。
+
+## Operator 指南
+
+Session 权威依据当前持久绑定检查。Telemetry 按 Role/AgentRun 分组，进程 owner 使用
+PID/start 身份。存储变更遵循[唯一的显式升级边界](sqlite-control-plane-design.zh-CN.md);
+普通命令绝不改写 Home schema。
+
+grant 的签发与撤销是不可逆权威操作。它们需要当前已登记的全局 Operator 对话。它的
+原生 session ID 必须与持久的活动 session 绑定匹配：Codex 命令在存在时使用
+`CODEX_THREAD_ID`，否则使用 `YUI_NATIVE_SESSION_ID`;Claude 使用 `YUI_NATIVE_SESSION_ID`。
+Host generation 和启动时的 Agent 标签不是调用者身份。通过另一个入口恢复同一段对话
+不撤销其权威。一个未登记、被替换或已结束的对话没有这种权威。一个受管的 Task Agent
+不能自签发或自撤销 grant，清空子进程环境也不赋予用户权威。被记录的授权者/撤销者
+绑定到那个 Operator session（`operator:<agent-id>`）；不存在可伪造的 `--granter`/`--by`
+标签。
+
+```sh
+# 1. Operator session 为发布链签发权威。
+yui task grant issue task-15 \
+  --action pr-create-or-reuse --action npm-publish --action post-verify \
+  --irreversibility-ceiling irreversible
+
+# 2. 针对确切来源和预先声明的计划创建工作流。
+#    npm-publish 步骤需要一个内容寻址的来源 artifact：不可变的工作流来源以后
+#    永远无法再获得它，因此没有 --source-artifact 的计划在创建时即被拒绝。
+yui task workflow create task-15 \
+  --grant capability-grant-1 \
+  --source-repo acme/widget --source-commit abc1234deadbeef0000000000000000000000000 \
+  --source-artifact widget-1.0.0.tgz@sha512-<base64-integrity> \
+  --step pr:pr-create-or-reuse \
+  --step publish:npm-publish --step-irreversibility publish=irreversible \
+  --step-param publish:tarball=./dist/widget-1.0.0.tgz \
+  --step verify:post-verify --step-param verify:command='yui --version'
+
+# 3. 运行（或 resume）并检查。
+yui task workflow run    task-15 release-workflow-1
+yui task workflow resume task-15 release-workflow-1 [--grant capability-grant-2] [--max-steps 1]
+yui task workflow status task-15 release-workflow-1
+
+# 4. 随时撤销权威；下一个步骤以 unauthorized 停止。
+yui task grant revoke task-15 capability-grant-1
+```
+
+`workflow status` 渲染每个步骤的状态、尝试次数和已确认的 external id，因此 operator
+能准确看到一次发布在哪里停下以及为什么。
+
+## 真实资源边界
+
+真实执行只通过 `yui` CLI 发生，它接上真实适配器（`createReleaseWorkflowPorts`）。该
+适配器是既有原子操作——`gh`、`npm`、`git`、CLI 更新编排器、Controller stop/restart 和
+`project migrate`——之上的一层薄壳，并且只在一个人类授权者签发了对每个步骤都通过
+`checkGrant` 的显式 CapabilityGrant 时才运行。一个本地测试请求绝不替代那份权威。
+
+由 tag 触发的 `publish.yml` 工作流是唯一维护的发布冒烟。它复用那个通过了 core CI 的
+确切 commit，只增加发布所需的产物装配、全新安装和 provenance 检查。
+
+该工作流通过 npm Trusted Publishing（OIDC）认证，因此发布身份存在于 tag 之外的两处：
+`repository`、`bugs` 和 `homepage` 由 `assemble-runtime-package.mjs` 从源 `package.json`
+逐字复制进已发布 manifest，而该包的 npm Trusted Publisher 条目点明 GitHub owner、
+仓库、工作流文件和环境。npm 在接受 provenance 之前会区分大小写地将 `repository.url`
+与正在构建的仓库比较。因此重命名或转移 GitHub 仓库时，必须连同重命名一起更新这些 URL
+和 npm Trusted Publisher 条目；否则下一个 tag 会走到 `npm publish` 并在那里失败——此时
+tag 和已过门的构建都已成功。
+
+## 适配器安全加固
+
+真实适配器（`createReleaseWorkflowPorts`）在引擎的 grant 检查之外再施加额外防护：
+
+- **Tarball 选项注入。** 一个看起来像选项的 tarball 路径（以 `-` 开头）在任何子进程
+  ——`tar -xOf` manifest 检视和 `npm publish`——看到它之前就被拒绝，因此一个精心构造的
+  路径永远不会被当作 flag 解释。
+- **Tarball TOCTOU。** 在校验冻结的 `source.artifact.integrity` 之后，被校验的字节被
+  快照到一个工作流私有、只读的临时文件。`tar -xOf` manifest 检视和 `npm publish` 都
+  读取该快照，而不是活的 tarball 路径，因此校验之后对原文件的替换不能改变所发布的内容。
+  步骤完成时移除该快照。
+- **钉住的外部命令。** 适配器在构造时通过 `resolveExecutable` 把它 shell 调用的外部
+  命令（`gh`、`git`、`npm`、`tar`、`sh`）解析为绝对路径，只走一次调用者的 `PATH`。每次
+  子进程调用都使用解析后的路径，因此之后的 `PATH` 变化（或被操纵的工作目录）不能把一次
+  发布效果重定向到另一个二进制。一个无法解析的命令返回一个合成失败（exit 127），不调用
+  任何二进制。
+- **钉住的 cli-update 激活目标。** 在不可逆的更新效果之前，适配器把确切的激活目标——
+  Home 加上全局 npm 前缀（`bin/yui`）——持久化到 Home 下的一个持久文件
+  （`release/cli-update-identity/<idempotency-key>.json`）。一次硬退出的恢复查询（一个
+  没有记录身份的步骤）读取这个文件并调用那个钉住的目标；如果该文件不存在（进程在预效果
+  持久化之前退出），查询返回 `unknown`，而不是从 resume 调用者的 `npm prefix --global`
+  或 `PATH` 推导目标，因此 resume 环境中的另一个安装不能替这个步骤背书。
+- **Controller 生命周期校验。** 一次 `cli-update` 恢复查询会证明替换后的 Controller
+  确实拥有目标 Home：它运行 `yui --json controller status`（`YUI_HOME` 钉在记录的 Home
+  上），并要求一个 `current` controller 资源，其 `yuiHome` 解析到那个 Home，然后运行
+  `yui --json controller identity`，并要求已认证的 Controller 身份与已激活的产物匹配：
+  Node.js 可执行路径、由钉住的全局二进制派生的确切 Controller 入口点，以及包版本。仅有
+  二进制健康（doctor、`--version`）绝不确认这次交接，任何不可证明的状态都返回 `unknown`。
+  这适用于带身份的查询和硬退出查询（一个没有记录身份的步骤）两者。
+- **npm integrity 比较。** 一次 `npm-publish` 恢复查询不止步于已发布版本：它通过
+  `npm view <pkg>@<version> dist.integrity` 取 `dist.integrity`，并与冻结的
+  `source.artifact.integrity` 逐字节比较。匹配则确认该步骤；同一版本但字节不同是一个
+  冲突，返回 `unknown`（绝不确认，绝不重新发布）；一个缺失的版本是 `absent`。

package/docs/roles-and-configuration.md

@@ -1,3 +1,5 @@
+<p align="right"><strong>English</strong> | <a href="./roles-and-configuration.zh-CN.md">简体中文</a></p>
+
 # Roles, Profiles and execution configuration
 
 ## Responsibilities

package/docs/roles-and-configuration.zh-CN.md

@@ -0,0 +1,96 @@
+<p align="right"><a href="./roles-and-configuration.md">English</a> | <strong>简体中文</strong></p>
+
+# Role、Profile 与执行配置
+
+## 职责
+
+Agent 选择一个执行组件、连接方案和启动环境。Role 选择一个活动的 Agent 绑定和
+可移植行为。每个绑定保留独立的运行时选项。一个 Role 可以持有多个绑定，而不产生
+并行写者，也不把一个绑定的凭据/配置共享给另一个。
+
+Task Role 是 Task 局部的；global Role 提供已配置的默认值和全局对话。Role
+身份/配置不是可写的运行时状态。Session 与 Provider 观察描述实际活动。
+
+一次显式的 Task-final Review 使用既有的 Task 局部 Reviewer Role，不要求存在同名
+的 global Role。只有当请求的 Task Role 不存在时，global Role 才作为创建模板。
+可用性、producer 分离和冻结的审查候选仍然适用。
+
+## Profile
+
+Agent Profile 把可移植行为（指令、Skill 和访问意图）与运行时意图组合在一起。
+运行时要么沿用当前 Global Worker 绑定，要么显式选择一个 Agent 并可选 model 和
+effort。`config profile reset` 提供 `worker`、`explorer`、`implementer` 和
+`reviewer`。
+
+从 Profile 创建 Task Role 会冻结其解析后的行为和绑定。之后对 Profile 或 Global
+Worker 的编辑不会改写既有的 Task Role。重新套用一个 Profile 是一次显式配置变更。
+所选 Agent 必须与目标绑定匹配；显式的 Role 选项覆盖对应的模板字段。Profile
+不是 Session、工作区 owner 或资源 grant。
+
+原生子代继承其父 Agent 和权限。Profile 可以引导它们的行为；model/effort 覆盖
+需要真实的原生工具支持。它们不获得 Yui Role、独立 Assignment 或更大范围。
+
+## 期望、生效与观察
+
+期望设置是下一次启动的意图。AgentRun 和 Session 捕获生效启动：Agent/组件、
+协议、model、effort、权限策略、工作区/环境、Role 上下文以及 planning/delivery
+权限。
+
+对运行中配置的检查单独报告 Agent 实际声明的内容。unsupported 和 unknown 都是
+显式的；一个被接受的 setter 若没有回报当前值，并不算已观察到的匹配。读取配置
+不会修改 Agent 以让观察与期望一致。
+
+Worker 绑定变更保留活动 Assignment 的 Agent 和生效快照；之后的显式派发使用当前
+选择。Leader 替换撤销上一条管理入口，但不改写 Worker Assignment。更改期望配置
+不会热改原生 Session。一次显式的 `task role session new` 请求会在选择新 Session
+之前处理旧运行时清理；它不要求先手动结算 Run 状态。一个有用的 Session 可以复用，
+但它绝不是 Task 上下文的唯一持有者。
+
+## 权限与 Project 上下文
+
+Provider 权限策略、Profile 访问意图和 Project 写范围是不同的合同。Provider 旁路
+不授予对另一个 Project 的写入。受管工作区 owner、精确 Assignment 和资源 grant
+落实 Yui 操作；宽泛的原生权限不是 OS 沙箱。
+
+Yui 提供其通用 Role Skill 和 Context 指针。Project Skill 仍是由 Agent 原生发现的
+普通 Project 文件。Project Knowledge 维护在 `YUI_HOME` 下；把仓库材料复制进 prompt
+并不使其成为权威 Knowledge。
+
+## 原生认证
+
+账号配置比 Session 活得更久。Yui 保留 `HOME` 和所选的 `CLAUDE_CONFIG_DIR`；
+新建/恢复的 Session 不会复制、清除或伪造原生登录、key 批准或 onboarding 记录。
+
+对 Claude Code，标准的 API-key、base-URL、bearer/OAuth、model-alias 以及原生
+provider 选择相关环境变量只转发给 Claude。这些值留在 Controller 可替换的运行时
+环境和子进程中，不进入 Task/Role 记录。取消某个来源并刷新 Controller 环境，即可
+在后续启动中移除它。其他自定义凭据变量仍使用显式的 Agent 环境绑定或原生用户设置；
+Yui 不继承整个 shell 环境，也不推断云凭据。
+
+Claude 自身加载原生设置，并按其生效配置在 API key、既有 helper、登录凭据、profile
+和云认证之间做选择。Yui 不注入 `apiKeyHelper`、不复制凭据文件，也不覆盖原生认证
+优先级。显式的 `--settings` 路径和 settings 来源选择被原样透传。
+
+全新的原生配置仍可能需要 Claude 的初始化、key、工作区和安全确认，包括访问初始化
+服务。隔离 `YUI_HOME` 或替换 Session 都不要求一个全新的原生账号目录。受管的 Task
+执行使用 Claude 的非交互 stream-json 路径，并沿用同样的原生配置归属。
+
+## 命令
+
+```sh
+yui config agent capabilities <agent-id>
+yui config role show <global-role>
+yui config profile show <profile>
+yui task role add <task> <role> --profile <profile>
+yui task role show <task> <role>
+yui task role update <task> <role> --environment <preparation-id>
+yui task role update <task> <role> --managed-environment
+yui task role session inspect <task> <role>
+yui task role session new <task> <role> --reason "<why a fresh Session is useful>"
+```
+
+创建 Role 时，显式的 Agent 设置需要 `--agent`。更新时，省略 `--agent` 针对活动
+绑定；一个具名绑定会被更新但不被激活。`task role bind` 更改选择。在更改期望设置
+之前，活动 Session 需要该命令的显式确认。
+
+关于原生配置和实现限制，参见 [Provider Runtime](provider-runtime.zh-CN.md)。

package/docs/sqlite-control-plane-design.md

@@ -1,3 +1,5 @@
+<p align="right"><strong>English</strong> | <a href="./sqlite-control-plane-design.zh-CN.md">简体中文</a></p>
+
 # SQLite control-plane storage
 
 Yui has one authoritative product Store: `YUI_HOME/yui.db` in WAL mode. The
@@ -67,10 +69,232 @@ Every persistent schema or payload change appends one immutable, contiguous
 storage migration. The CLI publishes both `storageVersion` and
 `minimumStorageVersion`; every valid Home in that inclusive range can upgrade
 directly to the current version without installing intermediate releases.
-The current source declares storage version **18**, with minimum supported
+The current source declares storage version **25**, with minimum supported
 migration version **1**, in `src/storage/storageVersions.ts`. Homes below that
 floor are not migration inputs and remain untouched.
 The target binary's `upgrade --update-preflight` and `--update-apply` result
 shapes and parent-owned handover-lock proof remain backward compatible with
 every updater released from storage version 1 onward, so an old source CLI can
 still drive a much newer target's complete migration chain.
+
+## Unified Home layout
+
+Every Yui self-managed directory lives under the single canonical `YUI_HOME`
+(default `~/.yui`; an explicit `YUI_HOME` is honoured verbatim). `YUI_HOME` is
+never inferred from the current working directory and never substituted with a
+username. `src/storage/homeLayout.ts` is the one authority that derives each
+managed root from Home:
+
+| Root | Path | Holds |
+|---|---|---|
+| Managed worktrees | `<home>/workspaces/tasks/<taskId>/<owner>/<projectDirectory>` | Actual Task/WorkItem/Review/Integration Git directories, addressed by the bound Project directory. Owners are `main`, `work-items/<id>`, `reviews/<id>`, `integrations/<id>` and `execution-lanes/<group>/<lane>`. |
+| Read-only context views | Within the same owner directory | Regenerable symlinks to read-only Project context only; writable entries are actual Git directories, not links. |
+| Global Role workspace | `<home>/workspaces/global` | Default cwd for Yui-auto-created Global Roles (the `yui setup` Operator/Leader and ad-hoc Global Roles added without an explicit `--workspace`). A plain cwd, not a managed Git workspace. |
+| Task provider runtimes | `<home>/runtime/task-runtimes` | Task provider data/cache/tmp; also the planning cwd at `…/planning/<taskId>`. |
+| Integration runtimes | `<home>/runtime/integration-runtimes` | The integration check's provider data/cache/tmp (a separate partition from Task runtimes). |
+| Update staging | `<home>/runtime/update-staging` | `yui update`'s side-by-side package install (an upgrade artifact). |
+| Release workflow scratch | `<home>/runtime/release-workflow` | The release workflow's smoke-install dir and verified publish-snapshot tarball (release artifacts). |
+| Storage backups | `<home>/backups` | Pre-upgrade DB backups (the fenced upgrade's rollback anchor). |
+
+Published migrations 1–23 remain unchanged, including Task artifacts in local
+Git (19), Integration continuation (20), force-archive evidence (21), and
+Controller-owned Host ingress (22), and unified message input control (23).
+The two offline layout steps are now 23→24 (`unify-home-layout`) and
+24→25 (`collapse-worktree-layout`). Version 24's
+`workspaces/worktree` directory is an intermediate layout, not a second live
+root at version 25. A single upgrade applies the full pending chain.
+
+Stop this Home's writers and take a backup before upgrading. The layout steps
+copy and verify the registered Git trees, repair only the copies' links, and
+preserve old sources for manual recovery. Version 25 replaces registered
+Task-view symlinks with real writable directories; unrelated Task scratch is
+retained. Read-only context remains a view and can be promoted to a writable
+worktree when WorkItem scope expands. Do not delete the old sources until the
+new layout is verified; a failed upgrade requires manual residue cleanup and
+backup recovery, not automatic resume.
+
+Both runtime partitions (`runtime/task-runtimes`, `runtime/integration-runtimes`)
+are the ONLY Home subtrees a provider runtime root is allowed to overlap; a
+runtime root overlapping any other part of Home (the database, `workspaces/`,
+`projects/`) is still rejected by `assertTaskRuntimeIsolationPreflight`, so
+unifying the root does not weaken control-data or cross-owner isolation.
+
+`defaultWorkspace` is a user-facing cwd for external Project input only; it is
+**not** a second authority for internal managed paths, and is intentionally not
+an input to `homeLayout.ts`. A Yui-auto-created Global Role that carries no
+user-chosen cwd no longer falls back to it (or to `process.cwd()`): `yui setup`'s
+built-in Operator/Leader and `yui role add` without `--workspace` now default to
+the Home-internal `managedGlobalRoleWorkspace(home)` (`<home>/workspaces/global`),
+and `setup` no longer fabricates an external Home-sibling `workspace/` — a
+`default-workspace` is persisted only if the user configured one. A user who
+*names* an external directory (explicit `--workspace`, or a configured
+`default-workspace`) keeps external-resource semantics; the outside-Home guard
+still applies to it. The "planning/global cwd" that criterion 1 places under Home
+is thus both the *disposable runtime cwd Yui materializes itself* — the Draft
+planning cwd (`planningRuntimeCwd`, under `runtime/task-runtimes/planning`) — and
+the auto-created Global Role cwd above; only an operator's *explicitly named*
+external directory stays outside by design.
+
+Only genuine short-path IPC socket ENDPOINTS remain outside Home, and only
+because a Unix-domain `sockaddr_un` path has a small fixed length budget that a
+deep Home path would exceed. Each is a single socket path, never a data/cache/tmp
+root:
+
+- the Controller socket (`/tmp/yui-<uid>/<homeId>.sock`),
+- the tmux server socket (`/tmp/tmux-<uid>` via the tmux namespace),
+- the Agent Host socket (`/tmp/yui-<uid>/agent-host/…sock`), and
+- the integration check's tmux socket dir (`/tmp/yi-<uid>-<digest>`), bound only
+  into `TMUX_TMPDIR`.
+
+The integration check's ordinary runtime state is **not** an exception: its
+provider data, cache, and temp roots live in the Home partition above
+(`runtime/integration-runtimes`); `TMPDIR`/`TMP`/`TEMP` point there, and only
+`TMUX_TMPDIR` is redirected to the short `/tmp` socket dir.
+
+## Migration 23 → 24: unify managed paths under Home
+
+Historically the managed worktrees lived under the out-of-Home
+`defaultWorkspace` (`<ws>/worktree`, `<ws>/tasks`) and the provider runtimes
+under a string-built Home sibling (`<home>.task-runtimes`). The one forward
+migration `unify-home-layout` (`src/storage/migrations/unifyHomeLayout.ts`)
+brings that content under Home and rewrites the persisted absolute pointers the
+runtime dereferences as live, without re-cloning Git content or renaming the
+path-independent Git refs. It runs as the migration's `migrateData` step inside
+the upgrade transaction, so schema and data advance atomically or roll back
+together.
+
+**Exactly one tree is physically relocated: the managed Git worktree tree.** It
+is the sole subtree that holds durable, non-regenerable content (committed **and**
+uncommitted work), so it alone is copied on disk. Everything else that "moves"
+moves only by pointer:
+
+- the per-Task symlink views (`<ws>/tasks`) are regenerable — the pointer is
+  rewritten and `ensureWorkspaceView` rebuilds the links at the next launch;
+- the provider runtimes (`<home>.task-runtimes`) are disposable — the pointer is
+  rewritten and the roots are recreated at the next launch.
+
+The worktree copy is **non-destructive and verified** (see *Recovery and
+rollback*): the source is copied (never renamed away), the replica's content
+digest is checked against the source, and only a verified replica is atomically
+published. The original worktree tree is **preserved** as the rollback anchor;
+removing it is a later, authorized, post-restart cleanup step, never part of this
+transaction.
+
+The pointer rewrite is **surgical, not a table sweep** — only records the runtime
+treats as live launch pointers are touched:
+
+- `managed_workspaces` — the authoritative registry (`path` column, payload
+  `root`, every `entries[].path`). Every surviving row is live (dispositioned
+  rows are deleted at cleanup).
+- active (`status='active'`) `turns` — **both** `run.effective.workspace` (the
+  actual OS launch cwd source) and the `run.workspace` mirror, rewritten together
+  because `validateRun` requires them to stay identical; a run's
+  `.result.systemEvidence.workspaceSnapshot` is frozen Git evidence and is left
+  byte-for-byte intact.
+- `role_session_sets` / `global_role_session_sets` — each live session's
+  `effective.workspace` in the `sessions` map; terminal sessions in `history` are
+  preserved.
+- `review_rounds` — the mirrored workspace (only while its `managed_workspaces`
+  owner row still exists) and each OPEN execution lane; an orphaned mirror or a
+  terminal lane is frozen evidence and is preserved.
+- `work_items` — each OPEN execution lane inside `executionGroups`; candidate
+  snapshots (`work_item_candidates`) are frozen and preserved.
+- `task_roles.workspace` — the live launch cwd, including a Draft's planning Role
+  under the old runtime sibling (never self-healed until activation).
+- `task_records.cwd` — self-heals on the next `prepareTaskWorkspace`, but is
+  rewritten defensively to close the stale-read window.
+
+Everything else is preserved on purpose: `context_snapshots`, terminal `turns`
+(with their system evidence), terminal sessions, `work_item_candidates`, terminal
+execution lanes, terminal `durable_jobs`, `events`, and reports are frozen
+history. `resource_registry` is re-discovered from disk; `projects.path` is an
+external, user-owned checkout.
+
+The migration is applied **offline** and is **fail-closed and pre-checkable**.
+It is run by the standalone `yui upgrade` boundary AFTER the operator has stopped
+this Home's Controller, Agent Host, and any execution/Job writers; it does not
+orchestrate that shutdown, coordinate an online write-stop, or migrate a live
+Session. It keeps only the minimal preconditions it can implement directly:
+
+- It **refuses** if a queued or running `durable_jobs` step is bound to a tree
+  about to relocate. A durable Job's runner is detached and could outlive an
+  incompletely stopped Controller, so moving that tree would risk an in-flight
+  silent move; this is the one residual runtime signal the offline migration
+  still guards. Let the Job drain or cancel it, then re-run the upgrade.
+  (`active_turns` is steady state, not an in-flight signal, and is deliberately
+  not consulted.)
+- It **refuses** if a relocation target already exists at all — it is either a
+  foreign directory or residue from a failed prior run, and the offline migration
+  never adopts a pre-existing target. Confirm the source is intact, then move or
+  remove the target and re-run the upgrade.
+- Every refusal is surfaced as a **collected, read-only pre-check**: `yui
+  upgrade --dry-run` and the updater's `--update-preflight` run the same plan and
+  the same blocking conditions execute would throw on, opening the DB read-only
+  and reporting each independent blocker as `{reason, detail}` (blocked outcome)
+  without mutating the Home — a genuine pre-check, not a best-effort guess.
+- A Home already in the unified layout (or a fresh Home with nothing to relocate)
+  is a **no-op**.
+
+### Recovery and rollback
+
+The migration keeps **no recovery manifest and no resumable state machine** — it
+is a one-time offline transform, not an interruptible online orchestration. The
+worktree relocation is **copy → digest-verify → atomic-publish → preserve-source**:
+
+1. the relocation target must not already exist; a pre-existing target is refused
+   up front (foreign directory or failed-run residue — never adopted);
+2. the source is copied into a same-filesystem staging dir (`<to>.incoming`),
+   never renamed away;
+3. a content-addressed inventory digest of the replica is compared to the source
+   — a mismatch deletes the staging copy and aborts (nothing published, source
+   intact);
+4. only a verified replica is `rename`d into the final target (atomic on one
+   filesystem);
+5. the original source tree is left in place as the rollback anchor.
+
+There is **no automatic idempotent recovery**. Because a pre-existing target is
+always refused, a run interrupted after a partial publish does not silently
+resume or adopt the partial tree on the next attempt: the operator inspects the
+preserved source, removes the incomplete target (and any `<to>.incoming`
+staging), and re-runs the upgrade from a clean state. The `--dry-run` /
+`--update-preflight` pre-check surfaces exactly this `target-conflict` before the
+apply transaction is entered, so the residue is reported, not discovered
+mid-migration.
+
+After the copy, the worktrees are reconnected. `git worktree repair` chases the
+absolute pointer files inside a worktree, so running it on a verbatim copy whose
+pointers still address the OLD source would rewrite the OLD source's `.git`
+files and corrupt the rollback anchor. The migration therefore **relinks first**:
+it deterministically repoints, in the NEW copy only, the two cross-reference
+pointer files (a linked worktree's `.git` stub and each
+`main/.git/worktrees/<name>/gitdir`) from OLD to NEW, and only THEN runs `git
+worktree repair` from each main clone at its new path as a belt-and-braces
+reconciliation now confined to the new tree. This keeps the preserved source a
+fully independent, working Git: its `.git` is byte-for-byte unchanged and it
+still resolves HEAD/index/status after the migration (verified empirically on a
+private disposable Home). **A repair failure is fatal** — it aborts the migration
+so the transaction rolls back rather than advancing the version over unrepaired
+worktrees.
+
+Because the data step runs inside the upgrade transaction, any throw rolls the
+schema back to its original version; the fenced upgrade orchestrator additionally takes a
+`database.backup()` and restores it on failure. Recovery from a failed run is
+**manual, not automatic**: because the source is never removed and the copy is
+digest-verified before publish, the preserved source is always intact, so the
+operator clears any partial target and re-runs the upgrade. No re-run can lose or
+corrupt the original content, but the tool does not itself resume an interrupted
+move set.
+
+**Old-source cleanup** is intentionally deferred and out of band: after a
+successful upgrade the old external `worktree`, `tasks`, and `<home>.task-runtimes`
+roots are left **in place** (not emptied) until an operator-authorized cleanup
+removes them. This keeps a full rollback anchor available across the first
+restart.
+
+**Rollback limits:** once the Controller restarts against the unified layout and
+begins writing new records under Home, restoring the pre-upgrade DB backup no
+longer matches the newly written on-disk state. Until that first post-upgrade
+write, the preserved old source plus the DB backup are a complete rollback pair;
+after it, the supported recovery is forward (the layout is already unified), not a
+downgrade to the split layout. Verify an upgrade only on a private, disposable
+Home before applying it to a shared environment.