@runuai/host 0.9.148 → 0.9.150

package/lib/orchestrator.ts

@@ -50,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";
@@ -83,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,
@@ -97,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,
@@ -126,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,
@@ -150,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;
 
@@ -708,6 +739,7 @@ export class Orchestrator {
           channel.sharedFiles,
           spec.mode,
           spec.secretaryAgentId,
+          taskProxiedKeys(channel.taskId),
         ),
       );
     }
@@ -937,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
@@ -2112,6 +2145,7 @@ export class Orchestrator {
               attachCompatibilityKey: this.attachCompatibilityKeyFor(
                 channel,
                 agent,
+                task,
               ),
               agentEnv: this.accountAgentEnv(
                 channel,
@@ -2124,7 +2158,7 @@ export class Orchestrator {
                   cliSecret,
                   this.isPromptLevelSecretary(channel, agent.id),
                 ),
-                this.machineProjectEnv(task),
+                task,
               ),
             },
           );
@@ -2153,6 +2187,7 @@ export class Orchestrator {
   private attachCompatibilityKeyFor(
     channel: Channel,
     agent: RosterAgent,
+    task: { envMode?: string | null },
   ): string | 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
@@ -2168,9 +2203,11 @@ export class Orchestrator {
     // Preserve legacy null/policy-only attachment for agents that choose no
     // launch flags. Explicit model/effort gets a stable key so a host restart
     // cannot attach a runner created under different settings.
-    if (!model && !effort) return policy;
+    const envMode = hostTaskEnvMode(task);
+    if (envMode === "baked" && !model && !effort) return policy;
     return JSON.stringify([
-      "roster-launch-v1",
+      envMode === "baked" ? "roster-launch-v1" : "roster-launch-v2",
+      ...(envMode === "loader" ? [envMode] : []),
       agent.kind,
       model,
       effort,
@@ -2209,10 +2246,13 @@ 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 };
@@ -2230,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));
   }
 
@@ -2386,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,
@@ -2577,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,
@@ -2740,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,
-          ),
-          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(
@@ -2757,7 +2804,7 @@ export class Orchestrator {
                 cliSecret,
                 this.isPromptLevelSecretary(channel, agent.id),
               ),
-              this.machineProjectEnv(task),
+              task,
             ),
           },
         );
@@ -3204,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,
@@ -3860,10 +3908,15 @@ export class Orchestrator {
         attachCompatibilityKey: this.attachCompatibilityKeyFor(
           channel,
           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) {
         if (channel.rosterSessionChanges.has(agentId)) {
@@ -4062,8 +4115,13 @@ export class Orchestrator {
           attachCompatibilityKey: this.attachCompatibilityKeyFor(
             channel,
             agent,
+            task,
           ),
-          agentEnv: { ...next.execEnv, ...base },
+          agentEnv: {
+            ...this.machineProjectEnv(task),
+            ...next.execEnv,
+            ...base,
+          },
         },
         recovery,
       );
@@ -4267,8 +4325,13 @@ export class Orchestrator {
           attachCompatibilityKey: this.attachCompatibilityKeyFor(
             channel,
             agent,
+            task,
           ),
-          agentEnv: { ...account.execEnv, ...base },
+          agentEnv: {
+            ...this.machineProjectEnv(task),
+            ...account.execEnv,
+            ...base,
+          },
         },
         recovery,
       );
@@ -4559,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);
   }
 
@@ -4587,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());
@@ -4612,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);
@@ -4633,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,
@@ -4645,6 +4738,24 @@ 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 };
   }
@@ -4802,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,
@@ -4898,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,
@@ -4910,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) =>
@@ -5355,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.
@@ -5550,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",
@@ -6971,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. */
@@ -6990,6 +7140,7 @@ export async function recoverRunningTasks(opts?: {
     const result = await recoveryPass(
       pendingTaskIds,
       opts?.lifecycle,
+      opts?.consumerLifecycle,
       opts?.maintenanceReady ?? agentClisReady,
       opts?.isCurrent ?? (() => true),
     );
@@ -7034,6 +7185,7 @@ interface RecoveryPassResult {
 async function recoveryPass(
   onlyTaskIds?: ReadonlySet<string>,
   lifecycle?: Orchestrator,
+  consumerLifecycle?: Orchestrator,
   maintenanceReady: Promise<void> = agentClisReady,
   isCurrent: () => boolean = () => true,
 ): Promise<RecoveryPassResult> {
@@ -7091,6 +7243,7 @@ async function recoveryPass(
               task,
               maintenanceReady,
               isCurrent,
+              consumerLifecycle,
             );
         if (recovered) {
           if (!lifecycle) finishTaskRecovery(task.taskId);
@@ -7285,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(
@@ -7328,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>;
 }
@@ -7809,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,
@@ -7835,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 (
@@ -7860,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
@@ -7882,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") {
@@ -7900,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
@@ -7930,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 });
@@ -7983,6 +8253,7 @@ async function recoverDockerTaskEnvironment(
 
   const lifecycleCallbacks = [
     context.quarantineConsumers,
+    context.prepareConsumers,
     context.allowConsumers,
     context.ensureConsumersStarted,
   ];
@@ -7998,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");
@@ -8037,6 +8314,17 @@ async function recoverOneDockerTask(
   lifecycle?: RecoveryTaskConsumers,
 ): Promise<boolean> {
   if (!isCurrent()) return true;
+  // Recovery is sanctioned private maintenance while public admission is
+  // deliberately `checking`. Its container work is fenced by this daemon
+  // epoch instead of the public operational bit: work it starts keeps going
+  // while the generation is current, and a superseded one stops.
+  const admitRecoveryContainerWork = (): void => {
+    if (!isCurrent()) {
+      throw new ContainerRuntimeUnavailableError(
+        "container runtime recovery generation was superseded",
+      );
+    }
+  };
   const composeProject = task.composeProject;
   if (!composeProject) {
     // We never wrote a compose project name for this row — must be
@@ -8186,7 +8474,9 @@ async function recoverOneDockerTask(
     // ~8h later. Cheap with the per-user access-token cache — one exchange
     // per user, every task re-injects from it. Best-effort.
     if (task.ownerUserId) {
-      void reconcileTaskGitAuth(task.taskId, task.ownerUserId).catch((err) =>
+      void reconcileTaskGitAuth(task.taskId, task.ownerUserId, {
+        admitContainerWork: admitRecoveryContainerWork,
+      }).catch((err) =>
         console.warn(
           `[github] task ${task.taskId}: running recovery reconciliation failed: ${
             err instanceof Error ? err.message : String(err)
@@ -8205,6 +8495,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()) {
@@ -8318,17 +8615,9 @@ async function recoverOneDockerTask(
   if (task.ownerUserId) {
     try {
       await reconcileTaskGitAuth(task.taskId, task.ownerUserId, {
-        // Recovery is sanctioned private maintenance while public admission is
-        // deliberately `checking`. Fence it by this daemon epoch instead of
-        // the public operational bit, preserving private-dependency setup
-        // before uai-init without letting stale recovery keep mutating.
-        admitContainerWork: () => {
-          if (!isCurrent()) {
-            throw new ContainerRuntimeUnavailableError(
-              "container runtime recovery generation was superseded",
-            );
-          }
-        },
+        // Before uai-init, so private dependencies resolve; fenced by this
+        // recovery's epoch, not the public operational bit.
+        admitContainerWork: admitRecoveryContainerWork,
       });
       if (!isCurrent()) return true;
     } catch (err) {
@@ -8340,6 +8629,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(
@@ -8431,9 +8737,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;
@@ -8456,9 +8769,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,
@@ -8475,7 +8799,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);