@humwick/server 0.0.0-stage → 0.130.0

package/runner/src/adapters/codex.ts

@@ -0,0 +1,1442 @@
+import { writeChildEnv } from "@humwick/sdk/env";
+import { terminateProviderProcesses } from "../provider-processes";
+import { type InteractivePrompt, type LivenessSignal, type Message, type MessageTurnEndReason, type ProviderState, type ToolCallCategory, sanitizeLaunchBoundary, sanitizeLaunchText, errMessage, isRecord, stringValue, HARNESS_SUBAGENTS_DISABLED, harnessSubagentsEnabled } from "@humwick/sdk";
+import { codexEndedByFrom, codexTurnFailure } from "./codex-turn-outcome";
+import { processTreePidsFromTable } from "@humwick/sdk/process-utils";
+import { providerMessageText, type ManagedProcess, type PromptOfferOptions, type ProviderAdapter, type ProviderConfig, type ProviderDeliverContext, type ProviderInputObserver, type ProviderPermissionDecisionInput, type ProviderSessionEvent, type ProviderStatusUpdate, type ProviderTokenUsageReporter, type RunnerSpawnConfig, type ShutdownOutcome, type SpawnArgs, type TerminalAttachSpec } from "../adapter";
+import { launchProvisionedMcpServers } from "../provisioning";
+import { resolveRelayContext, workspaceDepsNoteFromEnv } from "../relay-instructions";
+import { allocateLoopbackPort } from "../free-port";
+import { midTurnClientUserId, partitionMidTurnDelivery, resolveActiveTurnMessageDelivery } from "../mid-turn-delivery";
+import { CODEX_TURN_IN_PROGRESS_MESSAGE } from "../runner-helpers";
+
+import { assembleLaunch, bundledCodexSkillDirs, bundledSkillConfigArgs, codexSkillRoots, materializeLaunchAssembly } from "../launch-assembly";
+import { logger } from "../logger";
+import { freshContextState } from "../transcript-context";
+import type { SessionEvent } from "../session-insights";
+import { CodexAgentMessageCapture } from "./codex-agent-message-capture";
+import { absoluteToolPaths, clipToolSummary, codexReadPaths, oneLineText, redactAndCapParams } from "./tool-summary";
+import { codexTokenUsageContext, isContextState, latestCodexContext } from "./codex-rollout-context";
+import { reportCodexTokenUsage } from "./codex-token-usage-capture";
+import { computeLivenessSignal, type LivenessInputs } from "../liveness";
+import { CodexAppClient, CodexRpcError, type ClientEvent } from "./codex-client";
+import { registerCodexSkillRoots } from "./codex-skill-discovery";
+import { spawnCodexAppServer } from "./codex-app-server";
+import { codexWebToolsConfigArgs, launchWebTools } from "../web-tools";
+import { codexMcpOutputRedactor } from "./codex-tool-output";
+
+/** Relay context prepended to a Codex agent's first turn: the standard relay
+ * blurb plus, when running in an isolated workspace, the deps caveat (#159). */
+function codexRelayContextBlock(process: ManagedProcess): string {
+  const config = process.meta?.config as RunnerSpawnConfig | undefined;
+  return [resolveRelayContext({
+    slug: "relay.context.codex", config,
+    mcpServers: config ? launchProvisionedMcpServers(config) : undefined,
+    webTools: config ? { names: launchWebTools(config), claude: false } : undefined,
+  }).text, workspaceDepsNoteFromEnv()].filter(Boolean).join("\n\n");
+}
+import { prepareCodexProfileHome } from "../profile-home";
+import { buildCodexTuiSpawnArgs, codexApprovalConfigArgs, codexAppServerConfigArgs, codexHarnessConfigArgs, codexManagedConfigArgs, codexModelConfigArgs, codexToolOutputTokenLimitConfigArgs, isCodexCliCommand, resolveRealCodexCommand } from "./codex-launch-config";
+import { codexProjectShellConfigArgs } from "./project-shell";
+
+export { processTreePidsFromTable };
+// Launch/config-arg construction lives in ./codex-launch-config; re-exported so
+// codex.ts consumers + tests keep their import path.
+export {
+  codexApprovalConfigArgs,
+  codexAppServerConfigArgs,
+  codexManagedConfigArgs,
+  codexModelConfigArgs,
+  codexToolOutputTokenLimitConfigArgs,
+  DEFAULT_CODEX_TOOL_OUTPUT_TOKEN_LIMIT,
+  isCodexCliCommand,
+  resolveRealCodexCommand,
+} from "./codex-launch-config";
+
+type PendingCodexApproval = {
+  id: string;
+  requestId: string | number;
+  method: string;
+  params: Record<string, unknown>;
+  view: InteractivePrompt;
+};
+
+type PendingCodexCompact = {
+  threadId: string;
+  timeout: ReturnType<typeof setTimeout>;
+  resolve: () => void;
+  reject: (error: Error) => void;
+};
+
+const CODEX_COMPACT_TIMEOUT_MS = 10 * 60 * 1000;
+
+// #2539 Phase A — bounded memory of clientUserMessageIds POSITIVELY accepted by the app-server
+// (observed via the userMessage item echo). Insertion-ordered, oldest evicted; the reconcile
+// path only needs recent turns' ids.
+const CODEX_STEER_ACCEPTED_CLIENT_CAP = 128;
+
+/**
+ * #2539 Phase A — classify a rejected `turn/steer` RPC so the fallback matches the refusal.
+ * The app-server refuses steer against a turn that cannot take additive input (review/compact)
+ * and against a turn id that is no longer active (ended under us / expected-id mismatch); both
+ * are expected flow control, distinct from transport faults (socket, 30s timeout — an AMBIGUOUS
+ * outcome: the steer may still have been accepted, so the caller must not assume either way).
+ * Any OTHER structured JSON-RPC error is still a definitive refusal (the input was not
+ * accepted) — classified "unknown-refusal" so the caller defers instead of rethrowing into a
+ * ~1s refused-RPC hot loop. Pure + exported so the classification table is unit-testable.
+ *
+ * Spellings verified live-fire against codex-cli 0.153.3 app-server (2026-09-11), all code
+ * -32600, `data` undefined on the wire:
+ * - `no active turn to steer` → stale-turn
+ * - `expected active turn id \`X\` but found \`Y\`` → stale-turn (expected-id mismatch)
+ * - `cannot steer a compact turn` → not-steerable (a compact runs AS an active turn; review
+ *   is the parallel construction; upstream CodexErrorInfo names the kind
+ *   activeTurnNotSteerable{turnKind: "review"|"compact"} — checked first when `data` carries it)
+ */
+export function classifyTurnSteerRejection(error: unknown): "not-steerable" | "stale-turn" | "unknown-refusal" | undefined {
+  if (!(error instanceof CodexRpcError)) return undefined;
+  const message = error.message.toLowerCase();
+  const data = isRecord(error.data) ? error.data : undefined;
+  const dataKind = stringValue(data?.kind) ?? stringValue(data?.reason) ?? stringValue(data?.type);
+  if (dataKind === "review" || dataKind === "compact") return "not-steerable";
+  if (message.includes("not steerable") || message.includes("notsteerable")) return "not-steerable";
+  if (/cannot steer a (review|compact) turn/.test(message)) return "not-steerable";
+  if (dataKind === "stale-turn" || /no active turn|expected active turn id|turn (id )?mismatch|expected turn|unknown turn|turn not (found|active)/.test(message)) return "stale-turn";
+  return "unknown-refusal";
+}
+
+export class CodexAdapter implements ProviderAdapter {
+  mcpToolResponseRedactor = codexMcpOutputRedactor;
+  readonly provider = "codex";
+  readonly reportsContextResets = true;
+  readonly supportsMidTurnSteer = true;
+  // #2569 — clearContext starts a FRESH thread and compact rewrites the current one, both via an
+  // awaited app-server handshake. That await confirms the new generation is ready but does NOT
+  // settle the predecessor turn (the model calls relay_compact_and_resume from within its own live
+  // turn). Without a fence, that turn keeps writing the worktree on the old thread while the
+  // successor generation writes on the new one. The runner therefore interrupts + settles the
+  // predecessor turn before compact/clearContext (interrupt-then-settle, via the primitives below).
+  readonly interruptsTurnBeforeContextCommand = true;
+  private statusCb: (status: ProviderStatusUpdate) => void = () => {};
+  private sessionEventCb: (event: ProviderSessionEvent) => void = () => {};
+  private readonly subagentThreads = new Map<string, { label?: string; role?: string; parentId?: string }>();
+  private readonly pendingApprovals = new Map<string, PendingCodexApproval>();
+  private pendingCompact?: PendingCodexCompact;
+  // Active turn id for the main thread, captured from turn/started so an interrupt
+  // can target the in-flight turn. Cleared on turn/completed.
+  private activeTurnId?: string;
+  private lastCompactionKey?: string;
+  private turnFailure?: ReturnType<typeof codexTurnFailure>;
+  // #1339: the turn id we last logged a delivery-deferral for, so the once-per-turn "held
+  // behind active turn" notice isn't repeated on every ~1s runner retry during that turn.
+  private deferredForTurnId?: string;
+  // #2539 Phase A — the turn id whose steer the app-server REJECTED as not steerable
+  // (review/compact). Once set for a turn id, mid-turn offers silently defer until the turn id
+  // changes, instead of re-attempting the RPC on every ~1s drain only to be refused again.
+  private steerDeniedForTurnId?: string;
+  // #2539 Phase A — clientUserMessageIds POSITIVELY accepted by the app-server (the userMessage
+  // item echoes the steered input's clientId). The reconcile path reads this to settle an
+  // accepted-but-response-lost steer instead of re-steering (which could duplicate the input).
+  private readonly acceptedSteerClientIds = new Set<string>();
+  // #653: monotonic id for a turn we synthesize from live item activity when a real
+  // turn/started never reached us — so a working Codex agent isn't reported `idle`.
+  private syntheticTurnSeq = 0;
+  // #2543: monotonic clientUserMessageId sequence for prompt injections steered into a live
+  // turn — per-attempt unique (the app-server echoes it back; no reconcile reads it).
+  private injectionSteerSeq = 0;
+  private tokenUsageReporter?: ProviderTokenUsageReporter;
+  private readonly agentMessageCapture = new CodexAgentMessageCapture();
+  private readonly itemTextBuffers = new Map<string, string>();
+  private readonly itemTextBufferTypes = new Map<string, string>();
+  // #183/#184: the normalized session-event log for the current process lifetime, fed
+  // from the same completed-item stream that drives the chat mirror. The runner slices
+  // this per-segment (since the last compact/clear/restart) via its own cursor, so we
+  // accumulate and never clear mid-session; spawn() resets it for a fresh process. Soft
+  // cap below keeps a runaway session from growing memory unbounded.
+  private sessionEvents: SessionEvent[] = [];
+  private static readonly SESSION_EVENTS_CAP = 50_000;
+  // #3411 — the session cwd a fileChange's relative paths resolve against.
+  private sessionCwd?: string;
+
+  onStatusChange(cb: (status: ProviderStatusUpdate) => void): void {
+    this.statusCb = cb;
+  }
+
+  // §4.1 contract verdict (#746). Codex reference (#724): a Codex provider-turn can wedge
+  // while a long-running subprocess child (a `bun test` / build gate) is still alive and
+  // making real progress. That subprocess is tracked as a non-`provider-turn` work-kind, so
+  // `hasLiveWork` stays true and the turn is never mis-read as stuck; app-server item events
+  // also refresh `lastProviderEventAt` → lastProgressAt. The fold is shared; this override
+  // documents and owns Codex's progress sources behind the contract.
+  liveness(inputs: LivenessInputs): LivenessSignal {
+    return computeLivenessSignal(inputs);
+  }
+
+  onSessionEvent(cb: (event: ProviderSessionEvent) => void): void {
+    this.sessionEventCb = cb;
+  }
+
+  private resetProcessState(): void {
+    this.resetThreadState();
+    this.sessionEvents = []; // fresh process -> fresh segment cursor (#184)
+  }
+
+  private resetThreadState(): void {
+    this.cancelPendingCompact(new Error("Codex compact canceled by thread reset"));
+    this.subagentThreads.clear();
+    this.pendingApprovals.clear();
+    this.activeTurnId = undefined;
+    this.turnFailure = undefined;
+    this.steerDeniedForTurnId = undefined;
+    this.acceptedSteerClientIds.clear();
+    this.agentMessageCapture.reset();
+    this.itemTextBuffers.clear();
+    this.itemTextBufferTypes.clear();
+  }
+
+  async interrupt(process: ManagedProcess): Promise<Record<string, unknown>> {
+    const client = process.meta?.client as CodexAppClient | undefined;
+    if (!client) throw new Error("Codex App Server client is unavailable");
+    const threadId = typeof process.meta?.threadId === "string" ? process.meta.threadId : "";
+    if (!threadId) throw new Error("Codex thread is not ready");
+    if (!this.activeTurnId) throw new Error("no active Codex turn to interrupt");
+    await client.turnInterrupt(threadId, this.activeTurnId);
+    return { method: "turn-interrupt", turnId: this.activeTurnId };
+  }
+
+  async probeActivity(process: ManagedProcess): Promise<"busy" | "idle" | "unknown"> {
+    const client = process.meta?.client as CodexAppClient | undefined;
+    if (!client?.isConnected()) return "unknown";
+    const threadId = typeof process.meta?.threadId === "string" ? process.meta.threadId : "";
+    // #651: when no local activeTurnId, don't short-circuit to idle — query the app-server.
+    // turn/started can arrive after processing begins (or be missed entirely); a stale-idle
+    // probe would make a busy agent appear idle to the coordinator. Same fallback as #653's
+    // ensureMainTurnActive path, but for the pull (probe) direction, not the push (event) one.
+    if (!this.activeTurnId) {
+      if (!threadId) return "idle";
+      try {
+        const read = await client.threadRead(threadId, true);
+        const thread = isRecord(read.thread) ? read.thread : undefined;
+        const turns = Array.isArray(thread?.turns) ? thread.turns : [];
+        const inProgressTurn = turns.find((t) => isRecord(t) && stringValue(t.status) === "inProgress");
+        if (inProgressTurn) {
+          // Synthesize the active turn (same path as ensureMainTurnActive on item events).
+          this.ensureMainTurnActive(stringValue(inProgressTurn.id));
+          return "busy";
+        }
+        const threadStatus = statusType(thread?.status);
+        if (threadStatus === "active") return "busy";
+        return "idle";
+      } catch {
+        return "unknown";
+      }
+    }
+    if (!threadId) return "busy";
+    try {
+      const read = await client.threadRead(threadId, true);
+      const thread = isRecord(read.thread) ? read.thread : undefined;
+      const turns = Array.isArray(thread?.turns) ? thread.turns : [];
+      const activeTurn = turns.find((turn) => isRecord(turn) && stringValue(turn.id) === this.activeTurnId);
+      const turnStatus = isRecord(activeTurn) ? stringValue(activeTurn.status) : undefined;
+      if (turnStatus === "inProgress") return "busy";
+      if (turnStatus === "completed" || turnStatus === "interrupted" || turnStatus === "failed") {
+        this.finishMainTurn(codexEndedByFrom(turnStatus), isRecord(activeTurn) ? activeTurn.error : undefined);
+        return "idle";
+      }
+      const threadStatus = statusType(thread?.status);
+      if (threadStatus === "active") return "busy";
+      if (threadStatus === "idle" || threadStatus === "notLoaded" || threadStatus === "systemError") {
+        this.finishMainTurn(codexEndedByFrom(threadStatus));
+        return "idle";
+      }
+    } catch {
+      return "unknown";
+    }
+    return "busy";
+  }
+
+  // The Codex app-server is headless and has no tmux session, but an unexpected
+  // exit should still be restarted with backoff rather than resolved as a final exit.
+  supportsUnexpectedExitRestart(): boolean {
+    return true;
+  }
+
+  async spawn(config: RunnerSpawnConfig): Promise<ManagedProcess> {
+    this.resetProcessState();
+    this.sessionCwd = config.cwd;
+    const args = this.buildSpawnArgs(config, config.providerConfig as ProviderConfig);
+    const { appServer, appServerUrl, client } = await spawnCodexAppServer(args);
+    if (client) {
+      await client.initialize().catch(() => undefined);
+      await registerCodexSkillRoots(client, codexSkillRoots(config), (message) => logger.warn("codex", message));
+    }
+
+    const tuiArgs = buildCodexTuiSpawnArgs(config, config.providerConfig, appServerUrl, args.env);
+    const tui = tuiArgs
+      ? Bun.spawn([tuiArgs.command, ...tuiArgs.args], {
+        cwd: tuiArgs.cwd,
+        env: tuiArgs.env,
+        stdin: "inherit",
+        stdout: "inherit",
+        stderr: "inherit",
+      })
+      : undefined;
+
+    // app-server and tui exit independently; the first exit defines the agent's
+    // fate. Latch so a trailing second exit can't fire a duplicate terminal event.
+    let exitReported = false;
+    const reportExit = (status: ProviderStatusUpdate): void => {
+      if (exitReported) return;
+      exitReported = true;
+      this.statusCb(status);
+    };
+    void appServer.exited.then((code) => reportExit(code === 0 ? "offline" : "error")).catch(() => reportExit("error")).catch(() => {});
+    if (tui) void tui.exited.then((code) => reportExit(code === 0 ? "idle" : "error")).catch(() => reportExit("error")).catch(() => {});
+    const process: ManagedProcess = {
+      pid: tui?.pid ?? appServer.pid,
+      process: appServer,
+      meta: {
+        client,
+        cwd: config.cwd,
+        appServer,
+        appServerUrl,
+        tui,
+        config,
+        attachCommand: resolveRealCodexCommand(config.providerConfig.command, args.env.PATH),
+      },
+    };
+    process.meta = { ...process.meta, getContext: () => latestCodexContext(process) };
+    if (client) client.onEvent((event) => this.handleCodexEvent(event, process));
+    return process;
+  }
+
+  async shutdown(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<ShutdownOutcome> {
+    const client = process.meta?.client as CodexAppClient | undefined;
+    client?.close();
+    return terminateProviderProcesses([process.meta?.tui, process.meta?.appServer, process.process].filter(Boolean) as Bun.Subprocess[], opts);
+  }
+
+  async compact(process: ManagedProcess): Promise<Record<string, unknown>> {
+    const client = process.meta?.client as CodexAppClient | undefined;
+    if (!client) throw new Error("Codex App Server client is unavailable");
+    const threadId = typeof process.meta?.threadId === "string" ? process.meta.threadId : "";
+    if (!threadId) throw new Error("Codex thread is not ready");
+    this.statusCb({ status: "busy", reason: "provider-turn", timeline: { status: "compacting", timestamp: Date.now() } });
+    const currentContext = isContextState(process.meta?.context) ? process.meta.context : undefined;
+    if (currentContext) {
+      process.meta = {
+        ...(process.meta ?? {}),
+        context: { ...currentContext, lifecycleState: "compacting", lastUpdatedAt: Date.now() },
+      };
+    }
+    const completion = this.waitForPendingCompact(threadId);
+    try {
+      await client.threadCompactStart(threadId);
+      await completion;
+    } catch (error) {
+      this.clearPendingCompact(threadId);
+      this.statusCb({ status: "idle", reason: "provider-turn" });
+      throw error;
+    }
+    return { threadId };
+  }
+
+  /** #3398 — every compaction of the main thread is a context reset, whether or not compact() still waits for it. */
+  private onThreadCompacted(process: ManagedProcess, threadId: string, turnId: string | undefined, compactTrigger: "manual" | "auto"): void {
+    if (threadId !== process.meta?.threadId) return;
+    // thread/compacted and the compaction item report the same compaction.
+    const key = turnId ? `${threadId}:${turnId}` : undefined;
+    if (key && key === this.lastCompactionKey) return;
+    this.lastCompactionKey = key;
+    const compactedAt = Date.now();
+    if (isContextState(process.meta?.context)) {
+      process.meta = { ...(process.meta ?? {}), context: { ...process.meta.context, lifecycleState: "cooling", tasksSinceCompact: 0, lastCompactedAt: compactedAt, lastUpdatedAt: compactedAt } };
+    }
+    const timeline = { status: "compacted", timestamp: compactedAt };
+    const metadata = { compactTrigger };
+    this.statusCb(this.activeTurnId ? { status: "busy", reason: "provider-turn", id: this.activeTurnId, timeline, metadata } : { status: "idle", reason: "provider-turn", timeline, metadata });
+    this.completePendingCompact(threadId);
+  }
+
+  async clearContext(process: ManagedProcess): Promise<Record<string, unknown>> {
+    const client = process.meta?.client as CodexAppClient | undefined;
+    if (!client) throw new Error("Codex App Server client is unavailable");
+    const previousThreadId = typeof process.meta?.threadId === "string" ? process.meta.threadId : undefined;
+    this.statusCb({ status: "busy", reason: "provider-turn", timeline: { status: "clearing-context", timestamp: Date.now() } });
+    let started: Awaited<ReturnType<CodexAppClient["threadStart"]>>;
+    try {
+      started = await client.threadStart({ cwd: typeof process.meta?.cwd === "string" ? process.meta.cwd : globalThis.process.cwd() });
+    } catch (error) {
+      this.statusCb({ status: "idle", reason: "provider-turn" });
+      throw error;
+    }
+    const clearedAt = Date.now();
+    this.resetThreadState();
+    process.meta = {
+      ...(process.meta ?? {}),
+      threadId: started.thread.id,
+      relayContextSent: false,
+      context: freshContextState(clearedAt),
+    };
+    this.statusCb({ status: "idle", reason: "provider-turn", clear: ["subagent"], timeline: { status: "context-cleared", timestamp: clearedAt } });
+    return { previousThreadId, threadId: started.thread.id };
+  }
+
+  async terminalAttachSpec(process: ManagedProcess): Promise<TerminalAttachSpec> {
+    const threadId = typeof process.meta?.threadId === "string" ? process.meta.threadId : "";
+    if (!threadId) throw new Error("Codex thread is not ready");
+    const appServerUrl = typeof process.meta?.appServerUrl === "string" ? process.meta.appServerUrl : "";
+    if (!appServerUrl) throw new Error("Codex app-server URL is unavailable");
+    const command = typeof process.meta?.attachCommand === "string" && process.meta.attachCommand
+      ? process.meta.attachCommand
+      : resolveRealCodexCommand("codex");
+    return {
+      mode: "guest",
+      provider: "codex",
+      cwd: typeof process.meta?.cwd === "string" ? process.meta.cwd : globalThis.process.cwd(),
+      command: [command, ...codexManagedConfigArgs(), "resume", threadId, "--remote", appServerUrl],
+      title: `Codex ${threadId.slice(0, 8)}`,
+      ttlMs: 60 * 60 * 1000,
+    };
+  }
+
+  async deliverInitialPrompt(process: ManagedProcess, prompt: string, options?: PromptOfferOptions): Promise<void> {
+    const text = sanitizeLaunchText(prompt, "initial prompt").trim(); // options.readyTimeoutMs (#329) is a Claude-TUI concern; ignored here
+    if (!text) return;
+    const threadId = await ensureCodexThread(process);
+    // #1228: only a genuine first turn gets the initial-prompt label — a mid-session
+    // dashboard continue/injection (isInitial: false) is delivered as a plain turn.
+    const isInitial = options?.isInitial !== false;
+    // #2543 — the last provider-input path without an active-turn guard: a non-initial injection
+    // (dashboard continue/hard-redirect, AskUserQuestion answer, empty-turn nudge) offered while
+    // a turn is ACTIVE must never issue turn/start (#1339: the app-server silently drops it).
+    // Fold it into the live turn via the same additive turn/steer channel deliverMidTurn uses; a
+    // refusal defers by throwing the shared turn-in-progress signal, which the runner's injection
+    // paths translate into a bounded wait-for-turn-clear + re-offer. A genuine initial prompt
+    // (isInitial: true) keeps the start path — its process was just spawned, there is no live turn.
+    if (!isInitial && this.activeTurnId !== undefined) {
+      await this.steerInjectionIntoActiveTurn(process, threadId, this.activeTurnId, text, options?.inputObserver);
+      return;
+    }
+    let input = [
+      codexLaunchContext(process),
+      ...(isInitial ? ["[agent-relay initial prompt from dashboard]"] : []),
+      text,
+    ].filter(Boolean).join("\n\n");
+    // #2542 — transactional first-delivery context (#2539 design C applied to this start path):
+    // stage the relay-context block but commit relayContextSent ONLY after turn/start is
+    // positively accepted, so a failed first turn/start (ready-signal retry, spawn retry) still
+    // carries the context instead of silently losing it.
+    let relayContextPending = false;
+    if (codexRelayContextEnabled(process) && !process.meta?.relayContextSent) {
+      input = codexRelayContextBlock(process) + "\n\n" + input;
+      relayContextPending = true;
+    }
+    logger.info("codex", `starting Codex initial prompt in thread ${threadId}`);
+    const client = process.meta?.client as CodexAppClient;
+    options?.inputObserver?.offered(Date.now(), true);
+    const started = await client.turnStart(threadId, input);
+    options?.inputObserver?.consumed();
+    if (relayContextPending) process.meta = { ...(process.meta ?? {}), relayContextSent: true };
+    // #1565 F1 — claim the turn from the RESPONSE, the same hardening deliver() has: without it,
+    // a second input in the notification lag read activeTurnId as undefined and issued a
+    // concurrent turn/start the app-server silently dropped. A later turn/started overwrites
+    // this id; the completion/interrupt/probeActivity paths clear it, so it cannot wedge.
+    this.ensureMainTurnActive(stringValue(isRecord(started?.turn) ? started.turn.id : undefined));
+  }
+
+  /**
+   * #2543 — fold a non-initial prompt injection into the ACTIVE turn via the additive
+   * `turn/steer` channel (the #2539 Phase A channel, shared with deliverMidTurn). The relay
+   * context is not re-prepended: an active turn can only exist if its own accepted start already
+   * carried (and committed) the first-delivery context. Refusals DEFER — the shared
+   * turn-in-progress signal makes the runner's injection paths wait for the turn to clear and
+   * re-offer on the idle path — while transport faults stay AMBIGUOUS and rethrow (the command
+   * fails visibly; never a silent drop, never an automatic re-steer against a possibly-accepted
+   * steer). Unlike deliverMidTurn there is no accepted-clientId reconcile: injections are
+   * one-shot user actions with no relay-id settlement and no automatic re-offer of the same
+   * payload, so a lost steer response simply fails the command.
+   */
+  private async steerInjectionIntoActiveTurn(process: ManagedProcess, threadId: string, steerTurnId: string, text: string, inputObserver?: ProviderInputObserver): Promise<void> {
+    const client = process.meta?.client as CodexAppClient;
+    const clientId = `relay-inject-${++this.injectionSteerSeq}`;
+    try {
+      inputObserver?.offered(Date.now(), true);
+      await client.turnSteer(threadId, steerTurnId, text, clientId);
+      inputObserver?.consumed();
+    } catch (error) {
+      const rejection = classifyTurnSteerRejection(error);
+      if (rejection === undefined) throw error;
+      if (rejection === "stale-turn") {
+        // The turn ended under us: zero ack. The runner's defer waits for the cleared turn and
+        // re-offers; the re-offer then observes no activeTurnId and takes the start path.
+        logger.info("codex", `injection steer rejected against Codex turn ${steerTurnId} (no longer active); deferring until the provider is idle`);
+      } else {
+        // not-steerable (review/compact) or an unrecognized structured refusal: this turn cannot
+        // take additive input. Remember it so MESSAGE offers defer silently too (the same memory
+        // deliverMidTurn keeps), and defer this injection until the turn ends.
+        this.steerDeniedForTurnId = steerTurnId;
+        logger.info("codex", `active Codex turn ${steerTurnId} refused an injection steer (${rejection}); deferring until it ends`);
+      }
+      throw new Error(CODEX_TURN_IN_PROGRESS_MESSAGE);
+    }
+    logger.info("codex", `steered relay prompt injection (${text.length} chars) into active Codex turn ${steerTurnId}`);
+  }
+
+  async deliver(process: ManagedProcess, messages: Message[], ctx?: ProviderDeliverContext): Promise<void | number[]> {
+    const threadId = await ensureCodexThread(process);
+    // #2539 Phase A — a mid-turn offer goes through the adapter-owned steer contract: the
+    // steerable subset folds into the in-flight turn (soft-steer is the codex default), while
+    // boundary-only classes stay un-acked for the runner to requeue toward turn-end. An idle
+    // offer takes the WHOLE ordered batch as one fresh turn/start — NEVER turn/start while a
+    // turn is active (#1339: the app-server would drop it).
+    if (this.activeTurnId !== undefined) {
+      return this.deliverMidTurn(process, messages, ctx);
+    }
+    const client = process.meta?.client as CodexAppClient;
+    // #2542 — transactional formatting state on the IDLE turn/start path (#2539 design C, the
+    // same fix deliverMidTurn already has): stage the first-delivery
+    // relay context, and commit BOTH only after turn/start is positively accepted — a failed
+    // start must not consume the first-delivery context, so the runner's requeue re-offers WITH
+    // it instead of silently losing it.
+    let text = [codexLaunchContext(process), providerMessageText(messages)].filter(Boolean).join("\n\n");
+    let relayContextPending = false;
+    if (codexRelayContextEnabled(process) && !process.meta?.relayContextSent) {
+      text = codexRelayContextBlock(process) + "\n\n" + text;
+      relayContextPending = true;
+    }
+    logger.info("codex", codexDeliveryNotice(messages, threadId));
+    ctx?.inputObserver?.offered(Date.now(), true);
+    const started = await client.turnStart(threadId, text);
+    ctx?.inputObserver?.consumed();
+    if (relayContextPending) process.meta = { ...(process.meta ?? {}), relayContextSent: true };
+    // #1565 F1 — claim the turn from the RESPONSE, not from the later `turn/started` notification.
+    // The guard above is only as good as the state it reads: with the turn id arriving a few ms
+    // later over the event stream, a second delivery in that window passed the guard and issued a
+    // concurrent turn/start on the same thread, which the app-server silently drops — while its
+    // command still reported success, so nothing retried it. Claiming it here closes the window:
+    // the second payload is DEFERRED (the runner re-offers it when this turn ends) instead of
+    // being lost. A later `turn/started` overwrites this id; `turn/completed`, `turn/failed`,
+    // `turn/interrupted` and the 4s probeActivity sweep all clear it, so it cannot wedge.
+    this.ensureMainTurnActive(stringValue(isRecord(started?.turn) ? started.turn.id : undefined));
+  }
+
+  /**
+   * #2539 Phase A — the codex implementation of the shared mid-turn steer contract (see
+   * {@link ProviderAdapter.deliverMidTurn}). Steerable messages fold into the in-flight turn via
+   * the ADDITIVE app-server `turn/steer`: the running tool/response step finishes untouched, and
+   * the injected input is drained before the next model request — never an abort, never a
+   * concurrent turn/start. Guards, per the authoritative design:
+   *
+   * - Boundary-only partition (shared `partitionMidTurnDelivery`): synthetic memory/self-resume/context injections, and claimable/task assignments
+   *   keep the turn-end path — left un-acked so the runner requeues them.
+   * - Kill switch: `ProviderConfig.activeTurnMessageDelivery === "defer"` restricts the steerable
+   *   set to empty, deferring messages until the turn ends.
+   * - Not-steerable turns (review/compact) defer silently for the WHOLE turn id — remembered
+   *   once, no ~1s hot loop of refused RPCs.
+   * - Transactional formatting state: relayContextSent commit ONLY on positive
+   *   acceptance, so a rejected steer never consumes the first-delivery relay context.
+    * - Acceptance correlation: the steer carries a stable clientUserMessageId; its echo settles
+    *   an accepted-but-response-lost steer by correlation. At-least-once with EXPLICIT ambiguity —
+    *   a timeout is never assumed accepted, and a re-steer after a true in-flight loss may
+    *   duplicate (correlation is not idempotent dedupe upstream). The reconcile assumes
+    *   echo ⇒ eventual consumption: if the turn is interrupted/aborted AFTER the clientId echo
+    *   but BEFORE the pending input is consumed, a re-offer settles by correlation and the
+    *   content never reached the model — inside this documented ambiguity envelope.
+    * - Unrecognized structured refusals defer (see {@link classifyTurnSteerRejection}); ONLY
+    *   transport faults (socket, 30s timeout — genuinely ambiguous) rethrow into re-steer.
+    */
+  async deliverMidTurn(process: ManagedProcess, messages: Message[], ctx?: ProviderDeliverContext): Promise<void | number[]> {
+    const steerTurnId = this.activeTurnId;
+    if (steerTurnId === undefined) throw new Error(CODEX_TURN_IN_PROGRESS_MESSAGE);
+    const client = process.meta?.client as CodexAppClient | undefined;
+    const threadId = typeof process.meta?.threadId === "string" ? process.meta.threadId : "";
+    if (!client || !threadId) throw new Error(CODEX_TURN_IN_PROGRESS_MESSAGE);
+    // Codex's own default is STEER (the app-server `turn/steer` is additive); the config kill
+    // switch ("defer") waits until the turn ends. The default lives HERE, in the
+    // owning adapter — never a provider-name table (lint:provider-contract).
+    const softSteer = resolveActiveTurnMessageDelivery(this.spawnProviderConfig(process), "steer") === "steer";
+    const { steerable } = partitionMidTurnDelivery(messages);
+    const eligible = softSteer ? steerable : [];
+    // Nothing steerable (or this turn already refused steer): defer the whole batch. The once-
+    // per-turn notice keeps the ~1s runner retries from spamming the log.
+    if (eligible.length === 0 || this.steerDeniedForTurnId === steerTurnId) {
+      if (this.deferredForTurnId !== steerTurnId) {
+        this.deferredForTurnId = steerTurnId;
+        logger.info("codex", `holding ${messages.length} relay message${messages.length === 1 ? "" : "s"} behind active turn ${steerTurnId}; will deliver after it completes`);
+      }
+      throw new Error(CODEX_TURN_IN_PROGRESS_MESSAGE);
+    }
+    const clientUserMessageId = midTurnClientUserId(eligible);
+    // Acceptance reconcile: an earlier steer of this EXACT composition was positively accepted
+    // (the userMessage echo) but its response was lost — settle by correlation instead of
+    // re-steering a possible duplicate.
+    if (this.acceptedSteerClientIds.has(clientUserMessageId)) {
+      ctx?.inputObserver?.offered(Date.now(), true);
+      ctx?.inputObserver?.consumed();
+      logger.info("codex", `steer for Codex turn ${steerTurnId} was already accepted (clientId ${clientUserMessageId}); settling ${eligible.length} message${eligible.length === 1 ? "" : "s"} without re-steering`);
+      return eligible.map((message) => message.id);
+    }
+    // Transactional formatting state (#2539 design C): prepare the Relay context, send,
+    // and commit it ONLY on positive acceptance.
+    let steerText = [codexLaunchContext(process), providerMessageText(eligible)].filter(Boolean).join("\n\n");
+    let relayContextPending = false;
+    if (codexRelayContextEnabled(process) && !process.meta?.relayContextSent) {
+      steerText = codexRelayContextBlock(process) + "\n\n" + steerText;
+      relayContextPending = true;
+    }
+    logger.info("codex", `steering ${eligible.length} relay message${eligible.length === 1 ? "" : "s"} into active Codex turn ${steerTurnId}`);
+    try {
+      ctx?.inputObserver?.offered(Date.now(), true);
+      await client.turnSteer(threadId, steerTurnId, steerText, clientUserMessageId);
+      ctx?.inputObserver?.consumed();
+    } catch (error) {
+      const rejection = classifyTurnSteerRejection(error);
+      if (rejection === "not-steerable") {
+        // Review/compact turn: remember it for this turn id so later drains defer SILENTLY
+        // (no per-second refused RPC) and the batch delivers normally once the turn ends.
+        this.steerDeniedForTurnId = steerTurnId;
+        logger.info("codex", `active Codex turn ${steerTurnId} is not steerable (review/compact); deferring ${eligible.length} message${eligible.length === 1 ? "" : "s"} until it ends`);
+      } else if (rejection === "stale-turn") {
+        // The turn ended under us (or the id never matched): zero ack. The runner requeues the
+        // whole batch; once the cleared activeTurnId is observed, the offer takes turn/start.
+        logger.info("codex", `steer rejected against Codex turn ${steerTurnId} (no longer active); deferring until the provider is idle`);
+      } else if (rejection === "unknown-refusal") {
+        // Structured refusal we don't recognize (a future upstream kind, version skew): the
+        // app-server definitively REFUSED this steer, so the input was NOT accepted. Remember
+        // the turn id and defer — same shape as review/compact — instead of rethrowing into a
+        // ~1s refused-RPC hot loop for the rest of the turn. Delivers normally once it ends.
+        this.steerDeniedForTurnId = steerTurnId;
+        logger.warn("codex", `Codex turn ${steerTurnId} refused steer (unrecognized app-server rejection: ${errMessage(error)}); deferring ${eligible.length} message${eligible.length === 1 ? "" : "s"} until it ends`);
+      } else {
+        // Transport fault or 30s timeout — AMBIGUOUS acceptance. Zero ack; the runner requeues
+        // and the re-offer re-steers with the SAME clientId, reconciled by the echo if it lands.
+        throw error;
+      }
+      throw new Error(CODEX_TURN_IN_PROGRESS_MESSAGE);
+    }
+    if (relayContextPending) process.meta = { ...(process.meta ?? {}), relayContextSent: true };
+    this.rememberAcceptedSteerClient(clientUserMessageId);
+    return eligible.map((message) => message.id);
+  }
+
+  // The spawn config the adapter was launched with (meta.config is the RunnerSpawnConfig handed
+  // to spawn()); the steer policy reads its providerConfig — never a provider-name branch.
+  private spawnProviderConfig(process: ManagedProcess): ProviderConfig | undefined {
+    const config = process.meta?.config as { providerConfig?: ProviderConfig } | undefined;
+    return config?.providerConfig;
+  }
+
+  private rememberAcceptedSteerClient(clientId: string): void {
+    // Re-insert to refresh recency, then evict oldest-first past the cap.
+    this.acceptedSteerClientIds.delete(clientId);
+    this.acceptedSteerClientIds.add(clientId);
+    while (this.acceptedSteerClientIds.size > CODEX_STEER_ACCEPTED_CLIENT_CAP) {
+      const oldest = this.acceptedSteerClientIds.values().next().value;
+      if (oldest === undefined) break;
+      this.acceptedSteerClientIds.delete(oldest);
+    }
+  }
+
+  async respondToPermissionDecision(process: ManagedProcess, input: ProviderPermissionDecisionInput): Promise<Record<string, unknown>> {
+    const pending = this.pendingApprovals.get(input.approvalId);
+    if (!pending) throw new Error("approval request not found or already resolved");
+    const client = process.meta?.client as CodexAppClient | undefined;
+    if (!client) throw new Error("Codex App Server client is unavailable");
+    const response = codexApprovalResponse(pending.method, pending.params, input.decision);
+    // Always drop the pending entry: a failed send means the request is dead on
+    // the Codex side too, so a stale entry would only mislead later lookups.
+    try {
+      client.respondToServerRequest(pending.requestId, response);
+    } finally {
+      this.pendingApprovals.delete(input.approvalId);
+    }
+    this.statusCb({
+      status: "busy",
+      reason: "provider-turn",
+      providerState: {
+        state: "active",
+        reason: "permissionResolved",
+        label: "Codex approval resolved",
+        source: "codex",
+        updatedAt: Date.now(),
+      },
+    });
+    return { approvalId: input.approvalId, decision: input.decision, provider: "codex" };
+  }
+
+  configureTokenUsageReporter(reporter: ProviderTokenUsageReporter): void {
+    this.tokenUsageReporter = reporter;
+  }
+
+  buildSpawnArgs(config: RunnerSpawnConfig, providerConfig: ProviderConfig): SpawnArgs {
+    // #2719 — the fallback listen port is allocated, never derived: `controlPort + 1000`
+    // overflowed 65535 on a high ephemeral control port (macOS), which the app-server does not
+    // report as a bad port — it binds elsewhere and the client then polls a dead URL.
+    const appServerUrl = String(config.appServerUrl || process.env.CODEX_APP_SERVER_URL || `ws://127.0.0.1:${allocateLoopbackPort()}`);
+    // Create + bootstrap the isolated CODEX_HOME (no-op for host base) so the assembler's
+    // materialize step has somewhere to write the provisioned skills.
+    prepareCodexProfileHome(config);
+    // #557 — ONE assembler owns the provisioning/vanilla surface (skills.config, relay +
+    // provisioned -c mcp_servers.*, project_doc_max_bytes); profile-projection describes the
+    // SAME assembled result, so report == launch. The adapter only adds core launch config the
+    // assembler does not own: app-server wiring, model/approval/tool-output, managed flags, --listen.
+    const assembled = assembleLaunch("codex", config, providerConfig);
+    materializeLaunchAssembly("codex", config);
+    const defaultArgs = assembled.hostDefaultArgs;
+    const args = isCodexCliCommand(providerConfig.command)
+      ? [
+        "app-server",
+        ...codexAppServerConfigArgs(defaultArgs, config.providerArgs),
+        ...codexModelConfigArgs(config.model, config.effort),
+        ...codexApprovalConfigArgs(config.approvalMode),
+        ...codexToolOutputTokenLimitConfigArgs(config), ...codexHarnessConfigArgs(config), ...codexWebToolsConfigArgs(config),
+        ...assembled.args,
+        ...codexManagedConfigArgs(),
+        ...codexProjectShellConfigArgs(config.env, codexAppServerConfigArgs(defaultArgs, config.providerArgs), assembled.env.CODEX_HOME ?? config.env.CODEX_HOME),
+        "--listen",
+        appServerUrl,
+      ]
+      : [...defaultArgs, ...config.providerArgs];
+    return sanitizeLaunchBoundary({
+      command: providerConfig.command,
+      args,
+      cwd: config.cwd,
+      env: writeChildEnv({}, {
+        ...config.env,
+        // #557 — the assembler owns the isolated config-home env (CODEX_HOME).
+        ...assembled.env,
+        CODEX_APP_SERVER_URL: appServerUrl,
+        AGENT_RELAY_PROVIDER: "codex",
+      }),
+    });
+  }
+
+  private handleCodexEvent(event: ClientEvent, process?: ManagedProcess): void {
+    if (event.type === "server-request" && process) {
+      const approval = codexApprovalFromServerRequest(event.message);
+      if (approval) {
+        // #435/#723 ordering invariant: mirror every reasoning/narrative step of the turn
+        // BEFORE the approval form surfaces — the same guarantee Claude makes by pre-flushing
+        // the transcript at its hook seam, here enforced from the Codex app-server mechanism.
+        // approval.view.reasoningSettled === true asserts this flush has run.
+        this.agentMessageCapture.closeSegment((body) => this.emitAgentNarration(body));
+        this.flushBufferedReasoning();
+        this.pendingApprovals.set(approval.pending.id, approval.pending);
+        this.statusCb({
+          status: "busy",
+          reason: "provider-turn",
+          providerState: {
+            state: "blocked",
+            reason: "permissionRequest",
+            label: approval.view.title,
+            recommendedAction: "Review the permission request in Agent Relay.",
+            source: "codex",
+            pendingApproval: approval.view,
+            updatedAt: Date.now(),
+          },
+        });
+      } else if (event.message.method === CODEX_MCP_ELICITATION_METHOD && isCodexHeadless(process)) {
+        // Codex routes per-MCP-tool-call approval through the MCP elicitation channel
+        // (request_id `mcp_tool_call_approval_*`): even with `approval_policy="never"`, a
+        // downstream server's elicitation — or codex's own per-call approval gate — is
+        // forwarded to the app-server client as `mcpServer/elicitation/request`. A headless
+        // managed agent has no human to answer it; the old -32601 reject makes codex resolve
+        // the elicitation as `Decline`, so the MCP tool call dies with "user rejected MCP tool
+        // call" — stranding read-only recon/reviewer workers with no egress to report back
+        // over the bus (#395). The agent is already bounded by its scoped relay token + the
+        // codex sandbox, so auto-accept (spec-compliant `{ action: "accept" }`, not codex's
+        // legacy `{ decision: "approved" }`) so the agent's reporting/recon MCP tools run.
+        const client = process.meta?.client as CodexAppClient | undefined;
+        const serverName = isRecord(event.message.params) ? stringValue(event.message.params.serverName) : undefined;
+        logger.info("codex", `auto-accepting headless MCP elicitation from ${serverName ?? "unknown server"} so the agent's MCP tools can run (#395)`);
+        client?.respondToServerRequest(event.message.id, codexHeadlessElicitationResponse());
+      } else {
+        const client = process.meta?.client as CodexAppClient | undefined;
+        logger.warn("codex", `rejecting unknown Codex server-request method: ${event.message.method}`);
+        client?.rejectServerRequest(event.message.id, -32601, `Method not found: ${event.message.method}`, {
+          method: event.message.method,
+        });
+      }
+      return;
+    }
+
+    const method = event.type === "notification" ? event.message.method : "";
+    const params = event.type === "notification" ? event.message.params : undefined;
+    const thread = isRecord(params?.thread) ? params.thread : undefined;
+    const threadId = stringValue(params?.threadId) ?? stringValue(thread?.id);
+    const isSubagent = Boolean(threadId && this.subagentThreads.has(threadId)) || isSubagentThread(thread, params);
+
+    // clearContext has already installed a fresh thread id before late notifications from the
+    // discarded thread can arrive. Those old turn/status events must never clear or re-block the
+    // fresh session: doing so reopens the continuation-first race after the runner fenced it.
+    // A thread-less notification is still accepted because the app-server emits a few global
+    // lifecycle signals without a thread id.
+    const activeMainThreadId = process && typeof process.meta?.threadId === "string" ? process.meta.threadId : undefined;
+    if (threadId && activeMainThreadId && threadId !== activeMainThreadId && !isSubagent) return;
+
+    if (threadId && process && !isSubagent) {
+      const threadPath = stringValue(thread?.path) ?? stringValue(params?.path);
+      process.meta = {
+        ...(process.meta ?? {}),
+        threadId,
+        ...(threadPath ? { threadPath } : {}),
+      };
+    }
+
+    if (method.includes("thread/tokenUsage/updated") || method.includes("thread.tokenUsage.updated") || method.includes("thread/token_usage/updated") || method.includes("thread.token_usage.updated")) {
+      const context = codexTokenUsageContext(params);
+      if (context && process) process.meta = { ...(process.meta ?? {}), context };
+      reportCodexTokenUsage(params, threadId, process, this.tokenUsageReporter);
+    }
+
+    if ((method.includes("thread/started") || method.includes("thread.started")) && threadId && isSubagent) {
+      const details = subagentThreadDetails(thread, params);
+      this.subagentThreads.set(threadId, details);
+      this.statusCb({ status: "busy", reason: "subagent", id: threadId, ...details });
+      return;
+    }
+
+    if (method.includes("turn/started") || method.includes("turn.started")) {
+      if (threadId && this.subagentThreads.has(threadId)) {
+        this.statusCb({ status: "busy", reason: "subagent", id: threadId, ...this.subagentThreads.get(threadId) });
+      } else {
+        const turn = isRecord(params?.turn) ? params.turn : undefined;
+        this.activeTurnId = stringValue(turn?.id);
+        this.turnFailure = undefined;
+        this.agentMessageCapture.reset();
+        this.itemTextBuffers.clear();
+        this.itemTextBufferTypes.clear();
+        this.statusCb({ status: "busy", reason: "provider-turn", id: this.activeTurnId });
+      }
+    }
+    if (method.includes("turn/completed") || method.includes("turn.completed") || method.includes("turn/failed") || method.includes("turn.failed") || method.includes("turn/interrupted") || method.includes("turn.interrupted")) {
+      if (threadId && this.subagentThreads.has(threadId)) {
+        this.statusCb({ status: "idle", reason: "subagent", id: threadId, ...this.subagentThreads.get(threadId) });
+      } else {
+        const turn = isRecord(params?.turn) ? params.turn : undefined;
+        this.finishMainTurn(codexEndedByFrom(stringValue(turn?.status) ?? method), turn?.error ?? params?.error);
+      }
+    }
+    if (method === "error" && !isSubagent && params?.willRetry === false) this.finishMainTurn("failed", params.error);
+    if ((method.includes("thread/compacted") || method.includes("thread.compacted")) && threadId && process) {
+      this.onThreadCompacted(process, threadId, stringValue(params?.turnId), "manual");
+    }
+    if ((method.includes("item/completed") || method.includes("item.completed")) && !isSubagent) {
+      const item = isRecord(params?.item) ? params.item : undefined;
+      this.handleCodexItem(item);
+      // Codex compacts by itself only inside a live turn; a requested compaction runs with none.
+      if (codexItemIsCompactionComplete(item) && threadId && process) this.onThreadCompacted(process, threadId, stringValue(params?.turnId), this.pendingCompact || !this.activeTurnId ? "manual" : "auto");
+    }
+    if (!isSubagent) this.handleCodexItemDelta(method, params);
+    if (method.includes("thread/status") || method.includes("thread.status")) {
+      const status = statusType(params?.status);
+      if (threadId && this.subagentThreads.has(threadId)) {
+        if (status === "active") this.statusCb({ status: "busy", reason: "subagent", id: threadId, ...this.subagentThreads.get(threadId) });
+        if (status === "idle" || status === "notLoaded") this.statusCb({ status: "idle", reason: "subagent", id: threadId, ...this.subagentThreads.get(threadId) });
+      } else {
+        if (status === "active") this.statusCb({ status: "busy", reason: "provider-turn", providerState: this.providerStateFromThreadStatus(params?.status, params) });
+        if (status === "idle" || status === "notLoaded" || status === "systemError") this.finishMainTurn(codexEndedByFrom(status));
+      }
+    }
+  }
+
+  // Turn one completed Codex thread item into a session-mirror event. agentMessage text is
+  // mirrored as narration as it lands; the captured turn-final response repeats only the
+  // TRAILING agentMessage run — the segment after the last tool/file-change/reasoning
+  // boundary (design #1079 §3.2) — never earlier mid-work narration, which was already
+  // mirrored live. The rest (user prompt echo, reasoning, tool steps) is surfaced as it lands.
+  private handleCodexItem(item: Record<string, unknown> | undefined): void {
+    if (!item) return;
+    const type = stringValue(item.type);
+    const turnId = this.activeTurnId;
+    const itemId = codexItemId(item);
+    if (type !== "agentMessage") this.agentMessageCapture.closeSegment((body) => this.emitAgentNarration(body));
+    // A completed non-reasoning item ends the reasoning segment that preceded it — flush the
+    // buffered reasoning first so it lands in transcript order, ahead of this tool/message.
+    if (type !== "reasoning") this.flushBufferedReasoning();
+    if (type === "agentMessage") {
+      this.agentMessageCapture.completeItem(itemId, stringValue(item.text), (body) => this.emitAgentNarration(body), { phase: item.phase });
+      return;
+    }
+    if (type === "userMessage") {
+      // #2539 Phase A — the app-server echoes a steered input's clientUserMessageId as the
+      // item's clientId. Observing it is the POSITIVE acceptance evidence that reconciles an
+      // accepted-but-response-lost steer: the next offer of the same composition settles by
+      // correlation instead of re-steering.
+      const clientId = stringValue(item.clientId);
+      if (clientId) this.rememberAcceptedSteerClient(clientId);
+      const text = codexUserMessageText(item.content);
+      if (text) {
+        this.recordInsightEvent({ type: "user_prompt" });
+        this.sessionEventCb({ type: "prompt", origin: "terminal", body: text, ...(turnId ? { turnId } : {}) });
+      }
+      return;
+    }
+    if (type === "reasoning") {
+      // Codex has no reliable reasoning item/completed carrying text — the stream IS the deltas.
+      // Keep the longer of (accumulated deltas, item.content) in the buffer and emit at the next
+      // boundary (next item / turn end), the same coarse signal the Claude reasoning tail uses.
+      const fromItem = codexReasoningText(item);
+      if (itemId && fromItem) {
+        const existing = this.itemTextBuffers.get(itemId) ?? "";
+        if (fromItem.length >= existing.length) this.itemTextBuffers.set(itemId, fromItem);
+        this.itemTextBufferTypes.set(itemId, "reasoning");
+      }
+      return;
+    }
+    const tool = codexToolSummary(type, item, this.sessionCwd);
+    if (tool) {
+      this.recordInsightEvent({ type: "tool", name: codexInsightToolName(type, item) });
+      if (codexItemFailed(item)) this.recordInsightEvent({ type: "tool_error" });
+      // stepId = the app-server item id: the server upserts the running step emitted on
+      // item/started into this terminal state IN PLACE, so the tool persists as ONE row.
+      // #2354 — a FAILED item was previously hardcoded to status:"completed", so a tool that
+      // errored rendered identical to one that succeeded. `codexItemFailed` is the same
+      // failed-outcome predicate used for the insight proxy above; map it through to the shared
+      // `failed` status so every provider agrees on the contract.
+      this.sessionEventCb({ type: "tool", origin: "provider", body: tool.body, label: tool.label, category: codexToolCategory(type, item), status: codexItemFailed(item) ? "failed" : "completed", ...(turnId ? { turnId } : {}), ...(itemId ? { stepId: itemId } : {}), ...(tool.params !== undefined ? { params: tool.params } : {}) , ...(tool.paths ? { paths: tool.paths } : {}) });
+    }
+    if (itemId) this.itemTextBuffers.delete(itemId);
+    if (itemId) this.itemTextBufferTypes.delete(itemId);
+  }
+
+  private emitAgentNarration(body: string): void {
+    this.recordInsightEvent({ type: "turn" }); // a substantive assistant turn
+    // Stream the assistant text into the trace as narration (Claude parity). The closing
+    // response bubble at turn end repeats the final block; the dashboard suppresses the
+    // matching narration so it isn't shown twice.
+    this.sessionEventCb({ type: "narration", origin: "provider", body, ...(this.activeTurnId ? { turnId: this.activeTurnId } : {}) });
+  }
+
+  // Emit any buffered reasoning as discrete trace blocks (appended, in transcript order). Codex
+  // streams reasoning as deltas with no reliable completion event, so we flush coarsely at item
+  // and turn boundaries — the signal the Claude reasoning tail uses — never a codex-only timer.
+  private flushBufferedReasoning(): void {
+    const turnId = this.activeTurnId;
+    for (const [itemId, text] of [...this.itemTextBuffers.entries()]) {
+      if (this.itemTextBufferTypes.get(itemId) !== "reasoning") continue;
+      this.itemTextBuffers.delete(itemId);
+      this.itemTextBufferTypes.delete(itemId);
+      const body = text.trim();
+      if (body) this.sessionEventCb({ type: "reasoning", origin: "provider", body, ...(turnId ? { turnId } : {}) });
+    }
+  }
+
+  // #183/#184: append to the session-event log with a soft cap. On overflow we drop the
+  // oldest half; the runner detects the resulting length shrink and resets its segment
+  // cursor (worst case: one slightly-truncated datapoint on a pathologically long session).
+  private recordInsightEvent(event: SessionEvent): void {
+    this.sessionEvents.push(event);
+    if (this.sessionEvents.length > CodexAdapter.SESSION_EVENTS_CAP) {
+      this.sessionEvents = this.sessionEvents.slice(this.sessionEvents.length >> 1);
+    }
+  }
+
+  // Whole-session event stream for the Insights context-ratio signal (#184). Codex learns
+  // about activity through app-server item events, not a transcript, so we replay the log
+  // accumulated since this process started. The runner owns per-segment slicing.
+  async collectSessionEvents(): Promise<SessionEvent[] | null> {
+    return [...this.sessionEvents];
+  }
+
+  // #653: Codex busy-state normally flips on turn/started, but the app-server can stream
+  // item activity (which already drives the dashboard chat mirror) before — or without —
+  // a turn/started reaching us, leaving a visibly-working agent reported `idle` (a reap
+  // hazard). Derive busy from that SAME live activity: any in-flight item event with no
+  // active turn means a turn IS running we missed, so synthesize one and report busy.
+  // turn/completed → finishMainTurn clears it; we never synthesize on a closing
+  // item.completed, so a legitimately ended turn is not re-flipped to busy.
+  private ensureMainTurnActive(turnId?: string): void {
+    if (this.activeTurnId) return;
+    this.turnFailure = undefined;
+    this.activeTurnId = turnId ?? `codex-synth-turn-${++this.syntheticTurnSeq}`;
+    this.statusCb({ status: "busy", reason: "provider-turn", id: this.activeTurnId });
+  }
+
+  private handleCodexItemDelta(method: string, params: Record<string, unknown> | undefined): void {
+    if (!method.includes("item/") && !method.includes("item.")) return;
+    // Live item stream (start/delta/progress) = a turn in flight. A closing
+    // item.completed is handled by handleCodexItem and must not synthesize a turn.
+    if (!method.includes("/completed") && !method.includes(".completed")) {
+      this.ensureMainTurnActive(stringValue(params?.turnId));
+    }
+    const item = isRecord(params?.item) ? params.item : undefined;
+    const itemId = codexItemId(params) ?? codexItemId(item);
+    const type = codexItemTypeFromMethod(method) ?? stringValue(item?.type);
+    const turnId = this.activeTurnId;
+
+    if (method.includes("/started") || method.includes(".started")) {
+      if (type !== "agentMessage") this.agentMessageCapture.closeSegment((body) => this.emitAgentNarration(body));
+      // A new item starting ends the prior reasoning segment — flush it ahead of this step.
+      this.flushBufferedReasoning();
+      const tool = codexToolSummary(type, item ?? params ?? {}, this.sessionCwd);
+      // stepId = item id so the server upserts this running step → completed IN PLACE (one row).
+      if (tool) this.sessionEventCb({ type: "tool", origin: "provider", body: tool.body, label: tool.label, category: codexToolCategory(type, item ?? params ?? {}), status: "running", streaming: true, ...(turnId ? { turnId } : {}), ...(itemId ? { stepId: itemId } : {}), ...(tool.params !== undefined ? { params: tool.params } : {}) , ...(tool.paths ? { paths: tool.paths } : {}) });
+      return;
+    }
+
+    if (type === "agentMessage") {
+      const delta = codexDeltaText(params);
+      if (delta) this.agentMessageCapture.appendDelta(itemId, delta);
+      return;
+    }
+
+    if (type === "reasoning" || type === "plan") {
+      this.agentMessageCapture.closeSegment((body) => this.emitAgentNarration(body));
+      const delta = codexDeltaText(params);
+      if (delta && itemId) {
+        this.itemTextBuffers.set(itemId, `${this.itemTextBuffers.get(itemId) ?? ""}${delta}`);
+        if (type) this.itemTextBufferTypes.set(itemId, type);
+      }
+      return;
+    }
+
+    // Raw stdout/stderr deltas can be huge. Surface the tool lifecycle via started/completed
+    // summaries only; never persist raw process output into the chat mirror.
+    if (method.includes("outputDelta") || method.includes("output_delta") || method.includes("progress")) return;
+  }
+
+  // A turn-final capture is emitted ONLY for a genuine `completed` turn (design #1079 §3.2):
+  // failed/interrupted turns must never produce a turn-final. Every "response"-type
+  // ProviderSessionEvent is unconditionally dual-stamped turnFinal/final downstream
+  // (publishCapturedResponse's provider-agnostic stamp), so the only way to keep a
+  // failed/interrupted partial OUT of D's work-final ring is to never emit it as a
+  // "response" event at all (#1083 Finding 1). The partial text was already mirrored live
+  // as narration by the `emit` callback inside agentMessageCapture.finish(), so it's still
+  // visible in the dashboard.
+  private flushTurnResponse(endedBy: MessageTurnEndReason): void {
+    const text = this.agentMessageCapture.finish((body) => this.emitAgentNarration(body));
+    if (!text || endedBy !== "completed") return;
+    this.sessionEventCb({ type: "response", origin: "provider", body: text, final: true, confidence: "definitive", endedBy, ...(this.activeTurnId ? { turnId: this.activeTurnId } : {}) });
+  }
+
+  private finishMainTurn(endedBy: MessageTurnEndReason, error?: unknown): void {
+    if (endedBy === "failed" && (!this.turnFailure || error)) this.turnFailure = codexTurnFailure(error, this.activeTurnId);
+    this.flushBufferedReasoning(); // surface any trailing reasoning before the closing response
+    this.flushTurnResponse(endedBy);
+    const turnId = this.activeTurnId;
+    this.activeTurnId = undefined;
+    this.pendingApprovals.clear();
+    this.itemTextBuffers.clear();
+    this.itemTextBufferTypes.clear();
+    this.agentMessageCapture.reset();
+    this.statusCb(this.turnFailure ?? { status: "idle", reason: "provider-turn", id: turnId });
+  }
+
+  private waitForPendingCompact(threadId: string): Promise<void> {
+    if (this.pendingCompact) throw new Error("Codex compact is already in progress");
+    return new Promise<void>((resolve, reject) => {
+      const pending: PendingCodexCompact = {
+        threadId,
+        resolve,
+        reject,
+        timeout: setTimeout(() => {
+          if (this.pendingCompact !== pending) return;
+          this.pendingCompact = undefined;
+          reject(new Error(`Codex compact timed out after ${Math.round(CODEX_COMPACT_TIMEOUT_MS / 1000)}s`));
+        }, CODEX_COMPACT_TIMEOUT_MS),
+      };
+      this.pendingCompact = pending;
+    });
+  }
+
+  private completePendingCompact(threadId: string): boolean {
+    const pending = this.pendingCompact;
+    if (!pending || pending.threadId !== threadId) return false;
+    clearTimeout(pending.timeout);
+    this.pendingCompact = undefined;
+    pending.resolve();
+    return true;
+  }
+
+  private clearPendingCompact(threadId?: string): void {
+    const pending = this.pendingCompact;
+    if (!pending || (threadId && pending.threadId !== threadId)) return;
+    clearTimeout(pending.timeout);
+    this.pendingCompact = undefined;
+  }
+
+  private cancelPendingCompact(error: Error): void {
+    const pending = this.pendingCompact;
+    if (!pending) return;
+    clearTimeout(pending.timeout);
+    this.pendingCompact = undefined;
+    pending.reject(error);
+  }
+
+  private providerStateFromThreadStatus(status: unknown, params?: Record<string, unknown>): ProviderState | undefined {
+    const state = codexProviderStateFromThreadStatus(status, params);
+    if (state?.state !== "blocked" || state.reason !== "waitingOnApproval" || state.pendingApproval) return state;
+    const pending = [...this.pendingApprovals.values()].at(-1);
+    return pending ? { ...state, pendingApproval: pending.view } : state;
+  }
+}
+
+function codexItemId(item: Record<string, unknown> | undefined): string | undefined {
+  return stringValue(item?.itemId) ?? stringValue(item?.id);
+}
+
+function codexItemIsCompactionComplete(item: Record<string, unknown> | undefined): boolean {
+  const type = stringValue(item?.type);
+  return type === "context_compaction" || type === "contextCompaction" || type === "compaction";
+}
+
+function codexDeltaText(params: Record<string, unknown> | undefined): string {
+  const delta = params?.delta;
+  if (typeof delta === "string") return delta;
+  if (isRecord(delta)) {
+    const text = stringValue(delta.text) ?? stringValue(delta.value) ?? stringValue(delta.content);
+    if (text) return text;
+  }
+  return stringValue(params?.text) ?? stringValue(params?.chunk) ?? stringValue(params?.content) ?? "";
+}
+
+function codexItemTypeFromMethod(method: string): string | undefined {
+  const match = method.match(/item[/.]([^/.]+)[/.]/);
+  return match?.[1];
+}
+
+// Codex forwards MCP elicitation (incl. its per-tool-call approval gate) to the app-server
+// client under this server-request method (#395). See handleCodexEvent for why a headless
+// agent must answer it instead of rejecting it.
+export const CODEX_MCP_ELICITATION_METHOD = "mcpServer/elicitation/request";
+
+// A managed agent with no attended TUI (the spawn intent, `config.headless`) has no human to
+// resolve an elicitation. Such agents are the #395 case; interactive (TUI) sessions leave the
+// elicitation to the human in the attached terminal.
+function isCodexHeadless(process: ManagedProcess): boolean {
+  return (process.meta?.config as RunnerSpawnConfig | undefined)?.headless === true;
+}
+
+// Spec-compliant auto-accept for a headless agent's MCP elicitation. `action` (not codex's
+// legacy `decision`) is the load-bearing field; `content: {}` approves codex's per-tool-call
+// gate and any no-required-field form without fabricating runtime field values for the agent.
+export function codexHeadlessElicitationResponse(): Record<string, unknown> {
+  return { action: "accept", content: {}, _meta: null };
+}
+
+function codexApprovalFromServerRequest(message: { id: string | number; method: string; params?: unknown }): { pending: PendingCodexApproval; view: InteractivePrompt } | null {
+  if (!isRecord(message.params)) return null;
+  const method = message.method;
+  if (!codexApprovalMethod(method)) return null;
+  const id = `${method}:${String(message.id)}`;
+  const view = codexApprovalView(id, method, message.params);
+  return {
+    pending: { id, requestId: message.id, method, params: message.params, view },
+    view,
+  };
+}
+
+/** Extract the human text from a Codex userMessage item's content (UserInput[]). */
+export function codexUserMessageText(content: unknown): string {
+  if (typeof content === "string") return content.trim();
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter(isRecord)
+    .filter((part) => part.type === "text" || part.type === "input_text" || part.type === "output_text")
+    .map((part) => (typeof part.text === "string" ? part.text : ""))
+    .filter(Boolean)
+    .join("")
+    .trim();
+}
+
+/** Extract reasoning text from a Codex reasoning item (content[] preferred, summary[] fallback). */
+export function codexReasoningText(item: Record<string, unknown>): string {
+  const stringsOf = (value: unknown): string[] =>
+    Array.isArray(value) ? value.filter((v): v is string => typeof v === "string" && v.trim().length > 0) : [];
+  const content = stringsOf(item.content);
+  const text = (content.length ? content : stringsOf(item.summary)).join("\n\n").trim();
+  return text;
+}
+
+/** Build a compact { label, body } activity summary for a Codex tool item. */
+// Canonical tool name for the #184 gathering/action classifier. Codex item types map to
+// names the shared classifier already understands: commandExecution executes (→ Bash, an
+// action), fileChange mutates (→ Edit), webSearch gathers (→ WebSearch, in the set), and
+// MCP/dynamic calls carry their real tool name so name-shape classification applies.
+export function codexInsightToolName(type: string | undefined, item: Record<string, unknown>): string {
+  switch (type) {
+    case "commandExecution": return "Bash";
+    case "fileChange": return "Edit";
+    case "webSearch": return "WebSearch";
+    case "mcpToolCall":
+    case "dynamicToolCall":
+    case "collabAgentToolCall":
+      return stringValue(item.tool) ?? type ?? "tool";
+    default: return type ?? "tool";
+  }
+}
+
+// #1498: Codex app-server item types → the provider-independent category taxonomy. Codex has
+// no MCP-tool-search or native read/ask-user-question item, so it simply never emits those
+// categories; webSearch and any other/future item type fall to "generic" rather than being
+// force-fit — the fallback exists precisely so nothing is hidden from the activity trace.
+// dynamicToolCall is a distinct client-provided dynamic tool (not MCP) so it falls to the
+// default generic case; collabAgentToolCall covers several collab ops (sendInput, resumeAgent,
+// wait, closeAgent, ...) and only the spawnAgent op is actually an agent spawn.
+export function codexToolCategory(type: string | undefined, item: Record<string, unknown>): ToolCallCategory {
+  switch (type) {
+    case "commandExecution": return "cli-bash";
+    case "fileChange": return "edit";
+    case "mcpToolCall": return "mcp-tool-call";
+    case "collabAgentToolCall": return stringValue(item.tool) === "spawnAgent" ? "agent-spawn" : "generic";
+    case "plan": return "plan";
+    default: return "generic";
+  }
+}
+
+// Did a completed tool item fail? Mirrors Claude's tool_result is_error outcome proxy.
+export function codexItemFailed(item: Record<string, unknown>): boolean {
+  if (stringValue(item.status) === "failed") return true;
+  if (item.error != null && item.error !== false) return true;
+  const exitCode = item.exitCode ?? item.exit_code;
+  return typeof exitCode === "number" && exitCode !== 0;
+}
+
+export function codexToolSummary(type: string | undefined, item: Record<string, unknown>, cwd?: string): { label: string; body: string; params?: unknown; paths?: string[] } | null {
+  // One-line + redact + clip is the shared `tool-summary.ts` primitive (Claude/OpenCode parity);
+  // only Codex's per-item-type field mapping lives here. `params` (#2437) reuses the same raw
+  // field each branch already extracted for its one-line body, redacted+capped separately for
+  // the trace's expandable detail — the one-line label stays exactly as it was.
+  const oneLine = oneLineText, clip = clipToolSummary, params = redactAndCapParams;
+  if (type === "commandExecution") {
+    const command = oneLine(item.command), paths = codexReadPaths(item, cwd);
+    return { label: "Shell", body: clip(command || "command"), params: params(item.command), ...(paths ? { paths } : {}) };
+  }
+  if (type === "fileChange") {
+    const changes = Array.isArray(item.changes) ? item.changes.filter(isRecord) : [];
+    const files = changes.map((c) => stringValue(c.path) ?? stringValue(c.file) ?? "").filter(Boolean);
+    const paths = absoluteToolPaths(files, cwd); // #3411 — from the raw changes, never the capped params
+    return { label: "Edit", body: clip(files.length ? files.join(", ") : "file changes"), params: params(item.changes), ...(paths ? { paths } : {}) };
+  }
+  if (type === "mcpToolCall" || type === "dynamicToolCall") {
+    const tool = stringValue(item.tool) ?? "tool";
+    const server = stringValue(item.server) ?? stringValue(item.namespace);
+    return { label: server ? `${server}/${tool}` : tool, body: clip(oneLine(JSON.stringify(item.arguments ?? {})) || tool), params: params(item.arguments) };
+  }
+  if (type === "webSearch") {
+    return { label: "Search", body: clip(oneLine(item.query) || "web search"), params: params(item.query) };
+  }
+  if (type === "plan") {
+    return { label: "Plan", body: clip(oneLine(item.text) || "updated plan"), params: params(item.text) };
+  }
+  if (type === "collabAgentToolCall") {
+    const tool = stringValue(item.tool) ?? "collab";
+    const prompt = oneLine(item.prompt);
+    const targets = Array.isArray(item.receiverThreadIds)
+      ? item.receiverThreadIds.filter((t): t is string => typeof t === "string").length
+      : 0;
+    const detail = prompt || (targets ? `${targets} agent${targets === 1 ? "" : "s"}` : tool);
+    return { label: `Collab/${tool}`, body: clip(detail), params: params(item.prompt) };
+  }
+  // reasoning/agentMessage/userMessage are handled earlier in the event stream and never reach
+  // here as a "tool" item — those genuinely aren't tool activity, so they stay null.
+  if (type === "reasoning" || type === "agentMessage" || type === "userMessage") return null;
+  // Any other/future Codex tool item type still gets a minimal summary rather than being
+  // dropped — the "nothing dropped, unknown→generic" guarantee must hold even here.
+  return { label: type ?? "Tool", body: clip(type ?? "tool") };
+}
+
+function codexApprovalMethod(method: string): boolean {
+  return method === "execCommandApproval" ||
+    method === "applyPatchApproval" ||
+    method === "item/commandExecution/requestApproval" ||
+    method === "item/fileChange/requestApproval" ||
+    method === "item/permissions/requestApproval";
+}
+
+// Build the normalized InteractivePrompt for a Codex app-server approval request.
+// reasoningSettled is stamped `true` because handleCodexEvent flushes buffered reasoning +
+// any open narration segment BEFORE this view is emitted as pendingApproval (#435/#723). No
+// `provider` tag — the server reads the typed contract, not provider identity.
+function codexApprovalView(id: string, method: string, params: Record<string, unknown>): InteractivePrompt {
+  const command = typeof params.command === "string" ? params.command
+    : Array.isArray(params.command) ? params.command.filter((v): v is string => typeof v === "string").join(" ")
+    : "";
+  const cwd = stringValue(params.cwd) ?? stringValue(params.conversationId) ?? stringValue(params.threadId);
+  const reason = stringValue(params.reason);
+  const grantRoot = stringValue(params.grantRoot);
+  const fileChanges = isRecord(params.fileChanges) ? Object.keys(params.fileChanges) : [];
+  const permissions = isRecord(params.permissions) ? params.permissions : undefined;
+  const body = [
+    command,
+    grantRoot ? `Grant write access: ${grantRoot}` : "",
+    fileChanges.length ? `Files: ${fileChanges.join(", ")}` : "",
+    permissions ? `Permissions: ${JSON.stringify(permissions)}` : "",
+    reason ? `Reason: ${reason}` : "",
+    cwd ? `Context: ${cwd}` : "",
+  ].filter(Boolean).join("\n");
+  const isSessionCapable = method !== "item/permissions/requestApproval";
+  return {
+    id,
+    kind: method.includes("file") || method === "applyPatchApproval" ? "file-change" : method.includes("permission") ? "permission" : "command",
+    title: method.includes("file") || method === "applyPatchApproval"
+      ? "Approve file changes"
+      : method.includes("permission")
+        ? "Approve extra permissions"
+        : "Approve command",
+    body: body || "Codex is requesting permission.",
+    choices: [
+      { id: "approve", label: method.includes("permission") ? "Allow this turn" : "Approve" },
+      ...(isSessionCapable ? [{ id: "approve-session", label: "Approve session" }] : [{ id: "approve-session", label: "Allow session" }]),
+      { id: "deny", label: "Deny" },
+    ],
+    reasoningSettled: true,
+  };
+}
+
+function codexApprovalResponse(method: string, params: Record<string, unknown>, decision: ProviderPermissionDecisionInput["decision"]): Record<string, unknown> {
+  if (method === "item/commandExecution/requestApproval") {
+    return { decision: decision === "approve-session" ? "acceptForSession" : decision === "deny" ? "decline" : decision === "abort" ? "cancel" : "accept" };
+  }
+  if (method === "item/fileChange/requestApproval") {
+    return { decision: decision === "approve-session" ? "acceptForSession" : decision === "deny" ? "decline" : decision === "abort" ? "cancel" : "accept" };
+  }
+  if (method === "item/permissions/requestApproval") {
+    const permissions = decision === "deny" || decision === "abort" ? {} : isRecord(params.permissions) ? params.permissions : {};
+    return { permissions, scope: decision === "approve-session" ? "session" : "turn" };
+  }
+  return { decision: decision === "approve-session" ? "approved_for_session" : decision === "deny" ? "denied" : decision === "abort" ? "abort" : "approved" };
+}
+
+async function ensureCodexThread(process: ManagedProcess): Promise<string> {
+  const client = process.meta?.client as CodexAppClient | undefined;
+  if (!client) throw new Error("Codex App Server client is unavailable");
+  const threadId = typeof process.meta?.threadId === "string" ? process.meta.threadId : "";
+  if (threadId) return threadId;
+  // Memoize the in-flight start so concurrent deliveries don't create two threads
+  // and orphan the first turn's context.
+  const pending = process.meta?.threadStartPromise as Promise<string> | undefined;
+  if (pending) return pending;
+  const startPromise = client
+    .threadStart({ cwd: typeof process.meta?.cwd === "string" ? process.meta.cwd : globalThis.process.cwd() })
+    .then((started) => {
+      process.meta = { ...(process.meta ?? {}), threadId: started.thread.id, threadStartPromise: undefined };
+      return started.thread.id;
+    })
+    .catch((error) => {
+      if (process.meta) process.meta.threadStartPromise = undefined;
+      throw error;
+    });
+  process.meta = { ...(process.meta ?? {}), threadStartPromise: startPromise };
+  return startPromise;
+}
+
+export function codexDeliveryNotice(messages: Message[], threadId: string): string {
+  const ids = messages.map((message) => `#${message.id}`).join(", ");
+  const senders = [...new Set(messages.map((message) => message.from))].join(", ");
+  return `[agent-relay] received ${messages.length} relay message${messages.length === 1 ? "" : "s"} ${ids} from ${senders}; injecting into Codex thread ${threadId}`;
+}
+
+export function codexProviderStateFromThreadStatus(status: unknown, params?: Record<string, unknown>, now = Date.now()): ProviderState | undefined {
+  const type = statusType(status);
+  const flags = activeFlags(status);
+  const threadId = stringValue(params?.threadId) ?? (isRecord(params?.thread) ? stringValue(params.thread.id) : undefined);
+  const raw = { ...(threadId ? { threadId } : {}), status: isRecord(status) ? status : { type } };
+  const reason = flags[0] ?? type;
+
+  if (type === "active" && flags.some((flag) => flag.toLowerCase() === "waitingonapproval")) {
+    return {
+      state: "blocked",
+      reason: "waitingOnApproval",
+      label: "waiting for Codex approval",
+      recommendedAction: "Open the attached TUI to approve, or restart with non-interactive approval.",
+      source: "codex",
+      raw,
+      updatedAt: now,
+    };
+  }
+
+  if (type === "active" && flags.some((flag) => flag.toLowerCase().includes("auth"))) {
+    return {
+      state: "blocked",
+      reason: "authRequired",
+      label: "Codex authentication required",
+      recommendedAction: "Open the provider session and complete authentication, then retry.",
+      source: "codex",
+      raw,
+      updatedAt: now,
+    };
+  }
+
+  if (type === "systemError") {
+    return {
+      state: "blocked",
+      reason: "systemError",
+      label: "Codex system error",
+      recommendedAction: "View provider logs, then restart the provider if the error is not transient.",
+      source: "codex",
+      raw,
+      updatedAt: now,
+    };
+  }
+
+  if (type === "active") {
+    return {
+      state: "active",
+      reason,
+      label: flags.length ? `Codex active: ${flags.join(", ")}` : "Codex turn active",
+      source: "codex",
+      raw,
+      updatedAt: now,
+    };
+  }
+
+  return undefined;
+}
+
+function isSubagentThread(thread: Record<string, unknown> | undefined, params: Record<string, unknown> | undefined): boolean {
+  if (thread?.threadSource === "subagent" || params?.threadSource === "subagent") return true;
+  const source = isRecord(thread?.sessionSource) ? thread.sessionSource : isRecord(params?.sessionSource) ? params.sessionSource : undefined;
+  return isRecord(source?.subagent);
+}
+
+function subagentThreadDetails(thread: Record<string, unknown> | undefined, params: Record<string, unknown> | undefined): { label?: string; role?: string; parentId?: string } {
+  const source = isRecord(thread?.sessionSource) ? thread.sessionSource : isRecord(params?.sessionSource) ? params.sessionSource : undefined;
+  const subagent = isRecord(source?.subagent) ? source.subagent : undefined;
+  const threadSpawn = isRecord(subagent?.thread_spawn) ? subagent.thread_spawn : undefined;
+  return {
+    label: stringValue(thread?.agentNickname) ?? stringValue(params?.agentNickname) ?? stringValue(threadSpawn?.agent_nickname),
+    role: stringValue(thread?.agentRole) ?? stringValue(params?.agentRole) ?? stringValue(threadSpawn?.agent_role),
+    parentId: stringValue(threadSpawn?.parent_thread_id) ?? stringValue(params?.parentThreadId),
+  };
+}
+
+function statusType(value: unknown): string | undefined {
+  if (typeof value === "string") return value;
+  return isRecord(value) ? stringValue(value.type) : undefined;
+}
+
+function activeFlags(value: unknown): string[] {
+  if (!isRecord(value) || !Array.isArray(value.activeFlags)) return [];
+  return value.activeFlags.filter((flag): flag is string => typeof flag === "string" && flag.length > 0);
+}
+
+// #557 — bundledCodexSkillDirs + bundledSkillConfigArgs now live in ../launch-assembly
+// (the single launch-arg home, shared with the assembler); re-exported so existing
+// codex.ts consumers + tests keep their import path. tomlString likewise from ../relay-mcp.
+export { bundledCodexSkillDirs, bundledSkillConfigArgs };
+// Rollout/token-usage context parsing lives in ./codex-rollout-context; re-exported
+// so codex.ts consumers + tests keep their import path.
+export { codexTokenUsageContext, codexRolloutContextFromText } from "./codex-rollout-context";
+
+function codexRelayContextEnabled(process: ManagedProcess): boolean {
+  const config = process.meta?.config as RunnerSpawnConfig | undefined;
+  return resolveRelayContext({ slug: "relay.context.codex", config }).available;
+}
+
+// Exported for integration coverage (#462): Codex has no `--append-system-prompt`
+// flag — the composed systemPromptAppend rides in as the launch-context message
+// prepended to the first turn. This is the Codex twin of Claude's append arg.
+export function codexLaunchContext(process: ManagedProcess): string | undefined {
+  const config = process.meta?.config as RunnerSpawnConfig | undefined;
+  const text = [config?.systemPromptAppend && sanitizeLaunchText(config.systemPromptAppend, "systemPromptAppend").trim(), ...(config && !harnessSubagentsEnabled(config) ? [HARNESS_SUBAGENTS_DISABLED] : [])].filter(Boolean).join("\n\n");
+  if (!text || process.meta?.systemPromptAppendSent) return undefined;
+  process.meta = { ...(process.meta ?? {}), systemPromptAppendSent: true };
+  return [
+    "[agent-relay launch context]",
+    "The following context was attached when this provider session was launched. Treat it as background context, not as a user request and not as your own prior actions.",
+    text,
+  ].join("\n");
+}