lazycodex-ai 5.0.0-beta.53 → 5.0.0-beta.55

package/packages/omo-codex/plugin/components/ulw-loop/dist/codex-goal-snapshot.js

@@ -7,16 +7,25 @@ function safeObject(value) {
     return value && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
 function safeString(value) {
+    return typeof value === "string" ? value : "";
+}
+function safeStatusString(value) {
     return typeof value === "string" ? value.trim() : "";
 }
 function normalizeStatus(value) {
-    const status = safeString(value).toLowerCase();
+    const status = safeStatusString(value).toLowerCase();
     if (status === "complete" || status === "completed" || status === "done")
         return "complete";
     if (status === "cancelled" || status === "canceled")
         return "cancelled";
     if (status === "failed" || status === "failure")
         return "failed";
+    if (status === "paused")
+        return "paused";
+    if (status === "usage_limited")
+        return "usage_limited";
+    if (status === "budget_limited")
+        return "budget_limited";
     if (status === "active" || status === "in_progress" || status === "pending" || status === "running")
         return "active";
     return "unknown";
@@ -64,48 +73,29 @@ export function reconcileCodexGoalSnapshot(snapshot, options) {
     const effectiveSnapshot = snapshot ?? { available: false, raw: null };
     const errors = [];
     const warnings = [];
+    const expected = options.expectedObjective;
+    const normalizedExpected = normalizeObjective(expected);
     if (!effectiveSnapshot.available) {
-        const message = "Codex goal snapshot is absent or reports no active goal; call get_goal and pass its JSON with --codex-goal-json.";
-        if (options.requireSnapshot)
-            errors.push(message);
-        else
-            warnings.push(message);
+        warnings.push(`call get_goal; if none, create_goal with codexObjective "${expected}" verbatim`);
         return { ok: errors.length === 0, snapshot: effectiveSnapshot, warnings, errors };
     }
-    const expected = normalizeObjective(options.expectedObjective);
-    const accepted = new Set([expected, ...(options.acceptedObjectives ?? []).map((objective) => normalizeObjective(objective))].filter(Boolean));
+    const accepted = new Set([
+        normalizedExpected,
+        ...(options.acceptedObjectives ?? []).map((objective) => normalizeObjective(objective)),
+    ].filter(Boolean));
     const actual = normalizeObjective(effectiveSnapshot.objective ?? "");
-    if (!actual) {
-        errors.push("Codex goal snapshot is missing objective text.");
-    }
-    else if (!accepted.has(actual)) {
-        errors.push(`Codex goal objective mismatch: expected "${expected}", got "${actual}".`);
+    if (actual && !accepted.has(normalizeObjective(actual))) {
+        warnings.push(`driver_objective_differs: expected "${expected}", got "${actual}".`);
     }
-    const allowed = options.allowedStatuses ?? (options.requireComplete ? ["complete"] : ["active", "complete"]);
     const actualStatus = effectiveSnapshot.status ?? "unknown";
-    if (!allowed.includes(actualStatus)) {
-        errors.push(`Codex goal status mismatch: expected ${allowed.join(" or ")}, got ${actualStatus}.`);
-    }
-    if (options.requireComplete && actualStatus !== "complete") {
-        errors.push('Codex goal is not complete; call update_goal({status: "complete"}) only after the objective is actually complete, then pass the fresh get_goal JSON.');
+    if (actualStatus === "paused" || actualStatus === "usage_limited" || actualStatus === "budget_limited") {
+        warnings.push("/goal resume or raise the budget");
     }
+    if (actualStatus === "complete")
+        warnings.push(`driver closed early: call create_goal with codexObjective "${expected}" verbatim`);
     return { ok: errors.length === 0, snapshot: effectiveSnapshot, warnings, errors };
 }
 export function formatCodexGoalReconciliation(reconciliation) {
     const parts = [...reconciliation.errors, ...reconciliation.warnings];
     return parts.join(" ");
 }
-/**
- * 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, snapshot) {
-    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/dist/review-blockers.d.ts

@@ -12,5 +12,7 @@ export interface RecordFinalReviewBlockersResult {
     readonly blockedGoal: UlwLoopItem;
     readonly newGoal: UlwLoopItem;
     readonly ledgerEntries: UlwLoopLedgerEntry[];
+    readonly nextActions: readonly string[];
+    readonly warnings: readonly string[];
 }
 export declare function recordFinalReviewBlockers(repoRoot: string, args: RecordFinalReviewBlockersArgs, scope?: UlwLoopScope): Promise<RecordFinalReviewBlockersResult>;

package/packages/omo-codex/plugin/components/ulw-loop/dist/review-blockers.js

@@ -1,7 +1,6 @@
 // biome-ignore-all format: compact port must stay within the requested pure LOC budget.
-import { codexSnapshotMismatchError } from "./checkpoint-reconciliation.js";
-import { readCodexGoalSnapshotInput, reconcileCodexGoalSnapshot } from "./codex-goal-snapshot.js";
-import { codexGoalMode, compatibleCodexObjectives, expectedCodexObjective, isFinalRunCompletionCandidate } from "./goal-status.js";
+import { CodexGoalSnapshotError, formatCodexGoalReconciliation, readCodexGoalSnapshotInput, reconcileCodexGoalSnapshot, } from "./codex-goal-snapshot.js";
+import { compatibleCodexObjectives, expectedCodexObjective, isFinalRunCompletionCandidate } from "./goal-status.js";
 import { seedDefaultSuccessCriteria } from "./plan-crud.js";
 import { appendLedger, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
 import { iso, UlwLoopError } from "./types.js";
@@ -42,11 +41,12 @@ export async function recordFinalReviewBlockers(repoRoot, args, scope) {
         if (!isFinalRunCompletionCandidate(plan, goal))
             ulwLoopError(`${goal.id} is not final.`, "ulw_loop_not_final_story");
         const snapshot = await readCodexGoalSnapshotInput(args.codexGoalJson, repoRoot);
-        const aggregate = codexGoalMode(plan) === "aggregate";
-        const expected = expectedCodexObjective(plan, goal);
-        const reconciliation = reconcileCodexGoalSnapshot(snapshot, { expectedObjective: expected, ...(aggregate ? { acceptedObjectives: compatibleCodexObjectives(plan) } : {}), allowedStatuses: ["active"], requireSnapshot: true, requireComplete: false });
+        const reconciliation = reconcileCodexGoalSnapshot(snapshot, {
+            expectedObjective: expectedCodexObjective(plan, goal),
+            acceptedObjectives: compatibleCodexObjectives(plan),
+        });
         if (!reconciliation.ok)
-            throw codexSnapshotMismatchError({ reconciliation, snapshot, expectedObjective: expected });
+            throw new CodexGoalSnapshotError(formatCodexGoalReconciliation(reconciliation));
         const now = iso();
         for (const field of BLOCKER_FIELDS)
             Reflect.deleteProperty(goal, field);
@@ -58,7 +58,7 @@ export async function recordFinalReviewBlockers(repoRoot, args, scope) {
             delete plan.activeGoalId;
         const newGoal = appendBlockerGoal(plan, args, now);
         plan.updatedAt = now;
-        const codexGoal = reconciliation.snapshot.raw;
+        const codexGoal = snapshot?.raw;
         const blockedEntry = { at: now, kind: "goal_review_blocked", goalId: goal.id, status: goal.status, evidence: args.evidence, codexGoal };
         const addedEntry = { at: now, kind: "goal_added", goalId: newGoal.id, status: newGoal.status, evidence: args.evidence, message: newGoal.title };
         const summaryEntry = { at: now, kind: "goal_review_blocked", goalId: goal.id, status: goal.status, evidence: args.evidence, codexGoal, message: `Review blockers recorded; appended ${newGoal.id}.` };
@@ -67,6 +67,13 @@ export async function recordFinalReviewBlockers(repoRoot, args, scope) {
         await writePlan(repoRoot, plan, scope);
         for (const entry of ledgerEntries)
             await appendLedger(repoRoot, entry, scope);
-        return { plan, blockedGoal: goal, newGoal, ledgerEntries };
+        return {
+            plan,
+            blockedGoal: goal,
+            newGoal,
+            ledgerEntries,
+            nextActions: reconciliation.warnings,
+            warnings: reconciliation.warnings.filter((warning) => warning.startsWith("driver_objective_differs")),
+        };
     });
 }

package/packages/omo-codex/plugin/components/ulw-loop/hooks/hooks.json

@@ -7,7 +7,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook user-prompt-submit --with-ultrawork",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.0.0-beta.53) Checking Ulw-Loop Steering"
+						"statusMessage": "(OmO 5.0.0-beta.55) Checking Ulw-Loop Steering"
 					}
 				]
 			}
@@ -20,7 +20,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook post-tool-use-spawn",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.53) Recording Spawn Admission"
+						"statusMessage": "(OmO 5.0.0-beta.55) Recording Spawn Admission"
 					}
 				]
 			}
@@ -33,7 +33,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook pre-tool-use",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.53) Enforcing Unlimited Ulw-Loop Budget"
+						"statusMessage": "(OmO 5.0.0-beta.55) Enforcing Unlimited Ulw-Loop Budget"
 					}
 				]
 			},
@@ -44,7 +44,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook pre-tool-use-spawn",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.53) Guarding Ulw-Loop Spawns"
+						"statusMessage": "(OmO 5.0.0-beta.55) Guarding Ulw-Loop Spawns"
 					}
 				]
 			}
@@ -56,7 +56,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook stop",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.0.0-beta.53) Checking Ulw-Loop Resume"
+						"statusMessage": "(OmO 5.0.0-beta.55) Checking Ulw-Loop Resume"
 					}
 				]
 			}

package/packages/omo-codex/plugin/components/ulw-loop/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-ulw-loop",
-	"version": "5.0.0-beta.53",
+	"version": "5.0.0-beta.55",
 	"description": "Codex plugin: durable repo-native multi-goal orchestration with embedded success criteria and observable evidence audit.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",

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

@@ -1,23 +1,14 @@
 import {
-	canReconcileActiveFinalTaskScopedAggregateSnapshot,
-	canReconcileCompletedTaskScopedAggregateSnapshot,
-	codexSnapshotMismatchError,
-} from "./checkpoint-reconciliation.js";
-import { readCodexGoalSnapshotInput, reconcileCodexGoalSnapshot } from "./codex-goal-snapshot.js";
-import {
-	codexGoalMode,
-	compatibleCodexObjectives,
-	expectedCodexObjective,
-	isFinalRunCompletionCandidate,
-} from "./goal-status.js";
+	CodexGoalSnapshotError,
+	formatCodexGoalReconciliation,
+	readCodexGoalSnapshotInput,
+	reconcileCodexGoalSnapshot,
+} from "./codex-goal-snapshot.js";
+import { codexGoalMode, compatibleCodexObjectives, expectedCodexObjective } from "./goal-status.js";
 import type { UlwLoopScope } from "./paths.js";
 import type { UlwLoopItem, UlwLoopPlan } from "./types.js";
 import { UlwLoopError } from "./types.js";
 
-function normalizeObjective(value: string): string {
-	return value.replace(/\s+/g, " ").trim();
-}
-
 export async function validateCheckpointCodexGoal(input: {
 	readonly repoRoot: string;
 	readonly plan: UlwLoopPlan;
@@ -25,53 +16,21 @@ export async function validateCheckpointCodexGoal(input: {
 	readonly raw: string | undefined;
 	readonly evidence: string;
 	readonly scope?: UlwLoopScope;
-}): Promise<unknown> {
-	const aggregate = codexGoalMode(input.plan) === "aggregate";
-	const final = isFinalRunCompletionCandidate(input.plan, input.goal);
+}): Promise<{ readonly raw: unknown; readonly nextActions: readonly string[]; readonly warnings: readonly string[] }> {
 	const snapshot = await readCodexGoalSnapshotInput(input.raw, input.repoRoot);
-	const expectedObjective = expectedCodexObjective(input.plan, input.goal);
+	const expected = expectedCodexObjective(input.plan, input.goal);
 	const reconciliation = reconcileCodexGoalSnapshot(snapshot, {
-		expectedObjective,
-		...(aggregate ? { acceptedObjectives: compatibleCodexObjectives(input.plan) } : {}),
-		allowedStatuses: aggregate ? (final ? ["complete"] : ["active"]) : ["complete"],
-		requireSnapshot: true,
-		requireComplete: !aggregate || final,
-	});
-	if (reconciliation.ok) return reconciliation.snapshot.raw;
-	const objective = snapshot?.objective;
-	const mismatchedTaskObjective =
-		snapshot?.available === true &&
-		objective !== undefined &&
-		normalizeObjective(objective) !== normalizeObjective(expectedObjective);
-	const completedTaskScoped =
-		mismatchedTaskObjective &&
-		snapshot.status === "complete" &&
-		(await canReconcileCompletedTaskScopedAggregateSnapshot(
-			input.repoRoot,
-			input.plan,
-			input.goal,
-			objective,
-			input.evidence,
-			input.scope,
-		));
-	const activeFinalTaskScoped =
-		mismatchedTaskObjective &&
-		snapshot.status === "active" &&
-		(await canReconcileActiveFinalTaskScopedAggregateSnapshot(
-			input.repoRoot,
-			input.plan,
-			input.goal,
-			objective,
-			input.evidence,
-			input.scope,
-		));
-	if (completedTaskScoped || activeFinalTaskScoped) return reconciliation.snapshot.raw;
-	throw codexSnapshotMismatchError({
-		reconciliation,
-		snapshot,
-		expectedObjective,
-		taskScopedHint: { goal: input.goal, aggregate, final },
+		expectedObjective: expected,
+		...(codexGoalMode(input.plan) === "aggregate"
+			? { acceptedObjectives: compatibleCodexObjectives(input.plan) }
+			: {}),
 	});
+	if (!reconciliation.ok) throw new CodexGoalSnapshotError(formatCodexGoalReconciliation(reconciliation));
+	return {
+		raw: snapshot?.raw,
+		nextActions: reconciliation.warnings,
+		warnings: reconciliation.warnings.filter((warning) => warning.startsWith("driver_objective_differs")),
+	};
 }
 
 export function combineCheckpointValidationErrors(codexError: UlwLoopError, gateError: UlwLoopError): UlwLoopError {

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

@@ -42,12 +42,7 @@ export async function checkpoint(
 	const goalId = required(argv, "--goal-id");
 	const statusValue = checkpointStatus(required(argv, "--status"));
 	const evidence = required(argv, "--evidence");
-	const codexGoalJson = await parseCodexGoalJson(
-		statusValue === "complete" ? required(argv, "--codex-goal-json") : readValue(argv, "--codex-goal-json"),
-	);
-	if (statusValue === "complete" && codexGoalJson === undefined) {
-		throw new UlwLoopError("Missing --codex-goal-json.", "ULW_LOOP_CODEX_GOAL_JSON_REQUIRED");
-	}
+	const codexGoalJson = await parseCodexGoalJson(readValue(argv, "--codex-goal-json"));
 	const qualityGateJson = readValue(argv, "--quality-gate-json");
 	const args: CheckpointUlwLoopArgs & { readonly advance: boolean } = {
 		goalId,

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

@@ -1,130 +1,7 @@
-import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
-
-import type { CodexGoalReconciliation, CodexGoalSnapshot } from "./codex-goal-snapshot.js";
-import { codexGoalMismatchRecovery, formatCodexGoalReconciliation } from "./codex-goal-snapshot.js";
-import { codexGoalMode, isFinalRunCompletionCandidate } from "./goal-status.js";
-import { type UlwLoopScope, ulwLoopBriefPath } from "./paths.js";
-import type { UlwLoopItem, UlwLoopPlan } from "./types.js";
-import { ULW_LOOP_DIR, ULW_LOOP_GOALS, ULW_LOOP_LEDGER, UlwLoopError } from "./types.js";
-
-export interface CodexSnapshotMismatchInput {
-	readonly reconciliation: CodexGoalReconciliation;
-	readonly snapshot: CodexGoalSnapshot | null | undefined;
-	readonly expectedObjective: string;
-	/** Only the checkpoint path can fall back to task-scoped aggregate reconciliation, so only it asks for that hint. */
-	readonly taskScopedHint?: { readonly goal: UlwLoopItem; readonly aggregate: boolean; readonly final: boolean };
-}
+import { UlwLoopError } from "./types.js";
 
 export function combineCheckpointValidationErrors(codexError: UlwLoopError, gateError: UlwLoopError): UlwLoopError {
 	return new UlwLoopError(`${codexError.message}\n${gateError.message}`, "ULW_LOOP_QUALITY_GATE_INVALID", {
 		details: { ...(codexError.details ?? {}), ...(gateError.details ?? {}) },
 	});
 }
-
-export function codexSnapshotMismatchError(input: CodexSnapshotMismatchInput): UlwLoopError {
-	const { reconciliation, snapshot, taskScopedHint } = input;
-	const hint =
-		taskScopedHint?.aggregate === true && snapshot?.status === "complete" && snapshot.objective !== undefined
-			? buildTaskScopedAggregateReconciliationHint(taskScopedHint.goal, taskScopedHint.final)
-			: "";
-	const recovery = codexGoalMismatchRecovery(input.expectedObjective, snapshot);
-	return new UlwLoopError(
-		`${formatCodexGoalReconciliation(reconciliation)}${hint}\n${recovery.message}`,
-		"ulw_loop_codex_snapshot_mismatch",
-		{ details: recovery.details },
-	);
-}
-
-function normalizeObjective(value: string): string {
-	return value.replace(/\s+/g, " ").trim();
-}
-
-function textMentionsUlwLoopPlanArtifact(value: string | undefined): boolean {
-	const normalized = (value ?? "").toLowerCase();
-	return (
-		normalized.includes(ULW_LOOP_DIR.toLowerCase()) ||
-		normalized.includes(ULW_LOOP_GOALS.toLowerCase()) ||
-		normalized.includes(ULW_LOOP_LEDGER.toLowerCase())
-	);
-}
-
-function textMentionsGoalId(value: string | undefined, goalId: string): boolean {
-	return (value ?? "").toLowerCase().includes(goalId.toLowerCase());
-}
-
-function textHasCompletionValidationEvidence(value: string | undefined): boolean {
-	const normalized = (value ?? "").toLowerCase();
-	const done =
-		/\b(?:planned work|implementation|deliverables?|scope|task|work)\b/.test(normalized) &&
-		/\b(?:done|complete|completed|finished|shipped)\b/.test(normalized);
-	const verified =
-		/\b(?:validation|verification|tests?|build|lint|review|quality gate|code-review)\b/.test(normalized) &&
-		/\b(?:passed|complete|completed|clean|green|approve|approved|clear)\b/.test(normalized);
-	return done && verified;
-}
-
-async function snapshotObjectiveMapsToUlwLoopPlan(
-	repoRoot: string,
-	snapshotObjective: string,
-	scope?: UlwLoopScope,
-): Promise<boolean> {
-	const actual = normalizeObjective(snapshotObjective).toLowerCase();
-	if (textMentionsUlwLoopPlanArtifact(actual)) return true;
-	if (actual.length < 24 || !existsSync(ulwLoopBriefPath(repoRoot, scope))) return false;
-	try {
-		const brief = normalizeObjective(await readFile(ulwLoopBriefPath(repoRoot, scope), "utf8")).toLowerCase();
-		return brief.length >= 24 && (brief.includes(actual) || actual.includes(brief));
-	} catch (error) {
-		if (error instanceof Error) return false;
-		throw error;
-	}
-}
-
-export async function canReconcileCompletedTaskScopedAggregateSnapshot(
-	repoRoot: string,
-	plan: UlwLoopPlan,
-	goal: UlwLoopItem,
-	snapshotObjective: string,
-	evidence: string,
-	scope?: UlwLoopScope,
-): Promise<boolean> {
-	if (codexGoalMode(plan) !== "aggregate") return false;
-	if (goal.status !== "in_progress" || plan.activeGoalId !== goal.id) return false;
-	if (isFinalRunCompletionCandidate(plan, goal)) {
-		return snapshotObjectiveMapsToUlwLoopPlan(repoRoot, snapshotObjective, scope);
-	}
-	if (!textMentionsUlwLoopPlanArtifact(evidence) || !textMentionsGoalId(evidence, goal.id)) return false;
-	if (!textHasCompletionValidationEvidence(evidence)) return false;
-	return snapshotObjectiveMapsToUlwLoopPlan(repoRoot, snapshotObjective, scope);
-}
-
-export async function canReconcileActiveFinalTaskScopedAggregateSnapshot(
-	repoRoot: string,
-	plan: UlwLoopPlan,
-	goal: UlwLoopItem,
-	snapshotObjective: string,
-	evidence: string,
-	scope?: UlwLoopScope,
-): Promise<boolean> {
-	if (codexGoalMode(plan) !== "aggregate") return false;
-	if (goal.status !== "in_progress" || plan.activeGoalId !== goal.id) return false;
-	if (!isFinalRunCompletionCandidate(plan, goal)) return false;
-	if (!textHasCompletionValidationEvidence(evidence)) return false;
-	return snapshotObjectiveMapsToUlwLoopPlan(repoRoot, snapshotObjective, scope);
-}
-
-function buildCompletedLegacyGoalRemediation(goal: UlwLoopItem): string {
-	return [
-		"If get_goal returns a different completed legacy/thread objective, do not repeat --status complete in this thread.",
-		`Record a non-terminal blocker with: omo-agent-toolkit ulw-loop checkpoint --goal-id ${goal.id} --status blocked --evidence "<completed legacy Codex goal blocks create_goal in this thread>" --codex-goal-json "<different completed get_goal JSON or path>".`,
-		"Then continue only from a Codex goal context with no active/completed conflicting goal, in the same repo/worktree, and create the intended goal there.",
-	].join(" ");
-}
-
-export function buildTaskScopedAggregateReconciliationHint(goal: UlwLoopItem, final: boolean): string {
-	if (final) {
-		return ` Final task-scoped aggregate reconciliation requires the checkpoint goal to be the active in-progress final OMO goal and the completed get_goal objective to map to the ulw-loop brief or artifact. ${buildCompletedLegacyGoalRemediation(goal)}`;
-	}
-	return ` Completed task-scoped aggregate reconciliation requires the checkpoint goal to be the active in-progress OMO goal, evidence that names that active OMO goal id, names .omo/ulw-loop/goals.json or ledger.jsonl, includes completed implementation plus validation/review evidence, and a get_goal objective that maps to the ulw-loop brief/artifact. ${buildCompletedLegacyGoalRemediation(goal)}`;
-}

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

@@ -40,6 +40,8 @@ export interface CheckpointUlwLoopResult {
 	readonly goal: UlwLoopItem;
 	readonly ledgerEntry: UlwLoopLedgerEntry;
 	readonly aggregateCompletion?: UlwLoopAggregateCompletion;
+	readonly nextActions: readonly string[];
+	readonly warnings: readonly string[];
 }
 
 const QUALITY_GATE_FS = { existsSync, statSync } as const;
@@ -158,6 +160,8 @@ export async function checkpointUlwLoop(
 		let aggregateCompletion: UlwLoopAggregateCompletion | undefined;
 		let qualityGate: UlwLoopQualityGate | undefined;
 		let codexGoal: unknown;
+		let nextActions: readonly string[] = [];
+		let warnings: readonly string[] = [];
 		if (args.status === "complete") {
 			const aggregate = codexGoalMode(plan) === "aggregate";
 			const final = isFinalRunCompletionCandidate(plan, goal);
@@ -170,7 +174,7 @@ export async function checkpointUlwLoop(
 			else requireAllCriteriaPass(goal);
 			let codexValidationError: UlwLoopError | undefined;
 			try {
-				codexGoal = await validateCheckpointCodexGoal({
+				const validation = await validateCheckpointCodexGoal({
 					repoRoot,
 					plan,
 					goal,
@@ -178,6 +182,9 @@ export async function checkpointUlwLoop(
 					evidence,
 					...(scope === undefined ? {} : { scope }),
 				});
+				codexGoal = validation.raw;
+				nextActions = validation.nextActions;
+				warnings = validation.warnings;
 			} catch (error) {
 				if (!(error instanceof UlwLoopError)) throw error;
 				codexValidationError = error;
@@ -213,6 +220,7 @@ export async function checkpointUlwLoop(
 		} else applyBlockedOrFailed(goal, plan, args.status, evidence, now);
 		goal.updatedAt = now;
 		if (aggregateCompletion !== undefined) plan.aggregateCompletion = aggregateCompletion;
+		if (aggregateCompletion !== undefined) nextActions = [...nextActions, 'aggregate complete — now update_goal({status:"complete"})'];
 		plan.updatedAt = now;
 		await writePlan(repoRoot, plan, scope);
 		const ledgerEntry = buildLedger(now, args, goal, qualityGate, codexGoal, aggregateCompletion);
@@ -220,7 +228,7 @@ export async function checkpointUlwLoop(
 		const closedBatch = args.status === "complete" ? batchClosedBy(plan, goal.id) : undefined;
 		if (closedBatch !== undefined) await appendLedger(repoRoot, { at: now, kind: "batch_closed", goalId: goal.id, message: closedBatch.batchId }, scope);
 		return aggregateCompletion === undefined
-			? { plan, goal, ledgerEntry }
-			: { plan, goal, ledgerEntry, aggregateCompletion };
+			? { plan, goal, ledgerEntry, nextActions, warnings }
+			: { plan, goal, ledgerEntry, aggregateCompletion, nextActions, warnings };
 	});
 }

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

@@ -65,11 +65,17 @@ export async function readJsonInput(value: string | undefined): Promise<unknown
 
 export async function parseCodexGoalJson(value: string | undefined): Promise<string | undefined> {
 	if (value === undefined) return undefined;
-	const raw = looksLikeJson(value) ? value : await readFile(value, "utf8");
-	try { JSON.parse(raw); return raw; }
-	catch (error) {
+	try {
+		const raw = looksLikeJson(value) ? value : await readFile(value, "utf8");
+		JSON.parse(raw);
+		return raw;
+	} catch (error) {
 		const message = error instanceof Error ? error.message : "unknown error";
-		throw new UlwLoopError(`Invalid --codex-goal-json: ${message}`, "ULW_LOOP_CODEX_GOAL_JSON_INVALID", { cause: error });
+		throw new UlwLoopError(
+			`Invalid --codex-goal-json: ${looksLikeJson(value) ? message : "neither valid JSON nor a readable path"}`,
+			"ULW_LOOP_CODEX_GOAL_JSON_INVALID",
+			{ cause: error },
+		);
 	}
 }
 

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

@@ -203,6 +203,8 @@ export async function reviewBlockers(
 			blockedGoal: result.blockedGoal,
 			goal: result.newGoal,
 			ledgerEntries: result.ledgerEntries,
+			nextActions: result.nextActions,
+			warnings: result.warnings,
 			summary: summarizeUlwLoopPlan(result.plan),
 		});
 	} else {