ai-foreman 1.7.4 → 1.7.6

package/dist/branch/github.js

@@ -1,6 +1,8 @@
 import { spawnSync } from "node:child_process";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { branchNodeFooter } from "./presentation.js";
+import { configuredReviewBody, configuredReviewTitle } from "../tickets/reviewStandards.js";
 const DEFAULT_COMMAND_TIMEOUT_MS = 15_000;
 const OUTPUT_LIMIT = 2_000;
 function runCommand(cwd, bin, args, timeoutMs = DEFAULT_COMMAND_TIMEOUT_MS) {
@@ -133,7 +135,7 @@ export function createOrReusePr(cwd, opts) {
     const bodyPath = join(cwd, ".foreman", "pr-bodies", opts.runId, `${opts.node.ticket.id}.md`);
     try {
         mkdirSync(join(cwd, ".foreman", "pr-bodies", opts.runId), { recursive: true });
-        writeFileSync(bodyPath, buildPrBody(opts), "utf8");
+        writeFileSync(bodyPath, configuredReviewBody(cwd, opts.node, opts.qaEvidence, opts.commit), "utf8");
     }
     catch (err) {
         return prFailure(prBodyWriteFailure(opts.runId, bodyPath, err));
@@ -146,7 +148,7 @@ export function createOrReusePr(cwd, opts) {
         "--head",
         opts.node.branch,
         "--title",
-        `${opts.node.ticket.id}: ${opts.node.ticket.title}`,
+        configuredReviewTitle(cwd, opts.node.ticket),
         "--body-file",
         bodyPath,
     ];
@@ -440,7 +442,7 @@ function buildPrBody(opts) {
         `- Dependencies: ${opts.node.dependencies.length ? opts.node.dependencies.join(", ") : "None"}`,
         `- Commit: ${opts.commit ?? "N/A"}`,
         "",
-        "Generated by Rafi ai-foreman branch-per-ticket mode.",
+        branchNodeFooter(opts.node),
         "",
     ].join("\n");
 }

package/dist/branch/gitlab.js

@@ -1,6 +1,8 @@
 import { spawnSync } from "node:child_process";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { branchNodeFooter } from "./presentation.js";
+import { configuredReviewBody, configuredReviewTitle } from "../tickets/reviewStandards.js";
 const DEFAULT_COMMAND_TIMEOUT_MS = 15_000;
 const OUTPUT_LIMIT = 2_000;
 export function preflightGlab(cwd) {
@@ -54,7 +56,7 @@ export function createOrReuseMr(cwd, opts) {
     const bodyPath = join(cwd, ".foreman", "mr-bodies", opts.runId, `${opts.node.ticket.id}.md`);
     try {
         mkdirSync(join(cwd, ".foreman", "mr-bodies", opts.runId), { recursive: true });
-        writeFileSync(bodyPath, buildMrBody(opts), "utf8");
+        writeFileSync(bodyPath, configuredReviewBody(cwd, opts.node, opts.qaEvidence, opts.commit), "utf8");
     }
     catch (err) {
         return prFailure(failure("mr_create_failed", `Failed to write GitLab MR body file at ${bodyPath}.`, [
@@ -69,7 +71,7 @@ export function createOrReuseMr(cwd, opts) {
         "--target-branch",
         opts.node.baseBranch,
         "--title",
-        `${opts.node.ticket.id}: ${opts.node.ticket.title}`,
+        configuredReviewTitle(cwd, opts.node.ticket),
         "--description",
         readBodyArg(bodyPath),
         "--yes",
@@ -272,7 +274,7 @@ function buildMrBody(opts) {
         `- Dependencies: ${opts.node.dependencies.length ? opts.node.dependencies.join(", ") : "None"}`,
         `- Commit: ${opts.commit ?? "N/A"}`,
         "",
-        "Generated by Rafi ai-foreman branch-per-ticket mode.",
+        branchNodeFooter(opts.node),
         "",
     ].join("\n");
 }

package/dist/branch/planner.d.ts

@@ -1,6 +1,8 @@
 import type { TicketDef } from "../tickets/ticketSchema.js";
 import type { TicketState } from "../tickets/stateDb.js";
 import type { BranchPlan } from "./types.js";
+import type { DeliveryConfig } from "../tickets/delivery.js";
+import type { TicketBuildSetupConfig } from "../tickets/setupConfig.js";
 export interface AuditDependency {
     ticket: string;
     dependsOn: string;
@@ -18,5 +20,8 @@ export interface BuildBranchPlanOptions {
 export declare function buildBranchPlan(tickets: TicketDef[], states: Map<string, TicketState>, opts: BuildBranchPlanOptions): BranchPlan;
 export declare function selectTicketsForBranchRun(tickets: TicketDef[], states: Map<string, TicketState>, steps: number, ticketIds?: string[]): TicketDef[];
 export declare function applySharedDeliveryBranch(plan: BranchPlan, unitId: string, allRemainingTicketIds: string[], branchPrefix?: string): BranchPlan;
+/** Apply branch sharing only; this deliberately never creates delivery stacks or dependency edges. */
+export declare function applySizeBranchPolicy(plan: BranchPlan, policy: TicketBuildSetupConfig["branch_policy"], delivery?: DeliveryConfig, branchPrefix?: string): BranchPlan;
 export declare function parseAuditDependencies(text: string): AuditDependency[];
 export declare function buildBranchAuditInstruction(tickets: TicketDef[]): string;
+export declare function normalizeBranchPrefix(prefix: string | undefined): string;

package/dist/branch/planner.js

@@ -99,11 +99,11 @@ export function selectTicketsForBranchRun(tickets, states, steps, ticketIds) {
     }
     return selected;
 }
-export function applySharedDeliveryBranch(plan, unitId, allRemainingTicketIds, branchPrefix = "rafi") {
+export function applySharedDeliveryBranch(plan, unitId, allRemainingTicketIds, branchPrefix = "feature") {
     if (plan.nodes.length === 0)
         return plan;
     const slug = unitId.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "group";
-    const branch = `${branchPrefix.replace(/^\/+|\/+$/g, "") || "rafi"}/${slug}`;
+    const branch = `${normalizeBranchPrefix(branchPrefix)}/${slug}`;
     const finalSelected = plan.nodes.at(-1)?.ticket.id;
     const completesUnit = plan.nodes.length === allRemainingTicketIds.length
         && allRemainingTicketIds.every((id) => plan.nodes.some((node) => node.ticket.id === id));
@@ -118,6 +118,38 @@ export function applySharedDeliveryBranch(plan, unitId, allRemainingTicketIds, b
         })),
     };
 }
+/** Apply branch sharing only; this deliberately never creates delivery stacks or dependency edges. */
+export function applySizeBranchPolicy(plan, policy, delivery, branchPrefix = "feature") {
+    if (policy.mode !== "size" || plan.nodes.length < 2)
+        return plan;
+    const explicitlyAssigned = new Set(delivery?.units.flatMap((unit) => unit.tickets) ?? []);
+    const candidates = plan.nodes.filter((node) => policy.by_size[node.ticket.size] === "shared" && !explicitlyAssigned.has(node.ticket.id));
+    const groups = new Map();
+    for (const node of candidates) {
+        // Tickets with selected dependency edges need their existing topology. Independent
+        // tickets sharing the same base are safe to execute serially in one worktree/review.
+        if (node.dependencies.length)
+            continue;
+        const key = node.baseBranch;
+        groups.set(key, [...(groups.get(key) ?? []), node]);
+    }
+    const replacement = new Map();
+    for (const [base, nodes] of groups) {
+        if (nodes.length < 2)
+            continue;
+        const ids = nodes.map((node) => node.ticket.id.toLowerCase()).join("-");
+        const groupId = `size-small-${ids}`;
+        const branch = `${normalizeBranchPrefix(branchPrefix)}/${groupId}`.slice(0, 120).replace(/-+$/, "");
+        nodes.forEach((node, index) => replacement.set(node.ticket.id, {
+            ...node,
+            branch,
+            baseBranch: base,
+            deliveryUnitId: groupId,
+            deliveryUnitFinal: index === nodes.length - 1,
+        }));
+    }
+    return { ...plan, nodes: plan.nodes.map((node) => replacement.get(node.ticket.id) ?? node) };
+}
 export function parseAuditDependencies(text) {
     const deps = [];
     for (const line of text.split(/\r?\n/)) {
@@ -145,7 +177,7 @@ Only name dependencies where both tickets are in this selected batch. If there a
 ${body}`;
 }
 function uniqueBranchName(prefix, ticket, used) {
-    const cleanPrefix = prefix.replace(/^\/+|\/+$/g, "") || "rafi";
+    const cleanPrefix = normalizeBranchPrefix(prefix);
     const baseSlug = `${ticket.id}-${ticket.title}`
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, "-")
@@ -160,6 +192,13 @@ function uniqueBranchName(prefix, ticket, used) {
     used.add(branch);
     return branch;
 }
+export function normalizeBranchPrefix(prefix) {
+    const value = prefix === undefined || prefix === "" ? "feature" : prefix;
+    if (value.startsWith("/") || value.endsWith("/") || value.includes("..") || value.includes("//") || /[~^:?*\[\\\s]/.test(value)) {
+        throw new Error(`invalid Git branch prefix: ${value}`);
+    }
+    return value;
+}
 function detectSelectedCycles(tickets, deps) {
     const selected = new Set(tickets.map((ticket) => ticket.id));
     const visited = new Set();

package/dist/branch/presentation.d.ts

@@ -0,0 +1,17 @@
+import type { BranchPlan, BranchPlanNode } from "./types.js";
+export type BranchAllocationMode = "per-ticket" | "shared" | "mixed";
+export interface BranchPresentation {
+    allocationMode: BranchAllocationMode;
+    description: "one branch per ticket" | "one shared branch" | "mixed shared and per-ticket branches" | "stacked delivery branches";
+    banner: string;
+    prompt: string;
+}
+export interface BranchPresentationOptions {
+    stacked?: boolean;
+    resumed?: boolean;
+}
+export declare function branchPlanLogMetadata(plan: BranchPlan, presentation: BranchPresentation): Record<string, unknown>;
+/** Describe an isolated branch run from its final, transformed plan. */
+export declare function presentBranchPlan(plan: BranchPlan, options?: BranchPresentationOptions): BranchPresentation;
+export declare function branchNodeBehavior(node: BranchPlanNode): "shared delivery branch" | "per-ticket branch";
+export declare function branchNodeFooter(node: BranchPlanNode): string;

package/dist/branch/presentation.js

@@ -0,0 +1,38 @@
+export function branchPlanLogMetadata(plan, presentation) {
+    return {
+        baseRef: plan.baseRef,
+        tickets: plan.nodes.map((node) => node.ticket.id),
+        branches: plan.nodes.map((node) => ({ ticket: node.ticket.id, branch: node.branch, base: node.baseBranch })),
+        issues: plan.issues,
+        branchMode: presentation.allocationMode,
+        executionDescription: presentation.description,
+    };
+}
+/** Describe an isolated branch run from its final, transformed plan. */
+export function presentBranchPlan(plan, options = {}) {
+    const sharedNodes = plan.nodes.filter((node) => Boolean(node.deliveryUnitId)).length;
+    const allocationMode = sharedNodes === 0
+        ? "per-ticket"
+        : sharedNodes === plan.nodes.length
+            ? "shared"
+            : "mixed";
+    const description = options.stacked
+        ? "stacked delivery branches"
+        : allocationMode === "shared"
+            ? "one shared branch"
+            : allocationMode === "mixed"
+                ? "mixed shared and per-ticket branches"
+                : "one branch per ticket";
+    return {
+        allocationMode,
+        description,
+        banner: `foreman: ${options.resumed ? "resuming " : ""}${description} for ${plan.nodes.length} ticket(s)`,
+        prompt: `Proceed with ${description}?`,
+    };
+}
+export function branchNodeBehavior(node) {
+    return node.deliveryUnitId ? "shared delivery branch" : "per-ticket branch";
+}
+export function branchNodeFooter(node) {
+    return `Generated by Rafi ai-foreman for a ${branchNodeBehavior(node)}.`;
+}

package/dist/branch/resume.d.ts

@@ -16,6 +16,8 @@ export interface BranchResumeSession {
     reviewProvider?: string;
     prReady?: boolean;
     keepWorktrees?: boolean;
+    deliveryUnitId?: string;
+    deliveryUnitFinal?: boolean;
     ts?: string;
 }
 export declare function findResumableBranchSessions(foremanDir: string): BranchResumeSession[];

package/dist/branch/resume.js

@@ -43,6 +43,8 @@ export function findResumableBranchSessions(foremanDir) {
                     reviewProvider: stringField(record.reviewProvider),
                     prReady: booleanField(record.prReady),
                     keepWorktrees: booleanField(record.keepWorktrees),
+                    deliveryUnitId: stringField(record.deliveryUnitId),
+                    deliveryUnitFinal: booleanField(record.deliveryUnitFinal),
                     ts: stringField(record.ts),
                 });
             }

package/dist/branch/runner.js

@@ -1,5 +1,5 @@
 import { buildDurableQaFixHandoff, compactWithRetry, runIsolatedQa } from "../qaReview.js";
-import { changeManifest } from "../qaSnapshot.js";
+import { changeManifestAsync } from "../qaSnapshot.js";
 import { Foreman, MARKER_SPEC, parseStepStatus } from "../foreman.js";
 import { fireNotification } from "../notify.js";
 import { cmdBlock, cmdComplete, cmdUpdate } from "../tickets/commands.js";
@@ -9,6 +9,7 @@ import { checkGitLabMrMerged, createOrReuseMr, enableGitLabAutoMerge, pushBranch
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { WorkflowDb } from "../workflowDb.js";
+import { currentActivity, withActivityPhase } from "../activity.js";
 export function readDeliveryUnitSession(projectDir, unitId) {
     const path = deliverySessionPath(projectDir, unitId);
     if (!existsSync(path))
@@ -176,6 +177,8 @@ export async function runBranchPlan(opts) {
                     reviewProvider,
                     prReady: opts.prReady,
                     keepWorktrees: opts.keepWorktrees,
+                    deliveryUnitId: node.deliveryUnitId,
+                    deliveryUnitFinal: node.deliveryUnitFinal,
                 });
                 if (node.deliveryUnitId) {
                     const path = deliverySessionPath(opts.projectDir, node.deliveryUnitId);
@@ -228,7 +231,7 @@ export async function runBranchPlan(opts) {
                             await builder.close();
                             builder = await opts.createBuilder(worktreePath);
                         }
-                        const digest = changeManifest(worktreePath).diffDigest;
+                        const digest = (await withActivityPhase("recording QA fix changes", () => changeManifestAsync(worktreePath, (state, detail) => currentActivity()?.update(state, detail), "recording QA fix changes"))).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;
@@ -287,9 +290,12 @@ export async function runBranchPlan(opts) {
                 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);
+                const push = await withActivityPhase(`pushing ${node.branch}`, async () => {
+                    currentActivity()?.update(`pushing ${node.branch}`, `publishing ${node.ticket.id}`);
+                    return 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" });
@@ -326,24 +332,27 @@ export async function runBranchPlan(opts) {
                 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,
-                        ready: opts.prReady || completionMode === "auto-merge",
-                        runId: opts.runId,
-                        qaEvidence: qaSummary,
-                        commit,
-                        autoMerge: false,
-                        cleanup: opts.cleanupBranches ?? true,
-                        mergeMethod: opts.mergeMethod ?? "squash",
-                    })
-                    : createOrReusePr(opts.projectDir, {
-                        node,
-                        ready: opts.prReady || completionMode === "auto-merge",
-                        runId: opts.runId,
-                        qaEvidence: qaSummary,
-                        commit,
-                    });
+                const pr = await withActivityPhase(`creating ${reviewProvider === "gitlab" ? "merge request" : "pull request"}`, async () => {
+                    currentActivity()?.update(`creating ${reviewProvider === "gitlab" ? "merge request" : "pull request"}`, node.ticket.id);
+                    return reviewProvider === "gitlab"
+                        ? createOrReuseMr(opts.projectDir, {
+                            node,
+                            ready: opts.prReady || completionMode === "auto-merge",
+                            runId: opts.runId,
+                            qaEvidence: qaSummary,
+                            commit,
+                            autoMerge: false,
+                            cleanup: opts.cleanupBranches ?? true,
+                            mergeMethod: opts.mergeMethod ?? "squash",
+                        })
+                        : createOrReusePr(opts.projectDir, {
+                            node,
+                            ready: opts.prReady || completionMode === "auto-merge",
+                            runId: opts.runId,
+                            qaEvidence: qaSummary,
+                            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 });
@@ -362,7 +371,10 @@ export async function runBranchPlan(opts) {
                     continue;
                 }
                 if (completionMode === "auto-merge" && reviewProvider === "github") {
-                    const autoMerge = enableGitHubAutoMerge(opts.projectDir, node.branch, opts.cleanupBranches ?? true, opts.mergeMethod ?? "squash");
+                    const autoMerge = await withActivityPhase("enabling GitHub auto-merge", async () => {
+                        currentActivity()?.update("enabling GitHub auto-merge", node.branch);
+                        return enableGitHubAutoMerge(opts.projectDir, node.branch, opts.cleanupBranches ?? true, opts.mergeMethod ?? "squash");
+                    });
                     summary.pr = autoMerge.status === "failed" ? autoMerge : { ...pr, status: "auto_merge_enabled", url: autoMerge.url ?? pr.url };
                     if (autoMerge.status === "failed") {
                         opts.log.write("pr-auto-merge-failed", failureLogFields(node, autoMerge));
@@ -373,7 +385,10 @@ export async function runBranchPlan(opts) {
                     opts.log.write("pr-auto-merge-enabled", { ticket: node.ticket.id, branch: node.branch, url: summary.pr.url });
                 }
                 else if (completionMode === "auto-merge" && reviewProvider === "gitlab") {
-                    const autoMerge = enableGitLabAutoMerge(opts.projectDir, node.branch, opts.cleanupBranches ?? true, opts.mergeMethod ?? "squash");
+                    const autoMerge = await withActivityPhase("enabling GitLab auto-merge", async () => {
+                        currentActivity()?.update("enabling GitLab auto-merge", node.branch);
+                        return enableGitLabAutoMerge(opts.projectDir, node.branch, opts.cleanupBranches ?? true, opts.mergeMethod ?? "squash");
+                    });
                     summary.pr = autoMerge.status === "failed" ? autoMerge : { ...pr, status: "auto_merge_enabled", url: autoMerge.url ?? pr.url };
                     if (autoMerge.status === "failed") {
                         opts.log.write("mr-auto-merge-failed", failureLogFields(node, autoMerge));
@@ -501,6 +516,9 @@ function workflowCheckpoint(projectDir, runId, checkpoint, ticket, payload) {
     }
 }
 async function waitForAutoMergeDependencies(opts, node, provider) {
+    return withActivityPhase("checking dependency merges", () => waitForAutoMergeDependenciesInternal(opts, node, provider));
+}
+async function waitForAutoMergeDependenciesInternal(opts, node, provider) {
     const dependencyNodes = node.dependencies
         .map((dep) => opts.plan.nodes.find((candidate) => candidate.ticket.id === dep))
         .filter((dep) => Boolean(dep));
@@ -532,6 +550,7 @@ async function waitForAutoMergeDependencies(opts, node, provider) {
         if (pending.length === 0)
             return { ok: true };
         const message = `auto-merge dependency ${pending.join(", ")} has not merged into the root base yet`;
+        currentActivity()?.update("waiting for dependency merge", pending.join(", "));
         if (!opts.autoMergeWait) {
             return {
                 ok: false,

package/dist/buildRuns.d.ts

@@ -1,42 +1,66 @@
-import type { BuildRunRecordV1, ResolvedAgentSettings } from "rafi-spec";
-export declare const BUILD_RUN_VERSION = 1;
+import type { BuildRunRecordV2, ResolvedAgentSettings } from "rafi-spec";
+export declare const BUILD_RUN_VERSION = 2;
 export declare const BUILD_RUN_DIRECTORY = ".foreman/runs";
 export declare const BUILD_HEARTBEAT_MS = 10000;
 export declare const BUILD_LEASE_STALE_MS = 45000;
 export interface CreateBuildRunInput {
     tickets: string[];
     deliveryUnit?: string;
-    branchMode?: BuildRunRecordV1["branchMode"];
+    branchMode?: BuildRunRecordV2["branchMode"];
     repositoryRoot: string;
     worktree?: string;
     branch?: string;
     baseHead?: string;
+    baseRef?: string;
     startHead?: string;
     builder?: LegacyResolvedAgentSettings;
     qa?: LegacyResolvedAgentSettings;
     now?: Date;
 }
-export declare function createBuildRun(input: CreateBuildRunInput): BuildRunRecordV1;
+export declare function createBuildRun(input: CreateBuildRunInput): BuildRunRecordV2;
 export declare function resumeBuildRun(projectDir: string, runId: string, patch: {
     builder?: LegacyResolvedAgentSettings;
     qa?: LegacyResolvedAgentSettings;
     builderSessionId?: string | null;
-}, now?: Date): BuildRunRecordV1;
+}, now?: Date): BuildRunRecordV2;
 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;
-export declare function recordBuildReceipt(projectDir: string, run: BuildRunRecordV1, operationId: string, detail?: {
+export declare function saveBuildRun(projectDir: string, run: BuildRunRecordV2, now?: Date): BuildRunRecordV2;
+export declare function checkpointBuildRun(projectDir: string, run: BuildRunRecordV2, checkpoint: string, patch?: Partial<BuildRunRecordV2>): BuildRunRecordV2;
+export declare function persistBuildSession(projectDir: string, run: BuildRunRecordV2, role: "builder" | "qa", sessionId: string): BuildRunRecordV2;
+export declare function recordBuildReceipt(projectDir: string, run: BuildRunRecordV2, operationId: string, detail?: {
     externalId?: string;
     detail?: string;
-}): BuildRunRecordV1;
-export declare function heartbeatBuildRun(projectDir: string, run: BuildRunRecordV1, now?: Date): BuildRunRecordV1;
-export declare function releaseBuildLease(projectDir: string, run: BuildRunRecordV1, status?: BuildRunRecordV1["status"]): BuildRunRecordV1;
-export declare function completeBuildRun(projectDir: string, run: BuildRunRecordV1, now?: Date): BuildRunRecordV1;
-export declare function readBuildRuns(projectDir: string): BuildRunRecordV1[];
-export declare function recoverableBuildRuns(projectDir: string, now?: Date): Array<BuildRunRecordV1 & {
+}): BuildRunRecordV2;
+export declare function heartbeatBuildRun(projectDir: string, run: BuildRunRecordV2, now?: Date): BuildRunRecordV2;
+export declare function releaseBuildLease(projectDir: string, run: BuildRunRecordV2, status?: BuildRunRecordV2["status"]): BuildRunRecordV2;
+export declare function completeBuildRun(projectDir: string, run: BuildRunRecordV2, now?: Date): BuildRunRecordV2;
+export declare function readBuildRuns(projectDir: string): BuildRunRecordV2[];
+export declare function recoverableBuildRuns(projectDir: string, now?: Date): Array<BuildRunRecordV2 & {
     active: boolean;
 }>;
-export declare function isLeaseActive(run: BuildRunRecordV1, now?: Date): boolean;
-export declare function buildRecoveryPreview(run: BuildRunRecordV1): string[];
+export declare function isLeaseActive(run: BuildRunRecordV2, now?: Date): boolean;
+export declare function buildRecoveryPreview(run: BuildRunRecordV2): string[];
+export interface BuildRecoveryProjection {
+    run: BuildRunRecordV2;
+    ticketId?: string;
+    ticketTitle?: string;
+    compactLabel: string;
+    compactHint: string;
+    completed: string[];
+    remaining: string[];
+    lastSuccess: string;
+    interruption: string;
+    validation: string;
+    expectedChanges: string[];
+    unexpectedChanges: Array<{
+        path: string;
+        risk: string;
+    }>;
+    nextAction: string;
+    worktree: string;
+    branch?: string;
+    exactSessionId?: string;
+}
+export declare function projectBuildRecovery(projectDir: string, run: BuildRunRecordV2, now?: Date, ticketOverride?: string): BuildRecoveryProjection;
+export declare function formatBuildRecoveryProjection(projection: BuildRecoveryProjection): string[];
 export {};