oh-my-opencode 5.0.0-beta.31 → 5.0.0-beta.32

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

@@ -1,17 +1,124 @@
 #!/usr/bin/env node
 
-// packages/omo-codex/plugin/components/ulw-loop/src/checkpoint.ts
+// components/ulw-loop/src/checkpoint.ts
 import { existsSync as existsSync4, statSync } from "node:fs";
 import { readFile as readFile5 } from "node:fs/promises";
-import { resolve as resolve3 } from "node:path";
+import { resolve as resolve4 } from "node:path";
+
+// components/ulw-loop/src/checkpoint-reconciliation.ts
+import { existsSync as existsSync2 } from "node:fs";
+import { readFile as readFile2 } from "node:fs/promises";
 
-// packages/omo-codex/plugin/components/ulw-loop/src/checkpoint-reconciliation.ts
+// components/ulw-loop/src/codex-goal-snapshot.ts
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+class CodexGoalSnapshotError extends Error {
+}
+function safeObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function safeString(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+function normalizeStatus(value) {
+  const status = safeString(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 === "active" || status === "in_progress" || status === "pending" || status === "running")
+    return "active";
+  return "unknown";
+}
+function normalizeObjective(value) {
+  return value.replace(/\s+/g, " ").trim();
+}
+function parseCodexGoalSnapshot(value) {
+  const root = safeObject(value);
+  const goalValue = Object.hasOwn(root, "goal") ? root["goal"] : value;
+  if (goalValue === null || goalValue === undefined || goalValue === false) {
+    return { available: false, raw: value };
+  }
+  const goal = safeObject(goalValue);
+  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"),
+    ...objective ? { objective } : {},
+    status,
+    raw: value
+  };
+}
+async function readCodexGoalSnapshotInput(raw, cwd = process.cwd()) {
+  if (!raw?.trim())
+    return null;
+  const trimmed = raw.trim();
+  try {
+    return parseCodexGoalSnapshot(JSON.parse(trimmed));
+  } catch {
+    const path = resolve(cwd, trimmed);
+    if (!existsSync(path)) {
+      throw new CodexGoalSnapshotError(`Codex goal snapshot is neither valid JSON nor a readable path: ${trimmed}`);
+    }
+    try {
+      return parseCodexGoalSnapshot(JSON.parse(await readFile(path, "utf-8")));
+    } catch (error) {
+      throw new CodexGoalSnapshotError(`Codex goal snapshot path does not contain valid JSON: ${trimmed}${error instanceof Error ? ` (${error.message})` : ""}`);
+    }
+  }
+}
+function reconcileCodexGoalSnapshot(snapshot, options) {
+  const effectiveSnapshot = snapshot ?? { available: false, raw: null };
+  const errors = [];
+  const warnings = [];
+  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);
+    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 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}".`);
+  }
+  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.');
+  }
+  return { ok: errors.length === 0, snapshot: effectiveSnapshot, warnings, errors };
+}
+function formatCodexGoalReconciliation(reconciliation) {
+  const parts = [...reconciliation.errors, ...reconciliation.warnings];
+  return parts.join(" ");
+}
+function codexGoalMismatchRecovery(expectedObjective, snapshot) {
+  const receivedObjective = snapshot?.objective ?? "";
+  const message = [
+    "Recovery: the Codex goal objective must equal the plan's codexObjective exactly — copy the expected value below into update_goal and re-run get_goal.",
+    `expected codexObjective: ${expectedObjective}`,
+    `received objective: ${receivedObjective || "(none)"}`
+  ].join(`
+`);
+  return { message, details: { expectedObjective, receivedObjective } };
+}
 
-// packages/omo-codex/plugin/components/ulw-loop/src/paths.ts
+// components/ulw-loop/src/paths.ts
 import { isAbsolute, join, relative, sep } from "node:path";
-// packages/omo-codex/plugin/components/ulw-loop/src/constants.ts
+// components/ulw-loop/src/constants.ts
 var ULW_LOOP_DIR = ".omo/ulw-loop";
 var ULW_LOOP_BRIEF = "brief.md";
 var ULW_LOOP_GOALS = "goals.json";
@@ -31,7 +138,7 @@ var ULW_LOOP_SUCCESS_CRITERION_USER_MODELS = [
   "regression",
   "adversarial"
 ];
