lazycodex-ai 5.0.0-beta.48 → 5.0.0-beta.49

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

@@ -1,5 +1,5 @@
 import { randomBytes } from "node:crypto";
-import { existsSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { parsePreToolUsePayload } from "./codex-hook.js";
 import { isFinalRunCompletionCandidate } from "./goal-status.js";
@@ -10,7 +10,7 @@ import { GATE_REVIEWER_AGENT_NAMES, REVIEWER_ROLES_BY_SURFACE, resolveToolkitSur
 // 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;
+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 = [
@@ -22,6 +22,9 @@ const REVIEW_AGENT_TYPE_SET = new Set(REVIEW_AGENT_TYPES);
 export function applySpawnGuards(payload, options = {}) {
     if (payload.hook_event_name !== "PreToolUse" || !SPAWN_TOOL_TOKENS.has(payload.tool_name))
         return "";
+    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 };
     const stateDir = ulwLoopDir(payload.cwd, scope);
     const plan = readPlan(join(stateDir, "goals.json"));
@@ -43,7 +46,7 @@ function evaluateGuards(payload, plan, stateDir) {
         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);
@@ -52,6 +55,32 @@ function evaluateGuards(payload, plan, stateDir) {
         return deny(fanOutDenial);
     return "";
 }
+export async function runSpawnAdmissionRecorderCli(stdin, stdout) {
+    const chunks = [];
+    for await (const chunk of stdin)
+        chunks.push(Buffer.from(chunk));
+    try {
+        const payload = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        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");
+        mkdirSync(markerDir, { recursive: true });
+        atomicWriteJson(join(markerDir, `${payload["session_id"]}.json`), {
+            reason: response,
+            at: new Date().toISOString(),
+        });
+    }
+    catch {
+        /* malformed hook input is ignored */
+    }
+    void stdout;
+}
 export async function runSpawnGuardCli(stdin, stdout) {
     try {
         const chunks = [];
@@ -120,8 +149,7 @@ function missingGateArtifact(payload, plan) {
     if (!goal.successCriteria.every((criterion) => criterion.status === "pass"))
         return null;
     const scope = { sessionId: payload.session_id };
-    const surface = resolveToolkitSurface();
-    const requiredArtifacts = surface === "omo-senpi" ? [`${goal.id}-manual-qa.md`] : [`${goal.id}-code-review.md`, `${goal.id}-manual-qa.md`];
+    const requiredArtifacts = [`${goal.id}-manual-qa.md`];
     if (plan.evidenceLayoutVersion === 2) {
         const attemptDir = ulwLoopAttemptEvidenceDir(goal.id, goal.attempt, scope);
         for (const name of requiredArtifacts) {
@@ -131,17 +159,8 @@ function missingGateArtifact(payload, plan) {
         }
         return null;
     }
-    const flatReport = `.omo/evidence/${goal.id}-code-review.md`;
-    if (surface !== "omo-senpi" && !isNonEmptyFile(join(payload.cwd, flatReport)))
-        return flatReport;
-    if (surface === "omo-senpi") {
-        const manualQa = `.omo/evidence/${goal.id}-manual-qa.md`;
-        return isNonEmptyFile(join(payload.cwd, manualQa)) ? null : manualQa;
-    }
-    // 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/${goal.id}-manual-qa.md`;
-    return null;
+    const manualQa = `.omo/evidence/${goal.id}-manual-qa.md`;
+    return isNonEmptyFile(join(payload.cwd, manualQa)) ? null : manualQa;
 }
 function isGateReviewerSpawn(toolInput) {
     const agentType = reviewAgentType(toolInput);
@@ -212,6 +231,18 @@ function deny(reason) {
         },
     })}\n`;
 }
+function readAdmissionBreaker(sessionId) {
+    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"));
+        return typeof value.reason === "string" ? value.reason : "capacity limit";
+    }
+    catch {
+        return null;
+    }
+}
 function fanOutLimit() {
     const raw = process.env["OMO_SPAWN_FANOUT_LIMIT"];
     if (raw === undefined)
@@ -236,16 +267,6 @@ function isNonEmptyFile(path) {
         throw error;
     }
 }
-function hasOtherEvidenceFile(evidenceDir, excludedName) {
-    try {
-        return readdirSync(evidenceDir).some((name) => name !== excludedName && isNonEmptyFile(join(evidenceDir, name)));
-    }
-    catch (error) {
-        if (error instanceof Error)
-            return false;
-        throw error;
-    }
-}
 function readCount(counterPath) {
     try {
         const parsed = JSON.parse(readFileSync(counterPath, "utf8"));

package/packages/omo-codex/plugin/components/ulw-loop/dist/status-next-actions.js

@@ -25,9 +25,9 @@ function activeGoalActions(plan, active) {
         ];
     if (hasAllCriteriaPass(active) && isFinalRunCompletionCandidate(plan, active))
         return [
-            `${active.id} passes every criterion and is the final story: update_goal complete, then checkpoint --print-template to build the final quality gate.`,
+            `${active.id} passes every criterion and is the final story: update_goal complete, then checkpoint --print-template to build the final quality gate. Use status --json's currentAttemptDir for all quality-gate artifacts.`,
         ];
     return [
-        `${active.id} passes every criterion: close it with \`omo-agent-toolkit ulw-loop checkpoint --goal-id ${active.id} --status complete --evidence "<proof>" --codex-goal-json '<get_goal json>'\`.`,
+        `${active.id} passes every criterion: close it with \`omo-agent-toolkit ulw-loop checkpoint --goal-id ${active.id} --status complete --evidence "<proof>" --codex-goal-json '<get_goal json>'\`. Put quality-gate artifacts under the currentAttemptDir shown by status --json.`,
     ];
 }

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

@@ -8,6 +8,7 @@ export declare const REVIEWER_ROLES_BY_SURFACE: Readonly<Record<UlwLoopToolkitSu
 export declare const GATE_REVIEWER_AGENT_NAMES: ReadonlySet<string>;
 export type UlwLoopGateSection = "codeReview" | "manualQa" | "gateReview" | "iteration" | "criteriaCoverage";
 export declare const REQUIRED_GATE_SECTIONS_BY_SURFACE: Readonly<Record<UlwLoopToolkitSurface, readonly UlwLoopGateSection[]>>;
+export declare const OPTIONAL_GATE_SECTIONS_BY_SURFACE: Readonly<Record<UlwLoopToolkitSurface, readonly UlwLoopGateSection[]>>;
 export declare const GATE_SECTION_BY_ACCEPTOR: Readonly<Record<UlwLoopToolkitSurface, Readonly<Partial<Record<UlwLoopGateSection, readonly string[]>>>>>;
 export declare function reviewerRolesFor(surface: UlwLoopToolkitSurface): UlwLoopReviewerRoles;
 export declare const SURFACE_MARKER_FILENAME = "surface.json";

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

@@ -15,14 +15,24 @@ export const REVIEWER_ROLES_BY_SURFACE = {
 };
 export const GATE_REVIEWER_AGENT_NAMES = new Set(Object.values(REVIEWER_ROLES_BY_SURFACE).map((roles) => roles.gateReview));
 export const REQUIRED_GATE_SECTIONS_BY_SURFACE = {
-    lazycodex: ["codeReview", "manualQa", "gateReview", "iteration", "criteriaCoverage"],
+    lazycodex: ["manualQa", "gateReview", "iteration", "criteriaCoverage"],
     "omo-senpi": ["manualQa", "gateReview", "iteration", "criteriaCoverage"],
 };
+export const OPTIONAL_GATE_SECTIONS_BY_SURFACE = {
+    lazycodex: ["codeReview"],
+    "omo-senpi": [],
+};
 export const GATE_SECTION_BY_ACCEPTOR = {
     lazycodex: {
-        codeReview: [REVIEWER_ROLES_BY_SURFACE.lazycodex.codeReview],
-        manualQa: [REVIEWER_ROLES_BY_SURFACE.lazycodex.manualQa],
-        gateReview: [REVIEWER_ROLES_BY_SURFACE.lazycodex.gateReview],
+        codeReview: [REVIEWER_ROLES_BY_SURFACE.lazycodex.codeReview, "main-session"],
+        manualQa: [REVIEWER_ROLES_BY_SURFACE.lazycodex.manualQa, "main-session"],
+        gateReview: [
+            REVIEWER_ROLES_BY_SURFACE.lazycodex.gateReview,
+            "category:deep",
+            "category:unspecified-high",
+            "category:unspecified-low",
+            "main-session",
+        ],
     },
     "omo-senpi": {
         manualQa: ["main-session"],

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

@@ -7,7 +7,20 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook user-prompt-submit --with-ultrawork",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.0.0-beta.48) Checking Ulw-Loop Steering"
+						"statusMessage": "(OmO 5.0.0-beta.49) Checking Ulw-Loop Steering"
+					}
+				]
+			}
+		],
+		"PostToolUse": [
+			{
+				"matcher": "^(spawn_agent|collaborationspawn_agent|collaboration\\.spawn_agent)$",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook post-tool-use-spawn",
+						"timeout": 5,
+						"statusMessage": "(OmO 5.0.0-beta.49) Recording Spawn Admission"
 					}
 				]
 			}
