oh-my-opencode 5.0.0-beta.60 → 5.0.0-beta.63

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

@@ -2,7 +2,6 @@ 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";
-import { setImmediate as tick } from "node:timers/promises";
 import { beforeEach, describe, expect, it } from "vitest";
 import { ulwLoopDir, ulwLoopGoalsPath, ulwLoopLedgerPath } from "../src/paths.js";
 import {
@@ -15,6 +14,7 @@ import {
 } from "../src/plan-io.js";
 import type { UlwLoopItem, UlwLoopLedgerEntry, UlwLoopPlan, UlwLoopSteeringAudit } from "../src/types.js";
 import { UlwLoopError } from "../src/types.js";
+import { barrier } from "./fixtures/barrier.js";
 
 const NOW = "2026-05-23T00:00:00.000Z";
 const STABLE_OBJECTIVE =
@@ -97,6 +97,12 @@ async function makeRepo(): Promise<string> {
 	return mkdtemp(join(tmpdir(), "ug-io-"));
 }
 
+async function makeLedgerRepo(): Promise<string> {
+	const root = await makeRepo();
+	await writePlan(root, makePlan());
+	return root;
+}
+
 async function writeRawPlan(repoRoot: string, plan: UlwLoopPlan): Promise<void> {
 	await mkdir(ulwLoopDir(repoRoot), { recursive: true });
 	await writeFile(ulwLoopGoalsPath(repoRoot), `${JSON.stringify(plan, null, 2)}\n`, "utf8");
@@ -136,13 +142,17 @@ describe("readUlwLoopPlan", () => {
 		expect(plan.goals[0]?.successCriteria).toHaveLength(3);
 	});
 
-	it("migrates legacy aggregate objective on read + writes aggregate_objective_migrated ledger entry + retains alias", async () => {
+	it("migrates legacy aggregate objective in memory and folds its audit into the enclosing commit", async () => {
 		// given
 		const legacyObjective = "Complete all ulw-loop stories in .omo/ulw-loop/goals.json: G001 Build auth service";
 		await writeRawPlan(repoRoot, makePlan({ codexObjective: legacyObjective }));
 
 		// when: read inside the mutation lock, the way every mutating command does
-		const plan = await withUlwLoopMutationLock(repoRoot, () => readUlwLoopPlan(repoRoot));
+		const plan = await withUlwLoopMutationLock(repoRoot, async () => {
+			const migrated = await readUlwLoopPlan(repoRoot);
+			await writePlan(repoRoot, migrated);
+			return migrated;
+		});
 
 		// then
 		expect(plan.codexObjective).toBe(STABLE_OBJECTIVE);
@@ -157,22 +167,17 @@ describe("readUlwLoopPlan", () => {
 		});
 	});
 
-	it("readUlwLoopPlan refuses to migrate a legacy aggregate plan outside the mutation lock (no unlocked write on a read path)", async () => {
+	it("readUlwLoopPlan migrates a legacy aggregate plan in memory outside the mutation lock without writing", 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 migrated = await readUlwLoopPlan(repoRoot);
+
+		// then: only the returned shape changes
+		expect(migrated.codexObjective).toBe(STABLE_OBJECTIVE);
+		expect(migrated.codexObjectiveAliases).toContain(legacyObjective);
 		const persisted = JSON.parse(await readFile(ulwLoopGoalsPath(repoRoot), "utf8"));
 		expect(persisted.codexObjective).toBe(legacyObjective);
 		expect(existsSync(ulwLoopLedgerPath(repoRoot))).toBe(false);
@@ -211,7 +216,8 @@ describe("writePlan", () => {
 		await writePlan(repoRoot, makePlan({ codexObjective: "first" }));
 
 		// when
-		await writePlan(repoRoot, makePlan({ codexObjective: "second" }));
+		const current = await readUlwLoopPlan(repoRoot);
+		await writePlan(repoRoot, { ...current, codexObjective: "second" });
 
 		// then
 		expect(JSON.parse(await readFile(ulwLoopGoalsPath(repoRoot), "utf8"))).toMatchObject({
@@ -223,7 +229,7 @@ describe("writePlan", () => {
 describe("appendLedger", () => {
 	it("appends a single JSONL line to ledger.jsonl", async () => {
 		// given
-		const repoRoot = await makeRepo();
+		const repoRoot = await makeLedgerRepo();
 		const ledgerEntry = entry("goal_started");
 
 		// when
@@ -236,6 +242,7 @@ describe("appendLedger", () => {
 	it("creates ledger.jsonl if missing", async () => {
 		// given
 		const repoRoot = await makeRepo();
+		await writeRawPlan(repoRoot, makePlan());
 
 		// when
 		await appendLedger(repoRoot, entry("goal_completed"));
@@ -246,7 +253,7 @@ describe("appendLedger", () => {
 
 	it("preserves prior entries", async () => {
 		// given
-		const repoRoot = await makeRepo();
+		const repoRoot = await makeLedgerRepo();
 		const first = entry("goal_started");
 		const second = entry("goal_completed");
 
@@ -262,7 +269,7 @@ describe("appendLedger", () => {
 describe("readSteeringLedgerEntries", () => {
 	it("returns only steering-related event kinds", async () => {
 		// given
-		const repoRoot = await makeRepo();
+		const repoRoot = await makeLedgerRepo();
 		await appendLedger(repoRoot, entry("steering_accepted"));
 		await appendLedger(repoRoot, entry("goal_started"));
 		await appendLedger(repoRoot, entry("steering_rejected"));
@@ -297,7 +304,7 @@ describe("findAcceptedSteeringLedgerEntry", () => {
 		],
 	] as const)("finds an accepted entry by %s", async (_name, target) => {
 		// given
-		const repoRoot = await makeRepo();
+		const repoRoot = await makeLedgerRepo();
 		await appendLedger(repoRoot, steeringEntry("steering_accepted", steeringAudit({ idempotencyKey: "other-key" })));
 		await appendLedger(repoRoot, target);
 
@@ -310,7 +317,7 @@ describe("findAcceptedSteeringLedgerEntry", () => {
 
 	it("skips a rejected entry carrying the same key", async () => {
 		// given
-		const repoRoot = await makeRepo();
+		const repoRoot = await makeLedgerRepo();
 		await appendLedger(
 			repoRoot,
 			steeringEntry("steering_rejected", rejectedSteeringAudit({ idempotencyKey: "needle-key" })),
@@ -322,7 +329,7 @@ describe("findAcceptedSteeringLedgerEntry", () => {
 
 	it("returns the accepted entry even when a rejected one with the same key precedes it", async () => {
 		// given
-		const repoRoot = await makeRepo();
+		const repoRoot = await makeLedgerRepo();
 		const accepted = steeringEntry("steering_accepted", steeringAudit({ idempotencyKey: "needle-key" }));
 		await appendLedger(
 			repoRoot,
@@ -344,7 +351,7 @@ describe("findAcceptedSteeringLedgerEntry", () => {
 
 	it("ignores the key when it only appears in non-steering entries", async () => {
 		// given
-		const repoRoot = await makeRepo();
+		const repoRoot = await makeLedgerRepo();
 		await appendLedger(repoRoot, { at: NOW, kind: "goal_completed", goalId: "G001", idempotencyKey: "needle-key" });
 		await appendLedger(repoRoot, { at: NOW, kind: "evidence_captured", goalId: "G001", evidence: "needle-key" });
 
@@ -354,7 +361,7 @@ describe("findAcceptedSteeringLedgerEntry", () => {
 
 	it("ignores an accepted entry whose key only appears in evidence text", async () => {
 		// given
-		const repoRoot = await makeRepo();
+		const repoRoot = await makeLedgerRepo();
 		await appendLedger(repoRoot, steeringEntry("steering_accepted", steeringAudit({ evidence: "needle-key" })));
 
 		// when/then
@@ -440,13 +447,13 @@ describe("withUlwLoopMutationLock", () => {
 		const body = async (): Promise<void> => {
 			active += 1;
 			maxActive = Math.max(maxActive, active);
-			await tick();
+			await Promise.resolve();
 			active -= 1;
 		};
 
 		// when
 		await Promise.all([1, 2, 3].map(() => withUlwLoopMutationLock(repoRoot, body)));
-		await tick();
+		await Promise.resolve();
 		await Promise.all([1, 2].map(() => withUlwLoopMutationLock(repoRoot, body)));
 
 		// then
@@ -457,7 +464,8 @@ describe("withUlwLoopMutationLock", () => {
 		// given
 		const repoRoot = await makeRepo();
 		const events: string[] = [];
-		let releaseSecond = false;
+		const releaseSecond = barrier();
+		const enteredSecond = barrier();
 
 		// when
 		const first = withUlwLoopMutationLock(repoRoot, async () => {
@@ -465,15 +473,16 @@ describe("withUlwLoopMutationLock", () => {
 		});
 		const second = withUlwLoopMutationLock(repoRoot, async () => {
 			events.push("second:start");
-			while (!releaseSecond) await tick();
+			enteredSecond.resolve();
+			await releaseSecond.promise;
 			events.push("second:end");
 		});
 		await first;
-		await tick();
+		await enteredSecond.promise;
 		const third = withUlwLoopMutationLock(repoRoot, async () => {
 			events.push("third");
 		});
-		releaseSecond = true;
+		releaseSecond.resolve();
 		await Promise.all([second, third]);
 
 		// then
@@ -485,18 +494,21 @@ describe("withUlwLoopMutationLock", () => {
 		const rootA = await makeRepo();
 		const rootB = await makeRepo();
 		const events: string[] = [];
-		let releaseA = false;
+		const releaseA = barrier();
+		const enteredA = barrier();
 
 		// when
 		const held = withUlwLoopMutationLock(rootA, async () => {
 			events.push("a:start");
-			while (!releaseA) await tick();
+			enteredA.resolve();
+			await releaseA.promise;
 			events.push("a:end");
 		});
+		await enteredA.promise;
 		await withUlwLoopMutationLock(rootB, async () => {
 			events.push("b");
 		});
-		releaseA = true;
+		releaseA.resolve();
 		await held;
 
 		// then
@@ -508,21 +520,24 @@ describe("withUlwLoopMutationLock", () => {
 		const repoRoot = await makeRepo();
 		const scoped = { sessionId: "session-a" };
 		const events: string[] = [];
-		let releaseScoped = false;
+		const releaseScoped = barrier();
+		const enteredScoped = barrier();
 
 		// when
 		const heldScoped = withUlwLoopMutationLock(repoRoot, scoped, async () => {
 			events.push("scoped-1:start");
-			while (!releaseScoped) await tick();
+			enteredScoped.resolve();
+			await releaseScoped.promise;
 			events.push("scoped-1:end");
 		});
+		await enteredScoped.promise;
 		const queuedScoped = withUlwLoopMutationLock(repoRoot, scoped, async () => {
 			events.push("scoped-2");
 		});
 		await withUlwLoopMutationLock(repoRoot, async () => {
 			events.push("root-scope");
 		});
-		releaseScoped = true;
+		releaseScoped.resolve();
 		await Promise.all([heldScoped, queuedScoped]);
 
 		// then

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

@@ -0,0 +1,72 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { ulwLoopDir } from "../src/paths.js";
+import { createUlwLoopPlan } from "../src/plan-crud.js";
+import { readNewestRecord, readRecords, reconcilePlan } from "../src/plan-log.js";
+import type { UlwLoopPlan } from "../src/types.js";
+
+let root: string;
+let dir: string;
+let base: UlwLoopPlan;
+const scope = { sessionId: "newest-record" };
+beforeEach(async () => {
+	root = await mkdtemp(join(tmpdir(), "ulw-newest-"));
+	dir = ulwLoopDir(root, scope);
+	base = await createUlwLoopPlan(root, { brief: "initial" }, scope);
+});
+afterEach(async () => {
+	await rm(root, { recursive: true, force: true });
+});
+// The names are deliberately mixed-width: lexicographically "000000010.json" sorts BEFORE "00000009.json",
+// so only numeric ordering of the parsed revision picks revision 10 as the newest record.
+function seedRecord(name: string, revision: number, brief: string): UlwLoopPlan {
+	const plan: UlwLoopPlan = { ...base, revision, brief };
+	mkdirSync(join(dir, "revisions"), { recursive: true });
+	writeFileSync(
+		join(dir, "revisions", name),
+		`${JSON.stringify({ version: 1, revision, plan, ledger: [{ at: "now", kind: "goal_added", revision, id: `${revision}-0` }] })}\n`,
+	);
+	return plan;
+}
+
+describe("#given a commit log whose newest record is the only one a plan read needs", () => {
+	it("#when the newest record is valid #then it wins over older records and a stale goals cache", async () => {
+		seedRecord("00000009.json", 9, "nine");
+		const newest = seedRecord("000000010.json", 10, "ten");
+
+		expect(base.revision).toBe(1);
+		expect(readNewestRecord(dir)?.revision).toBe(10);
+		expect(reconcilePlan(dir)).toEqual(newest);
+	});
+	it("#when the newest record is corrupt #then the newest valid older record wins", () => {
+		const older = seedRecord("00000009.json", 9, "nine");
+		writeFileSync(join(dir, "revisions", "000000010.json"), "{not json");
+
+		expect(readNewestRecord(dir)?.revision).toBe(9);
+		expect(reconcilePlan(dir)).toEqual(older);
+	});
+	it("#when an OLDER record is unreadable for a non-syntax reason #then the read stops at the newest record", () => {
+		const newest = seedRecord("000000010.json", 10, "ten");
+		rmSync(join(dir, "revisions", "00000001.json"));
+		mkdirSync(join(dir, "revisions", "00000001.json"));
+
+		expect(reconcilePlan(dir)).toEqual(newest);
+		expect(readNewestRecord(dir)).toEqual({
+			version: 1,
+			revision: 10,
+			plan: newest,
+			ledger: [{ at: "now", kind: "goal_added", revision: 10, id: "10-0" }],
+		});
+		expect(() => readRecords(dir)).toThrow(/EISDIR/);
+	});
+	it("#when the NEWEST record is unreadable for a non-syntax reason #then the error propagates", () => {
+		seedRecord("00000009.json", 9, "nine");
+		mkdirSync(join(dir, "revisions", "000000010.json"));
+
+		expect(() => readNewestRecord(dir)).toThrow(/EISDIR/);
+		expect(() => reconcilePlan(dir)).toThrow(/EISDIR/);
+	});
+});

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

@@ -0,0 +1,43 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { commit } from "../src/plan-commit.js";
+import { readUlwLoopPlan, withUlwLoopMutationLock } from "../src/plan-io.js";
+import { createAgentToolkit } from "../src/sdk.js";
+import type { UlwLoopToolkitSurface } from "../src/surface.js";
+
+const directories: string[] = [];
+afterEach(async () => {
+	for (const directory of directories.splice(0)) await rm(directory, { recursive: true, force: true });
+});
+
+const surfaces: UlwLoopToolkitSurface[] = ["lazycodex", "omo-senpi"];
+describe.each(surfaces)("#given a completed plan on %s", (surface) => {
+	it("#when createGoals is called #then it rejects without overwriting, unless explicitly forced", async () => {
+		const cwd = await mkdtemp(join(tmpdir(), "sdk-completed-plan-"));
+		directories.push(cwd);
+		const scope = { sessionId: "completed-plan" };
+		const toolkit = createAgentToolkit({ cwd, ...scope, surface });
+		expect((await toolkit.createGoals({ brief: "- original" })).ok).toBe(true);
+		await withUlwLoopMutationLock(cwd, scope, async () => {
+			const plan = await readUlwLoopPlan(cwd, scope);
+			for (const goal of plan.goals) goal.status = "complete";
+			await commit(cwd, scope, { plan, entries: [] });
+		});
+		const before = await readUlwLoopPlan(cwd, scope);
+		const response = await toolkit.createGoals({ brief: "- replacement" });
+		expect(response).toMatchObject({ ok: false, error: { code: "ULW_LOOP_PLAN_EXISTS_COMPLETE" } });
+		if (response.ok) throw new Error("expected createGoals to fail");
+		if (surface === "omo-senpi") {
+			expect(response.error.message).toMatch(/agentToolkit\.createGoals\(/);
+			expect(response.error.message).not.toMatch(/omo-agent-toolkit ulw-loop/);
+		} else {
+			expect(response.error.message).toMatch(/omo-agent-toolkit ulw-loop create-goals/);
+			expect(response.error.message).not.toMatch(/agentToolkit\./);
+		}
+		expect(await readUlwLoopPlan(cwd, scope)).toEqual(before);
+		expect((await toolkit.createGoals({ brief: "- replacement", force: true })).ok).toBe(true);
+		expect((await readUlwLoopPlan(cwd, scope)).goals[0]?.id).toBe("G001-replacement");
+	});
+});

package/packages/omo-codex/plugin/components/ulw-loop/test/sdk-driver-states.test.ts

@@ -0,0 +1,145 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { readUlwLoopPlan } from "../src/plan-io.js";
+import { createAgentToolkit } from "../src/sdk.js";
+
+const workDirs: string[] = [];
+
+afterEach(async () => {
+	for (const dir of workDirs.splice(0)) await rm(dir, { recursive: true, force: true });
+});
+
+interface Seeded {
+	readonly cwd: string;
+	readonly sessionId: string;
+	readonly goalId: string;
+	readonly objective: string;
+}
+
+// One fixture shape for every driver state: a real plan whose first goal is ready to close, so the
+// only thing under test is what the driver snapshot does to the checkpoint.
+async function seed(sessionId: string): Promise<Seeded> {
+	const cwd = await mkdtemp(join(tmpdir(), "ulw-driver-"));
+	workDirs.push(cwd);
+	const toolkit = createAgentToolkit({ cwd, sessionId, surface: "omo-senpi" });
+	const created = await toolkit.createGoals({ brief: "- alpha goal\n- beta goal" });
+	if (!created.ok) throw new Error("fixture could not create goals");
+	const started = await toolkit.completeGoals({});
+	if (!started.ok || started.operation !== "complete-goals" || "done" in started.result)
+		throw new Error("fixture could not start a goal");
+	const goalId = started.result.goal.id;
+	const criteria = await toolkit.criteria({ goalId });
+	if (!criteria.ok || criteria.operation !== "criteria") throw new Error("fixture has no criteria");
+	for (const criterion of criteria.result.criteria) {
+		const recorded = await toolkit.recordEvidence({
+			goalId,
+			criterionId: criterion.id,
+			status: "pass",
+			evidence: "driver-state fixture proof",
+		});
+		if (!recorded.ok) throw new Error("fixture could not record evidence");
+	}
+	const plan = await readUlwLoopPlan(cwd, { sessionId });
+	return { cwd, sessionId, goalId, objective: plan.codexObjective ?? "" };
+}
+
+async function closeWith(seeded: Seeded, snapshot?: Record<string, unknown>) {
+	const toolkit = createAgentToolkit({ cwd: seeded.cwd, sessionId: seeded.sessionId, surface: "omo-senpi" });
+	return toolkit.checkpoint({
+		goalId: seeded.goalId,
+		status: "complete",
+		evidence: "driver-state checkpoint",
+		...(snapshot === undefined ? {} : { codexGoalJson: JSON.stringify(snapshot) }),
+	});
+}
+
+describe("SDK driver-goal states", () => {
+	describe("#given no driver snapshot", () => {
+		it("#when the goal is checkpointed #then it completes and advises creating the driver goal", async () => {
+			const seeded = await seed("driver-absent");
+
+			const closed = await closeWith(seeded);
+
+			expect(closed.ok).toBe(true);
+			if (closed.ok) expect(closed.nextActions.join(" ")).toContain("create_goal");
+		});
+	});
+
+	describe("#given an active driver carrying the plan objective", () => {
+		it("#when the goal is checkpointed #then it completes with no objective difference reported", async () => {
+			const seeded = await seed("driver-active");
+
+			const closed = await closeWith(seeded, { goal: { objective: seeded.objective, status: "active" } });
+
+			expect(closed.ok).toBe(true);
+			if (closed.ok) {
+				expect([...(closed.warnings ?? []), ...closed.nextActions].join(" ")).not.toContain(
+					"driver_objective_differs",
+				);
+			}
+		});
+	});
+
+	describe("#given a driver completed before the plan finished", () => {
+		it("#when the goal is checkpointed #then it completes and advises re-creating the driver", async () => {
+			const seeded = await seed("driver-early");
+
+			const closed = await closeWith(seeded, { goal: { objective: seeded.objective, status: "complete" } });
+
+			expect(closed.ok).toBe(true);
+			if (closed.ok) expect(closed.nextActions.join(" ")).toContain("create_goal");
+		});
+	});
+
+	describe("#given a driver the harness has limited", () => {
+		for (const status of ["paused", "usage_limited", "budget_limited"] as const) {
+			it(`#when the driver is ${status} #then the checkpoint still completes and advises resuming it`, async () => {
+				const seeded = await seed(`driver-${status}`);
+
+				const closed = await closeWith(seeded, { goal: { objective: seeded.objective, status } });
+
+				expect(closed.ok).toBe(true);
+				if (closed.ok) expect(closed.nextActions.join(" ")).toContain("/goal resume");
+			});
+		}
+	});
+
+	describe("#given a driver whose objective differs from the plan", () => {
+		it("#when the goal is checkpointed #then the difference is reported, never a rejection", async () => {
+			const seeded = await seed("driver-differs");
+
+			const closed = await closeWith(seeded, { goal: { objective: "a different objective", status: "active" } });
+
+			expect(closed.ok).toBe(true);
+			if (closed.ok) {
+				expect([...(closed.warnings ?? []), ...closed.nextActions].join(" ")).toContain("driver_objective_differs");
+			}
+		});
+	});
+
+	describe("#given snapshot input that is neither JSON nor a readable path", () => {
+		it("#when the goal is checkpointed #then the typed error is returned and the goal stays open", async () => {
+			const seeded = await seed("driver-malformed");
+
+			const closed = await closeWith(seeded);
+			expect(closed.ok).toBe(true);
+
+			const second = await seed("driver-malformed-2");
+			const toolkit = createAgentToolkit({ cwd: second.cwd, sessionId: second.sessionId, surface: "omo-senpi" });
+			const rejected = await toolkit.checkpoint({
+				goalId: second.goalId,
+				status: "complete",
+				evidence: "driver-state checkpoint",
+				codexGoalJson: "not json and not a path",
+			});
+
+			expect(rejected.ok).toBe(false);
+			if (!rejected.ok) expect(rejected.error.code).toBe("ULW_LOOP_CODEX_GOAL_JSON_INVALID");
+			const plan = await readUlwLoopPlan(second.cwd, { sessionId: second.sessionId });
+			expect(plan.goals.find((goal) => goal.id === second.goalId)?.status).not.toBe("complete");
+		});
+	});
+});

package/packages/omo-codex/plugin/components/ulw-loop/test/sdk-session-context.test.ts

@@ -72,6 +72,27 @@ async function seedSession(
 }
 
 describe("agent toolkit session context", () => {
+	describe("#given a session id that normalizes to null", () => {
+		it("#when an omo-senpi SDK context is created #then it rejects without creating session state", async () => {
+			const cwd = await makeWorkdir();
+
+			expect(() => createAgentToolkit({ cwd, sessionId: "../../x", surface: "omo-senpi" })).toThrowError(
+				expect.objectContaining({ code: "ULW_LOOP_SESSION_ID_INVALID" }),
+			);
+			expect(existsSync(join(cwd, ".omo", "ulw-loop"))).toBe(false);
+		});
+	});
+
+	describe("#given a blank session id", () => {
+		it("#when an SDK context is created #then it reports the required-id error", async () => {
+			const cwd = await makeWorkdir();
+
+			expect(() => createAgentToolkit({ cwd, sessionId: "   ", surface: "omo-senpi" })).toThrowError(
+				expect.objectContaining({ code: "ULW_LOOP_SESSION_ID_REQUIRED" }),
+			);
+		});
+	});
+
 	describe("#given a plan written under session A", () => {
 		it("#when session B reads through its own context #then the read fails closed instead of borrowing A", async () => {
 			const cwd = await makeWorkdir();

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

@@ -6,7 +6,13 @@ import { Readable, Writable } from "node:stream";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import type { PreToolUsePayload } from "../src/codex-hook.ts";
-import { applySpawnGuards, DEFAULT_FANOUT_LIMIT, runSpawnAdmissionRecorderCli } from "../src/spawn-guard.ts";
+// Budget/artifact behavior is independent of role admission; the native entry
+// point and its composition are covered in spawn-role-matrix.test.ts.
+import {
+	applySpawnBudgetGuards as applySpawnGuards,
+	DEFAULT_FANOUT_LIMIT,
+	runSpawnAdmissionRecorderCli,
+} from "../src/spawn-guard.ts";
 
 let workDir: string;
 let originalLimit: string | undefined;