@deksden-com/dd-flow-cli 0.9.0-beta.7 → 0.9.0-beta.74

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

@@ -0,0 +1,141 @@
+import { captureDispatchGuard, cancelPendingDispatch } from "./dispatch-fence.mjs";
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, lstat, mkdir, open, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import net from "node:net";
+import { durableDaemonDispatch } from "./daemon-operations.mjs";
+import { observedTimeout } from "./observation-clock.mjs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { waitForSettlement } from "./session-settlement.mjs";
+import { errorRecord } from "./operation-errors.mjs";
+import { CodexBridge, cancelSessionWithBridge, createSessionWithBridge, inspectSessionWithBridge, promptSessionWithBridge, startSessionWithBridge } from "./dd-codex.mjs";
+import { prepareRuntimeOwner, cleanupFailedStart, confirmDaemonProcess, confirmDaemonStopped, finishDaemonProcess, heartbeatDaemonProcess, registerDaemonProcess, stopProcessGroup } from "./managed-daemon.mjs";
+
+const requestSchema = "dd-codex/daemon-request@1";
+const responseSchema = "dd-codex/daemon-response@1";
+const stateSchema = "dd-codex/daemon-state@1";
+const absolute = (value, label) => { if (!value || !path.isAbsolute(value)) throw Object.assign(new Error(`${label} must be an absolute path`), { code: "invalid_path" }); return path.resolve(value); };
+function locations(stateDir) { const dir = absolute(stateDir, "--state-dir"); const local = path.join(dir, "daemon.sock"); return { dir, socket: Buffer.byteLength(local) < 100 ? local : `/tmp/dd-codex-${createHash("sha256").update(dir).digest("hex").slice(0, 24)}.sock`, state: path.join(dir, "daemon.json"), log: path.join(dir, "daemon.log") }; }
+async function readState(file) { try { return JSON.parse(await readFile(file, "utf8")); } catch (error) { if (error.code === "ENOENT") return null; throw error; } }
+async function writeState(file, value) { const temp = `${file}.${process.pid}.tmp`; await writeFile(temp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 }); await rename(temp, file); }
+async function removeSocket(socket) { try { const info = await lstat(socket); if (!info.isSocket()) throw Object.assign(new Error("refusing to remove non-socket daemon path"), { code: "unsafe_socket" }); await unlink(socket); } catch (error) { if (error.code !== "ENOENT") throw error; } }
+const errorPayload = errorRecord;
+const terminalTurn = turn => ["completed", "interrupted", "failed", "cancelled"].includes(turn?.status);
+export function settledCodexSession(status, latestTurn, active) {
+  if (status === "idle") return true;
+  if (status === "notLoaded") return !latestTurn || terminalTurn(latestTurn);
+  // `systemError` alone is not evidence that the provider stopped. A current
+  // terminal Turn plus no daemon operation is the narrow settled case.
+  return status === "systemError" && !active && terminalTurn(latestTurn);
+}
+
+async function observeCodexSessions(bridge, options, sessions, active, remember = () => {}) {
+  // Expand trusted native topology before profile/history diagnostics: an
+  // unavailable root must not hide its already discovered siblings/children.
+  for (const id of sessions) for (const child of bridge.directChildren?.(id) ?? []) {
+    if (typeof child.provider_session_id !== "string" || !child.provider_session_id.trim()) throw Object.assign(new Error("Codex child has no native identity"), { code: "invalid_session_topology" });
+    sessions.add(child.provider_session_id); remember(child.provider_session_id);
+  }
+  const unsettled = [], observations = [];
+  for (const sessionId of sessions) {
+    const observed = await inspectSessionWithBridge(bridge, { ...options, sessionId });
+    for (const child of observed.descendants ?? []) { sessions.add(child.provider_session_id); remember(child.provider_session_id); }
+    const status = observed.status?.type ?? observed.status;
+    const stored = ["notLoaded", "systemError"].includes(status) ? await bridge.request("thread/turns/list", { threadId: sessionId, limit: 1, sortDirection: "desc", itemsView: "summary" }, 5_000) : null;
+    const settled = settledCodexSession(status, stored?.data?.[0] ?? null, active());
+    if (!settled) unsettled.push(sessionId);
+    observations.push({ ...observed, settled });
+  }
+  return { sessions: unsettled.reverse(), active: Boolean(active()), observations };
+}
+
+export async function inspectCodexTree(bridge, options, { remember = () => {}, active = () => null } = {}) {
+  const sessions = new Set([options.sessionId]);
+  const observed = await observeCodexSessions(bridge, options, sessions, active, remember);
+  return { ...observed.observations[0], settled: !observed.active && !observed.sessions.length, unsettled_sessions: observed.sessions, tree_session_ids: [...sessions], tree_observations: observed.observations.map(item => ({ provider_session_id: item.provider_session_id, status: item.status, settled: item.settled })) };
+}
+
+export async function cancelCodexTree(bridge, options, { remember = () => {}, active = () => null, timeoutMs = 5_000 } = {}) {
+  const sessions = new Set([options.sessionId]);
+  const settlement = await waitForSettlement({
+    timeoutMs, knownSessions: () => [...sessions],
+    cancel: async sessionId => {
+      try { await cancelSessionWithBridge(bridge, { ...options, sessionId, turnId: null }); }
+      catch (error) { if (error.code !== "turn_not_active") throw error; }
+    },
+    observe: () => observeCodexSessions(bridge, options, sessions, active, remember)
+  });
+  return { harness: "codex-desktop", provider_session_id: options.sessionId, adapter_session_id: options.sessionId, cancelled: true, settled: true, tree_session_ids: [...sessions], cleanup_errors: settlement.cleanup_errors, tree_observations: settlement.observations.map(item => ({ provider_session_id: item.provider_session_id, status: item.status, settled: item.settled })) };
+}
+
+export async function callDaemon(stateDir, operation, params = {}, timeoutMs = 30_000) {
+  const target = locations(stateDir); const request = { schema_id: requestSchema, id: process.env.DD_EVAL_OPERATION_ID ?? randomUUID(), operation, params };
+  return await new Promise((resolve, reject) => {
+    const client = net.createConnection(target.socket); let buffer = ""; let settled = false; const timer = operation === "session.prompt" ? null : observedTimeout(() => finish(Object.assign(new Error(`${operation} timed out`), { code: "daemon_timeout", retryable: true })), timeoutMs);
+    const finish = (error, value) => { if (settled) return; settled = true; clearTimeout(timer); client.destroy(); error ? reject(error) : resolve(value); };
+    client.setEncoding("utf8"); client.on("connect", () => client.write(`${JSON.stringify(request)}\n`)); client.on("error", (error) => finish(Object.assign(error, { code: "daemon_not_running", retryable: true })));
+    client.on("end", () => finish(Object.assign(new Error("daemon closed the request without a response"), { code: "daemon_connection_closed", retryable: true })));
+    client.on("close", () => finish(Object.assign(new Error("daemon connection closed without a response"), { code: "daemon_connection_closed", retryable: true })));
+    client.on("data", (chunk) => { buffer += chunk; const at = buffer.indexOf("\n"); if (at < 0) return; try { const response = JSON.parse(buffer.slice(0, at)); if (response.schema_id !== responseSchema || response.id !== request.id) throw new Error("invalid daemon response"); response.ok ? finish(null, response.result) : finish(Object.assign(new Error(response.error?.message ?? "daemon error"), response.error)); } catch (error) { finish(Object.assign(error, { code: "daemon_protocol" })); } });
+  });
+}
+
+export async function startDaemon(options) {
+  const paths = locations(options.stateDir); const cwd = absolute(options.cwd, "--cwd"); const config = { cwd, journal: absolute(options.journal, "--journal"), bin: options.bin ?? null, ddFlowBin: options.ddFlowBin ? absolute(options.ddFlowBin, "--dd-flow-bin") : null, ddFlowHome: options.ddFlowHome ? absolute(options.ddFlowHome, "--dd-flow-home") : null, projectRoot: options.projectRoot ? absolute(options.projectRoot, "--project-root") : cwd, resourceHome: process.env.DD_FLOW_RESOURCE_HOME ? absolute(process.env.DD_FLOW_RESOURCE_HOME, "DD_FLOW_RESOURCE_HOME") : null, env: options.ddFlowHome ? { DD_FLOW_HOME: absolute(options.ddFlowHome, "--dd-flow-home") } : {} };
+  await prepareRuntimeOwner(config, paths.dir);
+  await mkdir(paths.dir, { recursive: true, mode: 0o700 }); await chmod(paths.dir, 0o700);
+  try { const status = await callDaemon(paths.dir, "daemon.status", {}, 1_000); if (JSON.stringify(status.config) !== JSON.stringify(config)) throw Object.assign(new Error("running daemon has a different configuration"), { code: "daemon_config_mismatch" }); return { ...status, already_running: true }; } catch (error) { if (!["daemon_not_running", "daemon_timeout"].includes(error.code)) throw error; }
+  const previous = await readState(paths.state); if (previous?.shutdown_state === "running") throw Object.assign(new Error("previous dd-codex daemon died; do not reuse its state directory"), { code: "invalid_harness_crash" });
+  if (previous?.shutdown_state === "clean") await authorizeRetainedDaemonResume(paths.dir, previous, options.sessionId, config);
+  await removeSocket(paths.socket); const resourceProcess = await registerDaemonProcess(config, { kind: "codex-daemon", owner: `codex:${path.basename(paths.dir)}`, operation: `codex-daemon:${path.basename(paths.dir)}`, stdout: paths.log, stderr: paths.log }); const state = { schema_id: stateSchema, daemon_id: randomUUID(), pid: null, cwd: config.cwd, journal: config.journal, config, socket: paths.socket, started_at: new Date().toISOString(), shutdown_state: "starting", sessions: previous?.sessions ?? [], resource_process: resourceProcess }; await writeState(paths.state, state);
+  const log = await open(paths.log, "a", 0o600); const child = spawn(process.execPath, [options.entryPath, "daemon", "serve", "--state-dir", paths.dir], { cwd: config.cwd, detached: true, stdio: ["ignore", log.fd, log.fd] }); child.unref(); await log.close();
+  try { await confirmDaemonProcess(config, resourceProcess, child); const deadline = Date.now() + 15_000; while (Date.now() < deadline) { await new Promise((resolve) => setTimeout(resolve, 100)); try { return await callDaemon(paths.dir, "daemon.status", {}, 1_000); } catch (error) { if (!["daemon_not_running", "daemon_timeout"].includes(error.code)) throw error; } } throw Object.assign(new Error("daemon did not become ready"), { code: "daemon_start_failed" }); }
+  catch (error) { await cleanupFailedStart(config, resourceProcess, child, error); throw error; }
+}
+export async function stopDaemon(options) { const timeoutMs = options.timeoutMs ?? 30_000; return await confirmDaemonStopped(() => callDaemon(options.stateDir, "daemon.stop", { cancelTree: options.cancelTree === true }, timeoutMs), locations(options.stateDir).socket, timeoutMs); }
+
+export async function serveDaemon(stateDir) {
+  const paths = locations(stateDir); const state = await readState(paths.state); if (!state || state.schema_id !== stateSchema) throw Object.assign(new Error("daemon state missing"), { code: "daemon_state_missing" });
+  const bridge = new CodexBridge({ ...state.config, env: { ...state.config.env, DD_FLOW_DAEMON_ID: state.daemon_id } }); await bridge.start(); const sessions = new Set(state.sessions ?? []); let active = null; let server; let persist = Promise.resolve();
+  const save = (patch = {}) => { Object.assign(state, patch, { pid: process.pid, updated_at: new Date().toISOString(), sessions: [...sessions] }); const snapshot = structuredClone(state); persist = persist.then(() => writeState(paths.state, snapshot)).then(() => heartbeatDaemonProcess(snapshot.config, snapshot.resource_process).catch(() => {})); return persist; };
+  const dispatch = async (operation, params) => {
+    const assertDispatch = captureDispatchGuard(bridge);
+    if (operation === "daemon.status") return { daemon_id: state.daemon_id, pid: process.pid, cwd: state.cwd, journal: state.journal, config: state.config, sessions: [...sessions], active_operation: active, shutdown_state: state.shutdown_state };
+    // The runner may need to retire an orphaned daemon after its caller was
+    // interrupted. `daemon.stop` is the one control operation that remains
+    // available while a request is marked active; callers must first prove the
+    // provider Session itself is idle.
+    if (operation === "daemon.stop") {
+      if (params.cancelTree) cancelPendingDispatch(bridge);
+      if (active && !params.cancelTree) throw Object.assign(new Error("productive operation is running"), { code: "tree_not_settled" });
+      await waitForSettlement({
+        knownSessions: () => [...sessions],
+        observe: () => observeCodexSessions(bridge, state.config, sessions, () => active),
+        ...(params.cancelTree ? { cancel: async sessionId => { try { await cancelSessionWithBridge(bridge, { ...state.config, sessionId }); } catch (error) { if (error.code !== "turn_not_active") throw error; } } } : {})
+      });
+      await save({ active_tree: false });
+      return { stopped: true, clean: true, _shutdown: true };
+    }
+    if (active && !["session.inspect", "session.cancel"].includes(operation)) throw Object.assign(new Error(`${active} is in progress`), { code: "operation_busy", retryable: true });
+    if (operation === "session.create") { active = operation; try { await save({ active_operation: active }); const result = await createSessionWithBridge(bridge, { ...state.config, ...params }); sessions.add(result.provider_session_id); return result; } finally { active = null; await save({ active_operation: null }); } }
+    if (operation === "session.prompt") { sessions.add(params.sessionId); active = operation; try { await save({ active_operation: active }); return await promptSessionWithBridge(bridge, { ...state.config, ...params, assertDispatch }); } finally { active = null; await save({ active_operation: null }); } }
+    if (operation === "session.start") { sessions.add(params.sessionId); active = operation; try { await save({ active_operation: active }); return await startSessionWithBridge(bridge, { ...state.config, ...params, assertDispatch }); } finally { active = null; await save({ active_operation: null }); } }
+    if (operation === "session.inspect" || operation === "session.resume") {
+      const owned = new Set(sessions);
+      for (const id of owned) for (const child of bridge.directChildren?.(id) ?? []) owned.add(child.provider_session_id);
+      if (!owned.has(params.sessionId)) throw Object.assign(new Error("inspection Session is not owned by this daemon"), { code: "session_identity_mismatch" });
+      try { return await inspectCodexTree(bridge, { ...state.config, ...params }, { remember: id => sessions.add(id), active: () => active }); }
+      finally { await save(); }
+    }
+    if (operation === "session.cancel") {
+      if (!sessions.has(params.sessionId)) throw Object.assign(new Error("cancellation Session is not owned by this daemon"), { code: "session_identity_mismatch" });
+      cancelPendingDispatch(bridge);
+      try { return await cancelCodexTree(bridge, { ...state.config, ...params }, { remember: id => sessions.add(id), active: () => active }); }
+      finally { await save(); }
+    }
+    throw Object.assign(new Error(`unknown operation: ${operation}`), { code: "unknown_operation" });
+  };
+await removeSocket(paths.socket); server = net.createServer((connection) => { connection.setEncoding("utf8"); let buffer = ""; connection.on("data", (chunk) => { buffer += chunk; const at = buffer.indexOf("\n"); if (at < 0) return; const line = buffer.slice(0, at); buffer = buffer.slice(at + 1); void (async () => { let request; try { request = JSON.parse(line); if (request.schema_id !== requestSchema || !request.id || !request.operation) throw Object.assign(new Error("invalid daemon request"), { code: "daemon_protocol" }); const result = await durableDaemonDispatch(paths.dir, request, () => dispatch(request.operation, request.params ?? {}), () => dispatch("session.inspect", request.params ?? {})); connection.end(`${JSON.stringify({ schema_id: responseSchema, id: request.id, ok: true, result: { ...result, _shutdown: undefined } })}\n`); if (result._shutdown) { await bridge.close(); await save({ shutdown_state: "clean", stopped_at: new Date().toISOString() }); await finishDaemonProcess(state.config, state.resource_process); server.close(() => process.exit(0)); await removeSocket(paths.socket); } } catch (error) { if (connection.writableEnded) { await save({ shutdown_state: "cleanup_failed", cleanup_error: errorPayload(error) }); return; } connection.end(`${JSON.stringify({ schema_id: responseSchema, id: request?.id ?? null, ok: false, error: errorPayload(error) })}\n`); } })(); }); });
+  await new Promise((resolve, reject) => { server.once("error", reject); server.listen(paths.socket, resolve); }); await chmod(paths.socket, 0o600); await save({ shutdown_state: "running", active_operation: null }); return await new Promise(() => {});
+}
+import { authorizeRetainedDaemonResume } from "./driver-recovery.mjs";

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

