@zq-silk/yui 0.15.7 → 0.15.9

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

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

package/docs/architecture/README.md

@@ -0,0 +1,50 @@
+<p align="right"><strong>English</strong> | <a href="./README.zh-CN.md">简体中文</a></p>
+
+# Architecture and documentation map
+
+These documents describe the current source contracts. A capability boundary is
+not a claim that every real Provider scenario has been validated.
+
+## Start here
+
+- [README](../../README.md): install, configure and everyday use.
+- [Chinese README](../../i18n/README.zh-CN.md): the same product entry in
+  Simplified Chinese.
+- [Architecture overview](../../ARCHITECTURE.md): responsibilities, authority and
+  the end-to-end flow.
+- [Capabilities, resources and Surfaces](capabilities-and-resources.md): the
+  extension ingress, instance ownership and resource effects.
+
+## Domain contracts
+
+| Question | Current document |
+| --- | --- |
+| How do Session, AgentRun, messages and activation fit together? | [Session and AgentRun runtime](../managed-turn-and-session-runtime.md) |
+| Who consumes results, synthesis and review? | [Result consumption](../agent-result-consumption.md) |
+| When is a WorkItem dependency satisfied? | [Task dependencies](../task-dag-semantics.md) |
+| How are records referenced inside a Task? | [Task-local identity](../task-local-identity.md) |
+| How do Roles, Profiles and run configuration take effect? | [Roles and configuration](../roles-and-configuration.md) |
+| How do delivery, integration and archive work? | [Task delivery](../task-delivery.md) |
+| How do Provider, ACP and configuration facts connect? | [Provider runtime](../provider-runtime.md) |
+| Who interprets runtime observations and errors? | [Agent Drivers](../agent-runtime-drivers.md) |
+| How are plugins created, validated and adopted? | [Plugin SDK](../plugin-sdk.md) |
+| What are the data, upgrade and concurrency boundaries? | [SQLite control plane](../sqlite-control-plane-design.md) |
+| How do authorized release operations run? | [Release workflow](../release-workflow.md) |
+| How do I read current runtime evidence? | [Observability](../observability/README.md) |
+| Which checks should be kept permanently? | [Verification policy](../testing/verification-levels.md) |
+
+## Maintenance conventions
+
+When behavior changes, update the owning contract and any entry-point text in the
+same change. The exact CLI flags are defined by `src/cli/commandCatalog.ts` and
+the command handlers; public domain types follow the running source. We do not
+maintain a separate target model or a generated offline copy.
+
+Each document is bilingual: `X.md` is the English version and `X.zh-CN.md` is the
+Simplified Chinese one. When behavior changes, update both language versions
+together so they stay in sync.
+
+The Project Skill owns Yui's development and validation rules; the generic Role
+Skills own how an Agent uses Yui. Repository documents do not replace the Project
+Knowledge maintained under `YUI_HOME`, and they do not grant execution access to
+shared environments, real models or external systems.

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

