lazycodex-ai 5.0.0-beta.62 → 5.0.0-beta.64

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

@@ -1,12 +1,13 @@
 // biome-ignore-all format: compact steering module must stay below the 240 pure-LOC budget
 import { isUlwLoopDone } from "./goal-status.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 { iso, ULW_LOOP_STEERING_MUTATION_KINDS, ULW_LOOP_SUCCESS_CRITERION_USER_MODELS } from "./types.js";
 import { batchUpdateLedgerEntry } from "./validation-batch.js";
 const SOURCES = ["user_prompt_submit", "finding", "cli"];
-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) => typeof value === "object" && value !== null;
 const isPlain = (value) => isObject(value) && !Array.isArray(value);
 const read = (value, key) => Object.entries(value).find(([name]) => name === key)?.[1];
@@ -163,13 +164,13 @@ function validateCriterion(plan, proposal, reasons) {
     if (model !== undefined && !isModel(model))
         reasons.push("invalid userModel");
 }
-export function applySteeringMutation(plan, proposal, audit) {
+export function applySteeringMutation(plan, proposal, audit, surface = "lazycodex") {
     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));
+        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 !== undefined), ...next.goals.filter((item) => !order.includes(item.id))];
@@ -177,7 +178,7 @@ export function applySteeringMutation(plan, proposal, audit) {
     if (proposal.kind === "revise_pending_wording")
         reviseWording(next, proposal, now);
     if (proposal.kind === "split_subgoal" || proposal.kind === "mark_blocked_superseded")
-        splitOrBlock(next, proposal, now);
+        splitOrBlock(next, proposal, now, surface);
     if (proposal.kind === "revise_criterion")
         reviseCriterion(next, proposal, now);
     if (proposal.kind !== "annotate_ledger")
@@ -201,7 +202,7 @@ export function parseUlwLoopSteeringDirective(text) {
         throw error;
     }
 }
-export async function steerUlwLoop(repoRoot, proposal, scope) {
+export async function steerUlwLoop(repoRoot, proposal, scope, surface = "lazycodex") {
     return withUlwLoopMutationLock(repoRoot, scope, async () => {
         const plan = await readUlwLoopPlan(repoRoot, scope);
         const key = proposal.idempotencyKey ?? proposal.promptSignature;
@@ -214,7 +215,7 @@ export async function steerUlwLoop(repoRoot, proposal, scope) {
         }
         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 = { ...audit };
         if (accepted) {
             const changed = changedGoalIdsBetween(plan, next);
@@ -223,11 +224,10 @@ export async function steerUlwLoop(repoRoot, proposal, scope) {
         }
         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);
+        const entries = [ledgerEntry(proposal, finalAudit, at)];
         if (batchEntry !== null)
-            await appendLedger(repoRoot, batchEntry, scope);
+            entries.push(batchEntry);
+        await commit(repoRoot, scope, { plan: next, entries });
         return { plan: next, accepted, audit: finalAudit, rejectedReasons: audit.invariant.rejectedReasons, deduped: false };
     });
 }

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

@@ -1,6 +1,8 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, resolve, sep } from "node:path";
+import { readLedgerAt } from "./ledger.js";
 import { normalizeUlwLoopSessionId, ulwLoopDir, ulwLoopStateLockPath } from "./paths.js";
