ai-foreman 1.7.28 → 2.0.0

package/dist/adapters/structured.js

@@ -0,0 +1,213 @@
+import { boundedJson, structuredDigest, validateStructuredCandidate } from "rafi-spec";
+export function structuredReceipt(contract, provider, value, identity, representation, selected, tuple) {
+    if (value === undefined)
+        return { state: "rejected", reason: "missing-result", detail: "Successful provider terminal omitted its structured result", dispatchId: identity.dispatchId };
+    let observedValue;
+    try {
+        // Retain bounded invalid JSON text too, before parsing can reject it.
+        if (representation === "json-text" && typeof value === "string" && Buffer.byteLength(value) <= selected.maximumResponseBytes)
+            observedValue = { representation, value, digest: structuredDigest(value) };
+        else if (representation === "decoded-json")
+            observedValue = { representation, value: boundedJson(value, representation, selected.maximumResponseBytes), digest: structuredDigest(value) };
+        if (!identity.sessionId || !identity.nativeTurnId)
+            throw new Error("Missing native receipt identity");
+        boundedJson(value, representation, selected.maximumResponseBytes);
+        if (tuple.provider !== provider || tuple.operation !== contract.operation || tuple.schemaDigest !== contract.schemaDigest || tuple.descriptorDigest !== selected.descriptorDigest ||
+            tuple.dispatchId !== identity.dispatchId || tuple.sessionId !== identity.sessionId)
+            throw new Error("Receipt identity does not match selected dispatch tuple v2");
+        const candidate = { state: "candidate", protocolVersion: 2, operation: contract.operation,
+            schemaVersion: contract.schemaVersion, schemaDigest: contract.schemaDigest, wireSchemaDigest: selected.wireSchemaDigest, profile: selected.profile,
+            wireContractDigest: selected.descriptorDigest, wireVariant: selected.variant,
+            selectedDispatchDigest: tuple.digest,
+            ...identity, sessionId: identity.sessionId, nativeTurnId: identity.nativeTurnId, terminal: "completed", representation, value };
+        const normalized = validateStructuredCandidate(contract, candidate, selected, tuple);
+        candidate.normalization = { version: 1, rawDecodedDigest: structuredDigest(boundedJson(value, representation, selected.maximumResponseBytes)), canonicalDigest: structuredDigest(normalized) };
+        return candidate;
+    }
+    catch (error) {
+        return { state: "rejected", reason: "invalid-contract", detail: String(error), dispatchId: identity.dispatchId, ...(observedValue ? { observedValue } : {}) };
+    }
+}
+const STREAM_HEAD_BYTES = 65_536;
+const STREAM_TAIL_BYTES = 8_192;
+const STREAM_TEXT_ITEMS = 8;
+/** Pretty-printed JSON never needs this much consecutive whitespace. */
+export const CODEX_RUNAWAY_WHITESPACE_BYTES = 2_048;
+/** The provider is emitting a runaway whitespace sequence; its output can never be accepted. */
+export class CodexRunawayOutputError extends Error {
+    itemId;
+    whitespaceBytes;
+    constructor(itemId, whitespaceBytes) {
+        super(`Codex streamed ${whitespaceBytes} consecutive whitespace bytes in one message; runaway output was stopped before completion`);
+        this.itemId = itemId;
+        this.whitespaceBytes = whitespaceBytes;
+        this.name = "CodexRunawayOutputError";
+    }
+}
+function headUtf8(text, maximum) {
+    const bytes = Buffer.from(text);
+    if (bytes.length <= maximum)
+        return text;
+    let end = maximum;
+    while (end > 0 && (bytes[end] & 0xc0) === 0x80)
+        end--;
+    return bytes.subarray(0, end).toString();
+}
+function tailUtf8(text, maximum) {
+    const bytes = Buffer.from(text);
+    if (bytes.length <= maximum)
+        return text;
+    let start = bytes.length - maximum;
+    while (start < bytes.length && (bytes[start] & 0xc0) === 0x80)
+        start++;
+    return bytes.subarray(start).toString();
+}
+/** Holds early notifications until turn/start supplies the exact turn identity. */
+export class CodexTurnCollector {
+    threadId;
+    requirePhase;
+    onProgress;
+    maximumResponseBytes;
+    turnId;
+    early = [];
+    bytes = 0;
+    finals = new Map();
+    streams = new Map();
+    streamedBytes = 0;
+    streamedDeltas = 0;
+    earlyDeltaBytes = 0;
+    terminal;
+    error;
+    tools = false;
+    resolve;
+    reject;
+    completion = new Promise((resolve, reject) => { this.resolve = resolve; this.reject = reject; });
+    constructor(threadId, requirePhase, onProgress, maximumResponseBytes = 2_000_000) {
+        this.threadId = threadId;
+        this.requirePhase = requirePhase;
+        this.onProgress = onProgress;
+        this.maximumResponseBytes = maximumResponseBytes;
+        void this.completion.catch(() => { });
+    }
+    bind(turnId) {
+        if (!turnId || this.turnId)
+            throw new Error("Missing or duplicate native turn binding");
+        this.turnId = turnId;
+        this.onProgress?.();
+        const early = this.early;
+        this.early = [];
+        this.bytes = 0; // Early transport was already bounded; count result bytes once while draining.
+        for (const event of early)
+            this.ingest(event.method, event.params);
+        this.settle();
+    }
+    ingest(method, params) {
+        if (params.threadId !== this.threadId)
+            return;
+        if (!this.terminal && this.turnId && params.turnId === this.turnId && method.startsWith("item/") && method.endsWith("/delta"))
+            this.onProgress?.();
+        if (!["item/started", "item/completed", "turn/completed", "item/agentMessage/delta"].includes(method))
+            return;
+        if (!this.turnId) {
+            // Early streamed text has its own budget so a final item is never charged twice.
+            // Event count bounds overhead; content bytes bound early streamed text.
+            if (method === "item/agentMessage/delta")
+                this.earlyDeltaBytes += typeof params.delta === "string" ? Buffer.byteLength(params.delta) : 0;
+            else
+                this.bytes += Buffer.byteLength(JSON.stringify(params));
+            if (this.early.length >= 10_000 || this.bytes > this.maximumResponseBytes || this.earlyDeltaBytes > this.maximumResponseBytes)
+                return this.fail(new Error("Early Codex notification limit exceeded"));
+            this.early.push({ method, params });
+            return;
+        }
+        const terminal = params.turn;
+        if ((method === "turn/completed" ? terminal?.id : params.turnId) !== this.turnId)
+            return;
+        if (method === "item/agentMessage/delta")
+            return this.ingestDelta(params);
+        if (!this.terminal)
+            this.onProgress?.();
+        const item = params.item;
+        if (item && ["commandExecution", "fileChange", "mcpToolCall", "dynamicToolCall", "webSearch", "imageGeneration", "collabAgentToolCall"].includes(String(item.type)))
+            this.tools = true;
+        if (method === "item/completed" && item?.type === "agentMessage" && typeof item.text === "string" && (item.phase === "final_answer" || !this.requirePhase && item.phase === undefined)) {
+            if (typeof item.id !== "string" || !item.id)
+                return this.invalidate(new Error("Final result has no native item identity"));
+            const previous = this.finals.get(item.id);
+            if (previous !== undefined && previous !== item.text)
+                return this.invalidate(new Error("Conflicting redelivery of native result item"));
+            if (previous === undefined) {
+                this.bytes += Buffer.byteLength(item.text);
+                if (this.bytes > this.maximumResponseBytes)
+                    return this.fail(new Error("Codex result limit exceeded"));
+                this.finals.set(item.id, item.text);
+            }
+        }
+        if (method === "item/completed" && item?.type === "agentMessage" && typeof item.id === "string") {
+            const stream = this.streams.get(item.id);
+            if (stream)
+                stream.completed = true;
+        }
+        if (method === "turn/completed") {
+            if (this.terminal && JSON.stringify(this.terminal) !== JSON.stringify(terminal))
+                return this.invalidate(new Error("Conflicting native terminal events"));
+            this.terminal = terminal;
+            this.settle();
+        }
+    }
+    /**
+     * Streamed text is bounded before completion, but never becomes a result:
+     * only a completed final item is accepted and charged against the budget.
+     */
+    ingestDelta(params) {
+        if (this.terminal || this.error)
+            return;
+        const itemId = params.itemId, delta = params.delta;
+        if (typeof itemId !== "string" || !itemId || typeof delta !== "string" || this.finals.has(itemId))
+            return;
+        const now = new Date().toISOString();
+        let stream = this.streams.get(itemId);
+        if (!stream) {
+            stream = { itemId, bytes: 0, deltas: 0, completed: false, whitespaceRun: 0, head: "", tail: "", textRetained: true, startedAt: now, lastDeltaAt: now };
+            this.streams.set(itemId, stream);
+            const retained = [...this.streams.values()].filter(item => item.textRetained);
+            if (retained.length > STREAM_TEXT_ITEMS) {
+                const oldest = retained[0];
+                oldest.head = "";
+                oldest.tail = "";
+                oldest.textRetained = false;
+            }
+        }
+        const bytes = Buffer.byteLength(delta);
+        stream.bytes += bytes;
+        stream.deltas += 1;
+        stream.lastDeltaAt = now;
+        this.streamedBytes += bytes;
+        this.streamedDeltas += 1;
+        const headBytes = Buffer.byteLength(stream.head);
+        if (headBytes < STREAM_HEAD_BYTES)
+            stream.head += headUtf8(delta, STREAM_HEAD_BYTES - headBytes);
+        stream.tail = tailUtf8(stream.tail + delta, STREAM_TAIL_BYTES);
+        const trailing = delta.length - delta.trimEnd().length;
+        stream.whitespaceRun = trailing === delta.length ? stream.whitespaceRun + bytes : Buffer.byteLength(delta.slice(delta.length - trailing));
+        if (stream.whitespaceRun >= CODEX_RUNAWAY_WHITESPACE_BYTES)
+            return this.fail(new CodexRunawayOutputError(itemId, stream.whitespaceRun));
+        if (stream.bytes > this.maximumResponseBytes)
+            this.fail(new Error(`Codex streamed message exceeded the ${this.maximumResponseBytes}-byte result limit before completion`));
+    }
+    streamDiagnostic() {
+        return { authoritative: false, streamedBytes: this.streamedBytes, deltas: this.streamedDeltas, items: [...this.streams.values()].map(item => ({ ...item })) };
+    }
+    fail(error) { this.error = error; this.reject(error); }
+    invalidate(error) { this.error = error; }
+    settle() { if (this.terminal)
+        this.resolve(this.terminal); }
+    final() {
+        if (this.error)
+            throw this.error;
+        if (this.finals.size > 1)
+            throw new Error("Multiple distinct final result items");
+        const entry = [...this.finals][0];
+        return { text: entry?.[1] ?? "", itemId: entry?.[0] };
+    }
+}

