ai-foreman 1.7.20 → 1.7.21

package/dist/agentRun.d.ts

@@ -1,3 +1,4 @@
+export { withGraphDerivedAccess } from "./graph/derived.js";
 import { type PermissionConfig } from "./config.js";
 import { Log } from "./log.js";
 import { type StepStatus } from "./foreman.js";
@@ -6,10 +7,13 @@ import type { AnsweredProviderQuestion } from "./providerQuestions.js";
 import { type RoleBundle } from "./roles.js";
 import type { AgentRuntime } from "./runtimeAuth.js";
 import type { AgentRoleDefaultsV1, ProviderSessionRefV1 } from "rafi-spec";
+import type { GraphPurpose } from "rafi-spec";
 export type { EffortLevel } from "./adapters/types.js";
 export declare const VALID_EFFORT: readonly EffortLevel[];
 export interface RoleBuilderOptions {
+    graphPurpose?: GraphPurpose;
     projectDir: string;
+    configRoot?: string;
     role: string;
     agent?: string;
     model?: string;
@@ -21,6 +25,7 @@ export interface RoleBuilderOptions {
     log?: Log;
     permissionConfig?: PermissionConfig;
     extraSkills?: string[];
+    preloadedSkillContent?: BuilderAdapterOptions["preloadedSkillContent"];
     sandboxMode?: BuilderAdapterOptions["sandboxMode"];
     /** Disable recovery-session persistence for isolated, non-recoverable roles such as Manager. */
     persistSessionBindings?: boolean;
@@ -33,6 +38,7 @@ export interface RoleBuilderOptions {
     onProviderQuestion?: (request: import("./adapters/types.js").PermissionRequest) => void;
 }
 export interface RoleBuilder {
+    graphRoot?: string;
     builder: BuilderAdapter;
     runtime: AgentRuntime;
     model?: string;
@@ -65,5 +71,6 @@ export declare function makeLogPath(projectDir: string, label: string): string;
 export declare function mergeSkills(roleSkills: readonly string[], extraSkills?: readonly string[]): string[];
 export declare function readOnlyPermissionConfig(): PermissionConfig;
 export declare function createRoleBuilder(opts: RoleBuilderOptions): Promise<RoleBuilder>;
+export declare function sendRoleGraphTurn(role: RoleBuilder, instruction: string, purpose: GraphPurpose, policy?: Parameters<BuilderAdapter["sendTurn"]>[1]): Promise<TurnResult>;
 export declare function readRoleDefaultsForExecution(projectDir: string, role: string): AgentRoleDefaultsV1 | undefined;
 export declare function runRoleInstruction(opts: RoleInstructionRunOptions): Promise<RoleInstructionRunResult>;

package/dist/agentRun.js

@@ -1,3 +1,4 @@
+export { withGraphDerivedAccess } from "./graph/derived.js";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { loadConfig, DEFAULT_CONFIG } from "./config.js";
@@ -15,6 +16,7 @@ import { resolveAgentForProject } from "./cli/runtimeSelection.js";
 import { parse as parseYaml } from "yaml";
 import { captureWorkspaceIdentity, createProviderSessionRef, resolveUniqueSessionBinding } from "./sessionIdentity.js";
 import { WorkflowDb } from "./workflowDb.js";
+import { graphContext, sendGraphTurn } from "./graph/turn.js";
 export const VALID_EFFORT = ["low", "medium", "high", "xhigh"];
 export function assertEffortLevel(effort) {
     if (effort && !VALID_EFFORT.includes(effort)) {
@@ -107,13 +109,14 @@ export async function createRoleBuilder(opts) {
     if (!existsSync(opts.projectDir)) {
         throw new Error(`project directory not found: ${opts.projectDir}`);
     }
-    const saved = readRoleDefaultsForExecution(opts.projectDir, opts.role);
+    const executionRoot = opts.configRoot ?? opts.projectDir;
+    const saved = readRoleDefaultsForExecution(executionRoot, opts.role);
     if (opts.resumeSessionRef && opts.resumeSessionId && opts.resumeSessionRef.sessionId !== opts.resumeSessionId) {
         throw new Error("resume session ID does not match the supplied location-scoped reference");
     }
     let requestedResumeRef = opts.resumeSessionRef;
     if (!requestedResumeRef && opts.resumeSessionId) {
-        const bindingDb = new WorkflowDb(opts.projectDir);
+        const bindingDb = new WorkflowDb(executionRoot);
         try {
             requestedResumeRef = resolveUniqueSessionBinding(bindingDb.providerSessionBindings(opts.resumeSessionId), opts.resumeSessionId);
         }
@@ -124,19 +127,19 @@ export async function createRoleBuilder(opts) {
     const configuredEffort = saved?.reasoning && saved.reasoning !== "default" ? saved.reasoning : undefined;
     const effectiveEffort = opts.effort ?? (VALID_EFFORT.includes(configuredEffort) ? configuredEffort : undefined);
     assertEffortLevel(effectiveEffort);
-    let runtime = resolveAgentForProject(opts.projectDir, opts.agent ?? requestedResumeRef?.provider ?? saved?.make);
+    let runtime = resolveAgentForProject(executionRoot, opts.agent ?? requestedResumeRef?.provider ?? saved?.make);
     if (requestedResumeRef && requestedResumeRef.provider !== runtime) {
         throw new Error(`session ${requestedResumeRef.sessionId} belongs to ${requestedResumeRef.provider}, but ${runtime} was selected`);
     }
     if (requestedResumeRef && requestedResumeRef.role !== configurableRole(opts.role)) {
         throw new Error(`session ${requestedResumeRef.sessionId} belongs to role ${requestedResumeRef.role}, not ${configurableRole(opts.role)}`);
     }
-    const config = loadConfig(join(opts.projectDir, "foreman.yaml"));
-    const log = opts.log ?? new Log(makeLogPath(opts.projectDir, opts.label.replace(/\s+/g, "-")));
-    const roleBundle = loadRoleBundle(opts.role, { projectDir: opts.projectDir });
+    const config = loadConfig(join(executionRoot, "foreman.yaml"));
+    const log = opts.log ?? new Log(makeLogPath(executionRoot, opts.label.replace(/\s+/g, "-")));
+    const roleBundle = loadRoleBundle(opts.role, { projectDir: opts.configRoot ?? opts.projectDir });
     const initialModel = opts.model ?? (saved?.model !== "default" ? saved?.model : undefined) ?? roleBundle.model ?? undefined;
     const effort = effectiveEffort ?? roleBundle.effort ?? undefined;
-    const ready = await ensureRuntimeReadyForCommand(opts.projectDir, runtime, {
+    const ready = await ensureRuntimeReadyForCommand(executionRoot, runtime, {
         label: opts.label,
         yes: Boolean(opts.yes),
         allowSwitch: requestedResumeRef || opts.resumeSessionId ? false : opts.allowSwitch,
@@ -151,7 +154,7 @@ export async function createRoleBuilder(opts) {
     const makeAdapter = async (nextRuntime, resumeSessionId, resumeSessionRef) => {
         let scopedRef = resumeSessionRef;
         if (!scopedRef && resumeSessionId) {
-            const bindingDb = new WorkflowDb(opts.projectDir);
+            const bindingDb = new WorkflowDb(executionRoot);
             try {
                 scopedRef = resolveUniqueSessionBinding(bindingDb.providerSessionBindings(resumeSessionId), resumeSessionId);
             }
@@ -165,7 +168,7 @@ export async function createRoleBuilder(opts) {
                 stream: opts.role,
                 generation: 0,
                 cwd: opts.projectDir,
-                configRoot: opts.projectDir,
+                configRoot: opts.configRoot ?? opts.projectDir,
                 workspaceIdentity: captureWorkspaceIdentity(opts.projectDir),
                 source: "legacy-inferred",
             });
@@ -175,7 +178,7 @@ export async function createRoleBuilder(opts) {
         }
         const adapterOpts = {
             cwd: opts.projectDir,
-            configRoot: opts.projectDir,
+            configRoot: opts.configRoot ?? opts.projectDir,
             runtimeExecutable,
             runtimePhase: phaseForRole(opts.role),
             onQuestionTrace: (trace) => log.write("question-round-trip", { ...trace }),
@@ -196,6 +199,7 @@ export async function createRoleBuilder(opts) {
             sandboxMode: opts.sandboxMode,
             systemPromptAppend: roleBundle.system || undefined,
             skills: skills.length > 0 ? skills : undefined,
+            preloadedSkillContent: opts.preloadedSkillContent,
         };
         const adapter = nextRuntime === "codex"
             ? new CodexAdapter(adapterOpts)
@@ -221,7 +225,7 @@ export async function createRoleBuilder(opts) {
     const persistSessionRef = (ref) => {
         if (opts.persistSessionBindings === false)
             return;
-        const bindingDb = new WorkflowDb(opts.projectDir);
+        const bindingDb = new WorkflowDb(executionRoot);
         try {
             bindingDb.recordProviderSessionBinding(ref);
         }
@@ -239,7 +243,7 @@ export async function createRoleBuilder(opts) {
         enabled: interactive,
         allowSwitch: opts.allowSwitch !== false && !opts.resumeSessionId && !requestedResumeRef,
         recreate: async (nextRuntime, resumeSessionId, resumeSessionRef) => {
-            const nextReady = await ensureRuntimeReadyForCommand(opts.projectDir, nextRuntime, {
+            const nextReady = await ensureRuntimeReadyForCommand(executionRoot, nextRuntime, {
                 label: opts.label,
                 allowSwitch: false,
                 model: nextRuntime === runtime ? model : undefined,
@@ -251,7 +255,13 @@ export async function createRoleBuilder(opts) {
         },
         onSessionRef: persistSessionRef,
     });
-    return { builder, runtime, model, effort, roleBundle, skills, log };
+    return { builder, runtime, model, effort, roleBundle, skills, log, graphRoot: opts.configRoot ?? opts.projectDir };
+}
+export function sendRoleGraphTurn(role, instruction, purpose, policy) {
+    const root = role.graphRoot;
+    if (!root)
+        return role.builder.sendTurn(instruction, policy);
+    return sendGraphTurn(role.builder, instruction, graphContext(root, role.builder.sessionRef?.()?.cwd ?? root, purpose, instruction), policy);
 }
 function phaseForRole(role) {
     if (role === "planner")
@@ -322,6 +332,7 @@ export async function runRoleInstruction(opts) {
     const viewer = printEvents(builder.events());
     const config = loadConfig(join(opts.projectDir, "foreman.yaml"));
     const foreman = new Foreman(builder, log, { desktop: config.notifications.enabled, terminalBell: config.notifications.terminal_bell }, false, 3, opts.projectDir);
+    foreman.setGraphPurpose(opts.graphPurpose ?? { planner: "planning", discovery: "discovery", "ticket-maker": "ticket-population", uninstaller: "uninstall-analysis" }[opts.role] ?? "implementation");
     try {
         const turn = await foreman.runInstruction(opts.instruction);
         await builder.close();

package/dist/branch/currentGuard.d.ts

@@ -34,6 +34,7 @@ export declare class CurrentWorkflowGuardAdapter 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<BuilderEvent>;

package/dist/branch/currentGuard.js

@@ -63,6 +63,7 @@ export class CurrentWorkflowGuardAdapter {
     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?.(settings) ?? Promise.resolve({ ok: false, error: "settings switch unavailable" }); }
     events() { return this.adapter.events(); }

package/dist/branch/finalization.js

@@ -1,3 +1,4 @@
+import { graphCheckoutBoundary } from "./git.js";
 import { currentWorktreeBranch, findWorktreeForBranch, hasWorktreeChanges, mergeBranchToLocalBase, runGit } from "./git.js";
 import { captureProspectiveGitTree } from "../qaSnapshot.js";
 export class DirectMergeSourceChangedError extends Error {
@@ -75,6 +76,7 @@ export function removeDirectMergeWorktree(projectDir, intent, worktree) {
     verifyDirectMergeWorktree(projectDir, intent);
     // Let Git reject edits made even after the preceding verification. Never
     // force-remove or recursively delete a finalization worktree on failure.
+    graphCheckoutBoundary(projectDir, worktree, "worktree-removed");
     runGit(projectDir, ["worktree", "remove", worktree]);
 }
 export function hasExactStagedDirectMerge(projectDir, intent) {
@@ -95,8 +97,10 @@ export function hasExactStagedDirectMerge(projectDir, intent) {
 }
 export function executeDirectMerge(projectDir, intent, message) {
     const completed = reconcileDirectMerge(projectDir, intent);
-    if (completed)
+    if (completed) {
+        graphCheckoutBoundary(projectDir, projectDir, "merge-or-rebase");
         return completed;
+    }
     verifyDirectMergeWorktree(projectDir, intent);
     const indexTree = runGit(projectDir, ["write-tree"]).stdout;
     const baseTree = runGit(projectDir, ["rev-parse", `${intent.baseCommit}^{tree}`]).stdout;
@@ -107,6 +111,7 @@ export function executeDirectMerge(projectDir, intent, message) {
         // Git prepared the merge before the host crashed, but commit did not.
         // Only commit the exact tree frozen in the durable intent.
         runGit(projectDir, ["commit", "-m", message]);
+        graphCheckoutBoundary(projectDir, projectDir, "merge-or-rebase");
     }
     else {
         // Squash/merge publish the immutable source commit, even if an external

package/dist/branch/git.d.ts

@@ -16,6 +16,7 @@ export declare function ensureCleanBaseWorktree(cwd: string, opts?: BaseWorktree
 export declare function ensureForemanExcluded(cwd: string): void;
 export declare function createTicketWorktree(projectDir: string, runId: string, branch: string, base: string): string;
 export declare function findWorktreeForBranch(projectDir: string, branch: string): string | undefined;
+export declare function graphCheckoutBoundary(projectDir: string, workspace: string, reason: "merge-or-rebase" | "worktree-created" | "worktree-removed"): void;
 export declare function removeTicketWorktree(projectDir: string, worktreePath: string): void;
 export declare function currentWorktreeBranch(worktreePath: string): string;
 export declare function hasTrackerChanges(worktreePath: string, paths?: {

package/dist/branch/git.js

@@ -1,3 +1,4 @@
+import { invalidateGraphWorkspace } from "../graph/lifecycle.js";
 import { execFileSync } from "node:child_process";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -52,6 +53,7 @@ export function createTicketWorktree(projectDir, runId, branch, base) {
     const worktreePath = join(projectDir, ".foreman", "worktrees", runId, branch.replace(/\//g, "__"));
     mkdirSync(dirname(worktreePath), { recursive: true });
     runGit(projectDir, ["worktree", "add", "-b", branch, worktreePath, base]);
+    graphCheckoutBoundary(projectDir, worktreePath, "worktree-created");
     return worktreePath;
 }
 export function findWorktreeForBranch(projectDir, branch) {
@@ -67,7 +69,16 @@ export function findWorktreeForBranch(projectDir, branch) {
     }
     return undefined;
 }
+export function graphCheckoutBoundary(projectDir, workspace, reason) {
+    try {
+        invalidateGraphWorkspace(projectDir, workspace, reason);
+    }
+    catch (error) {
+        console.error(`rafi graph: checkout metadata invalidation failed: ${String(error)}`);
+    }
+}
 export function removeTicketWorktree(projectDir, worktreePath) {
+    graphCheckoutBoundary(projectDir, worktreePath, "worktree-removed");
     try {
         runGit(projectDir, ["worktree", "remove", "--force", worktreePath]);
     }
@@ -120,8 +131,10 @@ export function pushBranch(worktreePath, branch) {
 export function mergeBranchToLocalBase(projectDir, branch, baseBranch, message, method = "squash") {
     if (method === "rebase") {
         const branchWorktree = findWorktreeForBranch(projectDir, branch);
-        if (branchWorktree)
+        if (branchWorktree) {
             runGit(branchWorktree, ["rebase", baseBranch]);
+            graphCheckoutBoundary(projectDir, branchWorktree, "merge-or-rebase");
+        }
         else
             runGit(projectDir, ["rebase", baseBranch, branch]);
     }
@@ -140,6 +153,7 @@ export function mergeBranchToLocalBase(projectDir, branch, baseBranch, message,
     else {
         runGit(projectDir, ["merge", "--ff-only", branch]);
     }
+    graphCheckoutBoundary(projectDir, projectDir, "merge-or-rebase");
     return runGit(projectDir, ["rev-parse", "--short", "HEAD"]).stdout;
 }
 /** Compatibility export for callers compiled against the older helper. */

package/dist/branch/runner.d.ts

@@ -79,8 +79,10 @@ export declare function runBranchPlan(opts: BranchRunnerOptions): Promise<Branch
 export declare function buildBranchTicketInstruction(node: BranchPlanNode, trackerPaths?: {
     progressDoc?: string;
     archiveDoc?: string;
+    validationChecklist?: string[];
 }): string;
 export declare function buildBranchTicketResumeInstruction(node: BranchPlanNode, trackerPaths?: {
     progressDoc?: string;
     archiveDoc?: string;
+    validationChecklist?: string[];
 }): string;

package/dist/branch/runner.js

@@ -1,3 +1,8 @@
+import { renderBuildWorkContext } from "../buildWorkContext.js";
+import { loadTicketSetupConfigWithDefaults } from "../tickets/setupConfig.js";
+import { deliverBuilderGuidanceFollowup } from "../builderGuidanceFollowup.js";
+import { qaDigest } from "../qaProtocolV2.js";
+import { loadTickets } from "../tickets/ticketLoader.js";
 import { formatRecoveryCommand } from "../recoveryGuidance.js";
 import { WorkflowReader } from "../workflowReader.js";
 import { buildScopeRevision } from "../buildApproval.js";
@@ -15,6 +20,7 @@ import { checkGitLabMrMerged, createOrReuseMr, enableGitLabAutoMerge, pushBranch
 import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 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 { SessionUnavailableContinuityError } from "../continuity.js";
@@ -46,6 +52,7 @@ function deliverySessionPath(projectDir, unitId) {
     return join(projectDir, ".foreman", "delivery-sessions", `${unitId}.json`);
 }
 export async function runBranchPlan(opts) {
+    assertBuildAssignmentReconciled(opts.projectDir, opts.runId);
     let qaResumedRecovery = opts.qaResumedRecovery;
     if (qaResumedRecovery) {
         const matches = opts.plan.nodes.filter((node) => node.ticket.id === qaResumedRecovery.manifest.ticketId);
@@ -165,6 +172,15 @@ export async function runBranchPlan(opts) {
         const commitOperation = finalizationOperationKey(protocolDb, opts.runId, node.ticket.id, "commit");
         const completionOperation = finalizationOperationKey(protocolDb, opts.runId, node.ticket.id, "ticket-complete");
         let completedDirectMerge = finalizationRecovery ? protocolDb.operation(directMergeOperation) : undefined;
+        try {
+            if (finalizationRecovery)
+                protocolDb.assertFinalizationControls(opts.runId, node.ticket.id);
+        }
+        catch (error) {
+            protocolDb.close();
+            summaries.push(summaryFor(node, "needs-human", error instanceof Error ? error.message : String(error)));
+            continue;
+        }
         if (completedDirectMerge?.status === "in_progress") {
             try {
                 const intent = readDirectMergeIntent(completedDirectMerge.intent);
@@ -271,6 +287,13 @@ export async function runBranchPlan(opts) {
                 continue;
             }
         }
+        const admissionDb = new WorkflowDb(opts.projectDir);
+        try {
+            admissionDb.assertAdmittedWork(opts.runId, node.ticket.id);
+        }
+        finally {
+            admissionDb.close();
+        }
         opts.log.write("branch-start", {
             ticket: node.ticket.id,
             branch: node.branch,
@@ -308,7 +331,7 @@ export async function runBranchPlan(opts) {
                         summary: resumeSession ? `Resuming branch ${node.branch}` : `Starting branch ${node.branch}`,
                     });
                 });
-            let ticketInstruction = resumeSession ? buildBranchTicketResumeInstruction(node, opts.trackerPaths) : buildBranchTicketInstruction(node, opts.trackerPaths);
+            let ticketInstruction = resumeSession ? buildBranchTicketResumeInstruction(node, { ...opts.trackerPaths, validationChecklist: loadTicketSetupConfigWithDefaults(opts.projectDir).build.validation_checklist }) : buildBranchTicketInstruction(node, { ...opts.trackerPaths, validationChecklist: loadTicketSetupConfigWithDefaults(opts.projectDir).build.validation_checklist });
             if (continuations.length)
                 ticketInstruction += "\n\nScoped answers authorizing this ticket continuation:\n" + continuations.map(decision => `${decision.prompt}\nAnswer: ${decision.answer ?? decision.selectedChoiceId}`).join("\n");
             // Reattach the predecessor even for a `fresh` strategy so the host can
@@ -337,7 +360,7 @@ export async function runBranchPlan(opts) {
             if (!qaOnlyRecovery)
                 builderWorkSessions += 1;
             viewer = opts.observeBuilder?.(builder);
-            const foreman = new Foreman(builder, opts.log, { desktop: opts.notificationsEnabled, terminalBell: opts.terminalBellEnabled ?? true }, opts.qaEnabled, 3, opts.projectDir, undefined, undefined, opts.qaSessionStrategy ?? "compact", undefined, opts.builderSessionStrategy ?? "compact", undefined, opts.beforeBuilderTurn ? (adapter, action) => opts.beforeBuilderTurn(adapter, action, worktreePath) : undefined, undefined, undefined, undefined, async (adapter) => opts.observeBuilderNativeCompactions?.(adapter, worktreePath), opts.observer, undefined, false, undefined, undefined, opts.runId, opts.continueIndependentTickets ?? true, node.ticket.id);
+            const foreman = new Foreman(builder, opts.log, { desktop: opts.notificationsEnabled, terminalBell: opts.terminalBellEnabled ?? true }, opts.qaEnabled, 3, opts.projectDir, undefined, opts.createQa, opts.qaSessionStrategy ?? "compact", undefined, opts.builderSessionStrategy ?? "compact", undefined, opts.beforeBuilderTurn ? (adapter, action) => opts.beforeBuilderTurn(adapter, action, worktreePath) : undefined, undefined, undefined, undefined, async (adapter) => opts.observeBuilderNativeCompactions?.(adapter, worktreePath), opts.observer, undefined, false, undefined, undefined, opts.runId, opts.continueIndependentTickets ?? true, node.ticket.id, worktreePath);
             const turn = async () => {
                 const db = new WorkflowDb(opts.projectDir);
                 try {
@@ -450,6 +473,54 @@ export async function runBranchPlan(opts) {
                     observeNativeCompactions: opts.observeQaNativeCompactions,
                     resolveBlocked: (adapter, reason) => foreman.resolveBlocker(adapter, reason, "qa"),
                     evidence: (entry) => opts.log.write("qa-evidence", { ticket: node.ticket.id, ...entry }),
+                    resumeBuilderGuidance: qaOnlyRecovery,
+                    deliverBuilderFollowup: (instruction, followup) => deliverBuilderGuidanceFollowup({ projectDir: opts.projectDir, runId: opts.runId, ticketId: node.ticket.id, worktree: worktreePath }, instruction, followup, {
+                        prepare: async (instruction) => {
+                            if (!builder)
+                                throw new Error("Builder session unavailable");
+                            const strategy = opts.builderSessionStrategy ?? "compact";
+                            if (opts.builderSessionBoundary)
+                                builder = await opts.builderSessionBoundary(builder, instruction, strategy, worktreePath);
+                            else if (strategy === "fresh") {
+                                await builder.close();
+                                builder = await opts.createBuilder(worktreePath);
+                            }
+                            else if (builder.sessionId()) {
+                                const compacted = await compactWithRetry(builder);
+                                if (!compacted.ok) {
+                                    await builder.close();
+                                    builder = await opts.createBuilder(worktreePath);
+                                }
+                            }
+                            if (opts.beforeBuilderTurn)
+                                builder = await opts.beforeBuilderTurn(builder, instruction, worktreePath);
+                            return builder;
+                        },
+                        validateRequirements: () => {
+                            const current = loadTickets(resolveTicketPaths(loadTicketsConfig(opts.projectDir), opts.projectDir).tickets).find(ticket => ticket.id === node.ticket.id);
+                            if (!current || qaDigest("admitted-requirements", current) !== followup.requirementsDigest)
+                                throw new BuildAssignmentRejected("Ticket requirements changed during session preparation; renewed scope approval is required");
+                        },
+                        recordSession: adapter => {
+                            const sessionId = adapter.sessionId(), sessionRef = adapter.sessionRef?.();
+                            if (!sessionId)
+                                return;
+                            builderStream = { sessionId, ...(sessionRef ? { sessionRef } : {}), worktreePath };
+                            const db = new WorkflowDb(opts.projectDir);
+                            try {
+                                db.recordBranchResumeSession(opts.runId, { ticket: node.ticket.id, branch: node.branch, base: node.baseBranch, worktreePath, sessionId, sessionRef, logPath: "structured-recovery", deliveryUnitId: node.deliveryUnitId });
+                            }
+                            finally {
+                                db.close();
+                            }
+                            opts.recordBuilderSession?.(sessionRef ?? sessionId, node.ticket.id, worktreePath);
+                        },
+                        completed: async (operationId, adapter) => {
+                            builderWorkSessions += 1;
+                            await opts.observeBuilderNativeCompactions?.(adapter, worktreePath);
+                            opts.log.write("qa-fix", { kind: "builder-guidance-followup", ticket: node.ticket.id, operationId });
+                        },
+                    }),
                     deliverFailure: async (request) => {
                         if (!builder)
                             return { ok: false, detail: "Builder session unavailable" };
@@ -530,6 +601,13 @@ export async function runBranchPlan(opts) {
                     isError: false,
                 });
             }
+            const finalControlsDb = new WorkflowDb(opts.projectDir);
+            try {
+                finalControlsDb.assertFinalizationControls(opts.runId, node.ticket.id);
+            }
+            finally {
+                finalControlsDb.close();
+            }
             if (opts.qaEnabled && !qaWaived && !finalizationRecovery) {
                 if (!qaPassCertificateId || !qaSourceStateDigest)
                     throw new Error("QA passed without a durable pass certificate");
@@ -760,6 +838,10 @@ export async function runBranchPlan(opts) {
                 await observeNode(opts, node, "cleanup", "removing ticket worktree", () => removeTicketWorktree(opts.projectDir, worktreePath));
         }
         catch (err) {
+            if (err instanceof BuildAssignmentRejected) {
+                summaries.push(summaryFor(node, "needs-human", err.message));
+                return summaries;
+            }
             if (err instanceof SessionUnavailableError || err instanceof SessionUnavailableContinuityError) {
                 const message = err.message;
                 opts.log.write("branch-issue", { ticket: node.ticket.id, code: "session_unavailable", message, blocking: true });
@@ -1027,6 +1109,8 @@ export function buildBranchTicketInstruction(node, trackerPaths = {}) {
 
 ${node.ticket.id}: ${node.ticket.title}
 
+${renderBuildWorkContext(node.ticket, trackerPaths.validationChecklist ?? [])}
+
 Summary:
 ${node.ticket.summary}
 
@@ -1047,7 +1131,7 @@ Branch-mode rules:
 - If another selected ticket is required before this one can be completed, stop and end with STEP_STATUS: blocked | ticket="${node.ticket.id}" branch_dependency="<ticket-id>" reason="<why>".
 - End with STEP_STATUS: done | ticket="${node.ticket.id}" summary="<what changed>" when the ticket is implemented.
 
-QA will happen in this same builder session after implementation.
+Final QA runs independently in a separate disposable snapshot and fresh reviewer conversation.
 
 ${MARKER_SPEC}`;
 }
@@ -1057,6 +1141,8 @@ export function buildBranchTicketResumeInstruction(node, trackerPaths = {}) {
 
 ${node.ticket.id}: ${node.ticket.title}
 
+${renderBuildWorkContext(node.ticket, trackerPaths.validationChecklist ?? [])}
+
 Resume from the current repository state. Inspect the worktree if needed, then finish only this ticket.
 
 Branch-mode rules:
@@ -1067,7 +1153,7 @@ Branch-mode rules:
 - If another selected ticket is required before this one can be completed, stop and end with STEP_STATUS: blocked | ticket="${node.ticket.id}" branch_dependency="<ticket-id>" reason="<why>".
 - End with STEP_STATUS: done | ticket="${node.ticket.id}" summary="<what changed>" when the ticket is implemented.
 
-QA will happen in this same builder session after implementation.
+Final QA runs independently in a separate disposable snapshot and fresh reviewer conversation.
 
 ${MARKER_SPEC}`;
 }

package/dist/buildAdmission.js

@@ -1,3 +1,4 @@
+import { registerHandbackWriter } from "./qaHandbackMigration.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash, randomUUID } from "node:crypto";
 import { realpathSync } from "node:fs";
@@ -56,6 +57,7 @@ export function maintainBuildAdmission(authority) {
         try {
             db = new Database(join(authority.project, ".rafi/recovery.sqlite3"), { fileMustExist: true });
             db.function("rafi_protocol_v3", () => 1);
+            registerHandbackWriter(db);
             const changed = db.prepare("UPDATE build_admission SET record_json=json_set(record_json,'$.heartbeatAt',?) WHERE singleton=1 AND json_extract(record_json,'$.token')=?").run(new Date().toISOString(), authority.token);
             if (changed.changes !== 1)
                 stopBuildAdmissionHeartbeat(authority);

package/dist/buildAssignment.d.ts

@@ -0,0 +1,33 @@
+import type { BuilderAdapter } from "./adapters/types.js";
+import type { StepStatus } from "./foreman.js";
+import type { TurnResult } from "./adapters/types.js";
+import { type FrozenQaSourceState } from "./qaSnapshot.js";
+/** Work responses confirm an assignment; they never select the next ticket. */
+export declare function validateBuildAssignment(ticketId: string, status: StepStatus, responseText?: string): string | undefined;
+export interface BuildAssignmentCapture {
+    operationId: string;
+    runId: string;
+    ticketId: string;
+    worktree: string;
+    before: BuildSourceState;
+    instruction: string;
+    guidanceIds: string[];
+}
+type BuildSourceState = Pick<FrozenQaSourceState, "digest" | "head" | "contentDigest" | "capturedAt" | "pathInventory" | "stagedDiff" | "unstagedDiff" | "untracked"> & {
+    captureMode: "git" | "filesystem";
+    omissions?: string[];
+};
+export declare class BuildAssignmentRejected extends Error {
+}
+export interface BuilderGuidanceFollowup {
+    reviewAttemptId: string;
+    requirementsDigest: string;
+    maximum: number;
+    authorizationId?: string;
+}
+export declare function assertBuildAssignmentReconciled(projectDir: string, runId: string, worktree?: string): void;
+/** Commit response/source bytes before interpreting any scoped outcome. */
+export declare function beginBuildAssignment(projectDir: string, runId: string, ticketId: string, worktree: string, instruction: string, followup?: BuilderGuidanceFollowup, adapter?: BuilderAdapter): BuildAssignmentCapture;
+export declare function finishBuildAssignment(projectDir: string, assignment: BuildAssignmentCapture, result: TurnResult, status: StepStatus): string | undefined;
+export declare function captureBuildSource(worktree: string): BuildSourceState;
+export {};