ai-foreman 1.7.24 → 1.7.25

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,8 @@ 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;
 /**
  * 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 +34,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

@@ -26,6 +26,18 @@ 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;
+    return decision?.runId === run.runId && decision.role === "builder" && decision.mode === "exact-session"
+        && decision.executionTickets?.length === 1
+        && run.tickets.includes(decision.executionTickets[0])
+        && Boolean(continuation?.ticketIds?.includes(decision.executionTickets[0]))
+        && Boolean(continuation?.sessionRef && decision.predecessorSessionRef && sameSession(continuation.sessionRef, decision.predecessorSessionRef));
+}
 /**
  * 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 +90,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 +155,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;

package/dist/cli/start.d.ts

@@ -24,7 +24,9 @@ export declare function validateStartOptions(opts: Record<string, any>, requireC
 export declare function validateRecoveryArguments(args: readonly string[], projectDir: string): void;
 /** Validate persisted preparation argv without executing a command or provider. */
 export declare function validatePreparationArguments(args: readonly string[], projectDir: string): string[];
-export declare function buildStartCommand(): Command;
+export declare function buildStartCommand(options?: {
+    beforeFreshStart?: (projectDir: string) => Promise<boolean>;
+}): Command;
 export declare function createQaNonconvergenceHandler(projectDir: string, noninteractive: boolean, planner?: AgentRoleDefaultsV1, observer?: () => RunObserver | undefined, activeRunId?: () => string): (context: QaNonconvergenceContext) => Promise<QaNonconvergenceDecision>;
 export declare function createQaReportRecoveryHandler(projectDir: string, noninteractive: boolean, observer?: () => RunObserver | undefined): QaReportRecoveryHandler;
 /** Make the executable branch plan exactly match each explicit root-to-tip stack. */

package/dist/cli/start.js

@@ -8,7 +8,7 @@ import { formatRecoveryCommand, formatDecisionCommands, formatExactRunRecovery }
 import { durableReadOnlyProposal } from "../readOnlyProposal.js";
 import { captureFrozenQaSource } from "../qaSnapshot.js";
 import { finishStartAdmission, superviseStart, supervisedRunId } from "../supervisedStart.js";
-import { assertBuildAssignmentReconciled } from "../buildAssignment.js";
+import { assertBuildAssignmentReconciled, isInterruptedBuilderRecovery } from "../buildAssignment.js";
 import { durableHumanDecision, HumanDecisionRequired, HumanDecisionCancelled, servicePendingHumanDecisions } from "../humanDecision.js";
 import { requiresBuildApproval, buildScopeRevision, createBuildApprovalGate } from "../buildApproval.js";
 import { Command, Option } from "commander";
@@ -450,7 +450,7 @@ export function validatePreparationArguments(args, projectDir) {
             throw new Error("Saved preparation contains stale internal recovery authority");
     return savedStartArguments(command, projectDir, options);
 }
