oh-my-opencode 5.0.0-beta.6 → 5.0.0-beta.60

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

@@ -0,0 +1,159 @@
+import { checkpointUlwLoop } from "../checkpoint.js";
+import { checkpointTemplate } from "../checkpoint-template.js";
+import { recordEvidence } from "../evidence.js";
+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 { UlwLoopError } from "../runtime.js";
+import { statusNextActions } from "../status-next-actions.js";
+import { steerUlwLoop } from "../steering.js";
+import type { UlwLoopOperation } from "./manifest.js";
+import { ULW_LOOP_MANIFEST } from "./manifest.js";
+import type {
+	AgentToolkit,
+	AgentToolkitDependencies,
+	CheckpointArgs,
+	ToolkitContext,
+	ToolkitDispatchRequest,
+	ToolkitDispatchResponse,
+	ToolkitError,
+	ToolkitFailure,
+	ToolkitResponseFor,
+	ToolkitResultFor,
+	ToolkitUnknownRequest,
+} from "./types.js";
+
+function validateContext(context: ToolkitContext): void {
+	if (!context.cwd.trim()) throw new UlwLoopError("cwd is required.", "ULW_LOOP_CWD_REQUIRED");
+	if (!context.sessionId.trim())
+		throw new UlwLoopError("ULW_LOOP_SESSION_ID_REQUIRED: sessionId is required.", "ULW_LOOP_SESSION_ID_REQUIRED");
+	if (context.surface !== "omo-senpi" && context.surface !== "lazycodex")
+		throw new UlwLoopError("surface must be omo-senpi or lazycodex.", "ULW_LOOP_SURFACE_INVALID");
+}
+
+function errorDetails(error: UlwLoopError): ToolkitError {
+	const details =
+		error.details === undefined
+			? undefined
+			: Object.fromEntries(Object.entries(error.details).map(([key, value]) => [key, String(value)]));
+	return details === undefined
+		? { code: error.code, message: error.message }
+		: { code: error.code, message: error.message, details };
+}
+
+function failure<Operation extends string>(operation: Operation, error: UlwLoopError): ToolkitFailure<Operation> {
+	return { ok: false, operation, error: errorDetails(error) };
+}
+
+function caught<Operation extends string>(operation: Operation, error: Error): ToolkitFailure<Operation> {
+	return failure(operation, error instanceof UlwLoopError ? error : new UlwLoopError(error.message, "ULW_LOOP_ERROR"));
+}
+
+function isKnownRequest(request: ToolkitDispatchRequest | ToolkitUnknownRequest): request is ToolkitDispatchRequest {
+	return ULW_LOOP_MANIFEST.operations.some((operation) => operation.name === request.operation);
+}
+
+function unreachable(value: never): never {
+	throw new UlwLoopError(`Unhandled operation: ${String(value)}`, "ULW_LOOP_OPERATION_UNHANDLED");
+}
+
+function nextActionsFrom(result: object): readonly string[] {
+	if (!("nextActions" in result) || !Array.isArray(result.nextActions)) return [];
+	return result.nextActions.filter((action): action is string => typeof action === "string").slice(0, 8);
+}
+
+export function createAgentToolkit(context: ToolkitContext, deps: AgentToolkitDependencies = {}): AgentToolkit {
+	validateContext(context);
+	const scope: UlwLoopScope = { sessionId: context.sessionId };
+	const notify = async <Operation extends UlwLoopOperation>(
+		operation: Operation,
+		response: ToolkitResponseFor<Operation>,
+	): Promise<ToolkitResponseFor<Operation>> => {
+		if (deps.hooks?.onOperation !== undefined) await deps.hooks.onOperation({ operation, context, response });
+		return response;
+	};
+	const invoke = async <Operation extends UlwLoopOperation>(
+		operation: Operation,
+		fn: () => Promise<ToolkitResultFor<Operation>>,
+	): Promise<ToolkitResponseFor<Operation>> => {
+		try {
+			const result = await fn();
+			const nextActions = typeof result === "object" && result !== null ? nextActionsFrom(result) : [];
+			return await notify(operation, { ok: true, operation, result, nextActions });
+		} catch (error) {
+			const response = caught(operation, error instanceof Error ? error : new Error("ULW_LOOP_ERROR"));
+			return notify(operation, response);
+		}
+	};
+	const toolkit: AgentToolkit = {
+		dispatch: async (request): Promise<ToolkitDispatchResponse> => {
+			if (!isKnownRequest(request))
+				return failure(
+					request.operation,
+					new UlwLoopError(`Unknown operation: ${request.operation}`, "ULW_LOOP_OPERATION_UNKNOWN"),
+				);
+			switch (request.operation) {
+				case "help":
+					return toolkit.help();
+				case "create-goals":
+					return toolkit.createGoals(request.args);
+				case "status":
+					return toolkit.status();
+				case "complete-goals":
+					return toolkit.completeGoals(request.args);
+				case "checkpoint":
+					return toolkit.checkpoint(request.args);
+				case "steer":
+					return toolkit.steer(request.args);
+				case "add-goal":
+					return toolkit.addGoal(request.args);
+				case "criteria":
+					return toolkit.criteria(request.args);
+				case "record-evidence":
+					return toolkit.recordEvidence(request.args);
+				case "record-review-blockers":
+					return toolkit.recordReviewBlockers(request.args);
+				default:
+					return unreachable(request);
+			}
+		},
+		help: () => invoke("help", async () => ULW_LOOP_MANIFEST),
+		createGoals: (args) => invoke("create-goals", () => createUlwLoopPlan(context.cwd, args, scope)),
+		status: () =>
+			invoke("status", async () => {
+				const plan = await readUlwLoopPlan(context.cwd, scope);
+				const active = plan.goals.find((goal) => goal.id === plan.activeGoalId);
+				return {
+					plan,
+					summary: summarizeUlwLoopPlan(plan),
+					nextActions: statusNextActions(plan),
+					// Attempt directories are an evidence-layout v2 concept; a v1 plan must not advertise one.
+					...(active === undefined || plan.evidenceLayoutVersion !== 2
+						? {}
+						: { currentAttemptDir: ulwLoopAttemptEvidenceDir(active.id, active.attempt, scope) }),
+				};
+			}),
+		completeGoals: (args = {}) => invoke("complete-goals", () => startNextUlwLoop(context.cwd, args, scope)),
+		checkpoint: (args: CheckpointArgs) =>
+			invoke("checkpoint", () =>
+				args.printTemplate === true
+					? checkpointTemplate(context.cwd, scope, args.goalId, { surface: context.surface })
+					: checkpointUlwLoop(context.cwd, args, scope, { surface: context.surface }),
+			),
+		steer: (args) => invoke("steer", () => steerUlwLoop(context.cwd, args, scope)),
+		addGoal: (args) => invoke("add-goal", () => addUlwLoopGoal(context.cwd, args, scope)),
+		criteria: (args) =>
+			invoke("criteria", async () => {
+				const plan = await readUlwLoopPlan(context.cwd, scope);
+				const goal = plan.goals.find((candidate) => candidate.id === args.goalId);
+				if (goal === undefined)
+					throw new UlwLoopError(`Unknown ulw-loop id: ${args.goalId}.`, "ULW_LOOP_GOAL_NOT_FOUND");
+				return { goalId: goal.id, criteria: goal.successCriteria };
+			}),
+		recordEvidence: (args) => invoke("record-evidence", () => recordEvidence(context.cwd, args, scope)),
+		recordReviewBlockers: (args) =>
+			invoke("record-review-blockers", () => recordFinalReviewBlockers(context.cwd, args, scope)),
+	};
+	return toolkit;
+}

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

