@zq-silk/yui 0.15.9 → 0.15.12

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

@@ -78,6 +78,26 @@ Surface contribution 由 Registry 当前获授权目录派生，没有第二份
 CLI contribution 使用能力原名称。Web panel 只接受受控 text、HTTP(S) link 或
 JSON query 描述，不接受作者脚本或任意 HTML。
 
-Web listener 由 Controller 启停，仅允许 loopback。浏览器写入通过现有领域
-事务，错误区分确定未提交与提交结果未知。查询面板不能借浏览器身份执行 mutation
-或插件管理。终端连接只 attach 客户端，不接管原生对话的持久所有权。
+Web listener 由 Controller 启停，仅允许 loopback（`127.0.0.1`、`::1` 或
+`localhost`；默认端口 4173）。`yui web` 打开的是本地 Surface，不是远程多用户
+服务或 OS 沙箱。
+
+页面提供 token，通过 `x-yui-web-token` 认证所有 HTTP API 读取与写入；服务端
+也检查 loopback Host。这些控制使用受信任本地用户身份，不由请求正文选择 Role。
+它们支持修改 Task 元数据、发送消息、回答 InputRequest，以及对 Task 或 Global
+Role 显式 `queue / steer / interrupt`。受管 Agent 的能力 RPC 仍使用自身 Session
+认证与范围；浏览器 token 不是 Agent 或插件绕过这些边界的途径。
+
+只读 dashboard、Context 和查询面板投影与这些修改分开。查询面板不能借浏览器的
+用户权限修改状态或管理插件。Task 控制复用公开 CLI 领域命令；Global Role 控制复用
+Global 处理器，但目前缺少已注册的顶层 CLI 路径。消息提交意图
+（`record / discuss / develop`，默认 `discuss`）与
+[输入时机](../managed-turn-and-session-runtime.zh-CN.md#输入时机queuesteer-与-interrupt)
+分开。传输接受不证明需求已实施或 Task 已验收。
+
+浏览器写入使用现有领域事务。错误区分已证明的 `not-submitted` 与 `unknown`；
+后者可能包含已经提交、但原生投递失败或未确认的 Message。选择恢复动作前先读
+原始 Message、控制回执和当前 Session，不盲目换 request ID 重发或切换动作。
+
+终端 WebSocket 校验 token 和同源握手。它只 attach 客户端，不接管对话的持久
+所有权，并遵守连接的 `readOnly` 标记。附着终端不授予控制其他 Session 的权限。

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

@@ -109,6 +109,53 @@ Resolve releases the claim after native-effect fences are clear. It neither
 replays the notification nor invents acceptance or completion. Independent
 Role work and legal local facts are not a Task-wide recovery lock.
 
+## Input timing: queue, steer and interrupt
+
+Submission intent (`record / discuss / develop`) decides how a requirement is
+routed. Input timing decides when an already-authorized input reaches a Role;
+it does not activate a Task, expand an Assignment or upgrade planning authority.
+The [authenticated Web controls](architecture/capabilities-and-resources.md#cli-and-web)
+use the same three operations as the CLI.
+
+| Action | Effect | What it does not prove |
+| --- | --- | --- |
+| `queue` | Saves a Message for the recipient's next legal opportunity, idempotently by request ID | Reading Context or accepting delivery is not implementation |
+| `steer` | Saves a Message and attempts native steering of the exact current Turn | Unsupported, stale or unconfirmed steering is not a queued continuation |
+| `interrupt` | Records a control request and asks the Provider to cancel the exact current Turn | A stop request is not a terminal or proof that background resources stopped |
+
+Inspect the Session before selecting a live target:
+
+```sh
+yui task role session inspect <task> <role>
+yui task message queue <task> "<continuation>" --request-id <id> --to leader
+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>]
+```
+
+Worker/Reviewer messages retain their existing `--work-item` or `--review-round`
+association. Reusing a request ID with different content or a different target
+is a conflict. `steer` and `interrupt` never silently retarget, replace a Session,
+kill a process or fall back to another action. No live managed Turn yields
+`NO_ACTIVE_TURN`; stale targets and unsupported control remain explicit outcomes.
+
+Bare interrupt creates no Message. Optional `--then-message` names an already-saved,
+eligible input and reserves its next opportunity only after an exact terminal,
+within the original Session/writer boundary. It is not a fourth action or a way
+to replay accepted, pending or unknown steering. A conclusive non-delivery can
+permit an explicit new control choice when the user's intent authorizes it;
+uncertainty cannot.
+
+Global Roles use the same three actions with their own owner and Session,
+without inventing a Task or Run. The local-user Web surface exposes them through
+the shared Global Role handler. There is a current CLI availability gap:
+`src/cli.ts` implements `yui role message queue|steer` and `yui role interrupt`,
+but `src/cli/commandCatalog.ts` does not register the top-level `role` command,
+so public CLI routing rejects these paths as unknown. They are not usable CLI
+examples; report this gap rather than fabricating a Task/Run or borrowing the
+browser's user authority. New controlled Global Sessions use the Host console.
+A live unmanaged Session is not silently adopted; an explicit Session lifecycle
+action is needed first.
+
 ## Exact results
 
 The native terminal settles only the matching execution. Known native Turn IDs

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

@@ -94,6 +94,46 @@ yui task wake resolve <task> <wake> --reason <quiescence-evidence>
 resolve 在原生效果围栏清除后释放该认领。它既不重放通知，也不编造接受或完成。独立的
 Role 工作和合法的本地事实不是一把 Task 范围的恢复锁。
 
+## 输入时机：queue、steer 与 interrupt
+
+提交意图（`record / discuss / develop`）决定需求如何路由。输入时机决定一条已经
+获授权的输入何时到达 Role；它不激活 Task、不扩大 Assignment，也不提升 planning
+权限。[经认证的 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> --to leader
+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>]
+```
+
+Worker/Reviewer 消息保留既有的 `--work-item` 或 `--review-round` 关联。同一个
+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 存在可用性
+缺口：`src/cli.ts` 实现了 `yui role message queue|steer` 和 `yui role interrupt`，
+但 `src/cli/commandCatalog.ts` 没有注册顶层 `role`，因此公开 CLI 路由会拒绝这些路径，
+报告 unknown command。它们不是可用的 CLI 示例；应报告该缺口，不虚构 Task/Run 或
+借用浏览器用户权限。新的受控 Global Session 使用 Host console。活动的非受管 Session
+不会被静默采用，需要先执行显式的 Session 生命周期操作。
+
 ## 精确结果
 
 原生终态只结算相匹配的那次执行。已知的原生 Turn ID 必须匹配；串行流可以使用已证明的

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/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/release-workflow.md

@@ -74,6 +74,45 @@ Candidate and Task-final ReviewRound records must all carry that one contract.
 Conflicting records fail closed; there is no rebind event, recovery command, or
 second contract state machine.
 
+## Persistent Agent Host compatibility
+
+A running Host keeps its original Endpoint implementation. It records exact
+Session/attempt/native-Turn facts in the existing durable Inbox before contacting
+the Controller; only the current Controller resolves Run ownership, validates
+authority/workspace/lifecycle/history, and commits the result. An Inbox file is
+not acceptance. Files are consumed only after commit, so downtime or a lost ACK
+does not replay user input or model work.
+
+Startup facts use the exact Run identity from the redeemed launch payload, not
+the long-lived Session environment. This preserves pre-adoption evidence even
+when the frozen Run workspace differs from the Role's default; later activity
+and terminal facts still resolve solely by their own native input identities.
+
+The supported Host boundary is control `yui-agent-host/v5`, event source
+`yui-agent-host-events/v1`, and Controller RPC version 4. Hosts advertising
+`storage=controller-owned` do not open the Home database, including for process
+custody, native account locations, or execution-environment checks. Home 22
+declares the additive Inbox source envelope; valid older Inbox v1 facts and
+domain history remain readable. Future changes must retain this wire boundary
+or reject incompatible live producers before changing storage. CLI wrapper
+refresh and a successful new `doctor` are not Host compatibility proofs.
+
+`upgrade`, the staged target's `update` preflight, and release activation inspect
+live Host capabilities independently. An old Host without this capability,
+including an idle Host or one whose response is unconfirmed, blocks adoption.
+Checks are repeated at the existing fenced/quiesced handover boundary before
+migration or promotion. No Host is killed, replaced, or reloaded by these checks.
+Let existing work settle and preserve original pending input/result evidence;
+then an authorized Operator can select a safe Session replacement/cleanup before
+retrying. Installing this change cannot repair already-loaded legacy Host code
+or collect a terminal that that code never durably emitted.
+
+`task role status`, `task role list`, and `task role session inspect` expose Host
+reporting alongside durable Run state. Pending native results or known reporting
+failures require attention; they do not mean the Provider failed, the Run ended,
+or the work was accepted. The Host's live diagnostics inspect only its own event
+file identities and never parse or quarantine another producer's newer payload.
+
 ## CLI and Controller release boundary
 
 The global `yui` command is the stable user and managed-Session interface. It

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

@@ -59,6 +59,35 @@ Session 使用普通的 `yui` 命令，兼容性由协议和存储身份检查
 Task-final 的 ReviewRound 记录必须全部携带那唯一的合同。冲突的记录 fail closed；
 不存在重新绑定事件、恢复命令或第二套合同状态机。
 
+## 常驻 Agent Host 升级兼容
+
+存活 Host 保持原 Endpoint 实现，先把准确的 Session/attempt/nativeTurn 事实写入现有
+持久 Inbox，再联系 Controller。只有当前 Controller 解析 Run 归属、校验权限、工作区、
+生命周期与历史关联并提交结果。Inbox 文件不代表接受；提交后才确认消费，断线或丢失
+ACK 不会重放用户输入或模型工作。
+
+启动事实从已兑现的 launch payload 取得准确 Run 身份，不把 Run 固定到长期 Session
+环境。即使冻结的 Run 工作区不同于 Role 默认值，登记前的证据也能保留；后续活动和
+终态仍只按各自的原生输入身份解析归属。
+
+支持边界为控制协议 `yui-agent-host/v5`、事件来源协议 `yui-agent-host-events/v1`、
+Controller RPC 版本 4。声明 `storage=controller-owned` 的 Host 不打开 Home 数据库，
+包括进程归属、原生账号位置和执行环境校验。Home 22 声明 Inbox 的新增来源字段，
+不改写有效历史事实与业务记录。后续版本要么保留该线协议，要么在修改存储前拒绝不兼容
+的存活生产者。刷新 Session CLI wrapper 或新 `doctor` 成功都不能证明旧 Host 兼容。
+
+`upgrade`、`update` 的目标版本预检及 release activation 独立检查存活 Host。
+没有此能力的 legacy Host（包括 idle）以及兼容响应不确定的 Host 都阻止采用；
+在既有隔离/静默交接边界再次检查，先于迁移或发布切换。检查不会 kill、替换或 reload
+Host。先让原有工作结束并保留原始未决输入/结果证据，再由获授权的 Operator 在安全
+边界选择 Session 替换或清理，之后重试。安装新代码不能修改已加载的 legacy Host 内存，
+也不能回收它从未持久投递过的终态。
+
+`task role status`、`task role list` 和 `task role session inspect` 在持久 Run 状态旁
+显示 Host 上报观测。原生结果待落库或已知上报故障需要关注，但不代表 Provider 失败、
+Run 已结束或业务已验收。Host 诊断只检查自己已投递文件的身份是否存在，不解析或隔离
+其他生产者的新格式事件。
+
 ## CLI 与 Controller 发布边界
 
 全局 `yui` 命令是稳定的用户与受管 Session 接口。对普通命令，它不跟随