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

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

@@ -0,0 +1,227 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { dirname } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { UlwLoopError } from "./types.js";
+// Cross-process exclusive lock for one ulw-loop state directory. Every CLI
+// invocation is its own process, so the in-process promise chain in plan-io
+// serializes nothing across them; this file-level lock is what makes the
+// read-modify-write of goals.json (and the counters next to it) atomic.
+//
+// Protocol: the lock is a file created with O_EXCL whose body records the
+// owner (pid + a per-acquisition token). A waiter reclaims it only when the
+// owner is provably gone (pid dead) or the body never became a record within
+// `staleMs` (a creator that died mid-write); a live owner is never reclaimed by
+// age alone, because overlapping two bodies is exactly the lost update this lock
+// exists to prevent. Waiters back off and fail closed at `timeoutMs`. Release
+// unlinks only a lock that still carries the releaser's own token.
+export const ULW_LOOP_LOCK_TIMEOUT_CODE = "ULW_LOOP_LOCK_TIMEOUT";
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_STALE_MS = 60_000;
+const MIN_DELAY_MS = 5;
+const MAX_DELAY_MS = 100;
+const SLEEP_CELL = new Int32Array(new SharedArrayBuffer(4));
+export async function withStateLock(lockPath, fn, options = {}) {
+    const token = await acquireAsync(lockPath, options);
+    try {
+        return await fn();
+    }
+    finally {
+        release(lockPath, token);
+    }
+}
+export function withStateLockSync(lockPath, fn, options = {}) {
+    const token = acquireSync(lockPath, options);
+    try {
+        return fn();
+    }
+    finally {
+        release(lockPath, token);
+    }
+}
+export function isStateLockTimeout(error) {
+    return error instanceof UlwLoopError && error.code === ULW_LOOP_LOCK_TIMEOUT_CODE;
+}
+async function acquireAsync(lockPath, options) {
+    const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+    mkdirSync(dirname(lockPath), { recursive: true });
+    for (let attempt = 0;;) {
+        const outcome = attemptOnce(lockPath, staleMs);
+        if (outcome.kind === "acquired")
+            return outcome.token;
+        if (outcome.kind === "retry")
+            continue;
+        if (Date.now() >= deadline)
+            throw lockTimeout(lockPath, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        await sleep(backoffMs(attempt));
+        attempt += 1;
+    }
+}
+function acquireSync(lockPath, options) {
+    const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+    mkdirSync(dirname(lockPath), { recursive: true });
+    for (let attempt = 0;;) {
+        const outcome = attemptOnce(lockPath, staleMs);
+        if (outcome.kind === "acquired")
+            return outcome.token;
+        if (outcome.kind === "retry")
+            continue;
+        if (Date.now() >= deadline)
+            throw lockTimeout(lockPath, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        Atomics.wait(SLEEP_CELL, 0, 0, backoffMs(attempt));
+        attempt += 1;
+    }
+}
+// EINTR surfaces raw from macOS fs syscalls under some runtimes; it is a retry, never a verdict.
+function attemptOnce(lockPath, staleMs) {
+    try {
+        const token = tryCreate(lockPath);
+        if (token !== null)
+            return { kind: "acquired", token };
+        const snapshot = readSnapshot(lockPath);
+        if (snapshot === null)
+            return { kind: "retry" };
+        if (isStale(snapshot, staleMs) && reclaim(lockPath, snapshot.raw))
+            return { kind: "retry" };
+        return { kind: "wait" };
+    }
+    catch (error) {
+        if (hasCode(error, "EINTR"))
+            return { kind: "wait" };
+        throw error;
+    }
+}
+function tryCreate(lockPath) {
+    let fd;
+    try {
+        fd = openSync(lockPath, "wx");
+    }
+    catch (error) {
+        if (hasCode(error, "EEXIST"))
+            return null;
+        throw error;
+    }
+    const record = { pid: process.pid, createdAt: new Date().toISOString(), token: randomUUID() };
+    try {
+        writeSync(fd, JSON.stringify(record));
+    }
+    catch (error) {
+        closeSync(fd);
+        // A failed write (e.g. EINTR) must not leave a partial lock the owner never recorded;
+        // otherwise later readers see a young ownerless lock and only age can retire it.
+        try {
+            unlinkSync(lockPath);
+        }
+        catch {
+            // another process already reclaimed the partial file; leave it alone
+        }
+        throw error;
+    }
+    closeSync(fd);
+    return record.token;
+}
+function readSnapshot(lockPath) {
+    try {
+        const raw = readFileSync(lockPath, "utf8");
+        const ageMs = Date.now() - statSync(lockPath).mtimeMs;
+        return { raw, record: parseRecord(raw), ageMs };
+    }
+    catch (error) {
+        if (hasCode(error, "ENOENT"))
+            return null;
+        throw error;
+    }
+}
+function parseRecord(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null)
+            return null;
+        const record = parsed;
+        const pid = record["pid"];
+        const createdAt = record["createdAt"];
+        const token = record["token"];
+        if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0 || typeof createdAt !== "string")
+            return null;
+        if (typeof token !== "string" || token.length === 0)
+            return null;
+        return { pid, createdAt, token };
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            return null;
+        throw error;
+    }
+}
+// A body that is not a record is a lock mid-write (or a foreign/legacy file); only
+// age retires it. A parsable record is stale only when its owner is dead: a live
+// owner running past staleMs is slow, not gone, and the waiter fails closed instead.
+function isStale(snapshot, staleMs) {
+    if (snapshot.record === null)
+        return snapshot.ageMs > staleMs;
+    return !isProcessAlive(snapshot.record.pid);
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (hasCode(error, "ESRCH"))
+            return false;
+        if (hasCode(error, "EPERM"))
+            return true;
+        throw error;
+    }
+}
+// Re-read right before unlinking so a lock that changed hands since the stale
+// verdict (a sibling waiter reclaimed and re-acquired it) is left alone.
+function reclaim(lockPath, expectedRaw) {
+    const current = readSnapshot(lockPath);
+    if (current === null)
+        return true;
+    if (current.raw !== expectedRaw)
+        return false;
+    try {
+        unlinkSync(lockPath);
+    }
+    catch (error) {
+        if (!hasCode(error, "ENOENT"))
+            throw error;
+    }
+    return true;
+}
+// Only the acquisition that wrote this token may unlink: if the file now carries
+// another token, a waiter has legitimately taken over and its lock must stand.
+function release(lockPath, token) {
+    const current = readSnapshot(lockPath);
+    if (current === null || current.record?.token !== token)
+        return;
+    try {
+        unlinkSync(lockPath);
+    }
+    catch (error) {
+        if (!hasCode(error, "ENOENT"))
+            throw error;
+    }
+}
+function backoffMs(attempt) {
+    const exponential = Math.min(MAX_DELAY_MS, MIN_DELAY_MS * 2 ** attempt);
+    return exponential + Math.random() * MIN_DELAY_MS;
+}
+function lockTimeout(lockPath, timeoutMs) {
+    const holder = readSnapshot(lockPath)?.record;
+    const owner = holder === undefined || holder === null ? "another process" : `pid ${holder.pid}`;
+    return new UlwLoopError(`ulw-loop state lock ${lockPath} is held by ${owner} for more than ${timeoutMs}ms; retry once that process finishes, or delete the lock file if that process is gone.`, ULW_LOOP_LOCK_TIMEOUT_CODE, {
+        details: {
+            lockPath,
+            timeoutMs,
+            ...(holder === undefined || holder === null ? {} : { holderPid: holder.pid }),
+        },
+    });
+}
+function hasCode(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}

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

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

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

