@zq-silk/yui 0.15.8 → 0.15.11

package/docs/architecture/README.zh-CN.md

@@ -0,0 +1,43 @@
+<p align="right"><a href="./README.md">English</a> | <strong>简体中文</strong></p>
+
+# 当前架构与文档导航
+
+以下文档描述当前源码合同。能力边界不等于所有真实 Provider 场景已经验证。
+
+## 阅读入口
+
+- [English README](../../README.md)：安装、配置和日常使用。
+- [中文 README](../../i18n/README.zh-CN.md)：同一产品入口的中文说明。
+- [总体架构](../../ARCHITECTURE.md)：职责、权威和端到端流程（英文）。
+- [能力、资源与 Surface](capabilities-and-resources.zh-CN.md)：扩展入口、实例所有权和资源效果。
+
+## 领域合同
+
+| 问题 | 当前文档 |
+| --- | --- |
+| Session、AgentRun、消息和激活如何配合？ | [执行与会话](../managed-turn-and-session-runtime.zh-CN.md) |
+| 谁消费结果、综合与审查？ | [结果消费](../agent-result-consumption.zh-CN.md) |
+| WorkItem 依赖何时满足？ | [Task 依赖](../task-dag-semantics.zh-CN.md) |
+| Task 内记录如何引用？ | [局部身份](../task-local-identity.zh-CN.md) |
+| Role、Profile 与运行配置如何生效？ | [角色与配置](../roles-and-configuration.zh-CN.md) |
+| 怎样交付、集成和归档？ | [交付生命周期](../task-delivery.zh-CN.md) |
+| Provider、ACP 与配置事实如何接入？ | [Provider Runtime](../provider-runtime.zh-CN.md) |
+| 运行观察和错误由谁解释？ | [Agent Drivers](../agent-runtime-drivers.zh-CN.md) |
+| 如何创建、验证与采用插件？ | [插件 SDK](../plugin-sdk.zh-CN.md) |
+| 数据、升级与并发的边界是什么？ | [SQLite Store](../sqlite-control-plane-design.zh-CN.md) |
+| 如何执行获授权的发布操作？ | [发布流程](../release-workflow.zh-CN.md) |
+| 如何查看当前运行证据？ | [可观察性](../observability/README.zh-CN.md) |
+| 哪些验证应长期保留？ | [验证策略](../testing/verification-levels.zh-CN.md) |
+
+## 维护约定
+
+行为变更同步修改所属合同和必要的入口说明。具体 CLI 参数以
+`src/cli/commandCatalog.ts` 和命令处理器为准；公开领域类型以运行源码为准，
+不另外维护一套目标模型或生成的离线副本。
+
+每篇文档保持中英双语：`X.md` 为英文，`X.zh-CN.md` 为对应中文。行为变更时
+一并更新两种语言版本，保持内容一致。
+
+Project Skill 管理 Yui 的开发与验证规则；通用 Role Skills 管理 Agent 使用
+Yui 的职责。仓库文档不替代 `YUI_HOME` 中维护的 Project Knowledge，也不授予
+共享环境、真实模型或外部系统的执行权限。

package/docs/architecture/capabilities-and-resources.md

