oh-my-opencode 5.0.0-beta.9 → 5.0.0

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

@@ -1,6 +1,7 @@
 // biome-ignore-all format: compact batch steering module stays below the pure LOC budget.
 import type { UlwLoopScope } from "./paths.js";
-import { appendLedger, appendLedgerEntries, findAcceptedSteeringLedgerEntry, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
+import { commit } from "./plan-commit.js";
+import { findAcceptedSteeringLedgerEntry, readUlwLoopPlan, withUlwLoopMutationLock } from "./plan-io.js";
 import { applySteeringMutation, validateUlwLoopSteeringProposal } from "./steering.js";
 import { buildSteeringPlanSnapshot, changedGoalIdsBetween } from "./steering-snapshot.js";
 import type { UlwLoopLedgerEntry, UlwLoopPlan, UlwLoopSteeringAudit, UlwLoopSteeringProposal } from "./types.js";
@@ -43,17 +44,16 @@ export async function steerUlwLoopBatch(
 		const failed = prepared.results.find((item) => !item.accepted);
 		if (failed !== undefined) {
 			const entry = rejectedLedgerEntry(prepared.results);
-			await appendLedger(repoRoot, entry, scope);
+			await commit(repoRoot, scope, { plan, entries: [entry] });
 			return rejected(plan, prepared.results, failed.rejectedReasons);
 		}
 		let next = plan;
 		for (const item of prepared.items) if (item.kind === "fresh") next = item.prepared.next;
 		const fresh = prepared.items.filter((item): item is Extract<PreparedItem, { readonly kind: "fresh" }> => item.kind === "fresh");
 		if (fresh.length > 0) {
-			await writePlan(repoRoot, next, scope);
 			const entries = fresh.map((item) => ledgerEntry(item.prepared.proposal, item.prepared.audit, item.prepared.proposal.now?.toISOString() ?? iso()));
 			const batchEntry = batchUpdateLedgerEntry(plan, next, iso());
-			await appendLedgerEntries(repoRoot, batchEntry === null ? entries : [...entries, batchEntry], scope);
+			await commit(repoRoot, scope, { plan: next, entries: batchEntry === null ? entries : [...entries, batchEntry] });
 		}
 		return { plan: next, accepted: true, results: prepared.results, rejectedReasons: [] };
 	});

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

@@ -1,5 +1,6 @@
 // biome-ignore-all format: compact extracted steering mutations stay below the pure LOC budget.
 import { seedDefaultSuccessCriteria } from "./plan-crud.js";
+import type { UlwLoopToolkitSurface } from "./surface.js";
 import type { UlwLoopItem, UlwLoopPlan, UlwLoopSteeringChildGoal, UlwLoopSteeringProposal, UlwLoopSuccessCriterionUserModel } from "./types.js";
 import { ULW_LOOP_SUCCESS_CRITERION_USER_MODELS } from "./types.js";
 import { updateBatchesAfterSupersede } from "./validation-batch.js";
@@ -30,9 +31,9 @@ function nextId(plan: UlwLoopPlan, offset: number): string {
 	return `G${String(max + offset).padStart(3, "0")}`;
 }
 