@@ -0,0 +1,33 @@
+import { hasAllCriteriaPass, isFinalRunCompletionCandidate } from "./goal-status.js";
+import { ULW_LOOP_CREATE_GOALS_COMMAND } from "./plan-missing-recovery.js";
+/**
+ * `status --json` is the one call every agent already makes between steps, so it is
+ * also the cheapest place to answer "what now?" without a second round trip.
+ */
+export function statusNextActions(plan) {
+    const actions = [];
+    const active = plan.goals.find((goal) => goal.id === plan.activeGoalId);
+    if (plan.goals.length === 0)
+        actions.push(`No goals yet: bootstrap with \`${ULW_LOOP_CREATE_GOALS_COMMAND}\`.`);
+    else if (active !== undefined)
+        actions.push(...activeGoalActions(plan, active));
+    for (const goal of plan.goals.filter((candidate) => candidate.status === "review_blocked"))
+        actions.push(`${goal.id} is review_blocked: capture the reviewer verdict with \`omo-agent-toolkit ulw-loop record-review-blockers --goal-id ${goal.id} --title "<title>" --objective "<objective>" --evidence "<verdict>" --codex-goal-json '<get_goal json>'\`.`);
+    if (plan.evidenceLayoutVersion !== 2 || active === undefined)
+        actions.push("plan is evidence-layout v1; artifacts go under .omo/evidence/");
+    return actions;
+}
+function activeGoalActions(plan, active) {
+    const unresolved = active.successCriteria.filter((criterion) => criterion.status !== "pass");
+    if (unresolved.length > 0)
+        return [
+            `${active.id} has ${unresolved.length} unresolved criterion(s) (${unresolved.map((criterion) => criterion.id).join(", ")}): record proof with \`omo-agent-toolkit ulw-loop record-evidence --goal-id ${active.id} --criterion-id <id> --status pass --evidence "<observable proof>"\`.`,
+        ];
+    if (hasAllCriteriaPass(active) && isFinalRunCompletionCandidate(plan, active))
+        return [
+            `${active.id} passes every criterion and is the final story: update_goal complete, then checkpoint --print-template to build the final quality gate. Use status --json's currentAttemptDir for all quality-gate artifacts.`,
+        ];
+    return [
+        `${active.id} passes every criterion: close it with \`omo-agent-toolkit ulw-loop checkpoint --goal-id ${active.id} --status complete --evidence "<proof>" --codex-goal-json '<get_goal json>'\`. Put quality-gate artifacts under the currentAttemptDir shown by status --json.`,
+    ];
+}

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

