@gajae-code/coding-agent 0.11.0 → 0.11.2

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

@@ -1,7 +1,6 @@
 import * as crypto from "node:crypto";
 import * as os from "node:os";
 import * as path from "node:path";
-import { inflateSync } from "node:zlib";
 import type { WorkflowHudSummary } from "../skill-state/active-state";
 import { buildUltragoalHudSummary as buildWorkflowUltragoalHudSummary } from "../skill-state/workflow-hud";
 import { renderCliWriteReceipt } from "./cli-write-receipt";
@@ -291,18 +290,18 @@ export interface UltragoalCommandResult {
 	createdPlan?: boolean;
 }
 
-interface JsonObject {
+export interface JsonObject {
 	[key: string]: unknown;
 }
 
-function currentUltragoalSessionId(cwd: string): string {
+export function currentUltragoalSessionId(cwd: string): string {
 	return resolveGjcSessionForWrite(cwd, { envSessionId: process.env.GJC_SESSION_ID }).gjcSessionId;
 }
 
 const TERMINAL_OR_SKIPPED_STATUSES = new Set<UltragoalGoalStatus>(["complete", "superseded"]);
 const CLEAN_ARCHITECT_STATUS = "CLEAR";
 const APPROVE_RECOMMENDATION = "APPROVE";
-const PASSED_STATUS = "passed";
+export const PASSED_STATUS = "passed";
 const NOT_APPLICABLE_STATUS = "not_applicable";
 const COVERED_STATUS = "covered";
 const ACCEPTED_PROOF_STATUSES = new Set([COVERED_STATUS, "passed", "verified"]);
@@ -364,13 +363,17 @@ export function getUltragoalPaths(cwd: string, sessionId?: string | null): Ultra
 	};
 }
 
