@zq-silk/yui 0.8.6 → 0.8.7

package/README.md

@@ -633,6 +633,21 @@ and `task work retire <task>/<work> --summary "..."` to retire obsolete work,
 optionally naming a replacement. WorkItem and Integration
 worktrees and check logs remain available as evidence until explicit cleanup.
 
+Incorrect historical directives and execution attempts can be removed from
+operational projections without deleting their audit records:
+
+```sh
+yui task message retire <task>/<message> --reason "Superseded instruction"
+yui task run retire <task>/<agent-run> --reason "Invalid launch record"
+```
+
+These commands append a retirement fact. Lists and audit views retain the
+original Message, WorkItem, or AgentRun and mark it retired; managed Run context,
+actionability, recovery, review evidence, and scheduling ignore it. Retiring
+an active AgentRun first terminalizes that exact Run, and retirement is
+idempotent. Only the user or global Operator may retire Messages or AgentRuns;
+WorkItems may also be retired by their Task Leader.
+
 For long-running Tasks, the Leader keeps Yui—not a native transcript—as the
 recovery authority. The Task Brief owns the overall technical approach,
 including how coordinated Project changes fit together. WorkItems own the
@@ -766,9 +781,11 @@ running AgentRun and its native Session continue under their immutable
 effective snapshot even if the Role is edited or switched. Resume is allowed
 only when the complete effective snapshot and workspace remain compatible;
 otherwise Yui starts a new Session after the old process has stopped and keeps
-the terminal Session's immutable effective snapshot in history. Until that
-process terminates, exact control-plane wakes continue through its actual
-snapshot instead of applying desired drift as a hot change.
+the terminal Session's immutable effective snapshot in history. Managed
+Sessions invoke the ordinary `yui` command; their Manifest and durable
+Role/Run fences authenticate scope while protocol and storage compatibility
+allow a CLI package or Controller upgrade in place. Exact internal callbacks
+remain fenced to their originating runtime snapshot.
 
 Use `yui config role unbind <global-role> <agent-id>` or `yui task role unbind <task-id> <role> <agent-id>` to retire a dormant binding. The active binding and any non-stopped native session are rejected; a stopped session record is removed atomically with the binding.
 

package/dist/cli/commandCatalog.js