@@ -20,7 +33,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook pre-tool-use",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.48) Enforcing Unlimited Ulw-Loop Budget"
+						"statusMessage": "(OmO 5.0.0-beta.49) Enforcing Unlimited Ulw-Loop Budget"
 					}
 				]
 			},
@@ -31,7 +44,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook pre-tool-use-spawn",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.48) Guarding Ulw-Loop Spawns"
+						"statusMessage": "(OmO 5.0.0-beta.49) Guarding Ulw-Loop Spawns"
 					}
 				]
 			}
@@ -43,7 +56,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook stop",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.0.0-beta.48) Checking Ulw-Loop Resume"
+						"statusMessage": "(OmO 5.0.0-beta.49) 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.48",
+	"version": "5.0.0-beta.49",
 	"description": "Codex plugin: durable repo-native multi-goal orchestration with embedded success criteria and observable evidence audit.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",
@@ -38,7 +38,7 @@
 		"CHANGELOG.md"
 	],
 	"scripts": {
-		"build": "tsc -p tsconfig.build.json",
+		"build": "tsc -p tsconfig.build.json && bun build src/cli.ts --target node --format esm --outfile dist/cli.js",
 		"test": "vitest --run",
 		"test:watch": "vitest",
 		"typecheck": "tsc --noEmit",

package/packages/omo-codex/plugin/components/ulw-loop/skills/ulw-loop/references/full-workflow.md

@@ -198,7 +198,7 @@ omo-agent-toolkit ulw-loop checkpoint --goal-id <g> --status complete --evidence
 omo-agent-toolkit ulw-loop complete-goals
 ```
 
-The lazycodex gate uses all five sections shown in the sample below, including `codeReview`.
+The lazycodex gate requires `manualQa`, `gateReview`, `iteration`, and `criteriaCoverage`; `codeReview` is optional. Self-review defaults to `main-session`, while gate review may use `main-session` or an approved `category:*` acceptor. Spawn reviewer lanes only when strict review is explicitly requested.
 
 ## Final Quality Gate
 Trigger only for the final aggregate goal after every criterion in every goal is `pass`.

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

@@ -31,7 +31,7 @@ function gateTemplate(surface: UlwLoopToolkitSurface, base: string): Record<stri
 		},
 	];
 	const manualQa = {
-		by: surface === "omo-senpi" ? "main-session" : "lazycodex-qa-executor",
+		by: "main-session",
 		status: "passed",
 		evidence: "<replace:manual QA evidence>",
 		surfaceEvidence: [
@@ -68,7 +68,7 @@ function gateTemplate(surface: UlwLoopToolkitSurface, base: string): Record<stri
 	const common = {
 		manualQa,
 		gateReview: {
-			by: surface === "omo-senpi" ? "category:deep" : "lazycodex-gate-reviewer",
+			by: surface === "omo-senpi" ? "category:deep" : "main-session",
 			recommendation: "APPROVE",
 			reportPath: artifactPath(base, "gate-review.md"),
 			evidence: "<replace:gate review evidence>",
@@ -90,18 +90,7 @@ function gateTemplate(surface: UlwLoopToolkitSurface, base: string): Record<stri
 			adversarialClassesCovered: ["<replace:adversarial class>"],
 		},
 	};
-	if (surface === "omo-senpi") return common;
-	return {
-		codeReview: {
-			by: "lazycodex-code-reviewer",
-			recommendation: "APPROVE",
-			codeQualityStatus: "CLEAR",
-			reportPath: artifactPath(base, "code-review.md"),
-			evidence: "<replace:code review evidence>",
-			blockers: [],
-		},
-		...common,
-	};
+	return common;
 }
 
 export async function checkpointTemplate(
@@ -121,6 +110,11 @@ export async function checkpointTemplate(
 		"Fill every <replace:...> value with plausible non-empty evidence and use real, non-empty artifact files.",
 		'Passing codex-goal-json example: {"goal":{"objective":"<plan codexObjective verbatim>","status":"complete"}}.',
 		'Passing quality-gate-json example requires gateReview {"by":"category:deep","recommendation":"APPROVE","evidence":"review passed","reportPath":"<attemptDir>/gate-review.md","blockers":[],"notes":[]}, manualQa.artifactRefs objects, iteration, and criteriaCoverage.',
+		...(resolveToolkitSurface() === "lazycodex"
+			? [
+					"Self-review defaults: manualQa.by and gateReview.by are main-session. Alternatives: manualQa.by accepts lazycodex-qa-executor; gateReview.by accepts lazycodex-gate-reviewer, category:deep, category:unspecified-high, or category:unspecified-low. Optional codeReview.by accepts lazycodex-code-reviewer or main-session.",
+				]
+			: []),
 		...(hasAttempt ? [] : ["This plan is evidence-layout v1; artifacts go under .omo/evidence/."]),
 	].join(" ");
 	return {

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

@@ -126,7 +126,7 @@ function buildLedger(
 	codexGoal: unknown,
 	aggregateCompletion: UlwLoopAggregateCompletion | undefined,
 ): UlwLoopLedgerEntry {
-	const watch = qualityGate?.surface === "lazycodex" && qualityGate.codeReview.codeQualityStatus === "WATCH";
+	const watch = qualityGate?.surface === "lazycodex" && qualityGate.codeReview?.codeQualityStatus === "WATCH";
 	const entry: UlwLoopLedgerEntry = {
 		at: now,
 		kind: ledgerKind(args.status, goal, aggregateCompletion),
@@ -134,7 +134,7 @@ function buildLedger(
 		status: goal.status,
 		evidence:
 			watch && qualityGate.surface === "lazycodex"
-				? `${args.evidence} | codeQuality=WATCH: ${qualityGate.codeReview.evidence}`
+				? `${args.evidence} | codeQuality=WATCH: ${qualityGate.codeReview?.evidence ?? ""}`
 				: args.evidence,
 	};
 	if (codexGoal !== undefined) entry.codexGoal = codexGoal;

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

@@ -16,7 +16,7 @@ export const ULW_LOOP_HELP = `Usage:
   omo-agent-toolkit ulw-loop add-goal --title "..." --objective "..." [--json]
   omo-agent-toolkit ulw-loop record-review-blockers --goal-id <id> --title "..." --objective "..." --evidence "..." --codex-goal-json <...> [--json]
 
-Every state subcommand needs a session scope: [--session-id <id>] or the session env (OMO_ULW_LOOP_SESSION_ID / CODEX_SESSION_ID / CODEX_THREAD_ID / PI_SESSION_ID); state lives under .omo/ulw-loop/<id>/ and the unscoped root is never used implicitly.
+Every state subcommand needs a session scope: [--session-id <id>] or the session env (OMO_ULW_LOOP_SESSION_ID / CODEX_SESSION_ID / CODEX_THREAD_ID / PI_SESSION_ID); state lives under .omo/ulw-loop/<id>/ and the unscoped root is never used implicitly. status --json exposes the currentAttemptDir; put all quality-gate artifacts under it.
 Every subcommand accepts --help | -h to print its own usage line.`;
 
 export function subcommandHelp(subcommand: string): string {

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

@@ -2,7 +2,7 @@
 import { isUlwLoopSubcommand, ulwLoopCommand } from "./cli-commands.js";
 import { ULW_LOOP_HELP } from "./cli-output.js";
 import { runPreToolUseGoalBudgetGuardCli, runUlwLoopHookCli } from "./codex-hook.js";
-import { runSpawnGuardCli } from "./spawn-guard.js";
+import { runSpawnAdmissionRecorderCli, runSpawnGuardCli } from "./spawn-guard.js";
 import { runStopResumeHookCli } from "./stop-resume-hook.js";
 
 async function main(): Promise<number> {
@@ -29,6 +29,10 @@ async function main(): Promise<number> {
 			await runStopResumeHookCli(process.stdin, process.stdout);
 			return 0;
 		}
+		if (sub === "post-tool-use-spawn") {
+			await runSpawnAdmissionRecorderCli(process.stdin, process.stdout);
+			return 0;
+		}
 		if (sub === "pre-tool-use-spawn") {
 			await runSpawnGuardCli(process.stdin, process.stdout);
 			return 0;

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

@@ -131,12 +131,11 @@ function finalSection(
 	const blockerCommand = `omo-agent-toolkit ulw-loop record-review-blockers${option} --goal-id ${goal.id} --title "Resolve final code-review blockers" --objective "<blocker-resolution objective>" --evidence "<review findings>" --codex-goal-json "<active get_goal JSON or path>"`;
 	const checkpointCommand = `omo-agent-toolkit ulw-loop checkpoint${option} --goal-id ${goal.id} --status complete --evidence "<targeted verification/manualQa/gateReview evidence>" --codex-goal-json "<fresh complete get_goal JSON or path>" --quality-gate-json "<quality gate JSON or path>"`;
 	return joinLines([
-		"Final story — run mandatory quality gate before update_goal:",
+		"Final story — self-review and manual QA are the default; use the quality gate before update_goal:",
 		"- Run targeted verification for changed behavior.",
 		"- Confirm every manualQa artifact path exists and has non-zero size.",
-		`- 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.",
+		`- Run manual QA yourself and write its artifact under currentAttemptDir. Only if the user explicitly demands strict, rigorous, or high-accuracy review, spawn ${roles.gateReview}, optionally also ${roles.codeReview} and ${roles.manualQa}; otherwise set manualQa.by and gateReview.by to "main-session".`,
+		"- Require passed manualQa, approved gateReview, passed iteration, and complete criteriaCoverage; include codeReview only when strict review was requested. 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.",
 		"- If any reviewer is blocked/inconclusive or the quality gate is not clean, do not call update_goal. Record blocker work first:",

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

@@ -141,7 +141,7 @@ interface UlwLoopQualityGateCommon {
 
 export interface UlwLoopQualityGateLazycodex extends UlwLoopQualityGateCommon {
 	readonly surface: "lazycodex";
-	readonly codeReview: {
+	readonly codeReview?: {
 		readonly by: string;
 		readonly recommendation: "APPROVE";
 		readonly codeQualityStatus: "CLEAR" | "WATCH";

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

@@ -61,7 +61,10 @@ export function isRecord(value: unknown): value is Record<string, unknown> {
 }
 export function section(value: unknown, field: string): Record<string, unknown> {
 	if (isRecord(value)) return value;
-	invalid(`Final quality gate is missing ${field} evidence.`, field);
+	invalid(
+		`Final quality gate is missing ${field} evidence (accepted input: a bare object with manualQa/gateReview/iteration/criteriaCoverage and optional codeReview, or the same object under a top-level "qualityGate" key).`,
+		field,
+	);
 	return {};
 }
 export function textField(value: unknown, field: string): string {

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

@@ -20,7 +20,12 @@ import {
 	withQualityGateCollector,
 } from "./quality-gate-fields.js";
 import { adversarialVerdict, codeQualityStatusField, passedVerdict } from "./quality-gate-verdicts.js";
-import { GATE_SECTION_BY_ACCEPTOR, type UlwLoopToolkitSurface } from "./surface.js";
+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 {
@@ -42,20 +47,10 @@ export interface ValidateQualityGateOptions {
 	readonly reviewerSurface?: UlwLoopToolkitSurface;
 }
 
-function reviewerRoleField(value: unknown, expected: string, field: string): string {
-	if (typeof value !== "string" || value.trim() === "") {
-		textField(value, field);
-		return expected;
-	}
-	const actual = textField(value, field);
-	if (actual !== expected) invalid(`${field} must be ${expected}.`, field);
-	return expected;
-}
-
 function reviewerAcceptorField(
 	value: unknown,
 	surface: UlwLoopToolkitSurface,
-	sectionName: "manualQa" | "gateReview",
+	sectionName: "codeReview" | "manualQa" | "gateReview",
 ): string {
 	const field = `${sectionName}.by`;
 	const accepted = GATE_SECTION_BY_ACCEPTOR[surface][sectionName];
@@ -75,19 +70,28 @@ export function validateQualityGate(input: unknown, opts?: ValidateQualityGateOp
 
 function validateQualityGateUncollected(input: unknown, opts?: ValidateQualityGateOptions): UlwLoopQualityGate {
 	const surface = opts?.reviewerSurface ?? "lazycodex";
-	const gate = section(input, "qualityGate");
+	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);
+	}
 	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 = surface === "lazycodex" ? section(gate["codeReview"], "codeReview") : {};
+	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");
-	if (surface === "lazycodex") reviewerRoleField(codeReview?.["by"], "lazycodex-code-reviewer", "codeReview.by");
+
 	const totalCriteria = numberField(coverage["totalCriteria"], "criteriaCoverage.totalCriteria");
 	const passCount = numberField(coverage["passCount"], "criteriaCoverage.passCount");
 	if (!isPoisoned("criteriaCoverage.passCount") && passCount < totalCriteria)
@@ -133,13 +137,14 @@ function validateQualityGateUncollected(input: unknown, opts?: ValidateQualityGa
 		},
 	};
 	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: "lazycodex-code-reviewer",
+			by: reviewerAcceptorField(codeReview["by"], surface, "codeReview"),
 			recommendation: literal(codeReview["recommendation"], "APPROVE", "codeReview.recommendation"),
 			codeQualityStatus: codeQualityStatusField(codeReview["codeQualityStatus"], "codeReview.codeQualityStatus"),
 			reportPath: codeReportPath,

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

@@ -1,5 +1,5 @@
 import { randomBytes } from "node:crypto";
-import { existsSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
 import type { PreToolUsePayload } from "./codex-hook.js";
@@ -19,7 +19,7 @@ import type { UlwLoopPlan } from "./types.js";
 // 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;
+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 = [
@@ -35,6 +35,11 @@ export interface SpawnGuardOptions {
 
 export function applySpawnGuards(payload: PreToolUsePayload, options: SpawnGuardOptions = {}): string {
 	if (payload.hook_event_name !== "PreToolUse" || !SPAWN_TOOL_TOKENS.has(payload.tool_name)) return "";
+	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"));
@@ -59,7 +64,7 @@ function evaluateGuards(payload: PreToolUsePayload, plan: UlwLoopPlan, 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);
@@ -67,6 +72,34 @@ function evaluateGuards(payload: PreToolUsePayload, plan: UlwLoopPlan, stateDir:
 	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");
+		mkdirSync(markerDir, { recursive: true });
+		atomicWriteJson(join(markerDir, `${payload["session_id"]}.json`), {
+			reason: response,
+			at: new Date().toISOString(),
+		});
+	} catch {
+		/* malformed hook input is ignored */
+	}
+	void stdout;
+}
+
 export async function runSpawnGuardCli(stdin: NodeJS.ReadableStream, stdout: NodeJS.WritableStream): Promise<void> {
 	try {
 		const chunks: Buffer[] = [];
@@ -128,9 +161,7 @@ function missingGateArtifact(payload: PreToolUsePayload, plan: UlwLoopPlan): str
 	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 surface = resolveToolkitSurface();
-	const requiredArtifacts =
-		surface === "omo-senpi" ? [`${goal.id}-manual-qa.md`] : [`${goal.id}-code-review.md`, `${goal.id}-manual-qa.md`];
+	const requiredArtifacts = [`${goal.id}-manual-qa.md`];
 	if (plan.evidenceLayoutVersion === 2) {
 		const attemptDir = ulwLoopAttemptEvidenceDir(goal.id, goal.attempt, scope);
 		for (const name of requiredArtifacts) {
@@ -139,16 +170,8 @@ function missingGateArtifact(payload: PreToolUsePayload, plan: UlwLoopPlan): str
 		}
 		return null;
 	}
-	const flatReport = `.omo/evidence/${goal.id}-code-review.md`;
-	if (surface !== "omo-senpi" && !isNonEmptyFile(join(payload.cwd, flatReport))) return flatReport;
-	if (surface === "omo-senpi") {
-		const manualQa = `.omo/evidence/${goal.id}-manual-qa.md`;
-		return isNonEmptyFile(join(payload.cwd, manualQa)) ? null : manualQa;
-	}
-	// 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/${goal.id}-manual-qa.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 {
@@ -216,6 +239,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;
@@ -239,15 +275,6 @@ function isNonEmptyFile(path: string): boolean {
 	}
 }
 
-function hasOtherEvidenceFile(evidenceDir: string, excludedName: string): boolean {
-	try {
-		return readdirSync(evidenceDir).some((name) => name !== excludedName && isNonEmptyFile(join(evidenceDir, name)));
-	} catch (error) {
-		if (error instanceof Error) return false;
-		throw error;
-	}
-}
-
 function readCount(counterPath: string): number {
 	try {
 		const parsed = JSON.parse(readFileSync(counterPath, "utf8")) as Record<string, unknown>;

package/packages/omo-codex/plugin/components/ulw-loop/src/status-next-actions.ts

@@ -28,9 +28,9 @@ function activeGoalActions(plan: UlwLoopPlan, active: UlwLoopItem): readonly str
 		];
 	if (hasAllCriteriaPass(active) && isFinalRunCompletionCandidate(plan, active))
 		return [
-			`${active.id} passes every criterion and is the final story: update_goal complete, then checkpoint --print-template to build the final quality gate.`,
+			`${active.id} passes every criterion and is the final story: update_goal complete, then checkpoint --print-template to build the final quality gate. Use status --json's currentAttemptDir for all quality-gate artifacts.`,
 		];
 	return [
-		`${active.id} passes every criterion: close it with \`omo-agent-toolkit ulw-loop checkpoint --goal-id ${active.id} --status complete --evidence "<proof>" --codex-goal-json '<get_goal json>'\`.`,
+		`${active.id} passes every criterion: close it with \`omo-agent-toolkit ulw-loop checkpoint --goal-id ${active.id} --status complete --evidence "<proof>" --codex-goal-json '<get_goal json>'\`. Put quality-gate artifacts under the currentAttemptDir shown by status --json.`,
 	];
 }