@deksden-com/dd-flow-cli 0.9.0-beta.124 → 0.9.0-beta.127

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

@@ -1,11 +1,16 @@
 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 } from "./operation-errors.mjs";
-import { ObservationClock, observedTimeout } from "./observation-clock.mjs";
+import { errorRecord, 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";
 
 const LATE_RESPONSE_GRACE_MS = 5_000;
 const CODEX_SESSION_CONFIG = Object.freeze({
@@ -35,43 +40,51 @@ export function parseCodexCliVersion(value) {
   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`)); }
+  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";
-    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" })));
+    // 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("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));
+    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);
     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.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();
@@ -83,16 +96,57 @@ export class CodexBridge {
           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); });
+        })).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);
+      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);
       }
     }
-    if (message.id === undefined && (message.method?.startsWith("item/") || message.method === "turn/started" || message.method === "thread/tokenUsage/updated")) {
+    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); this.activity.set(id, (this.activity.get(id) ?? 0) + 1);
-        id = this.descendants.get(id)?.parent_provider_session_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:
@@ -117,6 +171,11 @@ export class CodexBridge {
         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;
@@ -126,7 +185,10 @@ export class CodexBridge {
       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 (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);
@@ -141,6 +203,14 @@ export class CodexBridge {
   }
 
   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 ?? []) {
@@ -152,8 +222,12 @@ export class CodexBridge {
     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);
+    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) {
@@ -167,7 +241,8 @@ export class CodexBridge {
       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)) {
+        || 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 });
     }
     return { rootSessionId, sessionId, toolCallId, parentSessionId: sessionId === rootSessionId ? null : this.descendants.get(sessionId)?.parent_provider_session_id };
@@ -180,6 +255,11 @@ export class CodexBridge {
         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;
@@ -193,78 +273,120 @@ export class CodexBridge {
     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 }
-    });
+    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: correction ? "no_effect" : "unknown", 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;
+    }
     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);
       }
     }
+    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 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);
+    }
+    this.descendants.set(child, { ...previous, ...facts, parent_turn_id: facts.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) {
+  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); 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);
+      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) });
+            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 = value.params?.item;
+    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 && activity.agentThreadId !== activityParent) {
+        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;
-      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 (activity.kind === "started") this.bindChild(activity.agentThreadId, activityParent, { status, parent_turn_id: value.params?.turnId === this.currentTurns?.get(activityParent) ? value.params.turnId : null, 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 || child === value.senderThreadId) continue;
+        if (typeof child !== "string" || !child) continue;
         const previous = this.descendants.get(child);
-        this.descendants.set(child, { ...previous, provider_session_id: child, parent_provider_session_id: value.senderThreadId,
+        this.bindChild(child, value.senderThreadId, {
+          parent_turn_id: parentTurn === this.currentTurns?.get(value.senderThreadId) ? parentTurn : null,
           status: previous?.status === "completed" || previous?.active_turn_id ? previous.status : value.agentsStates?.[child]?.status ?? previous?.status ?? "unknown", source: "codex.app_server" });
       }
     }
-    const id = value.threadId ?? value.id ?? null;
-    const parent = value.parentThreadId ?? value.parent_thread_id ?? null;
+    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.descendants.set(id, { ...previous, provider_session_id: id, parent_provider_session_id: parent,
-        status: previous?.status === "completed" || previous?.active_turn_id ? previous.status : value.status?.type ?? value.status ?? previous?.status ?? "unknown", source: "codex.app_server" });
+      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);
     }
-    for (const child of Object.values(value)) this.observeTopology(child, depth + 1);
   }
 
   directChildren(sessionId) {
@@ -285,6 +407,15 @@ export class CodexBridge {
   }
 
   request(method, params = {}, timeoutMs = this.options.timeoutMs ?? 120_000) {
+    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(() => {
@@ -295,9 +426,15 @@ export class CodexBridge {
         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 });
+        }, LATE_RESPONSE_GRACE_MS, { progress: () => pending.progress });
+      }, timeoutMs, { progress: () => 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) {
@@ -309,19 +446,19 @@ export class CodexBridge {
       throw error;
     }
     try { stdin.write(`${JSON.stringify(value)}\n`); }
-    catch (error) { this.rejectAll(Object.assign(error, { code: error.code ?? "bridge_pipe_broken" })); throw error; }
+    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(); }
+  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 this.modelObservations; await this.journal.flush(); });
+    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;
-  try { await bridge.start(); return await action(bridge); }
+  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 error; primary.cleanup_error = errorRecord(error); primary.details = { ...primary.details, cleanup_error: primary.cleanup_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"); }
@@ -335,7 +472,7 @@ async function observedChildren(bridge, sessionId) {
     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) };
+      native_turn_items: turnItemEvidence(turn, bridge, child.provider_session_id) };
   }));
 }
 function codexSessionConfig() { return { ...CODEX_SESSION_CONFIG }; }
@@ -413,6 +550,7 @@ export async function startSessionWithBridge(bridge, 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" } }, 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");
@@ -421,6 +559,7 @@ export async function startSessionWithBridge(bridge, options) {
 
 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");
+  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;
@@ -429,26 +568,44 @@ export async function promptSessionWithBridge(bridge, 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);
+  bridge.dispatchOperationId = options.operationId;
+  const clock = new ObservationClock({ timeoutMs: options.livenessTimeoutMs ?? options.timeoutMs ?? 1_800_000, onGap: gap => bridge.journal?.write("observation_gap", { ...gap, session_id: 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" } }, 30_000);
   const turn = started?.turn ?? started; const turnId = turn?.id ?? null;
   let completed;
-  try { completed = await waitForTurn(bridge, sessionId, turnId, options.timeoutMs ?? 1_800_000, options, cwd); }
+  try { completed = await waitForTurn(bridge, sessionId, turnId, options.livenessTimeoutMs ?? options.timeoutMs ?? 1_800_000, options, cwd, clock); }
   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);
+          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 });
+      }
     }
     throw error;
   }
-  const thread = await readCompletedThread(bridge, sessionId);
-  bridge.assertHookHealthy?.(sessionId);
-  const assistantText = latestAssistantText(thread?.turns?.find(item => item?.id === turnId)) ?? 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: await observedChildren(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") };
+  const nativeOutcome = { harness: "codex-desktop", provider_session_id: sessionId, adapter_session_id: sessionId, turn_id: turnId, status: "completed", turn: completed };
+  try {
+    const thread = await readCompletedThread(bridge, sessionId);
+    bridge.assertHookHealthy?.(sessionId);
+    const assistantText = latestAssistantText(thread?.turns?.find(item => item?.id === turnId)) ?? latestAssistantText(completed);
+    return { ...nativeOutcome, ...(thread ? { thread: threadReceipt(thread) } : {}), descendants: await observedChildren(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") };
+  } 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) {
@@ -464,17 +621,17 @@ async function ensureThreadLoaded(bridge, sessionId, options, cwd) {
   }, 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 }) });
+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 }) })) {
   // 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))) {
+  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);
-    if (Date.now() >= nextStoredReadAt) {
+    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);
       if (stored?.turn && isAuthoritativeTerminal(bridge, turnId, stored.turn.status, stored.threadStatus, failureNotBefore)) return terminalTurn({ turn: stored.turn }, sessionId, turnId, bridge);
       // A loaded app-server can retain a stale `active` Thread state after a
@@ -516,9 +673,10 @@ async function waitForTurn(bridge, sessionId, turnId, timeoutMs, options, cwd) {
       }
       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, native_outcome: "unknown" });
     await new Promise((resolve) => setTimeout(resolve, 250));
   }
-  fail("Codex turn timed out", "turn_timeout");
 }
 
 function terminalTurn(value, sessionId, turnId, bridge) {
@@ -529,7 +687,7 @@ function terminalTurn(value, sessionId, turnId, bridge) {
   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) });
+    provider_error: providerError, native_turn_items: turnItemEvidence(turn, bridge, sessionId) });
   return value;
 }
 
@@ -540,12 +698,25 @@ function nativeTurnError(bridge, sessionId, turn) {
   return error && native?.willRetry !== undefined && typeof error === "object" ? { ...error, willRetry: native.willRetry } : error;
 }
 
-function turnItemEvidence(turn) {
+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 => ({ id: item?.id ?? null, type: item?.type ?? "unknown", status: item?.status ?? null })),
-    pending: items.some(item => !["agentMessage", "reasoning", "userMessage"].includes(item?.type) && !["completed", "failed", "declined"].includes(item?.status)),
-    possible_effects: items.some(item => !["agentMessage", "reasoning", "userMessage"].includes(item?.type)) } : { observed: false };
+    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 { terminalCodexOverload } from "./codex-capacity-policy.mjs";
@@ -575,11 +746,12 @@ async function readPersistedTurn(bridge, sessionId, turnId) {
 }
 
 async function readCompletedThread(bridge, sessionId) {
+  let lastError;
   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)); }
+    catch (error) { lastError = error; bridge.assertHookHealthy?.(sessionId); bridge.journal.write("thread_read_retry", { session_id: sessionId, attempt, error: errorRecord(error) }); await new Promise((resolve) => setTimeout(resolve, 150)); }
   }
-  return null;
+  throw lastError;
 }
 
 function latestAssistantText(value) {
@@ -604,7 +776,7 @@ export async function inspectSession(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;
   const terminal = options.turnId ? (await readTurn(bridge, sessionId, options.turnId, true))?.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) } : {};
+  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), 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") };
 }