oh-my-opencode 5.0.0-beta.5 → 5.0.0-beta.50

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

@@ -0,0 +1,239 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { dirname } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+
+import { UlwLoopError } from "./types.js";
+
+// Cross-process exclusive lock for one ulw-loop state directory. Every CLI
+// invocation is its own process, so the in-process promise chain in plan-io
+// serializes nothing across them; this file-level lock is what makes the
+// read-modify-write of goals.json (and the counters next to it) atomic.
+//
+// Protocol: the lock is a file created with O_EXCL whose body records the
+// owner (pid + a per-acquisition token). A waiter reclaims it only when the
+// owner is provably gone (pid dead) or the body never became a record within
+// `staleMs` (a creator that died mid-write); a live owner is never reclaimed by
+// age alone, because overlapping two bodies is exactly the lost update this lock
+// exists to prevent. Waiters back off and fail closed at `timeoutMs`. Release
+// unlinks only a lock that still carries the releaser's own token.
+
+export const ULW_LOOP_LOCK_TIMEOUT_CODE = "ULW_LOOP_LOCK_TIMEOUT";
+
+export interface StateLockOptions {
+	readonly timeoutMs?: number;
+	readonly staleMs?: number;
+}
+
+interface LockRecord {
+	readonly pid: number;
+	readonly createdAt: string;
+	readonly token: string;
+}
+
+interface LockSnapshot {
+	readonly raw: string;
+	readonly record: LockRecord | null;
+	readonly ageMs: number;
+}
+
+type AttemptOutcome = { readonly kind: "acquired"; readonly token: string } | { readonly kind: "retry" | "wait" };
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_STALE_MS = 60_000;
+const MIN_DELAY_MS = 5;
+const MAX_DELAY_MS = 100;
+const SLEEP_CELL = new Int32Array(new SharedArrayBuffer(4));
+
+export async function withStateLock<T>(
+	lockPath: string,
+	fn: () => Promise<T>,
+	options: StateLockOptions = {},
+): Promise<T> {
+	const token = await acquireAsync(lockPath, options);
+	try {
+		return await fn();
+	} finally {
+		release(lockPath, token);
+	}
+}
+
+export function withStateLockSync<T>(lockPath: string, fn: () => T, options: StateLockOptions = {}): T {
+	const token = acquireSync(lockPath, options);
+	try {
+		return fn();
+	} finally {
+		release(lockPath, token);
+	}
+}
+
+export function isStateLockTimeout(error: unknown): error is UlwLoopError {
+	return error instanceof UlwLoopError && error.code === ULW_LOOP_LOCK_TIMEOUT_CODE;
+}
+
+async function acquireAsync(lockPath: string, options: StateLockOptions): Promise<string> {
+	const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+	const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+	mkdirSync(dirname(lockPath), { recursive: true });
+	for (let attempt = 0; ; ) {
+		const outcome = attemptOnce(lockPath, staleMs);
+		if (outcome.kind === "acquired") return outcome.token;
+		if (outcome.kind === "retry") continue;
+		if (Date.now() >= deadline) throw lockTimeout(lockPath, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+		await sleep(backoffMs(attempt));
+		attempt += 1;
+	}
+}
+
+function acquireSync(lockPath: string, options: StateLockOptions): string {
+	const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+	const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+	mkdirSync(dirname(lockPath), { recursive: true });
+	for (let attempt = 0; ; ) {
+		const outcome = attemptOnce(lockPath, staleMs);
+		if (outcome.kind === "acquired") return outcome.token;
+		if (outcome.kind === "retry") continue;
+		if (Date.now() >= deadline) throw lockTimeout(lockPath, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+		Atomics.wait(SLEEP_CELL, 0, 0, backoffMs(attempt));
+		attempt += 1;
+	}
+}
+
+// EINTR surfaces raw from macOS fs syscalls under some runtimes; it is a retry, never a verdict.
+function attemptOnce(lockPath: string, staleMs: number): AttemptOutcome {
+	try {
+		const token = tryCreate(lockPath);
+		if (token !== null) return { kind: "acquired", token };
+		const snapshot = readSnapshot(lockPath);
+		if (snapshot === null) return { kind: "retry" };
+		if (isStale(snapshot, staleMs) && reclaim(lockPath, snapshot.raw)) return { kind: "retry" };
+		return { kind: "wait" };
+	} catch (error) {
+		if (hasCode(error, "EINTR")) return { kind: "wait" };
+		throw error;
+	}
+}
+
+function tryCreate(lockPath: string): string | null {
+	let fd: number;
+	try {
+		fd = openSync(lockPath, "wx");
+	} catch (error) {
+		if (hasCode(error, "EEXIST")) return null;
+		throw error;
+	}
+	const record: LockRecord = { pid: process.pid, createdAt: new Date().toISOString(), token: randomUUID() };
+	try {
+		writeSync(fd, JSON.stringify(record));
+	} catch (error) {
+		closeSync(fd);
+		// A failed write (e.g. EINTR) must not leave a partial lock the owner never recorded;
+		// otherwise later readers see a young ownerless lock and only age can retire it.
+		try {
+			unlinkSync(lockPath);
+		} catch {
+			// another process already reclaimed the partial file; leave it alone
+		}
+		throw error;
+	}
+	closeSync(fd);
+	return record.token;
+}
+
+function readSnapshot(lockPath: string): LockSnapshot | null {
+	try {
+		const raw = readFileSync(lockPath, "utf8");
+		const ageMs = Date.now() - statSync(lockPath).mtimeMs;
+		return { raw, record: parseRecord(raw), ageMs };
+	} catch (error) {
+		if (hasCode(error, "ENOENT")) return null;
+		throw error;
+	}
+}
+
+function parseRecord(raw: string): LockRecord | null {
+	try {
+		const parsed: unknown = JSON.parse(raw);
+		if (typeof parsed !== "object" || parsed === null) return null;
+		const record = parsed as Record<string, unknown>;
+		const pid = record["pid"];
+		const createdAt = record["createdAt"];
+		const token = record["token"];
+		if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0 || typeof createdAt !== "string") return null;
+		if (typeof token !== "string" || token.length === 0) return null;
+		return { pid, createdAt, token };
+	} catch (error) {
+		if (error instanceof SyntaxError) return null;
+		throw error;
+	}
+}
+
+// A body that is not a record is a lock mid-write (or a foreign/legacy file); only
+// age retires it. A parsable record is stale only when its owner is dead: a live
+// owner running past staleMs is slow, not gone, and the waiter fails closed instead.
+function isStale(snapshot: LockSnapshot, staleMs: number): boolean {
+	if (snapshot.record === null) return snapshot.ageMs > staleMs;
+	return !isProcessAlive(snapshot.record.pid);
+}
+
+function isProcessAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		if (hasCode(error, "ESRCH")) return false;
+		if (hasCode(error, "EPERM")) return true;
+		throw error;
+	}
+}
+
+// Re-read right before unlinking so a lock that changed hands since the stale
+// verdict (a sibling waiter reclaimed and re-acquired it) is left alone.
+function reclaim(lockPath: string, expectedRaw: string): boolean {
+	const current = readSnapshot(lockPath);
+	if (current === null) return true;
+	if (current.raw !== expectedRaw) return false;
+	try {
+		unlinkSync(lockPath);
+	} catch (error) {
+		if (!hasCode(error, "ENOENT")) throw error;
+	}
+	return true;
+}
+
+// Only the acquisition that wrote this token may unlink: if the file now carries
+// another token, a waiter has legitimately taken over and its lock must stand.
+function release(lockPath: string, token: string): void {
+	const current = readSnapshot(lockPath);
+	if (current === null || current.record?.token !== token) return;
+	try {
+		unlinkSync(lockPath);
+	} catch (error) {
+		if (!hasCode(error, "ENOENT")) throw error;
+	}
+}
+
+function backoffMs(attempt: number): number {
+	const exponential = Math.min(MAX_DELAY_MS, MIN_DELAY_MS * 2 ** attempt);
+	return exponential + Math.random() * MIN_DELAY_MS;
+}
+
+function lockTimeout(lockPath: string, timeoutMs: number): UlwLoopError {
+	const holder = readSnapshot(lockPath)?.record;
+	const owner = holder === undefined || holder === null ? "another process" : `pid ${holder.pid}`;
+	return new UlwLoopError(
+		`ulw-loop state lock ${lockPath} is held by ${owner} for more than ${timeoutMs}ms; retry once that process finishes, or delete the lock file if that process is gone.`,
+		ULW_LOOP_LOCK_TIMEOUT_CODE,
+		{
+			details: {
+				lockPath,
+				timeoutMs,
+				...(holder === undefined || holder === null ? {} : { holderPid: holder.pid }),
+			},
+		},
+	);
+}
+
+function hasCode(error: unknown, code: string): boolean {
+	return error instanceof Error && "code" in error && error.code === code;
+}

