@zq-silk/yui 0.15.9 → 0.15.11

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
+import { recordTaskInterruptResult } from "./message/taskInterrupt.js";
 import { agentAdapterLabel as adapterLabel } from "./agent/adapterCatalog.js";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
@@ -12,6 +13,7 @@ import { describeCommandTree, findCommandNode } from "./cli/commandCatalog.js";
 import { routeInvocation } from "./cli/invocationRouter.js";
 import { renderCompletion } from "./cli/completion.js";
 import { resolveCompletionCandidates } from "./cli/dynamicCompletion.js";
+import { recordGlobalInterruptResult, recordGlobalSteerResult } from "./message/globalInterrupt.js";
 import { allowsInteractiveSelection, resolveInteractiveArguments } from "./cli/interactiveSelection.js";
 import { runCompletionWizard } from "./cli/completionWizard.js";
 import { renderAgentConfigurationResolutionNotice } from "./cli/agentConfigurationPicker.js";
@@ -40,8 +42,9 @@ import { runResourcesCommand } from "./commands/resourcesCommands.js";
 import { applyOperatorSessionControl, runOperatorCommand } from "./commands/operatorCommands.js";
 import { runProjectCommand } from "./commands/projectCommands.js";
 import { previewProfileAgentConfigurationMutation, runProfileCommand } from "./commands/profileCommands.js";
-import { assertWorkItemDependenciesCompletedForCommand, dispatchPreparedReviewRound, failPendingReviewRound, preserveReviewRoundWorkspace, parseTaskCompletionRequest, previewTaskRoleAgentConfigurationMutation, preflightTaskCompletion, runTaskCommand, planReplicatedWorkItemLanes, validateTaskArchiveRequest } from "./commands/taskCommands.js";
+import { assertWorkItemDependenciesCompletedForCommand, requireWorkItemAssignee, dispatchPreparedReviewRound, failPendingReviewRound, preserveReviewRoundWorkspace, parseTaskCompletionRequest, previewTaskRoleAgentConfigurationMutation, preflightTaskCompletion, runTaskCommand, planReplicatedWorkItemLanes, validateTaskArchiveRequest } from "./commands/taskCommands.js";
 import { assertTaskRemoteDeliveryIntegrated, createTaskRemoteDeliveryProof } from "./commands/taskRemoteDeliveryCommand.js";
+import { renderArchiveDiagnostics, taskArchiveDiagnostics } from "./task/archiveDiagnostics.js";
 import { runTaskPublicationVerifyCommand } from "./commands/taskPublicationVerifyCommand.js";
 import { createGitHubCliPublicationVerifier } from "./external/githubPublicationVerifier.js";
 import { createGitLabCliPublicationVerifier } from "./external/gitlabPublicationVerifier.js";
@@ -75,10 +78,11 @@ import { runRuntimeObservationHookCommand } from "./controller/runtimeObservatio
 import { buildDoctorReport, renderDoctor, runDoctorCommand } from "./doctor/doctor.js";
 import { agentNotFound, CliError, runtimeError, usageError } from "./errors/cliError.js";
 import { FileRoleLaunchPlanner } from "./executor/fileRoleLaunchPlanner.js";
-import { AGENT_HOST_CONTROL_PROTOCOL, inspectAgentHost, runAgentHost, sendAgentHostAuthorityControl } from "./runtime/agentHost.js";
+import { AGENT_HOST_CONTROL_PROTOCOL, inspectAgentHost, runAgentHost, sendAgentHostAuthorityControl, sendAgentHostSteerControl, sendAgentHostCancelControl, foldSteerLiveReceipt, foldInterruptLiveReceipt } from "./runtime/agentHost.js";
 import { unknownAgentRunConfiguration } from "./runtime/agentRunConfiguration.js";
 import { TaskWorkspaceCoordinator, WorkspaceCleanupBlockedError } from "./repository/taskWorkspaceCoordinator.js";
 import { FileTaskWorkspacePreparer } from "./repository/taskWorkspacePreparer.js";
