oh-my-opencode 5.0.0-beta.4 → 5.0.0-beta.40

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

@@ -0,0 +1,137 @@
+import { existsSync, statSync } from "node:fs";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { ulwLoopCommand } from "../src/cli-commands.js";
+import { writePlan } from "../src/plan-io.js";
+import { validateQualityGate } from "../src/quality-gate.js";
+import { goal, plan } from "./fixtures/checkpoint-builders.js";
+
+let repo: string;
+let output: string[];
+
+beforeEach(async () => {
+	repo = await mkdtemp(join(tmpdir(), "ulw-template-"));
+	output = [];
+	vi.spyOn(process, "cwd").mockReturnValue(repo);
+	vi.spyOn(process.stdout, "write").mockImplementation((chunk: string | Uint8Array): boolean => {
+		output.push(chunk.toString());
+		return true;
+	});
+	delete process.env["OMO_AGENT_TOOLKIT_SURFACE"];
+});
+
+afterEach(async () => {
+	vi.restoreAllMocks();
+	await rm(repo, { recursive: true, force: true });
+});
+
+async function run(args: string[]): Promise<Record<string, unknown>> {
+	const code = await ulwLoopCommand(["checkpoint", ...args]);
+	expect(code).toBe(0);
+	return JSON.parse(output.join(""));
+}
+
+function fillTemplate(value: unknown): unknown {
+	if (typeof value === "string") {
+		return value.replace(/<replace:[^>]+>/g, "plausible evidence");
+	}
+	if (Array.isArray(value)) return value.map(fillTemplate);
+	if (value !== null && typeof value === "object") {
+		return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, fillTemplate(item)]));
+	}
+	return value;
+}
+
+describe("checkpoint --print-template", () => {
+	it("#given a printed template #when every placeholder is filled #then the quality gate validates", async () => {
+		await writePlan(
+			repo,
+			plan([goal({ id: "G001", attempt: 2 })], {
+				evidenceLayoutVersion: 2,
+				activeGoalId: "G001",
+				codexObjective: "Exact objective from goals.json",
+			}),
+		);
+		process.env["OMO_AGENT_TOOLKIT_SURFACE"] = "omo-senpi";
+		const result = await run(["--print-template", "--goal-id", "G001", "--json"]);
+		const template = fillTemplate(result["qualityGateTemplate"]) as Record<string, unknown>;
+		const paths = [
+			...((template["manualQa"] as Record<string, unknown>)["artifactRefs"] as Array<Record<string, unknown>>),
+		];
+		await Promise.all(
+			[
+				...paths.map((artifact) => String(artifact["path"])),
+				String((template["gateReview"] as Record<string, unknown>)["reportPath"]),
+			].map(async (path) => {
+				const absolute = resolve(repo, path);
+				await mkdir(resolve(absolute, ".."), { recursive: true });
+				await writeFile(absolute, "evidence");
+			}),
+		);
+		const validated = validateQualityGate(template, {
+			repoRoot: repo,
+			fs: { existsSync, statSync },
+			reviewerSurface: "omo-senpi",
+		});
+		expect(validated.gateReview.recommendation).toBe("APPROVE");
+	});
+	it("#given an active senpi v2 plan #when printed with only goal-id #then emits the senpi gate skeleton", async () => {
+		await writePlan(
+			repo,
+			plan([goal({ id: "G001", attempt: 2 })], {
+				evidenceLayoutVersion: 2,
+				activeGoalId: "G001",
+				codexObjective: "Exact objective from goals.json",
+			}),
+		);
+		process.env["OMO_AGENT_TOOLKIT_SURFACE"] = "omo-senpi";
+		const result = await run(["--print-template", "--goal-id", "G001", "--json"]);
+		const gate = result["qualityGateTemplate"] as Record<string, unknown>;
+		expect(Object.keys(gate)).toEqual(["manualQa", "gateReview", "iteration", "criteriaCoverage"]);
+		expect((gate["manualQa"] as Record<string, unknown>)["by"]).toBe("main-session");
+		expect((gate["gateReview"] as Record<string, unknown>)["by"]).toBe("category:deep");
+		expect(result["codexGoalTemplate"]).toEqual({
+			goal: { objective: "Exact objective from goals.json", status: "complete" },
+		});
+		expect(result["attemptDir"]).toBe(".omo/evidence/ulw/session/G001/a2");
+	});
+
+	it("#given an active v2 plan #when printed without any goal id #then targets the active goal", async () => {
+		await writePlan(
+			repo,
+			plan([goal({ id: "G001", attempt: 1 })], {
+				evidenceLayoutVersion: 2,
+				activeGoalId: "G001",
+				codexObjective: "Exact objective from goals.json",
+			}),
+		);
+		process.env["OMO_AGENT_TOOLKIT_SURFACE"] = "omo-senpi";
+		const result = await run(["--print-template", "--json"]);
+		const gate = result["qualityGateTemplate"] as Record<string, unknown>;
+		expect(Object.keys(gate)).toEqual(["manualQa", "gateReview", "iteration", "criteriaCoverage"]);
+		expect(result["attemptDir"]).toBe(".omo/evidence/ulw/session/G001/a1");
+	});
+
+	it("#given two goals #when printed with an explicit non-active goal id #then targets that goal's attempt dir", async () => {
+		await writePlan(
+			repo,
+			plan([goal({ id: "G001", attempt: 1 }), goal({ id: "G002", attempt: 3 })], {
+				evidenceLayoutVersion: 2,
+				activeGoalId: "G001",
+				codexObjective: "Exact objective from goals.json",
+			}),
+		);
+		const result = await run(["--print-template", "--goal-id", "G002", "--json"]);
+		expect(result["attemptDir"]).toBe(".omo/evidence/ulw/session/G002/a3");
+	});
+
+	it("#given a v1 plan #when printed without status #then exits successfully and gives v1 guidance", async () => {
+		await writePlan(repo, plan([goal({ id: "G001" })]));
+		const result = await run(["--print-template", "--goal-id", "G001", "--json"]);
+		expect(result["guidance"]).toContain("evidence-layout v1");
+		expect(result).not.toHaveProperty("attemptDir");
+	});
+});

