ai-foreman 1.7.29 → 2.0.0

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,7 @@ 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) {
     const parents = ["", ...readdirSync(sourceRoot, { withFileTypes: true })
             .filter((entry) => entry.isDirectory() && entry.name !== ".git" && entry.name !== "node_modules")
             .flatMap((entry) => {
@@ -491,11 +514,38 @@ 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");
     }
+    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" });
+    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"]);

package/dist/qaStructuredResponse.d.ts

@@ -0,0 +1,10 @@
+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;

package/dist/qaStructuredResponse.js

@@ -0,0 +1,57 @@
+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: {} };
+    }
+}

package/dist/qaTimeline.js

@@ -1,6 +1,6 @@
 import { decisionBelongsToWork } from "./buildInterventions.js";
 import { evidenceRecord } from "./qaEvidenceReader.js";
-import { parseQaResponseContract } from "rafi-spec";
+import { describeLegacyQaTranscript } from "./legacyCommunicationDisplay.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,8 +25,10 @@ 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 classification = contract ? contract.valid ? contract.status : "malformed" : "unavailable";
+        const contract = bytes ? describeLegacyQaTranscript(bytes.toString("utf8")) : undefined;
+        let classification = contract ? contract.valid ? contract.status : "malformed" : "unavailable";
+        if (typeof receipt?.structuredResponseDigest === "string")
+            classification = "unavailable";
         if (slot === "initial" && classification === "malformed")
             counters.malformedResponses++;
         if (slot === "initial" && classification === "blocked")

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/runtimeReadiness.js

@@ -1,3 +1,4 @@
+import { ProbeIpcTracker } from "./probeIpc.js";
 import { fileURLToPath } from "node:url";
 import { cleanupReadiness } from "./readinessCleanup.js";
 import { windowsProbeCommand } from "./windowsProbeJob.js";