package/packages/omo-codex/plugin/components/ulw-loop/src/status-next-actions.ts

@@ -0,0 +1,36 @@
+import { hasAllCriteriaPass, isFinalRunCompletionCandidate } from "./goal-status.js";
+import { ULW_LOOP_CREATE_GOALS_COMMAND } from "./plan-missing-recovery.js";
+import type { UlwLoopItem, UlwLoopPlan } from "./types.js";
+
+/**
+ * `status --json` is the one call every agent already makes between steps, so it is
+ * also the cheapest place to answer "what now?" without a second round trip.
+ */
+export function statusNextActions(plan: UlwLoopPlan): readonly string[] {
+	const actions: string[] = [];
+	const active = plan.goals.find((goal) => goal.id === plan.activeGoalId);
+	if (plan.goals.length === 0) actions.push(`No goals yet: bootstrap with \`${ULW_LOOP_CREATE_GOALS_COMMAND}\`.`);
+	else if (active !== undefined) actions.push(...activeGoalActions(plan, active));
+	for (const goal of plan.goals.filter((candidate) => candidate.status === "review_blocked"))
+		actions.push(
+			`${goal.id} is review_blocked: capture the reviewer verdict with \`omo-agent-toolkit ulw-loop record-review-blockers --goal-id ${goal.id} --title "<title>" --objective "<objective>" --evidence "<verdict>" --codex-goal-json '<get_goal json>'\`.`,
+		);
+	if (plan.evidenceLayoutVersion !== 2 || active === undefined)
+		actions.push("plan is evidence-layout v1; artifacts go under .omo/evidence/");
+	return actions;
+}
+
+function activeGoalActions(plan: UlwLoopPlan, active: UlwLoopItem): readonly string[] {
+	const unresolved = active.successCriteria.filter((criterion) => criterion.status !== "pass");
+	if (unresolved.length > 0)
+		return [
+			`${active.id} has ${unresolved.length} unresolved criterion(s) (${unresolved.map((criterion) => criterion.id).join(", ")}): record proof with \`omo-agent-toolkit ulw-loop record-evidence --goal-id ${active.id} --criterion-id <id> --status pass --evidence "<observable proof>"\`.`,
+		];
+	if (hasAllCriteriaPass(active) && isFinalRunCompletionCandidate(plan, active))
+		return [
+			`${active.id} passes every criterion and is the final story: update_goal complete, then checkpoint --print-template to build the final quality gate. Use status --json's currentAttemptDir for all quality-gate artifacts.`,
+		];
+	return [
+		`${active.id} passes every criterion: close it with \`omo-agent-toolkit ulw-loop checkpoint --goal-id ${active.id} --status complete --evidence "<proof>" --codex-goal-json '<get_goal json>'\`. Put quality-gate artifacts under the currentAttemptDir shown by status --json.`,
+	];
+}

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