@@ -1,11 +1,12 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, resolve, sep } from "node:path";
-import { normalizeUlwLoopSessionId, ulwLoopDir } from "./paths.js";
+import { normalizeUlwLoopSessionId, ulwLoopDir, ulwLoopStateLockPath } from "./paths.js";
+import { isStateLockTimeout, withStateLockSync } from "./state-lock.js";
 // Turn-death recovery only: Codex emits Stop when a turn ends, so a run that
 // dies mid-turn (crash, kill, context blowup before any Stop) never reaches
 // this handler. Mid-turn stalls are out of scope by design.
 const RESUME_CAP = 2;
-// Mirrors start-work-continuation's context-pressure bail-out: injecting a
+// Mirrors ulw-execute-continuation's context-pressure bail-out: injecting a
 // resume directive into an already-overflowing context makes things worse.
 const CONTEXT_PRESSURE_MARKERS = [
     "context compacted",
@@ -24,14 +25,15 @@ export function runStopResumeHook(input) {
         return "";
     if (boulderContinuationWillFire(payload.cwd, payload.session_id))
         return "";
-    const stateDir = ulwLoopDir(payload.cwd, { sessionId: payload.session_id });
+    const scope = { sessionId: payload.session_id };
+    const stateDir = ulwLoopDir(payload.cwd, scope);
     const plan = readPlan(join(stateDir, "goals.json"));
     if (plan === null || plan.aggregateCompletion?.status === "complete")
         return "";
     const goal = resumableGoal(plan);
     if (goal === undefined)
         return "";
-    if (!consumeResumeBudget(stateDir, goal.id))
+    if (!consumeResumeBudgetLocked(ulwLoopStateLockPath(payload.cwd, scope), stateDir, goal.id))
         return "";
     const output = {
         decision: "block",
@@ -62,6 +64,18 @@ function resumableGoal(plan) {
 function isResumableStatus(status) {
     return status === "pending" || status === "in_progress";
 }
+// A resume is a budgeted side effect; when the session lock cannot be taken the
+// hook stays silent (fail closed) instead of charging the counter unlocked.
+function consumeResumeBudgetLocked(lockPath, stateDir, goalId) {
+    try {
+        return withStateLockSync(lockPath, () => consumeResumeBudget(stateDir, goalId));
+    }
+    catch (error) {
+        if (isStateLockTimeout(error))
+            return false;
+        throw error;
+    }
+}
 // Two-strike cap keyed on ledger movement: an unchanged ledger.jsonl line
 // count across resumes means the loop is not progressing. The stuck marker is
 // a separate file — a ledger append would change the count and self-reset.
@@ -132,7 +146,7 @@ function readCounter(counterPath) {
         throw error;
     }
 }
-// Local ~10-LOC approximation of start-work-continuation's boulder check (no
+// Local ~10-LOC approximation of ulw-execute-continuation's boulder check (no
 // cross-component import allowed): any continuable work for this session means
 // that hook owns the Stop event, so this one stays silent.
 function boulderContinuationWillFire(cwd, sessionId) {
@@ -167,7 +181,7 @@ function transcriptShowsContextPressure(transcriptPath) {
         throw error;
     }
 }
-// start-work-continuation owns an active Boulder plan until its final gate marks
+// ulw-execute-continuation owns an active Boulder plan until its final gate marks
 // the work complete, including the zero-remaining checklist state.
 function boulderPlanHasChecklist(cwd, entry) {
     const activePlan = entry["active_plan"];

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

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

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

@@ -0,0 +1,75 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+export const REVIEWER_ROLES_BY_SURFACE = {
+    lazycodex: {
+        codeReview: "lazycodex-code-reviewer",
+        manualQa: "lazycodex-qa-executor",
+        gateReview: "lazycodex-gate-reviewer",
+    },
+    "omo-senpi": {
+        codeReview: "omo-senpi-code-reviewer",
+        manualQa: "omo-senpi-qa-executor",
+        gateReview: "omo-senpi-gate-reviewer",
+    },
+};
+export const GATE_REVIEWER_AGENT_NAMES = new Set(Object.values(REVIEWER_ROLES_BY_SURFACE).map((roles) => roles.gateReview));
+export const REQUIRED_GATE_SECTIONS_BY_SURFACE = {
+    lazycodex: ["manualQa", "gateReview", "iteration", "criteriaCoverage"],
+    "omo-senpi": ["manualQa", "gateReview", "iteration", "criteriaCoverage"],
+};
+export const OPTIONAL_GATE_SECTIONS_BY_SURFACE = {
+    lazycodex: ["codeReview"],
+    "omo-senpi": [],
+};
+export const GATE_SECTION_BY_ACCEPTOR = {
+    lazycodex: {
+        codeReview: [REVIEWER_ROLES_BY_SURFACE.lazycodex.codeReview, "main-session"],
+        manualQa: [REVIEWER_ROLES_BY_SURFACE.lazycodex.manualQa, "main-session"],
+        gateReview: [
+            REVIEWER_ROLES_BY_SURFACE.lazycodex.gateReview,
+            "category:deep",
+            "category:unspecified-high",
+            "category:unspecified-low",
+            "main-session",
+        ],
+    },
+    "omo-senpi": {
+        manualQa: ["main-session"],
+        gateReview: ["category:deep", "category:unspecified-high", "category:unspecified-low"],
+    },
+};
+export function reviewerRolesFor(surface) {
+    return REVIEWER_ROLES_BY_SURFACE[surface];
+}
+export const SURFACE_MARKER_FILENAME = "surface.json";
+const SURFACE_ENV_KEY = "OMO_AGENT_TOOLKIT_SURFACE";
+function parseSurface(value) {
+    return value === "lazycodex" || value === "omo-senpi" ? value : null;
+}
+// Resolution order: explicit env override (tests, doctor probes) -> staged surface.json marker
+// sitting next to the running bundle -> lazycodex default. The marker is distribution-baked, so a
+// malformed marker falls back to the default instead of crashing checkpoint validation; the env
+// override remains available to force the intended surface on a damaged install.
+export function resolveToolkitSurface(options) {
+    const env = options?.env ?? process.env;
+    const fromEnv = parseSurface(env[SURFACE_ENV_KEY]);
+    if (fromEnv !== null)
+        return fromEnv;
+    const entryDir = options?.entryDir ?? dirname(fileURLToPath(import.meta.url));
+    const markerPath = join(entryDir, SURFACE_MARKER_FILENAME);
+    return readMarkerSurface(markerPath) ?? "lazycodex";
+}
+function readMarkerSurface(markerPath) {
+    try {
+        if (!existsSync(markerPath))
+            return null;
+        const parsed = JSON.parse(readFileSync(markerPath, "utf8"));
+        return parseSurface(parsed["surface"]);
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return null;
+        throw error;
+    }
+}

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

@@ -7,7 +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.6) Checking Ulw-Loop Steering"
+						"statusMessage": "(OmO 5.0.0-beta.60) Checking Ulw-Loop Steering"
+					}
+				]
+			}
+		],
+		"PostToolUse": [
+			{
+				"matcher": "^(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"
 					}
 				]
 			}