@@ -1,79 +1,118 @@
-# 能力、资源与 Surface
-
-## 唯一入口与原始事实
-
-Controller 承载 CapabilityRegistry 和 InstanceHost。`capability search`、
-`describe`、`call` 使用同一认证入口，先解析当前 Session 身份和 Task 范围，
-再检查能力与资源权限。输入中的 actor 或自称的 user scope 不能授予权限。
-
-描述符包含名称、合同版本、Provider、scope、输入输出 schema、effect 和
-requiredPermissions。查询只展示获授权的目录；同名 Provider 或版本有歧义时，
-调用者明确选择，不按加载顺序决定。Schema 是有界方言，未知关键词拒绝。
-
-当前目录覆盖 context、message、artifact、environment、resource、project、
-plugin 和部分 task/job 操作。Task 生命周期与部分 CLI/Web 写入直接共享
-领域命令；这些不是另一份业务状态，也不假称已经通过 Registry 执行。
-
-## 效果与操作事实
-
-能力返回值与真实效果分开。一次调用即使输出校验失败，也可能已产生确认的
-子操作；返回结果必须保留原 owner 的 operationRef 和 receipt。Unknown
-不能解释为未执行，不进行自动 fallback。
-
-嵌套调用重新检查当前权限，不能扩大父调用声明的权限与效果。requestId 标识
-调用，不自动提供所有业务的通用幂等性；Job 等 owner 执行自己的精确幂等合同。
-错误后先读取原操作事实再决定下一步。
-
-## 实现实例
-
-InstanceHost 管理 attach、acquire、release、detach 与实际引用。替换发布后，
-新调用选择新实现；已有引用继续绑定原实现，排空后才能 dispose。查询是观察，
-不启动或恢复代码。清理失败保留诊断，不把新发布反转为失败，也不伪造排空。
-
-Session 的长引用由实际 AgentHost 固定到所加载实现。Controller 传递已有 pin，
-不把活 Session 静默搬到另一份代码。结束客户端与共享 Provider 物理静止分别判断。
-
-## Project 与工作区
-
-Project 保存参考 checkout、Knowledge 与资源引用。稳定 checkout 只读；Task
-交付发生在受管 worktree。多 Project Task 使用独立 Git 根和明确写范围。
-工作区 owner 属于 Task、WorkItem、ReviewRound 或 IntegrationAttempt。
-Role 仅选择执行配置，不独立拥有另一份工作区状态。
-
-Git 集成捕获精确 ChangeSet，在候选 worktree 检查后 CAS 推进目标。
-冲突、检查失败、目标移动与拒绝都不更新目标，Agent 决定下一次操作。
-
-## Artifact 与环境
-
-- `artifact.save/read/list` 保存不可变内容、外部版本证据、Job 回执或引用资料。
-  Reference 不等于固定交付成果；最终结果不能选择缺失或跨 Task Artifact。
-- `environment.prepare` 准备 empty、scratch 或获授权 local 目录，不自动采用。
-- `environment.adopt` 复核身份、资源意图、权限与冲突后保存所有权。
-- `environment.bind` 选择 Role 下一次原生执行环境；`null` 返回 managed workspace。
-- `environment.release` 检查真实引用和静止证据，不删除用户目录。
-
-Adopted native launch 保留目录身份、access、isolation 与 preparation 引用，
-在 launch、resume 和 Yui 输入边界复核。撤权不能靠新 grant 静默重新采用旧环境。
-Read-only 环境的支持取决于实现；不能将目录 access 标签视为通用 OS 沙箱。
-
-## 插件与自扩展
-
-Task Leader 或 global Operator 可以管理该 Task 的插件；Worker/Reviewer 不能
-自行管理或授信。声明式插件不执行任意代码；trusted-local 插件执行还需要精确
-源码或产物摘要、环境和阶段的 grant。
-
-Store 保存 enabled 意图及验证产物，Host 保存实际实例。重启后 enabled 仍可读，
-actual 可以为空，必须显式激活。原 Task 可以发现并调用新能力，不必修改自身
-原生工具 schema。业务结果应保存为 Artifact，而不是依赖插件继续存活。
-
-完整作者、授权及失败合同见[插件 SDK](../plugin-sdk.md)。
-
-## CLI 与 Web
-
-Surface contribution 由 Registry 当前获授权目录派生，没有第二份目录或 Host。
-CLI contribution 使用能力原名称。Web panel 只接受受控 text、HTTP(S) link 或
-JSON query 描述，不接受作者脚本或任意 HTML。
-
-Web listener 由 Controller 启停，仅允许 loopback。浏览器写入通过现有领域
-事务，错误区分确定未提交与提交结果未知。查询面板不能借浏览器身份执行 mutation
-或插件管理。终端连接只 attach 客户端，不接管原生对话的持久所有权。
+<p align="right"><strong>English</strong> | <a href="./capabilities-and-resources.zh-CN.md">简体中文</a></p>
+
+# Capabilities, resources and Surfaces
+
+## One ingress, original facts
+
+The Controller hosts the CapabilityRegistry and InstanceHost. `capability
+search`, `describe` and `call` use one authenticated ingress: it first resolves
+the current Session identity and Task scope, then checks capability and resource
+permissions. An actor supplied in the input, or a self-declared user scope,
+cannot grant permission.
+
+A descriptor carries its name, contract version, Provider, scope, input/output
+schema, effect and requiredPermissions. A query shows only the authorized
+catalog; when a Provider or version is ambiguous, the caller selects explicitly
+rather than relying on load order. The schema is a bounded dialect, and unknown
+keywords are rejected.
+
+The current catalog covers context, message, artifact, environment, resource,
+project, plugin and selected task/job operations. Task lifecycle and some CLI/Web
+writes share domain commands directly; these are not a second business state and
+do not pretend to have run through the Registry.
+
+## Effects and operation facts
+
+A capability's return value is separate from its real effect. A call can produce
+a confirmed sub-operation even when its output validation fails, so the returned
+result must preserve the original owner's operationRef and receipt. Unknown must
+not be read as "did not run," and there is no automatic fallback.
+
+A nested call rechecks current permissions and cannot widen the permissions or
+effect the parent call declared. A requestId identifies the call; it does not
+supply universal idempotency for every downstream operation — an owner such as a
+Job runs its own exact idempotency contract. After an error, read the original
+operation facts before deciding the next step.
+
+## Implementation instances
+
+InstanceHost manages attach, acquire, release, detach and the actual references.
+After a replacement is published, new calls select the new implementation while
+existing references stay bound to the original one and can be disposed only once
+drained. A query is an observation; it does not start or recover code. A cleanup
+failure keeps its diagnosis, does not reverse a new publication into a failure,
+and does not fake a drain.
+
+A Session's long-lived reference is pinned by the actual AgentHost to the
+implementation it loaded. The Controller carries an existing pin forward and does
+not silently move a live Session onto different code. Ending a client and the
+shared Provider's physical quiescence are judged separately.
+
+## Projects and workspaces
+
+A Project stores its reference checkout, Knowledge and resource references. The
+stable checkout is read-only; Task delivery happens in a managed worktree. A
+multi-Project Task uses independent Git roots and explicit write scopes. A
+workspace owner is a Task, WorkItem, ReviewRound or IntegrationAttempt. A Role
+only selects execution configuration; it does not independently own a separate
+workspace state.
+
+Git integration captures an exact ChangeSet and advances the target by
+compare-and-swap after its checks pass in a candidate worktree. A conflict,
+failed check, moved target or rejection never advances the target, and the Agent
+chooses the next action.
+
+## Artifacts and environments
+
+- `artifact.save/read/list` maintains file/directory deliverables — complete
+  plans, prototypes, charts, reports — in the Task's own local-only Git
+  repository. `save` writes a `relativePath` and commits exactly that path,
+  returning a self-certifying `commit + relativePath` reference; `read` resolves
+  HEAD or a pinned commit for frozen evidence; `list` is an ordinary current
+  read. A reference is not a fixed delivery result; a final result cannot select
+  a missing or cross-Task artifact.
+- `environment.prepare` prepares an empty, scratch or authorized local directory
+  without adopting it automatically.
+- `environment.adopt` rechecks identity, resource intent, permissions and
+  conflicts, then records ownership.
+- `environment.bind` selects a Role's next native execution environment; `null`
+  returns to the managed workspace.
+- `environment.release` checks the real references and quiescence evidence and
+  never deletes a user directory.
+
+An adopted native launch retains the directory's identity, access, isolation and
+preparation reference, and rechecks them at launch, resume and the Yui input
+boundary. Revoking a grant cannot silently re-adopt an old environment on the
+strength of a new grant. Read-only environment support depends on the adapter; a
+directory access label is not a general OS sandbox.
+
+## Plugins and self-extension
+
+A Task Leader or the global Operator can manage that Task's plugins; a
+Worker/Reviewer cannot self-manage or self-trust them. A declarative plugin runs
+no arbitrary code; executing a trusted-local plugin additionally requires a grant
+scoped to the exact source or artifact digest, environment and phase.
+
+The Store keeps the enabled intent and validation artifacts, and the Host keeps
+the actual instances. After a restart the enabled selection is still readable,
+the actual instance can be empty, and activation must be explicit. The original
+Task can discover and call the new capability without rewriting its own native
+tool schema. A business result should be saved as an Artifact rather than
+depending on the plugin staying alive.
+
+See the [Plugin SDK](../plugin-sdk.md) for the full authoring, authorization and
+failure contract.
+
+## CLI and Web
+
+A Surface contribution is derived from the Registry's currently authorized
+catalog; there is no second catalog or Host. A CLI contribution uses the
+capability's original name. A Web panel accepts only controlled text, an HTTP(S)
+link or a JSON query description — not author scripts or arbitrary HTML.
+
+The Web listener is started and stopped by the Controller and allows loopback
+only. A browser write goes through an existing domain transaction, and its error
+distinguishes a definite non-commit from a committed-but-unknown result. A query
+panel cannot use the browser's identity to run a mutation or manage plugins. A
+terminal connection only attaches a client; it does not take over durable
+ownership of the native conversation.

