ai-foreman 1.7.5 → 1.7.7

package/dist/buildRuns.js

@@ -1,17 +1,26 @@
-import { createHash, randomUUID } from "node:crypto";
+import { 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 { canonicalSessionPath, captureWorkspaceIdentity, createProviderSessionRef, latestSessionBinding, upsertSessionBinding } from "./sessionIdentity.js";
+import { resolveProviderSessionAvailability } from "./sessionAvailability.js";
+import { captureCurrentWorkflowSessionIdentity, currentWorkflowIdentityKey } from "./branch/currentGuard.js";
+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 +32,15 @@ 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" },
+        runDecisions: input.runDecisions,
         receipts: {},
         lease: currentLease(now),
         createdAt: stamp,
@@ -57,21 +69,38 @@ export function resumeBuildRun(projectDir, runId, patch, now = new Date()) {
     finally {
         workflow.close();
     }
+    const clearBuilderSession = patch.builderSessionId === null && patch.builderSessionRef === null;
+    const builderSessionId = clearBuilderSession
+        ? undefined
+        : patch.builderSessionRef?.sessionId ?? patch.builderSessionId ?? existing.builder?.sessionId;
     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,
+        builder: patch.builder ? { settings: normalizeCapturedSettings(patch.builder), ...(builderSessionId ? { sessionId: builderSessionId } : {}) } : existing.builder,
         qa: patch.qa ? { settings: normalizeCapturedSettings(patch.qa), sessionId: existing.qa?.sessionId } : existing.qa,
+        sessionBindings: patch.builderSessionRef ? upsertSessionBinding(existing.sessionBindings, patch.builderSessionRef) : existing.sessionBindings,
         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 };
+    return {
+        ...settings,
+        session_strategy: settings.session_strategy ?? (["builder", "qa", "ticket-maker"].includes(settings.role) ? "compact" : "fresh"),
+        display_session_cost: settings.display_session_cost ?? false,
+        auto_compact_threshold_percent: settings.auto_compact_threshold_percent ?? 50,
+        compact_maximum: settings.compact_maximum ?? 10,
+        settings_revision: settings.settings_revision ?? 0,
+    };
 }
 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 });
@@ -91,9 +120,9 @@ export function saveBuildRun(projectDir, run, now = new Date()) {
                 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);
