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

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

@@ -2,6 +2,7 @@ export declare const ULW_LOOP_DIR = ".omo/ulw-loop";
 export declare const ULW_LOOP_BRIEF = "brief.md";
 export declare const ULW_LOOP_GOALS = "goals.json";
 export declare const ULW_LOOP_LEDGER = "ledger.jsonl";
+export declare const ULW_LOOP_STATE_LOCK = ".state.lock";
 export type UlwLoopStatus = "pending" | "in_progress" | "complete" | "failed" | "blocked" | "review_blocked" | "needs_user_decision";
 export type UlwLoopCodexGoalMode = "aggregate" | "per_story";
 export type UlwLoopSteeringStatus = "superseded" | "blocked";

package/packages/omo-codex/plugin/components/ulw-loop/dist/constants.js

@@ -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 const ULW_LOOP_STEERING_MUTATION_KINDS = [
     "add_subgoal",
     "split_subgoal",

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

@@ -12,6 +12,7 @@ export declare function ulwLoopLedgerRelativePath(scope?: UlwLoopScope): string;
 export declare function ulwLoopBriefPath(repoRoot: string, scope?: UlwLoopScope): string;
 export declare function ulwLoopGoalsPath(repoRoot: string, scope?: UlwLoopScope): string;
 export declare function ulwLoopLedgerPath(repoRoot: string, scope?: UlwLoopScope): string;
+export declare function ulwLoopStateLockPath(repoRoot: string, scope?: UlwLoopScope): string;
 export declare function repoRelative(absolutePath: string, repoRoot: string): string;
 export declare function ulwLoopAttemptEvidenceDir(goalId: string, attempt: number, scope?: UlwLoopScope): string;
 interface AttemptPathApi {

package/packages/omo-codex/plugin/components/ulw-loop/dist/paths.js

@@ -1,5 +1,5 @@
 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";
 const SESSION_ENV_KEYS = ["OMO_ULW_LOOP_SESSION_ID", "CODEX_SESSION_ID", "CODEX_THREAD_ID", "PI_SESSION_ID"];
 export function normalizeUlwLoopSessionId(sessionId) {
     const trimmed = sessionId?.trim();
@@ -48,6 +48,11 @@ export function ulwLoopGoalsPath(repoRoot, scope) {
 export function ulwLoopLedgerPath(repoRoot, scope) {
     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, scope) {
+    return join(ulwLoopDir(repoRoot, scope), ULW_LOOP_STATE_LOCK);
+}
 export function repoRelative(absolutePath, repoRoot) {
     const slashPrefix = `${repoRoot}/`;
     const backslashPrefix = `${repoRoot}\\`;
@@ -58,9 +63,13 @@ export function repoRelative(absolutePath, repoRoot) {
     return absolutePath.split("\\").join("/");
 }
 // 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, attempt, scope) {
-    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}`;
 }
 const PLATFORM_PATH_API = { relative, isAbsolute, sep };

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

@@ -3,6 +3,7 @@ import type { UlwLoopLedgerEntry, UlwLoopPlan } from "./types.js";
 export declare function withUlwLoopMutationLock<T>(repoRoot: string, fn: () => Promise<T>): Promise<T>;
 export declare function withUlwLoopMutationLock<T>(repoRoot: string, scope: UlwLoopScope | undefined, fn: () => Promise<T>): Promise<T>;
 export declare function readUlwLoopPlan(repoRoot: string, scope?: UlwLoopScope): Promise<UlwLoopPlan>;
+export declare function listUlwLoopSessionIds(repoRoot: string): readonly string[];
 export declare function writePlan(repoRoot: string, plan: UlwLoopPlan, scope?: UlwLoopScope): Promise<void>;
 export declare function appendLedger(repoRoot: string, entry: UlwLoopLedgerEntry, scope?: UlwLoopScope): Promise<void>;
 export declare function appendLedgerEntries(repoRoot: string, entries: readonly UlwLoopLedgerEntry[], scope?: UlwLoopScope): Promise<void>;

package/packages/omo-codex/plugin/components/ulw-loop/dist/plan-io.js

@@ -1,13 +1,19 @@
+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";
 import { aggregateCodexObjectiveForScope } from "./goal-status.js";
-import { repoRelative, ulwLoopDir, ulwLoopGoalsPath, ulwLoopLedgerPath, ulwLoopRelativeDir, } from "./paths.js";
+import { repoRelative, ulwLoopDir, ulwLoopGoalsPath, ulwLoopLedgerPath, ulwLoopRelativeDir, ulwLoopStateLockPath, } from "./paths.js";
 import { planMissingRecovery } from "./plan-missing-recovery.js";
+import { withStateLock } from "./state-lock.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();
+// 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();
 function hasCode(error, code) {
     return error instanceof Error && "code" in error && error.code === code;
 }
@@ -26,8 +32,12 @@ export async function withUlwLoopMutationLock(repoRoot, 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 = () => 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.
@@ -48,7 +58,7 @@ export async function readUlwLoopPlan(repoRoot, scope) {
     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", { cause: error, ...(recovery.details === undefined ? {} : { details: recovery.details }) });
     }
     const parsed = JSON.parse(raw);
@@ -58,6 +68,11 @@ export async function readUlwLoopPlan(repoRoot, scope) {
     const previousObjective = parsed.codexObjective;
     if ((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])];
@@ -73,9 +88,9 @@ export async function readUlwLoopPlan(repoRoot, scope) {
     }
     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) {
+// 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) {
     try {
         return readdirSync(ulwLoopDir(repoRoot), { withFileTypes: true })
             .filter((entry) => entry.isDirectory())

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

@@ -10,4 +10,5 @@ export interface PlanMissingRecovery {
  * session id"; the recovery text has to answer both without the caller guessing.
  */
 export declare function planMissingRecovery(existingSessionIds: readonly string[]): PlanMissingRecovery;
+export declare function sessionScopeRequiredMessage(flag: string, existingSessionIds: readonly string[]): string;
 export declare function sessionIdRequiredMessage(flag: string): string;

package/packages/omo-codex/plugin/components/ulw-loop/dist/plan-missing-recovery.js

@@ -10,6 +10,16 @@ export function planMissingRecovery(existingSessionIds) {
     lines.push(`Existing ulw-loop session ids under .omo/ulw-loop/: ${existingSessionIds.join(", ")}. Re-run with \`--session-id <id>\` to target one of them.`);
     return { message: lines.join("\n"), details: { existingSessionIds } };
 }
+export function sessionScopeRequiredMessage(flag, existingSessionIds) {
+    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) {
     return [
         `${flag} requires a non-empty value.`,

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

@@ -1,3 +1,6 @@
 import type { PreToolUsePayload } from "./codex-hook.js";
-export declare function applySpawnGuards(payload: PreToolUsePayload): string;
+export interface SpawnGuardOptions {
+    readonly lockTimeoutMs?: number;
+}
+export declare function applySpawnGuards(payload: PreToolUsePayload, options?: SpawnGuardOptions): string;
 export declare function runSpawnGuardCli(stdin: NodeJS.ReadableStream, stdout: NodeJS.WritableStream): Promise<void>;

package/packages/omo-codex/plugin/components/ulw-loop/dist/spawn-guard.js

@@ -1,9 +1,10 @@
 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 { 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, withStateLockSync } from "./state-lock.js";
 import { GATE_REVIEWER_AGENT_NAMES, REVIEWER_ROLES_BY_SURFACE, resolveToolkitSurface, reviewerRolesFor, } from "./surface.js";
 // spawn_agent = v1; collaborationspawn_agent = the delimiter-free flattened v2
 // hook token from codex-rs hook_names.rs; collaboration.spawn_agent = the
@@ -18,13 +19,25 @@ const REVIEW_AGENT_TYPES = [
     ...Object.values(REVIEWER_ROLES_BY_SURFACE).map((roles) => roles.manualQa),
 ];
 const REVIEW_AGENT_TYPE_SET = new Set(REVIEW_AGENT_TYPES);
-export function applySpawnGuards(payload) {
+export function applySpawnGuards(payload, options = {}) {
     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 };
+    const stateDir = ulwLoopDir(payload.cwd, scope);
     const plan = readPlan(join(stateDir, "goals.json"));
     if (plan === null)
         return "";
+    const lockOptions = 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, plan, stateDir) {
     const fanOutPeek = peekFanOutBudget(stateDir);
     if (fanOutPeek !== null)
         return deny(fanOutPeek);
@@ -88,18 +101,15 @@ function consumeReviewSpawnBudget(payload, plan, stateDir) {
     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, plan) {
     if (!isGateReviewerSpawn(payload.tool_input))
@@ -187,48 +197,6 @@ function activeSurfaceReviewerAlias(reviewer) {
     }
     return reviewer;
 }
-function withExclusiveLock(lockPath, fn) {
-    mkdirSync(dirname(lockPath), { recursive: true });
-    const maxAttempts = 10;
-    const baseDelayMs = 10;
-    for (let attempt = 0; attempt < maxAttempts; attempt++) {
-        let fd = 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.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, data) {
     const tmp = join(dirname(targetPath), `.tmp-${randomBytes(6).toString("hex")}`);
     writeFileSync(tmp, JSON.stringify(data));

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

@@ -0,0 +1,9 @@
+import { UlwLoopError } from "./types.js";
+export declare const ULW_LOOP_LOCK_TIMEOUT_CODE = "ULW_LOOP_LOCK_TIMEOUT";
+export interface StateLockOptions {
+    readonly timeoutMs?: number;
+    readonly staleMs?: number;
+}
+export declare function withStateLock<T>(lockPath: string, fn: () => Promise<T>, options?: StateLockOptions): Promise<T>;
+export declare function withStateLockSync<T>(lockPath: string, fn: () => T, options?: StateLockOptions): T;
+export declare function isStateLockTimeout(error: unknown): error is UlwLoopError;

package/packages/omo-codex/plugin/components/ulw-loop/dist/state-lock.js

@@ -0,0 +1,227 @@
+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";
+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(lockPath, fn, options = {}) {
+    const token = await acquireAsync(lockPath, options);
+    try {
+        return await fn();
+    }
+    finally {
+        release(lockPath, token);
+    }
+}
+export function withStateLockSync(lockPath, fn, options = {}) {
+    const token = acquireSync(lockPath, options);
+    try {
+        return fn();
+    }
+    finally {
+        release(lockPath, token);
+    }
+}
+export function isStateLockTimeout(error) {
+    return error instanceof UlwLoopError && error.code === ULW_LOOP_LOCK_TIMEOUT_CODE;
+}
+async function acquireAsync(lockPath, options) {
+    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, options) {
+    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, staleMs) {
+    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) {
+    let fd;
+    try {
+        fd = openSync(lockPath, "wx");
+    }
+    catch (error) {
+        if (hasCode(error, "EEXIST"))
+            return null;
+        throw error;
+    }
+    const record = { 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) {
+    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) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null)
+            return null;
+        const record = parsed;
+        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, staleMs) {
+    if (snapshot.record === null)
+        return snapshot.ageMs > staleMs;
+    return !isProcessAlive(snapshot.record.pid);
+}
+function isProcessAlive(pid) {
+    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, expectedRaw) {
+    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, token) {
+    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) {
+    const exponential = Math.min(MAX_DELAY_MS, MIN_DELAY_MS * 2 ** attempt);
+    return exponential + Math.random() * MIN_DELAY_MS;
+}
+function lockTimeout(lockPath, timeoutMs) {
+    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, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}

package/packages/omo-codex/plugin/components/ulw-loop/dist/stop-resume-hook.js

@@ -1,6 +1,7 @@
 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";
 // Turn-death recovery only: Codex emits Stop when a turn ends, so a run that
 // dies mid-turn (crash, kill, context blowup before any Stop) never reaches
 // this handler. Mid-turn stalls are out of scope by design.
@@ -24,14 +25,15 @@ export function runStopResumeHook(input) {
         return "";
     if (boulderContinuationWillFire(payload.cwd, payload.session_id))
         return "";
-    const stateDir = ulwLoopDir(payload.cwd, { sessionId: payload.session_id });
+    const scope = { sessionId: payload.session_id };
+    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))
+    if (!consumeResumeBudgetLocked(ulwLoopStateLockPath(payload.cwd, scope), stateDir, goal.id))
         return "";
     const output = {
         decision: "block",
@@ -62,6 +64,18 @@ function resumableGoal(plan) {
 function isResumableStatus(status) {
     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, stateDir, goalId) {
+    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.

package/packages/omo-codex/plugin/components/ulw-loop/hooks/hooks.json

@@ -7,7 +7,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook user-prompt-submit --with-ultrawork",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.0.0-beta.45) Checking Ulw-Loop Steering"
+						"statusMessage": "(OmO 5.0.0-beta.47) Checking Ulw-Loop Steering"
 					}
 				]
 			}
@@ -20,7 +20,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook pre-tool-use",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.45) Enforcing Unlimited Ulw-Loop Budget"
+						"statusMessage": "(OmO 5.0.0-beta.47) Enforcing Unlimited Ulw-Loop Budget"
 					}
 				]
 			},
@@ -31,7 +31,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook pre-tool-use-spawn",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.45) Guarding Ulw-Loop Spawns"
+						"statusMessage": "(OmO 5.0.0-beta.47) Guarding Ulw-Loop Spawns"
 					}
 				]
 			}