package/docs/architecture/capabilities-and-resources.zh-CN.md

@@ -0,0 +1,83 @@
+<p align="right"><a href="./capabilities-and-resources.md">English</a> | <strong>简体中文</strong></p>
+
+# 能力、资源与 Surface
+
+## 唯一入口与原始事实
+
+Controller 承载 CapabilityRegistry 和 InstanceHost。`capability search`、
+`describe`、`call` 使用同一认证入口，先解析当前 Session 身份和 Task 范围，
+再检查能力与资源权限。输入中的 actor 或自称的 user scope 不能授予权限。
+
+描述符包含名称、合同版本、Provider、scope、输入输出 schema、effect 和
+requiredPermissions。查询只展示获授权的目录；同名 Provider 或版本有歧义时，
+调用者明确选择，不按加载顺序决定。Schema 是有界方言，未知关键词拒绝。
+
+当前目录覆盖 context、message、artifact、environment、resource、project、
+plugin 和部分 task/job 操作。Task 生命周期与部分 CLI/Web 写入直接共享
+领域命令；这些不是另一份业务状态，也不假称已经通过 Registry 执行。
+
+## 效果与操作事实
+
+能力返回值与真实效果分开。一次调用即使输出校验失败，也可能已产生确认的
+子操作；返回结果必须保留原 owner 的 operationRef 和 receipt。Unknown
+不能解释为未执行，不进行自动 fallback。
+
+嵌套调用重新检查当前权限，不能扩大父调用声明的权限与效果。requestId 标识
+调用，不自动提供所有业务的通用幂等性；Job 等 owner 执行自己的精确幂等合同。
+错误后先读取原操作事实再决定下一步。
+
+## 实现实例
+
+InstanceHost 管理 attach、acquire、release、detach 与实际引用。替换发布后，
+新调用选择新实现；已有引用继续绑定原实现，排空后才能 dispose。查询是观察，
+不启动或恢复代码。清理失败保留诊断，不把新发布反转为失败，也不伪造排空。
+
+Session 的长引用由实际 AgentHost 固定到所加载实现。Controller 传递已有 pin，
+不把活 Session 静默搬到另一份代码。结束客户端与共享 Provider 物理静止分别判断。
+
+## Project 与工作区
+
+Project 保存参考 checkout、Knowledge 与资源引用。稳定 checkout 只读；Task
+交付发生在受管 worktree。多 Project Task 使用独立 Git 根和明确写范围。
+工作区 owner 属于 Task、WorkItem、ReviewRound 或 IntegrationAttempt。
+Role 仅选择执行配置，不独立拥有另一份工作区状态。
+
+Git 集成捕获精确 ChangeSet，在候选 worktree 检查后 CAS 推进目标。
+冲突、检查失败、目标移动与拒绝都不更新目标，Agent 决定下一次操作。
+
+## Artifact 与环境
+
+- `artifact.save/read/list` 在 Task 自有的本地专用 Git 仓库中维护文件/目录交付物
+  （完整方案、原型、图表、报告）。`save` 写入 `relativePath` 并只提交该路径，
+  返回自证的 `commit + relativePath` 引用；`read` 解析 HEAD 或固定 commit 以取冻结证据；
+  `list` 为普通当前读取。Reference 不等于固定交付成果；最终结果不能选择缺失或跨 Task Artifact。
+- `environment.prepare` 准备 empty、scratch 或获授权 local 目录，不自动采用。
+- `environment.adopt` 复核身份、资源意图、权限与冲突后保存所有权。
+- `environment.bind` 选择 Role 下一次原生执行环境；`null` 返回 managed workspace。
+- `environment.release` 检查真实引用和静止证据，不删除用户目录。
+
+Adopted native launch 保留目录身份、access、isolation 与 preparation 引用，
+在 launch、resume 和 Yui 输入边界复核。撤权不能靠新 grant 静默重新采用旧环境。
+Read-only 环境的支持取决于实现；不能将目录 access 标签视为通用 OS 沙箱。
+
+## 插件与自扩展
+
+Task Leader 或 global Operator 可以管理该 Task 的插件；Worker/Reviewer 不能
+自行管理或授信。声明式插件不执行任意代码；trusted-local 插件执行还需要精确
+源码或产物摘要、环境和阶段的 grant。
+
+Store 保存 enabled 意图及验证产物，Host 保存实际实例。重启后 enabled 仍可读，
+actual 可以为空，必须显式激活。原 Task 可以发现并调用新能力，不必修改自身
+原生工具 schema。业务结果应保存为 Artifact，而不是依赖插件继续存活。
+
+完整作者、授权及失败合同见[插件 SDK](../plugin-sdk.zh-CN.md)。
+
+## CLI 与 Web
+
+Surface contribution 由 Registry 当前获授权目录派生，没有第二份目录或 Host。
+CLI contribution 使用能力原名称。Web panel 只接受受控 text、HTTP(S) link 或
+JSON query 描述，不接受作者脚本或任意 HTML。
+
+Web listener 由 Controller 启停，仅允许 loopback。浏览器写入通过现有领域
+事务，错误区分确定未提交与提交结果未知。查询面板不能借浏览器身份执行 mutation
+或插件管理。终端连接只 attach 客户端，不接管原生对话的持久所有权。

