ai-foreman 1.7.24 → 1.7.26

package/dist/adapters/fastMode.js

@@ -0,0 +1,9 @@
+/** Only explicit speed-option rejection permits a same-session retry. Auth,
+ * generic model failures, timeouts, and uncertain transport failures do not. */
+export function isFastModeUnavailable(detail) {
+    return /(?:fast(?:[ _-]mode)?|service[ _-]tier|speed\s*[=:]\s*["']?fast)[\s\S]{0,160}(?:not supported|unsupported|not available|unavailable|not enabled|disabled|not allowed|requires|invalid|unrecognized|unknown)|(?:not supported|unsupported|not available|unavailable|invalid|unrecognized|unknown)[\s\S]{0,100}(?:--fast|fast[ _-]mode|service[ _-]tier)/i.test(detail);
+}
+export function reportFastModeUnavailable(model) {
+    const label = (model ?? "the selected model").replace(/[\x00-\x1f\x7f-\x9f]/g, "").slice(0, 200);
+    console.error(`rafi: Fast mode not available with ${label}; continuing at standard speed.`);
+}

package/dist/adapters/types.d.ts

@@ -6,6 +6,8 @@ import type { ConfigurableAgentRole, ProviderSessionRefV1, RuntimeProbeCategory,
 import type { RunObserver } from "../observability.js";
 /** A permission request surfaced by a builder before it runs a tool. */
 export interface PermissionRequest {
+    /** Provider-observed tool cwd, distinct from immutable session launch scope. */
+    executionCwd?: string;
     toolName: string;
     input: Record<string, unknown>;
     /** Human-readable prompt from the agent, when available. */

package/dist/agentRun.js

@@ -54,6 +54,7 @@ export function readOnlyPermissionConfig() {
             "npm run typecheck",
             "npm run lint",
             "npm run check",
+            "node --test",
             "pnpm test",
             "pnpm run test",
             "pnpm typecheck",

package/dist/branch/runner.js

@@ -304,7 +304,7 @@ export async function runBranchPlan(opts) {
             base: node.baseBranch,
             dependencies: node.dependencies,
         });
-        workflowCheckpoint(opts.projectDir, opts.runId, "builder-before", node.ticket.id, { branch: node.branch, worktree: node.worktreePath });
+        workflowCheckpoint(opts.projectDir, opts.runId, qaOnlyRecovery ? "qa-recovery-before" : "builder-before", node.ticket.id, { branch: node.branch, worktree: node.worktreePath });
         const continuationDb = new WorkflowDb(opts.projectDir);
         const continuationSession = continuations.length ? continuationDb.branchResumeSession(opts.runId, node.ticket.id) : undefined;
         continuationDb.close();
@@ -391,50 +391,52 @@ export async function runBranchPlan(opts) {
                     ? await opts.observer.withContext({ role: "builder", stream: "builder", ticketId: node.ticket.id, deliveryUnitId: node.deliveryUnitId }, turn)
                     : await turn();
             builder = foreman.builderAdapter();
-            workflowCheckpoint(opts.projectDir, opts.runId, "builder-after", node.ticket.id, { status: status.kind, sessionId: builder.sessionId(), worktree: worktreePath });
-            const sessionId = builder.sessionId();
-            const sessionRef = builder.sessionRef?.();
-            if (sessionId)
-                builderStream = { sessionId, ...(sessionRef ? { sessionRef } : {}), worktreePath };
-            if (sessionId) {
-                opts.recordBuilderSession?.(sessionRef ?? sessionId, node.ticket.id, worktreePath);
-                workflowCheckpoint(opts.projectDir, opts.runId, "builder-session-scoped", node.ticket.id, { sessionId, sessionRef, worktree: worktreePath, branch: node.branch });
-            }
-            if (sessionId) {
-                const resumeSession = {
-                    ticket: node.ticket.id,
-                    branch: node.branch,
-                    base: node.baseBranch,
-                    worktreePath,
-                    sessionId,
-                    sessionRef: builder.sessionRef?.(),
-                    agent: opts.agent,
-                    model: opts.model,
-                    effort: opts.effort,
-                    fast: opts.fast,
-                    qaEnabled: opts.qaEnabled,
-                    createPr: createsReview,
-                    completionMode,
-                    reviewProvider,
-                    prReady: opts.prReady,
-                    keepWorktrees: opts.keepWorktrees,
-                    deliveryUnitId: node.deliveryUnitId,
-                    deliveryUnitFinal: node.deliveryUnitFinal,
-                    logPath: "structured-recovery",
-                    ts: new Date().toISOString(),
-                };
-                opts.log.write("branch-session", resumeSession);
-                const resumeDb = new WorkflowDb(opts.projectDir);
-                try {
-                    resumeDb.recordBranchResumeSession(opts.runId, resumeSession);
-                }
-                finally {
-                    resumeDb.close();
+            if (!qaOnlyRecovery) {
+                workflowCheckpoint(opts.projectDir, opts.runId, "builder-after", node.ticket.id, { status: status.kind, sessionId: builder.sessionId(), worktree: worktreePath });
+                const sessionId = builder.sessionId();
+                const sessionRef = builder.sessionRef?.();
+                if (sessionId)
+                    builderStream = { sessionId, ...(sessionRef ? { sessionRef } : {}), worktreePath };
+                if (sessionId) {
+                    opts.recordBuilderSession?.(sessionRef ?? sessionId, node.ticket.id, worktreePath);
+                    workflowCheckpoint(opts.projectDir, opts.runId, "builder-session-scoped", node.ticket.id, { sessionId, sessionRef, worktree: worktreePath, branch: node.branch });
                 }
-                if (node.deliveryUnitId) {
-                    const path = deliverySessionPath(opts.projectDir, node.deliveryUnitId);
-                    mkdirSync(join(opts.projectDir, ".foreman", "delivery-sessions"), { recursive: true });
-                    writeFileSync(path, `${JSON.stringify({ runId: opts.runId, unitId: node.deliveryUnitId, branch: node.branch, worktreePath, sessionId, sessionRef: builder.sessionRef?.(), ticket: node.ticket.id }, null, 2)}\n`, "utf8");
+                if (sessionId) {
+                    const resumeSession = {
+                        ticket: node.ticket.id,
+                        branch: node.branch,
+                        base: node.baseBranch,
+                        worktreePath,
+                        sessionId,
+                        sessionRef: builder.sessionRef?.(),
+                        agent: opts.agent,
+                        model: opts.model,
+                        effort: opts.effort,
+                        fast: opts.fast,
+                        qaEnabled: opts.qaEnabled,
+                        createPr: createsReview,
+                        completionMode,
+                        reviewProvider,
+                        prReady: opts.prReady,
+                        keepWorktrees: opts.keepWorktrees,
+                        deliveryUnitId: node.deliveryUnitId,
+                        deliveryUnitFinal: node.deliveryUnitFinal,
+                        logPath: "structured-recovery",
+                        ts: new Date().toISOString(),
+                    };
+                    opts.log.write("branch-session", resumeSession);
+                    const resumeDb = new WorkflowDb(opts.projectDir);
+                    try {
+                        resumeDb.recordBranchResumeSession(opts.runId, resumeSession);
+                    }
+                    finally {
+                        resumeDb.close();
+                    }
+                    if (node.deliveryUnitId) {
+                        const path = deliverySessionPath(opts.projectDir, node.deliveryUnitId);
+                        mkdirSync(join(opts.projectDir, ".foreman", "delivery-sessions"), { recursive: true });
+                        writeFileSync(path, `${JSON.stringify({ runId: opts.runId, unitId: node.deliveryUnitId, branch: node.branch, worktreePath, sessionId, sessionRef: builder.sessionRef?.(), ticket: node.ticket.id }, null, 2)}\n`, "utf8");
+                    }
                 }
             }
             opts.log.write("step", {

package/dist/buildAssignment.d.ts

@@ -2,7 +2,7 @@ import type { BuilderAdapter } from "./adapters/types.js";
 import type { StepStatus } from "./foreman.js";
 import type { TurnResult } from "./adapters/types.js";
 import { type FrozenQaSourceState } from "./qaSnapshot.js";
-import type { ProviderSessionRefV1 } from "rafi-spec";
+import type { BuildRunRecordV2, ProviderSessionRefV1 } from "rafi-spec";
 /** Work responses confirm an assignment; they never select the next ticket. */
 export declare function validateBuildAssignment(ticketId: string, status: StepStatus, responseText?: string): string | undefined;
 export interface BuildAssignmentCapture {
@@ -20,6 +20,23 @@ type BuildSourceState = Pick<FrozenQaSourceState, "digest" | "head" | "contentDi
 };
 export declare class BuildAssignmentRejected extends Error {
 }
+/** A frozen exact-session Builder decision may defer unrelated pending QA. */
+export declare function isInterruptedBuilderRecovery(run: BuildRunRecordV2 | undefined): boolean;
+/** Recovery requires current source, assignment and admission proofs.
+ * A V3 or migrated record alone never grants continuation authority;
+ * full eligibility is verified before any unknown receipt is reconciled. */
+export declare function canReconcileInterruptedBuilderSource(projectDir: string, runId: string): boolean;
+/** Resume the existing approved build from observed local source, never replay
+ * the interrupted instruction or pretend its unknown outcome was successful.
+ * The caller must own recovery admission and the original run's workflow lease. */
+export declare function prepareInterruptedBuilderSourceContinuation(projectDir: string, runId: string): {
+    ticketIds: string[];
+    reconciliationId: string;
+    sourceDigest: string;
+    contentDigest: string;
+};
+/** A launch may not consume a recovery snapshot after product source changes. */
+export declare function assertInterruptedSourceSnapshot(projectDir: string, run: BuildRunRecordV2): void;
 /**
  * Retire only the host-side records for a Builder turn that was interrupted
  * before Rafi received a durable response.  The next turn is sent to the
@@ -32,6 +49,9 @@ export declare function prepareExactSessionBuilderContinuation(projectDir: strin
     dispatchIds: string[];
     assignmentIds: string[];
 };
+/** Retire uncertain execution for an explicitly selected start-over, never claim
+ * that a provider did not run or that its preserved implementation passed QA. */
+export declare function retireBuildExecutionForStartOver(projectDir: string, runId: string, operationId: string): void;
 export interface BuilderGuidanceFollowup {
     reviewAttemptId: string;
     requirementsDigest: string;

package/dist/buildAssignment.js

@@ -10,6 +10,11 @@ import { spawnSync } from "node:child_process";
 import { captureFrozenQaSource } from "./qaSnapshot.js";
 import { WorkflowDb } from "./workflowDb.js";
 import { WorkflowReader } from "./workflowReader.js";
+import { classifyProcess, processGroupQuiescent } from "./processIdentity.js";
+import { loadTicketsConfig, resolveTicketPaths } from "./tickets/config.js";
+import { loadTickets } from "./tickets/ticketLoader.js";
+import { qaDigest } from "./qaProtocolV2.js";
+import { providerSessionKey } from "./sessionIdentity.js";
 /** Work responses confirm an assignment; they never select the next ticket. */
 export function validateBuildAssignment(ticketId, status, responseText = "") {
     // An unmarked response may receive the existing bounded response-only repair.
@@ -26,6 +31,140 @@ export function validateBuildAssignment(ticketId, status, responseText = "") {
 }
 export class BuildAssignmentRejected extends Error {
 }
+/** A frozen exact-session Builder decision may defer unrelated pending QA. */
+export function isInterruptedBuilderRecovery(run) {
+    if (!run)
+        return false;
+    const decision = run.recoveryDecision;
+    const continuation = run.interruptedBuilderContinuation;
+    if (continuation?.recovery === "source-reconciled" && continuation.reconciliationId) {
+        return decision?.runId === run.runId && decision.role === "builder" && decision.mode === "fresh-with-handoff"
+            && Boolean(continuation.ticketIds?.length === 1 && decision.executionTickets?.includes(continuation.ticketIds[0])
+                && run.tickets.includes(continuation.ticketIds[0]));
+    }
+    return decision?.runId === run.runId && decision.role === "builder" && decision.mode === "exact-session"
+        && Boolean(decision.executionTickets?.length && decision.executionTickets.every(id => run.tickets.includes(id)))
+        && Boolean(continuation?.ticketIds?.length === 1 && decision.executionTickets?.includes(continuation.ticketIds[0]))
+        && Boolean(continuation?.sessionRef && decision.predecessorSessionRef && sameSession(continuation.sessionRef, decision.predecessorSessionRef));
+}
+/** Recovery requires current source, assignment and admission proofs.
+ * A V3 or migrated record alone never grants continuation authority;
+ * full eligibility is verified before any unknown receipt is reconciled. */
+export function canReconcileInterruptedBuilderSource(projectDir, runId) {
+    const db = new WorkflowReader(projectDir);
+    try {
+        const state = db.getRun(runId)?.state;
+        const assignments = db.operations(runId, true).filter(op => op.kind === "build-assignment" && ["in_progress", "uncertain"].includes(op.status));
+        if (state?.version !== 3 || state.branchMode !== "current" || assignments.length !== 1)
+            return false;
+        const intent = assignments[0].intent;
+        return Boolean(intent.ticketId && state.tickets.includes(intent.ticketId) && intent.before?.digest && intent.requirementsDigest && intent.instructionDigest
+            && db.events(runId).some(event => event.type === "worker_started"));
+    }
+    finally {
+        db.close();
+    }
+}
+/** Resume the existing approved build from observed local source, never replay
+ * the interrupted instruction or pretend its unknown outcome was successful.
+ * The caller must own recovery admission and the original run's workflow lease. */
+export function prepareInterruptedBuilderSourceContinuation(projectDir, runId) {
+    const db = new WorkflowDb(projectDir);
+    try {
+        const lease = db.currentLease();
+        if (lease?.runId !== runId || lease.pid !== process.pid)
+            throw new BuildAssignmentRejected("Source recovery requires the original run's current recovery lease");
+        if (!canReconcileInterruptedBuilderSource(projectDir, runId))
+            throw new BuildAssignmentRejected("Interrupted work lacks current source-bound assignment authority; use guided recovery or preserve files and restart");
+        const run = db.getRun(runId).state;
+        if (run.builderCapabilities?.grantedNetwork)
+            throw new BuildAssignmentRejected("Interrupted network-enabled work requires explicit side-effect reconciliation; source inspection cannot establish remote outcomes");
+        if (db.readinessProcesses().length || db.unresolvedRoleDispatches(runId, "qa").length)
+            throw new BuildAssignmentRejected("Owned processes or a separate QA dispatch must be reconciled before Builder source recovery");
+        if (db.incompletePublications().some(item => item.runId === runId && item.intent.operation !== "build-run-projection"))
+            throw new BuildAssignmentRejected("A pending source/tracker publication must be reconciled before Builder source recovery");
+        const worker = db.events(runId).filter(event => event.type === "worker_started").at(-1)?.payload;
+        if (!worker?.workerPid || classifyProcess(worker.workerPid, worker.processStart, worker.host).state !== "dead" || !processGroupQuiescent(worker.workerPid)) {
+            throw new BuildAssignmentRejected("The interrupted worker and its owned process group must be verified stopped before source recovery");
+        }
+        const assignment = db.operations(runId).find(op => op.kind === "build-assignment" && ["in_progress", "uncertain"].includes(op.status));
+        const intent = assignment.intent;
+        if (realpathSync(intent.worktree) !== realpathSync(projectDir) || realpathSync(run.repository.worktree) !== realpathSync(projectDir))
+            throw new BuildAssignmentRejected("Interrupted source belongs to another worktree");
+        if (run.progress.completedTickets.includes(intent.ticketId) || ["completed", "waived"].includes(db.qaTicketHead(runId, intent.ticketId).state))
+            throw new BuildAssignmentRejected("A completed ticket cannot be reopened by interrupted source recovery");
+        const admission = db.assertAdmittedWork(runId, intent.ticketId);
+        const definition = loadTickets(resolveTicketPaths(loadTicketsConfig(projectDir), projectDir).tickets).find(ticket => ticket.id === intent.ticketId);
+        if (!definition || admission.requirementsDigest !== intent.requirementsDigest || qaDigest("admitted-requirements", definition) !== intent.requirementsDigest)
+            throw new BuildAssignmentRejected("Interrupted ticket requirements changed; current scope needs approval before recovery");
+        const dispatches = db.unresolvedRoleDispatches(runId, "builder");
+        const owner = db.roleMutationLease(runId, "builder");
+        if (!dispatches.length || !owner?.sessionRef || !owner.sessionKey || owner.sessionRef.source !== "observed" || !owner.sessionRef.validatedAt
+            || Number.isNaN(Date.parse(owner.sessionRef.validatedAt)) || dispatches.some(op => {
+            const ref = op.intent.sessionRef;
+            return !sameSession(ref, owner.sessionRef) || providerSessionKey(ref) !== owner.sessionKey;
+        }))
+            throw new BuildAssignmentRejected("Interrupted dispatch is not bound to the recorded Builder owner");
+        const source = captureBuildSource(projectDir);
+        if (run.repository.branch && sourceBranch(projectDir) !== run.repository.branch)
+            throw new BuildAssignmentRejected("The current branch changed; return to the interrupted build's owning branch before source recovery");
+        const reconciliationId = `source-resume:${runId}:${randomUUID()}`;
+        db.atomic(() => {
+            if (captureBuildSource(projectDir).digest !== source.digest)
+                throw new BuildAssignmentRejected("Preserved source changed during recovery inspection; retry from the current files");
+            const retained = retainSource(db, source);
+            const receipt = { recovery: "source-reconciled", reconciliationId, outcomeUnknown: true, providerReplayAuthorized: false, source: retained, ticketId: intent.ticketId, requirementsDigest: intent.requirementsDigest, worker, at: new Date().toISOString() };
+            for (const dispatch of dispatches)
+                db.updateOperation(dispatch.idempotencyKey, "failed", { result: { ...receipt, priorResult: dispatch.result }, error: "Interrupted provider outcome remains unknown; verified stopped local execution is replaced by source inspection and fresh QA, without replay" });
+            db.updateOperation(assignment.idempotencyKey, "failed", { result: { ...receipt, priorResult: assignment.result }, error: "Interrupted assignment preserved for source-bound continuation; completion is not established" });
+            const event = db.appendContinuityEvent({ runId, role: "host", kind: "interrupted_source_reconciled", payload: { ...receipt, dispatchIds: dispatches.map(op => op.idempotencyKey), assignmentId: assignment.idempotencyKey }, authoritativeStateRevision: db.continuityHead(runId, "run")?.authoritativeStateRevision ?? 0 });
+            db.publishContinuityCheckpoint({ runId, role: "builder", state: "current", authoritativeStateRevision: event.authoritativeStateRevision, delta: {
+                    version: 1, decisions: [`Continue already-approved ticket ${intent.ticketId} in the SAME build from preserved source; this host reconciliation is not a successful provider turn.`],
+                    constraints: ["Never replay the interrupted provider instruction or assume its side effects did not happen. Inspect current files first, implement only missing approved work, and require independent QA. Preserve all completed tickets and accepted QA.", "The predecessor session's compaction history remains unknown; use a validated fresh handoff before any new implementation."],
+                    discoveries: [], completedActions: [], evidence: [`Host-observed source digest ${source.digest}; interrupted assignment ${assignment.idempotencyKey}; reconciliation ${reconciliationId}`],
+                    failures: ["The interrupted provider outcome is unknown and remains preserved in the historical receipt."], blockers: [], openWork: [`Inspect preserved implementation of ${intent.ticketId}; complete remaining criteria and obtain fresh QA.`], nextAction: `Accept a fresh source-bound handoff, inspect ${intent.ticketId}, then continue all remaining approved tickets.`,
+                } });
+            const current = db.getRun(runId);
+            db.transition(runId, { checkpoint: "builder-source-reconciled", state: { ...current.state, interruptedBuilderContinuation: { recovery: "source-reconciled", ticketIds: [intent.ticketId], reconciliationId, sourceDigest: source.digest, contentDigest: source.contentDigest, productDigest: interruptedProductDigest(projectDir, source) } }, event: "builder_source_continuation_authorized", payload: receipt });
+        });
+        return { ticketIds: [intent.ticketId], reconciliationId, sourceDigest: source.digest, contentDigest: source.contentDigest };
+    }
+    finally {
+        db.close();
+    }
+}
+/** A launch may not consume a recovery snapshot after product source changes. */
+export function assertInterruptedSourceSnapshot(projectDir, run) {
+    const continuation = run.interruptedBuilderContinuation;
+    if (continuation?.recovery !== "source-reconciled" || continuation.firstAssignmentId || !continuation.ticketIds?.some(id => !run.progress.completedTickets.includes(id)))
+        return;
+    const reader = new WorkflowReader(projectDir);
+    try {
+        // A stale in-memory snapshot can lag the atomic consumption marker. The
+        // source-bound assignment journal is durable and cannot be overwritten by
+        // the next ordinary run projection.
+        const reconciliationId = continuation.reconciliationId;
+        if (reconciliationId && reader.operations(run.runId, true).some(op => op.kind === "build-assignment" && op.intent.sourceRecoveryId === reconciliationId))
+            return;
+    }
+    finally {
+        reader.close();
+    }
+    const source = captureBuildSource(projectDir);
+    if (continuation.productDigest ? interruptedProductDigest(projectDir, source) !== continuation.productDigest : source.contentDigest !== continuation.contentDigest)
+        throw new BuildAssignmentRejected("Preserved implementation changed after recovery preparation; inspect the current files with rafi resume before launching new work");
+}
+function interruptedProductDigest(projectDir, source) {
+    const paths = resolveTicketPaths(loadTicketsConfig(projectDir), projectDir);
+    // Ticket status/rendering is host bookkeeping, not product mutation. Ticket
+    // definitions and other documents remain bound, including unrelated docs.
+    const bookkeeping = new Set([paths.stateDb, `${paths.stateDb}-wal`, `${paths.stateDb}-shm`, paths.progressDoc, paths.archiveDoc].map(path => relative(projectDir, path).replace(/\\/g, "/")));
+    return createHash("sha256").update(JSON.stringify({ head: source.head, branch: sourceBranch(projectDir), paths: source.pathInventory.filter(path => !bookkeeping.has(path.path)) })).digest("hex");
+}
+function sourceBranch(projectDir) {
+    const result = spawnSync("git", ["branch", "--show-current"], { cwd: projectDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    return result.status === 0 ? result.stdout.trim() : undefined;
+}
 /**
  * Retire only the host-side records for a Builder turn that was interrupted
  * before Rafi received a durable response.  The next turn is sent to the
@@ -78,12 +217,62 @@ export function prepareExactSessionBuilderContinuation(projectDir, runId, sessio
         db.close();
     }
 }
+/** Retire uncertain execution for an explicitly selected start-over, never claim
+ * that a provider did not run or that its preserved implementation passed QA. */
+export function retireBuildExecutionForStartOver(projectDir, runId, operationId) {
+    const db = new WorkflowDb(projectDir);
+    let admission;
+    let lease;
+    try {
+        const operation = db.getRun(operationId);
+        const original = operation?.originalWork;
+        if (operation?.kind !== "recovery" || operation.state.operation !== "build-start-over" || original?.run?.runId !== runId)
+            throw new Error("Execution retirement requires a recorded start-over intent for this run");
+        admission = db.acquireBuildRecoveryAdmission(runId);
+        lease = db.acquireLease(runId);
+        if (db.readinessProcesses().length)
+            throw new Error("Owned process cleanup must be verified before starting over");
+        if (db.incompletePublications().some(item => {
+            if (item.runId !== runId)
+                return false;
+            const intent = item.intent;
+            return intent.operation !== "build-run-projection" || intent.target !== join(resolve(projectDir), ".foreman", "runs", `${runId}.json`);
+        }))
+            throw new Error("Finish pending publication recovery before starting over; preserved files may still be awaiting publication");
+        db.atomic(() => {
+            for (const dispatch of [...db.unresolvedRoleDispatches(runId, "builder"), ...db.unresolvedRoleDispatches(runId, "qa")]) {
+                db.updateOperation(dispatch.idempotencyKey, "failed", { result: { recovery: "start-over", operationId, outcomeUnknown: true, providerReplayAuthorized: false }, error: "Operator chose a fresh run from preserved source; historical execution outcome remains unknown" });
+            }
+            const run = db.getRun(runId);
+            if (!run)
+                throw new Error("Original run disappeared before start-over");
+            db.transition(runId, { checkpoint: "execution-retired-for-start-over", state: { ...run.state, executionRetiredForStartOver: operationId }, event: "execution_retired_for_start_over", payload: { operationId, providerReplayAuthorized: false } });
+        });
+    }
+    finally {
+        try {
+            if (lease)
+                db.releaseLease(lease);
+        }
+        finally {
+            try {
+                if (admission)
+                    db.releaseBuildAdmission(admission);
+            }
+            finally {
+                db.close();
+            }
+        }
+    }
+}
 function sameSession(value, session) {
     if (!value || typeof value !== "object")
         return false;
     const candidate = value;
     return candidate.provider === session.provider
         && candidate.sessionId === session.sessionId
+        && candidate.generation === session.generation
+        && session.role === "builder" && session.stream === "builder"
         && candidate.role === "builder"
         && candidate.stream === "builder"
         && candidate.cwd === session.cwd
@@ -93,9 +282,23 @@ export function assertBuildAssignmentReconciled(projectDir, runId, worktree = pr
     const reader = new WorkflowReader(projectDir);
     try {
         const runs = [...new Set([runId, ...reader.buildRuns(true).map(run => run.runId)])];
+        const retiredRuns = new Set();
         for (const operation of runs.flatMap(id => reader.operations(id, true))) {
             if (operation.kind !== "build-assignment")
                 continue;
+            if (retiredRuns.has(operation.runId))
+                continue;
+            const owner = reader.getRun(operation.runId);
+            // An explicit start-over retires execution, while retaining assignments
+            // as historical evidence. It never authorizes their provider replay.
+            const retirement = typeof owner?.state.supersededBy === "string" ? reader.getRun(owner.state.supersededBy) : undefined;
+            if (owner?.status === "superseded" && retirement?.kind === "recovery" && retirement.state.operation === "build-start-over"
+                && retirement.state.gitPreserved === true && typeof retirement.state.resetId === "string"
+                && retirement.originalWork.run?.runId === operation.runId
+                && reader.events(operation.runId).some(event => event.type === "execution_retired_for_start_over" && event.payload.operationId === retirement.runId)) {
+                retiredRuns.add(operation.runId);
+                continue;
+            }
             const result = operation.result;
             if (result?.reconciliationId)
                 continue;
@@ -134,6 +337,12 @@ export function beginBuildAssignment(projectDir, runId, ticketId, worktree, inst
         db.atomic(() => {
             db.ensureRun(runId);
             const admission = db.assertAdmittedWork(runId, ticketId);
+            const continuationState = db.getRun(runId);
+            const sourceContinuation = continuationState.state.interruptedBuilderContinuation;
+            if (sourceContinuation?.recovery === "source-reconciled" && sourceContinuation.ticketIds?.includes(ticketId) && !sourceContinuation.firstAssignmentId) {
+                assertInterruptedSourceSnapshot(projectDir, continuationState.state);
+                db.transition(runId, { checkpoint: continuationState.checkpoint, state: { ...continuationState.state, interruptedBuilderContinuation: { ...sourceContinuation, firstAssignmentId: operationId } }, event: "builder_source_continuation_consumed", payload: { ticketId, operationId, sourceDigest: before.digest } });
+            }
             let contractBinding;
             if (db.qaPreparationStore().policy(runId)?.mode === "enforce") {
                 const contract = assertContractReceipt(db.qaPreparationStore(), runId, ticketId, admission.requirementsDigest, adapter ? actualContractSession(adapter, worktree, projectDir) : undefined, adapter);
@@ -145,7 +354,11 @@ export function beginBuildAssignment(projectDir, runId, ticketId, worktree, inst
                 if (contract.inputs.find(input => input.kind === "rules")?.digest !== current.digest || contract.inputs.find(input => input.kind === "checklist")?.digest !== contractDigest("input-checklist", current.checklist))
                     throw new BuildAssignmentRejected("Canonical QA rules, skills or checklist changed after delivery; reconcile the contract before implementation");
             }
-            guidance = db.reserveGuidance(runId, ticketId, "builder", operationId, before.digest, instruction);
+            const continuation = db.getRun(runId)?.state.interruptedBuilderContinuation;
+            const recoveredInstruction = continuation?.recovery === "source-reconciled" && continuation.ticketIds?.includes(ticketId)
+                ? `${instruction}\n\nHost recovery ${continuation.reconciliationId}: an earlier assignment was interrupted with an unknown result. Inspect the preserved files before acting. Do not replay the old instruction, repeat completed side effects, or redo completed tickets. Implement only missing acceptance criteria for this ticket, validate the current implementation and return truthful evidence for independent fresh QA.`
+                : instruction;
+            guidance = db.reserveGuidance(runId, ticketId, "builder", operationId, before.digest, recoveredInstruction);
             if (followup) {
                 if (admission.requirementsDigest !== followup.requirementsDigest)
                     throw new BuildAssignmentRejected("Ticket requirements changed; renewed scope approval is required before the Builder follow-up");
@@ -160,7 +373,7 @@ export function beginBuildAssignment(projectDir, runId, ticketId, worktree, inst
                 db.transitionQa(runId, ticketId, head.revision, { type: "builder-guidance-followup-intended" });
             }
             const instructionDigest = db.putEvidence("qa", Buffer.from(guidance.text));
-            db.planOperation({ runId, idempotencyKey: operationId, kind: "build-assignment", intent: { ticketId, worktree, admissionId: admission.assignmentId, requirementsDigest: admission.requirementsDigest, instructionDigest, ...(contractBinding ? { contractBinding } : {}), before: retainSource(db, before), ...(followup ? { managerFollowup: followup } : {}) } });
+            db.planOperation({ runId, idempotencyKey: operationId, kind: "build-assignment", intent: { ticketId, worktree, admissionId: admission.assignmentId, requirementsDigest: admission.requirementsDigest, instructionDigest, ...(continuation?.recovery === "source-reconciled" && continuation.ticketIds?.includes(ticketId) ? { sourceRecoveryId: continuation.reconciliationId } : {}), ...(contractBinding ? { contractBinding } : {}), before: retainSource(db, before), ...(followup ? { managerFollowup: followup } : {}) } });
             db.recordWorkAssignment(runId, ticketId, operationId, { requirementsDigest: admission.requirementsDigest, worktree, sourceDigest: before.digest, ownerGeneration: db.currentLease()?.generation, instructionDigest });
             db.updateOperation(operationId, "in_progress");
         });

package/dist/buildRuns.d.ts

@@ -39,6 +39,9 @@ export declare function resumeBuildRun(projectDir: string, runId: string, patch:
 type LegacyResolvedAgentSettings = Omit<ResolvedAgentSettings, "session_strategy" | "settings_revision" | "display_session_cost" | "auto_compact_threshold_percent" | "compact_maximum"> & Partial<Pick<ResolvedAgentSettings, "session_strategy" | "settings_revision" | "display_session_cost" | "auto_compact_threshold_percent" | "compact_maximum">>;
 export declare function saveBuildRun(projectDir: string, run: BuildRunRecordV2, now?: Date): BuildRunRecordV2;
 export declare function checkpointBuildRun(projectDir: string, run: BuildRunRecordV2, checkpoint: string, patch?: Partial<BuildRunRecordV2>): BuildRunRecordV2;
+/** Refresh a publication from durable state while retaining only the caller's
+ * original execution authority. A read-only projection never grants authority. */
+export declare function persistCurrentBuildSession(projectDir: string, authorizedRun: BuildRunRecordV2, role: "builder" | "qa", session: ProviderSessionRefV1): BuildRunRecordV2;
 export declare function persistBuildSession(projectDir: string, run: BuildRunRecordV2, role: "builder" | "qa", session: string | ProviderSessionRefV1): BuildRunRecordV2;
 /** Latest scoped binding, with the narrow legacy Builder inference allowed by the recovery protocol. */
 export declare function buildRunSessionBinding(run: BuildRunRecordV2, role: "builder" | "qa", sessionId?: string): ProviderSessionRefV1 | undefined;
@@ -51,6 +54,8 @@ export declare function releaseBuildLease(projectDir: string, run: BuildRunRecor
 export declare function completeBuildRun(projectDir: string, run: BuildRunRecordV2, now?: Date): BuildRunRecordV2;
 /** A recovered ticket boundary is complete only when the saved run scope is done. */
 export declare function finishRecoveredTicketScope(projectDir: string, run: BuildRunRecordV2, checkpoint: string): BuildRunRecordV2;
+/** A recovered boundary cannot authorize work on a still-blocked remainder. */
+export declare function hasRunnableBuildRemainder(projectDir: string, run: BuildRunRecordV2): boolean;
 export declare function readBuildRuns(projectDir: string): BuildRunRecordV2[];
 export declare function recoverableBuildRuns(projectDir: string, now?: Date): Array<BuildRunRecordV2 & {
     active: boolean;
@@ -71,6 +76,7 @@ export interface BuildRecoveryProjection {
     compactLabel: string;
     compactHint: string;
     completed: string[];
+    completedOperations?: string[];
     remaining: string[];
     lastSuccess: string;
     interruption: string;