lazycodex-ai 5.0.0-beta.9 → 5.0.0

package/packages/omo-codex/plugin/components/ulw-loop/test/quality-gate-senpi-surface.test.ts

@@ -0,0 +1,131 @@
+import { readFile } from "node:fs/promises";
+
+import { describe, expect, it } from "vitest";
+
+import { validateQualityGate } from "../src/quality-gate.js";
+import { UlwLoopError } from "../src/types.js";
+
+const COMMON = {
+	manualQa: {
+		status: "passed",
+		evidence: "Ran senpi manual QA with artifact-backed evidence.",
+		surfaceEvidence: [
+			{
+				id: "surface-cli-pass",
+				criterionRef: "C1",
+				surface: "cli",
+				invocation: "omo-agent-toolkit ulw-loop checkpoint --status complete",
+				verdict: "passed",
+				artifactRefs: ["artifact-cli-pass"],
+			},
+		],
+		adversarialCases: [
+			{
+				id: "adv-role",
+				criterionRef: "C2",
+				scenario: "a reviewer role is invalid",
+				expectedBehavior: "the gate rejects the invalid role",
+				verdict: "passed",
+				artifactRefs: ["artifact-cli-pass"],
+			},
+		],
+		artifactRefs: [
+			{
+				id: "artifact-cli-pass",
+				kind: "cli-transcript",
+				description: "CLI transcript for valid checkpoint.",
+				path: "cli-pass.txt",
+			},
+		],
+	},
+	iteration: {
+		fullRerun: true,
+		status: "passed",
+		rerunCommands: ["bunx vitest run"],
+		evidence: "Focused tests passed.",
+	},
+	criteriaCoverage: {
+		totalCriteria: 2,
+		passCount: 2,
+		originalIntent: "User wanted a valid senpi quality gate.",
+		desiredOutcome: "The senpi gate accepts its four required lanes.",
+		userOutcomeReview: "The requested senpi outcome is covered.",
+		adversarialClassesCovered: ["role_mismatch"],
+	},
+} as const;
+
+function senpiGate(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+	return {
+		...COMMON,
+		manualQa: { ...COMMON.manualQa, by: "main-session" },
+		gateReview: {
+			by: "category:deep",
+			recommendation: "APPROVE",
+			reportPath: "gate-review.md",
+			evidence: "Verified the senpi gate.",
+			blockers: [],
+		},
+		...overrides,
+	};
+}
+
+function section(input: Record<string, unknown>, key: string): Record<string, unknown> {
+	const value = input[key];
+	if (typeof value !== "object" || value === null || Array.isArray(value))
+		throw new Error(`missing object section: ${key}`);
+	return value as Record<string, unknown>;
+}
+
+function errorFor(input: unknown): UlwLoopError {
+	try {
+		validateQualityGate(input, { reviewerSurface: "omo-senpi" });
+	} catch (error) {
+		if (error instanceof UlwLoopError) return error;
+		throw error;
+	}
+	throw new Error("Expected quality gate validation to fail");
+}
+
+describe("validateQualityGate omo-senpi surface", () => {
+	it("#given a four-section senpi gate #when validated #then it accepts main-session manual QA and category:deep review", () => {
+		expect(() => validateQualityGate(senpiGate(), { reviewerSurface: "omo-senpi" })).not.toThrow();
+	});
+
+	it("#given a senpi gate with codeReview #when validated #then it rejects the forbidden codeReview lane", () => {
+		const error = errorFor(senpiGate({ codeReview: { by: "anything" } }));
+		expect(error.details?.["field"]).toContain("codeReview");
+		expect(error.message).toContain("omo-senpi gate has no codeReview lane");
+	});
+
+	it.each(["category:deep", "category:unspecified-high", "category:unspecified-low"])(
+		"#given gateReview.by %s #when validated on senpi #then it accepts the category role",
+		(by) => {
+			expect(() =>
+				validateQualityGate(senpiGate({ gateReview: { ...section(senpiGate(), "gateReview"), by } }), {
+					reviewerSurface: "omo-senpi",
+				}),
+			).not.toThrow();
+		},
+	);
+
+	it.each(["omo-senpi-gate-reviewer", "lazycodex-gate-reviewer", "arbitrary"])(
+		"#given gateReview.by %s #when validated on senpi #then it rejects the non-category role",
+		(by) => {
+			const error = errorFor(senpiGate({ gateReview: { ...section(senpiGate(), "gateReview"), by } }));
+			expect(error.message).toContain("gateReview.by");
+		},
+	);
+
+	it.each(["omo-senpi-qa-executor", "lazycodex-qa-executor", "arbitrary"])(
+		"#given manualQa.by %s #when validated on senpi #then it rejects the non-main-session role",
+		(by) => {
+			const error = errorFor(senpiGate({ manualQa: { ...COMMON.manualQa, by } }));
+			expect(error.message).toContain("manualQa.by");
+		},
+	);
+
+	it("#given the existing lazycodex fixture #when validated on the default surface #then it remains valid", async () => {
+		const raw = await readFile(new URL("./fixtures/sample-quality-gate.json", import.meta.url), "utf8");
+		expect(() => validateQualityGate(JSON.parse(raw))).not.toThrow();
+	});
+});

