ai-foreman 1.7.10 → 1.7.12

package/dist/cli/start.js

@@ -31,6 +31,7 @@ import { detectGitProvider, loadTicketSetupConfig } from "../tickets/setupConfig
 import { loadDeliveryConfig, selectDeliveryUnitForRun, selectStacksForRun, updateStackDeliveryState } from "../tickets/delivery.js";
 import { AgentStatusReporter, RoleStatusAdapter } from "../statusReporter.js";
 import { currentActivity, withActivityPhase } from "../activity.js";
+import { fireTerminalBell } from "../notify.js";
 import { WorkflowDb, readCurrentWorkflowLease } from "../workflowDb.js";
 import { makeLogPath as makeRoleLogPath, readOnlyPermissionConfig, runRoleInstruction } from "../agentRun.js";
 import { eligibleTickets, evaluateTicketEligibility } from "../tickets/eligibility.js";
@@ -38,7 +39,7 @@ import { BUILTIN_BRANCH_PREFIX, validateBranchPrefix } from "../branch/prefix.js
 import { captureCurrentWorkflowSessionIdentity, CurrentWorkflowChangedError, CurrentWorkflowGuardAdapter } from "../branch/currentGuard.js";
 import { ContinuityAdapter, ContinuityRecoveryRequiredError, SessionUnavailableContinuityError } from "../continuity.js";
 import { ContextCapabilityError, RoleSessionController, ThresholdCompactionController } from "../sessionLifecycle.js";
-import { HandoffLoopError, HandoffService, parseBuilderHandoffRequest } from "../handoffs.js";
+import { HandoffAcceptanceError, HandoffLoopError, HandoffRecoveryPausedError, HandoffService, parseBuilderHandoffRequest } from "../handoffs.js";
 import { captureWorkspaceIdentity, createProviderSessionRef, resolveUniqueSessionBinding } from "../sessionIdentity.js";
 import { SessionUnavailableError } from "../adapters/sessionFailure.js";
 import { resolveProviderSessionAvailability } from "../sessionAvailability.js";
