lazycodex-ai 5.0.0-beta.45 → 5.0.0-beta.47

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

@@ -13,7 +13,7 @@ Use GPT-5.x style: outcome-first, evidence-bound, atomic decisions, no nested br
 Deliver every goal in `.omo/ulw-loop/goals.json` end-to-end.
 Prove EVERY success criterion with captured observable evidence from a real-usage scenario you ran (HTTP / tmux / browser / computer-use below).
 TESTS ALONE NEVER PROVE DONE. A green test suite is supporting evidence, not completion proof.
-Audit each pass, fail, block, steering change, and checkpoint in `.omo/ulw-loop/ledger.jsonl`.
+Audit each pass, fail, block, steering change, and checkpoint in `.omo/ulw-loop/<session-id>/ledger.jsonl`.
 
 ## Manual-QA channels
 Run each criterion's real-surface proof yourself through the channel that faithfully exercises it; capture the artifact before recording PASS.
@@ -110,13 +110,16 @@ If `ULW_LOOP_CLI` is empty, open the durable notepad first, record the missing C
 
 Run one form:
 ```sh
-omo-agent-toolkit ulw-loop create-goals --brief "<brief>" [--validation-batch-json <json-or-path>] --json
-omo-agent-toolkit ulw-loop create-goals --brief-file <path> [--validation-batch-json <json-or-path>] --json
-cat <brief> | omo-agent-toolkit ulw-loop create-goals --from-stdin [--validation-batch-json <json-or-path>] --json
+omo-agent-toolkit ulw-loop create-goals --session-id <id> --brief "<brief>" [--validation-batch-json <json-or-path>] --json
+omo-agent-toolkit ulw-loop create-goals --session-id <id> --brief-file <path> [--validation-batch-json <json-or-path>] --json
+cat <brief> | omo-agent-toolkit ulw-loop create-goals --session-id <id> --from-stdin [--validation-batch-json <json-or-path>] --json
 ```
