lazycodex-ai 5.0.0-beta.9 → 5.0.0-beta.90

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

@@ -1,3 +1,4 @@
+import { type UlwLoopToolkitSurface } from "./surface.js";
 import type { UlwLoopItem, UlwLoopPlan } from "./types.js";
 export interface CodexCreateGoalPayload {
     readonly objective: string;
@@ -10,4 +11,5 @@ export declare function buildCodexGoalInstruction(args: {
     readonly plan: UlwLoopPlan;
     readonly goal: UlwLoopItem;
     readonly isFinal?: boolean;
+    readonly surface?: UlwLoopToolkitSurface;
 }): UlwLoopGoalInstruction;

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

@@ -1,15 +1,17 @@
 // biome-ignore-all format: long agent-facing instruction strings are intentionally stable.
 import { codexGoalMode, expectedCodexObjective, isEssentialCriterion, isFinalRunCompletionCandidate, } from "./goal-status.js";
+import { resolveToolkitSurface, reviewerRolesFor } from "./surface.js";
 export function buildCodexGoalInstruction(args) {
     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, goal) {
     return { objective: expectedCodexObjective(plan, goal) };
 }
-function buildText(mode, plan, goal, createGoal, isFinal) {
+function buildText(mode, plan, goal, createGoal, isFinal, surface) {
     return joinLines([
         mode === "aggregate" ? "UlwLoop aggregate-goal handoff" : "UlwLoop active-goal handoff",
         `Mode: ${mode}`,
@@ -26,7 +28,7 @@ function buildText(mode, plan, goal, createGoal, isFinal) {
         "- 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:",
@@ -80,19 +82,21 @@ function evidenceLayoutLines(plan) {
         "- Evidence layout v2: write every artifact for the active goal (QA matrix, review reports, receipts) under the current attempt directory — read currentAttemptDir from `omo-agent-toolkit ulw-loop status --json` (.omo/evidence/ulw/<session>/<goalId>/a<attempt>). The final checkpoint rejects quality-gate artifacts outside that directory.",
     ];
 }
-function finalSection(plan, goal, isFinal, aggregate) {
+function finalSection(plan, goal, isFinal, aggregate, surface) {
+    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:",
@@ -103,6 +107,22 @@ function finalSection(plan, goal, isFinal, aggregate) {
         `  ${checkpointCommand}`,
     ]);
 }
+function senpiFinalSection(plan, goal, aggregate) {
+    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) {
     const prefix = ".omo/ulw-loop/";
     const suffix = "/goals.json";

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

@@ -1,4 +1,4 @@
-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;
     objective?: string;
@@ -8,15 +8,18 @@ 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 declare class CodexGoalSnapshotError extends Error {
 }

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

@@ -7,16 +7,25 @@ function safeObject(value) {
     return value && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
 function safeString(value) {
+    return typeof value === "string" ? value : "";
+}
+function safeStatusString(value) {
     return typeof value === "string" ? value.trim() : "";
 }
 function normalizeStatus(value) {
-    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";
@@ -31,7 +40,7 @@ export function parseCodexGoalSnapshot(value) {
         return { available: false, raw: value };
     }
     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 {
         available: Boolean(objective || status !== "unknown"),
@@ -64,34 +73,37 @@ export function reconcileCodexGoalSnapshot(snapshot, options) {
     const effectiveSnapshot = snapshot ?? { available: false, raw: null };
     const errors = [];
     const warnings = [];
+    const nextActions = [];
+    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) => 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;
+    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 (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.');
+    if (actualStatus === "paused" || actualStatus === "usage_limited" || actualStatus === "budget_limited") {
+        nextActions.push("/goal resume or raise the budget");
     }
-    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) {
-    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/dist/constants.d.ts

@@ -2,6 +2,7 @@ export declare const ULW_LOOP_DIR = ".omo/ulw-loop";
 export declare const ULW_LOOP_BRIEF = "brief.md";
 export declare const ULW_LOOP_GOALS = "goals.json";
 export declare const ULW_LOOP_LEDGER = "ledger.jsonl";
+export declare const ULW_LOOP_STATE_LOCK = ".state.lock";
 export type UlwLoopStatus = "pending" | "in_progress" | "complete" | "failed" | "blocked" | "review_blocked" | "needs_user_decision";
 export type UlwLoopCodexGoalMode = "aggregate" | "per_story";
 export type UlwLoopSteeringStatus = "superseded" | "blocked";

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

@@ -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 const ULW_LOOP_STEERING_MUTATION_KINDS = [
     "add_subgoal",
     "split_subgoal",

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

@@ -10,6 +10,7 @@ export interface UlwLoopSuccessCriterion {
     status: UlwLoopCriterionStatus;
     capturedAt?: string;
     notes?: string;
+    artifacts?: string[];
 }
 export interface UlwLoopItem {
     id: string;
@@ -50,6 +51,9 @@ export interface UlwLoopValidationBatch {
 }
 export interface UlwLoopPlan {
     version: 1;
+    revision?: number;
+    brief?: string;
+    ledgerResetRevision?: number;
     evidenceLayoutVersion?: 2;
     createdAt: string;
     updatedAt: string;
@@ -59,6 +63,7 @@ export interface UlwLoopPlan {
     codexGoalMode?: UlwLoopCodexGoalMode;
     codexObjective?: string;
     codexObjectiveAliases?: string[];
+    acknowledgedDriverObjectives?: string[];
     aggregateCompletion?: UlwLoopAggregateCompletion;
     activeGoalId?: string;
     validationBatches?: readonly UlwLoopValidationBatch[];
@@ -89,15 +94,7 @@ export interface UlwLoopManualQaAdversarialCase {
     readonly reason?: string;
     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";
@@ -128,7 +125,24 @@ export interface UlwLoopQualityGate {
         readonly adversarialClassesCovered: readonly string[];
     };
 }
+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;
@@ -139,6 +153,7 @@ export interface UlwLoopLedgerEntry {
     codexGoal?: unknown;
     evidence?: string;
     capturedEvidence?: string;
+    artifacts?: string[];
     qualityGate?: unknown;
     steering?: UlwLoopSteeringAudit;
     before?: unknown;
@@ -149,3 +164,4 @@ export interface UlwLoopLedgerEntry {
     blockerOccurrenceCount?: number;
     requiredExternalDecision?: string;
 }
+export {};

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

@@ -0,0 +1,4 @@
+import type { UlwLoopPlan } from "./types.js";
+export declare function normalizeDriverObjective(value: string): string;
+export declare function acknowledgedDriverObjectives(plan: UlwLoopPlan): readonly string[];
+export declare function acknowledgeDriverObjective(plan: UlwLoopPlan, objective: string | undefined): boolean;

package/packages/omo-codex/plugin/components/ulw-loop/dist/driver-objective-ack.js

@@ -0,0 +1,18 @@
+export function normalizeDriverObjective(value) {
+    return value.replace(/\s+/g, " ").trim();
+}
+export function acknowledgedDriverObjectives(plan) {
+    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, objective) {
+    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/dist/evidence-artifacts.d.ts

@@ -0,0 +1 @@
+export declare function resolveEvidenceArtifacts(repoRoot: string, artifacts: readonly unknown[] | undefined): string[] | undefined;

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

@@ -0,0 +1,37 @@
+import { existsSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { UlwLoopError } from "./types.js";
+function fail(message, code, details) {
+    throw new UlwLoopError(message, code, { details });
+}
+function stored(repoRoot, absolute) {
+    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, artifacts) {
+    if (artifacts === undefined)
+        return undefined;
+    const seen = new Set();
+    const resolved = [];
+    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/dist/evidence.d.ts

@@ -7,6 +7,7 @@ type RecordEvidenceArgs = {
     readonly status: EvidenceStatus;
     readonly evidence: string;
     readonly notes?: string;
+    readonly artifacts?: readonly string[];
 };
 export declare function recordEvidence(repoRoot: string, args: RecordEvidenceArgs, scope?: UlwLoopScope): Promise<{
     plan: UlwLoopPlan;

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

@@ -1,5 +1,7 @@
+import { resolveEvidenceArtifacts } from "./evidence-artifacts.js";
 import { essentialCriteriaOf, hasAllCriteriaPass, hasEssentialCriteriaPass } from "./goal-status.js";
-import { appendLedger, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
+import { commit } from "./plan-commit.js";
+import { readUlwLoopPlan, withUlwLoopMutationLock } from "./plan-io.js";
 import { iso, UlwLoopError } from "./types.js";
 function ulwLoopFail(message, code, details) {
     throw new UlwLoopError(message, code, { details });
@@ -38,6 +40,7 @@ export async function recordEvidence(repoRoot, args, scope) {
         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();
@@ -46,9 +49,12 @@ export async function recordEvidence(repoRoot, args, scope) {
         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 = {
             at: capturedAt,
             kind,
@@ -57,10 +63,11 @@ export async function recordEvidence(repoRoot, args, scope) {
             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 };
     });
 }
@@ -80,18 +87,23 @@ export async function markCriteriaPendingResetForGoal(repoRoot, goalId, scope) {
             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/dist/ledger.d.ts

@@ -0,0 +1,4 @@
+import { type UlwLoopScope } from "./paths.js";
+import type { UlwLoopLedgerEntry } from "./types.js";
+export declare function readLedgerAt(dir: string): UlwLoopLedgerEntry[];
+export declare function readLedger(repoRoot: string, scope?: UlwLoopScope): UlwLoopLedgerEntry[];

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

@@ -0,0 +1,39 @@
+import { join } from "node:path";
+import { ulwLoopDir } from "./paths.js";
+import { readOptional, readRecords, reconcilePlan } from "./plan-log.js";
+export function readLedgerAt(dir) {
+    const entries = new Map();
+    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 = 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) => 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, scope) {
+    return readLedgerAt(ulwLoopDir(repoRoot, scope));
+}

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

@@ -12,7 +12,9 @@ export declare function ulwLoopLedgerRelativePath(scope?: UlwLoopScope): string;
 export declare function ulwLoopBriefPath(repoRoot: string, scope?: UlwLoopScope): string;
 export declare function ulwLoopGoalsPath(repoRoot: string, scope?: UlwLoopScope): string;
 export declare function ulwLoopLedgerPath(repoRoot: string, scope?: UlwLoopScope): string;
+export declare function ulwLoopStateLockPath(repoRoot: string, scope?: UlwLoopScope): string;
 export declare function repoRelative(absolutePath: string, repoRoot: string): string;
+export declare function ulwLoopEvidenceRoot(scope?: UlwLoopScope): string;
 export declare function ulwLoopAttemptEvidenceDir(goalId: string, attempt: number, scope?: UlwLoopScope): string;
 interface AttemptPathApi {
     relative(from: string, to: string): string;

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

@@ -1,6 +1,6 @@
 import { isAbsolute, join, relative, sep } from "node:path";
-import { ULW_LOOP_BRIEF, ULW_LOOP_DIR, ULW_LOOP_GOALS, ULW_LOOP_LEDGER } from "./types.js";
-const SESSION_ENV_KEYS = ["OMO_ULW_LOOP_SESSION_ID", "CODEX_SESSION_ID", "CODEX_THREAD_ID"];
+import { ULW_LOOP_BRIEF, ULW_LOOP_DIR, ULW_LOOP_GOALS, ULW_LOOP_LEDGER, ULW_LOOP_STATE_LOCK, UlwLoopError, } from "./types.js";
+const SESSION_ENV_KEYS = ["OMO_ULW_LOOP_SESSION_ID", "CODEX_SESSION_ID", "CODEX_THREAD_ID", "PI_SESSION_ID"];
 export function normalizeUlwLoopSessionId(sessionId) {
     const trimmed = sessionId?.trim();
     if (!trimmed)
@@ -48,6 +48,11 @@ export function ulwLoopGoalsPath(repoRoot, scope) {
 export function ulwLoopLedgerPath(repoRoot, scope) {
     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, scope) {
+    return join(ulwLoopDir(repoRoot, scope), ULW_LOOP_STATE_LOCK);
+}
 export function repoRelative(absolutePath, repoRoot) {
     const slashPrefix = `${repoRoot}/`;
     const backslashPrefix = `${repoRoot}\\`;
@@ -57,10 +62,20 @@ export function repoRelative(absolutePath, repoRoot) {
         return absolutePath.slice(backslashPrefix.length).split("\\").join("/");
     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) {
+    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, attempt, scope) {
-    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}`;
 }
 const PLATFORM_PATH_API = { relative, isAbsolute, sep };

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

@@ -0,0 +1,19 @@
+import { type UlwLoopScope } from "./paths.js";
+import { type UlwLoopLedgerEntry, type UlwLoopPlan } from "./types.js";
+interface CommitHooks {
+    readonly beforeMutation?: () => void | Promise<void>;
+    readonly beforeCommit?: () => void | Promise<void>;
+    readonly afterCommit?: () => void | Promise<void>;
+    readonly link?: (source: string, destination: string) => void;
+    readonly writeView?: (path: string, content: string) => Promise<void>;
+}
+export declare function withCommitHooks<T>(value: CommitHooks, fn: () => Promise<T>): Promise<T>;
+export declare function beforePlanMutation(): Promise<void>;
+export declare function writeViewFile(path: string, content: string): Promise<void>;
+export declare function commit(repoRoot: string, scope: UlwLoopScope | undefined, mutation: {
+    readonly plan: UlwLoopPlan;
+    readonly entries: readonly UlwLoopLedgerEntry[];
+}): Promise<void>;
+export declare function materializeSync(dir: string): void;
+export declare function materialize(dir: string): Promise<void>;
+export {};