package/packages/omo-codex/plugin/components/ulw-loop/test/cli-create-goals.test.ts

@@ -13,6 +13,7 @@ let err: string[];
 let originalCodexSessionId: string | undefined;
 let originalCodexThreadId: string | undefined;
 let originalOmoSessionId: string | undefined;
+let originalPiSessionId: string | undefined;
 
 beforeEach(async () => {
 	testDir = await mkdtemp(join(tmpdir(), "ug-cli-create-goals-"));
@@ -21,9 +22,11 @@ beforeEach(async () => {
 	originalCodexSessionId = process.env["CODEX_SESSION_ID"];
 	originalCodexThreadId = process.env["CODEX_THREAD_ID"];
 	originalOmoSessionId = process.env["OMO_ULW_LOOP_SESSION_ID"];
+	originalPiSessionId = process.env["PI_SESSION_ID"];
 	delete process.env["CODEX_SESSION_ID"];
 	delete process.env["CODEX_THREAD_ID"];
 	delete process.env["OMO_ULW_LOOP_SESSION_ID"];
+	delete process.env["PI_SESSION_ID"];
 	vi.spyOn(process, "cwd").mockReturnValue(testDir);
 	vi.spyOn(process.stdout, "write").mockImplementation((chunk: string | Uint8Array): boolean => {
 		out.push(chunk.toString());
@@ -43,6 +46,8 @@ afterEach(async () => {
 	else process.env["CODEX_THREAD_ID"] = originalCodexThreadId;
 	if (originalOmoSessionId === undefined) delete process.env["OMO_ULW_LOOP_SESSION_ID"];
 	else process.env["OMO_ULW_LOOP_SESSION_ID"] = originalOmoSessionId;
+	if (originalPiSessionId === undefined) delete process.env["PI_SESSION_ID"];
+	else process.env["PI_SESSION_ID"] = originalPiSessionId;
 	await rm(testDir, { recursive: true, force: true });
 });
 
@@ -182,6 +187,26 @@ describe("ulwLoopCommand create-goals", () => {
 		expect(await readFile(join(testDir, ".omo/ulw-loop/manual-456/goals.json"), "utf8")).toContain("Manual scoped");
 	});
 
+	it("#given two Senpi sessions in one cwd #when each reads ulw-loop state #then only the owner sees its run", async () => {
+		process.env["PI_SESSION_ID"] = "session-A";
+		expect(await ulwLoopCommand(["create-goals", "--brief", "- Session A run", "--json"])).toBe(0);
+		resetOutput();
+
+		process.env["PI_SESSION_ID"] = "session-B";
+		expect(await ulwLoopCommand(["status", "--json"])).toBe(1);
+		expect(stdoutJson()).toMatchObject({ ok: false, error: { code: "ULW_LOOP_PLAN_MISSING" } });
+		resetOutput();
+
+		process.env["PI_SESSION_ID"] = "session-A";
+		expect(await ulwLoopCommand(["status", "--json"])).toBe(0);
+		expect(stdoutJson()).toMatchObject({
+			plan: {
+				goalsPath: ".omo/ulw-loop/session-A/goals.json",
+				goals: [{ title: "Session A run" }],
+			},
+		});
+	});
+
 	it("#given a valueless --session-id #when creating goals #then it fails and writes no plan", async () => {
 		const code = await ulwLoopCommand(["create-goals", "--session-id", "--brief", "- Alpha"]);
 

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

@@ -91,12 +91,36 @@ describe("dist/cli.js entrypoint dispatch", () => {
 		expect(result.code).toBe(1);
 	});
 
-	it("#given the top-level entrypoint #when invoked with 'help' #then prints usage and exits 0", async () => {
+	it("#given the top-level entrypoint #when invoked with 'help' #then prints the merged hook and subcommand usage and exits 0", async () => {
 		const result = await runCli(["help"]);
 
 		expect(result.code).toBe(0);
 		expect(result.stdout).toContain("Usage:");
-		expect(result.stdout).toContain("omo-agent-toolkit ulw-loop <subcommand>");
+		expect(result.stdout).toContain("hook user-prompt-submit");
+		expect(result.stdout).toContain("create-goals");
+		expect(result.stdout).toContain("complete-goals");
+		expect(result.stdout).toContain("record-review-blockers");
+		expect(result.stdout).not.toContain("for ulw-loop subcommands");
+	});
+
+	it("#given the staged router strips nothing #when invoked with 'ulw-loop help' #then prints the same merged help text", async () => {
+		const bare = await runCli(["help"]);
+		const nested = await runCli(["ulw-loop", "help"]);
+
+		expect(nested.code).toBe(0);
+		expect(nested.stdout.trim()).toBe(bare.stdout.trim());
+		expect(nested.stdout).toContain("hook user-prompt-submit");
+		expect(nested.stdout).toContain("record-review-blockers");
+		expect(nested.stdout).not.toContain("for ulw-loop subcommands");
+	});
+
+	it("#given a subcommand with required args #when invoked with 'create-goals --help' #then prints its usage and exits 0", async () => {
+		const result = await runCli(["create-goals", "--help"]);
+
+		expect(result.code).toBe(0);
+		expect(result.stdout).toContain("Usage:");
+		expect(result.stdout).toContain("create-goals");
+		expect(`${result.stdout}${result.stderr}`).not.toContain("Missing brief text");
 	});
 
 	it("#given a command outside the ulw-loop vocabulary #when invoked with 'frobnicate' #then fails as unknown command", async () => {

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

@@ -0,0 +1,183 @@
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { ulwLoopCommand } from "../src/cli-commands.js";
+import { ulwLoopDir } from "../src/paths.js";
+import { writePlan } from "../src/plan-io.js";
+import type { UlwLoopItem, UlwLoopPlan, UlwLoopSuccessCriterion } from "../src/types.js";
+
+const NOW = "2026-05-23T00:00:00.000Z";
+const SESSION_ENV_KEYS = ["OMO_ULW_LOOP_SESSION_ID", "CODEX_SESSION_ID", "CODEX_THREAD_ID", "PI_SESSION_ID"] as const;
+
+let testDir: string;
+let out: string[];
+let err: string[];
+let savedEnv: Record<string, string | undefined>;
+
+beforeEach(async () => {
+	testDir = await mkdtemp(join(tmpdir(), "ug-status-next-"));
+	out = [];
+	err = [];
+	savedEnv = {};
+	for (const key of SESSION_ENV_KEYS) {
+		savedEnv[key] = process.env[key];
+		delete process.env[key];
+	}
+	vi.spyOn(process, "cwd").mockReturnValue(testDir);
+	vi.spyOn(process.stdout, "write").mockImplementation((chunk: string | Uint8Array): boolean => {
+		out.push(chunk.toString());
+		return true;
+	});
+	vi.spyOn(process.stderr, "write").mockImplementation((chunk: string | Uint8Array): boolean => {
+		err.push(chunk.toString());
+		return true;
+	});
+});
+
+afterEach(async () => {
+	vi.restoreAllMocks();
+	for (const key of SESSION_ENV_KEYS) {
+		const saved = savedEnv[key];
+		if (saved === undefined) delete process.env[key];
+		else process.env[key] = saved;
+	}
+	await rm(testDir, { recursive: true, force: true });
+});
+
+function stdoutJson(): Record<string, unknown> {
+	return JSON.parse(out.join(""));
+}
+
+function nextActions(): readonly string[] {
+	const value = stdoutJson()["nextActions"];
+	if (!Array.isArray(value)) throw new Error(`expected nextActions array, got ${JSON.stringify(value)}`);
+	return value.map((entry) => String(entry));
+}
+
+function criterion(id: string, status: UlwLoopSuccessCriterion["status"]): UlwLoopSuccessCriterion {
+	return {
+		id,
+		scenario: `${id} scenario`,
+		userModel: "happy",
+		expectedEvidence: `${id} proof`,
+		capturedEvidence: status === "pass" ? `${id} passed` : null,
+		status,
+	};
+}
+
+function goal(overrides: Partial<UlwLoopItem> = {}): UlwLoopItem {
+	return {
+		id: "G001",
+		title: "Build auth",
+		objective: "Implement JWT auth endpoint",
+		status: "in_progress",
+		successCriteria: [criterion("C001", "pass")],
+		attempt: 1,
+		createdAt: NOW,
+		updatedAt: NOW,
+		...overrides,
+	};
+}
+
+function plan(goals: UlwLoopItem[], overrides: Partial<UlwLoopPlan> = {}): UlwLoopPlan {
+	const result: UlwLoopPlan = {
+		version: 1,
+		evidenceLayoutVersion: 2,
+		createdAt: NOW,
+		updatedAt: NOW,
+		briefPath: ".omo/ulw-loop/brief.md",
+		goalsPath: ".omo/ulw-loop/goals.json",
+		ledgerPath: ".omo/ulw-loop/ledger.jsonl",
+		goals,
+	};
+	Object.assign(result, overrides);
+	return result;
+}
+
+function legacyLayoutPlan(goals: UlwLoopItem[], overrides: Partial<UlwLoopPlan> = {}): UlwLoopPlan {
+	const result = plan(goals, overrides);
+	delete result.evidenceLayoutVersion;
+	return result;
+}
+
+async function seed(seedPlan: UlwLoopPlan): Promise<void> {
+	await mkdir(ulwLoopDir(testDir), { recursive: true });
+	await writePlan(testDir, seedPlan);
+}
+
+describe("#given a plan with no goals", () => {
+	it("#when status --json #then nextActions points at create-goals", async () => {
+		await seed(plan([]));
+
+		expect(await ulwLoopCommand(["status", "--json"])).toBe(0);
+		expect(nextActions().join("\n")).toContain('omo-agent-toolkit ulw-loop create-goals --brief "<brief>" --json');
+	});
+});
+
+describe("#given an active goal with unresolved criteria", () => {
+	it("#when status --json #then nextActions names record-evidence with the remaining criterion ids", async () => {
+		await seed(
+			plan(
+				[
+					goal({
+						successCriteria: [criterion("C001", "pass"), criterion("C002", "pending"), criterion("C003", "fail")],
+					}),
+				],
+				{
+					activeGoalId: "G001",
+				},
+			),
+		);
+
+		expect(await ulwLoopCommand(["status", "--json"])).toBe(0);
+		const actions = nextActions().join("\n");
+		expect(actions).toContain("record-evidence");
+		expect(actions).toContain("C002");
+		expect(actions).toContain("C003");
+		expect(actions).not.toContain("C001");
+		expect(stdoutJson()).toHaveProperty("currentAttemptDir");
+	});
+});
+
+describe("#given the final story with every criterion passing", () => {
+	it("#when status --json #then nextActions tells the agent to complete the goal then print the template", async () => {
+		await seed(plan([goal({ successCriteria: [criterion("C001", "pass")] })], { activeGoalId: "G001" }));
+
+		expect(await ulwLoopCommand(["status", "--json"])).toBe(0);
+		const actions = nextActions().join("\n");
+		expect(actions).toContain("update_goal complete, then checkpoint --print-template");
+	});
+});
+
+describe("#given a review_blocked goal", () => {
+	it("#when status --json #then nextActions points at record-review-blockers", async () => {
+		await seed(plan([goal({ status: "review_blocked", successCriteria: [criterion("C001", "pass")] })]));
+
+		expect(await ulwLoopCommand(["status", "--json"])).toBe(0);
+		expect(nextActions().join("\n")).toContain("record-review-blockers");
+	});
+});
+
+describe("#given an evidence-layout v1 plan", () => {
+	it("#when status --json #then currentAttemptDir stays absent and nextActions explains the v1 layout", async () => {
+		await seed(legacyLayoutPlan([goal()], { activeGoalId: "G001" }));
+
+		expect(await ulwLoopCommand(["status", "--json"])).toBe(0);
+		expect(stdoutJson()).not.toHaveProperty("currentAttemptDir");
+		expect(nextActions().join("\n")).toContain("plan is evidence-layout v1; artifacts go under .omo/evidence/");
+	});
+});
+
+describe("#given a valueless --session-id in a subprocess context", () => {
+	it("#when any subcommand runs #then the error explains the missing session env and the flag usage", async () => {
+		expect(await ulwLoopCommand(["status", "--session-id", "--json"])).toBe(1);
+
+		const payload = stdoutJson();
+		expect(payload).toMatchObject({ ok: false, error: { code: "ULW_LOOP_SESSION_ID_REQUIRED" } });
+		const message = String((payload["error"] as Record<string, unknown>)["message"]);
+		expect(message).toContain("--session-id <id>");
+		expect(message).toContain("subprocess");
+	});
+});

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

@@ -6,6 +6,7 @@ import type { UlwLoopItem, UlwLoopPlan, UlwLoopSuccessCriterion } from "../src/t
 
 const NOW = "2026-05-23T00:00:00.000Z";
 const FINAL_REVIEW_ROLES = ["lazycodex-code-reviewer", "lazycodex-qa-executor", "lazycodex-gate-reviewer"] as const;
+const SENPI_REVIEW_ROLES = ["omo-senpi-code-reviewer", "omo-senpi-qa-executor", "omo-senpi-gate-reviewer"] as const;
 const QUALITY_GATE_SECTIONS = ["codeReview", "manualQa", "gateReview", "iteration", "criteriaCoverage"] as const;
 
 function makeCriterion(overrides: Partial<UlwLoopSuccessCriterion> = {}): UlwLoopSuccessCriterion {
@@ -94,6 +95,40 @@ describe("buildCodexGoalInstruction aggregate mode", () => {
 		expect(text).toContain("checkpoint");
 	});
 
+	it("#given a final story on the omo-senpi surface #when rendering instructions #then teaches the single-gate category chain", () => {
+		const { text } = buildCodexGoalInstruction({
+			plan: makePlan({ codexGoalMode: "aggregate" }),
+			goal: makeGoal(),
+			isFinal: true,
+			surface: "omo-senpi",
+		});
+
+		expectTextToContainAll(text, [
+			"main-session",
+			'category: "deep"',
+			"unspecified-high",
+			"unspecified-low",
+			"gateReview.by",
+			"category:<name>",
+			"--print-template",
+		]);
+		for (const role of [...FINAL_REVIEW_ROLES, ...SENPI_REVIEW_ROLES]) expect(text).not.toContain(role);
+		expect(text).toMatch(/model_unavailable/);
+		expect(text).not.toContain("attempted_chain");
+	});
+
+	it("#given a final story with the explicit lazycodex surface #when rendering instructions #then keeps the lazycodex reviewers", () => {
+		const { text } = buildCodexGoalInstruction({
+			plan: makePlan({ codexGoalMode: "aggregate" }),
+			goal: makeGoal(),
+			isFinal: true,
+			surface: "lazycodex",
+		});
+
+		expectTextToContainAll(text, FINAL_REVIEW_ROLES);
+		for (const role of SENPI_REVIEW_ROLES) expect(text).not.toContain(role);
+	});
+
 	it("#given a scoped plan #when rendering final commands #then includes the session id option", () => {
 		const { text } = buildCodexGoalInstruction({
 			plan: makePlan({
@@ -113,9 +148,9 @@ describe("buildCodexGoalInstruction aggregate mode", () => {
 
 describe("buildCodexGoalInstruction per_story mode", () => {
 	it("uses the goal's own objective for create_goal", () => {
-		const goal = makeGoal({ objective: "Build the auth service" });
+		const goal = makeGoal({ objective: "per-story-objective-sentinel" });
 		const { text } = buildCodexGoalInstruction({ plan: makePlan({ codexGoalMode: "per_story" }), goal });
-		expect(text).toContain("Build the auth service");
+		expect(text).toContain("per-story-objective-sentinel");
 	});
 });
 

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 };

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/quality-gate-builder.ts

@@ -1,6 +1,8 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
+import { reviewerRolesFor, type UlwLoopToolkitSurface } from "../../src/surface.js";
+
 // v2 evidence layout: artifacts must live inside the goal's current attempt dir
 export function qaDirFor(goalId: string, attempt = 1, sessionId = "session"): string {
 	return `.omo/evidence/ulw/${sessionId}/${goalId}/a${attempt}`;
@@ -25,13 +27,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 +43,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 +82,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,105 @@
+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 { ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE } from "../src/goal-status.js";
+import { ulwLoopDir } from "../src/paths.js";
+import { readUlwLoopPlan } from "../src/plan-io.js";
+import { recordFinalReviewBlockers } from "../src/review-blockers.js";
+import { UlwLoopError } from "../src/types.js";
+import { goal, passGoal, plan, repoWith, snapshot } 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 the mismatch carries the verbatim expected and received objectives", async () => {
+		const repo = await repoWith(plan([passGoal("G001"), goal({ id: "G002", status: "pending" })]));
+
+		const error = await captureError(() =>
+			checkpointUlwLoop(repo, {
+				goalId: "G001",
+				status: "complete",
+				evidence: "work complete and validation passed",
+				codexGoalJson: snapshot("active", "wrong objective"),
+			}),
+		);
+
+		expect(error.code).toBe("ulw_loop_codex_snapshot_mismatch");
+		expect(error.details).toMatchObject({
+			expectedObjective: ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE,
+			receivedObjective: "wrong objective",
+		});
+		expect(error.message).toContain(
+			"objective must equal the plan's codexObjective exactly — copy the expected value below",
+		);
+		expect(error.message).toContain(ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE);
+	});
+
+	it("#when record-review-blockers reconciles it #then the same guided payload is emitted", async () => {
+		const repo = await repoWith(
+			plan([passGoal("G001", { status: "complete" }), goal({ id: "G002", status: "in_progress" })]),
+		);
+
+		const error = await captureError(() =>
+			recordFinalReviewBlockers(repo, {
+				goalId: "G002",
+				title: "Resolve final review blockers",
+				objective: "Address the BLOCK findings",
+				evidence: "review verdict: REQUEST_CHANGES",
+				codexGoalJson: JSON.stringify({ goal: { objective: "stale objective", status: "active" } }),
+			}),
+		);
+
+		expect(error.code).toBe("ulw_loop_codex_snapshot_mismatch");
+		expect(error.details).toMatchObject({
+			expectedObjective: ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE,
+			receivedObjective: "stale objective",
+		});
+		expect(error.message).toContain(
+			"objective must equal the plan's codexObjective exactly — copy the expected value below",
+		);
+	});
+});
+
+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();
+	});
+});