lazycodex-ai 5.0.0-beta.4 → 5.0.0-beta.40

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

@@ -1,142 +1,74 @@
-import { resolve } from "node:path";
-import { isWithinAttemptDir } from "./paths.js";
-import { emptyBlockers, invalid, literal, numberField, section, stringArray, textField, } from "./quality-gate-fields.js";
+import { artifactCompatible, artifactMap, checkFile, compatibleKindsFor, parseArtifactRefs, referencedArtifacts, surfaceField, } from "./quality-gate-artifacts.js";
+import { emptyBlockers, invalid, isPoisoned, isPoisonedArtifactKind, literal, numberField, section, stringArray, textField, withQualityGateCollector, } from "./quality-gate-fields.js";
 import { adversarialVerdict, codeQualityStatusField, passedVerdict } from "./quality-gate-verdicts.js";
-const REVIEWER_ROLES = {
-    codeReview: "lazycodex-code-reviewer",
-    manualQa: "lazycodex-qa-executor",
-    gateReview: "lazycodex-gate-reviewer",
-};
+import { GATE_SECTION_BY_ACCEPTOR } from "./surface.js";
 export { classifyExternalAuthorizationBlocker, clearGoalBlockerFields, normalizeBlockerEvidence, sameBlockerOccurrences, } from "./quality-gate-blockers.js";
 function reviewerRoleField(value, expected, field) {
+    if (typeof value !== "string" || value.trim() === "") {
+        textField(value, field);
+        return expected;
+    }
     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 === undefined)