package/packages/omo-codex/plugin/components/ulw-loop/test/quality-gate-single-report.test.ts

@@ -0,0 +1,241 @@
+import { describe, expect, it } from "vitest";
+import { validateQualityGate } from "../src/quality-gate.js";
+import { UlwLoopError } from "../src/types.js";
+
+describe("quality gate single report per invalid value", () => {
+	it("#given an empty artifact reference id #when validating #then reports only the array item defect", () => {
+		const gate = {
+			manualQa: {
+				by: "main-session",
+				status: "passed",
+				evidence: "qa",
+				surfaceEvidence: [
+					{
+						id: "surface",
+						criterionRef: "C001",
+						surface: "cli",
+						invocation: "run",
+						verdict: "passed",
+						artifactRefs: [""],
+					},
+				],
+				adversarialCases: [
+					{
+						id: "adv",
+						criterionRef: "C001",
+						scenario: "scenario",
+						expectedBehavior: "reject",
+						verdict: "passed",
+						artifactRefs: [],
+					},
+				],
+				artifactRefs: [{ id: "artifact", kind: "cli-transcript", description: "artifact", path: "artifact.txt" }],
+			},
+			gateReview: {
+				by: "category:deep",
+				recommendation: "APPROVE",
+				evidence: "review",
+				reportPath: "report.txt",
+				blockers: [],
+			},
+			iteration: { fullRerun: true, status: "passed", rerunCommands: ["test"], evidence: "rerun" },
+			criteriaCoverage: {
+				totalCriteria: 1,
+				passCount: 1,
+				originalIntent: "intent",
+				desiredOutcome: "outcome",
+				userOutcomeReview: "review",
+				adversarialClassesCovered: ["none"],
+			},
+		};
+		try {
+			validateQualityGate(gate, { reviewerSurface: "omo-senpi" });
+			throw new Error("expected validation failure");
+		} catch (error) {
+			expect(error).toBeInstanceOf(UlwLoopError);
+			if (!(error instanceof UlwLoopError)) throw error;
+			const fields = error.details?.["fields"];
+			const artifactFields = Array.isArray(fields)
+				? fields.filter((item) => item["field"] === "manualQa.surfaceEvidence[0].artifactRefs")
+				: [];
+			expect(artifactFields).toHaveLength(1);
+		}
+	});
+
+	it("#given a malformed artifact entry #when validating #then does not derive downstream artifact defects", () => {
+		const gate = {
+			manualQa: {
+				by: "main-session",
+				status: "passed",
+				evidence: "qa",
+				surfaceEvidence: [],
+				adversarialCases: [],
+				artifactRefs: [null],
+			},
+			gateReview: {
+				by: "category:deep",
+				recommendation: "APPROVE",
+				evidence: "review",
+				reportPath: "report.txt",
+				blockers: [],
+			},
+			iteration: { fullRerun: true, status: "passed", rerunCommands: ["test"], evidence: "rerun" },
+			criteriaCoverage: {
+				totalCriteria: 1,
+				passCount: 1,
+				originalIntent: "intent",
+				desiredOutcome: "outcome",
+				userOutcomeReview: "review",
+				adversarialClassesCovered: ["none"],
+			},
+		};
+		try {
+			validateQualityGate(gate, { reviewerSurface: "omo-senpi" });
+			throw new Error("expected validation failure");
+		} catch (error) {
+			expect(error).toBeInstanceOf(UlwLoopError);
+			if (!(error instanceof UlwLoopError)) throw error;
+			const fields = error.details?.["fields"];
+			const artifactFields = Array.isArray(fields)
+				? fields.filter((item) => String(item["field"]).startsWith("manualQa.artifactRefs[0]"))
+				: [];
+			expect(artifactFields).toHaveLength(1);
+			expect(artifactFields[0]?.["field"]).toBe("manualQa.artifactRefs[0]");
+		}
+	});
+
+	it("#given an invalid artifact kind #when validating #then does not derive compatibility defects", () => {
+		const gate = {
+			manualQa: {
+				by: "main-session",
+				status: "passed",
+				evidence: "qa",
+				surfaceEvidence: [
+					{
+						id: "surface",
+						criterionRef: "C001",
+						// A data surface accepts only data-diff, so the validator's "log" fallback
+						// for the invalid kind WOULD trip the compatibility check if poisoning
+						// were removed; a cli surface would let the fallback pass silently.
+						surface: "data",
+						invocation: "run",
+						verdict: "passed",
+						artifactRefs: ["artifact"],
+					},
+				],
+				adversarialCases: [
+					{
+						id: "adv",
+						criterionRef: "C001",
+						scenario: "scenario",
+						expectedBehavior: "reject",
+						verdict: "passed",
+						artifactRefs: [],
+					},
+				],
+				artifactRefs: [{ id: "artifact", kind: "invalid", description: "artifact", path: "artifact.txt" }],
+			},
+			gateReview: {
+				by: "category:deep",
+				recommendation: "APPROVE",
+				evidence: "review",
+				reportPath: "report.txt",
+				blockers: [],
+			},
+			iteration: { fullRerun: true, status: "passed", rerunCommands: ["test"], evidence: "rerun" },
+			criteriaCoverage: {
+				totalCriteria: 1,
+				passCount: 1,
+				originalIntent: "intent",
+				desiredOutcome: "outcome",
+				userOutcomeReview: "review",
+				adversarialClassesCovered: ["none"],
+			},
+		};
+		try {
+			validateQualityGate(gate, { reviewerSurface: "omo-senpi" });
+			throw new Error("expected validation failure");
+		} catch (error) {
+			expect(error).toBeInstanceOf(UlwLoopError);
+			if (!(error instanceof UlwLoopError)) throw error;
+			const fields = error.details?.["fields"];
+			const labels = Array.isArray(fields) ? fields.map((item) => item["field"]) : [];
+			expect(labels).toContain("manualQa.artifactRefs[0].kind");
+			expect(labels).not.toContain("manualQa.surfaceEvidence");
+			expect(labels).not.toContain("manualQa.surfaceEvidence[0].artifactRefs");
+			expect(labels.filter((label) => label === "manualQa.artifactRefs[0].kind")).toHaveLength(1);
+		}
+	});
+	it("#given an empty gate #when validating #then reports each missing section once", () => {
+		try {
+			validateQualityGate({}, { reviewerSurface: "omo-senpi" });
+			throw new Error("expected validation failure");
+		} catch (error) {
+			expect(error).toBeInstanceOf(UlwLoopError);
+			if (!(error instanceof UlwLoopError)) throw error;
+			const fields = error.details?.["fields"];
+			const labels = Array.isArray(fields) ? fields.map((item) => item["field"]) : [];
+			expect(labels).toEqual(expect.arrayContaining(["manualQa", "gateReview", "iteration", "criteriaCoverage"]));
+			expect(new Set(labels).size).toBe(labels.length);
+		}
+	});
+
+	it("#given a not-applicable surface verdict #when validating #then reports that verdict defect once", () => {
+		const gate = {
+			manualQa: {
+				by: "main-session",
+				status: "passed",
+				evidence: "qa",
+				surfaceEvidence: [
+					{
+						id: "surface",
+						criterionRef: "C001",
+						surface: "cli",
+						invocation: "run",
+						verdict: "not_applicable",
+						artifactRefs: [],
+					},
+				],
+				adversarialCases: [
+					{
+						id: "adv",
+						criterionRef: "C001",
+						scenario: "scenario",
+						expectedBehavior: "reject",
+						verdict: "passed",
+						artifactRefs: [],
+					},
+				],
+				artifactRefs: [{ id: "artifact", kind: "cli-transcript", description: "artifact", path: "artifact.txt" }],
+			},
+			gateReview: {
+				by: "category:deep",
+				recommendation: "APPROVE",
+				evidence: "review",
+				reportPath: "report.txt",
+				blockers: [],
+			},
+			iteration: { fullRerun: true, status: "passed", rerunCommands: ["test"], evidence: "rerun" },
+			criteriaCoverage: {
+				totalCriteria: 1,
+				passCount: 1,
+				originalIntent: "intent",
+				desiredOutcome: "outcome",
+				userOutcomeReview: "review",
+				adversarialClassesCovered: ["none"],
+			},
+		};
+		try {
+			validateQualityGate(gate, { reviewerSurface: "omo-senpi" });
+			throw new Error("expected validation failure");
+		} catch (error) {
+			expect(error).toBeInstanceOf(UlwLoopError);
+			if (!(error instanceof UlwLoopError)) throw error;
+			const fields = error.details?.["fields"];
+			const verdictFields = Array.isArray(fields)
+				? fields.filter((item) => item["field"] === "manualQa.surfaceEvidence[0].verdict")
+				: [];
+			expect(verdictFields).toHaveLength(1);
+		}
+	});
+});

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

