@zq-silk/yui 0.15.11 → 0.16.0

package/docs/release-workflow.md

@@ -20,12 +20,193 @@ Two task-level record families back it:
   exact source (repository + pinned commit, optionally an artifact), an
   immutable ordered step plan, and one persisted record per step.
 
-The engine (`src/release/releaseWorkflowEngine.ts`) is a pure library; the
+The engine (`src/release/releaseWorkflowEngine.ts`) owns persisted transitions and the workflow lock; the
 `yui task workflow` and `yui task grant` commands drive it. Every external
 system sits behind `ReleaseWorkflowPorts`
-(`src/release/releaseWorkflowPorts.ts`), so the whole workflow is testable
-with deterministic fakes and no real GitHub, npm, git, Controller, or process
-side effect.
+(`src/release/releaseWorkflowPorts.ts`). Disposable SQLite and deterministic
+external ports exercise recovery without real GitHub, npm, git, Controller,
+or model effects.
+
+## Pre-1.0 contract cleanup
+
+Version 0.16.0 retires runtime compatibility before the final
+1.0 baseline cutover. It does not reset storage numbering.
+Storage 27→28 normalizes only provable singleton Role dispatch dedupe keys;
+the old migration ledger, Messages, Task results and unconfirmed effects remain
+unchanged. Ordinary opens require storage 37. Existing Homes advance only through
+the explicit upgrade boundary; no runtime dual-reader is added.
+
+This is a breaking pre-1.0 change:
+
+- `message send` uses `--intent`; `--wake-policy` is no longer accepted by the
+  CLI or capability API. Draft edits preserve intent.
+- Internal command integrations implement `notifyMailboxChanged`; the Task-only
+  notification adapter has been removed with its callers updated.
+- ACP peers must report `configOptions`; there is no `modes`/`set_mode` path.
+- Release recovery requires a pinned Home and installation prefix. Unpinned
+  identities remain unknown, and incomplete handover locks remain fenced.
+- Development link/unlink requires the current registry. It does not discover
+  or adopt older NVM registrations or reconstruct orphan links.
+- GC no longer discovers retired deployment layouts or reconstructs removed
+  worktrees. Unsupported quarantine evidence is retained, never purged as if
+  it were a current move receipt.
+- `task activate` consumes an existing request; no request means no resource
+  adoption. Request creation, deferred admission and atomic workspace adoption
+  remain separate, using the same current boundary.
+- `task integration queue` and its state machine are removed. The Agent chooses
+  each WorkItem result's order and strategy and calls the atomic Integration
+  operations; exact checks, target CAS and completion obligations remain.
+
+Storage 28→29 preserves every former queue payload verbatim in a Task event
+`integration.queue-retired`, with its original queue ID, before dropping the
+active table. Event IDs advance past both the stored counter and existing
+history. This does not accept delivery, generate an Integration or replay work.
+Existing Integrations and Jobs stay intact. Inspect `task event list <task>`
+and the referenced WorkItem/Integration before deciding what remains to do;
+retiring the queue does not settle an unfinished Integration.
+
+Storage 29→30 retires Run-linked wakes into `wake.run-link-retired` Task events
+with the complete original payload. Current notification IDs, delivery status
+and references remain intact, using wake schema 2; Run termination no longer
+consumes notifications. Live Runs, owned retries and unresolved claims referring
+to a retiring wake block both preflight and migration. The migration does not
+stop execution or fabricate acceptance. Global Session sets use an explicit
+`providerBinding: null` when no controlled binding exists.
+
+Storage 30→31 makes every Review's scope explicit. Missing/null scope in a valid
+older WorkItem Review becomes `work-item`; Task-final candidate evidence and
+the old ledger are unchanged. New and retried Reviews always write their scope.
+
+Storage 31→32 removes WorkItem `historicalState` from the current record.
+Before removal, the entire original payload is preserved verbatim in a
+`work-item.execution-state-retired` Task event. Current status, scope, Candidates
+and execution groups are unchanged; no Run or acceptance is created. Unrecognized
+historical shapes fail without changing the record or advancing the ledger.
+
+Storage 32→33 retires the Leader rollout/budget settings and VerificationPlan
+rollout modes. Active plan bodies gain an explicit schema version; their checks
+remain unchanged, while retired Knowledge bodies are preserved. Integration
+records gain explicit `rerunChecks: false`, and shadow reuse counters are removed
+from cached artifacts. Original settings remain recoverable from the explicit
+upgrade backup. This is an approved behavior change, not an assertion that
+`record`, `reuse` and `enforce` meant the same thing.
+
+Admitted `running`/`validating` plan gates block preflight and migration; settle
+them with the old release first. No in-flight Job is relabelled under the new
+proof contract. That cutover's v3 verification-plan digest excluded older cache entries from
+automatic reuse without rewriting historical Job/Integration results or deleting
+their logs. Historical plan interpretation is frozen inside the migration
+directory so earlier migrations keep their original semantics.
+
+The current clean-candidate proof uses a v5 L2-only execution digest. Both local and
+Job-backed verification check candidate cleanliness, branch and exact HEAD
+before publishing reusable success; older cache identities cannot silently pass
+this boundary. Existing records/logs remain readable and admitted Jobs are not
+relabeled under a new digest. Settle old attempts with their matching contract,
+or explicitly abandon them before starting another operation.
+
+The L1 runner, selector and current plan/artifact type branches are removed.
+Storage 34→35 archives the original Project plan payloads and L1 artifacts/logs
+in `storage_migration_archive`, then adopts VerificationPlan schema 2 without L1.
+The archive is raw audit data, not an alternate execution reader or cache.
+Settled historical ChangeSet-source Integrations become full-payload Task Events;
+live workspaces, unsettled Jobs and adoption references block their retirement.
+The complete earlier migration ledger remains unchanged.
+
+Session custody now has one source, SQLite. Legacy `launch-env` owner rows or
+files in `runtime/session-owners` block this cutover: use the old release to
+inspect and settle their exact resources, then explicitly archive obsolete
+files outside the active Home. The migration does not kill, infer ownership,
+repair malformed records or rewrite immutable Session Manifests.
+
+Storage 35→36 preserves historical Agent errors and explicitly marks missing
+failure configuration as unavailable. Storage 36→37 narrows recorded failure
+context to native metadata-query inputs, preserving the original snapshot and
+empty optional identity placeholders in migration audit. Current error readers
+do not depend on the execution snapshot protocol or reconstruct missing history.
+Configuration rejection preserves input without automatic retry; an authorized
+Agent can inspect failure-scoped model capabilities, correct the intended
+configuration, and explicitly retry the rejected notification.
+
+`task turn` and the `yui-dev` completion identity are no longer supported.
+Before rollout, replace Sessions whose old Manifest still names `task turn`,
+and explicitly remove/archive old `yui-dev` completion blocks before installing
+current `yui` completion. User shell files are never rewritten by storage migration.
+Host control/event compatibility and updater handover safety remain unchanged.
+
+Storage 33→34 removes Message `wakePolicy` and activation `origin` from current
+records, preserving their original representations in audit Events. Historical
+save-only Messages become `intent: record`; other user/operator Messages without
+intent become `discuss`. Runtime readers never infer a missing stored intent.
+Editing record-only context does not wake the Leader. Completion reads actual
+pending message references, including an explicit handoff of previously saved context.
+
+Draft editing also preserves request identity: messages bound to submission,
+queue/steer or handoff requests cannot change body in place. Use a new Message
+and request ID; identical-body updates are no-ops. Unkeyed discussion edits
+honor pending/failed activation, while develop edits never start planning or
+create/retry activation. These are operation-boundary fixes, not a new storage
+format or a repair of previously edited historical content.
+
+An origin-less pending immediate Draft activation blocks preflight and migration,
+including on a stopped Task. Activate or cancel it explicitly with the old release
+first. An admitted current request needs no second origin gate: cancellation,
+planning deferral, execution state and exact Session authority remain enforced.
+Old origin metadata, including settled-request history, remains in
+`task.activation-origin-retired` Events; this never fabricates authorization.
+
+New `job start` calls require `--request-id`; RPC callers supply `requestId`, and
+the capability boundary supplies its invocation identity. There is no implicit
+content-addressed request or anonymous Job constructor. Existing Jobs retain
+their operation evidence and remain addressable by ID. Retrying the same explicit
+request is idempotent, changed input conflicts, and Integration recovery still
+finds its original Job across Session replacement. Choosing a new request ID is
+an explicit new operation, not recovery of an uncertain earlier result.
+
+Core Scheduler readers and persistence operations are required ports. A missing
+Session/event reader cannot be interpreted as empty evidence or skipped error
+persistence. Task execution and Web projections read the current store directly;
+queue admission requires its Task lifecycle read. Exact dispatch settlement
+remains separate and does not gain an archive gate that could lose late evidence.
+Observer, config, Knowledge and workspace-cleanup Store readers are also required;
+test doubles implement those contracts rather than selecting production fallbacks.
+
+Task listing and `/api/dashboard` now expose only the bounded catalog; remove
+`--view compact` from callers and use per-Task reads for detail. Scheduler
+catalog projections are required internal ports, not optional full-scan adapters.
+Extra `schema.json`/`state.json` files cannot override SQLite's version or be
+used to reset a development Home; upgrades leave unrelated files untouched.
+A missing database in a non-empty Home remains a refusal to initialize.
+Unrecognized writer leases are diagnosed without adoption or deletion.
+
+`controller status` always reports identity and retains the nonzero health exit
+for contradictory storage. `YUI_STATUS_IDENTITY` no longer selects another
+contract. Update-owned lifecycle capture uses the same resource collector
+directly, without requiring the old Home to pass current-schema health.
+
+Additional current boundaries:
+
+- Project/artifact file locks and handover locks require exact process-generation
+  evidence. Missing/invalid owners or unreadable OS identity remain fenced;
+  age alone never proves a creator exited. No PID-only positive fallback remains.
+- PR head lookup uses one `gh pr list --head ... --state open` query. Only an
+  empty, valid array proves absence. Transport errors, malformed identities and
+  multiple matches fail without attempting creation.
+- Existing Git operations cannot be adopted without the Integration's original
+  progress receipt. Preserve their files and diagnose explicitly; current
+  receipt-backed conflict/Job continuation remains supported.
+
+Before rollout, settle old executions and use explicit cleanup for unsupported
+locks, links or quarantines. Preserve those records until their owner and
+disposition are established; the runtime does not choose recovery for them.
+
+The later baseline cutover must first establish a verified bridge/export to the
+chosen current format, then replace the old initialization/migration chain with
+one clean baseline. Only then remove pre-baseline migrations and their historical
+fixtures. Reset the storage baseline once; do not reset it again when tagging
+1.0.0. Keep unknown-version rejection, exact process/Host identity checks and
+durable audit evidence. Version tags and real migration/publication effects
+require their separate release authorization.
 
 ## Authorization model
 
