lazycodex-ai 5.0.0-beta.4 → 5.0.0-beta.40

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

@@ -1,10 +1,27 @@
-import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import {
+	existsSync,
+	mkdirSync,
+	openSync,
+	readdirSync,
+	readFileSync,
+	renameSync,
+	statSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
 
 import type { PreToolUsePayload } from "./codex-hook.js";
 import { parsePreToolUsePayload } from "./codex-hook.js";
 import { isFinalRunCompletionCandidate } from "./goal-status.js";
 import { ulwLoopAttemptEvidenceDir, ulwLoopDir } from "./paths.js";
+import {
+	GATE_REVIEWER_AGENT_NAMES,
+	REVIEWER_ROLES_BY_SURFACE,
+	resolveToolkitSurface,
+	reviewerRolesFor,
+} from "./surface.js";
 import type { UlwLoopPlan } from "./types.js";
 
 // spawn_agent = v1; collaborationspawn_agent = the delimiter-free flattened v2
@@ -12,18 +29,29 @@ import type { UlwLoopPlan } from "./types.js";
 // dotted token observed live in the task-1 probe (hook-tool-tokens.txt).
 const SPAWN_TOOL_TOKENS = new Set(["spawn_agent", "collaborationspawn_agent", "collaboration.spawn_agent"]);
 const DEFAULT_FANOUT_LIMIT = 60;
-const GATE_MESSAGE_PATTERN = /lazycodex-gate-reviewer|final gate review/i;
+const DEFAULT_REVIEW_SPAWN_LIMIT = 3;
+const GATE_MESSAGE_PATTERN = /lazycodex-gate-reviewer|omo-senpi-gate-reviewer|final gate review/i;
+const REVIEW_AGENT_TYPES = [
+	...Object.values(REVIEWER_ROLES_BY_SURFACE).map((roles) => roles.gateReview),
+	...Object.values(REVIEWER_ROLES_BY_SURFACE).map((roles) => roles.codeReview),
+	...Object.values(REVIEWER_ROLES_BY_SURFACE).map((roles) => roles.manualQa),
+] as const;
+const REVIEW_AGENT_TYPE_SET = new Set<string>(REVIEW_AGENT_TYPES);
 
 export function applySpawnGuards(payload: PreToolUsePayload): string {
 	if (payload.hook_event_name !== "PreToolUse" || !SPAWN_TOOL_TOKENS.has(payload.tool_name)) return "";
 	const stateDir = ulwLoopDir(payload.cwd, { sessionId: payload.session_id });
 	const plan = readPlan(join(stateDir, "goals.json"));
 	if (plan === null) return "";
-	const fanOutDenial = consumeFanOutBudget(stateDir);
-	if (fanOutDenial !== null) return deny(fanOutDenial);
+	const fanOutPeek = peekFanOutBudget(stateDir);
+	if (fanOutPeek !== null) return deny(fanOutPeek);
 	const missingArtifact = missingGateArtifact(payload, plan);
 	if (missingArtifact !== null)
 		return deny(`spawn code-review + QA first; gate audits their artifacts: missing ${missingArtifact}`);
+	const reviewDenial = consumeReviewSpawnBudget(payload, plan, stateDir);
+	if (reviewDenial !== null) return deny(reviewDenial);
+	const fanOutDenial = consumeFanOutBudget(stateDir);
+	if (fanOutDenial !== null) return deny(fanOutDenial);
 	return "";
 }
 
@@ -40,46 +68,171 @@ export async function runSpawnGuardCli(stdin: NodeJS.ReadableStream, stdout: Nod
 	}
 }
 
