ai-foreman 1.4.0 → 1.6.0

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/runtimeAuthPrompt.d.ts

@@ -9,7 +9,7 @@ export interface RuntimeReadyForCommandOptions {
     yes?: boolean;
     allowSwitch?: boolean;
     model?: string | undefined;
-    check?: (projectDir: string, runtime: AgentRuntime) => void;
+    check?: (projectDir: string, runtime: AgentRuntime) => void | Promise<void>;
     checkClaudeSdk?: () => Promise<void>;
     choose?: (err: RuntimeAuthError, context: RuntimeCommandRecoveryContext) => Promise<RuntimeCommandRecoveryChoice>;
 }

package/dist/cli/runtimeAuthPrompt.js

@@ -12,7 +12,7 @@ export async function ensureRuntimeReadyForCommand(projectDir, runtime, labelOrO
     const nonInteractive = !opts.choose && (Boolean(opts.yes) || !process.stdin.isTTY || !process.stdout.isTTY);
     while (true) {
         try {
-            check(projectDir, runtime);
+            await check(projectDir, runtime);
             return { runtime, model: opts.model, fellBack: false };
         }
         catch (err) {
@@ -30,7 +30,7 @@ export async function ensureRuntimeReadyForCommand(projectDir, runtime, labelOrO
                 continue;
             if (choice === "switch" && allowSwitch) {
                 try {
-                    check(projectDir, fallbackRuntime);
+                    await check(projectDir, fallbackRuntime);
                     if (fallbackRuntime === "claude") {
                         await checkClaudeSdk();
                     }

package/dist/cli/start.js

@@ -15,13 +15,16 @@ import { resolveAgentForProject } from "./runtimeSelection.js";
 import { isTicketsInitialized, loadTicketsConfig, resolveTicketPaths } from "../tickets/config.js";
 import { loadTickets } from "../tickets/ticketLoader.js";
 import { StateDb } from "../tickets/stateDb.js";
-import { buildBranchAuditInstruction, buildBranchPlan, parseAuditDependencies } from "../branch/planner.js";
+import { applySharedDeliveryBranch, buildBranchAuditInstruction, buildBranchPlan, parseAuditDependencies } from "../branch/planner.js";
 import { currentGitRef, ensureCleanBaseWorktree, generatedTrackerDirtyPaths } from "../branch/git.js";
 import { formatGitHubFailure, preflightGh } from "../branch/github.js";
 import { preflightGlab } from "../branch/gitlab.js";
-import { runBranchPlan } from "../branch/runner.js";
+import { readDeliveryUnitSession, runBranchPlan } from "../branch/runner.js";
+import { checkpointBuildRun, completeBuildRun, createBuildRun, heartbeatBuildRun, persistBuildSession, releaseBuildLease } from "../buildRuns.js";
+import { parse as parseYaml } from "yaml";
 import { findResumableBranchSessions, formatBranchContinueCommand, formatBranchSummaryFollowupCommands, } from "../branch/resume.js";
 import { detectGitProvider, loadTicketSetupConfig } from "../tickets/setupConfig.js";
+import { loadDeliveryConfig, selectDeliveryUnitForRun } from "../tickets/delivery.js";
 function fail(message) {
     console.error(`foreman: ${message}`);
     process.exit(1);
@@ -53,7 +56,7 @@ function optionWasProvided(command, name) {
     const source = command.getOptionValueSource(name);
     return source !== undefined && source !== "default";
 }
-function resolveStartBranchDefaults(cwd, opts, command) {
+function resolveStartBranchDefaults(cwd, opts, command, delivery) {
     const setup = loadTicketSetupConfig(cwd);
     const savedBuild = setup?.build;
     const branchFlagProvided = optionWasProvided(command, "branchPerTicket");
@@ -63,8 +66,10 @@ function resolveStartBranchDefaults(cwd, opts, command) {
     const completionFromFlag = typeof opts.completion === "string"
         ? parseCompletionMode(opts.completion)
         : undefined;
+    const deliveryCompletion = delivery?.unit.completion;
     let completionMode = completionFromFlag
         ?? (createPrFlagOn ? "pr" : undefined)
+        ?? deliveryCompletion
         ?? savedBuild?.completion
         ?? "none";
     if (createPrFlagProvided && opts.createPr === false) {
@@ -72,6 +77,9 @@ function resolveStartBranchDefaults(cwd, opts, command) {
     }
     const savedBranchMode = savedBuild?.branch_strategy === "branch-per-ticket";
     let branchMode = Boolean(savedBranchMode || branchFlagOn || createPrFlagOn || completionMode !== "none");
+    if (!branchFlagProvided && !createPrFlagProvided && !optionWasProvided(command, "completion") && delivery) {
+        branchMode = delivery.unit.branch_mode !== "current";
+    }
     if (branchFlagProvided && opts.branchPerTicket === false) {
         branchMode = false;
         completionMode = "none";
@@ -79,7 +87,7 @@ function resolveStartBranchDefaults(cwd, opts, command) {
     if (completionMode !== "none")
         branchMode = true;
     const providerFromFlag = typeof opts.provider === "string" ? parseReviewProviderOption(opts.provider, cwd) : undefined;
-    const provider = providerFromFlag ?? (createPrFlagOn ? "github" : providerFromSaved(savedBuild?.provider, cwd));
+    const provider = providerFromFlag ?? (createPrFlagOn ? "github" : providerFromSaved(delivery?.unit.provider ?? savedBuild?.provider, cwd));
     const autoMergeWaitProvided = optionWasProvided(command, "autoMergeWait");
     const autoMergeTimeoutMinutes = typeof opts.autoMergeTimeoutMinutes === "string"
         ? parseOptionalPositiveInteger(opts.autoMergeTimeoutMinutes, "--auto-merge-timeout-minutes")
@@ -89,13 +97,19 @@ function resolveStartBranchDefaults(cwd, opts, command) {
         completionMode,
         reviewProvider: provider,
         createReview: completionMode === "pr" || completionMode === "auto-merge",
-        prReady: Boolean(opts.prReady || savedBuild?.pr_ready || completionMode === "auto-merge"),
-        cleanupBranches: opts.keepWorktrees ? false : savedBuild?.cleanup ?? true,
+        prReady: Boolean(opts.prReady || delivery?.unit.pr_ready || savedBuild?.pr_ready || completionMode === "auto-merge"),
+        cleanupBranches: opts.keepWorktrees ? false : delivery?.unit.cleanup ?? savedBuild?.cleanup ?? true,
         rootBaseBranches: completionMode === "auto-merge" || completionMode === "direct-merge",
         autoMergeWait: autoMergeWaitProvided ? opts.autoMergeWait !== false : savedBuild?.auto_merge_wait ?? false,
         autoMergeTimeoutMinutes,
+        mergeMethod: typeof opts.mergeMethod === "string" ? parseMergeMethod(opts.mergeMethod) : delivery?.unit.merge_method ?? savedBuild?.merge_method ?? "squash",
     };
 }
+function parseMergeMethod(value) {
+    if (["squash", "merge", "rebase"].includes(value))
+        return value;
+    fail("--merge-method must be one of: squash, merge, rebase");
+}
 function parseCompletionMode(value) {
     if (["pr", "auto-merge", "direct-merge", "none"].includes(value))
         return value;
@@ -222,6 +236,7 @@ export function buildStartCommand() {
         .option("--create-pr", "push each successful ticket branch and create a GitHub PR (implies --branch-per-ticket)")
         .option("--no-create-pr", "disable saved PR/MR creation defaults for this run")
         .option("--completion <mode>", "ticket branch completion behavior (pr | auto-merge | direct-merge | none)")
+        .option("--merge-method <method>", "merge method for local or remote completion (squash | merge | rebase)")
         .option("--provider <provider>", "PR/MR provider for branch completion (auto | github | gitlab)")
         .option("--auto-merge-wait", "wait for dependency PR/MRs to merge before starting dependent tickets")
         .option("--no-auto-merge-wait", "do not wait for dependency PR/MRs before dependent tickets")
@@ -232,6 +247,7 @@ export function buildStartCommand() {
         .option("--pr-ready", "create ready-for-review PRs instead of draft PRs")
         .option("--keep-worktrees", "keep successful ticket worktrees for inspection")
         .option("--ticket <id>", "ticket id to continue in branch mode; repeat for multiple tickets", collectTicket, [])
+        .option("--skip-delivery-unit <id>", "skip one unfinished delivery unit for this run", collectTicket, [])
         .action(async (project, opts, command) => {
         const steps = Number.parseInt(opts.steps, 10);
         if (!Number.isInteger(steps) || steps < 1) {
@@ -244,15 +260,43 @@ export function buildStartCommand() {
         const cwd = resolve(project);
         if (!existsSync(cwd))
             fail(`project directory not found: ${cwd}`);
-        const branchDefaults = resolveStartBranchDefaults(cwd, opts, command);
+        const roleDefaults = readAgentDefaults(cwd);
+        let deliveryRun;
+        if (isTicketsInitialized(cwd)) {
+            const delivery = loadDeliveryConfig(cwd);
+            if (delivery) {
+                const earlyConfig = loadTicketsConfig(cwd);
+                const earlyPaths = resolveTicketPaths(earlyConfig, cwd);
+                const earlyDb = new StateDb(earlyPaths.stateDb);
+                const earlyStates = earlyDb.getAllStates();
+                earlyDb.close();
+                deliveryRun = selectDeliveryUnitForRun(delivery, earlyStates, opts.skipDeliveryUnit ?? []);
+                if (deliveryRun?.state === "resume" && !opts.yes && process.stdin.isTTY && process.stdout.isTTY) {
+                    const answer = await select({ message: `Resume unfinished delivery unit ${deliveryRun.unit.id} (${deliveryRun.remaining.length} remaining)?`, options: [
+                            { value: "resume", label: "Resume (Recommended)" }, { value: "skip", label: "Skip for this run" },
+                        ] });
+                    if (isCancel(answer))
+                        process.exit(0);
+                    if (answer === "skip")
+                        deliveryRun = selectDeliveryUnitForRun(delivery, earlyStates, [deliveryRun.unit.id, ...(opts.skipDeliveryUnit ?? [])]);
+                }
+            }
+        }
+        const branchDefaults = resolveStartBranchDefaults(cwd, opts, command, deliveryRun);
         let agent;
         try {
-            agent = resolveAgentForProject(cwd, opts.agent);
+            agent = resolveAgentForProject(cwd, opts.agent ?? roleDefaults.builder?.make);
         }
         catch (err) {
             fail(err instanceof Error ? err.message : String(err));
         }
-        let model = opts.model;
+        let model = opts.model ?? explicitDefaultValue(roleDefaults.builder?.model);
+        const builderEffort = opts.effort ?? explicitEffort(roleDefaults.builder?.reasoning);
+        const builderFast = opts.fast ?? roleDefaults.builder?.fast;
+        let qaAgent = resolveAgentForProject(cwd, roleDefaults.qa?.make);
+        let qaModel = explicitDefaultValue(roleDefaults.qa?.model);
+        const qaEffort = explicitEffort(roleDefaults.qa?.reasoning);
+        const qaFast = roleDefaults.qa?.fast ?? false;
         const configuredTrackerPath = isTicketsInitialized(cwd)
             ? loadTicketsConfig(cwd).paths.progressDoc
             : undefined;
@@ -328,8 +372,8 @@ export function buildStartCommand() {
                 model,
                 resumeSessionId: sessionId,
                 permission: createPermissionHandler(builderPolicy, log),
-                effort: opts.effort,
-                fast: opts.fast,
+                effort: builderEffort,
+                fast: builderFast,
                 systemPromptAppend: roleBundle.system || undefined,
                 skills: roleBundle.skills.length > 0 ? roleBundle.skills : undefined,
             };
@@ -337,6 +381,23 @@ export function buildStartCommand() {
                 ? new CodexAdapter(adapterOpts)
                 : await ClaudeAdapter.create(adapterOpts);
         };
+        const createQa = async (qaCwd, sessionId) => {
+            const qaPolicy = new PermissionPolicy(config.permissions, qaCwd);
+            const roleBundle = loadRoleBundle("qa", { projectDir: qaCwd });
+            const adapterOpts = {
+                cwd: qaCwd,
+                model: qaModel,
+                resumeSessionId: sessionId,
+                permission: createPermissionHandler(qaPolicy, log),
+                effort: qaEffort,
+                fast: qaFast,
+                systemPromptAppend: `${roleBundle.system}\n\nYou are an independent QA reviewer. Do not edit source, tickets, configuration, or project documentation. You may run tests and create only harmless ignored caches or coverage output.`,
+                skills: roleBundle.skills.length > 0 ? roleBundle.skills : undefined,
+            };
+            return qaAgent === "codex"
+                ? new CodexAdapter(adapterOpts)
+                : await ClaudeAdapter.create(adapterOpts);
+        };
         if (branchMode) {
             const ticketsConfig = loadTicketsConfig(cwd);
             const allowedBaseDirtyPaths = generatedTrackerDirtyPaths(ticketsConfig.paths);
@@ -412,6 +473,7 @@ export function buildStartCommand() {
                     branchPrefix: opts.branchPrefix,
                     maxBranchDepth,
                     rootBaseBranches: branchDefaults.rootBaseBranches,
+                    ticketIds: deliveryRun?.remaining.slice(0, steps),
                 });
                 let auditBuilder;
                 let auditViewer;
@@ -427,6 +489,7 @@ export function buildStartCommand() {
                         maxBranchDepth,
                         auditDependencies,
                         rootBaseBranches: branchDefaults.rootBaseBranches,
+                        ticketIds: deliveryRun?.remaining.slice(0, steps),
                     });
                     log.write("branch-plan", {
                         baseRef: plan.baseRef,
@@ -440,11 +503,26 @@ export function buildStartCommand() {
                     await auditBuilder?.close().catch(() => { });
                     await auditViewer?.catch(() => { });
                 }
+                if (deliveryRun?.unit.branch_mode === "shared") {
+                    plan = applySharedDeliveryBranch(plan, deliveryRun.unit.id, deliveryRun.remaining, opts.branchPrefix);
+                    const saved = readDeliveryUnitSession(cwd, deliveryRun.unit.id);
+                    const first = plan.nodes[0];
+                    if (saved && first && saved.branch === first.branch && existsSync(saved.worktreePath)) {
+                        resumeSessionByTicket.set(first.ticket.id, { worktreePath: saved.worktreePath, sessionId: saved.sessionId });
+                    }
+                }
             }
             console.log(`foreman: ${continueTickets.length > 0 ? "resuming branch-per-ticket mode" : "branch-per-ticket mode"} for ${plan.nodes.length} ticket(s)`);
             console.log(`foreman: project ${cwd}`);
             console.log(`foreman: base ${plan.baseRef}`);
             console.log(`foreman: log ${logPath}\n`);
+            if (deliveryRun) {
+                console.log(`foreman: delivery unit ${deliveryRun.unit.id} — ${deliveryRun.completed}/${deliveryRun.unit.tickets.length} complete, ${deliveryRun.remaining.length} remaining`);
+                if (deliveryRun.unit.branch_mode === "shared" && steps < deliveryRun.remaining.length)
+                    console.log(`foreman: --steps ${steps} completes ${steps} ticket(s) in this ${deliveryRun.remaining.length}-ticket remainder; branch/session is preserved and PR completion is deferred`);
+                if (deliveryRun.unit.dependency_mode === "stack")
+                    console.log("foreman: stacked delivery — dependent branches must be rebased or retargeted after prerequisite merges");
+            }
             for (const node of plan.nodes) {
                 console.log(`  ${node.ticket.id}  ${node.branch}  base=${node.baseBranch}`);
             }
@@ -472,8 +550,8 @@ export function buildStartCommand() {
                 log,
                 agent,
                 model,
-                effort: opts.effort,
-                fast: opts.fast,
+                effort: builderEffort,
+                fast: builderFast,
                 notificationsEnabled: config.notifications.enabled,
                 qaEnabled,
                 createPr: branchDefaults.createReview,
@@ -484,6 +562,7 @@ export function buildStartCommand() {
                 cleanupBranches: branchDefaults.cleanupBranches,
                 autoMergeWait: branchDefaults.autoMergeWait,
                 autoMergeTimeoutMinutes: branchDefaults.autoMergeTimeoutMinutes,
+                mergeMethod: branchDefaults.mergeMethod,
                 allowedBaseDirtyPaths,
                 trackerPaths: {
                     progressDoc: ticketsConfig.paths.progressDoc,
@@ -525,12 +604,36 @@ export function buildStartCommand() {
         });
         agent = ready.runtime;
         model = ready.model;
+        if (qaEnabled) {
+            const qaReady = await ensureRuntimeReadyForCommand(cwd, qaAgent, { label: "independent QA", yes: Boolean(opts.yes), model: qaModel });
+            qaAgent = qaReady.runtime;
+            qaModel = qaReady.model;
+        }
+        const capturedBuilder = {
+            role: "builder", source: opts.agent || opts.model || opts.effort || opts.fast ? "cli" : roleDefaults.builder ? "project" : "provider",
+            make: agent, model: model ?? "default", reasoning: builderEffort ?? "default", fast: Boolean(builderFast),
+        };
+        const capturedQa = { role: "qa", source: roleDefaults.qa ? "project" : "provider", make: qaAgent, model: qaModel ?? "default", reasoning: qaEffort ?? "default", fast: qaFast };
+        let buildRun = createBuildRun({
+            tickets: [], repositoryRoot: cwd, branchMode: "current", builder: capturedBuilder, qa: capturedQa,
+        });
+        const heartbeat = setInterval(() => { buildRun = heartbeatBuildRun(cwd, buildRun); }, 10_000);
+        heartbeat.unref();
+        const checkpointSignal = () => {
+            try {
+                buildRun = releaseBuildLease(cwd, buildRun, "interrupted");
+            }
+            catch { /* best effort */ }
+        };
+        process.once("SIGINT", checkpointSignal);
+        process.once("SIGTERM", checkpointSignal);
         const builder = await createBuilder(cwd, resumeSessionId);
-        const foreman = new Foreman(builder, log, config.notifications.enabled, qaEnabled, 3, cwd);
+        const qaReviewer = qaEnabled ? await createQa(cwd) : undefined;
+        const foreman = new Foreman(builder, log, config.notifications.enabled, qaEnabled, 3, cwd, qaReviewer);
         const modifiers = [
             model ? `model=${model}` : null,
-            opts.effort ? `effort=${opts.effort}` : null,
-            opts.fast ? "fast" : null,
+            builderEffort ? `effort=${builderEffort}` : null,
+            builderFast ? "fast" : null,
             qaEnabled ? null : "qa=off",
         ].filter(Boolean).join(" ");
         console.log(`foreman: driving a ${agent} builder through ${steps} step(s)${modifiers ? ` [${modifiers}]` : ""}`);
@@ -541,7 +644,13 @@ export function buildStartCommand() {
         const viewer = printEvents(builder.events());
         try {
             console.log("ai-foreman: asking builder to plan the next tickets or steps...\n");
+            buildRun = checkpointBuildRun(cwd, buildRun, "before-preflight");
             await foreman.runPreflight(steps, ticketsContent);
+            if (builder.sessionId())
+                buildRun = persistBuildSession(cwd, buildRun, "builder", builder.sessionId());
+            if (qaReviewer?.sessionId())
+                buildRun = persistBuildSession(cwd, buildRun, "qa", qaReviewer.sessionId());
+            buildRun = checkpointBuildRun(cwd, buildRun, "preflight-complete");
             if (!opts.yes) {
                 while (true) {
                     console.log();
@@ -578,6 +687,11 @@ export function buildStartCommand() {
                 }
             }
             const result = await foreman.runBatch(steps, trackerRelPath);
+            buildRun = result.outcome === "all-done" || result.outcome === "plan-complete"
+                ? completeBuildRun(cwd, buildRun)
+                : releaseBuildLease(cwd, checkpointBuildRun(cwd, buildRun, "builder-or-qa-interrupted", { status: "recoverable" }), "recoverable");
+            clearInterval(heartbeat);
+            await qaReviewer?.close().catch(() => { });
             await builder.close();
             await viewer;
             console.log(`\nforeman: ${result.completed}/${result.requested} step(s) completed`);
@@ -590,9 +704,32 @@ export function buildStartCommand() {
             process.exit(result.outcome === "needs-human" ? 2 : 0);
         }
         catch (err) {
+            clearInterval(heartbeat);
+            buildRun = releaseBuildLease(cwd, checkpointBuildRun(cwd, buildRun, "failed", { status: "failed", failure: { category: "unknown", summary: err instanceof Error ? err.message.slice(0, 1000) : String(err).slice(0, 1000), at: new Date().toISOString() } }), "failed");
+            await qaReviewer?.close().catch(() => { });
             await builder.close().catch(() => { });
             log.write("error", { message: String(err) });
             fail(`run failed: ${err instanceof Error ? err.message : String(err)}`);
         }
     });
 }
+function readAgentDefaults(projectDir) {
+    const path = join(projectDir, "rafi-config.yaml");
+    if (!existsSync(path))
+        return {};
+    try {
+        const parsed = parseYaml(readFileSync(path, "utf8"));
+        if (parsed?.agent_defaults?.version !== 1)
+            return {};
+        return { builder: parsed.agent_defaults.roles.builder, qa: parsed.agent_defaults.roles.qa };
+    }
+    catch {
+        return {};
+    }
+}
+function explicitDefaultValue(value) {
+    return value && value !== "default" ? value : undefined;
+}
+function explicitEffort(value) {
+    return value && ["low", "medium", "high", "xhigh"].includes(value) ? value : undefined;
+}

package/dist/cli/status.d.ts

@@ -1,2 +1,4 @@
 import { Command } from "commander";
 export declare function buildStatusCommand(): Command;
+/** Print the existing Foreman status report for a resolved project. */
+export declare function runStatus(project: string): void;