ai-foreman 1.7.26 → 1.7.28

package/dist/cli/start.js

@@ -31,8 +31,9 @@ import { loadRoleBundle } from "../roles.js";
 import { ensureBuildRuntimeReadyForCommand } from "./runtimeAuthPrompt.js";
 import { resolveAgentForProject } from "./runtimeSelection.js";
 import { isTicketsInitialized, loadTicketsConfig, resolveTicketPaths } from "../tickets/config.js";
-import { loadTickets } from "../tickets/ticketLoader.js";
+import { hasRollbackOrMitigationPlan, loadTickets } from "../tickets/ticketLoader.js";
 import { StateDb } from "../tickets/stateDb.js";
+import { ticketDefinitionDigest } from "../tickets/riskWaivers.js";
 import { applySharedDeliveryBranch, applySizeBranchPolicy, buildBranchAuditInstruction, buildBranchPlan, parseAuditDependencies } from "../branch/planner.js";
 import { currentGitRef, ensureCleanBaseWorktree, generatedTrackerDirtyPaths } from "../branch/git.js";
 import { captureDirtyBaseline } from "../branch/dirtyBaseline.js";
@@ -40,7 +41,8 @@ import { formatGitHubFailure, preflightGh } from "../branch/github.js";
 import { preflightGlab } from "../branch/gitlab.js";
 import { readDeliveryUnitSession, runBranchPlan } from "../branch/runner.js";
 import { branchPlanLogMetadata, presentBranchPlan } from "../branch/presentation.js";
-import { buildRunSessionBinding, checkpointBuildRun, completeBuildRun, createBuildRun, currentBranchRecoveryTicket, currentBranchTicketProgress, recoveryExecutionTickets, finishRecoveredTicketScope, heartbeatBuildRun, persistBuildSession, persistCurrentBuildSession, projectBuildRecovery, readBuildRuns, releaseBuildLease, resumeBuildRun } from "../buildRuns.js";
+import { branchTicketScopeProgress, buildRunSessionBinding, checkpointBuildRun, completeBuildRun, createBuildRun, currentBranchRecoveryTicket, currentBranchTicketProgress, recoveryExecutionTickets, finishBranchTicketScope, finishRecoveredTicketScope, heartbeatBuildRun, persistBuildSession, persistCurrentBuildSession, projectBuildRecovery, readBuildRuns, releaseBuildLease, resumeBuildRun } from "../buildRuns.js";
+import { parseProviderContract, qaRemediationProposalV1Schema } from "rafi-spec";
 import { parse as parseYaml } from "yaml";
 import { findResumableBranchSessions, formatBranchContinueCommand, formatBranchSummaryFollowupCommands, } from "../branch/resume.js";
 import { detectGitProvider, loadTicketSetupConfig } from "../tickets/setupConfig.js";
@@ -51,6 +53,8 @@ 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";
+import { globallyEligibleTickets } from "../tickets/eligibility.js";
+import { cmdValidate } from "../tickets/commands.js";
 import { BUILTIN_BRANCH_PREFIX, validateBranchPrefix } from "../branch/prefix.js";
 import { captureCurrentWorkflowSessionIdentity, CurrentWorkflowChangedError, CurrentWorkflowGuardAdapter } from "../branch/currentGuard.js";
 import { ContinuityAdapter, ContinuityRecoveryRequiredError, SessionUnavailableContinuityError } from "../continuity.js";
@@ -61,7 +65,7 @@ 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, recoverPendingQaRecoveryPublications } from "../qaRecovery.js";
+import { canonicalizeQaRecoveryRequirements, loadQaRecoveryPacket, recoverPendingQaRecoveryPublications } from "../qaRecovery.js";
 import { qaDigest } from "../qaProtocolV2.js";
 import { acceptQaRuntimeHandoff, describeQaRuntimeHandle, frozenQaRuntimeSettings } from "../qaRuntime.js";
 const FOREMAN_VERSION = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