+// Read-only fan-out eligibility check. Returns a denial reason when the next
+// spawn would exceed the limit, without incrementing the counter. Call this
+// before charging any per-reviewer quota so a saturated global cap cannot
+// silently consume reviewer allowances for spawns that will never run.
+function peekFanOutBudget(stateDir: string): string | null {
+	const counterPath = join(stateDir, "spawn-count.json");
+	const count = readCount(counterPath) + 1;
+	const limit = fanOutLimit();
+	if (count <= limit) return null;
+	return `ulw-loop spawn fan-out cap reached (${count}/${limit}). Consolidate work into the agents already running, or raise OMO_SPAWN_FANOUT_LIMIT if this volume is intentional.`;
+}
+
 // Per-session spawn counter; depth/lineage tracking is descoped — this is a
 // total-volume backstop against fan-out explosions, not a recursion tracker.
 function consumeFanOutBudget(stateDir: string): string | null {
 	const counterPath = join(stateDir, "spawn-count.json");
 	const count = readCount(counterPath) + 1;
-	writeFileSync(counterPath, JSON.stringify({ count }));
+	atomicWriteJson(counterPath, { count });
 	const limit = fanOutLimit();
 	if (count <= limit) return null;
 	return `ulw-loop spawn fan-out cap reached (${count}/${limit}). Consolidate work into the agents already running, or raise OMO_SPAWN_FANOUT_LIMIT if this volume is intentional.`;
 }
 