package/docs/managed-turn-and-session-runtime.md

@@ -1,3 +1,5 @@
+<p align="right"><strong>English</strong> | <a href="./managed-turn-and-session-runtime.zh-CN.md">简体中文</a></p>
+
 # Session, AgentRun and notifications
 
 ## Authority

package/docs/managed-turn-and-session-runtime.zh-CN.md

@@ -0,0 +1,180 @@
+<p align="right"><a href="./managed-turn-and-session-runtime.md">English</a> | <strong>简体中文</strong></p>
+
+# Session、AgentRun 与通知
+
+## 权威
+
+Task、WorkItem、Message、Decision、Artifact 和 Project Knowledge 保存持久工作。
+Session 标识一段原生对话及其捕获的权限。AgentRun 记录一次明确请求的执行和原始
+结果。AgentHost 是一次性 attachment，不是 Task 真相的 owner。
+
+一个当前、未撤销的 Leader Session 可以在没有活动 Run 的情况下读取 Context 并保存
+范围受限的 Task 事实，包括一个正式的 InputRequest。它确切的 Session 是该请求的
+来源；有实际 Run 时会一并包含。这个问题在该执行结束后仍然存在，直到被回答或取消
+才关闭。Worker 与 Reviewer 命令保留精确的 Assignment 检查。Session 替换、Role
+绑定、Task 范围和资源 grant 各在其边界检查。一个活动 Run 指针并不证明同一 Session
+中一条无关命令来自那个 Run。
+
+原生对话、Goal 延续和普通 Leader 通知不会自动创建 Run。显式派发加载一个确切的
+Run Context Pack。
+
+## Context
+
+```sh
+yui task context <task> --json
+yui task context delta <task> --after <coreCursor>
+yui task context inspect <task> --store <store> --ref <id>
+yui task run context <task/run> --json
+```
+
+Task Context 是一个有界的、获授权的工作集，带有当前 core 游标。delta 在一个固定
+上界内分页不可变事件；inspect 展开一条当前记录，并可要求确切摘要。运行时观察声明
+自己的覆盖范围，不会成为另一份持久快照。
+
+Run Context 冻结 Assignment、来源引用、生效配置和工作区边界。一次 Role 编辑不改写
+既有 Assignment。读取任一 Context 都不确认输入或创建执行权限。每一条受管输入都指向
+确切的 Session Manifest 和 CLI 入口。Run Pack 是一个参考目录：动手前先读相关的需求
+和消息正文，而不是把加载成功当成交付物。规划 Pack 不暴露 Project 写范围或 Task 完成
+权限。
+
+当前 Task 读取也会把无定向目标的 user/Operator 消息暴露给该 Task 当前的 Worker 和
+Reviewer Session，包括在它们 Run 快照冻结之后新增的需求。用 `task message list/show`
+或 Task Context inspect 来读取那些原始记录。这不改写冻结的 Assignment，也不授予投递
+权限。定向消息、其他 Role 的结果以及其他 Task 仍在调用者范围之外，除非其 Assignment
+授权访问它们。
+
+## 派发与通知
+
+一次显式派发在原生提交之前持久化执行意图。普通 Leader 唤醒则认领一个固定的
+TaskWake/mailbox 批次，并通过同一个 Host/Endpoint 提交一条通知。已确认的接受只消费
+那个批次；之后的输入仍待处理。通知不需要最终执行报告，也不会强行 steer 进入一段忙碌
+的原生对话。
+
+Leader 本地编辑保留持久事件，但不创建自唤醒。当 Leader 忙碌或不可用时，其他来源的
+输入仍然持久。Operator 通知同样携带 TaskEvent/InputRequest 读取指针，而不是重复的
+Task 叙述。人工输入、显式执行进入和激活失败通过既有唤醒机制及时投递。Worker 结果
+保留其聚合窗口。忙碌的原生输入仍保留待处理的消息。
+
+| 证据 | 处置 |
+| --- | --- |
+| 忙碌且已证明未接受 | 保留输入；新的传输尝试可以使用同一 Session |
+| 原生接受 | 绝不重发；若这是一次执行，等待确切终态 |
+| 仅有传输写入 | 保留传输证据；不宣称原生已接受 |
+| 显式拒绝 | 保留原始原因并结算相应的准入 |
+| 未知接受/效果 | 保留该尝试和冲突资源围栏；不重放也不切换 Session |
+
+崩溃后缺少回执不证明未接受。结构化的 `SESSION_BUSY` 是证据；含有 “busy” 字样的文本
+不是重试合同。
+
+## 延续既有工作
+
+```sh
+yui task message send <task> "Continue with the clarified requirement" \
+  --to <role> --work-item <work-item>
+yui task message handoff <task/message> --to <successor-role>
+```
+
+Review 澄清使用 `--review-round` 代替 `--work-item`。Message 保留收件人、工作关联和
+owner Run。当 Role 忙碌时，保存会返回而不打断它。一旦它可用，一个有界有序批次可以
+创建一个 continuation Run，与那些消息原子地关联。既有 Assignment、生效权限、工作区
+和未完成文件都保留；快照再加上获授权的消息和前一次原始结果。重复的终态不能把消息
+指派两次。
+
+所有权变更、不兼容的 Session、终态工作和过时的 Review 候选都保留可见的未投递原因。
+显式 handoff 只针对同一工作已派发的后继。复制的 Producer/综合血缘不会被一条消息
+静默改写。
+
+未知的 Leader 通知保留其唤醒和输入窗口：
+
+```sh
+yui task wake show <task> <wake>
+yui task wake resolve <task> <wake> --reason <quiescence-evidence>
+```
+
+resolve 在原生效果围栏清除后释放该认领。它既不重放通知，也不编造接受或完成。独立的
+Role 工作和合法的本地事实不是一把 Task 范围的恢复锁。
+
+## 精确结果
+
+原生终态只结算相匹配的那次执行。已知的原生 Turn ID 必须匹配；串行流可以使用已证明的
+本地尝试关联。message UUID 不是原生 Turn ID。同一 Session 中无关的原生对话不能完成
+待处理的 Yui 请求。
+
+终态事务保存一个 AgentRunResult 和一条引用 Message。
+`resultRef: { type: "agent-run-result", runId: "run-12" }` 展开原始报告而不是复制它。
+Candidate 和 ReviewRound 保留来源；Core 不从散文中推导语义接受。
+
+取消请求不证明物理静止。确切的终态证据保留部分输出，并只结算原始执行。Host 退出
+并不意味着共享 Provider 或后代进程已停止。
+
+## Draft 规划与激活
+
+`EffectiveLaunchSnapshot.executionAuthority` 捕获 `planning | delivery`。它不从 Task
+当前生命周期重新计算。planning 允许本地规划事实，不允许交付派发、候选采用、集成或
+交付工作区 Job。
+
+初始 Draft 规划派发创建一个 planning Run，并只绑定其初始消息批次。接受或一个确切终态
+消费该批次；失败不会反复重建同一个规划执行。既有 planning Session 中后续的普通消息
+仍是通知。Operator 提交和直接的 Task 消息都能到达那个 Session。Draft 计划/WorkItem
+编辑保留执行历史；外部编辑通知 Leader，而它自己的规划编辑不创建自唤醒。
+
+新的 Draft Role 使用位于 `<YUI_HOME>.task-runtimes/planning` 下、专属于该 Task 的规划
+目录，在控制 Home 和交付树之外。一个 planning Run 可以用 `task activation request`
+持久化意图并立即返回一个 `afterPlanningRun` 引用。它的终态把该请求释放给 Controller
+准入；被取消的意图不会复活。Leader 也可以在普通讨论中请求激活而无需 AgentRun：一旦
+原生输入结算，Controller 就采用其持久意图。不需要合成 Run 或额外的用户“continue”。
+
+对于已绑定的 Git Project，`--environment empty` 表示没有额外环境：这些 Project 仍会
+获得受管 worktree。`scratch` 选择一个 Task 拥有的目录。`local` 需要一个已登记的 local
+Resource 及其 grant；Project ID 不是 local Resource ID。
+
+资源准备先于对 Task 状态和工作区所有权的原子采用。一次失败的采用记录一个失败请求，
+并用持久事实通知 Leader；在失败未变时它不反复准备资源。Leader 选择显式重试或修正后的
+请求。成功激活同样为 Leader 留下一条交付通知。激活绝不把活动 Session 变更为交付权限。
+一次改变的启动必须通过既有的 Session 替换/环境边界。planning 权限是一项 CLI 保证，
+不是针对恶意代码的文件系统沙箱。
+
+## 检查与生命周期
+
+```sh
+yui task run list <task>
+yui task run show <task/run> --json
+yui task message show <task/message>
+yui task role session inspect <task> <role>
+yui task execution start <task>
+yui task execution stop <task> --force --reason <reason>
+```
+
+Task execution start/stop 控制 Task 准入，而不是 Task 验收。stop 先围住新的 Yui 工作，
+然后中断每一条被拥有的确切原生输入，并在移除 attachment 之前确认其终态。这也覆盖没有
+Run 的普通 Leader 通知。未知的原生状态阻塞清理；仅停止一个代理绝不证明一个共享 Turn
+已结束。start 保留持久进展，并在旧占用结算后接纳新输入。Draft 规划可以暂停/恢复，
+失败的 planning Run 以 planning 权限重试。获授权的 user/Operator 可以通过
+`task role session stop` 停止一个空闲的 Draft Session；它不必仅为恢复就激活 Task。
+`task role session new <task> <role> --reason <reason>` 持久化一个显式替换请求。复用是
+一种偏好，而不是要求证明旧对话不可恢复。该请求在 AgentRun 活动、Session 已结束或
+上一次清理待处理时都是合法的。Leader 也可以请求替换自己并结束当前轮次。
+
+`task role session stop` 也可以在不先更改 Run 状态的情况下停止一个运行中的 Role。它
+保留原生对话以备复用。待处理的 Message 仍是意图，可以在停止后启动一次 continuation；
+当整个 Task 都必须保持暂停时，使用 Task execution stop。对于自我替换，使用异步的
+`session new` 请求，而不是同步的自我停止。
+
+既有的运行时清理路径停止确切的原生执行，把该 Role 剩余的工程尝试关闭为 cancelled，
+保留 Session/Run 历史和工作区，并选择一段新对话。其他 Role 和 Task 验收保持不变。
+Leader 收到一条新的上下文通知；它决定重试哪些 Worker/Reviewer 尝试。待处理的输入
+引用在替换后仍然存在，包括比新通知时间窗更早的记录。
+
+一个缺席的 Host 不移除恢复入口。Codex 可以通过一个一次性的原生控制连接被检查和中断，
+而不启动模型。专用 Claude 进程托管独立于 Host 持久化。真实的未确认执行仍阻止冲突资源
+复用；清理失败是一条路由给 supervisor 的持久诊断，而不是编造接受或删除 Task 的理由。
+仅有一个预分配的 ID 不证明一段对话存在。Codex 在一次失败的原生 Turn 之后可能保留
+`systemError`。仅凭那个标签既不证明活动也不授权清理：Yui 在替换 Session 之前会检查
+最新原生 Turn 的终态元数据并排空后台执行。未知或仍在运行的原生工作仍受保护。
+
+已释放的 Leader 保留对自己 Task 和上下文的范围受限诊断读取，但不能修改它或读取另一个
+Task。Operator 诊断和 Controller 重启不先要求一个健康的 Controller；当 RPC 不可用时，
+显式重启只能用 PID/start 身份停止同一 Home 的那个确切进程。Operator 的存储诊断/升级
+也能到达专用的迁移入口，而不先要求 Home 已经处于目标存储版本。完成、取消和归档具有
+彼此不同的权限和资源边界。存储变更使用唯一的
+[升级合同](sqlite-control-plane-design.zh-CN.md)。

