oh-my-opencode 5.0.0-beta.60 → 5.0.0-beta.62

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

@@ -3059,6 +3059,15 @@ var ULW_LOOP_MANIFEST = {
 };
 
 // components/ulw-loop/src/sdk/factory.ts
+function validateCodexGoalJson(raw) {
+  if (raw === undefined)
+    return;
+  try {
+    JSON.parse(raw);
+  } catch (error) {
+    throw new UlwLoopError(`Invalid codexGoal: ${error instanceof Error ? error.message : "not valid JSON"}`, "ULW_LOOP_CODEX_GOAL_JSON_INVALID", { cause: error });
+  }
+}
 function validateContext(context) {
   if (!context.cwd.trim())
     throw new UlwLoopError("cwd is required.", "ULW_LOOP_CWD_REQUIRED");
@@ -3088,6 +3097,10 @@ function nextActionsFrom(result) {
     return [];
   return result.nextActions.filter((action) => typeof action === "string").slice(0, 8);
 }
+function checkpointWithValidatedSnapshot(context, scope, args) {
+  validateCodexGoalJson(args.codexGoalJson);
+  return checkpointUlwLoop(context.cwd, args, scope, { surface: context.surface });
+}
 function createAgentToolkit(context, deps = {}) {
   validateContext(context);
   const scope = { sessionId: context.sessionId };
@@ -3148,7 +3161,7 @@ function createAgentToolkit(context, deps = {}) {
       };
     }),
     completeGoals: (args = {}) => invoke("complete-goals", () => startNextUlwLoop(context.cwd, args, scope)),
