ai-foreman 2.0.0 → 2.0.1

package/dist/qaRecovery.js

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { execFileSync } from "node:child_process";
 import { chmodSync, closeSync, cpSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readlinkSync, readdirSync, realpathSync, renameSync, writeFileSync, } from "node:fs";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
-import { parseProviderContract, parseStrictJson, validateQaFailureReport, QA_FAILURE_REPORT_MAX_BYTES, qaRecoveryAcknowledgementV1Schema } from "rafi-spec";
+import { parseStrictJson, validateQaFailureReport, QA_FAILURE_REPORT_MAX_BYTES } from "rafi-spec";
 import { calculateFrozenQaStateDigest, captureFrozenQaSource } from "./qaSnapshot.js";
 import { WorkflowDb } from "./workflowDb.js";
 export const QA_RECOVERY_ROOT = ".foreman/qa-report-recovery";
@@ -520,29 +520,6 @@ export function renderQaRecoveryAcknowledgementInstruction(packet, relativePath)
         JSON.stringify({ packet: packet.manifest.packetDigest, reviewed_state: packet.manifest.reviewedStateDigest, required_resources_read: "all" }),
     ].join("\n");
 }
-export function validateQaRecoveryAcknowledgement(text, packet, options = {}) {
-    const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
-    const expected = `RAFI_QA_RECOVERY_ACK packet="${packet.manifest.packetDigest}" reviewed_state="${packet.manifest.reviewedStateDigest}" required_resources_read="all"`;
-    const errors = [];
-    if (lines[0] !== expected)
-        errors.push("missing or malformed exact recovery-packet acknowledgement");
-    const acknowledgement = /^RAFI_QA_RECOVERY_ACK packet="([a-f0-9]{64})" reviewed_state="([a-f0-9]{64})" required_resources_read="(all)"$/.exec(lines[0] ?? "");
-    if (acknowledgement) {
-        try {
-            parseProviderContract(qaRecoveryAcknowledgementV1Schema, { packet: acknowledgement[1], reviewed_state: acknowledgement[2], required_resources_read: acknowledgement[3] }, "RAFI_QA_RECOVERY_ACK");
-        }
-        catch (error) {
-            errors.push(error instanceof Error ? error.message : String(error));
-        }
-    }
-    if (options.continuityAlreadyValidated) {
-        if (lines.length !== 1)
-            errors.push("recovery acknowledgement must not contain additional text");
-    }
-    else if (lines.length !== 2 || !/^RAFI_CONTINUITY_DELTA(?:\s|$)/.test(lines[1] ?? ""))
-        errors.push("exactly one continuity record must follow the recovery acknowledgement");
-    return errors;
-}
 export function qaRecoveryInventory(packet) {
     return packet.manifest.resources.map((resource) => `${resource.path}\t${resource.purpose}\t${resource.mediaType}\t${resource.bytes}\t${resource.digest}\t${resource.integrityPolicy}`).join("\n");
 }

package/dist/qaReview.js

@@ -1,6 +1,5 @@
-import { describeLegacyQaTranscript } from "./legacyCommunicationDisplay.js";
 import { BoundedTurnEvents, boundedUtf8, receiptFingerprint } from "./boundedTurnEvidence.js";
-import { qaStructuredResponse, qaStructuredStatus } from "./qaStructuredResponse.js";
+import { describeNativeQaResponse, qaStructuredResponse, qaStructuredStatus } from "./qaStructuredResponse.js";
 import { journalStructuredDispatch, operationInstruction, operationPayload, operationResponse, nativePolicy } from "./structuredOperation.js";
 import { durableOwnerDispatch } from "./structuredDispatchAuthority.js";
 import { providerWireContract, qaVerdictOutput, qaRecoveryOutput, initializationOutput, remediationOutput } from "rafi-spec";
@@ -19,10 +18,10 @@ import { formatRecoveryCommand } from "./recoveryGuidance.js";
 import { assertBuildAssignmentReconciled, BuildAssignmentRejected, captureBuildSource } from "./buildAssignment.js";
 import { checkQaPrerequisites } from "./qaPrerequisites.js";
 import { boundedQaHistory } from "./qaHandbackHistory.js";
-import { QA_FAILURE_REPORT_END, QA_FAILURE_REPORT_START, qaFailureReportV1Schema, } from "rafi-spec";
+import { qaFailureReportV1Schema, } from "rafi-spec";
 import { SessionUnavailableError } from "./adapters/sessionFailure.js";
 import { currentActivity, withActivityPhase } from "./activity.js";
-import { buildQaInstruction, parseStepStatus } from "./foreman.js";
+import { buildQaInstruction } from "./foreman.js";
 import { captureFrozenQaSourceAsync, captureProspectiveGitTree, createDisposableQaSnapshotAsync, prospectiveGitTreeMatches, QaSourceInstabilityError } from "./qaSnapshot.js";
 import { loadTicketSetupConfigWithDefaults } from "./tickets/setupConfig.js";
 import { randomUUID } from "node:crypto";
