@zq-silk/yui 0.15.9 → 0.15.12

package/dist/commands/taskCommands.js

@@ -1,6 +1,9 @@
+import { controlProviderRetry, providerRetryProjection, renderProviderRetry } from "../runtime/providerRetry.js";
 import { roleLaunchEventPayload, saveTaskRoleUpdate } from "../role/taskRoleUpdate.js";
-import { randomUUID } from "node:crypto";
-import { join } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { archiveDeliveryWarnings, archiveRetainedResources, renderArchiveDiagnostics, taskArchiveDiagnostics } from "../task/archiveDiagnostics.js";
+import { archiveSettlementChecks } from "../task/archivePreflight.js";
+import { CleanupInspectionError } from "../workspace/cleanupInspection.js";
 import { isDeepStrictEqual } from "node:util";
 import { createRunInput } from "../context/runInputContract.js";
 import { buildRunContextPack, buildRunContextDelta, contextSnapshotDeltaRefIds, expandRunContextRef, freezeWorkItemExecutionAssignmentContextSnapshot, freezeReviewStageContextSnapshot, freezeRunContextSnapshot } from "../context/runContextPack.js";
@@ -20,7 +23,7 @@ import { agentExecutionComponentLabel } from "../agent/executionComponents.js";
 import { agentRunConfigurationLabel, renderAgentRunConfiguration } from "../output/agentRunConfigurationPresentation.js";
 import { formatTimestamp } from "../output/timePresentation.js";
 import { renderRoleDetails, renderRoleLaunchComparison } from "../output/rolePresentation.js";
-import { createTaskMessage, expandTaskMessageResult, taskMessageAuthorLabel, updateDraftTaskMessage, withSubmissionReceipt, TASK_SUBMISSION_INTENTS } from "../message/message.js";
+import { createTaskMessage, expandTaskMessageResult, recordTaskMessageControlOutcome, taskMessageAuthorLabel, taskMessageInputControlState, updateDraftTaskMessage, withSubmissionReceipt, TASK_SUBMISSION_INTENTS } from "../message/message.js";
 import { assertDraftTaskExecutionFree, validateDraftWorkItemEdit } from "../task/draftPlan.js";
 import { TASK_PLANNING_ENTERED_EVENT, decideSubmissionRouting, describeSubmissionFeedback, draftActivationState, draftHasEnteredPlanning, normalizeSubmissionIntent, sameSubmissionTarget } from "../task/taskSubmission.js";
 import { recordTaskActivationRequestInTransaction, taskActivationOperationRef } from "../task/taskActivationService.js";
