ai-foreman 1.7.19 → 1.7.21

package/dist/processIdentity.js

@@ -1,13 +1,56 @@
 import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { linuxProbeInventory } from "./linuxProbeInventory.js";
+/** Field 2 is parenthesized and may itself contain whitespace/parentheses. */
+export function linuxProcessStart(stat) {
+    const end = stat.lastIndexOf(")");
+    if (end < 0)
+        return undefined;
+    const value = stat.slice(end + 1).trim().split(/\s+/)[19];
+    return value && /^\d+$/.test(value) ? value : undefined;
+}
+export function classifyProcess(pid, expectedStart, host = hostname(), probe = {
+    kill: pid => { process.kill(pid, 0); }, identity: processStartIdentity,
+}) {
+    if (host !== hostname())
+        return { state: "unknown", reason: "owner is on another host" };
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return { state: "unknown", reason: "owner PID is missing or invalid" };
+    try {
+        probe.kill(pid);
+    }
+    catch (error) {
+        return error.code === "ESRCH"
+            ? { state: "dead", reason: "recorded process no longer exists" }
+            : { state: "unknown", reason: "process visibility is unavailable" };
+    }
+    const actual = probe.identity(pid);
+    if (!expectedStart || expectedStart === "unavailable" || actual === "unavailable")
+        return { state: "unknown", reason: "process incarnation cannot be verified" };
+    return actual === expectedStart ? { state: "live", reason: "owner process verified" } : { state: "dead", reason: "PID belongs to a different process incarnation" };
+}
 /**
  * A stable, host-local process incarnation marker. Linux exposes it through
  * procfs; macOS does not, so use `ps lstart` instead. The value is persisted
  * only to detect PID reuse and is never treated as a portable identifier.
  */
