@zq-silk/yui 0.15.11 → 0.15.12

package/dist/workspace/cleanupInspection.js

@@ -0,0 +1,63 @@
+import { isAbsolute, join, relative } from "node:path";
+export class CleanupInspectionError extends Error {
+    checks;
+    constructor(checks) {
+        super(checks.map(renderCleanupCheck).join("\n"));
+        this.checks = checks;
+        this.name = "CleanupInspectionError";
+    }
+}
+export function renderCleanupCheck(check) {
+    return `[${check.reason}] ${check.resource}: ${check.detail}`
+        + ` Expected=${JSON.stringify(check.expected)}; observed=${JSON.stringify(check.observed)}.`
+        + (check.actions.length === 0 ? "" : ` Inspect/resolve: ${check.actions.join("; ")}.`);
+}
+/** Do not forward arbitrary Git stderr, native arguments, or foreign paths. */
+export function cleanupCheckFromError(error, resource, sources, actions) {
+    if (error instanceof CleanupInspectionError) {
+        return error.checks.map(check => ({ ...check, resource, sources, actions }));
+    }
+    let cause = error;
+    let errorCode;
+    for (let depth = 0; depth < 4 && cause instanceof Error; depth += 1) {
+        const code = cause.code;
+        if ((typeof code === "string" && /^[A-Z][A-Z0-9_]{0,63}$/.test(code))
+            || (typeof code === "number" && Number.isSafeInteger(code))) {
+            errorCode = code;
+            break;
+        }
+        cause = cause.cause;
+    }
+    return [{ resource, reason: "inspection-unavailable", status: "unknown",
+            detail: "The resource could not be inspected; no safe cleanup conclusion is available.",
+            expected: "readable owned resource", observed: errorCode === undefined ? "unavailable" : { errorCode }, sources, actions }];
+}
+export function cleanupFailure(reason, detail, expected, observed, status = "blocked") {
+    throw new CleanupInspectionError([{ resource: "git-workspace", reason, status,
+            detail, expected, observed, sources: [], actions: [] }]);
+}
+/** Describe exact differences without disclosing paths outside this Task.
+ * Legacy locations are displayed only for this Task's exact branch identity;
+ * displaying a historical location is not accepting it as migration proof.
+ */
+export function workspacePathValue(workspace, path) {
+    const inside = (root) => {
+        const value = relative(root, path);
+        return value !== ".." && !value.startsWith("../") && !isAbsolute(value) ? value || "." : undefined;
+    };
+    const marker = `/workspaces/tasks/${workspace.owner.taskId}/`;
+    const index = workspace.root.lastIndexOf(marker);
+    if (index >= 0) {
+        const home = workspace.root.slice(0, index);
+        const taskPath = inside(join(home, "workspaces", "tasks", workspace.owner.taskId));
+        if (taskPath !== undefined)
+            return `<task>/${taskPath}`;
+        const legacyPath = inside(join(home, "workspaces", "worktree"));
+        const parts = legacyPath?.split("/");
+        const taskSegment = workspace.entries.find(e => e.access === "write")?.branch.split("/")[1];
+        if (parts?.length === 3 && parts[1] === taskSegment)
+            return `<legacy-worktree>/${legacyPath}`;
+    }
+    const local = inside(workspace.root);
+    return local === undefined ? "[outside authorized Task paths]" : `<owner>/${local}`;
+}

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

@@ -111,8 +111,33 @@ 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 but currently lack a
+registered top-level CLI path. 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

@@ -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.