oh-my-opencode 5.0.0-beta.3 → 5.0.0-beta.31

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

@@ -10,6 +10,7 @@ import {
 	textField,
 } from "./quality-gate-fields.js";
 import { adversarialVerdict, codeQualityStatusField, passedVerdict } from "./quality-gate-verdicts.js";
+import { reviewerRolesFor, type UlwLoopToolkitSurface } from "./surface.js";
 import type {
 	UlwLoopManualQaArtifactKind,
 	UlwLoopManualQaArtifactRef,
@@ -17,12 +18,6 @@ import type {
 	UlwLoopQualityGate,
 } from "./types.js";
 
-const REVIEWER_ROLES = {
-	codeReview: "lazycodex-code-reviewer",
-	manualQa: "lazycodex-qa-executor",
-	gateReview: "lazycodex-gate-reviewer",
-} as const;
-
 export {
 	classifyExternalAuthorizationBlocker,
 	clearGoalBlockerFields,
@@ -36,12 +31,13 @@ export interface QualityGateFs {
 }
 
 export interface ValidateQualityGateOptions {
-	readonly repoRoot: string;
-	readonly fs: QualityGateFs;
+	readonly repoRoot?: string;
+	readonly fs?: QualityGateFs;
 	readonly currentAttemptDir?: string;
+	readonly reviewerSurface?: UlwLoopToolkitSurface;
 }
 
-function reviewerRoleField<T extends string>(value: unknown, expected: T, field: string): T {
+function reviewerRoleField(value: unknown, expected: string, field: string): string {
 	const actual = textField(value, field);
 	if (actual !== expected) invalid(`${field} must be ${expected}.`, field);
 	return expected;
@@ -91,11 +87,11 @@ function artifactCompatible(surface: UlwLoopManualQaSurface, kind: UlwLoopManual
 }
 
 function checkFile(path: string, field: string, opts?: ValidateQualityGateOptions): void {
-	if (opts === undefined) return;
+	if (opts?.repoRoot === undefined || opts.fs === undefined) return;
 	const absolute = resolve(opts.repoRoot, path);
 	if (!opts.fs.existsSync(absolute)) invalid(`${field} must point to an existing artifact.`, field);
 	if (opts.fs.statSync(absolute).size <= 0) invalid(`${field} must point to a non-empty artifact.`, field);
-	if (opts.currentAttemptDir !== undefined) {
+	if (opts.currentAttemptDir !== undefined && opts.repoRoot !== undefined) {
 		const attemptRoot = resolve(opts.repoRoot, opts.currentAttemptDir);
 		if (!isWithinAttemptDir(absolute, attemptRoot))
 			invalid(
@@ -143,6 +139,7 @@ function referencedArtifacts(
 }
 
 export function validateQualityGate(input: unknown, opts?: ValidateQualityGateOptions): UlwLoopQualityGate {
+	const reviewerRoles = reviewerRolesFor(opts?.reviewerSurface ?? "lazycodex");
 	const gate = section(input, "qualityGate");
 	const codeReview = section(gate["codeReview"], "codeReview");
 	const manualQa = section(gate["manualQa"], "manualQa");
@@ -163,7 +160,7 @@ export function validateQualityGate(input: unknown, opts?: ValidateQualityGateOp
 	checkFile(gateReportPath, "gateReview.reportPath", opts);
 	return {
 		codeReview: {
-			by: reviewerRoleField(codeReview["by"], REVIEWER_ROLES.codeReview, "codeReview.by"),
+			by: reviewerRoleField(codeReview["by"], reviewerRoles.codeReview, "codeReview.by"),
 			recommendation: literal(codeReview["recommendation"], "APPROVE", "codeReview.recommendation"),
 			codeQualityStatus: codeQualityStatusField(codeReview["codeQualityStatus"], "codeReview.codeQualityStatus"),
 			reportPath: codeReportPath,
@@ -171,7 +168,7 @@ export function validateQualityGate(input: unknown, opts?: ValidateQualityGateOp
 			blockers: emptyBlockers(codeReview["blockers"], "codeReview.blockers"),
 		},
 		manualQa: {
-			by: reviewerRoleField(manualQa["by"], REVIEWER_ROLES.manualQa, "manualQa.by"),
+			by: reviewerRoleField(manualQa["by"], reviewerRoles.manualQa, "manualQa.by"),
 			status: literal(manualQa["status"], "passed", "manualQa.status"),
 			evidence: textField(manualQa["evidence"], "manualQa.evidence"),
 			surfaceEvidence,
@@ -179,7 +176,7 @@ export function validateQualityGate(input: unknown, opts?: ValidateQualityGateOp
 			artifactRefs,
 		},
 		gateReview: {
-			by: reviewerRoleField(gateReview["by"], REVIEWER_ROLES.gateReview, "gateReview.by"),
+			by: reviewerRoleField(gateReview["by"], reviewerRoles.gateReview, "gateReview.by"),
 			recommendation: literal(gateReview["recommendation"], "APPROVE", "gateReview.recommendation"),
 			reportPath: gateReportPath,
 			evidence: textField(gateReview["evidence"], "gateReview.evidence"),

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

@@ -5,6 +5,7 @@ import type { PreToolUsePayload } from "./codex-hook.js";
 import { parsePreToolUsePayload } from "./codex-hook.js";
 import { isFinalRunCompletionCandidate } from "./goal-status.js";
 import { ulwLoopAttemptEvidenceDir, ulwLoopDir } from "./paths.js";
+import { GATE_REVIEWER_AGENT_NAMES } from "./surface.js";
 import type { UlwLoopPlan } from "./types.js";
 
 // spawn_agent = v1; collaborationspawn_agent = the delimiter-free flattened v2
@@ -12,7 +13,7 @@ import type { UlwLoopPlan } from "./types.js";
 // dotted token observed live in the task-1 probe (hook-tool-tokens.txt).
 const SPAWN_TOOL_TOKENS = new Set(["spawn_agent", "collaborationspawn_agent", "collaboration.spawn_agent"]);
 const DEFAULT_FANOUT_LIMIT = 60;
-const GATE_MESSAGE_PATTERN = /lazycodex-gate-reviewer|final gate review/i;
+const GATE_MESSAGE_PATTERN = /lazycodex-gate-reviewer|omo-senpi-gate-reviewer|final gate review/i;
 
 export function applySpawnGuards(payload: PreToolUsePayload): string {
 	if (payload.hook_event_name !== "PreToolUse" || !SPAWN_TOOL_TOKENS.has(payload.tool_name)) return "";
@@ -77,7 +78,7 @@ function isGateReviewerSpawn(toolInput: unknown): boolean {
 	if (typeof toolInput !== "object" || toolInput === null) return false;
 	const record = toolInput as Record<string, unknown>;
 	const agentType = record["agent_type"];
-	if (typeof agentType === "string") return agentType === "lazycodex-gate-reviewer";
+	if (typeof agentType === "string") return GATE_REVIEWER_AGENT_NAMES.has(agentType);
 	const message = record["message"];
 	return typeof message === "string" && GATE_MESSAGE_PATTERN.test(message);
 }

package/packages/omo-codex/plugin/components/ulw-loop/src/stop-resume-hook.ts

@@ -10,7 +10,7 @@ import type { UlwLoopItem, UlwLoopPlan } from "./types.js";
 
 const RESUME_CAP = 2;
 
-// Mirrors start-work-continuation's context-pressure bail-out: injecting a
+// Mirrors ulw-execute-continuation's context-pressure bail-out: injecting a
 // resume directive into an already-overflowing context makes things worse.
 const CONTEXT_PRESSURE_MARKERS = [
 	"context compacted",
@@ -136,7 +136,7 @@ function readCounter(counterPath: string): { count: number; ledgerLineCount: num
 	}
 }
 
-// Local ~10-LOC approximation of start-work-continuation's boulder check (no
+// Local ~10-LOC approximation of ulw-execute-continuation's boulder check (no
 // cross-component import allowed): any continuable work for this session means
 // that hook owns the Stop event, so this one stays silent.
 function boulderContinuationWillFire(cwd: string, sessionId: string): boolean {
@@ -168,7 +168,7 @@ function transcriptShowsContextPressure(transcriptPath: string): boolean {
 	}
 }
 
-// start-work-continuation owns an active Boulder plan until its final gate marks
+// ulw-execute-continuation owns an active Boulder plan until its final gate marks
 // the work complete, including the zero-remaining checklist state.
 function boulderPlanHasChecklist(cwd: string, entry: Record<string, unknown>): boolean {
 	const activePlan = entry["active_plan"];

package/packages/omo-codex/plugin/components/ulw-loop/src/surface.ts

@@ -0,0 +1,73 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// The agent toolkit ships on two surfaces: the LazyCodex (Codex CLI) plugin runs the component
+// bundle directly, while omo-senpi stages the same bundle through stage-agent-toolkit.mjs. The
+// reviewer identities the final quality gate enforces differ per surface, so the staging script
+// bakes a `surface.json` marker next to the staged bundle and this module resolves it. Without a
+// marker (the Codex layout) the surface stays "lazycodex".
+export type UlwLoopToolkitSurface = "lazycodex" | "omo-senpi";
+
+export interface UlwLoopReviewerRoles {
+	readonly codeReview: string;
+	readonly manualQa: string;
+	readonly gateReview: string;
+}
+
+export const REVIEWER_ROLES_BY_SURFACE: Readonly<Record<UlwLoopToolkitSurface, UlwLoopReviewerRoles>> = {
+	lazycodex: {
+		codeReview: "lazycodex-code-reviewer",
+		manualQa: "lazycodex-qa-executor",
+		gateReview: "lazycodex-gate-reviewer",
+	},
+	"omo-senpi": {
+		codeReview: "omo-senpi-code-reviewer",
+		manualQa: "omo-senpi-qa-executor",
+		gateReview: "omo-senpi-gate-reviewer",
+	},
+};
+
+export const GATE_REVIEWER_AGENT_NAMES: ReadonlySet<string> = new Set(
+	Object.values(REVIEWER_ROLES_BY_SURFACE).map((roles) => roles.gateReview),
+);
+
+export function reviewerRolesFor(surface: UlwLoopToolkitSurface): UlwLoopReviewerRoles {
+	return REVIEWER_ROLES_BY_SURFACE[surface];
+}
+
+export const SURFACE_MARKER_FILENAME = "surface.json";
+const SURFACE_ENV_KEY = "OMO_AGENT_TOOLKIT_SURFACE";
+
+function parseSurface(value: unknown): UlwLoopToolkitSurface | null {
+	return value === "lazycodex" || value === "omo-senpi" ? value : null;
+}
+
+export interface ResolveToolkitSurfaceOptions {
+	readonly env?: Readonly<Record<string, string | undefined>>;
+	readonly entryDir?: string;
+}
+
+// Resolution order: explicit env override (tests, doctor probes) -> staged surface.json marker
+// sitting next to the running bundle -> lazycodex default. The marker is distribution-baked, so a
+// malformed marker falls back to the default instead of crashing checkpoint validation; the env
+// override remains available to force the intended surface on a damaged install.
+export function resolveToolkitSurface(options?: ResolveToolkitSurfaceOptions): UlwLoopToolkitSurface {
+	const env = options?.env ?? process.env;
+	const fromEnv = parseSurface(env[SURFACE_ENV_KEY]);
+	if (fromEnv !== null) return fromEnv;
+	const entryDir = options?.entryDir ?? dirname(fileURLToPath(import.meta.url));
+	const markerPath = join(entryDir, SURFACE_MARKER_FILENAME);
+	return readMarkerSurface(markerPath) ?? "lazycodex";
+}
+
+function readMarkerSurface(markerPath: string): UlwLoopToolkitSurface | null {
+	try {
+		if (!existsSync(markerPath)) return null;
+		const parsed = JSON.parse(readFileSync(markerPath, "utf8")) as Record<string, unknown>;
+		return parseSurface(parsed["surface"]);
+	} catch (error) {
+		if (error instanceof Error) return null;
+		throw error;
+	}
+}

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

@@ -31,7 +31,6 @@ describe("checkpointAndContinue", () => {
 		});
 
 		expect(result.next).toMatchObject({ resumed: false, goal: { id: "G002", status: "in_progress" } });
-		expect(result.next && "instruction" in result.next ? result.next.instruction.text : "").toContain("Goal: G002");
 		expect((await readUlwLoopPlan(repo)).activeGoalId).toBe("G002");
 	});
 

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

@@ -1,5 +1,5 @@
 import { writeFile } from "node:fs/promises";
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it } from "vitest";
 
 import { checkpointUlwLoop } from "../src/checkpoint.js";
 import { ulwLoopBriefPath } from "../src/paths.js";
@@ -7,6 +7,49 @@ import { startNextUlwLoop } from "../src/plan-crud.js";
 import { criterion, expectCode, goal, passGoal, plan, repoWith, snapshot } from "./fixtures/checkpoint-builders.js";
 import { MISSING_ARTIFACT_PATH, qualityGateJson } from "./fixtures/quality-gate-builder.js";
 
+describe("checkpointUlwLoop final story surface resolution", () => {
+	afterEach(() => {
+		delete process.env["OMO_AGENT_TOOLKIT_SURFACE"];
+	});
+
+	it("#given the omo-senpi surface #when the gate names omo-senpi reviewers #then the final story completes", async () => {
+		process.env["OMO_AGENT_TOOLKIT_SURFACE"] = "omo-senpi";
+		const repo = await repoWith(
+			plan([passGoal("G001", { status: "complete" }), passGoal("G002")], { activeGoalId: "G002" }),
+		);
+
+		const result = await checkpointUlwLoop(repo, {
+			goalId: "G002",
+			status: "complete",
+			evidence: "final work complete and validation passed",
+			codexGoalJson: snapshot("complete"),
+			qualityGateJson: await qualityGateJson(repo, undefined, "G001-finished", "omo-senpi"),
+		});
+
+		expect(result.aggregateCompletion?.status).toBe("complete");
+	});
+
+	it("#given the omo-senpi surface #when the gate names lazycodex reviewers #then the final story is rejected", async () => {
+		process.env["OMO_AGENT_TOOLKIT_SURFACE"] = "omo-senpi";
+		const repo = await repoWith(
+			plan([passGoal("G001", { status: "complete" }), passGoal("G002")], { activeGoalId: "G002" }),
+		);
+		const gateJson = await qualityGateJson(repo);
+
+		await expectCode(
+			() =>
+				checkpointUlwLoop(repo, {
+					goalId: "G002",
+					status: "complete",
+					evidence: "final work complete and validation passed",
+					codexGoalJson: snapshot("complete"),
+					qualityGateJson: gateJson,
+				}),
+			"ULW_LOOP_QUALITY_GATE_INVALID",
+		);
+	});
+});
+
 describe("checkpointUlwLoop final story", () => {
 	it("requires quality-gate-json for the final goal complete", async () => {
 		const repo = await repoWith(

package/packages/omo-codex/plugin/components/ulw-loop/test/cli-create-goals.test.ts

@@ -13,6 +13,7 @@ let err: string[];
 let originalCodexSessionId: string | undefined;
 let originalCodexThreadId: string | undefined;
 let originalOmoSessionId: string | undefined;
+let originalPiSessionId: string | undefined;
 
 beforeEach(async () => {
 	testDir = await mkdtemp(join(tmpdir(), "ug-cli-create-goals-"));
@@ -21,9 +22,11 @@ beforeEach(async () => {
 	originalCodexSessionId = process.env["CODEX_SESSION_ID"];
 	originalCodexThreadId = process.env["CODEX_THREAD_ID"];
 	originalOmoSessionId = process.env["OMO_ULW_LOOP_SESSION_ID"];
+	originalPiSessionId = process.env["PI_SESSION_ID"];
 	delete process.env["CODEX_SESSION_ID"];
 	delete process.env["CODEX_THREAD_ID"];
 	delete process.env["OMO_ULW_LOOP_SESSION_ID"];
+	delete process.env["PI_SESSION_ID"];
 	vi.spyOn(process, "cwd").mockReturnValue(testDir);
 	vi.spyOn(process.stdout, "write").mockImplementation((chunk: string | Uint8Array): boolean => {
 		out.push(chunk.toString());
@@ -43,6 +46,8 @@ afterEach(async () => {
 	else process.env["CODEX_THREAD_ID"] = originalCodexThreadId;
 	if (originalOmoSessionId === undefined) delete process.env["OMO_ULW_LOOP_SESSION_ID"];
 	else process.env["OMO_ULW_LOOP_SESSION_ID"] = originalOmoSessionId;
+	if (originalPiSessionId === undefined) delete process.env["PI_SESSION_ID"];
+	else process.env["PI_SESSION_ID"] = originalPiSessionId;
 	await rm(testDir, { recursive: true, force: true });
 });
 
@@ -182,6 +187,26 @@ describe("ulwLoopCommand create-goals", () => {
 		expect(await readFile(join(testDir, ".omo/ulw-loop/manual-456/goals.json"), "utf8")).toContain("Manual scoped");
 	});
 
+	it("#given two Senpi sessions in one cwd #when each reads ulw-loop state #then only the owner sees its run", async () => {
+		process.env["PI_SESSION_ID"] = "session-A";
+		expect(await ulwLoopCommand(["create-goals", "--brief", "- Session A run", "--json"])).toBe(0);
+		resetOutput();
+
+		process.env["PI_SESSION_ID"] = "session-B";
+		expect(await ulwLoopCommand(["status", "--json"])).toBe(1);
+		expect(stdoutJson()).toMatchObject({ ok: false, error: { code: "ULW_LOOP_PLAN_MISSING" } });
+		resetOutput();
+
+		process.env["PI_SESSION_ID"] = "session-A";
+		expect(await ulwLoopCommand(["status", "--json"])).toBe(0);
+		expect(stdoutJson()).toMatchObject({
+			plan: {
+				goalsPath: ".omo/ulw-loop/session-A/goals.json",
+				goals: [{ title: "Session A run" }],
+			},
+		});
+	});
+
 	it("#given a valueless --session-id #when creating goals #then it fails and writes no plan", async () => {
 		const code = await ulwLoopCommand(["create-goals", "--session-id", "--brief", "- Alpha"]);
 

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

@@ -91,12 +91,36 @@ describe("dist/cli.js entrypoint dispatch", () => {
 		expect(result.code).toBe(1);
 	});
 
-	it("#given the top-level entrypoint #when invoked with 'help' #then prints usage and exits 0", async () => {
+	it("#given the top-level entrypoint #when invoked with 'help' #then prints the merged hook and subcommand usage and exits 0", async () => {
 		const result = await runCli(["help"]);
 
 		expect(result.code).toBe(0);
 		expect(result.stdout).toContain("Usage:");
-		expect(result.stdout).toContain("omo-agent-toolkit ulw-loop <subcommand>");
+		expect(result.stdout).toContain("hook user-prompt-submit");
+		expect(result.stdout).toContain("create-goals");
+		expect(result.stdout).toContain("complete-goals");
+		expect(result.stdout).toContain("record-review-blockers");
+		expect(result.stdout).not.toContain("for ulw-loop subcommands");
+	});
+
+	it("#given the staged router strips nothing #when invoked with 'ulw-loop help' #then prints the same merged help text", async () => {
+		const bare = await runCli(["help"]);
+		const nested = await runCli(["ulw-loop", "help"]);
+
+		expect(nested.code).toBe(0);
+		expect(nested.stdout.trim()).toBe(bare.stdout.trim());
+		expect(nested.stdout).toContain("hook user-prompt-submit");
+		expect(nested.stdout).toContain("record-review-blockers");
+		expect(nested.stdout).not.toContain("for ulw-loop subcommands");
+	});
+
+	it("#given a subcommand with required args #when invoked with 'create-goals --help' #then prints its usage and exits 0", async () => {
+		const result = await runCli(["create-goals", "--help"]);
+
+		expect(result.code).toBe(0);
+		expect(result.stdout).toContain("Usage:");
+		expect(result.stdout).toContain("create-goals");
+		expect(`${result.stdout}${result.stderr}`).not.toContain("Missing brief text");
 	});
 
 	it("#given a command outside the ulw-loop vocabulary #when invoked with 'frobnicate' #then fails as unknown command", async () => {

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

@@ -6,6 +6,7 @@ import type { UlwLoopItem, UlwLoopPlan, UlwLoopSuccessCriterion } from "../src/t
 
 const NOW = "2026-05-23T00:00:00.000Z";
 const FINAL_REVIEW_ROLES = ["lazycodex-code-reviewer", "lazycodex-qa-executor", "lazycodex-gate-reviewer"] as const;
+const SENPI_REVIEW_ROLES = ["omo-senpi-code-reviewer", "omo-senpi-qa-executor", "omo-senpi-gate-reviewer"] as const;
 const QUALITY_GATE_SECTIONS = ["codeReview", "manualQa", "gateReview", "iteration", "criteriaCoverage"] as const;
 
 function makeCriterion(overrides: Partial<UlwLoopSuccessCriterion> = {}): UlwLoopSuccessCriterion {
@@ -94,6 +95,30 @@ describe("buildCodexGoalInstruction aggregate mode", () => {
 		expect(text).toContain("checkpoint");
 	});
 
+	it("#given a final story on the omo-senpi surface #when rendering instructions #then names the omo-senpi reviewers only", () => {
+		const { text } = buildCodexGoalInstruction({
+			plan: makePlan({ codexGoalMode: "aggregate" }),
+			goal: makeGoal(),
+			isFinal: true,
+			surface: "omo-senpi",
+		});
+
+		expectTextToContainAll(text, SENPI_REVIEW_ROLES);
+		for (const role of FINAL_REVIEW_ROLES) expect(text).not.toContain(role);
+	});
+
+	it("#given a final story with the explicit lazycodex surface #when rendering instructions #then keeps the lazycodex reviewers", () => {
+		const { text } = buildCodexGoalInstruction({
+			plan: makePlan({ codexGoalMode: "aggregate" }),
+			goal: makeGoal(),
+			isFinal: true,
+			surface: "lazycodex",
+		});
+
+		expectTextToContainAll(text, FINAL_REVIEW_ROLES);
+		for (const role of SENPI_REVIEW_ROLES) expect(text).not.toContain(role);
+	});
+
 	it("#given a scoped plan #when rendering final commands #then includes the session id option", () => {
 		const { text } = buildCodexGoalInstruction({
 			plan: makePlan({
@@ -113,9 +138,9 @@ describe("buildCodexGoalInstruction aggregate mode", () => {
 
 describe("buildCodexGoalInstruction per_story mode", () => {
 	it("uses the goal's own objective for create_goal", () => {
-		const goal = makeGoal({ objective: "Build the auth service" });
+		const goal = makeGoal({ objective: "per-story-objective-sentinel" });
 		const { text } = buildCodexGoalInstruction({ plan: makePlan({ codexGoalMode: "per_story" }), goal });
-		expect(text).toContain("Build the auth service");
+		expect(text).toContain("per-story-objective-sentinel");
 	});
 });
 

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

@@ -24,6 +24,24 @@ describe("parseCodexGoalSnapshot", () => {
 		expect(snapshot.status).toBe("active");
 	});
 
+	it("reads the objective from a title-bearing ulw-loop status goal", () => {
+		// given
+		const payload = {
+			id: "G002-goal-2-senpi-repo-audit-determine-wh",
+			title: "Audit the Senpi repository",
+			status: "in_progress",
+			successCriteria: [],
+		};
+
+		// when
+		const snapshot = parseCodexGoalSnapshot(payload);
+
+		// then
+		expect(snapshot.available).toBe(true);
+		expect(snapshot.objective).toBe("Audit the Senpi repository");
+		expect(snapshot.status).toBe("active");
+	});
+
 	it("ignores remaining token budget fields from goal snapshots", () => {
 		// given
 		const payload = { goal: { objective: "X", status: "active" }, remainingTokens: 123 };

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

@@ -242,7 +242,6 @@ describe("applyPreToolUseGoalBudgetGuard", () => {
 				permissionDecision: "deny",
 			},
 		});
-		expect(parsed.hookSpecificOutput.permissionDecisionReason).toContain("objective only");
 		expect(parsed.hookSpecificOutput.permissionDecisionReason).toContain("token_budget");
 		expect(parsed.hookSpecificOutput.permissionDecisionReason).toContain("unlimited");
 		expect(parsed.hookSpecificOutput.permissionDecisionReason).toContain("update_goal");
@@ -258,7 +257,6 @@ describe("applyPreToolUseGoalBudgetGuard", () => {
 		// then
 		const parsed = JSON.parse(output);
 		expect(parsed.hookSpecificOutput.permissionDecision).toBe("deny");
-		expect(parsed.hookSpecificOutput.permissionDecisionReason).toContain("objective only");
 		expect(parsed.hookSpecificOutput.permissionDecisionReason).toContain("update_goal");
 	});
 
@@ -272,7 +270,6 @@ describe("applyPreToolUseGoalBudgetGuard", () => {
 		// then
 		const parsed = JSON.parse(output);
 		expect(parsed.hookSpecificOutput.permissionDecision).toBe("deny");
-		expect(parsed.hookSpecificOutput.permissionDecisionReason).toContain("objective only");
 	});
 
 	it("#given create_goal omits token_budget #when PreToolUse runs #then it stays silent", () => {

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

@@ -1,6 +1,8 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
+import { reviewerRolesFor, type UlwLoopToolkitSurface } from "../../src/surface.js";
+
 // v2 evidence layout: artifacts must live inside the goal's current attempt dir
 export function qaDirFor(goalId: string, attempt = 1, sessionId = "session"): string {
 	return `.omo/evidence/ulw/${sessionId}/${goalId}/a${attempt}`;
@@ -25,13 +27,15 @@ export async function qualityGateJson(
 	repoRoot: string,
 	cliArtifactPath?: string,
 	goalId = "G001-finished",
+	surface: UlwLoopToolkitSurface = "lazycodex",
 ): Promise<string> {
+	const roles = reviewerRolesFor(surface);
 	const qaDir = qaDirFor(goalId);
 	await writeQualityGateArtifacts(repoRoot, qaDir);
 	const cliPath = cliArtifactPath ?? `${qaDir}/cli-pass.txt`;
 	return JSON.stringify({
 		codeReview: {
-			by: "lazycodex-code-reviewer",
+			by: roles.codeReview,
 			recommendation: "APPROVE",
 			codeQualityStatus: "CLEAR",
 			reportPath: `${qaDir}/code-review.md`,
@@ -39,7 +43,7 @@ export async function qualityGateJson(
 			blockers: [],
 		},
 		manualQa: {
-			by: "lazycodex-qa-executor",
+			by: roles.manualQa,
 			status: "passed",
 			evidence: "Ran CLI checkpoint validation with artifact-backed evidence.",
 			surfaceEvidence: [
@@ -78,7 +82,7 @@ export async function qualityGateJson(
 			],
 		},
 		gateReview: {
-			by: "lazycodex-gate-reviewer",
+			by: roles.gateReview,
 			recommendation: "APPROVE",
 			reportPath: `${qaDir}/gate-review.md`,
 			evidence: "Verified all criteria and artifact evidence.",

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

@@ -24,9 +24,7 @@ type ShellResult = {
 };
 
 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);
+	const blockStart = text.indexOf("```sh\n");
 	expect(blockStart).toBeGreaterThanOrEqual(0);
 	const codeStart = blockStart + "```sh\n".length;
 	const blockEnd = text.indexOf("\n```", codeStart);
@@ -90,7 +88,8 @@ describe("hooks/hooks.json", () => {
 		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;
+		const command = (events[0]?.["hooks"] as readonly Record<string, unknown>[] | undefined)?.[0]?.["command"];
+		expect(command).toEqual(expect.any(String));
 		expect(command).toContain(`$${"{PLUGIN_ROOT}"}`);
 		expect(command).toContain("dist/cli.js");
 		expect(command).toContain("hook user-prompt-submit");
@@ -129,9 +128,7 @@ describe("skills/ulw-loop/SKILL.md", () => {
 		const text = await readText("skills/ulw-loop/agents/openai.yaml");
 
 		expect(text).toContain('display_name: "(OmO) ulw-loop"');
-		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 () => {
@@ -172,7 +169,7 @@ describe("skills/ulw-loop/SKILL.md", () => {
 				].join("\n"),
 			);
 
-			const result = await runShell(`${bootstrap}\n\"$ULW_LOOP_NODE\" \"$ULW_LOOP_CLI\" ulw-loop status --json`, {
+			const result = await runShell(`${bootstrap}\n"$ULW_LOOP_NODE" "$ULW_LOOP_CLI" ulw-loop status --json`, {
 				...process.env,
 				CODEX_HOME: codexHome,
 				HOME: home,
@@ -181,7 +178,6 @@ describe("skills/ulw-loop/SKILL.md", () => {
 
 			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 });
 		}
@@ -189,27 +185,7 @@ describe("skills/ulw-loop/SKILL.md", () => {
 
 });
 
-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/quality-gate-verdicts.ts", "src/checkpoint.ts", "src/review-blockers.ts",
-			"src/stop-resume-hook.ts", "src/spawn-guard.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);
-		}
-	});
-});
-
-describe("README implementation contract", () => {
+	describe("README implementation contract", () => {
 	it("#given the README #when subcommands are inspected #then every implemented CLI subcommand is documented", async () => {
 		const readme = await readText("README.md");
 
@@ -218,14 +194,6 @@ describe("README implementation contract", () => {
 		}
 	});
 
-	it("#given the README #when stale scaffold language is checked #then it is absent", async () => {
-		const readme = await readText("README.md");
-
-		expect(readme).not.toMatch(/scaffold only/i);
-		expect(readme).not.toMatch(/Wave 1/i);
-		expect(readme).not.toMatch(/lands in later waves/i);
-	});
-
 	it("#given the README #when hooks are described #then both hook channels are documented", async () => {
 		const readme = await readText("README.md");
 

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

@@ -7,6 +7,7 @@ import {
 	isWithinAttemptDir,
 	normalizeUlwLoopSessionId,
 	repoRelative,
+	resolveUlwLoopSessionIdFromEnv,
 	ulwLoopBriefPath,
 	ulwLoopDir,
 	ulwLoopGoalsPath,
@@ -25,6 +26,14 @@ describe("ulwLoopDir(repo)", () => {
 	});
 });
 
+describe("resolveUlwLoopSessionIdFromEnv", () => {
+	it("#given a Senpi session env #when resolving scope #then uses the current Pi session id", () => {
+		expect(resolveUlwLoopSessionIdFromEnv({ PI_SESSION_ID: "01a00baf-feed-7f4d-a4a9-b8345c67cf72" })).toBe(
+			"01a00baf-feed-7f4d-a4a9-b8345c67cf72",
+		);
+	});
+});
+
 describe("ulw-loop*Path helpers", () => {
 	it("compose artifact filenames under ulwLoopDir", () => {
 		// when/then