ai-foreman 1.7.25 → 1.7.27

package/dist/adapters/codex.js

@@ -9,6 +9,8 @@ import { BuilderEventQueue, withActivityPhase } from "../activity.js";
 import { normalizeRuntimeErrorText } from "../runtimeAuth.js";
 import { canonicalSessionPath, createProviderSessionRef, validateProviderSessionScope } from "../sessionIdentity.js";
 import { SessionUnavailableError, sessionUnavailableResult } from "./sessionFailure.js";
+import { isFastModeUnavailable, reportFastModeUnavailable } from "./fastMode.js";
+import { handoffSystemInstructions } from "../handoffProtocol.js";
 /** Compatibility parser for recorded pre-app-server JSONL fixtures. */
 export function parseCodexLine(raw) {
     const type = raw.type;
@@ -42,6 +44,7 @@ export class CodexAdapter {
     sessionAvailability;
     initialized = false;
     closed = false;
+    closePromise;
     activeText = [];
     usage;
     usageRevision = 0;
@@ -67,12 +70,73 @@ export class CodexAdapter {
     answeredApprovalRequests = new Set();
     activeProviderTurnSpanId;
     toolSpans = new Map();
+    effectiveModel;
+    fastPreparedModel;
+    fastTier;
+    fastUnavailableModels = new Set();
+    turnSawTool = false;
+    /** Native compaction is non-blocking. The next host turn gets this reminder. */
+    qaContractReminder;
+    qaContractReminderPending = false;
+    qaContractReminderEvent;
+    disableFastMode() {
+        const model = this.opts.model ?? this.effectiveModel ?? "default";
+        if (!this.fastUnavailableModels.has(model))
+            reportFastModeUnavailable(model);
+        this.fastUnavailableModels.add(model);
+        this.fastTier = undefined;
+    }
+    async prepareFastMode() {
+        const model = this.opts.model ?? this.effectiveModel ?? "default";
+        if (!this.opts.fast || this.fastPreparedModel === model)
+            return;
+        this.fastPreparedModel = model;
+        this.fastTier = undefined;
+        if (this.fastUnavailableModels.has(model))
+            return;
+        try {
+            let cursor;
+            for (let page = 0; page < 20; page++) {
+                const result = await this.request("model/list", { includeHidden: true, ...(cursor ? { cursor } : {}) });
+                const entry = result.data?.find(item => item.model === model || item.id === model);
+                if (entry) {
+                    this.fastTier = entry.serviceTiers?.find(tier => tier.name?.toLowerCase() === "fast" || ["fast", "priority"].includes(tier.id))?.id;
+                    // Older app-server versions publish only the legacy speed list.
+                    if (entry.serviceTiers === undefined && entry.additionalSpeedTiers?.includes("fast"))
+                        this.fastTier = "fast";
+                    break;
+                }
+                if (!result.nextCursor || result.nextCursor === cursor)
+                    break;
+                cursor = result.nextCursor;
+            }
+        }
+        catch { /* Optional capability discovery never blocks a standard turn. */ }
+        if (!this.fastTier)
+            this.disableFastMode();
+    }
     constructor(opts) {
         this.opts = opts;
         this._sessionId = opts.resumeSessionRef?.sessionId ?? opts.resumeSessionId;
         this._sessionRef = opts.resumeSessionRef;
     }
     contractCapabilities() { return { sameSessionAcceptance: true, nativeCompactionBarrier: false }; }
+    contractCompactionSequence() { return this.nativeCompactionSequence; }
+    configureQaContractReminder(reminder, onEvent) {
+        this.qaContractReminder = reminder;
+        this.qaContractReminderEvent = onEvent;
+        onEvent?.({ kind: "installed", at: new Date().toISOString(), sessionId: this._sessionId });
+    }
+    qaReminderEvent(kind) {
+        this.qaContractReminderEvent?.({ kind, at: new Date().toISOString(), sessionId: this._sessionId });
+    }
+    instructionWithPendingQaReminder(instruction) {
+        if (!this.qaContractReminderPending || !this.qaContractReminder)
+            return { instruction, includedReminder: false };
+        // Do not clear this before the provider has completed a turn. A failed or
+        // disconnected dispatch is not evidence that Codex received the reminder.
+        return { instruction: `${this.qaContractReminder}\n\nContinue the assigned ticket now.\n\n${instruction}`, includedReminder: true };
+    }
     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,
@@ -93,20 +157,32 @@ export class CodexAdapter {
             args.push("-m", this.opts.model);
         if (this.opts.effort)
             args.push("-c", `model_reasoning_effort=${this.opts.effort}`);
-        else if (this.opts.fast)
-            args.push("-c", "model_reasoning_effort=low");
         if (this._sessionId)
             args.push("resume", this._sessionId);
         args.push(instruction);
         return args;
     }
     async sendTurn(instruction, policy) {
+        const prepared = this.instructionWithPendingQaReminder(instruction);
+        instruction = prepared.instruction;
         const turnId = randomUUID();
         this.activeProviderTurnId = turnId;
         const observer = this.opts.observer;
         if (!observer) {
             try {
-                return await withActivityPhase(`Codex ${activityPhase(this.opts.runtimePhase)}`, () => this.sendTurnInternal(instruction, policy));
+                const result = await withActivityPhase(`Codex ${activityPhase(this.opts.runtimePhase)}`, () => this.sendTurnInternal(instruction, policy));
+                if (prepared.includedReminder && !result.isError && !result.failure) {
+                    this.qaContractReminderPending = false;
+                    this.qaReminderEvent("reminder-delivered");
+                }
+                else if (prepared.includedReminder)
+                    this.qaReminderEvent("reminder-retained");
+                return result;
+            }
+            catch (error) {
+                if (prepared.includedReminder)
+                    this.qaReminderEvent("reminder-retained");
+                throw error;
             }
             finally {
                 this.activeProviderTurnId = undefined;
@@ -120,9 +196,17 @@ export class CodexAdapter {
         try {
             const result = await withActivityPhase(`Codex ${activityPhase(this.opts.runtimePhase)}`, () => this.sendTurnInternal(instruction, policy));
             observer.store.finishSpan(spanId, { outcome: result.isError ? "failed" : "completed", attributes: { usage: result.usage } });
+            if (prepared.includedReminder && !result.isError && !result.failure) {
+                this.qaContractReminderPending = false;
+                this.qaReminderEvent("reminder-delivered");
+            }
+            else if (prepared.includedReminder)
+                this.qaReminderEvent("reminder-retained");
             return result;
         }
         catch (error) {
+            if (prepared.includedReminder)
+                this.qaReminderEvent("reminder-retained");
             observer.store.finishSpan(spanId, { outcome: "failed", attributes: { error: String(error).slice(0, 500) } });
             throw error;
         }
@@ -144,23 +228,38 @@ export class CodexAdapter {
         const providerInstruction = this.buildInstruction(instruction);
         try {
             await this.ensureThread();
+            if (this.opts.fast)
+                await this.prepareFastMode();
             const toolsBefore = this.observedToolCalls;
+            this.turnSawTool = false;
             this.activeText = [];
             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(() => { });
             turnStartDispatched = true;
-            const started = await this.request("turn/start", {
+            const startParams = {
                 threadId: this._sessionId,
                 input: [{ type: "text", text: providerInstruction, text_elements: [] }],
                 cwd: this.opts.cwd,
-                model: this.opts.model ?? null,
-                effort: this.opts.effort ?? (this.opts.fast ? "low" : null),
+                model: this.opts.model ?? this.effectiveModel ?? null,
+                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 }
                     : { type: "workspaceWrite", writableRoots: [this.opts.cwd], networkAccess: this.effectiveNetworkAccess() },
-            });
+            };
+            let started;
+            try {
+                started = await this.request("turn/start", startParams);
+            }
+            catch (error) {
+                if (!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;
@@ -168,6 +267,10 @@ export class CodexAdapter {
             const failed = turn?.status === "failed" || responseOnlyViolation;
             const error = turn?.error;
             const text = this.activeText.join("\n");
+            if (failed && !responseOnlyViolation && this.fastTier && !this.turnSawTool && !text && isFastModeUnavailable(String(error?.message ?? ""))) {
+                this.disableFastMode();
+                return this.sendTurnInternal(instruction, policy);
+            }
             const 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,
@@ -381,6 +484,8 @@ export class CodexAdapter {
     }
     async sessionUsage() { return this.providerSessionUsage ? { ...this.providerSessionUsage } : undefined; }
     async switchSettings(settings) {
+        if (settings.model !== this.opts.model || settings.fast !== this.opts.fast)
+            this.fastPreparedModel = undefined;
         this.opts.model = settings.model;
         this.opts.effort = settings.effort;
         this.opts.fast = settings.fast;
@@ -417,7 +522,8 @@ export class CodexAdapter {
     }
     observeEvents(listener) { return this.eventQueue.observe(listener); }
     events() { return this.eventQueue; }
-    async close() {
+    close() { return this.closePromise ??= this.closeInternal(); }
+    async closeInternal() {
         if (this.closed)
             return;
         this.closed = true;
@@ -475,7 +581,7 @@ export class CodexAdapter {
                 model: this.opts.model ?? null, approvalPolicy: this.effectiveApprovalPolicy(),
                 config: { sandbox_workspace_write: { network_access: this.effectiveNetworkAccess() } },
                 sandbox: this.opts.sandboxMode === "read-only" || this.opts.sessionRole === "qa" ? "read-only" : "workspace-write",
-                developerInstructions: this.opts.systemPromptAppend ?? null,
+                developerInstructions: handoffSystemInstructions(this.opts.sessionRole, this.opts.systemPromptAppend) ?? null,
             });
         }
         catch (error) {
@@ -546,6 +652,7 @@ export class CodexAdapter {
         }
         this.sessionAvailability = { version: 1, status: "available", checkedAt: new Date().toISOString(), observedCwd: providerCwd ?? canonicalSessionPath(this.opts.cwd), sessionRef: this._sessionRef };
         this.threadAttached = true;
+        this.effectiveModel = typeof result.model === "string" ? result.model : this.opts.model;
         this.eventQueue.push({ kind: "session-transition", transition: method === "thread/resume" ? "resumed" : "started" });
     }
     threadAttached = false;
@@ -614,6 +721,7 @@ export class CodexAdapter {
             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() });
             if (isCodexToolItem(item)) {
+                this.turnSawTool = true;
                 this.observedToolCalls += 1;
                 const callId = codexItemId(item) ?? randomUUID();
                 const name = codexToolName(item);
@@ -633,6 +741,7 @@ export class CodexAdapter {
             if (item)
                 this.eventQueue.push({ kind: "provider-item", provider: "codex", lifecycle: "completed", itemType: String(item.type ?? "unknown"), payload: exactProviderItem(item), payloadCompleteness: "complete", providerTurnId: this.activeProviderTurnId, eventId: randomUUID(), observedAt: new Date().toISOString() });
             if (isCodexToolItem(item)) {
+                this.turnSawTool = true;
                 const callId = codexItemId(item);
                 const spanId = callId ? this.toolSpans.get(callId) : undefined;
                 const status = typeof item?.status === "string" ? item.status : undefined;
@@ -663,6 +772,13 @@ export class CodexAdapter {
                     provider: "codex",
                     usageRevision: this.usageRevision,
                 });
+                // A native compaction does not invalidate completed work or QA handoff.
+                // The next Rafi-controlled turn re-supplies the full requirement
+                // contract and tells the Builder to check it before continuing.
+                if (this.qaContractReminder) {
+                    this.qaContractReminderPending = true;
+                    this.qaReminderEvent("compaction-observed");
+                }
                 this.eventQueue.push({ kind: "session-transition", transition: "compacted", detail: "provider-native automatic compaction" });
             }
             else {
@@ -710,6 +826,8 @@ export class CodexAdapter {
         else if (message.method === "error") {
             const error = params.error;
             const reason = String(error?.message ?? params.message ?? "Codex app-server error");
+            if (this.fastTier && isFastModeUnavailable(reason) && !this.activeText.length && !this.turnSawTool)
+                return;
             if (params.willRetry === true) {
                 const retryId = randomUUID();
                 this.eventQueue.push(this.opts.observer

package/dist/adapters/fastMode.d.ts

@@ -0,0 +1,4 @@
+/** Only explicit speed-option rejection permits a same-session retry. Auth,
+ * generic model failures, timeouts, and uncertain transport failures do not. */
+export declare function isFastModeUnavailable(detail: string): boolean;
+export declare function reportFastModeUnavailable(model?: string): void;

package/dist/adapters/fastMode.js

@@ -0,0 +1,9 @@
+/** Only explicit speed-option rejection permits a same-session retry. Auth,
+ * generic model failures, timeouts, and uncertain transport failures do not. */
+export function isFastModeUnavailable(detail) {
+    return /(?:fast(?:[ _-]mode)?|service[ _-]tier|speed\s*[=:]\s*["']?fast)[\s\S]{0,160}(?:not supported|unsupported|not available|unavailable|not enabled|disabled|not allowed|requires|invalid|unrecognized|unknown)|(?:not supported|unsupported|not available|unavailable|invalid|unrecognized|unknown)[\s\S]{0,100}(?:--fast|fast[ _-]mode|service[ _-]tier)/i.test(detail);
+}
+export function reportFastModeUnavailable(model) {
+    const label = (model ?? "the selected model").replace(/[\x00-\x1f\x7f-\x9f]/g, "").slice(0, 200);
+    console.error(`rafi: Fast mode not available with ${label}; continuing at standard speed.`);
+}

package/dist/adapters/recovering.d.ts

@@ -24,6 +24,9 @@ export declare class RecoveringAdapter implements BuilderAdapter {
     private eventPump;
     private closed;
     private contractEnforcing;
+    /** Reapply a Codex post-compaction reminder if recovery recreates its adapter. */
+    private qaContractReminder?;
+    private qaContractReminderEvent?;
     constructor(opts: RecoveringAdapterOptions);
     graphRuntimeSettings(): Pick<import("./types.js").BuilderAdapterOptions, "model" | "effort" | "fast" | "runtimeExecutable"> | undefined;
     get agent(): "claude" | "codex";
@@ -34,6 +37,7 @@ export declare class RecoveringAdapter implements BuilderAdapter {
     enableContractEnforcement(): void;
     contractCompactionSequence(): number;
     acceptContractDelivery(sequence: number): void;
+    configureQaContractReminder(reminder: string, onEvent?: Parameters<NonNullable<BuilderAdapter["configureQaContractReminder"]>>[1]): void;
     sendTurn(text: string, policy?: Parameters<BuilderAdapter["sendTurn"]>[1]): Promise<TurnResult>;
     sessionId(): string | undefined;
     sessionRef(): ProviderSessionRefV1 | undefined;

package/dist/adapters/recovering.js

@@ -11,6 +11,9 @@ export class RecoveringAdapter {
     eventPump;
     closed = false;
     contractEnforcing = false;
+    /** Reapply a Codex post-compaction reminder if recovery recreates its adapter. */
+    qaContractReminder;
+    qaContractReminderEvent;
     constructor(opts) {
         this.opts = opts;
         this.adapter = opts.initial;
@@ -25,6 +28,11 @@ export class RecoveringAdapter {
     enableContractEnforcement() { this.contractEnforcing = true; this.adapter.enableContractEnforcement?.(); }
     contractCompactionSequence() { return this.adapter.contractCompactionSequence?.() ?? 0; }
     acceptContractDelivery(sequence) { this.adapter.acceptContractDelivery?.(sequence); }
+    configureQaContractReminder(reminder, onEvent) {
+        this.qaContractReminder = reminder;
+        this.qaContractReminderEvent = onEvent;
+        this.adapter.configureQaContractReminder?.(reminder, onEvent);
+    }
     async sendTurn(text, policy) {
         while (true) {
             const result = await this.adapter.sendTurn(text, policy);
@@ -123,6 +131,8 @@ export class RecoveringAdapter {
         await this.adapter.close().catch(() => { });
         await this.eventPump.catch(() => { });
         this.adapter = await this.opts.recreate(runtime, resumeSessionId, resumeSessionRef);
+        if (this.qaContractReminder)
+            this.adapter.configureQaContractReminder?.(this.qaContractReminder, this.qaContractReminderEvent);
         this.runtime = runtime;
         this.opts.onRuntimeChange?.(runtime);
         this.eventPump = this.forwardEvents(this.adapter);

package/dist/adapters/sessionFailure.d.ts

@@ -16,3 +16,9 @@ export declare class SessionUnavailableError extends Error {
 export declare function sessionUnavailableResult(error: SessionUnavailableError): TurnResult;
 export declare function isSessionUnavailableFailure(value: unknown): boolean;
 export declare function sessionUnavailableErrorFromFailure(failure: RuntimeFailure): SessionUnavailableError;
+/**
+ * A Builder turn whose dispatch outcome is unknown must enter durable source
+ * recovery. It is not an ordinary ticket blocker: the provider may have
+ * applied part of the requested change before its stream failed.
+ */
+export declare function recoverableBuilderTurnError(result: TurnResult): SessionUnavailableError | undefined;

package/dist/adapters/sessionFailure.js

@@ -49,3 +49,22 @@ export function sessionUnavailableErrorFromFailure(failure) {
         availability: failure.availability,
     });
 }
+/**
+ * A Builder turn whose dispatch outcome is unknown must enter durable source
+ * recovery. It is not an ordinary ticket blocker: the provider may have
+ * applied part of the requested change before its stream failed.
+ */
+export function recoverableBuilderTurnError(result) {
+    const failure = result.failure;
+    if (!failure || failure.dispatchState !== "unknown")
+        return undefined;
+    return new SessionUnavailableError({
+        runtime: failure.runtime,
+        phase: failure.phase === "preflight" || failure.phase === "attach" || failure.phase === "turn" ? failure.phase : "turn",
+        dispatchState: "unknown",
+        executable: failure.executable,
+        cwd: failure.cwd,
+        diagnostics: result.text || failure.diagnostics,
+        availability: failure.availability,
+    });
+}

package/dist/adapters/types.d.ts

@@ -6,6 +6,8 @@ import type { ConfigurableAgentRole, ProviderSessionRefV1, RuntimeProbeCategory,
 import type { RunObserver } from "../observability.js";
 /** A permission request surfaced by a builder before it runs a tool. */
 export interface PermissionRequest {
+    /** Provider-observed tool cwd, distinct from immutable session launch scope. */
+    executionCwd?: string;
     toolName: string;
     input: Record<string, unknown>;
     /** Human-readable prompt from the agent, when available. */
@@ -297,6 +299,12 @@ export interface BuilderAdapter {
     enableContractEnforcement?(): void;
     contractCompactionSequence?(): number;
     acceptContractDelivery?(sequence: number): void;
+    /** Codex re-sends this exact contract reminder on its first host turn after native compaction. */
+    configureQaContractReminder?(reminder: string, onEvent?: (event: {
+        kind: "installed" | "compaction-observed" | "reminder-delivered" | "reminder-retained";
+        at: string;
+        sessionId?: string;
+    }) => void): void;
     /** Send one instruction; resolves when that turn completes. */
     sendTurn(text: string, policy?: {
         handback?: boolean;

package/dist/agentRun.js

@@ -54,6 +54,7 @@ export function readOnlyPermissionConfig() {
             "npm run typecheck",
             "npm run lint",
             "npm run check",
+            "node --test",
             "pnpm test",
             "pnpm run test",
             "pnpm typecheck",

package/dist/branch/currentGuard.d.ts

@@ -21,6 +21,14 @@ export declare class CurrentWorkflowGuardAdapter implements BuilderAdapter {
     readonly agent: BuilderAdapter["agent"];
     constructor(adapter: BuilderAdapter, cwd: string, expected?: CurrentWorkflowIdentity);
     sendTurn(text: string, policy?: Parameters<BuilderAdapter["sendTurn"]>[1]): Promise<TurnResult>;
+    contractCapabilities(): {
+        sameSessionAcceptance: boolean;
+        nativeCompactionBarrier: boolean;
+    };
+    enableContractEnforcement(): void;
+    contractCompactionSequence(): number;
+    acceptContractDelivery(sequence: number): void;
+    configureQaContractReminder(reminder: string, onEvent?: Parameters<NonNullable<BuilderAdapter["configureQaContractReminder"]>>[1]): void;
     sessionId(): string | undefined;
     sessionRef(): ProviderSessionRefV1 | undefined;
     prepareSession(): Promise<ProviderSessionRefV1>;

package/dist/branch/currentGuard.js

@@ -43,6 +43,11 @@ export class CurrentWorkflowGuardAdapter {
         assertCurrentWorkflowIdentity(this.cwd, this.expected);
         return result;
     }
+    contractCapabilities() { return this.adapter.contractCapabilities?.() ?? { sameSessionAcceptance: false, nativeCompactionBarrier: false }; }
+    enableContractEnforcement() { this.adapter.enableContractEnforcement?.(); }
+    contractCompactionSequence() { return this.adapter.contractCompactionSequence?.() ?? 0; }
+    acceptContractDelivery(sequence) { this.adapter.acceptContractDelivery?.(sequence); }
+    configureQaContractReminder(reminder, onEvent) { this.adapter.configureQaContractReminder?.(reminder, onEvent); }
     sessionId() { return this.adapter.sessionId(); }
     sessionRef() { return this.adapter.sessionRef?.(); }
     async prepareSession() {

package/dist/branch/runner.js

@@ -22,7 +22,7 @@ import { join, resolve } from "node:path";
 import { WorkflowDb } from "../workflowDb.js";
 import { assertBuildAssignmentReconciled, BuildAssignmentRejected } from "../buildAssignment.js";
 import { currentActivity, withActivityPhase } from "../activity.js";
-import { SessionUnavailableError } from "../adapters/sessionFailure.js";
+import { SessionUnavailableError, recoverableBuilderTurnError } from "../adapters/sessionFailure.js";
 import { SessionUnavailableContinuityError } from "../continuity.js";
 export function readDeliveryUnitSession(projectDir, unitId) {
     const path = deliverySessionPath(projectDir, unitId);
@@ -304,7 +304,7 @@ export async function runBranchPlan(opts) {
             base: node.baseBranch,
             dependencies: node.dependencies,
         });
-        workflowCheckpoint(opts.projectDir, opts.runId, "builder-before", node.ticket.id, { branch: node.branch, worktree: node.worktreePath });
+        workflowCheckpoint(opts.projectDir, opts.runId, qaOnlyRecovery ? "qa-recovery-before" : "builder-before", node.ticket.id, { branch: node.branch, worktree: node.worktreePath });
         const continuationDb = new WorkflowDb(opts.projectDir);
         const continuationSession = continuations.length ? continuationDb.branchResumeSession(opts.runId, node.ticket.id) : undefined;
         continuationDb.close();
@@ -391,50 +391,52 @@ export async function runBranchPlan(opts) {
                     ? await opts.observer.withContext({ role: "builder", stream: "builder", ticketId: node.ticket.id, deliveryUnitId: node.deliveryUnitId }, turn)
                     : await turn();
             builder = foreman.builderAdapter();
-            workflowCheckpoint(opts.projectDir, opts.runId, "builder-after", node.ticket.id, { status: status.kind, sessionId: builder.sessionId(), worktree: worktreePath });
-            const sessionId = builder.sessionId();
-            const sessionRef = builder.sessionRef?.();
-            if (sessionId)
-                builderStream = { sessionId, ...(sessionRef ? { sessionRef } : {}), worktreePath };
-            if (sessionId) {
-                opts.recordBuilderSession?.(sessionRef ?? sessionId, node.ticket.id, worktreePath);
-                workflowCheckpoint(opts.projectDir, opts.runId, "builder-session-scoped", node.ticket.id, { sessionId, sessionRef, worktree: worktreePath, branch: node.branch });
-            }
-            if (sessionId) {
-                const resumeSession = {
-                    ticket: node.ticket.id,
-                    branch: node.branch,
-                    base: node.baseBranch,
-                    worktreePath,
-                    sessionId,
-                    sessionRef: builder.sessionRef?.(),
-                    agent: opts.agent,
-                    model: opts.model,
-                    effort: opts.effort,
-                    fast: opts.fast,
-                    qaEnabled: opts.qaEnabled,
-                    createPr: createsReview,
-                    completionMode,
-                    reviewProvider,
-                    prReady: opts.prReady,
-                    keepWorktrees: opts.keepWorktrees,
-                    deliveryUnitId: node.deliveryUnitId,
-                    deliveryUnitFinal: node.deliveryUnitFinal,
-                    logPath: "structured-recovery",
-                    ts: new Date().toISOString(),
-                };
-                opts.log.write("branch-session", resumeSession);
-                const resumeDb = new WorkflowDb(opts.projectDir);
-                try {
-                    resumeDb.recordBranchResumeSession(opts.runId, resumeSession);
-                }
-                finally {
-                    resumeDb.close();
+            if (!qaOnlyRecovery) {
+                workflowCheckpoint(opts.projectDir, opts.runId, "builder-after", node.ticket.id, { status: status.kind, sessionId: builder.sessionId(), worktree: worktreePath });
+                const sessionId = builder.sessionId();
+                const sessionRef = builder.sessionRef?.();
+                if (sessionId)
+                    builderStream = { sessionId, ...(sessionRef ? { sessionRef } : {}), worktreePath };
+                if (sessionId) {
+                    opts.recordBuilderSession?.(sessionRef ?? sessionId, node.ticket.id, worktreePath);
+                    workflowCheckpoint(opts.projectDir, opts.runId, "builder-session-scoped", node.ticket.id, { sessionId, sessionRef, worktree: worktreePath, branch: node.branch });
                 }
-                if (node.deliveryUnitId) {
-                    const path = deliverySessionPath(opts.projectDir, node.deliveryUnitId);
-                    mkdirSync(join(opts.projectDir, ".foreman", "delivery-sessions"), { recursive: true });
-                    writeFileSync(path, `${JSON.stringify({ runId: opts.runId, unitId: node.deliveryUnitId, branch: node.branch, worktreePath, sessionId, sessionRef: builder.sessionRef?.(), ticket: node.ticket.id }, null, 2)}\n`, "utf8");
+                if (sessionId) {
+                    const resumeSession = {
+                        ticket: node.ticket.id,
+                        branch: node.branch,
+                        base: node.baseBranch,
+                        worktreePath,
+                        sessionId,
+                        sessionRef: builder.sessionRef?.(),
+                        agent: opts.agent,
+                        model: opts.model,
+                        effort: opts.effort,
+                        fast: opts.fast,
+                        qaEnabled: opts.qaEnabled,
+                        createPr: createsReview,
+                        completionMode,
+                        reviewProvider,
+                        prReady: opts.prReady,
+                        keepWorktrees: opts.keepWorktrees,
+                        deliveryUnitId: node.deliveryUnitId,
+                        deliveryUnitFinal: node.deliveryUnitFinal,
+                        logPath: "structured-recovery",
+                        ts: new Date().toISOString(),
+                    };
+                    opts.log.write("branch-session", resumeSession);
+                    const resumeDb = new WorkflowDb(opts.projectDir);
+                    try {
+                        resumeDb.recordBranchResumeSession(opts.runId, resumeSession);
+                    }
+                    finally {
+                        resumeDb.close();
+                    }
+                    if (node.deliveryUnitId) {
+                        const path = deliverySessionPath(opts.projectDir, node.deliveryUnitId);
+                        mkdirSync(join(opts.projectDir, ".foreman", "delivery-sessions"), { recursive: true });
+                        writeFileSync(path, `${JSON.stringify({ runId: opts.runId, unitId: node.deliveryUnitId, branch: node.branch, worktreePath, sessionId, sessionRef: builder.sessionRef?.(), ticket: node.ticket.id }, null, 2)}\n`, "utf8");
+                    }
                 }
             }
             opts.log.write("step", {
@@ -446,8 +448,12 @@ export async function runBranchPlan(opts) {
                 costUsd: result.costUsd,
                 isError: result.isError,
             });
-            if (result.isError)
+            if (result.isError) {
+                const recoverable = recoverableBuilderTurnError(result);
+                if (recoverable)
+                    throw recoverable;
                 throw new Error(`builder turn errored: ${result.text.slice(0, 200)}`);
+            }
             if (status.branchDependency) {
                 throw new Error(`builder requested branch_dependency=${status.branchDependency}; retry is not available after ticket start in this run`);
             }

package/dist/buildApproval.js

@@ -14,7 +14,7 @@ function canonical(value) {
 }
 function material(ticket) {
     return { id: ticket.id, plan_ref: ticket.plan_ref, title: ticket.title, summary: ticket.summary, acceptance: ticket.acceptance,
-        required_tests: ticket.required_tests, depends_on: ticket.depends_on, likely_files: ticket.likely_files, rollback: ticket.rollback, source_refs: ticket.source_refs };
+        required_tests: ticket.required_tests, depends_on: ticket.depends_on, likely_files: ticket.likely_files, rollback: ticket.rollback, documentation: ticket.documentation ?? { required: false, targets: [], criteria: [] }, source_refs: ticket.source_refs };
 }
 /** Reuse only source-bound approval. Ambiguous legacy provenance still asks. */
 export function approvedBuildScope(projectDir, ticketIds) {
@@ -52,6 +52,7 @@ export function approvedBuildScope(projectDir, ticketIds) {
                 const ids = new Map(all.filter(item => item.plan_ref?.plan_id === ref.plan_id && item.plan_ref.revision === ref.revision).map(item => [item.plan_ref.slice_ref, item.id]));
                 const legacy = slice && !ticket.rollback ? { ...ticket, title: slice.title, summary: slice.summary,
                     acceptance: slice.acceptance, required_tests: slice.required_tests, likely_files: slice.likely_files,
+                    documentation: slice.documentation ?? { required: false, targets: [], criteria: [] },
                     depends_on: (slice.depends_on ?? []).map((id) => ids.get(id)),
                     source_refs: slice.source_refs?.map((source) => ({ source: source.source_id, item: source.item ?? "document", source_id: source.source_id, fingerprint: source.fingerprint, ...(source.url !== undefined ? { url: source.url } : {}), ...(source.note !== undefined ? { note: source.note } : {}) })) } : undefined;
                 if (canonical(material(approved ?? legacy ?? {})) !== canonical(material(ticket)))

package/dist/buildAssignment.d.ts

@@ -22,6 +22,21 @@ export declare class BuildAssignmentRejected extends Error {
 }
 /** A frozen exact-session Builder decision may defer unrelated pending QA. */
 export declare function isInterruptedBuilderRecovery(run: BuildRunRecordV2 | undefined): boolean;
+/** Recovery requires current source, assignment and admission proofs.
+ * A V3 or migrated record alone never grants continuation authority;
+ * full eligibility is verified before any unknown receipt is reconciled. */
+export declare function canReconcileInterruptedBuilderSource(projectDir: string, runId: string): boolean;
+/** Resume the existing approved build from observed local source, never replay
+ * the interrupted instruction or pretend its unknown outcome was successful.
+ * The caller must own recovery admission and the original run's workflow lease. */
+export declare function prepareInterruptedBuilderSourceContinuation(projectDir: string, runId: string): {
+    ticketIds: string[];
+    reconciliationId: string;
+    sourceDigest: string;
+    contentDigest: string;
+};
+/** A launch may not consume a recovery snapshot after product source changes. */
+export declare function assertInterruptedSourceSnapshot(projectDir: string, run: BuildRunRecordV2): void;
 /**
  * Retire only the host-side records for a Builder turn that was interrupted
  * before Rafi received a durable response.  The next turn is sent to the