@@ -0,0 +1,43 @@
+<p align="right"><a href="./README.md">English</a> | <strong>简体中文</strong></p>
+
+# 当前架构与文档导航
+
+以下文档描述当前源码合同。能力边界不等于所有真实 Provider 场景已经验证。
+
+## 阅读入口
+
+- [English README](../../README.md)：安装、配置和日常使用。
+- [中文 README](../../i18n/README.zh-CN.md)：同一产品入口的中文说明。
+- [总体架构](../../ARCHITECTURE.md)：职责、权威和端到端流程（英文）。
+- [能力、资源与 Surface](capabilities-and-resources.zh-CN.md)：扩展入口、实例所有权和资源效果。
+
+## 领域合同
+
+| 问题 | 当前文档 |
+| --- | --- |
+| Session、AgentRun、消息和激活如何配合？ | [执行与会话](../managed-turn-and-session-runtime.zh-CN.md) |
+| 谁消费结果、综合与审查？ | [结果消费](../agent-result-consumption.zh-CN.md) |
+| WorkItem 依赖何时满足？ | [Task 依赖](../task-dag-semantics.zh-CN.md) |
+| Task 内记录如何引用？ | [局部身份](../task-local-identity.zh-CN.md) |
+| Role、Profile 与运行配置如何生效？ | [角色与配置](../roles-and-configuration.zh-CN.md) |
+| 怎样交付、集成和归档？ | [交付生命周期](../task-delivery.zh-CN.md) |
+| Provider、ACP 与配置事实如何接入？ | [Provider Runtime](../provider-runtime.zh-CN.md) |
+| 运行观察和错误由谁解释？ | [Agent Drivers](../agent-runtime-drivers.zh-CN.md) |
+| 如何创建、验证与采用插件？ | [插件 SDK](../plugin-sdk.zh-CN.md) |
+| 数据、升级与并发的边界是什么？ | [SQLite Store](../sqlite-control-plane-design.zh-CN.md) |
+| 如何执行获授权的发布操作？ | [发布流程](../release-workflow.zh-CN.md) |
+| 如何查看当前运行证据？ | [可观察性](../observability/README.zh-CN.md) |
+| 哪些验证应长期保留？ | [验证策略](../testing/verification-levels.zh-CN.md) |
+
+## 维护约定
+
+行为变更同步修改所属合同和必要的入口说明。具体 CLI 参数以
+`src/cli/commandCatalog.ts` 和命令处理器为准；公开领域类型以运行源码为准，
+不另外维护一套目标模型或生成的离线副本。
+
+每篇文档保持中英双语：`X.md` 为英文，`X.zh-CN.md` 为对应中文。行为变更时
+一并更新两种语言版本，保持内容一致。
+
+Project Skill 管理 Yui 的开发与验证规则；通用 Role Skills 管理 Agent 使用
+Yui 的职责。仓库文档不替代 `YUI_HOME` 中维护的 Project Knowledge，也不授予
+共享环境、真实模型或外部系统的执行权限。

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

