ai-foreman 1.7.26 → 1.7.27

package/dist/adapters/codex.d.ts

@@ -59,6 +59,10 @@ export declare class CodexAdapter implements BuilderAdapter {
     private fastTier?;
     private readonly fastUnavailableModels;
     private turnSawTool;
+    /** Native compaction is non-blocking. The next host turn gets this reminder. */
+    private qaContractReminder?;
+    private qaContractReminderPending;
+    private qaContractReminderEvent?;
     private disableFastMode;
     private prepareFastMode;
     constructor(opts: BuilderAdapterOptions);
@@ -66,6 +70,14 @@ export declare class CodexAdapter implements BuilderAdapter {
         sameSessionAcceptance: boolean;
         nativeCompactionBarrier: boolean;
     };
+    contractCompactionSequence(): number;
+    configureQaContractReminder(reminder: string, onEvent?: (event: {
+        kind: "installed" | "compaction-observed" | "reminder-delivered" | "reminder-retained";
+        at: string;
+        sessionId?: string;
+    }) => void): void;
+    private qaReminderEvent;
+    private instructionWithPendingQaReminder;
     buildInstruction(instruction: string): string;
     buildAppServerArgs(): string[];
     /** Deprecated fixture helper. Runtime execution uses only app-server. */

package/dist/adapters/codex.js

@@ -75,6 +75,10 @@ export class CodexAdapter {
     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))
@@ -117,6 +121,22 @@ export class CodexAdapter {
         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,
@@ -143,12 +163,26 @@ export class CodexAdapter {
         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;
@@ -162,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;
         }
@@ -730,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 {

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

@@ -299,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/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);
@@ -448,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/buildRuns.d.ts

@@ -54,6 +54,18 @@ export declare function releaseBuildLease(projectDir: string, run: BuildRunRecor
 export declare function completeBuildRun(projectDir: string, run: BuildRunRecordV2, now?: Date): BuildRunRecordV2;
 /** A recovered ticket boundary is complete only when the saved run scope is done. */
 export declare function finishRecoveredTicketScope(projectDir: string, run: BuildRunRecordV2, checkpoint: string): BuildRunRecordV2;
+/**
+ * Branch recovery may run one preserved ticket at a time.  Its returned summary
+ * is therefore never proof that the original admitted run is complete.  Use the
+ * tracker and (when enabled) each ticket's durable QA terminal state to derive
+ * the original scope before changing the run's terminal status.
+ */
+export declare function branchTicketScopeProgress(projectDir: string, run: BuildRunRecordV2): {
+    completed: string[];
+    remaining: string[];
+} | undefined;
+/** Complete an isolated-branch run only after its entire admitted scope is proven done. */
+export declare function finishBranchTicketScope(projectDir: string, run: BuildRunRecordV2, checkpoint: string): BuildRunRecordV2;
 /** A recovered boundary cannot authorize work on a still-blocked remainder. */
 export declare function hasRunnableBuildRemainder(projectDir: string, run: BuildRunRecordV2): boolean;
 export declare function readBuildRuns(projectDir: string): BuildRunRecordV2[];

package/dist/buildRuns.js

@@ -350,6 +350,56 @@ export function finishRecoveredTicketScope(projectDir, run, checkpoint) {
         progress: { ...run.progress, completedTickets: completed, remainingTickets: remaining, nextAction: `Resume ${remaining[0]}` },
     }), "recoverable");
 }