-export function buildStartCommand() {
+export function buildStartCommand(options = {}) {
     return new Command("start")
         .description("Enlist a builder and drive it through a batch of N steps.")
         .argument("<project>", "path to the project directory the builder works in")
@@ -557,6 +557,10 @@ export function buildStartCommand() {
         const cwd = resolve(project);
         if (!existsSync(cwd))
             fail(`project directory not found: ${cwd}`);
+        // Recovery commands launch a frozen continuation and must not recursively
+        // offer a different recovery path. Fresh launches may be redirected first.
+        if (!recoveryIntent && options.beforeFreshStart && !await options.beforeFreshStart(cwd))
+            return;
         const recoveryRecord = opts.recoverRun ? readBuildRuns(cwd).find((run) => run.runId === opts.recoverRun) : undefined;
         let dirtyWork = recoveryRecord?.runDecisions?.dirtyWork;
         if (opts.recoverRun && !recoveryRecord)
@@ -1985,9 +1989,9 @@ export function buildStartCommand() {
                 for (const node of plan.nodes)
                     admitApprovedTicket(cwd, masterRun.runId, node.ticket.id, buildScopeRevision(cwd), `build invocation ${invocationRunId}: approved branch plan`);
                 masterRun = checkpointBuildRun(cwd, masterRun, "capabilities-resolved", { builderCapabilities });
-                const qaResumedRecovery = recoveryRecord ? pendingQaRecoveryPacket(cwd, masterRun.runId, requestedTicketIds[0]) : undefined;
+                const qaResumedRecovery = recoveryRecord && !isInterruptedBuilderRecovery(recoveryRecord) ? pendingQaRecoveryPacket(cwd, masterRun.runId, requestedTicketIds[0]) : undefined;
                 let qaProtocolResumeTicket;
-                if (recoveryRecord && !qaResumedRecovery) {
+                if (recoveryRecord && !qaResumedRecovery && !isInterruptedBuilderRecovery(recoveryRecord)) {
                     const protocolDb = new WorkflowDb(cwd);
                     try {
                         const pendingHeads = protocolDb.pendingQaTicketHeads(masterRun.runId);
@@ -2300,10 +2304,10 @@ export function buildStartCommand() {
             buildRun = checkpointBuildRun(cwd, buildRun, "capabilities-resolved", { builderCapabilities });
             activeObserver?.store.attachExecutionLease(activeObserver.executionId, readCurrentWorkflowLease(cwd)?.generation);
             activeContinuityRunId = buildRun.runId;
-            const qaResumedRecovery = recoveryRecord ? pendingQaRecoveryPacket(cwd, buildRun.runId, requestedTicketIds[0]) : undefined;
+            const qaResumedRecovery = recoveryRecord && !isInterruptedBuilderRecovery(recoveryRecord) ? pendingQaRecoveryPacket(cwd, buildRun.runId, requestedTicketIds[0]) : undefined;
             let qaFinalizationTicket;
             let qaProtocolResumeTicket;
-            if (recoveryRecord && !qaResumedRecovery) {
+            if (recoveryRecord && !qaResumedRecovery && !isInterruptedBuilderRecovery(recoveryRecord)) {
                 const finalizationDb = new WorkflowDb(cwd);
                 try {
                     const pendingHeads = finalizationDb.pendingQaTicketHeads(buildRun.runId);

package/dist/cli/tickets.d.ts

@@ -61,5 +61,6 @@ export declare function ticketOwnershipReceipts(projectDir: string, commandName:
 export declare function buildTicketsCommand(options?: {
     prepareOwnership?: (projectDir: string, receipts: TicketOwnershipReceipt[]) => void;
     recordOwnership?: (projectDir: string, receipts: TicketOwnershipReceipt[]) => void;
+    restartBuild?: (projectDir: string, runId: string, tickets: string[]) => Promise<void>;
 }): Command;
 export {};

package/dist/cli/tickets.js

@@ -1843,7 +1843,7 @@ export function buildTicketsCommand(options = {}) {
     });
     tickets
         .command("reset [ticketId]")
-        .description("Reset one ticket or an explicit ticket scope to pristine active state while retaining history.")
+        .description("Reset tracker state while retaining history; use build:start-over to restart interrupted execution.")
         .option("-p, --project <dir>", "project directory (default: cwd)")
         .option("--all", "open the interactive bulk reset scope chooser")
         .option("--scope <scope>", "bulk scope (all | completed-and-unfinished | unfinished)")
@@ -1898,10 +1898,28 @@ export function buildTicketsCommand(options = {}) {
             for (const row of preview.tickets)
                 console.log(`  ${row.id}: ${row.title} [${row.status}] — clears ${row.cleared.join(", ")}`);
             if (preview.relatedRuns.length) {
-                console.log("  ! Matching build/recovery metadata is not deleted. Use `rafi build:start-over` for a coherent whole-run restart.");
+                console.log("  ! Ticket reset clears tracker state only. It cannot resume a Builder session or resolve pending QA/process recovery.");
                 for (const run of preview.relatedRuns)
                     console.log(`    ${run.runId.slice(0, 8)} [${run.status}] ${run.tickets.join(", ")}`);
             }
+            if (preview.relatedRuns.length) {
+                for (const run of preview.relatedRuns)
+                    console.log(`    Keep files and restart execution: rafi build:start-over --run ${run.runId} --action restart-current`);
+                if (options.restartBuild && process.stdin.isTTY && process.stdout.isTTY && !opts.yes) {
+                    const answer = await select({ message: "These tickets belong to interrupted builds. What should Rafi do?", options: [
+                            ...preview.relatedRuns.map(run => ({ value: run.runId, label: `Restart execution from current files for build ${run.runId.slice(0, 8)} (keep implementation)` })),
+                            { value: "tracker-only", label: "Reset tracker state only; leave build recovery unchanged" },
+                            { value: "cancel", label: "Cancel" },
+                        ] });
+                    if (isCancel(answer) || answer === "cancel")
+                        return;
+                    if (answer !== "tracker-only") {
+                        const run = preview.relatedRuns.find(item => item.runId === answer);
+                        await options.restartBuild(cwd(opts), run.runId, preview.tickets.map(item => item.id).filter(id => run.tickets.includes(id)));
+                        return;
+                    }
+                }
+            }
             if (!preview.tickets.length)
                 return;
             const explicitlyConfirmed = Boolean(opts.yes && (ticketId || opts.scope));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-foreman",
-  "version": "1.7.24",
+  "version": "1.7.25",
   "description": "An orchestrator that keeps Codex CLI / Claude Code builders moving through their step list unattended. Part of Rafi.",
   "license": "Apache-2.0",
   "type": "module",
@@ -308,7 +308,7 @@
     "parse5": "7.2.1",
     "pdfjs-dist": "4.10.38",
     "rafi-spec": "0.8.15",
-    "special-agents": "0.8.14",
+    "special-agents": "0.8.15",
     "yaml": "^2.5.1"
   },
   "devDependencies": {