@@ -214,9 +395,11 @@ The key is passed to every `executeStep` call for that step, including
 retries after a confirmed-absent timeout. The port contract requires
 `executeStep` to be idempotent under the same key: a retried attempt must not
 produce a second side effect. The engine side of the contract is stricter
-still — it never calls `executeStep` for a step it has marked `unknown`; it
-re-queries by the recorded identity instead. The fakes record every key, so
-the test suite proves at-most-once execution directly.
+still — it never blindly calls `executeStep` for an `unknown` step; it first
+re-queries by the recorded identity. A deterministic core scenario checks
+uncertain-effect queries, confirmed-step reuse and grant exhaustion against
+real SQLite. This proves those engine boundaries, not the idempotency of real
+external services or every release adapter.
 
 ## Operator guide
 

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

@@ -15,10 +15,143 @@ Agent 选择一个预先声明的计划，设施从持久状态驱动该计划
 - **ReleaseWorkflow**（`release-workflow-N`）——计划及其进展：一个确切来源（仓库 +
   钉住的 commit，可选一个 artifact）、一份不可变的有序步骤计划，以及每步一条持久记录。
 
-引擎（`src/release/releaseWorkflowEngine.ts`）是一个纯库；`yui task workflow` 和
+引擎（`src/release/releaseWorkflowEngine.ts`）负责持久状态转换和工作流锁；`yui task workflow` 和
 `yui task grant` 命令驱动它。每个外部系统都位于 `ReleaseWorkflowPorts`
