ai-foreman 1.6.2 → 1.7.0

package/dist/branch/runner.d.ts

@@ -1,4 +1,6 @@
 import type { BuilderAdapter, EffortLevel } from "../adapters/types.js";
+import type { SessionStrategy } from "rafi-spec";
+import { type QaNonconvergenceContext, type QaNonconvergenceDecision } from "../qaReview.js";
 import type { Log } from "../log.js";
 import type { BranchPlan, BranchPlanNode, BranchRunSummary, CompletionMode, MergeMethod, ReviewProvider } from "./types.js";
 export interface DeliveryUnitSession {
@@ -39,7 +41,11 @@ export interface BranchRunnerOptions {
         sessionId: string;
     }>;
     createBuilder: (cwd: string, sessionId?: string) => Promise<BuilderAdapter>;
+    createQa?: (cwd: string, sessionId?: string) => Promise<BuilderAdapter>;
+    builderSessionStrategy?: SessionStrategy;
+    qaSessionStrategy?: SessionStrategy;
     observeBuilder?: (builder: BuilderAdapter) => Promise<void>;
+    qaNonconvergence?: (context: QaNonconvergenceContext) => Promise<QaNonconvergenceDecision>;
 }
 export declare function runBranchPlan(opts: BranchRunnerOptions): Promise<BranchRunSummary[]>;
 export declare function buildBranchTicketInstruction(node: BranchPlanNode, trackerPaths?: {

package/dist/branch/runner.js

@@ -1,4 +1,6 @@
-import { Foreman, MARKER_SPEC } from "../foreman.js";
+import { buildDurableQaFixHandoff, compactWithRetry, runIsolatedQa } from "../qaReview.js";
+import { changeManifest } from "../qaSnapshot.js";
+import { Foreman, MARKER_SPEC, parseStepStatus } from "../foreman.js";
 import { fireNotification } from "../notify.js";
 import { cmdBlock, cmdComplete, cmdUpdate } from "../tickets/commands.js";
 import { commitAll, createTicketWorktree, findWorktreeForBranch, currentWorktreeBranch, deleteLocalBranch, ensureCleanBaseWorktree, ensureForemanExcluded, hasTrackerChanges, hasWorktreeChanges, headCommitIfAhead, removeTicketWorktree, mergeBranchToLocalBase, } from "./git.js";
@@ -6,6 +8,7 @@ import { checkGitHubPrMerged, createOrReusePr, enableGitHubAutoMerge, pushBranch
 import { checkGitLabMrMerged, createOrReuseMr, enableGitLabAutoMerge, pushBranchForMr } from "./gitlab.js";
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { WorkflowDb } from "../workflowDb.js";
 export function readDeliveryUnitSession(projectDir, unitId) {
     const path = deliverySessionPath(projectDir, unitId);
     if (!existsSync(path))
@@ -29,6 +32,9 @@ export async function runBranchPlan(opts) {
     const summaries = [];
     const successfulBranches = new Set();
     const pushedBranches = new Set();
+    let builderStreamSession;
+    let builderWorkSessions = 0;
+    const qaStream = { reviews: 0, modificationViolations: 0 };
     for (const issue of opts.plan.issues) {
         opts.log.write("branch-issue", { ...issue });
         notifyIssue(opts.notificationsEnabled, issue.message);
@@ -102,6 +108,7 @@ export async function runBranchPlan(opts) {
             base: node.baseBranch,
             dependencies: node.dependencies,
         });
+        workflowCheckpoint(opts.projectDir, opts.runId, "builder-before", node.ticket.id, { branch: node.branch, worktree: node.worktreePath });
         const resumeSession = opts.resumeSessions?.get(node.ticket.id);
         const worktreePath = resumeSession?.worktreePath
             ?? (sharedUnit ? findWorktreeForBranch(opts.projectDir, node.branch) : undefined)
@@ -119,16 +126,26 @@ export async function runBranchPlan(opts) {
                     sessionId: resumeSession.sessionId,
                 });
             }
-            cmdUpdate(opts.projectDir, node.ticket.id, {
-                status: "in_progress",
-                actor: "foreman",
+            journalTracker(opts.projectDir, opts.runId, `${opts.runId}:tracker-update:${node.ticket.id}:in-progress`, { ticket: node.ticket.id, status: "in_progress" }, () => cmdUpdate(opts.projectDir, node.ticket.id, {
+                status: "in_progress", actor: "foreman",
                 summary: resumeSession ? `Resuming branch ${node.branch}` : `Starting branch ${node.branch}`,
-            });
-            builder = await opts.createBuilder(worktreePath, resumeSession?.sessionId);
+            }));
+            const continuedBuilderSession = resumeSession?.sessionId ?? (opts.builderSessionStrategy === "compact" ? builderStreamSession : undefined);
+            builder = await opts.createBuilder(worktreePath, continuedBuilderSession);
+            if (opts.builderSessionStrategy === "compact" && builderWorkSessions > 0 && continuedBuilderSession) {
+                const compacted = await compactWithRetry(builder);
+                if (!compacted.ok) {
+                    await builder.close();
+                    builder = await opts.createBuilder(worktreePath);
+                }
+            }
+            builderWorkSessions += 1;
             viewer = opts.observeBuilder?.(builder);
             const foreman = new Foreman(builder, opts.log, opts.notificationsEnabled, opts.qaEnabled, 3, undefined);
             const { result, status } = await foreman.runInstruction(resumeSession ? buildBranchTicketResumeInstruction(node, opts.trackerPaths) : buildBranchTicketInstruction(node, opts.trackerPaths));
+            workflowCheckpoint(opts.projectDir, opts.runId, "builder-after", node.ticket.id, { status: status.kind, sessionId: builder.sessionId(), worktree: worktreePath });
             const sessionId = builder.sessionId();
+            builderStreamSession = opts.builderSessionStrategy === "compact" ? sessionId : undefined;
             if (sessionId) {
                 opts.log.write("branch-session", {
                     ticket: node.ticket.id,
@@ -169,19 +186,51 @@ export async function runBranchPlan(opts) {
             }
             if (status.kind !== "done" && status.kind !== "plan_complete") {
                 const detail = status.reason ?? status.error ?? `builder emitted ${status.kind}`;
-                cmdBlock(opts.projectDir, node.ticket.id, { summary: detail, actor: "foreman" });
+                journalTracker(opts.projectDir, opts.runId, `${opts.runId}:tracker-update:${node.ticket.id}:builder-block`, { ticket: node.ticket.id, status: "blocked", detail }, () => cmdBlock(opts.projectDir, node.ticket.id, { summary: detail, actor: "foreman" }));
                 summaries.push(summaryFor(node, status.kind === "blocked" ? "blocked" : "needs-human", detail));
                 continue;
             }
             let qaSummary;
+            let qaWaived = false;
             if (opts.qaEnabled) {
-                const qa = await foreman.runQaReview(summaries.length + 1);
-                if (qa.outcome !== "passed") {
+                if (!opts.createQa)
+                    throw new Error("independent disposable QA factory is required when QA is enabled");
+                workflowCheckpoint(opts.projectDir, opts.runId, "qa-before", node.ticket.id, { worktree: worktreePath });
+                const qa = await runIsolatedQa({
+                    ticket: node.ticket, builderWorktree: worktreePath, builderSummary: status.summary ?? result.text,
+                    qaStrategy: opts.qaSessionStrategy ?? "compact", state: qaStream, createQa: opts.createQa, maxCycles: 3,
+                    evidence: (entry) => opts.log.write("qa-evidence", { ticket: node.ticket.id, ...entry }),
+                    fix: async (issues) => {
+                        if (!builder)
+                            return { ok: false, detail: "Builder session unavailable" };
+                        builderWorkSessions += 1;
+                        if (opts.builderSessionStrategy === "compact" && builder.sessionId()) {
+                            const compacted = await compactWithRetry(builder);
+                            if (!compacted.ok) {
+                                await builder.close();
+                                builder = await opts.createBuilder(worktreePath);
+                            }
+                        }
+                        else if (opts.builderSessionStrategy === "fresh") {
+                            await builder.close();
+                            builder = await opts.createBuilder(worktreePath);
+                        }
+                        const digest = changeManifest(worktreePath).diffDigest;
+                        const fixed = await builder.sendTurn(buildDurableQaFixHandoff(node.ticket, issues, worktreePath, result.text, digest));
+                        const fixedStatus = parseStepStatus(fixed.text);
+                        builderStreamSession = opts.builderSessionStrategy === "compact" ? builder.sessionId() : undefined;
+                        return { ok: !fixed.isError && fixedStatus.kind === "done", detail: fixedStatus.error ?? fixed.text.slice(0, 500) };
+                    },
+                    onNonconvergence: opts.qaNonconvergence,
+                });
+                workflowCheckpoint(opts.projectDir, opts.runId, "qa-after", node.ticket.id, { outcome: qa.outcome, detail: qa.detail });
+                if (qa.outcome !== "passed" && qa.outcome !== "waived") {
                     const detail = qa.detail ?? "QA did not pass";
-                    cmdBlock(opts.projectDir, node.ticket.id, { summary: detail, actor: "foreman" });
+                    journalTracker(opts.projectDir, opts.runId, `${opts.runId}:tracker-update:${node.ticket.id}:qa-block`, { ticket: node.ticket.id, status: "blocked", detail }, () => cmdBlock(opts.projectDir, node.ticket.id, { summary: detail, actor: "foreman" }));
                     summaries.push(summaryFor(node, qa.outcome === "blocked" ? "blocked" : "needs-human", detail));
                     continue;
                 }
+                qaWaived = qa.outcome === "waived";
                 qaSummary = qa.summary;
             }
             else {
@@ -203,7 +252,18 @@ export async function runBranchPlan(opts) {
             }
             let commit;
             if (hasWorktreeChanges(worktreePath)) {
-                commit = commitAll(worktreePath, `${node.ticket.id}: ${node.ticket.title}`);
+                workflowCheckpoint(opts.projectDir, opts.runId, "commit-before", node.ticket.id, { branch: node.branch });
+                const operation = `${opts.runId}:commit:${node.ticket.id}`;
+                planJournal(opts.projectDir, opts.runId, operation, "commit", { ticket: node.ticket.id, branch: node.branch, worktreePath });
+                try {
+                    commit = commitAll(worktreePath, `${node.ticket.id}: ${node.ticket.title}`);
+                    confirmJournal(opts.projectDir, operation, commit, { sha: commit });
+                    workflowCheckpoint(opts.projectDir, opts.runId, "commit-after", node.ticket.id, { sha: commit });
+                }
+                catch (error) {
+                    failJournal(opts.projectDir, operation, error, false);
+                    throw error;
+                }
             }
             if (!commit && (createsReviewForNode || (completionMode === "direct-merge" && completesSharedUnit))) {
                 commit = headCommitIfAhead(worktreePath, node.baseBranch);
@@ -211,14 +271,20 @@ export async function runBranchPlan(opts) {
             const summary = summaryFor(node, "done", commit ? undefined : "no_changes");
             summary.commit = commit;
             if (commit && createsReviewForNode) {
+                workflowCheckpoint(opts.projectDir, opts.runId, "push-before", node.ticket.id, { branch: node.branch, sha: commit });
+                const pushOperation = `${opts.runId}:push:${node.branch}`;
+                planJournal(opts.projectDir, opts.runId, pushOperation, "push", { branch: node.branch, sha: commit, remote: "origin" });
                 const push = reviewProvider === "gitlab"
                     ? pushBranchForMr(worktreePath, node.branch)
                     : pushBranchForPr(worktreePath, node.branch);
                 if (push.ok) {
+                    confirmJournal(opts.projectDir, pushOperation, node.branch, { sha: commit });
                     opts.log.write("branch-push", { ticket: node.ticket.id, branch: node.branch, status: "pushed" });
                     summary.pushStatus = "pushed";
+                    workflowCheckpoint(opts.projectDir, opts.runId, "push-after", node.ticket.id, { branch: node.branch, sha: commit });
                 }
                 else {
+                    failJournal(opts.projectDir, pushOperation, push.message, push.code === "network_or_timeout");
                     summary.pushStatus = "failed";
                     summary.pr = {
                         status: "skipped",
@@ -244,6 +310,9 @@ export async function runBranchPlan(opts) {
                     continue;
                 }
                 pushedBranches.add(node.branch);
+                workflowCheckpoint(opts.projectDir, opts.runId, "review-creation-before", node.ticket.id, { provider: reviewProvider, head: node.branch, base: node.baseBranch });
+                const reviewOperation = `${opts.runId}:${reviewProvider === "gitlab" ? "mr" : "pr"}:${node.branch}:${node.baseBranch}`;
+                planJournal(opts.projectDir, opts.runId, reviewOperation, reviewProvider === "gitlab" ? "mr-create" : "pr-create", { head: node.branch, base: node.baseBranch, sha: commit });
                 const pr = reviewProvider === "gitlab"
                     ? createOrReuseMr(opts.projectDir, {
                         node,
@@ -263,6 +332,12 @@ export async function runBranchPlan(opts) {
                         commit,
                     });
                 summary.pr = pr;
+                if (pr.status === "created" || pr.status === "existing") {
+                    confirmJournal(opts.projectDir, reviewOperation, pr.url, { head: node.branch, base: node.baseBranch, url: pr.url });
+                    workflowCheckpoint(opts.projectDir, opts.runId, "review-creation-after", node.ticket.id, { provider: reviewProvider, head: node.branch, base: node.baseBranch, url: pr.url });
+                }
+                else if (pr.status === "failed")
+                    failJournal(opts.projectDir, reviewOperation, pr.message ?? pr.error ?? "review creation failed", pr.code === "network_or_timeout");
                 if (pr.status === "created")
                     opts.log.write(reviewProvider === "gitlab" ? "mr-created" : "pr-created", { ticket: node.ticket.id, branch: node.branch, url: pr.url });
                 if (pr.status === "existing")
@@ -314,13 +389,18 @@ export async function runBranchPlan(opts) {
                 if (opts.cleanupBranches ?? true)
                     deleteLocalBranch(opts.projectDir, node.branch);
             }
+            const completionOperation = `${opts.runId}:ticket-complete:${node.ticket.id}`;
+            workflowCheckpoint(opts.projectDir, opts.runId, "ticket-completion-before", node.ticket.id, { validationResult: qaWaived ? "failed" : opts.qaEnabled ? "passed" : "not_applicable" });
+            planJournal(opts.projectDir, opts.runId, completionOperation, "ticket-complete", { ticket: node.ticket.id });
             cmdComplete(opts.projectDir, node.ticket.id, {
                 actor: "foreman",
                 summary: status.summary ?? `Completed ${node.ticket.id}`,
-                validationResult: opts.qaEnabled ? "passed" : "not_applicable",
-                validationNotes: opts.qaEnabled ? "Foreman QA emitted qa_pass" : "Foreman QA disabled for this run",
-                evidence: opts.qaEnabled ? (qaSummary ?? "Foreman QA emitted qa_pass") : undefined,
+                validationResult: qaWaived ? "failed" : opts.qaEnabled ? "passed" : "not_applicable",
+                validationNotes: qaWaived ? "User explicitly waived unresolved QA failures" : opts.qaEnabled ? "Foreman QA emitted qa_pass" : "Foreman QA disabled for this run",
+                evidence: opts.qaEnabled ? (qaSummary ?? (qaWaived ? "Unresolved QA issues preserved in run evidence" : "Foreman QA emitted qa_pass")) : undefined,
             });
+            confirmJournal(opts.projectDir, completionOperation, node.ticket.id, { status: "done" });
+            workflowCheckpoint(opts.projectDir, opts.runId, "ticket-completion-after", node.ticket.id, { status: "done" });
             successfulBranches.add(node.ticket.id);
             summaries.push(summary);
             opts.log.write("branch-complete", {
@@ -344,7 +424,7 @@ export async function runBranchPlan(opts) {
                     : "builder_error";
             opts.log.write("branch-issue", { ticket: node.ticket.id, code, message, blocking: false });
             notifyIssue(opts.notificationsEnabled, `${node.ticket.id}: ${message}`);
-            cmdBlock(opts.projectDir, node.ticket.id, { summary: message, actor: "foreman" });
+            journalTracker(opts.projectDir, opts.runId, `${opts.runId}:tracker-update:${node.ticket.id}:runtime-block`, { ticket: node.ticket.id, status: "blocked", detail: message }, () => cmdBlock(opts.projectDir, node.ticket.id, { summary: message, actor: "foreman" }));
             summaries.push(summaryFor(node, "blocked", message));
         }
         finally {
@@ -354,6 +434,59 @@ export async function runBranchPlan(opts) {
     }
     return summaries;
 }
+function planJournal(projectDir, runId, key, kind, intent) {
+    const db = new WorkflowDb(projectDir);
+    try {
+        if (!db.getRun(runId))
+            db.createRun({ runId, kind: "build", originalWork: {}, state: {} });
+        db.planOperation({ runId, idempotencyKey: key, kind, intent });
+        db.updateOperation(key, "in_progress");
+    }
+    finally {
+        db.close();
+    }
+}
+function confirmJournal(projectDir, key, externalId, result) {
+    const db = new WorkflowDb(projectDir);
+    try {
+        db.updateOperation(key, "confirmed", { externalId, result });
+    }
+    finally {
+        db.close();
+    }
+}
+function failJournal(projectDir, key, error, uncertain) {
+    const db = new WorkflowDb(projectDir);
+    try {
+        db.updateOperation(key, uncertain ? "uncertain" : "failed", { error: error instanceof Error ? error.message : String(error) });
+    }
+    finally {
+        db.close();
+    }
+}
+function journalTracker(projectDir, runId, key, intent, action) {
+    planJournal(projectDir, runId, key, "tracker-update", intent);
+    try {
+        action();
+        confirmJournal(projectDir, key, undefined, intent);
+    }
+    catch (error) {
+        failJournal(projectDir, key, error, false);
+        throw error;
+    }
+}
+function workflowCheckpoint(projectDir, runId, checkpoint, ticket, payload) {
+    const db = new WorkflowDb(projectDir);
+    try {
+        const run = db.getRun(runId);
+        if (!run)
+            return;
+        db.transition(runId, { checkpoint, state: { ...run.state, currentTicket: ticket, ...payload }, event: checkpoint, payload: { ticket, ...payload } });
+    }
+    finally {
+        db.close();
+    }
+}
 async function waitForAutoMergeDependencies(opts, node, provider) {
     const dependencyNodes = node.dependencies
         .map((dep) => opts.plan.nodes.find((candidate) => candidate.ticket.id === dep))
@@ -435,7 +568,7 @@ function blockBranchIssue(opts, node, summary, code, message, details) {
         output: details?.output,
     });
     notifyIssue(opts.notificationsEnabled, `${node.ticket.id}: ${message}`);
-    cmdBlock(opts.projectDir, node.ticket.id, { summary: message, actor: "foreman" });
+    journalTracker(opts.projectDir, opts.runId, `${opts.runId}:tracker-update:${node.ticket.id}:remote-block`, { ticket: node.ticket.id, status: "blocked", detail: message }, () => cmdBlock(opts.projectDir, node.ticket.id, { summary: message, actor: "foreman" }));
 }
 function failureLogFields(node, pr) {
     return {

package/dist/buildRuns.d.ts

@@ -12,11 +12,17 @@ export interface CreateBuildRunInput {
     branch?: string;
     baseHead?: string;
     startHead?: string;
-    builder?: ResolvedAgentSettings;
-    qa?: ResolvedAgentSettings;
+    builder?: LegacyResolvedAgentSettings;
+    qa?: LegacyResolvedAgentSettings;
     now?: Date;
 }
 export declare function createBuildRun(input: CreateBuildRunInput): BuildRunRecordV1;
+export declare function resumeBuildRun(projectDir: string, runId: string, patch: {
+    builder?: LegacyResolvedAgentSettings;
+    qa?: LegacyResolvedAgentSettings;
+    builderSessionId?: string | null;
+}, now?: Date): BuildRunRecordV1;
+type LegacyResolvedAgentSettings = Omit<ResolvedAgentSettings, "session_strategy" | "settings_revision"> & Partial<Pick<ResolvedAgentSettings, "session_strategy" | "settings_revision">>;
 export declare function saveBuildRun(projectDir: string, run: BuildRunRecordV1, now?: Date): BuildRunRecordV1;
 export declare function checkpointBuildRun(projectDir: string, run: BuildRunRecordV1, checkpoint: string, patch?: Partial<BuildRunRecordV1>): BuildRunRecordV1;
 export declare function persistBuildSession(projectDir: string, run: BuildRunRecordV1, role: "builder" | "qa", sessionId: string): BuildRunRecordV1;
@@ -33,3 +39,4 @@ export declare function recoverableBuildRuns(projectDir: string, now?: Date): Ar
 }>;
 export declare function isLeaseActive(run: BuildRunRecordV1, now?: Date): boolean;
 export declare function buildRecoveryPreview(run: BuildRunRecordV1): string[];
+export {};

package/dist/buildRuns.js

@@ -2,6 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { hostname } from "node:os";
 import { join, resolve } from "node:path";
+import { WorkflowDb } from "./workflowDb.js";
 export const BUILD_RUN_VERSION = 1;
 export const BUILD_RUN_DIRECTORY = ".foreman/runs";
 export const BUILD_HEARTBEAT_MS = 10_000;
@@ -18,8 +19,8 @@ export function createBuildRun(input) {
         branchMode: input.branchMode ?? "current",
         checkpoint: "created",
         currentTicket: input.tickets[0],
-        builder: input.builder ? { settings: input.builder } : undefined,
-        qa: input.qa ? { settings: input.qa } : undefined,
+        builder: input.builder ? { settings: normalizeCapturedSettings(input.builder) } : undefined,
+        qa: input.qa ? { settings: normalizeCapturedSettings(input.qa) } : undefined,
         repository: {
             root: resolve(input.repositoryRoot),
             worktree: resolve(input.worktree ?? input.repositoryRoot),
@@ -33,7 +34,38 @@ export function createBuildRun(input) {
         createdAt: stamp,
         updatedAt: stamp,
     };
-    return saveBuildRun(input.repositoryRoot, run, now);
+    const saved = saveBuildRun(input.repositoryRoot, run, now);
+    const workflow = new WorkflowDb(input.repositoryRoot);
+    try {
+        workflow.acquireLease(saved.runId, undefined, now, BUILD_LEASE_STALE_MS);
+    }
+    finally {
+        workflow.close();
+    }
+    return saved;
+}
+export function resumeBuildRun(projectDir, runId, patch, now = new Date()) {
+    const existing = readBuildRuns(projectDir).find((run) => run.runId === runId);
+    if (!existing)
+        throw new Error(`recoverable build run not found: ${runId}`);
+    if (existing.status === "completed")
+        throw new Error(`build run ${runId} is already complete`);
+    const workflow = new WorkflowDb(projectDir);
+    try {
+        workflow.acquireLease(runId, undefined, now, BUILD_LEASE_STALE_MS);
+    }
+    finally {
+        workflow.close();
+    }
+    return saveBuildRun(projectDir, {
+        ...existing, status: "running", checkpoint: "recovery-resumed", completedAt: undefined,
+        builder: patch.builder ? { settings: normalizeCapturedSettings(patch.builder), ...(patch.builderSessionId === null ? {} : { sessionId: patch.builderSessionId ?? existing.builder?.sessionId }) } : existing.builder,
+        qa: patch.qa ? { settings: normalizeCapturedSettings(patch.qa), sessionId: existing.qa?.sessionId } : existing.qa,
+        lease: currentLease(now),
+    }, now);
+}
+function normalizeCapturedSettings(settings) {
+    return { ...settings, session_strategy: settings.session_strategy ?? (["builder", "qa", "ticket-maker"].includes(settings.role) ? "compact" : "fresh"), settings_revision: settings.settings_revision ?? 0 };
 }
 export function saveBuildRun(projectDir, run, now = new Date()) {
     validateBuildRun(run);
@@ -44,6 +76,28 @@ export function saveBuildRun(projectDir, run, now = new Date()) {
     const temp = `${target}.${process.pid}.${randomUUID()}.tmp`;
     writeFileSync(temp, `${JSON.stringify(next, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
     renameSync(temp, target);
+    const workflow = new WorkflowDb(projectDir);
+    try {
+        const existing = workflow.getRun(next.runId);
+        if (!existing)
+            workflow.createRun({
+                runId: next.runId, kind: "build", checkpoint: next.checkpoint,
+                originalWork: { tickets: next.tickets, deliveryUnit: next.deliveryUnit, branchMode: next.branchMode },
+                remainingWork: { tickets: remainingTickets(next) }, state: next,
+            }, now);
+        else
+            workflow.transition(next.runId, {
+                status: workflowStatus(next.status), checkpoint: next.checkpoint,
+                remainingWork: { tickets: remainingTickets(next) }, state: next, event: "build_snapshot",
+            }, now);
+        if (next.builder?.sessionId)
+            workflow.recordSession(next.runId, "builder", "builder", next.builder.sessionId, "checkpoint", next.builder.settings, now);
+        if (next.qa?.sessionId)
+            workflow.recordSession(next.runId, "qa", "qa", next.qa.sessionId, "checkpoint", next.qa.settings, now);
+    }
+    finally {
+        workflow.close();
+    }
     return next;
 }
 export function checkpointBuildRun(projectDir, run, checkpoint, patch = {}) {
@@ -58,19 +112,42 @@ export function persistBuildSession(projectDir, run, role, sessionId) {
 export function recordBuildReceipt(projectDir, run, operationId, detail) {
     if (run.receipts[operationId])
         return run;
-    return saveBuildRun(projectDir, {
+    const next = saveBuildRun(projectDir, {
         ...run,
         receipts: { ...run.receipts, [operationId]: { completedAt: new Date().toISOString(), ...detail } },
     });
+    const workflow = new WorkflowDb(projectDir);
+    try {
+        workflow.planOperation({ runId: run.runId, idempotencyKey: operationId, kind: operationId.split(":", 1)[0] ?? "operation", intent: { checkpoint: run.checkpoint } });
+        workflow.updateOperation(operationId, "confirmed", { externalId: detail?.externalId, result: { detail: detail?.detail } });
+    }
+    finally {
+        workflow.close();
+    }
+    return next;
 }
 export function heartbeatBuildRun(projectDir, run, now = new Date()) {
-    return saveBuildRun(projectDir, { ...run, lease: { ...(run.lease ?? currentLease(now)), heartbeatAt: now.toISOString() } }, now);
+    const saved = saveBuildRun(projectDir, { ...run, lease: { ...(run.lease ?? currentLease(now)), heartbeatAt: now.toISOString() } }, now);
+    const workflow = new WorkflowDb(projectDir);
+    try {
+        const lease = workflow.currentLease();
+        if (lease?.runId === run.runId)
+            workflow.heartbeatLease(lease, now);
+    }
+    finally {
+        workflow.close();
+    }
+    return saved;
 }
 export function releaseBuildLease(projectDir, run, status = "interrupted") {
-    return saveBuildRun(projectDir, { ...run, status, lease: undefined });
+    const saved = saveBuildRun(projectDir, { ...run, status, lease: undefined });
+    releaseWorkflowLease(projectDir, run.runId);
+    return saved;
 }
 export function completeBuildRun(projectDir, run, now = new Date()) {
-    return saveBuildRun(projectDir, { ...run, status: "completed", checkpoint: "complete", lease: undefined, completedAt: now.toISOString() }, now);
+    const saved = saveBuildRun(projectDir, { ...run, status: "completed", checkpoint: "complete", lease: undefined, completedAt: now.toISOString() }, now);
+    releaseWorkflowLease(projectDir, run.runId, now);
+    return saved;
 }
 export function readBuildRuns(projectDir) {
     const directory = join(resolve(projectDir), BUILD_RUN_DIRECTORY);
@@ -147,3 +224,29 @@ function validateBuildRun(run) {
         throw new Error("invalid build run record");
     }
 }
+function workflowStatus(status) {
+    if (status === "completed")
+        return "completed";
+    if (status === "failed")
+        return "failed";
+    if (status === "blocked")
+        return "blocked";
+    if (status === "interrupted" || status === "recoverable")
+        return "paused";
+    return "running";
+}
+function remainingTickets(run) {
+    const current = run.currentTicket ? run.tickets.indexOf(run.currentTicket) : 0;
+    return run.status === "completed" ? [] : run.tickets.slice(Math.max(0, current));
+}
+function releaseWorkflowLease(projectDir, runId, now = new Date()) {
+    const workflow = new WorkflowDb(projectDir);
+    try {
+        const lease = workflow.currentLease();
+        if (lease?.runId === runId)
+            workflow.releaseLease(lease, now);
+    }
+    finally {
+        workflow.close();
+    }
+}

package/dist/cli/start.d.ts

@@ -1,4 +1,8 @@
 import { Command } from "commander";
+import type { BranchPlan } from "../branch/types.js";
+import { type DeliveryConfig, type DeliveryStack } from "../tickets/delivery.js";
 export declare function formatStartResumeCommand(executable: "ai-foreman", projectDir: string, steps: number, sessionId: string): string;
 export declare function formatResumeGuidance(executable: "rafi" | "ai-foreman", projectDir: string, steps: number, sessionId?: string): string[];
 export declare function buildStartCommand(): Command;
+/** 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;