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

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

@@ -0,0 +1,59 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export function readAdmissionBreaker(sessionId: string): string | null {
+	const dataDir = process.env["PLUGIN_DATA"];
+	if (typeof dataDir !== "string") return null;
+	try {
+		const value: unknown = JSON.parse(readFileSync(join(dataDir, "spawn-breaker", `${sessionId}.json`), "utf8"));
+		return typeof value === "object" && value !== null && "reason" in value && typeof value.reason === "string"
+			? value.reason
+			: "capacity limit";
+	} catch {
+		return null;
+	}
+}
+
+// These hook budget files are not plan/audit state and remain outside the log.
+export function atomicWriteJson(targetPath: string, data: unknown): void {
+	const tmp = join(dirname(targetPath), `.tmp-${randomBytes(6).toString("hex")}`);
+	writeFileSync(tmp, JSON.stringify(data));
+	renameSync(tmp, targetPath);
+}
+export function isNonEmptyFile(path: string): boolean {
+	try {
+		return existsSync(path) && statSync(path).size > 0;
+	} catch (error) {
+		if (error instanceof Error) return false;
+		throw error;
+	}
+}
+export function readCount(counterPath: string): number {
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(counterPath, "utf8"));
+		return typeof parsed === "object" &&
+			parsed !== null &&
+			"count" in parsed &&
+			typeof parsed.count === "number" &&
+			parsed.count >= 0
+			? parsed.count
+			: 0;
+	} catch (error) {
+		if (error instanceof Error) return 0;
+		throw error;
+	}
+}
+export function readCounts(counterPath: string): Record<string, number> {
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(counterPath, "utf8"));
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {};
+		const counts: Record<string, number> = {};
+		for (const [key, value] of Object.entries(parsed))
+			if (typeof value === "number" && value >= 0) counts[key] = value;
+		return counts;
+	} catch (error) {
+		if (error instanceof Error) return {};
+		throw error;
+	}
+}

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

