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

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

@@ -1,11 +1,12 @@
-import { randomBytes } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
 
 import type { PreToolUsePayload } from "./codex-hook.js";
 import { parsePreToolUsePayload } from "./codex-hook.js";
 import { isFinalRunCompletionCandidate } from "./goal-status.js";
 import { ulwLoopAttemptEvidenceDir, ulwLoopDir, ulwLoopStateLockPath } from "./paths.js";
+import { readUlwLoopPlanSync } from "./plan-io.js";
+import { atomicWriteJson, isNonEmptyFile, readAdmissionBreaker, readCount, readCounts } from "./spawn-budget-io.js";
 import { spawnRoleDenial } from "./spawn-role-guard.js";
 import { isStateLockTimeout, type StateLockOptions, withStateLockSync } from "./state-lock.js";
 import {
@@ -57,7 +58,7 @@ export function applySpawnBudgetGuards(payload: PreToolUsePayload, options: Spaw
 		);
 	const scope = { sessionId: payload.session_id } as const;
 	const stateDir = ulwLoopDir(payload.cwd, scope);
-	const plan = readPlan(join(stateDir, "goals.json"));
+	const plan = readPlan(payload.cwd, payload.session_id);
 	if (plan === null) return "";
 	const lockOptions: StateLockOptions =
 		options.lockTimeoutMs === undefined ? {} : { timeoutMs: options.lockTimeoutMs };
@@ -148,6 +149,7 @@ function peekFanOutBudget(stateDir: string): string | null {
 	return `ulw-loop spawn fan-out cap reached (${count}/${limit}). Consolidate work into the agents already running, or raise OMO_SPAWN_FANOUT_LIMIT if this volume is intentional.`;
 }
 
+// Hook budget counters are exempt from plan/audit commits.
 // Per-session spawn counter; depth/lineage tracking is descoped — this is a
 // total-volume backstop against fan-out explosions, not a recursion tracker.
 function consumeFanOutBudget(stateDir: string): string | null {
@@ -245,12 +247,6 @@ function activeSurfaceReviewerAlias(reviewer: string): string {
 	return reviewer;
 }
 
-function atomicWriteJson(targetPath: string, data: unknown): void {
-	const tmp = join(dirname(targetPath), `.tmp-${randomBytes(6).toString("hex")}`);
-	writeFileSync(tmp, JSON.stringify(data));
-	renameSync(tmp, targetPath);
-}
-
 function deny(reason: string): string {
 	return `${JSON.stringify({
 		hookSpecificOutput: {
@@ -262,19 +258,6 @@ function deny(reason: string): string {
 	})}\n`;
 }
 
-function readAdmissionBreaker(sessionId: string): string | null {
-	const dataDir = process.env["PLUGIN_DATA"];
-	if (typeof dataDir !== "string") return null;
-	try {
-		const value = JSON.parse(readFileSync(join(dataDir, "spawn-breaker", `${sessionId}.json`), "utf8")) as {
-			reason?: unknown;
-		};
-		return typeof value.reason === "string" ? value.reason : "capacity limit";
-	} catch {
-		return null;
-	}
-}
-
 function fanOutLimit(): number {
 	const raw = process.env["OMO_SPAWN_FANOUT_LIMIT"];
 	if (raw === undefined) return DEFAULT_FANOUT_LIMIT;
@@ -289,43 +272,9 @@ function reviewSpawnLimit(): number {
 	return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_REVIEW_SPAWN_LIMIT;
 }
 
-function isNonEmptyFile(path: string): boolean {
-	try {
-		return existsSync(path) && statSync(path).size > 0;
-	} catch (error) {
-		if (error instanceof Error) return false;
-		throw error;
-	}
-}
-
-function readCount(counterPath: string): number {
-	try {
-		const parsed = JSON.parse(readFileSync(counterPath, "utf8")) as Record<string, unknown>;
-		return typeof parsed["count"] === "number" && parsed["count"] >= 0 ? parsed["count"] : 0;
-	} catch (error) {
-		if (error instanceof Error) return 0;
-		throw error;
-	}
-}
-
-function readCounts(counterPath: string): Record<string, number> {
-	try {
-		const parsed: unknown = JSON.parse(readFileSync(counterPath, "utf8"));
-		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {};
-		const counts: Record<string, number> = {};
-		for (const [key, value] of Object.entries(parsed)) {
-			if (typeof value === "number" && value >= 0) counts[key] = value;
-		}
-		return counts;
-	} catch (error) {
-		if (error instanceof Error) return {};
-		throw error;
-	}
-}
-
-function readPlan(goalsPath: string): UlwLoopPlan | null {
+function readPlan(repoRoot: string, sessionId: string): UlwLoopPlan | null {
 	try {
-		return JSON.parse(readFileSync(goalsPath, "utf8")) as UlwLoopPlan;
+		return readUlwLoopPlanSync(repoRoot, { sessionId });
 	} catch (error) {
 		if (error instanceof Error) return null;
 		throw error;

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

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

package/packages/omo-codex/plugin/components/ulw-loop/src/status-next-actions.ts

@@ -1,36 +1,45 @@
 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";
+import type { UlwLoopToolkitSurface } from "./surface.js";
 import type { UlwLoopItem, 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 function statusNextActions(plan: UlwLoopPlan): readonly string[] {
+export function statusNextActions(plan: UlwLoopPlan, surface: UlwLoopToolkitSurface = "lazycodex"): readonly string[] {
 	const actions: string[] = [];
 	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));
+	if (plan.goals.length === 0) actions.push(`No goals yet: bootstrap with \`${createGoalsAction(surface)}\`.`);
+	else if (active !== undefined) 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>'\`.`,
+			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: UlwLoopPlan, active: UlwLoopItem): readonly string[] {
+function activeGoalActions(plan: UlwLoopPlan, active: UlwLoopItem, surface: UlwLoopToolkitSurface): readonly string[] {
 	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/src/steering-batch.ts

@@ -1,6 +1,7 @@
 // biome-ignore-all format: compact batch steering module stays below the pure LOC budget.
 import type { UlwLoopScope } from "./paths.js";
-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 type { UlwLoopLedgerEntry, UlwLoopPlan, UlwLoopSteeringAudit, UlwLoopSteeringProposal } from "./types.js";
@@ -43,17 +44,16 @@ export async function steerUlwLoopBatch(
 		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;
 		for (const item of prepared.items) if (item.kind === "fresh") next = item.prepared.next;
 		const fresh = prepared.items.filter((item): item is Extract<PreparedItem, { readonly kind: "fresh" }> => 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/src/steering.ts

@@ -1,7 +1,8 @@
 // biome-ignore-all format: compact steering module must stay below the 240 pure-LOC budget
 import { isUlwLoopDone } from "./goal-status.js";
 import type { UlwLoopScope } from "./paths.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 type {
@@ -209,9 +210,9 @@ export async function steerUlwLoop(repoRoot: string, proposal: UlwLoopSteeringPr
 		}
 		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);
-		if (batchEntry !== null) await appendLedger(repoRoot, batchEntry, scope);
+		const entries = [ledgerEntry(proposal, finalAudit, at)];
+		if (batchEntry !== null) 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/src/stop-resume-hook.ts

@@ -1,7 +1,9 @@
 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";
 import type { UlwLoopItem, UlwLoopPlan } from "./types.js";
 
@@ -37,7 +39,7 @@ export function runStopResumeHook(input: unknown): string {
 	if (boulderContinuationWillFire(payload.cwd, payload.session_id)) return "";
 	const scope = { sessionId: payload.session_id } as const;
 	const stateDir = ulwLoopDir(payload.cwd, scope);
-	const plan = readPlan(join(stateDir, "goals.json"));
+	const plan = readPlan(payload.cwd, payload.session_id);
 	if (plan === null || plan.aggregateCompletion?.status === "complete") return "";
 	const goal = resumableGoal(plan);
 	if (goal === undefined) return "";
@@ -81,11 +83,10 @@ function consumeResumeBudgetLocked(lockPath: string, stateDir: string, goalId: s
 	}
 }
 
-// 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: string, goalId: string): boolean {
-	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
@@ -119,24 +120,15 @@ function renderResumeDirective(plan: UlwLoopPlan, goal: UlwLoopItem, sessionId:
 	].join("\n");
 }
 
-function readPlan(goalsPath: string): UlwLoopPlan | null {
+function readPlan(repoRoot: string, sessionId: string): UlwLoopPlan | null {
 	try {
-		return JSON.parse(readFileSync(goalsPath, "utf8")) as UlwLoopPlan;
+		return readUlwLoopPlanSync(repoRoot, { sessionId });
 	} catch (error) {
 		if (error instanceof Error) return null;
 		throw error;
 	}
 }
 
-function countLedgerLines(ledgerPath: string): number {
-	try {
-		return readFileSync(ledgerPath, "utf8").split("\n").filter(Boolean).length;
-	} catch (error) {
-		if (error instanceof Error) return 0;
-		throw error;
-	}
-}
-
 function readCounter(counterPath: string): { count: number; ledgerLineCount: number } | null {
 	try {
 		if (!existsSync(counterPath)) return null;