lazycodex-ai 5.0.0-beta.9 → 5.0.0

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

@@ -1,85 +1,255 @@
-import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { mkdirSync } from "node:fs";
 import { 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 { readUlwLoopPlanSync } from "./plan-io.js";
+import { atomicWriteJson, isNonEmptyFile, readAdmissionBreaker, readCount, readCounts } from "./spawn-budget-io.js";
+import { spawnRoleDenial } from "./spawn-role-guard.js";
+import { isStateLockTimeout, type StateLockOptions, withStateLockSync } from "./state-lock.js";
+import {
+	canonicalReviewerAgentName,
+	GATE_REVIEWER_AGENT_NAMES,
+	LEGACY_REVIEWER_AGENT_ALIASES,
+	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;
+const SPAWN_TOOL_TOKENS = new Set([
+	"spawn_agent",
+	"multi_agent_v1.spawn_agent",
+	"collaborationspawn_agent",
+	"collaboration.spawn_agent",
+]);
+export const DEFAULT_FANOUT_LIMIT = 24;
+const DEFAULT_REVIEW_SPAWN_LIMIT = 3;
+const GATE_MESSAGE_PATTERN =
+	/lazycodex-gate-reviewer|omo-native-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),
+	...Object.keys(LEGACY_REVIEWER_AGENT_ALIASES),
+] 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 "";
+	if (resolveToolkitSurface() === "lazycodex") {
+		const reason = spawnRoleDenial(payload.tool_input);
+		if (reason !== null) return deny(reason);
+	}
+	return applySpawnBudgetGuards(payload, options);
+}
+
+export function applySpawnBudgetGuards(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 plan = readPlan(join(stateDir, "goals.json"));
+	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(payload.cwd, payload.session_id);
 	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[] = [];
 		for await (const chunk of stdin) chunks.push(Buffer.from(chunk));
 		const payload = parsePreToolUsePayload(Buffer.concat(chunks).toString("utf8"));
-		if (payload === null) return;
+		if (payload === null) {
+			stdout.write(deny("LazyCodex spawn guard received an invalid hook payload; role routing was not verified."));
+			return;
+		}
 		const output = applySpawnGuards(payload);
 		if (output.length > 0) stdout.write(output);
 	} catch (error) {
-		if (error instanceof Error) return;
+		stdout.write(deny(`LazyCodex spawn guard failed: ${error instanceof Error ? error.message : String(error)}`));
 	}
 }
 
+// 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.`;
+}
+
+// Hook budget counters are exempt from plan/audit commits.
 // 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 canonical = canonicalReviewerAgentName(reviewer);
