oh-my-opencode 5.0.0-beta.4 → 5.0.0-beta.42

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

@@ -3,22 +3,11 @@ import { existsSync, statSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import {
-	buildTaskScopedAggregateReconciliationHint,
-	canReconcileActiveFinalTaskScopedAggregateSnapshot,
-	canReconcileCompletedTaskScopedAggregateSnapshot,
-} from "./checkpoint-reconciliation.js";
-import {
-	formatCodexGoalReconciliation,
-	readCodexGoalSnapshotInput,
-	reconcileCodexGoalSnapshot,
-} from "./codex-goal-snapshot.js";
+	combineCheckpointValidationErrors,
+	validateCheckpointCodexGoal,
+} from "./checkpoint-codex-validation.js";
 import { requireAllCriteriaPass, requireAllPlanCriteriaPass, requireEssentialCriteriaPass } from "./evidence.js";
-import {
-	codexGoalMode,
-	compatibleCodexObjectives,
-	expectedCodexObjective,
-	isFinalRunCompletionCandidate,
-} from "./goal-status.js";
+import { codexGoalMode, isFinalRunCompletionCandidate } from "./goal-status.js";
 import type { UlwLoopScope } from "./paths.js";
 import { ulwLoopAttemptEvidenceDir } from "./paths.js";
 import { appendLedger, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
@@ -28,6 +17,7 @@ import {
 	sameBlockerOccurrences,
 	validateQualityGate,
 } from "./quality-gate.js";
+import { resolveToolkitSurface } from "./surface.js";
 import type {
 	UlwLoopAggregateCompletion,
 	UlwLoopItem,
@@ -57,9 +47,6 @@ const QUALITY_GATE_FS = { existsSync, statSync } as const;
 function ulwLoopFail(message: string, code: string): never {
 	throw new UlwLoopError(message, code);
 }
-function normalizeObjective(value: string): string {
-	return value.replace(/\s+/g, " ").trim();
-}
 function nonEmptyEvidence(value: string): string {
 	const trimmed = value.trim();
 	return trimmed || ulwLoopFail("Evidence must be a non-empty string.", "ulw_loop_evidence_required");
@@ -139,13 +126,16 @@ function buildLedger(
 	codexGoal: unknown,
 	aggregateCompletion: UlwLoopAggregateCompletion | undefined,
 ): UlwLoopLedgerEntry {
-	const watch = qualityGate?.codeReview.codeQualityStatus === "WATCH";
+	const watch = qualityGate?.surface === "lazycodex" && qualityGate.codeReview.codeQualityStatus === "WATCH";
 	const entry: UlwLoopLedgerEntry = {
 		at: now,
 		kind: ledgerKind(args.status, goal, aggregateCompletion),
 		goalId: goal.id,
 		status: goal.status,
-		evidence: watch ? `${args.evidence} | codeQuality=WATCH: ${qualityGate.codeReview.evidence}` : args.evidence,
+		evidence:
+			watch && qualityGate.surface === "lazycodex"
+				? `${args.evidence} | codeQuality=WATCH: ${qualityGate.codeReview.evidence}`
+				: args.evidence,
 	};
 	if (codexGoal !== undefined) entry.codexGoal = codexGoal;
 	if (qualityGate !== undefined) entry.qualityGate = qualityGate;
@@ -178,64 +168,41 @@ export async function checkpointUlwLoop(
 				requireAllValidationBatchesClosed(plan, goal.id);
 			} else if (aggregate) requireEssentialCriteriaPass(goal);
 			else requireAllCriteriaPass(goal);
-			const snapshot = await readCodexGoalSnapshotInput(args.codexGoalJson, repoRoot);
-			const reconciliation = reconcileCodexGoalSnapshot(snapshot, {
-				expectedObjective: expectedCodexObjective(plan, goal),
-				...(aggregate ? { acceptedObjectives: compatibleCodexObjectives(plan) } : {}),
-				allowedStatuses: aggregate ? (final ? ["complete"] : ["active"]) : ["complete"],
-				requireSnapshot: true,
-				requireComplete: !aggregate || final,
-			});
-			codexGoal = reconciliation.snapshot.raw;
-			if (!reconciliation.ok) {
-				const objective = snapshot?.objective;
-				const mismatchedTaskObjective =
-					snapshot?.available === true &&
-					objective !== undefined &&
-					normalizeObjective(objective) !== normalizeObjective(expectedCodexObjective(plan, goal));
-				const completedTaskScoped =
-					mismatchedTaskObjective &&
-					snapshot.status === "complete" &&
-					(await canReconcileCompletedTaskScopedAggregateSnapshot(
-						repoRoot,
-						plan,
-						goal,
-						objective,
-						evidence,
-						scope,
-					));
-				const activeFinalTaskScoped =
-					mismatchedTaskObjective &&
-					snapshot.status === "active" &&
-					(await canReconcileActiveFinalTaskScopedAggregateSnapshot(
-						repoRoot,
-						plan,
-						goal,
-						objective,
-						evidence,
-						scope,
-					));
-				const taskScoped = completedTaskScoped || activeFinalTaskScoped;
-				if (!taskScoped)
-					throw new UlwLoopError(
-						`${formatCodexGoalReconciliation(reconciliation)}${aggregate && snapshot?.status === "complete" && objective !== undefined ? buildTaskScopedAggregateReconciliationHint(goal, final) : ""}`,
-						"ulw_loop_codex_snapshot_mismatch",
-					);
+			let codexValidationError: UlwLoopError | undefined;
+			try {
+				codexGoal = await validateCheckpointCodexGoal({
+					repoRoot,
+					plan,
+					goal,
+					raw: args.codexGoalJson,
+					evidence,
+					...(scope === undefined ? {} : { scope }),
+				});
+			} catch (error) {
+				if (!(error instanceof UlwLoopError)) throw error;
+				codexValidationError = error;
 			}
 			if (closesBatch) requireBatchFinalReady(plan, goal);
 			if (closesBatch && args.qualityGateJson === undefined)
 				throw new UlwLoopError("Validation batch final checkpoint requires --quality-gate-json.", "ULW_LOOP_VALIDATION_BATCH_GATE_REQUIRED");
 			if (final) aggregateCompletion = makeAggregateCompletion(now, evidence, codexGoal);
 			if (final || aggregateCompletion !== undefined || closesBatch) {
-				qualityGate = validateQualityGate(await readJsonInput(args.qualityGateJson, repoRoot), {
-					repoRoot,
-					fs: QUALITY_GATE_FS,
-					...(plan.evidenceLayoutVersion === 2
-						? { currentAttemptDir: ulwLoopAttemptEvidenceDir(goal.id, goal.attempt, scope) }
-						: {}),
-				});
-				requireBatchGate(plan, goal, qualityGate);
+				try {
+					qualityGate = validateQualityGate(await readJsonInput(args.qualityGateJson, repoRoot), {
+						repoRoot,
+						fs: QUALITY_GATE_FS,
+						reviewerSurface: resolveToolkitSurface(),
+						...(plan.evidenceLayoutVersion === 2
+							? { currentAttemptDir: ulwLoopAttemptEvidenceDir(goal.id, goal.attempt, scope) }
+							: {}),
+					});
+					requireBatchGate(plan, goal, qualityGate);
+				} catch (error) {
+					if (!(error instanceof UlwLoopError) || codexValidationError === undefined) throw error;
+					throw combineCheckpointValidationErrors(codexValidationError, error);
+				}
 			}
+			if (codexValidationError !== undefined) throw codexValidationError;
 			goal.status = "complete";
 			goal.completedAt = now;
 			goal.evidence = evidence;

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

@@ -1,6 +1,6 @@
 import { checkpoint } from "./checkpoint-continuation.js";
 import { hasFlag, readValue } from "./cli-arg-parser.js";
-import { printJsonError, ULW_LOOP_HELP } from "./cli-output.js";
+import { printJsonError, subcommandHelp, ULW_LOOP_HELP } from "./cli-output.js";
 import {
 	addGoal,
 	captureEvidence,
@@ -12,6 +12,7 @@ import {
 	steer,
 } from "./cli-subcommands.js";
 import { resolveUlwLoopSessionIdFromEnv, type UlwLoopScope } from "./paths.js";
+import { sessionIdRequiredMessage } from "./plan-missing-recovery.js";
 import { UlwLoopError } from "./types.js";
 
 export const ULW_LOOP_SUBCOMMANDS = [
@@ -53,6 +54,10 @@ export async function ulwLoopCommand(argv: readonly string[]): Promise<number> {
 			process.stdout.write(`${ULW_LOOP_HELP}\n`);
 			return 1;
 		}
+		if (command !== "help" && (hasFlag(rest, "--help") || hasFlag(rest, "-h"))) {
+			process.stdout.write(`${subcommandHelp(command)}\n`);
+			return 0;
+		}
 		switch (command) {
 			case "help":
 				process.stdout.write(`${ULW_LOOP_HELP}\n`);
@@ -104,7 +109,7 @@ function commandScope(argv: readonly string[]): UlwLoopScope | undefined {
 	if (sessionIdFlagPresent(argv)) {
 		const sessionId = readValue(argv, SESSION_ID_FLAG)?.trim();
 		if (!sessionId) {
-			throw new UlwLoopError(`${SESSION_ID_FLAG} requires a non-empty value.`, "ULW_LOOP_SESSION_ID_REQUIRED", {
+			throw new UlwLoopError(sessionIdRequiredMessage(SESSION_ID_FLAG), "ULW_LOOP_SESSION_ID_REQUIRED", {
 				details: { flag: SESSION_ID_FLAG },
 			});
 		}

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

@@ -2,17 +2,30 @@ import type { UlwLoopCodexGoalMode, UlwLoopItem, UlwLoopPlan } from "./types.js"
 import { UlwLoopError } from "./types.js";
 
 export const ULW_LOOP_HELP = `Usage:
+  omo-agent-toolkit hook user-prompt-submit [--with-ultrawork]  (Codex UserPromptSubmit hook)
+  omo-agent-toolkit help | --help | -h                          (this message)
+  omo-agent-toolkit ulw-loop help
   omo-agent-toolkit ulw-loop create-goals --brief "..." [--brief-file <path>] [--from-stdin] [--codex-goal-mode aggregate|per_story] [--validation-batch-json <json-or-path>] [--force] [--json]
   omo-agent-toolkit ulw-loop status [--json]
   omo-agent-toolkit ulw-loop complete-goals [--retry-failed] [--json]
   omo-agent-toolkit ulw-loop criteria --goal-id <id> [--json]
   omo-agent-toolkit ulw-loop record-evidence --goal-id <id> --criterion-id <id> --status pass|fail|blocked --evidence "..." [--notes "..."] [--json]
+  omo-agent-toolkit ulw-loop checkpoint --print-template [--goal-id <id>] [--json]
   omo-agent-toolkit ulw-loop checkpoint --goal-id <id> --status complete|failed|blocked --evidence "..." --codex-goal-json <...> [--quality-gate-json <...>] [--no-advance] [--json]
   omo-agent-toolkit ulw-loop steer --kind <kind> ... --evidence "..." --rationale "..." [--proposals-json <json-or-path>] [--json]
   omo-agent-toolkit ulw-loop add-goal --title "..." --objective "..." [--json]
   omo-agent-toolkit ulw-loop record-review-blockers --goal-id <id> --title "..." --objective "..." --evidence "..." --codex-goal-json <...> [--json]
 
-All subcommands accept [--session-id <id>] to isolate state under .omo/ulw-loop/<id>/; without it, Codex session env is used when present.`;
+All subcommands accept [--session-id <id>] to isolate state under .omo/ulw-loop/<id>/; without it, Codex session env is used when present.
+Every subcommand accepts --help | -h to print its own usage line.`;
+
+export function subcommandHelp(subcommand: string): string {
+	const lines = ULW_LOOP_HELP.split("\n").filter((line) =>
+		line.trimStart().startsWith(`omo-agent-toolkit ulw-loop ${subcommand}`),
+	);
+	if (lines.length === 0) return ULW_LOOP_HELP;
+	return ["Usage:", ...lines].join("\n");
+}
 
 type CriteriaCounts = { readonly pass: number; readonly total: number };
 

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

@@ -17,6 +17,7 @@ import { type UlwLoopScope, ulwLoopAttemptEvidenceDir } from "./paths.js";
 import { addUlwLoopGoal, createUlwLoopPlan, startNextUlwLoop, summarizeUlwLoopPlan } from "./plan-crud.js";
 import { readUlwLoopPlan } from "./plan-io.js";
 import { recordFinalReviewBlockers } from "./review-blockers.js";
+import { statusNextActions } from "./status-next-actions.js";
 import { steerUlwLoop } from "./steering.js";
 import { steerUlwLoopBatch } from "./steering-batch.js";
 import type { UlwLoopItem } from "./types.js";
@@ -73,6 +74,7 @@ export async function status(repoRoot: string, json: boolean, scope?: UlwLoopSco
 			plan,
 			summary: summarizeUlwLoopPlan(plan),
 			...(currentAttemptDir === undefined ? {} : { currentAttemptDir }),
+			nextActions: statusNextActions(plan),
 		});
 	} else printStatus(plan);
 	return 0;

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

@@ -1,17 +1,15 @@
 #!/usr/bin/env node
 import { isUlwLoopSubcommand, ulwLoopCommand } from "./cli-commands.js";
+import { ULW_LOOP_HELP } from "./cli-output.js";
 import { runPreToolUseGoalBudgetGuardCli, runUlwLoopHookCli } from "./codex-hook.js";
 import { runSpawnGuardCli } from "./spawn-guard.js";
 import { runStopResumeHookCli } from "./stop-resume-hook.js";
 
-const TOP_LEVEL_HELP =
-	"Usage:\n  omo-agent-toolkit ulw-loop <subcommand> [args]\n  omo-agent-toolkit hook user-prompt-submit [--with-ultrawork]  (Codex UserPromptSubmit hook)\n  omo-agent-toolkit help | --help | -h                          (this message)\n\nRun `omo-agent-toolkit ulw-loop help` for ulw-loop subcommands.\n";
-
 async function main(): Promise<number> {
 	const argv = process.argv.slice(2);
 	const command = argv[0];
 	if (command === undefined || command === "help" || command === "--help" || command === "-h") {
-		process.stdout.write(TOP_LEVEL_HELP);
+		process.stdout.write(`${ULW_LOOP_HELP}\n`);
 		return 0;
 	}
 	if (command === "ulw-loop") return ulwLoopCommand(argv.slice(1));
@@ -39,7 +37,7 @@ async function main(): Promise<number> {
 		return 1;
 	}
 	if (isUlwLoopSubcommand(command)) return ulwLoopCommand(argv);
-	process.stderr.write(`[omo] unknown command: ${command}\n${TOP_LEVEL_HELP}`);
+	process.stderr.write(`[omo] unknown command: ${command}\n${ULW_LOOP_HELP}\n`);
 	return 1;
 }
 

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

@@ -5,6 +5,7 @@ import {
 	isEssentialCriterion,
 	isFinalRunCompletionCandidate,
 } from "./goal-status.js";
+import { resolveToolkitSurface, reviewerRolesFor, type UlwLoopToolkitSurface } from "./surface.js";
 import type { UlwLoopCodexGoalMode, UlwLoopItem, UlwLoopPlan, UlwLoopSuccessCriterion } from "./types.js";
 
 export interface CodexCreateGoalPayload {
@@ -20,11 +21,13 @@ export function buildCodexGoalInstruction(args: {
 	readonly plan: UlwLoopPlan;
 	readonly goal: UlwLoopItem;
 	readonly isFinal?: boolean;
+	readonly surface?: UlwLoopToolkitSurface;
 }): UlwLoopGoalInstruction {
 	const mode = codexGoalMode(args.plan);
 	const createGoal = buildCreateGoalPayload(args.plan, args.goal);
 	const isFinal = args.isFinal ?? isFinalRunCompletionCandidate(args.plan, args.goal);
-	return { text: buildText(mode, args.plan, args.goal, createGoal, isFinal), json: createGoal };
+	const surface = args.surface ?? resolveToolkitSurface();
+	return { text: buildText(mode, args.plan, args.goal, createGoal, isFinal, surface), json: createGoal };
 }
 
 function buildCreateGoalPayload(plan: UlwLoopPlan, goal: UlwLoopItem): CodexCreateGoalPayload {
@@ -37,6 +40,7 @@ function buildText(
 	goal: UlwLoopItem,
 	createGoal: CodexCreateGoalPayload,
 	isFinal: boolean,
+	surface: UlwLoopToolkitSurface,
 ): string {
 	return joinLines([
 		mode === "aggregate" ? "UlwLoop aggregate-goal handoff" : "UlwLoop active-goal handoff",
@@ -54,7 +58,7 @@ function buildText(
 		"- Goals are unlimited. Do not add numeric limits.",
 		...modeConstraintLines(mode, isFinal),
 		...evidenceLayoutLines(plan),
-		finalSection(plan, goal, isFinal, mode === "aggregate"),
+		finalSection(plan, goal, isFinal, mode === "aggregate", surface),
 		...checkpointLines(plan, mode),
 		"",
 		"create_goal payload:",
@@ -112,18 +116,26 @@ function evidenceLayoutLines(plan: UlwLoopPlan): string[] {
 	];
 }
 
-function finalSection(plan: UlwLoopPlan, goal: UlwLoopItem, isFinal: boolean, aggregate: boolean): string {
+function finalSection(
+	plan: UlwLoopPlan,
+	goal: UlwLoopItem,
+	isFinal: boolean,
+	aggregate: boolean,
+	surface: UlwLoopToolkitSurface,
+): string {
+	const roles = reviewerRolesFor(surface);
 	if (!isFinal)
 		return "- This is not the final ulw-loop story; do not run the final reviewer/manual-QA/gate-review quality gate yet.";
 	const option = sessionOption(plan);
+	if (surface === "omo-senpi") return senpiFinalSection(plan, goal, aggregate);
 	const blockerCommand = `omo-agent-toolkit ulw-loop record-review-blockers${option} --goal-id ${goal.id} --title "Resolve final code-review blockers" --objective "<blocker-resolution objective>" --evidence "<review findings>" --codex-goal-json "<active get_goal JSON or path>"`;
 	const checkpointCommand = `omo-agent-toolkit ulw-loop checkpoint${option} --goal-id ${goal.id} --status complete --evidence "<targeted verification/manualQa/gateReview evidence>" --codex-goal-json "<fresh complete get_goal JSON or path>" --quality-gate-json "<quality gate JSON or path>"`;
 	return joinLines([
 		"Final story — run mandatory quality gate before update_goal:",
 		"- Run targeted verification for changed behavior.",
 		"- Confirm every manualQa artifact path exists and has non-zero size.",
-		"- First spawn lazycodex-code-reviewer and lazycodex-qa-executor in parallel (fork_context: false on the v1 surface; fork_turns: \"none\" on v2). Include the original brief, goal objectives, desired user-visible outcome, diff, and evidence; wait for BOTH to return and confirm their report artifacts exist on disk (code-review report + manualQa matrix).",
-		"- Only then spawn lazycodex-gate-reviewer (same fork settings), passing those artifact paths.",
+		`- First spawn ${roles.codeReview} and ${roles.manualQa} in parallel (fork_context: false on the v1 surface; fork_turns: "none" on v2). Include the original brief, goal objectives, desired user-visible outcome, diff, and evidence; wait for BOTH to return and confirm their report artifacts exist on disk (code-review report + manualQa matrix).`,
+		`- Only then spawn ${roles.gateReview} (same fork settings), passing those artifact paths.`,
 		"- Require clean codeReview, manualQa, gateReview, iteration, and criteriaCoverage. criteriaCoverage must summarize originalIntent, desiredOutcome, and userOutcomeReview; counts alone are not approval.",
 		"- On a reviewer REJECT, fix only the cited blockers, rerun the affected verification/Manual-QA, and re-review the delta at most TWICE; if blockers remain, record them and surface to the user.",
 		"- If codeQualityStatus is WATCH, include the WATCH notes verbatim in your final user-facing message.",
@@ -136,6 +148,23 @@ function finalSection(plan: UlwLoopPlan, goal: UlwLoopItem, isFinal: boolean, ag
 	]);
 }
 
+function senpiFinalSection(plan: UlwLoopPlan, goal: UlwLoopItem, aggregate: boolean): string {
+	const option = sessionOption(plan);
+	const checkpointCommand = `omo-agent-toolkit ulw-loop checkpoint${option} --goal-id ${goal.id} --status complete --evidence "<manualQa/gateReview evidence>" --codex-goal-json "<fresh complete get_goal JSON or path>" --quality-gate-json "$(omo-agent-toolkit ulw-loop checkpoint${option} --print-template)"`;
+	return joinLines([
+		"Final story — run the single-reviewer quality gate before update_goal:",
+		"- Run manual QA yourself and write the non-empty artifact under currentAttemptDir; set manualQa.by to \"main-session\".",
+		'- Spawn exactly one gate reviewer with task(category: "deep").',
+		"- If that task fails with any model_unavailable failure, retry with category:unspecified-high, then category:unspecified-low.",
+		'- Set gateReview.by to the exact category:<name> literal used for the successful task.',
+		'- Build the gate JSON with omo-agent-toolkit ulw-loop checkpoint --print-template, then fill manualQa, gateReview, iteration, and criteriaCoverage.',
+		'- Require passed manualQa, approved gateReview, passed iteration, and complete criteriaCoverage before update_goal({status: "complete"}).',
+		aggregate
+			? `- If the gate is clean, call update_goal({status: "complete"}), call get_goal again, then checkpoint the aggregate story: ${checkpointCommand}`
+			: `- If the gate is clean, call update_goal({status: "complete"}), call get_goal again, then checkpoint: ${checkpointCommand}`,
+	]);
+}
+
 function sessionOption(plan: UlwLoopPlan): string {
 	const prefix = ".omo/ulw-loop/";
 	const suffix = "/goals.json";

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

@@ -56,7 +56,9 @@ export function parseCodexGoalSnapshot(value: unknown): CodexGoalSnapshot {
 	}
 
 	const goal = safeObject(goalValue);
-	const objective = safeString(goal["objective"] ?? goal["goal"] ?? goal["description"] ?? root["objective"]);
+	const objective = safeString(
+		goal["objective"] ?? goal["goal"] ?? goal["description"] ?? goal["title"] ?? root["objective"] ?? root["title"],
+	);
 	const status = normalizeStatus(goal["status"] ?? root["status"]);
 
 	return {
@@ -137,3 +139,26 @@ export function formatCodexGoalReconciliation(reconciliation: CodexGoalReconcili
 	const parts = [...reconciliation.errors, ...reconciliation.warnings];
 	return parts.join(" ");
 }
+
+export interface CodexGoalMismatchRecovery {
+	readonly message: string;
+	readonly details: { readonly expectedObjective: string; readonly receivedObjective: string };
+}
+
+/**
+ * The reconciliation errors normalize whitespace for comparison, which makes the
+ * quoted objective unusable as a copy source. Recovery therefore carries the
+ * plan's `codexObjective` verbatim so the agent can paste it into `update_goal`.
+ */
+export function codexGoalMismatchRecovery(
+	expectedObjective: string,
+	snapshot: CodexGoalSnapshot | null | undefined,
+): CodexGoalMismatchRecovery {
+	const receivedObjective = snapshot?.objective ?? "";
+	const message = [
+		"Recovery: the Codex goal objective must equal the plan's codexObjective exactly — copy the expected value below into update_goal and re-run get_goal.",
+		`expected codexObjective: ${expectedObjective}`,
+		`received objective: ${receivedObjective || "(none)"}`,
+	].join("\n");
+	return { message, details: { expectedObjective, receivedObjective } };
+}

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

@@ -95,7 +95,9 @@ export async function applyUserPromptUlwLoopSteering(
 }
 
 function hasSteeringDirectiveMarker(prompt: string): boolean {
-	return /(?:^|\s)(?:OMO_ULW_LOOP_STEER|omo\.ulw-loop\.steer|omo ulw-loop steer|omo-agent-toolkit ulw-loop steer):/u.test(prompt);
+	return /(?:^|\s)(?:OMO_ULW_LOOP_STEER|omo\.ulw-loop\.steer|omo ulw-loop steer|omo-agent-toolkit ulw-loop steer):/u.test(
+		prompt,
+	);
 }
 
 function payloadScope(payload: UserPromptSubmitPayload): UlwLoopScope {

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

@@ -107,15 +107,7 @@ export interface UlwLoopManualQaAdversarialCase {
 	readonly artifactRefs: readonly string[];
 }
 
-export interface UlwLoopQualityGate {
-	readonly codeReview: {
-		readonly by: string;
-		readonly recommendation: "APPROVE";
-		readonly codeQualityStatus: "CLEAR" | "WATCH";
-		readonly reportPath: string;
-		readonly evidence: string;
-		readonly blockers: readonly [];
-	};
+interface UlwLoopQualityGateCommon {
 	readonly manualQa: {
 		readonly by: string;
 		readonly status: "passed";
@@ -147,6 +139,24 @@ export interface UlwLoopQualityGate {
 	};
 }
 
+export interface UlwLoopQualityGateLazycodex extends UlwLoopQualityGateCommon {
+	readonly surface: "lazycodex";
+	readonly codeReview: {
+		readonly by: string;
+		readonly recommendation: "APPROVE";
+		readonly codeQualityStatus: "CLEAR" | "WATCH";
+		readonly reportPath: string;
+		readonly evidence: string;
+		readonly blockers: readonly [];
+	};
+}
+
+export interface UlwLoopQualityGateSenpi extends UlwLoopQualityGateCommon {
+	readonly surface: "omo-senpi";
+}
+
+export type UlwLoopQualityGate = UlwLoopQualityGateLazycodex | UlwLoopQualityGateSenpi;
+
 export interface UlwLoopLedgerEntry {
 	at: string;
 	kind: UlwLoopLedgerEventKind;

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

@@ -5,7 +5,7 @@ export interface UlwLoopScope {
 	readonly sessionId?: string | null;
 }
 
-const SESSION_ENV_KEYS = ["OMO_ULW_LOOP_SESSION_ID", "CODEX_SESSION_ID", "CODEX_THREAD_ID"] as const;
+const SESSION_ENV_KEYS = ["OMO_ULW_LOOP_SESSION_ID", "CODEX_SESSION_ID", "CODEX_THREAD_ID", "PI_SESSION_ID"] as const;
 type EnvMap = Readonly<Record<string, string | undefined>>;
 
 export function normalizeUlwLoopSessionId(sessionId: string | null | undefined): string | null {

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

@@ -1,4 +1,4 @@
-import { createReadStream } from "node:fs";
+import { createReadStream, readdirSync } from "node:fs";
 import { appendFile, mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { createInterface } from "node:readline";
 
@@ -11,6 +11,7 @@ import {
 	ulwLoopLedgerPath,
 	ulwLoopRelativeDir,
 } from "./paths.js";
+import { planMissingRecovery } from "./plan-missing-recovery.js";
 import type { UlwLoopLedgerEntry, UlwLoopPlan } from "./types.js";
 import { iso, ULW_LOOP_DIR, ULW_LOOP_GOALS, ULW_LOOP_LEDGER, UlwLoopError } from "./types.js";
 
@@ -73,10 +74,11 @@ export async function readUlwLoopPlan(repoRoot: string, scope?: UlwLoopScope): P
 		raw = await readFile(path, "utf8");
 	} catch (error) {
 		if (!hasCode(error, "ENOENT")) throw error;
+		const recovery = planMissingRecovery(readSessionDirs(repoRoot));
 		throw new UlwLoopError(
-			`No ulw-loop plan found at ${repoRelative(path, repoRoot)}. Run \`omo-agent-toolkit ulw-loop create-goals ...\` first.`,
+			`No ulw-loop plan found at ${repoRelative(path, repoRoot)}.\n${recovery.message}`,
 			"ULW_LOOP_PLAN_MISSING",
-			{ cause: error },
+			{ cause: error, ...(recovery.details === undefined ? {} : { details: recovery.details }) },
 		);
 	}
 	const parsed: UlwLoopPlan = JSON.parse(raw);
@@ -108,6 +110,19 @@ export async function readUlwLoopPlan(repoRoot: string, scope?: UlwLoopScope): P
 	return parsed;
 }
 
+// Session dirs are the only recovery hint that matters when a plan is missing: the
+// caller is almost always scoped to a session whose sibling actually holds the plan.
+function readSessionDirs(repoRoot: string): readonly string[] {
+	try {
+		return readdirSync(ulwLoopDir(repoRoot), { withFileTypes: true })
+			.filter((entry) => entry.isDirectory())
+			.map((entry) => entry.name)
+			.sort();
+	} catch {
+		return [];
+	}
+}
+
 export async function writePlan(repoRoot: string, plan: UlwLoopPlan, scope?: UlwLoopScope): Promise<void> {
 	await mkdir(ulwLoopDir(repoRoot, scope), { recursive: true });
 	const path = ulwLoopGoalsPath(repoRoot, scope);

package/packages/omo-codex/plugin/components/ulw-loop/src/plan-missing-recovery.ts

@@ -0,0 +1,27 @@
+export const ULW_LOOP_CREATE_GOALS_COMMAND = 'omo-agent-toolkit ulw-loop create-goals --brief "<brief>" --json';
+
+export interface PlanMissingRecovery {
+	readonly message: string;
+	readonly details?: { readonly existingSessionIds: readonly string[] };
+}
+
+/**
+ * A missing plan is either "never bootstrapped" or "bootstrapped under a different
+ * session id"; the recovery text has to answer both without the caller guessing.
+ */
+export function planMissingRecovery(existingSessionIds: readonly string[]): PlanMissingRecovery {
+	const lines = [`Recovery: bootstrap the plan with \`${ULW_LOOP_CREATE_GOALS_COMMAND}\`.`];
+	if (existingSessionIds.length === 0) return { message: lines.join("\n") };
+	lines.push(
+		`Existing ulw-loop session ids under .omo/ulw-loop/: ${existingSessionIds.join(", ")}. Re-run with \`--session-id <id>\` to target one of them.`,
+	);
+	return { message: lines.join("\n"), details: { existingSessionIds } };
+}
+
+export function sessionIdRequiredMessage(flag: string): string {
+	return [
+		`${flag} requires a non-empty value.`,
+		"Recovery: subprocess, eval, and hook contexts do not inherit the ulw-loop session env (OMO_ULW_LOOP_SESSION_ID / CODEX_SESSION_ID / CODEX_THREAD_ID / PI_SESSION_ID),",
+		`so pass the scope explicitly: \`${flag} <id>\` (for example \`${flag} 01a05b8a-6763-7780-834f-319423b071ce\`).`,
+	].join("\n");
+}

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

@@ -0,0 +1,11 @@
+import type { ValidateQualityGateOptions } from "./quality-gate.js";
+import { validateQualityGate } from "./quality-gate.js";
+
+/**
+ * Compatibility entry point for callers that used the former pre-pass API.
+ * Validation is performed by the real parser, which collects defects across
+ * every nested field before throwing one aggregate error.
+ */
+export function aggregateQualityGateDefects(input: unknown, opts: ValidateQualityGateOptions | undefined): void {
+	validateQualityGate(input, opts);
+}