oh-my-opencode 5.0.0-beta.5 → 5.0.0-beta.50

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

@@ -1,29 +1,86 @@
-import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, 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
 // 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;
-export function applySpawnGuards(payload) {
+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;
+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),
+];
+const REVIEW_AGENT_TYPE_SET = new Set(REVIEW_AGENT_TYPES);
+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 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 };
+    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);
+    const missingArtifact = missingGateArtifact(payload, plan);
+    if (missingArtifact !== null)
+        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);
-    const missingArtifact = missingGateArtifact(payload, plan);
-    if (missingArtifact !== null)
-        return deny(`spawn code-review + QA first; gate audits their artifacts: missing ${missingArtifact}`);
     return "";
 }
+export async function runSpawnAdmissionRecorderCli(stdin, stdout) {
+    const chunks = [];
+    for await (const chunk of stdin)
+        chunks.push(Buffer.from(chunk));
+    try {
+        const payload = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        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");
+        mkdirSync(markerDir, { recursive: true });
+        atomicWriteJson(join(markerDir, `${payload["session_id"]}.json`), {
+            reason: response,
+            at: new Date().toISOString(),
+        });
+    }
+    catch {
+        /* malformed hook input is ignored */
+    }
+    void stdout;
+}
 export async function runSpawnGuardCli(stdin, stdout) {
     try {
         const chunks = [];
@@ -41,17 +98,48 @@ export async function runSpawnGuardCli(stdin, stdout) {
             return;
     }
 }
+// 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) {
+    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.`;
+}
 // 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) {
     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, plan, stateDir) {
+    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, plan) {
     if (!isGateReviewerSpawn(payload.tool_input))
         return null;
@@ -61,32 +149,77 @@ function missingGateArtifact(payload, plan) {
     if (!goal.successCriteria.every((criterion) => criterion.status === "pass"))
         return null;
     const scope = { sessionId: payload.session_id };
+    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) {
+    const agentType = reviewAgentType(toolInput);
+    return agentType !== null && GATE_REVIEWER_AGENT_NAMES.has(agentType);
+}
+function reviewAgentType(toolInput) {
     if (typeof toolInput !== "object" || toolInput === null)
-        return false;
+        return null;
     const record = toolInput;
     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) {
+    const activeRoles = reviewerRolesFor(resolveToolkitSurface());
+    for (const roles of Object.values(REVIEWER_ROLES_BY_SURFACE)) {
+        if (reviewer === roles.codeReview)
+            return activeRoles.codeReview;
+        if (reviewer === roles.manualQa)
+            return activeRoles.manualQa;
+        if (reviewer === roles.gateReview)
+            return activeRoles.gateReview;
+    }
+    return reviewer;
+}
+function atomicWriteJson(targetPath, data) {
+    const tmp = join(dirname(targetPath), `.tmp-${randomBytes(6).toString("hex")}`);
+    writeFileSync(tmp, JSON.stringify(data));
+    renameSync(tmp, targetPath);
 }
 function deny(reason) {
     return `${JSON.stringify({
@@ -98,6 +231,18 @@ function deny(reason) {
         },
     })}\n`;
 }
+function readAdmissionBreaker(sessionId) {
+    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"));
+        return typeof value.reason === "string" ? value.reason : "capacity limit";
+    }
+    catch {
+        return null;
+    }
+}
 function fanOutLimit() {
     const raw = process.env["OMO_SPAWN_FANOUT_LIMIT"];
     if (raw === undefined)
@@ -105,6 +250,13 @@ function fanOutLimit() {
     const parsed = Number.parseInt(raw, 10);
     return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_FANOUT_LIMIT;
 }
+function reviewSpawnLimit() {
+    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 isNonEmptyFile(path) {
     try {
         return existsSync(path) && statSync(path).size > 0;
@@ -115,24 +267,32 @@ function isNonEmptyFile(path) {
         throw error;
     }
 }
-function hasOtherEvidenceFile(evidenceDir, excludedName) {
+function readCount(counterPath) {
     try {
-        return readdirSync(evidenceDir).some((name) => name !== excludedName && isNonEmptyFile(join(evidenceDir, name)));
+        const parsed = JSON.parse(readFileSync(counterPath, "utf8"));
+        return typeof parsed["count"] === "number" && parsed["count"] >= 0 ? parsed["count"] : 0;
     }
     catch (error) {
         if (error instanceof Error)
-            return false;
+            return 0;
         throw error;
     }
 }
-function readCount(counterPath) {
+function readCounts(counterPath) {
     try {
         const parsed = JSON.parse(readFileSync(counterPath, "utf8"));
-        return typeof parsed["count"] === "number" && parsed["count"] >= 0 ? parsed["count"] : 0;
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            return {};
+        const counts = {};
+        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 0;
+            return {};
         throw error;
     }
 }

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/status-next-actions.d.ts

@@ -0,0 +1,6 @@
+import type { UlwLoopPlan } from "./types.js";
+/**
+ * `status --json` 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 declare function statusNextActions(plan: UlwLoopPlan): readonly string[];

package/packages/omo-codex/plugin/components/ulw-loop/dist/status-next-actions.js

@@ -0,0 +1,33 @@
+import { hasAllCriteriaPass, isFinalRunCompletionCandidate } from "./goal-status.js";
+import { ULW_LOOP_CREATE_GOALS_COMMAND } from "./plan-missing-recovery.js";
+/**
+ * `status --json` 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) {
+    const actions = [];
+    const active = plan.goals.find((goal) => goal.id === plan.activeGoalId);
+    if (plan.goals.length === 0)
+        actions.push(`No goals yet: bootstrap with \`${ULW_LOOP_CREATE_GOALS_COMMAND}\`.`);
+    else if (active !== undefined)
+        actions.push(...activeGoalActions(plan, active));
+    for (const goal of plan.goals.filter((candidate) => candidate.status === "review_blocked"))
+        actions.push(`${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, active) {
+    const unresolved = active.successCriteria.filter((criterion) => criterion.status !== "pass");
+    if (unresolved.length > 0)
+        return [
+            `${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 [
+            `${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 [
+        `${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.`,
+    ];
+}

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

@@ -1,11 +1,12 @@
 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.
 const RESUME_CAP = 2;
-// Mirrors start-work-continuation's context-pressure bail-out: injecting a
+// Mirrors ulw-execute-continuation's context-pressure bail-out: injecting a
 // resume directive into an already-overflowing context makes things worse.
 const CONTEXT_PRESSURE_MARKERS = [
     "context compacted",
@@ -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.
@@ -132,7 +146,7 @@ function readCounter(counterPath) {
         throw error;
     }
 }
-// Local ~10-LOC approximation of start-work-continuation's boulder check (no
+// Local ~10-LOC approximation of ulw-execute-continuation's boulder check (no
 // cross-component import allowed): any continuable work for this session means
 // that hook owns the Stop event, so this one stays silent.
 function boulderContinuationWillFire(cwd, sessionId) {
@@ -167,7 +181,7 @@ function transcriptShowsContextPressure(transcriptPath) {
         throw error;
     }
 }
-// start-work-continuation owns an active Boulder plan until its final gate marks
+// ulw-execute-continuation owns an active Boulder plan until its final gate marks
 // the work complete, including the zero-remaining checklist state.
 function boulderPlanHasChecklist(cwd, entry) {
     const activePlan = entry["active_plan"];