-（`src/release/releaseWorkflowPorts.ts`）之后，因此整个工作流可以用确定性的 fake
-测试，不产生任何真实的 GitHub、npm、git、Controller 或进程副作用。
+（`src/release/releaseWorkflowPorts.ts`）之后。可用临时 SQLite 和确定性的外部端口测试
+恢复逻辑，无需真实 GitHub、npm、git、Controller 或模型效果。
+
+## 1.0 前的契约清理
+
+版本 `0.16.0` 先清退运行时兼容分支，尚未执行最终 1.0 基线切换，也不重置
+存储编号。存储 `27→28` 只规范化可明确识别的单条 Role 调度去重键，旧迁移账本、
+Message、Task 结果和不确定外部效果保持不变。普通打开要求存储 37；已有 Home 只通过
+显式升级入口前进，不增加运行时双读。
+
+这是一次 1.0 前的破坏性变更：
+
+- `message send` 统一使用 `--intent`；CLI 与 capability API 不再接受 `--wake-policy`
+  或 `wakePolicy` 参数，Draft 编辑保留原提交意图。
+- 内部命令集成实现 `notifyMailboxChanged`；Task-only 通知适配器及其调用已统一。
+- ACP peer 必须回报 `configOptions`，不再走 `modes`／`set_mode` 路径。
+- Release 恢复要求精确 Home 与安装 prefix。缺少固定目标的效果保持 unknown，
+  身份不完整的 handover lock 保持围栏。
+- 开发 link/unlink 要求当前登记文件，不搜索或接管旧 NVM 登记，不重建孤立链接。
+- GC 不再发现旧 deployment 布局或重建已删除 worktree；不受支持的 quarantine
+  证据保留，不会被当成当前 move 回执清除。
+- `task activate` 只消费已有请求；没有请求就不采用资源。请求创建、延后准入和
+  原子工作区采用仍分开，并复用同一个现行执行边界。
+- 删除 `task integration queue` 及其状态机。Agent 选择每个 WorkItem 结果的顺序与
+  策略，逐项调用原子 Integration；保留精确检查、目标 CAS 和完成义务。
+
+存储 `28→29` 在删除活动队列表前，将每条旧 payload 原样保存在
+`integration.queue-retired` Task 事件中，并保留原队列 ID。事件编号越过已有计数器
+和历史最大 ID。此操作不验收交付、不生成 Integration、不重放工作；已有 Integration
+与 Job 保持不变。通过 `task event list <task>` 和引用的 WorkItem/Integration
+判断剩余工作；队列退役不代表未完成的 Integration 已结算。
+
+存储 `29→30` 将 Run-linked wake 的完整原文移入 `wake.run-link-retired` Task 事件。
+现有通知保留 ID、投递状态和引用，使用 wake schema 2；Run 终态不再消费通知。
+引用待退役 wake 的活动 Run、受管重试或未决 claim 会同时阻止预检和迁移；
+迁移不停止执行、不编造接受。Global Session 没有受控 binding 时统一显式保存
+`providerBinding: null`。
+
+存储 `30→31` 将 Review scope 统一为显式值：有效旧 WorkItem Review 的缺失／null
+scope 转为 `work-item`，Task-final 候选证据和原迁移账本不变。新建和重试均显式写入 scope。
+
+存储 `31→32` 从当前 WorkItem 移除 `historicalState`，移除前将完整原始 payload
+原样保存在 `work-item.execution-state-retired` Task 事件。当前状态、工作范围、
+Candidate 和执行组不变，不生成 Run 或验收。未知历史形态会报错，记录和迁移账本不前进。
+
+存储 `32→33` 清退 Leader 过渡／预算配置以及 VerificationPlan 的模式。
+活动计划显式补上 schema 版本，实际检查保持不变；已退役 Knowledge 原文保留。
+Integration 显式补入 `rerunChecks: false`，缓存 Artifact 移除试运行复用计数。
+原配置可从显式升级备份恢复。这是已确认的行为变更，不将三种旧模式声称为等价。
+
+已接纳且仍为 `running/validating` 的计划验证会阻止预检和迁移，需先用旧版本完成
+结算；不会把运行中的 Job 改标为新证据契约。该次切换使用 v3 验证摘要，使更早缓存不再被
+自动复用，不重写历史 Job／Integration 结果或删除其日志。旧计划解析冻结在迁移
+目录中，早期迁移保持原有语义。
+
+现行干净候选证明采用 v5 L2-only 执行摘要。Job 和本地验证都在发布可复用成功前，
+检查候选工作区的干净状态、分支和精确 HEAD；旧缓存身份不能绕过这一边界。
+旧记录和日志保持可读，已接纳 Job 不会被改标为新摘要。应先按原契约结算旧尝试，
+或明确放弃后再开始新操作。
+
+L1 执行入口、选择器及当前计划／artifact 类型分支已移除。存储 `34→35` 将
+原始 Project 计划、L1 artifact 与日志保存在 `storage_migration_archive`，
+当前计划改为不含 L1 的 schema 2。存档只是原始审计数据，不是执行 reader 或缓存。
+已结算的旧 ChangeSet-source Integration 转为完整 payload 的 Task 事件；
+仍有工作区、未结算 Job 或 adoption 引用时阻止退休。旧迁移账本不变。
+
+Session 归属统一使用 SQLite。旧 `launch-env` owner 行或 `runtime/session-owners`
+中的文件会阻止切换：先使用旧版本检查并释放精确资源，再明确将旧文件归档到
+活动 Home 之外。迁移不杀进程、不推断归属、不修复损坏数据，也不重写不可变 Manifest。
+
+存储 `35→36` 保留历史 Agent 错误，并将缺失的失败配置明确标为不可用。
+存储 `36→37` 将已记录的失败上下文缩小为原生元数据查询所需输入，原始快照和
+空的可选身份占位值保存在迁移审计中。当前错误读取不依赖执行快照协议，也不
+重建缺失历史。配置拒绝保留原始输入但不自动重试；有权限的 Agent 可查询该次
+失败的模型能力、修正原本要求的配置，再显式重试被拒绝的通知。
+
+不再支持 `task turn` 和 `yui-dev` 补全身份。上线前应替换仍依赖 `task turn`
+Manifest 的 Session；明确卸载／归档旧 `yui-dev` 补全块后，再安装现行 `yui` 补全。
+存储迁移不会修改用户 shell 文件。Host 控制／事件兼容与 updater 交接安全检查保持不变。
+
+存储 `33→34` 从当前记录移除 Message `wakePolicy` 与激活 `origin`，原始表达
+保存在审计事件。旧的仅记录消息转换为 `intent: record`，其他缺少意图的
+user/operator 消息转换为 `discuss`；运行时不再解释缺失的持久化意图。
+编辑仅记录内容不会唤醒 Leader。完成检查读取实际待投递消息引用，也涵盖显式交接
+此前仅保存的内容。
+
+Draft 编辑同时保护请求身份：已经绑定 submission、queue/steer 或交接请求的消息
+不能原地改正文，需新建消息并使用新请求 ID；相同正文更新为无操作。未绑定请求
+身份的讨论编辑仍遵守 pending/failed 激活状态，develop 编辑不启动规划或创建／
+重试激活。这是操作边界修复，不改变存储格式，也不猜测修复过去已被编辑的原文。
+
+Draft 中缺少 origin 且仍 pending 的旧 immediate 激活请求会阻止预检和迁移，即使 Task
+已停止执行。必须先用旧版本显式激活或取消；升级不替用户做这个决定。当前已接纳
+请求不再经过第二次来源门槛，但取消、planning 延后、执行状态与精确 Session 权限
+仍需检查。旧来源及 settled 请求历史保留在 `task.activation-origin-retired` 事件。
+
+新 `job start` 必须带 `--request-id`；RPC 必须提供 `requestId`，capability
+入口使用 invocation 身份。不再从命令内容隐式生成请求，也不再构造匿名 Job。
+已有 Job 的操作证据和按 ID 读取保持不变；相同请求重试防重、不同输入冲突，
+Integration 在 Session 替换后仍找回原 Job。新 request ID 表示明确的新操作，
+不是对旧未知结果的自动重放。
+
+Scheduler 核心读取和持久化操作成为必需接口，缺少 Session／Event 读取不再被当作
+空证据，也不能跳过错误持久化。执行及 Web 投影直接读取当前 Store；
+消息入队必须读取 Task 生命周期。精确投递结算仍独立，不增加会丢失迟到证据的归档门槛。
+Observer、配置、Knowledge 与工作区清理所需 Store 读取也成为必需接口；
+测试替身实现现行合同，不再令生产代码降级。
+
+Task 列表及 `/api/dashboard` 只保留有界目录；调用方去掉 `--view compact`，
+详情使用单 Task 读取。Scheduler 目录索引是必需接口，不再兼容缺失时的全量扫描。
+额外 `schema.json`／`state.json` 不覆盖 SQLite 版本，也不用于开发 Home reset；
+升级保留无关文件。非空 Home 缺少数据库时仍拒绝初始化。
+不认识的 writer lease 明确诊断，不接管、不删除。
+
+`controller status` 固定输出身份信息，存储矛盾仍返回非零健康退出码；
+`YUI_STATUS_IDENTITY` 不再选择另一套契约。升级侧直接复用资源采集器读取生命周期，
+无需让旧 Home 先通过当前 schema 的健康校验。
+
+现行边界进一步收敛：
+
+- Project／Artifact 文件锁及 handover lock 要求精确进程代际证据。owner 缺失、
+  格式不完整或 OS 身份不可读时保持围栏；仅凭年龄不能证明创建者退出，不再用
+  PID-only 存活判断代替身份确认。
+- PR head 查询只调用 `gh pr list --head ... --state open`。仅有效空数组证明不存在；
+  传输失败、身份格式错误和多个匹配都不允许继续创建。
+- 已有 Git 操作缺少原 Integration 进度回执时不再被接管。保留文件并明确诊断；
+  有精确回执的正常冲突／Job 续作仍受支持。
+
+发布前应先收敛旧执行，对不受支持的锁、链接和隔离资源做显式清理。归属与处置尚未
+确定时保留原记录，运行时不替 Agent 选择恢复方案。
+
+后续基线切换必须先验证到目标格式的桥接或导出，再用一个干净基线替换旧初始化和迁移链，
+之后才能删除基线之前的迁移及历史夹具。存储基线只重置一次，不在发布 `1.0.0` 时再次
+重置。未知版本拒绝、精确进程／Host 身份检查与持久审计证据仍应保留。版本 tag、真实
+Home 迁移和发布效果需要各自的发布授权。
 
 ## 授权模型
 
