@gajae-code/coding-agent 0.4.4 → 0.5.0

package/src/harness-control-plane/finalize.ts

@@ -19,11 +19,12 @@ import {
 	type ReceiptSubject,
 	type ReviewFailureEvidence,
 	type ReviewVerdictEvidence,
+	sha256Hex,
 	type ValidationEvidence,
 	validateReceipt,
 } from "./receipts";
 import { readReceiptIndex, writeReceiptImmutable } from "./storage";
-import { isReviewVerdict, type ReviewVerdict } from "./types";
+import { extractReviewVerdict, isReviewVerdict, type ReviewVerdict } from "./types";
 
 export interface ValidationCommandSpec {
 	name: string;
@@ -56,6 +57,11 @@ export interface FinalizeOptions {
 	reviewOnly?: boolean;
 	/** Operator/loop-supplied terminal review verdict (closed vocabulary). */
 	verdict?: string | null;
+	/**
+	 * Final assistant text from the live RPC owner, used to extract a closed-vocabulary verdict
+	 * for review-only sessions when no explicit {@link verdict} is supplied. Never persisted raw.
+	 */
+	assistantText?: string | null;
 	/** Bounded PR/issue reference for the review target (e.g. "PR-414"). Never resolved from the live repo. */
 	prTarget?: string | null;
 	validationCommands?: ValidationCommandSpec[];
@@ -78,6 +84,14 @@ function receiptId(prefix: string): string {
 	return `${prefix}-${Date.now()}-${randomBytes(4).toString("hex")}`;
 }
 
+/** Bound + whitespace-collapse assistant text into a redaction-safe digest summary (never a raw dump). */
+function boundedAssistantSummary(text: string | null): string | null {
+	if (!text) return null;
+	const collapsed = text.replace(/\s+/g, " ").trim();
+	if (collapsed.length === 0) return null;
+	return collapsed.length > 280 ? `${collapsed.slice(0, 280)}…` : collapsed;
+}
+
 export async function runFinalize(opts: FinalizeOptions): Promise<FinalizeResult> {
 	if (opts.reviewOnly) return runReviewFinalize(opts);
 
@@ -214,9 +228,27 @@ async function runReviewFinalize(opts: FinalizeOptions): Promise<FinalizeResult>
 		issueArtifact: null,
 	};
 
-	if (!isReviewVerdict(opts.verdict)) {
-		const reason = opts.verdict == null ? "review-verdict-missing" : "review-verdict-invalid";
-		const failure: ReviewFailureEvidence = { reason, prTarget, failedAt: now(), fallback: "operator-or-omx-review" };
+	// Explicit operator/loop verdict always wins. Only when none is supplied do we fall back to
+	// extracting a closed-vocabulary verdict from the live RPC owner's final assistant text.
+	const explicitProvided = opts.verdict != null;
+	const explicitValid = isReviewVerdict(opts.verdict);
+	const assistantText = typeof opts.assistantText === "string" ? opts.assistantText : null;
+	const extracted = explicitProvided ? null : extractReviewVerdict(assistantText);
+	const verdict: ReviewVerdict | null = explicitValid ? (opts.verdict as ReviewVerdict) : extracted;
+	const verdictSource: "input" | "assistant" = explicitValid ? "input" : "assistant";
+
+	if (!verdict) {
+		const reason = explicitProvided ? "review-verdict-invalid" : "review-verdict-missing";
+		const assistantDigest = assistantText ? sha256Hex(assistantText) : null;
+		const assistantSummary = boundedAssistantSummary(assistantText);
+		const failure: ReviewFailureEvidence = {
+			reason,
+			prTarget,
+			failedAt: now(),
+			fallback: "operator-or-omx-review",
+			...(assistantDigest ? { assistantDigest } : {}),
+			...(assistantSummary ? { assistantSummary } : {}),
+		};
 		const receipt = buildReceipt<ReviewFailureEvidence>({
 			receiptId: receiptId("revfail"),
 			sessionId: opts.sessionId,
@@ -238,12 +270,14 @@ async function runReviewFinalize(opts: FinalizeOptions): Promise<FinalizeResult>
 		return { ...baseResult, completed: false, receiptPath: entry.path, verdict: null, blockers };
 	}
 
-	const verdict = opts.verdict as ReviewVerdict;
+	const assistantDigest = verdictSource === "assistant" && assistantText ? sha256Hex(assistantText) : null;
 	const evidence: ReviewVerdictEvidence = {
 		verdict,
 		prTarget,
 		finalizedAt: now(),
 		summaryRef: typeof opts.prTarget === "string" ? `verdict:${verdict}@${opts.prTarget}` : `verdict:${verdict}`,
+		verdictSource,
+		...(assistantDigest ? { assistantDigest } : {}),
 	};
 	const receipt = buildReceipt<ReviewVerdictEvidence>({
 		receiptId: receiptId("verdict"),

package/src/harness-control-plane/owner.ts

@@ -20,6 +20,7 @@ import { ControlServer, type EndpointRequest } from "./control-endpoint";
 import { defaultFinalizeChecks, type FinalizeChecks, runFinalize, type ValidationCommandSpec } from "./finalize";
 import { type OperateResult, operate } from "./operate";
 import { preserveDirtyWorktree } from "./preserve";
+import { RECEIPT_SPOOL_DIR_ENV, withReceiptSpoolDir } from "./receipt-spool";
 import {
 	buildReceipt,
 	type ReceiptSubject,
@@ -28,8 +29,7 @@ import {
 	type VanishEvidence,
 	validateReceipt,
 } from "./receipts";
-import type { HarnessRpc } from "./rpc-adapter";
-import { singleFlightAccept } from "./rpc-adapter";
+import { type HarnessRpc, type RpcStateSnapshot, singleFlightAccept } from "./rpc-adapter";
 import {
 	acquireLease,
 	canWriteEvents,
@@ -39,7 +39,7 @@ import {
 	releaseLease,
 	type SessionLease,
 } from "./session-lease";
-import { buildStateView, nextAllowedActions } from "./state-machine";
+import { buildStateView, nextAllowedActions, submitUnavailableReason } from "./state-machine";
 import {
 	appendEvent,
 	controlSocketPath,
@@ -200,11 +200,6 @@ export class RuntimeOwner {
 	}
 
 	async #emitMapped(mapped: NonNullable<ReturnType<typeof observeRpcOutboundFrame>>): Promise<void> {
-		await this.#emit(
-			mapped.severity,
-			mapped.kind,
-			mapped.signal ? { ...mapped.evidence, signal: mapped.signal } : mapped.evidence,
-		);
 		if (mapped.kind === "rpc_agent_completed") {
 			const state = await readSessionState(this.#opts.root, this.#opts.sessionId);
 			if (
@@ -218,6 +213,11 @@ export class RuntimeOwner {
 				await writeSessionState(this.#opts.root, state);
 			}
 		}
+		await this.#emit(
+			mapped.severity,
+			mapped.kind,
+			mapped.signal ? { ...mapped.evidence, signal: mapped.signal } : mapped.evidence,
+		);
 	}
 
 	#aggregateSignals(events: EventEnvelope[]): string[] {
@@ -233,6 +233,20 @@ export class RuntimeOwner {
 		return out;
 	}
 
+	#eventSubmitGateReason(kind: string, evidence: Record<string, unknown>): string | null {
+		const reason = typeof evidence.reason === "string" ? evidence.reason : null;
+		const signal = typeof evidence.signal === "string" ? evidence.signal : null;
+		const rpcActive =
+			kind === "prompt_accepted" ||
+			reason === "pre-state-not-idle" ||
+			kind.startsWith("rpc_") ||
+			signal === "prompt-accepted" ||
+			signal === "streaming" ||
+			signal === "tool-call" ||
+			signal === "test-running";
+		return rpcActive ? "rpc-not-idle" : null;
+	}
+
 	async #emit(severity: Severity, kind: string, evidence: Record<string, unknown>): Promise<void> {
 		const lease = await readLease(this.#opts.root, this.#opts.sessionId);
 		// Single-writer guard: only emit while we still hold a live lease.
@@ -247,6 +261,7 @@ export class RuntimeOwner {
 					ownerLive: true,
 					blockers: [],
 				};
+		const submitGateReason = this.#eventSubmitGateReason(kind, evidence);
 		const envelope: EventEnvelope = {
 			eventId: randomUUID(),
 			cursor: ++this.#cursor,
@@ -255,21 +270,41 @@ export class RuntimeOwner {
 			kind,
 			state: view,
 			evidence,
-			nextAllowedActions: nextAllowedActions(view.lifecycle, true),
+			nextAllowedActions: nextAllowedActions(view.lifecycle, true, { submitUnavailableReason: submitGateReason }),
 			writer: { ownerId: this.ownerId, leaseEpoch: this.#leaseEpoch },
 		};
 		await appendEvent(this.#opts.root, this.#opts.sessionId, envelope);
 	}
 
-	#response(state: SessionState, evidence: Record<string, unknown>, ok = true): PrimitiveResponse {
+	#response(
+		state: SessionState,
+		evidence: Record<string, unknown>,
+		ok = true,
+		submitGateReason: string | null = null,
+	): PrimitiveResponse {
 		return {
 			ok,
 			state: buildStateView(state, true),
 			evidence,
-			nextAllowedActions: nextAllowedActions(state.lifecycle, true),
+			nextAllowedActions: nextAllowedActions(state.lifecycle, true, { submitUnavailableReason: submitGateReason }),
 		};
 	}
 
+	#submitGateReason(state: SessionState, rpcState: RpcStateSnapshot | null): string | null {
+		const rpcReason = rpcState
+			? rpcState.isStreaming || rpcState.steeringQueueDepth > 0 || rpcState.followupQueueDepth > 0
+				? "rpc-not-idle"
+				: null
+			: "rpc-not-live";
+		return submitUnavailableReason(state.lifecycle, true, rpcReason);
+	}
+
+	async #withReceiptSpoolFromInput<T>(input: Record<string, unknown>, fn: () => Promise<T>): Promise<T> {
+		const requested = input[RECEIPT_SPOOL_DIR_ENV];
+		if (typeof requested === "string" && requested.trim()) return withReceiptSpoolDir(requested, fn);
+		return fn();
+	}
+
 	async #handle(req: EndpointRequest): Promise<unknown> {
 		switch (req.verb) {
 			case "ping":
@@ -281,13 +316,13 @@ export class RuntimeOwner {
 			case "retire":
 				return this.#retire();
 			case "finalize":
-				return this.#finalize(req.input);
+				return this.#withReceiptSpoolFromInput(req.input, () => this.#finalize(req.input));
 			case "recover":
-				return this.#recover();
+				return this.#withReceiptSpoolFromInput(req.input, () => this.#recover());
 			case "validate":
-				return this.#validate();
+				return this.#withReceiptSpoolFromInput(req.input, () => this.#validate());
 			case "operate":
-				return this.#operate(req.input);
+				return this.#withReceiptSpoolFromInput(req.input, () => this.#operate(req.input));
 			default:
 				return { ok: false, error: `owner_unsupported_verb:${req.verb}` };
 		}
@@ -297,8 +332,10 @@ export class RuntimeOwner {
 		const state = await this.#loadState();
 		const workspace = state.handle.workspace;
 		let streaming = false;
+		let rpcState: RpcStateSnapshot | null = null;
 		try {
-			streaming = (await this.#opts.rpc.getState()).isStreaming;
+			rpcState = await this.#opts.rpc.getState();
+			streaming = rpcState.isStreaming;
 		} catch {
 			streaming = false;
 		}
@@ -328,12 +365,7 @@ export class RuntimeOwner {
 				gitDelta = "unknown";
 			}
 		}
-		const rpcLive = this.#opts.rpc.isLive
-			? this.#opts.rpc.isLive()
-			: await this.#opts.rpc
-					.getState()
-					.then(() => true)
-					.catch(() => false);
+		const rpcLive = this.#opts.rpc.isLive ? this.#opts.rpc.isLive() : rpcState !== null;
 		const rpcLastFrameAt = this.#opts.rpc.lastFrameAt ? this.#opts.rpc.lastFrameAt() : null;
 		// Sticky semantic signals come from the persisted owner event log -> survive polling gaps.
 		const recent = (await readEvents(this.#opts.root, this.#opts.sessionId, 0)).slice(-200);
@@ -343,6 +375,7 @@ export class RuntimeOwner {
 			(t): t is string => typeof t === "string",
 		);
 		const lastActivityAt = stamps.length > 0 ? (stamps.sort().at(-1) ?? state.updatedAt) : state.updatedAt;
+		const submitGateReason = this.#submitGateReason(state, rpcState);
 		return {
 			lifecycle: state.lifecycle,
 			ownerLive: true,
@@ -354,6 +387,8 @@ export class RuntimeOwner {
 			risk: deleted ? "deleted-worktree" : "normal",
 			rpcLive,
 			rpcLastFrameAt,
+			readyForSubmit: submitGateReason === null,
+			submitUnavailableReason: submitGateReason,
 		};
 	}
 
@@ -504,13 +539,21 @@ export class RuntimeOwner {
 		const workspace = state.handle.workspace;
 		const checks = this.#finalizeChecks ?? defaultFinalizeChecks(workspace);
 		const reviewOnly = state.handle.mode === "review";
+		const inputVerdict = reviewOnly ? (typeof input.verdict === "string" ? input.verdict : null) : undefined;
+		// Review-only finalize with no explicit verdict pulls the final assistant text from the live
+		// RPC owner so the verdict can be extracted deterministically instead of demanded from the operator.
+		let assistantText: string | null = null;
+		if (reviewOnly && inputVerdict == null && this.#opts.rpc.getLastAssistantText) {
+			assistantText = await this.#opts.rpc.getLastAssistantText().catch(() => null);
+		}
 		const fin = await runFinalize({
 			root: this.#opts.root,
 			sessionId: this.#opts.sessionId,
 			workspace,
 			branch: state.handle.branch ?? "",
 			reviewOnly,
-			verdict: reviewOnly ? (typeof input.verdict === "string" ? input.verdict : null) : undefined,
+			verdict: inputVerdict,
+			assistantText: reviewOnly ? assistantText : undefined,
 			prTarget: reviewOnly ? state.handle.issueOrPr : undefined,
 			requireTests: input.requireTests !== false,
 			requireCommit: input.requireCommit !== false,
@@ -535,10 +578,21 @@ export class RuntimeOwner {
 		const prompt = typeof input.prompt === "string" ? input.prompt : "";
 		const state = await this.#loadState();
 		if (!prompt) {
-			return this.#response(state, { accepted: false, reason: "empty-prompt" }, false);
+			return this.#response(
+				state,
+				{ accepted: false, submitted: false, reason: "empty-prompt" },
+				false,
+				"empty-prompt",
+			);
 		}
-		if (state.lifecycle === "blocked") {
-			return this.#response(state, { accepted: false, reason: "lifecycle-blocked" }, false);
+		const lifecycleGate = submitUnavailableReason(state.lifecycle, true);
+		if (lifecycleGate) {
+			return this.#response(
+				state,
+				{ accepted: false, submitted: false, reason: lifecycleGate },
+				false,
+				lifecycleGate,
+			);
 		}
 		const result = await singleFlightAccept(this.#opts.rpc, prompt, this.#opts.acceptanceTimeoutMs);
 		if (result.accepted) {
@@ -552,11 +606,12 @@ export class RuntimeOwner {
 		} else {
 			await this.#emit("warn", "prompt_not_accepted", { reason: result.reason });
 		}
+		const submitGateReason = result.accepted ? null : result.reason === "pre-state-not-idle" ? "rpc-not-idle" : null;
 		return this.#response(
 			state,
 			{
 				accepted: result.accepted,
-				submitted: true,
+				submitted: result.commandId !== null,
 				reason: result.reason,
 				commandId: result.commandId,
 				preSubmitCursor: result.preSubmitCursor,
@@ -564,12 +619,16 @@ export class RuntimeOwner {
 				acceptanceEvidence: result.preSubmitState,
 			},
 			result.accepted,
+			submitGateReason,
 		);
 	}
 
 	async #observe(): Promise<PrimitiveResponse> {
 		const state = await this.#loadState();
-		return this.#response(state, { observation: await this.#observeGit(), ownerRouted: true });
+		const observation = await this.#observeGit();
+		const submitGateReason =
+			typeof observation.submitUnavailableReason === "string" ? observation.submitUnavailableReason : null;
+		return this.#response(state, { observation, ownerRouted: true }, true, submitGateReason);
 	}
 
 	async #retire(): Promise<PrimitiveResponse> {

package/src/harness-control-plane/phase-rollup.ts

@@ -0,0 +1,96 @@
+/**
+ * Phase-boundary receipt rollup builder (receipt-of-receipts).
+ *
+ * At a harness lifecycle boundary, N child task receipts can be superseded by a
+ * single `phase-rollup` receipt that preserves per-child pointers (id, status,
+ * outputRef, sha256) plus aggregate ROI totals. The rollup is hash-sealed via
+ * the standard receipt envelope and validated fail-closed like every other
+ * family (see `validatePhaseRollup` in receipts.ts). Pure builder — no runtime
+ * injection behavior is changed here.
+ */
+import type { TaskResultReceipt } from "../task/receipt";
+import {
+	type BuildReceiptInput,
+	buildReceipt,
+	canonicalJson,
+	type PhaseRollupChildPointer,
+	type PhaseRollupEvidence,
+	type ReceiptEnvelope,
+	sha256Hex,
+} from "./receipts";
+
+function childPointer(receipt: TaskResultReceipt): PhaseRollupChildPointer {
+	const ref = receipt.outputRef;
+	// Receipt-of-receipts integrity requires BOTH a pointer URI and its content
+	// hash. A URI without a verifiable hash cannot be integrity-checked, so we
+	// drop the (one-sided) pointer entirely rather than emit an unverifiable ref
+	// that the fail-closed validator would reject.
+	const hasVerifiableRef = Boolean(ref?.uri) && Boolean(ref?.sha256);
+	return {
+		id: receipt.id,
+		status: receipt.status,
+		outputUri: hasVerifiableRef ? (ref?.uri ?? null) : null,
+		outputSha256: hasVerifiableRef ? (ref?.sha256 ?? null) : null,
+		// Normalize through JSON first: in-memory task receipts carry optional
+		// fields with value `undefined`, which canonicalJson would hash as
+		// `null` while persisted/parsed receipts omit those keys entirely.
+		// JSON round-tripping drops undefined-valued keys so the hash is
+		// identical for in-memory and rehydrated copies of the same receipt.
+		receiptSha256: sha256Hex(canonicalJson(JSON.parse(JSON.stringify(receipt)))),
+		// Per-child ROI accounting so the rollup aggregate is recomputable from
+		// child evidence (see validatePhaseRollup). `tokens` falls back to the
+		// receipt's raw token count when no ROI proxy is present.
+		tokens: receipt.roi?.tokens ?? receipt.tokens,
+		costTotal: receipt.roi?.costTotal ?? null,
+		clonedTokens: receipt.roi?.clonedTokens ?? null,
+		lowRoi: receipt.roi?.lowRoi ?? false,
+	};
+}
+
+export interface BuildPhaseRollupInput {
+	receiptId: string;
+	sessionId: string;
+	source: string;
+	subject: BuildReceiptInput<PhaseRollupEvidence>["subject"];
+	phase: string;
+	children: readonly TaskResultReceipt[];
+	/** Supply for deterministic output; defaults to now. */
+	createdAt?: string;
+}
+
+export function buildPhaseRollupReceipt(input: BuildPhaseRollupInput): ReceiptEnvelope<PhaseRollupEvidence> {
+	// `null` means "no child reported this metric" — the canonical value the
+	// fail-closed validator reconciles against. Decide presence from whether a
+	// child carried the field at all (not from a >0 sum), so a legitimate
+	// all-zero total reconciles instead of collapsing to null and mismatching.
+	const anyCost = input.children.some(child => (child.roi?.costTotal ?? null) !== null);
+	const anyCloned = input.children.some(child => (child.roi?.clonedTokens ?? null) !== null);
+	const totalCostTotal = anyCost
+		? input.children.reduce((total, child) => total + (child.roi?.costTotal ?? 0), 0)
+		: null;
+	const totalClonedTokens = anyCloned
+		? input.children.reduce((total, child) => total + (child.roi?.clonedTokens ?? 0), 0)
+		: null;
+	const evidence: PhaseRollupEvidence = {
+		phase: input.phase,
+		children: input.children.map(childPointer),
+		aggregate: {
+			childCount: input.children.length,
+			completed: input.children.filter(child => child.status === "completed").length,
+			failed: input.children.filter(child => child.status === "failed" || child.status === "merge_failed").length,
+			totalTokens: input.children.reduce((total, child) => total + (child.roi?.tokens ?? child.tokens), 0),
+			totalCostTotal,
+			totalClonedTokens,
+			lowRoiChildIds: input.children.filter(child => child.roi?.lowRoi).map(child => child.id),
+		},
+	};
+	return buildReceipt({
+		receiptId: input.receiptId,
+		sessionId: input.sessionId,
+		family: "phase-rollup",
+		source: input.source,
+		subject: input.subject,
+		evidence,
+		createdAt: input.createdAt,
+	});
+}

package/src/harness-control-plane/receipt-ingest.ts

@@ -0,0 +1,127 @@
+import type { CompletionEvidence, ReceiptEnvelope, ReviewVerdictEvidence } from "./receipts";
+import { validateReceipt } from "./receipts";
+import { canTransition } from "./state-machine";
+import type { HarnessLifecycle, ReceiptFamily, SessionState } from "./types";
+
+export const RECEIPT_DIGEST_MAX_CHARS = 280;
+
+export const RECEIPT_FAMILY_LIFECYCLE_TARGETS: Partial<Record<ReceiptFamily, HarnessLifecycle>> = {
+	completion: "completed",
+	// Review-only sessions terminate on a valid review verdict rather than a
+	// completion receipt; the finalizer treats valid verdicts as terminal.
+	"review-verdict": "completed",
+};
+
+/**
+ * Family-specific evidence consistency: the lifecycle target must agree with
+ * what the evidence itself claims. Hash validity alone is not enough — a
+ * semantically contradictory receipt must not drive the lifecycle.
+ */
+function evidenceContradiction(receipt: ReceiptEnvelope<unknown>, target: HarnessLifecycle): string | undefined {
+	if (receipt.family === "completion") {
+		const evidence = receipt.evidence as CompletionEvidence;
+		if (evidence.finalLifecycle !== target) {
+			return `evidence-lifecycle-mismatch:${evidence.finalLifecycle}`;
+		}
+	}
+	if (receipt.family === "review-verdict") {
+		const evidence = receipt.evidence as ReviewVerdictEvidence;
+		// Owner confirmation is not a terminal success verdict.
+		if (evidence.verdict === "OWNER_CONFIRMATION_REQUIRED") {
+			return "review-verdict-not-terminal";
+		}
+	}
+	return undefined;
+}
+
+export interface ReceiptIngestResult {
+	accepted: ReceiptEnvelope<unknown>[];
+	rejected: { receipt: ReceiptEnvelope<unknown>; reasons: string[] }[];
+	transitions: { from: HarnessLifecycle; to: HarnessLifecycle; receiptId: string }[];
+	finalLifecycle: HarnessLifecycle;
+	digest: string;
+}
+
+export function ingestReceipts(
+	state: SessionState,
+	receipts: readonly ReceiptEnvelope<unknown>[],
+): ReceiptIngestResult {
+	let lifecycle = state.lifecycle;
+	const accepted: ReceiptEnvelope<unknown>[] = [];
+	const rejected: { receipt: ReceiptEnvelope<unknown>; reasons: string[] }[] = [];
+	const transitions: { from: HarnessLifecycle; to: HarnessLifecycle; receiptId: string }[] = [];
+
+	for (const receipt of receipts) {
+		const validation = validateReceipt(receipt);
+		if (!validation.valid) {
+			rejected.push({ receipt, reasons: validation.reasons });
+			continue;
+		}
+
+		// Fail closed on receipts the envelope itself marks invalid: the hash
+		// can be self-consistent while the issuer recorded the receipt as not
+		// proving its claim.
+		if (receipt.valid !== true) {
+			rejected.push({ receipt, reasons: ["receipt-marked-invalid"] });
+			continue;
+		}
+
+		// Fail closed on cross-session receipts: a self-consistent receipt from
+		// another session must never drive this session's lifecycle.
+		if (receipt.sessionId !== state.sessionId) {
+			rejected.push({ receipt, reasons: [`session-mismatch:${receipt.sessionId}`] });
+			continue;
+		}
+
+		const target = RECEIPT_FAMILY_LIFECYCLE_TARGETS[receipt.family];
+		if (target) {
+			// Non-terminal review verdicts (OWNER_CONFIRMATION_REQUIRED) are
+			// valid receipts but do not complete the session: accept, no move.
+			if (receipt.family === "review-verdict" && evidenceContradiction(receipt, target) !== undefined) {
+				accepted.push(receipt);
+				continue;
+			}
+			// Other contradictions (e.g. completion evidence whose
+			// finalLifecycle disagrees with the target) reject fail-closed.
+			const contradiction = evidenceContradiction(receipt, target);
+			if (contradiction !== undefined) {
+				rejected.push({ receipt, reasons: [contradiction] });
+				continue;
+			}
+			if (!canTransition(lifecycle, target)) {
+				rejected.push({ receipt, reasons: [`illegal-transition:${lifecycle}->${target}`] });
+				continue;
+			}
+
+			transitions.push({ from: lifecycle, to: target, receiptId: receipt.receiptId });
+			lifecycle = target;
+		}
+
+		accepted.push(receipt);
+	}
+
+	return {
+		accepted,
+		rejected,
+		transitions,
+		finalLifecycle: lifecycle,
+		digest: buildReceiptIngestDigest(receipts.length, accepted.length, rejected, state.lifecycle, lifecycle),
+	};
+}
+
+function buildReceiptIngestDigest(
+	total: number,
+	acceptedCount: number,
+	rejected: readonly { receipt: ReceiptEnvelope<unknown>; reasons: readonly string[] }[],
+	initialLifecycle: HarnessLifecycle,
+	finalLifecycle: HarnessLifecycle,
+): string {
+	let digest = `ingested ${total} receipts: ${acceptedCount} accepted, ${rejected.length} rejected; lifecycle ${initialLifecycle}->${finalLifecycle}`;
+	if (rejected.length > 0) {
+		const rejectedSummary = rejected
+			.map(item => `${item.receipt?.receiptId ?? "<malformed>"}(${item.reasons.join("|")})`)
+			.join(",");
+		digest += `; rejected: ${rejectedSummary}`;
+	}
+	return digest.slice(0, RECEIPT_DIGEST_MAX_CHARS);
+}