@zq-silk/yui 0.14.2 → 0.15.1

package/dist/cli/updatePorts.js

@@ -7,9 +7,10 @@
  * `npm install --global --prefix <tmp>`, so the live global install is never
  * touched until the binary-activation step. Preflight invokes the STAGED binary's
  * internal `yui upgrade --update-preflight` contract so the target version
- * proves that the Home exactly matches its current storage contract. After the
- * parent stops the exact old Controller, the binary is promoted and the
- * activated binary verifies the unchanged Home.
+ * proves that the Home is current or has a complete supported migration path.
+ * After the parent stops the exact old Controller, the binary is promoted,
+ * required migrations run through that same staged artifact, and the activated
+ * binary verifies the resulting current Home.
  *
  * Two hardening guarantees this module enforces:
  *
@@ -146,13 +147,26 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
             const result = run("npm", ["install", "--global", spec], { cwd: process.cwd(), env: environment, shell: false, stdio: "inherit" });
             assertSpawnOk(result, "activate the new binary");
         },
+        migrateStorage(staged, home) {
+            const result = run(staged.binaryPath, ["--json", "upgrade", "--update-apply"], {
+                cwd: process.cwd(),
+                env: {
+                    ...environment,
+                    YUI_HOME: home,
+                    YUI_UPDATE_HANDOVER_OWNER_PID: String(process.pid)
+                },
+                shell: false
+            });
+            return interpretStorageMigration(result);
+        },
         verify(staged, home) {
             // Verify the ACTUALLY-ACTIVATED global binary, not the staging path (P1-3).
             const activeBinary = resolveGlobalBinary(environment, run);
             if (activeBinary === null || !existsSync(activeBinary)) {
                 throw runtimeError("Post-update health check failed: could not locate the activated global `yui` binary.");
             }
-            // 1) Health check the unchanged current Home through the activated binary.
+            // 1) Health check the current (possibly just migrated) Home through the
+            // activated binary.
             // POST-VERIFY PARSES THE MACHINE-READABLE RESULT FIRST, THEN THE EXIT STATUS
             // (R2-F2). `yui --json doctor` deliberately sets a non-zero exit when storage
             // is unhealthy, so interpreting the exit status before the envelope would
@@ -784,21 +798,69 @@ function interpretPreflight(result) {
         ...(data.sceneUnchanged === true ? { sceneUnchanged: true } : {})
     };
 }
