ai-foreman 1.5.0 → 1.6.1

package/dist/cli/runtimeAuthPrompt.d.ts

@@ -1,4 +1,5 @@
 import { RuntimeAuthError, type AgentRuntime } from "../runtimeAuth.js";
+import type { RuntimeProbeResult } from "rafi-spec";
 export type RuntimeCommandRecoveryChoice = "retry" | "switch" | "cancel";
 export interface RuntimeCommandRecoveryContext {
     otherRuntime: AgentRuntime;
@@ -9,7 +10,7 @@ export interface RuntimeReadyForCommandOptions {
     yes?: boolean;
     allowSwitch?: boolean;
     model?: string | undefined;
-    check?: (projectDir: string, runtime: AgentRuntime) => void;
+    check?: (projectDir: string, runtime: AgentRuntime) => void | RuntimeProbeResult | Promise<void | RuntimeProbeResult>;
     checkClaudeSdk?: () => Promise<void>;
     choose?: (err: RuntimeAuthError, context: RuntimeCommandRecoveryContext) => Promise<RuntimeCommandRecoveryChoice>;
 }
@@ -17,5 +18,6 @@ export interface RuntimeReadyForCommandResult {
     runtime: AgentRuntime;
     model?: string;
     fellBack: boolean;
+    executable: string;
 }
 export declare function ensureRuntimeReadyForCommand(projectDir: string, runtime: AgentRuntime, labelOrOptions: string | RuntimeReadyForCommandOptions): Promise<RuntimeReadyForCommandResult>;

package/dist/cli/runtimeAuthPrompt.js

@@ -1,6 +1,7 @@
 import { select, isCancel, log } from "@clack/prompts";
 import { requireClaudeSDK } from "../adapters/claude.js";
 import { checkRuntimeReady, RuntimeAuthError, runtimeCommandLabel, } from "../runtimeAuth.js";
+import { resolveExecutablePath } from "../runtimeReadiness.js";
 import { otherRuntime, runtimeDisplayName } from "./runtimeSelection.js";
 export async function ensureRuntimeReadyForCommand(projectDir, runtime, labelOrOptions) {
     const opts = typeof labelOrOptions === "string"
@@ -12,13 +13,23 @@ 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);
-            return { runtime, model: opts.model, fellBack: false };
+            const probe = await check(projectDir, runtime);
+            if (runtime === "claude")
+                await checkClaudeSdk();
+            const executable = probe?.executable ?? resolveExecutablePath(runtime === "claude" ? "claude" : "codex");
+            if (!executable)
+                throw new Error(`${runtime} executable disappeared after readiness`);
+            return { runtime, model: opts.model, fellBack: false, executable };
         }
         catch (err) {
             const failure = err instanceof RuntimeAuthError
                 ? err
-                : new RuntimeAuthError({ runtime, context: opts.label, cause: err });
+                : new RuntimeAuthError({
+                    runtime,
+                    context: opts.label,
+                    stderr: err instanceof Error ? err.message : String(err),
+                    cause: err,
+                });
             if (nonInteractive) {
                 throw failure;
             }
@@ -30,7 +41,7 @@ export async function ensureRuntimeReadyForCommand(projectDir, runtime, labelOrO
                 continue;
             if (choice === "switch" && allowSwitch) {
                 try {
-                    check(projectDir, fallbackRuntime);
+                    const probe = await check(projectDir, fallbackRuntime);
                     if (fallbackRuntime === "claude") {
                         await checkClaudeSdk();
                     }
@@ -38,12 +49,20 @@ export async function ensureRuntimeReadyForCommand(projectDir, runtime, labelOrO
                         console.log(`foreman: ignored --model ${opts.model} after switching to ${fallbackRuntime}; model names are provider-specific.`);
                     }
                     console.log(`foreman: using ${runtimeDisplayName(fallbackRuntime)} for this run.`);
-                    return { runtime: fallbackRuntime, model: undefined, fellBack: true };
+                    const executable = probe?.executable ?? resolveExecutablePath(fallbackRuntime === "claude" ? "claude" : "codex");
+                    if (!executable)
+                        throw new Error(`${fallbackRuntime} executable disappeared after readiness`);
+                    return { runtime: fallbackRuntime, model: undefined, fellBack: true, executable };
                 }
                 catch (switchErr) {
                     const switchFailure = switchErr instanceof RuntimeAuthError
                         ? switchErr
-                        : new RuntimeAuthError({ runtime: fallbackRuntime, context: opts.label, cause: switchErr });
+                        : new RuntimeAuthError({
+                            runtime: fallbackRuntime,
+                            context: opts.label,
+                            stderr: switchErr instanceof Error ? switchErr.message : String(switchErr),
+                            cause: switchErr,
+                        });
                     log.error(`Fallback runtime is not ready:\n${switchFailure.message}`);
                     continue;
                 }

package/dist/cli/start.js

@@ -7,6 +7,7 @@ import { Log } from "../log.js";
 import { PermissionPolicy } from "../permissions/policy.js";
 import { ClaudeAdapter } from "../adapters/claude.js";
 import { CodexAdapter } from "../adapters/codex.js";
+import { RecoveringAdapter } from "../adapters/recovering.js";
 import { Foreman, createPermissionHandler } from "../foreman.js";
 import { printEvents } from "./events.js";
 import { loadRoleBundle } from "../roles.js";
@@ -15,13 +16,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 +57,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 +67,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 +78,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 +88,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 +98,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 +237,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 +248,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 +261,45 @@ 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);
+        let agentExecutable;
+        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);
+        let qaExecutable;
+        const qaEffort = explicitEffort(roleDefaults.qa?.reasoning);
+        const qaFast = roleDefaults.qa?.fast ?? false;
         const configuredTrackerPath = isTicketsInitialized(cwd)
             ? loadTicketsConfig(cwd).paths.progressDoc
             : undefined;
@@ -320,16 +367,18 @@ export function buildStartCommand() {
         const logPath = join(cwd, ".foreman", `${stamp}.jsonl`);
         const log = new Log(logPath);
         const qaEnabled = opts.qa !== false && config.qa.enabled !== false;
-        const createBuilder = async (builderCwd, sessionId) => {
+        const createRawBuilder = async (builderCwd, sessionId) => {
             const builderPolicy = new PermissionPolicy(config.permissions, builderCwd);
             const roleBundle = loadRoleBundle("builder", { projectDir: builderCwd });
             const adapterOpts = {
                 cwd: builderCwd,
+                runtimeExecutable: agentExecutable,
+                runtimePhase: "builder",
                 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 +386,67 @@ export function buildStartCommand() {
                 ? new CodexAdapter(adapterOpts)
                 : await ClaudeAdapter.create(adapterOpts);
         };
+        const createBuilder = async (builderCwd, sessionId) => {
+            const initial = await createRawBuilder(builderCwd, sessionId);
+            return new RecoveringAdapter({
+                initial,
+                runtime: agent,
+                label: "builder turn",
+                enabled: !opts.yes && Boolean(process.stdin.isTTY && process.stdout.isTTY),
+                allowSwitch: !(opts.resume || opts.continue),
+                recreate: async (nextRuntime, resumeSessionId) => {
+                    const nextReady = await ensureRuntimeReadyForCommand(builderCwd, nextRuntime, {
+                        label: "builder recovery",
+                        allowSwitch: false,
+                        model: nextRuntime === agent ? model : undefined,
+                    });
+                    agent = nextReady.runtime;
+                    model = nextReady.model;
+                    agentExecutable = nextReady.executable;
+                    return createRawBuilder(builderCwd, resumeSessionId);
+                },
+            });
+        };
+        const createRawQa = async (qaCwd, sessionId) => {
+            const qaPolicy = new PermissionPolicy(config.permissions, qaCwd);
+            const roleBundle = loadRoleBundle("qa", { projectDir: qaCwd });
+            const adapterOpts = {
+                cwd: qaCwd,
+                runtimeExecutable: qaExecutable,
+                runtimePhase: "qa",
+                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);
+        };
+        const createQa = async (qaCwd, sessionId) => {
+            const initial = await createRawQa(qaCwd, sessionId);
+            return new RecoveringAdapter({
+                initial,
+                runtime: qaAgent,
+                label: "QA turn",
+                enabled: !opts.yes && Boolean(process.stdin.isTTY && process.stdout.isTTY),
+                allowSwitch: !sessionId,
+                recreate: async (nextRuntime, resumeSessionId) => {
+                    const nextReady = await ensureRuntimeReadyForCommand(qaCwd, nextRuntime, {
+                        label: "QA recovery",
+                        allowSwitch: false,
+                        model: nextRuntime === qaAgent ? qaModel : undefined,
+                    });
+                    qaAgent = nextReady.runtime;
+                    qaModel = nextReady.model;
+                    qaExecutable = nextReady.executable;
+                    return createRawQa(qaCwd, resumeSessionId);
+                },
+            });
+        };
         if (branchMode) {
             const ticketsConfig = loadTicketsConfig(cwd);
             const allowedBaseDirtyPaths = generatedTrackerDirtyPaths(ticketsConfig.paths);
@@ -357,6 +467,7 @@ export function buildStartCommand() {
             });
             agent = ready.runtime;
             model = ready.model;
+            agentExecutable = ready.executable;
             const ticketPaths = resolveTicketPaths(ticketsConfig, cwd);
             const tickets = loadTickets(ticketPaths.tickets);
             const db = new StateDb(ticketPaths.stateDb);
@@ -412,6 +523,7 @@ export function buildStartCommand() {
                     branchPrefix: opts.branchPrefix,
                     maxBranchDepth,
                     rootBaseBranches: branchDefaults.rootBaseBranches,
+                    ticketIds: deliveryRun?.remaining.slice(0, steps),
                 });
                 let auditBuilder;
                 let auditViewer;
@@ -419,6 +531,8 @@ export function buildStartCommand() {
                     auditBuilder = await createBuilder(cwd);
                     auditViewer = printEvents(auditBuilder.events());
                     const audit = await auditBuilder.sendTurn(buildBranchAuditInstruction(plan.nodes.map((node) => node.ticket)));
+                    if (audit.isError)
+                        throw new Error(audit.text);
                     const auditDependencies = parseAuditDependencies(audit.text);
                     plan = buildBranchPlan(tickets, states, {
                         steps,
@@ -427,6 +541,7 @@ export function buildStartCommand() {
                         maxBranchDepth,
                         auditDependencies,
                         rootBaseBranches: branchDefaults.rootBaseBranches,
+                        ticketIds: deliveryRun?.remaining.slice(0, steps),
                     });
                     log.write("branch-plan", {
                         baseRef: plan.baseRef,
@@ -440,11 +555,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 +602,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 +614,7 @@ export function buildStartCommand() {
                 cleanupBranches: branchDefaults.cleanupBranches,
                 autoMergeWait: branchDefaults.autoMergeWait,
                 autoMergeTimeoutMinutes: branchDefaults.autoMergeTimeoutMinutes,
+                mergeMethod: branchDefaults.mergeMethod,
                 allowedBaseDirtyPaths,
                 trackerPaths: {
                     progressDoc: ticketsConfig.paths.progressDoc,
@@ -525,12 +656,38 @@ export function buildStartCommand() {
         });
         agent = ready.runtime;
         model = ready.model;
+        agentExecutable = ready.executable;
+        if (qaEnabled) {
+            const qaReady = await ensureRuntimeReadyForCommand(cwd, qaAgent, { label: "independent QA", yes: Boolean(opts.yes), model: qaModel });
+            qaAgent = qaReady.runtime;
+            qaModel = qaReady.model;
+            qaExecutable = qaReady.executable;
+        }
+        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 +698,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 +741,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 +758,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;