oh-my-opencode 4.5.1 → 4.6.0

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

@@ -0,0 +1,327 @@
+import { describe, expect, it } from "vitest";
+
+import {
+	aggregateCodexObjective,
+	codexGoalMode,
+	compatibleCodexObjectives,
+	expectedCodexObjective,
+	firstUnresolvedCriterion,
+	hasAllCriteriaPass,
+	isFinalRunCompletionCandidate,
+	isUlwLoopDone,
+	ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE,
+} from "../src/goal-status.js";
+import type { UlwLoopItem, UlwLoopPlan, UlwLoopSuccessCriterion } from "../src/types.js";
+
+const NOW = "2026-05-23T00:00:00.000Z";
+
+function makeCriterion(overrides: Partial<UlwLoopSuccessCriterion> = {}): UlwLoopSuccessCriterion {
+	return {
+		id: "C001",
+		scenario: "happy path",
+		userModel: "happy",
+		expectedEvidence: "observable proof",
+		capturedEvidence: null,
+		status: "pending",
+		...overrides,
+	};
+}
+
+function makeGoal(overrides: Partial<UlwLoopItem> = {}): UlwLoopItem {
+	return {
+		id: "G001",
+		title: "Goal one",
+		objective: "Complete goal one",
+		status: "pending",
+		successCriteria: [],
+		attempt: 1,
+		createdAt: NOW,
+		updatedAt: NOW,
+		...overrides,
+	};
+}
+
+function makePlan(overrides: Partial<UlwLoopPlan> = {}): UlwLoopPlan {
+	return {
+		version: 1,
+		createdAt: NOW,
+		updatedAt: NOW,
+		briefPath: ".omo/ulw-loop/brief.md",
+		goalsPath: ".omo/ulw-loop/goals.json",
+		ledgerPath: ".omo/ulw-loop/ledger.jsonl",
+		goals: [],
+		...overrides,
+	};
+}
+
+describe("isUlwLoopDone", () => {
+	it("returns true when all goals complete", () => {
+		// given
+		const plan = makePlan({
+			goals: [makeGoal({ status: "complete" }), makeGoal({ id: "G002", status: "complete" })],
+		});
+
+		// when
+		const done = isUlwLoopDone(plan);
+
+		// then
+		expect(done).toBe(true);
+	});
+
+	it("returns false when any pending remains", () => {
+		// given
+		const plan = makePlan({ goals: [makeGoal({ status: "complete" }), makeGoal({ id: "G002", status: "pending" })] });
+
+		// when
+		const done = isUlwLoopDone(plan);
+
+		// then
+		expect(done).toBe(false);
+	});
+
+	it("treats superseded-with-complete-replacements as resolved", () => {
+		// given
+		const replacement = makeGoal({ id: "G002", status: "complete" });
+		const superseded = makeGoal({
+			id: "G001",
+			status: "pending",
+			steeringStatus: "superseded",
+			supersededBy: [replacement.id],
+		});
+		const plan = makePlan({ goals: [superseded, replacement] });
+
+		// when
+		const done = isUlwLoopDone(plan);
+
+		// then
+		expect(done).toBe(true);
+	});
+});
+
+describe("isFinalRunCompletionCandidate", () => {
+	it("returns true when only one unresolved goal remains", () => {
+		// given
+		const finalGoal = makeGoal({ id: "G002", status: "pending" });
+		const plan = makePlan({ goals: [makeGoal({ status: "complete" }), finalGoal] });
+
+		// when
+		const candidate = isFinalRunCompletionCandidate(plan, finalGoal);
+
+		// then
+		expect(candidate).toBe(true);
+	});
+
+	it("returns false when multiple unresolved", () => {
+		// given
+		const goal = makeGoal({ id: "G001", status: "pending" });
+		const plan = makePlan({ goals: [goal, makeGoal({ id: "G002", status: "pending" })] });
+
+		// when
+		const candidate = isFinalRunCompletionCandidate(plan, goal);
+
+		// then
+		expect(candidate).toBe(false);
+	});
+});
+
+describe("codexGoalMode", () => {
+	it("defaults to per_story when undefined", () => {
+		// when
+		const mode = codexGoalMode(makePlan());
+
+		// then
+		expect(mode).toBe("per_story");
+	});
+
+	it("returns aggregate when explicitly aggregate", () => {
+		// when
+		const mode = codexGoalMode(makePlan({ codexGoalMode: "aggregate" }));
+
+		// then
+		expect(mode).toBe("aggregate");
+	});
+});
+
+describe("expectedCodexObjective", () => {
+	it("aggregate mode returns plan.codexObjective", () => {
+		// given
+		const goal = makeGoal({ objective: "story objective" });
+		const plan = makePlan({ codexGoalMode: "aggregate", codexObjective: "aggregate objective" });
+
+		// when
+		const objective = expectedCodexObjective(plan, goal);
+
+		// then
+		expect(objective).toBe("aggregate objective");
+	});
+
+	it("aggregate mode falls back to ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE when codexObjective missing", () => {
+		// given
+		const goal = makeGoal({ objective: "story objective" });
+		const plan = makePlan({ codexGoalMode: "aggregate" });
+
+		// when
+		const objective = expectedCodexObjective(plan, goal);
+
+		// then
+		expect(objective).toBe(ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE);
+	});
+
+	it("per_story mode returns goal.objective", () => {
+		// given
+		const goal = makeGoal({ objective: "story objective" });
+		const plan = makePlan({ codexGoalMode: "per_story", codexObjective: "aggregate objective" });
+
+		// when
+		const objective = expectedCodexObjective(plan, goal);
+
+		// then
+		expect(objective).toBe("story objective");
+	});
+});
+
+describe("aggregateCodexObjective", () => {
+	it("returns plan.codexObjective when set", () => {
+		// when
+		const objective = aggregateCodexObjective(makePlan({ codexObjective: "aggregate objective" }));
+
+		// then
+		expect(objective).toBe("aggregate objective");
+	});
+
+	it("falls back to ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE", () => {
+		// when
+		const objective = aggregateCodexObjective(makePlan());
+
+		// then
+		expect(objective).toBe(ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE);
+	});
+});
+
+describe("compatibleCodexObjectives", () => {
+	it("includes aggregate objective + aliases", () => {
+		// given
+		const plan = makePlan({
+			codexObjective: "aggregate objective",
+			codexObjectiveAliases: ["legacy one", "legacy two"],
+		});
+
+		// when
+		const objectives = compatibleCodexObjectives(plan);
+
+		// then
+		expect(objectives).toEqual(["aggregate objective", "legacy one", "legacy two"]);
+	});
+});
+
+describe("hasAllCriteriaPass", () => {
+	it("returns true when all criteria pass", () => {
+		// given
+		const goal = makeGoal({
+			successCriteria: [makeCriterion({ status: "pass" }), makeCriterion({ id: "C002", status: "pass" })],
+		});
+
+		// when
+		const passed = hasAllCriteriaPass(goal);
+
+		// then
+		expect(passed).toBe(true);
+	});
+
+	it("returns false when any criterion pending", () => {
+		// given
+		const goal = makeGoal({
+			successCriteria: [makeCriterion({ status: "pass" }), makeCriterion({ id: "C002", status: "pending" })],
+		});
+
+		// when
+		const passed = hasAllCriteriaPass(goal);
+
+		// then
+		expect(passed).toBe(false);
+	});
+
+	it("returns false when any criterion fail", () => {
+		// given
+		const goal = makeGoal({
+			successCriteria: [makeCriterion({ status: "pass" }), makeCriterion({ id: "C002", status: "fail" })],
+		});
+
+		// when
+		const passed = hasAllCriteriaPass(goal);
+
+		// then
+		expect(passed).toBe(false);
+	});
+
+	it("returns false when any criterion blocked", () => {
+		// given
+		const goal = makeGoal({
+			successCriteria: [makeCriterion({ status: "pass" }), makeCriterion({ id: "C002", status: "blocked" })],
+		});
+
+		// when
+		const passed = hasAllCriteriaPass(goal);
+
+		// then
+		expect(passed).toBe(false);
+	});
+
+	it("returns false for empty criteria array", () => {
+		// when
+		const passed = hasAllCriteriaPass(makeGoal({ successCriteria: [] }));
+
+		// then
+		expect(passed).toBe(false);
+	});
+});
+
+describe("firstUnresolvedCriterion", () => {
+	it("returns first non-pass criterion", () => {
+		// given
+		const unresolved = makeCriterion({ id: "C002", status: "fail" });
+		const goal = makeGoal({ successCriteria: [makeCriterion({ status: "pass" }), unresolved] });
+
+		// when
+		const criterion = firstUnresolvedCriterion(goal);
+
+		// then
+		expect(criterion).toBe(unresolved);
+	});
+
+	it("returns undefined when all pass", () => {
+		// given
+		const goal = makeGoal({
+			successCriteria: [makeCriterion({ status: "pass" }), makeCriterion({ id: "C002", status: "pass" })],
+		});
+
+		// when
+		const criterion = firstUnresolvedCriterion(goal);
+
+		// then
+		expect(criterion).toBeUndefined();
+	});
+
+	it("returns first pending in mixed pass/pending/fail", () => {
+		// given
+		const pending = makeCriterion({ id: "C002", status: "pending" });
+		const goal = makeGoal({
+			successCriteria: [makeCriterion({ status: "pass" }), pending, makeCriterion({ id: "C003", status: "fail" })],
+		});
+
+		// when
+		const criterion = firstUnresolvedCriterion(goal);
+
+		// then
+		expect(criterion).toBe(pending);
+	});
+});
+
+describe("ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE", () => {
+	it("references the .omo/ulw-loop path and excludes the legacy workspace", () => {
+		const legacyWorkspace = [".", "om", "x"].join("");
+
+		expect(ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE).toContain(".omo/ulw-loop");
+		expect(ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE).not.toContain(legacyWorkspace);
+	});
+});

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

