lazycodex-ai 5.0.0-beta.7 → 5.0.0-beta.71

package/packages/omo-codex/plugin/components/ulw-loop/dist/quality-gate-fields.js

@@ -1,39 +1,95 @@
 import { UlwLoopError } from "./types.js";
-const PLACEHOLDER_PATTERN = /^(?:placeholder|todo|tbd|n\/a|stub)$/i;
+const PLACEHOLDER_PATTERN = /^(?:<replace:[^>]+>|placeholder|todo|tbd|n\/a|stub)$/i;
+let activeCollector;
+/** A recorded defect poisons only its field; consumers skip dependent checks while preserving valid siblings and entry identity. */
+export function withQualityGateCollector(operation) {
+    const previous = activeCollector;
+    const collector = { defects: [], poisonedFields: new Set(), poisonedArtifactKinds: new Set() };
+    activeCollector = collector;
+    try {
+        const result = operation();
+        if (collector.defects.length === 0)
+            return result;
+        throwQualityGateDefects(collector.defects);
+    }
+    finally {
+        activeCollector = previous;
+    }
+}
+export function throwQualityGateDefects(defects) {
+    const uniqueDefects = [
+        ...new Map(defects.map((defect) => [`${defect.field}\u0000${defect.message}`, defect])).values(),
+    ];
+    const fields = uniqueDefects.slice(0, 25);
+    const truncated = uniqueDefects.length > fields.length;
+    const message = [
+        `Final quality gate has ${fields.length}${truncated ? "+" : ""} validation defects:`,
+        ...fields.map((item) => `- ${item.field}: ${item.message}`),
+    ].join("\n");
+    throw new UlwLoopError(message, "ULW_LOOP_QUALITY_GATE_INVALID", {
+        details: { field: fields[0]?.field, fields, ...(truncated ? { truncated: true } : {}) },
+    });
+}
 export function invalid(message, field) {
-    throw new UlwLoopError(message, "ULW_LOOP_QUALITY_GATE_INVALID", { details: { field } });
+    if (activeCollector === undefined)
+        throw new UlwLoopError(message, "ULW_LOOP_QUALITY_GATE_INVALID", { details: { field } });
+    activeCollector.defects.push({ field, message });
+    activeCollector.poisonedFields.add(field);
+    return undefined;
+}
+export function isPoisoned(field) {
+    return activeCollector?.poisonedFields.has(field) ?? false;
+}
+export function poisonField(field) {
+    activeCollector?.poisonedFields.add(field);
+}
+export function markPoisonedArtifactKind(id) {
+    activeCollector?.poisonedArtifactKinds.add(id);
+}
+export function isPoisonedArtifactKind(id) {
+    return activeCollector?.poisonedArtifactKinds.has(id) ?? false;
 }
 export function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 export function section(value, field) {
-    return isRecord(value) ? value : invalid(`Final quality gate is missing ${field} evidence.`, field);
+    if (isRecord(value))
+        return value;
+    invalid(`Final quality gate is missing ${field} evidence (accepted input: a bare object with manualQa/gateReview/iteration/criteriaCoverage and optional codeReview, or the same object under a top-level "qualityGate" key).`, field);
+    return {};
 }
 export function textField(value, field) {
-    if (typeof value !== "string" || value.trim() === "")
+    if (typeof value !== "string" || value.trim() === "") {
         invalid(`Final quality gate requires non-empty ${field}.`, field);
+        return "";
+    }
     const trimmed = value.trim();
     if (PLACEHOLDER_PATTERN.test(trimmed))
         invalid(`Final quality gate rejects placeholder ${field}.`, field);
     return trimmed;
 }
 export function numberField(value, field) {
-    return typeof value === "number" && Number.isFinite(value)
-        ? value
-        : invalid(`Final quality gate requires numeric ${field}.`, field);
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    invalid(`Final quality gate requires numeric ${field}.`, field);
+    return 0;
 }
 export function stringArray(value, field) {
-    if (!Array.isArray(value) || value.length === 0)
-        return invalid(`Final quality gate requires ${field}.`, field);
+    if (!Array.isArray(value) || value.length === 0) {
+        invalid(`Final quality gate requires ${field}.`, field);
+        return [];
+    }
     return value.map((item) => textField(item, field));
 }
 export function emptyBlockers(value, field) {
     if (Array.isArray(value) && value.length === 0)
         return [];
     invalid(`${field} must be empty.`, field);
+    return [];
 }
 export function literal(value, expected, field) {
     if (value === expected)
         return expected;
     invalid(`${field} must be ${String(expected)}.`, field);
+    return expected;
 }