@@ -84,6 +83,9 @@ function pauseQaReview(opts, stage, detail, frozenState) {
  * The allowance is shared by all protocol failures for this ticket and survives restart.
  * oneReview's finally closes the predecessor before the loop allocates a new snapshot.
  */
+/** Frozen source of the review an automatic fresh retry replaces, so a retry
+ * that cannot be dispatched safely still pauses at that exact boundary. */
+const freshRetryState = new WeakMap();
 function retryFreshQaReview(opts, stage, detail, frozenState) {
     const db = new WorkflowDb(opts.recovery.projectDir);
     let retry = false;
@@ -102,6 +104,7 @@ function retryFreshQaReview(opts, stage, detail, frozenState) {
     }
     if (!retry)
         return pauseQaReview(opts, stage, `${detail}; automatic fresh QA review allowance exhausted`, frozenState);
+    freshRetryState.set(opts, frozenState);
     opts.resumedRecovery = undefined;
     currentActivity()?.update("qa-recovery", `${opts.ticket.id}: ${detail}. Running a complete fresh QA review.`);
     opts.evidence?.({ cycle: 0, outcome: "qa_fresh_review_retry", detail });
@@ -366,7 +369,18 @@ async function runIsolatedQaOwned(opts) {
         opts.qaHistory = [...history];
         reviewAttempt += 1;
         const attemptId = randomUUID();
-        const review = await withActivityPhase(`running QA review ${cycle} (${automaticFixes}/${maxBuilderFixes} fixes used)`, () => observedQaReview(opts, { cycle, reviewAttempt, remediationGeneration, attemptId }));
+        let review;
+        try {
+            review = await withActivityPhase(`running QA review ${cycle} (${automaticFixes}/${maxBuilderFixes} fixes used)`, () => observedQaReview(opts, { cycle, reviewAttempt, remediationGeneration, attemptId }));
+        }
+        catch (error) {
+            // An automatic fresh review that graph-access revocation blocks before
+            // dispatch pauses safely instead of failing the build.
+            const frozen = freshRetryState.get(opts);
+            if (frozen && /Graph access changed/.test(String(error)))
+                return pauseQaReview(opts, "graph-access-changed", String(error).replace(/^Error: /, ""), frozen);
+            throw error;
+        }
         if (review.outcome === "retry-modification") {
             const durableFixes = persistedQaFixCount(opts);
             cycle += Math.max(0, durableFixes - automaticFixes);
@@ -898,8 +912,8 @@ async function oneReview(opts, identity) {
             return pauseQaReview(opts, "invalid-continuity", `QA continuity record was invalid: ${turn.continuityErrors.join("; ")}`, reviewedSnapshot.frozenState);
         if (!responseContract.valid && !turn.failure) {
             const retained = resumedPacket
-                ? await retainInvalidResumedResponse(opts, identity, resumedPacket, snapshot, turn, responseContract.errors, qaEvents)
-                : await retainInvalidQaResponse(opts, identity, snapshot, qa, qaHandle, handoff, turn, responseContract.errors, qaEvents);
+                ? await retainInvalidResumedResponse(opts, identity, resumedPacket, snapshot, turn, responseContract.errors, qaEvents, true)
+                : await retainInvalidQaResponse(opts, identity, snapshot, qa, qaHandle, handoff, turn, responseContract.errors, qaEvents, true);
             return retained.result;
         }
         if (turn.isError || turn.failure)
@@ -990,7 +1004,7 @@ function finishDurableQaReview(opts, attemptId, patch) {
 function qaFindingRefs(runId, ticketId, reviewAttemptId, reportDigest, rawFindingIds) {
     return createQaFindingRefs({ runId, ticketId, reviewAttemptId, reportDigest, rawFindingIds });
 }
-async function retainInvalidResumedResponse(opts, identity, initialPacket, snapshot, originalTurn, originalErrors, qaEvents) {
+async function retainInvalidResumedResponse(opts, identity, initialPacket, snapshot, originalTurn, originalErrors, qaEvents, retryFresh = false) {
     const originalResponse = effectiveTurnText(originalTurn);
     let packet = appendQaRecoveryResource(initialPacket, `qa-responses/resumed-${identity.attemptId}.txt`, originalResponse, {
         purpose: "Exact first cleaned QA report response after resumed packet acknowledgement", exact: true,
@@ -998,9 +1012,10 @@ async function retainInvalidResumedResponse(opts, identity, initialPacket, snaps
     await awaitQaTurnEvent(qaEvents, originalTurn);
     packet = await appendTurnObservation(packet, `resumed-original-${identity.attemptId}`, originalTurn, originalTurn.hostInstruction, originalErrors, "resumed-fail-closed", qaEvents);
     packet = appendQaRecoveryResource(packet, `validation/resumed-${identity.attemptId}.json`, {
-        status: parseStepStatus(originalResponse), errors: originalErrors, recoveryStage: "resumed-fail-closed",
+        status: describeNativeQaResponse(originalResponse).status, errors: originalErrors, recoveryStage: "resumed-fail-closed",
     }, { purpose: "Validation result for the first resumed QA report response" });
-    return { outcome: "failed", result: pauseQaReview(opts, "resumed-invalid-contract", `Resumed QA response failed validation. Evidence retained at ${packet.directory}. ${originalErrors.map(error => sanitizePreview(error)).join("; ")}`, snapshot.frozenState) };
+    const resumedDetail = `Resumed QA response failed validation. Evidence retained at ${packet.directory}. ${originalErrors.map(error => sanitizePreview(error)).join("; ")}`;
+    return { outcome: "failed", result: retryFresh ? retryFreshQaReview(opts, "resumed-invalid-contract", resumedDetail, snapshot.frozenState) : pauseQaReview(opts, "resumed-invalid-contract", resumedDetail, snapshot.frozenState) };
 }
 export function buildQaReviewHandoff(ticket, builderSummary, diffDigest, validationChecklist, changeSummary, history = []) {
     return [
@@ -1011,7 +1026,7 @@ export function buildQaReviewHandoff(ticket, builderSummary, diffDigest, validat
         `Prior authoritative QA/report and Builder-remediation history: ${history.length ? JSON.stringify(boundedQaHistory(history)) : "(none; perform a complete first review)"}`,
         `Failure report JSON Schema: ${JSON.stringify(qaFailureReportV1Schema)}`,
         QA_COMMAND_DISCIPLINE,
-        "Submit the native qa-verdict payload. A failed verdict must include the complete failure report; a passed verdict must include all required coverage claims.",
+        "Submit the native qa-verdict payload. Every verdict, passed or failed, includes coverage and verifiedInstructionIds. Coverage holds the required coverage claims when a verification contract exists; otherwise it is null. A failed verdict also includes the complete failure report.",
         "Be very thorough. Don't leave anything out. Make sure all required fields are added. Triple check your work to ensure nothing is left out and all required fields are added and populated correctly.",
         "Do not change source, configuration, documentation, tickets, or control files. Only ignored cache, coverage, and build output is allowed.",
     ].join("\n");
@@ -1032,7 +1047,7 @@ export async function compactWithRetry(adapter) {
 export const QA_REPORT_RECOVERY_MENU = [
     "Try a complete fresh QA review.", "Manually fix saved JSON for human inspection.", "Give QA specific instructions for a fresh review.", "Pause.",
 ];
-async function retainInvalidQaResponse(opts, identity, snapshot, originalQa, qaHandle, reviewPrompt, originalTurn, originalErrors, qaEvents) {
+async function retainInvalidQaResponse(opts, identity, snapshot, originalQa, qaHandle, reviewPrompt, originalTurn, originalErrors, qaEvents, retryFresh = false) {
     const originalResponse = effectiveTurnText(originalTurn);
     const runId = opts.recovery?.runId ?? `volatile-${identity.attemptId}`;
     const continuity = qaContinuityRecoveryContext(opts);
@@ -1041,7 +1056,7 @@ async function retainInvalidQaResponse(opts, identity, snapshot, originalQa, qaH
         projectDir: opts.recovery?.projectDir ?? opts.builderWorktree, frozenState: snapshot.frozenState,
         runId, ticketId: opts.ticket.id, cycle: identity.cycle, reviewAttempt: identity.reviewAttempt,
         reviewAttemptId: identity.attemptId,
-        recoveryStage: "same-session", correctionTurns: 0, reportJson: extractReportBody(originalResponse),
+        recoveryStage: "same-session", correctionTurns: 0, reportJson: describeNativeQaResponse(originalResponse).reportJson ?? "{}\n",
         resources: {
             ticket: { value: opts.ticket, purpose: "Complete authoritative ticket definition" },
             "qa-review-prompt": { value: reviewPrompt, purpose: "Exact original QA review instruction", exactText: true },
@@ -1052,7 +1067,7 @@ async function retainInvalidQaResponse(opts, identity, snapshot, originalQa, qaH
             "original-provider-prompt": { value: originalTurn.providerInstruction ?? { unavailable: "adapter did not expose provider-dispatched instruction" }, purpose: "Exact provider-dispatched original QA instruction or explicit unavailable marker", exactText: typeof originalTurn.providerInstruction === "string" },
             "original-raw-response": { value: originalTurn.transportEvidence ?? { unavailable: true }, purpose: "Retained bounded transport references" },
             "original-cleaned-response": { value: originalTurn.transportEvidence ?? { unavailable: true }, purpose: "Retained bounded cleaned evidence references" },
-            "original-validation": { value: { errors: originalErrors, parsedStatus: parseStepStatus(originalResponse), responseBytes: Buffer.byteLength(originalResponse), turn: turnMetadata(originalTurn) }, purpose: "Parsed status, validator result, and complete host-observable turn metadata" },
+            "original-validation": { value: { errors: originalErrors, parsedStatus: describeNativeQaResponse(originalResponse).status, responseBytes: Buffer.byteLength(originalResponse), turn: turnMetadata(originalTurn) }, purpose: "Parsed status, validator result, and complete host-observable turn metadata" },
             "qa-history": { value: opts.qaHistory ?? [], purpose: "Earlier valid reports, observations, fixes, and unresolved history" },
             "tool-events": { value: qaEvents instanceof BoundedTurnEvents ? qaEvents.metadata() : { unavailable: true }, purpose: "All QA tool/activity events available through BuilderEvent, or an explicit unavailable marker" },
             continuity: { value: continuity, purpose: "Cumulative continuity checkpoints, later host facts, handoff lineage, and recovery history" },
@@ -1072,10 +1087,11 @@ async function retainInvalidQaResponse(opts, identity, snapshot, originalQa, qaH
     }
     let packet = existingPacket ? appendQaRecoveryAttempt(existingPacket, packetInput) : createQaRecoveryPacket(packetInput);
     packet = appendQaRecoveryResource(packet, "qa-responses/native-receipt.json", originalTurn.structured ?? { unavailable: true }, { purpose: "Original native provider receipt retained without changing or repeating completed QA work" });
-    return { outcome: "failed", result: pauseQaReview(opts, "invalid-native-qa-response", `QA response failed validation. Evidence retained at ${packet.directory}. ${originalErrors.join("; ")}`, snapshot.frozenState) };
+    const invalidDetail = `QA response failed validation. Evidence retained at ${packet.directory}. ${originalErrors.join("; ")}`;
+    return { outcome: "failed", result: retryFresh ? retryFreshQaReview(opts, "invalid-native-qa-response", invalidDetail, snapshot.frozenState) : pauseQaReview(opts, "invalid-native-qa-response", invalidDetail, snapshot.frozenState) };
 }
 async function exhausted(packet, originalResponse, opts, prefix = "QA review requires an explicit recovery decision", qa, snapshot, liveSession = Boolean(qa), unavailableOperatorReason, requireFreshReviewReason) {
-    const synopsis = describeLegacyQaTranscript(originalResponse).issues?.trim();
+    const synopsis = describeNativeQaResponse(originalResponse).issues?.trim();
     let currentPrefix = prefix;
     if (packet.manifest.pendingAction !== "operator-menu") {
         packet = updateQaRecoveryPosition(packet, "operator-menu", packet.manifest.correctionTurns, "operator-menu");
@@ -1138,12 +1154,6 @@ function normalizeUnsupportedOperator(result, reason) {
         ? { outcome: "failed", result: { outcome: "needs-human", detail: `Requested QA recovery route is unavailable because ${reason}` } }
         : result;
 }
-function extractReportBody(text) {
-    const start = text.split(/\r?\n/).findIndex((line) => line.trim() === QA_FAILURE_REPORT_START);
-    const lines = text.split(/\r?\n/);
-    const end = lines.findIndex((line, index) => index > start && line.trim() === QA_FAILURE_REPORT_END);
-    return start >= 0 && end > start ? lines.slice(start + 1, end).join("\n") : "{}\n";
-}
 function boundedBuilderSummary(text) { return Buffer.from(text).subarray(0, 16 * 1024).toString(); }
 function latestBuilderResponse(opts) {
     return opts.state.builderResponseHistory?.filter((entry) => entry.ticketId === opts.ticket.id).at(-1)?.response ?? opts.builderSummary;

package/dist/qaSnapshot.js

@@ -499,6 +499,25 @@ async function cloneRepositoryAsync(root, review, head) {
  * commands in the independent clone can resolve the same installed toolchain.
  */
 function projectDependencyTrees(sourceRoot, reviewRoot, uncommitted = false) {
+    // Ignored top-level directories (vendored checkouts, runtimes) are also
+    // environment. A committed clone links one only when the clone ignores it
+    // too, so the link never appears as an untracked QA edit. Link these first:
+    // projecting a nested node_modules would otherwise create the parent as a
+    // plain directory and hide the checkout (e.g. vendor/starnet/.git).
+    for (const entry of readdirSync(sourceRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory() || [".git", ".rafi", ".foreman", "node_modules"].includes(entry.name))
+            continue;
+        const source = join(sourceRoot, entry.name);
+        const target = join(reviewRoot, entry.name);
+        if (existsSync(target))
+            continue;
+        const ignored = spawnSync("git", ["-C", sourceRoot, "check-ignore", "-q", "--", entry.name]).status === 0;
+        if (!ignored)
+            continue;
+        if (!uncommitted && spawnSync("git", ["-C", reviewRoot, "check-ignore", "-q", "--", entry.name]).status !== 0)
+            continue;
+        symlinkSync(source, target, "dir");
+    }
     const parents = ["", ...readdirSync(sourceRoot, { withFileTypes: true })
             .filter((entry) => entry.isDirectory() && entry.name !== ".git" && entry.name !== "node_modules")
             .flatMap((entry) => {
@@ -519,20 +538,6 @@ function projectDependencyTrees(sourceRoot, reviewRoot, uncommitted = false) {
         mkdirSync(dirname(target), { recursive: true });
         symlinkSync(source, target, "dir");
     }
-    if (!uncommitted)
-        return;
-    for (const entry of readdirSync(sourceRoot, { withFileTypes: true })) {
-        if (!entry.isDirectory() || [".git", ".rafi", ".foreman", "node_modules"].includes(entry.name))
-            continue;
-        const source = join(sourceRoot, entry.name);
-        const target = join(reviewRoot, entry.name);
-        if (existsSync(target))
-            continue;
-        const ignored = spawnSync("git", ["-C", sourceRoot, "check-ignore", "-q", "--", entry.name]).status === 0;
-        if (!ignored)
-            continue;
-        symlinkSync(source, target, "dir");
-    }
 }
 function hasHeadSync(cwd) {
     const result = spawnSync("git", ["-C", resolve(cwd), "rev-parse", "--verify", "HEAD"], { stdio: "ignore" });

package/dist/qaStructuredResponse.d.ts

@@ -8,3 +8,11 @@ export declare function remediationStructuredResponse(turn: TurnResult, expected
     handoffId?: string;
     findings?: QaFindingRefV2[];
 }): BuilderQaRemediationContract;
+/** Describe a retained native qa-verdict response for evidence and display.
+ * It never authorizes a result; workflow decisions use qaStructuredResponse. */
+export declare function describeNativeQaResponse(text: string): {
+    status: "qa_pass" | "qa_fail" | "blocked" | "needs_input" | "unknown";
+    valid: boolean;
+    issues?: string;
+    reportJson?: string;
+};

package/dist/qaStructuredResponse.js

@@ -55,3 +55,27 @@ export function remediationStructuredResponse(turn, expected) {
         return { valid: false, errors: [String(error)], status: "unknown", fields: {} };
     }
 }
+/** Describe a retained native qa-verdict response for evidence and display.
+ * It never authorizes a result; workflow decisions use qaStructuredResponse. */
+export function describeNativeQaResponse(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return { status: "unknown", valid: false, issues: "Response is not native JSON" };
+    }
+    const result = value?.result;
+    if (value?.operation !== "qa-verdict" || !result || typeof result !== "object")
+        return { status: "unknown", valid: false, issues: "Response is not a qa-verdict result" };
+    if (result.kind === "blocked")
+        return { status: "blocked", valid: true, issues: typeof result.reason === "string" ? result.reason : undefined };
+    if (result.kind === "needs-input")
+        return { status: "needs_input", valid: true, issues: typeof result.question === "string" ? result.question : undefined };
+    const summary = typeof result.summary === "string" ? result.summary : undefined;
+    if (result.kind === "completed" && result.payload?.kind === "passed")
+        return { status: "qa_pass", valid: true, issues: summary };
+    if (result.kind === "completed" && result.payload?.kind === "failed")
+        return { status: "qa_fail", valid: true, issues: summary, reportJson: JSON.stringify(result.payload.report ?? {}) };
+    return { status: "unknown", valid: false, issues: summary };
+}

package/dist/qaTimeline.js

@@ -1,6 +1,6 @@
 import { decisionBelongsToWork } from "./buildInterventions.js";
 import { evidenceRecord } from "./qaEvidenceReader.js";
-import { describeLegacyQaTranscript } from "./legacyCommunicationDisplay.js";
+import { describeNativeQaResponse } from "./qaStructuredResponse.js";
 /** All counters are scoped rows. A changed digest is never a code-change explanation. */
 export function buildQaTimeline(snapshot, workId) {
     const scoped = (table) => (snapshot.rows[table] ?? []).filter(row => row.ticket_id === workId);
@@ -25,10 +25,8 @@ export function buildQaTimeline(snapshot, workId) {
         if (/correction|repair/.test(slot))
             counters.corrections++;
         const bytes = typeof receipt?.cleanedResponseDigest === "string" ? snapshot.blobs.get(receipt.cleanedResponseDigest) : undefined;
-        const contract = bytes ? describeLegacyQaTranscript(bytes.toString("utf8")) : undefined;
-        let classification = contract ? contract.valid ? contract.status : "malformed" : "unavailable";
-        if (typeof receipt?.structuredResponseDigest === "string")
-            classification = "unavailable";
+        const contract = bytes ? describeNativeQaResponse(bytes.toString("utf8")) : undefined;
+        const classification = contract ? contract.valid ? contract.status : "malformed" : "unavailable";
         if (slot === "initial" && classification === "malformed")
             counters.malformedResponses++;
         if (slot === "initial" && classification === "blocked")

package/dist/recoveryOwners.d.ts

@@ -0,0 +1,32 @@
+export interface RecoveryOwner {
+    source: "build-admission" | "project-lease" | "supervisor" | "owned-process";
+    runId: string;
+    pid: number | null;
+    processStart?: string;
+    host?: string;
+}
+export interface CompletedPlanApproval {
+    runId: string;
+    originalWork: unknown;
+    state: {
+        planId?: string;
+        revision?: number;
+        digest?: string;
+        decisionReceipt?: unknown;
+    } & Record<string, unknown>;
+    updatedAt: string;
+}
+/**
+ * Reads completed `rafi plan` approval runs without migrating. They are
+ * planning state that predates any build, so a build reset must carry them
+ * into the fresh database; build recovery refuses to resume without one.
+ */
+export declare function readCompletedPlanApprovals(dbPath: string): CompletedPlanApproval[];
+/**
+ * Lists every process that may still own a recovery database, without
+ * migrating it. Archiving tools need this because opening a database from an
+ * older Rafi through WorkflowDb runs the structured-communication cutover, and
+ * a stale build admission left by a dead process makes that cutover fail.
+ * Unknown or malformed tables are skipped; callers decide liveness.
+ */
+export declare function readRecoveryOwners(dbPath: string): RecoveryOwner[];

package/dist/recoveryOwners.js

@@ -0,0 +1,87 @@
+import { existsSync } from "node:fs";
+import Database from "better-sqlite3";
+/**
+ * Reads completed `rafi plan` approval runs without migrating. They are
+ * planning state that predates any build, so a build reset must carry them
+ * into the fresh database; build recovery refuses to resume without one.
+ */
+export function readCompletedPlanApprovals(dbPath) {
+    if (!existsSync(dbPath))
+        return [];
+    const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+    try {
+        db.pragma("query_only = ON");
+        if (!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='workflow_runs'").get())
+            return [];
+        const rows = db.prepare("SELECT run_id,original_work_json,state_json,updated_at FROM workflow_runs WHERE kind='plan' AND status='completed' ORDER BY updated_at")
+            .all();
+        const approvals = [];
+        for (const row of rows) {
+            try {
+                approvals.push({ runId: row.run_id, originalWork: JSON.parse(row.original_work_json), state: JSON.parse(row.state_json), updatedAt: row.updated_at });
+            }
+            catch { /* a malformed historical row is not an approval */ }
+        }
+        return approvals;
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Lists every process that may still own a recovery database, without
+ * migrating it. Archiving tools need this because opening a database from an
+ * older Rafi through WorkflowDb runs the structured-communication cutover, and
+ * a stale build admission left by a dead process makes that cutover fail.
+ * Unknown or malformed tables are skipped; callers decide liveness.
+ */
+export function readRecoveryOwners(dbPath) {
+    if (!existsSync(dbPath))
+        return [];
+    const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+    try {
+        db.pragma("query_only = ON");
+        const has = (table) => Boolean(db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?").get(table));
+        const owners = [];
+        if (has("build_admission")) {
+            const row = db.prepare("SELECT record_json FROM build_admission WHERE singleton=1").get();
+            if (row) {
+                let record;
+                try {
+                    record = JSON.parse(row.record_json);
+                }
+                catch { /* malformed: report as unverifiable */ }
+                owners.push({ source: "build-admission", runId: String(record?.runId ?? ""), pid: typeof record?.pid === "number" ? record.pid : null, processStart: record?.processStart, host: record?.host });
+            }
+        }
+        if (has("project_lease")) {
+            for (const row of db.prepare("SELECT * FROM project_lease").all()) {
+                owners.push({ source: "project-lease", runId: String(row.run_id ?? ""), pid: typeof row.pid === "number" ? row.pid : null, processStart: row.process_start ?? undefined, host: row.host ?? undefined });
+            }
+        }
+        if (has("supervisor_leases") && has("workflow_runs")) {
+            const rows = db.prepare(`SELECT s.run_id,s.state_json FROM supervisor_leases s JOIN workflow_runs r USING(run_id)
+        WHERE r.kind='build' AND r.status NOT IN ('completed','cancelled','superseded')`).all();
+            for (const row of rows) {
+                let state;
+                try {
+                    state = JSON.parse(row.state_json);
+                }
+                catch { /* malformed: report as unverifiable */ }
+                // Matches the prior reset rule: only a supervisor recorded as running owns the run.
+                if (state && state.status !== "running")
+                    continue;
+                owners.push({ source: "supervisor", runId: row.run_id, pid: typeof state?.pid === "number" ? state.pid : null, processStart: state?.processStart });
+            }
+        }
+        if (has("build_owned_processes")) {
+            for (const row of db.prepare("SELECT run_id,pid,process_start,host FROM build_owned_processes WHERE state<>'quiescent'").all()) {
+                owners.push({ source: "owned-process", runId: String(row.run_id), pid: typeof row.pid === "number" ? row.pid : null, processStart: row.process_start ?? undefined, host: row.host ?? undefined });
+            }
+        }
+        return owners;
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/runtimePreflight.d.ts

@@ -0,0 +1,11 @@
+export interface RuntimeCheck {
+    ok: boolean;
+    label: string;
+    detail: string;
+    fix?: string;
+}
+/** Minimal semver check for the range forms Rafi declares: "24.x", "^13.0.3", "13.0.3". */
+export declare function satisfiesRange(version: string, range: string): boolean;
+export declare function checkRuntimeEnvironment(): RuntimeCheck[];
+/** Text for a failed preflight, or undefined when every check passed. */
+export declare function runtimePreflightFailure(checks?: RuntimeCheck[]): string | undefined;

package/dist/runtimePreflight.js

@@ -0,0 +1,77 @@
+/**
+ * Runtime environment checks that must run before Rafi's main modules load.
+ * Uses only Node built-ins so it still reports clearly on an unsupported
+ * Node, where importing the CLI itself fails with an opaque SyntaxError.
+ */
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+const REINSTALL_FIX = "reinstall Rafi under the active Node (npm install -g @rafi-ai/cli); in a Rafi workspace run `corepack pnpm install --frozen-lockfile`";
+function packageJson() {
+    try {
+        return JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+/** Minimal semver check for the range forms Rafi declares: "24.x", "^13.0.3", "13.0.3". */
+export function satisfiesRange(version, range) {
+    const parse = (value) => value.replace(/^[v^~=]/, "").split(".").map(part => Number.parseInt(part, 10));
+    const [major, minor = 0, patch = 0] = parse(version);
+    const spec = range.trim();
+    if (/^\d+\.x(\.x)?$/.test(spec))
+        return major === Number.parseInt(spec, 10);
+    const [wantMajor, wantMinor = 0, wantPatch = 0] = parse(spec);
+    if (spec.startsWith("^"))
+        return major === wantMajor && (minor > wantMinor || minor === wantMinor && patch >= wantPatch);
+    return major === wantMajor && minor === wantMinor && patch === wantPatch;
+}
+export function checkRuntimeEnvironment() {
+    const pkg = packageJson();
+    const checks = [];
+    const nodeRange = pkg.engines?.node;
+    const nodeSupported = !nodeRange || satisfiesRange(process.versions.node, nodeRange);
+    if (nodeRange) {
+        const ok = nodeSupported;
+        checks.push({ ok, label: `node ${nodeRange}`, detail: `${process.version} (${process.execPath})`,
+            ...(ok ? {} : { fix: `run Rafi with Node ${nodeRange}, e.g. \`nvm use 24\`, and reinstall it there` }) });
+    }
+    const sqliteRange = pkg.dependencies?.["better-sqlite3"];
+    const require = createRequire(import.meta.url);
+    let installed;
+    try {
+        installed = require("better-sqlite3/package.json").version;
+    }
+    catch { /* reported below */ }
+    if (sqliteRange) {
+        const ok = Boolean(installed && satisfiesRange(installed, sqliteRange));
+        checks.push({ ok, label: `better-sqlite3 ${sqliteRange}`, detail: installed ? `installed ${installed}` : "not installed",
+            ...(ok ? {} : { fix: `the installed native SQLite module does not match the declared version; ${REINSTALL_FIX}` }) });
+    }
+    // Only probe the native binding on a supported Node with the declared
+    // version: under an unsupported Node the probe can abort the process
+    // (uncatchable N-API fatal error, seen on Node 18), and a mismatched module
+    // may load and then crash later (seen with 12.10 under Node 24).
+    if (nodeSupported && installed && (!sqliteRange || satisfiesRange(installed, sqliteRange))) {
+        try {
+            const Database = require("better-sqlite3");
+            new Database(":memory:").close();
+            checks.push({ ok: true, label: "native SQLite loads", detail: `Node ABI ${process.versions.modules}` });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const abi = /NODE_MODULE_VERSION (\d+)/.exec(message)?.[1];
+            checks.push({ ok: false, label: "native SQLite loads", detail: abi ? `built for Node ABI ${abi}, active Node ABI ${process.versions.modules}` : message.split("\n")[0],
+                fix: `rebuild the native module for this Node: ${REINSTALL_FIX}` });
+        }
+    }
+    return checks;
+}
+/** Text for a failed preflight, or undefined when every check passed. */
+export function runtimePreflightFailure(checks = checkRuntimeEnvironment()) {
+    const failed = checks.filter(check => !check.ok);
+    if (!failed.length)
+        return undefined;
+    return ["rafi: this runtime environment cannot run Rafi:", ...failed.map(check => `  - ${check.label}: ${check.detail}${check.fix ? `\n    fix: ${check.fix}` : ""}`)].join("\n");
+}

package/dist/sources/sourceRegistry.d.ts

@@ -1,6 +1,4 @@
 import type { ProjectSourceEntry, ProjectSourceLocator, ProjectSourceType, SourceRegistryConfig, SourceSnapshotStorage, TicketSetupSource } from "rafi-spec";
-export declare const SOURCE_REQUEST_START = "RAFI_SOURCE_REQUEST_START";
-export declare const SOURCE_REQUEST_END = "RAFI_SOURCE_REQUEST_END";
 export interface StructuredSourceRequest {
     type?: ProjectSourceType;
     description?: string;
@@ -38,7 +36,6 @@ export declare function removeSource(registry: SourceRegistryConfig, id: string)
 export declare function discardStagedSourceCaptures(projectDir: string, original: SourceRegistryConfig, staged: SourceRegistryConfig): void;
 /** Compatibility bridge for legacy ticket setup callers. Existing entries and versions are retained. */
 export declare function appendLegacyTicketSources(registry: SourceRegistryConfig, sources: TicketSetupSource[]): SourceRegistryConfig;
-export declare function extractSourceRequests(output: string): StructuredSourceRequest[];
 /** Deterministically recognize only an entire obvious locator; all other language stays pending for agent interpretation. */
 export declare function sourceRequestFromAnswer(answer: string, projectDir: string): StructuredSourceRequest;
 export declare function registerSourceRequests(projectDir: string, registry: SourceRegistryConfig, requests: StructuredSourceRequest[], opts?: {

package/dist/sources/sourceRegistry.js

@@ -8,10 +8,7 @@ import { parse, stringify } from "yaml";
 import { fetchAndSnapshotUrl, normalizePublicHttpUrl, snapshotExternalLocalFile } from "../tickets/sourceFetch.js";
 import { fetchJiraIssues, fetchLinearIssues } from "../tickets/importer.js";
 import { withActivityPhase } from "../activity.js";
-import { structuredSourceRequestSchema, zodIssues } from "rafi-spec";
 const execFileAsync = promisify(execFile);
-export const SOURCE_REQUEST_START = "RAFI_SOURCE_REQUEST_START";
-export const SOURCE_REQUEST_END = "RAFI_SOURCE_REQUEST_END";
 const CONFIG_FILE = "rafi-config.yaml";
 const DEFAULT_REGISTRY = { version: 1, snapshot_storage: "local", entries: [] };
 export function emptySourceRegistry(storage = "local") {
@@ -138,45 +135,6 @@ export function appendLegacyTicketSources(registry, sources) {
         migrateTicketSource(next, source, warnings);
     return next;
 }
-export function extractSourceRequests(output) {
-    const requests = [];
-    let cursor = 0;
-    while (true) {
-        const start = output.indexOf(SOURCE_REQUEST_START, cursor);
-        if (start < 0)
-            break;
-        const end = output.indexOf(SOURCE_REQUEST_END, start + SOURCE_REQUEST_START.length);
-        if (end < 0)
-            throw new Error(`source request is missing ${SOURCE_REQUEST_END}`);
-        const body = output.slice(start + SOURCE_REQUEST_START.length, end).trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "");
-        let value;
-        try {
-            value = JSON.parse(body);
-        }
-        catch (error) {
-            throw new Error(`source request is invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
-        }
-        const values = Array.isArray(value) ? value : [value];
-        for (const item of values) {
-            const parsed = structuredSourceRequestSchema.safeParse(item);
-            if (!parsed.success)
-                throw new Error(`source request contract validation failed:\n${zodIssues(parsed.error).map((issue) => `- ${issue}`).join("\n")}`);
-            requests.push(parsed.data);
-        }
-        cursor = end + SOURCE_REQUEST_END.length;
-    }
-    // Compatibility with the original single-line protocol. Preserve the complete remainder.
-    for (const match of output.matchAll(/^SOURCE_REQUEST:\s*(.+)$/gim)) {
-        const legacy = structuredSourceRequestSchema.safeParse({ description: match[1].trim() });
-        // Legacy lines are intentionally converted into the same typed contract;
-        // they remain description-only pending requests after registration, but
-        // they no longer bypass shape validation.
-        if (!legacy.success)
-            throw new Error(`legacy source request contract validation failed:\n${zodIssues(legacy.error).map((issue) => `- ${issue}`).join("\n")}`);
-        requests.push(legacy.data);
-    }
-    return requests;
-}
 /** Deterministically recognize only an entire obvious locator; all other language stays pending for agent interpretation. */
 export function sourceRequestFromAnswer(answer, projectDir) {
     const value = answer.trim();