@@ -0,0 +1,438 @@
+import { spawn } from "node:child_process";
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import readline from "node:readline";
+import { stopProcessGroup } from "./managed-daemon.mjs";
+import { ObservationClock, observedTimeout } from "./observation-clock.mjs";
+import { observeModel } from "./model-observations.mjs";
+
+const LATE_RESPONSE_GRACE_MS = 5_000;
+
+// 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];
+}
+
+function commandText(bin, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(bin, args, { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = ""; let stderr = "";
+    child.stdout.setEncoding("utf8").on("data", (chunk) => { stdout += chunk; });
+    child.stderr.setEncoding("utf8").on("data", (chunk) => { stderr += chunk; });
+    child.on("error", reject);
+    child.on("exit", (code) => code === 0 ? resolve(stdout) : reject(Object.assign(new Error(`Codex CLI version failed: ${stderr.trim() || code}`), { code: "codex_version_unavailable" })));
+  });
+}
+
+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`)); }
+  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.finalMessages = new Map(); this.descendants = new Map(); this.journal = new Journal(options.journal); this.stderr = ""; this.requestedProfiles = new Map(); this.modelObservations = Promise.resolve(); }
+
+  async start() {
+    const bin = this.options.bin ?? process.env.DD_CODEX_BIN ?? "codex";
+    this.child = spawn(bin, ["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.child.stderr.setEncoding("utf8").on("data", (chunk) => { this.stderr += String(chunk); this.journal.write("stderr", { text: String(chunk) }); });
+    this.child.stdin?.on("error", (error) => this.rejectAll(Object.assign(error, { code: error.code ?? "bridge_pipe_broken" })));
+    this.child.on("error", (error) => this.rejectAll(error));
+    this.child.on("exit", (code) => this.rejectAll(Object.assign(new Error(`Codex app-server exited ${code}${this.stderr.trim() ? `: ${this.stderr.trim()}` : ""}`), { code: "bridge_exited" })));
+    readline.createInterface({ input: this.child.stdout }).on("line", (line) => this.receive(line));
+    await this.request("initialize", { clientInfo: { name: "dd-codex", version: "0.1.0" }, capabilities: { optOutNotificationMethods: [], experimentalApi: true } });
+  }
+
+  receive(line) {
+    let message; try { message = JSON.parse(line); } catch { this.journal.write("malformed", { line }); return; }
+    this.observeTopology(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(error => { this.modelObservationError = error; this.rejectAll(error); });
+      }
+    }
+    if (message.id === undefined && (message.method?.startsWith("item/") || message.method === "turn/started" || message.method === "thread/tokenUsage/updated")) {
+      this.activity ??= new Map();
+      const visited = new Set();
+      let id = message.params?.threadId;
+      while (id && !visited.has(id)) {
+        visited.add(id); this.activity.set(id, (this.activity.get(id) ?? 0) + 1);
+        id = this.descendants.get(id)?.parent_provider_session_id;
+      }
+    }
+    // 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") {
+      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.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 === "turn/completed") this.turns.set(message.params?.turn?.id ?? message.params?.threadId, { status: "completed", value: message.params });
+    if (message.method === "turn/started") this.turns.set(message.params?.turn?.id ?? message.params?.threadId, { status: "running", value: message.params });
+    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, completedAt: Date.now() });
+  }
+
+  // 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) {
+    if (!value || typeof value !== "object" || depth > 8) return;
+    if (Array.isArray(value)) { for (const item of value) this.observeTopology(item, depth + 1); return; }
+    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 || child === value.senderThreadId) continue;
+        this.descendants.set(child, { provider_session_id: child, parent_provider_session_id: value.senderThreadId,
+          status: value.agentsStates?.[child]?.status ?? "unknown", source: "codex.app_server" });
+      }
+    }
+    const id = value.threadId ?? value.id ?? null;
+    const parent = value.parentThreadId ?? value.parent_thread_id ?? null;
+    if (typeof id === "string" && id && typeof parent === "string" && parent) {
+      this.descendants.set(id, { provider_session_id: id, parent_provider_session_id: parent, status: value.status?.type ?? value.status ?? "unknown", source: "codex.app_server" });
+    }
+    for (const child of Object.values(value)) this.observeTopology(child, depth + 1);
+  }
+
+  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 ?? 120_000) {
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      const timer = observedTimeout(() => {
+        const pending = this.pending.get(id); if (!pending || pending.timedOut) return;
+        pending.timedOut = true;
+        const timeoutError = Object.assign(new Error(`${method} timed out`), { code: "rpc_timeout", details: { method, request_id: id, timeout_ms: timeoutMs, grace_ms: LATE_RESPONSE_GRACE_MS } });
+        this.journal.write("request_deadline", timeoutError.details);
+        pending.timer = observedTimeout(() => {
+          if (this.pending.get(id) !== pending) return;
+          this.pending.delete(id); reject(timeoutError);
+        }, LATE_RESPONSE_GRACE_MS);
+      }, timeoutMs, { onGap: gap => this.journal.write("observation_gap", { ...gap, method, request_id: id }) });
+      this.pending.set(id, { resolve, reject, timer, method }); this.send({ jsonrpc: "2.0", id, method, params });
+    });
+  }
+  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 (error) { this.rejectAll(Object.assign(error, { code: error.code ?? "bridge_pipe_broken" })); throw error; }
+  }
+  rejectAll(error) { for (const pending of this.pending.values()) { clearTimeout(pending.timer); pending.reject(error); } this.pending.clear(); }
+  async close() {
+    if (!this.child) return;
+    this.child.stdin.end();
+    await Promise.race([new Promise((resolve) => this.child.once("exit", resolve)), new Promise((resolve) => setTimeout(resolve, 2_000))]);
+    await stopProcessGroup(this.child, 2_000);
+    await this.modelObservations;
+    await this.journal.flush();
+  }
+}
+
+async function withBridge(options, action) { const bridge = new CodexBridge(options); try { await bridge.start(); return await action(bridge); } finally { await bridge.close(); } }
+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) : []; }
+
+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"]));
+  return await withBridge(options, async () => ({ harness: "codex-desktop", app_server: "available", 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 bridge.request("thread/start", {
+    cwd,
+    model: options.model ?? null,
+    approvalPolicy: "never",
+    sandbox: "danger-full-access",
+    ephemeral: false,
+    config: { bypass_hook_trust: true, "features.plugins": 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) {
+  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?.();
+  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" } }, 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) {
+  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);
+  // 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?.();
+  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" } }, options.timeoutMs ?? 1_800_000);
+  const turn = started?.turn ?? started; const turnId = turn?.id ?? null;
+  const completed = await waitForTurn(bridge, sessionId, turnId, options.timeoutMs ?? 1_800_000, options, cwd);
+  const thread = await readCompletedThread(bridge, sessionId);
+  const assistantText = latestAssistantText(thread) ?? latestAssistantText(completed);
+  return { harness: "codex-desktop", provider_session_id: sessionId, adapter_session_id: sessionId, turn_id: turnId, status: "completed", turn: completed, ...(thread ? { thread: threadReceipt(thread) } : {}), descendants: directChildren(bridge, sessionId), ...(assistantText ? { assistant_text: assistantText } : {}), 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") };
+}
+
+async function ensureThreadLoaded(bridge, sessionId, options, cwd) {
+  const value = await bridge.request("thread/read", { threadId: sessionId, includeTurns: false }, 10_000);
+  const thread = value?.thread ?? value;
+  if (thread?.status?.type !== "notLoaded") return;
+  await bridge.request("thread/resume", {
+    threadId: sessionId,
+    cwd,
+    model: options.model ?? null,
+    approvalPolicy: "never",
+    sandbox: "danger-full-access",
+    config: { bypass_hook_trust: true, "features.plugins": false }
+  }, 30_000);
+}
+
+async function waitForTurn(bridge, sessionId, turnId, timeoutMs, options, cwd) {
+  const clock = new ObservationClock({ timeoutMs, onGap: gap => bridge.journal?.write("observation_gap", { ...gap, session_id: sessionId, turn_id: turnId }) });
+  // 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;
+  let nextStoredReadAt = Date.now();
+  while (!clock.sample(bridge.activity?.get(sessionId))) {
+    const known = bridge.turns.get(turnId) ?? bridge.turns.get(sessionId); if (known?.status === "completed") return terminalTurn(known.value, turnId, bridge);
+    if (Date.now() >= nextStoredReadAt) {
+      const stored = await readTurn(bridge, sessionId, turnId, false);
+      if (stored?.turn && isAuthoritativeTerminal(bridge, turnId, stored.turn.status, stored.threadStatus, failureNotBefore)) return terminalTurn({ turn: stored.turn }, 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; unlike `includeTurns`, it never hydrates the whole history.
+      const persisted = await readPersistedTurn(bridge, sessionId, turnId);
+      if (persisted && isAuthoritativeTerminal(bridge, turnId, persisted.status, stored?.threadStatus, failureNotBefore)) return terminalTurn({ turn: persisted }, 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);
+        if (hydrated?.turn && isAuthoritativeTerminal(bridge, turnId, hydrated.turn.status, hydrated.threadStatus, failureNotBefore)) return terminalTurn({ turn: hydrated.turn }, 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 = await readTurn(bridge, sessionId, turnId, true);
+        // "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 && isAuthoritativeTerminal(bridge, turnId, hydrated.turn.status, hydrated.threadStatus, failureNotBefore)) return terminalTurn({ turn: hydrated.turn }, 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 && stored?.threadStatus === "idle" && Date.now() - final.completedAt >= 1_000) {
+        const hydrated = await readTurn(bridge, sessionId, turnId, true);
+        if (hydrated?.turn && isAuthoritativeTerminal(bridge, turnId, hydrated.turn.status, hydrated.threadStatus, failureNotBefore)) return terminalTurn({ turn: hydrated.turn }, turnId, bridge);
+        return terminalTurn({ turn: { id: turnId, status: "completed", synthetic: true, final_message: final.item } }, turnId, bridge);
+      }
+      nextStoredReadAt = Date.now() < failureNotBefore ? failureNotBefore : Date.now() + 15_000;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  fail("Codex turn timed out", "turn_timeout");
+}
+
+function terminalTurn(value, 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") value = observed.value;
+  const turn = value?.turn ?? value;
+  if (turn?.status && turn.status !== "completed") fail(`Codex turn ${turnId ?? "unknown"} ended as ${turn.status}`, "turn_interrupted", { turn_id: turn.id ?? turnId ?? null, terminal_status: turn.status, provider_error: turn.error ?? turn.codexErrorInfo ?? null });
+  return value;
+}
+
+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) {
+  if (!turnId) return null;
+  try {
+    const result = await bridge.request("thread/read", { threadId: sessionId, includeTurns }, 10_000);
+    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 { return null; }
+}
+
+async function readPersistedTurn(bridge, sessionId, turnId) {
+  try {
+    const result = await bridge.request("thread/turns/list", { threadId: sessionId, limit: 20, sortDirection: "desc", itemsView: "summary" }, 10_000);
+    return Array.isArray(result?.data) ? result.data.find((turn) => turn?.id === turnId) ?? null : null;
+  } catch { return null; }
+}
+
+async function readCompletedThread(bridge, sessionId) {
+  for (let attempt = 0; attempt < 8; attempt += 1) {
+    try { const result = await bridge.request("thread/read", { threadId: sessionId, includeTurns: true }, 10_000); return result?.thread ?? result; }
+    catch (error) { bridge.journal.write("thread_read_retry", { session_id: sessionId, attempt, error: error.message }); await new Promise((resolve) => setTimeout(resolve, 150)); }
+  }
+  return null;
+}
+
+function latestAssistantText(value) {
+  const messages = value?.messages ?? value?.items ?? value?.turn?.items ?? [];
+  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 sessionId = required(options.sessionId, "--session-id"); const value = await bridge.request("thread/read", { threadId: sessionId, includeTurns: false }); const thread = value?.thread ?? value;
+  return { harness: "codex-desktop", provider_session_id: sessionId, adapter_session_id: sessionId, status: thread.status ?? null, thread: threadReceipt(thread), descendants: directChildren(bridge, sessionId), 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 sessionId = required(options.sessionId, "--session-id");
+  let turnId = options.turnId ?? null;
+  if (!turnId) {
+    const result = await bridge.request("thread/read", { threadId: sessionId, includeTurns: true }, 10_000);
+    const thread = result?.thread ?? result;
+    turnId = [...(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"); }