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

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

@@ -1,120 +1,159 @@
 import { randomUUID } from "node:crypto";
-import { closeSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { closeSync, ftruncateSync, 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.
-
+// O_EXCL establishes ownership. Async holders keep the fd open and refresh a
+// lease through that fd, never through the pathname: a reclaimed inode is invisible.
+// Sync/legacy holders are lease-less and only dead pids retire their records.
+// Expiry permits overlapping bodies; immutable revision publication fences them.
+// Reclaim's reread/unlink is not atomic. On Windows an open inode may not unlink:
+// treat that refusal as a live owner and fail closed. Release checks its token.
 export const ULW_LOOP_LOCK_TIMEOUT_CODE = "ULW_LOOP_LOCK_TIMEOUT";
-
+export interface StateLockClock {
+	readonly now: () => number;
+	readonly schedule: (fn: () => void, ms: number) => { unref(): void; cancel(): void };
+}
 export interface StateLockOptions {
 	readonly timeoutMs?: number;
 	readonly staleMs?: number;
+	readonly leaseMs?: number;
+	readonly heartbeatMs?: number;
+	readonly clock?: StateLockClock;
 }
-
 interface LockRecord {
 	readonly pid: number;
 	readonly createdAt: string;
 	readonly token: string;
+	leaseUntil?: number;
+}
+interface Holder {
+	readonly fd: number;
+	readonly record: LockRecord;
 }
-
 interface LockSnapshot {
 	readonly raw: string;
 	readonly record: LockRecord | null;
 	readonly ageMs: number;
 }
-
-type AttemptOutcome = { readonly kind: "acquired"; readonly token: string } | { readonly kind: "retry" | "wait" };
-
+type AttemptOutcome = { readonly kind: "acquired"; readonly holder: Holder } | { readonly kind: "retry" | "wait" };
 const DEFAULT_TIMEOUT_MS = 10_000;
 const DEFAULT_STALE_MS = 60_000;
-const MIN_DELAY_MS = 5;
-const MAX_DELAY_MS = 100;
+const DEFAULT_LEASE_MS = 30_000;
 const SLEEP_CELL = new Int32Array(new SharedArrayBuffer(4));
+const systemClock: StateLockClock = {
+	now: Date.now,
+	schedule(fn, ms) {
+		const timer = setTimeout(fn, ms);
+		return {
+			unref: () => {
+				timer.unref();
+			},
+			cancel: () => clearTimeout(timer),
+		};
+	},
+};
 
 export async function withStateLock<T>(
 	lockPath: string,
-	fn: () => Promise<T>,
+	fn: (token: string) => Promise<T>,
 	options: StateLockOptions = {},
 ): Promise<T> {
-	const token = await acquireAsync(lockPath, options);
+	const holder = await acquireAsync(lockPath, options);
+	const clock = options.clock ?? systemClock;
+	let timer: ReturnType<StateLockClock["schedule"]> | undefined;
+	let heartbeatError: unknown;
+	const beat = () => {
+		try {
+			holder.record.leaseUntil = clock.now() + (options.leaseMs ?? DEFAULT_LEASE_MS);
+			writeRecord(holder);
+			schedule();
+		} catch (error) {
+			heartbeatError = error;
+		}
+	};
+	const schedule = () => {
+		if (options.heartbeatMs === 0) return;
+		timer = clock.schedule(beat, options.heartbeatMs ?? (options.leaseMs ?? DEFAULT_LEASE_MS) / 3);
+		timer.unref();
+	};
+	schedule();
 	try {
-		return await fn();
+		const result = await fn(holder.record.token);
+		if (heartbeatError !== undefined) throw heartbeatError;
+		return result;
 	} finally {
-		release(lockPath, token);
+		timer?.cancel();
+		closeSync(holder.fd);
+		release(lockPath, holder.record.token);
 	}
 }
-
 export function withStateLockSync<T>(lockPath: string, fn: () => T, options: StateLockOptions = {}): T {
-	const token = acquireSync(lockPath, options);
+	const holder = acquireSync(lockPath, options);
 	try {
 		return fn();
 	} finally {
-		release(lockPath, token);
+		closeSync(holder.fd);
+		release(lockPath, holder.record.token);
 	}
 }
-
 export function isStateLockTimeout(error: unknown): error is UlwLoopError {
 	return error instanceof UlwLoopError && error.code === ULW_LOOP_LOCK_TIMEOUT_CODE;
 }
-
-async function acquireAsync(lockPath: string, options: StateLockOptions): Promise<string> {
-	const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
-	const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+async function acquireAsync(lockPath: string, options: StateLockOptions): Promise<Holder> {
+	const clock = options.clock ?? systemClock;
+	const deadline = clock.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
 	mkdirSync(dirname(lockPath), { recursive: true });
 	for (let attempt = 0; ; ) {
-		const outcome = attemptOnce(lockPath, staleMs);
-		if (outcome.kind === "acquired") return outcome.token;
+		const outcome = attemptOnce(lockPath, options, clock.now(), options.leaseMs ?? DEFAULT_LEASE_MS);
+		if (outcome.kind === "acquired") return outcome.holder;
 		if (outcome.kind === "retry") continue;
-		if (Date.now() >= deadline) throw lockTimeout(lockPath, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
-		await sleep(backoffMs(attempt));
+		if (clock.now() >= deadline) throw lockTimeout(lockPath, options);
+		await new Promise<void>((resolve) => clock.schedule(resolve, backoffMs(attempt)));
 		attempt += 1;
 	}
 }
-
-function acquireSync(lockPath: string, options: StateLockOptions): string {
+function acquireSync(lockPath: string, options: StateLockOptions): Holder {
 	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;
+		const outcome = attemptOnce(lockPath, options, Date.now());
+		if (outcome.kind === "acquired") return outcome.holder;
 		if (outcome.kind === "retry") continue;
-		if (Date.now() >= deadline) throw lockTimeout(lockPath, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+		if (Date.now() >= deadline) throw lockTimeout(lockPath, options);
 		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: string, staleMs: number): AttemptOutcome {
+function attemptOnce(lockPath: string, options: StateLockOptions, now: number, leaseMs?: number): AttemptOutcome {
 	try {
-		const token = tryCreate(lockPath);
-		if (token !== null) return { kind: "acquired", token };
-		const snapshot = readSnapshot(lockPath);
+		const holder = tryCreate(lockPath, now, leaseMs);
+		if (holder !== null) return { kind: "acquired", holder };
+		const snapshot = readSnapshot(lockPath, now);
 		if (snapshot === null) return { kind: "retry" };
-		if (isStale(snapshot, staleMs) && reclaim(lockPath, snapshot.raw)) return { kind: "retry" };
+		const record = snapshot.record;
+		const stale =
+			record === null
+				? snapshot.ageMs > (options.staleMs ?? DEFAULT_STALE_MS)
+				: !isProcessAlive(record.pid) || (record.leaseUntil !== undefined && now > record.leaseUntil);
+		if (stale && reclaim(lockPath, snapshot.raw)) return { kind: "retry" };
 		return { kind: "wait" };
 	} catch (error) {
 		if (hasCode(error, "EINTR")) return { kind: "wait" };
 		throw error;
 	}
 }
-
-function tryCreate(lockPath: string): string | null {
+function writeRecord(holder: Holder): void {
+	const buf = Buffer.from(JSON.stringify(holder.record));
+	ftruncateSync(holder.fd, 0);
+	let offset = 0;
+	while (offset < buf.length) {
+		const written = writeSync(holder.fd, buf, offset, buf.length - offset, offset);
+		if (written === 0) throw new Error("State lock write made no progress.");
+		offset += written;
+	}
+}
+function tryCreate(lockPath: string, now: number, leaseMs?: number): Holder | null {
 	let fd: number;
 	try {
 		fd = openSync(lockPath, "wx");
@@ -122,60 +161,54 @@ function tryCreate(lockPath: string): string | null {
 		if (hasCode(error, "EEXIST")) return null;
 		throw error;
 	}
-	const record: LockRecord = { pid: process.pid, createdAt: new Date().toISOString(), token: randomUUID() };
+	const record: LockRecord = {
+		pid: process.pid,
+		createdAt: new Date(now).toISOString(),
+		token: randomUUID(),
+		...(leaseMs === undefined ? {} : { leaseUntil: now + leaseMs }),
+	};
+	const holder = { fd, record };
 	try {
-		writeSync(fd, JSON.stringify(record));
+		writeRecord(holder);
 	} 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
+		} catch (cleanup) {
+			if (!hasCode(cleanup, "ENOENT")) throw cleanup;
 		}
 		throw error;
 	}
-	closeSync(fd);
-	return record.token;
+	return holder;
 }
-
-function readSnapshot(lockPath: string): LockSnapshot | null {
+function readSnapshot(lockPath: string, now: number): LockSnapshot | null {
 	try {
 		const raw = readFileSync(lockPath, "utf8");
-		const ageMs = Date.now() - statSync(lockPath).mtimeMs;
-		return { raw, record: parseRecord(raw), ageMs };
+		return { raw, record: parseRecord(raw), ageMs: now - statSync(lockPath).mtimeMs };
 	} catch (error) {
 		if (hasCode(error, "ENOENT")) return null;
 		throw error;
 	}
 }
-
 function parseRecord(raw: string): LockRecord | null {
 	try {
-		const parsed: unknown = JSON.parse(raw);
-		if (typeof parsed !== "object" || parsed === null) return null;
-		const record = parsed as Record<string, unknown>;
-		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 };
+		const record: unknown = JSON.parse(raw);
+		if (typeof record !== "object" || record === null) return null;
+		if (!("pid" in record) || typeof record.pid !== "number" || !Number.isInteger(record.pid) || record.pid <= 0)
+			return null;
+		if (!("createdAt" in record) || typeof record.createdAt !== "string") return null;
+		if (!("token" in record) || typeof record.token !== "string" || record.token.length === 0) return null;
+		return {
+			pid: record.pid,
+			createdAt: record.createdAt,
+			token: record.token,
+			...("leaseUntil" in record && typeof record.leaseUntil === "number" ? { leaseUntil: record.leaseUntil } : {}),
+		};
 	} 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: LockSnapshot, staleMs: number): boolean {
-	if (snapshot.record === null) return snapshot.ageMs > staleMs;
-	return !isProcessAlive(snapshot.record.pid);
-}
-
 function isProcessAlive(pid: number): boolean {
 	try {
 		process.kill(pid, 0);
@@ -186,54 +219,39 @@ function isProcessAlive(pid: number): boolean {
 		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: string, expectedRaw: string): boolean {
-	const current = readSnapshot(lockPath);
+	const current = readSnapshot(lockPath, Date.now());
 	if (current === null) return true;
 	if (current.raw !== expectedRaw) return false;
 	try {
 		unlinkSync(lockPath);
 	} catch (error) {
+		if (hasCode(error, "EPERM") || hasCode(error, "EACCES")) return false;
 		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: string, token: string): void {
-	const current = readSnapshot(lockPath);
-	if (current === null || current.record?.token !== token) return;
+	if (readSnapshot(lockPath, Date.now())?.record?.token !== token) return;
 	try {
 		unlinkSync(lockPath);
 	} catch (error) {
 		if (!hasCode(error, "ENOENT")) throw error;
 	}
 }
-
 function backoffMs(attempt: number): number {
-	const exponential = Math.min(MAX_DELAY_MS, MIN_DELAY_MS * 2 ** attempt);
-	return exponential + Math.random() * MIN_DELAY_MS;
+	return Math.min(100, 5 * 2 ** attempt) + Math.random() * 5;
 }
-
-function lockTimeout(lockPath: string, timeoutMs: number): UlwLoopError {
-	const holder = readSnapshot(lockPath)?.record;
-	const owner = holder === undefined || holder === null ? "another process" : `pid ${holder.pid}`;
+function lockTimeout(lockPath: string, options: StateLockOptions): UlwLoopError {
+	const holder = readSnapshot(lockPath, Date.now())?.record;
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const owner = 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 state lock ${lockPath} is held by ${owner} for more than ${timeoutMs}ms. The lock owner is still alive. If a JS eval kernel was interrupted while writing, wait for its lease to expire (${options.leaseMs ?? DEFAULT_LEASE_MS} ms) or restart the owning senpi process; never delete a lock owned by a live process.`,
 		ULW_LOOP_LOCK_TIMEOUT_CODE,
-		{
-			details: {
-				lockPath,
-				timeoutMs,
-				...(holder === undefined || holder === null ? {} : { holderPid: holder.pid }),
-			},
-		},
+		{ details: { lockPath, timeoutMs, ...(holder == null ? {} : { holderPid: holder.pid }) } },
 	);
 }
-
 function hasCode(error: unknown, code: string): boolean {
 	return error instanceof Error && "code" in error && error.code === code;
 }

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

@@ -1,36 +1,45 @@
 import { hasAllCriteriaPass, isFinalRunCompletionCandidate } from "./goal-status.js";
-import { ULW_LOOP_CREATE_GOALS_COMMAND } from "./plan-missing-recovery.js";
+import { createGoalsAction } from "./plan-missing-recovery.js";
+import type { UlwLoopToolkitSurface } from "./surface.js";
 import type { UlwLoopItem, UlwLoopPlan } from "./types.js";
 
 /**
- * `status --json` is the one call every agent already makes between steps, so it is
+ * Status 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: UlwLoopPlan): readonly string[] {
+export function statusNextActions(plan: UlwLoopPlan, surface: UlwLoopToolkitSurface = "lazycodex"): readonly string[] {
 	const actions: string[] = [];
 	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));
+	if (plan.goals.length === 0) actions.push(`No goals yet: bootstrap with \`${createGoalsAction(surface)}\`.`);
+	else if (active !== undefined) actions.push(...activeGoalActions(plan, active, surface));
 	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>'\`.`,
+			surface === "omo-senpi"
+				? `${goal.id} is review_blocked: capture the reviewer verdict with \`agentToolkit.recordReviewBlockers({ goalId: "${goal.id}", title: "<title>", objective: "<objective>", evidence: "<verdict>" })\`.`
+				: `${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: UlwLoopPlan, active: UlwLoopItem): readonly string[] {
+function activeGoalActions(plan: UlwLoopPlan, active: UlwLoopItem, surface: UlwLoopToolkitSurface): readonly string[] {
 	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>"\`.`,
+			surface === "omo-senpi"
+				? `${active.id} has ${unresolved.length} unresolved criterion(s) (${unresolved.map((criterion) => criterion.id).join(", ")}): record proof with \`agentToolkit.recordEvidence({ goalId: "${active.id}", criterionId: "<id>", status: "pass", evidence: "<observable proof>" })\`.`
+				: `${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.`,
+			surface === "omo-senpi"
+				? `${active.id} passes every criterion and is the final story: complete the driver goal, then call \`agentToolkit.checkpoint({ goalId: "${active.id}", printTemplate: true })\` to build the final quality gate. Use status().result.currentAttemptDir for all quality-gate artifacts.`
+				: `${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.`,
+		surface === "omo-senpi"
+			? `${active.id} passes every criterion: close it with \`agentToolkit.checkpoint({ goalId: "${active.id}", status: "complete", evidence: "<proof>" })\`. Put quality-gate artifacts under status().result.currentAttemptDir.`
+			: `${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/src/steering-batch.ts

@@ -1,6 +1,7 @@
 // biome-ignore-all format: compact batch steering module stays below the pure LOC budget.
 import type { UlwLoopScope } from "./paths.js";
-import { appendLedger, appendLedgerEntries, findAcceptedSteeringLedgerEntry, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
+import { commit } from "./plan-commit.js";
+import { findAcceptedSteeringLedgerEntry, readUlwLoopPlan, withUlwLoopMutationLock } from "./plan-io.js";
 import { applySteeringMutation, validateUlwLoopSteeringProposal } from "./steering.js";
 import { buildSteeringPlanSnapshot, changedGoalIdsBetween } from "./steering-snapshot.js";
 import type { UlwLoopLedgerEntry, UlwLoopPlan, UlwLoopSteeringAudit, UlwLoopSteeringProposal } from "./types.js";
@@ -43,17 +44,16 @@ export async function steerUlwLoopBatch(
 		const failed = prepared.results.find((item) => !item.accepted);
 		if (failed !== undefined) {
 			const entry = rejectedLedgerEntry(prepared.results);
-			await appendLedger(repoRoot, entry, scope);
+			await commit(repoRoot, scope, { plan, entries: [entry] });
 			return rejected(plan, prepared.results, failed.rejectedReasons);
 		}
 		let next = plan;
 		for (const item of prepared.items) if (item.kind === "fresh") next = item.prepared.next;
 		const fresh = prepared.items.filter((item): item is Extract<PreparedItem, { readonly kind: "fresh" }> => item.kind === "fresh");
 		if (fresh.length > 0) {
-			await writePlan(repoRoot, next, scope);
 			const entries = fresh.map((item) => ledgerEntry(item.prepared.proposal, item.prepared.audit, item.prepared.proposal.now?.toISOString() ?? iso()));
 			const batchEntry = batchUpdateLedgerEntry(plan, next, iso());
-			await appendLedgerEntries(repoRoot, batchEntry === null ? entries : [...entries, batchEntry], scope);
+			await commit(repoRoot, scope, { plan: next, entries: batchEntry === null ? entries : [...entries, batchEntry] });
 		}
 		return { plan: next, accepted: true, results: prepared.results, rejectedReasons: [] };
 	});

package/packages/omo-codex/plugin/components/ulw-loop/src/steering-mutations.ts

@@ -1,5 +1,6 @@
 // biome-ignore-all format: compact extracted steering mutations stay below the pure LOC budget.
 import { seedDefaultSuccessCriteria } from "./plan-crud.js";
+import type { UlwLoopToolkitSurface } from "./surface.js";
 import type { UlwLoopItem, UlwLoopPlan, UlwLoopSteeringChildGoal, UlwLoopSteeringProposal, UlwLoopSuccessCriterionUserModel } from "./types.js";
 import { ULW_LOOP_SUCCESS_CRITERION_USER_MODELS } from "./types.js";
 import { updateBatchesAfterSupersede } from "./validation-batch.js";
@@ -30,9 +31,9 @@ function nextId(plan: UlwLoopPlan, offset: number): string {
 	return `G${String(max + offset).padStart(3, "0")}`;
 }
 
-export function makeGoal(plan: UlwLoopPlan, childGoal: UlwLoopSteeringChildGoal, evidence: string, now: string, offset: number): UlwLoopItem {
+export function makeGoal(plan: UlwLoopPlan, childGoal: UlwLoopSteeringChildGoal, evidence: string, now: string, offset: number, surface: UlwLoopToolkitSurface = "lazycodex"): UlwLoopItem {
 	const id = nextId(plan, offset); const digits = /^G(\d+)/u.exec(id)?.[1]; const goalIndex = digits === undefined ? plan.goals.length + offset - 1 : Number(digits) - 1;
-	return { id, title: childGoal.title, objective: childGoal.objective, status: "pending", successCriteria: seedDefaultSuccessCriteria(goalIndex, childGoal.objective), attempt: 0, createdAt: now, updatedAt: now, evidence };
+	return { id, title: childGoal.title, objective: childGoal.objective, status: "pending", successCriteria: seedDefaultSuccessCriteria(goalIndex, childGoal.objective, { goalId: id, surface }), attempt: 0, createdAt: now, updatedAt: now, evidence };
 }
 
 export function reviseWording(plan: UlwLoopPlan, proposal: UlwLoopSteeringProposal, now: string): void {
@@ -41,9 +42,9 @@ export function reviseWording(plan: UlwLoopPlan, proposal: UlwLoopSteeringPropos
 	target.steeringEvidence = proposal.evidence; target.steeringRationale = proposal.rationale; target.updatedAt = now;
 }
 
-export function splitOrBlock(plan: UlwLoopPlan, proposal: UlwLoopSteeringProposal, now: string): void {
+export function splitOrBlock(plan: UlwLoopPlan, proposal: UlwLoopSteeringProposal, now: string, surface: UlwLoopToolkitSurface = "lazycodex"): void {
 	const target = goal(plan, targets(proposal)[0]); if (target === undefined) return;
-	const replacements = children(proposal).map((item, index) => makeGoal(plan, item, proposal.evidence, now, index + 1));
+	const replacements = children(proposal).map((item, index) => makeGoal(plan, item, proposal.evidence, now, index + 1, surface));
 	target.steeringEvidence = proposal.evidence; target.steeringRationale = proposal.rationale; target.updatedAt = now;
 	if (replacements.length === 0) { target.status = "blocked"; target.steeringStatus = "blocked"; target.blockedReason = proposal.blockedReason ?? proposal.rationale; }
 	else { target.steeringStatus = "superseded"; target.supersededBy = replacements.map((item) => item.id); for (const item of replacements) item.supersedes = [target.id]; plan.goals.splice(plan.goals.indexOf(target) + 1, 0, ...replacements); updateBatchesAfterSupersede(plan, target.id, replacements.map((item) => item.id)); }

package/packages/omo-codex/plugin/components/ulw-loop/src/steering-types.ts

@@ -1,4 +1,8 @@
-import type { UlwLoopSteeringMutationKind, UlwLoopSteeringSource } from "./constants.js";
+import type {
+	UlwLoopSteeringMutationKind,
+	UlwLoopSteeringSource,
+	UlwLoopSuccessCriterionUserModel,
+} from "./constants.js";
 import type { UlwLoopItem, UlwLoopPlan } from "./domain-types.js";
 
 export interface UlwLoopSteeringInvariantResult {
@@ -25,9 +29,17 @@ export interface UlwLoopSteeringAfterPayload {
 export interface UlwLoopSteeringProposal {
 	kind: UlwLoopSteeringMutationKind;
 	source: UlwLoopSteeringSource;
+	/** Alias of `targetGoalId`; the SDK documentation uses `goalId` like every other operation. */
+	goalId?: string;
 	targetGoalId?: string;
 	targetGoalIds?: string[];
 	criterionId?: string;
+	/** `revise_criterion` payload: the replacement scenario text. */
+	scenario?: string;
+	/** `revise_criterion` payload: the replacement observable-proof text. */
+	expectedEvidence?: string;
+	/** `revise_criterion` payload: the replacement user model. */
+	userModel?: UlwLoopSuccessCriterionUserModel;
 	evidence: string;
 	rationale: string;
 	title?: string;

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

@@ -1,9 +1,11 @@
 // biome-ignore-all format: compact steering module must stay below the 240 pure-LOC budget
 import { isUlwLoopDone } from "./goal-status.js";
 import type { UlwLoopScope } from "./paths.js";
-import { appendLedger, findAcceptedSteeringLedgerEntry, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
+import { commit } from "./plan-commit.js";
+import { findAcceptedSteeringLedgerEntry, readUlwLoopPlan, withUlwLoopMutationLock } from "./plan-io.js";
 import { makeGoal, reviseCriterion, reviseWording, splitOrBlock } from "./steering-mutations.js";
 import { buildSteeringPlanSnapshot, changedGoalIdsBetween } from "./steering-snapshot.js";
+import type { UlwLoopToolkitSurface } from "./surface.js";
 import type {
 	SteerUlwLoopResult,
 	UlwLoopItem,
@@ -20,7 +22,7 @@ import { iso, ULW_LOOP_STEERING_MUTATION_KINDS, ULW_LOOP_SUCCESS_CRITERION_USER_
 import { batchUpdateLedgerEntry } from "./validation-batch.js";
 
 const SOURCES = ["user_prompt_submit", "finding", "cli"] as const satisfies readonly UlwLoopSteeringSource[];
-const PROTECTED = new Set(["aggregateCompletion", "codexObjective", "codexObjectiveAliases", "originalConstraints", "qualityGate", "status", "completedAt", "completionStatus"]);
+const PROTECTED = new Set(["aggregateCompletion", "codexObjective", "codexObjectiveAliases", "acknowledgedDriverObjectives", "originalConstraints", "qualityGate", "status", "completedAt", "completionStatus"]);
 const isObject = (value: unknown): value is object => typeof value === "object" && value !== null; const isPlain = (value: unknown): value is object => isObject(value) && !Array.isArray(value);
 const read = (value: object, key: string): unknown => Object.entries(value).find(([name]) => name === key)?.[1];
 const isText = (value: unknown): value is string => typeof value === "string" && value.trim().length > 0;
@@ -155,17 +157,17 @@ function validateCriterion(plan: UlwLoopPlan, proposal: object, reasons: string[
 	if (model !== undefined && !isModel(model)) reasons.push("invalid userModel");
 }
 
-export function applySteeringMutation(plan: UlwLoopPlan, proposal: UlwLoopSteeringProposal, audit: UlwLoopSteeringAudit): UlwLoopPlan {
+export function applySteeringMutation(plan: UlwLoopPlan, proposal: UlwLoopSteeringProposal, audit: UlwLoopSteeringAudit, surface: UlwLoopToolkitSurface = "lazycodex"): UlwLoopPlan {
 	const next = structuredClone(plan);
 	if (!audit.invariant.accepted) return next;
 	const now = proposal.now?.toISOString() ?? iso();
-	if (proposal.kind === "add_subgoal") next.goals.push(makeGoal(next, { title: proposal.title ?? "", objective: proposal.objective ?? "" }, proposal.evidence, now, 1));
+	if (proposal.kind === "add_subgoal") next.goals.push(makeGoal(next, { title: proposal.title ?? "", objective: proposal.objective ?? "" }, proposal.evidence, now, 1, surface));
 	if (proposal.kind === "reorder_pending") {
 		const order = pendingOrder(proposal);
 		next.goals = [...order.map((id) => goal(next, id)).filter((item): item is UlwLoopItem => item !== undefined), ...next.goals.filter((item) => !order.includes(item.id))];
 	}
 	if (proposal.kind === "revise_pending_wording") reviseWording(next, proposal, now);
-	if (proposal.kind === "split_subgoal" || proposal.kind === "mark_blocked_superseded") splitOrBlock(next, proposal, now);
+	if (proposal.kind === "split_subgoal" || proposal.kind === "mark_blocked_superseded") splitOrBlock(next, proposal, now, surface);
 	if (proposal.kind === "revise_criterion") reviseCriterion(next, proposal, now);
 	if (proposal.kind !== "annotate_ledger") next.updatedAt = now;
 	return next;
@@ -187,7 +189,7 @@ export function parseUlwLoopSteeringDirective(text: string): UlwLoopSteeringProp
 	}
 }
 
-export async function steerUlwLoop(repoRoot: string, proposal: UlwLoopSteeringProposal, scope?: UlwLoopScope): Promise<SteerUlwLoopResult> {
+export async function steerUlwLoop(repoRoot: string, proposal: UlwLoopSteeringProposal, scope?: UlwLoopScope, surface: UlwLoopToolkitSurface = "lazycodex"): Promise<SteerUlwLoopResult> {
 	return withUlwLoopMutationLock(repoRoot, scope, async () => {
 		const plan = await readUlwLoopPlan(repoRoot, scope);
 		const key = proposal.idempotencyKey ?? proposal.promptSignature;
@@ -200,7 +202,7 @@ export async function steerUlwLoop(repoRoot: string, proposal: UlwLoopSteeringPr
 		}
 		const audit = validateUlwLoopSteeringProposal(plan, proposal);
 		const accepted = audit.invariant.accepted;
-		const next = accepted ? applySteeringMutation(plan, proposal, audit) : plan;
+		const next = accepted ? applySteeringMutation(plan, proposal, audit, surface) : plan;
 		const finalAudit: UlwLoopSteeringAudit = { ...audit };
 		if (accepted) {
 			const changed = changedGoalIdsBetween(plan, next);
@@ -209,9 +211,9 @@ export async function steerUlwLoop(repoRoot: string, proposal: UlwLoopSteeringPr
 		}
 		const at = proposal.now?.toISOString() ?? iso();
 		const batchEntry = accepted ? batchUpdateLedgerEntry(plan, next, at) : null;
-		if (accepted) await writePlan(repoRoot, next, scope);
-		await appendLedger(repoRoot, ledgerEntry(proposal, finalAudit, at), scope);
-		if (batchEntry !== null) await appendLedger(repoRoot, batchEntry, scope);
+		const entries = [ledgerEntry(proposal, finalAudit, at)];
+		if (batchEntry !== null) entries.push(batchEntry);
+		await commit(repoRoot, scope, { plan: next, entries });
 		return { plan: next, accepted, audit: finalAudit, rejectedReasons: audit.invariant.rejectedReasons, deduped: false };
 	});
 }