@@ -0,0 +1,118 @@
+<p align="right"><strong>English</strong> | <a href="./capabilities-and-resources.zh-CN.md">简体中文</a></p>
+
+# Capabilities, resources and Surfaces
+
+## One ingress, original facts
+
+The Controller hosts the CapabilityRegistry and InstanceHost. `capability
+search`, `describe` and `call` use one authenticated ingress: it first resolves
+the current Session identity and Task scope, then checks capability and resource
+permissions. An actor supplied in the input, or a self-declared user scope,
+cannot grant permission.
+
+A descriptor carries its name, contract version, Provider, scope, input/output
+schema, effect and requiredPermissions. A query shows only the authorized
+catalog; when a Provider or version is ambiguous, the caller selects explicitly
+rather than relying on load order. The schema is a bounded dialect, and unknown
+keywords are rejected.
+
+The current catalog covers context, message, artifact, environment, resource,
+project, plugin and selected task/job operations. Task lifecycle and some CLI/Web
+writes share domain commands directly; these are not a second business state and
+do not pretend to have run through the Registry.
+
+## Effects and operation facts
+
+A capability's return value is separate from its real effect. A call can produce
+a confirmed sub-operation even when its output validation fails, so the returned
+result must preserve the original owner's operationRef and receipt. Unknown must
+not be read as "did not run," and there is no automatic fallback.
+
+A nested call rechecks current permissions and cannot widen the permissions or
+effect the parent call declared. A requestId identifies the call; it does not
+supply universal idempotency for every downstream operation — an owner such as a
+Job runs its own exact idempotency contract. After an error, read the original
+operation facts before deciding the next step.
+
+## Implementation instances
+
+InstanceHost manages attach, acquire, release, detach and the actual references.
+After a replacement is published, new calls select the new implementation while
+existing references stay bound to the original one and can be disposed only once
+drained. A query is an observation; it does not start or recover code. A cleanup
+failure keeps its diagnosis, does not reverse a new publication into a failure,
+and does not fake a drain.
+
+A Session's long-lived reference is pinned by the actual AgentHost to the
+implementation it loaded. The Controller carries an existing pin forward and does
+not silently move a live Session onto different code. Ending a client and the
+shared Provider's physical quiescence are judged separately.
+
+## Projects and workspaces
+
+A Project stores its reference checkout, Knowledge and resource references. The
+stable checkout is read-only; Task delivery happens in a managed worktree. A
+multi-Project Task uses independent Git roots and explicit write scopes. A
+workspace owner is a Task, WorkItem, ReviewRound or IntegrationAttempt. A Role
+only selects execution configuration; it does not independently own a separate
+workspace state.
+
+Git integration captures an exact ChangeSet and advances the target by
+compare-and-swap after its checks pass in a candidate worktree. A conflict,
+failed check, moved target or rejection never advances the target, and the Agent
+chooses the next action.
+
+## Artifacts and environments
+
+- `artifact.save/read/list` maintains file/directory deliverables — complete
+  plans, prototypes, charts, reports — in the Task's own local-only Git
+  repository. `save` writes a `relativePath` and commits exactly that path,
+  returning a self-certifying `commit + relativePath` reference; `read` resolves
+  HEAD or a pinned commit for frozen evidence; `list` is an ordinary current
+  read. A reference is not a fixed delivery result; a final result cannot select
+  a missing or cross-Task artifact.
+- `environment.prepare` prepares an empty, scratch or authorized local directory
+  without adopting it automatically.
+- `environment.adopt` rechecks identity, resource intent, permissions and
+  conflicts, then records ownership.
+- `environment.bind` selects a Role's next native execution environment; `null`
+  returns to the managed workspace.
+- `environment.release` checks the real references and quiescence evidence and
+  never deletes a user directory.
+
+An adopted native launch retains the directory's identity, access, isolation and
+preparation reference, and rechecks them at launch, resume and the Yui input
+boundary. Revoking a grant cannot silently re-adopt an old environment on the
+strength of a new grant. Read-only environment support depends on the adapter; a
+directory access label is not a general OS sandbox.
+
+## Plugins and self-extension
+
+A Task Leader or the global Operator can manage that Task's plugins; a
+Worker/Reviewer cannot self-manage or self-trust them. A declarative plugin runs
+no arbitrary code; executing a trusted-local plugin additionally requires a grant
+scoped to the exact source or artifact digest, environment and phase.
+
+The Store keeps the enabled intent and validation artifacts, and the Host keeps
+the actual instances. After a restart the enabled selection is still readable,
+the actual instance can be empty, and activation must be explicit. The original
+Task can discover and call the new capability without rewriting its own native
+tool schema. A business result should be saved as an Artifact rather than
+depending on the plugin staying alive.
+
+See the [Plugin SDK](../plugin-sdk.md) for the full authoring, authorization and
+failure contract.
+
+## CLI and Web
+
+A Surface contribution is derived from the Registry's currently authorized
+catalog; there is no second catalog or Host. A CLI contribution uses the
+capability's original name. A Web panel accepts only controlled text, an HTTP(S)
+link or a JSON query description — not author scripts or arbitrary HTML.
+
+The Web listener is started and stopped by the Controller and allows loopback
+only. A browser write goes through an existing domain transaction, and its error
+distinguishes a definite non-commit from a committed-but-unknown result. A query
+panel cannot use the browser's identity to run a mutation or manage plugins. A
+terminal connection only attaches a client; it does not take over durable
+ownership of the native conversation.

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