@@ -150,26 +151,31 @@ async function probeRuntimeInternal(cwd, runtime, opts) {
         let providerSpawnError;
         let providerResult;
         let startupTimer;
+        const probeMessages = new ProbeIpcTracker(tag, child.pid);
         if (useHost) {
             startupTimer = setTimeout(() => { startupError = new RuntimeCleanupError("Readiness helper startup timed out"); abort(); }, 15_000);
-            child.on("message", message => {
-                if (!message || typeof message !== "object" || !("kind" in message))
+            child.on("message", raw => {
+                if (settled)
+                    return;
+                const message = probeMessages.accept(raw);
+                if (message === "conflict") {
+                    startupError = new RuntimeCleanupError("Readiness helper sent conflicting terminal results");
+                    abort();
+                    return;
+                }
+                if (!message)
                     return;
                 if (message.kind === "rafi-probe-result") {
-                    const reported = message;
-                    if ((reported.exitCode === null || Number.isInteger(reported.exitCode)) && (reported.signal === null || typeof reported.signal === "string")) {
-                        providerResult = reported;
-                        setTimeout(() => { if (!settled) {
-                            child.stdout?.destroy();
-                            child.stderr?.destroy();
-                            void finish(providerResult.exitCode, providerResult.signal);
-                        } }, 100).unref();
-                    }
+                    providerResult = { exitCode: message.exitCode, signal: message.signal };
+                    setTimeout(() => { if (!settled) {
+                        child.stdout?.destroy();
+                        child.stderr?.destroy();
+                        void finish(providerResult.exitCode, providerResult.signal);
+                    } }, 100).unref();
                     return;
                 }
                 if (message.kind === "rafi-probe-spawn-error") {
-                    const reported = message;
-                    providerSpawnError = Object.assign(new Error(reported.message ?? "Provider could not start"), { code: reported.code });
+                    providerSpawnError = Object.assign(new Error(message.message), { code: message.code ?? undefined });
                     return;
                 }
                 if (message.kind !== "rafi-probe-registered")
@@ -186,7 +192,7 @@ async function probeRuntimeInternal(cwd, runtime, opts) {
                     }
                     if (authority && ownedProcess)
                         journal.authorizeReadinessHelper(authority, ownedProcess, child.pid);
-                    child.send("rafi-probe-authorized", error => { if (error) {
+                    child.send({ version: 1, kind: "rafi-probe-authorized", id: tag, pid: child.pid }, error => { if (error) {
                         startupError = error;
                         abort();
                     } });
@@ -204,7 +210,7 @@ async function probeRuntimeInternal(cwd, runtime, opts) {
         const notifySupervisor = (active) => {
             if (process.send && process.connected && process.env.RAFI_BUILD_WORKER_RUN && child.pid) {
                 try {
-                    process.send({ kind: "rafi-readiness-child", active, tag, pid: child.pid, processStart: active ? processStartIdentity(child.pid) : undefined }, () => { });
+                    process.send({ version: 1, kind: "rafi-readiness-child", runId: process.env.RAFI_BUILD_WORKER_RUN, generation: Number(process.env.RAFI_BUILD_WORKER_GENERATION), workerPid: process.pid, active, tag, pid: child.pid, processStart: active ? processStartIdentity(child.pid) ?? null : null }, () => { });
                 }
                 catch { /* Durable ownership survives a disconnected supervisor. */ }
             }
@@ -253,6 +259,8 @@ async function probeRuntimeInternal(cwd, runtime, opts) {
             if (settled)
                 return;
             settled = true;
+            if (useHost && !probeMessages.terminal && !cancelled && !timedOut && !spawnError)
+                startupError ??= new RuntimeCleanupError("Readiness helper exited without a correlated terminal result");
             if (providerResult) {
                 exitCode = providerResult.exitCode;
                 signal = providerResult.signal;

package/dist/statusReporter.d.ts

@@ -74,6 +74,8 @@ export declare class RoleStatusAdapter implements BuilderAdapter {
     private readonly adapter;
     private readonly onActive;
     private readonly onClose;
+    postConfirmedDispatch(reference: import("./adapters/types.js").ConfirmedDispatchReference): Promise<TurnResult | void>;
+    structuredDispatchRequirement(): import("./adapters/types.js").StructuredDispatchRequirement | undefined;
     readonly agent: "claude" | "codex";
     constructor(adapter: BuilderAdapter, onActive: (adapter: BuilderAdapter) => void, onClose: () => void);
     contractCapabilities(): {

package/dist/statusReporter.js

@@ -164,6 +164,8 @@ export class RoleStatusAdapter {
     adapter;
     onActive;
     onClose;
+    postConfirmedDispatch(reference) { return this.adapter.postConfirmedDispatch?.(reference) ?? Promise.resolve(); }
+    structuredDispatchRequirement() { return this.adapter.structuredDispatchRequirement?.(); }
     agent;
     constructor(adapter, onActive, onClose) {
         this.adapter = adapter;

package/dist/structuredCutover.d.ts

@@ -0,0 +1,31 @@
+import type Database from "better-sqlite3";
+export declare const STRUCTURED_CUTOVER = "003_structured_communication_v2_cutover";
+export declare const STRUCTURED_AUDIT_CLOSURE = "004_structured_communication_audit_closure";
+export declare const STRUCTURED_CUTOVER_MATRIX_VERSION = 3;
+export declare const STRUCTURED_CUTOVER_REASON = "structured-communication-v2-cutover";
+export declare const STRUCTURED_AUTHORITY_TABLES: readonly string[];
+type Row = Record<string, any>;
+type ForeignKey = {
+    id: number;
+    seq: number;
+    table: string;
+    from: string;
+    to: string;
+};
+export interface CutoverOwnershipEntry {
+    table: string;
+    disposition: "retain" | "purge-owned";
+    columns: string[];
+    foreignKeys: ForeignKey[];
+    jsonColumns: string[];
+    owner: "retained-artifact" | "run-id" | "foreign-key" | "session-key" | "contract-id" | "json-run-id";
+    evidenceReferenceExtractor: "normalized-refs-with-conservative-unknown-retention";
+    deletionOrder: number | null;
+}
+export declare function cutoverOwnershipMatrix(db: Database.Database): CutoverOwnershipEntry[];
+export declare function assertStructuredCutoverComplete(db: Database.Database): void;
+/** Classification is structural; JSON spelling or merely containing a tuple key is never proof. */
+export declare function invalidStructuredRun(db: Database.Database, run: Row, projectDir?: string): boolean;
+/** Archive then delete only selected rows. Foreign-key closure computes child ownership and deletion order. */
+export declare function purgeStructuredRun(db: Database.Database, runId: string, matrix: CutoverOwnershipEntry[], fileReferences?: ReadonlySet<string>): number;
+export {};