-    checkpoint: (args) => invoke("checkpoint", () => args.printTemplate === true ? checkpointTemplate(context.cwd, scope, args.goalId, { surface: context.surface }) : checkpointUlwLoop(context.cwd, args, scope, { surface: context.surface })),
+    checkpoint: (args) => invoke("checkpoint", () => args.printTemplate === true ? checkpointTemplate(context.cwd, scope, args.goalId, { surface: context.surface }) : checkpointWithValidatedSnapshot(context, scope, args)),
     steer: (args) => invoke("steer", () => steerUlwLoop(context.cwd, args, scope)),
     addGoal: (args) => invoke("add-goal", () => addUlwLoopGoal(context.cwd, args, scope)),
     criteria: (args) => invoke("criteria", async () => {
@@ -3809,7 +3822,36 @@ function readAll(stdin) {
 import { randomBytes } from "node:crypto";
 import { existsSync as existsSync6, mkdirSync as mkdirSync2, readFileSync as readFileSync5, renameSync, statSync as statSync3, writeFileSync } from "node:fs";
 import { dirname as dirname3, join as join3 } from "node:path";
-var SPAWN_TOOL_TOKENS = new Set(["spawn_agent", "collaborationspawn_agent", "collaboration.spawn_agent"]);
+
+// components/ulw-loop/src/spawn-role-guard.ts
+var 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"
+]);
+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.`;
+}
+
+// components/ulw-loop/src/spawn-guard.ts
+var SPAWN_TOOL_TOKENS = new Set([
+  "spawn_agent",
+  "multi_agent_v1.spawn_agent",
+  "collaborationspawn_agent",
+  "collaboration.spawn_agent"
+]);
 var DEFAULT_FANOUT_LIMIT = 24;
 var DEFAULT_REVIEW_SPAWN_LIMIT = 3;
 var GATE_MESSAGE_PATTERN = /lazycodex-gate-reviewer|omo-senpi-gate-reviewer|final gate review/i;
@@ -3820,6 +3862,16 @@ var REVIEW_AGENT_TYPES = [
 ];
 var REVIEW_AGENT_TYPE_SET = new Set(REVIEW_AGENT_TYPES);
 function applySpawnGuards(payload, options = {}) {
+  if (payload.hook_event_name !== "PreToolUse" || !SPAWN_TOOL_TOKENS.has(payload.tool_name))
+    return "";
+  if (resolveToolkitSurface() === "lazycodex") {
+    const reason = spawnRoleDenial(payload.tool_input);
+    if (reason !== null)
+      return deny(reason);
+  }
+  return applySpawnBudgetGuards(payload, options);
+}
+function applySpawnBudgetGuards(payload, options = {}) {
   if (payload.hook_event_name !== "PreToolUse" || !SPAWN_TOOL_TOKENS.has(payload.tool_name))
     return "";
   const breaker = readAdmissionBreaker(payload.session_id);
@@ -3886,14 +3938,15 @@ async function runSpawnGuardCli(stdin, stdout) {
     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)}`));
   }
 }
 function peekFanOutBudget(stateDir) {

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

@@ -9,6 +9,18 @@ import { UlwLoopError } from "../runtime.js";
 import { statusNextActions } from "../status-next-actions.js";
 import { steerUlwLoop } from "../steering.js";
 import { ULW_LOOP_MANIFEST } from "./manifest.js";
+// The SDK takes inline values only, so a snapshot that is not JSON is a caller error - normalize it
+// to the same stable code the CLI reports instead of letting it surface as a generic failure.
+function validateCodexGoalJson(raw) {
+    if (raw === undefined)
+        return;
+    try {
+        JSON.parse(raw);
+    }
+    catch (error) {
+        throw new UlwLoopError(`Invalid codexGoal: ${error instanceof Error ? error.message : "not valid JSON"}`, "ULW_LOOP_CODEX_GOAL_JSON_INVALID", { cause: error });
+    }
+}
 function validateContext(context) {
     if (!context.cwd.trim())
         throw new UlwLoopError("cwd is required.", "ULW_LOOP_CWD_REQUIRED");
@@ -42,6 +54,10 @@ function nextActionsFrom(result) {
         return [];
     return result.nextActions.filter((action) => typeof action === "string").slice(0, 8);
 }
+function checkpointWithValidatedSnapshot(context, scope, args) {
+    validateCodexGoalJson(args.codexGoalJson);
+    return checkpointUlwLoop(context.cwd, args, scope, { surface: context.surface });
+}
 export function createAgentToolkit(context, deps = {}) {
     validateContext(context);
     const scope = { sessionId: context.sessionId };
@@ -108,7 +124,7 @@ export function createAgentToolkit(context, deps = {}) {
         completeGoals: (args = {}) => invoke("complete-goals", () => startNextUlwLoop(context.cwd, args, scope)),
         checkpoint: (args) => invoke("checkpoint", () => args.printTemplate === true
             ? checkpointTemplate(context.cwd, scope, args.goalId, { surface: context.surface })
-            : checkpointUlwLoop(context.cwd, args, scope, { surface: context.surface })),
+            : checkpointWithValidatedSnapshot(context, scope, args)),
         steer: (args) => invoke("steer", () => steerUlwLoop(context.cwd, args, scope)),
         addGoal: (args) => invoke("add-goal", () => addUlwLoopGoal(context.cwd, args, scope)),
         criteria: (args) => invoke("criteria", async () => {

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

@@ -4,5 +4,6 @@ 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

@@ -4,12 +4,18 @@ import { dirname, join } from "node:path";
 import { parsePreToolUsePayload } from "./codex-hook.js";
 import { isFinalRunCompletionCandidate } from "./goal-status.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 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;
@@ -20,6 +26,16 @@ const REVIEW_AGENT_TYPES = [
 ];
 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 "";
+    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);
@@ -93,15 +109,16 @@ export async function runSpawnGuardCli(stdin, stdout) {
         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

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/hooks/hooks.json

@@ -7,20 +7,20 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook user-prompt-submit --with-ultrawork",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.0.0-beta.60) Checking Ulw-Loop Steering"
+						"statusMessage": "(OmO 5.0.0-beta.62) Checking Ulw-Loop Steering"
 					}
 				]
 			}
 		],
 		"PostToolUse": [
 			{
-				"matcher": "^(spawn_agent|collaborationspawn_agent|collaboration\\.spawn_agent)$",
+				"matcher": "^(spawn_agent|multi_agent_v1\\.spawn_agent|collaborationspawn_agent|collaboration\\.spawn_agent)$",
 				"hooks": [
 					{
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook post-tool-use-spawn",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.60) Recording Spawn Admission"
+						"statusMessage": "(OmO 5.0.0-beta.62) Recording Spawn Admission"
 					}
 				]
 			}
@@ -33,18 +33,18 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook pre-tool-use",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.60) Enforcing Unlimited Ulw-Loop Budget"
+						"statusMessage": "(OmO 5.0.0-beta.62) Enforcing Unlimited Ulw-Loop Budget"
 					}
 				]
 			},
 			{
-				"matcher": "^(spawn_agent|collaborationspawn_agent|collaboration\\.spawn_agent)$",
+				"matcher": "^(spawn_agent|multi_agent_v1\\.spawn_agent|collaborationspawn_agent|collaboration\\.spawn_agent)$",
 				"hooks": [
 					{
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook pre-tool-use-spawn",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.60) Guarding Ulw-Loop Spawns"
+						"statusMessage": "(OmO 5.0.0-beta.62) Guarding Ulw-Loop Spawns"
 					}
 				]
 			}
