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

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

@@ -0,0 +1,101 @@
+import { existsSync, statSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import { validateQualityGate } from "../src/quality-gate.js";
+import { UlwLoopError } from "../src/types.js";
+
+const opts = { repoRoot: process.cwd(), fs: { existsSync, statSync }, reviewerSurface: "omo-senpi" as const };
+
+describe("aggregated quality gate validation", () => {
+	it("#given four independent defects #when validating #then reports all defects in one error", () => {
+		const gate = {
+			manualQa: {
+				by: "main-session",
+				status: "passed",
+				evidence: "placeholder",
+				surfaceEvidence: [],
+				adversarialCases: [],
+				artifactRefs: [
+					{ id: "missing", kind: "cli-transcript", description: "artifact", path: "does-not-exist.txt" },
+				],
+			},
+			gateReview: {
+				by: "category:deep",
+				recommendation: "REJECT",
+				reportPath: "test/fixtures/artifacts/gate-review.md",
+				blockers: [],
+			},
+			iteration: { fullRerun: true, status: "passed", rerunCommands: ["test"], evidence: "rerun" },
+			criteriaCoverage: {
+				totalCriteria: 1,
+				passCount: 1,
+				originalIntent: "intent",
+				desiredOutcome: "outcome",
+				userOutcomeReview: "review",
+				adversarialClassesCovered: ["none"],
+			},
+		};
+		try {
+			validateQualityGate(gate, opts);
+			throw new Error("expected validation failure");
+		} catch (error) {
+			expect(error).toBeInstanceOf(UlwLoopError);
+			if (!(error instanceof UlwLoopError)) throw error;
+			expect(error.code).toBe("ULW_LOOP_QUALITY_GATE_INVALID");
+			expect(error.details?.["field"]).toBe("manualQa.evidence");
+			expect(error.details?.["fields"]).toEqual(
+				expect.arrayContaining([
+					{ field: "manualQa.evidence", message: expect.stringContaining("placeholder") },
+					{ field: "gateReview.evidence", message: expect.stringContaining("non-empty") },
+					{ field: "gateReview.recommendation", message: expect.stringContaining("APPROVE") },
+					{ field: "manualQa.artifactRefs[0].path", message: expect.stringContaining("existing") },
+				]),
+			);
+		}
+	});
+
+	it("#given more than twenty-five defects #when validating #then caps the list and flags truncation", () => {
+		const refs = Array.from({ length: 30 }, (_, index) => ({
+			id: `ref-${index}`,
+			kind: "cli-transcript",
+			description: "artifact",
+			path: `does-not-exist-${index}.txt`,
+		}));
+		const gate = {
+			manualQa: {
+				by: "main-session",
+				status: "passed",
+				evidence: "real evidence",
+				surfaceEvidence: [],
+				adversarialCases: [],
+				artifactRefs: refs,
+			},
+			gateReview: {
+				by: "category:deep",
+				recommendation: "APPROVE",
+				reportPath: "test/fixtures/artifacts/gate-review.md",
+				evidence: "gate evidence",
+				blockers: [],
+			},
+			iteration: { fullRerun: true, status: "passed", rerunCommands: ["test"], evidence: "rerun" },
+			criteriaCoverage: {
+				totalCriteria: 1,
+				passCount: 1,
+				originalIntent: "intent",
+				desiredOutcome: "outcome",
+				userOutcomeReview: "review",
+				adversarialClassesCovered: ["none"],
+			},
+		};
+		try {
+			validateQualityGate(gate, opts);
+			throw new Error("expected validation failure");
+		} catch (error) {
+			expect(error).toBeInstanceOf(UlwLoopError);
+			if (!(error instanceof UlwLoopError)) throw error;
+			const fields = error.details?.["fields"];
+			expect(Array.isArray(fields) && fields.length).toBe(25);
+			expect(error.details?.["truncated"]).toBe(true);
+			expect(error.message).toContain("25+");
+		}
+	});
+});

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,22 @@ function qualityGateError(input: unknown): UlwLoopError {
 	throw new Error("Expected UlwLoopError");
 }
 
+function senpiGate(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+	const { codeReview: _codeReview, ...withoutCodeReview } = BASE_GATE;
+	return {
+		...withoutCodeReview,
+		manualQa: { ...BASE_GATE.manualQa, by: "main-session" },
+		gateReview: { ...BASE_GATE.gateReview, by: "category:deep" },
+		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.",
+		},
+		...overrides,
+	};
+}
+
 describe("validateQualityGate reviewer roles", () => {
 	it("#given arbitrary reviewer role names #when validated #then each role field is rejected", () => {
 		const cases = [
@@ -106,6 +122,34 @@ 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 a codeReview lane #when validated on the omo-senpi surface #then it is rejected", () => {
+		const error = qualityGateError(gateWith({}), "omo-senpi");
+		expect(error.code).toBe("ULW_LOOP_QUALITY_GATE_INVALID");
+		expect(error.message).toContain("no codeReview lane");
+	});
+
+	it("#given a four-section senpi gate #when validated on the default lazycodex surface #then codeReview is required", () => {
+		const error = qualityGateError(senpiGate());
+		expect(error.code).toBe("ULW_LOOP_QUALITY_GATE_INVALID");
+		expect(error.message).toContain("codeReview");
+	});
+
+	it("#given swapped omo-senpi reviewer roles #when validated on the omo-senpi surface #then section-specific roles are enforced", () => {
+		const swapped = senpiGate({
+			manualQa: { ...BASE_GATE.manualQa, by: "category:deep" },
+			gateReview: { ...BASE_GATE.gateReview, by: "main-session" },
+		});
+
+		const error = qualityGateError(swapped, "omo-senpi");
+
+		expect(error.code).toBe("ULW_LOOP_QUALITY_GATE_INVALID");
+		expect(error.message).toContain("manualQa.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/quality-gate-senpi-surface.test.ts

@@ -0,0 +1,131 @@
+import { readFile } from "node:fs/promises";
+
+import { describe, expect, it } from "vitest";
+
+import { validateQualityGate } from "../src/quality-gate.js";
+import { UlwLoopError } from "../src/types.js";
+
+const COMMON = {
+	manualQa: {
+		status: "passed",
+		evidence: "Ran senpi manual QA with artifact-backed evidence.",
+		surfaceEvidence: [
+			{
+				id: "surface-cli-pass",
+				criterionRef: "C1",
+				surface: "cli",
+				invocation: "omo-agent-toolkit ulw-loop checkpoint --status complete",
+				verdict: "passed",
+				artifactRefs: ["artifact-cli-pass"],
+			},
+		],
+		adversarialCases: [
+			{
+				id: "adv-role",
+				criterionRef: "C2",
+				scenario: "a reviewer role is invalid",
+				expectedBehavior: "the gate rejects the invalid role",
+				verdict: "passed",
+				artifactRefs: ["artifact-cli-pass"],
+			},
+		],
+		artifactRefs: [
+			{
+				id: "artifact-cli-pass",
+				kind: "cli-transcript",
+				description: "CLI transcript for valid checkpoint.",
+				path: "cli-pass.txt",
+			},
+		],
+	},
+	iteration: {
+		fullRerun: true,
+		status: "passed",
+		rerunCommands: ["bunx vitest run"],
+		evidence: "Focused tests passed.",
+	},
+	criteriaCoverage: {
+		totalCriteria: 2,
+		passCount: 2,
+		originalIntent: "User wanted a valid senpi quality gate.",
+		desiredOutcome: "The senpi gate accepts its four required lanes.",
+		userOutcomeReview: "The requested senpi outcome is covered.",
+		adversarialClassesCovered: ["role_mismatch"],
+	},
+} as const;
+
+function senpiGate(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+	return {
+		...COMMON,
+		manualQa: { ...COMMON.manualQa, by: "main-session" },
+		gateReview: {
+			by: "category:deep",
+			recommendation: "APPROVE",
+			reportPath: "gate-review.md",
+			evidence: "Verified the senpi gate.",
+			blockers: [],
+		},
+		...overrides,
+	};
+}
+
+function section(input: Record<string, unknown>, key: string): Record<string, unknown> {
+	const value = input[key];
+	if (typeof value !== "object" || value === null || Array.isArray(value))
+		throw new Error(`missing object section: ${key}`);
+	return value as Record<string, unknown>;
+}
+
+function errorFor(input: unknown): UlwLoopError {
+	try {
+		validateQualityGate(input, { reviewerSurface: "omo-senpi" });
+	} catch (error) {
+		if (error instanceof UlwLoopError) return error;
+		throw error;
+	}
+	throw new Error("Expected quality gate validation to fail");
+}
+
+describe("validateQualityGate omo-senpi surface", () => {
+	it("#given a four-section senpi gate #when validated #then it accepts main-session manual QA and category:deep review", () => {
+		expect(() => validateQualityGate(senpiGate(), { reviewerSurface: "omo-senpi" })).not.toThrow();
+	});
+
+	it("#given a senpi gate with codeReview #when validated #then it rejects the forbidden codeReview lane", () => {
+		const error = errorFor(senpiGate({ codeReview: { by: "anything" } }));
+		expect(error.details?.["field"]).toContain("codeReview");
+		expect(error.message).toContain("omo-senpi gate has no codeReview lane");
+	});
+
+	it.each(["category:deep", "category:unspecified-high", "category:unspecified-low"])(
+		"#given gateReview.by %s #when validated on senpi #then it accepts the category role",
+		(by) => {
+			expect(() =>
+				validateQualityGate(senpiGate({ gateReview: { ...section(senpiGate(), "gateReview"), by } }), {
+					reviewerSurface: "omo-senpi",
+				}),
+			).not.toThrow();
+		},
+	);
+
+	it.each(["omo-senpi-gate-reviewer", "lazycodex-gate-reviewer", "arbitrary"])(
+		"#given gateReview.by %s #when validated on senpi #then it rejects the non-category role",
+		(by) => {
+			const error = errorFor(senpiGate({ gateReview: { ...section(senpiGate(), "gateReview"), by } }));
+			expect(error.message).toContain("gateReview.by");
+		},
+	);
+
+	it.each(["omo-senpi-qa-executor", "lazycodex-qa-executor", "arbitrary"])(
+		"#given manualQa.by %s #when validated on senpi #then it rejects the non-main-session role",
+		(by) => {
+			const error = errorFor(senpiGate({ manualQa: { ...COMMON.manualQa, by } }));
+			expect(error.message).toContain("manualQa.by");
+		},
+	);
+
+	it("#given the existing lazycodex fixture #when validated on the default surface #then it remains valid", async () => {
+		const raw = await readFile(new URL("./fixtures/sample-quality-gate.json", import.meta.url), "utf8");
+		expect(() => validateQualityGate(JSON.parse(raw))).not.toThrow();
+	});
+});

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

@@ -111,7 +111,10 @@ describe("validateQualityGate", () => {
 			"gateReview",
 			"iteration",
 			"manualQa",
+			"surface",
 		]);
+		expect("codeReview" in gate).toBe(true);
+		if (!("codeReview" in gate)) throw new Error("expected lazycodex codeReview section");
 		expect(gate.codeReview.codeQualityStatus).toBe("CLEAR");
 		expect(gate).toMatchObject({
 			criteriaCoverage: { totalCriteria: 9, passCount: 9, userOutcomeReview: expect.stringContaining("user") },
@@ -127,6 +130,8 @@ describe("validateQualityGate", () => {
 		const gate = validateQualityGate(parsed, FS_OPTS);
 
 		// then
+		expect("codeReview" in gate).toBe(true);
+		if (!("codeReview" in gate)) throw new Error("expected lazycodex codeReview section");
 		expect(gate.codeReview.recommendation).toBe("APPROVE");
 		expect(gate.manualQa.artifactRefs).toHaveLength(5);
 	});

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

@@ -1,4 +1,4 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -9,16 +9,27 @@ import { applySpawnGuards } from "../src/spawn-guard.ts";
 
 let workDir: string;
 let originalLimit: string | undefined;
+let originalReviewLimit: string | undefined;
+let originalToolkitSurface: string | undefined;
 
 beforeEach(async () => {
 	workDir = await mkdtemp(join(tmpdir(), "ulw-spawn-guard-"));
 	originalLimit = process.env["OMO_SPAWN_FANOUT_LIMIT"];
+	originalReviewLimit = process.env["OMO_ULW_LOOP_REVIEW_SPAWN_LIMIT"];
+	originalToolkitSurface = process.env["OMO_AGENT_TOOLKIT_SURFACE"];
 	delete process.env["OMO_SPAWN_FANOUT_LIMIT"];
+	delete process.env["OMO_ULW_LOOP_REVIEW_SPAWN_LIMIT"];
+	delete process.env["OMO_AGENT_TOOLKIT_SURFACE"];
 });
 
 afterEach(async () => {
+	delete process.env["OMO_AGENT_TOOLKIT_SURFACE"];
 	if (originalLimit === undefined) delete process.env["OMO_SPAWN_FANOUT_LIMIT"];
 	else process.env["OMO_SPAWN_FANOUT_LIMIT"] = originalLimit;
+	if (originalReviewLimit === undefined) delete process.env["OMO_ULW_LOOP_REVIEW_SPAWN_LIMIT"];
+	else process.env["OMO_ULW_LOOP_REVIEW_SPAWN_LIMIT"] = originalReviewLimit;
+	if (originalToolkitSurface === undefined) delete process.env["OMO_AGENT_TOOLKIT_SURFACE"];
+	else process.env["OMO_AGENT_TOOLKIT_SURFACE"] = originalToolkitSurface;
 	await rm(workDir, { recursive: true, force: true });
 });
 
@@ -132,7 +143,118 @@ describe("applySpawnGuards fan-out cap", () => {
 	});
 });
 
+describe("applySpawnGuards fan-out cap + reviewer quota interaction", () => {
+	it("#given fan-out cap exhausted #when a reviewer spawns #then denies without charging reviewer quota", () => {
+		writeGoals();
+		process.env["OMO_SPAWN_FANOUT_LIMIT"] = "3";
+
+		// exhaust the fan-out cap with non-reviewer spawns
+		expect(applySpawnGuards(payload("spawn_agent", { message: "scan" }))).toBe("");
+		expect(applySpawnGuards(payload("spawn_agent", { message: "scan" }))).toBe("");
+		expect(applySpawnGuards(payload("spawn_agent", { message: "scan" }))).toBe("");
+
+		// reviewer spawn while cap is exhausted — must deny without incrementing reviewer count
+		const reviewSpawn = payload("spawn_agent", {
+			agent_type: "lazycodex-code-reviewer",
+			message: "review the current diff",
+		});
+		const result = applySpawnGuards(reviewSpawn);
+		expect(result).not.toBe("");
+		expect(deny(result).permissionDecisionReason).toContain("4/3");
+
+		// reviewer quota must be untouched — a subsequent spawn after raising the limit must succeed
+		process.env["OMO_SPAWN_FANOUT_LIMIT"] = "10";
+		expect(applySpawnGuards(reviewSpawn)).toBe("");
+		const counters = JSON.parse(readFileSync(join(sessionDir(), "review-spawn-counts.json"), "utf8"));
+		expect(counters["lazycodex-code-reviewer:g1:a1"]).toBe(1);
+	});
+});
+
+describe("applySpawnGuards review repetition cap", () => {
+	it("#given one goal attempt #when the same reviewer spawns four times #then denies until the attempt advances", () => {
+		writeGoals();
+		const reviewSpawn = payload("spawn_agent", {
+			agent_type: "lazycodex-code-reviewer",
+			message: "review the current diff",
+		});
+
+		expect(applySpawnGuards(reviewSpawn)).toBe("");
+		expect(applySpawnGuards(reviewSpawn)).toBe("");
+		expect(applySpawnGuards(reviewSpawn)).toBe("");
+
+		const fourth = applySpawnGuards(reviewSpawn);
+		expect(fourth).not.toBe("");
+		expect(deny(fourth).permissionDecisionReason).toContain("4/3");
+		const counter = JSON.parse(readFileSync(join(sessionDir(), "spawn-count.json"), "utf8"));
+		expect(counter.count).toBe(3);
+
+		const goalsPath = join(sessionDir(), "goals.json");
+		const plan = JSON.parse(readFileSync(goalsPath, "utf8")) as {
+			goals: Array<{ attempt: number }>;
+		};
+		const [goal] = plan.goals;
+		if (goal === undefined) throw new Error("fixture must include a goal");
+		goal.attempt = 2;
+		writeFileSync(goalsPath, JSON.stringify(plan));
+
+		expect(applySpawnGuards(reviewSpawn)).toBe("");
+	});
+
+	it.each(["lazycodex-code-reviewer", "lazycodex-qa-executor"])(
+		"#given a MultiAgentV2 %s message #when it spawns four times #then applies the reviewer cap",
+		(agentType) => {
+			writeGoals();
+			const reviewSpawn = payload("spawn_agent", {
+				message: `Delegate this final-quality lane to ${agentType}`,
+			});
+
+			expect(applySpawnGuards(reviewSpawn)).toBe("");
+			expect(applySpawnGuards(reviewSpawn)).toBe("");
+			expect(applySpawnGuards(reviewSpawn)).toBe("");
+
+			const fourth = deny(applySpawnGuards(reviewSpawn));
+			expect(fourth.permissionDecisionReason).toContain(`${agentType} 4/3`);
+		},
+	);
+
+	it("#given exhausted code reviews and an explicit QA assignment #when a mixed V2 prompt is guarded #then charges the QA role", () => {
+		writeGoals();
+		const codeReview = payload("collaboration.spawn_agent", {
+			message: "Act as lazycodex-code-reviewer; review the current diff",
+		});
+
+		expect(applySpawnGuards(codeReview)).toBe("");
+		expect(applySpawnGuards(codeReview)).toBe("");
+		expect(applySpawnGuards(codeReview)).toBe("");
+
+		const output = applySpawnGuards(
+			payload("collaboration.spawn_agent", {
+				message: "Act as a lazycodex-qa-executor; verify the lazycodex-code-reviewer finding",
+			}),
+		);
+		expect(output).toBe("");
+
+		const counters = JSON.parse(readFileSync(join(sessionDir(), "review-spawn-counts.json"), "utf8"));
+		expect(counters["lazycodex-code-reviewer:g1:a1"]).toBe(3);
+		expect(counters["lazycodex-qa-executor:g1:a1"]).toBe(1);
+	});
+});
+
 describe("applySpawnGuards gate-artifact guard", () => {
+	it("#given a mixed-role V2 gate prompt #when guarded #then prioritizes the gate role and denies on missing artifact without charging quota", () => {
+		writeGoals();
+
+		const output = applySpawnGuards(
+			payload("spawn_agent", {
+				message: "Act as lazycodex-gate-reviewer; audit the lazycodex-code-reviewer report",
+			}),
+		);
+
+		expect(output).not.toBe("");
+		expect(deny(output).permissionDecisionReason).toContain("g1-code-review.md");
+		expect(existsSync(join(sessionDir(), "review-spawn-counts.json"))).toBe(false);
+	});
+
 	it("#given a gate spawn by agent_type without artifacts #when guarded #then denies naming the missing path", () => {
 		writeGoals();
 
@@ -146,6 +268,53 @@ describe("applySpawnGuards gate-artifact guard", () => {
 		expect(parsed.permissionDecisionReason).toContain("g1-code-review.md");
 	});
 
+	it("#given senpi main-session QA is present but code review is absent #when the gate reviewer spawns #then the self-check allows it", () => {
+		process.env["OMO_AGENT_TOOLKIT_SURFACE"] = "omo-senpi";
+		writeGoals();
+		mkdirSync(join(workDir, ".omo", "evidence"), { recursive: true });
+		writeFileSync(join(workDir, ".omo", "evidence", "g1-manual-qa.md"), "matrix\n");
+
+		const output = applySpawnGuards(
+			payload("collaborationspawn_agent", { agent_type: "omo-senpi-gate-reviewer", message: "audit the artifacts" }),
+		);
+
+		expect(output).toBe("");
+	});
+
+	it("#given senpi QA is absent #when the gate reviewer spawns #then the self-check blocks naming manual QA", () => {
+		process.env["OMO_AGENT_TOOLKIT_SURFACE"] = "omo-senpi";
+		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-manual-qa.md");
+	});
+
+	it("#given an omo-senpi gate spawn with a code-review artifact only #when guarded #then blocks the missing manual QA", () => {
+		process.env["OMO_AGENT_TOOLKIT_SURFACE"] = "omo-senpi";
+		writeGoals();
+		mkdirSync(join(workDir, ".omo", "evidence"), { recursive: true });
+		writeFileSync(join(workDir, ".omo", "evidence", "g1-code-review.md"), "report\n");
+
+		const output = applySpawnGuards(
+			payload("collaborationspawn_agent", { agent_type: "omo-senpi-gate-reviewer", message: "audit the artifacts" }),
+		);
+
+		expect(deny(output).permissionDecisionReason).toContain("g1-manual-qa.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();
 
@@ -154,6 +323,49 @@ describe("applySpawnGuards gate-artifact guard", () => {
 		expect(deny(output).permissionDecision).toBe("deny");
 	});
 
+	it("#given the staged Senpi surface #when generic and explicit gate spawns alternate #then they share one cap", () => {
+		writeGoals();
+		process.env["OMO_AGENT_TOOLKIT_SURFACE"] = "omo-senpi";
+		mkdirSync(join(workDir, ".omo", "evidence"), { recursive: true });
+		writeFileSync(join(workDir, ".omo", "evidence", "g1-code-review.md"), "report\n");
+		writeFileSync(join(workDir, ".omo", "evidence", "g1-manual-qa.md"), "matrix\n");
+		const genericGate = payload("spawn_agent", { message: "run the final gate review now" });
+		const explicitGate = payload("spawn_agent", {
+			message: "Act as omo-senpi-gate-reviewer; audit the final evidence",
+		});
+
+		expect(applySpawnGuards(genericGate)).toBe("");
+		expect(applySpawnGuards(explicitGate)).toBe("");
+		expect(applySpawnGuards(genericGate)).toBe("");
+
+		const fourth = deny(applySpawnGuards(explicitGate));
+		expect(fourth.permissionDecisionReason).toContain("omo-senpi-gate-reviewer 4/3");
+		const counters = JSON.parse(readFileSync(join(sessionDir(), "review-spawn-counts.json"), "utf8"));
+		expect(counters["omo-senpi-gate-reviewer:g1:a1"]).toBe(3);
+		expect(counters["lazycodex-gate-reviewer:g1:a1"]).toBeUndefined();
+	});
+
+	it("#given the staged Senpi surface #when LazyCodex and Senpi aliases alternate #then one reviewer lane owns the cap", () => {
+		writeGoals();
+		process.env["OMO_AGENT_TOOLKIT_SURFACE"] = "omo-senpi";
+		const senpiReviewer = payload("spawn_agent", {
+			message: "Act as omo-senpi-code-reviewer; inspect the current diff",
+		});
+		const lazycodexReviewer = payload("spawn_agent", {
+			message: "Act as lazycodex-code-reviewer; inspect the current diff",
+		});
+
+		expect(applySpawnGuards(senpiReviewer)).toBe("");
+		expect(applySpawnGuards(lazycodexReviewer)).toBe("");
+		expect(applySpawnGuards(senpiReviewer)).toBe("");
+
+		const fourth = deny(applySpawnGuards(lazycodexReviewer));
+		expect(fourth.permissionDecisionReason).toContain("omo-senpi-code-reviewer 4/3");
+		const counters = JSON.parse(readFileSync(join(sessionDir(), "review-spawn-counts.json"), "utf8"));
+		expect(counters["omo-senpi-code-reviewer:g1:a1"]).toBe(3);
+		expect(counters["lazycodex-code-reviewer:g1:a1"]).toBeUndefined();
+	});
+
 	it("#given v1 artifacts on disk #when the gate spawns #then allows", () => {
 		writeGoals();
 		mkdirSync(join(workDir, ".omo", "evidence"), { recursive: true });
@@ -226,3 +438,108 @@ describe("applySpawnGuards gate-artifact guard", () => {
 		expect(output).toBe("");
 	});
 });
+
+describe("applySpawnGuards V1 agent_type non-reviewer early-exit", () => {
+	it("#given a V1 spawn with a non-reviewer agent_type #when guarded #then allows without charging any quota", () => {
+		writeGoals();
+		const explorerSpawn = payload("spawn_agent", {
+			agent_type: "explorer",
+			message: "scan the codebase for lazycodex-code-reviewer patterns",
+		});
+
+		const result = applySpawnGuards(explorerSpawn);
+
+		expect(result).toBe("");
+		expect(existsSync(join(sessionDir(), "review-spawn-counts.json"))).toBe(false);
+	});
+
+	it("#given a V1 spawn with a non-reviewer agent_type mentioning a gate role #when guarded #then does not charge gate quota", () => {
+		writeGoals();
+		const explorerSpawn = payload("spawn_agent", {
+			agent_type: "deep",
+			message: "final gate review — summarize findings",
+		});
+
+		const result = applySpawnGuards(explorerSpawn);
+
+		expect(result).toBe("");
+		expect(existsSync(join(sessionDir(), "review-spawn-counts.json"))).toBe(false);
+	});
+});
+
+describe("applySpawnGuards V2 explicit non-reviewer act-as guard", () => {
+	it("#given an explicit 'act as explorer' assignment mentioning a reviewer #when guarded #then allows without charging reviewer quota", () => {
+		writeGoals();
+		const explorerSpawn = payload("spawn_agent", {
+			message: "Act as explorer; scan for lazycodex-code-reviewer usage patterns",
+		});
+
+		const result = applySpawnGuards(explorerSpawn);
+
+		expect(result).toBe("");
+		expect(existsSync(join(sessionDir(), "review-spawn-counts.json"))).toBe(false);
+	});
+
+	it("#given an explicit 'act as a deep' assignment with gate keyword #when guarded #then allows without charging gate quota", () => {
+		writeGoals();
+		const deepSpawn = payload("spawn_agent", {
+			message: "Act as a deep agent; run the final gate review summary",
+		});
+
+		const result = applySpawnGuards(deepSpawn);
+
+		expect(result).toBe("");
+		expect(existsSync(join(sessionDir(), "review-spawn-counts.json"))).toBe(false);
+	});
+
+	it("#given an explicit reviewer act-as assignment #when guarded #then still charges reviewer quota", () => {
+		writeGoals();
+		const reviewerSpawn = payload("spawn_agent", {
+			message: "Act as lazycodex-code-reviewer; inspect the diff",
+		});
+
+		const result = applySpawnGuards(reviewerSpawn);
+
+		expect(result).toBe("");
+		const counters = JSON.parse(readFileSync(join(sessionDir(), "review-spawn-counts.json"), "utf8"));
+		expect(counters["lazycodex-code-reviewer:g1:a1"]).toBe(1);
+	});
+});
+
+describe("applySpawnGuards gate-artifact check before reviewer quota", () => {
+	it("#given a gate spawn without artifacts #when the fan-out budget is available #then denies on artifact rule without charging reviewer quota", () => {
+		writeGoals();
+
+		const gateSpawn = payload("spawn_agent", {
+			agent_type: "lazycodex-gate-reviewer",
+			message: "final gate review",
+		});
+
+		const result = applySpawnGuards(gateSpawn);
+
+		expect(result).not.toBe("");
+		expect(deny(result).permissionDecisionReason).toContain("missing");
+		expect(existsSync(join(sessionDir(), "review-spawn-counts.json"))).toBe(false);
+	});
+
+	it("#given a gate spawn denied for missing artifacts #when retried after artifacts land #then charges quota only on the allowed spawn", () => {
+		writeGoals();
+		const gateSpawn = payload("spawn_agent", {
+			agent_type: "lazycodex-gate-reviewer",
+			message: "final gate review",
+		});
+
+		const firstResult = applySpawnGuards(gateSpawn);
+		expect(firstResult).not.toBe("");
+		expect(existsSync(join(sessionDir(), "review-spawn-counts.json"))).toBe(false);
+
+		mkdirSync(join(workDir, ".omo", "evidence"), { recursive: true });
+		writeFileSync(join(workDir, ".omo", "evidence", "g1-code-review.md"), "report\n");
+		writeFileSync(join(workDir, ".omo", "evidence", "g1-manual-qa.md"), "matrix\n");
+
+		const secondResult = applySpawnGuards(gateSpawn);
+		expect(secondResult).toBe("");
+		const counters = JSON.parse(readFileSync(join(sessionDir(), "review-spawn-counts.json"), "utf8"));
+		expect(counters["lazycodex-gate-reviewer:g1:a1"]).toBe(1);
+	});
+});