oh-my-opencode 5.0.0-beta.6 → 5.0.0-beta.62

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

@@ -9,6 +9,7 @@ import { parseSteeringProposals } from "../src/cli-steering.js";
 import { ulwLoopGoalsPath } from "../src/paths.js";
 import { writePlan } from "../src/plan-io.js";
 import type { UlwLoopPlan } from "../src/types.js";
+import { CLI_TEST_SCOPE } from "./fixtures/cli-session.js";
 
 const NOW = "2026-05-23T00:00:00.000Z";
 
@@ -45,9 +46,11 @@ describe("parseSteeringProposals", () => {
 	it("#given kind and proposals-json #when steering through CLI #then rejects conflict without mutation", async () => {
 		const repo = await mkdtemp(join(tmpdir(), "ug-cli-steer-batch-conflict-"));
 		const out: string[] = [];
+		const originalOmoSessionId = process.env["OMO_ULW_LOOP_SESSION_ID"];
 		try {
-			await writePlan(repo, plan());
-			const before = await readFile(ulwLoopGoalsPath(repo), "utf8");
+			process.env["OMO_ULW_LOOP_SESSION_ID"] = CLI_TEST_SCOPE.sessionId;
+			await writePlan(repo, plan(), CLI_TEST_SCOPE);
+			const before = await readFile(ulwLoopGoalsPath(repo, CLI_TEST_SCOPE), "utf8");
 			vi.spyOn(process, "cwd").mockReturnValue(repo);
 			vi.spyOn(process.stdout, "write").mockImplementation((chunk: string | Uint8Array): boolean => {
 				out.push(chunk.toString());
@@ -58,8 +61,10 @@ describe("parseSteeringProposals", () => {
 			expect(await ulwLoopCommand(["steer", "--kind", "annotate_ledger", "--evidence", "flag", "--rationale", "flag", "--proposals-json", '[{"kind":"annotate_ledger","evidence":"batch","rationale":"batch"}]', "--json"])).toBe(1);
 
 			expect(JSON.parse(out.join(""))).toHaveProperty("error.code", "ULW_LOOP_STEERING_BATCH_CONFLICT");
-			expect(await readFile(ulwLoopGoalsPath(repo), "utf8")).toBe(before);
+			expect(await readFile(ulwLoopGoalsPath(repo, CLI_TEST_SCOPE), "utf8")).toBe(before);
 		} finally {
+			if (originalOmoSessionId === undefined) delete process.env["OMO_ULW_LOOP_SESSION_ID"];
+			else process.env["OMO_ULW_LOOP_SESSION_ID"] = originalOmoSessionId;
 			vi.restoreAllMocks();
 			await rm(repo, { recursive: true, force: true });
 		}

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

@@ -4,13 +4,17 @@ import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { ulwLoopCommand } from "../src/cli-commands.js";
+import { CLI_TEST_SESSION_ID } from "./fixtures/cli-session.js";
 
 let testDir: string;
 let out: string[];
+let originalOmoSessionId: string | undefined;
 
 beforeEach(async () => {
 	testDir = await mkdtemp(join(tmpdir(), "ug-cli-validation-batch-"));
 	out = [];
+	originalOmoSessionId = process.env["OMO_ULW_LOOP_SESSION_ID"];
+	process.env["OMO_ULW_LOOP_SESSION_ID"] = CLI_TEST_SESSION_ID;
 	vi.spyOn(process, "cwd").mockReturnValue(testDir);
 	vi.spyOn(process.stdout, "write").mockImplementation((chunk: string | Uint8Array): boolean => {
 		out.push(chunk.toString());
@@ -21,6 +25,8 @@ beforeEach(async () => {
 
 afterEach(async () => {
 	vi.restoreAllMocks();
+	if (originalOmoSessionId === undefined) delete process.env["OMO_ULW_LOOP_SESSION_ID"];
+	else process.env["OMO_ULW_LOOP_SESSION_ID"] = originalOmoSessionId;
 	await rm(testDir, { recursive: true, force: true });
 });
 

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 };
@@ -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,34 @@ 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");
 	});
 
-	it("reports error when status mismatches", () => {
+	it("accepts a parsable snapshot without objective as advisory", () => {
 		// when
 		const reconciliation = reconcileCodexGoalSnapshot(
-			{ available: true, objective: "X", status: "active", raw: null },
-			{ expectedObjective: "X", allowedStatuses: ["complete"] },
+			{ available: true, status: "active", raw: { goal: { status: "active" } } },
+			{ expectedObjective: "X" },
 		);
 
 		// then
-		expect(reconciliation.ok).toBe(false);
-		expect(reconciliation.errors.length).toBeGreaterThan(0);
+		expect(reconciliation.ok).toBe(true);
+		expect(reconciliation.errors).toHaveLength(0);
+	});
+
+	it("accepts limited driver statuses", () => {
+		// when
+		const reconciliation = reconcileCodexGoalSnapshot(
+			{ available: true, objective: "X", status: "budget_limited", raw: null },
+			{ expectedObjective: "X" },
+		);
+
+		// then
+		expect(reconciliation.ok).toBe(true);
+		expect(reconciliation.errors).toHaveLength(0);
+		expect(reconciliation.warnings.join(" ")).toContain("/goal resume");
 	});
 });
 
@@ -144,7 +185,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/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/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();
+	});
+});

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

@@ -24,9 +24,7 @@ type ShellResult = {
 };
 
 function bootstrapScriptFrom(text: string): string {
-	const heading = text.indexOf("### 1. Create goals from the brief");
-	expect(heading).toBeGreaterThanOrEqual(0);
-	const blockStart = text.indexOf("```sh\n", heading);
+	const blockStart = text.indexOf("```sh\n");
 	expect(blockStart).toBeGreaterThanOrEqual(0);
 	const codeStart = blockStart + "```sh\n".length;
 	const blockEnd = text.indexOf("\n```", codeStart);
@@ -90,7 +88,8 @@ describe("hooks/hooks.json", () => {
 		const hooks = await readJson("hooks/hooks.json") as Record<string, unknown>;
 		const events = (hooks["hooks"] as Record<string, unknown>)["UserPromptSubmit"] as readonly Record<string, unknown>[];
 		expect(events.length).toBeGreaterThan(0);
-		const command = ((events[0]?.["hooks"] as readonly Record<string, unknown>[])[0]?.["command"]) as string;
+		const command = (events[0]?.["hooks"] as readonly Record<string, unknown>[] | undefined)?.[0]?.["command"];
+		expect(command).toEqual(expect.any(String));
 		expect(command).toContain(`$${"{PLUGIN_ROOT}"}`);
 		expect(command).toContain("dist/cli.js");
 		expect(command).toContain("hook user-prompt-submit");
@@ -129,9 +128,7 @@ describe("skills/ulw-loop/SKILL.md", () => {
 		const text = await readText("skills/ulw-loop/agents/openai.yaml");
 
 		expect(text).toContain('display_name: "(OmO) ulw-loop"');
-		expect(text).not.toContain("ulw-loop / ulw-loop");
 		expect(text).toContain('short_description: "Goal-like ultrawork loop for systematic decomposition"');
-		expect(text).toContain("Use $ulw-loop");
 	});
 
 	it("#given Codex dollar hinting #when querying ulw-loop #then ulw-loop remains discoverable as an alias", async () => {
@@ -172,7 +169,7 @@ describe("skills/ulw-loop/SKILL.md", () => {
 				].join("\n"),
 			);
 
-			const result = await runShell(`${bootstrap}\n\"$ULW_LOOP_NODE\" \"$ULW_LOOP_CLI\" ulw-loop status --json`, {
+			const result = await runShell(`${bootstrap}\n"$ULW_LOOP_NODE" "$ULW_LOOP_CLI" ulw-loop status --json`, {
 				...process.env,
 				CODEX_HOME: codexHome,
 				HOME: home,
@@ -181,7 +178,6 @@ describe("skills/ulw-loop/SKILL.md", () => {
 
 			expect(result.code).toBe(0);
 			expect(result.stdout).toContain('"source":"cached-ulw-loop"');
-			expect(result.stderr).not.toContain("unknown command");
 		} finally {
 			await rm(root, { recursive: true, force: true });
 		}
@@ -189,27 +185,7 @@ describe("skills/ulw-loop/SKILL.md", () => {
 
 });
 
-describe("source LOC budget", () => {
-	it("every source file stays at or under 250 pure LOC", async () => {
-		const files = [
-			"src/types.ts", "src/paths.ts", "src/plan-io.ts", "src/plan-crud.ts", "src/goal-status.ts",
-			"src/evidence.ts", "src/quality-gate.ts", "src/quality-gate-verdicts.ts", "src/checkpoint.ts", "src/review-blockers.ts",
-			"src/stop-resume-hook.ts", "src/spawn-guard.ts",
-			"src/steering.ts", "src/codex-goal-instruction.ts", "src/codex-goal-snapshot.ts", "src/codex-hook.ts",
-			"src/cli.ts", "src/cli-arg-parser.ts", "src/cli-output.ts", "src/cli-steering.ts", "src/cli-commands.ts",
-		];
-		for (const file of files) {
-			const text = await readText(file);
-			const pure = text.split("\n").filter((line) => {
-				const trimmed = line.trim();
-				return trimmed.length > 0 && !trimmed.startsWith("//");
-			}).length;
-			expect(pure, `${file} pure LOC`).toBeLessThanOrEqual(250);
-		}
-	});
-});
-
-describe("README implementation contract", () => {
+	describe("README implementation contract", () => {
 	it("#given the README #when subcommands are inspected #then every implemented CLI subcommand is documented", async () => {
 		const readme = await readText("README.md");
 
@@ -218,14 +194,6 @@ describe("README implementation contract", () => {
 		}
 	});
 
-	it("#given the README #when stale scaffold language is checked #then it is absent", async () => {
-		const readme = await readText("README.md");
-
-		expect(readme).not.toMatch(/scaffold only/i);
-		expect(readme).not.toMatch(/Wave 1/i);
-		expect(readme).not.toMatch(/lands in later waves/i);
-	});
-
 	it("#given the README #when hooks are described #then both hook channels are documented", async () => {
 		const readme = await readText("README.md");
 

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

@@ -7,6 +7,7 @@ import {
 	isWithinAttemptDir,
 	normalizeUlwLoopSessionId,
 	repoRelative,
+	resolveUlwLoopSessionIdFromEnv,
 	ulwLoopBriefPath,
 	ulwLoopDir,
 	ulwLoopGoalsPath,
@@ -25,6 +26,14 @@ describe("ulwLoopDir(repo)", () => {
 	});
 });
 
+describe("resolveUlwLoopSessionIdFromEnv", () => {
+	it("#given a Senpi session env #when resolving scope #then uses the current Pi session id", () => {
+		expect(resolveUlwLoopSessionIdFromEnv({ PI_SESSION_ID: "01a00baf-feed-7f4d-a4a9-b8345c67cf72" })).toBe(
+			"01a00baf-feed-7f4d-a4a9-b8345c67cf72",
+		);
+	});
+});
+
 describe("ulw-loop*Path helpers", () => {
 	it("compose artifact filenames under ulwLoopDir", () => {
 		// when/then

package/packages/omo-codex/plugin/components/ulw-loop/test/plan-io-cross-process.test.ts

@@ -0,0 +1,106 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { UlwLoopPlan } from "../src/types.ts";
+
+type EvidenceModule = typeof import("../src/evidence.ts");
+
+const NOW = "2026-09-07T00:00:00.000Z";
+const SCOPE = { sessionId: "s1" } as const;
+const CRITERIA = ["C001", "C002", "C003"] as const;
+
+let repoRoot: string;
+
+beforeEach(async () => {
+	repoRoot = await mkdtemp(join(tmpdir(), "ulw-cross-process-"));
+	await mkdir(join(repoRoot, ".omo", "ulw-loop", "s1"), { recursive: true });
+	await writeFile(join(repoRoot, ".omo", "ulw-loop", "s1", "goals.json"), `${JSON.stringify(plan(), null, 2)}\n`);
+	await writeFile(join(repoRoot, ".omo", "ulw-loop", "s1", "ledger.jsonl"), "");
+});
+
+afterEach(async () => {
+	vi.resetModules();
+	await rm(repoRoot, { recursive: true, force: true });
+});
+
+function plan(): UlwLoopPlan {
+	return {
+		version: 1,
+		evidenceLayoutVersion: 2,
+		createdAt: NOW,
+		updatedAt: NOW,
+		briefPath: ".omo/ulw-loop/s1/brief.md",
+		goalsPath: ".omo/ulw-loop/s1/goals.json",
+		ledgerPath: ".omo/ulw-loop/s1/ledger.jsonl",
+		codexGoalMode: "aggregate",
+		activeGoalId: "G001",
+		goals: [
+			{
+				id: "G001",
+				title: "Goal one",
+				objective: "Goal one",
+				status: "in_progress",
+				attempt: 1,
+				createdAt: NOW,
+				updatedAt: NOW,
+				successCriteria: CRITERIA.map((id) => ({
+					id,
+					scenario: `scenario ${id}`,
+					userModel: "happy",
+					expectedEvidence: "evidence",
+					essential: true,
+					capturedEvidence: null,
+					status: "pending",
+				})),
+			},
+		],
+	};
+}
+
+// Each isolated import evaluates plan-io again, so every instance owns a fresh
+// in-process promise chain: the same situation as separate CLI processes
+// sharing one state directory.
+async function loadIsolatedEvidenceModule(): Promise<EvidenceModule> {
+	vi.resetModules();
+	return await import("../src/evidence.ts");
+}
+
+async function readPlanFile(): Promise<UlwLoopPlan> {
+	return JSON.parse(await readFile(join(repoRoot, ".omo", "ulw-loop", "s1", "goals.json"), "utf8"));
+}
+
+async function readLedgerKinds(): Promise<readonly string[]> {
+	const raw = await readFile(join(repoRoot, ".omo", "ulw-loop", "s1", "ledger.jsonl"), "utf8");
+	return raw
+		.split("\n")
+		.filter((line) => line.trim().length > 0)
+		.map((line) => JSON.parse(line).kind);
+}
+
+describe("record-evidence across independent module instances", () => {
+	describe("#given three evidence writers that share only the state directory", () => {
+		it("#when they record different criteria concurrently #then every criterion lands in goals.json", async () => {
+			const writers: { readonly criterionId: string; readonly module: EvidenceModule }[] = [];
+			for (const criterionId of CRITERIA) {
+				writers.push({ criterionId, module: await loadIsolatedEvidenceModule() });
+			}
+
+			await Promise.all(
+				writers.map(({ criterionId, module }) =>
+					module.recordEvidence(
+						repoRoot,
+						{ goalId: "G001", criterionId, status: "pass", evidence: `proof ${criterionId}` },
+						SCOPE,
+					),
+				),
+			);
+
+			const persisted = await readPlanFile();
+			const statuses = persisted.goals[0]?.successCriteria.map((criterion) => criterion.status);
+			expect(statuses).toEqual(["pass", "pass", "pass"]);
+			expect(await readLedgerKinds()).toEqual(["evidence_captured", "evidence_captured", "evidence_captured"]);
+		});
+	});
+});

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

@@ -1,3 +1,4 @@
+import { existsSync } from "node:fs";
 import { appendFile, copyFile, mkdir, mkdtemp, readdir, readFile, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -140,8 +141,8 @@ describe("readUlwLoopPlan", () => {
 		const legacyObjective = "Complete all ulw-loop stories in .omo/ulw-loop/goals.json: G001 Build auth service";
 		await writeRawPlan(repoRoot, makePlan({ codexObjective: legacyObjective }));
 
-		// when
-		const plan = await readUlwLoopPlan(repoRoot);
+		// when: read inside the mutation lock, the way every mutating command does
+		const plan = await withUlwLoopMutationLock(repoRoot, () => readUlwLoopPlan(repoRoot));
 
 		// then
 		expect(plan.codexObjective).toBe(STABLE_OBJECTIVE);
@@ -155,6 +156,39 @@ describe("readUlwLoopPlan", () => {
 			before: { codexObjective: legacyObjective },
 		});
 	});
+
+	it("readUlwLoopPlan refuses to migrate a legacy aggregate plan outside the mutation lock (no unlocked write on a read path)", async () => {
+		// given: the same legacy plan, but the read is not wrapped in withUlwLoopMutationLock
+		const legacyObjective = "Complete all ulw-loop stories in .omo/ulw-loop/goals.json: G001 Build auth service";
+		await writeRawPlan(repoRoot, makePlan({ codexObjective: legacyObjective }));
+
+		// when
+		let caught: unknown;
+		try {
+			await readUlwLoopPlan(repoRoot);
+		} catch (error) {
+			caught = error;
+		}
+
+		// then: it refuses with a recovery hint and writes nothing
+		expect(caught).toBeInstanceOf(UlwLoopError);
+		expect((caught as UlwLoopError).code).toBe("ULW_LOOP_MIGRATION_REQUIRED");
+		const persisted = JSON.parse(await readFile(ulwLoopGoalsPath(repoRoot), "utf8"));
+		expect(persisted.codexObjective).toBe(legacyObjective);
+		expect(existsSync(ulwLoopLedgerPath(repoRoot))).toBe(false);
+	});
+
+	it("a read of an already-migrated plan outside the lock still succeeds", async () => {
+		// given
+		await writeRawPlan(repoRoot, makePlan({ codexObjective: STABLE_OBJECTIVE }));
+
+		// when
+		const plan = await readUlwLoopPlan(repoRoot);
+
+		// then
+		expect(plan.codexObjective).toBe(STABLE_OBJECTIVE);
+		expect(existsSync(ulwLoopLedgerPath(repoRoot))).toBe(false);
+	});
 });
 
 describe("writePlan", () => {