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

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

@@ -1,27 +1,32 @@
-import { resolve } from "node:path";
-import { isWithinAttemptDir } from "./paths.js";
+import {
+	artifactCompatible,
+	artifactMap,
+	checkFile,
+	compatibleKindsFor,
+	parseArtifactRefs,
+	referencedArtifacts,
+	surfaceField,
+} from "./quality-gate-artifacts.js";
 import {
 	emptyBlockers,
 	invalid,
+	isPoisoned,
+	isPoisonedArtifactKind,
 	literal,
 	numberField,
 	section,
 	stringArray,
 	textField,
+	withQualityGateCollector,
 } from "./quality-gate-fields.js";
 import { adversarialVerdict, codeQualityStatusField, passedVerdict } from "./quality-gate-verdicts.js";
-import type {
-	UlwLoopManualQaArtifactKind,
-	UlwLoopManualQaArtifactRef,
-	UlwLoopManualQaSurface,
-	UlwLoopQualityGate,
-} from "./types.js";
-
-const REVIEWER_ROLES = {
-	codeReview: "lazycodex-code-reviewer",
-	manualQa: "lazycodex-qa-executor",
-	gateReview: "lazycodex-gate-reviewer",
-} as const;
+import {
+	GATE_SECTION_BY_ACCEPTOR,
+	OPTIONAL_GATE_SECTIONS_BY_SURFACE,
+	REQUIRED_GATE_SECTIONS_BY_SURFACE,
+	type UlwLoopToolkitSurface,
+} from "./surface.js";
+import type { UlwLoopManualQaArtifactRef, UlwLoopQualityGate } from "./types.js";
 
 export {
 	classifyExternalAuthorizationBlocker,
@@ -36,153 +41,81 @@ 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 {
-	const actual = textField(value, field);
-	if (actual !== expected) invalid(`${field} must be ${expected}.`, field);
-	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 reviewerAcceptorField(
+	value: unknown,
+	surface: UlwLoopToolkitSurface,
+	sectionName: "codeReview" | "manualQa" | "gateReview",
+): string {
+	const field = `${sectionName}.by`;
+	const accepted = GATE_SECTION_BY_ACCEPTOR[surface][sectionName];
+	if (typeof value !== "string" || value.trim() === "") {
+		textField(value, field);
+		return accepted?.[0] ?? "";
 	}
+	const actual = textField(value, field);
+	if (accepted === undefined || !accepted.includes(actual))
+		invalid(`${field} must be one of ${accepted?.join(", ") ?? "the configured reviewers"}.`, field);
+	return actual;
 }
 
-function checkFile(path: string, field: string, opts?: ValidateQualityGateOptions): void {
-	if (opts === 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) {
-		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 validateQualityGate(input: unknown, opts?: ValidateQualityGateOptions): UlwLoopQualityGate {
+	return withQualityGateCollector(() => validateQualityGateUncollected(input, opts));
 }
 
-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);
+function validateQualityGateUncollected(input: unknown, opts?: ValidateQualityGateOptions): UlwLoopQualityGate {
+	const surface = opts?.reviewerSurface ?? "lazycodex";
+	const raw = input as Record<string, unknown>;
+	const gate = section(
+		raw && typeof raw === "object" && "qualityGate" in raw ? raw["qualityGate"] : input,
+		"qualityGate",
+	);
+	for (const name of REQUIRED_GATE_SECTIONS_BY_SURFACE[surface]) section(gate[name], name);
+	for (const name of Object.keys(gate)) {
+		if (name === "codeReview" && !OPTIONAL_GATE_SECTIONS_BY_SURFACE[surface].includes(name as never))
+			invalid("omo-senpi gate has no codeReview lane.", name);
 	}
-	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(
-	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;
-	});
-}
-
-export function validateQualityGate(input: unknown, opts?: ValidateQualityGateOptions): UlwLoopQualityGate {
-	const gate = section(input, "qualityGate");
-	const codeReview = section(gate["codeReview"], "codeReview");
+	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 codeReview = gate["codeReview"] !== undefined ? section(gate["codeReview"], "codeReview") : undefined;
+	const manualQaBy = reviewerAcceptorField(manualQa["by"], surface, "manualQa");
+	const gateReviewBy = reviewerAcceptorField(gateReview["by"], surface, "gateReview");
+	const manualQaEvidence = textField(manualQa["evidence"], "manualQa.evidence");
+	const gateReviewEvidence = textField(gateReview["evidence"], "gateReview.evidence");
+
 	const totalCriteria = numberField(coverage["totalCriteria"], "criteriaCoverage.totalCriteria");
 	const passCount = numberField(coverage["passCount"], "criteriaCoverage.passCount");
-	if (passCount < totalCriteria)
+	if (!isPoisoned("criteriaCoverage.passCount") && passCount < totalCriteria)
 		invalid("criteriaCoverage.passCount must cover totalCriteria.", "criteriaCoverage.passCount");
 	const artifactRefs = parseArtifactRefs(manualQa["artifactRefs"], opts);
 	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"], REVIEWER_ROLES.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"),
-		},
+	if (!isPoisoned("gateReview.reportPath")) checkFile(gateReportPath, "gateReview.reportPath", opts);
+	const common = {
 		manualQa: {
-			by: reviewerRoleField(manualQa["by"], REVIEWER_ROLES.manualQa, "manualQa.by"),
+			by: manualQaBy,
 			status: literal(manualQa["status"], "passed", "manualQa.status"),
-			evidence: textField(manualQa["evidence"], "manualQa.evidence"),
+			evidence: manualQaEvidence,
 			surfaceEvidence,
 			adversarialCases,
 			artifactRefs,
 		},
 		gateReview: {
-			by: reviewerRoleField(gateReview["by"], REVIEWER_ROLES.gateReview, "gateReview.by"),
+			by: gateReviewBy,
 			recommendation: literal(gateReview["recommendation"], "APPROVE", "gateReview.recommendation"),
 			reportPath: gateReportPath,
-			evidence: textField(gateReview["evidence"], "gateReview.evidence"),
+			evidence: gateReviewEvidence,
 			blockers: emptyBlockers(gateReview["blockers"], "gateReview.blockers"),
 		},
 		iteration: {
@@ -203,16 +136,35 @@ export function validateQualityGate(input: unknown, opts?: ValidateQualityGateOp
 			),
 		},
 	};
+	if (surface === "omo-senpi") return { surface, ...common };
+	if (codeReview === undefined) return { surface, ...common };
+	const codeReportPath = textField(codeReview["reportPath"], "codeReview.reportPath");
+	checkFile(codeReportPath, "codeReview.reportPath", opts);
+	return {
+		surface,
+		...common,
+		codeReview: {
+			by: reviewerAcceptorField(codeReview["by"], surface, "codeReview"),
+			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(
 	value: unknown,
 	byId: ReadonlyMap<string, UlwLoopManualQaArtifactRef>,
 ): UlwLoopQualityGate["manualQa"]["surfaceEvidence"] {
-	if (!Array.isArray(value) || value.length === 0)
+	if (!Array.isArray(value) || value.length === 0) {
 		invalid("manualQa.surfaceEvidence must not be empty.", "manualQa.surfaceEvidence");
-	return value.map((item, index) => {
+		return [];
+	}
+	return value.flatMap((item, index) => {
 		const row = section(item, `manualQa.surfaceEvidence[${index}]`);
+		if (isPoisoned(`manualQa.surfaceEvidence[${index}]`)) return [];
 		const surface = surfaceField(row["surface"], `manualQa.surfaceEvidence[${index}].surface`);
 		const artifacts = referencedArtifacts(
 			row["artifactRefs"],
@@ -220,9 +172,10 @@ function parseSurfaceEvidence(
 			byId,
 		);
 		for (const artifact of artifacts) {
+			if (isPoisoned(`manualQa.surfaceEvidence[${index}].surface`) || isPoisonedArtifactKind(artifact.id)) continue;
 			if (!artifactCompatible(surface, artifact.kind)) {
 				invalid(
-					`manualQa.surfaceEvidence ${surface} artifact ${artifact.kind} is incompatible.`,
+					`manualQa.surfaceEvidence ${surface} artifact ${artifact.kind} is incompatible; surface "${surface}" accepts artifact kinds: ${compatibleKindsFor(surface).join(", ")}.`,
 					"manualQa.surfaceEvidence",
 				);
 			}
@@ -242,10 +195,13 @@ function parseAdversarialCases(
 	value: unknown,
 	byId: ReadonlyMap<string, UlwLoopManualQaArtifactRef>,
 ): UlwLoopQualityGate["manualQa"]["adversarialCases"] {
-	if (!Array.isArray(value) || value.length === 0)
+	if (!Array.isArray(value) || value.length === 0) {
 		invalid("manualQa.adversarialCases must not be empty.", "manualQa.adversarialCases");
-	return value.map((item, index) => {
+		return [];
+	}
+	return value.flatMap((item, index) => {
 		const row = section(item, `manualQa.adversarialCases[${index}]`);
+		if (isPoisoned(`manualQa.adversarialCases[${index}]`)) return [];
 		const artifacts = referencedArtifacts(
 			row["artifactRefs"],
 			`manualQa.adversarialCases[${index}].artifactRefs`,

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);

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

@@ -1,32 +1,110 @@
-import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, 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 { ulwLoopAttemptEvidenceDir, ulwLoopDir, ulwLoopStateLockPath } from "./paths.js";
+import { isStateLockTimeout, type StateLockOptions, withStateLockSync } from "./state-lock.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
 // hook token from codex-rs hook_names.rs; collaboration.spawn_agent = the
 // 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;
+export const DEFAULT_FANOUT_LIMIT = 24;
+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 {
+export interface SpawnGuardOptions {
+	readonly lockTimeoutMs?: number;
+}
+
+export function applySpawnGuards(payload: PreToolUsePayload, options: SpawnGuardOptions = {}): 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 breaker = readAdmissionBreaker(payload.session_id);
+	if (breaker !== null)
+		return deny(
+			`Subagent admission failed earlier in this session (${breaker}). Do not spawn more workers or reviewers; report the capacity block and wait for the user.`,
+		);
+	const scope = { sessionId: payload.session_id } as const;
+	const stateDir = ulwLoopDir(payload.cwd, scope);
 	const plan = readPlan(join(stateDir, "goals.json"));
 	if (plan === null) return "";
-	const fanOutDenial = consumeFanOutBudget(stateDir);
-	if (fanOutDenial !== null) return deny(fanOutDenial);
+	const lockOptions: StateLockOptions =
+		options.lockTimeoutMs === undefined ? {} : { timeoutMs: options.lockTimeoutMs };
+	try {
+		return withStateLockSync(
+			ulwLoopStateLockPath(payload.cwd, scope),
+			() => evaluateGuards(payload, plan, stateDir),
+			lockOptions,
+		);
+	} catch (error) {
+		if (isStateLockTimeout(error))
+			return deny(`ulw-loop spawn guard could not take the session state lock: ${error.message}`);
+		throw error;
+	}
+}
+
+function evaluateGuards(payload: PreToolUsePayload, plan: UlwLoopPlan, stateDir: string): string {
+	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}`);
+		return deny(`record manual QA first; gate audits its 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 "";
 }
 
+export async function runSpawnAdmissionRecorderCli(
+	stdin: NodeJS.ReadableStream,
+	stdout: NodeJS.WritableStream,
+): Promise<void> {
+	const chunks: Buffer[] = [];
+	for await (const chunk of stdin) chunks.push(Buffer.from(chunk));
+	try {
+		const payload = JSON.parse(Buffer.concat(chunks).toString("utf8")) as Record<string, unknown>;
+		const response =
+			typeof payload["tool_response"] === "string"
+				? payload["tool_response"]
+				: JSON.stringify(payload["tool_response"] ?? "");
+		if (!/too many active cells|AgentLimitReached|max_threads|max_concurrent_threads_per_session/i.test(response))
+			return;
+		const dataDir = process.env["PLUGIN_DATA"];
+		if (typeof dataDir !== "string" || typeof payload["session_id"] !== "string") return;
+		const markerDir = join(dataDir, "spawn-breaker");
+		try {
+			mkdirSync(markerDir, { recursive: true });
+			atomicWriteJson(join(markerDir, `${payload["session_id"]}.json`), {
+				reason: response,
+				at: new Date().toISOString(),
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			process.stderr.write(`[ulw-loop] spawn-guard: could not persist admission failure: ${message}\n`);
+		}
+	} catch {
+		/* malformed hook input is ignored */
+	}
+	void stdout;
+}
+
 export async function runSpawnGuardCli(stdin: NodeJS.ReadableStream, stdout: NodeJS.WritableStream): Promise<void> {
 	try {
 		const chunks: Buffer[] = [];
@@ -40,46 +118,119 @@ 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 limit = reviewSpawnLimit();
+	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 requiredArtifacts = [`${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;
-	// 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 null;
+	const manualQa = `.omo/evidence/${goal.id}-manual-qa.md`;
+	return isNonEmptyFile(join(payload.cwd, manualQa)) ? null : manualQa;
 }
 
 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 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 {
@@ -93,6 +244,19 @@ function deny(reason: string): string {
 	})}\n`;
 }
 
+function readAdmissionBreaker(sessionId: string): string | null {
+	const dataDir = process.env["PLUGIN_DATA"];
+	if (typeof dataDir !== "string") return null;
+	try {
+		const value = JSON.parse(readFileSync(join(dataDir, "spawn-breaker", `${sessionId}.json`), "utf8")) as {
+			reason?: unknown;
+		};
+		return typeof value.reason === "string" ? value.reason : "capacity limit";
+	} catch {
+		return null;
+	}
+}
+
 function fanOutLimit(): number {
 	const raw = process.env["OMO_SPAWN_FANOUT_LIMIT"];
 	if (raw === undefined) return DEFAULT_FANOUT_LIMIT;
@@ -100,6 +264,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;
@@ -109,21 +280,27 @@ function isNonEmptyFile(path: string): boolean {
 	}
 }
 
-function hasOtherEvidenceFile(evidenceDir: string, excludedName: string): boolean {
+function readCount(counterPath: string): number {
 	try {
-		return readdirSync(evidenceDir).some((name) => name !== excludedName && isNonEmptyFile(join(evidenceDir, name)));
+		const parsed = JSON.parse(readFileSync(counterPath, "utf8")) as Record<string, unknown>;
+		return typeof parsed["count"] === "number" && parsed["count"] >= 0 ? parsed["count"] : 0;
 	} catch (error) {
-		if (error instanceof Error) return false;
+		if (error instanceof Error) return 0;
 		throw error;
 	}
 }
 
-function readCount(counterPath: string): number {
+function readCounts(counterPath: string): Record<string, number> {
 	try {
-		const parsed = JSON.parse(readFileSync(counterPath, "utf8")) as Record<string, unknown>;
-		return typeof parsed["count"] === "number" && parsed["count"] >= 0 ? parsed["count"] : 0;
+		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 0;
+		if (error instanceof Error) return {};
 		throw error;
 	}
 }