@runuai/host 0.9.148 → 0.9.149

package/lib/sidecar-guard.ts

@@ -0,0 +1,58 @@
+/**
+ * A task machine's own guards, held by its sidecar (root) before the task
+ * runs anything there (ADR-133; ADR-153 §3, "Where the proxy runs"):
+ *
+ * - The runner's data directory is root's alone, so the task's user cannot
+ *   read the store's database. Its values are sealed with a root-only key,
+ *   but its key names and bindings would still be there to read.
+ * - The instance metadata service is closed to the task's user, so it can
+ *   read neither the machine's user-data, which carries the sidecar's host
+ *   token, nor the instance role's credentials.
+ *
+ * The image's prepare step sets both up too. The runner insists on them at
+ * every task-up, since an image that skipped or failed that step would
+ * otherwise let the task start without them.
+ */
+
+import { execFileSync } from "node:child_process";
+import { chmodSync, mkdirSync } from "node:fs";
+
+/** Rejects the task user's traffic to the instance metadata service, with
+ *  whichever iptables backend the kernel serves (as the proxy's chain does),
+ *  adding the rule only when it is missing. */
+export const METADATA_BLOCK_SCRIPT = [
+  "set -eu",
+  "ipt=iptables",
+  "if ! command -v iptables >/dev/null 2>&1 || ! iptables -S OUTPUT >/dev/null 2>&1; then ipt=iptables-legacy; fi",
+  'command -v "$ipt" >/dev/null 2>&1 || { echo "iptables is not installed" >&2; exit 1; }',
+  '"$ipt" -C OUTPUT -d 169.254.169.254 -m owner --uid-owner node -j REJECT 2>/dev/null \\',
+  '  || "$ipt" -I OUTPUT -d 169.254.169.254 -m owner --uid-owner node -j REJECT',
+].join("\n");
+
+export interface SidecarGuardDeps {
+  dataDir: string;
+  /** Runs a script as this (root) process; throws when it fails. */
+  runScript(script: string): void;
+}
+
+const defaultRunScript = (script: string): void => {
+  execFileSync("/bin/sh", ["-c", script], { stdio: ["ignore", "ignore", "pipe"], timeout: 15_000 });
+};
+
+/** Puts both guards in place, or says which could not be. */
+export function guardSidecarMachine(deps: Partial<SidecarGuardDeps> & Pick<SidecarGuardDeps, "dataDir">): { ok: true } | { ok: false; reason: string } {
+  const runScript = deps.runScript ?? defaultRunScript;
+  try {
+    mkdirSync(deps.dataDir, { recursive: true, mode: 0o700 });
+    chmodSync(deps.dataDir, 0o700);
+  } catch (error) {
+    return { ok: false, reason: `its data directory could not be made private (${error instanceof Error ? error.message : String(error)})` };
+  }
+  try {
+    runScript(METADATA_BLOCK_SCRIPT);
+  } catch (error) {
+    const detail = error instanceof Error && "stderr" in error ? String((error as { stderr?: unknown }).stderr ?? "").trim() : "";
+    return { ok: false, reason: `the instance metadata service could not be closed to the task${detail ? ` (${detail})` : ""}` };
+  }
+  return { ok: true };
+}

package/lib/sidecar-resume.ts

@@ -19,6 +19,10 @@ import { getDb } from "./db";
 import { mountSharedFilesFromLease } from "./shared-files-s3";
 import { sidecarTaskId } from "./sidecar";
 import { reconstructPersistedTaskEnvironment } from "./task-environment";
+import { installMachineProjectEnvLoader } from "./machine-project-env-loader";
+import { activeSecretsProxy } from "./secrets-proxy/host";
+import { taskViewProven } from "./secrets-proxy/sidecar-view";
+import { reconcileSidecarTaskProxy } from "./secrets-proxy/task-trust";
 import { ensureCodeServer } from "./task-environment/machine-task-up";
 import type { TaskEnvironmentHandle } from "./task-environment/types";
 
@@ -33,12 +37,15 @@ export interface SidecarResumeDeps {
     workspacePath: string,
     task: { sharedFiles?: string },
   ) => Promise<string | null>;
+  loader?: (handle: TaskEnvironmentHandle<unknown>) => Promise<void>;
   editor?: (handle: TaskEnvironmentHandle<unknown>, workspacePath: string) => Promise<void>;
