ai-foreman 1.7.20 → 1.7.22

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 {};

package/dist/buildAssignment.js

@@ -0,0 +1,215 @@
+import { assertBuilderContractCoverage } from "./qaBuilderCoverage.js";
+import { resolveEffectiveQaConfiguration } from "./qaEffectiveConfig.js";
+import { contractDigest } from "./qaVerificationContract.js";
+import { queueGraphMaintenance } from "./graph/boundary.js";
+import { actualContractSession, assertContractReceipt } from "./qaContractDelivery.js";
+import { createHash, randomUUID } from "node:crypto";
+import { lstatSync, readFileSync, readdirSync, readlinkSync, realpathSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { captureFrozenQaSource } from "./qaSnapshot.js";
+import { WorkflowDb } from "./workflowDb.js";
+import { WorkflowReader } from "./workflowReader.js";
+/** Work responses confirm an assignment; they never select the next ticket. */
+export function validateBuildAssignment(ticketId, status, responseText = "") {
+    // An unmarked response may receive the existing bounded response-only repair.
+    // Explicit foreign markers must not be erased by a parser error or correction.
+    const named = [...responseText.matchAll(/\bticket="([^"]*)"/g)].map(match => match[1]);
+    if (status.kind === "unknown" && !status.ticket && named.every(id => id === ticketId))
+        return undefined;
+    if (status.ticket !== ticketId) {
+        return `Builder response named ${status.ticket ?? "no ticket"}, but this turn was assigned to ${ticketId}. Preserved work requires ownership reconciliation before further execution.`;
+    }
+    if (status.kind === "qa_pass" || status.kind === "qa_fail")
+        return `Builder emitted QA status ${status.kind} for assigned ticket ${ticketId}; independent QA is required.`;
+    return undefined;
+}
+export class BuildAssignmentRejected extends Error {
+}
+export function assertBuildAssignmentReconciled(projectDir, runId, worktree = projectDir) {
+    const reader = new WorkflowReader(projectDir);
+    try {
+        const runs = [...new Set([runId, ...reader.buildRuns(true).map(run => run.runId)])];
+        for (const operation of runs.flatMap(id => reader.operations(id, true))) {
+            if (operation.kind !== "build-assignment")
+                continue;
+            const result = operation.result;
+            if (result?.reconciliationId)
+                continue;
+            if (!result?.rejection && !result?.sourceError && operation.status !== "in_progress" && operation.status !== "uncertain")
+                continue;
+            const intent = operation.intent;
+            if (operation.runId !== runId) {
+                if (!intent.worktree)
+                    continue;
+                try {
+                    if (realpathSync(intent.worktree) !== realpathSync(worktree))
+                        continue;
+                }
+                catch {
+                    if (resolve(intent.worktree) !== resolve(worktree))
+                        continue;
+                }
+            }
+            if (result?.rejection || result?.sourceError || operation.status === "in_progress" || operation.status === "uncertain") {
+                throw new BuildAssignmentRejected(`Build ${runId} requires assignment reconciliation for ${operation.idempotencyKey}: ${result?.rejection ?? result?.sourceError ?? "provider dispatch outcome is unconfirmed"}. Inspect with rafi manager --ask '/qa-conflicts ${runId}'.`);
+            }
+        }
+    }
+    finally {
+        reader.close();
+    }
+}
+/** Commit response/source bytes before interpreting any scoped outcome. */
+export function beginBuildAssignment(projectDir, runId, ticketId, worktree, instruction, followup, adapter) {
+    assertBuildAssignmentReconciled(projectDir, runId, worktree);
+    const operationId = `build-assignment:${runId}:${randomUUID()}`;
+    const db = new WorkflowDb(projectDir);
+    try {
+        const before = captureBuildSource(worktree);
+        let guidance = { text: instruction, ids: [] };
+        db.atomic(() => {
+            db.ensureRun(runId);
+            const admission = db.assertAdmittedWork(runId, ticketId);
+            let contractBinding;
+            if (db.qaPreparationStore().policy(runId)?.mode === "enforce") {
+                const contract = assertContractReceipt(db.qaPreparationStore(), runId, ticketId, admission.requirementsDigest, adapter ? actualContractSession(adapter, worktree, projectDir) : undefined, adapter);
+                const session = actualContractSession(adapter, worktree, projectDir);
+                const receipt = db.qaPreparationStore().receipts(contract.contentDigest).find(row => row.sessionId === session.sessionId && row.generation === session.generation && row.workspace === session.workspace && row.compactionSequence === session.compactionSequence);
+                contractBinding = { digest: contract.contentDigest, revision: contract.revision, receiptOperationId: receipt.operationId, session };
+                const qaMake = db.getRun(runId)?.state?.qa?.settings?.make ?? adapter.agent;
+                const current = resolveEffectiveQaConfiguration(projectDir, { make: qaMake });
+                if (contract.inputs.find(input => input.kind === "rules")?.digest !== current.digest || contract.inputs.find(input => input.kind === "checklist")?.digest !== contractDigest("input-checklist", current.checklist))
+                    throw new BuildAssignmentRejected("Canonical QA rules, skills or checklist changed after delivery; reconcile the contract before implementation");
+            }
+            guidance = db.reserveGuidance(runId, ticketId, "builder", operationId, before.digest, instruction);
+            if (followup) {
+                if (admission.requirementsDigest !== followup.requirementsDigest)
+                    throw new BuildAssignmentRejected("Ticket requirements changed; renewed scope approval is required before the Builder follow-up");
+                if (!guidance.ids.length)
+                    throw new BuildAssignmentRejected("No eligible Builder guidance remains; no follow-up was dispatched");
+                const latest = db.qaReviewAttempts(runId, ticketId).at(-1);
+                const head = db.qaTicketHead(runId, ticketId);
+                if (latest?.attemptId !== followup.reviewAttemptId || latest.status !== "passed" || head.state !== "passed")
+                    throw new BuildAssignmentRejected("Builder follow-up requires the current unfinalized QA pass");
+                db.reserveQaRemediation(runId, ticketId, latest.attemptId, operationId, followup.maximum, followup.authorizationId);
+                db.invalidateUnconsumedQaPassCertificates(runId, ticketId, "builder-guidance-followup");
+                db.transitionQa(runId, ticketId, head.revision, { type: "builder-guidance-followup-intended" });
+            }
+            const instructionDigest = db.putEvidence("qa", Buffer.from(guidance.text));
+            db.planOperation({ runId, idempotencyKey: operationId, kind: "build-assignment", intent: { ticketId, worktree, admissionId: admission.assignmentId, requirementsDigest: admission.requirementsDigest, instructionDigest, ...(contractBinding ? { contractBinding } : {}), before: retainSource(db, before), ...(followup ? { managerFollowup: followup } : {}) } });
+            db.recordWorkAssignment(runId, ticketId, operationId, { requirementsDigest: admission.requirementsDigest, worktree, sourceDigest: before.digest, ownerGeneration: db.currentLease()?.generation, instructionDigest });
+            db.updateOperation(operationId, "in_progress");
+        });
+        return { operationId, runId, ticketId, worktree, before, instruction: guidance.text, guidanceIds: guidance.ids };
+    }
+    finally {
+        db.close();
+    }
+}
+export function finishBuildAssignment(projectDir, assignment, result, status) {
+    let rejection = result.failure?.dispatchState === "not-sent" ? undefined : validateBuildAssignment(assignment.ticketId, status, result.text);
+    // Source capture can fail after an external turn. Keep the response even then.
+    let after;
+    let sourceError;
+    try {
+        after = captureBuildSource(assignment.worktree);
+    }
+    catch (error) {
+        sourceError = error instanceof Error ? error.message : String(error);
+    }
+    if (result.failure?.dispatchState === "not-sent" && after && after.contentDigest !== assignment.before.contentDigest)
+        rejection = "Provider claimed an unsubmitted turn but product source changed; reconcile the captured source before continuing";
+    const db = new WorkflowDb(projectDir);
+    try {
+        db.atomic(() => {
+            if (!rejection && !result.isError && !result.failure && ["done", "plan_complete"].includes(status.kind) && after) {
+                try {
+                    assertBuilderContractCoverage(db, assignment.runId, assignment.ticketId, assignment.operationId, after.digest);
+                }
+                catch (error) {
+                    rejection = String(error);
+                }
+            }
+            const responseDigest = db.putEvidence("qa", Buffer.from(result.rawResponse ?? result.text));
+            const cleanedResponseDigest = db.putEvidence("qa", Buffer.from(result.cleanedResponse ?? result.text));
+            const providerInstructionDigest = result.providerInstruction ? db.putEvidence("qa", Buffer.from(result.providerInstruction)) : undefined;
+            db.updateOperation(assignment.operationId, result.failure?.dispatchState === "unknown" || result.isError && !result.failure?.dispatchState && status.kind === "unknown" ? "uncertain" : "confirmed", { result: { turnId: result.turnId, responseDigest, cleanedResponseDigest, providerInstructionDigest, providerMetadata: result.providerMetadata, dispatchState: result.failure?.dispatchState, status, rejection, sourceError, after: after ? retainSource(db, after) : undefined } });
+            const admission = db.assertAdmittedWork(assignment.runId, assignment.ticketId);
+            db.qaPreparationStore().metric(assignment.runId, assignment.ticketId, admission.requirementsDigest, `metric:builder-result:${assignment.operationId}`, "phase-observation", { phase: "builder", durationMs: Math.max(0, Date.now() - Date.parse(assignment.before.capturedAt)), costUsd: result.costAuthoritative ? result.costUsd : null, inputTokens: result.inputTokens ?? null, outputTokens: result.outputTokens ?? null });
+            db.finishGuidance(assignment.guidanceIds, "builder", { submitted: result.failure?.dispatchState === "not-sent" ? false : result.turnId ? true : undefined, receipt: result.turnId ? { turnId: result.turnId, responseDigest, providerInstructionDigest, postSourceDigest: after?.digest } : undefined, applied: !rejection && status.kind === "done" && assignment.guidanceIds.every(id => result.text.includes(id)) });
+            if (rejection || sourceError) {
+                const run = db.getRun(assignment.runId);
+                db.transition(assignment.runId, { checkpoint: "build-assignment-rejected", state: { ...run.state, assignmentConflict: { operationId: assignment.operationId, ticketId: assignment.ticketId, worktree: assignment.worktree, responseDigest, rejection, sourceError } }, event: "build_assignment_rejected", payload: { operationId: assignment.operationId, ticketId: assignment.ticketId, returnedTicketId: status.ticket, responseDigest, rejection, sourceError } });
+            }
+        });
+    }
+    finally {
+        db.close();
+    }
+    if (!rejection && !sourceError && !result.isError && status.kind === "done" && after) {
+        try {
+            queueGraphMaintenance(projectDir, assignment.worktree, assignment.operationId, result.text, after.contentDigest !== assignment.before.contentDigest);
+        }
+        catch (error) {
+            console.error(`Graph maintenance deferred: ${String(error)}`);
+        }
+    }
+    return rejection ?? (sourceError ? `Builder source evidence is unavailable: ${sourceError}. Reconcile before continuing.` : undefined);
+}
+function retainSource(db, source) {
+    const staged = retainDiff(db, source.stagedDiff);
+    const unstaged = retainDiff(db, source.unstagedDiff);
+    return { digest: source.digest, head: source.head, captureMode: source.captureMode, omissions: source.omissions, contentDigest: source.contentDigest, capturedAt: source.capturedAt, pathInventory: source.pathInventory,
+        stagedDiffDigest: staged.digest, stagedDiffChunks: staged.chunks, stagedDiffBytes: source.stagedDiff.length,
+        unstagedDiffDigest: unstaged.digest, unstagedDiffChunks: unstaged.chunks, unstagedDiffBytes: source.unstagedDiff.length,
+        untracked: source.untracked.map(file => { const evidence = retainDiff(db, file.bytes); return { path: file.path, mode: file.mode, kind: file.kind, digest: file.digest, evidenceDigest: evidence.digest, evidenceChunks: evidence.chunks, byteLength: file.bytes.length }; }) };
+}
+/** Preserve large product files without changing the shared per-item evidence limits. */
+function retainDiff(db, bytes) {
+    if (bytes.length <= 16 * 1024 * 1024)
+        return { digest: db.putEvidence("diff", bytes) };
+    const chunks = [];
+    for (let offset = 0; offset < bytes.length; offset += 8 * 1024 * 1024)
+        chunks.push(db.putEvidence("diff", bytes.subarray(offset, offset + 8 * 1024 * 1024)));
+    return { chunks };
+}
+export function captureBuildSource(worktree) {
+    const head = spawnSync("git", ["-C", worktree, "rev-parse", "--verify", "HEAD"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    if (head.status === 0)
+        return { ...captureFrozenQaSource(worktree), captureMode: "git" };
+    if (head.error?.code !== "ENOENT" && !/not a git repository|Needed a single revision|unknown revision/.test(head.stderr ?? ""))
+        throw head.error ?? new Error(`Git source identity is unavailable: ${head.stderr}`);
+    const capture = () => {
+        const root = resolve(worktree);
+        const untracked = [];
+        const ignored = new Set([".git", ".rafi", ".foreman", "node_modules"]);
+        const visit = (directory) => {
+            for (const entry of readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+                if (ignored.has(entry.name))
+                    continue;
+                const path = join(directory, entry.name);
+                if (entry.isDirectory())
+                    visit(path);
+                else if (entry.isFile() || entry.isSymbolicLink()) {
+                    const kind = entry.isSymbolicLink() ? "symlink" : "file";
+                    const bytes = kind === "symlink" ? Buffer.from(readlinkSync(path)) : readFileSync(path);
+                    untracked.push({ path: relative(root, path).replace(/\\/g, "/"), kind, bytes, mode: lstatSync(path).mode, digest: createHash("sha256").update(bytes).digest("hex") });
+                }
+                else
+                    throw new Error(`Unsupported source path type: ${path}`);
+            }
+        };
+        visit(root);
+        const contentDigest = createHash("sha256").update(JSON.stringify(untracked.map(({ bytes: _, ...identity }) => identity))).digest("hex");
+        return { digest: contentDigest, head: "unavailable", captureMode: "filesystem", omissions: ["Git baseline/diff unavailable: project is not a repository or has no first commit"], contentDigest, capturedAt: new Date().toISOString(),
+            pathInventory: untracked.map(file => ({ path: file.path, staged: [], unstaged: [], untracked: { kind: file.kind, mode: file.mode, digest: file.digest } })), untracked, stagedDiff: Buffer.alloc(0), unstagedDiff: Buffer.alloc(0) };
+    };
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const before = capture();
+        const after = capture();
+        if (before.digest === after.digest)
+            return after;
+    }
+    throw new Error("Product source changed during assignment evidence capture; retry at a stable boundary");
+}

package/dist/buildInterventions.d.ts

@@ -0,0 +1,90 @@
+import Database from "better-sqlite3";
+import type { ManagerActionRequestV1 } from "rafi-spec";
+export type InstructionRecipient = "builder" | "qa";
+export type InstructionState = "queued" | "reserved" | "delivered" | "acknowledged" | "applied" | "verified" | "uncertain" | "rejected" | "superseded" | "withdrawn";
+export interface BuildInstruction {
+    instructionId: string;
+    request: ManagerActionRequestV1;
+    sequence: number;
+    userTurn: string;
+    textDigest: string;
+    requirementsDigest: string;
+    createdAt: string;
+    basis: {
+        assignmentId: string;
+        scopeRevision: string;
+        reviewAttemptId?: string;
+        sourceDigest?: string;
+    };
+    deliveries: Array<{
+        recipient: InstructionRecipient;
+        state: InstructionState;
+        operationId?: string;
+        sourceDigest?: string;
+        instructionDigest?: string;
+        receipt?: unknown;
+        detail?: string;
+    }>;
+}
+export declare class BuildControlBoundary extends Error {
+}
+export declare function migrateBuildInterventions(db: Database.Database): void;
+/** Questions belong to work through their ticket interruption or retained remediation stop. */
+export declare function decisionBelongsToWork(decision: {
+    decisionId: string;
+    runId: string;
+    interruptionId: string;
+}, runId: string, workId: string, stops: Array<{
+    runId: string;
+    workId: string;
+    operationId: string;
+    decisionId?: string;
+}>): boolean;
+export declare function decisionWorkId(db: Database.Database, decision: {
+    decisionId: string;
+    runId: string;
+    interruptionId: string;
+}): string | undefined;
+/** A proposal never authorizes itself. Only exact commands from the original user turn do. */
+export declare function parseManagerAction(userTurn: string, requestId?: string, expectedRevision?: number): ManagerActionRequestV1 | undefined;
+/** Narrow write capability coexists with a build lease and cannot dispatch or publish workflow state. */
+export declare class BuildInterventionControl {
+    private readonly runId;
+    private readonly workId;
+    private readonly db;
+    constructor(projectDir: string, runId: string, workId: string);
+    close(): void;
+    revision(): number;
+    enqueue(request: ManagerActionRequestV1, userTurn: string): BuildInstruction;
+}
+export declare function instruction(db: Database.Database, id: string): BuildInstruction | undefined;
+/** Restart consumes retained completion proof, never sends a replacement provider turn. */
+export declare function reconcileGuidance(db: Database.Database, runId: string, workId: string): void;
+export declare function queuedControls(db: Database.Database, runId: string, workId: string): BuildInstruction[];
+export declare function hasQueuedBuilderGuidance(db: Database.Database, runId: string, workId: string): boolean;
+export declare function completeControl(db: Database.Database, id: string, receipt: unknown, rejection?: string): void;
+export declare function assertFinalizationControls(db: Database.Database, runId: string, workId: string): void;
+export declare function builderVerificationContext(db: Database.Database, runId: string, workId: string, sourceDigest: string): {
+    text: string;
+    ids: string[];
+};
+export declare function verifyBuilderGuidance(db: Database.Database, ids: string[], certificate: {
+    certificateId: string;
+    sourceStateDigest: string;
+    reviewBasisDigest: string;
+}, response: string, turnReceiptDigest: string): void;
+/** Called only inside the owning process's existing dispatch transaction. */
+export declare function reserveGuidance(db: Database.Database, runId: string, workId: string, recipient: InstructionRecipient, operationId: string, sourceDigest: string, instructionText: string, reserve?: boolean): {
+    text: string;
+    ids: string[];
+};
+export declare function finishGuidance(db: Database.Database, ids: string[], recipient: InstructionRecipient, result: {
+    submitted: boolean | undefined;
+    receipt?: unknown;
+    applied?: boolean;
+}): void;
+export declare function verifyGuidance(db: Database.Database, ids: string[], certificate: {
+    certificateId: string;
+    sourceStateDigest: string;
+    reviewBasisDigest: string;
+}, response: string): void;