@runuai/host 0.8.42 → 0.8.44

package/lib/orchestrator.ts

@@ -50,7 +50,11 @@ import {
   loadTaskCliSecret,
   writeAgentCli,
 } from "./agent-cli";
-import { setupBrowserTesting } from "./browser-testing";
+import {
+  DEFAULT_CODEX_HOME,
+  setupBrowserTesting,
+  type BrowserSetup,
+} from "./browser-testing";
 import { injectCodexIntoContainer } from "./codex-auth";
 import {
   cooldownEngineAccount,
@@ -60,6 +64,7 @@ import {
   resolveEngineAccounts,
 } from "./engine-accounts";
 import { clearTaskGatewayAcl, setupMcpTaskConfig } from "./mcp-gateway";
+import { stopPreviewSidecars } from "./preview-sidecar";
 import { env } from "./env";
 import type {
   ChannelEnsureInput,
@@ -90,9 +95,60 @@ interface Channel {
    *  awaits docker work before populating it). Reset to null on failure so the
    *  next ensure retries. */
   sessionsReady: Promise<boolean> | null;
+  /** ADR-053: true only when both the browser install and managed MCP configs
+   *  are ready. A task still starts while false; setup retries in the
+   *  background on a bounded timer. */
+  browserReady: boolean;
+  /** The one setup pass currently touching this container. Reconcile, retry,
+   *  and initial start all join this promise instead of racing config files. */
+  browserSetup: Promise<BrowserSetup> | null;
+  /** Codex account homes covered by the in-flight setup. A roster/account
+   *  change that adds a home queues one stronger pass after it. */
+  browserSetupCodexHomes: string[] | null;
+  /** Engine kinds provisioned by the in-flight setup. A roster generation
+   *  that adds a kind cannot join a weaker provisioning pass. */
+  browserSetupEngineKinds: string[] | null;
+  /** Exact account roster covered by the in-flight provisioning pass. */
+  browserSetupProvisionFingerprint: string | null;
+  /** Mutable coverage of the in-flight materialization pass. Joiners retain
+   *  this object through cleanup and can distinguish requested browser work
+   *  from a browser attempt that actually began. */
+  browserSetupCoverage: {
+    browserRequested: boolean;
+    browserAttempted: boolean;
+    skippedBecauseDisabled: boolean;
+    provisionAttempted: boolean;
+  } | null;
+  /** Last account roster whose provisioning was attempted in this container.
+   *  Missing-session reconciliation must not hot-loop an unchanged failed
+   *  copy and invalidate the peer sessions it is trying to repair. */
+  provisionAttemptedFingerprint?: string;
+  /** An incomplete account copy that must be retried on the bounded timer. */
+  provisionRetryFingerprint?: string;
+  /** Self-scheduled retry after a failed install/configuration pass. */
+  browserRetryTimer: ReturnType<typeof setTimeout> | null;
+  /** 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>;
+  /** 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>;
+  /** One reconcile loop per channel. It covers ordinary missing agents and
+   *  stale-session recycling without overlapping factory creates. */
+  reconcileReady: 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
+   *  this flag and the channel-map identity before mutating or spawning. */
+  closed: boolean;
   /** Agents with turn output already streamed for the current turn — i.e. the
    *  cloud has buffered content for them (see ChannelRouter.turnBuffer). */
   openTurns: Set<string>;
+  /** Agents with a delivered turn that has not reached a terminal event yet.
+   *  Unlike openTurns, this covers thinking/tool/permission time before text. */
+  activeTurns: Map<string, number>;
   /** Agents whose current turn was interrupted (ESC) — their next
    *  turn_complete is flagged `aborted` so the cloud DISCARDS the buffered
    *  half-turn instead of delivering it to @-mentioned peers. */
@@ -116,9 +172,30 @@ interface Channel {
    *  ensure runs on every message). Live sessions read MCP config at spawn,
    *  so a mid-task write takes effect on the next (re)spawn. */
   mcpConfigFingerprint?: string;
+  /** Serialize gateway config writes so two ensures cannot publish stale
+   *  content and then memoize the newer fingerprint over it. */
+  mcpConfigWrite: Promise<void> | null;
+  /** Account provisioning can overwrite per-engine config without changing
+   *  the desired gateway fingerprint. A monotonic epoch prevents an older
+   *  in-flight writer from clearing a newer provisioning mutation. */
+  mcpConfigDirtyEpoch: number;
+  /** Dirty epoch covered by the last successful gateway publication. */
+  mcpConfigAppliedEpoch: number;
+  /** 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. */
+  configGeneration: number;
   /** Agents with a reconcile-spawn in flight (ADR-049 mid-task adds) — guards
    *  against a concurrent ensure double-spawning the same new agent. */
   spawning: Set<string>;
+  /** Factory creates are externally side-effecting before they bind. Teardown
+   *  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>>;
+  /** 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. */
+  eventOperations: Set<Promise<unknown>>;
   /** ADR-076: which engine account each agent's live session is bound to, so a
    *  rate-limit can cool THAT account and rotate off it. */
   accountByAgent: Map<string, string>;
@@ -136,6 +213,10 @@ const MAX_RESPAWNS_PER_AGENT = 5;
 const MAX_ROTATIONS_PER_AGENT = 6;
 /** A burned respawn budget resets after this quiet period (see reconcile). */
 const RESPAWN_COOLDOWN_MS = 10 * 60_000;
+/** ADR-053: gap between browser-install retries. Ensures fire every couple of
+ *  seconds; a container-gone failure returns instantly, so without this the
+ *  retry would spin npx continuously for the life of a broken task. */
+const BROWSER_RETRY_COOLDOWN_MS = 60_000;
 
 /** Substrings in an agent's error output that mean "config was
  *  unlinked between runs" — repair-and-respawn covers the common
@@ -146,9 +227,18 @@ const CLAUDE_CONFIG_MISSING_PATTERNS = [
   /\/\.claude\.json/i,
 ];
 
-class Orchestrator {
+export class Orchestrator {
   private readonly channels = new Map<string, Channel>();
   private readonly channelSpecs = new Map<string, ChannelEnsureInput>();
+  /** Teardown tombstones prevent a cloud ensure from reopening a task between
+   *  session close and container stop/removal. Cleared only by task-up. */
+  private readonly blockedTasks = new Set<string>();
+  /** Every teardown caller for a task joins the same container-reuse fence. */
+  private readonly channelClosures = new Map<string, Promise<void>>();
+  /** Host lifecycle commands can arrive concurrently over the bridge/local
+   *  UI. Serialize each task through container creation/destruction so a
+   *  later command cannot overtake an earlier one after channel close. */
+  private readonly taskLifecycleTails = new Map<string, Promise<void>>();
   private readonly hostSubscribers = new Set<HostEventSubscriber>();
 
   constructor(private readonly factory: AgentSessionFactory) {}
@@ -160,6 +250,36 @@ class Orchestrator {
     return () => this.hostSubscribers.delete(fn);
   }
 
+  /** Run one task lifecycle mutation in arrival order. Different task ids
+   *  remain fully concurrent. The queue tail never rejects, so one failed
+   *  command cannot poison later recovery. */
+  async runTaskLifecycle<T>(
+    taskId: string,
+    operation: () => Promise<T>,
+  ): Promise<T> {
+    const previous =
+      this.taskLifecycleTails.get(taskId) ?? Promise.resolve();
+    let release!: () => void;
+    const current = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const tail = previous.catch(() => {}).then(() => current);
+    this.taskLifecycleTails.set(taskId, tail);
+    await previous.catch(() => {});
+    try {
+      // Boot recovery can still be starting/copying into this task's stable
+      // container name while bridge and local-UI commands are already live.
+      // Join that per-task barrier before any queued create/destroy mutation.
+      await taskRecoveryComplete(taskId);
+      return await operation();
+    } finally {
+      release();
+      if (this.taskLifecycleTails.get(taskId) === tail) {
+        this.taskLifecycleTails.delete(taskId);
+      }
+    }
+  }
+
   /** Emit a host-originated system note into a task's channel (ADR-027). */
   emitSystemNote(taskId: string, text: string): void {
     this.emitHost({ kind: "system.note", taskId, text });
@@ -179,6 +299,7 @@ class Orchestrator {
 
   registerChannelSpec(spec: ChannelEnsureInput): void {
     this.channelSpecs.set(spec.taskId, spec);
+    if (this.blockedTasks.has(spec.taskId)) return;
     // ADR-049: the cloud re-sends the spec on every message AND right after a
     // mid-task roster/participant change. If the channel is already live,
     // fold the fresh spec in: append new roster agents (their sessions spawn
@@ -190,6 +311,11 @@ 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 previousMcpShape = JSON.stringify({
+      connections: channel.mcpConnections,
+      kinds: [...new Set(channel.roster.map((agent) => agent.kind))].sort(),
+    });
     const known = new Set(channel.roster.map((a) => a.id));
     // 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
@@ -211,6 +337,13 @@ class Orchestrator {
     channel.browserTesting = spec.browserTesting === true;
     channel.sharedFiles = spec.sharedFiles ?? "ro";
     channel.mcpConnections = spec.mcpConnections ?? [];
+    const nextMcpShape = JSON.stringify({
+      connections: channel.mcpConnections,
+      kinds: [...new Set(channel.roster.map((agent) => agent.kind))].sort(),
+    });
+    if (nextMcpShape !== previousMcpShape) {
+      channel.mcpConfigDirtyEpoch += 1;
+    }
     for (const agent of channel.roster) {
       channel.preambles.set(
         agent.id,
@@ -227,9 +360,52 @@ class Orchestrator {
         ),
       );
     }
+    if (!browserWasEnabled && channel.browserTesting) {
+      void this.enableBrowserTesting(channel);
+    } else if (browserWasEnabled && !channel.browserTesting) {
+      if (channel.provisionRetryFingerprint) {
+        // Browser readiness is no longer required, but a failed extra-account
+        // copy still needs its bounded retry.
+        this.scheduleBrowserRetry(channel);
+      } else {
+        this.clearBrowserRetry(channel);
+      }
+      // Config files copied while browser readiness was required no longer
+      // need to wait for a download. They still need a safe process reload.
+      for (const agentId of channel.browserPendingStaleSessions) {
+        channel.browserStaleSessions.add(agentId);
+      }
+      channel.browserPendingStaleSessions.clear();
+      void this.reconcileIfStarted(channel).catch((err: unknown) => {
+        console.warn(
+          `[orchestrator] ${channel.taskId}: browser-disable reconcile failed: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        );
+      });
+    }
+  }
+
+  /** Materialize a browser flag enabled after the channel already started. */
+  private async enableBrowserTesting(channel: Channel): Promise<void> {
+    try {
+      await this.ensureBrowserSetup(
+        channel,
+        channel.roster.some((agent) => agent.kind === "codex"),
+        Boolean(channel.provisionRetryFingerprint),
+      );
+      await this.reconcileIfStarted(channel);
+    } catch (err) {
+      console.warn(
+        `[browser] task ${channel.taskId}: enable failed: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    }
   }
 
   private async getOrCreateChannel(taskId: string): Promise<Channel | null> {
+    if (this.blockedTasks.has(taskId)) return null;
     const existing = this.channels.get(taskId);
     if (existing) return existing;
 
@@ -275,7 +451,20 @@ class Orchestrator {
       preambles,
       firstTurns,
       sessionsReady: null,
+      browserReady: false,
+      browserSetup: null,
+      browserSetupCodexHomes: null,
+      browserSetupEngineKinds: null,
+      browserSetupProvisionFingerprint: null,
+      browserSetupCoverage: null,
+      browserRetryTimer: null,
+      browserStaleSessions: new Set(),
+      browserPendingStaleSessions: new Set(),
+      reconcileReady: null,
+      reconcileAgain: false,
+      closed: false,
       openTurns: new Set(),
+      activeTurns: new Map(),
       interrupted: new Set(),
       respawns: new Map(),
       respawnLastAt: new Map(),
@@ -283,7 +472,13 @@ class Orchestrator {
       browserTesting: spec.browserTesting === true,
       sharedFiles: spec.sharedFiles ?? "ro",
       mcpConnections: spec.mcpConnections ?? [],
+      mcpConfigWrite: null,
+      mcpConfigDirtyEpoch: 1,
+      mcpConfigAppliedEpoch: 0,
+      configGeneration: 0,
       spawning: new Set(),
+      factoryOperations: new Set(),
+      eventOperations: new Set(),
       accountByAgent: new Map(),
       lastPrompt: new Map(),
       rotations: new Map(),
@@ -304,6 +499,11 @@ class Orchestrator {
    * Returns whether sessions are ready.
    */
   private async ensureSessions(channel: Channel): Promise<boolean> {
+    // Boot recovery may be restarting this exact container and copying the
+    // full Codex directory. Wait only for this task's recovery barrier so that
+    // copy cannot land after browser/MCP materialization and erase config.
+    await taskRecoveryComplete(channel.taskId);
+    if (!this.isActiveChannel(channel)) 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
     // (startSessions awaits docker work before populating it — the old boolean
@@ -314,7 +514,7 @@ class Orchestrator {
       // next ensure retries (e.g. the task wasn't `running` yet).
       channel.sessionsReady.then(
         (ok) => {
-          if (!ok) channel.sessionsReady = null;
+          if (!ok && this.isActiveChannel(channel)) channel.sessionsReady = null;
         },
         (err: unknown) => {
           // A start failure retries on the next ensure — but it must be
@@ -324,58 +524,536 @@ class Orchestrator {
             `[orchestrator] ${channel.taskId}: session start failed: ` +
               `${err instanceof Error ? (err.stack ?? err.message) : String(err)}`,
           );
-          channel.sessionsReady = null;
+          if (this.isActiveChannel(channel)) channel.sessionsReady = null;
         },
       );
     }
     const ready = await channel.sessionsReady;
+    if (!this.isActiveChannel(channel)) return false;
+    // A live browser-enable or retry starts outside this ensure path. Join its
+    // serialized setup before reconciliation/delivery so the next message
+    // cannot reach a session that still holds the old MCP definition.
+    if (ready && channel.browserSetup) {
+      await this.ensureBrowserSetup(
+        channel,
+        channel.roster.some((agent) => agent.kind === "codex"),
+      );
+      if (!this.isActiveChannel(channel)) return false;
+    }
     // ADR-049 reconcile pass: spawn any roster agent that has no live session
     // yet — the initial batch, host-restart recovery, and mid-task adds all
     // converge here. No-op when every roster agent has a session.
     if (ready) {
-      await this.reconcileSessions(channel);
       // ADR-057: keep the container's MCP configs current so a connection
-      // added mid-task lands (effective at each session's next spawn).
+      // or engine added mid-task lands before its missing session spawns.
       await this.ensureMcpConfig(channel);
+      if (!this.isActiveChannel(channel)) return false;
+      await this.reconcileSessions(channel);
     }
     return ready;
   }
 
+  /**
+   * Background browser work may recycle sessions only after the memoized
+   * initial start has finished. Waiting here prevents live enable/retry from
+   * reconciling the same missing agents while startSessions is creating them.
+   */
+  private async reconcileIfStarted(channel: Channel): Promise<void> {
+    const starting = channel.sessionsReady;
+    if (!starting) return;
+    const ready = await starting;
+    if (ready && this.isActiveChannel(channel)) {
+      await this.reconcileSessions(channel);
+    }
+  }
+
+  /** Is this exact channel generation still the task's live channel? */
+  private isActiveChannel(channel: Channel): boolean {
+    return !channel.closed && this.channels.get(channel.taskId) === channel;
+  }
+
+  /**
+   * The single account/browser-materialization gate for a channel.
+   *
+   * Initial start, a missing-session reconcile, live enable, rotation, and the
+   * failure retry all join the same promise. Even browser-disabled account
+   * copies use this gate: a false→true toggle queues migration after the older
+   * copy, so that copy cannot land last and erase the managed browser block.
+   */
+  private codexHomes(hasCodex: boolean): string[] {
+    if (!hasCodex) return [];
+    const homes = resolveEngineAccounts("codex")
+      .map((account) => account.configDir?.containerDir)
+      .filter((home): home is string => Boolean(home));
+    return [...new Set([DEFAULT_CODEX_HOME, ...homes])];
+  }
+
+  private noteProvisionMutation(
+    channel: Channel,
+    waitForBrowserReadiness: boolean,
+  ): void {
+    if (!this.isActiveChannel(channel)) return;
+    channel.configGeneration += 1;
+    channel.mcpConfigDirtyEpoch += 1;
+    for (const agentId of channel.sessions.keys()) {
+      if (waitForBrowserReadiness) {
+        channel.browserPendingStaleSessions.add(agentId);
+      } else {
+        channel.browserStaleSessions.add(agentId);
+      }
+    }
+  }
+
+  private fenceConfigGeneration(channel: Channel): void {
+    if (this.isActiveChannel(channel)) channel.configGeneration += 1;
+  }
+
+  private provisionFingerprint(kinds: readonly string[]): string {
+    const accounts = kinds.flatMap((kind) =>
+      resolveEngineAccounts(kind)
+        .filter((account) => !account.isDefault && account.configDir)
+        .map((account) => ({
+          kind,
+          id: account.id,
+          hostDir: account.configDir!.hostDir,
+          containerDir: account.configDir!.containerDir,
+        })),
+    );
+    accounts.sort((left, right) =>
+      JSON.stringify(left).localeCompare(JSON.stringify(right)),
+    );
+    return JSON.stringify({
+      kinds: [...new Set(kinds)].sort(),
+      accounts,
+    });
+  }
+
+  private async ensureBrowserSetup(
+    channel: Channel,
+    hasCodex: boolean,
+    forceProvision = false,
+  ): Promise<BrowserSetup> {
+    const unavailable: BrowserSetup = {
+      ready: false,
+      configured: false,
+      changed: false,
+    };
+    if (!this.isActiveChannel(channel)) return unavailable;
+    const requestedBrowser = channel.browserTesting;
+    const requestedHasCodex =
+      hasCodex || channel.roster.some((agent) => agent.kind === "codex");
+    const requestedHomes = requestedBrowser
+      ? this.codexHomes(requestedHasCodex)
+      : [];
+    const requestedKinds = [
+      ...new Set(channel.roster.map((agent) => agent.kind)),
+    ];
+    const requestedProvisionFingerprint =
+      this.provisionFingerprint(requestedKinds);
+    const mayProvisionConfig = requestedKinds.some((kind) =>
+      resolveEngineAccounts(kind).some(
+        (account) => !account.isDefault && Boolean(account.configDir),
+      ),
+    );
+
+    const inFlight = channel.browserSetup;
+    if (inFlight) {
+      const coveredHomes = channel.browserSetupCodexHomes ?? [];
+      const coveredKinds = channel.browserSetupEngineKinds ?? [];
+      const coveredProvisionFingerprint =
+        channel.browserSetupProvisionFingerprint;
+      const coverage = channel.browserSetupCoverage;
+      const setup = await inFlight;
+      if (!this.isActiveChannel(channel)) return unavailable;
+      const latestBrowser = channel.browserTesting;
+      const latestHasCodex =
+        requestedHasCodex ||
+        channel.roster.some((agent) => agent.kind === "codex");
+      const latestHomes = latestBrowser
+        ? this.codexHomes(latestHasCodex)
+        : [];
+      const latestKinds = [
+        ...new Set(channel.roster.map((agent) => agent.kind)),
+      ];
+      const latestProvisionFingerprint =
+        this.provisionFingerprint(latestKinds);
+      if (
+        (latestBrowser &&
+          coverage?.browserAttempted !== true &&
+          coverage?.browserRequested === false) ||
+        (latestBrowser && coverage?.skippedBecauseDisabled === true) ||
+        latestHomes.some((home) => !coveredHomes.includes(home)) ||
+        latestKinds.some((kind) => !coveredKinds.includes(kind)) ||
+        latestProvisionFingerprint !== coveredProvisionFingerprint ||
+        (forceProvision && coverage?.provisionAttempted !== true)
+      ) {
+        return this.ensureBrowserSetup(
+          channel,
+          latestHasCodex,
+          forceProvision,
+        );
+      }
+      return setup;
+    }
+
+    const coverage = {
+      browserRequested: requestedBrowser,
+      browserAttempted: false,
+      skippedBecauseDisabled: false,
+      provisionAttempted: false,
+    };
+    const core = (async (): Promise<BrowserSetup> => {
+      let setup: BrowserSetup;
+      try {
+        // Account copies and MCP migration share one serialized generation.
+        // Otherwise a concurrent provision can overwrite config.toml after
+        // migration and immediately strand an extra-account Codex session.
+        const shouldProvision =
+          forceProvision ||
+          channel.provisionAttemptedFingerprint !==
+            requestedProvisionFingerprint;
+        if (shouldProvision) {
+          coverage.provisionAttempted = true;
+          if (mayProvisionConfig) {
+            // Fence a factory that started before the copy without declaring a
+            // disk mutation until the aggregate result says bytes may have
+            // landed. A total failure must not churn live peers.
+            this.fenceConfigGeneration(channel);
+          }
+          let copiedOrUnknown = false;
+          try {
+            const provisioned = await provisionEngineAccounts(
+              channel.containerName,
+              requestedKinds,
+            );
+            copiedOrUnknown =
+              provisioned.copied > 0 || provisioned.mayHaveMutated;
+            if (provisioned.failed > 0) {
+              channel.provisionRetryFingerprint =
+                requestedProvisionFingerprint;
+            } else {
+              channel.provisionRetryFingerprint = undefined;
+            }
+          } catch (err) {
+            // A thrown multi-command copy may have landed before failing.
+            copiedOrUnknown = true;
+            channel.provisionRetryFingerprint =
+              requestedProvisionFingerprint;
+            throw err;
+          } finally {
+            // Cache the ATTEMPT even when incomplete. Immediate reconcile
+            // loops may replace missing agents, but only the bounded retry
+            // timer may repeat a failed account copy.
+            channel.provisionAttemptedFingerprint =
+              requestedProvisionFingerprint;
+            if (mayProvisionConfig) {
+              if (copiedOrUnknown) {
+                // A process that starts during a real/partial copy observes
+                // this second bump, while gateway config is reasserted.
+                this.noteProvisionMutation(
+                  channel,
+                  channel.browserTesting,
+                );
+              } else {
+                this.fenceConfigGeneration(channel);
+              }
+            }
+          }
+        }
+        if (
+          !this.isActiveChannel(channel) ||
+          !requestedBrowser ||
+          !channel.browserTesting
+        ) {
+          if (
+            this.isActiveChannel(channel) &&
+            channel.provisionRetryFingerprint
+          ) {
+            this.scheduleBrowserRetry(channel);
+          }
+          coverage.skippedBecauseDisabled =
+            this.isActiveChannel(channel) &&
+            (!requestedBrowser || !channel.browserTesting);
+          return unavailable;
+        }
+        coverage.browserAttempted = true;
+        setup = await setupBrowserTesting(
+          channel.taskId,
+          channel.containerName,
+          requestedHasCodex,
+          requestedHomes,
+        );
+      } catch (err) {
+        console.warn(
+          `[browser] task ${channel.taskId}: setup failed: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        );
+        setup = unavailable;
+      }
+
+      if (!this.isActiveChannel(channel)) return unavailable;
+
+      channel.browserReady = setup.ready && setup.configured;
+      if (setup.changed) {
+        channel.configGeneration += 1;
+        for (const agentId of channel.sessions.keys()) {
+          channel.browserPendingStaleSessions.add(agentId);
+        }
+      }
+      if (channel.browserReady) {
+        for (const agentId of channel.browserPendingStaleSessions) {
+          channel.browserStaleSessions.add(agentId);
+        }
+        channel.browserPendingStaleSessions.clear();
+      }
+
+      if (channel.browserReady && !channel.provisionRetryFingerprint) {
+        this.clearBrowserRetry(channel);
+        console.log(`[browser] task ${channel.taskId}: browser ready`);
+      } else {
+        this.scheduleBrowserRetry(channel);
+      }
+      return setup;
+    })();
+
+    let run: Promise<BrowserSetup>;
+    run = core.finally(() => {
+      if (channel.browserSetup === run) {
+        channel.browserSetup = null;
+        channel.browserSetupCodexHomes = null;
+        channel.browserSetupEngineKinds = null;
+        channel.browserSetupProvisionFingerprint = null;
+        channel.browserSetupCoverage = null;
+      }
+    });
+    channel.browserSetup = run;
+    channel.browserSetupCodexHomes = requestedHomes;
+    channel.browserSetupEngineKinds = requestedKinds;
+    channel.browserSetupProvisionFingerprint = requestedProvisionFingerprint;
+    channel.browserSetupCoverage = coverage;
+    const setup = await run;
+    if (!this.isActiveChannel(channel)) return unavailable;
+    const latestBrowser = channel.browserTesting;
+    const latestHasCodex =
+      requestedHasCodex ||
+      channel.roster.some((agent) => agent.kind === "codex");
+    const latestHomes = latestBrowser
+      ? this.codexHomes(latestHasCodex)
+      : [];
+    const latestKinds = [
+      ...new Set(channel.roster.map((agent) => agent.kind)),
+    ];
+    const latestProvisionFingerprint = this.provisionFingerprint(latestKinds);
+    if (
+      (latestBrowser &&
+        !coverage.browserAttempted &&
+        !coverage.browserRequested) ||
+      (latestBrowser && coverage.skippedBecauseDisabled) ||
+      latestHomes.some((home) => !requestedHomes.includes(home)) ||
+      latestKinds.some((kind) => !requestedKinds.includes(kind)) ||
+      latestProvisionFingerprint !== requestedProvisionFingerprint ||
+      (forceProvision && !coverage.provisionAttempted)
+    ) {
+      return this.ensureBrowserSetup(channel, latestHasCodex, forceProvision);
+    }
+    return setup;
+  }
+
+  private clearBrowserRetry(channel: Channel): void {
+    if (channel.browserRetryTimer) {
+      clearTimeout(channel.browserRetryTimer);
+      channel.browserRetryTimer = null;
+    }
+  }
+
+  /** A failed setup gets a real retry even if no message/ensure arrives. */
+  private scheduleBrowserRetry(channel: Channel): void {
+    if (
+      (!channel.browserTesting && !channel.provisionRetryFingerprint) ||
+      !this.isActiveChannel(channel) ||
+      channel.browserRetryTimer
+    ) {
+      return;
+    }
+    const timer = setTimeout(() => {
+      if (channel.browserRetryTimer === timer) {
+        channel.browserRetryTimer = null;
+      }
+      if (!this.isActiveChannel(channel)) return;
+      const forceProvision = Boolean(channel.provisionRetryFingerprint);
+      void this.ensureBrowserSetup(
+        channel,
+        channel.roster.some((a) => a.kind === "codex"),
+        forceProvision,
+      ).then(() => {
+        if (this.isActiveChannel(channel)) return this.reconcileIfStarted(channel);
+      }).catch((err: unknown) => {
+        console.warn(
+          `[browser] task ${channel.taskId}: retry reconcile failed: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        );
+      });
+    }, BROWSER_RETRY_COOLDOWN_MS);
+    channel.browserRetryTimer = timer;
+  }
+
   /** Write the task's MCP configs when the connection set changed. */
   private async ensureMcpConfig(channel: Channel): Promise<void> {
-    const fingerprint = JSON.stringify(channel.mcpConnections.map((c) => c.id));
-    if (channel.mcpConfigFingerprint === fingerprint) return;
+    if (!this.isActiveChannel(channel)) return;
+    const inFlight = channel.mcpConfigWrite;
+    if (inFlight) {
+      await inFlight;
+      // Recompute after the serialized writer: the channel spec may have
+      // changed while we waited, in which case this caller owns the next pass.
+      if (this.isActiveChannel(channel)) await this.ensureMcpConfig(channel);
+      return;
+    }
+
+    let run: Promise<void>;
+    run = this.writeMcpConfigPass(channel).finally(() => {
+      if (channel.mcpConfigWrite === run) channel.mcpConfigWrite = null;
+    });
+    channel.mcpConfigWrite = run;
+    await run;
+  }
+
+  private async writeMcpConfigPass(channel: Channel): Promise<void> {
+    if (!this.isActiveChannel(channel)) return;
+    const connections = channel.mcpConnections.map((connection) => ({
+      id: connection.id,
+      slug: connection.slug,
+    }));
+    const engineKinds = [
+      ...new Set(channel.roster.map((agent) => agent.kind)),
+    ].sort();
+    const codexHomes = engineKinds.includes("codex")
+      ? this.codexHomes(true)
+      : [];
+    const fingerprint = JSON.stringify({
+      connections,
+      engineKinds,
+      codexHomes,
+    });
+    const dirtyEpoch = channel.mcpConfigDirtyEpoch;
+    const repairingProvisionedConfig =
+      channel.mcpConfigAppliedEpoch !== dirtyEpoch &&
+      channel.mcpConfigFingerprint === fingerprint;
+    if (
+      channel.mcpConfigFingerprint === fingerprint &&
+      channel.mcpConfigAppliedEpoch === dirtyEpoch
+    ) {
+      return;
+    }
     const hadPrevious = channel.mcpConfigFingerprint !== undefined;
-    channel.mcpConfigFingerprint = fingerprint;
-    await setupMcpTaskConfig(
+    let previous:
+      | {
+          connections: Array<{ id: string; slug: string }>;
+          engineKinds: string[];
+          codexHomes?: string[];
+        }
+      | undefined;
+    try {
+      previous = channel.mcpConfigFingerprint
+        ? (JSON.parse(channel.mcpConfigFingerprint) as typeof previous)
+        : undefined;
+    } catch {
+      previous = undefined;
+    }
+    const connectionsChanged =
+      JSON.stringify(previous?.connections) !== JSON.stringify(connections);
+    const addedKinds = new Set(
+      engineKinds.filter((kind) => !previous?.engineKinds?.includes(kind)),
+    );
+    const hadLiveSessions = channel.sessions.size > 0;
+    const configured = await setupMcpTaskConfig(
       channel.taskId,
       channel.containerName,
-      channel.mcpConnections,
-      channel.roster.map((a) => a.kind),
+      connections,
+      engineKinds,
+      codexHomes,
     );
+    if (!configured || !this.isActiveChannel(channel)) return;
+    channel.configGeneration += 1;
+    channel.mcpConfigFingerprint = fingerprint;
+    // Only acknowledge the epoch this write observed. If provisioning dirtied
+    // the files while docker exec was in flight, the newer epoch remains
+    // uncovered and the serialized ensure immediately publishes another pass.
+    channel.mcpConfigAppliedEpoch = dirtyEpoch;
     // 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
     // sessions so the change actually reaches the agents; busy agents keep
-    // their turn (and in-memory context) and pick it up on a later change or
-    // natural respawn. Trade-off: a recycled agent loses its in-memory
+    // their turn (and in-memory context), remain marked stale, and recycle at
+    // turn_complete. Trade-off: a recycled agent loses its in-memory
     // context and is re-briefed from chat — same as any respawn, and better
     // than never seeing the connection the user just added. Skipped on the
-    // channel's first fingerprint (sessions just spawned with this config).
-    if (hadPrevious) await this.recycleIdleSessions(channel);
+    // channel's first successful fingerprint unless sessions already spawned
+    // after a failed write and therefore need to reload the recovered config.
+    // A kind-only change is written before missing-agent reconciliation, so
+    // existing engines keep the same files; only an already-live session of
+    // the newly-added kind could be stale.
+    if (repairingProvisionedConfig) {
+      // 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);
+    } else if (!hadPrevious && hadLiveSessions) {
+      this.markSessionsStale(channel);
+    } else if (hadPrevious && connectionsChanged) {
+      this.markSessionsStale(channel);
+    } else if (hadPrevious && addedKinds.size > 0) {
+      const affected = channel.roster
+        .filter((agent) => addedKinds.has(agent.kind))
+        .map((agent) => agent.id);
+      this.markSessionsStale(channel, affected);
+    }
+  }
+
+  /**
+   * Mark current sessions stale after an MCP config change. Publication stays
+   * pure: callers reconcile only after the writer promise has cleared, avoiding
+   * writer -> reconcile -> same-writer self-deadlock. Busy sessions remain
+   * marked until their turn_complete event.
+   */
+  private markSessionsStale(
+    channel: Channel,
+    agentIds: Iterable<string> = channel.sessions.keys(),
+  ): void {
+    if (!this.isActiveChannel(channel)) return;
+    for (const agentId of agentIds) {
+      if (channel.sessions.has(agentId)) {
+        channel.browserStaleSessions.add(agentId);
+      }
+    }
   }
 
-  /** Close + respawn every session with no open turn (MCP set changed). */
-  private async recycleIdleSessions(channel: Channel): Promise<void> {
+  /** Close stale sessions that are idle, without recursively reconciling. */
+  private async closeIdleStaleSessions(channel: Channel): Promise<number> {
     let recycled = 0;
-    for (const [agentId, session] of [...channel.sessions]) {
-      if (channel.openTurns.has(agentId)) continue; // never mid-turn
-      if (channel.spawning.has(agentId)) continue;
+    for (const agentId of [...channel.browserStaleSessions]) {
+      if (!this.isActiveChannel(channel)) return recycled;
+      if (
+        channel.activeTurns.has(agentId) ||
+        channel.openTurns.has(agentId) ||
+        channel.spawning.has(agentId)
+      ) {
+        continue;
+      }
+      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.
+      if (!session) {
+        channel.browserStaleSessions.delete(agentId);
+        continue;
+      }
+      channel.browserStaleSessions.delete(agentId);
       channel.sessions.delete(agentId);
       try {
-        // close() flips the adapter's `closed` flag first, so the session's
-        // exit is suppressed — no budget increment, no agent.exit noise, no
-        // race with the respawn below (recoverClaudeAgent's pattern).
+        // 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.
@@ -386,82 +1064,124 @@ class Orchestrator {
       console.log(
         `[orchestrator] ${channel.taskId}: recycled ${recycled} idle session(s) for MCP config change`,
       );
-      await this.reconcileSessions(channel);
     }
+    return recycled;
   }
 
-  /** Spawn sessions for roster agents added after the initial start. */
+  /** Serialize all missing-session and stale-session reconciliation. */
   private async reconcileSessions(channel: Channel): Promise<void> {
-    const missing = channel.roster.filter((agent) => {
-      if (channel.sessions.has(agent.id) || channel.spawning.has(agent.id)) {
-        return false;
-      }
-      // Crash-loop budget: an agent whose session keeps dying stops being
-      // respawned after MAX_RESPAWNS_PER_AGENT (the exit paths increment) —
-      // but a budget that has been cold for RESPAWN_COOLDOWN_MS resets, so
-      // the task heals itself once the cause (a missing CLI on the shared
-      // volume, a broken config) is fixed, instead of staying dead until a
-      // host restart.
-      if ((channel.respawns.get(agent.id) ?? 0) > MAX_RESPAWNS_PER_AGENT) {
-        const lastAt = channel.respawnLastAt.get(agent.id) ?? 0;
-        if (Date.now() - lastAt < RESPAWN_COOLDOWN_MS) return false;
-        channel.respawns.set(agent.id, 0);
-      }
-      return true;
-    });
-    if (missing.length === 0) return;
+    if (!this.isActiveChannel(channel)) return;
+    if (channel.reconcileReady) {
+      channel.reconcileAgain = true;
+      return channel.reconcileReady;
+    }
 
-    const task = getHostTask(channel.taskId);
-    if (!task || task.statusMirror !== "running") return;
+    const core = (async () => {
+      do {
+        channel.reconcileAgain = false;
+        await this.reconcileSessionsInner(channel);
+      } while (channel.reconcileAgain && this.isActiveChannel(channel));
+    })();
+    let run: Promise<void>;
+    run = core.finally(() => {
+      if (channel.reconcileReady === run) channel.reconcileReady = null;
+    });
+    channel.reconcileReady = run;
+    return run;
+  }
 
-    for (const agent of missing) channel.spawning.add(agent.id);
-    try {
-      // Same per-agent materialisation the initial start does: package
-      // skills (idempotent — only the new agents' installs run), and the
-      // shared `uai` CLI rewritten for the full roster.
-      await installPackageSkills(channel.taskId, missing);
-      if (channel.browserTesting) {
-        await setupBrowserTesting(
-          channel.taskId,
-          channel.containerName,
-          channel.roster.some((a) => a.kind === "codex"),
-        );
-      }
-      const apiUrl = apiUrlFromCloudUrl(env.UAI_CLOUD_URL);
-      const cliSecret = loadTaskCliSecret(channel.taskId);
-      writeAgentCli(channel.taskId, channel.roster, apiUrl);
+  private async reconcileSessionsInner(channel: Channel): Promise<void> {
+    while (this.isActiveChannel(channel)) {
+      await this.closeIdleStaleSessions(channel);
+      if (!this.isActiveChannel(channel)) return;
+
+      // Snapshot before any slow work. An agent added while this generation is
+      // setting up is handled by the next loop, with a setup pass that includes
+      // its engine (especially the Claude-only -> Codex transition).
+      const roster = [...channel.roster];
+      const missing = roster.filter((agent) => {
+        if (channel.sessions.has(agent.id) || channel.spawning.has(agent.id)) {
+          return false;
+        }
+        // Crash-loop budget: an agent whose session keeps dying stops being
+        // respawned after MAX_RESPAWNS_PER_AGENT (the exit paths increment) —
+        // but a cold budget resets so the task can heal after the cause clears.
+        if ((channel.respawns.get(agent.id) ?? 0) > MAX_RESPAWNS_PER_AGENT) {
+          const lastAt = channel.respawnLastAt.get(agent.id) ?? 0;
+          if (Date.now() - lastAt < RESPAWN_COOLDOWN_MS) return false;
+          channel.respawns.set(agent.id, 0);
+        }
+        return true;
+      });
+      if (missing.length === 0) return;
 
-      // ADR-076: extra config-dir accounts for the newly-spawning agents.
-      await provisionEngineAccounts(
-        channel.containerName,
-        missing.map((a) => a.kind),
-      );
+      const task = getHostTask(channel.taskId);
+      if (!task || task.statusMirror !== "running") return;
 
-      for (const agent of missing) {
-        const session = await this.factory.create({
-          taskId: channel.taskId,
-          agent,
-          containerName: channel.containerName,
-          systemPreamble: channel.preambles.get(agent.id) ?? "",
-          agentEnv: this.accountAgentEnv(
+      for (const agent of missing) channel.spawning.add(agent.id);
+      try {
+        // Same per-agent materialisation the initial start does. Browser setup
+        // is awaited before EVERY missing-session spawn: that reasserts configs
+        // clobbered by resume/auth injection and covers roster generation.
+        await installPackageSkills(channel.taskId, missing);
+        if (!this.isActiveChannel(channel)) return;
+
+        // One materialization gate owns provisioning and (when enabled)
+        // browser migration. This remains serialized across a live false→true
+        // transition, so an older account copy cannot land after migration.
+        await this.ensureBrowserSetup(
+          channel,
+          roster.some((a) => a.kind === "codex"),
+        );
+        if (!this.isActiveChannel(channel)) return;
+        // Provisioning may have refreshed an extra account's whole config
+        // directory. Reassert gateway entries in every Codex home before any
+        // process for this generation can start.
+        await this.ensureMcpConfig(channel);
+        if (!this.isActiveChannel(channel)) return;
+        // Browser and gateway definitions are both loaded only at process
+        // start. A writer marks the previous generation stale; close its idle
+        // subset now regardless of the browser feature flag.
+        await this.closeIdleStaleSessions(channel);
+        if (!this.isActiveChannel(channel)) return;
+
+        const apiUrl = apiUrlFromCloudUrl(env.UAI_CLOUD_URL);
+        const cliSecret = loadTaskCliSecret(channel.taskId);
+        writeAgentCli(channel.taskId, roster, apiUrl);
+
+        for (const agent of missing) {
+          if (!this.isActiveChannel(channel)) return;
+          // Another recovery path may have filled this slot while the browser
+          // setup was awaiting.
+          if (channel.sessions.has(agent.id)) continue;
+          const session = await this.createAndBindStableSession(
             channel,
-            agent,
-            agentCliEnv(
-              channel.taskId,
+            agent.id,
+            {
+              taskId: channel.taskId,
               agent,
-              task.ownerUserId,
-              apiUrl,
-              cliSecret,
-            ),
-          ),
-        });
-        channel.sessions.set(agent.id, session);
-        session.onEvent((event) => {
-          void this.handleAgentEvent(channel, agent.id, event);
-        });
+              containerName: channel.containerName,
+              systemPreamble: channel.preambles.get(agent.id) ?? "",
+              agentEnv: this.accountAgentEnv(
+                channel,
+                agent,
+                agentCliEnv(
+                  channel.taskId,
+                  agent,
+                  task.ownerUserId,
+                  apiUrl,
+                  cliSecret,
+                ),
+              ),
+            },
+          );
+          if (!session) return;
+        }
+      } finally {
+        for (const agent of missing) channel.spawning.delete(agent.id);
       }
-    } finally {
-      for (const agent of missing) channel.spawning.delete(agent.id);
+      // Loop once more: roster additions and sessions retired by a config
+      // rewrite each get a setup pass for their exact roster generation.
     }
   }
 
@@ -487,9 +1207,105 @@ class Orchestrator {
     return { ...base, ...account.execEnv };
   }
 
+  /** Install a session with an event handler scoped to this exact generation. */
+  private bindSession(
+    channel: Channel,
+    agentId: string,
+    session: AgentSession,
+  ): void {
+    channel.sessions.set(agentId, session);
+    session.onEvent((event) => {
+      // Recycle/teardown deletes the old session before calling close().
+      // Adapters deliberately emit a final exit event; without this identity
+      // guard it can delete a replacement or consume its respawn budget.
+      if (
+        !this.isActiveChannel(channel) ||
+        channel.sessions.get(agentId) !== session
+      ) {
+        return;
+      }
+      const operation = this.handleAgentEvent(channel, agentId, event).catch(
+        (err: unknown) => {
+          console.warn(
+            `[orchestrator] ${channel.taskId}/${agentId}: event handling failed: ${
+              err instanceof Error ? (err.stack ?? err.message) : String(err)
+            }`,
+          );
+        },
+      );
+      channel.eventOperations.add(operation);
+      operation.then(
+        () => channel.eventOperations.delete(operation),
+        () => channel.eventOperations.delete(operation),
+      );
+    });
+  }
+
+  /**
+   * Create against a stable managed-config generation. Agent processes load
+   * MCP definitions during factory startup but are not yet present in the
+   * sessions map, so a concurrent rewrite cannot mark them stale. Detect that
+   * straddle explicitly, close the ambiguous process, and retry.
+   */
+  private createAndBindStableSession(
+    channel: Channel,
+    agentId: string,
+    args: Parameters<AgentSessionFactory["create"]>[0],
+  ): Promise<AgentSession | null> {
+    const operation = this.createAndBindStableSessionCore(
+      channel,
+      agentId,
+      args,
+    );
+    channel.factoryOperations.add(operation);
+    operation.then(
+      () => channel.factoryOperations.delete(operation),
+      () => channel.factoryOperations.delete(operation),
+    );
+    return operation;
+  }
+
+  private async createAndBindStableSessionCore(
+    channel: Channel,
+    agentId: string,
+    args: Parameters<AgentSessionFactory["create"]>[0],
+  ): Promise<AgentSession | null> {
+    while (this.isActiveChannel(channel)) {
+      const generation = channel.configGeneration;
+      const session = await this.factory.create(args);
+      if (!this.isActiveChannel(channel)) {
+        await session.close().catch(() => {});
+        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
+        // afterward now sees this session and marks it stale; it can no longer
+        // change the generation in the await→bind gap while the process is
+        // invisible.
+        channel.browserStaleSessions.delete(agentId);
+        channel.browserPendingStaleSessions.delete(agentId);
+        this.bindSession(channel, agentId, session);
+        return session;
+      }
+      await session.close().catch(() => {});
+    }
+    return null;
+  }
+
   private async startSessions(channel: Channel): Promise<boolean> {
     const task = getHostTask(channel.taskId);
-    if (!task || task.statusMirror !== "running") return false;
+    if (
+      !task ||
+      task.statusMirror !== "running" ||
+      !this.isActiveChannel(channel)
+    ) {
+      return false;
+    }
+    // Freeze the generation before any slow docker work. A roster add while
+    // setup awaits must reconcile under its own engine-aware browser pass,
+    // not slip into this factory loop under the old generation's config.
+    const initialRoster = [...channel.roster];
 
     // Set the task creator's git author identity in the container (ADR-029).
     // The SSH key itself is installed earlier by task-up.sh (host clone +
@@ -497,6 +1313,7 @@ class Orchestrator {
     // async (docker exec via dockerCli) so it doesn't block the event loop —
     // this runs on every channel ensure, including each post-restart reconnect.
     await setupTaskGitIdentity(channel.taskId, task.ownerName, task.ownerEmail);
+    if (!this.isActiveChannel(channel)) return false;
 
     // GitHub auth for `gh` (ADR-027): mint + inject the access token and
     // (re)start its refresh schedule. Done here — not only at task-up — so it
@@ -518,22 +1335,26 @@ class Orchestrator {
     // turn. Idempotent + best-effort (returns fast when there are none); a slow
     // clone/install briefly delays start, which is acceptable for skill-bearing
     // tasks. Never throws.
-    await installPackageSkills(channel.taskId, channel.roster);
-
-    // ADR-053: wire the Playwright MCP browser (configs + backgrounded
-    // Chromium install) before agents spawn. Idempotent + best-effort.
-    if (channel.browserTesting) {
-      await setupBrowserTesting(
-        channel.taskId,
-        channel.containerName,
-        channel.roster.some((a) => a.kind === "codex"),
-      );
-    }
+    await installPackageSkills(channel.taskId, initialRoster);
+    if (!this.isActiveChannel(channel)) return false;
+
+    // ADR-053: wire the Playwright MCP browser before agents spawn — configs
+    // AND the Chromium install, awaited, because the only other place the
+    // download could happen is inside the MCP server's startup handshake,
+    // which the client caps at 10s (Codex) / 30s (Claude Code). Idempotent
+    // and ~0.5s once the build is present; a failure arms its own 60s retry
+    // rather than depending on another delivery/ensure to arrive.
+    await this.ensureBrowserSetup(
+      channel,
+      initialRoster.some((a) => a.kind === "codex"),
+    );
+    if (!this.isActiveChannel(channel)) return false;
 
     // ADR-057: the owner's MCP connections, reached through the host gateway
     // (tokens never enter the container) — written BEFORE agents spawn so
     // first sessions load them.
     await this.ensureMcpConfig(channel);
+    if (!this.isActiveChannel(channel)) return false;
 
     // ADR-048: write the in-container `uai` CLI (apiUrl only, no token) into the
     // workspace. Each agent's OWN task token — carrying only ITS permissions — is
@@ -543,30 +1364,40 @@ class Orchestrator {
     const cliSecret = loadTaskCliSecret(channel.taskId);
     writeAgentCli(channel.taskId, channel.roster, apiUrl);
 
-    // ADR-076: copy EXTRA config-dir engine accounts into their per-account
-    // container dirs (chowned) before sessions spawn — the default account's
-    // dir is already handled by task-up.sh. Best-effort per account.
-    await provisionEngineAccounts(
-      channel.containerName,
-      channel.roster.map((a) => a.kind),
-    );
-
-    for (const agent of channel.roster) {
-      const session = await this.factory.create({
-        taskId: channel.taskId,
-        agent,
-        containerName: channel.containerName,
-        systemPreamble: channel.preambles.get(agent.id) ?? "",
-        agentEnv: this.accountAgentEnv(
+    for (const agent of initialRoster) {
+      if (!this.isActiveChannel(channel)) return false;
+      // A prior partial start or an independently guarded recovery may already
+      // own this slot. Never replace it with an untracked second generation.
+      if (channel.sessions.has(agent.id) || channel.spawning.has(agent.id)) {
+        continue;
+      }
+      channel.spawning.add(agent.id);
+      try {
+        const session = await this.createAndBindStableSession(
           channel,
-          agent,
-          agentCliEnv(channel.taskId, agent, task.ownerUserId, apiUrl, cliSecret),
-        ),
-      });
-      channel.sessions.set(agent.id, session);
-      session.onEvent((event) => {
-        void this.handleAgentEvent(channel, agent.id, event);
-      });
+          agent.id,
+          {
+            taskId: channel.taskId,
+            agent,
+            containerName: channel.containerName,
+            systemPreamble: channel.preambles.get(agent.id) ?? "",
+            agentEnv: this.accountAgentEnv(
+              channel,
+              agent,
+              agentCliEnv(
+                channel.taskId,
+                agent,
+                task.ownerUserId,
+                apiUrl,
+                cliSecret,
+              ),
+            ),
+          },
+        );
+        if (!session) return false;
+      } finally {
+        channel.spawning.delete(agent.id);
+      }
     }
 
     // First-turn delivery is owned by the CLOUD (channel-router.ensureStarted),
@@ -590,6 +1421,32 @@ class Orchestrator {
     if (channel) await this.ensureSessions(channel);
   }
 
+  private incrementActiveTurns(channel: Channel, agentId: string): void {
+    channel.activeTurns.set(
+      agentId,
+      (channel.activeTurns.get(agentId) ?? 0) + 1,
+    );
+  }
+
+  /** Session output proves at least one active turn, but deltas/tools from the
+   *  same turn must not inflate the delivery count. */
+  private markActiveTurn(channel: Channel, agentId: string): void {
+    if (!channel.activeTurns.has(agentId)) {
+      channel.activeTurns.set(agentId, 1);
+    }
+  }
+
+  /** Consume one queued/active turn and report how many remain. */
+  private decrementActiveTurns(channel: Channel, agentId: string): number {
+    const remaining = Math.max(
+      0,
+      (channel.activeTurns.get(agentId) ?? 1) - 1,
+    );
+    if (remaining === 0) channel.activeTurns.delete(agentId);
+    else channel.activeTurns.set(agentId, remaining);
+    return remaining;
+  }
+
   // -- inbound: a human (or routed peer) message ----------------------------
 
   /**
@@ -622,7 +1479,17 @@ class Orchestrator {
     // ADR-076: remember the in-flight prompt so an account rotation on a
     // rate-limit can re-deliver it to the fresh session.
     channel.lastPrompt.set(agentId, prompt);
-    void session.send(prompt);
+    this.incrementActiveTurns(channel, agentId);
+    void session.send(prompt).catch((err: unknown) => {
+      if (channel.sessions.get(agentId) === session) {
+        this.decrementActiveTurns(channel, agentId);
+      }
+      console.warn(
+        `[orchestrator] ${channel.taskId}/${agentId}: send failed: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    });
     return { ok: true };
   }
 
@@ -673,8 +1540,10 @@ class Orchestrator {
     agentId: string,
     event: AgentEvent,
   ): Promise<void> {
+    if (!this.isActiveChannel(channel)) return;
     switch (event.type) {
       case "message_delta": {
+        this.markActiveTurn(channel, agentId);
         channel.openTurns.add(agentId);
         this.emitHost({
           kind: "agent.message_delta",
@@ -685,6 +1554,7 @@ class Orchestrator {
         break;
       }
       case "message_complete": {
+        this.markActiveTurn(channel, agentId);
         channel.openTurns.add(agentId);
         this.emitHost({
           kind: "agent.message_complete",
@@ -696,6 +1566,7 @@ class Orchestrator {
         break;
       }
       case "tool_call": {
+        this.markActiveTurn(channel, agentId);
         this.emitHost({
           kind: "agent.tool_call",
           taskId: channel.taskId,
@@ -706,6 +1577,7 @@ class Orchestrator {
         break;
       }
       case "permission_request": {
+        this.markActiveTurn(channel, agentId);
         this.emitHost({
           kind: "agent.permission_request",
           taskId: channel.taskId,
@@ -733,6 +1605,7 @@ class Orchestrator {
       case "error": {
         // The turn died with the session — drop its turn-state flags so a
         // respawned session starts clean.
+        channel.activeTurns.delete(agentId);
         channel.openTurns.delete(agentId);
         channel.interrupted.delete(agentId);
         // Claude under load (especially Docker Desktop macOS) occasionally
@@ -780,6 +1653,8 @@ class Orchestrator {
         channel.respawns.set(agentId, (channel.respawns.get(agentId) ?? 0) + 1);
         channel.respawnLastAt.set(agentId, Date.now());
         channel.sessions.delete(agentId);
+        channel.browserStaleSessions.delete(agentId);
+        channel.browserPendingStaleSessions.delete(agentId);
         break;
       }
       case "turn_complete": {
@@ -788,6 +1663,7 @@ class Orchestrator {
         // An interrupted (ESC'd) turn goes out `aborted`: it's a half-turn, so
         // the cloud discards the buffer instead of handing it to peers.
         const aborted = channel.interrupted.delete(agentId);
+        const remainingTurns = this.decrementActiveTurns(channel, agentId);
         channel.openTurns.delete(agentId);
         // ADR-076: a turn that completed means the current account is healthy —
         // reset its rotation budget so a LATER rate-limit gets a fresh failover.
@@ -799,14 +1675,33 @@ class Orchestrator {
           aborted,
           usage: event.usage,
         });
+        // A config repair never interrupts a turn. The stale id remains queued
+        // until this exact boundary, then reconcile closes and replaces it.
+        if (
+          remainingTurns === 0 &&
+          channel.browserStaleSessions.has(agentId)
+        ) {
+          void this.reconcileSessions(channel).catch((err: unknown) => {
+            console.warn(
+              `[orchestrator] ${channel.taskId}: stale-session reconcile failed: ${
+                err instanceof Error ? err.message : String(err)
+              }`,
+            );
+          });
+        }
         break;
       }
       case "exit":
         // Same zombie hazard as the error path — a session whose process
         // ended (even cleanly) can never carry another turn.
+        channel.activeTurns.delete(agentId);
+        channel.openTurns.delete(agentId);
+        channel.interrupted.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);
+        channel.browserPendingStaleSessions.delete(agentId);
         break;
     }
   }
@@ -822,11 +1717,16 @@ class Orchestrator {
     channel: Channel,
     agentId: string,
   ): Promise<void> {
+    if (!this.isActiveChannel(channel) || channel.spawning.has(agentId)) return;
+
     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.sessions.delete(agentId);
+      channel.browserStaleSessions.delete(agentId);
+      channel.browserPendingStaleSessions.delete(agentId);
       this.emitHost({
         kind: "agent.exit",
         taskId: channel.taskId,
@@ -839,40 +1739,84 @@ class Orchestrator {
       return;
     }
 
-    const restored = repairClaudeConfigInContainer(channel.containerName);
+    channel.spawning.add(agentId);
+    try {
+      const restored = repairClaudeConfigInContainer(channel.containerName);
 
-    // Tear the dead session down and build a fresh one in its place.
-    const old = channel.sessions.get(agentId);
-    if (old) {
-      try {
-        await old.close();
-      } catch {
-        // Already exited — close is idempotent for our adapters.
+      // Delete the old generation before awaiting close. Its adapter emits a
+      // terminal event during teardown; bindSession's identity guard must see
+      // it as stale, and reconciliation must see `spawning` instead of opening
+      // a second replacement path.
+      const old = channel.sessions.get(agentId);
+      channel.sessions.delete(agentId);
+      channel.browserStaleSessions.delete(agentId);
+      channel.browserPendingStaleSessions.delete(agentId);
+      if (old) {
+        try {
+          await old.close();
+        } catch {
+          // Already exited — close is idempotent for our adapters.
+        }
       }
-    }
+      if (!this.isActiveChannel(channel)) return;
 
-    const agent = channel.roster.find((a) => a.id === agentId);
-    if (!agent) return;
-    const session = await this.factory.create({
-      taskId: channel.taskId,
-      agent,
-      containerName: channel.containerName,
-      systemPreamble: channel.preambles.get(agentId) ?? "",
-    });
-    channel.sessions.set(agentId, session);
-    session.onEvent((event) => {
-      void this.handleAgentEvent(channel, agentId, event);
-    });
+      const agent = channel.roster.find((a) => a.id === agentId);
+      const task = getHostTask(channel.taskId);
+      if (!agent || !task || task.statusMirror !== "running") return;
 
-    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).`;
-    this.emitHost({
-      kind: "agent.exit",
-      taskId: channel.taskId,
-      agentId,
-      reason: message,
-    });
+      const apiUrl = apiUrlFromCloudUrl(env.UAI_CLOUD_URL);
+      const cliSecret = loadTaskCliSecret(channel.taskId);
+      const base = agentCliEnv(
+        channel.taskId,
+        agent,
+        task.ownerUserId,
+        apiUrl,
+        cliSecret,
+      );
+      const boundAccountId = channel.accountByAgent.get(agentId);
+      const boundAccount = boundAccountId
+        ? resolveEngineAccounts(agent.kind).find(
+            (account) => account.id === boundAccountId,
+          )
+        : undefined;
+      const session = await this.createAndBindStableSession(channel, agentId, {
+        taskId: channel.taskId,
+        agent,
+        containerName: channel.containerName,
+        systemPreamble: channel.preambles.get(agentId) ?? "",
+        agentEnv: boundAccount
+          ? { ...base, ...boundAccount.execEnv }
+          : this.accountAgentEnv(channel, agent, base),
+      });
+      if (!session) return;
+
+      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).`;
+      this.emitHost({
+        kind: "agent.exit",
+        taskId: channel.taskId,
+        agentId,
+        reason: message,
+      });
+    } finally {
+      channel.spawning.delete(agentId);
+      // A concurrent config writer can mark the newly-bound recovery stale
+      // while this spawn slot is still held. Reconciliation skips spawning
+      // ids by design, so release must explicitly give that mark another turn.
+      if (
+        this.isActiveChannel(channel) &&
+        channel.browserStaleSessions.has(agentId)
+      ) {
+        void this.reconcileSessions(channel).catch((err: unknown) => {
+          console.warn(
+            `[orchestrator] ${channel.taskId}/${agentId}: post-recovery reconcile failed: ${
+              err instanceof Error ? err.message : String(err)
+            }`,
+          );
+        });
+      }
+    }
   }
 
   /**
@@ -888,6 +1832,10 @@ class Orchestrator {
     agentId: string,
     agent: RosterAgent,
   ): Promise<boolean> {
+    if (!this.isActiveChannel(channel)) 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;
     if (resolveEngineAccounts(agent.kind).length < 2) return false;
 
     const budget = (channel.rotations.get(agentId) ?? 0) + 1;
@@ -904,53 +1852,100 @@ class Orchestrator {
     const task = getHostTask(channel.taskId);
     if (!task || task.statusMirror !== "running") return false;
 
-    // Tear the rate-limited session down (its `closed` flag suppresses its own
-    // exit, so no respawn-budget noise races this rotation).
-    const old = channel.sessions.get(agentId);
-    channel.sessions.delete(agentId);
-    if (old) {
-      try {
-        await old.close();
-      } catch {
-        /* already gone — close is idempotent for our adapters */
+    let replacement: AgentSession | null = null;
+    channel.spawning.add(agentId);
+    try {
+      // Tear the rate-limited session down. Delete first so its final adapter
+      // event is generation-stale, while `spawning` keeps reconciliation from
+      // opening a second replacement path during the slow provisioning/setup.
+      const old = channel.sessions.get(agentId);
+      channel.sessions.delete(agentId);
+      channel.browserStaleSessions.delete(agentId);
+      channel.browserPendingStaleSessions.delete(agentId);
+      if (old) {
+        try {
+          await old.close();
+        } catch {
+          /* already gone — close is idempotent for our adapters */
+        }
       }
-    }
+      if (!this.isActiveChannel(channel)) return true;
+
+      // The serialized materialization gate owns both account provisioning
+      // and, when enabled, browser migration.
+      await this.ensureBrowserSetup(
+        channel,
+        channel.roster.some((candidate) => candidate.kind === "codex"),
+        true,
+      );
+      if (!this.isActiveChannel(channel)) return true;
+      await this.ensureMcpConfig(channel);
+      if (!this.isActiveChannel(channel)) return true;
 
-    // Extra config-dir accounts need their dir copied in before use.
-    await provisionEngineAccounts(channel.containerName, [agent.kind]);
+      const apiUrl = apiUrlFromCloudUrl(env.UAI_CLOUD_URL);
+      const cliSecret = loadTaskCliSecret(channel.taskId);
+      const base = agentCliEnv(
+        channel.taskId,
+        agent,
+        task.ownerUserId,
+        apiUrl,
+        cliSecret,
+      );
+      channel.accountByAgent.set(agentId, next.id);
+      noteEngineAccountUsed(next.id);
 
-    const apiUrl = apiUrlFromCloudUrl(env.UAI_CLOUD_URL);
-    const cliSecret = loadTaskCliSecret(channel.taskId);
-    const base = agentCliEnv(
-      channel.taskId,
-      agent,
-      task.ownerUserId,
-      apiUrl,
-      cliSecret,
-    );
-    channel.accountByAgent.set(agentId, next.id);
-    noteEngineAccountUsed(next.id);
-
-    const session = await this.factory.create({
-      taskId: channel.taskId,
-      agent,
-      containerName: channel.containerName,
-      systemPreamble: channel.preambles.get(agentId) ?? "",
-      agentEnv: { ...base, ...next.execEnv },
-    });
-    channel.sessions.set(agentId, session);
-    session.onEvent((event) => {
-      void this.handleAgentEvent(channel, agentId, event);
-    });
+      replacement = await this.createAndBindStableSession(
+        channel,
+        agentId,
+        {
+          taskId: channel.taskId,
+          agent,
+          containerName: channel.containerName,
+          systemPreamble: channel.preambles.get(agentId) ?? "",
+          agentEnv: { ...base, ...next.execEnv },
+        },
+      );
+      if (!replacement) return true;
 
-    this.emitSystemNote(
-      channel.taskId,
-      `${agentId}: hit a rate limit — switched to another ${agent.kind} account and retried.`,
-    );
+      this.emitSystemNote(
+        channel.taskId,
+        `${agentId}: hit a rate limit — switched to another ${agent.kind} account and retried.`,
+      );
+
+      // Re-deliver the in-flight prompt so the interrupted turn resumes.
+      const prompt = channel.lastPrompt.get(agentId);
+      if (prompt) {
+        this.incrementActiveTurns(channel, agentId);
+        void replacement.send(prompt).catch((err: unknown) => {
+          if (channel.sessions.get(agentId) === replacement) {
+            this.decrementActiveTurns(channel, agentId);
+          }
+          console.warn(
+            `[orchestrator] ${channel.taskId}/${agentId}: rotated send failed: ${
+              err instanceof Error ? err.message : String(err)
+            }`,
+          );
+        });
+      }
+    } finally {
+      channel.spawning.delete(agentId);
+    }
 
-    // Re-deliver the in-flight prompt so the interrupted turn resumes.
-    const prompt = channel.lastPrompt.get(agentId);
-    if (prompt) void session.send(prompt);
+    // Browser/config setup may have marked other live generations stale. Run
+    // their safe-idle recycle only after this agent's replacement is bound.
+    if (
+      replacement &&
+      this.isActiveChannel(channel) &&
+      channel.browserStaleSessions.size > 0
+    ) {
+      void this.reconcileSessions(channel).catch((err: unknown) => {
+        console.warn(
+          `[orchestrator] ${channel.taskId}: post-rotation reconcile failed: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        );
+      });
+    }
     return true;
   }
 
@@ -970,11 +1965,69 @@ class Orchestrator {
   }
 
   /** Tear a channel down (task killed). */
-  async closeChannel(taskId: string): Promise<void> {
+  closeChannel(taskId: string): Promise<void> {
+    const existing = this.channelClosures.get(taskId);
+    if (existing) return existing;
+
+    this.blockedTasks.add(taskId);
+    this.channelSpecs.delete(taskId);
     const ch = this.channels.get(taskId);
-    if (!ch) return;
-    for (const session of ch.sessions.values()) await session.close();
+    if (!ch) return Promise.resolve();
+    // Invalidate the generation BEFORE the first await. Browser setup and the
+    // start/reconcile factory continuations all check this identity, so none
+    // can repopulate an orphan channel while its sessions close.
+    ch.closed = true;
     this.channels.delete(taskId);
+    this.clearBrowserRetry(ch);
+    ch.browserStaleSessions.clear();
+    ch.browserPendingStaleSessions.clear();
+    ch.activeTurns.clear();
+    ch.openTurns.clear();
+    ch.interrupted.clear();
+    ch.reconcileAgain = false;
+    const drains = [
+      ch.browserSetup,
+      ch.mcpConfigWrite,
+      ch.reconcileReady,
+      ch.sessionsReady,
+      ...ch.factoryOperations,
+      ...ch.eventOperations,
+    ].filter((promise): promise is Promise<unknown> => promise !== null);
+    const sessions = [...ch.sessions.values()];
+    ch.sessions.clear();
+    const closes = sessions.map((session) =>
+      session.close().catch(() => {
+        // Teardown is best-effort; every adapter close is intended idempotent.
+      }),
+    );
+    // Draining externally side-effecting work is part of the container-name
+    // reuse fence. An old docker cp/config writer/factory must finish before
+    // taskDown can return and a later taskUp can create the same container.
+    let closing: Promise<void>;
+    closing = Promise.allSettled([...drains, ...closes])
+      .then(() => undefined)
+      .finally(() => {
+        if (this.channelClosures.get(taskId) === closing) {
+          this.channelClosures.delete(taskId);
+        }
+      });
+    this.channelClosures.set(taskId, closing);
+    return closing;
+  }
+
+  /** Task-up must join teardown before it can recreate the same compose and
+   *  container names. This does not clear the tombstone; only success does. */
+  waitForChannelClose(taskId: string): Promise<void> {
+    return this.channelClosures.get(taskId) ?? Promise.resolve();
+  }
+
+  /** 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;
+    this.blockedTasks.delete(taskId);
   }
 
   /**
@@ -986,22 +2039,50 @@ class Orchestrator {
    * `stopped` is not an ACTIVE status, host recovery won't restart it.
    */
   async stopTask(taskId: string): Promise<{ ok: boolean; error?: string }> {
+    return this.runTaskLifecycle(taskId, () =>
+      this.stopTaskWithinLifecycle(taskId),
+    );
+  }
+
+  private async stopTaskWithinLifecycle(
+    taskId: string,
+  ): Promise<{ ok: boolean; error?: string }> {
     const task = getHostTask(taskId);
     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.
     await this.closeChannel(taskId);
+    try {
+      await stopPreviewSidecars(taskId);
+    } catch (err) {
+      console.warn(
+        `[orchestrator] ${taskId}: preview cleanup before stop failed: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    }
     const ps = await dockerCli([
       "ps",
       "-q",
       "--filter",
       `label=com.docker.compose.project=${project}`,
     ]);
+    if (ps.status !== 0) {
+      // An empty stdout is not evidence that the stack is gone when docker
+      // itself failed. Reopen the channel and leave the runtime mirror alone
+      // so cloud reconciliation cannot turn a live container into "stopped".
+      this.allowChannel(taskId);
+      return {
+        ok: false,
+        error: ps.stderr.trim().slice(0, 200) || "docker ps failed",
+      };
+    }
     const ids = ps.stdout.split("\n").map((s) => s.trim()).filter(Boolean);
     if (ids.length > 0) {
       const stopped = await dockerCli(["stop", ...ids], { timeoutMs: 60_000 });
       if (stopped.status !== 0) {
+        this.allowChannel(taskId);
         return {
           ok: false,
           error: stopped.stderr.trim().slice(0, 200) || "docker stop failed",
@@ -1411,7 +2492,7 @@ export function buildSystemPreamble(
       ? [
           "## Browser",
           "",
-          "This container has a headless Chromium available through the",
+          "This container has Chromium available through the",
           "`browser` MCP server (Playwright). Use it to VERIFY UI work",
           "end-to-end — the dev server you're building runs in this same",
           "container, so navigate to `http://localhost:<port>` directly.",
@@ -1422,9 +2503,10 @@ export function buildSystemPreamble(
           "in your reply as `[image: /workspace/.uai/attachments/<name>.png]`.",
           "Your browser runs on a virtual display the humans can WATCH live",
           "(the \"browser\" preview) — nothing for you to do about that.",
-          "The first browser launch in a fresh container may take a minute",
-          "while Chromium's system deps finish installing — retry once if",
-          "it fails immediately after task start.",
+          "The browser is ready to use — just call it. If a call ever fails,",
+          "the failure is real: report it and say what you could not verify.",
+          "Do NOT fall back to a static HTML harness and describe it as",
+          "verified — that is worse than saying the browser was unavailable.",
           "",
         ]
       : []),
@@ -1575,6 +2657,39 @@ export function getOrchestrator(): Orchestrator {
 
 let recoveryPromise: Promise<void> = Promise.resolve();
 
+interface TaskRecoveryBarrier {
+  promise: Promise<void>;
+  resolve(): void;
+}
+
+const taskRecoveryBarriers = new Map<string, TaskRecoveryBarrier>();
+
+function openTaskRecoveryBarrier(taskId: string): void {
+  if (taskRecoveryBarriers.has(taskId)) return;
+  let resolve!: () => void;
+  const promise = new Promise<void>((done) => {
+    resolve = done;
+  });
+  taskRecoveryBarriers.set(taskId, { promise, resolve });
+}
+
+function finishTaskRecovery(taskId: string): void {
+  const barrier = taskRecoveryBarriers.get(taskId);
+  if (!barrier) return;
+  taskRecoveryBarriers.delete(taskId);
+  barrier.resolve();
+}
+
+function finishAllTaskRecovery(): void {
+  for (const taskId of [...taskRecoveryBarriers.keys()]) {
+    finishTaskRecovery(taskId);
+  }
+}
+
+export function taskRecoveryComplete(taskId: string): Promise<void> {
+  return taskRecoveryBarriers.get(taskId)?.promise ?? Promise.resolve();
+}
+
 /**
  * Resolves once boot-time recovery has finished (starting the orchestrator —
  * and with it recovery — if that hasn't happened yet). Never rejects.
@@ -1698,47 +2813,67 @@ export async function recoverRunningTasks(opts?: {
 }): Promise<void> {
   const retryMs = opts?.retryMs ?? 20_000;
   const maxPasses = opts?.maxPasses ?? 45;
+  let pendingTaskIds: ReadonlySet<string> | undefined;
   // After a machine reboot the host service and the Docker daemon start
   // concurrently; a pass that finds docker unreachable resolves nothing and
   // must retry once the daemon is up — the whole point of recovery is to
   // restart the exited containers that reboot left behind.
   for (let pass = 1; ; pass++) {
-    const deferred = await recoveryPass();
-    if (deferred === 0) return;
+    const deferred = await recoveryPass(pendingTaskIds);
+    if (deferred.size === 0) {
+      finishAllTaskRecovery();
+      return;
+    }
+    pendingTaskIds = deferred;
     if (pass >= maxPasses) {
       console.warn(
-        `[orchestrator] recovery: docker still unreachable after ${pass} passes — giving up (${deferred} task(s) unresolved)`,
+        `[orchestrator] recovery: docker still unreachable after ${pass} passes — giving up (${deferred.size} task(s) unresolved)`,
       );
+      finishAllTaskRecovery();
       return;
     }
     if (pass === 1) {
       console.log(
-        `[orchestrator] recovery: docker not ready — retrying every ${Math.round(retryMs / 1000)}s for ${deferred} task(s)`,
+        `[orchestrator] recovery: docker not ready — retrying every ${Math.round(retryMs / 1000)}s for ${deferred.size} task(s)`,
       );
     }
     await new Promise((resolve) => setTimeout(resolve, retryMs));
   }
 }
 
-/** One recovery sweep. Returns how many tasks were deferred on an
- *  unreachable docker (0 = everything resolved one way or another). */
-async function recoveryPass(): Promise<number> {
-  let deferred = 0;
+/** One recovery sweep. Returns only task ids deferred by unreachable Docker;
+ *  successful ids are never revisited by a later retry pass. */
+async function recoveryPass(
+  onlyTaskIds?: ReadonlySet<string>,
+): Promise<Set<string>> {
+  const deferred = new Set<string>();
   try {
     const db = getDb();
-    const rows = db
+    const activeRows = db
       .select()
       .from(schema.hostTasks)
       .where(inArray(schema.hostTasks.statusMirror, [...ACTIVE_STATUSES]))
       .all();
-    if (rows.length === 0) return 0;
+    const rows = onlyTaskIds
+      ? activeRows.filter((task) => onlyTaskIds.has(task.taskId))
+      : activeRows;
+    const activeTaskIds = new Set(rows.map((task) => task.taskId));
+    const expectedTaskIds =
+      onlyTaskIds ?? new Set(taskRecoveryBarriers.keys());
+    for (const taskId of expectedTaskIds) {
+      if (!activeTaskIds.has(taskId)) finishTaskRecovery(taskId);
+    }
+    for (const task of rows) openTaskRecoveryBarrier(task.taskId);
+    if (rows.length === 0) return deferred;
     console.log(
       `[orchestrator] recovery: scanning ${rows.length} active task row(s)`,
     );
     for (const task of rows) {
       try {
-        if (!(await recoverOneTask(task))) deferred += 1;
+        if (await recoverOneTask(task)) finishTaskRecovery(task.taskId);
+        else deferred.add(task.taskId);
       } catch (err) {
+        finishTaskRecovery(task.taskId);
         console.error(
           `[orchestrator] recovery: ${task.taskId} failed:`,
           err instanceof Error ? err.message : err,
@@ -1746,6 +2881,7 @@ async function recoveryPass(): Promise<number> {
       }
     }
   } catch (err) {
+    finishAllTaskRecovery();
     console.error(
       "[orchestrator] recovery: top-level failure",
       err instanceof Error ? err.message : err,
@@ -1875,5 +3011,3 @@ function db_setRuntime(
 ): void {
   upsertHostTask(taskId, extras);
 }
-
-export type { Orchestrator };