+  proxy?: typeof reconcileSidecarTaskProxy;
 }
 
 export interface SidecarResumeResult {
-  /** `no-task`: not a sidecar. `not-up`: the task has not been provisioned on
-   * this machine yet (a fresh launch — task-up does the work). `resumed`: the
+  /** `no-task`: not a sidecar. `not-up`: the task has not come up on this
+   * machine yet (a fresh launch, or a start that a runner restart cut short —
+   * task-up does the work). `resumed`: the
    * task was up before this runner started; its mounts and editor were
    * re-asserted, with any per-step warning listed. */
   outcome: "no-task" | "not-up" | "resumed";
@@ -52,18 +59,59 @@ function mountedModeFromMarker(bytes: Uint8Array | null): "ro" | "rw" | null {
   return Buffer.from(bytes).toString("utf8").trim() === "rw" ? "rw" : "ro";
 }
 
+/**
+ * ADR-153 machines, at the runner's start and before any command can reach
+ * the task: a task this machine has a row for, in whatever state (`starting`
+ * included), is held for this boot unless its hosts-view record proves it.
+ * A start driven again, or a resume, then finds the hold. Only task-up for a
+ * task with no row admits it fresh (src/index.ts).
+ */
+export function classifySidecarTaskView(
+  deps: Pick<SidecarResumeDeps, "taskId" | "persistedTask"> = {},
+): void {
+  const taskId = (deps.taskId ?? sidecarTaskId)();
+  if (!taskId) return;
+  if ((deps.persistedTask ?? defaultPersistedTask)(taskId) === undefined) return;
+  // Asked for its record: one with none is held from here on.
+  taskViewProven(taskId);
+}
+
 export async function resumeSidecarTask(
   deps: SidecarResumeDeps = {},
 ): Promise<SidecarResumeResult> {
   const taskId = (deps.taskId ?? sidecarTaskId)();
   if (!taskId) return { outcome: "no-task", warnings: [] };
   const task = (deps.persistedTask ?? defaultPersistedTask)(taskId);
-  if (!task?.environmentLocator) return { outcome: "not-up", warnings: [] };
+  // Only a task that came all the way up: one still starting (a runner that
+  // died mid-provision) is task-up's to finish, and resuming it would race
+  // that retry's loader, proxy steps and editor.
+  if (!task?.environmentLocator || task.statusMirror !== "running") return { outcome: "not-up", warnings: [] };
   const handle = await (deps.reconstruct ?? reconstructPersistedTaskEnvironment)(task);
   if (!handle) return { outcome: "not-up", warnings: [] };
   const workspacePath = handle.descriptor.workspacePath;
   const warnings: string[] = [];
 
+  if (task.envMode === "loader") {
+    try {
+      await (deps.loader ?? installMachineProjectEnvLoader)(handle);
+    } catch (error) {
+      // The loader remains fail-closed: no project value was baked into this
+      // machine. Keep repairing the editor/mounts, but make the degraded env
+      // channel visible to the sidecar's restart log.
+      warnings.push(
+        `project env loader: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+    // ADR-153: the proxy's CA and pins again (a reboot keeps neither the
+    // chain nor this runner's record of any of it).
+    const proxyWarning = await (deps.proxy ?? reconcileSidecarTaskProxy)(
+      handle,
+      activeSecretsProxy()?.runtime ?? null,
+      { start: false },
+    );
+    if (proxyWarning !== null) warnings.push(proxyWarning);
+  }
+
   const marker = await handle
     .readWorkspaceFile(`${workspacePath}/.uai/files-mounted`)
     .catch(() => null);

package/lib/standard-image.ts

@@ -60,6 +60,9 @@ export const ASDF_DATA_VOLUME = "uai-asdf-data";
  */
 export const STANDARD_DEFAULT_NODE_VERSION = "22.11.0";
 
+/** Exact Codex CLI release exposed to task runtimes through the shared volume. */
+export const STANDARD_CODEX_CLI_VERSION = "0.157.0";
+
 /**
  * Runtimes the standard image's asdf plugins can satisfy, with a sensible set
  * of advertised versions per kind (ADR-021 `runtimes`). These are the
@@ -510,9 +513,19 @@ async function runMaintenanceContainer(
  * e.g. a stale volume with `codex` but no `claude`, which makes `claude` exit
  * 127 in every task container. Reconciled on each host start.
  */
-const VOLUME_AGENT_CLIS: { bin: string; pkg: string }[] = [
-  { bin: "claude", pkg: "@anthropic-ai/claude-code" },
-  { bin: "codex", pkg: "@openai/codex" },
+const VOLUME_AGENT_CLIS: {
+  bin: string;
+  pkg: string;
+  version: string;
+  expectedVersionOutput?: string;
+}[] = [
+  { bin: "claude", pkg: "@anthropic-ai/claude-code", version: "latest" },
+  {
+    bin: "codex",
+    pkg: "@openai/codex",
+    version: STANDARD_CODEX_CLI_VERSION,
+    expectedVersionOutput: `codex-cli ${STANDARD_CODEX_CLI_VERSION}`,
+  },
 ];
 
 /**
@@ -521,7 +534,16 @@ const VOLUME_AGENT_CLIS: { bin: string; pkg: string }[] = [
  * locked reconcile below always performs its own proof before releasing.
  */
 async function probeVolumeAgentClis(): Promise<string[] | null> {
-  const bins = VOLUME_AGENT_CLIS.map((c) => c.bin).join(" ");
+  const checks = VOLUME_AGENT_CLIS.map((cli) => {
+    const missing = `echo "UAI_MISSING:${cli.bin}"`;
+    if (cli.expectedVersionOutput === undefined) {
+      return `"${cli.bin}" --version >/dev/null 2>&1 || ${missing}`;
+    }
+    return (
+      `version="$("${cli.bin}" --version 2>/dev/null)" && ` +
+      `[ "$version" = "${cli.expectedVersionOutput}" ] || ${missing}`
+    );
+  }).join("; ");
   // Probe by EXECUTING each bin (`--version`), not `command -v`. A stale asdf
   // shim — the shim file survives in the volume but the reshim DB no longer
   // maps it to an installed exe — passes `command -v` (the file is present and
@@ -542,7 +564,7 @@ async function probeVolumeAgentClis(): Promise<string[] | null> {
     STANDARD_IMAGE_TAG,
     "/bin/bash",
     "-c",
-    `for b in ${bins}; do "$b" --version >/dev/null 2>&1 || echo "UAI_MISSING:$b"; done`,
+    checks,
   ], SHORT_DOCKER_TIMEOUT_MS);
   if (check.code !== 0) {
     console.warn(
@@ -609,7 +631,9 @@ async function prepareAsdfMaintenanceLock(): Promise<boolean> {
 export function standardImageVolumeMaintenanceCommandForTest(
   autoUpdate: boolean,
 ): string {
-  const pkgs = VOLUME_AGENT_CLIS.map((c) => `${c.pkg}@latest`).join(" ");
+  const pkgs = VOLUME_AGENT_CLIS.map(
+    (cli) => `${cli.pkg}@${cli.version}`,
+  ).join(" ");
   const trustedNpmFlags =
     "--registry=https://registry.npmjs.org/ --userconfig=/dev/null " +
     "--globalconfig=/dev/uai-empty-npmrc";
@@ -625,6 +649,7 @@ export function standardImageVolumeMaintenanceCommandForTest(
     `COREPACK_ENABLE_UNSAFE_CUSTOM_URLS=0 COREPACK_INTEGRITY_CHECK=1 ` +
     `COREPACK_ENABLE_NETWORK=0 COREPACK_NPM_REGISTRY=https://registry.npmjs.org; ` +
     `default_node="$(/usr/bin/awk '$1 == "nodejs" { print $2; exit }' /home/node/.tool-versions)"; ` +
+    `required_codex="${STANDARD_CODEX_CLI_VERSION}"; ` +
     `if ! printf '%s' "$default_node" | /usr/bin/grep -Eq '^[0-9]+\\.[0-9]+\\.[0-9]+$'; then ` +
     `fail default-node; fi; ` +
     `[ "$default_node" = "${STANDARD_DEFAULT_NODE_VERSION}" ] || ` +
@@ -781,14 +806,17 @@ export function standardImageVolumeMaintenanceCommandForTest(
     `contained_executable "$candidate" "$candidate/bin/$b" || return 1; ` +
     `direct_version="$(as_node "$candidate/bin/$b" --version 2>/dev/null ` +
     `| /usr/bin/head -1)"; [ -n "$direct_version" ] || return 1; ` +
+    `if [ "$b" = codex ] && ` +
+    `[ "$direct_version" != "codex-cli $required_codex" ]; then return 1; fi; ` +
     `shim="$shims_root/$b"; [ ! -L "$shim" ] && [ -f "$shim" ] ` +
     `&& [ -x "$shim" ] || return 1; ` +
     `shim_version="$(as_node "$shim" --version 2>/dev/null ` +
     `| /usr/bin/head -1)"; [ "$shim_version" = "$direct_version" ]; }; ` +
     `repair_cli_once() { b="$1"; case "$b" in ` +
     `claude) pkg='@anthropic-ai/claude-code'; scope='@anthropic-ai'; ` +
-    `package_name='claude-code';; ` +
-    `codex) pkg='@openai/codex'; scope='@openai'; package_name='codex';; ` +
+    `package_name='claude-code'; version='latest';; ` +
+    `codex) pkg='@openai/codex'; scope='@openai'; package_name='codex'; ` +
+    `version="$required_codex";; ` +
     `*) return 1;; esac; ` +
     `package_path="$candidate/lib/node_modules/$scope/$package_name"; ` +
     `npm_prefix_is_safe || return 1; ` +
@@ -796,7 +824,7 @@ export function standardImageVolumeMaintenanceCommandForTest(
     `|| return 1; ` +
     `as_node /usr/bin/rm -rf --one-file-system -- ` +
     `"$candidate/bin/$b" "$package_path" || return 1; ` +
-    `as_node "$npm_bin" install -g --force "$pkg@latest" ${trustedNpmFlags} ` +
+    `as_node "$npm_bin" install -g --force "$pkg@$version" ${trustedNpmFlags} ` +
     `>/dev/null 2>&1 || return 1; ` +
     `run_asdf_reshim nodejs "$default_node" ` +
     `>/dev/null 2>&1 || return 1; cli_ready_once "$b"; }; ` +
@@ -841,6 +869,9 @@ export function standardImageVolumeMaintenanceCommandForTest(
     `|| [ ! -x "$shim" ]; then echo "UAI_STILL_BROKEN:$b-shim" >&2; ` +
     `failed=1; continue; fi; ` +
     `shim_version="$(as_node "$shim" --version 2>/dev/null | /usr/bin/head -1)"; ` +
+    `if [ "$b" = codex ] && ` +
+    `[ "$version" != "codex-cli $required_codex" ]; then ` +
+    `echo "UAI_STILL_BROKEN:$b-version" >&2; failed=1; continue; fi; ` +
     `if [ -z "$version" ] || [ "$shim_version" != "$version" ]; then ` +
     `echo "UAI_STILL_BROKEN:$b" >&2; failed=1; ` +
     `else printf '%s ' "$version"; fi; done; ` +
@@ -947,7 +978,11 @@ async function writeVolumeReconcileProof(): Promise<void> {
   try {
     writeFileSync(
       await volumeReconcileProofPath(),
-      `${JSON.stringify({ schemaVersion: 1, provedAt: Date.now() })}\n`,
+      `${JSON.stringify({
+        schemaVersion: 1,
+        codexVersion: STANDARD_CODEX_CLI_VERSION,
+        provedAt: Date.now(),
+      })}\n`,
       { mode: 0o600 },
     );
   } catch (error) {
@@ -963,8 +998,11 @@ async function volumeReconcileProofExists(): Promise<boolean> {
   try {
     const raw = JSON.parse(
       readFileSync(await volumeReconcileProofPath(), "utf8"),
-    ) as { schemaVersion?: unknown };
-    return raw?.schemaVersion === 1;
+    ) as { schemaVersion?: unknown; codexVersion?: unknown };
+    return (
+      raw?.schemaVersion === 1 &&
+      raw.codexVersion === STANDARD_CODEX_CLI_VERSION
+    );
   } catch {
     return false;
   }

package/lib/task-env-forwarder.ts

@@ -0,0 +1,228 @@
+import type { TaskEnvironmentHandle } from "./task-environment/types";
+import { isEnvironmentTransportProvider } from "./task-environment/types";
+import { MACHINE_GATEWAY_TUNNEL_PORT } from "./machine-gateway-tunnel";
+import {
+  installMachineProjectEnvLoader,
+  installMachineTaskForwarderAsset,
+} from "./machine-project-env-loader";
+import { MCP_GATEWAY_PORT, taskGatewayHost } from "./mcp-gateway";
+import { STANDARD_DEFAULT_NODE_VERSION } from "./standard-image";
+import {
+  taskGatewayForwarderSecretInput,
+  taskGatewayRegistrationForRecovery,
+} from "./task-gateway-state";
+import { TASK_FORWARDER_SECRET_BYTES } from "./task-gateway-protocol";
+import type { TaskGatewayRegistration } from "./task-gateway-state";
+
+const STEP_OUTPUT_BYTES = 256 * 1024;
+const APPLE_FORWARDER_NODE_PATH =
+  `/run/uai/asdf-lower/installs/nodejs/${STANDARD_DEFAULT_NODE_VERSION}/bin/node` as const;
+
+type TaskForwarderNodePath =
+  | "/usr/bin/node"
+  | "/usr/local/bin/node"
+  | typeof APPLE_FORWARDER_NODE_PATH;
+
+// Shared by initial machine provisioning and every recovery topology. Keep
+// the ownership/process proof in lockstep with task-up.sh's container
+// launcher. The generation secret arrives on stdin; no task file, argv entry,
+// or environment variable ever contains it.
+const START_TASK_FORWARDER = String.raw`set -eu
+task_id=$1
+generation=$2
+gateway_host=$3
+gateway_port=$4
+node_path=$5
+case "$node_path" in
+  /usr/bin/node | /usr/local/bin/node) ;;
+  ${APPLE_FORWARDER_NODE_PATH})
+    [ ! -L "$node_path" ] && [ -f "$node_path" ] && [ -x "$node_path" ] \
+      || exit 1
+    ;;
+  *) exit 1 ;;
+esac
+case "$gateway_port" in ''|*[!0-9]*) exit 1 ;; esac
+[ "$gateway_port" -ge 1 ] && [ "$gateway_port" -le 65535 ] || exit 1
+state_dir=/run/uai/task-forwarder
+pid_file=$state_dir/pid
+ready_file=$state_dir/ready
+error_file=$state_dir/error.log
+umask 077
+[ ! -L "$state_dir" ] || exit 1
+[ ! -e "$state_dir" ] || [ -d "$state_dir" ] || exit 1
+/usr/bin/install -d -o root -g root -m 0700 "$state_dir"
+
+if [ -f "$pid_file" ] && [ ! -L "$pid_file" ]; then
+  old_pid=$(/bin/cat "$pid_file" 2>/dev/null || true)
+  case "$old_pid" in ''|*[!0-9]*) old_pid= ;; esac
+  if [ -n "$old_pid" ] && /bin/kill -0 "$old_pid" 2>/dev/null; then
+    old_uid=$(/usr/bin/awk '/^Uid:/ { print $2; exit }' "/proc/$old_pid/status" 2>/dev/null || true)
+    old_args=$(/usr/bin/tr '\000' '\n' < "/proc/$old_pid/cmdline" 2>/dev/null || true)
+    # /run survives a Docker stop/start. Its recorded pid may have been
+    # reused by uai-init or another innocent process; treat that record as
+    # stale and never signal a process unless both uid and argv prove it is
+    # this task's prior forwarder.
+    if [ "$old_uid" = 65532 ] \
+       && printf '%s\n' "$old_args" | /bin/grep -Fxq '/usr/local/share/uai/uai-task-forwarder.mjs' \
+       && printf '%s\n' "$old_args" | /bin/grep -Fxq "$task_id"; then
+      /bin/kill -TERM "$old_pid"
+      attempts=0
+      while /bin/kill -0 "$old_pid" 2>/dev/null && [ "$attempts" -lt 50 ]; do
+        /bin/sleep 0.1
+        attempts=$((attempts + 1))
+      done
+      if /bin/kill -0 "$old_pid" 2>/dev/null; then
+        /bin/kill -KILL "$old_pid"
+      fi
+    fi
+  fi
+fi
+/bin/rm -f -- "$pid_file" "$ready_file" "$error_file"
+
+exec 3<&0
+/usr/bin/env -i PATH=/usr/bin:/bin \
+  /usr/bin/setsid \
+  /usr/bin/setpriv \
+    --reuid=65532 \
+    --regid=65532 \
+    --clear-groups \
+    --bounding-set=-all \
+    --inh-caps=-all \
+    --ambient-caps=-all \
+    --no-new-privs \
+  "$node_path" \
+    /usr/local/share/uai/uai-task-forwarder.mjs \
+    --task-id "$task_id" \
+    --generation "$generation" \
+    --gateway-host "$gateway_host" \
+    --gateway-port "$gateway_port" \
+    --listen-port 5877 \
+  <&3 3<&- >"$ready_file" 2>"$error_file" &
+forwarder_pid=$!
+exec 3<&-
+printf '%s\n' "$forwarder_pid" > "$pid_file"
+
+attempts=0
+while [ "$attempts" -lt 50 ]; do
+  /bin/kill -0 "$forwarder_pid" 2>/dev/null || exit 1
+  if [ -f "$ready_file" ] \
+     && [ "$(/bin/cat "$ready_file" 2>/dev/null || true)" = READY ]; then
+    exit 0
+  fi
+  /bin/sleep 0.1
+  attempts=$((attempts + 1))
+done
+exit 1`;
+
+export interface TaskEnvForwarderLaunchOptions {
+  gatewayHost: string;
+  gatewayPort: number;
+  nodePath: TaskForwarderNodePath;
+}
+
+/** Launch or replace one authenticated task forwarder. Consumes and wipes
+ * the caller-owned secret copy on every outcome. */
+export async function launchTaskEnvForwarder(
+  environment: Pick<TaskEnvironmentHandle<unknown>, "exec">,
+  identity: TaskGatewayRegistration,
+  secret: Uint8Array,
+  options: TaskEnvForwarderLaunchOptions,
+): Promise<void> {
+  if (
+    secret.byteLength !== TASK_FORWARDER_SECRET_BYTES ||
+    !Number.isSafeInteger(options.gatewayPort) ||
+    options.gatewayPort < 1 ||
+    options.gatewayPort > 65_535
+  ) {
+    secret.fill(0);
+    throw new Error("task env forwarder launch parameters are invalid");
+  }
+  try {
+    const result = await environment.exec({
+      argv: [
+        "/bin/bash",
+        "-c",
+        START_TASK_FORWARDER,
+        "uai-task-forwarder",
+        identity.taskId,
+        identity.generation,
+        options.gatewayHost,
+        String(options.gatewayPort),
+        options.nodePath,
+      ],
+      user: "root",
+      projectEnvProfile: "maintenance",
+      stdin: secret,
+      timeoutMs: 30_000,
+      maxOutputBytes: STEP_OUTPUT_BYTES,
+    });
+    if (
+      result.exitCode !== 0 ||
+      result.signal !== null ||
+      result.stdoutTruncated ||
+      result.stderrTruncated
+    ) {
+      throw new Error(
+        `task env forwarder failed to start: ${Buffer.from(result.stderr)
+          .toString("utf8")
+          .trim()
+          .slice(-512) || `exit ${String(result.exitCode)}`}`,
+      );
+    }
+  } finally {
+    secret.fill(0);
+  }
+}
+
+/** Reassert the loader process after runtime recovery, before consumers.
+ * Uses the task only through `exec`, so a caller can fence every exec. */
+export async function ensureContainerTaskEnvForwarder(
+  environment: Pick<TaskEnvironmentHandle<unknown>, "descriptor" | "exec">,
+): Promise<void> {
+  const { descriptor } = environment;
+  if (descriptor.envMode !== "loader") return;
+  const isTransport = isEnvironmentTransportProvider(
+    descriptor.locator.provider,
+  );
+  const directMachine = descriptor.locator.provider === "machine";
+  if (isTransport && !directMachine) {
+    // A fixed-task sidecar serves its own loopback and must not bind a second
+    // listener. Other non-machine transports share that conservative shape.
+    return;
+  }
+  if (directMachine) {
+    // A machine reboot preserves disk but not /run or the uid-65532 process.
+    // Refresh the current runner's root-owned assets before exporting the
+    // generation secret, then recreate the process below.
+    await installMachineProjectEnvLoader(environment);
+    await installMachineTaskForwarderAsset(environment);
+  }
+  const identity = taskGatewayRegistrationForRecovery(descriptor.taskId);
+  if (identity === null) {
+    throw new Error("task env gateway identity is not active during recovery");
+  }
+  const launch: TaskEnvForwarderLaunchOptions = directMachine
+    ? {
+        gatewayHost: "127.0.0.1",
+        gatewayPort: MACHINE_GATEWAY_TUNNEL_PORT,
+        nodePath: "/usr/bin/node",
+      }
+    : {
+        gatewayHost: await taskGatewayHost(),
+        gatewayPort: MCP_GATEWAY_PORT,
+        nodePath:
+          descriptor.locator.provider === "apple-container"
+            ? APPLE_FORWARDER_NODE_PATH
+            : "/usr/local/bin/node",
+      };
+  // The secret copy is taken last, with nothing left to await before the
+  // launch, which wipes it on every outcome: no failure strands it.
+  const secret = taskGatewayForwarderSecretInput(
+    identity.taskId,
+    identity.generation,
+  );
+  if (secret === null) {
+    throw new Error("task env gateway secret is unavailable during recovery");
+  }
+  await launchTaskEnvForwarder(environment, identity, secret, launch);
+}