@@ -111,7 +111,10 @@ describe("validateQualityGate", () => {
 			"gateReview",
 			"iteration",
 			"manualQa",
+			"surface",
 		]);
+		expect("codeReview" in gate).toBe(true);
+		if (!("codeReview" in gate)) throw new Error("expected lazycodex codeReview section");
 		expect(gate.codeReview.codeQualityStatus).toBe("CLEAR");
 		expect(gate).toMatchObject({
 			criteriaCoverage: { totalCriteria: 9, passCount: 9, userOutcomeReview: expect.stringContaining("user") },
@@ -127,10 +130,22 @@ describe("validateQualityGate", () => {
 		const gate = validateQualityGate(parsed, FS_OPTS);
 
 		// then
+		expect("codeReview" in gate).toBe(true);
+		if (!("codeReview" in gate)) throw new Error("expected lazycodex codeReview section");
 		expect(gate.codeReview.recommendation).toBe("APPROVE");
 		expect(gate.manualQa.artifactRefs).toHaveLength(5);
 	});
 
+	it("#given missing manualQa section #when validated #then it explains accepted input forms", () => {
+		const input = makeGate();
+		delete input["manualQa"];
+
+		const error = getQualityGateError(input);
+
+		expect(error.message).toContain("accepted input");
+		expect(error.message).toContain('top-level "qualityGate" key');
+	});
+
 	it("#given missing manualQa surface evidence #when validated #then it fails closed", () => {
 		// given
 		const input = makeGate({
@@ -161,20 +176,60 @@ describe("validateQualityGate", () => {
 		expect(error.message).toContain("missing-artifact");
 	});
 
-	it("#given incompatible surface artifact kind #when validated #then it rejects the gate", () => {
+	it("#given incompatible surface artifact kind #when validated #then it rejects the gate with compatible kinds", () => {
 		// when
 		const error = getQualityGateError(
 			makeGate({
 				manualQa: {
 					...VALID_GATE.manualQa,
-					artifactRefs: [{ ...VALID_GATE.manualQa.artifactRefs[0], kind: "http-dump" }],
+					artifactRefs: [
+						{ ...VALID_GATE.manualQa.artifactRefs[0], kind: "http-dump" },
+						VALID_GATE.manualQa.artifactRefs[1],
+					],
 				},
 			}),
 		);
 
 		// then
 		expect(error.code).toBe("ULW_LOOP_QUALITY_GATE_INVALID");
-		expect(error.message).toContain("cli");
+		expect(error.message).toContain(
+			'manualQa.surfaceEvidence cli artifact http-dump is incompatible; surface "cli" accepts artifact kinds: cli-transcript, log.',
+		);
+	});
+
+	it("#given an unsupported artifact kind #when validated #then it lists allowed kinds and report path guidance", () => {
+		const error = getQualityGateError(
+			makeGate({
+				manualQa: {
+					...VALID_GATE.manualQa,
+					artifactRefs: [
+						{ ...VALID_GATE.manualQa.artifactRefs[0], kind: "review-report" },
+						VALID_GATE.manualQa.artifactRefs[1],
+					],
+				},
+			}),
+		);
+
+		expect(error.code).toBe("ULW_LOOP_QUALITY_GATE_INVALID");
+		expect(error.message).toContain(
+			"manualQa.artifactRefs[0].kind must be a supported artifact kind (cli-transcript, log, screenshot, image, http-dump, data-diff); review/QA reports belong in codeReview.reportPath or gateReview.reportPath, not artifactRefs.",
+		);
+	});
+
+	it("#given an unsupported manual QA surface #when validated #then it lists allowed surfaces", () => {
+		const error = getQualityGateError(
+			makeGate({
+				manualQa: {
+					...VALID_GATE.manualQa,
+					surfaceEvidence: [{ ...VALID_GATE.manualQa.surfaceEvidence[0], surface: "terminal" }],
+				},
+			}),
+		);
+
+		expect(error.code).toBe("ULW_LOOP_QUALITY_GATE_INVALID");
+		expect(error.message).toContain(
+			"manualQa.surfaceEvidence[0].surface must be a supported manual QA surface (cli, http, tmux, browser, gui, data).",
+		);
 	});
 
 	it("#given placeholder evidence and artifact path #when validated #then it rejects placeholders", () => {

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

@@ -157,15 +157,17 @@ describe("recordFinalReviewBlockers error cases", () => {
 			"ulw_loop_not_final_story",
 		);
 	});
+});
 
-	it("throws ulw_loop_codex_snapshot_mismatch when objective mismatches", async () => {
+describe("recordFinalReviewBlockers advisory results", () => {
+	it("returns objective-difference warning and resume action for a limited snapshot", async () => {
 		const repo = await bootstrapRepo(finalPlan());
-		const codexGoalJson = JSON.stringify({ goal: { objective: "wrong", status: "active" } });
-
-		await expectUlwLoopCode(
-			() => recordFinalReviewBlockers(repo, { ...validArgs, codexGoalJson }),
-			"ulw_loop_codex_snapshot_mismatch",
-		);
+		const result = await recordFinalReviewBlockers(repo, {
+			...validArgs,
+			codexGoalJson: JSON.stringify({ goal: { objective: "different", status: "budget_limited" } }),
+		});
+		expect(result.nextActions).toContain("/goal resume or raise the budget");
+		expect(result.warnings.some((warning) => warning.startsWith("driver_objective_differs"))).toBe(true);
 	});
 });
 

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-contract.test.ts

@@ -0,0 +1,137 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { seedDefaultSuccessCriteria } from "../src/plan-crud.js";
+import { readUlwLoopPlan } from "../src/plan-io.js";
+import {
+	createAgentToolkit,
+	type ToolkitContext,
+	type ToolkitDispatchRequest,
+	ULW_LOOP_MANIFEST,
+	ULW_LOOP_OPERATIONS,
+} from "../src/sdk.js";
+
+describe("agent toolkit SDK contract", () => {
+	it("exposes exactly the ten existing operations in its manifest", () => {
+		expect(ULW_LOOP_OPERATIONS).toEqual([
+			"help",
+			"create-goals",
+			"status",
+			"complete-goals",
+			"checkpoint",
+			"steer",
+			"add-goal",
+			"criteria",
+			"record-evidence",
+			"record-review-blockers",
+		]);
+		expect(ULW_LOOP_MANIFEST.operations.map((operation) => operation.name)).toEqual(ULW_LOOP_OPERATIONS);
+	});
+
+	it("fails closed for an absent session identity", () => {
+		expect(() => createAgentToolkit({ cwd: ".", sessionId: "", surface: "lazycodex" })).toThrow(
+			"ULW_LOOP_SESSION_ID_REQUIRED",
+		);
+	});
+
+	it("uses explicit surface roles for SDK checkpoint templates", async () => {
+		for (const surface of ["omo-senpi", "lazycodex"] as const) {
+			const cwd = await mkdtemp(join(tmpdir(), `ulw-sdk-template-${surface}-`));
+			try {
+				const toolkit = createAgentToolkit({ cwd, sessionId: `template-${surface}`, surface });
+				const created = await toolkit.createGoals({ brief: "Template fixture" });
+				expect(created.ok).toBe(true);
+				const template = await toolkit.checkpoint({ printTemplate: true });
+				expect(template.ok).toBe(true);
+				if (!template.ok) return;
+				expect(template.operation).toBe("checkpoint");
+				expect("qualityGateTemplate" in template.result).toBe(true);
+				if (!("qualityGateTemplate" in template.result)) return;
+				expect(template.result.qualityGateTemplate["manualQa"]).toMatchObject({ by: "main-session" });
+				expect(template.result.qualityGateTemplate["gateReview"]).toMatchObject({
+					by: surface === "omo-senpi" ? "category:deep-high" : "main-session",
+				});
+			} finally {
+				await rm(cwd, { recursive: true, force: true });
+			}
+		}
+	});
+
+	it("returns the stable unknown-operation error at the public dispatch boundary", async () => {
+		const toolkit = createAgentToolkit({ cwd: ".", sessionId: "sdk-contract", surface: "lazycodex" });
+		const result = await toolkit.dispatch({ operation: "does-not-exist" });
+		expect(result.ok).toBe(false);
+		if (!result.ok) expect(result.error.code).toBe("ULW_LOOP_OPERATION_UNKNOWN");
+	});
+
+	it("calls every operation through typed structured envelopes on a session-scoped fixture", async () => {
+		const cwd = await mkdtemp(join(tmpdir(), "ulw-sdk-contract-"));
+		try {
+			const context: ToolkitContext = { cwd, sessionId: "sdk-contract", surface: "lazycodex" };
+			const hookOperations: string[] = [];
+			const toolkit = createAgentToolkit(context, {
+				hooks: {
+					onOperation: ({ operation }) => {
+						hookOperations.push(operation);
+					},
+				},
+			});
+			const request = async (value: ToolkitDispatchRequest) => {
+				const response = await toolkit.dispatch(value);
+				expect(response.ok).toBe(true);
+				return response;
+			};
+
+			await request({ operation: "help", args: {} });
+			await request({ operation: "create-goals", args: { brief: "Build the SDK fixture" } });
+			await request({ operation: "status", args: {} });
+			const started = await request({ operation: "complete-goals", args: {} });
+			if (!started.ok || started.operation !== "complete-goals" || "done" in started.result)
+				throw new Error("fixture did not start a goal");
+			const goalId = started.result.goal.id;
+			const criterionId = seedDefaultSuccessCriteria(0, "Build the SDK fixture")[0]?.id;
+			if (criterionId === undefined) throw new Error("fixture has no criterion");
+			await request({ operation: "criteria", args: { goalId } });
+			await request({
+				operation: "record-evidence",
+				args: { goalId, criterionId, status: "pass", evidence: "fixture proof" },
+			});
+			await request({
+				operation: "steer",
+				args: {
+					kind: "annotate_ledger",
+					source: "cli",
+					evidence: "fixture observation",
+					rationale: "fixture rationale",
+				},
+			});
+			const plan = await readUlwLoopPlan(cwd, { sessionId: context.sessionId });
+			const review = await request({
+				operation: "record-review-blockers",
+				args: {
+					goalId,
+					title: "Review follow-up",
+					objective: "Exercise review blockers",
+					evidence: "fixture review evidence",
+					codexGoalJson: JSON.stringify({ goal: { objective: plan.codexObjective, status: "active" } }),
+				},
+			});
+			if (!review.ok || review.operation !== "record-review-blockers")
+				throw new Error("fixture did not record review blockers");
+			await request({
+				operation: "checkpoint",
+				args: { goalId: review.result.newGoal.id, status: "failed", evidence: "fixture failure" },
+			});
+			await request({
+				operation: "add-goal",
+				args: { title: "Extra fixture goal", objective: "Exercise add-goal" },
+			});
+			const operationCount = hookOperations.length;
+			expect(operationCount).toBe(10);
+			expect(new Set(hookOperations)).toEqual(new Set(ULW_LOOP_OPERATIONS));
+		} finally {
+			await rm(cwd, { recursive: true, force: true });
+		}
+	});
+});