+            workflow.recordSession(next.runId, "builder", "builder", latestSessionBinding(next.sessionBindings, "builder", next.builder.sessionId) ?? 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);
+            workflow.recordSession(next.runId, "qa", "qa", latestSessionBinding(next.sessionBindings, "qa", next.qa.sessionId) ?? next.qa.sessionId, "checkpoint", next.qa.settings, now);
     }
     finally {
         workflow.close();
@@ -103,11 +132,40 @@ export function saveBuildRun(projectDir, run, now = new Date()) {
 export function checkpointBuildRun(projectDir, run, checkpoint, patch = {}) {
     return saveBuildRun(projectDir, { ...run, ...patch, checkpoint, receipts: patch.receipts ?? run.receipts });
 }
-export function persistBuildSession(projectDir, run, role, sessionId) {
+export function persistBuildSession(projectDir, run, role, session) {
     const current = run[role];
     if (!current)
         throw new Error(`${role} settings were not captured for run ${run.runId}`);
-    return checkpointBuildRun(projectDir, { ...run, [role]: { ...current, sessionId } }, `${role}-session-ready`);
+    const sessionId = typeof session === "string" ? session : session.sessionId;
+    const sessionBindings = typeof session === "string" ? run.sessionBindings : upsertSessionBinding(run.sessionBindings, session);
+    return checkpointBuildRun(projectDir, { ...run, sessionBindings, [role]: { ...current, sessionId } }, `${role}-session-ready`);
+}
+/** Latest scoped binding, with the narrow legacy Builder inference allowed by the recovery protocol. */
+export function buildRunSessionBinding(run, role, sessionId) {
+    const bound = latestSessionBinding(run.sessionBindings, role, sessionId);
+    if (bound)
+        return bound;
+    if (role === "qa")
+        return undefined;
+    const raw = sessionId ?? run.builder?.sessionId;
+    if (!raw || !run.builder || !existsSync(run.repository.worktree))
+        return undefined;
+    return createProviderSessionRef({
+        provider: run.builder.settings.make,
+        sessionId: raw,
+        role: "builder",
+        stream: "builder",
+        generation: 0,
+        cwd: run.repository.worktree,
+        configRoot: run.repository.root,
+        workspaceIdentity: run.branchMode === "current" && run.repository.git.branch
+            ? currentWorkflowIdentityKey({ worktree: canonicalSessionPath(run.repository.worktree), ref: `branch:${run.repository.git.branch}` })
+            : run.repository.git.worktreeIdentity ?? captureWorkspaceIdentity(run.repository.worktree),
+        ticketId: run.currentTicket,
+        deliveryUnitId: run.deliveryUnit,
+        source: "legacy-inferred",
+        createdAt: run.createdAt,
+    });
 }
 export function recordBuildReceipt(projectDir, run, operationId, detail) {
     if (run.receipts[operationId])
@@ -145,7 +203,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 +215,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 +225,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,34 +286,146 @@ 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"}`,
+        `session ${buildRunSessionBinding(run, "builder") ? "Builder session candidate requires validation" : "fresh Builder session required"}`,
+        `QA session ${buildRunSessionBinding(run, "qa") ? "QA session candidate requires validation" : "fresh QA session required"}`,
     ];
 }
-function currentLease(now) {
-    return { hostname: hostname(), pid: process.pid, processStart: processStartIdentity(process.pid), heartbeatAt: now.toISOString() };
+export function projectBuildRecovery(projectDir, run, now = new Date(), ticketOverride, sessionAvailability) {
+    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)";
+    const stateSessionId = typeof workflowState.sessionId === "string" ? workflowState.sessionId : undefined;
+    const sessionCandidateRef = buildRunSessionBinding(run, "builder", stateSessionId ?? run.builder?.sessionId);
+    const exactSessionRef = sessionAvailability?.status === "available" ? sessionAvailability.sessionRef ?? sessionCandidateRef : undefined;
+    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,
+        ...(sessionCandidateRef ? { sessionCandidateRef } : {}),
+        ...(sessionAvailability ? { sessionAvailability } : {}),
+        ...(exactSessionRef ? { exactSessionRef, exactSessionId: exactSessionRef.sessionId } : {}),
+    };
 }
-function processStartIdentity(pid) {
+export async function resolveBuildRecoveryProjection(projectDir, run, now = new Date(), ticketOverride, probe = {}) {
+    const frozen = projectBuildRecovery(projectDir, run, now, ticketOverride);
+    const candidate = frozen.sessionCandidateRef;
+    if (!candidate)
+        return frozen;
+    const availability = await resolveProviderSessionAvailability(candidate, {
+        ...probe,
+        cwd: frozen.worktree,
+        configRoot: run.repository.root,
+        workspaceIdentity: run.branchMode === "current" ? safeCurrentIdentity(frozen.worktree) : captureWorkspaceIdentity(frozen.worktree),
+        now,
+    });
+    return projectBuildRecovery(projectDir, run, now, ticketOverride, availability);
+}
+function safeCurrentIdentity(worktree) {
     try {
-        return statSync(`/proc/${pid}`).birthtimeMs.toString();
+        return captureCurrentWorkflowSessionIdentity(worktree);
     }
     catch {
-        return pid === process.pid ? `${Date.now() - Math.round(process.uptime() * 1000)}` : "unknown";
+        return undefined;
     }
 }
-function fingerprintWorkingFiles(worktree) {
+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 (validated)" : projection.sessionCandidateRef ? `exact Builder session unavailable (${projection.sessionAvailability?.reason ?? "validation pending"})` : "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() };
+}
+function processStartIdentity(pid) {
     try {
-        const stat = statSync(resolve(worktree));
-        return createHash("sha256").update(`${stat.dev}:${stat.ino}:${stat.mtimeMs}`).digest("hex");
+        return statSync(`/proc/${pid}`).birthtimeMs.toString();
     }
     catch {
-        return undefined;
+        return pid === process.pid ? `${Date.now() - Math.round(process.uptime() * 1000)}` : "unknown";
     }
 }
 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 +434,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 +446,86 @@ 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) {
+    return captureWorkspaceIdentity(worktree);
+}
+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 {

package/dist/cli/handoffs.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function buildHandoffsCommand(): Command;

package/dist/cli/handoffs.js

@@ -0,0 +1,74 @@
+import { Command } from "commander";
+import { resolve } from "node:path";
+import { recoverableBuildRuns } from "../buildRuns.js";
+import { HandoffService, writeHandoffInspection } from "../handoffs.js";
+import { WorkflowDb } from "../workflowDb.js";
+export function buildHandoffsCommand() {
+    const command = new Command("handoffs").description("Inspect and explicitly manage validated cumulative handoffs.");
+    command.command("inspect")
+        .requiredOption("--run <id>", "build run ID")
+        .option("--generation <n>", "handoff generation")
+        .option("--format <format>", "markdown or json", "markdown")
+        .option("--output <path>", "write inspection to a file")
+        .option("--project <dir>", "project directory", ".")
+        .action((opts) => {
+        const format = String(opts.format);
+        if (!["markdown", "json"].includes(format))
+            throw new Error("--format must be markdown or json");
+        const generation = opts.generation === undefined ? undefined : positiveInteger(opts.generation, "--generation");
+        const service = new HandoffService(resolve(String(opts.project)));
+        const value = service.inspect(String(opts.run), generation);
+        const content = format === "json"
+            ? `${JSON.stringify({ version: 1, lineage: value.lineage, manifest: value.manifest }, null, 2)}\n`
+            : value.markdown;
+        if (opts.output) {
+            writeHandoffInspection(String(opts.output), content);
+            console.log(`rafi handoffs: wrote ${format} inspection to ${resolve(String(opts.output))}`);
+        }
+        else
+            process.stdout.write(content.endsWith("\n") ? content : `${content}\n`);
+    });
+    command.command("prune-cache")
+        .requiredOption("--run <id>", "build run ID")
+        .option("--keep-latest <n>", "number of newest cache generations to keep", "1")
+        .option("--project <dir>", "project directory", ".")
+        .action((opts) => {
+        const keep = nonNegativeInteger(opts.keepLatest, "--keep-latest");
+        const removed = new HandoffService(resolve(String(opts.project))).pruneCache(String(opts.run), keep);
+        console.log(`rafi handoffs: pruned ${removed.length} disposable cache generation(s); durable history was preserved`);
+    });
+    command.command("delete-history")
+        .requiredOption("--run <id>", "build run ID")
+        .requiredOption("--yes", "confirm irreversible durable history deletion")
+        .option("--project <dir>", "project directory", ".")
+        .action((opts) => {
+        const projectDir = resolve(String(opts.project));
+        const runId = String(opts.run);
+        const recoverable = recoverableBuildRuns(projectDir).find((run) => run.runId === runId);
+        if (recoverable)
+            throw new Error(`run ${runId} is active or recoverable; finish or explicitly clean up the run before deleting durable handoff history`);
+        const db = new WorkflowDb(projectDir);
+        try {
+            const deleted = db.deleteHandoffHistory(runId);
+            console.log(`rafi handoffs: deleted ${deleted} durable handoff generation(s) for run ${runId}`);
+            console.log(`rafi handoffs: disposable copies remain until pruned; run: rafi handoffs prune-cache --run ${shellQuote(runId)} --keep-latest 1`);
+        }
+        finally {
+            db.close();
+        }
+    });
+    return command;
+}
+function positiveInteger(value, label) {
+    const result = Number(value);
+    if (!Number.isSafeInteger(result) || result < 1)
+        throw new Error(`${label} must be a positive safe integer`);
+    return result;
+}
+function nonNegativeInteger(value, label) {
+    const result = Number(value);
+    if (!Number.isSafeInteger(result) || result < 0)
+        throw new Error(`${label} must be a non-negative safe integer`);
+    return result;
+}
+function shellQuote(value) { return `'${value.replace(/'/g, `'\\''`)}'`; }