oh-my-opencode 5.0.0-beta.8 → 5.0.0-beta.81

package/packages/omo-codex/plugin/components/ulw-loop/test/codex-goal-snapshot.test.ts

@@ -24,6 +24,24 @@ describe("parseCodexGoalSnapshot", () => {
 		expect(snapshot.status).toBe("active");
 	});
 
+	it("reads the objective from a title-bearing ulw-loop status goal", () => {
+		// given
+		const payload = {
+			id: "G002-goal-2-senpi-repo-audit-determine-wh",
+			title: "Audit the Senpi repository",
+			status: "in_progress",
+			successCriteria: [],
+		};
+
+		// when
+		const snapshot = parseCodexGoalSnapshot(payload);
+
+		// then
+		expect(snapshot.available).toBe(true);
+		expect(snapshot.objective).toBe("Audit the Senpi repository");
+		expect(snapshot.status).toBe("active");
+	});
+
 	it("ignores remaining token budget fields from goal snapshots", () => {
 		// given
 		const payload = { goal: { objective: "X", status: "active" }, remainingTokens: 123 };
@@ -85,10 +103,10 @@ describe("readCodexGoalSnapshotInput", () => {
 
 	it("reads from sample fixture path", async () => {
 		// given
-		const filePath = join(process.cwd(), "test", "fixtures", "codex-goal-snapshot.json");
+		const filePath = new URL("./fixtures/codex-goal-snapshot.json", import.meta.url);
 
 		// when
-		const snapshot = await readCodexGoalSnapshotInput(filePath);
+		const snapshot = await readCodexGoalSnapshotInput(filePath.pathname);
 
 		// then
 		expect(snapshot?.available).toBe(true);
@@ -102,6 +120,15 @@ describe("readCodexGoalSnapshotInput", () => {
 });
 
 describe("reconcileCodexGoalSnapshot", () => {
+	it("preserves objective whitespace in driver advice while normalizing comparison", () => {
+		const expectedObjective = "  exact   objective\nwith spacing  ";
+		const result = reconcileCodexGoalSnapshot(
+			parseCodexGoalSnapshot({ goal: { objective: "different", status: "active" } }),
+			{ expectedObjective },
+		);
+
+		expect(result.warnings[0]).toContain(`expected "${expectedObjective}"`);
+	});
 	it("returns ok=true when snapshot matches expected", () => {
 		// when
 		const reconciliation = reconcileCodexGoalSnapshot(
@@ -114,7 +141,7 @@ describe("reconcileCodexGoalSnapshot", () => {
 		expect(reconciliation.errors).toHaveLength(0);
 	});
 
-	it("reports error when objective mismatches", () => {
+	it("reports warning when objective mismatches", () => {
 		// when
 		const reconciliation = reconcileCodexGoalSnapshot(
 			{ available: true, objective: "X", status: "active", raw: null },
@@ -122,20 +149,70 @@ describe("reconcileCodexGoalSnapshot", () => {
 		);
 
 		// then
-		expect(reconciliation.ok).toBe(false);
-		expect(reconciliation.errors.length).toBeGreaterThan(0);
+		expect(reconciliation.ok).toBe(true);
+		expect(reconciliation.errors).toHaveLength(0);
+		expect(reconciliation.warnings.join(" ")).toContain("driver_objective_differs");
+		expect(reconciliation.nextActions).toEqual([]);
+		expect(reconciliation.unacknowledgedObjective).toBe("X");
+	});
+
+	it("#given the differing objective was acknowledged #when reconciled again #then it is silent", () => {
+		const reconciliation = reconcileCodexGoalSnapshot(
+			{ available: true, objective: " X  \n", status: "active", raw: null },
+			{ expectedObjective: "Y", acknowledgedObjectives: ["X"] },
+		);
+
+		expect(reconciliation.warnings).toEqual([]);
+		expect(reconciliation.nextActions).toEqual([]);
+		expect(reconciliation.unacknowledgedObjective).toBeUndefined();
+	});
+
+	it("#given no driver snapshot #when reconciled #then create_goal is a next action, not a warning", () => {
+		const reconciliation = reconcileCodexGoalSnapshot(null, { expectedObjective: "Y" });
+
+		expect(reconciliation.nextActions.join(" ")).toContain("create_goal");
+		expect(reconciliation.warnings).toEqual([]);
+	});
+
+	it("#given a completed or limited driver #when reconciled #then the advice is a next action", () => {
+		const completed = reconcileCodexGoalSnapshot(
+			{ available: true, objective: "Y", status: "complete", raw: null },
+			{ expectedObjective: "Y" },
+		);
+		const limited = reconcileCodexGoalSnapshot(
+			{ available: true, objective: "Y", status: "usage_limited", raw: null },
+			{ expectedObjective: "Y" },
+		);
+
+		expect(completed.nextActions.join(" ")).toContain("create_goal");
+		expect(limited.nextActions.join(" ")).toContain("/goal resume");
+		expect([...completed.warnings, ...limited.warnings]).toEqual([]);
+	});
+
+	it("accepts a parsable snapshot without objective as advisory", () => {
+		// when
+		const reconciliation = reconcileCodexGoalSnapshot(
+			{ available: true, status: "active", raw: { goal: { status: "active" } } },
+			{ expectedObjective: "X" },
+		);
+
+		// then
+		expect(reconciliation.ok).toBe(true);
+		expect(reconciliation.errors).toHaveLength(0);
 	});
 
-	it("reports error when status mismatches", () => {
+	it("accepts limited driver statuses", () => {
 		// when
 		const reconciliation = reconcileCodexGoalSnapshot(
-			{ available: true, objective: "X", status: "active", raw: null },
-			{ expectedObjective: "X", allowedStatuses: ["complete"] },
+			{ available: true, objective: "X", status: "budget_limited", raw: null },
+			{ expectedObjective: "X" },
 		);
 
 		// then
-		expect(reconciliation.ok).toBe(false);
-		expect(reconciliation.errors.length).toBeGreaterThan(0);
+		expect(reconciliation.ok).toBe(true);
+		expect(reconciliation.errors).toHaveLength(0);
+		expect(reconciliation.nextActions.join(" ")).toContain("/goal resume");
+		expect(reconciliation.warnings).toEqual([]);
 	});
 });
 
@@ -144,7 +221,7 @@ describe("formatCodexGoalReconciliation", () => {
 		// given
 		const reconciliation = reconcileCodexGoalSnapshot(
 			{ available: true, objective: "X", status: "active", raw: null },
-			{ expectedObjective: "Y", allowedStatuses: ["complete"] },
+			{ expectedObjective: "Y" },
 		);
 
 		// when

package/packages/omo-codex/plugin/components/ulw-loop/test/codex-hook.test.ts

@@ -242,7 +242,6 @@ describe("applyPreToolUseGoalBudgetGuard", () => {
 				permissionDecision: "deny",
 			},
 		});
-		expect(parsed.hookSpecificOutput.permissionDecisionReason).toContain("objective only");
 		expect(parsed.hookSpecificOutput.permissionDecisionReason).toContain("token_budget");
 		expect(parsed.hookSpecificOutput.permissionDecisionReason).toContain("unlimited");
 		expect(parsed.hookSpecificOutput.permissionDecisionReason).toContain("update_goal");
@@ -258,7 +257,6 @@ describe("applyPreToolUseGoalBudgetGuard", () => {
 		// then
 		const parsed = JSON.parse(output);
 		expect(parsed.hookSpecificOutput.permissionDecision).toBe("deny");
-		expect(parsed.hookSpecificOutput.permissionDecisionReason).toContain("objective only");
 		expect(parsed.hookSpecificOutput.permissionDecisionReason).toContain("update_goal");
 	});
 
@@ -272,7 +270,6 @@ describe("applyPreToolUseGoalBudgetGuard", () => {
 		// then
 		const parsed = JSON.parse(output);
 		expect(parsed.hookSpecificOutput.permissionDecision).toBe("deny");
-		expect(parsed.hookSpecificOutput.permissionDecisionReason).toContain("objective only");
 	});
 
 	it("#given create_goal omits token_budget #when PreToolUse runs #then it stays silent", () => {

package/packages/omo-codex/plugin/components/ulw-loop/test/fixtures/barrier.ts

@@ -0,0 +1,13 @@
+export function barrier() {
+	let resolve: () => void = () => {
+		throw new Error("barrier not initialized");
+	};
+	const promise = new Promise<void>((done, reject) => {
+		const timeout = setTimeout(() => reject(new Error("barrier timed out")), 5_000);
+		resolve = () => {
+			clearTimeout(timeout);
+			done();
+		};
+	});
+	return { promise, resolve };
+}

package/packages/omo-codex/plugin/components/ulw-loop/test/fixtures/cli-session.ts

@@ -0,0 +1,4 @@
+// Every CLI-level test runs inside one explicit session scope: the CLI refuses to
+// touch the unscoped .omo/ulw-loop root, so state and evidence live under this id.
+export const CLI_TEST_SESSION_ID = "cli-test";
+export const CLI_TEST_SCOPE = { sessionId: CLI_TEST_SESSION_ID } as const;

package/packages/omo-codex/plugin/components/ulw-loop/test/fixtures/commit-child.ts

@@ -0,0 +1,65 @@
+import { fork } from "node:child_process";
+import { join } from "node:path";
+
+const running = new Set<ReturnType<typeof childWriter>>();
+export async function cleanupWriters(): Promise<void> {
+	await Promise.all(
+		[...running].map(async (writer) => {
+			writer.child.kill("SIGKILL");
+			await writer.exited;
+		}),
+	);
+}
+export function childWriter(rootPath: string, mode: string, now = Date.now()) {
+	const child = fork(join(import.meta.dirname, "commit-writer.ts"), [rootPath, mode, String(now)], {
+		execPath: "bun",
+		execArgv: [],
+		stdio: ["ignore", "inherit", "inherit", "ipc"],
+	});
+	const pending = new Map<string, { resolve: () => void; reject: (error: Error) => void }>();
+	const seen = new Set<string>();
+	child.on("message", (message) => {
+		if (typeof message !== "string") return;
+		seen.add(message);
+		pending.get(message)?.resolve();
+	});
+	const exited = new Promise<number | null>((resolve, reject) => {
+		const timeout = setTimeout(() => {
+			child.kill("SIGKILL");
+			reject(new Error("child exit timed out"));
+		}, 15_000);
+		child.once("error", (error) => {
+			clearTimeout(timeout);
+			reject(error);
+		});
+		child.once("exit", (code) => {
+			clearTimeout(timeout);
+			running.delete(writer);
+			resolve(code);
+			for (const [name, waiter] of pending)
+				if (!seen.has(name)) waiter.reject(new Error(`child exited before ${name}: ${code}`));
+		});
+	});
+	const writer = {
+		child,
+		exited,
+		wait(name: string) {
+			if (seen.has(name)) return Promise.resolve();
+			return new Promise<void>((resolve, reject) => {
+				const timeout = setTimeout(() => reject(new Error(`IPC timeout: ${name}`)), 10_000);
+				pending.set(name, {
+					resolve: () => {
+						clearTimeout(timeout);
+						resolve();
+					},
+					reject: (error) => {
+						clearTimeout(timeout);
+						reject(error);
+					},
+				});
+			});
+		},
+	};
+	running.add(writer);
+	return writer;
+}

package/packages/omo-codex/plugin/components/ulw-loop/test/fixtures/commit-cli-qa.mjs

@@ -0,0 +1,76 @@
+import assert from "node:assert/strict";
+import { fork, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { withCommitHooks } from "../../dist/plan-commit.js";
+import { commit } from "../../dist/plan-commit.js";
+import { readLedger, readUlwLoopPlan, withUlwLoopMutationLock } from "../../dist/plan-io.js";
+const cli = resolve("dist/cli.js");
+const root = mkdtempSync(join(tmpdir(), "ulw-cli-qa-"));
+const legacyRoot = mkdtempSync(join(tmpdir(), "ulw-legacy-qa-"));
+const scope = { sessionId: "commit-log" };
+const dir = join(root, ".omo", "ulw-loop", scope.sessionId);
+const json = (path) => JSON.parse(readFileSync(path, "utf8"));
+function run(cwd, ...args) {
+	const argv = [...args, "--session-id", scope.sessionId, "--json"];
+	const result = spawnSync(process.execPath, [cli, ...argv], { cwd, encoding: "utf8", timeout: 15_000, env: { ...process.env, PI_SESSION_ID: "", CODEX_SESSION_ID: "", CODEX_THREAD_ID: "", OMO_ULW_LOOP_SESSION_ID: "" } });
+	console.log(`command=${process.execPath} ${cli} ${argv.map((arg) => JSON.stringify(arg)).join(" ")} cwd=${cwd}\n${result.stdout}${result.stderr}\nexit=${result.status}`);
+	assert.equal(result.status, 0);
+	return JSON.parse(result.stdout);
+}
+try {
+	run(root, "create-goals", "--brief", "Build durable state");
+	const original = json(join(dir, "goals.json"));
+	assert.equal(run(root, "status").plan.revision, 1);
+	rmSync(join(dir, "goals.json"));
+	assert.equal(run(root, "status").plan.revision, 1);
+	assert.equal(existsSync(join(dir, "goals.json")), false);
+	const goal = original.goals[0];
+	run(root, "record-evidence", "--goal-id", goal.id, "--criterion-id", goal.successCriteria[0].id, "--status", "pass", "--evidence", "Observed real CLI publication");
+	assert.equal(json(join(dir, "revisions", "00000002.json")).ledger[0].kind, "evidence_captured");
+	assert.equal(json(join(dir, "goals.json")).revision, 2);
+	console.log("QA=PASS log-only status is read-only; CLI evidence repairs and commits plan plus audit");
+	const clock = { now: () => 0, schedule: () => { throw new Error("Unexpected scheduler use"); } };
+	await assert.rejects(withCommitHooks({ beforeCommit: async () => {
+		const child = fork(resolve("test/fixtures/commit-writer.ts"), [root, "write", "201"], { execPath: "bun", execArgv: [], stdio: ["ignore", "inherit", "inherit", "ipc"] });
+		const exit = await new Promise((done, reject) => {
+			const timeout = setTimeout(() => { child.kill("SIGKILL"); reject(new Error("writer B timed out")); }, 10_000);
+			child.once("error", (error) => { clearTimeout(timeout); reject(error); });
+			child.once("exit", (code) => { clearTimeout(timeout); done(code); });
+		});
+		assert.equal(exit, 0);
+	} }, () => withUlwLoopMutationLock(root, scope, async () => {
+		const plan = await readUlwLoopPlan(root, scope);
+		plan.brief = "zombie";
+		await commit(root, scope, { plan, entries: [{ at: "A", kind: "goal_added", message: "A" }] });
+	}, { clock, leaseMs: 200, heartbeatMs: 0 })), { code: "ULW_LOOP_LOCK_LOST" });
+	assert.equal(readLedger(root, scope).at(-1).message, "B");
+	assert.equal(readLedger(root, scope).some((entry) => entry.message === "A"), false);
+	assert.deepEqual(readdirSync(join(dir, "revisions")), ["00000001.json", "00000002.json", "00000003.json"]);
+	console.log(`QA=PASS real fork zombie fencing ULW_LOOP_LOCK_LOST record=${JSON.stringify(json(join(dir, "revisions", "00000003.json")))}`);
+	run(root, "create-goals", "--brief", "Replacement brief", "--force");
+	const recreated = json(join(dir, "goals.json"));
+	assert.equal(recreated.revision, 4);
+	assert.equal(recreated.ledgerResetRevision, 4);
+	assert.equal(readFileSync(join(dir, "brief.md"), "utf8"), recreated.brief);
+	assert.equal(readLedger(root, scope).length, 1);
+	console.log("QA=PASS force recreation retains revision history and resets the logical audit");
+	const legacyDir = join(legacyRoot, ".omo", "ulw-loop", scope.sessionId);
+	mkdirSync(legacyDir, { recursive: true });
+	delete original.revision; delete original.brief; delete original.ledgerResetRevision;
+	writeFileSync(join(legacyDir, "goals.json"), JSON.stringify(original));
+	writeFileSync(join(legacyDir, "brief.md"), "Legacy brief\n");
+	writeFileSync(join(legacyDir, "ledger.jsonl"), '{"at":"legacy","kind":"goal_started"}\n');
+	assert.equal(run(legacyRoot, "status").plan.revision ?? 0, 0);
+	assert.equal(existsSync(join(legacyDir, "revisions")), false);
+	run(legacyRoot, "add-goal", "--title", "Extra", "--objective", "Verify legacy hydration");
+	assert.equal(json(join(legacyDir, "revisions", "00000001.json")).plan.brief, "Legacy brief\n");
+	assert.equal(readLedger(legacyRoot, scope)[0].id, "legacy-1");
+	console.log("QA=PASS legacy CLI status and first commit preserve brief and legacy audit");
+} finally {
+	rmSync(root, { recursive: true, force: true });
+	rmSync(legacyRoot, { recursive: true, force: true });
+	assert.equal(existsSync(root) || existsSync(legacyRoot), false);
+	console.log(`cleanup=REMOVED ${root} ${legacyRoot}; real home directories not accessed by this driver`);
+}

package/packages/omo-codex/plugin/components/ulw-loop/test/fixtures/commit-crash.ts

@@ -0,0 +1,23 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { type UlwLoopScope, ulwLoopDir } from "../../src/paths.js";
+import { createUlwLoopPlan } from "../../src/plan-crud.js";
+
+export async function seedCrash(root: string, scope: UlwLoopScope, first: boolean) {
+	const dir = ulwLoopDir(root, scope);
+	const plan = await createUlwLoopPlan(root, { brief: "original" }, scope);
+	const next = { ...plan, revision: (plan.revision ?? 0) + 1, brief: "committed\n", codexObjective: "committed" };
+	mkdirSync(join(dir, "revisions"), { recursive: true });
+	writeFileSync(
+		join(dir, "revisions", `${String(next.revision).padStart(8, "0")}.json`),
+		JSON.stringify({
+			version: 1,
+			revision: next.revision,
+			plan: next,
+			ledger: [{ at: "now", kind: "goal_added", revision: next.revision, id: `${next.revision}-0` }],
+		}),
+	);
+	if (first) await rm(join(dir, "goals.json"));
+	return next;
+}

package/packages/omo-codex/plugin/components/ulw-loop/test/fixtures/commit-mutations.mjs

@@ -0,0 +1,58 @@
+// Run only in an isolated remote test checkout. Each mutant is restored before the next.
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+
+function replace(source, before, after) {
+	if (source.split(before).length !== 2) throw new Error(`Mutation anchor is not unique: ${before}`);
+	return source.replace(before, after);
+}
+const publication = '(hooks.getStore()?.link ?? linkSync)(temp, join(dir, "revisions", `${String(next).padStart(8, "0")}.json`));';
+const logTest = "test/plan-commit-log.test.ts";
+const recoveryTest = "test/plan-commit-recovery.test.ts";
+const mutations = [
+	{ name: "heartbeat-no-refresh", file: "src/state-lock.ts", test: "test/state-lock.test.ts", pattern: "\\(3\\)", change: (s) => replace(s, "holder.record.leaseUntil = clock.now()", "holder.record.leaseUntil ??= clock.now()") },
+	{ name: "heartbeat-by-path", file: "src/state-lock.ts", test: "test/state-lock.test.ts", pattern: "\\(2\\)", change: (s) => 'import { writeFileSync } from "node:fs";\n' + replace(s, "writeRecord(holder);\n\t\t\tschedule();", "writeFileSync(lockPath, JSON.stringify(holder.record));\n\t\t\tschedule();") },
+	{ name: "rename-over-goals", file: "src/plan-commit.ts", test: logTest, pattern: "B wins write", change: (s) => replace(s, publication, `if (next === 1) { ${publication} } else { writeFileSync(temp, JSON.stringify(record.plan)); renameSync(temp, join(dir, "goals.json")); }`) },
+	{ name: "delete-published-record", file: "src/plan-commit.ts", test: logTest, pattern: "B wins write", change: (s) => replace(s, "await materialize(dir);", 'await materialize(dir);\n if (next > 1) rmSync(join(dir, "revisions", `${String(next).padStart(8, "0")}.json`));') },
+	{ name: "next-from-directory", file: "src/plan-commit.ts", test: logTest, pattern: "\\(6\\)", change: (s) => replace(s, "const next = (plan.revision ?? 0) + 1;", "const next = Math.max(plan.revision ?? 0, ...readRecords(dir).map((record) => record.revision)) + 1;") },
+	{ name: "no-holder-retry", file: "src/plan-io.ts", test: logTest, pattern: "\\(6\\)", change: (s) => replace(s, "if (attempt !== 0) throw error;", "throw error;") },
+	{ name: "no-plan-reconciliation", file: "src/plan-log.ts", test: logTest, pattern: "\\(7a\\)", change: (s) => replace(s, "const latest = readNewestRecord(dir);", "const latest = cached === undefined ? readNewestRecord(dir) : undefined;") },
+	{ name: "no-ledger-reconciliation", file: "src/ledger.ts", test: logTest, pattern: "\\(7a\\)", change: (s) => replace(s, "for (const record of readRecords(dir))", "for (const record of [])") },
+	{ name: "cache-only-existence", file: "src/plan-log.ts", test: recoveryTest, pattern: "\\(7b\\)", change: (s) => replace(s, 'return existsSync(join(dir, "goals.json")) || logNames(dir).length > 0;', 'return existsSync(join(dir, "goals.json"));') },
+	{ name: "in-place-ledger-append",  file: "src/plan-commit.ts", test: logTest, pattern: "\\(7c\\)", change: (s) => {
+		const start = s.indexOf("export async function materialize(dir:");
+		if (start < 0) throw new Error("materializer not found");
+		const body = replace(s.slice(start), 'const temp = join(dir, "tmp", `${process.pid}-${randomUUID()}-${name}`);', 'const temp = name === "ledger.jsonl" && readRecords(dir).length > 1 ? join(dir, name) : join(dir, "tmp", `${process.pid}-${randomUUID()}-${name}`);');
+		return 'import { appendFile } from "node:fs/promises";\n' + s.slice(0, start) + replace(body, 'await writeViewFile(temp, content);', 'if (name === "ledger.jsonl" && readRecords(dir).length > 1) await (hooks.getStore()?.writeView ?? appendFile)(temp, content); else await writeViewFile(temp, content);');
+	} },
+	{ name: "brief-before-publication", file: "src/plan-crud.ts", test: recoveryTest, pattern: "\\(9\\)", change: (s) => replace(replace(s, 'import { beforePlanMutation, commit }', 'import { beforePlanMutation, commit, writeViewFile }'), "await beforePlanMutation();", 'await beforePlanMutation();\n await writeViewFile(`${repoRoot}/${plan.briefPath}`, plan.brief ?? "");') },
+	{ name: "steering-audit-outside-record", file: "src/steering.ts", test: logTest, pattern: "\\(11\\)", change: (s) => replace(s, "await commit(repoRoot, scope, { plan: next, entries });", 'await commit(repoRoot, scope, { plan: next, entries: [] });\n await (await import("node:fs/promises")).appendFile(`${repoRoot}/${next.ledgerPath}`, entries.map((entry) => JSON.stringify(entry)).join("\\n") + "\\n");') },
+	{ name: "copy-fallback", file: "src/plan-commit.ts", test: logTest, pattern: "\\(12\\)", change: (s) => 'import { copyFileSync } from "node:fs";\n' + replace(s, publication, `try { ${publication} } catch (error) { if (hasCode(error, "EPERM")) copyFileSync(temp, join(dir, "revisions", \`\${String(next).padStart(8, "0")}.json\`)); else throw error; }`) },
+];
+const digest = (content) => createHash("sha256").update(content).digest("hex");
+let failures = 0;
+for (const mutation of mutations) {
+	const original = readFileSync(mutation.file, "utf8");
+	console.log(`\n## MUTATION ${mutation.name}\nfile=${mutation.file}\nbefore_sha256=${digest(original)}`);
+	try {
+		writeFileSync(mutation.file, mutation.change(original));
+		const args = ["run", "test", "--", mutation.test, "-t", mutation.pattern];
+		console.log(`command=bun ${args.map((arg) => JSON.stringify(arg)).join(" ")}`);
+		const result = spawnSync("bun", args, { encoding: "utf8", timeout: 60_000 });
+		const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+		console.log(output);
+		console.log(`mutation_exit=${result.status}`);
+		if (result.status !== 1 || !/[1-9]\d* failed/.test(output.replace(/\x1b\[[0-9;]*m/g, "")) || !output.includes("AssertionError")) {
+			failures += 1;
+			console.log(`PROOF=FAILED ${mutation.name}`);
+		} else console.log(`PROOF=RED ${mutation.name}`);
+	} finally {
+		writeFileSync(mutation.file, original);
+		const restored = readFileSync(mutation.file, "utf8");
+		if (restored !== original) throw new Error(`Failed to restore ${mutation.file}`);
+		console.log(`restored_sha256=${digest(restored)} cleanup=RESTORED`);
+	}
+}
+console.log(`mutation_proofs=${mutations.length} failed_proofs=${failures}`);
+process.exitCode = failures === 0 ? 0 : 1;

package/packages/omo-codex/plugin/components/ulw-loop/test/fixtures/commit-writer.ts

@@ -0,0 +1,65 @@
+import { writeFile } from "node:fs/promises";
+import { commit, withCommitHooks } from "../../src/plan-commit.js";
+import { createUlwLoopPlan } from "../../src/plan-crud.js";
+import { readUlwLoopPlan, withMutationLockOptions, withUlwLoopMutationLock } from "../../src/plan-io.js";
+import { steerUlwLoop } from "../../src/steering.js";
+import { leaseClock } from "./lease-clock.js";
+
+const root = process.argv[2];
+const mode = process.argv[3];
+if (root === undefined) throw new Error("root required");
+const scope = { sessionId: "commit-log" };
+function barrier(name: string): Promise<void> {
+	return new Promise((resolve, reject) => {
+		const timeout = setTimeout(() => reject(new Error(`barrier timed out: ${name}`)), 10_000);
+		process.once("message", () => {
+			clearTimeout(timeout);
+			resolve();
+		});
+		process.send?.(name);
+	});
+}
+let calls = 0;
+await withMutationLockOptions({ clock: leaseClock(Number(process.argv[4])), heartbeatMs: 0, timeoutMs: 0 }, () =>
+	withCommitHooks(
+		{
+			beforeCommit: async () => {
+				calls += 1;
+				if (mode === "mirror" && calls === 1) await barrier("before");
+			},
+			afterCommit: async () => {
+				if (mode === "accepted" || mode === "rejected") await barrier("linked");
+			},
+			writeView: async (path, content) => {
+				if (mode === "partial" && path.endsWith("ledger.jsonl")) {
+					await writeFile(path, content.slice(0, Math.max(1, Math.floor(content.length / 2))));
+					await barrier("partial");
+				}
+				await writeFile(path, content);
+			},
+		},
+		async () => {
+			if (mode === "force") await createUlwLoopPlan(root, { brief: "B\n", force: true }, scope);
+			else if (mode === "accepted" || mode === "rejected")
+				await steerUlwLoop(
+					root,
+					{
+						kind: "annotate_ledger",
+						source: "cli",
+						evidence: mode === "rejected" ? "" : "observed",
+						rationale: "audit",
+						idempotencyKey: "crash-key",
+					},
+					scope,
+				);
+			else
+				await withUlwLoopMutationLock(root, scope, async () => {
+					const plan = await readUlwLoopPlan(root, scope);
+					plan.codexObjective = `${plan.codexObjective}|B`;
+					await commit(root, scope, { plan, entries: [{ at: "B", kind: "goal_added", message: "B" }] });
+				});
+		},
+	),
+);
+process.send?.("done");
+process.disconnect?.();

package/packages/omo-codex/plugin/components/ulw-loop/test/fixtures/lease-clock.ts

@@ -0,0 +1,23 @@
+export function leaseClock(initial = 0) {
+	let now = initial;
+	const tasks = new Set<{ at: number; fn: () => void }>();
+	return {
+		now: () => now,
+		schedule(fn: () => void, ms: number) {
+			const task = { at: now + ms, fn };
+			tasks.add(task);
+			return { unref() {}, cancel: () => tasks.delete(task) };
+		},
+		advance(ms: number) {
+			const end = now + ms;
+			for (;;) {
+				const next = [...tasks].filter((task) => task.at <= end).sort((a, b) => a.at - b.at)[0];
+				if (next === undefined) break;
+				now = next.at;
+				tasks.delete(next);
+				next.fn();
+			}
+			now = end;
+		},
+	};
+}

package/packages/omo-codex/plugin/components/ulw-loop/test/fixtures/quality-gate-builder.ts

@@ -1,8 +1,11 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
+import { reviewerRolesFor, type UlwLoopToolkitSurface } from "../../src/surface.js";
+import { CLI_TEST_SESSION_ID } from "./cli-session.js";
+
 // v2 evidence layout: artifacts must live inside the goal's current attempt dir
-export function qaDirFor(goalId: string, attempt = 1, sessionId = "session"): string {
+export function qaDirFor(goalId: string, attempt = 1, sessionId = CLI_TEST_SESSION_ID): string {
 	return `.omo/evidence/ulw/${sessionId}/${goalId}/a${attempt}`;
 }
 
@@ -25,13 +28,15 @@ export async function qualityGateJson(
 	repoRoot: string,
 	cliArtifactPath?: string,
 	goalId = "G001-finished",
+	surface: UlwLoopToolkitSurface = "lazycodex",
 ): Promise<string> {
+	const roles = reviewerRolesFor(surface);
 	const qaDir = qaDirFor(goalId);
 	await writeQualityGateArtifacts(repoRoot, qaDir);
 	const cliPath = cliArtifactPath ?? `${qaDir}/cli-pass.txt`;
 	return JSON.stringify({
 		codeReview: {
-			by: "lazycodex-code-reviewer",
+			by: roles.codeReview,
 			recommendation: "APPROVE",
 			codeQualityStatus: "CLEAR",
 			reportPath: `${qaDir}/code-review.md`,
@@ -39,7 +44,7 @@ export async function qualityGateJson(
 			blockers: [],
 		},
 		manualQa: {
-			by: "lazycodex-qa-executor",
+			by: roles.manualQa,
 			status: "passed",
 			evidence: "Ran CLI checkpoint validation with artifact-backed evidence.",
 			surfaceEvidence: [
@@ -78,7 +83,7 @@ export async function qualityGateJson(
 			],
 		},
 		gateReview: {
-			by: "lazycodex-gate-reviewer",
+			by: roles.gateReview,
 			recommendation: "APPROVE",
 			reportPath: `${qaDir}/gate-review.md`,
 			evidence: "Verified all criteria and artifact evidence.",

package/packages/omo-codex/plugin/components/ulw-loop/test/guided-recovery.test.ts

@@ -0,0 +1,67 @@
+import { mkdir, mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+import { checkpointUlwLoop } from "../src/checkpoint.js";
+import { ulwLoopDir } from "../src/paths.js";
+import { readUlwLoopPlan } from "../src/plan-io.js";
+import { UlwLoopError } from "../src/types.js";
+import { goal, passGoal, plan, repoWith } from "./fixtures/checkpoint-builders.js";
+
+async function captureError(action: () => Promise<unknown>): Promise<UlwLoopError> {
+	try {
+		await action();
+	} catch (error) {
+		expect(error).toBeInstanceOf(UlwLoopError);
+		if (error instanceof UlwLoopError) return error;
+		throw error;
+	}
+	throw new Error("Expected UlwLoopError");
+}
+
+describe("#given a codex goal snapshot whose objective differs from the plan", () => {
+	it("#when checkpoint reconciles it #then it succeeds with driver advice", async () => {
+		const repo = await repoWith(plan([passGoal("G001"), goal({ id: "G002", status: "pending" })]));
+		const result = await checkpointUlwLoop(repo, {
+			goalId: "G001",
+			status: "complete",
+			evidence: "work complete",
+			codexGoalJson: JSON.stringify({ goal: { objective: "wrong objective", status: "budget_limited" } }),
+		});
+		expect(result.nextActions.join(" ")).toContain("/goal resume");
+		expect(result.warnings.join(" ")).toContain("driver_objective_differs");
+	});
+});
+
+describe("#given no ulw-loop plan on disk", () => {
+	it("#when the plan is read #then the error names the exact create-goals bootstrap command", async () => {
+		const repo = await mkdtemp(join(tmpdir(), "ug-guided-plan-"));
+
+		const error = await captureError(() => readUlwLoopPlan(repo));
+
+		expect(error.code).toBe("ULW_LOOP_PLAN_MISSING");
+		expect(error.message).toContain('omo-agent-toolkit ulw-loop create-goals --brief "<brief>" --json');
+	});
+
+	it("#when sibling session dirs exist #then the error lists the existing session ids", async () => {
+		const repo = await mkdtemp(join(tmpdir(), "ug-guided-plan-"));
+		await mkdir(join(ulwLoopDir(repo), "session-alpha"), { recursive: true });
+		await mkdir(join(ulwLoopDir(repo), "session-beta"), { recursive: true });
+
+		const error = await captureError(() => readUlwLoopPlan(repo, { sessionId: "session-gamma" }));
+
+		expect(error.code).toBe("ULW_LOOP_PLAN_MISSING");
+		expect(error.message).toContain("session-alpha");
+		expect(error.message).toContain("session-beta");
+		expect(error.details).toMatchObject({ existingSessionIds: ["session-alpha", "session-beta"] });
+	});
+
+	it("#when no session dirs exist #then the error lists no session ids", async () => {
+		const repo = await mkdtemp(join(tmpdir(), "ug-guided-plan-"));
+
+		const error = await captureError(() => readUlwLoopPlan(repo, { sessionId: "session-gamma" }));
+
+		expect(error.details?.["existingSessionIds"]).toBeUndefined();
+	});
+});