ai-foreman 1.7.29 → 2.0.1

package/dist/qaReviewEvidence.d.ts

@@ -1,6 +1,10 @@
 import type { RunSpanV1 } from "rafi-spec";
-/** Explicit authorization is scoped to one nonempty ticket ID. */
-export declare function qaCommandOutputExcerptsAllowed(workId: string, configuredTicket?: string | undefined): boolean;
-/** Excerpts are opt-in; command text is never forwarded. */
+/**
+ * Bounded, adapter-redacted output excerpts are host-retained evidence and are
+ * delivered to independent QA by default. RAFI_QA_COMMAND_OUTPUT_EXCERPTS=0
+ * (or off/false) disables them; a ticket ID limits them to that ticket.
+ */
+export declare function qaCommandOutputExcerptsAllowed(workId: string, configured?: string | undefined): boolean;
+/** Command text is never forwarded; excerpts are bounded and may be truncated. */
 export declare function selectQaCommandObservations(spans: RunSpanV1[], runId: string, workId: string, includeOutputExcerpts?: boolean): unknown[];
 export declare function retainedQaCommandObservations(projectDir: string, runId: string, workId: string, includeOutputExcerpts?: boolean): unknown[];

package/dist/qaReviewEvidence.js

@@ -1,9 +1,20 @@
 import { ObservabilityReader } from "./observability.js";
