@zq-silk/yui 0.12.0 → 0.12.2

package/dist/cli/updatePorts.js

@@ -34,10 +34,13 @@ import { accessSync, constants, existsSync, mkdtempSync, readFileSync, realpathS
 import { tmpdir } from "node:os";
 import { delimiter, dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import Database from "better-sqlite3";
 import { runtimeError } from "../errors/cliError.js";
 import { isConcreteVersion } from "../domain/validation.js";
 import { STORAGE_DOCTOR_CHECK_NAMES } from "../doctor/doctor.js";
+import { acquireHandoverLock } from "../release/runtimeRelease.js";
 import { inspectStorageSchema } from "../storage/storageSchema.js";
+import { placeUpgradeFence } from "../storage/upgradeFence.js";
 import { correlateUpgradeReceipt } from "../storage/upgrade/upgradeOrchestrator.js";
 import { readSwitchProgress } from "../storage/upgrade/switchProgress.js";
 const PACKAGE_NAME = "@zq-silk/yui";
@@ -91,8 +94,29 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
     // deliberately not persisted as a retry or recovery protocol.
     let verifiedActivatedBinary;
     let verifiedActivatedVersion;
+    let storageFenceOwnerPid;
     const stopReplacementController = (home, pid) => (stopReplacementControllerForUpdate(home, pid, environment, run));
     return {
+        beginControllerHandover(home) {
+            return acquireHandoverLock(home).release;
+        },
+        beginStorageWriteFence(home) {
+            const release = placeUpgradeFence(home, {
+                reason: "update storage activation in progress",
+                createdAt: new Date().toISOString(),
+                ownerPid: process.pid
+            });
+            storageFenceOwnerPid = process.pid;
+            let released = false;
+            return () => {
+                if (released)
+                    return;
+                release();
+                released = true;
+                if (storageFenceOwnerPid === process.pid)
+                    storageFenceOwnerPid = undefined;
+            };
+        },
         stage(version) {
             // A caller that names a version (the release workflow, which freezes the
             // exact version in its plan) installs THAT version — never a moving
@@ -151,7 +175,10 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
                 env: {
                     ...environment,
                     YUI_HOME: home,
-                    YUI_UPDATE_EXTERNALLY_QUIESCED: "1"
+                    YUI_UPDATE_EXTERNALLY_QUIESCED: "1",
+                    ...(storageFenceOwnerPid === undefined
+                        ? {}
+                        : { YUI_UPDATE_HANDOVER_OWNER_PID: String(storageFenceOwnerPid) })
                 },
                 shell: false
             });
@@ -219,6 +246,7 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
             // on-disk schema and report `switched: false` so the caller re-probes the
             // real state instead of giving a recovery instruction from a stale receipt.
             const schema = inspectStorageSchema(home);
+            const sqliteSchemaHead = inspectSqliteSchemaHead(home);
             // A crash mid-switch leaves a durable progress marker. A marker of ANY phase
             // — `backing-up`, `promoting`, or `interrupted` — is only actionable as an
             // interrupted switch when the FILESYSTEM still corroborates it: the backup
@@ -243,6 +271,7 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
                         switched: false,
                         interrupted: true,
                         schemaCurrent: false,
+                        ...(sqliteSchemaHead === undefined ? {} : { sqliteSchemaHead }),
                         ...(progress.backupPath === undefined ? {} : { backupPath: progress.backupPath })
                     };
                 }
@@ -252,12 +281,17 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
             }
             const correlation = correlateUpgradeReceipt(home);
             if (!correlation.corresponds) {
-                return { switched: false, schemaCurrent: schema.status === "current" };
+                return {
+                    switched: false,
+                    schemaCurrent: schema.status === "current",
+                    ...(sqliteSchemaHead === undefined ? {} : { sqliteSchemaHead })
+                };
             }
             const receipt = correlation.receipt;
             return {
                 switched: true,
                 schemaCurrent: schema.status === "current",
+                ...(sqliteSchemaHead === undefined ? {} : { sqliteSchemaHead }),
                 ...(receipt.backupPath === undefined ? {} : { backupPath: receipt.backupPath })
             };
         },