@@ -165,8 +298,9 @@ kind、可选 params，以及一个可选的不可逆级别（`none` | `reversib
 
 该键被传给该步骤的每一次 `executeStep` 调用，包括在一次确认为 absent 的超时之后的
 重试。端口合同要求 `executeStep` 在同一键下是幂等的：一次重试尝试不得产生第二次
-副作用。引擎侧的合同更严格——它绝不为一个已标记 `unknown` 的步骤调用 `executeStep`,
-而是按记录的身份重新查询。fake 记录每一个键，因此测试套件直接证明至多一次执行。
+副作用。引擎不会盲目为 `unknown` 步骤调用 `executeStep`，而是先按记录的身份查询。
+核心测试用真实 SQLite 和确定性端口检查不确定效果查询、已确认步骤复用和 grant 次数耗尽。
+这证明这些引擎边界，不代表真实外部服务或所有发布适配器的幂等性已被验证。
 
 ## Operator 指南
 

package/docs/roles-and-configuration.md

@@ -93,10 +93,20 @@ services. Isolating `YUI_HOME` or replacing a Session does not require a fresh
 native account directory. Managed Task execution uses Claude's non-interactive
 stream-json path with the same native configuration ownership.
 
+Model catalogs are native observations, not a universal Provider whitelist.
+Yui displays the selectable ID/alias and its reported resolved model. An explicit
+custom ID is passed unchanged when the native model field allows custom values;
+this does not prove that the Provider will accept it. Known model-specific effort
+limits are still validated. Configuration rejection reports the observed model
+options and how to inspect the full catalog; an unavailable catalog is not
+replaced by a fabricated list.
+
 ## Commands
 
 ```sh
 yui config agent capabilities <agent-id>