@@ -0,0 +1,261 @@
+// biome-ignore-all format: smoke test pulls verbatim JSON for structural assertion.
+import { spawn } from "node:child_process";
+import { chmod, mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+async function readText(relative: string): Promise<string> {
+	return readFile(join(repoRoot, relative), "utf8");
+}
+
+async function readJson(relative: string): Promise<unknown> {
+	return JSON.parse(await readText(relative));
+}
+
+type ShellResult = {
+	readonly code: number | null;
+	readonly stdout: string;
+	readonly stderr: string;
+};
+
+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);
+	expect(blockStart).toBeGreaterThanOrEqual(0);
+	const codeStart = blockStart + "```sh\n".length;
+	const blockEnd = text.indexOf("\n```", codeStart);
+	expect(blockEnd).toBeGreaterThan(codeStart);
+	return text.slice(codeStart, blockEnd);
+}
+
+async function runShell(script: string, env: NodeJS.ProcessEnv): Promise<ShellResult> {
+	return new Promise((resolvePromise, reject) => {
+		const child = spawn("/bin/sh", ["-c", script], { env });
+		const stdout: Buffer[] = [];
+		const stderr: Buffer[] = [];
+		child.stdout.on("data", (chunk: Buffer) => stdout.push(chunk));
+		child.stderr.on("data", (chunk: Buffer) => stderr.push(chunk));
+		child.on("error", reject);
+		child.on("close", (code) => {
+			resolvePromise({
+				code,
+				stdout: Buffer.concat(stdout).toString("utf8"),
+				stderr: Buffer.concat(stderr).toString("utf8"),
+			});
+		});
+	});
+}
+
+describe("package.json", () => {
+	it("declares ESM + npm + Node >=20", async () => {
+		const pkg = await readJson("package.json") as Record<string, unknown>;
+		expect(pkg["type"]).toBe("module");
+		expect(pkg["packageManager"]).toBe("npm@11.12.1");
+		expect((pkg["engines"] as Record<string, unknown>)["node"]).toBe(">=20.0.0");
+	});
+
+	it("exposes the omo binary pointing at dist/cli.js", async () => {
+		const pkg = await readJson("package.json") as Record<string, unknown>;
+		const bin = pkg["bin"] as Record<string, string>;
+		expect(bin["omo"]).toBe("./dist/cli.js");
+	});
+
+	it("ships the expected files for npm publish", async () => {
+		const pkg = await readJson("package.json") as Record<string, unknown>;
+		const files = pkg["files"] as readonly string[];
+		expect(files).toContain("dist");
+		expect(files).toContain("hooks");
+		expect(files).toContain("skills");
+		expect(files).not.toContain(".codex-plugin");
+	});
+});
+
+describe("component plugin identity", () => {
+	it("is owned by the aggregate OMO plugin root", async () => {
+		await expect(readText(".codex-plugin/plugin.json")).rejects.toMatchObject({ code: "ENOENT" });
+	});
+});
+
+describe("hooks/hooks.json", () => {
+	it("registers UserPromptSubmit with PLUGIN_ROOT interpolation", async () => {
+		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;
+		expect(command).toContain(`$${"{PLUGIN_ROOT}"}`);
+		expect(command).toContain("dist/cli.js");
+		expect(command).toContain("hook user-prompt-submit");
+	});
+
+	it("#given ulw-loop component is enabled #when hooks are inspected #then create_goal PreToolUse guard is registered", async () => {
+		const text = await readText("hooks/hooks.json");
+
+		expect(text).toContain('"PreToolUse"');
+		expect(text).toContain('"matcher": "^create_goal$"');
+		expect(text).toContain("hook pre-tool-use");
+	});
+});
+
+describe("src/cli.ts", () => {
+	it("starts with #!/usr/bin/env node shebang", async () => {
+		const text = await readText("src/cli.ts");
+		expect(text.split("\n")[0]).toBe("#!/usr/bin/env node");
+	});
+});
+
+describe("skills/ulw-loop/SKILL.md", () => {
+	it("exists", async () => {
+		const info = await stat(join(repoRoot, "skills/ulw-loop/SKILL.md"));
+		expect(info.isFile()).toBe(true);
+	});
+
+	it("#given Codex skill hinting #when ulw-loop skill metadata is inspected #then ulw-loop is the primary mention name", async () => {
+		const text = await readText("skills/ulw-loop/SKILL.md");
+
+		expect(text).toMatch(/^---\nname: ulw-loop\n/m);
+		expect(text).toContain("Goal-like loop that uses ultrawork mode to decompose work into systematic, evidence-bound steps.");
+		expect(text).toContain("short-description: Goal-like ultrawork loop for systematic decomposition");
+	});
+
+	it("#given Codex dollar hinting #when querying ulw-loop #then ulw-loop surfaces the ulw-loop alias", async () => {
+		const text = await readText("skills/ulw-loop/agents/openai.yaml");
+
+		expect(text).toContain('display_name: "ulw-loop (omo)"');
+		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 () => {
+		const text = await readText("skills/ulw-loop/agents/openai.yaml");
+
+		expect(text).toContain("search_terms:");
+		expect(text).toContain('- "ulw-loop"');
+	});
+
+	it("references the success criteria and record-evidence vocabulary", async () => {
+		const text = await readText("skills/ulw-loop/references/full-workflow.md");
+		expect(text.toLowerCase()).toMatch(/success criteria|successcriteria/);
+		expect(text.toLowerCase()).toContain("record-evidence");
+	});
+
+	it("#given omo is absent from PATH #when bootstrap instructions are read #then local cached CLI fallback is documented", async () => {
+		const text = await readText("skills/ulw-loop/references/full-workflow.md");
+
+		expect(text).toContain("If `omo` is absent from PATH");
+		expect(text).toContain("ULW_LOOP_CLI");
+		expect(text).toContain("components/ulw-loop/dist/cli.js");
+	});
+
+	it("#given empty PATH #when bootstrap instructions are read #then handles empty PATH without losing notepad bootstrap", async () => {
+		const text = await readText("skills/ulw-loop/references/full-workflow.md");
+
+		expect(text).toContain("If PATH is empty");
+		expect(text).toContain("ULW_LOOP_NODE");
+		expect(text).toContain(".omo/ulw-loop/bootstrap-notepad.md");
+		expect(text).not.toContain("ls -1");
+	});
+
+	it("#given PATH omo lacks ulw-loop #when bootstrap runs #then falls back to cached ulw-loop CLI", async () => {
+		const text = await readText("skills/ulw-loop/references/full-workflow.md");
+		const bootstrap = bootstrapScriptFrom(text);
+		const root = await mkdtemp(join(tmpdir(), "omo-ulw-loop-bootstrap-"));
+		try {
+			const badBin = join(root, "bad-bin");
+			const home = join(root, "home");
+			const codexHome = join(home, ".codex");
+			const cachedCli = join(codexHome, "plugins", "cache", "sisyphuslabs", "omo", "0.1.0", "components", "ulw-loop", "dist", "cli.js");
+			await mkdir(badBin, { recursive: true });
+			await mkdir(dirname(cachedCli), { recursive: true });
+			await writeFile(join(badBin, "omo"), "#!/bin/sh\nprintf '%s\\n' \"error: unknown command 'ulw-loop'\" >&2\nexit 1\n");
+			await chmod(join(badBin, "omo"), 0o755);
+			await writeFile(
+				cachedCli,
+				[
+					"#!/usr/bin/env node",
+					"const args = process.argv.slice(2);",
+					"if (args[0] === 'ulw-loop' && args[1] === 'help') process.exit(0);",
+					"if (args[0] === 'ulw-loop' && args[1] === 'status' && args.includes('--json')) {",
+					"  console.log(JSON.stringify({ ok: true, source: 'cached-ulw-loop' }));",
+					"  process.exit(0);",
+					"}",
+					"console.error('unexpected args: ' + args.join(' '));",
+					"process.exit(1);",
+					"",
+				].join("\n"),
+			);
+
+			const result = await runShell(`${bootstrap}\nomo ulw-loop status --json`, {
+				...process.env,
+				CODEX_HOME: codexHome,
+				HOME: home,
+				PATH: `${badBin}:${process.env["PATH"] ?? ""}`,
+			});
+
+			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 });
+		}
+	});
+
+	it("uses the .omo workspace path", async () => {
+		const text = await readText("skills/ulw-loop/SKILL.md");
+		expect(text).toContain(".omo/ulw-loop");
+	});
+
+	it("#given long Codex runs #when worker guidance is inspected #then avoids context-expensive agent polling", async () => {
+		const text = await readText("skills/ulw-loop/references/full-workflow.md");
+
+		expect(text).toMatch(/list_agents/);
+		expect(text).toMatch(/polling or status tool/);
+		expect(text).toMatch(/replay large agent status and latest-message payloads/);
+		expect(text).toMatch(/Track spawned agent names locally/);
+		expect(text).toMatch(/wait_agent.*completion/);
+		expect(text).toMatch(/targeted followups only when needed/);
+		expect(text).toMatch(/close_agent.*after integrating each result/);
+		expect(text).toMatch(/Plan and reviewer agents may run for a long time/);
+		expect(text).toMatch(/short wait_agent cycles/);
+		expect(text).toMatch(/single long blocking wait/);
+		expect(text).toContain("Every worker message MUST carry");
+		expect(text).toContain("Each worker does strict TDD");
+	});
+
+	it("#given Codex subagent delegation #when worker guidance is inspected #then assignment ambiguity is hardened", async () => {
+		const text = await readText("skills/ulw-loop/SKILL.md");
+
+		expect(text).toMatch(/TASK:/);
+		expect(text).toMatch(/fork_turns:\s*"none"/);
+		expect(text).toMatch(/wait_agent.*signal, not proof/);
+		expect(text).toMatch(/one targeted followup/);
+		expect(text).toMatch(/respawn.*smaller/);
+		expect(text).toMatch(/Plan and reviewer agents may run for a long time/);
+		expect(text).toMatch(/short wait_agent cycles/);
+		expect(text).toMatch(/single long blocking wait/);
+	});
+});
+
+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/checkpoint.ts", "src/review-blockers.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);
+		}
+	});
+});

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

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+
+import {
+	normalizeUlwLoopSessionId,
+	repoRelative,
+	ulwLoopBriefPath,
+	ulwLoopDir,
+	ulwLoopGoalsPath,
+	ulwLoopLedgerPath,
+} from "../src/paths.ts";
+
+describe("ulwLoopDir(repo)", () => {
+	it("returns repo + '/.omo/ulw-loop'", () => {
+		// when/then
+		expect(ulwLoopDir("/repo")).toBe("/repo/.omo/ulw-loop");
+	});
+
+	it("#given a session id #when resolving the loop dir #then scopes artifacts under that session", () => {
+		// when/then
+		expect(ulwLoopDir("/repo", { sessionId: "sess_abc" })).toBe("/repo/.omo/ulw-loop/sess_abc");
+	});
+});
+
+describe("ulw-loop*Path helpers", () => {
+	it("compose artifact filenames under ulwLoopDir", () => {
+		// when/then
+		expect(ulwLoopBriefPath("/r")).toBe("/r/.omo/ulw-loop/brief.md");
+		expect(ulwLoopGoalsPath("/r")).toBe("/r/.omo/ulw-loop/goals.json");
+		expect(ulwLoopLedgerPath("/r")).toBe("/r/.omo/ulw-loop/ledger.jsonl");
+	});
+
+	it("#given a session id #when composing artifact filenames #then returns session-scoped paths", () => {
+		// when/then
+		expect(ulwLoopBriefPath("/r", { sessionId: "session-A" })).toBe("/r/.omo/ulw-loop/session-A/brief.md");
+		expect(ulwLoopGoalsPath("/r", { sessionId: "session-A" })).toBe("/r/.omo/ulw-loop/session-A/goals.json");
+		expect(ulwLoopLedgerPath("/r", { sessionId: "session-A" })).toBe("/r/.omo/ulw-loop/session-A/ledger.jsonl");
+	});
+});
+
+describe("normalizeUlwLoopSessionId", () => {
+	it("#given traversal-like input #when normalized #then returns a path-safe session segment", () => {
+		// when/then
+		expect(normalizeUlwLoopSessionId("../bad/id")).toBe("bad-id");
+	});
+
+	it("#given blank input #when normalized #then returns null", () => {
+		// when/then
+		expect(normalizeUlwLoopSessionId("  ")).toBeNull();
+	});
+});
+
+describe("repoRelative", () => {
+	it("strips repo prefix when path is inside repo", () => {
+		// when/then
+		expect(repoRelative("/repo/.omo/ulw-loop/goals.json", "/repo")).toBe(".omo/ulw-loop/goals.json");
+	});
+
+	it("returns absolute when path is outside repo", () => {
+		// when/then
+		expect(repoRelative("/elsewhere/file", "/repo")).toBe("/elsewhere/file");
+	});
+});