@moondeck/station 0.0.0-stage → 1.0.0

package/lib/agents/codex.ts

@@ -0,0 +1,1392 @@
+/**
+ * CodexSession — a real AgentSession backed by `codex app-server`, run
+ * inside the task environment (ADR-010):
+ *
+ *   codex app-server
+ *
+ * JSON-RPC 2.0 over stdio, newline-delimited. The protocol below is
+ * verified against `codex app-server generate-json-schema` (the
+ * generated schema, not guesswork).
+ *
+ * Lifecycle:
+ *   initialize        (request)      → server result
+ *   initialized       (notification) → sent by us
+ *   thread/start      (request)      → result `{ thread: { id, … } }`
+ *   turn/start        (request)      → output streams as notifications;
+ *                                      response/activity acknowledges acceptance
+ *
+ * Streaming notifications consumed (`mapCodexNotification`):
+ *   item/agentMessage/delta        → message_delta
+ *   item/completed (agentMessage)  → message_complete
+ *   item/completed (tool item)     → tool_call
+ *   thread/tokenUsage/updated      → accumulated for its turn
+ *   turn/completed                 → turn_complete (+ error if failed)
+ *   error                          → error
+ *
+ * The thread runs with `approvalPolicy: "never"` and
+ * `sandbox: "danger-full-access"` — the task container is the isolation
+ * boundary (ADR-011), and codex's bubblewrap sandbox can't create user
+ * namespaces inside it anyway.
+ */
+
+import { connectionFailureReason, tomlString } from "../custom-connection-launch";
+import { connectionFailureDetail } from "../custom-connection-runtime";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { and, eq, isNull } from "drizzle-orm";
+
+import { getDb, schema } from "../db";
+import { requireContainerRuntimeOperational } from "../runtime-guard";
+import type { TaskEnvironmentAgentSessionSurface } from "../task-environment/types";
+import { newId } from "../ulid";
+import { agentErrorMessage, reportAgentError } from "../agent-errors";
+import { attachCompatibilityKeysMatch } from "./attach-compatibility";
+import { createAgentTransport, type LineTransport } from "./transport";
+import { rateLimitErrorUsage, resetSecondsToEpochMs } from "./rate-limit";
+import { register } from "./registry";
+import { CODEX_MODELS } from "../../src/engine-models";
+import type {
+  AgentEvent,
+  AgentAccountUsage,
+  AgentEventHandler,
+  AgentKind,
+  AgentSession,
+  AgentUsage,
+  RosterAgent,
+} from "./types";
+
+// The model list is host-agent/src/engine-models.ts (CODEX_MODELS).
+
+// gpt-6.1-sol is Codex's current workhorse coding model (the CLI default).
+// Update alongside CODEX_MODELS. When an agent's model is null the adapter
+// omits the override entirely and Codex uses the user's own configured
+// default.
+const CODEX_DEFAULT_MODEL = "gpt-6.1-sol";
+
+// Reasoning levels set via `-c model_reasoning_effort=<level>`. "xhigh" is
+// the picker's "Extra high"; gpt-5.6 added "max" and "ultra" (ultra =
+// maximum reasoning with automatic task delegation). UPDATE WHEN CODEX
+// CHANGES its reasoning levels.
+const CODEX_EFFORTS = ["low", "medium", "high", "xhigh", "max", "ultra"];
+
+// medium stays OUR default (the 5.6 CLI defaults to low — too light for
+// agentic task work). Update alongside CODEX_EFFORTS.
+const CODEX_DEFAULT_EFFORT = "medium";
+
+/** Account headroom bands are product policy, not protocol magic numbers. */
+export const CODEX_USAGE_WARNING_PERCENT = 90;
+export const CODEX_USAGE_LIMITED_PERCENT = 100;
+export const CODEX_USAGE_POLL_INTERVAL_MS = 5 * 60_000;
+/** Only bounds acceptance, never the duration of an acknowledged turn. A
+ * minute allows cold starts/network setup while bounding false working state.
+ * Queued starts wait for accepted work to finish before this clock runs. */
+export const CODEX_TURN_START_TIMEOUT_MS = 60_000;
+
+// ---------------------------------------------------------------------------
+// Pure protocol mapping — JSON-RPC notification → AgentEvent[].
+// ---------------------------------------------------------------------------
+
+function isObj(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null;
+}
+
+function str(v: unknown, fallback = ""): string {
+  return typeof v === "string" ? v : fallback;
+}
+
+function nonNegativeInt(v: unknown): number | undefined {
+  return typeof v === "number" &&
+    Number.isSafeInteger(v) &&
+    v >= 0
+    ? v
+    : undefined;
+}
+
+interface CodexTokenBreakdown {
+  inputTokens: number;
+  outputTokens: number;
+  cachedInputTokens: number;
+}
+
+function codexTokenBreakdown(value: unknown): CodexTokenBreakdown | null {
+  if (!isObj(value)) return null;
+  const inputTokens = nonNegativeInt(value.inputTokens);
+  const outputTokens = nonNegativeInt(value.outputTokens);
+  const cachedInputTokens = nonNegativeInt(value.cachedInputTokens);
+  if (
+    inputTokens === undefined ||
+    outputTokens === undefined ||
+    cachedInputTokens === undefined ||
+    cachedInputTokens > inputTokens
+  ) {
+    return null;
+  }
+  return {
+    inputTokens,
+    outputTokens,
+    cachedInputTokens,
+  };
+}
+
+function addBreakdowns(
+  left: CodexTokenBreakdown | undefined,
+  right: CodexTokenBreakdown,
+): CodexTokenBreakdown | null {
+  return codexTokenBreakdown({
+    inputTokens: (left?.inputTokens ?? 0) + right.inputTokens,
+    outputTokens: (left?.outputTokens ?? 0) + right.outputTokens,
+    cachedInputTokens:
+      (left?.cachedInputTokens ?? 0) + right.cachedInputTokens,
+  });
+}
+
+function breakdownDelta(
+  current: CodexTokenBreakdown,
+  previous: CodexTokenBreakdown,
+): CodexTokenBreakdown | null {
+  const delta = {
+    inputTokens: current.inputTokens - previous.inputTokens,
+    outputTokens: current.outputTokens - previous.outputTokens,
+    cachedInputTokens:
+      current.cachedInputTokens - previous.cachedInputTokens,
+  };
+  return codexTokenBreakdown(delta);
+}
+
+/** Codex fills the context meter with zero charge counters when a request
+ * reaches its context limit (TokenUsageInfo.fill_to_context_window). This
+ * explicit marker resets the thread baseline without adding a model call. */
+function contextWindowUsageReset(
+  value: Record<string, unknown>,
+  last: CodexTokenBreakdown,
+  total: CodexTokenBreakdown,
+): boolean {
+  if (
+    Object.values(last).some((count) => count !== 0) ||
+    Object.values(total).some((count) => count !== 0)
+  ) return false;
+  const window = nonNegativeInt(value.modelContextWindow);
+  const totalTokens = isObj(value.total) ? nonNegativeInt(value.total.totalTokens) : undefined;
+  const lastTokens = isObj(value.last) ? nonNegativeInt(value.last.totalTokens) : undefined;
+  return window !== undefined && window > 0 && totalTokens === window && lastTokens !== undefined && lastTokens <= window;
+}
+
+/**
+ * Codex 0.157 emits one token update after every model call. `last` is that
+ * call, not the whole turn; `total` is the running thread total. A tool-using
+ * turn therefore emits several updates. Seed an unseen thread from `last`,
+ * then add positive `total` deltas so repeated snapshots add zero. Usage is
+ * kept by turn id and consumed exactly once at its turn/completed boundary.
+ */
+class CodexTurnUsage {
+  private readonly threadTotals = new Map<string, CodexTokenBreakdown>();
+  private readonly turns = new Map<string, CodexTokenBreakdown>();
+  private readonly unknownTurns = new Set<string>();
+
+  private unknown(threadId: string, turnId: string): void {
+    this.unknownTurns.add(turnId);
+    this.turns.delete(turnId);
+    // Its next first call must seed from `last`, never charge unknown history
+    // from a stale total that accompanied an invalid snapshot.
+    this.threadTotals.delete(threadId);
+  }
+
+  observe(params: unknown): void {
+    if (!isObj(params)) return;
+    const threadId = str(params.threadId);
+    const turnId = str(params.turnId);
+    const tokenUsage = isObj(params.tokenUsage) ? params.tokenUsage : null;
+    if (!threadId || !turnId) return;
+    if (!tokenUsage) {
+      this.unknown(threadId, turnId);
+      return;
+    }
+    const last = codexTokenBreakdown(tokenUsage.last);
+    const total = codexTokenBreakdown(tokenUsage.total);
+    if (!last || !total) {
+      this.unknown(threadId, turnId);
+      return;
+    }
+
+    const previousTotal = this.threadTotals.get(threadId);
+    const contribution = previousTotal && !contextWindowUsageReset(tokenUsage, last, total)
+      ? breakdownDelta(total, previousTotal)
+      : last;
+    if (!contribution) {
+      // A decreasing total or impossible cache delta cannot safely be
+      // repaired by adding `last`: it may replay an already counted call.
+      this.unknown(threadId, turnId);
+      return;
+    }
+    this.threadTotals.set(threadId, total);
+    if (this.unknownTurns.has(turnId)) return;
+    const accumulated = addBreakdowns(this.turns.get(turnId), contribution);
+    if (!accumulated) {
+      this.unknown(threadId, turnId);
+      return;
+    }
+    this.turns.set(turnId, accumulated);
+  }
+
+  complete(params: unknown, model: string | undefined): AgentUsage | undefined {
+    const p = isObj(params) ? params : {};
+    const turn = isObj(p.turn) ? p.turn : {};
+    const turnId = str(turn.id);
+    if (!turnId) return undefined;
+    const usage = this.turns.get(turnId);
+    this.turns.delete(turnId);
+    if (this.unknownTurns.delete(turnId) || !usage) return undefined;
+    return {
+      ...(model ? { model } : {}),
+      // OpenAI includes cached input inside inputTokens. Uai's shared shape,
+      // like Claude's, keeps fresh input and cache reads in separate columns.
+      // Source: openai/codex rust-v0.157.0, TokenUsage.non_cached_input and
+      // ResponseCompletedUsage -> TokenUsage. Cache writes are also input,
+      // but without their TTL/rate breakdown this is not an exact bill.
+      // Leave writes in fresh input rather than also reporting a cache create.
+      inputTokens: usage.inputTokens - usage.cachedInputTokens,
+      cacheReadTokens: usage.cachedInputTokens,
+      // reasoningOutputTokens is a subset of outputTokens in this protocol
+      // (totalTokens = inputTokens + outputTokens), so do not add it again.
+      outputTokens: usage.outputTokens,
+    };
+  }
+}
+
+/** `item/completed` item types rendered as tool-call cards. */
+const TOOL_ITEM_TYPES = new Set([
+  "commandExecution",
+  "fileChange",
+  "mcpToolCall",
+  "dynamicToolCall",
+  "webSearch",
+]);
+
+function turnComplete(usage: AgentUsage | undefined): AgentEvent {
+  return usage ? { type: "turn_complete", usage } : { type: "turn_complete" };
+}
+
+/**
+ * Map one Codex JSON-RPC *notification* (method + params) to AgentEvents.
+ * Pure and total — an unrecognised method yields [].
+ */
+export function mapCodexNotification(
+  method: string,
+  params: unknown,
+  now: number = Date.now(),
+  turnUsage?: AgentUsage,
+): AgentEvent[] {
+  const p = isObj(params) ? params : {};
+
+  if (method === "account/rateLimits/updated") {
+    const usage = mapCodexRateLimits(p.rateLimits, now);
+    return usage ? [{ type: "account_usage", usage }] : [];
+  }
+
+  if (method === "item/agentMessage/delta") {
+    const text = str(p.delta);
+    return text ? [{ type: "message_delta", text }] : [];
+  }
+
+  if (method === "item/completed" && isObj(p.item)) {
+    const item = p.item;
+    const itemType = str(item.type);
+    if (itemType === "agentMessage") {
+      return [{ type: "message_complete", text: str(item.text) }];
+    }
+    if (TOOL_ITEM_TYPES.has(itemType)) {
+      return [
+        {
+          type: "tool_call",
+          id: str(item.id) || newId(),
+          title: codexToolTitle(itemType, item),
+          detail: codexToolDetail(item),
+        },
+      ];
+    }
+    return [];
+  }
+
+  if (method === "turn/completed") {
+    const turn = isObj(p.turn) ? p.turn : {};
+    if (turn.status === "failed" && isObj(turn.error)) {
+      const message = str(turn.error.message, "codex turn failed");
+      const accountUsage = rateLimitErrorUsage(message, now);
+      return [
+        ...(accountUsage
+          ? [{ type: "account_usage", usage: accountUsage } as const]
+          : []),
+        accountUsage
+          ? {
+              type: "error",
+              message,
+              retryable: "rate_limit",
+              ...(accountUsage.resetsAt === undefined
+                ? {}
+                : { resetsAt: accountUsage.resetsAt }),
+            }
+          : { type: "error", message },
+        turnComplete(turnUsage),
+      ];
+    }
+    return [turnComplete(turnUsage)];
+  }
+
+  if (method === "error") {
+    const message = isObj(p.error)
+      ? str(p.error.message, "codex error")
+      : "codex error";
+    const accountUsage = rateLimitErrorUsage(message, now);
+    return accountUsage
+      ? [
+          { type: "account_usage", usage: accountUsage },
+          {
+            type: "error",
+            message,
+            retryable: "rate_limit",
+            ...(accountUsage.resetsAt === undefined
+              ? {}
+              : { resetsAt: accountUsage.resetsAt }),
+          },
+        ]
+      : [{ type: "error", message }];
+  }
+
+  return [];
+}
+
+function codexWindow(
+  name: "primary" | "secondary",
+  value: unknown,
+  observedAt: number,
+): AgentAccountUsage["windows"][number] | null {
+  if (!isObj(value) || typeof value.usedPercent !== "number") return null;
+  const usedPercent = Math.min(100, Math.max(0, value.usedPercent));
+  if (!Number.isFinite(usedPercent)) return null;
+  const windowMinutes =
+    typeof value.windowDurationMins === "number" &&
+    Number.isSafeInteger(value.windowDurationMins) &&
+    value.windowDurationMins > 0
+      ? value.windowDurationMins
+      : undefined;
+  // The 0.157 schema says int64; the live app-server read confirms seconds.
+  const resetsAt = resetSecondsToEpochMs(value.resetsAt, observedAt);
+  return {
+    window: name,
+    ...(windowMinutes === undefined ? {} : { windowMinutes }),
+    usedPercent,
+    ...(resetsAt === undefined ? {} : { resetsAt }),
+  };
+}
+
+/** Map the shared RateLimitSnapshot used by the read response and update
+ * notification in Codex app-server 0.157. */
+export function mapCodexRateLimits(
+  value: unknown,
+  observedAt: number = Date.now(),
+): AgentAccountUsage | null {
+  if (!isObj(value)) return null;
+  const windows = (["primary", "secondary"] as const)
+    .map((name) => codexWindow(name, value[name], observedAt))
+    .filter((window): window is NonNullable<typeof window> => window !== null);
+  if (windows.length === 0) return null;
+  const limited = windows.filter(
+    (window) =>
+      (window.usedPercent ?? 0) >= CODEX_USAGE_LIMITED_PERCENT,
+  );
+  const status =
+    limited.length > 0
+      ? "limited"
+      : windows.some(
+            (window) =>
+              (window.usedPercent ?? 0) >= CODEX_USAGE_WARNING_PERCENT,
+          )
+        ? "warning"
+        : "allowed";
+  const limitedResets = limited
+    .map((window) => window.resetsAt)
+    .filter((reset): reset is number => reset !== undefined);
+  const resetsAt =
+    limitedResets.length > 0 ? Math.max(...limitedResets) : undefined;
+  return {
+    status,
+    ...(resetsAt === undefined ? {} : { resetsAt }),
+    windows,
+    source: "codex-rate-limits",
+    observedAt,
+    coverage: { kind: "all-windows" },
+  };
+}
+
+function codexToolTitle(
+  itemType: string,
+  item: Record<string, unknown>,
+): string {
+  if (itemType === "commandExecution") {
+    const c = item.command;
+    const cmd = Array.isArray(c)
+      ? c.map((x) => String(x)).join(" ")
+      : str(c, "command");
+    return `$ ${cmd}`;
+  }
+  if (itemType === "fileChange") {
+    const n = Array.isArray(item.changes) ? item.changes.length : 0;
+    return `Edit ${n} file${n === 1 ? "" : "s"}`;
+  }
+  if (itemType === "mcpToolCall") {
+    return `MCP ${str(item.server)}/${str(item.tool)}`;
+  }
+  if (itemType === "dynamicToolCall") return `Tool ${str(item.tool)}`;
+  if (itemType === "webSearch") return `Search ${str(item.query)}`;
+  return itemType;
+}
+
+function codexToolDetail(item: Record<string, unknown>): string {
+  for (const key of ["aggregatedOutput", "result", "query"]) {
+    const v = item[key];
+    if (typeof v === "string" && v.length > 0) return v;
+  }
+  try {
+    return JSON.stringify(item, null, 2);
+  } catch {
+    return "";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// JSON-RPC framing.
+// ---------------------------------------------------------------------------
+
+/** Server→client requests we recognise as approval prompts. */
+const APPROVAL_METHODS = new Set([
+  "item/commandExecution/requestApproval",
+  "item/fileChange/requestApproval",
+  "item/permissions/requestApproval",
+  "applyPatchApproval",
+  "execCommandApproval",
+]);
+
+/** Bounds the handshake so a wrong-shape protocol surfaces as an error
+ *  rather than an endless "thinking…". `turn/start` is exempt — turns
+ *  can legitimately run for minutes. */
+const RPC_TIMEOUT_MS = 30_000;
+
+/**
+ * ADR-078 thread/resume lock retry. Right after a host restart the previous
+ * (durable, in-container) app-server may still hold the thread's rollout lock;
+ * `thread/resume` then fails with JSON-RPC -32600 until the stop we sent the old
+ * runner lands. Retry that specific error a bounded number of times.
+ */
+const RESUME_LOCK_ATTEMPTS = 10;
+const RESUME_LOCK_BACKOFF_MS = 1_000;
+
+const delay = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
+// ---------------------------------------------------------------------------
+// Thread persistence (ADR-078) — resume the SAME thread across a host restart.
+// ---------------------------------------------------------------------------
+
+/** The compatible Codex thread id persisted for (task, agent), or null. */
+function readCodexThreadId(
+  taskId: string,
+  agentId: string,
+  attachCompatibilityKey: string | undefined,
+): string | null {
+  try {
+    const row = getDb()
+      .select({
+        id: schema.hostAgentSessions.codexThreadId,
+        kind: schema.hostAgentSessions.kind,
+        sessionDir: schema.hostAgentSessions.sessionDir,
+        attachCompatibilityKey:
+          schema.hostAgentSessions.attachCompatibilityKey,
+      })
+      .from(schema.hostAgentSessions)
+      .where(
+        and(
+          eq(schema.hostAgentSessions.taskId, taskId),
+          eq(schema.hostAgentSessions.agentId, agentId),
+        ),
+      )
+      .get();
+    if (
+      row?.kind !== "codex" ||
+      !attachCompatibilityKeysMatch(
+        row.attachCompatibilityKey,
+        attachCompatibilityKey,
+      )
+    ) {
+      // Transport will promote the row to the new launch key while preserving
+      // codexThreadId. Clear the incompatible id first so a crash between that
+      // upsert and thread/started cannot make the next host resume it.
+      if (row?.id && row.sessionDir) {
+        getDb()
+          .update(schema.hostAgentSessions)
+          .set({ codexThreadId: null, updatedAt: Date.now() })
+          .where(
+            and(
+              eq(schema.hostAgentSessions.taskId, taskId),
+              eq(schema.hostAgentSessions.agentId, agentId),
+              eq(schema.hostAgentSessions.sessionDir, row.sessionDir),
+            ),
+          )
+          .run();
+      }
+      return null;
+    }
+    return row?.id ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Persist the Codex thread id for (task, agent) so a later host process resumes
+ * it. Best-effort — a write failure just means the next restart starts a fresh
+ * thread (today's behavior). The transport's session-row upsert never clears
+ * this column, so it survives the kill+respawn of a host restart.
+ */
+function saveCodexThreadId(
+  taskId: string,
+  agentId: string,
+  threadId: string,
+  sessionDir: string | undefined,
+  attachCompatibilityKey: string | undefined,
+): void {
+  if (!sessionDir) return;
+  try {
+    const db = getDb();
+    const row = db
+      .select({
+        kind: schema.hostAgentSessions.kind,
+        sessionDir: schema.hostAgentSessions.sessionDir,
+        attachCompatibilityKey:
+          schema.hostAgentSessions.attachCompatibilityKey,
+      })
+      .from(schema.hostAgentSessions)
+      .where(
+        and(
+          eq(schema.hostAgentSessions.taskId, taskId),
+          eq(schema.hostAgentSessions.agentId, agentId),
+        ),
+      )
+      .get();
+    const persistedKey = row?.attachCompatibilityKey ?? null;
+    if (
+      row?.kind !== "codex" ||
+      row.sessionDir !== sessionDir ||
+      !attachCompatibilityKeysMatch(
+        row.attachCompatibilityKey,
+        attachCompatibilityKey,
+      )
+    ) {
+      return;
+    }
+    db
+      .update(schema.hostAgentSessions)
+      .set({ codexThreadId: threadId, updatedAt: Date.now() })
+      .where(
+        and(
+          eq(schema.hostAgentSessions.taskId, taskId),
+          eq(schema.hostAgentSessions.agentId, agentId),
+          eq(schema.hostAgentSessions.kind, "codex"),
+          eq(schema.hostAgentSessions.sessionDir, sessionDir),
+          persistedKey === null
+            ? isNull(schema.hostAgentSessions.attachCompatibilityKey)
+            : eq(
+                schema.hostAgentSessions.attachCompatibilityKey,
+                persistedKey,
+              ),
+        ),
+      )
+      .run();
+  } catch {
+    /* best effort — see doc comment */
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The session.
+// ---------------------------------------------------------------------------
+
+export class CodexSession implements AgentSession {
+  readonly agentId: string;
+  readonly kind: AgentKind = "codex";
+
+  private readonly proc: LineTransport;
+  private readonly handlers = new Set<AgentEventHandler>();
+  private readonly systemPreamble: string;
+  private readonly taskId: string;
+  private readonly customConnection: boolean;
+  /** The connection's key, only to scrub it out of an upstream excerpt. */
+  private readonly connectionKey: string;
+  /** ADR-078: a thread id persisted by a PRIOR host process, to resume. */
+  private readonly resumeThreadId: string | null;
+  private closed = false;
+  private handshakeOk = false;
+
+  private nextRpcId = 1;
+  private readonly pending = new Map<
+    number,
+    { resolve: (v: unknown) => void; reject: (e: Error) => void }
+  >();
+  /** permission_request id → the JSON-RPC request id to answer with. */
+  private readonly approvals = new Map<string, number | string>();
+  /** Responses can follow notifications, so keep ids until completion. */
+  private readonly turnStarts = new Map<number, {
+    timer: ReturnType<typeof setTimeout> | null;
+    turnId: string | null;
+    accepted: boolean;
+    settles: number;
+  }>();
+  /** Merged request id → the canonical start, until its turn completes. */
+  private readonly mergedStarts = new Map<number, number>();
+  private readonly firedRequests = new Map<number, string>();
+  /** Live provider turns plus unacknowledged starts, excluding merged aliases. */
+  private outstandingTurns = 0;
+  private failed = false;
+  private cliVersion: string | null = null;
+
+  private threadId: string | null = null;
+  private readonly ready: Promise<void>;
+  private readonly attachCompatibilityKey: string | undefined;
+  private turnRunning = false;
+  private lastRateLimitsReadAt = 0;
+  private rateLimitsTimer: ReturnType<typeof setTimeout> | null = null;
+  private readonly turnUsage = new CodexTurnUsage();
+  private actualModel: string | undefined;
+
+  constructor(args: {
+    taskId: string;
+    agent: RosterAgent;
+    environment: TaskEnvironmentAgentSessionSurface;
+    systemPreamble: string;
+    agentEnv?: Record<string, string>;
+    attachCompatibilityKey?: string;
+    /** ADR-128: `-c key=value` overrides a delegating adapter prepends. */
+    cliConfigOverrides?: string[];
+    /** ADR-157: the Astronaut runs without Codex's native multi-agent tools. */
+    executionProfile?: "communicator" | "astronaut";
+  }) {
+    this.agentId = args.agent.id;
+    this.systemPreamble = args.systemPreamble;
+    this.taskId = args.taskId;
+    this.customConnection = args.agentEnv?.UAI_CUSTOM_CONNECTION === "1";
+    this.connectionKey = args.agentEnv?.UAI_CUSTOM_API_KEY ?? "";
+    this.attachCompatibilityKey = args.attachCompatibilityKey;
+    // ADR-078: read BEFORE createAgentTransport (whose session-row upsert
+    // preserves this column). Non-null → a host restart; resume the thread.
+    this.resumeThreadId = readCodexThreadId(
+      args.taskId,
+      args.agent.id,
+      args.attachCompatibilityKey,
+    );
+
+    // The agent's model / effort (when set) are selected via config overrides
+    // (`-c model=<model>`, `-c model_reasoning_effort=<effort>`) on the
+    // app-server process (ADR-021). All `-c` overrides go BEFORE the
+    // `app-server` subcommand. Without them codex uses its configured defaults.
+    const codexArgs: string[] = [];
+    if (args.agent.model) {
+      codexArgs.push("-c", `model=${tomlString(args.agent.model)}`);
+    }
+    if (args.agent.effort) {
+      codexArgs.push("-c", `model_reasoning_effort=${tomlString(args.agent.effort)}`);
+    }
+    for (const override of args.cliConfigOverrides ?? []) {
+      codexArgs.push("-c", override);
+    }
+    // These are two independent features in Codex 0.157. Append after every
+    // user override so task env can never be frozen into an on-disk snapshot.
+    codexArgs.push(
+      "--disable",
+      "shell_snapshot",
+      "--disable",
+      "shell_snapshot_v2",
+    );
+    // ADR-157: an Astronaut's helpers must be crew agents the task can see and
+    // bill, so Codex's own subagents (spawn_agent; multi_agent is on by
+    // default in 0.157, multi_agent_v2 off) are disabled for it. Also after
+    // every override, so nothing can turn them back on.
+    if (args.executionProfile === "astronaut") {
+      codexArgs.push("--disable", "multi_agent", "--disable", "multi_agent_v2");
+    }
+    codexArgs.push("app-server");
+    // ADR-061: the CLI is owned by an in-container runner (durable across
+    // host restarts); legacy pipes behind UAI_DURABLE_SESSIONS=0. Codex
+    // re-handshakes per host process (initialize + thread/start live in this
+    // object), so a leftover runner is never attached — allowAttach:false
+    // stops it and spawns fresh. Its final output before the stop still
+    // reaches the cloud via the outbox.
+    this.proc = createAgentTransport({
+      taskId: args.taskId,
+      agentId: this.agentId,
+      environment: args.environment,
+      cli: "codex",
+      cliArgs: codexArgs,
+      passEnv: [],
+      explicitEnv: args.agentEnv ?? {},
+      allowAttach: false,
+      attachCompatibilityKey: args.attachCompatibilityKey,
+      kind: "codex",
+      debugLabel: `codex:${this.agentId}`,
+    });
+    this.proc.onLine((line) => this.onLine(line));
+    this.proc.onExit((code) => {
+      if (this.closed) return;
+      if (!this.failed && (code !== 0 || this.outstandingTurns > 0)) {
+        const tail = this.proc.stderrTail.trim();
+        this.failTurn(
+            (code === null ? `${this.cliLabel} process stopped unexpectedly` :
+              `${this.cliLabel} process exited (${code})${code === 0 ? " before replying to the message" : ""}`) +
+            (tail
+              ? `:\n${tail}`
+              : ". Please try again."),
+        );
+      }
+      this.clearTurnState();
+      this.closed = true;
+      for (const waiter of this.pending.values()) {
+        waiter.reject(new Error("codex process exited"));
+      }
+      this.pending.clear();
+      this.emit({ type: "exit", code: code ?? -1 });
+    });
+
+    this.ready = this.handshake().catch((err: unknown) => {
+      this.failTurn(`${this.cliLabel} could not start: ${
+          err instanceof Error ? err.message : String(err)
+        }`, (err as { rpcCode?: number }).rpcCode);
+    });
+  }
+
+  // -- JSON-RPC plumbing ----------------------------------------------------
+
+  private onLine(line: string): void {
+    // close() severs this generation before the durable runner necessarily
+    // exits. Ignore buffered notifications so a late thread/started cannot
+    // restore the resume id that a live roster edit just cleared.
+    if (this.closed || this.failed) return;
+    let msg: unknown;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      return;
+    }
+    if (!isObj(msg)) return;
+
+    const hasId = "id" in msg && (typeof msg.id === "number" || typeof msg.id === "string");
+
+    // Response to one of our requests (id, no method).
+    if (hasId && !("method" in msg)) {
+      const id = typeof msg.id === "number" ? msg.id : -1;
+      const fired = this.firedRequests.get(id);
+      this.firedRequests.delete(id);
+      if (this.turnStarts.has(id) || this.mergedStarts.has(id)) {
+        if (isObj(msg.error)) {
+          this.failRpc(msg.error);
+        } else {
+          this.acknowledgeTurn(id, msg.result);
+        }
+        return;
+      }
+      const waiter = this.pending.get(id);
+      if (waiter) {
+        this.pending.delete(id);
+        if (isObj(msg.error)) {
+          // Preserve the JSON-RPC code so thread/resume can retry -32600
+          // (the thread's single-writer lock still held by a dying app-server).
+          const code =
+            typeof msg.error.code === "number" ? msg.error.code : undefined;
+          waiter.reject(
+            Object.assign(new Error(str(msg.error.message, "rpc error")), {
+              rpcCode: code,
+            }),
+          );
+        } else {
+          waiter.resolve(msg.result);
+        }
+      } else if (fired === "turn/interrupt" && isObj(msg.error)) {
+        const code = typeof msg.error.code === "number" ? msg.error.code : undefined;
+        let message = `Couldn't stop the message: ${this.cliLabel}${code === undefined ? "" : ` (code ${code})`}: ${str(msg.error.message, "Unknown error. Please try again.")}`;
+        if (this.customConnection) message = connectionFailureReason(message);
+        this.reportError(message, code);
+        this.emit({ type: "notice", message: agentErrorMessage(message) });
+      }
+      return;
+    }
+
+    // Server→client request (id + method).
+    if (hasId && "method" in msg) {
+      this.onServerRequest(
+        msg.id as number | string,
+        str(msg.method),
+        msg.params,
+      );
+      return;
+    }
+
+    // Notification (method, no id).
+    if ("method" in msg) {
+      const method = str(msg.method);
+      // Account usage responses are not proof of a running turn. Turn/item
+      // activity (including an approval request below) is acceptance even on
+      // CLIs that defer the turn/start response until the turn ends.
+      if (method === "turn/started" || method.startsWith("item/") ||
+        method === "thread/tokenUsage/updated" || method === "turn/completed") {
+        this.acknowledgeActivity(msg.params, method === "turn/started");
+      }
+      if (method === "thread/tokenUsage/updated") {
+        this.turnUsage.observe(msg.params);
+      }
+      const completedUsage =
+        method === "turn/completed"
+          ? this.turnUsage.complete(msg.params, this.actualModel)
+          : undefined;
+      let settles = 1;
+      if (method === "turn/completed") {
+        if (isObj(msg.params) && isObj(msg.params.turn) &&
+          msg.params.turn.status === "failed" && isObj(msg.params.turn.error)) {
+          this.failRpc(msg.params.turn.error, completedUsage);
+          return;
+        }
+        this.outstandingTurns = Math.max(0, this.outstandingTurns - 1);
+        const turnId = this.notificationTurnId(msg.params);
+        const completed = [...this.turnStarts].find(([, turn]) => turnId !== null && turn.turnId === turnId)
+          ?? [...this.turnStarts].find(([, turn]) => turn.accepted);
+        if (completed) {
+          settles = completed[1].settles;
+          this.turnStarts.delete(completed[0]);
+          this.firedRequests.delete(completed[0]);
+          for (const [alias, owner] of this.mergedStarts) {
+            if (owner !== completed[0]) continue;
+            this.mergedStarts.delete(alias);
+            this.firedRequests.delete(alias);
+          }
+        }
+        this.turnRunning = this.outstandingTurns > 0;
+        if (!this.turnRunning) this.clearTurnState();
+        else this.reconcileAcceptanceTimers();
+      }
+      if (method === "error") {
+        const params = isObj(msg.params) ? msg.params : {};
+        this.failRpc(isObj(params.error) ? params.error : {});
+        return;
+      }
+      // The thread id arrives on `thread/started`; also captured from
+      // the `thread/start` response in handshake().
+      if (method === "thread/started" && isObj(msg.params)) {
+        const thread = msg.params.thread;
+        if (isObj(thread) && typeof thread.id === "string") {
+          this.threadId = thread.id;
+          this.persistThreadId(thread.id);
+          if (typeof thread.model === "string" && thread.model.length > 0) {
+            this.actualModel = thread.model;
+          }
+        }
+      }
+      for (const ev of mapCodexNotification(
+        method,
+        msg.params,
+        Date.now(),
+        completedUsage,
+      )) {
+        this.emit(ev.type === "turn_complete" ? {
+          ...ev,
+          ...(settles > 1 ? { settles } : {}),
+          ...(isObj(msg.params) && isObj(msg.params.turn) && msg.params.turn.status === "interrupted" ? { aborted: true } : {}),
+        } : ev);
+      }
+    }
+  }
+
+  private onServerRequest(
+    id: number | string,
+    method: string,
+    params: unknown,
+  ): void {
+    if (APPROVAL_METHODS.has(method)) {
+      this.acknowledgeActivity(params);
+      const permId = newId();
+      this.approvals.set(permId, id);
+      const p = isObj(params) ? params : {};
+      this.emit({
+        type: "permission_request",
+        id: permId,
+        title: method.includes("fileChange")
+          ? "Allow file changes?"
+          : `Allow: ${str(p.command, method)}`,
+        detail: codexToolDetail(p),
+      });
+      return;
+    }
+    // Anything else (tool calls, elicitation, token refresh) — we can't
+    // service it; reply with an error so codex doesn't block waiting.
+    this.respondError(id, `uai does not handle "${method}"`);
+  }
+
+  /** Send a JSON-RPC request, resolving with its result; rejects after
+   *  RPC_TIMEOUT_MS. For short calls (initialize, thread/start). */
+  private request(method: string, params: unknown): Promise<unknown> {
+    const id = this.nextRpcId++;
+    return new Promise<unknown>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        if (this.pending.delete(id)) {
+          reject(
+            new Error(
+              `codex did not answer "${method}" within ${
+                RPC_TIMEOUT_MS / 1000
+              }s`,
+            ),
+          );
+        }
+      }, RPC_TIMEOUT_MS);
+      this.pending.set(id, {
+        resolve: (v) => {
+          clearTimeout(timer);
+          resolve(v);
+        },
+        reject: (e) => {
+          clearTimeout(timer);
+          reject(e);
+        },
+      });
+      this.proc.writeLine({ jsonrpc: "2.0", id, method, params });
+    });
+  }
+
+  /** Send a JSON-RPC request without awaiting it — for `turn/start`,
+   *  whose output streams as notifications and whose response can take
+   *  minutes. Acceptance/errors are handled separately, without a waiter. */
+  private fireRequest(method: string, params: unknown): number {
+    const id = this.nextRpcId++;
+    this.firedRequests.set(id, method);
+    this.proc.writeLine({
+      jsonrpc: "2.0",
+      id,
+      method,
+      params,
+    });
+    return id;
+  }
+
+  private notify(method: string, params: unknown): void {
+    this.proc.writeLine({ jsonrpc: "2.0", method, params });
+  }
+
+  private respond(id: number | string, result: unknown): void {
+    this.proc.writeLine({ jsonrpc: "2.0", id, result });
+  }
+
+  private respondError(id: number | string, message: string): void {
+    this.proc.writeLine({
+      jsonrpc: "2.0",
+      id,
+      error: { code: -32601, message },
+    });
+  }
+
+  private async handshake(): Promise<void> {
+    const initialized = await this.request("initialize", {
+      clientInfo: { name: "uai", version: "0.2" },
+      // ADR-078: unlock experimental fields. thread/resume's `excludeTurns`
+      // (resume without replaying history — see tryResumeThread) is gated on
+      // this; without it the app-server rejects the field with
+      // "thread/resume.excludeTurns requires experimentalApi capability" and
+      // we fall back to a fresh thread, losing the whole conversation.
+      capabilities: { experimentalApi: true },
+    });
+    // The server's user agent starts with <client-name>/<CLI-version>; it
+    // does not use the clientInfo.version we sent (verified on codex 0.164).
+    if (isObj(initialized)) {
+      this.cliVersion = str(initialized.userAgent)
+        .match(/^[^/\s]+\/(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)(?:\s|$)/)?.[1] ?? null;
+    }
+    this.notify("initialized", {});
+    // ADR-078: a thread id from a prior host process means this is a restart —
+    // resume the SAME durable thread so the conversation survives, instead of
+    // starting fresh. Fall back to a new thread if resume isn't possible
+    // (thread gone/corrupt, or the old writer never released the lock).
+    if (this.resumeThreadId && (await this.tryResumeThread(this.resumeThreadId))) {
+      this.handshakeOk = true;
+      this.readRateLimits();
+      return;
+    }
+    await this.startThread();
+    this.handshakeOk = true;
+    this.readRateLimits();
+  }
+
+  /** Best-effort account snapshot. It is intentionally outside `ready`: a
+   * slow usage endpoint must not delay the agent's first turn. */
+  private readRateLimits(): void {
+    if (this.closed) return;
+    this.lastRateLimitsReadAt = Date.now();
+    void this.request("account/rateLimits/read", null)
+      .then((result) => {
+        const usage =
+          isObj(result) && "rateLimits" in result
+            ? mapCodexRateLimits(result.rateLimits)
+            : null;
+        if (usage) this.emit({ type: "account_usage", usage });
+      })
+      .catch((error: unknown) => {
+        // Usage is advisory. Authentication/turn errors still follow their
+        // normal app-server notifications and must not be duplicated here.
+        if (!this.closed && !this.failed) {
+          this.reportError(`${this.cliLabel} usage read failed: ${error instanceof Error ? error.message : String(error)}`,
+            (error as { rpcCode?: number }).rpcCode, false);
+        }
+      });
+  }
+
+  private clearRateLimitsTimer(): void {
+    if (this.rateLimitsTimer !== null) clearTimeout(this.rateLimitsTimer);
+    this.rateLimitsTimer = null;
+  }
+
+  private scheduleRateLimitsRead(): void {
+    this.clearRateLimitsTimer();
+    if (!this.turnRunning || this.closed) return;
+    const wait = Math.max(
+      0,
+      this.lastRateLimitsReadAt + CODEX_USAGE_POLL_INTERVAL_MS - Date.now(),
+    );
+    this.rateLimitsTimer = setTimeout(() => {
+      this.rateLimitsTimer = null;
+      if (!this.turnRunning || this.closed) return;
+      this.readRateLimits();
+      this.scheduleRateLimitsRead();
+    }, wait);
+    this.rateLimitsTimer.unref?.();
+  }
+
+  private async startThread(): Promise<void> {
+    // The uai channel briefing (how to @-mention, the roster, the project's
+    // defaultPrompt) goes in as developer instructions so it applies to every
+    // turn on the thread (persisted with the thread, so resume needn't resend).
+    const threadParams: Record<string, unknown> = {
+      approvalPolicy: "never",
+      sandbox: "danger-full-access",
+    };
+    if (this.systemPreamble.trim().length > 0) {
+      threadParams.developerInstructions = this.systemPreamble;
+    }
+    const result = await this.request("thread/start", threadParams);
+    if (isObj(result) && typeof result.model === "string") {
+      this.actualModel = result.model;
+    }
+    if (isObj(result) && isObj(result.thread)) {
+      const id = str(result.thread.id) || this.threadId;
+      if (!this.actualModel && typeof result.thread.model === "string") {
+        this.actualModel = result.thread.model;
+      }
+      this.threadId = id;
+      if (id) this.persistThreadId(id);
+    }
+  }
+
+  /**
+   * Reopen the persisted thread by id (ADR-078). `excludeTurns:true` returns
+   * only metadata — no history replay, which would double-post the transcript
+   * the cloud already holds. The app-server allows one writer per thread, so a
+   * -32600 (lock still held by the dying predecessor app-server) is retried with
+   * backoff; any other failure returns false and the caller starts a fresh
+   * thread. Returns true iff the thread is now open for turns.
+   */
+  private async tryResumeThread(threadId: string): Promise<boolean> {
+    for (let attempt = 0; attempt < RESUME_LOCK_ATTEMPTS; attempt++) {
+      try {
+        const result = await this.request("thread/resume", {
+          threadId,
+          excludeTurns: true,
+          approvalPolicy: "never",
+          sandbox: "danger-full-access",
+        });
+        const id =
+          isObj(result) && isObj(result.thread) && str(result.thread.id)
+            ? str(result.thread.id)
+            : threadId;
+        if (isObj(result) && typeof result.model === "string") {
+          this.actualModel = result.model;
+        } else if (
+          isObj(result) &&
+          isObj(result.thread) &&
+          typeof result.thread.model === "string"
+        ) {
+          this.actualModel = result.thread.model;
+        }
+        this.threadId = id;
+        this.persistThreadId(id);
+        return true;
+      } catch (err) {
+        const code = (err as { rpcCode?: number }).rpcCode;
+        if (code === -32600 && attempt < RESUME_LOCK_ATTEMPTS - 1) {
+          await delay(RESUME_LOCK_BACKOFF_MS);
+          continue;
+        }
+        console.warn(
+          `[codex] thread/resume ${this.customConnection ? "connection" : threadId} failed (${
+            this.customConnection ? connectionFailureReason(err) : err instanceof Error ? err.message : String(err)
+          }) — starting a fresh thread`,
+        );
+        return false;
+      }
+    }
+    return false;
+  }
+
+  // -- AgentSession ---------------------------------------------------------
+
+  private persistThreadId(threadId: string): void {
+    saveCodexThreadId(
+      this.taskId,
+      this.agentId,
+      threadId,
+      this.proc.durableSessionDir,
+      this.attachCompatibilityKey,
+    );
+  }
+
+  onEvent(handler: AgentEventHandler): () => void {
+    this.handlers.add(handler);
+    return () => this.handlers.delete(handler);
+  }
+
+  private emit(event: AgentEvent): void {
+    if (this.closed && event.type !== "exit") return;
+    for (const h of this.handlers) h(event);
+  }
+
+  private get cliLabel(): string {
+    return this.cliVersion ? `codex-cli ${this.cliVersion}` : "Codex";
+  }
+
+  private notificationTurnId(params: unknown): string | null {
+    if (!isObj(params)) return null;
+    return str(params.turnId) || (isObj(params.turn) ? str(params.turn.id) : "") || null;
+  }
+
+  private acknowledgeTurn(id: number, params?: unknown): void {
+    const turn = this.turnStarts.get(id);
+    if (!turn) return;
+    if (turn.timer) clearTimeout(turn.timer);
+    turn.timer = null;
+    turn.accepted = true;
+    turn.turnId = this.notificationTurnId(params) ?? turn.turnId;
+    const owner = turn.turnId === null ? undefined : [...this.turnStarts].find(
+      ([otherId, other]) => otherId !== id && other.accepted && other.turnId === turn.turnId,
+    );
+    if (owner) {
+      // Codex 0.164 steers a mid-turn start into the existing turn. One
+      // provider completion must settle every logical delivery it absorbed.
+      owner[1].settles += turn.settles;
+      this.turnStarts.delete(id);
+      this.outstandingTurns = Math.max(0, this.outstandingTurns - 1);
+      for (const [alias, target] of this.mergedStarts) {
+        if (target === id) this.mergedStarts.set(alias, owner[0]);
+      }
+      this.mergedStarts.set(id, owner[0]);
+    }
+    this.reconcileAcceptanceTimers();
+  }
+
+  private acknowledgeActivity(params: unknown, started = false): void {
+    const turnId = this.notificationTurnId(params);
+    if (turnId && [...this.turnStarts.values()].some(turn => turn.turnId === turnId)) {
+      // Ordinary chunks still belong to the running turn. Only an explicit
+      // new start notification can identify another start as merged here.
+      const pending = started && [...this.turnStarts].find(([, turn]) => !turn.accepted);
+      if (pending) this.acknowledgeTurn(pending[0], params);
+      return;
+    }
+    // Associate the first activity with an already acknowledged start before
+    // attributing it to a newer queued request. Old output must not cancel a
+    // different request's watchdog.
+    const unknown = [...this.turnStarts].find(([, turn]) => turn.turnId === null && turn.accepted);
+    if (unknown) {
+      if (turnId) unknown[1].turnId = turnId;
+      return;
+    }
+    const pending = [...this.turnStarts].find(([, turn]) => !turn.accepted);
+    if (pending) this.acknowledgeTurn(pending[0], params);
+  }
+
+  private reconcileAcceptanceTimers(): void {
+    // A late turn/start response can be queued behind accepted work on this
+    // thread. Bound waiting only when the thread is free, and give queued
+    // starts a fresh deadline when the last accepted message completes.
+    const occupied = [...this.turnStarts.values()].some(turn => turn.accepted);
+    for (const turn of this.turnStarts.values()) {
+      if (occupied) {
+        if (turn.timer) clearTimeout(turn.timer);
+        turn.timer = null;
+      } else if (!turn.timer) {
+        turn.timer = setTimeout(() => {
+          this.failTurn(`${this.cliLabel} didn't start this message within 60 seconds. Please try again.`);
+        }, CODEX_TURN_START_TIMEOUT_MS);
+        turn.timer.unref?.();
+      }
+    }
+  }
+
+  private clearTurnState(): void {
+    this.turnRunning = false;
+    this.outstandingTurns = 0;
+    this.clearRateLimitsTimer();
+    for (const turn of this.turnStarts.values()) if (turn.timer) clearTimeout(turn.timer);
+    this.turnStarts.clear();
+    this.mergedStarts.clear();
+    this.firedRequests.clear();
+  }
+
+  private failRpc(error: Record<string, unknown>, usage?: AgentUsage): void {
+    const code = typeof error.code === "number" ? error.code : undefined;
+    this.failTurn(`${this.cliLabel} rejected the message${code === undefined ? "" : ` (code ${code})`}: ${str(error.message, "Unknown error. Please try again.")}`, code, usage);
+  }
+
+  private reportError(message: string, rpcCode?: number, capture = true): void {
+    if (this.customConnection) message = connectionFailureReason(message);
+    reportAgentError(message, { taskId: this.taskId, agentId: this.agentId, engine: this.kind, rpcCode }, { capture });
+  }
+
+  /** One terminal failure per generation. Late responses, completion and
+   * process exit cannot end this turn twice or leak into a replacement. */
+  private failTurn(message: string, code?: number, usage?: AgentUsage): void {
+    if (this.failed || this.closed) return;
+    this.failed = true;
+    // The chat gets the upstream's status and a scrubbed excerpt (the same
+    // function the sanitizer uses); telemetry and every other reader see only
+    // the reason code, and no raw upstream text leaves this adapter.
+    const detail = this.customConnection ? connectionFailureDetail(message, this.connectionKey) : null;
+    if (this.customConnection) message = connectionFailureReason(message);
+    this.reportError(message, code);
+    const aborted = this.outstandingTurns > 0;
+    const settles = this.outstandingTurns + [...this.turnStarts.values()]
+      .reduce((merged, turn) => merged + turn.settles - 1, 0);
+    this.clearTurnState();
+    const display = agentErrorMessage(message);
+    for (const event of mapCodexNotification("error", { error: { message } })) {
+      this.emit(event.type === "error" ? { ...event, message: display,
+        ...(display === message ? {} : { diagnosticMessage: message }), ...(detail ? { detail } : {}), code, aborted } : event);
+    }
+    if (aborted) this.emit({ type: "turn_complete", aborted: true,
+      ...(settles > 1 ? { settles } : {}), ...(usage ? { usage } : {}) });
+    for (const waiter of this.pending.values()) waiter.reject(new Error(message));
+    this.pending.clear();
+    void this.proc.close().catch(() => {});
+  }
+
+  async send(text: string): Promise<void> {
+    if (this.closed || this.failed) throw new Error(`${this.cliLabel} is no longer available. Please try again.`);
+    this.outstandingTurns += 1;
+    await this.ready;
+    if (this.closed || this.failed) return;
+    if (!this.handshakeOk || !this.threadId) {
+      this.failTurn(`${this.cliLabel} could not start. Please try again.`);
+      return;
+    }
+
+    // `ready` may have waited across a runtime generation change. Recheck at
+    // the turn/start write rather than trusting session construction time.
+    try {
+      requireContainerRuntimeOperational();
+    } catch (error) {
+      this.outstandingTurns -= 1;
+      throw error;
+    }
+    const turnStartId = this.fireRequest("turn/start", {
+      threadId: this.threadId,
+      input: [{ type: "text", text }],
+    });
+    this.turnRunning = true;
+    this.turnStarts.set(turnStartId, { timer: null, turnId: null, accepted: false, settles: 1 });
+    this.reconcileAcceptanceTimers();
+    this.scheduleRateLimitsRead();
+  }
+
+  async interrupt(): Promise<void> {
+    if (this.closed || !this.threadId) return;
+    // Cancel the thread's in-flight turn (codex's ESC). The app-server ends the
+    // current turn and emits a `turn/completed`. No-op when nothing is running.
+    // ⚠️ VERIFY-ON-MAC: confirm the codex interrupt method/params.
+    this.fireRequest("turn/interrupt", { threadId: this.threadId });
+  }
+
+  async resolvePermission(
+    requestId: string,
+    decision: "accept" | "decline",
+  ): Promise<void> {
+    if (this.closed) return;
+    const rpcId = this.approvals.get(requestId);
+    if (rpcId === undefined) return;
+    this.approvals.delete(requestId);
+    this.respond(rpcId, {
+      decision: decision === "accept" ? "accept" : "decline",
+    });
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) {
+      await this.proc.close();
+      return;
+    }
+    this.closed = true;
+    this.clearTurnState();
+    for (const waiter of this.pending.values()) {
+      waiter.reject(new Error("session closed"));
+    }
+    this.pending.clear();
+    await this.proc.close();
+    this.emit({ type: "exit", code: 0 });
+    this.handlers.clear();
+  }
+}
+
+// Register the Codex adapter at module load (ADR-021). The `-c model=` config
+// override above means `model` flows from the roster entry to the app-server.
+register({
+  kind: "codex",
+  label: "Codex",
+  supportedModels: () => [...CODEX_MODELS],
+  defaultModel: CODEX_DEFAULT_MODEL,
+  supportedEfforts: () => [...CODEX_EFFORTS],
+  defaultEffort: CODEX_DEFAULT_EFFORT,
+  // ADR-157: enforceable by construction (the --disable flags above). The
+  // communicator profile is Claude-only; Codex never declared it.
+  executionProfiles: [{ id: "astronaut", mechanism: "codex-disable-multi-agent-v1" }],
+  // Usable only when the owner's ~/.codex login exists — task-up copies it into
+  // each container from UAI_OWNER_HOME (default $HOME). Gates advertisement
+  // (ADR-044 P2).
+  available: () =>
+    existsSync(
+      join(process.env.UAI_OWNER_HOME?.trim() || homedir(), ".codex", "auth.json"),
+    ),
+  // Forward `cliConfigOverrides` too: the Uai Managed Engine's gateway
+  // provider block rides it, and this destructuring silently dropped it on
+  // the first live gpt-5-mini smoke (2026-09-12, host 0.9.136 — codex still
+  // dialed api.openai.com).
+  create: async ({
+    taskId,
+    agent,
+    environment,
+    systemPreamble,
+    agentEnv,
+    attachCompatibilityKey,
+    cliConfigOverrides,
+    executionProfile,
+  }) =>
+    new CodexSession({
+      taskId,
+      agent,
+      environment,
+      systemPreamble,
+      agentEnv,
+      attachCompatibilityKey,
+      cliConfigOverrides,
+      executionProfile,
+    }),
+});