ai-foreman 1.7.11 → 1.7.13

package/dist/foreman.js

@@ -1,12 +1,14 @@
-import { select, isCancel } from "@clack/prompts";
+import { select, text, isCancel } from "@clack/prompts";
 import { MARKER_SPEC, QA_MARKER_SPEC } from "./markers.js";
 import { countProviderQuestions, handleProviderQuestionTool } from "./providerQuestions.js";
-import { fireNotification } from "./notify.js";
+import { signalAttention } from "./notify.js";
+import { pauseActivityForInput } from "./activity.js";
 import { isTicketsInitialized, loadTicketsConfig } from "./tickets/config.js";
-import { cmdUpdate, cmdComplete, cmdBlock, cmdImplementationQueue } from "./tickets/commands.js";
+import { cmdUpdate, cmdComplete, cmdBlock, cmdUnblock, cmdImplementationQueue } from "./tickets/commands.js";
 import { loadTickets } from "./tickets/ticketLoader.js";
-import { runIsolatedQa } from "./qaReview.js";
-import { createHash } from "node:crypto";
+import { buildDurableQaFixHandoff, runIsolatedQa } from "./qaReview.js";
+import { changeManifestAsync, deterministicChangeSummaryAsync } from "./qaSnapshot.js";
+import { createHash, randomUUID } from "node:crypto";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
 import { SessionUnavailableError, sessionUnavailableErrorFromFailure } from "./adapters/sessionFailure.js";