+import { readUlwLoopPlanSync } from "./plan-io.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
@@ -27,7 +29,7 @@ export function runStopResumeHook(input) {
         return "";
     const scope = { sessionId: payload.session_id };
     const stateDir = ulwLoopDir(payload.cwd, scope);
-    const plan = readPlan(join(stateDir, "goals.json"));
+    const plan = readPlan(payload.cwd, payload.session_id);
     if (plan === null || plan.aggregateCompletion?.status === "complete")
         return "";
     const goal = resumableGoal(plan);
@@ -76,11 +78,10 @@ function consumeResumeBudgetLocked(lockPath, stateDir, goalId) {
         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.
+// Hook budget counters are exempt from plan/audit commits. Count reconciled
+// entries, not cache lines: a writer dying after link still made progress.
 function consumeResumeBudget(stateDir, goalId) {
-    const ledgerLineCount = countLedgerLines(join(stateDir, "ledger.jsonl"));
+    const ledgerLineCount = readLedgerAt(stateDir).length;
     const counterPath = resolve(stateDir, `auto-resume-${goalId}.json`);
     const stuckPath = resolve(stateDir, `auto-resume-${goalId}.stuck`);
     // goals.json is untrusted input: a crafted goal id (e.g. `../../x`) must
@@ -111,9 +112,9 @@ function renderResumeDirective(plan, goal, sessionId) {
         "If the loop is genuinely blocked on the user, checkpoint the goal as blocked with the reason instead.",
     ].join("\n");
 }
-function readPlan(goalsPath) {
+function readPlan(repoRoot, sessionId) {
     try {
-        return JSON.parse(readFileSync(goalsPath, "utf8"));
+        return readUlwLoopPlanSync(repoRoot, { sessionId });
     }
     catch (error) {
         if (error instanceof Error)
@@ -121,16 +122,6 @@ function readPlan(goalsPath) {
         throw error;
     }
 }
-function countLedgerLines(ledgerPath) {
-    try {
-        return readFileSync(ledgerPath, "utf8").split("\n").filter(Boolean).length;
-    }
-    catch (error) {
-        if (error instanceof Error)
-            return 0;
-        throw error;
-    }
-}
 function readCounter(counterPath) {
     try {
         if (!existsSync(counterPath))

package/packages/omo-codex/plugin/components/ulw-loop/dist/success-criteria-input.d.ts

@@ -0,0 +1,9 @@
+import type { UlwLoopSuccessCriterion, UlwLoopSuccessCriterionUserModel } from "./types.js";
+export interface SuccessCriterionInput {
+    readonly scenario: string;
+    readonly expectedEvidence: string;
+    readonly userModel?: UlwLoopSuccessCriterionUserModel;
+    readonly essential?: boolean;
+}
+export declare function criterionId(index: number): string;
+export declare function criteriaFromInput(input: readonly unknown[]): UlwLoopSuccessCriterion[];

package/packages/omo-codex/plugin/components/ulw-loop/dist/success-criteria-input.js

@@ -0,0 +1,41 @@
+import { ULW_LOOP_SUCCESS_CRITERION_USER_MODELS, UlwLoopError } from "./types.js";
+function invalid(message, details) {
+    throw new UlwLoopError(`Invalid successCriteria: ${message}`, "ULW_LOOP_ARGUMENT_INVALID", { details });
+}
+function isUserModel(value) {
+    return typeof value === "string" && ULW_LOOP_SUCCESS_CRITERION_USER_MODELS.some((model) => model === value);
+}
+function requireText(value, field, index) {
+    const trimmed = typeof value === "string" ? value.trim() : "";
+    return trimmed || invalid(`entry ${index + 1} needs a non-empty ${field}.`, { index, field });
+}
+export function criterionId(index) {
+    return `C${String(index + 1).padStart(3, "0")}`;
+}
+export function criteriaFromInput(input) {
+    if (input.length === 0)
+        invalid("provide at least one criterion or omit the field for placeholders.", { count: 0 });
+    return input.map((entry, index) => {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry))
+            return invalid(`entry ${index + 1} must be an object.`, { index });
+        const record = { ...entry };
+        const userModel = record["userModel"] ?? "happy";
+        if (!isUserModel(userModel))
+            return invalid(`entry ${index + 1} userModel must be one of ${ULW_LOOP_SUCCESS_CRITERION_USER_MODELS.join(", ")}.`, {
+                index,
+                userModel: String(userModel),
+            });
+        const essential = record["essential"];
+        if (essential !== undefined && typeof essential !== "boolean")
+            return invalid(`entry ${index + 1} essential must be a boolean.`, { index });
+        return {
+            id: criterionId(index),
+            scenario: requireText(record["scenario"], "scenario", index),
+            userModel,
+            expectedEvidence: requireText(record["expectedEvidence"], "expectedEvidence", index),
+            essential: essential ?? true,
+            capturedEvidence: null,
+            status: "pending",
+        };
+    });
+}

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

@@ -7,7 +7,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook user-prompt-submit --with-ultrawork",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.0.0-beta.62) Checking Ulw-Loop Steering"
+						"statusMessage": "(OmO 5.0.0-beta.64) Checking Ulw-Loop Steering"
 					}
 				]
 			}
@@ -20,7 +20,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook post-tool-use-spawn",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.62) Recording Spawn Admission"
+						"statusMessage": "(OmO 5.0.0-beta.64) Recording Spawn Admission"
 					}
 				]
 			}
