lazycodex-ai 5.0.0-beta.9 → 5.0.0

package/packages/omo-codex/plugin/components/{start-work-continuation → ulw-execute-continuation}/src/types.ts

@@ -1,4 +1,4 @@
-export const STOP_HOOK_EVENTS = ["Stop", "SubagentStop"] as const;
+export const STOP_HOOK_EVENTS = ["Stop"] as const;
 export type StopHookEventName = (typeof STOP_HOOK_EVENTS)[number];
 
 export type StopInput = {

package/packages/omo-codex/plugin/components/{start-work-continuation → ulw-execute-continuation}/test/boulder-reader.test.ts

@@ -11,7 +11,7 @@ afterEach(() => {
 	for (const root of cleanupRoots.splice(0)) rmSync(root, { recursive: true, force: true });
 });
 
-describe("start-work plan checklist consumption", () => {
+describe("ulw-execute plan checklist consumption", () => {
 	it("#given scaffold headings and canonical numbered rows #when parsed #then structured totals and next label match", () => {
 		// given
 		const planPath = createPlan(SCAFFOLD_PLAN_MARKDOWN);
@@ -242,7 +242,7 @@ describe("start-work plan checklist consumption", () => {
 	});
 });
 
-describe("start-work boulder state reader", () => {
+describe("ulw-execute boulder state reader", () => {
 	it("#given active codex work with remaining checklist #when state is read #then continuation fields match baseline", () => {
 		// given
 		const workspace = createWorkspace({
@@ -258,7 +258,7 @@ describe("start-work boulder state reader", () => {
 			planName: "launch-plan",
 			planPath: join(workspace, ".omo", "plans", "plan.md"),
 			boulderPath: join(workspace, ".omo", "boulder.json"),
-			ledgerPath: join(workspace, ".omo", "start-work", "ledger.jsonl"),
+			ledgerPath: join(workspace, ".omo", "ulw-execute", "ledger.jsonl"),
 			worktreePath: null,
 			checklist: {
 				completed: 2,

package/packages/omo-codex/plugin/components/{start-work-continuation → ulw-execute-continuation}/test/cli.test.ts

@@ -12,7 +12,7 @@ afterEach(() => {
 	for (const root of cleanupRoots.splice(0)) rmSync(root, { recursive: true, force: true });
 });
 
-describe("start-work continuation CLI", () => {
+describe("ulw-execute continuation CLI", () => {
 	it("#given valid Stop stdin #when CLI runs #then stdout contains block JSON", () => {
 		// given
 		const cwd = createWorkspace(["codex:s1"]);
@@ -28,7 +28,7 @@ describe("start-work continuation CLI", () => {
 		expect(output.decision).toBe("block");
 	});
 
-	it("#given valid SubagentStop stdin #when CLI runs #then stdout contains block JSON", () => {
+	it("#given valid SubagentStop stdin #when CLI runs #then stdout is empty", () => {
 		// given
 		const cwd = createWorkspace(["codex:s1"]);
 		const payload = JSON.stringify(makePayload(cwd, false, "SubagentStop"));
@@ -39,7 +39,7 @@ describe("start-work continuation CLI", () => {
 		// then
 		if (result.error !== undefined) throw result.error;
 		expect(result.status).toBe(0);
-		expect(result.stdout).toContain('"decision":"block"');
+		expect(result.stdout).toBe("");
 	});
 
 	it("#given active stop hook stdin #when CLI runs #then stdout is empty and exit is zero", () => {
@@ -119,11 +119,7 @@ function createWorkspace(sessionIds: readonly string[]): string {
 	return root;
 }
 
-function makePayload(
-	cwd: string,
-	stopHookActive: boolean,
-	eventName: "Stop" | "SubagentStop",
-): Record<string, string | boolean> {
+function makePayload(cwd: string, stopHookActive: boolean, eventName: string): Record<string, string | boolean> {
 	return {
 		session_id: "s1",
 		turn_id: "t1",

package/packages/omo-codex/plugin/components/{start-work-continuation → ulw-execute-continuation}/test/codex-hook.test.ts

@@ -14,7 +14,7 @@ afterEach(() => {
 	for (const root of cleanupRoots.splice(0)) rmSync(root, { recursive: true, force: true });
 });
 
-describe("start-work Stop hook", () => {
+describe("ulw-execute Stop hook", () => {
 	it("#given stop hook is already active #when hook runs #then returns empty output", () => {
 		// given
 		const fs = createMemoryFs();
@@ -61,6 +61,22 @@ describe("start-work Stop hook", () => {
 		expect(parseBlockOutput(output).decision).toBe("block");
 	});
 
+	it("#given active Boulder work and a SubagentStop event #when hook runs #then returns empty output", () => {
+		// given
+		const workspace = createWorkspace({
+			boulderJson: createBoulderJson({ sessionIds: ["codex:sess_abc"], status: "active" }),
+			planMarkdown: SCAFFOLD_PLAN_MARKDOWN,
+		});
+		const fs = createMemoryFs();
+		const input = { ...createStopInput(workspace), hook_event_name: "SubagentStop" as const };
+
+		// when
+		const output = runStopHook(input, fs);
+
+		// then
+		expect(output).toBe("");
+	});
+
 	it("#given active codex work and an external-blocker marker #when hook runs #then returns empty output", () => {
 		// given
 		const workspace = createWorkspace({
@@ -71,7 +87,7 @@ describe("start-work Stop hook", () => {
 		const input = {
 			...createStopInput(workspace),
 			last_assistant_message: [
-				"<start-work-blocked-external>",
+				"<ulw-execute-blocked-external>",
 				"Blocker: the staging deploy credential is missing.",
 				"Resume when a valid credential is provisioned.",
 			].join("\n"),
@@ -95,7 +111,7 @@ describe("start-work Stop hook", () => {
 			...createStopInput(workspace),
 			last_assistant_message: [
 				"ULTRAWORK MODE ENABLED!",
-				"<start-work-blocked-external>",
+				"<ulw-execute-blocked-external>",
 				"Blocker: the staging deploy credential is missing.",
 			].join("\n"),
 		};
@@ -118,7 +134,7 @@ describe("start-work Stop hook", () => {
 		const fs = createMemoryFs();
 		const input = {
 			...createStopInput(workspace),
-			last_assistant_message: "<start-work-blocked-external>",
+			last_assistant_message: "<ulw-execute-blocked-external>",
 		};
 
 		// when
@@ -137,7 +153,7 @@ describe("start-work Stop hook", () => {
 		const fs = createMemoryFs();
 		const input = {
 			...createStopInput(workspace),
-			last_assistant_message: ["ULTRAWORK MODE ENABLED!", "<start-work-blocked-external>", "   "].join("\n"),
+			last_assistant_message: ["ULTRAWORK MODE ENABLED!", "<ulw-execute-blocked-external>", "   "].join("\n"),
 		};
 
 		// when
@@ -156,7 +172,7 @@ describe("start-work Stop hook", () => {
 		const fs = createMemoryFs();
 		const input = {
 			...createStopInput(workspace),
-			last_assistant_message: ["Next turn I may need to emit", "<start-work-blocked-external>"].join("\n"),
+			last_assistant_message: ["Next turn I may need to emit", "<ulw-execute-blocked-external>"].join("\n"),
 		};
 
 		// when

package/packages/omo-codex/plugin/components/ulw-loop/AGENTS.md

@@ -42,7 +42,26 @@ Conventions for human contributors and AI agents working on this repository.
 - CLI commands use the `omo-agent-toolkit ulw-loop` form.
 - Do not use any alternate legacy CLI alias anywhere.
 
+## Layout
+
+- `src/cli.ts`: bin entry (`omo-ulw-loop`, `ulw`, `ulw-loop` all map to `dist/cli.js`); documented invocation form `omo-agent-toolkit ulw-loop <subcommand>`.
+- `src/cli-commands.ts`: subcommand dispatch (`ULW_LOOP_SUBCOMMANDS`, `ulwLoopCommand`, flag/value readers).
+- `src/plan-io.ts`: plan persistence, append-only `ledger.jsonl`, `withUlwLoopMutationLock`.
+- `src/quality-gate.ts` (188 LOC), `src/checkpoint.ts` (247), `src/steering.ts` (203): state-transition hotspots (evidence containment, checkpoint reconciliation, steering mutations).
+- `src/quality-gate-artifacts.ts`: artifact-ref / surface-kind primitives shared by the gate validator; `src/quality-gate-aggregate.ts`: non-throwing defect pre-pass that aggregates every gate defect into one error.
+- `src/codex-hook.ts`: UserPromptSubmit steering injection + `create_goal` budget guard.
+- `src/spawn-guard.ts`, `src/stop-resume-hook.ts`: spawn guards, Stop auto-resume.
+- `src/surface.ts`: toolkit surface + reviewer-identity resolution (`lazycodex` default; staged `surface.json` marker or `OMO_AGENT_TOOLKIT_SURFACE` selects `omo-senpi`).
+- `src/ultrawork-skill-pointer.ts`: byte-identical mirror of ultrawork's pointer (pinned by `plugin/test/ultrawork-skill-pointer.test.mjs`).
+- `directive.md`: runtime-read directive (never inlined into TypeScript). GENERATED from the canonical `packages/prompts-core/prompts/ultrawork/codex.md` by `components/ultrawork/scripts/sync-directive.mjs` and checked in, because this package is published standalone with no prompts-core dependency. Do not hand-edit; byte identity is pinned by `test/ultrawork-directive.test.ts`.
+
 ## Build and Hooks
 
 - Build output goes to `dist/`.
 - `hooks/hooks.json` wires `hook user-prompt-submit --with-ultrawork` (UserPromptSubmit), `hook pre-tool-use` (create_goal budget), `hook pre-tool-use-spawn` (spawn guards), and `hook stop` (auto-resume).
+
+## Commands
+
+- `npm test` (vitest --run) / `npm run test:watch`; focused: `bunx vitest run test/<file>.test.ts`
+- `npm run typecheck` / `npm run lint` / `npm run build` (`tsc -p tsconfig.build.json`) / `npm run check`
+- These stay npm even though the repo root is bun-driven: `.github/workflows/ci.yml` runs this component as `npm --prefix "$component" run check` (the loop selects every component whose `package.json` declares `scripts.check`, which includes this one), `scripts.check` itself shells `npm run build`, and the surrounding plugin tree is installed with `npm --prefix packages/omo-codex/plugin ci` in both `ci.yml` and `publish.yml`. Run the bun equivalents (`bun run test`, `bunx tsc -p tsconfig.build.json`, `bunx biome check .`) locally if you prefer, but do not rewrite this section to bun-only while CI invokes npm here.

package/packages/omo-codex/plugin/components/ulw-loop/CHANGELOG.md

@@ -2,9 +2,25 @@
 
 ## [0.1.0] - unreleased
 
+- **Fix:** a `goals.json` written outside the commit log (the removed `omo_agent_toolkit` tool path rewrote it wholesale, never stamping `revision`) no longer loses to an older `revisions/` snapshot when it holds goals that snapshot lacks; the cache wins, is stamped with the snapshot's revision, and the next publish folds it into revision N+1 instead of colliding on an existing record. Raw `ledger.jsonl` lines appended after a published revision are attributed to that revision rather than to the pre-store past a later `ledgerResetRevision` discards. Locked reads and every commit now refuse to rewrite `goals.json` while the reconciled ledger names a `goal_added` goal the projection lacks (`ULW_LOOP_PROJECTION_TRUNCATED`, `details.missingGoalIds`) instead of silently truncating the plan (code-yeongyu/oh-my-openagent#8328).
+- Status nextActions and missing-plan recovery now follow the calling surface: omo-senpi teaches the eval SDK methods and current attempt directory without asking for a driver snapshot; LazyCodex retains its existing CLI guidance byte-for-byte.
+
+- Async `.state.lock` holders now keep their file descriptor open and refresh a 30-second lease through it. An expired lease can be reclaimed even while its process remains alive; sync hooks and older lease-less records retain dead-pid-only ownership. Windows filesystems that refuse unlinking an open lock fail closed. Interrupted kernels can recover after lease expiry without deleting a live owner's lock.
+- Plan and audit mutations publish one immutable `revisions/<revision>.json` record using create-only hard links. Published revision paths are never deleted or reused.
+- `ULW_LOOP_PUBLISH_CONFLICT` retries the complete mutation once while its lock token remains owned.
+- A displaced writer receives `ULW_LOOP_LOCK_LOST` instead of overwriting its successor's state.
+- Filesystems without atomic hard links fail closed with `ULW_LOOP_PUBLISH_UNSUPPORTED_FS` (no copy fallback).
+- Additive plan fields `revision`, `brief`, and `ledgerResetRevision`, plus ledger `revision` and `id`, remain optional on legacy reads. The first mutation hydrates a legacy brief, and objective migration is folded into that mutation rather than committed by a read. Force recreation advances the revision and filters older audit entries instead of truncating the ledger.
+- `goals.json`, `ledger.jsonl`, and `brief.md` are complete-file, temp-and-rename derived views. Shared readers reconcile committed records after a crash, including audit-only steering and idempotency, and locked reads repair lagging views. Logical audit order is revision/sequence, not completion order. Older CLIs see complete but possibly lagging or transiently regressed caches; after force recreation they may see pre-reset entries until views are replaced. Hook budget counters remain separate from plan/audit state. Reconciliation now materializes the logical ledger in memory, replacing the earlier streaming-only dedup implementation.
+- Reconciling a plan reads only the newest commit record (newest revision first, stopping at the first valid one) instead of parsing every record in `revisions/`, so a status probe stays independent of how many revisions a session has committed. The full scan remains where the audit trail needs every record.
+
+- SDK contexts now reject session IDs that normalize to null with `ULW_LOOP_SESSION_ID_INVALID`, before any session state directory is created.
+
+- LazyCodex native spawns now require an explicit bundled role before plan, budget, or artifact checks. Unknown and unnamed roles fail loudly; Senpi admission is unchanged. Guidance follows the actual spawn schema, including V2 `agent_type` when exposed. Installer/bootstrap provide an opt-out-able, ownership-checked medium-worker `default` for unnamed non-forks. An unnamed full-history fork still skips role application inside Codex: configuration cannot repair that upstream gap, and enforcement depends on Codex invoking the trusted hook. Legacy schemas without `agent_type` retain message-carried instructions but are rejected by the schema-blind guard rather than silently falling through.
+
 - Bundled `directive.md` picks up the ultrawork test-proportionality change: the execution-loop PIN step asks for characterization pins only when refactoring behavior whose regressions the change could hide. Stays byte-identical to `prompts-core/ultrawork/codex.md` and the ultrawork component's `directive.md`.
 
-- **Hooks:** new `Stop` hook auto-resumes a turn that died with unfinished goals (defers to start-work-continuation while its plan has remaining tasks, bails under context pressure, and caps at two resumes without ledger movement via a separate `.stuck` marker). New `PreToolUse` spawn guard adds a per-session fan-out cap (`OMO_SPAWN_FANOUT_LIMIT`, default 60) and denies final gate-reviewer spawns while the reviewer artifacts the gate audits are missing.
+- **Hooks:** new `Stop` hook auto-resumes a turn that died with unfinished goals (defers to ulw-execute-continuation while its plan has remaining tasks, bails under context pressure, and caps at two resumes without ledger movement via a separate `.stuck` marker). New `PreToolUse` spawn guard adds a per-session fan-out cap (`OMO_SPAWN_FANOUT_LIMIT`, default 60) and denies final gate-reviewer spawns while the reviewer artifacts the gate audits are missing.
 
 - **Memory:** steering ledger entries no longer embed the full plan four times (`before`/`after` at both the audit and entry level). Accepted steers now record a compact `UlwLoopSteeringPlanSnapshot` (plan counters + only the goals the mutation touched), shrinking a measured real-world entry from 189KB to 7.8KB (~24x) and ending quadratic `ledger.jsonl` growth over long runs.
 - **Memory:** steering dedup (`--idempotency-key` / `promptSignature`) streams the ledger line-by-line with a substring pre-filter instead of `JSON.parse`-ing every entry into memory; dedup returns strip legacy full-plan `before`/`after` payloads from re-surfaced audits. `readSteeringLedgerEntries` streams too.

package/packages/omo-codex/plugin/components/ulw-loop/README.md

@@ -21,7 +21,17 @@ Every subcommand below is implemented. Pass `--json` where supported for machine
 | `omo-agent-toolkit ulw-loop record-evidence` | Record observable evidence for one criterion. |
 | `omo-agent-toolkit ulw-loop record-review-blockers` | Mark a goal as review-blocked and add follow-up work from final-review findings. |
 
-The final quality gate parsed by `checkpoint` validates `codeReview`, `manualQa`, `gateReview`, `iteration`, and `criteriaCoverage`. `criteriaCoverage` records the original intent, desired outcome, user-facing outcome review, pass counts, and covered adversarial classes.
+The final quality gate parsed by `checkpoint` requires `manualQa`, `gateReview`, `iteration`, and `criteriaCoverage`; lazycodex accepts optional `codeReview`. Lazycodex defaults to `main-session` self-review, with `category:*` and reviewer acceptors available when needed. `criteriaCoverage` records the original intent, desired outcome, user-facing outcome review, pass counts, and covered adversarial classes. The companion `codex-goal-json` must contain `goal.objective` equal to the plan's `codexObjective` verbatim.
+
+A complete passing checkpoint uses both payloads:
+
+```json
+{"goal":{"objective":"Ship the requested behavior","status":"complete"}}
+```
+
+```json
+{"gateReview":{"by":"main-session","recommendation":"APPROVE","reportPath":".omo/evidence/gate-review.md","evidence":"Gate review passed.","blockers":[],"notes":[]},"manualQa":{"by":"lazycodex-qa-executor","status":"passed","evidence":"Manual QA passed.","surfaceEvidence":[{"id":"cli","criterionRef":"C1","surface":"cli","invocation":"omo-agent-toolkit ulw-loop checkpoint --json","verdict":"passed","artifactRefs":["cli-artifact"]}],"adversarialCases":[{"id":"malformed","criterionRef":"C2","scenario":"Malformed input","expectedBehavior":"Rejected","verdict":"not_applicable","reason":"Not triggered","artifactRefs":["cli-artifact"]}],"artifactRefs":[{"id":"cli-artifact","kind":"cli-transcript","description":"Passing CLI transcript","path":".omo/evidence/cli.txt"}]},"codeReview":{"by":"lazycodex-code-reviewer","recommendation":"APPROVE","codeQualityStatus":"CLEAR","reportPath":".omo/evidence/code-review.md","evidence":"Code review passed.","blockers":[]},"iteration":{"fullRerun":true,"status":"passed","rerunCommands":["bun test"],"evidence":"Full rerun passed."},"criteriaCoverage":{"totalCriteria":2,"passCount":2,"originalIntent":"Ship the requested behavior","desiredOutcome":"The behavior works for users.","userOutcomeReview":"The result matches the requested outcome.","adversarialClassesCovered":["malformed_input"]}}
+```
 
 Validation batches are optional review boundaries declared at plan creation with `--validation-batch-json '[{"batchId":"VB001","memberIds":[...],"finalGoalId":"..."}]'`. The batch-final goal cannot complete until every other member is complete or superseded-resolved, every member criterion is pass, and a quality gate's coverage counts match the recomputed member criteria. Steering split/supersede mutations keep batch membership consistent and record `batch_updated`.
 
@@ -35,6 +45,7 @@ This directory is a component of the aggregate `@sisyphuslabs/omo-codex-plugin`
   - `PreToolUse` matching the spawn tool tokens -> `node "${PLUGIN_ROOT}/dist/cli.js" hook pre-tool-use-spawn` (fan-out cap + gate-artifact preflight)
   - `Stop` -> `node "${PLUGIN_ROOT}/dist/cli.js" hook stop` (auto-resume with a two-strike no-progress cap)
 - `skills/ulw-loop/` for the bundled `ulw-loop` skill.
+- `directive.md`, the ultrawork directive read at runtime when `--with-ultrawork` falls back to the full text. This package is published standalone and takes no dependency on `@oh-my-opencode/prompts-core`, so it intentionally bundles its own byte-identical copy of the canonical `packages/prompts-core/prompts/ultrawork/codex.md`. The copy is generated by `components/ultrawork/scripts/sync-directive.mjs` and pinned byte-for-byte by `test/ultrawork-directive.test.ts`; do not hand-edit it.
 - `bin.omo-ulw-loop` -> `dist/cli.js` for standalone CLI invocation.
 
 This component ships a CLI, a skill, and hooks. It does not expose an MCP server.

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

@@ -1,9 +1,9 @@
 {
-	"$schema": "https://biomejs.dev/schemas/2.4.16/schema.json",
+	"$schema": "https://biomejs.dev/schemas/2.5.9/schema.json",
 	"linter": {
 		"enabled": true,
 		"rules": {
-			"recommended": true,
+			"preset": "recommended",
 			"style": {
 				"noDefaultExport": "error",
 				"noEnum": "error",

package/packages/omo-codex/plugin/components/ulw-loop/directive.md

@@ -6,13 +6,13 @@
 [CODE RED] Maximum precision. Outcome-first. Evidence-driven.
 
 # Role
-Expert coding agent. Ship verified work. No process narration.
+Expert coding agent. Ship verified work; report at handoffs, not between them.
 
 # Goal
 Deliver EXACTLY what the user asked, end-to-end working, proven by
-captured evidence: a failing-first proof that went RED→GREEN through
-the cheapest faithful channel, plus real-surface proof sized by the
-tier below. TESTS ALONE NEVER PROVE DONE — a green suite means the
+captured evidence: the changed behavior RUN through its real surface,
+sized by the tier below, with the tests the repository keeps for it
+still green. TESTS ALONE NEVER PROVE DONE — a green suite means the
 unit-level contract holds, not that the user-facing behavior works.
 
 # Tier triage (classify ONCE at bootstrap; record tier + one-line
@@ -46,15 +46,15 @@ first-class for CLI- or data-shaped work; self-review recorded in the
 notepad instead of the reviewer loop.
 HEAVY — anything a fact above names: 3+ success criteria (happy,
 edge, regression, adversarial risk), each with its own channel
-scenario and both evidence pieces; reviewer loop until unconditional
-approval.
+scenario and both evidence pieces; when the verification gate is
+triggered, run the reviewer loop until unconditional approval.
 
 # Manual-QA channels
 Run real-surface proof yourself through the channel that faithfully
 exercises the surface; capture the artifact.
 
-  1. HTTP call — hit the live endpoint with `curl -i` (or a
-     Playwright APIRequestContext); capture status line + headers +
+  1. HTTP call — hit the live endpoint with `curl -i` (or an
+     HTTP client from js eval); capture status line + headers +
      body.
   2. Terminal / TUI - drive a real pty and prove it through the
      xterm.js web terminal (see the TUI visual QA note below). tmux
@@ -62,11 +62,21 @@ exercises the surface; capture the artifact.
      for color / layout / CJK evidence, which degrades truecolor.
   3. Browser use — in Codex, use `browser:control-in-app-browser`
      first when available and no authenticated/persistent user browser
-     profile is required. Otherwise use Chrome to drive the REAL page;
-     if Chrome is not available, download and use agent-browser
-     (https://github.com/vercel-labs/agent-browser). Capture action
-     log + screenshot path. Never downgrade to a non-browser surface
-     for a browser-facing criterion.
+     profile is required. Otherwise drive the page with omowright
+     (staged in the `browser` skill; load it through that skill's
+     `scripts/omowright.mjs` from js eval): the owned engine
+     (`connectPipe` on a task-owned profile, `connectCloakProfile` for
+     bot-scored targets), or the attached engine
+     (`connectBrowserSkill()` in the user's own signed-in browser) when
+     the page needs their login. Capture action log + screenshot path.
+     Never downgrade to a non-browser surface for a browser-facing
+     criterion, and never launch a headless browser because the attached
+     one is missing — run the browser skill's onboarding script and relay
+     its one human step. NEVER clear cookies, cache, or site data
+     (`Network.clearBrowserCookies`, `Storage.clearCookies`,
+     `chrome.browsingData.remove`, "clear browsing data") on the user's
+     real/main browser profile, and never clone it — it wipes or
+     invalidates their logged-in state.
   4. Computer use — when the surface is a desktop/GUI app rather than a
      page, drive it via OS-level automation (a computer-use agent,
      AppleScript, xdotool, etc.) against the running app; capture
@@ -141,9 +151,6 @@ The criteria MUST list, upfront:
   its exact scenario: the literal command / page action / payload and
   the binary PASS/FAIL observable, plus the evidence artifact it will
   capture.
-- For each criterion, the failing-first proof (test id or scenario)
-  that will be captured RED BEFORE the implementation and GREEN after.
-  Evidence added after the green code does NOT satisfy this.
 - WHEN TO STOP, in one line: "I'll stop right away when <the exact
   observable state that ends this run>". The Stop rules bind to this
   line — the moment it holds, you stop.
@@ -179,7 +186,7 @@ Started: <ISO timestamp>
 <patterns / pitfalls / principles to remember next turn>
 ```
 
-Append each finding, decision, command, RED/GREEN capture, and QA
+Append each finding, decision, command, test read, and QA
 artifact path the moment it happens. Update `## Now` and
 `## Todo` on every transition. Append-only — never rewrite. This notepad
 is your durable memory and it OUTLIVES the context window. After any
@@ -205,11 +212,10 @@ instead of waiting for the next pass. Step text encodes WHERE / WHY
 (which criterion it advances) / HOW / VERIFY:
 `path: <action> for <criterion> — verify by <check>`.
 
-GOOD pair (test-first, ordered):
-  `foo.test.ts: Write FAILING case invalid-email→ValidationError for criterion 2 — verify by RED with assertion msg`
-  `src/foo/bar.ts: Implement validateEmail() RFC-5322-lite for criterion 2 — verify by foo.test.ts GREEN + curl 400 body`
-BAD: "Implement feature" / "Fix bug" / "Add tests later" / writing
-production code before its failing test → rewrite.
+GOOD pair (ordered):
+  `test/foo.test.ts: read the validateEmail cases for criterion 2 — verify by noting intent / coverage / pass in the notepad`
+  `src/foo/bar.ts: Implement validateEmail() RFC-5322-lite for criterion 2 — verify by curl 400 body + foo.test.ts green`
+BAD: "Implement feature" / "Fix bug" / "Add tests later" → rewrite.
 
 # Finding things (lead with these, code-mode the first wave)
 Never guess from memory — locate with the right tool, and re-read before
@@ -223,8 +229,8 @@ and utility functions to batch commands and reduce output. Keep direct calls
 when one result chooses the next action, outputs are already small, semantic
 judgment is required between calls, approval or side effects are involved,
 or native artifacts / citations must be preserved.
-- Architecture / flow / blast radius → `codegraph_explore` first when
-  `codegraph_*` exists; if unavailable, continue with repo tools and LSP.
+- Architecture / flow / blast radius → explore agents plus LSP references
+  and impact; do not guess from conventions.
 - **SYMBOLS REQUIRE LSP** — definitions, references, rename impact,
   workspace symbols, and diagnostics use the available `lsp_*` tools, not
   text search. Run diagnostics after edits and treat errors as blocking.
@@ -238,51 +244,35 @@ search, absolute-path results). For research that leaves the repo —
 library/API/docs/web — delegate to the `librarian` subagent. Spawn them
 `fork_context: false` and keep doing root work while they run.
 
-# Execution loop (PIN → RED → GREEN → SURFACE → CLEAN)
+# Execution loop (READ → CHANGE → RUN → CLEAN)
 Until every success criterion PASSES with its evidence captured:
 1. Pick next criterion → mark in_progress → update notepad `## Now`.
-2. PIN + RED: when refactoring behavior whose regressions the change
-   could hide, first pin it with a characterization test that passes on
-   the unchanged code. Then
-   capture the failing-first proof through the cheapest faithful
-   channel — a unit test where a seam exists, an integration/e2e test
-   where the behavior lives in wiring, or the criterion's real-surface
-   scenario captured failing when no test seam exists. It must fail
-   for the RIGHT reason (not a syntax error, not a missing import).
-   Paste RED output into the notepad. No production code yet.
-   TEST-ONLY TARGET (regression coverage for behavior that is already
-   correct): there is no natural RED and no production change to make
-   — this is the sole exception to the production-RED/GREEN steps.
-   Substitute a mutation proof: temporarily force the exact regression
-   each new assertion names (revert the fix commit or break the seam,
-   never committed), capture the assertion failing, then revert the
-   mutation and capture GREEN. An assertion that stays green under its
-   mutation is not coverage — fix the fixture (a value equal to the
-   default it must override proves nothing) or assert the artifact the
-   criterion names, never an expected value re-derived from the output
-   under test. Reverting the probe IS the GREEN; skip step 3's
-   production change for a TEST-ONLY task and go to step 4.
-   PROSE TARGET (prompt, SKILL.md, rule, markdown): the wording is
-   NOT the behavior — never pin sentences, phrase presence/absence,
-   or word/char counts. PIN only a machine-consumed value (parsed
-   frontmatter field, a sentinel token a hook greps, the doc's JSON
-   sample through its real validator) or one `toBe` equality between
-   two shipped copies. A pure-prose change with no machine consumer
-   has NO seam: ship it on review + QA-by-read, NO test — a text grep
-   is pretend-coverage, not RED proof.
-3. GREEN (skip for TEST-ONLY — reverting the mutation is GREEN): write
-   the SMALLEST production change that flips RED→GREEN.
-   Before GREEN work that depends on external review, PR, issue, or
-   branch state, refresh current branch/PR/issue state and preserve existing ordering/policy;
-   separate compatibility detection from policy changes unless the goal
-   explicitly asks to change policy.
-   Re-run the proof. Capture GREEN output. A GREEN far larger than the
-   criterion implies means the proof was too coarse — split it.
-4. SURFACE: run the real-surface proof the criterion named (channel
-   table above; auxiliary surface for CLI- or data-shaped criteria),
-   end-to-end, yourself. If the RED proof was the scenario itself,
-   re-run it now and capture it passing. Paste the artifact path into
-   the notepad.
+2. READ what already proves the area BEFORE touching it. Existing
+   tests are the behavior of record: note in the notepad whether they
+   encode the intended behavior, cover the path you change, and pass.
+   One WRONG before your change is a FINDING to report — NEVER edit a
+   test green. A bug: reproduce it first and capture the failure. A
+   refactor: the existing tests are green on the unchanged code first.
+3. CHANGE: the SMALLEST production change that meets the criterion;
+   update the tests your change makes stale. Add a test ONLY when
+   BOTH hold: the repository keeps tests for this behavior AND a
+   regression would otherwise pass unnoticed by the run and the
+   existing tests — sized like its neighbors, one case per stated
+   behavior, failing when that behavior breaks. A test that restates
+   the change (a constant, a string, a rename, a call) is NOT evidence;
+   the run is. Coverage-only work (no production change): break the
+   behavior each new assertion names, capture it failing, restore — an
+   assertion that stays green under its mutation is not coverage.
+   PROSE TARGET (prompt, SKILL.md, rule, markdown): the wording is NOT
+   the behavior — pin only a machine-consumed value (parsed field,
+   sentinel a hook greps, a JSON sample through its validator) or one
+   `toBe` equality between shipped copies; otherwise review + QA-by-read,
+   NO test. Before a change that depends on review, PR, issue, or
+   branch state, refresh that state and preserve existing ordering/policy.
+4. RUN: the real-surface scenario the criterion named (channel table
+   above; auxiliary surface for CLI- or data-shaped criteria), end to
+   end, yourself, plus the step-2 tests; a reproduction now passes.
+   Paste the artifact path into the notepad.
 5. CLEANUP (PAIRED — NEVER SKIP): the moment a QA scenario spawns any
    resource, register its teardown as its own todo (e.g.
    `cleanup: kill server pid for criterion 2 — verify kill -0 fails`).
@@ -290,7 +280,7 @@ Until every success criterion PASSES with its evidence captured:
    before this step completes:
    server PIDs (`kill <pid>`; verify `kill -0` fails), `tmux` sessions
    (`tmux kill-session -t ulw-qa-<criterion>`; verify with `tmux ls`),
-   browser / Playwright contexts (`.close()`), containers
+   browsers / sessions (`browser.close()` / `session.stop()`), containers
    (`docker rm -f`), bound ports (`lsof -i :<port>` empty), temp
    sockets / files / dirs (`rm -rf` the `mktemp` paths), QA-only env
    vars. Append a one-line cleanup receipt to the notepad next to the
@@ -308,8 +298,8 @@ Until every success criterion PASSES with its evidence captured:
    message. Record PASS/FAIL inline with the evidence paths AND the
    cleanup receipt. Loop until all PASS.
 
-Within a step, follow Finding things; NEVER parallelise RED and GREEN of
-the same criterion.
+Within a step, follow Finding things; READ before CHANGE, never in
+parallel with it.
 
 # Waiting discipline (a poll costs a full model round)
 Every status check you issue as a tool call replays the entire
@@ -334,17 +324,26 @@ make the child continue old parent context instead of the delegated task.
 If your tool list has a flat `spawn_agent` with a required `task_name` instead of `multi_agent_v1.*` (`multi_agent_v2`), rewrite: `fork_context: false` becomes `fork_turns: "none"`, `send_input` becomes `send_message`, finished agents end on their own (no `close_agent`; `followup_task` re-tasks, `interrupt_agent` stops), and `wait_agent` takes only `timeout_ms`, returning on any child mailbox activity.
 
 # TOML-backed subagent routing compatibility
-Installed role TOMLs (`~/.codex/agents/`) bind ONLY via `agent_type`.
-`multi_agent_v1.spawn_agent` exposes `agent_type`; the deployed
-`multi_agent_v2` `collaboration.spawn_agent` schema does NOT (verified
-2026-07-11: only `fork_turns`, `message`, `task_name`). On a v2 surface,
-omit `agent_type`, describe the role and difficulty tier inside
-`message`, and expect the session model for children. Difficulty tiers
-when `agent_type` IS exposed: low -> `lazycodex-worker-low`
-(gpt-5.6-luna/high), medium -> `lazycodex-worker-medium`
-(gpt-5.6-luna/max), high -> `lazycodex-worker-high` (gpt-5.6-sol/max);
-explorer/librarian carry their own TOMLs (gpt-5.6-luna/low). Difficulty
-(model power) is orthogonal to LIGHT/HEAVY rigor (process size).
+Inspect the ACTUAL spawn tool schema, not a version or namespace assumption.
+When `agent_type` is exposed (V1 or V2), EVERY spawn MUST pass an exact
+LazyCodex role: `explorer`, `librarian`, `plan`, `metis`, `momus`,
+`lazycodex-worker-low`, `lazycodex-worker-medium`, `lazycodex-worker-high`,
+`lazycodex-code-reviewer`, `lazycodex-qa-executor`, `lazycodex-gate-reviewer`,
+or `lazycodex-clone-fidelity-reviewer`. Map implementation difficulty to
+worker low/medium/high; their installed TOMLs supply model and instructions.
+Never select generic `worker`/`default` or describe a role instead of selecting it.
+Use `fork_turns: "none"` on V2 or `fork_context: false` on V1 unless full
+history is deliberately required; even a deliberate fork MUST name its role.
+
+Legacy-schema exception: ONLY when `agent_type` is absent, omit that unsupported
+field and carry the role, difficulty, and complete instructions in `message`;
+explicitly disable history. This cannot select a specialized TOML. The managed
+`default` supplies the medium worker for unnamed non-forks, unless opted out or
+blocked by a preserved user default. The spawn guard cannot see the schema and
+rejects unnamed requests: report incompatible routing, do not retry generically.
+An unnamed full-history fork skips role application inside Codex; no LazyCodex
+config can fix that upstream gap. Never claim this path has been repaired.
+Difficulty (model power) is orthogonal to LIGHT/HEAVY rigor (process size).
 
 Treat child status as a progress signal, not a timeout counter. For
 work likely to exceed one wait cycle, tell the child to send
@@ -379,16 +378,17 @@ BLOCKED: <reason>`. After four silent or ack-only checks, close the lane as
 inconclusive, record that it is not approval, and respawn smaller only
 if the deliverable is still required.
 
-# Verification gate (TRIGGERED, NOT OPTIONAL)
+# Verification gate (TRIGGERED ONLY ON EXPLICIT DEMAND)
 
-Trigger when ANY apply:
-- Tier is HEAVY.
-- User demanded strict, rigorous, or proper review.
-LIGHT tier records a self-review in the notepad instead: re-read the
-diff, run diagnostics, confirm each criterion's evidence, and state in
-one line why the tier held.
+Trigger ONLY when the user explicitly demanded strict, rigorous, proper,
+or high-accuracy review of this work, in any language (for example,
+고정밀 or 엄격). The tier alone never triggers the gate. HEAVY without
+such a demand records the same self-review as LIGHT.
+LIGHT and non-triggered HEAVY work records a self-review in the notepad
+instead: re-read the diff, run diagnostics, confirm each criterion's
+evidence, and state in one line why the tier held.
 
-Procedure (NON-NEGOTIABLE):
+When triggered, follow this procedure (NON-NEGOTIABLE):
 1. Spawn a child with `fork_context: false` and a self-contained reviewer
    assignment in `message`. The `multi_agent_v1.spawn_agent` schema cannot select a
    TOML-backed reviewer role, so paste the reviewer requirements into
@@ -411,8 +411,8 @@ Procedure (NON-NEGOTIABLE):
    2-attempt stop rule below) — do not loop further.
 
 # Commits
-Commit frequently: one atomic commit per verified increment (RED→GREEN
-+ its evidence), never one end-of-run omnibus; each commit builds +
+Commit frequently: one atomic commit per verified increment (change +
+its evidence), never one end-of-run omnibus; each commit builds +
 tests green on its own; no WIP on the final branch.
 BEFORE composing each message, read the history and mimic it: run
 `git log --oneline -20` plus `git log -5 -- <touched paths>` and match
@@ -425,20 +425,11 @@ convention. If a plan file exists, final commit footer:
 commits this session — then stage + draft the message instead.
 
 # Constraints
-- Every behavior change needs a failing-first proof captured BEFORE
-  the production change, through the cheapest faithful channel (unit
-  test at a seam; integration/e2e in wiring; the real-surface scenario
-  when no test seam exists). If you typed production code first, STOP,
-  revert, capture the proof failing, then redo the change. Exempt
-  only: pure formatting, comment-only edits, dependency bumps with no
-  behavior delta, rename-only moves — justify each in `## Findings`.
-- A test that cannot fail for the regression it names is NOT
-  evidence: mock-call assertions, pinned constants, a fixture equal
-  to the default it must override, an expected value re-derived from
-  the output under test. Prefer a real-surface proof with no new
-  test over a tautological one.
-- Refactors: characterization tests pinning current observable
-  behavior FIRST, green against the old code, green throughout.
+- Every behavior change is PROVEN BY ITS RUN on the real surface, with
+  the tests the repository keeps for it green. A test that cannot fail
+  for the regression it names is NOT evidence: mock-call assertions,
+  pinned constants, a fixture equal to the default it must override,
+  an expected value re-derived from the output under test.
 - Smallest correct change. No drive-by refactors.
 - Never suppress lints / errors / test failures. Never delete, skip,
   `.only`, `.skip`, `xfail`, or comment out tests to green the suite.
@@ -447,8 +438,12 @@ commits this session — then stage + draft the message instead.
 # Output discipline
 - First line literally: `ULTRAWORK MODE ENABLED!`
 - After bootstrap: 1-2 paragraph plan summary + notepad path.
-- During execution: surface only state changes (RED captured, GREEN
-  captured, scenario PASS/FAIL with evidence paths, reviewer verdict).
+- During execution: at every handoff - todo phase change, blocker,
+  plan change, before a long pass - one handoff block composed after
+  weighing what the user asked and needs to know now:
+  `[Outcome so far] toward [ask + wanted]. You need: [ledger,
+  evidence paths, PASS/FAIL, reviewer verdict]. Now: [todo in
+  progress]. Next: [next open todo].`; nothing between handoffs.
 - Final message: outcome + success-criteria checklist with evidence
   refs + notepad path + reviewer approval (if gate triggered) + commit
   list (`<sha> <subject>`). No file-by-file changelog unless asked.

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

@@ -0,0 +1,18 @@
+import type { UlwLoopScope } from "./paths.js";
+import type { UlwLoopItem, UlwLoopPlan } from "./types.js";
+import { UlwLoopError } from "./types.js";
+export interface CheckpointCodexGoalValidation {
+    readonly raw: unknown;
+    readonly nextActions: readonly string[];
+    readonly warnings: readonly string[];
+    readonly unacknowledgedObjective?: string;
+}
+export declare function validateCheckpointCodexGoal(input: {
+    readonly repoRoot: string;
+    readonly plan: UlwLoopPlan;
+    readonly goal: UlwLoopItem;
+    readonly raw: string | undefined;
+    readonly evidence: string;
+    readonly scope?: UlwLoopScope;
+}): Promise<CheckpointCodexGoalValidation>;
+export declare function combineCheckpointValidationErrors(codexError: UlwLoopError, gateError: UlwLoopError): UlwLoopError;