ai-foreman 1.5.0 → 1.6.1

package/dist/branch/github.d.ts

@@ -1,4 +1,4 @@
-import type { BranchPlanNode, GitHubFailure, GitHubOperationResult, GitHubReadinessResult, GitHubRemote, GitHubRemoteResult, PrResult, ReviewMergeStatus } from "./types.js";
+import type { BranchPlanNode, GitHubFailure, GitHubOperationResult, GitHubReadinessResult, GitHubRemote, GitHubRemoteResult, PrResult, ReviewMergeStatus, MergeMethod } from "./types.js";
 export declare function inspectGitHubRemote(cwd: string): GitHubRemoteResult;
 export declare function originLooksLikeGitHub(cwd: string): boolean;
 export declare function checkGitHubReadiness(cwd: string): GitHubReadinessResult;
@@ -17,7 +17,7 @@ export interface CreatePrOptions {
     commit?: string;
 }
 export declare function createOrReusePr(cwd: string, opts: CreatePrOptions): PrResult;
-export declare function enableGitHubAutoMerge(cwd: string, branch: string, cleanup: boolean): PrResult;
+export declare function enableGitHubAutoMerge(cwd: string, branch: string, cleanup: boolean, method?: MergeMethod): PrResult;
 export declare function checkGitHubPrMerged(cwd: string, branch: string): ReviewMergeStatus;
 export declare function formatGitHubFailure(failure: GitHubFailure): string;
 export {};

package/dist/branch/github.js

@@ -157,8 +157,8 @@ export function createOrReusePr(cwd, opts) {
         return { status: "created", url: created.stdout };
     return prFailure(classifyPrFailure(created, opts.node.branch, "Failed to create GitHub PR.", remoteForRepair));
 }
