ai-foreman 1.7.11 → 1.7.12

package/dist/agentRun.js

@@ -293,7 +293,7 @@ export async function runRoleInstruction(opts) {
     const { builder, effort, roleBundle, skills } = roleBuilder;
     const viewer = printEvents(builder.events());
     const config = loadConfig(join(opts.projectDir, "foreman.yaml"));
-    const foreman = new Foreman(builder, log, config.notifications.enabled, false, 3, opts.projectDir);
+    const foreman = new Foreman(builder, log, { desktop: config.notifications.enabled, terminalBell: config.notifications.terminal_bell }, false, 3, opts.projectDir);
     try {
         const turn = await foreman.runInstruction(opts.instruction);
         await builder.close();

package/dist/branch/runner.d.ts

@@ -25,6 +25,7 @@ export interface BranchRunnerOptions {
     effort?: EffortLevel;
     fast?: boolean;
     notificationsEnabled: boolean;
+    terminalBellEnabled?: boolean;
     qaEnabled: boolean;
     createPr: boolean;
     completionMode?: CompletionMode;

package/dist/branch/runner.js

@@ -2,7 +2,7 @@ import { buildDurableQaFixHandoff, compactWithRetry, runIsolatedQa } from "../qa
 import { changeManifestAsync } from "../qaSnapshot.js";
 import { Foreman, MARKER_SPEC, parseStepStatus } from "../foreman.js";
 import { fireNotification } from "../notify.js";
-import { cmdBlock, cmdComplete, cmdUpdate } from "../tickets/commands.js";
+import { cmdBlock, cmdComplete, cmdUnblock, cmdUpdate } from "../tickets/commands.js";
 import { commitAll, createTicketWorktree, findWorktreeForBranch, currentWorktreeBranch, deleteLocalBranch, ensureCleanBaseWorktree, ensureForemanExcluded, hasTrackerChanges, hasWorktreeChanges, headCommitIfAhead, removeTicketWorktree, mergeBranchToLocalBase, } from "./git.js";
 import { checkGitHubPrMerged, createOrReusePr, enableGitHubAutoMerge, pushBranchForPr } from "./github.js";
 import { checkGitLabMrMerged, createOrReuseMr, enableGitLabAutoMerge, pushBranchForMr } from "./gitlab.js";
@@ -143,10 +143,14 @@ export async function runBranchPlan(opts) {
                     sessionRef: resumeSession.sessionRef,
                 });
             }
-            journalTracker(opts.projectDir, opts.runId, `${opts.runId}:tracker-update:${node.ticket.id}:in-progress`, { ticket: node.ticket.id, status: "in_progress" }, () => cmdUpdate(opts.projectDir, node.ticket.id, {
-                status: "in_progress", actor: "foreman",
-                summary: resumeSession ? `Resuming branch ${node.branch}` : `Starting branch ${node.branch}`,
-            }));
+            journalTracker(opts.projectDir, opts.runId, `${opts.runId}:tracker-update:${node.ticket.id}:in-progress`, { ticket: node.ticket.id, status: "in_progress" }, () => {
+                if (resumeSession)
+                    cmdUnblock(opts.projectDir, node.ticket.id, { actor: "foreman", summary: `Reopened by explicit branch recovery for ${node.branch}` });
+                cmdUpdate(opts.projectDir, node.ticket.id, {
+                    status: "in_progress", actor: "foreman",
+                    summary: resumeSession ? `Resuming branch ${node.branch}` : `Starting branch ${node.branch}`,
+                });
+            });
             const ticketInstruction = resumeSession ? buildBranchTicketResumeInstruction(node, opts.trackerPaths) : buildBranchTicketInstruction(node, opts.trackerPaths);
             // Reattach the predecessor even for a `fresh` strategy so the host can
             // publish and validate a cumulative handoff before creating its successor.
@@ -173,7 +177,7 @@ export async function runBranchPlan(opts) {
             }
             builderWorkSessions += 1;
             viewer = opts.observeBuilder?.(builder);
-            const foreman = new Foreman(builder, opts.log, opts.notificationsEnabled, opts.qaEnabled, 3, undefined, undefined, undefined, opts.qaSessionStrategy ?? "compact", undefined, opts.builderSessionStrategy ?? "compact", undefined, opts.beforeBuilderTurn ? (adapter, action) => opts.beforeBuilderTurn(adapter, action, worktreePath) : undefined, undefined, undefined, async (adapter) => opts.observeBuilderNativeCompactions?.(adapter, worktreePath));
+            const foreman = new Foreman(builder, opts.log, { desktop: opts.notificationsEnabled, terminalBell: opts.terminalBellEnabled ?? true }, opts.qaEnabled, 3, undefined, undefined, undefined, opts.qaSessionStrategy ?? "compact", undefined, opts.builderSessionStrategy ?? "compact", undefined, opts.beforeBuilderTurn ? (adapter, action) => opts.beforeBuilderTurn(adapter, action, worktreePath) : undefined, undefined, undefined, undefined, async (adapter) => opts.observeBuilderNativeCompactions?.(adapter, worktreePath));
             const { result, status } = await foreman.runInstruction(ticketInstruction);
             builder = foreman.builderAdapter();
             workflowCheckpoint(opts.projectDir, opts.runId, "builder-after", node.ticket.id, { status: status.kind, sessionId: builder.sessionId(), worktree: worktreePath });
@@ -243,6 +247,7 @@ export async function runBranchPlan(opts) {
                     qaStrategy: opts.qaSessionStrategy ?? "compact", state: qaStream, createQa: opts.createQa, maxCycles: 3,
                     sessionBoundary: opts.qaSessionBoundary,
                     observeNativeCompactions: opts.observeQaNativeCompactions,
+                    resolveBlocked: (adapter, reason) => foreman.resolveBlocker(adapter, reason),
                     evidence: (entry) => opts.log.write("qa-evidence", { ticket: node.ticket.id, ...entry }),
                     fix: async (issues) => {
                         if (!builder)
@@ -267,8 +272,13 @@ export async function runBranchPlan(opts) {
                         }
                         if (opts.beforeBuilderTurn)
                             builder = await opts.beforeBuilderTurn(builder, fixInstruction, worktreePath);
-                        const fixed = await builder.sendTurn(fixInstruction);
-                        const fixedStatus = parseStepStatus(fixed.text);
+                        let fixed = await builder.sendTurn(fixInstruction);
+                        let fixedStatus = parseStepStatus(fixed.text);
+                        if (!fixed.isError && fixedStatus.kind === "blocked") {
+                            const resolved = await foreman.resolveBlocker(builder, fixedStatus.reason ?? "Builder QA fix reported an unspecified blocker");
+                            fixed = resolved.result;
+                            fixedStatus = resolved.status;
+                        }
                         const fixedSessionId = builder.sessionId();
                         const fixedSessionRef = builder.sessionRef?.();
                         if (fixedSessionId)

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.

package/dist/foreman.js

@@ -1,9 +1,10 @@
-import { select, isCancel } from "@clack/prompts";
+import { select, text, isCancel } from "@clack/prompts";
 import { MARKER_SPEC, QA_MARKER_SPEC } from "./markers.js";
 import { countProviderQuestions, handleProviderQuestionTool } from "./providerQuestions.js";
-import { fireNotification } from "./notify.js";
+import { signalAttention } from "./notify.js";
+import { pauseActivityForInput } from "./activity.js";
 import { isTicketsInitialized, loadTicketsConfig } from "./tickets/config.js";
-import { cmdUpdate, cmdComplete, cmdBlock, cmdImplementationQueue } from "./tickets/commands.js";
+import { cmdUpdate, cmdComplete, cmdBlock, cmdUnblock, cmdImplementationQueue } from "./tickets/commands.js";
 import { loadTickets } from "./tickets/ticketLoader.js";
 import { runIsolatedQa } from "./qaReview.js";
 import { createHash } from "node:crypto";
@@ -216,7 +217,6 @@ export function createPermissionHandler(policy, log, opts = {}) {
 export class Foreman {
     builder;
     log;
-    notificationsEnabled;
     qaEnabled;
     qaMaxCycles;
     projectDir;
@@ -232,14 +232,15 @@ export class Foreman {
     observeQaNativeCompactions;
     observeBuilderNativeCompactions;
     ticketsEnabled;
+    notificationsEnabled;
+    terminalBellEnabled;
     qaStream = { reviews: 0, modificationViolations: 0 };
     builderWorkSessions = 0;
-    constructor(builder, log, notificationsEnabled = false, qaEnabled = true, qaMaxCycles = 3, projectDir, qaReviewer, qaFactory, qaSessionStrategy = "compact", builderFactory, builderSessionStrategy = "compact", qaNonconvergence, beforeBuilderTurn, builderSessionBoundary, qaSessionBoundary, observeQaNativeCompactions, 
+    constructor(builder, log, notifications = false, qaEnabled = true, qaMaxCycles = 3, projectDir, qaReviewer, qaFactory, qaSessionStrategy = "compact", builderFactory, builderSessionStrategy = "compact", qaNonconvergence, beforeBuilderTurn, builderSessionBoundary, qaSessionBoundary, observeQaNativeCompactions, 
     /** Persist a Builder's provider-native event immediately after every turn. */
     observeBuilderNativeCompactions) {
         this.builder = builder;
         this.log = log;
-        this.notificationsEnabled = notificationsEnabled;
         this.qaEnabled = qaEnabled;
         this.qaMaxCycles = qaMaxCycles;
         this.projectDir = projectDir;
@@ -254,6 +255,8 @@ export class Foreman {
         this.qaSessionBoundary = qaSessionBoundary;
         this.observeQaNativeCompactions = observeQaNativeCompactions;
         this.observeBuilderNativeCompactions = observeBuilderNativeCompactions;
+        this.notificationsEnabled = typeof notifications === "boolean" ? notifications : notifications.desktop;
+        this.terminalBellEnabled = typeof notifications === "boolean" ? true : notifications.terminalBell;
         this.ticketsEnabled = !!(projectDir && isTicketsInitialized(projectDir));
     }
     /**
@@ -338,33 +341,67 @@ export class Foreman {
                     status = { ...status, error: `protocol correction exhausted: ${status.error ?? "missing final marker"}` };
             }
         }
-        while (status.kind === "needs_input") {
-            const question = status.question ?? "The builder has a question";
-            const choices = status.choices?.length
-                ? status.choices
-                : ["Continue", "Cancel"];
-            this.log.write("needs_input", { question, choices });
-            if (this.notificationsEnabled) {
-                fireNotification("Foreman needs your input", question);
+        while (true) {
+            while (status.kind === "needs_input") {
+                const question = status.question ?? "The builder has a question";
+                const choices = status.choices?.length ? status.choices : ["Continue"];
+                this.log.write("needs_input", { question, choices });
+                signalAttention("Foreman needs your input", question, this.notificationsEnabled, this.terminalBellEnabled);
+                if (!process.stdin.isTTY || !process.stdout.isTTY) {
+                    console.error(`foreman: input required: ${question}`);
+                    console.error("foreman: resume this run in an interactive terminal, or provide explicit guidance through the printed resume command");
+                    result = { text: result.text, isError: false, numTurns: result.numTurns, costUsd: result.costUsd };
+                    status = { kind: "blocked", reason: `input required in an interactive terminal: ${question}` };
+                    break;
+                }
+                const answer = await pauseActivityForInput(async () => {
+                    console.log();
+                    const selected = await select({
+                        message: question,
+                        options: [
+                            ...choices.map((choice) => ({ value: choice, label: choice })),
+                            { value: "__rafi_custom__", label: "Custom response", hint: "Type a different answer" },
+                            { value: "__rafi_pause__", label: "Pause safely", hint: "Keep the run recoverable and return to the terminal" },
+                        ],
+                    });
+                    if (isCancel(selected) || selected === "__rafi_pause__")
+                        return undefined;
+                    if (selected !== "__rafi_custom__")
+                        return selected;
+                    const custom = await text({ message: "Custom response:", validate: (value) => String(value ?? "").trim() ? undefined : "Enter a response" });
+                    return isCancel(custom) ? undefined : String(custom);
+                });
+                console.log();
+                if (answer === undefined) {
+                    result = { text: "", isError: false, numTurns: 0, costUsd: 0 };
+                    status = { kind: "blocked", reason: "user chose safe pause at an input prompt" };
+                    break;
+                }
+                if (adapter === this.builder && this.beforeBuilderTurn) {
+                    this.builder = await this.beforeBuilderTurn(this.builder, answer);
+                    adapter = this.builder;
+                }
+                result = await adapter.sendTurn(answer);
+                await this.observeBuilderNative(adapter);
+                status = parseStepStatus(result.text);
             }
-            console.log();
-            const answer = await select({
-                message: question,
-                options: choices.map((c) => ({ value: c, label: c })),
-            });
-            console.log();
-            if (isCancel(answer)) {
-                result = { text: "", isError: false, numTurns: 0, costUsd: 0 };
-                status = { kind: "blocked", reason: "user cancelled at input prompt" };
+            if (status.kind !== "blocked" || status.reason?.startsWith("user chose safe pause") || !process.stdin.isTTY || !process.stdout.isTTY)
                 break;
-            }
+            const reason = status.reason ?? "the agent reported an unspecified blocker";
+            this.log.write("blocked-recovery", { reason, role: adapter === this.builder ? "builder" : "qa" });
+            const recoveryInstruction = buildBlockerRecoveryInstruction(reason);
             if (adapter === this.builder && this.beforeBuilderTurn) {
-                this.builder = await this.beforeBuilderTurn(this.builder, String(answer));
+                this.builder = await this.beforeBuilderTurn(this.builder, recoveryInstruction);
                 adapter = this.builder;
             }
-            result = await adapter.sendTurn(String(answer));
+            result = await adapter.sendTurn(recoveryInstruction);
             await this.observeBuilderNative(adapter);
             status = parseStepStatus(result.text);
+            if (status.kind === "unknown") {
+                result = await adapter.sendTurn('Protocol correction only: return the blocker approaches now using exactly one final STEP_STATUS: needs_input marker with question="..." and choices="recommended (Recommended)|alternative|alternative". Do not repeat tools or implementation.');
+                await this.observeBuilderNative(adapter);
+                status = parseStepStatus(result.text);
+            }
         }
         return { result, status };
     }
@@ -398,6 +435,10 @@ export class Foreman {
     async runInstruction(instruction) {
         return this.doTurn(instruction);
     }
+    /** Ask an already-active role session to propose choices for its reported blocker. */
+    async resolveBlocker(adapter, reason) {
+        return this.doTurnWith(adapter, buildBlockerRecoveryInstruction(reason));
+    }
     async observeBuilderNative(adapter) {
         if (adapter === this.builder)
             await this.observeBuilderNativeCompactions?.(adapter);
@@ -431,6 +472,7 @@ export class Foreman {
                 },
                 evidence: ({ cycle, outcome, detail, qaDiff }) => this.log.write("qa", { stepIndex, cycle, outcome, detail, qaDiff, disposable: true }),
                 onNonconvergence: this.qaNonconvergence,
+                resolveBlocked: (adapter, reason) => this.resolveBlocker(adapter, reason),
             });
             if (review.outcome === "nonconverged")
                 return { outcome: "needs-human", detail: review.detail };
@@ -539,7 +581,10 @@ export class Foreman {
                         detail = `recovery ticket ${preferredTicketId} is no longer available in the implementation queue`;
                         break;
                     }
-                    if (i === 1 && preferredTicketId && next && next.status !== "next" && next.status !== "in_progress") {
+                    if (i === 1 && preferredTicketId && next?.status === "blocked") {
+                        cmdUnblock(this.projectDir, preferredTicketId, { actor: "foreman", summary: "Reopened by explicit build recovery" });
+                    }
+                    else if (i === 1 && preferredTicketId && next && next.status !== "next" && next.status !== "in_progress") {
                         outcome = "needs-human";
                         detail = `recovery ticket ${preferredTicketId} cannot resume while its status is ${next.status}`;
                         break;
@@ -672,6 +717,16 @@ function lastLine(text) {
     const lines = text.trim().split("\n");
     return (lines[lines.length - 1] ?? "").slice(0, 200);
 }
+function buildBlockerRecoveryInstruction(reason) {
+    return [
+        `You reported this blocker: ${reason}`,
+        "Do not end the run. Analyze the durable state and propose two or three safe, materially different approaches the user can choose from.",
+        "Put your recommended approach first and end its label with (Recommended). Include the important consequence or tradeoff in every choice label.",
+        "Do not perform more implementation or QA work until the user chooses. End exactly with:",
+        'STEP_STATUS: needs_input | question="How should Rafi unblock this work?" choices="recommended approach and consequence (Recommended)|alternative and consequence|another alternative and consequence"',
+        "After the user answers, apply that guidance in this same session. If still blocked, report blocked again so Rafi can offer a new set of approaches.",
+    ].join("\n\n");
+}
 function fingerprintProtectedTree(root) {
     const out = new Map();
     const ignored = new Set([".git", "node_modules", "dist", "coverage"]);

package/dist/handoffs.d.ts

@@ -45,14 +45,42 @@ export declare class HandoffLoopError extends Error {
     readonly runId: string;
     constructor(runId: string);
 }
+export type HandoffAcceptanceFailureCode = "missing-acknowledgement" | "invalid-continuity-delta" | "missing-successor-session" | "missing-scoped-successor-session" | "reused-predecessor-session";
+export declare class HandoffAcceptanceError extends Error {
+    readonly code: HandoffAcceptanceFailureCode;
+    readonly runId: string;
+    readonly generation: number;
+    constructor(code: HandoffAcceptanceFailureCode, runId: string, generation: number, detail: string);
+}
+export declare class HandoffRecoveryPausedError extends Error {
+    readonly runId: string;
+    readonly generation: number;
+    constructor(runId: string, generation: number, detail: string);
+}
+export type HandoffRecoveryChoice = "retry" | "switch" | "custom" | "pause";
+export interface HandoffRecoveryOptions {
+    /** Enables the provider-switch choice. The callback must honor the requested runtime. */
+    allowProviderSwitch?: boolean;
+    choose?: (error: HandoffAcceptanceError, currentRuntime: "claude" | "codex") => Promise<HandoffRecoveryChoice>;
+    customGuidance?: () => Promise<string | undefined>;
+    desktopNotifications?: boolean;
+    terminalBell?: boolean;
+    /** Persist run-local provider selection only after validated acceptance. */
+    onAccepted?: (result: HandoffTransferResult) => void | Promise<void>;
+}
 /** Durable, validated ownership transfer; cache copies are never authoritative. */
 export declare class HandoffService {
     readonly projectDir: string;
     readonly cacheRoot: string;
     constructor(projectDir: string);
     stage(input: CreateHandoffInput, now?: Date): StagedHandoff;
-    transfer(input: CreateHandoffInput, createSuccessor: (handoff: StagedHandoff) => Promise<BuilderAdapter>): Promise<HandoffTransferResult>;
-    acceptStaged(staged: StagedHandoff, successor: BuilderAdapter): Promise<HandoffTransferResult>;
+    transfer(input: CreateHandoffInput, createSuccessor: (handoff: StagedHandoff, requestedRuntime?: "claude" | "codex") => Promise<BuilderAdapter>, recovery?: HandoffRecoveryOptions): Promise<HandoffTransferResult>;
+    acceptStagedWithRecovery(staged: StagedHandoff, initialSuccessor: BuilderAdapter, createSuccessor: (handoff: StagedHandoff, requestedRuntime?: "claude" | "codex") => Promise<BuilderAdapter>, recovery?: HandoffRecoveryOptions): Promise<HandoffTransferResult>;
+    acceptStaged(staged: StagedHandoff, successor: BuilderAdapter, options?: {
+        finalizeFailure?: boolean;
+        guidance?: string;
+    }): Promise<HandoffTransferResult>;
+    private failStaged;
     inspect(runId: string, generation?: number): {
         manifest: HandoffManifestV1;
         markdown: string;

package/dist/handoffs.js

@@ -3,6 +3,8 @@ import { existsSync, mkdirSync, mkdtempSync, readdirSync, renameSync, rmSync, st
 import { dirname, join, resolve } from "node:path";
 import { continuityInstruction, mergeContinuityDeltas, parseContinuityDelta } from "./continuity.js";
 import { WorkflowDb } from "./workflowDb.js";
+import { pauseActivityForInput } from "./activity.js";
+import { signalAttention } from "./notify.js";
 export const HANDOFF_CACHE_RETENTION_DAYS = 30;
 export const HANDOFF_ACCEPTED = "HANDOFF_ACCEPTED";
 export const HANDOFF_REQUEST_START = "RAFI_HANDOFF_REQUEST_START";
@@ -55,6 +57,28 @@ export class HandoffLoopError extends Error {
         this.runId = runId;
     }
 }
+export class HandoffAcceptanceError extends Error {
+    code;
+    runId;
+    generation;
+    constructor(code, runId, generation, detail) {
+        super(`handoff acceptance rejected (${code}): ${detail}; predecessor retains the lease`);
+        this.code = code;
+        this.runId = runId;
+        this.generation = generation;
+        this.name = "HandoffAcceptanceError";
+    }
+}
+export class HandoffRecoveryPausedError extends Error {
+    runId;
+    generation;
+    constructor(runId, generation, detail) {
+        super(`handoff recovery paused safely: ${detail}`);
+        this.runId = runId;
+        this.generation = generation;
+        this.name = "HandoffRecoveryPausedError";
+    }
+}
 /** Durable, validated ownership transfer; cache copies are never authoritative. */
 export class HandoffService {
     projectDir;
@@ -130,34 +154,86 @@ export class HandoffService {
             db.close();
         }
     }
-    async transfer(input, createSuccessor) {
+    async transfer(input, createSuccessor, recovery = {}) {
         const staged = this.stage(input);
         const successor = await createSuccessor(staged);
-        return this.acceptStaged(staged, successor);
+        return this.acceptStagedWithRecovery(staged, successor, createSuccessor, recovery);
     }
-    async acceptStaged(staged, successor) {
+    async acceptStagedWithRecovery(staged, initialSuccessor, createSuccessor, recovery = {}) {
+        let successor = initialSuccessor;
+        let guidance;
+        while (true) {
+            try {
+                const accepted = await this.acceptStaged(staged, successor, { finalizeFailure: false, guidance });
+                await recovery.onAccepted?.(accepted);
+                return accepted;
+            }
+            catch (error) {
+                if (!(error instanceof HandoffAcceptanceError)) {
+                    this.failStaged(staged, error instanceof Error ? error.message : String(error));
+                    throw error;
+                }
+                if ((!process.stdin.isTTY || !process.stdout.isTTY) && !recovery.choose) {
+                    this.failStaged(staged, error.message);
+                    throw error;
+                }
+                signalAttention("Rafi handoff needs input", error.message, recovery.desktopNotifications, recovery.terminalBell);
+                const currentRuntime = successor.agent;
+                const choice = recovery.choose
+                    ? await recovery.choose(error, currentRuntime)
+                    : await promptHandoffRecovery(error, currentRuntime, Boolean(recovery.allowProviderSwitch));
+                if (choice === "pause") {
+                    this.failStaged(staged, `user paused after ${error.code}`);
+                    throw new HandoffRecoveryPausedError(staged.manifest.runId, staged.manifest.generation, error.message);
+                }
+                guidance = undefined;
+                let requestedRuntime;
+                if (choice === "switch")
+                    requestedRuntime = currentRuntime === "claude" ? "codex" : "claude";
+                if (choice === "custom") {
+                    guidance = recovery.customGuidance ? await recovery.customGuidance() : await promptCustomHandoffGuidance();
+                    if (!guidance) {
+                        successor = await createSuccessor(staged);
+                        continue;
+                    }
+                }
+                successor = await createSuccessor(staged, requestedRuntime);
+                if (requestedRuntime && successor.agent !== requestedRuntime) {
+                    await successor.close().catch(() => { });
+                    console.warn(`foreman: ${requestedRuntime} was not available from the successor factory; choose another handoff recovery option`);
+                    successor = await createSuccessor(staged);
+                }
+            }
+        }
+    }
+    async acceptStaged(staged, successor, options = {}) {
         const db = new WorkflowDb(this.projectDir);
         try {
-            const response = await successor.sendTurn([
+            const acceptancePrompt = [
                 "Accept this validated Rafi handoff. Do not repeat completed work and reconcile host receipts before side effects.",
                 staged.markdown,
                 `Manifest JSON: ${JSON.stringify(staged.manifest)}`,
+                ...(options.guidance ? [`Human recovery guidance: ${options.guidance}`] : []),
                 `Reply with ${HANDOFF_ACCEPTED} on the first line, then ${continuityInstruction()}`,
-            ].join("\n\n"));
+            ].join("\n\n");
+            let response = await successor.sendTurn(acceptancePrompt);
+            let validation = validateHandoffAcceptance(staged, successor, response.text);
+            if (validation && (validation.code === "missing-acknowledgement" || validation.code === "invalid-continuity-delta")) {
+                response = await successor.sendTurn([
+                    `Your handoff acknowledgement was rejected: ${validation.message}.`,
+                    "Correction only: do not use tools, repeat completed work, or perform implementation.",
+                    `Reply with ${HANDOFF_ACCEPTED} on the first line, then ${continuityInstruction()}`,
+                ].join("\n\n"));
+                validation = validateHandoffAcceptance(staged, successor, response.text);
+            }
+            if (validation)
+                throw new HandoffAcceptanceError(validation.code, staged.manifest.runId, staged.manifest.generation, validation.message);
             const parsed = parseContinuityDelta(response.text);
             const sessionId = successor.sessionId();
             const observedSuccessorRef = successor.sessionRef?.();
             const successorRef = observedSuccessorRef ? { ...observedSuccessorRef, generation: staged.manifest.generation, validatedAt: new Date().toISOString() } : undefined;
-            if (!response.text.trimStart().startsWith(HANDOFF_ACCEPTED) || !parsed.delta || !sessionId || (staged.manifest.predecessorSessionRef && !successorRef)) {
-                db.failHandoff(staged.manifest.runId, staged.manifest.generation, "successor did not provide HANDOFF_ACCEPTED, a valid continuity delta, and a fresh session identity");
-                await successor.close().catch(() => { });
-                throw new Error("fresh successor failed validated handoff acceptance; predecessor retains the lease");
-            }
-            if (staged.manifest.predecessorSessionId && sessionId === staged.manifest.predecessorSessionId) {
-                db.failHandoff(staged.manifest.runId, staged.manifest.generation, "successor reused predecessor session ID");
-                await successor.close().catch(() => { });
-                throw new Error("handoff successor must be a genuinely fresh provider session");
-            }
+            if (!parsed.delta || !sessionId)
+                throw new Error("validated handoff acceptance lost its parsed continuity state");
             if (successorRef)
                 successor.adoptSessionRef?.(successorRef);
             db.appendContinuityEvent({ runId: staged.manifest.runId, role: staged.manifest.role, kind: "handoff_successor_accepted", payload: { generation: staged.manifest.generation, sessionId, sessionRef: successorRef, delta: parsed.delta }, authoritativeStateRevision: db.continuityHead(staged.manifest.runId, staged.manifest.role)?.authoritativeStateRevision ?? 0, sessionRef: successorRef });
@@ -166,8 +242,10 @@ export class HandoffService {
             return { ...staged, lineage, successor, successorSessionId: sessionId, acceptanceCheckpointDigest: checkpoint.digest };
         }
         catch (error) {
+            if (error instanceof HandoffAcceptanceError)
+                await successor.close().catch(() => { });
             const current = db.handoff(staged.manifest.runId, staged.manifest.generation);
-            if (current?.state === "staged")
+            if (options.finalizeFailure !== false && current?.state === "staged")
                 db.failHandoff(staged.manifest.runId, staged.manifest.generation, error instanceof Error ? error.message : String(error));
             throw error;
         }
@@ -175,6 +253,17 @@ export class HandoffService {
             db.close();
         }
     }
+    failStaged(staged, detail) {
+        const db = new WorkflowDb(this.projectDir);
+        try {
+            if (db.handoff(staged.manifest.runId, staged.manifest.generation)?.state === "staged") {
+                db.failHandoff(staged.manifest.runId, staged.manifest.generation, detail);
+            }
+        }
+        finally {
+            db.close();
+        }
+    }
     inspect(runId, generation) {
         const db = new WorkflowDb(this.projectDir);
         try {
@@ -275,6 +364,52 @@ export class HandoffService {
         return count;
     }
 }
+function validateHandoffAcceptance(staged, successor, text) {
+    if (!text.trimStart().startsWith(HANDOFF_ACCEPTED)) {
+        return { code: "missing-acknowledgement", message: `the first non-whitespace line must begin with ${HANDOFF_ACCEPTED}` };
+    }
+    const parsed = parseContinuityDelta(text);
+    if (!parsed.delta) {
+        return { code: "invalid-continuity-delta", message: parsed.error?.problems.join("; ") ?? "the continuity delta is missing or malformed" };
+    }
+    const sessionId = successor.sessionId();
+    if (!sessionId)
+        return { code: "missing-successor-session", message: "the provider did not expose a successor session ID" };
+    if (staged.manifest.predecessorSessionRef && !successor.sessionRef?.()) {
+        return { code: "missing-scoped-successor-session", message: "the provider did not expose a location-scoped successor session reference" };
+    }
+    if (staged.manifest.predecessorSessionId && sessionId === staged.manifest.predecessorSessionId) {
+        return { code: "reused-predecessor-session", message: `successor reused predecessor session ${sessionId}; a genuinely fresh session is required` };
+    }
+    return undefined;
+}
+async function promptHandoffRecovery(error, runtime, allowProviderSwitch) {
+    const { select, isCancel } = await import("@clack/prompts");
+    return pauseActivityForInput(async () => {
+        console.error(`foreman: ${error.message}`);
+        const other = runtime === "claude" ? "codex" : "claude";
+        const answer = await select({
+            message: "How should Rafi recover the rejected successor handoff?",
+            options: [
+                { value: "retry", label: `Retry ${runtime} with a fresh successor (Recommended)`, hint: "The rejected successor is closed; the predecessor keeps its lease" },
+                ...(allowProviderSwitch ? [{ value: "switch", label: `Switch to verified ${other}`, hint: "Use a fresh provider session without changing project defaults" }] : []),
+                { value: "custom", label: "Add custom guidance and retry", hint: "Give the next fresh successor an explicit correction" },
+                { value: "pause", label: "Pause safely", hint: "Keep the predecessor lease and return recovery instructions" },
+            ],
+        });
+        return isCancel(answer) ? "pause" : answer;
+    });
+}
+async function promptCustomHandoffGuidance() {
+    const { text, isCancel } = await import("@clack/prompts");
+    return pauseActivityForInput(async () => {
+        const answer = await text({
+            message: "Guidance for the next fresh successor:",
+            validate: (value) => String(value ?? "").trim() ? undefined : "Enter guidance",
+        });
+        return isCancel(answer) ? undefined : String(answer);
+    });
+}
 export function renderHandoffMarkdown(manifest) {
     const section = (title, values) => [`## ${title}`, "", ...(values.length ? values.map((value) => `- ${value}`) : ["- None recorded."]), ""];
     return [

package/dist/log.d.ts

@@ -1,7 +1,7 @@
 /** A single structured log record. */
 export interface LogRecord {
     ts: string;
-    event: "batch-start" | "batch-end" | "branch-plan" | "branch-start" | "branch-session" | "branch-resume" | "branch-issue" | "branch-complete" | "branch-push" | "github-readiness-failed" | "gitlab-readiness-failed" | "pr-created" | "pr-existing" | "pr-failed" | "pr-auto-merge-enabled" | "pr-auto-merge-failed" | "mr-created" | "mr-existing" | "mr-failed" | "mr-auto-merge-enabled" | "mr-auto-merge-failed" | "branch-auto-merge-wait" | "branch-direct-merge" | "step" | "permission" | "escalation" | "needs_input" | "preflight" | "rafi-plan" | "ticket-populate" | "uninstall-proposal" | "qa" | "qa-fix" | "qa-protected-files-changed" | "qa-evidence" | "agent-status" | "context-lifecycle" | "handoff-transfer" | "recovery-handoff-accepted" | "guided-recovery-required" | "safe-boundary-paused" | "session-unavailable" | "error";
+    event: "batch-start" | "batch-end" | "branch-plan" | "branch-start" | "branch-session" | "branch-resume" | "branch-issue" | "branch-complete" | "branch-push" | "github-readiness-failed" | "gitlab-readiness-failed" | "pr-created" | "pr-existing" | "pr-failed" | "pr-auto-merge-enabled" | "pr-auto-merge-failed" | "mr-created" | "mr-existing" | "mr-failed" | "mr-auto-merge-enabled" | "mr-auto-merge-failed" | "branch-auto-merge-wait" | "branch-direct-merge" | "step" | "permission" | "escalation" | "needs_input" | "blocked-recovery" | "preflight" | "rafi-plan" | "ticket-populate" | "uninstall-proposal" | "qa" | "qa-fix" | "qa-protected-files-changed" | "qa-evidence" | "agent-status" | "context-lifecycle" | "handoff-transfer" | "recovery-handoff-accepted" | "guided-recovery-required" | "safe-boundary-paused" | "session-unavailable" | "error";
     [key: string]: unknown;
 }
 /** Append-only JSONL logger. One line per record, plus an echo to the console. */

package/dist/notify.d.ts

@@ -7,3 +7,7 @@
  * WSL    : powershell.exe Windows toast (no extra install required)
  */
 export declare function fireNotification(title: string, body: string): void;
+/** Ring one best-effort terminal bell for a user-attention boundary. */
+export declare function fireTerminalBell(enabled?: boolean): void;
+/** Notify through the terminal by default and through the desktop when opted in. */
+export declare function signalAttention(title: string, body: string, desktop?: boolean, terminalBell?: boolean): void;

package/dist/notify.js

@@ -47,3 +47,18 @@ export function fireNotification(title, body) {
         // best-effort — never crash the run
     }
 }
+/** Ring one best-effort terminal bell for a user-attention boundary. */
+export function fireTerminalBell(enabled = true) {
+    if (!enabled || !process.stderr.isTTY)
+        return;
+    try {
+        process.stderr.write("\u0007");
+    }
+    catch { /* best-effort */ }
+}
+/** Notify through the terminal by default and through the desktop when opted in. */
+export function signalAttention(title, body, desktop = false, terminalBell = true) {
+    fireTerminalBell(terminalBell);
+    if (desktop)
+        fireNotification(title, body);
+}

package/dist/qaReview.d.ts

@@ -43,6 +43,11 @@ export interface IsolatedQaOptions {
         qaDiff?: string[];
     }) => void;
     onNonconvergence?: (context: QaNonconvergenceContext) => Promise<QaNonconvergenceDecision>;
+    /** Resolve a QA blocker with the same still-open QA session before disposal. */
+    resolveBlocked?: (adapter: BuilderAdapter, reason: string) => Promise<{
+        result: import("./adapters/types.js").TurnResult;
+        status: import("./foreman.js").StepStatus;
+    }>;
 }
 export interface IsolatedQaResult {
     outcome: "passed" | "blocked" | "needs-human" | "nonconverged" | "waived";

package/dist/qaReview.js

@@ -49,9 +49,15 @@ async function oneReview(opts, cycle) {
         // continuity/checkpoint stream; an old provider session is never moved
         // into a newly-created /tmp/rafi-qa-* directory.
         qa = await opts.createQa(snapshot.path);
-        const turn = await qa.sendTurn(handoff);
-        const status = parseStepStatus(turn.text);
+        let turn = await qa.sendTurn(handoff);
+        let status = parseStepStatus(turn.text);
         await opts.observeNativeCompactions?.(qa);
+        if (!turn.isError && status.kind === "blocked" && opts.resolveBlocked) {
+            const resolved = await opts.resolveBlocked(qa, status.reason ?? "QA reported an unspecified blocker");
+            turn = resolved.result;
+            status = resolved.status;
+            await opts.observeNativeCompactions?.(qa);
+        }
         opts.state.reviews += 1;
         opts.state.sessionId = qa.sessionId();
         opts.state.sessionRef = qa.sessionRef?.();
@@ -66,6 +72,8 @@ async function oneReview(opts, cycle) {
         opts.state.modificationViolations = 0;
         if (turn.isError)
             return { outcome: "blocked", detail: turn.text.slice(0, 500) };
+        if (status.kind === "blocked")
+            return { outcome: "blocked", detail: status.reason ?? "QA reported blocked" };
         if (status.kind === "qa_pass") {
             opts.evidence?.({ cycle, outcome: "passed", detail: status.summary ?? "qa_pass" });
             return { outcome: "passed", summary: status.summary };

package/foreman.yaml

@@ -75,6 +75,10 @@ permissions:
     - WebSearch
 
 notifications:
+  # Ring once when input is required and once when a master run finishes.
+  # Default: true.
+  terminal_bell: true
+
   # When enabled, a desktop notification fires whenever the builder emits
   # STEP_STATUS: needs_input — useful if you've walked away and need a nudge
   # to come back to the terminal to answer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-foreman",
-  "version": "1.7.11",
+  "version": "1.7.12",
   "description": "An orchestrator that keeps Codex CLI / Claude Code builders moving through their step list unattended. Part of Rafi.",
   "license": "Apache-2.0",
   "type": "module",
@@ -159,7 +159,7 @@
   },
   "dependencies": {
     "special-agents": "0.8.7",
-    "rafi-spec": "0.8.7",
+    "rafi-spec": "0.8.8",
     "@clack/prompts": "^1.4.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",