lazycodex-ai 5.0.0-beta.7 → 5.0.0-beta.71

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

@@ -1,24 +1,47 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { Readable, Writable } from "node:stream";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import type { PreToolUsePayload } from "../src/codex-hook.ts";
-import { applySpawnGuards } from "../src/spawn-guard.ts";
+// Budget/artifact behavior is independent of role admission; the native entry
+// point and its composition are covered in spawn-role-matrix.test.ts.
+import {
+	applySpawnBudgetGuards as applySpawnGuards,
+	DEFAULT_FANOUT_LIMIT,
+	runSpawnAdmissionRecorderCli,
+} from "../src/spawn-guard.ts";
 
 let workDir: string;
 let originalLimit: string | undefined;
+let originalReviewLimit: string | undefined;
+let originalToolkitSurface: string | undefined;
+let originalPluginData: string | undefined;
 
 beforeEach(async () => {
 	workDir = await mkdtemp(join(tmpdir(), "ulw-spawn-guard-"));
+	originalPluginData = process.env["PLUGIN_DATA"];
+	process.env["PLUGIN_DATA"] = join(workDir, "plugin-data");
 	originalLimit = process.env["OMO_SPAWN_FANOUT_LIMIT"];
+	originalReviewLimit = process.env["OMO_ULW_LOOP_REVIEW_SPAWN_LIMIT"];
+	originalToolkitSurface = process.env["OMO_AGENT_TOOLKIT_SURFACE"];
 	delete process.env["OMO_SPAWN_FANOUT_LIMIT"];
+	delete process.env["OMO_ULW_LOOP_REVIEW_SPAWN_LIMIT"];
+	delete process.env["OMO_AGENT_TOOLKIT_SURFACE"];
 });
 
 afterEach(async () => {
+	delete process.env["OMO_AGENT_TOOLKIT_SURFACE"];
 	if (originalLimit === undefined) delete process.env["OMO_SPAWN_FANOUT_LIMIT"];
 	else process.env["OMO_SPAWN_FANOUT_LIMIT"] = originalLimit;
+	if (originalReviewLimit === undefined) delete process.env["OMO_ULW_LOOP_REVIEW_SPAWN_LIMIT"];
+	else process.env["OMO_ULW_LOOP_REVIEW_SPAWN_LIMIT"] = originalReviewLimit;
+	if (originalToolkitSurface === undefined) delete process.env["OMO_AGENT_TOOLKIT_SURFACE"];
+	else process.env["OMO_AGENT_TOOLKIT_SURFACE"] = originalToolkitSurface;
+	if (originalPluginData === undefined) delete process.env["PLUGIN_DATA"];
+	else process.env["PLUGIN_DATA"] = originalPluginData;
 	await rm(workDir, { recursive: true, force: true });
 });
 
@@ -87,7 +110,86 @@ function deny(output: string): { permissionDecision: string; permissionDecisionR
 	return JSON.parse(output).hookSpecificOutput;
 }
 
