lazycodex-ai 5.0.0-beta.9 → 5.0.0

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

@@ -0,0 +1,67 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+export 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 === "object" && value !== null && "reason" in value && typeof value.reason === "string"
+            ? value.reason
+            : "capacity limit";
+    }
+    catch {
+        return null;
+    }
+}
+// These hook budget files are not plan/audit state and remain outside the log.
+export function atomicWriteJson(targetPath, data) {
+    const tmp = join(dirname(targetPath), `.tmp-${randomBytes(6).toString("hex")}`);
+    writeFileSync(tmp, JSON.stringify(data));
+    renameSync(tmp, targetPath);
+}
+export function isNonEmptyFile(path) {
+    try {
+        return existsSync(path) && statSync(path).size > 0;
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return false;
+        throw error;
+    }
+}
+export function readCount(counterPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(counterPath, "utf8"));
+        return typeof parsed === "object" &&
+            parsed !== null &&
+            "count" in parsed &&
+            typeof parsed.count === "number" &&
+            parsed.count >= 0
+            ? parsed.count
+            : 0;
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return 0;
+        throw error;
+    }
+}
+export 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;
+    }
+}

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,171 @@
-import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { mkdirSync } from "node:fs";
 import { 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 { readUlwLoopPlanSync } from "./plan-io.js";
+import { atomicWriteJson, isNonEmptyFile, readAdmissionBreaker, readCount, readCounts } from "./spawn-budget-io.js";
+import { spawnRoleDenial } from "./spawn-role-guard.js";
+import { isStateLockTimeout, withStateLockSync } from "./state-lock.js";
+import { canonicalReviewerAgentName, GATE_REVIEWER_AGENT_NAMES, LEGACY_REVIEWER_AGENT_ALIASES, 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-native-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),
+    ...Object.keys(LEGACY_REVIEWER_AGENT_ALIASES),
+];
+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 });
-    const plan = readPlan(join(stateDir, "goals.json"));
+    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(payload.cwd, payload.session_id);
     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.`;
+}
+// Hook budget counters are exempt from plan/audit commits.
 // 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 +175,73 @@ 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 canonical = canonicalReviewerAgentName(reviewer);
+    const activeRoles = reviewerRolesFor(resolveToolkitSurface());
+    for (const roles of Object.values(REVIEWER_ROLES_BY_SURFACE)) {
+        if (canonical === roles.codeReview)
+            return activeRoles.codeReview;
+        if (canonical === roles.manualQa)
+            return activeRoles.manualQa;
+        if (canonical === roles.gateReview)
+            return activeRoles.gateReview;
+    }
+    return canonical;
 }
 function deny(reason) {
     return `${JSON.stringify({
@@ -105,40 +260,16 @@ function fanOutLimit() {
     const parsed = Number.parseInt(raw, 10);
     return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_FANOUT_LIMIT;
 }
-function isNonEmptyFile(path) {
-    try {
-        return existsSync(path) && statSync(path).size > 0;
-    }
-    catch (error) {
-        if (error instanceof Error)
-            return false;
-        throw error;
-    }
-}
-function hasOtherEvidenceFile(evidenceDir, excludedName) {
-    try {
-        return readdirSync(evidenceDir).some((name) => name !== excludedName && isNonEmptyFile(join(evidenceDir, name)));
-    }
-    catch (error) {
-        if (error instanceof Error)
-            return false;
-        throw error;
-    }
-}
-function readCount(counterPath) {
-    try {
-        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 0;
-        throw error;
-    }
+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 readPlan(goalsPath) {
+function readPlan(repoRoot, sessionId) {
     try {
-        return JSON.parse(readFileSync(goalsPath, "utf8"));
+        return readUlwLoopPlanSync(repoRoot, { sessionId });
     }
     catch (error) {
         if (error instanceof 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,19 @@
+import { UlwLoopError } from "./types.js";
+export declare const ULW_LOOP_LOCK_TIMEOUT_CODE = "ULW_LOOP_LOCK_TIMEOUT";
+export interface StateLockClock {
+    readonly now: () => number;
+    readonly schedule: (fn: () => void, ms: number) => {
+        unref(): void;
+        cancel(): void;
+    };
+}
+export interface StateLockOptions {
+    readonly timeoutMs?: number;
+    readonly staleMs?: number;
+    readonly leaseMs?: number;
+    readonly heartbeatMs?: number;
+    readonly clock?: StateLockClock;
+}
+export declare function withStateLock<T>(lockPath: string, fn: (token: string) => 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;