ai-foreman 1.7.29 → 2.0.1

package/dist/adapters/codex.d.ts

@@ -1,6 +1,6 @@
-import type { ProviderTurnPurpose } from "../providerPhase.js";
 import type { BuilderAdapter, BuilderAdapterOptions, BuilderEvent, CompactResult, ContextUsage, NativeAutoCompactionPolicy, NativeCompaction, ProviderSessionUsage, ProviderSettingSwitch, TurnResult } from "./types.js";
 import type { ProviderSessionRefV1, SessionAvailabilityV1 } from "rafi-spec";
+import type { ProviderTurnPolicy } from "./types.js";
 export interface CodexLineResult {
     events: BuilderEvent[];
     sessionId?: string;
@@ -30,6 +30,12 @@ export declare class CodexAdapter implements BuilderAdapter {
     private closed;
     private closePromise?;
     private activeText;
+    private structuredCollector?;
+    private turnStreamedBytes;
+    private streamStartedAt;
+    private streamActivityAt;
+    private streamDiagnosticAt;
+    private turnInFlight;
     private usage?;
     private usageRevision;
     private providerSessionUsage?;
@@ -82,12 +88,7 @@ export declare class CodexAdapter implements BuilderAdapter {
     buildAppServerArgs(): string[];
     /** Deprecated fixture helper. Runtime execution uses only app-server. */
     buildArgs(instruction: string): string[];
-    sendTurn(instruction: string, policy?: {
-        handback?: boolean;
-        responseOnly?: boolean;
-        logicalActionId?: string;
-        purpose?: ProviderTurnPurpose;
-    }): Promise<TurnResult>;
+    sendTurn(instruction: string, policy?: ProviderTurnPolicy): Promise<TurnResult>;
     private sendTurnInternal;
     compact(): Promise<CompactResult>;
     private compactInternal;
@@ -119,9 +120,20 @@ export declare class CodexAdapter implements BuilderAdapter {
     private handle;
     private observationContext;
     private waitFor;
+    /** Ask the app-server to stop a native turn; true only once its terminal is observed. */
+    private interruptNativeTurn;
+    /** Streamed output is visible progress; it is never treated as a result. */
+    private observeAgentMessageDelta;
+    /**
+     * Bounded interruption evidence for structured turns under .foreman (Rafi's
+     * git-excluded log directory). Diagnostic only: never read back as output.
+     */
+    private writeStreamDiagnostic;
     private traceLifecycle;
     private touchWaiters;
     private providerIdleTimeoutMs;
+    /** Read-only QA may reach the network only with the operator's --qa-network grant. */
+    private qaNetworkAccess;
     private effectiveNetworkAccess;
     private effectiveApprovalPolicy;
     /** Fail closed; approval is for this operation only, never a session cache or policy amendment. */

package/dist/adapters/codex.js

@@ -1,7 +1,8 @@
+import { inheritedStructuredLiveBudget } from "../structuredLiveBudget.js";
 import { OperationDeadline } from "../util/deadline.js";
 import { spawn } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { createInterface } from "node:readline";
 import { loadSkill } from "special-agents";
@@ -11,6 +12,9 @@ import { canonicalSessionPath, createProviderSessionRef, validateProviderSession
 import { SessionUnavailableError, sessionUnavailableResult } from "./sessionFailure.js";
 import { isFastModeUnavailable, reportFastModeUnavailable } from "./fastMode.js";
 import { handoffSystemInstructions } from "../handoffProtocol.js";
+import { providerControlOperationV2, providerWireContract, renderProviderWireInstruction, initializationOutput, validateStructuredCandidate, selectedDispatchTupleV2, structuredDigest } from "rafi-spec";
+import { assertActiveProviderDispatch, withEphemeralInitializationDispatch } from "../structuredDispatchAuthority.js";
+import { CodexRunawayOutputError, CodexTurnCollector, structuredReceipt } from "./structured.js";
 /** Compatibility parser for recorded pre-app-server JSONL fixtures. */
 export function parseCodexLine(raw) {
     const type = raw.type;
@@ -46,6 +50,12 @@ export class CodexAdapter {
     closed = false;
     closePromise;
     activeText = [];
+    structuredCollector;
+    turnStreamedBytes = 0;
+    streamStartedAt = 0;
+    streamActivityAt = 0;
+    streamDiagnosticAt = 0;
+    turnInFlight = false;
     usage;
     usageRevision = 0;
     providerSessionUsage;
@@ -117,6 +127,7 @@ export class CodexAdapter {
     }
     constructor(opts) {
         this.opts = opts;
+        inheritedStructuredLiveBudget("codex");
         this._sessionId = opts.resumeSessionRef?.sessionId ?? opts.resumeSessionId;
         this._sessionRef = opts.resumeSessionRef;
     }
@@ -140,6 +151,7 @@ export class CodexAdapter {
     buildInstruction(instruction) {
         return [this.opts.systemPromptAppend,
             this.opts.sessionRole === "builder" ? `Builder runtime contract: shell network ${this.effectiveNetworkAccess() ? "explicitly approved for this build" : "disabled"}; sandbox escalation ${this.effectiveApprovalPolicy() === "on-request" ? "requires separate approval for each exact operation" : "disabled"}. Web tools do not establish shell network access. If acquisition needs unavailable capabilities, request input before running acquisition, or use a local source/dependency bundle with verified provenance. A ticket answer does not change runtime permissions.` : undefined,
+            this.qaNetworkAccess() ? "QA runtime contract: shell network explicitly approved for this review (--qa-network); you may run live checks against operator-provided local or remote services. Workspace stays read-only." : undefined,
             this.buildSkillsAppendix(), instruction]
             .filter((part) => Boolean(part)).join("\n\n");
     }
@@ -163,9 +175,23 @@ export class CodexAdapter {
         return args;
     }
     async sendTurn(instruction, policy) {
+        if (this.turnInFlight)
+            throw new Error("a turn is already in progress");
+        if (policy?.output)
+            assertActiveProviderDispatch(policy, instruction, "codex", this.sessionRef());
+        if (policy?.output) {
+            const selected = policy.wireContract ?? providerWireContract(policy.output, "codex", "default", { requireRegistered: true });
+            if (selected.provider !== "codex" || selected.canonical.schemaDigest !== policy.output.schemaDigest)
+                throw new Error("Codex received a mismatched provider wire contract");
+            if (policy.renderedWireContractDigest && policy.renderedWireContractDigest !== selected.descriptorDigest)
+                throw new Error("Codex received mismatched rendered wire guidance");
+            instruction = renderProviderWireInstruction(instruction, selected);
+            policy = { ...policy, wireContract: selected, renderedWireContractDigest: selected.descriptorDigest };
+        }
+        this.turnInFlight = true;
         const prepared = this.instructionWithPendingQaReminder(instruction);
         instruction = prepared.instruction;
-        const turnId = randomUUID();
+        const turnId = policy?.dispatchId ?? randomUUID();
         this.activeProviderTurnId = turnId;
         const observer = this.opts.observer;
         if (!observer) {
@@ -187,6 +213,8 @@ export class CodexAdapter {
             finally {
                 this.activeProviderTurnId = undefined;
                 this.activeNativeTurnId = undefined;
+                this.structuredCollector = undefined;
+                this.turnInFlight = false;
             }
         }
         const context = this.observationContext();
@@ -218,9 +246,11 @@ export class CodexAdapter {
             this.activeProviderTurnId = undefined;
             this.activeNativeTurnId = undefined;
             this.activeProviderTurnSpanId = undefined;
+            this.structuredCollector = undefined;
+            this.turnInFlight = false;
         }
     }
-    async sendTurnInternal(instruction, policy) {
+    async sendTurnInternal(instruction, policy, runawayRetries = 0) {
         if (this.closed)
             throw new Error("builder is closed");
         this.eventQueue.push({ kind: "activity", state: "starting Codex turn", provider: "codex", model: this.opts.model });
@@ -233,12 +263,29 @@ export class CodexAdapter {
             const toolsBefore = this.observedToolCalls;
             this.turnSawTool = false;
             this.activeText = [];
+            this.turnStreamedBytes = 0;
+            this.streamStartedAt = 0;
+            this.streamActivityAt = 0;
+            this.streamDiagnosticAt = 0;
             this.lastTurnTokens = undefined;
             this.turnUsageBaseline = this.providerSessionUsage ? { ...this.providerSessionUsage } : undefined;
-            const completion = this.waitFor("turn/completed", (params) => params.threadId === this._sessionId, this.providerIdleTimeoutMs(), true);
-            void completion.catch(() => { });
+            const deadline = new OperationDeadline("Codex active turn", this.opts.turnDeadlineMs ?? 3_600_000);
+            let idleTimer;
+            const clearIdle = () => { if (idleTimer)
+                clearTimeout(idleTimer); idleTimer = undefined; };
+            const resetIdle = () => {
+                clearIdle();
+                idleTimer = setTimeout(() => collector?.fail(new Error("Codex native turn idle deadline expired; execution outcome requires reconciliation")), this.providerIdleTimeoutMs());
+                idleTimer.unref();
+            };
+            const wire = policy?.output ? policy.wireContract ?? providerWireContract(policy.output, "codex", "default", { requireRegistered: true }) : undefined;
+            const collector = policy?.output ? this.structuredCollector = new CodexTurnCollector(this._sessionId, true, resetIdle, wire.maximumResponseBytes) : undefined;
+            const completion = collector ? collector.completion : this.waitFor("turn/completed", (params) => params.threadId === this._sessionId, this.providerIdleTimeoutMs(), true);
+            void completion.then(clearIdle, clearIdle);
             turnStartDispatched = true;
+            const readOnlyTurn = Boolean(policy?.responseOnly || policy?.purpose && policy.purpose !== "implementation" || this.opts.sandboxMode === "read-only" || this.opts.sessionRole === "qa");
             const startParams = {
+                ...(wire ? { outputSchema: wire.wireSchema } : {}),
                 threadId: this._sessionId,
                 input: [{ type: "text", text: providerInstruction, text_elements: [] }],
                 cwd: this.opts.cwd,
@@ -246,41 +293,82 @@ export class CodexAdapter {
                 effort: this.opts.effort ?? null,
                 ...(this.opts.fast ? { serviceTier: this.fastTier ?? "default" } : {}),
                 approvalPolicy: policy?.responseOnly || policy?.purpose && policy.purpose !== "implementation" ? "never" : this.effectiveApprovalPolicy(),
-                sandboxPolicy: policy?.responseOnly || policy?.purpose && policy.purpose !== "implementation" || this.opts.sandboxMode === "read-only" || this.opts.sessionRole === "qa"
-                    ? { type: "readOnly", networkAccess: false }
+                sandboxPolicy: readOnlyTurn
+                    ? { type: "readOnly", networkAccess: this.qaNetworkAccess() }
                     : { type: "workspaceWrite", writableRoots: [this.opts.cwd], networkAccess: this.effectiveNetworkAccess() },
             };
             let started;
             try {
-                started = await this.request("turn/start", startParams);
+                started = await deadline.run(() => this.request("turn/start", startParams));
             }
             catch (error) {
-                if (!this.fastTier || !isFastModeUnavailable(String(error)) || this.turnSawTool || this.activeText.length)
+                if (policy?.output || !this.fastTier || !isFastModeUnavailable(String(error)) || this.turnSawTool || this.activeText.length)
                     throw error;
                 this.disableFastMode();
                 started = await this.request("turn/start", { ...startParams, serviceTier: "default" });
             }
             this.activeNativeTurnId = String(started.turn?.id ?? "") || undefined;
-            const params = await new OperationDeadline("Codex active turn", this.opts.turnDeadlineMs ?? 3_600_000).run(() => completion);
-            const turn = params.turn;
-            const responseOnlyViolation = Boolean(policy?.responseOnly && this.observedToolCalls !== toolsBefore);
-            const failed = turn?.status === "failed" || responseOnlyViolation;
+            collector?.bind(this.activeNativeTurnId ?? "");
+            let params;
+            try {
+                params = await deadline.run(() => completion);
+            }
+            catch (error) {
+                // Runaway output is a definite provider rejection, not an unknown
+                // outcome. A read-only turn cannot change the workspace, so after the
+                // native turn is confirmed stopped it may be asked once more, inside
+                // the same sealed host dispatch. Writable turns are never retried.
+                const nativeTurnId = this.activeNativeTurnId;
+                if (error instanceof CodexRunawayOutputError && runawayRetries < 1 && readOnlyTurn && nativeTurnId && await this.interruptNativeTurn(nativeTurnId)) {
+                    this.writeStreamDiagnostic("interrupted", `${error.message}; retrying once`);
+                    this.traceLifecycle("runaway-output-retry", { elapsedMs: 0 });
+                    this.eventQueue.push({ kind: "retry", provider: "codex", reason: error.message, attempt: 1, maximum: 1, managedBy: "rafi", retryId: nativeTurnId });
+                    return this.sendTurnInternal(instruction, policy, runawayRetries + 1);
+                }
+                throw error;
+            }
+            const turn = collector ? params : params.turn;
+            const responseOnlyViolation = Boolean(policy?.responseOnly && (collector ? collector.tools : this.observedToolCalls !== toolsBefore));
+            const failed = turn?.status !== "completed" || responseOnlyViolation;
             const error = turn?.error;
-            const text = this.activeText.join("\n");
-            if (failed && !responseOnlyViolation && this.fastTier && !this.turnSawTool && !text && isFastModeUnavailable(String(error?.message ?? ""))) {
+            let final;
+            let invalidFinal;
+            try {
+                final = collector?.final();
+            }
+            catch (error) {
+                invalidFinal = String(error);
+            }
+            if (this.streamDiagnosticAt)
+                this.writeStreamDiagnostic(failed || invalidFinal ? "interrupted" : "completed", failed ? `Codex terminal ${String(turn?.status)}` : invalidFinal);
+            const text = final?.text ?? this.activeText.join("\n");
+            if (!policy?.output && failed && !responseOnlyViolation && this.fastTier && !this.turnSawTool && !text && isFastModeUnavailable(String(error?.message ?? ""))) {
                 this.disableFastMode();
                 return this.sendTurnInternal(instruction, policy);
             }
-            const result = {
+            let result = {
                 text: failed ? normalizeRuntimeErrorText("codex", String(responseOnlyViolation ? "Response-only correction used tools; its result cannot authorize completion" : error?.message ?? text), null, "app-server turn") : text,
                 isError: failed, numTurns: 1, costUsd: 0, costAuthoritative: false,
                 turnId: this.activeProviderTurnId, hostInstruction: instruction, providerInstruction,
                 rawResponse: text, cleanedResponse: failed ? normalizeRuntimeErrorText("codex", String(responseOnlyViolation ? "Response-only correction used tools; its result cannot authorize completion" : error?.message ?? text), null, "app-server turn") : text,
                 providerMetadata: { provider: "codex", sessionId: this._sessionId, sessionRef: this._sessionRef },
+                ...(policy?.selectedDispatch ? { selectedDispatch: policy.selectedDispatch } : {}),
                 ...(this.lastTurnTokens ?? {}),
             };
             result.usage = { scope: "turn-delta", inputTokens: result.inputTokens, outputTokens: result.outputTokens,
                 ...(result.inputTokens !== undefined || result.outputTokens !== undefined ? { totalTokens: (result.inputTokens ?? 0) + (result.outputTokens ?? 0) } : {}) };
+            if (policy?.output) {
+                const selectedDispatch = policy.selectedDispatch;
+                if (!selectedDispatch || !this._sessionId)
+                    throw new Error("Structured terminal lost its sealed dispatch tuple or session");
+                result = { ...result, selectedDispatch, structured: failed ? { state: "rejected", reason: responseOnlyViolation ? "tool-policy-violation" : "execution-not-completed", detail: `Codex terminal ${String(turn?.status)}`, dispatchId: result.turnId }
+                        : invalidFinal ? { state: "rejected", reason: "ambiguous-result", detail: invalidFinal, dispatchId: result.turnId }
+                            : !wire || !policy.selectedDispatch
+                                ? { state: "rejected", reason: "invalid-contract", detail: "Codex structured turn has no sealed descriptor or tuple", dispatchId: result.turnId }
+                                : structuredReceipt(policy.output, "codex", final?.itemId ? text : undefined, { dispatchId: result.turnId, sessionId: this._sessionId, nativeTurnId: this.activeNativeTurnId, nativeItemId: final?.itemId }, "json-text", wire, policy.selectedDispatch) };
+                if (result.structured.state === "rejected")
+                    result.isError = true;
+            }
             this.eventQueue.push({ kind: "turn-complete", result, turnId: result.turnId });
             return result;
         }
@@ -298,6 +386,8 @@ export class CodexAdapter {
                 return result;
             }
             const detail = [error instanceof Error ? error.message : String(error), this.stderr].filter(Boolean).join("\n");
+            if (this.turnStreamedBytes)
+                this.writeStreamDiagnostic("interrupted", error instanceof Error ? error.message : String(error));
             const text = normalizeRuntimeErrorText("codex", detail, this.process?.exitCode ?? null, "builder turn");
             this.disconnect(new Error(text));
             const resumed = Boolean(this.opts.resumeSessionRef);
@@ -379,6 +469,7 @@ export class CodexAdapter {
             }, hardTimeoutMs, false, controller.signal);
             this.manualCompactionInFlight = true;
             try {
+                providerControlOperationV2("codex", "thread/compact/start");
                 const acknowledgementFailure = this.request("thread/compact/start", { threadId: this._sessionId }).then(() => { this.traceLifecycle("compaction-acknowledged"); return new Promise(() => { }); }, error => {
                     // A missing acknowledgement is not failure evidence. Explicit
                     // completion plus fresh occupancy is sufficient to reconcile it.
@@ -391,6 +482,13 @@ export class CodexAdapter {
             finally {
                 this.manualCompactionInFlight = false;
             }
+            // Manual completion must invalidate delivery receipts just like automatic
+            // compaction. Continuity accounts for this requested compaction separately.
+            this.nativeCompactionSequence++;
+            if (this.qaContractReminder) {
+                this.qaContractReminderPending = true;
+                this.qaReminderEvent("compaction-observed");
+            }
             this.eventQueue.push({ kind: "session-transition", transition: "compacted" });
             this.traceLifecycle("compaction-completed", { elapsedMs: performance.now() - began });
             return { ok: true };
@@ -437,11 +535,28 @@ export class CodexAdapter {
             if (this.opts.allowAutoCompactionSetupTurn === false)
                 return;
             const toolsBefore = this.observedToolCalls;
-            const setup = await this.sendTurnInternal("Rafi internal initialization only. Do not call tools or modify files. Reply briefly that the context is ready.", { purpose: "initialization", responseOnly: true });
+            const descriptor = providerWireContract(initializationOutput, "codex");
+            const instruction = renderProviderWireInstruction("Rafi internal initialization only. Do not call tools or modify files. Submit the native session-initialization result with completed payload {ready:true} and null continuity.", descriptor);
+            const session = this.sessionRef();
+            if (!session)
+                throw new Error("Ephemeral Codex initialization requires a prepared session");
+            const id = randomUUID();
+            const tuple = selectedDispatchTupleV2({ operation: initializationOutput.operation, schemaVersion: initializationOutput.schemaVersion, schemaDigest: initializationOutput.schemaDigest,
+                provider: "codex", profile: descriptor.profile, variant: descriptor.variant, descriptorDigest: descriptor.descriptorDigest,
+                wireSchemaDigest: descriptor.wireSchemaDigest, guidanceDigest: descriptor.guidanceDigest, normalizerId: descriptor.normalizerId,
+                normalizerVersion: descriptor.normalizerVersion, maximumSchemaBytes: descriptor.maximumSchemaBytes, maximumResponseBytes: descriptor.maximumResponseBytes,
+                maximumPageBytes: descriptor.maximumPageBytes ?? null, instructionDigest: structuredDigest(instruction), actionId: id, dispatchId: id, sessionId: session.sessionId, generation: session.generation });
+            const setup = await withEphemeralInitializationDispatch(this.opts.configRoot ?? this.opts.cwd, tuple, dispatchCapability => this.sendTurn(instruction, { purpose: "initialization", responseOnly: true, output: initializationOutput, dispatchId: id, logicalActionId: id, wireContract: descriptor,
+                renderedWireContractDigest: descriptor.descriptorDigest, selectedDispatch: tuple, dispatchCapability }), session);
             if (setup.isError)
                 throw new Error(`Codex automatic-compaction setup failed: ${setup.text.slice(0, 240)}`);
             if (this.observedToolCalls !== toolsBefore)
                 throw new Error("Codex automatic-compaction setup unexpectedly called a tool");
+            if (!setup.selectedDispatch)
+                throw new Error("Codex initialization returned no sealed dispatch tuple");
+            const accepted = validateStructuredCandidate(initializationOutput, setup.structured, providerWireContract(initializationOutput, "codex"), setup.selectedDispatch);
+            if (accepted.result.kind !== "completed" || !accepted.result.payload.ready)
+                throw new Error("Codex initialization did not confirm readiness");
         }
         const maximum = this.usage?.maximum;
         if (!maximum || !Number.isFinite(maximum) || maximum <= 0) {
@@ -527,6 +642,8 @@ export class CodexAdapter {
         if (this.closed)
             return;
         this.closed = true;
+        if (this.turnInFlight && this.turnStreamedBytes)
+            this.writeStreamDiagnostic("interrupted", "adapter closed during an active turn");
         const child = this.process;
         let onExit;
         const exited = child && child.exitCode === null ? new Promise(resolve => { onExit = resolve; child.once("exit", resolve); }) : Promise.resolve();
@@ -716,7 +833,17 @@ export class CodexAdapter {
         if (!message.method)
             return;
         const params = message.params ?? {};
-        if (message.method === "item/started") {
+        this.structuredCollector?.ingest(message.method, params);
+        // Native receipts and tool observations must belong to the same dispatch.
+        // Foreign notifications remain unable to affect completion or evidence.
+        if (this.structuredCollector && (params.threadId && params.threadId !== this._sessionId || this.activeNativeTurnId && params.turnId && params.turnId !== this.activeNativeTurnId))
+            return;
+        if (message.method === "item/agentMessage/delta") {
+            if (!this.turnInFlight || params.threadId && this._sessionId && params.threadId !== this._sessionId)
+                return;
+            this.observeAgentMessageDelta(params);
+        }
+        else if (message.method === "item/started") {
             const item = params.item;
             if (item)
                 this.eventQueue.push({ kind: "provider-item", provider: "codex", lifecycle: "started", itemType: String(item.type ?? "unknown"), payload: exactProviderItem(item), payloadCompleteness: "complete", providerTurnId: this.activeProviderTurnId, eventId: randomUUID(), observedAt: new Date().toISOString() });
@@ -904,6 +1031,54 @@ export class CodexAdapter {
             }
         });
     }
+    /** Ask the app-server to stop a native turn; true only once its terminal is observed. */
+    async interruptNativeTurn(nativeTurnId) {
+        const stopped = this.waitFor("turn/completed", params => params.threadId === this._sessionId && params.turn?.id === nativeTurnId, 15_000)
+            .then(() => true, () => false);
+        try {
+            await new OperationDeadline("Codex turn interrupt", 10_000).run(() => this.request("turn/interrupt", { threadId: this._sessionId, turnId: nativeTurnId }));
+        }
+        catch (error) {
+            this.traceLifecycle("turn-interrupt-failed", { method: error instanceof Error ? error.message.slice(0, 200) : "unknown" });
+        }
+        return stopped;
+    }
+    /** Streamed output is visible progress; it is never treated as a result. */
+    observeAgentMessageDelta(params) {
+        if (typeof params.delta !== "string")
+            return;
+        this.turnStreamedBytes += Buffer.byteLength(params.delta);
+        const now = Date.now();
+        if (!this.streamStartedAt)
+            this.streamStartedAt = now;
+        if (now - this.streamActivityAt >= 1_000) {
+            this.streamActivityAt = now;
+            this.eventQueue.push({ kind: "activity", provider: "codex", state: "writing response", detail: `${formatStreamBytes(this.turnStreamedBytes)} streamed`, transient: true });
+        }
+        if (now - (this.streamDiagnosticAt || this.streamStartedAt) >= 2_000)
+            this.writeStreamDiagnostic("streaming");
+    }
+    /**
+     * Bounded interruption evidence for structured turns under .foreman (Rafi's
+     * git-excluded log directory). Diagnostic only: never read back as output.
+     */
+    writeStreamDiagnostic(state, detail) {
+        const collector = this.structuredCollector, nativeTurnId = this.activeNativeTurnId, threadId = this._sessionId;
+        if (!collector || !nativeTurnId || !threadId)
+            return;
+        this.streamDiagnosticAt = Date.now();
+        try {
+            const safe = (value) => value.replace(/[^A-Za-z0-9_.-]/g, "_").slice(0, 120);
+            const dir = join(this.opts.configRoot ?? this.opts.cwd, ".foreman", "provider-streams");
+            mkdirSync(dir, { recursive: true });
+            const path = join(dir, `codex-${safe(threadId)}-${safe(nativeTurnId)}.json`);
+            const body = { version: 1, provider: "codex", state, threadId, nativeTurnId, dispatchId: this.activeProviderTurnId, updatedAt: new Date().toISOString(),
+                ...(detail ? { detail: Buffer.from(detail).subarray(0, 2_000).toString() } : {}), ...collector.streamDiagnostic() };
+            writeFileSync(`${path}.tmp`, JSON.stringify(body, null, 2));
+            renameSync(`${path}.tmp`, path);
+        }
+        catch { /* diagnostics cannot change execution */ }
+    }
     traceLifecycle(phase, data = {}) {
         try {
             this.opts.onLifecycleTrace?.({ phase, at: new Date().toISOString(), sessionId: this._sessionId, ...data });
@@ -916,9 +1091,13 @@ export class CodexAdapter {
                 waiter.touch?.();
     }
     providerIdleTimeoutMs() {
-        const configured = this.opts.providerIdleTimeoutMs;
+        const configured = this.opts.providerIdleTimeoutMs ?? Number(process.env.RAFI_PROVIDER_IDLE_TIMEOUT_MS);
         return Number.isFinite(configured) && configured > 0 ? configured : DEFAULT_PROVIDER_IDLE_TIMEOUT_MS;
     }
+    /** Read-only QA may reach the network only with the operator's --qa-network grant. */
+    qaNetworkAccess() {
+        return this.opts.sessionRole === "qa" && this.opts.networkAccess === true;
+    }
     effectiveNetworkAccess() {
         return this.opts.sandboxMode !== "read-only" && this.opts.sessionRole !== "qa" && this.opts.networkAccess === true;
     }
@@ -973,6 +1152,7 @@ export class CodexAdapter {
         }
     }
     disconnect(error) {
+        this.structuredCollector?.fail(error);
         this.connectionGeneration++;
         for (const controller of this.approvalRequests.values())
             controller.abort();
@@ -1088,3 +1268,6 @@ function loadSkillMarkdown(cwd, skill) {
 function cumulativeDelta(before, after) {
     return before !== undefined && after !== undefined && after >= before ? after - before : undefined;
 }
+function formatStreamBytes(bytes) {
+    return bytes < 1024 ? `${bytes} B` : bytes < 1_048_576 ? `${(bytes / 1024).toFixed(1)} KB` : `${(bytes / 1_048_576).toFixed(1)} MB`;
+}

package/dist/adapters/recovering.d.ts

@@ -18,6 +18,8 @@ export interface RecoveringAdapterOptions {
 /** Adds interactive recovery around structured runtime turn failures. */
 export declare class RecoveringAdapter implements BuilderAdapter {
     private readonly opts;
+    postConfirmedDispatch(reference: import("../adapters/types.js").ConfirmedDispatchReference): Promise<TurnResult | void>;
+    structuredDispatchRequirement(): import("../adapters/types.js").StructuredDispatchRequirement | undefined;
     private adapter;
     private runtime;
     private readonly eventQueue;

package/dist/adapters/recovering.js

@@ -5,6 +5,8 @@ import { randomUUID } from "node:crypto";
 /** Adds interactive recovery around structured runtime turn failures. */
 export class RecoveringAdapter {
     opts;
+    postConfirmedDispatch(reference) { return this.adapter.postConfirmedDispatch?.(reference) ?? Promise.resolve(); }
+    structuredDispatchRequirement() { return this.adapter.structuredDispatchRequirement?.(); }
     adapter;
     runtime;
     eventQueue = new AsyncQueue();
@@ -45,7 +47,9 @@ export class RecoveringAdapter {
                     this.eventQueue.push({ kind: "error", message: `failed to persist scoped provider session binding: ${error instanceof Error ? error.message : String(error)}` });
                 }
             }
-            if (policy?.handback || !this.opts.enabled || !result.isError || !result.failure)
+            // Structured operations have one recovery owner above the adapter. Never
+            // hide a second actual dispatch behind the same request/receipt identity.
+            if (policy?.output || policy?.handback || !this.opts.enabled || !result.isError || !result.failure)
                 return result;
             // The host cannot know whether a missing exact session received this
             // instruction. Never replay it or silently switch providers.

package/dist/adapters/structured.d.ts

@@ -0,0 +1,71 @@
+import { providerWireContract, type OutputContract, type SelectedDispatchTupleV2, type StructuredResponse } from "rafi-spec";
+export declare function structuredReceipt(contract: OutputContract, provider: "claude" | "codex", value: unknown, identity: {
+    dispatchId: string;
+    sessionId: string;
+    nativeTurnId?: string;
+    nativeItemId?: string;
+}, representation: "json-text" | "decoded-json", selected: ReturnType<typeof providerWireContract>, tuple: SelectedDispatchTupleV2): StructuredResponse;
+/** Pretty-printed JSON never needs this much consecutive whitespace. */
+export declare const CODEX_RUNAWAY_WHITESPACE_BYTES = 2048;
+/** The provider is emitting a runaway whitespace sequence; its output can never be accepted. */
+export declare class CodexRunawayOutputError extends Error {
+    readonly itemId: string;
+    readonly whitespaceBytes: number;
+    constructor(itemId: string, whitespaceBytes: number);
+}
+/** Bounded, non-authoritative view of one streamed agent message. */
+export interface CodexStreamItemDiagnostic {
+    itemId: string;
+    bytes: number;
+    deltas: number;
+    completed: boolean;
+    whitespaceRun: number;
+    head: string;
+    tail: string;
+    textRetained: boolean;
+    startedAt: string;
+    lastDeltaAt: string;
+}
+export interface CodexStreamDiagnostic {
+    authoritative: false;
+    streamedBytes: number;
+    deltas: number;
+    items: CodexStreamItemDiagnostic[];
+}
+/** Holds early notifications until turn/start supplies the exact turn identity. */
+export declare class CodexTurnCollector {
+    private readonly threadId;
+    private readonly requirePhase;
+    private readonly onProgress?;
+    private readonly maximumResponseBytes;
+    private turnId?;
+    private early;
+    private bytes;
+    private finals;
+    private streams;
+    private streamedBytes;
+    private streamedDeltas;
+    private earlyDeltaBytes;
+    private terminal?;
+    private error?;
+    tools: boolean;
+    private resolve;
+    private reject;
+    readonly completion: Promise<Record<string, unknown>>;
+    constructor(threadId: string, requirePhase: boolean, onProgress?: (() => void) | undefined, maximumResponseBytes?: number);
+    bind(turnId: string): void;
+    ingest(method: string, params: Record<string, unknown>): void;
+    /**
+     * Streamed text is bounded before completion, but never becomes a result:
+     * only a completed final item is accepted and charged against the budget.
+     */
+    private ingestDelta;
+    streamDiagnostic(): CodexStreamDiagnostic;
+    fail(error: Error): void;
+    private invalidate;
+    private settle;
+    final(): {
+        text: string;
+        itemId?: string;
+    };
+}