@zq-silk/yui 0.15.8 → 0.15.11

package/dist/web/webTaskSurface.js

@@ -1,14 +1,53 @@
+import { recordTaskInterruptResult } from "../message/taskInterrupt.js";
+import { recordGlobalInterruptResult, recordGlobalSteerResult } from "../message/globalInterrupt.js";
+import { runGlobalRoleCommand } from "../commands/globalRoleCommands.js";
 import { readTaskContext, readTaskContextDelta, inspectTaskContext, withContextObservations } from "../context/taskContext.js";
 import { BUILTIN_CAPABILITIES } from "../kernel/builtinCapabilities.js";
 import { capabilitySchemaError } from "../kernel/capabilitySchema.js";
-import { updateTaskMetadataCommand, sendTaskMessageCommand } from "../commands/taskCommands.js";
+import { updateTaskMetadataCommand, sendTaskMessageCommand, runTaskCommand } from "../commands/taskCommands.js";
 import { webLocalMutation, WebRequestRejected } from "./webMutation.js";
 import { runTaskInputCommand } from "../commands/taskInputCommands.js";
+import { sendAgentHostSteerControl, sendAgentHostCancelControl, AGENT_HOST_CONTROL_PROTOCOL, foldSteerLiveReceipt, foldInterruptLiveReceipt } from "../runtime/agentHost.js";
+const DEFAULT_WEB_HOST_CONTROL = {
+    steer: sendAgentHostSteerControl,
+    cancel: sendAgentHostCancelControl
+};
+/** The store-only CLI argv for the shared application-layer primitive
+ * (decision-3 §7). The Web surface never re-implements the queue/steer/interrupt
+ * decisions; it drives the exact same command the CLI drives. */
+function controlArgv(taskId, input) {
+    if (input.action === "queue") {
+        return ["message", "queue", taskId, input.body, "--request-id", input.requestId,
+            ...(input.to === undefined ? [] : ["--to", input.to]),
+            ...(input.workItem === undefined ? [] : ["--work-item", input.workItem]),
+            ...(input.reviewRound === undefined ? [] : ["--review-round", input.reviewRound])];
+    }
+    if (input.action === "steer") {
+        return ["message", "steer", taskId, input.body, "--request-id", input.requestId,
+            "--expected-target", input.expectedTarget, "--to", input.to,
+            ...(input.workItem === undefined ? [] : ["--work-item", input.workItem]),
+            ...(input.reviewRound === undefined ? [] : ["--review-round", input.reviewRound])];
+    }
+    return ["role", "interrupt", taskId, input.role, "--expected-target", input.expectedTarget,
+        ...(input.thenMessage === undefined ? [] : ["--then-message", input.thenMessage]),
+        "--request-id", input.requestId];
+}
+/** A queue is delivered to the Leader mailbox only when it is unaddressed or
+ * addressed to the Leader; an addressed Worker/Reviewer queue goes to the Task
+ * mailbox. A steer/interrupt is a live control op, so it only reconciles the
+ * Task. This mirrors the mailbox the core command itself enqueues. */
+function controlNotifiesLeader(input) {
+    return input.action === "queue" && (input.to === undefined || input.to === "leader");
+}
+function controlTarget(taskId, input) {
+    const roleName = input.action === "interrupt" ? input.role : input.to ?? "leader";
+    return { scope: "task", taskId, roleName };
+}
 /** Installed only by the local-user Web composition root. HTTP authenticates
  * its token before using this port; input never supplies a caller or Role.
  * Managed capability RPC keeps its own Session authentication unchanged.
  */
