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

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

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

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

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

package/packages/omo-codex/plugin/components/ulw-loop/skills/ulw-loop/references/full-workflow.md

@@ -20,7 +20,7 @@ Run each criterion's real-surface proof yourself through the channel that faithf
 
 1. **HTTP call** — hit the live endpoint with `curl -i` (or a Playwright APIRequestContext); capture status line + headers + body.
 2. **Terminal / TUI** - prove it through the xterm.js web terminal; tmux `send-keys` is fine for a boot smoke, but NEVER `tmux capture-pane` for color/layout/CJK evidence (it degrades truecolor).
-3. **Browser use** — in Codex, use `browser:control-in-app-browser` first when available and the scenario does not need an authenticated or persistent user browser profile. Otherwise use Chrome to drive the REAL page; if unavailable, use agent-browser. Capture action log + screenshot path. Never downgrade a browser-facing criterion.
+3. **Browser use** — in Codex, prefer `browser:control-in-app-browser`. Otherwise, or for Chrome semantics, stealth, trace, or auth, WRITE a `playwright-core` script and run it from js eval against local Chrome (`channel: "chrome"`; persistent context on a CLONED profile, never the live one). Capture action log + screenshot path. Never downgrade a browser-facing criterion.
 4. **Computer use** — for desktop/GUI apps, drive the running app via OS automation (computer-use, AppleScript, xdotool, etc.); capture action log + screenshot.
 
 For TUI visual QA (mandatory when a PR or review must inspect the terminal screen),
@@ -165,7 +165,7 @@ Loop per goal. Cap at 5 cycles per goal. Cap identical same-criterion failures a
 4. INTEGRATE + CRITICAL SELF-QA + GIT CHECKPOINT (EVERY WORKER RETURN): do NOT trust the worker's report. Read the diff yourself, re-run its tests, and run LSP diagnostics on the changed files. Treat "done" as a claim to disprove. If the diff drifts, the test is hollow, or evidence is missing, RESPAWN the worker with the specific failure context. Once the work unit is verified, use `git-master` before staging: inspect recent repository commits and touched-path history to infer commit language, Conventional Commit scope, message shape, and unit size. Stage only that unit's files and commit in the observed style; do not carry verified work forward into a later omnibus commit. If no git-tracked files changed or committing is unsafe, record the no-commit reason as evidence. Forward every finding/learning to subsequent workers.
 5. EXECUTE-AS-SCENARIO: ACTUALLY run the Manual-QA scenario the criterion named (channel table above). Run it yourself for the orchestrator check; for heavier flows dispatch a dedicated QA execution worker (`lazycodex-worker-medium` by default; `lazycodex-worker-high` when the QA flow itself is hard) whose ONLY job is to drive the channel and write the artifact to the named evidence path. If the scenario FAILS, respawn the implementing worker with the captured failure — do not hand-patch around it.
 6. CAPTURE: collect the observable artifact path: transcript, stdout, screenshot, assertion, status+body, diff, or parsed dump. No artifact written at the evidence path — not done; record BLOCKED and respawn QA.
-7. CLEAN (PAIRED, NEVER SKIP): tear down every runtime artifact step 5 spawned BEFORE recording — server PIDs (`kill`, verify `kill -0` fails), `tmux` sessions (`tmux kill-session -t ulw-qa-<criterion>`; confirm `tmux ls`), browser / Playwright contexts (`.close()`), containers (`docker rm -f`), bound ports (`lsof -i :<port>` empty), temp sockets / files / dirs (`rm -rf` the `mktemp` paths), QA-only env vars, AND close every finished worker (v1 `close_agent`; on V2 finished workers end on their own — `interrupt_agent` any still running). Register each teardown as its own todo the moment the QA spawns the resource (scripts, tmux assets, browsers / agent-browser sessions, PIDs, ports) so none is forgotten. Embed a one-line cleanup receipt in the evidence string, e.g. `cleanup: killed 12345; tmux kill-session ulw-qa-foo; rm -rf /tmp/ulw.aB12cD; interrupt_agent w-3`. Missing receipt → record BLOCKED, not PASS.
+7. CLEAN (PAIRED, NEVER SKIP): tear down every runtime artifact step 5 spawned BEFORE recording — server PIDs (`kill`, verify `kill -0` fails), `tmux` sessions (`tmux kill-session -t ulw-qa-<criterion>`; confirm `tmux ls`), browser / Playwright contexts (`.close()`), containers (`docker rm -f`), bound ports (`lsof -i :<port>` empty), temp sockets / files / dirs (`rm -rf` the `mktemp` paths), QA-only env vars, AND close every finished worker (v1 `close_agent`; on V2 finished workers end on their own — `interrupt_agent` any still running). Register each teardown as its own todo the moment the QA spawns the resource (scripts, tmux assets, browser contexts, PIDs, ports) so none is forgotten. Embed a one-line cleanup receipt in the evidence string, e.g. `cleanup: killed 12345; tmux kill-session ulw-qa-foo; rm -rf /tmp/ulw.aB12cD; interrupt_agent w-3`. Missing receipt → record BLOCKED, not PASS.
 8. RECORD one result immediately from the artifact you just wrote — never from memory or a later turn — stamping the capture tree `$(git rev-parse --short "HEAD^{tree}")` into the evidence:
    - PASS: `omo-agent-toolkit ulw-loop record-evidence --goal-id <id> --criterion-id <id> --status pass --evidence "<observable> @tree:<short-tree> | <cleanup receipt>" --json`
    - FAIL: `omo-agent-toolkit ulw-loop record-evidence --goal-id <id> --criterion-id <id> --status fail --evidence "<observable> @tree:<short-tree> | <cleanup receipt>" --notes "<diagnosis>" --json`

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

