@zq-silk/yui 0.15.0 → 0.15.1

package/README.md

@@ -15,6 +15,10 @@ execution and continuity, but they are not competing sources of Task truth.
 
 The current implementation restores the useful Role/Agent/session and CLI framework without restoring the later data-maintenance, lease, schedule, and recovery-ledger systems.
 
+The [target architecture handbook](docs/architecture/README.md) preserves the
+2026-09-06 design baseline for the upcoming refactor; it does not describe
+already implemented behavior.
+
 ## Requirements
 
 - Node.js 20.17+, 22.9+, or 24.x
@@ -599,7 +603,11 @@ future launch. Each Turn and native Role Session stores the complete actual
 agent, adapter, model, effort, Profile access intent, exact writable Projects,
 permission strategy and native options, workspace, context, and source desired revision. Updating,
 switching, or clearing Role overrides never
-hot-mutates an existing process. `task context`, Role views, Turn history,
+hot-mutates an existing process. When the Role has a live Session,
+`task role update`, `config role update`, and `config agent update` report that
+Session once and require `--yes`, so the change is recorded in the knowledge
+that it applies to the next activation; stopping the Session applies it
+immediately instead. `task context`, Role views, Turn history,
 Events, and Web show desired/effective revisions, Profile intent, permission, and
 pending next-launch drift.
 
@@ -909,7 +917,11 @@ Session/Driver lifecycle facts.
 Global Operator and global Role sessions remain native interactive CLIs. Codex
 connects that TUI to the default shared App Server, so the same thread can move
 between Yui and Desktop without transferring a rollout writer or losing its
-Global Context entry:
+Global Context entry. A thin Host in the same pane transparently forwards the
+native TUI's App Server connection and acknowledges its exact `thread/start`
+or `thread/resume` response. Yui records that Thread ID before the first user
+Turn, without depending on `notify`, scanning history, or creating a bootstrap
+message. The attachment outlives Controller restarts but exits with the TUI:
 
 ```sh
 yui session enter <global-role>
@@ -934,12 +946,23 @@ running, Yui asks before stopping it and switching the conversation. On a
 cross-Agent switch, the saved model and effort are reused unless the user
 explicitly chooses to update them.
 
-The Role's active binding is desired state for the next compatible launch. A
+Window existence does not imply a running Agent: `pane_dead=0` is live and
+`pane_dead=1` is an exited, retained diagnostic pane. Status reads never delete
+that evidence, and unreadable state is an error rather than proof of exit.
+An explicit launch can rebuild the exact dead window; tmux refuses to replace
+a live pane. An unidentified live Operator still cannot be overwritten.
+
+The Role's active binding is desired state for the next launch. A
 running Turn 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. Managed
+effective snapshot even if the Role is edited or switched. Resume is refused
+only when continuation is impossible: no recoverable native Session, a
+different Agent or adapter, or a different physical workspace. Desired launch
+configuration such as model, effort, permission, Role context, Skills, or
+declared write scope shapes the next activation instead of ending the Session,
+and Turn-scoped facts such as ReviewRound identity or candidate commits never
+affect reuse. When continuation is impossible Yui starts a new Session after
+the old process has stopped and keeps the terminal Session's immutable
+effective snapshot in history. Managed
 Sessions invoke the ordinary `yui` command; their Manifest and durable
 Role/Turn fences authenticate scope while protocol and storage compatibility
 allow a CLI package or Controller upgrade in place. Exact internal callbacks
@@ -949,8 +972,9 @@ Use `yui config role unbind <global-role> <agent-id>` or `yui task role unbind <
 
 Claude session IDs are preallocated at launch. Codex discovers its native
 thread identity from App Server responses. Managed Task Turns use structured
-Provider observations for both CLIs. Global interactive Codex sessions may
-still use its `notify` callback for conversation presentation.
+Provider observations for both CLIs. Global Codex uses the native TUI's exact
+App Server startup response and the existing Host acknowledgement. Legacy
+global `notify` callbacks cannot register a Session or change its lifecycle.
 
 Automated lifecycle and delivery decisions use structured Provider events or
 supported Hook payloads, persisted identities, usage snapshots, tmux process state, receipts, and pane

