ai-foreman 1.7.5 → 1.7.6

package/README.md

@@ -112,7 +112,7 @@ What each part does:
 | `--keep-worktrees` | flag | remove successful worktrees | Keeps successful ticket worktrees for inspection. Blocked worktrees are kept automatically. |
 | `--ticket <id>` | `T001` | none | Selects a branch-mode ticket to continue. Repeatable with `--continue`. |
 | `--base <ref>` | `main` / `origin/main` / `HEAD` | current branch or `HEAD` | Base ref for root ticket branches. |
-| `--branch-prefix <prefix>` | `rafi` / `feature` | `rafi` | Prefix for generated ticket branches. |
+| `--branch-prefix <prefix>` | `feature` / `rafi` / another valid Git prefix | `feature` | Prefix for generated ticket branches. Explicit prefixes are preserved verbatim. |
 | `--max-branch-depth <n>` | positive integer | `5` | Maximum selected branch/PR stack depth (root PR is depth 1). |
 
 Auto-detected tracker files:

package/dist/branch/github.js

@@ -2,6 +2,7 @@ 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) {
@@ -134,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));
@@ -147,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,
     ];

package/dist/branch/gitlab.js

@@ -2,6 +2,7 @@ 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) {
@@ -55,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}.`, [
@@ -70,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",

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

package/dist/buildRuns.js

@@ -2,16 +2,22 @@ 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 { execFileSync } from "node:child_process";
+import Database from "better-sqlite3";
 import { WorkflowDb } from "./workflowDb.js";
-export const BUILD_RUN_VERSION = 1;
+import { isTicketsInitialized, loadTicketsConfig, resolveTicketPaths } from "./tickets/config.js";
+import { loadTickets } from "./tickets/ticketLoader.js";
+export const BUILD_RUN_VERSION = 2;
 export const BUILD_RUN_DIRECTORY = ".foreman/runs";
 export const BUILD_HEARTBEAT_MS = 10_000;
 export const BUILD_LEASE_STALE_MS = 45_000;
 export function createBuildRun(input) {
     const now = input.now ?? new Date();
     const stamp = now.toISOString();
+    const worktree = resolve(input.worktree ?? input.repositoryRoot);
+    const snapshot = captureGitSnapshot(worktree, input);
     const run = {
-        version: 1,
+        version: 2,
         runId: randomUUID(),
         status: "running",
         tickets: [...input.tickets],
@@ -23,12 +29,14 @@ export function createBuildRun(input) {
         qa: input.qa ? { settings: normalizeCapturedSettings(input.qa) } : undefined,
         repository: {
             root: resolve(input.repositoryRoot),
-            worktree: resolve(input.worktree ?? input.repositoryRoot),
-            branch: input.branch,
-            baseHead: input.baseHead,
-            startHead: input.startHead,
-            partialFingerprint: fingerprintWorkingFiles(input.worktree ?? input.repositoryRoot),
+            worktree,
+            branch: input.branch ?? snapshot.branch,
+            baseHead: input.baseHead ?? snapshot.baselineHead,
+            startHead: input.startHead ?? snapshot.startHead,
+            git: snapshot,
+            baselineComplete: Boolean(snapshot.baselineHead && snapshot.startHead && snapshot.branch),
         },
+        progress: { completedTickets: [], completedOperations: [], remainingTickets: [...input.tickets], nextAction: input.tickets[0] ? `Start ${input.tickets[0]}` : "Plan next work" },
         receipts: {},
         lease: currentLease(now),
         createdAt: stamp,
@@ -71,7 +79,12 @@ export function saveBuildRun(projectDir, run, now = new Date()) {
     validateBuildRun(run);
     const directory = join(resolve(projectDir), BUILD_RUN_DIRECTORY);
     mkdirSync(directory, { recursive: true });
-    const next = { ...run, updatedAt: now.toISOString() };
+    const completedOperations = Object.keys(run.receipts).sort();
+    const next = {
+        ...run,
+        progress: { ...run.progress, completedOperations, remainingTickets: remainingTickets(run) },
+        updatedAt: now.toISOString(),
+    };
     const target = join(directory, `${run.runId}.json`);
     const temp = `${target}.${process.pid}.${randomUUID()}.tmp`;
     writeFileSync(temp, `${JSON.stringify(next, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
@@ -145,7 +158,7 @@ export function releaseBuildLease(projectDir, run, status = "interrupted") {
     return saved;
 }
 export function completeBuildRun(projectDir, run, now = new Date()) {
-    const saved = 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(), progress: { ...run.progress, completedTickets: [...run.tickets], remainingTickets: [], nextAction: "None; build complete" } }, now);
     releaseWorkflowLease(projectDir, run.runId, now);
     return saved;
 }
