@zq-silk/yui 2.1.0 → 2.2.0

package/docs/native-agent.md

@@ -0,0 +1,283 @@
+# 独立编码 Agent 入口
+
+升级前请阅读 [2.2.0 兼容性及迁移说明](release-workflow.zh-CN.md#220-兼容性及迁移说明)：
+Yui 的 minor 编号不承诺向后兼容，旧 `createAgent({onEvent})` 调用方须迁移到
+`recorder`／`observer`，否则旧回调不会执行。
+
+`yui agent` 与控制面共用安装包，不共用运行生命周期：它在控制面模块加载之前
+分流，不初始化或读取 Yui Home，不启动 Controller/Task/Role/Host/ACP。
+既有管理命令仍是 `yui config agent`。
+
+当前入口已装配真实 kernel、ModelGateway、ExecutionOwner、工具、上下文、
+SQLite、行式交互和观测，以及真实本地安全 binding/permission/environment、
+项目指导、按需完整Skill与唯一项目MEMORY。
+已接入真实持久 Session catalog、标题CAS、有界历史和原子不可变root/cwd；
+新进程按明确ID恢复原位置，并重新获取本次授权。本文描述本地实现，
+不替代独立Review或Leader最终接受。
+
+## 启动
+
+源码开发先运行 `make install-local`，使用 checkout 的绝对
+`output/dev/bin/yui` 和独立 `YUI_HOME`。以下 `yui` 代表安装包命令，
+或该绝对开发入口；不需要 `yui setup`：
+
+```sh
+# 使用自己明确选择的凭据变量；示例不提供真实凭据。
+yui agent check-config --config /absolute/agent.json
+yui agent start --config /absolute/agent.json
+yui agent run --config /absolute/agent.json --input '读取 input.txt，说明内容'
+# 用前次 receipt 中的 ID 明确恢复；不要自动选择最近会话。
+yui agent run --config /absolute/agent.json --session SESSION_ID --input '继续'
+```
+
+显式 JSON 文件（不自动发现、执行或保存配置）：
+
+```json
+{
+  "schemaVersion": 1,
+  "adapter": "chat-completions",
+  "endpoint": "https://your-selected-provider.example/v1/chat/completions",
+  "model": "your-explicit-model",
+  "credentialRef": "env:MY_AGENT_KEY",
+  "root": "/absolute/controlled/repo",
+  "cwd": "/absolute/controlled/repo",
+  "stateDir": "/absolute/agent-state",
+  "tools": ["read", "list", "find", "search", "project_context", "project_memory"],
+  "maxSteps": 8,
+  "contextBytes": 1048576,
+  "outputReserveBytes": 0,
+  "modelTimeoutMs": 30000,
+  "stream": false
+}
+```
+
+仅支持当前 Chat Completions 文本/function 协议子集，endpoint 是完整地址，
+不自动拼路径。HTTPS 不允许 userinfo/query/fragment；本地 HTTP fixture 必须
+显式 `--allow-http`，且只能是 loopback。无认证必须明确
+`credentialRef: "anonymous"`，缺少 key 不会降级成匿名。
+
+`check-config` 校验数据与凭据是否可解析，显示非敏感有效配置及来源；
+不请求网络、不创建状态库。实际存储打开失败在启动时报告。
+文件最多64 KiB、schemaVersion必须为1、未知字段拒绝，不读取项目代码配置。
+
+优先级逐字段为 CLI > `NATIVE_AGENT_*` > 所选文件 > 安全默认；
+工具数组完整替换，不合并能力。环境项为 `NATIVE_AGENT_ADAPTER`、
+`ENDPOINT`、`MODEL`、`CREDENTIAL_REF`、`ROOT`、`CWD`、`STATE_DIR`、`TOOLS`、
+`MAX_STEPS`、`CONTEXT_BYTES`、`OUTPUT_RESERVE_BYTES`、`MODEL_TIMEOUT_MS`、
+`STREAM`、`COMMAND_CONFIG`（每项都带 `NATIVE_AGENT_` 前缀）。CLI 对应 `--credential-ref`、
+`--state-dir` 等 kebab-case 名称；tools是逗号分隔，stream是true/false。
+文件相对路径基于文件目录，CLI相对路径基于启动目录，环境路径必须绝对。
+新建时cwd默认启动目录、root默认有效cwd；可分别指定`--root`、`--cwd`。
+root/cwd都必须存在、为规范化目录、所有路径组件无软链，cwd须位于root内。
+恢复时未明确指定的位置从同ID持久详情读取，不使用新进程启动目录默认值；
+CLI、环境或配置文件明确指定的root/cwd与原位置冲突则拒绝。
+model/endpoint/credentialRef/stateDir无账号或Home回退。
+
+预算只承诺已有机制：maxSteps为1–100、contextBytes为1–1048576的JSON字节，
+outputReserveBytes小于contextBytes；modelTimeoutMs为1–300000的单次模型逻辑请求
+总预算（包括网关已分类重试等待），不是整个Turn或命令的硬超时。
+工具现有大小/命令超时上限仍生效；不承诺货币、token或整体墙钟限额。
+
+## 明确选择副作用
+
+默认选择read/list/find/search及只读project_context/project_memory。选择write/edit或command时，当前调用必须分别
+带`--allow-write`或`--allow-command`，不能从配置、环境或历史自动恢复这些opt-in：
+
+```sh
+# agent.json须含下述已审查command配置；单有allow-command不授予任意命令。
+yui agent start --config /absolute/agent.json \
+  --tools read,list,find,search,write,edit,command --allow-write --allow-command
+```
+
+入口使用真实 `createLocalToolBinding`，同一工厂的编码tools、permission、environment
+通过公开能力组合交给唯一 `createToolExecutor`，不使用 Agent 的 tools 简写。
+编码调用保留原工厂的活lease和实际权限检查；普通项目工具不获取编码lease，
+按其Session作用域、具体action与本次授权检查，不向82私有声明集合注入外来工具。
+实际声明仍受 `tools` 选择限制。root 与 cwd 绑定到有效配置或已保存的原位置；
+不会从 `.git` 或项目文本推断更大根。有效配置和 binding 描述可供核对真实目录。
+文件工具相对路径基于root，只有命令使用固定cwd；二者可不同。
+目录身份在授权和执行时复核，替换/消失/软链变化拒绝旧绑定。
+
+选择command还必须提供调用方审查过的完整规格：所选JSON文件的 `command` 字段，
+或 `--command-config JSON` / `NATIVE_AGENT_COMMAND_CONFIG` JSON值。
+例如文件中加入：
+
+```json
+{
+  "command": {
+    "env": {"LANG": "C"},
+    "specs": [
+      {"executable": "/canonical/path/to/reviewed-program", "argv": ["--check"], "effect": "read"}
+    ],
+    "timeoutMs": 10000,
+    "maxOutputBytes": 65536,
+    "killGraceMs": 1000
+  }
+}
+```
+
+这是片段，需合并进前述version-1配置；程序路径必须是真实规范化绝对普通可执行
+文件、无软链组件。argv逐项精确匹配，command调用的cwd必须等于绑定cwd；
+程序身份变化、额外参数、另一个解释器或目录均拒绝。`effect:"write"` 还需要本次
+`--allow-write`，仅 `--allow-command` 不允许写规格。上述三个预算字段可省略，
+沿用工具预算；无command配置时不能启用command。
+
+规格不是程序分析或只读证明。调用方必须审查具体程序、完整参数及其实际配置行为；
+不得把模型临时生成的脚本、可写脚本文件、可变外部配置或任意参数当作已审查规格。
+`--allow-command` 不是任意shell/脚本权限。离线例子只授权代码中固定且已审查的
+fixture检查程序，不代表可以自动授权任意模型建议。
+
+env是完整白名单环境，只允许显式PATH/LANG/LC_ALL/TZ，默认`{}`；
+不继承process.env/HOME/凭据/代理/加载器变量。PATH目录及程序仍须可信审查。
+公共配置输出不打印command规格、argv或环境值，binding只报告envKeys/commandCount。
+模型请求另含本次调用的最小运行事实：实际root/cwd、所选工具、当前独立授权开关，
+以及当前可执行的已审查executable/argv/effect（没有command授权时为空）。
+它通过既有ContextBuilder作为required的user数据材料进入请求，不是system指令，
+也不能替代82的实际授权校验；不足预算则拒绝请求。环境值、凭据和权限token不进入
+该材料，材料本身不写入历史；恢复时按原位置和本次配置重新建立，绝不恢复旧授权。
+原始调用/结果是必要执行事实，仍会保存到历史；不要在argv或配置中放秘密。
+入口把当前已知凭据传给82的outcome脱敏，并继续保护模型/记录/诊断出口；
+这是已知秘密文字保护，不是全通道DLP，也不改变被读取文件的实际内容/sha256。
+
+改变工具/授权需先取消并等旧owner结算、关闭，再显式重开。
+每次启动/指定ID恢复均从当前配置和本次opt-in创建新binding/executor，重新验证目录、
+程序与授权；旧标题/ID/历史/描述不授予权限，不热更新旧lease。
+不实现`/permissions`或授权提示UI。命令仍可访问root外的路径、网络与系统资源，
+不对敌对文件系统或脱离进程组的后代作隔离保证，不是OS强沙箱。
+
+真实凭据仅用于内存中的模型认证；不保存在配置/历史/日志/诊断中，不传给工具
+子进程。已知的当前凭据若出现在模型响应/工具参数/必要记录，入口拒绝该出口，
+停止后续效果；不把秘密写入错误。流式正文不直接显示，避免分片泄密；
+UI显示确认消息、工具事件和不含正文的观测。无法识别用户主动输入的其他秘密。
+
+## 输入、取消、关闭与保存
+
+`start`复用行式UI：普通文本提交；`/cancel`按精确活动Turn身份取消；
+`/history [CURSOR]`查询真实分页事件，`/sessions [CURSOR]`查询持久目录；
+`/info`读取当前会话详情，`/rename METADATA_REVISION JSON_TITLE_OR_NULL`用明确版本改名；
+`/use ID`选择明确会话，`/new [title]`新建并通过真实catalog保存标题；
+`/quit`、EOF或SIGTERM关闭整个产品。Ctrl-C在执行时请求取消，在空闲时退出。
+取消不是回滚：已发生的文件/命令效果仍按真实结果保存；未知效果不重放。
+执行所有者先取消/drain，再关闭SQLite、观测、响应体和自有HTTP连接池，
+移除信号/输出监听。UI断开不是工具停止证明。
+
+正常/取消/预算终态的receipt由真实SQLite记录产生并与再次load的digest/revision
+核对；展示终态不等于已保存。保存失败只给lastConfirmedReceipt及检查建议，
+不声称完整Turn已保存，不重试必要记录。`run`返回JSON：
+configuration/binding/projectAuthority/result/receipt/observations；退出码0完成，1错误或保存失败，
+2配置错误，3步骤预算耗尽，130取消/中断，143终止信号。
+全局`--json`前缀与`run/check-config`的`--json`标记也在控制面加载前处理；
+`start`是行式UI，若要求JSON则明确拒绝并建议使用run。
+工具执行非零exitCode不是业务成功；完整结果中需要检查实际工具outcome。
+`/refresh`回放旧终态不会等待当前Turn执行；回执展示只读取同一精确Turn已结算的
+owner证据，再核对当前存储的digest/revision。挂起模型期间仍可取消、退出或EOF，
+旧Turn回执不会冒充新Turn的保存证明；关闭时仍等待取消/drain与实际保存完成。
+
+状态文件固定为显式stateDir下`sessions.sqlite`，使用独立Session文档格式2和
+81的SQLite NAS1布局4、集中v1→v2→v3→v4迁移，不改变Yui Home版本。合法v2/v3文档
+字节/revision/digest保留，标题和事件投影保留，旧记录位置明确为null；
+未知/损坏格式拒绝，迁移失败回滚。旧二进制不能打开布局4，不提供自动降级。
+新状态目录0700、数据库0600；
+已有目录权限不擅自重设。请独占受控状态目录，每个Session只运行一个owner；
+CAS不是跨进程执行租约。恢复非ready状态被拒绝且不自动修复/重放。
+掉电/SIGKILL不保证finally运行；强沙箱、真实模型质量和其他平台未验证。
+
+## 持久目录、命名与有界历史
+
+关闭所有连接后可从新进程查看原目录，不需要模型配置、cwd或工具授权：
+
+```sh
+yui agent sessions --state-dir /absolute/agent-state --limit 20
+yui agent session-info --state-dir /absolute/agent-state --session SESSION_ID
+yui agent history --state-dir /absolute/agent-state --session SESSION_ID --limit 20
+yui agent rename --state-dir /absolute/agent-state --session SESSION_ID \
+  --expected-metadata-revision 0 --title '"我的会话"'
+# 清除标题用 --title null；下一页原样带回nextCursor并保留原limit。
+yui agent sessions --state-dir /absolute/agent-state --limit 20 --cursor OPAQUE_CURSOR
+```
+
+这些命令只消费真实SessionCatalog，不创建Agent/owner、不调用模型、不重放工具；
+改名是用户明确请求的元数据CAS写入，不是执行授权。它们打开已存在的目录和数据库，
+缺失时报错且不新建。打开合法旧库仍可能运行81的既有格式迁移，不承诺字节级只读。
+状态目录CLI优先于`NATIVE_AGENT_STATE_DIR`，环境路径须绝对；这些目录命令不读取
+模型配置文件。可用`--credential-ref env:NAME`或`NATIVE_AGENT_CREDENTIAL_REF`
+指定当前已知凭据的输出保护，不请求账户/模型；未指定时也不猜测其他秘密。
+
+目录返回真实sessionId/title/metadataRevision，不返回历史正文或猜测live状态。
+标题可重复，选择只用ID。标题版本与事件revision/digest独立；改名不改历史回执。
+页大小1–100，默认20；UI固定20。不透明cursor绑定库、操作、Session、limit和相应
+版本；过期或错配明确报cursor_stale/invalid_cursor并要求用户从首屏刷新，
+不自动换页、不混合新旧结果。历史页是原始revision/event，可能跨页配对，
+不是恢复上下文；真正submit仍由唯一ExecutionOwner从同一store完整load/recorder
+检查。未知效果或cleanup-required历史可查，但查询不会消除恢复限制。
+
+元数据写确认失败保守报告effect:unknown、精确Session ID和对账建议，
+先读当前title/metadataRevision，不能盲目重试。新建后标题保存失败时保留已创建
+的空Session事实，不重复创建或假装完整成功。UI展示、目录版本及观测不替代必要记录。
+
+## 项目指导、Skill与MEMORY
+
+每个Turn从实际recording的Session身份创建真实`createProjectGuidance`，
+接入已有ContextBuilder；不使用UI当前选择作为授权身份。
+每次按该Session的原root/cwd验证并重建82/84，不捕获另一个Session的位置。
+内建编码指导是required system材料，项目AGENTS、Skill和MEMORY是required的
+低信任user材料；来源、revision和materialId进入ContextReport。预算不足或读取
+失败阻止模型请求，不静默丢弃、摘要截断或把项目文本提升成system权限。
+
+初始只加载当前目录指导及Skill元数据目录。模型可用`project_context`的`inspect`
+检查目标目录规则，`load_skill`读取指定locator的完整SKILL.md，`reference`按需
+读取已加载Skill的相对资源。成功后下一步上下文加载完整正文，不把正文复制到历史；
+每个Turn重建状态，跨Session或恢复不会继承已激活Skill/目录。frontmatter中的
+allowed-tools/model/hooks、伪造role或记忆文本不能扩展工具或权限。
+
+唯一项目记忆位置为`.agents/MEMORY.md`，不是另一个Session存储。`project_memory`
+的`read`默认允许；`replace`和`delete`需要**本次调用**的`--allow-memory-write`，
+并按生产工具的expectedSha256规则防止覆盖陈旧内容。该flag不从文件、环境或历史
+恢复，也不授予编码write/edit/command；`--allow-write`不能替代它。示例：
+
+```sh
+yui agent run --config /absolute/agent.json --allow-memory-write \
+  --input '读取项目记忆，然后以当前指纹保存这次确认过的经验'
+```
+
+这是project_memory的具体action授权，不是文件系统ACL：若另行明确授予普通
+write/edit或可写命令，它们仍具有其既有受控root权限，可能直接修改这个文件。
+外部修改在下一步重新读取；旧指纹拒绝，读写权限与记忆内容不互相授予能力。
+项目读取遵守84的大小、总材料、目录/Skill数量和深度上限；不自动执行Skill脚本，
+也不访问Home或任意项目外资源。显式`--tools`完整替换默认集合；
+即使未选择项目工具，required内建和基线项目指导仍加载，但不能按需激活更多内容。
+
+## 原位置恢复与剩余边界
+
+初始run/start和UI的`/new`都通过唯一ExecutionOwner调用81原子创建，
+同时保存空Session与不可变root/cwd；承认可执行前位置已持久，不存在后补窗口。
+目录、详情、完整load和执行共用同一store，没有sidecar或第二账本。
+`--session ID`可省略root/cwd，按原位置重新验证真实文件系统，再重建82/84；
+位置、标题和历史均不恢复write/command/MEMORY授权、命令规格或凭据。
+
+legacy缺失位置时拒绝自动执行，提示明确选择新会话，不猜补或修改旧位置。
+仍可使用独立目录/历史命令检查旧记录。unknown-effects、interrupted和cleanup-required
+仍拒绝新Turn，查询不能清除这些事实。UI允许同位置的`/use ID`；
+跨位置选择明确拒绝并保留当前选择，须先结束旧活动、关闭进程，再以目标ID显式重开。
+
+创建确认丢失时报告effect:unknown与原尝试Session ID，用同ID的getSessionInfo和load
+进行一次只读对账；即使确认空Session及位置已保存，本次也不执行、重建或换ID。
+按错误指引显式重开同ID；若对账读取失败则保留未知，不把not_found当未提交证明。
+独立Review与最终接受仍由Leader处理；真实模型、硬件掉电、跨OS迁移、
+敌对文件系统和强沙箱不在本地离线证据的保证范围内。
+
+## 可执行离线样例
+
+源码完成本地安装后：
+
+```sh
+node docs/examples/agent-offline.mjs
+```
+
+样例创建本地HTTP服务、一次性目录和dummy凭据，经真实入口完成读取、编辑、
+精确授权本地检查、按需完整Skill、MEMORY默认拒绝与显式写入、回执核对和指定ID
+续聊，随后重开不继承command/write/MEMORY授权，并验证持久分页发现、重复标题ID选择、
+改名和有界历史、失效游标明确刷新；root与cwd不同，新进程从另一个启动目录
+按目录中的确切ID恢复原root/cwd，并取得新命令授权后继续真实读取与检查；
+finally关闭fixture进程/服务并删除自己的目录。
+不使用真实模型、账号或共享资源，不启动控制面。

package/docs/release-workflow.md

@@ -37,15 +37,53 @@ Task's actual authorization. A workflow containing only PR, CI and merge steps
 is a valid delivery plan; its `ReleaseWorkflow` name does not authorize any
 package release, global CLI update or Controller replacement.
 
-When the user explicitly asks to release a new version without naming its
-level, select only minor or patch according to the actual changes and project
-version rules. A major release requires explicit user authorization for major
-or a specific major version. If breaking changes cannot honestly be represented
-by minor/patch, explain the compatibility conflict and wait for the necessary
-explicit user choice: neither silently publish major nor mislabel incompatible
-behavior as compatible. This does not require adding historical compatibility
-mechanisms. Package release versions are distinct from storage migration
-versions; the storage rules below do not authorize a package release.
+When the user explicitly asks to release a new version, select minor for new
+features or incompatible interface/behavior changes, and patch for compatible
+fixes. Incompatibility does not require major or another version-level approval;
+major is used only when explicitly requested by the user.
+
+This is Yui's project-specific numbering convention, not the usual SemVer
+backward-compatibility meaning. A minor release can be incompatible. Users must
+read its compatibility and migration notes before upgrading; release notes must
+identify affected contracts and how to move to the new interfaces, not label
+incompatible behavior as compatible. Do not add historical compatibility mechanisms
+merely to avoid a version decision. Package versions remain distinct from protocol
+and persistent-storage contracts: their compatibility checks and required migrations
+are unchanged, and the storage rules below do not authorize a package release.
+
+### 2.2.0 compatibility and migration notes
+
+This minor release adds the independent `yui agent` entry, explicit model/tool
+configuration, durable local sessions, context compaction and offline evaluation,
+alongside Task handoff/Leader scope fixes and Web layout improvements.
+
+The independent Agent's public `createAgent({ onEvent })` option from 2.1.0 has
+been replaced. Passing `onEvent` in JavaScript no longer invokes the callback;
+the turn may complete with facts retained only in memory. Update callers before
+upgrading—this is an incompatible interface change, despite the minor version.
+
+Use `recorder.record` for required ordered recording; it is awaited and a rejected
+record stops new effects. Use synchronous `observer.observe` for optional display
+or telemetry; its failure is reported in `observerErrors` and does not stop the
+turn. An observer must enqueue asynchronous work itself, not return a Promise.
+For an old awaited persistence callback, the equivalent construction is:
+
+```js
+const agent = createAgent({
+  provider,
+  tools,
+  recorder: { record: persistEvent }, // async (event) => { await durableWrite(event); }
+  observer: { observe: renderEvent }, // optional, synchronous
+});
+```
+
+Inspect `result.recording` for recording evidence and `result.error` for failure.
+Recording errors now use `recording_failed`, not `event_sink_failed`. Do not move
+required persistence into an observer. Existing Tasks and historical reports
+remain readable, but a new Review requires frozen candidate/report evidence;
+missing historical evidence is not reconstructed. Context compaction requires
+an explicit compressor when the budget is exceeded. These notes do not authorize
+global CLI installation, Home migration or Controller restart.
 
 The operations and examples below describe how to execute already-authorized
 effects, not a default sequence to run after completing or merging a Task.

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

@@ -27,12 +27,42 @@ Agent 选择一个预先声明的计划，设施从持久状态驱动该计划
 发布 npm；每项外部效果仍需 Task 的实际授权。仅包含 PR、CI 和合并步骤也是合法的交付
 计划，`ReleaseWorkflow` 这个名称不授予包发布、全局 CLI 更新或 Controller 替换权限。
 
-用户明确要求「发布新版本」但没有指定级别时，根据实际变更和项目版本规则，仅选择
-minor（中版本）或 patch（小版本）。major（大版本）必须得到用户对大版本或具体 major
-版本号的明确授权。如果破坏性变更无法诚实地用 minor/patch 表达，说明兼容性冲突，
-等待必要的明确用户选择：既不能静默发布 major，也不能把不兼容行为冒称为兼容。
-这不要求为了回避选择而新增历史兼容机制。包发布版本与存储迁移版本是不同契约，
-下文的存储规则不授予包发布权限。
+用户明确要求「发布新版本」时，新功能或接口／行为不兼容变更使用 minor（中版本），
+纯兼容修复可使用 patch（小版本）。不兼容本身不要求 major 或再次确认版本级别；
+只有用户明确要求 major（大版本）时才发布 major。
+
+这是 Yui 项目专属的编号约定，不是通常 SemVer 的向后兼容承诺：minor 也可能不兼容。
+用户升级前应阅读兼容性及迁移说明；发布说明必须列明受影响的契约与新接口用法，
+不能将不兼容冒称为兼容，也不为回避版本选择新增历史兼容机制。包版本与协议、
+持久存储契约仍然独立：兼容性检查和必要迁移要求不变，下文存储规则不授予发版权限。
+
+### 2.2.0 兼容性及迁移说明
+
+本 minor 增加独立 `yui agent` 入口、显式模型／工具配置、持久本地会话、上下文压缩、
+离线评估，以及 Task 交接／Leader 写域修复和 Web 布局改善。
+
+2.1.0 独立 Agent 的公开 `createAgent({ onEvent })` 已被替换。
+JavaScript 调用方继续传入 `onEvent` 时不会再触发该回调，Turn 仍可能完成，
+但事实仅保留在内存中。升级前必须调整调用方；虽然编号为 minor，这仍是不兼容变化。
+
+必要的有序记录使用 `recorder.record`：内核等待记录确认，拒绝会停止新增效果。
+可选展示／遥测使用同步 `observer.observe`：失败写入 `observerErrors`，不停止 Turn。
+Observer 必须自行排队异步工作，不能返回 Promise。旧异步持久化回调应改为：
+
+```js
+const agent = createAgent({
+  provider,
+  tools,
+  recorder: { record: persistEvent }, // async (event) => { await durableWrite(event); }
+  observer: { observe: renderEvent }, // 可选，同步
+});
+```
+
+检查 `result.recording` 的记录证据及 `result.error`；记录失败代码由
+`event_sink_failed` 改为 `recording_failed`。不要把必要持久化放入 Observer。
+已有 Task 和历史报告仍可读取，但新 Review 必须有冻结 Candidate／原报告证据，
+缺少的历史证据不会自动补造。上下文超预算时，压缩需要显式 compressor。
+上述说明不授予全局 CLI 安装、Home 迁移或 Controller 重启权限。
 
 下文操作及示例说明如何执行已经获授权的效果，不是 Task 完成或合并后默认运行的步骤。
 

package/docs/roles-and-configuration.md

@@ -62,6 +62,38 @@ different contracts. Provider bypass does not grant writes to another Project.
 Managed workspace owner, exact Assignment and resource grants enforce Yui
 operations; broad native permissions are not an OS sandbox.
 
+A write-intent delivery Leader launched in its own Task-owned main workspace
+captures that workspace's bound writable Projects without needing an open
+WorkItem. Accepted results do not remove this direct-delivery scope. An explicit
+Assignment (including an empty write scope) remains authoritative for assigned
+execution. Planning, read-intent execution and global Roles do not acquire this
+Task-main scope; Reviewer writes remain confined to their exact Review workspace.
+Project effects recheck the current Session's frozen scope as well as Task
+lifecycle and workspace ownership. The scope does not authorize stable Project
+checkouts, other Tasks, private Worker/Review workspaces or Home mutations.
+
+Managed Leader Integration targets must name the Task-main branch, and that
+branch must actually be checked out in the captured Task-main directory.
+Admission, checks and target CAS revalidate this boundary; `--target` does not
+grant access to another worktree in the same repository.
+
+`integration abort` may confirm an already-applied CAS as committed without
+granting new Project writes. It still verifies current delivery identity,
+captured Task-main ownership, actual checkout, candidate and check/Job evidence.
+An unadvanced CAS remains a Project effect and requires the full write scope.
+
+An existing empty-scope Session stays empty after a runtime update, including
+ordinary failed-Run retries. Resume cannot change captured Profile access or
+Project write scope. Inspect
+`yui task role session inspect <task> leader --json` (`session.effective`), then
+request `yui task role session new <task> leader --reason "<adopt new scope>"`.
+When replacing your own Session, end the turn. After Yui confirms cleanup and
+launches the successor, inspect its captured `executionAuthority`,
+`profileAccess`, `writeProjectIds` and workspace before editing. A replacement
+request is not proof of adoption. Exact Run Context and launch environment
+derive their write scope from the same frozen effective snapshot; models,
+effort, accepted Candidates and their acceptance history are unchanged.
+
 Yui supplies its generic Role Skills and Context pointers. Project Skills remain
 ordinary Project files discovered natively by the Agent. Project Knowledge is
 maintained under `YUI_HOME`; copying repository material into a prompt does not

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

@@ -52,6 +52,32 @@ Provider 权限策略、Profile 访问意图和 Project 写范围是不同的合
 不授予对另一个 Project 的写入。受管工作区 owner、精确 Assignment 和资源 grant
 落实 Yui 操作；宽泛的原生权限不是 OS 沙箱。
 
+以 write 意图在自己 Task-owned main 工作区启动的 delivery Leader，从该工作区
+捕获已绑定 Project 的写域，不要求存在 open WorkItem；已接受结果也不会移除这个
+直接交付写域。显式 Assignment（包括空写域）仍决定受派发执行的范围。
+Planning、read 意图执行和全局 Role 不获得这个 Task-main 写域；Reviewer 仍只可写
+精确的 Review 工作区。Project 实际操作重新校验当前 Session 的冻结写域、Task
+生命周期和工作区 owner；它不授权稳定 Project checkout、其他 Task、私有
+Worker/Review 工作区或 Home 修改。
+
+受管 Leader 的 Integration 目标必须是 Task-main 分支，且该分支实际 checkout
+在捕获的 Task-main 目录。入场、检查及目标 CAS 都重新校验此边界；
+`--target` 不授予对同仓库另一工作区的写入。
+
+`integration abort` 可以把已发生的 CAS 确认为 committed，而不授予新项目写域。
+结算仍校验当前 delivery 身份、捕获的 Task-main 归属、实际 checkout、
+候选及检查/Job 证据。未执行的 CAS 仍是项目写操作，必须具备完整写域。
+
+运行时更新后，旧的空写域 Session 仍保持空域，包括失败 Run 的普通 retry。
+Resume 不改变捕获的 Profile 访问意图或项目写域。先用
+`yui task role session inspect <task> leader --json` 读取 `session.effective`，
+再通过 `yui task role session new <task> leader --reason "<采用新写域>"`
+请求正式替换。替换自己时应结束当前 turn。Yui 确认清理并启动 successor 后，
+读回其 `executionAuthority`、`profileAccess`、`writeProjectIds` 和 workspace，
+确认后再编辑；替换请求本身不证明采用成功。精确 Run Context 与启动环境从同一
+冻结 effective snapshot 取得写域；模型、effort、accepted Candidate 和原验收
+历史保持不变。
+
 Yui 提供其通用 Role Skill 和 Context 指针。Project Skill 仍是由 Agent 原生发现的
 普通 Project 文件。Project Knowledge 维护在 `YUI_HOME` 下；把仓库材料复制进 prompt
 并不使其成为权威 Knowledge。

package/package.json

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

package/skills/yui-leader/SKILL.md

@@ -19,6 +19,15 @@ not copied reports. Follow Runtime's `nextCursor` and `contentPage` rules:
 read the full relevant window and originals before disposition, without
 unconditionally walking unrelated history.
 
+Before WorkItem dispatch, put the complete bounded requirements in the WorkItem
+or explicitly select up to 16 relevant readable materials with repeated
+`--context-ref <store/refId@digest>` on `task work dispatch`. Obtain exact IDs and
+digests from current Task context list/inspect. Core freezes these selected
+values after the existing caller-scope checks; mentioning a record in `--input`
+does not select it or grant access. Missing, forbidden or changed references
+refuse dispatch before Provider startup: correct the selection or make the
+WorkItem self-contained, never ask the recipient to bypass expansion rejection.
+
 ## Select the applicable stage
 
 Use current lifecycle, latest intent and the Session's actual planning/delivery

package/skills/yui-reviewer/SKILL.md

@@ -28,6 +28,11 @@ WorkItem Develop workspace, and never become a ChangeSet source.
 
 For a dispatched Review, the AgentRun Context Pack identifies the ReviewRound,
 frozen Project commits, and assigned workspace. Inspect those exact commits.
+For a Run-backed Candidate, read its frozen `source-run` reference whose
+`evidenceOf` names that Candidate, including every content page of the original
+report. A summary or a newer Run is not a replacement. Missing historical
+evidence is a bounded infrastructure diagnosis, not permission to read outside
+the inventory or require the Leader to manually copy a report.
 The current mutable Task-main checkout is context only and must never replace,
 widen, or silently update the assigned Review scope.
 

package/skills/yui-runtime/SKILL.md

@@ -178,6 +178,13 @@ public view. This offline view is only guidance, not an authenticated permission
 or a way to switch Roles. An incomplete or stale managed identity must not be
 cleared to obtain public execution authority.
 
+For Codex, the native `CODEX_THREAD_ID` takes precedence over the transport's
+`YUI_NATIVE_SESSION_ID`; a newly created thread can legitimately lack the latter.
+Other adapters do not borrow Codex identity for offline discovery. A missing
+transport variable or hidden help entry alone does not prove Session failure.
+Discovery does not establish that a Session is current: actual execution still
+revalidates Session, Task/Assignment, workspace, resource and Grant boundaries.
+
 When capability discovery appears in that view, use `capability search` for
 templates and `capability describe <name> --task
 <task-id> --input '<json>'` for supported exact authorization assessments.