-/** Accept only an exact current Home. */
+/** Accept either an exact current Home or a complete supported migration path. */
 function parseUpdatePreflightResult(data) {
-    if (data.status !== "already-current"
+    if ((data.status !== "already-current" && data.status !== "migration-ready")
         || !Number.isSafeInteger(data.stepCount)
-        || data.stepCount !== 0
         || !Array.isArray(data.steps)
-        || data.steps.length !== 0)
+        || data.steps.length !== data.stepCount)
         return null;
     const homeClassification = data.classification;
     if (!isRecord(homeClassification) || !isRecord(homeClassification.classification))
         return null;
     const classification = homeClassification.classification;
-    if (classification.verdict !== "USABLE" || classification.status !== "current")
+    if (data.status === "already-current") {
+        if (data.stepCount !== 0
+            || classification.verdict !== "USABLE"
+            || classification.status !== "current")
+            return null;
+        return { status: "already-current", stepCount: 0 };
+    }
+    if (data.stepCount <= 0
+        || classification.verdict !== "MIGRATABLE"
+        || classification.status !== "migration-ready"
+        || !data.steps.every(isStorageMigrationStep))
         return null;
-    return { status: "already-current", stepCount: 0 };
+    return { status: "migration-ready", stepCount: data.stepCount };
+}
+function interpretStorageMigration(result) {
+    const data = parseSuccessEnvelopeData(result);
+    if (data === null) {
+        throw runtimeError("The staged binary did not return a successful storage migration result "
+            + `(exit ${result.status ?? "null"}${result.signal === null ? "" : `, signal ${result.signal}`}).`);
+    }
+    if (data.outcome === "blocked" || data.outcome === "failed") {
+        const message = typeof data.message === "string"
+            ? data.message
+            : "The staged binary refused the storage migration.";
+        const action = typeof data.action === "string" ? ` Action: ${data.action}` : "";
+        const backup = typeof data.backupPath === "string"
+            ? ` Backup: ${data.backupPath}`
+            : "";
+        throw runtimeError(`${message}${action}${backup}`);
+    }
+    if (result.status !== 0) {
+        throw runtimeError(`The staged binary returned outcome=${String(data.outcome)} but exited `
+            + `with status ${result.status ?? "null"}.`);
+    }
+    if (data.outcome === "already-current")
+        return {};
+    if (data.outcome !== "upgraded" || !isRecord(data.report)) {
+        throw runtimeError(`The staged binary returned unexpected storage migration outcome=${String(data.outcome)}.`);
+    }
+    const backupPath = data.report.backupPath;
+    if (typeof backupPath !== "string" || backupPath.length === 0) {
+        throw runtimeError("The staged binary did not report the required storage backup path.");
+    }
+    return { backupPath };
+}
+function isStorageMigrationStep(value) {
+    return isRecord(value)
+        && Number.isSafeInteger(value.fromVersion)
+        && Number.isSafeInteger(value.toVersion)
+        && value.toVersion === value.fromVersion + 1
+        && typeof value.name === "string"
+        && value.name.length > 0;
 }
 function parseUpdateBlockers(value) {
     if (value === undefined)

package/dist/cli/upgradeCommand.js

@@ -1,23 +1,24 @@
-/** `yui upgrade` validates the exact storage contract supported by this release. */
-import { latestStorageVersionState } from "../storage/upgrade/recordVersions.js";
+/** `yui upgrade` plans or applies the supported linear storage migration chain. */
 import { runStorageUpgrade } from "../storage/upgrade/upgradeOrchestrator.js";
-import { usageError } from "../errors/cliError.js";
+import { ensureFileTaskController, stopFileTaskController } from "../controller/clientRuntime.js";
+import { runtimeError, usageError } from "../errors/cliError.js";
+import { acquireHandoverLock, isForeignHandoverLockHeld, isHandoverLockHeld } from "../release/runtimeRelease.js";
 /**
  * Run the upgrade command. Parses the public `[--dry-run]` form plus the staged
  * updater's internal `--update-preflight` form, then returns rendered text,
  * structured data, and an exit code (0 for a safe result, 5 for a blocker).
  */
-export async function runUpgradeCommand(args, home) {
+export async function runUpgradeCommand(args, home, environment = process.env) {
     const mode = parseUpgradeArgs(args);
-    const result = await runStorageUpgrade({
-        home,
-        latest: latestStorageVersionState(),
-        mode
-    });
+    const result = mode === "execute"
+        ? await runInteractiveUpgrade(home, environment)
+        : mode === "update-apply"
+            ? await runUpdateOwnedUpgrade(home, environment)
+            : await runStorageUpgrade({ home, mode });
     return {
         output: renderUpgradeResult(result, mode),
         data: result,
-        exitCode: result.outcome === "blocked" ? 5 : 0
+        exitCode: result.outcome === "blocked" || result.outcome === "failed" ? 5 : 0
     };
 }
 function parseUpgradeArgs(args) {
@@ -26,37 +27,121 @@ function parseUpgradeArgs(args) {
     if (args.length === 1 && args[0] === "--dry-run")
         return "dry-run";
     // Intentionally omitted from public command help: this is the machine contract
-    // used by a staged `yui update`, not a replacement for user-facing dry-turn.
+    // used by a staged `yui update`, not a replacement for user-facing dry-run.
     if (args.length === 1 && args[0] === "--update-preflight")
         return "update-preflight";
+    if (args.length === 1 && args[0] === "--update-apply")
+        return "update-apply";
     throw usageError("Upgrade usage: yui upgrade [--dry-run]");
 }
+async function runInteractiveUpgrade(home, environment) {
+    const preflight = await runStorageUpgrade({ home, mode: "update-preflight" });
+    if (preflight.outcome !== "update-preflight"
+        || preflight.status === "already-current") {
+        return runStorageUpgrade({ home, mode: "execute" });
+    }
+    const handover = acquireHandoverLock(home);
+    let controllerWasRunning = false;
+    try {
+        const stopped = await stopFileTaskController(home, {
+            environment,
+            handoverOwnerPid: process.pid
+        });
+        controllerWasRunning = stopped.stopped;
+        const result = await runStorageUpgrade({ home, mode: "execute" });
+        if (controllerWasRunning
+            && (result.outcome === "upgraded" || result.outcome === "already-current")) {
+            try {
+                await ensureFileTaskController(home, {
+                    environment,
+                    handoverOwnerPid: process.pid
+                });
+            }
+            catch (error) {
+                throw runtimeError(`Storage reached version ${result.report.targetVersion}, but the current `
+                    + `Controller could not restart: ${messageOf(error)} Backup: `
+                    + `${result.report.backupPath ?? "none"}. Keep the Home quiesced, inspect `
+                    + "Controller ownership, and start only the current Yui Controller.");
+            }
+        }
+        return result;
+    }
+    finally {
+        handover.release();
+    }
+}
+async function runUpdateOwnedUpgrade(home, environment) {
+    const ownerText = environment.YUI_UPDATE_HANDOVER_OWNER_PID;
+    const ownerPid = ownerText === undefined ? Number.NaN : Number(ownerText);
+    if (!Number.isSafeInteger(ownerPid)
+        || ownerPid < 1
+        || process.ppid !== ownerPid
+        || !isHandoverLockHeld(home)
+        || isForeignHandoverLockHeld(home, ownerPid)) {
+        throw runtimeError("The internal update migration requires its direct parent to own the live "
+            + "Controller handover lock.");
+    }
+    return runStorageUpgrade({ home, mode: "execute" });
+}
 /** Render an {@link UpgradeResult} as concise, CLI-style text. */
 export function renderUpgradeResult(result, mode) {
     const header = versionHeader(result);
     switch (result.outcome) {
         case "already-current":
             return `${header}\nStorage is already at the current version; nothing to upgrade.`;
+        case "upgrade-plan":
+            return [
+                header,
+                `Upgrade plan: ${renderSteps(result.report.steps)}. Storage was not modified.`
+            ].join("\n");
+        case "upgraded":
+            return [
+                header,
+                `Storage upgraded through ${renderSteps(result.report.steps)}.`,
+                `Backup: ${result.report.backupPath ?? "none"}`
+            ].join("\n");
         case "update-preflight":
             return `${header}\nUpdate preflight: ${result.status} (${result.stepCount} steps). Storage was not modified.`;
         case "blocked": {
             return [
                 header,
-                `${mode === "dry-run" ? "Dry run" : mode === "update-preflight" ? "Update preflight" : "Upgrade"} blocked at ${result.stage}: ${result.message}`,
+                `${mode === "dry-run"
+                    ? "Dry run"
+                    : mode === "update-preflight"
+                        ? "Update preflight"
+                        : "Upgrade"} blocked at ${result.stage}: ${result.message}`,
                 `Action: ${result.action}`,
                 "The authoritative Home is unchanged."
             ].join("\n");
         }
+        case "failed":
+            return [
+                header,
+                `Upgrade failed at ${result.stage}: ${result.message}`,
+                `Action: ${result.action}`,
+                `Backup: ${result.backupPath ?? "none"}`,
+                result.sceneUnchanged
+                    ? "The authoritative Home was restored."
+                    : "The authoritative Home may have changed; keep it quiesced."
+            ].join("\n");
     }
 }
 function versionHeader(result) {
     const classification = result.classification;
-    const layout = classification.layoutVersion ?? classification.latestLayoutVersion;
-    const aggregate = classification.aggregateVersion ?? classification.latestAggregateVersion;
+    const storage = classification.storageVersion === undefined
+        ? "unknown"
+        : String(classification.storageVersion);
     const verdict = classification.classification.verdict;
-    const incompatible = classification.incompatibleComponent === undefined
-        ? ""
-        : ` incompatibleComponent=${classification.incompatibleComponent}`;
-    return `Storage: ${verdict} layout=${layout}/${classification.latestLayoutVersion} `
-        + `aggregate=${aggregate}/${classification.latestAggregateVersion}${incompatible}`;
+    return `Storage: ${verdict} version=${storage}/${classification.currentStorageVersion} `
+        + `minimum=${classification.minimumSupportedStorageVersion}`;
+}
+function renderSteps(steps) {
+    if (steps.length === 0)
+        return "no migrations";
+    return steps
+        .map(({ fromVersion, toVersion, name }) => `${fromVersion}->${toVersion} ${name}`)
+        .join(", ");
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
 }

package/dist/cli.js

@@ -2092,10 +2092,10 @@ async function executeOperatorSessionControl(control, home, store, runtime, tmux
         throw usageError("Operator is not configured. Run yui setup first.");
     const sessionSet = store.getGlobalRoleSessionSet(role.name);
     const active = sessionSet?.sessions[sessionSet.activeAgentId];
-    const paneRunning = tmux.detectRoleStatus("operator", "operator") === "running";
+    const paneRunning = tmux.probeRoleStatus("operator", "operator") === "running";
     if (paneRunning && active === undefined) {
         throw usageError("Operator is running but its native session has not been recorded yet. "
-            + "Wait for the first turn to settle before switching sessions.");
+            + "Record the exact native session before switching sessions.");
     }
     if (control.action === "resume"
         && paneRunning

package/dist/commands/agentCommands.js

@@ -2,6 +2,7 @@ import { isDeepStrictEqual } from "node:util";
 import { agentNotFound, usageError } from "../errors/cliError.js";
 import { defaultTableWidth, renderTable } from "../output/table.js";
 import { createConfiguredAgent, validateConfiguredAgent } from "../agent/agent.js";
+import { LIVE_SESSION_ACKNOWLEDGEMENT_OPTION } from "./roleRuntimeGuard.js";
 import { hasRuntimeLifecycleWork, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
 const SUPPORTED_ADAPTERS = Object.freeze(["codex", "claude"]);
 export function runAgentCommand(args, store) {
@@ -72,7 +73,8 @@ function updateAgent(args, store) {
     const [rawId, ...tail] = args;
     const id = agentId(rawId);
     const parsed = parseAgentOptions(tail, "update");
-    if (parsed.seen.size === 0) {
+    if (parsed.seen.size === 0
+        || [...parsed.seen].every((option) => option === LIVE_SESSION_ACKNOWLEDGEMENT_OPTION)) {
         throw usageError("Agent update requires at least one operational option.");
     }
     if (parsed.has("--arg") && parsed.has("--clear-args")) {
@@ -113,10 +115,13 @@ function updateAgent(args, store) {
                 + "Wait for lifecycle reconciliation to finish before changing Agent launch settings.");
         }
         const liveSession = findNonStoppedSessionReference(tx, id);
-        if (liveSession !== null) {
-            throw usageError(`Agent ${id} cannot be updated because ${describeReference(liveSession)} `
-                + `retains a non-stopped native session (${liveSession.status}). `
-                + "Stop that Role session before changing Agent launch settings.");
+        if (liveSession !== null && !parsed.has(LIVE_SESSION_ACKNOWLEDGEMENT_OPTION)) {
+            throw usageError(`${describeReference(liveSession)} runs a live native session (${liveSession.status}) on `
+                + `Agent ${id}, so this change applies to its next Host activation instead of the `
+                + "running one.\n"
+                + `Re-run with ${LIVE_SESSION_ACKNOWLEDGEMENT_OPTION} to record the change and keep that `
+                + "session.\n"
+                + "Stop the affected Role session first to apply it to a fresh session instead.");
         }
         if (changes.adapter) {
             const profile = findAgentProfileReference(tx, id);
@@ -273,7 +278,9 @@ function parseAgentOptions(args, mode) {
         ["--arg", { repeatable: true, allowOptionLikeValue: true }],
         ["--env", { repeatable: true, allowOptionLikeValue: false }]
     ]);
-    const flags = mode === "update" ? new Set(["--clear-args", "--clear-env"]) : new Set();
+    const flags = mode === "update"
+        ? new Set(["--clear-args", "--clear-env", LIVE_SESSION_ACKNOWLEDGEMENT_OPTION])
+        : new Set();
     const seen = new Set();
     const values = new Map();
     for (let index = 0; index < args.length; index += 1) {

package/dist/commands/controllerCommands.js

@@ -201,7 +201,7 @@ export function renderRuntimeIdentitySection(input) {
         `  Entry digest    ${build.entryDigest}`,
         `  Source commit   ${build.sourceCommit}`,
         `  Node            ${build.nodeVersion} (${build.platform})`,
-        `  Storage         layout ${storage.logicalLayout} (manifest ${storage.manifestStatus}) · backend ${storage.configuredBackend} · worker ${storage.workerEnabled ? "on" : "off"}`,
+        `  Storage         version ${storage.storageVersion} (status ${storage.storageStatus}, minimum ${storage.minimumStorageVersion}) · backend ${storage.configuredBackend} · worker ${storage.workerEnabled ? "on" : "off"}`,
         `  Store files     state.json ${storage.physicalStateJson.present ? "present" : "absent"} · yui.db ${storage.physicalDatabase.present ? "present" : "absent"}${storage.physicalDatabase.wal ? " +WAL" : ""}${storage.physicalDatabase.present && storage.physicalDatabase.health !== UNSUPPORTED ? ` (${storage.physicalDatabase.health})` : ""}`
     ];
     for (const finding of storage.findings) {

package/dist/commands/globalRoleCommands.js

@@ -5,9 +5,9 @@ import { defaultTableWidth, renderTable } from "../output/table.js";
 import { activeRoleSummary, renderRoleDetails } from "../output/rolePresentation.js";
 import { activeRoleAgentBinding, createGlobalRole, createRoleAgentBinding, switchActiveRoleAgent, unbindRoleAgent, updateGlobalRole } from "../role/role.js";
 import { isSystemRoleName, SYSTEM_ROLE_NAMES, systemRoleDescription } from "../role/systemRoles.js";
-import { hasAgentConfigOptions, parseRoleOptions, patchRoleAgentBinding, roleOptionSpecs, roleProfileFrom, roleProfilePatch } from "./roleConfiguration.js";
+import { hasAgentConfigOptions, hasNoRoleMutation, parseRoleOptions, patchRoleAgentBinding, roleOptionSpecs, roleProfileFrom, roleProfilePatch } from "./roleConfiguration.js";
 import { hasRoleLaunchContextOptions, validateConfiguredRoleSkills } from "./roleSkillValidation.js";
-import { assertRoleRuntimeMutationAllowed } from "./roleRuntimeGuard.js";
+import { assertLiveRoleSessionAcknowledged, assertRoleRuntimeMutationAllowed, LIVE_SESSION_ACKNOWLEDGEMENT_OPTION } from "./roleRuntimeGuard.js";
 export function runGlobalRoleCommand(args, store, options = {}) {
     const [command, ...rest] = args;
     switch (command) {
@@ -175,7 +175,7 @@ function updateRole(args, store, options) {
     if (parsed.has("--workspace") && trimmed(parsed.one("--workspace")) === undefined) {
         throw usageError("--workspace is required.");
     }
-    if ([...parsed.seen].every((option) => option === "--agent")) {
+    if (hasNoRoleMutation(parsed)) {
         throw usageError("At least one role update option is required.");
     }
     const workspace = trimmed(parsed.one("--workspace"));
@@ -188,6 +188,14 @@ function updateRole(args, store, options) {
                 scope: "global",
                 roleName: role.name
             }, "desired launch configuration update");
+            assertLiveRoleSessionAcknowledged({
+                sessions: tx.getGlobalRoleSessionSet(role.name),
+                roleName: role.name,
+                desiredRevision: role.launchRevision,
+                acknowledged: parsed.has(LIVE_SESSION_ACKNOWLEDGEMENT_OPTION),
+                stopCommand: "yui session stop --all",
+                endsSession: workspace !== undefined && workspace !== role.workspace
+            });
         }
         let bindings = role.agentBindings;
         if (changesAgentConfig) {

package/dist/commands/roleConfiguration.js

@@ -42,6 +42,12 @@ const AGENT_CONFIG_OPTIONS = new Set([
     ...AGENT_REPEATABLE_OPTIONS.map(([option]) => option),
     ...AGENT_CLEAR_OPTIONS.map(([option]) => option)
 ]);
+/** Options that select a target or acknowledge a fact instead of changing the Role. */
+const NON_MUTATING_OPTIONS = ["--agent", "--yes"];
+/** Whether the parsed options change nothing about the Role itself. */
+export function hasNoRoleMutation(parsed) {
+    return [...parsed.seen].every((option) => NON_MUTATING_OPTIONS.includes(option));
+}
 export function roleOptionSpecs(input) {
     const agentValueOptions = input.agentOptions === "execution"
         ? AGENT_VALUE_OPTIONS.filter(([option]) => option === "--model" || option === "--effort")
@@ -57,6 +63,7 @@ export function roleOptionSpecs(input) {
     return new Map([
         ...(input.includeAgent === true ? [["--agent", "value"]] : []),
         ...(input.includeWorkspace === true ? [["--workspace", "value"]] : []),
+        ...(input.update ? [["--yes", "flag"]] : []),
         ...PROFILE_OPTIONS,
         ...agentValueOptions,
         ...agentRepeatableOptions,

package/dist/commands/roleRuntimeGuard.js

@@ -1,4 +1,5 @@
 import { usageError } from "../errors/cliError.js";
+import { activeLiveRoleAgentSession } from "../executor/agentExecutor.js";
 import { hasRuntimeLifecycleWork, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
 /**
  * Runtime launch reservation and cleanup are ownership obligations for a Role
@@ -10,3 +11,32 @@ export function assertRoleRuntimeMutationAllowed(store, owner, action) {
         return;
     throw usageError(`Role ${action} is blocked while a runtime lifecycle transition is pending or processing.`);
 }
+export const LIVE_SESSION_ACKNOWLEDGEMENT_OPTION = "--yes";
+/**
+ * A live native Session keeps the launch configuration it started with. Changing
+ * the desired configuration is therefore a decision about the next Host
+ * activation, and the Agent making the change is the one that knows whether the
+ * running Session should keep going or be replaced. Report that fact once, here,
+ * instead of refusing the Turn that later resumes the Session.
+ */
+export function assertLiveRoleSessionAcknowledged(input) {
+    if (input.acknowledged)
+        return;
+    const session = activeLiveRoleAgentSession(input.sessions);
+    if (session === null)
+        return;
+    throw usageError([
+        input.endsSession === true
+            ? `Role ${input.roleName} has a live native Session that cannot continue after this `
+                + "change; its next Turn will need a new Session."
+            : `Role ${input.roleName} has a live native Session, so this change applies to its `
+                + "next Host activation instead of the running one.",
+        `  Agent: ${session.agentId} (${session.adapterId})`,
+        `  Native Session: ${session.nativeSessionId}`,
+        `  Host activation: ${session.runtimeGenerationId ?? "not recorded"}`,
+        `  Session launched from desired revision r${session.effective.sourceDesiredRevision}; `
+            + `current desired revision r${input.desiredRevision}`,
+        `Re-run with ${LIVE_SESSION_ACKNOWLEDGEMENT_OPTION} to record the change and keep the Session.`,
+        `Run \`${input.stopCommand}\` first to apply it to a fresh Session instead.`
+    ].join("\n"));
+}

package/dist/commands/taskCommands.js

@@ -50,9 +50,9 @@ import { projectWorkItemExecution } from "../execution/workItemExecutionProjecti
 import { sameTaskFinalReviewContract, taskFinalReviewConfig, validateTaskFinalReviewContract } from "../review/taskFinalReviewContract.js";
 import { resolveRecordedTaskFinalReviewContract } from "../review/taskFinalReviewContractResolution.js";
 import { managedWorkspaceKey } from "../worktree/managedWorkspace.js";
-import { hasAgentConfigOptions, parseRoleOptions, patchRoleAgentBinding, roleOptionSpecs, roleProfilePatch } from "./roleConfiguration.js";
+import { hasAgentConfigOptions, hasNoRoleMutation, parseRoleOptions, patchRoleAgentBinding, roleOptionSpecs, roleProfilePatch } from "./roleConfiguration.js";
 import { hasRoleLaunchContextOptions, validateConfiguredRoleSkills } from "./roleSkillValidation.js";
-import { assertRoleRuntimeMutationAllowed } from "./roleRuntimeGuard.js";
+import { assertLiveRoleSessionAcknowledged, assertRoleRuntimeMutationAllowed, LIVE_SESSION_ACKNOWLEDGEMENT_OPTION } from "./roleRuntimeGuard.js";
 import { runTaskContextCommand } from "./taskContextCommand.js";
 import { runTaskNextActionCommand } from "./taskNextActionCommand.js";
 import { runDeliveryGuardPreflight, withGuardWarnings } from "./deliveryGuardPreflight.js";
@@ -1643,7 +1643,7 @@ function updateTaskRole(args, store, options) {
     if (parsed.has("--agent") && (parsed.one("--agent")?.trim().length ?? 0) === 0) {
         throw usageError("--agent is required.", usage);
     }
-    if ([...parsed.seen].every((option) => option === "--agent")) {
+    if (hasNoRoleMutation(parsed)) {
         throw usageError("At least one role update option is required.", usage);
     }
     const now = clock(options);
@@ -1660,6 +1660,13 @@ function updateTaskRole(args, store, options) {
                 taskId: task.id,
                 roleName: role.name
             }, "desired launch configuration update");
+            assertLiveRoleSessionAcknowledged({
+                sessions: tx.getTaskRoleSessionSet(task.id, role.name),
+                roleName: role.name,
+                desiredRevision: role.launchRevision,
+                acknowledged: parsed.has(LIVE_SESSION_ACKNOWLEDGEMENT_OPTION),
+                stopCommand: `yui task role session stop ${task.id} ${role.name} --reason "<decision>"`
+            });
         }
         const profileId = parsed.one("--profile");
         const agentProfile = profileId === undefined

package/dist/controller/fileSchedulerStoreAdapter.js

@@ -9,7 +9,7 @@ import { buildTaskWakeEnvelope } from "../context/wakeNotification.js";
 import { createTaskWake, fallbackWakeCursor, latestTaskWake } from "../scheduler/taskWake.js";
 import { answerInputRequest } from "../input/inputRequest.js";
 import { activeRoleAgentBinding } from "../role/role.js";
-import { effectiveLaunchWithTaskMainWorkspace, effectiveLaunchSnapshotsCompatible, effectiveLaunchSnapshotsCompatibleForTaskSession, resolveEffectiveLaunch, validateEffectiveLaunchSnapshot } from "../executor/effectiveLaunch.js";
+import { effectiveLaunchWithTaskMainWorkspace, roleSessionMayContinue, resolveEffectiveLaunch, validateEffectiveLaunchSnapshot } from "../executor/effectiveLaunch.js";
 import { SYSTEM_OPERATOR_ROLE } from "../role/systemRoles.js";
 import { appendTurnInput, createTurn } from "../turn/turn.js";
 import { transportAgentResult } from "../domain/agentResultTransport.js";
@@ -2603,7 +2603,7 @@ function recordTaskRuntimeNativeSession(store, input, now) {
     const effective = input.effective === undefined
         ? resolvedEffective
         : validateEffectiveLaunchSnapshot(input.effective);
-    if (!effectiveLaunchSnapshotsCompatibleForTaskSession(resolvedEffective, effective)) {
+    if (!roleSessionMayContinue(resolvedEffective, effective)) {
         throw new Error("Reserved native Session effective launch changed before persistence.");
     }
     if (effective.agentId !== input.agentId || effective.adapterId !== input.adapterId) {
@@ -2636,7 +2636,7 @@ function recordGlobalRuntimeNativeSession(store, input, now) {
     const effective = input.effective === undefined
         ? resolvedEffective
         : validateEffectiveLaunchSnapshot(input.effective);
-    if (!effectiveLaunchSnapshotsCompatible(resolvedEffective, effective)) {
+    if (!roleSessionMayContinue(resolvedEffective, effective)) {
         throw new Error("Reserved global native Session effective launch changed before persistence.");
     }
     if (effective.agentId !== input.agentId || effective.adapterId !== input.adapterId) {
@@ -2719,7 +2719,7 @@ function taskSessionEffective(store, taskId, roleName, agentId, existing) {
             throw new Error(`Native Session registration does not match the effective Turn Agent: ${taskId}/${roleName}.`);
         }
         if (existing !== undefined) {
-            if (!effectiveLaunchSnapshotsCompatibleForTaskSession(existing.effective, active.effective)) {
+            if (!roleSessionMayContinue(existing.effective, active.effective)) {
                 throw new Error(`Native Session effective launch does not match the active Turn: ${taskId}/${roleName}.`);
             }
             return existing.effective;

package/dist/controller/runtime.js

@@ -1,5 +1,4 @@
 import { reconciliationIntervalMilliseconds, resolveAgentLaunchInactivityTimeoutSeconds, resolveControllerTaskConcurrency, resolveDeliveryTimeoutSeconds, resolveRuntimeHealth, resolveTmuxBin, resolveTmuxHistoryLimit } from "../config/yuiConfig.js";
-import { createHash } from "node:crypto";
 import { resolve } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { controllerSocketPath } from "../core/controllerEndpoint.js";
@@ -7,9 +6,9 @@ import { AGENT_OPERATIONAL_ENVIRONMENT_NAMES, nativeAgentEnvironmentNames, YUI_M
 import { hasRuntimeCleanupObligation, runtimeLifecycleSignalKey, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
 import { agentProcessReadinessProbe, ExecutorRegistry } from "../executor/executorRegistry.js";
 import { activeLiveRoleAgentSession, roleAgentSessionResumeMode } from "../executor/agentExecutor.js";
-import { effectiveLaunchSnapshotsCompatible, effectiveLaunchSnapshotsCompatibleForTaskSession, effectiveLaunchConfig, resolveEffectiveLaunch } from "../executor/effectiveLaunch.js";
+import { roleSessionMayContinue, effectiveLaunchConfig, resolveEffectiveLaunch } from "../executor/effectiveLaunch.js";
 import { AgentConfigurationCatalogService, validateAgentLaunchConfiguration } from "../executor/agentConfigurationCatalog.js";
-import { isTaskOwnedWorkspace, managedWorkspaceIdentity, sameManagedWorkspaceIdentity } from "../worktree/managedWorkspace.js";
+import { isTaskOwnedWorkspace, sameManagedWorkspaceIdentity } from "../worktree/managedWorkspace.js";
 import { FileRoleLaunchPlanner } from "../executor/fileRoleLaunchPlanner.js";
 import { openCurrentTaskStore } from "../storage/currentTaskStore.js";
 import { SqliteTaskStore } from "../storage/sqliteStore.js";
@@ -216,7 +215,6 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
         assertCurrent: (request) => {
             assertRuntimeLaunchRequestCurrent(store, request);
         },
-        launchFingerprint: (request) => (runtimeLaunchFingerprint(store, request)),
         onCleanupRequired: signalRuntimeCleanup,
         runtimeIsolation
     });
@@ -501,7 +499,6 @@ export function createRuntimeLifecycleDispatcher(store, schedulerStore, sessionH
             assertCurrent: (request) => {
                 assertRuntimeLaunchRequestCurrent(store, request);
             },
-            launchFingerprint: (request) => (runtimeLaunchFingerprint(store, request)),
             onCleanupRequired
         });
     const lifecycleTails = new Map();
@@ -862,11 +859,15 @@ function assertRuntimeLaunchRequestCurrent(store, request) {
             || session.nativeSessionId !== request.nativeSessionId) {
             throw new Error(`Native session changed: ${request.owner.roleName}.`);
         }
-        const sessionEffectiveCompatible = request.owner.scope === "task"
-            ? effectiveLaunchSnapshotsCompatibleForTaskSession(session.effective, request.effective)
-            : effectiveLaunchSnapshotsCompatible(session.effective, request.effective);
-        if (!sessionEffectiveCompatible) {
-            throw new Error(`Native session effective launch changed: ${request.owner.roleName}.`);
+        // The Role's durable Session record is the only authority for which Host
+        // activation may be restored. Targeting anything else would revive a
+        // historical activation.
+        if (request.hostActivationId !== undefined
+            && session.runtimeGenerationId !== request.hostActivationId) {
+            throw new Error(`Session restore does not target the Role's current Host activation: ${request.owner.roleName}.`);
+        }
+        if (!roleSessionMayContinue(session.effective, request.effective)) {
+            throw new Error(`Native session cannot continue under this launch: ${request.owner.roleName}.`);
         }
     }
 }
@@ -888,21 +889,6 @@ function currentDesiredEffective(store, request, role) {
         ...(item === null ? {} : { workItemWriteProjectIds: item.writeProjectIds })
     });
 }
-function runtimeLaunchFingerprint(store, request) {
-    const agent = store.getConfiguredAgent(request.effective.agentId);
-    if (agent === null) {
-        throw new Error(`Agent no longer exists: ${request.effective.agentId}.`);
-    }
-    return createHash("sha256").update(JSON.stringify([
-        request.owner,
-        request.effective,
-        request.managedWorkspace === undefined
-            ? undefined
-            : managedWorkspaceIdentity(request.managedWorkspace),
-        request.runtimePolicy,
-        agent
-    ])).digest("hex");
-}
 function currentDesiredManagedWorkspace(store, taskId, roleName) {
     const item = store.listWorkItems(taskId).find((candidate) => (candidate.assignee === roleName
         && !["completed", "failed", "retired"].includes(candidate.status))) ?? null;