@@ -1,11 +1,13 @@
-import { randomBytes } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+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, 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 {
 	GATE_REVIEWER_AGENT_NAMES,
@@ -18,7 +20,12 @@ 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 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-senpi-gate-reviewer|final gate review/i;
@@ -34,6 +41,15 @@ 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 "";
+	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 breaker = readAdmissionBreaker(payload.session_id);
 	if (breaker !== null)
@@ -42,7 +58,7 @@ export function applySpawnGuards(payload: PreToolUsePayload, options: SpawnGuard
 		);
 	const scope = { sessionId: payload.session_id } as const;
 	const stateDir = ulwLoopDir(payload.cwd, scope);
-	const plan = readPlan(join(stateDir, "goals.json"));
+	const plan = readPlan(payload.cwd, payload.session_id);
 	if (plan === null) return "";
 	const lockOptions: StateLockOptions =
 		options.lockTimeoutMs === undefined ? {} : { timeoutMs: options.lockTimeoutMs };
@@ -110,11 +126,14 @@ export async function runSpawnGuardCli(stdin: NodeJS.ReadableStream, stdout: Nod
 		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)}`));
 	}
 }
 
@@ -130,6 +149,7 @@ function peekFanOutBudget(stateDir: string): string | 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 {
@@ -227,12 +247,6 @@ function activeSurfaceReviewerAlias(reviewer: string): string {
 	return reviewer;
 }
 
-function atomicWriteJson(targetPath: string, data: unknown): void {
-	const tmp = join(dirname(targetPath), `.tmp-${randomBytes(6).toString("hex")}`);
-	writeFileSync(tmp, JSON.stringify(data));
-	renameSync(tmp, targetPath);
-}
-
 function deny(reason: string): string {
 	return `${JSON.stringify({
 		hookSpecificOutput: {
@@ -244,19 +258,6 @@ 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;
@@ -271,43 +272,9 @@ function reviewSpawnLimit(): number {
 	return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_REVIEW_SPAWN_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 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 readCounts(counterPath: string): Record<string, number> {
-	try {
-		const parsed: unknown = JSON.parse(readFileSync(counterPath, "utf8"));
-		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {};
-		const counts: Record<string, number> = {};
-		for (const [key, value] of Object.entries(parsed)) {
-			if (typeof value === "number" && value >= 0) counts[key] = value;
-		}
-		return counts;
-	} catch (error) {
-		if (error instanceof Error) return {};
-		throw error;
-	}
-}
-
-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

@@ -1,120 +1,159 @@
 import { randomUUID } from "node:crypto";
-import { closeSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { closeSync, ftruncateSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeSync } from "node:fs";
 import { dirname } from "node:path";
-import { setTimeout as sleep } from "node:timers/promises";
-
 import { UlwLoopError } from "./types.js";
 
-// Cross-process exclusive lock for one ulw-loop state directory. Every CLI
-// invocation is its own process, so the in-process promise chain in plan-io
-// serializes nothing across them; this file-level lock is what makes the
-// read-modify-write of goals.json (and the counters next to it) atomic.
-//
-// Protocol: the lock is a file created with O_EXCL whose body records the
-// owner (pid + a per-acquisition token). A waiter reclaims it only when the
-// owner is provably gone (pid dead) or the body never became a record within
-// `staleMs` (a creator that died mid-write); a live owner is never reclaimed by
-// age alone, because overlapping two bodies is exactly the lost update this lock
-// exists to prevent. Waiters back off and fail closed at `timeoutMs`. Release
-// unlinks only a lock that still carries the releaser's own token.
-
+// 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 token: string } | { readonly kind: "retry" | "wait" };
-
+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 MIN_DELAY_MS = 5;
-const MAX_DELAY_MS = 100;
+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: () => Promise<T>,
+	fn: (token: string) => Promise<T>,
 	options: StateLockOptions = {},
 ): Promise<T> {
-	const token = await acquireAsync(lockPath, options);
+	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 {
-		return await fn();
+		const result = await fn(holder.record.token);
+		if (heartbeatError !== undefined) throw heartbeatError;
+		return result;
 	} finally {
-		release(lockPath, token);
+		timer?.cancel();
+		closeSync(holder.fd);
+		release(lockPath, holder.record.token);
 	}
 }
-
 export function withStateLockSync<T>(lockPath: string, fn: () => T, options: StateLockOptions = {}): T {
-	const token = acquireSync(lockPath, options);
+	const holder = acquireSync(lockPath, options);
 	try {
 		return fn();
 	} finally {
-		release(lockPath, token);
+		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<string> {
-	const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
-	const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+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, staleMs);
-		if (outcome.kind === "acquired") return outcome.token;
+		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 (Date.now() >= deadline) throw lockTimeout(lockPath, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
-		await sleep(backoffMs(attempt));
+		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): string {
+function acquireSync(lockPath: string, options: StateLockOptions): Holder {
 	const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
-	const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
 	mkdirSync(dirname(lockPath), { recursive: true });
 	for (let attempt = 0; ; ) {
-		const outcome = attemptOnce(lockPath, staleMs);
-		if (outcome.kind === "acquired") return outcome.token;
+		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.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+		if (Date.now() >= deadline) throw lockTimeout(lockPath, options);
 		Atomics.wait(SLEEP_CELL, 0, 0, backoffMs(attempt));
 		attempt += 1;
 	}
 }
-
-// EINTR surfaces raw from macOS fs syscalls under some runtimes; it is a retry, never a verdict.
-function attemptOnce(lockPath: string, staleMs: number): AttemptOutcome {
+function attemptOnce(lockPath: string, options: StateLockOptions, now: number, leaseMs?: number): AttemptOutcome {
 	try {
-		const token = tryCreate(lockPath);
-		if (token !== null) return { kind: "acquired", token };
-		const snapshot = readSnapshot(lockPath);
+		const holder = tryCreate(lockPath, now, leaseMs);
+		if (holder !== null) return { kind: "acquired", holder };
+		const snapshot = readSnapshot(lockPath, now);
 		if (snapshot === null) return { kind: "retry" };
-		if (isStale(snapshot, staleMs) && reclaim(lockPath, snapshot.raw)) 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 tryCreate(lockPath: string): string | null {
+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");
@@ -122,60 +161,54 @@ function tryCreate(lockPath: string): string | null {
 		if (hasCode(error, "EEXIST")) return null;
 		throw error;
 	}
-	const record: LockRecord = { pid: process.pid, createdAt: new Date().toISOString(), token: randomUUID() };
+	const record: LockRecord = {
+		pid: process.pid,
+		createdAt: new Date(now).toISOString(),
+		token: randomUUID(),
+		...(leaseMs === undefined ? {} : { leaseUntil: now + leaseMs }),
+	};
+	const holder = { fd, record };
 	try {
-		writeSync(fd, JSON.stringify(record));
+		writeRecord(holder);
 	} catch (error) {
 		closeSync(fd);
-		// A failed write (e.g. EINTR) must not leave a partial lock the owner never recorded;
-		// otherwise later readers see a young ownerless lock and only age can retire it.
 		try {
 			unlinkSync(lockPath);
-		} catch {
-			// another process already reclaimed the partial file; leave it alone
+		} catch (cleanup) {
+			if (!hasCode(cleanup, "ENOENT")) throw cleanup;
 		}
 		throw error;
 	}
-	closeSync(fd);
-	return record.token;
+	return holder;
 }
-
-function readSnapshot(lockPath: string): LockSnapshot | null {
+function readSnapshot(lockPath: string, now: number): LockSnapshot | null {
 	try {
 		const raw = readFileSync(lockPath, "utf8");
-		const ageMs = Date.now() - statSync(lockPath).mtimeMs;
-		return { raw, record: parseRecord(raw), ageMs };
+		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 parsed: unknown = JSON.parse(raw);
-		if (typeof parsed !== "object" || parsed === null) return null;
-		const record = parsed as Record<string, unknown>;
-		const pid = record["pid"];
-		const createdAt = record["createdAt"];
-		const token = record["token"];
-		if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0 || typeof createdAt !== "string") return null;
-		if (typeof token !== "string" || token.length === 0) return null;
-		return { pid, createdAt, token };
+		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;
 	}
 }
-
-// A body that is not a record is a lock mid-write (or a foreign/legacy file); only
-// age retires it. A parsable record is stale only when its owner is dead: a live
-// owner running past staleMs is slow, not gone, and the waiter fails closed instead.
-function isStale(snapshot: LockSnapshot, staleMs: number): boolean {
-	if (snapshot.record === null) return snapshot.ageMs > staleMs;
-	return !isProcessAlive(snapshot.record.pid);
-}
-
 function isProcessAlive(pid: number): boolean {
 	try {
 		process.kill(pid, 0);
@@ -186,54 +219,39 @@ function isProcessAlive(pid: number): boolean {
 		throw error;
 	}
 }
-
-// Re-read right before unlinking so a lock that changed hands since the stale
-// verdict (a sibling waiter reclaimed and re-acquired it) is left alone.
 function reclaim(lockPath: string, expectedRaw: string): boolean {
-	const current = readSnapshot(lockPath);
+	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;
 }
-
-// Only the acquisition that wrote this token may unlink: if the file now carries
-// another token, a waiter has legitimately taken over and its lock must stand.
 function release(lockPath: string, token: string): void {
-	const current = readSnapshot(lockPath);
-	if (current === null || current.record?.token !== token) return;
+	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 {
-	const exponential = Math.min(MAX_DELAY_MS, MIN_DELAY_MS * 2 ** attempt);
-	return exponential + Math.random() * MIN_DELAY_MS;
+	return Math.min(100, 5 * 2 ** attempt) + Math.random() * 5;
 }
-
-function lockTimeout(lockPath: string, timeoutMs: number): UlwLoopError {
-	const holder = readSnapshot(lockPath)?.record;
-	const owner = holder === undefined || holder === null ? "another process" : `pid ${holder.pid}`;
+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; retry once that process finishes, or delete the lock file if that process is gone.`,
+		`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 === undefined || holder === null ? {} : { holderPid: holder.pid }),
-			},
-		},
+		{ 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;
 }