@@ -33,7 +33,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook pre-tool-use",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.62) Enforcing Unlimited Ulw-Loop Budget"
+						"statusMessage": "(OmO 5.0.0-beta.64) Enforcing Unlimited Ulw-Loop Budget"
 					}
 				]
 			},
@@ -44,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.62) Guarding Ulw-Loop Spawns"
+						"statusMessage": "(OmO 5.0.0-beta.64) Guarding Ulw-Loop Spawns"
 					}
 				]
 			}
@@ -56,7 +56,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook stop",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.0.0-beta.62) Checking Ulw-Loop Resume"
+						"statusMessage": "(OmO 5.0.0-beta.64) 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.62",
+	"version": "5.0.0-beta.64",
 	"description": "Codex plugin: durable repo-native multi-goal orchestration with embedded success criteria and observable evidence audit.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",

package/packages/omo-codex/plugin/components/ulw-loop/skills/ulw-loop/references/full-workflow.md

@@ -20,7 +20,7 @@ Run each criterion's real-surface proof yourself through the channel that faithf
 
 1. **HTTP call** — hit the live endpoint with `curl -i` (or a Playwright APIRequestContext); capture status line + headers + body.
 2. **Terminal / TUI** - prove it through the xterm.js web terminal; tmux `send-keys` is fine for a boot smoke, but NEVER `tmux capture-pane` for color/layout/CJK evidence (it degrades truecolor).
-3. **Browser use** — in Codex, use `browser:control-in-app-browser` first when available and the scenario does not need an authenticated or persistent user browser profile. Otherwise use Chrome to drive the REAL page; if unavailable, use agent-browser. Capture action log + screenshot path. Never downgrade a browser-facing criterion.
+3. **Browser use** — in Codex, prefer `browser:control-in-app-browser`. Otherwise, or for Chrome semantics, stealth, trace, or auth, WRITE a `playwright-core` script and run it from js eval against local Chrome (`channel: "chrome"`; persistent context on a CLONED profile, never the live one). Capture action log + screenshot path. Never downgrade a browser-facing criterion.
 4. **Computer use** — for desktop/GUI apps, drive the running app via OS automation (computer-use, AppleScript, xdotool, etc.); capture action log + screenshot.
 
 For TUI visual QA (mandatory when a PR or review must inspect the terminal screen),
@@ -165,7 +165,7 @@ Loop per goal. Cap at 5 cycles per goal. Cap identical same-criterion failures a
 4. INTEGRATE + CRITICAL SELF-QA + GIT CHECKPOINT (EVERY WORKER RETURN): do NOT trust the worker's report. Read the diff yourself, re-run its tests, and run LSP diagnostics on the changed files. Treat "done" as a claim to disprove. If the diff drifts, the test is hollow, or evidence is missing, RESPAWN the worker with the specific failure context. Once the work unit is verified, use `git-master` before staging: inspect recent repository commits and touched-path history to infer commit language, Conventional Commit scope, message shape, and unit size. Stage only that unit's files and commit in the observed style; do not carry verified work forward into a later omnibus commit. If no git-tracked files changed or committing is unsafe, record the no-commit reason as evidence. Forward every finding/learning to subsequent workers.
 5. EXECUTE-AS-SCENARIO: ACTUALLY run the Manual-QA scenario the criterion named (channel table above). Run it yourself for the orchestrator check; for heavier flows dispatch a dedicated QA execution worker (`lazycodex-worker-medium` by default; `lazycodex-worker-high` when the QA flow itself is hard) whose ONLY job is to drive the channel and write the artifact to the named evidence path. If the scenario FAILS, respawn the implementing worker with the captured failure — do not hand-patch around it.
 6. CAPTURE: collect the observable artifact path: transcript, stdout, screenshot, assertion, status+body, diff, or parsed dump. No artifact written at the evidence path — not done; record BLOCKED and respawn QA.
