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

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

@@ -1,24 +1,41 @@
-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";
+import { 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 +104,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 +228,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 +350,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 +408,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 +472,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 +521,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);
+	});
+});