-        return;
-    const absolute = resolve(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) {
-        const attemptRoot = resolve(opts.repoRoot, opts.currentAttemptDir);
-        if (!isWithinAttemptDir(absolute, attemptRoot))
-            invalid(`${field} (${path}) must point to an artifact from the current attempt (${opts.currentAttemptDir}).`, field);
+function reviewerAcceptorField(value, surface, sectionName) {
+    const field = `${sectionName}.by`;
+    const accepted = GATE_SECTION_BY_ACCEPTOR[surface][sectionName];
+    if (typeof value !== "string" || value.trim() === "") {
+        textField(value, field);
+        return accepted?.[0] ?? "";
     }
-}
-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;
-    });
+    const actual = textField(value, field);
+    if (accepted === undefined || !accepted.includes(actual))
+        invalid(`${field} must be one of ${accepted?.join(", ") ?? "the configured reviewers"}.`, field);
+    return actual;
 }
 export function validateQualityGate(input, opts) {
+    return withQualityGateCollector(() => validateQualityGateUncollected(input, opts));
+}
+function validateQualityGateUncollected(input, opts) {
+    const surface = opts?.reviewerSurface ?? "lazycodex";
     const gate = section(input, "qualityGate");
-    const codeReview = section(gate["codeReview"], "codeReview");
+    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 codeReview = surface === "lazycodex" ? section(gate["codeReview"], "codeReview") : {};
+    const manualQaBy = reviewerAcceptorField(manualQa["by"], surface, "manualQa");
+    const gateReviewBy = reviewerAcceptorField(gateReview["by"], surface, "gateReview");
+    const manualQaEvidence = textField(manualQa["evidence"], "manualQa.evidence");
+    const gateReviewEvidence = textField(gateReview["evidence"], "gateReview.evidence");
+    if (surface === "lazycodex")
+        reviewerRoleField(codeReview?.["by"], "lazycodex-code-reviewer", "codeReview.by");
     const totalCriteria = numberField(coverage["totalCriteria"], "criteriaCoverage.totalCriteria");
     const passCount = numberField(coverage["passCount"], "criteriaCoverage.passCount");
-    if (passCount < totalCriteria)
+    if (!isPoisoned("criteriaCoverage.passCount") && passCount < totalCriteria)
         invalid("criteriaCoverage.passCount must cover totalCriteria.", "criteriaCoverage.passCount");
     const artifactRefs = parseArtifactRefs(manualQa["artifactRefs"], 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"], REVIEWER_ROLES.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"),
-        },
+    if (!isPoisoned("gateReview.reportPath"))
+        checkFile(gateReportPath, "gateReview.reportPath", opts);
+    const common = {
         manualQa: {
-            by: reviewerRoleField(manualQa["by"], REVIEWER_ROLES.manualQa, "manualQa.by"),
+            by: manualQaBy,
             status: literal(manualQa["status"], "passed", "manualQa.status"),
-            evidence: textField(manualQa["evidence"], "manualQa.evidence"),
+            evidence: manualQaEvidence,
             surfaceEvidence,
             adversarialCases,
             artifactRefs,
         },
         gateReview: {
-            by: reviewerRoleField(gateReview["by"], REVIEWER_ROLES.gateReview, "gateReview.by"),
+            by: gateReviewBy,
             recommendation: literal(gateReview["recommendation"], "APPROVE", "gateReview.recommendation"),
             reportPath: gateReportPath,
-            evidence: textField(gateReview["evidence"], "gateReview.evidence"),
+            evidence: gateReviewEvidence,
             blockers: emptyBlockers(gateReview["blockers"], "gateReview.blockers"),
         },
         iteration: {
@@ -154,17 +86,39 @@ export function validateQualityGate(input, opts) {
             adversarialClassesCovered: stringArray(coverage["adversarialClassesCovered"], "criteriaCoverage.adversarialClassesCovered"),
         },
     };
+    if (surface === "omo-senpi")
+        return { surface, ...common };
+    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)
+    if (!Array.isArray(value) || value.length === 0) {
         invalid("manualQa.surfaceEvidence must not be empty.", "manualQa.surfaceEvidence");
-    return value.map((item, index) => {
+        return [];
+    }
+    return value.flatMap((item, index) => {
         const row = section(item, `manualQa.surfaceEvidence[${index}]`);
+        if (isPoisoned(`manualQa.surfaceEvidence[${index}]`))
+            return [];
         const surface = surfaceField(row["surface"], `manualQa.surfaceEvidence[${index}].surface`);
         const artifacts = referencedArtifacts(row["artifactRefs"], `manualQa.surfaceEvidence[${index}].artifactRefs`, byId);
         for (const artifact of artifacts) {
+            if (isPoisoned(`manualQa.surfaceEvidence[${index}].surface`) || isPoisonedArtifactKind(artifact.id))
+                continue;
             if (!artifactCompatible(surface, artifact.kind)) {
-                invalid(`manualQa.surfaceEvidence ${surface} artifact ${artifact.kind} is incompatible.`, "manualQa.surfaceEvidence");
+                invalid(`manualQa.surfaceEvidence ${surface} artifact ${artifact.kind} is incompatible; surface "${surface}" accepts artifact kinds: ${compatibleKindsFor(surface).join(", ")}.`, "manualQa.surfaceEvidence");
             }
         }
         return {
@@ -178,10 +132,14 @@ function parseSurfaceEvidence(value, byId) {
     });
 }
 function parseAdversarialCases(value, byId) {
-    if (!Array.isArray(value) || value.length === 0)
+    if (!Array.isArray(value) || value.length === 0) {
         invalid("manualQa.adversarialCases must not be empty.", "manualQa.adversarialCases");
-    return value.map((item, index) => {
+        return [];
+    }
+    return value.flatMap((item, index) => {
         const row = section(item, `manualQa.adversarialCases[${index}]`);
+        if (isPoisoned(`manualQa.adversarialCases[${index}]`))
+            return [];
         const artifacts = referencedArtifacts(row["artifactRefs"], `manualQa.adversarialCases[${index}].artifactRefs`, byId);
         const verdictInfo = adversarialVerdict(row, `manualQa.adversarialCases[${index}]`);
         return {

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

@@ -1,4 +1,5 @@
 // biome-ignore-all format: compact port must stay within the requested pure LOC budget.
+import { codexSnapshotMismatchError } from "./checkpoint-reconciliation.js";
 import { readCodexGoalSnapshotInput, reconcileCodexGoalSnapshot } from "./codex-goal-snapshot.js";
 import { codexGoalMode, compatibleCodexObjectives, expectedCodexObjective, isFinalRunCompletionCandidate } from "./goal-status.js";
 import { seedDefaultSuccessCriteria } from "./plan-crud.js";
@@ -42,9 +43,10 @@ export 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);

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

@@ -1,14 +1,23 @@
-import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
 import { parsePreToolUsePayload } from "./codex-hook.js";
 import { isFinalRunCompletionCandidate } from "./goal-status.js";
 import { ulwLoopAttemptEvidenceDir, ulwLoopDir } from "./paths.js";
+import { GATE_REVIEWER_AGENT_NAMES, REVIEWER_ROLES_BY_SURFACE, resolveToolkitSurface, reviewerRolesFor, } from "./surface.js";
 // spawn_agent = v1; collaborationspawn_agent = the delimiter-free flattened v2
 // hook token from codex-rs hook_names.rs; collaboration.spawn_agent = the
 // dotted token observed live in the task-1 probe (hook-tool-tokens.txt).
 const SPAWN_TOOL_TOKENS = new Set(["spawn_agent", "collaborationspawn_agent", "collaboration.spawn_agent"]);
 const DEFAULT_FANOUT_LIMIT = 60;
-const GATE_MESSAGE_PATTERN = /lazycodex-gate-reviewer|final gate review/i;
+const DEFAULT_REVIEW_SPAWN_LIMIT = 3;
+const GATE_MESSAGE_PATTERN = /lazycodex-gate-reviewer|omo-senpi-gate-reviewer|final gate review/i;
+const 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),
+];
+const REVIEW_AGENT_TYPE_SET = new Set(REVIEW_AGENT_TYPES);
 export function applySpawnGuards(payload) {
     if (payload.hook_event_name !== "PreToolUse" || !SPAWN_TOOL_TOKENS.has(payload.tool_name))
         return "";
@@ -16,12 +25,18 @@ export function applySpawnGuards(payload) {
     const plan = readPlan(join(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 "";
 }
 export async function runSpawnGuardCli(stdin, stdout) {
@@ -41,17 +56,51 @@ export async function runSpawnGuardCli(stdin, stdout) {
             return;
     }
 }
+// Read-only fan-out eligibility check. Returns a denial reason when the next
+// spawn would exceed the limit, without incrementing the counter. Call this
+// before charging any per-reviewer quota so a saturated global cap cannot
+// silently consume reviewer allowances for spawns that will never run.
+function peekFanOutBudget(stateDir) {
+    const counterPath = join(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.`;
+}
 // Per-session spawn counter; depth/lineage tracking is descoped — this is a
 // total-volume backstop against fan-out explosions, not a recursion tracker.
 function consumeFanOutBudget(stateDir) {
     const counterPath = join(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 goal = plan.goals.find((candidate) => candidate.id === plan.activeGoalId) ??
+        plan.goals.find((candidate) => isFinalRunCompletionCandidate(plan, candidate));
+    if (goal === undefined)
+        return null;
+    const counterPath = join(stateDir, "review-spawn-counts.json");
+    const lockPath = `${counterPath}.lock`;
+    const limit = reviewSpawnLimit();
+    return withExclusiveLock(lockPath, () => {
+        const counts = readCounts(counterPath);
+        const key = `${agentType}:${goal.id}:a${goal.attempt}`;
+        const count = (counts[key] ?? 0) + 1;
+        if (count > limit)
+            return `ulw-loop reviewer no-progress cap reached (${agentType} ${count}/${limit}) for ${goal.id} attempt ${goal.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;
@@ -61,9 +110,11 @@ function missingGateArtifact(payload, plan) {
     if (!goal.successCriteria.every((criterion) => criterion.status === "pass"))
         return null;
     const scope = { sessionId: payload.session_id };
+    const surface = resolveToolkitSurface();
+    const requiredArtifacts = surface === "omo-senpi" ? [`${goal.id}-manual-qa.md`] : [`${goal.id}-code-review.md`, `${goal.id}-manual-qa.md`];
     if (plan.evidenceLayoutVersion === 2) {
         const attemptDir = ulwLoopAttemptEvidenceDir(goal.id, goal.attempt, scope);
-        for (const name of [`${goal.id}-code-review.md`, `${goal.id}-manual-qa.md`]) {
+        for (const name of requiredArtifacts) {
             const relative = `${attemptDir}/${name}`;
             if (!isNonEmptyFile(join(payload.cwd, relative)))
                 return relative;
@@ -71,22 +122,117 @@ function missingGateArtifact(payload, plan) {
         return null;
     }
     const flatReport = `.omo/evidence/${goal.id}-code-review.md`;
-    if (!isNonEmptyFile(join(payload.cwd, flatReport)))
+    if (surface !== "omo-senpi" && !isNonEmptyFile(join(payload.cwd, flatReport)))
         return flatReport;
+    if (surface === "omo-senpi") {
+        const manualQa = `.omo/evidence/${goal.id}-manual-qa.md`;
+        return isNonEmptyFile(join(payload.cwd, manualQa)) ? null : manualQa;
+    }
     // v1 manual-QA approximation: any other non-empty evidence file counts.
     if (!hasOtherEvidenceFile(join(payload.cwd, ".omo", "evidence"), `${goal.id}-code-review.md`))
-        return `.omo/evidence/<any manual-QA artifact besides ${goal.id}-code-review.md>`;
+        return `.omo/evidence/${goal.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 agentType === "lazycodex-gate-reviewer";
+    if (typeof agentType === "string") {
+        // V1: agent_type is present — only reviewer types proceed; any other type is not a review spawn.
+        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();
+    // Explicit "act as <role>" assignment takes priority. If the assigned role is not a reviewer,
+    // treat the spawn as non-review so a message that merely mentions a reviewer name does not
+    // accidentally charge that reviewer's quota.
+    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);
+    // Check for an explicit "act as <non-reviewer-role>" assignment. If found, the spawn is not a
+    // review spawn even if the message body mentions a reviewer 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(dirname(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 {
+                    /* empty */
+                }
+            }
+        }
+        catch (error) {
+            if (fd !== null) {
+                try {
+                    unlinkSync(lockPath);
+                }
+                catch {
+                    /* empty */
+                }
+            }
+            if (error.code !== "EEXIST") {
+                return fn();
+            }
+            const delayMs = baseDelayMs * 2 ** attempt + Math.random() * baseDelayMs;
+            const deadline = Date.now() + delayMs;
+            while (Date.now() < deadline) {
+                /* spin */
+            }
+        }
+    }
+    return fn();
+}
+function atomicWriteJson(targetPath, data) {
+    const tmp = join(dirname(targetPath), `.tmp-${randomBytes(6).toString("hex")}`);
+    writeFileSync(tmp, JSON.stringify(data));
+    renameSync(tmp, targetPath);
 }
 function deny(reason) {
     return `${JSON.stringify({
@@ -105,6 +251,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 existsSync(path) && statSync(path).size > 0;
@@ -136,6 +289,24 @@ function readCount(counterPath) {
         throw error;
     }
 }
+function readCounts(counterPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(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(readFileSync(goalsPath, "utf8"));

package/packages/omo-codex/plugin/components/ulw-loop/dist/status-next-actions.d.ts

@@ -0,0 +1,6 @@
+import type { UlwLoopPlan } from "./types.js";
+/**
+ * `status --json` is the one call every agent already makes between steps, so it is
+ * also the cheapest place to answer "what now?" without a second round trip.
+ */
+export declare function statusNextActions(plan: UlwLoopPlan): readonly string[];

package/packages/omo-codex/plugin/components/ulw-loop/dist/status-next-actions.js

@@ -0,0 +1,33 @@
+import { hasAllCriteriaPass, isFinalRunCompletionCandidate } from "./goal-status.js";
+import { ULW_LOOP_CREATE_GOALS_COMMAND } from "./plan-missing-recovery.js";
+/**
+ * `status --json` is the one call every agent already makes between steps, so it is
+ * also the cheapest place to answer "what now?" without a second round trip.
+ */
+export 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>'\`.`,
+    ];
+}

package/packages/omo-codex/plugin/components/ulw-loop/dist/stop-resume-hook.js

@@ -5,7 +5,7 @@ import { normalizeUlwLoopSessionId, ulwLoopDir } from "./paths.js";
 // dies mid-turn (crash, kill, context blowup before any Stop) never reaches
 // this handler. Mid-turn stalls are out of scope by design.
 const RESUME_CAP = 2;
-// Mirrors start-work-continuation's context-pressure bail-out: injecting a
+// Mirrors ulw-execute-continuation's context-pressure bail-out: injecting a
 // resume directive into an already-overflowing context makes things worse.
 const CONTEXT_PRESSURE_MARKERS = [
     "context compacted",
@@ -132,7 +132,7 @@ function readCounter(counterPath) {
         throw error;
     }
 }
-// Local ~10-LOC approximation of start-work-continuation's boulder check (no
+// Local ~10-LOC approximation of ulw-execute-continuation's boulder check (no
 // cross-component import allowed): any continuable work for this session means
 // that hook owns the Stop event, so this one stays silent.
 function boulderContinuationWillFire(cwd, sessionId) {
@@ -167,7 +167,7 @@ function transcriptShowsContextPressure(transcriptPath) {
         throw error;
     }
 }
-// start-work-continuation owns an active Boulder plan until its final gate marks
+// ulw-execute-continuation owns an active Boulder plan until its final gate marks
 // the work complete, including the zero-remaining checklist state.
 function boulderPlanHasChecklist(cwd, entry) {
     const activePlan = entry["active_plan"];

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

@@ -0,0 +1,18 @@
+export type UlwLoopToolkitSurface = "lazycodex" | "omo-senpi";
+export interface UlwLoopReviewerRoles {
+    readonly codeReview: string;
+    readonly manualQa: string;
+    readonly gateReview: string;
+}
+export declare const REVIEWER_ROLES_BY_SURFACE: Readonly<Record<UlwLoopToolkitSurface, UlwLoopReviewerRoles>>;
+export declare const GATE_REVIEWER_AGENT_NAMES: ReadonlySet<string>;
+export type UlwLoopGateSection = "codeReview" | "manualQa" | "gateReview" | "iteration" | "criteriaCoverage";
+export declare const REQUIRED_GATE_SECTIONS_BY_SURFACE: Readonly<Record<UlwLoopToolkitSurface, readonly UlwLoopGateSection[]>>;
+export declare const GATE_SECTION_BY_ACCEPTOR: Readonly<Record<UlwLoopToolkitSurface, Readonly<Partial<Record<UlwLoopGateSection, readonly string[]>>>>>;
+export declare function reviewerRolesFor(surface: UlwLoopToolkitSurface): UlwLoopReviewerRoles;
+export declare const SURFACE_MARKER_FILENAME = "surface.json";
+export interface ResolveToolkitSurfaceOptions {
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly entryDir?: string;
+}
+export declare function resolveToolkitSurface(options?: ResolveToolkitSurfaceOptions): UlwLoopToolkitSurface;