package/packages/omo-codex/plugin/components/ulw-loop/dist/quality-gate-verdicts.js

@@ -1,13 +1,16 @@
 import { invalid, literal, textField } from "./quality-gate-fields.js";
 export function passedVerdict(value, field) {
-    if (value === "not_applicable")
+    if (value === "not_applicable") {
         invalid(`${field} must not be not_applicable.`, field);
+        return "passed";
+    }
     return literal(value, "passed", field);
 }
 export function codeQualityStatusField(value, field) {
     if (value === "CLEAR" || value === "WATCH")
         return value;
     invalid(`${field} must be CLEAR or WATCH.`, field);
+    return "CLEAR";
 }
 export function adversarialVerdict(row, field) {
     const value = row["verdict"];
@@ -17,4 +20,5 @@ export function adversarialVerdict(row, field) {
         return { verdict: "not_applicable", reason: textField(row["reason"], `${field}.reason`) };
     }
     invalid(`${field} must be passed or not_applicable with a reason.`, field);
+    return { verdict: "passed" };
 }

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

@@ -1,3 +1,4 @@
+import { type UlwLoopToolkitSurface } from "./surface.js";
 import type { UlwLoopQualityGate } from "./types.js";
 export { classifyExternalAuthorizationBlocker, clearGoalBlockerFields, normalizeBlockerEvidence, sameBlockerOccurrences, } from "./quality-gate-blockers.js";
 export interface QualityGateFs {
@@ -7,8 +8,9 @@ export interface QualityGateFs {
     };
 }
 export interface ValidateQualityGateOptions {
-    readonly repoRoot: string;
-    readonly fs: QualityGateFs;
+    readonly repoRoot?: string;
+    readonly fs?: QualityGateFs;
     readonly currentAttemptDir?: string;
+    readonly reviewerSurface?: UlwLoopToolkitSurface;
 }
 export declare function validateQualityGate(input: unknown, opts?: ValidateQualityGateOptions): UlwLoopQualityGate;

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

@@ -1,142 +1,69 @@
-import { resolve } from "node:path";
-import { isWithinAttemptDir } from "./paths.js";
-import { emptyBlockers, invalid, literal, numberField, section, stringArray, textField, } from "./quality-gate-fields.js";
+import { artifactCompatible, artifactMap, checkFile, compatibleKindsFor, parseArtifactRefs, referencedArtifacts, surfaceField, } from "./quality-gate-artifacts.js";
+import { emptyBlockers, invalid, isPoisoned, isPoisonedArtifactKind, literal, numberField, section, stringArray, textField, withQualityGateCollector, } from "./quality-gate-fields.js";
 import { adversarialVerdict, codeQualityStatusField, passedVerdict } from "./quality-gate-verdicts.js";
-const REVIEWER_ROLES = {
-    codeReview: "lazycodex-code-reviewer",
-    manualQa: "lazycodex-qa-executor",
-    gateReview: "lazycodex-gate-reviewer",
-};
+import { GATE_SECTION_BY_ACCEPTOR, OPTIONAL_GATE_SECTIONS_BY_SURFACE, REQUIRED_GATE_SECTIONS_BY_SURFACE, } from "./surface.js";
 export { classifyExternalAuthorizationBlocker, clearGoalBlockerFields, normalizeBlockerEvidence, sameBlockerOccurrences, } from "./quality-gate-blockers.js";