@@ -10,7 +10,8 @@ import { requireAllCriteriaPass, requireAllPlanCriteriaPass, requireEssentialCri
 import { codexGoalMode, isFinalRunCompletionCandidate } from "./goal-status.js";
 import type { UlwLoopScope } from "./paths.js";
 import { ulwLoopAttemptEvidenceDir } from "./paths.js";
-import { appendLedger, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
+import { commit } from "./plan-commit.js";
+import { readUlwLoopPlan, withUlwLoopMutationLock } from "./plan-io.js";
 import {
 	classifyExternalAuthorizationBlocker,
 	clearGoalBlockerFields,
@@ -226,11 +227,11 @@ export async function checkpointUlwLoop(
 		if (aggregateCompletion !== undefined) plan.aggregateCompletion = aggregateCompletion;
 		if (aggregateCompletion !== undefined) nextActions = [...nextActions, 'aggregate complete — now update_goal({status:"complete"})'];
 		plan.updatedAt = now;
-		await writePlan(repoRoot, plan, scope);
 		const ledgerEntry = buildLedger(now, args, goal, qualityGate, codexGoal, aggregateCompletion);
-		await appendLedger(repoRoot, ledgerEntry, scope);
+		const entries = [ledgerEntry];
 		const closedBatch = args.status === "complete" ? batchClosedBy(plan, goal.id) : undefined;
-		if (closedBatch !== undefined) await appendLedger(repoRoot, { at: now, kind: "batch_closed", goalId: goal.id, message: closedBatch.batchId }, scope);
+		if (closedBatch !== undefined) entries.push({ at: now, kind: "batch_closed", goalId: goal.id, message: closedBatch.batchId });
+		await commit(repoRoot, scope, { plan, entries });
 		return aggregateCompletion === undefined
 			? { plan, goal, ledgerEntry, nextActions, warnings }
 			: { plan, goal, ledgerEntry, aggregateCompletion, nextActions, warnings };

package/packages/omo-codex/plugin/components/ulw-loop/src/domain-types.ts

@@ -63,6 +63,9 @@ export interface UlwLoopValidationBatch {
 
 export interface UlwLoopPlan {
 	version: 1;
+	revision?: number;
+	brief?: string;
+	ledgerResetRevision?: number;
 	evidenceLayoutVersion?: 2;
 	createdAt: string;
 	updatedAt: string;
@@ -158,6 +161,8 @@ export interface UlwLoopQualityGateSenpi extends UlwLoopQualityGateCommon {
 export type UlwLoopQualityGate = UlwLoopQualityGateLazycodex | UlwLoopQualityGateSenpi;
 
 export interface UlwLoopLedgerEntry {
+	revision?: number;
+	id?: string;
 	at: string;
 	kind: UlwLoopLedgerEventKind;
 	goalId?: string;

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

@@ -1,6 +1,7 @@
 import { essentialCriteriaOf, hasAllCriteriaPass, hasEssentialCriteriaPass } from "./goal-status.js";
 import type { UlwLoopScope } from "./paths.js";
-import { appendLedger, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
+import { commit } from "./plan-commit.js";
+import { readUlwLoopPlan, withUlwLoopMutationLock } from "./plan-io.js";
 import type { UlwLoopItem, UlwLoopLedgerEntry, UlwLoopPlan, UlwLoopSuccessCriterion } from "./types.js";
 import { iso, UlwLoopError } from "./types.js";
 
@@ -75,7 +76,6 @@ export async function recordEvidence(
 		if (args.notes !== undefined) criterion.notes = args.notes;
 		goal.updatedAt = capturedAt;
 		plan.updatedAt = capturedAt;
-		await writePlan(repoRoot, plan, scope);
 		const ledgerEntry: UlwLoopLedgerEntry = {
 			at: capturedAt,
 			kind,
@@ -87,7 +87,7 @@ export async function recordEvidence(
 			before: { status: prevStatus },
 			after: { goalId: goal.id, criterionId: criterion.id, status: args.status, evidence, capturedAt, prevStatus },
 		};
-		await appendLedger(repoRoot, ledgerEntry, scope);
+		await commit(repoRoot, scope, { plan, entries: [ledgerEntry] });
 		return { plan, goal, criterion, ledgerEntry };
 	});
 }
@@ -115,19 +115,19 @@ export async function markCriteriaPendingResetForGoal(
 		}
 		goal.updatedAt = now;
 		plan.updatedAt = now;
-		await writePlan(repoRoot, plan, scope);
-		await appendLedger(
-			repoRoot,
-			{
-				at: now,
-				kind: "criteria_revised",
-				goalId,
-				message: `Reset ${goal.successCriteria.length} criteria to pending.`,
-				before,
-				after: { resetCount: goal.successCriteria.length },
-			},
-			scope,
-		);
+		await commit(repoRoot, scope, {
+			plan,
+			entries: [
+				{
+					at: now,
+					kind: "criteria_revised",
+					goalId,
+					message: `Reset ${goal.successCriteria.length} criteria to pending.`,
+					before,
+					after: { resetCount: goal.successCriteria.length },
+				},
+			],
+		});
 		return { plan, resetCount: goal.successCriteria.length };
 	});
 }

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

@@ -0,0 +1,33 @@
+import { join } from "node:path";
+import { type UlwLoopScope, ulwLoopDir } from "./paths.js";
+import { readOptional, readRecords, reconcilePlan } from "./plan-log.js";
+import type { UlwLoopLedgerEntry } from "./types.js";
+
+export function readLedgerAt(dir: string): UlwLoopLedgerEntry[] {
+	const entries = new Map<string, UlwLoopLedgerEntry>();
+	const lines = (readOptional(join(dir, "ledger.jsonl")) ?? "").split(/\r?\n/);
+	for (const [index, line] of lines.entries()) {
+		if (line.trim().length === 0) continue;
+		try {
+			const entry: UlwLoopLedgerEntry = JSON.parse(line);
+			entry.revision ??= 0;
+			entry.id ??= `legacy-${index + 1}`;
+			entries.set(entry.id, entry);
+		} catch (error) {
+			if (!(error instanceof SyntaxError)) throw error;
+		}
+	}
+	for (const record of readRecords(dir))
+		for (const [seq, entry] of record.ledger.entries()) {
+			const id = entry.id ?? `${record.revision}-${seq}`;
+			entries.set(id, { ...entry, revision: record.revision, id });
+		}
+	const reset = reconcilePlan(dir)?.ledgerResetRevision ?? 0;
+	const sequence = (entry: UlwLoopLedgerEntry) => Number(entry.id?.split("-").at(-1) ?? 0);
+	return [...entries.values()]
+		.filter((entry) => (entry.revision ?? 0) >= reset)
+		.sort((a, b) => (a.revision ?? 0) - (b.revision ?? 0) || sequence(a) - sequence(b));
+}
+export function readLedger(repoRoot: string, scope?: UlwLoopScope): UlwLoopLedgerEntry[] {
+	return readLedgerAt(ulwLoopDir(repoRoot, scope));
+}

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

@@ -0,0 +1,124 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import { linkSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { readLedgerAt } from "./ledger.js";
+import { type UlwLoopScope, ulwLoopDir, ulwLoopStateLockPath } from "./paths.js";
+import { assertStateLockOwned, migrationEntries } from "./plan-io.js";
+import { hasCode, type PlanCommitRecord, readOptional, readRecords, reconcilePlan } from "./plan-log.js";
+import { UlwLoopError, type UlwLoopLedgerEntry, type UlwLoopPlan } from "./types.js";
+
+interface CommitHooks {
+	readonly beforeMutation?: () => void | Promise<void>;
+	readonly beforeCommit?: () => void | Promise<void>;
+	readonly afterCommit?: () => void | Promise<void>;
+	readonly link?: (source: string, destination: string) => void;
+	readonly writeView?: (path: string, content: string) => Promise<void>;
+}
+const hooks = new AsyncLocalStorage<CommitHooks>();
+export function withCommitHooks<T>(value: CommitHooks, fn: () => Promise<T>): Promise<T> {
+	return hooks.run(value, fn);
+}
+
+export async function beforePlanMutation(): Promise<void> {
+	await hooks.getStore()?.beforeMutation?.();
+}
+export async function writeViewFile(path: string, content: string): Promise<void> {
+	await (hooks.getStore()?.writeView ?? writeFile)(path, content);
+}
+
+// link is the sole commit point; no copy fallback (Node copyFile is not atomic).
+// A resumed zombie can publish first, but never overwrite an existing revision.
+// Logical audit order is (revision, sequence), not materialization completion time.
+export async function commit(
+	repoRoot: string,
+	scope: UlwLoopScope | undefined,
+	mutation: {
+		readonly plan: UlwLoopPlan;
+		readonly entries: readonly UlwLoopLedgerEntry[];
+	},
+): Promise<void> {
+	const { plan } = mutation;
+	const dir = ulwLoopDir(repoRoot, scope);
+	assertStateLockOwned(ulwLoopStateLockPath(repoRoot, scope));
+	await hooks.getStore()?.beforeCommit?.();
+	const next = (plan.revision ?? 0) + 1;
+	const brief = plan.brief ?? readOptional(join(dir, "brief.md")) ?? "";
+	const entries = [...migrationEntries(plan), ...mutation.entries].map((entry, seq) => ({
+		...entry,
+		revision: next,
+		id: `${next}-${seq}`,
+	}));
+	const record: PlanCommitRecord = {
+		version: 1,
+		revision: next,
+		plan: { ...plan, revision: next, brief },
+		ledger: entries,
+	};
+	mkdirSync(join(dir, "revisions"), { recursive: true });
+	mkdirSync(join(dir, "tmp"), { recursive: true });
+	const temp = join(dir, "tmp", `${process.pid}-${randomUUID()}.json`);
+	try {
+		writeFileSync(temp, `${JSON.stringify(record)}\n`, { flag: "wx" });
+		try {
+			(hooks.getStore()?.link ?? linkSync)(temp, join(dir, "revisions", `${String(next).padStart(8, "0")}.json`));
+		} catch (error) {
+			if (hasCode(error, "EEXIST"))
+				throw new UlwLoopError("Another writer published the read revision.", "ULW_LOOP_PUBLISH_CONFLICT", {
+					cause: error,
+				});
+			if (["EPERM", "ENOTSUP", "EXDEV"].some((code) => hasCode(error, code)))
+				throw new UlwLoopError(
+					"Immutable ulw-loop publication requires atomic hard links.",
+					"ULW_LOOP_PUBLISH_UNSUPPORTED_FS",
+					{ cause: error },
+				);
+			throw error;
+		}
+	} finally {
+		rmSync(temp, { force: true });
+	}
+	plan.revision = next;
+	plan.brief = brief;
+	for (const [index, entry] of mutation.entries.entries())
+		Object.assign(entry, entries[index + entries.length - mutation.entries.length]);
+	await hooks.getStore()?.afterCommit?.();
+	await materialize(dir);
+}
+
+function viewContents(dir: string): [string, string][] {
+	const plan = reconcilePlan(dir);
+	if (plan === undefined || readRecords(dir).length === 0) return [];
+	const ledger = readLedgerAt(dir);
+	const views: [string, string][] = [
+		["goals.json", `${JSON.stringify(plan, null, 2)}\n`],
+		["ledger.jsonl", ledger.length === 0 ? "" : `${ledger.map((entry) => JSON.stringify(entry)).join("\n")}\n`],
+		["brief.md", plan.brief ?? readOptional(join(dir, "brief.md")) ?? ""],
+	];
+	return views.filter(([name, content]) => readOptional(join(dir, name)) !== content);
+}
+export function materializeSync(dir: string): void {
+	for (const [name, content] of viewContents(dir)) {
+		mkdirSync(join(dir, "tmp"), { recursive: true });
+		const temp = join(dir, "tmp", `${process.pid}-${randomUUID()}-${name}`);
+		try {
+			writeFileSync(temp, content, { flag: "wx" });
+			renameSync(temp, join(dir, name));
+		} finally {
+			rmSync(temp, { force: true });
+		}
+	}
+}
+export async function materialize(dir: string): Promise<void> {
+	for (const [name, content] of viewContents(dir)) {
+		mkdirSync(join(dir, "tmp"), { recursive: true });
+		const temp = join(dir, "tmp", `${process.pid}-${randomUUID()}-${name}`);
+		try {
+			await writeViewFile(temp, content);
+			await rename(temp, join(dir, name));
+		} finally {
+			rmSync(temp, { force: true });
+		}
+	}
+}

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

@@ -1,20 +1,21 @@
-import { existsSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
-
 import { aggregateCodexObjectiveForScope, isUlwLoopDone } from "./goal-status.js";
 import {
 	type UlwLoopScope,
-	ulwLoopBriefPath,
 	ulwLoopBriefRelativePath,
-	ulwLoopDir,
-	ulwLoopGoalsPath,
 	ulwLoopGoalsRelativePath,
-	ulwLoopLedgerPath,
 	ulwLoopLedgerRelativePath,
 } from "./paths.js";
+import { beforePlanMutation, commit } from "./plan-commit.js";
 import { appendGoalToPlan, deriveGoalCandidates, makeGoal } from "./plan-goal-factory.js";
-import { appendLedger, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
-import type { UlwLoopCodexGoalMode, UlwLoopItem, UlwLoopPlan, UlwLoopSuccessCriterion } from "./types.js";
+import { planExists, readUlwLoopPlan, withUlwLoopMutationLock } from "./plan-io.js";
+import type { UlwLoopToolkitSurface } from "./surface.js";
+import type {
+	UlwLoopCodexGoalMode,
+	UlwLoopItem,
+	UlwLoopLedgerEntry,
+	UlwLoopPlan,
+	UlwLoopSuccessCriterion,
+} from "./types.js";
 import { iso, UlwLoopError } from "./types.js";
 import { parseValidationBatches } from "./validation-batch.js";
 
@@ -60,11 +61,19 @@ export async function createUlwLoopPlan(
 	repoRoot: string,
 	args: { brief: string; codexGoalMode?: UlwLoopCodexGoalMode; force?: boolean; validationBatchesJson?: string },
 	scope?: UlwLoopScope,
+	surface: UlwLoopToolkitSurface = "lazycodex",
 ): Promise<UlwLoopPlan> {
 	return withUlwLoopMutationLock(repoRoot, scope, async () => {
-		if (!args.force && existsSync(ulwLoopGoalsPath(repoRoot, scope))) {
-			const existing = await readUlwLoopPlan(repoRoot, scope);
-			if (isUlwLoopDone(existing)) throw completedPlanExistsError(scope);
+		let existing: UlwLoopPlan | undefined;
+		if (planExists(repoRoot, scope)) {
+			try {
+				existing = await readUlwLoopPlan(repoRoot, scope);
+			} catch (error) {
+				if (!args.force) throw error;
+			}
+		}
+		if (!args.force && existing !== undefined) {
+			if (isUlwLoopDone(existing)) throw completedPlanExistsError(scope, surface);
 			throw new UlwLoopError(
 				`Refusing to overwrite existing ${ulwLoopGoalsRelativePath(scope)}; pass --force to recreate it.`,
 				"ULW_LOOP_PLAN_EXISTS",
@@ -76,6 +85,9 @@ export async function createUlwLoopPlan(
 		);
 		const plan: UlwLoopPlan = {
 			version: 1,
+			revision: existing?.revision ?? 0,
+			ledgerResetRevision: (existing?.revision ?? 0) + 1,
+			brief: args.brief.endsWith("\n") ? args.brief : `${args.brief}\n`,
 			evidenceLayoutVersion: 2,
 			createdAt: now,
 			updatedAt: now,
@@ -88,29 +100,27 @@ export async function createUlwLoopPlan(
 		const validationBatches = await parseValidationBatches(args.validationBatchesJson, goals);
 		if (validationBatches !== undefined) plan.validationBatches = validationBatches;
 		if (plan.codexGoalMode === "aggregate") plan.codexObjective = aggregateCodexObjectiveForScope(scope);
-		await mkdir(ulwLoopDir(repoRoot, scope), { recursive: true });
-		await writeFile(
-			ulwLoopBriefPath(repoRoot, scope),
-			args.brief.endsWith("\n") ? args.brief : `${args.brief}\n`,
-			"utf8",
-		);
-		await writePlan(repoRoot, plan, scope);
-		await writeFile(ulwLoopLedgerPath(repoRoot, scope), "", "utf8");
-		await appendLedger(
-			repoRoot,
-			{ at: now, kind: "plan_created", message: `${goals.length} goal(s) created` },
-			scope,
-		);
+		await beforePlanMutation();
+		await commit(repoRoot, scope, {
+			plan,
+			entries: [{ at: now, kind: "plan_created", message: `${goals.length} goal(s) created` }],
+		});
 		return plan;
 	});
 }
 
-function completedPlanExistsError(scope?: UlwLoopScope): UlwLoopError {
+function completedPlanExistsError(scope: UlwLoopScope | undefined, surface: UlwLoopToolkitSurface): UlwLoopError {
 	return new UlwLoopError(
 		[
 			`Existing ulw-loop aggregate is already complete at ${ulwLoopGoalsRelativePath(scope)}.`,
-			"Start a new run with `omo-agent-toolkit ulw-loop create-goals --session-id <new-id> ...` to isolate fresh state.",
-			"Use --force only when you intentionally want to overwrite the completed evidence.",
+			...(surface === "omo-senpi"
+				? [
+						"Start a new run under a fresh session id (a new senpi session) or call agentToolkit.createGoals({ brief, force: true }) to recreate.",
+					]
+				: [
+						"Start a new run with `omo-agent-toolkit ulw-loop create-goals --session-id <new-id> ...` to isolate fresh state.",
+						"Use --force only when you intentionally want to overwrite the completed evidence.",
+					]),
 		].join(" "),
 		"ULW_LOOP_PLAN_EXISTS_COMPLETE",
 	);
@@ -125,12 +135,10 @@ export async function addUlwLoopGoal(
 		const plan = await readUlwLoopPlan(repoRoot, scope);
 		const now = iso();
 		const goal = appendGoalToPlan(plan, args.title, args.objective, now);
-		await writePlan(repoRoot, plan, scope);
-		await appendLedger(
-			repoRoot,
-			{ at: now, kind: "goal_added", goalId: goal.id, status: goal.status, message: goal.title },
-			scope,
-		);
+		await commit(repoRoot, scope, {
+			plan,
+			entries: [{ at: now, kind: "goal_added", goalId: goal.id, status: goal.status, message: goal.title }],
+		});
 		return { plan, goal };
 	});
 }
@@ -146,21 +154,18 @@ export async function startNextUlwLoop(
 		if (plan.aggregateCompletion?.status === "complete") return { done: true, plan };
 		const existing = plan.goals.find((goal) => goal.status === "in_progress" && isScheduleEligible(goal));
 		if (existing) return { plan, goal: existing, resumed: true };
+		const entries: UlwLoopLedgerEntry[] = [];
 		let next = plan.goals.find((goal) => goal.status === "pending" && isScheduleEligible(goal));
 		if (!next && args.retryFailed) {
 			next = plan.goals.find((goal) => goal.status === "failed" && !goal.nonRetriable && isScheduleEligible(goal));
 			if (next)
-				await appendLedger(
-					repoRoot,
-					{
-						at: now,
-						kind: "goal_retried",
-						goalId: next.id,
-						status: "pending",
-						...(next.failureReason ? { message: next.failureReason } : {}),
-					},
-					scope,
-				);
+				entries.push({
+					at: now,
+					kind: "goal_retried",
+					goalId: next.id,
+					status: "pending",
+					...(next.failureReason ? { message: next.failureReason } : {}),
+				});
 		}
 		if (!next) return { done: true, plan };
 		next.status = "in_progress";
@@ -170,12 +175,14 @@ export async function startNextUlwLoop(
 		next.updatedAt = now;
 		plan.activeGoalId = next.id;
 		plan.updatedAt = now;
-		await writePlan(repoRoot, plan, scope);
-		await appendLedger(
-			repoRoot,
-			{ at: now, kind: "goal_started", goalId: next.id, status: next.status, message: `Attempt ${next.attempt}` },
-			scope,
-		);
+		entries.push({
+			at: now,
+			kind: "goal_started",
+			goalId: next.id,
+			status: next.status,
+			message: `Attempt ${next.attempt}`,
+		});
+		await commit(repoRoot, scope, { plan, entries });
 		return { plan, goal: next, resumed: false };
 	});
 }