@@ -0,0 +1,42 @@
+export const ULW_LOOP_OPERATIONS = [
+	"help",
+	"create-goals",
+	"status",
+	"complete-goals",
+	"checkpoint",
+	"steer",
+	"add-goal",
+	"criteria",
+	"record-evidence",
+	"record-review-blockers",
+] as const;
+
+export type UlwLoopOperation = (typeof ULW_LOOP_OPERATIONS)[number];
+
+export interface ToolkitOperationManifest {
+	readonly name: UlwLoopOperation;
+	readonly mutating: boolean;
+}
+
+export interface ToolkitManifest {
+	readonly version: 1;
+	readonly name: "ulw-loop";
+	readonly operations: readonly ToolkitOperationManifest[];
+}
+
+export const ULW_LOOP_MANIFEST = {
+	version: 1,
+	name: "ulw-loop",
+	operations: [
+		{ name: "help", mutating: false },
+		{ name: "create-goals", mutating: true },
+		{ name: "status", mutating: false },
+		{ name: "complete-goals", mutating: true },
+		{ name: "checkpoint", mutating: true },
+		{ name: "steer", mutating: true },
+		{ name: "add-goal", mutating: true },
+		{ name: "criteria", mutating: false },
+		{ name: "record-evidence", mutating: true },
+		{ name: "record-review-blockers", mutating: true },
+	] satisfies readonly ToolkitOperationManifest[],
+} satisfies ToolkitManifest;

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

