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

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

@@ -0,0 +1,310 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { mkdtemp, rm, utimes, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { ULW_LOOP_LOCK_TIMEOUT_CODE, withStateLock, withStateLockSync } from "../src/state-lock.ts";
+import { UlwLoopError } from "../src/types.ts";
+
+let workDir: string;
+let lockPath: string;
+const children: ChildProcess[] = [];
+
+beforeEach(async () => {
+	workDir = await mkdtemp(join(tmpdir(), "ulw-state-lock-"));
+	lockPath = join(workDir, ".omo", "ulw-loop", "s1", ".state.lock");
+});
+
+afterEach(async () => {
+	for (const child of children.splice(0)) {
+		if (child.exitCode === null) child.kill("SIGKILL");
+	}
+	await rm(workDir, { recursive: true, force: true });
+});
+
+const HOLDER_SCRIPT = `
+const fs = require("node:fs");
+const [lockPath, holdMs] = process.argv.slice(1);
+fs.mkdirSync(require("node:path").dirname(lockPath), { recursive: true });
+const fd = fs.openSync(lockPath, "wx");
+fs.writeSync(fd, JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString(), token: "holder-" + process.pid }));
+fs.closeSync(fd);
+process.stdout.write("HELD\\n");
+setTimeout(() => {
+	fs.writeFileSync(lockPath + ".released", "");
+	fs.unlinkSync(lockPath);
+}, Number(holdMs));
+`;
+
+interface ForeignHolder {
+	readonly released: () => boolean;
+}
+
+// A real second process holds the lock file the way another CLI invocation
+// would. Release is observed through a marker file so the check also works
+// while the synchronous acquirer has the event loop blocked.
+function spawnForeignHolder(holdMs: number): Promise<ForeignHolder> {
+	return new Promise((resolve, reject) => {
+		const child = spawn(process.execPath, ["-e", HOLDER_SCRIPT, lockPath, String(holdMs)], {
+			stdio: ["ignore", "pipe", "inherit"],
+		});
+		children.push(child);
+		let output = "";
+		child.stdout.setEncoding("utf8");
+		child.stdout.on("data", (chunk: string) => {
+			output += chunk;
+			if (output.includes("HELD")) resolve({ released: () => existsSync(`${lockPath}.released`) });
+		});
+		child.once("error", reject);
+	});
+}
+
+function spawnExitedProcess(): Promise<number> {
+	return new Promise((resolve, reject) => {
+		const child = spawn(process.execPath, ["-e", "process.exit(0)"], { stdio: "ignore" });
+		child.once("exit", () => {
+			if (child.pid === undefined) reject(new Error("child had no pid"));
+			else resolve(child.pid);
+		});
+		child.once("error", reject);
+	});
+}
+
+function ownerPid(): number {
+	const record: unknown = JSON.parse(readFileSync(lockPath, "utf8"));
+	if (typeof record !== "object" || record === null || !("pid" in record) || typeof record.pid !== "number") {
+		throw new Error("lock record has no pid");
+	}
+	return record.pid;
+}
+
+function manualClock() {
+	let now = Date.now();
+	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;
+		},
+	};
+}
+
+describe("#given lease-based ownership", () => {
+	it("#when (1) a live owner's lease expired #then an async waiter reclaims it", async () => {
+		const clock = manualClock();
+		mkdirSync(join(workDir, ".omo", "ulw-loop", "s1"), { recursive: true });
+		await writeFile(
+			lockPath,
+			JSON.stringify({
+				pid: process.pid,
+				token: "expired",
+				createdAt: new Date().toISOString(),
+				leaseUntil: clock.now() - 1,
+			}),
+		);
+		await expect(withStateLock(lockPath, async () => "acquired", { clock, leaseMs: 90, timeoutMs: 0 })).resolves.toBe(
+			"acquired",
+		);
+	});
+
+	it("#when (2) reclaimed while owner alive #then its heartbeat never overwrites or recreates the successor path", async () => {
+		const clock = manualClock();
+		await withStateLock(
+			lockPath,
+			async () => {
+				const initial = JSON.parse(readFileSync(lockPath, "utf8"));
+				expect(initial.leaseUntil).toBe(clock.now() + 90);
+				await withStateLock(
+					lockPath,
+					async () => {
+						const successor = readFileSync(lockPath, "utf8");
+						clock.advance(30);
+						expect(readFileSync(lockPath, "utf8")).toBe(successor);
+					},
+					{ leaseMs: 900, heartbeatMs: 0, timeoutMs: 0, clock: { ...clock, now: () => clock.now() + 91 } },
+				);
+				clock.advance(30);
+				expect(existsSync(lockPath)).toBe(false);
+			},
+			{ clock, leaseMs: 90 },
+		);
+	});
+
+	it("#when (3) the clock passes the original lease #then a refreshing holder cannot be reclaimed", async () => {
+		const clock = manualClock();
+		await withStateLock(
+			lockPath,
+			async () => {
+				clock.advance(120);
+				await expect(withStateLock(lockPath, async () => "stolen", { clock, timeoutMs: 0 })).rejects.toMatchObject({
+					code: ULW_LOOP_LOCK_TIMEOUT_CODE,
+				});
+			},
+			{ clock, leaseMs: 90 },
+		);
+	});
+
+	it("#when acquisition hands off to its body #then ownership uses the acquired token rather than rereading a successor", async () => {
+		await withStateLock(lockPath, async (token: string) => {
+			expect(token).toBe(JSON.parse(readFileSync(lockPath, "utf8")).token);
+		});
+	});
+
+	it("#when (4) a synchronous holder runs #then it writes a lease-less record", () => {
+		withStateLockSync(lockPath, () => {
+			expect(JSON.parse(readFileSync(lockPath, "utf8"))).not.toHaveProperty("leaseUntil");
+		});
+	});
+});
+
+describe("withStateLock", () => {
+	describe("#given a lock held by another live process", () => {
+		it("#when acquiring #then it waits for that process to release before running the body", async () => {
+			const holder = await spawnForeignHolder(300);
+
+			const observedReleaseFirst = await withStateLock(lockPath, async () => holder.released(), {
+				timeoutMs: 5_000,
+			});
+
+			expect(observedReleaseFirst).toBe(true);
+			expect(existsSync(lockPath)).toBe(false);
+		});
+
+		it("#when the holder outlives the timeout #then it fails closed without running the body", async () => {
+			await spawnForeignHolder(5_000);
+			let bodyRan = false;
+
+			const attempt = withStateLock(
+				lockPath,
+				async () => {
+					bodyRan = true;
+				},
+				{ timeoutMs: 150 },
+			);
+
+			await expect(attempt).rejects.toMatchObject({ code: ULW_LOOP_LOCK_TIMEOUT_CODE });
+			await expect(attempt).rejects.toBeInstanceOf(UlwLoopError);
+			expect(bodyRan).toBe(false);
+			expect(existsSync(lockPath)).toBe(true);
+		});
+	});
+
+	describe("#given a lock left behind by a process that is gone", () => {
+		it("#when acquiring #then the stale lock is reclaimed immediately", async () => {
+			const deadPid = await spawnExitedProcess();
+			mkdirSync(join(workDir, ".omo", "ulw-loop", "s1"), { recursive: true });
+			await writeFile(
+				lockPath,
+				JSON.stringify({ pid: deadPid, createdAt: new Date().toISOString(), token: "gone" }),
+			);
+
+			const seenOwner = await withStateLock(lockPath, async () => ownerPid(), { timeoutMs: 1_000 });
+
+			expect(seenOwner).toBe(process.pid);
+		});
+
+		it("#when a legacy record without a token is young #then it is treated as mid-write and waited on, not stolen", async () => {
+			mkdirSync(join(workDir, ".omo", "ulw-loop", "s1"), { recursive: true });
+			await writeFile(lockPath, JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }));
+
+			const attempt = withStateLock(lockPath, async () => "unreachable", { timeoutMs: 150, staleMs: 60_000 });
+
+			await expect(attempt).rejects.toMatchObject({ code: ULW_LOOP_LOCK_TIMEOUT_CODE });
+			expect(existsSync(lockPath)).toBe(true);
+		});
+	});
+
+	describe("#given a live holder whose lock is older than staleMs", () => {
+		it("#when acquiring #then age alone never reclaims it and the waiter fails closed", async () => {
+			await spawnForeignHolder(5_000);
+			const holderPid = ownerPid();
+			const twoMinutesAgo = new Date(Date.now() - 120_000);
+			await utimes(lockPath, twoMinutesAgo, twoMinutesAgo);
+			let bodyRan = false;
+
+			const attempt = withStateLock(
+				lockPath,
+				async () => {
+					bodyRan = true;
+				},
+				{ timeoutMs: 200, staleMs: 60_000 },
+			);
+
+			await expect(attempt).rejects.toMatchObject({ code: ULW_LOOP_LOCK_TIMEOUT_CODE });
+			expect(bodyRan).toBe(false);
+			expect(ownerPid()).toBe(holderPid);
+		});
+	});
+
+	describe("#given the lock changed hands while the body ran", () => {
+		it("#when the original owner releases #then it leaves the successor's lock in place", async () => {
+			const foreign = JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString(), token: "successor" });
+
+			await withStateLock(lockPath, async () => {
+				await writeFile(lockPath, foreign);
+			});
+
+			expect(existsSync(lockPath)).toBe(true);
+			expect(readFileSync(lockPath, "utf8")).toBe(foreign);
+		});
+
+		it("#when the record is unreadable but older than staleMs #then it is reclaimed", async () => {
+			mkdirSync(join(workDir, ".omo", "ulw-loop", "s1"), { recursive: true });
+			await writeFile(lockPath, "not json");
+			const twoMinutesAgo = new Date(Date.now() - 120_000);
+			await utimes(lockPath, twoMinutesAgo, twoMinutesAgo);
+
+			const seenOwner = await withStateLock(lockPath, async () => ownerPid(), {
+				timeoutMs: 1_000,
+				staleMs: 60_000,
+			});
+
+			expect(seenOwner).toBe(process.pid);
+		});
+	});
+
+	describe("#given the body throws", () => {
+		it("#when it rejects #then the lock is released and the error propagates", async () => {
+			const failure = withStateLock(lockPath, async () => {
+				throw new Error("body exploded");
+			});
+
+			await expect(failure).rejects.toThrow("body exploded");
+			expect(existsSync(lockPath)).toBe(false);
+		});
+	});
+});
+
+describe("withStateLockSync", () => {
+	it("#given a lock held by another live process #when acquiring #then it blocks until release", async () => {
+		const holder = await spawnForeignHolder(300);
+
+		const observedReleaseFirst = withStateLockSync(lockPath, () => holder.released(), { timeoutMs: 5_000 });
+
+		expect(observedReleaseFirst).toBe(true);
+		expect(existsSync(lockPath)).toBe(false);
+	});
+
+	it("#given the holder outlives the timeout #when acquiring #then it throws the timeout error", async () => {
+		await spawnForeignHolder(5_000);
+
+		expect(() => withStateLockSync(lockPath, () => "unreachable", { timeoutMs: 150 })).toThrow(
+			expect.objectContaining({ code: ULW_LOOP_LOCK_TIMEOUT_CODE }),
+		);
+	});
+});

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

