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

package/packages/omo-codex/plugin/components/ulw-loop/README.md

@@ -21,7 +21,17 @@ Every subcommand below is implemented. Pass `--json` where supported for machine
 | `omo-agent-toolkit ulw-loop record-evidence` | Record observable evidence for one criterion. |
 | `omo-agent-toolkit ulw-loop record-review-blockers` | Mark a goal as review-blocked and add follow-up work from final-review findings. |
 
-The final quality gate parsed by `checkpoint` validates `codeReview`, `manualQa`, `gateReview`, `iteration`, and `criteriaCoverage`. `criteriaCoverage` records the original intent, desired outcome, user-facing outcome review, pass counts, and covered adversarial classes.
+The final quality gate parsed by `checkpoint` requires `manualQa`, `gateReview`, `iteration`, and `criteriaCoverage`; lazycodex accepts optional `codeReview`. Lazycodex defaults to `main-session` self-review, with `category:*` and reviewer acceptors available when needed. `criteriaCoverage` records the original intent, desired outcome, user-facing outcome review, pass counts, and covered adversarial classes. The companion `codex-goal-json` must contain `goal.objective` equal to the plan's `codexObjective` verbatim.
+
+A complete passing checkpoint uses both payloads:
+
+```json
+{"goal":{"objective":"Ship the requested behavior","status":"complete"}}
+```
+
+```json
+{"gateReview":{"by":"main-session","recommendation":"APPROVE","reportPath":".omo/evidence/gate-review.md","evidence":"Gate review passed.","blockers":[],"notes":[]},"manualQa":{"by":"lazycodex-qa-executor","status":"passed","evidence":"Manual QA passed.","surfaceEvidence":[{"id":"cli","criterionRef":"C1","surface":"cli","invocation":"omo-agent-toolkit ulw-loop checkpoint --json","verdict":"passed","artifactRefs":["cli-artifact"]}],"adversarialCases":[{"id":"malformed","criterionRef":"C2","scenario":"Malformed input","expectedBehavior":"Rejected","verdict":"not_applicable","reason":"Not triggered","artifactRefs":["cli-artifact"]}],"artifactRefs":[{"id":"cli-artifact","kind":"cli-transcript","description":"Passing CLI transcript","path":".omo/evidence/cli.txt"}]},"codeReview":{"by":"lazycodex-code-reviewer","recommendation":"APPROVE","codeQualityStatus":"CLEAR","reportPath":".omo/evidence/code-review.md","evidence":"Code review passed.","blockers":[]},"iteration":{"fullRerun":true,"status":"passed","rerunCommands":["bun test"],"evidence":"Full rerun passed."},"criteriaCoverage":{"totalCriteria":2,"passCount":2,"originalIntent":"Ship the requested behavior","desiredOutcome":"The behavior works for users.","userOutcomeReview":"The result matches the requested outcome.","adversarialClassesCovered":["malformed_input"]}}
+```
 
 Validation batches are optional review boundaries declared at plan creation with `--validation-batch-json '[{"batchId":"VB001","memberIds":[...],"finalGoalId":"..."}]'`. The batch-final goal cannot complete until every other member is complete or superseded-resolved, every member criterion is pass, and a quality gate's coverage counts match the recomputed member criteria. Steering split/supersede mutations keep batch membership consistent and record `batch_updated`.
 
@@ -35,6 +45,7 @@ This directory is a component of the aggregate `@sisyphuslabs/omo-codex-plugin`
   - `PreToolUse` matching the spawn tool tokens -> `node "${PLUGIN_ROOT}/dist/cli.js" hook pre-tool-use-spawn` (fan-out cap + gate-artifact preflight)
   - `Stop` -> `node "${PLUGIN_ROOT}/dist/cli.js" hook stop` (auto-resume with a two-strike no-progress cap)
 - `skills/ulw-loop/` for the bundled `ulw-loop` skill.
+- `directive.md`, the ultrawork directive read at runtime when `--with-ultrawork` falls back to the full text. This package is published standalone and takes no dependency on `@oh-my-opencode/prompts-core`, so it intentionally bundles its own byte-identical copy of the canonical `packages/prompts-core/prompts/ultrawork/codex.md`. The copy is generated by `components/ultrawork/scripts/sync-directive.mjs` and pinned byte-for-byte by `test/ultrawork-directive.test.ts`; do not hand-edit it.
 - `bin.omo-ulw-loop` -> `dist/cli.js` for standalone CLI invocation.
 
 This component ships a CLI, a skill, and hooks. It does not expose an MCP server.

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

