ai-foreman 1.7.19 → 1.7.21

package/dist/cli/status.js

@@ -6,8 +6,9 @@ import { recoverableBuildRuns } from "../buildRuns.js";
 import { WORKFLOW_DB_FILE } from "../workflowDb.js";
 import { WorkflowReader } from "../workflowReader.js";
 import { formatWorkflowIssue } from "../outcomes.js";
+import { accent, error, sanitizeTerminalText, success, warning } from "../terminalStyle.js";
 function fail(message) {
-    console.error(`foreman: ${message}`);
+    console.error(`${error("foreman:", { stream: process.stderr })} ${message}`);
     process.exit(1);
 }
 export function buildStatusCommand() {
@@ -24,6 +25,16 @@ export function runStatus(project) {
     const workflowPath = join(projectDir, WORKFLOW_DB_FILE);
     const workflow = existsSync(workflowPath) ? new WorkflowReader(projectDir, workflowPath) : undefined;
     const activeWorkflows = workflow?.activeRuns() ?? [];
+    for (const run of activeWorkflows) {
+        const preparation = workflow?.qaPreparation(run.runId);
+        if (!preparation || preparation.mode === "legacy")
+            continue;
+        console.log(`foreman: QA preparation ${preparation.mode} — ${run.runId}`);
+        const metrics = workflow.qaPreparationMetrics(run.runId);
+        console.log(`  admitted ${metrics.approved}; started ${metrics.started}; first reviews ${metrics.firstReviews}; passes ${metrics.firstReviewPasses}; unknown finding causes ${metrics.causes.unknown}`);
+        for (const work of preparation.works)
+            console.log(`  ${work.workId}: ${work.state}; depth ${work.depth ?? "assessment pending"}; contract ${work.digest ?? "unpublished"}${work.detail ? `; ${work.detail}` : ""}`);
+    }
     if (!existsSync(dir) && activeWorkflows.length === 0) {
         workflow?.close();
         fail(`no foreman runs found under ${dir}`);
@@ -52,8 +63,8 @@ export function runStatus(project) {
     const prEvents = records.filter((r) => ["pr-created", "pr-existing", "pr-failed"].includes(String(r.event)));
     const latestFailure = findLatestGitHubFailure(records);
     const batchEnd = [...records].reverse().find((r) => r.event === "batch-end");
-    console.log(`foreman: latest run ${logs[logs.length - 1]}`);
-    console.log(`foreman: ${steps.length} step record(s), ${escalations.length} escalation(s)`);
+    console.log(`${accent("foreman:")} latest run ${sanitizeTerminalText(logs[logs.length - 1] ?? "")}`);
+    console.log(`${accent("foreman:")} ${steps.length} step record(s), ${escalations.length} escalation(s)`);
     if (branchEvents.length || prEvents.length) {
         const completed = branchEvents.filter((r) => r.event === "branch-complete").length;
         const issues = branchEvents.filter((r) => r.event === "branch-issue").length;
@@ -61,12 +72,16 @@ export function runStatus(project) {
         console.log(`foreman: branch mode — ${completed} completed, ${issues} issue(s), ${prs} PR(s)`);
     }
     if (batchEnd) {
-        console.log(`foreman: outcome — ${batchEnd.outcome} (${batchEnd.completed}/${batchEnd.requested})`);
+        const outcome = sanitizeTerminalText(String(batchEnd.outcome ?? ""));
+        const styledOutcome = /success|complete|pass/i.test(outcome) ? success(outcome)
+            : /fail|error/i.test(outcome) ? error(outcome)
+                : /warn|partial|blocked/i.test(outcome) ? warning(outcome) : outcome;
+        console.log(`${accent("foreman:")} outcome — ${styledOutcome} (${batchEnd.completed}/${batchEnd.requested})`);
         if (batchEnd.detail)
             console.log(`foreman: ${batchEnd.detail}`);
     }
     else {
-        console.log("ai-foreman: run is still in progress or did not finish");
+        console.log(`${accent("ai-foreman:")} run is still in progress or did not finish`);
     }
     if (latestFailure) {
         console.log(`foreman: latest GitHub failure — ${latestFailure.code}: ${latestFailure.message}`);

package/dist/cli/tickets.js

@@ -1,4 +1,5 @@
 import { Command } from "commander";
+import { accent, error, sanitizeTerminalText, success, warning } from "../terminalStyle.js";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { parse as parseYaml } from "yaml";
@@ -1240,6 +1241,7 @@ export async function cmdPopulateCli(opts) {
         builder = roleBuilder.builder;
         viewer = printEvents(builder.events());
         const foreman = new Foreman(builder, log, { desktop: config.notifications.enabled, terminalBell: config.notifications.terminal_bell }, false, 3, dir);
+        foreman.setGraphPurpose("ticket-population");
         console.log(`foreman tickets: populating tickets with ${roleBuilder.runtime}`);
         console.log(`foreman tickets: project ${dir}`);
         console.log(`foreman tickets: role ${TICKET_POPULATE_ROLE}`);
@@ -1927,7 +1929,7 @@ export function buildTicketsCommand(options = {}) {
                 evidence: opts.evidence,
                 lastError: opts.lastError,
             });
-            console.log(`foreman tickets: updated ${ticketId}`);
+            console.log(`${accent("foreman tickets:")} updated ${sanitizeTerminalText(ticketId)}`);
         }
         catch (err) {
             fail(String(err instanceof Error ? err.message : err));
@@ -1954,7 +1956,7 @@ export function buildTicketsCommand(options = {}) {
                 evidence: opts.evidence,
                 validationNotes: opts.validationNotes,
             });
-            console.log(`foreman tickets: completed ${ticketId}`);
+            console.log(`${accent("foreman tickets:")} ${success("completed")} ${sanitizeTerminalText(ticketId)}`);
         }
         catch (err) {
             fail(String(err instanceof Error ? err.message : err));
@@ -1979,7 +1981,7 @@ export function buildTicketsCommand(options = {}) {
                 actor: opts.actor,
                 unblockCriteria: opts.unblockCriteria,
             });
-            console.log(`foreman tickets: blocked ${ticketId}`);
+            console.log(`${accent("foreman tickets:")} ${warning("blocked")} ${sanitizeTerminalText(ticketId)}`);
         }
         catch (err) {
             fail(String(err instanceof Error ? err.message : err));
@@ -1998,7 +2000,7 @@ export function buildTicketsCommand(options = {}) {
                 summary: opts.summary,
                 actor: opts.actor,
             });
-            console.log(`foreman tickets: unblocked ${ticketId}`);
+            console.log(`${accent("foreman tickets:")} ${success("unblocked")} ${sanitizeTerminalText(ticketId)}`);
         }
         catch (err) {
             fail(String(err instanceof Error ? err.message : err));
@@ -2188,10 +2190,10 @@ export function buildTicketsCommand(options = {}) {
         try {
             const result = cmdValidate(cwd(opts));
             if (result.issues.length === 0) {
-                console.log("foreman tickets: validation passed — all 4 passes clean");
+                console.log(`${accent("foreman tickets:")} ${success("validation passed")} — all 4 passes clean`);
             }
             else {
-                console.log(`foreman tickets: ${result.issues.length} issue(s) found:`);
+                console.log(`${accent("foreman tickets:")} ${error(`${result.issues.length} issue(s) found:`)}`);
                 console.log(formatValidationIssues(result.issues));
                 if (!result.clean)
                     process.exit(1);
@@ -2221,7 +2223,7 @@ export function buildTicketsCommand(options = {}) {
                         console.log(line);
                 return;
             }
-            console.log("Batches: none configured. Queue is flat.");
+            console.log(`${accent("Batches:")} none configured. Queue is flat.`);
             const rows = cmdQueue(dir, opts.limit !== undefined ? Number(opts.limit) : undefined);
             if (rows.length === 0) {
                 console.log("No remaining tickets.");

package/dist/continuity.d.ts

@@ -30,7 +30,7 @@ export declare function parseContinuityDelta(text: string): {
 };
 export declare function mergeContinuityDeltas(deltas: readonly ContinuityDelta[]): ContinuityDelta;
 export declare function baselineContinuityDelta(nextAction?: string): ContinuityDelta;
-export declare function continuityInstruction(): string;
+export declare function continuityInstruction(role?: "builder" | "qa"): string;
 export interface ContinuityAdapterOptions {
     adapter: BuilderAdapter;
     projectDir: string;
@@ -61,16 +61,30 @@ export interface ContinuityAdapterOptions {
 export declare class ContinuityAdapter implements BuilderAdapter {
     private readonly options;
     private adapter;
+    contractCapabilities(): {
+        sameSessionAcceptance: boolean;
+        nativeCompactionBarrier: boolean;
+    };
+    private contractEnforcing;
+    enableContractEnforcement(): void;
+    contractCompactionSequence(): number;
+    acceptContractDelivery(sequence: number): void;
     private readonly queue;
     private sourcePump?;
     private recoveryLeasePending;
+    private validatingFreshRecovery;
+    private readonly buildAuthority?;
     constructor(options: ContinuityAdapterOptions);
+    /** Establish an explicitly requested fresh owner before context probes or work. */
+    validateFreshRecovery(): Promise<void>;
     get agent(): "claude" | "codex";
     sendTurn(instruction: string, policy?: {
         handback?: boolean;
         responseOnly?: boolean;
         logicalActionId?: string;
+        purpose?: import("./providerPhase.js").ProviderTurnPurpose;
     }): Promise<TurnResult>;
+    private sendTurnOwned;
     observeEvents(listener: (event: import("./adapters/types.js").BuilderEvent) => void): () => void;
     acceptHandbackTurn(turn: TurnResult): void;
     sessionId(): string | undefined;
@@ -86,6 +100,7 @@ export declare class ContinuityAdapter implements BuilderAdapter {
     restoreNativeCompactions(compactions: NativeCompaction[]): void;
     contextUsageAfterNativeCompaction(compaction: NativeCompaction): Promise<ContextUsage | undefined>;
     contextUsage(): Promise<ContextUsage | undefined>;
+    graphRuntimeSettings(): Pick<import("./adapters/types.js").BuilderAdapterOptions, "model" | "effort" | "fast" | "runtimeExecutable"> | undefined;
     sessionUsage(): Promise<ProviderSessionUsage | undefined>;
     switchSettings(settings: ProviderSettingSwitch): Promise<CompactResult>;
     events(): AsyncIterable<import("./adapters/types.js").BuilderEvent>;

package/dist/continuity.js

@@ -1,3 +1,5 @@
+import { dispatchWithGraphAccess, withGraphSessionAccess } from "./graph/session.js";
+import { localBuildAuthority } from "./buildAdmission.js";
 import { randomUUID, createHash } from "node:crypto";
 import { BuilderEventQueue } from "./activity.js";
 import { providerSessionKey } from "./sessionIdentity.js";
@@ -96,10 +98,11 @@ export function mergeContinuityDeltas(deltas) {
 export function baselineContinuityDelta(nextAction = "Await the first role action.") {
     return { version: 1, decisions: [], constraints: [], discoveries: [], completedActions: [], evidence: [], failures: [], blockers: [], openWork: [], nextAction };
 }
-export function continuityInstruction() {
+export function continuityInstruction(role) {
     return [
         "Before your final STEP_STATUS line (or as the final line when STEP_STATUS is not requested), emit exactly one single-line continuity record:",
         `${CONTINUITY_MARKER} {"version":1,"decisions":[],"constraints":[],"discoveries":[],"completedActions":[],"evidence":[],"failures":[],"blockers":[],"openWork":[],"nextAction":"specific next action"}`,
+        ...(role === "qa" ? ["QA protocol: this continuity record is required even when the review requests only a report or status. Put it before RAFI_QA_FAILURE_REPORT_START when returning a failure envelope, outside the report JSON. Rafi strips the record before validating the report, so keep the report envelope immediately followed by STEP_STATUS."] : []),
         "Keep it concise and cumulative for facts learned this turn. Do not include credentials, hidden reasoning, or raw transcripts.",
     ].join("\n");
 }
@@ -107,12 +110,20 @@ export function continuityInstruction() {
 export class ContinuityAdapter {
     options;
     adapter;
+    contractCapabilities() { return this.adapter.contractCapabilities?.() ?? { sameSessionAcceptance: false, nativeCompactionBarrier: false }; }
+    contractEnforcing = false;
+    enableContractEnforcement() { this.contractEnforcing = true; this.adapter.enableContractEnforcement?.(); }
+    contractCompactionSequence() { return this.adapter.contractCompactionSequence?.() ?? 0; }
+    acceptContractDelivery(sequence) { this.adapter.acceptContractDelivery?.(sequence); }
     queue = new BuilderEventQueue();
     sourcePump;
     recoveryLeasePending;
+    validatingFreshRecovery = false;
+    buildAuthority;
     constructor(options) {
         this.options = options;
         this.adapter = options.adapter;
+        this.buildAuthority = localBuildAuthority(options.projectDir);
         this.recoveryLeasePending = Boolean(options.replaceRecoveryLeaseAfterCheckpoint);
         const db = new WorkflowDb(options.projectDir);
         try {
@@ -130,8 +141,42 @@ export class ContinuityAdapter {
         }
         this.pumpEvents();
     }
+    /** Establish an explicitly requested fresh owner before context probes or work. */
+    async validateFreshRecovery() {
+        if (!this.recoveryLeasePending)
+            return;
+        const db = new WorkflowDb(this.options.projectDir);
+        let owner;
+        try {
+            owner = db.roleMutationLease(this.options.runId, this.options.role);
+        }
+        finally {
+            db.close();
+        }
+        const current = this.adapter.sessionRef?.();
+        if (!owner || (current && owner.sessionKey === providerSessionKey(current))) {
+            this.recoveryLeasePending = false;
+            return;
+        }
+        this.validatingFreshRecovery = true;
+        try {
+            const result = await this.sendTurn("Fresh recovery validation only. Do not use tools, change files, implement work, or request a handoff. Acknowledge this new session and emit the required continuity record using only the supplied instructions.", { responseOnly: true });
+            if (result.isError || result.failure || this.recoveryLeasePending)
+                throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "fresh recovery did not establish a valid continuity checkpoint");
+        }
+        catch (error) {
+            await this.close().catch(() => { });
+            throw error;
+        }
+        finally {
+            this.validatingFreshRecovery = false;
+        }
+    }
     get agent() { return this.adapter.agent; }
     async sendTurn(instruction, policy) {
+        return withGraphSessionAccess(this.options.projectDir, this.adapter, () => this.sendTurnOwned(instruction, policy));
+    }
+    async sendTurnOwned(instruction, policy) {
         const db = new WorkflowDb(this.options.projectDir);
         try {
             db.appendContinuityEvent({ runId: this.options.runId, role: "host", kind: "turn_started", payload: { role: this.options.role, instructionDigest: sha(instruction), instructionBytes: Buffer.byteLength(instruction) }, authoritativeStateRevision: this.revision() });
@@ -139,12 +184,16 @@ export class ContinuityAdapter {
         finally {
             db.close();
         }
-        const providerInstruction = `${instruction}\n\n${continuityInstruction()}`;
+        const providerInstruction = `${instruction}\n\n${continuityInstruction(this.options.role)}`;
         const journal = new WorkflowDb(this.options.projectDir);
         const dispatchId = `dispatch:${this.options.runId}:${this.options.role}:${randomUUID()}`;
         let original;
         try {
             journal.atomic(() => {
+                if (this.buildAuthority)
+                    journal.assertBuildAdmission(this.buildAuthority);
+                else if (journal.buildAdmission())
+                    throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "dispatch requires original build admission authority");
                 if (process.send && process.env.RAFI_BUILD_WORKER_RUN === this.options.runId) {
                     const supervisor = journal.supervisorState(this.options.runId);
                     if (!process.connected || supervisor?.status !== "running" || supervisor.workerGeneration !== Number(process.env.RAFI_BUILD_WORKER_GENERATION))
@@ -153,7 +202,7 @@ export class ContinuityAdapter {
                 const owner = journal.roleMutationLease(this.options.runId, this.options.role);
                 const ref = this.adapter.sessionRef?.();
                 const session = ref?.sessionId ?? this.adapter.sessionId();
-                if (owner && session && (owner.providerSessionId !== session || (owner.sessionKey && ref && owner.sessionKey !== providerSessionKey(ref)))) {
+                if (!(this.validatingFreshRecovery && this.recoveryLeasePending && policy?.responseOnly) && owner && session && (owner.providerSessionId !== session || (owner.sessionKey && ref && owner.sessionKey !== providerSessionKey(ref)))) {
                     throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "provider session no longer owns role dispatch authority");
                 }
                 if (journal.unresolvedRoleDispatches(this.options.runId, this.options.role).length)
@@ -162,7 +211,7 @@ export class ContinuityAdapter {
                 journal.updateOperation(dispatchId, "in_progress");
             });
             try {
-                original = await this.adapter.sendTurn(providerInstruction, policy);
+                original = await dispatchWithGraphAccess(this.options.projectDir, this.adapter, providerInstruction, policy, (text, p) => this.adapter.sendTurn(text, p));
             }
             catch (error) {
                 journal.updateOperation(dispatchId, "uncertain", { error: String(error) });
@@ -203,7 +252,7 @@ export class ContinuityAdapter {
         if (parsed.delta && !original.isError && !original.failure) {
             this.publish(parsed.delta, "turn_completed", original);
             this.moveRecoveryLeaseAfterCheckpoint();
-            if (this.options.durableSingleTurn) {
+            if (this.options.durableSingleTurn || this.validatingFreshRecovery) {
                 return { ...original, text: parsed.cleanText, hostInstruction: instruction, providerInstruction: original.providerInstruction ?? providerInstruction,
                     rawResponse: original.rawResponse ?? original.text, cleanedResponse: parsed.cleanText };
             }
@@ -213,12 +262,12 @@ export class ContinuityAdapter {
                 return this.sendTurn([
                     "Continue the frozen action after the accepted Rafi handoff. Do not repeat completed side effects.",
                     instruction,
-                ].join("\n\n"));
+                ].join("\n\n"), policy);
             }
             return { ...original, text: parsed.cleanText, hostInstruction: instruction, providerInstruction: original.providerInstruction ?? providerInstruction,
                 rawResponse: original.rawResponse ?? original.text, cleanedResponse: parsed.cleanText };
         }
-        if (this.options.durableSingleTurn) {
+        if (this.options.durableSingleTurn || (this.validatingFreshRecovery && this.recoveryLeasePending && policy?.responseOnly)) {
             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() });
@@ -226,7 +275,7 @@ export class ContinuityAdapter {
             finally {
                 invalidDb.close();
             }
-            return { ...original, isError: true, text: `QA continuity record was invalid: ${parsed.error?.problems.join("; ") ?? "unknown error"}`,
+            return { ...original, isError: true, continuityErrors: parsed.error?.problems ?? ["unknown continuity error"], 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 };
         }
@@ -240,12 +289,12 @@ export class ContinuityAdapter {
         finally {
             budget.close();
         }
-        const repair = await this.adapter.sendTurn([
+        const repair = await dispatchWithGraphAccess(this.options.projectDir, this.adapter, [
             "Continuity protocol repair only. Do not run tools, repeat work, or change files.",
             `Your prior turn's continuity record was invalid: ${parsed.error?.problems.join("; ")}.`,
             continuityInstruction(),
             "Return only the continuity record.",
-        ].join("\n"), { ...policy, responseOnly: true });
+        ].join("\n"), { ...policy, purpose: "response-repair", responseOnly: true }, (text, p) => this.adapter.sendTurn(text, p));
         const repaired = parseContinuityDelta(repair.text);
         if (repaired.delta && !repair.isError && !repair.failure) {
             this.publish(repaired.delta, "turn_completed_after_repair", original);
@@ -253,7 +302,7 @@ export class ContinuityAdapter {
             const successor = await this.options.handleHandoffRequest?.(original.text, this.adapter, instruction);
             if (successor && successor !== this.adapter) {
                 await this.adoptValidatedSuccessor(successor);
-                return this.sendTurn(["Continue the frozen action after the accepted Rafi handoff. Do not repeat completed side effects.", instruction].join("\n\n"));
+                return this.sendTurn(["Continue the frozen action after the accepted Rafi handoff. Do not repeat completed side effects.", instruction].join("\n\n"), policy);
             }
             return { ...original, text: parsed.cleanText, hostInstruction: instruction, providerInstruction: original.providerInstruction ?? providerInstruction,
                 rawResponse: original.rawResponse ?? original.text, cleanedResponse: parsed.cleanText };
@@ -290,7 +339,7 @@ export class ContinuityAdapter {
         if (!this.options.createSuccessor)
             throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "continuity repair failed in the original session and no validated successor is configured");
         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 accepted = await dispatchWithGraphAccess(this.options.projectDir, successor, `${handoff}\n\nReply with HANDOFF_ACCEPTED on the first line, then ${continuityInstruction()}`, { purpose: "contract-acceptance", responseOnly: true }, (text, p) => successor.sendTurn(text, p));
         const successorDelta = parseContinuityDelta(accepted.text);
         const firstAcceptanceLine = accepted.text.split(/\r?\n/).map((line) => line.trim()).find(Boolean);
         if (firstAcceptanceLine !== "HANDOFF_ACCEPTED" || !successorDelta.delta || !successor.sessionId()) {
@@ -338,12 +387,19 @@ export class ContinuityAdapter {
     restoreNativeCompactions(compactions) { this.adapter.restoreNativeCompactions?.(compactions); }
     contextUsageAfterNativeCompaction(compaction) { return this.adapter.contextUsageAfterNativeCompaction?.(compaction) ?? Promise.resolve(undefined); }
     contextUsage() { return this.adapter.contextUsage?.() ?? Promise.resolve(undefined); }
+    graphRuntimeSettings() { return this.adapter.graphRuntimeSettings?.(); }
     sessionUsage() { return this.adapter.sessionUsage?.() ?? Promise.resolve(undefined); }
     switchSettings(settings) { return this.adapter.switchSettings ? this.adapter.switchSettings(settings) : Promise.resolve({ ok: false, error: "provider adapter does not support settings changes" }); }
     events() { return this.queue; }
     async close() { await this.adapter.close(); await this.sourcePump?.catch(() => { }); this.queue.close(); }
     /** Keep the observable wrapper and event stream stable while moving to an accepted successor. */
     async adoptValidatedSuccessor(successor) {
+        if (this.contractEnforcing) {
+            successor.enableContractEnforcement?.();
+            if (successor !== this.adapter)
+                await successor.close().catch(() => { });
+            throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "Replacement Builder requires host contract delivery before any continuation; completed turn must be reconciled without automatic replay");
+        }
         if (successor === this.adapter)
             return;
         const prior = this.adapter;

package/dist/foreman.d.ts

@@ -1,3 +1,4 @@
+import type { GraphPurpose } from "rafi-spec";
 import type { BuilderAdapter, PermissionHandler, PermissionRequest, TurnResult } from "./adapters/types.js";
 import type { PermissionPolicy } from "./permissions/policy.js";
 import { type AnsweredProviderQuestion } from "./providerQuestions.js";
@@ -85,19 +86,25 @@ export declare class Foreman {
     /** Exact durable build-run scope. Observability is never an identity authority. */
     private readonly qaRunId;
     private readonly continueIndependentTickets;
+    private readonly builderWorktree?;
+    private readonly decisionPrompt?;
+    private graphPurpose;
+    setGraphPurpose(purpose: GraphPurpose): void;
     private readonly ticketsEnabled;
     private readonly notificationsEnabled;
     private readonly terminalBellEnabled;
     private readonly qaStream;
     private builderWorkSessions;
     private currentTicketId?;
+    private preflightPlan;
+    approvedPlanText(): string;
     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<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, 
     /** Exact durable build-run scope. Observability is never an identity authority. */
-    qaRunId?: string, continueIndependentTickets?: boolean, initialTicketId?: string);
+    qaRunId?: string, continueIndependentTickets?: boolean, initialTicketId?: string, builderWorktree?: string | undefined, decisionPrompt?: ((decision: import("rafi-spec").PendingHumanDecision) => Promise<string | undefined>) | undefined);
     private waitForUserInput;
     /**
      * Send one instruction and resolve any needs_input exchanges before returning.
@@ -106,8 +113,9 @@ export declare class Foreman {
     private doTurn;
     private prepareBuilderBoundary;
     private doTurnWith;
+    private doTurnWithOwned;
     /** Send a planning turn and return the builder's response text. Does not count toward steps. */
-    runPreflight(n: number, ticketsContent?: string, preferredTicketId?: string): Promise<string>;
+    runPreflight(n: number, ticketsContent?: string, preferredTicketId?: string, executionTickets?: readonly string[]): Promise<string>;
     /** Send user feedback on the plan; builder responds with a revised list. Does not count toward steps. */
     sendPreflightFeedback(feedback: string): Promise<void>;
     /** Send one custom instruction through the same needs_input loop as a batch turn. */
@@ -140,7 +148,7 @@ export declare class Foreman {
         passCertificateId?: string;
         sourceStateDigest?: string;
     }>;
-    /** Complete only the pending QA boundary and its tracker transition. No Builder work turn is sent. */
+    /** Resume the pending boundary, including authorized waiting guidance, then complete its tracker transition. */
     completePendingQaRecovery(ticketId: string): Promise<{
         outcome: "passed" | "blocked" | "needs-human" | "waived";
         detail?: string;
@@ -153,5 +161,5 @@ export declare class Foreman {
     builderAdapter(): BuilderAdapter;
     close(): Promise<void>;
     private ticketForQa;
-    runBatch(n: number, trackerPath?: string, onTicketStart?: (ticketId: string) => void | Promise<void>, preferredTicketId?: string): Promise<BatchResult>;
+    runBatch(n: number, trackerPath?: string, onTicketStart?: (ticketId: string) => void | Promise<void>, preferredTicketId?: string, recoveryTickets?: readonly string[]): Promise<BatchResult>;
 }