+yui task role capabilities <task> <role> --refresh
+yui task role capabilities <task> <role> --error <error-event-id> --refresh
 yui config role show <global-role>
 yui config profile show <profile>
 yui task role add <task> <role> --profile <profile>
@@ -107,6 +117,25 @@ yui task role session inspect <task> <role>
 yui task role session new <task> <role> --reason "<why a fresh Session is useful>"
 ```
 
+The global query uses the calling process's default native context. Task-scoped
+queries use the Controller's native account environment and the selected Role
+configuration; they never forward the caller's credentials to another Provider.
+Omitting `--error` selects the current desired Role. With `--error`, the recorded
+failed request supplies model, workspace and profile/settings options even after
+the Role changes. A changed configured Agent command/environment binding or an
+unrecorded historical context produces a diagnosis, not a default substitution.
+Task-scoped metadata queries require a running Controller and do not start one.
+
+`--refresh` explicitly re-probes metadata. A failed probe may show a clearly
+marked cached catalog, not claim it is current. Native files and credentials
+are read currently; their secret contents are never snapshotted in error history.
+The lookup reports metadata only, without running a model to test a candidate ID.
+
+Completed in-memory catalogs have a bounded least-recently-used cache. Concurrent
+requests for the same scope share the active probe, including refresh requests;
+once it settles, an explicit refresh probes again. Retained results are labelled
+as cached rather than as a new live response. No cleanup timer or worker is added.
+
 On Role creation, explicit Agent settings require `--agent`. On update, omitted
 `--agent` targets the active binding; a named binding is updated without being
 activated. `task role bind` changes selection. A live Session requires the

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

@@ -75,10 +75,17 @@ Claude 自身加载原生设置，并按其生效配置在 API key、既有 help
 服务。隔离 `YUI_HOME` 或替换 Session 都不要求一个全新的原生账号目录。受管的 Task
 执行使用 Claude 的非交互 stream-json 路径，并沿用同样的原生配置归属。
 
+模型目录是原生观测结果，不是整个 Provider 的模型白名单。Yui 显示可选择的 ID/别名
+及原生报告的实际模型映射。原生模型字段允许自定义值时，显式模型 ID 会原样透传；
+这不代表 Provider 已接受该模型。已知模型的 effort 限制仍会校验。配置校验拒绝会显示
+已观测到的模型选项和完整目录查询方式；目录不可用时，不编造“合法模型列表”。
+
 ## 命令
 
 ```sh
 yui config agent capabilities <agent-id>
