@runuai/host 0.9.147 → 0.9.149

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,
@@ -45,7 +50,12 @@ import { ACTIVE_STATUSES, isActive, isOnDashboard } from "./task-status";
 import { isSafeHostTaskId } from "./task-identity";
 import { projectEnvForTask } from "./host-env";
 import { shadowRoute } from "./routing/shadow";
-import { getHostTask, hostTaskProjectIds, upsertHostTask } from "./runtime-state";
+import {
+  getHostTask,
+  hostTaskEnvMode,
+  hostTaskProjectIds,
+  upsertHostTask,
+} from "./runtime-state";
 import { clearRefresh, reconcileTaskGitAuth } from "./github-tokens";
 import { ensureTaskSshIdentity, setupTaskGitIdentity } from "./git-identity";
 import { dockerCli } from "./docker-exec";
@@ -78,7 +88,20 @@ import {
   appleTaskStoreVolumeName,
   parseAppleTaskEnvironmentLocator,
 } from "./task-environment/apple-container";
-import { parseDockerTaskEnvironmentLocator } from "./task-environment/docker";
+import {
+  DOCKER_TASK_ENVIRONMENT_PROVIDER,
+  parseDockerTaskEnvironmentLocator,
+} from "./task-environment/docker";
+import { APPLE_TASK_ENVIRONMENT_PROVIDER } from "./task-environment/apple-container";
+import { activeSecretsProxy } from "./secrets-proxy/host";
+import { usableProxiedKeys } from "./secrets-proxy/policy";
+import { forgetTaskProxyReadiness } from "./secrets-proxy/readiness";
+import {
+  invalidateTaskWrites,
+  applyTaskRootSteps,
+  taskWritesQuiescing,
+  type RecoveryProxyFailure,
+} from "./secrets-proxy/task-trust";
 import type {
   TaskEnvironmentDescriptor,
   TaskEnvironmentHandle,
@@ -92,9 +115,15 @@ import {
   type SkillExec,
   writeAgentSkills,
 } from "./skills";
-import { ensureMachineGatewayTunnel } from "./machine-gateway-tunnel";
+import {
+  ensureMachineGatewayTunnel,
+  ensureMachineGatewayTunnelReady,
+  MACHINE_GATEWAY_TUNNEL_PORT,
+} from "./machine-gateway-tunnel";
+import { ensureContainerTaskEnvForwarder } from "./task-env-forwarder";
 import {
   CONTAINER_CLI_PATH,
+  agentCliArgv,
   agentCliEnv,
   apiUrlFromCloudUrl,
   loadTaskCliSecret,
@@ -121,6 +150,12 @@ import {
   type ResolvedEngineAccount,
 } from "./engine-accounts";
 import { clearTaskGatewayAcl, setupMcpTaskConfig } from "./mcp-gateway";
+import {
+  reactivateTaskGatewayTask,
+  removeTaskGatewayTask,
+  suspendTaskGatewayTask,
+  type TaskGatewayRegistration,
+} from "./task-gateway-state";
 import {
   PREVIEW_SIDECAR_TASK_LABEL,
   stopPreviewSidecars,
@@ -145,6 +180,7 @@ import {
   SECRETARY_TYPED_DISPATCH_PROTOCOL_FEATURE,
 } from "../src/protocol";
 import { isEnvironmentTransportProvider } from "./task-environment/types";
+import { forgetTaskEnvSnapshot } from "./task-env-source";
 
 export type HostEventSubscriber = (event: HostEvent) => void;
 
@@ -223,14 +259,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 +309,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 +345,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 +369,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 +391,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 +618,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";
@@ -597,6 +739,7 @@ export class Orchestrator {
           channel.sharedFiles,
           spec.mode,
           spec.secretaryAgentId,
+          taskProxiedKeys(channel.taskId),
         ),
       );
     }
@@ -626,6 +769,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 {
@@ -670,6 +969,7 @@ export class Orchestrator {
           spec.sharedFiles ?? "ro",
           spec.mode,
           spec.secretaryAgentId,
+          taskProxiedKeys(taskId),
         ),
       );
       // ADR-046: materialise this agent's skills to its per-agent SKILL.md in
@@ -709,8 +1009,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 +1025,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 +1036,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 +1070,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 +1186,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 +1276,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 +1319,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 +1381,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 +1465,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 +1504,7 @@ export class Orchestrator {
                 this.noteProvisionMutation(
                   channel,
                   channel.browserTesting,
+                  new Set(mutableProvisionKinds),
                 );
               } else {
                 this.fenceConfigGeneration(channel);
@@ -1107,10 +1562,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 +1727,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 +1792,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 +1812,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 +1849,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 +1869,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 +2130,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 +2144,8 @@ export class Orchestrator {
               executionProfile: this.executionProfileFor(channel, agent.id),
               attachCompatibilityKey: this.attachCompatibilityKeyFor(
                 channel,
-                agent.id,
+                agent,
+                task,
               ),
               agentEnv: this.accountAgentEnv(
                 channel,
@@ -1543,7 +2158,7 @@ export class Orchestrator {
                   cliSecret,
                   this.isPromptLevelSecretary(channel, agent.id),
                 ),
-                this.machineProjectEnv(task),
+                task,
               ),
             },
           );
@@ -1571,16 +2186,33 @@ export class Orchestrator {
 
   private attachCompatibilityKeyFor(
     channel: Channel,
-    agentId: string,
+    agent: RosterAgent,
+    task: { envMode?: string | null },
   ): 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.
+    const envMode = hostTaskEnvMode(task);
+    if (envMode === "baked" && !model && !effort) return policy;
+    return JSON.stringify([
+      envMode === "baked" ? "roster-launch-v1" : "roster-launch-v2",
+      ...(envMode === "loader" ? [envMode] : []),
+      agent.kind,
+      model,
+      effort,
+      policy ?? "",
+    ]);
   }
 
   private isSecretary(channel: Channel, agentId: string): boolean {
@@ -1614,10 +2246,17 @@ export class Orchestrator {
     channel: Channel,
     agent: RosterAgent,
     base: Record<string, string>,
-    /** Lowest precedence: project env for tasks whose environment has no
-     *  container env to carry it. The account's env and the uai base win. */
-    floor: Record<string, string> = {},
+    task: {
+      environmentProvider: string | null;
+      projectIds?: string | null;
+      envMode?: string | null;
+    },
   ): Record<string, string> {
+    const floor = this.machineProjectEnv(task);
+    if (!this.hasDesiredLaunchSettings(channel, agent.id, agent)) {
+      channel.accountByAgent.delete(agent.id);
+      return { ...floor, ...base };
+    }
     const account = pickEngineAccount(agent.kind, {
       scope: channel.engineAccountScope,
     });
@@ -1631,18 +2270,22 @@ export class Orchestrator {
   }
 
   /**
-   * ADR-015 project env for a machine task (ADR-121): Docker tasks receive it
-   * from the compose env task-up renders, but a machine has no container, so
-   * it rides every agent session's env instead. Read at each spawn, so a
-   * respawn picks up values set since the task started. Empty for container
-   * tasks — their env already carries it and must not be doubled into argv.
+   * Rollout compatibility for a machine/self task created before ADR-153.
+   * Those runtimes had no container env: project values rode every agent
+   * spawn. Loader tasks must never take this path; they fetch through the
+   * gateway, and adding values here would freeze them and bypass declarations.
    */
   private machineProjectEnv(task: {
     environmentProvider: string | null;
     projectIds?: string | null;
+    envMode?: string | null;
   }): Record<string, string> {
-    // Machine OR sidecar (ADR-133): neither has a compose env to ride.
-    if (!isEnvironmentTransportProvider(task.environmentProvider)) return {};
+    if (
+      hostTaskEnvMode(task) !== "baked" ||
+      !isEnvironmentTransportProvider(task.environmentProvider)
+    ) {
+      return {};
+    }
     return projectEnvForTask(hostTaskProjectIds(task));
   }
 
@@ -1662,6 +2305,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 +2384,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;
   }
@@ -1762,6 +2430,7 @@ export class Orchestrator {
     try {
       const res = await environment.exec({
         argv: ["/bin/sh", "-c", codexHomeSeedCommand(home, perAgent)],
+        projectEnvProfile: "maintenance",
         user: "root",
         env: RUNTIME_AUTHORITY_ENV,
         timeoutMs: 30_000,
@@ -1791,8 +2460,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 +2497,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 +2564,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>> {
@@ -1878,6 +2622,7 @@ export class Orchestrator {
       const argv = cmd as [string, ...string[]];
       const result = await environment.exec({
         argv,
+        projectEnvProfile: "maintenance",
         cwd,
         user: "node",
         env: RUNTIME_AUTHORITY_ENV,
@@ -2029,6 +2774,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(
@@ -2037,13 +2786,14 @@ export class Orchestrator {
           {
             taskId: channel.taskId,
             agent,
-          systemPreamble: channel.preambles.get(agent.id) ?? "",
-          executionProfile: this.executionProfileFor(channel, agent.id),
-          attachCompatibilityKey: this.attachCompatibilityKeyFor(
-            channel,
-            agent.id,
-          ),
-          agentEnv: this.accountAgentEnv(
+            systemPreamble: channel.preambles.get(agent.id) ?? "",
+            executionProfile: this.executionProfileFor(channel, agent.id),
+            attachCompatibilityKey: this.attachCompatibilityKeyFor(
+              channel,
+              agent,
+              task,
+            ),
+            agentEnv: this.accountAgentEnv(
               channel,
               agent,
               agentCliEnv(
@@ -2054,7 +2804,7 @@ export class Orchestrator {
                 cliSecret,
                 this.isPromptLevelSecretary(channel, agent.id),
               ),
-              this.machineProjectEnv(task),
+              task,
             ),
           },
         );
@@ -2185,6 +2935,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.
    *
@@ -2429,7 +3251,8 @@ export class Orchestrator {
         exec: async (argv) => {
           if (!handle || !canExec) return null;
           const r = await handle.exec({
-            argv,
+            argv: agentCliArgv(handle, argv),
+            projectEnvProfile: "task",
             cwd: scratchDir,
             user: "node",
             env,
@@ -2618,6 +3441,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 +3457,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 +3499,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 +3577,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 +3592,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 +3646,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 +3681,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 +3772,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 +3798,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 +3810,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 +3829,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 +3845,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 +3858,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 +3907,45 @@ export class Orchestrator {
         executionProfile: this.executionProfileFor(channel, agentId),
         attachCompatibilityKey: this.attachCompatibilityKeyFor(
           channel,
-          agentId,
+          agent,
+          task,
         ),
         agentEnv: boundAccount
-          ? { ...boundAccount.execEnv, ...base }
-          : this.accountAgentEnv(channel, agent, base),
+          ? {
+              ...this.machineProjectEnv(task),
+              ...boundAccount.execEnv,
+              ...base,
+            }
+          : this.accountAgentEnv(channel, agent, base, task),
       });
-      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 +3987,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 +4021,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 +4033,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 +4047,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 +4075,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 +4114,39 @@ export class Orchestrator {
           executionProfile: this.executionProfileFor(channel, agentId),
           attachCompatibilityKey: this.attachCompatibilityKeyFor(
             channel,
-            agentId,
+            agent,
+            task,
           ),
-          agentEnv: { ...next.execEnv, ...base },
+          agentEnv: {
+            ...this.machineProjectEnv(task),
+            ...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 +4156,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 +4221,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 +4259,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 +4285,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 +4314,84 @@ 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,
+            task,
+          ),
+          agentEnv: {
+            ...this.machineProjectEnv(task),
+            ...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 +4420,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 +4451,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 +4462,7 @@ export class Orchestrator {
       agent,
       account,
       `${agentId}: ${agent.kind} credential refreshed — restarted the agent.`,
+      abortBoundary,
     );
   }
 
@@ -3252,9 +4504,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 +4563,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 +4574,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.
@@ -3350,18 +4622,38 @@ export class Orchestrator {
    * tombstone prevents any agent process from respawning during maintenance. */
   async quarantineChannelForRecovery(taskId: string): Promise<void> {
     const currentSpec = this.channelSpecs.get(taskId);
+    const suspended = suspendTaskGatewayTask(taskId);
+    if (suspended) this.suspendedTaskGateways.set(taskId, suspended);
     await this.closeChannel(taskId);
     if (currentSpec && !this.channelSpecs.has(taskId)) {
       this.channelSpecs.set(taskId, currentSpec);
     }
   }
 
+  /** Reopen only the authenticated task gateway for sanctioned recovery
+   * work. The channel tombstone remains in place until allowChannel(), so
+   * agents cannot respawn while uai-init's dependency worker refreshes env. */
+  reactivateTaskGatewayForRecovery(taskId: string): void {
+    const suspended = this.suspendedTaskGateways.get(taskId);
+    if (!suspended) return;
+    if (!reactivateTaskGatewayTask(suspended)) {
+      throw new Error(
+        `task ${taskId} gateway generation could not be reactivated for recovery`,
+      );
+    }
+  }
+
   /** A successful task-up is the only transition that reopens a tombstoned
    *  task id after stop/teardown. */
   allowChannel(taskId: string): void {
     // A caller that forgot the task-up fence cannot reopen the id while old
     // external operations are still draining.
     if (this.channelClosures.has(taskId)) return;
+    const suspended = this.suspendedTaskGateways.get(taskId);
+    if (suspended) {
+      reactivateTaskGatewayTask(suspended);
+      this.suspendedTaskGateways.delete(taskId);
+    }
     this.blockedTasks.delete(taskId);
   }
 
@@ -3378,6 +4670,10 @@ export class Orchestrator {
    * (ADR-125) reads this — the cloud decides idleness from what it can see,
    * but only the host can see a turn that is mid-flight RIGHT NOW. */
   readonly #channelActivity = new Map<string, number>();
+  private readonly suspendedTaskGateways = new Map<
+    string,
+    TaskGatewayRegistration
+  >();
 
   markChannelActivity(taskId: string): void {
     this.#channelActivity.set(taskId, Date.now());
@@ -3403,7 +4699,11 @@ export class Orchestrator {
     if (!task) return { ok: false, error: "unknown task" };
     const project = task.composeProject;
     if (!project) return { ok: false, error: "task has no running stack" };
-    // Close sessions first so nothing races to respawn them mid-stop.
+    // Revoke env/proxy access before a potentially long session drain, then
+    // close sessions so nothing races to respawn them mid-stop.
+    const suspendedGateway = suspendTaskGatewayTask(taskId);
+    // ADR-153: no longer served; end its open proxy connections too.
+    activeSecretsProxy()?.runtime.stopTask(taskId);
     await this.closeChannel(taskId);
     try {
       await stopPreviewSidecars(taskId);
@@ -3424,11 +4724,13 @@ export class Orchestrator {
     try {
       const environment = await reconstructPersistedTaskEnvironment(task);
       if (!environment) {
+        if (suspendedGateway) reactivateTaskGatewayTask(suspendedGateway);
         this.allowChannel(taskId);
         return { ok: false, error: "task has no persisted environment" };
       }
       await environment.stop();
     } catch (err) {
+      if (suspendedGateway) reactivateTaskGatewayTask(suspendedGateway);
       this.allowChannel(taskId);
       return {
         ok: false,
@@ -3436,11 +4738,41 @@ export class Orchestrator {
       };
     }
     upsertHostTask(taskId, { statusMirror: "stopped" });
+    // The next start installs the CA again before anything reads the env;
+    // no write still queued for the stopped container may land or record.
+    invalidateTaskWrites(taskId);
+    forgetTaskProxyReadiness(taskId);
+    try {
+      removeTaskGatewayTask(taskId);
+    } catch (error) {
+      // The runtime is stopped and the in-memory generation is already
+      // inactive. A leftover durable file also loads inactive; explicit
+      // Resume rotates it through task-up.
+      console.warn(
+        `[task-gateway] ${taskId}: paused with stale inactive gateway state: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+    // Nothing serves the task's env now: no value of it stays in memory.
+    forgetTaskEnvSnapshot(taskId);
     clearTaskGatewayAcl(taskId);
     return { ok: true };
   }
 }
 
+/** 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<
@@ -3581,6 +4913,7 @@ async function repairClaudeConfigInContainer(
   if (environment) {
     const write = await environment.exec({
       argv: ["/bin/sh", "-c", repairScript],
+      projectEnvProfile: "maintenance",
       env: RUNTIME_AUTHORITY_ENV,
       stdin: content,
       timeoutMs: 30_000,
@@ -3677,6 +5010,28 @@ export function assembleFirstTurnPrompt(
  * to every turn; only `initialPrompt` is delivered as the first user
  * turn (see `assembleFirstTurnPrompt`).
  */
+/** The task's usable proxied keys right now (ADR-153 §5): its agents are
+ *  told which env vars hold placeholders, and for which domains; a withheld
+ *  key is absent from the task, so it is not mentioned. */
+function taskProxiedKeys(taskId: string): { key: string; domains: string[] }[] {
+  // The same gate as the placeholder and the injection.
+  return usableProxiedKeys(taskId).map((key) => ({ key: key.key, domains: [...key.domains] }));
+}
+
+/** ADR-153 §5's line, with the exact key-to-domain mapping. */
+export function proxiedEnvLine(keys: readonly { readonly key: string; readonly domains: readonly string[] }[]): string {
+  const listed = [...keys]
+    .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
+    .map((entry) => `\`${entry.key}\` (${entry.domains.join(", ")})`)
+    .join(", ");
+  const domainCount = new Set(keys.flatMap((entry) => entry.domains)).size;
+  return (
+    `These env vars hold placeholders, not the real secrets: ${listed}. Uai's proxy puts the real value in on ` +
+    `HTTPS requests to ${domainCount === 1 ? "that domain" : "those domains"}, so use them as they are — don't ` +
+    `replace, re-fetch or "fix" them. They won't work anywhere else.`
+  );
+}
+
 export function buildSystemPreamble(
   roster: Roster,
   agent: RosterAgent,
@@ -3689,6 +5044,7 @@ export function buildSystemPreamble(
   sharedFiles?: string,
   mode?: "open" | "secretary",
   secretaryAgentId?: string,
+  proxiedKeys?: readonly { readonly key: string; readonly domains: readonly string[] }[],
 ): string {
   const channelList = roster
     .map((a) =>
@@ -4134,6 +5490,10 @@ export function buildSystemPreamble(
           "",
         ]
       : []),
+    // ADR-153 §5: proxied keys reach the task as placeholders.
+    ...(proxiedKeys !== undefined && proxiedKeys.length > 0
+      ? ["## Proxied env vars", "", proxiedEnvLine(proxiedKeys), ""]
+      : []),
     // ADR-048: tell every agent with persona-granted permissions about its
     // `uai` CLI. Secretary mode adds dispatch but does not invent any other
     // permission: an empty persona permission set remains empty.
@@ -4329,7 +5689,15 @@ function beginRuntimeRecovery(
   const predecessor = recoveryInFlight;
   const sweep = async (): Promise<boolean> => {
     try {
-      return await recoverRunningTasks({ lifecycle, isCurrent });
+      return await recoverRunningTasks({
+        lifecycle,
+        // Boot recovery deliberately keeps its per-task barriers instead of
+        // entering lifecycle slots, but still needs the live orchestrator to
+        // suspend/reactivate gateway generations around uai-init.
+        consumerLifecycle:
+          lifecycle ?? globalForOrchestrator.__uaiOrchestrator,
+        isCurrent,
+      });
     } catch (error) {
       console.error(
         "[orchestrator] recovery: unhandled failure",
@@ -5750,6 +7118,9 @@ export async function recoverRunningTasks(opts?: {
   /** Post-boot recovery must queue behind live taskUp/taskDown operations.
    * Boot recovery omits this and uses its earlier per-task barriers instead. */
   lifecycle?: Orchestrator;
+  /** Consumer quarantine/admission hooks without changing boot recovery's
+   * barrier-based sequencing. Production boot supplies the live singleton. */
+  consumerLifecycle?: Orchestrator;
   /** Test seam; production waits for the shared image/CLI-volume reconcile. */
   maintenanceReady?: Promise<void>;
   /** A daemon-generation fence. False cancels every remaining side effect. */
@@ -5769,6 +7140,7 @@ export async function recoverRunningTasks(opts?: {
     const result = await recoveryPass(
       pendingTaskIds,
       opts?.lifecycle,
+      opts?.consumerLifecycle,
       opts?.maintenanceReady ?? agentClisReady,
       opts?.isCurrent ?? (() => true),
     );
@@ -5813,6 +7185,7 @@ interface RecoveryPassResult {
 async function recoveryPass(
   onlyTaskIds?: ReadonlySet<string>,
   lifecycle?: Orchestrator,
+  consumerLifecycle?: Orchestrator,
   maintenanceReady: Promise<void> = agentClisReady,
   isCurrent: () => boolean = () => true,
 ): Promise<RecoveryPassResult> {
@@ -5870,6 +7243,7 @@ async function recoveryPass(
               task,
               maintenanceReady,
               isCurrent,
+              consumerLifecycle,
             );
         if (recovered) {
           if (!lifecycle) finishTaskRecovery(task.taskId);
@@ -6064,15 +7438,23 @@ async function quarantineWritableAppleRuntimeContainers(options: {
 /** Keep the MCP gateway reverse tunnel alive for a machine channel. The
  * handle exposes tunnel argv only on the machine provider; anything else is
  * a quiet no-op. */
-function ensureMachineGatewayTunnelFor(
+async function ensureMachineGatewayTunnelFor(
   taskId: string,
   handle: TaskEnvironmentHandle<unknown> | null,
-): void {
+  waitUntilReady = false,
+): Promise<void> {
   const argv = handle?.gatewayTunnelSshArgs;
   if (!argv) return;
-  ensureMachineGatewayTunnel(taskId, {
-    gatewayTunnelSshArgs: argv.bind(handle),
-  });
+  const source = { gatewayTunnelSshArgs: argv.bind(handle) };
+  const loaderPort =
+    handle.descriptor.envMode === "loader"
+      ? MACHINE_GATEWAY_TUNNEL_PORT
+      : undefined;
+  if (waitUntilReady && loaderPort !== undefined) {
+    await ensureMachineGatewayTunnelReady(taskId, source, loaderPort);
+    return;
+  }
+  ensureMachineGatewayTunnel(taskId, source, loaderPort);
 }
 
 async function materializeAgentCli(
@@ -6107,25 +7489,105 @@ async function recoverPersistedTaskEnvironment(
   const environment = await reconstructPersistedTaskEnvironment(task);
   if (environment === null) return true;
   if (!isCurrent()) return true;
-  const result = await environment.recover({
-    maintenanceReady,
-    isCurrent,
-    ...(lifecycle
-      ? {
-          quarantineConsumers: () =>
-            lifecycle.quarantineChannelForRecovery(task.taskId),
-          allowConsumers: () => lifecycle.allowChannel(task.taskId),
-          ensureConsumersStarted: async () => {
-            await lifecycle.ensureStarted(task.taskId);
-          },
-        }
-      : {}),
-  });
-  return result.outcome === "recovered";
+  // ADR-153: a recovery may restart the task's container or VM, which takes
+  // the proxy's CA, chain and names with it, and its forwarder. Before the
+  // provider touches it, nothing recorded counts any more and no write queued
+  // or under way may land: a reconcile in flight ends with its exec under
+  // way, and none pins again until this recovery's own slot has the
+  // forwarder running.
+  invalidateTaskWrites(task.taskId);
+  forgetTaskProxyReadiness(task.taskId);
+  // A running machine's editor can submit a command before any agent channel
+  // is reconstructed. Re-arm the authenticated gateway tunnel at recovery,
+  // not only at the first session spawn, so that command can refresh env.
+  void ensureMachineGatewayTunnelFor(task.taskId, environment);
+  let consumersPrepared = false;
+  let tunnelReadinessFailed = false;
+  const prepareConsumers = async (): Promise<void> => {
+    if (!isCurrent()) return;
+    try {
+      await ensureMachineGatewayTunnelFor(task.taskId, environment, true);
+    } catch (error) {
+      tunnelReadinessFailed = true;
+      console.warn(
+        `[machine-tunnel] ${task.taskId}: recovery deferred until the gateway tunnel is ready (${error instanceof Error ? error.message : String(error)})`,
+      );
+      throw error;
+    }
+    // ADR-153 "Order", in one slot of the task's write queue: the CA (or,
+    // with the proxy off, the pins out), then the forwarder, then the pins,
+    // so no name is pinned with nothing listening behind it. The forwarder
+    // carries the generation's secret into the task as root, and the
+    // reactivation opens the gateway to it: neither once this recovery is
+    // stale or the runner is shutting down. Every exec is fenced, so
+    // shutdown waits for one under way rather than exiting under it, and
+    // refuses (throws) any that would start after.
+    if (!isCurrent()) return;
+    const secretsProxy = activeSecretsProxy();
+    let proxyFailure: RecoveryProxyFailure | null;
+    try {
+      proxyFailure = await applyTaskRootSteps(
+        environment,
+        environment.descriptor.envMode === "loader" ? { runtime: secretsProxy?.runtime ?? null } : null,
+        (fenced) => ensureContainerTaskEnvForwarder(fenced),
+        isCurrent,
+      );
+    } catch (error) {
+      // Made stale meanwhile, its exec refused: recover() handles a stale
+      // recovery itself.
+      if (!isCurrent()) return;
+      throw error;
+    }
+    if (proxyFailure !== null) {
+      console.warn(
+        `[secrets-proxy] ${task.taskId}: recovery could not reconcile the proxy's pins and trust: ${
+          proxyFailure.error instanceof Error ? proxyFailure.error.message : String(proxyFailure.error)
+        }`,
+      );
+      // A failure leaves the task up without the proxy: the trust watcher
+      // retries, and its proxied keys stay withheld until the CA and the
+      // pins are in.
+      secretsProxy?.runtime.requestTrustDelivery();
+    }
+    if (!isCurrent()) return;
+    // Shutdown began during the launch: not prepared, so the consumers stay
+    // unadmitted, as for any failed preparation.
+    if (taskWritesQuiescing()) throw new Error("the runner is shutting down");
+    lifecycle?.reactivateTaskGatewayForRecovery(task.taskId);
+    consumersPrepared = true;
+  };
+  try {
+    const result = await environment.recover({
+      maintenanceReady,
+      isCurrent,
+      ...(lifecycle
+        ? {
+            quarantineConsumers: () =>
+              lifecycle.quarantineChannelForRecovery(task.taskId),
+            prepareConsumers,
+            allowConsumers: () => lifecycle.allowChannel(task.taskId),
+            ensureConsumersStarted: async () => {
+              await lifecycle.ensureStarted(task.taskId);
+            },
+          }
+        : {}),
+    });
+    if (result.outcome === "recovered" && !consumersPrepared && isCurrent()) {
+      const current = getHostTask(task.taskId);
+      if (current?.statusMirror && isActive(current.statusMirror)) {
+        await prepareConsumers();
+      }
+    }
+    return result.outcome === "recovered";
+  } catch (error) {
+    if (tunnelReadinessFailed) return false;
+    throw error;
+  }
 }
 
 interface RecoveryTaskConsumers {
   quarantineChannelForRecovery(taskId: string): Promise<void>;
+  prepareChannelForRecovery(taskId: string): Promise<void>;
   allowChannel(taskId: string): void;
   ensureStarted(taskId: string): Promise<boolean | void>;
 }
@@ -6588,6 +8050,7 @@ export async function recoverAppleTaskEnvironment(
         '[ "$(/usr/bin/stat -c %U /opt/uai/store/pnpm)" = "node" ] || { echo "store dir is not node-owned" >&2; exit 1; }; ' +
         "fi",
     ],
+    projectEnvProfile: "maintenance",
     user: "root",
     env: {},
     timeoutMs: 30_000,
@@ -6614,23 +8077,47 @@ export async function recoverAppleTaskEnvironment(
     );
     return settleFromStatus(afterOverlay);
   }
+  // The dependency worker inside uai-init performs its one loader sync. Its
+  // root forwarder and authenticated generation must be live first, while
+  // public agent admission remains quarantined until initialization ends.
+  let consumersPreparedForInit = false;
+  const reclosePreparedConsumers = async (): Promise<void> => {
+    if (!consumersPreparedForInit) return;
+    consumersPreparedForInit = false;
+    await context.quarantineConsumers?.();
+  };
+  if (context.prepareConsumers) {
+    await context.prepareConsumers();
+    consumersPreparedForInit = true;
+  }
+  if (!context.isCurrent()) {
+    await reclosePreparedConsumers();
+    return { outcome: "deferred", detail: "runtime generation superseded" };
+  }
   // Dependencies + code-server. The in-container deadline (TERM then KILL)
   // means a host-side expiry can never leave the initializer mutating the
   // workspace while agents use it; exit 78 is a runtime-authority violation
   // and quarantines exactly like at task-up.
-  const init = await environment.exec({
-    argv: [
-      "/usr/bin/timeout",
-      "--signal=TERM",
-      "--kill-after=15s",
-      "570s",
-      "/usr/local/bin/uai-init",
-    ],
-    env: {},
-    timeoutMs: 10 * 60_000,
-    maxOutputBytes: 1024 * 1024,
-  });
+  const init = await environment
+    .exec({
+      argv: [
+        "/usr/bin/timeout",
+        "--signal=TERM",
+        "--kill-after=15s",
+        "570s",
+        "/usr/local/bin/uai-init",
+      ],
+      projectEnvProfile: "maintenance",
+      env: {},
+      timeoutMs: 10 * 60_000,
+      maxOutputBytes: 1024 * 1024,
+    })
+    .catch(async (error: unknown) => {
+      await reclosePreparedConsumers();
+      throw error;
+    });
   if (!context.isCurrent()) {
+    await reclosePreparedConsumers();
     return { outcome: "deferred", detail: "runtime generation superseded" };
   }
   if (
@@ -6639,6 +8126,7 @@ export async function recoverAppleTaskEnvironment(
     init.stdoutTruncated ||
     init.stderrTruncated
   ) {
+    await reclosePreparedConsumers();
     // The host-side client died (deadline, overflow, forced settlement)
     // without a real exit code, so the in-container initializer may STILL be
     // mutating dependencies for several minutes. Never expose the task on an
@@ -6661,6 +8149,7 @@ export async function recoverAppleTaskEnvironment(
     return settleFromStatus(after);
   }
   if (init.exitCode === 78) {
+    await reclosePreparedConsumers();
     await environment.stop();
     const after = await environment.status();
     if (after.state === "running" || after.state === "unknown") {
@@ -6679,6 +8168,7 @@ export async function recoverAppleTaskEnvironment(
     return settleFromStatus(after);
   }
   if (init.exitCode === 127) {
+    await reclosePreparedConsumers();
     // Command-not-found from a read-only bind mount the guest cannot touch:
     // the initializer itself is unrunnable — live 2026-08-26, containers
     // whose versioned asset tree a host update had pruned looped here as
@@ -6709,6 +8199,7 @@ export async function recoverAppleTaskEnvironment(
     );
   }
   if (!context.isCurrent()) {
+    await reclosePreparedConsumers();
     return { outcome: "deferred", detail: "runtime generation superseded" };
   }
   db_setRuntime(descriptor.taskId, { codeServerPort: null });
@@ -6762,6 +8253,7 @@ async function recoverDockerTaskEnvironment(
 
   const lifecycleCallbacks = [
     context.quarantineConsumers,
+    context.prepareConsumers,
     context.allowConsumers,
     context.ensureConsumersStarted,
   ];
@@ -6777,6 +8269,12 @@ async function recoverDockerTaskEnvironment(
           }
           await context.quarantineConsumers!();
         },
+        prepareChannelForRecovery: async (taskId) => {
+          if (taskId !== descriptor.taskId) {
+            throw new Error("task environment recovery consumer identity mismatch");
+          }
+          await context.prepareConsumers!();
+        },
         allowChannel: (taskId) => {
           if (taskId !== descriptor.taskId) {
             throw new Error("task environment recovery consumer identity mismatch");
@@ -6984,6 +8482,13 @@ async function recoverOneDockerTask(
     );
     if (!isCurrent()) return true;
     if (lifecycle) {
+      await lifecycle.prepareChannelForRecovery(task.taskId);
+      if (!isCurrent()) {
+        // Preparation may have reactivated this task's gateway generation.
+        // A superseded pass must close that authority again before returning.
+        await lifecycle.quarantineChannelForRecovery(task.taskId);
+        return true;
+      }
       lifecycle.allowChannel(task.taskId);
       await lifecycle.ensureStarted(task.taskId);
       if (!isCurrent()) {
@@ -7119,6 +8624,23 @@ async function recoverOneDockerTask(
     }
     if (!isCurrent()) return true;
   }
+  // uai-init's dependency worker loads the task env once. Recreate the
+  // forwarder and reactivate only its authenticated gateway before that
+  // worker runs; the channel itself stays tombstoned until recovery finishes.
+  let consumersPreparedForInit = false;
+  const reclosePreparedConsumers = async (): Promise<void> => {
+    if (!consumersPreparedForInit || !lifecycle) return;
+    consumersPreparedForInit = false;
+    await lifecycle.quarantineChannelForRecovery(task.taskId);
+  };
+  if (lifecycle) {
+    await lifecycle.prepareChannelForRecovery(task.taskId);
+    consumersPreparedForInit = true;
+    if (!isCurrent()) {
+      await reclosePreparedConsumers();
+      return true;
+    }
+  }
   // uai-init reinstalls workspace deps (pnpm/npm install) — minutes on a big
   // repo. dockerCli's 30s default would SIGKILL it mid-install.
   const initResult = await dockerCli(
@@ -7210,9 +8732,16 @@ async function recoverOneDockerTask(
       RECOVERY_INIT_PATH,
     ],
     { timeoutMs: 10 * 60_000 },
-  );
-  if (!isCurrent()) return true;
+  ).catch(async (error: unknown) => {
+    await reclosePreparedConsumers();
+    throw error;
+  });
+  if (!isCurrent()) {
+    await reclosePreparedConsumers();
+    return true;
+  }
   if (initResult.status === 78) {
+    await reclosePreparedConsumers();
     const quarantined = await quarantineRunningContainer(containerName);
     if (!isCurrent()) return true;
     if (quarantined === "unreachable") return false;
@@ -7235,9 +8764,20 @@ async function recoverOneDockerTask(
       `[orchestrator] recovery: ${task.taskId} uai-init failed; container is up but Editor may be down`,
     );
   }
-  const portResult = await dockerPort(containerName, 8080);
-  if (!isCurrent()) return true;
-  if (!portResult.reachable) return false;
+  const portResult = await dockerPort(containerName, 8080).catch(
+    async (error: unknown) => {
+      await reclosePreparedConsumers();
+      throw error;
+    },
+  );
+  if (!isCurrent()) {
+    await reclosePreparedConsumers();
+    return true;
+  }
+  if (!portResult.reachable) {
+    await reclosePreparedConsumers();
+    return false;
+  }
   const port = portResult.port;
   db_setRuntime(task.taskId, {
     codeServerPort: port,
@@ -7254,7 +8794,10 @@ async function recoverOneDockerTask(
   console.log(
     `[orchestrator] recovery: ${task.taskId} resumed (port ${port ?? "?"})`,
   );
-  if (!isCurrent()) return true;
+  if (!isCurrent()) {
+    await reclosePreparedConsumers();
+    return true;
+  }
   if (lifecycle) {
     lifecycle.allowChannel(task.taskId);
     await lifecycle.ensureStarted(task.taskId);