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

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

@@ -0,0 +1,190 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { mkdtemp, 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 { PreToolUsePayload } from "../src/codex-hook.js";
+import { ulwLoopDir } from "../src/paths.js";
+import { commit, materialize, withCommitHooks } from "../src/plan-commit.js";
+import { createUlwLoopPlan } from "../src/plan-crud.js";
+import {
+	planExists,
+	readLedger,
+	readUlwLoopPlan,
+	withMutationLockOptions,
+	withUlwLoopMutationLock,
+} from "../src/plan-io.js";
+import { applySpawnBudgetGuards } from "../src/spawn-guard.js";
+import { runStopResumeHook } from "../src/stop-resume-hook.js";
+import { childWriter, cleanupWriters } from "./fixtures/commit-child.js";
+import { leaseClock } from "./fixtures/lease-clock.js";
+
+let root: string;
+let dir: string;
+const scope = { sessionId: "commit-log" };
+beforeEach(async () => {
+	root = await mkdtemp(join(tmpdir(), "ulw-recovery-"));
+	dir = ulwLoopDir(root, scope);
+});
+afterEach(async () => {
+	await cleanupWriters();
+	vi.unstubAllEnvs();
+	await rm(root, { recursive: true, force: true });
+});
+function signal() {
+	let resolve: () => void = () => {
+		throw new Error("signal not initialized");
+	};
+	const promise = new Promise<void>((done, reject) => {
+		const timeout = setTimeout(() => reject(new Error("signal timed out")), 5_000);
+		resolve = () => {
+			clearTimeout(timeout);
+			done();
+		};
+	});
+	return { promise, resolve };
+}
+function views() {
+	return ["goals.json", "ledger.jsonl", "brief.md"].map((name) => readFileSync(join(dir, name), "utf8"));
+}
+describe("#given crash recovery through public surfaces", () => {
+	it("#when (7b) only revision one exists #then both hooks and existence gates use it", async () => {
+		const plan = await createUlwLoopPlan(root, { brief: "unfinished" }, scope);
+		for (const name of ["goals.json", "ledger.jsonl", "brief.md"]) await rm(join(dir, name));
+		expect(readdirSync(join(dir, "revisions"))).toEqual(["00000001.json"]);
+		expect(planExists(root, scope)).toBe(true);
+		expect((await readUlwLoopPlan(root, scope)).revision).toBe(1);
+		const payload = {
+			session_id: scope.sessionId,
+			turn_id: "turn",
+			cwd: root,
+			model: "test",
+			permission_mode: "default",
+		};
+		const stop = {
+			...payload,
+			hook_event_name: "Stop",
+			transcript_path: join(root, "transcript"),
+			stop_hook_active: false,
+		};
+		expect(JSON.parse(runStopResumeHook(stop)).decision).toBe("block");
+		expect(JSON.parse(readFileSync(join(dir, `auto-resume-${plan.goals[0]?.id}.json`), "utf8")).ledgerLineCount).toBe(
+			1,
+		);
+		vi.stubEnv("OMO_SPAWN_FANOUT_LIMIT", "1");
+		vi.stubEnv("PLUGIN_DATA", join(root, "plugin-data"));
+		const spawn: PreToolUsePayload = {
+			...payload,
+			hook_event_name: "PreToolUse",
+			transcript_path: null,
+			tool_name: "spawn_agent",
+			tool_use_id: "tool",
+			tool_input: {},
+		};
+		expect(applySpawnBudgetGuards(spawn)).toBe("");
+		expect(JSON.parse(applySpawnBudgetGuards(spawn)).hookSpecificOutput.permissionDecision).toBe("deny");
+	});
+	it("#when (7c) two materializers overlap #then every public inode is complete even if a view regresses", async () => {
+		const plan = await createUlwLoopPlan(root, { brief: "old" }, scope);
+		const old = views();
+		await withCommitHooks(
+			{
+				afterCommit: () => {
+					throw new Error("crash");
+				},
+			},
+			() =>
+				commit(root, scope, {
+					plan: { ...plan, brief: "middle\n" },
+					entries: [{ at: "middle", kind: "goal_added" }],
+				}),
+		).catch((error: unknown) => {
+			expect(error).toBeInstanceOf(Error);
+		});
+		const middleViews = [
+			`${JSON.stringify(await readUlwLoopPlan(root, scope), null, 2)}\n`,
+			`${readLedger(root, scope)
+				.map((entry) => JSON.stringify(entry))
+				.join("\n")}\n`,
+			"middle\n",
+		];
+		const partial = signal();
+		const resume = signal();
+		const first = withCommitHooks(
+			{
+				writeView: async (path, content) => {
+					if (path.endsWith("ledger.jsonl")) {
+						await writeFile(path, content.slice(0, 5));
+						partial.resolve();
+						await resume.promise;
+					}
+					await writeFile(path, content);
+				},
+			},
+			() => materialize(dir),
+		);
+		await partial.promise;
+		expect(readFileSync(join(dir, "ledger.jsonl"), "utf8")).toBe(old[1]);
+		const latest = await readUlwLoopPlan(root, scope);
+		await commit(root, scope, { plan: { ...latest, brief: "new\n" }, entries: [{ at: "new", kind: "goal_added" }] });
+		const newViews = views();
+		resume.resolve();
+		await first;
+		const final = views();
+		expect(() => JSON.parse(final[0] ?? "")).not.toThrow();
+		for (const line of (final[1] ?? "").trim().split("\n")) expect(() => JSON.parse(line)).not.toThrow();
+		for (const [index, content] of final.entries()) expect([middleViews[index], newViews[index]]).toContain(content);
+		expect(
+			readLedger(root, scope)
+				.map((entry) => entry.at)
+				.slice(-2),
+		).toEqual(["middle", "new"]);
+	});
+	it("#when (9) a force-recreator loses before its first possible view write #then its successor stays untouched", async () => {
+		await createUlwLoopPlan(root, { brief: "old" }, scope);
+		let successor: string[] = [];
+		let writes = 0;
+		const clock = leaseClock();
+		await expect(
+			withCommitHooks(
+				{
+					beforeMutation: async () => {
+						clock.advance(201);
+						const writer = childWriter(root, "force", clock.now());
+						expect(await writer.exited).toBe(0);
+						successor = views();
+					},
+					writeView: async (path, content) => {
+						writes += 1;
+						await writeFile(path, content);
+					},
+				},
+				() =>
+					withMutationLockOptions({ clock, leaseMs: 200, heartbeatMs: 0 }, () =>
+						createUlwLoopPlan(root, { brief: "A", force: true }, scope),
+					),
+			),
+		).rejects.toMatchObject({ code: "ULW_LOOP_LOCK_LOST" });
+		expect(writes).toBe(0);
+		expect(views()).toEqual(successor);
+		expect(readLedger(root, scope)).toHaveLength(1);
+	});
+	it("#when a locked ledger-only read follows a crash #then all views are repaired without another revision", async () => {
+		const plan = await createUlwLoopPlan(root, { brief: "old" }, scope);
+		await expect(
+			withCommitHooks(
+				{
+					afterCommit: () => {
+						throw new Error("crash");
+					},
+				},
+				() => commit(root, scope, { plan: { ...plan, brief: "new\n" }, entries: [] }),
+			),
+		).rejects.toThrow("crash");
+		await withUlwLoopMutationLock(root, scope, async () => {
+			expect(readLedger(root, scope)).toHaveLength(1);
+		});
+		expect(readFileSync(join(dir, "brief.md"), "utf8")).toBe("new\n");
+		expect(readdirSync(join(dir, "revisions"))).toHaveLength(2);
+	});
+});

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-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();