@@ -43,7 +43,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook stop",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.0.0-beta.45) Checking Ulw-Loop Resume"
+						"statusMessage": "(OmO 5.0.0-beta.47) Checking Ulw-Loop Resume"
 					}
 				]
 			}

package/packages/omo-codex/plugin/components/ulw-loop/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-ulw-loop",
-	"version": "5.0.0-beta.45",
+	"version": "5.0.0-beta.47",
 	"description": "Codex plugin: durable repo-native multi-goal orchestration with embedded success criteria and observable evidence audit.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",

package/packages/omo-codex/plugin/components/ulw-loop/skills/ulw-loop/SKILL.md

@@ -23,7 +23,8 @@ This skill is intentionally compact. The full workflow lives in `references/full
 - Use the ulw-loop CLI state under `.omo/ulw-loop`; do not hand-edit goal state.
 - Register goals up front, shaped by `references/define-goal.md` (`omo-agent-toolkit ulw-loop create-goals`, then `create_goal` from the printed handoff), and mirror every atomic step into the live `update_plan` checklist: one ultra-granular step per action, exactly one in_progress, transitions marked the instant they happen.
 - After any compaction or context loss, re-read brief + goals + ledger FIRST plus `omo-agent-toolkit ulw-loop status --json`, then resume; never re-plan from scratch.
-- If `omo-agent-toolkit ulw-loop create-goals` says the existing aggregate is already complete, start unrelated new work with a fresh `--session-id <new-id>` instead of steering or forcing the completed default state. Use `--force` only to intentionally overwrite completed evidence.
+- Every ulw-loop command needs the session scope: pass `--session-id <id>` (the printed handoff and resume directive carry it; `CODEX_THREAD_ID` in the environment also resolves it). The CLI refuses unscoped state (`ULW_LOOP_SESSION_SCOPE_REQUIRED`) instead of touching the shared `.omo/ulw-loop` root.
+- If `omo-agent-toolkit ulw-loop create-goals` says this session's aggregate is already complete, start unrelated new work with a fresh `--session-id <new-id>` (passed on every later call) instead of steering or forcing the completed state. Use `--force` only to intentionally overwrite completed evidence.
 - Every success criterion needs observable evidence from a real surface: a channel (terminal/TUI via the xterm.js web terminal, HTTP, browser, computer-use) or, for CLI- or data-shaped criteria, an auxiliary surface (CLI stdout, DB diff, parsed config dump).
 - Evidence is bound to the tree it was captured at (`git rev-parse --short "HEAD^{tree}"`); it goes stale only when tracked content changes — a rebase or amend that keeps the tree identical keeps it valid. When the tree differs, re-run at the current HEAD and re-record, never relabel or regenerate. Record only after cleanup receipts exist.
 - Delegate code edits, test writes, fixes, and QA execution to right-sized Codex subagents when the workflow requires it.