@@ -291,6 +325,39 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
         }
     };
 }
+/**
+ * Read the generic durable SQLite ledger without asking the old parent binary
+ * to understand the staged release's migration registry. The staged preflight
+ * supplies the validated source and target heads used to interpret this value.
+ */
+function inspectSqliteSchemaHead(home) {
+    const path = join(home, "yui.db");
+    if (!existsSync(path))
+        return undefined;
+    const db = new Database(path, { readonly: true, fileMustExist: true });
+    try {
+        db.pragma("query_only = ON");
+        const rows = db.prepare("SELECT version, checksum FROM schema_migrations ORDER BY version").all();
+        if (rows.length === 0)
+            throw new Error("SQLite migration ledger is empty.");
+        for (let index = 0; index < rows.length; index += 1) {
+            const row = rows[index];
+            if (row.version !== index + 1
+                || typeof row.checksum !== "string"
+                || row.checksum.length === 0) {
+                throw new Error("SQLite migration ledger is not a contiguous checksummed prefix.");
+            }
+        }
+        const head = rows.at(-1);
+        return {
+            version: head.version,
+            checksum: head.checksum
+        };
+    }
+    finally {
+        db.close();
+    }
+}
 const UPDATE_CLI_PATH = fileURLToPath(new URL("../cli.js", import.meta.url));
 const UPDATE_CLIENT_RUNTIME_PATH = fileURLToPath(new URL("../controller/clientRuntime.js", import.meta.url));
 const UPDATE_CONTROLLER_RECONCILIATION_PATH = fileURLToPath(new URL("../controller/updateReconciliation.js", import.meta.url));