-export function createWebTaskSurface(store, options = {}, observations = []) {
+export function createWebTaskSurface(store, options = {}, observations = [], hostControl = DEFAULT_WEB_HOST_CONTROL) {
     const environment = {};
     const commandOptions = { ...options, environment, runtime: undefined };
     // Notifications are after the outer transaction. Their failure must not be
@@ -22,18 +61,196 @@ export function createWebTaskSurface(store, options = {}, observations = []) {
             options.runtime?.notifyStateChanged(taskId);
     };
     return {
-        message: (taskId, body) => {
-            // `queuedForLeader` is the fact the shared transaction actually committed,
-            // not a re-derivation from Task status. A Draft queues its Leader exactly
-            // like an active Task (planning is a Leader conversation), so reporting
-            // "saved" here would have understated a wake that really did happen.
-            const { message, task, queuedForLeader } = webLocalMutation(store, (tx) => sendTaskMessageCommand(tx, taskId, body, "leader", commandOptions));
+        globalState: (roleName) => {
+            const role = store.getGlobalRole(roleName);
+            if (role === null)
+                throw new WebRequestRejected("Global Role not found.");
+            const sessions = store.getGlobalRoleSessionSet(roleName);
+            return {
+                roleName,
+                nativeSessionId: sessions?.sessions[sessions.activeAgentId]?.nativeSessionId,
+                turn: sessions?.providerBinding?.run ?? null,
+                authority: sessions?.providerBinding?.authority ?? null,
+                interrupts: sessions?.interrupts ?? {},
+                messages: store.listGlobalRoleMessages(roleName).map(message => ({
+                    id: message.id, body: message.body, inputControl: message.inputControl,
+                    control: message.control, delivery: message.delivery, notDelivered: message.notDelivered
+                }))
+            };
+        },
+        globalControl: async (roleName, input) => {
+            const argv = input.action === "interrupt"
+                ? ["interrupt", roleName, "--request-id", input.requestId, "--expected-target", input.expectedTarget,
+                    ...(input.thenMessage === undefined ? [] : ["--then-message", input.thenMessage])]
+                : ["message", input.action, roleName, input.body, "--request-id", input.requestId,
+                    ...(input.action === "steer" ? ["--expected-target", input.expectedTarget] : [])];
+            const result = webLocalMutation(store, tx => runGlobalRoleCommand(argv, tx, {
+                env: {}, yuiHome: options.yuiHome, jsonOutput: true
+            }));
+            if (typeof result === "string") {
+                if (input.action === "queue")
+                    void options.runtime?.notifyMailboxChanged?.({
+                        kind: "global-role-runtime", roleName
+                    });
+                return { action: input.action, ...JSON.parse(result) };
+            }
+            if (result.kind !== "input-steer" && result.kind !== "input-interrupt") {
+                throw new WebRequestRejected("Global input cannot perform a Session lifecycle operation.");
+            }
+            if (options.yuiHome === undefined)
+                throw new Error("Global control requires a configured Yui Home.");
+            if (result.kind === "input-steer") {
+                let control;
+                try {
+                    control = await hostControl.steer({
+                        home: options.yuiHome, scope: "global", roleName,
+                        control: { protocol: AGENT_HOST_CONTROL_PROTOCOL, type: "steer-turn",
+                            nativeSessionId: result.target.nativeSessionId, nativeTurnId: result.target.nativeTurnId,
+                            authority: result.target.authority,
+                            run: { attemptId: result.receiptId, boundedText: result.text } }
+                    });
+                }
+                catch (error) {
+                    recordGlobalSteerResult(store, roleName, result.messageId, { state: "steer-unknown", outcome: "pending" });
+                    throw error;
+                }
+                const steer = foldSteerLiveReceipt(control);
+                recordGlobalSteerResult(store, roleName, result.messageId, steer);
+                return { action: "steer", roleName, messageId: result.messageId, steer };
+            }
+            let control;
+            try {
+                control = await hostControl.cancel({
+                    home: options.yuiHome, scope: "global", roleName,
+                    control: { protocol: AGENT_HOST_CONTROL_PROTOCOL, type: "cancel", nativeOnly: true,
+                        nativeSessionId: result.target.nativeSessionId,
+                        authority: result.target.authority, attemptId: result.target.attemptId }
+                });
+            }
+            catch (error) {
+                recordGlobalInterruptResult(store, roleName, result.receiptId, { state: "interrupt-unknown", outcome: "cancel-requested" });
+                throw error;
+            }
+            const interrupt = foldInterruptLiveReceipt(control);
+            recordGlobalInterruptResult(store, roleName, result.receiptId, interrupt);
+            return { action: "interrupt", roleName, receiptId: result.receiptId, interrupt };
+        },
+        message: (taskId, body, intent, requestId) => {
+            // Preserve the submission's intent and frozen receipt separately from
+            // queue/steer controls; an omitted intent still means discuss.
+            const { message, task, queuedForLeader, feedback } = webLocalMutation(store, (tx) => sendTaskMessageCommand(tx, taskId, body, undefined, commandOptions, undefined, intent, requestId));
             notify(taskId, queuedForLeader);
             return { record: message, revision: message.createdAt,
                 disposition: queuedForLeader ? "queued" : "saved",
                 planning: task.status === "draft",
+                ...(feedback === undefined ? {} : { submission: feedback }),
                 target: { scope: "task", taskId, roleName: "leader" } };
         },
+        /**
+         * The decision-3 three-action input-control path for the local-user Web
+         * surface. Its store-only phase is the identical shared application-layer
+         * primitive the CLI uses (`runTaskCommand`), run inside `webLocalMutation`
+         * so a rejected input is provably not-submitted. A ready steer/interrupt
+         * returns a live intent; the single Agent Host edge then runs OUTSIDE the
+         * transaction exactly as cli.ts performs it — never a fallback, retarget, or
+         * fourth action. A committed input whose live edge fails is delivery-unknown,
+         * not not-submitted: it throws a plain error so the receipt is "unknown" and
+         * the durable Message is retained (decision-3 §1/§3/§5, message-5 gap F).
+         */
+        control: async (taskId, input) => {
+            const execution = webLocalMutation(store, (tx) => runTaskCommand(controlArgv(taskId, input), tx, commandOptions));
+            if (execution.kind === "output") {
+                // A queue receipt, or a steer/interrupt that was saved-but-not-delivered
+                // or an idempotent replay: fully durable, no live edge, exact disposition.
+                notify(taskId, controlNotifiesLeader(input));
+                const data = execution.data;
+                const settlement = data.delivery ?? data.steer ?? data.interrupt;
+                return {
+                    action: input.action, disposition: settlement?.state ?? "saved",
+                    target: controlTarget(taskId, input),
+                    ...(data.message === undefined ? {} : { record: data.message, revision: data.message.createdAt }),
+                    ...(data.delivery === undefined ? {} : { delivery: data.delivery }),
+                    ...(data.steer === undefined ? {} : { steer: data.steer }),
+                    ...(data.interrupt === undefined ? {} : { interrupt: data.interrupt })
+                };
+            }
+            // A resolved live control op. Core has persisted the Message (steer) and
+            // recorded the one `pending` control attempt; both are already committed.
+            const home = options.yuiHome;
+            if (home === undefined) {
+                throw new Error("Live Agent Host control requires a configured Yui home.");
+            }
+            if (execution.kind === "input-steer") {
+                let control;
+                try {
+                    control = await hostControl.steer({
+                        home, scope: "task", taskId: execution.taskId, roleName: execution.roleName,
+                        control: {
+                            protocol: AGENT_HOST_CONTROL_PROTOCOL, type: "steer-turn",
+                            nativeSessionId: execution.target.nativeSessionId,
+                            nativeTurnId: execution.target.nativeTurnId ?? execution.target.attemptId,
+                            authority: execution.target.authority,
+                            run: { attemptId: execution.receiptId, boundedText: execution.text }
+                        }
+                    });
+                }
+                catch (error) {
+                    throw new Error(`Steer message ${execution.messageId} is saved but the native steer did not `
+                        + `complete: ${error instanceof Error ? error.message : String(error)}. The Message is `
+                        + "retained and its outcome is recorded from the Host; whether the Provider accepted it may "
+                        + "be delivery-unknown. Re-read the Session before acting; do not reissue the same input "
+                        + "under a new requestId or a different action.");
+                }
+                notify(taskId);
+                // decision-3 §7 live acceptance: fold the actual Host outcome rather than
+                // presume success. `steered` is the only proven delivery; pending is
+                // delivery-unknown; rejected/unavailable did not deliver. No fallback.
+                const steer = foldSteerLiveReceipt(control);
+                return { action: "steer", disposition: steer.state,
+                    taskId, roleName: execution.roleName, messageId: execution.messageId,
+                    target: { scope: "task", taskId, roleName: execution.roleName },
+                    steer };
+            }
+            let control;
+            if (execution.kind !== "input-interrupt") {
+                // The three-action argv only ever yields output/input-steer/input-interrupt;
+                // any other intent means the shared command was mis-dispatched, not a
+                // control outcome to fold. Fail closed rather than guess.
+                throw new Error(`Unexpected control execution kind: ${execution.kind}.`);
+            }
+            try {
+                control = await hostControl.cancel({
+                    home, scope: "task", taskId: execution.taskId, roleName: execution.roleName,
+                    control: {
+                        protocol: AGENT_HOST_CONTROL_PROTOCOL, type: "cancel",
+                        nativeOnly: true,
+                        nativeSessionId: execution.target.nativeSessionId,
+                        // Native cancel names the exact original execution attempt it stops,
+                        // never the durable receiptId of this interrupt operation.
+                        attemptId: execution.target.attemptId,
+                        authority: execution.target.authority
+                    }
+                });
+            }
+            catch (error) {
+                recordTaskInterruptResult(store, execution.taskId, execution.receiptId, { state: "interrupt-unknown", outcome: "cancel-requested" });
+                throw new Error(`Interrupt ${execution.receiptId} of ${execution.taskId}/${execution.roleName} did not complete: `
+                    + `${error instanceof Error ? error.message : String(error)}. No process was killed; `
+                    + "re-read the Session before retrying.");
+            }
+            notify(taskId);
+            // The proof is `control.cancellation`, not the bare `cancel-requested`
+            // outcome: only a proven stop-request is `interrupted`. A then-handoff, if
+            // any, was already claimed durably by Core and is delivered once by the
+            // ordinary continuation path — never re-driven from this receipt.
+            const interrupt = foldInterruptLiveReceipt(control);
+            recordTaskInterruptResult(store, execution.taskId, execution.receiptId, interrupt);
+            return { action: "interrupt", disposition: interrupt.state,
+                taskId, roleName: execution.roleName,
+                target: { scope: "task", taskId, roleName: execution.roleName },
+                ...(execution.thenMessageId === undefined ? {} : { thenMessageId: execution.thenMessageId }),
+                interrupt };
+        },
         read: async (taskId) => withContextObservations(readTaskContext(store, taskId, environment), observations),
         delta: (taskId, input) => readTaskContextDelta(store, taskId, input, environment),
         inspect: (taskId, input) => inspectTaskContext(store, taskId, input, environment),

package/dist/workItem/workItem.js

@@ -1,3 +1,4 @@
+import { validateGitArtifactRef } from "../artifacts/gitArtifactRef.js";
 import { normalizedUniqueIdentities, normalizedUniqueText, requireIdentity, requireText, requireTimestamp } from "../domain/validation.js";
 import { validateReviewConfig } from "../review/reviewConfig.js";
 import { taskFinalReviewConfig, validateTaskFinalReviewContract } from "../review/taskFinalReviewContract.js";
@@ -112,7 +113,7 @@ export function submitWorkItemCandidate(workItem, input, now) {
         ...(input.taskMainSnapshot === undefined
             ? {}
             : { taskMainSnapshot: input.taskMainSnapshot }),
-        ...(input.artifactRefs === undefined ? {} : { artifactRefs: input.artifactRefs.map((ref) => ({ ...ref })) }),
+        ...(input.artifactRefs === undefined ? {} : { artifactRefs: input.artifactRefs.map((ref) => validateGitArtifactRef(ref)) }),
         createdAt: now.toISOString()
     });
     const { outcome: _outcome, endedAt: _endedAt, ...base } = workItem;
@@ -502,17 +503,20 @@ export function validateWorkItemCandidate(candidate) {
     if (candidate.artifactRefs !== undefined) {
         if (!Array.isArray(candidate.artifactRefs))
             throw new Error("Candidate Artifact refs must be an array.");
-        const ids = new Set();
+        const identities = new Set();
         for (const ref of candidate.artifactRefs) {
-            requireIdentity(ref.artifactId, "Candidate Artifact id");
-            if (ref.taskId !== candidate.taskId || !["content", "external-version", "receipt"].includes(ref.kind)
-                || ids.has(ref.artifactId))
-                throw new Error("Candidate Artifact scope, kind or identity is invalid.");
-            if ((ref.kind !== "external-version" || ref.digest !== undefined)
-                && (typeof ref.digest !== "string" || !/^[a-f0-9]{64}$/u.test(ref.digest))) {
-                throw new Error("Candidate Artifact digest is invalid.");
+            // Pure, no-I/O shape check: the commit self-certifies the frozen bytes,
+            // so a valid pinned reference is complete evidence on its own. Existence
+            // is proven lazily when the bytes are resolved on the async read path.
+            const valid = validateGitArtifactRef(ref);
+            if (valid.taskId !== candidate.taskId) {
+                throw new Error("Candidate Artifact scope, commit or path is invalid.");
             }
-            ids.add(ref.artifactId);
+            const identity = `${valid.commit}:${valid.relativePath}`;
+            if (identities.has(identity)) {
+                throw new Error("Candidate Artifact scope, commit or path is invalid.");
+            }
+            identities.add(identity);
         }
     }
     if (typeof candidate.source !== "object" || candidate.source === null) {

package/dist/workspace/workItemChangeSetManager.js

@@ -1,4 +1,5 @@
 import { isDeepStrictEqual } from "node:util";
+import { lstat } from "node:fs/promises";
 import { createWorkItemChangeSet } from "../integration/changeSet.js";
 import { createChangeSetManifest } from "../integration/changeSetManifest.js";
 import { deriveManifestTags } from "../integration/manifestTags.js";
@@ -60,11 +61,25 @@ export class WorkItemChangeSetManager {
         const git = new NodeGitWorkspace();
         const projects = [];
         for (const entry of writableEntries(workspace)) {
-            if (!await git.isClean(entry.path)) {
+            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 workspaceHeadCommit = (await git.inspect(entry.path, "HEAD")).baseCommit;
             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
@@ -109,6 +124,7 @@ export class WorkItemChangeSetManager {
         }
         const unresolved = this.store.listIntegrationAttempts(task.id).find((attempt) => (attempt.status === "running"
             || attempt.status === "blocked"
+            || attempt.status === "conflicted"
             || attempt.status === "validating"));
         if (unresolved !== undefined) {
             throw new Error(`Task has an unresolved Integration Attempt: ${task.id}/${unresolved.id}.`);

package/docs/agent-result-consumption.md

@@ -1,3 +1,5 @@
+<p align="right"><strong>English</strong> | <a href="./agent-result-consumption.zh-CN.md">简体中文</a></p>
+
 # Agent result consumption
 
 Every explicitly dispatched AgentRun produces one durable original result.

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

@@ -0,0 +1,81 @@
+<p align="right"><a href="./agent-result-consumption.md">English</a> | <strong>简体中文</strong></p>
+
+# Agent 结果消费
+
+每一次显式派发的 AgentRun 都产生一个持久的原始结果。普通通知和原生对话不会
+隐式创建 Run。所有权链上的下一个 Agent 读取这个精确结果并判断它意味着什么。
+
+## 唯一的原始结果
+
+`AgentRunResult.output` 是 Agent 撰写的报告。Core 保留其字节，不解析、不分类、
+也不校验语义内容。Markdown、JSON 和普通散文都是合法的；缺少标题或结论不够有力
+都是质量证据，而不是运行时失败。
+
+Core 另外记录 Provider 身份/状态、完成时间、诊断、失败原因和系统拥有的工作区
+证据。非空输出必须符合当前传输上限且不含 NUL。缺失或不可传输的文本会让 Run
+失败，而不编造散文。当之后某个 Core 拥有的边界失败时，一份已到达的报告仍可以
+留在一个 failed 的 Run 上。
+
+终态结果会附带保存一条引用 Message。`task message show <task/message>` 和
+Context inspect 展开同一个 `resultRef`。ReviewRound 不持有第二份报告。文件和
+持久业务产物归 Artifact 或受管 Git 结果。
+
+## 执行不等于验收
+
+Run 生命周期是 `active / completed / failed`。Provider 结果、输入接受和资源静止
+是彼此独立的事实。Run completed 只表示它所需的 Core 执行边界成功，而不表示答案
+正确或 WorkItem 已验收。
+
+可写的 replicated Lane 需要其精确的、Core 拥有的工作区证据。分支错误、快照脏、
+owner 不符或范围不符都会让该边界失败，但不会替换一份已到达的原始报告。
+
+只有 Leader 决定证据是否足以验收、继续工作、再审查或放弃。Core 从不从 Agent
+文本中推导 findings、投票或修复拓扑。
+
+## 直接执行与复制执行
+
+直接的 WorkItem 执行使用一个 main Run，没有 ExecutionGroup。直接 Review 同样
+使用一个 main Reviewer Run。
+
+复制执行在一个冻结 Assignment 上使用彼此不同的 Producer Lane。每个 Producer
+保留自己的原始结果和精确血缘。Leader 显式地把彼此不同的终态来源 Run 引用交给
+综合。来源必须属于确切的 Group/Lane 且有结果，可以是 completed 或 failed。不存在
+自动综合、投票、最少成功 Producer 数，也不要求在选择来源前等待所有 Lane。
+
+综合快照保留所选来源顺序，以及它们原始输出、诊断和来源的有界视图，不复制完整
+transcript。只有 main 综合结果能提供 WorkItem Candidate 或权威的 replicated
+Review 结果。Producer 从不直接进入 Integration 或验收。重试针对失败的那次精确
+执行，不会静默重跑已成功的 Producer。
+
+## Review
+
+ReviewRound 拥有冻结的 Candidate 或 Task-head 身份、工作区来源、执行拓扑、精确
+的 main Reviewer Run、生命周期和 Core 诊断。它的 completed 状态是结构性执行证据，
+而不是从报告里提取出来的“通过”。
+
+Candidate 审查遵循其捕获的审查规则。Task-final 审查可以被显式请求，或由不可变的
+final-review 合同要求。一次被请求的审查是证据，而不是要求此后每次改动都审查的
+自动新策略。当前交付需要审查时，它必须覆盖确切的治理候选或 head 以及 completed
+的 main Run。
+
+Reviewer 应检查完整的有界范围，并把重要 findings 一并报告。Leader 读取完整报告，
+把 findings 路由给原 owner，直接修复 Task-main 上的小问题，只为有独立价值的实质
+工作创建新的 WorkItem。
+
+## Leader 消费
+
+唤醒窗口指向带结果的事件，包括在窗口之前创建、但在窗口之内完成的 Run。读取精确
+来源：
+
+```sh
+yui task wake show <task> <wake>
+yui task run show <task/run>
+yui task message show <task/message>
+```
+
+一个可选的报告结构是：结果、改动/发现、验证、不确定性和下一步动作。它是沟通
+建议，不是机器协议。
+
+验收与 Task 完成仍是显式操作，并带有当前 Git、审查、范围和资源检查。参见
+[执行与会话](managed-turn-and-session-runtime.zh-CN.md)和
+[Task 依赖](task-dag-semantics.zh-CN.md)。

package/docs/agent-runtime-drivers.md

@@ -1,3 +1,5 @@
+<p align="right"><strong>English</strong> | <a href="./agent-runtime-drivers.zh-CN.md">简体中文</a></p>
+
 # Agent runtime Drivers
 
 AgentEndpoint supplies the common execution boundary. Drivers translate native

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

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