-export function enableGitHubAutoMerge(cwd, branch, cleanup) {
-    const args = ["pr", "merge", branch, "--auto", "--squash"];
+export function enableGitHubAutoMerge(cwd, branch, cleanup, method = "squash") {
+    const args = ["pr", "merge", branch, "--auto", `--${method}`];
     if (cleanup)
         args.push("--delete-branch");
     const result = runCommand(cwd, "gh", args, 30_000);

package/dist/branch/gitlab.d.ts

@@ -1,4 +1,4 @@
-import type { BranchPlanNode, GitHubOperationResult, PrResult, ReviewMergeStatus } from "./types.js";
+import type { BranchPlanNode, GitHubOperationResult, PrResult, ReviewMergeStatus, MergeMethod } from "./types.js";
 export declare function preflightGlab(cwd: string): GitHubOperationResult;
 export declare function pushBranchForMr(cwd: string, branch: string): GitHubOperationResult;
 export interface CreateMrOptions {
@@ -9,7 +9,8 @@ export interface CreateMrOptions {
     commit?: string;
     autoMerge?: boolean;
     cleanup?: boolean;
+    mergeMethod?: MergeMethod;
 }
 export declare function createOrReuseMr(cwd: string, opts: CreateMrOptions): PrResult;
-export declare function enableGitLabAutoMerge(cwd: string, branch: string, cleanup: boolean): PrResult;
+export declare function enableGitLabAutoMerge(cwd: string, branch: string, cleanup: boolean, method?: MergeMethod): PrResult;
 export declare function checkGitLabMrMerged(cwd: string, branch: string): ReviewMergeStatus;

package/dist/branch/gitlab.js

@@ -77,7 +77,9 @@ export function createOrReuseMr(cwd, opts) {
     if (!opts.ready)
         args.push("--draft");
     if (opts.autoMerge)
-        args.push("--auto-merge", "--squash-before-merge");
+        args.push("--auto-merge");
+    if (opts.mergeMethod === "squash")
+        args.push("--squash-before-merge");
     if (opts.cleanup)
         args.push("--remove-source-branch");
     const created = runCommand(cwd, "glab", args);
@@ -88,15 +90,19 @@ export function createOrReuseMr(cwd, opts) {
         "glab auth status",
     ]));
 }
-export function enableGitLabAutoMerge(cwd, branch, cleanup) {
-    const args = ["mr", "merge", branch, "--auto-merge", "--squash", "--yes"];
+export function enableGitLabAutoMerge(cwd, branch, cleanup, method = "squash") {
+    const args = ["mr", "merge", branch, "--auto-merge", "--yes"];
+    if (method === "squash")
+        args.push("--squash");
+    if (method === "rebase")
+        args.push("--rebase");
     if (cleanup)
         args.push("--remove-source-branch");
     const result = runCommand(cwd, "glab", args, 30_000);
     if (result.ok)
         return { status: "auto_merge_enabled", url: result.stdout };
     return prFailure(classifyCommandFailure(result, "mr_create_failed", `Failed to enable GitLab MR auto-merge. Branch: ${branch}`, [
-        `glab mr merge ${branch} --auto-merge --squash --yes`,
+        `glab mr merge ${branch} --auto-merge${method === "squash" ? " --squash" : method === "rebase" ? " --rebase" : ""} --yes`,
         "glab auth status",
     ]));
 }

package/dist/branch/planner.d.ts

@@ -13,8 +13,10 @@ export interface BuildBranchPlanOptions {
     maxBranchDepth: number;
     auditDependencies?: AuditDependency[];
     rootBaseBranches?: boolean;
+    ticketIds?: string[];
 }
 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): TicketDef[];
+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;
 export declare function parseAuditDependencies(text: string): AuditDependency[];
 export declare function buildBranchAuditInstruction(tickets: TicketDef[]): string;

package/dist/branch/planner.js

@@ -1,5 +1,5 @@
 export function buildBranchPlan(tickets, states, opts) {
-    const selected = selectTicketsForBranchRun(tickets, states, opts.steps);
+    const selected = selectTicketsForBranchRun(tickets, states, opts.steps, opts.ticketIds);
     const selectedIds = new Set(selected.map((ticket) => ticket.id));
     const issues = [];
     const dependencyMap = new Map();
@@ -75,9 +75,12 @@ export function buildBranchPlan(tickets, states, opts) {
     }
     return { baseRef: opts.baseRef, nodes: selected.map((ticket) => nodeById.get(ticket.id)), issues };
 }
-export function selectTicketsForBranchRun(tickets, states, steps) {
+export function selectTicketsForBranchRun(tickets, states, steps, ticketIds) {
+    const allowed = ticketIds ? new Set(ticketIds) : undefined;
     const remaining = tickets
         .filter((ticket) => {
+        if (allowed && !allowed.has(ticket.id))
+            return false;
         const status = states.get(ticket.id)?.status ?? "planned";
         return status !== "done" && status !== "canceled";
     })
@@ -96,6 +99,25 @@ export function selectTicketsForBranchRun(tickets, states, steps) {
     }
     return selected;
 }
+export function applySharedDeliveryBranch(plan, unitId, allRemainingTicketIds, branchPrefix = "rafi") {
+    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 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));
+    return {
+        ...plan,
+        nodes: plan.nodes.map((node) => ({
+            ...node,
+            branch,
+            baseBranch: plan.baseRef,
+            deliveryUnitId: unitId,
+            deliveryUnitFinal: completesUnit && node.ticket.id === finalSelected,
+        })),
+    };
+}
 export function parseAuditDependencies(text) {
     const deps = [];
     for (const line of text.split(/\r?\n/)) {

package/dist/branch/runner.d.ts

@@ -1,6 +1,14 @@
 import type { BuilderAdapter, EffortLevel } from "../adapters/types.js";
 import type { Log } from "../log.js";
-import type { BranchPlan, BranchPlanNode, BranchRunSummary, CompletionMode, ReviewProvider } from "./types.js";
+import type { BranchPlan, BranchPlanNode, BranchRunSummary, CompletionMode, MergeMethod, ReviewProvider } from "./types.js";
+export interface DeliveryUnitSession {
+    unitId: string;
+    branch: string;
+    worktreePath: string;
+    sessionId: string;
+    ticket: string;
+}
+export declare function readDeliveryUnitSession(projectDir: string, unitId: string): DeliveryUnitSession | undefined;
 export interface BranchRunnerOptions {
     projectDir: string;
     runId: string;
@@ -20,6 +28,7 @@ export interface BranchRunnerOptions {
     cleanupBranches?: boolean;
     autoMergeWait?: boolean;
     autoMergeTimeoutMinutes?: number | null;
+    mergeMethod?: MergeMethod;
     allowedBaseDirtyPaths?: string[];
     trackerPaths?: {
         progressDoc: string;

package/dist/branch/runner.js

@@ -1,9 +1,25 @@
 import { Foreman, MARKER_SPEC } from "../foreman.js";
 import { fireNotification } from "../notify.js";
 import { cmdBlock, cmdComplete, cmdUpdate } from "../tickets/commands.js";
-import { commitAll, createTicketWorktree, currentWorktreeBranch, deleteLocalBranch, ensureCleanBaseWorktree, ensureForemanExcluded, hasTrackerChanges, hasWorktreeChanges, headCommitIfAhead, removeTicketWorktree, squashMergeBranchToLocalBase, } from "./git.js";
+import { commitAll, createTicketWorktree, findWorktreeForBranch, currentWorktreeBranch, deleteLocalBranch, ensureCleanBaseWorktree, ensureForemanExcluded, hasTrackerChanges, hasWorktreeChanges, headCommitIfAhead, removeTicketWorktree, mergeBranchToLocalBase, } from "./git.js";
 import { checkGitHubPrMerged, createOrReusePr, enableGitHubAutoMerge, pushBranchForPr } from "./github.js";
 import { checkGitLabMrMerged, createOrReuseMr, enableGitLabAutoMerge, pushBranchForMr } from "./gitlab.js";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export function readDeliveryUnitSession(projectDir, unitId) {
+    const path = deliverySessionPath(projectDir, unitId);
+    if (!existsSync(path))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function deliverySessionPath(projectDir, unitId) {
+    return join(projectDir, ".foreman", "delivery-sessions", `${unitId}.json`);
+}
 export async function runBranchPlan(opts) {
     ensureCleanBaseWorktree(opts.projectDir, { allowedDirtyPaths: opts.allowedBaseDirtyPaths });
     ensureForemanExcluded(opts.projectDir);
@@ -29,6 +45,9 @@ export async function runBranchPlan(opts) {
     if (opts.plan.issues.some((issue) => issue.blocking))
         return summaries;
     for (const node of orderNodes(opts.plan.nodes)) {
+        const sharedUnit = Boolean(node.deliveryUnitId);
+        const completesSharedUnit = !sharedUnit || Boolean(node.deliveryUnitFinal);
+        const createsReviewForNode = createsReview && completesSharedUnit;
         const missingDependency = node.dependencies.find((dep) => !successfulBranches.has(dep));
         if (missingDependency) {
             const detail = `dependency ${missingDependency} did not complete`;
@@ -42,7 +61,7 @@ export async function runBranchPlan(opts) {
             notifyIssue(opts.notificationsEnabled, detail);
             continue;
         }
-        if (createsReview) {
+        if (createsReview && !sharedUnit) {
             const missingPush = node.dependencies.find((dep) => {
                 const depNode = opts.plan.nodes.find((candidate) => candidate.ticket.id === dep);
                 return depNode && !pushedBranches.has(depNode.branch);
@@ -60,7 +79,7 @@ export async function runBranchPlan(opts) {
                 continue;
             }
         }
-        if (completionMode === "auto-merge" && node.dependencies.length > 0) {
+        if (completionMode === "auto-merge" && node.dependencies.length > 0 && !sharedUnit) {
             const mergeReadiness = await waitForAutoMergeDependencies(opts, node, reviewProvider);
             if (!mergeReadiness.ok) {
                 summaries.push(summaryFor(node, "skipped", mergeReadiness.message, "skipped"));
@@ -85,6 +104,7 @@ export async function runBranchPlan(opts) {
         });
         const resumeSession = opts.resumeSessions?.get(node.ticket.id);
         const worktreePath = resumeSession?.worktreePath
+            ?? (sharedUnit ? findWorktreeForBranch(opts.projectDir, node.branch) : undefined)
             ?? createTicketWorktree(opts.projectDir, opts.runId, node.branch, node.baseBranch);
         node.worktreePath = worktreePath;
         let builder;
@@ -127,6 +147,11 @@ export async function runBranchPlan(opts) {
                     prReady: opts.prReady,
                     keepWorktrees: opts.keepWorktrees,
                 });
+                if (node.deliveryUnitId) {
+                    const path = deliverySessionPath(opts.projectDir, node.deliveryUnitId);
+                    mkdirSync(join(opts.projectDir, ".foreman", "delivery-sessions"), { recursive: true });
+                    writeFileSync(path, `${JSON.stringify({ unitId: node.deliveryUnitId, branch: node.branch, worktreePath, sessionId, ticket: node.ticket.id }, null, 2)}\n`, "utf8");
+                }
             }
             opts.log.write("step", {
                 index: summaries.length + 1,
@@ -180,12 +205,12 @@ export async function runBranchPlan(opts) {
             if (hasWorktreeChanges(worktreePath)) {
                 commit = commitAll(worktreePath, `${node.ticket.id}: ${node.ticket.title}`);
             }
-            if (!commit && (createsReview || completionMode === "direct-merge")) {
+            if (!commit && (createsReviewForNode || (completionMode === "direct-merge" && completesSharedUnit))) {
                 commit = headCommitIfAhead(worktreePath, node.baseBranch);
             }
             const summary = summaryFor(node, "done", commit ? undefined : "no_changes");
             summary.commit = commit;
-            if (commit && createsReview) {
+            if (commit && createsReviewForNode) {
                 const push = reviewProvider === "gitlab"
                     ? pushBranchForMr(worktreePath, node.branch)
                     : pushBranchForPr(worktreePath, node.branch);
@@ -226,8 +251,9 @@ export async function runBranchPlan(opts) {
                         runId: opts.runId,
                         qaEvidence: qaSummary,
                         commit,
-                        autoMerge: completionMode === "auto-merge",
+                        autoMerge: false,
                         cleanup: opts.cleanupBranches ?? true,
+                        mergeMethod: opts.mergeMethod ?? "squash",
                     })
                     : createOrReusePr(opts.projectDir, {
                         node,
@@ -248,7 +274,7 @@ export async function runBranchPlan(opts) {
                     continue;
                 }
                 if (completionMode === "auto-merge" && reviewProvider === "github") {
-                    const autoMerge = enableGitHubAutoMerge(opts.projectDir, node.branch, opts.cleanupBranches ?? true);
+                    const autoMerge = 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));
@@ -258,8 +284,8 @@ 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" && pr.status === "existing") {
-                    const autoMerge = enableGitLabAutoMerge(opts.projectDir, node.branch, opts.cleanupBranches ?? true);
+                else if (completionMode === "auto-merge" && reviewProvider === "gitlab") {
+                    const autoMerge = 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));
@@ -270,14 +296,14 @@ export async function runBranchPlan(opts) {
                     opts.log.write("mr-auto-merge-enabled", { ticket: node.ticket.id, branch: node.branch, url: summary.pr.url });
                 }
             }
-            else if (createsReview) {
+            else if (createsReviewForNode) {
                 summary.pushStatus = "skipped";
                 summary.pr = { status: "skipped", error: commit ? undefined : "no_changes" };
             }
-            else if (commit && completionMode === "direct-merge") {
+            else if (commit && completionMode === "direct-merge" && completesSharedUnit) {
                 if (!opts.keepWorktrees)
                     removeTicketWorktree(opts.projectDir, worktreePath);
-                const mergeCommit = squashMergeBranchToLocalBase(opts.projectDir, node.branch, node.baseBranch, `${node.ticket.id}: ${node.ticket.title}`);
+                const mergeCommit = mergeBranchToLocalBase(opts.projectDir, node.branch, node.baseBranch, `${node.ticket.id}: ${node.ticket.title}`, opts.mergeMethod ?? "squash");
                 summary.pr = { status: "merged", url: mergeCommit };
                 opts.log.write("branch-direct-merge", {
                     ticket: node.ticket.id,
@@ -304,7 +330,9 @@ export async function runBranchPlan(opts) {
                 status: "done",
                 detail: summary.detail,
             });
-            if (!opts.keepWorktrees && completionMode !== "direct-merge")
+            if (node.deliveryUnitId && node.deliveryUnitFinal)
+                rmSync(deliverySessionPath(opts.projectDir, node.deliveryUnitId), { force: true });
+            if (!opts.keepWorktrees && completionMode !== "direct-merge" && completesSharedUnit)
                 removeTicketWorktree(opts.projectDir, worktreePath);
         }
         catch (err) {

package/dist/branch/types.d.ts

@@ -7,6 +7,9 @@ export interface BranchPlanNode {
     dependencies: string[];
     depth: number;
     worktreePath?: string;
+    /** Shared delivery units intentionally reuse one isolated branch/worktree. */
+    deliveryUnitId?: string;
+    deliveryUnitFinal?: boolean;
 }
 export interface BranchIssue {
     ticket?: string;
@@ -56,6 +59,7 @@ export interface BranchPlan {
 }
 export type CompletionMode = "none" | "pr" | "auto-merge" | "direct-merge";
 export type ReviewProvider = "github" | "gitlab";
+export type MergeMethod = "squash" | "merge" | "rebase";
 export interface PrResult {
     status: "created" | "existing" | "failed" | "skipped" | "auto_merge_enabled" | "merged";
     url?: string;

package/dist/buildRuns.d.ts

@@ -0,0 +1,35 @@
+import type { BuildRunRecordV1, ResolvedAgentSettings } from "rafi-spec";
+export declare const BUILD_RUN_VERSION = 1;
+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"];
+    repositoryRoot: string;
+    worktree?: string;
+    branch?: string;
+    baseHead?: string;
+    startHead?: string;
+    builder?: ResolvedAgentSettings;
+    qa?: ResolvedAgentSettings;
+    now?: Date;
+}
+export declare function createBuildRun(input: CreateBuildRunInput): BuildRunRecordV1;
+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?: {
+    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 & {
+    active: boolean;
+}>;
+export declare function isLeaseActive(run: BuildRunRecordV1, now?: Date): boolean;
+export declare function buildRecoveryPreview(run: BuildRunRecordV1): string[];

package/dist/buildRuns.js

@@ -0,0 +1,149 @@
+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";
+export const BUILD_RUN_VERSION = 1;
+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 run = {
+        version: 1,
+        runId: randomUUID(),
+        status: "running",
+        tickets: [...input.tickets],
+        deliveryUnit: input.deliveryUnit,
+        branchMode: input.branchMode ?? "current",
+        checkpoint: "created",
+        currentTicket: input.tickets[0],
+        builder: input.builder ? { settings: input.builder } : undefined,
+        qa: input.qa ? { settings: 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),
+        },
+        receipts: {},
+        lease: currentLease(now),
+        createdAt: stamp,
+        updatedAt: stamp,
+    };
+    return saveBuildRun(input.repositoryRoot, run, now);
+}
+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 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 });
+    renameSync(temp, target);
+    return next;
+}
+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) {
+    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`);
+}
+export function recordBuildReceipt(projectDir, run, operationId, detail) {
+    if (run.receipts[operationId])
+        return run;
+    return saveBuildRun(projectDir, {
+        ...run,
+        receipts: { ...run.receipts, [operationId]: { completedAt: new Date().toISOString(), ...detail } },
+    });
+}
+export function heartbeatBuildRun(projectDir, run, now = new Date()) {
+    return saveBuildRun(projectDir, { ...run, lease: { ...(run.lease ?? currentLease(now)), heartbeatAt: now.toISOString() } }, now);
+}
+export function releaseBuildLease(projectDir, run, status = "interrupted") {
+    return saveBuildRun(projectDir, { ...run, status, lease: undefined });
+}
+export function completeBuildRun(projectDir, run, now = new Date()) {
+    return saveBuildRun(projectDir, { ...run, status: "completed", checkpoint: "complete", lease: undefined, completedAt: now.toISOString() }, now);
+}
+export function readBuildRuns(projectDir) {
+    const directory = join(resolve(projectDir), BUILD_RUN_DIRECTORY);
+    if (!existsSync(directory))
+        return [];
+    return readdirSync(directory).filter((name) => name.endsWith(".json")).flatMap((name) => {
+        try {
+            const run = JSON.parse(readFileSync(join(directory, name), "utf8"));
+            validateBuildRun(run);
+            return [run];
+        }
+        catch {
+            return [];
+        }
+    }).sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+export function recoverableBuildRuns(projectDir, now = new Date()) {
+    return readBuildRuns(projectDir)
+        .filter((run) => run.status !== "completed")
+        .map((run) => ({ ...run, active: isLeaseActive(run, now) }));
+}
+export function isLeaseActive(run, now = new Date()) {
+    if (!run.lease)
+        return false;
+    const age = now.getTime() - new Date(run.lease.heartbeatAt).getTime();
+    if (age > BUILD_LEASE_STALE_MS)
+        return false;
+    if (run.lease.hostname !== hostname())
+        return true;
+    try {
+        process.kill(run.lease.pid, 0);
+        return run.lease.processStart === processStartIdentity(run.lease.pid);
+    }
+    catch {
+        return false;
+    }
+}
+export function buildRecoveryPreview(run) {
+    const completed = Object.keys(run.receipts).sort();
+    return [
+        `run ${run.runId}`,
+        `ticket ${run.currentTicket ?? run.tickets[0] ?? "unknown"}`,
+        `checkpoint ${run.checkpoint}`,
+        `worktree ${run.repository.worktree}`,
+        `branch ${run.repository.branch ?? "current"}`,
+        `partial files fingerprint ${run.repository.partialFingerprint ?? "unavailable"}`,
+        `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"}`,
+    ];
+}
+function currentLease(now) {
+    return { hostname: hostname(), pid: process.pid, processStart: processStartIdentity(process.pid), heartbeatAt: now.toISOString() };
+}
+function processStartIdentity(pid) {
+    try {
+        return statSync(`/proc/${pid}`).birthtimeMs.toString();
+    }
+    catch {
+        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) {
+        throw new Error("invalid build run record");
+    }
+}

package/dist/cli/doctor.js

@@ -6,6 +6,8 @@ import { loadConfig } from "../config.js";
 import { isTicketsInitialized } from "../tickets/config.js";
 import { cmdValidate } from "../tickets/commands.js";
 import { checkGitHubReadiness, inspectGitHubRemote } from "../branch/github.js";
+import { requireClaudeSDK } from "../adapters/claude.js";
+import { resolveExecutablePath, sanitizeDiagnostics } from "../runtimeReadiness.js";
 const PACKAGE_VERSION = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"))?.version;
 function commandVersion(command) {
     const result = spawnSync(command, ["--version"], {
@@ -23,7 +25,8 @@ export function buildDoctorCommand() {
         .description("Check Foreman, agent CLIs, config, and optional ticket tracker readiness.")
         .argument("[project]", "path to the project directory", ".")
         .option("--github", "run GitHub PR readiness checks")
-        .action((project, opts) => {
+        .option("--live-claude", "run a bounded no-tools Claude adapter request (uses account quota)")
+        .action(async (project, opts) => {
         const cwd = resolve(project);
         let errors = 0;
         const report = (ok, label, detail) => {
@@ -46,11 +49,37 @@ export function buildDoctorCommand() {
         catch (err) {
             report(false, "foreman.yaml", err instanceof Error ? err.message : String(err));
         }
-        const claude = commandVersion("claude");
+        const claudeExecutable = resolveExecutablePath("claude");
+        const claude = claudeExecutable ? commandVersion(claudeExecutable) : { ok: false };
         if (claude.ok)
-            warn("claude CLI found", claude.detail);
+            warn("claude CLI found", `${claudeExecutable} (${claude.detail})`);
         else
-            warn("claude CLI not found", "Claude adapter may still work through the SDK if credentials are configured");
+            warn("claude CLI not found", "required for Claude runs; Rafi never falls back to the SDK-bundled binary");
+        try {
+            await requireClaudeSDK();
+            warn("Rafi Claude SDK wrapper", "available; execution uses the system Claude CLI above");
+        }
+        catch (err) {
+            report(false, "Rafi Claude SDK wrapper", err instanceof Error ? err.message.split("\n")[0] : String(err));
+        }
+        warn("Claude setting sources", "user, project, local, and managed policy");
+        const relevantEnvironment = Object.keys(process.env)
+            .filter((name) => /^(ANTHROPIC|CLAUDE|HTTP_PROXY|HTTPS_PROXY|NO_PROXY|SSL_CERT_FILE|NODE_EXTRA_CA_CERTS)(_|$)/i.test(name))
+            .sort();
+        warn("Claude environment names", relevantEnvironment.length > 0 ? relevantEnvironment.join(", ") : "none set");
+        const projectSdkRemoval = projectClaudeSdkRemoval(cwd);
+        if (projectSdkRemoval) {
+            warn("project-local Claude Agent SDK", `Rafi does not use this dependency; keep it if the application does, otherwise: ${projectSdkRemoval}`);
+        }
+        if (opts.liveClaude) {
+            if (!claudeExecutable) {
+                report(false, "live Claude adapter", "system Claude executable is missing");
+            }
+            else {
+                const live = await liveClaudeSmoke(cwd, claudeExecutable);
+                report(live.ok, "live Claude adapter", live.detail);
+            }
+        }
         const codex = commandVersion("codex");
         if (codex.ok)
             warn("codex CLI found", codex.detail);
@@ -91,6 +120,64 @@ export function buildDoctorCommand() {
         process.exit(errors === 0 ? 0 : 1);
     });
 }
+async function liveClaudeSmoke(cwd, executable) {
+    const abortController = new AbortController();
+    const timer = setTimeout(() => abortController.abort(), 45_000);
+    timer.unref();
+    try {
+        const { query } = await requireClaudeSDK();
+        const queryInstance = query({
+            prompt: "Return exactly OK",
+            options: {
+                cwd,
+                pathToClaudeCodeExecutable: executable,
+                settingSources: ["user", "project", "local"],
+                tools: [],
+                permissionMode: "dontAsk",
+                persistSession: false,
+                abortController,
+            },
+        });
+        for await (const message of queryInstance) {
+            if (message.type !== "result")
+                continue;
+            const output = "result" in message ? message.result : message.errors.join("; ");
+            return message.is_error
+                ? { ok: false, detail: sanitizeDiagnostics(output || "Claude returned an error") }
+                : { ok: output.trim().toUpperCase() === "OK", detail: sanitizeDiagnostics(output) };
+        }
+        return { ok: false, detail: "Claude adapter ended without a result" };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, detail: abortController.signal.aborted ? "timed out after 45 seconds" : sanitizeDiagnostics(message) };
+    }
+    finally {
+        clearTimeout(timer);
+        abortController.abort();
+    }
+}
+function projectClaudeSdkRemoval(cwd) {
+    const packagePath = join(cwd, "package.json");
+    if (!existsSync(packagePath))
+        return undefined;
+    try {
+        const pkg = JSON.parse(readFileSync(packagePath, "utf8"));
+        const name = "@anthropic-ai/claude-agent-sdk";
+        if (!pkg.dependencies?.[name] && !pkg.devDependencies?.[name] && !pkg.optionalDependencies?.[name])
+            return undefined;
+        if (existsSync(join(cwd, "pnpm-lock.yaml")))
+            return `pnpm remove ${name}`;
+        if (existsSync(join(cwd, "yarn.lock")))
+            return `yarn remove ${name}`;
+        if (existsSync(join(cwd, "bun.lock")) || existsSync(join(cwd, "bun.lockb")))
+            return `bun remove ${name}`;
+        return `npm uninstall ${name}`;
+    }
+    catch {
+        return undefined;
+    }
+}
 function truncateOneLine(value) {
     const compact = value.replace(/\s+/g, " ").trim();
     return compact.length <= 180 ? compact : `${compact.slice(0, 180).trimEnd()}...`;