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

package/packages/omo-codex/plugin/components/ulw-loop/dist/surface.js

@@ -0,0 +1,50 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+export const REVIEWER_ROLES_BY_SURFACE = {
+    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 = new Set(Object.values(REVIEWER_ROLES_BY_SURFACE).map((roles) => roles.gateReview));
+export function reviewerRolesFor(surface) {
+    return REVIEWER_ROLES_BY_SURFACE[surface];
+}
+export const SURFACE_MARKER_FILENAME = "surface.json";
+const SURFACE_ENV_KEY = "OMO_AGENT_TOOLKIT_SURFACE";
+function parseSurface(value) {
+    return value === "lazycodex" || value === "omo-senpi" ? value : null;
+}
+// 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) {
+    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) {
+    try {
+        if (!existsSync(markerPath))
+            return null;
+        const parsed = JSON.parse(readFileSync(markerPath, "utf8"));
+        return parseSurface(parsed["surface"]);
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return null;
+        throw error;
+    }
+}

package/packages/omo-codex/plugin/components/ulw-loop/hooks/hooks.json

@@ -7,7 +7,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook user-prompt-submit --with-ultrawork",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.0.0-beta.30) Checking Ulw-Loop Steering"
+						"statusMessage": "(OmO 5.0.0-beta.31) Checking Ulw-Loop Steering"
 					}
 				]
 			}
@@ -20,7 +20,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook pre-tool-use",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.30) Enforcing Unlimited Ulw-Loop Budget"
+						"statusMessage": "(OmO 5.0.0-beta.31) Enforcing Unlimited Ulw-Loop Budget"
 					}
 				]
 			},
@@ -31,7 +31,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook pre-tool-use-spawn",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.30) Guarding Ulw-Loop Spawns"
+						"statusMessage": "(OmO 5.0.0-beta.31) Guarding Ulw-Loop Spawns"
 					}
 				]
 			}
@@ -43,7 +43,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook stop",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.0.0-beta.30) Checking Ulw-Loop Resume"
+						"statusMessage": "(OmO 5.0.0-beta.31) Checking Ulw-Loop Resume"
 					}
 				]
 			}

package/packages/omo-codex/plugin/components/ulw-loop/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-ulw-loop",
-	"version": "5.0.0-beta.30",
+	"version": "5.0.0-beta.31",
 	"description": "Codex plugin: durable repo-native multi-goal orchestration with embedded success criteria and observable evidence audit.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",

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

@@ -28,6 +28,7 @@ import {
 	sameBlockerOccurrences,
 	validateQualityGate,
 } from "./quality-gate.js";
