ai-foreman 1.7.11 → 1.7.13

package/dist/cli/start.js

@@ -2,7 +2,7 @@ import { Command } from "commander";
 import { resolve, join, relative } from "node:path";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { execFileSync } from "node:child_process";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { select, text, isCancel } from "@clack/prompts";
 import { loadConfig } from "../config.js";
 import { Log } from "../log.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,14 +39,37 @@ 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";
+import { ObservabilityStore, RunObserver } from "../observability.js";
+import { loadProjectAutonomyConfig, resolveAutonomyPolicy, resolveQaEnablement } from "../recoveryPolicy.js";
+import { loadQaRecoveryPacket } from "../qaRecovery.js";
+import { loadSkill } from "special-agents";
+const FOREMAN_VERSION = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
 function fail(message) {
     console.error(`foreman: ${message}`);
     process.exit(1);
 }
+function pendingQaRecoveryPacket(projectDir, runId) {
+    const db = new WorkflowDb(projectDir);
+    try {
+        const pending = db.getRun(runId)?.state.qaReportRecovery;
+        if (!pending || typeof pending !== "object")
+            return undefined;
+        const state = pending;
+        if (state.pendingAction !== "operator-menu" || typeof state.packetPath !== "string" || typeof state.packetDigest !== "string")
+            return undefined;
+        const packet = loadQaRecoveryPacket(state.packetPath);
+        if (packet.manifest.packetDigest !== state.packetDigest || packet.manifest.runId !== runId)
+            throw new Error("saved QA recovery packet does not match its durable pending-decision state");
+        return packet;
+    }
+    finally {
+        db.close();
+    }
+}
 function findLastSessionId(dir) {
     if (!existsSync(dir))
         return undefined;
@@ -310,6 +334,9 @@ export function buildStartCommand() {
         .option("--effort <level>", "reasoning effort level (low|medium|high|xhigh)")
         .option("--fast", "fast mode — lower latency (maps to effort=low for codex)")
         .option("--no-qa", "disable per-ticket QA review (enabled by default)")
+        .option("--autonomy <profile>", "autonomy profile (supervised | balanced | unattended)")
+        .option("--detach", "return after launching the durable supervisor")
+        .option("--no-supervisor", "run the compatibility worker directly without supervision")
         .option("--branch-per-ticket", "run each selected structured ticket in an isolated git worktree and branch")
         .option("--no-branch-per-ticket", "disable saved branch-per-ticket defaults for this run")
         .option("--create-pr", "push each successful ticket branch and create a GitHub PR (implies --branch-per-ticket)")
@@ -374,6 +401,15 @@ 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 autonomyProfile = opts.autonomy;
+        if (autonomyProfile && !["supervised", "balanced", "unattended"].includes(autonomyProfile))
+            fail("--autonomy must be supervised, balanced, or unattended");
+        const frozenPolicy = recoveryRecord && "frozenPolicy" in recoveryRecord
+            ? recoveryRecord.frozenPolicy
+            : resolveAutonomyPolicy(loadProjectAutonomyConfig(cwd), autonomyProfile);
+        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)))
@@ -603,7 +639,43 @@ export function buildStartCommand() {
         const stamp = new Date().toISOString().replace(/[:.]/g, "-");
         const logPath = join(cwd, ".foreman", `${stamp}.jsonl`);
         const log = new Log(logPath);
-        const qaEnabled = opts.qa !== false && config.qa.enabled !== false;
+        const qaResolution = resolveQaEnablement({
+            cli: command.getOptionValueSource("qa") === "cli" ? Boolean(opts.qa) : undefined,
+            frozen: recoveryRecord && "qaEnabled" in recoveryRecord ? Boolean(recoveryRecord.qaEnabled) : undefined,
+            projectDir: cwd,
+            legacyForeman: config.qa.enabled,
+        });
+        const qaEnabled = qaResolution.enabled;
+        if (qaResolution.deprecationWarning)
+            console.error(`rafi: warning: ${qaResolution.deprecationWarning}`);
+        const invocationRunId = recoveryRecord?.runId ?? randomUUID();
+        let observabilityStore;
+        if (config.observability.enabled) {
+            try {
+                observabilityStore = new ObservabilityStore(cwd, { config: config.observability });
+            }
+            catch (error) {
+                console.error(`rafi: observability unavailable; build will continue: ${String(error).replace(/\s+/g, " ").slice(0, 300)}`);
+            }
+        }
+        let activeObserver = observabilityStore ? new RunObserver(observabilityStore, invocationRunId) : undefined;
+        const finishObservationOnExit = () => {
+            if (!activeObserver)
+                return;
+            activeObserver.finish("interrupted");
+            observabilityStore?.closeLogFile(logPath, "interrupted");
+            observabilityStore?.close();
+            activeObserver = undefined;
+        };
+        process.once("exit", finishObservationOnExit);
+        activeObserver?.startResourceSampling();
+        observabilityStore?.recordCapabilities(invocationRunId, {
+            provider_turns: { source: "provider_turns", state: "available", observedAt: new Date().toISOString() },
+            tools: { source: "tools", state: "available", observedAt: new Date().toISOString() },
+            process_resources: { source: "process_resources", state: "available", observedAt: new Date().toISOString() },
+            child_process_resources: { source: "child_process_resources", state: "unavailable", observedAt: new Date().toISOString(), detail: "provider child-process attribution is unsupported" },
+        }, FOREMAN_VERSION);
+        observabilityStore?.indexLogFile(logPath, invocationRunId);
         const createRawBuilder = async (builderCwd, sessionId, sessionRef) => {
             const builderPolicy = new PermissionPolicy(config.permissions, builderCwd, { currentBranchWorkflow: !branchMode });
             const roleBundle = loadRoleBundle("builder", { projectDir: builderCwd });
@@ -626,6 +698,7 @@ export function buildStartCommand() {
                 systemPromptAppend: roleBundle.system || undefined,
                 skills: roleBundle.skills.length > 0 ? roleBundle.skills : undefined,
                 autoCompactThresholdPercent: thresholdOverride ?? roleDefaults.builder?.auto_compact_threshold_percent ?? 50,
+                observer: activeObserver,
             };
             const adapter = agent === "codex"
                 ? new CodexAdapter(adapterOpts)
@@ -676,6 +749,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",
@@ -700,6 +801,7 @@ export function buildStartCommand() {
                 systemPromptAppend: roleBundle.system || undefined,
                 skills: roleBundle.skills.length > 0 ? roleBundle.skills : undefined,
                 autoCompactThresholdPercent: settings.auto_compact_threshold_percent,
+                observer: activeObserver,
             };
             const created = settings.make === "codex" ? new CodexAdapter(adapterOptions) : await ClaudeAdapter.create(adapterOptions);
             await prepareNativeAutoCompaction(created);
@@ -728,6 +830,7 @@ export function buildStartCommand() {
                 systemPromptAppend: `${roleBundle.system}\n\nYou are an independent QA reviewer. Do not edit source, tickets, configuration, or project documentation. You may run tests and create only harmless ignored caches or coverage output.`,
                 skills: roleBundle.skills.length > 0 ? roleBundle.skills : undefined,
                 autoCompactThresholdPercent: settings.auto_compact_threshold_percent,
+                observer: activeObserver,
             };
             const created = settings.make === "codex" ? new CodexAdapter(adapterOptions) : await ClaudeAdapter.create(adapterOptions);
             await prepareNativeAutoCompaction(created);
@@ -757,7 +860,8 @@ export function buildStartCommand() {
                 initial,
                 runtime: agent,
                 label: "builder turn",
-                enabled: !opts.yes && Boolean(process.stdin.isTTY && process.stdout.isTTY),
+                observer: activeObserver,
+                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 +910,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 +958,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 +973,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 +1009,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,
@@ -947,6 +1052,7 @@ export function buildStartCommand() {
                 systemPromptAppend: `${roleBundle.system}\n\nYou are an independent QA reviewer. Do not edit source, tickets, configuration, or project documentation. You may run tests and create only harmless ignored caches or coverage output.`,
                 skills: roleBundle.skills.length > 0 ? roleBundle.skills : undefined,
                 autoCompactThresholdPercent: qaSettings.auto_compact_threshold_percent,
+                observer: activeObserver,
             };
             const created = qaSettings.make === "codex"
                 ? new CodexAdapter(adapterOpts)
@@ -960,7 +1066,8 @@ export function buildStartCommand() {
                 initial,
                 runtime: qaAgent,
                 label: "QA turn",
-                enabled: !opts.yes && Boolean(process.stdin.isTTY && process.stdout.isTTY),
+                observer: activeObserver,
+                enabled: Boolean(process.stdin.isTTY && process.stdout.isTTY),
                 allowSwitch: !sessionRef,
                 recreate: async (nextRuntime, resumeSessionId, resumeRef) => {
                     const nextReady = await ensureRuntimeReadyForCommand(qaCwd, nextRuntime, {
@@ -1025,7 +1132,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,
@@ -1080,12 +1187,15 @@ export function buildStartCommand() {
             void sessionId;
             let adapter = await createRecoveringQa(qaCwd, effectiveSessionId);
             let explicitRecoveryAccepted = false;
+            let handoffReceipt = { unavailable: "no predecessor handoff was required" };
             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;
+                handoffReceipt = { generation: accepted.manifest.generation, successorSessionId: accepted.successorSessionId, acceptanceCheckpointDigest: accepted.acceptanceCheckpointDigest };
                 log.write("recovery-handoff-accepted", { role: "qa", generation: accepted.manifest.generation, successorSessionId: accepted.successorSessionId, acceptanceCheckpointDigest: accepted.acceptanceCheckpointDigest });
             }
             // A new disposable QA worktree always means a new provider session.
@@ -1116,8 +1226,9 @@ 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;
+                    handoffReceipt = { generation: accepted.manifest.generation, successorSessionId: accepted.successorSessionId, acceptanceCheckpointDigest: accepted.acceptanceCheckpointDigest };
                     log.write("handoff-transfer", {
                         role: "qa", reason: staged.manifest.reason, generation: accepted.manifest.generation,
                         predecessorSessionId: staged.manifest.predecessorSessionId, successorSessionId: accepted.successorSessionId,
@@ -1125,7 +1236,35 @@ export function buildStartCommand() {
                     });
                 }
             }
-            return decorateQa(adapter, qaCwd, effectiveSessionId);
+            const decorated = decorateQa(adapter, qaCwd, effectiveSessionId);
+            const settings = resolvedContinuitySettings("qa");
+            const bundle = loadRoleBundle("qa", { projectDir: qaCwd });
+            const effectiveRoleInstructions = `${bundle.system}\n\nYou are an independent QA reviewer. Do not edit source, tickets, configuration, or project documentation. You may run tests and create only harmless ignored caches or coverage output.`;
+            return {
+                adapter: decorated,
+                sessionIdentity: decorated.sessionRef?.() ?? decorated.sessionId(),
+                effectiveRoleInstructions,
+                runtimeContext: settings,
+                skills: bundle.skills.map((name) => {
+                    const path = [join(qaCwd, ".agents", "skills", name, "SKILL.md"), join(qaCwd, ".claude", "skills", name, "SKILL.md"), join(qaCwd, ".codex", "skills", name, "SKILL.md")].find(existsSync);
+                    if (path) {
+                        const dispatchedContent = `## ${name}\n${readFileSync(path, "utf8").trim()}`;
+                        return { name, path, digest: createHash("sha256").update(dispatchedContent).digest("hex") };
+                    }
+                    if (settings.make === "codex") {
+                        try {
+                            const bundled = loadSkill(name);
+                            if (bundled.body?.trim()) {
+                                const dispatchedContent = `## ${bundled.name}\n${bundled.body.trim()}`;
+                                return { name, path: `special-agents:${name}`, digest: createHash("sha256").update(dispatchedContent).digest("hex") };
+                            }
+                        }
+                        catch { /* explicit unavailable result below */ }
+                    }
+                    return { name, digest: "unavailable", reason: "runtime skill name had no resolvable loaded skill content" };
+                }),
+                handoffReceipt,
+            };
         };
         const applyQaSettingsBoundary = async (runId, qaCwd, input) => {
             const context = await input.adapter.contextUsage?.().catch(() => undefined);
@@ -1155,7 +1294,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,
@@ -1164,7 +1303,7 @@ export function buildStartCommand() {
             await input.adapter.close().catch(() => { });
             return decorateQa(transfer.successor, qaCwd, undefined, input.next);
         };
-        const qaSessionBoundary = async (adapter, frozenAction, strategy, qaCwd) => {
+        const qaSessionBoundary = async (adapter, frozenAction, strategy, qaCwd, recovery) => {
             if (!activeContinuityRunId)
                 throw new Error("QA session boundary requires an active durable run");
             const qaSettings = resolvedContinuitySettings("qa");
@@ -1183,13 +1322,13 @@ export function buildStartCommand() {
                 }),
                 report: (event) => {
                     currentActivity()?.update(event.kind, event.detail, { provider: qaSettings.make, model: qaSettings.model });
-                    log.write("context-lifecycle", { role: "qa", ...event, sample: event.sample });
                 },
                 handoff: async ({ reason, adapter: predecessor, sample, settings, compactionCount }) => {
                     const nativeUsage = await predecessor.sessionUsage?.().catch(() => undefined);
                     const transfer = await new HandoffService(cwd).transfer({
                         runId: activeContinuityRunId, role: "qa", reason, predecessorSessionId: predecessor.sessionId(), predecessorSessionRef: predecessor.sessionRef?.(),
-                        roleState: { frozenActionDigest: createHash("sha256").update(frozenAction).digest("hex"), contextSample: sample },
+                        roleState: { frozenActionDigest: createHash("sha256").update(frozenAction).digest("hex"), contextSample: sample,
+                            ...(recovery ? { recoveryPacketDigest: recovery.packetDigest, reviewedStateDigest: recovery.reviewedStateDigest } : {}) },
                         ...(nativeUsage ? { sessionUsage: {
                                 version: 1, runId: activeContinuityRunId, role: "qa", provider: predecessor.agent,
                                 providerSessionId: predecessor.sessionId(), observedAt: nativeUsage.observedAt, source: nativeUsage.source,
@@ -1197,8 +1336,11 @@ export function buildStartCommand() {
                                 cumulativeTotalTokens: nativeUsage.totalTokens, authoritativeCostUsd: nativeUsage.authoritativeCostUsd,
                             } } : {}),
                         compactionCount, compactMaximum: settings.compact_maximum ?? 10,
-                        resources: [{ label: "frozen-qa-action", content: frozenAction, authoritative: true }],
-                    }, () => createQaForSettings(qaCwd, settings));
+                        resources: [{ label: "frozen-qa-action", content: frozenAction, authoritative: true }, ...(recovery ? [
+                                { label: "qa-recovery-packet", digest: recovery.packetDigest, authoritative: true, requiredForRecovery: true, mediaType: "application/vnd.rafi.qa-recovery+json", path: recovery.packetPath },
+                                { label: "qa-reviewed-state", digest: recovery.reviewedStateDigest, authoritative: true, requiredForRecovery: true, mediaType: "application/vnd.rafi.reviewed-state", path: "reviewed-state/" },
+                            ] : [])],
+                    }, (_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 +1361,8 @@ 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, () => activeObserver);
+        const qaReportRecovery = createQaReportRecoveryHandler(!process.stdin.isTTY || !process.stdout.isTTY, () => activeObserver);
         if (branchMode) {
             const ticketsConfig = loadTicketsConfig(cwd);
             const allowedBaseDirtyPaths = generatedTrackerDirtyPaths(ticketsConfig.paths);
@@ -1408,14 +1551,14 @@ export function buildStartCommand() {
                 console.log(`  ! ${issue.ticket ?? "plan"}: ${issue.message}`);
             }
             console.log();
-            if (!opts.yes && plan.issues.every((issue) => !issue.blocking)) {
-                const action = await select({
+            if (!autoApprovePlanUpdates && plan.issues.every((issue) => !issue.blocking)) {
+                const action = await withObservedUserWait(activeObserver, "branch plan approval", () => select({
                     message: branchPresentation.prompt,
                     options: [
                         { value: "proceed", label: "Proceed" },
                         { value: "cancel", label: "Cancel" },
                     ],
-                });
+                }));
                 if (isCancel(action) || action === "cancel") {
                     console.log("ai-foreman: cancelled");
                     process.exit(0);
@@ -1455,11 +1598,15 @@ export function buildStartCommand() {
             };
             const firstResumeRef = plan.nodes[0] ? resumeSessionByTicket.get(plan.nodes[0].ticket.id)?.sessionRef : undefined;
             let masterRun = recoveryRecord ? resumeBuildRun(cwd, recoveryRecord.runId, { builder: capturedBranchBuilder, qa: capturedBranchQa, builderSessionId: firstResumeRef?.sessionId ?? null, builderSessionRef: firstResumeRef ?? null }) : createBuildRun({
+                runId: invocationRunId,
                 tickets: plan.nodes.map((node) => node.ticket.id), deliveryUnit: selectedStacks.length ? selectedStacks.map((stack) => stack.id).join(",") : deliveryRun?.unit.id,
                 repositoryRoot: cwd, branchMode: branchPresentation.allocationMode, baseRef: plan.baseRef, builder: capturedBranchBuilder, qa: capturedBranchQa,
+                frozenPolicy, autonomyProfile, qaEnabled,
                 runDecisions: { workMode: "branch-per-ticket", workModeSource, branchPrefix, branchPrefixSource: resolvedPrefix.source, autoCompactThresholdPercent: capturedBranchBuilder.auto_compact_threshold_percent ?? 50, thresholdSource: thresholdOverride === undefined ? "project" : "cli" },
             });
             activeContinuityRunId = masterRun.runId;
+            const qaResumedRecovery = recoveryRecord ? pendingQaRecoveryPacket(cwd, masterRun.runId) : undefined;
+            activeObserver?.store.attachExecutionLease(activeObserver.executionId, readCurrentWorkflowLease(cwd)?.generation);
             const branchContextControllers = new Map();
             const branchContextController = (worktreePath) => {
                 const existing = branchContextControllers.get(worktreePath);
@@ -1475,7 +1622,7 @@ export function buildStartCommand() {
                         adapter: active, settingsRevision: settings.settings_revision, displaySessionCost: settings.display_session_cost,
                         sessionTransition: "adopted live settings",
                     }),
-                    report: (event) => { currentActivity()?.update(event.kind, event.detail, { provider: capturedBranchBuilder.make, model: capturedBranchBuilder.model }); log.write("context-lifecycle", { worktreePath, ...event, sample: event.sample }); },
+                    report: (event) => { currentActivity()?.update(event.kind, event.detail, { provider: capturedBranchBuilder.make, model: capturedBranchBuilder.model }); },
                     handoff: async ({ reason, adapter, sample, settings, compactionCount, frozenAction }) => {
                         const nativeUsage = await adapter.sessionUsage?.().catch(() => undefined);
                         const transfer = await new HandoffService(cwd).transfer({
@@ -1484,7 +1631,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 +1647,109 @@ 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,
+                    qaRuntimeContext: capturedBranchQa,
+                    qaContinuityManaged: true,
+                    qaReportRecovery,
+                    qaResumedRecovery,
+                    qaMaxFixAttempts: frozenPolicy.limits.builderQaFixesPerTicket,
+                    observer: activeObserver,
+                    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);
+                            activeObserver?.store.updateCurrentState({ runId: masterRun.runId, role: "builder", stream: "builder", executionId: activeObserver.executionId, ticketId: masterRun.currentTicket, providerSessionId: snapshot.contextSample.providerSessionId, phase: "builder ticket session", lastSignalAt: snapshot.contextSample.observedAt });
+                            if (snapshot.contextSample.used !== undefined)
+                                activeObserver?.store.recordMetric({ runId: masterRun.runId, executionId: activeObserver.executionId, role: "builder", stream: "builder", providerSessionId: snapshot.contextSample.providerSessionId }, "context_used_tokens", snapshot.contextSample.used, { unit: "tokens" });
+                        });
+                        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,9 +1787,18 @@ 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");
+            activeObserver?.finish(masterRun.status, observationSummaryMetadata(cwd, masterRun, qaEnabled, capturedBranchBuilder.make, summaries.find(row => row.pr?.url)));
+            observabilityStore?.closeLogFile(logPath, masterRun.status);
+            observabilityStore?.enforceLimits();
+            observabilityStore?.maintainLogs(cwd);
+            observabilityStore?.close();
+            pruneRecoveryTelemetryAtCompletion(cwd, config.observability.detail_retention_days);
+            activeObserver = undefined;
+            process.off("exit", finishObservationOnExit);
             console.log("foreman: branch run summary");
             console.log("ticket\tbranch\tbase\tstatus\tcommit\tpush\tcompletion");
             for (const row of summaries) {
@@ -1651,6 +1823,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, {
@@ -1692,10 +1865,14 @@ export function buildStartCommand() {
         };
         const capturedQa = { role: "qa", source: roleDefaults.qa ? "project" : "provider", make: qaAgent, model: qaModel ?? "default", reasoning: qaEffort ?? "default", fast: qaFast, session_strategy: roleDefaults.qa?.session_strategy ?? "compact", display_session_cost: sessionCostOverride ?? roleDefaults.qa?.display_session_cost ?? false, auto_compact_threshold_percent: roleDefaults.qa?.auto_compact_threshold_percent ?? 50, compact_maximum: roleDefaults.qa?.compact_maximum ?? 10, settings_revision: settingsRevision };
         let buildRun = recoveryRecord ? resumeBuildRun(cwd, recoveryRecord.runId, { builder: capturedBuilder, qa: capturedQa, builderSessionId: resumeSessionId ?? null, builderSessionRef: resumeSessionRef ?? null }) : createBuildRun({
+            runId: invocationRunId,
             tickets: [], repositoryRoot: cwd, branchMode: "current", baseRef: opts.base ?? loadTicketSetupConfig(cwd)?.build.base_branch, builder: capturedBuilder, qa: capturedQa,
+            frozenPolicy, autonomyProfile, qaEnabled,
             runDecisions: { workMode: "current", workModeSource, branchPrefix, branchPrefixSource: resolvedPrefix.source, autoCompactThresholdPercent: capturedBuilder.auto_compact_threshold_percent ?? 50, thresholdSource: thresholdOverride === undefined ? "project" : "cli" },
         });
+        activeObserver?.store.attachExecutionLease(activeObserver.executionId, readCurrentWorkflowLease(cwd)?.generation);
         activeContinuityRunId = buildRun.runId;
+        const qaResumedRecovery = recoveryRecord ? pendingQaRecoveryPacket(cwd, buildRun.runId) : undefined;
         const heartbeat = setInterval(() => { buildRun = heartbeatBuildRun(cwd, buildRun); }, 10_000);
         heartbeat.unref();
         const checkpointSignal = () => {
@@ -1739,7 +1916,6 @@ export function buildStartCommand() {
             }),
             report: (event) => {
                 currentActivity()?.update(event.kind, event.detail, { provider: capturedBuilder.make, model: capturedBuilder.model });
-                log.write("context-lifecycle", { ...event, sample: event.sample });
             },
             handoff: async ({ reason, adapter, sample, settings, compactionCount, frozenAction }) => {
                 const nativeUsage = await adapter.sessionUsage?.().catch(() => undefined);
@@ -1759,7 +1935,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 +1945,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, frozenPolicy.limits.builderQaFixesPerTicket, 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); }, activeObserver, capturedQa, true, qaReportRecovery, qaResumedRecovery);
         activeBuilderForStatus = () => foreman.builderAdapter();
         const statusReporter = liveStatusReporter = new AgentStatusReporter({
             runId: buildRun.runId,
@@ -1796,17 +1972,9 @@ export function buildStartCommand() {
                 activity.setAgentStatus(line.replace(/^\[[^\]]+\]\s*/, ""));
             else
                 console.log(line);
-            log.write("agent-status", { ...snapshot });
-            const db = new WorkflowDb(cwd);
-            try {
-                db.recordTelemetry(buildRun.runId, snapshot);
-                db.recordContextSample(snapshot.contextSample);
-                if (snapshot.sessionUsage)
-                    db.recordSessionUsage(snapshot.sessionUsage);
-            }
-            finally {
-                db.close();
-            }
+            activeObserver?.store.updateCurrentState({ runId: buildRun.runId, role: "builder", stream: "builder", executionId: activeObserver.executionId, ticketId: buildRun.currentTicket, providerSessionId: snapshot.contextSample.providerSessionId, phase: "builder work session", lastSignalAt: snapshot.contextSample.observedAt });
+            if (snapshot.contextSample.used !== undefined)
+                activeObserver?.store.recordMetric({ runId: buildRun.runId, executionId: activeObserver.executionId, role: "builder", stream: "builder", providerSessionId: snapshot.contextSample.providerSessionId }, "context_used_tokens", snapshot.contextSample.used, { unit: "tokens" });
         });
         statusReporter.start();
         const modifiers = [
@@ -1824,23 +1992,24 @@ export function buildStartCommand() {
         try {
             console.log("ai-foreman: asking builder to plan the next tickets or steps...\n");
             buildRun = checkpointBuildRun(cwd, buildRun, "before-preflight");
-            await foreman.runPreflight(steps, ticketsContent, preferredTicket);
+            await (activeObserver ? activeObserver.span("preflight", "Builder preflight", () => foreman.runPreflight(steps, ticketsContent, preferredTicket)) : 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({
+                    const action = await withObservedUserWait(activeObserver, "build plan decision", () => select({
                         message: "How does this plan look?",
                         options: [
                             { value: "proceed", label: "Proceed — start implementing" },
                             { value: "feedback", label: "Give feedback — revise the plan" },
                             { value: "cancel", label: "Cancel" },
                         ],
-                    });
+                    }));
                     if (isCancel(action) || action === "cancel") {
                         console.log("ai-foreman: cancelled");
                         statusReporter.stop();
@@ -1852,10 +2021,10 @@ export function buildStartCommand() {
                         console.log();
                         break;
                     }
-                    const fb = await text({
+                    const fb = await withObservedUserWait(activeObserver, "build plan feedback", () => text({
                         message: "Your feedback:",
                         validate: (v) => (v?.trim() ? undefined : "Please enter some feedback"),
-                    });
+                    }));
                     if (isCancel(fb)) {
                         console.log("ai-foreman: cancelled");
                         statusReporter.stop();
@@ -1867,7 +2036,7 @@ export function buildStartCommand() {
                     await foreman.sendPreflightFeedback(String(fb));
                 }
             }
-            const result = await foreman.runBatch(steps, trackerRelPath, (ticketId) => {
+            const result = await (activeObserver ? activeObserver.span("builder_work", "Builder and QA batch", () => foreman.runBatch(steps, trackerRelPath, (ticketId) => {
                 const tickets = buildRun.tickets.includes(ticketId)
                     ? buildRun.tickets
                     : [...buildRun.tickets, ticketId];
@@ -1875,7 +2044,10 @@ export function buildStartCommand() {
                     tickets,
                     currentTicket: ticketId,
                 });
-            }, preferredTicket);
+            }, preferredTicket)) : foreman.runBatch(steps, trackerRelPath, (ticketId) => {
+                const tickets = buildRun.tickets.includes(ticketId) ? buildRun.tickets : [...buildRun.tickets, ticketId];
+                buildRun = checkpointBuildRun(cwd, buildRun, "ticket-selected", { tickets, currentTicket: ticketId });
+            }, preferredTicket));
             if (pendingHandoffGeneration !== undefined)
                 throw new Error(`recovery handoff generation ${pendingHandoffGeneration} for ${pendingHandoffRole} was not accepted; recovery mode was not substituted`);
             if (foreman.builderSessionId())
@@ -1889,6 +2061,14 @@ export function buildStartCommand() {
             statusReporter.stop();
             await foreman.close();
             await viewer;
+            activeObserver?.finish(buildRun.status, observationSummaryMetadata(cwd, buildRun, qaEnabled, capturedBuilder.make));
+            observabilityStore?.closeLogFile(logPath, buildRun.status);
+            observabilityStore?.enforceLimits();
+            observabilityStore?.maintainLogs(cwd);
+            observabilityStore?.close();
+            pruneRecoveryTelemetryAtCompletion(cwd, config.observability.detail_retention_days);
+            activeObserver = undefined;
+            process.off("exit", finishObservationOnExit);
             console.log(`\nforeman: ${result.completed}/${result.requested} step(s) completed`);
             console.log(`foreman: outcome — ${result.outcome}`);
             if (result.detail)
@@ -1902,7 +2082,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 +2115,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", {
@@ -1953,6 +2146,74 @@ export function buildStartCommand() {
         }
     });
 }
+function withObservedUserWait(observer, label, operation) {
+    return observer ? observer.span("user_wait", label, operation) : operation();
+}
+function ticketSizeBucket(projectDir, ticketIds) {
+    if (!ticketIds.length || !isTicketsInitialized(projectDir))
+        return undefined;
+    try {
+        const paths = resolveTicketPaths(loadTicketsConfig(projectDir), projectDir);
+        const ranks = new Map([["XS", 0], ["S", 1], ["M", 2], ["L", 3], ["XL", 4]]);
+        return loadTickets(paths.tickets).filter(ticket => ticketIds.includes(ticket.id))
+            .sort((left, right) => (ranks.get(right.size) ?? -1) - (ranks.get(left.size) ?? -1))[0]?.size;
+    }
+    catch {
+        return undefined;
+    }
+}
+function observationSummaryMetadata(projectDir, run, qaEnabled, provider, reviewRun) {
+    const worktree = run.repository.worktree;
+    const terminalHead = reviewRun?.commit ?? diagnosticGit(worktree, ["rev-parse", "HEAD"]);
+    const base = run.repository.git.baselineHead ?? run.repository.baseHead;
+    const commitCount = base ? Number(diagnosticGit(worktree, ["rev-list", "--count", `${base}..HEAD`])) : undefined;
+    const status = diagnosticGit(worktree, ["status", "--porcelain=v1"]);
+    const numstat = base ? diagnosticGit(worktree, ["diff", "--numstat", `${base}..HEAD`]) : undefined;
+    let additions = 0;
+    let deletions = 0;
+    for (const line of numstat?.split("\n").filter(Boolean) ?? []) {
+        const [added, deleted] = line.split("\t");
+        if (/^\d+$/.test(added ?? ""))
+            additions += Number(added);
+        if (/^\d+$/.test(deleted ?? ""))
+            deletions += Number(deleted);
+    }
+    const receipt = Object.entries(run.receipts).find(([key, value]) => /(?:pull|merge|pr|mr)/i.test(`${key} ${value.externalId ?? ""}`));
+    const review = reviewRun?.pr;
+    const reviewId = review?.url?.match(/\/(?:pull|merge_requests)\/(\d+)(?:\D|$)/)?.[1] ?? receipt?.[1].externalId;
+    return {
+        branchMode: run.branchMode, qaEnabled, primaryProvider: provider, model: run.builder?.settings.model,
+        ticketCount: run.tickets.length, ticketIds: run.tickets, deliveryUnit: run.deliveryUnit, checkpoint: run.checkpoint,
+        failureCategory: run.failure?.category ?? run.interruption?.category, ticketSizeBucket: ticketSizeBucket(projectDir, run.tickets),
+        createdAt: run.createdAt, updatedAt: run.updatedAt, completedAt: run.completedAt,
+        git: { branch: reviewRun?.branch ?? run.repository.git.branch ?? run.repository.branch, terminalHead, ...(Number.isFinite(commitCount) ? { commitCount } : {}),
+            changedPathCount: status?.split("\n").filter(Boolean).length, ...(numstat !== undefined ? { additions, deletions } : {}),
+            ...(reviewId ? { pullRequest: { provider: /merge_requests\//.test(review?.url ?? "") || /mr|gitlab/i.test(receipt?.[0] ?? "") ? "gitlab" : "github", id: reviewId, state: review?.status, url: review?.url } } : {}),
+            observedAt: new Date().toISOString(), historical: true },
+    };
+}
+function diagnosticGit(cwd, args) {
+    try {
+        return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5_000, maxBuffer: 1024 * 1024 }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+function pruneRecoveryTelemetryAtCompletion(projectDir, retentionDays) {
+    try {
+        const db = new WorkflowDb(projectDir);
+        try {
+            db.pruneTerminalTelemetry(retentionDays);
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch (error) {
+        console.error(`rafi: recovery telemetry maintenance skipped: ${String(error).replace(/\s+/g, " ").slice(0, 300)}`);
+    }
+}
 async function prepareNativeAutoCompaction(adapter) {
     if (!adapter.prepareAutoCompaction) {
         await adapter.close().catch(() => { });
@@ -1971,25 +2232,25 @@ async function prepareNativeAutoCompaction(adapter) {
         throw error;
     }
 }
-function createQaNonconvergenceHandler(projectDir, noninteractive, planner) {
+function createQaNonconvergenceHandler(projectDir, noninteractive, planner, observer) {
     return async (context) => {
         if (noninteractive || !process.stdin.isTTY || !process.stdout.isTTY)
             return { action: "pause" };
         while (true) {
-            const choice = await select({ message: `QA did not converge for ${context.ticket.id}. What next?`, options: [
+            const choice = await withObservedUserWait(observer?.(), "QA nonconvergence decision", () => select({ message: `QA did not converge for ${context.ticket.id}. What next?`, options: [
                     { value: "retry", label: "Retry another Builder fix" },
                     { value: "pause", label: "Pause at this checkpoint" },
                     { value: "waive", label: "Explicitly waive QA" },
                     { value: "planner", label: "Discuss with read-only Planner" },
-                ] });
+                ] }));
             if (isCancel(choice) || choice === "pause")
                 return { action: "pause" };
             if (choice === "retry")
                 return { action: "retry" };
             if (choice === "waive") {
-                const approved = await select({ message: "Waive QA and record validation_result=failed with all unresolved issues?", options: [
+                const approved = await withObservedUserWait(observer?.(), "QA waiver confirmation", () => select({ message: "Waive QA and record validation_result=failed with all unresolved issues?", options: [
                         { value: "no", label: "No (Recommended)" }, { value: "yes", label: "Yes, waive and continue" },
-                    ] });
+                    ] }));
                 if (approved === "yes") {
                     const db = new WorkflowDb(projectDir);
                     try {
@@ -2008,18 +2269,26 @@ function createQaNonconvergenceHandler(projectDir, noninteractive, planner) {
                 }
                 continue;
             }
-            const discussion = await text({ message: "What should the Planner focus on?", defaultValue: "Explain the QA failures and propose the safest concrete remediation." });
+            const discussion = await withObservedUserWait(observer?.(), "QA remediation guidance", () => text({ message: "What should the Planner focus on?", defaultValue: "Explain the QA failures and propose the safest concrete remediation." }));
             if (isCancel(discussion))
                 continue;
-            const diff = execFileSync("git", ["-C", context.builderWorktree, "diff", "--binary", "HEAD"], { encoding: "utf8", maxBuffer: 128 * 1024 * 1024 });
+            const rawDiff = execFileSync("git", ["-C", context.builderWorktree, "diff", "--binary", "HEAD"], { encoding: "buffer", maxBuffer: 128 * 1024 * 1024 });
+            const diffLimit = 128 * 1024;
+            const diffTruncated = rawDiff.length > diffLimit;
+            const diff = rawDiff.subarray(0, diffLimit).toString("utf8");
+            const changeSummary = execFileSync("git", ["-C", context.builderWorktree, "status", "--short", "--untracked-files=all"], { encoding: "utf8" }).split("\n").filter(Boolean).sort().join("\n");
+            const untracked = execFileSync("git", ["-C", context.builderWorktree, "ls-files", "--others", "--exclude-standard"], { encoding: "utf8" }).split("\n").filter(Boolean).sort();
             let instruction = [
                 "You are the read-only Planner mediating QA nonconvergence. Do not edit files or run mutating tools.",
                 `Ticket: ${context.ticket.id} — ${context.ticket.title}`,
                 `Requirements: ${context.ticket.acceptance.join("; ")}`,
                 `Required tests: ${context.ticket.required_tests.join("; ")}`,
+                `Builder worktree: ${context.builderWorktree}`,
+                `Deterministic change summary:\n${changeSummary || "(clean)"}`,
+                `Untracked-file inventory:\n${untracked.join("\n") || "(none)"}`,
                 `User discussion: ${String(discussion)}`,
                 `Complete QA history:\n${JSON.stringify(context.history, null, 2)}`,
-                `Full Builder diff:\n${diff || "(no tracked diff)"}`,
+                `${diffTruncated ? "Builder diff (TRUNCATED at 128 KiB; inspect the actual worktree before relying on it)" : "Full Builder diff"}:\n${diff || "(no tracked diff)"}`,
                 "Return RAFI_QA_REMEDIATION_START, then one JSON object {\"summary\":\"...\",\"fix_instructions\":[\"...\"]}, then RAFI_QA_REMEDIATION_END.",
                 "End with STEP_STATUS: plan_complete | summary=\"QA remediation proposed\"",
             ].join("\n\n");
@@ -2040,14 +2309,14 @@ function createQaNonconvergenceHandler(projectDir, noninteractive, planner) {
                 if (!proposal.summary || !Array.isArray(proposal.fix_instructions) || !proposal.fix_instructions.every((item) => typeof item === "string"))
                     throw new Error("Planner remediation proposal is malformed");
                 console.log(`\nPlanner remediation: ${proposal.summary}\n${proposal.fix_instructions.map((item) => `- ${item}`).join("\n")}`);
-                const decision = await select({ message: "Use this remediation for a new Builder fix session?", options: [
+                const decision = await withObservedUserWait(observer?.(), "QA remediation approval", () => select({ message: "Use this remediation for a new Builder fix session?", options: [
                         { value: "approve", label: "Approve (Recommended)" }, { value: "revise", label: "Discuss/revise" }, { value: "cancel", label: "Cancel and return to choices" },
-                    ] });
+                    ] }));
                 if (decision === "approve")
                     return { action: "remediate", remediation: [proposal.summary, ...proposal.fix_instructions].join("\n") };
                 if (isCancel(decision) || decision === "cancel")
                     break;
-                const feedback = await text({ message: "Planner revision feedback:" });
+                const feedback = await withObservedUserWait(observer?.(), "QA Planner revision feedback", () => text({ message: "Planner revision feedback:" }));
                 if (isCancel(feedback))
                     break;
                 resumeSessionId = run.sessionId;
@@ -2056,6 +2325,41 @@ function createQaNonconvergenceHandler(projectDir, noninteractive, planner) {
         }
     };
 }
+function createQaReportRecoveryHandler(noninteractive, observer) {
+    return async ({ packet, originalIssues, liveSession, contextUsage }) => {
+        if (noninteractive || !process.stdin.isTTY || !process.stdout.isTTY) {
+            console.error(`foreman: QA report recovery requires input; saved packet ${packet.directory}`);
+            console.error(`foreman: resume with the run ID recorded in ${join(packet.directory, "manifest.json")}`);
+            return { action: "pause" };
+        }
+        const choice = await withObservedUserWait(observer?.(), "QA report recovery decision", () => select({
+            message: "QA report recovery:",
+            options: [
+                { value: "fresh", label: "Try another fresh QA." },
+                { value: "plain", label: "Use plain issues fallback.", hint: originalIssues ? originalIssues.slice(0, 120) : "Unavailable: original issues synopsis was empty" },
+                { value: "manual", label: "Manually fix saved JSON.", hint: join(packet.directory, "report.json") },
+                { value: "guidance", label: "Give QA specific instructions." },
+                { value: "pause", label: "Pause." },
+            ],
+        }));
+        if (isCancel(choice) || choice === "pause")
+            return { action: "pause" };
+        if (choice === "fresh")
+            return { action: "fresh" };
+        if (choice === "plain")
+            return { action: "plain" };
+        if (choice === "manual")
+            return { action: "manual" };
+        console.log(`foreman: current QA context usage: ${JSON.stringify(contextUsage).slice(0, 500)}`);
+        const guidance = await withObservedUserWait(observer?.(), "QA recovery guidance", () => text({ message: "Specific QA report-recovery instructions:" }));
+        if (isCancel(guidance) || !String(guidance).trim())
+            return { action: "pause" };
+        const route = await withObservedUserWait(observer?.(), "QA recovery session choice", () => select({ message: "Use which QA session route?", options: liveSession ? [
+                { value: "current", label: "Current session" }, { value: "compact", label: "Compact current session" }, { value: "fresh", label: "Fresh validated handoff" },
+            ] : [{ value: "fresh", label: "Fresh validated handoff (resumed recovery)" }] }));
+        return isCancel(route) ? { action: "pause" } : { action: "guidance", instructions: String(guidance), route };
+    };
+}
 function readAgentDefaults(projectDir) {
     const path = join(projectDir, "rafi-config.yaml");
     if (!existsSync(path))