@gajae-code/coding-agent 0.12.2 → 0.12.5

package/src/gjc-runtime/ultragoal-evidence.ts

@@ -1,5 +1,8 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
 import * as path from "node:path";
 import { inflateSync } from "node:zlib";
+import { isCompiledBinary } from "@gajae-code/utils/env";
 import {
 	evidenceKindMatches,
 	hasExistingNonEmptyArtifact,
@@ -382,6 +385,25 @@ function clampCliReplayTimeout(value: unknown): number {
 function basenameCommand(value: string): string {
 	return path.basename(value).toLowerCase();
 }
+
+function isDeterministicConsoleLogReplay(code: string): boolean {
+	let remaining = code.trim();
+	if (remaining.length === 0) return false;
+	let matched = false;
+	while (remaining.length > 0) {
+		const match =
+			/^console\.log\(\s*("(?:\\[\s\S]|[^"\\])*"|'(?:\\[\s\S]|[^'\\])*'|`(?:\\[\s\S]|[^`\\$])*`)\s*\)\s*;?\s*/.exec(
+				remaining,
+			);
+		if (!match) return false;
+		const statement = match[0]!;
+		const literal = match[1]!;
+		if (literal.startsWith("`") && literal.includes("${")) return false;
+		matched = true;
+		remaining = remaining.slice(statement.length);
+	}
+	return matched;
+}
 function hasShellRedirectionToken(value: string): boolean {
 	return /^(?:[<>]|\d?[<>]|\d?>&\d|\|\|?|&&|;)$/.test(value) || /(?:^|[^\w])-?>/.test(value);
 }
@@ -413,19 +435,73 @@ export function isAllowedGitReplayCommand(args: readonly string[]): boolean {
 	return true;
 }
 
-function resolveCliReplayCommand(command: string[]): string[] {
-	if (basenameCommand(command[0]!) === "bun") return [process.execPath, ...command.slice(1)];
-	return command;
+function isBareExecutableName(value: string): boolean {
+	return (
+		value.length > 0 &&
+		!value.includes("/") &&
+		!value.includes("\\") &&
+		value === path.basename(value) &&
+		value === value.toLowerCase()
+	);
+}
+
+function isAllowedCliReplayCommand(command: readonly string[]): boolean {
+	if (
+		command.length === 0 ||
+		command.some(arg => arg.trim() !== arg || arg.length === 0 || hasShellRedirectionToken(arg))
+	)
+		return false;
+	if (!isBareExecutableName(command[0]!) || command[0] !== "bun") return false;
+	const args = command.slice(1);
+	if (args.length === 1 && args[0] === "--version") return true;
+	return args.length === 2 && args[0] === "-e" && isDeterministicConsoleLogReplay(args[1]!);
 }
 
-function resolveUnderCwd(cwd: string, replayCwd: unknown, fieldName: string): string {
+function summarizeBlockedCliReplayCommand(command: readonly string[]): string {
+	const executable = command[0] ? basenameCommand(command[0]) : "<missing>";
+	const argCount = Math.max(0, command.length - 1);
+	return `${JSON.stringify(executable)} with ${argCount} arg${argCount === 1 ? "" : "s"}`;
+}
+
+function cliReplayAllowlistDescription(): string {
+	return '`bun --version` or deterministic `bun -e "console.log(...)"`; focused bun test execution is blocked and replayExempt still requires an existing screenshot, automation, or PTY structural fallback';
+}
+
+export function resolveCliReplayCommand(command: string[], options?: { compiled?: boolean }): string[] {
+	if (options?.compiled ?? isCompiledBinary()) {
+		throw new Error(
+			"CLI replay execution is unavailable in the compiled GJC runtime because process.execPath is the GJC application, not a Bun CLI executable",
+		);
+	}
+	return [process.execPath, ...command.slice(1)];
+}
+
+async function resolveUnderCwd(cwd: string, replayCwd: unknown, fieldName: string): Promise<string> {
 	const relative = replayCwd === undefined ? "." : nonEmptyString(replayCwd);
 	if (!relative) throw new Error(`qualityGate ${fieldName}.cwd must be a non-empty string when provided`);
-	const root = path.resolve(cwd);
-	const resolved = path.resolve(root, relative);
+	const lexicalRoot = path.resolve(cwd);
+	const lexical = path.resolve(lexicalRoot, relative);
+	const relativeToLexicalRoot = path.relative(lexicalRoot, lexical);
+	if (
+		relativeToLexicalRoot === ".." ||
+		relativeToLexicalRoot.startsWith(`..${path.sep}`) ||
+		path.isAbsolute(relativeToLexicalRoot)
+	) {
+		throw new Error(`qualityGate ${fieldName}.cwd must resolve under the repository cwd`);
+	}
+	let root: string;
+	let resolved: string;
+	try {
+		[root, resolved] = await Promise.all([fs.realpath(lexicalRoot), fs.realpath(lexical)]);
+	} catch {
+		throw new Error(`qualityGate ${fieldName}.cwd must reference an existing directory under the repository cwd`);
+	}
 	const relativeToRoot = path.relative(root, resolved);
 	if (relativeToRoot === ".." || relativeToRoot.startsWith(`..${path.sep}`) || path.isAbsolute(relativeToRoot)) {
-		throw new Error(`qualityGate ${fieldName}.cwd must resolve under the repository cwd`);
+		throw new Error(`qualityGate ${fieldName}.cwd must resolve under the repository cwd without symlink escape`);
+	}
+	if (!(await fs.stat(resolved)).isDirectory()) {
+		throw new Error(`qualityGate ${fieldName}.cwd must reference a directory`);
 	}
 	return resolved;
 }
@@ -467,16 +543,40 @@ function normalizeCliReplayOutput(value: string, cwd: string): string {
 }
 
 export async function readCliReplayRecord(cwd: string, row: JsonObject, fieldName: string): Promise<JsonObject | null> {
-	// A row is an inline replay record only when it actually carries replay fields.
-	// `kind: "cli-replay"` alone is the natural kind for an artifactRef that *points*
-	// at a replay file, so treating that as inline meant the referenced `path` was
-	// never read and surfaced a confusing `schemaVersion must be 1` error on the ref.
-	const inline =
-		qualityGateObject(row.replay) ?? (row.kind === "cli-replay" && row.command !== undefined ? row : null);
-	if (inline) return inline;
+	const nestedReplay = row.replay === undefined ? null : qualityGateObject(row.replay);
+	if (row.replay !== undefined && !nestedReplay) {
+		throw new Error(`qualityGate ${fieldName}.replay must be an object when provided`);
+	}
+	const inlineFieldNames = [
+		"schemaVersion",
+		"replaySafe",
+		"command",
+		"cwd",
+		"env",
+		"timeoutMs",
+		"expectedExitCode",
+		"recordedStdout",
+		"recordedStderr",
+		"normalization",
+		"invariants",
+		"replayExempt",
+	];
+	const hasTopLevelInlineFields = inlineFieldNames.some(name => row[name] !== undefined);
+	const hasPath = row.path !== undefined;
+	if (nestedReplay && (hasPath || hasTopLevelInlineFields)) {
+		throw new Error(`qualityGate ${fieldName} must not mix nested replay, artifact path, or top-level replay fields`);
+	}
+	if (hasTopLevelInlineFields && hasPath) {
+		throw new Error(`qualityGate ${fieldName} must not mix inline replay fields with an artifact path`);
+	}
+	if (nestedReplay) return nestedReplay;
+	if (row.kind === "cli-replay" && hasTopLevelInlineFields) return row;
 	if (!evidenceKindMatches(normalizedEvidenceKind(row), ["cli-replay", "command-replay"])) return null;
+	if (!hasPath) {
+		throw new Error(`qualityGate ${fieldName} CLI replay artifact must provide either replay fields or path`);
+	}
 	const bytes = await readArtifactBytes(cwd, row, fieldName);
-	if (!bytes) return null;
+	if (!bytes) throw new Error(`qualityGate ${fieldName} CLI replay artifact path must reference a readable file`);
 	try {
 		return requireQualityGateObject(JSON.parse(bytes.toString("utf8")), `${fieldName}.replay`);
 	} catch (error) {
@@ -494,6 +594,7 @@ function parseCliReplayRecord(
 	timeoutMs: number;
 	expectedExitCode: number;
 	recordedStdout: string;
+	recordedStderr: string;
 	invariants: JsonObject[];
 } {
 	if (record.schemaVersion !== 1) throw new Error(`qualityGate ${fieldName}.schemaVersion must be 1`);
@@ -505,6 +606,11 @@ function parseCliReplayRecord(
 	if (!command) throw new Error(`qualityGate ${fieldName}.command must be a non-empty string array`);
 	if (record.replaySafe !== true)
 		throw new Error(`qualityGate ${fieldName}.replaySafe must be true before CLI replay executes`);
+	if (!isAllowedCliReplayCommand(command)) {
+		throw new Error(
+			`qualityGate ${fieldName}.command is not in the deterministic CLI replay allowlist; command ${summarizeBlockedCliReplayCommand(command)} is blocked. Allowed replay commands: ${cliReplayAllowlistDescription()}. For other commands, provide audited replayExempt metadata with reasonCode, reason, approvedBy, and fallbackArtifactRefs that point to a structurally valid fallback artifact.`,
+		);
+	}
 	if (record.normalization !== undefined && record.normalization !== "default") {
 		throw new Error(`qualityGate ${fieldName}.normalization must be default when provided`);
 	}
@@ -526,6 +632,7 @@ function parseCliReplayRecord(
 		timeoutMs: clampCliReplayTimeout(record.timeoutMs),
 		expectedExitCode,
 		recordedStdout: record.recordedStdout,
+		recordedStderr: typeof record.recordedStderr === "string" ? record.recordedStderr : "",
 		invariants,
 	};
 }
@@ -597,11 +704,24 @@ async function collectCliReplayOutput(
 
 export interface ReplayProcessHandle {
 	readonly exited: Promise<number>;
+	readonly pid?: number;
 	kill(signal?: number | NodeJS.Signals): void;
 }
 
+function signalReplayProcessTree(handle: ReplayProcessHandle, signal: NodeJS.Signals): void {
+	if (process.platform !== "win32" && Number.isInteger(handle.pid) && (handle.pid ?? 0) > 0) {
+		try {
+			process.kill(-handle.pid!, signal);
+			return;
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ESRCH") return;
+		}
+	}
+	handle.kill(signal);
+}
+
 export async function waitForReplayProcessWithTimeout(
-	process: ReplayProcessHandle,
+	handle: ReplayProcessHandle,
 	timeoutMs: number,
 	graceMs = 2000,
 ): Promise<number> {
@@ -611,21 +731,21 @@ export async function waitForReplayProcessWithTimeout(
 	const timeout = new Promise<typeof timedOut>(resolve => {
 		timeoutTimer = setTimeout(() => resolve(timedOut), timeoutMs);
 	});
-	const first = await Promise.race([process.exited, timeout]);
+	const first = await Promise.race([handle.exited, timeout]);
 	if (first !== timedOut) {
 		if (timeoutTimer) clearTimeout(timeoutTimer);
 		return first;
 	}
-	process.kill("SIGTERM");
+	signalReplayProcessTree(handle, "SIGTERM");
 	const killed = Symbol("killed");
 	const grace = new Promise<typeof killed>(resolve => {
 		graceTimer = setTimeout(() => {
-			process.kill("SIGKILL");
+			signalReplayProcessTree(handle, "SIGKILL");
 			resolve(killed);
 		}, graceMs);
 	});
-	await Promise.race([process.exited, grace]);
-	await process.exited.catch(() => undefined);
+	await Promise.race([handle.exited, grace]);
+	await handle.exited.catch(() => undefined);
 	if (timeoutTimer) clearTimeout(timeoutTimer);
 	if (graceTimer) clearTimeout(graceTimer);
 	throw new Error("timeout");
@@ -684,18 +804,20 @@ export async function validateCliReplay(
 	}
 	void options.live;
 	const replay = parseCliReplayRecord(record, fieldName);
-	const replayCwd = resolveUnderCwd(cwd, replay.replayCwd, fieldName);
-	const process = Bun.spawn(resolveCliReplayCommand(replay.command), {
-		cwd: replayCwd,
-		env: replay.env,
-		stdout: "pipe",
-		stderr: "pipe",
-	});
+	await resolveUnderCwd(cwd, replay.replayCwd, fieldName);
+	const executionCwd = await fs.mkdtemp(path.join(os.tmpdir(), "gjc-cli-replay-"));
 	try {
+		const subprocess = Bun.spawn(resolveCliReplayCommand(replay.command), {
+			cwd: executionCwd,
+			env: { ...replay.env, HOME: executionCwd, TMPDIR: executionCwd },
+			stdout: "pipe",
+			stderr: "pipe",
+			detached: process.platform !== "win32",
+		});
 		const [stdout, stderr, exitCode] = await Promise.all([
-			collectCliReplayOutput(process.stdout),
-			collectCliReplayOutput(process.stderr),
-			waitForReplayProcessWithTimeout(process, replay.timeoutMs),
+			collectCliReplayOutput(subprocess.stdout),
+			collectCliReplayOutput(subprocess.stderr),
+			waitForReplayProcessWithTimeout(subprocess, replay.timeoutMs),
 		]);
 		if (stdout.truncated || stderr.truncated)
 			throw new Error(`qualityGate ${fieldName} CLI replay output exceeded 1 MiB buffer cap`);
@@ -706,6 +828,11 @@ export async function validateCliReplay(
 		}
 		const actualStdout = normalizeCliReplayOutput(stdout.text, cwd);
 		const recordedStdout = normalizeCliReplayOutput(replay.recordedStdout, cwd);
+		const actualStderr = normalizeCliReplayOutput(stderr.text, cwd);
+		const recordedStderr = normalizeCliReplayOutput(replay.recordedStderr, cwd);
+		if (actualStderr !== recordedStderr) {
+			throw new Error(`qualityGate ${fieldName} CLI replay stderr did not match recordedStderr after normalization`);
+		}
 		if (!replay.invariants.length || !validateCliReplayInvariants(replay.invariants, actualStdout, fieldName)) {
 			if (actualStdout !== recordedStdout) {
 				throw new Error(
@@ -719,6 +846,8 @@ export async function validateCliReplay(
 			throw new Error(`qualityGate ${fieldName} CLI replay timed out after ${replay.timeoutMs}ms`);
 		}
 		throw error;
+	} finally {
+		await fs.rm(executionCwd, { recursive: true, force: true }).catch(() => undefined);
 	}
 }
 

package/src/gjc-runtime/ultragoal-runtime.ts

@@ -1,4 +1,5 @@
 import * as crypto from "node:crypto";
+import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { getConfigRootDir } from "@gajae-code/utils";
 import type { WorkflowHudSummary } from "../skill-state/active-state";
@@ -1794,27 +1795,46 @@ export function hasTypedVerifiedReceipt(value: unknown): boolean {
 	return Boolean(type && id && (status === "verified" || status === "passed"));
 }
 
-export async function hasExistingNonEmptyArtifact(cwd: string, value: unknown): Promise<boolean> {
+async function resolveExistingArtifactPathUnderCwd(
+	cwd: string,
+	value: unknown,
+	fieldName: string,
+): Promise<string | null> {
 	const artifactPath = nonEmptyString(value);
-	if (!artifactPath) return false;
-	const resolved = path.resolve(cwd, artifactPath);
+	if (!artifactPath) return null;
+	const lexicalRoot = path.resolve(cwd);
+	const lexical = path.resolve(lexicalRoot, artifactPath);
+	const lexicalRelative = path.relative(lexicalRoot, lexical);
+	if (lexicalRelative === ".." || lexicalRelative.startsWith(`..${path.sep}`) || path.isAbsolute(lexicalRelative)) {
+		throw new Error(`qualityGate ${fieldName} artifact path must resolve under the repository cwd`);
+	}
 	try {
-		const file = Bun.file(resolved);
-		return (await file.exists()) && file.size > 0;
+		const [root, resolved] = await Promise.all([fs.realpath(lexicalRoot), fs.realpath(lexical)]);
+		const relative = path.relative(root, resolved);
+		if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+			throw new Error(`qualityGate ${fieldName} artifact path must not escape the repository cwd through symlinks`);
+		}
+		if (!(await fs.stat(resolved)).isFile()) {
+			throw new Error(`qualityGate ${fieldName} artifact path must reference a regular file`);
+		}
+		return resolved;
 	} catch (error) {
-		if (isEnoent(error)) return false;
+		if (isEnoent(error)) return null;
 		throw error;
 	}
 }
 
+export async function hasExistingNonEmptyArtifact(cwd: string, value: unknown): Promise<boolean> {
+	const resolved = await resolveExistingArtifactPathUnderCwd(cwd, value, "artifact");
+	if (!resolved) return false;
+	return (await fs.stat(resolved)).size > 0;
+}
+
 export async function readArtifactBytes(cwd: string, row: JsonObject, fieldName: string): Promise<Buffer | null> {
-	const artifactPath = nonEmptyString(row.path);
-	if (!artifactPath) return null;
-	const resolved = path.resolve(cwd, artifactPath);
+	const resolved = await resolveExistingArtifactPathUnderCwd(cwd, row.path, fieldName);
+	if (!resolved) return null;
 	try {
-		const file = Bun.file(resolved);
-		if (!(await file.exists())) return null;
-		return Buffer.from(await file.arrayBuffer());
+		return Buffer.from(await Bun.file(resolved).arrayBuffer());
 	} catch (error) {
 		if (isEnoent(error)) return null;
 		throw new Error(`qualityGate ${fieldName} artifact could not be read: ${String(error)}`);
@@ -1823,6 +1843,7 @@ export async function readArtifactBytes(cwd: string, row: JsonObject, fieldName:
 
 import {
 	readCliReplayRecord,
+	resolveCliReplayCommand,
 	validateArtifactProof,
 	validateCliReplay,
 	validateLiveSurfaceProofPresence,
@@ -1834,6 +1855,7 @@ import {
 
 export type { ReplayProcessHandle } from "./ultragoal-evidence";
 export {
+	resolveCliReplayCommand,
 	validateArtifactProof,
 	validateCliReplay,
 	validateLiveSurfaceProofPresence,
@@ -2230,6 +2252,169 @@ function validateDeferredLaneDeclaration(deferred: JsonObject, fieldName: string
 	}
 }
 
+/**
+ * Agent-friendly deferred-gate hydration: the runtime already stores the durable
+ * batch tuple and computes the cumulative change set itself, so a deferred gate
+ * only has to prove what the runtime cannot know — that targeted verification ran.
+ * Every mechanical field (`kind`, the batch tuple, `deferredLanes`, and the whole
+ * `changeSet` block including `paths` and `changeSetHash`) is auto-filled when
+ * omitted. Explicitly supplied values are never overwritten, so a wrong
+ * declaration still fails closed.
+ */
+function hydrateDeferredGateDefaults(
+	gate: JsonObject,
+	goal: UltragoalGoal,
+	changeSet: UltragoalChangeSet | undefined,
+): JsonObject {
+	const deferred = qualityGateObject(gate.deferredToBatch);
+	if (!deferred) return gate;
+	const metadata = goal.validationBatch;
+	// The final member must carry the full strict gate; never help it defer.
+	if (metadata && goal.id === metadata.finalGoalId) return gate;
+	const hydrated: JsonObject = { ...deferred };
+	if (hydrated.kind === undefined) hydrated.kind = "validation-batch-deferred";
+	if (metadata) {
+		if (hydrated.schemaVersion === undefined) hydrated.schemaVersion = metadata.schemaVersion;
+		if (hydrated.batchId === undefined) hydrated.batchId = metadata.batchId;
+		if (hydrated.memberIds === undefined) hydrated.memberIds = [...metadata.memberIds];
+		if (hydrated.finalGoalId === undefined) hydrated.finalGoalId = metadata.finalGoalId;
+		if (hydrated.metadataHash === undefined) hydrated.metadataHash = metadata.metadataHash;
+	}
+	if (hydrated.deferredLanes === undefined) hydrated.deferredLanes = ["architectReview", "executorQa"];
+	const computedRows = (changeSet?.paths ?? []).map(row => ({
+		path: row.path,
+		status: row.status,
+		...(row.oldPath ? { oldPath: row.oldPath } : {}),
+	}));
+	const computedByPath = new Map(computedRows.map(row => [row.path, row]));
+	const declared = qualityGateObject(hydrated.changeSet);
+	const changeSetRecord: JsonObject = declared ? { ...declared } : {};
+	if (changeSetRecord.memberGoalId === undefined) changeSetRecord.memberGoalId = goal.id;
+	if (changeSetRecord.cumulativeFromBase === undefined) changeSetRecord.cumulativeFromBase = true;
+	if (changeSetRecord.paths === undefined) {
+		changeSetRecord.paths = computedRows;
+	} else if (Array.isArray(changeSetRecord.paths)) {
+		// Accept plain-string rows and rows without a status; resolve the status
+		// from the computed change set instead of demanding git trivia.
+		changeSetRecord.paths = changeSetRecord.paths.map(row => {
+			const record = typeof row === "string" ? { path: row } : qualityGateObject(row);
+			if (!record) return row;
+			const pathValue = nonEmptyString(record.path);
+			if (!pathValue || nonEmptyString(record.status)) return record;
+			const computed = computedByPath.get(normalizeRepoPath(pathValue));
+			return {
+				...record,
+				status: computed?.status ?? "unknown",
+				...(computed?.oldPath && record.oldPath === undefined ? { oldPath: computed.oldPath } : {}),
+			};
+		});
+	}
+	if (changeSetRecord.changeSetHash === undefined) {
+		try {
+			changeSetRecord.changeSetHash = changeSetHashForPaths(
+				canonicalChangeSetRows(changeSetRecord.paths, "deferredToBatch.changeSet.paths"),
+			);
+		} catch {
+			// Malformed rows: leave the hash unset so validation reports the row defect.
+		}
+	}
+	hydrated.changeSet = changeSetRecord;
+	return { ...gate, deferredToBatch: hydrated };
+}
+
+/**
+ * Agent-friendly batch-close hydration, mirroring `hydrateDeferredGateDefaults`:
+ * every `validationBatchClose` field except `coverageEvidence` is derivable from
+ * durable state (batch metadata, member receipts) and the computed cumulative
+ * change set, so it is auto-filled when omitted. Supplied values are never
+ * overwritten and still fail closed when wrong. The minimal close is the full
+ * strict gate plus `{"validationBatchClose":{"coverageEvidence":"..."}}`.
+ */
+function hydrateBatchCloseDefaults(input: {
+	gate: JsonObject;
+	plan: UltragoalPlan;
+	goal: UltragoalGoal;
+	ledger: readonly UltragoalLedgerEvent[];
+	changeSet?: UltragoalChangeSet;
+}): JsonObject {
+	const metadata = input.goal.validationBatch;
+	if (!metadata || input.goal.id !== metadata.finalGoalId) return input.gate;
+	const requested = qualityGateObject(input.gate.validationBatchClose);
+	if (!requested) return input.gate;
+	// The replacement-close kind has its own dedicated hydrator.
+	if (requested.kind === "review-blocker-replacement-close") return input.gate;
+	const close: JsonObject = { ...requested };
+	if (close.schemaVersion === undefined) close.schemaVersion = 1;
+	if (close.kind === undefined) close.kind = "validation-batch-close";
+	if (close.batchId === undefined) close.batchId = metadata.batchId;
+	if (close.finalGoalId === undefined) close.finalGoalId = metadata.finalGoalId;
+	if (close.memberIds === undefined) close.memberIds = [...metadata.memberIds];
+	const derivedMetadataHashes: Record<string, string> = {};
+	const derivedChangeSetHashes: Record<string, string> = {};
+	const derivedReceipts: JsonObject[] = [];
+	for (const memberId of metadata.memberIds) {
+		const member = input.plan.goals.find(goal => goal.id === memberId);
+		if (member?.validationBatch) derivedMetadataHashes[memberId] = member.validationBatch.metadataHash;
+		if (!member || memberId === input.goal.id) continue;
+		try {
+			const receipt = requireDeferredMemberReceiptFresh(
+				input.plan,
+				input.ledger,
+				member,
+				"validationBatchClose hydration",
+			);
+			derivedChangeSetHashes[memberId] = receipt.validationBatch.changeSetHash;
+			derivedReceipts.push({
+				goalId: memberId,
+				receiptId: receipt.receiptId,
+				checkpointLedgerEventId: receipt.checkpointLedgerEventId,
+				qualityGateHash: receipt.qualityGateHash,
+				changeSetHash: receipt.validationBatch.changeSetHash,
+				role: "deferred-member",
+			});
+		} catch {
+			// Member not fresh/complete: omit it so validation reports the real defect.
+		}
+	}
+	const suppliedMetadataHashes = qualityGateObject(close.memberMetadataHashes);
+	if (close.memberMetadataHashes === undefined) close.memberMetadataHashes = derivedMetadataHashes;
+	else if (suppliedMetadataHashes)
+		close.memberMetadataHashes = { ...derivedMetadataHashes, ...suppliedMetadataHashes };
+	if (close.memberReceipts === undefined) close.memberReceipts = derivedReceipts;
+	const requestedUnion = qualityGateObject(close.unionChangeSet);
+	const union: JsonObject = requestedUnion ? { ...requestedUnion } : {};
+	if (union.source === undefined) union.source = "validation-batch";
+	if (union.paths === undefined) {
+		union.paths = (input.changeSet?.paths ?? []).map(row => ({
+			path: row.path,
+			status: row.status,
+			...(row.oldPath ? { oldPath: row.oldPath } : {}),
+		}));
+	}
+	try {
+		const unionRows = canonicalChangeSetRows(union.paths, "validationBatchClose.unionChangeSet.paths");
+		const suppliedChangeSetHashes = qualityGateObject(union.memberChangeSetHashes);
+		const memberChangeSetHashes: Record<string, unknown> = {
+			...derivedChangeSetHashes,
+			[metadata.finalGoalId]: changeSetHashForPaths(unionRows),
+			...suppliedChangeSetHashes,
+		};
+		if (union.memberChangeSetHashes === undefined || suppliedChangeSetHashes) {
+			union.memberChangeSetHashes = memberChangeSetHashes;
+		}
+		if (union.unionHash === undefined) {
+			union.unionHash = hashStructuredValue({
+				memberChangeSetHashes: qualityGateObject(union.memberChangeSetHashes) ?? memberChangeSetHashes,
+				paths: unionRows.map(row => ({ path: row.path, status: row.status, oldPath: row.oldPath })),
+			});
+		}
+	} catch {
+		// Malformed rows: leave derived hashes unset so validation reports the row defect.
+	}
+	close.unionChangeSet = union;
+	return { ...input.gate, validationBatchClose: close };
+}
+
 function validateDeferredCompletionQualityGate(
 	gate: JsonObject,
 	goal: UltragoalGoal,
@@ -2251,7 +2436,9 @@ function validateDeferredCompletionQualityGate(
 	}
 	const deferredLanes = stringArray(deferred.deferredLanes)?.filter(Boolean).sort();
 	if (deferredLanes?.join(",") !== "architectReview,executorQa")
-		throw new Error("deferredToBatch.deferredLanes must be architectReview and executorQa");
+		throw new Error(
+			"deferredToBatch.deferredLanes must be architectReview and executorQa (or omitted; the runtime fills it)",
+		);
 	const targeted = qualityGateObject(deferred.targetedVerification);
 	if (!targeted || targeted.status !== PASSED_STATUS || !nonEmptyStringArray(targeted.commands))
 		throw new Error("deferredToBatch.targetedVerification must pass with non-empty commands");
@@ -2276,13 +2463,17 @@ function validateDeferredCompletionQualityGate(
 	const declaredChangeSet = qualityGateObject(deferred.changeSet);
 	if (!declaredChangeSet) throw new Error("deferredToBatch.changeSet is required");
 	if (declaredChangeSet.memberGoalId !== goal.id)
-		throw new Error("deferredToBatch.changeSet.memberGoalId must label the checkpointed goal");
+		throw new Error(
+			`deferredToBatch.changeSet.memberGoalId must label the checkpointed goal ${goal.id} (or be omitted; the runtime fills it)`,
+		);
 	if (declaredChangeSet.cumulativeFromBase !== true)
-		throw new Error("deferredToBatch.changeSet.cumulativeFromBase must be true");
+		throw new Error("deferredToBatch.changeSet.cumulativeFromBase must be true (or omitted; the runtime fills it)");
 	const paths = canonicalChangeSetRows(declaredChangeSet.paths, "deferredToBatch.changeSet.paths");
 	requireChangeSetCoverage(changeSet, paths, "deferredToBatch.changeSet.paths");
 	if (declaredChangeSet.changeSetHash !== changeSetHashForPaths(paths))
-		throw new Error("deferredToBatch.changeSet.changeSetHash does not match declared paths");
+		throw new Error(
+			"deferredToBatch.changeSet.changeSetHash does not match declared paths; omit changeSetHash and the runtime computes it",
+		);
 }
 const COHORT_LANE_KEYS = ["cleaner", "architect", "qa"] as const;
 
@@ -2983,8 +3174,17 @@ export async function validateUltragoalQualityGateReadOnly(input: {
 	}
 	const ledger = plan ? await readUltragoalLedger(input.cwd, sessionId) : undefined;
 	const changeSet = await computeCheckpointChangeSet(input.cwd);
+	let hydratedGate = goal ? hydrateDeferredGateDefaults(gate, goal, changeSet) : gate;
+	if (goal && plan && ledger) {
+		hydratedGate = hydrateBatchCloseDefaults({ gate: hydratedGate, plan, goal, ledger, changeSet });
+	}
 	try {
-		await validateCompletionQualityGate(input.cwd, gate, { changeSet, plan: plan ?? undefined, goal, ledger });
+		await validateCompletionQualityGate(input.cwd, hydratedGate, {
+			changeSet,
+			plan: plan ?? undefined,
+			goal,
+			ledger,
+		});
 		return { valid: true, errors: [] };
 	} catch (error) {
 		if (error instanceof UltragoalQualityGateError) return { valid: false, errors: error.diagnostics };
@@ -3031,13 +3231,25 @@ async function readRequiredCompletionQualityGate(
 					changeSet: options.changeSet,
 				})
 			: gateObject;
-	await validateCompletionQualityGate(cwd, hydratedGate, {
+	let completionGate = options.goal
+		? hydrateDeferredGateDefaults(hydratedGate, options.goal, options.changeSet)
+		: hydratedGate;
+	if (options.goal && options.plan && options.ledger) {
+		completionGate = hydrateBatchCloseDefaults({
+			gate: completionGate,
+			plan: options.plan,
+			goal: options.goal,
+			ledger: options.ledger,
+			changeSet: options.changeSet,
+		});
+	}
+	await validateCompletionQualityGate(cwd, completionGate, {
 		changeSet: options.changeSet,
 		plan: options.plan,
 		goal: options.goal,
 		ledger: options.ledger,
 	});
-	return hydratedGate;
+	return completionGate;
 }
 
 function validateCompleteCheckpointTargetGoal(goal: UltragoalGoal): void {