@@ -25,7 +27,8 @@ const QUESTION_HINTS = [
  * Format: `STEP_STATUS: <kind> | key="value" key="value"`.
  */
 export function parseStepStatus(text) {
-    const markerCount = (text.match(/STEP_STATUS:/g) ?? []).length;
+    const markerLines = text.split(/\r?\n/).filter((line) => /^\s*STEP_STATUS:/.test(line));
+    const markerCount = markerLines.length;
     if (markerCount > 1) {
         return { kind: "unknown", error: "builder emitted multiple STEP_STATUS markers" };
     }
@@ -151,7 +154,7 @@ export function buildQaInstruction() {
 Triple-check. Do not rubber-stamp your own work. Be skeptical.
 
 If everything is solid, end with STEP_STATUS: qa_pass.
-If anything is off, end with STEP_STATUS: qa_fail and list every concrete issue in the issues="..." field. Do NOT fix issues on this turn — just report them. Foreman will instruct you to fix them next.
+If anything is off, return the required RAFI_QA_FAILURE_REPORT_START/RAFI_QA_FAILURE_REPORT_END JSON envelope immediately before STEP_STATUS: qa_fail. The report must contain every check, every blocking finding, and all nonblocking observations. Do NOT fix issues on this turn — just report them. Foreman will instruct the Builder to fix them next.
 
 ${QA_MARKER_SPEC}`;
 }
@@ -216,11 +219,9 @@ export function createPermissionHandler(policy, log, opts = {}) {
 export class Foreman {
     builder;
     log;
-    notificationsEnabled;
     qaEnabled;
     qaMaxCycles;
     projectDir;
-    qaReviewer;
     qaFactory;
     qaSessionStrategy;
     builderFactory;
@@ -231,19 +232,27 @@ export class Foreman {
     qaSessionBoundary;
     observeQaNativeCompactions;
     observeBuilderNativeCompactions;
+    observer;
+    qaRuntimeContext;
+    qaContinuityManaged;
+    qaReportRecovery;
+    qaResumedRecovery;
     ticketsEnabled;
+    notificationsEnabled;
+    terminalBellEnabled;
     qaStream = { reviews: 0, modificationViolations: 0 };
     builderWorkSessions = 0;
-    constructor(builder, log, notificationsEnabled = false, qaEnabled = true, qaMaxCycles = 3, projectDir, qaReviewer, qaFactory, qaSessionStrategy = "compact", builderFactory, builderSessionStrategy = "compact", qaNonconvergence, beforeBuilderTurn, builderSessionBoundary, qaSessionBoundary, observeQaNativeCompactions, 
+    fallbackQaRunId = `qa-${randomUUID()}`;
+    constructor(builder, log, notifications = false, qaEnabled = true, qaMaxCycles = 3, projectDir, 
+    /** @deprecated QA must be created by qaFactory in a disposable snapshot. */
+    _deprecatedSameSessionReviewer, qaFactory, qaSessionStrategy = "compact", builderFactory, builderSessionStrategy = "compact", qaNonconvergence, beforeBuilderTurn, builderSessionBoundary, qaSessionBoundary, observeQaNativeCompactions, 
     /** Persist a Builder's provider-native event immediately after every turn. */
-    observeBuilderNativeCompactions) {
+    observeBuilderNativeCompactions, observer, qaRuntimeContext, qaContinuityManaged = false, qaReportRecovery, qaResumedRecovery) {
         this.builder = builder;
         this.log = log;
-        this.notificationsEnabled = notificationsEnabled;
         this.qaEnabled = qaEnabled;
         this.qaMaxCycles = qaMaxCycles;
         this.projectDir = projectDir;
-        this.qaReviewer = qaReviewer;
         this.qaFactory = qaFactory;
         this.qaSessionStrategy = qaSessionStrategy;
         this.builderFactory = builderFactory;
@@ -254,8 +263,33 @@ export class Foreman {
         this.qaSessionBoundary = qaSessionBoundary;
         this.observeQaNativeCompactions = observeQaNativeCompactions;
         this.observeBuilderNativeCompactions = observeBuilderNativeCompactions;
+        this.observer = observer;
+        this.qaRuntimeContext = qaRuntimeContext;
+        this.qaContinuityManaged = qaContinuityManaged;
+        this.qaReportRecovery = qaReportRecovery;
+        this.qaResumedRecovery = qaResumedRecovery;
+        void _deprecatedSameSessionReviewer;
+        this.notificationsEnabled = typeof notifications === "boolean" ? notifications : notifications.desktop;
+        this.terminalBellEnabled = typeof notifications === "boolean" ? true : notifications.terminalBell;
         this.ticketsEnabled = !!(projectDir && isTicketsInitialized(projectDir));
     }
+    async waitForUserInput(operation) {
+        const paused = () => pauseActivityForInput(operation);
+        if (!this.observer)
+            return paused();
+        return this.observer.withContext({ role: "builder", stream: "user-input" }, async () => {
+            const spanId = this.observer.store.startSpan(this.observer.context(), { kind: "user_wait", name: "Builder input prompt" });
+            try {
+                const value = await paused();
+                this.observer.store.finishSpan(spanId, { outcome: value === undefined ? "paused" : "answered" });
+                return value;
+            }
+            catch (error) {
+                this.observer.store.finishSpan(spanId, { outcome: "error" });
+                throw error;
+            }
+        });
+    }
     /**
      * Send one instruction and resolve any needs_input exchanges before returning.
      * The returned result and status always reflect the final (non-needs_input) turn.
@@ -309,7 +343,7 @@ export class Foreman {
         this.builder = await this.builderFactory(this.projectDir);
         this.log.write("branch-session", { role: "builder", transition: "missing-session-fresh", continuityLost: true });
     }
-    async doTurnWith(adapter, instruction) {
+    async doTurnWith(adapter, instruction, mode = "builder") {
         if (adapter === this.builder && this.beforeBuilderTurn) {
             this.builder = await this.beforeBuilderTurn(this.builder, instruction);
             adapter = this.builder;
@@ -324,12 +358,11 @@ export class Foreman {
                 status = { kind: "needs_input", question: lastLine(result.text), choices: ["Continue", "Cancel"] };
             }
             else {
-                const qa = /\bQA\b|qa_pass|qa_fail/i.test(instruction);
                 if (adapter === this.builder && this.beforeBuilderTurn) {
                     this.builder = await this.beforeBuilderTurn(this.builder, instruction);
                     adapter = this.builder;
                 }
-                result = await adapter.sendTurn(qa
+                result = await adapter.sendTurn(mode === "qa"
                     ? "Protocol correction only: based on the review already completed, return exactly one final STEP_STATUS: qa_pass or STEP_STATUS: qa_fail marker. Do not repeat QA, tests, tools, or compaction."
                     : "Protocol correction only: based on the work already completed, return exactly one final STEP_STATUS: done, plan_complete, blocked, or needs_input marker. Do not repeat implementation, tools, or compaction.");
                 await this.observeBuilderNative(adapter);
@@ -338,33 +371,67 @@ export class Foreman {
                     status = { ...status, error: `protocol correction exhausted: ${status.error ?? "missing final marker"}` };
             }
         }
-        while (status.kind === "needs_input") {
-            const question = status.question ?? "The builder has a question";
-            const choices = status.choices?.length
-                ? status.choices
-                : ["Continue", "Cancel"];
-            this.log.write("needs_input", { question, choices });
-            if (this.notificationsEnabled) {
-                fireNotification("Foreman needs your input", question);
+        while (true) {
+            while (status.kind === "needs_input") {
+                const question = status.question ?? "The builder has a question";
+                const choices = status.choices?.length ? status.choices : ["Continue"];
+                this.log.write("needs_input", { question, choices });
+                signalAttention("Foreman needs your input", question, this.notificationsEnabled, this.terminalBellEnabled);
+                if (!process.stdin.isTTY || !process.stdout.isTTY) {
+                    console.error(`foreman: input required: ${question}`);
+                    console.error("foreman: resume this run in an interactive terminal, or provide explicit guidance through the printed resume command");
+                    result = { text: result.text, isError: false, numTurns: result.numTurns, costUsd: result.costUsd };
+                    status = { kind: "blocked", reason: `input required in an interactive terminal: ${question}` };
+                    break;
+                }
+                const answer = await this.waitForUserInput(async () => {
+                    console.log();
+                    const selected = await select({
+                        message: question,
+                        options: [
+                            ...choices.map((choice) => ({ value: choice, label: choice })),
+                            { value: "__rafi_custom__", label: "Custom response", hint: "Type a different answer" },
+                            { value: "__rafi_pause__", label: "Pause safely", hint: "Keep the run recoverable and return to the terminal" },
+                        ],
+                    });
+                    if (isCancel(selected) || selected === "__rafi_pause__")
+                        return undefined;
+                    if (selected !== "__rafi_custom__")
+                        return selected;
+                    const custom = await text({ message: "Custom response:", validate: (value) => String(value ?? "").trim() ? undefined : "Enter a response" });
+                    return isCancel(custom) ? undefined : String(custom);
+                });
+                console.log();
+                if (answer === undefined) {
+                    result = { text: "", isError: false, numTurns: 0, costUsd: 0 };
+                    status = { kind: "blocked", reason: "user chose safe pause at an input prompt" };
+                    break;
+                }
+                if (adapter === this.builder && this.beforeBuilderTurn) {
+                    this.builder = await this.beforeBuilderTurn(this.builder, answer);
+                    adapter = this.builder;
+                }
+                result = await adapter.sendTurn(answer);
+                await this.observeBuilderNative(adapter);
+                status = parseStepStatus(result.text);
             }
-            console.log();
-            const answer = await select({
-                message: question,
-                options: choices.map((c) => ({ value: c, label: c })),
-            });
-            console.log();
-            if (isCancel(answer)) {
-                result = { text: "", isError: false, numTurns: 0, costUsd: 0 };
-                status = { kind: "blocked", reason: "user cancelled at input prompt" };
+            if (status.kind !== "blocked" || status.reason?.startsWith("user chose safe pause") || !process.stdin.isTTY || !process.stdout.isTTY)
                 break;
-            }
+            const reason = status.reason ?? "the agent reported an unspecified blocker";
+            this.log.write("blocked-recovery", { reason, role: adapter === this.builder ? "builder" : "qa" });
+            const recoveryInstruction = buildBlockerRecoveryInstruction(reason);
             if (adapter === this.builder && this.beforeBuilderTurn) {
-                this.builder = await this.beforeBuilderTurn(this.builder, String(answer));
+                this.builder = await this.beforeBuilderTurn(this.builder, recoveryInstruction);
                 adapter = this.builder;
             }
-            result = await adapter.sendTurn(String(answer));
+            result = await adapter.sendTurn(recoveryInstruction);
             await this.observeBuilderNative(adapter);
             status = parseStepStatus(result.text);
+            if (status.kind === "unknown") {
+                result = await adapter.sendTurn('Protocol correction only: return the blocker approaches now using exactly one final STEP_STATUS: needs_input marker with question="..." and choices="recommended (Recommended)|alternative|alternative". Do not repeat tools or implementation.');
+                await this.observeBuilderNative(adapter);
+                status = parseStepStatus(result.text);
+            }
         }
         return { result, status };
     }
@@ -398,6 +465,10 @@ export class Foreman {
     async runInstruction(instruction) {
         return this.doTurn(instruction);
     }
+    /** Ask an already-active role session to propose choices for its reported blocker. */
+    async resolveBlocker(adapter, reason, mode = "builder") {
+        return this.doTurnWith(adapter, buildBlockerRecoveryInstruction(reason), mode);
+    }
     async observeBuilderNative(adapter) {
         if (adapter === this.builder)
             await this.observeBuilderNativeCompactions?.(adapter);
@@ -407,100 +478,56 @@ export class Foreman {
      * Loops on qa_fail → fix → re-QA until qa_pass or the cycle cap is reached.
      * QA turns are free — they do not advance the step counter.
      */
-    async runQa(stepIndex, ticketId) {
+    async runQa(stepIndex, ticketId, builderResult) {
         if (this.projectDir && this.qaFactory) {
+            const resumedRecovery = this.qaResumedRecovery;
+            this.qaResumedRecovery = undefined;
             const review = await runIsolatedQa({
                 ticket: this.ticketForQa(stepIndex, ticketId),
                 builderWorktree: this.projectDir,
-                builderSummary: `Builder completed step ${stepIndex}`,
+                builderSummary: builderResult ?? "Builder result unavailable at this explicit QA-only API boundary",
                 qaStrategy: this.qaSessionStrategy,
                 state: this.qaStream,
                 createQa: this.qaFactory,
                 sessionBoundary: this.qaSessionBoundary,
                 observeNativeCompactions: this.observeQaNativeCompactions,
                 maxCycles: this.qaMaxCycles,
-                fix: async (issues) => {
-                    const instruction = buildQaFixInstruction(issues);
+                recovery: { projectDir: this.projectDir, runId: this.observer?.runId ?? this.fallbackQaRunId },
+                observer: this.observer,
+                qaRuntimeContext: this.qaRuntimeContext,
+                continuityManaged: this.qaContinuityManaged,
+                onReportRecovery: this.qaReportRecovery,
+                resumedRecovery,
+                fix: async (request) => {
+                    const manifest = await changeManifestAsync(this.projectDir);
+                    const changeSummary = await deterministicChangeSummaryAsync(this.projectDir);
+                    const instruction = buildDurableQaFixHandoff(this.ticketForQa(stepIndex, ticketId), request, this.projectDir, request.latestBuilderResult, manifest.diffDigest, changeSummary);
                     await this.prepareBuilderBoundary(instruction);
                     this.builderWorkSessions += 1;
                     const fix = await this.doTurn(instruction);
                     this.log.write("qa-fix", { stepIndex, statusKind: fix.status.kind, costUsd: fix.result.costUsd, isError: fix.result.isError });
                     return fix.result.isError || fix.status.kind !== "done"
                         ? { ok: false, detail: fix.status.reason ?? fix.status.error ?? fix.result.text.slice(0, 200) }
-                        : { ok: true };
+                        : { ok: true, response: fix.result.text, summary: fix.status.summary ?? fix.result.text };
                 },
                 evidence: ({ cycle, outcome, detail, qaDiff }) => this.log.write("qa", { stepIndex, cycle, outcome, detail, qaDiff, disposable: true }),
                 onNonconvergence: this.qaNonconvergence,
+                resolveBlocked: (adapter, reason) => this.resolveBlocker(adapter, reason, "qa"),
             });
             if (review.outcome === "nonconverged")
                 return { outcome: "needs-human", detail: review.detail };
             return { outcome: review.outcome, detail: review.detail, summary: review.summary };
         }
-        for (let cycle = 1; cycle <= this.qaMaxCycles; cycle++) {
-            const before = this.qaReviewer && this.projectDir ? fingerprintProtectedTree(this.projectDir) : undefined;
-            const qa = await this.doTurnWith(this.qaReviewer ?? this.builder, buildQaInstruction());
-            if (before && this.projectDir) {
-                const changes = changedProtectedFiles(before, fingerprintProtectedTree(this.projectDir));
-                if (changes.length > 0) {
-                    this.log.write("qa-protected-files-changed", { stepIndex, cycle, paths: changes });
-                    return { outcome: "needs-human", detail: `independent QA changed protected files: ${changes.join(", ")}` };
-                }
-            }
-            this.log.write("qa", {
-                stepIndex,
-                cycle,
-                statusKind: qa.status.kind,
-                issues: qa.status.issues,
-                costUsd: qa.result.costUsd,
-                isError: qa.result.isError,
-            });
-            if (qa.result.isError) {
-                return { outcome: "blocked", detail: `QA turn errored: ${qa.result.text.slice(0, 200)}` };
-            }
-            if (qa.status.kind === "qa_pass") {
-                return { outcome: "passed", summary: qa.status.summary };
-            }
-            if (qa.status.kind === "blocked") {
-                return { outcome: "blocked", detail: qa.status.reason ?? "QA reported blocked" };
-            }
-            if (qa.status.kind !== "qa_fail") {
-                return {
-                    outcome: "needs-human",
-                    detail: qa.status.error ?? `QA turn did not emit a valid marker (got ${qa.status.kind})`,
-                };
-            }
-            const fix = await this.doTurn(buildQaFixInstruction(qa.status.issues ?? "(no issues listed)"));
-            this.log.write("qa-fix", {
-                stepIndex,
-                cycle,
-                statusKind: fix.status.kind,
-                costUsd: fix.result.costUsd,
-                isError: fix.result.isError,
-            });
-            if (fix.result.isError) {
-                return { outcome: "blocked", detail: `QA fix turn errored: ${fix.result.text.slice(0, 200)}` };
-            }
-            if (fix.status.kind === "blocked") {
-                return { outcome: "blocked", detail: fix.status.reason ?? "QA fix reported blocked" };
-            }
-            if (fix.status.kind !== "done") {
-                return {
-                    outcome: "needs-human",
-                    detail: fix.status.error ?? `QA fix turn did not emit done (got ${fix.status.kind})`,
-                };
-            }
-            // loop back into QA
-        }
         return {
             outcome: "needs-human",
-            detail: `QA could not converge after ${this.qaMaxCycles} cycles`,
+            detail: "QA is enabled but no fresh disposable QA factory and durable session boundary were configured",
         };
     }
-    async runQaReview(stepIndex) {
-        return this.runQa(stepIndex);
+    async runQaReview(stepIndex, builderResult) {
+        return this.runQa(stepIndex, undefined, builderResult);
     }
-    qaSessionId() { return this.qaStream.sessionId ?? this.qaReviewer?.sessionId(); }
-    qaSessionRef() { return this.qaStream.sessionRef ?? this.qaReviewer?.sessionRef?.(); }
+    qaSessionId() { return this.qaStream.sessionId; }
+    qaSessionRef() { return this.qaStream.sessionRef; }
     builderSessionId() { return this.builder.sessionId(); }
     builderAdapter() { return this.builder; }
     async close() { await this.builder.close(); }
@@ -539,7 +566,10 @@ export class Foreman {
                         detail = `recovery ticket ${preferredTicketId} is no longer available in the implementation queue`;
                         break;
                     }
-                    if (i === 1 && preferredTicketId && next && next.status !== "next" && next.status !== "in_progress") {
+                    if (i === 1 && preferredTicketId && next?.status === "blocked") {
+                        cmdUnblock(this.projectDir, preferredTicketId, { actor: "foreman", summary: "Reopened by explicit build recovery" });
+                    }
+                    else if (i === 1 && preferredTicketId && next && next.status !== "next" && next.status !== "in_progress") {
                         outcome = "needs-human";
                         detail = `recovery ticket ${preferredTicketId} cannot resume while its status is ${next.status}`;
                         break;
@@ -566,7 +596,10 @@ export class Foreman {
             if (i > 1)
                 await this.prepareBuilderBoundary(instruction);
             this.builderWorkSessions += 1;
-            const { result, status } = await this.doTurn(instruction);
+            const turn = () => this.doTurn(instruction);
+            const { result, status } = this.observer
+                ? await this.observer.withContext({ role: "builder", stream: "builder", ticketId: pendingTicketId }, turn)
+                : await turn();
             this.log.write("step", {
                 index: i,
                 statusKind: status.kind,
@@ -586,7 +619,7 @@ export class Foreman {
                 let qaSummary;
                 let qaWaived = false;
                 if (this.qaEnabled) {
-                    const qa = await this.runQa(i, status.ticket ?? pendingTicketId);
+                    const qa = await this.runQa(i, status.ticket ?? pendingTicketId, result.text);
                     if (qa.outcome === "blocked") {
                         outcome = "blocked";
                         detail = qa.detail;
@@ -672,6 +705,16 @@ function lastLine(text) {
     const lines = text.trim().split("\n");
     return (lines[lines.length - 1] ?? "").slice(0, 200);
 }
+function buildBlockerRecoveryInstruction(reason) {
+    return [
+        `You reported this blocker: ${reason}`,
+        "Do not end the run. Analyze the durable state and propose two or three safe, materially different approaches the user can choose from.",
+        "Put your recommended approach first and end its label with (Recommended). Include the important consequence or tradeoff in every choice label.",
+        "Do not perform more implementation or QA work until the user chooses. End exactly with:",
+        'STEP_STATUS: needs_input | question="How should Rafi unblock this work?" choices="recommended approach and consequence (Recommended)|alternative and consequence|another alternative and consequence"',
+        "After the user answers, apply that guidance in this same session. If still blocked, report blocked again so Rafi can offer a new set of approaches.",
+    ].join("\n\n");
+}
 function fingerprintProtectedTree(root) {
     const out = new Map();
     const ignored = new Set([".git", "node_modules", "dist", "coverage"]);

package/dist/handoffs.d.ts

@@ -23,8 +23,12 @@ export interface CreateHandoffInput {
     compactMaximum: number;
     resources?: Array<{
         label: string;
-        content: string | Buffer;
+        content?: string | Buffer;
+        digest?: string;
         authoritative: boolean;
+        requiredForRecovery?: boolean;
+        mediaType?: string;
+        path?: string;
     }>;
     requestedByBuilder?: boolean;
     /** Internal recovery path: use the last valid checkpoint while its head is marked degraded/invalid. */
@@ -45,14 +49,42 @@ export declare class HandoffLoopError extends Error {
     readonly runId: string;
     constructor(runId: string);
 }
+export type HandoffAcceptanceFailureCode = "missing-acknowledgement" | "invalid-continuity-delta" | "missing-successor-session" | "missing-scoped-successor-session" | "reused-predecessor-session";
+export declare class HandoffAcceptanceError extends Error {
+    readonly code: HandoffAcceptanceFailureCode;
+    readonly runId: string;
+    readonly generation: number;
+    constructor(code: HandoffAcceptanceFailureCode, runId: string, generation: number, detail: string);
+}
+export declare class HandoffRecoveryPausedError extends Error {
+    readonly runId: string;
+    readonly generation: number;
+    constructor(runId: string, generation: number, detail: string);
+}
+export type HandoffRecoveryChoice = "retry" | "switch" | "custom" | "pause";
+export interface HandoffRecoveryOptions {
+    /** Enables the provider-switch choice. The callback must honor the requested runtime. */
+    allowProviderSwitch?: boolean;
+    choose?: (error: HandoffAcceptanceError, currentRuntime: "claude" | "codex") => Promise<HandoffRecoveryChoice>;
+    customGuidance?: () => Promise<string | undefined>;
+    desktopNotifications?: boolean;
+    terminalBell?: boolean;
+    /** Persist run-local provider selection only after validated acceptance. */
+    onAccepted?: (result: HandoffTransferResult) => void | Promise<void>;
+}
 /** Durable, validated ownership transfer; cache copies are never authoritative. */
 export declare class HandoffService {
     readonly projectDir: string;
     readonly cacheRoot: string;
     constructor(projectDir: string);
     stage(input: CreateHandoffInput, now?: Date): StagedHandoff;
-    transfer(input: CreateHandoffInput, createSuccessor: (handoff: StagedHandoff) => Promise<BuilderAdapter>): Promise<HandoffTransferResult>;
-    acceptStaged(staged: StagedHandoff, successor: BuilderAdapter): Promise<HandoffTransferResult>;
+    transfer(input: CreateHandoffInput, createSuccessor: (handoff: StagedHandoff, requestedRuntime?: "claude" | "codex") => Promise<BuilderAdapter>, recovery?: HandoffRecoveryOptions): Promise<HandoffTransferResult>;
+    acceptStagedWithRecovery(staged: StagedHandoff, initialSuccessor: BuilderAdapter, createSuccessor: (handoff: StagedHandoff, requestedRuntime?: "claude" | "codex") => Promise<BuilderAdapter>, recovery?: HandoffRecoveryOptions): Promise<HandoffTransferResult>;
+    acceptStaged(staged: StagedHandoff, successor: BuilderAdapter, options?: {
+        finalizeFailure?: boolean;
+        guidance?: string;
+    }): Promise<HandoffTransferResult>;
+    private failStaged;
     inspect(runId: string, generation?: number): {
         manifest: HandoffManifestV1;
         markdown: string;