@deksden-com/dd-flow-cli 0.9.0-beta.8 → 0.9.0-beta.80

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

@@ -0,0 +1,562 @@
+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;
+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];
+}
+
+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);
+    this.observeNativeHook(message);
+    this.observeHookFailure(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() });
+  }
+
+  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/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") this.activeHooks.set(run.id, { threadId, turnId });
+    else 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)) {
+      fail("No matching active managed native hook", "native_hook_unproven", { provider_session_id: sessionId, tool_call_id: toolCallId });
+    }
+    return { rootSessionId, sessionId, toolCallId, parentSessionId: sessionId === rootSessionId ? null : this.descendants.get(sessionId)?.parent_provider_session_id };
+  }
+
+  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 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 = Object.assign(new Error(reason || "Managed Codex hook failed"), {
+      code: /timed out/i.test(reason) ? "native_hook_timeout" : "native_hook_failed",
+      details: { provider_session_id: threadId, root_provider_session_id: root, turn_id: turnId,
+        hook_run_id: run.id, effect: "unknown", duration_ms: run.durationMs }
+    });
+    this.hookFailures.set(root, error);
+    this.journal.write("native_hook_failure", { code: error.code, message: error.message, ...error.details });
+    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);
+      }
+    }
+  }
+
+  assertHookHealthy(sessionId) {
+    const visited = new Set();
+    while (sessionId && !visited.has(sessionId)) {
+      visited.add(sessionId);
+      const error = this.hookFailures?.get(sessionId);
+      if (error) throw error;
+      sessionId = this.descendants.get(sessionId)?.parent_provider_session_id;
+    }
+  }
+
+  // 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; }
+    const activity = value.params?.item;
+    const activityParent = value.params?.threadId;
+    if (activity?.type === "subAgentActivity" && typeof activity.agentThreadId === "string" && activity.agentThreadId &&
+        typeof activityParent === "string" && activityParent && activity.agentThreadId !== activityParent) {
+      const previous = this.descendants.get(activity.agentThreadId);
+      const observed = activity.kind === "completed" ? "completed" : activity.kind === "interrupted" ? "interrupted" : "running";
+      const status = previous?.status === "completed" ? "completed" : observed;
+      this.descendants.set(activity.agentThreadId, { ...previous, provider_session_id: activity.agentThreadId,
+        parent_provider_session_id: activityParent, status, agent_path: activity.agentPath ?? previous?.agent_path ?? null,
+        source: "codex.app_server.subAgentActivity" });
+    }
+    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;
+        const previous = this.descendants.get(child);
+        this.descendants.set(child, { ...previous, provider_session_id: child, parent_provider_session_id: value.senderThreadId,
+          status: previous?.status === "completed" ? "completed" : 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) {
+      const previous = this.descendants.get(id);
+      this.descendants.set(id, { ...previous, provider_session_id: id, parent_provider_session_id: parent,
+        status: previous?.status === "completed" ? "completed" : 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, threadId: params.threadId }); 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 codexSessionConfig() { return { ...CODEX_SESSION_CONFIG }; }
+
+async function requestConfiguredThread(bridge, method, params, timeoutMs) {
+  try { return await bridge.request(method, { ...params, config: codexSessionConfig() }, timeoutMs); }
+  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"]));
+  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 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) {
+  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);
+  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?.();
+  bridge.assertHookHealthy?.(sessionId);
+  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);
+  bridge.assertHookHealthy?.(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 requestConfiguredThread(bridge, "thread/resume", {
+    threadId: sessionId,
+    cwd,
+    model: options.model ?? null,
+    approvalPolicy: "never",
+    sandbox: "danger-full-access"
+  }, 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))) {
+    bridge.assertHookHealthy?.(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 { bridge.assertHookHealthy?.(sessionId); 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 { bridge.assertHookHealthy?.(sessionId); 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.assertHookHealthy?.(sessionId); 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"); }