+yui task role capabilities <task> <role> --refresh
+yui task role capabilities <task> <role> --error <error-event-id> --refresh
 yui config role show <global-role>
 yui config profile show <profile>
 yui task role add <task> <role> --profile <profile>
@@ -89,6 +96,20 @@ yui task role session inspect <task> <role>
 yui task role session new <task> <role> --reason "<why a fresh Session is useful>"
 ```
 
+全局查询使用调用进程的默认原生环境；Task 查询使用 Controller 的原生账户环境及
+所选 Role 配置，不把调用方的凭据转交给其他 Provider。省略 `--error` 查看当前期望
+配置；指定错误记录时，使用失败时保存的模型、工作区、profile/settings 选项，不受
+之后的 Role 修改影响。若配置的 Agent 命令／环境绑定已变化，或历史错误未记录配置，
+返回明确诊断，不替换成默认配置。Task 查询要求 Controller 已运行，不自动启动它。
+
+`--refresh` 显式重新查询元数据；查询失败后返回缓存时会标明缓存来源，不冒充当前
+结果。原生文件及凭据仍按当前值读取，秘密内容不会复制进错误历史。这里只查询
+元数据，不通过真实模型调用来试验候选名称。
+
+已完成目录使用有容量上限的近期使用缓存；相同上下文的并发请求（包括刷新）共享
+正在进行的查询，结束后显式刷新才重新查询。缓存命中标为缓存，不冒充新的实时响应。
+这不增加清理定时器或后台 worker。
+
 创建 Role 时，显式的 Agent 设置需要 `--agent`。更新时，省略 `--agent` 针对活动
 绑定；一个具名绑定会被更新但不被激活。`task role bind` 更改选择。在更改期望设置
 之前，活动 Session 需要该命令的显式确认。

package/docs/sqlite-control-plane-design.md

@@ -34,6 +34,19 @@ model. A newer, below-minimum, incomplete, or malformed Home fails closed.
 There is no runtime normalization, repair worker, file-Store fallback, dual
 read/write path, or second migration authority.
 
+Typed domain payloads use one current validator registry on writes, ordinary
+reads, bounded Context pages and full-Home diagnostics. Direct and worker-backed
+Stores do not have different validation strength. Invalid records are rejected
+without advancing the revision; an invalid stored record remains available for
+explicit diagnosis, never normalized into a valid-looking replacement.
+
+Storage 35 also has a migration-only `storage_migration_archive` table:
+`migration_version / family / record_key / payload / content`. It retains exact
+retired Project/gate payloads and binary logs without interpreting them in the
+current model. It is not scheduling state, a second cache or a runtime fallback.
+Task-scoped historical Integration retirement uses ordinary Task Events.
+Backups retain both current records and this audit archive.
+
 ## Write and concurrency contract
 
 - Each mutation is one SQLite transaction.
@@ -69,8 +82,8 @@ Every persistent schema or payload change appends one immutable, contiguous
 storage migration. The CLI publishes both `storageVersion` and
 `minimumStorageVersion`; every valid Home in that inclusive range can upgrade
 directly to the current version without installing intermediate releases.
-The current source declares storage version **25**, with minimum supported
-migration version **1**, in `src/storage/storageVersions.ts`. Homes below that
+The current version and migration floor are declared only in
+`src/storage/storageVersions.ts` and exposed by CLI identity. Homes below that
 floor are not migration inputs and remain untouched.
 The target binary's `upgrade --update-preflight` and `--update-apply` result
 shapes and parent-owned handover-lock proof remain backward compatible with
@@ -123,7 +136,7 @@ unifying the root does not weaken control-data or cross-owner isolation.
 **not** a second authority for internal managed paths, and is intentionally not
 an input to `homeLayout.ts`. A Yui-auto-created Global Role that carries no
 user-chosen cwd no longer falls back to it (or to `process.cwd()`): `yui setup`'s
-built-in Operator/Leader and `yui role add` without `--workspace` now default to
+built-in Operator/Leader and `yui config role add` without `--workspace` now default to
 the Home-internal `managedGlobalRoleWorkspace(home)` (`<home>/workspaces/global`),
 and `setup` no longer fabricates an external Home-sibling `workspace/` — a
 `default-workspace` is persisted only if the user configured one. A user who

package/docs/sqlite-control-plane-design.zh-CN.md

@@ -28,6 +28,17 @@ Yui 只有一个权威产品 Store：WAL 模式下的 `YUI_HOME/yui.db`。`schem
 不完整的或损坏的 Home 一律 fail closed。不存在运行时归一化、修复 worker、
 文件 Store 回退、双读写路径或第二套迁移权威。
 
