lazycodex-ai 5.0.0-beta.9 → 5.0.0

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

@@ -1,17 +1,15 @@
 #!/usr/bin/env node
 import { isUlwLoopSubcommand, ulwLoopCommand } from "./cli-commands.js";
+import { ULW_LOOP_HELP } from "./cli-output.js";
 import { runPreToolUseGoalBudgetGuardCli, runUlwLoopHookCli } from "./codex-hook.js";
-import { runSpawnGuardCli } from "./spawn-guard.js";
+import { runSpawnAdmissionRecorderCli, runSpawnGuardCli } from "./spawn-guard.js";
 import { runStopResumeHookCli } from "./stop-resume-hook.js";
 
-const TOP_LEVEL_HELP =
-	"Usage:\n  omo-agent-toolkit ulw-loop <subcommand> [args]\n  omo-agent-toolkit hook user-prompt-submit [--with-ultrawork]  (Codex UserPromptSubmit hook)\n  omo-agent-toolkit help | --help | -h                          (this message)\n\nRun `omo-agent-toolkit ulw-loop help` for ulw-loop subcommands.\n";
-
 async function main(): Promise<number> {
 	const argv = process.argv.slice(2);
 	const command = argv[0];
 	if (command === undefined || command === "help" || command === "--help" || command === "-h") {
-		process.stdout.write(TOP_LEVEL_HELP);
+		process.stdout.write(`${ULW_LOOP_HELP}\n`);
 		return 0;
 	}
 	if (command === "ulw-loop") return ulwLoopCommand(argv.slice(1));
@@ -31,6 +29,10 @@ async function main(): Promise<number> {
 			await runStopResumeHookCli(process.stdin, process.stdout);
 			return 0;
 		}
+		if (sub === "post-tool-use-spawn") {
+			await runSpawnAdmissionRecorderCli(process.stdin, process.stdout);
+			return 0;
+		}
 		if (sub === "pre-tool-use-spawn") {
 			await runSpawnGuardCli(process.stdin, process.stdout);
 			return 0;
@@ -39,7 +41,7 @@ async function main(): Promise<number> {
 		return 1;
 	}
 	if (isUlwLoopSubcommand(command)) return ulwLoopCommand(argv);
-	process.stderr.write(`[omo] unknown command: ${command}\n${TOP_LEVEL_HELP}`);
+	process.stderr.write(`[omo] unknown command: ${command}\n${ULW_LOOP_HELP}\n`);
 	return 1;
 }
 

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

@@ -5,6 +5,7 @@ import {
 	isEssentialCriterion,
 	isFinalRunCompletionCandidate,
 } from "./goal-status.js";
+import { resolveToolkitSurface, reviewerRolesFor, type UlwLoopToolkitSurface } from "./surface.js";
 import type { UlwLoopCodexGoalMode, UlwLoopItem, UlwLoopPlan, UlwLoopSuccessCriterion } from "./types.js";
 
 export interface CodexCreateGoalPayload {
@@ -20,11 +21,13 @@ export function buildCodexGoalInstruction(args: {
 	readonly plan: UlwLoopPlan;
 	readonly goal: UlwLoopItem;
 	readonly isFinal?: boolean;
+	readonly surface?: UlwLoopToolkitSurface;
 }): UlwLoopGoalInstruction {
 	const mode = codexGoalMode(args.plan);
 	const createGoal = buildCreateGoalPayload(args.plan, args.goal);
 	const isFinal = args.isFinal ?? isFinalRunCompletionCandidate(args.plan, args.goal);
-	return { text: buildText(mode, args.plan, args.goal, createGoal, isFinal), json: createGoal };
+	const surface = args.surface ?? resolveToolkitSurface();
+	return { text: buildText(mode, args.plan, args.goal, createGoal, isFinal, surface), json: createGoal };
 }
 
 function buildCreateGoalPayload(plan: UlwLoopPlan, goal: UlwLoopItem): CodexCreateGoalPayload {
@@ -37,6 +40,7 @@ function buildText(
 	goal: UlwLoopItem,
 	createGoal: CodexCreateGoalPayload,
 	isFinal: boolean,
+	surface: UlwLoopToolkitSurface,
 ): string {
 	return joinLines([
 		mode === "aggregate" ? "UlwLoop aggregate-goal handoff" : "UlwLoop active-goal handoff",
@@ -54,7 +58,7 @@ function buildText(
 		"- Goals are unlimited. Do not add numeric limits.",
 		...modeConstraintLines(mode, isFinal),
 		...evidenceLayoutLines(plan),
-		finalSection(plan, goal, isFinal, mode === "aggregate"),
+		finalSection(plan, goal, isFinal, mode === "aggregate", surface),
 		...checkpointLines(plan, mode),
 		"",
 		"create_goal payload:",
@@ -112,19 +116,26 @@ function evidenceLayoutLines(plan: UlwLoopPlan): string[] {
 	];
 }
 
-function finalSection(plan: UlwLoopPlan, goal: UlwLoopItem, isFinal: boolean, aggregate: boolean): string {
+function finalSection(
+	plan: UlwLoopPlan,
+	goal: UlwLoopItem,
+	isFinal: boolean,
+	aggregate: boolean,
+	surface: UlwLoopToolkitSurface,
+): string {
+	const roles = reviewerRolesFor(surface);
 	if (!isFinal)
 		return "- This is not the final ulw-loop story; do not run the final reviewer/manual-QA/gate-review quality gate yet.";
 	const option = sessionOption(plan);
+	if (surface === "omo-senpi") return senpiFinalSection(plan, goal, aggregate);
 	const blockerCommand = `omo-agent-toolkit ulw-loop record-review-blockers${option} --goal-id ${goal.id} --title "Resolve final code-review blockers" --objective "<blocker-resolution objective>" --evidence "<review findings>" --codex-goal-json "<active get_goal JSON or path>"`;
 	const checkpointCommand = `omo-agent-toolkit ulw-loop checkpoint${option} --goal-id ${goal.id} --status complete --evidence "<targeted verification/manualQa/gateReview evidence>" --codex-goal-json "<fresh complete get_goal JSON or path>" --quality-gate-json "<quality gate JSON or path>"`;
 	return joinLines([
-		"Final story — run mandatory quality gate before update_goal:",
+		"Final story — self-review and manual QA are the default; use the quality gate before update_goal:",
 		"- Run targeted verification for changed behavior.",
 		"- Confirm every manualQa artifact path exists and has non-zero size.",
-		"- First spawn lazycodex-code-reviewer and lazycodex-qa-executor in parallel (fork_context: false on the v1 surface; fork_turns: \"none\" on v2). Include the original brief, goal objectives, desired user-visible outcome, diff, and evidence; wait for BOTH to return and confirm their report artifacts exist on disk (code-review report + manualQa matrix).",
-		"- Only then spawn lazycodex-gate-reviewer (same fork settings), passing those artifact paths.",
-		"- Require clean codeReview, manualQa, gateReview, iteration, and criteriaCoverage. criteriaCoverage must summarize originalIntent, desiredOutcome, and userOutcomeReview; counts alone are not approval.",
+		`- Run manual QA yourself and write its artifact under currentAttemptDir. Only if the user explicitly demands strict, rigorous, or high-accuracy review, spawn ${roles.gateReview}, optionally also ${roles.codeReview} and ${roles.manualQa}; otherwise set manualQa.by and gateReview.by to "main-session".`,
+		"- Require passed manualQa, approved gateReview, passed iteration, and complete criteriaCoverage; include codeReview only when strict review was requested. criteriaCoverage must summarize originalIntent, desiredOutcome, and userOutcomeReview; counts alone are not approval.",
 		"- On a reviewer REJECT, fix only the cited blockers, rerun the affected verification/Manual-QA, and re-review the delta at most TWICE; if blockers remain, record them and surface to the user.",
 		"- If codeQualityStatus is WATCH, include the WATCH notes verbatim in your final user-facing message.",
 		"- If any reviewer is blocked/inconclusive or the quality gate is not clean, do not call update_goal. Record blocker work first:",
@@ -136,6 +147,23 @@ function finalSection(plan: UlwLoopPlan, goal: UlwLoopItem, isFinal: boolean, ag
 	]);
 }
 
+function senpiFinalSection(plan: UlwLoopPlan, goal: UlwLoopItem, aggregate: boolean): string {
+	const option = sessionOption(plan);
+	const checkpointCommand = `omo-agent-toolkit ulw-loop checkpoint${option} --goal-id ${goal.id} --status complete --evidence "<manualQa/gateReview evidence>" --codex-goal-json "<fresh complete get_goal JSON or path>" --quality-gate-json "$(omo-agent-toolkit ulw-loop checkpoint${option} --print-template)"`;
+	return joinLines([
+		"Final story — run the single-reviewer quality gate before update_goal:",
+		"- Run manual QA yourself and write the non-empty artifact under currentAttemptDir; set manualQa.by to \"main-session\".",
+		'- Spawn exactly one gate reviewer with task(category: "deep-high").',
+		"- If that task fails with any model_unavailable failure, retry with category:deep-low, then category:unspecified-high, then category:unspecified-low.",
+		'- Set gateReview.by to the exact category:<name> literal used for the successful task.',
+		'- Build the gate JSON with omo-agent-toolkit ulw-loop checkpoint --print-template, then fill manualQa, gateReview, iteration, and criteriaCoverage.',
+		'- Require passed manualQa, approved gateReview, passed iteration, and complete criteriaCoverage before update_goal({status: "complete"}).',
+		aggregate
+			? `- If the gate is clean, call update_goal({status: "complete"}), call get_goal again, then checkpoint the aggregate story: ${checkpointCommand}`
+			: `- If the gate is clean, call update_goal({status: "complete"}), call get_goal again, then checkpoint: ${checkpointCommand}`,
+	]);
+}
+
 function sessionOption(plan: UlwLoopPlan): string {
 	const prefix = ".omo/ulw-loop/";
 	const suffix = "/goals.json";

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

@@ -2,7 +2,15 @@ import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 
-export type CodexGoalSnapshotStatus = "active" | "complete" | "cancelled" | "failed" | "unknown";
+export type CodexGoalSnapshotStatus =
+	| "active"
+	| "complete"
+	| "paused"
+	| "usage_limited"
+	| "budget_limited"
+	| "cancelled"
+	| "failed"
+	| "unknown";
 
 export interface CodexGoalSnapshot {
 	available: boolean;
@@ -14,16 +22,19 @@ export interface CodexGoalSnapshot {
 export interface CodexGoalReconciliation {
 	ok: boolean;
 	snapshot: CodexGoalSnapshot;
+	/** Facts to know (a differing driver objective); never something to do. */
 	warnings: string[];
+	/** Things to do next (create, re-create, or resume the driver goal). */
+	nextActions: string[];
 	errors: string[];
+	/** The differing objective this reconciliation reported for the first time, for the caller to acknowledge. */
+	unacknowledgedObjective?: string;
 }
 
 export interface ReconcileCodexGoalOptions {
 	expectedObjective: string;
-	acceptedObjectives?: readonly string[];
-	allowedStatuses?: readonly CodexGoalSnapshotStatus[];
-	requireSnapshot?: boolean;
-	requireComplete?: boolean;
+	readonly acceptedObjectives?: readonly string[];
+	readonly acknowledgedObjectives?: readonly string[];
 }
 
 export class CodexGoalSnapshotError extends Error {}
@@ -32,14 +43,21 @@ function safeObject(value: unknown): Record<string, unknown> {
 }
 
 function safeString(value: unknown): string {
+	return typeof value === "string" ? value : "";
+}
+
+function safeStatusString(value: unknown): string {
 	return typeof value === "string" ? value.trim() : "";
 }
 
 function normalizeStatus(value: unknown): CodexGoalSnapshotStatus {
-	const status = safeString(value).toLowerCase();
+	const status = safeStatusString(value).toLowerCase();
 	if (status === "complete" || status === "completed" || status === "done") return "complete";
 	if (status === "cancelled" || status === "canceled") return "cancelled";
 	if (status === "failed" || status === "failure") return "failed";
+	if (status === "paused") return "paused";
+	if (status === "usage_limited") return "usage_limited";
+	if (status === "budget_limited") return "budget_limited";
 	if (status === "active" || status === "in_progress" || status === "pending" || status === "running") return "active";
 	return "unknown";
 }
@@ -56,7 +74,9 @@ export function parseCodexGoalSnapshot(value: unknown): CodexGoalSnapshot {
 	}
 
 	const goal = safeObject(goalValue);
-	const objective = safeString(goal["objective"] ?? goal["goal"] ?? goal["description"] ?? root["objective"]);
+	const objective = safeString(
+		goal["objective"] ?? goal["goal"] ?? goal["description"] ?? goal["title"] ?? root["objective"] ?? root["title"],
+	);
 	const status = normalizeStatus(goal["status"] ?? root["status"]);
 
 	return {
@@ -97,43 +117,41 @@ export function reconcileCodexGoalSnapshot(
 	const effectiveSnapshot = snapshot ?? { available: false, raw: null };
 	const errors: string[] = [];
 	const warnings: string[] = [];
+	const nextActions: string[] = [];
 
+	const expected = options.expectedObjective;
 	if (!effectiveSnapshot.available) {
-		const message =
-			"Codex goal snapshot is absent or reports no active goal; call get_goal and pass its JSON with --codex-goal-json.";
-		if (options.requireSnapshot) errors.push(message);
-		else warnings.push(message);
-		return { ok: errors.length === 0, snapshot: effectiveSnapshot, warnings, errors };
+		nextActions.push(`call get_goal; if none, create_goal with codexObjective "${expected}" verbatim`);
+		return { ok: errors.length === 0, snapshot: effectiveSnapshot, warnings, nextActions, errors };
 	}
 
-	const expected = normalizeObjective(options.expectedObjective);
-	const accepted = new Set(
-		[expected, ...(options.acceptedObjectives ?? []).map((objective) => normalizeObjective(objective))].filter(
-			Boolean,
-		),
-	);
+	const normalized = (objectives: readonly string[]) => new Set(objectives.map(normalizeObjective).filter(Boolean));
+	const accepted = normalized([expected, ...(options.acceptedObjectives ?? [])]);
+	const acknowledged = normalized(options.acknowledgedObjectives ?? []);
 	const actual = normalizeObjective(effectiveSnapshot.objective ?? "");
-	if (!actual) {
-		errors.push("Codex goal snapshot is missing objective text.");
-	} else if (!accepted.has(actual)) {
-		errors.push(`Codex goal objective mismatch: expected "${expected}", got "${actual}".`);
+	let unacknowledgedObjective: string | undefined;
+	if (actual && !accepted.has(actual) && !acknowledged.has(actual)) {
+		warnings.push(`driver_objective_differs: expected "${expected}", got "${actual}".`);
+		unacknowledgedObjective = actual;
 	}
 
-	const allowed = options.allowedStatuses ?? (options.requireComplete ? ["complete"] : ["active", "complete"]);
 	const actualStatus = effectiveSnapshot.status ?? "unknown";
-	if (!allowed.includes(actualStatus)) {
-		errors.push(`Codex goal status mismatch: expected ${allowed.join(" or ")}, got ${actualStatus}.`);
+	if (actualStatus === "paused" || actualStatus === "usage_limited" || actualStatus === "budget_limited") {
+		nextActions.push("/goal resume or raise the budget");
 	}
-	if (options.requireComplete && actualStatus !== "complete") {
-		errors.push(
-			'Codex goal is not complete; call update_goal({status: "complete"}) only after the objective is actually complete, then pass the fresh get_goal JSON.',
-		);
-	}
-
-	return { ok: errors.length === 0, snapshot: effectiveSnapshot, warnings, errors };
+	if (actualStatus === "complete")
+		nextActions.push(`driver closed early: call create_goal with codexObjective "${expected}" verbatim`);
+	return {
+		ok: errors.length === 0,
+		snapshot: effectiveSnapshot,
+		warnings,
+		nextActions,
+		errors,
+		...(unacknowledgedObjective === undefined ? {} : { unacknowledgedObjective }),
+	};
 }
 
 export function formatCodexGoalReconciliation(reconciliation: CodexGoalReconciliation): string {
-	const parts = [...reconciliation.errors, ...reconciliation.warnings];
+	const parts = [...reconciliation.errors, ...reconciliation.nextActions, ...reconciliation.warnings];
 	return parts.join(" ");
 }

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

@@ -95,7 +95,9 @@ export async function applyUserPromptUlwLoopSteering(
 }
 
 function hasSteeringDirectiveMarker(prompt: string): boolean {
-	return /(?:^|\s)(?:OMO_ULW_LOOP_STEER|omo\.ulw-loop\.steer|omo ulw-loop steer|omo-agent-toolkit ulw-loop steer):/u.test(prompt);
+	return /(?:^|\s)(?:OMO_ULW_LOOP_STEER|omo\.ulw-loop\.steer|omo ulw-loop steer|omo-agent-toolkit ulw-loop steer):/u.test(
+		prompt,
+	);
 }
 
 function payloadScope(payload: UserPromptSubmitPayload): UlwLoopScope {

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

@@ -2,6 +2,7 @@ export const ULW_LOOP_DIR = ".omo/ulw-loop";
 export const ULW_LOOP_BRIEF = "brief.md";
 export const ULW_LOOP_GOALS = "goals.json";
 export const ULW_LOOP_LEDGER = "ledger.jsonl";
+export const ULW_LOOP_STATE_LOCK = ".state.lock";
 
 export type UlwLoopStatus =
 	| "pending"

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

@@ -19,6 +19,7 @@ export interface UlwLoopSuccessCriterion {
 	status: UlwLoopCriterionStatus;
 	capturedAt?: string;
 	notes?: string;
+	artifacts?: string[];
 }
 
 export interface UlwLoopItem {
@@ -63,6 +64,9 @@ export interface UlwLoopValidationBatch {
 
 export interface UlwLoopPlan {
 	version: 1;
+	revision?: number;
+	brief?: string;
+	ledgerResetRevision?: number;
 	evidenceLayoutVersion?: 2;
 	createdAt: string;
 	updatedAt: string;
@@ -72,6 +76,7 @@ export interface UlwLoopPlan {
 	codexGoalMode?: UlwLoopCodexGoalMode;
 	codexObjective?: string;
 	codexObjectiveAliases?: string[];
+	acknowledgedDriverObjectives?: string[];
 	aggregateCompletion?: UlwLoopAggregateCompletion;
 	activeGoalId?: string;
 	validationBatches?: readonly UlwLoopValidationBatch[];
@@ -107,15 +112,7 @@ export interface UlwLoopManualQaAdversarialCase {
 	readonly artifactRefs: readonly string[];
 }
 
-export interface UlwLoopQualityGate {
-	readonly codeReview: {
-		readonly by: string;
-		readonly recommendation: "APPROVE";
-		readonly codeQualityStatus: "CLEAR" | "WATCH";
-		readonly reportPath: string;
-		readonly evidence: string;
-		readonly blockers: readonly [];
-	};
+interface UlwLoopQualityGateCommon {
 	readonly manualQa: {
 		readonly by: string;
 		readonly status: "passed";
@@ -147,7 +144,27 @@ export interface UlwLoopQualityGate {
 	};
 }
 
+export interface UlwLoopQualityGateLazycodex extends UlwLoopQualityGateCommon {
+	readonly surface: "lazycodex";
+	readonly codeReview?: {
+		readonly by: string;
+		readonly recommendation: "APPROVE";
+		readonly codeQualityStatus: "CLEAR" | "WATCH";
+		readonly reportPath: string;
+		readonly evidence: string;
+		readonly blockers: readonly [];
+	};
+}
+
+export interface UlwLoopQualityGateSenpi extends UlwLoopQualityGateCommon {
+	readonly surface: "omo-senpi";
+}
+
+export type UlwLoopQualityGate = UlwLoopQualityGateLazycodex | UlwLoopQualityGateSenpi;
+
 export interface UlwLoopLedgerEntry {
+	revision?: number;
+	id?: string;
 	at: string;
 	kind: UlwLoopLedgerEventKind;
 	goalId?: string;
@@ -158,6 +175,7 @@ export interface UlwLoopLedgerEntry {
 	codexGoal?: unknown;
 	evidence?: string;
 	capturedEvidence?: string;
+	artifacts?: string[];
 	qualityGate?: unknown;
 	steering?: UlwLoopSteeringAudit;
 	before?: unknown;

package/packages/omo-codex/plugin/components/ulw-loop/src/driver-objective-ack.ts

@@ -0,0 +1,20 @@
+import type { UlwLoopPlan } from "./types.js";
+
+export function normalizeDriverObjective(value: string): string {
+	return value.replace(/\s+/g, " ").trim();
+}
+
+export function acknowledgedDriverObjectives(plan: UlwLoopPlan): readonly string[] {
+	return plan.acknowledgedDriverObjectives ?? [];
+}
+
+// A differing driver objective is reported once; the plan remembers the exact text so every later
+// checkpoint under the same driver stays quiet, while a driver rewritten to a third objective is
+// reported again.
+export function acknowledgeDriverObjective(plan: UlwLoopPlan, objective: string | undefined): boolean {
+	if (objective === undefined) return false;
+	const normalized = normalizeDriverObjective(objective);
+	if (!normalized || acknowledgedDriverObjectives(plan).includes(normalized)) return false;
+	plan.acknowledgedDriverObjectives = [...acknowledgedDriverObjectives(plan), normalized];
+	return true;
+}

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

@@ -0,0 +1,45 @@
+import { existsSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { UlwLoopError } from "./types.js";
+
+function fail(message: string, code: string, details: Record<string, unknown>): never {
+	throw new UlwLoopError(message, code, { details });
+}
+
+function stored(repoRoot: string, absolute: string): string {
+	const rel = relative(repoRoot, absolute);
+	const inside = rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+	return inside ? rel.split(sep).join("/") : absolute;
+}
+
+// Artifacts are bound at record time: a cited path that does not exist is a claim without a file,
+// so the whole record is refused before any state changes. Paths inside the session cwd persist
+// repo-relative (portable across machines); paths outside persist absolute.
+export function resolveEvidenceArtifacts(
+	repoRoot: string,
+	artifacts: readonly unknown[] | undefined,
+): string[] | undefined {
+	if (artifacts === undefined) return undefined;
+	const seen = new Set<string>();
+	const resolved: string[] = [];
+	for (const [index, candidate] of artifacts.entries()) {
+		const path = typeof candidate === "string" ? candidate.trim() : "";
+		if (!path) fail(`Artifact ${index + 1} must be a non-empty path.`, "ULW_LOOP_ARGUMENT_INVALID", { index });
+		const absolute = resolve(repoRoot, path);
+		if (!existsSync(absolute))
+			fail(
+				`Evidence artifact does not exist: ${path} (resolved to ${absolute}).`,
+				"ULW_LOOP_EVIDENCE_ARTIFACT_MISSING",
+				{
+					path,
+					resolved: absolute,
+				},
+			);
+		const value = stored(repoRoot, absolute);
+		if (!seen.has(value)) {
+			seen.add(value);
+			resolved.push(value);
+		}
+	}
+	return resolved;
+}

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

@@ -1,6 +1,8 @@
+import { resolveEvidenceArtifacts } from "./evidence-artifacts.js";
 import { essentialCriteriaOf, hasAllCriteriaPass, hasEssentialCriteriaPass } from "./goal-status.js";
 import type { UlwLoopScope } from "./paths.js";
-import { appendLedger, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
+import { commit } from "./plan-commit.js";
+import { readUlwLoopPlan, withUlwLoopMutationLock } from "./plan-io.js";
 import type { UlwLoopItem, UlwLoopLedgerEntry, UlwLoopPlan, UlwLoopSuccessCriterion } from "./types.js";
 import { iso, UlwLoopError } from "./types.js";
 
@@ -11,6 +13,7 @@ type RecordEvidenceArgs = {
 	readonly status: EvidenceStatus;
 	readonly evidence: string;
 	readonly notes?: string;
+	readonly artifacts?: readonly string[];
 };
 
 function ulwLoopFail(message: string, code: string, details: Record<string, unknown>): never {
@@ -66,6 +69,7 @@ export async function recordEvidence(
 		const goal = findGoal(plan, args.goalId);
 		const criterion = findCriterion(goal, args.criterionId);
 		const evidence = nonEmptyEvidence(args.evidence);
+		const artifacts = resolveEvidenceArtifacts(repoRoot, args.artifacts);
 		const kind = ledgerKind(args.status);
 		const prevStatus = criterion.status;
 		const capturedAt = iso();
@@ -73,9 +77,10 @@ export async function recordEvidence(
 		criterion.capturedEvidence = evidence;
 		criterion.capturedAt = capturedAt;
 		if (args.notes !== undefined) criterion.notes = args.notes;
+		if (artifacts !== undefined) criterion.artifacts = artifacts;
+		else delete criterion.artifacts;
 		goal.updatedAt = capturedAt;
 		plan.updatedAt = capturedAt;
-		await writePlan(repoRoot, plan, scope);
 		const ledgerEntry: UlwLoopLedgerEntry = {
 			at: capturedAt,
 			kind,
@@ -84,10 +89,11 @@ export async function recordEvidence(
 			criterionStatus: args.status,
 			evidence,
 			capturedEvidence: evidence,
+			...(artifacts === undefined ? {} : { artifacts }),
 			before: { status: prevStatus },
 			after: { goalId: goal.id, criterionId: criterion.id, status: args.status, evidence, capturedAt, prevStatus },
 		};
-		await appendLedger(repoRoot, ledgerEntry, scope);
+		await commit(repoRoot, scope, { plan, entries: [ledgerEntry] });
 		return { plan, goal, criterion, ledgerEntry };
 	});
 }
@@ -112,22 +118,23 @@ export async function markCriteriaPendingResetForGoal(
 			criterion.capturedEvidence = null;
 			delete criterion.capturedAt;
 			delete criterion.notes;
+			delete criterion.artifacts;
 		}
 		goal.updatedAt = now;
 		plan.updatedAt = now;
-		await writePlan(repoRoot, plan, scope);
-		await appendLedger(
-			repoRoot,
-			{
-				at: now,
-				kind: "criteria_revised",
-				goalId,
-				message: `Reset ${goal.successCriteria.length} criteria to pending.`,
-				before,
-				after: { resetCount: goal.successCriteria.length },
-			},
-			scope,
-		);
+		await commit(repoRoot, scope, {
+			plan,
+			entries: [
+				{
+					at: now,
+					kind: "criteria_revised",
+					goalId,
+					message: `Reset ${goal.successCriteria.length} criteria to pending.`,
+					before,
+					after: { resetCount: goal.successCriteria.length },
+				},
+			],
+		});
 		return { plan, resetCount: goal.successCriteria.length };
 	});
 }

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

@@ -0,0 +1,38 @@
+import { join } from "node:path";
+import { type UlwLoopScope, ulwLoopDir } from "./paths.js";
+import { readOptional, readRecords, reconcilePlan } from "./plan-log.js";
+import type { UlwLoopLedgerEntry } from "./types.js";
+
+export function readLedgerAt(dir: string): UlwLoopLedgerEntry[] {
+	const entries = new Map<string, UlwLoopLedgerEntry>();
+	const lines = (readOptional(join(dir, "ledger.jsonl")) ?? "").split(/\r?\n/);
+	// A materialized view is sorted by revision, so a line that carries no revision (or revision 0)
+	// AFTER a published revision was appended out-of-band (the removed tool path) and belongs to the
+	// newest revision before it - not to the pre-store past a later ledgerResetRevision would discard.
+	let reached = 0;
+	for (const [index, line] of lines.entries()) {
+		if (line.trim().length === 0) continue;
+		try {
+			const entry: UlwLoopLedgerEntry = JSON.parse(line);
+			entry.revision = entry.revision || reached;
+			reached = Math.max(reached, entry.revision);
+			entry.id ??= `legacy-${index + 1}`;
+			entries.set(entry.id, entry);
+		} catch (error) {
+			if (!(error instanceof SyntaxError)) throw error;
+		}
+	}
+	for (const record of readRecords(dir))
+		for (const [seq, entry] of record.ledger.entries()) {
+			const id = entry.id ?? `${record.revision}-${seq}`;
+			entries.set(id, { ...entry, revision: record.revision, id });
+		}
+	const reset = reconcilePlan(dir)?.ledgerResetRevision ?? 0;
+	const sequence = (entry: UlwLoopLedgerEntry) => Number(entry.id?.split("-").at(-1) ?? 0);
+	return [...entries.values()]
+		.filter((entry) => (entry.revision ?? 0) >= reset)
+		.sort((a, b) => (a.revision ?? 0) - (b.revision ?? 0) || sequence(a) - sequence(b));
+}
+export function readLedger(repoRoot: string, scope?: UlwLoopScope): UlwLoopLedgerEntry[] {
+	return readLedgerAt(ulwLoopDir(repoRoot, scope));
+}

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

@@ -1,11 +1,18 @@
 import { isAbsolute, join, relative, sep } from "node:path";
-import { ULW_LOOP_BRIEF, ULW_LOOP_DIR, ULW_LOOP_GOALS, ULW_LOOP_LEDGER } from "./types.js";
+import {
+	ULW_LOOP_BRIEF,
+	ULW_LOOP_DIR,
+	ULW_LOOP_GOALS,
+	ULW_LOOP_LEDGER,
+	ULW_LOOP_STATE_LOCK,
+	UlwLoopError,
+} from "./types.js";
 
 export interface UlwLoopScope {
 	readonly sessionId?: string | null;
 }
 
-const SESSION_ENV_KEYS = ["OMO_ULW_LOOP_SESSION_ID", "CODEX_SESSION_ID", "CODEX_THREAD_ID"] as const;
+const SESSION_ENV_KEYS = ["OMO_ULW_LOOP_SESSION_ID", "CODEX_SESSION_ID", "CODEX_THREAD_ID", "PI_SESSION_ID"] as const;
 type EnvMap = Readonly<Record<string, string | undefined>>;
 
 export function normalizeUlwLoopSessionId(sessionId: string | null | undefined): string | null {
@@ -63,6 +70,12 @@ export function ulwLoopLedgerPath(repoRoot: string, scope?: UlwLoopScope): strin
 	return join(ulwLoopDir(repoRoot, scope), ULW_LOOP_LEDGER);
 }
 
+// One lock per state directory covers goals.json, ledger.jsonl, and the hook
+// counters beside them; the CLI mutations and the Codex hooks all take it.
+export function ulwLoopStateLockPath(repoRoot: string, scope?: UlwLoopScope): string {
+	return join(ulwLoopDir(repoRoot, scope), ULW_LOOP_STATE_LOCK);
+}
+
 export function repoRelative(absolutePath: string, repoRoot: string): string {
 	const slashPrefix = `${repoRoot}/`;
 	const backslashPrefix = `${repoRoot}\\`;
@@ -72,10 +85,25 @@ export function repoRelative(absolutePath: string, repoRoot: string): string {
 	return absolutePath.split("\\").join("/");
 }
 
+// The plan-level evidence root stays fixed for the whole run, unlike the per-goal attempt dir, so
+// long lanes that span goals have one stable place to write artifacts.
+export function ulwLoopEvidenceRoot(scope?: UlwLoopScope): string {
+	const sessionId = normalizeUlwLoopSessionId(scope?.sessionId);
+	return sessionId === null ? ".omo/evidence" : `.omo/evidence/ulw/${sessionId}`;
+}
+
 // Both the status --json emitter and the checkpoint enforcement resolve the attempt dir through
-// this function; a second resolution path would let the gate reject its own advertised directory.
+// this function from the scope alone; a second resolution path (env, a literal placeholder)
+// would let the gate reject its own advertised directory.
 export function ulwLoopAttemptEvidenceDir(goalId: string, attempt: number, scope?: UlwLoopScope): string {
-	const sessionId = normalizeUlwLoopSessionId(scope?.sessionId) ?? resolveUlwLoopSessionIdFromEnv() ?? "session";
+	const sessionId = normalizeUlwLoopSessionId(scope?.sessionId);
+	if (sessionId === null) {
+		throw new UlwLoopError(
+			`Evidence for ${goalId} attempt ${attempt} needs a session scope; pass --session-id <id> so the attempt directory lives under .omo/evidence/ulw/<id>/.`,
+			"ULW_LOOP_SESSION_SCOPE_REQUIRED",
+			{ details: { goalId, attempt } },
+		);
+	}
 	return `.omo/evidence/ulw/${sessionId}/${goalId}/a${attempt}`;
 }