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

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

@@ -8,12 +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;
     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

@@ -73,29 +73,37 @@ export function reconcileCodexGoalSnapshot(snapshot, options) {
     const effectiveSnapshot = snapshot ?? { available: false, raw: null };
     const errors = [];
     const warnings = [];
+    const nextActions = [];
     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) => 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;
+    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) {
-    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/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[];
@@ -136,6 +141,8 @@ export interface UlwLoopQualityGateSenpi extends UlwLoopQualityGateCommon {
 }
 export type UlwLoopQualityGate = UlwLoopQualityGateLazycodex | UlwLoopQualityGateSenpi;
 export interface UlwLoopLedgerEntry {
+    revision?: number;
+    id?: string;
     at: string;
     kind: UlwLoopLedgerEventKind;
     goalId?: string;
@@ -146,6 +153,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/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,34 @@
+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/);
+    for (const [index, line] of lines.entries()) {
+        if (line.trim().length === 0)
+            continue;
+        try {
+            const entry = JSON.parse(line);
+            entry.revision ??= 0;
+            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

@@ -14,6 +14,7 @@ export declare function ulwLoopGoalsPath(repoRoot: string, scope?: UlwLoopScope)
 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

@@ -62,6 +62,12 @@ 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 from the scope alone; a second resolution path (env, a literal placeholder)
 // would let the gate reject its own advertised directory.

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 {};

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

@@ -0,0 +1,107 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import { linkSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { readLedgerAt } from "./ledger.js";
+import { ulwLoopDir, ulwLoopStateLockPath } from "./paths.js";
+import { assertStateLockOwned, migrationEntries } from "./plan-io.js";
+import { hasCode, readOptional, readRecords, reconcilePlan } from "./plan-log.js";
+import { UlwLoopError } from "./types.js";
+const hooks = new AsyncLocalStorage();
+export function withCommitHooks(value, fn) {
+    return hooks.run(value, fn);
+}
+export async function beforePlanMutation() {
+    await hooks.getStore()?.beforeMutation?.();
+}
+export async function writeViewFile(path, content) {
+    await (hooks.getStore()?.writeView ?? writeFile)(path, content);
+}
+// link is the sole commit point; no copy fallback (Node copyFile is not atomic).
+// A resumed zombie can publish first, but never overwrite an existing revision.
+// Logical audit order is (revision, sequence), not materialization completion time.
+export async function commit(repoRoot, scope, mutation) {
+    const { plan } = mutation;
+    const dir = ulwLoopDir(repoRoot, scope);
+    assertStateLockOwned(ulwLoopStateLockPath(repoRoot, scope));
+    await hooks.getStore()?.beforeCommit?.();
+    const next = (plan.revision ?? 0) + 1;
+    const brief = plan.brief ?? readOptional(join(dir, "brief.md")) ?? "";
+    const entries = [...migrationEntries(plan), ...mutation.entries].map((entry, seq) => ({
+        ...entry,
+        revision: next,
+        id: `${next}-${seq}`,
+    }));
+    const record = {
+        version: 1,
+        revision: next,
+        plan: { ...plan, revision: next, brief },
+        ledger: entries,
+    };
+    mkdirSync(join(dir, "revisions"), { recursive: true });
+    mkdirSync(join(dir, "tmp"), { recursive: true });
+    const temp = join(dir, "tmp", `${process.pid}-${randomUUID()}.json`);
+    try {
+        writeFileSync(temp, `${JSON.stringify(record)}\n`, { flag: "wx" });
+        try {
+            (hooks.getStore()?.link ?? linkSync)(temp, join(dir, "revisions", `${String(next).padStart(8, "0")}.json`));
+        }
+        catch (error) {
+            if (hasCode(error, "EEXIST"))
+                throw new UlwLoopError("Another writer published the read revision.", "ULW_LOOP_PUBLISH_CONFLICT", {
+                    cause: error,
+                });
+            if (["EPERM", "ENOTSUP", "EXDEV"].some((code) => hasCode(error, code)))
+                throw new UlwLoopError("Immutable ulw-loop publication requires atomic hard links.", "ULW_LOOP_PUBLISH_UNSUPPORTED_FS", { cause: error });
+            throw error;
+        }
+    }
+    finally {
+        rmSync(temp, { force: true });
+    }
+    plan.revision = next;
+    plan.brief = brief;
+    for (const [index, entry] of mutation.entries.entries())
+        Object.assign(entry, entries[index + entries.length - mutation.entries.length]);
+    await hooks.getStore()?.afterCommit?.();
+    await materialize(dir);
+}
+function viewContents(dir) {
+    const plan = reconcilePlan(dir);
+    if (plan === undefined || readRecords(dir).length === 0)
+        return [];
+    const ledger = readLedgerAt(dir);
+    const views = [
+        ["goals.json", `${JSON.stringify(plan, null, 2)}\n`],
+        ["ledger.jsonl", ledger.length === 0 ? "" : `${ledger.map((entry) => JSON.stringify(entry)).join("\n")}\n`],
+        ["brief.md", plan.brief ?? readOptional(join(dir, "brief.md")) ?? ""],
+    ];
+    return views.filter(([name, content]) => readOptional(join(dir, name)) !== content);
+}
+export function materializeSync(dir) {
+    for (const [name, content] of viewContents(dir)) {
+        mkdirSync(join(dir, "tmp"), { recursive: true });
+        const temp = join(dir, "tmp", `${process.pid}-${randomUUID()}-${name}`);
+        try {
+            writeFileSync(temp, content, { flag: "wx" });
+            renameSync(temp, join(dir, name));
+        }
+        finally {
+            rmSync(temp, { force: true });
+        }
+    }
+}
+export async function materialize(dir) {
+    for (const [name, content] of viewContents(dir)) {
+        mkdirSync(join(dir, "tmp"), { recursive: true });
+        const temp = join(dir, "tmp", `${process.pid}-${randomUUID()}-${name}`);
+        try {
+            await writeViewFile(temp, content);
+            await rename(temp, join(dir, name));
+        }
+        finally {
+            rmSync(temp, { force: true });
+        }
+    }
+}

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

@@ -1,6 +1,9 @@
 import { type UlwLoopScope } from "./paths.js";
+import type { SuccessCriterionInput } from "./success-criteria-input.js";
+import type { UlwLoopToolkitSurface } from "./surface.js";
 import type { UlwLoopCodexGoalMode, UlwLoopItem, UlwLoopPlan } from "./types.js";
 export { deriveGoalCandidates, seedDefaultSuccessCriteria } from "./plan-goal-factory.js";
+export type { SuccessCriterionInput } from "./success-criteria-input.js";
 export type UlwLoopPlanSummary = {
     readonly total: number;
     readonly pending: number;
@@ -24,11 +27,12 @@ export declare function createUlwLoopPlan(repoRoot: string, args: {
     codexGoalMode?: UlwLoopCodexGoalMode;
     force?: boolean;
     validationBatchesJson?: string;
-}, scope?: UlwLoopScope): Promise<UlwLoopPlan>;
+}, scope?: UlwLoopScope, surface?: UlwLoopToolkitSurface): Promise<UlwLoopPlan>;
 export declare function addUlwLoopGoal(repoRoot: string, args: {
     title: string;
     objective: string;
-}, scope?: UlwLoopScope): Promise<{
+    successCriteria?: readonly SuccessCriterionInput[];
+}, scope?: UlwLoopScope, surface?: UlwLoopToolkitSurface): Promise<{
     plan: UlwLoopPlan;
     goal: UlwLoopItem;
 }>;

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

@@ -1,9 +1,8 @@
-import { existsSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
 import { aggregateCodexObjectiveForScope, isUlwLoopDone } from "./goal-status.js";
-import { ulwLoopBriefPath, ulwLoopBriefRelativePath, ulwLoopDir, ulwLoopGoalsPath, ulwLoopGoalsRelativePath, ulwLoopLedgerPath, ulwLoopLedgerRelativePath, } from "./paths.js";
+import { ulwLoopBriefRelativePath, ulwLoopGoalsRelativePath, ulwLoopLedgerRelativePath, } from "./paths.js";
+import { beforePlanMutation, commit } from "./plan-commit.js";
 import { appendGoalToPlan, deriveGoalCandidates, makeGoal } from "./plan-goal-factory.js";
-import { appendLedger, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
+import { planExists, readUlwLoopPlan, withUlwLoopMutationLock } from "./plan-io.js";
 import { iso, UlwLoopError } from "./types.js";
 import { parseValidationBatches } from "./validation-batch.js";
 export { deriveGoalCandidates, seedDefaultSuccessCriteria } from "./plan-goal-factory.js";
@@ -22,18 +21,30 @@ function clearGoalBlockerFields(goal) {
     ])
         delete goal[key];
 }
-export async function createUlwLoopPlan(repoRoot, args, scope) {
+export async function createUlwLoopPlan(repoRoot, args, scope, surface = "lazycodex") {
     return withUlwLoopMutationLock(repoRoot, scope, async () => {
-        if (!args.force && existsSync(ulwLoopGoalsPath(repoRoot, scope))) {
-            const existing = await readUlwLoopPlan(repoRoot, scope);
+        let existing;
+        if (planExists(repoRoot, scope)) {
+            try {
+                existing = await readUlwLoopPlan(repoRoot, scope);
+            }
+            catch (error) {
+                if (!args.force)
+                    throw error;
+            }
+        }
+        if (!args.force && existing !== undefined) {
             if (isUlwLoopDone(existing))
-                throw completedPlanExistsError(scope);
+                throw completedPlanExistsError(scope, surface);
             throw new UlwLoopError(`Refusing to overwrite existing ${ulwLoopGoalsRelativePath(scope)}; pass --force to recreate it.`, "ULW_LOOP_PLAN_EXISTS");
         }
         const now = iso();
-        const goals = deriveGoalCandidates(args.brief).map((goal, index) => makeGoal(goal.title, goal.objective, index, now));
+        const goals = deriveGoalCandidates(args.brief).map((goal, index) => makeGoal(goal.title, goal.objective, index, now, { surface }));
         const plan = {
             version: 1,
+            revision: existing?.revision ?? 0,
+            ledgerResetRevision: (existing?.revision ?? 0) + 1,
+            brief: args.brief.endsWith("\n") ? args.brief : `${args.brief}\n`,
             evidenceLayoutVersion: 2,
             createdAt: now,
             updatedAt: now,
@@ -48,28 +59,39 @@ export async function createUlwLoopPlan(repoRoot, args, scope) {
             plan.validationBatches = validationBatches;
         if (plan.codexGoalMode === "aggregate")
             plan.codexObjective = aggregateCodexObjectiveForScope(scope);
-        await mkdir(ulwLoopDir(repoRoot, scope), { recursive: true });
-        await writeFile(ulwLoopBriefPath(repoRoot, scope), args.brief.endsWith("\n") ? args.brief : `${args.brief}\n`, "utf8");
-        await writePlan(repoRoot, plan, scope);
-        await writeFile(ulwLoopLedgerPath(repoRoot, scope), "", "utf8");
-        await appendLedger(repoRoot, { at: now, kind: "plan_created", message: `${goals.length} goal(s) created` }, scope);
+        await beforePlanMutation();
+        await commit(repoRoot, scope, {
+            plan,
+            entries: [{ at: now, kind: "plan_created", message: `${goals.length} goal(s) created` }],
+        });
         return plan;
     });
 }
-function completedPlanExistsError(scope) {
+function completedPlanExistsError(scope, surface) {
     return new UlwLoopError([
         `Existing ulw-loop aggregate is already complete at ${ulwLoopGoalsRelativePath(scope)}.`,
-        "Start a new run with `omo-agent-toolkit ulw-loop create-goals --session-id <new-id> ...` to isolate fresh state.",
-        "Use --force only when you intentionally want to overwrite the completed evidence.",
+        ...(surface === "omo-senpi"
+            ? [
+                "Start a new run under a fresh session id (a new senpi session) or call agentToolkit.createGoals({ brief, force: true }) to recreate.",
+            ]
+            : [
+                "Start a new run with `omo-agent-toolkit ulw-loop create-goals --session-id <new-id> ...` to isolate fresh state.",
+                "Use --force only when you intentionally want to overwrite the completed evidence.",
+            ]),
     ].join(" "), "ULW_LOOP_PLAN_EXISTS_COMPLETE");
 }
-export async function addUlwLoopGoal(repoRoot, args, scope) {
+export async function addUlwLoopGoal(repoRoot, args, scope, surface = "lazycodex") {
     return withUlwLoopMutationLock(repoRoot, scope, async () => {
         const plan = await readUlwLoopPlan(repoRoot, scope);
         const now = iso();
-        const goal = appendGoalToPlan(plan, args.title, args.objective, now);
-        await writePlan(repoRoot, plan, scope);
-        await appendLedger(repoRoot, { at: now, kind: "goal_added", goalId: goal.id, status: goal.status, message: goal.title }, scope);
+        const goal = appendGoalToPlan(plan, args.title, args.objective, now, {
+            surface,
+            ...(args.successCriteria === undefined ? {} : { successCriteria: args.successCriteria }),
+        });
+        await commit(repoRoot, scope, {
+            plan,
+            entries: [{ at: now, kind: "goal_added", goalId: goal.id, status: goal.status, message: goal.title }],
+        });
         return { plan, goal };
     });
 }
@@ -82,17 +104,18 @@ export async function startNextUlwLoop(repoRoot, args = {}, scope) {
         const existing = plan.goals.find((goal) => goal.status === "in_progress" && isScheduleEligible(goal));
         if (existing)
             return { plan, goal: existing, resumed: true };
+        const entries = [];
         let next = plan.goals.find((goal) => goal.status === "pending" && isScheduleEligible(goal));
         if (!next && args.retryFailed) {
             next = plan.goals.find((goal) => goal.status === "failed" && !goal.nonRetriable && isScheduleEligible(goal));
             if (next)
-                await appendLedger(repoRoot, {
+                entries.push({
                     at: now,
                     kind: "goal_retried",
                     goalId: next.id,
                     status: "pending",
                     ...(next.failureReason ? { message: next.failureReason } : {}),
-                }, scope);
+                });
         }
         if (!next)
             return { done: true, plan };
@@ -103,8 +126,14 @@ export async function startNextUlwLoop(repoRoot, args = {}, scope) {
         next.updatedAt = now;
         plan.activeGoalId = next.id;
         plan.updatedAt = now;
-        await writePlan(repoRoot, plan, scope);
-        await appendLedger(repoRoot, { at: now, kind: "goal_started", goalId: next.id, status: next.status, message: `Attempt ${next.attempt}` }, scope);
+        entries.push({
+            at: now,
+            kind: "goal_started",
+            goalId: next.id,
+            status: next.status,
+            message: `Attempt ${next.attempt}`,
+        });
+        await commit(repoRoot, scope, { plan, entries });
         return { plan, goal: next, resumed: false };
     });
 }

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

@@ -1,8 +1,15 @@
+import { type SuccessCriterionInput } from "./success-criteria-input.js";
+import type { UlwLoopToolkitSurface } from "./surface.js";
 import type { UlwLoopItem, UlwLoopPlan, UlwLoopSuccessCriterion } from "./types.js";
-export declare function seedDefaultSuccessCriteria(goalIndex: number, objective: string): UlwLoopSuccessCriterion[];
+export interface GoalSeedOptions {
+    readonly goalId?: string;
+    readonly surface?: UlwLoopToolkitSurface;
+    readonly successCriteria?: readonly SuccessCriterionInput[];
+}
+export declare function seedDefaultSuccessCriteria(goalIndex: number, objective: string, options?: Pick<GoalSeedOptions, "goalId" | "surface">): UlwLoopSuccessCriterion[];
 export declare function deriveGoalCandidates(brief: string): Array<{
     title: string;
     objective: string;
 }>;
-export declare function makeGoal(title: string, objective: string, index: number, now: string): UlwLoopItem;
-export declare function appendGoalToPlan(plan: UlwLoopPlan, title: string, objective: string, now: string): UlwLoopItem;
+export declare function makeGoal(title: string, objective: string, index: number, now: string, options?: GoalSeedOptions): UlwLoopItem;
+export declare function appendGoalToPlan(plan: UlwLoopPlan, title: string, objective: string, now: string, options?: GoalSeedOptions): UlwLoopItem;