lazycodex-ai 5.0.0-beta.9 → 5.0.0

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

@@ -0,0 +1,134 @@
+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;
+}
+
+export interface CheckpointTemplateDependencies {
+	readonly surface?: UlwLoopToolkitSurface;
+}
+
+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-high" : "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,
+	dependencies?: CheckpointTemplateDependencies,
+): Promise<CheckpointTemplate> {
+	const plan: UlwLoopPlan = await readUlwLoopPlan(repoRoot, scope);
+	const surface = dependencies?.surface ?? resolveToolkitSurface();
+	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-high","recommendation":"APPROVE","evidence":"review passed","reportPath":"<attemptDir>/gate-review.md","blockers":[],"notes":[]}, manualQa.artifactRefs objects, iteration, and criteriaCoverage.',
+		...(surface === "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-high, category:deep-low, 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(surface, 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,31 +3,23 @@ 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 { acknowledgeDriverObjective } from "./driver-objective-ack.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";
+import { commit } from "./plan-commit.js";
+import { readUlwLoopPlan, withUlwLoopMutationLock } from "./plan-io.js";
 import {
 	classifyExternalAuthorizationBlocker,
 	clearGoalBlockerFields,
 	sameBlockerOccurrences,
 	validateQualityGate,
 } from "./quality-gate.js";
+import { resolveToolkitSurface, type UlwLoopToolkitSurface } from "./surface.js";
 import type {
 	UlwLoopAggregateCompletion,
 	UlwLoopItem,
@@ -45,11 +37,16 @@ export interface CheckpointUlwLoopArgs {
 	readonly codexGoalJson?: string;
 	readonly qualityGateJson?: string;
 }
+export interface CheckpointUlwLoopDependencies {
+	readonly surface?: UlwLoopToolkitSurface;
+}
 export interface CheckpointUlwLoopResult {
 	readonly plan: UlwLoopPlan;
 	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;
@@ -57,9 +54,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 +133,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;
@@ -159,6 +156,7 @@ export async function checkpointUlwLoop(
 	repoRoot: string,
 	args: CheckpointUlwLoopArgs,
 	scope?: UlwLoopScope,
+	dependencies?: CheckpointUlwLoopDependencies,
 ): Promise<CheckpointUlwLoopResult> {
 	return withUlwLoopMutationLock(repoRoot, scope, async () => {
 		const plan = await readUlwLoopPlan(repoRoot, scope);
@@ -168,6 +166,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);
@@ -178,64 +178,45 @@ 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 {
+				const validation = await validateCheckpointCodexGoal({
+					repoRoot,
+					plan,
+					goal,
+					raw: args.codexGoalJson,
+					evidence,
+					...(scope === undefined ? {} : { scope }),
+				});
+				codexGoal = validation.raw;
+				nextActions = validation.nextActions;
+				warnings = validation.warnings;
+				acknowledgeDriverObjective(plan, validation.unacknowledgedObjective);
+			} 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: dependencies?.surface ?? 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;
@@ -246,14 +227,15 @@ 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);
-		await appendLedger(repoRoot, ledgerEntry, scope);
+		const entries = [ledgerEntry];
 		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);
+		if (closedBatch !== undefined) entries.push({ at: now, kind: "batch_closed", goalId: goal.id, message: closedBatch.batchId });
+		await commit(repoRoot, scope, { plan, entries });
 		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-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

@@ -11,14 +11,12 @@ import {
 import { blockedDecisionHandoff, normalizeCodexGoalMode, printJson, printStatus } from "./cli-output.js";
 import { parseSteeringProposals, printSteerBatchResult, printSteerResult } from "./cli-steering.js";
 import { buildCodexGoalInstruction } from "./codex-goal-instruction.js";
-import { recordEvidence } from "./evidence.js";
 import { isEssentialCriterion } from "./goal-status.js";
-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 { steerUlwLoop } from "./steering.js";
+import type { UlwLoopScope } from "./paths.js";
+import { summarizeUlwLoopPlan } from "./plan-crud.js";
+import { type AgentToolkit, createAgentToolkit } from "./sdk.js";
 import { steerUlwLoopBatch } from "./steering-batch.js";
+import { resolveToolkitSurface } from "./surface.js";
 import type { UlwLoopItem } from "./types.js";
 import { UlwLoopError } from "./types.js";
 
@@ -41,15 +39,13 @@ export async function createGoals(
 		);
 	}
 	const validationBatchesJson = readValue(argv, "--validation-batch-json");
-	const plan = await createUlwLoopPlan(
-		repoRoot,
-		{
+	const plan = unwrap(
+		await toolkitFor(repoRoot, scope).createGoals({
 			brief,
 			codexGoalMode: normalizeCodexGoalMode(readValue(argv, "--codex-goal-mode")),
 			force: hasFlag(argv, "--force"),
 			...(validationBatchesJson === undefined ? {} : { validationBatchesJson }),
-		},
-		scope,
+		}),
 	);
 	if (json) printJson({ ok: true, plan, summary: summarizeUlwLoopPlan(plan) });
 	else {
@@ -61,20 +57,9 @@ export async function createGoals(
 }
 
 export async function status(repoRoot: string, json: boolean, scope?: UlwLoopScope): Promise<number> {
-	const plan = await readUlwLoopPlan(repoRoot, scope);
-	if (json) {
-		const active = plan.goals.find((goal) => goal.id === plan.activeGoalId);
-		const currentAttemptDir =
-			plan.evidenceLayoutVersion === 2 && active
-				? ulwLoopAttemptEvidenceDir(active.id, active.attempt, scope)
-				: undefined;
-		printJson({
-			ok: true,
-			plan,
-			summary: summarizeUlwLoopPlan(plan),
-			...(currentAttemptDir === undefined ? {} : { currentAttemptDir }),
-		});
-	} else printStatus(plan);
+	const status = unwrap(await toolkitFor(repoRoot, scope).status());
+	if (json) printJson({ ok: true, ...status });
+	else printStatus(status.plan);
 	return 0;
 }
 
@@ -84,7 +69,9 @@ export async function completeGoals(
 	json: boolean,
 	scope?: UlwLoopScope,
 ): Promise<number> {
-	const result = await startNextUlwLoop(repoRoot, { retryFailed: hasFlag(argv, "--retry-failed") }, scope);
+	const result = unwrap(
+		await toolkitFor(repoRoot, scope).completeGoals({ retryFailed: hasFlag(argv, "--retry-failed") }),
+	);
 	if ("done" in result) {
 		const handoff = blockedDecisionHandoff(result.plan);
 		if (json) {
@@ -114,7 +101,7 @@ export async function steer(
 	const proposals = await parseSteeringProposals(argv);
 	const single = proposals[0];
 	if (single !== undefined && proposals.length === 1 && readValue(argv, "--proposals-json") === undefined) {
-		const result = await steerUlwLoop(repoRoot, single, scope);
+		const result = unwrap(await toolkitFor(repoRoot, scope).steer(single));
 		printSteerResult(result, json);
 		return result.accepted ? 0 : 1;
 	}
@@ -129,10 +116,11 @@ export async function addGoal(
 	json: boolean,
 	scope?: UlwLoopScope,
 ): Promise<number> {
-	const result = await addUlwLoopGoal(
-		repoRoot,
-		{ title: required(argv, "--title"), objective: required(argv, "--objective") },
-		scope,
+	const result = unwrap(
+		await toolkitFor(repoRoot, scope).addGoal({
+			title: required(argv, "--title"),
+			objective: required(argv, "--objective"),
+		}),
 	);
 	if (json) printJson({ ok: true, plan: result.plan, goal: result.goal, summary: summarizeUlwLoopPlan(result.plan) });
 	else {
@@ -149,10 +137,12 @@ export async function criteria(
 	scope?: UlwLoopScope,
 ): Promise<number> {
 	const goalId = required(argv, "--goal-id");
-	const goal = findGoal(await readUlwLoopPlan(repoRoot, scope), goalId);
-	if (json) printJson({ ok: true, goalId: goal.id, criteria: goal.successCriteria });
+	const result = unwrap(await toolkitFor(repoRoot, scope).criteria({ goalId }));
+	if (json) printJson({ ok: true, goalId: result.goalId, criteria: result.criteria });
 	else {
-		process.stdout.write(`criteria for ${goal.id}:\n${goal.successCriteria.map(formatCriterionForCli).join("\n")}\n`);
+		process.stdout.write(
+			`criteria for ${result.goalId}:\n${result.criteria.map(formatCriterionForCli).join("\n")}\n`,
+		);
 	}
 	return 0;
 }
@@ -163,7 +153,7 @@ export async function captureEvidence(
 	json: boolean,
 	scope?: UlwLoopScope,
 ): Promise<number> {
-	const result = await recordEvidence(repoRoot, parseRecordEvidenceArgs(argv), scope);
+	const result = unwrap(await toolkitFor(repoRoot, scope).recordEvidence(parseRecordEvidenceArgs(argv)));
 	if (json) printJson({ ok: true, ...result, summary: summarizeUlwLoopPlan(result.plan) });
 	else {
 		process.stdout.write(
@@ -183,16 +173,14 @@ export async function reviewBlockers(
 	if (codexGoalJson === undefined) {
 		throw new UlwLoopError("Missing --codex-goal-json.", "ULW_LOOP_CODEX_GOAL_JSON_REQUIRED");
 	}
-	const result = await recordFinalReviewBlockers(
-		repoRoot,
-		{
+	const result = unwrap(
+		await toolkitFor(repoRoot, scope).recordReviewBlockers({
 			goalId: required(argv, "--goal-id"),
 			title: required(argv, "--title"),
 			objective: required(argv, "--objective"),
 			evidence: required(argv, "--evidence"),
 			codexGoalJson,
-		},
-		scope,
+		}),
 	);
 	if (json) {
 		printJson({
@@ -201,6 +189,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 {
@@ -211,6 +201,28 @@ export async function reviewBlockers(
 	return 0;
 }
 
+// Every subcommand runs through the SDK so state logic lives in one place; the CLI keeps only argv
+// parsing and the legacy output shapes. A failed envelope is rethrown as the typed error the CLI's
+// JSON error path already prints.
+function toolkitFor(repoRoot: string, scope?: UlwLoopScope): AgentToolkit {
+	const sessionId = scope?.sessionId?.trim();
+	if (sessionId === undefined || sessionId.length === 0) {
+		throw new UlwLoopError("Missing --session-id.", "ULW_LOOP_SESSION_ID_REQUIRED", {
+			details: { flag: "--session-id" },
+		});
+	}
+	return createAgentToolkit({ cwd: repoRoot, sessionId, surface: resolveToolkitSurface() });
+}
+
+function unwrap<Result>(
+	response:
+		| { readonly ok: true; readonly result: Result }
+		| { readonly ok: false; readonly error: { readonly code: string; readonly message: string } },
+): Result {
+	if (response.ok) return response.result;
+	throw new UlwLoopError(response.error.message, response.error.code);
+}
+
 function formatCriterionForCli(criterion: UlwLoopItem["successCriteria"][number]): string {
 	const marker = isEssentialCriterion(criterion) ? "essential" : "non-essential";
 	return `- ${criterion.id} [${criterion.status}] [${marker}] (${criterion.userModel}) ${criterion.scenario} evidence: ${criterion.capturedEvidence ?? "pending"}`;
@@ -221,9 +233,3 @@ function required(argv: readonly string[], flag: string): string {
 	if (value) return value;
 	throw new UlwLoopError(`Missing ${flag}.`, "ULW_LOOP_ARGUMENT_MISSING", { details: { flag } });
 }
-
-function findGoal(plan: { readonly goals: readonly UlwLoopItem[] }, goalId: string): UlwLoopItem {
-	const goal = plan.goals.find((candidate) => candidate.id === goalId);
-	if (goal !== undefined) return goal;
-	throw new UlwLoopError(`Unknown ulw-loop id: ${goalId}.`, "ULW_LOOP_GOAL_NOT_FOUND", { details: { goalId } });
-}