@zq-silk/yui 2.0.0 → 2.2.0

package/dist/commands/capabilityCommands.js

@@ -3,7 +3,7 @@ import { resolveJobCaller } from "../task/taskAuthority.js";
 import { callFileTaskController } from "../controller/clientRuntime.js";
 export async function runCapabilityCommand(args, home, environment) {
     const [action, ...rest] = args;
-    const usage = "yui capability search [query] --task <id> | commands --task <id> | panels --task <id> | describe <name> --task <id> [--provider <id>] [--version <version>] | call <name> --task <id> --input <json> [--provider <id>] [--version <version>] [--request-id <id>]";
+    const usage = "yui capability search [query] --task <id> | commands --task <id> | panels --task <id> | describe <name> --task <id> [--input <json>] [--provider <id>] [--version <version>] | call <name> --task <id> --input <json> [--provider <id>] [--version <version>] [--request-id <id>]";
     if (!["search", "commands", "panels", "describe", "call"].includes(action))
         throw usageError(usage);
     const surfaceList = action === "commands" || action === "panels";
@@ -29,12 +29,12 @@ export async function runCapabilityCommand(args, home, environment) {
         throw usageError(usage);
     if ((action === "search" || surfaceList) && [...flags.keys()].some((key) => key !== "--task"))
         throw usageError(usage);
-    if (action === "describe" && (flags.has("--input") || flags.has("--request-id")))
+    if (action === "describe" && flags.has("--request-id"))
         throw usageError(usage);
     let input;
-    if (action === "call") {
-        if (!flags.has("--input"))
-            throw usageError("Capability call requires --input <json>.", usage);
+    if (action === "call" && !flags.has("--input"))
+        throw usageError("Capability call requires --input <json>.", usage);
+    if (flags.has("--input")) {
         try {
             input = JSON.parse(flags.get("--input"));
         }

package/dist/commands/globalRoleCommands.js

@@ -1,4 +1,5 @@
 import { roleNotFound, usageError } from "../errors/cliError.js";
+import { hasManagedIdentity } from "../runtime/managedIdentity.js";
 import { boundedDocument, recordPage, readOptions, readDigest, messageReceipt } from "../output/boundedRead.js";
 import { controlProviderRetry, providerRetryProjection, renderProviderRetry } from "../runtime/providerRetry.js";
 import { settleGlobalRetryInput } from "../message/globalProviderRetry.js";
@@ -50,7 +51,7 @@ function assertGlobalInputAuthority(store, options, target) {
             throw usageError("Global input mutation requires the current native caller Session.");
         }
     }
-    else if (env.YUI_ROLE !== undefined || env.YUI_AGENT_ID !== undefined || env.YUI_NATIVE_SESSION_ID !== undefined) {
+    else if (hasManagedIdentity(env)) {
         throw usageError("Incomplete managed identity cannot acquire user authority.");
     }
 }

package/dist/commands/taskCommands.js

@@ -4,11 +4,12 @@ import { agentExecutionComponentLabel } from "../agent/executionComponents.js";
 import { assertLeaderArchiveAdmission } from "../task/leaderArchiveAuthority.js";
 import { createRun, runExecutionObservation, runPurposeAdmitsTaskState } from "../agentRun/agentRun.js";
 import { isGitArtifactRefString, parseGitArtifactRef } from "../artifacts/gitArtifactRef.js";
-import { contextSnapshotRef } from "../context/contextSnapshot.js";
-import { buildRunContextDelta, buildRunContextPack, contextSnapshotDeltaRefIds, expandRunContextRef, freezeReviewStageContextSnapshot, freezeRunContextSnapshot, freezeWorkItemExecutionAssignmentContextSnapshot, readRunContextSnapshot, synthesisSourceRunIds } from "../context/runContextPack.js";
+import { contextContentDigest, contextSnapshotRef } from "../context/contextSnapshot.js";
+import { sourceRunContextValue } from "../context/sourceRunContext.js";
+import { buildRunContextDelta, buildRunContextPack, contextSnapshotDeltaRefIds, expandRunContextRef, freezeReviewStageContextSnapshot, freezeRunContextSnapshot, freezeWorkItemExecutionAssignmentContextSnapshot, freezeCandidateContextSnapshot, readRunContextSnapshot, synthesisSourceRunIds } from "../context/runContextPack.js";
 import { createRunInput } from "../context/runInputContract.js";
 import { parseTaskCatalogOptions, readTaskCatalog, renderTaskCatalog } from "../context/taskCatalog.js";
-import { assertContextRecordReadable } from "../context/taskContext.js";
+import { assertContextRecordReadable, readTaskContextResource } from "../context/taskContext.js";
 import { boundedDocument, readOptions, messageReceipt, recordPage } from "../output/boundedRead.js";
 import { referencedWakeRunIds } from "../context/wakeRunReferences.js";
 import { completeProcessing, releaseProcessing } from "../coordination/workMailbox.js";
@@ -19,7 +20,7 @@ import { createExecutionGroup, createReviewExecutionAssignment, createWorkItemEx
 import { projectWorkItemExecution } from "../execution/workItemExecutionProjection.js";
 import { dispatchWorkItemSynthesis, selectedWorkItemSynthesisProducers } from "../execution/workItemMainRun.js";
 import { createRoleSessionSet, roleAgentSessionResumeMode, roleSessionControlTarget, updateTaskRoleProviderRuntime } from "../executor/agentExecutor.js";
-import { resolveEffectiveLaunch } from "../executor/effectiveLaunch.js";
+import { resolveEffectiveLaunch, effectiveLaunchWithTaskMainWorkspace } from "../executor/effectiveLaunch.js";
 import { cancelInputRequest } from "../input/inputRequest.js";
 import { retireExactActiveRun, terminalizeExactTaskRun, validateExactRunReviewRound } from "../lifecycle/exactRunTerminalization.js";
 import { resolveTaskInputControl } from "../message/inputControlResolution.js";
@@ -72,6 +73,8 @@ import { runGrantCommand } from "./grantCommands.js";
 import { hasAgentConfigOptions, hasNoRoleMutation, parseRoleOptions, patchRoleAgentBinding, roleOptionSpecs, roleProfilePatch } from "./roleConfiguration.js";
 import { assertRoleRuntimeMutationAllowed } from "./roleRuntimeGuard.js";
 import { hasRoleLaunchContextOptions, validateConfiguredRoleSkills } from "./roleSkillValidation.js";
+import { requireManagedGlobalCaller } from "../runtime/managedCaller.js";
+import { hasManagedIdentity } from "../runtime/managedIdentity.js";
 import { nonLeaderActivationIdentity, runTaskActivationCommand } from "./taskActivationCommands.js";
 import { assertTaskOpen, clock, exactPositionals, leaderActionEventPayload, leaderMailbox, notifyMailbox, optionalNonEmptyOption, output, parseMultiValueTail, parseTail, presentTime, recordTaskEvent, recordTaskEventRecord, requiredOption, requiredText, requireTask, roleMailbox, taskActor, taskMailbox, taskRef, trimmed } from "./taskCommandSupport.js";
 import { assertTaskCompletionPublishedTreeProof } from "./taskCompletionGate.js";
@@ -791,6 +794,15 @@ function parseSubmissionIntentOption(raw, usage) {
     throw usageError(`--intent must be one of ${TASK_SUBMISSION_INTENTS.join(", ")}: ${raw}.`, usage);
 }
 export function submitOperatorMessage(body, taskId, store, options = {}, intent, submissionKey) {
+    // Public terminals and ordinary unmanaged Agents retain the submission
+    // route. Managed callers cannot turn a Task Assignment into Operator input.
+    const callerEnvironment = options.environment ?? {};
+    if (hasManagedIdentity(callerEnvironment)) {
+        if (callerEnvironment.YUI_SESSION_SCOPE !== "global" || callerEnvironment.YUI_ROLE !== "operator") {
+            throw usageError("Operator submission requires a public caller or the current global Operator.");
+        }
+        requireManagedGlobalCaller(store, callerEnvironment);
+    }
     const now = clock(options);
     const effectiveIntent = normalizeSubmissionIntent(intent);
     const result = store.transaction((tx) => {
@@ -3401,6 +3413,7 @@ function updateWork(args, store, options) {
                 : { taskMainSnapshot: options.directTaskMainSnapshot })
         }, now);
         tx.saveWorkItem(task.id, updated);
+        freezeCandidateContextSnapshot(tx, updated.candidates.at(-1), now);
         recordTaskEvent(tx, task.id, "work.updated", {
             workItemId: updated.id,
             status: updated.status,
@@ -3452,8 +3465,8 @@ export function requireWorkItemAssignee(item) {
     return item.assignee;
 }
 function dispatchWork(args, store, options) {
-    const usage = "Task work dispatch usage: yui task work dispatch <task>/<work> [--input <text>] [--lane-role <role> ...].";
-    const parsed = parseMultiValueTail(args, new Set(["--input"]), new Set(["--lane-role"]), usage);
+    const usage = "Task work dispatch usage: yui task work dispatch <task>/<work> [--input <text>] [--context-ref <store/refId@digest> ...] [--lane-role <role> ...].";
+    const parsed = parseMultiValueTail(args, new Set(["--input"]), new Set(["--lane-role", "--context-ref"]), usage);
     exactPositionals(parsed.positionals, 1, usage);
     const requestedLaneRoles = parsed.multiOptions.get("--lane-role") ?? [];
     const now = clock(options);
@@ -3461,6 +3474,7 @@ function dispatchWork(args, store, options) {
         const item = requireWorkItem(tx, parsed.positionals[0], options);
         const task = requireTask(tx, item.taskId);
         taskActor(tx, options, task.id);
+        const requiredResources = readDispatchContextRefs(tx, task.id, parsed.multiOptions.get("--context-ref") ?? [], options.environment);
         if (task.status !== "active")
             throw usageError(inactiveTaskMessage(task, "dispatch"));
         assertTaskExecutionEnabled(task, "dispatching work");
@@ -3520,7 +3534,7 @@ function dispatchWork(args, store, options) {
                 purpose: "execution",
                 workItemId: item.id,
                 workspace
-            }, now, "controller");
+            }, now, "controller", undefined, undefined, requiredResources);
             const run = createRun(runId, task.id, role.name, roleAgentSessionResumeMode(tx.getTaskRoleSessionSet(task.id, role.name), effective.agentId, effective), createRunInput({
                 source: { type: "yui", channel: "workitem-dispatch" },
                 directive: rawInput,
@@ -3552,7 +3566,8 @@ function dispatchWork(args, store, options) {
         const assignmentContext = contextSnapshotRef(freezeWorkItemExecutionAssignmentContextSnapshot(tx, {
             taskId: task.id,
             workItemId: item.id,
-            executionGroupId: groupId
+            executionGroupId: groupId,
+            requiredResources
         }, now));
         const plans = roles.map((role, index) => {
             const laneId = `${groupId}-lane-${index + 1}`;
@@ -3657,6 +3672,45 @@ function dispatchWork(args, store, options) {
         ? `Direct WorkItem AgentRun queued as ${dispatch.runs[0].id}\n`
         : `Dispatch queued for ${dispatch.runs.length} replicated Lanes\n`;
 }
+/** Explicit, bounded reads; prose never grants access or selects records. */
+export function readDispatchContextRefs(store, taskId, selectors, environment = {}) {
+    if (selectors.length > 16 || new Set(selectors).size !== selectors.length) {
+        throw usageError("Dispatch requires at most 16 distinct --context-ref values.");
+    }
+    return selectors.flatMap(selector => {
+        const match = /^([^/]+)\/(.+)@([0-9a-f]{64})$/u.exec(selector);
+        if (match === null) {
+            throw usageError(`Invalid required Context reference: ${selector}. Use store/refId@digest from task context list/inspect.`);
+        }
+        const [, family, refId, digest] = match;
+        try {
+            const entry = readTaskContextResource(store, taskId, {
+                store: family, refId: refId, digest: digest
+            }, environment);
+            const resources = [{
+                    ref: { ...entry.ref, layer: "L4", evidenceOf: "dispatch-required" },
+                    value: entry.value
+                }];
+            // Selecting a result Message selects its already-authorized original
+            // result too, not just a pointer the receiving Assignment cannot expand.
+            if (family === "task-message" && "result" in entry) {
+                const message = entry.value;
+                const source = store.getRun(taskId, message.resultRef.runId);
+                const value = sourceRunContextValue(source);
+                resources.push({
+                    ref: { layer: "L4", store: "source-run", refId: source.id,
+                        revision: source.updatedAt, digest: contextContentDigest(value),
+                        evidenceOf: "dispatch-required", summary: `Original result for Message ${message.id}` },
+                    value
+                });
+            }
+            return resources;
+        }
+        catch (error) {
+            throw usageError(`Required Context reference ${selector} cannot be frozen: ${error instanceof Error ? error.message : String(error)} Read an authorized current reference, correct the selection or include the requirement in the WorkItem, then dispatch again.`);
+        }
+    });
+}
 function replicatedProducerAssignmentInput(input, requiresCodeRef) {
     return [
         input,
@@ -5040,12 +5094,20 @@ function retryRunOperation(args, store, options) {
                 throw dataError(`AgentRun ${previous.id} direct WorkItem workspace is missing or has drifted.`);
             }
         }
-        const effective = retryLane?.effective ?? resolveEffectiveLaunch({
-            role,
-            purpose: previous.purpose,
-            ...(retryManagedWorkspace === undefined ? {} : { workspace: retryManagedWorkspace }),
-            ...(retryItem === null ? {} : { workItemWriteProjectIds: retryItem.writeProjectIds })
-        });
+        // Direct Task delivery resumes the native Session's captured authority.
+        // New source/Role defaults are adopted only after formal replacement.
+        const directSession = retryItem === null && previous.purpose === "execution"
+            && retryManagedWorkspace?.owner.type === "task"
+            ? sessions?.sessions[role.activeAgentId] : undefined;
+        const effective = retryLane?.effective
+            ?? (directSession === undefined ? undefined
+                : effectiveLaunchWithTaskMainWorkspace(directSession.effective, retryManagedWorkspace))
+            ?? resolveEffectiveLaunch({
+                role,
+                purpose: previous.purpose,
+                ...(retryManagedWorkspace === undefined ? {} : { workspace: retryManagedWorkspace }),
+                ...(retryItem === null ? {} : { workItemWriteProjectIds: retryItem.writeProjectIds })
+            });
         const runId = tx.nextRunId(task.id);
         const runningGroup = retryGroup === undefined || retryLane === undefined
             ? undefined
@@ -5071,13 +5133,19 @@ function retryRunOperation(args, store, options) {
         const input = retriesSynthesisMain
             ? previous.inputs[0].input
             : (() => {
+                // A retry keeps the explicit frozen handoff, not today's mutable
+                // versions of those records. Legacy Runs without a Snapshot retain
+                // the existing explicit recovery from current facts.
+                const requiredResources = previous.inputs[0].input.contextSnapshotRef === undefined
+                    ? []
+                    : readRunContextSnapshot(tx, previous).resources.filter(entry => entry.ref.evidenceOf === "dispatch-required");
                 const retrySnapshot = freezeRunContextSnapshot(tx, {
                     taskId: task.id,
                     roleName: role.name,
                     purpose: previous.purpose,
                     ...(retryManagedWorkspace === undefined ? {} : { workspace: retryManagedWorkspace }),
                     ...(previous.workItemId === undefined ? {} : { workItemId: previous.workItemId })
-                }, now, "controller", retryGroup?.assignment.contextSnapshotRef);
+                }, now, "controller", retryGroup?.assignment.contextSnapshotRef, undefined, requiredResources, "frozen");
                 return createRunInput({
                     source: {
                         type: "yui",
@@ -5200,12 +5268,13 @@ function taskReviewProvenance(store, task, options, expected) {
                 break;
             }
         }
-        if (headIndex < 0) {
-            throw dataError(`Committed Integration provenance is unavailable for Project ${projectId}@${commit}.`);
-        }
-        const head = committedAttempts[headIndex];
-        const lineage = committedAttempts.slice(0, headIndex + 1)
-            .filter(({ targetRef }) => targetRef === head.targetRef);
+        const target = store.getTaskWorkspace(task.id)?.entries.find(entry => entry.projectId === projectId)?.branch ?? committedAttempts[headIndex]?.targetRef;
+        // A direct Task-main repair has no Integration at its new head. It is
+        // still reviewable; conservatively exclude prior producers on this target
+        // from reviewing it. This is an independence fence, not ancestry or proof
+        // that any prior report validates the current head.
+        const lineage = (headIndex < 0 ? committedAttempts : committedAttempts.slice(0, headIndex + 1))
+            .filter(({ targetRef }) => targetRef === target);
         for (const committed of lineage) {
             if (committed.source.kind !== "work-item")
                 continue;

package/dist/commands/taskIntegrationCommands.js

@@ -7,6 +7,7 @@ import { NodeGitWorkspace } from "../repository/gitWorkspace.js";
 import { assertProjectActive, resolveProject } from "../repository/project.js";
 import { FileTaskWorkspacePreparer } from "../repository/taskWorkspacePreparer.js";
 import { assertTaskDeliveryAuthority as taskLocalActor } from "../task/taskAuthority.js";
+import { taskIntegrationTargetCheckout } from "../task/taskAuthority.js";
 import { resolveTaskRecordReference } from "../task/taskRecordReference.js";
 import { governingWorkItemCandidate } from "../workItem/workItem.js";
 import { workspaceProjectEntry } from "../worktree/managedWorkspace.js";
@@ -132,6 +133,7 @@ async function start(args, store, home, now, options) {
     if (targetRef === undefined) {
         throw usageError(`Task main worktree is not ready; reconcile the Task first: ${task.id}.`);
     }
+    taskIntegrationTargetCheckout(store, options.environment, task.id, project.id, targetRef);
     const expectedHead = (await new NodeGitWorkspace().inspect(mainEntry.path, targetRef)).baseCommit;
     const snapshotEntry = candidate.workspace.entries.find(({ projectId }) => projectId === project.id);
     const resultCommit = candidate.gitSnapshot.projects.find(({ projectId }) => projectId === project.id)?.commit;
@@ -139,7 +141,7 @@ async function start(args, store, home, now, options) {
         throw usageError(`WorkItem result Project snapshot is incomplete: ${workItem.id}/${project.id}.`);
     }
     const integration = store.transaction((tx) => {
-        taskLocalActor(tx, options.environment, task.id);
+        taskIntegrationTargetCheckout(tx, options.environment, task.id, project.id, targetRef);
         const created = createIntegrationAttempt({
             id: tx.nextIntegrationAttemptId(task.id),
             taskId: task.id,

package/dist/commands/taskUpstreamCommands.js

@@ -6,7 +6,7 @@ import { createIntegrationAttempt } from "../integration/integrationAttempt.js";
 import { NodeGitWorkspace } from "../repository/gitWorkspace.js";
 import { FileTaskWorkspacePreparer } from "../repository/taskWorkspacePreparer.js";
 import { workspaceProjectEntry } from "../worktree/managedWorkspace.js";
-import { taskLocalActor } from "../task/taskAuthority.js";
+import { taskLocalActor, assertTaskProjectWriteAuthority } from "../task/taskAuthority.js";
 export async function runTaskUpstreamCommand(args, store, home, options = {}) {
     const [command, ...rest] = args;
     if (command === "integrate")
@@ -71,6 +71,7 @@ async function integrateUpstream(args, store, home, options) {
         let phase = "prepare";
         let integrationId;
         try {
+            assertTaskProjectWriteAuthority(store, options.environment, task.id, binding.projectId);
             const project = store.getProject(binding.projectId);
             if (project === null)
                 throw usageError(`Project not found: ${binding.projectId}.`);
@@ -94,6 +95,7 @@ async function integrateUpstream(args, store, home, options) {
                 branch: binding.baseRef
             });
             const attempt = store.transaction((tx) => {
+                assertTaskProjectWriteAuthority(tx, options.environment, task.id, binding.projectId);
                 const created = createIntegrationAttempt({
                     id: tx.nextIntegrationAttemptId(task.id),
                     taskId: task.id,

package/dist/context/runContextPack.js

@@ -10,7 +10,112 @@ import { managedWorkspaceKey } from "../worktree/managedWorkspace.js";
 import { contextContentDigest, contextSnapshotRef, createContextSnapshot, validateContextSnapshot } from "./contextSnapshot.js";
 import { MAX_SYNTHESIS_SOURCE_RUNS, sourceRunContextValue } from "./sourceRunContext.js";
 export const RUN_CONTEXT_PACK_SCHEMA_VERSION = 1;
-export function freezeRunContextSnapshot(store, run, now, frozenBy = "controller", baselineRef, sourceRunIds) {
+function mergeRequiredContext(automatic, required, requiredPolicy = "current") {
+    const entries = new Map(automatic.map(entry => [`${entry.ref.store}/${entry.ref.refId}`, entry]));
+    for (const entry of required) {
+        const key = `${entry.ref.store}/${entry.ref.refId}`;
+        const existing = entries.get(key);
+        if (requiredPolicy === "current" && existing !== undefined && existing.ref.digest !== entry.ref.digest) {
+            throw new Error(`Required Context changed during dispatch: ${key}. Read its current reference and dispatch again.`);
+        }
+        entries.set(key, entry);
+    }
+    return [...entries.values()];
+}
+/** Pin the original result together with the candidate, using the existing
+ * immutable Snapshot store rather than a second result/provenance ledger. */
+export function freezeCandidateContextSnapshot(store, candidate, now) {
+    if (candidate.source.type !== "run")
+        return undefined;
+    const source = store.getRun(candidate.taskId, candidate.source.runId);
+    if (source === null || source.taskId !== candidate.taskId
+        || source.workItemId !== candidate.workItemId || source.purpose !== "execution"
+        || source.status !== "completed" || source.result === undefined
+        || Date.parse(source.updatedAt) > Date.parse(candidate.createdAt)) {
+        throw new Error(`Candidate source report is missing or mismatched: ${candidate.workItemId}/${candidate.id}.`);
+    }
+    const evidenceOf = `${candidate.workItemId}/${candidate.id}`;
+    const report = materialize("L4", "source-run", source.id, sourceRunContextValue(source));
+    const resources = [
+        materialize("L3", "candidate", evidenceOf, candidate),
+        { ...report, ref: { ...report.ref, evidenceOf } }
+    ];
+    const snapshot = createContextSnapshot({
+        id: store.nextContextSnapshotId(candidate.taskId),
+        taskId: candidate.taskId, scope: "workitem", scopeRef: `candidate:${evidenceOf}`,
+        sequence: 1, refs: resources.map(({ ref }) => ref), resources, acceptRefs: [],
+        frozenAt: now, frozenBy: "controller"
+    });
+    store.saveContextSnapshot(snapshot);
+    return snapshot;
+}
+function candidateReviewContext(store, candidate) {
+    const identity = `${candidate.workItemId}/${candidate.id}`;
+    if (candidate.source.type === "direct") {
+        return [materialize("L3", "candidate", identity, candidate)];
+    }
+    const sourceRunId = candidate.source.runId;
+    const snapshots = store.listContextSnapshots(candidate.taskId).filter(snapshot => snapshot.scope === "workitem" && snapshot.scopeRef === `candidate:${identity}`);
+    if (snapshots.length !== 1) {
+        throw new Error(`Frozen candidate report is unavailable: ${identity}. Inspect source Run ${candidate.taskId}/${sourceRunId}; for a new Review use newly authorized delivery with a newly captured Candidate. Historical Snapshots are not rewritten.`);
+    }
+    const snapshot = validateContextSnapshot(snapshots[0]);
+    const proof = snapshot.resources.find(({ ref }) => ref.store === "candidate" && ref.refId === identity);
+    const report = snapshot.resources.find(({ ref }) => ref.store === "source-run"
+        && ref.refId === sourceRunId && ref.evidenceOf === identity);
+    const source = store.getRun(candidate.taskId, sourceRunId);
+    if (proof?.ref.digest !== contextContentDigest(candidate) || report === undefined
+        || source === null || source.status !== "completed" || source.result === undefined
+        || source.taskId !== candidate.taskId || source.workItemId !== candidate.workItemId
+        || source.purpose !== "execution"
+        || report.ref.digest !== contextContentDigest(sourceRunContextValue(source))) {
+        throw new Error(`Frozen candidate source/report drifted: ${identity}. Inspect the exact source and capture a new Candidate; do not substitute a newer result.`);
+    }
+    return [proof, report];
+}
+/** Reuse only exact head/target evidence. Temporal ordering and a shared branch
+ * name do not prove ancestry; absent proof is a reviewable evidence gap. */
+function taskReviewCandidateSources(store, taskId, heads) {
+    const selected = new Map();
+    const select = (candidate) => selected.set(`${candidate.workItemId}/${candidate.id}`, candidate);
+    const workspace = store.getTaskWorkspace(taskId);
+    const attempts = store.listIntegrationAttempts(taskId);
+    const items = store.listWorkItems(taskId);
+    const unmatchedHeads = [];
+    for (const { projectId, commit } of heads.projects) {
+        const targetRef = workspace?.entries.find(entry => entry.projectId === projectId)?.branch;
+        let matched = false;
+        for (const attempt of attempts.filter(entry => entry.projectId === projectId
+            && entry.status === "committed" && entry.candidateCommit === commit
+            && entry.targetRef === targetRef)) {
+            if (attempt.source.kind !== "work-item")
+                continue;
+            const source = attempt.source;
+            const item = store.getWorkItem(taskId, source.workItemId);
+            const candidate = [...(item?.candidates ?? [])].reverse().find(entry => entry.gitSnapshot?.projects.some(project => project.projectId === projectId && project.commit === source.resultCommit));
+            if (candidate !== undefined) {
+                select(candidate);
+                matched = true;
+            }
+        }
+        for (const item of items) {
+            const candidate = [...item.candidates].reverse().find(entry => entry.taskMainSnapshot?.projects.some(project => project.projectId === projectId && project.headCommit === commit
+                && project.branch === targetRef)
+                || entry.gitSnapshot?.projects.some(project => project.projectId === projectId && project.commit === commit));
+            if (candidate !== undefined) {
+                select(candidate);
+                matched = true;
+            }
+        }
+        if (!matched)
+            unmatchedHeads.push(`${projectId}@${commit}`);
+    }
+    return { candidates: [...selected.values()], unmatchedHeads };
+}
+export function freezeRunContextSnapshot(store, run, now, frozenBy = "controller", baselineRef, sourceRunIds, requiredResources = [], 
+// Only retry of a validated prior Snapshot inherits frozen values over live
+// automatic context; a new dispatch must still match current references.
+requiredPolicy = "current") {
     if (baselineRef !== undefined) {
         const baseline = store.getContextSnapshot(run.taskId, baselineRef.id);
         if (baseline === null
@@ -28,7 +133,7 @@ export function freezeRunContextSnapshot(store, run, now, frozenBy = "controller
             ...collectRunContextOverlays(store, run),
             ...collectSourceRunContext(store, run, sourceRunIds)
         ];
-        const resources = [...new Map([...baseline.resources, ...overlays].map((entry) => [
+        const resources = [...new Map(mergeRequiredContext([...baseline.resources, ...overlays], requiredResources, requiredPolicy).map((entry) => [
                 contextRefIdentity(entry.ref),
                 entry
             ])).values()].sort((left, right) => (contextRefIdentity(left.ref).localeCompare(contextRefIdentity(right.ref))));
@@ -60,7 +165,7 @@ export function freezeRunContextSnapshot(store, run, now, frozenBy = "controller
             ? "workitem"
             : "task";
     const scopeRef = run.reviewRoundId ?? run.workItemId;
-    const materialized = collectAuthorizedContext(store, run);
+    const materialized = mergeRequiredContext(collectAuthorizedContext(store, run), requiredResources, requiredPolicy);
     const previous = store.listContextSnapshots(run.taskId)
         .filter((candidate) => candidate.scope === scope && candidate.scopeRef === scopeRef)
         .sort((left, right) => left.sequence - right.sequence)
@@ -117,7 +222,7 @@ export function freezeWorkItemExecutionAssignmentContextSnapshot(store, input, n
             materialized.push(materialize("L1", "project-knowledge", `${project.id}:${entry.id}`, { projectId: project.id, ...entry }));
         }
     }
-    const resources = [...new Map(materialized.map((entry) => [
+    const resources = [...new Map(mergeRequiredContext(materialized, input.requiredResources ?? []).map((entry) => [
             contextRefIdentity(entry.ref),
             entry
         ])).values()].sort((left, right) => (contextRefIdentity(left.ref).localeCompare(contextRefIdentity(right.ref))));
@@ -365,7 +470,14 @@ function collectAuthorizedContext(store, run) {
         const round = store.getReviewRound(task.id, run.reviewRoundId);
         if (round === null)
             throw new Error(`AgentRun ReviewRound not found: ${run.reviewRoundId}.`);
-        result.push(materialize("L3", "review-round", round.id, round));
+        let roundContext = materialize("L3", "review-round", round.id, round);
+        if (round.scope === "work-item") {
+            const item = store.getWorkItem(task.id, round.workItemId);
+            const candidate = item?.candidates.find(({ id }) => id === round.candidateId);
+            if (candidate === undefined)
+                throw new Error(`Review candidate is unavailable: ${round.candidateId}.`);
+            result.push(...candidateReviewContext(store, candidate));
+        }
         if (round.scope === "task") {
             for (const item of store.listWorkItems(task.id).filter(({ status }) => status !== "retired")) {
                 const candidate = governingWorkItemCandidate(item);
@@ -374,7 +486,22 @@ function collectAuthorizedContext(store, run) {
                 result.push(materialize("L3", "candidate", `${item.id}/${candidate.id}`, candidate));
                 result.push(...candidateArtifacts(task.id, [candidate]));
             }
+            const evidence = taskReviewCandidateSources(store, task.id, round.taskCandidate);
+            // Existing pointer metadata exposes the gap without changing the Round,
+            // inventing validation, or adding another persisted evidence record.
+            roundContext = {
+                ...roundContext, ref: {
+                    ...roundContext.ref,
+                    summary: `Task-final Review ${round.id}. Producer reports are evidence only for their named Candidate, not validation of the entire Task head.${evidence.unmatchedHeads.length === 0 ? ""
+                        : ` Producer evidence gap: ${evidence.unmatchedHeads.join(", ")}. Review these fixed heads and report missing validation; the gap does not prohibit review.`}`
+                }
+            };
+            for (const candidate of evidence.candidates) {
+                result.push(...candidateReviewContext(store, candidate));
+                result.push(...candidateArtifacts(task.id, [candidate]));
+            }
         }
+        result.push(roundContext);
         if (round.deltaRecheck !== undefined) {
             const previous = store.getReviewRound(task.id, round.deltaRecheck.previousReviewRoundId);
             const previousRun = previous?.reviewerRunId === undefined

package/dist/context/sourceRunContext.js

@@ -1,7 +1,9 @@
 import { MAX_RUN_RESULT_OUTPUT_BYTES } from "../domain/agentResultTransport.js";
 export const MAX_SYNTHESIS_SOURCE_RUNS = 8;
-export const MAX_CONTEXT_SOURCE_RUNS = MAX_SYNTHESIS_SOURCE_RUNS + 1;
-export const MAX_CONTEXT_SOURCE_RUN_BYTES = MAX_CONTEXT_SOURCE_RUNS * (MAX_RUN_RESULT_OUTPUT_BYTES + 16 * 1024);
+// A Task review may combine several candidate reports, synthesis and
+// continuation evidence. Preserve the existing aggregate byte ceiling.
+export const MAX_CONTEXT_SOURCE_RUNS = 64;
+export const MAX_CONTEXT_SOURCE_RUN_BYTES = (MAX_SYNTHESIS_SOURCE_RUNS + 1) * (MAX_RUN_RESULT_OUTPUT_BYTES + 16 * 1024);
 /**
  * Frozen input for synthesis. The main Agent needs the producer identity and
  * exact result, not another copy of its prompt history, launch configuration,

package/dist/context/taskContext.js

@@ -3,6 +3,7 @@ import { isGitArtifactRefString, parseGitArtifactRef } from "../artifacts/gitArt
 import { taskNotFound, usageError } from "../errors/cliError.js";
 import { expandTaskMessageResult } from "../message/message.js";
 import { resolveManagedTaskReader } from "../runtime/managedCaller.js";
+import { hasManagedIdentity } from "../runtime/managedIdentity.js";
 import { providerRetryProjection } from "../runtime/providerRetry.js";
 import { projectTaskRemoteDeliveryFromStore } from "../task/remoteDeliveryService.js";
 import { retiredTaskRecordIds, TASK_RECORD_RETIRED_EVENT } from "../task/taskRecordRetirement.js";
@@ -64,6 +65,10 @@ export function readTaskContext(store, taskId, environment = {}) {
                 store, total, returned: records.filter(record => record.ref.store === store).length
             })),
             discovery: `task context list ${taskId} --store <store>`,
+            commandDiscovery: {
+                help: "yui help", describe: "yui --json help",
+                note: "Help and completion share the current caller's offline command view. Follow that view for operation-specific discovery; execution always revalidates authority."
+            },
             detail: `task context inspect ${taskId} --store <store> --ref <refId> --digest <digest>`,
             attention,
             records, count,
@@ -153,6 +158,11 @@ export function readTaskContextDelta(store, taskId, input, environment = {}) {
     });
 }
 export function inspectTaskContext(store, taskId, selector, environment = {}) {
+    const response = readTaskContextResource(store, taskId, selector, environment);
+    return boundedDocument(response, `task:${taskId}/${selector.store}/${selector.refId}`, selector.cursor);
+}
+/** The same authorized read as inspect, before transport pagination. */
+export function readTaskContextResource(store, taskId, selector, environment = {}) {
     return store.readTransaction((reader) => {
         const scope = authorizeContext(reader, taskId, environment);
         const value = isAllowed(scope.allow, selector.store, selector.refId)
@@ -172,7 +182,7 @@ export function inspectTaskContext(store, taskId, selector, environment = {}) {
                 ? { result: expansion.result } : {}),
             ...(selector.store === "run" ? { execution: runExecutionObservation(value, reader.getTaskRoleSessionSet(taskId, value.roleName)?.providerBinding, reader.listEventsByType(taskId, ["runtime.agent-error"])) } : {}),
         };
-        return boundedDocument(response, `task:${taskId}/${selector.store}/${selector.refId}`, selector.cursor);
+        return response;
     });
 }
 /** Discover one authorized family without copying its bodies or unrelated Task
@@ -269,8 +279,7 @@ export function resolveContextReader(store, environment) {
         throw usageError("Only Operator may read Task context from a global Session.");
     }
     if (caller === undefined && environment.YUI_SESSION_SCOPE === undefined
-        && (environment.YUI_ROLE !== undefined || environment.YUI_NATIVE_SESSION_ID !== undefined
-            || environment.YUI_TASK_ID !== undefined || environment.YUI_AGENT_ID !== undefined)) {
+        && hasManagedIdentity(environment)) {
         throw usageError("Incomplete managed Context caller identity.");
     }
     if (environment.YUI_SESSION_SCOPE !== undefined && !["task", "global"].includes(environment.YUI_SESSION_SCOPE)) {