ai-foreman 2.0.0 → 2.0.1

package/dist/structuredOperation.js

@@ -1,4 +1,5 @@
 import { sealTicketPopulationPage } from "./ticketPopulationPageAuthority.js";
+import { dispatchWasNotSent } from "./dispatchNotSent.js";
 import { boundedUtf8 } from "./boundedTurnEvidence.js";
 import { randomUUID } from "node:crypto";
 import { assertIntermediateResultV2, historicProviderWireContract, providerWireContract, renderProviderWireInstruction, selectedDispatchTupleV2, structuredDigest, validateStructuredCandidate } from "rafi-spec";
@@ -76,6 +77,8 @@ export async function journalStructuredDispatch(root, adapter, instruction, poli
     const db = new WorkflowDb(root);
     try {
         db.enableStructuredCommunication();
+        // A single agent call outside a build journals under its own run, which is
+        // never listed or resumed as a build.
         db.ensureRun(runId);
         if (adapter.postConfirmedDispatch)
             for (const pendingId of db.pendingStructuredPostprocessing(runId)) {
@@ -153,25 +156,31 @@ export async function journalStructuredDispatch(root, adapter, instruction, poli
             turn = await withSealedDispatch(root, tuple, dispatchCapability => dispatch(renderedInstruction, { ...sealedPolicy, journalRunId: runId, dispatchCapability }), before);
         }
         catch (error) {
+            // A host refusal before transport is a known unsent turn, not an unknown outcome.
             if (db.operation(key)?.status === "in_progress")
-                db.updateOperation(key, "uncertain", { error: boundedUtf8(String(error), 4000).toString() });
+                db.updateOperation(key, dispatchWasNotSent(error) ? "failed" : "uncertain", { error: boundedUtf8(String(error), 4000).toString(), ...(dispatchWasNotSent(error) ? { result: { dispatchState: "not-sent" } } : {}) });
             throw error;
         }
         const after = adapter.sessionRef?.();
         const sameScope = before && after && before.provider === after.provider && before.role === after.role &&
             before.stream === after.stream && before.cwd === after.cwd && before.configRoot === after.configRoot &&
             before.workspaceIdentity === after.workspaceIdentity && before.ticketId === after.ticketId && before.deliveryUnitId === after.deliveryUnitId;
+        // A receipt from another dispatch, session or generation leaves this
+        // dispatch's own outcome unknown.
+        let receiptMismatch = false;
         const observedCompaction = sameScope && (adapter.contractCompactionSequence?.() ?? 0) > compactionBefore && after.generation >= before.generation;
         if (turn.structured?.state === "candidate" && (turn.structured.profile !== wireContract.profile || turn.structured.wireContractDigest !== wireContract.descriptorDigest ||
             turn.structured.wireSchemaDigest !== wireContract.wireSchemaDigest || turn.structured.wireVariant !== wireContract.variant || turn.structured.dispatchId !== key || turn.structured.sessionId !== adapter.sessionId() ||
             before && (!sameScope || !observedCompaction && (before.sessionId !== after.sessionId || before.generation !== after.generation)))) {
             turn = { ...turn, selectedDispatch: tuple, isError: true, structured: { state: "rejected", reason: "invalid-contract", detail: "Dispatch/session/generation receipt mismatch", dispatchId: key } };
+            receiptMismatch = true;
         }
         // Exact raw provider material is retained once in the evidence store. The
         // journal only carries the digest/reference and validation fact, so it
         // cannot become a second, differently-redacted copy of the provider turn.
         turn = { ...turn, selectedDispatch: tuple };
         let receiptValidated = false;
+        let requirementRejected = false;
         if (turn.structured?.state === "rejected")
             turn = { ...turn, isError: true };
         else if (!turn.isError && !turn.failure) {
@@ -179,7 +188,13 @@ export async function journalStructuredDispatch(root, adapter, instruction, poli
                 const response = verifyPersistedDispatch(policy.output, db.structuredOwnerDispatch(key), turn.structured, tuple);
                 // A response that cannot satisfy host requirements is rejected before
                 // confirmation instead of failing in postprocessing after it.
-                requirement?.validate(response);
+                try {
+                    requirement?.validate(response);
+                }
+                catch (error) {
+                    requirementRejected = true;
+                    throw error;
+                }
                 receiptValidated = true;
             }
             catch (error) {
@@ -210,13 +225,20 @@ export async function journalStructuredDispatch(root, adapter, instruction, poli
         const rawDigest = db.putEvidence("handoff", retainedRaw);
         const responseDigest = db.putEvidence("handoff", Buffer.from(JSON.stringify(retained)));
         db.recordCommunicationEvidenceRefs(key, [responseDigest, rawDigest, ...(retained.valueDigest ? [retained.valueDigest] : []), ...(retained.rejectedValue ? [retained.rejectedValue.evidenceDigest] : [])]);
-        const status = turn.failure?.dispatchState === "not-sent" ? "failed" : turn.failure?.dispatchState === "unknown" || !receiptValidated ? "uncertain" : "confirmed";
+        // A provider that finished its turn with a response that fails validation
+        // has a known outcome: the answer was rejected. Only a missing or
+        // interrupted turn leaves the outcome unknown.
+        // Only the answer's own content counts: a wire-schema violation or a failed
+        // host requirement. Binding and receipt failures stay unknown.
+        const answeredInvalid = !receiptValidated && !turn.failure && !receiptMismatch && turn.structured?.state === "rejected" && turn.structured.reason === "invalid-contract"
+            && (requirementRejected || turn.structured.detail.includes("Structured result violates wire schema"));
+        const status = turn.failure?.dispatchState === "not-sent" || answeredInvalid ? "failed" : turn.failure?.dispatchState === "unknown" || !receiptValidated ? "uncertain" : "confirmed";
         turn = { ...turn, transportEvidence: { rawDigest, responseDigest, rawBytes: raw.length, retainedRawBytes: retainedRaw.length,
                 valueDigest: retained.valueDigest, rejectedValueDigest: retained.rejectedValue?.evidenceDigest } };
         db.atomic(() => {
             if (status === "confirmed" && adapter.postConfirmedDispatch)
                 db.requireStructuredPostprocessing(key, { instruction, policy: continuationPolicy(selected, key) });
-            db.updateOperation(key, status, { result: { responseDigest, rawDigest, rawBytes: raw.length, retainedRawBytes: retainedRaw.length, validation: receiptValidated ? "accepted" : turn.structured?.state ?? "missing-receipt", wireContractDigest: wireContract.descriptorDigest } });
+            db.updateOperation(key, status, { result: { responseDigest, rawDigest, rawBytes: raw.length, retainedRawBytes: retainedRaw.length, validation: receiptValidated ? "accepted" : turn.structured?.state ?? "missing-receipt", wireContractDigest: wireContract.descriptorDigest, ...(answeredInvalid ? { dispatchState: "answered-invalid" } : {}) } });
         });
         if (status === "confirmed" && adapter.postConfirmedDispatch) {
             try {

package/dist/ticketPlanning.d.ts

@@ -2,8 +2,6 @@ import type { TicketDef } from "./tickets/ticketSchema.js";
 import { type TicketStatus } from "./tickets/stateDb.js";
 import { type DeliveryConfig } from "./tickets/delivery.js";
 import { type TicketBuildSetupConfig } from "./tickets/setupConfig.js";
-export declare const PROPOSAL_START = "RAFI_PROPOSAL_START";
-export declare const PROPOSAL_END = "RAFI_PROPOSAL_END";
 export interface TicketEdit {
     id: string;
     patch: Partial<Omit<TicketDef, "id">>;
@@ -72,7 +70,6 @@ export { ticketPlanProposalV1Schema } from "rafi-spec";
 export declare function readTicketPlanningContext(projectDir: string): TicketPlanningContext;
 export declare function ticketPlanningFingerprint(projectDir: string): PlanningFingerprint[];
 export declare function planningFingerprintChanges(projectDir: string, expected: PlanningFingerprint[]): string[];
-export declare function extractTicketPlanProposal(output: string, existingTickets?: TicketDef[], context?: TicketPlanValidationContext): TicketPlanProposal;
 export declare function validateTicketPlanProposal(value: unknown, existingTickets?: TicketDef[], context?: TicketPlanValidationContext): string[];
 export interface ApplyTicketPlanOptions {
     expectedFingerprint: PlanningFingerprint[];

package/dist/ticketPlanning.js

@@ -11,8 +11,6 @@ import { runAllValidation } from "./tickets/validate.js";
 import { normalizeDeliveryConfig, validateDeliveryConfig } from "./tickets/delivery.js";
 import { loadTicketSetupConfig, mergeTicketSetup, saveTicketSetupConfig } from "./tickets/setupConfig.js";
 import { ticketPlanProposalV1Schema, zodIssues } from "rafi-spec";
-export const PROPOSAL_START = "RAFI_PROPOSAL_START";
-export const PROPOSAL_END = "RAFI_PROPOSAL_END";
 export { ticketPlanProposalV1Schema } from "rafi-spec";
 const TICKET_STATUSES = new Set([
     "planned", "next", "in_progress", "blocked", "done", "canceled", "obsolete",
@@ -46,27 +44,6 @@ export function ticketPlanningFingerprint(projectDir) {
 export function planningFingerprintChanges(projectDir, expected) {
     return expected.filter((item) => fileHash(join(projectDir, item.path)) !== item.sha256).map((item) => item.path);
 }
-export function extractTicketPlanProposal(output, existingTickets = [], context = {}) {
-    const start = output.lastIndexOf(PROPOSAL_START);
-    const end = output.lastIndexOf(PROPOSAL_END);
-    if (start < 0 || end <= start)
-        throw new Error(`planner output is missing ${PROPOSAL_START}/${PROPOSAL_END}`);
-    const raw = output.slice(start + PROPOSAL_START.length, end).trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "");
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch (err) {
-        throw new Error(`planner proposal is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    const contract = ticketPlanProposalV1Schema.safeParse(parsed);
-    if (!contract.success)
-        throw new Error(`planner proposal contract validation failed:\n${zodIssues(contract.error).map((issue) => `- ${issue}`).join("\n")}`);
-    const issues = validateTicketPlanProposal(contract.data, existingTickets, context);
-    if (issues.length)
-        throw new Error(`invalid planner proposal:\n${issues.map((issue) => `- ${issue}`).join("\n")}`);
-    return contract.data;
-}
 export function validateTicketPlanProposal(value, existingTickets = [], context = {}) {
     const issues = [];
     const contract = ticketPlanProposalV1Schema.safeParse(value);

package/dist/ticketPopulationPaging.js

@@ -6,10 +6,10 @@ import { assertTicketPopulationPageBinding, withTicketPopulationPage } from "./t
 /** Each provider page is sealed and durably appended before aggregate interpretation. */
 export async function streamTicketPopulation(input) {
     const runId = `ticket-population:${input.interviewId}`;
-    const artifactId = `${runId}:artifact:${input.correction}`;
     const db = new WorkflowDb(input.projectDir);
     try {
         db.enableStructuredCommunication();
+        const artifactId = restartableArtifactId(db, runId, `${runId}:artifact:${input.correction}`);
         const prior = db.operation(artifactId);
         if (prior) {
             const retained = prior.intent;
@@ -103,3 +103,25 @@ export async function streamTicketPopulation(input) {
         db.close();
     }
 }
+/**
+ * An earlier population attempt that never reached its terminal page (a bad
+ * answer, a provider crash or a stalled turn, or Rafi itself stopping) is
+ * retired with its unanswered page calls, and population restarts from its
+ * first page under a new lineage with the same instruction. A terminal
+ * lineage is kept so its retained pages can be replayed.
+ */
+function restartableArtifactId(db, runId, baseId) {
+    for (let restart = 0;; restart++) {
+        const artifactId = restart ? `${baseId}:restart-${restart}` : baseId;
+        const prior = db.operation(artifactId);
+        if (!prior || db.populationPageLedger(artifactId)?.state === "terminal")
+            return artifactId;
+        if (prior.status === "failed")
+            continue;
+        db.atomic(() => {
+            for (const dispatch of db.operations(runId).filter(op => op.kind === "provider-dispatch" && ["in_progress", "uncertain"].includes(op.status)))
+                db.updateOperation(dispatch.idempotencyKey, "failed", { result: { recovery: "population-restart", outcomeUnknown: true, providerReplayAuthorized: false, priorResult: dispatch.result }, error: "Unfinished ticket population page; population restarts from its first page" });
+            db.updateOperation(artifactId, "failed", { result: { recovery: "population-restart", priorResult: prior.result }, error: "Unfinished ticket population lineage retired; population restarts from its first page" });
+        });
+    }
+}

package/dist/workflowDb.d.ts

@@ -13,7 +13,10 @@ import type { QaDeliveryTurn, QaDeliveryOutcome, QaDeliveryInvocationV3 } from "
 import type { BranchResumeSession } from "./branch/resume.js";
 import { type BuilderRemediationReceiptV2, type BuilderRemediationReceiptV3, type FrozenQaSourceStateV2, type HandoffAcceptanceReceiptV2, type QaPassCertificateV2, type QaReducerEventV2, type QaReducerStateV2, type QaReportDisposition, type QaReviewBasisV2, type QaTurnIntentV2, type QaTurnReceiptV2 } from "./qaProtocolV2.js";
 export declare const WORKFLOW_DB_FILE = ".rafi/recovery.sqlite3";
-export type WorkflowKind = "plan" | "ticket-plan" | "ticket-populate" | "uninstall" | "build" | "qa-remediation" | "recovery" | "legacy";
+export type WorkflowKind = "plan" | "ticket-plan" | "ticket-populate" | "uninstall" | "build" | "qa-remediation" | "recovery" | "legacy" | "operation";
+/** Journal runs for agent calls outside a build use these run-id prefixes. */
+export declare const NON_BUILD_RUN_PREFIXES: readonly ["operation:", "ticket-population:", "qa-"];
+export declare function isNonBuildRunId(runId: string): boolean;
 export type WorkflowRunStatus = "running" | "paused" | "blocked" | "completed" | "failed" | "cancelled" | "superseded";
 export interface WorkflowRunSnapshot {
     runId: string;
@@ -419,6 +422,8 @@ export declare class WorkflowDb {
     humanDecisionKey(decisionId: string): string | undefined;
     humanDecision(decisionId: string): PendingHumanDecision | undefined;
     pendingHumanDecisions(runId: string): PendingHumanDecision[];
+    /** Answered decisions for a run, oldest first (e.g. answered with build:decide while no worker waited). */
+    answeredHumanDecisions(runId: string): PendingHumanDecision[];
     decisionContinuationAvailable(runId: string, decisionId: string): boolean;
     nextDecisionContinuationKey(runId: string, decisionId: string): string;
     answeredTicketDecisions(runId: string, scopeRevision: string): PendingHumanDecision[];
@@ -588,6 +593,16 @@ export declare class WorkflowDb {
      */
     enableStructuredCommunication(): void;
     beginQaTurn(intent: QaTurnIntentV2): void;
+    /** Retire this run's unresolved dispatches on a provider session the host
+     * has just closed after a failed call. The closed provider can no longer
+     * act, so the call's outcome is final: unknown, never replayed. */
+    retireClosedSessionDispatches(runId: string, sessionId: string | undefined, reason: string): string[];
+    /** Retire interrupted role turns that are not implementation or bound QA
+     * review work (for example build preflight, coverage, or handoff
+     * acceptance) so the step restarts from its beginning. Implementation and
+     * review turns keep their own recovery. The interrupted outcome stays unknown and is
+     * never replayed or treated as a result. Returns the retired dispatch IDs. */
+    reconcileInterruptedSteps(runId: string, role: "builder" | "qa"): string[];
     /** Retire an interrupted, proven read-only review transport, never a QA pass
      * or Builder remediation. A fresh immutable review must still run afterward. */
     reconcileInterruptedQaDispatch(runId: string, ticketId: string): boolean;

package/dist/workflowDb.js

@@ -1,3 +1,4 @@
+import { ensureLocalGitExcludes } from "./gitExclude.js";
 import { persistedProviderWireContract } from "rafi-spec";
 import { verifyCheckpointOrigin, verifyContinuityHeads } from "./continuityOrigin.js";
 import { registerQaGraphJournalWriter, ensureQaGraphJournalGuards } from "./qaDeliveryJournal.js";
@@ -22,7 +23,7 @@ import { admitWork, admittedWork, assertAdmittedWork } from "./buildWorkAdmissio
 import { cleanupReadiness, inspectReadiness, readinessMetadata } from "./readinessCleanup.js";
 import { originalBuildLease, rememberOriginalLease, forgetOriginalLease, registerLaunchChild, acknowledgeLaunchChild, reconcileLaunch, checkBuildOwnershipSchema, canonicalProject, launchDigest, localBuildAuthority, rememberBuildAuthority, forgetBuildAuthority, migrateBuildAdmission, acquireAdmission, readAdmission, assertAdmission, releaseAdmission, reserveLaunch, setLaunchState, claimLaunch, readLaunch } from "./buildAdmission.js";
 import { createHash, randomUUID } from "node:crypto";
-import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { hostname } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { execFileSync } from "node:child_process";
@@ -36,6 +37,22 @@ import { loadTickets } from "./tickets/ticketLoader.js";
 import { processGroupQuiescent, taggedProcesses, classifyProcess, processStartIdentity } from "./processIdentity.js";
 import { initialQaReducerState, qaDigest, reduceQaState, } from "./qaProtocolV2.js";
 export const WORKFLOW_DB_FILE = ".rafi/recovery.sqlite3";
+/** Role steps that change no project files, so an interrupted one can run
+ * again from its beginning with its original inputs. */
+// QA preparation runs in a disposable snapshot, so its steps are restartable too.
+const QA_PREPARATION_STEPS = ["qa-preparation-depth", "qa-preparation-draft", "qa-preparation-assessment", "qa-preparation-challenge"];
+const RESTARTABLE_STEPS = {
+    builder: new Set(["build-preflight", "session-initialization", "handoff-acceptance", "builder-coverage", "branch-dependency-audit", "qa-contract-acceptance", "qa-contract-segment", "status", "escalation", ...QA_PREPARATION_STEPS]),
+    qa: new Set(["session-initialization", "handoff-acceptance", "qa-recovery-acceptance", "qa-contract-acceptance", "qa-contract-segment", ...QA_PREPARATION_STEPS]),
+};
+/** Journal runs for agent calls outside a build use these run-id prefixes. */
+export const NON_BUILD_RUN_PREFIXES = ["operation:", "ticket-population:", "qa-"];
+export function isNonBuildRunId(runId) {
+    return NON_BUILD_RUN_PREFIXES.some(prefix => runId.startsWith(prefix));
+}
+function defaultRunKind(runId) {
+    return isNonBuildRunId(runId) ? "operation" : "build";
+}
 /** Read the current project lease without creating or migrating recovery state. */
 export function readCurrentWorkflowLease(projectDir) {
     const path = join(resolve(projectDir), WORKFLOW_DB_FILE);
@@ -440,7 +457,10 @@ export class WorkflowDb {
                 if (owner.state.pid && classifyProcess(owner.state.pid, owner.state.processStart).state !== "dead")
                     throw new Error(`supervisor already active for project (run ${owner.runId})`);
             }
-            const uncertain = this.db.prepare("SELECT run_id FROM operation_journal WHERE kind='provider-dispatch' AND status IN ('in_progress','uncertain') LIMIT 1").get();
+            // Single agent calls outside builds ("operation:<id>" runs: planning,
+            // ticket population, uninstall proposals) are read-only proposals; an
+            // unknown outcome there cannot conflict with a build.
+            const uncertain = this.db.prepare("SELECT run_id FROM operation_journal WHERE kind='provider-dispatch' AND status IN ('in_progress','uncertain') AND run_id NOT LIKE 'operation:%' AND run_id NOT LIKE 'ticket-population:%' AND run_id NOT LIKE 'qa-%' LIMIT 1").get();
             if (uncertain)
                 throw new Error(`Build ${uncertain.run_id} has unresolved provider dispatch; reconcile before another launch`);
             for (const row of this.db.prepare("SELECT DISTINCT run_id FROM build_owned_processes WHERE state<>'quiescent'").all()) {
@@ -465,7 +485,7 @@ export class WorkflowDb {
         return this.atomic(() => {
             this.assertExecutionProtocol();
             this.assertNoLegacyBuildOwner();
-            const otherDispatch = this.db.prepare("SELECT run_id FROM operation_journal WHERE run_id<>? AND kind='provider-dispatch' AND status IN ('in_progress','uncertain') LIMIT 1").get(runId);
+            const otherDispatch = this.db.prepare("SELECT run_id FROM operation_journal WHERE run_id<>? AND kind='provider-dispatch' AND status IN ('in_progress','uncertain') AND run_id NOT LIKE 'operation:%' AND run_id NOT LIKE 'ticket-population:%' AND run_id NOT LIKE 'qa-%' LIMIT 1").get(runId);
             if (otherDispatch)
                 throw new Error(`Build ${otherDispatch.run_id} has unresolved provider dispatch; reconcile before starting another recovery workflow`);
             const current = localBuildAuthority(this.projectDir);
@@ -827,7 +847,7 @@ export class WorkflowDb {
         return { eligible: reasons.length === 0, reasons };
     }
     /** Ensure non-workflow build records can use the same durable event store. */
-    ensureRun(runId, kind = "build", now = new Date()) {
+    ensureRun(runId, kind = defaultRunKind(runId), now = new Date()) {
         const existing = this.getRun(runId);
         if (existing)
             return existing;
@@ -1284,6 +1304,11 @@ export class WorkflowDb {
         return this.db.prepare("SELECT decision_json FROM human_decisions WHERE run_id=? AND status='pending' ORDER BY created_at").all(runId)
             .map((row) => parseJson(row.decision_json));
     }
+    /** Answered decisions for a run, oldest first (e.g. answered with build:decide while no worker waited). */
+    answeredHumanDecisions(runId) {
+        return this.db.prepare("SELECT decision_json FROM human_decisions WHERE run_id=? AND status='answered' ORDER BY created_at").all(runId)
+            .map((row) => parseJson(row.decision_json));
+    }
     decisionContinuationAvailable(runId, decisionId) {
         const prior = this.operations(runId).filter(op => op.kind === "decision-continuation" && op.intent.decisionId === decisionId);
         return prior.every(op => op.status === "failed" && op.result?.dispatchState === "not-sent");
@@ -2199,6 +2224,50 @@ export class WorkflowDb {
                 .run(intent.runId, intent.ticketId, intent.reviewNumber, intent.sessionGeneration, intent.slot, intent.operationId, at);
         })();
     }
+    /** Retire this run's unresolved dispatches on a provider session the host
+     * has just closed after a failed call. The closed provider can no longer
+     * act, so the call's outcome is final: unknown, never replayed. */
+    retireClosedSessionDispatches(runId, sessionId, reason) {
+        if (!sessionId)
+            return [];
+        const dispatches = [...this.unresolvedRoleDispatches(runId, "builder"), ...this.unresolvedRoleDispatches(runId, "qa")]
+            .filter(dispatch => dispatch.intent.sessionRef?.sessionId === sessionId);
+        this.atomic(() => {
+            for (const dispatch of dispatches)
+                this.updateOperation(dispatch.idempotencyKey, "failed", { result: { recovery: "provider-closed", outcomeUnknown: true, providerReplayAuthorized: false, priorResult: dispatch.result }, error: reason });
+        });
+        return dispatches.map(dispatch => dispatch.idempotencyKey);
+    }
+    /** Retire interrupted role turns that are not implementation or bound QA
+     * review work (for example build preflight, coverage, or handoff
+     * acceptance) so the step restarts from its beginning. Implementation and
+     * review turns keep their own recovery. The interrupted outcome stays unknown and is
+     * never replayed or treated as a result. Returns the retired dispatch IDs. */
+    reconcileInterruptedSteps(runId, role) {
+        // Only steps that are safe to run again from their beginning. Implementation
+        // turns, bound QA review turns and turns of unknown kind keep their own recovery.
+        const reviewTurn = this.db.prepare("SELECT 1 FROM qa_turns WHERE operation_id=?");
+        const dispatches = this.unresolvedRoleDispatches(runId, role).filter(dispatch => {
+            const operation = String(dispatch.intent.operation ?? "");
+            return RESTARTABLE_STEPS[role].has(operation) && (role === "builder" || !reviewTurn.get(dispatch.idempotencyKey));
+        });
+        if (!dispatches.length)
+            return [];
+        const lease = this.currentLease();
+        if (lease?.runId !== runId || lease.pid !== process.pid)
+            throw new Error("Step recovery requires the original build recovery lease");
+        const worker = this.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)
+            || this.readinessProcesses().length)
+            throw new Error("The interrupted step and all owned provider processes must be verified stopped before it restarts");
+        const reconciliationId = `${role}-step-restart:${runId}:${randomUUID()}`;
+        this.atomic(() => {
+            for (const dispatch of dispatches)
+                this.updateOperation(dispatch.idempotencyKey, "failed", { result: { recovery: "step-restart", reconciliationId, outcomeUnknown: true, providerReplayAuthorized: false, operation: dispatch.intent.operation ?? null, priorResult: dispatch.result }, error: "Interrupted step outcome remains unknown; the step restarts from its beginning with its original inputs" });
+            this.appendContinuityEvent({ runId, role: "host", kind: "interrupted_step_restarted", payload: { role, reconciliationId, dispatchIds: dispatches.map(dispatch => dispatch.idempotencyKey), outcomeUnknown: true, providerReplayAuthorized: false }, authoritativeStateRevision: this.continuityHead(runId, "run")?.authoritativeStateRevision ?? 0 });
+        });
+        return dispatches.map(dispatch => dispatch.idempotencyKey);
+    }
     /** Retire an interrupted, proven read-only review transport, never a QA pass
      * or Builder remediation. A fresh immutable review must still run afterward. */
     reconcileInterruptedQaDispatch(runId, ticketId) {
@@ -2225,17 +2294,20 @@ export class WorkflowDb {
         // A cancellation can have a durable host terminal receipt while the
         // provider dispatch is still unknown. Exact frozen-turn bindings remain
         // required; the old receipt is never promoted to an accepted QA result.
+        // A QA turn and its provider dispatch share one ID: the turn's operation ID
+        // is the dispatch's idempotency key. Instruction digests are not comparable
+        // across the two records (the dispatch hashes the full rendered provider
+        // instruction), so binding is by that shared ID.
+        // A host-completed turn is recoverable only when its dispatch recorded a
+        // typed unknown provider outcome.
         const rows = this.db.prepare("SELECT status,intent_json FROM qa_turns WHERE run_id=? AND ticket_id=? AND status IN ('intended','uncertain','unknown','completed')").all(runId, ticketId);
-        const turns = rows.flatMap(row => {
+        const turns = new Map(rows.flatMap(row => {
             const turn = parseJson(row.intent_json);
-            if (row.status === "completed" && !dispatches.some(dispatch => {
-                const result = dispatch.result;
-                return result?.isError === true && result.failure?.dispatchState === "unknown"
-                    && dispatch.intent.instructionDigest === turn.instructionDigest;
-            }))
+            const result = dispatches.find(dispatch => dispatch.idempotencyKey === turn.operationId)?.result;
+            if (row.status === "completed" && !(result?.isError === true && result.failure?.dispatchState === "unknown"))
                 return [];
-            return [turn];
-        });
+            return [[turn.operationId, turn]];
+        }));
         const bindings = dispatches.map(dispatch => {
             const intent = dispatch.intent;
             const ref = intent.sessionRef;
@@ -2243,9 +2315,10 @@ export class WorkflowDb {
                 || !ref.configRoot || canonicalProject(ref.configRoot) !== canonicalProject(this.projectDir) || !ref.validatedAt || Number.isNaN(Date.parse(ref.validatedAt))
                 || ref.source !== "observed" || providerSessionKey(ref) !== owner.sessionKey)
                 throw new Error("QA dispatch has no validated owner binding");
-            const turn = turns.find(turn => turn.reviewNumber === head.reviewNumber && turn.instructionDigest === intent.instructionDigest
-                && turn.providerSession.sessionId === ref.sessionId && turn.providerSession.provider === ref.provider && turn.providerSession.generation === ref.generation
-                && turn.providerSession.cwd === ref.cwd && turn.providerSession.configRoot === ref.configRoot);
+            const candidate = turns.get(dispatch.idempotencyKey);
+            const turn = candidate && candidate.reviewNumber === head.reviewNumber
+                && candidate.providerSession.sessionId === ref.sessionId && candidate.providerSession.provider === ref.provider && candidate.providerSession.generation === ref.generation
+                && candidate.providerSession.cwd === ref.cwd && candidate.providerSession.configRoot === ref.configRoot ? candidate : undefined;
             if (!turn || turn.sourceStateDigest !== head.sourceStateDigest || turn.reviewBasisDigest !== head.reviewBasisDigest)
                 throw new Error("QA dispatch does not match the frozen review turn");
             const sessions = this.db.prepare("SELECT session_json FROM qa_sessions WHERE run_id=? AND ticket_id=? AND generation=? AND source_state_digest=? AND review_basis_digest=?").all(runId, ticketId, ref.generation, turn.sourceStateDigest, turn.reviewBasisDigest);
@@ -3636,11 +3709,5 @@ function leaseVerifiedLive(lease, now, staleMs) {
     return classifyProcess(lease.pid, lease.processStart, lease.host).state !== "dead";
 }
 function ensureRecoveryGitignore(projectDir) {
-    const localExclude = join(projectDir, ".git", "info", "exclude");
-    const path = existsSync(localExclude) ? localExclude : join(projectDir, ".gitignore");
-    const entries = [WORKFLOW_DB_FILE, `${WORKFLOW_DB_FILE}-wal`, `${WORKFLOW_DB_FILE}-shm`, ".rafi/cache/handoffs/", ".rafi/backups/work-admission-v4/"];
-    const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
-    const missing = entries.filter((entry) => !existing.split(/\r?\n/).includes(entry));
-    if (missing.length)
-        appendFileSync(path, `${existing && !existing.endsWith("\n") ? "\n" : ""}${missing.join("\n")}\n`, "utf8");
+    ensureLocalGitExcludes(projectDir, [WORKFLOW_DB_FILE, `${WORKFLOW_DB_FILE}-wal`, `${WORKFLOW_DB_FILE}-shm`, ".rafi/cache/handoffs/", ".rafi/backups/work-admission-v4/"], { fallbackToGitignore: true });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-foreman",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "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",
@@ -93,6 +93,14 @@
       "types": "./dist/workflowReader.d.ts",
       "default": "./dist/workflowReader.js"
     },
+    "./recovery-owners.js": {
+      "types": "./dist/recoveryOwners.d.ts",
+      "default": "./dist/recoveryOwners.js"
+    },
+    "./runtime-preflight.js": {
+      "types": "./dist/runtimePreflight.d.ts",
+      "default": "./dist/runtimePreflight.js"
+    },
     "./process-identity.js": {
       "types": "./dist/processIdentity.d.ts",
       "default": "./dist/processIdentity.js"
@@ -319,8 +327,8 @@
     "luxon": "^3.7.2",
     "parse5": "7.2.1",
     "pdfjs-dist": "4.10.38",
-    "rafi-spec": "0.9.0",
-    "special-agents": "0.9.0",
+    "rafi-spec": "0.9.1",
+    "special-agents": "0.9.1",
     "yaml": "^2.5.1",
     "zod": "4.4.3"
   },