package/dist/adapters/types.d.ts

@@ -52,8 +52,17 @@ export interface RuntimeFailure {
     dispatchState?: TurnDispatchState;
     availability?: SessionAvailabilityV1;
 }
-export interface TurnResult {
-    /** Final assistant message text — where the STEP_STATUS marker lives. */
+export interface RetainedTransportEvidence {
+    rawDigest: string;
+    responseDigest: string;
+    rawBytes: number;
+    retainedRawBytes: number;
+    valueDigest?: string;
+    rejectedValueDigest?: string;
+}
+export interface TurnResultBase {
+    transportEvidence?: RetainedTransportEvidence;
+    /** Human display / historical transport only. Never parse for a native operation. */
     text: string;
     isError: boolean;
     numTurns: number;
@@ -75,6 +84,8 @@ export interface TurnResult {
     turnId?: string;
     /** Deferred handback continuity validation; no hidden provider repair. */
     continuityErrors?: string[];
+    /** Validated composed continuity, never parsed from presentation text. */
+    continuity?: import("rafi-spec").ContinuityDelta;
     /** Exact instruction requested by the immediate host caller. */
     hostInstruction?: string;
     /** Exact instruction dispatched to the provider after all wrappers. */
@@ -89,6 +100,14 @@ export interface TurnResult {
         sessionRef?: ProviderSessionRefV1;
     };
 }
+/** Structured transport observations always carry the tuple that selected them. */
+export type TurnResult = TurnResultBase & ({
+    readonly structured: import("rafi-spec").StructuredResponse;
+    readonly selectedDispatch: import("rafi-spec").SelectedDispatchTupleV2;
+} | {
+    readonly structured?: undefined;
+    readonly selectedDispatch?: import("rafi-spec").SelectedDispatchTupleV2;
+});
 /** Observability events emitted while a builder works. */
 export type BuilderEvent = ({
     kind: "text";
@@ -117,7 +136,7 @@ export type BuilderEvent = ({
     lifecycle: "started" | "completed";
     itemType: string;
     payload: Record<string, unknown>;
-    payloadCompleteness: "complete";
+    payloadCompleteness: "complete" | "truncated";
     providerTurnId?: string;
 } | {
     kind: "activity";
@@ -205,7 +224,17 @@ export interface ProviderSettingSwitch {
     fast?: boolean;
 }
 export type EffortLevel = "low" | "medium" | "high" | "xhigh";
+export interface ProviderQueryBudget {
+    reserveQuery(provider: "claude" | "codex"): {
+        maximumSpendUsd: number;
+        signal: AbortSignal;
+        record(costUsd: number): void;
+        close(): void;
+    };
+}
 export interface BuilderAdapterOptions {
+    /** Live validation supplies the shared supervisor; production has no synthetic dollar meter. */
+    queryBudget?: ProviderQueryBudget;
     /** Working directory the builder operates in. */
     cwd: string;
     /** Absolute runtime executable path verified by the readiness probe. */
@@ -287,9 +316,28 @@ export interface BuilderAdapterOptions {
         isError?: boolean;
         outputDigest?: string;
         rawOutputBytes?: number;
+        completionKnown?: boolean;
     }) => void;
 }
+export interface ConfirmedDispatchReference {
+    dispatchId: string;
+    runId: string;
+    tupleDigest: string;
+}
+/**
+ * Host-owned response requirement contributed by an adapter decorator. The
+ * instruction is applied before the dispatch is sealed; validation runs on the
+ * native-validated response before the dispatch can be confirmed.
+ */
+export interface StructuredDispatchRequirement {
+    readonly instruction: string;
+    validate(response: import("rafi-spec").OperationResponse): void;
+}
 export interface BuilderAdapter {
+    /** Receives only durable verified transport identity, after confirmation. */
+    postConfirmedDispatch?(reference: ConfirmedDispatchReference): Promise<TurnResult | void>;
+    /** Requirements every structured dispatch through this adapter must satisfy. */
+    structuredDispatchRequirement?(): StructuredDispatchRequirement | undefined;
     graphRuntimeSettings?(): Pick<BuilderAdapterOptions, "model" | "effort" | "fast" | "runtimeExecutable"> | undefined;
     readonly agent: "claude" | "codex";
     contractCapabilities?(): {
@@ -306,12 +354,7 @@ export interface BuilderAdapter {
         sessionId?: string;
     }) => void): void;
     /** Send one instruction; resolves when that turn completes. */
-    sendTurn(text: string, policy?: {
-        handback?: boolean;
-        responseOnly?: boolean;
-        logicalActionId?: string;
-        purpose?: ProviderTurnPurpose;
-    }): Promise<TurnResult>;
+    sendTurn(text: string, policy?: TurnRequest): Promise<TurnResult>;
     /** Synchronous observation through the event owner. Terminal precedes sendTurn resolution. */
     observeEvents?(listener: (event: BuilderEvent) => void): () => void;
     /** Commit a deferred handback checkpoint only after the host validates the turn. */
@@ -358,3 +401,37 @@ export interface BuilderAdapter {
     /** Shut the builder down and release resources. */
     close(): Promise<void>;
 }
+/** Host request only; the durable gateway must seal this before provider contact. */
+export interface TurnRequest {
+    journalRunId?: string;
+    /** Minted only inside the committed structured gateway; never serialized. */
+    dispatchCapability?: import("../structuredDispatchAuthority.js").StructuredDispatchCapability;
+    handback?: boolean;
+    responseOnly?: boolean;
+    logicalActionId?: string;
+    dispatchId?: string;
+    parentDispatchId?: string;
+    purpose?: ProviderTurnPurpose;
+    output?: import("rafi-spec").OutputContract;
+    /** Immutable selected provider boundary; no adapter may substitute a schema. */
+    wireContract?: import("rafi-spec").ProviderWireContract<any>;
+    /** Digest of the descriptor that rendered the exact provider instruction. */
+    renderedWireContractDigest?: string;
+    /** Immutable authority sealed before the provider receives the instruction. */
+    selectedDispatch?: import("rafi-spec").SelectedDispatchTupleV2;
+}
+/** Terminal provider boundary. Requests acquire this shape only after sealing. */
+export interface SealedTurnPolicy extends TurnRequest {
+    output: import("rafi-spec").OutputContract;
+    wireContract: import("rafi-spec").ProviderWireContract<any>;
+    renderedWireContractDigest: string;
+    selectedDispatch: import("rafi-spec").SelectedDispatchTupleV2;
+    dispatchCapability: import("../structuredDispatchAuthority.js").StructuredDispatchCapability;
+    dispatchId: string;
+}
+export type TurnPolicy = SealedTurnPolicy | (TurnRequest & {
+    output?: never;
+    selectedDispatch?: never;
+    dispatchCapability?: never;
+});
+export type ProviderTurnPolicy = TurnPolicy;

package/dist/agentRun.d.ts

@@ -1,4 +1,5 @@
 export { withGraphDerivedAccess } from "./graph/derived.js";
+export { operationInstruction, operationResponse, operationStatus, operationPayload, nativePolicy } from "./structuredOperation.js";
 import { type PermissionConfig } from "./config.js";
 import { Log } from "./log.js";
 import { type StepStatus } from "./foreman.js";
@@ -48,6 +49,7 @@ export interface RoleBuilder {
     log: Log;
 }
 export interface RoleInstructionRunOptions extends Omit<RoleBuilderOptions, "log"> {
+    output: import("rafi-spec").OutputContract;
     instruction: string;
     logPath?: string;
     logEvent?: "rafi-plan" | "ticket-populate" | "preflight" | "uninstall-proposal";

package/dist/agentRun.js

@@ -1,4 +1,5 @@
 export { withGraphDerivedAccess } from "./graph/derived.js";
+export { operationInstruction, operationResponse, operationStatus, operationPayload, nativePolicy } from "./structuredOperation.js";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { loadConfig, DEFAULT_CONFIG } from "./config.js";
@@ -335,7 +336,7 @@ export async function runRoleInstruction(opts) {
     const foreman = new Foreman(builder, log, { desktop: config.notifications.enabled, terminalBell: config.notifications.terminal_bell }, false, 3, opts.projectDir);
     foreman.setGraphPurpose(opts.graphPurpose ?? { planner: "planning", discovery: "discovery", "ticket-maker": "ticket-population", uninstaller: "uninstall-analysis" }[opts.role] ?? "implementation");
     try {
-        const turn = await foreman.runInstruction(opts.instruction);
+        const turn = await foreman.runInstruction(opts.instruction, { output: opts.output });
         await builder.close();
         await viewer;
         if (opts.logEvent) {

package/dist/boundedTurnEvidence.d.ts

@@ -0,0 +1,18 @@
+import type { BuilderEvent, TurnResult } from "./adapters/types.js";
+export declare function boundedUtf8(text: string, maximum: number): Buffer;
+export declare function receiptFingerprint(turn: TurnResult): string;
+export declare function rawFingerprint(turn: TurnResult): string;
+/** Retains at most one descriptor budget; omitted events cannot establish acceptance. */
+export declare class BoundedTurnEvents extends Array<BuilderEvent> {
+    readonly maximumBytes: number;
+    static get [Symbol.species](): ArrayConstructor;
+    retainedBytes: number;
+    totalCount: number;
+    toolCount: number;
+    terminalCount: number;
+    omittedCount: number;
+    terminalOverflow: boolean;
+    constructor(maximumBytes: number);
+    push(...events: BuilderEvent[]): number;
+    metadata(): unknown;
+}

package/dist/boundedTurnEvidence.js

@@ -0,0 +1,76 @@
+import { createHash } from "node:crypto";
+import { canonicalJson } from "rafi-spec";
+export function boundedUtf8(text, maximum) {
+    const bytes = Buffer.from(text);
+    if (bytes.length <= maximum)
+        return bytes;
+    let end = maximum;
+    while (end > 0 && (bytes[end] & 0xc0) === 0x80)
+        end--;
+    return bytes.subarray(0, end);
+}
+const fingerprints = new WeakMap();
+export function receiptFingerprint(turn) { return fingerprints.get(turn)?.receipt ?? digest(canonicalJson(JSON.parse(JSON.stringify(turn.structured ?? null)))); }
+export function rawFingerprint(turn) { return fingerprints.get(turn)?.raw ?? digest(turn.rawResponse ?? turn.text); }
+function digest(text) { return createHash("sha256").update(text).digest("hex"); }
+/** Retains at most one descriptor budget; omitted events cannot establish acceptance. */
+export class BoundedTurnEvents extends Array {
+    maximumBytes;
+    static get [Symbol.species]() { return Array; }
+    retainedBytes = 2;
+    totalCount = 0;
+    toolCount = 0;
+    terminalCount = 0;
+    omittedCount = 0;
+    terminalOverflow = false;
+    constructor(maximumBytes) {
+        super();
+        this.maximumBytes = maximumBytes;
+    }
+    push(...events) {
+        for (const event of events) {
+            this.totalCount++;
+            // Claude reports reasoning as thinking/redacted_thinking content blocks.
+            if (event.kind === "tool" || event.kind === "provider-item" && !["text", "agentMessage", "reasoning", "thinking", "redacted_thinking", "userMessage", "contextCompaction", "structuredOutput"].includes(event.itemType))
+                this.toolCount++;
+            let projected;
+            if (event.kind === "turn-complete") {
+                this.terminalCount++;
+                const turn = event.result;
+                const result = { text: "", isError: turn.isError, costUsd: 0, numTurns: turn.numTurns, turnId: turn.turnId,
+                    providerMetadata: turn.providerMetadata && JSON.parse(JSON.stringify(turn.providerMetadata)), failure: turn.failure && { ...turn.failure, diagnostics: "omitted" } };
+                fingerprints.set(result, { receipt: receiptFingerprint(turn), raw: rawFingerprint(turn) });
+                projected = { kind: "turn-complete", turnId: event.turnId, result };
+            }
+            else if (event.kind === "tool")
+                projected = { ...event, input: Buffer.byteLength(JSON.stringify(event.input) ?? "") <= 1024 ? JSON.parse(JSON.stringify(event.input ?? null)) : {}, outputSummary: undefined, inputCompleteness: Buffer.byteLength(JSON.stringify(event.input) ?? "") <= 1024 ? event.inputCompleteness : "truncated" };
+            else if (event.kind === "provider-item")
+                projected = { ...event, payload: {}, payloadCompleteness: "truncated" };
+            else if (event.kind === "text")
+                projected = { kind: "text", text: boundedUtf8(event.text, 512).toString(), byteCount: Buffer.byteLength(event.text), digest: digest(event.text) };
+            else if (event.kind === "error")
+                projected = { kind: "error", message: boundedUtf8(event.message, 512).toString() };
+            else
+                projected = event;
+            if (projected.kind !== "turn-complete")
+                projected = JSON.parse(JSON.stringify(projected));
+            const size = Buffer.byteLength(JSON.stringify(projected)) + 1;
+            const limit = event.kind === "turn-complete" ? this.maximumBytes - 2048 : Math.floor(this.maximumBytes / 2);
+            if (this.retainedBytes + size > limit) {
+                this.omittedCount++;
+                if (event.kind === "turn-complete")
+                    this.terminalOverflow = true;
+                continue;
+            }
+            this.retainedBytes += size;
+            super.push(projected);
+        }
+        return this.length;
+    }
+    metadata() {
+        return JSON.parse(JSON.stringify({ totalCount: this.totalCount, toolCount: this.toolCount, terminalCount: this.terminalCount, omittedCount: this.omittedCount,
+            terminalOverflow: this.terminalOverflow, events: this.map(event => event.kind === "turn-complete"
+                ? { kind: event.kind, turnId: event.turnId, receiptDigest: receiptFingerprint(event.result), rawDigest: rawFingerprint(event.result), isError: event.result.isError, provider: event.result.providerMetadata }
+                : event) }));
+    }
+}

package/dist/branch/currentGuard.d.ts

@@ -18,6 +18,8 @@ export declare class CurrentWorkflowGuardAdapter implements BuilderAdapter {
     private readonly adapter;
     private readonly cwd;
     private readonly expected;
+    postConfirmedDispatch(reference: import("../adapters/types.js").ConfirmedDispatchReference): Promise<TurnResult | void>;
+    structuredDispatchRequirement(): import("../adapters/types.js").StructuredDispatchRequirement | undefined;
     readonly agent: BuilderAdapter["agent"];
     constructor(adapter: BuilderAdapter, cwd: string, expected?: CurrentWorkflowIdentity);
     sendTurn(text: string, policy?: Parameters<BuilderAdapter["sendTurn"]>[1]): Promise<TurnResult>;

package/dist/branch/currentGuard.js

@@ -30,6 +30,8 @@ export class CurrentWorkflowGuardAdapter {
     adapter;
     cwd;
     expected;
+    postConfirmedDispatch(reference) { return this.adapter.postConfirmedDispatch?.(reference) ?? Promise.resolve(); }
+    structuredDispatchRequirement() { return this.adapter.structuredDispatchRequirement?.(); }
     agent;
     constructor(adapter, cwd, expected = captureCurrentWorkflowIdentity(cwd)) {
         this.adapter = adapter;

package/dist/branch/planner.js

@@ -170,10 +170,7 @@ export function buildBranchAuditInstruction(tickets) {
     ].join("\n")).join("\n\n");
     return `Audit this selected ticket batch for undeclared code dependencies. Do not implement anything.
 
-Return one line per required selected-ticket dependency using:
-<ticket> depends_on <ticket> - <short reason>
-
-Only name dependencies where both tickets are in this selected batch. If there are none, say "None".
+Submit the native branch-dependency-audit payload with dependencies containing ticket, dependsOn, and reason. Only name dependencies where both tickets are in this selected batch. If there are none, return an empty dependencies array.
 
 ${body}`;
 }

package/dist/branch/runner.d.ts

@@ -1,6 +1,6 @@
 import type { BuilderAdapter, EffortLevel } from "../adapters/types.js";
 import type { RunObserver } from "../observability.js";
-import type { ProviderSessionRefV1, SessionStrategy } from "rafi-spec";
+import { type ProviderSessionRefV1, type SessionStrategy } from "rafi-spec";
 import { type QaNonconvergenceContext, type QaNonconvergenceDecision, type QaReportRecoveryHandler, type QaSessionBoundaryRecovery, type QaSessionHandle } from "../qaReview.js";
 import type { Log } from "../log.js";
 import type { BranchPlan, BranchPlanNode, BranchRunSummary, CompletionMode, MergeMethod, ReviewProvider } from "./types.js";
@@ -8,6 +8,7 @@ import { SessionUnavailableError } from "../adapters/sessionFailure.js";
 import { SessionUnavailableContinuityError } from "../continuity.js";
 import type { QaRecoveryPacket } from "../qaRecovery.js";
 export interface DeliveryUnitSession {
+    communicationProtocolVersion?: 2;
     runId?: string;
     unitId: string;
     branch: string;

package/dist/branch/runner.js

@@ -6,6 +6,7 @@ import { loadTickets } from "../tickets/ticketLoader.js";
 import { formatRecoveryCommand } from "../recoveryGuidance.js";
 import { WorkflowReader } from "../workflowReader.js";
 import { buildScopeRevision } from "../buildApproval.js";
+import { qaVerdictOutput } from "rafi-spec";
 import { beginQaFinalization, completeQaFinalization, verifyPendingQaFinalizationSource, compactWithRetry, runIsolatedQa } from "../qaReview.js";
 import { QaFailureDeliveryService } from "../qaFailureDelivery.js";
 import { Foreman, MARKER_SPEC } from "../foreman.js";
@@ -30,6 +31,8 @@ export function readDeliveryUnitSession(projectDir, unitId) {
         return undefined;
     try {
         const cached = JSON.parse(readFileSync(path, "utf8"));
+        if (cached.communicationProtocolVersion !== 2)
+            return undefined;
         const reader = new WorkflowReader(projectDir);
         try {
             const known = reader.branchResumeSessions(false);
@@ -376,7 +379,7 @@ export async function runBranchPlan(opts) {
                             db.updateOperation(key, "in_progress");
                         }
                     });
-                    const response = await foreman.runInstruction(ticketInstruction);
+                    const response = await foreman.runBuilderWork(ticketInstruction);
                     for (const decision of continuations)
                         db.updateOperation(`decision-continuation:${decision.decisionId}`, response.result.failure?.dispatchState === "unknown" ? "uncertain" : "confirmed", { result: { isError: response.result.isError } });
                     return response;
@@ -435,7 +438,7 @@ export async function runBranchPlan(opts) {
                     if (node.deliveryUnitId) {
                         const path = deliverySessionPath(opts.projectDir, node.deliveryUnitId);
                         mkdirSync(join(opts.projectDir, ".foreman", "delivery-sessions"), { recursive: true });
-                        writeFileSync(path, `${JSON.stringify({ runId: opts.runId, unitId: node.deliveryUnitId, branch: node.branch, worktreePath, sessionId, sessionRef: builder.sessionRef?.(), ticket: node.ticket.id }, null, 2)}\n`, "utf8");
+                        writeFileSync(path, `${JSON.stringify({ communicationProtocolVersion: 2, runId: opts.runId, unitId: node.deliveryUnitId, branch: node.branch, worktreePath, sessionId, sessionRef: builder.sessionRef?.(), ticket: node.ticket.id }, null, 2)}\n`, "utf8");
                     }
                 }
             }
@@ -482,7 +485,7 @@ export async function runBranchPlan(opts) {
                     resumedRecovery: qaResumedRecovery,
                     sessionBoundary: opts.qaSessionBoundary ?? (async () => { throw new Error("QA recovery requires a validated durable session boundary"); }),
                     observeNativeCompactions: opts.observeQaNativeCompactions,
-                    resolveBlocked: (adapter, reason) => foreman.resolveBlocker(adapter, reason, "qa"),
+                    resolveBlocked: (adapter, reason) => foreman.resolveBlocker(adapter, reason, "qa", qaVerdictOutput),
                     evidence: (entry) => opts.log.write("qa-evidence", { ticket: node.ticket.id, ...entry }),
                     resumeBuilderGuidance: qaOnlyRecovery,
                     deliverBuilderFollowup: (instruction, followup) => deliverBuilderGuidanceFollowup({ projectDir: opts.projectDir, runId: opts.runId, ticketId: node.ticket.id, worktree: worktreePath }, instruction, followup, {
@@ -1145,8 +1148,8 @@ Branch-mode rules:
 - Do not push, create PRs, or run git commit.
 - Do not edit .tickets/, ${progressDoc}, or other tracker state.
 - If a required test is denied only because you added a pipe, redirection, substitution, or wrapper, retry the exact required-test command without that extra shell syntax. Do not retry other denied actions.
-- If another selected ticket is required before this one can be completed, stop and end with STEP_STATUS: blocked | ticket="${node.ticket.id}" branch_dependency="<ticket-id>" reason="<why>".
-- End with STEP_STATUS: done | ticket="${node.ticket.id}" summary="<what changed>" when the ticket is implemented.
+- If another selected ticket is required before this one can be completed, return a native blocked result with branchDependency set to that ticket ID, reason explaining the dependency, and nextAction describing the needed resolution. Do not execute that other ticket.
+- When this ticket is implemented, return the native completed work-report with its summary, evidence, coverage, and continuity. Rafi binds the assigned ticket ID and requires independent QA before acceptance.
 
 Final QA runs independently in a separate disposable snapshot and fresh reviewer conversation.
 
@@ -1167,8 +1170,8 @@ Branch-mode rules:
 - Do not switch branches.
 - Do not push, create PRs, or run git commit.
 - Do not edit .tickets/, ${progressDoc}, or other tracker state.
-- If another selected ticket is required before this one can be completed, stop and end with STEP_STATUS: blocked | ticket="${node.ticket.id}" branch_dependency="<ticket-id>" reason="<why>".
-- End with STEP_STATUS: done | ticket="${node.ticket.id}" summary="<what changed>" when the ticket is implemented.
+- If another selected ticket is required before this one can be completed, return a native blocked result with branchDependency set to that ticket ID, reason explaining the dependency, and nextAction describing the needed resolution. Do not execute that other ticket.
+- When this ticket is implemented, return the native completed work-report with its summary, evidence, coverage, and continuity. Rafi binds the assigned ticket ID and requires independent QA before acceptance.
 
 Final QA runs independently in a separate disposable snapshot and fresh reviewer conversation.
 

package/dist/buildAdmission.js

@@ -1,4 +1,6 @@
 import { registerHandbackWriter } from "./qaHandbackMigration.js";
+import { registerQaGraphJournalWriter } from "./qaDeliveryJournal.js";
+import { assertStructuredCutoverComplete } from "./structuredCutover.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash, randomUUID } from "node:crypto";
 import { realpathSync } from "node:fs";
@@ -58,6 +60,8 @@ export function maintainBuildAdmission(authority) {
             db = new Database(join(authority.project, ".rafi/recovery.sqlite3"), { fileMustExist: true });
             db.function("rafi_protocol_v3", () => 1);
             registerHandbackWriter(db);
+            registerQaGraphJournalWriter(db);
+            assertStructuredCutoverComplete(db);
             const changed = db.prepare("UPDATE build_admission SET record_json=json_set(record_json,'$.heartbeatAt',?) WHERE singleton=1 AND json_extract(record_json,'$.token')=?").run(new Date().toISOString(), authority.token);
             if (changed.changes !== 1)
                 stopBuildAdmissionHeartbeat(authority);