ai-foreman 1.7.24 → 1.7.26

package/dist/buildRuns.js

@@ -16,6 +16,7 @@ import { loadTickets } from "./tickets/ticketLoader.js";
 import { loadProjectAutonomyConfig, resolveAutonomyPolicy } from "./recoveryPolicy.js";
 import { classifyProcess, processStartIdentity } from "./processIdentity.js";
 import { assertBuildAssignmentReconciled } from "./buildAssignment.js";
+import { computeDisplayStatus, resolveBlockers } from "./tickets/blockers.js";
 export const BUILD_RUN_VERSION = 3;
 export const BUILD_RUN_DIRECTORY = ".foreman/runs";
 export const BUILD_HEARTBEAT_MS = 10_000;
@@ -176,6 +177,11 @@ export function saveBuildRun(projectDir, run, now = new Date()) {
             const existing = workflow.getRun(next.runId);
             const priorProgress = existing?.state.progress;
             next = { ...next, progress: { ...next.progress, completedTickets: [...new Set([...next.progress.completedTickets, ...(priorProgress?.completedTickets ?? [])])] } };
+            const newlyCompleted = next.progress.completedTickets.filter(ticket => !priorProgress?.completedTickets?.includes(ticket));
+            if (newlyCompleted.length || next.status === "completed")
+                next = { ...next, progress: { ...next.progress,
+                        lastSuccessfulAction: next.status === "completed" ? "Build completed" : `Recorded completion of ${newlyCompleted.join(", ")}`,
+                    } };
             if (existing && ["completed", "cancelled", "superseded"].includes(existing.status) && workflowStatus(next.status) !== existing.status)
                 throw new Error(`cannot rewrite a ${existing.status} build run`);
             if (!existing)
@@ -228,6 +234,21 @@ export function saveBuildRun(projectDir, run, now = new Date()) {
 export function checkpointBuildRun(projectDir, run, checkpoint, patch = {}) {
     return saveBuildRun(projectDir, { ...run, ...patch, checkpoint, receipts: patch.receipts ?? run.receipts });
 }
+/** Refresh a publication from durable state while retaining only the caller's
+ * original execution authority. A read-only projection never grants authority. */
+export function persistCurrentBuildSession(projectDir, authorizedRun, role, session) {
+    const db = new WorkflowDb(projectDir);
+    try {
+        assertBuildAuthority(db, authorizedRun);
+    }
+    finally {
+        db.close();
+    }
+    const latest = readBuildRuns(projectDir).find(run => run.runId === authorizedRun.runId);
+    if (!latest)
+        throw new Error("The authorized build no longer exists; inspect recovery before publishing a session");
+    return persistBuildSession(projectDir, { ...authorizedRun, ...latest }, role, session);
+}
 export function persistBuildSession(projectDir, run, role, session) {
     const current = run[role];
     if (!current)
@@ -329,6 +350,28 @@ export function finishRecoveredTicketScope(projectDir, run, checkpoint) {
         progress: { ...run.progress, completedTickets: completed, remainingTickets: remaining, nextAction: `Resume ${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)
+        return false;
+    if (!isTicketsInitialized(projectDir))
+        return false;
+    const paths = resolveTicketPaths(loadTicketsConfig(projectDir), projectDir);
+    const db = new Database(paths.stateDb, { readonly: true, fileMustExist: true });
+    try {
+        const states = new Map(db.prepare("SELECT * FROM ticket_state").all().map(state => [state.ticket_id, state]));
+        return loadTickets(paths.tickets).some(ticket => {
+            if (!run.progress.remainingTickets.includes(ticket.id))
+                return false;
+            const blockedBy = resolveBlockers(ticket, states);
+            const status = computeDisplayStatus(states.get(ticket.id)?.status ?? "planned", blockedBy);
+            return blockedBy.length === 0 && ["next", "in_progress"].includes(status);
+        });
+    }
+    finally {
+        db.close();
+    }
+}
 export function readBuildRuns(projectDir) {
     const directory = join(resolve(projectDir), BUILD_RUN_DIRECTORY);
     const workflow = new WorkflowReader(projectDir);
@@ -363,9 +406,13 @@ export function readBuildRuns(projectDir) {
             const authoritative = workflow?.getRun(projection.runId)?.state;
             const run = authoritative?.runId ? authoritative : projection;
             let upgraded = upgradeBuildRun(run, projectDir);
-            const dbStatus = workflow.getRun(run.runId)?.status;
+            const storedRun = workflow.getRun(run.runId);
+            const dbStatus = storedRun?.status;
             if (dbStatus === "superseded" || dbStatus === "completed" || dbStatus === "cancelled")
                 upgraded = { ...upgraded, status: dbStatus };
+            else if (storedRun && (dbStatus === "failed" || dbStatus === "paused" || dbStatus === "blocked")) {
+                upgraded = { ...upgraded, status: dbStatus === "failed" ? "failed" : "recoverable", checkpoint: storedRun.checkpoint, updatedAt: storedRun.updatedAt };
+            }
             if (!["completed", "superseded", "cancelled"].includes(workflow?.getRun(run.runId)?.status ?? "")) {
                 for (const role of ["builder", "qa"]) {
                     const lease = workflow?.roleMutationLease(run.runId, role);
@@ -563,7 +610,8 @@ export function projectBuildRecovery(projectDir, run, now = new Date(), ticketOv
         unexpectedChanges.push({ path: recoveryWorktree, risk: "preserved worktree identity changed" });
     if (branchChanged)
         unexpectedChanges.push({ path: recoveryWorktree, risk: `branch changed from ${expectedBranch} to ${branchNow}` });
-    const completed = [...new Set([...(progress?.completed ?? run.progress.completedTickets), ...run.progress.completedOperations, ...operationNames])];
+    const completed = [...new Set(progress?.completed ?? run.progress.completedTickets)];
+    const completedOperations = [...new Set([...run.progress.completedOperations, ...operationNames])];
     const remaining = progress?.remaining ?? (run.progress.remainingTickets.length ? run.progress.remainingTickets : remainingTickets(run));
     const interruption = run.interruption?.lastError ?? run.interruption?.summary ?? run.failure?.summary ?? issues.at(-1) ?? run.status;
     const validation = run.progress.validation
@@ -580,8 +628,8 @@ export function projectBuildRecovery(projectDir, run, now = new Date(), ticketOv
         run, ticketId, ticketTitle,
         compactLabel: `${primary} — ${run.status}`,
         compactHint: `${run.builder?.settings.make ?? "runtime unavailable"}; ${stateBranch ?? branchNow ?? run.repository.branch ?? "current branch"}; updated ${relativeTime(run.updatedAt, now)}`,
-        completed, remaining,
-        lastSuccess: run.progress.lastSuccessfulAction ?? run.checkpoint,
+        completed, completedOperations, remaining,
+        lastSuccess: run.progress.lastSuccessfulAction ?? "none recorded",
         interruption,
         validation,
         expectedChanges,
@@ -623,6 +671,7 @@ export function formatBuildRecoveryProjection(projection) {
         `ticket ${projection.ticketId ?? "unavailable"}${projection.ticketTitle ? `: ${projection.ticketTitle}` : ""}`,
         `status ${run.status}; checkpoint ${run.checkpoint}`,
         `completed ${projection.completed.join(", ") || "none recorded"}`,
+        ...(projection.completedOperations?.length ? [`verified operation receipts ${projection.completedOperations.join(", ")}`] : []),
         `current ${run.progress.currentStep ?? projection.ticketId ?? "not recorded"}`,
         `remaining ${projection.remaining.join(", ") || "none"}`,
         `last successful action ${projection.lastSuccess}`,
@@ -680,7 +729,7 @@ function captureGitSnapshot(worktree, input) {
             return undefined;
         }
     };
-    const statusPaths = (git(["status", "--porcelain=v1", "-z"]) ?? "").split("\0").filter(Boolean).map((line) => line.slice(3)).sort();
+    const statusPaths = gitStatusPaths(worktree);
     const head = input.startHead ?? git(["rev-parse", "HEAD"]);
     const branch = input.branch ?? git(["branch", "--show-current"]);
     return {
@@ -710,7 +759,24 @@ function gitValue(cwd, args) {
     }
 }
 function gitStatusPaths(cwd) {
-    return (gitValue(cwd, ["status", "--porcelain=v1", "-z"]) ?? "").split("\0").filter(Boolean).map((line) => line.slice(3)).sort();
+    try {
+        // Porcelain status columns and pathname whitespace are significant. In -z
+        // mode a rename/copy has a second raw pathname, without status columns.
+        const records = execFileSync("git", ["status", "--porcelain=v1", "-z"], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).split("\0");
+        const paths = [];
+        for (let i = 0; i < records.length; i++) {
+            const record = records[i];
+            if (!record)
+                continue;
+            paths.push(record.slice(3));
+            if (/[RC]/.test(record.slice(0, 2)) && records[i + 1])
+                paths.push(records[++i]);
+        }
+        return [...new Set(paths.filter(Boolean))].sort();
+    }
+    catch {
+        return [];
+    }
 }
 function relativeTime(value, now) {
     const seconds = Math.max(0, Math.floor((now.getTime() - new Date(value).getTime()) / 1000));
@@ -752,7 +818,7 @@ function upgradeBuildRun(run, projectDir = run.repository.root, now = new Date()
             completedTickets: legacy.status === "completed" ? [...legacy.tickets] : [],
             completedOperations: Object.keys(legacy.receipts).sort(),
             remainingTickets: remaining,
-            lastSuccessfulAction: legacy.checkpoint,
+            ...(legacy.status === "completed" ? { lastSuccessfulAction: "build completed" } : {}),
             nextAction: remaining[0] ? `Resume ${remaining[0]}` : "Inspect legacy run",
         },
         frozenPolicy: policy,

package/dist/cli/start.d.ts

@@ -24,8 +24,15 @@ export declare function validateStartOptions(opts: Record<string, any>, requireC
 export declare function validateRecoveryArguments(args: readonly string[], projectDir: string): void;
 /** Validate persisted preparation argv without executing a command or provider. */
 export declare function validatePreparationArguments(args: readonly string[], projectDir: string): string[];
-export declare function buildStartCommand(): Command;
+export declare function buildStartCommand(options?: {
+    beforeFreshStart?: (projectDir: string) => Promise<boolean>;
+}): Command;
 export declare function createQaNonconvergenceHandler(projectDir: string, noninteractive: boolean, planner?: AgentRoleDefaultsV1, observer?: () => RunObserver | undefined, activeRunId?: () => string): (context: QaNonconvergenceContext) => Promise<QaNonconvergenceDecision>;
 export declare function createQaReportRecoveryHandler(projectDir: string, noninteractive: boolean, observer?: () => RunObserver | undefined): QaReportRecoveryHandler;
+export declare function recoveryCompactionHistoryUncertain(projectDir: string, recovery: {
+    legacy?: boolean;
+    version?: number;
+    runDecisions?: unknown;
+} | undefined, runId: string | undefined, role: "builder" | "qa"): boolean;
 /** Make the executable branch plan exactly match each explicit root-to-tip stack. */
 export declare function applyExplicitStackTopology(plan: BranchPlan, stacks: DeliveryStack[], delivery: DeliveryConfig, branchPrefix: string): BranchPlan;

package/dist/cli/start.js

@@ -1,4 +1,5 @@
 import { finalQaRoleInstructions, resolveEffectiveQaConfiguration } from "../qaEffectiveConfig.js";
+import { activateQaRecoveryBuilder } from "../qaBuilderActivation.js";
 import { graphContext, sendGraphTurn } from "../graph/turn.js";
 import { initializeSyntheticWork } from "../buildSyntheticWork.js";
 import { admitApprovedTicket } from "../buildWorkAuthorization.js";
@@ -8,7 +9,7 @@ import { formatRecoveryCommand, formatDecisionCommands, formatExactRunRecovery }
 import { durableReadOnlyProposal } from "../readOnlyProposal.js";
 import { captureFrozenQaSource } from "../qaSnapshot.js";
 import { finishStartAdmission, superviseStart, supervisedRunId } from "../supervisedStart.js";
-import { assertBuildAssignmentReconciled } from "../buildAssignment.js";
+import { assertBuildAssignmentReconciled, isInterruptedBuilderRecovery, assertInterruptedSourceSnapshot } from "../buildAssignment.js";
 import { durableHumanDecision, HumanDecisionRequired, HumanDecisionCancelled, servicePendingHumanDecisions } from "../humanDecision.js";
 import { requiresBuildApproval, buildScopeRevision, createBuildApprovalGate } from "../buildApproval.js";
 import { Command, Option } from "commander";
@@ -24,7 +25,7 @@ import { PermissionPolicy } from "../permissions/policy.js";
 import { ClaudeAdapter } from "../adapters/claude.js";
 import { CodexAdapter } from "../adapters/codex.js";
 import { RecoveringAdapter } from "../adapters/recovering.js";
-import { Foreman, createPermissionHandler } from "../foreman.js";
+import { Foreman, BuildInterruptedError, createPermissionHandler } from "../foreman.js";
 import { printEvents } from "./events.js";
 import { loadRoleBundle } from "../roles.js";
 import { ensureBuildRuntimeReadyForCommand } from "./runtimeAuthPrompt.js";
@@ -39,7 +40,7 @@ import { formatGitHubFailure, preflightGh } from "../branch/github.js";
 import { preflightGlab } from "../branch/gitlab.js";
 import { readDeliveryUnitSession, runBranchPlan } from "../branch/runner.js";
 import { branchPlanLogMetadata, presentBranchPlan } from "../branch/presentation.js";
-import { buildRunSessionBinding, checkpointBuildRun, completeBuildRun, createBuildRun, currentBranchRecoveryTicket, currentBranchTicketProgress, recoveryExecutionTickets, finishRecoveredTicketScope, heartbeatBuildRun, persistBuildSession, projectBuildRecovery, readBuildRuns, releaseBuildLease, resumeBuildRun } from "../buildRuns.js";
+import { buildRunSessionBinding, checkpointBuildRun, completeBuildRun, createBuildRun, currentBranchRecoveryTicket, currentBranchTicketProgress, recoveryExecutionTickets, finishRecoveredTicketScope, heartbeatBuildRun, persistBuildSession, persistCurrentBuildSession, projectBuildRecovery, readBuildRuns, releaseBuildLease, resumeBuildRun } from "../buildRuns.js";
 import { parse as parseYaml } from "yaml";
 import { findResumableBranchSessions, formatBranchContinueCommand, formatBranchSummaryFollowupCommands, } from "../branch/resume.js";
 import { detectGitProvider, loadTicketSetupConfig } from "../tickets/setupConfig.js";
@@ -450,7 +451,7 @@ export function validatePreparationArguments(args, projectDir) {
             throw new Error("Saved preparation contains stale internal recovery authority");
     return savedStartArguments(command, projectDir, options);
 }
-export function buildStartCommand() {
+export function buildStartCommand(options = {}) {
     return new Command("start")
         .description("Enlist a builder and drive it through a batch of N steps.")
         .argument("<project>", "path to the project directory the builder works in")
@@ -471,7 +472,7 @@ export function buildStartCommand() {
         .option("-t, --tickets <path>", "path to ticket file (.md, .txt, .yaml, …) — passed to the builder as context")
         .option("-y, --yes", "skip pre-flight confirmation prompt")
         .option("--effort <level>", "reasoning effort level (low|medium|high|xhigh)")
-        .option("--fast", "fast mode — lower latency (maps to effort=low for codex)")
+        .option("--fast", "use native fast mode when available; keep the model and reasoning settings")
         .option("--no-qa", "disable per-ticket QA review (enabled by default)")
         .option("--autonomy <profile>", "autonomy profile (supervised | balanced | unattended)")
         .option("--detach", "return after launching the durable supervisor")
@@ -557,6 +558,10 @@ export function buildStartCommand() {
         const cwd = resolve(project);
         if (!existsSync(cwd))
             fail(`project directory not found: ${cwd}`);
+        // Recovery commands launch a frozen continuation and must not recursively
+        // offer a different recovery path. Fresh launches may be redirected first.
+        if (!recoveryIntent && options.beforeFreshStart && !await options.beforeFreshStart(cwd))
+            return;
         const recoveryRecord = opts.recoverRun ? readBuildRuns(cwd).find((run) => run.runId === opts.recoverRun) : undefined;
         let dirtyWork = recoveryRecord?.runDecisions?.dirtyWork;
         if (opts.recoverRun && !recoveryRecord)
@@ -956,7 +961,10 @@ export function buildStartCommand() {
             let activeContinuityRunId;
             let liveStatusReporter;
             let activeBuilderForStatus;
-            const resolvedContinuitySettings = (role) => role === "builder" ? {
+            const qaBuilderRecoverySelected = recoveryRecord?.recoveryDecision?.role === "qa";
+            const savedQaBuilderSettings = qaBuilderRecoverySelected ? recoveryRecord.builder?.settings : undefined;
+            let publishActivatedBuilderSession;
+            const resolvedContinuitySettings = (role) => role === "builder" && savedQaBuilderSettings ? { ...savedQaBuilderSettings } : role === "builder" ? {
                 role, source: roleDefaults.builder ? "project" : "provider", make: agent, model: model ?? "default",
                 reasoning: builderEffort ?? "default", fast: Boolean(builderFast), session_strategy: roleDefaults.builder?.session_strategy ?? "compact",
                 settings_revision: settingsRevision, display_session_cost: sessionCostOverride ?? roleDefaults.builder?.display_session_cost ?? false,
@@ -1254,6 +1262,35 @@ export function buildStartCommand() {
                     await continuous.validateFreshRecovery();
                 return continuous;
             };
+            // QA-only recovery leaves Builder ownership untouched until a real,
+            // approved remediation/guidance boundary needs Builder work. The unused
+            // adapter cannot bypass the old role owner or use QA's CLI model settings.
+            const activateBuilderForQaRecovery = async (adapter, worktree, frozenAction) => {
+                if (!qaBuilderRecoverySelected || !recoveryRecord)
+                    return adapter;
+                const currentRun = readBuildRuns(cwd).find(run => run.runId === recoveryRecord.runId);
+                // The saved recovery ticket is only the initial boundary. Later batch
+                // tickets must bind their own durable selection before Builder work.
+                const ticketId = currentRun?.currentTicket ?? recoveryRecord.recoveryDecision?.executionTickets?.[0] ?? requestedTicketIds[0];
+                if (!ticketId)
+                    throw new Error("QA recovery has no approved Builder follow-up ticket; inspect this build before dispatch");
+                const activated = await activateQaRecoveryBuilder({ projectDir: cwd, runId: recoveryRecord.runId, ticketId, worktree, adapter,
+                    settings: savedQaBuilderSettings ?? resolvedContinuitySettings("builder"), expectedCapabilities: builderCapabilities, frozenAction,
+                    createSuccessor: () => createBuilderForSettings(worktree, savedQaBuilderSettings ?? resolvedContinuitySettings("builder")),
+                    wrap: successor => continuousBuilder(successor, worktree, recoveryRecord.runId, savedQaBuilderSettings ?? resolvedContinuitySettings("builder")),
+                    recovery: { ...handoffRecoveryOptions("builder"), allowProviderSwitch: false },
+                });
+                if (activated !== adapter) {
+                    const current = readBuildRuns(cwd).find(run => run.runId === recoveryRecord.runId);
+                    const ref = activated.sessionRef?.();
+                    if (!current || !ref?.validatedAt)
+                        throw new Error("Accepted Builder activation lacks a durable scoped session; recovery is paused before implementation");
+                    if (!publishActivatedBuilderSession)
+                        throw new Error("Accepted Builder activation has no original execution authority; recovery is paused before implementation");
+                    publishActivatedBuilderSession(ref);
+                }
+                return activated;
+            };
             const applyBuilderSettingsBoundary = async (runId, builderCwd, input) => {
                 const context = await input.adapter.contextUsage?.().catch(() => undefined);
                 const nativeUsage = await input.adapter.sessionUsage?.().catch(() => undefined);
@@ -1450,7 +1487,7 @@ export function buildStartCommand() {
                         db.close();
                     } },
                     handoffGeneration: () => { const db = new WorkflowDb(cwd); try {
-                        return activeContinuityRunId ? db.handoffs(activeContinuityRunId).at(-1)?.generation ?? 0 : 0;
+                        return activeContinuityRunId ? db.roleMutationLease(activeContinuityRunId, "qa")?.generation ?? 0 : 0;
                     }
                     finally {
                         db.close();
@@ -1469,7 +1506,7 @@ export function buildStartCommand() {
                                 db.close();
                             } },
                             handoffGeneration: () => { const db = new WorkflowDb(cwd); try {
-                                return activeContinuityRunId ? db.handoffs(activeContinuityRunId).at(-1)?.generation ?? 0 : 0;
+                                return activeContinuityRunId ? db.roleMutationLease(activeContinuityRunId, "builder")?.generation ?? 0 : 0;
                             }
                             finally {
                                 db.close();
@@ -1544,8 +1581,16 @@ export function buildStartCommand() {
                     const packet = pendingQaRecoveryPacket(cwd, recoveryRecord.runId, requestedTicketIds[0]);
                     if (!packet)
                         throw new Error("accepted QA recovery handoff has no current durable packet");
+                    const boundaryDb = new WorkflowDb(cwd);
+                    let afterOwnedRemediation = false;
+                    try {
+                        afterOwnedRemediation = boundaryDb.hasConfirmedQaRemediationForRecheck(packet.manifest.runId, packet.manifest.ticketId);
+                    }
+                    finally {
+                        boundaryDb.close();
+                    }
                     const confinement = describeQaHandle(adapter, qaCwd, { kind: "initial" }).confinement;
-                    handoffReceipt = { kind: "accepted", receipt: qaV2HandoffReceipt(accepted.acceptanceReceipt, {
+                    handoffReceipt = afterOwnedRemediation ? { kind: "initial" } : { kind: "accepted", receipt: qaV2HandoffReceipt(accepted.acceptanceReceipt, {
                             runId: packet.manifest.runId, ticketId: packet.manifest.ticketId, packetDigest: packet.manifest.packetDigest,
                             reviewedStateDigest: packet.manifest.reviewedStateDigest,
                         }, confinement.digest) };
@@ -1754,7 +1799,8 @@ export function buildStartCommand() {
                 if (branchDefaults.createReview && branchDefaults.reviewProvider) {
                     await ensureReviewProviderReady(cwd, branchDefaults.reviewProvider, log, Boolean(opts.yes));
                 }
-                console.log(`foreman: builder capability request: workspace writes, shell network ${grantedNetwork ? "approved for this build" : "off"}, approvals ${opts.builderApprovals ? "per operation" : "never"}; effective policy requires provider confirmation. Use a provenance-verified local source/dependency bundle for offline acquisition.`);
+                if (grantedNetwork || opts.builderApprovals)
+                    console.log(`foreman: requested Builder shell capabilities: network ${grantedNetwork ? "approved for this build" : "off"}; approvals ${opts.builderApprovals ? "per operation" : "never"}. Effective permissions will be verified with the provider.`);
                 const ready = await ensureBuildRuntimeReadyForCommand(cwd, agent, { build: readinessOwner, durable: { projectDir: cwd, runId: activeContinuityRunId ?? invocationRunId, scopeRevision: buildScopeRevision(cwd, approvalConsequences) }, timeoutMs: frozenPolicy.runtimeDeadlines?.preparation_ms,
                     label: "start",
                     yes: Boolean(opts.yes),
@@ -1933,7 +1979,7 @@ export function buildStartCommand() {
                     }
                     resumeSessionByTicket.set(ticketId, { ...session, sessionRef: availability.sessionRef });
                 }
-                const capturedBranchBuilder = {
+                const capturedBranchBuilder = savedQaBuilderSettings ? { ...savedQaBuilderSettings } : {
                     role: "builder", source: opts.agent || opts.model || opts.effort || opts.fast ? "cli" : roleDefaults.builder ? "project" : "provider",
                     make: agent, model: model ?? "default", reasoning: builderEffort ?? "default", fast: Boolean(builderFast),
                     session_strategy: roleDefaults.builder?.session_strategy ?? "compact", settings_revision: settingsRevision,
@@ -1949,7 +1995,9 @@ export function buildStartCommand() {
                     compact_maximum: roleDefaults.qa?.compact_maximum ?? 10,
                 };
                 const firstResumeRef = plan.nodes[0] ? resumeSessionByTicket.get(plan.nodes[0].ticket.id)?.sessionRef : undefined;
-                let masterRun = recoveryRecord ? resumeBuildRun(cwd, recoveryRecord.runId, { builder: capturedBranchBuilder, qa: capturedBranchQa, builderSessionId: firstResumeRef?.sessionId ?? null, builderSessionRef: firstResumeRef ?? null, expectedRecoveryDecisionDigest: opts.recoveryDecisionDigest }) : createBuildRun({
+                const branchQaOnlyRecovery = Boolean(recoveryRecord && !isInterruptedBuilderRecovery(recoveryRecord)
+                    && (opts.qaRevision !== undefined || pendingQaRecoveryPacket(cwd, recoveryRecord.runId, requestedTicketIds[0])));
+                let masterRun = recoveryRecord ? resumeBuildRun(cwd, recoveryRecord.runId, { ...(branchQaOnlyRecovery ? {} : { builder: capturedBranchBuilder, builderSessionId: firstResumeRef?.sessionId ?? null, builderSessionRef: firstResumeRef ?? null }), qa: capturedBranchQa, expectedRecoveryDecisionDigest: opts.recoveryDecisionDigest }) : createBuildRun({
                     runId: invocationRunId,
                     builderCapabilities, tickets: plan.nodes.map((node) => node.ticket.id), deliveryUnit: selectedStacks.length ? selectedStacks.map((stack) => stack.id).join(",") : deliveryRun?.unit.id,
                     repositoryRoot: cwd, branchMode: branchPresentation.allocationMode, baseRef: plan.baseRef, builder: capturedBranchBuilder, qa: capturedBranchQa,
@@ -1957,6 +2005,7 @@ export function buildStartCommand() {
                     runDecisions: { dirtyWork, workMode: "branch-per-ticket", workModeSource, branchPrefix, branchPrefixSource: resolvedPrefix.source, autoCompactThresholdPercent: capturedBranchBuilder.auto_compact_threshold_percent ?? 65, thresholdSource: thresholdOverride === undefined ? "project" : "cli" },
                 });
                 activeContinuityRunId = masterRun.runId;
+                publishActivatedBuilderSession = ref => { masterRun = persistCurrentBuildSession(cwd, masterRun, "builder", ref); };
                 if (requiresBuildApproval(cwd, plan.nodes.map(node => node.ticket.id), autoApprovePlanUpdates, approvalConsequences) && plan.issues.every((issue) => !issue.blocking)) {
                     const action = await durableHumanDecision({ projectDir: cwd, runId: invocationRunId, key: `branch-plan:${buildScopeRevision(cwd, approvalConsequences)}`, prompt: branchPresentation.prompt, choices: [{ id: "proceed", label: "Proceed" }, { id: "cancel", label: "Cancel" }], operation: () => select({
                             message: branchPresentation.prompt,
@@ -1985,9 +2034,9 @@ export function buildStartCommand() {
                 for (const node of plan.nodes)
                     admitApprovedTicket(cwd, masterRun.runId, node.ticket.id, buildScopeRevision(cwd), `build invocation ${invocationRunId}: approved branch plan`);
                 masterRun = checkpointBuildRun(cwd, masterRun, "capabilities-resolved", { builderCapabilities });
-                const qaResumedRecovery = recoveryRecord ? pendingQaRecoveryPacket(cwd, masterRun.runId, requestedTicketIds[0]) : undefined;
+                const qaResumedRecovery = recoveryRecord && !isInterruptedBuilderRecovery(recoveryRecord) ? pendingQaRecoveryPacket(cwd, masterRun.runId, requestedTicketIds[0]) : undefined;
                 let qaProtocolResumeTicket;
-                if (recoveryRecord && !qaResumedRecovery) {
+                if (recoveryRecord && !qaResumedRecovery && !isInterruptedBuilderRecovery(recoveryRecord)) {
                     const protocolDb = new WorkflowDb(cwd);
                     try {
                         const pendingHeads = protocolDb.pendingQaTicketHeads(masterRun.runId);
@@ -2121,7 +2170,7 @@ export function buildStartCommand() {
                                     db.close();
                                 } },
                                 handoffGeneration: () => { const db = new WorkflowDb(cwd); try {
-                                    return db.handoffs(masterRun.runId).at(-1)?.generation ?? 0;
+                                    return db.roleMutationLease(masterRun.runId, "builder")?.generation ?? 0;
                                 }
                                 finally {
                                     db.close();
@@ -2145,9 +2194,12 @@ export function buildStartCommand() {
                             }
                         },
                         qaNonconvergence,
-                        beforeBuilderTurn: async (adapter, frozenAction, worktreePath) => (await branchContextController(worktreePath).atSafeBoundary(adapter, frozenAction)).adapter,
+                        beforeBuilderTurn: async (adapter, frozenAction, worktreePath) => (await branchContextController(worktreePath).atSafeBoundary(await activateBuilderForQaRecovery(adapter, worktreePath, frozenAction), frozenAction)).adapter,
                         observeBuilderNativeCompactions: async (adapter, worktreePath) => { await branchContextController(worktreePath).observeNativeCompactions(adapter); },
-                        builderSessionBoundary: async (adapter, frozenAction, strategy, worktreePath) => (await branchContextController(worktreePath).atWorkSessionBoundary(adapter, frozenAction, strategy)).adapter,
+                        builderSessionBoundary: async (adapter, frozenAction, strategy, worktreePath) => {
+                            const activated = await activateBuilderForQaRecovery(adapter, worktreePath, frozenAction);
+                            return activated !== adapter ? activated : (await branchContextController(worktreePath).atWorkSessionBoundary(activated, frozenAction, strategy)).adapter;
+                        },
                         qaSessionBoundary,
                         observeQaNativeCompactions,
                     });
@@ -2252,7 +2304,8 @@ export function buildStartCommand() {
                     state.close();
                 }
             }
-            console.log(`foreman: builder capability request: workspace writes, shell network ${grantedNetwork ? "approved for this build" : "off"}, approvals ${opts.builderApprovals ? "per operation" : "never"}; effective policy requires provider confirmation. Use a provenance-verified local source/dependency bundle for offline acquisition.`);
+            if (grantedNetwork || opts.builderApprovals)
+                console.log(`foreman: requested Builder shell capabilities: network ${grantedNetwork ? "approved for this build" : "off"}; approvals ${opts.builderApprovals ? "per operation" : "never"}. Effective permissions will be verified with the provider.`);
             const ready = await ensureBuildRuntimeReadyForCommand(cwd, agent, { build: readinessOwner, durable: { projectDir: cwd, runId: activeContinuityRunId ?? invocationRunId, scopeRevision: buildScopeRevision(cwd, approvalConsequences) }, timeoutMs: frozenPolicy.runtimeDeadlines?.preparation_ms,
                 label: "start",
                 yes: Boolean(opts.yes),
@@ -2282,7 +2335,7 @@ export function buildStartCommand() {
                 qaModel = qaReady.model;
                 qaExecutable = qaReady.executable;
             }
-            const capturedBuilder = {
+            const capturedBuilder = savedQaBuilderSettings ? { ...savedQaBuilderSettings } : {
                 role: "builder", source: opts.agent || opts.model || opts.effort || opts.fast ? "cli" : roleDefaults.builder ? "project" : "provider",
                 make: agent, model: model ?? "default", reasoning: builderEffort ?? "default", fast: Boolean(builderFast),
                 session_strategy: roleDefaults.builder?.session_strategy ?? "compact", settings_revision: settingsRevision,
@@ -2291,7 +2344,11 @@ export function buildStartCommand() {
                 compact_maximum: roleDefaults.builder?.compact_maximum ?? 10,
             };
             const capturedQa = { role: "qa", source: roleDefaults.qa ? "project" : "provider", make: qaAgent, model: qaModel ?? "default", reasoning: qaEffort ?? "default", fast: qaFast, session_strategy: roleDefaults.qa?.session_strategy ?? "compact", display_session_cost: sessionCostOverride ?? roleDefaults.qa?.display_session_cost ?? false, auto_compact_threshold_percent: roleDefaults.qa?.auto_compact_threshold_percent ?? 65, compact_maximum: roleDefaults.qa?.compact_maximum ?? 10, settings_revision: settingsRevision };
-            let buildRun = recoveryRecord ? resumeBuildRun(cwd, recoveryRecord.runId, { builder: capturedBuilder, qa: capturedQa, builderSessionId: resumeSessionId ?? null, builderSessionRef: resumeSessionRef ?? null, expectedRecoveryDecisionDigest: opts.recoveryDecisionDigest }) : createBuildRun({
+            // QA recovery owns the QA session only. Its CLI model overrides and unused
+            // Builder adapter must not replace the saved Builder that continues later.
+            const qaOnlyRecovery = Boolean(recoveryRecord && !isInterruptedBuilderRecovery(recoveryRecord)
+                && (opts.qaRevision !== undefined || pendingQaRecoveryPacket(cwd, recoveryRecord.runId, requestedTicketIds[0])));
+            let buildRun = recoveryRecord ? resumeBuildRun(cwd, recoveryRecord.runId, { ...(qaOnlyRecovery ? {} : { builder: capturedBuilder, builderSessionId: resumeSessionId ?? null, builderSessionRef: resumeSessionRef ?? null }), qa: capturedQa, expectedRecoveryDecisionDigest: opts.recoveryDecisionDigest }) : createBuildRun({
                 runId: invocationRunId,
                 tickets: [...(executionTickets ?? [])], builderCapabilities, authorizedBatch: { tickets: [...(executionTickets ?? [])], requestedSteps: steps, scopeRevision: buildScopeRevision(cwd, approvalConsequences), startedTickets: [] }, repositoryRoot: cwd, branchMode: "current", baseRef: opts.base ?? loadTicketSetupConfig(cwd)?.build.base_branch, builder: capturedBuilder, qa: capturedQa,
                 frozenPolicy, autonomyProfile, qaEnabled,
@@ -2300,10 +2357,11 @@ export function buildStartCommand() {
             buildRun = checkpointBuildRun(cwd, buildRun, "capabilities-resolved", { builderCapabilities });
             activeObserver?.store.attachExecutionLease(activeObserver.executionId, readCurrentWorkflowLease(cwd)?.generation);
             activeContinuityRunId = buildRun.runId;
-            const qaResumedRecovery = recoveryRecord ? pendingQaRecoveryPacket(cwd, buildRun.runId, requestedTicketIds[0]) : undefined;
+            publishActivatedBuilderSession = ref => { buildRun = persistCurrentBuildSession(cwd, buildRun, "builder", ref); };
+            const qaResumedRecovery = recoveryRecord && !isInterruptedBuilderRecovery(recoveryRecord) ? pendingQaRecoveryPacket(cwd, buildRun.runId, requestedTicketIds[0]) : undefined;
             let qaFinalizationTicket;
             let qaProtocolResumeTicket;
-            if (recoveryRecord && !qaResumedRecovery) {
+            if (recoveryRecord && !qaResumedRecovery && !isInterruptedBuilderRecovery(recoveryRecord)) {
                 const finalizationDb = new WorkflowDb(cwd);
                 try {
                     const pendingHeads = finalizationDb.pendingQaTicketHeads(buildRun.runId);
@@ -2343,19 +2401,38 @@ export function buildStartCommand() {
             }
             const heartbeat = setInterval(() => { buildRun = heartbeatBuildRun(cwd, buildRun); }, 10_000);
             heartbeat.unref();
+            let interruptionRequested = false;
+            let stopActiveBuild;
             const checkpointSignal = () => {
-                try {
-                    buildRun = releaseBuildLease(cwd, buildRun, "interrupted");
-                }
-                catch { /* best effort */ }
+                if (["completed", "cancelled", "superseded"].includes(buildRun.status))
+                    return;
+                if (interruptionRequested)
+                    return;
+                interruptionRequested = true;
+                clearInterval(heartbeat);
+                // Hold the lease until the cancelled provider turn has published its
+                // outcome. Releasing here races with assignment and completion writes.
+                void stopActiveBuild?.().catch(error => log.write("error", { phase: "interruption-cleanup", message: String(error) }));
             };
             process.once("SIGINT", checkpointSignal);
             process.once("SIGTERM", checkpointSignal);
             let builder;
             try {
+                if (recoveryRecord)
+                    assertInterruptedSourceSnapshot(cwd, recoveryRecord);
                 builder = await createBuilder(cwd, resumeSessionId, resumeSessionRef);
+                stopActiveBuild = () => builder.close();
+                if (interruptionRequested) {
+                    await builder.close();
+                    throw new BuildInterruptedError();
+                }
             }
             catch (error) {
+                if (error instanceof BuildInterruptedError) {
+                    buildRun = releaseBuildLease(cwd, checkpointBuildRun(cwd, buildRun, "interrupted", { status: "recoverable" }), "recoverable");
+                    console.error(`rafi: Build interrupted; current work is preserved. Continue with ${formatRecoveryCommand(cwd)}`);
+                    process.exit(2);
+                }
                 if (!(error instanceof SessionUnavailableError))
                     throw error;
                 const summary = error.message.slice(0, 1000);
@@ -2413,7 +2490,13 @@ export function buildStartCommand() {
                     return continuousBuilder(transfer.successor, cwd, buildRun.runId, settings);
                 },
             });
-            const foreman = new Foreman(builder, log, { desktop: config.notifications.enabled, terminalBell: config.notifications.terminal_bell }, qaEnabled, frozenPolicy.limits.builderQaFixesPerTicket, cwd, undefined, qaEnabled ? createQa : undefined, capturedQa.session_strategy, createBuilder, capturedBuilder.session_strategy, qaNonconvergence, async (adapter, frozenAction) => (await contextController.atSafeBoundary(adapter, frozenAction)).adapter, async (adapter, frozenAction, strategy) => (await contextController.atWorkSessionBoundary(adapter, frozenAction, strategy)).adapter, qaSessionBoundary, observeQaNativeCompactions, async (adapter) => { await contextController.observeNativeCompactions(adapter); }, activeObserver, capturedQa, true, qaReportRecovery, qaResumedRecovery, buildRun.runId, frozenPolicy.continueIndependentTickets);
+            const foreman = new Foreman(builder, log, { desktop: config.notifications.enabled, terminalBell: config.notifications.terminal_bell }, qaEnabled, frozenPolicy.limits.builderQaFixesPerTicket, cwd, undefined, qaEnabled ? createQa : undefined, capturedQa.session_strategy, createBuilder, capturedBuilder.session_strategy, qaNonconvergence, async (adapter, frozenAction) => (await contextController.atSafeBoundary(await activateBuilderForQaRecovery(adapter, cwd, frozenAction), frozenAction)).adapter, async (adapter, frozenAction, strategy) => {
+                const activated = await activateBuilderForQaRecovery(adapter, cwd, frozenAction);
+                return activated !== adapter ? activated : (await contextController.atWorkSessionBoundary(activated, frozenAction, strategy)).adapter;
+            }, qaSessionBoundary, observeQaNativeCompactions, async (adapter) => { await contextController.observeNativeCompactions(adapter); }, activeObserver, capturedQa, true, qaReportRecovery, qaResumedRecovery, buildRun.runId, frozenPolicy.continueIndependentTickets);
+            stopActiveBuild = () => foreman.requestStop();
+            if (interruptionRequested)
+                await foreman.requestStop();
             activeBuilderForStatus = () => foreman.builderAdapter();
             const statusReporter = liveStatusReporter = new AgentStatusReporter({
                 runId: buildRun.runId,
@@ -2429,7 +2512,7 @@ export function buildStartCommand() {
                     db.close();
                 } },
                 handoffGeneration: () => { const db = new WorkflowDb(cwd); try {
-                    return db.handoffs(buildRun.runId).at(-1)?.generation ?? 0;
+                    return db.roleMutationLease(buildRun.runId, "builder")?.generation ?? 0;
                 }
                 finally {
                     db.close();
@@ -2451,7 +2534,7 @@ export function buildStartCommand() {
                 builderFast ? "fast" : null,
                 qaEnabled ? null : "qa=off",
             ].filter(Boolean).join(" ");
-            console.log(`${accent("foreman:")} driving a ${sanitizeTerminalText(agent)} builder through ${steps} step(s)${modifiers ? ` [${sanitizeTerminalText(modifiers)}]` : ""}`);
+            console.log(`${accent("foreman:")} requested batch budget ${steps} step(s); current admitted scope ${buildRun.tickets.join(", ") || "awaiting a validated work plan"}; ${sanitizeTerminalText(agent)} Builder${modifiers ? ` [${sanitizeTerminalText(modifiers)}]` : ""}`);
             console.log(`${accent("foreman:")} project ${sanitizeTerminalText(cwd)}`);
             if (trackerRelPath)
                 console.log(`${accent("foreman:")} tracker ${sanitizeTerminalText(trackerRelPath)}`);
@@ -2497,8 +2580,6 @@ export function buildStartCommand() {
                         : foreman.completePendingQaRecovery(ticketId));
                     if (pendingHandoffGeneration !== undefined)
                         throw new Error(`recovery handoff generation ${pendingHandoffGeneration} for ${pendingHandoffRole} was not accepted`);
-                    if (foreman.builderSessionId())
-                        buildRun = persistBuildSession(cwd, buildRun, "builder", foreman.builderAdapter().sessionRef?.() ?? foreman.builderSessionId());
                     if (foreman.qaSessionId())
                         buildRun = persistBuildSession(cwd, buildRun, "qa", foreman.qaSessionRef() ?? foreman.qaSessionId());
                     buildRun = qa.outcome === "passed" || qa.outcome === "waived"
@@ -2650,7 +2731,16 @@ export function buildStartCommand() {
             }
             catch (err) {
                 clearInterval(heartbeat);
+                process.off("SIGINT", checkpointSignal);
+                process.off("SIGTERM", checkpointSignal);
+                await foreman.close().catch(() => { });
                 statusReporter.stop("interrupted");
+                if (interruptionRequested || err instanceof BuildInterruptedError) {
+                    buildRun = releaseBuildLease(cwd, checkpointBuildRun(cwd, buildRun, "interrupted", { status: "recoverable" }), "recoverable");
+                    log.write("safe-boundary-paused", { runId: buildRun.runId, checkpoint: "interrupted", intentional: true });
+                    console.error(`rafi: Build interrupted; current work is preserved. Continue with ${formatRecoveryCommand(cwd)}`);
+                    process.exit(2);
+                }
                 if (err instanceof ContextCapabilityError || err instanceof CurrentWorkflowChangedError) {
                     const summary = err.message.slice(0, 1000);
                     buildRun = releaseBuildLease(cwd, checkpointBuildRun(cwd, buildRun, "safe-boundary-paused", {
@@ -2717,7 +2807,7 @@ export function buildStartCommand() {
                 }
                 buildRun = releaseBuildLease(cwd, checkpointBuildRun(cwd, buildRun, "failed", { status: "failed", failure: { category: "unknown", summary: err instanceof Error ? err.message.slice(0, 1000) : String(err).slice(0, 1000), at: new Date().toISOString() } }), "failed");
                 await foreman.close().catch(() => { });
-                log.write("error", { message: String(err) });
+                log.write("error", { message: String(err), ...(err instanceof Error ? { stack: err.stack } : {}) });
                 fail(`run failed: ${err instanceof Error ? err.message : String(err)}`);
             }
         }
@@ -2801,6 +2891,7 @@ function pruneRecoveryTelemetryAtCompletion(projectDir, retentionDays) {
         console.error(`rafi: recovery telemetry maintenance skipped: ${String(error).replace(/\s+/g, " ").slice(0, 300)}`);
     }
 }
+const reportedCompactionPolicies = new WeakMap();
 async function prepareNativeAutoCompaction(adapter) {
     if (!adapter.prepareAutoCompaction) {
         await adapter.close().catch(() => { });
@@ -2808,11 +2899,14 @@ async function prepareNativeAutoCompaction(adapter) {
     }
     try {
         const policy = await adapter.prepareAutoCompaction();
-        if (policy && policy.effectiveThresholdPercent !== policy.requestedThresholdPercent) {
-            console.log(`foreman: ${adapter.agent} applied automatic compaction at ${policy.effectiveThresholdPercent}% `
-                + `(configured ${policy.requestedThresholdPercent}%; provider minimum or clamp). `
-                + "Use `rafi agents .` to update the Builder or QA saved threshold interactively.");
+        const noticeKey = policy ? `${policy.requestedThresholdPercent}:${policy.effectiveThresholdPercent}` : undefined;
+        if (policy && policy.effectiveThresholdPercent !== policy.requestedThresholdPercent && reportedCompactionPolicies.get(adapter) !== noticeKey) {
+            console.log(`foreman: ${adapter.agent} reports a native automatic-compaction trigger of ${policy.effectiveThresholdPercent}% `
+                + `(requested ${policy.requestedThresholdPercent}%). Configuration does not mean that compaction occurred. `
+                + "The provider's effective trigger may differ from the saved preference.");
         }
+        if (noticeKey)
+            reportedCompactionPolicies.set(adapter, noticeKey);
     }
     catch (error) {
         await adapter.close().catch(() => { });
@@ -2975,10 +3069,10 @@ function readAgentDefaults(projectDir) {
 function explicitDefaultValue(value) {
     return value && value !== "default" ? value : undefined;
 }
-function recoveryCompactionHistoryUncertain(projectDir, recovery, runId, role) {
+export function recoveryCompactionHistoryUncertain(projectDir, recovery, runId, role) {
     if (!recovery)
         return false;
-    if (recovery.legacy || !recovery.runDecisions || !runId)
+    if (recovery.legacy || (!recovery.runDecisions && recovery.version !== 3) || !runId)
         return true;
     const db = new WorkflowDb(projectDir);
     try {

package/dist/cli/tickets.d.ts

@@ -61,5 +61,6 @@ export declare function ticketOwnershipReceipts(projectDir: string, commandName:
 export declare function buildTicketsCommand(options?: {
     prepareOwnership?: (projectDir: string, receipts: TicketOwnershipReceipt[]) => void;
     recordOwnership?: (projectDir: string, receipts: TicketOwnershipReceipt[]) => void;
+    restartBuild?: (projectDir: string, runId: string, tickets: string[]) => Promise<void>;
 }): Command;
 export {};