agent-relay-server 0.121.5 → 0.122.1

package/runner/src/adapters/codex.ts

@@ -0,0 +1,1345 @@
+import { accessSync, constants, existsSync, readFileSync, realpathSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import type { ContextState, InteractivePrompt, LivenessSignal, Message, ProviderState } from "agent-relay-sdk";
+import { isRecord, stringValue } from "agent-relay-sdk";
+import { isPidAlive, killPid, processTreePids, processTreePidsFromTable, waitForPidsExit } from "agent-relay-sdk/process-utils";
+import { profileAllowsRelayFeature, providerMessageText, relayContext, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderPermissionDecisionInput, type ProviderSessionEvent, type ProviderStatusUpdate, type RunnerSpawnConfig, type SpawnArgs, type TerminalAttachSpec } from "../adapter";
+import { workspaceDepsNoteFromEnv } from "../relay-instructions";
+import { tomlString } from "../relay-mcp";
+import { assembleLaunch, bundledCodexSkillDirs, bundledSkillConfigArgs, materializeLaunchAssembly } from "../launch-assembly";
+import { logger } from "../logger";
+import type { SessionEvent } from "../session-insights";
+import { CodexAgentMessageCapture } from "./codex-agent-message-capture";
+import { computeLivenessSignal, type LivenessInputs } from "../liveness";
+
+/** 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(): string {
+  return [relayContext(), workspaceDepsNoteFromEnv()].filter(Boolean).join("\n\n");
+}
+import { prepareCodexProfileHome, profileUsesHostProviderGlobals } from "../profile-home";
+import { CodexAppClient, type ClientEvent } from "./codex-client";
+
+export { processTreePidsFromTable };
+export const DEFAULT_CODEX_TOOL_OUTPUT_TOKEN_LIMIT = 12_000;
+
+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;
+
+export class CodexAdapter implements ProviderAdapter {
+  readonly provider = "codex";
+  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;
+  // #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;
+  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;
+
+  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.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();
+        return "idle";
+      }
+      const threadStatus = statusType(thread?.status);
+      if (threadStatus === "active") return "busy";
+      if (threadStatus === "idle" || threadStatus === "notLoaded" || threadStatus === "systemError") {
+        this.finishMainTurn();
+        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();
+    const args = this.buildSpawnArgs(config, config.providerConfig as ProviderConfig);
+    const appServer = Bun.spawn([args.command, ...args.args], {
+      cwd: args.cwd,
+      env: args.env,
+      stdin: "ignore",
+      stdout: "inherit",
+      stderr: "inherit",
+    });
+    const appServerUrl = String(config.appServerUrl || args.env.CODEX_APP_SERVER_URL || "");
+    const client = appServerUrl ? new CodexAppClient(appServerUrl, () => {}) : undefined;
+    if (client) {
+      await connectWithRetry(client);
+      await client.initialize().catch(() => undefined);
+    }
+
+    const relaySkillArgs = profileAllowsRelayFeature(config, "skills") ? bundledSkillConfigArgs() : [];
+    const defaultArgs = profileUsesHostProviderGlobals(config) ? config.providerConfig.defaultArgs : [];
+    const tui = !config.headless && isCodexCliCommand(config.providerConfig.command)
+      ? Bun.spawn([config.providerConfig.command, "--remote", appServerUrl, ...relaySkillArgs, ...defaultArgs, ...config.providerArgs, ...codexManagedConfigArgs()], {
+        cwd: config.cwd,
+        env: args.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"));
+    if (tui) void tui.exited.then((code) => reportExit(code === 0 ? "idle" : "error"));
+    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<void> {
+    const client = process.meta?.client as CodexAppClient | undefined;
+    client?.close();
+    await terminateProcessTree(process, 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;
+    }
+    const compactedAt = Date.now();
+    const compactingContext = isContextState(process.meta?.context) ? process.meta.context : currentContext;
+    if (compactingContext) {
+      process.meta = {
+        ...(process.meta ?? {}),
+        context: {
+          ...compactingContext,
+          lifecycleState: "cooling",
+          tasksSinceCompact: 0,
+          lastCompactedAt: compactedAt,
+          lastUpdatedAt: compactedAt,
+        },
+      };
+    }
+    this.statusCb({ status: "idle", reason: "provider-turn", timeline: { status: "compacted", timestamp: compactedAt } });
+    return { 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: {
+        utilization: 0,
+        lifecycleState: "fresh",
+        warmTopics: [],
+        activeMemories: [],
+        tasksSinceCompact: 0,
+        lastCompactedAt: clearedAt,
+        lastUpdatedAt: clearedAt,
+        source: "api",
+        confidence: "reported",
+      } satisfies ContextState,
+    };
+    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, "--no-alt-screen"],
+      title: `Codex ${threadId.slice(0, 8)}`,
+      ttlMs: 60 * 60 * 1000,
+    };
+  }
+
+  async deliverInitialPrompt(process: ManagedProcess, prompt: string, _options?: { readyTimeoutMs?: number }): Promise<void> {
+    const text = prompt.trim(); // _options.readyTimeoutMs (#329) is a Claude-TUI concern; ignored here
+    if (!text) return;
+    const threadId = await ensureCodexThread(process);
+    let input = [
+      codexLaunchContext(process),
+      "[agent-relay initial prompt from dashboard]",
+      text,
+    ].filter(Boolean).join("\n\n");
+    if (codexRelayContextEnabled(process) && !process.meta?.relayContextSent) {
+      input = codexRelayContextBlock() + "\n\n" + input;
+      process.meta = { ...(process.meta ?? {}), relayContextSent: true };
+    }
+    logger.info("codex", `starting Codex initial prompt in thread ${threadId}`);
+    const client = process.meta?.client as CodexAppClient;
+    await client.turnStart(threadId, input);
+  }
+
+  async deliver(process: ManagedProcess, messages: Message[]): Promise<void> {
+    const threadId = await ensureCodexThread(process);
+    let text = [codexLaunchContext(process), providerMessageText(messages)].filter(Boolean).join("\n\n");
+    if (codexRelayContextEnabled(process) && !process.meta?.relayContextSent) {
+      text = codexRelayContextBlock() + "\n\n" + text;
+      process.meta = { ...(process.meta ?? {}), relayContextSent: true };
+    }
+    logger.info("codex", codexDeliveryNotice(messages, threadId));
+    const client = process.meta?.client as CodexAppClient;
+    await client.turnStart(threadId, text);
+  }
+
+  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" };
+  }
+
+  buildSpawnArgs(config: RunnerSpawnConfig, providerConfig: ProviderConfig): SpawnArgs {
+    const appServerUrl = String(config.appServerUrl || process.env.CODEX_APP_SERVER_URL || `ws://127.0.0.1:${config.controlPort + 1000}`);
+    // 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);
+    const defaultArgs = profileUsesHostProviderGlobals(config) ? providerConfig.defaultArgs : [];
+    // #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 args = isCodexCliCommand(providerConfig.command)
+      ? [
+        "app-server",
+        ...codexAppServerConfigArgs(defaultArgs, config.providerArgs),
+        ...codexModelConfigArgs(config.model, config.effort),
+        ...codexApprovalConfigArgs(config.approvalMode),
+        ...codexToolOutputTokenLimitConfigArgs(config),
+        ...assembled.args,
+        ...codexManagedConfigArgs(),
+        "--listen",
+        appServerUrl,
+      ]
+      : [...defaultArgs, ...config.providerArgs];
+    return {
+      command: providerConfig.command,
+      args,
+      cwd: config.cwd,
+      env: {
+        ...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);
+
+    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 };
+    }
+
+    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.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 {
+        this.finishMainTurn();
+      }
+    }
+    if ((method.includes("thread/compacted") || method.includes("thread.compacted")) && threadId) {
+      this.completePendingCompact(threadId);
+    }
+    if ((method.includes("item/completed") || method.includes("item.completed")) && !isSubagent) {
+      const item = isRecord(params?.item) ? params.item : undefined;
+      this.handleCodexItem(item);
+      if (codexItemIsCompactionComplete(item) && threadId) this.completePendingCompact(threadId);
+    }
+    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();
+      }
+    }
+  }
+
+  // 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 the substantive
+  // assistant answer, including a substantive wrap-up segment before a terse terminal status.
+  // 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") {
+      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);
+    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 completed state IN PLACE, so the tool persists as ONE row.
+      this.sessionEventCb({ type: "tool", origin: "provider", body: tool.body, label: tool.label, status: "completed", ...(turnId ? { turnId } : {}), ...(itemId ? { stepId: itemId } : {}) });
+    }
+    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.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 ?? {});
+      // 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, status: "running", streaming: true, ...(turnId ? { turnId } : {}), ...(itemId ? { stepId: itemId } : {}) });
+      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;
+  }
+
+  private flushTurnResponse(): void {
+    const text = this.agentMessageCapture.finish((body) => this.emitAgentNarration(body));
+    if (text) this.sessionEventCb({ type: "response", origin: "provider", body: text, final: true, ...(this.activeTurnId ? { turnId: this.activeTurnId } : {}) });
+  }
+
+  private finishMainTurn(): void {
+    this.flushBufferedReasoning(); // surface any trailing reasoning before the closing response
+    this.flushTurnResponse();
+    const turnId = this.activeTurnId;
+    this.activeTurnId = undefined;
+    this.pendingApprovals.clear();
+    this.itemTextBuffers.clear();
+    this.itemTextBufferTypes.clear();
+    this.agentMessageCapture.reset();
+    this.statusCb({ 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";
+  }
+}
+
+// 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>): { label: string; body: string } | null {
+  const oneLine = (value: unknown): string => (typeof value === "string" ? value.replace(/\s+/g, " ").trim() : "");
+  const clip = (text: string): string => (text.length > 200 ? `${text.slice(0, 197)}…` : text);
+  if (type === "commandExecution") {
+    const command = oneLine(item.command);
+    return { label: "Shell", body: clip(command || "command") };
+  }
+  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);
+    return { label: "Edit", body: clip(files.length ? files.join(", ") : "file changes") };
+  }
+  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) };
+  }
+  if (type === "webSearch") {
+    return { label: "Search", body: clip(oneLine(item.query) || "web search") };
+  }
+  if (type === "plan") {
+    return { label: "Plan", body: clip(oneLine(item.text) || "updated plan") };
+  }
+  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) };
+  }
+  return null;
+}
+
+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;
+}
+
+export function codexTokenUsageContext(params: Record<string, unknown> | undefined, now = Date.now()): ContextState | undefined {
+  const usage = isRecord(params?.tokenUsage) ? params.tokenUsage
+    : isRecord(params?.token_usage) ? params.token_usage
+    : isRecord(params?.usage) ? params.usage
+    : isRecord(params?.info) ? params.info
+    : params;
+  if (!usage) return undefined;
+  const total = isRecord(usage.total) ? usage.total
+    : isRecord(usage.totalTokenUsage) ? usage.totalTokenUsage
+    : isRecord(usage.total_token_usage) ? usage.total_token_usage
+    : undefined;
+  const last = isRecord(usage.last) ? usage.last
+    : isRecord(usage.lastTokenUsage) ? usage.lastTokenUsage
+    : isRecord(usage.last_token_usage) ? usage.last_token_usage
+    : undefined;
+  const tokensUsed = numberValue(last?.totalTokens) ?? numberValue(last?.total_tokens) ??
+    numberValue(total?.totalTokens) ?? numberValue(total?.total_tokens) ??
+    numberValue(usage.totalTokens) ?? numberValue(usage.total_tokens);
+  const tokensMax = numberValue(usage.modelContextWindow) ?? numberValue(usage.model_context_window) ??
+    numberValue(params?.modelContextWindow) ?? numberValue(params?.model_context_window);
+  if (tokensUsed === undefined || tokensMax === undefined || tokensMax <= 0) return undefined;
+  return {
+    utilization: Math.max(0, Math.min(1, tokensUsed / tokensMax)),
+    tokensUsed,
+    tokensMax,
+    lifecycleState: "working",
+    warmTopics: [],
+    activeMemories: [],
+    tasksSinceCompact: 0,
+    lastUpdatedAt: now,
+    source: "api",
+    confidence: "reported",
+  };
+}
+
+function latestCodexContext(process: ManagedProcess): ContextState | undefined {
+  const meta = process.meta ?? {};
+  const current = isContextState(meta.context) ? meta.context : undefined;
+  const explicitPath = stringValue(meta.threadPath);
+  const threadId = stringValue(meta.threadId);
+  const rolloutPath = explicitPath ?? (threadId ? findCodexRolloutPath(threadId) : undefined);
+  if (!rolloutPath) return current;
+  const context = readCodexRolloutContext(rolloutPath);
+  if (!context) return current;
+  process.meta = { ...meta, context, threadPath: rolloutPath };
+  return context;
+}
+
+function readCodexRolloutContext(path: string): ContextState | undefined {
+  try {
+    return codexRolloutContextFromText(readFileSync(path, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+export function codexRolloutContextFromText(input: string): ContextState | undefined {
+  const lines = input.split(/\r?\n/);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i]?.trim();
+    if (!line) continue;
+    let event: unknown;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!isRecord(event)) continue;
+    const payload = isRecord(event.payload) ? event.payload : undefined;
+    if (payload?.type !== "token_count") continue;
+    const timestamp = typeof event.timestamp === "string" ? Date.parse(event.timestamp) : Date.now();
+    return codexTokenUsageContext(payload, Number.isFinite(timestamp) ? timestamp : Date.now());
+  }
+  return undefined;
+}
+
+function findCodexRolloutPath(threadId: string): string | undefined {
+  const root = join(process.env.CODEX_HOME || join(homedir(), ".codex"), "sessions");
+  return findFileContaining(root, threadId);
+}
+
+function findFileContaining(dir: string, needle: string, depth = 0): string | undefined {
+  if (depth > 8) return undefined;
+  let entries: Array<{ name: string; isFile(): boolean; isDirectory(): boolean }>;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return undefined;
+  }
+  entries.sort((a, b) => b.name.localeCompare(a.name));
+  for (const entry of entries) {
+    const path = join(dir, entry.name);
+    if (entry.isFile() && entry.name.includes(needle) && entry.name.endsWith(".jsonl")) return path;
+    if (entry.isDirectory()) {
+      const found = findFileContaining(path, needle, depth + 1);
+      if (found) return found;
+    }
+  }
+  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);
+}
+
+function numberValue(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function isContextState(value: unknown): value is ContextState {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const state = value as Record<string, unknown>;
+  return typeof state.utilization === "number" &&
+    typeof state.lifecycleState === "string" &&
+    typeof state.source === "string" &&
+    typeof state.confidence === "string";
+}
+
+
+export function codexModelConfigArgs(model?: string, effort?: string): string[] {
+  const args: string[] = [];
+  if (model) args.push("-c", `model=${tomlString(model)}`);
+  if (effort) args.push("-c", `model_reasoning_effort=${tomlString(effort)}`);
+  return args;
+}
+
+export function codexApprovalConfigArgs(approvalMode?: string): string[] {
+  const sandboxMode = approvalMode === "open"
+    ? "danger-full-access"
+    : approvalMode === "read-only"
+      ? "read-only"
+      : "workspace-write";
+  return [
+    "-c",
+    'approval_policy="never"',
+    "-c",
+    `sandbox_mode=${tomlString(sandboxMode)}`,
+  ];
+}
+
+export function codexManagedConfigArgs(): string[] {
+  return ["-c", "check_for_update_on_startup=false"];
+}
+
+export function isCodexCliCommand(command: string): boolean {
+  return basename(command) === "codex";
+}
+
+export function resolveRealCodexCommand(command: string, pathValue = process.env.PATH || ""): string {
+  const candidates: string[] = [];
+  if (command.includes("/")) candidates.push(command);
+  for (const dir of pathValue.split(":").filter(Boolean)) candidates.push(join(dir, "codex"));
+
+  const seen = new Set<string>();
+  for (const candidate of candidates) {
+    if (seen.has(candidate)) continue;
+    seen.add(candidate);
+    if (!isExecutableFile(candidate)) continue;
+    const real = realPath(candidate);
+    if (isAgentRelayCodexShim(candidate) || isAgentRelayCodexShim(real)) continue;
+    return candidate;
+  }
+  return command;
+}
+
+function isExecutableFile(path: string): boolean {
+  try {
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function realPath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+function isAgentRelayCodexShim(path: string): boolean {
+  return path.includes("/.agent-relay/codex/bin/codex");
+}
+
+// #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 };
+export { tomlString };
+
+export function codexAppServerConfigArgs(...argLists: string[][]): string[] {
+  const result: string[] = [];
+  for (const args of argLists) {
+    for (let i = 0; i < args.length; i++) {
+      const arg = args[i];
+      if (arg === "-c" || arg === "--config" || arg === "--enable" || arg === "--disable") {
+        const value = args[i + 1];
+        if (value !== undefined) {
+          result.push(arg, value);
+          i++;
+        }
+      } else if (arg?.startsWith("--config=") || arg?.startsWith("--enable=") || arg?.startsWith("--disable=")) {
+        result.push(arg);
+      }
+    }
+  }
+  return result;
+}
+
+export function codexToolOutputTokenLimitConfigArgs(config: Pick<RunnerSpawnConfig, "agentProfile">): string[] {
+  const configured = codexToolOutputTokenLimit(config.agentProfile?.providerOptions);
+  if (configured === null) return [];
+  const limit = configured ?? DEFAULT_CODEX_TOOL_OUTPUT_TOKEN_LIMIT;
+  return ["-c", `tool_output_token_limit=${limit}`];
+}
+
+function codexToolOutputTokenLimit(providerOptions: unknown): number | null | undefined {
+  if (!isRecord(providerOptions)) return undefined;
+  const codex = providerOptions.codex;
+  if (!isRecord(codex)) return undefined;
+  const limit = codex.toolOutputTokenLimit;
+  return typeof limit === "number" || limit === null ? limit : undefined;
+}
+
+
+async function connectWithRetry(client: CodexAppClient, attempts = 40): Promise<void> {
+  // Give the freshly-spawned app-server a moment to bind its socket before the
+  // first attempt, so we don't spend the retry budget on guaranteed refusals.
+  await Bun.sleep(150);
+  let lastError: unknown;
+  for (let i = 0; i < attempts; i++) {
+    try {
+      await client.connect();
+      return;
+    } catch (error) {
+      lastError = error;
+      await Bun.sleep(250);
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error(String(lastError));
+}
+
+async function terminateProcessTree(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<void> {
+  const processes = [
+    process.meta?.tui as Bun.Subprocess | undefined,
+    process.meta?.appServer as Bun.Subprocess | undefined,
+    process.process,
+  ].filter(Boolean) as Bun.Subprocess[];
+  if (processes.length === 0) return;
+  const rootPids = processes.map((proc) => proc.pid).filter((pid): pid is number => typeof pid === "number" && pid > 0);
+  const pids = await processTreePids(rootPids).catch(() => rootPids);
+  const signal = opts.graceful ? "SIGTERM" : "SIGKILL";
+  try {
+    for (const pid of pids) killPid(pid, signal);
+  } catch {
+    return;
+  }
+  const exited = await waitForPidsExit(pids, opts.timeoutMs);
+  const alive = pids.filter(isPidAlive);
+  if (!exited || alive.length > 0) {
+    try {
+      for (const pid of alive) killPid(pid, "SIGKILL");
+    } catch {}
+    await waitForPidsExit(alive, 1_000);
+    await Promise.race([
+      Promise.all(processes.map((proc) => proc.exited.catch(() => {}))),
+      Bun.sleep(1_000),
+    ]);
+  }
+}
+
+function codexRelayContextEnabled(process: ManagedProcess): boolean {
+  const config = process.meta?.config as RunnerSpawnConfig | undefined;
+  return config ? profileAllowsRelayFeature(config, "context") : true;
+}
+
+// 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?.trim();
+  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");
+}