@@ -20,7 +33,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook pre-tool-use",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.6) Enforcing Unlimited Ulw-Loop Budget"
+						"statusMessage": "(OmO 5.0.0-beta.60) Enforcing Unlimited Ulw-Loop Budget"
 					}
 				]
 			},
@@ -31,7 +44,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook pre-tool-use-spawn",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.6) Guarding Ulw-Loop Spawns"
+						"statusMessage": "(OmO 5.0.0-beta.60) Guarding Ulw-Loop Spawns"
 					}
 				]
 			}
@@ -43,7 +56,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook stop",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.0.0-beta.6) Checking Ulw-Loop Resume"
+						"statusMessage": "(OmO 5.0.0-beta.60) 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.6",
+	"version": "5.0.0-beta.60",
 	"description": "Codex plugin: durable repo-native multi-goal orchestration with embedded success criteria and observable evidence audit.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",
@@ -38,7 +38,7 @@
 		"CHANGELOG.md"
 	],
 	"scripts": {
-		"build": "tsc -p tsconfig.build.json",
+		"build": "tsc -p tsconfig.build.json && bun build src/cli.ts --target node --format esm --outfile dist/cli.js",
 		"test": "vitest --run",
 		"test:watch": "vitest",
 		"typecheck": "tsc --noEmit",
@@ -47,10 +47,10 @@
 		"check": "tsc --noEmit && biome check . && npm run build"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "2.4.16",
-		"@types/node": "^25.9.3",
-		"typescript": "^6.0.3",
-		"vitest": "^4.1.8"
+		"@biomejs/biome": "2.5.9",
+		"@types/node": "^26.2.0",
+		"typescript": "^7.0.2",
+		"vitest": "^4.1.11"
 	},
 	"engines": {
 		"node": ">=20.0.0"

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

@@ -1,6 +1,6 @@
 ---
 name: ulw-loop
-description: Goal-like loop that uses ultrawork mode to decompose work into systematic, evidence-bound steps.
+description: "A goal-like loop that decomposes work into systematic, evidence-bound ultrawork steps. Use when the user wants a goal loop or durable, checkpointed execution."
 metadata:
   short-description: Goal-like ultrawork loop for systematic decomposition
 ---
@@ -15,14 +15,16 @@ This skill is intentionally compact. The full workflow lives in `references/full
 
 1. Open `references/full-workflow.md`.
 2. Read through **Bootstrap** (including its tier triage), **Execution Loop**, the **Manual-QA channels** table, and the **Stop Rules** before running any ULW command or recording evidence.
-3. If the task has code edits, tests, QA, or commit work, follow the full workflow's delegation and evidence rules. Tests alone never prove done.
+3. Open `references/define-goal.md` and register the run's goal by it. Goal creation is NEVER skipped: shape the objective and every success criterion by that reference before any implementation.
+4. If the task has code edits, tests, QA, or commit work, follow the full workflow's delegation and evidence rules. Tests alone never prove done.
 
 ## Non-Negotiables
 
 - Use the ulw-loop CLI state under `.omo/ulw-loop`; do not hand-edit goal state.
-- Register goals up front (`omo-agent-toolkit ulw-loop create-goals`, then `create_goal` from the printed handoff) and mirror every atomic step into the live `update_plan` checklist: one ultra-granular step per action, exactly one in_progress, transitions marked the instant they happen.
+- Register goals up front, shaped by `references/define-goal.md` (`omo-agent-toolkit ulw-loop create-goals`, then `create_goal` from the printed handoff), and mirror every atomic step into the live `update_plan` checklist: one ultra-granular step per action, exactly one in_progress, transitions marked the instant they happen.
 - After any compaction or context loss, re-read brief + goals + ledger FIRST plus `omo-agent-toolkit ulw-loop status --json`, then resume; never re-plan from scratch.
-- If `omo-agent-toolkit ulw-loop create-goals` says the existing aggregate is already complete, start unrelated new work with a fresh `--session-id <new-id>` instead of steering or forcing the completed default state. Use `--force` only to intentionally overwrite completed evidence.
+- Every ulw-loop command needs the session scope: pass `--session-id <id>` (the printed handoff and resume directive carry it; `CODEX_THREAD_ID` in the environment also resolves it). The CLI refuses unscoped state (`ULW_LOOP_SESSION_SCOPE_REQUIRED`) instead of touching the shared `.omo/ulw-loop` root.
+- If `omo-agent-toolkit ulw-loop create-goals` says this session's aggregate is already complete, start unrelated new work with a fresh `--session-id <new-id>` (passed on every later call) instead of steering or forcing the completed state. Use `--force` only to intentionally overwrite completed evidence.
 - Every success criterion needs observable evidence from a real surface: a channel (terminal/TUI via the xterm.js web terminal, HTTP, browser, computer-use) or, for CLI- or data-shaped criteria, an auxiliary surface (CLI stdout, DB diff, parsed config dump).
 - Evidence is bound to the tree it was captured at (`git rev-parse --short "HEAD^{tree}"`); it goes stale only when tracked content changes — a rebase or amend that keeps the tree identical keeps it valid. When the tree differs, re-run at the current HEAD and re-record, never relabel or regenerate. Record only after cleanup receipts exist.
 - Delegate code edits, test writes, fixes, and QA execution to right-sized Codex subagents when the workflow requires it.
@@ -66,3 +68,7 @@ Codex exposes ONE subagent surface per session — check your tool list. GPT-5.6
 V1 fallback (gpt-5.5, gpt-5.6-luna): `multi_agent_v1.spawn_agent({...,"fork_context":false})`, `multi_agent_v1.send_input` (re-task), `multi_agent_v1.wait_agent({"targets":[...],"timeout_ms":...})`, `multi_agent_v1.close_agent`.
 
 When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`.
+
+## Driver goal lifecycle
+
+The Codex thread goal is a DRIVER the loop instructs, never a gate. `checkpoint` takes an OPTIONAL `--codex-goal-json` snapshot, records it verbatim in the ledger, and never rejects on its status or objective; the advice arrives in `nextActions`. A driver completed early yields advice to `create_goal` again with the plan's objective verbatim; `paused`, `usage_limited`, and `budget_limited` yield resume advice; a differing objective is a warning, not a refusal. Malformed snapshot input is the only failure, reported as `ULW_LOOP_CODEX_GOAL_JSON_INVALID`.