ai-foreman 1.7.25 → 1.7.26

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, isInterruptedBuilderRecovery } 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";
@@ -471,7 +472,7 @@ export function buildStartCommand(options = {}) {
         .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")
@@ -960,7 +961,10 @@ export function buildStartCommand(options = {}) {
             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,
@@ -1258,6 +1262,35 @@ export function buildStartCommand(options = {}) {
                     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);
@@ -1454,7 +1487,7 @@ export function buildStartCommand(options = {}) {
                         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();
@@ -1473,7 +1506,7 @@ export function buildStartCommand(options = {}) {
                                 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();
@@ -1548,8 +1581,16 @@ export function buildStartCommand(options = {}) {
                     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) };
@@ -1758,7 +1799,8 @@ export function buildStartCommand(options = {}) {
                 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),
@@ -1937,7 +1979,7 @@ export function buildStartCommand(options = {}) {
                     }
                     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,
@@ -1953,7 +1995,9 @@ export function buildStartCommand(options = {}) {
                     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,
@@ -1961,6 +2005,7 @@ export function buildStartCommand(options = {}) {
                     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,
@@ -2125,7 +2170,7 @@ export function buildStartCommand(options = {}) {
                                     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();
@@ -2149,9 +2194,12 @@ export function buildStartCommand(options = {}) {
                             }
                         },
                         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,
                     });
@@ -2256,7 +2304,8 @@ export function buildStartCommand(options = {}) {
                     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),
@@ -2286,7 +2335,7 @@ export function buildStartCommand(options = {}) {
                 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,
@@ -2295,7 +2344,11 @@ export function buildStartCommand(options = {}) {
                 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,
@@ -2304,6 +2357,7 @@ export function buildStartCommand(options = {}) {
             buildRun = checkpointBuildRun(cwd, buildRun, "capabilities-resolved", { builderCapabilities });
             activeObserver?.store.attachExecutionLease(activeObserver.executionId, readCurrentWorkflowLease(cwd)?.generation);
             activeContinuityRunId = buildRun.runId;
+            publishActivatedBuilderSession = ref => { buildRun = persistCurrentBuildSession(cwd, buildRun, "builder", ref); };
             const qaResumedRecovery = recoveryRecord && !isInterruptedBuilderRecovery(recoveryRecord) ? pendingQaRecoveryPacket(cwd, buildRun.runId, requestedTicketIds[0]) : undefined;
             let qaFinalizationTicket;
             let qaProtocolResumeTicket;
@@ -2347,19 +2401,38 @@ export function buildStartCommand(options = {}) {
             }
             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);
@@ -2417,7 +2490,13 @@ export function buildStartCommand(options = {}) {
                     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,
@@ -2433,7 +2512,7 @@ export function buildStartCommand(options = {}) {
                     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();
@@ -2455,7 +2534,7 @@ export function buildStartCommand(options = {}) {
                 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)}`);
@@ -2501,8 +2580,6 @@ export function buildStartCommand(options = {}) {
                         : 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"
@@ -2654,7 +2731,16 @@ export function buildStartCommand(options = {}) {
             }
             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", {
@@ -2721,7 +2807,7 @@ export function buildStartCommand(options = {}) {
                 }
                 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)}`);
             }
         }
@@ -2805,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(() => { });
@@ -2812,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(() => { });
@@ -2979,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/continuity.js

@@ -102,6 +102,7 @@ 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"}`,
+        "The continuity record is JSON. A requested STEP_STATUS line is separate plain text: never add JSON braces, a trailing comma, or a code fence to that status line.",
         ...(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");
@@ -177,13 +178,6 @@ export class ContinuityAdapter {
         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() });
-        }
-        finally {
-            db.close();
-        }
         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()}`;
@@ -209,6 +203,7 @@ export class ContinuityAdapter {
                     throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "a previous dispatched turn has no durable completion; reconcile it before sending more work");
                 journal.planOperation({ runId: this.options.runId, idempotencyKey: dispatchId, kind: "provider-dispatch", intent: { role: this.options.role, sessionRef: this.adapter.sessionRef?.(), instructionDigest: sha(instruction), instructionBytes: Buffer.byteLength(instruction) } });
                 journal.updateOperation(dispatchId, "in_progress");
+                journal.appendContinuityEvent({ runId: this.options.runId, role: "host", kind: "turn_started", payload: { role: this.options.role, dispatchId, instructionDigest: sha(instruction), instructionBytes: Buffer.byteLength(instruction) }, authoritativeStateRevision: this.revision() });
             });
             try {
                 original = await dispatchWithGraphAccess(this.options.projectDir, this.adapter, providerInstruction, policy, (text, p) => this.adapter.sendTurn(text, p));
@@ -218,7 +213,11 @@ export class ContinuityAdapter {
                 throw error;
             }
             const responseDigest = journal.putEvidence("handoff", original.rawResponse ?? original.text);
-            journal.updateOperation(dispatchId, original.failure?.dispatchState === "unknown" ? "uncertain" : "confirmed", { result: { responseDigest, isError: original.isError, failure: original.failure, turnId: original.turnId, sessionRef: this.adapter.sessionRef?.() } });
+            journal.atomic(() => {
+                journal.updateOperation(dispatchId, original.failure?.dispatchState === "unknown" ? "uncertain" : original.failure?.dispatchState === "not-sent" ? "failed" : "confirmed", { result: { responseDigest, isError: original.isError, failure: original.failure, turnId: original.turnId, sessionRef: this.adapter.sessionRef?.() } });
+                if (original.failure?.dispatchState === "not-sent")
+                    journal.appendContinuityEvent({ runId: this.options.runId, role: this.options.role, kind: "turn_not_sent", payload: { dispatchId, role: this.options.role }, authoritativeStateRevision: this.revision() });
+            });
         }
         finally {
             journal.close();
@@ -418,8 +417,10 @@ export class ContinuityAdapter {
         const db = new WorkflowDb(this.options.projectDir);
         try {
             const sessionRef = this.adapter.sessionRef?.();
-            db.appendContinuityEvent({ runId: this.options.runId, role: this.options.role, kind, payload: { isError: result.isError, numTurns: result.numTurns, sessionId: this.adapter.sessionId(), sessionRef, delta }, authoritativeStateRevision: this.revision(), sessionRef });
-            return db.publishContinuityCheckpoint({ runId: this.options.runId, role: this.options.role, delta, authoritativeStateRevision: this.revision(), sessionRef });
+            return db.atomic(() => {
+                db.appendContinuityEvent({ runId: this.options.runId, role: this.options.role, kind, payload: { isError: result.isError, numTurns: result.numTurns, sessionId: this.adapter.sessionId(), sessionRef, delta }, authoritativeStateRevision: this.revision(), sessionRef });
+                return db.publishContinuityCheckpoint({ runId: this.options.runId, role: this.options.role, delta, authoritativeStateRevision: this.revision(), sessionRef });
+            });
         }
         finally {
             db.close();

package/dist/foreman.d.ts

@@ -61,6 +61,9 @@ export interface ForemanNotificationOptions {
     terminalBell: boolean;
 }
 /** Drives one builder through a batch of N steps via the STEP_STATUS protocol. */
+export declare class BuildInterruptedError extends Error {
+    constructor();
+}
 export declare class Foreman {
     private builder;
     private readonly log;
@@ -88,6 +91,10 @@ export declare class Foreman {
     private readonly continueIndependentTickets;
     private readonly builderWorktree?;
     private readonly decisionPrompt?;
+    private interruptionRequested;
+    private activeQaAdapter?;
+    private assertNotInterrupted;
+    private createOwnedQa;
     private graphPurpose;
     setGraphPurpose(purpose: GraphPurpose): void;
     private readonly ticketsEnabled;
@@ -160,6 +167,7 @@ export declare class Foreman {
     builderSessionId(): string | undefined;
     builderAdapter(): BuilderAdapter;
     close(): Promise<void>;
+    requestStop(): Promise<void>;
     private ticketForQa;
     runBatch(n: number, trackerPath?: string, onTicketStart?: (ticketId: string) => void | Promise<void>, preferredTicketId?: string, recoveryTickets?: readonly string[]): Promise<BatchResult>;
 }