@@ -581,7 +648,17 @@ function runControllerCommand(home, environment, spawn, method, cliBinary) {
     const args = cliBinary === undefined
         ? [UPDATE_CLI_PATH, "--json", "controller", method]
         : ["--json", "controller", method];
-    const result = spawn(command, args, { cwd: process.cwd(), env: { ...environment, YUI_HOME: home }, shell: false });
+    const result = spawn(command, args, {
+        cwd: process.cwd(),
+        env: {
+            ...environment,
+            YUI_HOME: home,
+            // This exact lifecycle child is part of the update process that owns
+            // the handover lock. Managed Sessions never receive this bypass.
+            YUI_UPDATE_HANDOVER_OWNER_PID: String(process.pid)
+        },
+        shell: false
+    });
     if (result.error !== undefined || result.status !== 0) {
         const error = new Error(`Controller ${method} failed (exit ${result.status ?? "null"}).`);
         const code = controllerErrorCodeFromResult(result);
@@ -828,11 +905,14 @@ function interpretPreflight(result) {
         ...(data.sceneUnchanged === true ? { sceneUnchanged: true } : {})
     };
 }
-/** Strictly parse the three green states of the internal update preflight. */
+/** Strictly parse the green states of the internal update preflight. */
 function parseUpdatePreflightResult(data) {
     const status = data.status;
     const stepCount = data.stepCount;
-    if ((status !== "already-current" && status !== "compatible" && status !== "migration-required")
+    if ((status !== "already-current"
+        && status !== "compatible"
+        && status !== "in-place-migration"
+        && status !== "migration-required")
         || !Number.isSafeInteger(stepCount)
         || stepCount < 0) {
         return null;
@@ -857,11 +937,57 @@ function parseUpdatePreflightResult(data) {
         return { status };
     const evidence = status === "compatible"
         ? `${stepCount} compatible step(s) classified and the compatible source validated in memory`
-        : `${stepCount} offline migration step(s) classified and the offline runtime inventory confirmed clear`;
+        : status === "in-place-migration"
+            ? `${stepCount} SQLite migration step(s) classified for one in-place transaction and the offline runtime inventory confirmed clear`
+            : `${stepCount} offline migration step(s) classified and the offline runtime inventory confirmed clear`;
+    const summary = `${evidence}. `
+        + "No staged Home or staged-output loader validation was performed during update preflight.";
+    if (status === "in-place-migration") {
+        const sqliteMigration = parseSqliteMigrationBoundary(data.sqliteMigration, stepCount);
+        if (sqliteMigration === null)
+            return null;
+        return {
+            status,
+            summary,
+            sqliteMigration
+        };
+    }
     return {
         status,
-        summary: `${evidence}. `
-            + "No staged Home or staged-output loader validation was performed during update preflight."
+        summary
+    };
+}
+function parseSqliteMigrationBoundary(value, stepCount) {
+    if (!isRecord(value))
+        return null;
+    const currentVersion = value.currentVersion;
+    const currentChecksum = value.currentChecksum;
+    const targetVersion = value.targetVersion;
+    const targetChecksum = value.targetChecksum;
+    const pendingVersions = value.pendingVersions;
+    if (!Number.isSafeInteger(currentVersion)
+        || currentVersion < 1
+        || typeof currentChecksum !== "string"
+        || currentChecksum.length === 0
+        || !Number.isSafeInteger(targetVersion)
+        || targetVersion <= currentVersion
+        || typeof targetChecksum !== "string"
+        || targetChecksum.length === 0
+        || !Array.isArray(pendingVersions)
+        || pendingVersions.length !== stepCount
+        || targetVersion !== currentVersion + stepCount
+        || pendingVersions.some((version, index) => !Number.isSafeInteger(version) || version !== currentVersion + index + 1)) {
+        return null;
+    }
+    return {
+        current: {
+            version: currentVersion,
+            checksum: currentChecksum
+        },
+        target: {
+            version: targetVersion,
+            checksum: targetChecksum
+        }
     };
 }
 function parseUpdateBlockers(value) {
@@ -933,6 +1059,9 @@ function interpretActivation(result) {
     if (outcome === "already-current")
         return { status: "already-current" };
     if (outcome === "upgraded") {
+        if (data.migrationMode === "in-place" && data.backupPath === undefined) {
+            return { status: "migrated-in-place" };
+        }
         const backupPath = data.backupPath;
         if (typeof backupPath !== "string"
             || backupPath.length === 0

package/dist/cli/upgradeCommand.js

@@ -35,6 +35,9 @@ export async function runUpgradeCommand(args, home, options = {}) {
         ...(options.controllerLifecycle === undefined
             ? {}
             : { controllerLifecycle: options.controllerLifecycle }),
+        ...(options.externalUpgradeFenceOwnerPid === undefined
+            ? {}
+            : { externalUpgradeFenceOwnerPid: options.externalUpgradeFenceOwnerPid }),
         ...(options.now === undefined ? {} : { now: options.now })
     });
     return {
@@ -68,28 +71,35 @@ export function renderUpgradeResult(result, mode) {
                 ? "four-state classification"
                 : result.status === "compatible"
                     ? "four-state classification plus compatible-source validation"
-                    : "four-state classification plus a clear offline runtime inventory";
+                    : result.status === "in-place-migration"
+                        ? "SQLite ledger classification plus a clear offline runtime inventory"
+                        : "four-state classification plus a clear offline runtime inventory";
             return `${header}\nUpdate preflight: ${result.status} (${result.stepCount} step(s)); `
                 + `${evidence}. No staged Home was created, `
                 + "no staged-output loader validation was performed, and storage was not switched.";
         }
         case "dry-run": {
-            const steps = result.report.outcome === "dry-run" ? result.report.steps.length : 0;
+            const steps = result.classification.sqliteMigration?.pendingVersions.length
+                ?? (result.report.outcome === "dry-run" ? result.report.steps.length : 0);
             return `${header}\nDry run: validated ${steps} migration step(s) through the loader gate. `
                 + "Staged output discarded; storage was not switched.";
         }
         case "upgraded":
-            return `${header}\nUpgraded storage. Original Home backed up at `
-                + `${result.backupPath ?? "(unspecified)"}.`;
+            return result.migrationMode === "in-place"
+                ? `${header}\nUpgraded SQLite in place in one transaction; no database rebuild or backup copy was created.`
+                : `${header}\nUpgraded storage. Original Home backed up at `
+                    + `${result.backupPath ?? "(unspecified)"}.`;
         case "blocked": {
             // Most blockers guarantee the source is untouched. A partial switch or a
             // post-switch ambiguity explicitly carries the committed boundary and
             // named recovery evidence; never print a false unchanged claim there.
-            const unchangedNote = result.switchCommitted === true
-                ? "The storage switch committed, but post-switch completion is ambiguous; the old Controller was not restored (see Action and recovery evidence)."
-                : result.stage === "switch-ambiguous"
-                    ? "The switch did not complete and could not be rolled back; the authoritative Home is NOT intact (see Action)."
-                    : "Storage was not switched; the authoritative Home is unchanged.";
+            const unchangedNote = result.storageCommitted === true
+                ? "The SQLite transaction committed in place; the old Controller was not restored (see Action)."
+                : result.switchCommitted === true
+                    ? "The storage switch committed, but post-switch completion is ambiguous; the old Controller was not restored (see Action and recovery evidence)."
+                    : result.stage === "switch-ambiguous"
+                        ? "The switch did not complete and could not be rolled back; the authoritative Home is NOT intact (see Action)."
+                        : "Storage was not switched; the authoritative Home is unchanged.";
             return [
                 header,
                 `${mode === "dry-run" ? "Dry run" : mode === "update-preflight" ? "Update preflight" : "Upgrade"} blocked at ${result.stage}: ${result.message}`,

package/dist/cli.js

@@ -301,19 +301,44 @@ export async function main() {
     if (args[0] === "upgrade") {
         // Mirror doctor/controller: needs a Home but self-manages the schema check,
         // because upgrade must run against a non-current Home.
-        const result = await runUpgradeCommand(args.slice(1), home, process.env.YUI_UPDATE_EXTERNALLY_QUIESCED === "1"
-            ? { controllerLifecycle: "externally-quiesced" }
-            : {});
-        // Public execute upgrades leave the Home operational even when no
-        // Controller existed before the command. Dry-run and the staged updater's
-        // externally-quiesced preflight must remain read-only/lifecycle-neutral.
-        if (args.length === 1
-            && result.exitCode === 0
-            && process.env.YUI_UPDATE_EXTERNALLY_QUIESCED !== "1") {
-            await ensureFileTaskController(home, { environment: process.env });
+        const externallyQuiesced = process.env.YUI_UPDATE_EXTERNALLY_QUIESCED === "1";
+        const ownsHandover = args.length === 1 && !externallyQuiesced;
+        const externalFenceOwner = externallyQuiesced
+            ? process.env.YUI_UPDATE_HANDOVER_OWNER_PID
+            : undefined;
+        const externalUpgradeFenceOwnerPid = externalFenceOwner === undefined
+            ? undefined
+            : Number(externalFenceOwner);
+        if (externalUpgradeFenceOwnerPid !== undefined
+            && (!Number.isSafeInteger(externalUpgradeFenceOwnerPid)
+                || externalUpgradeFenceOwnerPid < 1)) {
+            throw runtimeError("Update storage-fence owner PID is invalid.");
+        }
+        const handover = ownsHandover ? acquireHandoverLock(home) : undefined;
+        try {
+            const result = await runUpgradeCommand(args.slice(1), home, externallyQuiesced
+                ? {
+                    controllerLifecycle: "externally-quiesced",
+                    ...(externalUpgradeFenceOwnerPid === undefined
+                        ? {}
+                        : { externalUpgradeFenceOwnerPid })
+                }
+                : {});
+            // Public execute upgrades leave the Home operational even when no
+            // Controller existed before the command. Dry-run and the staged updater's
+            // externally-quiesced preflight must remain read-only/lifecycle-neutral.
+            if (ownsHandover && result.exitCode === 0) {
+                await ensureFileTaskController(home, {
+                    environment: process.env,
+                    handoverOwnerPid: process.pid
+                });
+            }
+            process.exitCode = result.exitCode;
+            emit(result.output, false, result.data);
+        }
+        finally {
+            handover?.release();
         }
-        process.exitCode = result.exitCode;
-        emit(result.output, false, result.data);
         return;
     }
     if (args[0] === "internal") {
@@ -521,9 +546,21 @@ export async function main() {
         }
         validateCompatibleFileTaskStore(home);
         const controllerMethod = method;
+        const updateHandoverOwner = process.env.YUI_UPDATE_HANDOVER_OWNER_PID;
+        const updateHandoverOwnerPid = updateHandoverOwner === undefined
+            ? undefined
+            : Number(updateHandoverOwner);
+        if (updateHandoverOwnerPid !== undefined
+            && (!Number.isSafeInteger(updateHandoverOwnerPid) || updateHandoverOwnerPid < 1)) {
+            throw runtimeError("Update Controller handover owner PID is invalid.");
+        }
+        const controllerOptions = {
+            environment: process.env,
+            ...(updateHandoverOwnerPid === undefined ? {} : { handoverOwnerPid: updateHandoverOwnerPid })
+        };
         const result = controllerMethod === "restart"
-            ? await restartFileTaskController(home, { environment: process.env })
-            : await stopFileTaskController(home, { environment: process.env });
+            ? await restartFileTaskController(home, controllerOptions)
+            : await stopFileTaskController(home, controllerOptions);
         // The update lifecycle needs the authenticated replacement PID returned by
         // restart/readiness.  Keep stop's long-standing text envelope, while
         // exposing restart's structured result alongside its human output.

package/dist/commands/configCommands.js

@@ -455,7 +455,7 @@ const CONFIG_KEY_HANDLERS = [
                 const { runtimeHealth: _removed, ...rest } = config;
                 return rest;
             });
-            return "Runtime health thresholds reset to quiet 300s / diagnostic 600s / stall 1800s\n";
+            return "Runtime health thresholds reset to quiet 300s / diagnostic 900s / stall 1800s\n";
         }
     },
     {

package/dist/commands/executionAuditCommands.js

@@ -139,7 +139,8 @@ export function renderExecutionAudit(report, width = defaultTableWidth()) {
     }
     if (report.sessions.status === "ok" && report.sessions.data !== undefined) {
         const sessions = report.sessions.data;
-        lines.push("", `Sessions: ${sessions.generations} generations · ${sessions.broken} broken · ${sessions.stopped} stopped · ${sessions.other} other`, `Resets: ${sessions.resets} · lifecycle events ${sessions.lifecycleEvents} · stop failures ${sessions.stopFailures}`, `Terminal by Run relation: ${sessions.terminalByRunRelation.postRunYielded} post-run-yielded`
+        lines.push("", `Sessions: ${sessions.generations} generations · ${sessions.broken} broken · ${sessions.stopped} stopped · ${sessions.other} other`, `Resets: ${sessions.resets} · Conversation switches ${sessions.conversationSwitches}`
+            + ` · lifecycle events ${sessions.lifecycleEvents} · stop failures ${sessions.stopFailures}`, `Terminal by Run relation: ${sessions.terminalByRunRelation.postRunYielded} post-run-yielded`
             + ` · ${sessions.terminalByRunRelation.runFailed} run-failed`
             + ` · ${sessions.terminalByRunRelation.activeRun} active-run`
             + ` · ${sessions.terminalByRunRelation.noRun} no-run`);

package/dist/commands/taskCommands.js

@@ -9,8 +9,9 @@ import { createTaskRecordRetirement, isTaskRecordRetired, taskRecordRetirement }
 import { isRoleRunStalled, RUN_PROGRESS_EVENT, RUN_RECOVERED_EVENT } from "../scheduler/roleRunStall.js";
 import { readCommandText } from "./textInput.js";
 import { assertTaskCompletionPublishedTreeProof } from "./taskCompletionGate.js";
-import { createRoleSessionSet, retireTaskRoleSessionsForWorkspace, roleAgentSessionResumeMode, updateTaskRoleProviderRuntime } from "../executor/agentExecutor.js";
+import { createRoleSessionSet, retireTaskRoleSessionsForWorkspace, updateTaskRoleProviderRuntime } from "../executor/agentExecutor.js";
 import { currentProviderActivation, transferProviderAuthority } from "../runtime/providerRuntimeIdentity.js";
+import { CONVERSATION_SWITCH_REQUESTED_EVENT, CONVERSATION_SWITCH_RESOLVED_EVENT, projectConversationSwitch, providerConversationGeneration, roleSessionDispatchModeWithConversationSwitch } from "../runtime/conversationSwitch.js";
 import { resolveEffectiveLaunch } from "../executor/effectiveLaunch.js";
 import { defaultTableWidth, renderTable } from "../output/table.js";
 import { formatTimestamp } from "../output/timePresentation.js";
@@ -18,7 +19,6 @@ import { renderRoleDetails } from "../output/rolePresentation.js";
 import { createTaskMessage, taskMessageAuthorLabel } from "../message/message.js";
 import { cancelInputRequest } from "../input/inputRequest.js";
 import { recoverExactAgentRun, terminalizeExactTaskRun, validateExactRunReviewRound } from "../lifecycle/exactRunTerminalization.js";
-import { resetTaskRoleSessionGeneration } from "../lifecycle/taskRoleSessionReset.js";
 import { copyGlobalRoleToTaskRole, createRole, createRoleAgentBinding, switchActiveRoleAgent, unbindRoleAgent, updateRole, updateRoleStatus } from "../role/role.js";
 import { agentRunDeliveryReceiptId, createAgentRun, withAgentRunContextSnapshot } from "../run/agentRun.js";
 import { projectRunRecovery, readRunRecoveryFacts } from "../run/recoveryProjection.js";
@@ -1373,8 +1373,8 @@ function taskRoleCommand(args, store, options) {
         return output(bindTaskRole(rest, store, options));
     if (command === "unbind")
         return output(unbindTaskRole(rest, store, options));
-    if (command === "reset")
-        return resetTaskRole(rest, store, options);
+    if (command === "session")
+        return taskRoleSessionCommand(rest, store, options);
     if (command === "view")
         return viewTaskRole(rest, store);
     if (command === "takeover")
@@ -1385,29 +1385,78 @@ function taskRoleCommand(args, store, options) {
         ? "Task role command is required."
         : `Unknown command: task role ${command}`);
 }
-function resetTaskRole(args, store, options) {
-    const usage = "Task role reset usage: yui task role reset <task> <role> --reason <text>.";
+function taskRoleSessionCommand(args, store, options) {
+    const [command, ...rest] = args;
+    if (command === "switch")
+        return switchTaskRoleSession(rest, store, options);
+    throw usageError(command === undefined
+        ? "Task role session command is required."
+        : `Unknown command: task role session ${command}`);
+}
+function switchTaskRoleSession(args, store, options) {
+    const usage = "Task role session switch usage: yui task role session switch <task> <role> --reason <text>.";
     const parsed = parseTail(args, new Set(["--reason"]), usage);
     exactPositionals(parsed.positionals, 2, usage);
-    const reason = requiredOption(parsed.options, "--reason");
+    const reason = truncateEventNote(requiredOption(parsed.options, "--reason"));
     const now = clock(options);
-    let result;
-    try {
-        result = store.transaction((tx) => resetTaskRoleSessionGeneration(tx, parsed.positionals[0], parsed.positionals[1], reason, now));
-    }
-    catch (error) {
-        throw usageError(error instanceof Error ? error.message : String(error), usage);
-    }
-    const target = runtimeLifecycleTarget({
-        scope: "task",
+    const result = store.transaction((tx) => {
+        const task = requireTask(tx, parsed.positionals[0]);
+        if (task.status !== "active") {
+            throw usageError(inactiveTaskMessage(task, "switching a Provider Conversation"), usage);
+        }
+        const role = requireRole(tx, task.id, parsed.positionals[1]);
+        const requestedBy = taskActor(options, task.id);
+        const leaderRunId = requestedBy === "leader"
+            ? taskLeaderActionRunId(tx, task.id, options.environment, options.yuiHome)
+            : undefined;
+        if (requestedBy === "leader" && leaderRunId === undefined) {
+            throw usageError("Leader Conversation switching requires the exact current-Turn assertion.", usage);
+        }
+        const sessions = tx.getTaskRoleSessionSet(task.id, role.name);
+        const generation = providerConversationGeneration(sessions);
+        if (sessions === null || generation === null) {
+            throw usageError(`Task Role has no current Provider Conversation: ${task.id}/${role.name}.`, usage);
+        }
+        const events = tx.listEvents(task.id);
+        const previous = projectConversationSwitch(events, role.name, sessions);
+        if (previous?.status === "pending"
+            && previous.generation === generation
+            && previous.requestedBy === requestedBy
+            && previous.reason === reason) {
+            return { taskId: task.id, roleName: role.name, request: previous, replayed: true };
+        }
+        if (previous !== null && previous.resolvedAt === undefined) {
+            tx.saveEvent(task.id, createTaskEvent(tx.nextEventId(task.id), task.id, CONVERSATION_SWITCH_RESOLVED_EVENT, {
+                requestId: previous.requestId,
+                roleName: role.name,
+                generation: previous.generation,
+                status: "obsolete"
+            }, now));
+        }
+        const requestId = tx.nextEventId(task.id);
+        const event = createTaskEvent(requestId, task.id, CONVERSATION_SWITCH_REQUESTED_EVENT, {
+            requestId,
+            roleName: role.name,
+            generation,
+            requestedBy,
+            reason,
+            ...(leaderRunId === undefined ? {} : { leaderRunId })
+        }, now);
+        tx.saveEvent(task.id, event);
+        return {
+            taskId: task.id,
+            roleName: role.name,
+            request: projectConversationSwitch([...events, event], role.name, sessions),
+            replayed: false
+        };
+    });
+    options.runtime?.notifyStateChanged(result.taskId);
+    options.runtime?.notifyMailboxChanged?.({
+        kind: "role",
         taskId: result.taskId,
         roleName: result.roleName
     });
-    options.runtime?.notifyMailboxChanged?.(target);
-    notifyMailbox(options.runtime, result.roleName === LEADER_ROLE
-        ? { kind: "operator" }
-        : leaderMailbox(result.taskId), result.taskId);
-    return output(`Reset Task Role Session ${result.taskId}/${result.roleName}; runtime cleanup is pending.\n`, result);
+    return output(`${result.replayed ? "Reused" : "Recorded"} pending Provider Conversation switch ${result.request.requestId} for ${result.taskId}/${result.roleName}. The current Conversation remains authoritative until safe replacement binding.\n`, result);
 }
 function addTaskRole(args, store, options) {
     const usage = "Task role add usage: yui task role add <task> <name> [Role and Agent settings].";
@@ -2337,7 +2386,7 @@ function dispatchWork(args, store, options) {
                 workItemWriteProjectIds: item.writeProjectIds
             });
             const sessions = tx.getTaskRoleSessionSet(task.id, plan.role.name);
-            const dispatchMode = roleAgentSessionResumeMode(sessions, effective.agentId, effective);
+            const dispatchMode = taskRoleDispatchMode(tx, task.id, plan.role.name, sessions, effective.agentId, effective);
             const laneWorkspace = laneManagedWorkspace === undefined
                 ? undefined
                 : {
@@ -4576,7 +4625,7 @@ function retryRun(args, store, options) {
             contextSnapshotRef: contextSnapshotRef(retrySnapshot),
             deltaRefIds: contextSnapshotDeltaRefIds(tx, retrySnapshot)
         });
-        const created = createAgentRun(runId, task.id, role.name, roleAgentSessionResumeMode(sessions, effective.agentId, effective), assignment, now, {
+        const created = createAgentRun(runId, task.id, role.name, taskRoleDispatchMode(tx, task.id, role.name, sessions, effective.agentId, effective), assignment, now, {
             ...(previous.workItemId === undefined ? {} : { workItemId: previous.workItemId }),
             ...(runningGroup === undefined ? {} : {
                 executionGroupId: runningGroup.id,
@@ -5125,11 +5174,11 @@ function retryFailedReviewRun(previous, store, options, now) {
 }
 /**
  * Records one explicit Leader recovery decision against an exact live Run.
- * Retry and Session replacement remain requests: the Controller never sends
- * another input or changes a native generation from this command.
+ * Diagnose and retry remain same-Run requests: this command never changes a
+ * native Conversation generation.
  */
 function recoverRun(args, store, options) {
-    const usage = "Task run recover usage: yui task run recover <task>/<run> --action <diagnose|retry|replace-session|terminate> (--expected-progress-at <timestamp>|--from-next-action <fingerprint>) --provider-acceptance <accepted|rejected|ambiguous> --reason <text> [--agent-id <id>] [--adapter-id <id>] [--native-session-id <id>] [--launch-id <id>].";
+    const usage = "Task run recover usage: yui task run recover <task>/<run> --action <diagnose|retry|terminate> (--expected-progress-at <timestamp>|--from-next-action <fingerprint>) --provider-acceptance <accepted|rejected|ambiguous> --reason <text> [--agent-id <id>] [--adapter-id <id>] [--native-session-id <id>] [--launch-id <id>].";
     const parsed = parseTail(args, new Set([
         "--action",
         "--expected-progress-at",
@@ -6153,7 +6202,7 @@ export function dispatchPreparedReviewRound(taskId, reviewRoundId, store, option
                 effective,
                 workspace: laneWorkspace
             }, now);
-            createdRuns.push(createAgentRun(runId, taskId, laneReviewer.name, roleAgentSessionResumeMode(sessions, effective.agentId, effective), assignment, now, {
+            createdRuns.push(createAgentRun(runId, taskId, laneReviewer.name, taskRoleDispatchMode(tx, taskId, laneReviewer.name, sessions, effective.agentId, effective), assignment, now, {
                 ...(item === undefined ? {} : { workItemId: item.id }),
                 purpose: "review",
                 reviewRoundId: round.id,
@@ -6519,6 +6568,9 @@ function assertTaskOpen(task) {
 function taskActor(options, taskId) {
     return resolveTaskActor(options.environment, taskId);
 }
+function taskRoleDispatchMode(store, taskId, roleName, sessions, agentId, effective) {
+    return roleSessionDispatchModeWithConversationSwitch(sessions, store.listEvents(taskId), store.getWorkMailbox({ kind: "role", taskId, roleName }), roleName, agentId, effective);
+}
 function inactiveTaskMessage(task, action) {
     if (task.status === "draft") {
         return `Task ${task.id} is a Draft; activate it before ${action}.`;
@@ -6549,10 +6601,9 @@ function parseWorkStatus(value) {
 function parseRecoveryAction(value, usage) {
     if (value === "diagnose"
         || value === "retry"
-        || value === "replace-session"
         || value === "terminate")
         return value;
-    throw usageError("--action must be diagnose, retry, replace-session, or terminate.", usage);
+    throw usageError("--action must be diagnose, retry, or terminate.", usage);
 }
 function parseProviderAcceptance(value, usage) {
     if (value === "accepted" || value === "rejected" || value === "ambiguous")

package/dist/commands/taskContextCommand.js

@@ -269,7 +269,9 @@ export function runTaskContextCommand(args, store, currentTaskReviewCandidate =
                         : [`    Runtime source at creation: ${creation.payload.runtimeSource}`]),
                     ...(recovery === undefined ? [] : [
                         `    Runtime cleanup: ${recovery.runtimeCleanupPending ? "pending" : "none"}`,
-                        `    Fresh launch: ${recovery.freshLaunchAllowed ? "allowed" : "blocked"}`
+                        `    Fresh launch: ${recovery.freshLaunchAllowed
+                            ? "allowed"
+                            : `blocked (${recovery.freshLaunchBlockers.join(", ")})`}`
                     ])
                 ];
             })),
@@ -420,7 +422,9 @@ function renderCoordinationMailbox(mailbox) {
 }
 function latestStallKind(events, runId) {
     const event = [...events]
-        .filter((candidate) => candidate.type === "run.stalled" && candidate.payload.runId === runId)
+        .filter((candidate) => candidate.type === "run.stalled"
+        && candidate.payload.runId === runId
+        && candidate.payload.status !== "diagnostic-only")
         .sort((left, right) => Date.parse(right.createdAt) - Date.parse(left.createdAt))[0];
     return event?.payload.kind ?? "workflow-not-progressing";
 }