@zq-silk/yui 0.15.7 → 0.15.9

package/dist/cli.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { agentAdapterLabel as adapterLabel } from "./agent/adapterCatalog.js";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
@@ -43,7 +45,8 @@ import { assertTaskRemoteDeliveryIntegrated, createTaskRemoteDeliveryProof } fro
 import { runTaskPublicationVerifyCommand } from "./commands/taskPublicationVerifyCommand.js";
 import { createGitHubCliPublicationVerifier } from "./external/githubPublicationVerifier.js";
 import { createGitLabCliPublicationVerifier } from "./external/gitlabPublicationVerifier.js";
-import { taskActor } from "./commands/taskActor.js";
+import { taskLocalActor, assertTaskDeliveryAuthority } from "./commands/taskActor.js";
+import { saveArtifactCapability, readArtifactCapability, listArtifactsCapability } from "./artifacts/artifactCapability.js";
 import { parseTaskExecutionStartRequest, parseTaskExecutionStopRequest, finalizeStoppedTaskExecution, startTaskExecutionCommand, stopTaskExecutionCommand } from "./commands/taskExecutionCommands.js";
 import { runTaskIntegrationCommand } from "./commands/taskIntegrationCommands.js";
 import { runTaskChangeSetCommand } from "./commands/taskChangeSetCommands.js";
@@ -72,7 +75,8 @@ 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, runAgentHost, sendAgentHostAuthorityControl } from "./runtime/agentHost.js";
+import { AGENT_HOST_CONTROL_PROTOCOL, inspectAgentHost, runAgentHost, sendAgentHostAuthorityControl } from "./runtime/agentHost.js";
+import { unknownAgentRunConfiguration } from "./runtime/agentRunConfiguration.js";
 import { TaskWorkspaceCoordinator, WorkspaceCleanupBlockedError } from "./repository/taskWorkspaceCoordinator.js";
 import { FileTaskWorkspacePreparer } from "./repository/taskWorkspacePreparer.js";
 import { inspectStorageSchema } from "./storage/storageSchema.js";
@@ -85,15 +89,15 @@ import { NodeCommandExecutor } from "./tmux/commandExecutor.js";
 import { TmuxManager } from "./tmux/tmuxManager.js";
 import { WorkItemChangeSetManager } from "./workspace/workItemChangeSetManager.js";
 import { workspaceProjectEntry } from "./worktree/managedWorkspace.js";
-import { parseWebCommandOptions, startYuiWebServer } from "./web/webServer.js";
+import { parseWebCommandOptions } from "./web/webServer.js";
 import { AgentConfigurationCatalogService, validateAgentLaunchConfiguration } from "./executor/agentConfigurationCatalog.js";
 import { resolveAgentProfileView } from "./profile/agentProfileRuntime.js";
-import { TmuxWebTerminalService } from "./web/tmuxWebTerminal.js";
 import { listOperatorSessions, operatorSessionRef } from "./operator/operatorSessionHistory.js";
 import { YUI_VERSION, yuiVersionIdentity } from "./version.js";
 import { SqliteSchemaMigrationError } from "./storage/sqliteSchema.js";
-import { assertRuntimeCoherence, } from "./runtime/runtimeCoherence.js";
-import { requireManagedTaskCaller } from "./runtime/managedCaller.js";
+import { assertRuntimeCoherence } from "./runtime/runtimeCoherence.js";
+import { requireManagedTaskCaller, resolveManagedTaskReader } from "./runtime/managedCaller.js";
+import { operatorOfflineCommand, taskDiagnosticTarget } from "./cli/managedDiagnostics.js";
 import { readSessionBootstrapManifest, refreshManagedSessionCliWrappers } from "./context/sessionBootstrapManifest.js";
 import { createTaskFinalReviewContract, extractTaskFinalReviewRequest } from "./review/taskFinalReviewContract.js";
 import { resolveRecordedTaskFinalReviewContract } from "./review/taskFinalReviewContractResolution.js";