+function consumeReviewSpawnBudget(payload: PreToolUsePayload, plan: UlwLoopPlan, stateDir: string): string | null {
+	const agentType = reviewAgentType(payload.tool_input);
+	if (agentType === null) return null;
+	const goal =
+		plan.goals.find((candidate) => candidate.id === plan.activeGoalId) ??
+		plan.goals.find((candidate) => isFinalRunCompletionCandidate(plan, candidate));
+	if (goal === undefined) return null;
+	const counterPath = join(stateDir, "review-spawn-counts.json");
+	const lockPath = `${counterPath}.lock`;
+	const limit = reviewSpawnLimit();
+	return withExclusiveLock(lockPath, () => {
+		const counts = readCounts(counterPath);
+		const key = `${agentType}:${goal.id}:a${goal.attempt}`;
+		const count = (counts[key] ?? 0) + 1;
+		if (count > limit)
+			return `ulw-loop reviewer no-progress cap reached (${agentType} ${count}/${limit}) for ${goal.id} attempt ${goal.attempt}. Consolidate existing review findings, or checkpoint and start a new attempt after concrete progress.`;
+		counts[key] = count;
+		atomicWriteJson(counterPath, counts);
+		return null;
+	});
+}
+
 function missingGateArtifact(payload: PreToolUsePayload, plan: UlwLoopPlan): string | null {
 	if (!isGateReviewerSpawn(payload.tool_input)) return null;
 	const goal = plan.goals.find((candidate) => isFinalRunCompletionCandidate(plan, candidate));
 	if (goal === undefined || goal.status === "complete") return null;
 	if (!goal.successCriteria.every((criterion) => criterion.status === "pass")) return null;
 	const scope = { sessionId: payload.session_id } as const;
+	const surface = resolveToolkitSurface();
+	const requiredArtifacts =
+		surface === "omo-senpi" ? [`${goal.id}-manual-qa.md`] : [`${goal.id}-code-review.md`, `${goal.id}-manual-qa.md`];
 	if (plan.evidenceLayoutVersion === 2) {
 		const attemptDir = ulwLoopAttemptEvidenceDir(goal.id, goal.attempt, scope);
-		for (const name of [`${goal.id}-code-review.md`, `${goal.id}-manual-qa.md`]) {
+		for (const name of requiredArtifacts) {
 			const relative = `${attemptDir}/${name}`;
 			if (!isNonEmptyFile(join(payload.cwd, relative))) return relative;
 		}
 		return null;
 	}
 	const flatReport = `.omo/evidence/${goal.id}-code-review.md`;
-	if (!isNonEmptyFile(join(payload.cwd, flatReport))) return flatReport;
+	if (surface !== "omo-senpi" && !isNonEmptyFile(join(payload.cwd, flatReport))) return flatReport;
+	if (surface === "omo-senpi") {
+		const manualQa = `.omo/evidence/${goal.id}-manual-qa.md`;
+		return isNonEmptyFile(join(payload.cwd, manualQa)) ? null : manualQa;
+	}
 	// v1 manual-QA approximation: any other non-empty evidence file counts.
 	if (!hasOtherEvidenceFile(join(payload.cwd, ".omo", "evidence"), `${goal.id}-code-review.md`))
-		return `.omo/evidence/<any manual-QA artifact besides ${goal.id}-code-review.md>`;
+		return `.omo/evidence/${goal.id}-manual-qa.md`;
 	return null;
 }
 
 function isGateReviewerSpawn(toolInput: unknown): boolean {
-	if (typeof toolInput !== "object" || toolInput === null) return false;
+	const agentType = reviewAgentType(toolInput);
+	return agentType !== null && GATE_REVIEWER_AGENT_NAMES.has(agentType);
+}
+
+function reviewAgentType(toolInput: unknown): string | null {
+	if (typeof toolInput !== "object" || toolInput === null) return null;
 	const record = toolInput as Record<string, unknown>;
 	const agentType = record["agent_type"];
-	if (typeof agentType === "string") return agentType === "lazycodex-gate-reviewer";
+	if (typeof agentType === "string") {
+		// V1: agent_type is present — only reviewer types proceed; any other type is not a review spawn.
+		if (!REVIEW_AGENT_TYPE_SET.has(agentType)) return null;
+		return activeSurfaceReviewerAlias(agentType);
+	}
 	const message = record["message"];
-	return typeof message === "string" && GATE_MESSAGE_PATTERN.test(message);
+	if (typeof message !== "string") return null;
+	const normalizedMessage = message.toLowerCase();
+	// Explicit "act as <role>" assignment takes priority. If the assigned role is not a reviewer,
+	// treat the spawn as non-review so a message that merely mentions a reviewer name does not
+	// accidentally charge that reviewer's quota.
+	const allRoleNames = [...REVIEW_AGENT_TYPES];
+	const explicitAssignment = allRoleNames
+		.map((name) => ({
+			name,
+			index: normalizedMessage.search(new RegExp(`\\bact as (?:an? )?${name}\\b`)),
+		}))
+		.filter(({ index }) => index >= 0)
+		.sort((left, right) => left.index - right.index)[0];
+	if (explicitAssignment !== undefined) return activeSurfaceReviewerAlias(explicitAssignment.name);
+	// Check for an explicit "act as <non-reviewer-role>" assignment. If found, the spawn is not a
+	// review spawn even if the message body mentions a reviewer name.
+	const nonReviewerActAs = /\bact as (?:an? )?\S+/.test(normalizedMessage);
+	if (nonReviewerActAs) return null;
+	const namedReviewer = REVIEW_AGENT_TYPES.find((name) => normalizedMessage.includes(name));
+	if (namedReviewer !== undefined) return activeSurfaceReviewerAlias(namedReviewer);
+	return GATE_MESSAGE_PATTERN.test(message) ? reviewerRolesFor(resolveToolkitSurface()).gateReview : null;
+}
+
+function activeSurfaceReviewerAlias(reviewer: string): string {
+	const activeRoles = reviewerRolesFor(resolveToolkitSurface());
+	for (const roles of Object.values(REVIEWER_ROLES_BY_SURFACE)) {
+		if (reviewer === roles.codeReview) return activeRoles.codeReview;
+		if (reviewer === roles.manualQa) return activeRoles.manualQa;
+		if (reviewer === roles.gateReview) return activeRoles.gateReview;
+	}
+	return reviewer;
+}
+
+function withExclusiveLock<T>(lockPath: string, fn: () => T): T {
+	mkdirSync(dirname(lockPath), { recursive: true });
+	const maxAttempts = 10;
+	const baseDelayMs = 10;
+	for (let attempt = 0; attempt < maxAttempts; attempt++) {
+		let fd: number | null = null;
+		try {
+			fd = openSync(lockPath, "wx");
+			writeFileSync(fd, process.pid.toString());
+			try {
+				return fn();
+			} finally {
+				try {
+					unlinkSync(lockPath);
+				} catch {
+					/* empty */
+				}
+			}
+		} catch (error) {
+			if (fd !== null) {
+				try {
+					unlinkSync(lockPath);
+				} catch {
+					/* empty */
+				}
+			}
+			if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+				return fn();
+			}
+			const delayMs = baseDelayMs * 2 ** attempt + Math.random() * baseDelayMs;
+			const deadline = Date.now() + delayMs;
+			while (Date.now() < deadline) {
+				/* spin */
+			}
+		}
+	}
+	return fn();
+}
+
+function atomicWriteJson(targetPath: string, data: unknown): void {
+	const tmp = join(dirname(targetPath), `.tmp-${randomBytes(6).toString("hex")}`);
+	writeFileSync(tmp, JSON.stringify(data));
+	renameSync(tmp, targetPath);
 }
 
 function deny(reason: string): string {
@@ -100,6 +253,13 @@ function fanOutLimit(): number {
 	return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_FANOUT_LIMIT;
 }
 
+function reviewSpawnLimit(): number {
+	const raw = process.env["OMO_ULW_LOOP_REVIEW_SPAWN_LIMIT"];
+	if (raw === undefined) return DEFAULT_REVIEW_SPAWN_LIMIT;
+	const parsed = Number.parseInt(raw, 10);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_REVIEW_SPAWN_LIMIT;
+}
+
 function isNonEmptyFile(path: string): boolean {
 	try {
 		return existsSync(path) && statSync(path).size > 0;
@@ -128,6 +288,21 @@ function readCount(counterPath: string): number {
 	}
 }
 
+function readCounts(counterPath: string): Record<string, number> {
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(counterPath, "utf8"));
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {};
+		const counts: Record<string, number> = {};
+		for (const [key, value] of Object.entries(parsed)) {
+			if (typeof value === "number" && value >= 0) counts[key] = value;
+		}
+		return counts;
+	} catch (error) {
+		if (error instanceof Error) return {};
+		throw error;
+	}
+}
+
 function readPlan(goalsPath: string): UlwLoopPlan | null {
 	try {
 		return JSON.parse(readFileSync(goalsPath, "utf8")) as UlwLoopPlan;

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.`,
+		];
+	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>'\`.`,
+	];
+}

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

