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

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

@@ -1,74 +1,122 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import { createReadStream, readdirSync } from "node:fs";
-import { appendFile, mkdir, readFile, rename, writeFile } from "node:fs/promises";
-import { createInterface } from "node:readline";
-
+import { readdirSync } from "node:fs";
 import { aggregateCodexObjectiveForScope } from "./goal-status.js";
+import { readLedger as reconcileLedger } from "./ledger.js";
 import {
 	repoRelative,
 	type UlwLoopScope,
 	ulwLoopDir,
 	ulwLoopGoalsPath,
-	ulwLoopLedgerPath,
 	ulwLoopRelativeDir,
 	ulwLoopStateLockPath,
 } from "./paths.js";
-import { planMissingRecovery } from "./plan-missing-recovery.js";
-import { withStateLock } from "./state-lock.js";
-import type { UlwLoopLedgerEntry, UlwLoopPlan } from "./types.js";
-import { iso, ULW_LOOP_DIR, ULW_LOOP_GOALS, ULW_LOOP_LEDGER, UlwLoopError } from "./types.js";
+import { commit, materialize, materializeSync } from "./plan-commit.js";
+import { readOptional, reconcilePlan } from "./plan-log.js";
+import { planMissingError } from "./plan-missing-recovery.js";
+import { type StateLockOptions, withStateLock } from "./state-lock.js";
+import {
+	iso,
+	ULW_LOOP_DIR,
+	ULW_LOOP_GOALS,
+	ULW_LOOP_LEDGER,
+	UlwLoopError,
+	type UlwLoopLedgerEntry,
+	type UlwLoopPlan,
+} from "./types.js";
+
+export function readLedger(repoRoot: string, scope?: UlwLoopScope): UlwLoopLedgerEntry[] {
+	const lockPath = ulwLoopStateLockPath(repoRoot, scope);
+	if (heldLocks.getStore()?.has(lockPath)) {
+		assertStateLockOwned(lockPath);
+		materializeSync(ulwLoopDir(repoRoot, scope));
+	}
+	return reconcileLedger(repoRoot, scope);
+}
+export { planExists } from "./plan-log.js";
 
 const LEGACY_OBJECTIVE_PREFIX = `Complete all ulw-loop stories in ${ULW_LOOP_DIR}/${ULW_LOOP_GOALS}: `;
 const LEGACY_OBJECTIVE = `Complete all ulw-loop stories listed in ${ULW_LOOP_DIR}/${ULW_LOOP_GOALS}. Use ${ULW_LOOP_DIR}/${ULW_LOOP_LEDGER} as the durable audit trail.`;
 const locks = new Map<string, Promise<undefined>>();
