@zq-silk/yui 2.1.0 → 2.3.0

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";
@@ -54,7 +55,7 @@ import { queueLeaderWakeup } from "../scheduler/wakeupQueue.js";
 import { planningRuntimeCwd } from "../storage/homeLayout.js";
 import { StorageConflictError } from "../storage/taskStore.js";
 import { archiveDeliveryWarnings, archiveRetainedResources, renderArchiveDiagnostics, taskArchiveDiagnostics } from "../task/archiveDiagnostics.js";
-import { archiveSettlementChecks } from "../task/archivePreflight.js";
+import { archiveExecutionChecks, archiveSettlementChecks } from "../task/archivePreflight.js";
 import { projectCompletionReadiness } from "../task/completionReadiness.js";
 import { assertDraftTaskExecutionFree, validateDraftWorkItemEdit } from "../task/draftPlan.js";
 import { assertTaskRemoteDeliveryProof, projectTaskRemoteDeliveryFromStore } from "../task/remoteDeliveryService.js";
@@ -1299,12 +1300,9 @@ function archiveTaskCommand(args, store, options) {
                 ? assertTaskRemoteDeliveryProof(tx, task, options.archiveRemoteDeliveryProof)
                 : undefined;
         if (!request.force) {
-            const checks = archiveSettlementChecks(tx, task);
+            const checks = [...archiveSettlementChecks(tx, task), ...archiveExecutionChecks(tx, task.id, options.yuiHome)];
             if (checks.length > 0)
                 throw new CleanupInspectionError(checks);
-            if (task.cwd !== undefined || tx.listManagedWorkspaces(task.id).length > 0) {
-                throw usageError(`Task ${task.id} still has managed worktrees; clean them before archiving.`);
-            }
             const activeRole = tx.listRoles(task.id)
                 .find((role) => tx.getActiveRun(task.id, role.name) !== null);
             if (activeRole !== undefined) {
@@ -1321,7 +1319,7 @@ function archiveTaskCommand(args, store, options) {
                     + "stop that Session before archiving.");
             }
         }
-        const retainedResources = request.force ? archiveRetainedResources(tx, task) : [];
+        const retainedResources = archiveRetainedResources(tx, task);
         const warnings = request.force && remoteDelivery !== undefined ? archiveDeliveryWarnings(remoteDelivery) : [];
         const archived = { ...archiveTask(task, now, { by: actor }), executionGate: { state: "stopped" } };
         tx.saveTask(archived);
@@ -1350,8 +1348,9 @@ function archiveTaskCommand(args, store, options) {
                 authorizationSource: JSON.stringify(options.archiveLeaderAdmission.source)
             }),
             workspaceDisposition: request.disposition,
+            cleanup: "pending",
             ...(request.force ? {
-                force: "true", cleanup: "pending",
+                force: "true",
                 warnings: JSON.stringify(warnings),
                 retainedResources: JSON.stringify(retainedResources)
             } : {}),
@@ -3412,6 +3411,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,
@@ -3463,8 +3463,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);
@@ -3472,6 +3472,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");
@@ -3531,7 +3532,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,
@@ -3563,7 +3564,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}`;
@@ -3668,6 +3670,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,
@@ -5051,12 +5092,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
@@ -5082,13 +5131,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",
@@ -5211,12 +5266,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";
@@ -48,19 +49,8 @@ async function cleanupIntegration(args, store, home, environment) {
         && integration.status !== "failed") {
         throw usageError(`Integration is not terminal: ${integration.id}/${integration.status}.`);
     }
-    // rr4/finding-5: An Integration Attempt with an active DurableJob cannot be
-    // cleaned up — the runner may still be using its worktree. Block on queued,
-    // running, and unacknowledged unknown-needs-attention jobs owned by it.
-    const activeIntegrationJob = store.listDurableJobs(integration.taskId).find((job) => (job.owner.kind === "integration-attempt"
-        && job.owner.integrationAttemptId === integration.id
-        && (job.status === "queued"
-            || job.status === "running"
-            || (job.status === "unknown-needs-attention" && job.acknowledgedAt === undefined))));
-    if (activeIntegrationJob !== undefined) {
-        throw usageError(`Integration ${integration.id} has an active DurableJob: `
-            + `${activeIntegrationJob.id}/${activeIntegrationJob.status}. `
-            + "Cancel or acknowledge it before cleanup.");
-    }
+    // The service's shared owner inspection checks both Job settlement and
+    // current physical occupancy before any runtime or worktree is released.
     const result = await new GitIntegrationService(home, store).cleanup(integration, {
         authorize: () => taskLocalActor(store, environment, integration.taskId)
     });
@@ -69,9 +59,9 @@ async function cleanupIntegration(args, store, home, environment) {
     }
     return {
         output: result === "removed"
-            ? `Cleaned Integration worktree and check logs ${integration.id}\n`
-            : `Integration worktree and check logs already clean: ${integration.id}\n`,
-        data: { integrationId: integration.id, cleanup: result }
+            ? `Cleaned Integration worktree ${integration.id}; history and check logs retained\n`
+            : `Integration worktree already clean: ${integration.id}; history and check logs retained\n`,
+        data: { integrationId: integration.id, cleanup: result, historyRetained: true }
     };
 }
 async function start(args, store, home, now, options) {
@@ -132,6 +122,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 +130,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

@@ -158,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)
@@ -177,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