oh-my-opencode 5.0.0-beta.6 → 5.0.0-beta.60

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

@@ -2,7 +2,15 @@ import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 
-export type CodexGoalSnapshotStatus = "active" | "complete" | "cancelled" | "failed" | "unknown";
+export type CodexGoalSnapshotStatus =
+	| "active"
+	| "complete"
+	| "paused"
+	| "usage_limited"
+	| "budget_limited"
+	| "cancelled"
+	| "failed"
+	| "unknown";
 
 export interface CodexGoalSnapshot {
 	available: boolean;
@@ -20,10 +28,7 @@ export interface CodexGoalReconciliation {
 
 export interface ReconcileCodexGoalOptions {
 	expectedObjective: string;
-	acceptedObjectives?: readonly string[];
-	allowedStatuses?: readonly CodexGoalSnapshotStatus[];
-	requireSnapshot?: boolean;
-	requireComplete?: boolean;
+	readonly acceptedObjectives?: readonly string[];
 }
 
 export class CodexGoalSnapshotError extends Error {}
@@ -32,14 +37,21 @@ function safeObject(value: unknown): Record<string, unknown> {
 }
 
 function safeString(value: unknown): string {
+	return typeof value === "string" ? value : "";
+}
+
+function safeStatusString(value: unknown): string {
 	return typeof value === "string" ? value.trim() : "";
 }
 
 function normalizeStatus(value: unknown): CodexGoalSnapshotStatus {
-	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";
 }
@@ -56,7 +68,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 {
@@ -98,38 +112,30 @@ export function reconcileCodexGoalSnapshot(
 	const errors: string[] = [];
 	const warnings: string[] = [];
 
+	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,
-		),
+		[
+			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 (actualStatus === "paused" || actualStatus === "usage_limited" || actualStatus === "budget_limited") {
+		warnings.push("/goal resume or raise the budget");
 	}
-	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 === "complete")
+		warnings.push(`driver closed early: call create_goal with codexObjective "${expected}" verbatim`);
 	return { ok: errors.length === 0, snapshot: effectiveSnapshot, warnings, errors };
 }
 

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;

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

@@ -1,11 +1,18 @@
 import { isAbsolute, join, relative, sep } from "node:path";
-import { ULW_LOOP_BRIEF, ULW_LOOP_DIR, ULW_LOOP_GOALS, ULW_LOOP_LEDGER } from "./types.js";
+import {
+	ULW_LOOP_BRIEF,
+	ULW_LOOP_DIR,
+	ULW_LOOP_GOALS,
+	ULW_LOOP_LEDGER,
+	ULW_LOOP_STATE_LOCK,
+	UlwLoopError,
+} from "./types.js";
 
 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 {
@@ -63,6 +70,12 @@ export function ulwLoopLedgerPath(repoRoot: string, scope?: UlwLoopScope): strin
 	return join(ulwLoopDir(repoRoot, scope), ULW_LOOP_LEDGER);
 }
 
+// One lock per state directory covers goals.json, ledger.jsonl, and the hook
+// counters beside them; the CLI mutations and the Codex hooks all take it.
+export function ulwLoopStateLockPath(repoRoot: string, scope?: UlwLoopScope): string {
+	return join(ulwLoopDir(repoRoot, scope), ULW_LOOP_STATE_LOCK);
+}
+
 export function repoRelative(absolutePath: string, repoRoot: string): string {
 	const slashPrefix = `${repoRoot}/`;
 	const backslashPrefix = `${repoRoot}\\`;
@@ -73,9 +86,17 @@ export function repoRelative(absolutePath: string, repoRoot: string): string {
 }
 
 // Both the status --json emitter and the checkpoint enforcement resolve the attempt dir through
-// this function; a second resolution path would let the gate reject its own advertised directory.
+// this function from the scope alone; a second resolution path (env, a literal placeholder)
+// would let the gate reject its own advertised directory.
 export function ulwLoopAttemptEvidenceDir(goalId: string, attempt: number, scope?: UlwLoopScope): string {
-	const sessionId = normalizeUlwLoopSessionId(scope?.sessionId) ?? resolveUlwLoopSessionIdFromEnv() ?? "session";
+	const sessionId = normalizeUlwLoopSessionId(scope?.sessionId);
+	if (sessionId === null) {
+		throw new UlwLoopError(
+			`Evidence for ${goalId} attempt ${attempt} needs a session scope; pass --session-id <id> so the attempt directory lives under .omo/evidence/ulw/<id>/.`,
+			"ULW_LOOP_SESSION_SCOPE_REQUIRED",
+			{ details: { goalId, attempt } },
+		);
+	}
 	return `.omo/evidence/ulw/${sessionId}/${goalId}/a${attempt}`;
 }
 

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

@@ -1,4 +1,5 @@
-import { createReadStream } from "node:fs";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createReadStream, readdirSync } from "node:fs";
 import { appendFile, mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { createInterface } from "node:readline";
 
@@ -10,13 +11,20 @@ import {
 	ulwLoopGoalsPath,
 	ulwLoopLedgerPath,
 	ulwLoopRelativeDir,
+	ulwLoopStateLockPath,
 } from "./paths.js";
+import { planMissingRecovery } from "./plan-missing-recovery.js";
+import { withStateLock } from "./state-lock.js";
 import type { UlwLoopLedgerEntry, UlwLoopPlan } from "./types.js";
 import { iso, ULW_LOOP_DIR, ULW_LOOP_GOALS, ULW_LOOP_LEDGER, UlwLoopError } from "./types.js";
 
 const LEGACY_OBJECTIVE_PREFIX = `Complete all ulw-loop stories in ${ULW_LOOP_DIR}/${ULW_LOOP_GOALS}: `;
 const LEGACY_OBJECTIVE = `Complete all ulw-loop stories listed in ${ULW_LOOP_DIR}/${ULW_LOOP_GOALS}. Use ${ULW_LOOP_DIR}/${ULW_LOOP_LEDGER} as the durable audit trail.`;
 const locks = new Map<string, Promise<undefined>>();
+// Tracks which state dirs the CURRENT async continuation holds, so a read nested
+// inside a locked mutation can tell itself apart from an unlocked read elsewhere
+// in the same process.
+const heldLocks = new AsyncLocalStorage<ReadonlySet<string>>();
 
 function hasCode(error: unknown, code: string): boolean {
 	return error instanceof Error && "code" in error && error.code === code;
@@ -50,8 +58,13 @@ export async function withUlwLoopMutationLock<T>(
 	const fn = typeof scopeOrFn === "function" ? scopeOrFn : maybeFn;
 	if (fn === undefined) throw new UlwLoopError("Missing ulw-loop mutation body.", "ULW_LOOP_LOCK_BODY_MISSING");
 	const lockKey = `${repoRoot}\0${ulwLoopRelativeDir(scope)}`;
+	const lockPath = ulwLoopStateLockPath(repoRoot, scope);
+	// The promise chain orders callers inside this process; the file lock is what
+	// excludes every other process (each CLI invocation) touching the same state dir.
+	const locked = (): Promise<T> =>
+		withStateLock(lockPath, () => heldLocks.run(new Set([...(heldLocks.getStore() ?? []), lockKey]), fn));
 	const prior = locks.get(lockKey) ?? Promise.resolve(undefined);
-	const run = prior.then(fn, fn);
+	const run = prior.then(locked, locked);
 	// The stored gate resolves to undefined so the map never retains fn's result
 	// (plans/audits), and it removes itself once no newer waiter replaced it —
 	// otherwise a long-lived host leaks one entry per (repo, scope) forever.
@@ -73,10 +86,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(listUlwLoopSessionIds(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);
@@ -88,6 +102,14 @@ export async function readUlwLoopPlan(repoRoot: string, scope?: UlwLoopScope): P
 		(parsed.codexGoalMode ?? "per_story") === "aggregate" &&
 		isLegacyEnumeratedAggregateObjective(previousObjective)
 	) {
+		if (!(heldLocks.getStore()?.has(`${repoRoot}\0${ulwLoopRelativeDir(scope)}`) ?? false)) {
+			// A read path (status/criteria) must not mutate state: mutating here runs
+			// unlocked and a second reader could write a partially-migrated plan.
+			throw new UlwLoopError(
+				`The ulw-loop plan at ${repoRelative(path, repoRoot)} carries a legacy enumerated aggregate objective that must be migrated before reads continue. Run any state-mutating ulw-loop command once (e.g. \`record-evidence\`, \`steer\`, \`checkpoint\`) to migrate it under the state lock, then retry.`,
+				"ULW_LOOP_MIGRATION_REQUIRED",
+			);
+		}
 		const now = iso();
 		parsed.codexObjective = aggregateCodexObjectiveForScope(scope);
 		parsed.codexObjectiveAliases = [...new Set([...(parsed.codexObjectiveAliases ?? []), previousObjective])];
@@ -108,6 +130,19 @@ export async function readUlwLoopPlan(repoRoot: string, scope?: UlwLoopScope): P
 	return parsed;
 }
 
+// Session dirs are the only recovery hint that matters when a plan or a scope is
+// missing: the caller is almost always meant to target one of these siblings.
+export function listUlwLoopSessionIds(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,38 @@
+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 sessionScopeRequiredMessage(flag: string, existingSessionIds: readonly string[]): string {
+	const lines = [
+		"No ulw-loop session scope: neither the session env (OMO_ULW_LOOP_SESSION_ID / CODEX_SESSION_ID / CODEX_THREAD_ID / PI_SESSION_ID) nor the flag names this run, and the shared .omo/ulw-loop root is never used implicitly because every session in this directory would read and overwrite it.",
+		`Recovery: pass the scope explicitly: \`${flag} <id>\` (subprocess, eval, and hook contexts do not inherit the session env).`,
+	];
+	if (existingSessionIds.length > 0) {
+		lines.push(`Existing ulw-loop session ids under .omo/ulw-loop/: ${existingSessionIds.join(", ")}.`);
+	}
+	return lines.join("\n");
+}
+
+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);
+}

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

@@ -0,0 +1,123 @@
+import { resolve } from "node:path";
+import { isWithinAttemptDir } from "./paths.js";
+import type { ValidateQualityGateOptions } from "./quality-gate.js";
+import {
+	invalid,
+	isPoisoned,
+	markPoisonedArtifactKind,
+	section,
+	stringArray,
+	textField,
+} from "./quality-gate-fields.js";
+import type { UlwLoopManualQaArtifactKind, UlwLoopManualQaArtifactRef, UlwLoopManualQaSurface } from "./types.js";
+
+export const SUPPORTED_SURFACES: readonly UlwLoopManualQaSurface[] = ["cli", "http", "tmux", "browser", "gui", "data"];
+export const SUPPORTED_KINDS: readonly UlwLoopManualQaArtifactKind[] = [
+	"cli-transcript",
+	"log",
+	"screenshot",
+	"image",
+	"http-dump",
+	"data-diff",
+];
+const COMPATIBLE_KINDS: Readonly<Record<UlwLoopManualQaSurface, readonly UlwLoopManualQaArtifactKind[]>> = {
+	cli: ["cli-transcript", "log"],
+	tmux: ["cli-transcript", "log"],
+	http: ["http-dump"],
+	browser: ["screenshot", "image"],
+	gui: ["screenshot", "image"],
+	data: ["data-diff"],
+};
+
+function isSupportedSurface(value: unknown): value is UlwLoopManualQaSurface {
+	return SUPPORTED_SURFACES.some((surface) => surface === value);
+}
+function isSupportedKind(value: unknown): value is UlwLoopManualQaArtifactKind {
+	return SUPPORTED_KINDS.some((kind) => kind === value);
+}
+
+export function surfaceField(value: unknown, field: string): UlwLoopManualQaSurface {
+	if (isSupportedSurface(value)) return value;
+	invalid(`${field} must be a supported manual QA surface (${SUPPORTED_SURFACES.join(", ")}).`, field);
+	return "cli";
+}
+export function kindField(value: unknown, field: string): UlwLoopManualQaArtifactKind {
+	if (isSupportedKind(value)) return value;
+	invalid(
+		`${field} must be a supported artifact kind (${SUPPORTED_KINDS.join(", ")}); review/QA reports belong in codeReview.reportPath or gateReview.reportPath, not artifactRefs.`,
+		field,
+	);
+	return "log";
+}
+export function compatibleKindsFor(surface: UlwLoopManualQaSurface): readonly UlwLoopManualQaArtifactKind[] {
+	return COMPATIBLE_KINDS[surface];
+}
+export function artifactCompatible(surface: UlwLoopManualQaSurface, kind: UlwLoopManualQaArtifactKind): boolean {
+	return compatibleKindsFor(surface).includes(kind);
+}
+export function checkFile(path: string, field: string, opts?: ValidateQualityGateOptions): void {
+	if (opts?.repoRoot === undefined || opts.fs === undefined || isPoisoned(field)) return;
+	const absolute = resolve(opts.repoRoot, path);
+	if (!opts.fs.existsSync(absolute)) {
+		invalid(`${field} must point to an existing artifact.`, field);
+		return;
+	}
+	if (opts.fs.statSync(absolute).size <= 0) invalid(`${field} must point to a non-empty artifact.`, field);
+	if (
+		opts.currentAttemptDir !== undefined &&
+		!isWithinAttemptDir(absolute, resolve(opts.repoRoot, opts.currentAttemptDir))
+	)
+		invalid(
+			`${field} (${path}) must point to an artifact from the current attempt (${opts.currentAttemptDir}).`,
+			field,
+		);
+}
+export function artifactMap(refs: readonly UlwLoopManualQaArtifactRef[]): Map<string, UlwLoopManualQaArtifactRef> {
+	const byId = new Map<string, UlwLoopManualQaArtifactRef>();
+	for (const ref of refs) {
+		if (byId.has(ref.id)) invalid(`manualQa.artifactRefs contains duplicate ${ref.id}.`, "manualQa.artifactRefs");
+		byId.set(ref.id, ref);
+	}
+	return byId;
+}
+export function parseArtifactRefs(
+	value: unknown,
+	opts?: ValidateQualityGateOptions,
+): readonly UlwLoopManualQaArtifactRef[] {
+	if (!Array.isArray(value) || value.length === 0) {
+		invalid("manualQa.artifactRefs must not be empty.", "manualQa.artifactRefs");
+		return [];
+	}
+	return value.flatMap((item, index) => {
+		const prefix = `manualQa.artifactRefs[${index}]`;
+		const ref = section(item, prefix);
+		if (isPoisoned(prefix)) return [];
+		const pathField = `${prefix}.path`;
+		const idField = `${prefix}.id`;
+		const kindFieldName = `${prefix}.kind`;
+		const descriptionField = `${prefix}.description`;
+		const path = textField(ref["path"], pathField);
+		const id = textField(ref["id"], idField);
+		const kind = kindField(ref["kind"], kindFieldName);
+		if (isPoisoned(kindFieldName)) markPoisonedArtifactKind(id);
+		const description = textField(ref["description"], descriptionField);
+		checkFile(path, pathField, opts);
+		return [{ id, kind, description, path }];
+	});
+}
+export function referencedArtifacts(
+	value: unknown,
+	field: string,
+	byId: ReadonlyMap<string, UlwLoopManualQaArtifactRef>,
+): readonly UlwLoopManualQaArtifactRef[] {
+	const ids = stringArray(value, field);
+	if (isPoisoned(field)) return [];
+	return ids.flatMap((id) => {
+		const artifact = byId.get(id);
+		if (artifact === undefined) {
+			invalid(`${field} references unknown artifact ${id}.`, field);
+			return [];
+		}
+		return [artifact];
+	});
+}