@moondeck/station 0.0.0-stage → 1.0.0

package/lib/engine-login.ts

@@ -0,0 +1,2933 @@
+/**
+ * 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,
+  readFile,
+  realpath,
+  rename,
+  rm,
+  unlink,
+} from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+
+import {
+  ENGINE_LOGIN_KINDS,
+  HOST_ACCOUNT_SCOPE,
+  isEngineAccountLabel,
+  isEngineAccountScope,
+  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 type { CaptureFlowWire } from "../src/cloud-credentials";
+import type { CaptureOutcome, EngineCaptureMaterial } from "./capture-flow";
+import {
+  addCodexAccountFromAuthJson,
+  addEngineAccount,
+  addGrokAccountFromAuthJson,
+} from "./engine-accounts";
+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;
+/** Delay before the separate submit keystroke — long enough for the TUI to
+ * finish ingesting the pasted code chunk, short enough to feel instant. */
+export const SUBMIT_KEYSTROKE_DELAY_MS = 300;
+// Global serialization keeps a failed per-operation stale-resource sweep from
+// ever deleting another live login's labeled container or marked temp dir.
+/**
+ * Concurrent login containers per runner. Workspace sign-ins run side by
+ * side (ADR-136 sign-in box: a user is never told to wait for someone else's
+ * login); only the host's DEFAULT slot is exclusive, per engine. Bounded so
+ * a burst cannot fork containers without limit.
+ */
+export const MAX_CONCURRENT_ENGINE_LOGINS = 16;
+
+const LOGIN_MOUNT = "/run/uai-engine-login";
+const LOGIN_HOME = `${LOGIN_MOUNT}/home`;
+const CODEX_HOME = `${LOGIN_MOUNT}/codex`;
+/** grok writes its auth.json under GROK_HOME (host 0.9.105 remote sign-in). */
+const GROK_HOME = `${LOGIN_MOUNT}/grok`;
+/** The login image only carries grok when the host had it configured at its
+ * last image build; a shared host never did. Install into the op's private
+ * HOME on the fly (x.ai's installer, ~seconds) when the image lacks it. */
+const GROK_LOGIN_SHELL =
+  'g="$(command -v grok 2>/dev/null || true)"; ' +
+  '[ -n "$g" ] || { curl -fsSL https://x.ai/cli/install.sh | bash >/dev/null 2>&1; g="$HOME/.grok/bin/grok"; }; ' +
+  '[ -x "$g" ] || { echo "grok CLI is not available in the login image" >&2; exit 127; }; ' +
+  'exec "$g" login --device-auth';
+const MAX_OUTPUT_TAIL_BYTES = 64 * 1_024;
+/** script(1) transcripts of a login run a few KB; 1MB is a hostile-file cap. */
+const MAX_TRANSCRIPT_BYTES = 1_024 * 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 = "io.moondeck.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 AccountAddOutcome {
+  ok: boolean;
+  message: string;
+  id?: string;
+}
+
+export interface EngineLoginSeams {
+  createTempDir(): Promise<string>;
+  removeTempDir(path: string): Promise<void>;
+  startContainer(
+    request: EngineLoginContainerRequest,
+    onOutput: (chunk: string, stream?: "stdout" | "stderr") => void,
+  ): Promise<EngineLoginProcess>;
+  replayCodexCallback(
+    containerName: string,
+    callbackUrl: string,
+  ): Promise<void>;
+  reconcileStaleContainers(): Promise<void>;
+  /**
+   * Read the script(1) PTY transcript from the login leaf (null when absent
+   * or unreadable). The transcript is written INSIDE the container, so it is
+   * the pure PTY byte stream — structurally free of the container runtime's
+   * own stdio chatter, which on the Apple CLI painted XPC noise over the
+   * very cells the TUI's diff renderer skipped (live 2026-08-21).
+   */
+  readTranscript(tempDir: string): Promise<string | null>;
+  persistClaudeToken(token: string): Promise<void>;
+  persistCodexAuth(sourceFile: string): Promise<void>;
+  /** ADR-116: labeled extra-account captures (never the default slots).
+   *  Sync on a host that seals the capture locally; a promise on the ADR-136
+   *  sign-in box, whose sink awaits the credential store's write. */
+  addClaudeAccount(
+    label: string,
+    token: string,
+    scope: string,
+  ): AccountAddOutcome | Promise<AccountAddOutcome>;
+  addCodexAccount(
+    label: string,
+    authJson: string,
+    scope: string,
+  ): AccountAddOutcome | Promise<AccountAddOutcome>;
+  addGrokAccount(
+    label: string,
+    authJson: string,
+    scope: string,
+  ): AccountAddOutcome | Promise<AccountAddOutcome>;
+  persistGrokAuth(sourceFile: string): Promise<void>;
+  /** ADR-154: the sign-in box's sink for a capture flow; absent elsewhere. */
+  captureEngineAccount?(
+    flow: CaptureFlowWire,
+    engine: EngineLoginKind,
+    material: EngineCaptureMaterial,
+  ): Promise<CaptureOutcome>;
+  /** Optional engines ride the standard image only when configured; a fresh
+   * account may be the first configuration → rebuild (queue-deduped). */
+  ensureStandardImage(): 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;
+  /** ADR-136 sign-in box: only labeled, workspace-scoped sign-ins are
+   *  admitted — the default slots are the host owner's and the box has none. */
+  workspaceOnly?: boolean;
+  seams?: Partial<EngineLoginSeams>;
+  /** Rebuild the standard image after a successful capture (optional engines). */
+  ensureStandardImage?: () => Promise<unknown>;
+}
+
+type OperationStage =
+  | "starting"
+  | "awaiting_input"
+  | "awaiting_callback"
+  | "awaiting_confirmation";
+
+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;
+  /** stdout-only tail — the credential boundary (stderr never joins it). */
+  stdoutTail: string;
+  inputUsed: boolean;
+  callbackUsed: boolean;
+  pendingInput: string | null;
+  callbackTarget: CodexCallbackTarget | null;
+  /** ADR-154: when set, the capture is written as this revision of a cloud
+   * credential and nothing else happens to it. */
+  captureFlow: CaptureFlowWire | null;
+  /** ADR-116: when set, the captured credential lands in a labeled extra
+   * account instead of the default slot. */
+  accountLabel: string | null;
+  /** ADR-131 D3: the scope a labeled capture is stored under. */
+  accountScope: string;
+  /** Diagnosis breadcrumb: has ANY output arrived after the one-time code
+   * was written? Distinguishes "stdin never delivered" from "CLI answered
+   * and we ignored it" without reading the PTY transcript. */
+  postInputOutputSeen: boolean;
+}
+
+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,
+  );
+}
+
+export async function persistGrokAuthAtomic(
+  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("Grok produced invalid auth data");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("Grok produced invalid auth data");
+  }
+  await writeSensitiveFileAtomic(
+    join(options.ownerHome ?? ownerHome(), ".grok", "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 }),
+    readTranscript: async (tempDir) => {
+      try {
+        const body = await readBoundedRegularFile(
+          join(tempDir, "typescript"),
+          MAX_TRANSCRIPT_BYTES,
+        );
+        return body.toString("utf8");
+      } catch {
+        return null;
+      }
+    },
+    persistClaudeToken: (token) => persistClaudeTokenAtomic(token),
+    persistCodexAuth: (sourceFile) => persistCodexAuthAtomic(sourceFile),
+    addClaudeAccount: (label, token, scope) =>
+      addEngineAccount("claude", label, { token }, {}, scope),
+    addCodexAccount: (label, authJson, scope) =>
+      addCodexAccountFromAuthJson(label, authJson, {}, scope),
+    addGrokAccount: (label, authJson, scope) =>
+      addGrokAccountFromAuthJson(label, authJson, {}, scope),
+    persistGrokAuth: (sourceFile) => persistGrokAuthAtomic(sourceFile),
+    ensureStandardImage: async () => {
+      await options.ensureStandardImage?.();
+    },
+    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 workspaceOnly: boolean;
+  private readonly operations = new Map<string, LoginOperation>();
+  /**
+   * The DEFAULT-SLOT lock: one unlabeled capture per engine at a time, since
+   * two of them would race on the host's own `~/.codex`-style slot. Labeled
+   * (workspace) captures land in isolated accounts and never take it — on
+   * the ADR-136 sign-in box every workspace's sign-in runs alongside every
+   * other's; a user is never told to wait for someone else's login.
+   */
+  private readonly defaultSlotOperations = new Map<EngineLoginKind, LoginOperation>();
+  private reconciliation: Promise<boolean>;
+
+  constructor(options: EngineLoginManagerOptions) {
+    this.seams = withDefaults(options);
+    this.workspaceOnly = options.workspaceOnly === true;
+    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"),
+    );
+    const grokConfigured =
+      this.seams.fileExists(join(this.seams.ownerHome(), ".grok", "auth.json")) ||
+      Boolean(this.seams.procEnv.XAI_API_KEY);
+    return [
+      {
+        engine: "claude",
+        status: claudeConfigured ? "configured" : "missing",
+        loginSupported: true,
+      },
+      {
+        engine: "codex",
+        status: codexConfigured ? "configured" : "missing",
+        loginSupported: true,
+      },
+      {
+        engine: "grok",
+        status: grokConfigured ? "configured" : "missing",
+        loginSupported: true,
+      },
+    ];
+  }
+
+  /** Reserve and launch without waiting for a human-paced OAuth flow. */
+  start(
+    opId: string,
+    engine: EngineLoginKind,
+    emit: EmitEngineLoginEvent,
+    label?: string,
+    scope?: string,
+    flow?: CaptureFlowWire,
+  ): boolean {
+    if (!isHostOpId(opId)) return false;
+    // ADR-154: a capture flow names its own destination; it runs only on the
+    // sign-in box, which alone writes cloud credentials.
+    if (
+      flow !== undefined &&
+      (!this.workspaceOnly || this.seams.captureEngineAccount === undefined)
+    ) {
+      safeEmit(
+        emit,
+        failedEvent(opId, engine, "start_failed", "Only the Moondeck Cloud sign-in box writes cloud credentials."),
+      );
+      return false;
+    }
+    if (scope !== undefined && !isEngineAccountScope(scope)) {
+      safeEmit(
+        emit,
+        failedEvent(opId, engine, "start_failed", "The account scope is invalid."),
+      );
+      return false;
+    }
+    // ADR-136 sign-in box: nothing here may write a default slot, and a
+    // host-scope account would belong to a runner that owns no credential.
+    if (
+      this.workspaceOnly &&
+      flow === undefined &&
+      (scope === undefined || scope === HOST_ACCOUNT_SCOPE || label === undefined)
+    ) {
+      safeEmit(
+        emit,
+        failedEvent(
+          opId,
+          engine,
+          "start_failed",
+          "The Moondeck Cloud sign-in box signs in workspace accounts only.",
+        ),
+      );
+      return false;
+    }
+    // A workspace's sign-in is always a labeled account: the default slot is
+    // the host owner's and must never be written on a tenant's behalf.
+    if (scope !== undefined && scope !== HOST_ACCOUNT_SCOPE && label === undefined) {
+      safeEmit(
+        emit,
+        failedEvent(opId, engine, "start_failed", "A workspace account needs a label."),
+      );
+      return false;
+    }
+    if (label !== undefined && !isEngineAccountLabel(label)) {
+      safeEmit(
+        emit,
+        failedEvent(opId, engine, "start_failed", "The account label is invalid."),
+      );
+      return false;
+    }
+    if (this.operations.has(opId)) {
+      safeEmit(emit, failedEvent(opId, engine, "unavailable", "Login operation already exists."));
+      return false;
+    }
+    if (label === undefined && this.defaultSlotOperations.has(engine)) {
+      safeEmit(
+        emit,
+        failedEvent(
+          opId,
+          engine,
+          "unavailable",
+          `A ${engineLabel(engine)} login is already in progress.`,
+        ),
+      );
+      return false;
+    }
+    // Every login is a container; bound the fan-out without serialising it.
+    if (this.operations.size >= MAX_CONCURRENT_ENGINE_LOGINS) {
+      safeEmit(
+        emit,
+        failedEvent(
+          opId,
+          engine,
+          "unavailable",
+          "Too many sign-ins are running on this station right now; try again in a minute.",
+        ),
+      );
+      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: "",
+      stdoutTail: "",
+      inputUsed: false,
+      callbackUsed: false,
+      pendingInput: null,
+      callbackTarget: null,
+      captureFlow: flow ?? null,
+      accountLabel: label ?? null,
+      accountScope: scope ?? HOST_ACCOUNT_SCOPE,
+      postInputOutputSeen: false,
+    };
+    this.operations.set(opId, operation);
+    if (label === undefined && flow === undefined) {
+      this.defaultSlotOperations.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);
+    // Every rejection names itself in the host log: a silently dropped code
+    // reads as "Waiting for the host…" forever on the cloud pane (live
+    // 2026-08-20, the guard chain gave the operator nothing to act on).
+    // Never log `text` — it is one-time OAuth material.
+    if (!operation) {
+      console.warn(`[engine-login] input dropped: unknown opId ${opId}`);
+      return false;
+    }
+    const rejection = !this.isCurrent(operation)
+      ? "operation belongs to a previous bridge generation"
+      : operation.engine !== "claude"
+        ? `engine is ${operation.engine}, not claude`
+        : operation.stage !== "awaiting_input"
+          ? `stage is ${operation.stage}, not awaiting_input`
+          : operation.inputUsed
+            ? "a code was already submitted for this operation"
+            : operation.finishing
+              ? "the operation is already finishing"
+              : null;
+    if (rejection !== null) {
+      console.warn(
+        `[engine-login] input dropped for ${opId}: ${rejection}`,
+      );
+      return false;
+    }
+    if (!isValidOneTimeInput(text)) {
+      console.warn(
+        `[engine-login] input rejected for ${opId}: failed one-time-input validation (length ${text.length})`,
+      );
+      void this.fail(
+        operation,
+        "invalid_input",
+        "The one-time authorization code was rejected.",
+      );
+      return false;
+    }
+    console.log(
+      `[engine-login] input accepted for ${opId} (${text.length} chars)`,
+    );
+    operation.inputUsed = true;
+    operation.outputTail = "";
+    operation.stdoutTail = "";
+    if (!operation.process) {
+      console.log(
+        `[engine-login] input buffered for ${opId} (login process still starting)`,
+      );
+      operation.pendingInput = text;
+      return true;
+    }
+    return this.deliverOneTimeCode(operation, text);
+  }
+
+  /**
+   * The submit is a SEPARATE, delayed carriage return — both halves of that
+   * are load-bearing, reproduced live 2026-08-20/21:
+   *  - `\r`, not `\n`: the Ink raw-mode prompt only submits on carriage
+   *    return (a `\n` types the code and sits forever).
+   *  - a separate delayed write, not one chunk: a real 92-char code + `\r`
+   *    in one write is treated as PASTE data and the embedded `\r` is
+   *    swallowed — stars appear, nothing submits (short test codes slipped
+   *    under the paste threshold, which is why every isolated repro passed
+   *    while production hung).
+   */
+  private deliverOneTimeCode(operation: LoginOperation, text: string): boolean {
+    const process = operation.process;
+    if (!process) return false;
+    try {
+      process.writeInput(text);
+      console.log(
+        `[engine-login] input written to the login process for ${operation.opId}`,
+      );
+    } catch {
+      console.warn(
+        `[engine-login] input write FAILED for ${operation.opId}: the login process rejected stdin`,
+      );
+      void this.fail(
+        operation,
+        "invalid_input",
+        "The login process could not accept the one-time code.",
+      );
+      return false;
+    }
+    const submitTimer = setTimeout(() => {
+      if (
+        !this.isCurrent(operation) ||
+        operation.finishing ||
+        operation.process !== process
+      ) {
+        return;
+      }
+      try {
+        process.writeInput("\r");
+        console.log(
+          `[engine-login] submit keystroke dispatched for ${operation.opId}`,
+        );
+      } catch {
+        void this.fail(
+          operation,
+          "invalid_input",
+          "The login process could not accept the submit keystroke.",
+        );
+      }
+    }, SUBMIT_KEYSTROKE_DELAY_MS);
+    unrefTimer(submitTimer);
+    return true;
+  }
+
+  /** 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);
+    // Same named-rejection contract as input() (0.9.51): every silent exit
+    // here left an operator staring at "Waiting for the host…" with zero
+    // evidence on either side (live 2026-08-21 — the callback path was the
+    // last breadcrumb-free room in the login pipeline).
+    const refuse = (reason: string): false => {
+      console.log(
+        `[engine-login] callback refused for ${opId}: ${reason}`,
+      );
+      return false;
+    };
+    if (!operation) return refuse("unknown opId");
+    if (!this.isCurrent(operation)) return refuse("superseded operation");
+    if (operation.engine !== "codex") return refuse("wrong engine");
+    if (operation.stage !== "awaiting_callback") {
+      return refuse(`wrong stage (${operation.stage})`);
+    }
+    if (operation.callbackUsed) return refuse("callback already used");
+    if (operation.finishing) return refuse("operation finishing");
+    if (!operation.process) return refuse("no login process");
+    if (!operation.callbackTarget) return refuse("no callback target");
+    console.log(
+      `[engine-login] callback accepted for ${opId} (${value.length} chars); validating`,
+    );
+    const query = validateCodexCallback(value, operation.callbackTarget);
+    if (!query) {
+      console.warn(
+        `[engine-login] callback failed validation for ${opId} (state/shape mismatch with this attempt's authorize URL)`,
+      );
+      await this.fail(
+        operation,
+        "invalid_callback",
+        "The localhost callback was rejected.",
+      );
+      return false;
+    }
+    console.log(
+      `[engine-login] callback validated for ${opId}; replaying into the login container`,
+    );
+    operation.callbackUsed = true;
+    const callbackUrl = callbackReplayUrl(operation.callbackTarget, query);
+    const replay = (async () => {
+      try {
+        await this.seams.replayCodexCallback(
+          operation.process!.containerName,
+          callbackUrl,
+        );
+        console.log(
+          `[engine-login] callback replay delivered for ${operation.opId}; waiting for the CLI to finish`,
+        );
+      } 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, stream) => this.onOutput(operation, chunk, stream ?? "stdout"),
+      );
+      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;
+        if (!this.deliverOneTimeCode(operation, pending)) return;
+      }
+      void processHandle.completion.then(
+        (result) => this.onProcessComplete(operation, result),
+        () =>
+          this.fail(
+            operation,
+            "start_failed",
+            "The login container stopped unexpectedly.",
+          ),
+      );
+    } catch (error) {
+      // The operator sees a one-line failure; the journal must say WHY (the
+      // 2026-09-09 sweep refusal was silent for six hours).
+      console.warn(
+        `[engine-login] ${operation.engine} login could not start: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+      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,
+    stream: "stdout" | "stderr" = "stdout",
+  ): void {
+    if (!this.isCurrent(operation) || operation.finishing) return;
+    operation.outputTail = appendUtf8Tail(
+      operation.outputTail,
+      chunk,
+      MAX_OUTPUT_TAIL_BYTES,
+    );
+    if (stream === "stdout") {
+      // The CREDENTIAL boundary reads stdout only: stderr chunks (the Apple
+      // runtime's XPC chatter) interleaving into a merged tail once produced
+      // a corrupted token-shaped capture (live 2026-08-21). The merged tail
+      // above stays for URL detection and human-facing evidence.
+      operation.stdoutTail = appendUtf8Tail(
+        operation.stdoutTail,
+        chunk,
+        MAX_OUTPUT_TAIL_BYTES,
+      );
+    }
+
+    if (operation.engine === "claude") {
+      if (operation.inputUsed && !operation.postInputOutputSeen) {
+        operation.postInputOutputSeen = true;
+        console.log(
+          `[engine-login] output resumed after input for ${operation.opId} — the code reached the login TUI`,
+        );
+      }
+      // The TUI answers a bad/expired/mismatched code with an error AND an
+      // open prompt — no exit, no token. Detect it and fail visibly instead
+      // of the silent wait-for-timeout that hid the 2026-08-20 hangs.
+      if (operation.inputUsed && !operation.finishing) {
+        const cliError = detectClaudeCliError(operation.outputTail);
+        if (cliError) {
+          console.warn(
+            `[engine-login] login CLI rejected the code for ${operation.opId}: ${cliError}`,
+          );
+          void this.fail(
+            operation,
+            "invalid_input",
+            `The sign-in CLI rejected the code: ${cliError} Make sure the code comes from THIS attempt's authorization page, then retry.`,
+          );
+          return;
+        }
+      }
+      // 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.
+      // The scan reads the RECONSTRUCTED screen, not the raw stream: the
+      // TUI's diff renderer skips already-correct cells, so the raw bytes
+      // never carry the contiguous token (see renderTerminalScreenText).
+      const token = operation.inputUsed
+        ? extractClaudeOAuthToken(renderTerminalScreenText(operation.stdoutTail))
+        : null;
+      if (token) {
+        console.log(
+          `[engine-login] token detected in CLI output for ${operation.opId}; persisting`,
+        );
+        operation.outputTail = "";
+        operation.stdoutTail = "";
+        this.beginClaudeFinish(operation, token);
+        return;
+      }
+      if (operation.stage === "starting") {
+        const authorizeUrl = findSafeHttpsUrl(operation.outputTail);
+        if (authorizeUrl) {
+          console.log(
+            `[engine-login] authorize URL found for ${operation.opId}; awaiting the one-time code`,
+          );
+          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 device =
+        operation.engine === "grok"
+          ? findGrokDeviceAuthorization(operation.outputTail)
+          : findCodexDeviceAuthorization(operation.outputTail);
+      if (device) {
+        console.log(
+          `[engine-login] ${operation.engine} device authorization found for ${operation.opId}; awaiting operator confirmation`,
+        );
+        operation.stage = "awaiting_confirmation";
+        safeEmit(
+          operation.emit,
+          authorizeEvent(operation, device.verificationUrl),
+        );
+        safeEmit(operation.emit, {
+          kind: "engine.login.event",
+          opId: operation.opId,
+          engine: operation.engine,
+          phase: "awaiting_confirmation",
+          code: device.userCode,
+          message: `Enter code ${device.userCode} on the verification page. Nothing to paste here — this completes on its own.`,
+        });
+        return;
+      }
+      if (operation.engine !== "codex") return;
+      const authorization = findCodexAuthorization(operation.outputTail);
+      if (authorization) {
+        // Symmetric with the claude branch: this breadcrumb's ABSENCE was
+        // unreadable during the 2026-08-21 hunt — silence meant either "no
+        // output arrived" or "detection fired, codex just never says so".
+        console.log(
+          `[engine-login] codex authorize URL found for ${operation.opId}; awaiting the callback URL`,
+        );
+        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" || operation.engine === "grok") &&
+      result.code === 0
+    ) {
+      this.beginCodexFinish(operation);
+      if (operation.finishPromise) await operation.finishPromise;
+      return;
+    }
+    if (
+      operation.engine === "claude" &&
+      result.code === 0 &&
+      operation.inputUsed &&
+      operation.tempDir
+    ) {
+      // A clean exit after the code went in means the CLI almost certainly
+      // minted and printed the token — a stream capture that saw nothing is
+      // the capture's failure, not the login's. The relayed stream can be
+      // polluted by the container runtime's own chatter (the Apple CLI's XPC
+      // noise painted characters over the cells the TUI's diff renderer
+      // skipped, corrupting the reconstructed screen — live 2026-08-21 on
+      // the Air, straight after the Linux fix). The PTY transcript is
+      // written inside the container and cannot contain that noise, so it
+      // gets the authoritative re-read before this operation is failed.
+      const transcript = await this.seams.readTranscript(operation.tempDir);
+      if (!this.isCurrent(operation) || operation.finishing) return;
+      const token = transcript
+        ? extractClaudeOAuthToken(renderTerminalScreenText(transcript))
+        : null;
+      if (token) {
+        console.log(
+          `[engine-login] token recovered from the PTY transcript for ${operation.opId}; persisting`,
+        );
+        operation.outputTail = "";
+        operation.stdoutTail = "";
+        this.beginClaudeFinish(operation, token);
+        if (operation.finishPromise) await operation.finishPromise;
+        return;
+      }
+    }
+    const evidence = lastSignificantOutputLine(operation.outputTail);
+    console.warn(
+      `[engine-login] login process for ${operation.opId} ended (exit ${result.code ?? "spawn-failed"}) before completion` +
+        (evidence ? `; last output: ${evidence}` : ""),
+    );
+    await this.fail(
+      operation,
+      result.spawnFailed ? "unavailable" : "start_failed",
+      result.spawnFailed
+        ? "The login runtime is unavailable."
+        : `${engineLabel(operation.engine)} login did not complete.${evidence ? ` Last output: ${evidence}` : ""}`,
+    );
+  }
+
+  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;
+    if (operation.captureFlow !== null) {
+      await this.finishCapture(operation, {
+        authKind: "env",
+        env: { CLAUDE_CODE_OAUTH_TOKEN: token },
+      });
+      return;
+    }
+    if (operation.accountLabel !== null) {
+      // ADR-116: labeled capture — an extra account, not the default slot.
+      // Extras are picked up at the next agent spawn / rotation, so no
+      // running-agent refresh is needed (mirrors the local accounts API).
+      const added = await this.seams.addClaudeAccount(
+        operation.accountLabel,
+        token,
+        operation.accountScope,
+      );
+      terminal = added.ok
+        ? {
+            kind: "engine.login.event",
+            opId: operation.opId,
+            engine: operation.engine,
+            phase: "succeeded",
+            message: added.message,
+            ...(added.id === undefined ? {} : { accountId: added.id }),
+          }
+        : failedEvent(
+            operation.opId,
+            operation.engine,
+            "persist_failed",
+            added.message,
+          );
+      await this.finishCommit(operation, terminal);
+      return;
+    }
+    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);
+  }
+
+  /** ADR-154: hand a capture to the box's sink and report its revision. */
+  private async finishCapture(
+    operation: LoginOperation,
+    material: EngineCaptureMaterial,
+  ): Promise<void> {
+    const sink = this.seams.captureEngineAccount;
+    const outcome =
+      sink && operation.captureFlow
+        ? await sink(operation.captureFlow, operation.engine, material)
+        : { ok: false, message: "Only the Moondeck Cloud sign-in box writes cloud credentials." };
+    await this.finishCommit(
+      operation,
+      outcome.ok && outcome.capture
+        ? {
+            kind: "engine.login.event",
+            opId: operation.opId,
+            engine: operation.engine,
+            phase: "succeeded",
+            message: outcome.message,
+            capture: outcome.capture,
+          }
+        : failedEvent(operation.opId, operation.engine, "persist_failed", outcome.message),
+    );
+  }
+
+  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;
+    // codex and grok share the shape: a device-code CLI that exits 0 after
+    // writing auth.json under its HOME var (CODEX_HOME / GROK_HOME), which
+    // the container mounts from the op's private leaf.
+    const grok = operation.engine === "grok";
+    const authFile = join(tempDir, grok ? "grok" : "codex", "auth.json");
+    const label = grok ? "Grok" : "Codex";
+    let terminal: EngineLoginEventFrame;
+    if (operation.captureFlow !== null) {
+      let contents: string;
+      try {
+        contents = await readFile(authFile, "utf8");
+      } catch {
+        await this.finishCommit(
+          operation,
+          failedEvent(
+            operation.opId,
+            operation.engine,
+            "persist_failed",
+            `${label} authorized, but its credential could not be read.`,
+          ),
+        );
+        return;
+      }
+      await this.finishCapture(operation, {
+        authKind: "config-dir",
+        files: { "auth.json": contents.endsWith("\n") ? contents : `${contents}\n` },
+      });
+      return;
+    }
+    if (operation.accountLabel !== null) {
+      // ADR-116: labeled capture — the auth.json this login produced becomes
+      // an isolated extra account instead of overwriting ~/.codex.
+      let added: AccountAddOutcome;
+      try {
+        const contents = await readFile(authFile, "utf8");
+        added = await (grok
+          ? this.seams.addGrokAccount(
+              operation.accountLabel,
+              contents,
+              operation.accountScope,
+            )
+          : this.seams.addCodexAccount(
+              operation.accountLabel,
+              contents,
+              operation.accountScope,
+            ));
+      } catch {
+        added = {
+          ok: false,
+          message: `${label} authorized, but its credential could not be read.`,
+        };
+      }
+      terminal = added.ok
+        ? {
+            kind: "engine.login.event",
+            opId: operation.opId,
+            engine: operation.engine,
+            phase: "succeeded",
+            message: added.message,
+            ...(added.id === undefined ? {} : { accountId: added.id }),
+          }
+        : failedEvent(
+            operation.opId,
+            operation.engine,
+            "persist_failed",
+            added.message,
+          );
+      await this.finishCommit(operation, terminal);
+      if (added.ok) runBestEffort(() => this.seams.ensureStandardImage());
+      return;
+    }
+    try {
+      if (grok) await this.seams.persistGrokAuth(authFile);
+      else await this.seams.persistCodexAuth(authFile);
+    } catch {
+      terminal = failedEvent(
+        operation.opId,
+        operation.engine,
+        "persist_failed",
+        `${label} authorized, but its credential could not be saved.`,
+      );
+      await this.finishCommit(operation, terminal);
+      return;
+    }
+    if (!grok) runBestEffort(() => this.seams.reinjectCodexRunningTasks());
+    terminal = {
+      kind: "engine.login.event",
+      opId: operation.opId,
+      engine: operation.engine,
+      phase: "succeeded",
+      message: `${label} connected.`,
+    };
+    await this.finishCommit(operation, terminal);
+    runBestEffort(() => this.seams.ensureStandardImage());
+  }
+
+  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;
+    }
+    // ADR-116: attach the CLI's last visible line — a remote operator staring
+    // at "Waiting for the host…" (live 2026-08-20, apple-container) otherwise
+    // has zero evidence of where the flow died.
+    const evidence = lastSignificantOutputLine(operation.outputTail);
+    this.detach(operation);
+    safeEmit(operation.emit, {
+      kind: "engine.login.event",
+      opId: operation.opId,
+      engine: operation.engine,
+      phase: "timed_out",
+      errorCode: "timeout",
+      message: evidence
+        ? `Login timed out. Last output: ${evidence}`
+        : "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.stdoutTail = "";
+    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.defaultSlotOperations.get(operation.engine) === operation) {
+        this.defaultSlotOperations.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);
+}
+
+/** Detect the TUI's post-input rejection ("OAuth error: Invalid code…",
+ * expired codes, …) in the sanitized output. ANSI stripping can eat spaces
+ * ("Invalidcode"), so the patterns tolerate missing whitespace. Exported for
+ * tests. */
+export function detectClaudeCliError(tail: string): string | null {
+  const lines = tail
+    .replace(/\u001b\[[0-9;?]*[ -\/]*[@-~]/g, "")
+    .replace(/[\u0000-\u0009\u000b-\u001f\u007f]/g, "")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+  const match = lines.find((line) =>
+    /oauth\s*error|invalid\s*cod|code\s*.{0,12}expired|authentication\s*failed/i.test(
+      line,
+    ),
+  );
+  if (!match) return null;
+  if (/sk-ant-|Bearer |[A-Za-z0-9_-]{40,}/.test(match)) return null;
+  return match.slice(0, 200);
+}
+
+/** The last visible, sanitized line of the login CLI's output — bounded and
+ * secret-checked so it can ride a terminal event message (ADR-116). Anything
+ * token-shaped disqualifies the whole line rather than risking a partial. */
+function lastSignificantOutputLine(tail: string): string | null {
+  // stripTerminalControl handles the shapes the old inline regex missed —
+  // private-parameter CSI (kitty's ESC[<u, ESC[>4m) and charset selects
+  // (ESC(B) — whose husks once surfaced verbatim as "(B[>4m[<u" evidence.
+  const lines = stripTerminalControl(tail)
+    .replace(/[\u0000-\u0009\u000b-\u001f\u007f]/g, "")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 3);
+  const last = lines.at(-1);
+  if (!last) return null;
+  if (/sk-ant-|Bearer |[A-Za-z0-9_-]{40,}/.test(last)) return null;
+  return last.slice(0, 200);
+}
+
+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" | "Grok" {
+  return engine === "claude" ? "Claude" : engine === "codex" ? "Codex" : "Grok";
+}
+
+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");
+}
+
+const SCREEN_MAX_ROWS = 200;
+const SCREEN_MAX_COLS = 600;
+
+/**
+ * Rebuild the visible terminal screen from raw TUI output. The login CLI's
+ * renderer diffs frames: a repainted line SKIPS cells that already show the
+ * right character and jumps the cursor over them. The minted token paints
+ * over the "Paste code here if prompted >" prompt, whose `code` leaves an
+ * 'o' exactly where `sk-ant-oat01-`'s 'o' lands — so the byte stream carries
+ * `sk-ant-` ESC[10G `at01-…` and NEVER the contiguous token (live
+ * 2026-08-21, first Linux host; the Air's earlier "corrupted" capture was
+ * the same hole, not stderr interleave). Only a spatial reconstruction sees
+ * what the operator sees, so the credential scan reads this rendering, never
+ * the raw stream. Cells no frame painted stay spaces — a hole can only be
+ * filled by content some frame actually painted there, never closed up.
+ */
+export function renderTerminalScreenText(value: string): string {
+  const rows: (string[] | undefined)[] = [];
+  let row = 0;
+  let col = 0;
+  let savedRow = 0;
+  let savedCol = 0;
+  const clamp = () => {
+    row = Math.min(Math.max(row, 0), SCREEN_MAX_ROWS - 1);
+    col = Math.min(Math.max(col, 0), SCREEN_MAX_COLS);
+  };
+  const line = (): string[] => (rows[row] ??= []);
+  const pattern =
+    // OSC | CSI(params, final) | charset | bare ESC final | CR | LF | text
+    /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b\[([0-9;:?<=>]*)[!-/]*([@-~])|\x1b[()][0-9A-B]|\x1b([78=>DEHM])|(\r)|(\n)|([^\x1b\r\n\x00-\x1f\x7f]+)|[\s\S]/g;
+  for (const part of value.matchAll(pattern)) {
+    const [, csiParams, csiFinal, escFinal, cr, lf, text] = part;
+    if (text !== undefined) {
+      const cells = line();
+      for (const ch of text) {
+        if (col < SCREEN_MAX_COLS) cells[col] = ch;
+        col += 1;
+      }
+      clamp();
+      continue;
+    }
+    if (cr !== undefined) {
+      col = 0;
+      continue;
+    }
+    if (lf !== undefined) {
+      row += 1;
+      clamp();
+      continue;
+    }
+    if (escFinal !== undefined) {
+      if (escFinal === "7") [savedRow, savedCol] = [row, col];
+      else if (escFinal === "8") [row, col] = [savedRow, savedCol];
+      else if (escFinal === "D" || escFinal === "E") row += 1;
+      else if (escFinal === "M") row -= 1;
+      if (escFinal === "E") col = 0;
+      clamp();
+      continue;
+    }
+    if (csiFinal === undefined) continue;
+    const params = csiParams ?? "";
+    // Private-parameter sequences (kitty keyboard pops, DEC modes) are not
+    // cursor movement — never let e.g. `ESC[<u` restore a stale cursor.
+    if (/[?<=>]/.test(params)) continue;
+    const numbers = params.split(";").map((entry) => Number.parseInt(entry, 10));
+    const n = (index: number, fallback: number): number => {
+      const parsed = numbers[index];
+      return Number.isFinite(parsed) && parsed! > 0 ? parsed! : fallback;
+    };
+    switch (csiFinal) {
+      case "G":
+        col = n(0, 1) - 1;
+        break;
+      case "A":
+        row -= n(0, 1);
+        break;
+      case "B":
+        row += n(0, 1);
+        break;
+      case "C":
+        col += n(0, 1);
+        break;
+      case "D":
+        col -= n(0, 1);
+        break;
+      case "E":
+        row += n(0, 1);
+        col = 0;
+        break;
+      case "F":
+        row -= n(0, 1);
+        col = 0;
+        break;
+      case "d":
+        row = n(0, 1) - 1;
+        break;
+      case "H":
+      case "f":
+        row = n(0, 1) - 1;
+        col = n(1, 1) - 1;
+        break;
+      case "s":
+        [savedRow, savedCol] = [row, col];
+        break;
+      case "u":
+        [row, col] = [savedRow, savedCol];
+        break;
+      case "K": {
+        const cells = line();
+        const mode = Number.isFinite(numbers[0]) ? numbers[0]! : 0;
+        if (mode === 0) cells.length = Math.min(cells.length, col);
+        else if (mode === 1) {
+          for (let i = 0; i <= col && i < cells.length; i += 1) cells[i] = " ";
+        } else if (mode === 2) cells.length = 0;
+        break;
+      }
+      case "J": {
+        const mode = Number.isFinite(numbers[0]) ? numbers[0]! : 0;
+        if (mode === 0) {
+          line().length = Math.min(line().length, col);
+          rows.length = Math.min(rows.length, row + 1);
+        } else if (mode === 1) {
+          for (let i = 0; i < row; i += 1) rows[i] = undefined;
+          const cells = line();
+          for (let i = 0; i <= col && i < cells.length; i += 1) cells[i] = " ";
+        } else {
+          rows.length = 0;
+        }
+        break;
+      }
+      default:
+        break;
+    }
+    clamp();
+  }
+  return rows
+    .map((cells) => Array.from(cells ?? [], (cell) => cell ?? " ").join(""))
+    .join("\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;
+}
+
+/**
+ * Codex `--device-auth` banner: a verification URL plus a short one-time
+ * code ("AC57-MDV9G" shape). Both the phrase gate and the code shape are
+ * required so container names, hashes, or URL fragments cannot fake a
+ * device prompt. Reads the merged tail — codex prints to stderr.
+ */
+export function findCodexDeviceAuthorization(
+  value: string,
+): { verificationUrl: string; userCode: string } | null {
+  const plain = stripTerminalControl(value);
+  if (!/one-time code|device code/i.test(plain)) return null;
+  const verificationUrl = findSafeHttpsUrl(plain);
+  if (!verificationUrl) return null;
+  const code = /(?:^|\s)([A-Z0-9]{4,8}-[A-Z0-9]{4,10})(?:\s|$)/m.exec(plain);
+  if (!code) return null;
+  return { verificationUrl, userCode: code[1]! };
+}
+
+/**
+ * Grok `login --device-auth` banner (host 0.9.105): "To sign in, open this
+ * URL in your browser: https://accounts.x.ai/oauth2/device?user_code=XXXX-XXXX
+ * … Confirm this code in your browser: XXXX-XXXX". Phrase gate + code shape,
+ * same posture as the codex parser; grok prints to stderr.
+ */
+export function findGrokDeviceAuthorization(
+  value: string,
+): { verificationUrl: string; userCode: string } | null {
+  const plain = stripTerminalControl(value);
+  if (!/confirm this code|open this url/i.test(plain)) return null;
+  const verificationUrl = findSafeHttpsUrl(plain);
+  if (!verificationUrl) return null;
+  const code =
+    /user_code=([A-Z0-9]{4,8}-[A-Z0-9]{4,10})\b/.exec(plain) ??
+    /(?:^|\s)([A-Z0-9]{4,8}-[A-Z0-9]{4,10})(?:\s|$)/m.exec(plain);
+  if (!code) return null;
+  return { verificationUrl, userCode: code[1]! };
+}
+
+export function extractClaudeOAuthToken(value: string): string | null {
+  const plain = stripTerminalControl(value);
+  // The FULL `sk-ant-oat01-` prefix and a realistic minimum length are both
+  // load-bearing: the TUI's diff renderer skips screen cells that already
+  // hold the right character, so naive control-stripping glues the runs into
+  // `sk-ant-at01-…` — one character short, token-shaped, wrong — which a
+  // permissive scan once persisted as a "successful" login whose agents then
+  // 401'd forever (live 2026-08-21). The strict prefix makes any mangled
+  // capture a non-match; the actual token match happens against the
+  // reconstructed screen (renderTerminalScreenText), where it is contiguous.
+  const match =
+    /(?:^|[^A-Za-z0-9_-])(sk-ant-oat01-[A-Za-z0-9_-]{64,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();
+}
+
+const LOGS_FOLLOW_ATTEMPTS = 20;
+const LOGS_FOLLOW_RETRY_MS = 200;
+const LOGS_FOLLOW_ATTACH_PROBE_MS = 500;
+
+function delayMs(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    unrefTimer(timer);
+  });
+}
+
+/**
+ * Stream a login container's output via `docker logs --follow`, which
+ * replays from byte zero — immune to the run/attach race that loses the
+ * container's first burst (see startLoginContainer). The container may not
+ * exist yet when the first attempt fires, and the client's own
+ * "No such container" stderr must never leak into the operation's output
+ * tail, so each attempt buffers until it is provably attached: container
+ * stdout, or survival past a probe window, count as proof; a quick exit
+ * with the not-found error is a retry.
+ */
+async function followLoginContainerLogs(
+  containerName: string,
+  runChild: { once(event: "close", listener: () => void): unknown },
+  onOutput: (chunk: string, stream?: "stdout" | "stderr") => void,
+): Promise<void> {
+  let runClosed = false;
+  runChild.once("close", () => {
+    runClosed = true;
+  });
+  for (let attempt = 0; attempt < LOGS_FOLLOW_ATTEMPTS; attempt += 1) {
+    const outcome = await followLoginContainerLogsOnce(
+      containerName,
+      onOutput,
+    );
+    if (outcome === "done") return;
+    // The container is absent. Before it ever starts that means "retry";
+    // after the run child closed it means the container already exited and
+    // was removed — nothing will ever appear.
+    if (runClosed) return;
+    await delayMs(LOGS_FOLLOW_RETRY_MS);
+  }
+}
+
+function followLoginContainerLogsOnce(
+  containerName: string,
+  onOutput: (chunk: string, stream?: "stdout" | "stderr") => void,
+): Promise<"done" | "absent"> {
+  return new Promise((resolve) => {
+    const follower = spawn(
+      engineLoginBackend().command,
+      ["logs", "--follow", containerName],
+      { shell: false, stdio: ["ignore", "pipe", "pipe"] },
+    );
+    follower.stdout.setEncoding("utf8");
+    follower.stderr.setEncoding("utf8");
+    const buffered: Array<{ chunk: string; stream: "stdout" | "stderr" }> = [];
+    let stderrTail = "";
+    let attached = false;
+    const flush = (): void => {
+      attached = true;
+      for (const entry of buffered) onOutput(entry.chunk, entry.stream);
+      buffered.length = 0;
+    };
+    const deliver = (chunk: string, stream: "stdout" | "stderr"): void => {
+      if (attached) {
+        onOutput(chunk, stream);
+        return;
+      }
+      buffered.push({ chunk, stream });
+      if (buffered.length > 256) buffered.shift();
+    };
+    follower.stdout.on("data", (chunk: string) => {
+      // Container stdout is proof of attachment — the docker client itself
+      // never writes to stdout here.
+      if (!attached) flush();
+      onOutput(chunk, "stdout");
+    });
+    follower.stderr.on("data", (chunk: string) => {
+      stderrTail = appendUtf8Tail(stderrTail, chunk, 4_096);
+      deliver(chunk, "stderr");
+    });
+    const probe = setTimeout(() => {
+      // Still running after the probe window: the client accepted the
+      // container and is following; anything buffered is container stderr.
+      if (follower.exitCode === null) flush();
+    }, LOGS_FOLLOW_ATTACH_PROBE_MS);
+    unrefTimer(probe);
+    follower.once("error", () => {
+      clearTimeout(probe);
+      resolve("absent");
+    });
+    follower.once("close", () => {
+      clearTimeout(probe);
+      if (
+        !attached &&
+        /no such container|dead or marked for removal/i.test(stderrTail)
+      ) {
+        resolve("absent");
+        return;
+      }
+      // A real follow that ended (container exited): deliver whatever was
+      // buffered — a fast-crashing container's stderr arrives exactly here.
+      if (!attached) flush();
+      resolve("done");
+    });
+  });
+}
+
+/** Exported for the follower-path tests and live harnesses. */
+export async function startLoginContainer(
+  request: EngineLoginContainerRequest,
+  onOutput: (chunk: string, stream?: "stdout" | "stderr") => void,
+): Promise<EngineLoginProcess> {
+  const apple = engineLoginBackend().apple;
+  const args = engineLoginContainerArgs(request);
+  const child = spawn(engineLoginBackend().command, args, {
+    shell: false,
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+  child.stdout.setEncoding("utf8");
+  child.stderr.setEncoding("utf8");
+  if (apple) {
+    // The Apple CLI keeps the attach-stdio path: its behavior differs from
+    // Docker's and the claude flow's continuous TUI repaint has proven it
+    // live; the transcript fallback covers its noise-corruption cases.
+    child.stdout.on("data", (chunk: string) => onOutput(chunk, "stdout"));
+    child.stderr.on("data", (chunk: string) => onOutput(chunk, "stderr"));
+  } else {
+    // Docker: the attached stream can MISS the container's first output
+    // burst — `docker run` starts the container and the attach stream races
+    // its earliest writes. codex login prints its authorize URL within
+    // milliseconds and then goes silent, so a lost burst is a dead login
+    // (live 2026-08-21 on the first Linux hosts: dockerd had the URL,
+    // `docker logs` showed it, the attached client never relayed a byte).
+    // Output truth therefore comes from `docker logs --follow`, which
+    // replays from byte zero; the run child keeps ONLY stdin and lifecycle.
+    // Its stdio still drains so the client can never block on backpressure.
+    child.stdout.on("data", () => {});
+    child.stderr.on("data", () => {});
+    const logsDone = followLoginContainerLogs(
+      request.containerName,
+      child,
+      onOutput,
+    );
+    // Without `--rm`, the exited container outlives the run child so the
+    // follower can finish its replay; remove it once the follower is done
+    // (bounded — a wedged follower must not leak containers).
+    child.once("close", () => {
+      void (async () => {
+        await Promise.race([logsDone, delayMs(2_000)]);
+        await removeEngineLoginContainer(request.containerName).catch(
+          () => undefined,
+        );
+      })();
+    });
+  }
+  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",
+          // A wide PTY first: `script` allocates 80×24 when stdin is no
+          // terminal, the CLI hard-wraps the OAuth URL at that width, and
+          // the streamed capture then sees only the first fragment — the
+          // operator lands on claude.ai with "Missing redirect_uri" and half
+          // a client id (live 2026-08-18). stty targets the PTY `script`
+          // just allocated.
+          "stty cols 500 rows 50 2>/dev/null; exec claude setup-token",
+          // The PTY transcript lands in the op's private bind leaf (same
+          // trust class as the codex auth.json captured there; the leaf is
+          // 0700 and deleted at cleanup). A stuck flow can then be read
+          // VERBATIM from the host — the 2026-08-20 hang was undiagnosable
+          // because the typescript went to /dev/null.
+          `${LOGIN_MOUNT}/typescript`,
+        ]
+      : request.engine === "grok"
+        ? ["sh", "-c", GROK_LOGIN_SHELL]
+        : // Device-code flow: no localhost callback, no paste — the CLI prints
+        // a verification URL + one-time code, the operator confirms on the
+        // provider's page, and the CLI polls to completion (ADR-116 v2,
+        // 2026-08-24). The callback machinery below stays as the fallback
+        // for CLIs that still print the localhost authorize URL.
+        ["codex", "login", "--device-auth"];
+  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",
+      `GROK_HOME=${GROK_HOME}`,
+      "--env",
+      "ASDF_CONFIG_FILE=/dev/null",
+      "--env",
+      "ASDF_DEFAULT_TOOL_VERSIONS_FILENAME=.tool-versions",
+      STANDARD_IMAGE_TAG,
+      ...command,
+    ];
+  }
+  // No `--rm` in the Docker dialect: output truth comes from
+  // `docker logs --follow` (see startLoginContainer), and an auto-removed
+  // fast-exiting container would take its logs with it. The host removes
+  // the container explicitly when the run child closes; the labeled stale
+  // reconcile sweeps anything a crash leaves behind.
+  return [
+    "run",
+    "--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",
+    `GROK_HOME=${GROK_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",
+      // Follow the callback's redirect to the CLI's /success page: codex
+      // writes auth.json on the callback but EXITS only after serving that
+      // page — a real browser follows; a replay that stops at the redirect
+      // leaves a completed login waiting forever (live 2026-08-24: the
+      // first-ever completed pane codex login needed a manual /success
+      // fetch to let the CLI exit).
+      "--location",
+      "--max-time",
+      "10",
+      "--output",
+      "/dev/null",
+      "--config",
+      "-",
+    ],
+    input: `url = "${configUrl}"\n`,
+  };
+}
+
+const ENGINE_LOGIN_CONTAINER_NAME = new RegExp(
+  `^uai-login-(?:${ENGINE_LOGIN_KINDS.join("|")})-[0-9a-f]{16}$`,
+);
+
+/** `uai-login-<kind>-<16 hex>` for every login kind. The sweep, the log
+ *  follower, the remover, and the codex callback replay all gate on this, so
+ *  a kind missing here strands its containers AND blocks every later login. */
+export function isEngineLoginContainerName(value: string): boolean {
+  return ENGINE_LOGIN_CONTAINER_NAME.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;
+    // The container is told HOME and CODEX_HOME live under the leaf, and
+    // codex refuses to start when CODEX_HOME does not exist (claude
+    // self-creates its HOME). Create both up front.
+    await mkdir(join(path, "home"), { mode: 0o700 });
+    await mkdir(join(path, "codex"), { mode: 0o700 });
+    await mkdir(join(path, "grok"), { mode: 0o700 });
+    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();
+  }
+}