package/dist/cli/commandCatalog.js

@@ -118,7 +118,7 @@ const agentChildren = [
         name: "update",
         summary: "Update a configured Agent.",
         usage: "yui config agent update <id> [--adapter <adapter>] [--command <command>] [--arg <arg> ... | --clear-args] [--env TARGET=PROCESS_NAME ... | --clear-env]",
-        options: ["--adapter", "--command", "--arg", "--clear-args", "--env", "--clear-env"],
+        options: ["--adapter", "--command", "--arg", "--clear-args", "--env", "--clear-env", "--yes"],
         optionValues: { "--adapter": supportedAgentAdapterIds() },
         executableOptions: ["--command"]
     },
@@ -170,7 +170,7 @@ const roleChildren = [
         summary: "Update a global Role.",
         usage: "yui config role update <name> [profile options] [clear options]",
         options: ["--agent", "--workspace", ...roleProfileOptions, ...roleAgentOptions,
-            ...roleProfileClearOptions, ...roleAgentClearOptions],
+            ...roleProfileClearOptions, ...roleAgentClearOptions, "--yes"],
         optionValues: roleAgentOptionValues,
         fileOptions: ["--workspace"]
     },
@@ -578,7 +578,7 @@ const taskChildren = [
                 summary: "Update a Task Role; Agent settings target the named or active binding without switching it.",
                 usage: "yui task role update <task> <role> [--profile <id>] [--agent <id>] [Role and Agent settings]",
                 options: ["--profile", "--agent", ...roleProfileOptions, ...roleAgentOptions,
-                    ...roleProfileClearOptions, ...roleAgentClearOptions],
+                    ...roleProfileClearOptions, ...roleAgentClearOptions, "--yes"],
                 optionValues: roleAgentOptionValues
             },
             { name: "remove", summary: "Remove a Task Role.", usage: "yui task role remove <task> <role>" },
