@runuai/host 0.9.146 → 0.9.148

package/lib/orchestrator.ts

@@ -34,6 +34,11 @@ import { getDb, schema } from "./db";
 import { mockAgentFactory } from "./agents/mock";
 import { realAgentFactory } from "./agents/factory";
 import { resolveAgentMode } from "./agents/mode";
+import {
+  clearPersistedCodexThread,
+  persistedAgentIds,
+  stopPersistedAgentSession,
+} from "./agents/session-state";
 import {
   type AgentEvent,
   type AgentSession,
@@ -223,14 +228,27 @@ interface Channel {
   /** Sessions that loaded MCP config before the latest rewrite. Busy sessions
    *  stay here until their turn completes; each id is recycled exactly once. */
   browserStaleSessions: Set<string>;
+  /** Launch-setting edits reuse the idle-safe stale-session path, but carry
+   *  their own lifecycle so only those replacements emit agent.session. */
+  rosterSessionChanges: Map<string, RosterSessionChange>;
   /** Browser-config rewrites whose install/config preconditions are not ready
    *  yet. These sessions must eventually reload the definition, but recycling
    *  them before the browser is usable only trades one broken session for
    *  another. */
   browserPendingStaleSessions: Set<string>;
+  /** Engine kinds newly covered by an already-enabled browser setup. The
+   * aggregate setup result can then recycle only sessions for those kinds. */
+  browserConfigAffectedKinds: Set<string>;
   /** One reconcile loop per channel. It covers ordinary missing agents and
    *  stale-session recycling without overlapping factory creates. */
   reconcileReady: Promise<void> | null;
+  /** Forced removal closes begun by refreshChannel. ensureSessions joins this
+   *  fence before spawning so one outbox consumer cannot overlap another. */
+  rosterRefreshReady: Promise<void> | null;
+  /** First-start cleanup of durable rows whose ids are absent from the fresh
+   *  cloud roster (the host may have restarted after their removal). */
+  persistedRosterChecked: boolean;
+  persistedRosterReady: Promise<void> | null;
   /** A reconcile request that arrived while the loop was in flight. */
   reconcileAgain: boolean;
   /** Set before teardown awaits anything. Every async continuation checks both
@@ -260,6 +278,14 @@ interface Channel {
    *  turn_complete is flagged `aborted` so the cloud DISCARDS the buffered
    *  half-turn instead of delivering it to @-mentioned peers. */
   interrupted: Set<string>;
+  /** Cloud turn boundaries whose runner generation was retired by recovery.
+   *  Kept separately from activeTurns because remove/edit may overtake the
+   *  async recovery after generation-local turn state has been cleared. */
+  retiredTurnBoundaries: Set<string>;
+  /** Async account recoveries fenced by roster removal/edit. A same-settings
+   * remove/re-add is invisible to launch-tuple comparison, so the recovery
+   * itself carries the supersession bit until it releases the spawn slot. */
+  recoveryByAgent: Map<string, RecoveryFence>;
   /** Per-agent respawn counter — bounded so a broken agent can't
    *  loop forever rewriting its config. */
   respawns: Map<string, number>;
@@ -288,6 +314,9 @@ interface Channel {
   mcpConfigDirtyEpoch: number;
   /** Dirty epoch covered by the last successful gateway publication. */
   mcpConfigAppliedEpoch: number;
+  /** Engine kinds whose provisioned config directories dirtied the managed
+   * gateway files at the current unapplied epoch. */
+  mcpProvisionAffectedKinds: Set<string>;
   /** Monotonic version of the managed config files agent processes read at
    *  startup. A factory create that straddles a rewrite is discarded and
    *  retried before it can be bound as the live generation. */
@@ -309,6 +338,9 @@ interface Channel {
    *  drains them so an old channel cannot resume against a reused container
    *  name and overwrite the replacement generation's durable transport. */
   factoryOperations: Set<Promise<unknown>>;
+  /** The create currently owning an agent id, used to fence a removal until a
+   *  stale in-flight process has observed the new roster and closed itself. */
+  factoryOperationByAgent: Map<string, Promise<AgentSession | null>>;
   /** Terminal-event recovery/rotation can remove a session before awaiting
    *  its close. Track the enclosing handler so teardown still drains that
    *  external operation before the container name can be reused. */
@@ -328,6 +360,16 @@ interface AcceptedPrompt {
   text: string;
 }
 
+interface RosterSessionChange {
+  reason: string;
+  state: "pending-close" | "restarting";
+  abortPublished: boolean;
+}
+
+interface RecoveryFence {
+  superseded: boolean;
+}
+
 /** Hard cap on automatic respawns per agent per channel lifetime. */
 const MAX_RESPAWNS_PER_AGENT = 5;
 /** ADR-076: hard cap on account rotations per agent between successful turns. */
@@ -545,31 +587,100 @@ export class Orchestrator {
   /** Fold a fresh channel spec into a live channel (ADR-049). */
   private refreshChannel(channel: Channel, spec: ChannelEnsureInput): void {
     const browserWasEnabled = channel.browserTesting;
+    const previousRoster = channel.roster;
     const previousMcpShape = JSON.stringify({
       connections: channel.mcpConnections,
-      kinds: [...new Set(channel.roster.map((agent) => agent.kind))].sort(),
+      kinds: [...new Set(previousRoster.map((agent) => agent.kind))].sort(),
     });
-    const known = new Set(channel.roster.map((a) => a.id));
+    const previousById = new Map(previousRoster.map((agent) => [agent.id, agent]));
+    const nextById = new Map(spec.agents.map((agent) => [agent.id, agent]));
+    const previousKinds = new Set(previousRoster.map((agent) => agent.kind));
+    const nextKinds = new Set(spec.agents.map((agent) => agent.kind));
+    const removed = previousRoster.filter((agent) => !nextById.has(agent.id));
+    const added = spec.agents.filter((agent) => !previousById.has(agent.id));
+    const changed = spec.agents.flatMap((agent) => {
+      const previous = previousById.get(agent.id);
+      if (!previous) return [];
+      const reason = rosterLaunchChangeReason(previous, agent);
+      return reason ? [{ agent, reason }] : [];
+    });
+
     // Replace EXISTING agents' data with the fresh spec — a mid-task roster edit
     // can change permissions, model, brief, role or skills, and without this the
     // stale snapshot persists (e.g. granting `uai` CLI permissions mid-task never
-    // took effect: writeAgentCli kept seeing the old empty list). Swapping the
-    // object (not merging) also drops fields that were removed. The token/model a
-    // LIVE session already carries only changes on its next respawn.
-    const bySpecId = new Map(spec.agents.map((a) => [a.id, a]));
-    channel.roster = channel.roster.map((a) => bySpecId.get(a.id) ?? a);
-    for (const agent of spec.agents) {
-      if (!known.has(agent.id)) {
-        channel.roster.push(agent);
-        // Per-agent link/document skills, like getOrCreateChannel does at
-        // channel birth. Best-effort.
-        writeAgentSkills(channel.taskId, agent);
+    // took effect: writeAgentCli kept seeing the old empty list). Replacing the
+    // array exactly also makes absence authoritative for live removal.
+    channel.roster = [...spec.agents];
+    for (const agent of added) {
+      // Per-agent link/document skills, like getOrCreateChannel does at
+      // channel birth. Best-effort.
+      writeAgentSkills(channel.taskId, agent);
+    }
+    for (const { agent, reason } of changed) {
+      const recoveryAbortPublished = this.supersedeRecovery(
+        channel,
+        agent.id,
+      );
+      // Clear before any reconcile can construct a replacement. A session can
+      // already be absent from the map while its durable runner/thread row is
+      // still live, so this must not depend on in-memory session presence.
+      try {
+        clearPersistedCodexThread(channel.taskId, agent.id);
+      } catch (err) {
+        console.warn(
+          `[orchestrator] ${channel.taskId}/${agent.id}: could not clear persisted Codex thread for roster change: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        );
       }
+      channel.accountByAgent.delete(agent.id);
+      channel.rotations.delete(agent.id);
+      // Crash/recovery budgets belong to the retired launch generation. A
+      // newly selected engine/model/effort must get an immediate clean start,
+      // not inherit the predecessor's cooldown window.
+      channel.respawns.delete(agent.id);
+      channel.respawnLastAt.delete(agent.id);
+      const priorChange = channel.rosterSessionChanges.get(agent.id);
+      channel.rosterSessionChanges.set(agent.id, {
+        reason,
+        state:
+          priorChange?.state === "restarting"
+            ? "restarting"
+            : "pending-close",
+        abortPublished:
+          priorChange?.abortPublished === true || recoveryAbortPublished,
+      });
+      channel.browserStaleSessions.add(agent.id);
+    }
+    if (removed.length > 0) {
+      const previousRefresh = channel.rosterRefreshReady ?? Promise.resolve();
+      const removals = removed.map((agent) =>
+        this.removeRosterAgent(channel, agent.id),
+      );
+      let refresh: Promise<void>;
+      refresh = Promise.allSettled([previousRefresh, ...removals])
+        .then(() => undefined)
+        .finally(() => {
+          if (channel.rosterRefreshReady === refresh) {
+            channel.rosterRefreshReady = null;
+          }
+        });
+      channel.rosterRefreshReady = refresh;
     }
     channel.humans = spec.humans ?? [];
     channel.mode = spec.mode === "secretary" ? "secretary" : "open";
     channel.secretaryAgentId = spec.secretaryAgentId;
     channel.browserTesting = spec.browserTesting === true;
+    if (channel.browserTesting) {
+      const affectedKinds = browserWasEnabled
+        ? [...nextKinds].filter((kind) => !previousKinds.has(kind))
+        : [...nextKinds];
+      for (const kind of affectedKinds) {
+        channel.browserConfigAffectedKinds.add(kind);
+      }
+    } else {
+      channel.browserConfigAffectedKinds.clear();
+    }
     channel.routingShadow = spec.routing?.shadow === true;
     channel.workspacePath = spec.workspacePath;
     channel.sharedFiles = spec.sharedFiles ?? "ro";
@@ -626,6 +737,162 @@ export class Orchestrator {
     }
   }
 
+  /** Remove every live/in-flight trace of one agent without deleting its
+   * durable session directory. Removal is intentionally immediate mid-turn. */
+  private async removeRosterAgent(
+    channel: Channel,
+    agentId: string,
+  ): Promise<void> {
+    const session = channel.sessions.get(agentId);
+    const inFlightCreate = channel.factoryOperationByAgent.get(agentId);
+    const lifecycleAtRemoval = channel.rosterSessionChanges.get(agentId);
+    channel.sessions.delete(agentId);
+    // Do not release another lifecycle owner's spawn slot. Recovery/reconcile
+    // paths clear it in their own finally blocks after rechecking the desired
+    // roster; releasing it here lets a rapid re-add start a second same-id
+    // factory while the first is still provisioning.
+
+    // Recovery may already have retired the runner-local turn state while an
+    // async provision/broker call was in flight. Consume that saved boundary
+    // before looking at the live generation's maps.
+    this.supersedeRecovery(channel, agentId);
+    this.emitRetiredTurnAbort(channel, agentId);
+    // A removed partial turn can never receive its natural terminal event.
+    // Close that cloud boundary as aborted before the old session's identity
+    // guard begins suppressing its final adapter events.
+    if (
+      channel.activeTurns.has(agentId) ||
+      channel.openTurns.has(agentId) ||
+      channel.acceptedPrompts.has(agentId)
+    ) {
+      channel.interrupted.add(agentId);
+    }
+    this.retireRunnerGeneration(channel, agentId);
+    channel.preambles.delete(agentId);
+    channel.firstTurns.delete(agentId);
+    channel.browserStaleSessions.delete(agentId);
+    channel.rosterSessionChanges.delete(agentId);
+    channel.browserPendingStaleSessions.delete(agentId);
+    channel.pendingPrompts.delete(agentId);
+    channel.runtimeDeferredPrompts.delete(agentId);
+    channel.runtimeDeferredAgents.delete(agentId);
+    channel.interrupted.delete(agentId);
+    channel.retiredTurnBoundaries.delete(agentId);
+    channel.respawns.delete(agentId);
+    channel.respawnLastAt.delete(agentId);
+    channel.everBound.delete(agentId);
+    channel.accountByAgent.delete(agentId);
+    channel.lastPrompt.delete(agentId);
+    channel.rotations.delete(agentId);
+
+    if (session) {
+      try {
+        // Delete-before-close above keeps the adapter's terminal event
+        // identity-guarded and prevents an outbox consumer overlap.
+        await session.close();
+      } catch {
+        // Already dead — close is idempotent for our adapters.
+      }
+    }
+    if (inFlightCreate) {
+      // createAndBindStableSessionCore rechecks the desired roster after the
+      // factory await and closes the stale process instead of binding it.
+      await inFlightCreate.catch(() => null);
+    }
+    if (!this.isActiveChannel(channel)) return;
+    // A newer ensure can re-add the same id while the old close/create drains.
+    // That spec owns the status now; do not stop its bound generation or emit
+    // a stale removed edge.
+    if (channel.roster.some((agent) => agent.id === agentId)) {
+      this.restoreReaddedRosterLifecycle(
+        channel,
+        agentId,
+        lifecycleAtRemoval,
+      );
+      void this.reconcileIfStarted(channel).catch((err: unknown) => {
+        console.warn(
+          `[orchestrator] ${channel.taskId}/${agentId}: re-added roster reconcile failed: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        );
+      });
+      return;
+    }
+    let durableCleanupFailed = false;
+    try {
+      await this.stopPersistedRunnerIfPresent(channel, agentId);
+    } catch (err) {
+      durableCleanupFailed = true;
+      // The same ensure that joined this removal fence will retry through the
+      // persisted-roster recovery pass instead of trusting a poisoned result.
+      channel.persistedRosterChecked = false;
+      console.warn(
+        `[orchestrator] ${channel.taskId}/${agentId}: removed durable session cleanup failed: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    }
+    if (!this.isActiveChannel(channel)) return;
+    if (channel.roster.some((agent) => agent.id === agentId)) {
+      this.restoreReaddedRosterLifecycle(
+        channel,
+        agentId,
+        lifecycleAtRemoval,
+      );
+      void this.reconcileIfStarted(channel).catch((err: unknown) => {
+        console.warn(
+          `[orchestrator] ${channel.taskId}/${agentId}: post-stop re-add reconcile failed: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        );
+      });
+      return;
+    }
+    // Slow rotation/account continuations captured before the roster swap may
+    // have reached their finally blocks while the close was in flight.
+    channel.accountByAgent.delete(agentId);
+    channel.rotations.delete(agentId);
+    channel.respawns.delete(agentId);
+    channel.respawnLastAt.delete(agentId);
+    channel.lastPrompt.delete(agentId);
+    if (!this.isActiveChannel(channel)) return;
+    if (durableCleanupFailed) return;
+    this.emitHost({
+      kind: "agent.session",
+      taskId: channel.taskId,
+      agentId,
+      state: "removed",
+    });
+    console.log(
+      `[orchestrator] ${channel.taskId}/${agentId}: stopped removed roster session`,
+    );
+  }
+
+  /** A remove superseded while an earlier edit was already restarting must
+   * still close that visible lifecycle with ready for the re-added roster. */
+  private restoreReaddedRosterLifecycle(
+    channel: Channel,
+    agentId: string,
+    removedChange: RosterSessionChange | undefined,
+  ): void {
+    if (
+      removedChange?.state !== "restarting" ||
+      channel.rosterSessionChanges.has(agentId)
+    ) {
+      return;
+    }
+    if (channel.sessions.has(agentId)) {
+      this.emitHost({
+        kind: "agent.session",
+        taskId: channel.taskId,
+        agentId,
+        state: "ready",
+      });
+      return;
+    }
+    channel.rosterSessionChanges.set(agentId, removedChange);
+  }
+
   /** Materialize a browser flag enabled after the channel already started. */
   private async enableBrowserTesting(channel: Channel): Promise<void> {
     try {
@@ -709,8 +976,13 @@ export class Orchestrator {
       browserSetupCoverage: null,
       browserRetryTimer: null,
       browserStaleSessions: new Set(),
+      rosterSessionChanges: new Map(),
       browserPendingStaleSessions: new Set(),
+      browserConfigAffectedKinds: new Set(),
       reconcileReady: null,
+      rosterRefreshReady: null,
+      persistedRosterChecked: false,
+      persistedRosterReady: null,
       reconcileAgain: false,
       closed: false,
       openTurns: new Set(),
@@ -720,6 +992,8 @@ export class Orchestrator {
       runtimeDeferredPrompts: new Map(),
       runtimeDeferredAgents: new Set(),
       interrupted: new Set(),
+      retiredTurnBoundaries: new Set(),
+      recoveryByAgent: new Map(),
       respawns: new Map(),
       respawnLastAt: new Map(),
       humans: spec.humans ?? [],
@@ -729,12 +1003,14 @@ export class Orchestrator {
       mcpConfigWrite: null,
       mcpConfigDirtyEpoch: 1,
       mcpConfigAppliedEpoch: 0,
+      mcpProvisionAffectedKinds: new Set(),
       configGeneration: 0,
       spawning: new Set(),
       everBound: new Set(),
       routingShadow: spec.routing?.shadow === true,
       workspacePath: spec.workspacePath,
       factoryOperations: new Set(),
+      factoryOperationByAgent: new Map(),
       eventOperations: new Set(),
       accountByAgent: new Map(),
       lastPrompt: new Map(),
@@ -761,6 +1037,58 @@ export class Orchestrator {
     // copy cannot land after browser/MCP materialization and erase config.
     await taskRecoveryComplete(channel.taskId);
     if (!this.isActiveChannel(channel)) return false;
+    if (channel.rosterRefreshReady) {
+      await channel.rosterRefreshReady;
+      if (!this.isActiveChannel(channel)) return false;
+    }
+    if (!channel.persistedRosterChecked) {
+      let removedIds: string[];
+      try {
+        const rosterIds = new Set(channel.roster.map((agent) => agent.id));
+        removedIds = persistedAgentIds(channel.taskId).filter(
+          (agentId) => !rosterIds.has(agentId),
+        );
+      } catch (err) {
+        console.warn(
+          `[orchestrator] ${channel.taskId}: persisted roster scan failed: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        );
+        throw err;
+      }
+      channel.persistedRosterChecked = true;
+      if (removedIds.length > 0) {
+        const operation = this.stopPersistedRemovedAgents(
+          channel,
+          removedIds,
+        );
+        let tracked: Promise<void>;
+        tracked = operation.then(
+          () => {
+            if (channel.persistedRosterReady === tracked) {
+              channel.persistedRosterReady = null;
+            }
+          },
+          (err: unknown) => {
+            if (channel.persistedRosterReady === tracked) {
+              channel.persistedRosterReady = null;
+              channel.persistedRosterChecked = false;
+            }
+            console.warn(
+              `[orchestrator] ${channel.taskId}: persisted roster cleanup failed: ${
+                err instanceof Error ? err.message : String(err)
+              }`,
+            );
+            throw err;
+          },
+        );
+        channel.persistedRosterReady = tracked;
+      }
+    }
+    if (channel.persistedRosterReady) {
+      await channel.persistedRosterReady;
+      if (!this.isActiveChannel(channel)) return false;
+    }
     if (!backgroundContainerWorkAllowed()) return false;
     // Memoized: every caller awaits the SAME in-flight start, so a concurrent
     // deliver() can't observe "ready" while the sessions map is still empty
@@ -825,6 +1153,48 @@ export class Orchestrator {
     return ready;
   }
 
+  /** A host restart loses the in-memory old roster, not its durable runners.
+   * Stop persisted ids that the authoritative fresh spec no longer contains. */
+  private async stopPersistedRemovedAgents(
+    channel: Channel,
+    removedIds: readonly string[],
+  ): Promise<void> {
+    const environment = await this.agentEnvironment(channel);
+    for (const agentId of removedIds) {
+      if (!this.isActiveChannel(channel)) return;
+      // The roster may have advanced while environment reconstruction was in
+      // flight. Last arrival wins; never stop an id the current spec wants.
+      if (channel.roster.some((agent) => agent.id === agentId)) continue;
+      const stoppedDir = await stopPersistedAgentSession(
+        channel.taskId,
+        agentId,
+        environment,
+      );
+      if (channel.roster.some((agent) => agent.id === agentId)) continue;
+      if (!stoppedDir || !this.isActiveChannel(channel)) continue;
+      this.emitHost({
+        kind: "agent.session",
+        taskId: channel.taskId,
+        agentId,
+        state: "removed",
+      });
+      console.log(
+        `[orchestrator] ${channel.taskId}/${agentId}: stopped removed durable session during roster recovery`,
+      );
+    }
+  }
+
+  /** Stop a durable predecessor even when its row is already marked closed.
+   * Closed is not proof of runner death: markClosed precedes the stop write. */
+  private async stopPersistedRunnerIfPresent(
+    channel: Channel,
+    agentId: string,
+  ): Promise<string | null> {
+    if (!persistedAgentIds(channel.taskId).includes(agentId)) return null;
+    const environment = await this.agentEnvironment(channel);
+    return stopPersistedAgentSession(channel.taskId, agentId, environment);
+  }
+
   /**
    * Background browser work may recycle sessions only after the memoized
    * initial start has finished. Waiting here prevents live enable/retry from
@@ -873,11 +1243,17 @@ export class Orchestrator {
   private noteProvisionMutation(
     channel: Channel,
     waitForBrowserReadiness: boolean,
+    affectedKinds: ReadonlySet<string>,
   ): void {
     if (!this.isActiveChannel(channel)) return;
     channel.configGeneration += 1;
     channel.mcpConfigDirtyEpoch += 1;
-    for (const agentId of channel.sessions.keys()) {
+    for (const kind of affectedKinds) {
+      channel.mcpProvisionAffectedKinds.add(kind);
+    }
+    for (const [agentId] of channel.sessions) {
+      const kind = channel.roster.find((agent) => agent.id === agentId)?.kind;
+      if (!kind || !affectedKinds.has(kind)) continue;
       if (waitForBrowserReadiness) {
         channel.browserPendingStaleSessions.add(agentId);
       } else {
@@ -910,6 +1286,42 @@ export class Orchestrator {
     });
   }
 
+  /** Kinds whose account-copy inputs changed since the last attempted pass. */
+  private changedProvisionKinds(
+    previousFingerprint: string | undefined,
+    nextFingerprint: string,
+    requestedKinds: readonly string[],
+  ): string[] {
+    if (!previousFingerprint) return [...requestedKinds];
+    type Fingerprint = {
+      kinds?: string[];
+      accounts?: Array<{
+        kind: string;
+        id: string;
+        hostDir: string;
+        containerDir: string;
+      }>;
+    };
+    try {
+      const previous = JSON.parse(previousFingerprint) as Fingerprint;
+      const next = JSON.parse(nextFingerprint) as Fingerprint;
+      return requestedKinds.filter((kind) => {
+        if (!previous.kinds?.includes(kind)) return true;
+        const previousAccounts = (previous.accounts ?? []).filter(
+          (account) => account.kind === kind,
+        );
+        const nextAccounts = (next.accounts ?? []).filter(
+          (account) => account.kind === kind,
+        );
+        return JSON.stringify(previousAccounts) !== JSON.stringify(nextAccounts);
+      });
+    } catch {
+      // A legacy/partial fingerprint is not trustworthy enough to narrow a
+      // write; copy and invalidate the requested kinds conservatively.
+      return [...requestedKinds];
+    }
+  }
+
   private async ensureBrowserSetup(
     channel: Channel,
     hasCodex: boolean,
@@ -936,11 +1348,20 @@ export class Orchestrator {
     ];
     const requestedProvisionFingerprint =
       this.provisionFingerprint(requestedKinds, channel.engineAccountScope);
-    const mayProvisionConfig = requestedKinds.some((kind) =>
+    const changedProvisionKinds = this.changedProvisionKinds(
+      channel.provisionAttemptedFingerprint,
+      requestedProvisionFingerprint,
+      requestedKinds,
+    );
+    const provisionKinds = forceProvision
+      ? requestedKinds
+      : changedProvisionKinds;
+    const mutableProvisionKinds = provisionKinds.filter((kind) =>
       resolveEngineAccounts(kind, {}, channel.engineAccountScope).some(
         (account) => !account.isDefault && Boolean(account.configDir),
       ),
     );
+    const mayProvisionConfig = mutableProvisionKinds.length > 0;
 
     const inFlight = channel.browserSetup;
     if (inFlight) {
@@ -1011,14 +1432,14 @@ export class Orchestrator {
             const provisioned = channel.agentHandle
               ? await provisionEngineAccounts(
                   channel.containerName,
-                  requestedKinds,
+                  provisionKinds,
                   {},
                   channel.agentHandle,
                   channel.engineAccountScope,
                 )
               : await provisionEngineAccounts(
                   channel.containerName,
-                  requestedKinds,
+                  provisionKinds,
                   {},
                   undefined,
                   channel.engineAccountScope,
@@ -1050,6 +1471,7 @@ export class Orchestrator {
                 this.noteProvisionMutation(
                   channel,
                   channel.browserTesting,
+                  new Set(mutableProvisionKinds),
                 );
               } else {
                 this.fenceConfigGeneration(channel);
@@ -1107,10 +1529,23 @@ export class Orchestrator {
       channel.browserReady = setup.ready && setup.configured;
       if (setup.changed) {
         channel.configGeneration += 1;
-        for (const agentId of channel.sessions.keys()) {
+        const affectedKinds = channel.browserConfigAffectedKinds;
+        const affectedIds =
+          affectedKinds.size > 0
+            ? channel.roster
+                .filter((agent) => affectedKinds.has(agent.kind))
+                .map((agent) => agent.id)
+            : [...channel.sessions.keys()];
+        for (const agentId of affectedIds) {
+          if (!channel.sessions.has(agentId)) continue;
           channel.browserPendingStaleSessions.add(agentId);
         }
       }
+      if (setup.configured) {
+        for (const kind of requestedKinds) {
+          channel.browserConfigAffectedKinds.delete(kind);
+        }
+      }
       if (channel.browserReady) {
         for (const agentId of channel.browserPendingStaleSessions) {
           channel.browserStaleSessions.add(agentId);
@@ -1259,6 +1694,9 @@ export class Orchestrator {
       ...(grokHomes.length > 0 ? { grokHomes } : {}),
     });
     const dirtyEpoch = channel.mcpConfigDirtyEpoch;
+    const provisionAffectedKinds = new Set(
+      channel.mcpProvisionAffectedKinds,
+    );
     const repairingProvisionedConfig =
       channel.mcpConfigAppliedEpoch !== dirtyEpoch &&
       channel.mcpConfigFingerprint === fingerprint;
@@ -1321,6 +1759,9 @@ export class Orchestrator {
     // the files while docker exec was in flight, the newer epoch remains
     // uncovered and the serialized ensure immediately publishes another pass.
     channel.mcpConfigAppliedEpoch = dirtyEpoch;
+    if (channel.mcpConfigDirtyEpoch === dirtyEpoch) {
+      channel.mcpProvisionAffectedKinds.clear();
+    }
     // Agent CLIs read MCP servers once, at process start — and durable
     // sessions (ADR-061) make processes long-lived, so without this a
     // connection added mid-task stays invisible indefinitely. Recycle IDLE
@@ -1338,7 +1779,10 @@ export class Orchestrator {
       // Provisioning marked the sessions that existed around its copy. Mark
       // again after the repair so a factory that bound during this write is
       // covered too (Set de-duplicates the earlier marks).
-      this.markSessionsStale(channel);
+      const affected = channel.roster
+        .filter((agent) => provisionAffectedKinds.has(agent.kind))
+        .map((agent) => agent.id);
+      this.markSessionsStale(channel, affected);
     } else if (!hadPrevious && hadLiveSessions) {
       this.markSessionsStale(channel);
     } else if (hadPrevious && connectionsChanged) {
@@ -1372,7 +1816,16 @@ export class Orchestrator {
   /** Close stale sessions that are idle, without recursively reconciling. */
   private async closeIdleStaleSessions(channel: Channel): Promise<number> {
     let recycled = 0;
-    for (const agentId of [...channel.browserStaleSessions]) {
+    let mcpRecycled = 0;
+    // The roster-change tracker is authoritative. Recovery paths written for
+    // ordinary config recycling may clear browserStaleSessions while an edit
+    // is waiting on their spawn slot; never let a pending-close edit bind its
+    // replacement without first publishing the actual restart boundary.
+    const staleAgentIds = new Set([
+      ...channel.browserStaleSessions,
+      ...channel.rosterSessionChanges.keys(),
+    ]);
+    for (const agentId of staleAgentIds) {
       if (!this.isActiveChannel(channel)) return recycled;
       if (
         channel.activeTurns.has(agentId) ||
@@ -1383,31 +1836,155 @@ export class Orchestrator {
       }
       const session = channel.sessions.get(agentId);
       // A session that exited on its own is already absent. Its eventual
-      // replacement is fresh, so the old generation is no longer stale.
+      // replacement is fresh for MCP purposes. A roster change still has to
+      // stop a possibly-live durable predecessor before that replacement can
+      // bind under new launch settings.
       if (!session) {
-        channel.browserStaleSessions.delete(agentId);
+        const rosterChange = channel.rosterSessionChanges.get(agentId);
+        if (rosterChange) {
+          await this.closeMissingRosterChangedSession(
+            channel,
+            agentId,
+            rosterChange,
+          );
+          recycled += 1;
+        } else {
+          channel.browserStaleSessions.delete(agentId);
+        }
         continue;
       }
       channel.browserStaleSessions.delete(agentId);
       channel.sessions.delete(agentId);
-      try {
-        // Delete before close. Event handlers are identity-guarded, so the
-        // old session's synthetic exit cannot consume respawn budget or delete
-        // the replacement that follows.
-        await session.close();
-      } catch {
-        // Already dead — close is idempotent for our adapters.
+      const rosterChange = channel.rosterSessionChanges.get(agentId);
+      if (rosterChange) {
+        await this.closeRosterChangedSession(
+          channel,
+          agentId,
+          session,
+          rosterChange,
+        );
+      } else {
+        try {
+          // Delete before close. Event handlers are identity-guarded, so the
+          // old session's synthetic exit cannot consume respawn budget or delete
+          // the replacement that follows.
+          await session.close();
+        } catch {
+          // Already dead — close is idempotent for our adapters.
+        }
+        mcpRecycled += 1;
       }
       recycled += 1;
     }
-    if (recycled > 0) {
+    if (mcpRecycled > 0) {
       console.log(
-        `[orchestrator] ${channel.taskId}: recycled ${recycled} idle session(s) for MCP config change`,
+        `[orchestrator] ${channel.taskId}: recycled ${mcpRecycled} idle session(s) for MCP config change`,
       );
     }
     return recycled;
   }
 
+  /** Stop one generation for a live launch-setting edit and publish the
+   * roster-specific lifecycle edge only if that edit still owns the id. */
+  private async closeRosterChangedSession(
+    channel: Channel,
+    agentId: string,
+    session: AgentSession,
+    change: RosterSessionChange,
+  ): Promise<void> {
+    // Durable attach cannot reconstruct whether a pre-restart runner is
+    // already mid-turn. Publish the terminal boundary before every forced
+    // launch close; it is a no-op for an actually idle cloud stream.
+    this.publishRosterChangeAbort(channel, agentId, change);
+    try {
+      await session.close();
+    } catch {
+      // Already dead — close is idempotent for our adapters.
+    }
+    try {
+      await this.stopPersistedRunnerIfPresent(channel, agentId);
+      // Clear again after close. A thread/started notification already queued
+      // by the old Codex process must not restore its resume id between the
+      // eager roster clear and replacement construction.
+      clearPersistedCodexThread(channel.taskId, agentId);
+    } catch (err) {
+      if (
+        this.isActiveChannel(channel) &&
+        channel.rosterSessionChanges.get(agentId) === change
+      ) {
+        channel.browserStaleSessions.add(agentId);
+      }
+      throw err;
+    }
+    if (
+      !this.isActiveChannel(channel) ||
+      channel.rosterSessionChanges.get(agentId) !== change ||
+      !channel.roster.some((agent) => agent.id === agentId)
+    ) {
+      return;
+    }
+    const alreadyRestarting = change.state === "restarting";
+    change.state = "restarting";
+    if (!alreadyRestarting) {
+      this.emitHost({
+        kind: "agent.session",
+        taskId: channel.taskId,
+        agentId,
+        state: "restarting",
+      });
+    }
+    console.log(
+      `[orchestrator] ${channel.taskId}/${agentId}: recycled session for live roster ${change.reason}`,
+    );
+  }
+
+  /** Finish a launch edit whose adapter already disappeared, but whose
+   * durable predecessor may still own the CLI process/outbox. */
+  private async closeMissingRosterChangedSession(
+    channel: Channel,
+    agentId: string,
+    change: RosterSessionChange,
+  ): Promise<void> {
+    this.publishRosterChangeAbort(channel, agentId, change);
+    const stoppedDir = await this.stopPersistedRunnerIfPresent(channel, agentId);
+    clearPersistedCodexThread(channel.taskId, agentId);
+    if (
+      !this.isActiveChannel(channel) ||
+      channel.rosterSessionChanges.get(agentId) !== change ||
+      !channel.roster.some((agent) => agent.id === agentId)
+    ) {
+      return;
+    }
+    channel.browserStaleSessions.delete(agentId);
+    if (!stoppedDir) {
+      // No old generation exists to recycle (one-shot engines between turns,
+      // crash cooldown, or an agent not spawned yet). The cloud set the row to
+      // Restarting when it persisted the edit, so clear that status now even
+      // though there is no close/restart edge to publish first.
+      channel.rosterSessionChanges.delete(agentId);
+      this.emitHost({
+        kind: "agent.session",
+        taskId: channel.taskId,
+        agentId,
+        state: "ready",
+      });
+      return;
+    }
+    const alreadyRestarting = change.state === "restarting";
+    change.state = "restarting";
+    if (!alreadyRestarting) {
+      this.emitHost({
+        kind: "agent.session",
+        taskId: channel.taskId,
+        agentId,
+        state: "restarting",
+      });
+    }
+    console.log(
+      `[orchestrator] ${channel.taskId}/${agentId}: stopped detached durable session for live roster ${change.reason}`,
+    );
+  }
+
   /** Serialize all missing-session and stale-session reconciliation. */
   private async reconcileSessions(channel: Channel): Promise<void> {
     if (!this.isActiveChannel(channel)) return;
@@ -1520,6 +2097,10 @@ export class Orchestrator {
           // Another recovery path may have filled this slot while the browser
           // setup was awaiting.
           if (channel.sessions.has(agent.id)) continue;
+          if (!this.hasDesiredLaunchSettings(channel, agent.id, agent)) {
+            channel.reconcileAgain = true;
+            continue;
+          }
           const session = await this.createAndBindStableSession(
             channel,
             agent.id,
@@ -1530,7 +2111,7 @@ export class Orchestrator {
               executionProfile: this.executionProfileFor(channel, agent.id),
               attachCompatibilityKey: this.attachCompatibilityKeyFor(
                 channel,
-                agent.id,
+                agent,
               ),
               agentEnv: this.accountAgentEnv(
                 channel,
@@ -1571,16 +2152,30 @@ export class Orchestrator {
 
   private attachCompatibilityKeyFor(
     channel: Channel,
-    agentId: string,
+    agent: RosterAgent,
   ): string | undefined {
-    if (!this.isSecretary(channel, agentId)) return undefined;
     // Key the durable runner to the policy actually passed to the adapter.
     // The restricted profile is dormant today, but giving it the normal-tools
     // generation would make a future opt-out able to attach a runner launched
     // under tool denial.
-    return this.executionProfileFor(channel, agentId) === "communicator"
-      ? RESTRICTED_SECRETARY_SESSION_ATTACH_KEY
-      : SECRETARY_SESSION_ATTACH_KEY;
+    const policy = this.isSecretary(channel, agent.id)
+      ? this.executionProfileFor(channel, agent.id) === "communicator"
+        ? RESTRICTED_SECRETARY_SESSION_ATTACH_KEY
+        : SECRETARY_SESSION_ATTACH_KEY
+      : undefined;
+    const model = agent.model ?? "";
+    const effort = agent.effort ?? "";
+    // Preserve legacy null/policy-only attachment for agents that choose no
+    // launch flags. Explicit model/effort gets a stable key so a host restart
+    // cannot attach a runner created under different settings.
+    if (!model && !effort) return policy;
+    return JSON.stringify([
+      "roster-launch-v1",
+      agent.kind,
+      model,
+      effort,
+      policy ?? "",
+    ]);
   }
 
   private isSecretary(channel: Channel, agentId: string): boolean {
@@ -1618,6 +2213,10 @@ export class Orchestrator {
      *  container env to carry it. The account's env and the uai base win. */
     floor: Record<string, string> = {},
   ): Record<string, string> {
+    if (!this.hasDesiredLaunchSettings(channel, agent.id, agent)) {
+      channel.accountByAgent.delete(agent.id);
+      return { ...floor, ...base };
+    }
     const account = pickEngineAccount(agent.kind, {
       scope: channel.engineAccountScope,
     });
@@ -1662,6 +2261,18 @@ export class Orchestrator {
   ): void {
     channel.sessions.set(agentId, session);
     channel.everBound.add(agentId);
+    const rosterChange = channel.rosterSessionChanges.get(agentId);
+    if (rosterChange) {
+      channel.rosterSessionChanges.delete(agentId);
+      if (rosterChange.state === "restarting") {
+        this.emitHost({
+          kind: "agent.session",
+          taskId: channel.taskId,
+          agentId,
+          state: "ready",
+        });
+      }
+    }
     // The launch screen's `ready` rides the bind, not the tail of the start
     // loop: whichever path brings the last roster agent up — the initial
     // start, a reconcile that won the race with it, a respawn after Resume —
@@ -1729,16 +2340,29 @@ export class Orchestrator {
     channel: Channel,
     agentId: string,
     args: Omit<Parameters<AgentSessionFactory["create"]>[0], "environment">,
+    recovery?: RecoveryFence,
   ): Promise<AgentSession | null> {
     const operation = this.createAndBindStableSessionCore(
       channel,
       agentId,
       args,
+      recovery,
     );
     channel.factoryOperations.add(operation);
+    channel.factoryOperationByAgent.set(agentId, operation);
     operation.then(
-      () => channel.factoryOperations.delete(operation),
-      () => channel.factoryOperations.delete(operation),
+      () => {
+        channel.factoryOperations.delete(operation);
+        if (channel.factoryOperationByAgent.get(agentId) === operation) {
+          channel.factoryOperationByAgent.delete(agentId);
+        }
+      },
+      () => {
+        channel.factoryOperations.delete(operation);
+        if (channel.factoryOperationByAgent.get(agentId) === operation) {
+          channel.factoryOperationByAgent.delete(agentId);
+        }
+      },
     );
     return operation;
   }
@@ -1791,8 +2415,27 @@ export class Orchestrator {
     channel: Channel,
     agentId: string,
     args: Omit<Parameters<AgentSessionFactory["create"]>[0], "environment">,
+    recovery?: RecoveryFence,
   ): Promise<AgentSession | null> {
+    if (recovery && !this.recoveryIsCurrent(channel, agentId, recovery)) {
+      channel.reconcileAgain = true;
+      return null;
+    }
+    if (
+      channel.rosterSessionChanges.get(agentId)?.state === "pending-close"
+    ) {
+      channel.reconcileAgain = true;
+      return null;
+    }
+    if (!this.hasDesiredLaunchSettings(channel, agentId, args.agent)) {
+      channel.reconcileAgain = true;
+      return null;
+    }
     const environment = await this.agentEnvironment(channel);
+    if (recovery && !this.recoveryIsCurrent(channel, agentId, recovery)) {
+      channel.reconcileAgain = true;
+      return null;
+    }
     // ADR-076 + codex-cli 0.152.0: two codex agents that resolve to the SAME
     // account share one CODEX_HOME, and codex's new sqlite state runtime
     // cannot be opened by two concurrent processes — the second agent dies
@@ -1809,12 +2452,57 @@ export class Orchestrator {
         ? await this.isolateCodexHome(environment, agentId, args)
         : args;
     while (this.isActiveChannel(channel)) {
+      if (recovery && !this.recoveryIsCurrent(channel, agentId, recovery)) {
+        channel.reconcileAgain = true;
+        return null;
+      }
+      if (
+        channel.rosterSessionChanges.get(agentId)?.state === "pending-close"
+      ) {
+        channel.reconcileAgain = true;
+        return null;
+      }
+      if (!this.hasDesiredLaunchSettings(channel, agentId, boundArgs.agent)) {
+        channel.reconcileAgain = true;
+        return null;
+      }
       const generation = channel.configGeneration;
       const session = await this.factory.create({ ...boundArgs, environment });
       if (!this.isActiveChannel(channel)) {
         await session.close().catch(() => {});
         return null;
       }
+      if (recovery && !this.recoveryIsCurrent(channel, agentId, recovery)) {
+        await session.close().catch(() => {});
+        channel.reconcileAgain = true;
+        return null;
+      }
+      const pendingRosterClose = channel.rosterSessionChanges.get(agentId);
+      if (pendingRosterClose?.state === "pending-close") {
+        await this.closeRosterChangedSession(
+          channel,
+          agentId,
+          session,
+          pendingRosterClose,
+        );
+        channel.reconcileAgain = true;
+        return null;
+      }
+      if (!this.hasDesiredLaunchSettings(channel, agentId, boundArgs.agent)) {
+        const change = channel.rosterSessionChanges.get(agentId);
+        if (change) {
+          await this.closeRosterChangedSession(
+            channel,
+            agentId,
+            session,
+            change,
+          );
+        } else {
+          await session.close().catch(() => {});
+        }
+        channel.reconcileAgain = true;
+        return null;
+      }
       if (generation === channel.configGeneration) {
         // Keep the final generation check, stale cleanup, and map bind in one
         // synchronous continuation. A config writer that resumes immediately
@@ -1831,6 +2519,17 @@ export class Orchestrator {
     return null;
   }
 
+  private hasDesiredLaunchSettings(
+    channel: Channel,
+    agentId: string,
+    launched: RosterAgent,
+  ): boolean {
+    const desired = channel.roster.find((agent) => agent.id === agentId);
+    return Boolean(
+      desired && rosterLaunchChangeReason(launched, desired) === null,
+    );
+  }
+
   private agentEnvironment(
     channel: Channel,
   ): Promise<TaskEnvironmentHandle<unknown>> {
@@ -2029,6 +2728,10 @@ export class Orchestrator {
       if (channel.sessions.has(agent.id) || channel.spawning.has(agent.id)) {
         continue;
       }
+      if (!this.hasDesiredLaunchSettings(channel, agent.id, agent)) {
+        channel.reconcileAgain = true;
+        continue;
+      }
       channel.spawning.add(agent.id);
       try {
         const session = await this.createAndBindStableSession(
@@ -2041,7 +2744,7 @@ export class Orchestrator {
           executionProfile: this.executionProfileFor(channel, agent.id),
           attachCompatibilityKey: this.attachCompatibilityKeyFor(
             channel,
-            agent.id,
+            agent,
           ),
           agentEnv: this.accountAgentEnv(
               channel,
@@ -2185,6 +2888,78 @@ export class Orchestrator {
     return remaining;
   }
 
+  /** Whether a retired generation still owns a cloud turn boundary. An
+   * explicit interrupt already publishes its own aborted completion. */
+  private needsAbortedTurnBoundary(
+    channel: Channel,
+    agentId: string,
+  ): boolean {
+    return (
+      !channel.interrupted.has(agentId) &&
+      (channel.activeTurns.has(agentId) ||
+        channel.openTurns.has(agentId) ||
+        (channel.acceptedPrompts.get(agentId)?.length ?? 0) > 0)
+    );
+  }
+
+  private retainRetiredTurnBoundary(
+    channel: Channel,
+    agentId: string,
+    needed: boolean,
+  ): void {
+    if (needed) channel.retiredTurnBoundaries.add(agentId);
+  }
+
+  /** Publish a retained terminal edge at most once. Recovery can be overtaken
+   * by remove/edit after its generation-local turn maps have been cleared. */
+  private emitRetiredTurnAbort(channel: Channel, agentId: string): boolean {
+    if (!channel.retiredTurnBoundaries.delete(agentId)) return false;
+    this.emitHost({
+      kind: "agent.turn_complete",
+      taskId: channel.taskId,
+      agentId,
+      aborted: true,
+    });
+    return true;
+  }
+
+  private supersedeRecovery(channel: Channel, agentId: string): boolean {
+    const recovery = channel.recoveryByAgent.get(agentId);
+    if (!recovery) return false;
+    recovery.superseded = true;
+    // A live edit/removal now owns the terminal edge. Publish it before the
+    // roster lifecycle can emit restarting/removed or bind a replacement.
+    return this.emitRetiredTurnAbort(channel, agentId);
+  }
+
+  private publishRosterChangeAbort(
+    channel: Channel,
+    agentId: string,
+    change: RosterSessionChange,
+  ): void {
+    if (change.abortPublished) return;
+    if (!this.emitRetiredTurnAbort(channel, agentId)) {
+      this.emitHost({
+        kind: "agent.turn_complete",
+        taskId: channel.taskId,
+        agentId,
+        aborted: true,
+      });
+    }
+    change.abortPublished = true;
+  }
+
+  private recoveryIsCurrent(
+    channel: Channel,
+    agentId: string,
+    recovery: RecoveryFence,
+  ): boolean {
+    return (
+      channel.recoveryByAgent.get(agentId) === recovery &&
+      !recovery.superseded
+    );
+  }
+
   /**
    * Retire turn-local state owned by a runner generation before replacement.
    *
@@ -2618,6 +3393,13 @@ export class Orchestrator {
         if (channel.sessions.get(agentId) !== session) break;
         // The turn died with the session — drop its turn-state flags so a
         // respawned session starts clean.
+        const abortBoundaryOnRosterChange =
+          this.needsAbortedTurnBoundary(channel, agentId);
+        this.retainRetiredTurnBoundary(
+          channel,
+          agentId,
+          abortBoundaryOnRosterChange,
+        );
         this.retireRunnerGeneration(channel, agentId);
         // Claude under load (especially Docker Desktop macOS) occasionally
         // unlinks ~/.claude.json mid-write during atomic config rewrites,
@@ -2627,13 +3409,32 @@ export class Orchestrator {
         // session so the user keeps working instead of staring at a dead
         // chat.
         const agent = channel.roster.find((a) => a.id === agentId);
+        if (channel.rosterSessionChanges.has(agentId)) {
+          // The authoritative roster already wants a different launch. Do not
+          // rotate/recover this obsolete generation with its captured account;
+          // preserve the live adapter so the normal stale-session recycler
+          // closes it (and fences late Codex notifications). The cloud still
+          // needs a terminal edge for any partial turn before restarting.
+          this.reconcileErroredRosterChange(
+            channel,
+            agentId,
+            event.message,
+            abortBoundaryOnRosterChange,
+          );
+          break;
+        }
         // ADR-076: a rate-limit/usage-cap error fails over to another account
         // for this kind (cool the current one, recreate the session on the
         // next, re-deliver the in-flight prompt). No-op with <2 accounts.
         if (
           event.retryable === "rate_limit" &&
           agent &&
-          (await this.rotateAccount(channel, agentId, agent))
+          (await this.rotateAccount(
+            channel,
+            agentId,
+            agent,
+            abortBoundaryOnRosterChange,
+          ))
         ) {
           break;
         }
@@ -2650,13 +3451,71 @@ export class Orchestrator {
             `[orchestrator] ${channel.taskId}/${agentId}: ${agent.kind} credential-invalid pattern matched: ${event.message.slice(0, 300)}`,
           );
           const accountId = channel.accountByAgent.get(agentId) ?? null;
-          const requested = await requestCredentialRefresh({
-            kind: agent.kind,
-            accountId: accountId && !accountId.startsWith("default:") ? accountId : null,
-            scope: channel.engineAccountScope,
-          });
+          // The broker is a slow await between a failed turn and its recovery.
+          // Own the spawn slot so a concurrent roster edit cannot publish
+          // ready for a replacement before this old generation publishes its
+          // aborted boundary (events carry no generation id in the cloud).
+          const ownsBrokerSlot = !channel.spawning.has(agentId);
+          if (ownsBrokerSlot) channel.spawning.add(agentId);
+          let requested = false;
+          try {
+            requested = await requestCredentialRefresh({
+              kind: agent.kind,
+              accountId:
+                accountId && !accountId.startsWith("default:")
+                  ? accountId
+                  : null,
+              scope: channel.engineAccountScope,
+            });
+          } catch (err) {
+            console.warn(
+              `[orchestrator] ${channel.taskId}/${agentId}: credential refresh request failed: ${
+                err instanceof Error ? err.message : String(err)
+              }`,
+            );
+          } finally {
+            if (ownsBrokerSlot) channel.spawning.delete(agentId);
+          }
+          // Removal/edit/recovery may have retired this generation while the
+          // broker request was in flight. Never let its continuation mutate a
+          // replacement or repopulate state for an absent roster id.
+          if (channel.sessions.get(agentId) !== session) {
+            // An edit can complete its restart while the broker request is
+            // still outstanding, consuming the roster-change marker at bind.
+            // The captured launch tuple still proves that this failed turn
+            // belongs to the retired generation and needs its aborted edge.
+            const stillRostered = channel.roster.some(
+              (candidate) => candidate.id === agentId,
+            );
+            if (
+              stillRostered &&
+              (!channel.sessions.has(agentId) ||
+                !this.hasDesiredLaunchSettings(channel, agentId, agent))
+            ) {
+              this.reconcileErroredRosterChange(
+                channel,
+                agentId,
+                event.message,
+                abortBoundaryOnRosterChange,
+              );
+            }
+            break;
+          }
+          if (channel.rosterSessionChanges.has(agentId)) {
+            this.reconcileErroredRosterChange(
+              channel,
+              agentId,
+              event.message,
+              abortBoundaryOnRosterChange,
+            );
+            break;
+          }
           if (requested) {
-            await this.refreshAgentToken(channel, agent);
+            await this.refreshAgentToken(
+              channel,
+              agent,
+              abortBoundaryOnRosterChange,
+            );
             break;
           }
         }
@@ -2670,7 +3529,11 @@ export class Orchestrator {
           console.warn(
             `[orchestrator] ${channel.taskId}/${agentId}: claude auth-revoked pattern matched: ${event.message.slice(0, 300)}`,
           );
-          await this.refreshAgentToken(channel, agent);
+          await this.refreshAgentToken(
+            channel,
+            agent,
+            abortBoundaryOnRosterChange,
+          );
           break;
         }
         const configMissing = CLAUDE_CONFIG_MISSING_PATTERNS.some((re) =>
@@ -2681,10 +3544,15 @@ export class Orchestrator {
           // than replaying the failed one. Do not leave it looking in-flight to
           // a later account refresh.
           channel.lastPrompt.delete(agentId);
-          await this.recoverClaudeAgent(channel, agentId);
+          await this.recoverClaudeAgent(
+            channel,
+            agentId,
+            abortBoundaryOnRosterChange,
+          );
           break;
         }
         channel.lastPrompt.delete(agentId);
+        channel.retiredTurnBoundaries.delete(agentId);
         this.emitHost({
           kind: "agent.exit",
           taskId: channel.taskId,
@@ -2730,7 +3598,11 @@ export class Orchestrator {
         });
         if (remainingTurns === 0) {
           channel.lastPrompt.delete(agentId);
-          this.startNextPendingPrompt(channel, agentId);
+          // A queued Secretary reply must run on the replacement settings,
+          // not extend the obsolete generation past its first safe boundary.
+          if (!channel.rosterSessionChanges.has(agentId)) {
+            this.startNextPendingPrompt(channel, agentId);
+          }
         }
         // A config repair never interrupts a turn. The stale id remains queued
         // until this exact boundary, then reconcile closes and replaces it.
@@ -2761,18 +3633,73 @@ export class Orchestrator {
         if (channel.sessions.get(agentId) !== session) break;
         // Same zombie hazard as the error path — a session whose process
         // ended (even cleanly) can never carry another turn.
+        const abortBoundaryOnRosterChange =
+          this.needsAbortedTurnBoundary(channel, agentId);
         this.retireRunnerGeneration(channel, agentId);
         channel.lastPrompt.delete(agentId);
         channel.respawns.set(agentId, (channel.respawns.get(agentId) ?? 0) + 1);
         channel.respawnLastAt.set(agentId, Date.now());
         channel.sessions.delete(agentId);
-        channel.browserStaleSessions.delete(agentId);
+        const rosterChangePending = channel.rosterSessionChanges.has(agentId);
+        if (rosterChangePending && abortBoundaryOnRosterChange) {
+          this.publishRosterChangeAbort(
+            channel,
+            agentId,
+            channel.rosterSessionChanges.get(agentId)!,
+          );
+        }
+        if (!rosterChangePending) channel.browserStaleSessions.delete(agentId);
         channel.browserPendingStaleSessions.delete(agentId);
         this.reconcilePendingSecretary(channel, agentId);
+        if (rosterChangePending) {
+          void this.reconcileSessions(channel).catch((err: unknown) => {
+            console.warn(
+              `[orchestrator] ${channel.taskId}/${agentId}: roster-change exit reconcile failed: ${
+                err instanceof Error ? err.message : String(err)
+              }`,
+            );
+          });
+        }
         break;
     }
   }
 
+  /** An engine error can race a live launch edit after a partial turn. Keep
+   * the obsolete adapter owned until the stale recycler closes it, but close
+   * the cloud turn boundary immediately so restarting/ready cannot leave the
+   * crew UI stuck in a working state. */
+  private reconcileErroredRosterChange(
+    channel: Channel,
+    agentId: string,
+    reason: string,
+    abortBoundary: boolean,
+  ): void {
+    channel.lastPrompt.delete(agentId);
+    channel.browserPendingStaleSessions.delete(agentId);
+    if (abortBoundary) {
+      const change = channel.rosterSessionChanges.get(agentId);
+      if (change) this.publishRosterChangeAbort(channel, agentId, change);
+      else this.emitRetiredTurnAbort(channel, agentId);
+    }
+    void this.reconcileAfterRosterRefresh(channel).catch((err: unknown) => {
+      console.warn(
+        `[orchestrator] ${channel.taskId}/${agentId}: roster-change error (${reason}) reconcile failed: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    });
+  }
+
+  /** Removal owns an asynchronous close/durable-stop fence. Recovery paths
+   * overtaken by remove/re-add must join it before they can spawn the re-added
+   * id, otherwise removal can stop the replacement generation. */
+  private async reconcileAfterRosterRefresh(channel: Channel): Promise<void> {
+    const rosterRefresh = channel.rosterRefreshReady;
+    if (rosterRefresh) await rosterRefresh;
+    if (!this.isActiveChannel(channel)) return;
+    await this.reconcileSessions(channel);
+  }
+
   /** A daemon loss is infrastructure recovery, not an agent crash. Preserve
    * accepted work, drop the dead generation, and leave respawn/exit accounting
    * untouched; the runtime-ready hook recreates it deterministically. */
@@ -2797,9 +3724,20 @@ export class Orchestrator {
       channel.runtimeDeferredAgents.add(agentId);
     }
     channel.sessions.delete(agentId);
-    channel.browserStaleSessions.delete(agentId);
+    if (!channel.rosterSessionChanges.has(agentId)) {
+      channel.browserStaleSessions.delete(agentId);
+    }
     channel.browserPendingStaleSessions.delete(agentId);
     await session.close().catch(() => {});
+    const rosterChange = channel.rosterSessionChanges.get(agentId);
+    if (rosterChange && this.isActiveChannel(channel)) {
+      await this.closeRosterChangedSession(
+        channel,
+        agentId,
+        session,
+        rosterChange,
+      );
+    }
   }
 
   // -- session recovery -----------------------------------------------------
@@ -2812,6 +3750,7 @@ export class Orchestrator {
   private async recoverClaudeAgent(
     channel: Channel,
     agentId: string,
+    abortBoundaryOnRosterChange = false,
   ): Promise<void> {
     if (!this.isActiveChannel(channel) || channel.spawning.has(agentId)) return;
 
@@ -2823,6 +3762,7 @@ export class Orchestrator {
       channel.sessions.delete(agentId);
       channel.browserStaleSessions.delete(agentId);
       channel.browserPendingStaleSessions.delete(agentId);
+      channel.retiredTurnBoundaries.delete(agentId);
       this.emitHost({
         kind: "agent.exit",
         taskId: channel.taskId,
@@ -2841,6 +3781,15 @@ export class Orchestrator {
         channel.containerName,
         channel.agentHandle ?? undefined,
       );
+      if (channel.rosterSessionChanges.has(agentId)) {
+        this.reconcileErroredRosterChange(
+          channel,
+          agentId,
+          "Claude config recovery superseded by live roster edit",
+          abortBoundaryOnRosterChange,
+        );
+        return;
+      }
 
       // Delete the old generation before awaiting close. Its adapter emits a
       // terminal event during teardown; bindSession's identity guard must see
@@ -2848,7 +3797,9 @@ export class Orchestrator {
       // a second replacement path.
       const old = channel.sessions.get(agentId);
       channel.sessions.delete(agentId);
-      channel.browserStaleSessions.delete(agentId);
+      if (!channel.rosterSessionChanges.has(agentId)) {
+        channel.browserStaleSessions.delete(agentId);
+      }
       channel.browserPendingStaleSessions.delete(agentId);
       this.retireRunnerGeneration(channel, agentId);
       if (old) {
@@ -2859,6 +3810,27 @@ export class Orchestrator {
         }
       }
       if (!this.isActiveChannel(channel)) return;
+      const rosterChange = channel.rosterSessionChanges.get(agentId);
+      if (rosterChange) {
+        // The generic recovery owned the close before the roster edit arrived.
+        // close() is idempotent; route its completed boundary through the
+        // roster lifecycle so the cloud still observes restarting -> ready.
+        this.reconcileErroredRosterChange(
+          channel,
+          agentId,
+          "Claude config recovery superseded by live roster edit",
+          abortBoundaryOnRosterChange,
+        );
+        if (old) {
+          await this.closeRosterChangedSession(
+            channel,
+            agentId,
+            old,
+            rosterChange,
+          );
+        }
+        return;
+      }
 
       const agent = channel.roster.find((a) => a.id === agentId);
       const task = getHostTask(channel.taskId);
@@ -2887,18 +3859,40 @@ export class Orchestrator {
         executionProfile: this.executionProfileFor(channel, agentId),
         attachCompatibilityKey: this.attachCompatibilityKeyFor(
           channel,
-          agentId,
+          agent,
         ),
         agentEnv: boundAccount
           ? { ...boundAccount.execEnv, ...base }
           : this.accountAgentEnv(channel, agent, base),
       });
-      if (!session) return;
+      if (!session) {
+        if (channel.rosterSessionChanges.has(agentId)) {
+          this.reconcileErroredRosterChange(
+            channel,
+            agentId,
+            "Claude config recovery superseded by live roster edit",
+            abortBoundaryOnRosterChange,
+          );
+        }
+        return;
+      }
+      if (!this.hasDesiredLaunchSettings(channel, agentId, agent)) {
+        if (channel.rosterSessionChanges.has(agentId)) {
+          this.reconcileErroredRosterChange(
+            channel,
+            agentId,
+            "Claude config recovery superseded by live roster edit",
+            abortBoundaryOnRosterChange,
+          );
+        }
+        return;
+      }
       this.startNextPendingPrompt(channel, agentId);
 
       const message = restored
         ? `${agentId} restarted — config file was missing in the container, restored from the host.`
         : `${agentId} restarted — config file was missing in the container (host copy not found; spawned anyway).`;
+      channel.retiredTurnBoundaries.delete(agentId);
       this.emitHost({
         kind: "agent.exit",
         taskId: channel.taskId,
@@ -2940,8 +3934,18 @@ export class Orchestrator {
     channel: Channel,
     agentId: string,
     agent: RosterAgent,
+    abortBoundaryOnRosterChange = false,
   ): Promise<boolean> {
     if (!this.isActiveChannel(channel)) return true;
+    if (channel.rosterSessionChanges.has(agentId)) {
+      this.reconcileErroredRosterChange(
+        channel,
+        agentId,
+        "account rotation superseded by live roster edit",
+        abortBoundaryOnRosterChange,
+      );
+      return true;
+    }
     // A concurrent terminal event for the same session is already being
     // handled by the path that owns this spawn slot.
     if (channel.spawning.has(agentId)) return true;
@@ -2964,6 +3968,8 @@ export class Orchestrator {
     const task = getHostTask(channel.taskId);
     if (!task || task.statusMirror !== "running") return false;
 
+    const recovery: RecoveryFence = { superseded: false };
+    channel.recoveryByAgent.set(agentId, recovery);
     let replacement: AgentSession | null = null;
     channel.spawning.add(agentId);
     try {
@@ -2974,6 +3980,11 @@ export class Orchestrator {
       channel.sessions.delete(agentId);
       channel.browserStaleSessions.delete(agentId);
       channel.browserPendingStaleSessions.delete(agentId);
+      this.retainRetiredTurnBoundary(
+        channel,
+        agentId,
+        abortBoundaryOnRosterChange,
+      );
       this.retireRunnerGeneration(channel, agentId);
       if (old) {
         try {
@@ -2983,6 +3994,25 @@ export class Orchestrator {
         }
       }
       if (!this.isActiveChannel(channel)) return true;
+      if (!this.recoveryIsCurrent(channel, agentId, recovery)) return true;
+      const rosterChange = channel.rosterSessionChanges.get(agentId);
+      if (rosterChange) {
+        this.reconcileErroredRosterChange(
+          channel,
+          agentId,
+          "account rotation superseded by live roster edit",
+          abortBoundaryOnRosterChange,
+        );
+        if (old) {
+          await this.closeRosterChangedSession(
+            channel,
+            agentId,
+            old,
+            rosterChange,
+          );
+        }
+        return true;
+      }
 
       // The serialized materialization gate owns both account provisioning
       // and, when enabled, browser migration.
@@ -2992,8 +4022,21 @@ export class Orchestrator {
         true,
       );
       if (!this.isActiveChannel(channel)) return true;
+      if (!this.recoveryIsCurrent(channel, agentId, recovery)) return true;
       await this.ensureMcpConfig(channel);
       if (!this.isActiveChannel(channel)) return true;
+      if (!this.recoveryIsCurrent(channel, agentId, recovery)) return true;
+      if (!this.hasDesiredLaunchSettings(channel, agentId, agent)) {
+        if (channel.rosterSessionChanges.has(agentId)) {
+          this.reconcileErroredRosterChange(
+            channel,
+            agentId,
+            "account rotation superseded by live roster edit",
+            abortBoundaryOnRosterChange,
+          );
+        }
+        return true;
+      }
 
       const apiUrl = apiUrlFromCloudUrl(env.UAI_CLOUD_URL);
       const cliSecret = loadTaskCliSecret(channel.taskId);
@@ -3018,12 +4061,34 @@ export class Orchestrator {
           executionProfile: this.executionProfileFor(channel, agentId),
           attachCompatibilityKey: this.attachCompatibilityKeyFor(
             channel,
-            agentId,
+            agent,
           ),
           agentEnv: { ...next.execEnv, ...base },
         },
+        recovery,
       );
-      if (!replacement) return true;
+      if (!replacement) {
+        if (!this.hasDesiredLaunchSettings(channel, agentId, agent)) {
+          this.reconcileErroredRosterChange(
+            channel,
+            agentId,
+            "account rotation superseded by live roster edit",
+            abortBoundaryOnRosterChange,
+          );
+        }
+        return true;
+      }
+      if (!this.hasDesiredLaunchSettings(channel, agentId, agent)) {
+        if (channel.rosterSessionChanges.has(agentId)) {
+          this.reconcileErroredRosterChange(
+            channel,
+            agentId,
+            "account rotation superseded by live roster edit",
+            abortBoundaryOnRosterChange,
+          );
+        }
+        return true;
+      }
 
       this.emitSystemNote(
         channel.taskId,
@@ -3033,14 +4098,35 @@ export class Orchestrator {
       // Re-deliver the in-flight prompt so the interrupted turn resumes.
       const prompt = channel.lastPrompt.get(agentId);
       if (prompt) {
+        channel.retiredTurnBoundaries.delete(agentId);
         this.startPrompt(channel, agentId, replacement, prompt);
       } else {
+        this.emitRetiredTurnAbort(channel, agentId);
         this.startNextPendingPrompt(channel, agentId);
       }
     } finally {
       channel.spawning.delete(agentId);
+      if (channel.recoveryByAgent.get(agentId) === recovery) {
+        channel.recoveryByAgent.delete(agentId);
+      }
       if (!replacement) {
+        if (!channel.roster.some((candidate) => candidate.id === agentId)) {
+          channel.accountByAgent.delete(agentId);
+          channel.rotations.delete(agentId);
+        }
         this.reconcilePendingSecretary(channel, agentId);
+        if (
+          this.isActiveChannel(channel) &&
+          (recovery.superseded || channel.rosterSessionChanges.has(agentId))
+        ) {
+          void this.reconcileAfterRosterRefresh(channel).catch((err: unknown) => {
+            console.warn(
+              `[orchestrator] ${channel.taskId}/${agentId}: post-rotation roster reconcile failed: ${
+                err instanceof Error ? err.message : String(err)
+              }`,
+            );
+          });
+        }
       }
     }
 
@@ -3077,10 +4163,23 @@ export class Orchestrator {
     agent: RosterAgent,
     account: ResolvedEngineAccount,
     note: string,
+    abortBoundaryOnRosterChange = false,
   ): Promise<boolean> {
+    if (channel.rosterSessionChanges.has(agentId)) {
+      this.reconcileErroredRosterChange(
+        channel,
+        agentId,
+        "credential respawn superseded by live roster edit",
+        abortBoundaryOnRosterChange,
+      );
+      return true;
+    }
+    if (!this.hasDesiredLaunchSettings(channel, agentId, agent)) return true;
     const task = getHostTask(channel.taskId);
     if (!task || task.statusMirror !== "running") return false;
 
+    const recovery: RecoveryFence = { superseded: false };
+    channel.recoveryByAgent.set(agentId, recovery);
     let replacement: AgentSession | null = null;
     channel.spawning.add(agentId);
     try {
@@ -3102,6 +4201,25 @@ export class Orchestrator {
         }
       }
       if (!this.isActiveChannel(channel)) return true;
+      if (!this.recoveryIsCurrent(channel, agentId, recovery)) return true;
+      const rosterChange = channel.rosterSessionChanges.get(agentId);
+      if (rosterChange) {
+        this.reconcileErroredRosterChange(
+          channel,
+          agentId,
+          "credential respawn superseded by live roster edit",
+          abortBoundaryOnRosterChange,
+        );
+        if (old) {
+          await this.closeRosterChangedSession(
+            channel,
+            agentId,
+            old,
+            rosterChange,
+          );
+        }
+        return true;
+      }
 
       await this.ensureBrowserSetup(
         channel,
@@ -3109,8 +4227,21 @@ export class Orchestrator {
         true,
       );
       if (!this.isActiveChannel(channel)) return true;
+      if (!this.recoveryIsCurrent(channel, agentId, recovery)) return true;
       await this.ensureMcpConfig(channel);
       if (!this.isActiveChannel(channel)) return true;
+      if (!this.recoveryIsCurrent(channel, agentId, recovery)) return true;
+      if (!this.hasDesiredLaunchSettings(channel, agentId, agent)) {
+        if (channel.rosterSessionChanges.has(agentId)) {
+          this.reconcileErroredRosterChange(
+            channel,
+            agentId,
+            "credential respawn superseded by live roster edit",
+            abortBoundaryOnRosterChange,
+          );
+        }
+        return true;
+      }
 
       const apiUrl = apiUrlFromCloudUrl(env.UAI_CLOUD_URL);
       const cliSecret = loadTaskCliSecret(channel.taskId);
@@ -3125,32 +4256,79 @@ export class Orchestrator {
       channel.accountByAgent.set(agentId, account.id);
       noteEngineAccountUsed(account.id);
 
-      replacement = await this.createAndBindStableSession(channel, agentId, {
-        taskId: channel.taskId,
-        agent,
-        systemPreamble: channel.preambles.get(agentId) ?? "",
-        executionProfile: this.executionProfileFor(channel, agentId),
-        attachCompatibilityKey: this.attachCompatibilityKeyFor(
-          channel,
-          agentId,
-        ),
-        agentEnv: { ...account.execEnv, ...base },
-      });
-      if (!replacement) return true;
+      replacement = await this.createAndBindStableSession(
+        channel,
+        agentId,
+        {
+          taskId: channel.taskId,
+          agent,
+          systemPreamble: channel.preambles.get(agentId) ?? "",
+          executionProfile: this.executionProfileFor(channel, agentId),
+          attachCompatibilityKey: this.attachCompatibilityKeyFor(
+            channel,
+            agent,
+          ),
+          agentEnv: { ...account.execEnv, ...base },
+        },
+        recovery,
+      );
+      if (!replacement) {
+        if (!this.hasDesiredLaunchSettings(channel, agentId, agent)) {
+          this.reconcileErroredRosterChange(
+            channel,
+            agentId,
+            "credential respawn superseded by live roster edit",
+            abortBoundaryOnRosterChange,
+          );
+        }
+        return true;
+      }
+      if (!this.hasDesiredLaunchSettings(channel, agentId, agent)) {
+        if (channel.rosterSessionChanges.has(agentId)) {
+          this.reconcileErroredRosterChange(
+            channel,
+            agentId,
+            "credential respawn superseded by live roster edit",
+            abortBoundaryOnRosterChange,
+          );
+        }
+        return true;
+      }
 
       this.emitSystemNote(channel.taskId, note);
 
       // Re-deliver the in-flight prompt so the interrupted turn resumes.
       const prompt = channel.lastPrompt.get(agentId);
       if (prompt) {
+        channel.retiredTurnBoundaries.delete(agentId);
         this.startPrompt(channel, agentId, replacement, prompt);
       } else {
+        this.emitRetiredTurnAbort(channel, agentId);
         this.startNextPendingPrompt(channel, agentId);
       }
     } finally {
       channel.spawning.delete(agentId);
+      if (channel.recoveryByAgent.get(agentId) === recovery) {
+        channel.recoveryByAgent.delete(agentId);
+      }
       if (!replacement) {
+        if (!channel.roster.some((candidate) => candidate.id === agentId)) {
+          channel.accountByAgent.delete(agentId);
+          channel.rotations.delete(agentId);
+        }
         this.reconcilePendingSecretary(channel, agentId);
+        if (
+          this.isActiveChannel(channel) &&
+          (recovery.superseded || channel.rosterSessionChanges.has(agentId))
+        ) {
+          void this.reconcileAfterRosterRefresh(channel).catch((err: unknown) => {
+            console.warn(
+              `[orchestrator] ${channel.taskId}/${agentId}: post-respawn roster reconcile failed: ${
+                err instanceof Error ? err.message : String(err)
+              }`,
+            );
+          });
+        }
       }
     }
 
@@ -3179,14 +4357,21 @@ export class Orchestrator {
   private async refreshAgentToken(
     channel: Channel,
     agent: RosterAgent,
+    abortBoundaryOnRosterChange?: boolean,
   ): Promise<void> {
     const agentId = agent.id;
     if (!this.isActiveChannel(channel) || channel.spawning.has(agentId)) return;
+    if (!this.hasDesiredLaunchSettings(channel, agentId, agent)) return;
+    const abortBoundary =
+      abortBoundaryOnRosterChange ??
+      this.needsAbortedTurnBoundary(channel, agentId);
+    this.retainRetiredTurnBoundary(channel, agentId, abortBoundary);
 
     const tries = (channel.respawns.get(agentId) ?? 0) + 1;
     channel.respawns.set(agentId, tries);
     channel.respawnLastAt.set(agentId, Date.now());
     if (tries > MAX_RESPAWNS_PER_AGENT) {
+      channel.retiredTurnBoundaries.delete(agentId);
       this.emitHost({
         kind: "agent.exit",
         taskId: channel.taskId,
@@ -3203,7 +4388,10 @@ export class Orchestrator {
     const account =
       accounts.find((a) => a.id === channel.accountByAgent.get(agentId)) ??
       accounts[0];
-    if (!account) return;
+    if (!account) {
+      this.emitRetiredTurnAbort(channel, agentId);
+      return;
+    }
 
     await this.respawnAgentOnAccount(
       channel,
@@ -3211,6 +4399,7 @@ export class Orchestrator {
       agent,
       account,
       `${agentId}: ${agent.kind} credential refreshed — restarted the agent.`,
+      abortBoundary,
     );
   }
 
@@ -3252,9 +4441,21 @@ export class Orchestrator {
   async refreshEngineAccountAgents(kind: string): Promise<void> {
     for (const channel of this.channels.values()) {
       if (!this.isActiveChannel(channel)) continue;
-      for (const agent of channel.roster) {
-        if (agent.kind !== kind || !channel.sessions.has(agent.id)) continue;
-        channel.respawns.set(agent.id, 0);
+      const agentIds = channel.roster
+        .filter((agent) => agent.kind === kind)
+        .map((agent) => agent.id);
+      for (const agentId of agentIds) {
+        const agent = channel.roster.find(
+          (candidate) => candidate.id === agentId,
+        );
+        if (
+          !agent ||
+          agent.kind !== kind ||
+          !channel.sessions.has(agentId)
+        ) {
+          continue;
+        }
+        channel.respawns.set(agentId, 0);
         try {
           await this.refreshAgentToken(channel, agent);
         } catch (err) {
@@ -3299,7 +4500,10 @@ export class Orchestrator {
     this.channels.delete(taskId);
     this.clearBrowserRetry(ch);
     ch.browserStaleSessions.clear();
+    ch.rosterSessionChanges.clear();
     ch.browserPendingStaleSessions.clear();
+    ch.browserConfigAffectedKinds.clear();
+    ch.mcpProvisionAffectedKinds.clear();
     ch.activeTurns.clear();
     ch.acceptedPrompts.clear();
     ch.pendingPrompts.clear();
@@ -3307,17 +4511,22 @@ export class Orchestrator {
     ch.runtimeDeferredAgents.clear();
     ch.openTurns.clear();
     ch.interrupted.clear();
+    ch.retiredTurnBoundaries.clear();
+    ch.recoveryByAgent.clear();
     ch.reconcileAgain = false;
     const drains = [
       ch.browserSetup,
       ch.mcpConfigWrite,
       ch.reconcileReady,
+      ch.rosterRefreshReady,
+      ch.persistedRosterReady,
       ch.sessionsReady,
       ...ch.factoryOperations,
       ...ch.eventOperations,
     ].filter((promise): promise is Promise<unknown> => promise !== null);
     const sessions = [...ch.sessions.values()];
     ch.sessions.clear();
+    ch.factoryOperationByAgent.clear();
     const closes = sessions.map((session) =>
       session.close().catch(() => {
         // Teardown is best-effort; every adapter close is intended idempotent.
@@ -3441,6 +4650,18 @@ export class Orchestrator {
   }
 }
 
+/** Launch-time settings only. Wire-compatible absence spellings are equal. */
+function rosterLaunchChangeReason(
+  previous: RosterAgent,
+  next: RosterAgent,
+): string | null {
+  const changed: string[] = [];
+  if (previous.kind !== next.kind) changed.push("engine");
+  if ((previous.model ?? "") !== (next.model ?? "")) changed.push("model");
+  if ((previous.effort ?? "") !== (next.effort ?? "")) changed.push("effort");
+  return changed.length > 0 ? `${changed.join("/")} change` : null;
+}
+
 /** Exact host-wire role validation; never trims or canonicalises agent ids. */
 export function hasValidSecretarySelection(
   spec: Pick<