lazycodex-ai 5.0.0-beta.6 → 5.0.0-beta.61

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

@@ -0,0 +1,28 @@
+export const ULW_LOOP_OPERATIONS = [
+    "help",
+    "create-goals",
+    "status",
+    "complete-goals",
+    "checkpoint",
+    "steer",
+    "add-goal",
+    "criteria",
+    "record-evidence",
+    "record-review-blockers",
+];
+export const ULW_LOOP_MANIFEST = {
+    version: 1,
+    name: "ulw-loop",
+    operations: [
+        { name: "help", mutating: false },
+        { name: "create-goals", mutating: true },
+        { name: "status", mutating: false },
+        { name: "complete-goals", mutating: true },
+        { name: "checkpoint", mutating: true },
+        { name: "steer", mutating: true },
+        { name: "add-goal", mutating: true },
+        { name: "criteria", mutating: false },
+        { name: "record-evidence", mutating: true },
+        { name: "record-review-blockers", mutating: true },
+    ],
+};

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

@@ -0,0 +1,127 @@
+import type { CheckpointUlwLoopArgs, CheckpointUlwLoopResult } from "../checkpoint.js";
+import type { CheckpointTemplate } from "../checkpoint-template.js";
+import type { recordEvidence } from "../evidence.js";
+import type { addUlwLoopGoal, createUlwLoopPlan, startNextUlwLoop, summarizeUlwLoopPlan } from "../plan-crud.js";
+import type { recordFinalReviewBlockers } from "../review-blockers.js";
+import type { steerUlwLoop } from "../steering.js";
+import type { UlwLoopSteeringProposal } from "../steering-types.js";
+import type { UlwLoopToolkitSurface } from "../surface.js";
+import type { UlwLoopPlan } from "../types.js";
+import type { ULW_LOOP_MANIFEST, UlwLoopOperation } from "./manifest.js";
+export type ToolkitSurface = UlwLoopToolkitSurface;
+export interface ToolkitContext {
+    readonly cwd: string;
+    readonly sessionId: string;
+    readonly surface: ToolkitSurface;
+}
+export type CreateGoalsArgs = Parameters<typeof createUlwLoopPlan>[1];
+export type CompleteGoalsArgs = NonNullable<Parameters<typeof startNextUlwLoop>[1]>;
+export type SteerArgs = UlwLoopSteeringProposal;
+export type AddGoalArgs = Parameters<typeof addUlwLoopGoal>[1];
+export type RecordEvidenceArgs = Parameters<typeof recordEvidence>[1];
+export type CriteriaArgs = {
+    readonly goalId: string;
+};
+export type CheckpointMutationArgs = CheckpointUlwLoopArgs & {
+    readonly printTemplate?: false;
+};
+export type CheckpointTemplateArgs = {
+    readonly printTemplate: true;
+    readonly goalId?: string;
+};
+export type CheckpointArgs = CheckpointMutationArgs | CheckpointTemplateArgs;
+export type RecordReviewBlockersArgs = Parameters<typeof recordFinalReviewBlockers>[1];
+export type ToolkitDispatchRequest = {
+    readonly operation: "help";
+    readonly args?: Record<never, never>;
+} | {
+    readonly operation: "create-goals";
+    readonly args: CreateGoalsArgs;
+} | {
+    readonly operation: "status";
+    readonly args?: Record<never, never>;
+} | {
+    readonly operation: "complete-goals";
+    readonly args?: CompleteGoalsArgs;
+} | {
+    readonly operation: "checkpoint";
+    readonly args: CheckpointArgs;
+} | {
+    readonly operation: "steer";
+    readonly args: SteerArgs;
+} | {
+    readonly operation: "add-goal";
+    readonly args: AddGoalArgs;
+} | {
+    readonly operation: "criteria";
+    readonly args: CriteriaArgs;
+} | {
+    readonly operation: "record-evidence";
+    readonly args: RecordEvidenceArgs;
+} | {
+    readonly operation: "record-review-blockers";
+    readonly args: RecordReviewBlockersArgs;
+};
+export interface ToolkitUnknownRequest {
+    readonly operation: string;
+    readonly args?: Record<never, never>;
+}
+export interface ToolkitError {
+    readonly code: string;
+    readonly message: string;
+    readonly details?: Readonly<Record<string, string>>;
+}
+export interface ToolkitSuccess<Operation extends UlwLoopOperation, Result> {
+    readonly ok: true;
+    readonly operation: Operation;
+    readonly result: Result;
+    readonly nextActions: readonly string[];
+    readonly warnings?: readonly string[];
+}
+export interface ToolkitFailure<Operation extends string = string> {
+    readonly ok: false;
+    readonly operation: Operation;
+    readonly error: ToolkitError;
+}
+type StatusResult = {
+    readonly plan: UlwLoopPlan;
+    readonly summary: ReturnType<typeof summarizeUlwLoopPlan>;
+    readonly nextActions: readonly string[];
+    readonly currentAttemptDir?: string;
+};
+type ResultFor<Operation extends UlwLoopOperation> = Operation extends "help" ? typeof ULW_LOOP_MANIFEST : Operation extends "create-goals" ? Awaited<ReturnType<typeof createUlwLoopPlan>> : Operation extends "status" ? StatusResult : Operation extends "complete-goals" ? Awaited<ReturnType<typeof startNextUlwLoop>> : Operation extends "checkpoint" ? CheckpointUlwLoopResult | CheckpointTemplate : Operation extends "steer" ? Awaited<ReturnType<typeof steerUlwLoop>> : Operation extends "add-goal" ? Awaited<ReturnType<typeof addUlwLoopGoal>> : Operation extends "criteria" ? {
+    readonly goalId: string;
+    readonly criteria: UlwLoopPlan["goals"][number]["successCriteria"];
+} : Operation extends "record-evidence" ? Awaited<ReturnType<typeof recordEvidence>> : Operation extends "record-review-blockers" ? Awaited<ReturnType<typeof recordFinalReviewBlockers>> : never;
+export type ToolkitResultFor<Operation extends UlwLoopOperation> = ResultFor<Operation>;
+export type ToolkitResponseFor<Operation extends UlwLoopOperation> = ToolkitSuccess<Operation, ResultFor<Operation>> | ToolkitFailure<Operation>;
+export type ToolkitOperationResponse = {
+    [Operation in UlwLoopOperation]: ToolkitResponseFor<Operation>;
+}[UlwLoopOperation];
+export type ToolkitDispatchResponse = ToolkitOperationResponse | ToolkitFailure<string>;
+export type ToolkitResponse<Result> = ToolkitSuccess<UlwLoopOperation, Result> | ToolkitFailure<string>;
+export interface ToolkitOperationHookEvent<Operation extends UlwLoopOperation = UlwLoopOperation> {
+    readonly operation: Operation;
+    readonly context: ToolkitContext;
+    readonly response: ToolkitResponseFor<Operation>;
+}
+export interface ToolkitHostHooks {
+    readonly onOperation?: <Operation extends UlwLoopOperation>(event: ToolkitOperationHookEvent<Operation>) => void | Promise<void>;
+}
+export interface AgentToolkitDependencies {
+    readonly hooks?: ToolkitHostHooks;
+}
+export interface AgentToolkit {
+    readonly dispatch: (request: ToolkitDispatchRequest | ToolkitUnknownRequest) => Promise<ToolkitDispatchResponse>;
+    readonly help: () => Promise<ToolkitResponseFor<"help">>;
+    readonly createGoals: (args: CreateGoalsArgs) => Promise<ToolkitResponseFor<"create-goals">>;
+    readonly status: () => Promise<ToolkitResponseFor<"status">>;
+    readonly completeGoals: (args?: CompleteGoalsArgs) => Promise<ToolkitResponseFor<"complete-goals">>;
+    readonly checkpoint: (args: CheckpointArgs) => Promise<ToolkitResponseFor<"checkpoint">>;
+    readonly steer: (args: SteerArgs) => Promise<ToolkitResponseFor<"steer">>;
+    readonly addGoal: (args: AddGoalArgs) => Promise<ToolkitResponseFor<"add-goal">>;
+    readonly criteria: (args: CriteriaArgs) => Promise<ToolkitResponseFor<"criteria">>;
+    readonly recordEvidence: (args: RecordEvidenceArgs) => Promise<ToolkitResponseFor<"record-evidence">>;
+    readonly recordReviewBlockers: (args: RecordReviewBlockersArgs) => Promise<ToolkitResponseFor<"record-review-blockers">>;
+}
+export {};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,3 @@
+export { createAgentToolkit } from "./sdk/factory.js";
+export * from "./sdk/manifest.js";
+export * from "./sdk/types.js";

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