-function isEnoent(error: unknown): boolean {
+export function isEnoent(error: unknown): boolean {
 	return (
 		typeof error === "object" && error !== null && "code" in error && (error as { code?: unknown }).code === "ENOENT"
 	);
 }
 
-async function appendLedger(cwd: string, event: JsonObject, sessionId?: string | null): Promise<UltragoalLedgerEvent> {
+export async function appendLedger(
+	cwd: string,
+	event: JsonObject,
+	sessionId?: string | null,
+): Promise<UltragoalLedgerEvent> {
 	const resolvedSessionId =
 		sessionId?.trim() || resolveGjcSessionForWrite(cwd, { envSessionId: process.env.GJC_SESSION_ID }).gjcSessionId;
 	const paths = getUltragoalPaths(cwd, resolvedSessionId);
@@ -554,7 +557,7 @@ export async function recordUltragoalNudgeIfBudgetRemaining(input: {
 	);
 }
 
-async function writePlan(cwd: string, plan: UltragoalPlan, sessionId?: string | null): Promise<void> {
+export async function writePlan(cwd: string, plan: UltragoalPlan, sessionId?: string | null): Promise<void> {
 	const resolvedSessionId =
 		sessionId?.trim() || resolveGjcSessionForWrite(cwd, { envSessionId: process.env.GJC_SESSION_ID }).gjcSessionId;
 	const paths = getUltragoalPaths(cwd, resolvedSessionId);
@@ -573,16 +576,32 @@ async function writePlan(cwd: string, plan: UltragoalPlan, sessionId?: string |
 
 function chooseReceiptKind(
 	plan: UltragoalPlan,
+	ledger: readonly UltragoalLedgerEvent[],
 	goal: UltragoalGoal,
 	status: UltragoalGoalStatus,
 ): UltragoalReceiptKind {
 	if (plan.gjcGoalMode === "per-story") return "per-goal";
 	if (status !== "complete") return "per-goal";
+	// A non-final validation-batch member must always carry a per-goal
+	// deferred receipt; only the batch's final goal may close the batch and
+	// (in aggregate mode) carry the final-aggregate receipt. Without this, a
+	// context-stale re-verification replay of a member could mint an invalid
+	// final-aggregate receipt with validationBatch.role "deferred-member".
+	if (goal.validationBatch && goal.validationBatch.finalGoalId !== goal.id) return "per-goal";
 	const requiredGoals = requiredUltragoalGoals(plan);
-	const existingFinalAggregateGoal = requiredGoals.find(
-		item => item.id !== goal.id && item.completionVerification?.receiptKind === "final-aggregate",
-	);
-	if (existingFinalAggregateGoal) return "per-goal";
+	// Only a still-fresh final-aggregate receipt on another goal defers this
+	// checkpoint to per-goal. A stale one (e.g. staled by `steer add_subgoal`
+	// appending goals after a terminal run) must not suppress re-minting,
+	// otherwise the run can never regain a verifiable final-aggregate receipt:
+	// the completion guard demands a fresh final-aggregate receipt while this
+	// gate would keep answering per-goal forever.
+	const existingFreshFinalAggregateGoal = requiredGoals.find(item => {
+		if (item.id === goal.id) return false;
+		const receipt = item.completionVerification;
+		if (receipt?.receiptKind !== "final-aggregate") return false;
+		return validateReceiptFreshBase({ plan, ledger, goal: item, receipt, receiptKind: "final-aggregate" }) === null;
+	});
+	if (existingFreshFinalAggregateGoal) return "per-goal";
 	const unfinishedRequiredGoals = requiredGoals.filter(
 		item => item.id !== goal.id && !TERMINAL_OR_SKIPPED_STATUSES.has(item.status),
 	);
@@ -673,10 +692,10 @@ function buildCompletionReceipt(input: {
 	};
 }
 
-function nonEmptyString(value: unknown): string | null {
+export function nonEmptyString(value: unknown): string | null {
 	return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
 }
-function stringArray(value: unknown): string[] | null {
+export function stringArray(value: unknown): string[] | null {
 	return Array.isArray(value) && value.every(item => typeof item === "string") ? value.map(item => item.trim()) : null;
 }
 
@@ -726,7 +745,7 @@ function pipelineMetadataHashBasis(metadata: Omit<UltragoalPipelineMetadata, "me
 	};
 }
 
-function hashPipelineMetadata(metadata: Omit<UltragoalPipelineMetadata, "metadataHash">): string {
+export function hashPipelineMetadata(metadata: Omit<UltragoalPipelineMetadata, "metadataHash">): string {
 	return hashStructuredValue(pipelineMetadataHashBasis(metadata));
 }
 
@@ -842,7 +861,7 @@ function pipelineMetadataConflictsWithValidationBatch(metadata: UltragoalPipelin
 	return metadata?.eligible === true || metadata?.source === "original_plan_graph" || metadata?.source === "steering";
 }
 
-function validateValidationBatchPipelineExclusion(goal: UltragoalGoal): void {
+export function validateValidationBatchPipelineExclusion(goal: UltragoalGoal): void {
 	if (goal.validationBatch && pipelineMetadataConflictsWithValidationBatch(goal.pipelineMetadata)) {
 		throw new Error(`Goal ${goal.id} cannot combine validationBatch with eligible pipeline metadata`);
 	}
@@ -1035,28 +1054,28 @@ function normalizePipelineMetadataRecord(value: unknown, goalIds: ReadonlySet<st
 	return withPipelineMetadataHash(basis);
 }
 
-function targetsAreDisjoint(left: UltragoalPipelineTargets, right: UltragoalPipelineTargets): boolean {
+export function targetsAreDisjoint(left: UltragoalPipelineTargets, right: UltragoalPipelineTargets): boolean {
 	return (
 		left.files.every(file => !right.files.includes(file)) &&
 		left.surfaces.every(surface => !right.surfaces.includes(surface))
 	);
 }
 
-function targetsOverlap(left: UltragoalPipelineTargets, right: UltragoalPipelineTargets): boolean {
+export function targetsOverlap(left: UltragoalPipelineTargets, right: UltragoalPipelineTargets): boolean {
 	return (
 		left.files.some(file => right.files.includes(file)) ||
 		left.surfaces.some(surface => right.surfaces.includes(surface))
 	);
 }
 
-function requireNonEmptyPipelineTargets(value: unknown, fieldName: string): UltragoalPipelineTargets {
+export function requireNonEmptyPipelineTargets(value: unknown, fieldName: string): UltragoalPipelineTargets {
 	const targets = normalizePipelineTargets(value, fieldName);
 	if (targets.files.length === 0 && targets.surfaces.length === 0)
 		throw new Error(`${fieldName} requires files or surfaces`);
 	return targets;
 }
 
-function collectPipelineBlockerFootprints(result: JsonObject, fieldName: string): UltragoalPipelineTargets[] {
+export function collectPipelineBlockerFootprints(result: JsonObject, fieldName: string): UltragoalPipelineTargets[] {
 	const raw = Array.isArray(result.blockers)
 		? result.blockers
 		: Array.isArray(result.blockerFootprints)
@@ -1074,12 +1093,12 @@ function pipelineTargetsCoverPath(targets: UltragoalPipelineTargets, filePath: s
 	return targets.files.some(target => normalized === target || normalized.startsWith(`${target}/`));
 }
 
-function pipelinePeer(plan: UltragoalPlan, metadata: UltragoalPipelineMetadata): UltragoalGoal | undefined {
+export function pipelinePeer(plan: UltragoalPlan, metadata: UltragoalPipelineMetadata): UltragoalGoal | undefined {
 	const peerId = metadata.goalId === metadata.priorGoalId ? metadata.nextGoalId : metadata.priorGoalId;
 	return peerId ? plan.goals.find(goal => goal.id === peerId) : undefined;
 }
 
-function handleIdsFromValue(value: JsonObject | JsonObject[], fieldName: string): string[] {
+export function handleIdsFromValue(value: JsonObject | JsonObject[], fieldName: string): string[] {
 	const records = Array.isArray(value) ? value : [value];
 	const ids = records.map(
 		(record, index) =>
@@ -1092,13 +1111,13 @@ function handleIdsFromValue(value: JsonObject | JsonObject[], fieldName: string)
 	return ids;
 }
 
-function resultHandleIds(value: JsonObject, fieldName: string): string[] {
+export function resultHandleIds(value: JsonObject, fieldName: string): string[] {
 	const ids = stringArray(value.handleIds) ?? stringArray(value.handles) ?? [];
 	if (ids.length === 0) throw new Error(`${fieldName} requires handleIds`);
 	return ids;
 }
 
-function requireCoveredHandles(expected: readonly string[], actual: readonly string[], fieldName: string): void {
+export function requireCoveredHandles(expected: readonly string[], actual: readonly string[], fieldName: string): void {
 	const missing = expected.filter(id => !actual.includes(id));
 	if (missing.length > 0) throw new Error(`${fieldName} is missing handle coverage for ${missing.join(", ")}`);
 }
@@ -1186,7 +1205,7 @@ function currentPipelineHash(metadata: UltragoalPipelineMetadata): string {
 	return hashPipelineMetadata(metadata);
 }
 
-function requireFreshPipelineMetadata(goal: UltragoalGoal): UltragoalPipelineMetadata {
+export function requireFreshPipelineMetadata(goal: UltragoalGoal): UltragoalPipelineMetadata {
 	const metadata = goal.pipelineMetadata;
 	if (!metadata) throw new Error(`Goal ${goal.id} has no pipeline metadata`);
 	if (metadata.metadataHash !== currentPipelineHash(metadata))
@@ -1194,7 +1213,7 @@ function requireFreshPipelineMetadata(goal: UltragoalGoal): UltragoalPipelineMet
 	return metadata;
 }
 
-function openPipelineOverlap(
+export function openPipelineOverlap(
 	plan: UltragoalPlan,
 ): { prior: UltragoalGoal; next: UltragoalGoal; overlapId: string } | null {
 	const openGoals = plan.goals.filter(goal => goal.pipelineMetadata?.overlap === "open");
@@ -1533,14 +1552,14 @@ export interface UltragoalRunCompletionState {
 	hasBlockers: boolean;
 	needsFinalAggregateReceipt: boolean;
 }
-function requireJsonObjectValue(value: unknown, fieldName: string): JsonObject {
+export function requireJsonObjectValue(value: unknown, fieldName: string): JsonObject {
 	if (typeof value !== "object" || value === null || Array.isArray(value))
 		throw new Error(`${fieldName} must be an object`);
 	if (Object.keys(value).length === 0) throw new Error(`${fieldName} must be non-empty`);
 	return value as JsonObject;
 }
 
-function requireJsonObjectOrArrayValue(value: unknown, fieldName: string): JsonObject | JsonObject[] {
+export function requireJsonObjectOrArrayValue(value: unknown, fieldName: string): JsonObject | JsonObject[] {
 	if (Array.isArray(value)) {
 		if (value.length === 0) throw new Error(`${fieldName} must be non-empty`);
 		return value.map((item, index) => requireJsonObjectValue(item, `${fieldName}[${index}]`));
@@ -1560,278 +1579,13 @@ async function readRequiredJsonObjectOrArray(
 	return requireJsonObjectOrArrayValue(await readStructuredValue(cwd, value), fieldName);
 }
 
-function requirePipelineStartable(plan: UltragoalPlan, prior: UltragoalGoal, next: UltragoalGoal): void {
-	if (plan.gjcGoalMode !== "aggregate")
-		throw new Error("pipeline overlap is supported only for aggregate ultragoal mode");
-	if (openPipelineOverlap(plan))
-		throw new Error("Cannot start pipeline overlap because another overlap is already open");
-	if (prior.status !== "active")
-		throw new Error(`Prior goal ${prior.id} must be active before pipeline overlap starts`);
-	if (next.status !== "pending" && next.status !== "failed")
-		throw new Error(`Next goal ${next.id} must be pending or retryable failed`);
-	validateValidationBatchPipelineExclusion(prior);
-	validateValidationBatchPipelineExclusion(next);
-	if (prior.validationBatch || next.validationBatch)
-		throw new Error("pipeline overlap cannot start for validation batch goals");
-	const priorMetadata = requireFreshPipelineMetadata(prior);
-	const nextMetadata = requireFreshPipelineMetadata(next);
-	if (!priorMetadata.eligible || !nextMetadata.eligible)
-		throw new Error("pipeline overlap requires eligible original-plan metadata on both goals");
-	if (!priorMetadata.independentOf.includes(next.id) || !nextMetadata.independentOf.includes(prior.id)) {
-		throw new Error("pipeline overlap requires symmetric original independence");
-	}
-	if (!targetsAreDisjoint(priorMetadata.targets, nextMetadata.targets))
-		throw new Error("pipeline overlap requires disjoint files and surfaces");
-}
-
-function pipelineEventRefs(prior: UltragoalGoal, next: UltragoalGoal): JsonObject {
-	return {
-		priorMetadataHash: prior.pipelineMetadata?.metadataHash,
-		nextMetadataHash: next.pipelineMetadata?.metadataHash,
-		priorTargets: prior.pipelineMetadata?.targets,
-		nextTargets: next.pipelineMetadata?.targets,
-	};
-}
-
-function pipelineReceipt(
-	cwd: string,
-	event: string,
-	overlapId: string,
-	prior: UltragoalGoal,
-	next: UltragoalGoal,
-): UltragoalPipelineOverlapReceipt {
-	const paths = getUltragoalPaths(cwd, currentUltragoalSessionId(cwd));
-	return {
-		ok: true,
-		event,
-		overlap_id: overlapId,
-		prior_goal_id: prior.id,
-		next_goal_id: next.id,
-		status: next.pipelineMetadata?.overlap,
-		next_goal_status: next.status,
-		goals_path: paths.goalsPath,
-		ledger_path: paths.ledgerPath,
-	};
-}
-
-export async function startUltragoalPipelineOverlap(input: {
-	cwd: string;
-	priorGoalId: string;
-	nextGoalId: string;
-	reviewHandles: JsonObject | JsonObject[];
-	qaHandles: JsonObject | JsonObject[];
-	implementationHandle: JsonObject;
-}): Promise<UltragoalPipelineOverlapReceipt> {
-	const plan = await readUltragoalPlan(input.cwd);
-	if (!plan) throw new Error("No ultragoal plan found. Run `gjc ultragoal create-goals --brief ...` first.");
-	const prior = plan.goals.find(goal => goal.id === input.priorGoalId);
-	const next = plan.goals.find(goal => goal.id === input.nextGoalId);
-	if (!prior || !next) throw new Error("start-pipeline-overlap requires existing prior and next goal ids");
-	const reviewHandles = requireJsonObjectOrArrayValue(input.reviewHandles, "review handles");
-	const qaHandles = requireJsonObjectOrArrayValue(input.qaHandles, "QA handles");
-	requireJsonObjectValue(input.implementationHandle, "implementation handle");
-	requirePipelineStartable(plan, prior, next);
-	const now = new Date().toISOString();
-	const overlapId = `pipeline-${crypto.randomUUID()}`;
-	const priorMetadata = requireFreshPipelineMetadata(prior);
-	const nextMetadata = requireFreshPipelineMetadata(next);
-	const priorOpenMetadata = {
-		...priorMetadata,
-		overlap: "open" as const,
-		overlapId,
-		priorGoalId: prior.id,
-		nextGoalId: next.id,
-	};
-	const nextOpenMetadata = {
-		...nextMetadata,
-		overlap: "open" as const,
-		overlapId,
-		priorGoalId: prior.id,
-		nextGoalId: next.id,
-	};
-	prior.pipelineMetadata = { ...priorOpenMetadata, metadataHash: hashPipelineMetadata(priorOpenMetadata) };
-	next.pipelineMetadata = { ...nextOpenMetadata, metadataHash: hashPipelineMetadata(nextOpenMetadata) };
-	prior.updatedAt = now;
-	next.updatedAt = now;
-	next.status = "active";
-	next.startedAt = next.startedAt ?? now;
-	plan.updatedAt = now;
-	await writePlan(input.cwd, plan);
-	const refs = pipelineEventRefs(prior, next);
-	const expectedReviewHandleIds = handleIdsFromValue(reviewHandles, "review");
-	const expectedQaHandleIds = handleIdsFromValue(qaHandles, "QA");
-	await appendLedger(input.cwd, {
-		event: "pipeline_overlap_started",
-		eventId: crypto.randomUUID(),
-		timestamp: now,
-		schemaVersion: 1,
-		overlapId,
-		priorGoalId: prior.id,
-		nextGoalId: next.id,
-		reviewHandles,
-		reviewHandleIds: expectedReviewHandleIds,
-		qaHandles,
-		qaHandleIds: expectedQaHandleIds,
-		implementationHandle: input.implementationHandle,
-		...refs,
-	});
-	await appendLedger(input.cwd, { event: "goal_started", goalId: next.id, pipelineOverlapId: overlapId });
-	return pipelineReceipt(input.cwd, "pipeline_overlap_started", overlapId, prior, next);
-}
-
-function resultStatus(value: JsonObject, fieldName: string): string {
-	const status = nonEmptyString(value.status) ?? nonEmptyString(value.verdict) ?? nonEmptyString(value.result);
-	if (!status) throw new Error(`${fieldName} requires status, verdict, or result`);
-	return status.toLowerCase();
-}
-
-function requireCleanPipelineResult(result: JsonObject, expectedHandleIds: readonly string[], fieldName: string): void {
-	const status = resultStatus(result, fieldName);
-	if (!["passed", "pass", "approved", "clear"].includes(status)) throw new Error(`${fieldName} did not pass`);
-	const evidence = nonEmptyString(result.evidence);
-	if (!evidence || !isSubstantiveEvidence(evidence)) throw new Error(`${fieldName} requires substantive evidence`);
-	requireCoveredHandles(expectedHandleIds, resultHandleIds(result, fieldName), fieldName);
-	if (collectPipelineBlockerFootprints(result, fieldName).length > 0)
-		throw new Error(`${fieldName} cannot clean-join with blockers`);
-}
-
-function pipelineStartEventHandleIds(
-	ledger: UltragoalLedgerEvent[],
-	overlapId: string,
-): { review: string[]; qa: string[] } {
-	const event = ledger.find(row => row.event === "pipeline_overlap_started" && row.overlapId === overlapId) as
-		| JsonObject
-		| undefined;
-	if (!event) throw new Error(`No pipeline_overlap_started event found for ${overlapId}`);
-	const review =
-		stringArray(event.reviewHandleIds) ??
-		handleIdsFromValue(requireJsonObjectOrArrayValue(event.reviewHandles, "review handles"), "review");
-	const qa =
-		stringArray(event.qaHandleIds) ??
-		handleIdsFromValue(requireJsonObjectOrArrayValue(event.qaHandles, "QA handles"), "QA");
-	return { review, qa };
-}
-
-export async function joinUltragoalPipelineOverlap(input: {
-	cwd: string;
-	overlapId: string;
-	reviewResult: JsonObject;
-	qaResult: JsonObject;
-}): Promise<UltragoalPipelineOverlapReceipt> {
-	const plan = await readUltragoalPlan(input.cwd);
-	if (!plan) throw new Error("No ultragoal plan found. Run `gjc ultragoal create-goals --brief ...` first.");
-	const overlap = openPipelineOverlap(plan);
-	if (!overlap || overlap.overlapId !== input.overlapId)
-		throw new Error(`No open pipeline overlap found for ${input.overlapId}`);
-	const { prior, next, overlapId } = overlap;
-	const nextMetadata = requireFreshPipelineMetadata(next);
-	const ledger = await readUltragoalLedger(input.cwd);
-	const expectedHandles = pipelineStartEventHandleIds(ledger, overlapId);
-	const reviewBlockers = collectPipelineBlockerFootprints(input.reviewResult, "review result");
-	const qaBlockers = collectPipelineBlockerFootprints(input.qaResult, "QA result");
-	const blockerFootprints = [...reviewBlockers, ...qaBlockers];
-	let state: UltragoalPipelineOverlapState;
-	let event: UltragoalPipelineLedgerEventName;
-	if (blockerFootprints.length === 0) {
-		try {
-			requireCleanPipelineResult(input.reviewResult, expectedHandles.review, "review result");
-			requireCleanPipelineResult(input.qaResult, expectedHandles.qa, "QA result");
-			state = "joined_clean";
-			event = "pipeline_overlap_joined";
-		} catch {
-			state = "quarantine_required";
-			event = "pipeline_overlap_quarantined";
-		}
-	} else if (blockerFootprints.every(footprint => !targetsOverlap(footprint, nextMetadata.targets))) {
-		state = "blocked_disjoint_continue";
-		event = "pipeline_overlap_joined";
-	} else {
-		state = "quarantine_required";
-		event = "pipeline_overlap_quarantined";
-	}
-	const now = new Date().toISOString();
-	for (const goal of [prior, next]) {
-		const metadata = requireFreshPipelineMetadata(goal);
-		const joinedMetadata = { ...metadata, overlap: state, blockerFootprints };
-		goal.pipelineMetadata = { ...joinedMetadata, metadataHash: hashPipelineMetadata(joinedMetadata) };
-		goal.updatedAt = now;
-	}
-	if (state === "quarantine_required") next.status = "blocked";
-	plan.updatedAt = now;
-	await writePlan(input.cwd, plan);
-	await appendLedger(input.cwd, {
-		event,
-		eventId: crypto.randomUUID(),
-		timestamp: now,
-		schemaVersion: 1,
-		overlapId,
-		priorGoalId: prior.id,
-		nextGoalId: next.id,
-		status: state,
-		reviewResult: input.reviewResult,
-		qaResult: input.qaResult,
-		blockerFootprints,
-		...pipelineEventRefs(prior, next),
-	});
-	return pipelineReceipt(input.cwd, event, overlapId, prior, next);
-}
+import {
+	joinUltragoalPipelineOverlap,
+	rebaselineUltragoalPipelineOverlap,
+	startUltragoalPipelineOverlap,
+} from "./ultragoal-pipeline";
 
-export async function rebaselineUltragoalPipelineOverlap(input: {
-	cwd: string;
-	overlapId: string;
-	goalId: string;
-	evidence: string;
-	targetState: JsonObject;
-}): Promise<UltragoalPipelineOverlapReceipt> {
-	const plan = await readUltragoalPlan(input.cwd);
-	if (!plan) throw new Error("No ultragoal plan found. Run `gjc ultragoal create-goals --brief ...` first.");
-	const goal = plan.goals.find(item => item.id === input.goalId);
-	if (!goal) throw new Error(`No ultragoal goal found for ${input.goalId}.`);
-	const evidence = input.evidence.trim();
-	if (!isSubstantiveEvidence(evidence)) throw new Error("rebaseline-pipeline-overlap requires substantive evidence");
-	const targetState = requireNonEmptyPipelineTargets(input.targetState, "target state");
-	const metadata = requireFreshPipelineMetadata(goal);
-	if (metadata.overlap !== "quarantine_required" || metadata.overlapId !== input.overlapId) {
-		throw new Error(`Goal ${goal.id} is not quarantined for overlap ${input.overlapId}`);
-	}
-	for (const footprint of metadata.blockerFootprints ?? []) {
-		if (targetsOverlap(footprint, targetState))
-			throw new Error("rebaseline-pipeline-overlap target state overlaps unresolved blocker footprints");
-	}
-	const now = new Date().toISOString();
-	const rebaselinedMetadata = { ...metadata, overlap: "rebaseline_complete" as const, targets: targetState };
-	goal.pipelineMetadata = { ...rebaselinedMetadata, metadataHash: hashPipelineMetadata(rebaselinedMetadata) };
-	goal.status = "active";
-	goal.evidence = evidence;
-	goal.updatedAt = now;
-	plan.updatedAt = now;
-	await writePlan(input.cwd, plan);
-	const peer = pipelinePeer(plan, metadata);
-	await appendLedger(input.cwd, {
-		event: "pipeline_overlap_rebaselined",
-		eventId: crypto.randomUUID(),
-		timestamp: now,
-		schemaVersion: 1,
-		overlapId: input.overlapId,
-		priorGoalId: metadata.priorGoalId ?? peer?.id ?? "",
-		nextGoalId: metadata.nextGoalId ?? goal.id,
-		goalId: goal.id,
-		evidence,
-		targetState,
-		metadataHash: goal.pipelineMetadata.metadataHash,
-	});
-	const paths = getUltragoalPaths(input.cwd, currentUltragoalSessionId(input.cwd));
-	return {
-		ok: true,
-		event: "pipeline_overlap_rebaselined",
-		overlap_id: input.overlapId,
-		prior_goal_id: metadata.priorGoalId ?? peer?.id ?? "",
-		goal_id: goal.id,
-		status: goal.pipelineMetadata.overlap,
-		goals_path: paths.goalsPath,
-		ledger_path: paths.ledgerPath,
-	};
-}
+export { joinUltragoalPipelineOverlap, rebaselineUltragoalPipelineOverlap, startUltragoalPipelineOverlap };
 
 export function getUltragoalRunCompletionState(
 	plan: UltragoalPlan,
@@ -1886,11 +1640,11 @@ async function readStructuredValue(cwd: string, value: string): Promise<unknown>
 		throw error;
 	}
 }
-function qualityGateObject(value: unknown): JsonObject | null {
+export function qualityGateObject(value: unknown): JsonObject | null {
 	return typeof value === "object" && value !== null && !Array.isArray(value) ? (value as JsonObject) : null;
 }
 
-function nonEmptyStringArray(value: unknown): string[] | null {
+export function nonEmptyStringArray(value: unknown): string[] | null {
 	if (!Array.isArray(value)) return null;
 	const strings = value.filter(item => typeof item === "string" && item.trim().length > 0);
 	return strings.length === value.length && strings.length > 0 ? strings : null;
@@ -1907,20 +1661,20 @@ function requireEmptyBlockers(value: unknown, fieldName: string): void {
 		throw new Error(`qualityGate ${fieldName} must be an empty blockers array`);
 	}
 }
-function requireQualityGateObject(value: unknown, fieldName: string): JsonObject {
+export function requireQualityGateObject(value: unknown, fieldName: string): JsonObject {
 	const object = qualityGateObject(value);
 	if (!object) throw new Error(`qualityGate ${fieldName} must be an object`);
 	return object;
 }
 
-function requireObjectArray(value: unknown, fieldName: string): JsonObject[] {
+export function requireObjectArray(value: unknown, fieldName: string): JsonObject[] {
 	if (!Array.isArray(value) || value.length === 0) {
 		throw new Error(`qualityGate ${fieldName} must be a non-empty object array`);
 	}
 	return value.map((item, index) => requireQualityGateObject(item, `${fieldName}[${index}]`));
 }
 
-function requiredStringField(row: JsonObject, key: string, fieldName: string): string {
+export function requiredStringField(row: JsonObject, key: string, fieldName: string): string {
 	const value = row[key];
 	if (typeof value !== "string" || value.trim().length === 0) {
 		const hint =
@@ -1969,7 +1723,7 @@ function requireSuccessfulRowOutcome(row: JsonObject, fieldName: string): void {
 	}
 }
 
-function requireStringLinks(value: unknown, fieldName: string): string[] {
+export function requireStringLinks(value: unknown, fieldName: string): string[] {
 	const strings = nonEmptyStringArray(value);
 	if (!strings) throw new Error(`qualityGate ${fieldName} must be a non-empty string array`);
 	return strings.map(item => item.trim());
@@ -1990,7 +1744,7 @@ function buildRowIdMap(rows: JsonObject[], fieldName: string): Map<string, JsonO
 	return ids;
 }
 
-function requireResolvedLinks(ids: string[], map: Map<string, JsonObject>, fieldName: string): void {
+export function requireResolvedLinks(ids: string[], map: Map<string, JsonObject>, fieldName: string): void {
 	for (const id of ids) {
 		if (!map.has(id)) throw new Error(`qualityGate ${fieldName} references unknown id ${id}`);
 	}
@@ -2006,11 +1760,11 @@ function successfulLinkedRows(ids: string[], map: Map<string, JsonObject>, field
 	return rows;
 }
 
-function normalizedEvidenceKind(row: JsonObject): string {
+export function normalizedEvidenceKind(row: JsonObject): string {
 	return requiredStringField(row, "kind", "executorQa.artifactRefs[]").toLowerCase().replaceAll("_", "-");
 }
 
-function evidenceKindMatches(kind: string, words: string[]): boolean {
+export function evidenceKindMatches(kind: string, words: string[]): boolean {
 	return words.some(word => kind.includes(word));
 }
 function formatActualArtifactKinds(artifactIds: string[], kinds: string[]): string {
@@ -2022,10 +1776,10 @@ function formatExpectedKindWords(words: string[]): string {
 	return words.map(word => `"${word}"`).join(", ");
 }
 
-type SurfaceFamily = "web" | "cli" | "native" | "api-package" | "algorithm-math" | "unknown";
+export type SurfaceFamily = "web" | "cli" | "native" | "api-package" | "algorithm-math" | "unknown";
 
-type UltragoalChangeStatus = "added" | "modified" | "deleted" | "renamed" | "copied" | "unknown";
-type UltragoalChangeCategory =
+export type UltragoalChangeStatus = "added" | "modified" | "deleted" | "renamed" | "copied" | "unknown";
+export type UltragoalChangeCategory =
 	| "code"
 	| "generated-binding"
 	| "tool"
@@ -2033,13 +1787,13 @@ type UltragoalChangeCategory =
 	| "prompt-doc-behavior"
 	| "docs-static"
 	| "other";
-interface UltragoalChangeSetPath extends JsonObject {
+export interface UltragoalChangeSetPath extends JsonObject {
 	path: string;
 	status: UltragoalChangeStatus;
 	oldPath?: string;
 	category?: UltragoalChangeCategory;
 }
-interface UltragoalChangeSet extends JsonObject {
+export interface UltragoalChangeSet extends JsonObject {
 	source: "checkpoint-git" | "review-pr" | "review-branch" | "review-worktree" | "review-spec";
 	baseRef?: string;
 	headRef?: string;
@@ -2061,7 +1815,7 @@ const MANDATORY_COMPUTER_CASE_IDS = [
 ] as const;
 const TOOLS_INDEX_PATH = "packages/coding-agent/src/tools/index.ts";
 
-function normalizeRepoPath(value: string): string {
+export function normalizeRepoPath(value: string): string {
 	return value.replaceAll("\\\\", "/").replace(/^\.\//, "");
 }
 
@@ -2069,7 +1823,7 @@ function isToolsIndexPath(value: string): boolean {
 	return normalizeRepoPath(value) === TOOLS_INDEX_PATH;
 }
 
-function categorizeComputerChangePath(value: string): UltragoalChangeCategory {
+export function categorizeComputerChangePath(value: string): UltragoalChangeCategory {
 	const normalized = normalizeRepoPath(value);
 	if (normalized.startsWith("crates/pi-natives/src/computer/")) return "code";
 	if (/^packages\/natives\/native\/index\.(?:d\.ts|js)$/.test(normalized)) return "generated-binding";
@@ -2137,7 +1891,7 @@ function isComputerSpecificToolsIndexDiff(diff: string | undefined, targetPath:
 /** Settings registry file that holds ALL settings, most of them unrelated to computer control. */
 const SETTINGS_SCHEMA_PATH = "packages/coding-agent/src/config/settings-schema.ts";
 
-function isSettingsSchemaPath(value: string): boolean {
+export function isSettingsSchemaPath(value: string): boolean {
 	return normalizeRepoPath(value) === SETTINGS_SCHEMA_PATH;
 }
 
@@ -2229,7 +1983,7 @@ export function surfaceFamily(value: string): SurfaceFamily {
 	return "unknown";
 }
 
-function isLiveSurfaceFamily(family: SurfaceFamily): boolean {
+export function isLiveSurfaceFamily(family: SurfaceFamily): boolean {
 	return family === "web" || family === "cli" || family === "native";
 }
 
@@ -2281,7 +2035,7 @@ function validateSurfaceArtifactCompatibility(
 	}
 }
 
-function isSubstantiveEvidence(value: unknown): boolean {
+export function isSubstantiveEvidence(value: unknown): boolean {
 	if (typeof value !== "string") return false;
 	const trimmed = value.trim();
 	if (trimmed.length < MIN_SUBSTANTIVE_EVIDENCE_CHARS) return false;
@@ -2291,7 +2045,7 @@ function isSubstantiveEvidence(value: unknown): boolean {
 	return !["todo", "tbd", "n/a", "na", "none", "placeholder", "empty", "stub"].includes(normalized);
 }
 
-function hasTypedVerifiedReceipt(value: unknown): boolean {
+export function hasTypedVerifiedReceipt(value: unknown): boolean {
 	const receipt = qualityGateObject(value);
 	if (!receipt) return false;
 	const type = nonEmptyString(receipt.type) ?? nonEmptyString(receipt.kind) ?? nonEmptyString(receipt.receiptType);
@@ -2300,7 +2054,7 @@ function hasTypedVerifiedReceipt(value: unknown): boolean {
 	return Boolean(type && id && (status === "verified" || status === "passed"));
 }
 
-async function hasExistingNonEmptyArtifact(cwd: string, value: unknown): Promise<boolean> {
+export async function hasExistingNonEmptyArtifact(cwd: string, value: unknown): Promise<boolean> {
 	const artifactPath = nonEmptyString(value);
 	if (!artifactPath) return false;
 	const resolved = path.resolve(cwd, artifactPath);
@@ -2313,7 +2067,7 @@ async function hasExistingNonEmptyArtifact(cwd: string, value: unknown): Promise
 	}
 }
 
-async function readArtifactBytes(cwd: string, row: JsonObject, fieldName: string): Promise<Buffer | null> {
+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);
@@ -2327,839 +2081,27 @@ async function readArtifactBytes(cwd: string, row: JsonObject, fieldName: string
 	}
 }
 
-const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
-const JPEG_START_OF_IMAGE = 0xd8;
-const JPEG_END_OF_IMAGE = 0xd9;
-const JPEG_START_OF_SCAN = 0xda;
-const JPEG_STANDALONE_MARKERS = new Set([0x01, 0xd0, 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7]);
-const PNG_CRC_TABLE = new Uint32Array(256).map((_, index) => {
-	let crc = index;
-	for (let bit = 0; bit < 8; bit++) crc = crc & 1 ? 0xedb88320 ^ (crc >>> 1) : crc >>> 1;
-	return crc >>> 0;
-});
-
-function pngCrc32(bytes: Buffer): number {
-	let crc = 0xffffffff;
-	for (const byte of bytes) crc = PNG_CRC_TABLE[(crc ^ byte) & 0xff]! ^ (crc >>> 8);
-	return (crc ^ 0xffffffff) >>> 0;
-}
-
-function parsePngDimensions(
-	bytes: Buffer,
-): { width: number; height: number; headerBytes: number; sampleBytes?: Buffer } | null {
-	if (bytes.length < 45) return null;
-	if (!bytes.subarray(0, 8).equals(PNG_SIGNATURE)) return null;
-	let offset = 8;
-	let width = 0;
-	let height = 0;
-	let sawIhdr = false;
-	let sawIdat = false;
-	const idatChunks: Buffer[] = [];
-	while (offset + 12 <= bytes.length) {
-		const chunkStart = offset;
-		const length = bytes.readUInt32BE(offset);
-		offset += 4;
-		const type = bytes.toString("ascii", offset, offset + 4);
-		offset += 4;
-		if (offset + length + 4 > bytes.length) return null;
-		const data = bytes.subarray(offset, offset + length);
-		offset += length;
-		const expectedCrc = bytes.readUInt32BE(offset);
-		offset += 4;
-		if (pngCrc32(bytes.subarray(chunkStart + 4, offset - 4)) !== expectedCrc) return null;
-		if (!sawIhdr) {
-			if (type !== "IHDR" || length !== 13) return null;
-			width = data.readUInt32BE(0);
-			height = data.readUInt32BE(4);
-			if (
-				width === 0 ||
-				height === 0 ||
-				data[8] !== 8 ||
-				![2, 6].includes(data[9]!) ||
-				data[10] !== 0 ||
-				data[11] !== 0 ||
-				data[12] !== 0
-			)
-				return null;
-			sawIhdr = true;
-		} else if (type === "IHDR") return null;
-		if (type === "IDAT") {
-			if (!sawIhdr || length === 0) return null;
-			sawIdat = true;
-			idatChunks.push(data);
-		}
-		if (type === "IEND") {
-			if (length !== 0 || !sawIhdr || !sawIdat || offset !== bytes.length) return null;
-			try {
-				return { width, height, headerBytes: 8, sampleBytes: inflateSync(Buffer.concat(idatChunks)) };
-			} catch {
-				return null;
-			}
-		}
-	}
-	return null;
-}
-
-function parseJpegDimensions(
-	bytes: Buffer,
-): { width: number; height: number; headerBytes: number; sampleBytes?: Buffer } | null {
-	if (bytes.length < 8 || bytes[0] !== 0xff || bytes[1] !== JPEG_START_OF_IMAGE) return null;
-	let offset = 2;
-	let dimensions: { width: number; height: number; headerBytes: number } | null = null;
-	let sawStartOfScan = false;
-	let scanStart = -1;
-	while (offset < bytes.length) {
-		if (bytes[offset] !== 0xff) return null;
-		while (offset < bytes.length && bytes[offset] === 0xff) offset++;
-		if (offset >= bytes.length) return null;
-		const marker = bytes[offset++];
-		if (marker === 0x00) return null;
-		if (marker === JPEG_END_OF_IMAGE) return null;
-		if (JPEG_STANDALONE_MARKERS.has(marker)) continue;
-		if (offset + 2 > bytes.length) return null;
-		const segmentLength = bytes.readUInt16BE(offset);
-		if (segmentLength < 2 || offset + segmentLength > bytes.length) return null;
-		const segmentDataEnd = offset + segmentLength;
-		if (marker === 0xc0 || marker === 0xc1 || marker === 0xc2) {
-			if (segmentLength < 8) return null;
-			dimensions = {
-				width: bytes.readUInt16BE(offset + 5),
-				height: bytes.readUInt16BE(offset + 3),
-				headerBytes: offset + segmentLength,
-			};
-		}
-		if (marker === JPEG_START_OF_SCAN) {
-			if (!dimensions || segmentDataEnd >= bytes.length) return null;
-			sawStartOfScan = true;
-			scanStart = segmentDataEnd;
-			break;
-		}
-		offset += segmentLength;
-	}
-	if (!dimensions || !sawStartOfScan || scanStart < 0) return null;
-	let scanOffset = scanStart;
-	let entropyBytes = 0;
-	while (scanOffset < bytes.length) {
-		const byte = bytes[scanOffset++]!;
-		if (byte !== 0xff) {
-			entropyBytes++;
-			continue;
-		}
-		if (scanOffset >= bytes.length) return null;
-		const marker = bytes[scanOffset++]!;
-		if (marker === 0x00) {
-			entropyBytes++;
-			continue;
-		}
-		if (JPEG_STANDALONE_MARKERS.has(marker)) continue;
-		if (marker === JPEG_END_OF_IMAGE) {
-			if (scanOffset !== bytes.length || entropyBytes < 32) return null;
-			return { ...dimensions, sampleBytes: bytes.subarray(scanStart, scanOffset - 2) };
-		}
-		return null;
-	}
-	return null;
-}
-
-function unsupportedScreenshotFormat(bytes: Buffer): string | null {
-	if (bytes.toString("ascii", 0, 6) === "GIF87a" || bytes.toString("ascii", 0, 6) === "GIF89a") return "GIF";
-	if (bytes.toString("ascii", 0, 2) === "BM") return "BMP";
-	if (bytes.length >= 12 && bytes.toString("ascii", 0, 4) === "RIFF" && bytes.toString("ascii", 8, 12) === "WEBP")
-		return "WebP";
-	return null;
-}
-
-function parseImageDimensions(
-	bytes: Buffer,
-): { width: number; height: number; headerBytes: number; sampleBytes?: Buffer } | null {
-	return parsePngDimensions(bytes) ?? parseJpegDimensions(bytes);
-}
-
-function hasNonUniformImageBytes(bytes: Buffer, headerBytes: number, sampleBytes?: Buffer): boolean {
-	const source = sampleBytes ?? bytes;
-	const sampleStart = sampleBytes ? 0 : Math.min(Math.max(headerBytes, 0), source.length);
-	const sampleLength = source.length - sampleStart;
-	if (sampleLength < 32) return false;
-	const windows: Buffer[] = [];
-	for (let index = 0; index < 64; index++) {
-		const offset = sampleStart + Math.floor(((sampleLength - 32) * index) / 63);
-		windows.push(source.subarray(offset, offset + 32));
-	}
-	const byteCounts = new Map<number, number>();
-	let total = 0;
-	for (const window of windows) {
-		for (const byte of window) {
-			byteCounts.set(byte, (byteCounts.get(byte) ?? 0) + 1);
-			total++;
-		}
-	}
-	const first = windows[0]!;
-	const differingWindows = windows.slice(1).filter(window => !window.equals(first)).length;
-	const maxCount = Math.max(...byteCounts.values());
-	return byteCounts.size >= 16 && differingWindows >= 8 && maxCount / total <= 0.95;
-}
-
-async function validateScreenshotArtifact(cwd: string, row: JsonObject, fieldName: string): Promise<boolean> {
-	const bytes = await readArtifactBytes(cwd, row, fieldName);
-	if (!bytes) throw new Error(`qualityGate ${fieldName} screenshot artifact path must resolve to an existing file`);
-	if (bytes.length < 4096) throw new Error(`qualityGate ${fieldName} screenshot artifact must be at least 4096 bytes`);
-	const unsupportedFormat = unsupportedScreenshotFormat(bytes);
-	if (unsupportedFormat) {
-		throw new Error(
-			`qualityGate ${fieldName} unsupported/undecodable screenshot format ${unsupportedFormat}; use PNG or fully marker-validated JPEG`,
-		);
-	}
-	const dimensions = parseImageDimensions(bytes);
-	if (!dimensions)
-		throw new Error(`qualityGate ${fieldName} screenshot artifact must be a decodable PNG or JPEG image`);
-	if (dimensions.width < 320 || dimensions.height < 180) {
-		throw new Error(`qualityGate ${fieldName} screenshot artifact must be at least 320x180 pixels`);
-	}
-	if (!hasNonUniformImageBytes(bytes, dimensions.headerBytes, dimensions.sampleBytes)) {
-		throw new Error(
-			`qualityGate ${fieldName} screenshot artifact must be non-uniform, not blank, solid, tiny, or placeholder imagery`,
-		);
-	}
-	return true;
-}
-
-function normalizeTranscriptTimestamp(value: unknown): number | null {
-	if (typeof value === "number" && Number.isFinite(value)) return value;
-	if (typeof value !== "string" || value.trim().length === 0) return null;
-	const numeric = Number(value);
-	if (Number.isFinite(numeric)) return numeric;
-	const parsed = Date.parse(value);
-	return Number.isFinite(parsed) ? parsed : null;
-}
-
-function transcriptSurfaceCompatible(value: unknown, family: SurfaceFamily): boolean {
-	const surface = nonEmptyString(value);
-	return !surface || family === "unknown" || surfaceFamily(surface) === family;
-}
-
-function actionSelectorRequired(type: string): boolean {
-	return ["click", "fill", "press", "assert", "screenshot", "observe"].includes(type);
-}
-
-async function validateAutomationTranscriptArtifact(
-	cwd: string,
-	row: JsonObject,
-	fieldName: string,
-	options: { surfaceFamily: SurfaceFamily },
-): Promise<boolean> {
-	const bytes = await readArtifactBytes(cwd, row, fieldName);
-	if (!bytes) throw new Error(`qualityGate ${fieldName} automation transcript path must resolve to an existing file`);
-	let transcript: JsonObject;
-	try {
-		const parsed = JSON.parse(bytes.toString("utf8"));
-		transcript = requireQualityGateObject(parsed, `${fieldName}.transcript`);
-	} catch (error) {
-		throw new Error(`qualityGate ${fieldName} automation transcript must be valid JSON: ${String(error)}`);
-	}
-	if (transcript.schemaVersion !== 1)
-		throw new Error(`qualityGate ${fieldName} automation transcript schemaVersion must be 1`);
-	if (!transcriptSurfaceCompatible(transcript.surface, options.surfaceFamily)) {
-		throw new Error(
-			`qualityGate ${fieldName} automation transcript surface is not compatible with ${options.surfaceFamily}`,
-		);
-	}
-	if (!nonEmptyString(transcript.tool))
-		throw new Error(`qualityGate ${fieldName} automation transcript tool must be non-empty`);
-	const actions = requireObjectArray(transcript.actions, `${fieldName}.actions`);
-	if (actions.length < 1) throw new Error(`qualityGate ${fieldName} automation transcript actions must be non-empty`);
-	const assertionsValue = transcript.assertions;
-	const assertions =
-		assertionsValue === undefined ? [] : requireObjectArray(assertionsValue, `${fieldName}.assertions`);
-	const timestamps: number[] = [];
-	let hasSelectorBearingEntry = false;
-	for (const [index, action] of actions.entries()) {
-		const actionField = `${fieldName}.actions[${index}]`;
-		const type = requiredStringField(action, "type", actionField).toLowerCase();
-		const timestamp = normalizeTranscriptTimestamp(action.timestamp);
-		if (timestamp === null) throw new Error(`qualityGate ${actionField}.timestamp must be present and parseable`);
-		timestamps.push(timestamp);
-		const selector = nonEmptyString(action.selector);
-		if (actionSelectorRequired(type) && !selector)
-			throw new Error(`qualityGate ${actionField}.selector must be non-empty`);
-		if (type === "goto" && !nonEmptyString(action.url))
-			throw new Error(`qualityGate ${actionField}.url must be non-empty`);
-		if (type === "custom" && !selector && !nonEmptyString(action.target)) {
-			throw new Error(`qualityGate ${actionField}.selector or target must be non-empty`);
-		}
-		if (selector) hasSelectorBearingEntry = true;
-	}
-	for (const [index, assertion] of assertions.entries()) {
-		const assertionField = `${fieldName}.assertions[${index}]`;
-		const timestamp = normalizeTranscriptTimestamp(assertion.timestamp);
-		if (timestamp === null) throw new Error(`qualityGate ${assertionField}.timestamp must be present and parseable`);
-		timestamps.push(timestamp);
-		if (nonEmptyString(assertion.status)?.toLowerCase() !== PASSED_STATUS) {
-			throw new Error(`qualityGate ${assertionField}.status must be passed`);
-		}
-		if (nonEmptyString(assertion.selector)) hasSelectorBearingEntry = true;
-	}
-	for (let index = 1; index < timestamps.length; index++) {
-		if (timestamps[index]! < timestamps[index - 1]!) {
-			throw new Error(`qualityGate ${fieldName} automation transcript timestamps must be monotonic non-decreasing`);
-		}
-	}
-	if (!hasSelectorBearingEntry) {
-		throw new Error(
-			`qualityGate ${fieldName} automation transcript must include at least one selector-bearing action or assertion`,
-		);
-	}
-	return true;
-}
-
-async function validatePtyCaptureArtifact(cwd: string, row: JsonObject, fieldName: string): Promise<boolean> {
-	const bytes = await readArtifactBytes(cwd, row, fieldName);
-	if (!bytes) throw new Error(`qualityGate ${fieldName} PTY capture path must resolve to an existing file`);
-	if (bytes.length < 512) throw new Error(`qualityGate ${fieldName} PTY capture must be at least 512 bytes`);
-	const text = bytes.toString("utf8");
-	const hasCsi = /\x1b\[[0-?]*[ -/]*[@-~]/.test(text);
-	const hasOsc = /\x1b\][^\x07]*(?:\x07|\x1b\\)/.test(text);
-	const hasAltOrCursor = /\x1b\[\?1049[hl]|\x1b\[H|\x1b\[2J/.test(text);
-	const hasRedraw = /[\r\b]/.test(text) && hasCsi;
-	if (!hasCsi && !hasOsc && !hasAltOrCursor && !hasRedraw) {
-		throw new Error(`qualityGate ${fieldName} PTY capture must contain terminal control sequences`);
-	}
-	if (!/[\x20-\x7e]{10,}/.test(text)) {
-		throw new Error(
-			`qualityGate ${fieldName} PTY capture must contain a printable text run of at least 10 characters`,
-		);
-	}
-	return true;
-}
-
-function structuralArtifactKind(row: JsonObject): "screenshot" | "automation" | "pty" | null {
-	const kind = normalizedEvidenceKind(row);
-	if (evidenceKindMatches(kind, ["screenshot", "image", "visual"])) return "screenshot";
-	if (evidenceKindMatches(kind, ["browser", "playwright", "pandawright", "automation", "app-automation"]))
-		return "automation";
-	if (evidenceKindMatches(kind, ["pty", "tui", "terminal-capture"])) return "pty";
-	return null;
-}
-
-async function validateStructuralArtifact(
-	cwd: string,
-	row: JsonObject,
-	fieldName: string,
-	options: { surfaceFamily: SurfaceFamily; live: boolean },
-): Promise<boolean> {
-	void options.live;
-	const kind = structuralArtifactKind(row);
-	if (!kind) return false;
-	if (kind === "screenshot") return validateScreenshotArtifact(cwd, row, fieldName);
-	if (kind === "automation") return validateAutomationTranscriptArtifact(cwd, row, fieldName, options);
-	if (kind === "pty") return validatePtyCaptureArtifact(cwd, row, fieldName);
-	return false;
-}
-
-const CLI_REPLAY_MAX_OUTPUT_BYTES = 1024 * 1024;
-const CLI_REPLAY_DEFAULT_TIMEOUT_MS = 10_000;
-const CLI_REPLAY_MIN_TIMEOUT_MS = 1_000;
-const CLI_REPLAY_MAX_TIMEOUT_MS = 30_000;
-const CLI_REPLAY_EXEMPT_REASON_CODES = [
-	"unsafe_side_effect",
-	"requires_credentials",
-	"requires_network",
-	"non_deterministic_external",
-	"destructive",
-	"interactive_only",
-	"platform_unavailable",
-] as const;
-const CLI_REPLAY_EXEMPT_REASON_CODE_SET = new Set<string>(CLI_REPLAY_EXEMPT_REASON_CODES);
-const CLI_REPLAY_ENV_BASE: Record<string, string> = { CI: "1", NO_COLOR: "1", GJC_ULTRAGOAL_REPLAY: "1" };
-const CLI_REPLAY_EXEMPT_REASON_CODE_LIST = CLI_REPLAY_EXEMPT_REASON_CODES.join(", ");
-const CLI_REPLAY_SAFE_ENV_NAMES = new Set(["LANG", "LC_ALL", "LC_CTYPE", "TZ"]);
-const CLI_REPLAY_DANGEROUS_ENV_NAME_PATTERN =
-	/^(?:NODE_OPTIONS|GIT_EXTERNAL_DIFF|GIT_SSH|GIT_SSH_COMMAND|GIT_PAGER|PATH|LD_PRELOAD|LD_LIBRARY_PATH)$|^(?:GIT_CONFIG|DYLD_|BUN_|NPM_CONFIG_)|(?:^|_)OPTIONS$|PRELOAD$/;
-const ANSI_ESCAPE_PATTERN = /\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07]*(?:\x07|\x1b\\)|[@-Z\\-_])/g;
-
-function clampCliReplayTimeout(value: unknown): number {
-	if (value === undefined) return CLI_REPLAY_DEFAULT_TIMEOUT_MS;
-	if (typeof value !== "number" || !Number.isFinite(value)) {
-		throw new Error("qualityGate CLI replay timeoutMs must be a finite number");
-	}
-	return Math.min(CLI_REPLAY_MAX_TIMEOUT_MS, Math.max(CLI_REPLAY_MIN_TIMEOUT_MS, Math.trunc(value)));
-}
-
-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);
-}
-
-function isSafeRefOrPathspec(value: string): boolean {
-	return value.length > 0 && !value.startsWith("-") && !/[\0\n\r]/.test(value) && !hasShellRedirectionToken(value);
-}
-
-function isAllowedGitReplayCommand(args: readonly string[]): boolean {
-	const subcommand = args[0];
-	const rest = args.slice(1);
-	if (subcommand === "status") return rest.every(arg => ["--short", "--porcelain", "--branch"].includes(arg));
-	if (subcommand === "rev-parse" || subcommand === "merge-base")
-		return rest.length > 0 && rest.every(isSafeRefOrPathspec);
-	if (subcommand !== "diff" && subcommand !== "show" && subcommand !== "log") return false;
-	let pathspecMode = false;
-	for (const arg of rest) {
-		if (arg === "--") {
-			pathspecMode = true;
-			continue;
-		}
-		if (pathspecMode) {
-			if (!isSafeRefOrPathspec(arg)) return false;
-			continue;
-		}
-		if (["--stat", "--name-only", "--oneline", "--no-ext-diff"].includes(arg)) continue;
-		if (!isSafeRefOrPathspec(arg)) return false;
-	}
-	return true;
-}
-
-function isBareExecutableName(value: string): boolean {
-	// The allowlist is keyed on the basename, but the raw command[0] is what gets spawned.
-	// Reject path-qualified or case-spoofed executables (e.g. ./git, /tmp/npm, scripts/node, GIT)
-	// so an attacker-controlled binary cannot impersonate a trusted tool.
-	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]!)) return false;
-	const executable = basenameCommand(command[0]!);
-	const args = command.slice(1);
-	if (executable === "bun" || executable === "node") {
-		if (args.length === 1 && args[0] === "--version") return true;
-		return args.length === 2 && args[0] === "-e" && isDeterministicConsoleLogReplay(args[1]!);
-	}
-	if (executable === "npm" || executable === "pnpm" || executable === "yarn") {
-		return (args.length === 1 && args[0] === "--version") || (args.length === 1 && args[0] === "list");
-	}
-	if (executable === "git") return isAllowedGitReplayCommand(args);
-	if (executable === "gjc") return args.length === 1 && ["read", "status"].includes(args[0] ?? "");
-	return false;
-}
-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`, `node --version`, or deterministic `bun/node -e "console.log(...)"`',
-		"`npm|pnpm|yarn --version` or `npm|pnpm|yarn list`",
-		"read-only `git status|rev-parse|merge-base|diff|show|log` with safe args",
-		"`gjc read` or `gjc status`",
-	].join("; ");
-}
-
-function resolveCliReplayCommand(command: string[]): string[] {
-	if (basenameCommand(command[0]!) === "bun") return [process.execPath, ...command.slice(1)];
-	return command;
-}
-
-function resolveUnderCwd(cwd: string, replayCwd: unknown, fieldName: string): 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 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`);
-	}
-	return resolved;
-}
-
-function buildCliReplayEnv(value: unknown, fieldName: string): Record<string, string> {
-	const env: Record<string, string> = { ...CLI_REPLAY_ENV_BASE };
-	if (value === undefined) return env;
-	const object = requireQualityGateObject(value, `${fieldName}.env`);
-	for (const [key, envValue] of Object.entries(object)) {
-		if (!/^[A-Z_][A-Z0-9_]*$/.test(key))
-			throw new Error(`qualityGate ${fieldName}.env.${key} must be an uppercase environment key`);
-		if (CLI_REPLAY_DANGEROUS_ENV_NAME_PATTERN.test(key) || !CLI_REPLAY_SAFE_ENV_NAMES.has(key)) {
-			throw new Error(`qualityGate ${fieldName}.env.${key} is not in the CLI replay safe environment allowlist`);
-		}
-		if (typeof envValue !== "string") throw new Error(`qualityGate ${fieldName}.env.${key} must be a string`);
-		env[key] = envValue;
-	}
-	return env;
-}
-
-function normalizeCliReplayOutput(value: string, cwd: string): string {
-	let normalized = value.replace(ANSI_ESCAPE_PATTERN, "").replace(/\r\n?/g, "\n");
-	const home = process.env.HOME;
-	const replacements: Array<[RegExp, string]> = [
-		[/\b\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z\b/g, "<TIMESTAMP>"],
-		[/\b[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\b/gi, "<UUID>"],
-		[/\b[0-9a-f]{7,}\b/gi, "<HASH>"],
-		[/(?:\/private)?\/var\/folders\/[^\s"']+|\/tmp\/[^\s"']+|\/var\/tmp\/[^\s"']+/g, "<TMP>"],
-	];
-	for (const candidate of [path.resolve(cwd), home]) {
-		if (!candidate) continue;
-		const escaped = candidate.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-		normalized = normalized.replace(new RegExp(escaped, "g"), candidate === home ? "<HOME>" : "<CWD>");
-	}
-	for (const [pattern, replacement] of replacements) normalized = normalized.replace(pattern, replacement);
-	const lines = normalized.split("\n").map(line => line.replace(/[ \t]+$/g, ""));
-	while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
-	return lines.join("\n");
-}
-
-async function readCliReplayRecord(cwd: string, row: JsonObject, fieldName: string): Promise<JsonObject | null> {
-	const inline = qualityGateObject(row.replay) ?? (row.kind === "cli-replay" ? row : null);
-	if (inline) return inline;
-	if (!evidenceKindMatches(normalizedEvidenceKind(row), ["cli-replay", "command-replay"])) return null;
-	const bytes = await readArtifactBytes(cwd, row, fieldName);
-	if (!bytes) return null;
-	try {
-		return requireQualityGateObject(JSON.parse(bytes.toString("utf8")), `${fieldName}.replay`);
-	} catch (error) {
-		throw new Error(`qualityGate ${fieldName} CLI replay artifact must be valid JSON: ${String(error)}`);
-	}
-}
-
-function parseCliReplayRecord(
-	record: JsonObject,
-	fieldName: string,
-): {
-	command: string[];
-	replayCwd: unknown;
-	env: Record<string, string>;
-	timeoutMs: number;
-	expectedExitCode: number;
-	recordedStdout: string;
-	invariants: JsonObject[];
-} {
-	if (record.schemaVersion !== 1) throw new Error(`qualityGate ${fieldName}.schemaVersion must be 1`);
-	if (record.kind !== "cli-replay") throw new Error(`qualityGate ${fieldName}.kind must be cli-replay`);
-	if (record.command !== undefined && typeof record.command === "string") {
-		throw new Error(`qualityGate ${fieldName}.command must be an argv string array, not a shell string`);
-	}
-	const command = nonEmptyStringArray(record.command);
-	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 conservative 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`);
-	}
-	if (typeof record.recordedStdout !== "string")
-		throw new Error(`qualityGate ${fieldName}.recordedStdout must be a string`);
-	if (record.recordedStderr !== undefined && typeof record.recordedStderr !== "string") {
-		throw new Error(`qualityGate ${fieldName}.recordedStderr must be a string when provided`);
-	}
-	const expectedExitCode = record.expectedExitCode === undefined ? 0 : record.expectedExitCode;
-	if (typeof expectedExitCode !== "number" || !Number.isInteger(expectedExitCode)) {
-		throw new Error(`qualityGate ${fieldName}.expectedExitCode must be an integer`);
-	}
-	const invariants =
-		record.invariants === undefined ? [] : requireObjectArray(record.invariants, `${fieldName}.invariants`);
-	return {
-		command: command.map(item => item.trim()),
-		replayCwd: record.cwd,
-		env: buildCliReplayEnv(record.env, fieldName),
-		timeoutMs: clampCliReplayTimeout(record.timeoutMs),
-		expectedExitCode,
-		recordedStdout: record.recordedStdout,
-		invariants,
-	};
-}
-
-function validateCliReplayInvariants(invariants: JsonObject[], stdout: string, fieldName: string): void {
-	for (const [index, invariant] of invariants.entries()) {
-		const invariantField = `${fieldName}.invariants[${index}]`;
-		const type = requiredStringField(invariant, "type", invariantField);
-		const value = requiredStringField(invariant, "value", invariantField);
-		if (type === "substring" && !stdout.includes(value))
-			throw new Error(`qualityGate ${invariantField} substring invariant did not match stdout`);
-		else if (type === "not_substring" && stdout.includes(value))
-			throw new Error(`qualityGate ${invariantField} not_substring invariant matched stdout`);
-		else if (type === "regex") {
-			const flags = invariant.flags === undefined ? "" : requiredStringField(invariant, "flags", invariantField);
-			if (!/^[im]*$/.test(flags)) throw new Error(`qualityGate ${invariantField}.flags may only contain i and m`);
-			if (!new RegExp(value, flags).test(stdout))
-				throw new Error(`qualityGate ${invariantField} regex invariant did not match stdout`);
-		} else if (type !== "substring" && type !== "not_substring") {
-			throw new Error(`qualityGate ${invariantField}.type must be substring, regex, or not_substring`);
-		}
-	}
-}
-
-async function collectCliReplayOutput(
-	stream: ReadableStream<Uint8Array> | null,
-): Promise<{ text: string; truncated: boolean }> {
-	if (!stream) return { text: "", truncated: false };
-	const reader = stream.getReader();
-	const chunks: Buffer[] = [];
-	let size = 0;
-	let truncated = false;
-	try {
-		while (true) {
-			const { done, value } = await reader.read();
-			if (done) break;
-			if (size < CLI_REPLAY_MAX_OUTPUT_BYTES) {
-				const remaining = CLI_REPLAY_MAX_OUTPUT_BYTES - size;
-				const chunk = Buffer.from(value.subarray(0, remaining));
-				chunks.push(chunk);
-				size += chunk.length;
-			}
-			if (value.length > 0 && size >= CLI_REPLAY_MAX_OUTPUT_BYTES) {
-				truncated = true;
-				await reader.cancel().catch(() => undefined);
-				break;
-			}
-		}
-	} finally {
-		reader.releaseLock();
-	}
-	return { text: Buffer.concat(chunks).toString("utf8"), truncated };
-}
-
-export interface ReplayProcessHandle {
-	readonly exited: Promise<number>;
-	kill(signal?: number | NodeJS.Signals): void;
-}
-
-export async function waitForReplayProcessWithTimeout(
-	process: ReplayProcessHandle,
-	timeoutMs: number,
-	graceMs = 2000,
-): Promise<number> {
-	let timeoutTimer: NodeJS.Timeout | undefined;
-	let graceTimer: NodeJS.Timeout | undefined;
-	const timedOut = Symbol("timedOut");
-	const timeout = new Promise<typeof timedOut>(resolve => {
-		timeoutTimer = setTimeout(() => resolve(timedOut), timeoutMs);
-	});
-	const first = await Promise.race([process.exited, timeout]);
-	if (first !== timedOut) {
-		if (timeoutTimer) clearTimeout(timeoutTimer);
-		return first;
-	}
-	process.kill("SIGTERM");
-	const killed = Symbol("killed");
-	const grace = new Promise<typeof killed>(resolve => {
-		graceTimer = setTimeout(() => {
-			process.kill("SIGKILL");
-			resolve(killed);
-		}, graceMs);
-	});
-	await Promise.race([process.exited, grace]);
-	await process.exited.catch(() => undefined);
-	if (timeoutTimer) clearTimeout(timeoutTimer);
-	if (graceTimer) clearTimeout(graceTimer);
-	throw new Error("timeout");
-}
-
-async function validateReplayExemptFallback(
-	cwd: string,
-	record: JsonObject,
-	fieldName: string,
-	artifactRefs: Map<string, JsonObject>,
-	options: { surfaceFamily: SurfaceFamily; live: boolean },
-): Promise<boolean> {
-	const exempt = qualityGateObject(record.replayExempt);
-	if (!exempt) return false;
-	const reasonCode = requiredStringField(exempt, "reasonCode", `${fieldName}.replayExempt`);
-	if (!CLI_REPLAY_EXEMPT_REASON_CODE_SET.has(reasonCode))
-		throw new Error(
-			`qualityGate ${fieldName}.replayExempt.reasonCode must be one of: ${CLI_REPLAY_EXEMPT_REASON_CODE_LIST}`,
-		);
-	const reason = requiredStringField(exempt, "reason", `${fieldName}.replayExempt`);
-	if (!isSubstantiveEvidence(reason) || reason.length < 30)
-		throw new Error(`qualityGate ${fieldName}.replayExempt.reason must be audited and substantive`);
-	requiredStringField(exempt, "approvedBy", `${fieldName}.replayExempt`);
-	const fallbackRefs = requireStringLinks(
-		exempt.fallbackArtifactRefs,
-		`${fieldName}.replayExempt.fallbackArtifactRefs`,
-	);
-	requireResolvedLinks(fallbackRefs, artifactRefs, `${fieldName}.replayExempt.fallbackArtifactRefs`);
-	let validFallback = false;
-	for (const fallbackRef of fallbackRefs) {
-		if (fallbackRef === requiredStringField(record, "id", fieldName)) {
-			throw new Error(`qualityGate ${fieldName}.replayExempt fallback must not reference the replay record itself`);
-		}
-		const fallback = artifactRefs.get(fallbackRef)!;
-		if (await validateStructuralArtifact(cwd, fallback, `executorQa.artifactRefs.${fallbackRef}`, options))
-			validFallback = true;
-	}
-	if (!validFallback)
-		throw new Error(
-			`qualityGate ${fieldName}.replayExempt requires at least one structurally-valid fallback artifact`,
-		);
-	return true;
-}
-async function validateCliReplay(
-	cwd: string,
-	row: JsonObject,
-	fieldName: string,
-	options: { live: boolean },
-): Promise<boolean> {
-	const record = await readCliReplayRecord(cwd, row, fieldName);
-	if (!record) return false;
-	if (record.replayExempt !== undefined) {
-		throw new Error(
-			`qualityGate ${fieldName}.replayExempt can only be validated from surfaceEvidence with fallback context`,
-		);
-	}
-	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",
-	});
-	try {
-		const [stdout, stderr, exitCode] = await Promise.all([
-			collectCliReplayOutput(process.stdout),
-			collectCliReplayOutput(process.stderr),
-			waitForReplayProcessWithTimeout(process, replay.timeoutMs),
-		]);
-		if (stdout.truncated || stderr.truncated)
-			throw new Error(`qualityGate ${fieldName} CLI replay output exceeded 1 MiB buffer cap`);
-		if (exitCode !== replay.expectedExitCode) {
-			throw new Error(
-				`qualityGate ${fieldName} CLI replay exit code ${exitCode} did not match expected ${replay.expectedExitCode}`,
-			);
-		}
-		const actualStdout = normalizeCliReplayOutput(stdout.text, cwd);
-		const recordedStdout = normalizeCliReplayOutput(replay.recordedStdout, cwd);
-		if (replay.invariants.length > 0) {
-			validateCliReplayInvariants(replay.invariants, actualStdout, fieldName);
-		} else if (actualStdout !== recordedStdout) {
-			throw new Error(`qualityGate ${fieldName} CLI replay stdout did not match recordedStdout after normalization`);
-		}
-		return true;
-	} catch (error) {
-		if (error instanceof Error && error.message === "timeout") {
-			throw new Error(`qualityGate ${fieldName} CLI replay timed out after ${replay.timeoutMs}ms`);
-		}
-		throw error;
-	}
-}
-
-async function hasLiveProofPresence(
-	cwd: string,
-	row: JsonObject,
-	fieldName: string,
-	family: SurfaceFamily,
-): Promise<boolean> {
-	if (await hasExistingNonEmptyArtifact(cwd, row.path)) return true;
-	if (family === "cli") {
-		const record = await readCliReplayRecord(cwd, row, fieldName);
-		if (record) return true;
-	}
-	return false;
-}
-
-async function validateLiveSurfaceProofPresence(
-	cwd: string,
-	family: SurfaceFamily,
-	artifactIds: string[],
-	artifactRefs: Map<string, JsonObject>,
-): Promise<void> {
-	if (!isLiveSurfaceFamily(family)) return;
-	for (const artifactId of artifactIds) {
-		if (
-			await hasLiveProofPresence(cwd, artifactRefs.get(artifactId)!, `executorQa.artifactRefs.${artifactId}`, family)
-		)
-			return;
-	}
-	throw new Error(
-		`qualityGate ${artifactIds.map(id => `executorQa.artifactRefs.${id}`).join(", ")} must reference a live proof artifact, structural capture, or CLI replay; inlineEvidence and typed verifiedReceipt do not prove live surfaces`,
-	);
-}
-async function validateSurfaceStructuralRequirement(
-	cwd: string,
-	family: SurfaceFamily,
-	artifactIds: string[],
-	artifactRefs: Map<string, JsonObject>,
-	fieldName: string,
-): Promise<void> {
-	if (family !== "web" && family !== "native") return;
-	let hasScreenshot = false;
-	let hasAutomation = false;
-	let hasPty = false;
-	for (const artifactId of artifactIds) {
-		const artifact = artifactRefs.get(artifactId)!;
-		const kind = structuralArtifactKind(artifact);
-		if (!kind) continue;
-		const valid = await validateStructuralArtifact(cwd, artifact, `executorQa.artifactRefs.${artifactId}`, {
-			surfaceFamily: family,
-			live: true,
-		});
-		if (kind === "screenshot" && valid) hasScreenshot = true;
-		if (kind === "automation" && valid) hasAutomation = true;
-		if (kind === "pty" && valid) hasPty = true;
-	}
-	if (family === "web" && (!hasScreenshot || !hasAutomation)) {
-		throw new Error(
-			`qualityGate ${fieldName} for GUI/web surfaces must include a valid automation transcript and non-uniform screenshot`,
-		);
-	}
-	if (family === "native" && !hasScreenshot && !hasAutomation && !hasPty) {
-		throw new Error(
-			`qualityGate ${fieldName} for native surfaces must include a valid screenshot, PTY capture, or app-automation transcript`,
-		);
-	}
-}
-
-async function validateArtifactProof(
-	cwd: string,
-	row: JsonObject,
-	fieldName: string,
-	options: { surfaceFamily: SurfaceFamily; live: boolean },
-): Promise<void> {
-	if (await hasExistingNonEmptyArtifact(cwd, row.path)) return;
-	if (await validateStructuralArtifact(cwd, row, fieldName, options)) return;
-	if (options.surfaceFamily === "cli" && (await validateCliReplay(cwd, row, fieldName, { live: options.live })))
-		return;
-	if (!options.live && (hasTypedVerifiedReceipt(row.verifiedReceipt) || hasTypedVerifiedReceipt(row.receipt))) return;
-	const proofLabel = options.live
-		? "a live proof artifact, structural capture, or CLI replay; inlineEvidence and typed verifiedReceipt do not prove live surfaces"
-		: "an existing non-empty artifact path or a typed verifiedReceipt; inlineEvidence alone is not sufficient";
-	throw new Error(`qualityGate ${fieldName} must reference ${proofLabel}`);
-}
+import {
+	readCliReplayRecord,
+	validateArtifactProof,
+	validateCliReplay,
+	validateLiveSurfaceProofPresence,
+	validateReplayExemptFallback,
+	validateStructuralArtifact,
+	validateSurfaceStructuralRequirement,
+	waitForReplayProcessWithTimeout,
+} from "./ultragoal-evidence";
+
+export type { ReplayProcessHandle } from "./ultragoal-evidence";
+export {
+	validateArtifactProof,
+	validateCliReplay,
+	validateLiveSurfaceProofPresence,
+	validateReplayExemptFallback,
+	validateStructuralArtifact,
+	validateSurfaceStructuralRequirement,
+	waitForReplayProcessWithTimeout,
+};
 
 async function validateArtifactRefs(cwd: string, executorQa: JsonObject): Promise<Map<string, JsonObject>> {
 	void cwd;
@@ -3964,13 +2906,21 @@ export async function checkpointUltragoalGoal(input: {
 	const evidence = input.evidence.trim();
 	if (!evidence) throw new Error("checkpoint evidence is required");
 	const ledgerBefore = await readUltragoalLedger(input.cwd);
-	const matchingIdempotentEvent = ledgerBefore.find(
+	const matchingIdempotentEvents = ledgerBefore.filter(
 		event =>
 			event.event === "goal_checkpointed" &&
 			event.goalId === goal.id &&
 			event.status === input.status &&
 			event.evidence === evidence,
 	);
+	// Re-verification replays legitimately append repeated same-status,
+	// same-evidence checkpoint events for one goal. The recorded receipt must
+	// be compared against ITS OWN checkpoint event — resolved by the receipt's
+	// checkpointLedgerEventId, falling back to the latest match — never the
+	// oldest duplicate, which would wrongly report the current receipt stale.
+	const matchingIdempotentEvent =
+		matchingIdempotentEvents.find(event => event.eventId === goal.completionVerification?.checkpointLedgerEventId) ??
+		matchingIdempotentEvents.at(-1);
 	const batchMetadata = input.status === "complete" ? requireFreshValidationBatchMetadata(goal) : undefined;
 	if (batchMetadata && goal.completionVerification?.validationBatch) {
 		const receiptBatch = goal.completionVerification.validationBatch;
@@ -3987,7 +2937,35 @@ export async function checkpointUltragoalGoal(input: {
 	if (input.status === "complete" && goal.completionVerification?.validationBatch && !batchMetadata) {
 		throw new Error(`Goal ${goal.id} has stale validation batch completion receipt`);
 	}
-	if (goal.status === input.status && goal.evidence === evidence && matchingIdempotentEvent) {
+	// An identical-evidence complete replay is only a no-op while the recorded
+	// receipt still validates fresh. When the goal row itself is untouched
+	// (updatedAt still matches the receipt's verifiedAt) but later goal-tagged
+	// ledger events (e.g. blocker classifications) or plan growth staled the
+	// receipt, the replay is a genuine re-verification: it must run the full
+	// quality gate and mint a fresh receipt, otherwise a completed goal with a
+	// context-staled receipt can never be repaired (different evidence is
+	// rejected on complete goals by design). A mutated goal row keeps the
+	// fail-loud tamper handling in the idempotent branch below.
+	const staleCompleteReceiptReplay =
+		input.status === "complete" &&
+		goal.status === "complete" &&
+		goal.evidence === evidence &&
+		Boolean(matchingIdempotentEvent) &&
+		(!goal.completionVerification ||
+			(goal.completionVerification.verifiedAt === goal.updatedAt &&
+				validateReceiptFreshBase({
+					plan,
+					ledger: ledgerBefore,
+					goal,
+					receipt: goal.completionVerification,
+					receiptKind: goal.completionVerification.receiptKind,
+				}) !== null));
+	if (
+		goal.status === input.status &&
+		goal.evidence === evidence &&
+		matchingIdempotentEvent &&
+		!staleCompleteReceiptReplay
+	) {
 		if (batchMetadata) {
 			const receipt = goal.completionVerification;
 			const receiptBatch = receipt?.validationBatch;
@@ -4009,6 +2987,18 @@ export async function checkpointUltragoalGoal(input: {
 			)
 				throw new Error(`Goal ${goal.id} has stale validation batch metadata hash in close receipt`);
 		}
+		// A complete goal whose row changed after its receipt was verified is
+		// neither a clean no-op nor a repairable context-stale replay: fail loud
+		// instead of silently laundering a tampered/inconsistent durable row.
+		if (
+			input.status === "complete" &&
+			goal.completionVerification &&
+			goal.completionVerification.verifiedAt !== goal.updatedAt
+		) {
+			throw new Error(
+				`Goal ${goal.id} changed after its completion receipt was verified; refusing idempotent replay. Investigate the durable goals.json row before re-checkpointing.`,
+			);
+		}
 		// Idempotent re-checkpoint: this goal is already recorded in the target status with the same
 		// evidence, so skip the plan rewrite and ledger append to avoid duplicate goal_checkpointed
 		// events. The ledger is the dedup source of truth because it is exactly what a duplicate write
@@ -4020,7 +3010,7 @@ export async function checkpointUltragoalGoal(input: {
 	const changeSet = input.status === "complete" ? await computeCheckpointChangeSet(input.cwd) : undefined;
 	if (input.status === "complete") {
 		validatePipelineCheckpointSafety(plan, goal, changeSet);
-		validateCompleteCheckpointTargetGoal(goal);
+		if (!staleCompleteReceiptReplay) validateCompleteCheckpointTargetGoal(goal);
 	}
 	const qualityGateJson =
 		input.status === "complete"
@@ -4047,7 +3037,7 @@ export async function checkpointUltragoalGoal(input: {
 			blockedGoal.updatedAt = now;
 		}
 	}
-	const receiptKind = input.status === "complete" ? chooseReceiptKind(plan, goal, input.status) : null;
+	const receiptKind = input.status === "complete" ? chooseReceiptKind(plan, ledgerBefore, goal, input.status) : null;
 	const pendingCheckpointEventId = crypto.randomUUID();
 	if (input.status === "complete" && receiptKind && qualityGateJson && !Array.isArray(qualityGateJson)) {
 		goal.completionVerification = buildCompletionReceipt({
@@ -4618,168 +3608,15 @@ async function readOptionalExecutorQa(cwd: string, value: string | undefined): P
 	return structured as JsonObject;
 }
 
-async function spawnText(
-	command: string[],
-	options: { cwd: string; timeoutMs?: number },
-): Promise<{ ok: boolean; stdout: string; stderr: string }> {
-	try {
-		const proc = Bun.spawn(command, { cwd: options.cwd, stdout: "pipe", stderr: "pipe" });
-		const timeout = setTimeout(() => proc.kill(), options.timeoutMs ?? 5000);
-		const [stdout, stderr, exitCode] = await Promise.all([
-			new Response(proc.stdout).text(),
-			new Response(proc.stderr).text(),
-			proc.exited,
-		]);
-		clearTimeout(timeout);
-		return { ok: exitCode === 0, stdout, stderr };
-	} catch (error) {
-		return { ok: false, stdout: "", stderr: error instanceof Error ? error.message : String(error) };
-	}
-}
-
-export async function resolveGitBase(cwd: string, branch?: string): Promise<string> {
-	if (branch) {
-		const exists = await spawnText(["git", "rev-parse", "--verify", branch], { cwd, timeoutMs: 3000 });
-		if (exists.ok) return branch;
-	} else {
-		// Prefer the NEAREST integration base (the branch this work actually forks
-		// from) rather than always `main`. A branch opened against `dev` must be
-		// scoped to `dev`; using a stale `main` sweeps in unrelated trunk history
-		// and mis-attributes other people's changes to this story (e.g. falsely
-		// tripping change-scoped gates). Among existing candidates, pick the one
-		// whose merge-base with HEAD is closest to HEAD (fewest commits ahead).
-		const candidates = ["origin/dev", "dev", "origin/main", "origin/master", "main", "master"];
-		let best: { ref: string; ahead: number } | undefined;
-		for (const candidate of candidates) {
-			const exists = await spawnText(["git", "rev-parse", "--verify", candidate], { cwd, timeoutMs: 3000 });
-			if (!exists.ok) continue;
-			const mergeBase = await spawnText(["git", "merge-base", "HEAD", candidate], { cwd, timeoutMs: 3000 });
-			if (!mergeBase.ok || !mergeBase.stdout.trim()) continue;
-			const count = await spawnText(["git", "rev-list", "--count", `${mergeBase.stdout.trim()}..HEAD`], {
-				cwd,
-				timeoutMs: 3000,
-			});
-			const ahead = Number.parseInt(count.stdout.trim(), 10);
-			if (!Number.isFinite(ahead)) continue;
-			if (!best || ahead < best.ahead) best = { ref: candidate, ahead };
-		}
-		if (best) return best.ref;
-	}
-	const mergeBase = await spawnText(["git", "merge-base", "HEAD", "origin/main"], { cwd, timeoutMs: 3000 });
-	if (mergeBase.ok && mergeBase.stdout.trim()) return mergeBase.stdout.trim();
-	return "HEAD~1";
-}
-
-function parseGitNameStatus(output: string): UltragoalChangeSetPath[] {
-	const rows: UltragoalChangeSetPath[] = [];
-	for (const line of output.split("\n")) {
-		const trimmed = line.trim();
-		if (!trimmed) continue;
-		const parts = trimmed.split(/\s+/);
-		const statusCode = parts[0] ?? "";
-		let status: UltragoalChangeStatus = "unknown";
-		if (statusCode.startsWith("A")) status = "added";
-		else if (statusCode.startsWith("M")) status = "modified";
-		else if (statusCode.startsWith("D")) status = "deleted";
-		else if (statusCode.startsWith("R")) status = "renamed";
-		else if (statusCode.startsWith("C")) status = "copied";
-		const pathValue = status === "renamed" || status === "copied" ? parts[2] : parts[1];
-		if (!pathValue) continue;
-		const oldPath = status === "renamed" || status === "copied" ? parts[1] : undefined;
-		rows.push({
-			path: normalizeRepoPath(pathValue),
-			oldPath: oldPath ? normalizeRepoPath(oldPath) : undefined,
-			status,
-			category: categorizeComputerChangePath(pathValue),
-		});
-	}
-	return rows;
-}
-
-function categorizeCiChangedPath(value: string): UltragoalChangeCategory {
-	// CI_DEV_CHANGED_PATHS intentionally carries path names only. Mixed registries
-	// such as settings-schema.ts require diff-level narrowing; without the diff,
-	// treating the whole registry as computer-control source forces the mandatory
-	// computer red-team suite on unrelated settings changes.
-	if (isSettingsSchemaPath(value)) return "other";
-	return categorizeComputerChangePath(value);
-}
-
-function ciDevChangedPathRows(): UltragoalChangeSetPath[] {
-	const raw = process.env.CI_DEV_CHANGED_PATHS;
-	if (!raw) return [];
-	return raw
-		.split(/\r?\n/)
-		.map(row => row.trim())
-		.filter(Boolean)
-		.map(pathValue => ({
-			path: normalizeRepoPath(pathValue),
-			status: "unknown" as UltragoalChangeStatus,
-			category: categorizeCiChangedPath(pathValue),
-		}));
-}
-
-function mergeChangeSetPaths(groups: UltragoalChangeSetPath[][]): UltragoalChangeSetPath[] {
-	const byKey = new Map<string, UltragoalChangeSetPath>();
-	for (const row of groups.flat()) byKey.set(`${row.oldPath ?? ""}\u0000${row.path}`, row);
-	return [...byKey.values()];
-}
-
-async function computeCheckpointChangeSet(cwd: string): Promise<UltragoalChangeSet | undefined> {
-	const ciChangedPaths = ciDevChangedPathRows();
-	const inGit = await spawnText(["git", "rev-parse", "--is-inside-work-tree"], { cwd, timeoutMs: 3000 });
-	if (!inGit.ok || inGit.stdout.trim() !== "true") {
-		if (ciChangedPaths.length === 0) return undefined;
-		return { source: "checkpoint-git", paths: ciChangedPaths, trusted: true };
-	}
-	const baseRef = await resolveGitBase(cwd);
-	const base = baseRef;
-	const mergeBase = await spawnText(["git", "merge-base", "HEAD", baseRef], { cwd, timeoutMs: 3000 });
-	const [committed, unstaged, staged, stat, committedDiff, unstagedDiff, stagedDiff] = await Promise.all([
-		spawnText(["git", "diff", "--name-status", `${base}...HEAD`], { cwd, timeoutMs: 5000 }),
-		spawnText(["git", "diff", "--name-status"], { cwd, timeoutMs: 5000 }),
-		spawnText(["git", "diff", "--cached", "--name-status"], { cwd, timeoutMs: 5000 }),
-		spawnText(["git", "diff", "--stat", `${base}...HEAD`], { cwd, timeoutMs: 5000 }),
-		spawnText(["git", "diff", `${base}...HEAD`], { cwd, timeoutMs: 5000 }),
-		spawnText(["git", "diff"], { cwd, timeoutMs: 5000 }),
-		spawnText(["git", "diff", "--cached"], { cwd, timeoutMs: 5000 }),
-	]);
-	if (!committed.ok && !unstaged.ok && !staged.ok && ciChangedPaths.length === 0) return undefined;
-	const gitPaths = mergeChangeSetPaths([
-		parseGitNameStatus(committed.stdout),
-		parseGitNameStatus(unstaged.stdout),
-		parseGitNameStatus(staged.stdout),
-	]);
-	const paths = gitPaths.length > 0 ? gitPaths : ciChangedPaths;
-	return {
-		source: "checkpoint-git",
-		baseRef,
-		mergeBase: mergeBase.ok && mergeBase.stdout.trim() ? mergeBase.stdout.trim() : undefined,
-		headRef: "HEAD",
-		paths,
-		rawDiffStat: stat.stdout,
-		rawDiff: [committedDiff.stdout, unstagedDiff.stdout, stagedDiff.stdout].filter(Boolean).join("\n"),
-		trusted: true,
-	};
-}
-
-function parseUnifiedDiffPaths(diff: string): UltragoalChangeSetPath[] {
-	const paths: UltragoalChangeSetPath[] = [];
-	for (const line of diff.split("\n")) {
-		if (!line.startsWith("diff --git ")) continue;
-		const match = /^diff --git a\/(.+?) b\/(.+)$/.exec(line);
-		if (!match) continue;
-		const oldPath = normalizeRepoPath(match[1]!);
-		const newPath = normalizeRepoPath(match[2]!);
-		paths.push({
-			path: newPath,
-			oldPath: oldPath === newPath ? undefined : oldPath,
-			status: oldPath === newPath ? "modified" : "renamed",
-			category: categorizeComputerChangePath(newPath),
-		});
-	}
-	return paths;
-}
+import {
+	computeCheckpointChangeSet,
+	parseGitNameStatus,
+	parseUnifiedDiffPaths,
+	resolveGitBase,
+	spawnText,
+} from "./ultragoal-change-set";
+
+export { computeCheckpointChangeSet, parseGitNameStatus, parseUnifiedDiffPaths, resolveGitBase, spawnText };
 
 function changeSetFromReviewSource(source: JsonObject): UltragoalChangeSet | undefined {
 	const kind = nonEmptyString(source.kind);