+类型化领域记录在写入、普通读取、有界 Context 分页和全 Home 检查时，共用一份
+现行校验注册表。直接 Store 与 worker-backed Store 不存在不同强度的校验。
+无效写入不会推进 revision；已存在的无效记录只会报错并保留供明确诊断，
+不会被自动规范化成看似有效的替代记录。
+
+存储 35 新增仅由迁移写入的 `storage_migration_archive`：
+`migration_version / family / record_key / payload / content`。它保留退休的
+Project／gate 原始 payload 和二进制日志，不在当前模型中解释这些历史格式，
+也不是调度状态、第二份缓存或运行时回退。Task 内的历史 Integration 使用普通
+Task 事件保存。数据库备份同时保留当前记录与这份审计存档。
+
 ## 写入与并发合同
 
 - 每次修改是一个 SQLite 事务。
@@ -54,8 +65,8 @@ WorkItem 与 Task 的验收权威仍归 Leader。
 
 每次持久 schema 或负载变更都追加一条不可变、连续的存储迁移。CLI 同时发布
 `storageVersion` 与 `minimumStorageVersion`；处在该闭区间内的每个有效 Home 都能
-直接升级到当前版本，无需安装中间发行版。当前源码在
-`src/storage/storageVersions.ts` 中声明存储版本 **18**、最低支持迁移版本 **1**。
+直接升级到当前版本，无需安装中间发行版。当前版本及最低支持版本统一由
+`src/storage/storageVersions.ts` 声明，并由 CLI 身份读取暴露。
 低于该下限的 Home 不是迁移输入，保持原样不动。目标二进制的
 `upgrade --update-preflight` 与 `--update-apply` 结果形态，以及由父进程持有的
 交接锁证明，对从存储版本 1 起发布的每个 updater 都保持向后兼容，因此一个旧的