@@ -374,6 +375,9 @@ export function buildStartCommand() {
         const recoveryRecord = opts.recoverRun ? readBuildRuns(cwd).find((run) => run.runId === opts.recoverRun) : undefined;
         if (opts.recoverRun && !recoveryRecord)
             fail(`recoverable build run not found: ${opts.recoverRun}`);
+        const autoApprovePlanUpdates = recoveryRecord
+            ? recoveryRecord.recoveryDecision?.planUpdateApproval === "auto"
+            : Boolean(opts.yes);
         if (opts.recoveryMode) {
             const allowed = ["exact-session", "fresh-with-handoff", "fresh-recovery-only", "guided-recovery"];
             if (!allowed.includes(String(opts.recoveryMode)))
@@ -676,6 +680,34 @@ export function buildStartCommand() {
                 settings_revision: revision,
             };
         };
+        const settingsForRequestedRuntime = (base, requestedRuntime) => requestedRuntime && requestedRuntime !== base.make
+            ? { ...base, make: requestedRuntime, model: "default", source: "cli" }
+            : base;
+        const handoffRecoveryOptions = (role) => ({
+            allowProviderSwitch: true,
+            desktopNotifications: config.notifications.enabled,
+            terminalBell: config.notifications.terminal_bell,
+            onAccepted: (accepted) => {
+                if (role === "builder" && accepted.successor.agent !== agent) {
+                    agent = accepted.successor.agent;
+                    model = undefined;
+                    agentExecutable = undefined;
+                }
+                if (role === "qa" && accepted.successor.agent !== qaAgent) {
+                    qaAgent = accepted.successor.agent;
+                    qaModel = undefined;
+                    qaExecutable = undefined;
+                }
+            },
+        });
+        const acceptedRuntimeSettings = (current, make, acceptedModel) => current.make === make && current.model === (acceptedModel ?? "default")
+            ? current
+            : { ...current, make, model: acceptedModel ?? "default", source: "cli" };
+        const withRunLocalAcceptedRuntimes = (run) => ({
+            ...run,
+            ...(run.builder ? { builder: { ...run.builder, settings: acceptedRuntimeSettings(run.builder.settings, agent, model) } } : {}),
+            ...(run.qa ? { qa: { ...run.qa, settings: acceptedRuntimeSettings(run.qa.settings, qaAgent, qaModel) } } : {}),
+        });
         const createBuilderForSettings = async (builderCwd, settings) => {
             const ready = await ensureRuntimeReadyForCommand(builderCwd, settings.make, {
                 label: "live Builder settings",
@@ -757,7 +789,7 @@ export function buildStartCommand() {
                 initial,
                 runtime: agent,
                 label: "builder turn",
-                enabled: !opts.yes && Boolean(process.stdin.isTTY && process.stdout.isTTY),
+                enabled: Boolean(process.stdin.isTTY && process.stdout.isTTY),
                 allowSwitch: !(opts.resume || opts.continue),
                 recreate: async (nextRuntime, resumeSessionId, resumeRef) => {
                     const nextReady = await ensureRuntimeReadyForCommand(builderCwd, nextRuntime, {
@@ -806,7 +838,7 @@ export function buildStartCommand() {
                         } } : {}),
                     compactionCount, compactMaximum: effectiveSettings.compact_maximum,
                     resources: [{ label: "continuity-reconstruction", content: reconstruction, authoritative: true }],
-                }, () => createBuilderForSettings(builderCwd, effectiveSettings));
+                }, (_handoff, runtime) => createBuilderForSettings(builderCwd, settingsForRequestedRuntime(effectiveSettings, runtime)), handoffRecoveryOptions("builder"));
                 log.write("handoff-transfer", {
                     role: "builder", reason, recovery: "double-invalid-continuity", generation: transfer.manifest.generation,
                     predecessorSessionId: transfer.manifest.predecessorSessionId, successorSessionId: transfer.successorSessionId,
@@ -854,7 +886,7 @@ export function buildStartCommand() {
                     compactionCount,
                     compactMaximum: effectiveSettings.compact_maximum,
                     resources: [{ label: "frozen-action", content: frozenAction, authoritative: true }],
-                }, () => createBuilderForSettings(builderCwd, effectiveSettings));
+                }, (_handoff, runtime) => createBuilderForSettings(builderCwd, settingsForRequestedRuntime(effectiveSettings, runtime)), handoffRecoveryOptions("builder"));
                 log.write("handoff-transfer", {
                     requestedByBuilder: true, reason: request.reason, generation: transfer.manifest.generation,
                     predecessorSessionId: transfer.manifest.predecessorSessionId, successorSessionId: transfer.successorSessionId,
@@ -869,7 +901,8 @@ export function buildStartCommand() {
             let adapter = await createRecoveringBuilder(builderCwd, effectiveSessionId, effectiveSessionId ? sessionRef : undefined);
             if (pendingHandoffGeneration !== undefined && pendingHandoffRole === "builder" && activeContinuityRunId === recoveryRecord?.runId) {
                 const service = new HandoffService(cwd);
-                const accepted = await service.acceptStaged(service.loadStaged(recoveryRecord.runId, pendingHandoffGeneration), adapter);
+                const staged = service.loadStaged(recoveryRecord.runId, pendingHandoffGeneration);
+                const accepted = await service.acceptStagedWithRecovery(staged, adapter, (_handoff, runtime) => createBuilderForSettings(builderCwd, settingsForRequestedRuntime(resolvedContinuitySettings("builder"), runtime)), handoffRecoveryOptions("builder"));
                 adapter = accepted.successor;
                 pendingHandoffGeneration = undefined;
                 log.write("recovery-handoff-accepted", { role: "builder", generation: accepted.manifest.generation, successorSessionId: accepted.successorSessionId, acceptanceCheckpointDigest: accepted.acceptanceCheckpointDigest });
@@ -904,7 +937,7 @@ export function buildStartCommand() {
                     } } : {}),
                 compactionCount, compactMaximum: input.next.compact_maximum,
                 resources: [{ label: "frozen-action", content: input.frozenAction, authoritative: true }],
-            }, () => createBuilderForSettings(builderCwd, input.next));
+            }, (_handoff, runtime) => createBuilderForSettings(builderCwd, settingsForRequestedRuntime(input.next, runtime)), handoffRecoveryOptions("builder"));
             log.write("handoff-transfer", {
                 role: "builder", reason, settingsRevision: input.next.settings_revision, generation: transfer.manifest.generation,
                 predecessorSessionId: transfer.manifest.predecessorSessionId, successorSessionId: transfer.successorSessionId,
@@ -960,7 +993,7 @@ export function buildStartCommand() {
                 initial,
                 runtime: qaAgent,
                 label: "QA turn",
-                enabled: !opts.yes && Boolean(process.stdin.isTTY && process.stdout.isTTY),
+                enabled: Boolean(process.stdin.isTTY && process.stdout.isTTY),
                 allowSwitch: !sessionRef,
                 recreate: async (nextRuntime, resumeSessionId, resumeRef) => {
                     const nextReady = await ensureRuntimeReadyForCommand(qaCwd, nextRuntime, {
@@ -1025,7 +1058,7 @@ export function buildStartCommand() {
                             } } : {}),
                         compactionCount, compactMaximum: effectiveSettings.compact_maximum,
                         resources: [{ label: "continuity-reconstruction", content: reconstruction, authoritative: true }],
-                    }, () => createQaForSettings(qaCwd, effectiveSettings));
+                    }, (_handoff, runtime) => createQaForSettings(qaCwd, settingsForRequestedRuntime(effectiveSettings, runtime)), handoffRecoveryOptions("qa"));
                     log.write("handoff-transfer", {
                         role: "qa", reason, recovery: "double-invalid-continuity", generation: transfer.manifest.generation,
                         predecessorSessionId: transfer.manifest.predecessorSessionId, successorSessionId: transfer.successorSessionId,
@@ -1082,7 +1115,8 @@ export function buildStartCommand() {
             let explicitRecoveryAccepted = false;
             if (pendingHandoffGeneration !== undefined && pendingHandoffRole === "qa" && activeContinuityRunId === recoveryRecord?.runId) {
                 const service = new HandoffService(cwd);
-                const accepted = await service.acceptStaged(service.loadStaged(recoveryRecord.runId, pendingHandoffGeneration), adapter);
+                const staged = service.loadStaged(recoveryRecord.runId, pendingHandoffGeneration);
+                const accepted = await service.acceptStagedWithRecovery(staged, adapter, (_handoff, runtime) => createQaForSettings(qaCwd, settingsForRequestedRuntime(resolvedContinuitySettings("qa"), runtime)), handoffRecoveryOptions("qa"));
                 adapter = accepted.successor;
                 pendingHandoffGeneration = undefined;
                 explicitRecoveryAccepted = true;
@@ -1116,7 +1150,7 @@ export function buildStartCommand() {
                         compactionCount,
                         compactMaximum: resolvedContinuitySettings("qa").compact_maximum,
                     });
-                    const accepted = await service.acceptStaged(staged, adapter);
+                    const accepted = await service.acceptStagedWithRecovery(staged, adapter, (_handoff, runtime) => createQaForSettings(qaCwd, settingsForRequestedRuntime(resolvedContinuitySettings("qa"), runtime)), handoffRecoveryOptions("qa"));
                     adapter = accepted.successor;
                     log.write("handoff-transfer", {
                         role: "qa", reason: staged.manifest.reason, generation: accepted.manifest.generation,
@@ -1155,7 +1189,7 @@ export function buildStartCommand() {
                     } } : {}),
                 compactionCount, compactMaximum: input.next.compact_maximum,
                 resources: [{ label: "frozen-qa-action", content: input.frozenAction, authoritative: true }],
-            }, () => createQaForSettings(qaCwd, input.next));
+            }, (_handoff, runtime) => createQaForSettings(qaCwd, settingsForRequestedRuntime(input.next, runtime)), handoffRecoveryOptions("qa"));
             log.write("handoff-transfer", {
                 role: "qa", reason, settingsRevision: input.next.settings_revision, generation: transfer.manifest.generation,
                 predecessorSessionId: transfer.manifest.predecessorSessionId, successorSessionId: transfer.successorSessionId,
@@ -1198,7 +1232,7 @@ export function buildStartCommand() {
                             } } : {}),
                         compactionCount, compactMaximum: settings.compact_maximum ?? 10,
                         resources: [{ label: "frozen-qa-action", content: frozenAction, authoritative: true }],