@@ -79,7 +83,7 @@ function pendingQaRecoveryPacket(projectDir, runId, ticketId) {
         const selected = ticketId ? pending.find((item) => item.ticketId === ticketId) : pending[0];
         if (!selected || selected.pendingAction === "resolved")
             return undefined;
-        const packet = loadQaRecoveryPacket(selected.packetPath);
+        const packet = canonicalizeQaRecoveryRequirements(loadQaRecoveryPacket(selected.packetPath));
         const state = db.qaRecoveryHead(runId, packet.manifest.ticketId);
         if (!state || packet.manifest.packetDigest !== state.packetDigest || packet.manifest.runId !== runId
             || packet.manifest.ticketId !== state.ticketId || packet.manifest.packetId !== state.packetId
@@ -422,6 +426,71 @@ export function validateStartOptions(opts, requireCount) {
         throw new Error("Preparation launch requires both run and token");
     if (opts.launchToken && !opts.preparationRun && !opts.recoverRun)
         throw new Error("Launch token requires a preparation or recovery run");
+    if (opts.auditLogging !== undefined && !["off", "summary", "trace"].includes(String(opts.auditLogging)))
+        throw new Error("--audit-logging must be off, summary, or trace");
+}
+export function resolveAuditLoggingMode(cli, configured, environment = process.env.RAFI_AUDIT_LOGGING) {
+    const value = cli ?? configured ?? environment ?? "summary";
+    if (!["off", "summary", "trace"].includes(String(value)))
+        throw new Error("audit logging must be off, summary, or trace");
+    return String(value);
+}
+function configuredAuditLoggingMode(path) {
+    if (!existsSync(path))
+        return undefined;
+    const raw = parseYaml(readFileSync(path, "utf8"));
+    return raw?.observability?.mode === undefined ? undefined : resolveAuditLoggingMode(undefined, raw.observability.mode, undefined);
+}
+/** A current waiver is an already-recorded decision: surface it, never demand a second start-time approval. */
+function warnRiskPlanWaivers(projectDir, ticketIds) {
+    if (!ticketIds.length || !isTicketsInitialized(projectDir))
+        return;
+    const paths = resolveTicketPaths(loadTicketsConfig(projectDir), projectDir);
+    const definitions = new Map(loadTickets(paths.tickets).map((ticket) => [ticket.id, ticket]));
+    const db = new StateDb(paths.stateDb, { readOnly: true });
+    try {
+        const waived = ticketIds.filter((id) => {
+            const ticket = definitions.get(id);
+            return ticket && ticket.risk !== "Low" && !hasRollbackOrMitigationPlan(ticket.rollback)
+                && Boolean(db.getTicketRiskWaiver(id, ticketDefinitionDigest(ticket)));
+        });
+        if (waived.length)
+            console.warn(`foreman: warning: ${waived.join(", ")} have explicitly waived missing rollback or mitigation plans.`);
+    }
+    finally {
+        db.close();
+    }
+}
+/** Preserve the distinction between a staged handoff and an unattempted acceptance. */
+export function recordHandoffAcceptanceNotAttempted(projectDir, runId, role, generation, stage, detail) {
+    const db = new WorkflowDb(projectDir);
+    try {
+        db.appendContinuityEvent({
+            runId,
+            role: "host",
+            kind: "handoff_acceptance_not_attempted",
+            payload: { generation, role, stage, detail },
+            authoritativeStateRevision: db.continuityHead(runId, role)?.authoritativeStateRevision ?? 0,
+        });
+    }
+    finally {
+        db.close();
+    }
+}
+/** Default start selection is deliberately the same eligibility model users see in the ticket queue. */
+export function selectDefaultExecutionTickets(tickets, states, implementationLimit, steps, delivery) {
+    return globallyEligibleTickets({ tickets, states, implementationLimit, delivery }).slice(0, steps).map((ticket) => ticket.id);
+}
+/** Fail before runtime/provider admission when canonical ticket data is unsafe. */
+export function assertStartTicketPreflight(projectDir) {
+    const validation = cmdValidate(projectDir);
+    const errors = validation.issues.filter((issue) => issue.severity === "error");
+    const warnings = validation.issues.filter((issue) => issue.severity === "warn");
+    for (const issue of warnings)
+        console.warn(`foreman: warning: ${issue.message}`);
+    if (errors.length) {
+        throw new Error(`ticket validation must be resolved before starting:\n${errors.map((issue) => `- ${issue.message}`).join("\n")}\nRun \`rafi tickets validate\` after repair to confirm readiness.`);
+    }
 }
 /** Validate generated established recovery before reserving execution authority. */
 export function validateRecoveryArguments(args, projectDir) {
@@ -490,6 +559,7 @@ export function buildStartCommand(options = {}) {
         .option("--base <ref>", "base ref for root ticket branches (default: current branch or HEAD)")
         .option("--branch-prefix <prefix>", "branch name prefix for ticket branches")
         .option("--show-session-cost", "show authoritative cost or trustworthy cumulative session tokens for Builder and QA")
+        .option("--audit-logging <mode>", "host-owned audit logging (off | summary | trace)", "summary")
         .option("--hide-session-cost", "hide session cost/token usage for Builder and QA")
         .option("--auto-compact-threshold <percent>", "initial Builder context compaction threshold (1-99)")
         .option("--max-branch-depth <n>", "maximum selected branch stack depth", "5")
@@ -566,6 +636,17 @@ export function buildStartCommand(options = {}) {
         let dirtyWork = recoveryRecord?.runDecisions?.dirtyWork;
         if (opts.recoverRun && !recoveryRecord)
             fail(`recoverable build run not found: ${opts.recoverRun}`);
+        // Both current-branch and branch delivery runs share this gate. A
+        // recovery resumes a previously admitted scope and is deliberately not
+        // reclassified by later tracker edits.
+        if (!recoveryRecord && isTicketsInitialized(cwd)) {
+            try {
+                assertStartTicketPreflight(cwd);
+            }
+            catch (err) {
+                fail(err instanceof Error ? err.message : String(err));
+            }
+        }
         const autonomyProfile = opts.autonomy;
         if (autonomyProfile && !["supervised", "balanced", "unattended"].includes(autonomyProfile))
             fail("--autonomy must be supervised, balanced, or unattended");
@@ -610,6 +691,7 @@ export function buildStartCommand(options = {}) {
             const readinessOwner = { project: cwd, runId: supervisedInvocationId, authority: localBuildAuthority(cwd) };
             const autoApprovePlanUpdates = recoveryRecord
                 ? recoveryRecord.recoveryDecision?.planUpdateApproval === "auto"
+                    && (recoveryRecord.recoveryDecision.planUpdateApprovalSource === "explicit-yes" || recoveryRecord.recoveryDecision.planUpdateApprovalSource === "explicit-choice")
                 : Boolean(opts.yes);
             if (opts.recoveryMode) {
                 const allowed = ["exact-session", "fresh-with-handoff", "fresh-recovery-only", "guided-recovery"];
@@ -756,7 +838,7 @@ export function buildStartCommand(options = {}) {
                 ? requestedTicketIds.length > 0
                     ? requestedTicketIds
                     : branchDefaults.branchMode && recoveryRecord
-                        ? [...recoveryRecord.tickets]
+                        ? branchTicketScopeProgress(cwd, recoveryRecord)?.remaining ?? [...recoveryRecord.tickets]
                         : recoveryRecord ? [currentBranchRecoveryTicket(cwd, recoveryRecord)].filter((ticket) => ticket !== undefined) : []
                 : [];
             if (recoveryRecord && continueTickets.some(ticket => !recoveryRecord.tickets.includes(ticket)))
@@ -868,6 +950,8 @@ export function buildStartCommand(options = {}) {
                 ? recoveryExecutionTickets(recoveryRecord, requestedTicketIds, Boolean(opts.recoveryMode))
                 : selectedNewTicket ? [selectedNewTicket] : undefined;
             const config = loadConfig(join(cwd, "foreman.yaml"));
+            const auditLogging = resolveAuditLoggingMode(command.getOptionValueSource("auditLogging") === "cli" ? opts.auditLogging : undefined, configuredAuditLoggingMode(join(cwd, "foreman.yaml")));
+            const observabilityConfig = { ...config.observability, mode: auditLogging, enabled: auditLogging !== "off" };
             const stamp = new Date().toISOString().replace(/[:.]/g, "-");
             const logPath = join(cwd, ".foreman", `${stamp}.jsonl`);
             const log = new Log(logPath);
@@ -882,9 +966,9 @@ export function buildStartCommand(options = {}) {
                 console.error(`rafi: warning: ${qaResolution.deprecationWarning}`);
             const invocationRunId = supervisedInvocationId;
             let observabilityStore;
-            if (config.observability.enabled) {
+            if (observabilityConfig.enabled) {
                 try {
-                    observabilityStore = new ObservabilityStore(cwd, { config: config.observability });
+                    observabilityStore = new ObservabilityStore(cwd, { config: observabilityConfig });
                 }
                 catch (error) {
                     console.error(`rafi: observability unavailable; build will continue: ${String(error).replace(/\s+/g, " ").slice(0, 300)}`);
@@ -1249,7 +1333,12 @@ export function buildStartCommand(options = {}) {
                 const recoveryMode = String(opts.recoveryMode ?? "");
                 const effectiveSessionId = recoveryMode && recoveryMode !== "exact-session" ? undefined : sessionId;
                 let adapter = await createRecoveringBuilder(builderCwd, effectiveSessionId, effectiveSessionId ? sessionRef : undefined);
-                if (pendingHandoffGeneration !== undefined && pendingHandoffRole === "builder" && activeContinuityRunId === recoveryRecord?.runId) {
+                // The persisted recovery record is the authority for the staged
+                // handoff's run. During QA-only recovery the active continuity ID is
+                // assigned later than adapter construction, so gating acceptance on
+                // that transient variable can silently skip the acceptance branch and
+                // leave the staged generation pending until the post-run guard fails.
+                if (pendingHandoffGeneration !== undefined && pendingHandoffRole === "builder" && recoveryRecord?.runId) {
                     const service = new HandoffService(cwd);
                     const staged = service.loadStaged(recoveryRecord.runId, pendingHandoffGeneration);
                     const accepted = await service.acceptStagedWithRecovery(staged, adapter, (_handoff, runtime) => createBuilderForSettings(builderCwd, settingsForRequestedRuntime(resolvedContinuitySettings("builder"), runtime)), handoffRecoveryOptions("builder"));
@@ -1566,10 +1655,26 @@ export function buildStartCommand(options = {}) {
                 // compatibility caller still supplies the previous raw ID.
                 const effectiveSessionId = undefined;
                 void sessionId;
-                let adapter = await createRecoveringQa(qaCwd, effectiveSessionId);
+                let adapter;
+                try {
+                    adapter = await createRecoveringQa(qaCwd, effectiveSessionId);
+                }
+                catch (error) {
+                    // A staged QA handoff is intentionally preserved when the successor
+                    // cannot reach a validated session (for example, host runtime
+                    // preparation fails). Record the exact pre-acceptance boundary so a
+                    // later recovery can distinguish "not attempted" from a rejected
+                    // acknowledgement without weakening the acceptance gate.
+                    if (pendingHandoffGeneration !== undefined && pendingHandoffRole === "qa" && recoveryRecord?.runId) {
+                        const detail = error instanceof Error ? error.message : String(error);
+                        recordHandoffAcceptanceNotAttempted(cwd, recoveryRecord.runId, "qa", pendingHandoffGeneration, "qa-runtime-preparation", detail);
+                        log.write("handoff-acceptance-not-attempted", { role: "qa", generation: pendingHandoffGeneration, stage: "qa-runtime-preparation", detail });
+                    }
+                    throw error;
+                }
                 let explicitRecoveryAccepted = false;
                 let handoffReceipt = { kind: "initial" };
-                if (pendingHandoffGeneration !== undefined && pendingHandoffRole === "qa" && activeContinuityRunId === recoveryRecord?.runId) {
+                if (pendingHandoffGeneration !== undefined && pendingHandoffRole === "qa" && recoveryRecord?.runId) {
                     const service = new HandoffService(cwd);
                     const staged = service.loadStaged(recoveryRecord.runId, pendingHandoffGeneration);
                     const accepted = await service.acceptStagedWithRecovery(staged, adapter, (_handoff, runtime) => createQaForSettings(qaCwd, settingsForRequestedRuntime(resolvedContinuitySettings("qa"), runtime)), handoffRecoveryOptions("qa"));
@@ -1716,7 +1821,7 @@ export function buildStartCommand(options = {}) {
                                     cumulativeTotalTokens: nativeUsage.totalTokens, authoritativeCostUsd: nativeUsage.authoritativeCostUsd,
                                 } } : {}),
                             compactionCount, compactMaximum: settings.compact_maximum ?? 10,
-                            resources: [{ label: "frozen-qa-action", content: frozenAction, authoritative: true, purpose: "Frozen QA action across the session boundary" }, ...(recovery ? recovery.resources.map((resource) => ({
+                            resources: [{ label: "frozen-qa-action", content: frozenAction, authoritative: true, purpose: "Frozen QA action across the session boundary" }, ...(recovery ? recovery.resources.filter((resource) => resource.requiredForRecovery).map((resource) => ({
                                     label: resource.label, digest: resource.digest, authoritative: true, requiredForRecovery: resource.requiredForRecovery,
                                     mediaType: resource.mediaType, path: resource.path, purpose: resource.purpose, bytes: resource.bytes,
                                 })) : [])],
@@ -1822,14 +1927,31 @@ export function buildStartCommand(options = {}) {
                 if (continueTickets.length > 0) {
                     const sessions = findResumableBranchSessions(join(cwd, ".foreman"));
                     const sessionByTicket = new Map(sessions.map((session) => [session.ticket, session]));
+                    const historicalReader = new WorkflowReader(cwd);
+                    let historicalSessionTickets;
+                    try {
+                        historicalSessionTickets = new Set(historicalReader.branchResumeSessions(false).map((session) => session.ticket));
+                    }
+                    finally {
+                        historicalReader.close();
+                    }
                     const nodes = [];
+                    const freshTicketIds = [];
                     for (const ticketId of continueTickets) {
                         const session = sessionByTicket.get(ticketId);
                         if (!session) {
-                            fail([
-                                `no resumable branch session found for ticket ${ticketId}`,
-                                branchContinueTicketHelp(cwd),
-                            ].join("\n"));
+                            const ticketState = states.get(ticketId)?.status ?? "planned";
+                            if (opts.resume || !recoveryRecord || recoveryRecord.branchMode !== "per-ticket" || historicalSessionTickets.has(ticketId) || !["planned", "next"].includes(ticketState)) {
+                                fail([
+                                    `no resumable branch session found for ticket ${ticketId}`,
+                                    branchContinueTicketHelp(cwd),
+                                ].join("\n"));
+                            }
+                            // This ticket has no prior branch/session evidence and remains in a
+                            // not-started tracker state. It is new work within the already
+                            // admitted original scope, not an interrupted session to replay.
+                            freshTicketIds.push(ticketId);
+                            continue;
                         }
                         const ticket = ticketById.get(ticketId);
                         if (!ticket)
@@ -1857,6 +1979,20 @@ export function buildStartCommand(options = {}) {
                             deliveryUnitFinal: session.deliveryUnitFinal,
                         });
                     }
+                    if (freshTicketIds.length) {
+                        const fresh = buildBranchPlan(tickets, states, {
+                            steps: freshTicketIds.length,
+                            baseRef: opts.base ?? loadTicketSetupConfig(cwd)?.build.base_branch ?? currentGitRef(cwd),
+                            branchPrefix,
+                            maxBranchDepth,
+                            rootBaseBranches: branchDefaults.rootBaseBranches,
+                            ticketIds: freshTicketIds,
+                        });
+                        if (fresh.issues.some(issue => issue.blocking) || fresh.nodes.length !== freshTicketIds.length || fresh.nodes.some(node => !freshTicketIds.includes(node.ticket.id))) {
+                            fail(`remaining branch tickets are not runnable as fresh approved work: ${fresh.issues.filter(issue => issue.blocking).map(issue => issue.message).join("; ") || "planner did not return the exact remaining scope"}`);
+                        }
+                        nodes.push(...fresh.nodes);
+                    }
                     plan = {
                         baseRef: nodes[0]?.baseRef ?? (opts.base ?? currentGitRef(cwd)),
                         nodes,
@@ -1939,6 +2075,7 @@ export function buildStartCommand(options = {}) {
                     stacked: selectedStacks.length > 0,
                     resumed: continueTickets.length > 0 || Boolean(recoveryRecord),
                 });
+                warnRiskPlanWaivers(cwd, plan.nodes.map((node) => node.ticket.id));
                 log.write("branch-plan", {
                     ...branchPlanLogMetadata(plan, branchPresentation),
                     ...(auditDependencyCount === undefined ? {} : { auditDependencyCount }),
@@ -2234,8 +2371,9 @@ export function buildStartCommand(options = {}) {
                         : `foreman: inspect recovery with: ${formatRecoveryCommand(cwd)}`);
                     process.exit(2);
                 }
-                if (pendingHandoffGeneration !== undefined)
-                    throw new Error(`recovery handoff generation ${pendingHandoffGeneration} for ${pendingHandoffRole} was not accepted; recovery mode was not substituted`);
+                if (pendingHandoffGeneration !== undefined) {
+                    throw new HandoffRecoveryPausedError(recoveryRecord?.runId ?? invocationRunId, pendingHandoffGeneration, `Recovery handoff generation ${pendingHandoffGeneration} was not consumed; the staged handoff remains available for a subsequent validated recovery`);
+                }
                 clearInterval(branchHeartbeat);
                 if (selectedStacks.length) {
                     let allComplete = true;
@@ -2256,15 +2394,15 @@ export function buildStartCommand(options = {}) {
                     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");
+                // A targeted QA recovery returns one completed summary. Reconcile the
+                // original admitted scope before declaring the master run complete.
+                masterRun = finishBranchTicketScope(cwd, masterRun, summaries.every((row) => row.buildStatus === "done") ? "branch-partial-scope-complete" : "branch-run-interrupted");
                 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);
+                pruneRecoveryTelemetryAtCompletion(cwd, observabilityConfig.detail_retention_days);
                 activeObserver = undefined;
                 process.off("exit", finishObservationOnExit);
                 console.log("foreman: branch run summary");
@@ -2295,14 +2433,20 @@ export function buildStartCommand(options = {}) {
                 process.exit(failed ? 2 : 0);
             }
             if (!recoveryRecord && isTicketsInitialized(cwd)) {
-                const paths = resolveTicketPaths(loadTicketsConfig(cwd), cwd);
+                const ticketsConfig = loadTicketsConfig(cwd);
+                const paths = resolveTicketPaths(ticketsConfig, cwd);
                 const state = new StateDb(paths.stateDb);
                 try {
-                    executionTickets = executionTickets ?? loadTickets(paths.tickets).filter(ticket => !["done", "canceled", "cancelled", "obsolete"].includes(state.getState(ticket.id)?.status ?? "planned")).sort((a, b) => a.order - b.order).slice(0, steps).map(ticket => ticket.id);
+                    if (!executionTickets) {
+                        executionTickets = selectDefaultExecutionTickets(loadTickets(paths.tickets), state.getAllStates(), ticketsConfig.implementationLimit, steps, deliveryConfig);
+                        if (!executionTickets.length)
+                            fail("no eligible tickets are available to start; run `rafi tickets queue` to inspect blockers");
+                    }
                 }
                 finally {
                     state.close();
                 }
+                warnRiskPlanWaivers(cwd, executionTickets);
             }
             if (grantedNetwork || opts.builderApprovals)
                 console.log(`foreman: requested Builder shell capabilities: network ${grantedNetwork ? "approved for this build" : "off"}; approvals ${opts.builderApprovals ? "per operation" : "never"}. Effective permissions will be verified with the provider.`);
@@ -2578,8 +2722,13 @@ export function buildStartCommand(options = {}) {
                     const qa = await (activeObserver
                         ? activeObserver.span("qa_recovery", "Exact QA-only recovery", () => foreman.completePendingQaRecovery(ticketId))
                         : foreman.completePendingQaRecovery(ticketId));
-                    if (pendingHandoffGeneration !== undefined)
-                        throw new Error(`recovery handoff generation ${pendingHandoffGeneration} for ${pendingHandoffRole} was not accepted`);
+                    if (pendingHandoffGeneration !== undefined) {
+                        // QA can stop before allocating a provider session (for example
+                        // when host prerequisites are unavailable). Keep the staged
+                        // handoff recoverable and report that boundary explicitly; do not
+                        // turn an unattempted acceptance into a terminal build failure.
+                        throw new HandoffRecoveryPausedError(buildRun.runId, pendingHandoffGeneration, `QA handoff generation ${pendingHandoffGeneration} was not consumed because QA stopped before session acceptance; the handoff remains staged for recovery`);
+                    }
                     if (foreman.qaSessionId())
                         buildRun = persistBuildSession(cwd, buildRun, "qa", foreman.qaSessionRef() ?? foreman.qaSessionId());
                     buildRun = qa.outcome === "passed" || qa.outcome === "waived"
@@ -2679,8 +2828,9 @@ export function buildStartCommand(options = {}) {
                 };
                 const batch = () => foreman.runBatch(steps, trackerRelPath, onTicketStart, preferredTicket, executionTickets);
                 const result = await (activeObserver ? activeObserver.span("builder_work", "Builder and QA batch", batch) : batch());
-                if (pendingHandoffGeneration !== undefined)
-                    throw new Error(`recovery handoff generation ${pendingHandoffGeneration} for ${pendingHandoffRole} was not accepted; recovery mode was not substituted`);
+                if (pendingHandoffGeneration !== undefined) {
+                    throw new HandoffRecoveryPausedError(buildRun.runId, pendingHandoffGeneration, `Recovery handoff generation ${pendingHandoffGeneration} was not consumed; the staged handoff remains available for a subsequent validated recovery`);
+                }
                 if (foreman.builderSessionId())
                     buildRun = persistBuildSession(cwd, buildRun, "builder", foreman.builderAdapter().sessionRef?.() ?? foreman.builderSessionId());
                 if (foreman.qaSessionId())
@@ -2699,7 +2849,7 @@ export function buildStartCommand(options = {}) {
                 observabilityStore?.enforceLimits();
                 observabilityStore?.maintainLogs(cwd);
                 observabilityStore?.close();
-                pruneRecoveryTelemetryAtCompletion(cwd, config.observability.detail_retention_days);
+                pruneRecoveryTelemetryAtCompletion(cwd, observabilityConfig.detail_retention_days);
                 activeObserver = undefined;
                 process.off("exit", finishObservationOnExit);
                 console.log(`\n${accent("foreman:")} ${result.completed}/${result.requested} step(s) completed`);
@@ -3003,9 +3153,14 @@ export function createQaNonconvergenceHandler(projectDir, noninteractive, planne
                 const match = /RAFI_QA_REMEDIATION_START\s*([\s\S]*?)\s*RAFI_QA_REMEDIATION_END/.exec(run.turn.result.text);
                 if (!match)
                     throw new Error("Planner remediation did not return the required structured proposal");
-                const proposal = JSON.parse(match[1].replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, ""));
-                if (!proposal.summary || !Array.isArray(proposal.fix_instructions) || !proposal.fix_instructions.every((item) => typeof item === "string"))
-                    throw new Error("Planner remediation proposal is malformed");
+                let parsed;
+                try {
+                    parsed = JSON.parse(match[1].replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, ""));
+                }
+                catch (error) {
+                    throw new Error(`Planner remediation proposal is invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                const proposal = parseProviderContract(qaRemediationProposalV1Schema, parsed, "RAFI_QA_REMEDIATION");
                 console.log(`\nPlanner remediation: ${proposal.summary}\n${proposal.fix_instructions.map((item) => `- ${item}`).join("\n")}`);
                 const decision = await ask(`QA remediation approval ${revision}: ${JSON.stringify(proposal)}`, [{ id: "approve", label: "Approve" }, { id: "revise", label: "Revise" }, { id: "cancel", label: "Return to choices" }], () => 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" },

package/dist/cli/state.js

@@ -1,6 +1,6 @@
 import { Command } from "commander";
 import { resolve } from "node:path";
-import { exportStateBundle, hasTransferableState, importStateBundle, inspectStateBundle } from "../stateTransfer.js";
+import { exportStateBundle, hasTransferableState, importStateBundle, inspectBuildProjectIdentity, inspectStateBundle, rebindBuildProjectIdentity } from "../stateTransfer.js";
 export function buildStateCommand(opts = {}) {
     const command = new Command("state")
         .description("Export, inspect, and import portable Rafi local state bundles.");
@@ -65,5 +65,43 @@ export function buildStateCommand(opts = {}) {
             console.log(`  previous state backup: ${result.backupDir}`);
         console.log("  provider sessions are historical only; resume with `rafi build:resume --fresh-with-handoff` if exact session recovery fails");
     });
+    command
+        .command("rebind")
+        .description("Inspect or explicitly rebind copied local build state to this checkout.")
+        .argument("[project]", "project directory", ".")
+        .option("-y, --yes", "confirm rebinding copied local state")
+        .action(async (project, options) => {
+        const root = opts.resolveProject ? opts.resolveProject(project) : resolve(project);
+        const status = inspectBuildProjectIdentity(root);
+        if (!status.recoveryDatabasePresent) {
+            console.log(`rafi state rebind: no local recovery database at ${status.currentRoot}; nothing to rebind`);
+            return;
+        }
+        if (!status.storedRoot) {
+            console.log(`rafi state rebind: local recovery database at ${status.currentRoot} predates project-root binding; nothing to rebind`);
+            return;
+        }
+        console.log("rafi state rebind:");
+        console.log(`  stored path: ${status.storedRoot}`);
+        console.log(`  current path: ${status.currentRoot}`);
+        if (status.matches) {
+            console.log("  status: already bound to this checkout");
+            return;
+        }
+        console.log("  status: copied or moved local build state");
+        console.log("  rebinding preserves local history and records the path change; it does not merge state from the original checkout.");
+        if (!options.yes) {
+            if (!process.stdin.isTTY || !process.stdout.isTTY)
+                throw new Error("rebinding changes local build-state identity; rerun with --yes after reviewing the stored and current paths");
+            const { confirm, isCancel } = await import("@clack/prompts");
+            const approved = await confirm({ message: "Rebind this copied local build state to the current checkout?", initialValue: false });
+            if (isCancel(approved) || !approved) {
+                console.log("rafi state rebind: cancelled; no state changed");
+                return;
+            }
+        }
+        rebindBuildProjectIdentity(root);
+        console.log(`rafi state rebind: rebound copied local state to ${status.currentRoot}`);
+    });
     return command;
 }

package/dist/cli/tickets.d.ts

@@ -5,7 +5,29 @@ import type { EffortLevel } from "../adapters/types.js";
 import { type RoleBuilderOptions } from "../agentRun.js";
 import type { TicketsConfig } from "../tickets/config.js";
 import { type TicketPopulateRuntimeMode, type TicketSourceConfig, type TicketsSetupConfig } from "../tickets/setupConfig.js";
+/** Commander preserves comma-delimited values as one argument; accept both documented forms. */
+export declare function normalizeRiskWaiverTicketIds(values: readonly string[] | undefined): string[];
+/** Record an explicit, definition-bound exception for existing risk tickets. */
+export declare function waiveTicketRiskNotes(projectDir: string, ticketIds: string[], reason: string, actor?: string): void;
+export interface RiskNoteRepairProposal {
+    version: 1;
+    tickets: Array<{
+        id: string;
+        rollback: string;
+    }>;
+}
+export declare function extractRiskNoteRepairProposal(output: string): RiskNoteRepairProposal;
+/** Validate a deliberately narrow repair: only exactly the missing rollback fields may change. */
+export declare function applyRiskNoteRepairProposal(tickets: import("../tickets/ticketSchema.js").TicketDef[], proposal: RiskNoteRepairProposal): import("../tickets/ticketSchema.js").TicketDef[];
 export declare function buildPopulateInstruction(approvedPlanPath: string, contextSources?: string[], progressDoc?: string): string;
+/** A bounded correction loop ended without a publishable proposal. */
+export declare class TicketPopulationRiskCorrectionExhaustedError extends Error {
+    readonly ticketIds: string[];
+    readonly projectDir: string;
+    readonly interviewId: string;
+    readonly proposalFile: string;
+    constructor(ticketIds: string[], projectDir: string, interviewId: string, proposalFile: string);
+}
 export declare function resolvePopulateSources(projectDir: string, explicitSources: string[] | undefined, ticketsConfig: TicketsConfig): string[] | undefined;
 export declare function buildPopulateAgentRunOptions(opts: {
     projectDir: string;
@@ -27,10 +49,25 @@ interface PopulateCommandOptions {
     fast?: boolean;
     yes?: boolean;
     authorizeRetire?: string[];
+    waiveRiskNotes?: string[];
+    waiverReason?: string;
+    waiverActor?: string;
     resumeSession?: string;
+    proposalFile?: string;
 }
 export declare function combineRequirementSelections(selected: string[], additions: string): string[];
 export declare function cmdPopulateCli(opts: PopulateCommandOptions): Promise<void>;
+interface RepairRiskNotesOptions {
+    project?: string;
+    agent?: string;
+    model?: string;
+    effort?: string;
+    fast?: boolean;
+    apply?: boolean;
+    yes?: boolean;
+}
+/** Ask Ticket Maker for a reviewable, rollback-only repair of published tickets. */
+export declare function cmdRepairRiskNotesCli(opts: RepairRiskNotesOptions): Promise<void>;
 /** Resolve only the strategy. Context documents never select an import mode. */
 export declare function resolvePopulationMode(setup: TicketsSetupConfig | undefined): TicketPopulateRuntimeMode;
 export interface PopulationContextSelection {