@@ -1,9 +1,9 @@
 {
-	"$schema": "https://biomejs.dev/schemas/2.4.16/schema.json",
+	"$schema": "https://biomejs.dev/schemas/2.5.9/schema.json",
 	"linter": {
 		"enabled": true,
 		"rules": {
-			"recommended": true,
+			"preset": "recommended",
 			"style": {
 				"noDefaultExport": "error",
 				"noEnum": "error",

package/packages/omo-codex/plugin/components/ulw-loop/directive.md

@@ -46,8 +46,8 @@ first-class for CLI- or data-shaped work; self-review recorded in the
 notepad instead of the reviewer loop.
 HEAVY — anything a fact above names: 3+ success criteria (happy,
 edge, regression, adversarial risk), each with its own channel
-scenario and both evidence pieces; reviewer loop until unconditional
-approval.
+scenario and both evidence pieces; when the verification gate is
+triggered, run the reviewer loop until unconditional approval.
 
 # Manual-QA channels
 Run real-surface proof yourself through the channel that faithfully
@@ -66,7 +66,13 @@ exercises the surface; capture the artifact.
      if Chrome is not available, download and use agent-browser
      (https://github.com/vercel-labs/agent-browser). Capture action
      log + screenshot path. Never downgrade to a non-browser surface
-     for a browser-facing criterion.
+     for a browser-facing criterion. NEVER clear cookies, cache, or
+     site data (`Network.clearBrowserCookies`, `Storage.clearCookies`,
+     `chrome.browsingData.remove`, "clear browsing data") on the user's
+     real/main browser profile — it wipes their logged-in state. If you
+     need that profile's login state, clone it first (`rsync -a
+     <profile>/ <tmp-clone>/`) and launch Chrome / agent-browser against
+     the clone as the user-data-dir; run any clearing there only.
   4. Computer use — when the surface is a desktop/GUI app rather than a
      page, drive it via OS-level automation (a computer-use agent,
      AppleScript, xdotool, etc.) against the running app; capture
@@ -126,6 +132,12 @@ exactly `objective`; do not include `status`. Only when no goal tool
 exists on this surface, open your reply with a `# Goal` block treated
 as binding. Goals are unlimited; never invent a numeric budget or
 limit.
+Check `get_goal` first: continue a matching active goal instead of
+duplicating one; surface a conflicting one. Write the objective
+outcome-first: the concrete thing that will be TRUE when done (an
+outcome, never an activity), the named deliverable surfaces, and
+explicit scope bounds — a vague objective produces vague criteria,
+and vague criteria cannot be proven.
 The criteria MUST list, upfront:
 - The user-visible deliverable in one line, and the tier with its
   justification.
@@ -217,8 +229,8 @@ and utility functions to batch commands and reduce output. Keep direct calls
 when one result chooses the next action, outputs are already small, semantic
 judgment is required between calls, approval or side effects are involved,
 or native artifacts / citations must be preserved.
-- Architecture / flow / blast radius → `codegraph_explore` first when
-  `codegraph_*` exists; if unavailable, continue with repo tools and LSP.
+- Architecture / flow / blast radius → explore agents plus LSP references
+  and impact; do not guess from conventions.
 - **SYMBOLS REQUIRE LSP** — definitions, references, rename impact,
   workspace symbols, and diagnostics use the available `lsp_*` tools, not
   text search. Run diagnostics after edits and treat errors as blocking.
@@ -373,16 +385,17 @@ BLOCKED: <reason>`. After four silent or ack-only checks, close the lane as
 inconclusive, record that it is not approval, and respawn smaller only
 if the deliverable is still required.
 
-# Verification gate (TRIGGERED, NOT OPTIONAL)
+# Verification gate (TRIGGERED ONLY ON EXPLICIT DEMAND)
 
-Trigger when ANY apply:
-- Tier is HEAVY.
-- User demanded strict, rigorous, or proper review.
-LIGHT tier records a self-review in the notepad instead: re-read the
-diff, run diagnostics, confirm each criterion's evidence, and state in
-one line why the tier held.
+Trigger ONLY when the user explicitly demanded strict, rigorous, proper,
+or high-accuracy review of this work, in any language (for example,
+고정밀 or 엄격). The tier alone never triggers the gate. HEAVY without
+such a demand records the same self-review as LIGHT.
+LIGHT and non-triggered HEAVY work records a self-review in the notepad
+instead: re-read the diff, run diagnostics, confirm each criterion's
+evidence, and state in one line why the tier held.
 
-Procedure (NON-NEGOTIABLE):
+When triggered, follow this procedure (NON-NEGOTIABLE):
 1. Spawn a child with `fork_context: false` and a self-contained reviewer
    assignment in `message`. The `multi_agent_v1.spawn_agent` schema cannot select a
    TOML-backed reviewer role, so paste the reviewer requirements into

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

@@ -0,0 +1,12 @@
+import type { UlwLoopScope } from "./paths.js";
+import type { UlwLoopItem, UlwLoopPlan } from "./types.js";
+import { UlwLoopError } from "./types.js";
+export declare function validateCheckpointCodexGoal(input: {
+    readonly repoRoot: string;
+    readonly plan: UlwLoopPlan;
+    readonly goal: UlwLoopItem;
+    readonly raw: string | undefined;
+    readonly evidence: string;
+    readonly scope?: UlwLoopScope;
+}): Promise<unknown>;
+export declare function combineCheckpointValidationErrors(codexError: UlwLoopError, gateError: UlwLoopError): UlwLoopError;

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

@@ -0,0 +1,45 @@
+import { canReconcileActiveFinalTaskScopedAggregateSnapshot, canReconcileCompletedTaskScopedAggregateSnapshot, codexSnapshotMismatchError, } from "./checkpoint-reconciliation.js";
+import { readCodexGoalSnapshotInput, reconcileCodexGoalSnapshot } from "./codex-goal-snapshot.js";
+import { codexGoalMode, compatibleCodexObjectives, expectedCodexObjective, isFinalRunCompletionCandidate, } from "./goal-status.js";
+import { UlwLoopError } from "./types.js";
+function normalizeObjective(value) {
+    return value.replace(/\s+/g, " ").trim();
+}
+export async function validateCheckpointCodexGoal(input) {
+    const aggregate = codexGoalMode(input.plan) === "aggregate";
+    const final = isFinalRunCompletionCandidate(input.plan, input.goal);
+    const snapshot = await readCodexGoalSnapshotInput(input.raw, input.repoRoot);
+    const expectedObjective = expectedCodexObjective(input.plan, input.goal);
+    const reconciliation = reconcileCodexGoalSnapshot(snapshot, {
+        expectedObjective,
+        ...(aggregate ? { acceptedObjectives: compatibleCodexObjectives(input.plan) } : {}),
+        allowedStatuses: aggregate ? (final ? ["complete"] : ["active"]) : ["complete"],
+        requireSnapshot: true,
+        requireComplete: !aggregate || final,
+    });
+    if (reconciliation.ok)
+        return reconciliation.snapshot.raw;
+    const objective = snapshot?.objective;
+    const mismatchedTaskObjective = snapshot?.available === true &&
+        objective !== undefined &&
+        normalizeObjective(objective) !== normalizeObjective(expectedObjective);
+    const completedTaskScoped = mismatchedTaskObjective &&
+        snapshot.status === "complete" &&
+        (await canReconcileCompletedTaskScopedAggregateSnapshot(input.repoRoot, input.plan, input.goal, objective, input.evidence, input.scope));
+    const activeFinalTaskScoped = mismatchedTaskObjective &&
+        snapshot.status === "active" &&
+        (await canReconcileActiveFinalTaskScopedAggregateSnapshot(input.repoRoot, input.plan, input.goal, objective, input.evidence, input.scope));
+    if (completedTaskScoped || activeFinalTaskScoped)
+        return reconciliation.snapshot.raw;
+    throw codexSnapshotMismatchError({
+        reconciliation,
+        snapshot,
+        expectedObjective,
+        taskScopedHint: { goal: input.goal, aggregate, final },
+    });
+}
+export function combineCheckpointValidationErrors(codexError, gateError) {
+    return new UlwLoopError(`${codexError.message}\n${gateError.message}`, "ULW_LOOP_QUALITY_GATE_INVALID", {
+        details: { ...(codexError.details ?? {}), ...(gateError.details ?? {}) },
+    });
+}

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

@@ -1,4 +1,5 @@
 import { checkpointUlwLoop } from "./checkpoint.js";
+import { checkpointTemplate } from "./checkpoint-template.js";
 import { hasFlag, parseCodexGoalJson, readValue } from "./cli-arg-parser.js";
 import { blockedDecisionHandoff, printJson } from "./cli-output.js";
 import { buildCodexGoalInstruction } from "./codex-goal-instruction.js";
@@ -15,6 +16,14 @@ export async function checkpointAndContinue(repoRoot, args, scope) {
     return { ...result, plan: next.plan, next: { resumed: next.resumed, goal: next.goal, instruction } };
 }
 export async function checkpoint(repoRoot, argv, json, scope) {
+    if (hasFlag(argv, "--print-template")) {
+        const template = await checkpointTemplate(repoRoot, scope, readValue(argv, "--goal-id"));
+        if (json)
+            printJson({ ok: true, ...template });
+        else
+            printJson(template);
+        return 0;
+    }
     const goalId = required(argv, "--goal-id");
     const statusValue = checkpointStatus(required(argv, "--status"));
     const evidence = required(argv, "--evidence");

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

@@ -1,5 +1,20 @@
+import type { CodexGoalReconciliation, CodexGoalSnapshot } from "./codex-goal-snapshot.js";
 import { type UlwLoopScope } from "./paths.js";
 import type { UlwLoopItem, UlwLoopPlan } from "./types.js";
+import { UlwLoopError } from "./types.js";
+export interface CodexSnapshotMismatchInput {
+    readonly reconciliation: CodexGoalReconciliation;
+    readonly snapshot: CodexGoalSnapshot | null | undefined;
+    readonly expectedObjective: string;
+    /** Only the checkpoint path can fall back to task-scoped aggregate reconciliation, so only it asks for that hint. */
+    readonly taskScopedHint?: {
+        readonly goal: UlwLoopItem;
+        readonly aggregate: boolean;
+        readonly final: boolean;
+    };
+}
+export declare function combineCheckpointValidationErrors(codexError: UlwLoopError, gateError: UlwLoopError): UlwLoopError;
+export declare function codexSnapshotMismatchError(input: CodexSnapshotMismatchInput): UlwLoopError;
 export declare function canReconcileCompletedTaskScopedAggregateSnapshot(repoRoot: string, plan: UlwLoopPlan, goal: UlwLoopItem, snapshotObjective: string, evidence: string, scope?: UlwLoopScope): Promise<boolean>;
 export declare function canReconcileActiveFinalTaskScopedAggregateSnapshot(repoRoot: string, plan: UlwLoopPlan, goal: UlwLoopItem, snapshotObjective: string, evidence: string, scope?: UlwLoopScope): Promise<boolean>;
 export declare function buildTaskScopedAggregateReconciliationHint(goal: UlwLoopItem, final: boolean): string;

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

@@ -1,8 +1,22 @@
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
+import { codexGoalMismatchRecovery, formatCodexGoalReconciliation } from "./codex-goal-snapshot.js";
 import { codexGoalMode, isFinalRunCompletionCandidate } from "./goal-status.js";
 import { ulwLoopBriefPath } from "./paths.js";
-import { ULW_LOOP_DIR, ULW_LOOP_GOALS, ULW_LOOP_LEDGER } from "./types.js";
+import { ULW_LOOP_DIR, ULW_LOOP_GOALS, ULW_LOOP_LEDGER, UlwLoopError } from "./types.js";
+export function combineCheckpointValidationErrors(codexError, gateError) {
+    return new UlwLoopError(`${codexError.message}\n${gateError.message}`, "ULW_LOOP_QUALITY_GATE_INVALID", {
+        details: { ...(codexError.details ?? {}), ...(gateError.details ?? {}) },
+    });
+}
+export function codexSnapshotMismatchError(input) {
+    const { reconciliation, snapshot, taskScopedHint } = input;
+    const hint = taskScopedHint?.aggregate === true && snapshot?.status === "complete" && snapshot.objective !== undefined
+        ? buildTaskScopedAggregateReconciliationHint(taskScopedHint.goal, taskScopedHint.final)
+        : "";
+    const recovery = codexGoalMismatchRecovery(input.expectedObjective, snapshot);
+    return new UlwLoopError(`${formatCodexGoalReconciliation(reconciliation)}${hint}\n${recovery.message}`, "ulw_loop_codex_snapshot_mismatch", { details: recovery.details });
+}
 function normalizeObjective(value) {
     return value.replace(/\s+/g, " ").trim();
 }

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

@@ -0,0 +1,8 @@
+import { type UlwLoopScope } from "./paths.js";
+export interface CheckpointTemplate {
+    readonly qualityGateTemplate: Record<string, unknown>;
+    readonly codexGoalTemplate: Record<string, unknown>;
+    readonly attemptDir?: string;
+    readonly guidance?: string;
+}
+export declare function checkpointTemplate(repoRoot: string, scope?: UlwLoopScope, goalId?: string): Promise<CheckpointTemplate>;

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

@@ -0,0 +1,113 @@
+import { ulwLoopAttemptEvidenceDir } from "./paths.js";
+import { readUlwLoopPlan } from "./plan-io.js";
+import { resolveToolkitSurface } from "./surface.js";
+import { UlwLoopError } from "./types.js";
+function artifactPath(base, name) {
+    return `${base}/${name}`;
+}
+function gateTemplate(surface, base) {
+    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" : "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, scope, goalId) {
+    const plan = await readUlwLoopPlan(repoRoot, scope);
+    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","recommendation":"APPROVE","evidence":"review passed","reportPath":"<attemptDir>/gate-review.md","blockers":[],"notes":[]}, manualQa.artifactRefs objects, iteration, and criteriaCoverage.',
+        ...(resolveToolkitSurface() === "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, 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(resolveToolkitSurface(), attemptDir),
+        codexGoalTemplate: {
+            goal: { objective: plan.codexObjective ?? "<replace:codex objective>", status: "complete" },
+        },
+        guidance,
+        ...(hasAttempt ? { attemptDir } : {}),
+    };
+}

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

@@ -2,22 +2,19 @@
 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";
+import { combineCheckpointValidationErrors, validateCheckpointCodexGoal, } from "./checkpoint-codex-validation.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 { ulwLoopAttemptEvidenceDir } from "./paths.js";
 import { appendLedger, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
 import { classifyExternalAuthorizationBlocker, clearGoalBlockerFields, sameBlockerOccurrences, validateQualityGate, } from "./quality-gate.js";
+import { resolveToolkitSurface } from "./surface.js";
 import { iso, UlwLoopError } from "./types.js";
 import { batchClosedBy, requireAllValidationBatchesClosed, requireBatchFinalReady, requireBatchGate } from "./validation-batch.js";
 const QUALITY_GATE_FS = { existsSync, statSync };
 function ulwLoopFail(message, code) {
     throw new UlwLoopError(message, code);
 }
-function normalizeObjective(value) {
-    return value.replace(/\s+/g, " ").trim();
-}
 function nonEmptyEvidence(value) {
     const trimmed = value.trim();
     return trimmed || ulwLoopFail("Evidence must be a non-empty string.", "ulw_loop_evidence_required");
@@ -82,13 +79,15 @@ function ledgerKind(status, goal, aggregateCompletion) {
     return status === "blocked" ? "goal_blocked" : "goal_failed";
 }
 function buildLedger(now, args, goal, qualityGate, codexGoal, aggregateCompletion) {
-    const watch = qualityGate?.codeReview.codeQualityStatus === "WATCH";
+    const watch = qualityGate?.surface === "lazycodex" && qualityGate.codeReview?.codeQualityStatus === "WATCH";
     const entry = {
         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;
@@ -124,29 +123,21 @@ export async function checkpointUlwLoop(repoRoot, args, scope) {
                 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;
+            try {
+                codexGoal = await validateCheckpointCodexGoal({
+                    repoRoot,
+                    plan,
+                    goal,
+                    raw: args.codexGoalJson,
+                    evidence,
+                    ...(scope === undefined ? {} : { scope }),
+                });
+            }
+            catch (error) {
+                if (!(error instanceof UlwLoopError))
+                    throw error;
+                codexValidationError = error;
             }
             if (closesBatch)
                 requireBatchFinalReady(plan, goal);
@@ -155,15 +146,25 @@ export async function checkpointUlwLoop(repoRoot, args, scope) {
             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: 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;

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

@@ -1,8 +1,10 @@
 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, completeGoals, createGoals, criteria, reviewBlockers, status, steer, } from "./cli-subcommands.js";
 import { resolveUlwLoopSessionIdFromEnv } 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 = [
     "help",
@@ -26,7 +28,6 @@ export async function ulwLoopCommand(argv) {
     const repoRoot = process.cwd();
     const json = hasFlag(rest, "--json");
     try {
-        const scope = commandScope(rest);
         if (!isUlwLoopSubcommand(command)) {
             if (json) {
                 printJsonError(new UlwLoopError(`Unknown ulw-loop subcommand: ${command}.`, "ULW_LOOP_SUBCOMMAND_UNKNOWN", {
@@ -37,10 +38,16 @@ export async function ulwLoopCommand(argv) {
             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":
@@ -84,16 +91,22 @@ const SESSION_ID_FLAG = "--session-id";
 function sessionIdFlagPresent(argv) {
     return hasFlag(argv, SESSION_ID_FLAG) || argv.some((arg) => arg.startsWith(`${SESSION_ID_FLAG}=`));
 }
-function commandScope(argv) {
+// 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, argv) {
     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/dist/cli-output.d.ts

@@ -1,5 +1,6 @@
 import type { UlwLoopCodexGoalMode, UlwLoopPlan } from "./types.js";
-export declare const ULW_LOOP_HELP = "Usage:\n  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]\n  omo-agent-toolkit ulw-loop status [--json]\n  omo-agent-toolkit ulw-loop complete-goals [--retry-failed] [--json]\n  omo-agent-toolkit ulw-loop criteria --goal-id <id> [--json]\n  omo-agent-toolkit ulw-loop record-evidence --goal-id <id> --criterion-id <id> --status pass|fail|blocked --evidence \"...\" [--notes \"...\"] [--json]\n  omo-agent-toolkit ulw-loop checkpoint --goal-id <id> --status complete|failed|blocked --evidence \"...\" --codex-goal-json <...> [--quality-gate-json <...>] [--no-advance] [--json]\n  omo-agent-toolkit ulw-loop steer --kind <kind> ... --evidence \"...\" --rationale \"...\" [--proposals-json <json-or-path>] [--json]\n  omo-agent-toolkit ulw-loop add-goal --title \"...\" --objective \"...\" [--json]\n  omo-agent-toolkit ulw-loop record-review-blockers --goal-id <id> --title \"...\" --objective \"...\" --evidence \"...\" --codex-goal-json <...> [--json]\n\nAll subcommands accept [--session-id <id>] to isolate state under .omo/ulw-loop/<id>/; without it, Codex session env is used when present.";
+export declare const ULW_LOOP_HELP = "Usage:\n  omo-agent-toolkit hook user-prompt-submit [--with-ultrawork]  (Codex UserPromptSubmit hook)\n  omo-agent-toolkit help | --help | -h                          (this message)\n  omo-agent-toolkit ulw-loop help\n  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]\n  omo-agent-toolkit ulw-loop status [--json]\n  omo-agent-toolkit ulw-loop complete-goals [--retry-failed] [--json]\n  omo-agent-toolkit ulw-loop criteria --goal-id <id> [--json]\n  omo-agent-toolkit ulw-loop record-evidence --goal-id <id> --criterion-id <id> --status pass|fail|blocked --evidence \"...\" [--notes \"...\"] [--json]\n  omo-agent-toolkit ulw-loop checkpoint --print-template [--goal-id <id>] [--json]\n  omo-agent-toolkit ulw-loop checkpoint --goal-id <id> --status complete|failed|blocked --evidence \"...\" --codex-goal-json <...> [--quality-gate-json <...>] [--no-advance] [--json]\n  omo-agent-toolkit ulw-loop steer --kind <kind> ... --evidence \"...\" --rationale \"...\" [--proposals-json <json-or-path>] [--json]\n  omo-agent-toolkit ulw-loop add-goal --title \"...\" --objective \"...\" [--json]\n  omo-agent-toolkit ulw-loop record-review-blockers --goal-id <id> --title \"...\" --objective \"...\" --evidence \"...\" --codex-goal-json <...> [--json]\n\nEvery 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.\nEvery subcommand accepts --help | -h to print its own usage line.";
+export declare function subcommandHelp(subcommand: string): string;
 export declare function printJson(value: unknown): void;
 export declare function printJsonError(error: unknown): void;
 export declare function printStatus(plan: UlwLoopPlan): void;

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

@@ -1,16 +1,27 @@
 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) {
+    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");
+}
 export function printJson(value) {
     process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }

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

@@ -9,6 +9,7 @@ import { 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 { statusNextActions } from "./status-next-actions.js";
 import { steerUlwLoop } from "./steering.js";
 import { steerUlwLoopBatch } from "./steering-batch.js";
 import { UlwLoopError } from "./types.js";
@@ -47,6 +48,7 @@ export async function status(repoRoot, json, scope) {
             plan,
             summary: summarizeUlwLoopPlan(plan),
             ...(currentAttemptDir === undefined ? {} : { currentAttemptDir }),
+            nextActions: statusNextActions(plan),
         });
     }
     else