-7. CLEAN (PAIRED, NEVER SKIP): tear down every runtime artifact step 5 spawned BEFORE recording — server PIDs (`kill`, verify `kill -0` fails), `tmux` sessions (`tmux kill-session -t ulw-qa-<criterion>`; confirm `tmux ls`), browser / Playwright contexts (`.close()`), containers (`docker rm -f`), bound ports (`lsof -i :<port>` empty), temp sockets / files / dirs (`rm -rf` the `mktemp` paths), QA-only env vars, AND close every finished worker (v1 `close_agent`; on V2 finished workers end on their own — `interrupt_agent` any still running). Register each teardown as its own todo the moment the QA spawns the resource (scripts, tmux assets, browsers / agent-browser sessions, PIDs, ports) so none is forgotten. Embed a one-line cleanup receipt in the evidence string, e.g. `cleanup: killed 12345; tmux kill-session ulw-qa-foo; rm -rf /tmp/ulw.aB12cD; interrupt_agent w-3`. Missing receipt → record BLOCKED, not PASS.
+7. CLEAN (PAIRED, NEVER SKIP): tear down every runtime artifact step 5 spawned BEFORE recording — server PIDs (`kill`, verify `kill -0` fails), `tmux` sessions (`tmux kill-session -t ulw-qa-<criterion>`; confirm `tmux ls`), browser / Playwright contexts (`.close()`), containers (`docker rm -f`), bound ports (`lsof -i :<port>` empty), temp sockets / files / dirs (`rm -rf` the `mktemp` paths), QA-only env vars, AND close every finished worker (v1 `close_agent`; on V2 finished workers end on their own — `interrupt_agent` any still running). Register each teardown as its own todo the moment the QA spawns the resource (scripts, tmux assets, browser contexts, PIDs, ports) so none is forgotten. Embed a one-line cleanup receipt in the evidence string, e.g. `cleanup: killed 12345; tmux kill-session ulw-qa-foo; rm -rf /tmp/ulw.aB12cD; interrupt_agent w-3`. Missing receipt → record BLOCKED, not PASS.
 8. RECORD one result immediately from the artifact you just wrote — never from memory or a later turn — stamping the capture tree `$(git rev-parse --short "HEAD^{tree}")` into the evidence:
    - PASS: `omo-agent-toolkit ulw-loop record-evidence --goal-id <id> --criterion-id <id> --status pass --evidence "<observable> @tree:<short-tree> | <cleanup receipt>" --json`
    - FAIL: `omo-agent-toolkit ulw-loop record-evidence --goal-id <id> --criterion-id <id> --status fail --evidence "<observable> @tree:<short-tree> | <cleanup receipt>" --notes "<diagnosis>" --json`

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

@@ -4,11 +4,19 @@ import {
 	readCodexGoalSnapshotInput,
 	reconcileCodexGoalSnapshot,
 } from "./codex-goal-snapshot.js";