@@ -0,0 +1,133 @@
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runInNewContext } from "node:vm";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { ulwLoopDir } from "../src/paths.js";
+import { writePlan } from "../src/plan-io.js";
+import {
+	type CheckpointArgs,
+	type CreateGoalsArgs,
+	createAgentToolkit,
+	type RecordEvidenceArgs,
+	type RecordReviewBlockersArgs,
+	type ToolkitSurface,
+} from "../src/sdk.js";
+import type { UlwLoopPlan } from "../src/types.js";
+import { criterion, goal, plan } from "./fixtures/checkpoint-builders.js";
+
+const scope = { sessionId: "surface-test" };
+const surfaces: ToolkitSurface[] = ["omo-senpi", "lazycodex"];
+let cwd: string;
+
+beforeEach(async () => {
+	cwd = await mkdtemp(join(tmpdir(), "ulw-surface-"));
+});
+afterEach(async () => {
+	await rm(cwd, { recursive: true, force: true });
+});
+
+interface Scenario {
+	readonly name: string;
+	readonly plan: UlwLoopPlan;
+	readonly method: string;
+	readonly args:
+		| CreateGoalsArgs
+		| RecordEvidenceArgs
+		| CheckpointArgs
+		| Omit<RecordReviewBlockersArgs, "codexGoalJson">;
+	readonly cli: string;
+}
+
+const scenarios: Scenario[] = [
+	{
+		name: "no goals",
+		plan: plan([]),
+		method: "createGoals",
+		args: { brief: "<brief>" },
+		cli: 'omo-agent-toolkit ulw-loop create-goals --brief "<brief>" --json',
+	},
+	{
+		name: "unresolved criteria",
+		plan: plan([goal({ successCriteria: [criterion("C001", "pass"), criterion("C002", "pending")] })]),
+		method: "recordEvidence",
+		args: { goalId: "G001", criterionId: "<id>", status: "pass", evidence: "<observable proof>" },
+		cli: 'omo-agent-toolkit ulw-loop record-evidence --goal-id G001 --criterion-id <id> --status pass --evidence "<observable proof>"',
+	},
+	{
+		name: "a passing non-final goal",
+		plan: plan([goal(), goal({ id: "G002", status: "pending" })]),
+		method: "checkpoint",
+		args: { goalId: "G001", status: "complete", evidence: "<proof>" },
+		cli: "omo-agent-toolkit ulw-loop checkpoint --goal-id G001 --status complete --evidence \"<proof>\" --codex-goal-json '<get_goal json>'",
+	},
+	{
+		name: "a passing final goal",
+		plan: plan([goal()]),
+		method: "checkpoint",
+		args: { goalId: "G001", printTemplate: true },
+		cli: "checkpoint --print-template",
+	},
+	{
+		name: "a review-blocked goal",
+		plan: plan([goal({ status: "review_blocked" })]),
+		method: "recordReviewBlockers",
+		args: { goalId: "G001", title: "<title>", objective: "<objective>", evidence: "<verdict>" },
+		cli: 'omo-agent-toolkit ulw-loop record-review-blockers --goal-id G001 --title "<title>" --objective "<objective>" --evidence "<verdict>" --codex-goal-json \'<get_goal json>\'',
+	},
+];
+
+function sdkArgs(text: string, method: string): unknown {
+	const snippet = text.match(new RegExp(`agentToolkit\\.${method}\\([^\x60]*\\)`))?.[0];
+	expect(snippet).toBeDefined();
+	if (snippet === undefined) throw new Error(`Missing SDK call: ${method}`);
+	return runInNewContext(snippet, { agentToolkit: { [method]: (args: unknown) => args } });
+}
+
+for (const surface of surfaces) {
+	describe(`#given the ${surface} SDK surface`, () => {
+		it.each(scenarios)("#when status reads $name #then its action uses the calling surface", async (scenario) => {
+			await mkdir(ulwLoopDir(cwd, scope), { recursive: true });
+			await writePlan(cwd, { ...scenario.plan, evidenceLayoutVersion: 2 }, scope);
+			const response = await createAgentToolkit({ cwd, ...scope, surface }).status();
+			if (!response.ok) throw new Error(response.error.message);
+
+			expect(response.nextActions).toEqual(response.result.nextActions);
+			const actions = response.nextActions.join("\n");
+			if (surface === "lazycodex") {
+				expect(actions).toContain(scenario.cli);
+				expect(actions).not.toContain("agentToolkit.");
+				return;
+			}
+			expect(actions).not.toMatch(/omo-agent-toolkit|status --json|codexGoalJson|--codex-goal-json|update_goal/);
+			expect(sdkArgs(actions, scenario.method)).toEqual(scenario.args);
+			if (scenario.method === "checkpoint") expect(actions).toContain("status().result.currentAttemptDir");
+		});
+
+		for (const siblings of [false, true]) {
+			it.each(["status", "completeGoals"])(
+				`#when %s has no plan and siblings=${siblings} #then recovery uses the calling surface`,
+				async (method) => {
+					if (siblings) await mkdir(ulwLoopDir(cwd, { sessionId: "other-session" }), { recursive: true });
+					const toolkit = createAgentToolkit({ cwd, ...scope, surface });
+					const response = await (method === "status" ? toolkit.status() : toolkit.completeGoals());
+					if (response.ok) throw new Error("Expected a missing-plan failure");
+
+					expect(response.error.code).toBe("ULW_LOOP_PLAN_MISSING");
+					if (surface === "lazycodex") {
+						expect(response.error.message).toContain(
+							'omo-agent-toolkit ulw-loop create-goals --brief "<brief>" --json',
+						);
+						if (siblings) expect(response.error.message).toContain("--session-id <id>");
+					} else {
+						expect(response.error.message).not.toMatch(/omo-agent-toolkit|--session-id/);
+						expect(sdkArgs(response.error.message, "createGoals")).toEqual({ brief: "<brief>" });
+					}
+					if (siblings)
+						expect(response.error.details?.["existingSessionIds"]?.split(",")).toContain("other-session");
+				},
+			);
+		}
+	});
+}

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

