@zq-silk/yui 0.15.8 → 0.15.9

package/dist/workItem/workItem.js

@@ -1,3 +1,4 @@
+import { validateGitArtifactRef } from "../artifacts/gitArtifactRef.js";
 import { normalizedUniqueIdentities, normalizedUniqueText, requireIdentity, requireText, requireTimestamp } from "../domain/validation.js";
 import { validateReviewConfig } from "../review/reviewConfig.js";
 import { taskFinalReviewConfig, validateTaskFinalReviewContract } from "../review/taskFinalReviewContract.js";
@@ -112,7 +113,7 @@ export function submitWorkItemCandidate(workItem, input, now) {
         ...(input.taskMainSnapshot === undefined
             ? {}
             : { taskMainSnapshot: input.taskMainSnapshot }),
-        ...(input.artifactRefs === undefined ? {} : { artifactRefs: input.artifactRefs.map((ref) => ({ ...ref })) }),
+        ...(input.artifactRefs === undefined ? {} : { artifactRefs: input.artifactRefs.map((ref) => validateGitArtifactRef(ref)) }),
         createdAt: now.toISOString()
     });
     const { outcome: _outcome, endedAt: _endedAt, ...base } = workItem;
@@ -502,17 +503,20 @@ export function validateWorkItemCandidate(candidate) {
     if (candidate.artifactRefs !== undefined) {
         if (!Array.isArray(candidate.artifactRefs))
             throw new Error("Candidate Artifact refs must be an array.");
-        const ids = new Set();
+        const identities = new Set();
         for (const ref of candidate.artifactRefs) {
-            requireIdentity(ref.artifactId, "Candidate Artifact id");
-            if (ref.taskId !== candidate.taskId || !["content", "external-version", "receipt"].includes(ref.kind)
-                || ids.has(ref.artifactId))
-                throw new Error("Candidate Artifact scope, kind or identity is invalid.");
-            if ((ref.kind !== "external-version" || ref.digest !== undefined)
-                && (typeof ref.digest !== "string" || !/^[a-f0-9]{64}$/u.test(ref.digest))) {
-                throw new Error("Candidate Artifact digest is invalid.");
+            // Pure, no-I/O shape check: the commit self-certifies the frozen bytes,
+            // so a valid pinned reference is complete evidence on its own. Existence
+            // is proven lazily when the bytes are resolved on the async read path.
+            const valid = validateGitArtifactRef(ref);
+            if (valid.taskId !== candidate.taskId) {
+                throw new Error("Candidate Artifact scope, commit or path is invalid.");
             }
-            ids.add(ref.artifactId);
+            const identity = `${valid.commit}:${valid.relativePath}`;
+            if (identities.has(identity)) {
+                throw new Error("Candidate Artifact scope, commit or path is invalid.");
+            }
+            identities.add(identity);
         }
     }
     if (typeof candidate.source !== "object" || candidate.source === null) {

package/docs/agent-result-consumption.md

@@ -1,3 +1,5 @@
+<p align="right"><strong>English</strong> | <a href="./agent-result-consumption.zh-CN.md">简体中文</a></p>
+
 # Agent result consumption
 
 Every explicitly dispatched AgentRun produces one durable original result.

package/docs/agent-result-consumption.zh-CN.md

@@ -0,0 +1,81 @@
+<p align="right"><a href="./agent-result-consumption.md">English</a> | <strong>简体中文</strong></p>
+
+# Agent 结果消费
+
+每一次显式派发的 AgentRun 都产生一个持久的原始结果。普通通知和原生对话不会
+隐式创建 Run。所有权链上的下一个 Agent 读取这个精确结果并判断它意味着什么。
+
+## 唯一的原始结果
+
+`AgentRunResult.output` 是 Agent 撰写的报告。Core 保留其字节，不解析、不分类、
+也不校验语义内容。Markdown、JSON 和普通散文都是合法的；缺少标题或结论不够有力
+都是质量证据，而不是运行时失败。
+
+Core 另外记录 Provider 身份/状态、完成时间、诊断、失败原因和系统拥有的工作区
+证据。非空输出必须符合当前传输上限且不含 NUL。缺失或不可传输的文本会让 Run
+失败，而不编造散文。当之后某个 Core 拥有的边界失败时，一份已到达的报告仍可以
+留在一个 failed 的 Run 上。
+
+终态结果会附带保存一条引用 Message。`task message show <task/message>` 和
+Context inspect 展开同一个 `resultRef`。ReviewRound 不持有第二份报告。文件和
+持久业务产物归 Artifact 或受管 Git 结果。
+
+## 执行不等于验收
+
+Run 生命周期是 `active / completed / failed`。Provider 结果、输入接受和资源静止
+是彼此独立的事实。Run completed 只表示它所需的 Core 执行边界成功，而不表示答案
+正确或 WorkItem 已验收。
+
+可写的 replicated Lane 需要其精确的、Core 拥有的工作区证据。分支错误、快照脏、
+owner 不符或范围不符都会让该边界失败，但不会替换一份已到达的原始报告。
+
+只有 Leader 决定证据是否足以验收、继续工作、再审查或放弃。Core 从不从 Agent
+文本中推导 findings、投票或修复拓扑。
+
+## 直接执行与复制执行
+
+直接的 WorkItem 执行使用一个 main Run，没有 ExecutionGroup。直接 Review 同样
+使用一个 main Reviewer Run。
+
+复制执行在一个冻结 Assignment 上使用彼此不同的 Producer Lane。每个 Producer
+保留自己的原始结果和精确血缘。Leader 显式地把彼此不同的终态来源 Run 引用交给
+综合。来源必须属于确切的 Group/Lane 且有结果，可以是 completed 或 failed。不存在
+自动综合、投票、最少成功 Producer 数，也不要求在选择来源前等待所有 Lane。
+
+综合快照保留所选来源顺序，以及它们原始输出、诊断和来源的有界视图，不复制完整
+transcript。只有 main 综合结果能提供 WorkItem Candidate 或权威的 replicated
+Review 结果。Producer 从不直接进入 Integration 或验收。重试针对失败的那次精确
+执行，不会静默重跑已成功的 Producer。
+
+## Review
+
+ReviewRound 拥有冻结的 Candidate 或 Task-head 身份、工作区来源、执行拓扑、精确
+的 main Reviewer Run、生命周期和 Core 诊断。它的 completed 状态是结构性执行证据，
+而不是从报告里提取出来的“通过”。
+
+Candidate 审查遵循其捕获的审查规则。Task-final 审查可以被显式请求，或由不可变的
+final-review 合同要求。一次被请求的审查是证据，而不是要求此后每次改动都审查的
+自动新策略。当前交付需要审查时，它必须覆盖确切的治理候选或 head 以及 completed
+的 main Run。
+
+Reviewer 应检查完整的有界范围，并把重要 findings 一并报告。Leader 读取完整报告，
+把 findings 路由给原 owner，直接修复 Task-main 上的小问题，只为有独立价值的实质
+工作创建新的 WorkItem。
+
+## Leader 消费
+
+唤醒窗口指向带结果的事件，包括在窗口之前创建、但在窗口之内完成的 Run。读取精确
+来源：
+
+```sh
+yui task wake show <task> <wake>
+yui task run show <task/run>
+yui task message show <task/message>
+```
+
+一个可选的报告结构是：结果、改动/发现、验证、不确定性和下一步动作。它是沟通
+建议，不是机器协议。
+
+验收与 Task 完成仍是显式操作，并带有当前 Git、审查、范围和资源检查。参见
+[执行与会话](managed-turn-and-session-runtime.zh-CN.md)和
+[Task 依赖](task-dag-semantics.zh-CN.md)。

package/docs/agent-runtime-drivers.md

@@ -1,3 +1,5 @@
+<p align="right"><strong>English</strong> | <a href="./agent-runtime-drivers.zh-CN.md">简体中文</a></p>
+
 # Agent runtime Drivers
 
 AgentEndpoint supplies the common execution boundary. Drivers translate native

package/docs/agent-runtime-drivers.zh-CN.md

@@ -0,0 +1,77 @@
+<p align="right"><a href="./agent-runtime-drivers.md">English</a> | <strong>简体中文</strong></p>
+
+# Agent 运行时 Driver
+
+AgentEndpoint 提供通用执行边界。Driver 把原生事件、错误和受支持的观察来源翻译
+成 `RuntimeObservation`；Controller、Store、CLI 和 Web 消费这份共享合同。
+
+## 职责
+
+连接实现拥有启动、协议、prompt 投递、resume 和中断。Driver 拥有原生身份提取、
+观察能力、事件/错误映射和用量归一化。Core 拥有权威、精确的请求关联、持久归并
+和投影；Agent 选择恢复方式并判断语义进展。
+
+内置 Driver 身份为 `openai/codex`、`anthropic/claude-code` 和
+`acp/agent-client-protocol`。ACP 是协议 Driver，不是产品标签。接入一个 ACP peer
+不需要另一套业务状态模型。
+
+能力必须如实声明。未知的 resume、取消、活动或用量行为不能从产品名推断。
+
+## 观察路径
+
+原生结构化事实通过精确的 Session/请求围栏，进入运行时收件箱，并归并为持久观察
+和原始结果。一个单独采样的用量来源可以馈入同一份规范合同。Driver 不能选择另一个
+actor、指派后继 Run，也不能绕过围栏。
+
+Yui Run 身份与 Provider 原生 Turn 身份不可互换。一个显式派发的 Run 保留其已接受
+的原生关联；直接的原生对话不是另一个隐式 Run。重放按精确事实身份去重，迟到事件
+不能终结一个后继。
+
+受管 Codex 使用 App Server 事件。Claude 映射其结构化流以及受支持的 Hook/来源
+负载。ACP 映射协议 Session 更新和 prompt 响应。终端文本、信任对话框和 prompt
+字形都不是生命周期事实。
+
+## 状态与错误证据
+
+持久 Run 生命周期是 `active / completed / failed`。输入处置、原生等待/活动、Goal、
+Session 生命周期和进程存在回答的是不同问题。UI 投影不得把一个排队中的请求当作
+Agent 忙碌的证明，也不得把一个存活进程当作接受。
+
+标准 Agent 错误保留 source、phase、category、code、输入处置、Session 处置以及
+序列化的原生错误。类别包括 availability、rate-limit、transport、access、
+invalid-request、context、session、runtime、conflict、cancelled 和 unknown。
+映射报告证据，而不是重试策略。无法识别的错误保持 unknown。
+
+运行时活动与工作流进展使用彼此独立的证据。一个工具边界可能显示原生活动；一个
+持久且被接受的结果才显示语义进展。token、CPU、RSS 和面板存在都不能替代接受或
+Task 完成。
+
+## 用量
+
+用量是只读的，范围限定在确切的原生 Session。输入/输出总量与缓存/推理分解、请求
+上下文和剩余容量区分开来。稳定的 activity ID 对请求快照去重；累计增量只在具备
+有效有序的同 Session 证据时使用。
+
+缺失、部分、混合或已回滚的观察保持“未观察”，而不是猜测。增量观察者报告健康度
+和覆盖度；采样不阻塞生命周期事件。度量绝不触发模型选择、唤醒、重试、资源释放
+或接受。
+
+## 原生子代
+
+原生 subagent 是父对话内部的协作，不是 Yui Role、Lane 或独立的受管工作区 owner。
+当 Provider 暴露血缘和结果引用时，continuation 观察可以记录它们。
+
+尽力而为的子代结果通过父代返回。只有持久化的内容回执才支持 `durable-result`；
+存活的子代或声称的成功都不行。被报告的结果仍是不受信任数据。一段丢失的尽力而为
+对话可能需要重做工作。当需要独立的持久性和验收时，选择受管的 WorkItem 执行；
+复制是另一个单独的选择。
+
+## 接入与验证
+
+一个新的连接实现必须提供如实的控制/观察能力，并把它们与精确的身份、错误和终态
+映射配对。Provider 专有的协议细节留在边缘，不进入 Task 规划、Store 语义或 Web
+业务规则。
+
+针对变更的一次性证据应覆盖被改动的关联、权限、取消或观察边界。永久测试保持在
+[验证策略](testing/verification-levels.zh-CN.md)中的主要路径。真实
+Provider/模型验证需要显式授权，并且必须把原生进程证据与夹具输出区分开。

package/docs/architecture/README.md

@@ -1,38 +1,50 @@
-# 当前架构与文档导航
+<p align="right"><strong>English</strong> | <a href="./README.zh-CN.md">简体中文</a></p>
 
-以下文档描述当前源码合同。能力边界不等于所有真实 Provider 场景已经验证。
+# Architecture and documentation map
 
-## 阅读入口
+These documents describe the current source contracts. A capability boundary is
+not a claim that every real Provider scenario has been validated.
 
-- [README](../../README.md)：安装、配置和日常使用。
-- [中文 README](../../i18n/README.zh-CN.md)：同一产品入口的中文说明。
-- [总体架构](../../ARCHITECTURE.md)：职责、权威和端到端流程。
-- [能力、资源与 Surface](capabilities-and-resources.md)：扩展入口、实例所有权和资源效果。
+## Start here
 
-## 领域合同
+- [README](../../README.md): install, configure and everyday use.
+- [Chinese README](../../i18n/README.zh-CN.md): the same product entry in
+  Simplified Chinese.
+- [Architecture overview](../../ARCHITECTURE.md): responsibilities, authority and
+  the end-to-end flow.
+- [Capabilities, resources and Surfaces](capabilities-and-resources.md): the
+  extension ingress, instance ownership and resource effects.
 
-| 问题 | 当前文档 |
+## Domain contracts
+
+| Question | Current document |
 | --- | --- |
-| Session、AgentRun、消息和激活如何配合？ | [执行与会话](../managed-turn-and-session-runtime.md) |
-| 谁消费结果、综合与审查？ | [结果消费](../agent-result-consumption.md) |
-| WorkItem 依赖何时满足？ | [Task 依赖](../task-dag-semantics.md) |
-| Task 内记录如何引用？ | [局部身份](../task-local-identity.md) |
-| Role、Profile 与运行配置如何生效？ | [角色与配置](../roles-and-configuration.md) |
-| 怎样交付、集成和归档？ | [交付生命周期](../task-delivery.md) |
-| Provider、ACP 与配置事实如何接入？ | [Provider Runtime](../provider-runtime.md) |
-| 运行观察和错误由谁解释？ | [Agent Drivers](../agent-runtime-drivers.md) |
-| 如何创建、验证与采用插件？ | [插件 SDK](../plugin-sdk.md) |
-| 数据、升级与并发的边界是什么？ | [SQLite Store](../sqlite-control-plane-design.md) |
-| 如何执行获授权的发布操作？ | [发布流程](../release-workflow.md) |
-| 如何查看当前运行证据？ | [可观察性](../observability/README.md) |
-| 哪些验证应长期保留？ | [验证策略](../testing/verification-levels.md) |
-
-## 维护约定
-
-行为变更同步修改所属合同和必要的入口说明。具体 CLI 参数以
-`src/cli/commandCatalog.ts` 和命令处理器为准；公开领域类型以运行源码为准，
-不另外维护一套目标模型或生成的离线副本。
-
-Project Skill 管理 Yui 的开发与验证规则；通用 Role Skills 管理 Agent 使用
-Yui 的职责。仓库文档不替代 `YUI_HOME` 中维护的 Project Knowledge，也不授予
-共享环境、真实模型或外部系统的执行权限。
+| How do Session, AgentRun, messages and activation fit together? | [Session and AgentRun runtime](../managed-turn-and-session-runtime.md) |
+| Who consumes results, synthesis and review? | [Result consumption](../agent-result-consumption.md) |
+| When is a WorkItem dependency satisfied? | [Task dependencies](../task-dag-semantics.md) |
+| How are records referenced inside a Task? | [Task-local identity](../task-local-identity.md) |
+| How do Roles, Profiles and run configuration take effect? | [Roles and configuration](../roles-and-configuration.md) |
+| How do delivery, integration and archive work? | [Task delivery](../task-delivery.md) |
+| How do Provider, ACP and configuration facts connect? | [Provider runtime](../provider-runtime.md) |
+| Who interprets runtime observations and errors? | [Agent Drivers](../agent-runtime-drivers.md) |
+| How are plugins created, validated and adopted? | [Plugin SDK](../plugin-sdk.md) |
+| What are the data, upgrade and concurrency boundaries? | [SQLite control plane](../sqlite-control-plane-design.md) |
+| How do authorized release operations run? | [Release workflow](../release-workflow.md) |
+| How do I read current runtime evidence? | [Observability](../observability/README.md) |
+| Which checks should be kept permanently? | [Verification policy](../testing/verification-levels.md) |
+
+## Maintenance conventions
+
+When behavior changes, update the owning contract and any entry-point text in the
+same change. The exact CLI flags are defined by `src/cli/commandCatalog.ts` and
+the command handlers; public domain types follow the running source. We do not
+maintain a separate target model or a generated offline copy.
+
+Each document is bilingual: `X.md` is the English version and `X.zh-CN.md` is the
+Simplified Chinese one. When behavior changes, update both language versions
+together so they stay in sync.
+
+The Project Skill owns Yui's development and validation rules; the generic Role
+Skills own how an Agent uses Yui. Repository documents do not replace the Project
+Knowledge maintained under `YUI_HOME`, and they do not grant execution access to
+shared environments, real models or external systems.

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 客户端，不接管原生对话的持久所有权。