package/docs/task-dag-semantics.md

@@ -61,10 +61,10 @@ it does not accept a WorkItem or rewrite dependencies.
 Direct and replicated execution share one Leader acceptance boundary. A
 replicated Producer does not form a Candidate; only the explicitly synthesized
 main Run result enters the candidate path. Delivery the Leader manages directly
-must also satisfy the applicable Candidate, ChangeSet and Integration boundaries.
+must also satisfy the applicable Candidate and Integration boundaries.
 
-An isolated code result captures a fixed per-Project ChangeSet and integrates via
-compare-and-swap after its checks; an uncaptured, unintegrated or stale latest
+An isolated code result freezes per-Project Candidate commits and integrates via
+compare-and-swap after its checks; an unsnapshotted, unintegrated or stale latest
 result cannot satisfy delivery. Review is checked against the applicable rule and
 the Task contract. A Task main the Leader delivers itself needs a clean,
 committed, exact snapshot.

package/docs/task-dag-semantics.zh-CN.md

@@ -45,9 +45,9 @@ InputRequest 表示待决问题；回答不自动接受 WorkItem 或改写依赖
 
 Direct 和 replicated 共享一个 Leader 接受边界。Replicated Producer 不形成
 Candidate；只有显式综合的 main Run 结果进入候选路径。Leader 直接管理的
-交付也必须满足适用的 Candidate、ChangeSet 和 Integration 边界。
+交付也必须满足适用的 Candidate 和 Integration 边界。
 
-隔离代码结果按 Project 捕获固定 ChangeSet，检查后 CAS 集成；未捕获、未集成
+隔离代码结果按 Project 冻结 Candidate 提交，检查后 CAS 集成；缺少快照、未集成
 或失效的最新结果不能满足交付。Review 依适用规则和 Task 合同检查。
 Leader 自己交付的 Task main 需要干净、已提交的精确快照。