-export function processStartIdentity(pid = process.pid) {
+export function processStartIdentity(pid = process.pid, timeoutMs = 5000) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return "unavailable";
+    if (process.platform === "win32") {
+        try {
+            const powershell = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\WindowsPowerShell\\v1.0\\powershell.exe`;
+            const script = `[System.Diagnostics.Process]::GetProcessById(${pid}).StartTime.ToUniversalTime().ToFileTimeUtc()`;
+            const value = execFileSync(powershell, ["-NoProfile", "-NonInteractive", "-Command", script], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: Math.max(1, timeoutMs) }).trim();
+            if (/^\d+$/.test(value))
+                return `win:${value}`;
+        }
+        catch { /* Missing process or unavailable identity remains unverified. */ }
+        return "unavailable";
+    }
     try {
-        const value = readFileSync(`/proc/${pid}/stat`, "utf8").split(" ")[21];
+        const value = linuxProcessStart(readFileSync(`/proc/${pid}/stat`, "utf8"));
         // Preserve the historical Linux representation so an upgrade does not
         // invalidate a lease that was created by the prior release.
         if (value)
@@ -18,7 +61,7 @@ export function processStartIdentity(pid = process.pid) {
     }
     try {
         const value = execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], {
-            encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 1_000,
+            encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: Math.max(1, Math.min(1000, timeoutMs)),
         }).trim();
         if (value)
             return `ps:${value}`;
@@ -30,11 +73,50 @@ export function processStartIdentity(pid = process.pid) {
 }
 /** True only when the PID exists and represents the recorded incarnation. */
 export function isLiveProcessIdentity(pid, expectedStart) {
+    return classifyProcess(pid, expectedStart).state === "live";
+}
+/** Complete local process inventory, including orphan descendants of a known group. */
+export function processGroupQuiescent(group, timeoutMs = 1000) {
+    if (process.platform === "win32" || !Number.isSafeInteger(group) || group <= 1)
+        return false;
+    if (process.platform === "linux") {
+        const rows = linuxProbeInventory(undefined, timeoutMs);
+        return rows !== undefined && rows.filter(row => row.group === group).every(row => row.state === "Z" || row.state === "X");
+    }
     try {
-        process.kill(pid, 0);
-        return expectedStart !== "unavailable" && processStartIdentity(pid) === expectedStart;
+        const rows = execFileSync("ps", ["-axo", "pid=,pgid=,stat="], { encoding: "utf8", timeout: Math.max(1, timeoutMs), maxBuffer: 4 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"] })
+            .split("\n").map(line => /^\s*(\d+)\s+(\d+)\s+(\S+)/.exec(line)).filter(row => row !== null);
+        return rows.some(row => Number(row[1]) === process.pid) && rows.filter(row => Number(row[2]) === group).every(row => row[3].startsWith("Z"));
     }
     catch {
         return false;
     }
 }
+/** Inventory inherited probe tags without exposing process environments in diagnostics.
+ * This covers reparented/setsid children that retain their launch environment.
+ * It is not an OS sandbox: deliberately scrubbed environments cannot be traced.
+ */
+export function taggedProcesses(tag, timeoutMs = 1000) {
+    if (!/^[a-f0-9-]{36}$/.test(tag) || process.platform === "win32")
+        return undefined;
+    if (process.platform === "linux")
+        return linuxProbeInventory(tag, timeoutMs)?.filter(row => row.tagged).map(({ pid, start }) => ({ pid, start }));
+    try {
+        const deadline = Date.now() + timeoutMs;
+        const rows = execFileSync("ps", ["eww", "-axo", "pid=,stat=,command="], { encoding: "utf8", timeout: Math.max(1, timeoutMs), maxBuffer: 16 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"] }).split("\n");
+        if (!rows.some(row => Number(row.trim().split(/\s+/)[0]) === process.pid))
+            return undefined;
+        return rows.flatMap(row => {
+            const match = /^\s*(\d+)\s+(\S+)\s+/.exec(row);
+            if (!match || match[2].startsWith("Z") || !row.includes(`RAFI_PROBE_OWNER=${tag}`))
+                return [];
+            const pid = Number(match[1]);
+            if (Date.now() >= deadline)
+                throw new Error("Tag inventory deadline exceeded");
+            return [{ pid, start: processStartIdentity(pid, deadline - Date.now()) }];
+        });
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/providerPhase.d.ts

@@ -0,0 +1,13 @@
+/** Host-selected provider boundary. Never inferred from agent prose. */
+export type ProviderTurnPurpose = "implementation" | "planning" | "contract-acceptance" | "preparation" | "assessment" | "initialization" | "response-repair";
+export declare class ProviderPhaseBarrier {
+    purpose: ProviderTurnPurpose;
+    private needsRenewal;
+    private enforcing;
+    compactionSequence: number;
+    begin(purpose: ProviderTurnPurpose): void;
+    enableEnforcement(): void;
+    compact(): void;
+    accept(sequence: number): void;
+    denial(tool: string): string | undefined;
+}

package/dist/providerPhase.js

@@ -0,0 +1,26 @@
+export class ProviderPhaseBarrier {
+    purpose = "implementation";
+    needsRenewal = false;
+    enforcing = false;
+    compactionSequence = 0;
+    begin(purpose) { this.purpose = purpose; }
+    enableEnforcement() { if (!this.enforcing)
+        this.needsRenewal = true; this.enforcing = true; }
+    compact() { this.compactionSequence++; if (this.enforcing)
+        this.needsRenewal = true; }
+    accept(sequence) { if (sequence !== this.compactionSequence)
+        throw new Error("Compaction occurred during contract delivery"); this.needsRenewal = false; }
+    denial(tool) {
+        if (this.enforcing && ["Agent", "Task", "TaskOutput"].includes(tool))
+            return "Enforcing Builder cannot delegate mutation outside the contract tool barrier";
+        if (this.needsRenewal)
+            return "Contract delivery renewal required after native compaction; implementation tools paused";
+        if (this.purpose === "implementation")
+            return undefined;
+        if (["contract-acceptance", "initialization", "response-repair"].includes(this.purpose))
+            return "Host response-only phase forbids all tools";
+        if (!["Read", "Glob", "Grep", "ListMcpResourcesTool", "ReadMcpResourceTool"].includes(tool))
+            return "Host planning phase forbids mutation, shell commands, installs, and child agents";
+        return undefined;
+    }
+}

package/dist/qaAuthorizedDisposition.d.ts

@@ -0,0 +1,24 @@
+import type Database from "better-sqlite3";
+import type { QaContractCandidateV1, VerificationCheckV1, VerificationMethod } from "rafi-spec";
+export interface AuthorizedEquivalentV1 {
+    version: 1;
+    kind: "qa-equivalent-verification";
+    runId: string;
+    workId: string;
+    admissionDigest: string;
+    contractId: string;
+    revision: number;
+    checkId: string;
+    expectationDigest: string;
+    method: Omit<VerificationMethod, "equivalentAuthorityId">;
+    reason: string;
+    validity: {
+        runtime: string;
+        expiresAt: string;
+        sourceDigest?: string;
+    };
+}
+export type EquivalentAuthorityResolver = (reference: string, candidate: QaContractCandidateV1, check: VerificationCheckV1, method: VerificationMethod, sourceDigest?: string, nowMs?: number) => boolean;
+export declare function expectationDigest(check: VerificationCheckV1): string;
+/** Only a human answer to an exactly scoped host decision supplies approval. Agent strings never do. */
+export declare function persistedEquivalentResolver(db: Database.Database): EquivalentAuthorityResolver;

package/dist/qaAuthorizedDisposition.js

@@ -0,0 +1,26 @@
+import { canonicalJson } from "./qaProtocolV2.js";
+import { contractDigest } from "./qaVerificationContract.js";
+export function expectationDigest(check) {
+    const { verification: _methods, dispositionRef: _disposition, ...expectation } = check;
+    return contractDigest("equivalent-expectation", expectation);
+}
+/** Only a human answer to an exactly scoped host decision supplies approval. Agent strings never do. */
+export function persistedEquivalentResolver(db) {
+    return (reference, candidate, check, method, sourceDigest, nowMs = Date.now()) => {
+        const row = db.prepare("SELECT decision_json FROM human_decisions WHERE decision_id=? AND run_id=?").get(reference, candidate.runId);
+        if (!row)
+            return false;
+        const decision = JSON.parse(row.decision_json);
+        if (decision.status !== "answered" || decision.selectedChoiceId !== "custom" || !decision.answeredAt || decision.interruptionId !== `qa-equivalent:${candidate.contractId}:${candidate.revision}:${check.id}` || !decision.answer)
+            return false;
+        let authority;
+        try {
+            authority = JSON.parse(decision.answer);
+        }
+        catch {
+            return false;
+        }
+        const { equivalentAuthorityId: _reference, ...concreteMethod } = method;
+        return authority.version === 1 && authority.kind === "qa-equivalent-verification" && authority.runId === candidate.runId && authority.workId === candidate.workId && authority.admissionDigest === candidate.admissionDigest && authority.contractId === candidate.contractId && authority.revision === candidate.revision && authority.checkId === check.id && authority.expectationDigest === expectationDigest(check) && Boolean(authority.reason?.trim()) && canonicalJson(authority.method) === canonicalJson(concreteMethod) && authority.validity?.runtime === method.runtime && Date.parse(authority.validity.expiresAt) > nowMs && (!authority.validity.sourceDigest || authority.validity.sourceDigest === sourceDigest);
+    };
+}

package/dist/qaBuildGate.d.ts

@@ -0,0 +1,4 @@
+import type { BuilderAdapter } from "./adapters/types.js";
+import type { QaSessionHandle } from "./qaReview.js";
+/** Shared by ordinary, branch, synthetic, remediation and Manager followups. */
+export declare function ensureBuilderContract(projectDir: string, runId: string, workId: string, workspace: string, builder: BuilderAdapter, qaFactory?: (cwd: string) => Promise<QaSessionHandle>): Promise<string>;

package/dist/qaBuildGate.js

@@ -0,0 +1,216 @@
+import { resolveQaPreparationConfig } from "./qaPreparationPolicy.js";
+import { createHash } from "node:crypto";
+import { readFileSync, realpathSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { isTicketsInitialized, loadTicketsConfig } from "./tickets/config.js";
+import { loadTickets } from "./tickets/ticketLoader.js";
+import { qaDigest } from "./qaProtocolV2.js";
+import { admittedPlanInput } from "./qaPreparationInputs.js";
+import { checkQaPrerequisites } from "./qaPrerequisites.js";
+import { OperationDeadline } from "./util/deadline.js";
+import { sendPreparationGraphTurn } from "./graph/preparation.js";
+import { withGraphDerivedAccess } from "./graph/derived.js";
+import { WorkflowDb } from "./workflowDb.js";
+import { createRoleBuilder, readOnlyPermissionConfig } from "./agentRun.js";
+import { captureBuildSource, assertBuildAssignmentReconciled } from "./buildAssignment.js";
+import { createDisposableQaSnapshotAsync } from "./qaSnapshot.js";
+import { allocateStableCheckIds, authoritativeInventory, contractDigest, renderVerificationContract } from "./qaVerificationContract.js";
+import { resolveEffectiveQaConfiguration } from "./qaEffectiveConfig.js";
+import { prepareVerificationContract } from "./qaPreparation.js";
+import { actualContractSession, assertContractReceipt, deliverVerificationContract } from "./qaContractDelivery.js";
+import { COVERAGE_INSTRUCTIONS } from "./qaContractCoverage.js";
+import { renderBuildWorkContext } from "./buildWorkContext.js";
+import { compareContractInputs } from "./qaContractFreshness.js";
+/** Shared by ordinary, branch, synthetic, remediation and Manager followups. */
+export async function ensureBuilderContract(projectDir, runId, workId, workspace, builder, qaFactory) {
+    return withGraphDerivedAccess([], () => ensureBuilderContractWithProvenance(projectDir, runId, workId, workspace, builder, qaFactory));
+}
+async function ensureBuilderContractWithProvenance(projectDir, runId, workId, workspace, builder, qaFactory) {
+    const db = new WorkflowDb(projectDir);
+    try {
+        db.ensureRun(runId);
+        const store = db.qaPreparationStore();
+        const policy = store.policy(runId) ?? store.freezePolicy(runId, resolveQaPreparationConfig(undefined));
+        if (policy.mode === "legacy")
+            return "";
+        if (policy.mode === "enforce" && !builder.contractCapabilities?.().nativeCompactionBarrier)
+            throw new Error(`unsupported-capability: ${builder.agent} enforcement requires proven native-compaction delivery continuity`);
+        assertBuildAssignmentReconciled(projectDir, runId, workspace);
+        const admission = db.assertAdmittedWork(runId, workId);
+        const ticket = db.workDefinitions(runId).find(work => work.workId === workId)?.definition;
+        if (!ticket)
+            throw new Error("Preparation requires the frozen admitted work definition");
+        if (admission.kind === "ticket" && isTicketsInitialized(projectDir)) {
+            const current = loadTickets(join(projectDir, loadTicketsConfig(projectDir).paths.tickets)).find(ticket => ticket.id === workId);
+            if (!current || qaDigest("admitted-requirements", current) !== admission.requirementsDigest)
+                throw new Error("Ticket changed from frozen admitted scope; renewed approval is required before preparation or implementation");
+        }
+        const state = db.getRun(runId)?.state;
+        const effective = resolveEffectiveQaConfiguration(projectDir, { make: state?.qa?.settings?.make ?? builder.agent });
+        const configurationEvent = `preparation-configuration:${runId}:${workId}:${effective.digest}`;
+        if (!store.eventRecord(configurationEvent))
+            store.event(runId, workId, configurationEvent, "effective-preparation-configuration", { policy, effectiveDigest: effective.digest, configRoot: effective.configRoot, roleSource: effective.roleSource, provider: builder.agent, capabilities: builder.contractCapabilities?.() ?? null, finalReviewEnabled: db.getRun(runId)?.state?.qaEnabled ?? null });
+        const inputs = [
+            { id: "admitted-ticket", kind: "ticket", reference: admission.assignmentId, digest: contractDigest("input-ticket", ticket), authority: "approved-scope", revision: admission.scopeRevision, availability: "available" },
+            { id: "project-checklist", kind: "checklist", reference: "tickets.build.validation_checklist", digest: contractDigest("input-checklist", effective.checklist), authority: "project-rule", revision: "current", availability: "available" },
+            { id: "effective-rules", kind: "rules", reference: effective.configRoot, digest: effective.digest, authority: "project-rule", revision: "current", availability: "available" },
+            { id: "preparation-policy", kind: "policy", reference: policy.policyVersion, digest: contractDigest("input-policy", policy), authority: "planner-policy", revision: policy.policyVersion, availability: "available" },
+        ];
+        const planInput = admittedPlanInput(projectDir, ticket);
+        if (planInput)
+            inputs.push(planInput.input);
+        const inventory = [...authoritativeInventory(ticket, effective.checklist, inputs), ...(planInput?.requirements ?? [])];
+        for (const [locator, statement] of [["qa-rules", effective.qaRules], ["builder-rules", effective.builderRules], ...effective.skills.map(skill => [`skill:${skill.name}`, skill.content])]) {
+            if (!statement.trim())
+                continue;
+            inventory.push({ id: `req-rules-${contractDigest("rule-identity", { locator, statement }).slice(0, 24)}`, inputRef: "effective-rules", locator, statement, digest: contractDigest("statement", statement), obligation: "mandatory", origin: "explicit", authority: "approved" });
+        }
+        const source = captureBuildSource(workspace);
+        const head = store.head(runId, workId, admission.requirementsDigest);
+        const priorBudget = store.budget(runId, workId, admission.requirementsDigest);
+        if (priorBudget)
+            store.applyAnsweredExtensions(priorBudget);
+        let amendmentPredecessor;
+        if (head.digest) {
+            const old = store.contract(head.digest);
+            const comparison = compareContractInputs(old, inputs);
+            const inputDigest = contractDigest("amended-inputs", inputs);
+            const retainedIntent = priorBudget ? store.progress(priorBudget, "amendment-inputs") : undefined;
+            const changedDuringAmendment = head.state !== "ready" && retainedIntent?.predecessorDigest === old.contentDigest && retainedIntent.inputDigest !== inputDigest;
+            if (comparison.changed.length || comparison.unavailable.length || changedDuringAmendment) {
+                const qaHead = db.qaTicketHead(runId, workId);
+                if (["completed", "waived", "finalizing", "turn-intended", "turn-uncertain", "remediation-intended", "remediation-uncertain"].includes(qaHead.state))
+                    throw new Error("Active or finalized QA authority requires explicit recovery/reopen before contract amendment");
+                const budget = priorBudget;
+                if (retainedIntent?.inputDigest !== inputDigest || retainedIntent.predecessorDigest !== old.contentDigest)
+                    store.beginAmendment(budget, inventory, { reason: `Canonical authorized inputs changed: ${[...comparison.changed, ...comparison.unavailable].join(", ") || "inputs reverted during amendment"}`, inputDigest, predecessorDigest: old.contentDigest });
+                amendmentPredecessor = old.contentDigest;
+            }
+        }
+        const initial = { version: 1, contractId: head.digest ? store.contract(head.digest).contractId : `contract:${contractDigest("contract-family", { runId, workId, admission: admission.requirementsDigest })}`, revision: head.digest ? store.contract(head.digest).revision + (amendmentPredecessor ? 1 : 0) : 1,
+            ...(amendmentPredecessor ? { predecessorDigest: amendmentPredecessor } : {}),
+            runId, workId, admissionDigest: admission.requirementsDigest, depthDecision: ticket.qa_preparation,
+            inputs, baseline: [], requirements: inventory, checks: [], coverage: [], preparationEvidence: [], unresolved: [], createdAt: new Date(priorBudget?.startMs ?? Date.now()).toISOString() };
+        const result = await prepareVerificationContract(initial, inventory, {
+            store, now: Date.now,
+            normalizeDraft: (draft, response) => {
+                const normalized = allocateStableCheckIds(draft);
+                for (const observation of normalized.baseline) {
+                    const original = structuredClone(observation);
+                    observation.sourceDigest = source.digest;
+                    observation.observedAt = new Date().toISOString();
+                    observation.phase = "preimplementation-investigation";
+                    observation.evidenceDigest = store.putArtifact("baseline-observation", { observation: original, sourceDigest: source.digest, operationId: response.operationId, sessionId: response.sessionId, providerReceipt: store.putArtifact("investigation-evidence", response) });
+                }
+                for (const evidence of normalized.preparationEvidence) {
+                    evidence.operationId = response.operationId;
+                    evidence.sessionId = response.sessionId;
+                    delete evidence.graphReceiptRefs;
+                    if (response.graphReceiptRefs?.length)
+                        evidence.graphReceiptRefs = [...response.graphReceiptRefs];
+                    evidence.evidenceDigest = store.putArtifact("investigation-evidence", response);
+                    for (const reference of evidence.references) {
+                        const path = realpathSync(resolve(workspace, reference.path)), root = realpathSync(workspace);
+                        if (!path.startsWith(root + sep))
+                            throw new Error("Inspected source reference escapes actual workspace");
+                        reference.digest = createHash("sha256").update(readFileSync(path)).digest("hex");
+                    }
+                }
+                return normalized;
+            },
+            inputsCurrent: candidate => {
+                if (db.assertAdmittedWork(runId, workId).requirementsDigest !== admission.requirementsDigest)
+                    return false;
+                const current = resolveEffectiveQaConfiguration(projectDir, { make: state?.qa?.settings?.make ?? builder.agent });
+                const compared = compareContractInputs(candidate, inputs.map(input => input.id === "effective-rules" ? { ...input, digest: current.digest } : input.id === "project-checklist" ? { ...input, digest: contractDigest("input-checklist", current.checklist) } : input));
+                return !compared.changed.length && !compared.unavailable.length;
+            },
+            dispatch: async (phase, instruction, operationId, remainingMs) => new OperationDeadline("QA preparation operation", remainingMs).run(async () => {
+                const started = performance.now();
+                const remaining = () => {
+                    const value = remainingMs - (performance.now() - started);
+                    if (value <= 0)
+                        throw new Error("QA preparation deadline expired during session setup; completion is unknown");
+                    return value;
+                };
+                const before = captureBuildSource(workspace);
+                if (phase === "planner") {
+                    const role = await createRoleBuilder({ projectDir: workspace, configRoot: projectDir, role: "planner", label: "QA depth assessment", sandboxMode: "read-only", permissionConfig: readOnlyPermissionConfig(), yes: true, allowSwitch: false });
+                    try {
+                        const turn = await sendPreparationGraphTurn(role.builder, `${instruction}\nFrozen admitted work definition: ${JSON.stringify(ticket)}\nOriginal approved plan context: ${JSON.stringify(planInput?.plan ?? null)}\nFrozen effective configuration: ${JSON.stringify(effective)}`, { phase, projectDir, workspace, sourceRef: before.digest, runId, workId, operationId, remainingMs: remaining() });
+                        store.event(runId, workId, `${operationId}:raw`, "preparation-provider-return", turn);
+                        if (captureBuildSource(workspace).contentDigest !== before.contentDigest)
+                            throw new Error("Product source changed during confined planning; reconcile retained dispatch");
+                        if (turn.isError || turn.failure || !role.builder.sessionId())
+                            throw new Error(`planner-unavailable: ${turn.text}`);
+                        return { text: turn.text, graphReceiptRefs: turn.graphReceiptRefs, sessionId: role.builder.sessionId(), usage: { inputTokens: turn.usage?.scope === "turn-delta" ? turn.usage.inputTokens : turn.inputTokens, outputTokens: turn.usage?.scope === "turn-delta" ? turn.usage.outputTokens : turn.outputTokens, costUsd: turn.costAuthoritative ? turn.costUsd : undefined } };
+                    }
+                    finally {
+                        await role.builder.close();
+                    }
+                }
+                const snapshot = await createDisposableQaSnapshotAsync(workspace);
+                let adapter;
+                try {
+                    remaining();
+                    const prerequisites = await checkQaPrerequisites({ snapshotPath: snapshot.path, sourceDigest: snapshot.frozenState.digest, ticket });
+                    const prerequisiteDigest = db.putEvidence("qa", JSON.stringify(prerequisites));
+                    remaining();
+                    if (qaFactory)
+                        adapter = (await qaFactory(snapshot.path)).adapter;
+                    else
+                        adapter = (await createRoleBuilder({ projectDir: snapshot.path, configRoot: projectDir, role: "qa", agent: state?.qa?.settings?.make ?? builder.agent, preloadedSkillContent: effective.skills.map(skill => ({ name: skill.name, content: skill.content })), label: "QA preparation", sandboxMode: "read-only", permissionConfig: readOnlyPermissionConfig(), yes: true, allowSwitch: false })).builder;
+                    const turn = await sendPreparationGraphTurn(adapter, `${instruction}\nOriginal approved plan context: ${JSON.stringify(planInput?.plan ?? null)}\nFrozen admitted work definition: ${JSON.stringify(ticket)}\nHost early prerequisite observations (host availability is not provider access; classify readiness versus final-only dependencies): ${JSON.stringify({ ...prerequisites, evidenceDigest: prerequisiteDigest })}\nFrozen effective configuration: ${JSON.stringify(effective)}\nOperation: ${operationId}; remaining wall time: ${remainingMs}ms; source: ${source.digest}`, { phase, projectDir, workspace: snapshot.path, accessWorkspace: workspace, sourceRef: snapshot.frozenState.digest, runId, workId, operationId, remainingMs: remaining() });
+                    store.event(runId, workId, `${operationId}:raw`, "preparation-provider-return", turn);
+                    if (turn.isError || turn.failure || !adapter.sessionId())
+                        throw new Error(`Preparation provider unavailable: ${turn.text}`);
+                    if (captureBuildSource(workspace).contentDigest !== before.contentDigest)
+                        throw new Error("Source changed during preparation; retained dispatch requires reconciliation");
+                    return { text: turn.text, graphReceiptRefs: turn.graphReceiptRefs, sessionId: adapter.sessionId(), usage: { inputTokens: turn.usage?.scope === "turn-delta" ? turn.usage.inputTokens : turn.inputTokens, outputTokens: turn.usage?.scope === "turn-delta" ? turn.usage.outputTokens : turn.outputTokens, costUsd: turn.costAuthoritative ? turn.costUsd : undefined } };
+                }
+                finally {
+                    try {
+                        await adapter?.close();
+                    }
+                    finally {
+                        await snapshot.remove();
+                    }
+                }
+            }),
+        });
+        if (result.status !== "ready") {
+            if (policy.mode === "shadow")
+                return "";
+            const budget = store.budget(runId, workId, admission.requirementsDigest);
+            if (budget && /budget exhausted|allowance exhausted|deadline expired/i.test(result.detail)) {
+                const decision = db.ensureHumanDecision({ runId, decisionKey: `qa-preparation-extension:${budget.id}:${budget.deadlineMs}:${budget.extensions.length}`, interruptionId: `qa-preparation:${budget.id}`, prompt: `Preparation allowance exhausted. Additional time/rounds require an operational extension, preserving depth, scope, original start and all consumed/uncertain dispatches. Supply JSON {"budgetId":"${budget.id}","reason":"operator reason","deadlineMs":<absolute epoch milliseconds>,"caps":{"investigation":<total round ceiling>,"assessment":<total round ceiling>}}. Current budget: ${JSON.stringify(budget)}`, choices: [{ id: "custom", label: "Provide a scoped operational extension using --answer" }] });
+                throw new Error(`QA preparation ${result.status}: ${result.detail}. Answer ${decision.decisionId} with rafi build:decide --run ${runId} --decision ${decision.decisionId} --choice custom --answer '<scoped JSON>', then resume. Uncertain dispatches still require reconciliation.`);
+            }
+            throw new Error(`QA preparation ${result.status}: ${result.detail}. ${result.nextAction}`);
+        }
+        amendmentPredecessor = result.contract.predecessorDigest;
+        if (amendmentPredecessor && !store.eventRecord(`amendment:${result.contract.contentDigest}`)) {
+            db.atomic(() => {
+                db.invalidateUnconsumedQaPassCertificates(runId, workId, "contract-amended");
+                db.markQaReportsRecheckRequired(runId, workId, "contract-amended");
+                const qaHead = db.qaTicketHead(runId, workId);
+                db.transitionQa(runId, workId, qaHead.revision, { type: "contract-amended", predecessorDigest: amendmentPredecessor, contractDigest: result.contract.contentDigest, reason: "Canonical authorized input reconciliation" });
+                store.metric(runId, workId, admission.requirementsDigest, `metric:amendment:${result.contract.contentDigest}`, "amendment");
+                store.event(runId, workId, `amendment:${result.contract.contentDigest}`, "contract-amendment", { predecessorDigest: amendmentPredecessor, contractDigest: result.contract.contentDigest, evidenceCarryForward: [], disposition: "All final checks require independent current-source review; no evidence silently carried" });
+            });
+        }
+        if (policy.mode === "shadow")
+            return "";
+        await builder.prepareSession?.();
+        try {
+            assertContractReceipt(store, runId, workId, admission.requirementsDigest, actualContractSession(builder, workspace, projectDir), builder);
+        }
+        catch {
+            await deliverVerificationContract(result.contract, store, builder, workspace, projectDir, renderBuildWorkContext(ticket, effective.checklist));
+        }
+        return `${renderVerificationContract(result.contract)}\n${COVERAGE_INSTRUCTIONS}\nCoverage binding: ${JSON.stringify({ phase: "builder", runId, workId, revision: result.contract.revision, contractDigest: result.contract.contentDigest })}`;
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/qaBuilderCoverage.d.ts

@@ -0,0 +1,5 @@
+import type { BuilderAdapter, TurnResult } from "./adapters/types.js";
+import { WorkflowDb } from "./workflowDb.js";
+/** Claims are collected after source capture so the provider can name the actual completed source. */
+export declare function collectBuilderContractCoverage(projectDir: string, runId: string, workId: string, workspace: string, adapter: BuilderAdapter, operationId: string, instruction: string, implementation: TurnResult): Promise<void>;
+export declare function assertBuilderContractCoverage(db: WorkflowDb, runId: string, workId: string, operationId: string, sourceDigest: string): void;

package/dist/qaBuilderCoverage.js

@@ -0,0 +1,78 @@
+import { dispatchWithGraphAccess, withGraphSessionAccess } from "./graph/session.js";
+import { WorkflowDb } from "./workflowDb.js";
+import { actualContractSession, assertContractReceipt } from "./qaContractDelivery.js";
+import { captureBuildSource } from "./buildAssignment.js";
+import { COVERAGE_INSTRUCTIONS, parseContractCoverage, validateContractCoverage } from "./qaContractCoverage.js";
+import { contractDigest } from "./qaVerificationContract.js";
+import { OperationDeadline } from "./util/deadline.js";
+/** Claims are collected after source capture so the provider can name the actual completed source. */
+export async function collectBuilderContractCoverage(projectDir, runId, workId, workspace, adapter, operationId, instruction, implementation) {
+    return withGraphSessionAccess(projectDir, adapter, () => collectBuilderContractCoverageOwned(projectDir, runId, workId, workspace, adapter, operationId, instruction, implementation));
+}
+async function collectBuilderContractCoverageOwned(projectDir, runId, workId, workspace, adapter, operationId, instruction, implementation) {
+    const db = new WorkflowDb(projectDir);
+    try {
+        const store = db.qaPreparationStore();
+        if (store.policy(runId)?.mode !== "enforce")
+            return;
+        const admission = db.assertAdmittedWork(runId, workId);
+        const session = actualContractSession(adapter, workspace, projectDir);
+        const contract = assertContractReceipt(store, runId, workId, admission.requirementsDigest, session, adapter);
+        const source = captureBuildSource(workspace);
+        const binding = { phase: "builder", sourceDigest: source.digest, inputBasisDigest: contractDigest("builder-input-basis", { operationId, instruction, contractDigest: contract.contentDigest }), attemptId: operationId, sessionId: session.sessionId };
+        const eventId = `builder-coverage:${operationId}`;
+        const existing = db.operation(eventId);
+        if (existing) {
+            if (existing.status !== "confirmed")
+                throw new Error("Uncertain Builder coverage dispatch must be reconciled without redispatch");
+            const retained = existing.result;
+            const errors = validateContractCoverage(contract, store.artifact(retained.coverageDigest, "builder-coverage"), binding, false);
+            if (errors.length)
+                throw new Error(errors.join("; "));
+            return;
+        }
+        // Preserve the implementation response before a failed acknowledgment or a crash.
+        const implementationDigest = db.putEvidence("qa", implementation.rawResponse ?? implementation.text);
+        db.planOperation({ runId, idempotencyKey: eventId, kind: "builder-coverage", intent: { workId, contractDigest: contract.contentDigest, binding, implementationDigest, session } });
+        db.updateOperation(eventId, "in_progress");
+        try {
+            const prompt = `Response-only evidence collection for completed implementation ${operationId}. Do not run tools, modify files, repeat work, or invent verification. Record failed, blocked or not-run truthfully. The implementation response is retained as ${implementationDigest}.\n${COVERAGE_INSTRUCTIONS}\nExact coverage binding: ${JSON.stringify({ version: 1, runId, workId, revision: contract.revision, contractDigest: contract.contentDigest, ...binding })}\nAll checks: ${JSON.stringify(contract.checks)}`;
+            const response = await new OperationDeadline("Builder coverage acknowledgment", 120_000).run(() => dispatchWithGraphAccess(projectDir, adapter, prompt, { purpose: "response-repair", responseOnly: true }, (text, policy) => adapter.sendTurn(text, policy)), () => { void adapter.close(); });
+            const responseDigest = db.putEvidence("qa", response.rawResponse ?? response.text);
+            db.updateOperation(eventId, "uncertain", { result: { responseDigest } });
+            if (response.isError || response.failure)
+                throw new Error("Builder coverage provider failed; retained response requires reconciliation");
+            if (JSON.stringify(actualContractSession(adapter, workspace, projectDir)) !== JSON.stringify(session) || captureBuildSource(workspace).digest !== source.digest)
+                throw new Error("Builder coverage changed session or product source");
+            const coverage = parseContractCoverage(response.text);
+            const errors = validateContractCoverage(contract, coverage, binding, false);
+            if (errors.length)
+                throw new Error(`Builder coverage invalid: ${errors.join("; ")}`);
+            const coverageDigest = store.putArtifact("builder-coverage", coverage);
+            db.updateOperation(eventId, "confirmed", { result: { responseDigest, coverageDigest, binding, implementationDigest } });
+        }
+        catch (error) {
+            throw new Error(`Builder evidence collection blocked: ${String(error)}`);
+        }
+    }
+    finally {
+        db.close();
+    }
+}
+export function assertBuilderContractCoverage(db, runId, workId, operationId, sourceDigest) {
+    const store = db.qaPreparationStore();
+    if (store.policy(runId)?.mode !== "enforce")
+        return;
+    const admission = db.assertAdmittedWork(runId, workId), head = store.head(runId, workId, admission.requirementsDigest);
+    if (head.state !== "ready" || !head.digest)
+        throw new Error("Completion requires the ready contract");
+    const operation = db.operation(`builder-coverage:${operationId}`);
+    if (operation?.status !== "confirmed")
+        throw new Error("Completion requires retained, source-bound Builder check coverage");
+    const result = operation.result;
+    if (result.binding.sourceDigest !== sourceDigest || result.binding.attemptId !== operationId)
+        throw new Error("Builder completion coverage is stale");
+    const errors = validateContractCoverage(store.contract(head.digest), store.artifact(result.coverageDigest, "builder-coverage"), result.binding, false);
+    if (errors.length)
+        throw new Error(errors.join("; "));
+}

package/dist/qaContractCoverage.d.ts

@@ -0,0 +1,10 @@
+import type { QaContractCoverageV1, QaVerificationContractV1 } from "rafi-spec";
+export declare const COVERAGE_INSTRUCTIONS = "Return RAFI_QA_COVERAGE_START, one QaContractCoverageV1 JSON object, RAFI_QA_COVERAGE_END before the final status marker. Include every check ID with independently evaluated applicability, predicate evidence, outcome (passed/failed/blocked/not-run), and concrete procedure/cwd/runtime/sourceDigest/reference evidence. Missing, blocked, not-run, unresolved applicability, or failed mandatory coverage cannot authorize normal completion. Builder coverage is a claim; final QA independently verifies it.";
+export declare function parseContractCoverage(text: string): QaContractCoverageV1;
+export declare function validateContractCoverage(contract: QaVerificationContractV1, coverage: QaContractCoverageV1, binding: {
+    phase: "builder" | "qa";
+    sourceDigest: string;
+    inputBasisDigest: string;
+    attemptId: string;
+    sessionId: string;
+}, requirePass?: boolean): string[];

package/dist/qaContractCoverage.js

@@ -0,0 +1,55 @@
+import { Ajv } from "ajv";
+import { qaContractCoverageV1Schema } from "rafi-spec";
+const coverageSchema = new Ajv({ allErrors: true }).compile(qaContractCoverageV1Schema);
+import { parsePreparationArtifact } from "./qaVerificationContract.js";
+export const COVERAGE_INSTRUCTIONS = `Return RAFI_QA_COVERAGE_START, one QaContractCoverageV1 JSON object, RAFI_QA_COVERAGE_END before the final status marker. Include every check ID with independently evaluated applicability, predicate evidence, outcome (passed/failed/blocked/not-run), and concrete procedure/cwd/runtime/sourceDigest/reference evidence. Missing, blocked, not-run, unresolved applicability, or failed mandatory coverage cannot authorize normal completion. Builder coverage is a claim; final QA independently verifies it.`;
+export function parseContractCoverage(text) { return parsePreparationArtifact(text, "RAFI_QA_COVERAGE"); }
+export function validateContractCoverage(contract, coverage, binding, requirePass = true) {
+    if (!coverageSchema(coverage))
+        return (coverageSchema.errors ?? []).map(error => `${error.instancePath} ${error.message}`);
+    const issues = [];
+    if (coverage.version !== 1 || coverage.runId !== contract.runId || coverage.workId !== contract.workId || coverage.revision !== contract.revision || coverage.contractDigest !== contract.contentDigest)
+        issues.push("Coverage contract/work binding mismatch");
+    for (const key of ["phase", "sourceDigest", "inputBasisDigest", "attemptId", "sessionId"])
+        if (coverage[key] !== binding[key])
+            issues.push(`Coverage ${key} mismatch`);
+    if (!Array.isArray(coverage.checks))
+        return [...issues, "Missing check coverage"];
+    const seen = new Set();
+    for (const row of coverage.checks) {
+        const check = contract.checks.find(check => check.id === row.checkId);
+        if (!check || seen.has(row.checkId)) {
+            issues.push(`Unknown/duplicate coverage ${row.checkId}`);
+            continue;
+        }
+        seen.add(row.checkId);
+        if (!["applicable", "not-applicable", "unresolved"].includes(row.applicability) || !["passed", "failed", "blocked", "not-run"].includes(row.outcome))
+            issues.push(`Illegal coverage state ${row.checkId}`);
+        if (check.applicability.kind === "unconditional" && row.applicability !== "applicable")
+            issues.push(`Unconditional applicability cannot be waived ${row.checkId}`);
+        if (row.applicability === "not-applicable" && !row.predicateEvidence?.length)
+            issues.push(`Not-applicable requires predicate evidence ${row.checkId}`);
+        if (check.applicability.kind === "conditional" && row.applicability === "applicable" && !row.predicateEvidence?.length)
+            issues.push(`Conditional applicability requires predicate evidence ${row.checkId}`);
+        if (requirePass && check.obligation === "mandatory" && (row.applicability === "unresolved" || row.applicability === "applicable" && row.outcome !== "passed"))
+            issues.push(`Mandatory check incomplete ${row.checkId}`);
+        if (!Array.isArray(row.evidence))
+            issues.push(`Missing evidence array ${row.checkId}`);
+        if (row.outcome === "passed" && row.applicability === "applicable") {
+            if (binding.phase === "qa" && check.timing === "preimplementation") {
+                const baseline = contract.baseline.find(observation => observation.checkId === check.id && observation.status === "passed");
+                if (!baseline || !row.evidence?.some(evidence => evidence.reference === baseline.evidenceDigest))
+                    issues.push(`Preimplementation coverage lacks retained baseline authority ${row.checkId}`);
+            }
+            if (!row.evidence?.length)
+                issues.push(`Passing check requires independent evidence ${row.checkId}`);
+            for (const evidence of row.evidence ?? [])
+                if (!evidence.reference?.trim() || !evidence.procedure?.trim() || !evidence.cwd?.trim() || !evidence.runtime?.trim() || check.timing !== "preimplementation" && evidence.sourceDigest !== binding.sourceDigest)
+                    issues.push(`Missing/stale source evidence ${row.checkId}`);
+        }
+    }
+    for (const check of contract.checks)
+        if (!seen.has(check.id))
+            issues.push(`Missing check ${check.id}`);
+    return issues;
+}

package/dist/qaContractDelivery.d.ts

@@ -0,0 +1,23 @@
+import type { QaVerificationContractV1, QaContractDeliveryReceiptV1 } from "rafi-spec";
+import type { BuilderAdapter } from "./adapters/types.js";
+import type { QaPreparationStore } from "./qaPreparationStore.js";
+export interface ContractSessionBinding {
+    provider: string;
+    sessionId: string;
+    generation: number;
+    workspace: string;
+    configRoot: string;
+    compactionSequence: number;
+}
+export declare function actualContractSession(adapter: BuilderAdapter, workspace: string, configRoot: string): ContractSessionBinding;
+export declare function materializeContract(contract: QaVerificationContractV1, workspace: string): {
+    json: string;
+    markdown: string;
+    resourceDigest: string;
+};
+/** Complete retained review inputs, accessible inside the confined QA snapshot. */
+export declare function finalReviewContractContext(contract: QaVerificationContractV1, store: QaPreparationStore, workspace: string, builderClaims?: unknown[]): string;
+export declare function deliverVerificationContract(contract: QaVerificationContractV1, store: QaPreparationStore, adapter: BuilderAdapter, workspace: string, configRoot: string, context: string): Promise<QaContractDeliveryReceiptV1>;
+/** Byte bounded, lossless Unicode transport. Concatenation reconstructs the exact original input. */
+export declare function segmentContractTransport(content: string, maximumBytes?: number): string[];
+export declare function assertContractReceipt(store: QaPreparationStore, runId: string, workId: string, admissionDigest: string, session?: ContractSessionBinding, adapter?: BuilderAdapter): QaVerificationContractV1;