-export function makeGoal(plan: UlwLoopPlan, childGoal: UlwLoopSteeringChildGoal, evidence: string, now: string, offset: number): UlwLoopItem {
+export function makeGoal(plan: UlwLoopPlan, childGoal: UlwLoopSteeringChildGoal, evidence: string, now: string, offset: number, surface: UlwLoopToolkitSurface = "lazycodex"): UlwLoopItem {
 	const id = nextId(plan, offset); const digits = /^G(\d+)/u.exec(id)?.[1]; const goalIndex = digits === undefined ? plan.goals.length + offset - 1 : Number(digits) - 1;
-	return { id, title: childGoal.title, objective: childGoal.objective, status: "pending", successCriteria: seedDefaultSuccessCriteria(goalIndex, childGoal.objective), attempt: 0, createdAt: now, updatedAt: now, evidence };
+	return { id, title: childGoal.title, objective: childGoal.objective, status: "pending", successCriteria: seedDefaultSuccessCriteria(goalIndex, childGoal.objective, { goalId: id, surface }), attempt: 0, createdAt: now, updatedAt: now, evidence };
 }
 
 export function reviseWording(plan: UlwLoopPlan, proposal: UlwLoopSteeringProposal, now: string): void {
@@ -41,9 +42,9 @@ export function reviseWording(plan: UlwLoopPlan, proposal: UlwLoopSteeringPropos
 	target.steeringEvidence = proposal.evidence; target.steeringRationale = proposal.rationale; target.updatedAt = now;
 }
 
-export function splitOrBlock(plan: UlwLoopPlan, proposal: UlwLoopSteeringProposal, now: string): void {
+export function splitOrBlock(plan: UlwLoopPlan, proposal: UlwLoopSteeringProposal, now: string, surface: UlwLoopToolkitSurface = "lazycodex"): void {
 	const target = goal(plan, targets(proposal)[0]); if (target === undefined) return;
-	const replacements = children(proposal).map((item, index) => makeGoal(plan, item, proposal.evidence, now, index + 1));
+	const replacements = children(proposal).map((item, index) => makeGoal(plan, item, proposal.evidence, now, index + 1, surface));
 	target.steeringEvidence = proposal.evidence; target.steeringRationale = proposal.rationale; target.updatedAt = now;
 	if (replacements.length === 0) { target.status = "blocked"; target.steeringStatus = "blocked"; target.blockedReason = proposal.blockedReason ?? proposal.rationale; }
 	else { target.steeringStatus = "superseded"; target.supersededBy = replacements.map((item) => item.id); for (const item of replacements) item.supersedes = [target.id]; plan.goals.splice(plan.goals.indexOf(target) + 1, 0, ...replacements); updateBatchesAfterSupersede(plan, target.id, replacements.map((item) => item.id)); }

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

@@ -1,4 +1,8 @@
-import type { UlwLoopSteeringMutationKind, UlwLoopSteeringSource } from "./constants.js";
+import type {
+	UlwLoopSteeringMutationKind,
+	UlwLoopSteeringSource,
+	UlwLoopSuccessCriterionUserModel,
+} from "./constants.js";
 import type { UlwLoopItem, UlwLoopPlan } from "./domain-types.js";
 
 export interface UlwLoopSteeringInvariantResult {
@@ -25,9 +29,17 @@ export interface UlwLoopSteeringAfterPayload {
 export interface UlwLoopSteeringProposal {
 	kind: UlwLoopSteeringMutationKind;
 	source: UlwLoopSteeringSource;
+	/** Alias of `targetGoalId`; the SDK documentation uses `goalId` like every other operation. */
+	goalId?: string;
 	targetGoalId?: string;
 	targetGoalIds?: string[];
 	criterionId?: string;
+	/** `revise_criterion` payload: the replacement scenario text. */
+	scenario?: string;
+	/** `revise_criterion` payload: the replacement observable-proof text. */
+	expectedEvidence?: string;
+	/** `revise_criterion` payload: the replacement user model. */
+	userModel?: UlwLoopSuccessCriterionUserModel;
 	evidence: string;
 	rationale: string;
 	title?: string;

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

@@ -1,9 +1,11 @@
 // biome-ignore-all format: compact steering module must stay below the 240 pure-LOC budget
 import { isUlwLoopDone } from "./goal-status.js";
 import type { UlwLoopScope } from "./paths.js";
-import { appendLedger, findAcceptedSteeringLedgerEntry, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
+import { commit } from "./plan-commit.js";
+import { findAcceptedSteeringLedgerEntry, readUlwLoopPlan, withUlwLoopMutationLock } from "./plan-io.js";
 import { makeGoal, reviseCriterion, reviseWording, splitOrBlock } from "./steering-mutations.js";
 import { buildSteeringPlanSnapshot, changedGoalIdsBetween } from "./steering-snapshot.js";
+import type { UlwLoopToolkitSurface } from "./surface.js";
 import type {
 	SteerUlwLoopResult,
 	UlwLoopItem,
@@ -20,7 +22,7 @@ import { iso, ULW_LOOP_STEERING_MUTATION_KINDS, ULW_LOOP_SUCCESS_CRITERION_USER_
 import { batchUpdateLedgerEntry } from "./validation-batch.js";
 
 const SOURCES = ["user_prompt_submit", "finding", "cli"] as const satisfies readonly UlwLoopSteeringSource[];
-const PROTECTED = new Set(["aggregateCompletion", "codexObjective", "codexObjectiveAliases", "originalConstraints", "qualityGate", "status", "completedAt", "completionStatus"]);
+const PROTECTED = new Set(["aggregateCompletion", "codexObjective", "codexObjectiveAliases", "acknowledgedDriverObjectives", "originalConstraints", "qualityGate", "status", "completedAt", "completionStatus"]);
 const isObject = (value: unknown): value is object => typeof value === "object" && value !== null; const isPlain = (value: unknown): value is object => isObject(value) && !Array.isArray(value);
 const read = (value: object, key: string): unknown => Object.entries(value).find(([name]) => name === key)?.[1];
 const isText = (value: unknown): value is string => typeof value === "string" && value.trim().length > 0;
@@ -155,17 +157,17 @@ function validateCriterion(plan: UlwLoopPlan, proposal: object, reasons: string[
 	if (model !== undefined && !isModel(model)) reasons.push("invalid userModel");
 }
 
-export function applySteeringMutation(plan: UlwLoopPlan, proposal: UlwLoopSteeringProposal, audit: UlwLoopSteeringAudit): UlwLoopPlan {
+export function applySteeringMutation(plan: UlwLoopPlan, proposal: UlwLoopSteeringProposal, audit: UlwLoopSteeringAudit, surface: UlwLoopToolkitSurface = "lazycodex"): UlwLoopPlan {
 	const next = structuredClone(plan);
 	if (!audit.invariant.accepted) return next;
 	const now = proposal.now?.toISOString() ?? iso();
-	if (proposal.kind === "add_subgoal") next.goals.push(makeGoal(next, { title: proposal.title ?? "", objective: proposal.objective ?? "" }, proposal.evidence, now, 1));
+	if (proposal.kind === "add_subgoal") next.goals.push(makeGoal(next, { title: proposal.title ?? "", objective: proposal.objective ?? "" }, proposal.evidence, now, 1, surface));
 	if (proposal.kind === "reorder_pending") {
 		const order = pendingOrder(proposal);
 		next.goals = [...order.map((id) => goal(next, id)).filter((item): item is UlwLoopItem => item !== undefined), ...next.goals.filter((item) => !order.includes(item.id))];
 	}
 	if (proposal.kind === "revise_pending_wording") reviseWording(next, proposal, now);
-	if (proposal.kind === "split_subgoal" || proposal.kind === "mark_blocked_superseded") splitOrBlock(next, proposal, now);
+	if (proposal.kind === "split_subgoal" || proposal.kind === "mark_blocked_superseded") splitOrBlock(next, proposal, now, surface);
 	if (proposal.kind === "revise_criterion") reviseCriterion(next, proposal, now);
 	if (proposal.kind !== "annotate_ledger") next.updatedAt = now;
 	return next;
@@ -187,7 +189,7 @@ export function parseUlwLoopSteeringDirective(text: string): UlwLoopSteeringProp
 	}
 }
 
-export async function steerUlwLoop(repoRoot: string, proposal: UlwLoopSteeringProposal, scope?: UlwLoopScope): Promise<SteerUlwLoopResult> {
+export async function steerUlwLoop(repoRoot: string, proposal: UlwLoopSteeringProposal, scope?: UlwLoopScope, surface: UlwLoopToolkitSurface = "lazycodex"): Promise<SteerUlwLoopResult> {
 	return withUlwLoopMutationLock(repoRoot, scope, async () => {
 		const plan = await readUlwLoopPlan(repoRoot, scope);
 		const key = proposal.idempotencyKey ?? proposal.promptSignature;
@@ -200,7 +202,7 @@ export async function steerUlwLoop(repoRoot: string, proposal: UlwLoopSteeringPr
 		}
 		const audit = validateUlwLoopSteeringProposal(plan, proposal);
 		const accepted = audit.invariant.accepted;
-		const next = accepted ? applySteeringMutation(plan, proposal, audit) : plan;
+		const next = accepted ? applySteeringMutation(plan, proposal, audit, surface) : plan;
 		const finalAudit: UlwLoopSteeringAudit = { ...audit };
 		if (accepted) {
 			const changed = changedGoalIdsBetween(plan, next);
@@ -209,9 +211,9 @@ export async function steerUlwLoop(repoRoot: string, proposal: UlwLoopSteeringPr
 		}
 		const at = proposal.now?.toISOString() ?? iso();
 		const batchEntry = accepted ? batchUpdateLedgerEntry(plan, next, at) : null;
-		if (accepted) await writePlan(repoRoot, next, scope);
-		await appendLedger(repoRoot, ledgerEntry(proposal, finalAudit, at), scope);
-		if (batchEntry !== null) await appendLedger(repoRoot, batchEntry, scope);
+		const entries = [ledgerEntry(proposal, finalAudit, at)];
+		if (batchEntry !== null) entries.push(batchEntry);
+		await commit(repoRoot, scope, { plan: next, entries });
 		return { plan: next, accepted, audit: finalAudit, rejectedReasons: audit.invariant.rejectedReasons, deduped: false };
 	});
 }

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

@@ -1,7 +1,10 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, resolve, sep } from "node:path";
 
-import { normalizeUlwLoopSessionId, ulwLoopDir } from "./paths.js";
+import { readLedgerAt } from "./ledger.js";
+import { normalizeUlwLoopSessionId, ulwLoopDir, ulwLoopStateLockPath } from "./paths.js";
+import { readUlwLoopPlanSync } from "./plan-io.js";
+import { isStateLockTimeout, withStateLockSync } from "./state-lock.js";
 import type { UlwLoopItem, UlwLoopPlan } from "./types.js";
 
 // Turn-death recovery only: Codex emits Stop when a turn ends, so a run that
@@ -10,7 +13,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",
@@ -34,12 +37,13 @@ export function runStopResumeHook(input: unknown): string {
 	if (payload === null || payload.stop_hook_active) return "";
 	if (transcriptShowsContextPressure(payload.transcript_path)) return "";
 	if (boulderContinuationWillFire(payload.cwd, payload.session_id)) return "";
-	const stateDir = ulwLoopDir(payload.cwd, { sessionId: payload.session_id });
-	const plan = readPlan(join(stateDir, "goals.json"));
+	const scope = { sessionId: payload.session_id } as const;
+	const stateDir = ulwLoopDir(payload.cwd, scope);
+	const plan = readPlan(payload.cwd, payload.session_id);
 	if (plan === null || plan.aggregateCompletion?.status === "complete") return "";
 	const goal = resumableGoal(plan);
 	if (goal === undefined) return "";
-	if (!consumeResumeBudget(stateDir, goal.id)) return "";
+	if (!consumeResumeBudgetLocked(ulwLoopStateLockPath(payload.cwd, scope), stateDir, goal.id)) return "";
 	const output: { decision: "block"; reason: string } = {
 		decision: "block",
 		reason: renderResumeDirective(plan, goal, payload.session_id),
@@ -68,11 +72,21 @@ function isResumableStatus(status: UlwLoopItem["status"]): boolean {
 	return status === "pending" || status === "in_progress";
 }
 
-// Two-strike cap keyed on ledger movement: an unchanged ledger.jsonl line
-// count across resumes means the loop is not progressing. The stuck marker is
-// a separate file — a ledger append would change the count and self-reset.
+// A resume is a budgeted side effect; when the session lock cannot be taken the
+// hook stays silent (fail closed) instead of charging the counter unlocked.
+function consumeResumeBudgetLocked(lockPath: string, stateDir: string, goalId: string): boolean {
+	try {
+		return withStateLockSync(lockPath, () => consumeResumeBudget(stateDir, goalId));
+	} catch (error) {
+		if (isStateLockTimeout(error)) return false;
+		throw error;
+	}
+}
+
+// Hook budget counters are exempt from plan/audit commits. Count reconciled
+// entries, not cache lines: a writer dying after link still made progress.
 function consumeResumeBudget(stateDir: string, goalId: string): boolean {
-	const ledgerLineCount = countLedgerLines(join(stateDir, "ledger.jsonl"));
+	const ledgerLineCount = readLedgerAt(stateDir).length;
 	const counterPath = resolve(stateDir, `auto-resume-${goalId}.json`);
 	const stuckPath = resolve(stateDir, `auto-resume-${goalId}.stuck`);
 	// goals.json is untrusted input: a crafted goal id (e.g. `../../x`) must
@@ -106,24 +120,15 @@ function renderResumeDirective(plan: UlwLoopPlan, goal: UlwLoopItem, sessionId:
 	].join("\n");
 }
 
-function readPlan(goalsPath: string): UlwLoopPlan | null {
+function readPlan(repoRoot: string, sessionId: string): UlwLoopPlan | null {
 	try {
-		return JSON.parse(readFileSync(goalsPath, "utf8")) as UlwLoopPlan;
+		return readUlwLoopPlanSync(repoRoot, { sessionId });
 	} catch (error) {
 		if (error instanceof Error) return null;
 		throw error;
 	}
 }
 
-function countLedgerLines(ledgerPath: string): number {
-	try {
-		return readFileSync(ledgerPath, "utf8").split("\n").filter(Boolean).length;
-	} catch (error) {
-		if (error instanceof Error) return 0;
-		throw error;
-	}
-}
-
 function readCounter(counterPath: string): { count: number; ledgerLineCount: number } | null {
 	try {
 		if (!existsSync(counterPath)) return null;
@@ -136,7 +141,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 +173,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/success-criteria-input.ts

@@ -0,0 +1,56 @@
+import type { UlwLoopSuccessCriterion, UlwLoopSuccessCriterionUserModel } from "./types.js";
+import { ULW_LOOP_SUCCESS_CRITERION_USER_MODELS, UlwLoopError } from "./types.js";
+
+export interface SuccessCriterionInput {
+	readonly scenario: string;
+	readonly expectedEvidence: string;
+	readonly userModel?: UlwLoopSuccessCriterionUserModel;
+	readonly essential?: boolean;
+}
+
+function invalid(message: string, details: Record<string, unknown>): never {
+	throw new UlwLoopError(`Invalid successCriteria: ${message}`, "ULW_LOOP_ARGUMENT_INVALID", { details });
+}
+
+function isUserModel(value: unknown): value is UlwLoopSuccessCriterionUserModel {
+	return typeof value === "string" && ULW_LOOP_SUCCESS_CRITERION_USER_MODELS.some((model) => model === value);
+}
+
+function requireText(value: unknown, field: string, index: number): string {
+	const trimmed = typeof value === "string" ? value.trim() : "";
+	return trimmed || invalid(`entry ${index + 1} needs a non-empty ${field}.`, { index, field });
+}
+
+export function criterionId(index: number): string {
+	return `C${String(index + 1).padStart(3, "0")}`;
+}
+
+export function criteriaFromInput(input: readonly unknown[]): UlwLoopSuccessCriterion[] {
+	if (input.length === 0) invalid("provide at least one criterion or omit the field for placeholders.", { count: 0 });
+	return input.map((entry, index) => {
+		if (typeof entry !== "object" || entry === null || Array.isArray(entry))
+			return invalid(`entry ${index + 1} must be an object.`, { index });
+		const record: Record<string, unknown> = { ...entry };
+		const userModel = record["userModel"] ?? "happy";
+		if (!isUserModel(userModel))
+			return invalid(
+				`entry ${index + 1} userModel must be one of ${ULW_LOOP_SUCCESS_CRITERION_USER_MODELS.join(", ")}.`,
+				{
+					index,
+					userModel: String(userModel),
+				},
+			);
+		const essential = record["essential"];
+		if (essential !== undefined && typeof essential !== "boolean")
+			return invalid(`entry ${index + 1} essential must be a boolean.`, { index });
+		return {
+			id: criterionId(index),
+			scenario: requireText(record["scenario"], "scenario", index),
+			userModel,
+			expectedEvidence: requireText(record["expectedEvidence"], "expectedEvidence", index),
+			essential: essential ?? true,
+			capturedEvidence: null,
+			status: "pending",
+		};
+	});
+}

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

@@ -0,0 +1,133 @@
+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-native-code-reviewer",
+		manualQa: "omo-native-qa-executor",
+		gateReview: "omo-native-gate-reviewer",
+	},
+};
+
+// The reviewer agents were renamed omo-senpi-* -> omo-native-*. The retired spellings stay
+// resolvable for one release line so a caller that still names one is recognized rather than
+// silently treated as a non-review spawn.
+export const LEGACY_REVIEWER_AGENT_ALIASES: Readonly<Record<string, string>> = {
+	"omo-senpi-code-reviewer": REVIEWER_ROLES_BY_SURFACE["omo-senpi"].codeReview,
+	"omo-senpi-qa-executor": REVIEWER_ROLES_BY_SURFACE["omo-senpi"].manualQa,
+	"omo-senpi-gate-reviewer": REVIEWER_ROLES_BY_SURFACE["omo-senpi"].gateReview,
+};
+
+export function canonicalReviewerAgentName(reviewer: string): string {
+	return LEGACY_REVIEWER_AGENT_ALIASES[reviewer] ?? reviewer;
+}
+
+const CANONICAL_GATE_REVIEW_NAMES = Object.values(REVIEWER_ROLES_BY_SURFACE).map((roles) => roles.gateReview);
+
+export const GATE_REVIEWER_AGENT_NAMES: ReadonlySet<string> = new Set([
+	...CANONICAL_GATE_REVIEW_NAMES,
+	...Object.entries(LEGACY_REVIEWER_AGENT_ALIASES)
+		.filter(([, canonical]) => CANONICAL_GATE_REVIEW_NAMES.includes(canonical))
+		.map(([legacy]) => legacy),
+]);
+
+export type UlwLoopGateSection = "codeReview" | "manualQa" | "gateReview" | "iteration" | "criteriaCoverage";
+
+export const REQUIRED_GATE_SECTIONS_BY_SURFACE: Readonly<Record<UlwLoopToolkitSurface, readonly UlwLoopGateSection[]>> =
+	{
+		lazycodex: ["manualQa", "gateReview", "iteration", "criteriaCoverage"],
+		"omo-senpi": ["manualQa", "gateReview", "iteration", "criteriaCoverage"],
+	};
+
+export const OPTIONAL_GATE_SECTIONS_BY_SURFACE: Readonly<Record<UlwLoopToolkitSurface, readonly UlwLoopGateSection[]>> =
+	{
+		lazycodex: ["codeReview"],
+		"omo-senpi": [],
+	};
+
+export const GATE_SECTION_BY_ACCEPTOR: Readonly<
+	Record<UlwLoopToolkitSurface, Readonly<Partial<Record<UlwLoopGateSection, readonly string[]>>>>
+> = {
+	lazycodex: {
+		codeReview: [REVIEWER_ROLES_BY_SURFACE.lazycodex.codeReview, "main-session"],
+		manualQa: [REVIEWER_ROLES_BY_SURFACE.lazycodex.manualQa, "main-session"],
+		gateReview: [
+			REVIEWER_ROLES_BY_SURFACE.lazycodex.gateReview,
+			"category:deep-high",
+			"category:deep-low",
+			"category:deep",
+			"category:unspecified-high",
+			"category:unspecified-low",
+			"main-session",
+		],
+	},
+	"omo-senpi": {
+		manualQa: ["main-session"],
+		gateReview: [
+			"category:deep-high",
+			"category:deep-low",
+			"category:deep",
+			"category:unspecified-high",
+			"category:unspecified-low",
+		],
+	},
+};
+
+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;
+	}
+}