@@ -47,6 +50,7 @@ import { addTaskProjectBinding, archiveTask, completeTask, createTask, retireTas
 import { resolveTaskRecordReference } from "../task/taskRecordReference.js";
 import { projectCompletionReadiness } from "../task/completionReadiness.js";
 import { StorageConflictError } from "../storage/taskStore.js";
+import { planningRuntimeCwd } from "../storage/homeLayout.js";
 import { requireResolvedAgentProfileRuntime } from "../profile/agentProfileRuntime.js";
 import { assertProjectActive, resolveProject } from "../repository/project.js";
 import { currentWorkItemCandidate, currentWorkItemExecutionGroup, workItemExecutionGroupById, createWorkItem, editWorkItemDefinition, attachWorkItemExecutionGroup, updateWorkItemExecutionGroup, retireWorkItem, prepareWorkItemDispatch, submitWorkItemCandidate, updateWorkItemWriteProjects, updateWorkItemStatus } from "../workItem/workItem.js";
@@ -68,13 +72,16 @@ import { createProjectResources } from "../resources/projectResourceService.js";
 import { isGitArtifactRefString, parseGitArtifactRef } from "../artifacts/gitArtifactRef.js";
 import { runTaskNextActionCommand } from "./taskNextActionCommand.js";
 import { runDeliveryGuardPreflight, withGuardWarnings } from "./deliveryGuardPreflight.js";
-import { inspectTaskRoleRuntimeStatuses, renderTaskRoleRuntimeStatus, taskRoleActiveWorkLabel, taskRoleLastRunLabel, taskRoleNativeSessionLabel, taskRoleOpenInputLabel, taskRoleTmuxLabel } from "./taskRoleRuntimeStatus.js";
-import { assertNoOpenInputRequests, openInputRequestCount, runTaskInputCommand } from "./taskInputCommands.js";
+import { inspectTaskRoleRuntimeStatuses, renderTaskRoleRuntimeStatus, taskRoleActiveWorkLabel, taskRoleLastRunLabel, taskRoleNativeSessionLabel, taskRoleOpenInputLabel, taskRoleTmuxLabel, withTaskRoleHostObservation, taskRoleHostDiagnostic } from "./taskRoleRuntimeStatus.js";
+import { openInputRequestCount, runTaskInputCommand } from "./taskInputCommands.js";
 import { runGrantCommand } from "./grantCommands.js";
 import { runWorkflowCommand } from "./workflowCommands.js";
-import { taskLocalActor as resolveTaskLocalActor, assertTaskDeliveryAuthority } from "./taskActor.js";
+import { taskLocalActor as resolveTaskLocalActor, assertTaskDeliveryAuthority, assertTaskInputControlAuthority } from "./taskActor.js";
 import { currentManagedRuntime, resolveManagedTaskReader } from "../runtime/managedCaller.js";
+import { parseTaskCatalogOptions, readTaskCatalog, renderTaskCatalog, taskCatalogScope } from "../context/taskCatalog.js";
 import { resolveMessageRecipient, messageContinuationBlocker } from "../message/messageContinuation.js";
+import { findTaskInterrupt, reserveTaskInterrupt, taskInterruptReceipt, taskInterruptWasRejected } from "../message/taskInterrupt.js";
+import { resolveTaskInputControl } from "../message/inputControlResolution.js";
 import { enqueueOperatorEvent } from "../scheduler/operatorEvent.js";
 import { queueLeaderWakeup } from "../scheduler/wakeupQueue.js";
 import { renderWakeReason, wakeReason } from "../scheduler/wakeReason.js";
@@ -308,7 +315,7 @@ export function runTaskCommand(args, store, options = {}) {
     switch (command) {
         case "create": return createTaskCommand(rest, store, options);
         case "update": return output(updateTaskCommand(rest, store, options));
-        case "list": return listTaskCommand(rest, store);
+        case "list": return listTaskCommand(rest, store, options.environment);
         case "show": return showTaskCommand(rest, store, options.actualTaskReviewCandidate ?? null);
         case "context": return runTaskContextCommand(rest, store, options.environment);
         case "next-action": return runTaskNextActionCommand(rest, store, options.actualTaskReviewCandidate ?? null);
@@ -317,7 +324,7 @@ export function runTaskCommand(args, store, options = {}) {
         case "activation": return runTaskActivationCommand(rest, store, options);
         case "complete": return completeTaskCommand(rest, store, options);
         case "reopen": return output(reopenTaskCommand(rest, store, options));
-        case "archive": return output(archiveTaskCommand(rest, store, options));
+        case "archive": return archiveTaskCommand(rest, store, options);
         case "retire": return retireTaskCommand(rest, store, options);
         case "cancel": return cancelTaskCommand(rest, store, options);
         case "reconcile": return output(reconcileTaskCommand(rest, store, options));
@@ -545,7 +552,7 @@ export function updateTaskMetadataCommand(store, taskId, patch, options = {}) {
     notifyMailbox(options.runtime, taskMailbox(result.id), result.id);
     return result;
 }
-function routeUserSubmission(tx, task, actor, body, intent, now, submissionKey, target) {
+function routeUserSubmission(tx, task, actor, body, intent, now, submissionKey, target, inputControl) {
     const kind = actor;
     const author = actor === "operator"
         ? { type: "operator" }
@@ -564,7 +571,8 @@ function routeUserSubmission(tx, task, actor, body, intent, now, submissionKey,
     // how routing then resolves (§2.5). Intent is stored, never re-read from the body.
     const message = appendMessage(tx, task.id, body, kind, author, now, {
         intent,
-        ...(submissionKey === undefined ? {} : { submissionKey })
+        ...(submissionKey === undefined ? {} : { submissionKey }),
+        ...(inputControl === undefined ? {} : { inputControl })
     });
     // Re-read phase and activation inside this same transaction: this is the point
     // the race is decided at (§2.3).
@@ -900,10 +908,15 @@ function createTaskAggregate(store, title, metadata, now, defaultProjectIds = []
     enqueueWork(store, taskMailbox(task.id), "task-created", now, [taskRef(task.id)]);
     return { task, leader };
 }
-function listTaskCommand(args, store) {
+function listTaskCommand(args, store, environment = {}) {
+    if (args.includes("--view")) {
+        const result = readTaskCatalog(store, parseTaskCatalogOptions(args), environment);
+        return output(renderTaskCatalog(result), result);
+    }
+    const taskId = taskCatalogScope(store, environment);
     const options = parseTaskListOptions(args);
     const snapshot = store.transaction((reader) => ({
-        result: buildTaskOverview(reader, options),
+        result: buildTaskOverview(reader, options, new Date(), taskId),
         timeZone: reader.getConfig().timeZone
     }));
     const rendered = renderTaskOverview(snapshot.result, options, snapshot.timeZone, defaultTableWidth());
@@ -924,6 +937,7 @@ function showTaskCommand(args, store, currentTaskCandidate) {
     const integrations = store.listIntegrationAttempts(task.id);
     const publications = store.listPublicationReferences(task.id);
     const remoteDelivery = projectTaskRemoteDeliveryFromStore(store, task, currentTaskCandidate);
+    const archive = task.status === "archived" ? taskArchiveDiagnostics(store, task) : undefined;
     const verifiedMergedPublications = publications.filter((reference) => (reference.state === "merged" && reference.verification === "verified")).length;
     const currentMessageCount = operationalTaskRecords(messages, events, "message").length;
     const currentWorkItemCount = work.filter(({ status }) => status !== "retired").length;
@@ -981,6 +995,7 @@ function showTaskCommand(args, store, currentTaskCandidate) {
         `Integration Attempts: ${counts.integrations}`,
         `Publication references: ${counts.publications} (${verifiedMergedPublications} verified merged)`,
         renderTaskRemoteDelivery(remoteDelivery).trimEnd(),
+        ...(archive === undefined ? [] : [renderArchiveDiagnostics(archive).trimEnd()]),
         `Open inputs: ${counts.openInputs}`,
         `Created: ${presentTime(task.createdAt, timeZone)}`,
         `Updated: ${presentTime(task.updatedAt, timeZone)}`
@@ -989,7 +1004,8 @@ function showTaskCommand(args, store, currentTaskCandidate) {
         task,
         counts,
         hasBrief: brief !== null,
-        remoteDelivery
+        remoteDelivery,
+        ...(archive === undefined ? {} : { archive })
     });
 }
 function activateTaskCommand(args, store, options) {
@@ -1254,50 +1270,44 @@ function archiveTaskCommand(args, store, options) {
             && task.status !== "cancelled") {
             throw usageError(`Task ${task.id} must be completed or retired before it can be archived.`);
         }
-        const remoteDelivery = request.disposition === "integrated"
-            ? assertTaskRemoteDeliveryProof(tx, task, options.archiveRemoteDeliveryProof, { forceUnverified: request.forceUnverified })
-            : undefined;
-        assertNoOpenInputRequests(tx, task.id, "archiving the Task");
-        const unsettledWork = tx.listWorkItems(task.id).find((item) => item.status === "open");
-        if (unsettledWork !== undefined) {
-            throw usageError(`Work Item ${unsettledWork.id} must be accepted or explicitly retired before archive.`);
-        }
-        const unresolvedIntegration = tx.listIntegrationAttempts(task.id).find((integration) => (integration.status === "running"
-            || integration.status === "blocked"
-            || integration.status === "validating"));
-        if (unresolvedIntegration !== undefined) {
-            throw usageError(`Task ${task.id} has an unresolved Integration Attempt: ${unresolvedIntegration.id}.`);
-        }
-        const activeArchiveJob = tx.listDurableJobs(task.id).find((job) => (job.status === "queued"
-            || job.status === "running"
-            || (job.status === "unknown-needs-attention" && job.acknowledgedAt === undefined)));
-        if (activeArchiveJob !== undefined) {
-            throw usageError(`Task ${task.id} has an active DurableJob: ${activeArchiveJob.id}/${activeArchiveJob.status}.`);
-        }
-        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) {
-            throw usageError(`Task ${task.id} still has an active AgentRun for Role ${activeRole.name}; `
-                + "stop its runtime before archiving.");
-        }
-        const liveSessionRole = tx.listRoles(task.id).find((role) => {
-            const sessions = tx.getTaskRoleSessionSet(task.id, role.name);
-            const session = sessions?.sessions[sessions.activeAgentId];
-            return session !== undefined && session.status !== "ended";
-        });
-        if (liveSessionRole !== undefined) {
-            throw usageError(`Task ${task.id} still has a live Session for Role ${liveSessionRole.name}; `
-                + "stop that Session before archiving.");
+        const remoteDelivery = request.force
+            ? projectTaskRemoteDeliveryFromStore(tx, task)
+            : request.disposition === "integrated"
+                ? assertTaskRemoteDeliveryProof(tx, task, options.archiveRemoteDeliveryProof)
+                : undefined;
+        if (!request.force) {
+            const checks = archiveSettlementChecks(tx, task);
+            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) {
+                throw usageError(`Task ${task.id} still has an active AgentRun for Role ${activeRole.name}; `
+                    + "stop its runtime before archiving.");
+            }
+            const liveSessionRole = tx.listRoles(task.id).find((role) => {
+                const sessions = tx.getTaskRoleSessionSet(task.id, role.name);
+                const session = sessions?.sessions[sessions.activeAgentId];
+                return session !== undefined && session.status !== "ended";
+            });
+            if (liveSessionRole !== undefined) {
+                throw usageError(`Task ${task.id} still has a live Session for Role ${liveSessionRole.name}; `
+                    + "stop that Session before archiving.");
+            }
         }
-        const archived = archiveTask(task, now, { by: actor });
+        const retainedResources = request.force ? archiveRetainedResources(tx, task) : [];
+        const warnings = request.force && remoteDelivery !== undefined ? archiveDeliveryWarnings(remoteDelivery) : [];
+        const archived = { ...archiveTask(task, now, { by: actor }), executionGate: { state: "stopped" } };
         tx.saveTask(archived);
-        tx.clearPendingWakeup(task.id);
         tx.clearLeaderFailure(task.id);
-        for (const role of tx.listRoles(task.id)) {
-            tx.removeWorkMailbox(roleMailbox(task.id, role.name));
+        if (!request.force) {
+            tx.clearPendingWakeup(task.id);
+            for (const role of tx.listRoles(task.id)) {
+                tx.removeWorkMailbox(roleMailbox(task.id, role.name));
+            }
         }
         const remoteProjectHeads = remoteDelivery === undefined
             ? undefined
@@ -1314,27 +1324,29 @@ function archiveTaskCommand(args, store, options) {
         recordTaskEvent(tx, task.id, "task.archived", {
             by: actor,
             workspaceDisposition: request.disposition,
+            ...(request.force ? {
+                force: "true", cleanup: "pending",
+                warnings: JSON.stringify(warnings),
+                retainedResources: JSON.stringify(retainedResources)
+            } : {}),
             ...(remoteDelivery === undefined
                 ? {}
                 : {
                     mergeCoverage: remoteDelivery.status,
                     allMerged: String(remoteDelivery.allMerged),
-                    allVerified: String(remoteDelivery.allVerified),
-                    ...(request.forceUnverified && !remoteDelivery.allVerified
-                        ? { verificationOverride: "true" }
-                        : {})
+                    allVerified: String(remoteDelivery.allVerified)
                 }),
             ...(remoteProjectHeads === undefined ? {} : { projectHeads: remoteProjectHeads }),
             ...(remoteProjectBases === undefined ? {} : { projectBases: remoteProjectBases })
         }, now);
-        enqueueWork(tx, taskMailbox(task.id), "task-archived", now, [taskRef(task.id)]);
         return { task: archived, changed: true };
     });
-    if (result.changed)
-        notifyMailbox(options.runtime, taskMailbox(result.task.id), result.task.id);
-    return result.changed
+    if (result.changed && !request.force)
+        options.runtime?.notifyStateChanged(result.task.id);
+    const diagnostics = taskArchiveDiagnostics(store, result.task);
+    return output((result.changed
         ? `Archived task ${result.task.id}\n`
-        : `Task ${result.task.id} is already archived\n`;
+        : `Task ${result.task.id} is already archived\n`) + renderArchiveDiagnostics(diagnostics), { task: result.task, changed: result.changed, ...diagnostics });
 }
 function cancelTaskCommand(args, store, options) {
     const usage = "Task cancel usage: yui task cancel <task> (--summary <text>|--summary-file <path|->).";
@@ -1400,6 +1412,7 @@ function retireTaskCommand(args, store, options) {
         }
         const unresolvedIntegration = tx.listIntegrationAttempts(task.id).find((integration) => (integration.status === "running"
             || integration.status === "blocked"
+            || integration.status === "conflicted"
             || integration.status === "validating"));
         if (unresolvedIntegration !== undefined) {
             throw usageError(`Task ${task.id} has an unresolved Integration Attempt: ${unresolvedIntegration.id}.`);
@@ -1493,9 +1506,9 @@ function assertTaskRetirementProof(store, task, proof) {
         throw usageError(`Task workspaces changed after retirement preflight: ${task.id}.`);
     }
 }
-export function parseTaskArchiveArguments(args) {
+export function parseTaskArchiveArguments(args, command = "archive") {
     const usage = "Task archive usage: "
-        + "yui task archive <id> (--integrated [--force]|--abandon).";
+        + `yui task ${command} <id> (--integrated|--abandon) [--force].`;
     const taskId = args[0]?.trim();
     const flags = args.slice(1);
     if (taskId === undefined
@@ -1506,14 +1519,14 @@ export function parseTaskArchiveArguments(args) {
     }
     const integrated = flags.includes("--integrated");
     const abandoned = flags.includes("--abandon");
-    const forceUnverified = flags.includes("--force");
-    if (integrated === abandoned || (forceUnverified && !integrated)) {
+    const force = flags.includes("--force");
+    if (integrated === abandoned) {
         throw usageError(usage);
     }
     return {
         taskId,
         disposition: integrated ? "integrated" : "abandoned",
-        forceUnverified
+        force
     };
 }
 function formatProjectCommits(projects) {
@@ -1532,14 +1545,10 @@ export function validateTaskArchiveRequest(args, store, options = {}) {
         && task.status !== "cancelled") {
         throw usageError(`Task ${task.id} must be completed or retired before it can be archived.`);
     }
-    if (task.status !== "archived") {
-        assertNoOpenInputRequests(store, task.id, "archiving the Task");
-        const unresolvedIntegration = store.listIntegrationAttempts(task.id).find((integration) => (integration.status === "running"
-            || integration.status === "blocked"
-            || integration.status === "validating"));
-        if (unresolvedIntegration !== undefined) {
-            throw usageError(`Task ${task.id} has an unresolved Integration Attempt: ${unresolvedIntegration.id}.`);
-        }
+    if (task.status !== "archived" && !request.force) {
+        const checks = archiveSettlementChecks(store, task);
+        if (checks.length > 0)
+            throw new CleanupInspectionError(checks);
     }
     return request;
 }
@@ -1637,6 +1646,10 @@ function taskMessageCommand(args, store, options) {
                 ? { state: "queued" } : { state: "saved" };
         return output(`Saved message ${result.message.id} to ${result.task.id} (${delivery.state}${reason === undefined ? "" : `: ${reason}`}).\n`, { taskId: result.task.id, message: result.message, delivery });
     }
+    if (command === "queue")
+        return queueTaskMessage(rest, store, options);
+    if (command === "steer")
+        return steerTaskMessage(rest, store, options);
     if (command === "list") {
         const messageListUsage = "Task message list usage: yui task message list <id> [--after <timestamp>] [--limit <n>].";
         const parsed = parseTail(rest, new Set(["--after", "--limit"]), messageListUsage);
@@ -1690,6 +1703,149 @@ function taskMessageCommand(args, store, options) {
         ? "Task message command is required."
         : `Unknown command: task message ${command}`);
 }
+/** CLI and authenticated user Surface share the same message and mailbox
+ * transaction. Talking to Leader does not impersonate Leader authority. */
+/**
+ * `queue` is the explicit, idempotent form of the existing send: it persists a
+ * Message tagged with the durable `queue` action and a stable requestId, and
+ * relies on the identical continuation path as `send`. Repeating the exact same
+ * (requestId, body) returns the original Message and delivers nothing twice;
+ * reusing the requestId with different content is a conflict, never a second
+ * input (decision-3 §5/§6).
+ */
+function queueTaskMessage(args, store, options) {
+    const usage = "Task message queue usage: yui task message queue <id> (<body>|--body-file <path|->) --request-id <id> [--to <role> --work-item <id>|--review-round <id>].";
+    const parsed = parseTail(args, new Set(["--body-file", "--request-id", "--to", "--work-item", "--review-round"]), usage);
+    if (parsed.positionals.length < 1 || parsed.positionals.length > 2)
+        throw usageError(usage);
+    const body = readCommandText(parsed.positionals[1], parsed.options.get("--body-file"), "--body", usage);
+    const requestId = requiredOption(parsed.options, "--request-id");
+    const recipientRole = parsed.options.get("--to");
+    const workItemId = parsed.options.get("--work-item");
+    const reviewRoundId = parsed.options.get("--review-round");
+    if (recipientRole === undefined && (workItemId !== undefined || reviewRoundId !== undefined)) {
+        throw usageError("--to is required for scoped Message delivery.");
+    }
+    const result = sendTaskMessageCommand(store, parsed.positionals[0], body, undefined, options, recipientRole === undefined ? undefined : { roleName: recipientRole, workItemId, reviewRoundId }, undefined, undefined, { action: "queue", requestId });
+    const reason = result.message.continuation?.notDeliveredReason;
+    const delivery = result.idempotentReplay ? { state: "idempotent-replay" }
+        : reason !== undefined ? { state: "not-delivered", reason }
+            : recipientRole !== undefined || result.actor !== "leader" ? { state: "queued" } : { state: "saved" };
+    return output(`Queued message ${result.message.id} to ${result.task.id} (${delivery.state}${reason === undefined ? "" : `: ${reason}`}).\n`, { taskId: result.task.id, message: result.message, delivery });
+}
+/**
+ * `steer` targets only the exact current native Turn. It always persists the
+ * Message (so an unsupported or missed steer stays visible and re-choosable),
+ * then resolves the live target from durable state with no Provider call. On a
+ * ready resolution it returns a structured intent the CLI performs against the
+ * Agent Host; on any explicit failure it returns the saved Message plus the
+ * exact error code, and never falls back to an interrupt or a queue
+ * (decision-3 §1/§5). The steer Message is excluded from the queued
+ * continuation path, so a failed live attempt cannot silently become a queue.
+ */
+function steerTaskMessage(args, store, options) {
+    const usage = "Task message steer usage: yui task message steer <id> (<body>|--body-file <path|->) --request-id <id> --expected-target <turn> [--to <role> --work-item <id>|--review-round <id>].";
+    const parsed = parseTail(args, new Set(["--body-file", "--request-id", "--expected-target", "--to", "--work-item", "--review-round"]), usage);
+    if (parsed.positionals.length < 1 || parsed.positionals.length > 2)
+        throw usageError(usage);
+    const body = readCommandText(parsed.positionals[1], parsed.options.get("--body-file"), "--body", usage);
+    const requestId = requiredOption(parsed.options, "--request-id");
+    const expectedTarget = requiredOption(parsed.options, "--expected-target");
+    const recipientRole = parsed.options.get("--to");
+    const workItemId = parsed.options.get("--work-item");
+    const reviewRoundId = parsed.options.get("--review-round");
+    if (recipientRole === undefined) {
+        throw usageError("steer requires --to <role>; it targets that Role's exact current Turn.");
+    }
+    // decision-3 §9: a Task Leader's current native turn (including a Draft's
+    // planning turn) is a real turn but NOT an implicit AgentRun, so steering it
+    // never establishes a Worker-style Assignment. It is persisted as an ordinary
+    // no-Run Leader notification (recipient undefined, wake "none" so it never
+    // spawns a Leader AgentRun) and its live target is the Leader's own turn. A
+    // Worker/Reviewer steer keeps the exact Assignment recipient it always had.
+    const leaderTarget = recipientRole === "leader";
+    if (leaderTarget && (workItemId !== undefined || reviewRoundId !== undefined)) {
+        throw usageError("Steering the Leader targets its current turn directly; it takes no --work-item/--review-round Assignment.");
+    }
+    const result = leaderTarget
+        ? sendTaskMessageCommand(store, parsed.positionals[0], body, "none", options, undefined, undefined, undefined, { action: "steer", requestId, expectedTarget })
+        : sendTaskMessageCommand(store, parsed.positionals[0], body, undefined, options, { roleName: recipientRole, workItemId, reviewRoundId }, undefined, undefined, { action: "steer", requestId, expectedTarget });
+    const roleName = result.message.recipient?.roleName ?? recipientRole;
+    if (result.idempotentReplay) {
+        // A replay is a later reader (another CLI invocation): surface the durable
+        // control state the Host settlement folded onto this exact Message, so an
+        // unknown steer is visibly not-submitted/pending/accepted/rejected/
+        // delivery-unknown rather than silently re-attempted (message-5 gap D).
+        const controlState = taskMessageInputControlState(result.message);
+        return output(`Steer message ${result.message.id} already recorded (idempotent-replay${controlState === undefined ? "" : `; control ${controlState}`}).\n`, { taskId: result.task.id, message: result.message,
+            steer: { state: "idempotent-replay",
+                ...(controlState === undefined ? {} : { control: controlState }) } });
+    }
+    // The static resolution is the testable contract: capability gate, exact-turn
+    // match, and writer fence, all from durable state without a live Endpoint.
+    const resolution = resolveTaskInputControl(store, result.task.id, roleName, "steer", expectedTarget);
+    if (resolution.outcome !== "ready") {
+        return output(`Steer message ${result.message.id} saved but not delivered (${resolution.code}: ${resolution.detail}).\n`, { taskId: result.task.id, message: result.message,
+            steer: { state: "not-steered", code: resolution.code, detail: resolution.detail } });
+    }
+    if (!leaderTarget) {
+        const current = store.getActiveRun(result.task.id, roleName);
+        const native = store.getTaskRoleSessionSet(result.task.id, roleName)?.providerBinding?.run;
+        const recipient = result.message.recipient;
+        if (current === null || native?.runId !== current.id
+            || recipient?.ownerRunId !== current.id
+            || recipient.workItemId !== current.workItemId
+            || recipient.reviewRoundId !== current.reviewRoundId
+            || messageContinuationBlocker(store, result.message) !== undefined) {
+            return output(`Steer message ${result.message.id} saved but not delivered (TARGET_CHANGED: active Assignment differs).\n`, { taskId: result.task.id, message: result.message,
+                steer: { state: "not-steered", code: "TARGET_CHANGED", detail: "The input does not belong to the active Turn's Assignment." } });
+        }
+    }
+    const receiptId = `steer:${result.task.id}/${result.message.id}`;
+    // Register the one independent control attempt as `pending` before the live
+    // edge runs (decision-3 §3, message-5 gap D). This is the messageRef-associated
+    // control op that makes a dispatched-but-unproven steer visibly distinct from a
+    // steer that was merely saved and never attempted (`not-submitted`). It is
+    // keyed by this exact receiptId and the steer's own requestId, and is monotonic
+    // and idempotent, so the Host's later settlement fold promotes it to a proven
+    // terminal and never rewinds it. An idempotent replay above already returned
+    // the saved Message, so this records the attempt exactly once.
+    store.transaction((tx) => {
+        const saved = tx.listMessages(result.task.id).find((entry) => entry.id === result.message.id);
+        const requestId = saved?.inputControl?.requestId;
+        if (saved === undefined || requestId === undefined)
+            return;
+        tx.updateMessage(result.task.id, recordTaskMessageControlOutcome(saved, {
+            requestId, receiptId, outcome: "pending", observedAt: clock(options)
+        }));
+    });
+    return {
+        kind: "input-steer",
+        taskId: result.task.id,
+        roleName,
+        messageId: result.message.id,
+        target: resolution.target,
+        receiptId,
+        // decision-3 §9: deliver the input as an authorized, reconcilable delta, not
+        // loose body text and not a bare Message id. The Host additionally decorates
+        // this with the Session Manifest read pointer, so the running turn can read
+        // the exact durable Message through its authorized Context path.
+        text: steerInputDelivery(result.task.id, result.message.id, roleName, body),
+        output: `Steering ${result.task.id}/${roleName} at Turn ${resolution.target.nativeTurnId ?? resolution.target.attemptId} with message ${result.message.id}.\n`
+    };
+}
+/** Compose the exact input a steer pushes into the live turn: a bounded header
+ * that names the durable Message and states receipt-is-not-acceptance, then the
+ * verbatim body. The header keeps the input reconcilable with durable state
+ * (decision-3 §9) without copying the body twice or fabricating a Run. */
+function steerInputDelivery(taskId, messageId, roleName, body) {
+    return [
+        `[Steer ${taskId}/${messageId} → ${roleName}] Additional input to your current turn; receipt is not acceptance of prior work.`,
+        `It is saved durably as Message ${messageId}; reconcile it through your Session Manifest's authorized Context read path.`,
+        "",
+        body
+    ].join("\n");
+}
 /** CLI and authenticated user Surface share the same message and mailbox
  * transaction. Talking to Leader does not impersonate Leader authority. */
 /**
@@ -1708,7 +1864,7 @@ function taskMessageCommand(args, store, options) {
  * execution is decided by the Controller from the Task's own status, so this
  * function never names a purpose and no second planning path exists.
  */
-export function sendTaskMessageCommand(store, taskId, body, wakePolicy, options = {}, recipient, intent, submissionKey) {
+export function sendTaskMessageCommand(store, taskId, body, wakePolicy, options = {}, recipient, intent, submissionKey, inputControl) {
     if (!body.trim())
         throw usageError("Message body is required.");
     if (recipient !== undefined && wakePolicy !== undefined) {
@@ -1723,6 +1879,32 @@ export function sendTaskMessageCommand(store, taskId, body, wakePolicy, options
     const now = clock(options);
     const result = store.transaction((tx) => {
         const task = requireTask(tx, taskId);
+        // A stable requestId makes the whole send idempotent: an exact repeat
+        // returns the original Message, and any different body/action/recipient/
+        // target under the same id is a conflicting reuse, never a silent second
+        // input (decision-3 §6). The prior input is matched by requestId across
+        // both a live inputControl and the reusedInput provenance an interrupt-then
+        // handoff preserved, so re-tagging a steer as a handoff never frees its
+        // requestId to create a second Message.
+        if (inputControl !== undefined) {
+            const existing = tx.listMessages(task.id).find((entry) => entry.inputControl?.requestId === inputControl.requestId
+                || entry.interruptThen?.reusedInput?.requestId === inputControl.requestId);
+            if (existing !== undefined) {
+                const prior = existing.inputControl ?? existing.interruptThen?.reusedInput;
+                const priorRecipient = existing.recipient === undefined ? undefined
+                    : { roleName: existing.recipient.roleName, workItemId: existing.recipient.workItemId,
+                        reviewRoundId: existing.recipient.reviewRoundId };
+                const nextRecipient = recipient === undefined ? undefined
+                    : { roleName: recipient.roleName, workItemId: recipient.workItemId, reviewRoundId: recipient.reviewRoundId };
+                if (prior?.action !== inputControl.action || existing.body !== body
+                    || prior.expectedTarget !== inputControl.expectedTarget
+                    || !isDeepStrictEqual(priorRecipient, nextRecipient)) {
+                    throw usageError(`Input requestId ${inputControl.requestId} was already used with different content or target; use a new requestId for a new input.`);
+                }
+                return { task, message: existing, actor: replayActor(existing), queuedForLeader: false,
+                    feedback: existing.submissionReceipt?.feedback, idempotentReplay: true };
+            }
+        }
         if (recipient === undefined)
             assertTaskOpen(task);
         const caller = currentManagedRuntime(tx, options.environment, task.id);
@@ -1743,10 +1925,10 @@ export function sendTaskMessageCommand(store, taskId, body, wakePolicy, options
         // gain develop authority (task-32 §2.5).
         if (recipient === undefined && (actor === "user" || actor === "operator")) {
             const effectiveIntent = normalizeSubmissionIntent(intent, wakePolicy);
-            const routed = routeUserSubmission(tx, task, actor, body, effectiveIntent, now, submissionKey, { kind: "task", taskId: task.id });
+            const routed = routeUserSubmission(tx, task, actor, body, effectiveIntent, now, submissionKey, { kind: "task", taskId: task.id }, inputControl);
             return {
                 task: routed.task, message: routed.message, actor,
-                queuedForLeader: routed.queuedForLeader, feedback: routed.feedback
+                queuedForLeader: routed.queuedForLeader, feedback: routed.feedback, idempotentReplay: false
             };
         }
         if (intent !== undefined) {
@@ -1764,7 +1946,8 @@ export function sendTaskMessageCommand(store, taskId, body, wakePolicy, options
             });
         const context = {
             ...(target === undefined ? {} : { recipient: target }),
-            ...(recipient?.workItemId === undefined ? {} : { workItemId: recipient.workItemId })
+            ...(recipient?.workItemId === undefined ? {} : { workItemId: recipient.workItemId }),
+            ...(inputControl === undefined ? {} : { inputControl })
         };
         const message = actor === "leader"
             ? appendMessage(tx, task.id, body, "role-result", { type: "role", roleName: LEADER_ROLE }, now, context)
@@ -1791,8 +1974,10 @@ export function sendTaskMessageCommand(store, taskId, body, wakePolicy, options
         else if (queuedForLeader) {
             enqueueWork(tx, leaderMailbox(task.id), actor === "operator" ? "operator-input" : "user-message", now, [messageRef(task.id, message.id)], { source: actor, dedupeKey: `message:${task.id}:${message.id}` });
         }
-        return { task, message, actor, queuedForLeader, feedback: undefined };
+        return { task, message, actor, queuedForLeader, feedback: undefined, idempotentReplay: false };
     });
+    if (result.idempotentReplay)
+        return result;
     if (recipient !== undefined) {
         notifyMailbox(options.runtime, taskMailbox(result.task.id), result.task.id);
     }
@@ -1802,6 +1987,13 @@ export function sendTaskMessageCommand(store, taskId, body, wakePolicy, options
     }
     return result;
 }
+/** The durable author of an already-persisted Message, for an idempotent replay
+ * that must return the same actor label the original send computed. */
+function replayActor(message) {
+    if (message.author.type === "role")
+        return message.author.roleName === LEADER_ROLE ? "leader" : "role";
+    return message.author.type === "operator" ? "operator" : "user";
+}
 /**
  * Whether an inbound Message on a Task in this status is delivered to its
  * Leader. Draft qualifies because planning is a Leader conversation that
@@ -1956,6 +2148,8 @@ function taskRoleCommand(args, store, options) {
         return output(unbindTaskRole(rest, store, options));
     if (command === "session")
         return taskRoleSessionCommand(rest, store, options);
+    if (command === "interrupt")
+        return interruptTaskRole(rest, store, options);
     if (command === "view")
         return viewTaskRole(rest, store);
     if (command === "takeover")
@@ -1966,8 +2160,254 @@ function taskRoleCommand(args, store, options) {
         ? "Task role command is required."
         : `Unknown command: task role ${command}`);
 }
+/**
+ * `interrupt` stops the exact current native Turn through the Provider's own
+ * native cancel, and never through an owned-process kill, restart, or detach
+ * (decision-3 §1/§7). It is a control operation, not a persisted Message, so it
+ * carries no body of its own.
+ *
+ * The optional `--then-message` is the explicit continuation handoff
+ * (decision-3 §4): it names a Message the Leader already saved (typically the
+ * one a failed steer left behind, reusing that Message's original ref) and
+ * claims "deliver this once, in the same Session, after the interrupted Turn
+ * reaches a proven terminal, without the prior queue preempting it." The claim
+ * is registered on the durable Message before the live cancel. Registration is
+ * idempotent per interrupt requestId, and only one continuation may claim a
+ * given target AgentRun; a conflicting second claim is refused, never silently
+ * dropped or duplicated.
+ */
+function interruptTaskRole(args, store, options) {
+    const usage = "Task role interrupt usage: yui task role interrupt <task> <role> --expected-target <turn> [--then-message <task/message>] [--request-id <id>].";
+    const parsed = parseTail(args, new Set(["--expected-target", "--then-message", "--request-id"]), usage);
+    exactPositionals(parsed.positionals, 2, usage);
+    const expectedTarget = requiredOption(parsed.options, "--expected-target");
+    const thenMessageRef = optionalNonEmptyOption(parsed.options, "--then-message");
+    const requestId = optionalNonEmptyOption(parsed.options, "--request-id");
+    const now = clock(options);
+    const task = requireTask(store, parsed.positionals[0]);
+    const role = requireRole(store, task.id, parsed.positionals[1]);
+    const fingerprint = createHash("sha256").update(JSON.stringify({
+        roleName: role.name, expectedTarget, thenMessageRef: thenMessageRef ?? null
+    })).digest("hex");
+    const operationId = requestId ?? `interrupt-${fingerprint}`;
+    let receiptId = "";
+    const resolved = store.transaction((tx) => {
+        assertTaskOpen(task);
+        assertTaskInputControlAuthority(tx, options.environment, task.id, role.name);
+        const previous = findTaskInterrupt(tx, task.id, operationId);
+        if (previous !== undefined) {
+            if (previous.payload.fingerprint !== fingerprint)
+                throw usageError("Interrupt requestId already names a different target or then input.");
+            return output("Interrupt already recorded; no native request was repeated.\n", {
+                taskId: task.id, roleName: role.name, interrupt: {
+                    state: "idempotent-replay", receipt: taskInterruptReceipt(tx, task.id, previous.payload.receiptId)
+                }
+            });
+        }
+        const resolution = resolveTaskInputControl(tx, task.id, role.name, "interrupt", expectedTarget);
+        if (resolution.outcome !== "ready") {
+            return output(`Interrupt not delivered (${resolution.code}: ${resolution.detail}).\n`, { taskId: task.id, roleName: role.name,
+                interrupt: { state: "not-interrupted", code: resolution.code, detail: resolution.detail } });
+        }
+        const priorTarget = tx.listEvents(task.id).find(event => event.type === "input.interrupt-requested"
+            && event.payload.roleName === role.name && event.payload.nativeSessionId === resolution.target.nativeSessionId
+            && event.payload.attemptId === resolution.target.attemptId
+            && !taskInterruptWasRejected(tx, task.id, event.payload.receiptId));
+        if (priorTarget !== undefined) {
+            return output("This exact Turn already has an interrupt request; inspect its original receipt.\n", {
+                taskId: task.id, roleName: role.name, interrupt: {
+                    state: "not-interrupted", code: "DELIVERY_UNKNOWN", receiptId: priorTarget.payload.receiptId
+                }
+            });
+        }
+        if (thenMessageRef !== undefined) {
+            const claimResult = registerInterruptThen(tx, task.id, role.name, thenMessageRef, resolution.target, operationId, options, now);
+            if (claimResult !== "claimed") {
+                return output(`Interrupt not delivered (${claimResult.code}: ${claimResult.detail}).\n`, { taskId: task.id, roleName: role.name,
+                    interrupt: { state: "not-interrupted", code: claimResult.code, detail: claimResult.detail } });
+            }
+        }
+        receiptId = reserveTaskInterrupt(tx, task.id, operationId, fingerprint, resolution.target, thenMessageRef, now);
+        return resolution.target;
+    });
+    if ("kind" in resolved)
+        return resolved;
+    return {
+        kind: "input-interrupt",
+        taskId: task.id,
+        roleName: role.name,
+        target: resolved,
+        receiptId,
+        ...(thenMessageRef === undefined ? {} : {
+            thenMessageId: taskRecordReference(thenMessageRef, "message", "Then Message reference", options).localId
+        }),
+        output: `Interrupting ${task.id}/${role.name} at Turn ${resolved.nativeTurnId ?? resolved.attemptId}`
+            + `${thenMessageRef === undefined ? "" : `, then delivering ${thenMessageRef} once after a proven terminal`}.\n`
+    };
+}
+/**
+ * Bind a saved Message as the one continuation of a target AgentRun. The target
+ * run is the exact interrupted Turn's durable AgentRun; the claim is refused
+ * when the target has no AgentRun (a native-only Turn cannot prove its terminal
+ * for a later same-Session delivery), when the Message is unknown or not a
+ * legal saved input to reuse, or when another continuation already claims that
+ * run.
+ *
+ * The Message being reused must be a legal handoff for this exact interrupt: it
+ * must belong to this Role's current Assignment, must not already have been
+ * delivered or marked undeliverable, and must not still be a live control op.
+ * Its original input identity is preserved as `interruptThen.reusedInput`
+ * provenance rather than erased, so a replay of that requestId keeps resolving
+ * to this same Message and never creates a second input (decision-3 §3).
+ */
+function registerInterruptThen(store, taskId, roleName, thenMessageRef, target, requestId, options, now) {
+    const targetAttemptId = target.attemptId;
+    const ref = taskRecordReference(thenMessageRef, "message", "Then Message reference", options);
+    if (ref.taskId !== taskId) {
+        return { code: "TARGET_CHANGED", detail: "The then-Message belongs to another Task." };
+    }
+    const message = store.listMessages(taskId).find((entry) => entry.id === ref.localId);
+    if (message === undefined) {
+        return { code: "TARGET_CHANGED", detail: `Then-Message ${thenMessageRef} is unknown.` };
+    }
+    // The claim is keyed on the exact interrupted native Turn (targetAttemptId),
+    // which the resolution proved present under the current Session. An AgentRun
+    // owns the Turn for a Worker/Reviewer Assignment; a Leader's own management or
+    // Draft planning Turn is a real native Turn with NO AgentRun (decision-3 §9,
+    // message-5 gap B). The claim never invents a Run to prove a terminal — the
+    // native Turn is the primary proof, and targetRunId is recorded only when a Run
+    // actually owns the Turn.
+    const active = store.getActiveRun(taskId, roleName);
+    // A synthesized fallback id is an opaque idempotency key (compared only for
+    // equality, never parsed), so it must satisfy the same safe-identity rule as a
+    // caller-supplied requestId: no path separators. Use `:` as the field joiner —
+    // the receiptId carries the `/`-shaped human receipt, this key stays slash-free.
+    const claimRequestId = requestId ?? `interrupt:${taskId}:${roleName}:${targetAttemptId}`;
+    // Idempotent per interrupt requestId: an exact repeat of the same claim (same
+    // request, same native Turn) is a no-op that still authorizes the live cancel.
+    if (message.interruptThen !== undefined) {
+        const prior = findTaskInterrupt(store, taskId, message.interruptThen.requestId);
+        const canReferenceClaim = message.interruptThen.requestId === claimRequestId
+            || (prior !== undefined && taskInterruptWasRejected(store, taskId, prior.payload.receiptId));
+        if (canReferenceClaim && message.interruptThen.notDeliveredReason === undefined
+            && message.interruptThen.targetAttemptId === targetAttemptId
+            && message.interruptThen.targetNativeSessionId === target.nativeSessionId
+            && message.interruptThen.targetAgentId === target.agentId
+            && message.interruptThen.targetAdapterId === target.adapterId
+            && message.interruptThen.targetRoleName === roleName
+            && message.interruptThen.targetAuthorityEpoch === target.authority.epoch
+            && message.interruptThen.targetAuthorityHolderId === target.authority.holderId)
+            return "claimed";
+        return { code: "TARGET_CHANGED",
+            detail: `Message ${thenMessageRef} already claims a continuation of Turn ${message.interruptThen.targetAttemptId}.` };
+    }
+    const inputState = taskMessageInputControlState(message);
+    if (inputState === "accepted" || inputState === "pending" || inputState === "delivery-unknown") {
+        return {
+            code: inputState === "accepted" ? "TARGET_CHANGED" : "DELIVERY_UNKNOWN",
+            detail: `Message ${thenMessageRef} has steer disposition ${inputState}; it cannot be submitted again.`
+        };
+    }
+    // The reused Message must be a legal handoff for this exact interrupt. A
+    // Worker/Reviewer handoff must be addressed to the interrupted Assignment; a
+    // no-Run Leader handoff (its own management/Draft turn) reuses a Leader input,
+    // which is never addressed to a Worker Assignment (no ownerRunId).
+    if (roleName !== LEADER_ROLE) {
+        if (active === null || message.recipient?.roleName !== roleName || message.recipient.ownerRunId !== active.id) {
+            return { code: "TARGET_CHANGED",
+                detail: `Message ${thenMessageRef} is not addressed to the current execution Assignment.` };
+        }
+    }
+    else if (message.recipient?.ownerRunId !== undefined) {
+        return { code: "TARGET_CHANGED",
+            detail: `Message ${thenMessageRef} is addressed to an execution Assignment and cannot be a no-Run ${roleName} handoff.` };
+    }
+    // A Message that already delivered, or was already ruled undeliverable, is not
+    // a fresh input to reuse; reusing it would replay or resurrect a settled fact.
+    if (message.continuation?.runId !== undefined) {
+        return { code: "TARGET_CHANGED", detail: `Message ${thenMessageRef} was already delivered by ${message.continuation.runId}.` };
+    }
+    if (message.continuation?.notDeliveredReason !== undefined) {
+        return { code: "TARGET_CHANGED",
+            detail: `Message ${thenMessageRef} was already settled not-delivered (${message.continuation.notDeliveredReason}).` };
+    }
+    // Only one continuation may claim a given target native Turn.
+    const existing = store.listMessages(taskId).find((entry) => entry.interruptThen?.targetAttemptId === targetAttemptId && entry.id !== message.id);
+    if (existing !== undefined) {
+        return { code: "TARGET_CHANGED",
+            detail: `Turn ${targetAttemptId} is already the terminal target of Message ${existing.id}.` };
+    }
+    // Reference the new op without rewriting the original input facts: keep the
+    // Message's history, move any steer identity into reusedInput provenance (so a
+    // replay of that requestId still resolves here, never a second input), and
+    // clear only the live steer action so the handoff is deliverable by the queued
+    // continuation path after a proven terminal.
+    const { inputControl, ...rest } = message;
+    store.updateMessage(taskId, { ...rest,
+        interruptThen: { requestId: claimRequestId, targetAttemptId,
+            targetRoleName: roleName, targetNativeSessionId: target.nativeSessionId,
+            targetAgentId: target.agentId, targetAdapterId: target.adapterId,
+            targetAuthorityEpoch: target.authority.epoch, targetAuthorityHolderId: target.authority.holderId,
+            ...(target.nativeTurnId === undefined ? {} : { targetNativeTurnId: target.nativeTurnId }),
+            ...(active === null ? {} : { targetRunId: active.id }),
+            ...(inputControl === undefined ? {} : { reusedInput: inputControl }) } });
+    recordTaskEvent(store, taskId, "message.interrupt-then-claimed", {
+        messageId: message.id, roleName, targetAttemptId,
+        ...(active === null ? {} : { targetRunId: active.id }),
+        ...(inputControl === undefined ? {} : { reusedRequestId: inputControl.requestId })
+    }, now);
+    // Release trigger for a no-Run Leader handoff (decision-3 §4/§9). A
+    // Worker/Reviewer claim (active !== null) is released by the reconcile loop's
+    // unconditional prepareMessageContinuations pass, driven by the owning
+    // AgentRun's terminal — no extra wake is needed. A no-Run Leader turn owns no
+    // AgentRun and is never surfaced by that push path; it is delivered only by
+    // being woken to read its own Context. The interrupt itself (and, when the
+    // handoff reuses a Leader self-steer, wakePolicy "none") enqueues no wake, so
+    // without this the claim would be structurally unreleasable: listPendingWakeups
+    // never selects the Task and the busy-gated leader mailbox is never consulted.
+    // Enqueue that wake now, keyed to the claimed Message so an idempotent repeat of
+    // the same claim does not stack a second one; claimLeaderNotification holds it
+    // until the interrupted native Turn reaches its proven terminal, and only then
+    // does the Leader read the Context that surfaces this handoff.
+    if (roleName === LEADER_ROLE) {
+        enqueueWork(store, leaderMailbox(taskId), "interrupt-then", now, [messageRef(taskId, message.id)], { source: "interrupt-then", dedupeKey: `interrupt-then:${taskId}:${message.id}` });
+    }
+    return "claimed";
+}
 function taskRoleSessionCommand(args, store, options) {
     const [command, ...rest] = args;
+    if (command === "retry") {
+        const [taskId, roleName, action = "show", ...extra] = rest;
+        if (extra.length > 0 || !["show", "cancel", "disable", "enable"].includes(action)) {
+            throw usageError("Usage: yui task role session retry <task> <role> [show|cancel|disable|enable]");
+        }
+        return store.transaction(tx => {
+            const task = requireTask(tx, taskId);
+            const role = requireRole(tx, task.id, roleName);
+            if (action !== "show")
+                taskActor(tx, options, task.id);
+            else {
+                const reader = resolveManagedTaskReader(tx, options.environment);
+                if (reader === undefined)
+                    taskActor(tx, options, task.id);
+                else if (reader.taskId !== task.id || reader.roleName !== "leader" && reader.roleName !== role.name) {
+                    throw usageError("Provider retry read is outside the caller's Task/Role.");
+                }
+            }
+            const sessions = tx.getTaskRoleSessionSet(task.id, role.name);
+            let binding = sessions?.providerBinding ?? null;
+            if (action !== "show") {
+                if (task.status === "archived" || sessions === null || binding === null)
+                    throw usageError("No writable Provider Session.");
+                binding = controlProviderRetry(binding, action, clock(options).getTime());
+                tx.saveTaskRoleSessionSet({ ...sessions, providerBinding: binding });
+                recordTaskEvent(tx, task.id, "provider.retry-control", { roleName: role.name, action }, clock(options));
+            }
+            return output(`${renderProviderRetry(binding)}\n`, {
+                roleName: role.name, retry: providerRetryProjection(binding), disabled: binding?.retryDisabled ?? false
+            });
+        });
+    }
     if (command === "inspect") {
         exactPositionals(rest, 2, "Task Role Session inspect usage: yui task role session inspect <task> <role>.");
         const task = requireTask(store, rest[0]);
@@ -1987,6 +2427,7 @@ function taskRoleSessionCommand(args, store, options) {
         // means there was nothing an Agent reported, and the one-line label above
         // still states which of the "no value" cases applies.
         const runConfiguration = active === null ? undefined : options.liveRunConfiguration;
+        const host = options.liveHostObservations?.[role.name];
         const runConfigurationDetail = renderAgentRunConfiguration(runConfiguration);
         return output(active === null
             ? `No attached Session exists for ${task.id}/${role.name}.\n`
@@ -2000,6 +2441,8 @@ function taskRoleSessionCommand(args, store, options) {
                 `Native id: ${active.nativeSessionId}`,
                 `Session: ${active.status}${active.endReason === undefined ? "" : `/${active.endReason}`}`,
                 `AgentRun: ${binding?.run?.status ?? "none"}`,
+                renderProviderRetry(binding),
+                ...(host === undefined ? [] : [`Host reporting: ${taskRoleHostDiagnostic(host)}`]),
                 `Run configuration: ${agentRunConfigurationLabel(runConfiguration)}`
             ].join("\n") + "\n"
                 + `\n${renderRoleLaunchComparison(role, active.effective)}\n`
@@ -2008,6 +2451,8 @@ function taskRoleSessionCommand(args, store, options) {
             role,
             session: active,
             providerBinding: binding,
+            retry: providerRetryProjection(binding),
+            ...(host === undefined ? {} : { host }),
             ...(runConfiguration === undefined ? {} : { runConfiguration })
         });
     }
@@ -2051,9 +2496,6 @@ function taskRoleSessionCommand(args, store, options) {
         const now = clock(options);
         const request = store.transaction((tx) => {
             const task = requireTask(tx, parsed.positionals[0]);
-            if (!["draft", "active", "completed", "cancelled"].includes(task.status)) {
-                throw usageError(`Task Role Session stop is unavailable for an archived Task: ${task.id}.`, usage);
-            }
             const actor = taskActor(tx, options, task.id);
             const role = requireRole(tx, task.id, parsed.positionals[1]);
             if (actor === "leader" && role.name === LEADER_ROLE) {
@@ -2172,14 +2614,14 @@ function addTaskRole(args, store, options) {
         `Runtime source: ${runtimeSource}`,
         `Agent: ${result.role.activeAgentId}/${result.binding.adapterId}`,
         `Model: ${result.binding.config.model ?? "CLI default"}; effort: ${result.binding.config.effort ?? "CLI default"}; permission: ${result.binding.config.permission.strategy}`,
-        "Next: create a WorkItem and start this Role when it has assigned work."
+        "Next: dispatch an assigned WorkItem, or request a Task-final Review with this Role; a Review needs no WorkItem."
     ].join("\n").concat("\n");
 }
 function listTaskRoles(args, store, options) {
     exactPositionals(args, 1, "Task role list usage: yui task role list <task>.");
     const task = requireTask(store, args[0]);
     const roles = store.listRoles(task.id);
-    const statuses = inspectTaskRoleRuntimeStatuses(task.id, roles, store, options.runtime?.inspectTaskRolePanes?.(task.id) ?? [], options.now?.() ?? new Date());
+    const statuses = inspectTaskRoleRuntimeStatuses(task.id, roles, store, options.runtime?.inspectTaskRolePanes?.(task.id) ?? [], options.now?.() ?? new Date()).map(status => withTaskRoleHostObservation(status, options.liveHostObservations?.[status.roleName]));
     if (statuses.length === 0)
         return output("No roles assigned.\n", { roles: statuses });
     return output(`${renderTable(`Task roles: ${task.id}`, [
@@ -2209,7 +2651,8 @@ function taskRoleStatus(args, store, options) {
     const [status] = inspectTaskRoleRuntimeStatuses(task.id, [role], store, options.runtime?.inspectTaskRolePanes?.(task.id) ?? [], options.now?.() ?? new Date());
     if (status === undefined)
         throw roleNotFound(role.name);
-    return output(renderTaskRoleRuntimeStatus(status), { role: status });
+    const observed = withTaskRoleHostObservation(status, options.liveHostObservations?.[role.name]);
+    return output(renderTaskRoleRuntimeStatus(observed), { role: observed });
 }
 function showTaskRole(args, store) {
     exactPositionals(args, 2, "Task role show usage: yui task role show <task> <role>.");
@@ -2956,6 +3399,17 @@ function updateWork(args, store, options) {
         workItem: result.item
     });
 }
+/** Shared with CLI preflight so a refused dispatch cannot prepare workspaces. */
+export function requireWorkItemAssignee(item) {
+    if (item.assignee === undefined) {
+        throw usageError(`Work Item has no Task Role assignee: ${item.id}. `
+            + `The Task Leader can execute it directly without dispatch: `
+            + `yui task work update ${item.taskId}/${item.id} running. `
+            + (item.writeProjectIds.length === 0 ? "" :
+                `For code, first use yui task work isolate ${item.taskId}/${item.id}.`));
+    }
+    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);
@@ -2969,11 +3423,8 @@ function dispatchWork(args, store, options) {
         if (task.status !== "active")
             throw usageError(inactiveTaskMessage(task, "dispatch"));
         assertTaskExecutionEnabled(task, "dispatching work");
-        if (item.assignee === undefined) {
-            throw usageError(`Work Item has no Task Role assignee: ${item.id}. `
-                + `The Task Leader must run "yui task work update ${item.id} running" and execute it directly.`);
-        }
-        const lanePlan = planReplicatedWorkItemLanes(item.assignee, requestedLaneRoles, `execution-group-${tx.peekNextRunId(task.id)}`);
+        const assignee = requireWorkItemAssignee(item);
+        const lanePlan = planReplicatedWorkItemLanes(assignee, requestedLaneRoles, `execution-group-${tx.peekNextRunId(task.id)}`);
         const currentGroup = currentWorkItemExecutionGroup(item);
         if (item.status !== "open") {
             throw usageError(`Work item ${item.id} cannot be dispatched from ${item.status}.`);
@@ -3010,7 +3461,7 @@ function dispatchWork(args, store, options) {
         const rawInput = trimmed(parsed.options.get("--input")) ?? item.objective;
         let workItemForDispatch = prepareWorkItemDispatch(item, now);
         if (lanePlan.roles.length === 0) {
-            const role = requireRole(tx, task.id, item.assignee);
+            const role = requireRole(tx, task.id, assignee);
             if (tx.getActiveRun(task.id, role.name) !== null) {
                 throw usageError(`${task.id}/${role.name} already has an active run.`);
             }
@@ -4393,6 +4844,45 @@ function settleStaleFinalReviewRun(args, store, options) {
         : `Obsolete final Review already settled: ${result.round.id}/${result.run.id}\n`, { reviewRound: result.round, reviewRun: result.run });
 }
 function retryRun(args, store, options) {
+    return store.transaction(tx => {
+        const previous = requireRun(tx, args[0], options);
+        const existing = tx.listEvents(previous.taskId).find(event => event.type === "run.retried"
+            && event.payload.previousRunId === previous.id);
+        if (existing !== undefined) {
+            return output(`Retry already recorded as ${existing.payload.runId}; retry that exact successor if needed.\n`);
+        }
+        const sessions = tx.getTaskRoleSessionSet(previous.taskId, previous.roleName);
+        const retry = sessions?.providerBinding?.retry;
+        if (options.providerRetryChainId !== undefined
+            && (retry?.chainId !== options.providerRetryChainId || retry.status !== "waiting"
+                || retry.previousRunId !== previous.id || clock(options).getTime() < Date.parse(retry.nextEligibleAt)
+                || clock(options).getTime() >= Date.parse(retry.deadline))) {
+            throw usageError("Provider recovery intent is no longer eligible.");
+        }
+        const result = retryRunOperation(args, tx, options);
+        if (retry !== undefined && retry.status !== "recovered" && retry.previousRunId === previous.id && sessions?.providerBinding != null) {
+            const successor = tx.getActiveRun(previous.taskId, previous.roleName);
+            tx.saveTaskRoleSessionSet({
+                ...sessions, providerBinding: {
+                    ...sessions.providerBinding, retry: {
+                        ...retry, status: "waiting", successorAutomatic: options.providerRetryChainId !== undefined,
+                        ...(options.providerRetryChainId === undefined ? {
+                            intentAt: clock(options).toISOString(),
+                            // An explicit manual attempt does not inherit automatic jitter,
+                            // but cannot shorten a trusted server minimum.
+                            nextEligibleAt: new Date(Math.max(clock(options).getTime(), retry.error.retryAfterMs === undefined ? 0
+                                : Date.parse(sessions.providerBinding.run.updatedAt) + retry.error.retryAfterMs + 1)).toISOString()
+                        } : {}),
+                        ...(successor === null ? {} : { successorRunId: successor.id }),
+                        ...(previous.reviewRoundId === undefined ? {} : { successorReviewRoundId: previous.reviewRoundId })
+                    }
+                }
+            });
+        }
+        return result;
+    });
+}
+function retryRunOperation(args, store, options) {
     exactPositionals(args, 1, "Task turn retry usage: yui task run retry <task>/<run>.");
     const now = clock(options);
     const previous = store.transaction((tx) => requireRun(tx, args[0], options));
@@ -4952,7 +5442,7 @@ function retryFailedReviewRun(previous, store, options, now) {
         const task = requireTask(tx, run.taskId);
         if (task.status !== "active")
             throw usageError(`Task is not active: ${task.id}.`);
-        const requestedBy = taskActor(tx, options, task.id);
+        const requestedBy = options.providerRetryChainId === undefined ? taskActor(tx, options, task.id) : "policy";
         const round = tx.getReviewRound(task.id, run.reviewRoundId);
         if (round === null) {
             throw dataError(`ReviewRound not found for run ${run.id}: ${run.reviewRoundId}.`);
@@ -5821,7 +6311,7 @@ function activeReviewRoundForCandidate(store, item, candidate) {
 }
 function createTaskRole(store, task, roleName, explicitAgentId, now, sourceGlobalRoleName) {
     const workspace = task.status === "draft"
-        ? join(`${store.rootDirectory()}.task-runtimes`, "planning", task.id)
+        ? planningRuntimeCwd(store.rootDirectory(), task.id)
         : task.cwd ?? store.getConfig().defaultWorkspace ?? process.cwd();
     if (explicitAgentId === undefined) {
         const sourceRoleName = sourceGlobalRoleName
@@ -5851,7 +6341,7 @@ function requireAgentProfile(store, id) {
 }
 function createTaskRoleFromAgentBinding(store, task, roleName, binding, now) {
     const workspace = task.status === "draft"
-        ? join(`${store.rootDirectory()}.task-runtimes`, "planning", task.id)
+        ? planningRuntimeCwd(store.rootDirectory(), task.id)
         : task.cwd ?? store.getConfig().defaultWorkspace ?? process.cwd();
     return createRole(task.id, roleName, [binding], binding.agentId, workspace, now);
 }