-// Tracks which state dirs the CURRENT async continuation holds, so a read nested
-// inside a locked mutation can tell itself apart from an unlocked read elsewhere
-// in the same process.
-const heldLocks = new AsyncLocalStorage<ReadonlySet<string>>();
-
-function hasCode(error: unknown, code: string): boolean {
-	return error instanceof Error && "code" in error && error.code === code;
+interface LockContext {
+	readonly token: string;
+	readonly migrations: Map<string, UlwLoopLedgerEntry[]>;
 }
-
-function isLegacyEnumeratedAggregateObjective(objective: string | undefined): objective is string {
-	return objective === LEGACY_OBJECTIVE || Boolean(objective?.startsWith(LEGACY_OBJECTIVE_PREFIX));
+const heldLocks = new AsyncLocalStorage<ReadonlyMap<string, LockContext>>();
+const lockOptions = new AsyncLocalStorage<StateLockOptions>();
+export function withMutationLockOptions<T>(options: StateLockOptions, fn: () => Promise<T>): Promise<T> {
+	return lockOptions.run(options, fn);
 }
-
-function isSteeringKind(value: unknown): value is UlwLoopLedgerEntry["kind"] {
-	return (
-		value === "steering_accepted" ||
-		value === "steering_rejected" ||
-		value === "criteria_revised" ||
-		value === "batch_updated"
-	);
+function tokenAt(lockPath: string): string | undefined {
+	const raw = readOptional(lockPath);
+	if (raw === undefined) return undefined;
+	try {
+		const record: unknown = JSON.parse(raw);
+		return typeof record === "object" && record !== null && "token" in record && typeof record.token === "string"
+			? record.token
+			: undefined;
+	} catch (error) {
+		if (error instanceof SyntaxError) return undefined;
+		throw error;
+	}
+}
+export function assertStateLockOwned(lockPath: string): void {
+	const context = heldLocks.getStore()?.get(lockPath);
+	if (context === undefined) return;
+	if (tokenAt(lockPath) !== context.token)
+		throw new UlwLoopError("The ulw-loop mutation lock changed owners.", "ULW_LOOP_LOCK_LOST");
+}
+export function migrationEntries(plan: UlwLoopPlan): readonly UlwLoopLedgerEntry[] {
+	for (const context of heldLocks.getStore()?.values() ?? []) {
+		const entries = context.migrations.get(plan.goalsPath);
+		if (entries !== undefined) {
+			context.migrations.delete(plan.goalsPath);
+			return entries;
+		}
+	}
+	return [];
 }
-
 export async function withUlwLoopMutationLock<T>(repoRoot: string, fn: () => Promise<T>): Promise<T>;
 export async function withUlwLoopMutationLock<T>(
 	repoRoot: string,
 	scope: UlwLoopScope | undefined,
 	fn: () => Promise<T>,
+	options?: StateLockOptions,
 ): Promise<T>;
 export async function withUlwLoopMutationLock<T>(
 	repoRoot: string,
 	scopeOrFn: UlwLoopScope | (() => Promise<T>) | undefined,
 	maybeFn?: () => Promise<T>,
+	options: StateLockOptions = {},
 ): Promise<T> {
 	const scope = typeof scopeOrFn === "function" ? undefined : scopeOrFn;
 	const fn = typeof scopeOrFn === "function" ? scopeOrFn : maybeFn;
 	if (fn === undefined) throw new UlwLoopError("Missing ulw-loop mutation body.", "ULW_LOOP_LOCK_BODY_MISSING");
 	const lockKey = `${repoRoot}\0${ulwLoopRelativeDir(scope)}`;
 	const lockPath = ulwLoopStateLockPath(repoRoot, scope);
-	// The promise chain orders callers inside this process; the file lock is what
-	// excludes every other process (each CLI invocation) touching the same state dir.
-	const locked = (): Promise<T> =>
-		withStateLock(lockPath, () => heldLocks.run(new Set([...(heldLocks.getStore() ?? []), lockKey]), fn));
+	const locked = () =>
+		withStateLock(
+			lockPath,
+			async (token) => {
+				return heldLocks.run(
+					new Map([...(heldLocks.getStore() ?? []), [lockPath, { token, migrations: new Map() }]]),
+					async () => {
+						for (let attempt = 0; ; attempt += 1) {
+							try {
+								return await fn();
+							} catch (error) {
+								if (!(error instanceof UlwLoopError) || error.code !== "ULW_LOOP_PUBLISH_CONFLICT") throw error;
+								assertStateLockOwned(lockPath);
+								if (attempt !== 0) throw error;
+							}
+						}
+					},
+				);
+			},
+			{ ...lockOptions.getStore(), ...options },
+		);
 	const prior = locks.get(lockKey) ?? Promise.resolve(undefined);
 	const run = prior.then(locked, locked);
-	// The stored gate resolves to undefined so the map never retains fn's result
-	// (plans/audits), and it removes itself once no newer waiter replaced it —
-	// otherwise a long-lived host leaks one entry per (repo, scope) forever.
-	const gate: Promise<undefined> = run.then(
+	const gate = run.then(
 		() => undefined,
 		() => undefined,
 	);
@@ -78,60 +126,41 @@ export async function withUlwLoopMutationLock<T>(
 	});
 	return run;
 }
-
-export async function readUlwLoopPlan(repoRoot: string, scope?: UlwLoopScope): Promise<UlwLoopPlan> {
+export function readUlwLoopPlanSync(repoRoot: string, scope?: UlwLoopScope): UlwLoopPlan {
 	const path = ulwLoopGoalsPath(repoRoot, scope);
-	let raw: string;
-	try {
-		raw = await readFile(path, "utf8");
-	} catch (error) {
-		if (!hasCode(error, "ENOENT")) throw error;
-		const recovery = planMissingRecovery(listUlwLoopSessionIds(repoRoot));
-		throw new UlwLoopError(
-			`No ulw-loop plan found at ${repoRelative(path, repoRoot)}.\n${recovery.message}`,
-			"ULW_LOOP_PLAN_MISSING",
-			{ cause: error, ...(recovery.details === undefined ? {} : { details: recovery.details }) },
-		);
-	}
-	const parsed: UlwLoopPlan = JSON.parse(raw);
-	if (parsed.version !== 1 || !Array.isArray(parsed.goals)) {
+	const parsed = reconcilePlan(ulwLoopDir(repoRoot, scope));
+	if (parsed === undefined) throw planMissingError(repoRelative(path, repoRoot), listUlwLoopSessionIds(repoRoot));
+	if (parsed.version !== 1 || !Array.isArray(parsed.goals))
 		throw new UlwLoopError(`Invalid ulw-loop plan at ${repoRelative(path, repoRoot)}.`, "ULW_LOOP_PLAN_INVALID");
-	}
 	const previousObjective = parsed.codexObjective;
 	if (
 		(parsed.codexGoalMode ?? "per_story") === "aggregate" &&
-		isLegacyEnumeratedAggregateObjective(previousObjective)
+		previousObjective !== undefined &&
+		(previousObjective === LEGACY_OBJECTIVE || previousObjective.startsWith(LEGACY_OBJECTIVE_PREFIX))
 	) {
-		if (!(heldLocks.getStore()?.has(`${repoRoot}\0${ulwLoopRelativeDir(scope)}`) ?? false)) {
-			// A read path (status/criteria) must not mutate state: mutating here runs
-			// unlocked and a second reader could write a partially-migrated plan.
-			throw new UlwLoopError(
-				`The ulw-loop plan at ${repoRelative(path, repoRoot)} carries a legacy enumerated aggregate objective that must be migrated before reads continue. Run any state-mutating ulw-loop command once (e.g. \`record-evidence\`, \`steer\`, \`checkpoint\`) to migrate it under the state lock, then retry.`,
-				"ULW_LOOP_MIGRATION_REQUIRED",
-			);
-		}
-		const now = iso();
 		parsed.codexObjective = aggregateCodexObjectiveForScope(scope);
 		parsed.codexObjectiveAliases = [...new Set([...(parsed.codexObjectiveAliases ?? []), previousObjective])];
-		parsed.updatedAt = now;
-		await writePlan(repoRoot, parsed, scope);
-		await appendLedger(
-			repoRoot,
-			{
-				at: now,
-				kind: "aggregate_objective_migrated",
-				message: "Migrated legacy enumerated aggregate Codex objective to the stable pointer objective.",
-				before: { codexObjective: previousObjective },
-				after: { codexObjective: parsed.codexObjective },
-			},
-			scope,
-		);
+		heldLocks
+			.getStore()
+			?.get(ulwLoopStateLockPath(repoRoot, scope))
+			?.migrations.set(parsed.goalsPath, [
+				{
+					at: iso(),
+					kind: "aggregate_objective_migrated",
+					before: { codexObjective: previousObjective },
+					after: { codexObjective: parsed.codexObjective },
+				},
+			]);
 	}
 	return parsed;
 }
-
-// Session dirs are the only recovery hint that matters when a plan or a scope is
-// missing: the caller is almost always meant to target one of these siblings.
+export async function readUlwLoopPlan(repoRoot: string, scope?: UlwLoopScope): Promise<UlwLoopPlan> {
+	if (heldLocks.getStore()?.has(ulwLoopStateLockPath(repoRoot, scope))) {
+		assertStateLockOwned(ulwLoopStateLockPath(repoRoot, scope));
+		await materialize(ulwLoopDir(repoRoot, scope));
+	}
+	return readUlwLoopPlanSync(repoRoot, scope);
+}
 export function listUlwLoopSessionIds(repoRoot: string): readonly string[] {
 	try {
 		return readdirSync(ulwLoopDir(repoRoot), { withFileTypes: true })
@@ -142,84 +171,41 @@ export function listUlwLoopSessionIds(repoRoot: string): readonly string[] {
 		return [];
 	}
 }
-
 export async function writePlan(repoRoot: string, plan: UlwLoopPlan, scope?: UlwLoopScope): Promise<void> {
-	await mkdir(ulwLoopDir(repoRoot, scope), { recursive: true });
-	const path = ulwLoopGoalsPath(repoRoot, scope);
-	const tmpPath = `${path}.${process.pid}.${Date.now()}.tmp`;
-	await writeFile(tmpPath, `${JSON.stringify(plan, null, 2)}\n`, "utf8");
-	await rename(tmpPath, path);
+	await commit(repoRoot, scope, { plan, entries: [] });
 }
-
 export async function appendLedger(repoRoot: string, entry: UlwLoopLedgerEntry, scope?: UlwLoopScope): Promise<void> {
 	await appendLedgerEntries(repoRoot, [entry], scope);
 }
-
 export async function appendLedgerEntries(
 	repoRoot: string,
 	entries: readonly UlwLoopLedgerEntry[],
 	scope?: UlwLoopScope,
 ): Promise<void> {
-	if (entries.length === 0) return;
-	await mkdir(ulwLoopDir(repoRoot, scope), { recursive: true });
-	await appendFile(
-		ulwLoopLedgerPath(repoRoot, scope),
-		`${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`,
-		"utf8",
-	);
+	if (entries.length > 0) await commit(repoRoot, scope, { plan: await readUlwLoopPlan(repoRoot, scope), entries });
 }
-
-/**
- * Streams raw ledger lines without materializing the file. Real ledgers reach
- * many MB (legacy entries embedded full-plan snapshots), so `readFile` here
- * ballooned every steer/dedup path; line-at-a-time keeps memory O(longest line).
- */
-async function* ledgerLines(repoRoot: string, scope?: UlwLoopScope): AsyncGenerator<string> {
-	const stream = createReadStream(ulwLoopLedgerPath(repoRoot, scope), { encoding: "utf8" });
-	const lines = createInterface({ input: stream, crlfDelay: Number.POSITIVE_INFINITY });
-	try {
-		for await (const line of lines) {
-			if (line.trim().length > 0) yield line;
-		}
-	} catch (error) {
-		if (!hasCode(error, "ENOENT")) throw error;
-	} finally {
-		lines.close();
-		stream.destroy();
-	}
+function isSteeringKind(value: unknown): boolean {
+	return (
+		value === "steering_accepted" ||
+		value === "steering_rejected" ||
+		value === "criteria_revised" ||
+		value === "batch_updated"
+	);
 }
-
 export async function readSteeringLedgerEntries(repoRoot: string, scope?: UlwLoopScope): Promise<UlwLoopLedgerEntry[]> {
-	const entries: UlwLoopLedgerEntry[] = [];
-	for await (const line of ledgerLines(repoRoot, scope)) {
-		const entry: UlwLoopLedgerEntry = JSON.parse(line);
-		if (isSteeringKind(entry.kind)) entries.push(entry);
-	}
-	return entries;
+	return readLedger(repoRoot, scope).filter((entry) => isSteeringKind(entry.kind));
 }
-
-/**
- * First accepted steering entry matching an idempotency key/prompt signature.
- * A cheap substring probe on the raw line skips JSON.parse for the vast
- * majority of entries, so dedup stays flat even on legacy multi-MB ledgers.
- */
 export async function findAcceptedSteeringLedgerEntry(
 	repoRoot: string,
 	key: string,
 	scope?: UlwLoopScope,
 ): Promise<UlwLoopLedgerEntry | undefined> {
-	const probe = JSON.stringify(key);
-	for await (const line of ledgerLines(repoRoot, scope)) {
-		if (!line.includes(probe)) continue;
-		const entry: UlwLoopLedgerEntry = JSON.parse(line);
-		if (!isSteeringKind(entry.kind)) continue;
-		if (entry.steering?.invariant.accepted !== true) continue;
-		if (
-			entry.idempotencyKey === key ||
-			entry.steering.idempotencyKey === key ||
-			entry.steering.promptSignature === key
-		)
-			return entry;
-	}
-	return undefined;
+	return readLedger(repoRoot, scope).find(
+		(entry) =>
+			isSteeringKind(entry.kind) &&
+			entry.steering?.invariant.accepted === true &&
+			(entry.idempotencyKey === key ||
+				entry.steering.idempotencyKey === key ||
+				entry.steering.promptSignature === key),
+	);
 }

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

@@ -0,0 +1,84 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { type UlwLoopScope, ulwLoopDir } from "./paths.js";
+import type { UlwLoopLedgerEntry, UlwLoopPlan } from "./types.js";
+
+export interface PlanCommitRecord {
+	readonly version: 1;
+	readonly revision: number;
+	readonly plan: UlwLoopPlan;
+	readonly ledger: readonly UlwLoopLedgerEntry[];
+}
+export function hasCode(error: unknown, code: string): boolean {
+	return error instanceof Error && "code" in error && error.code === code;
+}
+export function readOptional(path: string): string | undefined {
+	try {
+		return readFileSync(path, "utf8");
+	} catch (error) {
+		if (hasCode(error, "ENOENT")) return undefined;
+		throw error;
+	}
+}
+export function logNames(dir: string): string[] {
+	try {
+		return readdirSync(join(dir, "revisions"))
+			.filter((name) => /^\d{8,}\.json$/.test(name))
+			.sort();
+	} catch (error) {
+		if (hasCode(error, "ENOENT")) return [];
+		throw error;
+	}
+}
+function readRecord(dir: string, name: string): PlanCommitRecord | undefined {
+	try {
+		const record: PlanCommitRecord = JSON.parse(readFileSync(join(dir, "revisions", name), "utf8"));
+		return record.version === 1 &&
+			Number.isInteger(record.revision) &&
+			record.plan?.version === 1 &&
+			Array.isArray(record.plan.goals) &&
+			Array.isArray(record.ledger)
+			? record
+			: undefined;
+	} catch (error) {
+		if (!(error instanceof SyntaxError)) throw error;
+		return undefined;
+	}
+}
+// Only the audit trail needs every record; plan reads use readNewestRecord.
+export function readRecords(dir: string): PlanCommitRecord[] {
+	const records: PlanCommitRecord[] = [];
+	for (const name of logNames(dir)) {
+		const record = readRecord(dir, name);
+		if (record !== undefined) records.push(record);
+	}
+	return records.sort((a, b) => a.revision - b.revision);
+}
+// Every ulw-loop status probe reads the plan, each record embeds a full plan copy, and records are never
+// deleted - so a plan read parses the newest record only, newest first, and stops there. Names are ordered
+// by their parsed revision because a wider zero-padding would break lexicographic order.
+export function readNewestRecord(dir: string): PlanCommitRecord | undefined {
+	const names = logNames(dir).sort((a, b) => Number.parseInt(b, 10) - Number.parseInt(a, 10));
+	for (const name of names) {
+		const record = readRecord(dir, name);
+		if (record !== undefined) return record;
+	}
+	return undefined;
+}
+export function reconcilePlan(dir: string): UlwLoopPlan | undefined {
+	const raw = readOptional(join(dir, "goals.json"));
+	let cached: UlwLoopPlan | undefined;
+	if (raw !== undefined) {
+		try {
+			cached = JSON.parse(raw);
+		} catch (error) {
+			if (!(error instanceof SyntaxError)) throw error;
+		}
+	}
+	const latest = readNewestRecord(dir);
+	return latest !== undefined && latest.revision >= (cached?.revision ?? 0) ? latest.plan : cached;
+}
+export function planExists(repoRoot: string, scope?: UlwLoopScope): boolean {
+	const dir = ulwLoopDir(repoRoot, scope);
+	return existsSync(join(dir, "goals.json")) || logNames(dir).length > 0;
+}

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

@@ -1,5 +1,12 @@
+import { UlwLoopError } from "./runtime.js";
+import type { UlwLoopToolkitSurface } from "./surface.js";
+
 export const ULW_LOOP_CREATE_GOALS_COMMAND = 'omo-agent-toolkit ulw-loop create-goals --brief "<brief>" --json';
 
+export function createGoalsAction(surface: UlwLoopToolkitSurface): string {
+	return surface === "omo-senpi" ? 'agentToolkit.createGoals({ brief: "<brief>" })' : ULW_LOOP_CREATE_GOALS_COMMAND;
+}
+
 export interface PlanMissingRecovery {
 	readonly message: string;
 	readonly details?: { readonly existingSessionIds: readonly string[] };
@@ -9,15 +16,31 @@ export interface PlanMissingRecovery {
  * A missing plan is either "never bootstrapped" or "bootstrapped under a different
  * session id"; the recovery text has to answer both without the caller guessing.
  */
-export function planMissingRecovery(existingSessionIds: readonly string[]): PlanMissingRecovery {
-	const lines = [`Recovery: bootstrap the plan with \`${ULW_LOOP_CREATE_GOALS_COMMAND}\`.`];
+export function planMissingRecovery(
+	existingSessionIds: readonly string[],
+	surface: UlwLoopToolkitSurface = "lazycodex",
+): PlanMissingRecovery {
+	const lines = [`Recovery: bootstrap the plan with \`${createGoalsAction(surface)}\`.`];
 	if (existingSessionIds.length === 0) return { message: lines.join("\n") };
 	lines.push(
-		`Existing ulw-loop session ids under .omo/ulw-loop/: ${existingSessionIds.join(", ")}. Re-run with \`--session-id <id>\` to target one of them.`,
+		surface === "omo-senpi"
+			? `Existing ulw-loop session ids under .omo/ulw-loop/: ${existingSessionIds.join(", ")}. The SDK is bound to the current session; resume the owning session to target its plan.`
+			: `Existing ulw-loop session ids under .omo/ulw-loop/: ${existingSessionIds.join(", ")}. Re-run with \`--session-id <id>\` to target one of them.`,
 	);
 	return { message: lines.join("\n"), details: { existingSessionIds } };
 }
 
+export function planMissingError(
+	planPath: string,
+	existingSessionIds: readonly string[],
+	surface: UlwLoopToolkitSurface = "lazycodex",
+): UlwLoopError {
+	const recovery = planMissingRecovery(existingSessionIds, surface);
+	return new UlwLoopError(`No ulw-loop plan found at ${planPath}.\n${recovery.message}`, "ULW_LOOP_PLAN_MISSING", {
+		...(recovery.details === undefined ? {} : { details: recovery.details }),
+	});
+}
+
 export function sessionScopeRequiredMessage(flag: string, existingSessionIds: readonly string[]): string {
 	const lines = [
 		"No ulw-loop session scope: neither the session env (OMO_ULW_LOOP_SESSION_ID / CODEX_SESSION_ID / CODEX_THREAD_ID / PI_SESSION_ID) nor the flag names this run, and the shared .omo/ulw-loop root is never used implicitly because every session in this directory would read and overwrite it.",

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

@@ -8,8 +8,9 @@ import {
 } from "./codex-goal-snapshot.js";
 import { compatibleCodexObjectives, expectedCodexObjective, isFinalRunCompletionCandidate } from "./goal-status.js";
 import type { UlwLoopScope } from "./paths.js";
+import { commit } from "./plan-commit.js";
 import { seedDefaultSuccessCriteria } from "./plan-crud.js";
-import { appendLedger, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
+import { readUlwLoopPlan, withUlwLoopMutationLock } from "./plan-io.js";
 import type { UlwLoopItem, UlwLoopLedgerEntry, UlwLoopPlan } from "./types.js";
 import { iso, UlwLoopError } from "./types.js";
 
@@ -88,8 +89,7 @@ export async function recordFinalReviewBlockers(
 		const summaryEntry: UlwLoopLedgerEntry = { at: now, kind: "goal_review_blocked", goalId: goal.id, status: goal.status, evidence: args.evidence, codexGoal, message: `Review blockers recorded; appended ${newGoal.id}.` };
 		Reflect.set(summaryEntry, "kind", "blocker_recorded");
 		const ledgerEntries = [blockedEntry, addedEntry, summaryEntry];
-		await writePlan(repoRoot, plan, scope);
-		for (const entry of ledgerEntries) await appendLedger(repoRoot, entry, scope);
+		await commit(repoRoot, scope, { plan, entries: ledgerEntries });
 		return {
 			plan,
 			blockedGoal: goal,

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

@@ -1,9 +1,15 @@
 import { checkpointUlwLoop } from "../checkpoint.js";
 import { checkpointTemplate } from "../checkpoint-template.js";
 import { recordEvidence } from "../evidence.js";
-import { type UlwLoopScope, ulwLoopAttemptEvidenceDir } from "../paths.js";
+import {
+	normalizeUlwLoopSessionId,
+	type UlwLoopScope,
+	ulwLoopAttemptEvidenceDir,
+	ulwLoopGoalsRelativePath,
+} from "../paths.js";
 import { addUlwLoopGoal, createUlwLoopPlan, startNextUlwLoop, summarizeUlwLoopPlan } from "../plan-crud.js";
-import { readUlwLoopPlan } from "../plan-io.js";
+import { listUlwLoopSessionIds, readUlwLoopPlan } from "../plan-io.js";
+import { planMissingError } from "../plan-missing-recovery.js";
 import { recordFinalReviewBlockers } from "../review-blockers.js";
 import { UlwLoopError } from "../runtime.js";
 import { statusNextActions } from "../status-next-actions.js";
@@ -41,8 +47,15 @@ function validateCodexGoalJson(raw: string | undefined): void {
 
 function validateContext(context: ToolkitContext): void {
 	if (!context.cwd.trim()) throw new UlwLoopError("cwd is required.", "ULW_LOOP_CWD_REQUIRED");
-	if (!context.sessionId.trim())
+	const sessionId = context.sessionId.trim();
+	if (!sessionId)
 		throw new UlwLoopError("ULW_LOOP_SESSION_ID_REQUIRED: sessionId is required.", "ULW_LOOP_SESSION_ID_REQUIRED");
+	const normalizedSessionId = normalizeUlwLoopSessionId(sessionId);
+	if (normalizedSessionId === null || /(?:^|[\\/])\.\.(?:[\\/]|$)/.test(sessionId))
+		throw new UlwLoopError(
+			"ULW_LOOP_SESSION_ID_INVALID: sessionId normalizes to null.",
+			"ULW_LOOP_SESSION_ID_INVALID",
+		);
 	if (context.surface !== "omo-senpi" && context.surface !== "lazycodex")
 		throw new UlwLoopError("surface must be omo-senpi or lazycodex.", "ULW_LOOP_SURFACE_INVALID");
 }
@@ -106,6 +119,18 @@ export function createAgentToolkit(context: ToolkitContext, deps: AgentToolkitDe
 			const nextActions = typeof result === "object" && result !== null ? nextActionsFrom(result) : [];
 			return await notify(operation, { ok: true, operation, result, nextActions });
 		} catch (error) {
+			if (error instanceof UlwLoopError && error.code === "ULW_LOOP_PLAN_MISSING" && context.surface === "omo-senpi")
+				return notify(
+					operation,
+					failure(
+						operation,
+						planMissingError(
+							ulwLoopGoalsRelativePath(scope),
+							listUlwLoopSessionIds(context.cwd),
+							context.surface,
+						),
+					),
+				);
 			const response = caught(operation, error instanceof Error ? error : new Error("ULW_LOOP_ERROR"));
 			return notify(operation, response);
 		}
@@ -143,7 +168,7 @@ export function createAgentToolkit(context: ToolkitContext, deps: AgentToolkitDe
 			}
 		},
 		help: () => invoke("help", async () => ULW_LOOP_MANIFEST),
-		createGoals: (args) => invoke("create-goals", () => createUlwLoopPlan(context.cwd, args, scope)),
+		createGoals: (args) => invoke("create-goals", () => createUlwLoopPlan(context.cwd, args, scope, context.surface)),
 		status: () =>
 			invoke("status", async () => {
 				const plan = await readUlwLoopPlan(context.cwd, scope);
@@ -151,7 +176,7 @@ export function createAgentToolkit(context: ToolkitContext, deps: AgentToolkitDe
 				return {
 					plan,
 					summary: summarizeUlwLoopPlan(plan),
-					nextActions: statusNextActions(plan),
+					nextActions: statusNextActions(plan, context.surface),
 					// Attempt directories are an evidence-layout v2 concept; a v1 plan must not advertise one.
 					...(active === undefined || plan.evidenceLayoutVersion !== 2
 						? {}

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

@@ -0,0 +1,59 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export function readAdmissionBreaker(sessionId: string): string | null {
+	const dataDir = process.env["PLUGIN_DATA"];
+	if (typeof dataDir !== "string") return null;
+	try {
+		const value: unknown = JSON.parse(readFileSync(join(dataDir, "spawn-breaker", `${sessionId}.json`), "utf8"));
+		return typeof value === "object" && value !== null && "reason" in value && typeof value.reason === "string"
+			? value.reason
+			: "capacity limit";
+	} catch {
+		return null;
+	}
+}
+
+// These hook budget files are not plan/audit state and remain outside the log.
+export 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);
+}
+export function isNonEmptyFile(path: string): boolean {
+	try {
+		return existsSync(path) && statSync(path).size > 0;
+	} catch (error) {
+		if (error instanceof Error) return false;
+		throw error;
+	}
+}
+export function readCount(counterPath: string): number {
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(counterPath, "utf8"));
+		return typeof parsed === "object" &&
+			parsed !== null &&
+			"count" in parsed &&
+			typeof parsed.count === "number" &&
+			parsed.count >= 0
+			? parsed.count
+			: 0;
+	} catch (error) {
+		if (error instanceof Error) return 0;
+		throw error;
+	}
+}
+export 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;
+	}
+}