ai-foreman 1.7.13 → 1.7.14

package/dist/cli/state.d.ts

@@ -0,0 +1,4 @@
+import { Command } from "commander";
+export declare function buildStateCommand(opts?: {
+    resolveProject?: (project?: string) => string;
+}): Command;

package/dist/cli/state.js

@@ -0,0 +1,69 @@
+import { Command } from "commander";
+import { resolve } from "node:path";
+import { exportStateBundle, hasTransferableState, importStateBundle, inspectStateBundle } from "../stateTransfer.js";
+export function buildStateCommand(opts = {}) {
+    const command = new Command("state")
+        .description("Export, inspect, and import portable Rafi local state bundles.");
+    command
+        .command("export")
+        .description("Write a portable Rafi state bundle for sequential machine handoff.")
+        .argument("[project]", "project directory", ".")
+        .requiredOption("-o, --output <file>", "output bundle file")
+        .action(async (project, options) => {
+        const root = opts.resolveProject ? opts.resolveProject(project) : resolve(project);
+        const manifest = await exportStateBundle(root, options.output);
+        console.log(`rafi state export: wrote ${options.output}`);
+        console.log(`  bundle: ${manifest.bundleId}`);
+        console.log(`  files: ${manifest.files.length}`);
+        if (manifest.source.git.branch || manifest.source.git.head) {
+            console.log(`  git: ${manifest.source.git.branch ?? "(detached)"} ${manifest.source.git.head ?? ""}`.trimEnd());
+        }
+    });
+    command
+        .command("inspect")
+        .description("Inspect and verify a Rafi state bundle.")
+        .argument("<bundle>", "state bundle file")
+        .option("--json", "print the manifest as JSON")
+        .action((bundle, options) => {
+        const result = inspectStateBundle(bundle);
+        if (options.json) {
+            console.log(JSON.stringify(result.manifest, null, 2));
+            return;
+        }
+        console.log(`rafi state inspect: ${result.valid ? "valid" : "invalid"}`);
+        console.log(`  bundle: ${result.manifest.bundleId}`);
+        console.log(`  created: ${result.manifest.createdAt}`);
+        console.log(`  source: ${result.manifest.source.root}`);
+        console.log(`  files: ${result.manifest.files.length}`);
+        console.log("  provider sessions: not portable; use `rafi build:resume --fresh-with-handoff` when exact session recovery is unavailable");
+    });
+    command
+        .command("import")
+        .description("Restore a portable Rafi state bundle into an existing matching source checkout.")
+        .argument("<projectOrBundle>", "project directory or bundle file")
+        .argument("[bundle]", "state bundle file")
+        .option("-y, --yes", "confirm replacement of local Rafi state")
+        .action(async (projectOrBundle, bundle, options) => {
+        const project = bundle ? projectOrBundle : ".";
+        const bundleFile = bundle ?? projectOrBundle;
+        const root = opts.resolveProject ? opts.resolveProject(project) : resolve(project);
+        let confirmed = Boolean(options.yes);
+        if (!confirmed && hasTransferableState(root)) {
+            if (!process.stdin.isTTY || !process.stdout.isTTY)
+                throw new Error("refusing non-interactive import that replaces existing local Rafi state without --yes");
+            const { confirm, isCancel } = await import("@clack/prompts");
+            const answer = await confirm({ message: `Replace existing local Rafi state in ${root}?`, initialValue: false });
+            if (isCancel(answer) || !answer) {
+                console.log("rafi state import: cancelled; no state changed");
+                return;
+            }
+            confirmed = true;
+        }
+        const result = await importStateBundle(root, bundleFile, { yes: confirmed });
+        console.log(`rafi state import: restored bundle ${result.manifest.bundleId}`);
+        if (result.backupDir)
+            console.log(`  previous state backup: ${result.backupDir}`);
+        console.log("  provider sessions are historical only; resume with `rafi build:resume --fresh-with-handoff` if exact session recovery fails");
+    });
+    return command;
+}

package/dist/continuity.d.ts

