lazycodex-ai 5.0.0-beta.62 → 5.0.0-beta.63

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

@@ -1,9 +1,10 @@
-import { randomBytes } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
 import { parsePreToolUsePayload } from "./codex-hook.js";
 import { isFinalRunCompletionCandidate } from "./goal-status.js";
 import { ulwLoopAttemptEvidenceDir, ulwLoopDir, ulwLoopStateLockPath } from "./paths.js";
+import { readUlwLoopPlanSync } from "./plan-io.js";
+import { atomicWriteJson, isNonEmptyFile, readAdmissionBreaker, readCount, readCounts } from "./spawn-budget-io.js";
 import { spawnRoleDenial } from "./spawn-role-guard.js";
 import { isStateLockTimeout, withStateLockSync } from "./state-lock.js";
 import { GATE_REVIEWER_AGENT_NAMES, REVIEWER_ROLES_BY_SURFACE, resolveToolkitSurface, reviewerRolesFor, } from "./surface.js";
@@ -43,7 +44,7 @@ export function applySpawnBudgetGuards(payload, options = {}) {
         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"));
+    const plan = readPlan(payload.cwd, payload.session_id);
     if (plan === null)
         return "";
     const lockOptions = options.lockTimeoutMs === undefined ? {} : { timeoutMs: options.lockTimeoutMs };
@@ -133,6 +134,7 @@ function peekFanOutBudget(stateDir) {
         return null;
     return `ulw-loop spawn fan-out cap reached (${count}/${limit}). Consolidate work into the agents already running, or raise OMO_SPAWN_FANOUT_LIMIT if this volume is intentional.`;
 }
+// Hook budget counters are exempt from plan/audit commits.
 // Per-session spawn counter; depth/lineage tracking is descoped — this is a
 // total-volume backstop against fan-out explosions, not a recursion tracker.
 function consumeFanOutBudget(stateDir) {
@@ -239,11 +241,6 @@ function activeSurfaceReviewerAlias(reviewer) {
     }
     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({
         hookSpecificOutput: {
@@ -254,18 +251,6 @@ 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)
@@ -280,48 +265,9 @@ function reviewSpawnLimit() {
     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;
-    }
-    catch (error) {
-        if (error instanceof Error)
-            return false;
-        throw error;
-    }
-}
-function readCount(counterPath) {
-    try {
-        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 0;
-        throw error;
-    }
-}
-function readCounts(counterPath) {
-    try {
-        const parsed = JSON.parse(readFileSync(counterPath, "utf8"));
-        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 {};
-        throw error;
-    }
-}
-function readPlan(goalsPath) {
+function readPlan(repoRoot, sessionId) {
     try {
-        return JSON.parse(readFileSync(goalsPath, "utf8"));
+        return readUlwLoopPlanSync(repoRoot, { sessionId });
     }
     catch (error) {
         if (error instanceof Error)

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

@@ -1,9 +1,19 @@
 import { UlwLoopError } from "./types.js";
 export declare const ULW_LOOP_LOCK_TIMEOUT_CODE = "ULW_LOOP_LOCK_TIMEOUT";
+export interface StateLockClock {
+    readonly now: () => number;
+    readonly schedule: (fn: () => void, ms: number) => {
+        unref(): void;
+        cancel(): void;
+    };
+}
 export interface StateLockOptions {
     readonly timeoutMs?: number;
     readonly staleMs?: number;
+    readonly leaseMs?: number;
+    readonly heartbeatMs?: number;
+    readonly clock?: StateLockClock;
 }
-export declare function withStateLock<T>(lockPath: string, fn: () => Promise<T>, options?: StateLockOptions): Promise<T>;
+export declare function withStateLock<T>(lockPath: string, fn: (token: string) => 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

@@ -1,89 +1,121 @@
 import { randomUUID } from "node:crypto";
-import { closeSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { closeSync, ftruncateSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeSync } from "node:fs";
 import { dirname } from "node:path";
-import { setTimeout as sleep } from "node:timers/promises";
 import { UlwLoopError } from "./types.js";
-// Cross-process exclusive lock for one ulw-loop state directory. Every CLI
-// invocation is its own process, so the in-process promise chain in plan-io
-// serializes nothing across them; this file-level lock is what makes the
-// read-modify-write of goals.json (and the counters next to it) atomic.
-//
-// Protocol: the lock is a file created with O_EXCL whose body records the
-// owner (pid + a per-acquisition token). A waiter reclaims it only when the
-// owner is provably gone (pid dead) or the body never became a record within
-// `staleMs` (a creator that died mid-write); a live owner is never reclaimed by
-// age alone, because overlapping two bodies is exactly the lost update this lock
-// exists to prevent. Waiters back off and fail closed at `timeoutMs`. Release
-// unlinks only a lock that still carries the releaser's own token.
+// O_EXCL establishes ownership. Async holders keep the fd open and refresh a
+// lease through that fd, never through the pathname: a reclaimed inode is invisible.
+// Sync/legacy holders are lease-less and only dead pids retire their records.
+// Expiry permits overlapping bodies; immutable revision publication fences them.
+// Reclaim's reread/unlink is not atomic. On Windows an open inode may not unlink:
+// treat that refusal as a live owner and fail closed. Release checks its token.
 export const ULW_LOOP_LOCK_TIMEOUT_CODE = "ULW_LOOP_LOCK_TIMEOUT";
 const DEFAULT_TIMEOUT_MS = 10_000;
 const DEFAULT_STALE_MS = 60_000;
-const MIN_DELAY_MS = 5;
-const MAX_DELAY_MS = 100;
+const DEFAULT_LEASE_MS = 30_000;
 const SLEEP_CELL = new Int32Array(new SharedArrayBuffer(4));
+const systemClock = {
+    now: Date.now,
+    schedule(fn, ms) {
+        const timer = setTimeout(fn, ms);
+        return {
+            unref: () => {
+                timer.unref();
+            },
+            cancel: () => clearTimeout(timer),
+        };
+    },
+};
 export async function withStateLock(lockPath, fn, options = {}) {
-    const token = await acquireAsync(lockPath, options);
+    const holder = await acquireAsync(lockPath, options);
+    const clock = options.clock ?? systemClock;
+    let timer;
+    let heartbeatError;
+    const beat = () => {
+        try {
+            holder.record.leaseUntil = clock.now() + (options.leaseMs ?? DEFAULT_LEASE_MS);
+            writeRecord(holder);
+            schedule();
+        }
+        catch (error) {
+            heartbeatError = error;
+        }
+    };
+    const schedule = () => {
+        if (options.heartbeatMs === 0)
+            return;
+        timer = clock.schedule(beat, options.heartbeatMs ?? (options.leaseMs ?? DEFAULT_LEASE_MS) / 3);
+        timer.unref();
+    };
+    schedule();
     try {
-        return await fn();
+        const result = await fn(holder.record.token);
+        if (heartbeatError !== undefined)
+            throw heartbeatError;
+        return result;
     }
     finally {
-        release(lockPath, token);
+        timer?.cancel();
+        closeSync(holder.fd);
+        release(lockPath, holder.record.token);
     }
 }
 export function withStateLockSync(lockPath, fn, options = {}) {
-    const token = acquireSync(lockPath, options);
+    const holder = acquireSync(lockPath, options);
     try {
         return fn();
     }
     finally {
-        release(lockPath, token);
+        closeSync(holder.fd);
+        release(lockPath, holder.record.token);
     }
 }
 export function isStateLockTimeout(error) {
     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;
+    const clock = options.clock ?? systemClock;
+    const deadline = clock.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
     mkdirSync(dirname(lockPath), { recursive: true });
     for (let attempt = 0;;) {
-        const outcome = attemptOnce(lockPath, staleMs);
+        const outcome = attemptOnce(lockPath, options, clock.now(), options.leaseMs ?? DEFAULT_LEASE_MS);
         if (outcome.kind === "acquired")
-            return outcome.token;
+            return outcome.holder;
         if (outcome.kind === "retry")
             continue;
-        if (Date.now() >= deadline)
-            throw lockTimeout(lockPath, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
-        await sleep(backoffMs(attempt));
+        if (clock.now() >= deadline)
+            throw lockTimeout(lockPath, options);
+        await new Promise((resolve) => clock.schedule(resolve, 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);
+        const outcome = attemptOnce(lockPath, options, Date.now());
         if (outcome.kind === "acquired")
-            return outcome.token;
+            return outcome.holder;
         if (outcome.kind === "retry")
             continue;
         if (Date.now() >= deadline)
-            throw lockTimeout(lockPath, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+            throw lockTimeout(lockPath, options);
         Atomics.wait(SLEEP_CELL, 0, 0, backoffMs(attempt));
         attempt += 1;
     }
 }
-// EINTR surfaces raw from macOS fs syscalls under some runtimes; it is a retry, never a verdict.
-function attemptOnce(lockPath, staleMs) {
+function attemptOnce(lockPath, options, now, leaseMs) {
     try {
-        const token = tryCreate(lockPath);
-        if (token !== null)
-            return { kind: "acquired", token };
-        const snapshot = readSnapshot(lockPath);
+        const holder = tryCreate(lockPath, now, leaseMs);
+        if (holder !== null)
+            return { kind: "acquired", holder };
+        const snapshot = readSnapshot(lockPath, now);
         if (snapshot === null)
             return { kind: "retry" };
-        if (isStale(snapshot, staleMs) && reclaim(lockPath, snapshot.raw))
+        const record = snapshot.record;
+        const stale = record === null
+            ? snapshot.ageMs > (options.staleMs ?? DEFAULT_STALE_MS)
+            : !isProcessAlive(record.pid) || (record.leaseUntil !== undefined && now > record.leaseUntil);
+        if (stale && reclaim(lockPath, snapshot.raw))
             return { kind: "retry" };
         return { kind: "wait" };
     }
@@ -93,7 +125,18 @@ function attemptOnce(lockPath, staleMs) {
         throw error;
     }
 }
-function tryCreate(lockPath) {
+function writeRecord(holder) {
+    const buf = Buffer.from(JSON.stringify(holder.record));
+    ftruncateSync(holder.fd, 0);
+    let offset = 0;
+    while (offset < buf.length) {
+        const written = writeSync(holder.fd, buf, offset, buf.length - offset, offset);
+        if (written === 0)
+            throw new Error("State lock write made no progress.");
+        offset += written;
+    }
+}
+function tryCreate(lockPath, now, leaseMs) {
     let fd;
     try {
         fd = openSync(lockPath, "wx");
@@ -103,30 +146,33 @@ function tryCreate(lockPath) {
             return null;
         throw error;
     }
-    const record = { pid: process.pid, createdAt: new Date().toISOString(), token: randomUUID() };
+    const record = {
+        pid: process.pid,
+        createdAt: new Date(now).toISOString(),
+        token: randomUUID(),
+        ...(leaseMs === undefined ? {} : { leaseUntil: now + leaseMs }),
+    };
+    const holder = { fd, record };
     try {
-        writeSync(fd, JSON.stringify(record));
+        writeRecord(holder);
     }
     catch (error) {
         closeSync(fd);
-        // A failed write (e.g. EINTR) must not leave a partial lock the owner never recorded;
-        // otherwise later readers see a young ownerless lock and only age can retire it.
         try {
             unlinkSync(lockPath);
         }
-        catch {
-            // another process already reclaimed the partial file; leave it alone
+        catch (cleanup) {
+            if (!hasCode(cleanup, "ENOENT"))
+                throw cleanup;
         }
         throw error;
     }
-    closeSync(fd);
-    return record.token;
+    return holder;
 }
-function readSnapshot(lockPath) {
+function readSnapshot(lockPath, now) {
     try {
         const raw = readFileSync(lockPath, "utf8");
-        const ageMs = Date.now() - statSync(lockPath).mtimeMs;
-        return { raw, record: parseRecord(raw), ageMs };
+        return { raw, record: parseRecord(raw), ageMs: now - statSync(lockPath).mtimeMs };
     }
     catch (error) {
         if (hasCode(error, "ENOENT"))
@@ -136,18 +182,21 @@ function readSnapshot(lockPath) {
 }
 function parseRecord(raw) {
     try {
-        const parsed = JSON.parse(raw);
-        if (typeof parsed !== "object" || parsed === null)
+        const record = JSON.parse(raw);
+        if (typeof record !== "object" || record === null)
+            return null;
+        if (!("pid" in record) || typeof record.pid !== "number" || !Number.isInteger(record.pid) || record.pid <= 0)
             return null;
-        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")
+        if (!("createdAt" in record) || typeof record.createdAt !== "string")
             return null;
-        if (typeof token !== "string" || token.length === 0)
+        if (!("token" in record) || typeof record.token !== "string" || record.token.length === 0)
             return null;
-        return { pid, createdAt, token };
+        return {
+            pid: record.pid,
+            createdAt: record.createdAt,
+            token: record.token,
+            ...("leaseUntil" in record && typeof record.leaseUntil === "number" ? { leaseUntil: record.leaseUntil } : {}),
+        };
     }
     catch (error) {
         if (error instanceof SyntaxError)
@@ -155,14 +204,6 @@ function parseRecord(raw) {
         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);
@@ -176,10 +217,8 @@ function isProcessAlive(pid) {
         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);
+    const current = readSnapshot(lockPath, Date.now());
     if (current === null)
         return true;
     if (current.raw !== expectedRaw)
@@ -188,16 +227,15 @@ function reclaim(lockPath, expectedRaw) {
         unlinkSync(lockPath);
     }
     catch (error) {
+        if (hasCode(error, "EPERM") || hasCode(error, "EACCES"))
+            return false;
         if (!hasCode(error, "ENOENT"))
             throw error;
     }
     return true;
 }
-// Only the acquisition that wrote this token may unlink: if the file now carries
-// another token, a waiter has legitimately taken over and its lock must stand.
 function release(lockPath, token) {
-    const current = readSnapshot(lockPath);
-    if (current === null || current.record?.token !== token)
+    if (readSnapshot(lockPath, Date.now())?.record?.token !== token)
         return;
     try {
         unlinkSync(lockPath);
@@ -208,19 +246,13 @@ function release(lockPath, token) {
     }
 }
 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 }),
-        },
-    });
+    return Math.min(100, 5 * 2 ** attempt) + Math.random() * 5;
+}
+function lockTimeout(lockPath, options) {
+    const holder = readSnapshot(lockPath, Date.now())?.record;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const owner = holder == null ? "another process" : `pid ${holder.pid}`;
+    return new UlwLoopError(`ulw-loop state lock ${lockPath} is held by ${owner} for more than ${timeoutMs}ms. The lock owner is still alive. If a JS eval kernel was interrupted while writing, wait for its lease to expire (${options.leaseMs ?? DEFAULT_LEASE_MS} ms) or restart the owning senpi process; never delete a lock owned by a live process.`, ULW_LOOP_LOCK_TIMEOUT_CODE, { details: { lockPath, timeoutMs, ...(holder == null ? {} : { holderPid: holder.pid }) } });
 }
 function hasCode(error, 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

@@ -1,6 +1,7 @@
+import type { UlwLoopToolkitSurface } from "./surface.js";
 import type { UlwLoopPlan } from "./types.js";
 /**
- * `status --json` is the one call every agent already makes between steps, so it is
+ * Status is the one call every agent already makes between steps, so it is
  * also the cheapest place to answer "what now?" without a second round trip.
  */
-export declare function statusNextActions(plan: UlwLoopPlan): readonly string[];
+export declare function statusNextActions(plan: UlwLoopPlan, surface?: UlwLoopToolkitSurface): readonly string[];

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

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

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

@@ -1,4 +1,5 @@
-import { appendLedger, appendLedgerEntries, findAcceptedSteeringLedgerEntry, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
+import { commit } from "./plan-commit.js";
+import { findAcceptedSteeringLedgerEntry, readUlwLoopPlan, withUlwLoopMutationLock } from "./plan-io.js";
 import { applySteeringMutation, validateUlwLoopSteeringProposal } from "./steering.js";
 import { buildSteeringPlanSnapshot, changedGoalIdsBetween } from "./steering-snapshot.js";
 import { iso } from "./types.js";
@@ -10,7 +11,7 @@ export async function steerUlwLoopBatch(repoRoot, proposals, scope) {
         const failed = prepared.results.find((item) => !item.accepted);
         if (failed !== undefined) {
             const entry = rejectedLedgerEntry(prepared.results);
-            await appendLedger(repoRoot, entry, scope);
+            await commit(repoRoot, scope, { plan, entries: [entry] });
             return rejected(plan, prepared.results, failed.rejectedReasons);
         }
         let next = plan;
@@ -19,10 +20,9 @@ export async function steerUlwLoopBatch(repoRoot, proposals, scope) {
                 next = item.prepared.next;
         const fresh = prepared.items.filter((item) => item.kind === "fresh");
         if (fresh.length > 0) {
-            await writePlan(repoRoot, next, scope);
             const entries = fresh.map((item) => ledgerEntry(item.prepared.proposal, item.prepared.audit, item.prepared.proposal.now?.toISOString() ?? iso()));
             const batchEntry = batchUpdateLedgerEntry(plan, next, iso());
-            await appendLedgerEntries(repoRoot, batchEntry === null ? entries : [...entries, batchEntry], scope);
+            await commit(repoRoot, scope, { plan: next, entries: batchEntry === null ? entries : [...entries, batchEntry] });
         }
         return { plan: next, accepted: true, results: prepared.results, rejectedReasons: [] };
     });

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

@@ -1,6 +1,7 @@
 // biome-ignore-all format: compact steering module must stay below the 240 pure-LOC budget
 import { isUlwLoopDone } from "./goal-status.js";
-import { appendLedger, findAcceptedSteeringLedgerEntry, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
+import { commit } from "./plan-commit.js";
+import { findAcceptedSteeringLedgerEntry, readUlwLoopPlan, withUlwLoopMutationLock } from "./plan-io.js";
 import { makeGoal, reviseCriterion, reviseWording, splitOrBlock } from "./steering-mutations.js";
 import { buildSteeringPlanSnapshot, changedGoalIdsBetween } from "./steering-snapshot.js";
 import { iso, ULW_LOOP_STEERING_MUTATION_KINDS, ULW_LOOP_SUCCESS_CRITERION_USER_MODELS } from "./types.js";
@@ -223,11 +224,10 @@ export async function steerUlwLoop(repoRoot, proposal, scope) {
         }
         const at = proposal.now?.toISOString() ?? iso();
         const batchEntry = accepted ? batchUpdateLedgerEntry(plan, next, at) : null;
-        if (accepted)
-            await writePlan(repoRoot, next, scope);
-        await appendLedger(repoRoot, ledgerEntry(proposal, finalAudit, at), scope);
+        const entries = [ledgerEntry(proposal, finalAudit, at)];
         if (batchEntry !== null)
-            await appendLedger(repoRoot, batchEntry, scope);
+            entries.push(batchEntry);
+        await commit(repoRoot, scope, { plan: next, entries });
         return { plan: next, accepted, audit: finalAudit, rejectedReasons: audit.invariant.rejectedReasons, deduped: false };
     });
 }

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

@@ -1,6 +1,8 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, resolve, sep } from "node:path";
+import { readLedgerAt } from "./ledger.js";
 import { normalizeUlwLoopSessionId, ulwLoopDir, ulwLoopStateLockPath } from "./paths.js";
+import { readUlwLoopPlanSync } from "./plan-io.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
@@ -27,7 +29,7 @@ export function runStopResumeHook(input) {
         return "";
     const scope = { sessionId: payload.session_id };
     const stateDir = ulwLoopDir(payload.cwd, scope);
-    const plan = readPlan(join(stateDir, "goals.json"));
+    const plan = readPlan(payload.cwd, payload.session_id);
     if (plan === null || plan.aggregateCompletion?.status === "complete")
         return "";
     const goal = resumableGoal(plan);
@@ -76,11 +78,10 @@ function consumeResumeBudgetLocked(lockPath, stateDir, goalId) {
         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.
+// Hook budget counters are exempt from plan/audit commits. Count reconciled
+// entries, not cache lines: a writer dying after link still made progress.
 function consumeResumeBudget(stateDir, goalId) {
-    const ledgerLineCount = countLedgerLines(join(stateDir, "ledger.jsonl"));
+    const ledgerLineCount = readLedgerAt(stateDir).length;
     const counterPath = resolve(stateDir, `auto-resume-${goalId}.json`);
     const stuckPath = resolve(stateDir, `auto-resume-${goalId}.stuck`);
     // goals.json is untrusted input: a crafted goal id (e.g. `../../x`) must
@@ -111,9 +112,9 @@ function renderResumeDirective(plan, goal, sessionId) {
         "If the loop is genuinely blocked on the user, checkpoint the goal as blocked with the reason instead.",
     ].join("\n");
 }
-function readPlan(goalsPath) {
+function readPlan(repoRoot, sessionId) {
     try {
-        return JSON.parse(readFileSync(goalsPath, "utf8"));
+        return readUlwLoopPlanSync(repoRoot, { sessionId });
     }
     catch (error) {
         if (error instanceof Error)
@@ -121,16 +122,6 @@ function readPlan(goalsPath) {
         throw error;
     }
 }
-function countLedgerLines(ledgerPath) {
-    try {
-        return readFileSync(ledgerPath, "utf8").split("\n").filter(Boolean).length;
-    }
-    catch (error) {
-        if (error instanceof Error)
-            return 0;
-        throw error;
-    }
-}
 function readCounter(counterPath) {
     try {
         if (!existsSync(counterPath))