+import { snapshotWorkItemCandidate } from "./repository/workItemCandidateSnapshot.js";
 import { inspectStorageSchema } from "./storage/storageSchema.js";
 import { collectRuntimeBuildIdentity, collectStorageIdentity, countDroppedInboxEvents, createProductionRuntimeIdentityPorts, evaluateStorageHealth, resolveStatusIdentityEnabled } from "./observability/runtimeIdentity.js";
 import { resolveYuiHome } from "./storage/taskStore.js";
@@ -748,11 +752,146 @@ export async function main() {
             emit(result);
             return;
         }
+        // The session surface (record/replace/enter/context) only ever yields the
+        // enter control; the live input actions live under the top-level `role`
+        // command below, never here.
+        if (result.kind !== "enter") {
+            throw new Error("Session commands cannot perform a live input control.");
+        }
         await ensureFileTaskController(home, { environment: process.env });
         await runtime.prepareGlobalRoleEnter(result.role.name);
         tmux.attachRole("operator", result.role.name, "auto");
         return;
     }
+    if (resolved[0] === "role") {
+        // decision-3 §7 CLI grammar: the durable Global input actions are top-level
+        // `role message queue|steer <global-role> …` and `role interrupt
+        // <global-role> …`, distinct from `config role …` (desired configuration)
+        // and `session …` (native session lifecycle). Core persists the durable
+        // Global-owned Message, proves owner/target/capability/writer-fence from
+        // durable state, and returns either a string disposition (queued,
+        // idempotent-replay, or an explicit not-steered/not-interrupted failure with
+        // its exact code) or a resolved live intent. The CLI performs at most one
+        // native edge with scope "global" and taskId omitted — the same shared
+        // resolver and transport as a Task Role, never a fabricated Task.
+        let globalInputFailure;
+        const roleOptions = {
+            yuiHome: home,
+            env: process.env,
+            jsonOutput,
+            onInputFailure: failure => { globalInputFailure = failure; }
+        };
+        const result = runGlobalRoleCommand(resolved.slice(1), store, roleOptions);
+        if (resolved[1] === "message" && resolved[2] === "queue" && resolved[3] !== undefined) {
+            await callController(home, "scheduler.signal", {
+                key: `global-role:${encodeURIComponent(resolved[3])}`
+            }).catch(() => { });
+        }
+        if (typeof result === "string") {
+            if (globalInputFailure !== undefined) {
+                emitControlFailure(globalInputFailure.detail, globalInputFailure.code, globalInputFailure.data);
+                return;
+            }
+            emit(result);
+            return;
+        }
+        if (result.kind === "input-steer") {
+            // Core already persisted the durable Global Message and proved target +
+            // capability + writer fence from the Global Role's own Session set. This
+            // is the single live edge: one native steer of the exact current Turn,
+            // scope "global", no retarget and no fallback to interrupt or queue.
+            await ensureFileTaskController(home, { environment: process.env });
+            let control;
+            try {
+                control = await sendAgentHostSteerControl({
+                    home,
+                    scope: "global",
+                    roleName: result.roleName,
+                    control: {
+                        protocol: AGENT_HOST_CONTROL_PROTOCOL,
+                        type: "steer-turn",
+                        nativeSessionId: result.target.nativeSessionId,
+                        nativeTurnId: result.target.nativeTurnId ?? result.target.attemptId,
+                        authority: result.target.authority,
+                        run: { attemptId: result.receiptId, boundedText: result.text }
+                    }
+                });
+            }
+            catch (error) {
+                recordGlobalSteerResult(store, result.roleName, result.messageId, {
+                    state: "steer-unknown", outcome: "pending",
+                    detail: error instanceof Error ? error.message : String(error)
+                });
+                throw runtimeError(`Steer message ${result.messageId} is saved but the native steer did not complete: `
+                    + `${error instanceof Error ? error.message : String(error)}. `
+                    + "The Message is retained and its outcome is recorded from the Host; whether the "
+                    + "Provider accepted it may be delivery-unknown. Re-read the Session before acting; "
+                    + "do not reissue the same input under a new requestId or a different action.");
+            }
+            const steer = foldSteerLiveReceipt(control);
+            recordGlobalSteerResult(store, result.roleName, result.messageId, steer);
+            if (steer.state !== "steered") {
+                emitControlFailure(steerReceiptOutput(result.output, result.roleName, result.messageId, steer), steer.state === "steer-unknown" ? "DELIVERY_UNKNOWN" : "STEER_NOT_DELIVERED", { roleName: result.roleName, messageId: result.messageId, steer });
+                return;
+            }
+            emit(steerReceiptOutput(result.output, result.roleName, result.messageId, steer), false, {
+                roleName: result.roleName,
+                messageId: result.messageId, steer
+            });
+            return;
+        }
+        if (result.kind === "input-interrupt") {
+            // The single live edge for a Global interrupt: one native cancel of the
+            // exact current Turn, scope "global". Never a kill/restart/detach. Any
+            // then-handoff was already claimed durably by Core (an existing Global
+            // Message owned by this Role) and is delivered once by the ordinary
+            // continuation path after this Turn reaches a proven terminal.
+            await ensureFileTaskController(home, { environment: process.env });
+            let control;
+            try {
+                control = await sendAgentHostCancelControl({
+                    home,
+                    scope: "global",
+                    roleName: result.roleName,
+                    control: {
+                        protocol: AGENT_HOST_CONTROL_PROTOCOL,
+                        type: "cancel",
+                        nativeOnly: true,
+                        nativeSessionId: result.target.nativeSessionId,
+                        attemptId: result.target.attemptId,
+                        authority: result.target.authority
+                    }
+                });
+            }
+            catch (error) {
+                recordGlobalInterruptResult(store, result.roleName, result.receiptId, {
+                    state: "interrupt-unknown", outcome: "cancel-requested",
+                    detail: error instanceof Error ? error.message : String(error)
+                });
+                throw runtimeError(`Interrupt of global role ${result.roleName} did not complete: `
+                    + `${error instanceof Error ? error.message : String(error)}. `
+                    + "No process was killed; re-read the Session before retrying.");
+            }
+            const interrupt = foldInterruptLiveReceipt(control);
+            recordGlobalInterruptResult(store, result.roleName, result.receiptId, interrupt);
+            if (interrupt.state !== "interrupt-requested") {
+                emitControlFailure(interruptReceiptOutput(result.output, result.roleName, interrupt), interrupt.state === "interrupt-unknown" ? "DELIVERY_UNKNOWN" : "INTERRUPT_NOT_DELIVERED", { roleName: result.roleName, interrupt });
+                return;
+            }
+            emit(interruptReceiptOutput(result.output, result.roleName, interrupt), false, {
+                roleName: result.roleName,
+                ...(result.thenMessageId === undefined ? {} : { thenMessageId: result.thenMessageId }),
+                interrupt
+            });
+            return;
+        }
+        if (result.kind !== "enter") {
+            throw new Error("Role command returned an invalid control result.");
+        }
+        // A top-level `role` command never enters a runtime Session; that is
+        // `session enter`.
+        throw usageError("Use 'yui session enter <role>' to attach to a Global Role.");
+    }
     if (resolved[0] === "operator") {
         if (resolved[1] === "enter") {
             if (resolved.length !== 2)
@@ -1067,7 +1206,7 @@ export async function main() {
         let archiveRemoteDeliveryProof;
         let archiveTaskReviewCandidate;
         if (resolved[1] === "archive") {
-            const { taskId, disposition, forceUnverified } = validateTaskArchiveRequest(resolved.slice(2), store, {
+            const { taskId, disposition, force } = validateTaskArchiveRequest(resolved.slice(2), store, {
                 runtime,
                 environment: process.env,
                 yuiHome: home
@@ -1075,11 +1214,26 @@ export async function main() {
             const task = store.getTask(taskId);
             if (task === null)
                 throw new Error(`Task disappeared after archive validation: ${taskId}.`);
-            if (task.status !== "archived") {
+            if (force || task.status === "archived") {
+                // Archive admission and mandatory audit commit before any fallible
+                // filesystem/provider work. Repeats report facts, never replay cleanup.
+                const admitted = runTaskCommand(resolved.slice(1), store, {
+                    runtime, environment: process.env, yuiHome: home
+                });
+                if (force && admitted.kind === "output"
+                    && admitted.data.changed) {
+                    await workspaceCoordinator.cleanupArchivedTask(taskId, disposition);
+                }
+                const current = store.getTask(taskId);
+                const archive = taskArchiveDiagnostics(store, current);
+                emit(`Archived task ${taskId}\n${renderArchiveDiagnostics(archive)}`, false, { task: current, ...archive });
+                return;
+            }
+            {
                 if (disposition === "integrated") {
                     archiveTaskReviewCandidate = await actualTaskReviewCandidateForTaskCommand(resolved, store, workspacePreparer, process.env);
                     archiveRemoteDeliveryProof = createTaskRemoteDeliveryProof(store, task, archiveTaskReviewCandidate ?? null);
-                    assertTaskRemoteDeliveryIntegrated(archiveRemoteDeliveryProof.delivery, { forceUnverified });
+                    assertTaskRemoteDeliveryIntegrated(archiveRemoteDeliveryProof.delivery);
                 }
                 const workItemIds = store.listManagedWorkspaces(task.id)
                     .flatMap(({ owner }) => owner.type === "work-item" ? [owner.workItemId] : []);
@@ -1133,9 +1287,8 @@ export async function main() {
                 // Authority and pure Lane-shape checks precede every physical or
                 // durable workspace preparation performed for dispatch.
                 assertTaskDeliveryAuthority(store, process.env, task.id);
-                if (item.assignee !== undefined) {
-                    workItemDispatchLanePlan(resolved, store, item);
-                }
+                requireWorkItemAssignee(item);
+                workItemDispatchLanePlan(resolved, store, item);
             }
             // A rejected Candidate starts a new execution iteration. Release every
             // terminal Lane Role runtime before preparing the new Lane workspaces;
@@ -1259,17 +1412,17 @@ export async function main() {
                 laneDispatchRelease = preparedLanes.release;
                 laneDispatchProjectPaths = preparedLanes.projectPaths;
             }
-            const candidateGitSnapshot = await candidateSnapshotForTaskCommand(resolved, store, workspacePreparer, process.env, taskFinalReviewContract);
-            const directTaskMainSnapshot = await directTaskMainSnapshotForTaskCommand(resolved, store, workspacePreparer, process.env, taskFinalReviewContract);
+            const candidateSnapshots = await candidateSnapshotForTaskCommand(resolved, store, workspacePreparer, process.env, taskFinalReviewContract);
             const actualTaskReviewCandidate = archiveRemoteDeliveryProof === undefined
                 ? await actualTaskReviewCandidateForTaskCommand(resolved, store, workspacePreparer, process.env)
                 : archiveTaskReviewCandidate;
             const deltaRecheckPreflight = await deltaRecheckPreflightForTaskCommand(resolved.slice(1), store, actualTaskReviewCandidate);
-            // Read-only, and only for a Session inspect. The command itself stays
+            // Read-only Host evidence for Session inspect and Role status/list. The command stays
             // synchronous over persisted state; this is the live reading it prints
             // beside those facts, prepared here because the Host is reached over a
             // socket.
-            const liveRunConfiguration = await liveRunConfigurationForTaskCommand(resolved, store, home);
+            const liveHostObservations = await liveHostObservationsForTaskCommand(resolved, store, home);
+            const liveRunConfiguration = runConfigurationForHostObservation(liveHostObservations?.[resolved[5] ?? ""]);
             // Physical preparation may precede the durable write, but Task status,
             // workspace identity/cwd, and ManagedWorkspace ownership are adopted by
             // one transaction. A failed attempt therefore leaves the Task Draft and
@@ -1295,11 +1448,10 @@ export async function main() {
                     ? {}
                     : { completionPublishedTreeProof }),
                 ...(workItemIntegrationProof === undefined ? {} : { workItemIntegrationProof }),
-                ...(candidateGitSnapshot === undefined ? {} : { candidateGitSnapshot }),
+                ...candidateSnapshots,
                 ...(executionLaneWorkspaces === undefined ? {} : { executionLaneWorkspaces }),
                 ...(taskWorkspaceActivation === undefined ? {} : { taskWorkspaceActivation }),
                 ...(laneDispatchProjectPaths === undefined ? {} : { laneDispatchProjectPaths }),
-                ...(directTaskMainSnapshot === undefined ? {} : { directTaskMainSnapshot }),
                 ...(actualTaskReviewCandidate === undefined
                     ? {}
                     : { actualTaskReviewCandidate }),
@@ -1312,6 +1464,7 @@ export async function main() {
                 ...(liveRunConfiguration === undefined
                     ? {}
                     : { liveRunConfiguration }),
+                ...(liveHostObservations === undefined ? {} : { liveHostObservations }),
                 ...(taskRetirementProof === undefined ? {} : { taskRetirementProof }),
                 ...(validateAgentConfiguration === undefined
                     ? {}
@@ -1425,12 +1578,19 @@ export async function main() {
                         await workspacePreparer.prepareTaskWorkspace(task.id);
                     }
                 }
+                const controlData = result.data;
+                const failureCode = controlData?.steer?.code ?? controlData?.interrupt?.code;
+                if (failureCode !== undefined) {
+                    emitControlFailure(result.output, failureCode, result.data);
+                    return;
+                }
                 emit(`${result.output}${reviewOutput}`, false, reviewData === undefined
                     ? result.data
                     : { command: result.data, ...reviewData });
                 return;
             }
-            if (jsonOutput && result.kind !== "session-stop") {
+            if (jsonOutput && result.kind !== "session-stop"
+                && result.kind !== "input-steer" && result.kind !== "input-interrupt") {
                 throw usageError("Task Role view/takeover requires an interactive terminal.");
             }
             if (result.kind === "session-stop") {
@@ -1462,6 +1622,94 @@ export async function main() {
                 tmux.attachRole(result.taskId, result.roleName, "read-only");
                 return;
             }
+            if (result.kind === "input-steer") {
+                // Core already persisted the Message and proved target + capability +
+                // writer fence. This is the single live edge: one native steer of the
+                // exact current Turn, with no retarget and no fallback to interrupt or
+                // queue. Its durable settlement flows through the steer receipt fold.
+                await ensureFileTaskController(home, { environment: process.env });
+                let control;
+                try {
+                    control = await sendAgentHostSteerControl({
+                        home,
+                        scope: "task",
+                        taskId: result.taskId,
+                        roleName: result.roleName,
+                        control: {
+                            protocol: AGENT_HOST_CONTROL_PROTOCOL,
+                            type: "steer-turn",
+                            nativeSessionId: result.target.nativeSessionId,
+                            nativeTurnId: result.target.nativeTurnId ?? result.target.attemptId,
+                            authority: result.target.authority,
+                            run: { attemptId: result.receiptId, boundedText: result.text }
+                        }
+                    });
+                }
+                catch (error) {
+                    throw runtimeError(`Steer message ${result.messageId} is saved but the native steer did not complete: `
+                        + `${error instanceof Error ? error.message : String(error)}. `
+                        + "The Message is retained and its outcome is recorded from the Host; whether the "
+                        + "Provider accepted it may be delivery-unknown. Re-read the Session before acting; "
+                        + "do not reissue the same input under a new requestId or a different action.");
+                }
+                const steer = foldSteerLiveReceipt(control);
+                if (steer.state !== "steered") {
+                    emitControlFailure(steerReceiptOutput(result.output, `${result.taskId}/${result.roleName}`, result.messageId, steer), steer.state === "steer-unknown" ? "DELIVERY_UNKNOWN" : "STEER_REJECTED", { taskId: result.taskId, roleName: result.roleName, messageId: result.messageId, steer });
+                    return;
+                }
+                emit(steerReceiptOutput(result.output, `${result.taskId}/${result.roleName}`, result.messageId, steer), false, {
+                    taskId: result.taskId, roleName: result.roleName,
+                    messageId: result.messageId, steer
+                });
+                return;
+            }
+            if (result.kind === "input-interrupt") {
+                // The single live edge for interrupt: one native cancel of the exact
+                // current Turn. Never a kill/restart/detach. Any then-handoff was
+                // already claimed durably by Core and is delivered once by the ordinary
+                // continuation path after this Turn reaches a proven terminal.
+                await ensureFileTaskController(home, { environment: process.env });
+                let control;
+                try {
+                    control = await sendAgentHostCancelControl({
+                        home,
+                        scope: "task",
+                        taskId: result.taskId,
+                        roleName: result.roleName,
+                        control: {
+                            protocol: AGENT_HOST_CONTROL_PROTOCOL,
+                            type: "cancel",
+                            nativeOnly: true,
+                            nativeSessionId: result.target.nativeSessionId,
+                            // Native cancel names the exact original execution attempt it stops
+                            // (Host matches request.attemptId === activeRunAttemptId). That is
+                            // distinct from receiptId, the durable identity of this interrupt
+                            // control operation — never send the operation id as the turn id.
+                            attemptId: result.target.attemptId,
+                            authority: result.target.authority
+                        }
+                    });
+                }
+                catch (error) {
+                    recordTaskInterruptResult(store, result.taskId, result.receiptId, { state: "interrupt-unknown", outcome: "cancel-requested" });
+                    throw runtimeError(`Interrupt ${result.receiptId} of ${result.taskId}/${result.roleName} did not complete: `
+                        + `${error instanceof Error ? error.message : String(error)}. `
+                        + "No process was killed; re-read the Session before retrying.");
+                }
+                const interrupt = foldInterruptLiveReceipt(control);
+                recordTaskInterruptResult(store, result.taskId, result.receiptId, interrupt);
+                if (interrupt.state !== "interrupt-requested") {
+                    emitControlFailure(interruptReceiptOutput(result.output, `${result.taskId}/${result.roleName}`, interrupt), interrupt.state === "interrupt-unknown" ? "DELIVERY_UNKNOWN"
+                        : interrupt.state === "interrupt-not-active" ? "NO_ACTIVE_TURN" : "INTERRUPT_REJECTED", { taskId: result.taskId, roleName: result.roleName, receiptId: result.receiptId, interrupt });
+                    return;
+                }
+                emit(interruptReceiptOutput(result.output, `${result.taskId}/${result.roleName}`, interrupt), false, {
+                    taskId: result.taskId, roleName: result.roleName,
+                    ...(result.thenMessageId === undefined ? {} : { thenMessageId: result.thenMessageId }),
+                    interrupt
+                });
+                return;
+            }
             const syncAuthority = async (authorityResult) => {
                 let control;
                 try {
@@ -1766,34 +2014,11 @@ function assertWorkItemExecutionDependenciesForCommand(args, store, environment)
     assertWorkItemDependenciesCompletedForCommand(store, item);
 }
 async function candidateSnapshotForTaskCommand(args, store, preparer, environment, taskFinalReviewContract) {
-    if (args[0] !== "task")
-        return undefined;
-    const reviewableCandidateCommand = (args[1] === "work" && args[2] === "update"
-        && args[3] !== undefined && args[4] === "done") || (args[1] === "work" && args[2] === "group" && args[3] === "resolve"
-        && args[4] !== undefined);
-    // Explicit Task-final review requests must remain independent of the
-    // mutable global review trigger. Candidate snapshots are a delivery
-    // boundary for every writable WorkItem, not only review-configured Tasks.
-    const groupResolve = args[1] === "work" && args[2] === "group" && args[3] === "resolve";
-    if (!reviewableCandidateCommand
-        || (groupResolve && args.includes("--decision") && args[args.indexOf("--decision") + 1] !== "accept")) {
-        return undefined;
-    }
-    if (args[1] === "work" && args[2] === "update"
-        && args[3] !== undefined && args[4] === "done") {
-        const reference = cliWorkItemReference(args[3], environment);
-        const workspace = store.getWorkItemWorkspace(reference.taskId, reference.localId);
-        if (workspace === null) {
-            // The exact Task-final contract intentionally supports a Leader-direct,
-            // metadata-only Project Candidate. The command layer performs the full
-            // Task/WorkItem/source/contract validation before any aggregate write.
-            if (taskFinalReviewContract !== undefined)
-                return undefined;
-            throw usageError(`Reviewable direct WorkItem has no managed Candidate workspace: ${reference.localId}.`);
-        }
-        return preparer.snapshotCandidateWorkspace(workspace);
-    }
-    return undefined;
+    if (args[0] !== "task" || args[1] !== "work" || args[2] !== "update"
+        || args[3] === undefined || args[4] !== "done")
+        return {};
+    const reference = cliWorkItemReference(args[3], environment);
+    return snapshotWorkItemCandidate(store, preparer, reference.taskId, reference.localId, taskFinalReviewContract);
 }
 async function prepareExecutionLaneWorkspacesForCommand(args, store, preparer, environment) {
     const isDispatch = args[0] === "task"
@@ -1878,37 +2103,6 @@ async function prepareReviewLaneWorkspaces(taskId, reviewRoundId, store, prepare
     }
     return map;
 }
-async function directTaskMainSnapshotForTaskCommand(args, store, preparer, environment, taskFinalReviewContract) {
-    if (taskFinalReviewContract === undefined
-        || args[0] !== "task"
-        || args[1] !== "work"
-        || args[2] !== "update"
-        || args[3] === undefined
-        || args[4] !== "done") {
-        return undefined;
-    }
-    const reference = cliWorkItemReference(args[3], environment);
-    const item = store.getWorkItem(reference.taskId, reference.localId);
-    if (item === null || item.writeProjectIds.length === 0
-        || store.getWorkItemWorkspace(reference.taskId, reference.localId) !== null) {
-        return undefined;
-    }
-    const workspace = store.getTaskWorkspace(reference.taskId);
-    // Exact Task-final Candidates may intentionally be metadata-only when no
-    // Task main exists. They remain review anchors, but are not eligible for the
-    // direct ChangeSet capture path.
-    if (workspace === null)
-        return undefined;
-    if (workspace.owner.type !== "task") {
-        throw usageError(`Task has no authoritative main workspace: ${reference.taskId}.`);
-    }
-    try {
-        return await preparer.snapshotDirectTaskMain(workspace, item.writeProjectIds);
-    }
-    catch (error) {
-        throw usageError(error instanceof Error ? error.message : String(error));
-    }
-}
 async function actualTaskReviewCandidateForTaskCommand(args, store, preparer, environment) {
     if (args[0] !== "task")
         return undefined;
@@ -2368,18 +2562,22 @@ async function warmLegacyRoleConfigurationMutation(commandArgs, store, catalogs)
  * no Host is running for most Sessions ever inspected, and the persisted facts
  * the command prints are worth showing regardless of whether a live one answered.
  */
-async function liveRunConfigurationForTaskCommand(args, store, home) {
-    if (args[0] !== "task" || args[1] !== "role" || args[2] !== "session"
-        || args[3] !== "inspect" || args.length !== 6) {
+async function liveHostObservationsForTaskCommand(args, store, home) {
+    if (args[0] !== "task" || args[1] !== "role")
         return undefined;
-    }
-    const taskId = args[4];
-    const roleName = args[5];
-    if (taskId === undefined || roleName === undefined)
+    const inspect = args[2] === "session" && args[3] === "inspect" && args.length === 6;
+    const status = args[2] === "status" && args.length === 5;
+    const list = args[2] === "list" && args.length === 4;
+    if (!inspect && !status && !list)
         return undefined;
-    // A Session must be recorded as active before asking. Probing a socket for a
-    // Role that never ran would report a reach failure as if it were a fact about
-    // that Role's Agent.
+    const taskId = args[inspect ? 4 : 3];
+    const roles = list ? store.listRoles(taskId).map(role => role.name) : [args[inspect ? 5 : 4]];
+    const entries = await Promise.all(roles.map(async (roleName) => [
+        roleName, await readLiveHostObservation(store, home, taskId, roleName)
+    ]));
+    return Object.fromEntries(entries.filter((entry) => entry[1] !== undefined));
+}
+async function readLiveHostObservation(store, home, taskId, roleName) {
     const sessions = store.getTaskRoleSessionSet(taskId, roleName);
     const active = sessions === null
         ? undefined
@@ -2387,8 +2585,7 @@ async function liveRunConfigurationForTaskCommand(args, store, home) {
     if (active === undefined)
         return undefined;
     if (active.status !== "active") {
-        return unknownAgentRunConfiguration(`This Session is ${active.status}, so there is no live Agent to report what it `
-            + "is running under.");
+        return { detail: `This Session is ${active.status}; no live Host reading was requested.` };
     }
     try {
         const snapshot = await inspectAgentHost({
@@ -2398,18 +2595,20 @@ async function liveRunConfigurationForTaskCommand(args, store, home) {
             roleName
         });
         if (snapshot.nativeSessionId !== active.nativeSessionId
-            || snapshot.adapterId !== active.adapterId
-            || snapshot.state === "exited" || snapshot.state === "failed") {
-            return unknownAgentRunConfiguration("The Agent Host has no live connection matching the recorded Session.");
+            || snapshot.adapterId !== active.adapterId) {
+            return { detail: "The Agent Host does not match the recorded Session." };
         }
-        return snapshot.runConfiguration ?? unknownAgentRunConfiguration("The Agent Host is running but has no Provider Session open, so no Agent "
-            + "has reported a configuration yet.");
+        return { snapshot };
     }
     catch (error) {
-        return unknownAgentRunConfiguration("The Agent Host for this Session could not be reached, so its live "
-            + `configuration is unavailable: ${error instanceof Error ? error.message : String(error)}`);
+        return { detail: `The Agent Host could not be reached: ${error instanceof Error ? error.message : String(error)}` };
     }
 }
+function runConfigurationForHostObservation(host) {
+    if (host === undefined)
+        return undefined;
+    return host.snapshot?.runConfiguration ?? unknownAgentRunConfiguration(host.detail ?? `Host=${host.snapshot?.state ?? "unknown"}; no live Agent configuration was reported.`);
+}
 function hasModelOrEffortMutation(args) {
     const operation = (args[0] === "config" && args[1] === "role")
         || (args[0] === "task" && args[1] === "role");
@@ -2547,6 +2746,50 @@ function emit(output, literal = false, data) {
             : { ok: true, data })
         : normalized}\n`);
 }
+function emitControlFailure(message, code, details) {
+    process.exitCode = 2;
+    process.stdout.write(`${jsonOutput
+        ? JSON.stringify({ ok: false, code, message: message.trim(), details })
+        : message.trim()}\n`);
+}
+/**
+ * The human line for a live steer, corrected to the *actual* live acceptance
+ * (decision-3 §7). The store command's `base` line is written optimistically
+ * ("Steering …"); only a proven `steered` keeps it. `steer-unknown` (pending) is
+ * delivery-unknown, and a rejected/unavailable steer did not deliver — in both
+ * cases the Message is retained and the operator must not reissue. There is no
+ * retarget, queue, or interrupt fallback here; this only reports.
+ */
+function steerReceiptOutput(base, target, messageId, receipt) {
+    if (receipt.state === "steered")
+        return base;
+    const detail = receipt.detail === undefined ? "" : ` ${receipt.detail}`;
+    const head = receipt.state === "steer-unknown"
+        ? `Steer message ${messageId} to ${target} is delivery-unknown (${receipt.outcome}): the Host `
+            + "holds it but the Provider has not yet proven acceptance."
+        : `Steer message ${messageId} to ${target} did not deliver (${receipt.outcome}).`;
+    return `${head}${detail} The Message is retained; re-read the Session before acting, and do not `
+        + "reissue the same input under a new requestId or a different action.\n";
+}
+/**
+ * The human line for a live interrupt, corrected to `control.cancellation`
+ * (decision-3 §7). Only a proven stop-request keeps the optimistic `base` line.
+ * `not-active`/`unknown`/unavailable each report that nothing was proven stopped;
+ * no process is ever killed. A then-handoff, if any, was already claimed durably
+ * and is delivered once by the ordinary continuation path after a proven terminal.
+ */
+function interruptReceiptOutput(base, target, receipt) {
+    if (receipt.state === "interrupt-requested")
+        return `${base.trim()}\nNative cancel requested; Turn termination is not yet proven.\n`;
+    const detail = receipt.detail === undefined ? "" : ` ${receipt.detail}`;
+    const reason = receipt.state === "interrupt-not-active"
+        ? "found no active Turn to stop (not-active)"
+        : receipt.state === "interrupt-unknown"
+            ? "could not prove a stop (unknown)"
+            : `did not complete (${receipt.outcome})`;
+    return `Interrupt of ${target} ${reason}.${detail} No process was killed; re-read the Session `
+        + "before retrying.\n";
+}
 function withControllerRefreshWarning(output, refresh, label) {
     if (refresh.status !== "failed")
         return output;