@runuai/host 0.9.14 → 0.9.43

package/lib/engine-login.ts

@@ -0,0 +1,1952 @@
+/**
+ * Generation-scoped remote engine login (ADR-100).
+ *
+ * OAuth happens in a short-lived standard-image container, never in a task
+ * container. The cloud sees only a validated HTTPS authorization URL and
+ * secret-blind progress. One-time codes/callback queries are accepted once,
+ * consumed locally, and are never copied into an event, error, or log line.
+ */
+
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { constants, existsSync } from "node:fs";
+import {
+  chmod,
+  lstat,
+  mkdir,
+  mkdtemp,
+  open,
+  readdir,
+  realpath,
+  rename,
+  rm,
+  unlink,
+} from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+
+import {
+  isHostOpId,
+  MAX_ENGINE_LOGIN_QUERY_CHARS,
+  MAX_ENGINE_LOGIN_TEXT_CHARS,
+  MAX_ENGINE_LOGIN_URL_CHARS,
+  type EngineLoginCapability,
+  type EngineLoginErrorCode,
+  type EngineLoginEventFrame,
+  type EngineLoginKind,
+} from "../src/protocol";
+import { reinjectCodexRunningTasks } from "./codex-auth";
+import {
+  appleContainerRuntimeBinding,
+  pinnedContainerRuntimeProvider,
+} from "./container-runtime";
+import { dockerCli } from "./docker-exec";
+import { env } from "./env";
+import {
+  serializeEnvFileMutation,
+  writeEnvValuesAtomic,
+} from "./env-file";
+import { ASDF_DATA_VOLUME, STANDARD_IMAGE_TAG } from "./standard-image";
+
+export const ENGINE_LOGIN_TIMEOUT_MS = 10 * 60_000;
+// Global serialization keeps a failed per-operation stale-resource sweep from
+// ever deleting another live login's labeled container or marked temp dir.
+export const MAX_CONCURRENT_ENGINE_LOGINS = 1;
+
+const LOGIN_MOUNT = "/run/uai-engine-login";
+const LOGIN_HOME = `${LOGIN_MOUNT}/home`;
+const CODEX_HOME = `${LOGIN_MOUNT}/codex`;
+const MAX_OUTPUT_TAIL_BYTES = 64 * 1_024;
+const MAX_CODEX_AUTH_BYTES = 1024 * 1024;
+const DOCKER_CONTROL_TIMEOUT_MS = 15_000;
+const DOCKER_CLEANUP_TIMEOUT_MS = 5_000;
+const DOCKER_CLEANUP_ATTEMPTS = 3;
+const DOCKER_RUN_STOP_GRACE_MS = 1_000;
+const MAX_STALE_LOGIN_CONTAINERS = 64;
+const MAX_STALE_LOGIN_TEMP_DIRS = 64;
+const ENGINE_LOGIN_TEMP_DIR_PATTERN = /^uai-engine-login-[A-Za-z0-9]{6}$/;
+const ENGINE_LOGIN_TEMP_MARKER = ".uai-engine-login-owner";
+const ENGINE_LOGIN_TEMP_MARKER_VERSION = "v1";
+export const ENGINE_LOGIN_CONTAINER_LABEL = "com.runuai.engine-login";
+export const ENGINE_LOGIN_CONTAINER_LABEL_VALUE = "v1";
+
+type EmitEngineLoginEvent = (event: EngineLoginEventFrame) => void;
+
+export interface EngineLoginProcessResult {
+  readonly code: number | null;
+  readonly spawnFailed?: boolean;
+}
+
+/** A running `docker run --rm` login container. */
+export interface EngineLoginProcess {
+  readonly containerName: string;
+  readonly completion: Promise<EngineLoginProcessResult>;
+  writeInput(value: string): void;
+  stop(): Promise<void>;
+}
+
+export interface EngineLoginContainerRequest {
+  readonly engine: EngineLoginKind;
+  readonly containerName: string;
+  readonly tempDir: string;
+}
+
+export interface EngineLoginDockerResult {
+  readonly status: number | null;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+export type EngineLoginDockerExec = (
+  args: string[],
+  options: {
+    input?: string;
+    timeoutMs: number;
+    maxOutputBytes: number;
+  },
+) => Promise<EngineLoginDockerResult>;
+
+export interface EngineLoginTimers {
+  setTimeout(callback: () => void, delayMs: number): unknown;
+  clearTimeout(timer: unknown): void;
+}
+
+export interface EngineLoginSeams {
+  createTempDir(): Promise<string>;
+  removeTempDir(path: string): Promise<void>;
+  startContainer(
+    request: EngineLoginContainerRequest,
+    onOutput: (chunk: string) => void,
+  ): Promise<EngineLoginProcess>;
+  replayCodexCallback(
+    containerName: string,
+    callbackUrl: string,
+  ): Promise<void>;
+  reconcileStaleContainers(): Promise<void>;
+  persistClaudeToken(token: string): Promise<void>;
+  persistCodexAuth(sourceFile: string): Promise<void>;
+  refreshEngineAccountAgents(engine: "claude"): Promise<void>;
+  reinjectCodexRunningTasks(): Promise<void>;
+  ownerHome(): string;
+  procEnv: NodeJS.ProcessEnv;
+  fileExists(path: string): boolean;
+  randomHex(bytes: number): string;
+  timers: EngineLoginTimers;
+}
+
+export interface EngineLoginManagerOptions {
+  /** The running orchestrator owns this operation; main.ts supplies it. */
+  refreshEngineAccountAgents(engine: "claude"): Promise<void>;
+  /**
+   * Exact host directory used for short-lived bind inputs. main.ts supplies
+   * a private leaf under UAI_HOME; ambient Docker mounts it directly.
+   */
+  tempRoot?: string;
+  /** Defer Docker inventory until the first start when no runtime is selected. */
+  reconcileOnCreate?: boolean;
+  seams?: Partial<EngineLoginSeams>;
+}
+
+type OperationStage = "starting" | "awaiting_input" | "awaiting_callback";
+
+interface CodexCallbackTarget {
+  readonly origin: string;
+  readonly pathname: string;
+  readonly port: string;
+  readonly hostname: string;
+  readonly state: string;
+}
+
+interface LoginOperation {
+  readonly opId: string;
+  readonly engine: EngineLoginKind;
+  readonly emit: EmitEngineLoginEvent;
+  active: boolean;
+  finishing: boolean;
+  stage: OperationStage;
+  timer: unknown | null;
+  process: EngineLoginProcess | null;
+  tempDir: string | null;
+  launchPromise: Promise<void> | null;
+  callbackPromise: Promise<boolean> | null;
+  finishPromise: Promise<void> | null;
+  cleanupPromise: Promise<void> | null;
+  settlementPromise: Promise<void> | null;
+  suppressTerminalEvent: boolean;
+  outputTail: string;
+  inputUsed: boolean;
+  callbackUsed: boolean;
+  pendingInput: string | null;
+  callbackTarget: CodexCallbackTarget | null;
+}
+
+const defaultTimers: EngineLoginTimers = {
+  setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
+  clearTimeout: (timer) => clearTimeout(timer as ReturnType<typeof setTimeout>),
+};
+
+function unrefTimer(timer: unknown): void {
+  if (
+    typeof timer === "object" &&
+    timer !== null &&
+    "unref" in timer &&
+    typeof (timer as { unref?: unknown }).unref === "function"
+  ) {
+    (timer as { unref(): void }).unref();
+  }
+}
+
+function ownerHome(): string {
+  return process.env.UAI_OWNER_HOME?.trim() || homedir();
+}
+
+function envLocalPath(): string {
+  return join(env.uaiHome, ".env.local");
+}
+
+export async function persistClaudeTokenAtomic(
+  token: string,
+  options: {
+    envFile?: string;
+    procEnv?: NodeJS.ProcessEnv;
+  } = {},
+): Promise<void> {
+  if (extractClaudeOAuthToken(token) !== token) {
+    throw new Error("invalid Claude OAuth token");
+  }
+  const file = options.envFile ?? envLocalPath();
+  await serializeEnvFileMutation(file, () => {
+    writeEnvValuesAtomic(file, { CLAUDE_CODE_OAUTH_TOKEN: token });
+  });
+  // Agent availability and task env injection read the live process env.
+  (options.procEnv ?? process.env).CLAUDE_CODE_OAUTH_TOKEN = token;
+}
+
+export async function persistCodexAuthAtomic(
+  sourceFile: string,
+  options: { ownerHome?: string } = {},
+): Promise<void> {
+  const body = await readBoundedRegularFile(sourceFile, MAX_CODEX_AUTH_BYTES);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(body.toString("utf8"));
+  } catch {
+    throw new Error("Codex produced invalid auth data");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("Codex produced invalid auth data");
+  }
+  await writeSensitiveFileAtomic(
+    join(options.ownerHome ?? ownerHome(), ".codex", "auth.json"),
+    body,
+  );
+}
+
+function defaultSeams(options: EngineLoginManagerOptions): EngineLoginSeams {
+  const tempRoot = options.tempRoot;
+  return {
+    createTempDir: () => createEngineLoginTempDir(tempRoot),
+    removeTempDir: (path) => rm(path, { recursive: true, force: true }),
+    startContainer: startLoginContainer,
+    replayCodexCallback,
+    reconcileStaleContainers: () =>
+      reconcileStaleEngineLoginResources({ tempRoot }),
+    persistClaudeToken: (token) => persistClaudeTokenAtomic(token),
+    persistCodexAuth: (sourceFile) => persistCodexAuthAtomic(sourceFile),
+    refreshEngineAccountAgents: options.refreshEngineAccountAgents,
+    reinjectCodexRunningTasks: () => reinjectCodexRunningTasks(),
+    ownerHome,
+    procEnv: process.env,
+    fileExists: existsSync,
+    randomHex: (bytes) => randomBytes(bytes).toString("hex"),
+    timers: defaultTimers,
+  };
+}
+
+function withDefaults(options: EngineLoginManagerOptions): EngineLoginSeams {
+  const defaults = defaultSeams(options);
+  return {
+    ...defaults,
+    ...options.seams,
+    timers: { ...defaults.timers, ...options.seams?.timers },
+  };
+}
+
+/**
+ * One manager belongs to one authenticated socket generation. Disconnect must
+ * call `stopAll()` before dropping the socket emitter.
+ */
+export class EngineLoginManager {
+  private readonly seams: EngineLoginSeams;
+  private readonly operations = new Map<string, LoginOperation>();
+  private readonly engineOperations = new Map<EngineLoginKind, LoginOperation>();
+  private reconciliation: Promise<boolean>;
+
+  constructor(options: EngineLoginManagerOptions) {
+    this.seams = withDefaults(options);
+    this.reconciliation =
+      options.reconcileOnCreate === false
+        ? Promise.resolve(false)
+        : this.runReconciliation();
+  }
+
+  /** Secret-free current capability state. v1 deliberately claims no expiry. */
+  capabilities(): EngineLoginCapability[] {
+    const claudeConfigured = Boolean(
+      this.seams.procEnv.CLAUDE_CODE_OAUTH_TOKEN ||
+        this.seams.procEnv.ANTHROPIC_API_KEY ||
+        this.seams.procEnv.ANTHROPIC_AUTH_TOKEN,
+    );
+    const codexConfigured = this.seams.fileExists(
+      join(this.seams.ownerHome(), ".codex", "auth.json"),
+    );
+    return [
+      {
+        engine: "claude",
+        status: claudeConfigured ? "configured" : "missing",
+        loginSupported: true,
+      },
+      {
+        engine: "codex",
+        status: codexConfigured ? "configured" : "missing",
+        loginSupported: true,
+      },
+    ];
+  }
+
+  /** Reserve and launch without waiting for a human-paced OAuth flow. */
+  start(
+    opId: string,
+    engine: EngineLoginKind,
+    emit: EmitEngineLoginEvent,
+  ): boolean {
+    if (!isHostOpId(opId)) return false;
+    if (this.operations.has(opId)) {
+      safeEmit(emit, failedEvent(opId, engine, "unavailable", "Login operation already exists."));
+      return false;
+    }
+    if (this.engineOperations.has(engine)) {
+      safeEmit(
+        emit,
+        failedEvent(
+          opId,
+          engine,
+          "unavailable",
+          `A ${engineLabel(engine)} login is already in progress.`,
+        ),
+      );
+      return false;
+    }
+    if (this.operations.size >= MAX_CONCURRENT_ENGINE_LOGINS) {
+      safeEmit(
+        emit,
+        failedEvent(opId, engine, "unavailable", "Too many login operations are active."),
+      );
+      return false;
+    }
+
+    const operation: LoginOperation = {
+      opId,
+      engine,
+      emit,
+      active: true,
+      finishing: false,
+      stage: "starting",
+      timer: null,
+      process: null,
+      tempDir: null,
+      launchPromise: null,
+      callbackPromise: null,
+      finishPromise: null,
+      cleanupPromise: null,
+      settlementPromise: null,
+      suppressTerminalEvent: false,
+      outputTail: "",
+      inputUsed: false,
+      callbackUsed: false,
+      pendingInput: null,
+      callbackTarget: null,
+    };
+    this.operations.set(opId, operation);
+    this.engineOperations.set(engine, operation);
+    operation.timer = this.seams.timers.setTimeout(() => {
+      void this.timeout(operation);
+    }, ENGINE_LOGIN_TIMEOUT_MS);
+    unrefTimer(operation.timer);
+
+    safeEmit(emit, {
+      kind: "engine.login.event",
+      opId,
+      engine,
+      phase: "starting",
+      message: `Starting ${engineLabel(engine)} login on this host.`,
+    });
+    operation.launchPromise = this.launch(operation);
+    return true;
+  }
+
+  /** Consume Claude's one-time code exactly once. */
+  input(opId: string, text: string): boolean {
+    const operation = this.operations.get(opId);
+    if (
+      !operation ||
+      !this.isCurrent(operation) ||
+      operation.engine !== "claude" ||
+      operation.stage !== "awaiting_input" ||
+      operation.inputUsed ||
+      operation.finishing
+    ) {
+      return false;
+    }
+    if (!isValidOneTimeInput(text)) {
+      void this.fail(
+        operation,
+        "invalid_input",
+        "The one-time authorization code was rejected.",
+      );
+      return false;
+    }
+    operation.inputUsed = true;
+    operation.outputTail = "";
+    const value = `${text}\n`;
+    if (!operation.process) {
+      operation.pendingInput = value;
+      return true;
+    }
+    try {
+      operation.process.writeInput(value);
+      return true;
+    } catch {
+      void this.fail(
+        operation,
+        "invalid_input",
+        "The login process could not accept the one-time code.",
+      );
+      return false;
+    }
+  }
+
+  /** Validate and replay a Codex callback only to this operation's listener. */
+  async callback(opId: string, value: string): Promise<boolean> {
+    const operation = this.operations.get(opId);
+    if (
+      !operation ||
+      !this.isCurrent(operation) ||
+      operation.engine !== "codex" ||
+      operation.stage !== "awaiting_callback" ||
+      operation.callbackUsed ||
+      operation.finishing ||
+      !operation.process ||
+      !operation.callbackTarget
+    ) {
+      return false;
+    }
+    const query = validateCodexCallback(value, operation.callbackTarget);
+    if (!query) {
+      await this.fail(
+        operation,
+        "invalid_callback",
+        "The localhost callback was rejected.",
+      );
+      return false;
+    }
+    operation.callbackUsed = true;
+    const callbackUrl = callbackReplayUrl(operation.callbackTarget, query);
+    const replay = (async () => {
+      try {
+        await this.seams.replayCodexCallback(
+          operation.process!.containerName,
+          callbackUrl,
+        );
+      } catch {
+        if (this.isCurrent(operation)) {
+          await this.fail(
+            operation,
+            "invalid_callback",
+            "The localhost callback could not be delivered.",
+          );
+        }
+        return false;
+      }
+      return this.isCurrent(operation) || operation.finishing;
+    })();
+    operation.callbackPromise = replay;
+    try {
+      return await replay;
+    } finally {
+      if (operation.callbackPromise === replay) {
+        operation.callbackPromise = null;
+      }
+    }
+  }
+
+  /** Explicit operator cancellation emits one terminal event. */
+  async stop(opId: string): Promise<boolean> {
+    const operation = this.operations.get(opId);
+    if (!operation || !this.isCurrent(operation)) return false;
+    if (operation.finishPromise) {
+      // Credential commit is the irreversible boundary. Once it starts, join
+      // the truthful success/failure outcome instead of claiming cancellation.
+      await this.ensureSettlement(operation);
+      return true;
+    }
+    this.detach(operation);
+    safeEmit(operation.emit, {
+      kind: "engine.login.event",
+      opId: operation.opId,
+      engine: operation.engine,
+      phase: "cancelled",
+      message: "Login cancelled.",
+    });
+    await this.ensureSettlement(operation);
+    return true;
+  }
+
+  /**
+   * Generation teardown. Detach every operation and secret before awaiting
+   * Docker/fs cleanup, so no late child callback can touch a dead socket.
+   */
+  async stopAll(): Promise<void> {
+    const operations = [...this.operations.values()];
+    for (const operation of operations) {
+      operation.suppressTerminalEvent = true;
+      if (!operation.finishPromise) this.detach(operation);
+      else this.ensureSettlement(operation);
+    }
+    await Promise.all(
+      operations.map((operation) => this.ensureSettlement(operation)),
+    );
+  }
+
+  activeCount(): number {
+    let active = 0;
+    for (const operation of this.operations.values()) {
+      if (operation.active) active += 1;
+    }
+    return active;
+  }
+
+  private async launch(operation: LoginOperation): Promise<void> {
+    let tempDir: string | null = null;
+    let processHandle: EngineLoginProcess | null = null;
+    try {
+      if (!(await this.reconciliation)) {
+        // A daemon blip during the eager startup sweep gets one new bounded
+        // reconciliation on the next attempted login; never add an orphan on
+        // top of state whose ownership could not be established.
+        this.reconciliation = this.runReconciliation();
+        if (!(await this.reconciliation)) {
+          throw new Error("stale login containers could not be reconciled");
+        }
+      }
+      if (!this.isCurrent(operation)) return;
+      tempDir = await this.seams.createTempDir();
+      if (!this.isCurrent(operation)) {
+        await this.removeDetachedTemp(tempDir);
+        return;
+      }
+      operation.tempDir = tempDir;
+      const containerName = `uai-login-${operation.engine}-${this.seams.randomHex(8)}`;
+      processHandle = await this.seams.startContainer(
+        { engine: operation.engine, containerName, tempDir },
+        (chunk) => this.onOutput(operation, chunk),
+      );
+      if (!this.isCurrent(operation)) {
+        await this.stopDetachedProcess(processHandle);
+        if (operation.tempDir === tempDir) operation.tempDir = null;
+        await this.removeDetachedTemp(tempDir);
+        return;
+      }
+      operation.process = processHandle;
+      if (operation.pendingInput !== null) {
+        const pending = operation.pendingInput;
+        operation.pendingInput = null;
+        try {
+          processHandle.writeInput(pending);
+        } catch {
+          await this.fail(
+            operation,
+            "invalid_input",
+            "The login process could not accept the one-time code.",
+          );
+          return;
+        }
+      }
+      void processHandle.completion.then(
+        (result) => this.onProcessComplete(operation, result),
+        () =>
+          this.fail(
+            operation,
+            "start_failed",
+            "The login container stopped unexpectedly.",
+          ),
+      );
+    } catch {
+      if (processHandle && !operation.process) {
+        await this.stopDetachedProcess(processHandle);
+      }
+      if (tempDir && !operation.tempDir) await this.removeDetachedTemp(tempDir);
+      if (this.isCurrent(operation)) {
+        await this.fail(
+          operation,
+          "start_failed",
+          "The login container could not be started.",
+        );
+      }
+    }
+  }
+
+  private onOutput(operation: LoginOperation, chunk: string): void {
+    if (!this.isCurrent(operation) || operation.finishing) return;
+    operation.outputTail = appendUtf8Tail(
+      operation.outputTail,
+      chunk,
+      MAX_OUTPUT_TAIL_BYTES,
+    );
+
+    if (operation.engine === "claude") {
+      // Before the one-time input is consumed, token-shaped output could only
+      // be an authorization URL/detail or hostile terminal content. This also
+      // prevents an input echo from becoming the credential boundary.
+      const token = operation.inputUsed
+        ? extractClaudeOAuthToken(operation.outputTail)
+        : null;
+      if (token) {
+        operation.outputTail = "";
+        this.beginClaudeFinish(operation, token);
+        return;
+      }
+      if (operation.stage === "starting") {
+        const authorizeUrl = findSafeHttpsUrl(operation.outputTail);
+        if (authorizeUrl) {
+          operation.stage = "awaiting_input";
+          safeEmit(operation.emit, authorizeEvent(operation, authorizeUrl));
+          safeEmit(operation.emit, {
+            kind: "engine.login.event",
+            opId: operation.opId,
+            engine: operation.engine,
+            phase: "awaiting_input",
+            message: "Paste the one-time authorization code.",
+          });
+        }
+      }
+      return;
+    }
+
+    if (operation.stage === "starting") {
+      const authorization = findCodexAuthorization(operation.outputTail);
+      if (authorization) {
+        operation.callbackTarget = authorization.target;
+        operation.stage = "awaiting_callback";
+        safeEmit(
+          operation.emit,
+          authorizeEvent(operation, authorization.authorizeUrl),
+        );
+        safeEmit(operation.emit, {
+          kind: "engine.login.event",
+          opId: operation.opId,
+          engine: operation.engine,
+          phase: "awaiting_callback",
+          message: "Paste the failed localhost callback URL.",
+        });
+      }
+    }
+  }
+
+  private async onProcessComplete(
+    operation: LoginOperation,
+    result: EngineLoginProcessResult,
+  ): Promise<void> {
+    if (!this.isCurrent(operation) || operation.finishing) return;
+    if (operation.engine === "codex" && result.code === 0) {
+      this.beginCodexFinish(operation);
+      if (operation.finishPromise) await operation.finishPromise;
+      return;
+    }
+    await this.fail(
+      operation,
+      result.spawnFailed ? "unavailable" : "start_failed",
+      result.spawnFailed
+        ? "The login runtime is unavailable."
+        : `${engineLabel(operation.engine)} login did not complete.`,
+    );
+  }
+
+  private beginClaudeFinish(
+    operation: LoginOperation,
+    token: string,
+  ): void {
+    if (!this.isCurrent(operation) || operation.finishing) return;
+    operation.finishing = true;
+    this.clearOperationTimer(operation);
+    operation.finishPromise = this.commitClaude(operation, token);
+  }
+
+  private async commitClaude(
+    operation: LoginOperation,
+    token: string,
+  ): Promise<void> {
+    let terminal: EngineLoginEventFrame;
+    try {
+      await this.seams.persistClaudeToken(token);
+    } catch {
+      terminal = failedEvent(
+        operation.opId,
+        operation.engine,
+        "persist_failed",
+        "Claude authorized, but its credential could not be saved.",
+      );
+      await this.finishCommit(operation, terminal);
+      return;
+    }
+    // The credential is already durable. Refresh existing agents in the
+    // background: it may traverse many task containers, and must not retain
+    // this ephemeral login container/temp dir or block generation teardown.
+    runBestEffort(() => this.seams.refreshEngineAccountAgents("claude"));
+    terminal = {
+      kind: "engine.login.event",
+      opId: operation.opId,
+      engine: operation.engine,
+      phase: "succeeded",
+      message: "Claude connected.",
+    };
+    await this.finishCommit(operation, terminal);
+  }
+
+  private beginCodexFinish(operation: LoginOperation): void {
+    if (
+      !this.isCurrent(operation) ||
+      operation.finishing ||
+      !operation.tempDir
+    ) {
+      return;
+    }
+    operation.finishing = true;
+    this.clearOperationTimer(operation);
+    operation.finishPromise = this.commitCodex(operation);
+  }
+
+  private async commitCodex(operation: LoginOperation): Promise<void> {
+    const tempDir = operation.tempDir;
+    if (!tempDir) return;
+    let terminal: EngineLoginEventFrame;
+    try {
+      await this.seams.persistCodexAuth(
+        join(tempDir, "codex", "auth.json"),
+      );
+    } catch {
+      terminal = failedEvent(
+        operation.opId,
+        operation.engine,
+        "persist_failed",
+        "Codex authorized, but its credential could not be saved.",
+      );
+      await this.finishCommit(operation, terminal);
+      return;
+    }
+    runBestEffort(() => this.seams.reinjectCodexRunningTasks());
+    terminal = {
+      kind: "engine.login.event",
+      opId: operation.opId,
+      engine: operation.engine,
+      phase: "succeeded",
+      message: "Codex connected.",
+    };
+    await this.finishCommit(operation, terminal);
+  }
+
+  private async finishCommit(
+    operation: LoginOperation,
+    terminal: EngineLoginEventFrame,
+  ): Promise<void> {
+    if (this.isCurrent(operation)) this.detach(operation);
+    if (!operation.suppressTerminalEvent) safeEmit(operation.emit, terminal);
+    await this.cleanup(operation);
+  }
+
+  private async timeout(operation: LoginOperation): Promise<void> {
+    if (!this.isCurrent(operation)) return;
+    if (operation.finishPromise) {
+      await operation.finishPromise;
+      return;
+    }
+    this.detach(operation);
+    safeEmit(operation.emit, {
+      kind: "engine.login.event",
+      opId: operation.opId,
+      engine: operation.engine,
+      phase: "timed_out",
+      errorCode: "timeout",
+      message: "Login timed out.",
+    });
+    await this.ensureSettlement(operation);
+  }
+
+  private async fail(
+    operation: LoginOperation,
+    errorCode: EngineLoginErrorCode,
+    message: string,
+  ): Promise<void> {
+    if (!this.isCurrent(operation)) return;
+    if (operation.finishPromise) {
+      await operation.finishPromise;
+      return;
+    }
+    this.detach(operation);
+    safeEmit(
+      operation.emit,
+      failedEvent(operation.opId, operation.engine, errorCode, message),
+    );
+    await this.cleanup(operation);
+  }
+
+  private detach(operation: LoginOperation): void {
+    operation.active = false;
+    operation.outputTail = "";
+    operation.pendingInput = null;
+    operation.callbackTarget = null;
+    this.clearOperationTimer(operation);
+    // Keep the exact operation reserved in both maps until cleanup settles.
+    // stopAll() must be able to discover a terminal operation whose Docker/fs
+    // cleanup is still in flight, and a replacement login must not overlap it.
+    this.ensureSettlement(operation);
+  }
+
+  private cleanup(operation: LoginOperation): Promise<void> {
+    if (operation.cleanupPromise) return operation.cleanupPromise;
+    const processHandle = operation.process;
+    const tempDir = operation.tempDir;
+    operation.process = null;
+    operation.tempDir = null;
+    operation.cleanupPromise = (async () => {
+      if (processHandle) await this.stopDetachedProcess(processHandle);
+      if (tempDir) await this.removeDetachedTemp(tempDir);
+    })();
+    return operation.cleanupPromise;
+  }
+
+  private ensureSettlement(operation: LoginOperation): Promise<void> {
+    if (operation.settlementPromise) return operation.settlementPromise;
+    const launch = operation.launchPromise;
+    const finish = operation.finishPromise;
+    const callback = operation.callbackPromise;
+    operation.settlementPromise = (async () => {
+      // A detached launch owns any resource that appears after cancellation.
+      // Join it before snapshotting cleanup, then stop the container promptly
+      // while callback/credential completion settles independently.
+      if (launch) await launch;
+      const cleanup = this.cleanup(operation);
+      await Promise.all([
+        cleanup,
+        ...(finish ? [finish] : []),
+        ...(callback ? [callback] : []),
+      ]);
+    })().finally(() => {
+      if (this.operations.get(operation.opId) === operation) {
+        this.operations.delete(operation.opId);
+      }
+      if (this.engineOperations.get(operation.engine) === operation) {
+        this.engineOperations.delete(operation.engine);
+      }
+    });
+    return operation.settlementPromise;
+  }
+
+  private async stopDetachedProcess(
+    processHandle: EngineLoginProcess,
+  ): Promise<void> {
+    try {
+      await processHandle.stop();
+    } catch {
+      // A failed exact removal is not absence proof. Serialize a bounded
+      // labeled sweep behind any sweep already in flight and retain its false
+      // result so the next launch must retry before creating more resources.
+      await this.queueReconciliation();
+    }
+  }
+
+  private async removeDetachedTemp(path: string): Promise<void> {
+    try {
+      await this.seams.removeTempDir(path);
+    } catch {
+      // Codex may have written auth.json here. Queue the same container-first
+      // reconciliation used at boot and keep its false result as a launch
+      // gate rather than declaring a secret-bearing temp directory settled.
+      await this.queueReconciliation();
+    }
+  }
+
+  private isCurrent(operation: LoginOperation): boolean {
+    return operation.active && this.operations.get(operation.opId) === operation;
+  }
+
+  private clearOperationTimer(operation: LoginOperation): void {
+    if (operation.timer === null) return;
+    this.seams.timers.clearTimeout(operation.timer);
+    operation.timer = null;
+  }
+
+  private runReconciliation(): Promise<boolean> {
+    return this.seams.reconcileStaleContainers().then(
+      () => true,
+      () => false,
+    );
+  }
+
+  private queueReconciliation(): Promise<boolean> {
+    const queued = this.reconciliation.then(() => this.runReconciliation());
+    this.reconciliation = queued;
+    return queued;
+  }
+}
+
+function runBestEffort(work: () => Promise<void>): void {
+  try {
+    void work().catch(() => {
+      // Recovery/reconnect will inject the now-durable credential.
+    });
+  } catch {
+    // Treat a synchronous adapter failure the same as a rejected promise.
+  }
+}
+
+export function createEngineLoginManager(
+  options: EngineLoginManagerOptions,
+): EngineLoginManager {
+  return new EngineLoginManager(options);
+}
+
+function safeEmit(
+  emit: EmitEngineLoginEvent,
+  event: EngineLoginEventFrame,
+): void {
+  try {
+    emit(event);
+  } catch {
+    // Socket teardown calls stopAll; never turn a closed emitter into a crash.
+  }
+}
+
+function engineLabel(engine: EngineLoginKind): "Claude" | "Codex" {
+  return engine === "claude" ? "Claude" : "Codex";
+}
+
+function failedEvent(
+  opId: string,
+  engine: EngineLoginKind,
+  errorCode: EngineLoginErrorCode,
+  message: string,
+): EngineLoginEventFrame {
+  return {
+    kind: "engine.login.event",
+    opId,
+    engine,
+    phase: "failed",
+    errorCode,
+    message,
+  };
+}
+
+function authorizeEvent(
+  operation: LoginOperation,
+  url: string,
+): EngineLoginEventFrame {
+  return {
+    kind: "engine.login.event",
+    opId: operation.opId,
+    engine: operation.engine,
+    phase: "authorize",
+    url,
+  };
+}
+
+function isValidOneTimeInput(value: string): boolean {
+  return (
+    value.length >= 1 &&
+    value.length <= MAX_ENGINE_LOGIN_TEXT_CHARS &&
+    value.trim() === value &&
+    !/[\0-\x1f\x7f]/.test(value) &&
+    // The PTY echoes input. Never let a caller supply a token-shaped value
+    // that the output parser could mistake for the CLI's newly minted token.
+    extractClaudeOAuthToken(value) === null
+  );
+}
+
+function appendUtf8Tail(current: string, chunk: string, maxBytes: number): string {
+  const bytes = Buffer.from(current + chunk, "utf8");
+  if (bytes.byteLength <= maxBytes) return bytes.toString("utf8");
+  return bytes.subarray(bytes.byteLength - maxBytes).toString("utf8");
+}
+
+function stripTerminalControl(value: string): string {
+  return value
+    .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, "")
+    .replace(/\x1b\[[0-9;:?<=>]*[!-/]*[@-~]/g, "")
+    .replace(/\x1b[()][0-9A-B]/g, "")
+    .replace(/\x1b[78=>DEHM]/g, "")
+    .replace(/\r/g, "\n");
+}
+
+function candidateHttpsUrls(value: string): string[] {
+  const plain = stripTerminalControl(value);
+  return [...plain.matchAll(/https:\/\/[^\s<>"'\x00-\x1f]+/g)]
+    .map((match) => (match[0] ?? "").replace(/[),.;]+$/g, ""))
+    .filter(Boolean);
+}
+
+function parseSafeHttpsUrl(value: string): URL | null {
+  if (value.length < 1 || value.length > MAX_ENGINE_LOGIN_URL_CHARS) return null;
+  try {
+    const url = new URL(value);
+    if (
+      url.protocol !== "https:" ||
+      url.username ||
+      url.password ||
+      !url.hostname
+    ) {
+      return null;
+    }
+    return url.toString().length <= MAX_ENGINE_LOGIN_URL_CHARS ? url : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Exported narrow parsers make secret-boundary regressions easy to fuzz. */
+export function findSafeHttpsUrl(value: string): string | null {
+  for (const candidate of candidateHttpsUrls(value)) {
+    const parsed = parseSafeHttpsUrl(candidate);
+    if (parsed) return parsed.toString();
+  }
+  return null;
+}
+
+export function extractClaudeOAuthToken(value: string): string | null {
+  const plain = stripTerminalControl(value);
+  const match = /(?:^|[^A-Za-z0-9_-])(sk-ant-[A-Za-z0-9_-]{16,4096})(?![A-Za-z0-9_-])/.exec(
+    plain,
+  );
+  return match?.[1] ?? null;
+}
+
+function isLocalhost(hostname: string): boolean {
+  const normalized = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  return (
+    normalized === "localhost" ||
+    normalized === "127.0.0.1" ||
+    normalized === "::1"
+  );
+}
+
+function codexCallbackTarget(authorizeUrl: URL): CodexCallbackTarget | null {
+  const redirectValues = [
+    ...authorizeUrl.searchParams.getAll("redirect_uri"),
+    ...authorizeUrl.searchParams.getAll("redirect_url"),
+  ];
+  const states = authorizeUrl.searchParams.getAll("state");
+  if (
+    redirectValues.length !== 1 ||
+    !redirectValues[0] ||
+    states.length !== 1 ||
+    !states[0] ||
+    states[0].length > MAX_ENGINE_LOGIN_QUERY_CHARS
+  ) {
+    return null;
+  }
+  const redirectValue = redirectValues[0];
+  let redirect: URL;
+  try {
+    redirect = new URL(redirectValue);
+  } catch {
+    return null;
+  }
+  if (
+    redirect.protocol !== "http:" ||
+    !isLocalhost(redirect.hostname) ||
+    !redirect.port ||
+    redirect.username ||
+    redirect.password ||
+    redirect.search ||
+    redirect.hash ||
+    !/^\d{1,5}$/.test(redirect.port)
+  ) {
+    return null;
+  }
+  const port = Number(redirect.port);
+  if (port < 1 || port > 65_535) return null;
+  return {
+    origin: redirect.origin,
+    pathname: redirect.pathname || "/",
+    port: redirect.port,
+    hostname: redirect.hostname,
+    state: states[0],
+  };
+}
+
+function findCodexAuthorization(
+  value: string,
+): { authorizeUrl: string; target: CodexCallbackTarget } | null {
+  for (const candidate of candidateHttpsUrls(value)) {
+    const authorizeUrl = parseSafeHttpsUrl(candidate);
+    if (!authorizeUrl) continue;
+    const target = codexCallbackTarget(authorizeUrl);
+    if (target) return { authorizeUrl: authorizeUrl.toString(), target };
+  }
+  return null;
+}
+
+function validateCodexCallback(
+  value: string,
+  target: CodexCallbackTarget,
+): string | null {
+  if (
+    value.length < 1 ||
+    value.length > MAX_ENGINE_LOGIN_QUERY_CHARS ||
+    value.trim() !== value ||
+    /[\0\r\n]/.test(value)
+  ) {
+    return null;
+  }
+
+  let query: string;
+  if (/^https?:\/\//i.test(value)) {
+    let callback: URL;
+    try {
+      callback = new URL(value);
+    } catch {
+      return null;
+    }
+    if (
+      callback.protocol !== "http:" ||
+      !isLocalhost(callback.hostname) ||
+      callback.hostname !== target.hostname ||
+      callback.port !== target.port ||
+      callback.pathname !== target.pathname ||
+      callback.username ||
+      callback.password ||
+      callback.hash
+    ) {
+      return null;
+    }
+    query = callback.search.slice(1);
+  } else {
+    if (value.includes("#") || /^[A-Za-z][A-Za-z0-9+.-]*:/.test(value)) {
+      return null;
+    }
+    query = value.startsWith("?") ? value.slice(1) : value;
+  }
+  if (!query || query.length > MAX_ENGINE_LOGIN_QUERY_CHARS) return null;
+
+  const params = new URLSearchParams(query);
+  const codes = params.getAll("code");
+  const states = params.getAll("state");
+  if (
+    codes.length !== 1 ||
+    !codes[0] ||
+    states.length !== 1 ||
+    !states[0] ||
+    states[0] !== target.state
+  ) {
+    return null;
+  }
+  const normalized = params.toString();
+  return normalized.length <= MAX_ENGINE_LOGIN_QUERY_CHARS ? normalized : null;
+}
+
+function callbackReplayUrl(
+  target: CodexCallbackTarget,
+  query: string,
+): string {
+  const callback = new URL(target.pathname, target.origin);
+  callback.search = query;
+  return callback.toString();
+}
+
+async function startLoginContainer(
+  request: EngineLoginContainerRequest,
+  onOutput: (chunk: string) => void,
+): Promise<EngineLoginProcess> {
+  const args = engineLoginContainerArgs(request);
+  const child = spawn(engineLoginBackend().command, args, {
+    shell: false,
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+  child.stdout.setEncoding("utf8");
+  child.stderr.setEncoding("utf8");
+  child.stdout.on("data", (chunk: string) => onOutput(chunk));
+  child.stderr.on("data", (chunk: string) => onOutput(chunk));
+  child.stdin.on("error", () => {});
+
+  let stopped = false;
+  let settled = false;
+  let resolveCompletion: (result: EngineLoginProcessResult) => void = () => {};
+  const completion = new Promise<EngineLoginProcessResult>((resolve) => {
+    resolveCompletion = resolve;
+  });
+  const settle = (result: EngineLoginProcessResult): void => {
+    if (settled) return;
+    settled = true;
+    resolveCompletion(result);
+  };
+  child.once("error", () => settle({ code: null, spawnFailed: true }));
+  child.once("close", (code) => settle({ code }));
+
+  return {
+    containerName: request.containerName,
+    completion,
+    writeInput(value) {
+      if (stopped || child.stdin.destroyed) throw new Error("login input closed");
+      child.stdin.write(value);
+    },
+    async stop() {
+      if (stopped) return;
+      stopped = true;
+      await stopEngineLoginContainerProcess({
+        completion,
+        endInput: () => child.stdin.end(),
+        terminate: () => child.kill("SIGTERM"),
+        kill: () => child.kill("SIGKILL"),
+        remove: () => removeEngineLoginContainer(request.containerName),
+      });
+    },
+  };
+}
+
+export interface EngineLoginProcessStopControl {
+  readonly completion: Promise<EngineLoginProcessResult>;
+  endInput(): void;
+  terminate(): void;
+  kill(): void;
+  remove(): Promise<void>;
+}
+
+/**
+ * Close the docker-run client before proving/removing the daemon resource.
+ * Otherwise an in-flight `docker run` can create the container just after an
+ * early absence check, orphaning it across generation teardown.
+ */
+export async function stopEngineLoginContainerProcess(
+  control: EngineLoginProcessStopControl,
+): Promise<void> {
+  control.endInput();
+  control.terminate();
+  if (
+    !(await promiseSettlesWithin(
+      control.completion,
+      DOCKER_RUN_STOP_GRACE_MS,
+    ))
+  ) {
+    control.kill();
+    if (
+      !(await promiseSettlesWithin(
+        control.completion,
+        DOCKER_RUN_STOP_GRACE_MS,
+      ))
+    ) {
+      throw new Error("login docker client did not stop");
+    }
+  }
+  await control.remove();
+}
+
+async function promiseSettlesWithin(
+  promise: Promise<unknown>,
+  timeoutMs: number,
+): Promise<boolean> {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  try {
+    return await Promise.race([
+      promise.then(
+        () => true,
+        () => true,
+      ),
+      new Promise<boolean>((resolve) => {
+        timer = setTimeout(() => resolve(false), timeoutMs);
+        timer.unref?.();
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/** Pure command builder kept exported for the isolation regression test. */
+export function engineLoginContainerArgs(
+  request: EngineLoginContainerRequest,
+): string[] {
+  if (/[,\0\r\n]/.test(request.tempDir)) {
+    throw new Error("unsafe temporary path");
+  }
+  const uidArgs =
+    typeof process.getuid === "function" && typeof process.getgid === "function"
+      ? ["--user", `${process.getuid()}:${process.getgid()}`]
+      : [];
+  const command =
+    request.engine === "claude"
+      ? [
+          "/usr/bin/script",
+          "-qefc",
+          "exec claude setup-token",
+          "/dev/null",
+        ]
+      : ["codex", "login"];
+  if (engineLoginBackend().apple) {
+    // Same containment contract, Apple dialect: read-only root, all caps
+    // dropped, a plain tmpfs at /tmp (the Apple CLI takes no mount options —
+    // the VM boundary already denies device/suid tricks, which is also why
+    // the missing no-new-privileges knob costs nothing here), and -v mounts
+    // for the shared runtime volume + private temp leaf. The container runs
+    // as node: ownership maps transparently across the VM boundary, so the
+    // host uid/gid pin that Docker needs would be meaningless.
+    return [
+      "run",
+      "--rm",
+      "--name",
+      request.containerName,
+      "--label",
+      `${ENGINE_LOGIN_CONTAINER_LABEL}=${ENGINE_LOGIN_CONTAINER_LABEL_VALUE}`,
+      "--init",
+      "--interactive",
+      "--read-only",
+      "--cap-drop",
+      "ALL",
+      "--tmpfs",
+      "/tmp",
+      "-v",
+      `${ASDF_DATA_VOLUME}:/opt/asdf-data:ro`,
+      "-v",
+      `${request.tempDir}:${LOGIN_MOUNT}`,
+      "--user",
+      "node",
+      "--workdir",
+      "/home/node",
+      "--env",
+      `HOME=${LOGIN_HOME}`,
+      "--env",
+      `XDG_CONFIG_HOME=${LOGIN_HOME}/.config`,
+      "--env",
+      `XDG_DATA_HOME=${LOGIN_HOME}/.local/share`,
+      "--env",
+      `XDG_CACHE_HOME=${LOGIN_HOME}/.cache`,
+      "--env",
+      `CODEX_HOME=${CODEX_HOME}`,
+      "--env",
+      "ASDF_CONFIG_FILE=/dev/null",
+      "--env",
+      "ASDF_DEFAULT_TOOL_VERSIONS_FILENAME=.tool-versions",
+      STANDARD_IMAGE_TAG,
+      ...command,
+    ];
+  }
+  return [
+    "run",
+    "--rm",
+    "--name",
+    request.containerName,
+    "--label",
+    `${ENGINE_LOGIN_CONTAINER_LABEL}=${ENGINE_LOGIN_CONTAINER_LABEL_VALUE}`,
+    "--init",
+    "--interactive",
+    "--read-only",
+    "--cap-drop",
+    "ALL",
+    "--security-opt",
+    "no-new-privileges:true",
+    "--tmpfs",
+    "/tmp:rw,nosuid,nodev,noexec,size=64m,mode=1777",
+    "--mount",
+    `type=volume,src=${ASDF_DATA_VOLUME},dst=/opt/asdf-data,readonly`,
+    "--mount",
+    `type=bind,src=${request.tempDir},dst=${LOGIN_MOUNT}`,
+    ...uidArgs,
+    "--workdir",
+    "/home/node",
+    "--env",
+    `HOME=${LOGIN_HOME}`,
+    "--env",
+    `XDG_CONFIG_HOME=${LOGIN_HOME}/.config`,
+    "--env",
+    `XDG_DATA_HOME=${LOGIN_HOME}/.local/share`,
+    "--env",
+    `XDG_CACHE_HOME=${LOGIN_HOME}/.cache`,
+    "--env",
+    `CODEX_HOME=${CODEX_HOME}`,
+    "--env",
+    "ASDF_CONFIG_FILE=/dev/null",
+    "--env",
+    "ASDF_DEFAULT_TOOL_VERSIONS_FILENAME=.tool-versions",
+    STANDARD_IMAGE_TAG,
+    ...command,
+  ];
+}
+
+async function replayCodexCallback(
+  containerName: string,
+  callbackUrl: string,
+): Promise<void> {
+  const request = codexCallbackReplayDockerRequest(containerName, callbackUrl);
+  const result = await defaultEngineLoginDockerExec(request.args, {
+    input: request.input,
+    timeoutMs: DOCKER_CONTROL_TIMEOUT_MS,
+    maxOutputBytes: 8 * 1_024,
+  });
+  if (result.status !== 0) throw new Error("callback replay failed");
+}
+
+/**
+ * Docker and the in-container curl process receive a fixed argv. The full
+ * callback (including code/state) exists only in the child's stdin, so it is
+ * absent from process listings, daemon metadata, and Docker error messages.
+ */
+export function codexCallbackReplayDockerRequest(
+  containerName: string,
+  callbackUrl: string,
+): { args: string[]; input: string } {
+  if (!isEngineLoginContainerName(containerName)) {
+    throw new Error("invalid login container name");
+  }
+  if (/[\0\r\n]/.test(callbackUrl)) {
+    throw new Error("invalid callback URL");
+  }
+  const configUrl = callbackUrl
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"');
+  return {
+    args: [
+      "exec",
+      "--interactive",
+      containerName,
+      "/usr/bin/curl",
+      "--fail",
+      "--silent",
+      "--show-error",
+      "--max-time",
+      "10",
+      "--output",
+      "/dev/null",
+      "--config",
+      "-",
+    ],
+    input: `url = "${configUrl}"\n`,
+  };
+}
+
+function isEngineLoginContainerName(value: string): boolean {
+  return /^uai-login-(?:claude|codex)-[0-9a-f]{16}$/.test(value);
+}
+
+/** The CLI that owns login containers (ADR-106): the ambient docker client,
+ * or the bundled Apple CLI when that backend is pinned. Resolved per call so
+ * an HMR reload cannot strand a stale path; the pin itself never changes
+ * within a process. */
+function engineLoginBackend(): { command: string; apple: boolean } {
+  if (pinnedContainerRuntimeProvider() === "apple-container") {
+    const binding = appleContainerRuntimeBinding();
+    if (binding !== null) {
+      return { command: binding.containerCliPath, apple: true };
+    }
+  }
+  return { command: "docker", apple: false };
+}
+
+const defaultEngineLoginDockerExec: EngineLoginDockerExec = (args, options) => {
+  const backend = engineLoginBackend();
+  if (!backend.apple) return dockerCli(args, options);
+  return new Promise((resolveExec) => {
+    const child = spawn(backend.command, args, {
+      shell: false,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      const settle = setTimeout(() => settleResult(null), 5_000);
+      settle.unref?.();
+    }, options?.timeoutMs ?? 30_000);
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk: string) => (stdout += chunk));
+    child.stderr.on("data", (chunk: string) => (stderr += chunk));
+    child.stdin.on("error", () => {});
+    if (options?.input !== undefined) child.stdin.write(options.input);
+    child.stdin.end();
+    const settleResult = (status: number | null): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolveExec({ status, stdout, stderr });
+    };
+    child.on("error", () => settleResult(null));
+    child.on("close", (code) => settleResult(code));
+  });
+};
+
+/** The Apple CLI exits nonzero for both a missing container and a broken
+ * apiserver; only the not-found error naming this exact container proves
+ * absence. */
+function appleReportsAbsent(
+  result: { status: number | null; stdout: string; stderr: string },
+  containerName: string,
+): boolean {
+  // The complete bounded error line, never a substring: a not-found answer
+  // for `<name>-shadow` must not prove the absence of `<name>`.
+  return (
+    result.status !== 0 &&
+    result.stdout.trim() === "" &&
+    result.stderr
+      .split("\n")
+      .some(
+        (line) => line.trim() === `Error: container not found: ${containerName}`,
+      )
+  );
+}
+
+/** Force-remove one owned container, proving either success or exact absence. */
+export async function removeEngineLoginContainer(
+  containerName: string,
+  exec: EngineLoginDockerExec = defaultEngineLoginDockerExec,
+): Promise<void> {
+  if (!isEngineLoginContainerName(containerName)) {
+    throw new Error("invalid login container name");
+  }
+  const apple = engineLoginBackend().apple;
+  for (let attempt = 0; attempt < DOCKER_CLEANUP_ATTEMPTS; attempt += 1) {
+    let observedLabel: string | null = null;
+    if (apple) {
+      const inspected = await exec(["inspect", containerName], {
+        timeoutMs: DOCKER_CLEANUP_TIMEOUT_MS,
+        maxOutputBytes: 256 * 1_024,
+      });
+      if (inspected.status !== 0) {
+        if (await engineLoginContainerIsAbsent(containerName, exec)) return;
+        continue;
+      }
+      try {
+        const parsed = JSON.parse(inspected.stdout) as Array<{
+          configuration?: { labels?: Record<string, unknown> };
+        }>;
+        const label =
+          parsed[0]?.configuration?.labels?.[ENGINE_LOGIN_CONTAINER_LABEL];
+        observedLabel = typeof label === "string" ? label : null;
+      } catch {
+        continue;
+      }
+    } else {
+      const inspected = await exec(
+        [
+          "container",
+          "inspect",
+          "--format",
+          `{{ index .Config.Labels \"${ENGINE_LOGIN_CONTAINER_LABEL}\" }}`,
+          containerName,
+        ],
+        {
+          timeoutMs: DOCKER_CLEANUP_TIMEOUT_MS,
+          maxOutputBytes: 8 * 1_024,
+        },
+      );
+      if (inspected.status !== 0) {
+        if (await engineLoginContainerIsAbsent(containerName, exec)) return;
+        continue;
+      }
+      observedLabel = inspected.stdout.trim();
+    }
+    if (observedLabel !== ENGINE_LOGIN_CONTAINER_LABEL_VALUE) {
+      throw new Error("login container ownership could not be confirmed");
+    }
+
+    const removed = await exec(
+      apple
+        ? ["delete", "--force", containerName]
+        : ["rm", "--force", containerName],
+      {
+        timeoutMs: DOCKER_CLEANUP_TIMEOUT_MS,
+        maxOutputBytes: 8 * 1_024,
+      },
+    );
+    // Even a zero exit is followed by an exact-name absence proof. This closes
+    // daemon/client races and detects a same-name replacement before cleanup
+    // can be declared settled.
+    if (await engineLoginContainerIsAbsent(containerName, exec)) return;
+  }
+  throw new Error("login container cleanup could not be confirmed");
+}
+
+async function engineLoginContainerIsAbsent(
+  containerName: string,
+  exec: EngineLoginDockerExec,
+): Promise<boolean> {
+  if (engineLoginBackend().apple) {
+    const inspected = await exec(["inspect", containerName], {
+      timeoutMs: DOCKER_CLEANUP_TIMEOUT_MS,
+      maxOutputBytes: 256 * 1_024,
+    });
+    return appleReportsAbsent(inspected, containerName);
+  }
+  const inventory = await exec(
+    [
+      "container",
+      "ls",
+      "--all",
+      "--quiet",
+      "--filter",
+      `name=^/${containerName}$`,
+    ],
+    {
+      timeoutMs: DOCKER_CLEANUP_TIMEOUT_MS,
+      maxOutputBytes: 8 * 1_024,
+    },
+  );
+  return inventory.status === 0 && inventory.stdout.trim() === "";
+}
+
+/** Bounded boot sweep for containers left by a killed host or daemon blip. */
+export async function reconcileStaleEngineLoginContainers(
+  exec: EngineLoginDockerExec = defaultEngineLoginDockerExec,
+): Promise<void> {
+  let names: string[] | null = null;
+  const apple = engineLoginBackend().apple;
+  for (let attempt = 0; attempt < DOCKER_CLEANUP_ATTEMPTS; attempt += 1) {
+    if (apple) {
+      // No server-side label filter exists; list everything and select by the
+      // ownership label client-side (the container id IS its name).
+      const inventory = await exec(["list", "--all", "--format", "json"], {
+        timeoutMs: DOCKER_CLEANUP_TIMEOUT_MS,
+        maxOutputBytes: 4 * 1_024 * 1_024,
+      });
+      if (inventory.status !== 0) continue;
+      try {
+        const parsed = JSON.parse(inventory.stdout) as Array<{
+          configuration?: { id?: unknown; labels?: Record<string, unknown> };
+        }>;
+        names = parsed
+          .filter(
+            (item) =>
+              item.configuration?.labels?.[ENGINE_LOGIN_CONTAINER_LABEL] ===
+              ENGINE_LOGIN_CONTAINER_LABEL_VALUE,
+          )
+          .map((item) => item.configuration?.id)
+          .filter((id): id is string => typeof id === "string");
+      } catch {
+        continue;
+      }
+      break;
+    }
+    const inventory = await exec(
+      [
+        "container",
+        "ls",
+        "--all",
+        "--format",
+        "{{.Names}}",
+        "--filter",
+        `label=${ENGINE_LOGIN_CONTAINER_LABEL}=${ENGINE_LOGIN_CONTAINER_LABEL_VALUE}`,
+      ],
+      {
+        timeoutMs: DOCKER_CLEANUP_TIMEOUT_MS,
+        maxOutputBytes: 64 * 1_024,
+      },
+    );
+    if (inventory.status !== 0) continue;
+    names = inventory.stdout
+      .split("\n")
+      .map((name) => name.trim())
+      .filter(Boolean);
+    break;
+  }
+  if (names === null) {
+    throw new Error("stale login container inventory unavailable");
+  }
+  if (
+    names.length > MAX_STALE_LOGIN_CONTAINERS ||
+    names.some((name) => !isEngineLoginContainerName(name))
+  ) {
+    throw new Error("stale login container inventory is invalid");
+  }
+  for (const name of names) await removeEngineLoginContainer(name, exec);
+}
+
+function engineLoginTempMarkerBody(name: string): string {
+  return `${ENGINE_LOGIN_TEMP_MARKER_VERSION}:${name}\n`;
+}
+
+/** Create the private login workspace and its no-follow ownership marker. */
+export async function createEngineLoginTempDir(
+  requestedRoot?: string,
+): Promise<string> {
+  const root = requestedRoot ?? tmpdir();
+  if (requestedRoot !== undefined) await ensurePrivateEngineLoginTempRoot(root);
+  const path = await mkdtemp(join(root, "uai-engine-login-"));
+  let marker: Awaited<ReturnType<typeof open>> | null = null;
+  try {
+    const name = basename(path);
+    if (!ENGINE_LOGIN_TEMP_DIR_PATTERN.test(name)) {
+      throw new Error("login temp directory name is invalid");
+    }
+    await chmod(path, 0o700);
+    marker = await open(join(path, ENGINE_LOGIN_TEMP_MARKER), "wx", 0o600);
+    await marker.writeFile(engineLoginTempMarkerBody(name), "utf8");
+    await marker.sync();
+    await marker.close();
+    marker = null;
+    await syncDirectory(path);
+    return path;
+  } catch (error) {
+    if (marker) await marker.close().catch(() => undefined);
+    await rm(path, { recursive: true, force: true }).catch(() => undefined);
+    throw error;
+  }
+}
+
+/** Prepare only the dedicated bind leaf, never a broader Uai/home directory. */
+async function ensurePrivateEngineLoginTempRoot(root: string): Promise<void> {
+  if (
+    !root.startsWith("/") ||
+    resolve(root) !== root ||
+    root.length <= 1 ||
+    root.length > 4_096 ||
+    /[\0\r\n]/.test(root)
+  ) {
+    throw new Error("login temp root is invalid");
+  }
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  const entry = await lstat(root);
+  const uid = typeof process.getuid === "function" ? process.getuid() : null;
+  if (
+    !entry.isDirectory() ||
+    entry.isSymbolicLink() ||
+    (uid !== null && entry.uid !== uid) ||
+    (await realpath(root)) !== root
+  ) {
+    throw new Error("login temp root is unsafe");
+  }
+  await chmod(root, 0o700);
+}
+
+export interface EngineLoginTempReconcileOptions {
+  readonly tempRoot?: string;
+  readonly currentUid?: number | null;
+  readonly readNames?: (root: string) => Promise<string[]>;
+  readonly statEntry?: (path: string) => Promise<{
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+    readonly uid: number;
+  }>;
+  readonly markerIsValid?: (
+    path: string,
+    name: string,
+    currentUid: number | null,
+  ) => Promise<boolean>;
+  readonly removeEntry?: (path: string) => Promise<void>;
+}
+
+/**
+ * Remove only direct, exact mkdtemp-shaped directories owned by this service
+ * user. Symlinks, foreign-owned directories, and unrelated `/tmp` entries are
+ * deliberately untouched. Callers must reconcile labeled containers first so
+ * no still-live login process can own one of these mounts.
+ */
+export async function reconcileStaleEngineLoginTempDirs(
+  options: EngineLoginTempReconcileOptions = {},
+): Promise<void> {
+  const root = options.tempRoot ?? tmpdir();
+  // Injected inventory seams own their synthetic root metadata. Production
+  // reconciliation always uses the real reader and validates the exact leaf.
+  if (options.tempRoot !== undefined && options.readNames === undefined) {
+    await ensurePrivateEngineLoginTempRoot(root);
+  }
+  const names = await (options.readNames ?? ((path) => readdir(path)))(root);
+  const candidates = names.filter((name) =>
+    ENGINE_LOGIN_TEMP_DIR_PATTERN.test(name),
+  );
+  const uid =
+    options.currentUid === undefined
+      ? typeof process.getuid === "function"
+        ? process.getuid()
+        : null
+      : options.currentUid;
+  const statEntry = options.statEntry ?? lstat;
+  const markerIsValid = options.markerIsValid ?? engineLoginTempMarkerIsValid;
+  const removeEntry =
+    options.removeEntry ?? ((path: string) => rm(path, { recursive: true, force: true }));
+
+  const owned: string[] = [];
+  for (const name of candidates) {
+    const path = join(root, name);
+    let stat: Awaited<ReturnType<typeof statEntry>>;
+    try {
+      stat = await statEntry(path);
+    } catch (error) {
+      if (isNodeErrorCode(error, "ENOENT")) continue;
+      throw error;
+    }
+    if (
+      stat.isSymbolicLink() ||
+      !stat.isDirectory() ||
+      (uid !== null && stat.uid !== uid)
+    ) {
+      continue;
+    }
+    if (!(await markerIsValid(path, name, uid))) continue;
+    owned.push(path);
+  }
+  if (owned.length > MAX_STALE_LOGIN_TEMP_DIRS) {
+    throw new Error("stale login temp inventory is invalid");
+  }
+  for (const path of owned) await removeEntry(path);
+}
+
+async function engineLoginTempMarkerIsValid(
+  path: string,
+  name: string,
+  currentUid: number | null,
+): Promise<boolean> {
+  const markerPath = join(path, ENGINE_LOGIN_TEMP_MARKER);
+  let before: Awaited<ReturnType<typeof lstat>>;
+  try {
+    before = await lstat(markerPath);
+  } catch (error) {
+    if (isNodeErrorCode(error, "ENOENT")) return false;
+    throw error;
+  }
+  const expected = Buffer.from(engineLoginTempMarkerBody(name), "utf8");
+  if (
+    before.isSymbolicLink() ||
+    !before.isFile() ||
+    before.size !== expected.byteLength ||
+    (before.mode & 0o777) !== 0o600 ||
+    (currentUid !== null && before.uid !== currentUid)
+  ) {
+    return false;
+  }
+  const noFollow = "O_NOFOLLOW" in constants ? constants.O_NOFOLLOW : 0;
+  let handle: Awaited<ReturnType<typeof open>>;
+  try {
+    handle = await open(markerPath, constants.O_RDONLY | noFollow);
+  } catch (error) {
+    if (isNodeErrorCode(error, "ENOENT") || isNodeErrorCode(error, "ELOOP")) {
+      return false;
+    }
+    throw error;
+  }
+  try {
+    const opened = await handle.stat();
+    if (
+      !opened.isFile() ||
+      opened.dev !== before.dev ||
+      opened.ino !== before.ino ||
+      opened.size !== expected.byteLength ||
+      (opened.mode & 0o777) !== 0o600 ||
+      (currentUid !== null && opened.uid !== currentUid)
+    ) {
+      return false;
+    }
+    const body = await handle.readFile();
+    return body.equals(expected);
+  } finally {
+    await handle.close();
+  }
+}
+
+/** Container absence is proven before any secret-bearing temp is removed. */
+export async function reconcileStaleEngineLoginResources(
+  options: EngineLoginTempReconcileOptions = {},
+): Promise<void> {
+  await reconcileStaleEngineLoginContainers();
+  await reconcileStaleEngineLoginTempDirs(options);
+}
+
+function isNodeErrorCode(error: unknown, code: string): boolean {
+  return (
+    error instanceof Error &&
+    "code" in error &&
+    (error as NodeJS.ErrnoException).code === code
+  );
+}
+
+async function readBoundedRegularFile(
+  file: string,
+  maxBytes: number,
+): Promise<Buffer> {
+  const before = await lstat(file);
+  if (!before.isFile() || before.isSymbolicLink() || before.size > maxBytes) {
+    throw new Error("credential output is not a bounded regular file");
+  }
+  const noFollow = "O_NOFOLLOW" in constants ? constants.O_NOFOLLOW : 0;
+  const handle = await open(file, constants.O_RDONLY | noFollow);
+  try {
+    const opened = await handle.stat();
+    if (!opened.isFile() || opened.size < 1 || opened.size > maxBytes) {
+      throw new Error("credential output is not a bounded regular file");
+    }
+    const body = await handle.readFile();
+    if (body.byteLength < 1 || body.byteLength > maxBytes) {
+      throw new Error("credential output exceeds its size limit");
+    }
+    return body;
+  } finally {
+    await handle.close();
+  }
+}
+
+async function writeSensitiveFileAtomic(file: string, body: Buffer): Promise<void> {
+  const parent = dirname(file);
+  await ensureSensitiveParent(parent);
+  const temporary = join(
+    parent,
+    `.auth.json.${process.pid}.${randomBytes(8).toString("hex")}.tmp`,
+  );
+  let handle: Awaited<ReturnType<typeof open>> | null = null;
+  try {
+    handle = await open(temporary, "wx", 0o600);
+    await handle.writeFile(body);
+    await handle.sync();
+    await handle.close();
+    handle = null;
+    await rename(temporary, file);
+    await chmod(file, 0o600);
+    await syncDirectory(parent);
+  } finally {
+    if (handle) await handle.close().catch(() => undefined);
+    await unlink(temporary).catch((error: NodeJS.ErrnoException) => {
+      if (error.code !== "ENOENT") throw error;
+    });
+  }
+}
+
+async function ensureSensitiveParent(parent: string): Promise<void> {
+  try {
+    const current = await lstat(parent);
+    if (!current.isDirectory() || current.isSymbolicLink()) {
+      throw new Error("credential directory is not a local directory");
+    }
+    return;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+
+  await mkdir(parent, { recursive: true, mode: 0o700 });
+  // Re-check after creation. This catches an existing symlink followed by a
+  // recursive mkdir and a same-user replacement racing the initial ENOENT.
+  const created = await lstat(parent);
+  if (!created.isDirectory() || created.isSymbolicLink()) {
+    throw new Error("credential directory is not a local directory");
+  }
+}
+
+async function syncDirectory(directory: string): Promise<void> {
+  let handle: Awaited<ReturnType<typeof open>> | null = null;
+  try {
+    handle = await open(directory, "r");
+    await handle.sync();
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code !== "EINVAL" && code !== "ENOTSUP" && code !== "EISDIR") {
+      throw error;
+    }
+  } finally {
+    if (handle) await handle.close();
+  }
+}