@@ -54,6 +54,8 @@ export interface ContinuityAdapterOptions {
     replaceRecoveryLeaseAfterCheckpoint?: boolean;
     /** Host-owned validated Builder handoff request processing at a safe turn boundary. */
     handleHandoffRequest?: (text: string, predecessor: BuilderAdapter, frozenAction: string) => Promise<BuilderAdapter | undefined>;
+    /** QA journals each provider turn separately; wrappers must not repair or redispatch inside one host turn. */
+    durableSingleTurn?: boolean;
 }
 /** Enforces a durable role checkpoint after every completed provider turn. */
 export declare class ContinuityAdapter implements BuilderAdapter {
@@ -67,10 +69,12 @@ export declare class ContinuityAdapter implements BuilderAdapter {
     sendTurn(instruction: string): Promise<TurnResult>;
     sessionId(): string | undefined;
     sessionRef(): import("rafi-spec").ProviderSessionRefV1 | undefined;
+    prepareSession(): Promise<import("rafi-spec").ProviderSessionRefV1>;
     adoptSessionRef(ref: import("rafi-spec").ProviderSessionRefV1): void;
     validateSession(): Promise<import("rafi-spec").SessionAvailabilityV1>;
     compact(): Promise<CompactResult>;
     prepareAutoCompaction(thresholdPercent?: number): Promise<NativeAutoCompactionPolicy | void>;
+    requiresAutoCompactionSetupTurn(): boolean;
     autoCompactionPolicy(): NativeAutoCompactionPolicy | undefined;
     drainNativeCompactions(): import("./adapters/types.js").NativeCompaction[];
     restoreNativeCompactions(compactions: NativeCompaction[]): void;

package/dist/continuity.js

@@ -158,6 +158,10 @@ export class ContinuityAdapter {
         if (parsed.delta) {
             this.publish(parsed.delta, "turn_completed", original);
             this.moveRecoveryLeaseAfterCheckpoint();
+            if (this.options.durableSingleTurn) {
+                return { ...original, text: parsed.cleanText, hostInstruction: instruction, providerInstruction: original.providerInstruction ?? providerInstruction,
+                    rawResponse: original.rawResponse ?? original.text, cleanedResponse: parsed.cleanText };
+            }
             const successor = await this.options.handleHandoffRequest?.(original.text, this.adapter, instruction);
             if (successor && successor !== this.adapter) {
                 await this.adoptValidatedSuccessor(successor);
@@ -166,7 +170,19 @@ export class ContinuityAdapter {
                     instruction,
                 ].join("\n\n"));
             }
-            return { ...original, text: parsed.cleanText, hostInstruction: instruction, providerInstruction,
+            return { ...original, text: parsed.cleanText, hostInstruction: instruction, providerInstruction: original.providerInstruction ?? providerInstruction,
+                rawResponse: original.rawResponse ?? original.text, cleanedResponse: parsed.cleanText };
+        }
+        if (this.options.durableSingleTurn) {
+            const invalidDb = new WorkflowDb(this.options.projectDir);
+            try {
+                invalidDb.appendContinuityEvent({ runId: this.options.runId, role: "host", kind: "continuity_invalid", payload: { problems: parsed.error?.problems }, authoritativeStateRevision: this.revision() });
+            }
+            finally {
+                invalidDb.close();
+            }
+            return { ...original, isError: true, text: `QA continuity record was invalid: ${parsed.error?.problems.join("; ") ?? "unknown error"}`,
+                hostInstruction: instruction, providerInstruction: original.providerInstruction ?? providerInstruction,
                 rawResponse: original.rawResponse ?? original.text, cleanedResponse: parsed.cleanText };
         }
         const repair = await this.adapter.sendTurn([
@@ -179,7 +195,7 @@ export class ContinuityAdapter {
         if (repaired.delta) {
             this.publish(repaired.delta, "turn_completed_after_repair", original);
             this.moveRecoveryLeaseAfterCheckpoint();
-            return { ...original, text: parsed.cleanText, hostInstruction: instruction, providerInstruction,
+            return { ...original, text: parsed.cleanText, hostInstruction: instruction, providerInstruction: original.providerInstruction ?? providerInstruction,
                 rawResponse: original.rawResponse ?? original.text, cleanedResponse: parsed.cleanText };
         }
         const invalidDb = new WorkflowDb(this.options.projectDir);
@@ -216,7 +232,8 @@ export class ContinuityAdapter {
         const successor = await this.options.createSuccessor(handoff);
         const accepted = await successor.sendTurn(`${handoff}\n\nReply with HANDOFF_ACCEPTED on the first line, then ${continuityInstruction()}`);
         const successorDelta = parseContinuityDelta(accepted.text);
-        if (!/^HANDOFF_ACCEPTED\b/m.test(accepted.text) || !successorDelta.delta || !successor.sessionId()) {
+        const firstAcceptanceLine = accepted.text.split(/\r?\n/).map((line) => line.trim()).find(Boolean);
+        if (firstAcceptanceLine !== "HANDOFF_ACCEPTED" || !successorDelta.delta || !successor.sessionId()) {
             await successor.close().catch(() => { });
             throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "fresh successor did not validate and accept the cumulative checkpoint");
         }
@@ -234,10 +251,16 @@ export class ContinuityAdapter {
     }
     sessionId() { return this.adapter.sessionId(); }
     sessionRef() { return this.adapter.sessionRef?.(); }
+    prepareSession() {
+        if (!this.adapter.prepareSession)
+            return Promise.reject(new Error("wrapped adapter cannot establish a provider session without a work turn"));
+        return this.adapter.prepareSession();
+    }
     adoptSessionRef(ref) { this.adapter.adoptSessionRef?.(ref); }
     validateSession() { return this.adapter.validateSession?.() ?? Promise.resolve({ version: 1, status: "unknown", checkedAt: new Date().toISOString(), reason: "legacy-unscoped" }); }
     compact() { return this.adapter.compact ? this.adapter.compact() : Promise.resolve({ ok: false, error: "provider adapter does not expose native compaction" }); }
     prepareAutoCompaction(thresholdPercent) { return this.adapter.prepareAutoCompaction?.(thresholdPercent) ?? Promise.resolve(); }
+    requiresAutoCompactionSetupTurn() { return this.adapter.requiresAutoCompactionSetupTurn?.() ?? false; }
     autoCompactionPolicy() { return this.adapter.autoCompactionPolicy?.(); }
     drainNativeCompactions() { return this.adapter.drainNativeCompactions?.() ?? []; }
     restoreNativeCompactions(compactions) { this.adapter.restoreNativeCompactions?.(compactions); }

package/dist/foreman.d.ts

@@ -2,7 +2,7 @@ import type { BuilderAdapter, PermissionHandler, PermissionRequest, TurnResult }
 import type { PermissionPolicy } from "./permissions/policy.js";
 import { type AnsweredProviderQuestion } from "./providerQuestions.js";
 import type { Log } from "./log.js";
-import { type QaNonconvergenceContext, type QaNonconvergenceDecision, type QaReportRecoveryHandler, type QaSessionBoundaryRecovery, type QaSessionHandle } from "./qaReview.js";
+import { type QaNonconvergenceContext, type QaNonconvergenceDecision, type QaReportRecoveryHandler, type QaSessionBoundaryRecovery, type QaSessionBoundaryResult, type QaSessionHandle } from "./qaReview.js";
 import type { SessionStrategy } from "rafi-spec";
 import type { RunObserver } from "./observability.js";
 import type { QaRecoveryPacket } from "./qaRecovery.js";
@@ -77,17 +77,20 @@ export declare class Foreman {
     private readonly qaContinuityManaged;
     private readonly qaReportRecovery?;
     private qaResumedRecovery?;
+    /** Exact durable build-run scope. Observability is never an identity authority. */
+    private readonly qaRunId;
     private readonly ticketsEnabled;
     private readonly notificationsEnabled;
     private readonly terminalBellEnabled;
     private readonly qaStream;
     private builderWorkSessions;
-    private readonly fallbackQaRunId;
     constructor(builder: BuilderAdapter, log: Log, notifications?: boolean | ForemanNotificationOptions, qaEnabled?: boolean, qaMaxCycles?: number, projectDir?: string | undefined, 
     /** @deprecated QA must be created by qaFactory in a disposable snapshot. */
-    _deprecatedSameSessionReviewer?: BuilderAdapter, qaFactory?: ((cwd: string, sessionId?: string) => Promise<BuilderAdapter | QaSessionHandle>) | undefined, qaSessionStrategy?: SessionStrategy, builderFactory?: ((cwd: string, sessionId?: string) => Promise<BuilderAdapter>) | undefined, builderSessionStrategy?: SessionStrategy, qaNonconvergence?: ((context: QaNonconvergenceContext) => Promise<QaNonconvergenceDecision>) | undefined, beforeBuilderTurn?: ((adapter: BuilderAdapter, frozenAction: string) => Promise<BuilderAdapter>) | undefined, builderSessionBoundary?: ((adapter: BuilderAdapter, frozenAction: string, strategy: SessionStrategy) => Promise<BuilderAdapter>) | undefined, qaSessionBoundary?: ((adapter: BuilderAdapter, frozenAction: string, strategy: SessionStrategy, cwd: string, recovery?: QaSessionBoundaryRecovery) => Promise<BuilderAdapter>) | undefined, observeQaNativeCompactions?: ((adapter: BuilderAdapter) => Promise<void>) | undefined, 
+    _deprecatedSameSessionReviewer?: BuilderAdapter, qaFactory?: ((cwd: string, sessionId?: string) => Promise<QaSessionHandle>) | undefined, qaSessionStrategy?: SessionStrategy, builderFactory?: ((cwd: string, sessionId?: string) => Promise<BuilderAdapter>) | undefined, builderSessionStrategy?: SessionStrategy, qaNonconvergence?: ((context: QaNonconvergenceContext) => Promise<QaNonconvergenceDecision>) | undefined, beforeBuilderTurn?: ((adapter: BuilderAdapter, frozenAction: string) => Promise<BuilderAdapter>) | undefined, builderSessionBoundary?: ((adapter: BuilderAdapter, frozenAction: string, strategy: SessionStrategy) => Promise<BuilderAdapter>) | undefined, qaSessionBoundary?: ((handle: QaSessionHandle, frozenAction: string, strategy: SessionStrategy, cwd: string, recovery?: QaSessionBoundaryRecovery) => Promise<QaSessionBoundaryResult>) | undefined, observeQaNativeCompactions?: ((adapter: BuilderAdapter) => Promise<void>) | undefined, 
     /** Persist a Builder's provider-native event immediately after every turn. */
-    observeBuilderNativeCompactions?: ((adapter: BuilderAdapter) => Promise<void>) | undefined, observer?: RunObserver | undefined, qaRuntimeContext?: unknown | undefined, qaContinuityManaged?: boolean, qaReportRecovery?: QaReportRecoveryHandler | undefined, qaResumedRecovery?: QaRecoveryPacket | undefined);
+    observeBuilderNativeCompactions?: ((adapter: BuilderAdapter) => Promise<void>) | undefined, observer?: RunObserver | undefined, qaRuntimeContext?: unknown | undefined, qaContinuityManaged?: boolean, qaReportRecovery?: QaReportRecoveryHandler | undefined, qaResumedRecovery?: QaRecoveryPacket | undefined, 
+    /** Exact durable build-run scope. Observability is never an identity authority. */
+    qaRunId?: string);
     private waitForUserInput;
     /**
      * Send one instruction and resolve any needs_input exchanges before returning.
@@ -122,6 +125,21 @@ export declare class Foreman {
         detail?: string;
         summary?: string;
     }>;
+    /** Resume an already-built ticket at the QA boundary without dispatching Builder preflight/work. */
+    runPendingQaRecovery(ticketId: string, builderResult: string): Promise<{
+        outcome: "passed" | "blocked" | "needs-human" | "waived";
+        detail?: string;
+        summary?: string;
+        passCertificateId?: string;
+        sourceStateDigest?: string;
+    }>;
+    /** Complete only the pending QA boundary and its tracker transition. No Builder work turn is sent. */
+    completePendingQaRecovery(ticketId: string): Promise<{
+        outcome: "passed" | "blocked" | "needs-human" | "waived";
+        detail?: string;
+    }>;
+    /** Reconcile a crash between certificate consumption, tracker completion, and the final receipt. */
+    completePendingQaFinalization(ticketId: string): Promise<void>;
     qaSessionId(): string | undefined;
     qaSessionRef(): import("rafi-spec").ProviderSessionRefV1 | undefined;
     builderSessionId(): string | undefined;

package/dist/foreman.js

@@ -3,15 +3,18 @@ import { MARKER_SPEC, QA_MARKER_SPEC } from "./markers.js";
 import { countProviderQuestions, handleProviderQuestionTool } from "./providerQuestions.js";
 import { signalAttention } from "./notify.js";
 import { pauseActivityForInput } from "./activity.js";
-import { isTicketsInitialized, loadTicketsConfig } from "./tickets/config.js";
+import { isTicketsInitialized, loadTicketsConfig, resolveTicketPaths } from "./tickets/config.js";
+import { StateDb } from "./tickets/stateDb.js";
 import { cmdUpdate, cmdComplete, cmdBlock, cmdUnblock, cmdImplementationQueue } from "./tickets/commands.js";
 import { loadTickets } from "./tickets/ticketLoader.js";
-import { buildDurableQaFixHandoff, runIsolatedQa } from "./qaReview.js";
-import { changeManifestAsync, deterministicChangeSummaryAsync } from "./qaSnapshot.js";
+import { beginQaFinalization, completeQaFinalization, verifyPendingQaFinalizationSource, runIsolatedQa } from "./qaReview.js";
+import { QaFailureDeliveryService } from "./qaFailureDelivery.js";
+import { generatedTrackerDirtyPaths } from "./branch/git.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";
+import { WorkflowDb } from "./workflowDb.js";
 /** Phrases that suggest the builder ended its turn by asking the human. */
 const QUESTION_HINTS = [
     "should i",
@@ -237,17 +240,19 @@ export class Foreman {
     qaContinuityManaged;
     qaReportRecovery;
     qaResumedRecovery;
+    qaRunId;
     ticketsEnabled;
     notificationsEnabled;
     terminalBellEnabled;
     qaStream = { reviews: 0, modificationViolations: 0 };
     builderWorkSessions = 0;
-    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, observer, qaRuntimeContext, qaContinuityManaged = false, qaReportRecovery, qaResumedRecovery) {
+    observeBuilderNativeCompactions, observer, qaRuntimeContext, qaContinuityManaged = false, qaReportRecovery, qaResumedRecovery, 
+    /** Exact durable build-run scope. Observability is never an identity authority. */
+    qaRunId = `qa-${randomUUID()}`) {
         this.builder = builder;
         this.log = log;
         this.qaEnabled = qaEnabled;
@@ -268,6 +273,7 @@ export class Foreman {
         this.qaContinuityManaged = qaContinuityManaged;
         this.qaReportRecovery = qaReportRecovery;
         this.qaResumedRecovery = qaResumedRecovery;
+        this.qaRunId = qaRunId;
         void _deprecatedSameSessionReviewer;
         this.notificationsEnabled = typeof notifications === "boolean" ? notifications : notifications.desktop;
         this.terminalBellEnabled = typeof notifications === "boolean" ? true : notifications.terminalBell;
@@ -481,7 +487,6 @@ export class Foreman {
     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,
@@ -489,34 +494,49 @@ export class Foreman {
                 qaStrategy: this.qaSessionStrategy,
                 state: this.qaStream,
                 createQa: this.qaFactory,
-                sessionBoundary: this.qaSessionBoundary,
+                sessionBoundary: this.qaSessionBoundary ?? (async () => { throw new Error("QA recovery requires a validated durable session boundary"); }),
                 observeNativeCompactions: this.observeQaNativeCompactions,
                 maxCycles: this.qaMaxCycles,
-                recovery: { projectDir: this.projectDir, runId: this.observer?.runId ?? this.fallbackQaRunId },
+                recovery: { projectDir: this.projectDir, runId: this.qaRunId },
                 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);
+                deliverFailure: async (request) => {
                     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, response: fix.result.text, summary: fix.status.summary ?? fix.result.text };
+                    const delivery = new QaFailureDeliveryService();
+                    const result = await delivery.deliver(request, {
+                        adapter: () => this.builder,
+                        setAdapter: (adapter) => { this.builder = adapter; },
+                        sessionStrategy: this.builderSessionStrategy,
+                        prepareBoundary: async (_adapter, instruction) => { await this.prepareBuilderBoundary(instruction); return this.builder; },
+                        beforeTurn: async (adapter, instruction) => this.beforeBuilderTurn ? this.beforeBuilderTurn(adapter, instruction) : adapter,
+                        recordSession: (session) => {
+                            const sessionId = typeof session === "string" ? session : session.sessionId;
+                            this.log.write("qa-fix", { stepIndex, sessionId });
+                        },
+                    });
+                    this.log.write("qa-fix", { stepIndex, ok: result.ok, detail: result.detail, providerTurnId: result.providerTurnId, handoffId: result.handoffId, operationId: result.operationId });
+                    return result;
                 },
                 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 (resumedRecovery) {
+                const recoveryDb = new WorkflowDb(this.projectDir);
+                try {
+                    if (recoveryDb.qaRecoveryHead(resumedRecovery.manifest.runId, resumedRecovery.manifest.ticketId)?.pendingAction === "resolved")
+                        this.qaResumedRecovery = undefined;
+                }
+                finally {
+                    recoveryDb.close();
+                }
+            }
             if (review.outcome === "nonconverged")
                 return { outcome: "needs-human", detail: review.detail };
-            return { outcome: review.outcome, detail: review.detail, summary: review.summary };
+            return { outcome: review.outcome, detail: review.detail, summary: review.summary, passCertificateId: review.passCertificateId, sourceStateDigest: review.sourceStateDigest };
         }
         return {
             outcome: "needs-human",
@@ -526,6 +546,61 @@ export class Foreman {
     async runQaReview(stepIndex, builderResult) {
         return this.runQa(stepIndex, undefined, builderResult);
     }
+    /** Resume an already-built ticket at the QA boundary without dispatching Builder preflight/work. */
+    async runPendingQaRecovery(ticketId, builderResult) {
+        if (this.qaResumedRecovery && this.qaResumedRecovery.manifest.ticketId !== ticketId)
+            throw new Error(`pending QA recovery belongs to ${this.qaResumedRecovery.manifest.ticketId}, not ${ticketId}`);
+        return this.runQa(1, ticketId, builderResult);
+    }
+    /** Complete only the pending QA boundary and its tracker transition. No Builder work turn is sent. */
+    async completePendingQaRecovery(ticketId) {
+        if (!this.projectDir || !this.ticketsEnabled)
+            throw new Error("pending QA recovery requires an initialized ticket project");
+        const qa = await this.runPendingQaRecovery(ticketId, "Resuming the exact durable QA failure/review boundary; no new Builder work was dispatched.");
+        if (qa.outcome !== "passed" && qa.outcome !== "waived")
+            return qa;
+        if (qa.outcome === "passed") {
+            if (!qa.passCertificateId || !qa.sourceStateDigest)
+                throw new Error("QA passed without a durable pass certificate");
+            await beginQaFinalization(this.projectDir, this.projectDir, this.qaRunId, ticketId, qa.passCertificateId, qa.sourceStateDigest, `ticket-complete:${ticketId}`, generatedTrackerDirtyPaths(loadTicketsConfig(this.projectDir).paths));
+        }
+        cmdComplete(this.projectDir, ticketId, {
+            actor: "foreman",
+            summary: qa.summary ?? "Completed after exact QA recovery",
+            validationResult: qa.outcome === "waived" ? "failed" : "passed",
+            validationNotes: qa.outcome === "waived" ? "User explicitly waived unresolved QA failures" : "Durable QA recovery emitted qa_pass",
+            evidence: qa.summary ?? (qa.outcome === "waived" ? "Unresolved QA issues preserved in durable run evidence" : "Durable QA recovery emitted qa_pass"),
+        });
+        if (qa.outcome === "passed")
+            completeQaFinalization(this.projectDir, this.qaRunId, ticketId);
+        return qa;
+    }
+    /** Reconcile a crash between certificate consumption, tracker completion, and the final receipt. */
+    async completePendingQaFinalization(ticketId) {
+        if (!this.projectDir || !this.ticketsEnabled)
+            throw new Error("pending QA finalization requires an initialized ticket project");
+        const protocol = new WorkflowDb(this.projectDir);
+        try {
+            if (protocol.qaTicketHead(this.qaRunId, ticketId).state !== "finalizing")
+                throw new Error(`QA finalization is not pending for ${ticketId}`);
+        }
+        finally {
+            protocol.close();
+        }
+        const paths = resolveTicketPaths(loadTicketsConfig(this.projectDir), this.projectDir);
+        const stateDb = new StateDb(paths.stateDb);
+        const alreadyDone = stateDb.getState(ticketId)?.status === "done";
+        stateDb.close();
+        await verifyPendingQaFinalizationSource(this.projectDir, this.projectDir, this.qaRunId, ticketId, alreadyDone);
+        if (!alreadyDone) {
+            cmdComplete(this.projectDir, ticketId, {
+                actor: "foreman", summary: "Completed after reconciling durable QA finalization",
+                validationResult: "passed", validationNotes: "Pass certificate was consumed before the interrupted tracker transition",
+                evidence: "Durable QA pass certificate and finalization intent reconciled after restart",
+            });
+        }
+        completeQaFinalization(this.projectDir, this.qaRunId, ticketId);
+    }
     qaSessionId() { return this.qaStream.sessionId; }
     qaSessionRef() { return this.qaStream.sessionRef; }
     builderSessionId() { return this.builder.sessionId(); }
@@ -618,6 +693,8 @@ export class Foreman {
             if (status.kind === "done" || status.kind === "plan_complete") {
                 let qaSummary;
                 let qaWaived = false;
+                let qaPassCertificateId;
+                let qaSourceStateDigest;
                 if (this.qaEnabled) {
                     const qa = await this.runQa(i, status.ticket ?? pendingTicketId, result.text);
                     if (qa.outcome === "blocked") {
@@ -632,6 +709,8 @@ export class Foreman {
                     }
                     qaWaived = qa.outcome === "waived";
                     qaSummary = qa.summary;
+                    qaPassCertificateId = qa.passCertificateId;
+                    qaSourceStateDigest = qa.sourceStateDigest;
                 }
                 // Update ticket state only after QA has passed, so generated tracker
                 // state does not claim done before verification has completed.
@@ -639,6 +718,11 @@ export class Foreman {
                     const ticketId = status.ticket ?? pendingTicketId;
                     if (ticketId) {
                         try {
+                            if (this.qaEnabled && !qaWaived) {
+                                if (!qaPassCertificateId || !qaSourceStateDigest)
+                                    throw new Error("QA passed without a durable pass certificate");
+                                await beginQaFinalization(this.projectDir, this.projectDir, this.qaRunId, ticketId, qaPassCertificateId, qaSourceStateDigest, `ticket-complete:${ticketId}`, generatedTrackerDirtyPaths(loadTicketsConfig(this.projectDir).paths));
+                            }
                             cmdComplete(this.projectDir, ticketId, {
                                 actor: "foreman",
                                 summary: status.summary ?? `Step ${i} complete`,
@@ -650,6 +734,8 @@ export class Foreman {
                                     ? (qaSummary ?? (qaWaived ? "Unresolved QA issues preserved in run evidence" : "Foreman QA emitted qa_pass"))
                                     : undefined,
                             });
+                            if (this.qaEnabled && !qaWaived)
+                                completeQaFinalization(this.projectDir, this.qaRunId, ticketId);
                         }
                         catch (err) {
                             outcome = "needs-human";

package/dist/handoffs.d.ts

@@ -1,4 +1,4 @@
-import type { ContinuityDelta, HandoffLineage, HandoffManifestV1, ProviderSessionRefV1, SessionUsageSample } from "rafi-spec";
+import type { ContinuityDelta, HandoffAcceptanceReceiptV1, HandoffLineage, HandoffManifestV1, ProviderSessionRefV1, SessionUsageSample } from "rafi-spec";
 import type { BuilderAdapter } from "./adapters/types.js";
 export declare const HANDOFF_CACHE_RETENTION_DAYS = 30;
 export declare const HANDOFF_ACCEPTED = "HANDOFF_ACCEPTED";
@@ -29,6 +29,8 @@ export interface CreateHandoffInput {
         requiredForRecovery?: boolean;
         mediaType?: string;
         path?: string;
+        purpose?: string;
+        bytes?: number;
     }>;
     requestedByBuilder?: boolean;
     /** Internal recovery path: use the last valid checkpoint while its head is marked degraded/invalid. */
@@ -44,12 +46,13 @@ export interface HandoffTransferResult extends StagedHandoff {
     successor: BuilderAdapter;
     successorSessionId: string;
     acceptanceCheckpointDigest: string;
+    acceptanceReceipt?: HandoffAcceptanceReceiptV1;
 }
 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 type HandoffAcceptanceFailureCode = "missing-acknowledgement" | "invalid-continuity-delta" | "missing-successor-session" | "missing-scoped-successor-session" | "provider-turn-failed" | "successor-identity-mismatch" | "missing-terminal-event" | "reused-predecessor-session";
 export declare class HandoffAcceptanceError extends Error {
     readonly code: HandoffAcceptanceFailureCode;
     readonly runId: string;