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

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];
+	});
+}

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

@@ -1,44 +1,100 @@
 import { UlwLoopError } from "./types.js";
 
-const PLACEHOLDER_PATTERN = /^(?:placeholder|todo|tbd|n\/a|stub)$/i;
+const PLACEHOLDER_PATTERN = /^(?:<replace:[^>]+>|placeholder|todo|tbd|n\/a|stub)$/i;
+type QualityGateDefect = { readonly field: string; readonly message: string };
+type QualityGateCollector = {
+	readonly defects: QualityGateDefect[];
+	readonly poisonedFields: Set<string>;
+	readonly poisonedArtifactKinds: Set<string>;
+};
+let activeCollector: QualityGateCollector | undefined;
 
-export function invalid(message: string, field: string): never {
-	throw new UlwLoopError(message, "ULW_LOOP_QUALITY_GATE_INVALID", { details: { field } });
+/** A recorded defect poisons only its field; consumers skip dependent checks while preserving valid siblings and entry identity. */
+export function withQualityGateCollector<T>(operation: () => T): T {
+	const previous = activeCollector;
+	const collector: QualityGateCollector = { defects: [], poisonedFields: new Set(), poisonedArtifactKinds: new Set() };
+	activeCollector = collector;
+	try {
+		const result = operation();
+		if (collector.defects.length === 0) return result;
+		throwQualityGateDefects(collector.defects);
+	} finally {
+		activeCollector = previous;
+	}
 }
 
+export function throwQualityGateDefects(defects: readonly QualityGateDefect[]): never {
+	const uniqueDefects = [
+		...new Map(defects.map((defect) => [`${defect.field}\u0000${defect.message}`, defect])).values(),
+	];
+	const fields = uniqueDefects.slice(0, 25);
+	const truncated = uniqueDefects.length > fields.length;
+	const message = [
+		`Final quality gate has ${fields.length}${truncated ? "+" : ""} validation defects:`,
+		...fields.map((item) => `- ${item.field}: ${item.message}`),
+	].join("\n");
+	throw new UlwLoopError(message, "ULW_LOOP_QUALITY_GATE_INVALID", {
+		details: { field: fields[0]?.field, fields, ...(truncated ? { truncated: true } : {}) },
+	});
+}
+export function invalid(message: string, field: string): undefined {
+	if (activeCollector === undefined)
+		throw new UlwLoopError(message, "ULW_LOOP_QUALITY_GATE_INVALID", { details: { field } });
+	activeCollector.defects.push({ field, message });
+	activeCollector.poisonedFields.add(field);
+	return undefined;
+}
+export function isPoisoned(field: string): boolean {
+	return activeCollector?.poisonedFields.has(field) ?? false;
+}
+export function poisonField(field: string): void {
+	activeCollector?.poisonedFields.add(field);
+}
+export function markPoisonedArtifactKind(id: string): void {
+	activeCollector?.poisonedArtifactKinds.add(id);
+}
+export function isPoisonedArtifactKind(id: string): boolean {
+	return activeCollector?.poisonedArtifactKinds.has(id) ?? false;
+}
 export function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-
 export function section(value: unknown, field: string): Record<string, unknown> {
-	return isRecord(value) ? value : invalid(`Final quality gate is missing ${field} evidence.`, field);
+	if (isRecord(value)) return value;
+	invalid(
+		`Final quality gate is missing ${field} evidence (accepted input: a bare object with manualQa/gateReview/iteration/criteriaCoverage and optional codeReview, or the same object under a top-level "qualityGate" key).`,
+		field,
+	);
+	return {};
 }
-
 export function textField(value: unknown, field: string): string {
-	if (typeof value !== "string" || value.trim() === "")
+	if (typeof value !== "string" || value.trim() === "") {
 		invalid(`Final quality gate requires non-empty ${field}.`, field);
+		return "";
+	}
 	const trimmed = value.trim();
 	if (PLACEHOLDER_PATTERN.test(trimmed)) invalid(`Final quality gate rejects placeholder ${field}.`, field);
 	return trimmed;
 }
-
 export function numberField(value: unknown, field: string): number {
-	return typeof value === "number" && Number.isFinite(value)
-		? value
-		: invalid(`Final quality gate requires numeric ${field}.`, field);
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	invalid(`Final quality gate requires numeric ${field}.`, field);
+	return 0;
 }
-
 export function stringArray(value: unknown, field: string): readonly string[] {
-	if (!Array.isArray(value) || value.length === 0) return invalid(`Final quality gate requires ${field}.`, field);
+	if (!Array.isArray(value) || value.length === 0) {
+		invalid(`Final quality gate requires ${field}.`, field);
+		return [];
+	}
 	return value.map((item) => textField(item, field));
 }
-
 export function emptyBlockers(value: unknown, field: string): readonly [] {
 	if (Array.isArray(value) && value.length === 0) return [];
 	invalid(`${field} must be empty.`, field);
+	return [];
 }
-
 export function literal<T extends string | boolean>(value: unknown, expected: T, field: string): T {
 	if (value === expected) return expected;
 	invalid(`${field} must be ${String(expected)}.`, field);
+	return expected;
 }

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

@@ -1,13 +1,17 @@
 import { invalid, literal, textField } from "./quality-gate-fields.js";
 
 export function passedVerdict(value: unknown, field: string): "passed" {
-	if (value === "not_applicable") invalid(`${field} must not be not_applicable.`, field);
+	if (value === "not_applicable") {
+		invalid(`${field} must not be not_applicable.`, field);
+		return "passed";
+	}
 	return literal(value, "passed", field);
 }
 
 export function codeQualityStatusField(value: unknown, field: string): "CLEAR" | "WATCH" {
 	if (value === "CLEAR" || value === "WATCH") return value;
 	invalid(`${field} must be CLEAR or WATCH.`, field);
+	return "CLEAR";
 }
 
 export function adversarialVerdict(
@@ -20,4 +24,5 @@ export function adversarialVerdict(
 		return { verdict: "not_applicable", reason: textField(row["reason"], `${field}.reason`) };
 	}
 	invalid(`${field} must be passed or not_applicable with a reason.`, field);
+	return { verdict: "passed" };
 }