@@ -0,0 +1,3 @@
+export { createAgentToolkit } from "./sdk/factory.js";
+export * from "./sdk/manifest.js";
+export * from "./sdk/types.js";

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

@@ -1,3 +1,9 @@
 import type { PreToolUsePayload } from "./codex-hook.js";
-export declare function applySpawnGuards(payload: PreToolUsePayload): string;
+export declare const DEFAULT_FANOUT_LIMIT = 24;
+export interface SpawnGuardOptions {
+    readonly lockTimeoutMs?: number;
+}
+export declare function applySpawnGuards(payload: PreToolUsePayload, options?: SpawnGuardOptions): string;
+export declare function applySpawnBudgetGuards(payload: PreToolUsePayload, options?: SpawnGuardOptions): string;
+export declare function runSpawnAdmissionRecorderCli(stdin: NodeJS.ReadableStream, stdout: NodeJS.WritableStream): Promise<void>;
 export declare function runSpawnGuardCli(stdin: NodeJS.ReadableStream, stdout: NodeJS.WritableStream): Promise<void>;

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

@@ -1,57 +1,168 @@
-import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, 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 { ulwLoopAttemptEvidenceDir, ulwLoopDir, ulwLoopStateLockPath } from "./paths.js";
+import { spawnRoleDenial } from "./spawn-role-guard.js";
+import { isStateLockTimeout, withStateLockSync } from "./state-lock.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;
-export function applySpawnGuards(payload) {
+const SPAWN_TOOL_TOKENS = new Set([
+    "spawn_agent",
+    "multi_agent_v1.spawn_agent",
+    "collaborationspawn_agent",
+    "collaboration.spawn_agent",
+]);
+export const DEFAULT_FANOUT_LIMIT = 24;
+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, options = {}) {
     if (payload.hook_event_name !== "PreToolUse" || !SPAWN_TOOL_TOKENS.has(payload.tool_name))
         return "";
-    const stateDir = ulwLoopDir(payload.cwd, { sessionId: payload.session_id });
+    if (resolveToolkitSurface() === "lazycodex") {
+        const reason = spawnRoleDenial(payload.tool_input);
+        if (reason !== null)
+            return deny(reason);
+    }
+    return applySpawnBudgetGuards(payload, options);
+}
+export function applySpawnBudgetGuards(payload, options = {}) {
+    if (payload.hook_event_name !== "PreToolUse" || !SPAWN_TOOL_TOKENS.has(payload.tool_name))
+        return "";
+    const breaker = readAdmissionBreaker(payload.session_id);
+    if (breaker !== null)
+        return deny(`Subagent admission failed earlier in this session (${breaker}). Do not spawn more workers or reviewers; report the capacity block and wait for the user.`);
+    const scope = { sessionId: payload.session_id };
+    const stateDir = ulwLoopDir(payload.cwd, scope);
     const plan = readPlan(join(stateDir, "goals.json"));
     if (plan === null)
         return "";
+    const lockOptions = options.lockTimeoutMs === undefined ? {} : { timeoutMs: options.lockTimeoutMs };
+    try {
+        return withStateLockSync(ulwLoopStateLockPath(payload.cwd, scope), () => evaluateGuards(payload, plan, stateDir), lockOptions);
+    }
+    catch (error) {
+        if (isStateLockTimeout(error))
+            return deny(`ulw-loop spawn guard could not take the session state lock: ${error.message}`);
+        throw error;
+    }
+}
+function evaluateGuards(payload, plan, stateDir) {
+    const fanOutPeek = peekFanOutBudget(stateDir);
+    if (fanOutPeek !== null)
+        return deny(fanOutPeek);
+    const missingArtifact = missingGateArtifact(payload, plan);
+    if (missingArtifact !== null)
+        return deny(`record manual QA first; gate audits its 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);
-    const missingArtifact = missingGateArtifact(payload, plan);
-    if (missingArtifact !== null)
-        return deny(`spawn code-review + QA first; gate audits their artifacts: missing ${missingArtifact}`);
     return "";
 }
+export async function runSpawnAdmissionRecorderCli(stdin, stdout) {
+    const chunks = [];
+    for await (const chunk of stdin)
+        chunks.push(Buffer.from(chunk));
+    try {
+        const payload = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        const response = typeof payload["tool_response"] === "string"
+            ? payload["tool_response"]
+            : JSON.stringify(payload["tool_response"] ?? "");
+        if (!/too many active cells|AgentLimitReached|max_threads|max_concurrent_threads_per_session/i.test(response))
+            return;
+        const dataDir = process.env["PLUGIN_DATA"];
+        if (typeof dataDir !== "string" || typeof payload["session_id"] !== "string")
+            return;
+        const markerDir = join(dataDir, "spawn-breaker");
+        try {
+            mkdirSync(markerDir, { recursive: true });
+            atomicWriteJson(join(markerDir, `${payload["session_id"]}.json`), {
+                reason: response,
+                at: new Date().toISOString(),
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`[ulw-loop] spawn-guard: could not persist admission failure: ${message}\n`);
+        }
+    }
+    catch {
+        /* malformed hook input is ignored */
+    }
+    void stdout;
+}
 export async function runSpawnGuardCli(stdin, stdout) {
     try {
         const chunks = [];
         for await (const chunk of stdin)
             chunks.push(Buffer.from(chunk));
         const payload = parsePreToolUsePayload(Buffer.concat(chunks).toString("utf8"));
-        if (payload === null)
+        if (payload === null) {
+            stdout.write(deny("LazyCodex spawn guard received an invalid hook payload; role routing was not verified."));
             return;
+        }
         const output = applySpawnGuards(payload);
         if (output.length > 0)
             stdout.write(output);
     }
     catch (error) {
-        if (error instanceof Error)
-            return;
+        stdout.write(deny(`LazyCodex spawn guard failed: ${error instanceof Error ? error.message : String(error)}`));
     }
 }
+// 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 limit = reviewSpawnLimit();
+    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,32 +172,77 @@ function missingGateArtifact(payload, plan) {
     if (!goal.successCriteria.every((criterion) => criterion.status === "pass"))
         return null;
     const scope = { sessionId: payload.session_id };
+    const requiredArtifacts = [`${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;
         }
         return null;
     }
-    const flatReport = `.omo/evidence/${goal.id}-code-review.md`;
-    if (!isNonEmptyFile(join(payload.cwd, flatReport)))
-        return flatReport;
-    // 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 null;
+    const manualQa = `.omo/evidence/${goal.id}-manual-qa.md`;
+    return isNonEmptyFile(join(payload.cwd, manualQa)) ? null : manualQa;
 }
 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 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({
@@ -98,6 +254,18 @@ function deny(reason) {
         },
     })}\n`;
 }
+function readAdmissionBreaker(sessionId) {
+    const dataDir = process.env["PLUGIN_DATA"];
+    if (typeof dataDir !== "string")
+        return null;
+    try {
+        const value = JSON.parse(readFileSync(join(dataDir, "spawn-breaker", `${sessionId}.json`), "utf8"));
+        return typeof value.reason === "string" ? value.reason : "capacity limit";
+    }
+    catch {
+        return null;
+    }
+}
 function fanOutLimit() {
     const raw = process.env["OMO_SPAWN_FANOUT_LIMIT"];
     if (raw === undefined)
@@ -105,6 +273,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;
@@ -115,24 +290,32 @@ function isNonEmptyFile(path) {
         throw error;
     }
 }
-function hasOtherEvidenceFile(evidenceDir, excludedName) {
+function readCount(counterPath) {
     try {
-        return readdirSync(evidenceDir).some((name) => name !== excludedName && isNonEmptyFile(join(evidenceDir, name)));
+        const parsed = JSON.parse(readFileSync(counterPath, "utf8"));
+        return typeof parsed["count"] === "number" && parsed["count"] >= 0 ? parsed["count"] : 0;
     }
     catch (error) {
         if (error instanceof Error)
-            return false;
+            return 0;
         throw error;
     }
 }
-function readCount(counterPath) {
+function readCounts(counterPath) {
     try {
         const parsed = JSON.parse(readFileSync(counterPath, "utf8"));
-        return typeof parsed["count"] === "number" && parsed["count"] >= 0 ? parsed["count"] : 0;
+        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 0;
+            return {};
         throw error;
     }
 }

package/packages/omo-codex/plugin/components/ulw-loop/dist/spawn-role-guard.d.ts

@@ -0,0 +1,2 @@
+export declare const LAZYCODEX_SPAWN_ROLES: ReadonlySet<string>;
+export declare function spawnRoleDenial(input: unknown): string | null;

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

@@ -0,0 +1,22 @@
+// Explicit selectors, pinned by a test to the bundled role TOMLs. The generated
+// default is a non-fork fallback, not a selector: a user can opt out of owning it.
+export const LAZYCODEX_SPAWN_ROLES = new Set([
+    "explorer",
+    "lazycodex-clone-fidelity-reviewer",
+    "lazycodex-code-reviewer",
+    "lazycodex-gate-reviewer",
+    "lazycodex-qa-executor",
+    "lazycodex-worker-high",
+    "lazycodex-worker-low",
+    "lazycodex-worker-medium",
+    "librarian",
+    "metis",
+    "momus",
+    "plan",
+]);
+export function spawnRoleDenial(input) {
+    const role = typeof input === "object" && input !== null && "agent_type" in input ? input.agent_type : undefined;
+    if (typeof role === "string" && LAZYCODEX_SPAWN_ROLES.has(role))
+        return null;
+    return `LazyCodex requires an explicit registered agent_type: ${[...LAZYCODEX_SPAWN_ROLES].join(", ")}. Received ${JSON.stringify(role) ?? "no agent_type"}. Use the matching role and fork_turns: "none" (V2) or fork_context: false (V1), unless full history is deliberately required. The hook cannot see the tool schema; if agent_type is unavailable, stop and report incompatible role routing rather than spawning a generic agent. Describing a role in message does not select its TOML.`;
+}

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

@@ -0,0 +1,9 @@
+import { UlwLoopError } from "./types.js";
+export declare const ULW_LOOP_LOCK_TIMEOUT_CODE = "ULW_LOOP_LOCK_TIMEOUT";
+export interface StateLockOptions {
+    readonly timeoutMs?: number;
+    readonly staleMs?: number;
+}
+export declare function withStateLock<T>(lockPath: string, fn: () => Promise<T>, options?: StateLockOptions): Promise<T>;
+export declare function withStateLockSync<T>(lockPath: string, fn: () => T, options?: StateLockOptions): T;
+export declare function isStateLockTimeout(error: unknown): error is UlwLoopError;