+import { acknowledgedDriverObjectives } from "./driver-objective-ack.js";
 import { codexGoalMode, compatibleCodexObjectives, expectedCodexObjective } from "./goal-status.js";
 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 async function validateCheckpointCodexGoal(input: {
 	readonly repoRoot: string;
 	readonly plan: UlwLoopPlan;
@@ -16,11 +24,12 @@ export async function validateCheckpointCodexGoal(input: {
 	readonly raw: string | undefined;
 	readonly evidence: string;
 	readonly scope?: UlwLoopScope;
-}): Promise<{ readonly raw: unknown; readonly nextActions: readonly string[]; readonly warnings: readonly string[] }> {
+}): Promise<CheckpointCodexGoalValidation> {
 	const snapshot = await readCodexGoalSnapshotInput(input.raw, input.repoRoot);
 	const expected = expectedCodexObjective(input.plan, input.goal);
 	const reconciliation = reconcileCodexGoalSnapshot(snapshot, {
 		expectedObjective: expected,
+		acknowledgedObjectives: acknowledgedDriverObjectives(input.plan),
 		...(codexGoalMode(input.plan) === "aggregate"
 			? { acceptedObjectives: compatibleCodexObjectives(input.plan) }
 			: {}),
@@ -28,8 +37,11 @@ export async function validateCheckpointCodexGoal(input: {
 	if (!reconciliation.ok) throw new CodexGoalSnapshotError(formatCodexGoalReconciliation(reconciliation));
 	return {
 		raw: snapshot?.raw,
-		nextActions: reconciliation.warnings,
-		warnings: reconciliation.warnings.filter((warning) => warning.startsWith("driver_objective_differs")),
+		nextActions: reconciliation.nextActions,
+		warnings: reconciliation.warnings,
+		...(reconciliation.unacknowledgedObjective === undefined
+			? {}
+			: { unacknowledgedObjective: reconciliation.unacknowledgedObjective }),
 	};
 }
 

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

@@ -6,11 +6,13 @@ import {
 	combineCheckpointValidationErrors,
 	validateCheckpointCodexGoal,
 } from "./checkpoint-codex-validation.js";
+import { acknowledgeDriverObjective } from "./driver-objective-ack.js";
 import { requireAllCriteriaPass, requireAllPlanCriteriaPass, requireEssentialCriteriaPass } from "./evidence.js";
 import { codexGoalMode, isFinalRunCompletionCandidate } from "./goal-status.js";
 import type { UlwLoopScope } from "./paths.js";
 import { ulwLoopAttemptEvidenceDir } 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 {
 	classifyExternalAuthorizationBlocker,
 	clearGoalBlockerFields,
@@ -189,6 +191,7 @@ export async function checkpointUlwLoop(
 				codexGoal = validation.raw;
 				nextActions = validation.nextActions;
 				warnings = validation.warnings;
+				acknowledgeDriverObjective(plan, validation.unacknowledgedObjective);
 			} catch (error) {
 				if (!(error instanceof UlwLoopError)) throw error;
 				codexValidationError = error;
@@ -226,11 +229,11 @@ export async function checkpointUlwLoop(
 		if (aggregateCompletion !== undefined) plan.aggregateCompletion = aggregateCompletion;
 		if (aggregateCompletion !== undefined) nextActions = [...nextActions, 'aggregate complete — now update_goal({status:"complete"})'];
 		plan.updatedAt = now;
-		await writePlan(repoRoot, plan, scope);
 		const ledgerEntry = buildLedger(now, args, goal, qualityGate, codexGoal, aggregateCompletion);
-		await appendLedger(repoRoot, ledgerEntry, scope);
+		const entries = [ledgerEntry];
 		const closedBatch = args.status === "complete" ? batchClosedBy(plan, goal.id) : undefined;
-		if (closedBatch !== undefined) await appendLedger(repoRoot, { at: now, kind: "batch_closed", goalId: goal.id, message: closedBatch.batchId }, scope);
+		if (closedBatch !== undefined) entries.push({ at: now, kind: "batch_closed", goalId: goal.id, message: closedBatch.batchId });
+		await commit(repoRoot, scope, { plan, entries });
 		return aggregateCompletion === undefined
 			? { plan, goal, ledgerEntry, nextActions, warnings }
 			: { plan, goal, ledgerEntry, aggregateCompletion, nextActions, warnings };

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

@@ -22,13 +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;
 	readonly acceptedObjectives?: readonly string[];
+	readonly acknowledgedObjectives?: readonly string[];
 }
 
 export class CodexGoalSnapshotError extends Error {}
@@ -111,35 +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;
-	const normalizedExpected = normalizeObjective(expected);
 	if (!effectiveSnapshot.available) {
-		warnings.push(`call get_goal; if none, create_goal with codexObjective "${expected}" verbatim`);
-		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 accepted = new Set(
-		[
-			normalizedExpected,
-			...(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 && !accepted.has(normalizeObjective(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 actualStatus = effectiveSnapshot.status ?? "unknown";
 	if (actualStatus === "paused" || actualStatus === "usage_limited" || actualStatus === "budget_limited") {
-		warnings.push("/goal resume or raise the budget");
+		nextActions.push("/goal resume or raise the budget");
 	}
 	if (actualStatus === "complete")
-		warnings.push(`driver closed early: call create_goal with codexObjective "${expected}" verbatim`);
-	return { ok: errors.length === 0, snapshot: effectiveSnapshot, warnings, errors };
+		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/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[];
@@ -158,6 +163,8 @@ export interface UlwLoopQualityGateSenpi extends UlwLoopQualityGateCommon {
 export type UlwLoopQualityGate = UlwLoopQualityGateLazycodex | UlwLoopQualityGateSenpi;
 
 export interface UlwLoopLedgerEntry {
+	revision?: number;
+	id?: string;
 	at: string;
 	kind: UlwLoopLedgerEventKind;
 	goalId?: string;
@@ -168,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 };
 	});
 }