-function reviewerRoleField(value, expected, field) {
-    const actual = textField(value, field);
-    if (actual !== expected)
-        invalid(`${field} must be ${expected}.`, field);
-    return expected;
-}
-function surfaceField(value, field) {
-    if (value === "cli" ||
-        value === "http" ||
-        value === "tmux" ||
-        value === "browser" ||
-        value === "gui" ||
-        value === "data")
-        return value;
-    invalid(`${field} must be a supported manual QA surface.`, field);
-}
-function kindField(value, field) {
-    if (value === "cli-transcript" ||
-        value === "log" ||
-        value === "screenshot" ||
-        value === "image" ||
-        value === "http-dump" ||
-        value === "data-diff")
-        return value;
-    invalid(`${field} must be a supported artifact kind.`, field);
-}
-function artifactCompatible(surface, kind) {
-    switch (surface) {
-        case "cli":
-        case "tmux":
-            return kind === "cli-transcript" || kind === "log";
-        case "http":
-            return kind === "http-dump";
-        case "browser":
-        case "gui":
-            return kind === "screenshot" || kind === "image";
-        case "data":
-            return kind === "data-diff";
-        default:
-            invalid("manualQa.surfaceEvidence has an unsupported surface.", "manualQa.surfaceEvidence.surface");
+function reviewerAcceptorField(value, surface, sectionName) {
+    const field = `${sectionName}.by`;
+    const accepted = GATE_SECTION_BY_ACCEPTOR[surface][sectionName];
+    if (typeof value !== "string" || value.trim() === "") {
+        textField(value, field);
+        return accepted?.[0] ?? "";
     }
+    const actual = textField(value, field);
+    if (accepted === undefined || !accepted.includes(actual))
+        invalid(`${field} must be one of ${accepted?.join(", ") ?? "the configured reviewers"}.`, field);
+    return actual;
 }
-function checkFile(path, field, opts) {
-    if (opts === undefined)
-        return;
-    const absolute = resolve(opts.repoRoot, path);
-    if (!opts.fs.existsSync(absolute))
-        invalid(`${field} must point to an existing artifact.`, field);
-    if (opts.fs.statSync(absolute).size <= 0)
-        invalid(`${field} must point to a non-empty artifact.`, field);
-    if (opts.currentAttemptDir !== undefined) {
-        const attemptRoot = resolve(opts.repoRoot, opts.currentAttemptDir);
-        if (!isWithinAttemptDir(absolute, attemptRoot))
-            invalid(`${field} (${path}) must point to an artifact from the current attempt (${opts.currentAttemptDir}).`, field);
-    }
+export function validateQualityGate(input, opts) {
+    return withQualityGateCollector(() => validateQualityGateUncollected(input, opts));
 }
-function artifactMap(refs) {
-    const byId = new Map();
-    for (const ref of refs) {
-        if (byId.has(ref.id))
-            invalid(`manualQa.artifactRefs contains duplicate ${ref.id}.`, "manualQa.artifactRefs");
-        byId.set(ref.id, ref);
+function validateQualityGateUncollected(input, opts) {
+    const surface = opts?.reviewerSurface ?? "lazycodex";
+    const raw = input;
+    const gate = section(raw && typeof raw === "object" && "qualityGate" in raw ? raw["qualityGate"] : input, "qualityGate");
+    for (const name of REQUIRED_GATE_SECTIONS_BY_SURFACE[surface])
+        section(gate[name], name);
+    for (const name of Object.keys(gate)) {
+        if (name === "codeReview" && !OPTIONAL_GATE_SECTIONS_BY_SURFACE[surface].includes(name))
+            invalid("omo-senpi gate has no codeReview lane.", name);
     }
-    return byId;
-}
-function parseArtifactRefs(value, opts) {
-    if (!Array.isArray(value) || value.length === 0)
-        invalid("manualQa.artifactRefs must not be empty.", "manualQa.artifactRefs");
-    return value.map((item, index) => {
-        const ref = section(item, `manualQa.artifactRefs[${index}]`);
-        const path = textField(ref["path"], `manualQa.artifactRefs[${index}].path`);
-        checkFile(path, `manualQa.artifactRefs[${index}].path`, opts);
-        return {
-            id: textField(ref["id"], `manualQa.artifactRefs[${index}].id`),
-            kind: kindField(ref["kind"], `manualQa.artifactRefs[${index}].kind`),
-            description: textField(ref["description"], `manualQa.artifactRefs[${index}].description`),
-            path,
-        };
-    });
-}
-function referencedArtifacts(value, field, byId) {
-    return stringArray(value, field).map((id) => {
-        const artifact = byId.get(id);
-        if (artifact === undefined)
-            invalid(`${field} references unknown artifact ${id}.`, field);
-        return artifact;
-    });
-}
-export function validateQualityGate(input, opts) {
-    const gate = section(input, "qualityGate");
-    const codeReview = section(gate["codeReview"], "codeReview");
+    if (surface === "omo-senpi" && gate["codeReview"] !== undefined)
+        invalid("omo-senpi gate has no codeReview lane.", "codeReview");
     const manualQa = section(gate["manualQa"], "manualQa");
     const gateReview = section(gate["gateReview"], "gateReview");
     const iteration = section(gate["iteration"], "iteration");
     const coverage = section(gate["criteriaCoverage"], "criteriaCoverage");
+    const codeReview = gate["codeReview"] !== undefined ? section(gate["codeReview"], "codeReview") : undefined;
+    const manualQaBy = reviewerAcceptorField(manualQa["by"], surface, "manualQa");
+    const gateReviewBy = reviewerAcceptorField(gateReview["by"], surface, "gateReview");
+    const manualQaEvidence = textField(manualQa["evidence"], "manualQa.evidence");
+    const gateReviewEvidence = textField(gateReview["evidence"], "gateReview.evidence");
     const totalCriteria = numberField(coverage["totalCriteria"], "criteriaCoverage.totalCriteria");
     const passCount = numberField(coverage["passCount"], "criteriaCoverage.passCount");
-    if (passCount < totalCriteria)
+    if (!isPoisoned("criteriaCoverage.passCount") && passCount < totalCriteria)
         invalid("criteriaCoverage.passCount must cover totalCriteria.", "criteriaCoverage.passCount");
     const artifactRefs = parseArtifactRefs(manualQa["artifactRefs"], opts);
     const byId = artifactMap(artifactRefs);
     const surfaceEvidence = parseSurfaceEvidence(manualQa["surfaceEvidence"], byId);
     const adversarialCases = parseAdversarialCases(manualQa["adversarialCases"], byId);
-    const codeReportPath = textField(codeReview["reportPath"], "codeReview.reportPath");
     const gateReportPath = textField(gateReview["reportPath"], "gateReview.reportPath");
-    checkFile(codeReportPath, "codeReview.reportPath", opts);
-    checkFile(gateReportPath, "gateReview.reportPath", opts);
-    return {
-        codeReview: {
-            by: reviewerRoleField(codeReview["by"], REVIEWER_ROLES.codeReview, "codeReview.by"),
-            recommendation: literal(codeReview["recommendation"], "APPROVE", "codeReview.recommendation"),
-            codeQualityStatus: codeQualityStatusField(codeReview["codeQualityStatus"], "codeReview.codeQualityStatus"),
-            reportPath: codeReportPath,
-            evidence: textField(codeReview["evidence"], "codeReview.evidence"),
-            blockers: emptyBlockers(codeReview["blockers"], "codeReview.blockers"),
-        },
+    if (!isPoisoned("gateReview.reportPath"))
+        checkFile(gateReportPath, "gateReview.reportPath", opts);
+    const common = {
         manualQa: {
-            by: reviewerRoleField(manualQa["by"], REVIEWER_ROLES.manualQa, "manualQa.by"),
+            by: manualQaBy,
             status: literal(manualQa["status"], "passed", "manualQa.status"),
-            evidence: textField(manualQa["evidence"], "manualQa.evidence"),
+            evidence: manualQaEvidence,
             surfaceEvidence,
             adversarialCases,
             artifactRefs,
         },
         gateReview: {
-            by: reviewerRoleField(gateReview["by"], REVIEWER_ROLES.gateReview, "gateReview.by"),
+            by: gateReviewBy,
             recommendation: literal(gateReview["recommendation"], "APPROVE", "gateReview.recommendation"),
             reportPath: gateReportPath,
-            evidence: textField(gateReview["evidence"], "gateReview.evidence"),
+            evidence: gateReviewEvidence,
             blockers: emptyBlockers(gateReview["blockers"], "gateReview.blockers"),
         },
         iteration: {
@@ -154,17 +81,41 @@ export function validateQualityGate(input, opts) {
             adversarialClassesCovered: stringArray(coverage["adversarialClassesCovered"], "criteriaCoverage.adversarialClassesCovered"),
         },
     };
+    if (surface === "omo-senpi")
+        return { surface, ...common };
+    if (codeReview === undefined)
+        return { surface, ...common };
+    const codeReportPath = textField(codeReview["reportPath"], "codeReview.reportPath");
+    checkFile(codeReportPath, "codeReview.reportPath", opts);
+    return {
+        surface,
+        ...common,
+        codeReview: {
+            by: reviewerAcceptorField(codeReview["by"], surface, "codeReview"),
+            recommendation: literal(codeReview["recommendation"], "APPROVE", "codeReview.recommendation"),
+            codeQualityStatus: codeQualityStatusField(codeReview["codeQualityStatus"], "codeReview.codeQualityStatus"),
+            reportPath: codeReportPath,
+            evidence: textField(codeReview["evidence"], "codeReview.evidence"),
+            blockers: emptyBlockers(codeReview["blockers"], "codeReview.blockers"),
+        },
+    };
 }
 function parseSurfaceEvidence(value, byId) {
-    if (!Array.isArray(value) || value.length === 0)
+    if (!Array.isArray(value) || value.length === 0) {
         invalid("manualQa.surfaceEvidence must not be empty.", "manualQa.surfaceEvidence");
-    return value.map((item, index) => {
+        return [];
+    }
+    return value.flatMap((item, index) => {
         const row = section(item, `manualQa.surfaceEvidence[${index}]`);
+        if (isPoisoned(`manualQa.surfaceEvidence[${index}]`))
+            return [];
         const surface = surfaceField(row["surface"], `manualQa.surfaceEvidence[${index}].surface`);
         const artifacts = referencedArtifacts(row["artifactRefs"], `manualQa.surfaceEvidence[${index}].artifactRefs`, byId);
         for (const artifact of artifacts) {
+            if (isPoisoned(`manualQa.surfaceEvidence[${index}].surface`) || isPoisonedArtifactKind(artifact.id))
+                continue;
             if (!artifactCompatible(surface, artifact.kind)) {
-                invalid(`manualQa.surfaceEvidence ${surface} artifact ${artifact.kind} is incompatible.`, "manualQa.surfaceEvidence");
+                invalid(`manualQa.surfaceEvidence ${surface} artifact ${artifact.kind} is incompatible; surface "${surface}" accepts artifact kinds: ${compatibleKindsFor(surface).join(", ")}.`, "manualQa.surfaceEvidence");
             }
         }
         return {
@@ -178,10 +129,14 @@ function parseSurfaceEvidence(value, byId) {
     });
 }
 function parseAdversarialCases(value, byId) {
-    if (!Array.isArray(value) || value.length === 0)
+    if (!Array.isArray(value) || value.length === 0) {
         invalid("manualQa.adversarialCases must not be empty.", "manualQa.adversarialCases");
-    return value.map((item, index) => {
+        return [];
+    }
+    return value.flatMap((item, index) => {
         const row = section(item, `manualQa.adversarialCases[${index}]`);
+        if (isPoisoned(`manualQa.adversarialCases[${index}]`))
+            return [];
         const artifacts = referencedArtifacts(row["artifactRefs"], `manualQa.adversarialCases[${index}].artifactRefs`, byId);
         const verdictInfo = adversarialVerdict(row, `manualQa.adversarialCases[${index}]`);
         return {

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

@@ -12,5 +12,7 @@ export interface RecordFinalReviewBlockersResult {
     readonly blockedGoal: UlwLoopItem;
     readonly newGoal: UlwLoopItem;
     readonly ledgerEntries: UlwLoopLedgerEntry[];
+    readonly nextActions: readonly string[];
+    readonly warnings: readonly string[];
 }
 export declare function recordFinalReviewBlockers(repoRoot: string, args: RecordFinalReviewBlockersArgs, scope?: UlwLoopScope): Promise<RecordFinalReviewBlockersResult>;

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

@@ -1,8 +1,10 @@
 // biome-ignore-all format: compact port must stay within the requested pure LOC budget.
-import { readCodexGoalSnapshotInput, reconcileCodexGoalSnapshot } from "./codex-goal-snapshot.js";
-import { codexGoalMode, compatibleCodexObjectives, expectedCodexObjective, isFinalRunCompletionCandidate } from "./goal-status.js";
+import { CodexGoalSnapshotError, formatCodexGoalReconciliation, readCodexGoalSnapshotInput, reconcileCodexGoalSnapshot, } from "./codex-goal-snapshot.js";
+import { acknowledgeDriverObjective, acknowledgedDriverObjectives } from "./driver-objective-ack.js";
+import { compatibleCodexObjectives, expectedCodexObjective, isFinalRunCompletionCandidate } from "./goal-status.js";
+import { commit } from "./plan-commit.js";
 import { seedDefaultSuccessCriteria } from "./plan-crud.js";
-import { appendLedger, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
+import { readUlwLoopPlan, withUlwLoopMutationLock } from "./plan-io.js";
 import { iso, UlwLoopError } from "./types.js";
 const BLOCKER_FIELDS = "blockedReason blockerSignature blockerOccurrenceCount requiredExternalDecision nonRetriable failedAt failureReason completedAt blocker blockerEvidence blockerOccurrences blockedAt".split(" ");
 function ulwLoopError(message, code) {
@@ -17,12 +19,13 @@ function nextGoalId(plan) {
 }
 function appendBlockerGoal(plan, args, now) {
     const index = plan.goals.length;
+    const id = nextGoalId(plan);
     const goal = {
-        id: nextGoalId(plan),
+        id,
         title: args.title,
         objective: args.objective,
         status: "pending",
-        successCriteria: seedDefaultSuccessCriteria(index, args.objective),
+        successCriteria: seedDefaultSuccessCriteria(index, args.objective, { goalId: id }),
         attempt: 0,
         createdAt: now,
         updatedAt: now,
@@ -41,10 +44,14 @@ export async function recordFinalReviewBlockers(repoRoot, args, scope) {
         if (!isFinalRunCompletionCandidate(plan, goal))
             ulwLoopError(`${goal.id} is not final.`, "ulw_loop_not_final_story");
         const snapshot = await readCodexGoalSnapshotInput(args.codexGoalJson, repoRoot);
-        const aggregate = codexGoalMode(plan) === "aggregate";
-        const reconciliation = reconcileCodexGoalSnapshot(snapshot, { expectedObjective: expectedCodexObjective(plan, goal), ...(aggregate ? { acceptedObjectives: compatibleCodexObjectives(plan) } : {}), allowedStatuses: ["active"], requireSnapshot: true, requireComplete: false });
+        const reconciliation = reconcileCodexGoalSnapshot(snapshot, {
+            expectedObjective: expectedCodexObjective(plan, goal),
+            acceptedObjectives: compatibleCodexObjectives(plan),
+            acknowledgedObjectives: acknowledgedDriverObjectives(plan),
+        });
         if (!reconciliation.ok)
-            ulwLoopError(reconciliation.errors.join(" "), "ulw_loop_codex_snapshot_mismatch");
+            throw new CodexGoalSnapshotError(formatCodexGoalReconciliation(reconciliation));
+        acknowledgeDriverObjective(plan, reconciliation.unacknowledgedObjective);
         const now = iso();
         for (const field of BLOCKER_FIELDS)
             Reflect.deleteProperty(goal, field);
@@ -56,15 +63,20 @@ export async function recordFinalReviewBlockers(repoRoot, args, scope) {
             delete plan.activeGoalId;
         const newGoal = appendBlockerGoal(plan, args, now);
         plan.updatedAt = now;
-        const codexGoal = reconciliation.snapshot.raw;
+        const codexGoal = snapshot?.raw;
         const blockedEntry = { at: now, kind: "goal_review_blocked", goalId: goal.id, status: goal.status, evidence: args.evidence, codexGoal };
         const addedEntry = { at: now, kind: "goal_added", goalId: newGoal.id, status: newGoal.status, evidence: args.evidence, message: newGoal.title };
         const summaryEntry = { at: now, kind: "goal_review_blocked", goalId: goal.id, status: goal.status, evidence: args.evidence, codexGoal, message: `Review blockers recorded; appended ${newGoal.id}.` };
         Reflect.set(summaryEntry, "kind", "blocker_recorded");
         const ledgerEntries = [blockedEntry, addedEntry, summaryEntry];
-        await writePlan(repoRoot, plan, scope);
-        for (const entry of ledgerEntries)
-            await appendLedger(repoRoot, entry, scope);
-        return { plan, blockedGoal: goal, newGoal, ledgerEntries };
+        await commit(repoRoot, scope, { plan, entries: ledgerEntries });
+        return {
+            plan,
+            blockedGoal: goal,
+            newGoal,
+            ledgerEntries,
+            nextActions: reconciliation.nextActions,
+            warnings: reconciliation.warnings,
+        };
     });
 }

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

@@ -0,0 +1,2 @@
+import type { AgentToolkit, AgentToolkitDependencies, ToolkitContext } from "./types.js";
+export declare function createAgentToolkit(context: ToolkitContext, deps?: AgentToolkitDependencies): AgentToolkit;

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

@@ -0,0 +1,157 @@
+import { checkpointUlwLoop } from "../checkpoint.js";
+import { checkpointTemplate } from "../checkpoint-template.js";
+import { recordEvidence } from "../evidence.js";
+import { normalizeUlwLoopSessionId, ulwLoopAttemptEvidenceDir, ulwLoopEvidenceRoot, ulwLoopGoalsRelativePath, } from "../paths.js";
+import { addUlwLoopGoal, createUlwLoopPlan, startNextUlwLoop, summarizeUlwLoopPlan } from "../plan-crud.js";
+import { listUlwLoopSessionIds, readUlwLoopPlan } from "../plan-io.js";
+import { planMissingError } from "../plan-missing-recovery.js";
+import { recordFinalReviewBlockers } from "../review-blockers.js";
+import { UlwLoopError } from "../runtime.js";
+import { statusNextActions } from "../status-next-actions.js";
+import { steerUlwLoop } from "../steering.js";
+import { ULW_LOOP_MANIFEST } from "./manifest.js";
+// The SDK takes inline values only, so a snapshot that is not JSON is a caller error - normalize it
+// to the same stable code the CLI reports instead of letting it surface as a generic failure.
+function validateCodexGoalJson(raw) {
+    if (raw === undefined)
+        return;
+    try {
+        JSON.parse(raw);
+    }
+    catch (error) {
+        throw new UlwLoopError(`Invalid codexGoal: ${error instanceof Error ? error.message : "not valid JSON"}`, "ULW_LOOP_CODEX_GOAL_JSON_INVALID", { cause: error });
+    }
+}
+function validateContext(context) {
+    if (!context.cwd.trim())
+        throw new UlwLoopError("cwd is required.", "ULW_LOOP_CWD_REQUIRED");
+    const sessionId = context.sessionId.trim();
+    if (!sessionId)
+        throw new UlwLoopError("ULW_LOOP_SESSION_ID_REQUIRED: sessionId is required.", "ULW_LOOP_SESSION_ID_REQUIRED");
+    const normalizedSessionId = normalizeUlwLoopSessionId(sessionId);
+    if (normalizedSessionId === null || /(?:^|[\\/])\.\.(?:[\\/]|$)/.test(sessionId))
+        throw new UlwLoopError("ULW_LOOP_SESSION_ID_INVALID: sessionId normalizes to null.", "ULW_LOOP_SESSION_ID_INVALID");
+    if (context.surface !== "omo-senpi" && context.surface !== "lazycodex")
+        throw new UlwLoopError("surface must be omo-senpi or lazycodex.", "ULW_LOOP_SURFACE_INVALID");
+}
+function errorDetails(error) {
+    const details = error.details === undefined
+        ? undefined
+        : Object.fromEntries(Object.entries(error.details).map(([key, value]) => [key, String(value)]));
+    return details === undefined
+        ? { code: error.code, message: error.message }
+        : { code: error.code, message: error.message, details };
+}
+function failure(operation, error) {
+    return { ok: false, operation, error: errorDetails(error) };
+}
+function caught(operation, error) {
+    return failure(operation, error instanceof UlwLoopError ? error : new UlwLoopError(error.message, "ULW_LOOP_ERROR"));
+}
+function isKnownRequest(request) {
+    return ULW_LOOP_MANIFEST.operations.some((operation) => operation.name === request.operation);
+}
+function unreachable(value) {
+    throw new UlwLoopError(`Unhandled operation: ${String(value)}`, "ULW_LOOP_OPERATION_UNHANDLED");
+}
+function stringsFrom(result, key) {
+    if (!(key in result))
+        return [];
+    const value = Object.entries(result).find(([name]) => name === key)?.[1];
+    return Array.isArray(value) ? value.filter((item) => typeof item === "string").slice(0, 8) : [];
+}
+function checkpointWithValidatedSnapshot(context, scope, args) {
+    validateCodexGoalJson(args.codexGoalJson);
+    return checkpointUlwLoop(context.cwd, args, scope, { surface: context.surface });
+}
+export function createAgentToolkit(context, deps = {}) {
+    validateContext(context);
+    const scope = { sessionId: context.sessionId };
+    const notify = async (operation, response) => {
+        if (deps.hooks?.onOperation !== undefined)
+            await deps.hooks.onOperation({ operation, context, response });
+        return response;
+    };
+    const invoke = async (operation, fn) => {
+        try {
+            const result = await fn();
+            const nextActions = typeof result === "object" && result !== null ? stringsFrom(result, "nextActions") : [];
+            const warnings = typeof result === "object" && result !== null ? stringsFrom(result, "warnings") : [];
+            return await notify(operation, {
+                ok: true,
+                operation,
+                result,
+                nextActions,
+                ...(warnings.length === 0 ? {} : { warnings }),
+            });
+        }
+        catch (error) {
+            if (error instanceof UlwLoopError && error.code === "ULW_LOOP_PLAN_MISSING" && context.surface === "omo-senpi")
+                return notify(operation, failure(operation, planMissingError(ulwLoopGoalsRelativePath(scope), listUlwLoopSessionIds(context.cwd), context.surface)));
+            const response = caught(operation, error instanceof Error ? error : new Error("ULW_LOOP_ERROR"));
+            return notify(operation, response);
+        }
+    };
+    const toolkit = {
+        dispatch: async (request) => {
+            if (!isKnownRequest(request))
+                return failure(request.operation, new UlwLoopError(`Unknown operation: ${request.operation}`, "ULW_LOOP_OPERATION_UNKNOWN"));
+            switch (request.operation) {
+                case "help":
+                    return toolkit.help();
+                case "create-goals":
+                    return toolkit.createGoals(request.args);
+                case "status":
+                    return toolkit.status();
+                case "complete-goals":
+                    return toolkit.completeGoals(request.args);
+                case "checkpoint":
+                    return toolkit.checkpoint(request.args);
+                case "steer":
+                    return toolkit.steer(request.args);
+                case "add-goal":
+                    return toolkit.addGoal(request.args);
+                case "criteria":
+                    return toolkit.criteria(request.args);
+                case "record-evidence":
+                    return toolkit.recordEvidence(request.args);
+                case "record-review-blockers":
+                    return toolkit.recordReviewBlockers(request.args);
+                default:
+                    return unreachable(request);
+            }
+        },
+        help: () => invoke("help", async () => ULW_LOOP_MANIFEST),
+        createGoals: (args) => invoke("create-goals", () => createUlwLoopPlan(context.cwd, args, scope, context.surface)),
+        status: () => invoke("status", async () => {
+            const plan = await readUlwLoopPlan(context.cwd, scope);
+            const active = plan.goals.find((goal) => goal.id === plan.activeGoalId);
+            return {
+                plan,
+                summary: summarizeUlwLoopPlan(plan),
+                nextActions: statusNextActions(plan, context.surface),
+                evidenceRoot: ulwLoopEvidenceRoot(scope),
+                // Attempt directories are an evidence-layout v2 concept; a v1 plan must not advertise one.
+                ...(active === undefined || plan.evidenceLayoutVersion !== 2
+                    ? {}
+                    : { currentAttemptDir: ulwLoopAttemptEvidenceDir(active.id, active.attempt, scope) }),
+            };
+        }),
+        completeGoals: (args = {}) => invoke("complete-goals", () => startNextUlwLoop(context.cwd, args, scope)),
+        checkpoint: (args) => invoke("checkpoint", () => args.printTemplate === true
+            ? checkpointTemplate(context.cwd, scope, args.goalId, { surface: context.surface })
+            : checkpointWithValidatedSnapshot(context, scope, args)),
+        steer: (args) => invoke("steer", () => steerUlwLoop(context.cwd, args, scope, context.surface)),
+        addGoal: (args) => invoke("add-goal", () => addUlwLoopGoal(context.cwd, args, scope, context.surface)),
+        criteria: (args) => invoke("criteria", async () => {
+            const plan = await readUlwLoopPlan(context.cwd, scope);
+            const goal = plan.goals.find((candidate) => candidate.id === args.goalId);
+            if (goal === undefined)
+                throw new UlwLoopError(`Unknown ulw-loop id: ${args.goalId}.`, "ULW_LOOP_GOAL_NOT_FOUND");
+            return { goalId: goal.id, criteria: goal.successCriteria };
+        }),
+        recordEvidence: (args) => invoke("record-evidence", () => recordEvidence(context.cwd, args, scope)),
+        recordReviewBlockers: (args) => invoke("record-review-blockers", () => recordFinalReviewBlockers(context.cwd, args, scope)),
+    };
+    return toolkit;
+}