-// packages/omo-codex/plugin/components/ulw-loop/src/runtime.ts
+// components/ulw-loop/src/runtime.ts
 class UlwLoopError extends Error {
   constructor(message, code, opts) {
     super(message, opts?.cause === undefined ? undefined : { cause: opts.cause });
@@ -45,7 +152,7 @@ class UlwLoopError extends Error {
 function iso() {
   return new Date().toISOString();
 }
-// packages/omo-codex/plugin/components/ulw-loop/src/paths.ts
+// components/ulw-loop/src/paths.ts
 var SESSION_ENV_KEYS = ["OMO_ULW_LOOP_SESSION_ID", "CODEX_SESSION_ID", "CODEX_THREAD_ID", "PI_SESSION_ID"];
 function normalizeUlwLoopSessionId(sessionId) {
   const trimmed = sessionId?.trim();
@@ -111,7 +218,7 @@ function isWithinAttemptDir(absolutePath, attemptRoot, pathApi = PLATFORM_PATH_A
   return !pathApi.isAbsolute(relativePath);
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/goal-status.ts
+// components/ulw-loop/src/goal-status.ts
 var ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE = aggregateCodexObjectiveForScope();
 function aggregateCodexObjectiveForScope(scope) {
   return `Complete the durable ulw-loop plan in ${ulwLoopGoalsRelativePath(scope)}, including later accepted/appended stories, under the original brief constraints; use ${ulwLoopLedgerRelativePath(scope)} as the audit trail.`;
@@ -194,8 +301,15 @@ function hasEssentialCriteriaPass(goal) {
   return criteria.length > 0 && criteria.every((criterion) => criterion.status === "pass");
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/checkpoint-reconciliation.ts
-function normalizeObjective(value) {
+// components/ulw-loop/src/checkpoint-reconciliation.ts
+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}
+${recovery.message}`, "ulw_loop_codex_snapshot_mismatch", { details: recovery.details });
+}
+function normalizeObjective2(value) {
   return value.replace(/\s+/g, " ").trim();
 }
 function textMentionsUlwLoopPlanArtifact(value) {
@@ -212,13 +326,13 @@ function textHasCompletionValidationEvidence(value) {
   return done && verified;
 }
 async function snapshotObjectiveMapsToUlwLoopPlan(repoRoot, snapshotObjective, scope) {
-  const actual = normalizeObjective(snapshotObjective).toLowerCase();
+  const actual = normalizeObjective2(snapshotObjective).toLowerCase();
   if (textMentionsUlwLoopPlanArtifact(actual))
     return true;
-  if (actual.length < 24 || !existsSync(ulwLoopBriefPath(repoRoot, scope)))
+  if (actual.length < 24 || !existsSync2(ulwLoopBriefPath(repoRoot, scope)))
     return false;
   try {
-    const brief = normalizeObjective(await readFile(ulwLoopBriefPath(repoRoot, scope), "utf8")).toLowerCase();
+    const brief = normalizeObjective2(await readFile2(ulwLoopBriefPath(repoRoot, scope), "utf8")).toLowerCase();
     return brief.length >= 24 && (brief.includes(actual) || actual.includes(brief));
   } catch (error) {
     if (error instanceof Error)
@@ -265,107 +379,32 @@ function buildTaskScopedAggregateReconciliationHint(goal, final) {
   return ` Completed task-scoped aggregate reconciliation requires the checkpoint goal to be the active in-progress OMO goal, evidence that names that active OMO goal id, names .omo/ulw-loop/goals.json or ledger.jsonl, includes completed implementation plus validation/review evidence, and a get_goal objective that maps to the ulw-loop brief/artifact. ${buildCompletedLegacyGoalRemediation(goal)}`;
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/codex-goal-snapshot.ts
-import { existsSync as existsSync2 } from "node:fs";
-import { readFile as readFile2 } from "node:fs/promises";
-import { resolve } from "node:path";
+// components/ulw-loop/src/plan-io.ts
+import { createReadStream, readdirSync } from "node:fs";
+import { appendFile, mkdir, readFile as readFile3, rename, writeFile } from "node:fs/promises";
+import { createInterface } from "node:readline";
 
-class CodexGoalSnapshotError extends Error {
-}
-function safeObject(value) {
-  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
-}
-function safeString(value) {
-  return typeof value === "string" ? value.trim() : "";
-}
-function normalizeStatus(value) {
-  const status = safeString(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 === "active" || status === "in_progress" || status === "pending" || status === "running")
-    return "active";
-  return "unknown";
-}
-function normalizeObjective2(value) {
-  return value.replace(/\s+/g, " ").trim();
-}
-function parseCodexGoalSnapshot(value) {
-  const root = safeObject(value);
-  const goalValue = Object.hasOwn(root, "goal") ? root["goal"] : value;
-  if (goalValue === null || goalValue === undefined || goalValue === false) {
-    return { available: false, raw: value };
-  }
-  const goal = safeObject(goalValue);
-  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"),
-    ...objective ? { objective } : {},
-    status,
-    raw: value
-  };
-}
-async function readCodexGoalSnapshotInput(raw, cwd = process.cwd()) {
-  if (!raw?.trim())
-    return null;
-  const trimmed = raw.trim();
-  try {
-    return parseCodexGoalSnapshot(JSON.parse(trimmed));
-  } catch {
-    const path = resolve(cwd, trimmed);
-    if (!existsSync2(path)) {
-      throw new CodexGoalSnapshotError(`Codex goal snapshot is neither valid JSON nor a readable path: ${trimmed}`);
-    }
-    try {
-      return parseCodexGoalSnapshot(JSON.parse(await readFile2(path, "utf-8")));
-    } catch (error) {
-      throw new CodexGoalSnapshotError(`Codex goal snapshot path does not contain valid JSON: ${trimmed}${error instanceof Error ? ` (${error.message})` : ""}`);
-    }
-  }
-}
-function reconcileCodexGoalSnapshot(snapshot, options) {
-  const effectiveSnapshot = snapshot ?? { available: false, raw: null };
-  const errors = [];
-  const warnings = [];
-  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);
-    return { ok: errors.length === 0, snapshot: effectiveSnapshot, warnings, errors };
-  }
-  const expected = normalizeObjective2(options.expectedObjective);
-  const accepted = new Set([expected, ...(options.acceptedObjectives ?? []).map((objective) => normalizeObjective2(objective))].filter(Boolean));
-  const actual = normalizeObjective2(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}".`);
-  }
-  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.');
-  }
-  return { ok: errors.length === 0, snapshot: effectiveSnapshot, warnings, errors };
-}
-function formatCodexGoalReconciliation(reconciliation) {
-  const parts = [...reconciliation.errors, ...reconciliation.warnings];
-  return parts.join(" ");
+// components/ulw-loop/src/plan-missing-recovery.ts
+var ULW_LOOP_CREATE_GOALS_COMMAND = 'omo-agent-toolkit ulw-loop create-goals --brief "<brief>" --json';
+function planMissingRecovery(existingSessionIds) {
+  const lines = [`Recovery: bootstrap the plan with \`${ULW_LOOP_CREATE_GOALS_COMMAND}\`.`];
+  if (existingSessionIds.length === 0)
+    return { message: lines.join(`
+`) };
+  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(`
+`), details: { existingSessionIds } };
+}
+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(`
+`);
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/plan-io.ts
-import { createReadStream } from "node:fs";
-import { appendFile, mkdir, readFile as readFile3, rename, writeFile } from "node:fs/promises";
-import { createInterface } from "node:readline";
+// components/ulw-loop/src/plan-io.ts
 var LEGACY_OBJECTIVE_PREFIX = `Complete all ulw-loop stories in ${ULW_LOOP_DIR}/${ULW_LOOP_GOALS}: `;
 var 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.`;
 var locks = new Map;
@@ -406,7 +445,9 @@ 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(readSessionDirs(repoRoot));
+    throw new UlwLoopError(`No ulw-loop plan found at ${repoRelative(path, repoRoot)}.
+${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)) {
@@ -429,6 +470,13 @@ async function readUlwLoopPlan(repoRoot, scope) {
   }
   return parsed;
 }
+function readSessionDirs(repoRoot) {
+  try {
+    return readdirSync(ulwLoopDir(repoRoot), { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+  } catch {
+    return [];
+  }
+}
 async function writePlan(repoRoot, plan, scope) {
   await mkdir(ulwLoopDir(repoRoot, scope), { recursive: true });
   const path = ulwLoopGoalsPath(repoRoot, scope);
@@ -480,7 +528,7 @@ async function findAcceptedSteeringLedgerEntry(repoRoot, key, scope) {
   return;
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/evidence.ts
+// components/ulw-loop/src/evidence.ts
 function ulwLoopFail(message, code, details) {
   throw new UlwLoopError(message, code, { details });
 }
@@ -586,11 +634,11 @@ function requireEssentialCriteriaPass(goal) {
   });
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/quality-gate.ts
+// components/ulw-loop/src/quality-gate-aggregate.ts
 import { resolve as resolve2 } from "node:path";
 
-// packages/omo-codex/plugin/components/ulw-loop/src/quality-gate-fields.ts
-var PLACEHOLDER_PATTERN = /^(?:placeholder|todo|tbd|n\/a|stub)$/i;
+// components/ulw-loop/src/quality-gate-fields.ts
+var PLACEHOLDER_PATTERN = /^(?:<replace:[^>]+>|placeholder|todo|tbd|n\/a|stub)$/i;
 function invalid(message, field) {
   throw new UlwLoopError(message, "ULW_LOOP_QUALITY_GATE_INVALID", { details: { field } });
 }
@@ -627,7 +675,135 @@ function literal(value, expected, field) {
   invalid(`${field} must be ${String(expected)}.`, field);
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/quality-gate-verdicts.ts
+// components/ulw-loop/src/quality-gate-aggregate.ts
+var PLACEHOLDER = /^(?:<replace:[^>]+>|placeholder|todo|tbd|n\/a|stub)$/i;
+function add(defects, field, message) {
+  defects.push({ field, message });
+}
+function text(value, field, defects) {
+  if (typeof value !== "string" || value.trim() === "")
+    add(defects, field, `Final quality gate requires non-empty ${field}.`);
+  else if (PLACEHOLDER.test(value.trim()))
+    add(defects, field, `Final quality gate rejects placeholder ${field}.`);
+}
+function section2(value, field, defects) {
+  if (!isRecord(value)) {
+    add(defects, field, `Final quality gate is missing ${field} evidence.`);
+    return {};
+  }
+  return value;
+}
+function aggregateQualityGateDefects(input, opts) {
+  if (!isRecord(input))
+    return;
+  const defects = [];
+  const gate = input;
+  const manual = section2(gate["manualQa"], "manualQa", defects);
+  const review = section2(gate["gateReview"], "gateReview", defects);
+  text(manual["evidence"], "manualQa.evidence", defects);
+  text(review["evidence"], "gateReview.evidence", defects);
+  if (review["recommendation"] !== "APPROVE")
+    add(defects, "gateReview.recommendation", "gateReview.recommendation must be APPROVE.");
+  const artifacts = Array.isArray(manual["artifactRefs"]) ? manual["artifactRefs"] : [];
+  for (const [index, item] of artifacts.entries()) {
+    if (!isRecord(item))
+      continue;
+    const path = item["path"];
+    if (typeof path !== "string" || path.trim() === "")
+      continue;
+    if (opts?.repoRoot !== undefined && opts.fs !== undefined && !opts.fs.existsSync(resolve2(opts.repoRoot, path)))
+      add(defects, `manualQa.artifactRefs[${index}].path`, `manualQa.artifactRefs[${index}].path must point to an existing artifact.`);
+  }
+  if (defects.length === 0)
+    return;
+  const truncated = defects.length > 25;
+  const fields = defects.slice(0, 25).map(({ field, message: message2 }) => ({ field, message: message2 }));
+  const message = [
+    `Final quality gate has ${fields.length}${truncated ? "+" : ""} validation defects:`,
+    ...fields.map((item) => `- ${item.field}: ${item.message}`)
+  ].join(`
+`);
+  throw new UlwLoopError(message, "ULW_LOOP_QUALITY_GATE_INVALID", {
+    details: { field: fields[0]?.field, fields, ...truncated ? { truncated: true } : {} }
+  });
+}
+
+// components/ulw-loop/src/quality-gate-artifacts.ts
+import { resolve as resolve3 } from "node:path";
+function surfaceField(value, field) {
+  if (value === "cli" || value === "http" || value === "tmux" || value === "browser" || value === "gui" || value === "data")
+    return value;
+  invalid(`${field} must be a supported manual QA surface.`, field);
+}
+function kindField(value, field) {
+  if (value === "cli-transcript" || value === "log" || value === "screenshot" || value === "image" || value === "http-dump" || value === "data-diff")
+    return value;
+  invalid(`${field} must be a supported artifact kind.`, field);
+}
+function artifactCompatible(surface, kind) {
+  switch (surface) {
+    case "cli":
+    case "tmux":
+      return kind === "cli-transcript" || kind === "log";
+    case "http":
+      return kind === "http-dump";
+    case "browser":
+    case "gui":
+      return kind === "screenshot" || kind === "image";
+    case "data":
+      return kind === "data-diff";
+    default:
+      invalid("manualQa.surfaceEvidence has an unsupported surface.", "manualQa.surfaceEvidence.surface");
+  }
+}
+function checkFile(path, field, opts) {
+  if (opts?.repoRoot === undefined || opts.fs === undefined)
+    return;
+  const absolute = resolve3(opts.repoRoot, path);
+  if (!opts.fs.existsSync(absolute))
+    invalid(`${field} must point to an existing artifact.`, field);
+  if (opts.fs.statSync(absolute).size <= 0)
+    invalid(`${field} must point to a non-empty artifact.`, field);
+  if (opts.currentAttemptDir !== undefined && opts.repoRoot !== undefined) {
+    const attemptRoot = resolve3(opts.repoRoot, opts.currentAttemptDir);
+    if (!isWithinAttemptDir(absolute, attemptRoot))
+      invalid(`${field} (${path}) must point to an artifact from the current attempt (${opts.currentAttemptDir}).`, field);
+  }
+}
+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;
+}
+function parseArtifactRefs(value, opts) {
+  if (!Array.isArray(value) || value.length === 0)
+    invalid("manualQa.artifactRefs must not be empty.", "manualQa.artifactRefs");
+  return value.map((item, index) => {
+    const ref = section(item, `manualQa.artifactRefs[${index}]`);
+    const path = textField(ref["path"], `manualQa.artifactRefs[${index}].path`);
+    checkFile(path, `manualQa.artifactRefs[${index}].path`, opts);
+    return {
+      id: textField(ref["id"], `manualQa.artifactRefs[${index}].id`),
+      kind: kindField(ref["kind"], `manualQa.artifactRefs[${index}].kind`),
+      description: textField(ref["description"], `manualQa.artifactRefs[${index}].description`),
+      path
+    };
+  });
+}
+function referencedArtifacts(value, field, byId) {
+  return stringArray(value, field).map((id) => {
+    const artifact = byId.get(id);
+    if (artifact === undefined)
+      invalid(`${field} references unknown artifact ${id}.`, field);
+    return artifact;
+  });
+}
+
+// components/ulw-loop/src/quality-gate-verdicts.ts
 function passedVerdict(value, field) {
   if (value === "not_applicable")
     invalid(`${field} must not be not_applicable.`, field);
@@ -648,7 +824,7 @@ function adversarialVerdict(row, field) {
   invalid(`${field} must be passed or not_applicable with a reason.`, field);
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/surface.ts
+// components/ulw-loop/src/surface.ts
 import { existsSync as existsSync3, readFileSync } from "node:fs";
 import { dirname, join as join2 } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -665,6 +841,21 @@ var REVIEWER_ROLES_BY_SURFACE = {
   }
 };
 var GATE_REVIEWER_AGENT_NAMES = new Set(Object.values(REVIEWER_ROLES_BY_SURFACE).map((roles) => roles.gateReview));
+var REQUIRED_GATE_SECTIONS_BY_SURFACE = {
+  lazycodex: ["codeReview", "manualQa", "gateReview", "iteration", "criteriaCoverage"],
+  "omo-senpi": ["manualQa", "gateReview", "iteration", "criteriaCoverage"]
+};
+var GATE_SECTION_BY_ACCEPTOR = {
+  lazycodex: {
+    codeReview: [REVIEWER_ROLES_BY_SURFACE.lazycodex.codeReview],
+    manualQa: [REVIEWER_ROLES_BY_SURFACE.lazycodex.manualQa],
+    gateReview: [REVIEWER_ROLES_BY_SURFACE.lazycodex.gateReview]
+  },
+  "omo-senpi": {
+    manualQa: ["main-session"],
+    gateReview: ["category:deep", "category:unspecified-high", "category:unspecified-low"]
+  }
+};
 function reviewerRolesFor(surface) {
   return REVIEWER_ROLES_BY_SURFACE[surface];
 }
@@ -695,7 +886,7 @@ function readMarkerSurface(markerPath) {
   }
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/quality-gate-blockers.ts
+// components/ulw-loop/src/quality-gate-blockers.ts
 var BLOCKER_FIELD_KEYS = "blocker blockerSignature blockerEvidence blockerOccurrences blockedAt".split(" ");
 var URL_PATTERN = /https?:\/\/\S+/g;
 var PUNCTUATION_PATTERN = /[`"'()[\]{}:,;]/g;
@@ -737,93 +928,38 @@ function clearGoalBlockerFields(goal) {
     Reflect.deleteProperty(goal, key);
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/quality-gate.ts
+// components/ulw-loop/src/quality-gate.ts
 function reviewerRoleField(value, expected, field) {
   const actual = textField(value, field);
   if (actual !== expected)
     invalid(`${field} must be ${expected}.`, field);
   return expected;
 }
-function surfaceField(value, field) {
-  if (value === "cli" || value === "http" || value === "tmux" || value === "browser" || value === "gui" || value === "data")
-    return value;
-  invalid(`${field} must be a supported manual QA surface.`, field);
-}
-function kindField(value, field) {
-  if (value === "cli-transcript" || value === "log" || value === "screenshot" || value === "image" || value === "http-dump" || value === "data-diff")
-    return value;
-  invalid(`${field} must be a supported artifact kind.`, field);
-}
-function artifactCompatible(surface, kind) {
-  switch (surface) {
-    case "cli":
-    case "tmux":
-      return kind === "cli-transcript" || kind === "log";
-    case "http":
-      return kind === "http-dump";
-    case "browser":
-    case "gui":
-      return kind === "screenshot" || kind === "image";
-    case "data":
-      return kind === "data-diff";
-    default:
-      invalid("manualQa.surfaceEvidence has an unsupported surface.", "manualQa.surfaceEvidence.surface");
-  }
-}
-function checkFile(path, field, opts) {
-  if (opts?.repoRoot === undefined || opts.fs === undefined)
-    return;
-  const absolute = resolve2(opts.repoRoot, path);
-  if (!opts.fs.existsSync(absolute))
-    invalid(`${field} must point to an existing artifact.`, field);
-  if (opts.fs.statSync(absolute).size <= 0)
-    invalid(`${field} must point to a non-empty artifact.`, field);
-  if (opts.currentAttemptDir !== undefined && opts.repoRoot !== undefined) {
-    const attemptRoot = resolve2(opts.repoRoot, opts.currentAttemptDir);
-    if (!isWithinAttemptDir(absolute, attemptRoot))
-      invalid(`${field} (${path}) must point to an artifact from the current attempt (${opts.currentAttemptDir}).`, field);
-  }
-}
-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;
-}
-function parseArtifactRefs(value, opts) {
-  if (!Array.isArray(value) || value.length === 0)
-    invalid("manualQa.artifactRefs must not be empty.", "manualQa.artifactRefs");
-  return value.map((item, index) => {
-    const ref = section(item, `manualQa.artifactRefs[${index}]`);
-    const path = textField(ref["path"], `manualQa.artifactRefs[${index}].path`);
-    checkFile(path, `manualQa.artifactRefs[${index}].path`, opts);
-    return {
-      id: textField(ref["id"], `manualQa.artifactRefs[${index}].id`),
-      kind: kindField(ref["kind"], `manualQa.artifactRefs[${index}].kind`),
-      description: textField(ref["description"], `manualQa.artifactRefs[${index}].description`),
-      path
-    };
-  });
-}
-function referencedArtifacts(value, field, byId) {
-  return stringArray(value, field).map((id) => {
-    const artifact = byId.get(id);
-    if (artifact === undefined)
-      invalid(`${field} references unknown artifact ${id}.`, field);
-    return artifact;
-  });
+function reviewerAcceptorField(value, surface, sectionName) {
+  const field = `${sectionName}.by`;
+  const actual = textField(value, field);
+  const accepted = GATE_SECTION_BY_ACCEPTOR[surface][sectionName];
+  if (accepted === undefined || !accepted.includes(actual))
+    invalid(`${field} must be one of ${accepted?.join(", ") ?? "the configured reviewers"}.`, field);
+  return actual;
 }
 function validateQualityGate(input, opts) {
-  const reviewerRoles = reviewerRolesFor(opts?.reviewerSurface ?? "lazycodex");
+  const surface = opts?.reviewerSurface ?? "lazycodex";
+  aggregateQualityGateDefects(input, opts);
   const gate = section(input, "qualityGate");
-  const codeReview = section(gate["codeReview"], "codeReview");
+  const requiredSections = REQUIRED_GATE_SECTIONS_BY_SURFACE[surface];
+  for (const sectionName of requiredSections)
+    section(gate[sectionName], sectionName);
+  if (surface === "omo-senpi" && gate["codeReview"] !== undefined)
+    invalid("omo-senpi gate has no codeReview lane.", "codeReview");
   const manualQa = section(gate["manualQa"], "manualQa");
   const gateReview = section(gate["gateReview"], "gateReview");
   const iteration = section(gate["iteration"], "iteration");
   const coverage = section(gate["criteriaCoverage"], "criteriaCoverage");
+  const manualQaBy = reviewerAcceptorField(manualQa["by"], surface, "manualQa");
+  const gateReviewBy = reviewerAcceptorField(gateReview["by"], surface, "gateReview");
+  if (surface === "lazycodex")
+    reviewerRoleField(section(gate["codeReview"], "codeReview")["by"], "lazycodex-code-reviewer", "codeReview.by");
   const totalCriteria = numberField(coverage["totalCriteria"], "criteriaCoverage.totalCriteria");
   const passCount = numberField(coverage["passCount"], "criteriaCoverage.passCount");
   if (passCount < totalCriteria)
@@ -832,21 +968,11 @@ function validateQualityGate(input, opts) {
   const byId = artifactMap(artifactRefs);
   const surfaceEvidence = parseSurfaceEvidence(manualQa["surfaceEvidence"], byId);
   const adversarialCases = parseAdversarialCases(manualQa["adversarialCases"], byId);
-  const codeReportPath = textField(codeReview["reportPath"], "codeReview.reportPath");
   const gateReportPath = textField(gateReview["reportPath"], "gateReview.reportPath");
-  checkFile(codeReportPath, "codeReview.reportPath", opts);
   checkFile(gateReportPath, "gateReview.reportPath", opts);
-  return {
-    codeReview: {
-      by: reviewerRoleField(codeReview["by"], reviewerRoles.codeReview, "codeReview.by"),
-      recommendation: literal(codeReview["recommendation"], "APPROVE", "codeReview.recommendation"),
-      codeQualityStatus: codeQualityStatusField(codeReview["codeQualityStatus"], "codeReview.codeQualityStatus"),
-      reportPath: codeReportPath,
-      evidence: textField(codeReview["evidence"], "codeReview.evidence"),
-      blockers: emptyBlockers(codeReview["blockers"], "codeReview.blockers")
-    },
+  const common = {
     manualQa: {
-      by: reviewerRoleField(manualQa["by"], reviewerRoles.manualQa, "manualQa.by"),
+      by: manualQaBy,
       status: literal(manualQa["status"], "passed", "manualQa.status"),
       evidence: textField(manualQa["evidence"], "manualQa.evidence"),
       surfaceEvidence,
@@ -854,7 +980,7 @@ function validateQualityGate(input, opts) {
       artifactRefs
     },
     gateReview: {
-      by: reviewerRoleField(gateReview["by"], reviewerRoles.gateReview, "gateReview.by"),
+      by: gateReviewBy,
       recommendation: literal(gateReview["recommendation"], "APPROVE", "gateReview.recommendation"),
       reportPath: gateReportPath,
       evidence: textField(gateReview["evidence"], "gateReview.evidence"),
@@ -875,6 +1001,23 @@ function validateQualityGate(input, opts) {
       adversarialClassesCovered: stringArray(coverage["adversarialClassesCovered"], "criteriaCoverage.adversarialClassesCovered")
     }
   };
+  if (surface === "omo-senpi")
+    return { surface, ...common };
+  const codeReview = section(gate["codeReview"], "codeReview");
+  const codeReportPath = textField(codeReview["reportPath"], "codeReview.reportPath");
+  checkFile(codeReportPath, "codeReview.reportPath", opts);
+  return {
+    surface,
+    ...common,
+    codeReview: {
+      by: "lazycodex-code-reviewer",
+      recommendation: literal(codeReview["recommendation"], "APPROVE", "codeReview.recommendation"),
+      codeQualityStatus: codeQualityStatusField(codeReview["codeQualityStatus"], "codeReview.codeQualityStatus"),
+      reportPath: codeReportPath,
+      evidence: textField(codeReview["evidence"], "codeReview.evidence"),
+      blockers: emptyBlockers(codeReview["blockers"], "codeReview.blockers")
+    }
+  };
 }
 function parseSurfaceEvidence(value, byId) {
   if (!Array.isArray(value) || value.length === 0)
@@ -917,7 +1060,7 @@ function parseAdversarialCases(value, byId) {
   });
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/cli-arg-parser.ts
+// components/ulw-loop/src/cli-arg-parser.ts
 import { readFile as readFile4 } from "node:fs/promises";
 var VALUE_FLAGS = new Set("--brief --brief-file --session-id --codex-goal-mode --validation-batch-json --goal --goal-id --criterion-id --status --evidence --notes --codex-goal-json --quality-gate-json --kind --rationale --title --objective --target-goal-id --source --after-json --directive-json --directive-file --idempotency-key --proposals-json".split(" "));
 var SUBCOMMANDS = new Set("create-goals status complete-goals criteria record-evidence checkpoint steer add-goal record-review-blockers".split(" "));
@@ -1008,14 +1151,14 @@ function parseRecordEvidenceArgs(argv) {
   return notes ? { ...result, notes } : result;
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/validation-batch.ts
+// components/ulw-loop/src/validation-batch.ts
 function isObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function read(value, key) {
   return Object.entries(value).find(([name]) => name === key)?.[1];
 }
-function text(value, key) {
+function text2(value, key) {
   const candidate = read(value, key);
   return typeof candidate === "string" && candidate.trim().length > 0 ? candidate.trim() : undefined;
 }
@@ -1036,9 +1179,9 @@ async function parseValidationBatches(input, goals) {
 function batchFromObject(value) {
   if (!isObject(value))
     fail("validation batch entries must be objects.");
-  const batchId = text(value, "batchId");
+  const batchId = text2(value, "batchId");
   const memberIds = strings(value, "memberIds");
-  const finalGoalId = text(value, "finalGoalId");
+  const finalGoalId = text2(value, "finalGoalId");
   if (batchId === undefined)
     fail("validation batch requires batchId.");
   if (memberIds === undefined || memberIds.length < 2)
@@ -1126,7 +1269,7 @@ function fail(message, code = "ULW_LOOP_VALIDATION_BATCH_INVALID") {
   throw new UlwLoopError(message, code);
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/checkpoint.ts
+// components/ulw-loop/src/checkpoint.ts
 var QUALITY_GATE_FS = { existsSync: existsSync4, statSync };
 function ulwLoopFail2(message, code) {
   throw new UlwLoopError(message, code);
@@ -1152,7 +1295,7 @@ async function readJsonInput2(raw, repoRoot) {
     if (!(error instanceof SyntaxError))
       throw error;
   }
-  const path = resolve3(repoRoot, trimmed);
+  const path = resolve4(repoRoot, trimmed);
   if (!existsSync4(path))
     return ulwLoopFail2("Quality gate JSON is neither valid JSON nor a readable path.", "ulw_loop_json_input_invalid");
   try {
@@ -1196,13 +1339,13 @@ function ledgerKind2(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: ledgerKind2(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;
@@ -1253,7 +1396,7 @@ async function checkpointUlwLoop(repoRoot, args, 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");
+          throw codexSnapshotMismatchError({ reconciliation, snapshot, expectedObjective: expectedCodexObjective(plan, goal), taskScopedHint: { goal, aggregate, final } });
       }
       if (closesBatch)
         requireBatchFinalReady(plan, goal);
@@ -1294,7 +1437,116 @@ async function checkpointUlwLoop(repoRoot, args, scope) {
   });
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/cli-output.ts
+// components/ulw-loop/src/checkpoint-template.ts
+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: surface === "omo-senpi" ? "main-session" : "lazycodex-qa-executor",
+    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" : "lazycodex-gate-reviewer",
+      recommendation: "APPROVE",
+      reportPath: artifactPath(base, "gate-review.md"),
+      evidence: "<replace:gate review evidence>",
+      blockers: []
+    },
+    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>"]
+    }
+  };
+  if (surface === "omo-senpi")
+    return common;
+  return {
+    codeReview: {
+      by: "lazycodex-code-reviewer",
+      recommendation: "APPROVE",
+      codeQualityStatus: "CLEAR",
+      reportPath: artifactPath(base, "code-review.md"),
+      evidence: "<replace:code review evidence>",
+      blockers: []
+    },
+    ...common
+  };
+}
+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";
+  return {
+    qualityGateTemplate: gateTemplate(resolveToolkitSurface(), attemptDir),
+    codexGoalTemplate: {
+      goal: { objective: plan.codexObjective ?? "<replace:codex objective>", status: "complete" }
+    },
+    ...hasAttempt ? { attemptDir } : { guidance: "This plan is evidence-layout v1; artifacts go under .omo/evidence/." }
+  };
+}
+
+// components/ulw-loop/src/cli-output.ts
 var ULW_LOOP_HELP = `Usage:
   omo-agent-toolkit hook user-prompt-submit [--with-ultrawork]  (Codex UserPromptSubmit hook)
   omo-agent-toolkit help | --help | -h                          (this message)
@@ -1304,6 +1556,7 @@ var ULW_LOOP_HELP = `Usage:
   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]
@@ -1384,7 +1637,7 @@ function normalizeCodexGoalMode(value) {
   throw new UlwLoopError("Invalid --codex-goal-mode; expected aggregate or per_story.", "ULW_LOOP_CODEX_GOAL_MODE_INVALID", { details: { value } });
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/codex-goal-instruction.ts
+// components/ulw-loop/src/codex-goal-instruction.ts
 function buildCodexGoalInstruction(args) {
   const mode = codexGoalMode(args.plan);
   const createGoal = buildCreateGoalPayload(args.plan, args.goal);
@@ -1469,6 +1722,8 @@ function finalSection(plan, goal, isFinal, aggregate, 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([
@@ -1486,6 +1741,20 @@ function finalSection(plan, goal, isFinal, aggregate, surface) {
     `  ${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";
@@ -1499,11 +1768,11 @@ function joinLines(lines) {
 `);
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/plan-crud.ts
+// components/ulw-loop/src/plan-crud.ts
 import { existsSync as existsSync5 } from "node:fs";
 import { mkdir as mkdir2, writeFile as writeFile2 } from "node:fs/promises";
 
-// packages/omo-codex/plugin/components/ulw-loop/src/plan-goal-factory.ts
+// components/ulw-loop/src/plan-goal-factory.ts
 function cleanLine(line) {
   return line.replace(/^\s*(?:[-*+]\s+|\d+[.)]\s+)/, "").trim();
 }
@@ -1592,7 +1861,7 @@ function appendGoalToPlan(plan, title, objective, now) {
   return goal;
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/plan-crud.ts
+// components/ulw-loop/src/plan-crud.ts
 function isScheduleEligible(goal) {
   return goal.steeringStatus !== "superseded" && goal.steeringStatus !== "blocked";
 }
@@ -1719,7 +1988,7 @@ function summarizeUlwLoopPlan(plan) {
   };
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/checkpoint-continuation.ts
+// components/ulw-loop/src/checkpoint-continuation.ts
 async function checkpointAndContinue(repoRoot, args, scope) {
   const result = await checkpointUlwLoop(repoRoot, args, scope);
   if (args.status !== "complete" || result.aggregateCompletion !== undefined || !args.advance)
@@ -1731,6 +2000,14 @@ async function checkpointAndContinue(repoRoot, args, scope) {
   return { ...result, plan: next.plan, next: { resumed: next.resumed, goal: next.goal, instruction } };
 }
 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 = required2(argv, "--goal-id");
   const statusValue = checkpointStatus(required2(argv, "--status"));
   const evidence = required2(argv, "--evidence");
@@ -1782,10 +2059,10 @@ function checkpointStatus(value) {
   throw new UlwLoopError("Missing or invalid --status; expected complete, failed, or blocked.", "ULW_LOOP_STATUS_INVALID", { details: { status: value } });
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/cli-subcommands.ts
+// components/ulw-loop/src/cli-subcommands.ts
 import { readFile as readFile6 } from "node:fs/promises";
 
-// packages/omo-codex/plugin/components/ulw-loop/src/cli-steering.ts
+// components/ulw-loop/src/cli-steering.ts
 var SOURCES = ["user_prompt_submit", "finding", "cli"];
 var STEERING_KIND_HELP = [
   `Allowed --kind values: ${ULW_LOOP_STEERING_MUTATION_KINDS.join(", ")}`,
@@ -1817,7 +2094,7 @@ function kindMessage(prefix) {
 
 ${STEERING_KIND_HELP}`;
 }
-function text2(value, field) {
+function text3(value, field) {
   if (value === undefined)
     return;
   const trimmed = value.trim();
@@ -1826,11 +2103,11 @@ function text2(value, field) {
   return fail2(`Empty ${field}.`, "ULW_LOOP_STEERING_FIELD_EMPTY", { field });
 }
 function required3(argv, flag) {
-  const value = text2(readValue(argv, flag), flag);
+  const value = text3(readValue(argv, flag), flag);
   return value ?? fail2(`Missing ${flag}.`, "ULW_LOOP_STEERING_FIELD_REQUIRED", { flag });
 }
 function requiredGoal(argv) {
-  const value = text2(parseGoalArg(argv), "--goal-id");
+  const value = text3(parseGoalArg(argv), "--goal-id");
   return value ?? fail2("Missing --goal-id.", "ULW_LOOP_GOAL_ID_REQUIRED", { flag: "--goal-id" });
 }
 function readObject(value, key) {
@@ -1881,14 +2158,14 @@ function parseSteeringSource(argv) {
 function child(value) {
   if (!isPlain(value))
     return null;
-  const title = text2(objectText(value, "title"), "title");
-  const objective = text2(objectText(value, "objective"), "objective");
+  const title = text3(objectText(value, "title"), "title");
+  const objective = text3(objectText(value, "objective"), "objective");
   if (title === undefined || objective === undefined)
     return null;
   return { title, objective };
 }
 async function children(argv, flag, needed) {
-  const input = needed ? required3(argv, flag) : text2(readValue(argv, flag), flag);
+  const input = needed ? required3(argv, flag) : text3(readValue(argv, flag), flag);
   if (input === undefined)
     return [];
   const raw = await readJsonInput(input);
@@ -1911,12 +2188,12 @@ async function stringArray2(argv, flag) {
   for (const item of raw) {
     if (typeof item !== "string")
       return fail2(`${flag} entries must be strings.`, "ULW_LOOP_STEERING_STRING_ARRAY_REQUIRED", { flag });
-    values.push(text2(item, flag) ?? "");
+    values.push(text3(item, flag) ?? "");
   }
   return values;
 }
 function model(value) {
-  const trimmed = text2(value, "--user-model");
+  const trimmed = text3(value, "--user-model");
   if (trimmed === undefined)
     return;
   return isModel(trimmed) ? trimmed : fail2(`Invalid --user-model: ${trimmed}.`, "ULW_LOOP_STEERING_USER_MODEL_INVALID", { value: trimmed, expected: ULW_LOOP_SUCCESS_CRITERION_USER_MODELS });
@@ -1927,7 +2204,7 @@ function neverKind(kind) {
 async function parseSteeringProposal(argv) {
   const kind = parseSteeringKind(argv);
   const source = parseSteeringSource(argv);
-  const idempotencyKey = text2(readValue(argv, "--idempotency-key"), "--idempotency-key");
+  const idempotencyKey = text3(readValue(argv, "--idempotency-key"), "--idempotency-key");
   const base = { kind, source, evidence: required3(argv, "--evidence"), rationale: required3(argv, "--rationale"), ...idempotencyKey === undefined ? {} : { idempotencyKey } };
   switch (kind) {
     case "add_subgoal":
@@ -1970,36 +2247,36 @@ async function parseSteeringProposal(argv) {
 function normalizedChildren(values) {
   if (values === undefined)
     return;
-  return values.map((item) => ({ title: text2(item.title, "child.title") ?? "", objective: text2(item.objective, "child.objective") ?? "" }));
+  return values.map((item) => ({ title: text3(item.title, "child.title") ?? "", objective: text3(item.objective, "child.objective") ?? "" }));
 }
 function normalizedStrings(values, field) {
   if (values === undefined)
     return;
-  return values.map((value) => text2(value, field) ?? "");
+  return values.map((value) => text3(value, field) ?? "");
 }
 function normalizeSteeringProposal(proposal) {
-  const evidence = text2(proposal.evidence, "evidence") ?? "";
-  const rationale = text2(proposal.rationale, "rationale") ?? "";
-  const goalId = text2(proposal.goalId, "goalId");
-  const targetGoalId = text2(proposal.targetGoalId, "targetGoalId");
+  const evidence = text3(proposal.evidence, "evidence") ?? "";
+  const rationale = text3(proposal.rationale, "rationale") ?? "";
+  const goalId = text3(proposal.goalId, "goalId");
+  const targetGoalId = text3(proposal.targetGoalId, "targetGoalId");
   const targetGoalIds = normalizedStrings(proposal.targetGoalIds, "targetGoalIds");
-  const criterionId = text2(proposal.criterionId, "criterionId");
-  const title = text2(proposal.title, "title");
-  const objective = text2(proposal.objective, "objective");
-  const revisedTitle = text2(proposal.revisedTitle, "revisedTitle");
-  const revisedObjective = text2(proposal.revisedObjective, "revisedObjective");
-  const blockedReason = text2(proposal.blockedReason, "blockedReason");
-  const directiveText = text2(proposal.directiveText, "directiveText");
-  const promptSignature = text2(proposal.promptSignature, "promptSignature");
-  const idempotencyKey = text2(proposal.idempotencyKey, "idempotencyKey");
-  const scenario = text2(proposal.scenario, "scenario");
-  const expectedEvidence = text2(proposal.expectedEvidence, "expectedEvidence");
+  const criterionId = text3(proposal.criterionId, "criterionId");
+  const title = text3(proposal.title, "title");
+  const objective = text3(proposal.objective, "objective");
+  const revisedTitle = text3(proposal.revisedTitle, "revisedTitle");
+  const revisedObjective = text3(proposal.revisedObjective, "revisedObjective");
+  const blockedReason = text3(proposal.blockedReason, "blockedReason");
+  const directiveText = text3(proposal.directiveText, "directiveText");
+  const promptSignature = text3(proposal.promptSignature, "promptSignature");
+  const idempotencyKey = text3(proposal.idempotencyKey, "idempotencyKey");
+  const scenario = text3(proposal.scenario, "scenario");
+  const expectedEvidence = text3(proposal.expectedEvidence, "expectedEvidence");
   const childGoals = normalizedChildren(proposal.childGoals);
   const pendingOrder = normalizedStrings(proposal.pendingOrder, "pendingOrder");
   return { kind: proposal.kind, source: proposal.source, evidence, rationale, ...goalId === undefined ? {} : { goalId }, ...targetGoalId === undefined ? {} : { targetGoalId }, ...targetGoalIds === undefined ? {} : { targetGoalIds }, ...criterionId === undefined ? {} : { criterionId }, ...title === undefined ? {} : { title }, ...objective === undefined ? {} : { objective }, ...childGoals === undefined ? {} : { childGoals }, ...revisedTitle === undefined ? {} : { revisedTitle }, ...revisedObjective === undefined ? {} : { revisedObjective }, ...pendingOrder === undefined ? {} : { pendingOrder }, ...blockedReason === undefined ? {} : { blockedReason }, ...proposal.after === undefined ? {} : { after: proposal.after }, ...directiveText === undefined ? {} : { directiveText }, ...promptSignature === undefined ? {} : { promptSignature }, ...idempotencyKey === undefined ? {} : { idempotencyKey }, ...proposal.now === undefined ? {} : { now: proposal.now }, ...scenario === undefined ? {} : { scenario }, ...expectedEvidence === undefined ? {} : { expectedEvidence }, ...proposal.userModel === undefined ? {} : { userModel: proposal.userModel } };
 }
 async function parseSteeringProposals(argv) {
-  const input = text2(readValue(argv, "--proposals-json"), "--proposals-json");
+  const input = text3(readValue(argv, "--proposals-json"), "--proposals-json");
   if (input === undefined)
     return [await parseSteeringProposal(argv)];
   if (readValue(argv, "--kind") !== undefined)
@@ -2092,7 +2369,7 @@ function printSteerBatchResult(result, json) {
   printStatus(result.plan);
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/review-blockers.ts
+// components/ulw-loop/src/review-blockers.ts
 var BLOCKER_FIELDS = "blockedReason blockerSignature blockerOccurrenceCount requiredExternalDecision nonRetriable failedAt failureReason completedAt blocker blockerEvidence blockerOccurrences blockedAt".split(" ");
 function ulwLoopError(message, code) {
   throw new UlwLoopError(message, code);
@@ -2131,9 +2408,10 @@ async function recordFinalReviewBlockers(repoRoot, args, scope) {
       ulwLoopError(`${goal.id} is not final.`, "ulw_loop_not_final_story");
     const snapshot = await readCodexGoalSnapshotInput(args.codexGoalJson, repoRoot);
     const aggregate = codexGoalMode(plan) === "aggregate";
-    const reconciliation = reconcileCodexGoalSnapshot(snapshot, { expectedObjective: expectedCodexObjective(plan, goal), ...aggregate ? { acceptedObjectives: compatibleCodexObjectives(plan) } : {}, allowedStatuses: ["active"], requireSnapshot: true, requireComplete: false });
+    const expected = expectedCodexObjective(plan, goal);
+    const reconciliation = reconcileCodexGoalSnapshot(snapshot, { expectedObjective: expected, ...aggregate ? { acceptedObjectives: compatibleCodexObjectives(plan) } : {}, allowedStatuses: ["active"], requireSnapshot: true, requireComplete: false });
     if (!reconciliation.ok)
-      ulwLoopError(reconciliation.errors.join(" "), "ulw_loop_codex_snapshot_mismatch");
+      throw codexSnapshotMismatchError({ reconciliation, snapshot, expectedObjective: expected });
     const now = iso();
     for (const field of BLOCKER_FIELDS)
       Reflect.deleteProperty(goal, field);
@@ -2158,10 +2436,39 @@ async function recordFinalReviewBlockers(repoRoot, args, scope) {
   });
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/steering-mutations.ts
+// components/ulw-loop/src/status-next-actions.ts
+function statusNextActions(plan) {
+  const actions = [];
+  const active = plan.goals.find((goal) => goal.id === plan.activeGoalId);
+  if (plan.goals.length === 0)
+    actions.push(`No goals yet: bootstrap with \`${ULW_LOOP_CREATE_GOALS_COMMAND}\`.`);
+  else if (active !== undefined)
+    actions.push(...activeGoalActions(plan, active));
+  for (const goal of plan.goals.filter((candidate) => candidate.status === "review_blocked"))
+    actions.push(`${goal.id} is review_blocked: capture the reviewer verdict with \`omo-agent-toolkit ulw-loop record-review-blockers --goal-id ${goal.id} --title "<title>" --objective "<objective>" --evidence "<verdict>" --codex-goal-json '<get_goal json>'\`.`);
+  if (plan.evidenceLayoutVersion !== 2 || active === undefined)
+    actions.push("plan is evidence-layout v1; artifacts go under .omo/evidence/");
+  return actions;
+}
+function activeGoalActions(plan, active) {
+  const unresolved = active.successCriteria.filter((criterion) => criterion.status !== "pass");
+  if (unresolved.length > 0)
+    return [
+      `${active.id} has ${unresolved.length} unresolved criterion(s) (${unresolved.map((criterion) => criterion.id).join(", ")}): record proof with \`omo-agent-toolkit ulw-loop record-evidence --goal-id ${active.id} --criterion-id <id> --status pass --evidence "<observable proof>"\`.`
+    ];
+  if (hasAllCriteriaPass(active) && isFinalRunCompletionCandidate(plan, active))
+    return [
+      `${active.id} passes every criterion and is the final story: update_goal complete, then checkpoint --print-template to build the final quality gate.`
+    ];
+  return [
+    `${active.id} passes every criterion: close it with \`omo-agent-toolkit ulw-loop checkpoint --goal-id ${active.id} --status complete --evidence "<proof>" --codex-goal-json '<get_goal json>'\`.`
+  ];
+}
+
+// components/ulw-loop/src/steering-mutations.ts
 var read2 = (value, key) => Object.entries(value).find(([name]) => name === key)?.[1];
 var isText = (value) => typeof value === "string" && value.trim().length > 0;
-var text3 = (value, key) => {
+var text4 = (value, key) => {
   const candidate = read2(value, key);
   return isText(candidate) ? candidate.trim() : undefined;
 };
@@ -2170,13 +2477,13 @@ var after = (proposal) => {
   const candidate = read2(proposal, "after");
   return typeof candidate === "object" && candidate !== null && !Array.isArray(candidate) ? candidate : undefined;
 };
-var revised = (proposal, direct, nested) => text3(proposal, direct) ?? text3(after(proposal) ?? proposal, nested);
-var targets = (proposal) => proposal.targetGoalIds ?? [proposal.targetGoalId ?? text3(proposal, "goalId") ?? ""].filter(Boolean);
+var revised = (proposal, direct, nested) => text4(proposal, direct) ?? text4(after(proposal) ?? proposal, nested);
+var targets = (proposal) => proposal.targetGoalIds ?? [proposal.targetGoalId ?? text4(proposal, "goalId") ?? ""].filter(Boolean);
 var child2 = (value) => {
   if (typeof value !== "object" || value === null || Array.isArray(value))
     return null;
-  const title = text3(value, "title");
-  const objective = text3(value, "objective");
+  const title = text4(value, "title");
+  const objective = text4(value, "objective");
   return title === undefined || objective === undefined ? null : { title, objective };
 };
 var children2 = (proposal) => {
@@ -2241,11 +2548,11 @@ function reviseCriterion(plan, proposal, now) {
   if (target === undefined || current === undefined)
     return;
   const model2 = read2(proposal, "userModel");
-  target.successCriteria[index] = { ...current, scenario: text3(proposal, "scenario") ?? current.scenario, expectedEvidence: text3(proposal, "expectedEvidence") ?? current.expectedEvidence, userModel: isModel2(model2) ? model2 : current.userModel };
+  target.successCriteria[index] = { ...current, scenario: text4(proposal, "scenario") ?? current.scenario, expectedEvidence: text4(proposal, "expectedEvidence") ?? current.expectedEvidence, userModel: isModel2(model2) ? model2 : current.userModel };
   target.updatedAt = now;
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/steering-snapshot.ts
+// components/ulw-loop/src/steering-snapshot.ts
 function buildSteeringPlanSnapshot(plan, changedGoalIds) {
   const snapshot = {
     updatedAt: plan.updatedAt,
@@ -2269,14 +2576,14 @@ function changedGoalIdsBetween(before, after2) {
   return changed;
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/steering.ts
+// components/ulw-loop/src/steering.ts
 var SOURCES2 = ["user_prompt_submit", "finding", "cli"];
 var PROTECTED = new Set(["aggregateCompletion", "codexObjective", "codexObjectiveAliases", "originalConstraints", "qualityGate", "status", "completedAt", "completionStatus"]);
 var isObject2 = (value) => typeof value === "object" && value !== null;
 var isPlain2 = (value) => isObject2(value) && !Array.isArray(value);
 var read3 = (value, key) => Object.entries(value).find(([name]) => name === key)?.[1];
 var isText2 = (value) => typeof value === "string" && value.trim().length > 0;
-var text4 = (value, key) => {
+var text5 = (value, key) => {
   const candidate = read3(value, key);
   return isText2(candidate) ? candidate.trim() : undefined;
 };
@@ -2289,19 +2596,19 @@ var texts = (value, key) => {
 };
 function targets2(proposal) {
   const many = texts(proposal, "targetGoalIds");
-  const one = text4(proposal, "targetGoalId") ?? text4(proposal, "goalId");
+  const one = text5(proposal, "targetGoalId") ?? text5(proposal, "goalId");
   return many.length > 0 ? many : one === undefined ? [] : [one];
 }
 var after2 = (proposal) => {
   const candidate = read3(proposal, "after");
   return isPlain2(candidate) ? candidate : undefined;
 };
-var revised2 = (proposal, direct, nested) => text4(proposal, direct) ?? text4(after2(proposal) ?? proposal, nested);
+var revised2 = (proposal, direct, nested) => text5(proposal, direct) ?? text5(after2(proposal) ?? proposal, nested);
 function child3(value) {
   if (!isPlain2(value))
     return null;
-  const title = text4(value, "title");
-  const objective = text4(value, "objective");
+  const title = text5(value, "title");
+  const objective = text5(value, "objective");
   if (title === undefined || objective === undefined)
     return null;
   return { title, objective };
@@ -2340,15 +2647,15 @@ function auditFor(proposal, reasons) {
   const object = isPlain2(proposal) ? proposal : undefined;
   const kindRaw = object === undefined ? undefined : read3(object, "kind");
   const sourceRaw = object === undefined ? undefined : read3(object, "source");
-  const evidence = object === undefined ? "" : text4(object, "evidence") ?? "";
-  const rationale = object === undefined ? "" : text4(object, "rationale") ?? "";
+  const evidence = object === undefined ? "" : text5(object, "evidence") ?? "";
+  const rationale = object === undefined ? "" : text5(object, "rationale") ?? "";
   const audit = { kind: isKind2(kindRaw) ? kindRaw : "annotate_ledger", source: isSource2(sourceRaw) ? sourceRaw : "cli", targetGoalIds: object === undefined ? [] : targets2(object), evidence, rationale, invariant: { accepted: reasons.length === 0, structuralInvariantAccepted: reasons.length === 0, evidenceBackedNecessity: evidence.length > 0 && rationale.length > 0, noEasierCompletion: !weakens(proposal), rejectedReasons: reasons, reasons } };
   if (object === undefined)
     return audit;
-  const criterionId = text4(object, "criterionId");
-  const directiveText = text4(object, "directiveText");
-  const promptSignature = text4(object, "promptSignature");
-  const idempotencyKey = text4(object, "idempotencyKey");
+  const criterionId = text5(object, "criterionId");
+  const directiveText = text5(object, "directiveText");
+  const promptSignature = text5(object, "promptSignature");
+  const idempotencyKey = text5(object, "idempotencyKey");
   if (criterionId !== undefined)
     audit.criterionId = criterionId;
   if (directiveText !== undefined)
@@ -2369,9 +2676,9 @@ function validateUlwLoopSteeringProposal(plan, proposal) {
     reasons.push(`invalid kind: ${String(kind)}`);
   if (!isSource2(read3(object, "source")))
     reasons.push(`invalid source: ${String(read3(object, "source"))}`);
-  if (text4(object, "evidence") === undefined)
+  if (text5(object, "evidence") === undefined)
     reasons.push("missing evidence");
-  if (text4(object, "rationale") === undefined)
+  if (text5(object, "rationale") === undefined)
     reasons.push("missing rationale");
   if (hasProtected(proposal))
     reasons.push("protected payload");
@@ -2388,7 +2695,7 @@ function goal2(plan, id) {
 }
 function validateKind(plan, proposal, kind, reasons) {
   const target = goal2(plan, targets2(proposal)[0]);
-  if (kind === "add_subgoal" && (text4(proposal, "title") === undefined || text4(proposal, "objective") === undefined))
+  if (kind === "add_subgoal" && (text5(proposal, "title") === undefined || text5(proposal, "objective") === undefined))
     reasons.push("add_subgoal requires title/objective");
   if ((kind === "split_subgoal" || kind === "revise_pending_wording" || kind === "mark_blocked_superseded") && target === undefined)
     reasons.push(`${kind} requires target`);
@@ -2418,7 +2725,7 @@ function validateOrder(plan, proposal, reasons) {
 }
 function validateCriterion(plan, proposal, reasons) {
   const target = goal2(plan, targets2(proposal)[0]);
-  const criterionId = text4(proposal, "criterionId");
+  const criterionId = text5(proposal, "criterionId");
   if (target === undefined)
     reasons.push("revise_criterion requires goalId");
   else if (criterionId === undefined || target.successCriteria.every((item) => item.id !== criterionId))
@@ -2453,8 +2760,8 @@ function applySteeringMutation(plan, proposal, audit) {
 function isProposal(value) {
   return isPlain2(value) && isKind2(read3(value, "kind")) && isSource2(read3(value, "source")) && isText2(read3(value, "evidence")) && isText2(read3(value, "rationale"));
 }
-function parseUlwLoopSteeringDirective(text5) {
-  const match = /(?:^|\s)(?:OMO_ULW_LOOP_STEER|omo\.ulw-loop\.steer|omo ulw-loop steer|omo-agent-toolkit ulw-loop steer):\s*([\s\S]+)$/u.exec(text5);
+function parseUlwLoopSteeringDirective(text6) {
+  const match = /(?:^|\s)(?:OMO_ULW_LOOP_STEER|omo\.ulw-loop\.steer|omo ulw-loop steer|omo-agent-toolkit ulw-loop steer):\s*([\s\S]+)$/u.exec(text6);
   if (match?.[1] === undefined)
     return null;
   try {
@@ -2506,7 +2813,7 @@ function ledgerEntry(proposal, audit, at) {
   return entry;
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/steering-batch.ts
+// components/ulw-loop/src/steering-batch.ts
 async function steerUlwLoopBatch(repoRoot, proposals, scope) {
   return withUlwLoopMutationLock(repoRoot, scope, async () => {
     const plan = await readUlwLoopPlan(repoRoot, scope);
@@ -2587,7 +2894,7 @@ function ledgerEntry2(proposal, audit, at) {
   return entry;
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/cli-subcommands.ts
+// components/ulw-loop/src/cli-subcommands.ts
 async function createGoals(repoRoot, argv, json, scope) {
   const briefFile = readValue(argv, "--brief-file");
   const brief = readValue(argv, "--brief") ?? (briefFile === undefined ? undefined : await readFile6(briefFile, "utf8")) ?? (hasFlag(argv, "--from-stdin") ? await readStdin() : undefined) ?? positionalText(argv);
@@ -2621,7 +2928,8 @@ async function status(repoRoot, json, scope) {
       ok: true,
       plan,
       summary: summarizeUlwLoopPlan(plan),
-      ...currentAttemptDir === undefined ? {} : { currentAttemptDir }
+      ...currentAttemptDir === undefined ? {} : { currentAttemptDir },
+      nextActions: statusNextActions(plan)
     });
   } else
     printStatus(plan);
@@ -2743,7 +3051,7 @@ function findGoal3(plan, goalId) {
   throw new UlwLoopError(`Unknown ulw-loop id: ${goalId}.`, "ULW_LOOP_GOAL_NOT_FOUND", { details: { goalId } });
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/cli-commands.ts
+// components/ulw-loop/src/cli-commands.ts
 var ULW_LOOP_SUBCOMMANDS = [
   "help",
   "create-goals",
@@ -2837,7 +3145,7 @@ function commandScope(argv) {
   if (sessionIdFlagPresent(argv)) {
     const sessionId2 = readValue(argv, SESSION_ID_FLAG)?.trim();
     if (!sessionId2) {
-      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 }
       });
     }
@@ -2847,10 +3155,10 @@ function commandScope(argv) {
   return sessionId === null ? undefined : { sessionId };
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/ultrawork-directive.ts
+// components/ulw-loop/src/ultrawork-directive.ts
 import { readFileSync as readFileSync3 } from "node:fs";
 
-// packages/omo-codex/plugin/components/ulw-loop/src/ultrawork-skill-pointer.ts
+// components/ulw-loop/src/ultrawork-skill-pointer.ts
 import { existsSync as existsSync6, readFileSync as readFileSync2 } from "node:fs";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 var ULTRAWORK_SKILL_POINTER_TEMPLATE = `<ultrawork-mode>
@@ -2898,7 +3206,7 @@ function buildUltraworkAdditionalContext(options = {}) {
   return ULTRAWORK_DIRECTIVE;
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/ultrawork-directive.ts
+// components/ulw-loop/src/ultrawork-directive.ts
 var ULTRAWORK_CURRENT_PROMPT_PATTERN = /(?:ultrawork|ulw)/i;
 var ULTRAWORK_DIRECTIVE_MARKER = "<ultrawork-mode>";
 var TRANSCRIPT_SEARCH_BYTES = 512000;
@@ -3001,7 +3309,7 @@ function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/codex-hook.ts
+// components/ulw-loop/src/codex-hook.ts
 var CREATE_GOAL_TOOL_NAME = "create_goal";
 var CREATE_GOAL_PAYLOAD_WARNING = "Use create_goal with objective only. Omit token_budget so the goal stays unlimited, and put lifecycle status changes on update_goal.";
 function parseUserPromptSubmitPayload(raw) {
@@ -3127,23 +3435,41 @@ function optionalString(value) {
   return value === undefined || typeof value === "string";
 }
 function readAll(stdin) {
-  return new Promise((resolve4, reject) => {
+  return new Promise((resolve5, reject) => {
     let data = "";
     stdin.setEncoding("utf8");
     stdin.on("data", (chunk) => {
       data += chunk instanceof Buffer ? chunk.toString() : String(chunk);
     });
     stdin.once("error", reject);
-    stdin.once("end", () => resolve4(data));
+    stdin.once("end", () => resolve5(data));
   });
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/spawn-guard.ts
-import { existsSync as existsSync7, readdirSync, readFileSync as readFileSync4, statSync as statSync2, writeFileSync } from "node:fs";
-import { join as join3 } from "node:path";
+// components/ulw-loop/src/spawn-guard.ts
+import { randomBytes } from "node:crypto";
+import {
+  existsSync as existsSync7,
+  mkdirSync,
+  openSync,
+  readdirSync as readdirSync2,
+  readFileSync as readFileSync4,
+  renameSync,
+  statSync as statSync2,
+  unlinkSync,
+  writeFileSync
+} from "node:fs";
+import { dirname as dirname2, join as join3 } from "node:path";
 var SPAWN_TOOL_TOKENS = new Set(["spawn_agent", "collaborationspawn_agent", "collaboration.spawn_agent"]);
 var DEFAULT_FANOUT_LIMIT = 60;
+var DEFAULT_REVIEW_SPAWN_LIMIT = 3;
 var GATE_MESSAGE_PATTERN = /lazycodex-gate-reviewer|omo-senpi-gate-reviewer|final gate review/i;
+var REVIEW_AGENT_TYPES = [
+  ...Object.values(REVIEWER_ROLES_BY_SURFACE).map((roles) => roles.gateReview),
+  ...Object.values(REVIEWER_ROLES_BY_SURFACE).map((roles) => roles.codeReview),
+  ...Object.values(REVIEWER_ROLES_BY_SURFACE).map((roles) => roles.manualQa)
+];
+var REVIEW_AGENT_TYPE_SET = new Set(REVIEW_AGENT_TYPES);
 function applySpawnGuards(payload) {
   if (payload.hook_event_name !== "PreToolUse" || !SPAWN_TOOL_TOKENS.has(payload.tool_name))
     return "";
@@ -3151,12 +3477,18 @@ function applySpawnGuards(payload) {
   const plan = readPlan(join3(stateDir, "goals.json"));
   if (plan === null)
     return "";
-  const fanOutDenial = consumeFanOutBudget(stateDir);
-  if (fanOutDenial !== null)
-    return deny(fanOutDenial);
+  const fanOutPeek = peekFanOutBudget(stateDir);
+  if (fanOutPeek !== null)
+    return deny(fanOutPeek);
   const missingArtifact = missingGateArtifact(payload, plan);
   if (missingArtifact !== null)
     return deny(`spawn code-review + QA first; gate audits their artifacts: missing ${missingArtifact}`);
+  const reviewDenial = consumeReviewSpawnBudget(payload, plan, stateDir);
+  if (reviewDenial !== null)
+    return deny(reviewDenial);
+  const fanOutDenial = consumeFanOutBudget(stateDir);
+  if (fanOutDenial !== null)
+    return deny(fanOutDenial);
   return "";
 }
 async function runSpawnGuardCli(stdin, stdout) {
@@ -3175,15 +3507,44 @@ async function runSpawnGuardCli(stdin, stdout) {
       return;
   }
 }
+function peekFanOutBudget(stateDir) {
+  const counterPath = join3(stateDir, "spawn-count.json");
+  const count = readCount(counterPath) + 1;
+  const limit = fanOutLimit();
+  if (count <= limit)
+    return null;
+  return `ulw-loop spawn fan-out cap reached (${count}/${limit}). Consolidate work into the agents already running, or raise OMO_SPAWN_FANOUT_LIMIT if this volume is intentional.`;
+}
 function consumeFanOutBudget(stateDir) {
   const counterPath = join3(stateDir, "spawn-count.json");
   const count = readCount(counterPath) + 1;
-  writeFileSync(counterPath, JSON.stringify({ count }));
+  atomicWriteJson(counterPath, { count });
   const limit = fanOutLimit();
   if (count <= limit)
     return null;
   return `ulw-loop spawn fan-out cap reached (${count}/${limit}). Consolidate work into the agents already running, or raise OMO_SPAWN_FANOUT_LIMIT if this volume is intentional.`;
 }
+function consumeReviewSpawnBudget(payload, plan, stateDir) {
+  const agentType = reviewAgentType(payload.tool_input);
+  if (agentType === null)
+    return null;
+  const goal3 = plan.goals.find((candidate) => candidate.id === plan.activeGoalId) ?? plan.goals.find((candidate) => isFinalRunCompletionCandidate(plan, candidate));
+  if (goal3 === undefined)
+    return null;
+  const counterPath = join3(stateDir, "review-spawn-counts.json");
+  const lockPath = `${counterPath}.lock`;
+  const limit = reviewSpawnLimit();
+  return withExclusiveLock(lockPath, () => {
+    const counts = readCounts(counterPath);
+    const key = `${agentType}:${goal3.id}:a${goal3.attempt}`;
+    const count = (counts[key] ?? 0) + 1;
+    if (count > limit)
+      return `ulw-loop reviewer no-progress cap reached (${agentType} ${count}/${limit}) for ${goal3.id} attempt ${goal3.attempt}. Consolidate existing review findings, or checkpoint and start a new attempt after concrete progress.`;
+    counts[key] = count;
+    atomicWriteJson(counterPath, counts);
+    return null;
+  });
+}
 function missingGateArtifact(payload, plan) {
   if (!isGateReviewerSpawn(payload.tool_input))
     return null;
@@ -3193,9 +3554,11 @@ function missingGateArtifact(payload, plan) {
   if (!goal3.successCriteria.every((criterion) => criterion.status === "pass"))
     return null;
   const scope = { sessionId: payload.session_id };
+  const surface = resolveToolkitSurface();
+  const requiredArtifacts = surface === "omo-senpi" ? [`${goal3.id}-manual-qa.md`] : [`${goal3.id}-code-review.md`, `${goal3.id}-manual-qa.md`];
   if (plan.evidenceLayoutVersion === 2) {
     const attemptDir = ulwLoopAttemptEvidenceDir(goal3.id, goal3.attempt, scope);
-    for (const name of [`${goal3.id}-code-review.md`, `${goal3.id}-manual-qa.md`]) {
+    for (const name of requiredArtifacts) {
       const relative2 = `${attemptDir}/${name}`;
       if (!isNonEmptyFile(join3(payload.cwd, relative2)))
         return relative2;
@@ -3203,21 +3566,97 @@ function missingGateArtifact(payload, plan) {
     return null;
   }
   const flatReport = `.omo/evidence/${goal3.id}-code-review.md`;
-  if (!isNonEmptyFile(join3(payload.cwd, flatReport)))
+  if (surface !== "omo-senpi" && !isNonEmptyFile(join3(payload.cwd, flatReport)))
     return flatReport;
+  if (surface === "omo-senpi") {
+    const manualQa = `.omo/evidence/${goal3.id}-manual-qa.md`;
+    return isNonEmptyFile(join3(payload.cwd, manualQa)) ? null : manualQa;
+  }
   if (!hasOtherEvidenceFile(join3(payload.cwd, ".omo", "evidence"), `${goal3.id}-code-review.md`))
-    return `.omo/evidence/<any manual-QA artifact besides ${goal3.id}-code-review.md>`;
+    return `.omo/evidence/${goal3.id}-manual-qa.md`;
   return null;
 }
 function isGateReviewerSpawn(toolInput) {
+  const agentType = reviewAgentType(toolInput);
+  return agentType !== null && GATE_REVIEWER_AGENT_NAMES.has(agentType);
+}
+function reviewAgentType(toolInput) {
   if (typeof toolInput !== "object" || toolInput === null)
-    return false;
+    return null;
   const record = toolInput;
   const agentType = record["agent_type"];
-  if (typeof agentType === "string")
-    return GATE_REVIEWER_AGENT_NAMES.has(agentType);
+  if (typeof agentType === "string") {
+    if (!REVIEW_AGENT_TYPE_SET.has(agentType))
+      return null;
+    return activeSurfaceReviewerAlias(agentType);
+  }
   const message = record["message"];
-  return typeof message === "string" && GATE_MESSAGE_PATTERN.test(message);
+  if (typeof message !== "string")
+    return null;
+  const normalizedMessage = message.toLowerCase();
+  const allRoleNames = [...REVIEW_AGENT_TYPES];
+  const explicitAssignment = allRoleNames.map((name) => ({
+    name,
+    index: normalizedMessage.search(new RegExp(`\\bact as (?:an? )?${name}\\b`))
+  })).filter(({ index }) => index >= 0).sort((left, right) => left.index - right.index)[0];
+  if (explicitAssignment !== undefined)
+    return activeSurfaceReviewerAlias(explicitAssignment.name);
+  const nonReviewerActAs = /\bact as (?:an? )?\S+/.test(normalizedMessage);
+  if (nonReviewerActAs)
+    return null;
+  const namedReviewer = REVIEW_AGENT_TYPES.find((name) => normalizedMessage.includes(name));
+  if (namedReviewer !== undefined)
+    return activeSurfaceReviewerAlias(namedReviewer);
+  return GATE_MESSAGE_PATTERN.test(message) ? reviewerRolesFor(resolveToolkitSurface()).gateReview : null;
+}
+function activeSurfaceReviewerAlias(reviewer) {
+  const activeRoles = reviewerRolesFor(resolveToolkitSurface());
+  for (const roles of Object.values(REVIEWER_ROLES_BY_SURFACE)) {
+    if (reviewer === roles.codeReview)
+      return activeRoles.codeReview;
+    if (reviewer === roles.manualQa)
+      return activeRoles.manualQa;
+    if (reviewer === roles.gateReview)
+      return activeRoles.gateReview;
+  }
+  return reviewer;
+}
+function withExclusiveLock(lockPath, fn) {
+  mkdirSync(dirname2(lockPath), { recursive: true });
+  const maxAttempts = 10;
+  const baseDelayMs = 10;
+  for (let attempt = 0;attempt < maxAttempts; attempt++) {
+    let fd = null;
+    try {
+      fd = openSync(lockPath, "wx");
+      writeFileSync(fd, process.pid.toString());
+      try {
+        return fn();
+      } finally {
+        try {
+          unlinkSync(lockPath);
+        } catch {}
+      }
+    } catch (error) {
+      if (fd !== null) {
+        try {
+          unlinkSync(lockPath);
+        } catch {}
+      }
+      if (error.code !== "EEXIST") {
+        return fn();
+      }
+      const delayMs = baseDelayMs * 2 ** attempt + Math.random() * baseDelayMs;
+      const deadline = Date.now() + delayMs;
+      while (Date.now() < deadline) {}
+    }
+  }
+  return fn();
+}
+function atomicWriteJson(targetPath, data) {
+  const tmp = join3(dirname2(targetPath), `.tmp-${randomBytes(6).toString("hex")}`);
+  writeFileSync(tmp, JSON.stringify(data));
+  renameSync(tmp, targetPath);
 }
 function deny(reason) {
   return `${JSON.stringify({
@@ -3237,6 +3676,13 @@ function fanOutLimit() {
   const parsed = Number.parseInt(raw, 10);
   return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_FANOUT_LIMIT;
 }
+function reviewSpawnLimit() {
+  const raw = process.env["OMO_ULW_LOOP_REVIEW_SPAWN_LIMIT"];
+  if (raw === undefined)
+    return DEFAULT_REVIEW_SPAWN_LIMIT;
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_REVIEW_SPAWN_LIMIT;
+}
 function isNonEmptyFile(path) {
   try {
     return existsSync7(path) && statSync2(path).size > 0;
@@ -3248,7 +3694,7 @@ function isNonEmptyFile(path) {
 }
 function hasOtherEvidenceFile(evidenceDir, excludedName) {
   try {
-    return readdirSync(evidenceDir).some((name) => name !== excludedName && isNonEmptyFile(join3(evidenceDir, name)));
+    return readdirSync2(evidenceDir).some((name) => name !== excludedName && isNonEmptyFile(join3(evidenceDir, name)));
   } catch (error) {
     if (error instanceof Error)
       return false;
@@ -3265,6 +3711,23 @@ function readCount(counterPath) {
     throw error;
   }
 }
+function readCounts(counterPath) {
+  try {
+    const parsed = JSON.parse(readFileSync4(counterPath, "utf8"));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+      return {};
+    const counts = {};
+    for (const [key, value] of Object.entries(parsed)) {
+      if (typeof value === "number" && value >= 0)
+        counts[key] = value;
+    }
+    return counts;
+  } catch (error) {
+    if (error instanceof Error)
+      return {};
+    throw error;
+  }
+}
 function readPlan(goalsPath) {
   try {
     return JSON.parse(readFileSync4(goalsPath, "utf8"));
@@ -3275,9 +3738,9 @@ function readPlan(goalsPath) {
   }
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/stop-resume-hook.ts
+// components/ulw-loop/src/stop-resume-hook.ts
 import { existsSync as existsSync8, readFileSync as readFileSync5, writeFileSync as writeFileSync2 } from "node:fs";
-import { isAbsolute as isAbsolute2, join as join4, resolve as resolve4, sep as sep2 } from "node:path";
+import { isAbsolute as isAbsolute2, join as join4, resolve as resolve5, sep as sep2 } from "node:path";
 var RESUME_CAP = 2;
 var CONTEXT_PRESSURE_MARKERS2 = [
   "context compacted",
@@ -3335,8 +3798,8 @@ function isResumableStatus(status2) {
 }
 function consumeResumeBudget(stateDir, goalId) {
   const ledgerLineCount = countLedgerLines(join4(stateDir, "ledger.jsonl"));
-  const counterPath = resolve4(stateDir, `auto-resume-${goalId}.json`);
-  const stuckPath = resolve4(stateDir, `auto-resume-${goalId}.stuck`);
+  const counterPath = resolve5(stateDir, `auto-resume-${goalId}.json`);
+  const stuckPath = resolve5(stateDir, `auto-resume-${goalId}.stuck`);
   if (!isInsideDir(stateDir, counterPath) || !isInsideDir(stateDir, stuckPath))
     return false;
   const previous = readCounter(counterPath);
@@ -3350,7 +3813,7 @@ function consumeResumeBudget(stateDir, goalId) {
   return true;
 }
 function isInsideDir(dir, candidate) {
-  return candidate.startsWith(resolve4(dir) + sep2);
+  return candidate.startsWith(resolve5(dir) + sep2);
 }
 function renderResumeDirective(plan, goal3, sessionId) {
   const normalized = normalizeUlwLoopSessionId(sessionId);
@@ -3460,7 +3923,7 @@ function parseStopPayload(value) {
   };
 }
 
-// packages/omo-codex/plugin/components/ulw-loop/src/cli.ts
+// components/ulw-loop/src/cli.ts
 async function main() {
   const argv = process.argv.slice(2);
   const command = argv[0];