@@ -1132,7 +1132,7 @@ export const ROOT_COMMAND = buildNode({
                 ...CONFIG_DOMAINS.map(durableConfigDomainNode),
                 {
                     name: "agent",
-                    summary: "Manage configured native Agent CLIs; launch-setting changes require affected Sessions to be stopped.",
+                    summary: "Manage configured native Agent CLIs; launch-setting changes apply to the next Session activation.",
                     examples: ["yui config agent list", "yui config agent capabilities codex"],
                     sections: [
                         { id: "inspect", title: "Inspect", entries: ["list", "show", "capabilities"] },
@@ -1152,7 +1152,7 @@ export const ROOT_COMMAND = buildNode({
                 },
                 {
                     name: "role",
-                    summary: "Manage reusable global Roles and desired Agent launch configuration for the next compatible Session.",
+                    summary: "Manage reusable global Roles and desired Agent launch configuration for the next Host activation.",
                     examples: ["yui config role list", "yui config role show operator"],
                     sections: [
                         { id: "inspect", title: "Inspect", entries: ["list", "show"] },

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/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;

package/dist/controller/runtimeLaunchCoordinator.js

@@ -1,7 +1,7 @@
-import { createHash, randomUUID } from "node:crypto";
+import { randomUUID } from "node:crypto";
 import { runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
 import { createRuntimeBinding, RuntimeGenerationMismatchError, RuntimeHostContentionError, RuntimeLaunchError } from "../runtime/index.js";
-import { effectiveLaunchSnapshotsCompatible, validateEffectiveLaunchSnapshot } from "../executor/effectiveLaunch.js";
+import { sameEffectiveLaunch, validateEffectiveLaunchSnapshot } from "../executor/effectiveLaunch.js";
 class RuntimeBindingContractError extends Error {
     constructor(message, options) {
         super(message, options);
@@ -25,7 +25,6 @@ export class RuntimeLaunchCoordinator {
     #createGenerationId;
     #now;
     #assertCurrent;
-    #launchFingerprint;
     #onCleanupRequired;
     #runtimeIsolation;
     constructor(reservations, host, options = {}) {
@@ -34,8 +33,6 @@ export class RuntimeLaunchCoordinator {
         this.#createGenerationId = options.createGenerationId ?? randomUUID;
         this.#now = options.now ?? (() => new Date());
         this.#assertCurrent = options.assertCurrent;
-        this.#launchFingerprint = options.launchFingerprint
-            ?? defaultLaunchFingerprint;
         this.#onCleanupRequired = options.onCleanupRequired;
         this.#runtimeIsolation = options.runtimeIsolation;
     }
@@ -79,22 +76,19 @@ export class RuntimeLaunchCoordinator {
         if (request.owner.scope === "global" && request.managedWorkspace !== undefined) {
             throw new Error("A global runtime cannot use a Task ManagedWorkspace.");
         }
-        const expectedFingerprint = requireText(this.#launchFingerprint(request), "Launch fingerprint");
         const assertLaunchCurrent = () => {
             this.#assertCurrent?.(request);
             assertCurrent?.();
-            if (this.#launchFingerprint(request) !== expectedFingerprint) {
-                throw new Error(`Role or Agent launch state changed: ${request.owner.roleName}.`);
-            }
         };
-        const generationPrefix = `runtime-${expectedFingerprint}:generation:`;
         const proposedGenerationId = requireText(this.#createGenerationId(), "Launch generation id");
-        let proposedRuntimeGenerationId = `${generationPrefix}${proposedGenerationId}`;
+        // A Host activation id is an opaque durable identity, not a digest of the
+        // launch configuration. Whether a live activation may be reused is answered
+        // by the Role's durable Session record through `assertCurrent`, so launch
+        // configuration that only shapes the next activation never invalidates the
+        // current one.
+        let proposedRuntimeGenerationId = `runtime-${proposedGenerationId}`;
         let reusedConfirmedRunningHost = false;
         if (request.mode === "resume" && request.hostActivationId !== undefined) {
-            if (!request.hostActivationId.startsWith(generationPrefix)) {
-                throw new Error("Session restore targets an incompatible Host activation.");
-            }
             const inspection = await this.host.inspectOwner(request.owner);
             if (inspection.state === "unavailable" || inspection.state === "starting") {
                 throw new RuntimeLaunchError(true, request.hostActivationId, `Host activation is temporarily ${inspection.state}: ${request.owner.roleName}.`);
@@ -112,10 +106,6 @@ export class RuntimeLaunchCoordinator {
             runtimeGenerationId: proposedRuntimeGenerationId
         }, assertLaunchCurrent, this.#now());
         if (reservation.status === "existing") {
-            if (!reservation.runtimeGenerationId.startsWith(generationPrefix)) {
-                this.#requireCleanup(request.owner);
-                throw new Error(`Runtime launch reservation belongs to stale Role or Agent state: ${request.owner.roleName}.`);
-            }
             const inspection = await this.host.inspectOwner(request.owner);
             if (inspection.state === "unavailable" || inspection.state === "starting") {
                 throw new RuntimeLaunchError(true, reservation.runtimeGenerationId, `Runtime is temporarily ${inspection.state}: ${request.owner.roleName}/${reservation.runtimeGenerationId}.`);
@@ -416,7 +406,7 @@ function validateRuntimeLaunchPreflight(preflight, request, runtimeGenerationId)
         || preflight.turnId !== request.turnId
         || preflight.agentId !== request.agentId
         || preflight.adapterId !== request.adapterId
-        || !effectiveLaunchSnapshotsCompatible(preflight.effective, request.effective)
+        || !sameEffectiveLaunch(preflight.effective, request.effective)
         || (request.mode === "resume"
             && preflight.nativeSessionId !== request.nativeSessionId)) {
         throw new Error(`Session host pre-start launch fence does not match the requested runtime: ${request.owner.roleName}.`);
@@ -445,17 +435,6 @@ function requireMatchingRuntimeBinding(raw, request, runtimeGenerationId) {
     }
     return binding;
 }
-function defaultLaunchFingerprint(request) {
-    return createHash("sha256").update(JSON.stringify([
-        request.owner,
-        request.agentId,
-        request.adapterId,
-        request.effective,
-        request.workspace,
-        request.managedWorkspace,
-        request.runtimePolicy
-    ])).digest("hex");
-}
 function requireText(value, label) {
     if (typeof value !== "string"
         || value.length === 0

package/dist/controller/sessionNotify.js

@@ -7,6 +7,11 @@ import { openCurrentTaskStore } from "../storage/currentTaskStore.js";
 /** Hidden CLI entrypoint used by Codex's structured notify hook. */
 export async function runSessionNotifyCommand(payloadArgument, environment = process.env, call, setThreadName = setCodexThreadName) {
     const params = parseCodexSessionNotification(payloadArgument, environment);
+    // Old global TUIs can still emit their invocation-local hook. It is not
+    // evidence of a shared-daemon Thread's identity or process lifecycle.
+    // Global identity is committed from App Server at successful host start.
+    if (params.scope === "global")
+        return;
     const home = requireText(environment.YUI_HOME, "YUI_HOME");
     // A Codex process outlives its Turn, so the notify envelope cannot say which
     // Turn or runtime generation is current. Durable Session state answers both;

package/dist/executor/agentExecutor.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { hasRecentTurnId, rememberRecentTurnId, validateRecentTurnIds } from "../runtime/recentTurnIds.js";
-import { effectiveLaunchSnapshotsCompatible, effectiveLaunchSnapshotsCompatibleForTaskSession, validateEffectiveLaunchSnapshot } from "./effectiveLaunch.js";
+import { roleSessionMayContinue, validateEffectiveLaunchSnapshot } from "./effectiveLaunch.js";
 import { currentProviderActivation, endProviderActivation, settleProviderTurn, settleProviderTurnSubmission, validateProviderRuntimeBinding } from "../runtime/providerRuntimeIdentity.js";
 import { builtinDriverIdForAdapter } from "../runtime/builtinAgentDrivers.js";
 export function createRoleSessionSet(owner, activeAgentId, now) {
@@ -66,10 +66,9 @@ export function recordRoleAgentSession(set, input, now) {
         throw new Error(`Role Agent session effective identity is inconsistent: ${agentId}.`);
     }
     if (existing !== undefined && existing.nativeSessionId === nativeSessionId
-        && !effectiveLaunchSnapshotsCompatible(existing.effective, effective)
-        && !(set.owner.scope === "task"
-            && effectiveLaunchSnapshotsCompatibleForTaskSession(existing.effective, effective))) {
-        throw new Error(`Role Agent session effective launch cannot change: ${agentId}.`);
+        && !roleSessionMayContinue(existing.effective, effective)) {
+        throw new Error(`Role Agent session cannot continue under this launch: ${agentId}. `
+            + "Its Agent, adapter or physical workspace changed.");
     }
     if (existing !== undefined && existing.nativeSessionId !== nativeSessionId
         && existing.status === "active") {
@@ -280,13 +279,11 @@ export function roleAgentSessionResumeMode(set, agentId, desired) {
     if (session.status === "ended") {
         return "new";
     }
-    const compatible = set.owner.scope === "task"
-        ? effectiveLaunchSnapshotsCompatibleForTaskSession(session.effective, desired)
-        : effectiveLaunchSnapshotsCompatible(session.effective, desired);
-    if (compatible)
+    if (roleSessionMayContinue(session.effective, desired))
         return "resume";
-    throw new Error(`Role Agent session is incompatible with the next effective launch: ${agentId}. `
-        + "Stop the existing native process before starting a fresh Session.");
+    throw new Error(`Role Agent session cannot continue under the next launch: ${agentId}. `
+        + "Its Agent, adapter or physical workspace changed; stop the existing native "
+        + "process before starting a fresh Session.");
 }
 export function bindTaskRoleProviderRuntime(set, binding, updatedAt) {
     validateRoleSessionSet(set);