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

package/packages/omo-codex/plugin/components/ulw-loop/dist/codex-goal-instruction.d.ts

@@ -1,3 +1,4 @@
+import { type UlwLoopToolkitSurface } from "./surface.js";
 import type { UlwLoopItem, UlwLoopPlan } from "./types.js";
 export interface CodexCreateGoalPayload {
     readonly objective: string;
@@ -10,4 +11,5 @@ export declare function buildCodexGoalInstruction(args: {
     readonly plan: UlwLoopPlan;
     readonly goal: UlwLoopItem;
     readonly isFinal?: boolean;
+    readonly surface?: UlwLoopToolkitSurface;
 }): UlwLoopGoalInstruction;

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

@@ -1,15 +1,17 @@
 // biome-ignore-all format: long agent-facing instruction strings are intentionally stable.
 import { codexGoalMode, expectedCodexObjective, isEssentialCriterion, isFinalRunCompletionCandidate, } from "./goal-status.js";
+import { resolveToolkitSurface, reviewerRolesFor } from "./surface.js";
 export function buildCodexGoalInstruction(args) {
     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, goal) {
     return { objective: expectedCodexObjective(plan, goal) };
 }
-function buildText(mode, plan, goal, createGoal, isFinal) {
+function buildText(mode, plan, goal, createGoal, isFinal, surface) {
     return joinLines([
         mode === "aggregate" ? "UlwLoop aggregate-goal handoff" : "UlwLoop active-goal handoff",
         `Mode: ${mode}`,
@@ -26,7 +28,7 @@ function buildText(mode, plan, goal, createGoal, isFinal) {
         "- 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:",
@@ -80,19 +82,21 @@ function evidenceLayoutLines(plan) {
         "- Evidence layout v2: write every artifact for the active goal (QA matrix, review reports, receipts) under the current attempt directory — read currentAttemptDir from `omo-agent-toolkit ulw-loop status --json` (.omo/evidence/ulw/<session>/<goalId>/a<attempt>). The final checkpoint rejects quality-gate artifacts outside that directory.",
     ];
 }
-function finalSection(plan, goal, isFinal, aggregate) {
+function finalSection(plan, goal, isFinal, aggregate, surface) {
+    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:",
@@ -103,6 +107,22 @@ function finalSection(plan, goal, isFinal, aggregate) {
         `  ${checkpointCommand}`,
     ]);
 }
+function senpiFinalSection(plan, goal, aggregate) {
+    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) {
     const prefix = ".omo/ulw-loop/";
     const suffix = "/goals.json";

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

@@ -1,4 +1,4 @@
-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;
     objective?: string;
@@ -13,10 +13,7 @@ export interface CodexGoalReconciliation {
 }
 export interface ReconcileCodexGoalOptions {
     expectedObjective: string;
-    acceptedObjectives?: readonly string[];
-    allowedStatuses?: readonly CodexGoalSnapshotStatus[];
-    requireSnapshot?: boolean;
-    requireComplete?: boolean;
+    readonly acceptedObjectives?: readonly string[];
 }
 export declare class CodexGoalSnapshotError extends Error {
 }

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";
@@ -31,7 +40,7 @@ export function parseCodexGoalSnapshot(value) {
         return { available: false, raw: value };
     }
     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 {
         available: Boolean(objective || status !== "unknown"),
@@ -64,31 +73,26 @@ 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) {

package/packages/omo-codex/plugin/components/ulw-loop/dist/constants.d.ts

@@ -2,6 +2,7 @@ export declare const ULW_LOOP_DIR = ".omo/ulw-loop";
 export declare const ULW_LOOP_BRIEF = "brief.md";
 export declare const ULW_LOOP_GOALS = "goals.json";
 export declare const ULW_LOOP_LEDGER = "ledger.jsonl";
+export declare const ULW_LOOP_STATE_LOCK = ".state.lock";
 export type UlwLoopStatus = "pending" | "in_progress" | "complete" | "failed" | "blocked" | "review_blocked" | "needs_user_decision";
 export type UlwLoopCodexGoalMode = "aggregate" | "per_story";
 export type UlwLoopSteeringStatus = "superseded" | "blocked";

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

@@ -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 const ULW_LOOP_STEERING_MUTATION_KINDS = [
     "add_subgoal",
     "split_subgoal",

package/packages/omo-codex/plugin/components/ulw-loop/dist/domain-types.d.ts

@@ -89,15 +89,7 @@ export interface UlwLoopManualQaAdversarialCase {
     readonly reason?: string;
     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";
@@ -128,6 +120,21 @@ export interface UlwLoopQualityGate {
         readonly adversarialClassesCovered: readonly string[];
     };
 }
+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;
@@ -149,3 +156,4 @@ export interface UlwLoopLedgerEntry {
     blockerOccurrenceCount?: number;
     requiredExternalDecision?: string;
 }
+export {};

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

@@ -12,6 +12,7 @@ export declare function ulwLoopLedgerRelativePath(scope?: UlwLoopScope): string;
 export declare function ulwLoopBriefPath(repoRoot: string, scope?: UlwLoopScope): string;
 export declare function ulwLoopGoalsPath(repoRoot: string, scope?: UlwLoopScope): string;
 export declare function ulwLoopLedgerPath(repoRoot: string, scope?: UlwLoopScope): string;
+export declare function ulwLoopStateLockPath(repoRoot: string, scope?: UlwLoopScope): string;
 export declare function repoRelative(absolutePath: string, repoRoot: string): string;
 export declare function ulwLoopAttemptEvidenceDir(goalId: string, attempt: number, scope?: UlwLoopScope): string;
 interface AttemptPathApi {

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

@@ -1,6 +1,6 @@
 import { isAbsolute, join, relative, sep } from "node:path";
-import { ULW_LOOP_BRIEF, ULW_LOOP_DIR, ULW_LOOP_GOALS, ULW_LOOP_LEDGER } from "./types.js";
-const SESSION_ENV_KEYS = ["OMO_ULW_LOOP_SESSION_ID", "CODEX_SESSION_ID", "CODEX_THREAD_ID"];
+import { ULW_LOOP_BRIEF, ULW_LOOP_DIR, ULW_LOOP_GOALS, ULW_LOOP_LEDGER, ULW_LOOP_STATE_LOCK, UlwLoopError, } from "./types.js";
+const SESSION_ENV_KEYS = ["OMO_ULW_LOOP_SESSION_ID", "CODEX_SESSION_ID", "CODEX_THREAD_ID", "PI_SESSION_ID"];
 export function normalizeUlwLoopSessionId(sessionId) {
     const trimmed = sessionId?.trim();
     if (!trimmed)
@@ -48,6 +48,11 @@ export function ulwLoopGoalsPath(repoRoot, scope) {
 export function ulwLoopLedgerPath(repoRoot, scope) {
     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, scope) {
+    return join(ulwLoopDir(repoRoot, scope), ULW_LOOP_STATE_LOCK);
+}
 export function repoRelative(absolutePath, repoRoot) {
     const slashPrefix = `${repoRoot}/`;
     const backslashPrefix = `${repoRoot}\\`;
@@ -58,9 +63,13 @@ export function repoRelative(absolutePath, repoRoot) {
     return absolutePath.split("\\").join("/");
 }
 // 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, attempt, scope) {
-    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}`;
 }
 const PLATFORM_PATH_API = { relative, isAbsolute, sep };

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

@@ -3,6 +3,7 @@ import type { UlwLoopLedgerEntry, UlwLoopPlan } from "./types.js";
 export declare function withUlwLoopMutationLock<T>(repoRoot: string, fn: () => Promise<T>): Promise<T>;
 export declare function withUlwLoopMutationLock<T>(repoRoot: string, scope: UlwLoopScope | undefined, fn: () => Promise<T>): Promise<T>;
 export declare function readUlwLoopPlan(repoRoot: string, scope?: UlwLoopScope): Promise<UlwLoopPlan>;
+export declare function listUlwLoopSessionIds(repoRoot: string): readonly string[];
 export declare function writePlan(repoRoot: string, plan: UlwLoopPlan, scope?: UlwLoopScope): Promise<void>;
 export declare function appendLedger(repoRoot: string, entry: UlwLoopLedgerEntry, scope?: UlwLoopScope): Promise<void>;
 export declare function appendLedgerEntries(repoRoot: string, entries: readonly UlwLoopLedgerEntry[], scope?: UlwLoopScope): Promise<void>;

package/packages/omo-codex/plugin/components/ulw-loop/dist/plan-io.js

@@ -1,12 +1,19 @@
-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";
 import { aggregateCodexObjectiveForScope } from "./goal-status.js";
-import { repoRelative, ulwLoopDir, ulwLoopGoalsPath, ulwLoopLedgerPath, ulwLoopRelativeDir, } from "./paths.js";
+import { repoRelative, ulwLoopDir, ulwLoopGoalsPath, ulwLoopLedgerPath, ulwLoopRelativeDir, ulwLoopStateLockPath, } from "./paths.js";
+import { planMissingRecovery } from "./plan-missing-recovery.js";
+import { withStateLock } from "./state-lock.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();
+// 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();
 function hasCode(error, code) {
     return error instanceof Error && "code" in error && error.code === code;
 }
@@ -25,8 +32,12 @@ export async function withUlwLoopMutationLock(repoRoot, 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 = () => 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.
@@ -47,7 +58,8 @@ export async function readUlwLoopPlan(repoRoot, scope) {
     catch (error) {
         if (!hasCode(error, "ENOENT"))
             throw error;
-        throw new UlwLoopError(`No ulw-loop plan found at ${repoRelative(path, repoRoot)}. Run \`omo-agent-toolkit ulw-loop create-goals ...\` first.`, "ULW_LOOP_PLAN_MISSING", { cause: error });
+        const recovery = planMissingRecovery(listUlwLoopSessionIds(repoRoot));
+        throw new UlwLoopError(`No ulw-loop plan found at ${repoRelative(path, repoRoot)}.\n${recovery.message}`, "ULW_LOOP_PLAN_MISSING", { cause: error, ...(recovery.details === undefined ? {} : { details: recovery.details }) });
     }
     const parsed = JSON.parse(raw);
     if (parsed.version !== 1 || !Array.isArray(parsed.goals)) {
@@ -56,6 +68,11 @@ export async function readUlwLoopPlan(repoRoot, scope) {
     const previousObjective = parsed.codexObjective;
     if ((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])];
@@ -71,6 +88,19 @@ export async function readUlwLoopPlan(repoRoot, scope) {
     }
     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) {
+    try {
+        return readdirSync(ulwLoopDir(repoRoot), { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
 export async function writePlan(repoRoot, plan, scope) {
     await mkdir(ulwLoopDir(repoRoot, scope), { recursive: true });
     const path = ulwLoopGoalsPath(repoRoot, scope);

package/packages/omo-codex/plugin/components/ulw-loop/dist/plan-missing-recovery.d.ts

@@ -0,0 +1,14 @@
+export declare 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 declare function planMissingRecovery(existingSessionIds: readonly string[]): PlanMissingRecovery;
+export declare function sessionScopeRequiredMessage(flag: string, existingSessionIds: readonly string[]): string;
+export declare function sessionIdRequiredMessage(flag: string): string;

package/packages/omo-codex/plugin/components/ulw-loop/dist/plan-missing-recovery.js

@@ -0,0 +1,29 @@
+export const ULW_LOOP_CREATE_GOALS_COMMAND = 'omo-agent-toolkit ulw-loop create-goals --brief "<brief>" --json';
+/**
+ * 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) {
+    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, existingSessionIds) {
+    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) {
+    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/dist/quality-gate-aggregate.d.ts

@@ -0,0 +1,7 @@
+import type { ValidateQualityGateOptions } 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 declare function aggregateQualityGateDefects(input: unknown, opts: ValidateQualityGateOptions | undefined): void;

package/packages/omo-codex/plugin/components/ulw-loop/dist/quality-gate-aggregate.js

@@ -0,0 +1,9 @@
+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, opts) {
+    validateQualityGate(input, opts);
+}

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

@@ -0,0 +1,12 @@
+import type { ValidateQualityGateOptions } from "./quality-gate.js";
+import type { UlwLoopManualQaArtifactKind, UlwLoopManualQaArtifactRef, UlwLoopManualQaSurface } from "./types.js";
+export declare const SUPPORTED_SURFACES: readonly UlwLoopManualQaSurface[];
+export declare const SUPPORTED_KINDS: readonly UlwLoopManualQaArtifactKind[];
+export declare function surfaceField(value: unknown, field: string): UlwLoopManualQaSurface;
+export declare function kindField(value: unknown, field: string): UlwLoopManualQaArtifactKind;
+export declare function compatibleKindsFor(surface: UlwLoopManualQaSurface): readonly UlwLoopManualQaArtifactKind[];
+export declare function artifactCompatible(surface: UlwLoopManualQaSurface, kind: UlwLoopManualQaArtifactKind): boolean;
+export declare function checkFile(path: string, field: string, opts?: ValidateQualityGateOptions): void;
+export declare function artifactMap(refs: readonly UlwLoopManualQaArtifactRef[]): Map<string, UlwLoopManualQaArtifactRef>;
+export declare function parseArtifactRefs(value: unknown, opts?: ValidateQualityGateOptions): readonly UlwLoopManualQaArtifactRef[];
+export declare function referencedArtifacts(value: unknown, field: string, byId: ReadonlyMap<string, UlwLoopManualQaArtifactRef>): readonly UlwLoopManualQaArtifactRef[];

package/packages/omo-codex/plugin/components/ulw-loop/dist/quality-gate-artifacts.js

@@ -0,0 +1,104 @@
+import { resolve } from "node:path";
+import { isWithinAttemptDir } from "./paths.js";
+import { invalid, isPoisoned, markPoisonedArtifactKind, section, stringArray, textField, } from "./quality-gate-fields.js";
+export const SUPPORTED_SURFACES = ["cli", "http", "tmux", "browser", "gui", "data"];
+export const SUPPORTED_KINDS = [
+    "cli-transcript",
+    "log",
+    "screenshot",
+    "image",
+    "http-dump",
+    "data-diff",
+];
+const COMPATIBLE_KINDS = {
+    cli: ["cli-transcript", "log"],
+    tmux: ["cli-transcript", "log"],
+    http: ["http-dump"],
+    browser: ["screenshot", "image"],
+    gui: ["screenshot", "image"],
+    data: ["data-diff"],
+};
+function isSupportedSurface(value) {
+    return SUPPORTED_SURFACES.some((surface) => surface === value);
+}
+function isSupportedKind(value) {
+    return SUPPORTED_KINDS.some((kind) => kind === value);
+}
+export function surfaceField(value, field) {
+    if (isSupportedSurface(value))
+        return value;
+    invalid(`${field} must be a supported manual QA surface (${SUPPORTED_SURFACES.join(", ")}).`, field);
+    return "cli";
+}
+export function kindField(value, field) {
+    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) {
+    return COMPATIBLE_KINDS[surface];
+}
+export function artifactCompatible(surface, kind) {
+    return compatibleKindsFor(surface).includes(kind);
+}
+export function checkFile(path, field, opts) {
+    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) {
+    const byId = new Map();
+    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, opts) {
+    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, field, byId) {
+    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/dist/quality-gate-fields.d.ts

@@ -1,4 +1,15 @@
-export declare function invalid(message: string, field: string): never;
+type QualityGateDefect = {
+    readonly field: string;
+    readonly message: string;
+};
+/** A recorded defect poisons only its field; consumers skip dependent checks while preserving valid siblings and entry identity. */
+export declare function withQualityGateCollector<T>(operation: () => T): T;
+export declare function throwQualityGateDefects(defects: readonly QualityGateDefect[]): never;
+export declare function invalid(message: string, field: string): undefined;
+export declare function isPoisoned(field: string): boolean;
+export declare function poisonField(field: string): void;
+export declare function markPoisonedArtifactKind(id: string): void;
+export declare function isPoisonedArtifactKind(id: string): boolean;
 export declare function isRecord(value: unknown): value is Record<string, unknown>;
 export declare function section(value: unknown, field: string): Record<string, unknown>;
 export declare function textField(value: unknown, field: string): string;
@@ -6,3 +17,4 @@ export declare function numberField(value: unknown, field: string): number;
 export declare function stringArray(value: unknown, field: string): readonly string[];
 export declare function emptyBlockers(value: unknown, field: string): readonly [];
 export declare function literal<T extends string | boolean>(value: unknown, expected: T, field: string): T;
+export {};