@@ -363,7 +363,7 @@ const taskChildren = [
     {
         name: "message",
         summary: "Manage durable Task messages.",
-        sections: [{ id: "manage", title: "Commands", entries: ["send", "list"] }],
+        sections: [{ id: "manage", title: "Commands", entries: ["send", "list", "retire"] }],
         children: [
             {
                 name: "send",
@@ -381,6 +381,12 @@ const taskChildren = [
                 summary: "List Task messages.",
                 usage: "yui task message list <id> [--after <timestamp>] [--limit <n>]",
                 options: ["--after", "--limit"]
+            },
+            {
+                name: "retire",
+                summary: "Retire an incorrect historical Task Message without deleting its audit record.",
+                usage: "yui task message retire <task>/<message> --reason <text>",
+                options: ["--reason"]
             }
         ]
     },
@@ -689,7 +695,7 @@ const taskChildren = [
     {
         name: "run",
         summary: "Inspect and control Task Role Agent Runs.",
-        sections: [{ id: "manage", title: "Commands", entries: ["list", "show", "retry", "settle", "recover", "yield", "context", "checkpoint"] }],
+        sections: [{ id: "manage", title: "Commands", entries: ["list", "show", "retry", "settle", "recover", "yield", "context", "checkpoint", "retire"] }],
         children: [
             { name: "list", summary: "List Runs for a work item.", usage: "yui task run list <task>/<work>" },
             {
@@ -749,6 +755,12 @@ const taskChildren = [
                 options: ["--note", "--note-file"],
                 fileOptions: ["--note-file"],
                 hidden: true
+            },
+            {
+                name: "retire",
+                summary: "Retire an incorrect historical Agent Run without deleting its audit record.",
+                usage: "yui task run retire <task>/<run> --reason <text>",
+                options: ["--reason"]
             }
         ]
     },
@@ -1405,7 +1417,7 @@ export const ROOT_COMMAND = buildNode({
             sections: [{
                     id: "callbacks",
                     title: "Callbacks",
-                    entries: ["session-notify", "runtime-hook", "agent-host"]
+                    entries: ["session-notify", "runtime-hook", "agent-host", "session-cli-refresh"]
                 }],
             children: [
                 {
@@ -1422,6 +1434,11 @@ export const ROOT_COMMAND = buildNode({
                     name: "runtime-hook",
                     summary: "Record a managed Agent Driver observation from stdin.",
                     usage: "yui internal runtime-hook"
+                },
+                {
+                    name: "session-cli-refresh",
+                    summary: "Refresh legacy managed Session CLI wrappers after an update.",
+                    usage: "yui internal session-cli-refresh"
                 }
             ]
         }

package/dist/cli/updatePorts.js

@@ -199,6 +199,12 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
                     + `but the staged/verified artifact was ${staged.version}. Refusing to trust a `
                     + "different build than the one that passed preflight.");
             }
+            // Existing managed Sessions may have been created by a release that
+            // embedded an exact CLI path/version in its wrapper. Convert those
+            // authenticated, Manifest-referenced wrappers before the replacement
+            // Controller starts so the update cannot strand a live Session.
+            const sessionCliRefresh = run(activeBinary, ["--json", "internal", "session-cli-refresh"], { cwd: process.cwd(), env: { ...environment, YUI_HOME: home }, shell: false });
+            assertSpawnOk(sessionCliRefresh, "refresh managed Session CLI wrappers");
             // Retain the exact path used by both doctor and version verification. The
             // replacement start must not resolve UPDATE_CLI_PATH or npm again.
             verifiedActivatedBinary = activeBinary;

package/dist/cli.js

@@ -81,8 +81,8 @@ import { AgentConfigurationCatalogService } from "./executor/agentConfigurationC
 import { TmuxWebTerminalService } from "./web/tmuxWebTerminal.js";
 import { listOperatorSessions, operatorSessionRef } from "./operator/operatorSessionHistory.js";
 import { YUI_VERSION, yuiVersionIdentity } from "./version.js";
-import { YUI_CONTROL_PLANE_DESCRIPTOR, YUI_TASK_RUNTIME_DESCRIPTOR, assertExactControlPlanePreflight, assertExactTaskRuntimeEnvironment, assertExactTaskRuntimeState, exactControlPlaneDigest, extractExactControlArgument, parseExactControlPlaneDescriptor } from "./runtime/exactControlPlane.js";
-import { readSessionBootstrapManifest } from "./context/sessionBootstrapManifest.js";
+import { YUI_CONTROL_PLANE_DESCRIPTOR, YUI_TASK_RUNTIME_DESCRIPTOR, assertCompatibleControlPlanePreflight, assertExactControlPlanePreflight, assertExactTaskRuntimeEnvironment, assertExactTaskRuntimeState, exactControlPlaneDigest, extractExactControlArgument, createExactControlPlaneDescriptor, parseExactControlPlaneDescriptor } from "./runtime/exactControlPlane.js";
+import { readSessionBootstrapManifest, refreshManagedSessionCliWrappers } from "./context/sessionBootstrapManifest.js";
 import { builtinAgentDriverRegistry } from "./runtime/builtinAgentDrivers.js";
 import { createTaskFinalReviewContract, extractTaskFinalReviewRequest } from "./review/taskFinalReviewContract.js";
 import { prepareTaskFinalReviewContractRebindProof, resolveRecordedTaskFinalReviewContract } from "./review/taskFinalReviewContractRebind.js";
@@ -264,6 +264,16 @@ export async function main() {
         return;
     }
     if (args[0] === "internal") {
+        if (args[1] === "session-cli-refresh" && args.length === 2) {
+            if (process.env.YUI_SESSION_SCOPE === "task"
+                || (process.env.YUI_SESSION_SCOPE === "global" && process.env.YUI_ROLE !== "operator")) {
+                throw usageError("Managed Session CLI refresh may be run only by the user or global Operator.");
+            }
+            const result = refreshManagedSessionCliWrappers(home);
+            emit(`Refreshed ${result.refreshed} legacy Session CLI wrapper(s); `
+                + `${result.current} already current, ${result.skipped} skipped.`, false, result);
+            return;
+        }
         if (args[1] === "agent-host" && args.length === 4) {
             process.exitCode = await runAgentHost({
                 home,
@@ -1364,7 +1374,8 @@ async function preflightManagedTaskControlPlane() {
         throw new Error("Exact control-plane invocation requires both frozen descriptors in a managed Task runtime.");
     }
     if (!exactRuntime) {
-        if (exactControlInvocation.digest !== undefined) {
+        if (exactControlInvocation.digest !== undefined
+            || process.env.YUI_SESSION_SCOPE === "global") {
             return await preflightManagedGlobalControlPlane(exactControlInvocation.digest);
         }
         if (taskFinalReviewInvocation.request !== undefined) {
@@ -1379,24 +1390,42 @@ async function preflightManagedTaskControlPlane() {
         throw new Error("Exact control-plane invocation is required for this managed Task runtime.");
     }
     const control = parseExactControlPlaneDescriptor(serializedControl);
-    const internalCallback = args[0] === "internal";
-    if (!internalCallback && exactControlInvocation.digest === undefined) {
-        throw new Error("Exact control-plane invocation is required; bare `yui` and PATH launchers are not valid in a managed Task runtime.");
-    }
-    const digest = exactControlInvocation.digest ?? exactControlPlaneDigest(control);
-    await assertExactControlPlanePreflight({
-        serializedDescriptor: serializedControl,
-        digest,
-        actualExecutable: process.execPath,
-        actualCliEntry: fileURLToPath(import.meta.url),
-        actualHome: resolveYuiHome(process.env)
-    }, {
-        // Provider callbacks must remain able to append their immutable inbox fact
-        // while the Controller is offline. They still validate executable, CLI,
-        // Home, build, schema, and the exact Task runtime envelope first.
-        checkController: !internalCallback
-    });
-    const runtime = assertExactTaskRuntimeEnvironment(serializedRuntime, process.env, digest, control.yuiHome);
+    const internalCallback = args[0] === "internal"
+        && ["agent-host", "session-notify", "runtime-hook"].includes(args[1] ?? "");
+    const home = resolveYuiHome(process.env);
+    assertManagedSessionManifest(home, "task");
+    if (resolve(control.yuiHome) !== resolve(home)) {
+        throw new Error("Managed Task control-plane descriptor belongs to another YUI_HOME.");
+    }
+    const frozenDigest = exactControlPlaneDigest(control);
+    const exactCommand = internalCallback || exactControlInvocation.digest !== undefined;
+    let commandControl;
+    let digest;
+    if (exactCommand) {
+        digest = exactControlInvocation.digest ?? frozenDigest;
+        await assertExactControlPlanePreflight({
+            serializedDescriptor: serializedControl,
+            digest,
+            actualExecutable: process.execPath,
+            actualCliEntry: fileURLToPath(import.meta.url),
+            actualHome: home
+        }, {
+            // Provider callbacks must remain able to append their immutable inbox fact
+            // while the Controller is offline. They still validate executable, CLI,
+            // Home, schema, and the exact Task runtime envelope first.
+            checkController: !internalCallback
+        });
+        commandControl = control;
+    }
+    else {
+        await assertCompatibleControlPlanePreflight({ actualHome: home });
+        // Package/build identity is deliberately not part of ordinary Session
+        // continuity. Keep contracts on the Session's frozen digest while the
+        // current CLI is proven protocol/storage compatible.
+        commandControl = control;
+        digest = frozenDigest;
+    }
+    const runtime = assertExactTaskRuntimeEnvironment(serializedRuntime, process.env, frozenDigest, control.yuiHome);
     const runtimeDriverCallback = args[0] === "internal"
         && args[1] === "runtime-hook"
         && process.env.YUI_DRIVER_ID !== undefined
@@ -1417,7 +1446,7 @@ async function preflightManagedTaskControlPlane() {
     if (request === undefined) {
         return {
             contract: undefined,
-            controlPlane: { digest, descriptor: control },
+            controlPlane: { digest, descriptor: commandControl },
             verifiedStore
         };
     }
@@ -1427,13 +1456,22 @@ async function preflightManagedTaskControlPlane() {
     if (request.taskId !== runtime.taskId) {
         throw new Error(`Task final-review contract Task id mismatch: expected ${runtime.taskId}, found ${request.taskId}.`);
     }
+    const recordedContract = resolveRecordedTaskFinalReviewContract(runtime.taskId, verifiedStore.listWorkItems(runtime.taskId), verifiedStore.listReviewRounds(runtime.taskId), verifiedStore.listEvents(runtime.taskId))?.effective;
+    if (recordedContract !== undefined
+        && recordedContract.reviewerRoleName !== request.reviewerRoleName) {
+        throw new Error(`Task final-review Reviewer mismatch: expected ${recordedContract.reviewerRoleName}, `
+            + `found ${request.reviewerRoleName}.`);
+    }
     return {
         contract: createTaskFinalReviewContract({
             taskId: runtime.taskId,
             reviewerRoleName: request.reviewerRoleName,
-            controlPlaneDigest: digest
+            // Once Task evidence establishes a contract, a compatible Session or
+            // CLI replacement presents that same capability. Package/build identity
+            // must not force a release rebind or invalidate delivery evidence.
+            controlPlaneDigest: recordedContract?.controlPlaneDigest ?? digest
         }),
-        controlPlane: { digest, descriptor: control },
+        controlPlane: { digest, descriptor: commandControl },
         verifiedStore
     };
 }
@@ -1445,38 +1483,77 @@ async function preflightManagedGlobalControlPlane(digest) {
         throw new Error("Task final-review contract establishment requires a verified exact Task control-plane invocation.");
     }
     const manifestPath = process.env.YUI_SESSION_MANIFEST;
-    const sessionCliPath = process.env.YUI_SESSION_CLI;
-    if (manifestPath === undefined || sessionCliPath === undefined) {
-        throw new Error("Exact global control-plane invocation requires its Session Manifest and CLI.");
+    if (manifestPath === undefined) {
+        throw new Error("Managed global control-plane invocation requires its Session Manifest.");
     }
-    const manifest = readSessionBootstrapManifest(manifestPath);
+    const home = resolveYuiHome(process.env);
+    const manifest = assertManagedSessionManifest(home, "global");
     const expectedRoleKind = process.env.YUI_ROLE === "operator" ? "operator" : "global";
     if (manifest.owner.scope !== "global"
-        || manifest.roleKind !== expectedRoleKind
-        || resolve(manifest.controlPlane.sessionCliPath) !== resolve(sessionCliPath)
-        || manifest.controlPlane.digest !== digest) {
-        throw new Error("Exact global control-plane invocation does not match its Session Manifest.");
+        || manifest.roleKind !== expectedRoleKind) {
+        throw new Error("Managed global invocation does not match its Session Manifest.");
     }
     const serializedDescriptor = readFileSync(manifest.controlPlane.descriptorPath, "utf8");
     const descriptor = parseExactControlPlaneDescriptor(serializedDescriptor);
-    if (exactControlPlaneDigest(descriptor) !== digest
-        || resolve(manifest.controlPlane.descriptorPath) !== resolve(join(descriptor.yuiHome, "runtime", "control-plane", `${digest}.json`))
+    if (resolve(descriptor.yuiHome) !== resolve(home)) {
+        throw new Error("Managed global control-plane descriptor belongs to another YUI_HOME.");
+    }
+    const frozenDigest = exactControlPlaneDigest(descriptor);
+    if (frozenDigest !== manifest.controlPlane.digest
+        || resolve(manifest.controlPlane.descriptorPath) !== resolve(join(descriptor.yuiHome, "runtime", "control-plane", `${frozenDigest}.json`))
         || resolve(manifestPath) !== resolve(join(descriptor.yuiHome, "runtime", "session-manifests", `${manifest.digest}.json`))) {
         throw new Error("Exact global Session Manifest does not match its control-plane descriptor.");
     }
-    await assertExactControlPlanePreflight({
-        serializedDescriptor,
-        digest,
-        actualExecutable: process.execPath,
-        actualCliEntry: fileURLToPath(import.meta.url),
-        actualHome: resolveYuiHome(process.env)
-    });
+    let commandControl;
+    let commandDigest;
+    if (digest !== undefined) {
+        await assertExactControlPlanePreflight({
+            serializedDescriptor,
+            digest,
+            actualExecutable: process.execPath,
+            actualCliEntry: fileURLToPath(import.meta.url),
+            actualHome: home
+        });
+        commandControl = descriptor;
+        commandDigest = digest;
+    }
+    else {
+        await assertCompatibleControlPlanePreflight({ actualHome: home });
+        commandControl = currentInvocationControlPlane(home);
+        commandDigest = exactControlPlaneDigest(commandControl);
+    }
     return {
         contract: undefined,
-        controlPlane: { digest, descriptor },
-        verifiedStore: openCompatibleFileTaskStore(descriptor.yuiHome)
+        controlPlane: { digest: commandDigest, descriptor: commandControl },
+        verifiedStore: openCompatibleFileTaskStore(home)
     };
 }
+function currentInvocationControlPlane(home) {
+    return createExactControlPlaneDescriptor({
+        executable: process.execPath,
+        cliEntry: fileURLToPath(import.meta.url),
+        yuiHome: home
+    });
+}
+function assertManagedSessionManifest(home, scope) {
+    const manifestPath = process.env.YUI_SESSION_MANIFEST;
+    if (manifestPath === undefined) {
+        throw new Error("Managed control-plane invocation requires its Session Manifest.");
+    }
+    const manifest = readSessionBootstrapManifest(manifestPath);
+    if (manifest.owner.scope !== scope) {
+        throw new Error("Managed invocation scope does not match its Session Manifest.");
+    }
+    if (scope === "task" && (manifest.owner.scope !== "task"
+        || manifest.owner.taskId !== process.env.YUI_TASK_ID)) {
+        throw new Error("Managed Task invocation does not match its Session Manifest owner.");
+    }
+    const expectedPath = resolve(home, "runtime", "session-manifests", `${manifest.digest}.json`);
+    if (resolve(manifestPath) !== expectedPath) {
+        throw new Error("Managed Session Manifest path is outside this YUI_HOME.");
+    }
+    return manifest;
+}
 function cleanupCliError(error, fallbackResource) {
     if (error instanceof WorkspaceCleanupBlockedError) {
         return usageError(error.message, undefined, cleanupBlockedDetails(error.reason, error.resource, error.retryable));

package/dist/commands/globalRoleCommands.js

@@ -36,9 +36,8 @@ function roleContext(args, store, options) {
         if (environment.YUI_SESSION_SCOPE !== "global" || environment.YUI_ROLE !== name) {
             throw usageError("Managed GlobalRole context is outside the exact Session authority.");
         }
-        if (environment.YUI_SESSION_MANIFEST === undefined
-            || environment.YUI_SESSION_CLI === undefined) {
-            throw usageError("Managed GlobalRole context requires the exact Session Manifest and CLI.");
+        if (environment.YUI_SESSION_MANIFEST === undefined) {
+            throw usageError("Managed GlobalRole context requires its Session Manifest.");
         }
     }
     const role = requireRole(name, store);
@@ -81,7 +80,12 @@ function roleContext(args, store, options) {
                 : ["perform-global-role-request"]
         },
         sessionManifestPath: environment.YUI_SESSION_MANIFEST,
-        sessionCliPath: environment.YUI_SESSION_CLI
+        cliCommand: "yui",
+        // Compatibility hint for already-running Sessions. New instructions use
+        // the stable command name and do not bind behavior to this wrapper path.
+        ...(environment.YUI_SESSION_CLI === undefined
+            ? {}
+            : { legacySessionCliPath: environment.YUI_SESSION_CLI })
     });
     if (options.jsonOutput === true)
         return `${JSON.stringify(context)}\n`;

package/dist/commands/taskCommands.js

@@ -5,6 +5,7 @@ import { buildRunContextPack, buildRunContextDelta, contextSnapshotDeltaRefIds,
 import { contextSnapshotRef } from "../context/contextSnapshot.js";
 import { CliError, dataError, roleNotFound, runtimeError, taskNotFound, usageError } from "../errors/cliError.js";
 import { createTaskEvent } from "../event/taskEvent.js";
+import { createTaskRecordRetirement, isTaskRecordRetired, taskRecordRetirement } from "../task/taskRecordRetirement.js";
 import { clearMatchingLeaderStallAttention, isRoleRunStalled, RUN_PROGRESS_EVENT, RUN_RECOVERED_EVENT } from "../scheduler/roleRunStall.js";
 import { readCommandText } from "./textInput.js";
 import { assertTaskCompletionPublishedTreeProof } from "./taskCompletionGate.js";
@@ -1348,23 +1349,79 @@ function taskMessageCommand(args, store, options) {
         }
         if (messages.length === 0)
             return "No messages found.\n";
+        const retirements = new Map(store.listEvents(task.id).flatMap((event) => {
+            const retirement = taskRecordRetirement(event);
+            return retirement?.recordKind === "message"
+                ? [[retirement.recordId, retirement]]
+                : [];
+        }));
         const timeZone = store.getConfig().timeZone;
         return `${renderTable(`Task messages: ${task.id}`, [
             { header: "Message", minWidth: 7, maxWidth: 18 },
+            { header: "Status", minWidth: 6, maxWidth: 9 },
             { header: "Author", minWidth: 6, maxWidth: 18 },
             { header: "Created", minWidth: 10, maxWidth: 28 },
             { header: "Body", minWidth: 8, maxWidth: 72 }
         ], messages.map((message) => [
             message.id,
+            retirements.has(message.id) ? "retired" : "active",
             taskMessageAuthorLabel(message.author),
             presentTime(message.createdAt, timeZone),
             message.body
         ]), defaultTableWidth())}\n`;
     }
+    if (command === "retire") {
+        return retireMessage(rest, store, options);
+    }
     throw usageError(command === undefined
         ? "Task message command is required."
         : `Unknown command: task message ${command}`);
 }
+function retireMessage(args, store, options) {
+    const usage = "Task message retire usage: yui task message retire <task>/<message> --reason <text>.";
+    const parsed = parseTail(args, new Set(["--reason"]), usage);
+    exactPositionals(parsed.positionals, 1, usage);
+    const reason = requiredOption(parsed.options, "--reason");
+    const reference = taskRecordReference(parsed.positionals[0], "message", "Message reference", options);
+    const now = clock(options);
+    const result = store.transaction((tx) => {
+        const task = requireTask(tx, reference.taskId);
+        assertTaskOpen(task);
+        const actor = taskActor(options, task.id);
+        if (actor === "leader") {
+            throw usageError("Only the user or global Operator may retire a Task Message.");
+        }
+        const message = tx.listMessages(task.id).find(({ id }) => id === reference.localId);
+        if (message === undefined) {
+            throw dataError(`Task Message not found: ${task.id}/${reference.localId}.`);
+        }
+        const events = tx.listEvents(task.id);
+        if (isTaskRecordRetired(events, "message", message.id)) {
+            return { task, message, changed: false };
+        }
+        // Remove an isolated pending wake for this exact directive. A merged batch
+        // is retained because its other signals remain actionable; context and
+        // actionability projections still filter the retired message below.
+        try {
+            settleExactWorkExecution(tx, leaderMailbox(task.id), messageRef(task.id, message.id));
+        }
+        catch {
+            // Merged pending work cannot be split without losing unrelated signals.
+        }
+        tx.saveEvent(task.id, createTaskRecordRetirement({
+            eventId: tx.nextEventId(task.id),
+            taskId: task.id,
+            recordKind: "message",
+            recordId: message.id,
+            reason,
+            retiredBy: actor
+        }, now));
+        return { task, message, changed: true };
+    });
+    if (result.changed)
+        options.runtime?.notifyStateChanged(result.task.id);
+    return `Retired Task Message ${result.task.id}/${result.message.id}\n`;
+}
 /**
  * Issue 05: force-wake escape hatch. Bypasses the actionability digest and
  * enqueues exactly one Leader wakeup with an auditable reason. The reason is
@@ -2659,9 +2716,7 @@ function retireWork(args, store, options) {
         if (task.status !== "active") {
             throw usageError(`Task is not active: ${task.id}/${task.status}.`);
         }
-        if (taskActor(options, task.id) !== "leader") {
-            throw usageError("Only the Task Leader may retire a Work Item.");
-        }
+        const actor = taskActor(options, task.id);
         if (replacementWorkItemId !== undefined) {
             const replacement = requireWorkItem(tx, replacementWorkItemId, options);
             if (replacement.taskId !== task.id) {
@@ -2701,7 +2756,7 @@ function retireWork(args, store, options) {
             }
         }
         const next = retireWorkItem(item, {
-            by: "leader",
+            by: actor,
             summary,
             ...(replacementWorkItemId === undefined ? {} : { replacementWorkItemId })
         }, now);
@@ -2713,8 +2768,16 @@ function retireWork(args, store, options) {
                 ...(replacementWorkItemId === undefined
                     ? {}
                     : { replacementWorkItemId }),
-                ...leaderActionEventPayload(tx, task.id, options)
+                ...(actor === "leader" ? leaderActionEventPayload(tx, task.id, options) : { retiredBy: actor })
             }, now);
+            tx.saveEvent(task.id, createTaskRecordRetirement({
+                eventId: tx.nextEventId(task.id),
+                taskId: task.id,
+                recordKind: "work-item",
+                recordId: next.id,
+                reason: summary,
+                retiredBy: actor
+            }, now));
         }
         return next;
     });
@@ -3801,10 +3864,64 @@ function taskRunCommand(args, store, options) {
         return yieldRunStatus(rest, store, options);
     if (command === "checkpoint")
         return output(checkpointRun(rest, store, options));
+    if (command === "retire")
+        return retireRun(rest, store, options);
     throw usageError(command === undefined
         ? "Task run command is required."
         : `Unknown command: task run ${command}`);
 }
+function retireRun(args, store, options) {
+    const usage = "Task run retire usage: yui task run retire <task>/<run> --reason <text>.";
+    const parsed = parseTail(args, new Set(["--reason"]), usage);
+    exactPositionals(parsed.positionals, 1, usage);
+    const reason = requiredOption(parsed.options, "--reason");
+    const reference = taskRecordReference(parsed.positionals[0], "agentRun", "Agent Run reference", options);
+    const now = clock(options);
+    const result = store.transaction((tx) => {
+        const task = requireTask(tx, reference.taskId);
+        assertTaskOpen(task);
+        const actor = taskActor(options, task.id);
+        if (actor === "leader") {
+            throw usageError("Only the user or global Operator may retire an Agent Run.");
+        }
+        let run = tx.getAgentRun(task.id, reference.localId);
+        if (run === null)
+            throw dataError(`Agent Run not found: ${task.id}/${reference.localId}.`);
+        const events = tx.listEvents(task.id);
+        if (isTaskRecordRetired(events, "agent-run", run.id)) {
+            return { task, run, changed: false };
+        }
+        if (run.status === "active") {
+            const terminal = terminalizeExactTaskRun(tx, {
+                taskId: task.id,
+                roleName: run.roleName,
+                agentId: run.effective.agentId,
+                runId: run.id,
+                receiptId: agentRunDeliveryReceiptId(run),
+                outcome: { status: "failed", summary: `Agent Run retired: ${reason}` }
+            }, now);
+            if (terminal.disposition !== "applied" || terminal.run === null) {
+                throw usageError(`Agent Run changed during retirement: ${run.id}/${terminal.reason ?? "obsolete"}.`);
+            }
+            run = terminal.run;
+        }
+        tx.saveEvent(task.id, createTaskRecordRetirement({
+            eventId: tx.nextEventId(task.id),
+            taskId: task.id,
+            recordKind: "agent-run",
+            recordId: run.id,
+            reason,
+            retiredBy: actor
+        }, now));
+        return { task, run, changed: true };
+    });
+    if (result.changed)
+        options.runtime?.notifyStateChanged(result.task.id);
+    return output(`Retired Agent Run ${result.task.id}/${result.run.id}\n`, {
+        agentRun: result.run,
+        retired: true
+    });
+}
 function runContextCommand(args, store, options) {
     const [first, ...rest] = args;
     if (first === "expand") {
@@ -3878,6 +3995,7 @@ function listRuns(args, store, options) {
     const runs = store.listAgentRuns(item.taskId).filter((run) => run.workItemId === item.id);
     if (runs.length === 0)
         return "No runs found.\n";
+    const events = store.listEvents(item.taskId);
     return `${renderTable(`Runs: ${item.id}`, [
         { header: "Run", minWidth: 6, maxWidth: 20 },
         { header: "Role", minWidth: 4, maxWidth: 22 },
@@ -3887,6 +4005,7 @@ function listRuns(args, store, options) {
         { header: "Profile", minWidth: 7, maxWidth: 8 },
         { header: "Permission", minWidth: 8, maxWidth: 16 },
         { header: "Status", minWidth: 6, maxWidth: 12 },
+        { header: "History", minWidth: 7, maxWidth: 9 },
         { header: "Summary", minWidth: 8, maxWidth: 58 }
     ], runs.map((run) => [
         run.id,
@@ -3897,6 +4016,7 @@ function listRuns(args, store, options) {
         run.effective.profileAccess,
         run.effective.permission.strategy,
         run.status,
+        isTaskRecordRetired(events, "agent-run", run.id) ? "retired" : "active",
         run.summary ?? "-"
     ]), defaultTableWidth())}\n`;
 }
@@ -4907,14 +5027,21 @@ function showRun(args, store, options) {
         const facts = readRunRecoveryFacts(tx, run.taskId, run.id);
         if (facts === null)
             throw usageError(`Agent Run not found: ${run.taskId}/${run.id}.`, usage);
-        return { run, recovery: projectRunRecovery(facts) };
+        const retirement = tx.listEvents(run.taskId)
+            .map(taskRecordRetirement)
+            .find((entry) => entry?.recordKind === "agent-run" && entry.recordId === run.id) ?? null;
+        return { run, recovery: projectRunRecovery(facts), retirement };
     });
     if (asJson) {
         return { kind: "output", output: `${JSON.stringify(data, null, 2)}\n`, data };
     }
-    return { kind: "output", output: renderRunShow(data.run, data.recovery), data };
+    return {
+        kind: "output",
+        output: renderRunShow(data.run, data.recovery, data.retirement),
+        data
+    };
 }
-function renderRunShow(run, recovery) {
+function renderRunShow(run, recovery, retirement) {
     const lines = [
         `Run: ${run.id}`,
         `Task: ${run.taskId}`,
@@ -4922,6 +5049,10 @@ function renderRunShow(run, recovery) {
         `Purpose: ${run.purpose}`,
         `Mode: ${run.mode}`,
         `Status: ${run.status}`,
+        ...(retirement === null ? [] : [
+            `History: retired by ${retirement.retiredBy}`,
+            `Retirement reason: ${retirement.reason}`
+        ]),
         `Effective: ${run.effective.agentId}/${run.effective.adapterId} r${run.effective.sourceDesiredRevision}`,
         `Created: ${run.createdAt}`,
         ...(run.pushedAt === undefined ? [] : [`Pushed: ${run.pushedAt}`]),
@@ -6065,7 +6196,8 @@ function taskRecordReference(value, kind, label, options) {
 function assertWorkItemDependenciesCompleted(store, item) {
     for (const dependencyId of item.dependsOn) {
         const dependency = store.getWorkItem(item.taskId, dependencyId);
-        if (dependency === null || dependency.status !== "completed") {
+        if (dependency === null
+            || (dependency.status !== "completed" && dependency.status !== "retired")) {
             throw usageError(`Work Item dependency is not completed: ${dependencyId}.`);
         }
     }