oh-my-opencode 4.19.0 → 4.19.2

package/packages/omo-codex/plugin/components/ulw-loop/src/steering-batch.ts

@@ -0,0 +1,125 @@
+// biome-ignore-all format: compact batch steering module stays below the pure LOC budget.
+import type { UlwLoopScope } from "./paths.js";
+import { appendLedger, appendLedgerEntries, findAcceptedSteeringLedgerEntry, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
+import { applySteeringMutation, validateUlwLoopSteeringProposal } from "./steering.js";
+import { buildSteeringPlanSnapshot, changedGoalIdsBetween } from "./steering-snapshot.js";
+import type { UlwLoopLedgerEntry, UlwLoopPlan, UlwLoopSteeringAudit, UlwLoopSteeringProposal } from "./types.js";
+import { iso } from "./types.js";
+import { batchUpdateLedgerEntry } from "./validation-batch.js";
+
+export interface SteerUlwLoopBatchItemResult {
+	readonly accepted: boolean;
+	readonly deduped: boolean;
+	readonly audit: UlwLoopSteeringAudit;
+	readonly rejectedReasons: readonly string[];
+}
+
+export interface SteerUlwLoopBatchResult {
+	readonly plan: UlwLoopPlan;
+	readonly accepted: boolean;
+	readonly results: readonly SteerUlwLoopBatchItemResult[];
+	readonly rejectedReasons: readonly string[];
+}
+
+type PreparedFresh = {
+	readonly proposal: UlwLoopSteeringProposal;
+	readonly audit: UlwLoopSteeringAudit;
+	readonly before: UlwLoopPlan;
+	readonly next: UlwLoopPlan;
+};
+
+type PreparedItem =
+	| { readonly kind: "deduped"; readonly result: SteerUlwLoopBatchItemResult }
+	| { readonly kind: "fresh"; readonly prepared: PreparedFresh };
+
+export async function steerUlwLoopBatch(
+	repoRoot: string,
+	proposals: readonly UlwLoopSteeringProposal[],
+	scope?: UlwLoopScope,
+): Promise<SteerUlwLoopBatchResult> {
+	return withUlwLoopMutationLock(repoRoot, scope, async () => {
+		const plan = await readUlwLoopPlan(repoRoot, scope);
+		const prepared = await prepareBatch(repoRoot, plan, proposals, scope);
+		const failed = prepared.results.find((item) => !item.accepted);
+		if (failed !== undefined) {
+			const entry = rejectedLedgerEntry(prepared.results);
+			await appendLedger(repoRoot, entry, scope);
+			return rejected(plan, prepared.results, failed.rejectedReasons);
+		}
+		let next = plan;
+		for (const item of prepared.items) if (item.kind === "fresh") next = item.prepared.next;
+		const fresh = prepared.items.filter((item): item is Extract<PreparedItem, { readonly kind: "fresh" }> => item.kind === "fresh");
+		if (fresh.length > 0) {
+			await writePlan(repoRoot, next, scope);
+			const entries = fresh.map((item) => ledgerEntry(item.prepared.proposal, item.prepared.audit, item.prepared.proposal.now?.toISOString() ?? iso()));
+			const batchEntry = batchUpdateLedgerEntry(plan, next, iso());
+			await appendLedgerEntries(repoRoot, batchEntry === null ? entries : [...entries, batchEntry], scope);
+		}
+		return { plan: next, accepted: true, results: prepared.results, rejectedReasons: [] };
+	});
+}
+
+async function prepareBatch(
+	repoRoot: string,
+	plan: UlwLoopPlan,
+	proposals: readonly UlwLoopSteeringProposal[],
+	scope: UlwLoopScope | undefined,
+): Promise<{ readonly items: readonly PreparedItem[]; readonly results: readonly SteerUlwLoopBatchItemResult[] }> {
+	const items: PreparedItem[] = [];
+	const results: SteerUlwLoopBatchItemResult[] = [];
+	let current = plan;
+	for (const proposal of proposals) {
+		const key = proposal.idempotencyKey ?? proposal.promptSignature;
+		const prior = key === undefined ? undefined : await findAcceptedSteeringLedgerEntry(repoRoot, key, scope);
+		if (prior?.steering !== undefined) {
+			const result = { accepted: true, deduped: true, audit: { ...prior.steering, deduped: true }, rejectedReasons: [] };
+			items.push({ kind: "deduped", result });
+			results.push(result);
+			continue;
+		}
+		const audit = validateUlwLoopSteeringProposal(current, proposal);
+		if (!audit.invariant.accepted) {
+			const result = { accepted: false, deduped: false, audit, rejectedReasons: audit.invariant.rejectedReasons };
+			items.push({ kind: "deduped", result });
+			results.push(result);
+			continue;
+		}
+		const next = applySteeringMutation(current, proposal, audit);
+		const changed = changedGoalIdsBetween(current, next);
+		const finalAudit = { ...audit, before: buildSteeringPlanSnapshot(current, changed), after: buildSteeringPlanSnapshot(next, changed) };
+		const result = { accepted: true, deduped: false, audit: finalAudit, rejectedReasons: [] };
+		items.push({ kind: "fresh", prepared: { proposal, audit: finalAudit, before: current, next } });
+		results.push(result);
+		current = next;
+	}
+	return { items, results };
+}
+
+function rejected(
+	plan: UlwLoopPlan,
+	results: readonly SteerUlwLoopBatchItemResult[],
+	rejectedReasons: readonly string[],
+): SteerUlwLoopBatchResult {
+	return { plan, accepted: false, results, rejectedReasons };
+}
+
+function rejectedLedgerEntry(results: readonly SteerUlwLoopBatchItemResult[]): UlwLoopLedgerEntry {
+	const rejectedItems = results.map((result, index) => ({ result, index })).filter((item) => !item.result.accepted);
+	return { at: iso(), kind: "steering_rejected", message: rejectedItems.map((item) => `index ${item.index}: ${item.result.rejectedReasons.join(", ")}`).join("; ") };
+}
+
+function ledgerEntry(proposal: UlwLoopSteeringProposal, audit: UlwLoopSteeringAudit, at: string): UlwLoopLedgerEntry {
+	const entry: UlwLoopLedgerEntry = {
+		at,
+		kind: proposal.kind === "revise_criterion" ? "criteria_revised" : "steering_accepted",
+		evidence: proposal.evidence,
+		message: proposal.rationale,
+		steering: audit,
+		mutationKind: proposal.kind,
+	};
+	const goalId = audit.targetGoalIds[0];
+	if (goalId !== undefined) entry.goalId = goalId;
+	if (proposal.criterionId !== undefined) entry.criterionId = proposal.criterionId;
+	if (proposal.idempotencyKey !== undefined) entry.idempotencyKey = proposal.idempotencyKey;
+	return entry;
+}

package/packages/omo-codex/plugin/components/ulw-loop/src/steering-mutations.ts

@@ -0,0 +1,59 @@
+// biome-ignore-all format: compact extracted steering mutations stay below the pure LOC budget.
+import { seedDefaultSuccessCriteria } from "./plan-crud.js";
+import type { UlwLoopItem, UlwLoopPlan, UlwLoopSteeringChildGoal, UlwLoopSteeringProposal, UlwLoopSuccessCriterionUserModel } from "./types.js";
+import { ULW_LOOP_SUCCESS_CRITERION_USER_MODELS } from "./types.js";
+import { updateBatchesAfterSupersede } from "./validation-batch.js";
+
+const read = (value: object, key: string): unknown => Object.entries(value).find(([name]) => name === key)?.[1];
+const isText = (value: unknown): value is string => typeof value === "string" && value.trim().length > 0;
+const text = (value: object, key: string): string | undefined => { const candidate = read(value, key); return isText(candidate) ? candidate.trim() : undefined; };
+const isModel = (value: unknown): value is UlwLoopSuccessCriterionUserModel => typeof value === "string" && ULW_LOOP_SUCCESS_CRITERION_USER_MODELS.some((model) => model === value);
+const after = (proposal: object): object | undefined => { const candidate = read(proposal, "after"); return typeof candidate === "object" && candidate !== null && !Array.isArray(candidate) ? candidate : undefined; };
+const revised = (proposal: object, direct: string, nested: string): string | undefined => text(proposal, direct) ?? text(after(proposal) ?? proposal, nested);
+const targets = (proposal: UlwLoopSteeringProposal): string[] => proposal.targetGoalIds ?? [proposal.targetGoalId ?? text(proposal, "goalId") ?? ""].filter(Boolean);
+const child = (value: unknown): UlwLoopSteeringChildGoal | null => {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+	const title = text(value, "title"); const objective = text(value, "objective");
+	return title === undefined || objective === undefined ? null : { title, objective };
+};
+const children = (proposal: UlwLoopSteeringProposal): UlwLoopSteeringChildGoal[] => {
+	const direct = proposal.childGoals;
+	if (direct !== undefined && direct.length > 0) return direct;
+	const nested = after(proposal);
+	const fromAfter = nested === undefined ? undefined : read(nested, "children");
+	return Array.isArray(fromAfter) ? fromAfter.map(child).filter((item): item is UlwLoopSteeringChildGoal => item !== null) : [];
+};
+const goal = (plan: UlwLoopPlan, id: string | undefined): UlwLoopItem | undefined => id === undefined ? undefined : plan.goals.find((item) => item.id === id);
+
+function nextId(plan: UlwLoopPlan, offset: number): string {
+	const max = plan.goals.reduce((current, item) => { const digits = /^G(\d+)(?:-|$)/u.exec(item.id)?.[1]; return digits === undefined ? current : Math.max(current, Number(digits)); }, 0);
+	return `G${String(max + offset).padStart(3, "0")}`;
+}
+
+export function makeGoal(plan: UlwLoopPlan, childGoal: UlwLoopSteeringChildGoal, evidence: string, now: string, offset: number): UlwLoopItem {
+	const id = nextId(plan, offset); const digits = /^G(\d+)/u.exec(id)?.[1]; const goalIndex = digits === undefined ? plan.goals.length + offset - 1 : Number(digits) - 1;
+	return { id, title: childGoal.title, objective: childGoal.objective, status: "pending", successCriteria: seedDefaultSuccessCriteria(goalIndex, childGoal.objective), attempt: 0, createdAt: now, updatedAt: now, evidence };
+}
+
+export function reviseWording(plan: UlwLoopPlan, proposal: UlwLoopSteeringProposal, now: string): void {
+	const target = goal(plan, targets(proposal)[0]); if (target === undefined) return;
+	target.title = revised(proposal, "revisedTitle", "title") ?? target.title; target.objective = revised(proposal, "revisedObjective", "objective") ?? target.objective;
+	target.steeringEvidence = proposal.evidence; target.steeringRationale = proposal.rationale; target.updatedAt = now;
+}
+
+export function splitOrBlock(plan: UlwLoopPlan, proposal: UlwLoopSteeringProposal, now: string): void {
+	const target = goal(plan, targets(proposal)[0]); if (target === undefined) return;
+	const replacements = children(proposal).map((item, index) => makeGoal(plan, item, proposal.evidence, now, index + 1));
+	target.steeringEvidence = proposal.evidence; target.steeringRationale = proposal.rationale; target.updatedAt = now;
+	if (replacements.length === 0) { target.status = "blocked"; target.steeringStatus = "blocked"; target.blockedReason = proposal.blockedReason ?? proposal.rationale; }
+	else { target.steeringStatus = "superseded"; target.supersededBy = replacements.map((item) => item.id); for (const item of replacements) item.supersedes = [target.id]; plan.goals.splice(plan.goals.indexOf(target) + 1, 0, ...replacements); updateBatchesAfterSupersede(plan, target.id, replacements.map((item) => item.id)); }
+	if (plan.activeGoalId === target.id) delete plan.activeGoalId;
+}
+
+export function reviseCriterion(plan: UlwLoopPlan, proposal: UlwLoopSteeringProposal, now: string): void {
+	const target = goal(plan, targets(proposal)[0]); const index = target?.successCriteria.findIndex((item) => item.id === proposal.criterionId) ?? -1; const current = target?.successCriteria[index];
+	if (target === undefined || current === undefined) return;
+	const model = read(proposal, "userModel");
+	target.successCriteria[index] = { ...current, scenario: text(proposal, "scenario") ?? current.scenario, expectedEvidence: text(proposal, "expectedEvidence") ?? current.expectedEvidence, userModel: isModel(model) ? model : current.userModel };
+	target.updatedAt = now;
+}

package/packages/omo-codex/plugin/components/ulw-loop/src/steering.ts

@@ -1,8 +1,8 @@
 // biome-ignore-all format: compact steering module must stay below the 240 pure-LOC budget
 import { isUlwLoopDone } from "./goal-status.js";
 import type { UlwLoopScope } from "./paths.js";
-import { seedDefaultSuccessCriteria } from "./plan-crud.js";
 import { appendLedger, findAcceptedSteeringLedgerEntry, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
+import { makeGoal, reviseCriterion, reviseWording, splitOrBlock } from "./steering-mutations.js";
 import { buildSteeringPlanSnapshot, changedGoalIdsBetween } from "./steering-snapshot.js";
 import type {
 	SteerUlwLoopResult,
@@ -17,6 +17,7 @@ import type {
 	UlwLoopSuccessCriterionUserModel,
 } from "./types.js";
 import { iso, ULW_LOOP_STEERING_MUTATION_KINDS, ULW_LOOP_SUCCESS_CRITERION_USER_MODELS } from "./types.js";
+import { batchUpdateLedgerEntry } from "./validation-batch.js";
 
 const SOURCES = ["user_prompt_submit", "finding", "cli"] as const satisfies readonly UlwLoopSteeringSource[];
 const PROTECTED = new Set(["aggregateCompletion", "codexObjective", "codexObjectiveAliases", "originalConstraints", "qualityGate", "status", "completedAt", "completionStatus"]);
@@ -63,7 +64,6 @@ function childValues(proposal: object): unknown[] {
 	return Array.isArray(fromAfter) ? fromAfter : [];
 }
 
-const children = (proposal: object): UlwLoopSteeringChildGoal[] => childValues(proposal).map(child).filter((item): item is UlwLoopSteeringChildGoal => item !== null);
 const pendingOrder = (proposal: object): string[] => {
 	const direct = texts(proposal, "pendingOrder");
 	return direct.length > 0 ? direct : texts(after(proposal) ?? proposal, "pendingGoalIds");
@@ -155,21 +155,6 @@ function validateCriterion(plan: UlwLoopPlan, proposal: object, reasons: string[
 	if (model !== undefined && !isModel(model)) reasons.push("invalid userModel");
 }
 
-function nextId(plan: UlwLoopPlan, offset: number): string {
-	const max = plan.goals.reduce((current, item) => {
-		const digits = /^G(\d+)(?:-|$)/u.exec(item.id)?.[1];
-		return digits === undefined ? current : Math.max(current, Number(digits));
-	}, 0);
-	return `G${String(max + offset).padStart(3, "0")}`;
-}
-
-function makeGoal(plan: UlwLoopPlan, childGoal: UlwLoopSteeringChildGoal, evidence: string, now: string, offset: number): UlwLoopItem {
-	const id = nextId(plan, offset);
-	const digits = /^G(\d+)/u.exec(id)?.[1];
-	const goalIndex = digits === undefined ? plan.goals.length + offset - 1 : Number(digits) - 1;
-	return { id, title: childGoal.title, objective: childGoal.objective, status: "pending", successCriteria: seedDefaultSuccessCriteria(goalIndex, childGoal.objective), attempt: 0, createdAt: now, updatedAt: now, evidence };
-}
-
 export function applySteeringMutation(plan: UlwLoopPlan, proposal: UlwLoopSteeringProposal, audit: UlwLoopSteeringAudit): UlwLoopPlan {
 	const next = structuredClone(plan);
 	if (!audit.invariant.accepted) return next;
@@ -186,46 +171,6 @@ export function applySteeringMutation(plan: UlwLoopPlan, proposal: UlwLoopSteeri
 	return next;
 }
 
-function reviseWording(plan: UlwLoopPlan, proposal: UlwLoopSteeringProposal, now: string): void {
-	const target = goal(plan, targets(proposal)[0]);
-	if (target === undefined) return;
-	target.title = revised(proposal, "revisedTitle", "title") ?? target.title;
-	target.objective = revised(proposal, "revisedObjective", "objective") ?? target.objective;
-	target.steeringEvidence = proposal.evidence;
-	target.steeringRationale = proposal.rationale;
-	target.updatedAt = now;
-}
-
-function splitOrBlock(plan: UlwLoopPlan, proposal: UlwLoopSteeringProposal, now: string): void {
-	const target = goal(plan, targets(proposal)[0]);
-	if (target === undefined) return;
-	const replacements = children(proposal).map((item, index) => makeGoal(plan, item, proposal.evidence, now, index + 1));
-	target.steeringEvidence = proposal.evidence;
-	target.steeringRationale = proposal.rationale;
-	target.updatedAt = now;
-	if (replacements.length === 0) {
-		target.status = "blocked";
-		target.steeringStatus = "blocked";
-		target.blockedReason = proposal.blockedReason ?? proposal.rationale;
-	} else {
-		target.steeringStatus = "superseded";
-		target.supersededBy = replacements.map((item) => item.id);
-		for (const item of replacements) item.supersedes = [target.id];
-		plan.goals.splice(plan.goals.indexOf(target) + 1, 0, ...replacements);
-	}
-	if (plan.activeGoalId === target.id) delete plan.activeGoalId;
-}
-
-function reviseCriterion(plan: UlwLoopPlan, proposal: UlwLoopSteeringProposal, now: string): void {
-	const target = goal(plan, targets(proposal)[0]);
-	const index = target?.successCriteria.findIndex((item) => item.id === proposal.criterionId) ?? -1;
-	const current = target?.successCriteria[index];
-	if (target === undefined || current === undefined) return;
-	const model = read(proposal, "userModel");
-	target.successCriteria[index] = { ...current, scenario: text(proposal, "scenario") ?? current.scenario, expectedEvidence: text(proposal, "expectedEvidence") ?? current.expectedEvidence, userModel: isModel(model) ? model : current.userModel };
-	target.updatedAt = now;
-}
-
 function isProposal(value: unknown): value is UlwLoopSteeringProposal {
 	return isPlain(value) && isKind(read(value, "kind")) && isSource(read(value, "source")) && isText(read(value, "evidence")) && isText(read(value, "rationale"));
 }
@@ -262,8 +207,11 @@ export async function steerUlwLoop(repoRoot: string, proposal: UlwLoopSteeringPr
 			finalAudit.before = buildSteeringPlanSnapshot(plan, changed);
 			finalAudit.after = buildSteeringPlanSnapshot(next, changed);
 		}
+		const at = proposal.now?.toISOString() ?? iso();
+		const batchEntry = accepted ? batchUpdateLedgerEntry(plan, next, at) : null;
 		if (accepted) await writePlan(repoRoot, next, scope);
-		await appendLedger(repoRoot, ledgerEntry(proposal, finalAudit, proposal.now?.toISOString() ?? iso()), scope);
+		await appendLedger(repoRoot, ledgerEntry(proposal, finalAudit, at), scope);
+		if (batchEntry !== null) await appendLedger(repoRoot, batchEntry, scope);
 		return { plan: next, accepted, audit: finalAudit, rejectedReasons: audit.invariant.rejectedReasons, deduped: false };
 	});
 }

package/packages/omo-codex/plugin/components/ulw-loop/src/stop-resume-hook.ts

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { isAbsolute, join } from "node:path";
+import { isAbsolute, join, resolve, sep } from "node:path";
 
 import { normalizeUlwLoopSessionId, ulwLoopDir } from "./paths.js";
 import type { UlwLoopItem, UlwLoopPlan } from "./types.js";
@@ -73,17 +73,25 @@ function isResumableStatus(status: UlwLoopItem["status"]): boolean {
 // a separate file — a ledger append would change the count and self-reset.
 function consumeResumeBudget(stateDir: string, goalId: string): boolean {
 	const ledgerLineCount = countLedgerLines(join(stateDir, "ledger.jsonl"));
-	const counterPath = join(stateDir, `auto-resume-${goalId}.json`);
+	const counterPath = resolve(stateDir, `auto-resume-${goalId}.json`);
+	const stuckPath = resolve(stateDir, `auto-resume-${goalId}.stuck`);
+	// goals.json is untrusted input: a crafted goal id (e.g. `../../x`) must
+	// never drive a write outside the session state dir. Deny the resume.
+	if (!isInsideDir(stateDir, counterPath) || !isInsideDir(stateDir, stuckPath)) return false;
 	const previous = readCounter(counterPath);
 	const count = previous !== null && previous.ledgerLineCount === ledgerLineCount ? previous.count : 0;
 	if (count >= RESUME_CAP) {
-		writeFileSync(join(stateDir, `auto-resume-${goalId}.stuck`), `no ledger progress after ${count} resumes\n`);
+		writeFileSync(stuckPath, `no ledger progress after ${count} resumes\n`);
 		return false;
 	}
 	writeFileSync(counterPath, JSON.stringify({ count: count + 1, ledgerLineCount }));
 	return true;
 }
 
+function isInsideDir(dir: string, candidate: string): boolean {
+	return candidate.startsWith(resolve(dir) + sep);
+}
+
 function renderResumeDirective(plan: UlwLoopPlan, goal: UlwLoopItem, sessionId: string): string {
 	const normalized = normalizeUlwLoopSessionId(sessionId);
 	const option =
@@ -93,7 +101,7 @@ function renderResumeDirective(plan: UlwLoopPlan, goal: UlwLoopItem, sessionId:
 		"The turn ended before the loop completed. Resume it now:",
 		`1. Run \`omo ulw-loop status${option} --json\` to reload the plan, the active goal, and currentAttemptDir.`,
 		"2. Continue the active goal's remaining success criteria, recording evidence with record-evidence.",
-		`3. Checkpoint through \`omo ulw-loop checkpoint${option}\` when the goal's criteria are proven.`,
+		`3. Checkpoint through \`omo ulw-loop checkpoint${option}\` when the goal's criteria are proven; a complete checkpoint prints the next goal instruction.`,
 		"If the loop is genuinely blocked on the user, checkpoint the goal as blocked with the reason instead.",
 	].join("\n");
 }

package/packages/omo-codex/plugin/components/ulw-loop/src/validation-batch.ts

@@ -0,0 +1,122 @@
+// biome-ignore-all format: compact validation-batch helpers stay below the pure LOC budget.
+import { readJsonInput } from "./cli-arg-parser.js";
+import { isMemberResolved } from "./goal-status.js";
+import type { UlwLoopItem, UlwLoopLedgerEntry, UlwLoopPlan, UlwLoopQualityGate, UlwLoopValidationBatch } from "./types.js";
+import { UlwLoopError } from "./types.js";
+
+function isObject(value: unknown): value is object {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function read(value: object, key: string): unknown {
+	return Object.entries(value).find(([name]) => name === key)?.[1];
+}
+
+function text(value: object, key: string): string | undefined {
+	const candidate = read(value, key);
+	return typeof candidate === "string" && candidate.trim().length > 0 ? candidate.trim() : undefined;
+}
+
+function strings(value: object, key: string): readonly string[] | undefined {
+	const candidate = read(value, key);
+	return Array.isArray(candidate) && candidate.every((item) => typeof item === "string" && item.trim().length > 0)
+		? candidate.map((item) => item.trim())
+		: undefined;
+}
+
+export async function parseValidationBatches(
+	input: string | undefined,
+	goals: readonly UlwLoopItem[],
+): Promise<readonly UlwLoopValidationBatch[] | undefined> {
+	const raw = await readJsonInput(input);
+	if (raw === undefined) return undefined;
+	if (!Array.isArray(raw)) fail("--validation-batch-json must be a JSON array.");
+	const batches = raw.map(batchFromObject);
+	validateBatches(batches, goals);
+	return batches;
+}
+
+function batchFromObject(value: unknown): UlwLoopValidationBatch {
+	if (!isObject(value)) fail("validation batch entries must be objects.");
+	const batchId = text(value, "batchId");
+	const memberIds = strings(value, "memberIds");
+	const finalGoalId = text(value, "finalGoalId");
+	if (batchId === undefined) fail("validation batch requires batchId.");
+	if (memberIds === undefined || memberIds.length < 2) fail("validation batch requires at least two memberIds.");
+	if (finalGoalId === undefined) fail("validation batch requires finalGoalId.");
+	return { batchId, memberIds, finalGoalId };
+}
+
+function validateBatches(batches: readonly UlwLoopValidationBatch[], goals: readonly UlwLoopItem[]): void {
+	const goalIds = new Set(goals.map((goal) => goal.id));
+	const batchIds = new Set<string>();
+	const members = new Set<string>();
+	for (const batch of batches) {
+		if (batchIds.has(batch.batchId)) fail(`duplicate validation batch id: ${batch.batchId}.`);
+		batchIds.add(batch.batchId);
+		if (new Set(batch.memberIds).size !== batch.memberIds.length) fail(`validation batch ${batch.batchId} has duplicate memberIds.`);
+		if (!batch.memberIds.includes(batch.finalGoalId)) fail(`validation batch ${batch.batchId} finalGoalId must be a member.`, "ULW_LOOP_VALIDATION_BATCH_FINAL_NOT_MEMBER");
+		for (const memberId of batch.memberIds) {
+			if (!goalIds.has(memberId)) fail(`validation batch ${batch.batchId} references unknown goal: ${memberId}.`, "ULW_LOOP_VALIDATION_BATCH_MEMBER_UNKNOWN");
+			if (members.has(memberId)) fail(`goal appears in multiple validation batches: ${memberId}.`, "ULW_LOOP_VALIDATION_BATCH_OVERLAP");
+			members.add(memberId);
+		}
+	}
+}
+
+export function updateBatchesAfterSupersede(plan: UlwLoopPlan, targetId: string, replacementIds: readonly string[]): void {
+	if (replacementIds.length === 0 || plan.validationBatches === undefined) return;
+	plan.validationBatches = plan.validationBatches.map((batch) => {
+		if (!batch.memberIds.includes(targetId)) return batch;
+		const memberIds = batch.memberIds.flatMap((id) => (id === targetId ? [...replacementIds] : [id]));
+		const replacementFinalGoalId = replacementIds[replacementIds.length - 1] ?? batch.finalGoalId;
+		const finalGoalId = batch.finalGoalId === targetId ? replacementFinalGoalId : batch.finalGoalId;
+		return { batchId: batch.batchId, memberIds, finalGoalId };
+	});
+}
+
+export function batchUpdateLedgerEntry(before: UlwLoopPlan, after: UlwLoopPlan, at: string): UlwLoopLedgerEntry | null {
+	if (JSON.stringify(before.validationBatches ?? []) === JSON.stringify(after.validationBatches ?? [])) return null;
+	return { at, kind: "batch_updated", before: before.validationBatches ?? [], after: after.validationBatches ?? [], message: "Validation batch membership updated after steering." };
+}
+
+export function batchOf(plan: UlwLoopPlan, goalId: string): UlwLoopValidationBatch | undefined {
+	return plan.validationBatches?.find((batch) => batch.memberIds.includes(goalId));
+}
+
+export function batchClosedBy(plan: UlwLoopPlan, goalId: string): UlwLoopValidationBatch | undefined {
+	const batch = batchOf(plan, goalId);
+	return batch?.finalGoalId === goalId ? batch : undefined;
+}
+
+export function requireBatchFinalReady(plan: UlwLoopPlan, goal: UlwLoopItem): void {
+	const batch = batchClosedBy(plan, goal.id);
+	if (batch === undefined) return;
+	const open = batch.memberIds.filter((id) => id !== goal.id && !memberResolved(plan, id));
+	if (open.length > 0) throw new UlwLoopError("Validation batch has unresolved members.", "ULW_LOOP_VALIDATION_BATCH_OPEN", { details: { batchId: batch.batchId, open } });
+}
+
+export function requireAllValidationBatchesClosed(plan: UlwLoopPlan, closingGoalId?: string): void {
+	const open = (plan.validationBatches ?? []).filter((batch) => batch.memberIds.some((id) => id !== closingGoalId && !memberResolved(plan, id)));
+	if (open.length > 0) throw new UlwLoopError("Validation batches remain open.", "ULW_LOOP_VALIDATION_BATCH_OPEN", { details: { batchIds: open.map((batch) => batch.batchId) } });
+}
+
+export function requireBatchGate(plan: UlwLoopPlan, goal: UlwLoopItem, gate: UlwLoopQualityGate): void {
+	const batch = batchClosedBy(plan, goal.id);
+	if (batch === undefined) return;
+	const members = batch.memberIds.map((id) => plan.goals.find((item) => item.id === id)).filter((item): item is UlwLoopItem => item !== undefined);
+	const pending = members.flatMap((member) => member.successCriteria.filter((criterion) => criterion.status !== "pass").map((criterion) => `${member.id}:${criterion.id}`));
+	if (pending.length > 0) throw new UlwLoopError("Validation batch criteria remain pending.", "ULW_LOOP_VALIDATION_BATCH_CRITERIA_PENDING", { details: { batchId: batch.batchId, pending } });
+	const totalCriteria = members.reduce((sum, member) => sum + member.successCriteria.length, 0);
+	const passCount = members.reduce((sum, member) => sum + member.successCriteria.filter((criterion) => criterion.status === "pass").length, 0);
+	if (gate.criteriaCoverage.totalCriteria !== totalCriteria || gate.criteriaCoverage.passCount !== passCount) throw new UlwLoopError("Validation batch gate coverage does not match member criteria.", "ULW_LOOP_VALIDATION_BATCH_GATE_MISMATCH", { details: { batchId: batch.batchId, expected: { totalCriteria, passCount }, actual: gate.criteriaCoverage } });
+}
+
+function memberResolved(plan: UlwLoopPlan, goalId: string): boolean {
+	const goal = plan.goals.find((candidate) => candidate.id === goalId);
+	return goal !== undefined && isMemberResolved(goal, plan);
+}
+
+function fail(message: string, code = "ULW_LOOP_VALIDATION_BATCH_INVALID"): never {
+	throw new UlwLoopError(message, code);
+}

package/packages/omo-codex/plugin/components/ulw-loop/test/checkpoint-continuation.test.ts

@@ -0,0 +1,76 @@
+// biome-ignore-all format: compact continuation tests stay under the pure LOC budget.
+import { rm } from "node:fs/promises";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { checkpointAndContinue } from "../src/checkpoint-continuation.js";
+import { readUlwLoopPlan } from "../src/plan-io.js";
+import { goal, plan, repoWith, snapshot } from "./fixtures/checkpoint-builders.js";
+
+let repo: string | undefined;
+
+afterEach(async () => {
+	if (repo !== undefined) await rm(repo, { recursive: true, force: true });
+	repo = undefined;
+});
+
+describe("checkpointAndContinue", () => {
+	it("#given a completed non-final goal #when advance is enabled #then starts the next pending goal", async () => {
+		repo = await repoWith(
+			plan([
+				goal({ id: "G001", status: "in_progress" }),
+				goal({ id: "G002", status: "pending", attempt: 0 }),
+			]),
+		);
+
+		const result = await checkpointAndContinue(repo, {
+			goalId: "G001",
+			status: "complete",
+			evidence: "implementation done and validation passed",
+			codexGoalJson: snapshot("active"),
+			advance: true,
+		});
+
+		expect(result.next).toMatchObject({ resumed: false, goal: { id: "G002", status: "in_progress" } });
+		expect(result.next && "instruction" in result.next ? result.next.instruction.text : "").toContain("Goal: G002");
+		expect((await readUlwLoopPlan(repo)).activeGoalId).toBe("G002");
+	});
+
+	it("#given advance disabled #when a non-final goal completes #then preserves the old two-call state", async () => {
+		repo = await repoWith(
+			plan([
+				goal({ id: "G001", status: "in_progress" }),
+				goal({ id: "G002", status: "pending", attempt: 0 }),
+			]),
+		);
+
+		const result = await checkpointAndContinue(repo, {
+			goalId: "G001",
+			status: "complete",
+			evidence: "implementation done and validation passed",
+			codexGoalJson: snapshot("active"),
+			advance: false,
+		});
+
+		expect(result.next).toBeUndefined();
+		expect((await readUlwLoopPlan(repo)).activeGoalId).toBeUndefined();
+	});
+
+	it("#given a failed checkpoint #when advance is enabled #then it does not start the next goal", async () => {
+		repo = await repoWith(
+			plan([
+				goal({ id: "G001", status: "in_progress" }),
+				goal({ id: "G002", status: "pending", attempt: 0 }),
+			]),
+		);
+
+		const result = await checkpointAndContinue(repo, {
+			goalId: "G001",
+			status: "failed",
+			evidence: "implementation failed and validation captured",
+			advance: true,
+		});
+
+		expect(result.next).toBeUndefined();
+		expect((await readUlwLoopPlan(repo)).activeGoalId).toBeUndefined();
+	});
+});

package/packages/omo-codex/plugin/components/ulw-loop/test/cli-checkpoint-continuation.test.ts

@@ -0,0 +1,111 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { ulwLoopCommand } from "../src/cli-commands.js";
+import { ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE } from "../src/goal-status.js";
+
+let testDir: string;
+let out: string[];
+let originalOmoSessionId: string | undefined;
+
+beforeEach(async () => {
+	testDir = await mkdtemp(join(tmpdir(), "ug-cli-checkpoint-next-"));
+	out = [];
+	originalOmoSessionId = process.env["OMO_ULW_LOOP_SESSION_ID"];
+	delete process.env["OMO_ULW_LOOP_SESSION_ID"];
+	vi.spyOn(process, "cwd").mockReturnValue(testDir);
+	vi.spyOn(process.stdout, "write").mockImplementation((chunk: string | Uint8Array): boolean => {
+		out.push(chunk.toString());
+		return true;
+	});
+	vi.spyOn(process.stderr, "write").mockImplementation((): boolean => true);
+});
+
+afterEach(async () => {
+	vi.restoreAllMocks();
+	if (originalOmoSessionId === undefined) delete process.env["OMO_ULW_LOOP_SESSION_ID"];
+	else process.env["OMO_ULW_LOOP_SESSION_ID"] = originalOmoSessionId;
+	await rm(testDir, { recursive: true, force: true });
+});
+
+function resetOutput(): void {
+	out = [];
+}
+
+function stdoutJson(): Record<string, unknown> {
+	return JSON.parse(out.join(""));
+}
+
+function codexSnapshot(): string {
+	return JSON.stringify({ goal: { objective: ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE, status: "active" } });
+}
+
+async function passCriterion(criterionId: string): Promise<void> {
+	expect(
+		await ulwLoopCommand([
+			"record-evidence",
+			"--goal-id",
+			"G001-goal-a",
+			"--criterion-id",
+			criterionId,
+			"--status",
+			"pass",
+			"--evidence",
+			`${criterionId} observable proof`,
+		]),
+	).toBe(0);
+	resetOutput();
+}
+
+describe("ulwLoopCommand checkpoint continuation", () => {
+	it("#given another pending goal #when checkpoint completes #then JSON includes the next goal", async () => {
+		expect(await ulwLoopCommand(["create-goals", "--brief", "- Goal A\n- Goal B", "--json"])).toBe(0);
+		resetOutput();
+		await passCriterion("C001");
+		await passCriterion("C002");
+
+		expect(
+			await ulwLoopCommand([
+				"checkpoint",
+				"--goal-id",
+				"G001-goal-a",
+				"--status",
+				"complete",
+				"--evidence",
+				"implementation done and validation passed",
+				"--codex-goal-json",
+				codexSnapshot(),
+				"--json",
+			]),
+		).toBe(0);
+		expect(stdoutJson()).toMatchObject({
+			next: { resumed: false, goal: { id: "G002-goal-b", status: "in_progress" } },
+		});
+	});
+
+	it("#given no-advance #when checkpoint completes #then JSON omits next", async () => {
+		expect(await ulwLoopCommand(["create-goals", "--brief", "- Goal A\n- Goal B", "--json"])).toBe(0);
+		resetOutput();
+		await passCriterion("C001");
+		await passCriterion("C002");
+
+		expect(
+			await ulwLoopCommand([
+				"checkpoint",
+				"--goal-id",
+				"G001-goal-a",
+				"--status",
+				"complete",
+				"--evidence",
+				"implementation done and validation passed",
+				"--codex-goal-json",
+				codexSnapshot(),
+				"--no-advance",
+				"--json",
+			]),
+		).toBe(0);
+		expect(stdoutJson()).not.toHaveProperty("next");
+	});
+});