@@ -1,7 +1,8 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, resolve, sep } from "node:path";
 
-import { normalizeUlwLoopSessionId, ulwLoopDir } from "./paths.js";
+import { normalizeUlwLoopSessionId, ulwLoopDir, ulwLoopStateLockPath } from "./paths.js";
+import { isStateLockTimeout, withStateLockSync } from "./state-lock.js";
 import type { UlwLoopItem, UlwLoopPlan } from "./types.js";
 
 // Turn-death recovery only: Codex emits Stop when a turn ends, so a run that
@@ -10,7 +11,7 @@ import type { UlwLoopItem, UlwLoopPlan } from "./types.js";
 
 const RESUME_CAP = 2;
 
-// Mirrors start-work-continuation's context-pressure bail-out: injecting a
+// Mirrors ulw-execute-continuation's context-pressure bail-out: injecting a
 // resume directive into an already-overflowing context makes things worse.
 const CONTEXT_PRESSURE_MARKERS = [
 	"context compacted",
@@ -34,12 +35,13 @@ export function runStopResumeHook(input: unknown): string {
 	if (payload === null || payload.stop_hook_active) return "";
 	if (transcriptShowsContextPressure(payload.transcript_path)) return "";
 	if (boulderContinuationWillFire(payload.cwd, payload.session_id)) return "";
-	const stateDir = ulwLoopDir(payload.cwd, { sessionId: payload.session_id });
+	const scope = { sessionId: payload.session_id } as const;
+	const stateDir = ulwLoopDir(payload.cwd, scope);
 	const plan = readPlan(join(stateDir, "goals.json"));
 	if (plan === null || plan.aggregateCompletion?.status === "complete") return "";
 	const goal = resumableGoal(plan);
 	if (goal === undefined) return "";
-	if (!consumeResumeBudget(stateDir, goal.id)) return "";
+	if (!consumeResumeBudgetLocked(ulwLoopStateLockPath(payload.cwd, scope), stateDir, goal.id)) return "";
 	const output: { decision: "block"; reason: string } = {
 		decision: "block",
 		reason: renderResumeDirective(plan, goal, payload.session_id),
@@ -68,6 +70,17 @@ function isResumableStatus(status: UlwLoopItem["status"]): boolean {
 	return status === "pending" || status === "in_progress";
 }
 
+// A resume is a budgeted side effect; when the session lock cannot be taken the
+// hook stays silent (fail closed) instead of charging the counter unlocked.
+function consumeResumeBudgetLocked(lockPath: string, stateDir: string, goalId: string): boolean {
+	try {
+		return withStateLockSync(lockPath, () => consumeResumeBudget(stateDir, goalId));
+	} catch (error) {
+		if (isStateLockTimeout(error)) return false;
+		throw error;
+	}
+}
+
 // Two-strike cap keyed on ledger movement: an unchanged ledger.jsonl line
 // count across resumes means the loop is not progressing. The stuck marker is
 // a separate file — a ledger append would change the count and self-reset.
@@ -136,7 +149,7 @@ function readCounter(counterPath: string): { count: number; ledgerLineCount: num
 	}
 }
 
-// Local ~10-LOC approximation of start-work-continuation's boulder check (no
+// Local ~10-LOC approximation of ulw-execute-continuation's boulder check (no
 // cross-component import allowed): any continuable work for this session means
 // that hook owns the Stop event, so this one stays silent.
 function boulderContinuationWillFire(cwd: string, sessionId: string): boolean {
@@ -168,7 +181,7 @@ function transcriptShowsContextPressure(transcriptPath: string): boolean {
 	}
 }
 
-// start-work-continuation owns an active Boulder plan until its final gate marks
+// ulw-execute-continuation owns an active Boulder plan until its final gate marks
 // the work complete, including the zero-remaining checklist state.
 function boulderPlanHasChecklist(cwd: string, entry: Record<string, unknown>): boolean {
 	const activePlan = entry["active_plan"];

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

@@ -0,0 +1,107 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// The agent toolkit ships on two surfaces: the LazyCodex (Codex CLI) plugin runs the component
+// bundle directly, while omo-senpi stages the same bundle through stage-agent-toolkit.mjs. The
+// reviewer identities the final quality gate enforces differ per surface, so the staging script
+// bakes a `surface.json` marker next to the staged bundle and this module resolves it. Without a
+// marker (the Codex layout) the surface stays "lazycodex".
+export type UlwLoopToolkitSurface = "lazycodex" | "omo-senpi";
+
+export interface UlwLoopReviewerRoles {
+	readonly codeReview: string;
+	readonly manualQa: string;
+	readonly gateReview: string;
+}
+
+export const REVIEWER_ROLES_BY_SURFACE: Readonly<Record<UlwLoopToolkitSurface, UlwLoopReviewerRoles>> = {
+	lazycodex: {
+		codeReview: "lazycodex-code-reviewer",
+		manualQa: "lazycodex-qa-executor",
+		gateReview: "lazycodex-gate-reviewer",
+	},
+	"omo-senpi": {
+		codeReview: "omo-senpi-code-reviewer",
+		manualQa: "omo-senpi-qa-executor",
+		gateReview: "omo-senpi-gate-reviewer",
+	},
+};
+
+export const GATE_REVIEWER_AGENT_NAMES: ReadonlySet<string> = new Set(
+	Object.values(REVIEWER_ROLES_BY_SURFACE).map((roles) => roles.gateReview),
+);
+
+export type UlwLoopGateSection = "codeReview" | "manualQa" | "gateReview" | "iteration" | "criteriaCoverage";
+
+export const REQUIRED_GATE_SECTIONS_BY_SURFACE: Readonly<Record<UlwLoopToolkitSurface, readonly UlwLoopGateSection[]>> =
+	{
+		lazycodex: ["manualQa", "gateReview", "iteration", "criteriaCoverage"],
+		"omo-senpi": ["manualQa", "gateReview", "iteration", "criteriaCoverage"],
+	};
+
+export const OPTIONAL_GATE_SECTIONS_BY_SURFACE: Readonly<Record<UlwLoopToolkitSurface, readonly UlwLoopGateSection[]>> =
+	{
+		lazycodex: ["codeReview"],
+		"omo-senpi": [],
+	};
+
+export const GATE_SECTION_BY_ACCEPTOR: Readonly<
+	Record<UlwLoopToolkitSurface, Readonly<Partial<Record<UlwLoopGateSection, readonly string[]>>>>
+> = {
+	lazycodex: {
+		codeReview: [REVIEWER_ROLES_BY_SURFACE.lazycodex.codeReview, "main-session"],
+		manualQa: [REVIEWER_ROLES_BY_SURFACE.lazycodex.manualQa, "main-session"],
+		gateReview: [
+			REVIEWER_ROLES_BY_SURFACE.lazycodex.gateReview,
+			"category:deep",
+			"category:unspecified-high",
+			"category:unspecified-low",
+			"main-session",
+		],
+	},
+	"omo-senpi": {
+		manualQa: ["main-session"],
+		gateReview: ["category:deep", "category:unspecified-high", "category:unspecified-low"],
+	},
+};
+
+export function reviewerRolesFor(surface: UlwLoopToolkitSurface): UlwLoopReviewerRoles {
+	return REVIEWER_ROLES_BY_SURFACE[surface];
+}
+
+export const SURFACE_MARKER_FILENAME = "surface.json";
+const SURFACE_ENV_KEY = "OMO_AGENT_TOOLKIT_SURFACE";
+
+function parseSurface(value: unknown): UlwLoopToolkitSurface | null {
+	return value === "lazycodex" || value === "omo-senpi" ? value : null;
+}
+
+export interface ResolveToolkitSurfaceOptions {
+	readonly env?: Readonly<Record<string, string | undefined>>;
+	readonly entryDir?: string;
+}
+
+// Resolution order: explicit env override (tests, doctor probes) -> staged surface.json marker
+// sitting next to the running bundle -> lazycodex default. The marker is distribution-baked, so a
+// malformed marker falls back to the default instead of crashing checkpoint validation; the env
+// override remains available to force the intended surface on a damaged install.
+export function resolveToolkitSurface(options?: ResolveToolkitSurfaceOptions): UlwLoopToolkitSurface {
+	const env = options?.env ?? process.env;
+	const fromEnv = parseSurface(env[SURFACE_ENV_KEY]);
+	if (fromEnv !== null) return fromEnv;
+	const entryDir = options?.entryDir ?? dirname(fileURLToPath(import.meta.url));
+	const markerPath = join(entryDir, SURFACE_MARKER_FILENAME);
+	return readMarkerSurface(markerPath) ?? "lazycodex";
+}
+
+function readMarkerSurface(markerPath: string): UlwLoopToolkitSurface | null {
+	try {
+		if (!existsSync(markerPath)) return null;
+		const parsed = JSON.parse(readFileSync(markerPath, "utf8")) as Record<string, unknown>;
+		return parseSurface(parsed["surface"]);
+	} catch (error) {
+		if (error instanceof Error) return null;
+		throw error;
+	}
+}

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

@@ -31,7 +31,6 @@ describe("checkpointAndContinue", () => {
 		});
 
 		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");
 	});
 

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

@@ -1,5 +1,5 @@
 import { writeFile } from "node:fs/promises";
-import { describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
 import { checkpointUlwLoop } from "../src/checkpoint.js";
 import { ulwLoopBriefPath } from "../src/paths.js";
@@ -7,7 +7,138 @@ import { startNextUlwLoop } from "../src/plan-crud.js";
 import { criterion, expectCode, goal, passGoal, plan, repoWith, snapshot } from "./fixtures/checkpoint-builders.js";
 import { MISSING_ARTIFACT_PATH, qualityGateJson } from "./fixtures/quality-gate-builder.js";
 
+function requiredSection(gate: Record<string, Record<string, unknown>>, key: string): Record<string, unknown> {
+	const section = gate[key];
+	if (section === undefined) throw new Error(`missing gate section: ${key}`);
+	return section;
+}
+
+describe("checkpointUlwLoop final story surface resolution", () => {
+	beforeEach(() => {
+		delete process.env["OMO_AGENT_TOOLKIT_SURFACE"];
+	});
+
+	afterEach(() => {
+		delete process.env["OMO_AGENT_TOOLKIT_SURFACE"];
+	});
+
+	it("#given the omo-senpi surface #when the gate omits codeReview #then the final story completes", async () => {
+		process.env["OMO_AGENT_TOOLKIT_SURFACE"] = "omo-senpi";
+		const repo = await repoWith(
+			plan([passGoal("G001", { status: "complete" }), passGoal("G002")], { activeGoalId: "G002" }),
+		);
+		const gate = JSON.parse(await qualityGateJson(repo, undefined, "G001-finished", "omo-senpi")) as Record<
+			string,
+			Record<string, unknown>
+		>;
+		delete gate["codeReview"];
+		requiredSection(gate, "manualQa")["by"] = "main-session";
+		requiredSection(gate, "gateReview")["by"] = "category:deep";
+
+		const result = await checkpointUlwLoop(repo, {
+			goalId: "G002",
+			status: "complete",
+			evidence: "final work complete and validation passed",
+			codexGoalJson: snapshot("complete"),
+			qualityGateJson: JSON.stringify(gate),
+		});
+
+		expect(result.aggregateCompletion?.status).toBe("complete");
+		expect(result.plan.aggregateCompletion?.status).toBe("complete");
+	});
+
+	it("#given the same codeReview-free gate #when the surface is lazycodex #then the final story completes", async () => {
+		const repo = await repoWith(
+			plan([passGoal("G001", { status: "complete" }), passGoal("G002")], { activeGoalId: "G002" }),
+		);
+		const gate = JSON.parse(await qualityGateJson(repo, undefined, "G001-finished", "omo-senpi")) as Record<
+			string,
+			Record<string, unknown>
+		>;
+		delete gate["codeReview"];
+		requiredSection(gate, "manualQa")["by"] = "main-session";
+		requiredSection(gate, "gateReview")["by"] = "category:deep";
+
+		const result = await checkpointUlwLoop(repo, {
+			goalId: "G002",
+			status: "complete",
+			evidence: "final work complete and validation passed",
+			codexGoalJson: snapshot("complete"),
+			qualityGateJson: JSON.stringify(gate),
+		});
+
+		expect(result.aggregateCompletion?.status).toBe("complete");
+		expect(result.plan.aggregateCompletion?.status).toBe("complete");
+	});
+
+	it("#given the omo-senpi surface #when the gate includes codeReview #then the final story is rejected", async () => {
+		process.env["OMO_AGENT_TOOLKIT_SURFACE"] = "omo-senpi";
+		const repo = await repoWith(
+			plan([passGoal("G001", { status: "complete" }), passGoal("G002")], { activeGoalId: "G002" }),
+		);
+		const gateJson = await qualityGateJson(repo, undefined, "G001-finished", "omo-senpi");
+
+		await expectCode(
+			() =>
+				checkpointUlwLoop(repo, {
+					goalId: "G002",
+					status: "complete",
+					evidence: "final work complete and validation passed",
+					codexGoalJson: snapshot("complete"),
+					qualityGateJson: gateJson,
+				}),
+			"ULW_LOOP_QUALITY_GATE_INVALID",
+		);
+	});
+
+	it("#given the omo-senpi surface #when the gate names lazycodex reviewers #then the final story is rejected", async () => {
+		process.env["OMO_AGENT_TOOLKIT_SURFACE"] = "omo-senpi";
+		const repo = await repoWith(
+			plan([passGoal("G001", { status: "complete" }), passGoal("G002")], { activeGoalId: "G002" }),
+		);
+		const gateJson = await qualityGateJson(repo);
+
+		await expectCode(
+			() =>
+				checkpointUlwLoop(repo, {
+					goalId: "G002",
+					status: "complete",
+					evidence: "final work complete and validation passed",
+					codexGoalJson: snapshot("complete"),
+					qualityGateJson: gateJson,
+				}),
+			"ULW_LOOP_QUALITY_GATE_INVALID",
+		);
+	});
+});
+
 describe("checkpointUlwLoop final story", () => {
+	it("#given a mismatched codex objective and multiple gate defects #when completing the final checkpoint #then reports both validation domains", async () => {
+		const repo = await repoWith(
+			plan([passGoal("G001", { status: "complete" }), passGoal("G002")], { activeGoalId: "G002" }),
+		);
+		const gate = JSON.parse(await qualityGateJson(repo)) as Record<string, Record<string, unknown>>;
+		const manualQa = requiredSection(gate, "manualQa");
+		manualQa["surfaceEvidence"] = [];
+		requiredSection(gate, "gateReview")["recommendation"] = "REJECT";
+
+		try {
+			await checkpointUlwLoop(repo, {
+				goalId: "G002",
+				status: "complete",
+				evidence: "final work complete and validation passed",
+				codexGoalJson: snapshot("complete", "wrong objective"),
+				qualityGateJson: JSON.stringify(gate),
+			});
+			throw new Error("expected validation failure");
+		} catch (error) {
+			expect(error).toBeInstanceOf(Error);
+			if (!(error instanceof Error)) throw error;
+			expect(error.message).toContain("Codex goal objective mismatch");
+			expect(error.message).toContain("manualQa.surfaceEvidence");
+			expect(error.message).toContain("gateReview.recommendation");
+		}
+	});
 	it("requires quality-gate-json for the final goal complete", async () => {
 		const repo = await repoWith(
 			plan([passGoal("G001", { status: "complete" }), passGoal("G002")], { activeGoalId: "G002" }),