@zq-silk/yui 0.15.11 → 0.16.0

package/dist/workspace/workItemChangeSetManager.js

@@ -1,5 +1,6 @@
 import { isDeepStrictEqual } from "node:util";
-import { lstat } from "node:fs/promises";
+import { lstat, realpath } from "node:fs/promises";
+import { join } from "node:path";
 import { createWorkItemChangeSet } from "../integration/changeSet.js";
 import { createChangeSetManifest } from "../integration/changeSetManifest.js";
 import { deriveManifestTags } from "../integration/manifestTags.js";
@@ -8,6 +9,7 @@ import { sameTaskFinalReviewContract } from "../review/taskFinalReviewContract.j
 import { governingWorkItemCandidate } from "../workItem/workItem.js";
 import { managedWorkspaceKey } from "../worktree/managedWorkspace.js";
 import { captureManagedGitChanges } from "./gitChangeSetCapture.js";
+import { CleanupInspectionError, cleanupCheckFromError, workspacePathValue } from "./cleanupInspection.js";
 const CAPTURABLE_WORK_ITEM_STATUSES = new Set([
     "open",
     "accepted",
@@ -45,6 +47,12 @@ export class WorkItemChangeSetManager {
         return captured;
     }
     async assertIntegrated(taskId, workItemId, candidateId) {
+        const inspection = await this.inspectIntegrated(taskId, workItemId, candidateId);
+        if (inspection.checks.length > 0)
+            throw new CleanupInspectionError(inspection.checks);
+        return inspection.proof;
+    }
+    async inspectIntegrated(taskId, workItemId, candidateId) {
         const item = this.store.getWorkItem(taskId, workItemId);
         if (item === null)
             throw new Error(`Work item not found: ${taskId}/${workItemId}.`);
@@ -54,62 +62,114 @@ export class WorkItemChangeSetManager {
             throw new Error(`Candidate not found: ${taskId}/${workItemId}/${candidateId}.`);
         }
         const workspace = this.store.getWorkItemWorkspace(item.taskId, item.id);
-        if (workspace === null
-            || workspace.owner.type !== "work-item"
-            || workspace.owner.workItemId !== item.id)
-            return null;
+        if (workspace === null)
+            return { proof: null, checks: [] };
         const git = new NodeGitWorkspace();
         const projects = [];
-        for (const entry of writableEntries(workspace)) {
-            const path = await lstat(entry.path).catch(error => {
-                if (error.code === "ENOENT")
-                    return null;
-                throw error;
-            });
-            if (path?.isSymbolicLink())
-                throw new Error(`WorkItem path is a symbolic link: ${entry.path}.`);
-            if (path !== null && !await git.isClean(entry.path)) {
-                throw new Error(`WorkItem Project workspace is not clean: ${item.id}/${entry.projectId}.`);
+        const checks = [];
+        const sources = [`work-item:${taskId}/${workItemId}`,
+            `candidate:${taskId}/${workItemId}/${candidate?.id ?? "missing"}`, managedWorkspaceKey(workspace.owner)];
+        const actions = [`yui task work show ${taskId}/${workItemId}`, `yui task integration list ${taskId}`];
+        const add = (resource, reason, detail, expected, observed) => {
+            checks.push({ resource, reason, detail, expected, observed, status: "blocked", sources, actions });
+        };
+        const resource = `work-item:${taskId}/${workItemId}`;
+        if (workspace.owner.type !== "work-item" || workspace.owner.taskId !== taskId || workspace.owner.workItemId !== item.id) {
+            add(resource, "workspace-identity-mismatch", "Managed workspace is not owned by this WorkItem.", { type: "work-item", taskId, workItemId }, "different owner");
+            return { proof: null, checks };
+        }
+        if (candidate?.workspace === undefined) {
+            add(resource, "candidate-workspace-missing", "The governing Candidate has no frozen workspace.", "frozen WorkItem workspace", null);
+        }
+        else if (!isDeepStrictEqual(candidate.workspace, workspace)) {
+            const frozen = candidate.workspace;
+            if (!isDeepStrictEqual(frozen.owner, workspace.owner)) {
+                add(resource, "workspace-identity-mismatch", "Frozen and current workspace owners differ.", frozen.owner, workspace.owner);
+            }
+            // Paths remain frozen evidence. A path-shaped difference alone is NOT a
+            // receipt proving that migration moved this exact Candidate safely.
+            if (frozen.root !== workspace.root) {
+                add(resource, "workspace-path-mismatch", "Workspace roots differ; relocation is not proven.", workspacePathValue(workspace, frozen.root), workspacePathValue(workspace, workspace.root));
+            }
+            if (!isDeepStrictEqual(frozen.entries.map(e => e.projectId), workspace.entries.map(e => e.projectId))) {
+                add(resource, "workspace-identity-mismatch", "Frozen and current Project scope/order differ.", frozen.entries.map(e => e.projectId), workspace.entries.map(e => e.projectId));
+            }
+            for (const entry of workspace.entries) {
+                const previous = frozen.entries.find(e => e.projectId === entry.projectId);
+                if (previous === undefined)
+                    continue;
+                const entryResource = `${resource}/${entry.projectId}`;
+                if (previous.path !== entry.path) {
+                    add(entryResource, "workspace-path-mismatch", "Frozen and current Project paths differ; no relocation receipt is available. Historical evidence is unchanged.", workspacePathValue(workspace, previous.path), workspacePathValue(workspace, entry.path));
+                }
+                for (const key of ["directory", "access", "branch", "baseRef", "baseCommit"]) {
+                    if (previous[key] !== entry[key])
+                        add(entryResource, "workspace-identity-mismatch", `Frozen and current ${key} differ.`, { [key]: previous[key] }, { [key]: entry[key] });
+                }
+            }
+            for (const key of ["schemaVersion", "createdAt", "updatedAt"]) {
+                if (frozen[key] !== workspace[key])
+                    add(resource, "workspace-metadata-mismatch", `Frozen and current ${key} differ.`, { [key]: frozen[key] }, { [key]: workspace[key] });
             }
+        }
+        for (const entry of writableEntries(workspace)) {
+            const projectResource = `${resource}/${entry.projectId}`;
             const resultCommit = candidate?.gitSnapshot?.projects.find(({ projectId }) => projectId === entry.projectId)?.commit;
-            // Absence is a filesystem fact, not proof of integration or Git cleanup.
-            // Check any retained branch against the same frozen Candidate; the
-            // cleanup primitive separately removes its exact Git registration.
-            const repository = this.store.getTaskWorkspace(taskId)?.entries.find(e => e.projectId === entry.projectId);
-            const workspaceHeadCommit = path !== null ? (await git.inspect(entry.path, "HEAD")).baseCommit
-                : repository !== undefined && await git.refExists(repository.path, entry.branch)
-                    ? (await git.inspect(repository.path, entry.branch)).baseCommit
-                    : resultCommit;
-            if (candidate?.workspace === undefined
-                || !isDeepStrictEqual(candidate.workspace, workspace)
-                || resultCommit === undefined
-                || (candidateId === undefined && resultCommit !== workspaceHeadCommit)) {
-                throw new Error(`WorkItem Project no longer matches its frozen result: ${item.id}/${entry.projectId}.`);
+            if (resultCommit === undefined)
+                add(projectResource, "frozen-commit-missing", "The governing Candidate has no frozen Project commit.", "frozen commit", null);
+            if (resultCommit !== undefined) {
+                // An explicit historical selection is proved against its immutable
+                // integrated commit, not mislabeled as the workspace's current HEAD.
+                const integrated = this.store.listIntegrationAttempts(item.taskId).some(integration => integration.status === "committed"
+                    && integration.projectId === entry.projectId
+                    && integration.source.kind === "work-item"
+                    && integration.source.workItemId === item.id
+                    && integration.source.startCommit === entry.baseCommit
+                    && integration.source.resultCommit === resultCommit);
+                if (!integrated) {
+                    add(projectResource, "result-not-integrated", "WorkItem result is not integrated.", { baseCommit: entry.baseCommit, resultCommit }, "no committed Integration with these exact commits");
+                }
+                projects.push({ projectId: entry.projectId, baseCommit: entry.baseCommit, headCommit: resultCommit });
             }
-            // An explicit historical selection is proved against its immutable
-            // integrated commit, not mislabeled as the workspace's current HEAD.
-            const headCommit = resultCommit;
-            const integrated = this.store.listIntegrationAttempts(item.taskId).some((integration) => (integration.status === "committed"
-                && integration.projectId === entry.projectId
-                && integration.source.kind === "work-item"
-                && integration.source.workItemId === item.id
-                && integration.source.startCommit === entry.baseCommit
-                && integration.source.resultCommit === headCommit));
-            if (!integrated) {
-                throw new Error(`WorkItem result is not integrated: ${item.id}/${entry.projectId}.`);
+            if (entry.path !== join(workspace.root, entry.directory)) {
+                add(projectResource, "workspace-path-mismatch", "Current path differs from the exact owner-root/Project location.", workspacePathValue(workspace, join(workspace.root, entry.directory)), workspacePathValue(workspace, entry.path));
+                continue;
+            }
+            try {
+                const path = await lstat(entry.path).catch(error => {
+                    if (error.code === "ENOENT")
+                        return null;
+                    throw error;
+                });
+                if (path !== null && (path.isSymbolicLink() || await realpath(entry.path) !== entry.path)) {
+                    add(projectResource, "workspace-identity-mismatch", "WorkItem path resolves through a symbolic link.", "real owned directory", "symbolic link");
+                    continue;
+                }
+                // Absence is a filesystem fact, not proof of integration or Git cleanup.
+                // Check any retained branch against the same frozen Candidate; the
+                // cleanup primitive separately removes its exact Git registration.
+                const repository = this.store.getTaskWorkspace(taskId)?.entries.find(e => e.projectId === entry.projectId);
+                const workspaceHeadCommit = path !== null ? (await git.inspect(entry.path, "HEAD")).baseCommit
+                    : repository !== undefined && await git.refExists(repository.path, entry.branch)
+                        ? (await git.inspect(repository.path, entry.branch)).baseCommit
+                        : resultCommit;
+                if (candidateId === undefined && resultCommit !== undefined && resultCommit !== workspaceHeadCommit) {
+                    add(projectResource, "head-mismatch", "Current HEAD no longer matches the frozen result.", resultCommit, workspaceHeadCommit ?? null);
+                }
+                if (path !== null && !await git.inspectClean(entry.path)) {
+                    add(projectResource, "dirty-worktree", "WorkItem Project workspace is not clean.", "clean", "dirty");
+                }
+            }
+            catch (error) {
+                checks.push(...cleanupCheckFromError(error, projectResource, sources, actions));
             }
-            projects.push({
-                projectId: entry.projectId,
-                baseCommit: entry.baseCommit,
-                headCommit
-            });
         }
-        return {
-            workItemId: item.id,
-            ...(item.assignee === undefined ? {} : { assignee: item.assignee }),
-            workspace,
-            projects
-        };
+        return { checks, proof: checks.length > 0 ? null : {
+                workItemId: item.id,
+                ...(item.assignee === undefined ? {} : { assignee: item.assignee }),
+                workspace,
+                projects
+            } };
     }
     /**
      * Fail-closed proof that retiring the aggregate will not hide unrecorded Git

package/docs/agent-result-consumption.md

@@ -2,6 +2,10 @@
 
 # Agent result consumption
 
+For candidate discovery before reading original results, use the
+[bounded Task catalog](task-discovery.md). A catalog summary never replaces a
+requirement or the original result.
+
 Every explicitly dispatched AgentRun produces one durable original result.
 Ordinary notification and native conversation do not implicitly create Runs.
 The next Agent in the ownership chain reads the exact result and decides what

package/docs/agent-result-consumption.zh-CN.md

@@ -2,6 +2,9 @@
 
 # Agent 结果消费
 
+读取原始结果前，可用[有界 Task 目录](task-discovery.zh-CN.md)发现候选任务。
+目录摘要不替代需求正文或原始结果。
+
 每一次显式派发的 AgentRun 都产生一个持久的原始结果。普通通知和原生对话不会
 隐式创建 Run。所有权链上的下一个 Agent 读取这个精确结果并判断它意味着什么。
 

package/docs/agent-runtime-drivers.md

@@ -67,6 +67,13 @@ than guessed. Incremental observers report health and coverage; sampling does
 not block lifecycle events. Metrics never trigger model selection, wake, retry,
 resource release or acceptance.
 
+[Task usage and time](observability/README.md#task-usage-and-time) reuse this
+reducer across historical Sessions. Task-fenced observations are not a billing
+completeness guarantee. Native child counters are excluded from parent Session
+totals without an explicit non-overlap contract; they are never extra requests.
+Raw cumulative Session counters and safely attributable Task increments remain
+distinct, and only exact request/Run bindings support WorkItem allocation.
+
 ## Native children
 
 Native subagents are collaboration inside a parent conversation, not Yui Roles,

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

@@ -56,6 +56,11 @@ Task 完成。
 和覆盖度；采样不阻塞生命周期事件。度量绝不触发模型选择、唤醒、重试、资源释放
 或接受。
 
+[Task 用量与耗时](observability/README.zh-CN.md#task-用量与耗时)跨历史 Session
+复用此 reducer。Task 围栏内的观察不是完整账单保证。缺少明确互斥合同时，原生
+子计数不加入父 Session 总量，也不作为额外请求。原始 Session 累计值与安全归属
+的 Task 增量分开；仅精确请求/Run 绑定支持 WorkItem 分配。
+
 ## 原生子代
 
 原生 subagent 是父对话内部的协作，不是 Yui Role、Lane 或独立的受管工作区 owner。

package/docs/architecture/README.md

@@ -20,11 +20,13 @@ not a claim that every real Provider scenario has been validated.
 | Question | Current document |
 | --- | --- |
 | How do Session, AgentRun, messages and activation fit together? | [Session and AgentRun runtime](../managed-turn-and-session-runtime.md) |
+| What can Web control, and how do queue, steer and interrupt differ? | [Web permissions](capabilities-and-resources.md#cli-and-web) · [Input timing](../managed-turn-and-session-runtime.md#input-timing-queue-steer-and-interrupt) |
 | 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) |
+| What does Project refresh synchronize, and how are partial failures reported? | [Project refresh](../project-refresh.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) |

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

@@ -8,7 +8,7 @@
 
 - [English README](../../README.md)：安装、配置和日常使用。
 - [中文 README](../../i18n/README.zh-CN.md)：同一产品入口的中文说明。
-- [总体架构](../../ARCHITECTURE.md)：职责、权威和端到端流程（英文）。
+- [总体架构](../../ARCHITECTURE.zh-CN.md)：职责、权威和端到端流程。
 - [能力、资源与 Surface](capabilities-and-resources.zh-CN.md)：扩展入口、实例所有权和资源效果。
 
 ## 领域合同
@@ -16,11 +16,13 @@
 | 问题 | 当前文档 |
 | --- | --- |
 | Session、AgentRun、消息和激活如何配合？ | [执行与会话](../managed-turn-and-session-runtime.zh-CN.md) |
+| Web 可以控制什么，queue、steer 和 interrupt 有何区别？ | [Web 权限](capabilities-and-resources.zh-CN.md#cli-与-web) · [输入时机](../managed-turn-and-session-runtime.zh-CN.md#输入时机queuesteer-与-interrupt) |
 | 谁消费结果、综合与审查？ | [结果消费](../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) |
+| Project refresh 同步什么，怎样报告部分失败？ | [Project refresh](../project-refresh.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) |

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

@@ -105,14 +105,51 @@ failure contract.
 
 ## CLI and Web
 
+Ordinary Global CLI operations require the Role's current native Session;
+an old Manifest is a context pointer, not continuing write authority. Historical
+self-context reads and the explicit offline diagnostic/recovery routes remain
+available. Home configuration and resource-GC mutations belong to the user or
+current Operator, never a Task Worker. Configuration reads remain available.
+
+Managed Task commands cannot name a different Task. Independent Brief,
+Decision, Milestone, Event and Job reads share Context's readable references;
+an Assignment does not gain a wider view by selecting another query command.
+Job read RPCs carry an explicit caller, and the Controller enforces the scope.
+Current WorkItem Jobs remain visible to their assigned Worker.
+
 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.
+only (`127.0.0.1`, `::1` or `localhost`; default port 4173). `yui web` opens this
+local surface, not a remote multi-user service or an OS sandbox.
+
+The page supplies a token that authenticates all HTTP API reads and writes via
+`x-yui-web-token`; the server also checks the loopback Host. These controls act
+as the trusted local user, not a Role selected by the request body. They support
+Task metadata edits, messages, InputRequest answers, and explicit
+`queue / steer / interrupt` for Task or Global Roles. Managed Agent capability
+RPC retains its own Session authentication and scope; a browser token is not
+a way for an Agent or plugin to bypass those boundaries.
+
+Read-only dashboard, Context and query-panel projections remain separate from
+these mutations. A query panel cannot borrow the browser's user authority to
+mutate state or manage plugins. Task controls share the public CLI's domain
+commands; Global Role controls share the Global handler with
+`yui role message queue/steer` and `yui role interrupt`. Message submission intent
+(`record / discuss / develop`, default `discuss`) is
+separate from [input timing](../managed-turn-and-session-runtime.md#input-timing-queue-steer-and-interrupt).
+Transport acceptance does not establish implementation or Task acceptance.
+
+A browser write uses an existing domain transaction. Errors distinguish proven
+`not-submitted` from `unknown`, which can include an already-committed Message
+whose native delivery failed or is unconfirmed. Read the original Message,
+control receipt and current Session before choosing recovery; do not blindly
+resubmit under a new request ID or switch actions.
+
+A terminal WebSocket checks the token and same-origin handshake. It attaches a
+client without taking over durable conversation ownership, and respects the
+connection's `readOnly` flag. A terminal attachment is not a grant to control a
+different Session.

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

@@ -74,10 +74,40 @@ actual 可以为空，必须显式激活。原 Task 可以发现并调用新能
 
 ## CLI 与 Web
 
+普通 Global CLI 操作要求 Role 当前的原生 Session；旧 Manifest 只是 Context
+指针，不是持续写权限。历史 Session 的自身 Context 读取，以及明确的离线诊断、
+恢复入口仍可使用。Home 配置与资源 GC 修改属于用户或当前 Operator，不能由
+Task Worker 执行；配置读取保持可用。
+
+受管 Task 命令不能指定其他 Task。独立的 Brief、Decision、Milestone、Event
+和 Job 查询复用 Context 的可读引用，不能通过换查询入口扩大 Assignment
+视图。Job 读取 RPC 必须携带调用者，由 Controller 执行范围检查；
+Worker 仍可读取其当前 WorkItem 的 Job。
+
 Surface contribution 由 Registry 当前获授权目录派生，没有第二份目录或 Host。
 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 处理器，与 `yui role message queue/steer` 和 `yui role interrupt` 共用入口。消息提交意图
+（`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

@@ -98,6 +98,42 @@ 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.
 
+Rejected Leader notifications retain their original input and failure diagnosis.
+Deterministic startup failures do not automatically retry; only typed runtime
+contention remains deferred. New messages and a Controller restart do not replay
+the rejected claim. After correcting the cause, explicitly retry its exact wake:
+
+```sh
+yui task wake show <task> <wake>
+yui task wake retry <task> <wake> --reason "<what was corrected>"
+```
+
+Retry returns the rejected batch and later queued input to the existing mailbox;
+it does not rewrite the old wake as accepted or replace a Session. Current runtime
+authority and readiness checks still apply. Model/effort validation rejections show the
+native model options and a command to inspect the full current catalog.
+
+Pre-Run launch failures and native Provider rejections both retain a
+`runtime.agent-error` fact. Notification delivery references that original error
+instead of creating a second copy of the cause. `task event show` supplies the
+scoped capability-query pointer in both human and JSON output; `wake show`
+links the same fact. An unavailable Leader notifies the existing Operator
+channel once; Worker/Reviewer failures use the existing Leader channel. No new
+recovery Agent is started, and there need not be a Run or Session to record the
+failure.
+
+Storage 35→36 archives original historical error payloads and marks their
+unrecorded launch configuration as unavailable. It never reconstructs old model,
+account or settings choices from current Roles.
+
+Storage 36→37 narrows that context to native metadata selectors and the requested
+model/effort. Full old snapshots remain in migration audit, not in the active
+reader. Reading a failure's model options does not validate Task permissions,
+Review state, workspace entries or the current Session bootstrap protocol.
+The three failure ingresses retain their native fencing/classification, while
+record creation and deduplication share one writer and supervisor notices use
+the existing event-routing boundary.
+
 Unknown Leader notifications preserve their wake and input window:
 
 ```sh
@@ -109,6 +145,86 @@ 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.
 
+Wake status records notification delivery, not Message implementation. For
+ordinary Leader notifications, `consumed` means native acceptance. Native Turn
+completion and Task delivery need their own runtime evidence and durable results.
+A rejected wake stays `dispatched` with its claim until explicit retry or Session
+replacement; an explicitly released historical wake can remain `dispatched`
+without a claim. Unknown acceptance cannot use `wake retry`.
+Session replacement preserves queued input for a new wake and current Context;
+it does not retroactively mark an old wake accepted. Late receipts cannot settle
+the successor's batch. While Session cleanup is pending, new input remains queued.
+Inspect the wake, `notification.delivery` events, current mailbox and Session
+together; do not require one final response per historical wake.
+
+Current wakes are notification-only. Run completion cannot consume a wake, and
+the first notification window starts at Task creation. Retired Run-linked wake
+records remain in Task events with their original ID and payload, not as a
+second active wake format.
+
+## 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.
+Save-only input uses `message send --intent record`; `--wake-policy` is removed.
+Unkeyed Draft Message edits preserve submission intent. `record` and `develop`
+edits never start planning or create/retry activation; `discuss` edits use the
+same activation/planning routing as a discussion submission. A pending or failed
+activation therefore keeps the edited discussion waiting.
+
+A Message with a submission key, queue/steer request, or interrupt-then handoff
+has immutable content: submit a new Message with a new request ID to change it.
+This preserves the original retry comparison and receipt without adding a
+second stored representation of input. Updating to the identical body is a
+no-op, with no event, queue change or Controller notification. Current stored
+user/operator Messages always have an intent; changing that intent also requires
+a new explicit submission.
+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>
+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>]
+```
+
+Ordinary Leader `queue` input omits `--to`. An explicit `--to <role>` (including
+`leader`) addresses an existing Assignment and requires `--work-item` or
+`--review-round`; a Message cannot establish that Assignment. `steer` still
+requires an explicit Role and exact live target.
+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. The public CLI exposes
+`yui role message queue|steer <role> <text>` and `yui role interrupt <role>`.
+Queue/steer require `--request-id`; steer/interrupt require `--expected-target`.
+These commands retain the caller's existing Session authority; do not fabricate
+a Task/Run or borrow the browser's user authority. Configuration remains under
+`config role`, lifecycle under `session`. 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
@@ -141,7 +257,7 @@ 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.
+`<YUI_HOME>/runtime/task-runtimes/planning`, separate from durable control data 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.
@@ -154,6 +270,10 @@ 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.
 
+`task activate` is foreground adoption of an existing request, not an alternative
+way to create activation intent. A request-free Draft is rejected before resource
+preparation; the command does not invent an environment plan or request 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