@zq-silk/yui 0.15.11 → 0.16.0

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

@@ -84,6 +84,33 @@ owner Run。当 Role 忙碌时，保存会返回而不打断它。一旦它可
 显式 handoff 只针对同一工作已派发的后继。复制的 Producer/综合血缘不会被一条消息
 静默改写。
 
+被拒绝的 Leader 通知保留原始输入和失败原因。确定性的启动错误不再自动重试，
+只有明确的运行时资源争用可以延后再试。新消息和 Controller 重启不会重放被拒绝
+的认领。修正原因后，显式重试对应的 wake：
+
+```sh
+yui task wake show <task> <wake>
+yui task wake retry <task> <wake> --reason "<已修正的原因>"
+```
+
+retry 把被拒绝批次及后续排队输入交回现有 mailbox，不把旧 wake 改成已接受，
+也不替换 Session；当前运行权限和就绪检查仍然生效。模型／effort 校验拒绝会显示原生
+报告的模型选项，并提供查询完整当前目录的命令。
+
+没有 Run 的启动失败与原生 Provider 拒绝都保留规范的 `runtime.agent-error` 事实。
+通知投递引用该原始错误，而不复制第二份原因。`task event show` 的人类和 JSON 输出
+都提供有作用域的能力查询入口，`wake show` 也链接同一事实。无法接收的 Leader 将
+错误通过既有 Operator 通道通知一次；Worker／Reviewer 仍通知 Leader。不启动新的
+恢复 Agent，也不为了记录错误制造 Run 或 Session。
+
+存储 `35→36` 迁移保留历史错误原始 payload，并将当时未记录的启动配置标为不可用，
+不会从当前 Role 猜测过去的模型、账户或 settings 选择。
+
+存储 `36→37` 将该上下文收窄为原生元数据查询选项和请求的模型／effort。旧完整快照
+留在迁移审计中，不由运行时双读。查看模型选项不再校验 Task 权限、Review 状态、
+工作区条目或当前 Session 引导协议。三类错误入口保留各自的原生身份检查与分类，
+错误创建、去重统一一个写入入口，上级通知统一使用事件路由边界。
+
 未知的 Leader 通知保留其唤醒和输入窗口：
 
 ```sh
@@ -94,6 +121,70 @@ yui task wake resolve <task> <wake> --reason <quiescence-evidence>
 resolve 在原生效果围栏清除后释放该认领。它既不重放通知，也不编造接受或完成。独立的
 Role 工作和合法的本地事实不是一把 Task 范围的恢复锁。
 
+wake 状态记录通知投递，不记录 Message 的实施结果。普通 Leader 通知的 `consumed`
+表示原生接受；原生 Turn 完成与 Task 交付应分别依据运行证据和持久结果判断。
+被拒绝的 wake 保持 `dispatched` 并保留 claim，直到显式重试或 Session 替换；
+已显式释放的历史 wake 可以保持 `dispatched` 而不占用 claim。
+接受状态未知的通知不能用 `wake retry` 重放。Session 替换把待投递输入
+保留给新 wake 与当前 Context，不会追溯把旧 wake 标成已接受；旧回执也不能结算
+新批次。Session 清理期间，新输入保持排队。检查时应结合 wake、
+`notification.delivery` 事件、当前 mailbox 与 Session，不应要求每个历史 wake
+都对应一条最终回复。
+
+现行 wake 只表示通知，Run 完成不能消费 wake；首次通知窗口从 Task 创建时间开始。
+退役的 Run-linked wake 通过 Task 事件保留原 ID 和完整原文，不作为第二种活动 wake 格式。
+
+## 输入时机：queue、steer 与 interrupt
+
+提交意图（`record / discuss / develop`）决定需求如何路由。输入时机决定一条已经
+获授权的输入何时到达 Role；它不激活 Task、不扩大 Assignment，也不提升 planning
+权限。仅保存输入使用 `message send --intent record`，`--wake-policy` 已移除。
+未绑定请求身份的 Draft Message 仍可编辑，保留原提交意图。编辑 `record` 或
+`develop` 不会启动规划、创建或重试激活；编辑 `discuss` 复用讨论提交的激活／规划
+路由，因此已有 pending 或 failed 激活时，编辑后的讨论仍等待激活处理。
+
+带 submission key、queue/steer 请求或 interrupt-then 交接的 Message 正文不可变；
+需要改内容时，应使用新的 request ID 提交新消息。这保留原请求的判重依据和回执，
+不新增第二套输入存储。更新为相同正文是无操作：不写事件、不改队列、不通知
+Controller。现行 user/operator 消息必须存有意图；改变意图同样需要显式提交新输入。
+[经认证的 Web 控制](architecture/capabilities-and-resources.zh-CN.md#cli-与-web)
+与 CLI 使用同样的三种操作。
+
+| 动作 | 效果 | 不证明什么 |
+| --- | --- | --- |
+| `queue` | 保存 Message，等待收件人的下一个合法机会，按 request ID 幂等 | 读取 Context 或接受投递不等于实施 |
+| `steer` | 保存 Message，并尝试原生 steer 精确的当前 Turn | 不受支持、目标陈旧或未确认的 steer 不等于排队延续 |
+| `interrupt` | 记录控制请求，请 Provider 取消精确的当前 Turn | 停止请求不等于终态，也不证明后台资源已停止 |
+
+选择实时目标前先检查 Session：
+
+```sh
+yui task role session inspect <task> <role>
+yui task message queue <task> "<continuation>" --request-id <id>
+yui task message steer <task> "<correction>" --request-id <id> --to leader --expected-target <turn>
+yui task role interrupt <task> <role> --expected-target <turn> --request-id <id> [--then-message <task/message>]
+```
+
+普通 Leader `queue` 输入省略 `--to`。显式 `--to <role>`（包括 `leader`）指向既有
+Assignment，必须带 `--work-item` 或 `--review-round`；Message 不能创建 Assignment。
+`steer` 仍需要显式 Role 与精确实时目标。同一个 request ID 若换正文或目标会产生冲突。
+`steer` 与 `interrupt` 不会静默改目标、
+替换 Session、杀进程或回退到另一动作。没有活动受管 Turn 时返回 `NO_ACTIVE_TURN`；
+陈旧目标与不受支持的控制也保持为显式结果。
+
+裸 interrupt 不创建 Message。可选的 `--then-message` 引用一条已保存且符合交接条件
+的输入，只在精确终态之后、原 Session/writer 边界内保留下一次机会。它不是第四种动作，
+也不能用来重放已接受、待确认或未知的 steer。明确证明未投递时，若用户意图允许，
+可以显式选择新的控制；不确定性不允许重放。
+
+Global Role 使用同样的三种动作和自己的 owner、Session，不虚构 Task 或 Run。
+本地用户 Web Surface 通过共享 Global Role 处理器暴露这些动作。公开 CLI 提供
+`yui role message queue|steer <role> <text>` 和 `yui role interrupt <role>`。
+queue/steer 要求 `--request-id`，steer/interrupt 要求 `--expected-target`。
+这些命令保留调用者现有 Session 权限，不虚构 Task/Run 或借用浏览器用户权限。
+配置仍使用 `config role`，生命周期使用 `session`。新的受控 Global Session 使用 Host console。活动的非受管 Session
+不会被静默采用，需要先执行显式的 Session 生命周期操作。
+
 ## 精确结果
 
 原生终态只结算相匹配的那次执行。已知的原生 Turn ID 必须匹配；串行流可以使用已证明的
@@ -118,8 +209,8 @@ Candidate 和 ReviewRound 保留来源；Core 不从散文中推导语义接受
 仍是通知。Operator 提交和直接的 Task 消息都能到达那个 Session。Draft 计划/WorkItem
 编辑保留执行历史；外部编辑通知 Leader，而它自己的规划编辑不创建自唤醒。
 
-新的 Draft Role 使用位于 `<YUI_HOME>.task-runtimes/planning` 下、专属于该 Task 的规划
-目录，在控制 Home 和交付树之外。一个 planning Run 可以用 `task activation request`
+新的 Draft Role 使用位于 `<YUI_HOME>/runtime/task-runtimes/planning` 下、专属于该 Task 的规划
+目录，与持久控制数据和交付树分开。一个 planning Run 可以用 `task activation request`
 持久化意图并立即返回一个 `afterPlanningRun` 引用。它的终态把该请求释放给 Controller
 准入；被取消的意图不会复活。Leader 也可以在普通讨论中请求激活而无需 AgentRun：一旦
 原生输入结算，Controller 就采用其持久意图。不需要合成 Run 或额外的用户“continue”。
@@ -128,6 +219,9 @@ Candidate 和 ReviewRound 保留来源；Core 不从散文中推导语义接受
 获得受管 worktree。`scratch` 选择一个 Task 拥有的目录。`local` 需要一个已登记的 local
 Resource 及其 grant；Project ID 不是 local Resource ID。
 
+`task activate` 是对已有请求的前台采用，不是创建激活意图的另一条路径。
+没有请求的 Draft 会在资源准备前被拒绝；命令不代填环境计划或 request ID。
+
 资源准备先于对 Task 状态和工作区所有权的原子采用。一次失败的采用记录一个失败请求，
 并用持久事实通知 Leader；在失败未变时它不反复准备资源。Leader 选择显式重试或修正后的
 请求。成功激活同样为 Leader 留下一条交付通知。激活绝不把活动 Session 变更为交付权限。

package/docs/observability/README.md

@@ -81,3 +81,65 @@ raw Provider history merely to explain a status.
 Start with exact read-only records. Process changes, cancellation, grant updates
 and resource cleanup require the relevant explicit action and scope. A generic
 diagnostic request does not authorize live-model, shared or production tests.
+
+## Task usage and time
+
+Task overview, Web Task/WorkItem cards and `execution audit` use the same pure
+projection of authorized Task events. Reading never samples a Provider or opens
+raw transcripts. There is no new metric store, migration, price table or budget
+policy. Existing history remains readable.
+
+Each metric has `value`, `status` (`known`, `partial`, `unknown`) and `reasons`.
+Unknown is `null`, not zero. A known zero requires actual numeric evidence.
+Partial is an observed subtotal, not a complete bill or guaranteed monotonic
+lower bound. Coverage names the observed Session identities, source/semantics
+and evidence cutoff; it is not a percentage of an unknowable Provider total.
+The declared basis is Task-fenced, observed sources only.
+JSON consumers read `cost.tokens.value` and `cost.toolCalls.value` with their
+status/reasons, replacing the numeric placeholders and observable flags.
+`elapsedSeconds` and `executionSeconds` replace the misleading Group-sum
+`wallClockSeconds`; this changes a read projection, not persistent storage.
+
+- Request usage reuses the Session reducer: stable request identity, latest
+  received revision, input plus output, no extra addition of cache/reasoning
+  subsets. Missing boundaries, mixed semantics and cumulative rollback are not
+  guessed. Remaining context is capacity, never consumption.
+- Replaced Sessions remain in the lifetime view. A nonzero first cumulative
+  snapshot is an excluded baseline: it may predate the Task. Later comparable
+  increments are partial; one nonzero snapshot alone yields unknown Task usage.
+  A zero baseline supports the subsequent counter. JSON also exposes raw
+  Session counters separately; they are not additional Task consumption.
+- Direct Leader chat can contribute without a Run or WorkItem. WorkItems
+  receive only request usage whose revisions share one exact, matching Run
+  binding. Cumulative counters are not apportioned. Raw whole-Session totals
+  are not exposed as WorkItem usage. Task totals need not equal WorkItem sums.
+- Child counters are excluded because the current contract cannot prove they
+  are additional to the parent. Child evidence marks coverage partial. Conflicting
+  Role ownership of one native counter is unknown, not two independent totals.
+- Tool counts deduplicate retained exact native Session/Turn/operation identities,
+  including failures. Operation history is compacted, so this is always partial
+  when evidence exists and unknown otherwise. Absence never proves zero tools.
+
+**Task elapsed** runs from Task creation (including planning and waiting) to its
+recorded completion, retirement or cancellation, or to the read time if active.
+An archived Task keeps its original endpoint; missing terminal evidence is
+unknown. Group count is irrelevant.
+
+**Observed native execution sum** merges overlapping complete Turn intervals
+within one native resource and adds independent parallel resources. Two
+independent ten-second intervals can total twenty seconds during ten seconds of
+elapsed time. It is not CPU/GPU time. Since Turn history is compacted, this is
+partial; missing start/end and live Turns are excluded, never extended indefinitely.
+Subsecond precision is retained. WorkItem cards do not substitute Group duration
+for either measure.
+
+The audit `usage` section is explicitly **Task lifetime** even when `--since` or
+`--until` filters other sections. It does not offer window consumption; filtering
+cumulative snapshots first would mislabel historical usage as window usage.
+Its existing AgentRun-duration section remains a separately labeled Run metric.
+
+Deterministic fixtures cover the shared reducer and CLI/Web/audit semantics.
+They do not establish live Provider completeness. Built-in normalization supports
+Codex cumulative and Claude request observations when supplied; this delivery
+does not collect real-model billing evidence or assert Provider behavior was
+live-tested.

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

@@ -69,3 +69,50 @@ Telemetry 和缓存是诊断材料，不是 Task 真相，也不是 transcript
 
 从精确的只读记录开始。进程变更、取消、grant 更新和资源清理都需要相应的显式动作
 与范围。一个笼统的诊断请求不授权真实模型、共享或生产环境的测试。
+
+## Task 用量与耗时
+
+Task overview、Web Task/WorkItem 卡片和 `execution audit` 共用授权 Task
+事件的纯读投影。读取不采样 Provider、不打开原始 transcript；没有新增指标存储、
+迁移、价格表或预算策略，既有历史仍可读。
+
+每项指标带 `value`、`status`（`known`、`partial`、`unknown`）和 `reasons`。
+未知为 `null`，不是零；真实零必须有数值证据。部分值是已观测小计，不是完整账单，
+也不保证是单调增长的下界。覆盖说明包括已观测 Session 身份、来源/计数语义和
+证据截止点，不对不可知的 Provider 总量伪造覆盖百分比。口径是 Task 围栏内的
+已观测来源。
+JSON 使用方改读 `cost.tokens.value`、`cost.toolCalls.value` 及其状态/原因，
+不再读取数字占位和 observable 标志。`elapsedSeconds`、`executionSeconds`
+替代含义错误的 Group 求和 `wallClockSeconds`；这是读投影变更，不是持久存储变更。
+
+- 请求用量复用 Session reducer：按稳定请求身份取最后收到的修订，累加输入与
+  输出，缓存/推理子项不重复增加。缺失边界、混合语义、累计回退不猜测；剩余
+  上下文是容量，不是消费。
+- Session 替换不抹去历史。首次非零累计快照可能早于 Task，因此作为排除基线；
+  后续可比增量为部分值，仅一个非零快照时 Task 用量未知。零基线可支持后续
+  累计值。JSON 单独暴露原始 Session 计数，它不是额外的 Task 消费。
+- Leader 直聊不需要伪造 Run/WorkItem。WorkItem 仅接收各次修订均绑定同一
+  精确、匹配 Run 的请求用量；累计值不摊派，整个 Session 的原始计数不冒充
+  WorkItem 用量。Task 总量不必等于 WorkItem 小计之和。
+- 当前合同无法证明子执行计数在父统计之外，因此排除子计数并将覆盖标为部分。
+  多个 Role 对同一原生计数器的归属冲突为未知，不当成两份独立总量。
+- 工具次数按保留的精确原生 Session/Turn/operation 身份去重，失败调用也计一次。
+  工具历史已压缩，有证据时只能是部分次数；无证据为未知，不能推出零调用。
+
+**任务历时**从 Task 创建（含规划和等待）到记录的完成、退役或取消时间；
+活动 Task 截止本次读取时间。归档保留原终点，终态证据缺失则未知，与 Group
+数量无关。
+
+**已观测原生执行累计**合并同一原生资源上起止完整、彼此重叠的 Turn 区间，
+再相加独立并行资源。两个独立执行各十秒，可以在十秒自然时间内累计二十秒。
+它不是 CPU/GPU 时间。由于 Turn 历史已压缩，该指标为部分值；缺少起止证据和
+运行中的 Turn 不计入，不无限延长。保留不足一秒的精度，WorkItem 卡片不再用
+Group 时长替代上述含义。
+
+即使 `--since`、`--until` 过滤其他审计部分，`usage` 部分仍明确为 **Task 全生命周期**。
+首版不提供窗口消费，不能先过滤累计快照，再把历史消费称为窗口用量。
+既有 AgentRun 时长部分保留为单独标明的 Run 指标。
+
+确定性 fixture 验证共享 reducer 和 CLI/Web/audit 语义，不证明真实 Provider 的
+覆盖完整性。内置归一化支持来源所提供的 Codex 累计观察和 Claude 请求观察；
+本次交付不采集真实模型账单证据，也不声称已实测真实 Provider 行为。

package/docs/plugin-sdk.md

@@ -374,8 +374,10 @@ Publication rechecks the complete contribution, dependencies and permissions
 again. A failure does not change the existing directory; a competing
 activate/disable makes a late candidate refuse to publish. After a successful
 publication, the old generation only serves existing references and is disposed
-once drained; a cleanup failure keeps a diagnostic Artifact and neither rolls
-back the new Provider nor pretends the current instance is still unpublished.
+once drained. A cleanup failure is retained on that plugin's diagnostic channel
+with the old generation identity, even if another replacement has already
+published. It is not a Task Artifact, does not roll back the new Provider, and
+does not pretend the current instance is still unpublished.
 
 ## Storage and other ingress
 

package/docs/project-refresh.md

@@ -0,0 +1,77 @@
+<p align="right"><strong>English</strong> | <a href="./project-refresh.zh-CN.md">简体中文</a></p>
+
+# Project refresh
+
+`yui project refresh <project>` refreshes the canonical Project checkout from
+the Project's configured remote and stable branch. Stable and development
+branches must match. The per-Project maintenance fence covers the operation;
+Task workspaces and their recorded bases are not refreshed by this command.
+
+## Two separate facts
+
+The checkout HEAD and a local remote-tracking ref are distinct observations.
+Refresh fetches the exact branch into a unique temporary ref, compares its
+commit with the remote's advertised commit, and permits only a clean
+fast-forward from the original HEAD on the stable branch. Configured `HEAD`
+is resolved through the remote's symbolic HEAD, never a guessed default branch.
+
+When exactly one existing Git remote and fetch mapping manages a safe tracking
+destination, refresh also updates that destination to the verified commit.
+This runs even when HEAD is already current, repairing stale tracking refs
+that would otherwise make ordinary Git show a false `ahead` count.
+
+The mapping uses Git's effective fetch URL, including `insteadOf` resolution,
+and full-ref exact or one-star fetch refspecs with negative exclusions. It
+does not assume `origin` or `refs/remotes/<remote>/<branch>`. A configured
+destination under `refs/remotes/` can be created if absent. Multiple matching
+remotes/URLs, multiple destinations, another source managing the same target,
+unsupported refspecs, local-branch/tag destinations and symbolic destinations
+are explicitly unmanaged. Push URLs never establish fetch identity.
+
+Only the unique mapped ref can change. Fetch does not opportunistically update
+other tracking refs, fetch/prune tags, recurse into submodules, or write
+`FETCH_HEAD`. Remote/upstream configuration is never rewritten. Read-only
+tracking observations use the same mapping proof and return no tracking match
+when it is not uniquely established.
+
+## Results and concurrent changes
+
+- `fromCommit`, `toCommit` and `changed` describe HEAD; `changed: false` does
+  not imply that no tracking repair occurred.
+- `tracking.status` is `updated` or `current` for a synchronized target,
+  with its exact ref and old/new object IDs.
+- `tracking.status: unmanaged` includes a reason. HEAD can still refresh
+  successfully, but this is not a claim of tracking consistency.
+- Once work has started, a failed refresh uses the existing nonzero
+  `RUNTIME_ERROR` channel. JSON `details.refresh` retains observed HEAD,
+  the verified commit when available, and the tracking result (`failed` for
+  a managed target). Missing/unreadable observations are nullable. Text
+  errors also state the actual partial result. Preconditions can fail
+  before any mutation without a partial-result record.
+
+Refresh rechecks the mapping, cleanliness, branch and HEAD around the update.
+A Git ref transaction verifies the stable branch and compares the tracking
+target against its captured old value (or absence) before writing it. A local
+ref race, changed mapping, divergent checkout or fetched/advertised mismatch
+fails visibly. After a fast-forward, a failed tracking update leaves HEAD at
+its actual new commit; it never rolls back or overwrites a competing ref.
+There is no automatic retry, replay or background synchronizer.
+
+Temporary-ref cleanup compares the known fetched object before deletion.
+An unsuccessful cleanup reports the retained ref; an interrupted/failed fetch
+can report the exact temporary namespace to inspect. These are Git diagnostics,
+not durable Task progress or a new recovery protocol.
+
+The maintenance fence serializes Yui maintenance, not arbitrary external Git
+commands or user edits. Checks and Git locks bound the observed operation;
+they do not promise that local or remote state cannot change after observation.
+Ordinary `git status` loses the false `ahead` count only when the current
+branch's upstream is the tracking ref refreshed here. A different/missing
+upstream is left untouched and carries no such promise.
+
+## Scope of adoption
+
+This operation adds no persistent Yui schema or migration. Installing code
+that implements it does not itself refresh a real Project. A normal authorized
+refresh applies the behavior; Task completion, integration, publication and
+archive remain separate operations.

package/docs/project-refresh.zh-CN.md

@@ -0,0 +1,59 @@
+<p align="right"><a href="./project-refresh.md">English</a> | <strong>简体中文</strong></p>
+
+# Project refresh
+
+`yui project refresh <project>` 按 Project 配置的 remote 和 stable branch 刷新
+规范 checkout。stable 与 development branch 必须一致。操作全程持有 per-Project
+maintenance fence；不会刷新 Task 工作区或改写其记录的基线。
+
+## 两个独立事实
+
+checkout HEAD 与本地 remote-tracking ref 是不同的观察。refresh 将精确分支获取到
+唯一临时 ref，比较获取到的提交与远端 advertised commit，仅允许从原 HEAD 在干净的
+稳定分支上 fast-forward。配置为 `HEAD` 时解析远端 symbolic HEAD，不猜默认分支。
+
+当且仅当一个既有 Git remote 及其 fetch 映射管理安全的 tracking 目标时，refresh
+同时将该目标更新到已验证的提交。HEAD 已最新也执行这一检查，修复会让普通 Git
+错误显示 `ahead` 的陈旧 tracking ref。
+
+映射使用 Git 生效的 fetch URL（包括 `insteadOf` 解析），支持完整 ref 名称的
+精确或单星号 fetch refspec，并处理负向排除。不假定 `origin` 或
+`refs/remotes/<remote>/<branch>`。已配置的 `refs/remotes/` 目标缺失时可以创建。
+多个匹配 remote/URL、多个目标、其他来源也管理同一目标、不支持的 refspec、
+本地分支/标签目标和符号引用目标，均明确标为未管理。push URL 不证明 fetch 身份。
+
+只允许修改唯一映射目标。fetch 不顺带更新其他 tracking refs、不获取/修剪标签、
+不递归获取 submodule、不写入 `FETCH_HEAD`，也不改 remote/upstream 配置。
+只读 tracking 观察复用相同映射证明；无法唯一确证时不返回 tracking 匹配。
+
+## 结果与竞争
+
+- `fromCommit`、`toCommit`、`changed` 描述 HEAD；`changed: false` 不代表没有
+  发生 tracking 修复。
+- `tracking.status` 为 `updated` 或 `current` 时，目标已同步，并包含精确 ref
+  和新旧对象 ID。
+- `tracking.status: unmanaged` 带有原因。HEAD 仍可刷新成功，但不声称 tracking
+  一致。
+- 操作开始后失败，沿用非零的 `RUNTIME_ERROR` 通道。JSON 的 `details.refresh`
+  保留实际观察到的 HEAD、可用时的已验证提交和 tracking 结果（受管目标为
+  `failed`）。缺失或不可读的观察可为 null。文本错误也说明实际部分结果。
+  变更前的前置条件失败可以不带部分结果。
+
+refresh 在更新前后复查映射、干净状态、分支与 HEAD。Git ref 事务同时验证稳定分支，
+并以捕获的旧值（或不存在）比较后写入 tracking 目标。本地 ref 竞争、映射变化、
+checkout 分歧或 fetched/advertised 不一致都会显式失败。ff 之后 tracking 更新失败，
+HEAD 保留实际的新提交；不会回滚或覆盖竞争方的 ref。不自动重试、重放，也没有后台
+同步器。
+
+清理临时 ref 时比较已知 fetched 对象后才删除。清理失败报告保留的 ref；获取中断或
+失败可报告供检查的精确临时命名空间。这些是 Git 诊断，不是持久 Task 进度或新恢复协议。
+
+maintenance fence 串行化 Yui 维护，不锁住任意外部 Git 命令或用户编辑。检查和 Git
+锁约束本次观察，不承诺观察之后本地或远端不再变化。只有当前分支 upstream 指向此次
+刷新的 tracking ref，普通 `git status` 才会消除相应虚假 `ahead`。不同或缺失的
+upstream 保持原样，不作这一承诺。
+
+## 采用边界
+
+本操作不新增 Yui 持久 schema 或迁移。安装实现代码不等于刷新真实 Project；
+正常获授权的 refresh 才应用此行为。Task 完成、集成、发布和归档仍是独立操作。

package/docs/provider-retry.md

@@ -0,0 +1,70 @@
+# Bounded Provider recovery
+
+Yui can continue an owned input after a positively identified transient Provider
+failure without discarding its Session or local work. The Driver supplies failure
+and native-state evidence; the Controller schedules and atomically admits the
+next input. Agents still own semantic recovery and acceptance.
+
+- At most five automatic attempts after the initial failure, within ten minutes.
+- Exponential windows start at five seconds and cap at sixty seconds, with
+  50–100% jitter. A trusted Retry-After is a minimum, with positive jitter.
+  A wait beyond the remaining deadline ends automatic recovery.
+- Busy/admission waiting does not consume a model attempt. Acceptance, heartbeat
+  and partial output do not reset the streak. Only the matching successful
+  native terminal ends the chain; audit history remains.
+- A rejected input retains its original durable reference. An accepted failed
+  Turn gets a new Turn in the same Session with a system recovery instruction:
+  inspect existing work and receipts and continue only unfinished actions.
+- Unknown acceptance is never replayed. Existing exact-identity reconciliation
+  may supply the missing outcome. Restarting the Controller does not reset the
+  counter, deadline, pending input or writer fence.
+- An explicit manual retry of the same Run retains its recovery lineage,
+  automatic count and original deadline. It is not charged as an automatic
+  attempt, but a further failure cannot replenish automatic allowance.
+
+The records live on the existing Provider binding, with indexed pending-record
+reads and the existing Controller deadline timer. There is no retry Task status,
+second queue, automatic Session replacement, account-wide circuit breaker or
+model switch. The original failed AgentRun stays failed; ordinary Run/Review
+retry primitives own its successor and keep the original ReviewRound.
+
+## Inspect and control
+
+Task Sessions:
+
+```sh
+yui task role session retry <task> <role> show
+yui task role session retry <task> <role> cancel
+yui task role session retry <task> <role> disable
+yui task role session retry <task> <role> enable
+```
+
+Global Sessions use `yui session retry <role> show|cancel|disable|enable`.
+This narrow existing Session surface does not register the unrelated
+top-level Global `role` command family.
+
+The same projection appears in Context, Session inspection and the Web role
+panel. `cancel` withdraws this recovery chain; `disable` also disables future
+chains on the current Provider binding. Neither interrupts an admitted Turn.
+`enable` does not replay historical failures. Existing Task/Role authority applies.
+
+## Supported boundary and adoption
+
+Current controlled Codex Hosts advertise exact recovery support. The native
+preflight checks the latest failed Turn identity for accepted-input recovery
+and a complete empty background-terminal page; ordinary `systemError` admission
+remains closed. Missing protocol methods, a changed/active Turn, unresolved
+background execution or a changed Session/configuration require inspection,
+not automatic cleanup. Native chats without an owned input reference, old Hosts,
+and Adapters without this proof capability are not automatically replayed.
+Claude/ACP retain their normal error and explicit recovery behavior.
+
+Storage transition 26→27 adds optional recovery/input facts and indexes without
+scanning or scheduling old failures. Adoption requires the normal explicitly
+authorized release/upgrade and compatible Host lifecycle. Building or completing
+this Task does not enable the change in an already-running shared instance.
+
+Deterministic checks use disposable SQLite Homes, fake native protocol and
+injected time; they do not establish real-provider behavior or idempotency of
+arbitrary external tools. External effects still require their normal authority
+and receipt/idempotency protections.

package/docs/provider-runtime.md

@@ -91,7 +91,9 @@ The codec must not implement another Task/Run Store or invent native Turn IDs.
 Model, effort and permission requests are compiled against the peer's offered
 configuration axes and checked after application. Setters can change other axes;
 final observed values must still satisfy the requested launch before prompt.
-An acknowledgement without a reported value is weaker than an observed match.
+New and loaded Sessions must report `configOptions` (an empty array is valid).
+Configuration uses `session/set_config_option`; mode-only peers are unsupported.
+An acknowledgement without current reported values cannot satisfy a requested change.
 Unknown ACP products do not inherit a guessed bypass mode from another product.
 
 Yui distinguishes three configuration layers:

package/docs/provider-runtime.zh-CN.md

@@ -73,8 +73,10 @@ ACP 协商初始化和 Session 能力，打开或加载一个确切的 Session
 Task/Run Store，也不得编造原生 Turn ID。
 
 model、effort 和权限请求依据 peer 提供的配置轴编译，并在套用后检查。setter 可以
-改变其他轴；最终观察到的值在 prompt 之前仍必须满足请求的启动。一个没有回报值的
-确认弱于一次已观察的匹配。未知的 ACP 产品不从另一个产品继承猜测的旁路模式。
+改变其他轴；最终观察到的值在 prompt 之前仍必须满足请求的启动。
+新建和加载 Session 都必须回报 `configOptions`（可以为空数组），配置只使用
+`session/set_config_option`，不再支持 mode-only peer。仅确认调用、没有当前回报值
+不能证明请求的配置已生效。未知的 ACP 产品不从另一个产品继承猜测的旁路模式。
 
 Yui 区分三个配置层：