-/** Explicit authorization is scoped to one nonempty ticket ID. */
-export function qaCommandOutputExcerptsAllowed(workId, configuredTicket = process.env.RAFI_QA_COMMAND_OUTPUT_EXCERPTS) {
-    return workId.length > 0 && configuredTicket === workId;
+/**
+ * Bounded, adapter-redacted output excerpts are host-retained evidence and are
+ * delivered to independent QA by default. RAFI_QA_COMMAND_OUTPUT_EXCERPTS=0
+ * (or off/false) disables them; a ticket ID limits them to that ticket.
+ */
+export function qaCommandOutputExcerptsAllowed(workId, configured = process.env.RAFI_QA_COMMAND_OUTPUT_EXCERPTS) {
+    if (!workId)
+        return false;
+    const value = configured?.trim();
+    if (!value || ["1", "on", "true"].includes(value.toLowerCase()))
+        return true;
+    if (["0", "off", "false"].includes(value.toLowerCase()))
+        return false;
+    return value === workId;
 }
-/** Excerpts are opt-in; command text is never forwarded. */
+/** Command text is never forwarded; excerpts are bounded and may be truncated. */
 export function selectQaCommandObservations(spans, runId, workId, includeOutputExcerpts = false) {
     const turns = new Set(spans.filter(span => span.runId === runId && span.kind === "provider_turn" && span.role === "builder" && span.ticketId === workId).map(span => span.spanId));
     return spans.filter(span => span.runId === runId && span.kind === "tool" && span.role === "builder" && span.parentSpanId && turns.has(span.parentSpanId) && span.completionKnown && span.endedAt)

package/dist/qaRuntime.js

@@ -13,7 +13,7 @@ export function describeQaRuntimeHandle(adapter, metadata, handoffReceipt) {
     // need the machine owner's authentication settings; Codex does not receive
     // that SDK option.
     const settingsSources = adapter.agent === "claude" ? "user" : "none";
-    const confinementPolicy = { sandboxMode: "read-only", settingsSources, permissions: readOnlyPermissionConfig(), dependencyProjection: "read-only-symlink", scratch: "sibling-temp-directory" };
+    const confinementPolicy = { sandboxMode: "read-only", settingsSources, permissions: readOnlyPermissionConfig(), dependencyProjection: "read-only-symlink", scratch: adapter.agent === "claude" ? "adapter-owned-private-temp-directory" : "sibling-temp-directory" };
     const confinementBase = {
         version: 2, sourceMode: "read-only", scratchMode: "isolated",
         settingsSources, networkMode: "provider-required",

package/dist/qaSnapshot.js

@@ -51,11 +51,14 @@ export function createDisposableQaSnapshot(builderWorktree, options = {}) {
     const frozenState = captureFrozenQaSource(source);
     const tempRoot = mkdtempSync(join(tmpdir(), "rafi-qa-"));
     const review = join(tempRoot, "review");
-    cloneRepositorySync(root, review, frozenState.head);
+    if (frozenState.head === "unavailable")
+        initializeUncommittedReviewSync(review);
+    else
+        cloneRepositorySync(root, review, frozenState.head);
     try {
         applyFrozenSync(review, frozenState);
         if (options.projectDependencies !== false)
-            projectDependencyTrees(root, review);
+            projectDependencyTrees(root, review, frozenState.head === "unavailable");
         mkdirSync(join(tempRoot, "scratch"), { mode: 0o700 });
         const manifest = manifestFromFrozen(frozenState);
         const snapshot = {
@@ -81,9 +84,12 @@ export async function createDisposableQaSnapshotAsync(builderWorktree, progress
     const review = join(tempRoot, "review");
     try {
         progress("preparing disposable QA snapshot", "creating independent review repository");
-        await cloneRepositoryAsync(root, review, frozenState.head);
+        if (frozenState.head === "unavailable")
+            await initializeUncommittedReviewAsync(review);
+        else
+            await cloneRepositoryAsync(root, review, frozenState.head);
         await applyFrozenAsync(review, frozenState, progress);
-        projectDependencyTrees(root, review);
+        projectDependencyTrees(root, review, frozenState.head === "unavailable");
         await mkdir(join(tempRoot, "scratch"), { mode: 0o700 });
         const manifest = manifestFromFrozen(frozenState);
         const snapshot = {
@@ -106,11 +112,11 @@ export async function createDisposableQaSnapshotAsync(builderWorktree, progress
 }
 export function frozenQaStateManifest(state) { return manifestFromFrozen(state); }
 export function changeManifest(worktree) {
-    const diff = gitBuffer(resolve(worktree), ["diff", "--binary", "HEAD", ...PRODUCT_PATHSPEC]);
+    const diff = hasHeadSync(worktree) ? gitBuffer(resolve(worktree), ["diff", "--binary", "HEAD", ...PRODUCT_PATHSPEC]) : Buffer.alloc(0);
     return { diffDigest: hash(diff), untracked: untrackedPaths(worktree).map((path) => describeUntrackedSync(worktree, path)) };
 }
 export async function changeManifestAsync(worktree, progress = () => { }, state = "checking QA file changes") {
-    const diff = await runGit(worktree, ["diff", "--binary", "HEAD", ...PRODUCT_PATHSPEC]);
+    const diff = (await hasHeadAsync(worktree)) ? await runGit(worktree, ["diff", "--binary", "HEAD", ...PRODUCT_PATHSPEC]) : Buffer.alloc(0);
     const paths = await untrackedPathsAsync(worktree);
     const untracked = [];
     for (let index = 0; index < paths.length; index++) {
@@ -162,14 +168,14 @@ export function prospectiveGitTreeMatches(worktree, expectedTree, allowedPaths =
     throw new Error(`git diff could not compare QA finalization trees (exit ${result.status ?? "unknown"})`);
 }
 function captureOnce(cwd) {
-    const head = gitText(cwd, ["rev-parse", "HEAD"]);
+    const head = hasHeadSync(cwd) ? gitText(cwd, ["rev-parse", "HEAD"]) : "unavailable";
     const repository = captureRepositoryMetadataSync(cwd);
     const status = gitBuffer(cwd, ["status", "--porcelain=v2", "-z", "--untracked-files=all", ...PRODUCT_PATHSPEC]);
-    const combinedDiff = gitBuffer(cwd, ["diff", "--binary", "HEAD", ...PRODUCT_PATHSPEC]);
-    const stagedDiff = gitBuffer(cwd, ["diff", "--cached", "--binary", ...PRODUCT_PATHSPEC]);
-    const unstagedDiff = gitBuffer(cwd, ["diff", "--binary", ...PRODUCT_PATHSPEC]);
-    const stagedNames = gitBuffer(cwd, ["diff", "--cached", "--name-status", "-z", ...PRODUCT_PATHSPEC]);
-    const unstagedNames = gitBuffer(cwd, ["diff", "--name-status", "-z", ...PRODUCT_PATHSPEC]);
+    const combinedDiff = head === "unavailable" ? Buffer.alloc(0) : gitBuffer(cwd, ["diff", "--binary", "HEAD", ...PRODUCT_PATHSPEC]);
+    const stagedDiff = gitBuffer(cwd, ["diff", "--cached", "--binary", ...(head === "unavailable" ? ["--root"] : []), ...PRODUCT_PATHSPEC]);
+    const unstagedDiff = head === "unavailable" ? Buffer.alloc(0) : gitBuffer(cwd, ["diff", "--binary", ...PRODUCT_PATHSPEC]);
+    const stagedNames = gitBuffer(cwd, ["diff", "--cached", "--name-status", "-z", ...(head === "unavailable" ? ["--root"] : []), ...PRODUCT_PATHSPEC]);
+    const unstagedNames = head === "unavailable" ? Buffer.alloc(0) : gitBuffer(cwd, ["diff", "--name-status", "-z", ...PRODUCT_PATHSPEC]);
     const untrackedNames = gitBuffer(cwd, ["ls-files", "--others", "--exclude-standard", "-z"]);
     const untracked = untrackedPathsFrom(untrackedNames).map((path) => captureUntrackedSync(cwd, path));
     const pathInventory = enrichTrackedPathInventorySync(cwd, buildPathInventory(stagedNames, unstagedNames, untracked));
@@ -183,14 +189,15 @@ async function captureOnceAsync(cwd, progress) {
     // observe a different index/worktree generation and manufacture a state
     // that never existed. The enclosing double-capture supplies the stability
     // fence across the complete sequence.
-    const headBytes = await runGit(cwd, ["rev-parse", "HEAD"]);
+    const headAvailable = await hasHeadAsync(cwd);
+    const headBytes = headAvailable ? await runGit(cwd, ["rev-parse", "HEAD"]) : Buffer.from("unavailable");
     const repository = await captureRepositoryMetadataAsync(cwd);
     const status = await runGit(cwd, ["status", "--porcelain=v2", "-z", "--untracked-files=all", ...PRODUCT_PATHSPEC]);
-    const combinedDiff = await runGit(cwd, ["diff", "--binary", "HEAD", ...PRODUCT_PATHSPEC]);
-    const stagedDiff = await runGit(cwd, ["diff", "--cached", "--binary", ...PRODUCT_PATHSPEC]);
-    const unstagedDiff = await runGit(cwd, ["diff", "--binary", ...PRODUCT_PATHSPEC]);
-    const stagedNames = await runGit(cwd, ["diff", "--cached", "--name-status", "-z", ...PRODUCT_PATHSPEC]);
-    const unstagedNames = await runGit(cwd, ["diff", "--name-status", "-z", ...PRODUCT_PATHSPEC]);
+    const combinedDiff = headAvailable ? await runGit(cwd, ["diff", "--binary", "HEAD", ...PRODUCT_PATHSPEC]) : Buffer.alloc(0);
+    const stagedDiff = await runGit(cwd, ["diff", "--cached", "--binary", ...(headAvailable ? [] : ["--root"]), ...PRODUCT_PATHSPEC]);
+    const unstagedDiff = headAvailable ? await runGit(cwd, ["diff", "--binary", ...PRODUCT_PATHSPEC]) : Buffer.alloc(0);
+    const stagedNames = await runGit(cwd, ["diff", "--cached", "--name-status", "-z", ...(headAvailable ? [] : ["--root"]), ...PRODUCT_PATHSPEC]);
+    const unstagedNames = headAvailable ? await runGit(cwd, ["diff", "--name-status", "-z", ...PRODUCT_PATHSPEC]) : Buffer.alloc(0);
     const untrackedNames = await runGit(cwd, ["ls-files", "--others", "--exclude-standard", "-z"]);
     const paths = untrackedPathsFrom(untrackedNames);
     const untracked = [];
@@ -303,7 +310,13 @@ function describeUntrackedSync(worktree, path) {
 function untrackedPaths(worktree) { return untrackedPathsFrom(gitBuffer(resolve(worktree), ["ls-files", "--others", "--exclude-standard", "-z"])); }
 async function untrackedPathsAsync(worktree) { return untrackedPathsFrom(await runGit(worktree, ["ls-files", "--others", "--exclude-standard", "-z"])); }
 function untrackedPathsFrom(raw) { return raw.toString().split("\0").filter((path) => path && isQaProductPath(path)).sort(); }
-function isQaProductPath(path) { return path !== ".foreman" && !path.startsWith(".foreman/") && path !== ".rafi" && !path.startsWith(".rafi/"); }
+function isQaProductPath(path) {
+    return path !== ".git" && !path.startsWith(".git/")
+        && path !== ".foreman" && !path.startsWith(".foreman/")
+        && path !== ".rafi" && !path.startsWith(".rafi/")
+        && path !== "node_modules" && !path.startsWith("node_modules/")
+        && path !== "vendor" && !path.startsWith("vendor/");
+}
 function renderSummary(staged, unstaged, untracked) {
     const normalize = (value) => value.toString().split("\0").filter(Boolean).filter(isQaProductPath).sort().join("\n") || "(none)";
     return `tracked/staged:\n${normalize(staged)}\ntracked/unstaged:\n${normalize(unstaged)}\nuntracked:\n${normalize(untracked)}`;
@@ -454,6 +467,16 @@ function manifestDifference(before, after) {
             changes.push(path);
     return changes;
 }
+function initializeUncommittedReviewSync(review) {
+    mkdirSync(review, { recursive: true });
+    const initialized = spawnSync("git", ["init", "-q", review], { encoding: "utf8" });
+    if (initialized.status !== 0)
+        throw new Error(`cannot initialize independent QA repository: ${initialized.stderr.trim()}`);
+}
+async function initializeUncommittedReviewAsync(review) {
+    await mkdir(review, { recursive: true });
+    await runGit(dirname(review), ["init", "-q", review]);
+}
 function cloneRepositorySync(root, review, head) {
     const cloned = spawnSync("git", ["clone", "--no-local", "--no-hardlinks", "--no-checkout", "--quiet", root, review], { encoding: "utf8" });
     if (cloned.status !== 0) {
@@ -475,7 +498,26 @@ async function cloneRepositoryAsync(root, review, head) {
  * Project the existing trees without copying or permitting writes so validation
  * commands in the independent clone can resolve the same installed toolchain.
  */
-function projectDependencyTrees(sourceRoot, reviewRoot) {
+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) => {
@@ -491,12 +533,25 @@ function projectDependencyTrees(sourceRoot, reviewRoot) {
         if (!existsSync(source) || existsSync(target) || !lstatSync(source).isDirectory())
             continue;
         const relativeTarget = parent ? `${parent.replaceAll("\\", "/")}/node_modules` : "node_modules";
-        if (spawnSync("git", ["-C", reviewRoot, "check-ignore", "-q", "--", relativeTarget]).status !== 0)
+        if (!uncommitted && spawnSync("git", ["-C", reviewRoot, "check-ignore", "-q", "--", relativeTarget]).status !== 0)
             continue;
         mkdirSync(dirname(target), { recursive: true });
         symlinkSync(source, target, "dir");
     }
 }
+function hasHeadSync(cwd) {
+    const result = spawnSync("git", ["-C", resolve(cwd), "rev-parse", "--verify", "HEAD"], { stdio: "ignore" });
+    return result.status === 0;
+}
+async function hasHeadAsync(cwd) {
+    try {
+        await runGit(cwd, ["rev-parse", "--verify", "HEAD"]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function captureRepositoryMetadataSync(cwd) {
     const topLevel = gitText(cwd, ["rev-parse", "--show-toplevel"]);
     const gitDir = gitText(cwd, ["rev-parse", "--path-format=absolute", "--git-dir"]);

package/dist/qaStructuredResponse.d.ts

@@ -0,0 +1,18 @@
+import { type QaResponseContract } from "rafi-spec";
+import type { TurnResult } from "./adapters/types.js";
+import type { StepStatus } from "./foreman.js";
+import { type BuilderQaRemediationContract, type QaFindingRefV2 } from "rafi-spec";
+export declare function qaStructuredResponse(turn: TurnResult): QaResponseContract;
+export declare function qaStructuredStatus(turn: TurnResult): StepStatus;
+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

@@ -0,0 +1,81 @@
+import { qaVerdictOutput, validateQaFailureReport, validateBuilderQaRemediationReport } from "rafi-spec";
+import { operationResponse } from "./structuredOperation.js";
+import { remediationOutput, validateBuilderFindingCoverage } from "rafi-spec";
+export function qaStructuredResponse(turn) {
+    try {
+        const response = operationResponse(turn, qaVerdictOutput);
+        if (response.result.kind === "blocked")
+            return { valid: true, errors: [], status: "blocked", fields: { reason: response.result.reason } };
+        if (response.result.kind === "needs-input")
+            return { valid: true, errors: [], status: "needs_input", fields: { question: response.result.question, choices: response.result.choices.join("|") } };
+        if (response.result.kind !== "completed")
+            throw new Error("Unconsumed QA intermediate result");
+        const payload = response.result.payload;
+        if (payload.kind === "failed") {
+            const validation = validateQaFailureReport(payload.report);
+            if (!validation.valid)
+                throw new Error(validation.errors.join("; "));
+        }
+        return payload.kind === "passed" ? { valid: true, errors: [], status: "qa_pass", fields: { summary: response.result.summary } }
+            : { valid: true, errors: [], status: "qa_fail", fields: { issues: response.result.summary }, report: payload.report, rawReportJson: JSON.stringify(payload.report) };
+    }
+    catch (error) {
+        return { valid: false, errors: [String(error)], status: "unknown", fields: {} };
+    }
+}
+export function qaStructuredStatus(turn) {
+    const contract = qaStructuredResponse(turn);
+    return { kind: contract.status, ...contract.fields, choices: contract.fields.choices?.split("|"), error: contract.errors.join("; ") || undefined };
+}
+export function remediationStructuredResponse(turn, expected) {
+    try {
+        const { result } = operationResponse(turn, remediationOutput);
+        if (result.kind === "blocked")
+            return { valid: true, errors: [], status: "blocked", fields: { reason: result.reason } };
+        if (result.kind === "needs-input")
+            return { valid: true, errors: [], status: "needs_input", fields: { question: result.question } };
+        if (result.kind !== "completed")
+            throw new Error("Unconsumed remediation intermediate result");
+        const { report, status, reason } = result.payload;
+        const validation = validateBuilderQaRemediationReport(report);
+        if (!validation.valid)
+            throw new Error(validation.errors.join("; "));
+        const errors = expected.findings ? validateBuilderFindingCoverage(report, expected.findings) : [];
+        if (expected.handoffId && report.handoff_id !== expected.handoffId)
+            errors.push("Remediation handoff identity mismatch");
+        const blocked = report.findings.some(finding => finding.disposition === "blocked");
+        if (blocked !== (status === "blocked") || status === "blocked" && !reason || status === "done" && reason !== null)
+            errors.push("Contradictory remediation outcome");
+        for (const finding of report.findings)
+            if (Boolean(finding.blocker) !== (finding.disposition === "blocked"))
+                errors.push(`Invalid blocker for ${finding.finding_key}`);
+        return { valid: !errors.length, errors, status, fields: status === "blocked" ? { reason: reason } : { summary: result.summary }, report, rawReportJson: JSON.stringify(report) };
+    }
+    catch (error) {
+        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 { parseQaResponseContract } from "rafi-spec";
+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,7 +25,7 @@ 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 ? parseQaResponseContract(bytes.toString("utf8")) : undefined;
+        const contract = bytes ? describeNativeQaResponse(bytes.toString("utf8")) : undefined;
         const classification = contract ? contract.valid ? contract.status : "malformed" : "unavailable";
         if (slot === "initial" && classification === "malformed")
             counters.malformedResponses++;

package/dist/qaVerificationContract.d.ts

@@ -20,9 +20,8 @@ export declare function ensureHostScopeCheck(candidate: QaContractCandidateV1, b
  */
 export declare function rewriteProviderHostScopeChecks(candidate: QaContractCandidateV1, baselineId: string): QaContractCandidateV1;
 export declare function authoritativeInventory(ticket: TicketDef, checklist: string[], inputs: ContractInputRef[]): RequirementRef[];
-export declare function parsePreparationArtifact<T>(text: string, tag: string, maximum?: number): T;
 /** Capture safe absolute snapshot paths before the disposable snapshot is removed. */
-export declare function mapSnapshotWorkingDirectories(text: string, snapshotPath: string): Record<string, string>;
+export declare function mapSnapshotWorkingDirectories(text: Partial<QaContractCandidateV1>, snapshotPath: string): Record<string, string>;
 /** Providers sometimes repeat an absolute disposable-snapshot path from an earlier
  * conversation.  That path is host-owned and must not enter the durable contract;
  * normalize only the bounded QA snapshot naming convention to stable relative

package/dist/qaVerificationContract.js

@@ -129,8 +129,7 @@ export function bindUniqueBaselineCheckIds(candidate) {
 /** Ensure the host-owned scope invariant survives providers that omit or rename it. */
 export function ensureHostScopeCheck(candidate, baselineId) {
     const copy = structuredClone(candidate);
-    const hasHostScope = copy.checks.some(check => check.applicability.decisionOwner === "host"
-        && /scope comparison|product paths|preimplementation baseline/i.test(`${check.expectedBehavior} ${check.expectedEvidence.join(" ")} ${check.applicability.requiredEvidence.join(" ")}`));
+    const hasHostScope = copy.checks.some(check => check.hostKind === "source-scope");
     if (hasHostScope)
         return copy;
     // Every contract check must trace to at least one authoritative requirement.
@@ -141,8 +140,11 @@ export function ensureHostScopeCheck(candidate, baselineId) {
     const scopeRequirement = copy.requirements[0]?.id;
     if (!scopeRequirement)
         throw new Error("Cannot add host scope check without an authoritative requirement");
+    let hostId = "host-scope";
+    while (copy.checks.some(check => check.id === hostId))
+        hostId += "-host";
     copy.checks.push({
-        id: "host-scope",
+        id: hostId, hostKind: "source-scope",
         requirementRefs: [scopeRequirement],
         origin: "invariant",
         expectedBehavior: "Rafi compares the final product paths with the host-captured preimplementation baseline and rejects unauthorized product changes.",
@@ -214,42 +216,13 @@ export function authoritativeInventory(ticket, checklist, inputs) {
     }
     return result;
 }
-export function parsePreparationArtifact(text, tag, maximum = 2 * 1024 * 1024) {
-    if (Buffer.byteLength(text) > maximum)
-        throw new Error("QA preparation response exceeds size limit");
-    const start = `${tag}_START`, end = `${tag}_END`;
-    // Marker names can appear inline in provider prose or in a quoted repair
-    // instruction. Only a standalone marker line is an envelope boundary.
-    // This keeps the parser strict about malformed envelopes without treating
-    // explanatory text as a second/truncated artifact.
-    const markerOffsets = (marker) => {
-        const offsets = [];
-        const pattern = new RegExp(`^[ \\t]*${marker}[ \\t]*$`, "gm");
-        for (let match = pattern.exec(text); match; match = pattern.exec(text))
-            offsets.push(match.index);
-        return offsets;
-    };
-    const starts = markerOffsets(start), ends = markerOffsets(end);
-    if (!starts.length || starts.length !== ends.length)
-        throw new Error(`Expected exactly one ${tag} artifact`);
-    const artifacts = starts.map((at, index) => {
-        const from = at + start.length, to = ends[index];
-        if (to < from)
-            throw new Error("Malformed preparation artifact envelope");
-        return text.slice(from, to).trim();
-    });
-    if (artifacts.length > 1) {
-        const normalized = artifacts.map(artifact => canonicalContractJson(JSON.parse(artifact)));
-        if (normalized.some(artifact => artifact !== normalized[0]))
-            throw new Error(`Expected exactly one unambiguous ${tag} artifact`);
-    }
-    return JSON.parse(artifacts[0]);
-}
 /** Capture safe absolute snapshot paths before the disposable snapshot is removed. */
 export function mapSnapshotWorkingDirectories(text, snapshotPath) {
     const result = {};
     try {
-        const draft = parsePreparationArtifact(text, "RAFI_QA_CANDIDATE");
+        if (typeof text === "string")
+            throw new Error("Snapshot mappings require validated native draft fields");
+        const draft = text;
         const root = realpathSync(snapshotPath);
         for (const check of draft.checks ?? [])
             for (const method of check.verification ?? []) {
@@ -263,6 +236,17 @@ export function mapSnapshotWorkingDirectories(text, snapshotPath) {
                 }
                 catch { /* Missing or inaccessible paths remain invalid. */ }
             }
+        for (const evidence of draft.preparationEvidence ?? [])
+            for (const reference of evidence.references ?? []) {
+                if (!isAbsolute(reference.path))
+                    continue;
+                try {
+                    const target = realpathSync(reference.path), path = relative(root, target);
+                    if (path && path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path) && statSync(target).isFile())
+                        result[reference.path] = path;
+                }
+                catch { /* Unreadable/outside references are rejected during binding. */ }
+            }
     }
     catch { /* Parsing and validation report malformed provider responses. */ }
     return result;
@@ -310,6 +294,11 @@ export function validateCandidate(candidate, inventory, resolveEquivalent) {
     for (const req of candidate.requirements) {
         if (!inputs.has(req.inputRef) || !req.statement?.trim() || req.digest !== contractDigest("statement", req.statement))
             issues.push(`Invalid source/statement ${req.id}`);
+        if (req.verificationIntent !== undefined && req.verificationIntentDigest !== contractDigest("verification-intent-v2", req.verificationIntent)) {
+            issues.push(`Invalid V2 verification intent ${req.id}`);
+        }
+        if (req.verificationIntent === undefined && req.verificationIntentDigest !== undefined)
+            issues.push(`Unexpected V2 verification intent digest ${req.id}`);
         if (req.conflict)
             issues.push(`Unresolved requirement conflict ${req.id}`);
         if (req.authority === "proposed" && req.obligation === "mandatory")

package/dist/readinessGate.js

@@ -1,3 +1,4 @@
+import { parseHostIpc } from "rafi-spec";
 /** Trusted bootstrap: registration and durable authorization precede all provider work. */
 import { WorkflowDb } from "./workflowDb.js";
 import { spawn } from "node:child_process";
@@ -21,7 +22,7 @@ try {
     await new Promise((resolve, reject) => {
         const timer = setTimeout(() => finish(new Error("Readiness authorization timed out")), 10_000);
         const disconnect = () => finish(new Error("Readiness owner disconnected"));
-        const message = (value) => { if (value === "rafi-probe-authorized")
+        const message = (value) => { const ack = parseHostIpc(value); if (ack?.kind === "rafi-probe-authorized" && ack.id === id && ack.pid === process.pid)
             finish(); };
         function finish(error) {
             clearTimeout(timer);
@@ -34,7 +35,7 @@ try {
         }
         process.on("message", message);
         process.once("disconnect", disconnect);
-        process.send({ kind: "rafi-probe-registered", id });
+        process.send({ version: 1, kind: "rafi-probe-registered", id, pid: process.pid });
         if (disconnected)
             disconnect();
     });
@@ -47,11 +48,11 @@ try {
         stdio: [windows ? "pipe" : "ignore", "inherit", "inherit"],
     });
     child.on("error", (error) => {
-        process.send?.({ kind: "rafi-probe-spawn-error", code: error.code, message: error.message });
+        process.send?.({ version: 1, kind: "rafi-probe-spawn-error", id, pid: process.pid, code: error.code ?? null, message: error.message.slice(0, 8192) });
         console.error(error.message);
         process.exitCode = 127;
     });
-    const done = new Promise(resolve => { child.once("exit", (code, signal) => { process.send?.({ kind: "rafi-probe-result", exitCode: code, signal }); process.exitCode = code ?? 1; resolve(); }); child.once("error", () => resolve()); });
+    const done = new Promise(resolve => { child.once("exit", (code, signal) => { process.send?.({ version: 1, kind: "rafi-probe-result", id, pid: process.pid, exitCode: code, signal }); process.exitCode = code ?? 1; resolve(); }); child.once("error", () => resolve()); });
     if (windows) {
         try {
             if (!child.pid)

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;