+import { resolveToolkitSurface } from "./surface.js";
 import type {
 	UlwLoopAggregateCompletion,
 	UlwLoopItem,
@@ -230,6 +231,7 @@ export async function checkpointUlwLoop(
 				qualityGate = validateQualityGate(await readJsonInput(args.qualityGateJson, repoRoot), {
 					repoRoot,
 					fs: QUALITY_GATE_FS,
+					reviewerSurface: resolveToolkitSurface(),
 					...(plan.evidenceLayoutVersion === 2
 						? { currentAttemptDir: ulwLoopAttemptEvidenceDir(goal.id, goal.attempt, scope) }
 						: {}),

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

@@ -5,6 +5,7 @@ import {
 	isEssentialCriterion,
 	isFinalRunCompletionCandidate,
 } from "./goal-status.js";
+import { resolveToolkitSurface, reviewerRolesFor, type UlwLoopToolkitSurface } from "./surface.js";
 import type { UlwLoopCodexGoalMode, UlwLoopItem, UlwLoopPlan, UlwLoopSuccessCriterion } from "./types.js";
 
 export interface CodexCreateGoalPayload {
@@ -20,11 +21,13 @@ export function buildCodexGoalInstruction(args: {
 	readonly plan: UlwLoopPlan;
 	readonly goal: UlwLoopItem;
 	readonly isFinal?: boolean;
+	readonly surface?: UlwLoopToolkitSurface;
 }): UlwLoopGoalInstruction {
 	const mode = codexGoalMode(args.plan);
 	const createGoal = buildCreateGoalPayload(args.plan, args.goal);
 	const isFinal = args.isFinal ?? isFinalRunCompletionCandidate(args.plan, args.goal);
-	return { text: buildText(mode, args.plan, args.goal, createGoal, isFinal), json: createGoal };
+	const surface = args.surface ?? resolveToolkitSurface();
+	return { text: buildText(mode, args.plan, args.goal, createGoal, isFinal, surface), json: createGoal };
 }
 
 function buildCreateGoalPayload(plan: UlwLoopPlan, goal: UlwLoopItem): CodexCreateGoalPayload {
@@ -37,6 +40,7 @@ function buildText(
 	goal: UlwLoopItem,
 	createGoal: CodexCreateGoalPayload,
 	isFinal: boolean,
+	surface: UlwLoopToolkitSurface,
 ): string {
 	return joinLines([
 		mode === "aggregate" ? "UlwLoop aggregate-goal handoff" : "UlwLoop active-goal handoff",
@@ -54,7 +58,7 @@ function buildText(
 		"- Goals are unlimited. Do not add numeric limits.",
 		...modeConstraintLines(mode, isFinal),
 		...evidenceLayoutLines(plan),
-		finalSection(plan, goal, isFinal, mode === "aggregate"),
+		finalSection(plan, goal, isFinal, mode === "aggregate", surface),
 		...checkpointLines(plan, mode),
 		"",
 		"create_goal payload:",
@@ -112,7 +116,14 @@ function evidenceLayoutLines(plan: UlwLoopPlan): string[] {
 	];
 }
 
-function finalSection(plan: UlwLoopPlan, goal: UlwLoopItem, isFinal: boolean, aggregate: boolean): string {
+function finalSection(
+	plan: UlwLoopPlan,
+	goal: UlwLoopItem,
+	isFinal: boolean,
+	aggregate: boolean,
+	surface: UlwLoopToolkitSurface,
+): string {
+	const roles = reviewerRolesFor(surface);
 	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);
@@ -122,8 +133,8 @@ function finalSection(plan: UlwLoopPlan, goal: UlwLoopItem, isFinal: boolean, ag
 		"Final story — run mandatory quality gate before update_goal:",
 		"- Run targeted verification for changed behavior.",
 		"- Confirm every manualQa artifact path exists and has non-zero size.",
-		"- First spawn lazycodex-code-reviewer and lazycodex-qa-executor in parallel (fork_context: false on the v1 surface; fork_turns: \"none\" on v2). Include the original brief, goal objectives, desired user-visible outcome, diff, and evidence; wait for BOTH to return and confirm their report artifacts exist on disk (code-review report + manualQa matrix).",
-		"- Only then spawn lazycodex-gate-reviewer (same fork settings), passing those artifact paths.",
+		`- First spawn ${roles.codeReview} and ${roles.manualQa} in parallel (fork_context: false on the v1 surface; fork_turns: "none" on v2). Include the original brief, goal objectives, desired user-visible outcome, diff, and evidence; wait for BOTH to return and confirm their report artifacts exist on disk (code-review report + manualQa matrix).`,
+		`- Only then spawn ${roles.gateReview} (same fork settings), passing those artifact paths.`,
 		"- Require clean codeReview, manualQa, gateReview, iteration, and criteriaCoverage. criteriaCoverage must summarize originalIntent, desiredOutcome, and userOutcomeReview; counts alone are not approval.",
 		"- On a reviewer REJECT, fix only the cited blockers, rerun the affected verification/Manual-QA, and re-review the delta at most TWICE; if blockers remain, record them and surface to the user.",
 		"- If codeQualityStatus is WATCH, include the WATCH notes verbatim in your final user-facing message.",

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

@@ -10,6 +10,7 @@ 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,
@@ -17,12 +18,6 @@ import type {
 	UlwLoopQualityGate,
 } from "./types.js";
 
-const REVIEWER_ROLES = {
-	codeReview: "lazycodex-code-reviewer",
-	manualQa: "lazycodex-qa-executor",
-	gateReview: "lazycodex-gate-reviewer",
-} as const;
-
 export {
 	classifyExternalAuthorizationBlocker,
 	clearGoalBlockerFields,
@@ -36,12 +31,13 @@ export interface QualityGateFs {
 }
 
 export interface ValidateQualityGateOptions {
-	readonly repoRoot: string;
-	readonly fs: QualityGateFs;
+	readonly repoRoot?: string;
+	readonly fs?: QualityGateFs;
 	readonly currentAttemptDir?: string;
+	readonly reviewerSurface?: UlwLoopToolkitSurface;
 }
 
-function reviewerRoleField<T extends string>(value: unknown, expected: T, field: string): T {
+function reviewerRoleField(value: unknown, expected: string, field: string): string {
 	const actual = textField(value, field);
 	if (actual !== expected) invalid(`${field} must be ${expected}.`, field);
 	return expected;
@@ -91,11 +87,11 @@ function artifactCompatible(surface: UlwLoopManualQaSurface, kind: UlwLoopManual
 }
 
 function checkFile(path: string, field: string, opts?: ValidateQualityGateOptions): void {
-	if (opts === undefined) return;
+	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) {
+	if (opts.currentAttemptDir !== undefined && opts.repoRoot !== undefined) {
 		const attemptRoot = resolve(opts.repoRoot, opts.currentAttemptDir);
 		if (!isWithinAttemptDir(absolute, attemptRoot))
 			invalid(
@@ -143,6 +139,7 @@ function referencedArtifacts(
 }
 
 export function validateQualityGate(input: unknown, opts?: ValidateQualityGateOptions): UlwLoopQualityGate {
+	const reviewerRoles = reviewerRolesFor(opts?.reviewerSurface ?? "lazycodex");
 	const gate = section(input, "qualityGate");
 	const codeReview = section(gate["codeReview"], "codeReview");
 	const manualQa = section(gate["manualQa"], "manualQa");
@@ -163,7 +160,7 @@ export function validateQualityGate(input: unknown, opts?: ValidateQualityGateOp
 	checkFile(gateReportPath, "gateReview.reportPath", opts);
 	return {
 		codeReview: {
-			by: reviewerRoleField(codeReview["by"], REVIEWER_ROLES.codeReview, "codeReview.by"),
+			by: reviewerRoleField(codeReview["by"], reviewerRoles.codeReview, "codeReview.by"),
 			recommendation: literal(codeReview["recommendation"], "APPROVE", "codeReview.recommendation"),
 			codeQualityStatus: codeQualityStatusField(codeReview["codeQualityStatus"], "codeReview.codeQualityStatus"),
 			reportPath: codeReportPath,
@@ -171,7 +168,7 @@ export function validateQualityGate(input: unknown, opts?: ValidateQualityGateOp
 			blockers: emptyBlockers(codeReview["blockers"], "codeReview.blockers"),
 		},
 		manualQa: {
-			by: reviewerRoleField(manualQa["by"], REVIEWER_ROLES.manualQa, "manualQa.by"),
+			by: reviewerRoleField(manualQa["by"], reviewerRoles.manualQa, "manualQa.by"),
 			status: literal(manualQa["status"], "passed", "manualQa.status"),
 			evidence: textField(manualQa["evidence"], "manualQa.evidence"),
 			surfaceEvidence,
@@ -179,7 +176,7 @@ export function validateQualityGate(input: unknown, opts?: ValidateQualityGateOp
 			artifactRefs,
 		},
 		gateReview: {
-			by: reviewerRoleField(gateReview["by"], REVIEWER_ROLES.gateReview, "gateReview.by"),
+			by: reviewerRoleField(gateReview["by"], reviewerRoles.gateReview, "gateReview.by"),
 			recommendation: literal(gateReview["recommendation"], "APPROVE", "gateReview.recommendation"),
 			reportPath: gateReportPath,
 			evidence: textField(gateReview["evidence"], "gateReview.evidence"),

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

@@ -5,6 +5,7 @@ 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 } from "./surface.js";
 import type { UlwLoopPlan } from "./types.js";
 
 // spawn_agent = v1; collaborationspawn_agent = the delimiter-free flattened v2
@@ -12,7 +13,7 @@ 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 GATE_MESSAGE_PATTERN = /lazycodex-gate-reviewer|omo-senpi-gate-reviewer|final gate review/i;
 
 export function applySpawnGuards(payload: PreToolUsePayload): string {
 	if (payload.hook_event_name !== "PreToolUse" || !SPAWN_TOOL_TOKENS.has(payload.tool_name)) return "";
@@ -77,7 +78,7 @@ function isGateReviewerSpawn(toolInput: unknown): boolean {
 	if (typeof toolInput !== "object" || toolInput === null) return false;
 	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") return GATE_REVIEWER_AGENT_NAMES.has(agentType);
 	const message = record["message"];
 	return typeof message === "string" && GATE_MESSAGE_PATTERN.test(message);
 }

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

@@ -0,0 +1,73 @@
+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 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-final.test.ts

@@ -1,5 +1,5 @@
 import { writeFile } from "node:fs/promises";
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it } from "vitest";
 
 import { checkpointUlwLoop } from "../src/checkpoint.js";
 import { ulwLoopBriefPath } from "../src/paths.js";
@@ -7,6 +7,49 @@ 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";
 
+describe("checkpointUlwLoop final story surface resolution", () => {
+	afterEach(() => {
+		delete process.env["OMO_AGENT_TOOLKIT_SURFACE"];
+	});
+
+	it("#given the omo-senpi surface #when the gate names omo-senpi reviewers #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 result = await checkpointUlwLoop(repo, {
+			goalId: "G002",
+			status: "complete",
+			evidence: "final work complete and validation passed",
+			codexGoalJson: snapshot("complete"),
+			qualityGateJson: await qualityGateJson(repo, undefined, "G001-finished", "omo-senpi"),
+		});
+
+		expect(result.aggregateCompletion?.status).toBe("complete");
+	});
+
+	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("requires quality-gate-json for the final goal complete", async () => {
 		const repo = await repoWith(

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

@@ -6,6 +6,7 @@ import type { UlwLoopItem, UlwLoopPlan, UlwLoopSuccessCriterion } from "../src/t
 
 const NOW = "2026-05-23T00:00:00.000Z";
 const FINAL_REVIEW_ROLES = ["lazycodex-code-reviewer", "lazycodex-qa-executor", "lazycodex-gate-reviewer"] as const;
+const SENPI_REVIEW_ROLES = ["omo-senpi-code-reviewer", "omo-senpi-qa-executor", "omo-senpi-gate-reviewer"] as const;
 const QUALITY_GATE_SECTIONS = ["codeReview", "manualQa", "gateReview", "iteration", "criteriaCoverage"] as const;
 
 function makeCriterion(overrides: Partial<UlwLoopSuccessCriterion> = {}): UlwLoopSuccessCriterion {
@@ -94,6 +95,30 @@ describe("buildCodexGoalInstruction aggregate mode", () => {
 		expect(text).toContain("checkpoint");
 	});
 
+	it("#given a final story on the omo-senpi surface #when rendering instructions #then names the omo-senpi reviewers only", () => {
+		const { text } = buildCodexGoalInstruction({
+			plan: makePlan({ codexGoalMode: "aggregate" }),
+			goal: makeGoal(),
+			isFinal: true,
+			surface: "omo-senpi",
+		});
+
+		expectTextToContainAll(text, SENPI_REVIEW_ROLES);
+		for (const role of FINAL_REVIEW_ROLES) expect(text).not.toContain(role);
+	});
+
+	it("#given a final story with the explicit lazycodex surface #when rendering instructions #then keeps the lazycodex reviewers", () => {
+		const { text } = buildCodexGoalInstruction({
+			plan: makePlan({ codexGoalMode: "aggregate" }),
+			goal: makeGoal(),
+			isFinal: true,
+			surface: "lazycodex",
+		});
+
+		expectTextToContainAll(text, FINAL_REVIEW_ROLES);
+		for (const role of SENPI_REVIEW_ROLES) expect(text).not.toContain(role);
+	});
+
 	it("#given a scoped plan #when rendering final commands #then includes the session id option", () => {
 		const { text } = buildCodexGoalInstruction({
 			plan: makePlan({

package/packages/omo-codex/plugin/components/ulw-loop/test/fixtures/quality-gate-builder.ts

@@ -1,6 +1,8 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
+import { reviewerRolesFor, type UlwLoopToolkitSurface } from "../../src/surface.js";
+
 // v2 evidence layout: artifacts must live inside the goal's current attempt dir
 export function qaDirFor(goalId: string, attempt = 1, sessionId = "session"): string {
 	return `.omo/evidence/ulw/${sessionId}/${goalId}/a${attempt}`;
@@ -25,13 +27,15 @@ export async function qualityGateJson(
 	repoRoot: string,
 	cliArtifactPath?: string,
 	goalId = "G001-finished",
+	surface: UlwLoopToolkitSurface = "lazycodex",
 ): Promise<string> {
+	const roles = reviewerRolesFor(surface);
 	const qaDir = qaDirFor(goalId);
 	await writeQualityGateArtifacts(repoRoot, qaDir);
 	const cliPath = cliArtifactPath ?? `${qaDir}/cli-pass.txt`;
 	return JSON.stringify({
 		codeReview: {
-			by: "lazycodex-code-reviewer",
+			by: roles.codeReview,
 			recommendation: "APPROVE",
 			codeQualityStatus: "CLEAR",
 			reportPath: `${qaDir}/code-review.md`,
@@ -39,7 +43,7 @@ export async function qualityGateJson(
 			blockers: [],
 		},
 		manualQa: {
-			by: "lazycodex-qa-executor",
+			by: roles.manualQa,
 			status: "passed",
 			evidence: "Ran CLI checkpoint validation with artifact-backed evidence.",
 			surfaceEvidence: [
@@ -78,7 +82,7 @@ export async function qualityGateJson(
 			],
 		},
 		gateReview: {
-			by: "lazycodex-gate-reviewer",
+			by: roles.gateReview,
 			recommendation: "APPROVE",
 			reportPath: `${qaDir}/gate-review.md`,
 			evidence: "Verified all criteria and artifact evidence.",

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

@@ -75,9 +75,9 @@ function gateWith(overrides: Record<string, unknown>): Record<string, unknown> {
 	return { ...BASE_GATE, ...overrides };
 }
 
-function qualityGateError(input: unknown): UlwLoopError {
+function qualityGateError(input: unknown, surface?: "lazycodex" | "omo-senpi"): UlwLoopError {
 	try {
-		validateQualityGate(input);
+		validateQualityGate(input, surface === undefined ? undefined : { reviewerSurface: surface });
 	} catch (error) {
 		if (error instanceof UlwLoopError) return error;
 		throw error;
@@ -85,6 +85,20 @@ function qualityGateError(input: unknown): UlwLoopError {
 	throw new Error("Expected UlwLoopError");
 }
 
+function senpiGate(): Record<string, unknown> {
+	return gateWith({
+		codeReview: { ...BASE_GATE.codeReview, by: "omo-senpi-code-reviewer" },
+		manualQa: { ...BASE_GATE.manualQa, by: "omo-senpi-qa-executor" },
+		gateReview: { ...BASE_GATE.gateReview, by: "omo-senpi-gate-reviewer" },
+		criteriaCoverage: {
+			...BASE_GATE.criteriaCoverage,
+			originalIntent: "User wanted the senpi surface to accept honest reviewer attribution.",
+			desiredOutcome: "A gate naming the omo-senpi reviewers validates on the omo-senpi surface.",
+			userOutcomeReview: "The senpi-surface gate passed with truthful reviewer identities.",
+		},
+	});
+}
+
 describe("validateQualityGate reviewer roles", () => {
 	it("#given arbitrary reviewer role names #when validated #then each role field is rejected", () => {
 		const cases = [
@@ -106,6 +120,35 @@ describe("validateQualityGate reviewer roles", () => {
 		}
 	});
 
+	it("#given omo-senpi reviewer identities #when validated on the omo-senpi surface #then the gate is accepted", () => {
+		expect(() => validateQualityGate(senpiGate(), { reviewerSurface: "omo-senpi" })).not.toThrow();
+	});
+
+	it("#given lazycodex identities #when validated on the omo-senpi surface #then each role names the omo-senpi identity", () => {
+		const error = qualityGateError(gateWith({}), "omo-senpi");
+		expect(error.code).toBe("ULW_LOOP_QUALITY_GATE_INVALID");
+		expect(error.message).toContain("omo-senpi-code-reviewer");
+	});
+
+	it("#given omo-senpi identities #when validated on the default lazycodex surface #then the gate is rejected", () => {
+		const error = qualityGateError(senpiGate());
+		expect(error.code).toBe("ULW_LOOP_QUALITY_GATE_INVALID");
+		expect(error.message).toContain("lazycodex-code-reviewer");
+	});
+
+	it("#given swapped omo-senpi reviewer roles #when validated on the omo-senpi surface #then section-specific roles are enforced", () => {
+		const swapped = gateWith({
+			codeReview: { ...BASE_GATE.codeReview, by: "omo-senpi-qa-executor" },
+			manualQa: { ...BASE_GATE.manualQa, by: "omo-senpi-qa-executor" },
+			gateReview: { ...BASE_GATE.gateReview, by: "omo-senpi-gate-reviewer" },
+		});
+
+		const error = qualityGateError(swapped, "omo-senpi");
+
+		expect(error.code).toBe("ULW_LOOP_QUALITY_GATE_INVALID");
+		expect(error.message).toContain("codeReview.by");
+	});
+
 	it("#given swapped LazyCodex reviewer roles #when validated #then section-specific roles are enforced", () => {
 		const cases = [
 			{

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

@@ -146,6 +146,26 @@ describe("applySpawnGuards gate-artifact guard", () => {
 		expect(parsed.permissionDecisionReason).toContain("g1-code-review.md");
 	});
 
+	it("#given an omo-senpi gate spawn by agent_type without artifacts #when guarded #then denies naming the missing path", () => {
+		writeGoals();
+
+		const output = applySpawnGuards(
+			payload("collaborationspawn_agent", { agent_type: "omo-senpi-gate-reviewer", message: "audit the artifacts" }),
+		);
+
+		const parsed = deny(output);
+		expect(parsed.permissionDecision).toBe("deny");
+		expect(parsed.permissionDecisionReason).toContain("g1-code-review.md");
+	});
+
+	it("#given an omo-senpi gate reviewer named in the message #when guarded #then still denies", () => {
+		writeGoals();
+
+		const output = applySpawnGuards(payload("spawn_agent", { message: "spawn omo-senpi-gate-reviewer now" }));
+
+		expect(deny(output).permissionDecision).toBe("deny");
+	});
+
 	it("#given a gate spawn identified by message only #when guarded #then still denies", () => {
 		writeGoals();