+/**
+ * Branch recovery may run one preserved ticket at a time.  Its returned summary
+ * is therefore never proof that the original admitted run is complete.  Use the
+ * tracker and (when enabled) each ticket's durable QA terminal state to derive
+ * the original scope before changing the run's terminal status.
+ */
+export function branchTicketScopeProgress(projectDir, run) {
+    if (run.branchMode === "current" || !run.tickets.length || !isTicketsInitialized(projectDir))
+        return undefined;
+    if (run.status === "completed")
+        return { completed: [...run.tickets], remaining: [] };
+    let state;
+    let workflow;
+    try {
+        const paths = resolveTicketPaths(loadTicketsConfig(projectDir), projectDir);
+        state = new Database(paths.stateDb, { readonly: true, fileMustExist: true });
+        workflow = new WorkflowDb(projectDir);
+        const read = state.prepare("SELECT status FROM ticket_state WHERE ticket_id=?");
+        const qaEnabled = "qaEnabled" in run && run.qaEnabled === true;
+        const completed = run.tickets.filter((ticket) => {
+            if (read.get(ticket)?.status !== "done")
+                return false;
+            // A tracker row cannot replace a missing or unfinished QA verdict.
+            return !qaEnabled || ["completed", "waived"].includes(workflow.qaTicketHead(run.runId, ticket).state);
+        });
+        return { completed, remaining: run.tickets.filter(ticket => !completed.includes(ticket)) };
+    }
+    catch {
+        // Missing tracker/QA evidence must retain a recoverable scope.
+        return { completed: [], remaining: [...run.tickets] };
+    }
+    finally {
+        workflow?.close();
+        state?.close();
+    }
+}
+/** Complete an isolated-branch run only after its entire admitted scope is proven done. */
+export function finishBranchTicketScope(projectDir, run, checkpoint) {
+    if (run.branchMode === "current")
+        throw new Error("Branch scope reconciliation requires an isolated branch run");
+    const progress = branchTicketScopeProgress(projectDir, run);
+    if (!progress)
+        throw new Error("Branch scope reconciliation requires initialized ticket evidence");
+    if (!progress.remaining.length)
+        return completeBuildRun(projectDir, run);
+    return releaseBuildLease(projectDir, checkpointBuildRun(projectDir, run, checkpoint, {
+        currentTicket: progress.remaining[0],
+        progress: { ...run.progress, completedTickets: progress.completed, remainingTickets: progress.remaining, nextAction: `Resume ${progress.remaining[0]}` },
+    }), "recoverable");
+}
 /** A recovered boundary cannot authorize work on a still-blocked remainder. */
 export function hasRunnableBuildRemainder(projectDir, run) {
     if (run.authorizedBatch && run.progress.completedTickets.length >= run.authorizedBatch.requestedSteps)

package/dist/buildWorkContext.js

@@ -2,5 +2,5 @@
 export function renderBuildWorkContext(ticket, checklist) {
     return ["Full assigned work definition (scope authority):", JSON.stringify(ticket, null, 2),
         "Project validation checklist:", ...(checklist.length ? checklist.map((item, index) => `${index + 1}. ${item}`) : ["No additional project checklist configured."]),
-        "Implement this assigned work and provide verification evidence. Final QA runs independently in a separate disposable snapshot and fresh reviewer conversation."].join("\n");
+        "Implement this assigned work and provide verification evidence. Explicitly map every acceptance item to a concrete result or truthful limitation in the final report. If the delivered QA contract requires a historical sequence (for example, a test-first red phase before an implementation edit), execute that sequence in order and retain bounded, truthful evidence of each required step in your final response, including the relevant command result and an ordering record. Do not claim a later passing test proves an earlier failing step. Final QA runs independently in a separate disposable snapshot and fresh reviewer conversation."].join("\n");
 }

package/dist/buildWorkMigration.d.ts

@@ -1,5 +1,15 @@
 import type Database from "better-sqlite3";
 export declare const BUILD_WORK_SCHEMA_VERSION = 4;
+/**
+ * The recovery database is local state, rather than repository content. Keep
+ * the roots on the error so callers can give a copied checkout an actionable
+ * recovery path without weakening the ordinary writer guard.
+ */
+export declare class BuildProjectIdentityMismatchError extends Error {
+    readonly storedRoot: string;
+    readonly currentRoot: string;
+    constructor(storedRoot: string, currentRoot: string);
+}
 /** A copied database must be rebound by state transfer, never by an ordinary writer. */
 export declare function assertBuildProject(db: Database.Database, projectDir: string): void;
 /** Classify legacy records without converting observed progress into permission. */