@@ -0,0 +1,140 @@
+import type { CheckpointUlwLoopArgs, CheckpointUlwLoopResult } from "../checkpoint.js";
+import type { CheckpointTemplate } from "../checkpoint-template.js";
+import type { recordEvidence } from "../evidence.js";
+import type { addUlwLoopGoal, createUlwLoopPlan, startNextUlwLoop, summarizeUlwLoopPlan } from "../plan-crud.js";
+import type { recordFinalReviewBlockers } from "../review-blockers.js";
+import type { steerUlwLoop } from "../steering.js";
+import type { UlwLoopSteeringProposal } from "../steering-types.js";
+import type { UlwLoopToolkitSurface } from "../surface.js";
+import type { UlwLoopPlan } from "../types.js";
+import type { ULW_LOOP_MANIFEST, UlwLoopOperation } from "./manifest.js";
+
+export type ToolkitSurface = UlwLoopToolkitSurface;
+
+export interface ToolkitContext {
+	readonly cwd: string;
+	readonly sessionId: string;
+	readonly surface: ToolkitSurface;
+}
+
+export type CreateGoalsArgs = Parameters<typeof createUlwLoopPlan>[1];
+export type CompleteGoalsArgs = NonNullable<Parameters<typeof startNextUlwLoop>[1]>;
+export type SteerArgs = UlwLoopSteeringProposal;
+export type AddGoalArgs = Parameters<typeof addUlwLoopGoal>[1];
+export type RecordEvidenceArgs = Parameters<typeof recordEvidence>[1];
+export type CriteriaArgs = { readonly goalId: string };
+export type CheckpointMutationArgs = CheckpointUlwLoopArgs & { readonly printTemplate?: false };
+export type CheckpointTemplateArgs = { readonly printTemplate: true; readonly goalId?: string };
+export type CheckpointArgs = CheckpointMutationArgs | CheckpointTemplateArgs;
+export type RecordReviewBlockersArgs = Parameters<typeof recordFinalReviewBlockers>[1];
+
+export type ToolkitDispatchRequest =
+	| { readonly operation: "help"; readonly args?: Record<never, never> }
+	| { readonly operation: "create-goals"; readonly args: CreateGoalsArgs }
+	| { readonly operation: "status"; readonly args?: Record<never, never> }
+	| { readonly operation: "complete-goals"; readonly args?: CompleteGoalsArgs }
+	| { readonly operation: "checkpoint"; readonly args: CheckpointArgs }
+	| { readonly operation: "steer"; readonly args: SteerArgs }
+	| { readonly operation: "add-goal"; readonly args: AddGoalArgs }
+	| { readonly operation: "criteria"; readonly args: CriteriaArgs }
+	| { readonly operation: "record-evidence"; readonly args: RecordEvidenceArgs }
+	| { readonly operation: "record-review-blockers"; readonly args: RecordReviewBlockersArgs };
+
+export interface ToolkitUnknownRequest {
+	readonly operation: string;
+	readonly args?: Record<never, never>;
+}
+
+export interface ToolkitError {
+	readonly code: string;
+	readonly message: string;
+	readonly details?: Readonly<Record<string, string>>;
+}
+
+export interface ToolkitSuccess<Operation extends UlwLoopOperation, Result> {
+	readonly ok: true;
+	readonly operation: Operation;
+	readonly result: Result;
+	readonly nextActions: readonly string[];
+	readonly warnings?: readonly string[];
+}
+
+export interface ToolkitFailure<Operation extends string = string> {
+	readonly ok: false;
+	readonly operation: Operation;
+	readonly error: ToolkitError;
+}
+
+type StatusResult = {
+	readonly plan: UlwLoopPlan;
+	readonly summary: ReturnType<typeof summarizeUlwLoopPlan>;
+	readonly nextActions: readonly string[];
+	readonly currentAttemptDir?: string;
+};
+
+type ResultFor<Operation extends UlwLoopOperation> = Operation extends "help"
+	? typeof ULW_LOOP_MANIFEST
+	: Operation extends "create-goals"
+		? Awaited<ReturnType<typeof createUlwLoopPlan>>
+		: Operation extends "status"
+			? StatusResult
+			: Operation extends "complete-goals"
+				? Awaited<ReturnType<typeof startNextUlwLoop>>
+				: Operation extends "checkpoint"
+					? CheckpointUlwLoopResult | CheckpointTemplate
+					: Operation extends "steer"
+						? Awaited<ReturnType<typeof steerUlwLoop>>
+						: Operation extends "add-goal"
+							? Awaited<ReturnType<typeof addUlwLoopGoal>>
+							: Operation extends "criteria"
+								? {
+										readonly goalId: string;
+										readonly criteria: UlwLoopPlan["goals"][number]["successCriteria"];
+									}
+								: Operation extends "record-evidence"
+									? Awaited<ReturnType<typeof recordEvidence>>
+									: Operation extends "record-review-blockers"
+										? Awaited<ReturnType<typeof recordFinalReviewBlockers>>
+										: never;
+
+export type ToolkitResultFor<Operation extends UlwLoopOperation> = ResultFor<Operation>;
+export type ToolkitResponseFor<Operation extends UlwLoopOperation> =
+	| ToolkitSuccess<Operation, ResultFor<Operation>>
+	| ToolkitFailure<Operation>;
+export type ToolkitOperationResponse = {
+	[Operation in UlwLoopOperation]: ToolkitResponseFor<Operation>;
+}[UlwLoopOperation];
+export type ToolkitDispatchResponse = ToolkitOperationResponse | ToolkitFailure<string>;
+export type ToolkitResponse<Result> = ToolkitSuccess<UlwLoopOperation, Result> | ToolkitFailure<string>;
+
+export interface ToolkitOperationHookEvent<Operation extends UlwLoopOperation = UlwLoopOperation> {
+	readonly operation: Operation;
+	readonly context: ToolkitContext;
+	readonly response: ToolkitResponseFor<Operation>;
+}
+
+export interface ToolkitHostHooks {
+	readonly onOperation?: <Operation extends UlwLoopOperation>(
+		event: ToolkitOperationHookEvent<Operation>,
+	) => void | Promise<void>;
+}
+
+export interface AgentToolkitDependencies {
+	readonly hooks?: ToolkitHostHooks;
+}
+
+export interface AgentToolkit {
+	readonly dispatch: (request: ToolkitDispatchRequest | ToolkitUnknownRequest) => Promise<ToolkitDispatchResponse>;
+	readonly help: () => Promise<ToolkitResponseFor<"help">>;
+	readonly createGoals: (args: CreateGoalsArgs) => Promise<ToolkitResponseFor<"create-goals">>;
+	readonly status: () => Promise<ToolkitResponseFor<"status">>;
+	readonly completeGoals: (args?: CompleteGoalsArgs) => Promise<ToolkitResponseFor<"complete-goals">>;
+	readonly checkpoint: (args: CheckpointArgs) => Promise<ToolkitResponseFor<"checkpoint">>;
+	readonly steer: (args: SteerArgs) => Promise<ToolkitResponseFor<"steer">>;
+	readonly addGoal: (args: AddGoalArgs) => Promise<ToolkitResponseFor<"add-goal">>;
+	readonly criteria: (args: CriteriaArgs) => Promise<ToolkitResponseFor<"criteria">>;
+	readonly recordEvidence: (args: RecordEvidenceArgs) => Promise<ToolkitResponseFor<"record-evidence">>;
+	readonly recordReviewBlockers: (
+		args: RecordReviewBlockersArgs,
+	) => Promise<ToolkitResponseFor<"record-review-blockers">>;
+}

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

@@ -0,0 +1,3 @@
+export { createAgentToolkit } from "./sdk/factory.js";
+export * from "./sdk/manifest.js";
+export * from "./sdk/types.js";

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