@zq-silk/yui 0.15.7 → 0.15.9

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";
@@ -5,8 +6,7 @@ import { validateManagedWorkspace } from "../worktree/managedWorkspace.js";
 import { validateTaskRecordReference } from "../task/taskRecordReference.js";
 import { assertWorkItemExecutionGroupTransition, validateWorkItemExecutionGroup as validateExecutionGroupRecord, workItemExecutionGroupSettled } from "../execution/workItemExecution.js";
 const TERMINAL_STATUSES = [
-    "completed",
-    "failed",
+    "accepted",
     "retired"
 ];
 export function createWorkItem(id, taskId, input, now) {
@@ -31,21 +31,18 @@ export function createWorkItem(id, taskId, input, now) {
         ...(input.assignee === undefined
             ? {}
             : { assignee: requireIdentity(input.assignee, "Work item assignee") }),
-        status: "pending",
+        status: "open",
         candidates: [],
         createdAt: timestamp,
         updatedAt: timestamp
     });
 }
-/** Replace the mutable definition of an execution-free Draft WorkItem. */
-export function editDraftWorkItemDefinition(workItem, update, now) {
+/** Edit current open-work requirements; frozen Assignments are separate records.
+ * The command boundary owns Task authority and workspace/assignee constraints. */
+export function editWorkItemDefinition(workItem, update, now) {
     validateWorkItem(workItem);
-    if (workItem.status !== "pending"
-        || workItem.executionGroups.length > 0
-        || workItem.candidates.length > 0
-        || workItem.disposition !== undefined
-        || workItem.workspaceDisposition !== undefined) {
-        throw new Error(`Work Item has execution or retirement facts: ${workItem.id}.`);
+    if (workItem.status !== "open") {
+        throw new Error(`Only open Work Item definitions may change: ${workItem.id} (${workItem.status}).`);
     }
     const next = {
         ...workItem,
@@ -87,7 +84,7 @@ export function editDraftWorkItemDefinition(workItem, update, now) {
 }
 export function submitWorkItemCandidate(workItem, input, now) {
     validateWorkItem(workItem);
-    if (workItem.status !== "running") {
+    if (workItem.status !== "open") {
         throw new Error(`Work Item candidate can only be submitted from running: ${workItem.id}/${workItem.status}.`);
     }
     const revision = workItem.revision + 1;
@@ -116,26 +113,28 @@ export function submitWorkItemCandidate(workItem, input, now) {
         ...(input.taskMainSnapshot === undefined
             ? {}
             : { taskMainSnapshot: input.taskMainSnapshot }),
+        ...(input.artifactRefs === undefined ? {} : { artifactRefs: input.artifactRefs.map((ref) => validateGitArtifactRef(ref)) }),
         createdAt: now.toISOString()
     });
     const { outcome: _outcome, endedAt: _endedAt, ...base } = workItem;
     return validateWorkItem({
         ...base,
-        status: "awaiting_acceptance",
+        status: "open",
         candidates: [...workItem.candidates, candidate],
+        currentCandidateId: candidate.id,
         revision,
         updatedAt: now.toISOString()
     });
 }
-export function updateWorkItemStatus(workItem, status, now, outcome) {
+export function updateWorkItemStatus(workItem, status, now, outcome, candidateId) {
     validateWorkItem(workItem);
     validateStatus(status);
     const alreadyTerminal = isTerminalStatus(workItem.status);
     if (workItem.disposition !== undefined && status !== workItem.status) {
         throw new Error(`Retired Work Item status cannot change: ${workItem.id}.`);
     }
-    const closingFailedWork = workItem.status === "failed" && status === "retired";
-    if (alreadyTerminal && status !== workItem.status && !closingFailedWork) {
+    const withdrawingAcceptance = workItem.status === "accepted" && status === "open";
+    if (alreadyTerminal && status !== workItem.status && !withdrawingAcceptance) {
         throw new Error(`Terminal Work Item status cannot change: ${workItem.id}.`);
     }
     const terminal = isTerminalStatus(status);
@@ -154,16 +153,19 @@ export function updateWorkItemStatus(workItem, status, now, outcome) {
             updatedAt: timestamp
         });
     }
-    const { endedAt: _endedAt, outcome: _outcome, workspaceDisposition, ...base } = workItem;
+    const { endedAt: _endedAt, outcome: _outcome, workspaceDisposition, acceptedCandidateId, currentCandidateId, ...base } = workItem;
     return validateWorkItem({
         ...base,
         status,
         revision: workItem.revision + 1,
         ...(normalizedOutcome === undefined ? {} : { outcome: normalizedOutcome }),
         // Isolated workspace cleanup remains durable evidence after retirement.
-        ...(closingFailedWork && workspaceDisposition !== undefined
+        ...(workspaceDisposition !== undefined
             ? { workspaceDisposition }
             : {}),
+        ...(status === "accepted" && (candidateId ?? acceptedCandidateId ?? currentCandidateId) !== undefined
+            ? { acceptedCandidateId: candidateId ?? acceptedCandidateId ?? currentCandidateId } : {}),
+        ...(status === "open" && !withdrawingAcceptance && currentCandidateId !== undefined ? { currentCandidateId } : {}),
         updatedAt: timestamp,
         ...(terminal ? { endedAt: timestamp } : {})
     });
@@ -172,7 +174,7 @@ export function updateWorkItemStatus(workItem, status, now, outcome) {
 export function attachWorkItemExecutionGroup(workItem, executionGroup, now) {
     validateWorkItem(workItem);
     const checked = validateWorkItemExecutionGroup(executionGroup, workItem.taskId, workItem.id);
-    if (workItem.status === "completed" || workItem.status === "failed" || workItem.status === "retired") {
+    if (workItem.status !== "open") {
         throw new Error(`A terminal Work Item cannot attach an ExecutionGroup: ${workItem.id}.`);
     }
     const existing = workItemExecutionGroupById(workItem, checked.id);
@@ -235,11 +237,10 @@ export function retireWorkItem(workItem, input, now) {
         }
         throw new Error(`Work Item already has an explicit disposition: ${workItem.id}.`);
     }
-    if (workItem.status === "completed") {
+    if (workItem.status === "accepted") {
         throw new Error(`Completed Work Item cannot be retired: ${workItem.id}.`);
     }
     if (isTerminalStatus(workItem.status)
-        && workItem.status !== "failed"
         && workItem.status !== "retired") {
         throw new Error(`Terminal Work Item status cannot change: ${workItem.id}.`);
     }
@@ -254,15 +255,15 @@ export function retireWorkItem(workItem, input, now) {
         endedAt: timestamp
     });
 }
-export function retryFailedWorkItem(workItem, now) {
+export function prepareWorkItemDispatch(workItem, now) {
     validateWorkItem(workItem);
-    if (workItem.status !== "failed") {
+    if (workItem.status !== "open") {
         throw new Error(`Work item is not retryable from ${workItem.status}: ${workItem.id}.`);
     }
     if (workItem.workspaceDisposition !== undefined) {
         throw new Error(`Work item workspace is already settled: ${workItem.id}.`);
     }
-    const { outcome: _outcome, endedAt: _endedAt, ...base } = workItem;
+    const { outcome: _outcome, endedAt: _endedAt, currentCandidateId: _candidate, ...base } = workItem;
     // Keep every historical Group. A settled current Group is cleared only as
     // the current pointer; redispatch appends a fresh immutable Group.
     const current = currentWorkItemExecutionGroup(workItem);
@@ -271,7 +272,7 @@ export function retryFailedWorkItem(workItem, now) {
         : (({ currentExecutionGroupId: _currentExecutionGroupId, ...history }) => history)(base);
     return validateWorkItem({
         ...retryBase,
-        status: "running",
+        status: "open",
         revision: workItem.revision + 1,
         updatedAt: now.toISOString()
     });
@@ -316,7 +317,10 @@ export function validateWorkItem(workItem) {
         "workspaceDisposition",
         "createdAt",
         "updatedAt",
-        "endedAt"
+        "endedAt",
+        "acceptedCandidateId",
+        "currentCandidateId",
+        "historicalState"
     ], "WorkItem");
     if (workItem.schemaVersion !== 15)
         throw new Error("WorkItem must use schemaVersion 15.");
@@ -381,9 +385,27 @@ export function validateWorkItem(workItem) {
             throw new Error("Work Item candidate revision cannot exceed the Work Item revision.");
         }
     });
-    const currentCandidate = currentWorkItemCandidate(workItem);
-    if (workItem.status === "awaiting_acceptance" && currentCandidate === undefined) {
-        throw new Error("A Work Item awaiting acceptance requires a candidate.");
+    if (workItem.acceptedCandidateId !== undefined
+        && !candidateIds.has(workItem.acceptedCandidateId))
+        throw new Error("Accepted Candidate is missing.");
+    if (workItem.acceptedCandidateId !== undefined && workItem.status !== "accepted") {
+        throw new Error("Only an accepted Work Item may select an accepted Candidate.");
+    }
+    if (workItem.status === "accepted" && workItem.candidates.length > 0 && workItem.acceptedCandidateId === undefined) {
+        throw new Error("Accepted Work Item must identify its selected Candidate.");
+    }
+    if (workItem.currentCandidateId !== undefined
+        && !candidateIds.has(workItem.currentCandidateId))
+        throw new Error("Current Candidate is missing.");
+    if (workItem.historicalState !== undefined) {
+        const historical = workItem.historicalState;
+        if (!["pending", "running", "awaiting_acceptance", "completed", "failed", "retired"].includes(historical.status)) {
+            throw new Error("Historical Work Item status is invalid.");
+        }
+        if (historical.outcome !== undefined)
+            requireText(historical.outcome, "Historical outcome");
+        if (historical.endedAt !== undefined)
+            requireTimestamp(historical.endedAt, "Historical endedAt");
     }
     if (workItem.outcome !== undefined)
         requireText(workItem.outcome, "Work item outcome");
@@ -406,9 +428,6 @@ export function validateWorkItem(workItem) {
         if (!["integrated", "abandoned"].includes(workItem.workspaceDisposition)) {
             throw new Error("Work item workspaceDisposition is invalid.");
         }
-        if (!terminal) {
-            throw new Error("Only a terminal Work Item can record workspace cleanup.");
-        }
     }
     if (workItem.disposition !== undefined) {
         validateDisposition(workItem.disposition);
@@ -433,7 +452,7 @@ export function workItemExecutionGroupById(workItem, executionGroupId) {
     return workItem.executionGroups.find(({ id }) => id === executionGroupId);
 }
 /**
- * True when a Turn failure belongs to the WorkItem's current unresolved Lane.
+ * True when a AgentRun failure belongs to the WorkItem's current unresolved Lane.
  * Such a failure is Lane-bounded: the WorkItem remains running so the Leader
  * can reuse completed siblings and retry only this failed attempt.
  */
@@ -445,7 +464,7 @@ export function workItemOwnsUnresolvedExecutionLane(workItem, executionGroupId,
     const group = workItem.executionGroups.find(({ id }) => id === executionGroupId);
     return group !== undefined
         && !workItemExecutionGroupSettled(group)
-        && group.lanes.some(({ id, disposition, currentTurnId }) => (id === executionLaneId && disposition === "open" && currentTurnId !== undefined));
+        && group.lanes.some(({ id, disposition, currentRunId }) => (id === executionLaneId && disposition === "open" && currentRunId !== undefined));
 }
 function validateWorkItemExecutionGroup(group, taskId, workItemId) {
     validateExecutionGroupRecord(group);
@@ -481,17 +500,36 @@ export function validateWorkItemCandidate(candidate) {
         throw new Error("Work Item candidate revision must be a positive integer.");
     }
     requireText(candidate.summary, "Work Item candidate summary");
+    if (candidate.artifactRefs !== undefined) {
+        if (!Array.isArray(candidate.artifactRefs))
+            throw new Error("Candidate Artifact refs must be an array.");
+        const identities = new Set();
+        for (const ref of candidate.artifactRefs) {
+            // 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.");
+            }
+            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) {
         throw new Error("Work Item candidate source is required.");
     }
-    if (candidate.source.type !== "direct" && candidate.source.type !== "turn") {
+    if (candidate.source.type !== "direct" && candidate.source.type !== "run") {
         throw new Error("Work Item candidate source is invalid.");
     }
-    if (candidate.source.type === "turn") {
+    if (candidate.source.type === "run") {
         validateTaskRecordReference({
             taskId: candidate.taskId,
-            localId: candidate.source.turnId
-        }, "turn");
+            localId: candidate.source.runId
+        }, "run");
     }
     if ((candidate.executionGroupId === undefined) !== (candidate.executionLaneId === undefined)) {
         throw new Error("Work Item candidate execution lineage is incomplete.");
@@ -647,8 +685,8 @@ function requireCommit(value, label) {
     return commit;
 }
 export function currentWorkItemCandidate(workItem) {
-    return workItem.status === "awaiting_acceptance"
-        ? workItem.candidates.at(-1)
+    return workItem.status === "open"
+        ? workItem.candidates.find(({ id }) => id === workItem.currentCandidateId)
         : undefined;
 }
 /**
@@ -659,9 +697,10 @@ export function currentWorkItemCandidate(workItem) {
  * Candidates on the same WorkItem are superseded by its latest Candidate.
  */
 export function governingWorkItemCandidate(workItem) {
-    return workItem.status === "awaiting_acceptance" || workItem.status === "completed"
-        ? workItem.candidates.at(-1)
-        : undefined;
+    if (workItem.status === "accepted" && workItem.acceptedCandidateId !== undefined) {
+        return workItem.candidates.find(({ id }) => id === workItem.acceptedCandidateId);
+    }
+    return currentWorkItemCandidate(workItem);
 }
 export function updateWorkItemWriteProjects(workItem, writeProjectIds, now) {
     validateWorkItem(workItem);
@@ -690,11 +729,8 @@ function isTerminalStatus(status) {
 }
 function validateStatus(status) {
     if (![
-        "pending",
-        "running",
-        "awaiting_acceptance",
-        "completed",
-        "failed",
+        "open",
+        "accepted",
         "retired"
     ].includes(status)) {
         throw new Error(`Work Item status is invalid: ${String(status)}.`);

package/dist/workspace/workItemChangeSetManager.js

@@ -8,9 +8,8 @@ import { governingWorkItemCandidate } from "../workItem/workItem.js";
 import { managedWorkspaceKey } from "../worktree/managedWorkspace.js";
 import { captureManagedGitChanges } from "./gitChangeSetCapture.js";
 const CAPTURABLE_WORK_ITEM_STATUSES = new Set([
-    "awaiting_acceptance",
-    "completed",
-    "failed",
+    "open",
+    "accepted",
     "retired"
 ]);
 export class WorkItemChangeSetManager {
@@ -44,10 +43,15 @@ export class WorkItemChangeSetManager {
         }
         return captured;
     }
-    async assertIntegrated(taskId, workItemId) {
+    async assertIntegrated(taskId, workItemId, candidateId) {
         const item = this.store.getWorkItem(taskId, workItemId);
         if (item === null)
             throw new Error(`Work item not found: ${taskId}/${workItemId}.`);
+        const candidate = candidateId === undefined ? governingWorkItemCandidate(item)
+            : item.candidates.find(({ id }) => id === candidateId);
+        if (candidateId !== undefined && candidate === undefined) {
+            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"
@@ -59,14 +63,17 @@ export class WorkItemChangeSetManager {
             if (!await git.isClean(entry.path)) {
                 throw new Error(`WorkItem Project workspace is not clean: ${item.id}/${entry.projectId}.`);
             }
-            const headCommit = (await git.inspect(entry.path, "HEAD")).baseCommit;
-            const candidate = governingWorkItemCandidate(item);
+            const workspaceHeadCommit = (await git.inspect(entry.path, "HEAD")).baseCommit;
             const resultCommit = candidate?.gitSnapshot?.projects.find(({ projectId }) => projectId === entry.projectId)?.commit;
             if (candidate?.workspace === undefined
                 || !isDeepStrictEqual(candidate.workspace, workspace)
-                || resultCommit !== headCommit) {
+                || resultCommit === undefined
+                || (candidateId === undefined && resultCommit !== workspaceHeadCommit)) {
                 throw new Error(`WorkItem Project no longer matches its frozen result: ${item.id}/${entry.projectId}.`);
             }
+            // 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"
@@ -282,7 +289,7 @@ function requireCapturableContext(store, taskId, workItemId, taskFinalReviewCont
         if (taskFinalReviewContract === undefined) {
             throw new Error(`Work item has no managed workspace: ${item.id}.`);
         }
-        const candidate = item.candidates.at(-1);
+        const candidate = governingWorkItemCandidate(item);
         if (candidate === undefined
             || !sameTaskFinalReviewContract(candidate.taskFinalReviewContract, taskFinalReviewContract)) {
             throw new Error(`Work item has no matching exact Task-final direct Candidate: ${item.id}.`);
@@ -346,7 +353,7 @@ function assertCaptureStillCurrent(store, expected) {
     const workspace = expected.source === "task-main"
         ? store.getTaskWorkspace(expected.taskId)
         : store.getWorkItemWorkspace(expected.taskId, expected.workItemId);
-    const candidate = item?.candidates.at(-1);
+    const candidate = item === null ? undefined : governingWorkItemCandidate(item);
     if (task?.status !== "active"
         || item === null
         || item.revision !== expected.expectedRevision

package/docs/agent-result-consumption.md

@@ -0,0 +1,96 @@
+<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.
+Ordinary notification and native conversation do not implicitly create Runs.
+The next Agent in the ownership chain reads the exact result and decides what
+it means.
+
+## One original result
+
+`AgentRunResult.output` is the Agent-authored report. Core preserves its bytes
+and does not parse, classify or validate semantic content. Markdown, JSON and
+ordinary prose are all legal; omitted headings or an unconvincing conclusion are
+quality evidence, not a runtime failure.
+
+Core separately records Provider identity/status, completion time, diagnostics,
+failure reasons and system-owned workspace evidence. Non-empty output must fit
+the current transport limit and contain no NUL. Missing or untransportable text
+fails the Run without fabricated prose. An arrived report can remain on a failed
+Run when a later Core-owned boundary fails.
+
+One reference Message is saved with the terminal result.
+`task message show <task/message>` and Context inspect expand the same
+`resultRef`. ReviewRound does not hold a second report. Files and durable
+business outputs belong to Artifacts or managed Git results.
+
+## Execution is not acceptance
+
+Run lifecycle is `active / completed / failed`. Provider outcome, input
+acceptance and resource quiescence are separate facts. A completed Run means
+its required Core execution boundaries succeeded, not that its answer is
+correct or the WorkItem accepted.
+
+Writable replicated Lanes require their exact Core-owned workspace evidence.
+A wrong branch, dirty snapshot, mismatched owner or scope fails that boundary
+without replacing an already arrived original report.
+
+Only the Leader decides whether evidence warrants acceptance, further work,
+another review or abandonment. Core never derives findings, votes or repair
+topology from Agent text.
+
+## Direct and replicated execution
+
+Direct WorkItem execution uses one main Run and no ExecutionGroup. Direct
+Review likewise uses one main Reviewer Run.
+
+Replicated execution uses distinct Producer Lanes over one frozen Assignment.
+Each Producer retains its own original result and exact lineage. Leader
+explicitly supplies distinct terminal source Run references to synthesis.
+Sources must belong to the exact Group/Lane and have a result; they may be
+completed or failed. There is no automatic synthesis, vote, minimum successful
+Producer count or requirement to wait for all Lanes before choosing sources.
+
+The synthesis snapshot retains the selected source order and bounded views of
+their original outputs, diagnostics and provenance. It does not copy complete
+transcripts. Only the main synthesis result can supply the WorkItem Candidate
+or authoritative replicated Review result. Producers never enter Integration
+or acceptance directly. Retry targets the failed exact execution; it does not
+silently rerun successful Producers.
+
+## Review
+
+ReviewRound owns frozen Candidate or Task-head identity, workspace provenance,
+execution topology, exact main Reviewer Run, lifecycle and Core diagnostics.
+Its completed state is structural execution evidence, not a “pass” extracted
+from the report.
+
+Candidate review follows its captured review rule. Task-final review can be
+explicitly requested or required by the immutable final-review contract. A
+requested review is evidence, not an automatic new policy requiring review
+after every subsequent change. When current delivery requires a review, it
+must cover the exact governing candidate or heads and completed main Run.
+
+The Reviewer should inspect the complete bounded scope and report material
+findings together. The Leader reads the full report, routes findings to the
+original owner, fixes small Task-main issues directly, and creates a new
+WorkItem only for substantial independent work.
+
+## Leader consumption
+
+Wake windows point to result-bearing events, including a Run created before
+the window but completed inside it. Read the exact source:
+
+```sh
+yui task wake show <task> <wake>
+yui task run show <task/run>
+yui task message show <task/message>
+```
+
+An optional report layout is outcome, changes/findings, verification, uncertainty
+and next action. It is communication guidance, not a machine protocol.
+
+Acceptance and Task completion remain explicit operations with current Git,
+review, scope and resource checks. See [Session and AgentRun](managed-turn-and-session-runtime.md)
+and [Task dependencies](task-dag-semantics.md).

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

@@ -0,0 +1,93 @@
+<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
+events, errors and supported observation sources into `RuntimeObservation`;
+Controller, Store, CLI and Web consume that shared contract.
+
+## Responsibilities
+
+The connection implementation owns launch, protocol, prompt delivery, resume and
+interrupt. Driver owns native identity extraction, observation capabilities,
+event/error mapping and usage normalization. Core owns authority, exact request
+correlation, durable folding and projections; Agents choose recovery and judge
+semantic progress.
+
+Built-in Driver identities are `openai/codex`, `anthropic/claude-code` and
+`acp/agent-client-protocol`. ACP is a protocol Driver, not a product label.
+Adding an ACP peer does not require another business-state model.
+
+Capabilities must be stated truthfully. Unknown resume, cancellation, activity
+or usage behavior cannot be inferred from a product name.
+
+## Observation path
+
+Native structured facts pass the exact Session/request fence, enter the runtime
+inbox, and fold into durable observations and original results. A separately
+sampled usage source can feed the same canonical contract. Driver cannot choose
+another actor, assign a successor Run, or bypass the fence.
+
+Yui Run identity and Provider native Turn identity are not interchangeable.
+An explicitly dispatched Run retains its accepted native correlation; direct
+native chat is not another implicit Run. Replay is deduplicated by exact fact
+identity, and late events cannot terminalize a successor.
+
+Managed Codex uses App Server events. Claude maps its structured stream and
+supported Hook/source payloads. ACP maps protocol Session updates and prompt
+responses. Terminal text, trust dialogs and prompt glyphs are not lifecycle facts.
+
+## State and error evidence
+
+Persistent Run lifecycle is `active / completed / failed`. Input disposition,
+native waiting/activity, Goal, Session lifecycle and process presence answer
+different questions. UI projections must not present a queued request as proof
+that the Agent is busy, or a live process as acceptance.
+
+Standard Agent errors preserve source, phase, category, code, input disposition,
+Session disposition and the serialized native error. Categories include
+availability, rate-limit, transport, access, invalid-request, context, session,
+runtime, conflict, cancelled and unknown. A mapping reports evidence, not a
+retry policy. Unrecognized errors stay unknown.
+
+Runtime activity and workflow progress use separate evidence. A tool boundary
+may show native activity; a durable accepted result shows semantic progress.
+Tokens, CPU, RSS and pane presence cannot substitute for either acceptance or
+Task completion.
+
+## Usage
+
+Usage is read-only and scoped to the exact native Session. Input/output totals
+are distinguished from cache/reasoning breakdowns, request context and remaining
+capacity. Stable activity IDs deduplicate request snapshots; cumulative deltas
+are used only with valid ordered same-Session evidence.
+
+Missing, partial, mixed or rolled-back observations remain unobserved rather
+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.
+
+## Native children
+
+Native subagents are collaboration inside a parent conversation, not Yui Roles,
+Lanes or independent managed workspace owners. Continuation observations may
+record lineage and result references when the Provider exposes them.
+
+Best-effort child results return through the parent. Only a persisted content
+receipt justifies `durable-result`; a live child or claimed success does not.
+Reported results remain untrusted data. A lost best-effort conversation may
+require redoing the work. Choose a managed WorkItem execution when independent
+durability and acceptance are needed; replication is a separate choice.
+
+## Integration and validation
+
+A new connection implementation must supply truthful control/observation
+capabilities and pair them with exact identity, error and terminal mapping.
+Provider-specific protocol details stay at the edge, not in Task planning,
+Store semantics or Web business rules.
+
+Change-specific disposable evidence should cover the changed correlation,
+permission, cancellation or observation boundary. Keep permanent tests to the
+primary paths in the [verification policy](testing/verification-levels.md).
+Real Provider/model validation requires explicit authorization and must distinguish
+native process evidence from fixture output.