@@ -10,7 +10,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",
@@ -136,7 +136,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 +168,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,95 @@
+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: ["codeReview", "manualQa", "gateReview", "iteration", "criteriaCoverage"],
+		"omo-senpi": ["manualQa", "gateReview", "iteration", "criteriaCoverage"],
+	};
+
+export const GATE_SECTION_BY_ACCEPTOR: Readonly<
+	Record<UlwLoopToolkitSurface, Readonly<Partial<Record<UlwLoopGateSection, readonly string[]>>>>
+> = {
+	lazycodex: {
+		codeReview: [REVIEWER_ROLES_BY_SURFACE.lazycodex.codeReview],
+		manualQa: [REVIEWER_ROLES_BY_SURFACE.lazycodex.manualQa],
+		gateReview: [REVIEWER_ROLES_BY_SURFACE.lazycodex.gateReview],
+	},
+	"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,139 @@ 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 is rejected", 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";
+
+		await expectCode(
+			() =>
+				checkpointUlwLoop(repo, {
+					goalId: "G002",
+					status: "complete",
+					evidence: "final work complete and validation passed",
+					codexGoalJson: snapshot("complete"),
+					qualityGateJson: JSON.stringify(gate),
+				}),
+			"ULW_LOOP_QUALITY_GATE_INVALID",
+		);
+	});
+
+	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" }),