@zq-silk/yui 0.8.1 → 0.8.3

package/dist/commands/taskCommands.js

@@ -1,4 +1,4 @@
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 import { createRunAssignment } from "../context/runContextContract.js";
 import { buildRunContextPack, buildRunContextDelta, contextSnapshotDeltaRefIds, expandRunContextRef, freezeRunContextSnapshot } from "../context/runContextPack.js";
@@ -7,7 +7,9 @@ import { CliError, dataError, roleNotFound, runtimeError, taskNotFound, usageErr
 import { createTaskEvent } from "../event/taskEvent.js";
 import { clearMatchingLeaderStallAttention, isRoleRunStalled, RUN_PROGRESS_EVENT, RUN_RECOVERED_EVENT } from "../scheduler/roleRunStall.js";
 import { readCommandText } from "./textInput.js";
-import { createRoleSessionSet, roleAgentSessionResumeMode } from "../executor/agentExecutor.js";
+import { assertTaskCompletionPublishedTreeProof } from "./taskCompletionGate.js";
+import { createRoleSessionSet, roleAgentSessionResumeMode, updateTaskRoleProviderRuntime } from "../executor/agentExecutor.js";
+import { currentProviderActivation, transferProviderAuthority } from "../runtime/providerRuntimeIdentity.js";
 import { resolveEffectiveLaunch } from "../executor/effectiveLaunch.js";
 import { defaultTableWidth, renderTable } from "../output/table.js";
 import { formatTimestamp } from "../output/timePresentation.js";
@@ -16,7 +18,7 @@ import { createTaskMessage, taskMessageAuthorLabel } from "../message/message.js
 import { cancelInputRequest } from "../input/inputRequest.js";
 import { recoverExactAgentRun, terminalizeExactTaskRun, validateExactRunReviewRound } from "../lifecycle/exactRunTerminalization.js";
 import { resetTaskRoleSessionGeneration } from "../lifecycle/taskRoleSessionReset.js";
-import { activeRoleAgentBinding, copyGlobalRoleToTaskRole, createRole, createRoleAgentBinding, switchActiveRoleAgent, unbindRoleAgent, updateRole, updateRoleStatus } from "../role/role.js";
+import { copyGlobalRoleToTaskRole, createRole, createRoleAgentBinding, switchActiveRoleAgent, unbindRoleAgent, updateRole, updateRoleStatus } from "../role/role.js";
 import { agentRunDeliveryReceiptId, createAgentRun, withAgentRunContextSnapshot } from "../run/agentRun.js";
 import { projectRunRecovery, readRunRecoveryFacts } from "../run/recoveryProjection.js";
 import { matchYieldReceipt } from "../run/yieldReceipt.js";
@@ -35,10 +37,11 @@ import { blockingProviderContinuations, projectProviderContinuations } from "../
 import { runtimeObservationFromTaskEvent } from "../runtime/runtimeObservation.js";
 import { activateTask, addTaskProjectBinding, archiveTask, completeTask, createTask, retireTask, reopenTask, updateTaskMetadata } from "../task/task.js";
 import { resolveTaskRecordReference } from "../task/taskRecordReference.js";
+import { TASK_COMPLETION_PUBLISHED_TREE_AUTHORIZED_EVENT } from "../task/publicationReference.js";
 import { projectCompletionReadiness } from "../task/completionReadiness.js";
 import { resolveProject } from "../repository/project.js";
 import { acquireProjectMaintenanceLocks } from "../repository/projectMaintenanceLock.js";
-import { currentWorkItemCandidate, currentWorkItemExecutionGroup, workItemExecutionGroupById, createWorkItem, attachWorkItemExecutionGroup, updateWorkItemExecutionGroup, retireWorkItem, retryFailedWorkItem, submitWorkItemCandidate, updateWorkItemWriteProjects, updateWorkItemStatus } from "../workItem/workItem.js";
+import { currentWorkItemCandidate, governingWorkItemCandidate, currentWorkItemExecutionGroup, workItemExecutionGroupById, createWorkItem, attachWorkItemExecutionGroup, updateWorkItemExecutionGroup, retireWorkItem, retryFailedWorkItem, submitWorkItemCandidate, updateWorkItemWriteProjects, updateWorkItemStatus } from "../workItem/workItem.js";
 import { addExecutionLane, createExecutionGroup, resolveExecutionGroup, restartExecutionLane, updateExecutionLane } from "../execution/executionGroup.js";
 import { sameTaskFinalReviewContract, taskFinalReviewConfig, validateTaskFinalReviewContract } from "../review/taskFinalReviewContract.js";
 import { managedWorkspaceKey } from "../worktree/managedWorkspace.js";
@@ -79,8 +82,12 @@ function legacyWorkItemReviewConfig(config) {
 }
 function storedTaskFinalReviewContract(store, taskId) {
     const contracts = store.listWorkItems(taskId)
-        .flatMap(({ candidates }) => candidates)
-        .flatMap(({ taskFinalReviewContract }) => (taskFinalReviewContract === undefined ? [] : [taskFinalReviewContract]));
+        .flatMap((item) => {
+        const candidate = governingWorkItemCandidate(item);
+        return candidate?.taskFinalReviewContract === undefined
+            ? []
+            : [candidate.taskFinalReviewContract];
+    });
     const first = contracts[0];
     if (first === undefined)
         return undefined;
@@ -96,7 +103,7 @@ function storedTaskFinalReviewContract(store, taskId) {
  * acceptance, and completion mutation must present the same verified
  * capability; shared review-config drift is intentionally irrelevant.
  */
-function taskFinalReviewContractForMutation(store, taskId, options) {
+function taskFinalReviewContractForMutation(store, taskId, options, authorization = {}) {
     const supplied = options.taskFinalReviewContract;
     if (supplied !== undefined) {
         validateTaskFinalReviewContract(supplied);
@@ -112,6 +119,8 @@ function taskFinalReviewContractForMutation(store, taskId, options) {
     if (stored === undefined)
         return supplied;
     if (supplied === undefined) {
+        if (authorization.allowStoredWithoutSupplied === true)
+            return stored;
         throw usageError(`Task final-review contract is missing for ${taskId}.`);
     }
     if (!sameTaskFinalReviewContract(stored, supplied)) {
@@ -120,8 +129,8 @@ function taskFinalReviewContractForMutation(store, taskId, options) {
     return stored;
 }
 export function parseTaskCompletionRequest(args, summaryOverride) {
-    const usage = "Task complete usage: yui task complete <id> (--summary <text>|--summary-file <path|->) [--refresh-remote].";
-    const parsed = parseTail(args, new Set(["--summary", "--summary-file"]), usage, new Set(["--refresh-remote"]));
+    const usage = "Task complete usage: yui task complete <id> (--summary <text>|--summary-file <path|->) [--refresh-remote] [--accept-published-tree <publication-id>].";
+    const parsed = parseTail(args, new Set(["--summary", "--summary-file", "--accept-published-tree"]), usage, new Set(["--refresh-remote"]));
     exactPositionals(parsed.positionals, 1, usage);
     const inlineSummary = parsed.options.get("--summary");
     const summaryFile = parsed.options.get("--summary-file");
@@ -129,7 +138,14 @@ export function parseTaskCompletionRequest(args, summaryOverride) {
         throw usageError(`Specify exactly one of --summary or --summary-file.`, usage);
     }
     const summary = summaryOverride ?? readCommandText(inlineSummary, summaryFile, "--summary", usage);
-    return { taskId: parsed.positionals[0], summary };
+    const acceptedPublishedTreePublicationId = parsed.options.get("--accept-published-tree");
+    return {
+        taskId: parsed.positionals[0],
+        summary,
+        ...(acceptedPublishedTreePublicationId === undefined
+            ? {}
+            : { acceptedPublishedTreePublicationId })
+    };
 }
 /**
  * Check every read-only completion blocker before a caller resolves remote
@@ -143,7 +159,7 @@ export function parseTaskCompletionRequest(args, summaryOverride) {
  * terminalization precondition before attempting completion.  All blockers
  * are reported in one error instead of one per attempt.
  */
-export function preflightTaskCompletion(taskId, store, options = {}) {
+export function preflightTaskCompletion(taskId, store, options = {}, request = {}) {
     const task = requireTask(store, taskId);
     const actor = taskActor(options, task.id);
     if (task.status === "completed") {
@@ -156,7 +172,15 @@ export function preflightTaskCompletion(taskId, store, options = {}) {
     // Resolve and authenticate the durable Task-local gate before any remote
     // fetch or Integration write.  All checks below mirror the transactional
     // completion path, which remains the final CAS fence after reconciliation.
-    const taskFinalReviewContract = taskFinalReviewContractForMutation(store, task.id, options);
+    // A human/global Operator cannot present the exact managed Leader contract.
+    // For the explicit published-tree path only, let that caller authenticate
+    // the stored contract far enough to persist an exact authorization fact.
+    // The same command must return before any contract-governed completion
+    // mutation; the exact Leader later consumes the authorization with the real
+    // contract capability.
+    const authorizingPublishedTree = request.acceptedPublishedTreePublicationId !== undefined
+        && actor !== "leader";
+    const taskFinalReviewContract = taskFinalReviewContractForMutation(store, task.id, options, { allowStoredWithoutSupplied: authorizingPublishedTree });
     const activeTaskReview = store.listReviewRounds(task.id).some((round) => ((round.scope ?? "work-item") === "task"
         && (round.status === "pending" || round.status === "running")));
     // Issue 06: one shared readiness projection enumerates every blocker.
@@ -240,7 +264,6 @@ export function runTaskCommand(args, store, options = {}) {
         case "milestone": return taskMilestoneCommand(rest, store, options);
         case "event": return taskEventCommand(rest, store);
         case "continuation": return taskContinuationCommand(rest, store);
-        case "enter": return enterTaskRoleAlias(rest, store, options);
         default:
             throw usageError(command === undefined
                 ? "Task command is required."
@@ -429,8 +452,8 @@ function updateTaskCommand(args, store, options) {
 /** Compatibility helper for call sites that cannot yet handle foreground enter. */
 export function runTaskOutputCommand(args, store, options = {}) {
     const execution = runTaskCommand(args, store, options);
-    if (execution.kind === "enter") {
-        throw runtimeError("Task role enter requires foreground tmux handoff by the CLI.");
+    if (execution.kind !== "output") {
+        throw runtimeError("Task Role foreground runtime control requires the CLI.");
     }
     return execution.output;
 }
@@ -647,17 +670,42 @@ function completeTaskCommand(args, store, options) {
     const summary = request.summary;
     const now = clock(options);
     const result = store.transaction((tx) => {
-        const preflight = preflightTaskCompletion(request.taskId, tx, options);
+        const preflight = preflightTaskCompletion(request.taskId, tx, options, request);
         const { task, actor } = preflight;
         if (preflight.completed) {
             return {
                 task,
                 changed: false,
                 runtimeCleanupTargets: [],
-                finalReview: undefined
+                finalReview: undefined,
+                publishedTreeAuthorization: undefined
             };
         }
         const taskFinalContract = preflight.taskFinalReviewContract;
+        const publishedTreeProof = request.acceptedPublishedTreePublicationId === undefined
+            ? undefined
+            : assertTaskCompletionPublishedTreeProof(tx, task, request.acceptedPublishedTreePublicationId, options.completionPublishedTreeProof, actualTaskReviewCandidateForMutation(tx, task, options));
+        const requiresContractHandoff = publishedTreeProof !== undefined
+            && taskFinalContract !== undefined;
+        if (requiresContractHandoff && actor !== "leader") {
+            const existing = matchingPublishedTreeAuthorization(tx, publishedTreeProof);
+            const event = existing ?? recordTaskEventRecord(tx, task.id, TASK_COMPLETION_PUBLISHED_TREE_AUTHORIZED_EVENT, publishedTreeAuthorizationPayload(actor, publishedTreeProof), now);
+            enqueueWork(tx, leaderMailbox(task.id), wakeReason("published-tree-authorized", event.id), now, [eventRef(task.id, event.id)]);
+            return {
+                task,
+                changed: false,
+                runtimeCleanupTargets: [],
+                finalReview: undefined,
+                publishedTreeAuthorization: {
+                    event,
+                    proof: publishedTreeProof,
+                    created: existing === undefined
+                }
+            };
+        }
+        if (publishedTreeProof !== undefined && actor === "leader") {
+            requirePublishedTreeAuthorization(tx, publishedTreeProof);
+        }
         const roles = tx.listRoles(task.id);
         const activeRuns = roles
             .map((role) => ({ role, run: tx.getActiveAgentRun(task.id, role.name) }))
@@ -706,7 +754,8 @@ function completeTaskCommand(args, store, options) {
                 runtimeCleanupTargets: [],
                 finalReview,
                 resumedPendingFinalReview: pendingFinalReviewIds.has(finalReview.id),
-                terminalizedLeaderRun
+                terminalizedLeaderRun,
+                publishedTreeAuthorization: undefined
             };
         }
         // Issue 06: re-validate the full completion readiness inside the
@@ -729,6 +778,17 @@ function completeTaskCommand(args, store, options) {
         tx.clearOperatorNotification(task.id);
         tx.saveOperatorNotification(createTaskTerminalNotification(task.id, "completed", actor, summary, now));
         enqueueWork(tx, { kind: "operator" }, "task-terminal", now, [taskRef(task.id)]);
+        if (publishedTreeProof !== undefined) {
+            recordTaskEvent(tx, task.id, "task.completion-published-tree-accepted", {
+                by: actor,
+                projectId: publishedTreeProof.projectId,
+                publicationId: publishedTreeProof.publicationId,
+                reviewRoundId: publishedTreeProof.reviewRoundId,
+                localCommit: publishedTreeProof.localCommit,
+                remoteCommit: publishedTreeProof.remoteCommit,
+                tree: publishedTreeProof.tree
+            }, now);
+        }
         recordTaskEvent(tx, task.id, "task.completed", { by: actor, summary }, now);
         // A terminal Task must never leave a Task-lane signal that can wake it.
         // The durable records remain intact; only the derived mailbox work is
@@ -747,9 +807,21 @@ function completeTaskCommand(args, store, options) {
             runtimeCleanupTargets,
             finalReview: undefined,
             resumedPendingFinalReview: false,
-            terminalizedLeaderRun
+            terminalizedLeaderRun,
+            publishedTreeAuthorization: undefined
         };
     });
+    if (result.publishedTreeAuthorization !== undefined) {
+        notifyMailbox(options.runtime, leaderMailbox(result.task.id), result.task.id);
+        const authorization = result.publishedTreeAuthorization;
+        return output(authorization.created
+            ? `Authorized published-tree completion for ${result.task.id} as ${authorization.event.id}; exact Task Leader completion is required.\n`
+            : `Published-tree completion is already authorized for ${result.task.id} as ${authorization.event.id}; exact Task Leader completion is required.\n`, {
+            task: result.task,
+            authorizationEvent: authorization.event,
+            publishedTreeProof: authorization.proof
+        });
+    }
     if (result.changed) {
         for (const target of result.runtimeCleanupTargets) {
             // Cleanup owns an independent lifecycle lane. Never fall back to the
@@ -1192,8 +1264,12 @@ function taskRoleCommand(args, store, options) {
         return output(unbindTaskRole(rest, store, options));
     if (command === "reset")
         return resetTaskRole(rest, store, options);
-    if (command === "enter")
-        return enterTaskRole(rest, store, options);
+    if (command === "view")
+        return viewTaskRole(rest, store);
+    if (command === "takeover")
+        return transferTaskRoleAuthority(rest, store, options, "takeover");
+    if (command === "release")
+        return transferTaskRoleAuthority(rest, store, options, "release");
     throw usageError(command === undefined
         ? "Task role command is required."
         : `Unknown command: task role ${command}`);
@@ -1506,60 +1582,111 @@ function unbindTaskRole(args, store, options) {
     });
     return `Unbound Agent ${args[2]} from ${result.taskId}/${result.name}\n`;
 }
-function enterTaskRole(args, store, _options) {
-    const usage = "Task role enter usage: yui task role enter <task> <role> "
-        + "[--read-only | --read-write].";
-    const parsed = parseTail(args, new Set(), usage, new Set(["--read-only", "--read-write"]));
-    exactPositionals(parsed.positionals, 2, usage);
-    if (parsed.options.has("--read-only") && parsed.options.has("--read-write")) {
-        throw usageError("--read-only and --read-write are mutually exclusive.", usage);
-    }
-    const task = requireTask(store, parsed.positionals[0]);
+function viewTaskRole(args, store) {
+    const usage = "Task role view usage: yui task role view <task> <role>.";
+    exactPositionals(args, 2, usage);
+    const task = requireTask(store, args[0]);
     if (task.status !== "active") {
-        throw usageError(inactiveTaskMessage(task, "entering a role session"));
+        throw usageError(inactiveTaskMessage(task, "viewing a role session"));
     }
-    const role = requireRole(store, task.id, parsed.positionals[1]);
-    const access = parsed.options.has("--read-write") ? "read-write" : "read-only";
-    if (access === "read-write") {
-        assertTaskRoleWritableAttachAvailable(store, task.id, role.name);
+    const role = requireRole(store, task.id, args[1]);
+    const session = store.getRoleSession(task.id, role.name);
+    if (session === null || session.status === "stopped" || session.status === "broken") {
+        throw usageError(`Task Role has no live Provider view: ${task.id}/${role.name}.`);
     }
     return {
-        kind: "enter",
+        kind: "view",
         taskId: task.id,
         roleName: role.name,
-        access,
-        output: `Attaching to ${role.name} for ${task.id} (${access})\n`
+        access: "read-only",
+        output: `Viewing ${role.name} for ${task.id} (read-only)\n`
     };
 }
-/** Re-run after the tmux writer lease exists to close attach/launch races. */
-export function assertTaskRoleWritableAttachAvailable(store, taskId, roleName, options = {}) {
-    const role = requireRole(store, taskId, roleName);
-    if (store.getActiveAgentRun(taskId, roleName) !== null) {
-        throw usageError(`Role has an active managed Run; writable attach is unavailable: ${taskId}/${roleName}.`);
-    }
-    const session = store.getRoleSession(taskId, roleName);
-    if (activeRoleAgentBinding(role).adapterId === "claude"
-        && ((session !== null
-            && session.status !== "stopped"
-            && session.status !== "broken")
-            || options.isManagedProcessRunning?.() === true)) {
-        throw usageError(`A managed Claude process is still running; writable attach is unavailable: ${taskId}/${roleName}.`);
-    }
-}
-function enterTaskRoleAlias(args, store, options) {
-    const usage = "Task enter usage: yui task enter <task> [role] "
-        + "[--read-only | --read-write].";
-    const parsed = parseTail(args, new Set(), usage, new Set(["--read-only", "--read-write"]));
-    if (parsed.positionals.length < 1 || parsed.positionals.length > 2
-        || parsed.positionals.some((value) => value.trim().length === 0)) {
-        throw usageError(usage);
+function transferTaskRoleAuthority(args, store, options, action) {
+    const usage = `Task role ${action} usage: yui task role ${action} <task> <role>.`;
+    exactPositionals(args, 2, usage);
+    const now = clock(options);
+    try {
+        return store.transaction((tx) => {
+            const task = requireTask(tx, args[0]);
+            if (task.status !== "active") {
+                throw usageError(inactiveTaskMessage(task, `${action} Provider authority`));
+            }
+            const role = requireRole(tx, task.id, args[1]);
+            const sessions = tx.getTaskRoleSessionSet(task.id, role.name);
+            const session = sessions?.sessions[role.activeAgentId];
+            const binding = sessions?.providerBinding;
+            if (sessions === null || sessions === undefined || session === undefined
+                || binding === null || binding === undefined
+                || session.launchId === undefined
+                || session.status === "stopped" || session.status === "broken") {
+                throw new Error(`Task Role has no live managed Provider: ${task.id}/${role.name}.`);
+            }
+            const activation = currentProviderActivation(binding);
+            if (activation === null) {
+                throw new Error(`Provider Activation is not live: ${task.id}/${role.name}.`);
+            }
+            if (action === "takeover") {
+                const activeRun = tx.getActiveAgentRun(task.id, role.name);
+                if (sessions.inFlight === null || activeRun?.id !== sessions.inFlight.runId) {
+                    throw new Error(`Task Role has no active managed Run for takeover: ${task.id}/${role.name}.`);
+                }
+            }
+            if (action === "takeover"
+                && binding.authority.owner !== "controller"
+                && binding.authority.owner !== "human") {
+                throw new Error(`Provider authority is not Controller-owned: ${task.id}/${role.name}.`);
+            }
+            if (action === "release"
+                && binding.authority.owner !== "human"
+                && binding.authority.owner !== "controller") {
+                throw new Error(`Provider authority is not human-owned: ${task.id}/${role.name}.`);
+            }
+            const desiredOwner = action === "takeover" ? "human" : "controller";
+            const unchanged = binding.authority.owner === desiredOwner;
+            const updatedBinding = unchanged
+                ? binding
+                : transferProviderAuthority(binding, {
+                    expectedEpoch: binding.authority.epoch,
+                    expectedOwner: binding.authority.owner,
+                    owner: desiredOwner,
+                    holderId: action === "takeover" ? `human:${randomUUID()}` : activation.activationId,
+                    changedAt: now.toISOString()
+                });
+            const authority = updatedBinding.authority;
+            if (authority.owner !== "controller" && authority.owner !== "human") {
+                throw new Error("Provider authority transfer did not produce a writer.");
+            }
+            if (!unchanged) {
+                tx.saveTaskRoleSessionSet(updateTaskRoleProviderRuntime(sessions, updatedBinding, now));
+                recordTaskEvent(tx, task.id, "runtime.provider-authority-transferred", {
+                    role: role.name,
+                    owner: authority.owner,
+                    holderId: authority.holderId,
+                    epoch: String(authority.epoch)
+                }, now);
+            }
+            return {
+                kind: "authority",
+                action,
+                taskId: task.id,
+                roleName: role.name,
+                launchId: session.launchId,
+                nativeSessionId: session.nativeSessionId,
+                authority: {
+                    epoch: authority.epoch,
+                    owner: authority.owner,
+                    holderId: authority.holderId
+                },
+                output: action === "takeover"
+                    ? `Human authority ${unchanged ? "replayed" : "acquired"} for ${task.id}/${role.name} at epoch ${authority.epoch}.\n`
+                    : `Controller authority ${unchanged ? "replayed" : "restored"} for ${task.id}/${role.name} at epoch ${authority.epoch}.\n`
+            };
+        });
+    }
+    catch (error) {
+        throw usageError(messageOf(error), usage);
     }
-    return enterTaskRole([
-        parsed.positionals[0],
-        parsed.positionals[1] ?? LEADER_ROLE,
-        ...(parsed.options.has("--read-only") ? ["--read-only"] : []),
-        ...(parsed.options.has("--read-write") ? ["--read-write"] : [])
-    ], store, options);
 }
 function taskWorkCommand(args, store, options) {
     const [command, ...rest] = args;
@@ -2553,6 +2680,8 @@ function taskReviewCommand(args, store, options) {
     const [command, ...rest] = args;
     if (command === "request")
         return requestTaskReviewRound(rest, store, options);
+    if (command === "force-fresh")
+        return forceFreshTaskReviewRound(rest, store, options);
     if (command === "retry")
         return retryFailedTaskReviewRound(rest, store, options);
     if (command === "group")
@@ -3023,6 +3152,209 @@ function requestTaskReviewRound(args, store, options) {
             : `Task-final delta-recheck requested as ${round.id} (rechecks ${round.deltaRecheck.previousReviewRoundId})\n`
         : `Task-final Review is already ${round.status}: ${round.id}\n`, { reviewRound: round });
 }
+const TASK_FINAL_FORCE_FRESH_EVENT = "review.task-final-force-fresh-requested";
+/**
+ * Creates a distinct full Task-final ReviewRound only when the exact previous
+ * Round failed without producing semantic review evidence. The source Round,
+ * Run, findings, workspace, and terminal report remain immutable history; the
+ * linking Event is both the audit record and the idempotence key.
+ */
+function forceFreshTaskReviewRound(args, store, options) {
+    const usage = "Task review force-fresh usage: yui task review force-fresh <task>/<review-round>.";
+    exactPositionals(args, 1, usage);
+    const reference = taskRecordReference(args[0], "reviewRound", "ReviewRound reference", options);
+    const now = clock(options);
+    const result = store.transaction((tx) => {
+        const source = tx.getReviewRound(reference.taskId, reference.localId);
+        if (source === null) {
+            throw dataError(`ReviewRound not found: ${reference.taskId}/${reference.localId}.`);
+        }
+        const task = requireTask(tx, reference.taskId);
+        if (task.status !== "active")
+            throw usageError(`Task is not active: ${task.id}.`);
+        if (taskActor(options, task.id) !== "leader") {
+            throw usageError("Only the Task Leader may force a fresh Task-final ReviewRound.");
+        }
+        if ((source.scope ?? "work-item") !== "task") {
+            throw usageError(`ReviewRound ${source.id} is not a Task-final ReviewRound.`);
+        }
+        const replacementEvents = tx.listEvents(task.id).filter((event) => (event.type === TASK_FINAL_FORCE_FRESH_EVENT
+            && event.payload.sourceReviewRoundId === source.id));
+        if (replacementEvents.length > 1) {
+            throw dataError(`ReviewRound ${source.id} has duplicate force-fresh audit events.`);
+        }
+        const replacementEvent = replacementEvents[0];
+        if (replacementEvent !== undefined) {
+            const replacementId = replacementEvent.payload.reviewRoundId;
+            const replacement = replacementId === undefined
+                ? null
+                : tx.getReviewRound(task.id, replacementId);
+            if (replacement === null
+                || replacement.id === source.id
+                || (replacement.scope ?? "work-item") !== "task"
+                || replacement.workItemId !== source.workItemId
+                || replacement.candidateId !== source.candidateId
+                || replacement.reviewerRoleName !== source.reviewerRoleName
+                || replacement.deltaRecheck !== undefined
+                || !sameTaskFinalReviewContract(replacement.taskFinalReviewContract, source.taskFinalReviewContract)
+                || !isSameTaskReviewCandidate(replacement.taskCandidate, source.taskCandidate)
+                || replacementEvent.payload.workItemId !== replacement.workItemId
+                || replacementEvent.payload.candidateId !== replacement.candidateId
+                || replacementEvent.payload.reviewerRoleName !== replacement.reviewerRoleName
+                || replacementEvent.payload.taskCandidate !== JSON.stringify(replacement.taskCandidate)) {
+                throw dataError(`Force-fresh audit for ${source.id} does not match its replacement Round.`);
+            }
+            return { round: replacement, source, created: false };
+        }
+        const semanticBlocker = forceFreshSemanticBlocker(tx, source);
+        if (semanticBlocker !== null) {
+            throw usageError(`ReviewRound ${source.id} is not eligible for force-fresh: ${semanticBlocker}`);
+        }
+        if (source.taskCandidate === undefined) {
+            throw dataError(`ReviewRound ${source.id} has no frozen Task candidate.`);
+        }
+        const taskFinalContract = taskFinalReviewContractForMutation(tx, task.id, options);
+        if (!sameTaskFinalReviewContract(source.taskFinalReviewContract, taskFinalContract)) {
+            throw usageError(`Task final-review contract does not match ReviewRound ${source.id}.`);
+        }
+        if (source.executionGroup !== undefined
+            && (source.executionGroup.strategy.mode !== "fixed"
+                || source.executionGroup.strategy.count !== 1
+                || source.executionGroup.lanes.length !== 1
+                || source.executionGroup.lanes[0].roleName !== source.reviewerRoleName)) {
+            throw usageError(`ReviewRound ${source.id} is not a single-Reviewer full Review; force-fresh is refused.`);
+        }
+        const item = tx.getWorkItem(task.id, source.workItemId);
+        const candidate = item?.candidates.find(({ id }) => id === source.candidateId);
+        if (item === null || item === undefined || candidate === undefined) {
+            throw dataError(`Final Review anchor Candidate is no longer available: `
+                + `${source.workItemId}/${source.candidateId}.`);
+        }
+        const provenance = taskReviewProvenance(tx, task, options);
+        if (!isSameTaskReviewCandidate(source.taskCandidate, provenance.candidate)) {
+            throw usageError(`Final ReviewRound ${source.id} freezes a candidate that is no longer the current Task candidate.`);
+        }
+        const producerCollision = taskReviewProducerCollision(provenance, source.reviewerRoleName);
+        if (producerCollision !== null)
+            throw usageError(producerCollision);
+        const taskRounds = reviewRoundsByIdentity(tx.listReviewRounds(task.id)
+            .filter((entry) => (entry.scope ?? "work-item") === "task"));
+        const sourceIndex = taskRounds.findIndex(({ id }) => id === source.id);
+        if (sourceIndex < 0) {
+            throw dataError(`Final ReviewRound is not in Task history: ${source.id}.`);
+        }
+        const laterRound = taskRounds.slice(sourceIndex + 1).at(-1);
+        if (laterRound !== undefined) {
+            throw usageError(`A newer Task-final ReviewRound already exists after ${source.id}: `
+                + `${laterRound.id}/${laterRound.status}.`);
+        }
+        assertNoConflictingTaskReviewRound(taskRounds, source.id);
+        assertTaskReviewRequestLane(tx, task.id, source.reviewerRoleName);
+        let reviewer = tx.getRole(task.id, source.reviewerRoleName);
+        if (reviewer === null) {
+            if (tx.getGlobalRole(source.reviewerRoleName) === null) {
+                throw usageError(`Global Role not found: ${source.reviewerRoleName}.`);
+            }
+            reviewer = createTaskRole(tx, task, source.reviewerRoleName, undefined, now, source.reviewerRoleName);
+            tx.saveRole(task.id, reviewer);
+        }
+        let created = createTaskReviewRound(tx.nextReviewRoundId(task.id), task.id, source.workItemId, source.candidateId, source.reviewerRoleName, "leader", source.taskCandidate, now, taskFinalContract);
+        const group = createExecutionGroup(`execution-group-${created.id}`, task.id, {
+            purpose: "review",
+            target: executionTargetForReviewRound(task, created, item, candidate),
+            strategy: { mode: "fixed", count: 1 },
+            lanes: [{ roleName: reviewer.name, reviewRoundId: created.id }]
+        }, now);
+        created = { ...created, executionGroup: group };
+        tx.saveReviewRound(task.id, created);
+        recordTaskEvent(tx, task.id, TASK_FINAL_FORCE_FRESH_EVENT, {
+            sourceReviewRoundId: source.id,
+            ...(source.reviewerRunId === undefined ? {} : { sourceReviewerRunId: source.reviewerRunId }),
+            reviewRoundId: created.id,
+            workItemId: created.workItemId,
+            candidateId: created.candidateId,
+            reviewerRoleName: created.reviewerRoleName,
+            taskCandidate: JSON.stringify(created.taskCandidate),
+            reason: "source-round-failed-without-semantic-review",
+            leaderActionRunId: taskLeaderActionRunId(tx, task.id, options.environment, options.yuiHome) ?? "leader"
+        }, now);
+        return { round: created, source, created: true };
+    });
+    return output(result.created
+        ? `Fresh Task-final Review requested as ${result.round.id} after ${result.source.id}\n`
+        : `Fresh Task-final Review already requested as ${result.round.id} after ${result.source.id}\n`, { reviewRound: result.round, sourceReviewRound: result.source });
+}
+/** Returns the exact semantic evidence that makes a failed Round ineligible. */
+function forceFreshSemanticBlocker(store, round) {
+    if (round.status !== "failed")
+        return `source status is ${round.status}, not failed.`;
+    if ((round.checks ?? []).length > 0)
+        return "the Round records review checks.";
+    if (round.evidenceCommit !== undefined)
+        return "the Round records a review evidence commit.";
+    if (round.report !== round.summary) {
+        return "the Round stores a report distinct from its failure summary.";
+    }
+    if (runtimeFailureSummaryHasReviewerOutput(round.report ?? "")) {
+        return "the Round stores non-empty Reviewer output in its runtime failure summary.";
+    }
+    if (round.deltaRecheck?.disposition !== undefined
+        || round.deltaRecheck?.reasoning !== undefined) {
+        return "the Round records a semantic delta-recheck disposition.";
+    }
+    const semanticLane = round.executionGroup?.lanes.find((lane) => (lane.status === "yielded"
+        || lane.status === "completed"
+        || lane.result?.report !== undefined
+        || (lane.result?.checks ?? []).length > 0
+        || (lane.result?.findings ?? []).length > 0
+        || (lane.result?.evidence ?? []).length > 0
+        || lane.result?.evidenceCommit !== undefined));
+    if (semanticLane !== undefined) {
+        return `Reviewer Lane ${semanticLane.id} delivered semantic evidence.`;
+    }
+    const yieldedRun = store.listAgentRuns(round.taskId).find((run) => (run.purpose === "review"
+        && run.reviewRoundId === round.id
+        && run.status === "yielded"));
+    if (yieldedRun !== undefined)
+        return `Reviewer Run ${yieldedRun.id} yielded a report.`;
+    const finding = store.listReviewFindings(round.taskId).find((entry) => (entry.firstReviewRoundId === round.id || entry.lastReviewRoundId === round.id));
+    if (finding !== undefined)
+        return `Review finding ${finding.id} references the Round.`;
+    const semanticEvent = store.listEvents(round.taskId).find((event) => (event.type === "review.completed" && event.payload.reviewRoundId === round.id));
+    if (semanticEvent !== undefined)
+        return `Review completion Event ${semanticEvent.id} exists.`;
+    if (looksLikeStructuredReviewReport(round.report ?? "")) {
+        return "the Round stores a structured reviewer report.";
+    }
+    return null;
+}
+function runtimeFailureSummaryHasReviewerOutput(summary) {
+    const match = /(?:^|\n)last_assistant_message:[ \t]*([\s\S]*)$/u.exec(summary);
+    const output = match?.[1];
+    return output !== undefined && output.trim().length > 0;
+}
+function looksLikeStructuredReviewReport(report) {
+    let parsed;
+    try {
+        parsed = JSON.parse(report);
+    }
+    catch {
+        return false;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return false;
+    const record = parsed;
+    return [
+        "summary",
+        "report",
+        "checks",
+        "findings",
+        "evidence",
+        "evidenceCommit",
+        "deltaDisposition",
+        "deltaReasoning"
+    ].some((key) => Object.hasOwn(record, key));
+}
 /**
  * Issue 07: re-validates the CLI-computed delta preflight inside the store
  * transaction.  The previous Round must be a completed acceptance (a full
@@ -3252,13 +3584,16 @@ function taskRunCommand(args, store, options) {
 function runContextCommand(args, store, options) {
     const [first, ...rest] = args;
     if (first === "expand") {
-        if (rest.length < 2 || rest.length > 4 || (rest.length > 2
-            && !(rest.length === 4 && rest[2] === "--mode" && rest[3] === "full"))) {
-            throw usageError("Task run context expand usage: yui task run context expand <task>/<run> <ref-id> [--mode full].");
+        const usage = "Task run context expand usage: yui task run context expand <task>/<run> <ref-id> [--store <store>] [--mode full].";
+        const parsed = parseTail(rest, new Set(["--store", "--mode"]), usage);
+        exactPositionals(parsed.positionals, 2, usage);
+        const mode = parsed.options.get("--mode");
+        if (mode !== undefined && mode !== "full") {
+            throw usageError("Run Context expansion mode must be full.", usage);
         }
-        const { taskId, runId } = parseRunContextReference(rest[0]);
+        const { taskId, runId } = parseRunContextReference(parsed.positionals[0]);
         authorizeRunContext(store, taskId, runId, options.environment);
-        const expanded = store.transaction((tx) => expandRunContextRef(tx, taskId, runId, rest[1]));
+        const expanded = store.transaction((tx) => expandRunContextRef(tx, taskId, runId, parsed.positionals[1], optionalNonEmptyOption(parsed.options, "--store")));
         return output(`${JSON.stringify(expanded, null, 2)}\n`, { context: expanded });
     }
     if (first === "delta") {
@@ -3996,15 +4331,20 @@ function assertPendingFinalReviewWorkspaceEvidence(store, task, round) {
     }
 }
 function latestTaskReviewContractAnchor(store, task, taskFinalContract) {
-    const item = [...store.listWorkItems(task.id)]
-        .filter(({ candidates }) => candidates.some(({ taskFinalReviewContract: candidateContract }) => (sameTaskFinalReviewContract(candidateContract, taskFinalContract))))
-        .sort((left, right) => (left.updatedAt.localeCompare(right.updatedAt) || left.id.localeCompare(right.id)))
+    const anchor = store.listWorkItems(task.id)
+        .flatMap((item) => {
+        const candidate = governingWorkItemCandidate(item);
+        return candidate !== undefined && sameTaskFinalReviewContract(candidate.taskFinalReviewContract, taskFinalContract)
+            ? [{ item, candidate }]
+            : [];
+    })
+        .sort((left, right) => (left.item.updatedAt.localeCompare(right.item.updatedAt)
+        || left.item.id.localeCompare(right.item.id)))
         .at(-1);
-    const candidate = item?.candidates.filter(({ taskFinalReviewContract: candidateContract }) => (sameTaskFinalReviewContract(candidateContract, taskFinalContract))).at(-1);
-    if (item === undefined || candidate === undefined) {
+    if (anchor === undefined) {
         throw usageError(`Task ${task.id} has no WorkItem Candidate to anchor its final Review.`);
     }
-    return { item, candidate };
+    return anchor;
 }
 /**
  * Leader-only retry of an exact failed Task-final review Run. The old failed
@@ -5324,6 +5664,44 @@ function recordTaskEventRecord(store, taskId, type, payload, now) {
     store.saveEvent(taskId, event);
     return event;
 }
+function publishedTreeAuthorizationPayload(actor, proof) {
+    return {
+        by: actor,
+        projectId: proof.projectId,
+        publicationId: proof.publicationId,
+        reviewRoundId: proof.reviewRoundId,
+        localCommit: proof.localCommit,
+        remoteCommit: proof.remoteCommit,
+        tree: proof.tree
+    };
+}
+function matchingPublishedTreeAuthorization(store, proof) {
+    const events = store.listEvents(proof.taskId);
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        const event = events[index];
+        if (event.type === "task.completed" || event.type === "task.reopened")
+            return undefined;
+        if (event.type === TASK_COMPLETION_PUBLISHED_TREE_AUTHORIZED_EVENT
+            && (event.payload.by === "user" || event.payload.by === "operator")
+            && event.payload.projectId === proof.projectId
+            && event.payload.publicationId === proof.publicationId
+            && event.payload.reviewRoundId === proof.reviewRoundId
+            && event.payload.localCommit === proof.localCommit
+            && event.payload.remoteCommit === proof.remoteCommit
+            && event.payload.tree === proof.tree) {
+            return event;
+        }
+    }
+    return undefined;
+}
+function requirePublishedTreeAuthorization(store, proof) {
+    const authorization = matchingPublishedTreeAuthorization(store, proof);
+    if (authorization === undefined) {
+        throw usageError(`Published-tree completion requires explicit user or global Operator authorization for `
+            + `${proof.taskId}/${proof.publicationId} at Task-final Review ${proof.reviewRoundId}.`);
+    }
+    return authorization;
+}
 /** Keeps a free-text run-fact note bounded so an event payload stays compact. */
 function truncateEventNote(note) {
     const normalized = note.trim();
@@ -6272,6 +6650,9 @@ function workItemRef(taskId, id) {
 function messageRef(taskId, id) {
     return { type: "message", taskId, id };
 }
+function eventRef(taskId, id) {
+    return { type: "event", taskId, id };
+}
 function notifyMailbox(runtime, target, compatibilityTaskId) {
     if (runtime?.notifyMailboxChanged !== undefined) {
         runtime.notifyMailboxChanged(target);