-If the existing aggregate is already complete, do not steer or force the
-completed default state for unrelated new work. Start a fresh run with
-`omo-agent-toolkit ulw-loop create-goals --session-id <new-id> ...`; use `--force`
+Every state subcommand runs against exactly one session scope: pass `--session-id <id>` on every call (the printed handoff and the Stop hook resume directive carry this session's id; `PI_SESSION_ID`, `CODEX_THREAD_ID`, `CODEX_SESSION_ID`, or `OMO_ULW_LOOP_SESSION_ID` in the environment also resolve it). The CLI refuses with `ULW_LOOP_SESSION_SCOPE_REQUIRED` when neither is present instead of touching the shared `.omo/ulw-loop` root, because eval kernels, subprocesses, and hooks do not inherit the session env and every session in the directory would otherwise read and overwrite the same plan. Mutations are serialized across processes by `.omo/ulw-loop/<id>/.state.lock`, so parallel `record-evidence` calls from several workers are safe; `ULW_LOOP_LOCK_TIMEOUT` means another live process held the state for more than 10s — retry, never delete the lock while that process is alive.
+If this session's aggregate is already complete, do not steer or force the
+completed state for unrelated new work. Start a fresh run with
+`omo-agent-toolkit ulw-loop create-goals --session-id <new-id> ...` and keep passing
+that id on every later call; the Stop hook auto-resume follows only the
+Codex session's own id, so a run under a custom id is resumed by hand. Use `--force`
 only when deliberately overwriting completed evidence.
 Write state through the CLI path. Do not hand-edit state files.
 

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

@@ -12,7 +12,8 @@ import {
 	steer,
 } from "./cli-subcommands.js";
 import { resolveUlwLoopSessionIdFromEnv, type UlwLoopScope } from "./paths.js";
-import { sessionIdRequiredMessage } from "./plan-missing-recovery.js";
+import { listUlwLoopSessionIds } from "./plan-io.js";
+import { sessionIdRequiredMessage, sessionScopeRequiredMessage } from "./plan-missing-recovery.js";
 import { UlwLoopError } from "./types.js";
 
 export const ULW_LOOP_SUBCOMMANDS = [
@@ -41,7 +42,6 @@ export async function ulwLoopCommand(argv: readonly string[]): Promise<number> {
 	const repoRoot = process.cwd();
 	const json = hasFlag(rest, "--json");
 	try {
-		const scope = commandScope(rest);
 		if (!isUlwLoopSubcommand(command)) {
 			if (json) {
 				printJsonError(
@@ -58,10 +58,12 @@ export async function ulwLoopCommand(argv: readonly string[]): Promise<number> {
 			process.stdout.write(`${subcommandHelp(command)}\n`);
 			return 0;
 		}
+		if (command === "help") {
+			process.stdout.write(`${ULW_LOOP_HELP}\n`);
+			return 0;
+		}
+		const scope = commandScope(repoRoot, rest);
 		switch (command) {
-			case "help":
-				process.stdout.write(`${ULW_LOOP_HELP}\n`);
-				return 0;
 			case "create-goals":
 				return await createGoals(repoRoot, rest, json, scope);
 			case "status":
@@ -105,7 +107,10 @@ function sessionIdFlagPresent(argv: readonly string[]): boolean {
 	return hasFlag(argv, SESSION_ID_FLAG) || argv.some((arg) => arg.startsWith(`${SESSION_ID_FLAG}=`));
 }
 
-function commandScope(argv: readonly string[]): UlwLoopScope | undefined {
+// Every state subcommand runs against exactly one session directory. Without a flag or
+// a session env there is no owner to resolve, so the command refuses instead of
+// falling back to the repo-global root that every session in the cwd would share.
+function commandScope(repoRoot: string, argv: readonly string[]): UlwLoopScope {
 	if (sessionIdFlagPresent(argv)) {
 		const sessionId = readValue(argv, SESSION_ID_FLAG)?.trim();
 		if (!sessionId) {
@@ -116,5 +121,11 @@ function commandScope(argv: readonly string[]): UlwLoopScope | undefined {
 		return { sessionId };
 	}
 	const sessionId = resolveUlwLoopSessionIdFromEnv();
-	return sessionId === null ? undefined : { sessionId };
+	if (sessionId !== null) return { sessionId };
+	const existingSessionIds = listUlwLoopSessionIds(repoRoot);
+	throw new UlwLoopError(
+		sessionScopeRequiredMessage(SESSION_ID_FLAG, existingSessionIds),
+		"ULW_LOOP_SESSION_SCOPE_REQUIRED",
+		{ details: { flag: SESSION_ID_FLAG, existingSessionIds } },
+	);
 }

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

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

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

@@ -2,6 +2,7 @@ export const ULW_LOOP_DIR = ".omo/ulw-loop";
 export const ULW_LOOP_BRIEF = "brief.md";
 export const ULW_LOOP_GOALS = "goals.json";
 export const ULW_LOOP_LEDGER = "ledger.jsonl";
+export const ULW_LOOP_STATE_LOCK = ".state.lock";
 
 export type UlwLoopStatus =
 	| "pending"

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

@@ -1,5 +1,12 @@
 import { isAbsolute, join, relative, sep } from "node:path";
-import { ULW_LOOP_BRIEF, ULW_LOOP_DIR, ULW_LOOP_GOALS, ULW_LOOP_LEDGER } from "./types.js";
+import {
+	ULW_LOOP_BRIEF,
+	ULW_LOOP_DIR,
+	ULW_LOOP_GOALS,
+	ULW_LOOP_LEDGER,
+	ULW_LOOP_STATE_LOCK,
+	UlwLoopError,
+} from "./types.js";
 
 export interface UlwLoopScope {
 	readonly sessionId?: string | null;
@@ -63,6 +70,12 @@ export function ulwLoopLedgerPath(repoRoot: string, scope?: UlwLoopScope): strin
 	return join(ulwLoopDir(repoRoot, scope), ULW_LOOP_LEDGER);
 }
 
+// One lock per state directory covers goals.json, ledger.jsonl, and the hook
+// counters beside them; the CLI mutations and the Codex hooks all take it.
+export function ulwLoopStateLockPath(repoRoot: string, scope?: UlwLoopScope): string {
+	return join(ulwLoopDir(repoRoot, scope), ULW_LOOP_STATE_LOCK);
+}
+
 export function repoRelative(absolutePath: string, repoRoot: string): string {
 	const slashPrefix = `${repoRoot}/`;
 	const backslashPrefix = `${repoRoot}\\`;
@@ -73,9 +86,17 @@ export function repoRelative(absolutePath: string, repoRoot: string): string {
 }
 
 // Both the status --json emitter and the checkpoint enforcement resolve the attempt dir through
-// this function; a second resolution path would let the gate reject its own advertised directory.
+// this function from the scope alone; a second resolution path (env, a literal placeholder)
+// would let the gate reject its own advertised directory.
 export function ulwLoopAttemptEvidenceDir(goalId: string, attempt: number, scope?: UlwLoopScope): string {
-	const sessionId = normalizeUlwLoopSessionId(scope?.sessionId) ?? resolveUlwLoopSessionIdFromEnv() ?? "session";
+	const sessionId = normalizeUlwLoopSessionId(scope?.sessionId);
+	if (sessionId === null) {
+		throw new UlwLoopError(
+			`Evidence for ${goalId} attempt ${attempt} needs a session scope; pass --session-id <id> so the attempt directory lives under .omo/evidence/ulw/<id>/.`,
+			"ULW_LOOP_SESSION_SCOPE_REQUIRED",
+			{ details: { goalId, attempt } },
+		);
+	}
 	return `.omo/evidence/ulw/${sessionId}/${goalId}/a${attempt}`;
 }
 

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

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import { createReadStream, readdirSync } from "node:fs";
 import { appendFile, mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { createInterface } from "node:readline";
@@ -10,14 +11,20 @@ import {
 	ulwLoopGoalsPath,
 	ulwLoopLedgerPath,
 	ulwLoopRelativeDir,
+	ulwLoopStateLockPath,
 } from "./paths.js";
 import { planMissingRecovery } from "./plan-missing-recovery.js";
+import { withStateLock } from "./state-lock.js";
 import type { UlwLoopLedgerEntry, UlwLoopPlan } from "./types.js";
 import { iso, ULW_LOOP_DIR, ULW_LOOP_GOALS, ULW_LOOP_LEDGER, UlwLoopError } from "./types.js";
 
 const LEGACY_OBJECTIVE_PREFIX = `Complete all ulw-loop stories in ${ULW_LOOP_DIR}/${ULW_LOOP_GOALS}: `;
 const LEGACY_OBJECTIVE = `Complete all ulw-loop stories listed in ${ULW_LOOP_DIR}/${ULW_LOOP_GOALS}. Use ${ULW_LOOP_DIR}/${ULW_LOOP_LEDGER} as the durable audit trail.`;
 const locks = new Map<string, Promise<undefined>>();
+// Tracks which state dirs the CURRENT async continuation holds, so a read nested
+// inside a locked mutation can tell itself apart from an unlocked read elsewhere
+// in the same process.
+const heldLocks = new AsyncLocalStorage<ReadonlySet<string>>();
 
 function hasCode(error: unknown, code: string): boolean {
 	return error instanceof Error && "code" in error && error.code === code;
@@ -51,8 +58,13 @@ export async function withUlwLoopMutationLock<T>(
 	const fn = typeof scopeOrFn === "function" ? scopeOrFn : maybeFn;
 	if (fn === undefined) throw new UlwLoopError("Missing ulw-loop mutation body.", "ULW_LOOP_LOCK_BODY_MISSING");
 	const lockKey = `${repoRoot}\0${ulwLoopRelativeDir(scope)}`;
+	const lockPath = ulwLoopStateLockPath(repoRoot, scope);
+	// The promise chain orders callers inside this process; the file lock is what
+	// excludes every other process (each CLI invocation) touching the same state dir.
+	const locked = (): Promise<T> =>
+		withStateLock(lockPath, () => heldLocks.run(new Set([...(heldLocks.getStore() ?? []), lockKey]), fn));
 	const prior = locks.get(lockKey) ?? Promise.resolve(undefined);
-	const run = prior.then(fn, fn);
+	const run = prior.then(locked, locked);
 	// The stored gate resolves to undefined so the map never retains fn's result
 	// (plans/audits), and it removes itself once no newer waiter replaced it —
 	// otherwise a long-lived host leaks one entry per (repo, scope) forever.
@@ -74,7 +86,7 @@ export async function readUlwLoopPlan(repoRoot: string, scope?: UlwLoopScope): P
 		raw = await readFile(path, "utf8");
 	} catch (error) {
 		if (!hasCode(error, "ENOENT")) throw error;
-		const recovery = planMissingRecovery(readSessionDirs(repoRoot));
+		const recovery = planMissingRecovery(listUlwLoopSessionIds(repoRoot));
 		throw new UlwLoopError(
 			`No ulw-loop plan found at ${repoRelative(path, repoRoot)}.\n${recovery.message}`,
 			"ULW_LOOP_PLAN_MISSING",
@@ -90,6 +102,14 @@ export async function readUlwLoopPlan(repoRoot: string, scope?: UlwLoopScope): P
 		(parsed.codexGoalMode ?? "per_story") === "aggregate" &&
 		isLegacyEnumeratedAggregateObjective(previousObjective)
 	) {
+		if (!(heldLocks.getStore()?.has(`${repoRoot}\0${ulwLoopRelativeDir(scope)}`) ?? false)) {
+			// A read path (status/criteria) must not mutate state: mutating here runs
+			// unlocked and a second reader could write a partially-migrated plan.
+			throw new UlwLoopError(
+				`The ulw-loop plan at ${repoRelative(path, repoRoot)} carries a legacy enumerated aggregate objective that must be migrated before reads continue. Run any state-mutating ulw-loop command once (e.g. \`record-evidence\`, \`steer\`, \`checkpoint\`) to migrate it under the state lock, then retry.`,
+				"ULW_LOOP_MIGRATION_REQUIRED",
+			);
+		}
 		const now = iso();
 		parsed.codexObjective = aggregateCodexObjectiveForScope(scope);
 		parsed.codexObjectiveAliases = [...new Set([...(parsed.codexObjectiveAliases ?? []), previousObjective])];
@@ -110,9 +130,9 @@ export async function readUlwLoopPlan(repoRoot: string, scope?: UlwLoopScope): P
 	return parsed;
 }
 
-// Session dirs are the only recovery hint that matters when a plan is missing: the
-// caller is almost always scoped to a session whose sibling actually holds the plan.
-function readSessionDirs(repoRoot: string): readonly string[] {
+// Session dirs are the only recovery hint that matters when a plan or a scope is
+// missing: the caller is almost always meant to target one of these siblings.
+export function listUlwLoopSessionIds(repoRoot: string): readonly string[] {
 	try {
 		return readdirSync(ulwLoopDir(repoRoot), { withFileTypes: true })
 			.filter((entry) => entry.isDirectory())

package/packages/omo-codex/plugin/components/ulw-loop/src/plan-missing-recovery.ts

@@ -18,6 +18,17 @@ export function planMissingRecovery(existingSessionIds: readonly string[]): Plan
 	return { message: lines.join("\n"), details: { existingSessionIds } };
 }
 
+export function sessionScopeRequiredMessage(flag: string, existingSessionIds: readonly string[]): string {
+	const lines = [
+		"No ulw-loop session scope: neither the session env (OMO_ULW_LOOP_SESSION_ID / CODEX_SESSION_ID / CODEX_THREAD_ID / PI_SESSION_ID) nor the flag names this run, and the shared .omo/ulw-loop root is never used implicitly because every session in this directory would read and overwrite it.",
+		`Recovery: pass the scope explicitly: \`${flag} <id>\` (subprocess, eval, and hook contexts do not inherit the session env).`,
+	];
+	if (existingSessionIds.length > 0) {
+		lines.push(`Existing ulw-loop session ids under .omo/ulw-loop/: ${existingSessionIds.join(", ")}.`);
+	}
+	return lines.join("\n");
+}
+
 export function sessionIdRequiredMessage(flag: string): string {
 	return [
 		`${flag} requires a non-empty value.`,

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

@@ -1,21 +1,12 @@
 import { randomBytes } from "node:crypto";
-import {
-	existsSync,
-	mkdirSync,
-	openSync,
-	readdirSync,
-	readFileSync,
-	renameSync,
-	statSync,
-	unlinkSync,
-	writeFileSync,
-} from "node:fs";
+import { existsSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { dirname, 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 { isStateLockTimeout, type StateLockOptions, withStateLockSync } from "./state-lock.js";
 import {
 	GATE_REVIEWER_AGENT_NAMES,
 	REVIEWER_ROLES_BY_SURFACE,
@@ -38,11 +29,32 @@ const REVIEW_AGENT_TYPES = [
 ] 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 "";
-	const stateDir = ulwLoopDir(payload.cwd, { sessionId: payload.session_id });
+	const scope = { sessionId: payload.session_id } as const;
+	const stateDir = ulwLoopDir(payload.cwd, scope);
 	const plan = readPlan(join(stateDir, "goals.json"));
 	if (plan === null) return "";
+	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);
@@ -99,18 +111,15 @@ function consumeReviewSpawnBudget(payload: PreToolUsePayload, plan: UlwLoopPlan,
 		plan.goals.find((candidate) => isFinalRunCompletionCandidate(plan, candidate));
 	if (goal === undefined) return null;
 	const counterPath = join(stateDir, "review-spawn-counts.json");
-	const lockPath = `${counterPath}.lock`;
 	const limit = reviewSpawnLimit();
-	return withExclusiveLock(lockPath, () => {
-		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;
-	});
+	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 {
@@ -190,45 +199,6 @@ function activeSurfaceReviewerAlias(reviewer: string): string {
 	return reviewer;
 }
 
-function withExclusiveLock<T>(lockPath: string, fn: () => T): T {
-	mkdirSync(dirname(lockPath), { recursive: true });
-	const maxAttempts = 10;
-	const baseDelayMs = 10;
-	for (let attempt = 0; attempt < maxAttempts; attempt++) {
-		let fd: number | null = null;
-		try {
-			fd = openSync(lockPath, "wx");
-			writeFileSync(fd, process.pid.toString());
-			try {
-				return fn();
-			} finally {
-				try {
-					unlinkSync(lockPath);
-				} catch {
-					/* empty */
-				}
-			}
-		} catch (error) {
-			if (fd !== null) {
-				try {
-					unlinkSync(lockPath);
-				} catch {
-					/* empty */
-				}
-			}
-			if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
-				return fn();
-			}
-			const delayMs = baseDelayMs * 2 ** attempt + Math.random() * baseDelayMs;
-			const deadline = Date.now() + delayMs;
-			while (Date.now() < deadline) {
-				/* spin */
-			}
-		}
-	}
-	return fn();
-}
-
 function atomicWriteJson(targetPath: string, data: unknown): void {
 	const tmp = join(dirname(targetPath), `.tmp-${randomBytes(6).toString("hex")}`);
 	writeFileSync(tmp, JSON.stringify(data));

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

@@ -0,0 +1,239 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, 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.
+
+export const ULW_LOOP_LOCK_TIMEOUT_CODE = "ULW_LOOP_LOCK_TIMEOUT";
+
+export interface StateLockOptions {
+	readonly timeoutMs?: number;
+	readonly staleMs?: number;
+}
+
+interface LockRecord {
+	readonly pid: number;
+	readonly createdAt: string;
+	readonly token: string;
+}
+
+interface LockSnapshot {
+	readonly raw: string;
+	readonly record: LockRecord | null;
+	readonly ageMs: number;
+}
+
+type AttemptOutcome = { readonly kind: "acquired"; readonly token: string } | { 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 SLEEP_CELL = new Int32Array(new SharedArrayBuffer(4));
+
+export async function withStateLock<T>(
+	lockPath: string,
+	fn: () => Promise<T>,
+	options: StateLockOptions = {},
+): Promise<T> {
+	const token = await acquireAsync(lockPath, options);
+	try {
+		return await fn();
+	} finally {
+		release(lockPath, token);
+	}
+}
+
+export function withStateLockSync<T>(lockPath: string, fn: () => T, options: StateLockOptions = {}): T {
+	const token = acquireSync(lockPath, options);
+	try {
+		return fn();
+	} finally {
+		release(lockPath, 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;
+	mkdirSync(dirname(lockPath), { recursive: true });
+	for (let attempt = 0; ; ) {
+		const outcome = attemptOnce(lockPath, staleMs);
+		if (outcome.kind === "acquired") return outcome.token;
+		if (outcome.kind === "retry") continue;
+		if (Date.now() >= deadline) throw lockTimeout(lockPath, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+		await sleep(backoffMs(attempt));
+		attempt += 1;
+	}
+}
+
+function acquireSync(lockPath: string, options: StateLockOptions): string {
+	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;
+		if (outcome.kind === "retry") continue;
+		if (Date.now() >= deadline) throw lockTimeout(lockPath, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+		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 {
+	try {
+		const token = tryCreate(lockPath);
+		if (token !== null) return { kind: "acquired", token };
+		const snapshot = readSnapshot(lockPath);
+		if (snapshot === null) return { kind: "retry" };
+		if (isStale(snapshot, staleMs) && 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 {
+	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().toISOString(), token: randomUUID() };
+	try {
+		writeSync(fd, JSON.stringify(record));
+	} 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
+		}
+		throw error;
+	}
+	closeSync(fd);
+	return record.token;
+}
+
+function readSnapshot(lockPath: string): LockSnapshot | null {
+	try {
+		const raw = readFileSync(lockPath, "utf8");
+		const ageMs = Date.now() - statSync(lockPath).mtimeMs;
+		return { raw, record: parseRecord(raw), ageMs };
+	} 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 };
+	} 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);
+		return true;
+	} catch (error) {
+		if (hasCode(error, "ESRCH")) return false;
+		if (hasCode(error, "EPERM")) return true;
+		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);
+	if (current === null) return true;
+	if (current.raw !== expectedRaw) return false;
+	try {
+		unlinkSync(lockPath);
+	} catch (error) {
+		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;
+	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;
+}
+
+function lockTimeout(lockPath: string, timeoutMs: number): UlwLoopError {
+	const holder = readSnapshot(lockPath)?.record;
+	const owner = holder === undefined || 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_LOCK_TIMEOUT_CODE,
+		{
+			details: {
+				lockPath,
+				timeoutMs,
+				...(holder === undefined || 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/stop-resume-hook.ts

@@ -1,7 +1,8 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, resolve, sep } from "node:path";
 
-import { normalizeUlwLoopSessionId, ulwLoopDir } from "./paths.js";
+import { normalizeUlwLoopSessionId, ulwLoopDir, ulwLoopStateLockPath } from "./paths.js";
+import { isStateLockTimeout, withStateLockSync } from "./state-lock.js";
 import type { UlwLoopItem, UlwLoopPlan } from "./types.js";
 
 // Turn-death recovery only: Codex emits Stop when a turn ends, so a run that
@@ -34,12 +35,13 @@ export function runStopResumeHook(input: unknown): string {
 	if (payload === null || payload.stop_hook_active) return "";
 	if (transcriptShowsContextPressure(payload.transcript_path)) return "";
 	if (boulderContinuationWillFire(payload.cwd, payload.session_id)) return "";
-	const stateDir = ulwLoopDir(payload.cwd, { sessionId: payload.session_id });
+	const scope = { sessionId: payload.session_id } as const;
+	const stateDir = ulwLoopDir(payload.cwd, scope);
 	const plan = readPlan(join(stateDir, "goals.json"));
 	if (plan === null || plan.aggregateCompletion?.status === "complete") return "";
 	const goal = resumableGoal(plan);
 	if (goal === undefined) return "";
-	if (!consumeResumeBudget(stateDir, goal.id)) return "";
+	if (!consumeResumeBudgetLocked(ulwLoopStateLockPath(payload.cwd, scope), stateDir, goal.id)) return "";
 	const output: { decision: "block"; reason: string } = {
 		decision: "block",
 		reason: renderResumeDirective(plan, goal, payload.session_id),
@@ -68,6 +70,17 @@ function isResumableStatus(status: UlwLoopItem["status"]): boolean {
 	return status === "pending" || status === "in_progress";
 }
 
+// A resume is a budgeted side effect; when the session lock cannot be taken the
+// hook stays silent (fail closed) instead of charging the counter unlocked.
+function consumeResumeBudgetLocked(lockPath: string, stateDir: string, goalId: string): boolean {
+	try {
+		return withStateLockSync(lockPath, () => consumeResumeBudget(stateDir, goalId));
+	} catch (error) {
+		if (isStateLockTimeout(error)) return false;
+		throw error;
+	}
+}
+
 // Two-strike cap keyed on ledger movement: an unchanged ledger.jsonl line
 // count across resumes means the loop is not progressing. The stuck marker is
 // a separate file — a ledger append would change the count and self-reset.