+	const activeRoles = reviewerRolesFor(resolveToolkitSurface());
+	for (const roles of Object.values(REVIEWER_ROLES_BY_SURFACE)) {
+		if (canonical === roles.codeReview) return activeRoles.codeReview;
+		if (canonical === roles.manualQa) return activeRoles.manualQa;
+		if (canonical === roles.gateReview) return activeRoles.gateReview;
+	}
+	return canonical;
 }
 
 function deny(reason: string): string {
@@ -100,37 +270,16 @@ function fanOutLimit(): number {
 	return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_FANOUT_LIMIT;
 }
 
-function isNonEmptyFile(path: string): boolean {
-	try {
-		return existsSync(path) && statSync(path).size > 0;
-	} catch (error) {
-		if (error instanceof Error) return false;
-		throw error;
-	}
-}
-
-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>;
-		return typeof parsed["count"] === "number" && parsed["count"] >= 0 ? parsed["count"] : 0;
-	} catch (error) {
-		if (error instanceof Error) return 0;
-		throw error;
-	}
+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 readPlan(goalsPath: string): UlwLoopPlan | null {
+function readPlan(repoRoot: string, sessionId: string): UlwLoopPlan | null {
 	try {
-		return JSON.parse(readFileSync(goalsPath, "utf8")) as UlwLoopPlan;
+		return readUlwLoopPlanSync(repoRoot, { sessionId });
 	} catch (error) {
 		if (error instanceof Error) return null;
 		throw error;

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

@@ -0,0 +1,22 @@
+// Explicit selectors, pinned by a test to the bundled role TOMLs. The generated
+// default is a non-fork fallback, not a selector: a user can opt out of owning it.
+export const LAZYCODEX_SPAWN_ROLES: ReadonlySet<string> = new Set([
+	"explorer",
+	"lazycodex-clone-fidelity-reviewer",
+	"lazycodex-code-reviewer",
+	"lazycodex-gate-reviewer",
+	"lazycodex-qa-executor",
+	"lazycodex-worker-high",
+	"lazycodex-worker-low",
+	"lazycodex-worker-medium",
+	"librarian",
+	"metis",
+	"momus",
+	"plan",
+]);
+
+export function spawnRoleDenial(input: unknown): string | null {
+	const role = typeof input === "object" && input !== null && "agent_type" in input ? input.agent_type : undefined;
+	if (typeof role === "string" && LAZYCODEX_SPAWN_ROLES.has(role)) return null;
+	return `LazyCodex requires an explicit registered agent_type: ${[...LAZYCODEX_SPAWN_ROLES].join(", ")}. Received ${JSON.stringify(role) ?? "no agent_type"}. Use the matching role and fork_turns: "none" (V2) or fork_context: false (V1), unless full history is deliberately required. The hook cannot see the tool schema; if agent_type is unavailable, stop and report incompatible role routing rather than spawning a generic agent. Describing a role in message does not select its TOML.`;
+}

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

@@ -0,0 +1,257 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, ftruncateSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { dirname } from "node:path";
+import { UlwLoopError } from "./types.js";
+
+// O_EXCL establishes ownership. Async holders keep the fd open and refresh a
+// lease through that fd, never through the pathname: a reclaimed inode is invisible.
+// Sync/legacy holders are lease-less and only dead pids retire their records.
+// Expiry permits overlapping bodies; immutable revision publication fences them.
+// Reclaim's reread/unlink is not atomic. On Windows an open inode may not unlink:
+// treat that refusal as a live owner and fail closed. Release checks its token.
+export const ULW_LOOP_LOCK_TIMEOUT_CODE = "ULW_LOOP_LOCK_TIMEOUT";
+export interface StateLockClock {
+	readonly now: () => number;
+	readonly schedule: (fn: () => void, ms: number) => { unref(): void; cancel(): void };
+}
+export interface StateLockOptions {
+	readonly timeoutMs?: number;
+	readonly staleMs?: number;
+	readonly leaseMs?: number;
+	readonly heartbeatMs?: number;
+	readonly clock?: StateLockClock;
+}
+interface LockRecord {
+	readonly pid: number;
+	readonly createdAt: string;
+	readonly token: string;
+	leaseUntil?: number;
+}
+interface Holder {
+	readonly fd: number;
+	readonly record: LockRecord;
+}
+interface LockSnapshot {
+	readonly raw: string;
+	readonly record: LockRecord | null;
+	readonly ageMs: number;
+}
+type AttemptOutcome = { readonly kind: "acquired"; readonly holder: Holder } | { readonly kind: "retry" | "wait" };
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_STALE_MS = 60_000;
+const DEFAULT_LEASE_MS = 30_000;
+const SLEEP_CELL = new Int32Array(new SharedArrayBuffer(4));
+const systemClock: StateLockClock = {
+	now: Date.now,
+	schedule(fn, ms) {
+		const timer = setTimeout(fn, ms);
+		return {
+			unref: () => {
+				timer.unref();
+			},
+			cancel: () => clearTimeout(timer),
+		};
+	},
+};
+
+export async function withStateLock<T>(
+	lockPath: string,
+	fn: (token: string) => Promise<T>,
+	options: StateLockOptions = {},
+): Promise<T> {
+	const holder = await acquireAsync(lockPath, options);
+	const clock = options.clock ?? systemClock;
+	let timer: ReturnType<StateLockClock["schedule"]> | undefined;
+	let heartbeatError: unknown;
+	const beat = () => {
+		try {
+			holder.record.leaseUntil = clock.now() + (options.leaseMs ?? DEFAULT_LEASE_MS);
+			writeRecord(holder);
+			schedule();
+		} catch (error) {
+			heartbeatError = error;
+		}
+	};
+	const schedule = () => {
+		if (options.heartbeatMs === 0) return;
+		timer = clock.schedule(beat, options.heartbeatMs ?? (options.leaseMs ?? DEFAULT_LEASE_MS) / 3);
+		timer.unref();
+	};
+	schedule();
+	try {
+		const result = await fn(holder.record.token);
+		if (heartbeatError !== undefined) throw heartbeatError;
+		return result;
+	} finally {
+		timer?.cancel();
+		closeSync(holder.fd);
+		release(lockPath, holder.record.token);
+	}
+}
+export function withStateLockSync<T>(lockPath: string, fn: () => T, options: StateLockOptions = {}): T {
+	const holder = acquireSync(lockPath, options);
+	try {
+		return fn();
+	} finally {
+		closeSync(holder.fd);
+		release(lockPath, holder.record.token);
+	}
+}
+export function isStateLockTimeout(error: unknown): error is UlwLoopError {
+	return error instanceof UlwLoopError && error.code === ULW_LOOP_LOCK_TIMEOUT_CODE;
+}
+async function acquireAsync(lockPath: string, options: StateLockOptions): Promise<Holder> {
+	const clock = options.clock ?? systemClock;
+	const deadline = clock.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+	mkdirSync(dirname(lockPath), { recursive: true });
+	for (let attempt = 0; ; ) {
+		const outcome = attemptOnce(lockPath, options, clock.now(), options.leaseMs ?? DEFAULT_LEASE_MS);
+		if (outcome.kind === "acquired") return outcome.holder;
+		if (outcome.kind === "retry") continue;
+		if (clock.now() >= deadline) throw lockTimeout(lockPath, options);
+		await new Promise<void>((resolve) => clock.schedule(resolve, backoffMs(attempt)));
+		attempt += 1;
+	}
+}
+function acquireSync(lockPath: string, options: StateLockOptions): Holder {
+	const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+	mkdirSync(dirname(lockPath), { recursive: true });
+	for (let attempt = 0; ; ) {
+		const outcome = attemptOnce(lockPath, options, Date.now());
+		if (outcome.kind === "acquired") return outcome.holder;
+		if (outcome.kind === "retry") continue;
+		if (Date.now() >= deadline) throw lockTimeout(lockPath, options);
+		Atomics.wait(SLEEP_CELL, 0, 0, backoffMs(attempt));
+		attempt += 1;
+	}
+}
+function attemptOnce(lockPath: string, options: StateLockOptions, now: number, leaseMs?: number): AttemptOutcome {
+	try {
+		const holder = tryCreate(lockPath, now, leaseMs);
+		if (holder !== null) return { kind: "acquired", holder };
+		const snapshot = readSnapshot(lockPath, now);
+		if (snapshot === null) return { kind: "retry" };
+		const record = snapshot.record;
+		const stale =
+			record === null
+				? snapshot.ageMs > (options.staleMs ?? DEFAULT_STALE_MS)
+				: !isProcessAlive(record.pid) || (record.leaseUntil !== undefined && now > record.leaseUntil);
+		if (stale && reclaim(lockPath, snapshot.raw)) return { kind: "retry" };
+		return { kind: "wait" };
+	} catch (error) {
+		if (hasCode(error, "EINTR")) return { kind: "wait" };
+		throw error;
+	}
+}
+function writeRecord(holder: Holder): void {
+	const buf = Buffer.from(JSON.stringify(holder.record));
+	ftruncateSync(holder.fd, 0);
+	let offset = 0;
+	while (offset < buf.length) {
+		const written = writeSync(holder.fd, buf, offset, buf.length - offset, offset);
+		if (written === 0) throw new Error("State lock write made no progress.");
+		offset += written;
+	}
+}
+function tryCreate(lockPath: string, now: number, leaseMs?: number): Holder | null {
+	let fd: number;
+	try {
+		fd = openSync(lockPath, "wx");
+	} catch (error) {
+		if (hasCode(error, "EEXIST")) return null;
+		throw error;
+	}
+	const record: LockRecord = {
+		pid: process.pid,
+		createdAt: new Date(now).toISOString(),
+		token: randomUUID(),
+		...(leaseMs === undefined ? {} : { leaseUntil: now + leaseMs }),
+	};
+	const holder = { fd, record };
+	try {
+		writeRecord(holder);
+	} catch (error) {
+		closeSync(fd);
+		try {
+			unlinkSync(lockPath);
+		} catch (cleanup) {
+			if (!hasCode(cleanup, "ENOENT")) throw cleanup;
+		}
+		throw error;
+	}
+	return holder;
+}
+function readSnapshot(lockPath: string, now: number): LockSnapshot | null {
+	try {
+		const raw = readFileSync(lockPath, "utf8");
+		return { raw, record: parseRecord(raw), ageMs: now - statSync(lockPath).mtimeMs };
+	} catch (error) {
+		if (hasCode(error, "ENOENT")) return null;
+		throw error;
+	}
+}
+function parseRecord(raw: string): LockRecord | null {
+	try {
+		const record: unknown = JSON.parse(raw);
+		if (typeof record !== "object" || record === null) return null;
+		if (!("pid" in record) || typeof record.pid !== "number" || !Number.isInteger(record.pid) || record.pid <= 0)
+			return null;
+		if (!("createdAt" in record) || typeof record.createdAt !== "string") return null;
+		if (!("token" in record) || typeof record.token !== "string" || record.token.length === 0) return null;
+		return {
+			pid: record.pid,
+			createdAt: record.createdAt,
+			token: record.token,
+			...("leaseUntil" in record && typeof record.leaseUntil === "number" ? { leaseUntil: record.leaseUntil } : {}),
+		};
+	} catch (error) {
+		if (error instanceof SyntaxError) return null;
+		throw error;
+	}
+}
+function isProcessAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		if (hasCode(error, "ESRCH")) return false;
+		if (hasCode(error, "EPERM")) return true;
+		throw error;
+	}
+}
+function reclaim(lockPath: string, expectedRaw: string): boolean {
+	const current = readSnapshot(lockPath, Date.now());
+	if (current === null) return true;
+	if (current.raw !== expectedRaw) return false;
+	try {
+		unlinkSync(lockPath);
+	} catch (error) {
+		if (hasCode(error, "EPERM") || hasCode(error, "EACCES")) return false;
+		if (!hasCode(error, "ENOENT")) throw error;
+	}
+	return true;
+}
+function release(lockPath: string, token: string): void {
+	if (readSnapshot(lockPath, Date.now())?.record?.token !== token) return;
+	try {
+		unlinkSync(lockPath);
+	} catch (error) {
+		if (!hasCode(error, "ENOENT")) throw error;
+	}
+}
+function backoffMs(attempt: number): number {
+	return Math.min(100, 5 * 2 ** attempt) + Math.random() * 5;
+}
+function lockTimeout(lockPath: string, options: StateLockOptions): UlwLoopError {
+	const holder = readSnapshot(lockPath, Date.now())?.record;
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const owner = holder == null ? "another process" : `pid ${holder.pid}`;
+	return new UlwLoopError(
+		`ulw-loop state lock ${lockPath} is held by ${owner} for more than ${timeoutMs}ms. The lock owner is still alive. If a JS eval kernel was interrupted while writing, wait for its lease to expire (${options.leaseMs ?? DEFAULT_LEASE_MS} ms) or restart the owning senpi process; never delete a lock owned by a live process.`,
+		ULW_LOOP_LOCK_TIMEOUT_CODE,
+		{ details: { lockPath, timeoutMs, ...(holder == null ? {} : { holderPid: holder.pid }) } },
+	);
+}
+function hasCode(error: unknown, code: string): boolean {
+	return error instanceof Error && "code" in error && error.code === code;
+}

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

@@ -0,0 +1,45 @@
+import { hasAllCriteriaPass, isFinalRunCompletionCandidate } from "./goal-status.js";
+import { createGoalsAction } from "./plan-missing-recovery.js";
+import type { UlwLoopToolkitSurface } from "./surface.js";
+import type { UlwLoopItem, UlwLoopPlan } from "./types.js";
+
+/**
+ * Status is the one call every agent already makes between steps, so it is
+ * also the cheapest place to answer "what now?" without a second round trip.
+ */
+export function statusNextActions(plan: UlwLoopPlan, surface: UlwLoopToolkitSurface = "lazycodex"): readonly string[] {
+	const actions: string[] = [];
+	const active = plan.goals.find((goal) => goal.id === plan.activeGoalId);
+	if (plan.goals.length === 0) actions.push(`No goals yet: bootstrap with \`${createGoalsAction(surface)}\`.`);
+	else if (active !== undefined) actions.push(...activeGoalActions(plan, active, surface));
+	for (const goal of plan.goals.filter((candidate) => candidate.status === "review_blocked"))
+		actions.push(
+			surface === "omo-senpi"
+				? `${goal.id} is review_blocked: capture the reviewer verdict with \`agentToolkit.recordReviewBlockers({ goalId: "${goal.id}", title: "<title>", objective: "<objective>", evidence: "<verdict>" })\`.`
+				: `${goal.id} is review_blocked: capture the reviewer verdict with \`omo-agent-toolkit ulw-loop record-review-blockers --goal-id ${goal.id} --title "<title>" --objective "<objective>" --evidence "<verdict>" --codex-goal-json '<get_goal json>'\`.`,
+		);
+	if (plan.evidenceLayoutVersion !== 2 || active === undefined)
+		actions.push("plan is evidence-layout v1; artifacts go under .omo/evidence/");
+	return actions;
+}
+
+function activeGoalActions(plan: UlwLoopPlan, active: UlwLoopItem, surface: UlwLoopToolkitSurface): readonly string[] {
+	const unresolved = active.successCriteria.filter((criterion) => criterion.status !== "pass");
+	if (unresolved.length > 0)
+		return [
+			surface === "omo-senpi"
+				? `${active.id} has ${unresolved.length} unresolved criterion(s) (${unresolved.map((criterion) => criterion.id).join(", ")}): record proof with \`agentToolkit.recordEvidence({ goalId: "${active.id}", criterionId: "<id>", status: "pass", evidence: "<observable proof>" })\`.`
+				: `${active.id} has ${unresolved.length} unresolved criterion(s) (${unresolved.map((criterion) => criterion.id).join(", ")}): record proof with \`omo-agent-toolkit ulw-loop record-evidence --goal-id ${active.id} --criterion-id <id> --status pass --evidence "<observable proof>"\`.`,
+		];
+	if (hasAllCriteriaPass(active) && isFinalRunCompletionCandidate(plan, active))
+		return [
+			surface === "omo-senpi"
+				? `${active.id} passes every criterion and is the final story: complete the driver goal, then call \`agentToolkit.checkpoint({ goalId: "${active.id}", printTemplate: true })\` to build the final quality gate. Use status().result.currentAttemptDir for all quality-gate artifacts.`
+				: `${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 [
+		surface === "omo-senpi"
+			? `${active.id} passes every criterion: close it with \`agentToolkit.checkpoint({ goalId: "${active.id}", status: "complete", evidence: "<proof>" })\`. Put quality-gate artifacts under status().result.currentAttemptDir.`
+			: `${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.`,
+	];
+}