ai-foreman 1.7.28 → 2.0.0

package/dist/buildApproval.d.ts

@@ -7,5 +7,35 @@ export declare function approvedBuildScope(projectDir: string, ticketIds?: reado
 export declare function requiresBuildApproval(projectDir: string, ticketIds: readonly string[] | undefined, explicitYes: boolean, consequences?: Record<string, unknown>): boolean;
 /** Bind decisions to current files so an old answer cannot approve a changed scope. */
 export declare function buildScopeRevision(projectDir: string, consequences?: Record<string, unknown>): string;
+export interface PlanApprovalBinding {
+    planDigest: string;
+    ticketSetDigest: string;
+    ticketDefinitionsDigest: string;
+    scopeRevision: string;
+    workflowConsequenceDigest: string;
+}
+export interface FrozenWorkApprovalBinding {
+    kind: "synthetic";
+    runId: string;
+    workIds: string[];
+    admissionDigest: string;
+    scopeRevision: string;
+}
+/** Unticketed recovery binds existing authorizations, never a fabricated plan. */
+export declare function frozenWorkApprovalBinding(projectDir: string, runId: string, workIds: readonly string[]): FrozenWorkApprovalBinding;
+export declare function validateFrozenWorkApprovalBinding(projectDir: string, runId: string, workIds: readonly string[], binding: FrozenWorkApprovalBinding): {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+/** Compute the exact host-owned inputs covered by a recovery plan approval. */
+export declare function planApprovalBinding(projectDir: string, ticketIds: readonly string[], consequences?: Record<string, unknown>): PlanApprovalBinding;
+export declare function validatePlanApprovalBinding(projectDir: string, ticketIds: readonly string[], approval: PlanApprovalBinding, consequences?: Record<string, unknown>): {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
 /** Reuse a decision only while its source and consequences remain unchanged. */
 export declare function createBuildApprovalGate(projectDir: string, ticketIds: readonly string[] | undefined, explicitYes: boolean, consequences: Record<string, unknown> | undefined, requestApproval: () => Promise<void>): () => Promise<void>;

package/dist/buildApproval.js

@@ -125,6 +125,74 @@ export function buildScopeRevision(projectDir, consequences) {
     });
     return createHash("sha256").update(JSON.stringify([contents, consequences])).digest("hex");
 }
+/** Unticketed recovery binds existing authorizations, never a fabricated plan. */
+export function frozenWorkApprovalBinding(projectDir, runId, workIds) {
+    if (!workIds.length || new Set(workIds).size !== workIds.length)
+        throw new Error("Frozen work approval requires a unique nonempty work scope");
+    const db = new WorkflowDb(projectDir);
+    try {
+        const admissions = [...workIds].sort().map(id => db.assertAdmittedWork(runId, id));
+        if (admissions.some(admission => admission.kind !== "synthetic"))
+            throw new Error("Frozen work approval cannot replace ticket plan approval");
+        return { kind: "synthetic", runId, workIds: [...workIds].sort(), admissionDigest: createHash("sha256").update(canonical(admissions)).digest("hex"), scopeRevision: buildScopeRevision(projectDir) };
+    }
+    finally {
+        db.close();
+    }
+}
+export function validateFrozenWorkApprovalBinding(projectDir, runId, workIds, binding) {
+    try {
+        if (canonical(frozenWorkApprovalBinding(projectDir, runId, workIds)) !== canonical(binding))
+            return { valid: false, reason: "Frozen work authorization, scope or configuration changed" };
+        return { valid: true };
+    }
+    catch (error) {
+        return { valid: false, reason: String(error) };
+    }
+}
+/** Compute the exact host-owned inputs covered by a recovery plan approval. */
+export function planApprovalBinding(projectDir, ticketIds, consequences) {
+    const paths = resolveTicketPaths(loadTicketsConfig(projectDir), projectDir);
+    const all = loadTickets(paths.tickets);
+    const selected = ticketIds.map(id => all.find(ticket => ticket.id === id));
+    if (selected.some(ticket => !ticket))
+        throw new Error("plan approval cannot bind a missing ticket definition");
+    const config = parse(readFileSync(join(projectDir, "rafi-config.yaml"), "utf8"));
+    const docsRoot = config.docs?.root ?? "docs";
+    const plan = JSON.parse(readFileSync(join(projectDir, docsRoot, "rafi-plan.json"), "utf8"));
+    const planDigest = createHash("sha256").update(canonical({ ...plan, content_digest: "" })).digest("hex");
+    const db = new WorkflowDb(projectDir);
+    try {
+        const approved = db.completedPlanApprovals().some(receipt => {
+            const decision = receipt.decisionReceipt;
+            return receipt.planId === plan.plan_id && receipt.revision === plan.revision
+                && receipt.digest === planDigest && decision?.planDigest === planDigest;
+        });
+        if (!approved)
+            throw new Error("current plan has no matching completed host approval");
+    }
+    finally {
+        db.close();
+    }
+    const ticketSetDigest = createHash("sha256").update(canonical([...ticketIds].sort())).digest("hex");
+    const ticketDefinitionsDigest = createHash("sha256").update(canonical(selected.map(ticket => material(ticket)).sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))))).digest("hex");
+    const workflow = { build: config.tickets?.build ?? {}, consequences: consequences ?? {} };
+    const workflowConsequenceDigest = createHash("sha256").update(canonical(workflow)).digest("hex");
+    return { planDigest, ticketSetDigest, ticketDefinitionsDigest, scopeRevision: buildScopeRevision(projectDir, consequences), workflowConsequenceDigest };
+}
+export function validatePlanApprovalBinding(projectDir, ticketIds, approval, consequences) {
+    try {
+        const current = planApprovalBinding(projectDir, ticketIds, consequences);
+        for (const key of ["planDigest", "ticketSetDigest", "ticketDefinitionsDigest", "scopeRevision", "workflowConsequenceDigest"]) {
+            if (current[key] !== approval[key])
+                return { valid: false, reason: `${key} changed` };
+        }
+        return { valid: true };
+    }
+    catch (error) {
+        return { valid: false, reason: `approval inputs unavailable: ${String(error)}` };
+    }
+}
 /** Reuse a decision only while its source and consequences remain unchanged. */
 export function createBuildApprovalGate(projectDir, ticketIds, explicitYes, consequences, requestApproval) {
     let approvedRevision;

package/dist/buildAssignment.d.ts

@@ -17,6 +17,7 @@ export interface BuildAssignmentCapture {
 type BuildSourceState = Pick<FrozenQaSourceState, "digest" | "head" | "contentDigest" | "capturedAt" | "pathInventory" | "stagedDiff" | "unstagedDiff" | "untracked"> & {
     captureMode: "git" | "filesystem";
     omissions?: string[];
+    fileByteLengths?: Record<string, number>;
 };
 export declare class BuildAssignmentRejected extends Error {
 }

package/dist/buildAssignment.js

@@ -1,3 +1,5 @@
+import { operationPayload, operationResponse, operationStatus } from "./structuredOperation.js";
+import { workReportOutput } from "rafi-spec";
 import { assertBuilderContractCoverage } from "./qaBuilderCoverage.js";
 import { resolveEffectiveQaConfiguration } from "./qaEffectiveConfig.js";
 import { contractDigest } from "./qaVerificationContract.js";
@@ -118,7 +120,7 @@ export function prepareInterruptedBuilderSourceContinuation(projectDir, runId) {
                 db.updateOperation(dispatch.idempotencyKey, "failed", { result: { ...receipt, priorResult: dispatch.result }, error: "Interrupted provider outcome remains unknown; verified stopped local execution is replaced by source inspection and fresh QA, without replay" });
             db.updateOperation(assignment.idempotencyKey, "failed", { result: { ...receipt, priorResult: assignment.result }, error: "Interrupted assignment preserved for source-bound continuation; completion is not established" });
             const event = db.appendContinuityEvent({ runId, role: "host", kind: "interrupted_source_reconciled", payload: { ...receipt, dispatchIds: dispatches.map(op => op.idempotencyKey), assignmentId: assignment.idempotencyKey }, authoritativeStateRevision: db.continuityHead(runId, "run")?.authoritativeStateRevision ?? 0 });
-            db.publishContinuityCheckpoint({ runId, role: "builder", state: "current", authoritativeStateRevision: event.authoritativeStateRevision, delta: {
+            db.publishContinuityCheckpoint({ runId, role: "builder", state: "current", hostEventKind: "source-reconciliation", inputCheckpointDigests: [], authoritativeStateRevision: event.authoritativeStateRevision, delta: {
                     version: 1, decisions: [`Continue already-approved ticket ${intent.ticketId} in the SAME build from preserved source; this host reconciliation is not a successful provider turn.`],
                     constraints: ["Never replay the interrupted provider instruction or assume its side effects did not happen. Inspect current files first, implement only missing approved work, and require independent QA. Preserve all completed tickets and accepted QA.", "The predecessor session's compaction history remains unknown; use a validated fresh handoff before any new implementation."],
                     discoveries: [], completedActions: [], evidence: [`Host-observed source digest ${source.digest}; interrupted assignment ${assignment.idempotencyKey}; reconciliation ${reconciliationId}`],
@@ -384,7 +386,23 @@ export function beginBuildAssignment(projectDir, runId, ticketId, worktree, inst
     }
 }
 export function finishBuildAssignment(projectDir, assignment, result, status) {
-    let rejection = result.failure?.dispatchState === "not-sent" ? undefined : validateBuildAssignment(assignment.ticketId, status, result.text);
+    let rejection;
+    if (result.failure?.dispatchState !== "not-sent") {
+        try {
+            const response = operationResponse(result, workReportOutput);
+            if (!["completed", "blocked", "needs-input"].includes(response.result.kind))
+                throw new Error("Unconsumed intermediate assignment result");
+            if (result.structured?.state !== "candidate" || result.structured.dispatchId !== result.turnId)
+                throw new Error("Assignment receipt dispatch mismatch");
+            const nativeStatus = operationStatus(result, workReportOutput, assignment.ticketId);
+            if (nativeStatus.kind !== status.kind || status.ticket && status.ticket !== assignment.ticketId)
+                throw new Error("Assignment status disagrees with the native result");
+            status = nativeStatus;
+        }
+        catch (error) {
+            rejection = `Builder assignment has no valid native result: ${error instanceof Error ? error.message : String(error)}`;
+        }
+    }
     // Source capture can fail after an external turn. Keep the response even then.
     let after;
     let sourceError;
@@ -408,12 +426,13 @@ export function finishBuildAssignment(projectDir, assignment, result, status) {
                 }
             }
             const responseDigest = db.putEvidence("qa", Buffer.from(result.rawResponse ?? result.text));
+            const structuredResponseDigest = result.structured ? db.putEvidence("qa", Buffer.from(JSON.stringify(result.structured))) : undefined;
             const cleanedResponseDigest = db.putEvidence("qa", Buffer.from(result.cleanedResponse ?? result.text));
             const providerInstructionDigest = result.providerInstruction ? db.putEvidence("qa", Buffer.from(result.providerInstruction)) : undefined;
-            db.updateOperation(assignment.operationId, result.failure?.dispatchState === "unknown" || result.isError && !result.failure?.dispatchState && status.kind === "unknown" ? "uncertain" : "confirmed", { result: { turnId: result.turnId, responseDigest, cleanedResponseDigest, providerInstructionDigest, providerMetadata: result.providerMetadata, dispatchState: result.failure?.dispatchState, status, rejection, sourceError, after: after ? retainSource(db, after) : undefined } });
+            db.updateOperation(assignment.operationId, result.failure?.dispatchState === "unknown" || result.isError && !result.failure?.dispatchState && status.kind === "unknown" ? "uncertain" : "confirmed", { result: { turnId: result.turnId, responseDigest, structuredResponseDigest, cleanedResponseDigest, providerInstructionDigest, providerMetadata: result.providerMetadata, dispatchState: result.failure?.dispatchState, status, rejection, sourceError, after: after ? retainSource(db, after) : undefined } });
             const admission = db.assertAdmittedWork(assignment.runId, assignment.ticketId);
             db.qaPreparationStore().metric(assignment.runId, assignment.ticketId, admission.requirementsDigest, `metric:builder-result:${assignment.operationId}`, "phase-observation", { phase: "builder", durationMs: Math.max(0, Date.now() - Date.parse(assignment.before.capturedAt)), costUsd: result.costAuthoritative ? result.costUsd : null, inputTokens: result.inputTokens ?? null, outputTokens: result.outputTokens ?? null });
-            db.finishGuidance(assignment.guidanceIds, "builder", { submitted: result.failure?.dispatchState === "not-sent" ? false : result.turnId ? true : undefined, receipt: result.turnId ? { turnId: result.turnId, responseDigest, providerInstructionDigest, postSourceDigest: after?.digest } : undefined, applied: !rejection && status.kind === "done" && assignment.guidanceIds.every(id => result.text.includes(id)) });
+            db.finishGuidance(assignment.guidanceIds, "builder", { submitted: result.failure?.dispatchState === "not-sent" ? false : result.turnId ? true : undefined, receipt: result.turnId ? { turnId: result.turnId, responseDigest, providerInstructionDigest, postSourceDigest: after?.digest } : undefined, applied: !rejection && status.kind === "done" });
             if (rejection || sourceError) {
                 const run = db.getRun(assignment.runId);
                 db.transition(assignment.runId, { checkpoint: "build-assignment-rejected", state: { ...run.state, assignmentConflict: { operationId: assignment.operationId, ticketId: assignment.ticketId, worktree: assignment.worktree, responseDigest, rejection, sourceError } }, event: "build_assignment_rejected", payload: { operationId: assignment.operationId, ticketId: assignment.ticketId, returnedTicketId: status.ticket, responseDigest, rejection, sourceError } });
@@ -425,7 +444,7 @@ export function finishBuildAssignment(projectDir, assignment, result, status) {
     }
     if (!rejection && !sourceError && !result.isError && status.kind === "done" && after) {
         try {
-            queueGraphMaintenance(projectDir, assignment.worktree, assignment.operationId, result.text, after.contentDigest !== assignment.before.contentDigest);
+            queueGraphMaintenance(projectDir, assignment.worktree, assignment.operationId, operationPayload(result, workReportOutput).graphMaintenance === "meaningful-indexed-change", after.contentDigest !== assignment.before.contentDigest);
         }
         catch (error) {
             console.error(`Graph maintenance deferred: ${String(error)}`);
@@ -436,7 +455,7 @@ export function finishBuildAssignment(projectDir, assignment, result, status) {
 function retainSource(db, source) {
     const staged = retainDiff(db, source.stagedDiff);
     const unstaged = retainDiff(db, source.unstagedDiff);
-    return { digest: source.digest, head: source.head, captureMode: source.captureMode, omissions: source.omissions, contentDigest: source.contentDigest, capturedAt: source.capturedAt, pathInventory: source.pathInventory,
+    return { digest: source.digest, head: source.head, captureMode: source.captureMode, omissions: source.omissions, contentDigest: source.contentDigest, capturedAt: source.capturedAt, pathInventory: source.pathInventory, fileByteLengths: source.fileByteLengths,
         stagedDiffDigest: staged.digest, stagedDiffChunks: staged.chunks, stagedDiffBytes: source.stagedDiff.length,
         unstagedDiffDigest: unstaged.digest, unstagedDiffChunks: unstaged.chunks, unstagedDiffBytes: source.unstagedDiff.length,
         untracked: source.untracked.map(file => { const evidence = retainDiff(db, file.bytes); return { path: file.path, mode: file.mode, kind: file.kind, digest: file.digest, evidenceDigest: evidence.digest, evidenceChunks: evidence.chunks, byteLength: file.bytes.length }; }) };
@@ -452,31 +471,71 @@ function retainDiff(db, bytes) {
 }
 export function captureBuildSource(worktree) {
     const head = spawnSync("git", ["-C", worktree, "rev-parse", "--verify", "HEAD"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
-    if (head.status === 0)
-        return { ...captureFrozenQaSource(worktree), captureMode: "git" };
+    if (head.status === 0) {
+        const source = captureFrozenQaSource(worktree);
+        // Length is only a hint for comparing a final prefix with the already
+        // digest-bound baseline hash. A stale length can never manufacture a match.
+        const fileByteLengths = {};
+        for (const item of source.pathInventory) {
+            if (!item.worktreeObject?.startsWith("file:"))
+                continue;
+            try {
+                const stat = lstatSync(join(worktree, item.path));
+                if (stat.isFile())
+                    fileByteLengths[item.path] = stat.size;
+            }
+            catch { /* unavailable comparison stays explicit */ }
+        }
+        return { ...source, captureMode: "git", fileByteLengths };
+    }
     if (head.error?.code !== "ENOENT" && !/not a git repository|Needed a single revision|unknown revision/.test(head.stderr ?? ""))
         throw head.error ?? new Error(`Git source identity is unavailable: ${head.stderr}`);
     const capture = () => {
         const root = resolve(worktree);
         const untracked = [];
-        const ignored = new Set([".git", ".rafi", ".foreman", "node_modules"]);
-        const visit = (directory) => {
-            for (const entry of readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
-                if (ignored.has(entry.name))
+        const gitPaths = spawnSync("git", ["-C", root, "ls-files", "--others", "--exclude-standard", "-z"], { encoding: "buffer", stdio: ["ignore", "pipe", "pipe"] });
+        if (gitPaths.status === 0) {
+            for (const path of gitPaths.stdout.toString().split("\0").filter(Boolean).sort()) {
+                if (path === ".foreman" || path.startsWith(".foreman/") || path === ".rafi" || path.startsWith(".rafi/"))
                     continue;
-                const path = join(directory, entry.name);
-                if (entry.isDirectory())
-                    visit(path);
-                else if (entry.isFile() || entry.isSymbolicLink()) {
-                    const kind = entry.isSymbolicLink() ? "symlink" : "file";
-                    const bytes = kind === "symlink" ? Buffer.from(readlinkSync(path)) : readFileSync(path);
-                    untracked.push({ path: relative(root, path).replace(/\\/g, "/"), kind, bytes, mode: lstatSync(path).mode, digest: createHash("sha256").update(bytes).digest("hex") });
+                const absolute = join(root, path);
+                let stat;
+                try {
+                    stat = lstatSync(absolute);
                 }
-                else
-                    throw new Error(`Unsupported source path type: ${path}`);
+                catch {
+                    continue;
+                }
+                // Git reports an untracked nested repository as its directory. It is
+                // a separate source boundary, not a reason to recursively hash its
+                // entire checkout (MoneyTree's vendor/reference trees can be GBs).
+                if (!stat.isFile() && !stat.isSymbolicLink())
+                    continue;
+                const kind = stat.isSymbolicLink() ? "symlink" : "file";
+                const bytes = kind === "symlink" ? Buffer.from(readlinkSync(absolute)) : readFileSync(absolute);
+                untracked.push({ path, kind, bytes, mode: stat.mode, digest: createHash("sha256").update(bytes).digest("hex") });
             }
-        };
-        visit(root);
+        }
+        else {
+            const ignored = new Set([".git", ".rafi", ".foreman", "node_modules"]);
+            const visit = (directory) => {
+                for (const entry of readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+                    if (ignored.has(entry.name))
+                        continue;
+                    const path = join(directory, entry.name);
+                    if (entry.isDirectory())
+                        visit(path);
+                    else if (entry.isFile() || entry.isSymbolicLink()) {
+                        const kind = entry.isSymbolicLink() ? "symlink" : "file";
+                        const bytes = kind === "symlink" ? Buffer.from(readlinkSync(path)) : readFileSync(path);
+                        untracked.push({ path: relative(root, path).replace(/\\/g, "/"), kind, bytes, mode: lstatSync(path).mode, digest: createHash("sha256").update(bytes).digest("hex") });
+                    }
+                    else
+                        throw new Error(`Unsupported source path type: ${path}`);
+                }
+            };
+            visit(root);
+        }
         const contentDigest = createHash("sha256").update(JSON.stringify(untracked.map(({ bytes: _, ...identity }) => identity))).digest("hex");
         return { digest: contentDigest, head: "unavailable", captureMode: "filesystem", omissions: ["Git baseline/diff unavailable: project is not a repository or has no first commit"], contentDigest, capturedAt: new Date().toISOString(),
             pathInventory: untracked.map(file => ({ path: file.path, staged: [], unstaged: [], untracked: { kind: file.kind, mode: file.mode, digest: file.digest } })), untracked, stagedDiff: Buffer.alloc(0), unstagedDiff: Buffer.alloc(0) };

package/dist/buildInterventions.d.ts

@@ -72,7 +72,7 @@ export declare function verifyBuilderGuidance(db: Database.Database, ids: string
     certificateId: string;
     sourceStateDigest: string;
     reviewBasisDigest: string;
-}, response: string, turnReceiptDigest: string): void;
+}, response: string | readonly string[], turnReceiptDigest: string): void;
 /** Called only inside the owning process's existing dispatch transaction. */
 export declare function reserveGuidance(db: Database.Database, runId: string, workId: string, recipient: InstructionRecipient, operationId: string, sourceDigest: string, instructionText: string, reserve?: boolean): {
     text: string;
@@ -87,4 +87,4 @@ export declare function verifyGuidance(db: Database.Database, ids: string[], cer
     certificateId: string;
     sourceStateDigest: string;
     reviewBasisDigest: string;
-}, response: string): void;
+}, response: string | readonly string[]): void;

package/dist/buildInterventions.js

@@ -4,6 +4,8 @@ import { join } from "node:path";
 import { realpathSync as realpath } from "node:fs";
 import { validateManagerActionRequestV1 } from "rafi-spec";
 import { registerHandbackWriter } from "./qaHandbackMigration.js";
+import { registerQaGraphJournalWriter } from "./qaDeliveryJournal.js";
+import { assertStructuredCutoverComplete, STRUCTURED_CUTOVER_REASON } from "./structuredCutover.js";
 import { assertAdmittedWork } from "./buildWorkAdmission.js";
 export class BuildControlBoundary extends Error {
 }
@@ -81,6 +83,11 @@ export class BuildInterventionControl {
         this.db = new Database(join(projectDir, ".rafi/recovery.sqlite3"), { fileMustExist: true });
         try {
             registerHandbackWriter(this.db);
+            registerQaGraphJournalWriter(this.db);
+            assertStructuredCutoverComplete(this.db);
+            const run = this.db.prepare("SELECT legacy,checkpoint,state_json FROM workflow_runs WHERE run_id=?").get(runId);
+            if (!run || run.legacy || run.checkpoint === STRUCTURED_CUTOVER_REASON || JSON.parse(run.state_json).structuredCommunicationCutover)
+                throw new Error("Cutover workflow cannot receive Manager controls");
             if (this.db.pragma("user_version", { simple: true }) !== 4)
                 throw new Error("Manager controls require the work-admission upgrade");
             const project = this.db.prepare("SELECT canonical_root FROM build_project_identity").get();
@@ -259,10 +266,10 @@ export function assertFinalizationControls(db, runId, workId) {
 export function builderVerificationContext(db, runId, workId, sourceDigest) {
     const records = db.prepare("SELECT instruction_id FROM build_instructions WHERE run_id=? AND work_id=? ORDER BY sequence").all(runId, workId).map(row => instruction(db, row.instruction_id));
     const eligible = records.filter(record => (record.request.action === "guide_builder" || record.request.action === "supersede" && !record.deliveries.some(delivery => delivery.recipient === "qa")) && record.deliveries.some(delivery => delivery.recipient === "builder" && ["acknowledged", "applied"].includes(delivery.state) && delivery.receipt?.postSourceDigest === sourceDigest));
-    return { ids: eligible.map(record => record.instructionId), text: eligible.length ? "\n\nBuilder guidance awaiting independent verification on this exact source:\n" + eligible.map(record => `Instruction ${record.instructionId}: ${record.request.text}`).join("\n") + "\nOnly for a relevant result independently established with supporting evidence, emit MANAGER_INSTRUCTION_VERIFIED: <instruction ID>. A general pass alone is insufficient." : "" };
+    return { ids: eligible.map(record => record.instructionId), text: eligible.length ? "\n\nBuilder guidance awaiting independent verification on this exact source:\n" + eligible.map(record => `Instruction ${record.instructionId}: ${record.request.text}`).join("\n") + "\nOnly for a relevant result independently established with supporting evidence, include the exact instruction ID in the native qa-verdict payload.verifiedInstructionIds array. A general pass alone is insufficient." : "" };
 }
 export function verifyBuilderGuidance(db, ids, certificate, response, turnReceiptDigest) {
-    const verified = new Set([...response.matchAll(/^MANAGER_INSTRUCTION_VERIFIED:\s*([A-Za-z0-9_.:-]+)\s*$/gm)].map(match => match[1]));
+    const verified = new Set(typeof response === "string" ? [...response.matchAll(/^MANAGER_INSTRUCTION_VERIFIED:\s*([A-Za-z0-9_.:-]+)\s*$/gm)].map(match => match[1]) : response);
     for (const id of ids) {
         if (!verified.has(id))
             continue;
@@ -298,7 +305,7 @@ export function reserveGuidance(db, runId, workId, recipient, operationId, sourc
                 throw new BuildControlBoundary("Both-agent guidance is waiting for Builder's scoped response before a fresh QA review");
             selected.push(record);
         }
-        const text = instructionText + (selected.length ? "\n\nAuthorized one-use Manager guidance (mandatory requirements and findings still apply):\n" + selected.map(record => `Instruction ${record.instructionId} (${record.textDigest}):\n${record.request.text}`).join("\n\n") + (recipient === "qa" ? "\nFor each instruction whose relevant result you independently established on this source, include MANAGER_INSTRUCTION_VERIFIED: <instruction ID> with the supporting verification evidence. A general passing review alone does not verify an unrelated instruction." : "\nReport each instruction ID whose requested action you applied, with evidence; delivery alone is not independent verification.") : "");
+        const text = instructionText + (selected.length ? "\n\nAuthorized one-use Manager guidance (mandatory requirements and findings still apply):\n" + selected.map(record => `Instruction ${record.instructionId} (${record.textDigest}):\n${record.request.text}`).join("\n\n") + (recipient === "qa" ? "\nFor each instruction whose relevant result you independently established on this source, include the exact instruction ID in payload.verifiedInstructionIds with the supporting verification evidence. A general passing review alone does not verify an unrelated instruction." : "\nReport each instruction ID whose requested action you applied, with evidence; delivery alone is not independent verification.") : "");
         if (reserve)
             for (const record of selected)
                 setDelivery(db, record.instructionId, { recipient, state: "reserved", operationId: `${operationId}:${record.instructionId}:${recipient}`, sourceDigest, instructionDigest: hash(text) });
@@ -315,7 +322,7 @@ export function finishGuidance(db, ids, recipient, result) {
     } }).immediate();
 }
 export function verifyGuidance(db, ids, certificate, response) {
-    const verified = new Set([...response.matchAll(/^MANAGER_INSTRUCTION_VERIFIED:\s*([A-Za-z0-9_.:-]+)\s*$/gm)].map(match => match[1]));
+    const verified = new Set(typeof response === "string" ? [...response.matchAll(/^MANAGER_INSTRUCTION_VERIFIED:\s*([A-Za-z0-9_.:-]+)\s*$/gm)].map(match => match[1]) : response);
     for (const id of ids) {
         if (!verified.has(id))
             continue;

package/dist/buildLaunchGate.js

@@ -1,3 +1,4 @@
+import { parseHostIpc } from "rafi-spec";
 /** Minimal pre-CLI child. No providers or mutable workflow code before acknowledgement. */
 import { WorkflowDb } from "./workflowDb.js";
 import { pathToFileURL } from "node:url";
@@ -14,7 +15,7 @@ finally {
 await new Promise((resolve, reject) => {
     const timeout = setTimeout(() => finish(new Error("Resume startup acknowledgement timed out")), 10_000);
     const disconnected = () => finish(new Error("Resume launcher exited before acknowledgement"));
-    const message = (value) => { if (value === "rafi-launch-ack")
+    const message = (value) => { const ack = parseHostIpc(value); if (ack?.kind === "rafi-launch-ack" && ack.token === token && ack.pid === process.pid)
         finish(); };
     function finish(error) {
         clearTimeout(timeout);
@@ -27,7 +28,7 @@ await new Promise((resolve, reject) => {
     }
     process.once("disconnect", disconnected);
     process.on("message", message);
-    process.send({ kind: "rafi-launch-registered", token });
+    process.send({ version: 1, kind: "rafi-launch-registered", token, pid: process.pid });
 });
 // The durable claim still validates the token atomically after acknowledgement.
 if (!process.env.RAFI_BUILD_WORKER_RUN)

package/dist/builderGuidanceFollowup.js

@@ -1,9 +1,11 @@
 import { collectBuilderContractCoverage } from "./qaBuilderCoverage.js";
+import { observeHostBuilderTests } from "./qaBuilderEvidence.js";
 import { maintainGraphTask } from "./graph/boundary.js";
 import { ensureBuilderContract } from "./qaBuildGate.js";
 import { graphContext, sendGraphTurn } from "./graph/turn.js";
-import { beginBuildAssignment, finishBuildAssignment } from "./buildAssignment.js";
-import { parseStepStatus } from "./foreman.js";
+import { beginBuildAssignment, captureBuildSource, finishBuildAssignment } from "./buildAssignment.js";
+import { workReportOutput } from "rafi-spec";
+import { nativePolicy, operationInstruction, operationStatus } from "./structuredOperation.js";
 /** One journaled mutation shared by current-branch and isolated-worktree resume. */
 export async function deliverBuilderGuidanceFollowup(scope, instruction, followup, host) {
     try {
@@ -14,17 +16,26 @@ export async function deliverBuilderGuidanceFollowup(scope, instruction, followu
         instruction += "\n" + await ensureBuilderContract(scope.projectDir, scope.runId, scope.ticketId, scope.worktree, adapter);
         const assignment = beginBuildAssignment(scope.projectDir, scope.runId, scope.ticketId, scope.worktree, instruction, followup, adapter);
         // The handback policy prevents provider wrappers from retrying this mutation.
-        const result = await sendGraphTurn(adapter, assignment.instruction, graphContext(scope.projectDir, scope.worktree, "manager-guidance", assignment.instruction, { logicalTaskId: assignment.operationId, operationId: assignment.operationId, runId: scope.runId, workId: scope.ticketId }), { handback: true, logicalActionId: assignment.operationId });
-        const status = parseStepStatus(result.text);
+        const hostToolObservations = [];
+        const initialSourceDigest = captureBuildSource(scope.worktree).digest;
+        const stopHostObservation = observeHostBuilderTests(adapter, scope.worktree, hostToolObservations);
+        let result;
+        try {
+            result = await sendGraphTurn(adapter, `${assignment.instruction}\n${operationInstruction(workReportOutput)}`, graphContext(scope.projectDir, scope.worktree, "manager-guidance", assignment.instruction, { logicalTaskId: assignment.operationId, operationId: assignment.operationId, runId: scope.runId, workId: scope.ticketId }), nativePolicy(workReportOutput, { handback: true, logicalActionId: assignment.operationId, journalRunId: scope.runId }));
+        }
+        finally {
+            stopHostObservation();
+        }
+        const status = operationStatus(result, workReportOutput, scope.ticketId);
         if (!result.isError && !result.failure && status.kind === "done")
-            await collectBuilderContractCoverage(scope.projectDir, scope.runId, scope.ticketId, scope.worktree, adapter, assignment.operationId, assignment.instruction, result);
+            await collectBuilderContractCoverage(scope.projectDir, scope.runId, scope.ticketId, scope.worktree, adapter, assignment.operationId, assignment.instruction, result, hostToolObservations, initialSourceDigest);
         const rejection = finishBuildAssignment(scope.projectDir, assignment, result, status);
         if (!rejection && !result.isError && status.kind === "done")
             await maintainGraphTask(scope.projectDir, scope.worktree, assignment.operationId, adapter).catch(() => undefined);
         await host.completed?.(assignment.operationId, adapter);
         if (rejection || result.isError || result.failure || status.kind !== "done" || !result.turnId)
             return { ok: false, detail: rejection ?? result.failure?.diagnostics ?? `Builder follow-up stopped with ${status.kind}; reconcile its result before continuing`, response: result.text };
-        return { ok: true, response: result.text, summary: status.summary ?? "Builder applied waiting guidance", providerTurnId: result.turnId };
+        return { ok: true, outcome: "remediation-reported", response: result.text, summary: status.summary ?? "Builder applied waiting guidance", providerTurnId: result.turnId };
     }
     catch (error) {
         // A thrown submission leaves the assignment in progress. The existing

package/dist/cli/manager.js

@@ -1,5 +1,7 @@
+import { managerOutput } from "rafi-spec";
+import { nativePolicy, operationInstruction, operationResponse } from "../structuredOperation.js";
 import { dispatchWithGraphAccess } from "../graph/session.js";
-import { createManagerGraphEvidence, parseManagerGraphRequest } from "../graph/manager.js";
+import { createManagerGraphEvidence } from "../graph/manager.js";
 import { prepareOwnershipRepair, repairOwnership } from "../buildOwnershipRepair.js";
 import { BuildInterventionControl, parseManagerAction } from "../buildInterventions.js";
 import { randomUUID } from "node:crypto";
@@ -9,14 +11,14 @@ import { resolve } from "node:path";
 import { join } from "node:path";
 import { mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { ManagerEvidenceService, parseManagerEvidenceRequestV2 } from "../managerEvidence.js";
+import { ManagerEvidenceService } from "../managerEvidence.js";
 import { buildManagerEvidencePacketV2 } from "../managerPacket.js";
 import { Command } from "commander";
 import { createRoleBuilder, readOnlyPermissionConfig } from "../agentRun.js";
 import { Log } from "../log.js";
 import { buildManagerEvidencePacket, buildManagerProjectPacket } from "../managerPacket.js";
 import { ManagerSessionRecorder } from "../observability.js";
-import { collectManagerProjectDiagnostics, executeManagerEvidenceRequest, MANAGER_LOOKUP_MAX_ROUNDS, parseManagerEvidenceRequest, resolveManagerQuestionRuns } from "../projectDiagnostics.js";
+import { collectManagerProjectDiagnostics, executeManagerEvidenceRequest, MANAGER_LOOKUP_MAX_ROUNDS, resolveManagerQuestionRuns } from "../projectDiagnostics.js";
 import { accent, sanitizeTerminalText } from "../terminalStyle.js";
 export function buildManagerCommand(options = {}) {
     return new Command("manager")
@@ -87,11 +89,16 @@ export async function runManager(projectDir, options) {
             const packet = buildManagerProjectPacket(report, question, packetState, referencedRunIds);
             packetState = packet.state;
             const graphEvidence = createManagerGraphEvidence(projectDir, currentFocusRunId);
-            const send = (text) => dispatchWithGraphAccess(projectDir, activeRole.builder, text, undefined, (prompt, policy) => activeRole.builder.sendTurn(prompt, policy), graphEvidence.access());
+            const send = async (text) => {
+                const turn = await dispatchWithGraphAccess(projectDir, activeRole.builder, `${text}\n${operationInstruction(managerOutput)}`, nativePolicy(managerOutput, { responseOnly: true }), (prompt, policy) => activeRole.builder.sendTurn(prompt, policy), graphEvidence.access());
+                if (turn.isError || turn.failure)
+                    throw new Error("Manager operation failed; no answer accepted");
+                return operationResponse(turn, managerOutput).result;
+            };
             let result = await send(`${packet.prompt}\n\n${graphEvidence.guidance}`);
             let questionLookupRounds = 0;
             while (questionLookupRounds < MANAGER_LOOKUP_MAX_ROUNDS) {
-                const graphRequest = parseManagerGraphRequest(result.text);
+                const graphRequest = (result.kind === "evidence-request" && result.evidenceType === "graph" ? result.request : undefined);
                 if (graphRequest) {
                     questionLookupRounds++;
                     lookupRounds++;
@@ -100,7 +107,7 @@ export async function runManager(projectDir, options) {
                     result = await send(`Untrusted host-scoped graph evidence; verify claims against source. Remaining lookup rounds: ${MANAGER_LOOKUP_MAX_ROUNDS - questionLookupRounds}. Answer the original question: ${question}\n${graphPacket}`);
                     continue;
                 }
-                const evidenceRequest = parseManagerEvidenceRequestV2(result.text);
+                const evidenceRequest = (result.kind === "evidence-request" && result.evidenceType === "qa" ? result.request : undefined);
                 if (evidenceRequest) {
                     questionLookupRounds++;
                     lookupRounds++;
@@ -120,15 +127,9 @@ export async function runManager(projectDir, options) {
                     result = await send(buildManagerEvidencePacketV2(response, question));
                     continue;
                 }
-                const request = parseManagerEvidenceRequest(result.text);
-                if (!request) {
-                    if (!looksLikeEvidenceRequest(result.text))
-                        break;
-                    questionLookupRounds += 1;
-                    lookupRounds += 1;
-                    result = await send(buildManagerEvidencePacket({ version: 1, requestId: "invalid-request", results: [{ kind: "list_runs", status: "invalid", limitation: "The evidence envelope was invalid. Use only the documented fixed fields and read-only operations, then answer with any remaining limitation disclosed." }], lookupRound: questionLookupRounds, remainingRounds: MANAGER_LOOKUP_MAX_ROUNDS - questionLookupRounds, digest: report.digest }, question));
-                    continue;
-                }
+                const request = (result.kind === "evidence-request" && result.evidenceType === "run" ? result.request : undefined);
+                if (!request)
+                    break;
                 questionLookupRounds += 1;
                 lookupRounds += 1;
                 lookupOperations += Math.min(6, request.operations.length);
@@ -136,8 +137,8 @@ export async function runManager(projectDir, options) {
                 packetState.lastEvidenceScope = request.operations.flatMap(operation => "runIds" in operation ? operation.runIds : []);
                 result = await send(buildManagerEvidencePacket(response, question));
             }
-            const unfulfilled = parseManagerEvidenceRequest(result.text);
-            const pendingEvidence = parseManagerEvidenceRequestV2(result.text);
+            const unfulfilled = (result.kind === "evidence-request" && result.evidenceType === "run" ? result.request : undefined);
+            const pendingEvidence = (result.kind === "evidence-request" && result.evidenceType === "qa" ? result.request : undefined);
             if (pendingEvidence) {
                 const page = evidence.execute(pendingEvidence);
                 if (options.ask) {
@@ -152,9 +153,10 @@ export async function runManager(projectDir, options) {
                 result = await send(buildManagerEvidencePacket(limitation, question));
             }
             if (!pendingEvidence) {
-                const answer = parseManagerEvidenceRequest(result.text) || parseManagerGraphRequest(result.text) || looksLikeEvidenceRequest(result.text)
-                    ? "Manager could not complete an answer within the bounded evidence lookup budget. Continue with /qa-attempts <run> <ticket> or /qa-report <run> <ticket> <attempt>."
-                    : result.text.trim();
+                const answer = result.kind === "completed" ? result.payload.answer
+                    : result.kind === "blocked" ? `${result.reason} Next: ${result.nextAction}`
+                        : result.kind === "needs-input" ? result.question
+                            : "Manager could not complete an answer within the bounded evidence lookup budget. Continue with /qa-attempts <run> <ticket> or /qa-report <run> <ticket> <attempt>.";
                 // One-shot evidence requests can mix JSON with prose, so add the label
                 // only when this answer stream has not emitted machine-readable data.
                 // Model-provided text is sanitized only for display, never for storage.