oh-my-opencode 5.0.0-beta.5 → 5.0.0-beta.50

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

@@ -0,0 +1,128 @@
+import { type UlwLoopScope, ulwLoopAttemptEvidenceDir } from "./paths.js";
+import { readUlwLoopPlan } from "./plan-io.js";
+import { resolveToolkitSurface, type UlwLoopToolkitSurface } from "./surface.js";
+import type { UlwLoopPlan } from "./types.js";
+import { UlwLoopError } from "./types.js";
+
+export interface CheckpointTemplate {
+	readonly qualityGateTemplate: Record<string, unknown>;
+	readonly codexGoalTemplate: Record<string, unknown>;
+	readonly attemptDir?: string;
+	readonly guidance?: string;
+}
+
+function artifactPath(base: string, name: string): string {
+	return `${base}/${name}`;
+}
+
+function gateTemplate(surface: UlwLoopToolkitSurface, base: string): Record<string, unknown> {
+	const artifacts = [
+		{
+			id: "artifact-cli",
+			kind: "cli-transcript",
+			description: "<replace:artifact description>",
+			path: artifactPath(base, "cli-transcript.txt"),
+		},
+		{
+			id: "artifact-data",
+			kind: "data-diff",
+			description: "<replace:artifact description>",
+			path: artifactPath(base, "data-diff.txt"),
+		},
+	];
+	const manualQa = {
+		by: "main-session",
+		status: "passed",
+		evidence: "<replace:manual QA evidence>",
+		surfaceEvidence: [
+			{
+				id: "surface-cli",
+				criterionRef: "<replace:criterion id>",
+				surface: "cli",
+				invocation: "<replace:command>",
+				verdict: "passed",
+				artifactRefs: ["artifact-cli"],
+			},
+			{
+				id: "surface-data",
+				criterionRef: "<replace:criterion id>",
+				surface: "data",
+				invocation: "<replace:command>",
+				verdict: "passed",
+				artifactRefs: ["artifact-data"],
+			},
+		],
+		adversarialCases: [
+			{
+				id: "<replace:adversarial case id>",
+				criterionRef: "<replace:criterion id>",
+				scenario: "<replace:scenario>",
+				expectedBehavior: "<replace:expected behavior>",
+				verdict: "not_applicable",
+				reason: "<replace:reason>",
+				artifactRefs: ["artifact-cli"],
+			},
+		],
+		artifactRefs: artifacts,
+	};
+	const common = {
+		manualQa,
+		gateReview: {
+			by: surface === "omo-senpi" ? "category:deep" : "main-session",
+			recommendation: "APPROVE",
+			reportPath: artifactPath(base, "gate-review.md"),
+			evidence: "<replace:gate review evidence>",
+			blockers: [],
+			notes: [],
+		},
+		iteration: {
+			fullRerun: true,
+			status: "passed",
+			rerunCommands: ["<replace:verification command>"],
+			evidence: "<replace:iteration evidence>",
+		},
+		criteriaCoverage: {
+			totalCriteria: 0,
+			passCount: 0,
+			originalIntent: "<replace:original intent>",
+			desiredOutcome: "<replace:desired outcome>",
+			userOutcomeReview: "<replace:user outcome review>",
+			adversarialClassesCovered: ["<replace:adversarial class>"],
+		},
+	};
+	return common;
+}
+
+export async function checkpointTemplate(
+	repoRoot: string,
+	scope?: UlwLoopScope,
+	goalId?: string,
+): Promise<CheckpointTemplate> {
+	const plan: UlwLoopPlan = await readUlwLoopPlan(repoRoot, scope);
+	const targetId = goalId ?? plan.activeGoalId;
+	const active = plan.goals.find((goal) => goal.id === targetId);
+	if (goalId !== undefined && active === undefined)
+		throw new UlwLoopError(`Unknown ulw-loop id: ${goalId}.`, "ULW_LOOP_GOAL_NOT_FOUND", { details: { goalId } });
+	const hasAttempt = plan.evidenceLayoutVersion === 2 && active !== undefined;
+	const attemptDir = hasAttempt ? ulwLoopAttemptEvidenceDir(active.id, active.attempt, scope) : ".omo/evidence";
+	const guidance = [
+		"codex-goal-json requires goal.objective to equal the plan's codexObjective verbatim; do not paraphrase it.",
+		"Fill every <replace:...> value with plausible non-empty evidence and use real, non-empty artifact files.",
+		'Passing codex-goal-json example: {"goal":{"objective":"<plan codexObjective verbatim>","status":"complete"}}.',
+		'Passing quality-gate-json example requires gateReview {"by":"category:deep","recommendation":"APPROVE","evidence":"review passed","reportPath":"<attemptDir>/gate-review.md","blockers":[],"notes":[]}, manualQa.artifactRefs objects, iteration, and criteriaCoverage.',
+		...(resolveToolkitSurface() === "lazycodex"
+			? [
+					"Self-review defaults: manualQa.by and gateReview.by are main-session. Alternatives: manualQa.by accepts lazycodex-qa-executor; gateReview.by accepts lazycodex-gate-reviewer, category:deep, category:unspecified-high, or category:unspecified-low. Optional codeReview.by accepts lazycodex-code-reviewer or main-session.",
+				]
+			: []),
+		...(hasAttempt ? [] : ["This plan is evidence-layout v1; artifacts go under .omo/evidence/."]),
+	].join(" ");
+	return {
+		qualityGateTemplate: gateTemplate(resolveToolkitSurface(), attemptDir),
+		codexGoalTemplate: {
+			goal: { objective: plan.codexObjective ?? "<replace:codex objective>", status: "complete" },
+		},
+		guidance,
+		...(hasAttempt ? { attemptDir } : {}),
+	};
+}

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,8 @@ import {
 	steer,
 } from "./cli-subcommands.js";
 import { resolveUlwLoopSessionIdFromEnv, type UlwLoopScope } from "./paths.js";