package/docs/observability/README.md

@@ -1,3 +1,5 @@
+<p align="right"><strong>English</strong> | <a href="./README.zh-CN.md">简体中文</a></p>
+
 # Runtime observations and diagnostics
 
 Read-only projections help an Agent distinguish durable intent, actual runtime

package/docs/observability/README.zh-CN.md

@@ -0,0 +1,71 @@
+<p align="right"><a href="./README.md">English</a> | <strong>简体中文</strong></p>
+
+# 运行时观察与诊断
+
+只读投影帮助 Agent 区分持久意图、实际运行时活动和未知效果。它们不引入第二套
+调度或验收权威。
+
+## 检查
+
+```sh
+yui controller status
+yui execution audit --task <task-id> --json
+yui task next-action <task-id>
+yui task role session inspect <task-id> <role>
+yui task run show <task-id>/<run-id> --json
+```
+
+Controller status 暴露当前进程与 Home 身份。Session inspect 区分期望绑定、
+生效启动、实际连接以及 Agent 自报配置。Run 检查暴露原始输入、处置、精确结果
+和诊断。读取状态不会启动另一个 Agent，也不确认工作。
+
+## 证据的含义
+
+- Task 与 WorkItem 生命周期描述意图和验收。
+- AgentRun 生命周期描述明确请求的一次执行。
+- Provider 接受与原生活动描述实际的输入/连接。
+- Host PID、tmux 与资源清单描述进程观察。
+- 运行时配置区分请求值与自报值。
+- token、时长与编排成本是仅供参考的观察。
+
+对于专用 Claude 流，一次主 assistant 响应会在终态结果之前确认当前这一条本地
+输入已被处理。因此该响应到达后，Controller 与 Role 读取才显示 accepted/running。
+启动、回显的用户输入、子响应以及重复的旧消息都不建立新的接受；message UUID
+永远不作为原生 Turn ID。
+
+普通 Leader 通知是 TaskWake/mailbox 投递，不是 Leader Run。即使没有打开
+AgentRun，Role 状态也包含其原生准入/活动；当某个 WorkItem 处于终态时，它显示
+保留 Session 的实际工作区，而不是用 Task main 顶替。未知证据仍为未知；进程退出
+不证明共享 Provider 已停止，传输成功也不证明原生已接受。
+
+工程控制证据可以比附着的 Session 缓存活得更久。这样的 Role 会把保留的原生输入
+报告为需要关注，而不因缓存为空就当作空闲。范围受限的 Task/Session 检查仍可用于
+诊断。替换与原生清理失败是持久事件，路由给 supervisor；替换后待处理的输入引用
+仍然可读。
+
+精确的工具 start/result 事件投影为 `tool-active`，模型活动投影为 `model-active`；
+安静间隔并不意味着 Agent 卡住或已完成。工具失败是操作结果，不是自动的 Run 失败。
+被拥有的 Claude 执行进程若死亡，会关闭其精确输入并把 Session 标记为 failed，即使
+监督它的 Host 仍存活。一个已被有意停止、且原生输入已结算的 Session 是空闲状态，
+而不是虚假的运行时失败。
+
+## 执行审计
+
+`execution audit` 汇总既有的 Task、Run、wake、Session、Review、Integration、
+Publication、事件、WorkItem、存储和编排证据。`--since` 与 `--until` 界定时间窗。
+各部分各自报告自己的读取错误，不为缺失数据编造值。
+
+故障分类使用 Core 拥有的失败原因或明确标识的 Core 诊断证据。Agent 撰写的报告
+散文不会被解析为判定或严重级别。原生 Agent 错误保留其原始负载和标准类别，供
+Agent 结合当前 Task 上下文解读。
+
+成本与重复劳动提示不会阻止一个合法动作、设定 Review 预算或选择恢复拓扑。
+`task next-action` 是决策支持，不是自动执行的计划。
+
+## 隐私与资源边界
+
+Telemetry 和缓存是诊断材料，不是 Task 真相，也不是 transcript 备份。不要仅为
+解释某个状态就采集或发布凭据、私有环境值或原始 Provider 历史。
+
+从精确的只读记录开始。进程变更、取消、grant 更新和资源清理都需要相应的显式动作
+与范围。一个笼统的诊断请求不授权真实模型、共享或生产环境的测试。