+describe("spawn admission breaker", () => {
+	async function record(response: unknown): Promise<string> {
+		let output = "";
+		const stdout = new Writable({
+			write(chunk, _encoding, callback) {
+				output += chunk.toString();
+				callback();
+			},
+		});
+		await runSpawnAdmissionRecorderCli(
+			Readable.from([
+				JSON.stringify({
+					...payload("spawn_agent", { message: "scan" }),
+					hook_event_name: "PostToolUse",
+					tool_response: response,
+				}),
+			]),
+			stdout,
+		);
+		return output;
+	}
+
+	it.each(["too many active cells", "AgentLimitReached", "max_threads", "max_concurrent_threads_per_session"])(
+		"records %s silently and denies without a plan while isolating other sessions",
+		async (reason) => {
+			expect(await record(reason)).toBe("");
+			const marker = JSON.parse(readFileSync(join(workDir, "plugin-data", "spawn-breaker", "s1.json"), "utf8"));
+			expect(Object.keys(marker).sort()).toEqual(["at", "reason"]);
+			expect(marker.reason).toBe(reason);
+			expect(Number.isFinite(Date.parse(marker.at))).toBe(true);
+			expect(deny(applySpawnGuards(payload("spawn_agent", {}))).permissionDecision).toBe("deny");
+			expect(applySpawnGuards({ ...payload("spawn_agent", {}), session_id: "clean" })).toBe("");
+		},
+	);
+
+	it("does not record a successful admission", async () => {
+		expect(await record({ agent_id: "worker-1" })).toBe("");
+		expect(existsSync(join(workDir, "plugin-data", "spawn-breaker", "s1.json"))).toBe(false);
+	});
+
+	it("denies before artifact, quota, and state lock guards", async () => {
+		writeGoals();
+		writeFileSync(
+			join(sessionDir(), ".state.lock"),
+			JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString(), token: "live" }),
+		);
+		await record("AgentLimitReached");
+		const output = deny(
+			applySpawnGuards(payload("spawn_agent", { agent_type: "lazycodex-gate-reviewer" }), { lockTimeoutMs: 0 }),
+		);
+		expect(output.permissionDecisionReason).toContain("AgentLimitReached");
+		expect(existsSync(join(sessionDir(), "spawn-count.json"))).toBe(false);
+		expect(existsSync(join(sessionDir(), "review-spawn-counts.json"))).toBe(false);
+	});
+
+	it.skipIf(process.getuid?.() === 0)(
+		"#given PLUGIN_DATA is a file #when recording an admission failure #then reports persist failure on stderr and keeps stdout empty",
+		async () => {
+			const blocked = join(workDir, "blocked-plugin-data");
+			writeFileSync(blocked, "not-a-directory");
+			process.env["PLUGIN_DATA"] = blocked;
+			const err: string[] = [];
+			const spy = vi.spyOn(process.stderr, "write").mockImplementation((chunk: string | Uint8Array): boolean => {
+				err.push(chunk.toString());
+				return true;
+			});
+			try {
+				await expect(record("too many active cells")).resolves.toBe("");
+				expect(err.join("")).toContain("could not persist");
+			} finally {
+				spy.mockRestore();
+			}
+		},
+	);
+});
+
 describe("applySpawnGuards fan-out cap", () => {
+	it("defaults to 24 spawns", () => {
+		expect(DEFAULT_FANOUT_LIMIT).toBe(24);
+	});
 	it("#given spawns under the limit #when guarded #then allows and counts", () => {
 		writeGoals();
 
@@ -132,7 +234,118 @@ describe("applySpawnGuards fan-out cap", () => {
 	});
 });
 
+describe("applySpawnGuards fan-out cap + reviewer quota interaction", () => {
+	it("#given fan-out cap exhausted #when a reviewer spawns #then denies without charging reviewer quota", () => {
+		writeGoals();
+		process.env["OMO_SPAWN_FANOUT_LIMIT"] = "3";
+
+		// exhaust the fan-out cap with non-reviewer spawns
+		expect(applySpawnGuards(payload("spawn_agent", { message: "scan" }))).toBe("");
+		expect(applySpawnGuards(payload("spawn_agent", { message: "scan" }))).toBe("");
+		expect(applySpawnGuards(payload("spawn_agent", { message: "scan" }))).toBe("");
+
+		// reviewer spawn while cap is exhausted — must deny without incrementing reviewer count
+		const reviewSpawn = payload("spawn_agent", {
+			agent_type: "lazycodex-code-reviewer",
+			message: "review the current diff",
+		});
+		const result = applySpawnGuards(reviewSpawn);
+		expect(result).not.toBe("");
+		expect(deny(result).permissionDecisionReason).toContain("4/3");
+
+		// reviewer quota must be untouched — a subsequent spawn after raising the limit must succeed
+		process.env["OMO_SPAWN_FANOUT_LIMIT"] = "10";
+		expect(applySpawnGuards(reviewSpawn)).toBe("");
+		const counters = JSON.parse(readFileSync(join(sessionDir(), "review-spawn-counts.json"), "utf8"));
+		expect(counters["lazycodex-code-reviewer:g1:a1"]).toBe(1);
+	});
+});
+
+describe("applySpawnGuards review repetition cap", () => {
+	it("#given one goal attempt #when the same reviewer spawns four times #then denies until the attempt advances", () => {
+		writeGoals();
+		const reviewSpawn = payload("spawn_agent", {
+			agent_type: "lazycodex-code-reviewer",
+			message: "review the current diff",
+		});
+
+		expect(applySpawnGuards(reviewSpawn)).toBe("");
+		expect(applySpawnGuards(reviewSpawn)).toBe("");
+		expect(applySpawnGuards(reviewSpawn)).toBe("");
+
+		const fourth = applySpawnGuards(reviewSpawn);
+		expect(fourth).not.toBe("");
+		expect(deny(fourth).permissionDecisionReason).toContain("4/3");
+		const counter = JSON.parse(readFileSync(join(sessionDir(), "spawn-count.json"), "utf8"));
+		expect(counter.count).toBe(3);
+
+		const goalsPath = join(sessionDir(), "goals.json");
+		const plan = JSON.parse(readFileSync(goalsPath, "utf8")) as {
+			goals: Array<{ attempt: number }>;
+		};
+		const [goal] = plan.goals;
+		if (goal === undefined) throw new Error("fixture must include a goal");
+		goal.attempt = 2;
+		writeFileSync(goalsPath, JSON.stringify(plan));
+
+		expect(applySpawnGuards(reviewSpawn)).toBe("");
+	});
+
+	it.each(["lazycodex-code-reviewer", "lazycodex-qa-executor"])(
+		"#given a MultiAgentV2 %s message #when it spawns four times #then applies the reviewer cap",
+		(agentType) => {
+			writeGoals();
+			const reviewSpawn = payload("spawn_agent", {
+				message: `Delegate this final-quality lane to ${agentType}`,
+			});
+
+			expect(applySpawnGuards(reviewSpawn)).toBe("");
+			expect(applySpawnGuards(reviewSpawn)).toBe("");
+			expect(applySpawnGuards(reviewSpawn)).toBe("");
+
+			const fourth = deny(applySpawnGuards(reviewSpawn));
+			expect(fourth.permissionDecisionReason).toContain(`${agentType} 4/3`);
+		},
+	);
+
+	it("#given exhausted code reviews and an explicit QA assignment #when a mixed V2 prompt is guarded #then charges the QA role", () => {
+		writeGoals();
+		const codeReview = payload("collaboration.spawn_agent", {
+			message: "Act as lazycodex-code-reviewer; review the current diff",
+		});
+
+		expect(applySpawnGuards(codeReview)).toBe("");
+		expect(applySpawnGuards(codeReview)).toBe("");
+		expect(applySpawnGuards(codeReview)).toBe("");
+
+		const output = applySpawnGuards(
+			payload("collaboration.spawn_agent", {
+				message: "Act as a lazycodex-qa-executor; verify the lazycodex-code-reviewer finding",
+			}),
+		);
+		expect(output).toBe("");
+
+		const counters = JSON.parse(readFileSync(join(sessionDir(), "review-spawn-counts.json"), "utf8"));
+		expect(counters["lazycodex-code-reviewer:g1:a1"]).toBe(3);
+		expect(counters["lazycodex-qa-executor:g1:a1"]).toBe(1);
+	});
+});
+
 describe("applySpawnGuards gate-artifact guard", () => {
+	it("#given a mixed-role V2 gate prompt #when guarded #then prioritizes the gate role and denies on missing artifact without charging quota", () => {
+		writeGoals();
+
+		const output = applySpawnGuards(
+			payload("spawn_agent", {
+				message: "Act as lazycodex-gate-reviewer; audit the lazycodex-code-reviewer report",
+			}),
+		);
+
+		expect(output).not.toBe("");
+		expect(deny(output).permissionDecisionReason).toContain("g1-manual-qa.md");
+		expect(existsSync(join(sessionDir(), "review-spawn-counts.json"))).toBe(false);
+	});
+
 	it("#given a gate spawn by agent_type without artifacts #when guarded #then denies naming the missing path", () => {
 		writeGoals();
 
@@ -143,7 +356,54 @@ describe("applySpawnGuards gate-artifact guard", () => {
 		const parsed = deny(output);
 		expect(parsed.permissionDecision).toBe("deny");
 		expect(parsed.permissionDecisionReason).toContain("missing");
-		expect(parsed.permissionDecisionReason).toContain("g1-code-review.md");
+		expect(parsed.permissionDecisionReason).toContain("g1-manual-qa.md");
+	});
+
+	it("#given senpi main-session QA is present but code review is absent #when the gate reviewer spawns #then the self-check allows it", () => {
+		process.env["OMO_AGENT_TOOLKIT_SURFACE"] = "omo-senpi";
+		writeGoals();
+		mkdirSync(join(workDir, ".omo", "evidence"), { recursive: true });
+		writeFileSync(join(workDir, ".omo", "evidence", "g1-manual-qa.md"), "matrix\n");
+
+		const output = applySpawnGuards(
+			payload("collaborationspawn_agent", { agent_type: "omo-senpi-gate-reviewer", message: "audit the artifacts" }),
+		);
+
+		expect(output).toBe("");
+	});
+
+	it("#given senpi QA is absent #when the gate reviewer spawns #then the self-check blocks naming manual QA", () => {
+		process.env["OMO_AGENT_TOOLKIT_SURFACE"] = "omo-senpi";
+		writeGoals();
+
+		const output = applySpawnGuards(
+			payload("collaborationspawn_agent", { agent_type: "omo-senpi-gate-reviewer", message: "audit the artifacts" }),
+		);
+
+		const parsed = deny(output);
+		expect(parsed.permissionDecision).toBe("deny");
+		expect(parsed.permissionDecisionReason).toContain("g1-manual-qa.md");
+	});
+
+	it("#given an omo-senpi gate spawn with a code-review artifact only #when guarded #then blocks the missing manual QA", () => {
+		process.env["OMO_AGENT_TOOLKIT_SURFACE"] = "omo-senpi";
+		writeGoals();
+		mkdirSync(join(workDir, ".omo", "evidence"), { recursive: true });
+		writeFileSync(join(workDir, ".omo", "evidence", "g1-code-review.md"), "report\n");
+
+		const output = applySpawnGuards(
+			payload("collaborationspawn_agent", { agent_type: "omo-senpi-gate-reviewer", message: "audit the artifacts" }),
+		);
+
+		expect(deny(output).permissionDecisionReason).toContain("g1-manual-qa.md");
+	});
+
+	it("#given an omo-senpi gate reviewer named in the message #when guarded #then still denies", () => {
+		writeGoals();
+
+		const output = applySpawnGuards(payload("spawn_agent", { message: "spawn omo-senpi-gate-reviewer now" }));
+
+		expect(deny(output).permissionDecision).toBe("deny");
 	});
 
 	it("#given a gate spawn identified by message only #when guarded #then still denies", () => {
@@ -154,11 +414,53 @@ describe("applySpawnGuards gate-artifact guard", () => {
 		expect(deny(output).permissionDecision).toBe("deny");
 	});
 
-	it("#given v1 artifacts on disk #when the gate spawns #then allows", () => {
+	it("#given the staged Senpi surface #when generic and explicit gate spawns alternate #then they share one cap", () => {
 		writeGoals();
+		process.env["OMO_AGENT_TOOLKIT_SURFACE"] = "omo-senpi";
 		mkdirSync(join(workDir, ".omo", "evidence"), { recursive: true });
 		writeFileSync(join(workDir, ".omo", "evidence", "g1-code-review.md"), "report\n");
 		writeFileSync(join(workDir, ".omo", "evidence", "g1-manual-qa.md"), "matrix\n");
+		const genericGate = payload("spawn_agent", { message: "run the final gate review now" });
+		const explicitGate = payload("spawn_agent", {
+			message: "Act as omo-senpi-gate-reviewer; audit the final evidence",
+		});
+
+		expect(applySpawnGuards(genericGate)).toBe("");
+		expect(applySpawnGuards(explicitGate)).toBe("");
+		expect(applySpawnGuards(genericGate)).toBe("");
+
+		const fourth = deny(applySpawnGuards(explicitGate));
+		expect(fourth.permissionDecisionReason).toContain("omo-senpi-gate-reviewer 4/3");
+		const counters = JSON.parse(readFileSync(join(sessionDir(), "review-spawn-counts.json"), "utf8"));
+		expect(counters["omo-senpi-gate-reviewer:g1:a1"]).toBe(3);
+		expect(counters["lazycodex-gate-reviewer:g1:a1"]).toBeUndefined();
+	});
+
+	it("#given the staged Senpi surface #when LazyCodex and Senpi aliases alternate #then one reviewer lane owns the cap", () => {
+		writeGoals();
+		process.env["OMO_AGENT_TOOLKIT_SURFACE"] = "omo-senpi";
+		const senpiReviewer = payload("spawn_agent", {
+			message: "Act as omo-senpi-code-reviewer; inspect the current diff",
+		});
+		const lazycodexReviewer = payload("spawn_agent", {
+			message: "Act as lazycodex-code-reviewer; inspect the current diff",
+		});
+
+		expect(applySpawnGuards(senpiReviewer)).toBe("");
+		expect(applySpawnGuards(lazycodexReviewer)).toBe("");
+		expect(applySpawnGuards(senpiReviewer)).toBe("");
+
+		const fourth = deny(applySpawnGuards(lazycodexReviewer));
+		expect(fourth.permissionDecisionReason).toContain("omo-senpi-code-reviewer 4/3");
+		const counters = JSON.parse(readFileSync(join(sessionDir(), "review-spawn-counts.json"), "utf8"));
+		expect(counters["omo-senpi-code-reviewer:g1:a1"]).toBe(3);
+		expect(counters["lazycodex-code-reviewer:g1:a1"]).toBeUndefined();
+	});
+
+	it("#given only v1 manual QA on disk #when the gate spawns #then allows", () => {
+		writeGoals();
+		mkdirSync(join(workDir, ".omo", "evidence"), { recursive: true });
+		writeFileSync(join(workDir, ".omo", "evidence", "g1-manual-qa.md"), "matrix\n");
 
 		const output = applySpawnGuards(
 			payload("spawn_agent", { agent_type: "lazycodex-gate-reviewer", message: "final gate review" }),
@@ -176,14 +478,13 @@ describe("applySpawnGuards gate-artifact guard", () => {
 			payload("spawn_agent", { agent_type: "lazycodex-gate-reviewer", message: "final gate review" }),
 		);
 
-		expect(deny(output).permissionDecisionReason).toContain(".omo/evidence/ulw/s1/g1/a1/g1-code-review.md");
+		expect(deny(output).permissionDecisionReason).toContain(".omo/evidence/ulw/s1/g1/a1/g1-manual-qa.md");
 	});
 
 	it("#given a v2 plan with attempt-dir artifacts #when the gate spawns #then allows", () => {
 		writeGoals({ evidenceLayoutVersion: 2 });
 		const attemptDir = join(workDir, ".omo", "evidence", "ulw", "s1", "g1", "a1");
 		mkdirSync(attemptDir, { recursive: true });
-		writeFileSync(join(attemptDir, "g1-code-review.md"), "report\n");
 		writeFileSync(join(attemptDir, "g1-manual-qa.md"), "matrix\n");
 
 		const output = applySpawnGuards(
@@ -226,3 +527,145 @@ describe("applySpawnGuards gate-artifact guard", () => {
 		expect(output).toBe("");
 	});
 });
+
+describe("applySpawnGuards V1 agent_type non-reviewer early-exit", () => {
+	it("#given a V1 spawn with a non-reviewer agent_type #when guarded #then allows without charging any quota", () => {
+		writeGoals();
+		const explorerSpawn = payload("spawn_agent", {
+			agent_type: "explorer",
+			message: "scan the codebase for lazycodex-code-reviewer patterns",
+		});
+
+		const result = applySpawnGuards(explorerSpawn);
+
+		expect(result).toBe("");
+		expect(existsSync(join(sessionDir(), "review-spawn-counts.json"))).toBe(false);
+	});
+
+	it("#given a V1 spawn with a non-reviewer agent_type mentioning a gate role #when guarded #then does not charge gate quota", () => {
+		writeGoals();
+		const explorerSpawn = payload("spawn_agent", {
+			agent_type: "deep",
+			message: "final gate review — summarize findings",
+		});
+
+		const result = applySpawnGuards(explorerSpawn);
+
+		expect(result).toBe("");
+		expect(existsSync(join(sessionDir(), "review-spawn-counts.json"))).toBe(false);
+	});
+});
+
+describe("applySpawnGuards V2 explicit non-reviewer act-as guard", () => {
+	it("#given an explicit 'act as explorer' assignment mentioning a reviewer #when guarded #then allows without charging reviewer quota", () => {
+		writeGoals();
+		const explorerSpawn = payload("spawn_agent", {
+			message: "Act as explorer; scan for lazycodex-code-reviewer usage patterns",
+		});
+
+		const result = applySpawnGuards(explorerSpawn);
+
+		expect(result).toBe("");
+		expect(existsSync(join(sessionDir(), "review-spawn-counts.json"))).toBe(false);
+	});
+
+	it("#given an explicit 'act as a deep' assignment with gate keyword #when guarded #then allows without charging gate quota", () => {
+		writeGoals();
+		const deepSpawn = payload("spawn_agent", {
+			message: "Act as a deep agent; run the final gate review summary",
+		});
+
+		const result = applySpawnGuards(deepSpawn);
+
+		expect(result).toBe("");
+		expect(existsSync(join(sessionDir(), "review-spawn-counts.json"))).toBe(false);
+	});
+
+	it("#given an explicit reviewer act-as assignment #when guarded #then still charges reviewer quota", () => {
+		writeGoals();
+		const reviewerSpawn = payload("spawn_agent", {
+			message: "Act as lazycodex-code-reviewer; inspect the diff",
+		});
+
+		const result = applySpawnGuards(reviewerSpawn);
+
+		expect(result).toBe("");
+		const counters = JSON.parse(readFileSync(join(sessionDir(), "review-spawn-counts.json"), "utf8"));
+		expect(counters["lazycodex-code-reviewer:g1:a1"]).toBe(1);
+	});
+});
+
+describe("applySpawnGuards gate-artifact check before reviewer quota", () => {
+	it("#given a gate spawn without artifacts #when the fan-out budget is available #then denies on artifact rule without charging reviewer quota", () => {
+		writeGoals();
+
+		const gateSpawn = payload("spawn_agent", {
+			agent_type: "lazycodex-gate-reviewer",
+			message: "final gate review",
+		});
+
+		const result = applySpawnGuards(gateSpawn);
+
+		expect(result).not.toBe("");
+		expect(deny(result).permissionDecisionReason).toContain("missing");
+		expect(existsSync(join(sessionDir(), "review-spawn-counts.json"))).toBe(false);
+	});
+
+	it("#given a gate spawn denied for missing artifacts #when retried after artifacts land #then charges quota only on the allowed spawn", () => {
+		writeGoals();
+		const gateSpawn = payload("spawn_agent", {
+			agent_type: "lazycodex-gate-reviewer",
+			message: "final gate review",
+		});
+
+		const firstResult = applySpawnGuards(gateSpawn);
+		expect(firstResult).not.toBe("");
+		expect(existsSync(join(sessionDir(), "review-spawn-counts.json"))).toBe(false);
+
+		mkdirSync(join(workDir, ".omo", "evidence"), { recursive: true });
+		writeFileSync(join(workDir, ".omo", "evidence", "g1-code-review.md"), "report\n");
+		writeFileSync(join(workDir, ".omo", "evidence", "g1-manual-qa.md"), "matrix\n");
+
+		const secondResult = applySpawnGuards(gateSpawn);
+		expect(secondResult).toBe("");
+		const counters = JSON.parse(readFileSync(join(sessionDir(), "review-spawn-counts.json"), "utf8"));
+		expect(counters["lazycodex-gate-reviewer:g1:a1"]).toBe(1);
+	});
+});
+
+describe("applySpawnGuards session state lock", () => {
+	function lockPath(): string {
+		return join(sessionDir(), ".state.lock");
+	}
+
+	it("#given the state lock held by a live process past the timeout #when guarded #then denies without counting", () => {
+		writeGoals();
+		mkdirSync(sessionDir(), { recursive: true });
+		writeFileSync(
+			lockPath(),
+			JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString(), token: "live" }),
+		);
+
+		const output = applySpawnGuards(payload("spawn_agent", { message: "scan" }), { lockTimeoutMs: 100 });
+
+		expect(deny(output).permissionDecision).toBe("deny");
+		expect(deny(output).permissionDecisionReason).toContain("state lock");
+		expect(existsSync(join(sessionDir(), "spawn-count.json"))).toBe(false);
+		expect(existsSync(lockPath())).toBe(true);
+	});
+
+	it("#given a stale lock from a dead process #when guarded #then reclaims it and counts normally", () => {
+		writeGoals();
+		mkdirSync(sessionDir(), { recursive: true });
+		writeFileSync(
+			lockPath(),
+			JSON.stringify({ pid: 2147483646, createdAt: "2026-01-01T00:00:00.000Z", token: "gone" }),
+		);
+
+		expect(applySpawnGuards(payload("spawn_agent", { message: "scan" }), { lockTimeoutMs: 1000 })).toBe("");
+
+		const counter = JSON.parse(readFileSync(join(sessionDir(), "spawn-count.json"), "utf8"));
+		expect(counter.count).toBe(1);
+		expect(existsSync(lockPath())).toBe(false);
+	});
+});

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

@@ -0,0 +1,113 @@
+import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Readable, Writable } from "node:stream";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { applySpawnGuards, runSpawnGuardCli } from "../src/spawn-guard.js";
+import { LAZYCODEX_SPAWN_ROLES } from "../src/spawn-role-guard.js";
+
+let cwd: string;
+beforeEach(async () => {
+	cwd = await mkdtemp(join(tmpdir(), "spawn-role-matrix-"));
+	vi.stubEnv("OMO_AGENT_TOOLKIT_SURFACE", "lazycodex");
+	vi.stubEnv("PLUGIN_DATA", join(cwd, "data"));
+});
+afterEach(async () => {
+	vi.unstubAllEnvs();
+	await rm(cwd, { recursive: true, force: true });
+});
+
+function guard(tool_name: string, tool_input: Record<string, unknown>) {
+	return applySpawnGuards({
+		cwd,
+		hook_event_name: "PreToolUse",
+		model: "test",
+		permission_mode: "default",
+		session_id: "matrix",
+		tool_name,
+		tool_input,
+		tool_use_id: "call",
+		transcript_path: null,
+		turn_id: "turn",
+	});
+}
+
+describe("#given no active plan #when native spawns cross the role boundary", () => {
+	for (const tool of [
+		"spawn_agent",
+		"multi_agent_v1.spawn_agent",
+		"collaborationspawn_agent",
+		"collaboration.spawn_agent",
+	]) {
+		for (const fork of [false, true]) {
+			for (const registered of [false, true]) {
+				for (const named of [false, true]) {
+					it(`${tool}: named=${named}, full-history=${fork}, registered=${registered}`, () => {
+						const role = registered ? "lazycodex-worker-medium" : "worker";
+						const input = {
+							message: "TASK: implement",
+							...(named ? { agent_type: role } : {}),
+							...(tool.includes("collaboration")
+								? { fork_turns: fork ? "all" : "none", task_name: "work" }
+								: { fork_context: fork }),
+						};
+						const output = guard(tool, input);
+						if (named && registered) expect(output).toBe("");
+						else expect(JSON.parse(output).hookSpecificOutput.permissionDecision).toBe("deny");
+					});
+				}
+			}
+		}
+	}
+	it.each(["default", "deep", "explore", "", "unknown", 42, null])(
+		"rejects non-registry or malformed agent_type=%s",
+		(agent_type) => {
+			expect(JSON.parse(guard("spawn_agent", { agent_type })).hookSpecificOutput.permissionDecision).toBe("deny");
+		},
+	);
+	it("rejects omitted fork_turns and role rather than silently inheriting full history", () => {
+		expect(
+			JSON.parse(guard("collaboration.spawn_agent", { task_name: "work", message: "TASK: work" })).hookSpecificOutput
+				.permissionDecision,
+		).toBe("deny");
+	});
+	it("does not change Senpi role admission", () => {
+		vi.stubEnv("OMO_AGENT_TOOLKIT_SURFACE", "omo-senpi");
+		expect(guard("spawn_agent", { agent_type: "deep" })).toBe("");
+	});
+	it("pins explicit selectors to actual bundled TOML names", async () => {
+		const root = new URL("../../ultrawork/agents/", import.meta.url);
+		const names = await Promise.all(
+			(await readdir(root))
+				.filter((file) => file.endsWith(".toml"))
+				.map(async (file) => {
+					const content = await readFile(new URL(file, root), "utf8");
+					return /^name = "([^"]+)"/m.exec(content)?.[1];
+				}),
+		);
+		expect([...LAZYCODEX_SPAWN_ROLES].sort()).toEqual(names.sort());
+	});
+	it("still enforces admission breakers after role validation", async () => {
+		await mkdir(join(cwd, "data", "spawn-breaker"), { recursive: true });
+		await writeFile(join(cwd, "data", "spawn-breaker", "matrix.json"), JSON.stringify({ reason: "capacity" }));
+		expect(JSON.parse(guard("spawn_agent", { agent_type: "explorer" })).hookSpecificOutput.permissionDecision).toBe(
+			"deny",
+		);
+	});
+	it("fails loudly on malformed hook input", async () => {
+		let output = "";
+		await runSpawnGuardCli(
+			Readable.from(["{bad-json"]),
+			new Writable({
+				write(chunk, _encoding, callback) {
+					output += chunk.toString();
+					callback();
+				},
+			}),
+		);
+		expect(JSON.parse(output).hookSpecificOutput.permissionDecision).toBe("deny");
+	});
+	it("does not intercept other tools", () => {
+		expect(guard("read_file", {})).toBe("");
+	});
+});