+import { listUlwLoopSessionIds } from "./plan-io.js";
+import { sessionIdRequiredMessage, sessionScopeRequiredMessage } from "./plan-missing-recovery.js";
 import { UlwLoopError } from "./types.js";
 
 export const ULW_LOOP_SUBCOMMANDS = [
@@ -40,7 +42,6 @@ export async function ulwLoopCommand(argv: readonly string[]): Promise<number> {
 	const repoRoot = process.cwd();
 	const json = hasFlag(rest, "--json");
 	try {
-		const scope = commandScope(rest);
 		if (!isUlwLoopSubcommand(command)) {
 			if (json) {
 				printJsonError(
@@ -53,10 +54,16 @@ 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;
+		}
+		if (command === "help") {
+			process.stdout.write(`${ULW_LOOP_HELP}\n`);
+			return 0;
+		}
+		const scope = commandScope(repoRoot, rest);
 		switch (command) {
-			case "help":
-				process.stdout.write(`${ULW_LOOP_HELP}\n`);
-				return 0;
 			case "create-goals":
 				return await createGoals(repoRoot, rest, json, scope);
 			case "status":
@@ -100,16 +107,25 @@ function sessionIdFlagPresent(argv: readonly string[]): boolean {
 	return hasFlag(argv, SESSION_ID_FLAG) || argv.some((arg) => arg.startsWith(`${SESSION_ID_FLAG}=`));
 }
 
-function commandScope(argv: readonly string[]): UlwLoopScope | undefined {
+// Every state subcommand runs against exactly one session directory. Without a flag or
+// a session env there is no owner to resolve, so the command refuses instead of
+// falling back to the repo-global root that every session in the cwd would share.
+function commandScope(repoRoot: string, argv: readonly string[]): UlwLoopScope {
 	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 },
 			});
 		}
 		return { sessionId };
 	}
 	const sessionId = resolveUlwLoopSessionIdFromEnv();
-	return sessionId === null ? undefined : { sessionId };
+	if (sessionId !== null) return { sessionId };
+	const existingSessionIds = listUlwLoopSessionIds(repoRoot);
+	throw new UlwLoopError(
+		sessionScopeRequiredMessage(SESSION_ID_FLAG, existingSessionIds),
+		"ULW_LOOP_SESSION_SCOPE_REQUIRED",
+		{ details: { flag: SESSION_ID_FLAG, existingSessionIds } },
+	);
 }

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.`;
+Every state subcommand needs a session scope: [--session-id <id>] or the session env (OMO_ULW_LOOP_SESSION_ID / CODEX_SESSION_ID / CODEX_THREAD_ID / PI_SESSION_ID); state lives under .omo/ulw-loop/<id>/ and the unscoped root is never used implicitly. status --json exposes the currentAttemptDir; put all quality-gate artifacts under it.
+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 { runSpawnAdmissionRecorderCli, 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));
@@ -31,6 +29,10 @@ async function main(): Promise<number> {
 			await runStopResumeHookCli(process.stdin, process.stdout);
 			return 0;
 		}
+		if (sub === "post-tool-use-spawn") {
+			await runSpawnAdmissionRecorderCli(process.stdin, process.stdout);
+			return 0;
+		}
 		if (sub === "pre-tool-use-spawn") {
 			await runSpawnGuardCli(process.stdin, process.stdout);
 			return 0;
@@ -39,7 +41,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,19 +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:",
+		"Final story — self-review and manual QA are the default; use the 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.",
-		"- Require clean codeReview, manualQa, gateReview, iteration, and criteriaCoverage. criteriaCoverage must summarize originalIntent, desiredOutcome, and userOutcomeReview; counts alone are not approval.",
+		`- Run manual QA yourself and write its artifact under currentAttemptDir. Only if the user explicitly demands strict, rigorous, or high-accuracy review, spawn ${roles.gateReview}, optionally also ${roles.codeReview} and ${roles.manualQa}; otherwise set manualQa.by and gateReview.by to "main-session".`,
+		"- Require passed manualQa, approved gateReview, passed iteration, and complete criteriaCoverage; include codeReview only when strict review was requested. 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.",
 		"- If any reviewer is blocked/inconclusive or the quality gate is not clean, do not call update_goal. Record blocker work first:",
@@ -136,6 +147,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/constants.ts

@@ -2,6 +2,7 @@ export const ULW_LOOP_DIR = ".omo/ulw-loop";
 export const ULW_LOOP_BRIEF = "brief.md";
 export const ULW_LOOP_GOALS = "goals.json";
 export const ULW_LOOP_LEDGER = "ledger.jsonl";
+export const ULW_LOOP_STATE_LOCK = ".state.lock";
 
 export type UlwLoopStatus =
 	| "pending"

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;