oh-my-opencode 5.0.0-beta.31 → 5.0.0-beta.32

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

@@ -12,6 +12,7 @@ import {
 	steer,
 } from "./cli-subcommands.js";
 import { resolveUlwLoopSessionIdFromEnv, type UlwLoopScope } from "./paths.js";
+import { sessionIdRequiredMessage } from "./plan-missing-recovery.js";
 import { UlwLoopError } from "./types.js";
 
 export const ULW_LOOP_SUBCOMMANDS = [
@@ -108,7 +109,7 @@ function commandScope(argv: readonly string[]): UlwLoopScope | undefined {
 	if (sessionIdFlagPresent(argv)) {
 		const sessionId = readValue(argv, SESSION_ID_FLAG)?.trim();
 		if (!sessionId) {
-			throw new UlwLoopError(`${SESSION_ID_FLAG} requires a non-empty value.`, "ULW_LOOP_SESSION_ID_REQUIRED", {
+			throw new UlwLoopError(sessionIdRequiredMessage(SESSION_ID_FLAG), "ULW_LOOP_SESSION_ID_REQUIRED", {
 				details: { flag: SESSION_ID_FLAG },
 			});
 		}

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

@@ -10,6 +10,7 @@ export const ULW_LOOP_HELP = `Usage:
   omo-agent-toolkit ulw-loop complete-goals [--retry-failed] [--json]
   omo-agent-toolkit ulw-loop criteria --goal-id <id> [--json]
   omo-agent-toolkit ulw-loop record-evidence --goal-id <id> --criterion-id <id> --status pass|fail|blocked --evidence "..." [--notes "..."] [--json]
+  omo-agent-toolkit ulw-loop checkpoint --print-template [--goal-id <id>] [--json]
   omo-agent-toolkit ulw-loop checkpoint --goal-id <id> --status complete|failed|blocked --evidence "..." --codex-goal-json <...> [--quality-gate-json <...>] [--no-advance] [--json]
   omo-agent-toolkit ulw-loop steer --kind <kind> ... --evidence "..." --rationale "..." [--proposals-json <json-or-path>] [--json]
   omo-agent-toolkit ulw-loop add-goal --title "..." --objective "..." [--json]

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

@@ -17,6 +17,7 @@ import { type UlwLoopScope, ulwLoopAttemptEvidenceDir } from "./paths.js";
 import { addUlwLoopGoal, createUlwLoopPlan, startNextUlwLoop, summarizeUlwLoopPlan } from "./plan-crud.js";
 import { readUlwLoopPlan } from "./plan-io.js";
 import { recordFinalReviewBlockers } from "./review-blockers.js";
+import { statusNextActions } from "./status-next-actions.js";
 import { steerUlwLoop } from "./steering.js";
 import { steerUlwLoopBatch } from "./steering-batch.js";
 import type { UlwLoopItem } from "./types.js";
@@ -73,6 +74,7 @@ export async function status(repoRoot: string, json: boolean, scope?: UlwLoopSco
 			plan,
 			summary: summarizeUlwLoopPlan(plan),
 			...(currentAttemptDir === undefined ? {} : { currentAttemptDir }),
+			nextActions: statusNextActions(plan),
 		});
 	} else printStatus(plan);
 	return 0;

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

@@ -127,6 +127,7 @@ function finalSection(
 	if (!isFinal)
 		return "- This is not the final ulw-loop story; do not run the final reviewer/manual-QA/gate-review quality gate yet.";
 	const option = sessionOption(plan);
+	if (surface === "omo-senpi") return senpiFinalSection(plan, goal, aggregate);
 	const blockerCommand = `omo-agent-toolkit ulw-loop record-review-blockers${option} --goal-id ${goal.id} --title "Resolve final code-review blockers" --objective "<blocker-resolution objective>" --evidence "<review findings>" --codex-goal-json "<active get_goal JSON or path>"`;
 	const checkpointCommand = `omo-agent-toolkit ulw-loop checkpoint${option} --goal-id ${goal.id} --status complete --evidence "<targeted verification/manualQa/gateReview evidence>" --codex-goal-json "<fresh complete get_goal JSON or path>" --quality-gate-json "<quality gate JSON or path>"`;
 	return joinLines([
@@ -147,6 +148,23 @@ function finalSection(
 	]);
 }
 
+function senpiFinalSection(plan: UlwLoopPlan, goal: UlwLoopItem, aggregate: boolean): string {
+	const option = sessionOption(plan);
+	const checkpointCommand = `omo-agent-toolkit ulw-loop checkpoint${option} --goal-id ${goal.id} --status complete --evidence "<manualQa/gateReview evidence>" --codex-goal-json "<fresh complete get_goal JSON or path>" --quality-gate-json "$(omo-agent-toolkit ulw-loop checkpoint${option} --print-template)"`;
+	return joinLines([
+		"Final story — run the single-reviewer quality gate before update_goal:",
+		"- Run manual QA yourself and write the non-empty artifact under currentAttemptDir; set manualQa.by to \"main-session\".",
+		'- Spawn exactly one gate reviewer with task(category: "deep").',
+		"- If that task fails with any model_unavailable failure, retry with category:unspecified-high, then category:unspecified-low.",
+		'- Set gateReview.by to the exact category:<name> literal used for the successful task.',
+		'- Build the gate JSON with omo-agent-toolkit ulw-loop checkpoint --print-template, then fill manualQa, gateReview, iteration, and criteriaCoverage.',
+		'- Require passed manualQa, approved gateReview, passed iteration, and complete criteriaCoverage before update_goal({status: "complete"}).',
+		aggregate
+			? `- If the gate is clean, call update_goal({status: "complete"}), call get_goal again, then checkpoint the aggregate story: ${checkpointCommand}`
+			: `- If the gate is clean, call update_goal({status: "complete"}), call get_goal again, then checkpoint: ${checkpointCommand}`,
+	]);
+}
+
 function sessionOption(plan: UlwLoopPlan): string {
 	const prefix = ".omo/ulw-loop/";
 	const suffix = "/goals.json";

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

@@ -139,3 +139,26 @@ export function formatCodexGoalReconciliation(reconciliation: CodexGoalReconcili
 	const parts = [...reconciliation.errors, ...reconciliation.warnings];
 	return parts.join(" ");
 }
+
+export interface CodexGoalMismatchRecovery {
+	readonly message: string;
+	readonly details: { readonly expectedObjective: string; readonly receivedObjective: string };
+}
+
+/**
+ * The reconciliation errors normalize whitespace for comparison, which makes the
+ * quoted objective unusable as a copy source. Recovery therefore carries the
+ * plan's `codexObjective` verbatim so the agent can paste it into `update_goal`.
+ */
+export function codexGoalMismatchRecovery(
+	expectedObjective: string,
+	snapshot: CodexGoalSnapshot | null | undefined,
+): CodexGoalMismatchRecovery {
+	const receivedObjective = snapshot?.objective ?? "";
+	const message = [
+		"Recovery: the Codex goal objective must equal the plan's codexObjective exactly — copy the expected value below into update_goal and re-run get_goal.",
+		`expected codexObjective: ${expectedObjective}`,
+		`received objective: ${receivedObjective || "(none)"}`,
+	].join("\n");
+	return { message, details: { expectedObjective, receivedObjective } };
+}

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

@@ -107,15 +107,7 @@ export interface UlwLoopManualQaAdversarialCase {
 	readonly artifactRefs: readonly string[];
 }
 
-export interface UlwLoopQualityGate {
-	readonly codeReview: {
-		readonly by: string;
-		readonly recommendation: "APPROVE";
-		readonly codeQualityStatus: "CLEAR" | "WATCH";
-		readonly reportPath: string;
-		readonly evidence: string;
-		readonly blockers: readonly [];
-	};
+interface UlwLoopQualityGateCommon {
 	readonly manualQa: {
 		readonly by: string;
 		readonly status: "passed";
@@ -147,6 +139,24 @@ export interface UlwLoopQualityGate {
 	};
 }
 
+export interface UlwLoopQualityGateLazycodex extends UlwLoopQualityGateCommon {
+	readonly surface: "lazycodex";
+	readonly codeReview: {
+		readonly by: string;
+		readonly recommendation: "APPROVE";
+		readonly codeQualityStatus: "CLEAR" | "WATCH";
+		readonly reportPath: string;
+		readonly evidence: string;
+		readonly blockers: readonly [];
+	};
+}
+
+export interface UlwLoopQualityGateSenpi extends UlwLoopQualityGateCommon {
+	readonly surface: "omo-senpi";
+}
+
+export type UlwLoopQualityGate = UlwLoopQualityGateLazycodex | UlwLoopQualityGateSenpi;
+
 export interface UlwLoopLedgerEntry {
 	at: string;
 	kind: UlwLoopLedgerEventKind;

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

@@ -1,4 +1,4 @@
-import { createReadStream } from "node:fs";
+import { createReadStream, readdirSync } from "node:fs";
 import { appendFile, mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { createInterface } from "node:readline";
 
@@ -11,6 +11,7 @@ import {
 	ulwLoopLedgerPath,
 	ulwLoopRelativeDir,
 } from "./paths.js";
+import { planMissingRecovery } from "./plan-missing-recovery.js";
 import type { UlwLoopLedgerEntry, UlwLoopPlan } from "./types.js";
 import { iso, ULW_LOOP_DIR, ULW_LOOP_GOALS, ULW_LOOP_LEDGER, UlwLoopError } from "./types.js";
 
@@ -73,10 +74,11 @@ export async function readUlwLoopPlan(repoRoot: string, scope?: UlwLoopScope): P
 		raw = await readFile(path, "utf8");
 	} catch (error) {
 		if (!hasCode(error, "ENOENT")) throw error;
+		const recovery = planMissingRecovery(readSessionDirs(repoRoot));
 		throw new UlwLoopError(
-			`No ulw-loop plan found at ${repoRelative(path, repoRoot)}. Run \`omo-agent-toolkit ulw-loop create-goals ...\` first.`,
+			`No ulw-loop plan found at ${repoRelative(path, repoRoot)}.\n${recovery.message}`,
 			"ULW_LOOP_PLAN_MISSING",
-			{ cause: error },
+			{ cause: error, ...(recovery.details === undefined ? {} : { details: recovery.details }) },
 		);
 	}
 	const parsed: UlwLoopPlan = JSON.parse(raw);
@@ -108,6 +110,19 @@ export async function readUlwLoopPlan(repoRoot: string, scope?: UlwLoopScope): P
 	return parsed;
 }
 
+// Session dirs are the only recovery hint that matters when a plan is missing: the
+// caller is almost always scoped to a session whose sibling actually holds the plan.
+function readSessionDirs(repoRoot: string): readonly string[] {
+	try {
+		return readdirSync(ulwLoopDir(repoRoot), { withFileTypes: true })
+			.filter((entry) => entry.isDirectory())
+			.map((entry) => entry.name)
+			.sort();
+	} catch {
+		return [];
+	}
+}
+
 export async function writePlan(repoRoot: string, plan: UlwLoopPlan, scope?: UlwLoopScope): Promise<void> {
 	await mkdir(ulwLoopDir(repoRoot, scope), { recursive: true });
 	const path = ulwLoopGoalsPath(repoRoot, scope);

package/packages/omo-codex/plugin/components/ulw-loop/src/plan-missing-recovery.ts

@@ -0,0 +1,27 @@
+export const ULW_LOOP_CREATE_GOALS_COMMAND = 'omo-agent-toolkit ulw-loop create-goals --brief "<brief>" --json';
+
+export interface PlanMissingRecovery {
+	readonly message: string;
+	readonly details?: { readonly existingSessionIds: readonly string[] };
+}
+
+/**
+ * A missing plan is either "never bootstrapped" or "bootstrapped under a different
+ * session id"; the recovery text has to answer both without the caller guessing.
+ */
+export function planMissingRecovery(existingSessionIds: readonly string[]): PlanMissingRecovery {
+	const lines = [`Recovery: bootstrap the plan with \`${ULW_LOOP_CREATE_GOALS_COMMAND}\`.`];
+	if (existingSessionIds.length === 0) return { message: lines.join("\n") };
+	lines.push(
+		`Existing ulw-loop session ids under .omo/ulw-loop/: ${existingSessionIds.join(", ")}. Re-run with \`--session-id <id>\` to target one of them.`,
+	);
+	return { message: lines.join("\n"), details: { existingSessionIds } };
+}
+
+export function sessionIdRequiredMessage(flag: string): string {
+	return [
+		`${flag} requires a non-empty value.`,
+		"Recovery: subprocess, eval, and hook contexts do not inherit the ulw-loop session env (OMO_ULW_LOOP_SESSION_ID / CODEX_SESSION_ID / CODEX_THREAD_ID / PI_SESSION_ID),",
+		`so pass the scope explicitly: \`${flag} <id>\` (for example \`${flag} 01a05b8a-6763-7780-834f-319423b071ce\`).`,
+	].join("\n");
+}

package/packages/omo-codex/plugin/components/ulw-loop/src/quality-gate-aggregate.ts

@@ -0,0 +1,57 @@
+import { resolve } from "node:path";
+import type { ValidateQualityGateOptions } from "./quality-gate.js";
+import { isRecord } from "./quality-gate-fields.js";
+import { UlwLoopError } from "./types.js";
+
+type Defect = { readonly field: string; readonly message: string };
+const PLACEHOLDER = /^(?:<replace:[^>]+>|placeholder|todo|tbd|n\/a|stub)$/i;
+
+function add(defects: Defect[], field: string, message: string): void {
+	defects.push({ field, message });
+}
+function text(value: unknown, field: string, defects: Defect[]): void {
+	if (typeof value !== "string" || value.trim() === "")
+		add(defects, field, `Final quality gate requires non-empty ${field}.`);
+	else if (PLACEHOLDER.test(value.trim())) add(defects, field, `Final quality gate rejects placeholder ${field}.`);
+}
+function section(value: unknown, field: string, defects: Defect[]): Record<string, unknown> {
+	if (!isRecord(value)) {
+		add(defects, field, `Final quality gate is missing ${field} evidence.`);
+		return {};
+	}
+	return value;
+}
+
+export function aggregateQualityGateDefects(input: unknown, opts: ValidateQualityGateOptions | undefined): void {
+	if (!isRecord(input)) return;
+	const defects: Defect[] = [];
+	const gate = input;
+	const manual = section(gate["manualQa"], "manualQa", defects);
+	const review = section(gate["gateReview"], "gateReview", defects);
+	text(manual["evidence"], "manualQa.evidence", defects);
+	text(review["evidence"], "gateReview.evidence", defects);
+	if (review["recommendation"] !== "APPROVE")
+		add(defects, "gateReview.recommendation", "gateReview.recommendation must be APPROVE.");
+	const artifacts = Array.isArray(manual["artifactRefs"]) ? manual["artifactRefs"] : [];
+	for (const [index, item] of artifacts.entries()) {
+		if (!isRecord(item)) continue;
+		const path = item["path"];
+		if (typeof path !== "string" || path.trim() === "") continue;
+		if (opts?.repoRoot !== undefined && opts.fs !== undefined && !opts.fs.existsSync(resolve(opts.repoRoot, path)))
+			add(
+				defects,
+				`manualQa.artifactRefs[${index}].path`,
+				`manualQa.artifactRefs[${index}].path must point to an existing artifact.`,
+			);
+	}
+	if (defects.length === 0) return;
+	const truncated = defects.length > 25;
+	const fields = defects.slice(0, 25).map(({ field, message }) => ({ field, message }));
+	const message = [
+		`Final quality gate has ${fields.length}${truncated ? "+" : ""} validation defects:`,
+		...fields.map((item) => `- ${item.field}: ${item.message}`),
+	].join("\n");
+	throw new UlwLoopError(message, "ULW_LOOP_QUALITY_GATE_INVALID", {
+		details: { field: fields[0]?.field, fields, ...(truncated ? { truncated: true } : {}) },
+	});
+}

package/packages/omo-codex/plugin/components/ulw-loop/src/quality-gate-artifacts.ts

@@ -0,0 +1,103 @@
+import { resolve } from "node:path";
+import { isWithinAttemptDir } from "./paths.js";
+import type { ValidateQualityGateOptions } from "./quality-gate.js";
+import { invalid, section, stringArray, textField } from "./quality-gate-fields.js";
+import type { UlwLoopManualQaArtifactKind, UlwLoopManualQaArtifactRef, UlwLoopManualQaSurface } from "./types.js";
+
+export function surfaceField(value: unknown, field: string): UlwLoopManualQaSurface {
+	if (
+		value === "cli" ||
+		value === "http" ||
+		value === "tmux" ||
+		value === "browser" ||
+		value === "gui" ||
+		value === "data"
+	)
+		return value;
+	invalid(`${field} must be a supported manual QA surface.`, field);
+}
+
+export function kindField(value: unknown, field: string): UlwLoopManualQaArtifactKind {
+	if (
+		value === "cli-transcript" ||
+		value === "log" ||
+		value === "screenshot" ||
+		value === "image" ||
+		value === "http-dump" ||
+		value === "data-diff"
+	)
+		return value;
+	invalid(`${field} must be a supported artifact kind.`, field);
+}
+
+export function artifactCompatible(surface: UlwLoopManualQaSurface, kind: UlwLoopManualQaArtifactKind): boolean {
+	switch (surface) {
+		case "cli":
+		case "tmux":
+			return kind === "cli-transcript" || kind === "log";
+		case "http":
+			return kind === "http-dump";
+		case "browser":
+		case "gui":
+			return kind === "screenshot" || kind === "image";
+		case "data":
+			return kind === "data-diff";
+		default:
+			invalid("manualQa.surfaceEvidence has an unsupported surface.", "manualQa.surfaceEvidence.surface");
+	}
+}
+
+export function checkFile(path: string, field: string, opts?: ValidateQualityGateOptions): void {
+	if (opts?.repoRoot === undefined || opts.fs === undefined) return;
+	const absolute = resolve(opts.repoRoot, path);
+	if (!opts.fs.existsSync(absolute)) invalid(`${field} must point to an existing artifact.`, field);
+	if (opts.fs.statSync(absolute).size <= 0) invalid(`${field} must point to a non-empty artifact.`, field);
+	if (opts.currentAttemptDir !== undefined && opts.repoRoot !== undefined) {
+		const attemptRoot = resolve(opts.repoRoot, opts.currentAttemptDir);
+		if (!isWithinAttemptDir(absolute, attemptRoot))
+			invalid(
+				`${field} (${path}) must point to an artifact from the current attempt (${opts.currentAttemptDir}).`,
+				field,
+			);
+	}
+}
+
+export function artifactMap(refs: readonly UlwLoopManualQaArtifactRef[]): Map<string, UlwLoopManualQaArtifactRef> {
+	const byId = new Map<string, UlwLoopManualQaArtifactRef>();
+	for (const ref of refs) {
+		if (byId.has(ref.id)) invalid(`manualQa.artifactRefs contains duplicate ${ref.id}.`, "manualQa.artifactRefs");
+		byId.set(ref.id, ref);
+	}
+	return byId;
+}
+
+export function parseArtifactRefs(
+	value: unknown,
+	opts?: ValidateQualityGateOptions,
+): readonly UlwLoopManualQaArtifactRef[] {
+	if (!Array.isArray(value) || value.length === 0)
+		invalid("manualQa.artifactRefs must not be empty.", "manualQa.artifactRefs");
+	return value.map((item, index) => {
+		const ref = section(item, `manualQa.artifactRefs[${index}]`);
+		const path = textField(ref["path"], `manualQa.artifactRefs[${index}].path`);
+		checkFile(path, `manualQa.artifactRefs[${index}].path`, opts);
+		return {
+			id: textField(ref["id"], `manualQa.artifactRefs[${index}].id`),
+			kind: kindField(ref["kind"], `manualQa.artifactRefs[${index}].kind`),
+			description: textField(ref["description"], `manualQa.artifactRefs[${index}].description`),
+			path,
+		};
+	});
+}
+
+export function referencedArtifacts(
+	value: unknown,
+	field: string,
+	byId: ReadonlyMap<string, UlwLoopManualQaArtifactRef>,
+): readonly UlwLoopManualQaArtifactRef[] {
+	return stringArray(value, field).map((id) => {
+		const artifact = byId.get(id);
+		if (artifact === undefined) invalid(`${field} references unknown artifact ${id}.`, field);
+		return artifact;
+	});
+}

package/packages/omo-codex/plugin/components/ulw-loop/src/quality-gate-fields.ts

@@ -1,6 +1,6 @@
 import { UlwLoopError } from "./types.js";
 
-const PLACEHOLDER_PATTERN = /^(?:placeholder|todo|tbd|n\/a|stub)$/i;
+const PLACEHOLDER_PATTERN = /^(?:<replace:[^>]+>|placeholder|todo|tbd|n\/a|stub)$/i;
 
 export function invalid(message: string, field: string): never {
 	throw new UlwLoopError(message, "ULW_LOOP_QUALITY_GATE_INVALID", { details: { field } });

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

@@ -1,5 +1,12 @@
-import { resolve } from "node:path";
-import { isWithinAttemptDir } from "./paths.js";
+import { aggregateQualityGateDefects } from "./quality-gate-aggregate.js";
+import {
+	artifactCompatible,
+	artifactMap,
+	checkFile,
+	parseArtifactRefs,
+	referencedArtifacts,
+	surfaceField,
+} from "./quality-gate-artifacts.js";
 import {
 	emptyBlockers,
 	invalid,
@@ -10,13 +17,8 @@ import {
 	textField,
 } from "./quality-gate-fields.js";
 import { adversarialVerdict, codeQualityStatusField, passedVerdict } from "./quality-gate-verdicts.js";
-import { reviewerRolesFor, type UlwLoopToolkitSurface } from "./surface.js";
-import type {
-	UlwLoopManualQaArtifactKind,
-	UlwLoopManualQaArtifactRef,
-	UlwLoopManualQaSurface,
-	UlwLoopQualityGate,
-} from "./types.js";
+import { GATE_SECTION_BY_ACCEPTOR, REQUIRED_GATE_SECTIONS_BY_SURFACE, type UlwLoopToolkitSurface } from "./surface.js";
+import type { UlwLoopManualQaArtifactRef, UlwLoopQualityGate } from "./types.js";
 
 export {
 	classifyExternalAuthorizationBlocker,
@@ -43,109 +45,35 @@ function reviewerRoleField(value: unknown, expected: string, field: string): str
 	return expected;
 }
 
-function surfaceField(value: unknown, field: string): UlwLoopManualQaSurface {
-	if (
-		value === "cli" ||
-		value === "http" ||
-		value === "tmux" ||
-		value === "browser" ||
-		value === "gui" ||
-		value === "data"
-	)
-		return value;
-	invalid(`${field} must be a supported manual QA surface.`, field);
-}
-
-function kindField(value: unknown, field: string): UlwLoopManualQaArtifactKind {
-	if (
-		value === "cli-transcript" ||
-		value === "log" ||
-		value === "screenshot" ||
-		value === "image" ||
-		value === "http-dump" ||
-		value === "data-diff"
-	)
-		return value;
-	invalid(`${field} must be a supported artifact kind.`, field);
-}
-
-function artifactCompatible(surface: UlwLoopManualQaSurface, kind: UlwLoopManualQaArtifactKind): boolean {
-	switch (surface) {
-		case "cli":
-		case "tmux":
-			return kind === "cli-transcript" || kind === "log";
-		case "http":
-			return kind === "http-dump";
-		case "browser":
-		case "gui":
-			return kind === "screenshot" || kind === "image";
-		case "data":
-			return kind === "data-diff";
-		default:
-			invalid("manualQa.surfaceEvidence has an unsupported surface.", "manualQa.surfaceEvidence.surface");
-	}
-}
-
-function checkFile(path: string, field: string, opts?: ValidateQualityGateOptions): void {
-	if (opts?.repoRoot === undefined || opts.fs === undefined) return;
-	const absolute = resolve(opts.repoRoot, path);
-	if (!opts.fs.existsSync(absolute)) invalid(`${field} must point to an existing artifact.`, field);
-	if (opts.fs.statSync(absolute).size <= 0) invalid(`${field} must point to a non-empty artifact.`, field);
-	if (opts.currentAttemptDir !== undefined && opts.repoRoot !== undefined) {
-		const attemptRoot = resolve(opts.repoRoot, opts.currentAttemptDir);
-		if (!isWithinAttemptDir(absolute, attemptRoot))
-			invalid(
-				`${field} (${path}) must point to an artifact from the current attempt (${opts.currentAttemptDir}).`,
-				field,
-			);
-	}
-}
-
-function artifactMap(refs: readonly UlwLoopManualQaArtifactRef[]): Map<string, UlwLoopManualQaArtifactRef> {
-	const byId = new Map<string, UlwLoopManualQaArtifactRef>();
-	for (const ref of refs) {
-		if (byId.has(ref.id)) invalid(`manualQa.artifactRefs contains duplicate ${ref.id}.`, "manualQa.artifactRefs");
-		byId.set(ref.id, ref);
-	}
-	return byId;
-}
-
-function parseArtifactRefs(value: unknown, opts?: ValidateQualityGateOptions): readonly UlwLoopManualQaArtifactRef[] {
-	if (!Array.isArray(value) || value.length === 0)
-		invalid("manualQa.artifactRefs must not be empty.", "manualQa.artifactRefs");
-	return value.map((item, index) => {
-		const ref = section(item, `manualQa.artifactRefs[${index}]`);
-		const path = textField(ref["path"], `manualQa.artifactRefs[${index}].path`);
-		checkFile(path, `manualQa.artifactRefs[${index}].path`, opts);
-		return {
-			id: textField(ref["id"], `manualQa.artifactRefs[${index}].id`),
-			kind: kindField(ref["kind"], `manualQa.artifactRefs[${index}].kind`),
-			description: textField(ref["description"], `manualQa.artifactRefs[${index}].description`),
-			path,
-		};
-	});
-}
-
-function referencedArtifacts(
+function reviewerAcceptorField(
 	value: unknown,
-	field: string,
-	byId: ReadonlyMap<string, UlwLoopManualQaArtifactRef>,
-): readonly UlwLoopManualQaArtifactRef[] {
-	return stringArray(value, field).map((id) => {
-		const artifact = byId.get(id);
-		if (artifact === undefined) invalid(`${field} references unknown artifact ${id}.`, field);
-		return artifact;
-	});
+	surface: UlwLoopToolkitSurface,
+	sectionName: "manualQa" | "gateReview",
+): string {
+	const field = `${sectionName}.by`;
+	const actual = textField(value, field);
+	const accepted = GATE_SECTION_BY_ACCEPTOR[surface][sectionName];
+	if (accepted === undefined || !accepted.includes(actual))
+		invalid(`${field} must be one of ${accepted?.join(", ") ?? "the configured reviewers"}.`, field);
+	return actual;
 }
 
 export function validateQualityGate(input: unknown, opts?: ValidateQualityGateOptions): UlwLoopQualityGate {
-	const reviewerRoles = reviewerRolesFor(opts?.reviewerSurface ?? "lazycodex");
+	const surface = opts?.reviewerSurface ?? "lazycodex";
+	aggregateQualityGateDefects(input, opts);
 	const gate = section(input, "qualityGate");
-	const codeReview = section(gate["codeReview"], "codeReview");
+	const requiredSections = REQUIRED_GATE_SECTIONS_BY_SURFACE[surface];
+	for (const sectionName of requiredSections) section(gate[sectionName], sectionName);
+	if (surface === "omo-senpi" && gate["codeReview"] !== undefined)
+		invalid("omo-senpi gate has no codeReview lane.", "codeReview");
 	const manualQa = section(gate["manualQa"], "manualQa");
 	const gateReview = section(gate["gateReview"], "gateReview");
 	const iteration = section(gate["iteration"], "iteration");
 	const coverage = section(gate["criteriaCoverage"], "criteriaCoverage");
+	const manualQaBy = reviewerAcceptorField(manualQa["by"], surface, "manualQa");
+	const gateReviewBy = reviewerAcceptorField(gateReview["by"], surface, "gateReview");
+	if (surface === "lazycodex")
+		reviewerRoleField(section(gate["codeReview"], "codeReview")["by"], "lazycodex-code-reviewer", "codeReview.by");
 	const totalCriteria = numberField(coverage["totalCriteria"], "criteriaCoverage.totalCriteria");
 	const passCount = numberField(coverage["passCount"], "criteriaCoverage.passCount");
 	if (passCount < totalCriteria)
@@ -154,21 +82,11 @@ export function validateQualityGate(input: unknown, opts?: ValidateQualityGateOp
 	const byId = artifactMap(artifactRefs);
 	const surfaceEvidence = parseSurfaceEvidence(manualQa["surfaceEvidence"], byId);
 	const adversarialCases = parseAdversarialCases(manualQa["adversarialCases"], byId);
-	const codeReportPath = textField(codeReview["reportPath"], "codeReview.reportPath");
 	const gateReportPath = textField(gateReview["reportPath"], "gateReview.reportPath");
-	checkFile(codeReportPath, "codeReview.reportPath", opts);
 	checkFile(gateReportPath, "gateReview.reportPath", opts);
-	return {
-		codeReview: {
-			by: reviewerRoleField(codeReview["by"], reviewerRoles.codeReview, "codeReview.by"),
-			recommendation: literal(codeReview["recommendation"], "APPROVE", "codeReview.recommendation"),
-			codeQualityStatus: codeQualityStatusField(codeReview["codeQualityStatus"], "codeReview.codeQualityStatus"),
-			reportPath: codeReportPath,
-			evidence: textField(codeReview["evidence"], "codeReview.evidence"),
-			blockers: emptyBlockers(codeReview["blockers"], "codeReview.blockers"),
-		},
+	const common = {
 		manualQa: {
-			by: reviewerRoleField(manualQa["by"], reviewerRoles.manualQa, "manualQa.by"),
+			by: manualQaBy,
 			status: literal(manualQa["status"], "passed", "manualQa.status"),
 			evidence: textField(manualQa["evidence"], "manualQa.evidence"),
 			surfaceEvidence,
@@ -176,7 +94,7 @@ export function validateQualityGate(input: unknown, opts?: ValidateQualityGateOp
 			artifactRefs,
 		},
 		gateReview: {
-			by: reviewerRoleField(gateReview["by"], reviewerRoles.gateReview, "gateReview.by"),
+			by: gateReviewBy,
 			recommendation: literal(gateReview["recommendation"], "APPROVE", "gateReview.recommendation"),
 			reportPath: gateReportPath,
 			evidence: textField(gateReview["evidence"], "gateReview.evidence"),
@@ -200,6 +118,22 @@ export function validateQualityGate(input: unknown, opts?: ValidateQualityGateOp
 			),
 		},
 	};
+	if (surface === "omo-senpi") return { surface, ...common };
+	const codeReview = section(gate["codeReview"], "codeReview");
+	const codeReportPath = textField(codeReview["reportPath"], "codeReview.reportPath");
+	checkFile(codeReportPath, "codeReview.reportPath", opts);
+	return {
+		surface,
+		...common,
+		codeReview: {
+			by: "lazycodex-code-reviewer",
+			recommendation: literal(codeReview["recommendation"], "APPROVE", "codeReview.recommendation"),
+			codeQualityStatus: codeQualityStatusField(codeReview["codeQualityStatus"], "codeReview.codeQualityStatus"),
+			reportPath: codeReportPath,
+			evidence: textField(codeReview["evidence"], "codeReview.evidence"),
+			blockers: emptyBlockers(codeReview["blockers"], "codeReview.blockers"),
+		},
+	};
 }
 
 function parseSurfaceEvidence(

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

@@ -1,5 +1,6 @@
 // biome-ignore-all format: compact port must stay within the requested pure LOC budget.
 
+import { codexSnapshotMismatchError } from "./checkpoint-reconciliation.js";
 import { readCodexGoalSnapshotInput, reconcileCodexGoalSnapshot } from "./codex-goal-snapshot.js";
 import { codexGoalMode, compatibleCodexObjectives, expectedCodexObjective, isFinalRunCompletionCandidate } from "./goal-status.js";
 import type { UlwLoopScope } from "./paths.js";
@@ -55,8 +56,9 @@ export async function recordFinalReviewBlockers(
 
 		const snapshot = await readCodexGoalSnapshotInput(args.codexGoalJson, repoRoot);
 		const aggregate = codexGoalMode(plan) === "aggregate";
-		const reconciliation = reconcileCodexGoalSnapshot(snapshot, { expectedObjective: expectedCodexObjective(plan, goal), ...(aggregate ? { acceptedObjectives: compatibleCodexObjectives(plan) } : {}), allowedStatuses: ["active"], requireSnapshot: true, requireComplete: false });
-		if (!reconciliation.ok) ulwLoopError(reconciliation.errors.join(" "), "ulw_loop_codex_snapshot_mismatch");
+		const expected = expectedCodexObjective(plan, goal);
+		const reconciliation = reconcileCodexGoalSnapshot(snapshot, { expectedObjective: expected, ...(aggregate ? { acceptedObjectives: compatibleCodexObjectives(plan) } : {}), allowedStatuses: ["active"], requireSnapshot: true, requireComplete: false });
+		if (!reconciliation.ok) throw codexSnapshotMismatchError({ reconciliation, snapshot, expectedObjective: expected });
 
 		const now = iso();
 		for (const field of BLOCKER_FIELDS) Reflect.deleteProperty(goal, field);