@deksden-com/dd-flow-cli 0.9.0-beta.141 → 0.9.0-beta.143

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

@@ -4,7 +4,7 @@ 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, isProvenShellCorrection } from "./operation-errors.mjs";
+import { errorRecord, isObservationLoss, isProvenShellCorrection } from "./operation-errors.mjs";
 import { reportedFailure, commandText } from "./process-json.mjs";
 import { ObservationClock, observedTimeout, validateObservationDuration } from "./observation-clock.mjs";
 import { observeModel } from "./model-observations.mjs";
@@ -12,9 +12,105 @@ import { classifyCodexItem } from "./tool-observations.mjs";
 import { readNativeLines, streamNativeDiagnostics, nativeObservationError } from "./native-streams.mjs";
 import { operationProgressReporter } from "./operation-progress.mjs";
 import { publishSetup } from './setup-progress.mjs';
+import { capacityBackoff } from './provider-overload-policy.mjs';
 
 export const CODEX_REQUEST_TIMEOUT_MS = 120_000;
 export const LATE_RESPONSE_GRACE_MS = 5_000;
+export function codexReadPhase(bridge, options = {}) {
+  const timeoutMs = Math.min(CODEX_REQUEST_TIMEOUT_MS, options.livenessTimeoutMs ?? options.timeoutMs ?? CODEX_REQUEST_TIMEOUT_MS);
+  return { clock: new ObservationClock({ timeoutMs, ...options.observationClock,
+    onGap: gap => bridge.journal?.write("observation_gap", { ...gap, phase: "metadata_read" }) }),
+    random: options.readRandom ?? Math.random,
+    sleep: options.readSleep ?? (ms => new Promise(resolve => setTimeout(resolve, ms))) };
+}
+
+function dispatchBudget(phase, method, limitMs) {
+  const clock = phase.outerClock ?? phase.clock;
+  if (clock.sample(phase.progress?.())) throw Object.assign(new Error("Codex owner observation window expired before dispatch"), {
+    code: clock.observationLost ? "operation_observation_lost" : "rpc_timeout",
+    details: { method, phase: "before_dispatch", effect: "no_effect", observation: clock.state() }
+  });
+  const remaining = Math.max(1, Math.ceil(clock.timeoutMs - clock.elapsed));
+  const timeoutMs = Math.min(limitMs, remaining);
+  return [timeoutMs, { graceMs: Math.min(LATE_RESPONSE_GRACE_MS, remaining - timeoutMs) }];
+}
+
+export async function readCodexRpc(bridge, method, params, phase = codexReadPhase(bridge)) {
+  if (!["thread/read", "thread/turns/list"].includes(method)) throw new Error("Codex read policy only accepts read-only RPC");
+  const sample = () => phase.clock.sample(phase.progress?.());
+  let primary;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    if (sample()) throw primary ?? Object.assign(new Error("Codex metadata observation window expired"), { code: phase.clock.observationLost ? "operation_observation_lost" : "rpc_timeout", details: { method, phase: "metadata_read", observation: phase.clock.state() } });
+    const remaining = Math.min(CODEX_REQUEST_TIMEOUT_MS, Math.max(1, Math.ceil(phase.clock.timeoutMs - phase.clock.elapsed)));
+    try {
+      const result = await bridge.request(method, params, remaining, { graceMs: 0, observe: () => { sample(); phase.outerClock?.sample(); } });
+      if (!result || typeof result !== "object" || Array.isArray(result)
+        || method === "thread/read" && (!result.thread || typeof result.thread !== "object" || Array.isArray(result.thread) || typeof result.thread.id !== "string" || !result.thread.id)
+        || method === "thread/turns/list" && !Array.isArray(result.data))
+        throw Object.assign(new Error("Codex read returned invalid data"), { code: "rpc_schema_invalid", details: { method } });
+      if (method === "thread/read" && result.thread.id !== params.threadId)
+        throw Object.assign(new Error("Codex read returned a foreign Thread"), { code: "thread_identity_mismatch" });
+      return result;
+    }
+    catch (error) {
+      primary ??= error; bridge.assertHookHealthy?.(params.threadId);
+      // A broken process cannot be replaced under the guise of a read retry.
+      const current = bridge.currentTurns?.get(params.threadId);
+      const materializing = method === "thread/read" && current && !bridge.turns?.has(current)
+        && bridge.nativeHookTurns?.get(params.threadId) !== current && error?.code === "rpc_error" && error.details?.code === -32603;
+      const emptyMetadata = materializing && error.details.message?.match(/^failed to read thread: thread-store internal error: failed to read session metadata (.+): rollout at (.+) is empty$/);
+      const transient = error?.code === "rpc_timeout" || error?.code === "EAGAIN" || error?.code === "EINTR"
+        || Boolean(emptyMetadata && emptyMetadata[1] === emptyMetadata[2] && emptyMetadata[1].endsWith(`-${params.threadId}.jsonl`));
+      if (!transient) { if (error !== primary) error.previous_read_error = errorRecord(primary); throw error; }
+      if (attempt === 2 || sample()) { if (error !== primary) primary.secondary_error = errorRecord(error); throw primary; }
+      const delay = Math.min(capacityBackoff(error, attempt + 1, phase.clock.wall(), phase.random), Math.max(0, phase.clock.timeoutMs - phase.clock.elapsed));
+      bridge.journal?.write("thread_read_retry", { method, session_id: params.threadId, attempt: attempt + 1, delay_ms: delay, error: errorRecord(error) });
+      await phase.sleep(delay);
+    }
+  }
+}
+
+// Availability belongs to this read of this Thread, not to the whole binary.
+export async function readCodexHistory(bridge, method, params, phase = codexReadPhase(bridge)) {
+  if (method !== "thread/turns/list" && !(method === "thread/read" && params.includeTurns === true))
+    throw new Error("Codex history policy only accepts history reads");
+  let result, error;
+  try {
+    result = await readCodexRpc(bridge, method, params, phase);
+    if (method === "thread/read" && result.thread.turns !== undefined && !Array.isArray(result.thread.turns))
+      fail("Codex history read returned invalid turns", "rpc_schema_invalid", { method });
+  }
+  catch (cause) {
+    bridge.assertHookHealthy?.(params.threadId);
+    const native = cause?.details;
+    const operation = method === "thread/read" ? "includeTurns" : "thread/turns/list";
+    const unsupported = native?.code === -32601 && native.message === "list_turns is not supported yet";
+    const unmaterialized = native?.code === -32600 && native.message ===
+      `thread ${params.threadId} is not materialized yet; ${operation} is unavailable before first user message`;
+    if (cause?.code !== "rpc_error" || !unsupported && !unmaterialized) throw cause;
+    error = errorRecord(cause);
+  }
+  const available = !error;
+  phase.history ??= new Map();
+  const key = `${params.threadId}:${method}`;
+  if (phase.history.get(key)?.available !== available) bridge.journal?.write("history_availability", {
+    method, session_id: params.threadId, available, ...(error ? { error } : {})
+  });
+  phase.history.set(key, { available, error });
+  return { available, result, error };
+}
+
+export function retainedCodexTurn(bridge, sessionId, turnId = bridge.currentTurns?.get(sessionId)) {
+  if (!turnId) return null;
+  const retained = bridge.turns?.get(turnId);
+  if (!retained) return null;
+  if (retained.threadId && retained.threadId !== sessionId || retained.value?.threadId && retained.value.threadId !== sessionId)
+    fail("Codex retained Thread identity differs", "turn_identity_mismatch");
+  if (!retained.threadId && !retained.value?.threadId) return null;
+  const turn = retained.value?.turn;
+  if (turn?.id !== turnId) fail("Codex retained Turn identity differs", "turn_identity_mismatch");
+  return turn;
+}
 const CODEX_SESSION_CONFIG = Object.freeze({
   bypass_hook_trust: true,
   "features.plugins": false,
@@ -158,7 +254,7 @@ export class CodexBridge {
     // 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") {
+    if (request?.method === "thread/read" && !message.error) {
       const thread = message.result?.thread ?? message.result ?? {};
       this.journal.write("inbound", { jsonrpc: message.jsonrpc, id: message.id, result: { thread: {
         id: thread.id ?? null, status: thread.status ?? null, model: thread.model ?? null, modelProvider: thread.modelProvider ?? null, reasoningEffort: thread.reasoningEffort ?? null, updatedAt: thread.updatedAt ?? null,
@@ -410,7 +506,7 @@ export class CodexBridge {
     this.send({ jsonrpc: "2.0", id: message.id, error });
   }
 
-  request(method, params = {}, timeoutMs = this.options.timeoutMs ?? CODEX_REQUEST_TIMEOUT_MS) {
+  request(method, params = {}, timeoutMs = this.options.timeoutMs ?? CODEX_REQUEST_TIMEOUT_MS, policy = {}) {
     const turnFloor = method === "turn/start" ? new Set([this.currentTurns?.get(params.threadId), ...[...this.turns].filter(([, value]) => value.threadId === params.threadId).map(([id]) => id)].filter(Boolean)) : null;
     if (method === "turn/start" && params.threadId) {
       // Only one productive root Turn is admitted by the daemon fence. Drop
@@ -422,16 +518,18 @@ export class CodexBridge {
     }
     const id = this.nextId++;
     return new Promise((resolve, reject) => {
-      const timer = observedTimeout(() => {
+      const timer = observedTimeout(clock => {
         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 } });
+        const graceMs = policy.graceMs ?? LATE_RESPONSE_GRACE_MS;
+        const timeoutError = Object.assign(new Error(`${method} timed out`), { code: clock.observationLost ? "operation_observation_lost" : "rpc_timeout", details: { method, request_id: id, timeout_ms: timeoutMs, grace_ms: graceMs, observation: clock.state() } });
         this.journal.write("request_deadline", timeoutError.details);
+        if (!graceMs) { this.pending.delete(id); reject(timeoutError); return; }
         pending.timer = observedTimeout(() => {
           if (this.pending.get(id) !== pending) return;
           this.pending.delete(id); reject(timeoutError);
-        }, 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 }) });
+        }, graceMs, { progress: () => pending.progress });
+      }, timeoutMs, { progress: () => { policy.observe?.(); return this.pending.get(id)?.progress; }, onGap: gap => this.journal.write("observation_gap", { ...gap, method, request_id: id }) });
       const publish = operationProgressReporter();
       this.pending.set(id, { id, resolve, reject, timer, method, threadId: params.threadId, turnFloor });
       if (method === "turn/start" && params.threadId) {
@@ -467,12 +565,12 @@ async function withBridge(options, action) {
 function profile(options) { return { harness: "codex-desktop", model: options.model ?? null, reasoning: options.reasoning ?? null }; }
 function threadId(result) { const id = result?.thread?.id ?? result?.threadId; return required(id, "Codex thread id"); }
 function directChildren(bridge, sessionId) { return typeof bridge?.directChildren === "function" ? bridge.directChildren(sessionId) : []; }
-async function observedChildren(bridge, sessionId) {
+async function observedChildren(bridge, sessionId, phase) {
   const children = directChildren(bridge, sessionId);
   let reads = 0;
   return await Promise.all(children.map(async child => {
     if (child.status !== "failed" || !child.terminal_turn_id || reads++ >= 16) return child;
-    const observed = await readTurn(bridge, child.provider_session_id, child.terminal_turn_id, true);
+    const observed = await readTurn(bridge, child.provider_session_id, child.terminal_turn_id, true, phase);
     const turn = observed?.turn;
     if (turn?.id !== child.terminal_turn_id || turn.status !== child.status) return child;
     return { ...child, provider_error: nativeTurnError(bridge, child.provider_session_id, turn) ?? child.provider_error,
@@ -481,8 +579,8 @@ async function observedChildren(bridge, sessionId) {
 }
 function codexSessionConfig() { return { ...CODEX_SESSION_CONFIG }; }
 
-async function requestConfiguredThread(bridge, method, params, timeoutMs) {
-  try { return await bridge.request(method, { ...params, config: codexSessionConfig() }, timeoutMs); }
+async function requestConfiguredThread(bridge, method, params, timeoutMs, policy) {
+  try { return await bridge.request(method, { ...params, config: codexSessionConfig() }, timeoutMs, policy); }
   catch (error) {
     const data = error?.details?.data;
     const key = data?.configKey ?? data?.config_key ?? null;
@@ -506,7 +604,7 @@ function threadReceipt(thread) {
 
 export async function doctor(options = {}) {
   const codex_cli = parseCodexCliVersion(await commandText(options.bin ?? process.env.DD_CODEX_BIN ?? "codex", ["--version"], { phase: 'native-version' }));
-  return await withBridge(options, async () => ({ harness: "codex-desktop", app_server: "available", observed_runtime: { codex_cli, dd_harness_contract: "dd-codex-harness@1" }, requested_profile: profile(options), observed_at: now() }));
+  return await withBridge(options, async () => ({ harness: "codex-desktop", app_server: "available", observation_scope: "version_and_initialize", observed_runtime: { codex_cli, dd_harness_contract: "dd-codex-harness@1" }, requested_profile: profile(options), observed_at: now() }));
 }
 
 async function observeCodexProfile(bridge, options, id, observed, source) {
@@ -548,6 +646,9 @@ export async function startSession(options) {
 }
 
 export async function startSessionWithBridge(bridge, options) {
+  options = { ...options, readPhase: codexReadPhase(bridge, options) };
+  options.readPhase.outerClock = new ObservationClock({ timeoutMs: options.livenessTimeoutMs ?? options.timeoutMs ?? CODEX_REQUEST_TIMEOUT_MS,
+    ...options.observationClock, onGap: gap => bridge.journal?.write("observation_gap", { ...gap, phase: "start", session_id: options.sessionId }) });
   const sessionId = required(options.sessionId, "--session-id"); const cwd = absolute(options.cwd, "--cwd"); const prompt = required(options.prompt, "--prompt");
   await ensureThreadLoaded(bridge, sessionId, options, cwd);
   bridge.requestedProfiles?.set(sessionId, profile(options));
@@ -555,13 +656,16 @@ export async function startSessionWithBridge(bridge, options) {
   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 started = await bridge.request("turn/start", { threadId: sessionId, input: [{ type: "text", text: prompt }], cwd, model: options.model ?? null, effort: options.reasoning ?? null, approvalPolicy: "never", sandboxPolicy: { type: "dangerFullAccess" } }, ...dispatchBudget(options.readPhase, "turn/start", options.timeoutMs ?? 30_000));
   const turn = started?.turn ?? started; const turnId = turn?.id ?? null;
   if (typeof turnId !== "string" || !turnId) throw new Error("Codex did not return a Turn id");
   return { harness: "codex-desktop", provider_session_id: sessionId, adapter_session_id: sessionId, turn_id: turnId, status: "started", requested_profile: profile(options), observed_profile: { model: null, reasoning: null } };
 }
 
 export async function promptSessionWithBridge(bridge, options) {
+  options = { ...options, readPhase: codexReadPhase(bridge, options) };
+  const clock = new ObservationClock({ timeoutMs: options.livenessTimeoutMs ?? options.timeoutMs ?? 1_800_000, ...options.observationClock, onGap: gap => bridge.journal?.write("observation_gap", { ...gap, phase: "prompt", session_id: options.sessionId }) });
+  options.readPhase.outerClock = clock;
   const sessionId = required(options.sessionId, "--session-id"); const cwd = absolute(options.cwd, "--cwd"); const prompt = required(options.prompt, "--prompt");
   validateObservationDuration(options.livenessTimeoutMs ?? options.timeoutMs ?? 1_800_000);
   await ensureThreadLoaded(bridge, sessionId, options, cwd);
@@ -573,8 +677,7 @@ export async function promptSessionWithBridge(bridge, options) {
   options.assertDispatch?.();
   bridge.assertHookHealthy?.(sessionId);
   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 started = await bridge.request("turn/start", { threadId: sessionId, input: [{ type: "text", text: prompt }], cwd, model: options.model ?? null, effort: options.reasoning ?? null, approvalPolicy: "never", sandboxPolicy: { type: "dangerFullAccess" } }, ...dispatchBudget(options.readPhase, "turn/start", 30_000));
   const turn = started?.turn ?? started; const turnId = turn?.id ?? null;
   let completed;
   try { completed = isTerminalTurnStatus(turn?.status) ? terminalTurn({ turn }, sessionId, turnId, bridge)
@@ -599,14 +702,34 @@ export async function promptSessionWithBridge(bridge, options) {
           details: { native_outcome: { provider_session_id: sessionId, turn_id: turnId, status: "failed", provider_error: error.details?.provider_error }, settled: false, observation_error: errorRecord(observationError) }, cause: error });
       }
     }
+    if (isObservationLoss(error)) throw Object.assign(new Error("Codex accepted Turn outcome could not be observed", { cause: error }), {
+      code: "operation_observation_lost", retryable: false, details: { provider_session_id: sessionId, turn_id: turnId,
+        operation_id: options.operationId ?? null, phase: "turn_observation", native_dispatch_started: true,
+        native_outcome: "unknown", observation_error: errorRecord(error), history_reads: Object.fromEntries(options.readPhase.history ?? []) }
+    });
     throw error;
   }
   const nativeOutcome = { harness: "codex-desktop", provider_session_id: sessionId, adapter_session_id: sessionId, turn_id: turnId, status: "completed", turn: completed };
   try {
-    const thread = await readCompletedThread(bridge, sessionId);
+    const phase = codexReadPhase(bridge, options);
+    const history = await readCodexHistory(bridge, "thread/read", { threadId: sessionId, includeTurns: true }, phase);
+    const thread = history.available ? history.result.thread
+      : (await readCodexRpc(bridge, "thread/read", { threadId: sessionId, includeTurns: false }, phase)).thread;
     bridge.assertHookHealthy?.(sessionId);
-    const 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") };
+    const final = bridge.finalMessages?.get(sessionId);
+    const historyTurn = thread?.turns?.find(item => item?.id === turnId);
+    const completeHistory = history.available && (turnItemEvidence(historyTurn, bridge, sessionId).observed
+      // Preserve the existing idle + readable-history final-message receipt.
+      || completed?.turn?.synthetic === true && Array.isArray(thread.turns) && final?.turnId === turnId && thread.status?.type === "idle");
+    const assistantText = latestAssistantText(completed) ?? latestAssistantText(historyTurn)
+      ?? (final?.turnId === turnId ? latestAssistantText({ items: [final.item] }) : null);
+    if (!completeHistory && (!assistantText || !turnItemEvidence(completed?.turn ?? completed, bridge, sessionId).observed))
+      fail("Codex completed but its current output/items remain unavailable", "operation_observation_lost", { history_error: history.error, provider_session_id: sessionId, turn_id: turnId });
+    if (!completeHistory && (options.model && !thread.model || options.reasoning && !thread.reasoningEffort))
+      fail("Codex completed but its applied profile remains unavailable", "operation_observation_lost", { history_error: history.error, provider_session_id: sessionId, turn_id: turnId });
+    const result = { ...nativeOutcome, ...(thread ? { thread: threadReceipt(thread) } : {}), descendants: await observedChildren(bridge, sessionId, phase), ...(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") };
+    await bridge.journal?.flush?.();
+    return result;
   } catch (error) {
     throw Object.assign(new Error("Codex completed natively but mandatory observation failed"), { code: "native_outcome_observation_failed", retryable: false,
       details: { native_outcome: nativeOutcome, settled: false, observation_error: errorRecord(error) }, cause: error });
@@ -614,7 +737,7 @@ export async function promptSessionWithBridge(bridge, options) {
 }
 
 async function ensureThreadLoaded(bridge, sessionId, options, cwd) {
-  const value = await bridge.request("thread/read", { threadId: sessionId, includeTurns: false }, 10_000);
+  const value = await readCodexRpc(bridge, "thread/read", { threadId: sessionId, includeTurns: false }, options.readPhase);
   const thread = value?.thread ?? value;
   if (thread?.status?.type !== "notLoaded") return;
   await requestConfiguredThread(bridge, "thread/resume", {
@@ -623,10 +746,14 @@ async function ensureThreadLoaded(bridge, sessionId, options, cwd) {
     model: options.model ?? null,
     approvalPolicy: "never",
     sandbox: "danger-full-access"
-  }, 30_000);
+  }, ...dispatchBudget(options.readPhase, "thread/resume", 30_000));
 }
 
 async function waitForTurn(bridge, sessionId, turnId, timeoutMs, options, cwd, clock = new ObservationClock({ timeoutMs, onGap: gap => bridge.journal?.write("observation_gap", { ...gap, session_id: sessionId, turn_id: turnId }) }), startStatus) {
+  const readPhase = codexReadPhase(bridge, options);
+  readPhase.clock = clock;
+  readPhase.progress = () => bridge.activityObservations?.get(sessionId) ?? bridge.activity?.get(sessionId);
+  options = { ...options, readPhase };
   // app-server can briefly expose the new Turn as `interrupted` between the
   // turn/start response and its turn/started notification. Give that snapshot
   // one event-loop grace window before treating failure as authoritative.
@@ -636,7 +763,7 @@ async function waitForTurn(bridge, sessionId, turnId, timeoutMs, options, cwd, c
     if (status === "completed" || startStatus !== "inProgress" || bridge.turns.get(turnId)?.status === "completed") return true;
     // A provisional failure can contradict the accepted start before its
     // delayed notification arrives. Recheck this Turn, never start another.
-    const current = await readTurn(bridge, sessionId, turnId, true);
+    const current = await readTurn(bridge, sessionId, turnId, true, readPhase);
     return bridge.turns.get(turnId)?.status === "completed" || current?.turn?.status === status
       && isAuthoritativeTerminal(bridge, turnId, status, current.threadStatus, failureNotBefore);
   };
@@ -646,27 +773,29 @@ async function waitForTurn(bridge, sessionId, turnId, timeoutMs, options, cwd, c
     const known = bridge.turns.get(turnId) ?? bridge.turns.get(sessionId); if (known?.status === "completed" && (!known.threadId || known.threadId === sessionId)) return terminalTurn(known.value, sessionId, turnId, bridge);
     const expired = clock.sample(bridge.activityObservations?.get(sessionId) ?? bridge.activity?.get(sessionId));
     if (expired || Date.now() >= nextStoredReadAt) {
-      const stored = await readTurn(bridge, sessionId, turnId, false);
+      const stored = await readTurn(bridge, sessionId, turnId, false, readPhase);
       if (stored?.turn && await reconcileSnapshot(stored.turn.status, stored.threadStatus)) return terminalTurn({ turn: stored.turn }, sessionId, turnId, bridge);
       // A loaded app-server can retain a stale `active` Thread state after a
       // provider-side interruption. The persisted turn page is independent of
       // that live subscription and is the compact authority for its terminal
-      // status; unlike `includeTurns`, it never hydrates the whole history.
-      const persisted = await readPersistedTurn(bridge, sessionId, turnId);
-      if (persisted && await reconcileSnapshot(persisted.status, stored?.threadStatus)) return terminalTurn({ turn: persisted }, sessionId, turnId, bridge);
+      // status. Hydrate only when that read surface is unavailable.
+      const persisted = await readPersistedTurn(bridge, sessionId, turnId, readPhase);
+      if (persisted.turn && await reconcileSnapshot(persisted.turn.status, persisted.threadStatus ?? stored?.threadStatus)) return terminalTurn({ turn: persisted.turn }, sessionId, turnId, bridge);
+      const native = bridge.turns.get(turnId);
+      if (native?.status === "completed" && (!native.threadId || native.threadId === sessionId)) return terminalTurn(native.value, sessionId, turnId, bridge);
       // Desktop may unload an idle Thread immediately after an interrupted
       // Turn. Reload it once before polling again: otherwise the compact
       // status remains `notLoaded` forever and hides the terminal Turn.
       if (stored?.threadStatus === "notLoaded") {
         await ensureThreadLoaded(bridge, sessionId, options, cwd);
-        const hydrated = await readTurn(bridge, sessionId, turnId, true);
+        const hydrated = await readTurn(bridge, sessionId, turnId, true, readPhase);
         if (hydrated?.turn && await reconcileSnapshot(hydrated.turn.status, hydrated.threadStatus)) return terminalTurn({ turn: hydrated.turn }, sessionId, turnId, bridge);
       }
       // Some app-server versions correctly omit turns for a compact read.
       // Once the thread is idle, hydrate exactly once to recover the terminal
       // turn instead of waiting for the global timeout.
       if (stored?.threadStatus === "idle") {
-        const hydrated = await readTurn(bridge, sessionId, turnId, true);
+        const hydrated = persisted.hydrated ? persisted : await readTurn(bridge, sessionId, turnId, true, readPhase);
         // "idle" only describes the Thread.  Some app-server builds retain
         // an inProgress Turn after emitting the final agent message; treating
         // that stale Turn as terminal incorrectly aborts an otherwise usable
@@ -681,7 +810,7 @@ async function waitForTurn(bridge, sessionId, turnId, timeoutMs, options, cwd, c
       // reasoning and calling tools.  They are terminal evidence only after
       // app-server reports the Thread idle.
       if (final?.turnId === turnId && stored?.threadStatus === "idle" && Date.now() - final.completedAt >= 1_000) {
-        const hydrated = await readTurn(bridge, sessionId, turnId, true);
+        const hydrated = await readTurn(bridge, sessionId, turnId, true, readPhase);
         if (hydrated?.turn && await reconcileSnapshot(hydrated.turn.status, hydrated.threadStatus)) return terminalTurn({ turn: hydrated.turn }, sessionId, turnId, bridge);
         if (hydrated?.threadStatus === "idle" && !isTerminalTurnStatus(hydrated.turn?.status))
           return terminalTurn({ turn: { id: turnId, status: "completed", synthetic: true, final_message: final.item } }, sessionId, turnId, bridge);
@@ -689,7 +818,7 @@ async function waitForTurn(bridge, sessionId, turnId, timeoutMs, options, cwd, c
       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" });
+    if (expired && clock.sample(bridge.activityObservations?.get(sessionId) ?? bridge.activity?.get(sessionId))) fail("Codex native outcome remains unknown after its silence window", "operation_observation_lost", { provider_session_id: sessionId, turn_id: turnId, operation_id: options.operationId ?? null, native_dispatch_started: true, phase: "turn_observation", native_outcome: "unknown", history_reads: Object.fromEntries(readPhase.history ?? []) });
     await new Promise((resolve) => setTimeout(resolve, 250));
   }
 }
@@ -744,29 +873,23 @@ function isAuthoritativeTerminal(bridge, turnId, status, threadStatus, failureNo
   return !(bridge.turns.get(turnId)?.status === "running" && threadStatus === "active");
 }
 
-async function readTurn(bridge, sessionId, turnId, includeTurns) {
+async function readTurn(bridge, sessionId, turnId, includeTurns, phase) {
   if (!turnId) return null;
   try {
-    const result = await bridge.request("thread/read", { threadId: sessionId, includeTurns }, 10_000);
+    const history = includeTurns ? await readCodexHistory(bridge, "thread/read", { threadId: sessionId, includeTurns }, phase) : null;
+    if (history && !history.available) return { turn: null, threadStatus: null, historyAvailable: false };
+    const result = history?.result ?? await readCodexRpc(bridge, "thread/read", { threadId: sessionId, includeTurns }, phase);
     const thread = result?.thread ?? result;
     return { turn: Array.isArray(thread?.turns) ? thread.turns.find((turn) => turn?.id === turnId) ?? null : null, threadStatus: thread?.status?.type ?? null };
-  } catch { bridge.assertHookHealthy?.(sessionId); return null; }
+  } catch (error) { bridge.assertHookHealthy?.(sessionId); throw error; }
 }
 
-async function readPersistedTurn(bridge, sessionId, turnId) {
+async function readPersistedTurn(bridge, sessionId, turnId, phase) {
   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) {
-  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) { 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)); }
-  }
-  throw lastError;
+    const history = await readCodexHistory(bridge, "thread/turns/list", { threadId: sessionId, limit: 20, sortDirection: "desc", itemsView: "summary" }, phase);
+    if (!history.available) return { ...await readTurn(bridge, sessionId, turnId, true, phase), hydrated: true };
+    return { available: history.available, turn: history.result?.data.find((turn) => turn?.id === turnId) ?? null };
+  } catch (error) { bridge.assertHookHealthy?.(sessionId); throw error; }
 }
 
 function latestAssistantText(value) {
@@ -789,10 +912,11 @@ 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 phase = options.readPhase ?? codexReadPhase(bridge, options);
+  const sessionId = required(options.sessionId, "--session-id"); const value = await readCodexRpc(bridge, "thread/read", { threadId: sessionId, includeTurns: false }, phase); const thread = value?.thread ?? value;
+  const terminal = options.turnId ? retainedCodexTurn(bridge, sessionId, options.turnId) ?? (await readTurn(bridge, sessionId, options.turnId, true, phase))?.turn : null;
   const exact = terminal?.id === options.turnId && terminal?.status === "failed" ? { terminal_turn_id: terminal.id, terminal_status: terminal.status, provider_error: nativeTurnError(bridge, sessionId, terminal), native_turn_items: turnItemEvidence(terminal, bridge, sessionId) } : {};
-  return { harness: "codex-desktop", provider_session_id: sessionId, adapter_session_id: sessionId, status: thread.status ?? null, thread: threadReceipt(thread), ...exact, descendants: await observedChildren(bridge, sessionId), 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") };
+  return { harness: "codex-desktop", provider_session_id: sessionId, adapter_session_id: sessionId, status: thread.status ?? null, thread: threadReceipt(thread), ...exact, descendants: await observedChildren(bridge, sessionId, phase), requested_profile: profile(options), observed_profile: await observeCodexProfile(bridge, options, sessionId, { model: thread.model ?? null, reasoning: thread.reasoningEffort ?? null, provider: thread.modelProvider ?? null }, "thread/read") };
 }
 
 export async function cancelSession(options) {
@@ -800,12 +924,21 @@ export async function cancelSession(options) {
 }
 
 export async function cancelSessionWithBridge(bridge, options) {
+  const phase = options.readPhase ?? codexReadPhase(bridge, options);
   const sessionId = required(options.sessionId, "--session-id");
   let turnId = options.turnId ?? null;
   if (!turnId) {
-    const 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;
+    const currentId = bridge.currentTurns?.get(sessionId);
+    const retained = retainedCodexTurn(bridge, sessionId, currentId);
+    turnId = currentId && !isTerminalTurnStatus(retained?.status) ? currentId : null;
+    if (!turnId) {
+      const history = await readCodexHistory(bridge, "thread/read", { threadId: sessionId, includeTurns: true }, phase);
+      if (!history.available || !Array.isArray(history.result.thread.turns)
+        || history.result.thread.turns.some(turn => typeof turn?.id !== "string" || !turn.id.trim()
+          || turn.status !== "inProgress" && !isTerminalTurnStatus(turn.status)))
+        fail("Codex active Turn cannot be established from incomplete history", "operation_observation_lost", { provider_session_id: sessionId, native_outcome: "unknown", history_error: history.error });
+      turnId = [...history.result.thread.turns].reverse().find((turn) => turn.status === "inProgress")?.id ?? null;
+    }
   }
   if (!turnId) fail("Codex Session has no active Turn to interrupt", "turn_not_active");
   await bridge.request("turn/interrupt", { threadId: sessionId, turnId });

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

@@ -178,8 +178,26 @@ export async function startDaemon(options) {
 export const stopDaemon = async 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, { readState: () => readState(options.stateDir) }); };
 
 export class Runtime {
-  constructor(paths, state, client, child, providerProcess) { this.paths = paths; this.state = state; this.client = client; this.child = child; this.providerProcess = providerProcess; this.sessions = new Map((state.sessions ?? []).map(x => [x.provider_session_id, x])); this.active = null; this.persisting = Promise.resolve(); }
+  constructor(paths, state, client, child, providerProcess) { this.paths = paths; this.state = state; this.client = client; this.child = child; this.providerProcess = providerProcess; this.sessions = new Map();
+    for (const record of state.sessions ?? []) {
+      if (typeof record?.provider_session_id !== "string" || !record.provider_session_id || this.sessions.has(record.provider_session_id))
+        throw new DaemonError("session_identity_mismatch", "OpenCode retained Session identity is invalid or duplicated");
+      this.sessions.set(record.provider_session_id, record);
+    }
+    this.active = null; this.persisting = Promise.resolve(); }
   persist(patch = {}) { Object.assign(this.state, patch, { pid: process.pid, sessions: [...this.sessions.values()] }); const snapshot = structuredClone(this.state); this.persisting = this.persisting.catch(() => {}).then(() => writeJson(this.paths.state, snapshot)); return this.persisting; }
+  retainSession(info, root) {
+    const id = info.id, parent = info.fork ? null : info.parentID ?? null, retained = this.sessions.get(id);
+    if (typeof id !== "string" || !id || typeof info.directory !== "string" || !path.isAbsolute(info.directory)
+      || retained && ((retained.parent_provider_session_id ?? null) !== parent
+        || retained.adapter_session_id && retained.adapter_session_id !== id
+        || retained.root_provider_session_id && retained.root_provider_session_id !== root))
+      throw new DaemonError("session_identity_mismatch", "OpenCode retained Session identity changed");
+    // Cwd is observed routing authority, not ownership identity: a moved owned
+    // Session must remain observable/cancellable. requireSettled fences dispatch.
+    const record = { provider_session_id: id, adapter_session_id: id, parent_provider_session_id: parent, root_provider_session_id: root, cwd: info.directory };
+    this.sessions.set(id, record); return record;
+  }
   async journal(operation, result) { const line = `${JSON.stringify({ schema_id: "dd-opencode/daemon-event@1", event_id: randomUUID(), observed_at: new Date().toISOString(), operation, active_tree: this.state.active_tree, session_id: result?.provider_session_id ?? null })}\n`; for (const journal of new Set([this.paths.journal, this.state.config.journal].filter(Boolean))) { await mkdir(path.dirname(journal), { recursive: true, mode: 0o700 }); await appendFile(journal, line, { mode: 0o600 }); } }
   async childTree(id, seen = new Set()) {
     if (seen.has(id)) throw new DaemonError("session_identity_mismatch", "OpenCode native topology contains a cycle");
@@ -195,13 +213,11 @@ export class Runtime {
     const parent = info.fork ? null : info.parentID ?? null, existing = this.sessions.get(id);
     if (info.id !== id || !existing && (!parent || !this.sessions.has(parent) || info.fork)
       || existing && (existing.parent_provider_session_id ?? null) !== parent) throw new DaemonError("foreign_session", "OpenCode Session is not in the retained owned tree");
-    const record = { provider_session_id: id, adapter_session_id: id, parent_provider_session_id: parent,
-      root_provider_session_id: parent ? this.sessions.get(parent)?.root_provider_session_id ?? parent : existing?.root_provider_session_id ?? id, cwd: info.directory };
-    this.sessions.set(id, record);
+    const record = this.retainSession(info, parent ? this.sessions.get(parent)?.root_provider_session_id ?? parent : existing?.root_provider_session_id ?? id);
     for (const child of children) {
       const retained = this.sessions.get(child.id);
       if (child.fork || retained && retained.parent_provider_session_id !== child.parentID) throw new DaemonError("session_identity_mismatch", "OpenCode child ancestry changed");
-      this.sessions.set(child.id, { provider_session_id: child.id, parent_provider_session_id: child.parentID, root_provider_session_id: record.root_provider_session_id, cwd: child.directory });
+      this.retainSession(child, record.root_provider_session_id);
     }
     const pending = new Map();
     for (const session of [id, ...children.map(child => child.id)]) {
@@ -287,6 +303,7 @@ export class Runtime {
     if (seen.has(id)) return [];
     const native = await this.client.inspect(id), retained = this.sessions.get(id);
     if (native.id !== id || (retained.parent_provider_session_id ?? null) !== (native.fork ? null : native.parentID ?? null)) throw new DaemonError("session_identity_mismatch", "OpenCode cancellation Session ancestry changed");
+    this.retainSession(native, retained.root_provider_session_id ?? id);
     seen.add(id);
     const errors = []; let children = [];
     try { children = await this.client.children(id); } catch (error) { errors.push({ session_id: id, phase: "children", ...errorPayload(error) }); }
@@ -294,7 +311,7 @@ export class Runtime {
       if (child.parentID !== id || child.fork || this.sessions.has(child.id) && this.sessions.get(child.id).parent_provider_session_id !== id) {
         errors.push({ session_id: child.id, phase: "identity", code: "session_identity_mismatch" }); continue;
       }
-      this.sessions.set(child.id, { provider_session_id: child.id, parent_provider_session_id: id, root_provider_session_id: this.sessions.get(id)?.root_provider_session_id ?? id, cwd: child.directory });
+      this.retainSession(child, this.sessions.get(id)?.root_provider_session_id ?? id);
       try { errors.push(...await this.cancelTree(child.id, seen)); }
       catch (error) { errors.push({ session_id: child.id, phase: "cancel_child", ...errorPayload(error) }); }
     }
@@ -499,7 +516,9 @@ export async function awaitOpenCodeStartup(client, state, child, { timeoutMs = S
         if (["loading", "activating", "registered"].includes(plugin?.state?.status)) await mark(`required_plugin_${plugin.state.status}`);
       } catch (error) {
         const transient = error.code === "opencode_unavailable" && error.retryable === true
-          && (error.details?.native_type === "ServiceUnavailableError" || phase === "server" && ["TypeError", "ConnectionError", "Error"].includes(error.details?.native_type));
+          // Safe pre-identity reads use the normalized observation category,
+          // not a version-specific SDK error wrapper. No productive RPC here.
+          && (phase === "server" || error.details?.native_type === "ServiceUnavailableError");
         if (!transient) throw error;
       }
       const pause = Math.min([250, 500, 1000, 2000][Math.min(attempt++, 3)], remaining());

package/dist/schemas/code-review-decision.schema.json

@@ -5,6 +5,15 @@
   "additionalProperties": false,
   "required": ["schema_id", "summary", "findings"],
   "properties": {
+    "accepted_intent_acknowledgement": {
+      "type": "object", "additionalProperties": false,
+      "required": ["reviewed_fingerprint", "current_fingerprint", "clarification_refs"],
+      "properties": {
+        "reviewed_fingerprint": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+        "current_fingerprint": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+        "clarification_refs": {"type": "array", "uniqueItems": true, "items": {"type": "string", "pattern": "^HITL-[A-Za-z0-9._-]+$"}}
+      }
+    },
     "schema_id": {"const": "dd-flow/code-review-decision@3"},
     "summary": {"type": "string", "minLength": 1},
     "findings": {

package/dist/schemas/flow-run.schema.json

@@ -39,6 +39,7 @@
       }
     },
     "verification_matrix_contract": {"const": "dd-flow/verification-matrix@1"},
+    "accepted_intent_contract": {"const": "dd-flow/accepted-intent@1"},
     "final_check_coverage_contract": {"const": "dd-flow/final-check-coverage@1"},
     "status": {"enum": ["created", "running", "paused", "waiting_for_user", "done", "failed", "blocked", "cancelled", "discarded"]},
     "verdict": {"type": ["string", "null"]},

package/dist/schemas/plan-review-decision.schema.json

@@ -5,6 +5,15 @@
   "additionalProperties": false,
   "required": ["schema_id", "outcome", "summary", "finding_decisions", "correction"],
   "properties": {
+    "accepted_intent_acknowledgement": {
+      "type": "object", "additionalProperties": false,
+      "required": ["reviewed_fingerprint", "current_fingerprint", "clarification_refs"],
+      "properties": {
+        "reviewed_fingerprint": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+        "current_fingerprint": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+        "clarification_refs": {"type": "array", "uniqueItems": true, "items": {"type": "string", "pattern": "^HITL-[A-Za-z0-9._-]+$"}}
+      }
+    },
     "schema_id": {"const": "dd-flow/plan-review-decision@4"},
     "outcome": {"enum": ["accepted", "failed", "cancelled"]},
     "summary": {"type": "string", "minLength": 1},