@@ -146,7 +150,7 @@ export async function main() {
         || routedForFence?.kind === "help"
         || routedForFence?.kind === "path-error"
         || routedForFence?.kind === "incomplete";
-    if (managedInvocation || !homeFreeInvocation) {
+    if (!homeFreeInvocation) {
         assertCliHomeReleaseFence({
             home,
             packageRoot: fileURLToPath(new URL("../", import.meta.url)),
@@ -170,7 +174,6 @@ export async function main() {
         process.exitCode = delegated.status ?? 5;
         return;
     }
-    const { contract: taskFinalReviewContract, verifiedStore } = await preflightManagedTaskControlPlane();
     if (args.length === 0) {
         emit(renderCommandHelp((await import("./cli/commandCatalog.js")).ROOT_COMMAND, VERSION));
         return;
@@ -192,6 +195,7 @@ export async function main() {
     }
     if (args[0] === "version")
         throw usageError("Version usage: yui version");
+    const { contract: taskFinalReviewContract, verifiedStore } = await preflightManagedTaskControlPlane();
     if (args[0] === "update") {
         if (jsonOutput)
             throw usageError("Update does not support --json.");
@@ -328,11 +332,10 @@ export async function main() {
                 + `${result.current} already current, ${result.skipped} skipped.`, false, result);
             return;
         }
-        if (args[1] === "agent-host" && args.length === 4) {
+        if (args[1] === "agent-host" && args.length === 3) {
             process.exitCode = await runAgentHost({
                 home,
-                runtimeGenerationId: args[2],
-                ticket: args[3]
+                ticket: args[2]
             });
             return;
         }
@@ -343,7 +346,7 @@ export async function main() {
         if (args[1] === "runtime-hook" && args.length === 2) {
             // Provider lifecycle Hooks are observation channels, never execution
             // gates. A late/stale Hook must not make Claude reject an otherwise
-            // valid Session or Turn; its exact fence is revalidated before any
+            // valid Session or AgentRun; its exact fence is revalidated before any
             // inbox fact is written, so dropping an invalid observation is safe.
             try {
                 await runRuntimeObservationHookCommand(readFileSync(0, "utf8"), process.env);
@@ -549,7 +552,8 @@ export async function main() {
         emit(result.output, false, result.data);
         return;
     }
-    await assertFileTaskControllerStorageCompatible(home);
+    if (!operatorOfflineCommand(args))
+        await assertFileTaskControllerStorageCompatible(home);
     // Reuse the store the exact runtime preflight already opened and read for
     // this same Home. Opening a second store would parse the unchanged large
     // state a second time; the per-instance fingerprint cache still invalidates
@@ -586,46 +590,37 @@ export async function main() {
     });
     const workspaceCoordinator = new TaskWorkspaceCoordinator(store, workspacePreparer, runtime);
     if (resolved[0] === "web") {
+        if (managedInvocation || process.env.YUI_ROLE || process.env.YUI_NATIVE_SESSION_ID) {
+            throw usageError("The Web user ingress must be started from a local user terminal, not a managed Session.");
+        }
+        if (resolved.length === 2 && (resolved[1] === "--status" || resolved[1] === "--stop")) {
+            const status = await callController(home, "web.status", {});
+            if (resolved[1] === "--status")
+                emit(status ? `Yui web control room: ${status.url}\n` : "Web is not running.\n", false, status);
+            else {
+                if (status)
+                    await callController(home, "web.stop", { id: status.id });
+                emit("Web listener stopped; Controller and Agents are unchanged.\n");
+            }
+            return;
+        }
         if (jsonOutput)
-            throw usageError("Web does not support --json.");
+            throw usageError("Web start does not support --json; use --status.");
         const options = parseWebCommandOptions(resolved.slice(1));
-        const terminal = new TmuxWebTerminalService({
-            yuiHome: home,
-            tmuxBin: resolveTmuxBin(store.getConfig().tmuxBin),
-            tmux,
-            prepareGlobalRole: (roleName) => runtime.prepareGlobalRoleEnter(roleName),
-            environment: process.env,
-            onError: (error) => {
-                const message = error instanceof Error ? error.message : String(error);
-                process.stderr.write(`Web terminal cleanup error: ${message}\n`);
-            }
-        });
-        await startYuiWebServer(store, options, {
-            terminal,
-            answerInput: async ({ taskId, inputId, answer }) => {
-                const command = [
-                    "input", "answer", inputId, "--task", taskId,
-                    ...("choiceKey" in answer
-                        ? ["--choice", answer.choiceKey]
-                        : ["--text", answer.text])
-                ];
-                const result = runTaskCommand(command, store, {
-                    runtime,
-                    environment: {},
-                    yuiHome: home
-                });
-                if (result.kind !== "output") {
-                    throw new Error("Input answer returned an invalid control result.");
-                }
-                const data = result.data;
-                if (data?.request === undefined) {
-                    throw new Error("Input answer did not return the updated request.");
-                }
-                return data.request;
-            }
-        });
+        const id = randomUUID();
+        await callController(home, "web.start", { ...options, id });
         const displayHost = options.host === "::1" ? "[::1]" : options.host;
         process.stdout.write(`Yui web control room: http://${displayHost}:${options.port}\n`);
+        await new Promise((resolve) => {
+            const stop = () => {
+                process.off("SIGINT", stop);
+                process.off("SIGTERM", stop);
+                resolve();
+            };
+            process.once("SIGINT", stop);
+            process.once("SIGTERM", stop);
+        });
+        await callController(home, "web.stop", { id });
         return;
     }
     if (resolved[0] === "config") {
@@ -779,6 +774,72 @@ export async function main() {
         return;
     }
     if (resolved[0] === "task") {
+        if (resolved[1] === "artifact") {
+            // File/directory artifacts live in the Task's local Git repository, so
+            // their save/read/list are asynchronous and handled here rather than in
+            // the synchronous runTaskCommand chain. Save commits exactly one path and
+            // returns a self-certifying commit-pinned reference; read pins to a commit
+            // for frozen evidence; list is an ordinary current read.
+            const action = resolved[2];
+            const taskId = resolved[3];
+            const usage = "Usage: yui task artifact list <task> | read <task> <relative-path> [<commit>] | "
+                + "save <task> <relative-path> <content> [--message <text>] [--expected-head <commit>]";
+            if (taskId === undefined || action === undefined || !["list", "read", "save"].includes(action)) {
+                throw usageError(usage);
+            }
+            if (process.env.YUI_SESSION_SCOPE === "task" && process.env.YUI_TASK_ID !== taskId) {
+                throw usageError("Artifact is outside the managed Task scope.");
+            }
+            if (store.getTask(taskId) === null)
+                throw usageError(`Task not found: ${taskId}.`);
+            let data;
+            if (action === "list") {
+                if (resolved.length !== 4)
+                    throw usageError(usage);
+                data = await listArtifactsCapability(home, taskId);
+            }
+            else if (action === "read") {
+                const relativePath = resolved[4];
+                const commit = resolved[5];
+                if (relativePath === undefined || resolved.length > 6)
+                    throw usageError(usage);
+                data = await readArtifactCapability(home, taskId, {
+                    relativePath, ...(commit === undefined ? {} : { commit })
+                });
+            }
+            else {
+                // save: a delivery-authoritative action; a managed Task caller must be the current Leader.
+                taskLocalActor(store, process.env, taskId);
+                const relativePath = resolved[4];
+                const content = resolved[5];
+                if (relativePath === undefined || content === undefined)
+                    throw usageError(usage);
+                const rest = resolved.slice(6);
+                let message;
+                let expectedHead;
+                for (let index = 0; index < rest.length; index += 1) {
+                    const value = rest[index + 1];
+                    if (rest[index] === "--message" && value !== undefined) {
+                        message = value;
+                        index += 1;
+                        continue;
+                    }
+                    if (rest[index] === "--expected-head" && value !== undefined) {
+                        expectedHead = value;
+                        index += 1;
+                        continue;
+                    }
+                    throw usageError(usage);
+                }
+                data = await saveArtifactCapability(home, taskId, {
+                    relativePath, content,
+                    ...(message === undefined ? {} : { message }),
+                    ...(expectedHead === undefined ? {} : { expectedHead })
+                });
+            }
+            emit(JSON.stringify(data, null, 2), false, data);
+            return;
+        }
         if (resolved[1] === "execution") {
             if (resolved[2] === "stop") {
                 const request = parseTaskExecutionStopRequest(resolved.slice(3));
@@ -803,7 +864,7 @@ export async function main() {
                 if (task === null)
                     throw usageError(`Task not found: ${taskId}.`);
                 // Reject managed Task callers before inspecting or starting runtime resources.
-                if (taskActor(process.env, taskId) === "leader") {
+                if (taskLocalActor(store, process.env, taskId) === "leader") {
                     throw usageError("Task execution stop/start requires the global Operator or a human user.");
                 }
                 if (task.executionGate.state === "stopped") {
@@ -845,7 +906,7 @@ export async function main() {
                 },
                 candidateForTask: async (taskId) => {
                     const status = store.getTask(taskId)?.status;
-                    return status === "active" || status === "retired"
+                    return status === "active" || status === "cancelled"
                         ? snapshotActualTaskReviewCandidate(taskId, store, workspacePreparer)
                         : null;
                 },
@@ -911,7 +972,7 @@ export async function main() {
                 throw usageError("Task work capture usage: yui task work capture <task>/<work>.");
             }
             const reference = cliWorkItemReference(workItemId, process.env);
-            taskActor(process.env, reference.taskId);
+            assertTaskDeliveryAuthority(store, process.env, reference.taskId);
             const changeSets = await new WorkItemChangeSetManager(store).capture(reference.taskId, reference.localId, taskFinalReviewContract === undefined
                 ? {}
                 : { taskFinalReviewContract });
@@ -932,7 +993,7 @@ export async function main() {
             }
             const reference = cliWorkItemReference(workItemId, process.env);
             const qualified = `${reference.taskId}/${reference.localId}`;
-            taskActor(process.env, reference.taskId);
+            assertTaskDeliveryAuthority(store, process.env, reference.taskId);
             if (disposition === "--runtime-only") {
                 let runtimeCleanup;
                 try {
@@ -1024,7 +1085,7 @@ export async function main() {
                     .flatMap(({ owner }) => owner.type === "work-item" ? [owner.workItemId] : []);
                 for (const workItemId of workItemIds) {
                     const item = store.getWorkItem(task.id, workItemId);
-                    if (item?.status !== "completed" || disposition !== "integrated")
+                    if (item?.status !== "accepted" || disposition !== "integrated")
                         continue;
                     try {
                         await new WorkItemChangeSetManager(store).assertIntegrated(task.id, item.id);
@@ -1071,15 +1132,15 @@ export async function main() {
             if (item !== null && task !== null) {
                 // Authority and pure Lane-shape checks precede every physical or
                 // durable workspace preparation performed for dispatch.
-                taskActor(process.env, task.id);
+                assertTaskDeliveryAuthority(store, process.env, task.id);
                 if (item.assignee !== undefined) {
                     workItemDispatchLanePlan(resolved, store, item);
                 }
             }
             // A rejected Candidate starts a new execution iteration. Release every
             // terminal Lane Role runtime before preparing the new Lane workspaces;
-            // durable Turns, Groups, Candidates, and workspace owners remain intact.
-            if (item?.status === "failed"
+            // durable AgentRuns, Groups, Candidates, and workspace owners remain intact.
+            if (item?.status === "open"
                 && currentWorkItemExecutionGroup(item)?.lanes.every(({ disposition }) => disposition !== "open")) {
                 await workspaceCoordinator.cleanupWorkItemRuntime(item.taskId, item.id);
             }
@@ -1118,7 +1179,7 @@ export async function main() {
                 try {
                     const reference = cliWorkItemReference(workItemId, process.env);
                     workItemIntegrationProof = await new WorkItemChangeSetManager(store)
-                        .assertIntegrated(reference.taskId, reference.localId) ?? undefined;
+                        .assertIntegrated(reference.taskId, reference.localId, optionValue(resolved, "--candidate")) ?? undefined;
                 }
                 catch (error) {
                     throw usageError(error instanceof Error ? error.message : String(error));
@@ -1204,6 +1265,11 @@ export async function main() {
                 ? 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
+            // 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);
             // 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
@@ -1213,7 +1279,8 @@ export async function main() {
                 const taskId = resolved[2];
                 const task = taskId === undefined ? null : store.getTask(taskId);
                 if (task !== null && task.status === "draft") {
-                    taskWorkspaceActivation = await workspacePreparer.activateTaskWorkspace(task.id);
+                    taskLocalActor(store, process.env, task.id);
+                    taskWorkspaceActivation = await workspacePreparer.activateTaskWorkspace(task.id, process.env);
                 }
             }
             const result = runTaskCommand(resolved.slice(1), store, {
@@ -1242,6 +1309,9 @@ export async function main() {
                 ...(deltaRecheckPreflight === undefined
                     ? {}
                     : { deltaRecheckPreflight }),
+                ...(liveRunConfiguration === undefined
+                    ? {}
+                    : { liveRunConfiguration }),
                 ...(taskRetirementProof === undefined ? {} : { taskRetirementProof }),
                 ...(validateAgentConfiguration === undefined
                     ? {}
@@ -1263,13 +1333,13 @@ export async function main() {
                 let reviewData;
                 const resumesReviewDispatch = (resolved[1] === "review" && resolved[2] === "request")
                     || (resolved[1] === "work" && resolved[2] === "review")
-                    || (resolved[1] === "turn" && resolved[2] === "retry");
+                    || (resolved[1] === "run" && resolved[2] === "retry");
                 const reviewDispatchNeeded = requestedRound?.status === "pending"
                     || (requestedRound?.status === "running"
                         && resumesReviewDispatch
                         && persistedRequestedRound?.executionGroup?.lanes.some((lane) => (lane.disposition === "open"
-                            && (lane.currentTurnId === undefined
-                                || store.getTurn(requestedRound.taskId, lane.currentTurnId)?.status === "failed"))) === true);
+                            && (lane.currentRunId === undefined
+                                || store.getRun(requestedRound.taskId, lane.currentRunId)?.status === "failed"))) === true);
                 if (reviewDispatchNeeded) {
                     try {
                         const workspace = requestedRound.status === "running"
@@ -1319,7 +1389,7 @@ export async function main() {
                                     kind: "started",
                                     reviewerRoleName: requestedRound.reviewerRoleName,
                                     reviewRoundId: requestedRound.id,
-                                    turnId: run.id
+                                    runId: run.id
                                 },
                             reviewRound: store.getReviewRound(requestedRound.taskId, requestedRound.id),
                             ...(run === null ? {} : { reviewRun: run }),
@@ -1372,7 +1442,6 @@ export async function main() {
                         agentId: result.agentId,
                         adapterId: result.adapterId,
                         nativeSessionId: result.nativeSessionId,
-                        ...(result.runtimeGenerationId === undefined ? {} : { runtimeGenerationId: result.runtimeGenerationId }),
                         sessionUpdatedAt: result.sessionUpdatedAt
                     });
                 }
@@ -1446,7 +1515,7 @@ export async function main() {
             }
             finally {
                 const currentTask = store.getTask(result.taskId);
-                // Completing or retiring the Task from inside the takeover Turn owns
+                // Completing or retiring the Task from inside the takeover AgentRun owns
                 // Provider shutdown and clears the live binding. Do not turn that
                 // successful terminal transition into a failing best-effort release.
                 if (currentTask?.status === "active") {
@@ -1530,21 +1599,38 @@ async function preflightManagedTaskControlPlane() {
         && ["agent-host", "session-notify", "runtime-hook"].includes(args[1] ?? "");
     const home = resolveYuiHome(process.env);
     const manifest = assertManagedSessionManifest(home, "task");
+    const diagnosticTarget = taskDiagnosticTarget(args);
+    const diagnostic = diagnosticTarget !== undefined
+        && diagnosticTarget === process.env.YUI_TASK_ID;
+    if (diagnosticTarget !== undefined && !diagnostic) {
+        throw usageError("Diagnostics must remain within this Session's Task.");
+    }
     // One gate for every managed command: the current CLI, Home, and Controller
     // must agree. Internal callbacks must still be able to append their immutable
     // fact while the Controller is offline.
-    await assertRuntimeCoherence({ actualHome: home }, { checkController: !internalCallback });
+    await assertRuntimeCoherence({ actualHome: home }, { checkController: !internalCallback && !diagnostic });
     const verifiedStore = openCurrentTaskStore(home);
     // One authority for "may this process act as this Task Role?". Yui's own
     // internal callbacks run inside the Host process Yui itself launched; an Agent
     // command proves it is the Role's current runtime with its per-Session caller
     // key. Nothing here
-    // gates on the current Turn: which Turn is active is durable state that the
+    // gates on the current AgentRun: which AgentRun is active is durable state that the
     // command needing it reads, never a fact frozen into a process environment.
     const runtime = internalCallback
         ? undefined
-        : requireManagedTaskCaller(verifiedStore, process.env);
+        : diagnostic
+            ? resolveManagedTaskReader(verifiedStore, process.env)
+            : requireManagedTaskCaller(verifiedStore, process.env);
+    if (diagnostic && runtime?.roleName !== "leader"
+        && !(args[1] === "show"
+            || (args[1] === "role" && args[2] === "session" && args[3] === "inspect"
+                && args[5] === runtime?.roleName))) {
+        // Non-Leaders keep their Assignment-scoped read authorization.
+        requireManagedTaskCaller(verifiedStore, process.env);
+    }
     const request = taskFinalReviewInvocation.request;
+    if (request !== undefined && diagnostic)
+        requireManagedTaskCaller(verifiedStore, process.env);
     if (request === undefined) {
         return { contract: undefined, verifiedStore };
     }
@@ -1579,7 +1665,14 @@ async function preflightManagedGlobalControlPlane() {
         || manifest.roleKind !== expectedRoleKind) {
         throw new Error("Managed global invocation does not match its Session Manifest.");
     }
-    await assertRuntimeCoherence({ actualHome: home });
+    if (expectedRoleKind === "operator" && ["doctor", "upgrade", "update"].includes(args[0] ?? "")) {
+        // These commands inspect/adopt the storage contract themselves. Requiring
+        // current storage before reaching upgrade would make recovery impossible.
+        return { contract: undefined, verifiedStore: undefined };
+    }
+    await assertRuntimeCoherence({ actualHome: home }, {
+        checkController: !(expectedRoleKind === "operator" && operatorOfflineCommand(args))
+    });
     return { contract: undefined, verifiedStore: openCurrentTaskStore(home) };
 }
 /**
@@ -1643,7 +1736,7 @@ function cliTaskRecordReference(value, kind, environment) {
     try {
         return resolveTaskRecordReference(value, {
             kind,
-            label: kind === "turn" ? "Turn reference" : "ReviewRound reference",
+            label: kind === "run" ? "AgentRun reference" : "ReviewRound reference",
             ...(environment.YUI_TASK_ID === undefined
                 ? {}
                 : { contextTaskId: environment.YUI_TASK_ID })
@@ -1660,12 +1753,12 @@ function assertWorkItemExecutionDependenciesForCommand(args, store, environment)
         const reference = cliWorkItemReference(args[3], environment);
         item = store.getWorkItem(reference.taskId, reference.localId) ?? undefined;
     }
-    else if (args[0] === "task" && args[1] === "turn" && args[2] === "retry"
+    else if (args[0] === "task" && args[1] === "run" && args[2] === "retry"
         && args[3] !== undefined) {
-        const reference = cliTaskRecordReference(args[3], "turn", environment);
-        const turn = store.getTurn(reference.taskId, reference.localId);
-        item = turn?.purpose === "execution" && turn.workItemId !== undefined
-            ? store.getWorkItem(turn.taskId, turn.workItemId) ?? undefined
+        const reference = cliTaskRecordReference(args[3], "run", environment);
+        const run = store.getRun(reference.taskId, reference.localId);
+        item = run?.purpose === "execution" && run.workItemId !== undefined
+            ? store.getWorkItem(run.taskId, run.workItemId) ?? undefined
             : undefined;
     }
     if (item === undefined)
@@ -1720,7 +1813,7 @@ async function prepareExecutionLaneWorkspacesForCommand(args, store, preparer, e
         if (store.getRole(item.taskId, roleName) === null) {
             throw usageError(`Task Role not found: ${item.taskId}/${roleName}.`);
         }
-        if (store.getActiveTurn(item.taskId, roleName) !== null) {
+        if (store.getActiveRun(item.taskId, roleName) !== null) {
             throw usageError(`${item.taskId}/${roleName} already has an active turn.`);
         }
     }
@@ -1759,7 +1852,7 @@ function workItemDispatchLanePlan(args, store, item) {
     const roles = args.flatMap((value, index) => (value === "--lane-role" && args[index + 1] !== undefined
         ? [args[index + 1]]
         : []));
-    const groupId = `execution-group-${store.peekNextTurnId(item.taskId)}`;
+    const groupId = `execution-group-${store.peekNextRunId(item.taskId)}`;
     return {
         groupId,
         ...planReplicatedWorkItemLanes(item.assignee, roles, groupId)
@@ -1855,11 +1948,11 @@ async function actualTaskReviewCandidateForTaskCommand(args, store, preparer, en
             taskId = reference.taskId;
         }
     }
-    else if (args[1] === "turn"
+    else if (args[1] === "run"
         && (args[2] === "retry" || args[2] === "settle")
         && args[3] !== undefined) {
-        const reference = cliTaskRecordReference(args[3], "turn", environment);
-        const run = store.getTurn(reference.taskId, reference.localId);
+        const reference = cliTaskRecordReference(args[3], "run", environment);
+        const run = store.getRun(reference.taskId, reference.localId);
         const round = run?.reviewRoundId === undefined
             ? null
             : store.getReviewRound(reference.taskId, run.reviewRoundId);
@@ -1875,7 +1968,6 @@ async function actualTaskReviewCandidateForTaskCommand(args, store, preparer, en
         taskId = store.getTask(args[2])?.id;
     }
     else if ((args[1] === "show"
-        || args[1] === "context"
         || args[1] === "next-action"
         || args[1] === "remote-delivery")
         && args[2] !== undefined) {
@@ -1883,10 +1975,10 @@ async function actualTaskReviewCandidateForTaskCommand(args, store, preparer, en
         decisionSupportRead = true;
     }
     const status = taskId === undefined ? undefined : store.getTask(taskId)?.status;
-    if (taskId === undefined || (status !== "active" && status !== "retired"))
+    if (taskId === undefined || (status !== "active" && status !== "cancelled"))
         return undefined;
     try {
-        return await snapshotActualTaskReviewCandidate(taskId, store, preparer);
+        return await snapshotActualTaskReviewCandidate(taskId, store, preparer, !decisionSupportRead);
     }
     catch (error) {
         if (decisionSupportRead && error instanceof CliError)
@@ -1894,16 +1986,18 @@ async function actualTaskReviewCandidateForTaskCommand(args, store, preparer, en
         throw error;
     }
 }
-async function snapshotActualTaskReviewCandidate(taskId, store, preparer) {
+async function snapshotActualTaskReviewCandidate(taskId, store, preparer, prepareWorkspace = true) {
     const task = store.getTask(taskId);
     if (task === null)
         throw usageError(`Task not found: ${taskId}.`);
     if (task.projectBindings.length === 0) {
         throw usageError(`Final Task Review requires a Project-backed Task: ${task.id}.`);
     }
-    // Reconcile the durable currentCommit facts from the authoritative Task
-    // clones before freezing a completion/review candidate.
-    await preparer.prepareTaskWorkspace(task.id);
+    // Mutation preflights reconcile before freezing a candidate. A decision-
+    // support read only observes existing heads; it must not migrate Sessions,
+    // create worktrees or acquire workspace ownership as a side effect.
+    if (prepareWorkspace)
+        await preparer.prepareTaskWorkspace(task.id);
     const workspace = store.getTaskWorkspace(task.id);
     if (workspace === null
         || workspace.owner.type !== "task"
@@ -2075,13 +2169,6 @@ async function executeOperatorSessionControl(control, home, store, runtime, tmux
     await runtime.prepareGlobalRoleEnter(role.name);
     tmux.attachRole("operator", role.name, "auto");
 }
-function adapterLabel(adapterId) {
-    return adapterId === "codex"
-        ? "Codex"
-        : adapterId === "claude"
-            ? "Claude"
-            : adapterId;
-}
 function renderControllerResult(method, value) {
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
         return JSON.stringify(value);
@@ -2264,6 +2351,65 @@ async function warmLegacyRoleConfigurationMutation(commandArgs, store, catalogs)
         cwd: store.getConfig().defaultWorkspace ?? process.cwd()
     });
 }
+/**
+ * Ask the live Agent Host what the Session is running under, for a Session
+ * inspect.
+ *
+ * Only for `task role session inspect`. Every other command reads persisted
+ * state and must keep doing so: a query that reached into a running Session
+ * would make reading a Task's records depend on whether an Agent happened to be
+ * up.
+ *
+ * The request is the Host's existing `status` control, which reads state the
+ * Host already holds. It creates no Session, sends no prompt and changes nothing
+ * — which is what lets a read-only inspect use it at all.
+ *
+ * Every failure resolves to `unknown` with the reason rather than propagating:
+ * 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) {
+        return undefined;
+    }
+    const taskId = args[4];
+    const roleName = args[5];
+    if (taskId === undefined || roleName === undefined)
+        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 sessions = store.getTaskRoleSessionSet(taskId, roleName);
+    const active = sessions === null
+        ? undefined
+        : sessions.sessions[sessions.activeAgentId];
+    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.");
+    }
+    try {
+        const snapshot = await inspectAgentHost({
+            home,
+            scope: "task",
+            taskId,
+            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.");
+        }
+        return snapshot.runConfiguration ?? unknownAgentRunConfiguration("The Agent Host is running but has no Provider Session open, so no Agent "
+            + "has reported a configuration yet.");
+    }
+    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)}`);
+    }
+}
 function hasModelOrEffortMutation(args) {
     const operation = (args[0] === "config" && args[1] === "role")
         || (args[0] === "task" && args[1] === "role");
@@ -2336,7 +2482,7 @@ function selectionCall(store, catalogs, method, params) {
                 : store.listInputRequests(taskId);
             return params.all === true ? requests : requests.filter((request) => request.status === "open");
         }
-        case "task.turn.list": return callOptional(reader, "listTurns", [params.taskId]);
+        case "task.turn.list": return callOptional(reader, "listRuns", [params.taskId]);
         case "task.decision.list": return callOptional(reader, "listDecisions", [params.taskId]);
         case "task.milestone.list": return presentSelectionTimes(callOptional(reader, "listMilestones", [params.taskId]), store);
         case "task.event.list": return presentSelectionTimes(callOptional(reader, "listEvents", [params.taskId]), store);
@@ -2434,6 +2580,10 @@ export function cliIdentity(env) {
 }
 function normalizeAliases(input) {
     const normalized = [...input];
+    // Existing immutable Session Manifests (through 0.15.8) name this entry.
+    // Remove once those Sessions are retired; both names share one handler.
+    if (normalized[0] === "task" && normalized[1] === "turn")
+        normalized[1] = "run";
     if (normalized.length === 1 && (normalized[0] === "-v" || normalized[0] === "--version")) {
         return ["version"];
     }