@@ -157,7 +170,7 @@ export function readBuildRuns(projectDir) {
         try {
             const run = JSON.parse(readFileSync(join(directory, name), "utf8"));
             validateBuildRun(run);
-            return [run];
+            return [upgradeBuildRun(run)];
         }
         catch {
             return [];
@@ -167,7 +180,42 @@ export function readBuildRuns(projectDir) {
 export function recoverableBuildRuns(projectDir, now = new Date()) {
     return readBuildRuns(projectDir)
         .filter((run) => run.status !== "completed")
-        .map((run) => ({ ...run, active: isLeaseActive(run, now) }));
+        .map((run) => ({ ...inferLegacyRunTickets(projectDir, run), active: isLeaseActive(run, now) }));
+}
+/**
+ * Current-branch runs created before ticket checkpointing did not retain their
+ * selected ticket. Recover it from Foreman's tracker events so --ticket can
+ * still address those durable runs without rewriting the legacy record.
+ */
+function inferLegacyRunTickets(projectDir, run) {
+    if (run.tickets.length > 0 || !isTicketsInitialized(projectDir))
+        return run;
+    let db;
+    try {
+        const paths = resolveTicketPaths(loadTicketsConfig(projectDir), projectDir);
+        if (!existsSync(paths.stateDb))
+            return run;
+        db = new Database(paths.stateDb, { readonly: true, fileMustExist: true });
+        const rows = db.prepare(`
+      SELECT ticket_id
+      FROM ticket_events
+      WHERE actor = 'foreman'
+        AND ticket_id IS NOT NULL
+        AND julianday(timestamp) >= julianday(?)
+        AND julianday(timestamp) <= julianday(?)
+      ORDER BY timestamp, id
+    `).all(run.createdAt, run.updatedAt);
+        const tickets = [...new Set(rows.map((row) => row.ticket_id).filter(Boolean))];
+        if (tickets.length === 0)
+            return run;
+        return { ...run, tickets, currentTicket: tickets.at(-1) };
+    }
+    catch {
+        return run;
+    }
+    finally {
+        db?.close();
+    }
 }
 export function isLeaseActive(run, now = new Date()) {
     if (!run.lease)
@@ -193,12 +241,106 @@ export function buildRecoveryPreview(run) {
         `checkpoint ${run.checkpoint}`,
         `worktree ${run.repository.worktree}`,
         `branch ${run.repository.branch ?? "current"}`,
-        `partial files fingerprint ${run.repository.partialFingerprint ?? "unavailable"}`,
+        `baseline ${run.repository.baselineComplete ? `${run.repository.git.baseRef ?? "recorded"} @ ${run.repository.git.baselineHead}` : "incomplete legacy baseline"}`,
+        `preserved paths ${run.repository.git.runOwnedPaths.join(", ") || run.repository.git.statusPaths.join(", ") || "none recorded"}`,
         `completed operations ${completed.length ? completed.join(", ") : "none"}`,
         `session ${run.builder?.sessionId ? "exact Builder session available" : "fresh Builder session required"}`,
         `QA session ${run.qa?.sessionId ? "exact QA session available" : "fresh QA session required"}`,
     ];
 }
+export function projectBuildRecovery(projectDir, run, now = new Date(), ticketOverride) {
+    let operationNames = [];
+    let issues = [];
+    let workflowState = {};
+    if (existsSync(join(resolve(projectDir), ".rafi", "recovery.sqlite3"))) {
+        const workflow = new WorkflowDb(projectDir);
+        try {
+            operationNames = workflow.operations(run.runId).filter((operation) => operation.status === "confirmed").map((operation) => operation.kind);
+            issues = workflow.issues(run.runId).map((issue) => issue.detail);
+            workflowState = workflow.getRun(run.runId)?.state ?? {};
+        }
+        finally {
+            workflow.close();
+        }
+    }
+    const stateTicket = typeof workflowState.currentTicket === "string" ? workflowState.currentTicket : undefined;
+    const ticketId = ticketOverride ?? stateTicket ?? run.currentTicket ?? run.progress.remainingTickets[0] ?? run.tickets[0];
+    let ticketTitle;
+    if (ticketId && isTicketsInitialized(projectDir)) {
+        try {
+            const paths = resolveTicketPaths(loadTicketsConfig(projectDir), projectDir);
+            ticketTitle = loadTickets(paths.tickets).find((ticket) => ticket.id === ticketId)?.title;
+        }
+        catch { /* durable run data remains enough for a legacy preview */ }
+    }
+    const stateWorktree = typeof workflowState.worktree === "string" ? workflowState.worktree : undefined;
+    const recoveryWorktree = stateWorktree && existsSync(stateWorktree) ? stateWorktree : run.repository.worktree;
+    const stateBranch = typeof workflowState.branch === "string" ? workflowState.branch : undefined;
+    const expectedChanges = gitStatusPaths(recoveryWorktree);
+    const baseChanges = resolve(run.repository.root) === resolve(recoveryWorktree) ? [] : gitStatusPaths(run.repository.root);
+    const identityChanged = recoveryWorktree === run.repository.worktree && run.repository.git.worktreeIdentity && worktreeIdentity(recoveryWorktree) !== run.repository.git.worktreeIdentity;
+    const branchNow = gitValue(recoveryWorktree, ["branch", "--show-current"]);
+    const expectedBranch = stateBranch ?? run.repository.git.branch;
+    const branchChanged = Boolean(expectedBranch && branchNow && branchNow !== expectedBranch);
+    const unexpectedChanges = baseChanges.map((path) => ({ path, risk: "base-worktree changes may conflict with recovery" }));
+    if (identityChanged)
+        unexpectedChanges.push({ path: recoveryWorktree, risk: "preserved worktree identity changed" });
+    if (branchChanged)
+        unexpectedChanges.push({ path: recoveryWorktree, risk: `branch changed from ${expectedBranch} to ${branchNow}` });
+    const completed = [...new Set([...run.progress.completedTickets, ...run.progress.completedOperations, ...operationNames])];
+    const remaining = run.progress.remainingTickets.length ? run.progress.remainingTickets : remainingTickets(run);
+    const interruption = run.interruption?.lastError ?? run.interruption?.summary ?? run.failure?.summary ?? issues.at(-1) ?? run.status;
+    const validation = run.progress.validation
+        ? `${run.progress.validation.status}${run.progress.validation.qa ? `; QA ${run.progress.validation.qa}` : ""}`
+        : run.qa?.sessionId ? "QA session checkpointed" : "no completed QA/validation checkpoint recorded";
+    const nextAction = ticketOverride
+        ? `Resume ${ticketOverride} from ${run.checkpoint}`
+        : run.progress.nextAction ?? (ticketId ? `Resume ${ticketId} from ${run.checkpoint}` : `Resume from ${run.checkpoint}`);
+    const primary = ticketId ? `${ticketId}${ticketTitle ? `: ${ticketTitle}` : ""}` : "legacy run (ticket unavailable)";
+    return {
+        run, ticketId, ticketTitle,
+        compactLabel: `${primary} — ${run.status}`,
+        compactHint: `${run.builder?.settings.make ?? "runtime unavailable"}; ${stateBranch ?? branchNow ?? run.repository.branch ?? "current branch"}; updated ${relativeTime(run.updatedAt, now)}`,
+        completed, remaining,
+        lastSuccess: run.progress.lastSuccessfulAction ?? run.checkpoint,
+        interruption,
+        validation,
+        expectedChanges,
+        unexpectedChanges,
+        nextAction,
+        worktree: recoveryWorktree,
+        branch: stateBranch ?? branchNow ?? run.repository.git.branch ?? run.repository.branch,
+        exactSessionId: typeof workflowState.sessionId === "string" ? workflowState.sessionId : run.builder?.sessionId,
+    };
+}
+export function formatBuildRecoveryProjection(projection) {
+    const { run } = projection;
+    const lines = [
+        `run ${run.runId}`,
+        `ticket ${projection.ticketId ?? "unavailable"}${projection.ticketTitle ? `: ${projection.ticketTitle}` : ""}`,
+        `status ${run.status}; checkpoint ${run.checkpoint}`,
+        `completed ${projection.completed.join(", ") || "none recorded"}`,
+        `current ${run.progress.currentStep ?? projection.ticketId ?? "not recorded"}`,
+        `remaining ${projection.remaining.join(", ") || "none"}`,
+        `last successful action ${projection.lastSuccess}`,
+        `interruption/failure ${projection.interruption}`,
+        `validation/QA ${projection.validation}`,
+        `branch ${projection.branch ?? "current"}; worktree ${projection.worktree}`,
+        `baseline ${run.repository.baselineComplete ? `${run.repository.git.baseRef ?? "recorded"} @ ${run.repository.git.baselineHead}` : "incomplete; automatic rollback is unavailable"}`,
+        `session ${projection.exactSessionId ? "exact Builder session available" : "fresh Builder session required"}`,
+        `runtime ${run.builder?.settings.make ?? "unavailable"}; model ${run.builder?.settings.model ?? "unavailable"}`,
+        `updated ${run.updatedAt}`,
+        `preserved expected in-progress paths ${projection.expectedChanges.join(", ") || "none currently dirty"}`,
+    ];
+    if (projection.unexpectedChanges.length) {
+        lines.push("WARNING: unexpected recovery state (recovery remains available):");
+        for (const item of projection.unexpectedChanges)
+            lines.push(`  ${item.path}: ${item.risk}`);
+        lines.push("recommended action: preserve or move these changes before recovery if they overlap the interrupted work");
+    }
+    lines.push(`next action ${projection.nextAction}`);
+    return lines;
+}
 function currentLease(now) {
     return { hostname: hostname(), pid: process.pid, processStart: processStartIdentity(process.pid), heartbeatAt: now.toISOString() };
 }
@@ -210,17 +352,8 @@ function processStartIdentity(pid) {
         return pid === process.pid ? `${Date.now() - Math.round(process.uptime() * 1000)}` : "unknown";
     }
 }
-function fingerprintWorkingFiles(worktree) {
-    try {
-        const stat = statSync(resolve(worktree));
-        return createHash("sha256").update(`${stat.dev}:${stat.ino}:${stat.mtimeMs}`).digest("hex");
-    }
-    catch {
-        return undefined;
-    }
-}
 function validateBuildRun(run) {
-    if (run.version !== BUILD_RUN_VERSION || !run.runId || !run.repository?.root || !run.repository.worktree || !run.createdAt || !run.updatedAt) {
+    if (![1, 2].includes(run.version) || !run.runId || !run.repository?.root || !run.repository.worktree || !run.createdAt || !run.updatedAt) {
         throw new Error("invalid build run record");
     }
 }
@@ -229,6 +362,8 @@ function workflowStatus(status) {
         return "completed";
     if (status === "failed")
         return "failed";
+    if (status === "superseded")
+        return "superseded";
     if (status === "blocked")
         return "blocked";
     if (status === "interrupted" || status === "recoverable")
@@ -239,6 +374,92 @@ 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 captureGitSnapshot(worktree, input) {
+    const git = (args) => {
+        try {
+            return execFileSync("git", args, { cwd: worktree, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const statusPaths = (git(["status", "--porcelain=v1", "-z"]) ?? "").split("\0").filter(Boolean).map((line) => line.slice(3)).sort();
+    const head = input.startHead ?? git(["rev-parse", "HEAD"]);
+    const branch = input.branch ?? git(["branch", "--show-current"]);
+    return {
+        baselineHead: input.baseHead ?? head,
+        baseRef: input.baseRef ?? branch,
+        branch,
+        startHead: head,
+        worktree,
+        worktreeIdentity: worktreeIdentity(worktree),
+        statusPaths,
+        initialStatusPaths: [...statusPaths],
+        runOwnedPaths: [],
+        createdBranch: false,
+        createdWorktree: worktree !== resolve(input.repositoryRoot),
+        upstream: git(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"]),
+    };
+}
+function worktreeIdentity(worktree) {
+    try {
+        const stat = statSync(resolve(worktree));
+        return createHash("sha256").update(`${stat.dev}:${stat.ino}`).digest("hex");
+    }
+    catch {
+        return undefined;
+    }
+}
+function gitValue(cwd, args) {
+    try {
+        return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function gitStatusPaths(cwd) {
+    return (gitValue(cwd, ["status", "--porcelain=v1", "-z"]) ?? "").split("\0").filter(Boolean).map((line) => line.slice(3)).sort();
+}
+function relativeTime(value, now) {
+    const seconds = Math.max(0, Math.floor((now.getTime() - new Date(value).getTime()) / 1000));
+    if (seconds < 60)
+        return `${seconds}s ago`;
+    if (seconds < 3600)
+        return `${Math.floor(seconds / 60)}m ago`;
+    if (seconds < 86_400)
+        return `${Math.floor(seconds / 3600)}h ago`;
+    return `${Math.floor(seconds / 86_400)}d ago`;
+}
+function upgradeBuildRun(run) {
+    if (run.version === 2)
+        return run;
+    const legacy = run;
+    const remaining = legacy.status === "completed" ? [] : legacy.tickets.slice(Math.max(0, legacy.currentTicket ? legacy.tickets.indexOf(legacy.currentTicket) : 0));
+    return {
+        ...legacy,
+        version: 2,
+        legacy: true,
+        repository: {
+            ...legacy.repository,
+            baselineComplete: false,
+            git: {
+                baselineHead: legacy.repository.baseHead,
+                branch: legacy.repository.branch,
+                startHead: legacy.repository.startHead,
+                worktree: legacy.repository.worktree,
+                statusPaths: [], initialStatusPaths: [], runOwnedPaths: [], createdBranch: false, createdWorktree: false,
+            },
+        },
+        progress: {
+            completedTickets: legacy.status === "completed" ? [...legacy.tickets] : [],
+            completedOperations: Object.keys(legacy.receipts).sort(),
+            remainingTickets: remaining,
+            lastSuccessfulAction: legacy.checkpoint,
+            nextAction: remaining[0] ? `Resume ${remaining[0]}` : "Inspect legacy run",
+        },
+    };
+}
 function releaseWorkflowLease(projectDir, runId, now = new Date()) {
     const workflow = new WorkflowDb(projectDir);
     try {