@@ -0,0 +1,83 @@
+<p align="right"><a href="./capabilities-and-resources.md">English</a> | <strong>简体中文</strong></p>
+
+# 能力、资源与 Surface
+
+## 唯一入口与原始事实
+
+Controller 承载 CapabilityRegistry 和 InstanceHost。`capability search`、
+`describe`、`call` 使用同一认证入口，先解析当前 Session 身份和 Task 范围，
+再检查能力与资源权限。输入中的 actor 或自称的 user scope 不能授予权限。
+
+描述符包含名称、合同版本、Provider、scope、输入输出 schema、effect 和
+requiredPermissions。查询只展示获授权的目录；同名 Provider 或版本有歧义时，
+调用者明确选择，不按加载顺序决定。Schema 是有界方言，未知关键词拒绝。
+
+当前目录覆盖 context、message、artifact、environment、resource、project、
+plugin 和部分 task/job 操作。Task 生命周期与部分 CLI/Web 写入直接共享
+领域命令；这些不是另一份业务状态，也不假称已经通过 Registry 执行。
+
+## 效果与操作事实
+
+能力返回值与真实效果分开。一次调用即使输出校验失败，也可能已产生确认的
+子操作；返回结果必须保留原 owner 的 operationRef 和 receipt。Unknown
+不能解释为未执行，不进行自动 fallback。
+
+嵌套调用重新检查当前权限，不能扩大父调用声明的权限与效果。requestId 标识
+调用，不自动提供所有业务的通用幂等性；Job 等 owner 执行自己的精确幂等合同。
+错误后先读取原操作事实再决定下一步。
+
+## 实现实例
+
+InstanceHost 管理 attach、acquire、release、detach 与实际引用。替换发布后，
+新调用选择新实现；已有引用继续绑定原实现，排空后才能 dispose。查询是观察，
+不启动或恢复代码。清理失败保留诊断，不把新发布反转为失败，也不伪造排空。
+
+Session 的长引用由实际 AgentHost 固定到所加载实现。Controller 传递已有 pin，
+不把活 Session 静默搬到另一份代码。结束客户端与共享 Provider 物理静止分别判断。
+
+## Project 与工作区
+
+Project 保存参考 checkout、Knowledge 与资源引用。稳定 checkout 只读；Task
+交付发生在受管 worktree。多 Project Task 使用独立 Git 根和明确写范围。
+工作区 owner 属于 Task、WorkItem、ReviewRound 或 IntegrationAttempt。
+Role 仅选择执行配置，不独立拥有另一份工作区状态。
+
+Git 集成捕获精确 ChangeSet，在候选 worktree 检查后 CAS 推进目标。
+冲突、检查失败、目标移动与拒绝都不更新目标，Agent 决定下一次操作。
+
+## Artifact 与环境
+
+- `artifact.save/read/list` 在 Task 自有的本地专用 Git 仓库中维护文件/目录交付物
+  （完整方案、原型、图表、报告）。`save` 写入 `relativePath` 并只提交该路径，
+  返回自证的 `commit + relativePath` 引用；`read` 解析 HEAD 或固定 commit 以取冻结证据；
+  `list` 为普通当前读取。Reference 不等于固定交付成果；最终结果不能选择缺失或跨 Task Artifact。
+- `environment.prepare` 准备 empty、scratch 或获授权 local 目录，不自动采用。
+- `environment.adopt` 复核身份、资源意图、权限与冲突后保存所有权。
+- `environment.bind` 选择 Role 下一次原生执行环境；`null` 返回 managed workspace。
+- `environment.release` 检查真实引用和静止证据，不删除用户目录。
+
+Adopted native launch 保留目录身份、access、isolation 与 preparation 引用，
+在 launch、resume 和 Yui 输入边界复核。撤权不能靠新 grant 静默重新采用旧环境。
+Read-only 环境的支持取决于实现；不能将目录 access 标签视为通用 OS 沙箱。
+
+## 插件与自扩展
+
+Task Leader 或 global Operator 可以管理该 Task 的插件；Worker/Reviewer 不能
+自行管理或授信。声明式插件不执行任意代码；trusted-local 插件执行还需要精确
+源码或产物摘要、环境和阶段的 grant。
+
+Store 保存 enabled 意图及验证产物，Host 保存实际实例。重启后 enabled 仍可读，
+actual 可以为空，必须显式激活。原 Task 可以发现并调用新能力，不必修改自身
+原生工具 schema。业务结果应保存为 Artifact，而不是依赖插件继续存活。
+
+完整作者、授权及失败合同见[插件 SDK](../plugin-sdk.zh-CN.md)。
+
+## CLI 与 Web
+
+Surface contribution 由 Registry 当前获授权目录派生，没有第二份目录或 Host。
+CLI contribution 使用能力原名称。Web panel 只接受受控 text、HTTP(S) link 或
+JSON query 描述，不接受作者脚本或任意 HTML。
+
+Web listener 由 Controller 启停，仅允许 loopback。浏览器写入通过现有领域
+事务，错误区分确定未提交与提交结果未知。查询面板不能借浏览器身份执行 mutation
+或插件管理。终端连接只 attach 客户端，不接管原生对话的持久所有权。

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

