ai-foreman 2.0.0 → 2.0.1

package/dist/foreman.js

@@ -41,87 +41,6 @@ const QUESTION_HINTS = [
     "could you clarify",
     "which option",
 ];
-/**
- * Pull the STEP_STATUS marker out of a turn's final text.
- * Format: `STEP_STATUS: <kind> | key="value" key="value"`.
- */
-export function parseStepStatus(text, options = {}) {
-    const markerLines = text.split(/\r?\n/).filter((line) => /^\s*STEP_STATUS:/.test(line));
-    const markerCount = markerLines.length;
-    if (markerCount > 1) {
-        return { kind: "unknown", error: "builder emitted multiple STEP_STATUS markers" };
-    }
-    const lines = text.trimEnd().split(/\r?\n/).filter((line) => line.trim().length > 0);
-    const last = lines[lines.length - 1] ?? "";
-    if (!last.includes("STEP_STATUS:")) {
-        if (markerCount === 1 && options.requireFinalLine !== false) {
-            return { kind: "unknown", error: "STEP_STATUS marker was not the final non-empty line" };
-        }
-        if (markerCount === 0)
-            return { kind: "unknown" };
-    }
-    const marker = options.requireFinalLine === false ? markerLines[0]?.trim() ?? "" : last;
-    const match = marker.match(/^STEP_STATUS:\s*(done|blocked|plan_complete|needs_input|qa_pass|qa_fail)\b\s*(?:\|\s*(.*))?$/i);
-    if (!match) {
-        return { kind: "unknown", error: "malformed STEP_STATUS marker" };
-    }
-    const kind = match[1].toLowerCase();
-    const fields = parseMarkerFields(match[2] ?? "");
-    if (fields instanceof Error) {
-        return { kind: "unknown", error: fields.message };
-    }
-    return {
-        kind,
-        summary: fields.summary,
-        next: fields.next,
-        reason: fields.reason,
-        question: fields.question,
-        issues: fields.issues,
-        ticket: fields.ticket,
-        branchDependency: fields.branch_dependency,
-        choices: fields.choices
-            ? fields.choices.split("|").map((c) => c.trim()).filter(Boolean)
-            : undefined,
-    };
-}
-function parseMarkerFields(input) {
-    const fields = {};
-    let rest = input.trim();
-    while (rest.length > 0) {
-        const key = rest.match(/^(\w+)="/);
-        if (!key)
-            return new Error(`malformed STEP_STATUS field near: ${rest.slice(0, 40)}`);
-        const name = key[1];
-        let i = key[0].length;
-        let value = "";
-        let closed = false;
-        while (i < rest.length) {
-            const ch = rest[i];
-            if (ch === "\\") {
-                const next = rest[i + 1];
-                if (next === undefined)
-                    return new Error(`unterminated escape in STEP_STATUS field: ${name}`);
-                value += next;
-                i += 2;
-                continue;
-            }
-            if (ch === "\"") {
-                closed = true;
-                i++;
-                break;
-            }
-            value += ch;
-            i++;
-        }
-        if (!closed)
-            return new Error(`unterminated STEP_STATUS field: ${name}`);
-        if (fields[name] !== undefined)
-            return new Error(`duplicate STEP_STATUS field: ${name}`);
-        fields[name] = value;
-        rest = rest.slice(i).trim();
-    }
-    return fields;
-}
 /** Heuristic: did a marker-less turn end by asking the human something? */
 export function looksLikeQuestion(text) {
     const tail = text.trim().toLowerCase().slice(-400);
@@ -151,6 +70,17 @@ export function buildPrimer(n, trackerPath, ticketsEnabled = false, preferredTic
     const preferredTicketRule = preferredTicketId
         ? `\n- Resume and finish ticket ${preferredTicketId} first. Do not substitute a different queued ticket.`
         : "";
+    // With structured tickets the host assigns one whole ticket per step and QA
+    // reviews that ticket after the turn, so "step" must never mean a sub-task.
+    if (ticketsEnabled)
+        return `You are being run by an automated foreman. We will work through up to ${n} assigned tickets, one complete ticket per turn.
+
+Rules:
+- Implement the ENTIRE assigned ticket this turn: every acceptance criterion and required test. Do not split it into sub-steps across turns; independent QA reviews the whole ticket as soon as you report.
+- Return the result using the selected native JSON output contract.
+- If a tool action is denied by foreman policy, do not retry the denied form; report it using the blocked result. The one exception is a required test that you changed by adding a pipe, redirection, substitution, or wrapper: retry the exact required-test command without that extra shell syntax before reporting it blocked.${trackerRule}${preferredTicketRule}
+
+This is ticket 1 of up to ${n} in this batch. Implement the assigned ticket completely now.`;
     return `You are being run by an automated foreman. We will work through your next ${n} tickets or implementation steps, one per turn.
 
 Rules:
@@ -161,7 +91,9 @@ Rules:
 This is step 1 of ${n}. Implement the next ticket or step now.`;
 }
 /** Instruction sent on turns 2–N. */
-export function buildNextStepInstruction(i, n) {
+export function buildNextStepInstruction(i, n, ticketsEnabled = false) {
+    if (ticketsEnabled)
+        return `Implement the assigned ticket completely now — every acceptance criterion and required test, not a sub-step. This is ticket ${i} of up to ${n} in this batch; independent QA reviews the whole ticket when you report. Return the completed work-report through the selected native JSON contract.`;
     return `Implement the next ticket or step now (exactly one) — this is step ${i} of ${n}. Return the completed work-report through the selected native JSON contract.`;
 }
 /** QA review turn: ask the builder to triple-check the ticket or step it just completed. */
@@ -190,13 +122,15 @@ ${issues}
 Fix every one of them now. Submit the selected native remediation result so Foreman can rerun independent QA. Verify that your fixes resolve the reported issues.`;
 }
 /** Pre-flight planning turn: ask the builder to list its next N steps without implementing anything. */
-export function buildPlanningTurn(n, ticketsContent, preferredTicketId) {
+export function buildPlanningTurn(n, ticketsContent, preferredTicketId, ticketsEnabled = false) {
     const header = ticketsContent
         ? `Here is the project's ticket list:\n\n${ticketsContent}\n\n`
         : "";
     const preferred = preferredTicketId
         ? ` The first item must be ticket ${preferredTicketId}; this is an interrupted ticket being resumed.`
         : "";
+    if (ticketsEnabled)
+        return `${header}Before we begin, list up to ${n} ticket(s) you plan to implement, in dependency order, one entry per complete ticket.${preferred} Never split one ticket into several entries; each entry is implemented and independently reviewed as a whole ticket. A ticket whose dependencies are earlier entries in your list may be included. List fewer than ${n} if fewer can be built. Do not implement anything yet; return the ordered tickets through the build-preflight response.`;
     return `${header}Before we begin, list the next ${n} ticket(s) or step(s) you plan to implement, in order.${preferred} Be specific — reference ticket IDs or titles where applicable. Do not implement anything yet; return the ordered steps through the build-preflight response.`;
 }
 /** Builds the permission callback: classify, log, allow or escalate. */
@@ -586,7 +520,7 @@ export class Foreman {
     /** Send a planning turn and return the builder's response text. Does not count toward steps. */
     async runPreflight(n, ticketsContent, preferredTicketId, executionTickets) {
         this.assertNotInterrupted();
-        const instruction = buildPlanningTurn(n, ticketsContent, preferredTicketId) + (executionTickets ? `\nAuthorized ticket scope: ${executionTickets.join(", ")}. Plan only these tickets. Tickets awaiting answers are not eligible for implementation.` : "");
+        const instruction = buildPlanningTurn(n, ticketsContent, preferredTicketId, this.ticketsEnabled) + (executionTickets ? `\nAuthorized ticket scope: ${executionTickets.join(", ")}. Plan only these tickets. Tickets awaiting answers are not eligible for implementation.` : "");
         if (this.beforeBuilderTurn)
             this.builder = await this.beforeBuilderTurn(this.builder, instruction);
         this.assertNotInterrupted();
@@ -1018,7 +952,7 @@ export class Foreman {
             // have no preflight still receive the primer for compatibility.
             let instruction = i === 1 && !this.preflightPlan
                 ? buildPrimer(n, trackerPath, this.ticketsEnabled, pendingTicketId)
-                : buildNextStepInstruction(i, n);
+                : buildNextStepInstruction(i, n, this.ticketsEnabled);
             if (pendingTicketId)
                 instruction += `\n\nAssigned ticket: ${pendingTicketId}. Implement exactly this ticket. Do not substitute another ticket. Return the native work report for this assigned ticket.`;
             const continuations = answered.filter(decision => decision.interruptionId === `ticket:${pendingTicketId}`);

package/dist/gitExclude.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Add missing ignore entries for Rafi's local state to a repository.
+ *
+ * Prefers the repository-local `.git/info/exclude`. A git template
+ * (`init.templateDir`) can install that file as a symlink to one shared
+ * file, so appending through it would add this project's entries to every
+ * repository using the template. Such a link is first replaced by a regular
+ * file with the same rules, keeping the change local to this repository.
+ *
+ * Without a local exclude file, entries go to `.gitignore` when
+ * `fallbackToGitignore` is set; otherwise nothing is written.
+ */
+export declare function ensureLocalGitExcludes(projectDir: string, entries: readonly string[], options?: {
+    fallbackToGitignore?: boolean;
+    leadingBlankLine?: boolean;
+}): void;

package/dist/gitExclude.js

@@ -0,0 +1,46 @@
+import { appendFileSync, existsSync, lstatSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Add missing ignore entries for Rafi's local state to a repository.
+ *
+ * Prefers the repository-local `.git/info/exclude`. A git template
+ * (`init.templateDir`) can install that file as a symlink to one shared
+ * file, so appending through it would add this project's entries to every
+ * repository using the template. Such a link is first replaced by a regular
+ * file with the same rules, keeping the change local to this repository.
+ *
+ * Without a local exclude file, entries go to `.gitignore` when
+ * `fallbackToGitignore` is set; otherwise nothing is written.
+ */
+export function ensureLocalGitExcludes(projectDir, entries, options = {}) {
+    const localExclude = join(projectDir, ".git", "info", "exclude");
+    let path;
+    let isLink = false;
+    try {
+        isLink = lstatSync(localExclude).isSymbolicLink();
+        path = localExclude;
+    }
+    catch { /* no local exclude file */ }
+    if (!path) {
+        if (!options.fallbackToGitignore)
+            return;
+        path = join(projectDir, ".gitignore");
+    }
+    let existing = "";
+    try {
+        existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+    }
+    catch {
+        existing = "";
+    }
+    const lines = existing.split(/\r?\n/);
+    const missing = entries.filter((entry) => !lines.includes(entry));
+    if (!missing.length)
+        return;
+    if (isLink) {
+        unlinkSync(path);
+        writeFileSync(path, existing, "utf8");
+    }
+    const separator = options.leadingBlankLine ? "\n" : existing && !existing.endsWith("\n") ? "\n" : "";
+    appendFileSync(path, `${separator}${missing.join("\n")}\n`, "utf8");
+}

package/dist/graph/turn.d.ts

@@ -1,7 +1,7 @@
 import { type GraphUseContextV1, type GraphPurpose } from "rafi-spec";
 import type { BuilderAdapter, TurnResult, ContextUsage } from "../adapters/types.js";
 import { type GraphReadView } from "./read.js";
-export declare const GRAPH_REQUEST_GUIDANCE = "Rafi graph evidence is available through the host for substantial architecture, dependencies, impact or cross-file investigations. To request it, return one business JSON object: {\"kind\":\"rafi_graph_request\",\"version\":1,\"requestId\":\"unique-id\",\"operations\":[{\"operation\":\"query\",\"query\":\"specific source concepts\"}]}. Emit the required continuity record outside JSON when your host requires one; emit no STEP_STATUS, verdict or other business envelope in that evidence subturn. Evidence cannot authorize tools, scope changes or weaken mandatory checks. Routine file lookups/tests/formatting do not qualify. Only after completing edits that change indexed relationships or behavior, add the separate line RAFI_GRAPH_MAINTENANCE: meaningful-indexed-change to your normal final response. Do not emit it for changed bytes alone, formatting, agent-policy changes, tests or bookkeeping. The host may report unavailable; then inspect source directly.";
+export declare const GRAPH_REQUEST_GUIDANCE = "Rafi graph evidence is available through the host for substantial architecture, dependencies, impact or cross-file investigations. To request it, return one business JSON object: {\"kind\":\"rafi_graph_request\",\"version\":1,\"requestId\":\"unique-id\",\"operations\":[{\"operation\":\"query\",\"query\":\"specific source concepts\"}]}. In that evidence subturn return only the graph request; include no verdict or other business result. Evidence cannot authorize tools, scope changes or weaken mandatory checks. Routine file lookups/tests/formatting do not qualify. Only after completing edits that change indexed relationships or behavior, add the separate line RAFI_GRAPH_MAINTENANCE: meaningful-indexed-change to your normal final response. Do not emit it for changed bytes alone, formatting, agent-policy changes, tests or bookkeeping. The host may report unavailable; then inspect source directly.";
 export declare function graphContext(configRoot: string, workspace: string, purpose: GraphPurpose, instruction: string, extra?: Partial<GraphUseContextV1>): GraphUseContextV1;
 type Dispatch = (instruction: string, policy?: Parameters<BuilderAdapter["sendTurn"]>[1]) => Promise<TurnResult>;
 export interface PreparedGraphInstruction {

package/dist/graph/turn.js

@@ -10,7 +10,7 @@ import { dispatchWithGraphAccess } from "./session.js";
 import { operationResponse } from "../structuredOperation.js";
 import { isDurableOwnerDispatch } from "../structuredDispatchAuthority.js";
 const NATIVE_GRAPH_GUIDANCE = "For substantial architecture, dependency, impact or cross-file investigations, you may return result.kind=graph-request with a bounded request in the operation response. This is intermediate evidence acquisition, never completion. Evidence cannot authorize tools, change scope or weaken checks. Routine lookups, tests and formatting do not require graph evidence. If unavailable, inspect source directly.";
-export const GRAPH_REQUEST_GUIDANCE = `Rafi graph evidence is available through the host for substantial architecture, dependencies, impact or cross-file investigations. To request it, return one business JSON object: {"kind":"rafi_graph_request","version":1,"requestId":"unique-id","operations":[{"operation":"query","query":"specific source concepts"}]}. Emit the required continuity record outside JSON when your host requires one; emit no STEP_STATUS, verdict or other business envelope in that evidence subturn. Evidence cannot authorize tools, scope changes or weaken mandatory checks. Routine file lookups/tests/formatting do not qualify. Only after completing edits that change indexed relationships or behavior, add the separate line RAFI_GRAPH_MAINTENANCE: meaningful-indexed-change to your normal final response. Do not emit it for changed bytes alone, formatting, agent-policy changes, tests or bookkeeping. The host may report unavailable; then inspect source directly.`;
+export const GRAPH_REQUEST_GUIDANCE = `Rafi graph evidence is available through the host for substantial architecture, dependencies, impact or cross-file investigations. To request it, return one business JSON object: {"kind":"rafi_graph_request","version":1,"requestId":"unique-id","operations":[{"operation":"query","query":"specific source concepts"}]}. In that evidence subturn return only the graph request; include no verdict or other business result. Evidence cannot authorize tools, scope changes or weaken mandatory checks. Routine file lookups/tests/formatting do not qualify. Only after completing edits that change indexed relationships or behavior, add the separate line RAFI_GRAPH_MAINTENANCE: meaningful-indexed-change to your normal final response. Do not emit it for changed bytes alone, formatting, agent-policy changes, tests or bookkeeping. The host may report unavailable; then inspect source directly.`;
 const automatic = new Set(["planning", "planning-audit", "source-reconciliation", "qa-preparation", "preparation-assessment", "preparation-challenge", "build-preflight", "branch-dependency-audit", "final-qa", "discovery", "ticket-population", "manager-diagnosis"]);
 export function graphContext(configRoot, workspace, purpose, instruction, extra = {}) {
     const id = randomUUID();

package/dist/handoffs.d.ts

@@ -2,8 +2,6 @@ import type { ContinuityDelta, HandoffAcceptanceReceiptV1, HandoffLineage, Hando
 import type { BuilderAdapter } from "./adapters/types.js";
 export declare const HANDOFF_CACHE_RETENTION_DAYS = 30;
 export declare const HANDOFF_ACCEPTED = "HANDOFF_ACCEPTED";
-export declare const HANDOFF_REQUEST_START = "RAFI_HANDOFF_REQUEST_START";
-export declare const HANDOFF_REQUEST_END = "RAFI_HANDOFF_REQUEST_END";
 export interface BuilderHandoffRequest {
     predecessorDispatchId?: string;
     version: 1;
@@ -11,7 +9,9 @@ export interface BuilderHandoffRequest {
     delta: ContinuityDelta;
     roleState: Record<string, unknown>;
 }
-export declare function parseBuilderHandoffRequest(text: string | BuilderHandoffRequest): BuilderHandoffRequest | undefined;
+/** Builder handoff requests arrive only as validated native proposals; plain
+ * provider text never requests a handoff. */
+export declare function parseBuilderHandoffRequest(request: string | BuilderHandoffRequest): BuilderHandoffRequest | undefined;
 export interface CreateHandoffInput {
     predecessorDispatchId?: string;
     runId: string;

package/dist/handoffs.js

@@ -3,7 +3,7 @@ import { durableHumanDecision } from "./humanDecision.js";
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, mkdtempSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { builderHandoffRequestV1Schema, parseProviderContract, handoffAcceptanceOutput, providerWireContract } from "rafi-spec";
+import { handoffAcceptanceOutput, providerWireContract } from "rafi-spec";
 import { BoundedTurnEvents, boundedUtf8, receiptFingerprint, rawFingerprint } from "./boundedTurnEvidence.js";
 import { mergeContinuityDeltas, validateContinuityDelta } from "./continuity.js";
 import { nativePolicy, operationInstruction, operationResponse } from "./structuredOperation.js";
@@ -12,8 +12,6 @@ import { pauseActivityForInput } from "./activity.js";
 import { signalAttention } from "./notify.js";
 export const HANDOFF_CACHE_RETENTION_DAYS = 30;
 export const HANDOFF_ACCEPTED = "HANDOFF_ACCEPTED";
-export const HANDOFF_REQUEST_START = "RAFI_HANDOFF_REQUEST_START";
-export const HANDOFF_REQUEST_END = "RAFI_HANDOFF_REQUEST_END";
 function handoffSessionIdentity(ref) {
     return JSON.stringify([ref.version, ref.provider, ref.sessionId, ref.role, ref.stream, ref.generation, resolve(ref.cwd), resolve(ref.configRoot), ref.workspaceIdentity, ref.ticketId, ref.deliveryUnitId]);
 }
@@ -42,35 +40,10 @@ async function collectHandoffTerminalEvents(adapter, turnId, maximumBytes) {
     void collect.catch(() => { });
     return events;
 }
-export function parseBuilderHandoffRequest(text) {
-    if (typeof text !== "string")
-        return text; // Already validated native handoff proposal.
-    const starts = [...text.matchAll(/RAFI_HANDOFF_REQUEST_START/g)];
-    const ends = [...text.matchAll(/RAFI_HANDOFF_REQUEST_END/g)];
-    if (starts.length === 0 && ends.length === 0)
-        return undefined;
-    if (starts.length !== 1 || ends.length !== 1 || starts[0].index >= ends[0].index)
-        throw new Error("malformed structured Builder handoff request envelope");
-    const raw = text.slice(starts[0].index + HANDOFF_REQUEST_START.length, ends[0].index).trim();
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        throw new Error("Builder handoff request is not valid JSON");
-    }
-    const contract = parseProviderContract(builderHandoffRequestV1Schema, parsed, "Builder handoff request");
-    return {
-        version: 1,
-        reason: clean(contract.reason, 2_000),
-        delta: {
-            version: 1,
-            decisions: contract.decisions, constraints: contract.constraints, discoveries: contract.discoveries,
-            completedActions: contract.completed_actions, evidence: contract.evidence, failures: contract.failures,
-            blockers: contract.blockers, openWork: contract.open_work, nextAction: contract.next_action,
-        },
-        roleState: sanitizeObject(contract.role_state),
-    };
+/** Builder handoff requests arrive only as validated native proposals; plain
+ * provider text never requests a handoff. */
+export function parseBuilderHandoffRequest(request) {
+    return typeof request === "string" ? undefined : request;
 }
 export class HandoffLoopError extends Error {
     runId;

package/dist/humanDecision.d.ts

@@ -1,3 +1,4 @@
+import { WorkflowDb } from "./workflowDb.js";
 import type { RunObserver } from "./observability.js";
 import type { HumanDecisionChoice } from "rafi-spec";
 export declare class HumanDecisionCancelled extends Error {
@@ -35,3 +36,9 @@ export declare function servicePendingHumanDecisions(input: {
     observer?: RunObserver;
     prompt?: (decision: import("rafi-spec").PendingHumanDecision, signal?: AbortSignal) => Promise<string | undefined>;
 }): Promise<boolean>;
+/**
+ * A capability question answered while no worker was waiting (rafi
+ * build:decide after a non-interactive exit) is reused once on resume rather
+ * than asked again. The answer that produced the previous grant is never reused.
+ */
+export declare function reusableCapabilityDecision(db: WorkflowDb, runId: string, prefix: string, consumedDecisionId?: string): string | undefined;

package/dist/humanDecision.js

@@ -200,3 +200,14 @@ export async function servicePendingHumanDecisions(input) {
         db.close();
     }
 }
+/**
+ * A capability question answered while no worker was waiting (rafi
+ * build:decide after a non-interactive exit) is reused once on resume rather
+ * than asked again. The answer that produced the previous grant is never reused.
+ */
+export function reusableCapabilityDecision(db, runId, prefix, consumedDecisionId) {
+    const pending = db.pendingHumanDecisions(runId).find(decision => decision.interruptionId.startsWith(prefix));
+    if (pending)
+        return pending.interruptionId;
+    return db.answeredHumanDecisions(runId).filter(decision => decision.interruptionId.startsWith(prefix) && decision.decisionId !== consumedDecisionId).at(-1)?.interruptionId;
+}

package/dist/observability.js

@@ -1,6 +1,7 @@
+import { ensureLocalGitExcludes } from "./gitExclude.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash, randomUUID } from "node:crypto";
-import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statfsSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statfsSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { gzipSync } from "node:zlib";
 import { hostname, loadavg } from "node:os";
 import { dirname, join, resolve, sep } from "node:path";
@@ -1005,11 +1006,5 @@ function unionMs(intervals) {
     return total + (start === undefined ? 0 : end - start);
 }
 function ensureObservabilityIgnore(projectDir) {
-    const localExclude = join(projectDir, ".git", "info", "exclude");
-    const path = existsSync(localExclude) ? localExclude : join(projectDir, ".gitignore");
-    const entries = [OBSERVABILITY_DB_FILE, `${OBSERVABILITY_DB_FILE}-wal`, `${OBSERVABILITY_DB_FILE}-shm`];
-    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, [OBSERVABILITY_DB_FILE, `${OBSERVABILITY_DB_FILE}-wal`, `${OBSERVABILITY_DB_FILE}-shm`], { fallbackToGitignore: true });
 }

package/dist/qaBuildGate.js

@@ -152,7 +152,7 @@ async function ensureBuilderContractWithProvenance(projectDir, runId, workId, wo
             : buildRun?.branchMode === "per-ticket"
                 ? "Host-owned delivery-mode fact: this admitted build uses isolated branch-per-ticket semantics. Verify branch/worktree identity when the contract requires it; do not infer it from the independent QA snapshot."
                 : "Host-owned delivery-mode fact: delivery mode was not available from the authoritative build record; do not invent branch-isolation requirements without an explicit approved requirement.";
-        const result = await prepareVerificationContract(initial, inventory, {
+        const runPreparation = () => prepareVerificationContract(initial, inventory, {
             provider: builder.agent,
             store, now: Date.now, hostFacts: `${qaHostGraphFact(projectDir)}\n${deliveryFact}\nHost-owned baseline fact: Rafi captured the complete preimplementation per-file path manifest and will perform the exact unchanged-file and scope comparison. Its digest is ${preimplementationPathManifestDigest}. Do not require the provider to receive or reproduce the raw manifest; cite the retained host-preimplementation-source observation and assess the host comparison result instead. Do not author a provider-executed check for Rafi's host postimplementation path manifest, complete changed-path inventory, or unchanged-file comparison; Rafi performs that comparison outside the provider snapshot. Ordinary approved product paths, exports, and tests are not a material QA concern merely because the provider cannot prove whether they were present before implementation; Rafi owns that comparison. Do not reconstruct or disclose the full baseline. For current-branch additive tickets, a provider-authored or inferred request to test the branch with an already-completed sibling feature removed is not an applicable requirement when the approved scope says not to remove or reconstruct that sibling; verify the ticket's own behavior and tests against the shared baseline instead. Treat sibling-absence testing as binding only when the user explicitly approved that absence requirement. Escalate only an actual host-observed out-of-scope, destructive, protected-file, or requirement-relevant change.`,
             normalizeDraft: (draft, response) => {
@@ -240,7 +240,9 @@ async function ensureBuilderContractWithProvenance(projectDir, runId, workId, wo
                         return { text: payload.text, structured: turn.structured, selectedDispatch: turn.selectedDispatch, output, graphReceiptRefs: turn.graphReceiptRefs, sessionId: role.builder.sessionId(), usage: { inputTokens: turn.usage?.scope === "turn-delta" ? turn.usage.inputTokens : turn.inputTokens, outputTokens: turn.usage?.scope === "turn-delta" ? turn.usage.outputTokens : turn.outputTokens, costUsd: turn.costAuthoritative ? turn.costUsd : undefined } };
                     }
                     finally {
+                        const closedSession = role.builder.sessionId();
                         await role.builder.close();
+                        db.retireClosedSessionDispatches(runId, closedSession ?? undefined, "Preparation planner session closed after its call ended; the phase restarts if needed");
                     }
                 }
                 const snapshot = await createDisposableQaSnapshotAsync(workspace);
@@ -265,15 +267,25 @@ async function ensureBuilderContractWithProvenance(projectDir, runId, workId, wo
                     return { text: payload.text, structured: turn.structured, selectedDispatch: turn.selectedDispatch, output, graphReceiptRefs: turn.graphReceiptRefs, sessionId: adapter.sessionId(), workspacePaths: mapSnapshotWorkingDirectories(operationPayload(turn, output), snapshot.path), usage: { inputTokens: turn.usage?.scope === "turn-delta" ? turn.usage.inputTokens : turn.inputTokens, outputTokens: turn.usage?.scope === "turn-delta" ? turn.usage.outputTokens : turn.outputTokens, costUsd: turn.costAuthoritative ? turn.costUsd : undefined } };
                 }
                 finally {
+                    const closedSession = adapter?.sessionId();
                     try {
                         await adapter?.close();
                     }
                     finally {
                         await snapshot.remove();
                     }
+                    db.retireClosedSessionDispatches(runId, closedSession ?? undefined, "Preparation QA session closed after its call ended; the phase restarts if needed");
                 }
             }),
         });
+        let result = await runPreparation();
+        // A failed or interrupted provider call restarts its preparation phase
+        // once automatically; budget limits and real concerns still stop here.
+        // Shadow mode only observes; its result is not used, so it is not retried.
+        if (policy.mode !== "shadow" && (result.status === "uncertain" || result.status === "incomplete" && /Preparation provider unavailable|planner-unavailable|Structured result violates|invalid-contract/i.test(result.detail))) {
+            console.log(`foreman: QA preparation call failed (${result.detail.slice(0, 160)}); restarting that preparation phase once.`);
+            result = await runPreparation();
+        }
         if (result.status !== "ready") {
             if (policy.mode === "shadow")
                 return "";

package/dist/qaPreparation.js

@@ -86,9 +86,13 @@ export async function prepareVerificationContract(initial, inventory, deps) {
     const decisionIssues = initial.depthDecision ? validateDepthDecision(initial.depthDecision) : ["Missing planner depth assessment"];
     // Missing decisions begin with Standard's ceiling, never the synthetic Low placeholder.
     const budget = store.ensureBudget(initial.runId, initial.workId, initial.admissionDigest, decisionIssues.length ? 2 : initial.depthDecision.level, deps.now());
-    const unresolvedDispatch = budget.reservations.find(item => !item.resultDigest);
-    if (unresolvedDispatch)
-        return { status: "uncertain", detail: head.detail ?? `Uncertain preparation dispatch ${unresolvedDispatch.operationId}`, nextAction: "Reconcile retained provider receipt before retrying" };
+    // Preparation runs inside the build worker. A call still open when a new
+    // preparation starts belongs to an earlier, ended attempt (its provider was
+    // closed or its process is gone), so that phase restarts from the beginning.
+    if (budget.reservations.some(item => !item.resultDigest && !item.interruptedAt)) {
+        store.reconcileInterruptedReservations(budget, deps.now(), "preparation restarted after an interrupted provider call");
+        Object.assign(budget, store.budget(initial.runId, initial.workId, initial.admissionDigest));
+    }
     const retained = store.progress(budget, "draft");
     const priorAssessment = store.progress(budget, "assessment");
     const priorChallenge = store.progress(budget, "challenge");
@@ -98,14 +102,24 @@ export async function prepareVerificationContract(initial, inventory, deps) {
     let candidate = retained ? structuredClone(retained.candidate) : structuredClone(initial);
     if (retainedDepth)
         candidate.depthDecision = retainedDepth;
-    if (retained && canonicalContractJson(candidate.inputs) !== canonicalContractJson(initial.inputs))
-        return { status: "blocked", detail: "Retained draft inputs changed", nextAction: "Reconcile authoritative input changes" };
+    if (retained && canonicalContractJson(candidate.inputs) !== canonicalContractJson(initial.inputs)) {
+        const now = new Map(initial.inputs.map(input => [input.id, canonicalContractJson(input)]));
+        const changed = [...new Set([...candidate.inputs.filter(input => now.get(input.id) !== canonicalContractJson(input)).map(input => input.id), ...initial.inputs.filter(input => !candidate.inputs.some(prior => prior.id === input.id)).map(input => input.id)])];
+        // Only the pre-implementation source fingerprint moved (for example the
+        // host re-rendered its tracker while the build was stopped). Nothing has
+        // been implemented yet, so preparation restarts against current files.
+        if (changed.length === 1 && changed[0] === "preimplementation-source") {
+            store.restartDrafting(budget, deps.now(), "Pre-implementation source changed before implementation; preparation restarts against current files");
+            return prepareVerificationContract(initial, inventory, deps);
+        }
+        return { status: "blocked", detail: `Retained draft inputs changed: ${changed.join(", ") || "input order"}`, nextAction: "Reconcile authoritative input changes" };
+    }
     let correctionIssues = [];
     const run = async (phase, kind, instruction, resultId, artifact) => {
         const output = artifact ?? (phase === "planner" ? depthOutput : phase === "assess" ? assessmentOutput : phase === "challenge" ? challengeOutput : draftOutput);
         const effectivePhase = phase === "prepare" && correctionIssues.length > 0 ? "repair" : phase;
         if (phase === "assess")
-            instruction = `This is QA PREPARATION semantic assessment before Builder work, not final QA. Do not emit RAFI_QA_FAILURE_REPORT, RAFI_QA_COVERAGE, QA findings, or STEP_STATUS; return only the requested preparation-assessment result.\n\n${instruction}`;
+            instruction = `This is QA PREPARATION semantic assessment before Builder work, not final QA. Do not report QA findings; return only the requested preparation-assessment result.\n\n${instruction}`;
         if (phase === "prepare")
             instruction = `This is a fresh draft response. Use only check IDs declared in this response; do not copy allocated check IDs or baseline/coverage references from an earlier draft or correction attempt. Every check reference in prose, procedures, expected evidence, and mappings must use the exact check.id declared in this response; never use descriptive aliases such as qa-subtract-export. Rafi will allocate stable IDs after validating this response.\n\n${instruction}`;
         if (phase === "assess")
@@ -385,7 +399,7 @@ export async function prepareVerificationContract(initial, inventory, deps) {
     catch (error) {
         const detail = error instanceof Error ? error.message : String(error);
         const current = store.budget(initial.runId, initial.workId, initial.admissionDigest);
-        const status = current.reservations.some(reservation => !reservation.resultDigest) ? "uncertain" : "incomplete";
+        const status = current.reservations.some(reservation => !reservation.resultDigest && !reservation.interruptedAt) ? "uncertain" : "incomplete";
         store.setState(initial.runId, initial.workId, initial.admissionDigest, status, detail, store.head(initial.runId, initial.workId, initial.admissionDigest).generation);
         store.metric(initial.runId, initial.workId, initial.admissionDigest, `metric:preparation-failure:${current.id}:${current.reservations.length}`, "preparation-failure", { status: "blocked" });
         const failureDigest = createHash("sha256").update(JSON.stringify({ status, detail })).digest("hex");

package/dist/qaPreparationStore.d.ts

@@ -16,6 +16,7 @@ export interface LogicalPreparationBudget {
         kind: "planning" | "investigation" | "assessment" | "challenge" | "escalation" | "repair";
         resultId?: string;
         resultDigest?: string;
+        interruptedAt?: string;
     }>;
     usage: {
         inputTokens: number | null;
@@ -126,6 +127,12 @@ export declare class QaPreparationStore {
     budget(runId: string, workId: string, admissionDigest: string): LogicalPreparationBudget | undefined;
     ensureBudget(runId: string, workId: string, admissionDigest: string, level: QaPreparationLevel, nowMs: number): LogicalPreparationBudget;
     reserve(budget: LogicalPreparationBudget, operationId: string, kind: LogicalPreparationBudget["reservations"][number]["kind"], intent: unknown, nowMs: number, resultId?: string): void;
+    /** Close preparation calls that never returned a result. Only the current
+     * owner may call this, after the call that made them has ended (the
+     * provider was closed or the process that made it is gone). The phase runs
+     * again; the unknown outcome is never used as a result. Time the build
+     * spent stopped does not count against the preparation window. */
+    reconcileInterruptedReservations(budget: LogicalPreparationBudget, nowMs: number, reason: string): string[];
     retainResult(budget: LogicalPreparationBudget, operationId: string, result: unknown, usage?: Partial<LogicalPreparationBudget["usage"]>): string;
     reviseDepth(budget: LogicalPreparationBudget, decision: QaPreparationDepthDecisionV1): void;
     retainProgress(budget: LogicalPreparationBudget, stage: string, value: unknown): void;
@@ -134,6 +141,10 @@ export declare class QaPreparationStore {
         inputDigest: string;
         predecessorDigest: string;
     }): void;
+    /** Set aside retained drafting progress so preparation restarts from its
+     * beginning against current inputs. Earlier attempts no longer count
+     * against the allowances; their evidence stays retained. */
+    restartDrafting(budget: LogicalPreparationBudget, nowMs: number, reason: string): void;
     progress<T>(budget: LogicalPreparationBudget, stage: string): T | undefined;
     /** Explicit operator action against an answered, exactly scoped durable decision. */
     applyAnsweredExtensions(budget: LogicalPreparationBudget): void;

package/dist/qaPreparationStore.js

@@ -229,10 +229,11 @@ export class QaPreparationStore {
             const current = this.budget(budget.runId, budget.workId, budget.admissionDigest);
             if (nowMs >= current.deadlineMs)
                 throw new Error("Preparation budget exhausted; authorized operational extension required");
-            const unresolved = current.reservations.find(item => !item.resultDigest);
+            const unresolved = current.reservations.find(item => !item.resultDigest && !item.interruptedAt);
             if (unresolved)
                 throw new Error(`Uncertain preparation dispatch ${unresolved.operationId}; reconcile retained result before retry`);
-            const count = current.reservations.filter(item => item.kind === kind && (kind !== "repair" || item.resultId === resultId)).length;
+            // Interrupted attempts were never answered; they do not use the allowance.
+            const count = current.reservations.filter(item => !item.interruptedAt && item.kind === kind && (kind !== "repair" || item.resultId === resultId)).length;
             const maximum = current.caps?.[kind] ?? (kind === "planning" ? 1 : kind === "investigation" ? current.level <= 2 ? 2 : 3 : kind === "assessment" ? 3 : 2);
             if (count >= maximum)
                 throw new Error(`Preparation ${kind} allowance exhausted`);
@@ -241,6 +242,28 @@ export class QaPreparationStore {
             this.db.prepare("INSERT INTO qa_preparation_attempts VALUES(?,?,?,?,NULL)").run(operationId, current.id, "uncertain", this.protectedJson(intent));
         });
     }
+    /** Close preparation calls that never returned a result. Only the current
+     * owner may call this, after the call that made them has ended (the
+     * provider was closed or the process that made it is gone). The phase runs
+     * again; the unknown outcome is never used as a result. Time the build
+     * spent stopped does not count against the preparation window. */
+    reconcileInterruptedReservations(budget, nowMs, reason) {
+        this.assertOwner(budget.runId);
+        return this.atomic(() => {
+            const current = this.budget(budget.runId, budget.workId, budget.admissionDigest);
+            const open = current.reservations.filter(item => !item.resultDigest && !item.interruptedAt);
+            if (!open.length)
+                return [];
+            const at = new Date(nowMs).toISOString();
+            for (const item of open) {
+                item.interruptedAt = at;
+                this.db.prepare("UPDATE qa_preparation_attempts SET state='interrupted',result_json=? WHERE operation_id=?").run(this.protectedJson({ interruptedAt: at, reason }), item.operationId);
+            }
+            current.deadlineMs = Math.max(current.deadlineMs, nowMs + current.policy.wallTimeMs[current.level - 1]);
+            this.saveBudget(current);
+            return open.map(item => item.operationId);
+        });
+    }
     retainResult(budget, operationId, result, usage) {
         this.assertOwner(budget.runId);
         return this.atomic(() => {
@@ -296,7 +319,7 @@ export class QaPreparationStore {
             if (head.digest !== authority.predecessorDigest || !["ready", "amendment-required", "incomplete", "reconciling", "validating", "preparing"].includes(head.state) || !authority.reason.trim())
                 throw new Error("Amendment requires current predecessor and explicit input authority");
             const current = this.budget(budget.runId, budget.workId, budget.admissionDigest);
-            if (current.reservations.some(item => !item.resultDigest))
+            if (current.reservations.some(item => !item.resultDigest && !item.interruptedAt))
                 throw new Error("Uncertain preparation dispatch requires reconciliation before another input amendment");
             const priorInventory = this.progress(budget, "inventory");
             this.putArtifact("amendment-intent", { budgetId: budget.id, priorInventory, inventory, authority });
@@ -306,6 +329,23 @@ export class QaPreparationStore {
             this.setState(budget.runId, budget.workId, budget.admissionDigest, "reconciling", authority.reason, head.generation);
         });
     }
+    /** Set aside retained drafting progress so preparation restarts from its
+     * beginning against current inputs. Earlier attempts no longer count
+     * against the allowances; their evidence stays retained. */
+    restartDrafting(budget, nowMs, reason) {
+        this.assertOwner(budget.runId);
+        this.atomic(() => {
+            const current = this.budget(budget.runId, budget.workId, budget.admissionDigest);
+            const at = new Date(nowMs).toISOString();
+            for (const item of current.reservations)
+                if (!item.interruptedAt)
+                    item.interruptedAt = at;
+            current.deadlineMs = Math.max(current.deadlineMs, nowMs + current.policy.wallTimeMs[current.level - 1]);
+            this.saveBudget(current);
+            this.db.prepare("DELETE FROM qa_preparation_progress WHERE budget_id=? AND stage IN ('draft','assessment','challenge')").run(current.id);
+            this.event(current.runId, current.workId, `restart-drafting:${current.id}:${at}`, "preparation-restarted", { reason });
+        });
+    }
     progress(budget, stage) {
         const row = this.db.prepare("SELECT digest FROM qa_preparation_progress WHERE budget_id=? AND stage=?").get(budget.id, stage);
         return row ? this.artifact(row.digest, `progress-${stage}`) : undefined;
@@ -408,7 +448,7 @@ export class QaPreparationStore {
                 throw new Error(issues.join("; "));
             const head = this.head(contract.runId, contract.workId, contract.admissionDigest);
             const budget = this.budget(contract.runId, contract.workId, contract.admissionDigest);
-            if (!budget || nowMs >= budget.deadlineMs || budget.reservations.some(item => !item.resultDigest))
+            if (!budget || nowMs >= budget.deadlineMs || budget.reservations.some(item => !item.resultDigest && !item.interruptedAt))
                 throw new Error("Expired or uncertain preparation cannot publish ready");
             if (head.generation !== expectedGeneration || contract.predecessorDigest !== (head.digest ?? undefined) || contract.revision !== (head.digest ? this.contract(head.digest).revision + 1 : 1))
                 throw new Error("Stale contract revision/publication");

package/dist/qaRecovery.d.ts

@@ -151,9 +151,6 @@ export declare function materializeQaRecoveryContext(packet: QaRecoveryPacket, q
     verify(): void;
 };
 export declare function renderQaRecoveryAcknowledgementInstruction(packet: QaRecoveryPacket, relativePath: string): string;
-export declare function validateQaRecoveryAcknowledgement(text: string, packet: QaRecoveryPacket, options?: {
-    continuityAlreadyValidated?: boolean;
-}): string[];
 export declare function qaRecoveryInventory(packet: QaRecoveryPacket): string;
 export declare function qaReportDigest(report: QaFailureReportV1): string;
 export declare function ensureQaRecoveryExcluded(projectDir: string): void;