-                    }, () => createQaForSettings(qaCwd, settings));
+                    }, (_handoff, runtime) => createQaForSettings(qaCwd, settingsForRequestedRuntime(settings, runtime)), handoffRecoveryOptions("qa"));
                     log.write("handoff-transfer", { role: "qa", generation: transfer.manifest.generation, predecessorSessionId: transfer.manifest.predecessorSessionId, successorSessionId: transfer.successorSessionId, acceptanceCheckpointDigest: transfer.acceptanceCheckpointDigest });
                     await predecessor.close().catch(() => { });
                     return decorateQa(transfer.successor, qaCwd, undefined, settings);
@@ -1219,7 +1253,7 @@ export function buildStartCommand() {
             });
             await controller.observeNativeCompactions(adapter);
         };
-        const qaNonconvergence = createQaNonconvergenceHandler(cwd, Boolean(opts.yes), roleDefaults.planner);
+        const qaNonconvergence = createQaNonconvergenceHandler(cwd, !process.stdin.isTTY || !process.stdout.isTTY, roleDefaults.planner);
         if (branchMode) {
             const ticketsConfig = loadTicketsConfig(cwd);
             const allowedBaseDirtyPaths = generatedTrackerDirtyPaths(ticketsConfig.paths);
@@ -1408,7 +1442,7 @@ export function buildStartCommand() {
                 console.log(`  ! ${issue.ticket ?? "plan"}: ${issue.message}`);
             }
             console.log();
-            if (!opts.yes && plan.issues.every((issue) => !issue.blocking)) {
+            if (!autoApprovePlanUpdates && plan.issues.every((issue) => !issue.blocking)) {
                 const action = await select({
                     message: branchPresentation.prompt,
                     options: [
@@ -1484,7 +1518,7 @@ export function buildStartCommand() {
                             ...(nativeUsage ? { sessionUsage: { version: 1, runId: masterRun.runId, role: "builder", provider: adapter.agent, providerSessionId: adapter.sessionId(), observedAt: nativeUsage.observedAt, source: nativeUsage.source, cumulativeInputTokens: nativeUsage.inputTokens, cumulativeOutputTokens: nativeUsage.outputTokens, cumulativeTotalTokens: nativeUsage.totalTokens, authoritativeCostUsd: nativeUsage.authoritativeCostUsd } } : {}),
                             compactionCount, compactMaximum: settings.compact_maximum ?? 10,
                             resources: [{ label: "frozen-action", content: frozenAction, authoritative: true }],
-                        }, () => createBuilderForSettings(worktreePath, settings));
+                        }, (_handoff, runtime) => createBuilderForSettings(worktreePath, settingsForRequestedRuntime(settings, runtime)), handoffRecoveryOptions("builder"));
                         log.write("handoff-transfer", { worktreePath, generation: transfer.manifest.generation, predecessorSessionId: transfer.manifest.predecessorSessionId, successorSessionId: transfer.successorSessionId, acceptanceCheckpointDigest: transfer.acceptanceCheckpointDigest });
                         if (adapter instanceof ContinuityAdapter) {
                             await adapter.adoptValidatedSuccessor(transfer.successor);
@@ -1500,93 +1534,111 @@ export function buildStartCommand() {
             const branchHeartbeat = setInterval(() => { masterRun = heartbeatBuildRun(cwd, masterRun); }, 10_000);
             branchHeartbeat.unref();
             let branchSessionFailure;
-            const summaries = await runBranchPlan({
-                projectDir: cwd,
-                runId: masterRun.runId,
-                plan,
-                log,
-                agent,
-                model,
-                effort: builderEffort,
-                fast: builderFast,
-                notificationsEnabled: config.notifications.enabled,
-                qaEnabled,
-                createPr: branchDefaults.createReview,
-                completionMode: branchDefaults.completionMode,
-                reviewProvider: branchDefaults.reviewProvider,
-                prReady: branchDefaults.prReady,
-                keepWorktrees: Boolean(opts.keepWorktrees) || selectedStacks.length > 0,
-                cleanupBranches: branchDefaults.cleanupBranches,
-                autoMergeWait: branchDefaults.autoMergeWait,
-                autoMergeTimeoutMinutes: branchDefaults.autoMergeTimeoutMinutes,
-                mergeMethod: branchDefaults.mergeMethod,
-                allowedBaseDirtyPaths,
-                baseWorktreePolicy,
-                trackerPaths: {
-                    progressDoc: ticketsConfig.paths.progressDoc,
-                    archiveDoc: ticketsConfig.paths.archiveDoc,
-                },
-                resumeSessions: resumeSessionByTicket,
-                createBuilder: (builderCwd, sessionId, sessionRef) => createBuilder(builderCwd, sessionId, sessionRef),
-                recordBuilderSession: (session, ticketId) => { masterRun = persistBuildSession(cwd, { ...masterRun, currentTicket: ticketId }, "builder", session); },
-                recordQaSession: (session, ticketId) => { masterRun = persistBuildSession(cwd, { ...masterRun, currentTicket: ticketId }, "qa", session); },
-                onSessionUnavailable: (error) => { branchSessionFailure = error; },
-                createQa: (qaCwd, sessionId) => createQa(qaCwd, sessionId),
-                builderSessionStrategy: roleDefaults.builder?.session_strategy ?? "compact",
-                qaSessionStrategy: roleDefaults.qa?.session_strategy ?? "compact",
-                observeBuilder: async (builder) => {
-                    liveStatusReporter?.stop();
-                    activeBuilderForStatus = () => builder;
-                    const reporter = liveStatusReporter = new AgentStatusReporter({
-                        runId: masterRun.runId, role: "builder", provider: builder.agent, model: capturedBranchBuilder.model,
-                        reasoning: capturedBranchBuilder.reasoning, fast: capturedBranchBuilder.fast, step: Math.min(plan.nodes.length, branchContextControllers.size + 1), total: plan.nodes.length,
-                        phase: "builder ticket session", sessionTransition: builder.sessionId() ? "resumed session" : "initial session", adapter: builder,
-                        settingsRevision: capturedBranchBuilder.settings_revision, displaySessionCost: capturedBranchBuilder.display_session_cost ?? false,
-                        compactionCount: () => { const db = new WorkflowDb(cwd); try {
-                            return db.successfulCompactionCount(masterRun.runId, "builder", builder.sessionRef?.() ?? builder.sessionId());
-                        }
-                        finally {
-                            db.close();
-                        } },
-                        handoffGeneration: () => { const db = new WorkflowDb(cwd); try {
-                            return db.handoffs(masterRun.runId).at(-1)?.generation ?? 0;
-                        }
-                        finally {
-                            db.close();
-                        } },
-                    }, (line, snapshot) => {
-                        const activity = currentActivity();
-                        if (activity && process.stdout.isTTY)
-                            activity.setAgentStatus(line.replace(/^\[[^\]]+\]\s*/, ""));
-                        else
-                            console.log(line);
-                        log.write("agent-status", { ...snapshot });
-                        const db = new WorkflowDb(cwd);
+            let summaries;
+            try {
+                summaries = await runBranchPlan({
+                    projectDir: cwd,
+                    runId: masterRun.runId,
+                    plan,
+                    log,
+                    agent,
+                    model,
+                    effort: builderEffort,
+                    fast: builderFast,
+                    notificationsEnabled: config.notifications.enabled,
+                    terminalBellEnabled: config.notifications.terminal_bell,
+                    qaEnabled,
+                    createPr: branchDefaults.createReview,
+                    completionMode: branchDefaults.completionMode,
+                    reviewProvider: branchDefaults.reviewProvider,
+                    prReady: branchDefaults.prReady,
+                    keepWorktrees: Boolean(opts.keepWorktrees) || selectedStacks.length > 0,
+                    cleanupBranches: branchDefaults.cleanupBranches,
+                    autoMergeWait: branchDefaults.autoMergeWait,
+                    autoMergeTimeoutMinutes: branchDefaults.autoMergeTimeoutMinutes,
+                    mergeMethod: branchDefaults.mergeMethod,
+                    allowedBaseDirtyPaths,
+                    baseWorktreePolicy,
+                    trackerPaths: {
+                        progressDoc: ticketsConfig.paths.progressDoc,
+                        archiveDoc: ticketsConfig.paths.archiveDoc,
+                    },
+                    resumeSessions: resumeSessionByTicket,
+                    createBuilder: (builderCwd, sessionId, sessionRef) => createBuilder(builderCwd, sessionId, sessionRef),
+                    recordBuilderSession: (session, ticketId) => { masterRun = persistBuildSession(cwd, { ...masterRun, currentTicket: ticketId }, "builder", session); },
+                    recordQaSession: (session, ticketId) => { masterRun = persistBuildSession(cwd, { ...masterRun, currentTicket: ticketId }, "qa", session); },
+                    onSessionUnavailable: (error) => { branchSessionFailure = error; },
+                    createQa: (qaCwd, sessionId) => createQa(qaCwd, sessionId),
+                    builderSessionStrategy: roleDefaults.builder?.session_strategy ?? "compact",
+                    qaSessionStrategy: roleDefaults.qa?.session_strategy ?? "compact",
+                    observeBuilder: async (builder) => {
+                        liveStatusReporter?.stop();
+                        activeBuilderForStatus = () => builder;
+                        const reporter = liveStatusReporter = new AgentStatusReporter({
+                            runId: masterRun.runId, role: "builder", provider: builder.agent, model: capturedBranchBuilder.model,
+                            reasoning: capturedBranchBuilder.reasoning, fast: capturedBranchBuilder.fast, step: Math.min(plan.nodes.length, branchContextControllers.size + 1), total: plan.nodes.length,
+                            phase: "builder ticket session", sessionTransition: builder.sessionId() ? "resumed session" : "initial session", adapter: builder,
+                            settingsRevision: capturedBranchBuilder.settings_revision, displaySessionCost: capturedBranchBuilder.display_session_cost ?? false,
+                            compactionCount: () => { const db = new WorkflowDb(cwd); try {
+                                return db.successfulCompactionCount(masterRun.runId, "builder", builder.sessionRef?.() ?? builder.sessionId());
+                            }
+                            finally {
+                                db.close();
+                            } },
+                            handoffGeneration: () => { const db = new WorkflowDb(cwd); try {
+                                return db.handoffs(masterRun.runId).at(-1)?.generation ?? 0;
+                            }
+                            finally {
+                                db.close();
+                            } },
+                        }, (line, snapshot) => {
+                            const activity = currentActivity();
+                            if (activity && process.stdout.isTTY)
+                                activity.setAgentStatus(line.replace(/^\[[^\]]+\]\s*/, ""));
+                            else
+                                console.log(line);
+                            log.write("agent-status", { ...snapshot });
+                            const db = new WorkflowDb(cwd);
+                            try {
+                                db.recordTelemetry(masterRun.runId, snapshot);
+                                db.recordContextSample(snapshot.contextSample);
+                                if (snapshot.sessionUsage)
+                                    db.recordSessionUsage(snapshot.sessionUsage);
+                            }
+                            finally {
+                                db.close();
+                            }
+                        });
+                        reporter.start();
                         try {
-                            db.recordTelemetry(masterRun.runId, snapshot);
-                            db.recordContextSample(snapshot.contextSample);
-                            if (snapshot.sessionUsage)
-                                db.recordSessionUsage(snapshot.sessionUsage);
+                            await printEvents(builder.events());
                         }
                         finally {
-                            db.close();
+                            reporter.stop();
                         }
-                    });
-                    reporter.start();
-                    try {
-                        await printEvents(builder.events());
-                    }
-                    finally {
-                        reporter.stop();
-                    }
-                },
-                qaNonconvergence,
-                beforeBuilderTurn: async (adapter, frozenAction, worktreePath) => (await branchContextController(worktreePath).atSafeBoundary(adapter, frozenAction)).adapter,
-                observeBuilderNativeCompactions: async (adapter, worktreePath) => { await branchContextController(worktreePath).observeNativeCompactions(adapter); },
-                builderSessionBoundary: async (adapter, frozenAction, strategy, worktreePath) => (await branchContextController(worktreePath).atWorkSessionBoundary(adapter, frozenAction, strategy)).adapter,
-                qaSessionBoundary,
-                observeQaNativeCompactions,
-            });
+                    },
+                    qaNonconvergence,
+                    beforeBuilderTurn: async (adapter, frozenAction, worktreePath) => (await branchContextController(worktreePath).atSafeBoundary(adapter, frozenAction)).adapter,
+                    observeBuilderNativeCompactions: async (adapter, worktreePath) => { await branchContextController(worktreePath).observeNativeCompactions(adapter); },
+                    builderSessionBoundary: async (adapter, frozenAction, strategy, worktreePath) => (await branchContextController(worktreePath).atWorkSessionBoundary(adapter, frozenAction, strategy)).adapter,
+                    qaSessionBoundary,
+                    observeQaNativeCompactions,
+                });
+            }
+            catch (error) {
+                if (!(error instanceof HandoffAcceptanceError) && !(error instanceof HandoffRecoveryPausedError))
+                    throw error;
+                const summary = error.message.slice(0, 1000);
+                masterRun = releaseBuildLease(cwd, checkpointBuildRun(cwd, masterRun, "handoff-recovery-required", {
+                    status: "recoverable",
+                    failure: { category: "unknown", summary, at: new Date().toISOString() },
+                }), "recoverable");
+                clearInterval(branchHeartbeat);
+                log.write("safe-boundary-paused", { runId: masterRun.runId, message: summary, handoff: true });
+                console.error(`foreman: handoff paused at a recoverable checkpoint: ${summary}`);
+                console.error(`foreman: resume this run with: rafi build:resume ${shellQuote(cwd)} --run ${shellQuote(masterRun.runId)}`);
+                process.exit(2);
+            }
             if (branchSessionFailure) {
                 const failure = branchSessionFailure;
                 const guided = failure instanceof SessionUnavailableContinuityError ? failure.guidedRecovery : failure.failure.dispatchState === "unknown";
@@ -1624,6 +1676,7 @@ export function buildStartCommand() {
                 }
                 console.log(allComplete ? "foreman: stack publication complete; delivery is awaiting_review (no merges were attempted)" : "foreman: partial stack prefix published; resume point is preserved");
             }
+            masterRun = withRunLocalAcceptedRuntimes(masterRun);
             masterRun = summaries.every((row) => row.buildStatus === "done")
                 ? completeBuildRun(cwd, masterRun)
                 : releaseBuildLease(cwd, checkpointBuildRun(cwd, masterRun, "branch-run-interrupted", { status: "recoverable" }), "recoverable");
@@ -1651,6 +1704,7 @@ export function buildStartCommand() {
             if (masterRun.status === "completed")
                 printHandoffPruneCommand(masterRun.runId);
             const failed = summaries.some((row) => row.buildStatus === "blocked" || row.buildStatus === "needs-human");
+            fireTerminalBell(config.notifications.terminal_bell);
             process.exit(failed ? 2 : 0);
         }
         const ready = await ensureRuntimeReadyForCommand(cwd, agent, {
@@ -1759,7 +1813,7 @@ export function buildStartCommand() {
                     compactionCount,
                     compactMaximum: settings.compact_maximum ?? 10,
                     resources: [{ label: "frozen-action", content: frozenAction, authoritative: true }],
-                }, () => createBuilderForSettings(cwd, settings));
+                }, (_handoff, runtime) => createBuilderForSettings(cwd, settingsForRequestedRuntime(settings, runtime)), handoffRecoveryOptions("builder"));
                 log.write("handoff-transfer", { generation: transfer.manifest.generation, predecessorSessionId: transfer.manifest.predecessorSessionId, successorSessionId: transfer.successorSessionId, acceptanceCheckpointDigest: transfer.acceptanceCheckpointDigest });
                 if (adapter instanceof ContinuityAdapter) {
                     await adapter.adoptValidatedSuccessor(transfer.successor);
@@ -1769,7 +1823,7 @@ export function buildStartCommand() {
                 return continuousBuilder(transfer.successor, cwd, buildRun.runId, settings);
             },
         });
-        const foreman = new Foreman(builder, log, config.notifications.enabled, qaEnabled, 3, cwd, undefined, qaEnabled ? createQa : undefined, capturedQa.session_strategy, createBuilder, capturedBuilder.session_strategy, qaNonconvergence, async (adapter, frozenAction) => (await contextController.atSafeBoundary(adapter, frozenAction)).adapter, async (adapter, frozenAction, strategy) => (await contextController.atWorkSessionBoundary(adapter, frozenAction, strategy)).adapter, qaSessionBoundary, observeQaNativeCompactions, async (adapter) => { await contextController.observeNativeCompactions(adapter); });
+        const foreman = new Foreman(builder, log, { desktop: config.notifications.enabled, terminalBell: config.notifications.terminal_bell }, qaEnabled, 3, cwd, undefined, qaEnabled ? createQa : undefined, capturedQa.session_strategy, createBuilder, capturedBuilder.session_strategy, qaNonconvergence, async (adapter, frozenAction) => (await contextController.atSafeBoundary(adapter, frozenAction)).adapter, async (adapter, frozenAction, strategy) => (await contextController.atWorkSessionBoundary(adapter, frozenAction, strategy)).adapter, qaSessionBoundary, observeQaNativeCompactions, async (adapter) => { await contextController.observeNativeCompactions(adapter); });
         activeBuilderForStatus = () => foreman.builderAdapter();
         const statusReporter = liveStatusReporter = new AgentStatusReporter({
             runId: buildRun.runId,
@@ -1825,12 +1879,13 @@ export function buildStartCommand() {
             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, preferredTicket);
+            buildRun = withRunLocalAcceptedRuntimes(buildRun);
             if (foreman.builderSessionId())
                 buildRun = persistBuildSession(cwd, buildRun, "builder", foreman.builderAdapter().sessionRef?.() ?? foreman.builderSessionId());
             if (foreman.qaSessionId())
                 buildRun = persistBuildSession(cwd, buildRun, "qa", foreman.qaSessionRef() ?? foreman.qaSessionId());
             buildRun = checkpointBuildRun(cwd, buildRun, "preflight-complete");
-            if (!opts.yes) {
+            if (!autoApprovePlanUpdates) {
                 while (true) {
                     console.log();
                     const action = await select({
@@ -1902,7 +1957,8 @@ export function buildStartCommand() {
                     console.log(line);
                 }
             }
-            process.exit(result.outcome === "needs-human" ? 2 : 0);
+            fireTerminalBell(config.notifications.terminal_bell);
+            process.exit(result.outcome === "needs-human" || result.outcome === "blocked" ? 2 : 0);
         }
         catch (err) {
             clearInterval(heartbeat);
@@ -1934,6 +1990,18 @@ export function buildStartCommand() {
                     : `foreman: inspect recovery with: rafi build:resume ${shellQuote(cwd)} --run ${shellQuote(buildRun.runId)} --inspect`);
                 process.exit(2);
             }
+            if (err instanceof HandoffAcceptanceError || err instanceof HandoffRecoveryPausedError) {
+                const summary = err.message.slice(0, 1000);
+                buildRun = releaseBuildLease(cwd, checkpointBuildRun(cwd, buildRun, "handoff-recovery-required", {
+                    status: "recoverable",
+                    failure: { category: "unknown", summary, at: new Date().toISOString() },
+                }), "recoverable");
+                await foreman.close().catch(() => { });
+                log.write("safe-boundary-paused", { runId: buildRun.runId, message: summary, handoff: true });
+                console.error(`foreman: handoff paused at a recoverable checkpoint: ${summary}`);
+                console.error(`foreman: resume this run with: rafi build:resume ${shellQuote(cwd)} --run ${shellQuote(buildRun.runId)}`);
+                process.exit(2);
+            }
             if (err instanceof HandoffLoopError || err instanceof ContinuityRecoveryRequiredError) {
                 const summary = err.message.slice(0, 1000);
                 buildRun = releaseBuildLease(cwd, checkpointBuildRun(cwd, buildRun, "guided-recovery-required", {

package/dist/cli/tickets.js

@@ -1026,7 +1026,7 @@ export async function cmdPopulateCli(opts) {
         }));
         builder = roleBuilder.builder;
         viewer = printEvents(builder.events());
-        const foreman = new Foreman(builder, log, config.notifications.enabled, false, 3, dir);
+        const foreman = new Foreman(builder, log, { desktop: config.notifications.enabled, terminalBell: config.notifications.terminal_bell }, false, 3, dir);
         console.log(`foreman tickets: populating tickets with ${roleBuilder.runtime}`);
         console.log(`foreman tickets: project ${dir}`);
         console.log(`foreman tickets: role ${TICKET_POPULATE_ROLE}`);

package/dist/config.d.ts

@@ -13,6 +13,8 @@ export interface PermissionConfig {
 export interface NotificationsConfig {
     /** Fire a desktop notification when the builder needs user input. Default: false. */
     enabled: boolean;
+    /** Ring the terminal bell when user attention is required or a run finishes. Default: true. */
+    terminal_bell: boolean;
 }
 export interface QaConfig {
     /** Run a QA review pass after each completed ticket or step. Default: true. */

package/dist/config.js

@@ -65,7 +65,7 @@ export const DEFAULT_CONFIG = {
         ],
         escalateTools: ["WebFetch", "WebSearch"],
     },
-    notifications: { enabled: false },
+    notifications: { enabled: false, terminal_bell: true },
     qa: { enabled: true },
 };
 /** Load foreman.yaml if present and deep-merge it over the defaults. */
@@ -104,6 +104,10 @@ function validateConfig(raw, path) {
     }
     if (cfg.notifications !== undefined) {
         validateBooleanObject(cfg.notifications, "notifications", path);
+        const terminalBell = cfg.notifications.terminal_bell;
+        if (terminalBell !== undefined && typeof terminalBell !== "boolean") {
+            throw new Error(`${path}: notifications.terminal_bell must be a boolean`);
+        }
     }
     if (cfg.qa !== undefined) {
         validateBooleanObject(cfg.qa, "qa", path);

package/dist/foreman.d.ts

@@ -48,11 +48,14 @@ export interface BatchResult {
     outcome: "all-done" | "plan-complete" | "blocked" | "needs-human";
     detail?: string;
 }
+export interface ForemanNotificationOptions {
+    desktop: boolean;
+    terminalBell: boolean;
+}
 /** Drives one builder through a batch of N steps via the STEP_STATUS protocol. */
 export declare class Foreman {
     private builder;
     private readonly log;
-    private readonly notificationsEnabled;
     private readonly qaEnabled;
     private readonly qaMaxCycles;
     private readonly projectDir?;
@@ -69,9 +72,11 @@ export declare class Foreman {
     /** Persist a Builder's provider-native event immediately after every turn. */
     private readonly observeBuilderNativeCompactions?;
     private readonly ticketsEnabled;
+    private readonly notificationsEnabled;
+    private readonly terminalBellEnabled;
     private readonly qaStream;
     private builderWorkSessions;
-    constructor(builder: BuilderAdapter, log: Log, notificationsEnabled?: boolean, qaEnabled?: boolean, qaMaxCycles?: number, projectDir?: string | undefined, qaReviewer?: BuilderAdapter | undefined, qaFactory?: ((cwd: string, sessionId?: string) => Promise<BuilderAdapter>) | undefined, qaSessionStrategy?: SessionStrategy, builderFactory?: ((cwd: string, sessionId?: string) => Promise<BuilderAdapter>) | undefined, builderSessionStrategy?: SessionStrategy, qaNonconvergence?: ((context: QaNonconvergenceContext) => Promise<QaNonconvergenceDecision>) | undefined, beforeBuilderTurn?: ((adapter: BuilderAdapter, frozenAction: string) => Promise<BuilderAdapter>) | undefined, builderSessionBoundary?: ((adapter: BuilderAdapter, frozenAction: string, strategy: SessionStrategy) => Promise<BuilderAdapter>) | undefined, qaSessionBoundary?: ((adapter: BuilderAdapter, frozenAction: string, strategy: SessionStrategy, cwd: string) => Promise<BuilderAdapter>) | undefined, observeQaNativeCompactions?: ((adapter: BuilderAdapter) => Promise<void>) | undefined, 
+    constructor(builder: BuilderAdapter, log: Log, notifications?: boolean | ForemanNotificationOptions, qaEnabled?: boolean, qaMaxCycles?: number, projectDir?: string | undefined, qaReviewer?: BuilderAdapter | undefined, qaFactory?: ((cwd: string, sessionId?: string) => Promise<BuilderAdapter>) | undefined, qaSessionStrategy?: SessionStrategy, builderFactory?: ((cwd: string, sessionId?: string) => Promise<BuilderAdapter>) | undefined, builderSessionStrategy?: SessionStrategy, qaNonconvergence?: ((context: QaNonconvergenceContext) => Promise<QaNonconvergenceDecision>) | undefined, beforeBuilderTurn?: ((adapter: BuilderAdapter, frozenAction: string) => Promise<BuilderAdapter>) | undefined, builderSessionBoundary?: ((adapter: BuilderAdapter, frozenAction: string, strategy: SessionStrategy) => Promise<BuilderAdapter>) | undefined, qaSessionBoundary?: ((adapter: BuilderAdapter, frozenAction: string, strategy: SessionStrategy, cwd: string) => Promise<BuilderAdapter>) | undefined, observeQaNativeCompactions?: ((adapter: BuilderAdapter) => Promise<void>) | undefined, 
     /** Persist a Builder's provider-native event immediately after every turn. */
     observeBuilderNativeCompactions?: ((adapter: BuilderAdapter) => Promise<void>) | undefined);
     /**
@@ -90,6 +95,11 @@ export declare class Foreman {
         result: TurnResult;
         status: StepStatus;
     }>;
+    /** Ask an already-active role session to propose choices for its reported blocker. */
+    resolveBlocker(adapter: BuilderAdapter, reason: string): Promise<{
+        result: TurnResult;
+        status: StepStatus;
+    }>;
     private observeBuilderNative;
     /**
      * Run a QA review pass on the ticket the builder just completed.