@@ -56,7 +56,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook stop",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.0.0-beta.60) Checking Ulw-Loop Resume"
+						"statusMessage": "(OmO 5.0.0-beta.62) Checking Ulw-Loop Resume"
 					}
 				]
 			}

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

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-ulw-loop",
-	"version": "5.0.0-beta.60",
+	"version": "5.0.0-beta.62",
 	"description": "Codex plugin: durable repo-native multi-goal orchestration with embedded success criteria and observable evidence audit.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",

package/packages/omo-codex/plugin/components/ulw-loop/src/sdk/factory.ts

@@ -24,6 +24,21 @@ import type {
 	ToolkitUnknownRequest,
 } from "./types.js";
 
+// The SDK takes inline values only, so a snapshot that is not JSON is a caller error - normalize it
+// to the same stable code the CLI reports instead of letting it surface as a generic failure.
+function validateCodexGoalJson(raw: string | undefined): void {
+	if (raw === undefined) return;
+	try {
+		JSON.parse(raw);
+	} catch (error) {
+		throw new UlwLoopError(
+			`Invalid codexGoal: ${error instanceof Error ? error.message : "not valid JSON"}`,
+			"ULW_LOOP_CODEX_GOAL_JSON_INVALID",
+			{ cause: error },
+		);
+	}
+}
+
 function validateContext(context: ToolkitContext): void {
 	if (!context.cwd.trim()) throw new UlwLoopError("cwd is required.", "ULW_LOOP_CWD_REQUIRED");
 	if (!context.sessionId.trim())
@@ -63,6 +78,15 @@ function nextActionsFrom(result: object): readonly string[] {
 	return result.nextActions.filter((action): action is string => typeof action === "string").slice(0, 8);
 }
 
+function checkpointWithValidatedSnapshot(
+	context: ToolkitContext,
+	scope: UlwLoopScope,
+	args: Exclude<CheckpointArgs, { readonly printTemplate: true }>,
+): ReturnType<typeof checkpointUlwLoop> {
+	validateCodexGoalJson(args.codexGoalJson);
+	return checkpointUlwLoop(context.cwd, args, scope, { surface: context.surface });
+}
+
 export function createAgentToolkit(context: ToolkitContext, deps: AgentToolkitDependencies = {}): AgentToolkit {
 	validateContext(context);
 	const scope: UlwLoopScope = { sessionId: context.sessionId };
@@ -139,7 +163,7 @@ export function createAgentToolkit(context: ToolkitContext, deps: AgentToolkitDe
 			invoke("checkpoint", () =>
 				args.printTemplate === true
 					? checkpointTemplate(context.cwd, scope, args.goalId, { surface: context.surface })
-					: checkpointUlwLoop(context.cwd, args, scope, { surface: context.surface }),
+					: checkpointWithValidatedSnapshot(context, scope, args),
 			),
 		steer: (args) => invoke("steer", () => steerUlwLoop(context.cwd, args, scope)),
 		addGoal: (args) => invoke("add-goal", () => addUlwLoopGoal(context.cwd, args, scope)),

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

@@ -6,6 +6,7 @@ import type { PreToolUsePayload } from "./codex-hook.js";
 import { parsePreToolUsePayload } from "./codex-hook.js";
 import { isFinalRunCompletionCandidate } from "./goal-status.js";
 import { ulwLoopAttemptEvidenceDir, ulwLoopDir, ulwLoopStateLockPath } from "./paths.js";
+import { spawnRoleDenial } from "./spawn-role-guard.js";
 import { isStateLockTimeout, type StateLockOptions, withStateLockSync } from "./state-lock.js";
 import {
 	GATE_REVIEWER_AGENT_NAMES,
@@ -18,7 +19,12 @@ import type { UlwLoopPlan } from "./types.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 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;
@@ -34,6 +40,15 @@ export interface SpawnGuardOptions {
 }
 
 export function applySpawnGuards(payload: PreToolUsePayload, options: SpawnGuardOptions = {}): string {
+	if (payload.hook_event_name !== "PreToolUse" || !SPAWN_TOOL_TOKENS.has(payload.tool_name)) return "";
+	if (resolveToolkitSurface() === "lazycodex") {
+		const reason = spawnRoleDenial(payload.tool_input);
+		if (reason !== null) return deny(reason);
+	}
+	return applySpawnBudgetGuards(payload, options);
+}
+
+export function applySpawnBudgetGuards(payload: PreToolUsePayload, options: SpawnGuardOptions = {}): string {
 	if (payload.hook_event_name !== "PreToolUse" || !SPAWN_TOOL_TOKENS.has(payload.tool_name)) return "";
 	const breaker = readAdmissionBreaker(payload.session_id);
 	if (breaker !== null)
@@ -110,11 +125,14 @@ export async function runSpawnGuardCli(stdin: NodeJS.ReadableStream, stdout: Nod
 		const chunks: Buffer[] = [];
 		for await (const chunk of stdin) chunks.push(Buffer.from(chunk));
 		const payload = parsePreToolUsePayload(Buffer.concat(chunks).toString("utf8"));
-		if (payload === null) return;
+		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)}`));
 	}
 }
 

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

@@ -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: ReadonlySet<string> = 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: unknown): string | null {
+	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/test/sdk-driver-states.test.ts

@@ -0,0 +1,145 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { readUlwLoopPlan } from "../src/plan-io.js";
+import { createAgentToolkit } from "../src/sdk.js";
+
+const workDirs: string[] = [];
+
+afterEach(async () => {
+	for (const dir of workDirs.splice(0)) await rm(dir, { recursive: true, force: true });
+});
+
+interface Seeded {
+	readonly cwd: string;
+	readonly sessionId: string;
+	readonly goalId: string;
+	readonly objective: string;
+}
+
+// One fixture shape for every driver state: a real plan whose first goal is ready to close, so the
+// only thing under test is what the driver snapshot does to the checkpoint.
+async function seed(sessionId: string): Promise<Seeded> {
+	const cwd = await mkdtemp(join(tmpdir(), "ulw-driver-"));
+	workDirs.push(cwd);
+	const toolkit = createAgentToolkit({ cwd, sessionId, surface: "omo-senpi" });
+	const created = await toolkit.createGoals({ brief: "- alpha goal\n- beta goal" });
+	if (!created.ok) throw new Error("fixture could not create goals");
+	const started = await toolkit.completeGoals({});
+	if (!started.ok || started.operation !== "complete-goals" || "done" in started.result)
+		throw new Error("fixture could not start a goal");
+	const goalId = started.result.goal.id;
+	const criteria = await toolkit.criteria({ goalId });
+	if (!criteria.ok || criteria.operation !== "criteria") throw new Error("fixture has no criteria");
+	for (const criterion of criteria.result.criteria) {
+		const recorded = await toolkit.recordEvidence({
+			goalId,
+			criterionId: criterion.id,
+			status: "pass",
+			evidence: "driver-state fixture proof",
+		});
+		if (!recorded.ok) throw new Error("fixture could not record evidence");
+	}
+	const plan = await readUlwLoopPlan(cwd, { sessionId });
+	return { cwd, sessionId, goalId, objective: plan.codexObjective ?? "" };
+}
+
+async function closeWith(seeded: Seeded, snapshot?: Record<string, unknown>) {
+	const toolkit = createAgentToolkit({ cwd: seeded.cwd, sessionId: seeded.sessionId, surface: "omo-senpi" });
+	return toolkit.checkpoint({
+		goalId: seeded.goalId,
+		status: "complete",
+		evidence: "driver-state checkpoint",
+		...(snapshot === undefined ? {} : { codexGoalJson: JSON.stringify(snapshot) }),
+	});
+}
+
+describe("SDK driver-goal states", () => {
+	describe("#given no driver snapshot", () => {
+		it("#when the goal is checkpointed #then it completes and advises creating the driver goal", async () => {
+			const seeded = await seed("driver-absent");
+
+			const closed = await closeWith(seeded);
+
+			expect(closed.ok).toBe(true);
+			if (closed.ok) expect(closed.nextActions.join(" ")).toContain("create_goal");
+		});
+	});
+
+	describe("#given an active driver carrying the plan objective", () => {
+		it("#when the goal is checkpointed #then it completes with no objective difference reported", async () => {
+			const seeded = await seed("driver-active");
+
+			const closed = await closeWith(seeded, { goal: { objective: seeded.objective, status: "active" } });
+
+			expect(closed.ok).toBe(true);
+			if (closed.ok) {
+				expect([...(closed.warnings ?? []), ...closed.nextActions].join(" ")).not.toContain(
+					"driver_objective_differs",
+				);
+			}
+		});
+	});
+
+	describe("#given a driver completed before the plan finished", () => {
+		it("#when the goal is checkpointed #then it completes and advises re-creating the driver", async () => {
+			const seeded = await seed("driver-early");
+
+			const closed = await closeWith(seeded, { goal: { objective: seeded.objective, status: "complete" } });
+
+			expect(closed.ok).toBe(true);
+			if (closed.ok) expect(closed.nextActions.join(" ")).toContain("create_goal");
+		});
+	});
+
+	describe("#given a driver the harness has limited", () => {
+		for (const status of ["paused", "usage_limited", "budget_limited"] as const) {
+			it(`#when the driver is ${status} #then the checkpoint still completes and advises resuming it`, async () => {
+				const seeded = await seed(`driver-${status}`);
+
+				const closed = await closeWith(seeded, { goal: { objective: seeded.objective, status } });
+
+				expect(closed.ok).toBe(true);
+				if (closed.ok) expect(closed.nextActions.join(" ")).toContain("/goal resume");
+			});
+		}
+	});
+
+	describe("#given a driver whose objective differs from the plan", () => {
+		it("#when the goal is checkpointed #then the difference is reported, never a rejection", async () => {
+			const seeded = await seed("driver-differs");
+
+			const closed = await closeWith(seeded, { goal: { objective: "a different objective", status: "active" } });
+
+			expect(closed.ok).toBe(true);
+			if (closed.ok) {
+				expect([...(closed.warnings ?? []), ...closed.nextActions].join(" ")).toContain("driver_objective_differs");
+			}
+		});
+	});
+
+	describe("#given snapshot input that is neither JSON nor a readable path", () => {
+		it("#when the goal is checkpointed #then the typed error is returned and the goal stays open", async () => {
+			const seeded = await seed("driver-malformed");
+
+			const closed = await closeWith(seeded);
+			expect(closed.ok).toBe(true);
+
+			const second = await seed("driver-malformed-2");
+			const toolkit = createAgentToolkit({ cwd: second.cwd, sessionId: second.sessionId, surface: "omo-senpi" });
+			const rejected = await toolkit.checkpoint({
+				goalId: second.goalId,
+				status: "complete",
+				evidence: "driver-state checkpoint",
+				codexGoalJson: "not json and not a path",
+			});
+
+			expect(rejected.ok).toBe(false);
+			if (!rejected.ok) expect(rejected.error.code).toBe("ULW_LOOP_CODEX_GOAL_JSON_INVALID");
+			const plan = await readUlwLoopPlan(second.cwd, { sessionId: second.sessionId });
+			expect(plan.goals.find((goal) => goal.id === second.goalId)?.status).not.toBe("complete");
+		});
+	});
+});

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

@@ -6,7 +6,13 @@ import { Readable, Writable } from "node:stream";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import type { PreToolUsePayload } from "../src/codex-hook.ts";
-import { applySpawnGuards, DEFAULT_FANOUT_LIMIT, runSpawnAdmissionRecorderCli } from "../src/spawn-guard.ts";
+// Budget/artifact behavior is independent of role admission; the native entry
+// point and its composition are covered in spawn-role-matrix.test.ts.
+import {
+	applySpawnBudgetGuards as applySpawnGuards,
+	DEFAULT_FANOUT_LIMIT,
+	runSpawnAdmissionRecorderCli,
+} from "../src/spawn-guard.ts";
 
 let workDir: string;
 let originalLimit: string | undefined;