@@ -9,11 +9,11 @@ import { readSteeringLedgerEntries, readUlwLoopPlan, writePlan } from "../src/pl
 import { steerUlwLoopBatch } from "../src/steering-batch.js";
 import type { UlwLoopItem, UlwLoopPlan, UlwLoopSteeringProposal } from "../src/types.js";
 
-const appendFileCalls = vi.hoisted(() => vi.fn());
-vi.mock("node:fs/promises", async (importOriginal) => {
-	const actual = await importOriginal<typeof import("node:fs/promises")>();
-	appendFileCalls.mockImplementation(actual.appendFile);
-	return { ...actual, appendFile: appendFileCalls };
+const publishCalls = vi.hoisted(() => vi.fn());
+vi.mock("node:fs", async (importOriginal) => {
+	const actual = await importOriginal<typeof import("node:fs")>();
+	publishCalls.mockImplementation(actual.linkSync);
+	return { ...actual, linkSync: publishCalls };
 });
 
 const NOW = "2026-05-23T00:00:00.000Z";
@@ -78,12 +78,12 @@ describe("steerUlwLoopBatch", () => {
 
 	it("#given rejected proposals #when applied as a batch #then one rejection audit lists every rejected index", async () => {
 		const repo = await repoWithPlan();
-		const before = JSON.stringify(await readUlwLoopPlan(repo));
+		const before = await readUlwLoopPlan(repo);
 
 		const result = await steerUlwLoopBatch(repo, [proposal({ idempotencyKey: "ok" }), proposal({ kind: "reorder_pending", pendingOrder: ["missing"] }), proposal({ evidence: "" })]);
 
 		expect(result.accepted).toBe(false);
-		expect(JSON.stringify(await readUlwLoopPlan(repo))).toBe(before);
+		expect(await readUlwLoopPlan(repo)).toEqual({ ...before, revision: (before.revision ?? 0) + 1 });
 		expect((await readUlwLoopPlan(repo)).goals).toHaveLength(2);
 		const entries = await readSteeringLedgerEntries(repo);
 		expect(entries.filter((entry) => entry.kind === "steering_accepted")).toHaveLength(0);
@@ -120,13 +120,13 @@ describe("steerUlwLoopBatch", () => {
 		expect((await readUlwLoopPlan(repo)).goals).toHaveLength(4);
 	});
 
-	it("#given mixed fresh and deduped proposals #when accepted and replayed #then one append records all fresh audits and replay records none", async () => {
+	it("#given mixed fresh and deduped proposals #when accepted and replayed #then one publication records all fresh audits and replay records none", async () => {
 		const repo = await repoWithPlan();
 		const seeded = await readUlwLoopPlan(repo);
 		seeded.goals[0]?.successCriteria.push({ id: "C001", scenario: "old", expectedEvidence: "proof", userModel: "edge", status: "pending", capturedEvidence: null });
 		await writePlan(repo, { ...seeded, validationBatches: [{ batchId: "VB001", memberIds: ["G001", "G002"], finalGoalId: "G002" }] });
 		await steerUlwLoopBatch(repo, [proposal({ idempotencyKey: "dedupe-me" })]);
-		appendFileCalls.mockClear();
+		publishCalls.mockClear();
 
 		const revise = { ...proposal({ kind: "revise_criterion", targetGoalId: "G001", criterionId: "C001", idempotencyKey: "revise-c1" }), scenario: "new" } satisfies CliSteeringProposal;
 		const batch = [
@@ -138,15 +138,15 @@ describe("steerUlwLoopBatch", () => {
 
 		expect(result.accepted).toBe(true);
 		expect(result.results.map((item) => item.deduped)).toEqual([true, false, false]);
-		expect(appendFileCalls).toHaveBeenCalledTimes(1);
+		expect(publishCalls).toHaveBeenCalledTimes(1);
 		expect((await readSteeringLedgerEntries(repo)).map((entry) => entry.kind).slice(-3)).toEqual(["criteria_revised", "steering_accepted", "batch_updated"]);
 		const after = JSON.stringify(await readUlwLoopPlan(repo));
-		appendFileCalls.mockClear();
+		publishCalls.mockClear();
 
 		const replay = await steerUlwLoopBatch(repo, batch);
 
 		expect(replay.results.map((item) => item.deduped)).toEqual([true, true, true]);
 		expect(JSON.stringify(await readUlwLoopPlan(repo))).toBe(after);
-		expect(appendFileCalls).not.toHaveBeenCalled();
+		expect(publishCalls).not.toHaveBeenCalled();
 	});
 });

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

@@ -250,7 +250,10 @@ describe("steerUlwLoop", () => {
 		const repoRoot = await repoWithPlan(seed);
 		const result = await steerUlwLoop(repoRoot, steering({ kind: "annotate_ledger" }));
 		expect(result.plan.goals).toEqual(seed.goals);
-		expect(await readFile(ulwLoopGoalsPath(repoRoot), "utf8")).toBe(`${JSON.stringify(seed, null, 2)}\n`);
+		expect(JSON.parse(await readFile(ulwLoopGoalsPath(repoRoot), "utf8"))).toEqual({
+			...seed,
+			revision: (seed.revision ?? 0) + 1,
+		});
 	});
 
 	it("mark_blocked_superseded with children: supersede + replace", async () => {
@@ -422,11 +425,14 @@ describe("steerUlwLoop", () => {
 });
 
 describe("parseUlwLoopSteeringDirective", () => {
-	it.each(["OMO_ULW_LOOP_STEER", "omo.ulw-loop.steer", "omo ulw-loop steer", "omo-agent-toolkit ulw-loop steer"])("parses %s pattern", (marker) => {
-		expect(parseUlwLoopSteeringDirective(`${marker}: ${JSON.stringify(steering())}`)).toMatchObject({
-			kind: "add_subgoal",
-		});
-	});
+	it.each(["OMO_ULW_LOOP_STEER", "omo.ulw-loop.steer", "omo ulw-loop steer", "omo-agent-toolkit ulw-loop steer"])(
+		"parses %s pattern",
+		(marker) => {
+			expect(parseUlwLoopSteeringDirective(`${marker}: ${JSON.stringify(steering())}`)).toMatchObject({
+				kind: "add_subgoal",
+			});
+		},
+	);
 
 	it("returns null when no marker", () => {
 		expect(parseUlwLoopSteeringDirective(JSON.stringify(steering()))).toBeNull();

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

@@ -99,7 +99,7 @@ describe("runStopResumeHook", () => {
 		expect(runStopResumeHook({ hook_event_name: "Stop" })).toBe("");
 	});
 
-	it("#given an active boulder work with remaining plan tasks #when the hook runs #then defers to start-work-continuation", () => {
+	it("#given an active boulder work with remaining plan tasks #when the hook runs #then defers to ulw-execute-continuation", () => {
 		writeGoals([pendingGoal()]);
 		const plan = writeBoulderPlan(true);
 		writeFileSync(

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

@@ -0,0 +1,74 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { REVIEWER_ROLES_BY_SURFACE, resolveToolkitSurface, reviewerRolesFor } from "../src/surface.ts";
+
+let markerDir: string;
+
+beforeEach(async () => {
+	markerDir = await mkdtemp(join(tmpdir(), "ulw-surface-"));
+});
+
+afterEach(async () => {
+	await rm(markerDir, { recursive: true, force: true });
+});
+
+describe("resolveToolkitSurface", () => {
+	it("#given no marker and no env #when resolved #then defaults to lazycodex", () => {
+		expect(resolveToolkitSurface({ env: {}, entryDir: markerDir })).toBe("lazycodex");
+	});
+
+	it("#given a staged omo-senpi marker #when resolved #then returns omo-senpi", async () => {
+		await writeFile(join(markerDir, "surface.json"), '{"surface":"omo-senpi"}\n', "utf8");
+
+		expect(resolveToolkitSurface({ env: {}, entryDir: markerDir })).toBe("omo-senpi");
+	});
+
+	it("#given the env override #when a conflicting marker exists #then the env wins", async () => {
+		await writeFile(join(markerDir, "surface.json"), '{"surface":"omo-senpi"}\n', "utf8");
+
+		expect(resolveToolkitSurface({ env: { OMO_AGENT_TOOLKIT_SURFACE: "lazycodex" }, entryDir: markerDir })).toBe(
+			"lazycodex",
+		);
+	});
+
+	it("#given an omo-senpi env override without marker #when resolved #then returns omo-senpi", () => {
+		expect(resolveToolkitSurface({ env: { OMO_AGENT_TOOLKIT_SURFACE: "omo-senpi" }, entryDir: markerDir })).toBe(
+			"omo-senpi",
+		);
+	});
+
+	it("#given malformed or unknown markers #when resolved #then falls back to lazycodex", async () => {
+		await writeFile(join(markerDir, "surface.json"), "not json at all", "utf8");
+		expect(resolveToolkitSurface({ env: {}, entryDir: markerDir })).toBe("lazycodex");
+
+		await writeFile(join(markerDir, "surface.json"), '{"surface":"unknown-surface"}\n', "utf8");
+		expect(resolveToolkitSurface({ env: {}, entryDir: markerDir })).toBe("lazycodex");
+	});
+
+	it("#given an unknown env value #when a valid marker exists #then the marker still applies", async () => {
+		await writeFile(join(markerDir, "surface.json"), '{"surface":"omo-senpi"}\n', "utf8");
+
+		expect(resolveToolkitSurface({ env: { OMO_AGENT_TOOLKIT_SURFACE: "bogus" }, entryDir: markerDir })).toBe(
+			"omo-senpi",
+		);
+	});
+});
+
+describe("reviewerRolesFor", () => {
+	it("#given each surface #when resolving roles #then the identity namespaces match the surface", () => {
+		expect(reviewerRolesFor("lazycodex")).toEqual({
+			codeReview: "lazycodex-code-reviewer",
+			manualQa: "lazycodex-qa-executor",
+			gateReview: "lazycodex-gate-reviewer",
+		});
+		expect(reviewerRolesFor("omo-senpi")).toEqual({
+			codeReview: "omo-senpi-code-reviewer",
+			manualQa: "omo-senpi-qa-executor",
+			gateReview: "omo-senpi-gate-reviewer",
+		});
+		expect(Object.keys(REVIEWER_ROLES_BY_SURFACE).sort()).toEqual(["lazycodex", "omo-senpi"]);
+	});
+});

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

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import { describe, expect, it } from "vitest";
 
 import { applyUserPromptUlwLoopSteering, type UserPromptSubmitPayload } from "../src/codex-hook.js";
+import { buildUltraworkSkillPointer } from "../src/ultrawork-skill-pointer.js";
 
 const DEFAULT_SESSION_ID = "s1";
 
@@ -55,11 +56,17 @@ describe("standalone ultrawork directive injection", () => {
 		expect(parsed.hookSpecificOutput.additionalContext).toMatch(/^<ultrawork-mode>/);
 	});
 
-	it("#given ulw-loop bundles the ultrawork directive #when compared to ultrawork #then the copy stays byte-identical", async () => {
+	it("#given ulw-loop bundles the ultrawork directive #when compared to the canonical prompts-core source #then the copy stays byte-identical", async () => {
+		// ulw-loop is a standalone published package with no prompts-core dependency, so it bundles its
+		// own copy as the runtime fallback its `files` list ships. This pins that copy to the canonical
+		// source that scripts/sync-directive.mjs in the ultrawork component regenerates it from.
 		const ulwLoopDirective = await readFile(new URL("../directive.md", import.meta.url), "utf8");
-		const ultraworkDirective = await readFile(new URL("../../ultrawork/directive.md", import.meta.url), "utf8");
+		const canonicalDirective = await readFile(
+			new URL("../../../../../prompts-core/prompts/ultrawork/codex.md", import.meta.url),
+			"utf8",
+		);
 
-		expect(ulwLoopDirective).toBe(ultraworkDirective);
+		expect(ulwLoopDirective).toBe(canonicalDirective);
 	});
 
 	it("#given an existing ultrawork skill file #when standalone injection runs #then emits the compact skill pointer", async () => {
@@ -76,10 +83,7 @@ describe("standalone ultrawork directive injection", () => {
 		const parsed = JSON.parse(output);
 		const context = parsed.hookSpecificOutput.additionalContext;
 
-		expect(context).toMatch(/^<ultrawork-mode>/);
-		expect(context).toContain(skillFilePath);
-		expect(context).toContain("create_goal");
-		expect(context).not.toContain("Tier triage");
+		expect(context).toBe(buildUltraworkSkillPointer(skillFilePath).trim());
 	});
 
 	it("#given a missing ultrawork skill file #when standalone injection runs #then falls back to the full directive", async () => {
@@ -90,8 +94,9 @@ describe("standalone ultrawork directive injection", () => {
 			ultraworkSkillFilePath: missingSkillFilePath,
 		});
 		const parsed = JSON.parse(output);
+		const directive = await readFile(new URL("../directive.md", import.meta.url), "utf8");
 
-		expect(parsed.hookSpecificOutput.additionalContext).toContain("Tier triage");
+		expect(parsed.hookSpecificOutput.additionalContext).toBe(directive.trim());
 	});
 
 	it("#given the ulw-loop pointer template #when compared to ultrawork #then the copy stays byte-identical", async () => {