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

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

@@ -21,12 +21,17 @@ interface Seeded {
 
 // 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> {
+async function seed(sessionId: string, brief = "- alpha goal\n- beta goal"): 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" });
+	const created = await toolkit.createGoals({ brief });
 	if (!created.ok) throw new Error("fixture could not create goals");
+	return passNextGoal(cwd, sessionId);
+}
+
+async function passNextGoal(cwd: string, sessionId: string): Promise<Seeded> {
+	const toolkit = createAgentToolkit({ cwd, sessionId, surface: "omo-senpi" });
 	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");
@@ -46,6 +51,10 @@ async function seed(sessionId: string): Promise<Seeded> {
 	return { cwd, sessionId, goalId, objective: plan.codexObjective ?? "" };
 }
 
+function warningsOf(result: object): readonly string[] {
+	return "warnings" in result && Array.isArray(result.warnings) ? result.warnings : [];
+}
+
 async function closeWith(seeded: Seeded, snapshot?: Record<string, unknown>) {
 	const toolkit = createAgentToolkit({ cwd: seeded.cwd, sessionId: seeded.sessionId, surface: "omo-senpi" });
 	return toolkit.checkpoint({
@@ -108,15 +117,35 @@ describe("SDK driver-goal states", () => {
 	});
 
 	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 () => {
+		it("#when the goal is checkpointed #then the difference is a warning, never a rejection and never a next action", 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");
+				expect(warningsOf(closed.result).join(" ")).toContain("driver_objective_differs");
+				expect(closed.nextActions.join(" ")).not.toContain("driver_objective_differs");
+				expect(closed.nextActions.join(" ")).not.toContain("create_goal");
+			}
+		});
+
+		it("#when a later goal is checkpointed under the same driver #then the difference is acknowledged in the plan and not repeated", async () => {
+			const first = await seed("driver-differs-once", "- alpha goal\n- beta goal\n- gamma goal");
+			const driver = { goal: { objective: "  a different\n objective  ", status: "active" } };
+
+			const firstClose = await closeWith(first, driver);
+			const second = await passNextGoal(first.cwd, first.sessionId);
+			const secondClose = await closeWith(second, driver);
+
+			expect(firstClose.ok && secondClose.ok).toBe(true);
+			if (firstClose.ok && secondClose.ok) {
+				expect(warningsOf(firstClose.result).join(" ")).toContain("driver_objective_differs");
+				expect(warningsOf(secondClose.result)).toEqual([]);
+				expect(secondClose.nextActions).toEqual([]);
 			}
+			const plan = await readUlwLoopPlan(first.cwd, { sessionId: first.sessionId });
+			expect(plan.acknowledgedDriverObjectives).toEqual(["a different objective"]);
 		});
 	});
 

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

@@ -0,0 +1,219 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } 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, ULW_LOOP_MANIFEST, type ULW_LOOP_OPERATIONS } from "../src/sdk.js";
+
+const workDirs: string[] = [];
+afterEach(async () => {
+	for (const dir of workDirs.splice(0)) await rm(dir, { recursive: true, force: true });
+});
+
+async function fixture(sessionId: string, surface: "omo-senpi" | "lazycodex" = "omo-senpi") {
+	const cwd = await mkdtemp(join(tmpdir(), "ulw-dx-"));
+	workDirs.push(cwd);
+	const toolkit = createAgentToolkit({ cwd, sessionId, surface });
+	const created = await toolkit.createGoals({ brief: "- alpha goal\n- beta goal" });
+	if (!created.ok) throw new Error("fixture could not create goals");
+	return { cwd, toolkit };
+}
+
+describe("help() is self-describing", () => {
+	it("#given the manifest #when read #then every operation carries its camelCase method, a description, and an args map", () => {
+		const methods: Record<(typeof ULW_LOOP_OPERATIONS)[number], string> = {
+			help: "help",
+			"create-goals": "createGoals",
+			status: "status",
+			"complete-goals": "completeGoals",
+			checkpoint: "checkpoint",
+			steer: "steer",
+			"add-goal": "addGoal",
+			criteria: "criteria",
+			"record-evidence": "recordEvidence",
+			"record-review-blockers": "recordReviewBlockers",
+		};
+		for (const operation of ULW_LOOP_MANIFEST.operations) {
+			expect(operation.method).toBe(methods[operation.name]);
+			expect(operation.description.length).toBeGreaterThan(20);
+			expect(typeof operation.args).toBe("object");
+		}
+		const record = ULW_LOOP_MANIFEST.operations.find((operation) => operation.name === "record-evidence");
+		expect(record?.args).toMatchObject({ goalId: "string", criterionId: "string", evidence: "string" });
+		expect(Object.keys(record?.args ?? {})).toEqual(expect.arrayContaining(["status", "notes", "artifacts"]));
+		const add = ULW_LOOP_MANIFEST.operations.find((operation) => operation.name === "add-goal");
+		expect(Object.keys(add?.args ?? {})).toEqual(expect.arrayContaining(["title", "objective", "successCriteria"]));
+		const steer = ULW_LOOP_MANIFEST.operations.find((operation) => operation.name === "steer");
+		expect(Object.keys(steer?.args ?? {})).toEqual(
+			expect.arrayContaining([
+				"kind",
+				"source",
+				"evidence",
+				"rationale",
+				"goalId",
+				"criterionId",
+				"scenario",
+				"expectedEvidence",
+			]),
+		);
+	});
+
+	it("#given a toolkit #when help() runs #then the result is the manifest", async () => {
+		const { toolkit } = await fixture("dx-help");
+		const help = await toolkit.help();
+		expect(help.ok).toBe(true);
+		if (help.ok) expect(help.result.operations.map((operation) => operation.method)).toContain("recordEvidence");
+	});
+});
+
+describe("addGoal accepts success criteria", () => {
+	it("#given explicit successCriteria #when the goal is added #then exactly those criteria persist with sequential ids", async () => {
+		const { cwd, toolkit } = await fixture("dx-add-criteria");
+		const added = await toolkit.addGoal({
+			title: "lane",
+			objective: "ship the lane",
+			successCriteria: [
+				{ scenario: "curl -i /health returns 200", expectedEvidence: "status line captured in health.log" },
+				{
+					scenario: "malformed body returns 400",
+					expectedEvidence: "curl transcript",
+					userModel: "edge",
+					essential: false,
+				},
+			],
+		});
+		expect(added.ok).toBe(true);
+		if (!added.ok) return;
+		expect(added.result.goal.successCriteria).toEqual([
+			expect.objectContaining({
+				id: "C001",
+				scenario: "curl -i /health returns 200",
+				expectedEvidence: "status line captured in health.log",
+				userModel: "happy",
+				essential: true,
+				status: "pending",
+			}),
+			expect.objectContaining({
+				id: "C002",
+				scenario: "malformed body returns 400",
+				userModel: "edge",
+				essential: false,
+				status: "pending",
+			}),
+		]);
+		const plan = await readUlwLoopPlan(cwd, { sessionId: "dx-add-criteria" });
+		expect(plan.goals.at(-1)?.successCriteria).toHaveLength(2);
+	});
+
+	it("#given invalid successCriteria #when the goal is added #then the call fails closed with ULW_LOOP_ARGUMENT_INVALID and nothing persists", async () => {
+		const { cwd, toolkit } = await fixture("dx-add-invalid");
+		const attempts = [
+			{ successCriteria: [] },
+			{ successCriteria: [{ scenario: "  ", expectedEvidence: "x" }] },
+			{ successCriteria: [{ scenario: "s", expectedEvidence: "" }] },
+			{ successCriteria: [{ scenario: "s", expectedEvidence: "e", userModel: "vibes" }] },
+		];
+		for (const attempt of attempts) {
+			const added = await toolkit.addGoal({
+				title: "lane",
+				objective: "ship the lane",
+				...(attempt as { successCriteria: never }),
+			});
+			expect(added.ok).toBe(false);
+			if (!added.ok) expect(added.error.code).toBe("ULW_LOOP_ARGUMENT_INVALID");
+		}
+		const plan = await readUlwLoopPlan(cwd, { sessionId: "dx-add-invalid" });
+		expect(plan.goals).toHaveLength(2);
+	});
+
+	it("#given no successCriteria #when the goal is added #then the placeholders name the exact surface call", async () => {
+		const senpi = await fixture("dx-add-placeholder", "omo-senpi");
+		const added = await senpi.toolkit.addGoal({ title: "lane", objective: "ship the lane" });
+		expect(added.ok).toBe(true);
+		if (!added.ok) return;
+		const placeholder = added.result.goal.successCriteria[0]?.expectedEvidence ?? "";
+		expect(placeholder).toContain('agentToolkit.steer({ kind: "revise_criterion"');
+		expect(placeholder).toContain(`goalId: "${added.result.goal.id}"`);
+		expect(placeholder).toContain('criterionId: "C001"');
+		expect(placeholder).toContain("successCriteria");
+		expect(placeholder).not.toContain("Replace via revise_criterion with");
+
+		const codex = await fixture("dx-add-placeholder-cli", "lazycodex");
+		const cliAdded = await codex.toolkit.addGoal({ title: "lane", objective: "ship the lane" });
+		expect(cliAdded.ok).toBe(true);
+		if (cliAdded.ok) {
+			expect(cliAdded.result.goal.successCriteria[0]?.expectedEvidence).toContain(
+				`omo-agent-toolkit ulw-loop steer --kind revise_criterion --goal-id ${cliAdded.result.goal.id} --criterion-id C001`,
+			);
+		}
+	});
+});
+
+describe("recordEvidence binds artifacts", () => {
+	it("#given existing artifact paths #when evidence is recorded #then repo-relative paths persist on the criterion and the ledger", async () => {
+		const { cwd, toolkit } = await fixture("dx-artifacts");
+		await mkdir(join(cwd, "evidence"), { recursive: true });
+		await writeFile(join(cwd, "evidence", "gate.log"), "exit 0\n");
+		const outside = join(await mkdtemp(join(tmpdir(), "ulw-dx-outside-")), "shot.png");
+		workDirs.push(join(outside, ".."));
+		await writeFile(outside, "png");
+		const started = await toolkit.completeGoals({});
+		if (!started.ok || started.operation !== "complete-goals" || "done" in started.result) throw new Error("fixture");
+		const goalId = started.result.goal.id;
+		const recorded = await toolkit.recordEvidence({
+			goalId,
+			criterionId: "C001",
+			status: "pass",
+			evidence: "gate green",
+			artifacts: ["evidence/gate.log", join(cwd, "evidence", "gate.log"), outside],
+		});
+		expect(recorded.ok).toBe(true);
+		if (!recorded.ok) return;
+		expect(recorded.result.criterion.artifacts).toEqual(["evidence/gate.log", outside]);
+		expect(recorded.result.ledgerEntry.artifacts).toEqual(["evidence/gate.log", outside]);
+		const ledger = (await readFile(join(cwd, ".omo", "ulw-loop", "dx-artifacts", "ledger.jsonl"), "utf8"))
+			.trim()
+			.split("\n");
+		expect(ledger.at(-1)).toContain('"artifacts":["evidence/gate.log"');
+	});
+
+	it("#given a missing artifact #when evidence is recorded #then it fails with ULW_LOOP_EVIDENCE_ARTIFACT_MISSING naming the path and records nothing", async () => {
+		const { cwd, toolkit } = await fixture("dx-artifact-missing");
+		const started = await toolkit.completeGoals({});
+		if (!started.ok || started.operation !== "complete-goals" || "done" in started.result) throw new Error("fixture");
+		const goalId = started.result.goal.id;
+		const recorded = await toolkit.recordEvidence({
+			goalId,
+			criterionId: "C001",
+			status: "pass",
+			evidence: "gate green",
+			artifacts: ["evidence/does-not-exist.log"],
+		});
+		expect(recorded.ok).toBe(false);
+		if (!recorded.ok) {
+			expect(recorded.error.code).toBe("ULW_LOOP_EVIDENCE_ARTIFACT_MISSING");
+			expect(recorded.error.message).toContain("evidence/does-not-exist.log");
+		}
+		const plan = await readUlwLoopPlan(cwd, { sessionId: "dx-artifact-missing" });
+		expect(plan.goals[0]?.successCriteria[0]?.status).toBe("pending");
+	});
+});
+
+describe("status() exposes a stable evidence root", () => {
+	it("#given a session-scoped plan #when status runs #then evidenceRoot is the plan-level directory beside the moving attempt dir", async () => {
+		const { toolkit } = await fixture("dx-evidence-root");
+		const before = await toolkit.status();
+		expect(before.ok).toBe(true);
+		if (before.ok) expect(before.result.evidenceRoot).toBe(".omo/evidence/ulw/dx-evidence-root");
+		await toolkit.completeGoals({});
+		const after = await toolkit.status();
+		expect(after.ok).toBe(true);
+		if (after.ok) {
+			expect(after.result.evidenceRoot).toBe(".omo/evidence/ulw/dx-evidence-root");
+			expect(after.result.currentAttemptDir).toMatch(
+				/^\.omo\/evidence\/ulw\/dx-evidence-root\/G001-alpha-goal\/a\d+$/,
+			);
+		}
+	});
+});