@deksden-com/dd-flow-cli 0.9.0-beta.16 → 0.9.0-beta.161

package/dist/harness-runtime/lib/dd-codex.mjs

@@ -0,0 +1,986 @@
+import { spawn } from "node:child_process";
+import { createReadStream } from "node:fs";
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import readline from "node:readline";
+import { closeBridgeProcess } from "./managed-daemon.mjs";
+import { errorRecord, isObservationLoss, isProvenShellCorrection } from "./operation-errors.mjs";
+import { reportedFailure, commandText } from "./process-json.mjs";
+import { ObservationClock, observedTimeout, validateObservationDuration } from "./observation-clock.mjs";
+import { observeModel } from "./model-observations.mjs";
+import { classifyCodexItem } from "./tool-observations.mjs";
+import { readNativeLines, streamNativeDiagnostics, nativeObservationError } from "./native-streams.mjs";
+import { operationProgressReporter } from "./operation-progress.mjs";
+import { publishSetup } from './setup-progress.mjs';
+import { capacityBackoff } from './provider-overload-policy.mjs';
+
+export const CODEX_REQUEST_TIMEOUT_MS = 120_000;
+export const LATE_RESPONSE_GRACE_MS = 5_000;
+export function codexReadPhase(bridge, options = {}) {
+  const timeoutMs = Math.min(CODEX_REQUEST_TIMEOUT_MS, options.livenessTimeoutMs ?? options.timeoutMs ?? CODEX_REQUEST_TIMEOUT_MS);
+  return { clock: new ObservationClock({ timeoutMs, ...options.observationClock,
+    onGap: gap => bridge.journal?.write("observation_gap", { ...gap, phase: "metadata_read" }) }),
+    random: options.readRandom ?? Math.random,
+    sleep: options.readSleep ?? (ms => new Promise(resolve => setTimeout(resolve, ms))) };
+}
+
+function dispatchBudget(phase, method, limitMs) {
+  const clock = phase.outerClock ?? phase.clock;
+  if (clock.sample(phase.progress?.())) throw Object.assign(new Error("Codex owner observation window expired before dispatch"), {
+    code: clock.observationLost ? "operation_observation_lost" : "rpc_timeout",
+    details: { method, phase: "before_dispatch", effect: "no_effect", observation: clock.state() }
+  });
+  const remaining = Math.max(1, Math.ceil(clock.timeoutMs - clock.elapsed));
+  const timeoutMs = Math.min(limitMs, remaining);
+  return [timeoutMs, { graceMs: Math.min(LATE_RESPONSE_GRACE_MS, remaining - timeoutMs) }];
+}
+
+export async function readCodexRpc(bridge, method, params, phase = codexReadPhase(bridge)) {
+  if (!["thread/read", "thread/turns/list"].includes(method)) throw new Error("Codex read policy only accepts read-only RPC");
+  const sample = () => phase.clock.sample(phase.progress?.());
+  let primary;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    if (sample()) throw primary ?? Object.assign(new Error("Codex metadata observation window expired"), { code: phase.clock.observationLost ? "operation_observation_lost" : "rpc_timeout", details: { method, phase: "metadata_read", observation: phase.clock.state() } });
+    const remaining = Math.min(CODEX_REQUEST_TIMEOUT_MS, Math.max(1, Math.ceil(phase.clock.timeoutMs - phase.clock.elapsed)));
+    try {
+      const result = await bridge.request(method, params, remaining, { graceMs: 0, observe: () => { sample(); phase.outerClock?.sample(); } });
+      if (!result || typeof result !== "object" || Array.isArray(result)
+        || method === "thread/read" && (!result.thread || typeof result.thread !== "object" || Array.isArray(result.thread) || typeof result.thread.id !== "string" || !result.thread.id)
+        || method === "thread/turns/list" && !Array.isArray(result.data))
+        throw Object.assign(new Error("Codex read returned invalid data"), { code: "rpc_schema_invalid", details: { method } });
+      if (method === "thread/read" && result.thread.id !== params.threadId)
+        throw Object.assign(new Error("Codex read returned a foreign Thread"), { code: "thread_identity_mismatch" });
+      return result;
+    }
+    catch (error) {
+      primary ??= error; bridge.assertHookHealthy?.(params.threadId);
+      // A broken process cannot be replaced under the guise of a read retry.
+      const current = bridge.currentTurns?.get(params.threadId);
+      const materializing = method === "thread/read" && current && !bridge.turns?.has(current)
+        && bridge.nativeHookTurns?.get(params.threadId) !== current && error?.code === "rpc_error" && error.details?.code === -32603;
+      const emptyMetadata = materializing && error.details.message?.match(/^failed to read thread: thread-store internal error: failed to read session metadata (.+): rollout at (.+) is empty$/);
+      const transient = error?.code === "rpc_timeout" || error?.code === "EAGAIN" || error?.code === "EINTR"
+        || Boolean(emptyMetadata && emptyMetadata[1] === emptyMetadata[2] && emptyMetadata[1].endsWith(`-${params.threadId}.jsonl`));
+      if (!transient) { if (error !== primary) error.previous_read_error = errorRecord(primary); throw error; }
+      if (attempt === 2 || sample()) { if (error !== primary) primary.secondary_error = errorRecord(error); throw primary; }
+      const delay = Math.min(capacityBackoff(error, attempt + 1, phase.clock.wall(), phase.random), Math.max(0, phase.clock.timeoutMs - phase.clock.elapsed));
+      bridge.journal?.write("thread_read_retry", { method, session_id: params.threadId, attempt: attempt + 1, delay_ms: delay, error: errorRecord(error) });
+      await phase.sleep(delay);
+    }
+  }
+}
+
+// Availability belongs to this read of this Thread, not to the whole binary.
+export async function readCodexHistory(bridge, method, params, phase = codexReadPhase(bridge)) {
+  if (method !== "thread/turns/list" && !(method === "thread/read" && params.includeTurns === true))
+    throw new Error("Codex history policy only accepts history reads");
+  let result, error;
+  try {
+    result = await readCodexRpc(bridge, method, params, phase);
+    if (method === "thread/read" && result.thread.turns !== undefined && !Array.isArray(result.thread.turns))
+      fail("Codex history read returned invalid turns", "rpc_schema_invalid", { method });
+  }
+  catch (cause) {
+    bridge.assertHookHealthy?.(params.threadId);
+    const native = cause?.details;
+    const operation = method === "thread/read" ? "includeTurns" : "thread/turns/list";
+    const unsupported = native?.code === -32601 && native.message === "list_turns is not supported yet";
+    const unmaterialized = native?.code === -32600 && native.message ===
+      `thread ${params.threadId} is not materialized yet; ${operation} is unavailable before first user message`;
+    if (cause?.code !== "rpc_error" || !unsupported && !unmaterialized) throw cause;
+    error = errorRecord(cause);
+  }
+  const available = !error;
+  phase.history ??= new Map();
+  const key = `${params.threadId}:${method}`;
+  if (phase.history.get(key)?.available !== available) bridge.journal?.write("history_availability", {
+    method, session_id: params.threadId, available, ...(error ? { error } : {})
+  });
+  phase.history.set(key, { available, error });
+  return { available, result, error };
+}
+
+export function retainedCodexTurn(bridge, sessionId, turnId = bridge.currentTurns?.get(sessionId)) {
+  if (!turnId) return null;
+  const retained = bridge.turns?.get(turnId);
+  if (!retained) return null;
+  if (retained.threadId && retained.threadId !== sessionId || retained.value?.threadId && retained.value.threadId !== sessionId)
+    fail("Codex retained Thread identity differs", "turn_identity_mismatch");
+  if (!retained.threadId && !retained.value?.threadId) return null;
+  const turn = retained.value?.turn;
+  if (turn?.id !== turnId) fail("Codex retained Turn identity differs", "turn_identity_mismatch");
+  return turn;
+}
+const CODEX_SESSION_CONFIG = Object.freeze({
+  bypass_hook_trust: true,
+  "features.plugins": false,
+  "features.multi_agent_v2.enabled": true,
+  "features.multi_agent_v2.tool_namespace": "collaboration",
+  "features.multi_agent_v2.wait_agent_enabled": true
+});
+
+// Minimal JSON-RPC wrapper around the public Codex app-server protocol.  It is
+// intentionally one-shot: the provider owns durable Threads, while the caller
+// owns the runner journal and can safely resume after a process restart.
+function fail(message, code, details) { const error = new Error(message); if (code) error.code = code; if (details) error.details = details; throw error; }
+function required(value, label) { if (typeof value !== "string" || !value.trim()) fail(`${label} is required`); return value.trim(); }
+function absolute(value, label) { const resolved = path.resolve(required(value, label)); if (!path.isAbsolute(resolved)) fail(`${label} must be absolute`); return resolved; }
+function now() { return new Date().toISOString(); }
+function responseSummary(message) {
+  const result = message?.result;
+  return { request_id: message?.id ?? null, has_result: result !== undefined,
+    result_keys: result && typeof result === "object" && !Array.isArray(result) ? Object.keys(result).slice(0, 32) : [], error: message?.error ?? null };
+}
+
+export function parseCodexCliVersion(value) {
+  const match = String(value).trim().match(/^codex-cli\s+(\S+)$/m);
+  if (!match) fail("Codex CLI did not report its version", "codex_version_unavailable");
+  return match[1];
+}
+
+
+
+class Journal {
+  constructor(file) { this.file = file ? absolute(file, "--journal") : null; this.pending = this.file ? mkdir(path.dirname(this.file), { recursive: true }) : Promise.resolve(); this.order = 0; }
+  write(kind, payload) { if (!this.file) return; this.pending = this.pending.then(() => appendFile(this.file, `${JSON.stringify({ order: ++this.order, observed_at: now(), kind, payload })}\n`)); void this.pending.catch(() => {}); return this.pending; }
+  flush() { return this.pending; }
+}
+
+export class CodexBridge {
+  constructor(options = {}) { this.options = options; this.nextId = 1; this.pending = new Map(); this.lateResponses = new Map(); this.turns = new Map(); this.nativeErrors = new Map(); this.finalMessages = new Map(); this.descendants = new Map(); this.journal = new Journal(options.journal); this.stderr = ""; this.requestedProfiles = new Map(); this.modelObservations = Promise.resolve(); }
+
+  async restoreItemPhases() {
+    if (this.options.journal) {
+      const source = createReadStream(this.options.journal, { encoding: "utf8" });
+      try {
+        for await (const line of readline.createInterface({ input: source })) {
+          let record; try { record = JSON.parse(line); } catch { continue; }
+          if (record.direction === "inbound" || record.kind === "inbound") this.observeItemPhase(record.payload ?? record.message ?? record);
+        }
+      } catch (error) { if (error.code !== "ENOENT") throw error; }
+    }
+  }
+
+  async start() {
+    await this.restoreItemPhases();
+    const bin = this.options.bin ?? process.env.DD_CODEX_BIN ?? "codex";
+    // Thread overrides arrive too late to prevent app-server's background
+    // marketplace clones. Apply the same isolation policy before startup.
+    this.child = spawn(bin, ["-c", `features.plugins=${CODEX_SESSION_CONFIG["features.plugins"]}`, "app-server"], { cwd: this.options.cwd ? absolute(this.options.cwd, "--cwd") : process.cwd(), env: { ...process.env, ...(this.options.env ?? {}) }, detached: process.platform !== "win32", stdio: ["pipe", "pipe", "pipe"] });
+    this.diagnostics = streamNativeDiagnostics(this.child.stderr, async chunk => { this.stderr = (this.stderr + chunk).slice(-65_536); await this.journal.write("stderr", { text: chunk }); }, error => this.rejectAll(error));
+    this.child.stdin?.on("error", (error) => this.rejectAll(nativeObservationError(error)));
+    this.child.on("error", (error) => this.rejectAll(error));
+    this.child.on("close", code => { void Promise.all([this.nativeDrain, this.diagnostics]).then(() => this.rejectAll(Object.assign(new Error(`Codex app-server exited ${code}${this.stderr.trim() ? `: ${this.stderr.trim()}` : ""}`), { code: "bridge_exited" }))); });
+    this.nativeDrain = readNativeLines(this.child.stdout, async line => { this.receive(line); await this.journal.flush(); }, error => this.rejectAll(error));
+    if (this.options.onSpawn) await this.options.onSpawn(this.child);
+    publishSetup('probe_started', 'codex-initialize');
+    await this.request("initialize", { clientInfo: { name: "dd-codex", version: "0.1.0" }, capabilities: { optOutNotificationMethods: [], experimentalApi: true } });
+    publishSetup('native_initialized', 'codex-initialize');
+  }
+
+  receive(line) {
+    let message; try { message = JSON.parse(line); } catch { this.journal.write("malformed", { line }); return; }
+    // Read-induced idle/status notifications are not new execution. Native
+    // turn/item events and newly active threads invalidate an idle proof.
+    if (/^(turn|item)\//.test(message.method ?? "")
+      || message.method === "thread/status/changed" && message.params?.status?.type === "active") this.options.onNativeActivity?.();
+    this.observeItemPhase(message);
+    try { this.observeTopology(message); }
+    catch (error) { this.topologyError = error; this.rejectAll(error); return; }
+    this.observeHookFailure(message);
+    this.observeNativeHook(message);
+    if (["model/rerouted", "thread/settings/updated"].includes(message.method)) {
+      const params = message.params ?? {}, id = params.threadId;
+      let root = id; const seen = new Set();
+      while (root && !this.requestedProfiles.has(root) && !seen.has(root)) { seen.add(root); root = this.descendants.get(root)?.parent_provider_session_id; }
+      if (root && this.requestedProfiles.has(root)) {
+        const settings = params.threadSettings ?? {};
+        const rerouted = message.method === "model/rerouted";
+        this.modelObservations = this.modelObservations.then(() => observeModel({ journal: this.options.journal, harness: "codex-desktop", sessionId: id,
+          parentSessionId: this.descendants.get(id)?.parent_provider_session_id ?? null, requested: this.requestedProfiles.get(root),
+          observed: { model: rerouted ? params.toModel : settings.model, provider: settings.modelProvider, reasoning: settings.effort },
+          source: message.method, evidence: rerouted ? "response" : "configured", reason: params.reason ?? null, previousModel: params.fromModel ?? null
+        })).catch(cause => { const error = nativeObservationError(cause); this.modelObservationError = error; this.rejectAll(error); });
+      }
+    }
+    if (message.method === "turn/started") {
+      this.currentTurns ??= new Map(); const id = message.params?.turn?.id, thread = message.params?.threadId;
+      const pendingStart = [...this.pending.values()].find(value => value.method === "turn/start" && value.threadId === thread);
+      const dispatching = pendingStart && !pendingStart.turnFloor?.has(id);
+      if (id && dispatching && this.requestedProfiles.has(thread)) this.options.onOwnedRootTurn?.(thread, id);
+      const child = this.descendants.get(thread), parentCurrent = child?.parent_turn_id && child.parent_turn_id === this.currentTurns.get(child.parent_provider_session_id);
+      if (id && this.turns.get(id)?.status !== "completed" && (dispatching || parentCurrent && child.status === "running" || !this.currentTurns.has(thread) && !this.requestedProfiles.has(thread))) {
+        if (this.currentTurns.get(thread) !== id) this.usageMarkers?.delete(thread);
+        this.currentTurns.set(thread, id);
+      }
+    }
+    const params = message.params ?? {}, currentTurn = this.currentTurns?.get(params.threadId);
+    let productive = message.method === "turn/started" || /^item\/(started|completed|[^/]+\/(delta|outputDelta|summaryTextDelta|textDelta))$/.test(message.method ?? "");
+    if (productive && currentTurn && (params.turnId ?? params.turn?.id) === currentTurn && ["turn/started", "item/started", "item/completed"].includes(message.method)) {
+      this.progressPhases ??= new Map(); const key = JSON.stringify([params.threadId, currentTurn, message.method, params.item?.id ?? null]);
+      if (this.progressPhases.has(key)) productive = false;
+      else if (this.progressPhases.size < 1_024) this.progressPhases.set(key, true);
+      else productive = false;
+    }
+    if (productive && /(?:Delta|delta)$/.test(message.method ?? "") && !params.delta && !params.outputDelta && !params.text) productive = false;
+    let usageProgress = false;
+    if (message.method === "thread/tokenUsage/updated" && params.turnId === currentTurn) {
+      this.usageMarkers ??= new Map(); const count = params.tokenUsage?.last?.totalTokens ?? params.tokenUsage?.total?.totalTokens;
+      const prior = this.usageMarkers.get(params.threadId) ?? 0;
+      if (Number.isFinite(count) && count > prior) { usageProgress = true; this.usageMarkers.set(params.threadId, count); }
+    }
+    if (message.id === undefined && currentTurn && (params.turnId ?? params.turn?.id) === currentTurn && (productive || usageProgress)) {
+      this.activity ??= new Map();
+      this.activityObservations ??= new Map();
+      const visited = new Set();
+      let id = message.params?.threadId;
+      while (id && !visited.has(id)) {
+        visited.add(id); const cursor = (this.activity.get(id) ?? 0) + 1; this.activity.set(id, cursor); this.activityObservations.set(id, { cursor, observed_at: Date.now() });
+        const observer = this.turnObservers?.get(id), turnId = this.currentTurns?.get(id);
+        if (observer && turnId && !observer.turnFloor.has(turnId)) {
+          const pending = this.pending.get(observer.id);
+          if (pending) pending.progress = this.activityObservations.get(id);
+          const session = id;
+          void observer.publish("native_progress", { native_request_id: String(observer.id), session_id: id, observed_at: new Date(this.activityObservations.get(id).observed_at).toISOString() }).catch(cause => {
+            // Pipe publications can finish after this Turn's terminal response.
+            // Never attribute an old operation's storage failure to its successor.
+            if (this.turnObservers?.get(session) !== observer) return;
+            const error = nativeObservationError(cause); observer.progressError ??= error;
+            const current = this.pending.get(observer.id);
+            if (current === pending && current) { clearTimeout(current.timer); this.pending.delete(observer.id); current.reject(error); }
+          });
+        }
+        const child = this.descendants.get(id), parent = child?.parent_provider_session_id;
+        id = parent && child.parent_turn_id && child.parent_turn_id === this.currentTurns?.get(parent) ? parent : null;
+      }
+    }
+    // app-server currently returns complete turns even for `includeTurns:
+    // false`.  The individual item notifications are already journalled, so
+    // retain a compact read receipt instead of writing the same transcript on
+    // every status poll.
+    const request = message.id !== undefined ? this.pending.get(message.id) : null;
+    if (request?.method === "thread/read" && !message.error) {
+      const thread = message.result?.thread ?? message.result ?? {};
+      this.journal.write("inbound", { jsonrpc: message.jsonrpc, id: message.id, result: { thread: {
+        id: thread.id ?? null, status: thread.status ?? null, model: thread.model ?? null, modelProvider: thread.modelProvider ?? null, reasoningEffort: thread.reasoningEffort ?? null, updatedAt: thread.updatedAt ?? null,
+        turns: Array.isArray(thread.turns) ? thread.turns.map((turn) => ({ id: turn?.id ?? null, status: turn?.status ?? null, startedAt: turn?.startedAt ?? null, completedAt: turn?.completedAt ?? null })) : []
+      } } });
+    } else this.journal.write("inbound", message);
+    if (message.id !== undefined && message.method) { void this.answerRequest(message); return; }
+    if (message.id !== undefined) {
+      const pending = this.pending.get(message.id);
+      if (!pending) {
+        this.lateResponses.set(message.id, message);
+        while (this.lateResponses.size > 128) this.lateResponses.delete(this.lateResponses.keys().next().value);
+        this.journal.write("late_response", responseSummary(message));
+        return;
+      }
+      clearTimeout(pending.timer); this.pending.delete(message.id);
+      if (pending.method === "turn/start" && pending.threadId && message.result?.turn?.id) {
+        this.currentTurns ??= new Map();
+        if (this.currentTurns.get(pending.threadId) !== message.result.turn.id) this.usageMarkers?.delete(pending.threadId);
+        this.currentTurns.set(pending.threadId, message.result.turn.id);
+      }
+      if (pending.timedOut) this.journal.write("late_response", { ...responseSummary(message), method: pending.method, grace_ms: LATE_RESPONSE_GRACE_MS });
+      message.error ? pending.reject(Object.assign(new Error(message.error.message ?? JSON.stringify(message.error)), { code: "rpc_error", details: message.error })) : pending.resolve(message.result ?? {});
+      return;
+    }
+    if (message.method === "error" && message.params?.threadId && message.params?.turnId) {
+      const key = `${message.params.threadId}:${message.params.turnId}`;
+      this.nativeErrors.set(key, { error: message.params.error, willRetry: message.params.willRetry });
+      while (this.nativeErrors.size > 128) this.nativeErrors.delete(this.nativeErrors.keys().next().value);
+    }
+    if (message.method === "turn/completed") {
+      this.turns.set(message.params?.turn?.id ?? message.params?.threadId, { status: "completed", value: message.params, threadId: message.params?.threadId });
+      if (this.currentTurns?.get(message.params?.threadId) === message.params?.turn?.id) this.turnObservers?.delete(message.params.threadId);
+    }
+    if (message.method === "turn/started" && this.turns.get(message.params?.turn?.id)?.status !== "completed") this.turns.set(message.params?.turn?.id ?? message.params?.threadId, { status: "running", value: message.params, threadId: message.params?.threadId });
+    const threadId = message.params?.threadId;
+    if (threadId && message.method === "item/started") this.finalMessages.delete(threadId);
+    if (threadId && message.method === "item/completed" && message.params?.item?.type === "agentMessage") this.finalMessages.set(threadId, { item: message.params.item, turnId: message.params?.turnId ?? null, completedAt: Date.now() });
+  }
+
+  isManagedHook(run) {
+    const home = this.options.env?.CODEX_HOME;
+    return Boolean(home && run?.eventName === "preToolUse" && run.handlerType === "command"
+      && run.executionMode === "sync" && run.statusMessage === "dd-flow runtime observation"
+      && run.sourcePath === path.join(home, "hooks.json"));
+  }
+
+  observeNativeHook(message) {
+    if (message.method === "turn/started") {
+      const { threadId, turn } = message.params ?? {};
+      if (threadId && turn?.id && this.turns.get(turn.id)?.status !== "completed") {
+        this.nativeHookTurns ??= new Map(); this.nativeHookTurns.set(threadId, turn.id);
+        for (const [id, hook] of this.activeHooks ?? []) if (hook.threadId === threadId && hook.turnId !== turn.id) this.activeHooks.delete(id);
+      }
+      return;
+    }
+    if (message.method === "turn/completed") {
+      const { threadId, turn } = message.params ?? {};
+      for (const [id, hook] of this.activeHooks ?? []) {
+        if (hook.threadId === threadId && hook.turnId === turn?.id) this.activeHooks.delete(id);
+      }
+      return;
+    }
+    if (!["hook/started", "hook/completed"].includes(message.method)) return;
+    const { threadId, turnId, run } = message.params ?? {};
+    if (!this.isManagedHook(run) || typeof run.id !== "string" || !threadId) return;
+    this.activeHooks ??= new Map();
+    if (message.method === "hook/started") {
+      if (this.nativeHookTurns?.has(threadId) && this.nativeHookTurns.get(threadId) !== turnId) return;
+      let root = threadId; const seen = new Set();
+      while (this.descendants.has(root) && !seen.has(root)) { seen.add(root); root = this.descendants.get(root).parent_provider_session_id; }
+      this.activeHooks.set(run.id, { threadId, turnId, root, rootTurnId: this.nativeHookTurns?.get(root) ?? null, rootGeneration: this.hookPromptGenerations?.get(root) ?? 0 });
+    } else if (this.activeHooks.get(run.id)?.turnId === turnId) this.activeHooks.delete(run.id);
+  }
+
+  verifyNativeHook(input) {
+    const { rootSessionId, sessionId, toolCallId, turnId } = input;
+    const home = this.options.env?.CODEX_HOME;
+    const id = `pre-tool-use:0:${path.join(home ?? "", "hooks.json")}:${toolCallId}`;
+    const active = this.activeHooks?.get(id);
+    let current = sessionId;
+    const seen = new Set();
+    while (current && current !== rootSessionId && !seen.has(current)) {
+      seen.add(current); current = this.descendants.get(current)?.parent_provider_session_id;
+    }
+    if (!active || active.threadId !== sessionId || active.turnId !== turnId || !toolCallId
+        || current !== rootSessionId || !this.requestedProfiles.has(rootSessionId)
+        || active.rootGeneration !== (this.hookPromptGenerations?.get(rootSessionId) ?? 0)) {
+      fail("No matching active managed native hook", "native_hook_unproven", { provider_session_id: sessionId, tool_call_id: toolCallId });
+    }
+    let creatorRootTurnId = null;
+    if (sessionId !== rootSessionId) {
+      let child = sessionId; const visited = new Set();
+      while (child !== rootSessionId && !visited.has(child)) {
+        visited.add(child);
+        const edge = this.descendants.get(child), parent = edge?.parent_provider_session_id, turn = edge?.parent_turn_id;
+        if (!parent || !turn || this.creatorEdges?.get(child) !== JSON.stringify([parent, turn])) break;
+        if (parent === rootSessionId) { creatorRootTurnId = turn; break; }
+        const observed = this.turns.get(turn);
+        if (!observed || observed.threadId !== parent) break;
+        child = parent;
+      }
+    }
+    return { rootSessionId, sessionId, toolCallId, parentSessionId: sessionId === rootSessionId ? null : this.descendants.get(sessionId)?.parent_provider_session_id, ...(creatorRootTurnId ? { creatorRootTurnId } : {}) };
+  }
+
+  observeHookFailure(message) {
+    const { threadId, turnId, run } = message.params ?? {};
+    const home = this.options.env?.CODEX_HOME;
+    if (message.method !== "hook/completed" || run?.status !== "failed" ||
+        run.eventName !== "preToolUse" || run.handlerType !== "command" ||
+        run.statusMessage !== "dd-flow runtime observation" || !home ||
+        run.sourcePath !== path.join(home, "hooks.json")) return;
+    const active = this.activeHooks?.get(run.id);
+    if (!active || active.threadId !== threadId || active.turnId !== turnId) return;
+    if (this.nativeHookTurns?.has(threadId) && this.nativeHookTurns.get(threadId) !== turnId
+      || active.rootTurnId !== null && this.nativeHookTurns?.get(active.root) !== active.rootTurnId
+      || active.rootGeneration !== (this.hookPromptGenerations?.get(active.root) ?? 0)) return;
+    const ancestors = new Set();
+    let root;
+    let current = threadId;
+    while (current && !ancestors.has(current)) {
+      ancestors.add(current);
+      if (this.requestedProfiles.has(current)) root = current;
+      current = this.descendants.get(current)?.parent_provider_session_id;
+    }
+    if (!root) return;
+    this.hookFailures ??= new Map();
+    if (this.hookFailures.has(root)) return;
+    const entries = Array.isArray(run.entries) ? run.entries : [];
+    const reason = entries.filter(entry => entry.kind === "error").map(entry => entry.text).join("; ");
+    const error = reportedFailure(entries.filter(entry => entry.kind === "error").map(entry => entry.text).join("\n"), "", reason || "Managed Codex hook failed", /timed out/i.test(reason) ? "native_hook_timeout" : "native_hook_failed");
+    const correction = isProvenShellCorrection(error);
+    error.details = { ...error.details, native_hook_binding: { provider_session_id: threadId, root_provider_session_id: root, turn_id: turnId,
+        hook_run_id: run.id, source: "codex.hook/completed" }, provider_session_id: threadId, root_provider_session_id: root, turn_id: turnId,
+        hook_run_id: run.id, effect: error.details?.effect ?? "unknown", native_turn_items: { observed: false, possible_effects: true, pending: true }, duration_ms: run.durationMs };
+    if (correction) {
+      try { void Promise.resolve(this.journal.write("native_hook_correction", errorRecord(error))).catch(storage => { error.cleanup_error ??= errorRecord(storage); }); }
+      catch (storage) { error.cleanup_error ??= errorRecord(storage); }
+      return;
+    }
+    if (["native_hook_timeout", "native_hook_failed"].includes(error.code)) {
+      // Codex reports a failed hook independently of the shell tool: exit 1
+      // does not prove that the real CLI failed or even that it did not run.
+      // Retain the observation without rejecting the productive Turn.
+      const diagnostic = { ...errorRecord(error), root_generation: active.rootGeneration, root_turn_id: active.rootTurnId };
+      this.hookDiagnostics ??= new Map();
+      const notes = this.hookDiagnostics.get(root) ?? []; notes.push(diagnostic); this.hookDiagnostics.set(root, notes);
+      try { void Promise.resolve(this.journal.write("native_hook_observation_failure", diagnostic)).catch(() => {}); } catch { /* optional diagnostic */ }
+      return;
+    }
+    this.hookFailures.set(root, error);
+    for (const [id, pending] of this.pending) {
+      if (ancestors.has(pending.threadId) && pending.method !== "turn/interrupt") {
+        clearTimeout(pending.timer); this.pending.delete(id); pending.reject(error);
+      }
+    }
+    try { void Promise.resolve(this.journal.write("native_hook_failure", errorRecord(error))).catch(storage => { error.cleanup_error ??= errorRecord(storage); }); }
+    catch (storage) { error.cleanup_error ??= errorRecord(storage); }
+  }
+
+  assertHookHealthy(sessionId) {
+    if (this.topologyError) throw this.topologyError;
+    const visited = new Set();
+    while (sessionId && !visited.has(sessionId)) {
+      visited.add(sessionId);
+      if (this.turnObservers?.get(sessionId)?.progressError) throw this.turnObservers.get(sessionId).progressError;
+      const error = this.hookFailures?.get(sessionId);
+      if (error) throw error;
+      sessionId = this.descendants.get(sessionId)?.parent_provider_session_id;
+    }
+  }
+
+  observeItemPhase(message) {
+    const { threadId, turnId, item } = message?.params ?? {};
+    if (message?.method !== "item/completed" || !threadId || !turnId || !item?.id || classifyCodexItem(item.type) !== "tool") return;
+    this.itemPhases ??= new Map();
+    const key = JSON.stringify([threadId, turnId, item.id]);
+    const previous = this.itemPhases.get(key);
+    if (previous && (previous.type !== item.type || previous.status !== (item.status ?? null))) {
+      this.topologyError = Object.assign(new Error("Conflicting native item completion evidence"), { code: "native_item_completion_conflict", details: { provider_session_id: threadId, turn_id: turnId, item_id: item.id } });
+      this.rejectAll(this.topologyError); return;
+    }
+    this.itemPhases.set(key, { type: item.type, status: item.status ?? null });
+  }
+
+  bindChild(child, parent, facts) {
+    const previous = this.descendants.get(child);
+    if (child === parent || this.requestedProfiles.has(child) || previous?.parent_provider_session_id && previous.parent_provider_session_id !== parent) {
+      fail("Conflicting native child parent identity", "native_topology_conflict", { child_session_id: child, parent_session_id: parent, retained_parent: previous?.parent_provider_session_id ?? null });
+    }
+    const creator = this.creatorEdges?.get(child);
+    if (creator && facts.creator_turn_exact && facts.parent_turn_id && creator !== JSON.stringify([parent, facts.parent_turn_id])) {
+      fail("Conflicting native child creator Turn", "native_topology_conflict", { child_session_id: child, parent_session_id: parent, retained_turn: previous.parent_turn_id, observed_turn: facts.parent_turn_id });
+    }
+    const seen = new Set([child]);
+    for (let ancestor = parent; ancestor; ancestor = this.descendants.get(ancestor)?.parent_provider_session_id) {
+      if (seen.has(ancestor)) fail("Native child ancestry contains a cycle", "native_topology_cycle", { child_session_id: child, parent_session_id: parent });
+      seen.add(ancestor);
+    }
+    if (facts.creator_turn_exact && facts.parent_turn_id) { this.creatorEdges ??= new Map(); this.creatorEdges.set(child, JSON.stringify([parent, facts.parent_turn_id])); }
+    const { creator_turn_exact: _sourceIsExact, ...publicFacts } = facts;
+    this.descendants.set(child, { ...previous, ...publicFacts, parent_turn_id: publicFacts.parent_turn_id ?? previous?.parent_turn_id ?? null, provider_session_id: child, parent_provider_session_id: parent });
+  }
+
+  // Collaboration child Threads are provider facts.  Keep only objects that
+  // explicitly carry a parent relationship, including native spawn receipts.
+  // A wait/send receiver is not necessarily a child of its sender.
+  observeTopology(value, depth = 0, parentTurn = null) {
+    if (!value || typeof value !== "object" || depth > 8) return;
+    if (Array.isArray(value)) { for (const item of value) this.observeTopology(item, depth + 1, parentTurn); return; }
+    if (depth === 0 && ["turn/started", "turn/completed"].includes(value.method)) {
+      const { threadId, turn } = value.params ?? {};
+      const previous = this.descendants.get(threadId) ?? (threadId && !this.requestedProfiles.has(threadId) ? { provider_session_id: threadId, status: "unknown" } : null);
+      if (previous && typeof turn?.id === "string" && turn.id) {
+        if (value.method === "turn/started" && previous.active_turn_id !== turn.id && this.turns.get(turn.id)?.status !== "completed") {
+          this.descendants.set(threadId, { ...previous, status: "running", active_turn_id: turn.id, terminal_turn_id: null, provider_error: null });
+        } else if (value.method === "turn/completed" && (!previous.active_turn_id || previous.active_turn_id === turn.id)) {
+          this.descendants.set(threadId, { ...previous, status: turn.status === "completed" ? "completed" : turn.status ?? "unknown",
+            active_turn_id: turn.id, terminal_turn_id: turn.id, terminal_observed_at: previous.terminal_turn_id === turn.id ? previous.terminal_observed_at ?? now() : now(), provider_error: nativeTurnError(this, threadId, turn), native_turn_items: turnItemEvidence(turn, this, threadId) });
+        }
+      }
+    }
+    const activity = depth === 0 && ["item/started", "item/completed"].includes(value.method) ? value.params?.item : null;
+    const activityParent = value.params?.threadId;
+    if (activity?.type === "subAgentActivity" && typeof activity.agentThreadId === "string" && activity.agentThreadId &&
+        typeof activityParent === "string" && activityParent) {
+      const previous = this.descendants.get(activity.agentThreadId);
+      const observed = activity.kind === "completed" ? "completed" : activity.kind === "interrupted" ? "interrupted" : "running";
+      // Parent activity has no child Turn identity on some app-server builds.
+      // It can discover a child, but cannot reopen or close a later known Turn.
+      const status = previous?.active_turn_id || previous?.status === "completed" ? previous.status : observed;
+      if (activity.kind === "started") this.bindChild(activity.agentThreadId, activityParent, { status, parent_turn_id: value.params?.turnId === this.currentTurns?.get(activityParent) ? value.params.turnId : null, ...(value.params?.turnId && value.params.turnId === this.currentTurns?.get(activityParent) ? { creator_turn_exact: true } : {}), agent_path: activity.agentPath ?? previous?.agent_path ?? null, source: "codex.app_server.subAgentActivity" });
+      else if (["completed", "interrupted"].includes(activity.kind) && activity.agentThreadId !== activityParent && !this.requestedProfiles.has(activity.agentThreadId)) {
+        this.descendants.set(activity.agentThreadId, { ...previous, provider_session_id: activity.agentThreadId, status });
+      }
+    }
+    if (value.type === "collabAgentToolCall" && value.tool === "spawnAgent" &&
+        typeof value.senderThreadId === "string" && value.senderThreadId && Array.isArray(value.receiverThreadIds)) {
+      for (const child of value.receiverThreadIds) {
+        if (typeof child !== "string" || !child) continue;
+        const previous = this.descendants.get(child);
+        this.bindChild(child, value.senderThreadId, {
+          parent_turn_id: parentTurn === this.currentTurns?.get(value.senderThreadId) ? parentTurn : null,
+          ...(parentTurn && parentTurn === this.currentTurns?.get(value.senderThreadId) ? { creator_turn_exact: true } : {}),
+          status: previous?.status === "completed" || previous?.active_turn_id ? previous.status : value.agentsStates?.[child]?.status ?? previous?.status ?? "unknown", source: "codex.app_server" });
+      }
+    }
+    const thread = depth === 0 && ["thread/started", "thread/status/changed"].includes(value.method) ? value.params?.thread : null;
+    const id = thread?.id ?? null;
+    const parent = thread?.parentThreadId ?? thread?.parent_thread_id ?? null;
+    if (typeof id === "string" && id && typeof parent === "string" && parent) {
+      const previous = this.descendants.get(id);
+      this.bindChild(id, parent, {
+        parent_turn_id: !previous ? this.currentTurns?.get(parent) ?? null : previous.parent_turn_id,
+        status: previous?.status === "completed" || previous?.active_turn_id ? previous.status : thread.status?.type ?? thread.status ?? previous?.status ?? "unknown", source: "codex.app_server" });
+    }
+    if (depth === 0) {
+      if (["item/started", "item/completed"].includes(value.method)) this.observeTopology(value.params?.item, depth + 1, value.params?.turnId);
+      const nativeThread = this.pending.get(value.id)?.method === "thread/read" ? value.result?.thread : null;
+      if (nativeThread && Array.isArray(nativeThread.turns)) for (const turn of nativeThread.turns) this.observeTopology(turn.items, depth + 1, turn.id);
+    }
+  }
+
+  directChildren(sessionId) {
+    return [...this.descendants.values()].filter((child) => child.parent_provider_session_id === sessionId);
+  }
+
+  async answerRequest(message) {
+    // Eval runs are non-interactive. A request is evidence for the runner, not
+    // permission to continue. Do not silently approve a tool or elicitation.
+    // A JSON-RPC error is deliberately used instead of inventing a generic
+    // `{ decision: "deny" }` payload: app-server request methods have distinct
+    // result schemas, while every one must fail closed in a non-interactive
+    // eval.  The runner can classify this journalled request as infrastructure
+    // or unexpected interaction without corrupting the provider protocol.
+    const error = { code: -32001, message: `dd-codex refuses interactive request: ${message.method}` };
+    this.journal.write("request_refused", { method: message.method, params: message.params, error });
+    this.send({ jsonrpc: "2.0", id: message.id, error });
+  }
+
+  request(method, params = {}, timeoutMs = this.options.timeoutMs ?? CODEX_REQUEST_TIMEOUT_MS, policy = {}) {
+    const turnFloor = method === "turn/start" ? new Set([this.currentTurns?.get(params.threadId), ...[...this.turns].filter(([, value]) => value.threadId === params.threadId).map(([id]) => id)].filter(Boolean)) : null;
+    if (method === "turn/start" && params.threadId) {
+      // Only one productive root Turn is admitted by the daemon fence. Drop
+      // lifecycle replay keys at the next dispatch, not at arbitrary reads.
+      this.progressPhases?.clear();
+      this.hookPromptGenerations ??= new Map();
+      this.hookPromptGenerations.set(params.threadId, (this.hookPromptGenerations.get(params.threadId) ?? 0) + 1);
+      this.currentTurns?.delete(params.threadId);
+    }
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      const timer = observedTimeout(clock => {
+        const pending = this.pending.get(id); if (!pending || pending.timedOut) return;
+        pending.timedOut = true;
+        const graceMs = policy.graceMs ?? LATE_RESPONSE_GRACE_MS;
+        const timeoutError = Object.assign(new Error(`${method} timed out`), { code: clock.observationLost ? "operation_observation_lost" : "rpc_timeout", details: { method, request_id: id, timeout_ms: timeoutMs, grace_ms: graceMs, observation: clock.state() } });
+        this.journal.write("request_deadline", timeoutError.details);
+        if (!graceMs) { this.pending.delete(id); reject(timeoutError); return; }
+        pending.timer = observedTimeout(() => {
+          if (this.pending.get(id) !== pending) return;
+          this.pending.delete(id); reject(timeoutError);
+        }, graceMs, { progress: () => pending.progress });
+      }, timeoutMs, { progress: () => { policy.observe?.(); return this.pending.get(id)?.progress; }, onGap: gap => this.journal.write("observation_gap", { ...gap, method, request_id: id }) });
+      const publish = operationProgressReporter();
+      this.pending.set(id, { id, resolve, reject, timer, method, threadId: params.threadId, turnFloor });
+      if (method === "turn/start" && params.threadId) {
+        this.turnObservers ??= new Map(); this.turnObservers.set(params.threadId, { id, turnFloor, publish });
+      }
+      this.send({ jsonrpc: "2.0", id, method, params });
+      if (method === "turn/start") this.journal.write("native_dispatch", { operation_id: this.dispatchOperationId ?? process.env.DD_EVAL_OPERATION_ID ?? null, provider_session_id: params.threadId, native_request_id: id });
+    });
+  }
+  send(value) {
+    this.journal.write("outbound", value);
+    const stdin = this.child?.stdin;
+    if (!stdin || stdin.destroyed) {
+      const error = Object.assign(new Error("Codex app-server stdin is closed"), { code: "bridge_pipe_broken" });
+      this.rejectAll(error);
+      throw error;
+    }
+    try { stdin.write(`${JSON.stringify(value)}\n`); }
+    catch (cause) { const error = nativeObservationError(cause); this.rejectAll(error); throw error; }
+  }
+  rejectAll(error) { for (const pending of this.pending.values()) { clearTimeout(pending.timer); pending.reject(error); } this.pending.clear(); this.turnObservers?.clear(); }
+  async close() {
+    return await closeBridgeProcess(this, async () => { await Promise.all([this.nativeDrain, this.diagnostics]); await this.modelObservations; await this.journal.flush(); });
+  }
+}
+
+async function withBridge(options, action) {
+  const bridge = new CodexBridge(options); let primary, result;
+  try { await bridge.start(); result = await action(bridge); return result; }
+  catch (error) { primary = error; throw error; }
+  finally { try { await bridge.close(); } catch (error) { if (!primary) throw nativeObservationError(error, result === undefined ? {} : { result }); primary.cleanup_error = errorRecord(error); primary.details = { ...primary.details, cleanup_error: primary.cleanup_error }; } }
+}
+function profile(options) { return { harness: "codex-desktop", model: options.model ?? null, reasoning: options.reasoning ?? null }; }
+function threadId(result) { const id = result?.thread?.id ?? result?.threadId; return required(id, "Codex thread id"); }
+function directChildren(bridge, sessionId) { return typeof bridge?.directChildren === "function" ? bridge.directChildren(sessionId) : []; }
+async function observedChildren(bridge, sessionId, phase) {
+  const children = directChildren(bridge, sessionId);
+  let reads = 0;
+  return await Promise.all(children.map(async child => {
+    if (child.status !== "failed" || !child.terminal_turn_id || reads++ >= 16) return child;
+    const observed = await readTurn(bridge, child.provider_session_id, child.terminal_turn_id, true, phase);
+    const turn = observed?.turn;
+    if (turn?.id !== child.terminal_turn_id || turn.status !== child.status) return child;
+    return { ...child, provider_error: nativeTurnError(bridge, child.provider_session_id, turn) ?? child.provider_error,
+      native_turn_items: turnItemEvidence(turn, bridge, child.provider_session_id) };
+  }));
+}
+function codexSessionConfig() { return { ...CODEX_SESSION_CONFIG }; }
+
+async function requestConfiguredThread(bridge, method, params, timeoutMs, policy) {
+  try { return await bridge.request(method, { ...params, config: codexSessionConfig() }, timeoutMs, policy); }
+  catch (error) {
+    const data = error?.details?.data;
+    const key = data?.configKey ?? data?.config_key ?? null;
+    if (error?.code === "rpc_error" && (data?.reason === "config" || String(key ?? "").startsWith("features.multi_agent_v2"))) {
+      throw Object.assign(new Error("Codex runtime rejected the required multi-agent v2 session configuration"), {
+        code: "codex_multi_agent_v2_unavailable", cause: error, details: { method, provider_error: error.details }
+      });
+    }
+    throw error;
+  }
+}
+
+function threadReceipt(thread) {
+  // Thread reads can include the whole transcript even with includeTurns:false.
+  // Item evidence lives in the native history/journal, not each command reply.
+  return { ...thread, ...(Array.isArray(thread.turns) ? { turns: thread.turns.map(turn => ({
+    id: turn?.id ?? null, status: turn?.status ?? null,
+    startedAt: turn?.startedAt ?? null, completedAt: turn?.completedAt ?? null
+  })) } : {}) };
+}
+
+export async function doctor(options = {}) {
+  const codex_cli = parseCodexCliVersion(await commandText(options.bin ?? process.env.DD_CODEX_BIN ?? "codex", ["--version"], { phase: 'native-version' }));
+  return await withBridge(options, async () => ({ harness: "codex-desktop", app_server: "available", observation_scope: "version_and_initialize", observed_runtime: { codex_cli, dd_harness_contract: "dd-codex-harness@1" }, requested_profile: profile(options), observed_at: now() }));
+}
+
+async function observeCodexProfile(bridge, options, id, observed, source) {
+  bridge.requestedProfiles?.set(id, profile(options));
+  await bridge.modelObservations;
+  if (bridge.modelObservationError) throw bridge.modelObservationError;
+  await observeModel({ journal: options.journal ?? bridge.options?.journal, harness: "codex-desktop", sessionId: id,
+    parentSessionId: bridge.descendants?.get(id)?.parent_provider_session_id ?? null, requested: profile(options), observed, source });
+  return observed;
+}
+
+export async function createSession(options) {
+  return await withBridge(options, async (bridge) => await createSessionWithBridge(bridge, options));
+}
+
+export async function createSessionWithBridge(bridge, options) {
+  const cwd = absolute(options.cwd, "--cwd");
+  // dd-codex is the eval-only adapter. Its CODEX_HOME is generated by
+  // dd-flow, so trust only that managed PreToolUse hook for this thread and
+  // do not load user plugin hooks into the isolated evaluator.
+  const result = await requestConfiguredThread(bridge, "thread/start", {
+    cwd,
+    model: options.model ?? null,
+    approvalPolicy: "never",
+    sandbox: "danger-full-access",
+    ephemeral: false
+  });
+  // ThreadStartParams has no reasoning-effort field.  The first turn applies
+  // it, so reporting the Desktop default here would be a false profile drift.
+  return { harness: "codex-desktop", provider_session_id: threadId(result), adapter_session_id: threadId(result), requested_profile: profile(options), observed_profile: await observeCodexProfile(bridge, options, threadId(result), { model: result.model ?? null, reasoning: result.reasoningEffort ?? null, provider: result.modelProvider ?? null }, "thread/start.response"), cwd: result.cwd ?? cwd };
+}
+
+export async function promptSession(options) {
+  return await withBridge(options, async (bridge) => await promptSessionWithBridge(bridge, options));
+}
+
+export async function startSession(options) {
+  return await withBridge(options, async (bridge) => await startSessionWithBridge(bridge, options));
+}
+
+export async function startSessionWithBridge(bridge, options) {
+  options = { ...options, readPhase: codexReadPhase(bridge, options) };
+  options.readPhase.outerClock = new ObservationClock({ timeoutMs: options.livenessTimeoutMs ?? options.timeoutMs ?? CODEX_REQUEST_TIMEOUT_MS,
+    ...options.observationClock, onGap: gap => bridge.journal?.write("observation_gap", { ...gap, phase: "start", session_id: options.sessionId }) });
+  const sessionId = required(options.sessionId, "--session-id"); const cwd = absolute(options.cwd, "--cwd"); const prompt = required(options.prompt, "--prompt");
+  await ensureThreadLoaded(bridge, sessionId, options, cwd);
+  bridge.requestedProfiles?.set(sessionId, profile(options));
+  bridge.finalMessages?.delete(sessionId);
+  options.assertDispatch?.();
+  bridge.assertHookHealthy?.(sessionId);
+  bridge.dispatchOperationId = options.operationId;
+  const started = await bridge.request("turn/start", { threadId: sessionId, input: [{ type: "text", text: prompt }], cwd, model: options.model ?? null, effort: options.reasoning ?? null, approvalPolicy: "never", sandboxPolicy: { type: "dangerFullAccess" } }, ...dispatchBudget(options.readPhase, "turn/start", options.timeoutMs ?? 30_000));
+  const turn = started?.turn ?? started; const turnId = turn?.id ?? null;
+  if (typeof turnId !== "string" || !turnId) throw new Error("Codex did not return a Turn id");
+  return { harness: "codex-desktop", provider_session_id: sessionId, adapter_session_id: sessionId, turn_id: turnId, status: "started", requested_profile: profile(options), observed_profile: { model: null, reasoning: null } };
+}
+
+export async function promptSessionWithBridge(bridge, options) {
+  options = { ...options, readPhase: codexReadPhase(bridge, options) };
+  const clock = new ObservationClock({ timeoutMs: options.livenessTimeoutMs ?? options.timeoutMs ?? 1_800_000, ...options.observationClock, onGap: gap => bridge.journal?.write("observation_gap", { ...gap, phase: "prompt", session_id: options.sessionId }) });
+  options.readPhase.outerClock = clock;
+  const sessionId = required(options.sessionId, "--session-id"); const cwd = absolute(options.cwd, "--cwd"); const prompt = required(options.prompt, "--prompt");
+  validateObservationDuration(options.livenessTimeoutMs ?? options.timeoutMs ?? 1_800_000);
+  await ensureThreadLoaded(bridge, sessionId, options, cwd);
+  // A final-message fallback belongs only to the Turn that produced it.  A
+  // new Turn may start before app-server emits its first item notification;
+  // clearing here prevents the previous receipt from completing the new Turn.
+  bridge.requestedProfiles?.set(sessionId, profile(options));
+  bridge.finalMessages?.delete(sessionId);
+  options.assertDispatch?.();
+  bridge.assertHookHealthy?.(sessionId);
+  bridge.dispatchOperationId = options.operationId;
+  const started = await bridge.request("turn/start", { threadId: sessionId, input: [{ type: "text", text: prompt }], cwd, model: options.model ?? null, effort: options.reasoning ?? null, approvalPolicy: "never", sandboxPolicy: { type: "dangerFullAccess" } }, ...dispatchBudget(options.readPhase, "turn/start", 30_000));
+  const turn = started?.turn ?? started; const turnId = turn?.id ?? null;
+  let completed;
+  try { completed = isTerminalTurnStatus(turn?.status) ? terminalTurn({ turn }, sessionId, turnId, bridge)
+    : await waitForTurn(bridge, sessionId, turnId, options.livenessTimeoutMs ?? options.timeoutMs ?? 1_800_000, options, cwd, clock, turn?.status); }
+  catch (error) {
+    const retained = bridge.turns?.get(turnId);
+    if (retained?.value?.threadId === sessionId && retained.value.turn?.id === turnId && retained.value.turn.status === "completed") {
+      throw Object.assign(new Error("Codex completed natively but mandatory observation failed"), { code: "native_outcome_observation_failed", retryable: false,
+        details: { native_outcome: { harness: "codex-desktop", provider_session_id: sessionId, turn_id: turnId, status: "completed", turn: retained.value.turn }, settled: false, observation_error: errorRecord(error) }, cause: error });
+    }
+    if (error?.code === "turn_interrupted") {
+      try {
+        const observed = await readTurn(bridge, sessionId, turnId, true);
+        if (observed?.turn?.id === turnId && observed.turn.status === error.details?.terminal_status) {
+          error.details.native_turn_items = turnItemEvidence(observed.turn, bridge, sessionId);
+          error.details.provider_error ??= observed.turn.error ?? null;
+        }
+      } catch { /* The primary native terminal failure remains authoritative. */ }
+      try { await bridge.journal?.flush?.(); }
+      catch (observationError) {
+        throw Object.assign(new Error("Codex terminal failure lacks durable native item evidence"), { code: "native_outcome_observation_failed", retryable: false,
+          details: { native_outcome: { provider_session_id: sessionId, turn_id: turnId, status: "failed", provider_error: error.details?.provider_error }, settled: false, observation_error: errorRecord(observationError) }, cause: error });
+      }
+    }
+    if (isObservationLoss(error)) throw Object.assign(new Error("Codex accepted Turn outcome could not be observed", { cause: error }), {
+      code: "operation_observation_lost", retryable: false, details: { provider_session_id: sessionId, turn_id: turnId,
+        operation_id: options.operationId ?? null, phase: "turn_observation", native_dispatch_started: true,
+        native_outcome: "unknown", observation_error: errorRecord(error), history_reads: Object.fromEntries(options.readPhase.history ?? []) }
+    });
+    throw error;
+  }
+  const nativeOutcome = { harness: "codex-desktop", provider_session_id: sessionId, adapter_session_id: sessionId, turn_id: turnId, status: "completed", turn: completed };
+  try {
+    const phase = codexReadPhase(bridge, options);
+    const history = await readCodexHistory(bridge, "thread/read", { threadId: sessionId, includeTurns: true }, phase);
+    const thread = history.available ? history.result.thread
+      : (await readCodexRpc(bridge, "thread/read", { threadId: sessionId, includeTurns: false }, phase)).thread;
+    bridge.assertHookHealthy?.(sessionId);
+    const final = bridge.finalMessages?.get(sessionId);
+    const historyTurn = thread?.turns?.find(item => item?.id === turnId);
+    const completeHistory = history.available && (turnItemEvidence(historyTurn, bridge, sessionId).observed
+      // Preserve the existing idle + readable-history final-message receipt.
+      || completed?.turn?.synthetic === true && Array.isArray(thread.turns) && final?.turnId === turnId && thread.status?.type === "idle");
+    const assistantText = latestAssistantText(completed) ?? latestAssistantText(historyTurn)
+      ?? (final?.turnId === turnId ? latestAssistantText({ items: [final.item] }) : null);
+    if (!completeHistory && (!assistantText || !turnItemEvidence(completed?.turn ?? completed, bridge, sessionId).observed))
+      fail("Codex completed but its current output/items remain unavailable", "operation_observation_lost", { history_error: history.error, provider_session_id: sessionId, turn_id: turnId });
+    if (!completeHistory && (options.model && !thread.model || options.reasoning && !thread.reasoningEffort))
+      fail("Codex completed but its applied profile remains unavailable", "operation_observation_lost", { history_error: history.error, provider_session_id: sessionId, turn_id: turnId });
+    const diagnostics = (bridge.hookDiagnostics?.get(sessionId) ?? []).filter(item => item.root_generation === bridge.hookPromptGenerations?.get(sessionId));
+    const result = { ...nativeOutcome, ...(thread ? { thread: threadReceipt(thread) } : {}), descendants: await observedChildren(bridge, sessionId, phase), ...(assistantText ? { assistant_text: assistantText } : {}), ...(diagnostics.length ? { native_hook_diagnostics: diagnostics } : {}), requested_profile: profile(options), observed_profile: await observeCodexProfile(bridge, options, sessionId, { model: thread?.model ?? null, reasoning: thread?.reasoningEffort ?? null, provider: thread?.modelProvider ?? null }, "thread/read.after_turn") };
+    await bridge.journal?.flush?.();
+    return result;
+  } catch (error) {
+    throw Object.assign(new Error("Codex completed natively but mandatory observation failed"), { code: "native_outcome_observation_failed", retryable: false,
+      details: { native_outcome: nativeOutcome, settled: false, observation_error: errorRecord(error) }, cause: error });
+  }
+}
+
+async function ensureThreadLoaded(bridge, sessionId, options, cwd) {
+  const value = await readCodexRpc(bridge, "thread/read", { threadId: sessionId, includeTurns: false }, options.readPhase);
+  const thread = value?.thread ?? value;
+  if (thread?.status?.type !== "notLoaded") return;
+  await requestConfiguredThread(bridge, "thread/resume", {
+    threadId: sessionId,
+    cwd,
+    model: options.model ?? null,
+    approvalPolicy: "never",
+    sandbox: "danger-full-access"
+  }, ...dispatchBudget(options.readPhase, "thread/resume", 30_000));
+}
+
+async function waitForTurn(bridge, sessionId, turnId, timeoutMs, options, cwd, clock = new ObservationClock({ timeoutMs, onGap: gap => bridge.journal?.write("observation_gap", { ...gap, session_id: sessionId, turn_id: turnId }) }), startStatus) {
+  const readPhase = codexReadPhase(bridge, options);
+  readPhase.clock = clock;
+  readPhase.progress = () => bridge.activityObservations?.get(sessionId) ?? bridge.activity?.get(sessionId);
+  options = { ...options, readPhase };
+  // app-server can briefly expose the new Turn as `interrupted` between the
+  // turn/start response and its turn/started notification. Give that snapshot
+  // one event-loop grace window before treating failure as authoritative.
+  const failureNotBefore = Date.now() + 1_000;
+  const reconcileSnapshot = async (status, threadStatus) => {
+    if (!isAuthoritativeTerminal(bridge, turnId, status, threadStatus, failureNotBefore)) return false;
+    if (status === "completed" || startStatus !== "inProgress" || bridge.turns.get(turnId)?.status === "completed") return true;
+    // A provisional failure can contradict the accepted start before its
+    // delayed notification arrives. Recheck this Turn, never start another.
+    const current = await readTurn(bridge, sessionId, turnId, true, readPhase);
+    return bridge.turns.get(turnId)?.status === "completed" || current?.turn?.status === status
+      && isAuthoritativeTerminal(bridge, turnId, status, current.threadStatus, failureNotBefore);
+  };
+  let nextStoredReadAt = Date.now();
+  while (true) {
+    bridge.assertHookHealthy?.(sessionId);
+    const known = bridge.turns.get(turnId) ?? bridge.turns.get(sessionId); if (known?.status === "completed" && (!known.threadId || known.threadId === sessionId)) return terminalTurn(known.value, sessionId, turnId, bridge);
+    const expired = clock.sample(bridge.activityObservations?.get(sessionId) ?? bridge.activity?.get(sessionId));
+    if (expired || Date.now() >= nextStoredReadAt) {
+      const stored = await readTurn(bridge, sessionId, turnId, false, readPhase);
+      if (stored?.turn && await reconcileSnapshot(stored.turn.status, stored.threadStatus)) return terminalTurn({ turn: stored.turn }, sessionId, turnId, bridge);
+      // A loaded app-server can retain a stale `active` Thread state after a
+      // provider-side interruption. The persisted turn page is independent of
+      // that live subscription and is the compact authority for its terminal
+      // status. Hydrate only when that read surface is unavailable.
+      const persisted = await readPersistedTurn(bridge, sessionId, turnId, readPhase);
+      if (persisted.turn && await reconcileSnapshot(persisted.turn.status, persisted.threadStatus ?? stored?.threadStatus)) return terminalTurn({ turn: persisted.turn }, sessionId, turnId, bridge);
+      const native = bridge.turns.get(turnId);
+      if (native?.status === "completed" && (!native.threadId || native.threadId === sessionId)) return terminalTurn(native.value, sessionId, turnId, bridge);
+      // Desktop may unload an idle Thread immediately after an interrupted
+      // Turn. Reload it once before polling again: otherwise the compact
+      // status remains `notLoaded` forever and hides the terminal Turn.
+      if (stored?.threadStatus === "notLoaded") {
+        await ensureThreadLoaded(bridge, sessionId, options, cwd);
+        const hydrated = await readTurn(bridge, sessionId, turnId, true, readPhase);
+        if (hydrated?.turn && await reconcileSnapshot(hydrated.turn.status, hydrated.threadStatus)) return terminalTurn({ turn: hydrated.turn }, sessionId, turnId, bridge);
+      }
+      // Some app-server versions correctly omit turns for a compact read.
+      // Once the thread is idle, hydrate exactly once to recover the terminal
+      // turn instead of waiting for the global timeout.
+      if (stored?.threadStatus === "idle") {
+        const hydrated = persisted.hydrated ? persisted : await readTurn(bridge, sessionId, turnId, true, readPhase);
+        // "idle" only describes the Thread.  Some app-server builds retain
+        // an inProgress Turn after emitting the final agent message; treating
+        // that stale Turn as terminal incorrectly aborts an otherwise usable
+        // worker session.
+        if (hydrated?.turn && await reconcileSnapshot(hydrated.turn.status, hydrated.threadStatus)) return terminalTurn({ turn: hydrated.turn }, sessionId, turnId, bridge);
+      }
+      // Some app-server builds emit a final agent message but omit both the
+      // terminal event and the compact turn record. Wait briefly, hydrate once,
+      // then preserve that message as the terminal receipt if still omitted.
+      const final = bridge.finalMessages?.get(sessionId);
+      // Agent messages are streamed as completed items while a Turn is still
+      // reasoning and calling tools.  They are terminal evidence only after
+      // app-server reports the Thread idle.
+      if (final?.turnId === turnId && stored?.threadStatus === "idle" && Date.now() - final.completedAt >= 1_000) {
+        const hydrated = await readTurn(bridge, sessionId, turnId, true, readPhase);
+        if (hydrated?.turn && await reconcileSnapshot(hydrated.turn.status, hydrated.threadStatus)) return terminalTurn({ turn: hydrated.turn }, sessionId, turnId, bridge);
+        if (hydrated?.threadStatus === "idle" && !isTerminalTurnStatus(hydrated.turn?.status))
+          return terminalTurn({ turn: { id: turnId, status: "completed", synthetic: true, final_message: final.item } }, sessionId, turnId, bridge);
+      }
+      nextStoredReadAt = Date.now() < failureNotBefore ? failureNotBefore : Date.now() + 15_000;
+    }
+    const terminal = bridge.turns.get(turnId); if (terminal?.status === "completed" && (!terminal.threadId || terminal.threadId === sessionId)) return terminalTurn(terminal.value, sessionId, turnId, bridge);
+    if (expired && clock.sample(bridge.activityObservations?.get(sessionId) ?? bridge.activity?.get(sessionId))) fail("Codex native outcome remains unknown after its silence window", "operation_observation_lost", { provider_session_id: sessionId, turn_id: turnId, operation_id: options.operationId ?? null, native_dispatch_started: true, phase: "turn_observation", native_outcome: "unknown", history_reads: Object.fromEntries(readPhase.history ?? []) });
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+}
+
+function terminalTurn(value, sessionId, turnId, bridge) {
+  // A terminal event may arrive while an older snapshot RPC is in flight.
+  const observed = bridge.turns.get(turnId);
+  if (observed?.status === "completed" && (!observed.threadId || observed.threadId === sessionId)) value = observed.value;
+  const turn = value?.turn ?? value;
+  if (turn?.id && turn.id !== turnId || value?.threadId && value.threadId !== sessionId) fail("Codex terminal Turn identity does not match the requested Session/Turn", "turn_identity_mismatch", { provider_session_id: sessionId, turn_id: turnId, native_thread_id: value?.threadId ?? null, native_turn_id: turn?.id ?? null });
+  const providerError = nativeTurnError(bridge, sessionId, turn);
+  if (turn?.status && turn.status !== "completed") fail(`Codex turn ${turnId ?? "unknown"} ended as ${turn.status}`, "turn_interrupted", { provider_session_id: sessionId, turn_id: turnId, native_turn_id: turn.id ?? null, terminal_status: turn.status, observed_at: now(),
+    provider_error: providerError, native_turn_items: turnItemEvidence(turn, bridge, sessionId) });
+  return value;
+}
+
+function nativeTurnError(bridge, sessionId, turn) {
+  const native = bridge.nativeErrors?.get(`${sessionId}:${turn?.id}`);
+  const error = turn?.error && typeof turn.error === "object" && native?.error && typeof native.error === "object"
+    ? { ...native.error, ...turn.error } : turn?.error ?? native?.error ?? (turn?.codexErrorInfo ? { codexErrorInfo: turn.codexErrorInfo } : null);
+  return error && native?.willRetry !== undefined && typeof error === "object" ? { ...error, willRetry: native.willRetry } : error;
+}
+
+export function turnItemEvidence(turn, bridge, sessionId) {
+  const items = turn?.items;
+  const pending = item => {
+    const kind = classifyCodexItem(item?.type);
+    if (kind === "non_tool") return false;
+    if (kind === "unknown") return true;
+    const phase = bridge?.itemPhases?.get(JSON.stringify([sessionId, turn?.id, item?.id]));
+    if (phase && (phase.type !== item?.type || phase.status !== null && item?.status !== undefined && phase.status !== item.status)) return true;
+    if (phase && ![null, "completed", "failed", "declined", "interrupted"].includes(phase.status)) return true;
+    return !["completed", "failed", "declined", "interrupted"].includes(item?.status) && !(phase && phase.type === item?.type && (item?.status === undefined || item?.status === null));
+  };
+  return Array.isArray(items) && turn?.itemsView !== "notLoaded" ? { observed: true, count: items.length, types: items.map(item => item?.type ?? "unknown"),
+    items: items.map(item => {
+      const phase = bridge?.itemPhases?.get(JSON.stringify([sessionId, turn?.id, item?.id]));
+      return { id: item?.id ?? null, type: item?.type ?? "unknown", status: item?.status ?? null,
+        ...(phase && !pending(item) ? { completion_phase: { session_id: sessionId, turn_id: turn.id, item_id: item.id, status: phase.status, source: "codex.item/completed" } } : {}) };
+    }),
+    pending: items.some(pending),
+    possible_effects: items.some(item => classifyCodexItem(item?.type) !== "non_tool") } : { observed: false };
+}
+
+export { terminalProviderOverload as terminalCodexOverload } from "./provider-overload-policy.mjs";
+
+function isTerminalTurnStatus(status) { return ["completed", "failed", "interrupted", "cancelled"].includes(status); }
+function isAuthoritativeTerminal(bridge, turnId, status, threadStatus, failureNotBefore) {
+  if (!isTerminalTurnStatus(status)) return false;
+  if (status === "completed") return true;
+  if (Date.now() < failureNotBefore) return false;
+  return !(bridge.turns.get(turnId)?.status === "running" && threadStatus === "active");
+}
+
+async function readTurn(bridge, sessionId, turnId, includeTurns, phase) {
+  if (!turnId) return null;
+  try {
+    const history = includeTurns ? await readCodexHistory(bridge, "thread/read", { threadId: sessionId, includeTurns }, phase) : null;
+    if (history && !history.available) return { turn: null, threadStatus: null, historyAvailable: false };
+    const result = history?.result ?? await readCodexRpc(bridge, "thread/read", { threadId: sessionId, includeTurns }, phase);
+    const thread = result?.thread ?? result;
+    return { turn: Array.isArray(thread?.turns) ? thread.turns.find((turn) => turn?.id === turnId) ?? null : null, threadStatus: thread?.status?.type ?? null };
+  } catch (error) { bridge.assertHookHealthy?.(sessionId); throw error; }
+}
+
+async function readPersistedTurn(bridge, sessionId, turnId, phase) {
+  try {
+    const history = await readCodexHistory(bridge, "thread/turns/list", { threadId: sessionId, limit: 20, sortDirection: "desc", itemsView: "summary" }, phase);
+    if (!history.available) return { ...await readTurn(bridge, sessionId, turnId, true, phase), hydrated: true };
+    return { available: history.available, turn: history.result?.data.find((turn) => turn?.id === turnId) ?? null };
+  } catch (error) { bridge.assertHookHealthy?.(sessionId); throw error; }
+}
+
+function latestAssistantText(value) {
+  const messages = value?.messages ?? value?.items ?? value?.turn?.items ?? (value?.turn?.final_message ? [value.turn.final_message] : []);
+  if (!Array.isArray(messages)) return null;
+  for (const message of [...messages].reverse()) {
+    if (message?.role !== "assistant" && message?.type !== "agentMessage") continue;
+    const parts = message.content ?? message.parts ?? [];
+    if (typeof message.text === "string") return message.text;
+    if (Array.isArray(parts)) {
+      const text = parts.map((part) => typeof part?.text === "string" ? part.text : typeof part?.content === "string" ? part.content : "").filter(Boolean).join("\n");
+      if (text) return text;
+    }
+  }
+  return null;
+}
+
+export async function inspectSession(options) {
+  return await withBridge(options, async (bridge) => await inspectSessionWithBridge(bridge, options));
+}
+
+export async function inspectSessionWithBridge(bridge, options) {
+  const phase = options.readPhase ?? codexReadPhase(bridge, options);
+  const sessionId = required(options.sessionId, "--session-id"); const value = await readCodexRpc(bridge, "thread/read", { threadId: sessionId, includeTurns: false }, phase); const thread = value?.thread ?? value;
+  const terminal = options.turnId ? retainedCodexTurn(bridge, sessionId, options.turnId) ?? (await readTurn(bridge, sessionId, options.turnId, true, phase))?.turn : null;
+  const exact = terminal?.id === options.turnId && terminal?.status === "failed" ? { terminal_turn_id: terminal.id, terminal_status: terminal.status, provider_error: nativeTurnError(bridge, sessionId, terminal), native_turn_items: turnItemEvidence(terminal, bridge, sessionId) } : {};
+  return { harness: "codex-desktop", provider_session_id: sessionId, adapter_session_id: sessionId, status: thread.status ?? null, thread: threadReceipt(thread), ...exact, descendants: await observedChildren(bridge, sessionId, phase), requested_profile: profile(options), observed_profile: await observeCodexProfile(bridge, options, sessionId, { model: thread.model ?? null, reasoning: thread.reasoningEffort ?? null, provider: thread.modelProvider ?? null }, "thread/read") };
+}
+
+export async function cancelSession(options) {
+  return await withBridge(options, async (bridge) => await cancelSessionWithBridge(bridge, options));
+}
+
+export async function cancelSessionWithBridge(bridge, options) {
+  const phase = options.readPhase ?? codexReadPhase(bridge, options);
+  const sessionId = required(options.sessionId, "--session-id");
+  let turnId = options.turnId ?? null;
+  if (!turnId) {
+    const currentId = bridge.currentTurns?.get(sessionId);
+    const retained = retainedCodexTurn(bridge, sessionId, currentId);
+    turnId = currentId && !isTerminalTurnStatus(retained?.status) ? currentId : null;
+    if (!turnId) {
+      const history = await readCodexHistory(bridge, "thread/read", { threadId: sessionId, includeTurns: true }, phase);
+      if (!history.available || !Array.isArray(history.result.thread.turns)
+        || history.result.thread.turns.some(turn => typeof turn?.id !== "string" || !turn.id.trim()
+          || turn.status !== "inProgress" && !isTerminalTurnStatus(turn.status)))
+        fail("Codex active Turn cannot be established from incomplete history", "operation_observation_lost", { provider_session_id: sessionId, native_outcome: "unknown", history_error: history.error });
+      turnId = [...history.result.thread.turns].reverse().find((turn) => turn.status === "inProgress")?.id ?? null;
+    }
+  }
+  if (!turnId) fail("Codex Session has no active Turn to interrupt", "turn_not_active");
+  await bridge.request("turn/interrupt", { threadId: sessionId, turnId });
+  // Interrupt acknowledgement is not a provider terminal receipt. Reconcile
+  // observes the Thread before the runner records terminal cancellation.
+  return { harness: "codex-desktop", provider_session_id: sessionId, adapter_session_id: sessionId, turn_id: turnId, cancelled: true, settled: false };
+}
+
+export async function promptFromFile(file) { return await readFile(absolute(file, "--prompt-file"), "utf8"); }