@@ -0,0 +1,224 @@
+<p align="right"><strong>English</strong> | <a href="./managed-turn-and-session-runtime.zh-CN.md">简体中文</a></p>
+
+# Session, AgentRun and notifications
+
+## Authority
+
+Task, WorkItem, Message, Decision, Artifact and Project Knowledge preserve
+durable work. Session identifies a native conversation and its captured
+authority. AgentRun records an explicitly requested execution and original
+result. AgentHost is a disposable attachment, not the owner of Task truth.
+
+A current, non-revoked Leader Session can read Context and save scoped Task
+facts, including a formal InputRequest, without an active Run. Its exact
+Session is the request's origin; an actual Run is included when present.
+The question survives that execution ending and remains open until answered
+or cancelled. Worker and Reviewer commands retain exact
+Assignment checks. Session replacement, Role binding, Task scope and resource
+grants are checked at their respective boundaries. An active Run pointer is not
+proof that an unrelated command in the same Session came from that Run.
+
+Native chat, Goal continuations and ordinary Leader notifications do not
+automatically create Runs. Explicit dispatch loads one exact Run Context Pack.
+
+## Context
+
+```sh
+yui task context <task> --json
+yui task context delta <task> --after <coreCursor>
+yui task context inspect <task> --store <store> --ref <id>
+yui task run context <task/run> --json
+```
+
+Task Context is a bounded authorized working set with a current core cursor.
+Delta pages immutable events through a fixed upper bound; inspect expands a
+current record and can require an exact digest. Runtime observations state their
+own coverage and do not become another durable snapshot.
+
+Run Context freezes Assignment, source references, effective configuration and
+workspace boundaries. A Role edit does not rewrite an existing Assignment.
+Reading either Context does not acknowledge input or create execution authority.
+Every managed input points to the exact Session Manifest and CLI entry. The
+Run Pack is a reference directory: read the relevant requirement and message
+bodies before acting, rather than treating a successful load as the deliverable.
+Planning Packs expose no Project write scope or Task-completion permission.
+
+Current Task reads also expose untargeted user/Operator messages to the Task's
+current Worker and Reviewer Sessions, including requirements added after their
+Run snapshot was frozen. Use `task message list/show` or Task Context inspect
+to read those original records. This does not rewrite the frozen Assignment or
+grant delivery authority. Directed messages, other Roles' results and other
+Tasks remain outside the caller's scope unless its Assignment authorizes them.
+
+## Dispatch and notification
+
+An explicit dispatch persists execution intent before native submission.
+Ordinary Leader wake instead claims a fixed TaskWake/mailbox batch and submits
+a notification through the same Host/Endpoint. Confirmed acceptance consumes
+only that batch; later input remains pending. A notification requires no final
+execution report and does not force steer into a busy native conversation.
+
+Leader-local edits preserve durable events but do not create self-wakes.
+Other sources' input remains durable while the Leader is busy or unavailable.
+Operator notifications likewise carry TaskEvent/InputRequest read pointers,
+not duplicated Task narrative.
+Human input, explicit execution entry and activation failure are delivered
+promptly through the existing wake mechanism. Worker results retain their
+aggregation window. Busy native input still preserves pending messages.
+
+| Evidence | Disposition |
+| --- | --- |
+| Busy with proven non-acceptance | Preserve input; a new transport attempt may use the same Session |
+| Native acceptance | Never resend; wait for the exact terminal if this is an execution |
+| Transport write only | Retain transport evidence; do not claim native acceptance |
+| Explicit rejection | Retain the original cause and settle the corresponding admission |
+| Unknown acceptance/effect | Retain the attempt and conflicting-resource fences; do not replay or switch Session |
+
+Missing receipt after a crash is not proof of non-acceptance. Structured
+`SESSION_BUSY` is evidence; text containing “busy” is not a retry contract.
+
+## Continue existing work
+
+```sh
+yui task message send <task> "Continue with the clarified requirement" \
+  --to <role> --work-item <work-item>
+yui task message handoff <task/message> --to <successor-role>
+```
+
+Review clarification uses `--review-round` instead of `--work-item`.
+Message retains recipient, work association and owner Run. When the Role is
+busy, saving returns without interrupting it. Once it becomes available, a
+bounded ordered batch can create a continuation Run atomically associated with
+those messages. The existing Assignment, effective permissions, workspace and
+unfinished files remain; the snapshot adds authorized messages and the preceding
+original result. Duplicate terminals cannot assign the messages twice.
+
+Ownership changes, incompatible Sessions, terminal work and obsolete Review
+candidates retain visible nondelivery reasons. Explicit handoff only targets an
+already-dispatched successor for the same work. Replicated Producer/synthesis
+lineage is not silently rewritten by a message.
+
+Unknown Leader notifications preserve their wake and input window:
+
+```sh
+yui task wake show <task> <wake>
+yui task wake resolve <task> <wake> --reason <quiescence-evidence>
+```
+
+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.
+
+## Exact results
+
+The native terminal settles only the matching execution. Known native Turn IDs
+must match; a serialized stream may use proven local attempt correlation.
+Message UUIDs are not native Turn IDs. Unrelated native chat in the same Session
+cannot complete the pending Yui request.
+
+The terminal transaction saves one AgentRunResult and a reference Message.
+`resultRef: { type: "agent-run-result", runId: "run-12" }` expands the original
+report rather than copying it. Candidate and ReviewRound retain provenance;
+Core does not derive semantic acceptance from prose.
+
+Cancellation requests do not prove physical quiescence. Exact terminal evidence
+preserves partial output and settles the original execution only. Host exit
+does not imply shared Provider or descendant processes have stopped.
+
+## Draft planning and activation
+
+`EffectiveLaunchSnapshot.executionAuthority` captures `planning | delivery`.
+It is not recalculated from the Task's current lifecycle. Planning permits
+local planning facts, not delivery dispatch, candidate adoption, integration or
+delivery workspace Jobs.
+
+The initial Draft planning dispatch creates a planning Run and binds only its
+initial message batch. Acceptance or an exact terminal consumes that batch;
+failure does not repeatedly recreate the same planning execution. Subsequent ordinary
+messages in the existing planning Session remain notifications. Operator submit
+and direct Task messages both reach that Session. Draft plan/WorkItem edits
+preserve execution history; external edits notify the Leader, while its own
+planning edits do not create a self-wake.
+
+New Draft Roles use a Task-specific planning directory under
+`<YUI_HOME>.task-runtimes/planning`, outside the control Home and delivery trees.
+A planning Run can use `task activation request` to persist intent and return an
+`afterPlanningRun` reference immediately. Its terminal releases the request for
+Controller admission; cancelled intent is not resurrected.
+The Leader can also request activation during ordinary discussion without an
+AgentRun: the Controller adopts its durable intent once the native input is
+settled. No synthetic Run or extra user “continue” is required.
+
+For bound Git Projects, `--environment empty` means no additional environment:
+the Projects still receive managed worktrees. `scratch` selects a Task-owned
+directory. `local` requires a registered local Resource and its grant; a Project
+ID is not a local Resource ID.
+
+Resource preparation precedes the atomic adoption of Task status and workspace
+ownership. A failed adoption records a failed request and notifies the Leader
+with durable facts; it does not repeatedly prepare resources on unchanged
+failure. The Leader chooses an explicit retry or corrected request. Successful
+activation likewise leaves a delivery notification for the Leader.
+Activation never mutates the live Session into delivery authority. A changed
+launch must pass the existing Session replacement/environment boundary.
+Planning authority is a CLI guarantee, not a hostile-code filesystem sandbox.
+
+## Inspection and lifecycle
+
+```sh
+yui task run list <task>
+yui task run show <task/run> --json
+yui task message show <task/message>
+yui task role session inspect <task> <role>
+yui task execution start <task>
+yui task execution stop <task> --force --reason <reason>
+```
+
+Task execution start/stop controls Task admission, not Task acceptance.
+Stop first fences new Yui work, then interrupts each exact owned native input
+and confirms its terminal before removing the attachment. This also covers
+ordinary Leader notifications without Runs. Unknown native state blocks cleanup;
+stopping a proxy alone never proves a shared Turn ended. Start preserves durable
+progress and admits new input after the old occupancy is settled.
+Draft planning can be paused/resumed, and a failed planning Run retries with
+planning authority. An authorized user/Operator can stop an idle Draft Session
+through `task role session stop`; it need not activate the Task merely to recover.
+`task role session new <task> <role> --reason <reason>` persists an explicit
+replacement request. Reuse is a preference, not a requirement to prove the old
+conversation unrecoverable. The request is legal while an AgentRun is active,
+the Session is ended, or previous cleanup is pending. A Leader may also request
+its own replacement and end its current turn.
+
+`task role session stop` can also stop a running Role without first changing
+its Run status. It retains the native conversation for possible reuse. Pending
+Messages remain intent and may start a continuation after the stop; use Task
+execution stop when the whole Task must remain paused. For self-replacement,
+use the asynchronous `session new` request rather than a synchronous self-stop.
+
+The existing runtime cleanup path stops the exact native execution, closes this
+Role's remaining engineering attempts as cancelled, retains Session/Run history
+and workspaces, and selects a fresh conversation. Other Roles and Task acceptance
+remain unchanged. The Leader receives a new context notification; it decides
+which Worker/Reviewer attempts to retry. Pending input references survive the
+replacement, including records older than the new notification's time window.
+
+An absent Host does not remove the recovery entry point. Codex can be inspected
+and interrupted through a disposable native control connection without starting
+a model. Dedicated Claude process custody is persisted independently of the
+Host. Real unconfirmed execution still prevents conflicting resource reuse;
+cleanup failure is a durable diagnostic routed to the supervisor, not a reason
+to invent acceptance or delete the Task. A preallocated ID alone is not proof
+a conversation exists.
+Codex may retain `systemError` after a failed native Turn. That label alone
+neither proves activity nor authorizes cleanup: Yui checks the latest native
+Turn's terminal metadata and drains background execution before replacing the
+Session. Unknown or still-running native work remains protected.
+
+Released Leaders retain scoped diagnostic reads of their own Task and context,
+but cannot mutate it or read another Task. Operator diagnostics and Controller
+restart do not first require a healthy Controller; explicit restart can stop
+only the exact same-Home process using PID/start identity when RPC is unavailable.
+Operator storage diagnosis/upgrade also reaches the dedicated migration entry
+without first requiring the Home to already have the target storage version.
+Completion, cancellation and archive have distinct authority and resource
+boundaries. Storage changes use the single [upgrade contract](sqlite-control-plane-design.md).