@gajae-code/coding-agent 0.4.4 → 0.5.0

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

@@ -0,0 +1,128 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { withFileLock } from "../config/file-lock";
+import type { ReceiptEnvelope } from "./receipts";
+
+export const RECEIPT_SPOOL_DIR_ENV = "GJC_RECEIPT_SPOOL_DIR";
+export const RECEIPT_SPOOL_FILENAME = "spool.jsonl";
+export const RECEIPT_SPOOL_CURSOR_WIDTH = 12;
+
+export interface ReceiptSpoolRecord {
+	cursor: string;
+	envelope: ReceiptEnvelope<unknown>;
+}
+
+export interface ReceiptSpoolAppendResult {
+	cursor: string;
+	path: string;
+}
+
+const receiptSpoolDirStorage = new AsyncLocalStorage<string | undefined>();
+const spoolQueues = new Map<string, Promise<void>>();
+const noop = (): void => undefined;
+export async function withReceiptSpoolDir<T>(spoolDir: string, fn: () => Promise<T>): Promise<T> {
+	const trimmed = spoolDir.trim();
+	if (!trimmed) throw new Error("receipt_spool_dir_empty");
+	const resolved = path.resolve(trimmed);
+	return receiptSpoolDirStorage.run(resolved, fn);
+}
+
+export function resolveReceiptSpoolDir(env: NodeJS.ProcessEnv = process.env): string | undefined {
+	const active = receiptSpoolDirStorage.getStore();
+	if (active !== undefined) return active;
+	const raw = env[RECEIPT_SPOOL_DIR_ENV]?.trim();
+	return raw ? path.resolve(raw) : undefined;
+}
+
+export function receiptSpoolPath(spoolDir: string): string {
+	return path.join(path.resolve(spoolDir), RECEIPT_SPOOL_FILENAME);
+}
+
+function parseCursor(value: unknown): bigint | undefined {
+	if (typeof value !== "string" || !/^\d+$/.test(value)) return undefined;
+	try {
+		return BigInt(value);
+	} catch {
+		return undefined;
+	}
+}
+
+export function formatReceiptSpoolCursor(cursor: bigint): string {
+	const raw = cursor.toString();
+	return raw.length >= RECEIPT_SPOOL_CURSOR_WIDTH ? raw : raw.padStart(RECEIPT_SPOOL_CURSOR_WIDTH, "0");
+}
+
+export async function readHighestReceiptSpoolCursor(spoolDir: string): Promise<bigint> {
+	const spoolFile = receiptSpoolPath(spoolDir);
+	let raw: string;
+	try {
+		raw = await fs.readFile(spoolFile, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return 0n;
+		throw error;
+	}
+
+	let highest = 0n;
+	for (const line of raw.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		try {
+			const parsed = JSON.parse(trimmed) as { cursor?: unknown };
+			const cursor = parseCursor(parsed.cursor);
+			if (cursor !== undefined && cursor > highest) highest = cursor;
+		} catch {
+			// A crash may leave a torn tail; consumers skip malformed lines and so do we.
+		}
+	}
+	return highest;
+}
+
+async function enqueueSpoolAppend<T>(spoolFile: string, task: () => Promise<T>): Promise<T> {
+	const previous = spoolQueues.get(spoolFile) ?? Promise.resolve();
+	const running = previous.catch(noop).then(task);
+	const normalized = running.then(noop, noop);
+	spoolQueues.set(spoolFile, normalized);
+	normalized
+		.finally(() => {
+			if (spoolQueues.get(spoolFile) === normalized) spoolQueues.delete(spoolFile);
+		})
+		.catch(noop);
+	return running;
+}
+
+export async function appendReceiptToSpool(
+	spoolDir: string,
+	envelope: ReceiptEnvelope<unknown>,
+): Promise<ReceiptSpoolAppendResult> {
+	const resolvedDir = path.resolve(spoolDir);
+	const spoolFile = receiptSpoolPath(resolvedDir);
+	return enqueueSpoolAppend(spoolFile, async () => {
+		await fs.mkdir(resolvedDir, { recursive: true, mode: 0o700 });
+		return withFileLock(
+			spoolFile,
+			async () => {
+				const cursor = formatReceiptSpoolCursor((await readHighestReceiptSpoolCursor(resolvedDir)) + 1n);
+				const record: ReceiptSpoolRecord = { cursor, envelope };
+				const handle = await fs.open(spoolFile, "a", 0o600);
+				try {
+					await handle.writeFile(`${JSON.stringify(record)}\n`, "utf8");
+					await handle.sync();
+				} finally {
+					await handle.close();
+				}
+				return { cursor, path: spoolFile };
+			},
+			{ staleMs: 30_000, retries: 100, retryDelayMs: 25 },
+		);
+	});
+}
+
+export async function appendReceiptToConfiguredSpool(
+	envelope: ReceiptEnvelope<unknown>,
+	env: NodeJS.ProcessEnv = process.env,
+): Promise<ReceiptSpoolAppendResult | undefined> {
+	const spoolDir = resolveReceiptSpoolDir(env);
+	if (!spoolDir) return undefined;
+	return appendReceiptToSpool(spoolDir, envelope);
+}

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

@@ -46,7 +46,7 @@ export interface ReceiptEnvelope<E = Record<string, unknown>> {
 export const RECEIPT_SCHEMA_VERSION = 1 as const;
 
 /** Deterministic stringify with sorted keys (stable hash basis). */
-function canonicalJson(value: unknown): string {
+export function canonicalJson(value: unknown): string {
 	if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
 	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
 	const obj = value as Record<string, unknown>;
@@ -96,9 +96,50 @@ export interface ValidationOutcome {
 	reasons: string[];
 }
 
+/** Reusable non-empty string guard for structural envelope checks. */
+function isNonEmptyString(value: unknown): value is string {
+	return typeof value === "string" && value.length > 0;
+}
+
+/**
+ * Validate the structural envelope fields independently of the hash. A receipt
+ * can be hash-self-consistent while carrying empty/missing identity fields (an
+ * attacker controls the bytes the hash is computed over), so these checks must
+ * run BEFORE any lifecycle transition is allowed. Fail-closed.
+ */
+function validateStructure(receipt: ReceiptEnvelope<unknown>): string[] {
+	const reasons: string[] = [];
+	if (!isNonEmptyString(receipt.receiptId)) reasons.push("envelope-missing-receiptId");
+	if (!isNonEmptyString(receipt.sessionId)) reasons.push("envelope-missing-sessionId");
+	if (!isNonEmptyString(receipt.source)) reasons.push("envelope-missing-source");
+	if (!isNonEmptyString(receipt.createdAt)) reasons.push("envelope-missing-createdAt");
+	// Family vocabulary itself is enforced by `validateFamily`; here we only
+	// require a non-empty family token so the envelope is well-formed.
+	if (!isNonEmptyString(receipt.family)) reasons.push("envelope-missing-family");
+	if (typeof receipt.valid !== "boolean") reasons.push("envelope-bad-valid");
+	if (typeof receipt.sha256 !== "string") reasons.push("envelope-missing-sha256");
+	const subject = receipt.subject as ReceiptSubject | undefined;
+	if (!subject || typeof subject !== "object" || Array.isArray(subject) || !isNonEmptyString(subject.workspace)) {
+		reasons.push("envelope-bad-subject");
+	}
+	if (receipt.evidence === null || typeof receipt.evidence !== "object" || Array.isArray(receipt.evidence)) {
+		reasons.push("envelope-bad-evidence");
+	}
+	if (!receipt.artifactHashes || typeof receipt.artifactHashes !== "object" || Array.isArray(receipt.artifactHashes)) {
+		reasons.push("envelope-bad-artifactHashes");
+	}
+	return reasons;
+}
+
 /** Recompute the hash and run structural family checks. Fail-closed. */
 export function validateReceipt(receipt: ReceiptEnvelope<unknown>): ValidationOutcome {
+	// Fail closed on malformed/non-object envelopes (null, undefined, arrays,
+	// primitives) instead of throwing while destructuring below.
+	if (receipt === null || typeof receipt !== "object" || Array.isArray(receipt)) {
+		return { valid: false, reasons: ["malformed-envelope"] };
+	}
 	const reasons: string[] = [];
+	reasons.push(...validateStructure(receipt));
 	const { sha256, ...rest } = receipt;
 	if (sha256Hex(hashBasis(rest)) !== sha256) reasons.push("hash-mismatch");
 	if (receipt.schemaVersion !== RECEIPT_SCHEMA_VERSION) reasons.push("schema-version-mismatch");
@@ -156,6 +197,10 @@ export interface ReviewVerdictEvidence {
 	finalizedAt: string;
 	/** Bounded summary code/reference for the verdict; never raw assistant text. */
 	summaryRef: string | null;
+	/** Where the verdict came from: explicit operator input or extracted from final assistant text. */
+	verdictSource?: "input" | "assistant";
+	/** sha256 of the assistant text the verdict was extracted from, when sourced from the agent. */
+	assistantDigest?: string | null;
 }
 
 export interface ReviewFailureEvidence {
@@ -165,6 +210,10 @@ export interface ReviewFailureEvidence {
 	failedAt: string;
 	/** Routing hint for the operator/fallback path. */
 	fallback: string;
+	/** sha256 of the assistant text examined for a verdict, when one was available. */
+	assistantDigest?: string | null;
+	/** Bounded, whitespace-collapsed assistant summary (never an unbounded transcript dump). */
+	assistantSummary?: string | null;
 }
 
 function validateFamily(receipt: ReceiptEnvelope<unknown>): string[] {
@@ -181,11 +230,187 @@ function validateFamily(receipt: ReceiptEnvelope<unknown>): string[] {
 			return validateReviewVerdict(receipt.evidence as ReviewVerdictEvidence);
 		case "review-failure":
 			return validateReviewFailure(receipt.evidence as ReviewFailureEvidence);
+		case "phase-rollup":
+			return validatePhaseRollup(receipt.evidence as PhaseRollupEvidence);
 		default:
 			return [`unknown-family:${receipt.family}`];
 	}
 }
 
+// ---- Phase rollup (receipt-of-receipts) ----------------------------------------
+
+/** Pointer back to one superseded child task receipt. */
+export interface PhaseRollupChildPointer {
+	id: string;
+	status: "completed" | "failed" | "aborted" | "merge_failed" | "paused";
+	/** Artifact URI holding the child's full output, when available. */
+	outputUri: string | null;
+	/** Content hash of the child's output artifact, when available. */
+	outputSha256: string | null;
+	/** Hash of the child receipt itself (canonical JSON), for staleness checks. */
+	receiptSha256: string;
+	/**
+	 * Per-child ROI accounting carried into the rollup so the aggregate totals
+	 * below are recomputable/verifiable from child evidence (not self-reported).
+	 * `tokens` is the child's effective token count; cost/cloned are null when
+	 * the child reported no such accounting.
+	 */
+	tokens: number;
+	costTotal: number | null;
+	clonedTokens: number | null;
+	lowRoi: boolean;
+}
+
+export interface PhaseRollupEvidence {
+	/** Harness lifecycle boundary this rollup was emitted at. */
+	phase: string;
+	children: PhaseRollupChildPointer[];
+	aggregate: {
+		childCount: number;
+		completed: number;
+		failed: number;
+		totalTokens: number;
+		totalCostTotal: number | null;
+		totalClonedTokens: number | null;
+		lowRoiChildIds: string[];
+	};
+}
+
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+
+const PHASE_ROLLUP_CHILD_STATUSES = new Set(["completed", "failed", "aborted", "merge_failed", "paused"]);
+
+/** Reconcile two recomputed-vs-reported numeric totals (null == "not reported"). */
+function numbersReconcile(actual: number | null, expected: number | null): boolean {
+	if (actual === null || expected === null) return actual === expected;
+	return Math.abs(actual - expected) <= 1e-9;
+}
+
+/** True when two id lists describe the same set (order-independent). */
+function sameIdSet(actual: readonly string[], expected: readonly string[]): boolean {
+	if (actual.length !== expected.length) return false;
+	const expectedSet = new Set(expected);
+	for (const id of actual) {
+		if (!expectedSet.has(id)) return false;
+	}
+	return new Set(actual).size === expectedSet.size;
+}
+
+export function validatePhaseRollup(e: PhaseRollupEvidence): string[] {
+	const reasons: string[] = [];
+	if (!e || typeof e.phase !== "string" || e.phase.length === 0) return ["phase-rollup-missing-phase"];
+	if (!Array.isArray(e.children) || e.children.length === 0) {
+		reasons.push("phase-rollup-empty-children");
+		return reasons;
+	}
+	const seenIds = new Set<string>();
+	let completedFromChildren = 0;
+	let failedFromChildren = 0;
+	let tokensFromChildren = 0;
+	let costFromChildren = 0;
+	let clonedFromChildren = 0;
+	let anyCost = false;
+	let anyCloned = false;
+	const lowRoiFromChildren: string[] = [];
+	for (const child of e.children) {
+		if (!child || typeof child.id !== "string" || child.id.length === 0) {
+			reasons.push("phase-rollup-child-missing-id");
+			continue;
+		}
+		if (seenIds.has(child.id)) reasons.push(`phase-rollup-duplicate-child-id:${child.id}`);
+		seenIds.add(child.id);
+		if (!PHASE_ROLLUP_CHILD_STATUSES.has(child.status)) {
+			reasons.push(`phase-rollup-child-bad-status:${child.id}`);
+		}
+		if (child.status === "completed") completedFromChildren++;
+		if (child.status === "failed" || child.status === "merge_failed") failedFromChildren++;
+		if (typeof child.receiptSha256 !== "string" || !SHA256_HEX.test(child.receiptSha256)) {
+			reasons.push(`phase-rollup-child-bad-receipt-hash:${child.id}`);
+		}
+		if (child.outputUri !== null && (typeof child.outputUri !== "string" || child.outputUri.length === 0)) {
+			reasons.push(`phase-rollup-child-bad-output-uri:${child.id}`);
+		}
+		if (child.outputSha256 !== null && !SHA256_HEX.test(child.outputSha256)) {
+			reasons.push(`phase-rollup-child-bad-output-hash:${child.id}`);
+		}
+		// Receipt-of-receipts integrity requires BOTH an output URI and its
+		// content hash. Reject either one-sided pairing fail-closed: a hash
+		// without a URI is unanchored, and a URI without a hash is unverifiable.
+		if (child.outputSha256 !== null && child.outputUri === null) {
+			reasons.push(`phase-rollup-child-orphan-output-hash:${child.id}`);
+		}
+		if (child.outputUri !== null && child.outputSha256 === null) {
+			reasons.push(`phase-rollup-child-orphan-output-uri:${child.id}`);
+		}
+		// Per-child ROI accounting must be well-formed before it can be summed
+		// for the recomputed aggregate reconciliation below.
+		if (typeof child.tokens !== "number" || !Number.isFinite(child.tokens) || child.tokens < 0) {
+			reasons.push(`phase-rollup-child-bad-tokens:${child.id}`);
+		} else {
+			tokensFromChildren += child.tokens;
+		}
+		if (child.costTotal !== null) {
+			if (typeof child.costTotal !== "number" || !Number.isFinite(child.costTotal) || child.costTotal < 0) {
+				reasons.push(`phase-rollup-child-bad-cost:${child.id}`);
+			} else {
+				anyCost = true;
+				costFromChildren += child.costTotal;
+			}
+		}
+		if (child.clonedTokens !== null) {
+			if (typeof child.clonedTokens !== "number" || !Number.isFinite(child.clonedTokens) || child.clonedTokens < 0) {
+				reasons.push(`phase-rollup-child-bad-cloned-tokens:${child.id}`);
+			} else {
+				anyCloned = true;
+				clonedFromChildren += child.clonedTokens;
+			}
+		}
+		if (typeof child.lowRoi !== "boolean") {
+			reasons.push(`phase-rollup-child-bad-low-roi:${child.id}`);
+		} else if (child.lowRoi) {
+			lowRoiFromChildren.push(child.id);
+		}
+	}
+	const aggregate = e.aggregate;
+	if (!aggregate || typeof aggregate.childCount !== "number") {
+		reasons.push("phase-rollup-missing-aggregate");
+		return reasons;
+	}
+	if (aggregate.childCount !== e.children.length) reasons.push("phase-rollup-child-count-mismatch");
+	if (aggregate.completed !== completedFromChildren) reasons.push("phase-rollup-aggregate-completed-mismatch");
+	if (aggregate.failed !== failedFromChildren) reasons.push("phase-rollup-aggregate-failed-mismatch");
+	for (const field of ["totalTokens", "completed", "failed"] as const) {
+		const value = aggregate[field];
+		if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+			reasons.push(`phase-rollup-aggregate-bad-${field}`);
+		}
+	}
+	for (const field of ["totalCostTotal", "totalClonedTokens"] as const) {
+		const value = aggregate[field];
+		if (value !== null && (typeof value !== "number" || !Number.isFinite(value) || value < 0)) {
+			reasons.push(`phase-rollup-aggregate-bad-${field}`);
+		}
+	}
+	// Recompute the ROI aggregates from child evidence and fail closed on any
+	// self-reported total that does not reconcile. `null` is the canonical
+	// "no child reported this metric" value, mirroring the builder.
+	if (aggregate.totalTokens !== tokensFromChildren) {
+		reasons.push("phase-rollup-aggregate-tokens-mismatch");
+	}
+	if (!numbersReconcile(aggregate.totalCostTotal, anyCost ? costFromChildren : null)) {
+		reasons.push("phase-rollup-aggregate-cost-mismatch");
+	}
+	if (!numbersReconcile(aggregate.totalClonedTokens, anyCloned ? clonedFromChildren : null)) {
+		reasons.push("phase-rollup-aggregate-cloned-tokens-mismatch");
+	}
+	if (!Array.isArray(aggregate.lowRoiChildIds)) {
+		reasons.push("phase-rollup-aggregate-bad-lowRoiChildIds");
+	} else if (!sameIdSet(aggregate.lowRoiChildIds, lowRoiFromChildren)) {
+		reasons.push("phase-rollup-aggregate-low-roi-mismatch");
+	}
+	return reasons;
+}
+
 function validateVanish(e: VanishEvidence): string[] {
 	const reasons: string[] = [];
 	if (!e || typeof e.gitDelta !== "string") return ["vanish-missing-evidence"];
@@ -230,6 +455,9 @@ function validateCompletion(e: CompletionEvidence): string[] {
 		reasons.push("completion-missing-validation-receipts");
 	}
 	if (Array.isArray(e.blockers) && e.blockers.length > 0) reasons.push("completion-has-blockers");
+	// NOTE: evidence.finalLifecycle vs the lifecycle target is reconciled
+	// fail-closed at the ingest layer (`evidenceContradiction` ->
+	// `evidence-lifecycle-mismatch`), where the actual transition is gated.
 	return reasons;
 }
 

package/src/harness-control-plane/rpc-adapter.ts

@@ -36,6 +36,8 @@ export interface HarnessRpc {
 	isLive?(): boolean;
 	/** ISO timestamp of the last observed event frame, or null. */
 	lastFrameAt?(): string | null;
+	/** Final assistant text from the live session (for review-verdict extraction); null when unavailable. */
+	getLastAssistantText?(): Promise<string | null>;
 }
 
 export interface AcceptanceResult {
@@ -240,6 +242,12 @@ export class GajaeCodeRpc implements HarnessRpc {
 		};
 	}
 
+	async getLastAssistantText(): Promise<string | null> {
+		const res = await this.#send({ type: "get_last_assistant_text" });
+		const data = (res.data ?? {}) as Record<string, unknown>;
+		return typeof data.text === "string" ? data.text : null;
+	}
+
 	async sendPrompt(prompt: string): Promise<{ commandId: string; ack: boolean }> {
 		const id = randomUUID();
 		const ackPromise = new Promise<Record<string, unknown>>((resolve, reject) => {

package/src/harness-control-plane/state-machine.ts

@@ -8,6 +8,7 @@
 import type { HarnessLifecycle, NextAllowedAction, PrimitiveResponse, SessionState, SessionStateView } from "./types";
 
 const TERMINAL_LIFECYCLES: ReadonlySet<HarnessLifecycle> = new Set(["completed", "retired"]);
+const SUBMIT_READY_LIFECYCLES: ReadonlySet<HarnessLifecycle> = new Set(["started", "observing"]);
 
 const TRANSITIONS: Record<HarnessLifecycle, readonly HarnessLifecycle[]> = {
 	new: ["started", "blocked", "retired"],
@@ -37,11 +38,32 @@ export function assertTransition(from: HarnessLifecycle, to: HarnessLifecycle):
 	}
 }
 
+export interface NextAllowedActionsOptions {
+	/** Additional live-owner/RPC readiness gate for submit, e.g. rpc-not-idle. */
+	submitUnavailableReason?: string | null;
+}
+
+export function submitUnavailableReason(
+	lifecycle: HarnessLifecycle,
+	ownerLive: boolean,
+	gateReason: string | null = null,
+): string | null {
+	if (isTerminal(lifecycle)) return `lifecycle-terminal:${lifecycle}`;
+	if (lifecycle === "blocked") return "lifecycle-blocked";
+	if (!SUBMIT_READY_LIFECYCLES.has(lifecycle)) return `lifecycle-not-idle:${lifecycle}`;
+	if (!ownerLive) return "owner-not-live";
+	return gateReason;
+}
+
 /**
  * Derive the permitted next actions for a session given its lifecycle and whether
  * a live owner currently holds the lease.
  */
-export function nextAllowedActions(lifecycle: HarnessLifecycle, ownerLive: boolean): NextAllowedAction[] {
+export function nextAllowedActions(
+	lifecycle: HarnessLifecycle,
+	ownerLive: boolean,
+	options: NextAllowedActionsOptions = {},
+): NextAllowedAction[] {
 	const terminal = isTerminal(lifecycle);
 	const actions: NextAllowedAction[] = [];
 	const add = (verb: NextAllowedAction["verb"], available: boolean, reason?: string): void => {
@@ -57,11 +79,10 @@ export function nextAllowedActions(lifecycle: HarnessLifecycle, ownerLive: boole
 	// `start` creates a new session; never re-applicable to an existing record.
 	add("start", false, "session-already-exists");
 
-	// `submit` is owner-routed: it requires a live owner and a non-blocked, non-terminal lifecycle.
-	if (terminal) add("submit", false, `lifecycle-terminal:${lifecycle}`);
-	else if (lifecycle === "blocked") add("submit", false, "lifecycle-blocked");
-	else if (!ownerLive) add("submit", false, "owner-not-live");
-	else add("submit", true);
+	// `submit` is owner-routed: it requires a live owner, a submit-ready lifecycle,
+	// and (for owner-observed responses) an idle/routable RPC backend.
+	const submitReason = submitUnavailableReason(lifecycle, ownerLive, options.submitUnavailableReason ?? null);
+	add("submit", submitReason === null, submitReason ?? undefined);
 
 	// `recover` handles a dead/failed owner, so it is available without a live owner.
 	add("recover", !terminal, terminal ? `lifecycle-terminal:${lifecycle}` : undefined);

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

@@ -18,6 +18,8 @@ import * as fsSync from "node:fs";
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
+import { appendReceiptToConfiguredSpool } from "./receipt-spool";
+import type { ReceiptEnvelope } from "./receipts";
 import type { EventEnvelope, ReceiptFamily, SessionState } from "./types";
 
 interface HarnessRootRegistryEntry {
@@ -227,6 +229,26 @@ async function readJson<T>(file: string): Promise<T | null> {
 		throw error;
 	}
 }
+function isReceiptEnvelope(value: unknown): value is ReceiptEnvelope<unknown> {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const envelope = value as Record<string, unknown>;
+	return (
+		typeof envelope.receiptId === "string" &&
+		typeof envelope.schemaVersion === "number" &&
+		typeof envelope.sessionId === "string" &&
+		typeof envelope.family === "string" &&
+		typeof envelope.valid === "boolean" &&
+		typeof envelope.createdAt === "string" &&
+		typeof envelope.source === "string" &&
+		envelope.subject !== null &&
+		typeof envelope.subject === "object" &&
+		envelope.evidence !== null &&
+		typeof envelope.evidence === "object" &&
+		envelope.artifactHashes !== null &&
+		typeof envelope.artifactHashes === "object" &&
+		typeof envelope.sha256 === "string"
+	);
+}
 
 export async function readSessionState(root: string, sessionId: string): Promise<SessionState | null> {
 	return readJson<SessionState>(sessionPaths(root, sessionId).state);
@@ -372,6 +394,7 @@ export async function writeReceiptImmutable(
 		path: file,
 	};
 	await fs.appendFile(paths.receiptsIndex, `${JSON.stringify(entry)}\n`, "utf8");
+	if (isReceiptEnvelope(value)) await appendReceiptToConfiguredSpool(value);
 	return entry;
 }
 

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

@@ -29,6 +29,33 @@ export function isReviewVerdict(value: unknown): value is ReviewVerdict {
 	return typeof value === "string" && (REVIEW_VERDICTS as readonly string[]).includes(value);
 }
 
+/**
+ * Alias verdict tokens accepted from free-form assistant text, mapped to their canonical verdict.
+ * `MERGE_READY` is treated as `APPROVE_MERGE_READY`.
+ */
+const VERDICT_ALIASES: Readonly<Record<string, ReviewVerdict>> = {
+	MERGE_READY: "APPROVE_MERGE_READY",
+};
+
+/**
+ * Extract a single closed-vocabulary review verdict from free-form assistant text.
+ *
+ * Scans for canonical verdict tokens (and accepted aliases) as whole words and returns the
+ * LAST occurrence — the agent's final stated decision wins over any earlier mention. Returns
+ * null when no allowed token is present, so the finalizer fails closed on a missing verdict.
+ */
+export function extractReviewVerdict(text: string | null | undefined): ReviewVerdict | null {
+	if (typeof text !== "string" || text.length === 0) return null;
+	const tokens = [...REVIEW_VERDICTS, ...Object.keys(VERDICT_ALIASES)];
+	const pattern = new RegExp(`\\b(${tokens.join("|")})\\b`, "g");
+	let last: ReviewVerdict | null = null;
+	for (const match of text.matchAll(pattern)) {
+		const token = match[1];
+		last = VERDICT_ALIASES[token] ?? (token as ReviewVerdict);
+	}
+	return last;
+}
+
 /** Lifecycle states of an operated session. */
 export type HarnessLifecycle =
 	| "new"
@@ -68,7 +95,8 @@ export type ReceiptFamily =
 	| "validation"
 	| "completion"
 	| "review-verdict"
-	| "review-failure";
+	| "review-failure"
+	| "phase-rollup";
 
 /** The CLI verbs / primitives exposed by `gjc harness <verb>`. */
 export type HarnessVerb =
@@ -182,6 +210,10 @@ export interface Observation {
 	rpcLive?: boolean;
 	/** ISO timestamp of the most recent RPC frame the owner observed, if any. */
 	rpcLastFrameAt?: string | null;
+	/** True only when owner/rpc/lifecycle gates indicate a prompt can be submitted now. */
+	readyForSubmit?: boolean;
+	/** Present when readyForSubmit is false; mirrors submit's nextAllowedActions reason. */
+	submitUnavailableReason?: string | null;
 }
 
 /** Input to the deterministic recovery classifier. */

package/src/hindsight/mental-models.ts

@@ -295,12 +295,12 @@ export function summarizeMentalModel(model: MentalModelSummary): string {
  * snapshot only; the diff is computed locally for display purposes.
  *
  * This is intentionally minimal — for "what changed" at a glance, not for a
- * full structural diff. Each side is capped at `MAX_LCS_LINES` lines BEFORE
- * the O(n*m) LCS table is built so a long curated model can never hang the
- * TUI; output is then capped at `maxLines` so the rendered diff stays
- * readable. The cap is signalled inline.
+ * full structural diff. Each side is capped at `MAX_LCS_LINES` lines before
+ * the Hunt-Szymanski LCS pass so a long curated model can never hang the TUI;
+ * output is then capped at `maxLines` so the rendered diff stays readable. The
+ * cap is signalled inline.
  */
-/** Hard cap on input line count per side before LCS. Keeps the O(n*m) table tractable. */
+/** Hard cap on input line count per side before LCS. Keeps worst-case repeated-line matching bounded. */
 export const MAX_LCS_LINES = 1_000;
 
 export function diffMentalModelContent(previous: string | null, current: string, maxLines = 200): string {
@@ -346,24 +346,25 @@ export function diffMentalModelContent(previous: string | null, current: string,
 }
 
 function longestCommonSubsequence(a: string[], b: string[]): string[] {
-	const n = a.length;
-	const m = b.length;
-	if (n === 0 || m === 0) return [];
-	const table: number[][] = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
-	for (let i = 0; i < n; i++) {
-		for (let j = 0; j < m; j++) {
-			table[i + 1][j + 1] = a[i] === b[j] ? table[i][j] + 1 : Math.max(table[i + 1][j], table[i][j + 1]);
+	return longestCommonSubsequenceDense(a, b);
+}
+
+function longestCommonSubsequenceDense(a: string[], b: string[]): string[] {
+	const table: number[][] = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
+	for (let i = 0; i < a.length; i++) {
+		for (let j = 0; j < b.length; j++) {
+			table[i + 1]![j + 1] = a[i] === b[j] ? table[i]![j]! + 1 : Math.max(table[i + 1]![j]!, table[i]![j + 1]!);
 		}
 	}
 	const out: string[] = [];
-	let i = n;
-	let j = m;
+	let i = a.length;
+	let j = b.length;
 	while (i > 0 && j > 0) {
 		if (a[i - 1] === b[j - 1]) {
-			out.push(a[i - 1]);
+			out.push(a[i - 1]!);
 			i--;
 			j--;
-		} else if (table[i - 1][j] >= table[i][j - 1]) {
+		} else if (table[i - 1]![j]! >= table[i]![j - 1]!) {
 			i--;
 		} else {
 			j--;