package/dist/buildWorkMigration.js

@@ -4,11 +4,27 @@ import { join, relative } from "node:path";
 import { classifyProcess } from "./processIdentity.js";
 export const BUILD_WORK_SCHEMA_VERSION = 4;
 const migration = "004_admitted_build_work";
+/**
+ * The recovery database is local state, rather than repository content. Keep
+ * the roots on the error so callers can give a copied checkout an actionable
+ * recovery path without weakening the ordinary writer guard.
+ */
+export class BuildProjectIdentityMismatchError extends Error {
+    storedRoot;
+    currentRoot;
+    constructor(storedRoot, currentRoot) {
+        super(`Rafi local build state belongs to a different project path.\n  Stored path: ${storedRoot}\n  Current path: ${currentRoot}\n\nThis usually means the checkout was copied or moved with .rafi/recovery.sqlite3. Rafi will not write copied build history until you choose how to recover it.\n\nOptions:\n  1. Inspect: rafi state rebind .\n  2. Keep this copied local state: rafi state rebind . --yes\n  3. Transfer state from the original checkout: rafi state export <original-project> --output rafi-state.rafi.gz, then rafi state import . rafi-state.rafi.gz\n  4. Resolve it yourself: preserve or remove the copied .rafi/recovery.sqlite3, then rerun the command.`);
+        this.name = "BuildProjectIdentityMismatchError";
+        this.storedRoot = storedRoot;
+        this.currentRoot = currentRoot;
+    }
+}
 /** A copied database must be rebound by state transfer, never by an ordinary writer. */
 export function assertBuildProject(db, projectDir) {
     const identity = db.prepare("SELECT canonical_root FROM build_project_identity WHERE singleton=1").get();
-    if (identity.canonical_root !== realpathSync(projectDir))
-        throw new Error("Build project identity requires explicit state-transfer rebinding");
+    const currentRoot = realpathSync(projectDir);
+    if (identity.canonical_root !== currentRoot)
+        throw new BuildProjectIdentityMismatchError(identity.canonical_root, currentRoot);
 }
 /** Classify legacy records without converting observed progress into permission. */
 export function migrateBuildWork(db, projectDir, faults) {

package/dist/cli/start.d.ts

@@ -1,4 +1,6 @@
 import { Command } from "commander";
+import type { TicketState } from "../tickets/stateDb.js";
+import type { TicketDef } from "../tickets/ticketSchema.js";
 import type { AgentRoleDefaultsV1 } from "rafi-spec";
 import type { BranchPlan } from "../branch/types.js";
 import { type DeliveryConfig, type DeliveryStack } from "../tickets/delivery.js";
@@ -20,6 +22,12 @@ export declare function formatResumeGuidance(executable: "rafi" | "ai-foreman",
 export declare function savedStartArguments(command: Command, projectDir: string, opts: Record<string, unknown>): string[];
 /** Pure validation shared by interactive start and persisted preparation. */
 export declare function validateStartOptions(opts: Record<string, any>, requireCount: boolean): void;
+/** Preserve the distinction between a staged handoff and an unattempted acceptance. */
+export declare function recordHandoffAcceptanceNotAttempted(projectDir: string, runId: string, role: "builder" | "qa", generation: number, stage: string, detail: string): void;
+/** Default start selection is deliberately the same eligibility model users see in the ticket queue. */
+export declare function selectDefaultExecutionTickets(tickets: TicketDef[], states: Map<string, TicketState>, implementationLimit: number, steps: number, delivery?: DeliveryConfig): string[];
+/** Fail before runtime/provider admission when canonical ticket data is unsafe. */
+export declare function assertStartTicketPreflight(projectDir: string): void;
 /** Validate generated established recovery before reserving execution authority. */
 export declare function validateRecoveryArguments(args: readonly string[], projectDir: string): void;
 /** Validate persisted preparation argv without executing a command or provider. */