oh-my-codex 0.18.0 → 0.18.2

package/dist/ultragoal/artifacts.js

@@ -1,11 +1,25 @@
 import { existsSync } from 'node:fs';
-import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { appendFile, mkdir, open, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { join, relative } from 'node:path';
 import { formatCodexGoalReconciliation, parseCodexGoalSnapshot, reconcileCodexGoalSnapshot, } from '../goal-workflows/codex-goal-snapshot.js';
 export const ULTRAGOAL_DIR = '.omx/ultragoal';
 export const ULTRAGOAL_BRIEF = 'brief.md';
 export const ULTRAGOAL_GOALS = 'goals.json';
 export const ULTRAGOAL_LEDGER = 'ledger.jsonl';
+const ULTRAGOAL_MUTATION_LOCK = '.mutation.lock';
+export const ULTRAGOAL_STEERING_MUTATION_KINDS = [
+    'add_subgoal',
+    'split_subgoal',
+    'reorder_pending',
+    'revise_pending_wording',
+    'annotate_ledger',
+    'mark_blocked_superseded',
+];
+export const ULTRAGOAL_STEERING_SOURCES = [
+    'user_prompt_submit',
+    'finding',
+    'cli',
+];
 export class UltragoalError extends Error {
 }
 function iso(now = new Date()) {
@@ -32,6 +46,51 @@ function cleanLine(line) {
 function normalizeObjective(value) {
     return value.replace(/\s+/g, ' ').trim();
 }
+function normalizeBlockerEvidence(value) {
+    return (value ?? '')
+        .toLowerCase()
+        .replace(/https?:\/\/\S+/g, ' ')
+        .replace(/[`"'()[\]{}:,;]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function classifyExternalAuthorizationBlocker(evidence) {
+    const normalized = normalizeBlockerEvidence(evidence);
+    if (!normalized)
+        return null;
+    const mentionsAuthorization = /\b(auth|authorization|credential|credentials|token|permission|permissions|scope|scopes|access|unauthorized|forbidden|401|403)\b/.test(normalized);
+    const mentionsMissingAuthority = /\b(unset|missing|required|requires|without|omit|omits|not set|not available|no read packages|read packages)\b/.test(normalized);
+    if (!mentionsAuthorization || !mentionsMissingAuthority)
+        return null;
+    const mentionsGhcr = /\b(ghcr|github container registry|read packages|imagepullsecret|package api|anonymous image|container image)\b/.test(normalized);
+    if (mentionsGhcr) {
+        const has401 = /\b(401|unauthorized|anonymous pull|authentication required)\b/.test(normalized);
+        const has403 = /\b(403|forbidden|read packages|package api)\b/.test(normalized);
+        const status = [has401 ? 'HTTP_401_ANONYMOUS' : null, has403 ? 'HTTP_403_NO_READ_PACKAGES' : null]
+            .filter((part) => Boolean(part))
+            .join('+') || 'AUTHORIZATION_REQUIRED';
+        return {
+            signature: `GHCR_PULL_ACCESS:${status}:GHCR_VISIBILITY_OR_CREDENTIAL_REQUIRED`,
+            requiredDecision: 'make the GHCR package public, or provide/authorize a least-privilege read:packages credential and imagePullSecret/SOPS path',
+        };
+    }
+    return {
+        signature: 'EXTERNAL_AUTHORIZATION_REQUIRED',
+        requiredDecision: 'provide the missing external authorization/credential, or explicitly choose a different unblock path',
+    };
+}
+function sameBlockerOccurrences(entries, goalId, signature) {
+    return entries.filter((entry) => (entry.goalId === goalId
+        && (entry.event === 'goal_failed' || entry.event === 'goal_needs_user_decision')
+        && entry.blockerSignature === signature)).length;
+}
+function clearGoalBlockerFields(goal) {
+    goal.blockedReason = undefined;
+    goal.blockerSignature = undefined;
+    goal.blockerOccurrenceCount = undefined;
+    goal.requiredExternalDecision = undefined;
+    goal.nonRetriable = undefined;
+}
 function textMentionsUltragoalPlanArtifact(value) {
     const normalized = (value ?? '').toLowerCase();
     return normalized.includes(ULTRAGOAL_DIR.toLowerCase())
@@ -82,7 +141,14 @@ function buildCompletedLegacyGoalRemediation(goal) {
     return [
         'If get_goal returns a different completed legacy/thread objective, do not repeat --status complete in this thread.',
         `Record a non-terminal blocker with: omx ultragoal checkpoint --goal-id ${goal.id} --status blocked --evidence "<completed legacy Codex goal blocks create_goal in this thread>" --codex-goal-json "<different completed get_goal JSON or path>".`,
-        'Then continue this ultragoal in a fresh Codex thread in the same repo/worktree and create the intended goal there.',
+        'Then continue only from a Codex goal context with no active/completed conflicting goal, in the same repo/worktree, and create the intended goal there.',
+    ].join(' ');
+}
+function buildUnavailableCodexGoalRemediation(goal) {
+    return [
+        'If get_goal itself is unavailable due to a Codex DB/schema/context error, such as "no such table: thread_goals", do not repeat --status complete or mark the Codex goal complete from shell state.',
+        `Record an auditable non-terminal blocker with: omx ultragoal checkpoint --goal-id ${goal.id} --status blocked --evidence "<get_goal unavailable due to Codex DB/schema/context error; safe recovery requires a working Codex goal context>" --codex-goal-json "<unavailable get_goal error JSON or path>".`,
+        'Then continue from a Codex goal context where get_goal works and strict completion reconciliation can be proven.',
     ].join(' ');
 }
 function codexGoalMode(plan) {
@@ -91,35 +157,78 @@ function codexGoalMode(plan) {
 function isResolvedStatus(status) {
     return status === 'complete' || status === 'review_blocked';
 }
-function aggregateCodexObjective(goals) {
-    const prefix = `Complete all ultragoal stories in ${ULTRAGOAL_DIR}/${ULTRAGOAL_GOALS}: `;
-    const suffix = goals.map((goal) => `${goal.id} ${goal.title}`).join('; ');
-    const full = `${prefix}${suffix}`;
-    if (full.length <= 4000)
-        return full;
-    const fallback = `Complete all ultragoal stories listed in ${ULTRAGOAL_DIR}/${ULTRAGOAL_GOALS}. Use ${ULTRAGOAL_DIR}/${ULTRAGOAL_LEDGER} as the durable audit trail.`;
-    if (fallback.length <= 4000)
-        return fallback;
+function isScheduleEligibleGoal(goal) {
+    return goal.steeringStatus !== 'superseded' && goal.steeringStatus !== 'blocked';
+}
+export const ULTRAGOAL_AGGREGATE_CODEX_OBJECTIVE = `Complete the durable ultragoal plan in ${ULTRAGOAL_DIR}/${ULTRAGOAL_GOALS}, including later accepted/appended stories, under the original brief constraints; use ${ULTRAGOAL_DIR}/${ULTRAGOAL_LEDGER} as the audit trail.`;
+function aggregateCodexObjective(_goals) {
+    if (ULTRAGOAL_AGGREGATE_CODEX_OBJECTIVE.length <= 4000)
+        return ULTRAGOAL_AGGREGATE_CODEX_OBJECTIVE;
     throw new UltragoalError('Generated aggregate Codex objective exceeds the 4,000 character goal limit.');
 }
+function isLegacyEnumeratedAggregateObjective(objective) {
+    if (!objective)
+        return false;
+    return (objective.startsWith(`Complete all ultragoal stories in ${ULTRAGOAL_DIR}/${ULTRAGOAL_GOALS}: `)
+        || objective === `Complete all ultragoal stories listed in ${ULTRAGOAL_DIR}/${ULTRAGOAL_GOALS}. Use ${ULTRAGOAL_DIR}/${ULTRAGOAL_LEDGER} as the durable audit trail.`);
+}
+function compatibleCodexObjectives(plan) {
+    return (plan.codexObjectiveAliases ?? [])
+        .filter((objective) => isLegacyEnumeratedAggregateObjective(objective));
+}
 function expectedCodexObjective(plan, goal) {
     return codexGoalMode(plan) === 'aggregate'
         ? (plan.codexObjective ?? aggregateCodexObjective(plan.goals))
         : goal.objective;
 }
+function isSupersededResolved(goal, plan) {
+    if (goal.steeringStatus !== 'superseded')
+        return false;
+    const replacements = goal.supersededBy ?? [];
+    if (replacements.length === 0)
+        return false;
+    return replacements.every((id) => {
+        const replacement = plan.goals.find((candidate) => candidate.id === id);
+        return replacement !== undefined && isResolvedStatus(replacement.status);
+    });
+}
+function isCompletionBlocking(goal, plan) {
+    if (goal.steeringStatus === 'superseded')
+        return !isSupersededResolved(goal, plan);
+    if (goal.steeringStatus === 'blocked')
+        return true;
+    return !isResolvedStatus(goal.status);
+}
+function isCompletionBlockingForFinalCandidate(candidate, finalCandidate, plan) {
+    if (candidate.id === finalCandidate.id)
+        return false;
+    if (candidate.steeringStatus === 'superseded') {
+        const replacements = candidate.supersededBy ?? [];
+        if (replacements.length === 0)
+            return true;
+        return !replacements.every((id) => {
+            if (id === finalCandidate.id)
+                return true;
+            const replacement = plan.goals.find((goal) => goal.id === id);
+            return replacement !== undefined && isResolvedStatus(replacement.status);
+        });
+    }
+    return isCompletionBlocking(candidate, plan);
+}
+function isScheduleEligible(goal) {
+    return goal.steeringStatus !== 'superseded' && goal.steeringStatus !== 'blocked';
+}
 export function isFinalRunCompletionCandidate(plan, goal) {
-    return plan.goals.every((candidate) => candidate.id === goal.id || isResolvedStatus(candidate.status));
+    return plan.goals.every((candidate) => !isCompletionBlockingForFinalCandidate(candidate, goal, plan));
 }
 export function isUltragoalDone(plan) {
     if (plan.aggregateCompletion?.status === 'complete')
         return true;
     if (plan.goals.length === 0)
         return true;
-    if (plan.goals.some((goal) => goal.status === 'pending' || goal.status === 'in_progress' || goal.status === 'failed'))
+    if (plan.goals.some((goal) => isCompletionBlocking(goal, plan)))
         return false;
-    if (!plan.goals.every((goal) => isResolvedStatus(goal.status)))
-        return false;
-    const latestNonReviewBlocked = [...plan.goals].reverse().find((goal) => goal.status !== 'review_blocked');
+    const latestNonReviewBlocked = [...plan.goals].reverse().find((goal) => goal.status !== 'review_blocked' && goal.steeringStatus !== 'superseded');
     return latestNonReviewBlocked?.status === 'complete';
 }
 function titleFromObjective(objective, fallback) {
@@ -155,6 +264,37 @@ function normalizeGoalId(title, index) {
         .replace(/-+$/g, '');
     return `G${String(index + 1).padStart(3, '0')}${slug ? `-${slug}` : ''}`;
 }
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function withUltragoalMutationLock(cwd, operation) {
+    await mkdir(ultragoalDir(cwd), { recursive: true });
+    const lockPath = join(ultragoalDir(cwd), ULTRAGOAL_MUTATION_LOCK);
+    let handle;
+    for (let attempt = 0; attempt < 100; attempt += 1) {
+        try {
+            handle = await open(lockPath, 'wx');
+            await handle.writeFile(JSON.stringify({ pid: process.pid, createdAt: iso() }));
+            break;
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'EEXIST')
+                throw error;
+            await sleep(Math.min(25 + attempt * 5, 250));
+        }
+    }
+    if (!handle) {
+        throw new UltragoalError(`Timed out waiting for ultragoal mutation lock at ${repoRelative(cwd, lockPath)}.`);
+    }
+    try {
+        return await operation();
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+        await rm(lockPath, { force: true }).catch(() => undefined);
+    }
+}
 async function appendLedger(cwd, entry) {
     await mkdir(ultragoalDir(cwd), { recursive: true });
     const path = ultragoalLedgerPath(cwd);
@@ -173,49 +313,69 @@ export async function readUltragoalPlan(cwd) {
     if (parsed.version !== 1 || !Array.isArray(parsed.goals)) {
         throw new UltragoalError(`Invalid ultragoal plan at ${repoRelative(cwd, path)}.`);
     }
+    if (codexGoalMode(parsed) === 'aggregate' && isLegacyEnumeratedAggregateObjective(parsed.codexObjective)) {
+        const previousObjective = parsed.codexObjective;
+        const now = iso();
+        parsed.codexObjective = aggregateCodexObjective(parsed.goals);
+        parsed.codexObjectiveAliases = Array.from(new Set([...(parsed.codexObjectiveAliases ?? []), previousObjective].filter((value) => typeof value === 'string' && value.length > 0)));
+        parsed.updatedAt = now;
+        await writePlan(cwd, parsed);
+        await appendLedger(cwd, {
+            ts: now,
+            event: 'aggregate_objective_migrated',
+            message: 'Migrated legacy enumerated aggregate Codex objective to the stable pointer objective.',
+            before: { codexObjective: previousObjective },
+            after: { codexObjective: parsed.codexObjective },
+        });
+    }
     return parsed;
 }
 async function writePlan(cwd, plan) {
     await mkdir(ultragoalDir(cwd), { recursive: true });
-    await writeFile(ultragoalGoalsPath(cwd), `${JSON.stringify(plan, null, 2)}\n`);
+    const path = ultragoalGoalsPath(cwd);
+    const tmpPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+    await writeFile(tmpPath, `${JSON.stringify(plan, null, 2)}\n`);
+    await rename(tmpPath, path);
 }
 export async function createUltragoalPlan(cwd, options) {
-    if (!options.force && existsSync(ultragoalGoalsPath(cwd))) {
-        throw new UltragoalError(`Refusing to overwrite existing ${ULTRAGOAL_DIR}/${ULTRAGOAL_GOALS}; pass --force to recreate it.`);
-    }
-    const now = iso(options.now);
-    const sourceGoals = options.goals?.length
-        ? options.goals
-        : deriveGoalCandidates(options.brief);
-    const candidates = sourceGoals
-        .map((goal, index) => ({
-        id: normalizeGoalId(goal.title ?? titleFromObjective(goal.objective, `Goal ${index + 1}`), index),
-        title: goal.title ?? titleFromObjective(goal.objective, `Goal ${index + 1}`),
-        objective: goal.objective.trim(),
-        status: 'pending',
-        tokenBudget: goal.tokenBudget,
-        attempt: 0,
-        createdAt: now,
-        updatedAt: now,
-    }));
-    const plan = {
-        version: 1,
-        createdAt: now,
-        updatedAt: now,
-        briefPath: `${ULTRAGOAL_DIR}/${ULTRAGOAL_BRIEF}`,
-        goalsPath: `${ULTRAGOAL_DIR}/${ULTRAGOAL_GOALS}`,
-        ledgerPath: `${ULTRAGOAL_DIR}/${ULTRAGOAL_LEDGER}`,
-        codexGoalMode: options.codexGoalMode ?? 'aggregate',
-        goals: candidates,
-    };
-    if (plan.codexGoalMode === 'aggregate')
-        plan.codexObjective = aggregateCodexObjective(candidates);
-    await mkdir(ultragoalDir(cwd), { recursive: true });
-    await writeFile(ultragoalBriefPath(cwd), options.brief.endsWith('\n') ? options.brief : `${options.brief}\n`);
-    await writePlan(cwd, plan);
-    await writeFile(ultragoalLedgerPath(cwd), '');
-    await appendLedger(cwd, { ts: now, event: 'plan_created', message: `${candidates.length} goal(s) created` });
-    return plan;
+    return withUltragoalMutationLock(cwd, async () => {
+        if (!options.force && existsSync(ultragoalGoalsPath(cwd))) {
+            throw new UltragoalError(`Refusing to overwrite existing ${ULTRAGOAL_DIR}/${ULTRAGOAL_GOALS}; pass --force to recreate it.`);
+        }
+        const now = iso(options.now);
+        const sourceGoals = options.goals?.length
+            ? options.goals
+            : deriveGoalCandidates(options.brief);
+        const candidates = sourceGoals
+            .map((goal, index) => ({
+            id: normalizeGoalId(goal.title ?? titleFromObjective(goal.objective, `Goal ${index + 1}`), index),
+            title: goal.title ?? titleFromObjective(goal.objective, `Goal ${index + 1}`),
+            objective: goal.objective.trim(),
+            status: 'pending',
+            tokenBudget: goal.tokenBudget,
+            attempt: 0,
+            createdAt: now,
+            updatedAt: now,
+        }));
+        const plan = {
+            version: 1,
+            createdAt: now,
+            updatedAt: now,
+            briefPath: `${ULTRAGOAL_DIR}/${ULTRAGOAL_BRIEF}`,
+            goalsPath: `${ULTRAGOAL_DIR}/${ULTRAGOAL_GOALS}`,
+            ledgerPath: `${ULTRAGOAL_DIR}/${ULTRAGOAL_LEDGER}`,
+            codexGoalMode: options.codexGoalMode ?? 'aggregate',
+            goals: candidates,
+        };
+        if (plan.codexGoalMode === 'aggregate')
+            plan.codexObjective = aggregateCodexObjective(candidates);
+        await mkdir(ultragoalDir(cwd), { recursive: true });
+        await writeFile(ultragoalBriefPath(cwd), options.brief.endsWith('\n') ? options.brief : `${options.brief}\n`);
+        await writePlan(cwd, plan);
+        await writeFile(ultragoalLedgerPath(cwd), '');
+        await appendLedger(cwd, { ts: now, event: 'plan_created', message: `${candidates.length} goal(s) created` });
+        return plan;
+    });
 }
 export function summarizeUltragoalPlan(plan) {
     return {
@@ -225,6 +385,9 @@ export function summarizeUltragoalPlan(plan) {
         complete: plan.goals.filter((goal) => goal.status === 'complete').length,
         failed: plan.goals.filter((goal) => goal.status === 'failed').length,
         reviewBlocked: plan.goals.filter((goal) => goal.status === 'review_blocked').length,
+        needsUserDecision: plan.goals.filter((goal) => goal.status === 'needs_user_decision').length,
+        superseded: plan.goals.filter((goal) => goal.steeringStatus === 'superseded').length,
+        steeringBlocked: plan.goals.filter((goal) => goal.steeringStatus === 'blocked').length,
         aggregateComplete: plan.aggregateCompletion?.status === 'complete',
         activeGoalId: plan.activeGoalId,
     };
@@ -235,7 +398,34 @@ function assertNonEmpty(value, label) {
         throw new UltragoalError(`Missing ${label}.`);
     return trimmed;
 }
-function appendGoalToPlan(plan, options, now) {
+export function parseUltragoalSteeringDirective(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed || trimmed.length < 5)
+        return null;
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        if (!parsed.kind || typeof parsed.kind !== 'string')
+            return null;
+        if (!parsed.source || typeof parsed.source !== 'string')
+            return null;
+        if (!parsed.evidence || typeof parsed.evidence !== 'string')
+            return null;
+        if (!parsed.rationale || typeof parsed.rationale !== 'string')
+            return null;
+        if (!ULTRAGOAL_STEERING_MUTATION_KINDS.includes(parsed.kind))
+            return null;
+        if (!ULTRAGOAL_STEERING_SOURCES.includes(parsed.source))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function appendGoalToPlan(plan, options, nowOverride) {
+    const now = nowOverride ?? iso(options.now);
     const title = assertNonEmpty(options.title, '--title');
     const objective = assertNonEmpty(options.objective, '--objective');
     const goal = {
@@ -253,19 +443,360 @@ function appendGoalToPlan(plan, options, now) {
     return goal;
 }
 export async function addUltragoalGoal(cwd, options) {
-    const plan = await readUltragoalPlan(cwd);
-    const now = iso(options.now);
-    const goal = appendGoalToPlan(plan, options, now);
-    await writePlan(cwd, plan);
-    await appendLedger(cwd, {
-        ts: now,
-        event: 'goal_added',
-        goalId: goal.id,
-        status: goal.status,
-        evidence: options.evidence,
-        message: goal.title,
+    return withUltragoalMutationLock(cwd, async () => {
+        const plan = await readUltragoalPlan(cwd);
+        const now = iso(options.now);
+        const goal = appendGoalToPlan(plan, options);
+        await writePlan(cwd, plan);
+        await appendLedger(cwd, {
+            ts: now,
+            event: 'goal_added',
+            goalId: goal.id,
+            status: goal.status,
+            evidence: options.evidence,
+            message: goal.title,
+        });
+        return { plan, goal };
+    });
+}
+function proposalTargetIds(proposal) {
+    return proposal.targetGoalIds?.length ? proposal.targetGoalIds : (proposal.targetGoalId ? [proposal.targetGoalId] : []);
+}
+function steeringTargets(plan, proposal) {
+    return proposalTargetIds(proposal).map((id) => {
+        const goal = plan.goals.find((candidate) => candidate.id === id);
+        if (!goal)
+            throw new UltragoalError(`Unknown ultragoal id: ${id}`);
+        return goal;
+    });
+}
+function mentionsWeakenedCompletion(...values) {
+    const normalized = values.filter(Boolean).join(' ').toLowerCase();
+    return /\b(skip|bypass|weaken|remove|omit|auto[-\s]?complete|mark complete|complete faster)\b/.test(normalized)
+        && /\b(test|tests|verification|review|quality gate|complete|completion)\b/.test(normalized);
+}
+function hasProtectedSteeringPayload(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const protectedKeys = new Set([
+        'aggregateCompletion',
+        'brief',
+        'briefPath',
+        'codexObjective',
+        'constraints',
+        'completedAt',
+        'qualityGate',
+        'status',
+    ]);
+    const stack = [value];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current || typeof current !== 'object')
+            continue;
+        for (const [key, child] of Object.entries(current)) {
+            if (protectedKeys.has(key))
+                return true;
+            if (key.toLowerCase().includes('complete'))
+                return true;
+            if (child && typeof child === 'object')
+                stack.push(child);
+        }
+    }
+    return false;
+}
+function protectedIntentText(proposal) {
+    const after = proposal.after;
+    const childTexts = rawChildGoalsFromProposal(proposal).flatMap((child) => {
+        if (!child || typeof child !== 'object' || Array.isArray(child))
+            return [];
+        const candidate = child;
+        return [candidate.title, candidate.objective];
+    });
+    return [
+        proposal.title,
+        proposal.objective,
+        proposal.revisedTitle,
+        proposal.revisedObjective,
+        after?.title,
+        after?.objective,
+        proposal.rationale,
+        proposal.directiveText,
+        ...childTexts,
+    ]
+        .filter((value) => typeof value === 'string')
+        .join('\n')
+        .toLowerCase();
+}
+function rawChildGoalsFromProposal(proposal) {
+    if (Array.isArray(proposal.childGoals) && proposal.childGoals.length > 0)
+        return proposal.childGoals;
+    const after = proposal.after;
+    return Array.isArray(after?.children) ? after.children : [];
+}
+function isValidSteeringChildGoal(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const candidate = value;
+    return typeof candidate.title === 'string'
+        && candidate.title.trim().length > 0
+        && typeof candidate.objective === 'string'
+        && candidate.objective.trim().length > 0;
+}
+function childGoalsFromProposal(proposal) {
+    return rawChildGoalsFromProposal(proposal).filter(isValidSteeringChildGoal);
+}
+function pendingOrderFromProposal(proposal) {
+    if (proposal.pendingOrder?.length)
+        return proposal.pendingOrder;
+    const after = proposal.after;
+    return Array.isArray(after?.pendingGoalIds) ? after.pendingGoalIds : [];
+}
+function revisedTitleFromProposal(proposal) {
+    if (proposal.revisedTitle?.trim())
+        return proposal.revisedTitle;
+    const after = proposal.after;
+    return after?.title ?? proposal.title;
+}
+function revisedObjectiveFromProposal(proposal) {
+    if (proposal.revisedObjective?.trim())
+        return proposal.revisedObjective;
+    const after = proposal.after;
+    return after?.objective ?? proposal.objective;
+}
+export function validateUltragoalSteeringProposal(plan, proposal) {
+    const rejectedReasons = [];
+    const evidenceBackedNecessity = Boolean(proposal.evidence?.trim()) && Boolean(proposal.rationale?.trim());
+    if (!ULTRAGOAL_STEERING_MUTATION_KINDS.includes(proposal.kind))
+        rejectedReasons.push(`Invalid steering mutation kind: ${String(proposal.kind)}.`);
+    if (!ULTRAGOAL_STEERING_SOURCES.includes(proposal.source))
+        rejectedReasons.push(`Invalid steering source: ${String(proposal.source)}.`);
+    if (!evidenceBackedNecessity)
+        rejectedReasons.push('Steering requires non-empty evidence and rationale.');
+    if (hasProtectedSteeringPayload(proposal.after))
+        rejectedReasons.push('Steering payload must not edit protected objective, constraint, quality gate, or completion fields.');
+    if (/\b(?:skip|bypass|weaken|remove)\b.*\b(?:test|tests|review|verification|quality gate|complete|completion)\b|\bauto[- ]?complete\b/.test(protectedIntentText(proposal))) {
+        rejectedReasons.push('Steering must not weaken completion, quality gates, tests, reviews, or auto-complete work.');
+    }
+    if (plan.aggregateCompletion?.status === 'complete')
+        rejectedReasons.push('Cannot steer an already completed aggregate ultragoal plan.');
+    let targets = [];
+    try {
+        targets = steeringTargets(plan, proposal);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        rejectedReasons.push(message.replace(/^Unknown ultragoal id:/, 'unknown ultragoal id:'));
+    }
+    const target = targets[0];
+    if ((proposal.kind === 'split_subgoal' || proposal.kind === 'revise_pending_wording' || proposal.kind === 'mark_blocked_superseded') && !target) {
+        rejectedReasons.push(`${proposal.kind} requires a target goal id.`);
+    }
+    if ((proposal.kind === 'split_subgoal' || proposal.kind === 'revise_pending_wording') && target?.status !== 'pending') {
+        rejectedReasons.push(`${proposal.kind} can only target a pending goal.`);
+    }
+    if (proposal.kind === 'add_subgoal') {
+        if (!proposal.title?.trim() || !proposal.objective?.trim())
+            rejectedReasons.push('add_subgoal requires title and objective.');
+    }
+    if (proposal.kind === 'split_subgoal') {
+        const rawChildren = rawChildGoalsFromProposal(proposal);
+        if (rawChildren.length === 0)
+            rejectedReasons.push('split_subgoal requires replacement child goals.');
+        if (rawChildren.some((child) => !isValidSteeringChildGoal(child)))
+            rejectedReasons.push('split_subgoal children require title and objective.');
+    }
+    if (proposal.kind === 'mark_blocked_superseded') {
+        const rawChildren = rawChildGoalsFromProposal(proposal);
+        if (rawChildren.some((child) => !isValidSteeringChildGoal(child)))
+            rejectedReasons.push('mark_blocked_superseded replacement children require title and objective.');
+    }
+    if (proposal.kind === 'reorder_pending') {
+        const requested = pendingOrderFromProposal(proposal);
+        const pending = plan.goals.filter((goal) => goal.status === 'pending' && isScheduleEligible(goal)).map((goal) => goal.id);
+        if (requested.length === 0)
+            rejectedReasons.push('reorder_pending requires at least one pending goal id.');
+        if (new Set(requested).size !== requested.length)
+            rejectedReasons.push('duplicate goal id in pendingOrder.');
+        if (requested.some((id) => !pending.includes(id)))
+            rejectedReasons.push('pendingOrder contains non-pending or unknown goal.');
+    }
+    if (proposal.kind === 'revise_pending_wording') {
+        if (!revisedTitleFromProposal(proposal)?.trim() && !revisedObjectiveFromProposal(proposal)?.trim())
+            rejectedReasons.push('revise_pending_wording requires title or objective.');
+    }
+    if (proposal.kind === 'annotate_ledger' && !proposal.evidence?.trim())
+        rejectedReasons.push('annotate_ledger requires evidence.');
+    const accepted = rejectedReasons.length === 0;
+    const noEasierCompletion = !mentionsWeakenedCompletion(protectedIntentText(proposal));
+    return {
+        structuralInvariantAccepted: accepted,
+        evidenceBackedNecessity,
+        noEasierCompletion,
+        accepted,
+        rejectedReasons,
+        reasons: rejectedReasons,
+    };
+}
+export const validateSteeringProposal = validateUltragoalSteeringProposal;
+async function readSteeringLedgerEntries(cwd) {
+    try {
+        const raw = await readFile(ultragoalLedgerPath(cwd), 'utf-8');
+        return raw.split(/\r?\n/).filter(Boolean).map((line) => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}
+function cloneForAudit(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function moveGoalsAfterTarget(plan, targetId, movedIds) {
+    const moved = movedIds.map((id) => plan.goals.find((goal) => goal.id === id)).filter((goal) => Boolean(goal));
+    if (moved.length === 0)
+        return;
+    plan.goals = plan.goals.filter((goal) => !movedIds.includes(goal.id));
+    const targetIndex = plan.goals.findIndex((goal) => goal.id === targetId);
+    plan.goals.splice(targetIndex >= 0 ? targetIndex + 1 : plan.goals.length, 0, ...moved);
+}
+function applySteeringMutation(plan, proposal, now) {
+    const targets = steeringTargets(plan, proposal);
+    const target = targets[0];
+    if (proposal.kind === 'add_subgoal') {
+        const goal = appendGoalToPlan(plan, { title: proposal.title ?? '', objective: proposal.objective ?? '', evidence: proposal.evidence, now: new Date(now) });
+        return { before: undefined, after: cloneForAudit(goal) };
+    }
+    if (proposal.kind === 'split_subgoal') {
+        const before = cloneForAudit(target);
+        const children = childGoalsFromProposal(proposal).map((child) => appendGoalToPlan(plan, { ...child, evidence: proposal.evidence, now: new Date(now) }));
+        target.steeringStatus = 'superseded';
+        target.supersededBy = children.map((child) => child.id);
+        moveGoalsAfterTarget(plan, target.id, children.map((child) => child.id));
+        target.steeringEvidence = proposal.evidence;
+        target.steeringRationale = proposal.rationale;
+        target.updatedAt = now;
+        for (const child of children)
+            child.supersedes = [target.id];
+        if (plan.activeGoalId === target.id)
+            plan.activeGoalId = undefined;
+        plan.updatedAt = now;
+        return { before, after: { target: cloneForAudit(target), children: cloneForAudit(children) } };
+    }
+    if (proposal.kind === 'reorder_pending') {
+        const before = plan.goals.map((goal) => goal.id);
+        const requested = pendingOrderFromProposal(proposal);
+        const requestedSet = new Set(requested);
+        const requestedGoals = requested.map((id) => plan.goals.find((goal) => goal.id === id)).filter((goal) => Boolean(goal));
+        const remaining = plan.goals.filter((goal) => !requestedSet.has(goal.id));
+        plan.goals = [...requestedGoals, ...remaining];
+        plan.updatedAt = now;
+        return { before, after: plan.goals.map((goal) => goal.id) };
+    }
+    if (proposal.kind === 'revise_pending_wording') {
+        const before = cloneForAudit(target);
+        const revisedTitle = revisedTitleFromProposal(proposal);
+        const revisedObjective = revisedObjectiveFromProposal(proposal);
+        if (revisedTitle?.trim())
+            target.title = revisedTitle.trim();
+        if (revisedObjective?.trim())
+            target.objective = revisedObjective.trim();
+        target.steeringEvidence = proposal.evidence;
+        target.steeringRationale = proposal.rationale;
+        target.updatedAt = now;
+        plan.updatedAt = now;
+        return { before, after: cloneForAudit(target) };
+    }
+    if (proposal.kind === 'annotate_ledger') {
+        return { before: undefined, after: { evidence: proposal.evidence, rationale: proposal.rationale } };
+    }
+    if (proposal.kind === 'mark_blocked_superseded') {
+        const before = cloneForAudit(target);
+        const children = childGoalsFromProposal(proposal);
+        if (children.length > 0) {
+            const replacements = children.map((child) => appendGoalToPlan(plan, { ...child, evidence: proposal.evidence, now: new Date(now) }));
+            target.steeringStatus = 'superseded';
+            target.supersededBy = replacements.map((child) => child.id);
+            moveGoalsAfterTarget(plan, target.id, replacements.map((child) => child.id));
+            target.steeringEvidence = proposal.evidence;
+            target.steeringRationale = proposal.rationale;
+            target.updatedAt = now;
+            for (const replacement of replacements)
+                replacement.supersedes = [target.id];
+            if (plan.activeGoalId === target.id)
+                plan.activeGoalId = undefined;
+            plan.updatedAt = now;
+            return { before, after: { target: cloneForAudit(target), children: cloneForAudit(replacements) } };
+        }
+        if (plan.activeGoalId === target.id)
+            delete plan.activeGoalId;
+        target.steeringStatus = 'blocked';
+        target.blockedReason = proposal.blockedReason ?? proposal.rationale;
+        target.steeringEvidence = proposal.evidence;
+        target.steeringRationale = proposal.rationale;
+        target.updatedAt = now;
+        if (plan.activeGoalId === target.id)
+            plan.activeGoalId = undefined;
+        plan.updatedAt = now;
+        return { before, after: cloneForAudit(target) };
+    }
+    return {};
+}
+export async function steerUltragoal(cwd, proposal, options = {}) {
+    return withUltragoalMutationLock(cwd, async () => {
+        const plan = await readUltragoalPlan(cwd);
+        const existing = proposal.idempotencyKey
+            ? (await readSteeringLedgerEntries(cwd)).find((entry) => entry.event === 'steering_accepted' && (entry.idempotencyKey === proposal.idempotencyKey || entry.steering?.idempotencyKey === proposal.idempotencyKey) && entry.steering)
+            : undefined;
+        if (existing?.steering) {
+            return { plan, accepted: true, audit: { ...existing.steering, deduped: true }, rejectedReasons: [], deduped: true };
+        }
+        let invariant = validateUltragoalSteeringProposal(plan, proposal);
+        const now = iso(options.now ?? proposal.now);
+        const beforePlan = cloneForAudit(plan);
+        let mutation = {};
+        if (invariant.accepted) {
+            try {
+                mutation = applySteeringMutation(plan, proposal, now);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const rejectedReasons = [...invariant.rejectedReasons, `Steering mutation failed: ${message}`];
+                invariant = {
+                    ...invariant,
+                    accepted: false,
+                    structuralInvariantAccepted: false,
+                    rejectedReasons,
+                    reasons: rejectedReasons,
+                };
+            }
+        }
+        const audit = {
+            kind: proposal.kind,
+            source: proposal.source,
+            targetGoalIds: proposalTargetIds(proposal),
+            before: mutation.before ?? beforePlan,
+            after: mutation.after,
+            evidence: proposal.evidence,
+            rationale: proposal.rationale,
+            invariant,
+            directiveText: options.directiveText ?? proposal.directiveText,
+            promptSignature: proposal.promptSignature,
+            idempotencyKey: proposal.idempotencyKey,
+        };
+        if (invariant.accepted)
+            await writePlan(cwd, plan);
+        await appendLedger(cwd, {
+            ts: now,
+            event: invariant.accepted ? 'steering_accepted' : 'steering_rejected',
+            goalId: proposalTargetIds(proposal)[0],
+            evidence: proposal.evidence,
+            message: proposal.rationale,
+            steering: audit,
+            mutationKind: proposal.kind,
+            before: audit.before,
+            after: audit.after,
+        });
+        return { plan, accepted: invariant.accepted, audit, rejectedReasons: invariant.rejectedReasons, deduped: false };
     });
-    return { plan, goal };
 }
 function validateQualityGate(value) {
     if (!value || typeof value !== 'object') {
@@ -301,230 +832,278 @@ function validateQualityGate(value) {
     return gate;
 }
 export async function startNextUltragoal(cwd, options = {}) {
-    const plan = await readUltragoalPlan(cwd);
-    const now = iso(options.now);
-    if (plan.aggregateCompletion?.status === 'complete')
-        return { plan, goal: null, resumed: false, done: true };
-    const existing = plan.goals.find((goal) => goal.status === 'in_progress');
-    if (existing) {
-        await appendLedger(cwd, { ts: now, event: 'goal_resumed', goalId: existing.id, status: existing.status, message: 'Resuming active ultragoal' });
-        return { plan, goal: existing, resumed: true, done: false };
-    }
-    let next = plan.goals.find((goal) => goal.status === 'pending');
-    if (!next && options.retryFailed) {
-        next = plan.goals.find((goal) => goal.status === 'failed');
-        if (next)
-            await appendLedger(cwd, { ts: now, event: 'goal_retried', goalId: next.id, status: 'pending', message: next.failureReason });
-    }
-    if (!next)
-        return { plan, goal: null, resumed: false, done: isUltragoalDone(plan) };
-    next.status = 'in_progress';
-    next.attempt += 1;
-    next.startedAt = now;
-    next.failedAt = undefined;
-    next.failureReason = undefined;
-    next.updatedAt = now;
-    plan.activeGoalId = next.id;
-    plan.updatedAt = now;
-    await writePlan(cwd, plan);
-    await appendLedger(cwd, { ts: now, event: 'goal_started', goalId: next.id, status: next.status, message: `Attempt ${next.attempt}` });
-    return { plan, goal: next, resumed: false, done: false };
+    return withUltragoalMutationLock(cwd, async () => {
+        const plan = await readUltragoalPlan(cwd);
+        const now = iso(options.now);
+        if (plan.aggregateCompletion?.status === 'complete')
+            return { plan, goal: null, resumed: false, done: true };
+        const existing = plan.goals.find((goal) => goal.status === 'in_progress' && isScheduleEligibleGoal(goal));
+        if (existing) {
+            await appendLedger(cwd, { ts: now, event: 'goal_resumed', goalId: existing.id, status: existing.status, message: 'Resuming active ultragoal' });
+            return { plan, goal: existing, resumed: true, done: false };
+        }
+        let next = plan.goals.find((goal) => goal.status === 'pending' && isScheduleEligible(goal));
+        if (!next && options.retryFailed) {
+            next = plan.goals.find((goal) => goal.status === 'failed' && !goal.nonRetriable && isScheduleEligible(goal));
+            if (next)
+                await appendLedger(cwd, { ts: now, event: 'goal_retried', goalId: next.id, status: 'pending', message: next.failureReason });
+        }
+        if (!next)
+            return { plan, goal: null, resumed: false, done: isUltragoalDone(plan) };
+        next.status = 'in_progress';
+        next.attempt += 1;
+        next.startedAt = now;
+        next.failedAt = undefined;
+        next.failureReason = undefined;
+        clearGoalBlockerFields(next);
+        next.updatedAt = now;
+        plan.activeGoalId = next.id;
+        plan.updatedAt = now;
+        await writePlan(cwd, plan);
+        await appendLedger(cwd, { ts: now, event: 'goal_started', goalId: next.id, status: next.status, message: `Attempt ${next.attempt}` });
+        return { plan, goal: next, resumed: false, done: false };
+    });
 }
 export async function checkpointUltragoal(cwd, options) {
-    const plan = await readUltragoalPlan(cwd);
-    const goal = plan.goals.find((candidate) => candidate.id === options.goalId);
-    if (!goal)
-        throw new UltragoalError(`Unknown ultragoal id: ${options.goalId}`);
-    const now = iso(options.now);
-    if (options.status === 'blocked') {
-        if (goal.status !== 'in_progress') {
-            throw new UltragoalError(`Cannot record a blocked checkpoint for ${goal.id} while it is ${goal.status}; start or resume the ultragoal before recording a non-terminal blocker.`);
+    return withUltragoalMutationLock(cwd, async () => {
+        const plan = await readUltragoalPlan(cwd);
+        const goal = plan.goals.find((candidate) => candidate.id === options.goalId);
+        if (!goal)
+            throw new UltragoalError(`Unknown ultragoal id: ${options.goalId}`);
+        const now = iso(options.now);
+        if (options.status === 'blocked') {
+            if (goal.status !== 'in_progress') {
+                throw new UltragoalError(`Cannot record a blocked checkpoint for ${goal.id} while it is ${goal.status}; start or resume the ultragoal before recording a non-terminal blocker.`);
+            }
+            const snapshot = options.codexGoal === undefined ? null : parseCodexGoalSnapshot(options.codexGoal);
+            if (snapshot?.unavailableReason === 'db_schema_context_error') {
+                goal.updatedAt = now;
+                goal.failureReason = assertNonEmpty(options.evidence, '--evidence');
+                plan.activeGoalId = goal.id;
+                plan.updatedAt = now;
+                await writePlan(cwd, plan);
+                await appendLedger(cwd, {
+                    ts: now,
+                    event: 'goal_blocked',
+                    goalId: goal.id,
+                    status: goal.status,
+                    evidence: options.evidence,
+                    codexGoal: options.codexGoal,
+                    message: 'Codex get_goal was unavailable due to a DB/schema/context error; strict completion reconciliation is deferred until get_goal works.',
+                });
+                return plan;
+            }
+            if (!snapshot?.available) {
+                throw new UltragoalError('Blocked ultragoal checkpoints require either a get_goal snapshot for the completed legacy Codex goal that blocked create_goal, or an unavailable get_goal error JSON for a Codex DB/schema/context failure; pass --codex-goal-json.');
+            }
+            if (snapshot.status !== 'complete') {
+                throw new UltragoalError(`Cannot record a blocked ultragoal checkpoint while the existing Codex goal is ${snapshot.status ?? 'unknown'}; strict objective mismatch protection remains required for active or incomplete goals.`);
+            }
+            if (!snapshot.objective) {
+                throw new UltragoalError('Blocked ultragoal checkpoint Codex snapshot is missing objective text.');
+            }
+            if (normalizeObjective(snapshot.objective) === normalizeObjective(expectedCodexObjective(plan, goal))) {
+                throw new UltragoalError('Blocked ultragoal checkpoint is only for a different completed legacy Codex goal; complete this ultragoal with --status complete after its audit passes.');
+            }
+            goal.updatedAt = now;
+            plan.activeGoalId = goal.id;
+            plan.updatedAt = now;
+            await writePlan(cwd, plan);
+            await appendLedger(cwd, {
+                ts: now,
+                event: 'goal_blocked',
+                goalId: goal.id,
+                status: goal.status,
+                evidence: options.evidence,
+                codexGoal: options.codexGoal,
+            });
+            return plan;
         }
-        const snapshot = options.codexGoal === undefined ? null : parseCodexGoalSnapshot(options.codexGoal);
-        if (!snapshot?.available) {
-            throw new UltragoalError('Blocked ultragoal checkpoints require a get_goal snapshot for the completed legacy Codex goal that blocked create_goal; pass --codex-goal-json.');
+        let aggregateCompletion;
+        if (options.status === 'complete') {
+            const expectedObjective = expectedCodexObjective(plan, goal);
+            const aggregateMode = codexGoalMode(plan) === 'aggregate';
+            const finalRunCheckpoint = isFinalRunCompletionCandidate(plan, goal);
+            const snapshot = options.codexGoal === undefined ? null : parseCodexGoalSnapshot(options.codexGoal);
+            const reconciliation = reconcileCodexGoalSnapshot(snapshot, {
+                expectedObjective,
+                acceptedObjectives: aggregateMode ? compatibleCodexObjectives(plan) : undefined,
+                allowedStatuses: aggregateMode
+                    ? (finalRunCheckpoint && !options.allowActiveFinalCodexGoal ? ['complete'] : ['active'])
+                    : ['complete'],
+                requireSnapshot: true,
+                requireComplete: !aggregateMode || (finalRunCheckpoint && !options.allowActiveFinalCodexGoal),
+            });
+            if (!reconciliation.ok) {
+                const completedTaskScopedAggregateSnapshot = snapshot?.available
+                    && snapshot.status === 'complete'
+                    && Boolean(snapshot.objective)
+                    && normalizeObjective(snapshot.objective ?? '') !== normalizeObjective(expectedObjective)
+                    && await canReconcileCompletedTaskScopedAggregateSnapshot(cwd, plan, goal, snapshot.objective ?? '', options.evidence);
+                if (completedTaskScopedAggregateSnapshot) {
+                    aggregateCompletion = {
+                        status: 'complete',
+                        completedAt: now,
+                        evidence: assertNonEmpty(options.evidence, '--evidence'),
+                        codexGoal: options.codexGoal,
+                    };
+                }
+                else {
+                    const taskScopedRequirement = aggregateMode && snapshot?.status === 'complete' && Boolean(snapshot.objective)
+                        ? ' Completed task-scoped aggregate reconciliation requires the checkpoint goal to be the active in-progress OMX goal, evidence that names that active OMX goal id, names .omx/ultragoal/goals.json or ledger.jsonl, includes completed implementation plus validation/review evidence, and a get_goal objective that maps to the ultragoal brief/artifact.'
+                        : '';
+                    const remediation = reconciliation.snapshot.available
+                        && reconciliation.snapshot.status === 'complete'
+                        && Boolean(reconciliation.snapshot.objective)
+                        && normalizeObjective(reconciliation.snapshot.objective ?? '') !== normalizeObjective(expectedObjective)
+                        ? ` ${buildCompletedLegacyGoalRemediation(goal)}`
+                        : reconciliation.snapshot.unavailableReason === 'db_schema_context_error'
+                            ? ` ${buildUnavailableCodexGoalRemediation(goal)}`
+                            : '';
+                    throw new UltragoalError(`${formatCodexGoalReconciliation(reconciliation)}${taskScopedRequirement}${remediation}`);
+                }
+            }
+            if (finalRunCheckpoint && !options.allowActiveFinalCodexGoal)
+                goal.evidence = options.evidence;
         }
-        if (snapshot.status !== 'complete') {
-            throw new UltragoalError(`Cannot record a blocked ultragoal checkpoint while the existing Codex goal is ${snapshot.status ?? 'unknown'}; strict objective mismatch protection remains required for active or incomplete goals.`);
+        const qualityGate = options.status === 'complete' && (aggregateCompletion !== undefined || (isFinalRunCompletionCandidate(plan, goal) && !options.allowActiveFinalCodexGoal))
+            ? validateQualityGate(options.qualityGate)
+            : undefined;
+        if (aggregateCompletion) {
+            plan.aggregateCompletion = aggregateCompletion;
+            if (plan.activeGoalId === goal.id)
+                delete plan.activeGoalId;
+            plan.updatedAt = now;
+            await writePlan(cwd, plan);
+            await appendLedger(cwd, {
+                ts: now,
+                event: 'aggregate_completed',
+                goalId: goal.id,
+                status: goal.status,
+                evidence: options.evidence,
+                codexGoal: options.codexGoal,
+                qualityGate,
+                message: 'Aggregate ultragoal plan completed via task-scoped Codex goal snapshot; microgoal ledger progress remains independent.',
+            });
+            return plan;
         }
-        if (!snapshot.objective) {
-            throw new UltragoalError('Blocked ultragoal checkpoint Codex snapshot is missing objective text.');
+        goal.status = options.status;
+        goal.updatedAt = now;
+        if (options.status === 'complete') {
+            goal.completedAt = now;
+            goal.evidence = options.evidence;
+            goal.failureReason = undefined;
+            goal.failedAt = undefined;
+            clearGoalBlockerFields(goal);
+            if (plan.activeGoalId === goal.id)
+                delete plan.activeGoalId;
         }
-        if (normalizeObjective(snapshot.objective) === normalizeObjective(expectedCodexObjective(plan, goal))) {
-            throw new UltragoalError('Blocked ultragoal checkpoint is only for a different completed legacy Codex goal; complete this ultragoal with --status complete after its audit passes.');
+        else {
+            const blocker = classifyExternalAuthorizationBlocker(options.evidence);
+            const previousEntries = blocker ? await readSteeringLedgerEntries(cwd) : [];
+            const occurrenceCount = blocker ? sameBlockerOccurrences(previousEntries, goal.id, blocker.signature) + 1 : 0;
+            const shouldCircuitBreak = blocker !== null && occurrenceCount >= 3;
+            goal.failedAt = now;
+            goal.failureReason = options.evidence;
+            goal.blockerSignature = blocker?.signature;
+            goal.blockerOccurrenceCount = blocker ? occurrenceCount : undefined;
+            goal.requiredExternalDecision = blocker?.requiredDecision;
+            goal.nonRetriable = shouldCircuitBreak || undefined;
+            if (shouldCircuitBreak) {
+                goal.status = 'needs_user_decision';
+                goal.blockedReason = options.evidence;
+            }
+            if (plan.activeGoalId === goal.id)
+                delete plan.activeGoalId;
         }
-        goal.updatedAt = now;
-        plan.activeGoalId = goal.id;
         plan.updatedAt = now;
         await writePlan(cwd, plan);
+        const blockerEvent = goal.status === 'needs_user_decision';
         await appendLedger(cwd, {
             ts: now,
-            event: 'goal_blocked',
+            event: options.status === 'complete' ? 'goal_completed' : blockerEvent ? 'goal_needs_user_decision' : 'goal_failed',
             goalId: goal.id,
             status: goal.status,
             evidence: options.evidence,
             codexGoal: options.codexGoal,
+            qualityGate,
+            blockerSignature: goal.blockerSignature,
+            blockerOccurrenceCount: goal.blockerOccurrenceCount,
+            requiredExternalDecision: goal.requiredExternalDecision,
+            message: blockerEvent
+                ? `Blocked on repeated external authorization. Required decision: ${goal.requiredExternalDecision}.`
+                : undefined,
         });
         return plan;
-    }
-    let aggregateCompletion;
-    if (options.status === 'complete') {
+    });
+}
+export async function recordFinalReviewBlockers(cwd, options) {
+    return withUltragoalMutationLock(cwd, async () => {
+        const plan = await readUltragoalPlan(cwd);
+        const goal = plan.goals.find((candidate) => candidate.id === options.goalId);
+        if (!goal)
+            throw new UltragoalError(`Unknown ultragoal id: ${options.goalId}`);
+        assertNonEmpty(options.evidence, '--evidence');
+        if (goal.status !== 'in_progress') {
+            throw new UltragoalError(`Cannot record final review blockers for ${goal.id} while it is ${goal.status}; start or resume the ultragoal first.`);
+        }
+        if (!isFinalRunCompletionCandidate(plan, goal)) {
+            throw new UltragoalError(`Cannot record final review blockers for ${goal.id}; it is not the only unresolved ultragoal story.`);
+        }
+        const now = iso(options.now);
         const expectedObjective = expectedCodexObjective(plan, goal);
         const aggregateMode = codexGoalMode(plan) === 'aggregate';
-        const finalRunCheckpoint = isFinalRunCompletionCandidate(plan, goal);
-        const snapshot = options.codexGoal === undefined ? null : parseCodexGoalSnapshot(options.codexGoal);
-        const reconciliation = reconcileCodexGoalSnapshot(snapshot, {
+        const reconciliation = reconcileCodexGoalSnapshot(options.codexGoal === undefined ? null : parseCodexGoalSnapshot(options.codexGoal), {
             expectedObjective,
-            allowedStatuses: aggregateMode
-                ? (finalRunCheckpoint && !options.allowActiveFinalCodexGoal ? ['complete'] : ['active'])
-                : ['complete'],
+            acceptedObjectives: aggregateMode ? compatibleCodexObjectives(plan) : undefined,
+            allowedStatuses: ['active'],
             requireSnapshot: true,
-            requireComplete: !aggregateMode || (finalRunCheckpoint && !options.allowActiveFinalCodexGoal),
+            requireComplete: false,
         });
         if (!reconciliation.ok) {
-            const completedTaskScopedAggregateSnapshot = snapshot?.available
-                && snapshot.status === 'complete'
-                && Boolean(snapshot.objective)
-                && normalizeObjective(snapshot.objective ?? '') !== normalizeObjective(expectedObjective)
-                && await canReconcileCompletedTaskScopedAggregateSnapshot(cwd, plan, goal, snapshot.objective ?? '', options.evidence);
-            if (completedTaskScopedAggregateSnapshot) {
-                aggregateCompletion = {
-                    status: 'complete',
-                    completedAt: now,
-                    evidence: assertNonEmpty(options.evidence, '--evidence'),
-                    codexGoal: options.codexGoal,
-                };
-            }
-            else {
-                const taskScopedRequirement = aggregateMode && snapshot?.status === 'complete' && Boolean(snapshot.objective)
-                    ? ' Completed task-scoped aggregate reconciliation requires the checkpoint goal to be the active in-progress OMX goal, evidence that names that active OMX goal id, names .omx/ultragoal/goals.json or ledger.jsonl, includes completed implementation plus validation/review evidence, and a get_goal objective that maps to the ultragoal brief/artifact.'
-                    : '';
-                const remediation = reconciliation.snapshot.available
-                    && reconciliation.snapshot.status === 'complete'
-                    && Boolean(reconciliation.snapshot.objective)
-                    && normalizeObjective(reconciliation.snapshot.objective ?? '') !== normalizeObjective(expectedObjective)
-                    ? ` ${buildCompletedLegacyGoalRemediation(goal)}`
-                    : '';
-                throw new UltragoalError(`${formatCodexGoalReconciliation(reconciliation)}${taskScopedRequirement}${remediation}`);
-            }
+            throw new UltragoalError(formatCodexGoalReconciliation(reconciliation));
         }
-        if (finalRunCheckpoint && !options.allowActiveFinalCodexGoal)
-            goal.evidence = options.evidence;
-    }
-    const qualityGate = options.status === 'complete' && (aggregateCompletion !== undefined || (isFinalRunCompletionCandidate(plan, goal) && !options.allowActiveFinalCodexGoal))
-        ? validateQualityGate(options.qualityGate)
-        : undefined;
-    if (aggregateCompletion) {
-        plan.aggregateCompletion = aggregateCompletion;
+        const addedGoal = appendGoalToPlan(plan, { ...options, now: options.now });
+        goal.status = 'review_blocked';
+        goal.reviewBlockedAt = now;
+        goal.updatedAt = now;
+        goal.completedAt = undefined;
+        goal.failedAt = undefined;
+        goal.failureReason = undefined;
+        goal.evidence = options.evidence;
         if (plan.activeGoalId === goal.id)
             delete plan.activeGoalId;
         plan.updatedAt = now;
         await writePlan(cwd, plan);
         await appendLedger(cwd, {
             ts: now,
-            event: 'aggregate_completed',
+            event: 'final_review_failed',
             goalId: goal.id,
             status: goal.status,
             evidence: options.evidence,
             codexGoal: options.codexGoal,
-            qualityGate,
-            message: 'Aggregate ultragoal plan completed via task-scoped Codex goal snapshot; microgoal ledger progress remains independent.',
+            message: aggregateMode
+                ? 'Final aggregate code-review was not clean; blocker story was appended while Codex goal remains active.'
+                : 'Final per-story code-review was not clean; blocker story was appended and may require an available Codex goal context.',
         });
-        return plan;
-    }
-    goal.status = options.status;
-    goal.updatedAt = now;
-    if (options.status === 'complete') {
-        goal.completedAt = now;
-        goal.evidence = options.evidence;
-        goal.failureReason = undefined;
-        goal.failedAt = undefined;
-        if (plan.activeGoalId === goal.id)
-            delete plan.activeGoalId;
-    }
-    else {
-        goal.failedAt = now;
-        goal.failureReason = options.evidence;
-        if (plan.activeGoalId === goal.id)
-            delete plan.activeGoalId;
-    }
-    plan.updatedAt = now;
-    await writePlan(cwd, plan);
-    await appendLedger(cwd, {
-        ts: now,
-        event: options.status === 'complete' ? 'goal_completed' : 'goal_failed',
-        goalId: goal.id,
-        status: goal.status,
-        evidence: options.evidence,
-        codexGoal: options.codexGoal,
-        qualityGate,
-    });
-    return plan;
-}
-export async function recordFinalReviewBlockers(cwd, options) {
-    const plan = await readUltragoalPlan(cwd);
-    const goal = plan.goals.find((candidate) => candidate.id === options.goalId);
-    if (!goal)
-        throw new UltragoalError(`Unknown ultragoal id: ${options.goalId}`);
-    assertNonEmpty(options.evidence, '--evidence');
-    if (goal.status !== 'in_progress') {
-        throw new UltragoalError(`Cannot record final review blockers for ${goal.id} while it is ${goal.status}; start or resume the ultragoal first.`);
-    }
-    if (!isFinalRunCompletionCandidate(plan, goal)) {
-        throw new UltragoalError(`Cannot record final review blockers for ${goal.id}; it is not the only unresolved ultragoal story.`);
-    }
-    const now = iso(options.now);
-    const expectedObjective = expectedCodexObjective(plan, goal);
-    const aggregateMode = codexGoalMode(plan) === 'aggregate';
-    const reconciliation = reconcileCodexGoalSnapshot(options.codexGoal === undefined ? null : parseCodexGoalSnapshot(options.codexGoal), {
-        expectedObjective,
-        allowedStatuses: ['active'],
-        requireSnapshot: true,
-        requireComplete: false,
-    });
-    if (!reconciliation.ok) {
-        throw new UltragoalError(formatCodexGoalReconciliation(reconciliation));
-    }
-    const addedGoal = appendGoalToPlan(plan, options, now);
-    goal.status = 'review_blocked';
-    goal.reviewBlockedAt = now;
-    goal.updatedAt = now;
-    goal.completedAt = undefined;
-    goal.failedAt = undefined;
-    goal.failureReason = undefined;
-    goal.evidence = options.evidence;
-    if (plan.activeGoalId === goal.id)
-        delete plan.activeGoalId;
-    plan.updatedAt = now;
-    await writePlan(cwd, plan);
-    await appendLedger(cwd, {
-        ts: now,
-        event: 'final_review_failed',
-        goalId: goal.id,
-        status: goal.status,
-        evidence: options.evidence,
-        codexGoal: options.codexGoal,
-        message: aggregateMode
-            ? 'Final aggregate code-review was not clean; blocker story was appended while Codex goal remains active.'
-            : 'Final per-story code-review was not clean; blocker story was appended and may require a fresh/available Codex goal context.',
-    });
-    await appendLedger(cwd, {
-        ts: now,
-        event: 'goal_added',
-        goalId: addedGoal.id,
-        status: addedGoal.status,
-        evidence: options.evidence,
-        message: addedGoal.title,
-    });
-    await appendLedger(cwd, {
-        ts: now,
-        event: 'goal_review_blocked',
-        goalId: goal.id,
-        status: goal.status,
-        evidence: options.evidence,
-        codexGoal: options.codexGoal,
+        await appendLedger(cwd, {
+            ts: now,
+            event: 'goal_added',
+            goalId: addedGoal.id,
+            status: addedGoal.status,
+            evidence: options.evidence,
+            message: addedGoal.title,
+        });
+        await appendLedger(cwd, {
+            ts: now,
+            event: 'goal_review_blocked',
+            goalId: goal.id,
+            status: goal.status,
+            evidence: options.evidence,
+            codexGoal: options.codexGoal,
+        });
+        return { plan, blockedGoal: goal, addedGoal };
     });
-    return { plan, blockedGoal: goal, addedGoal };
 }
 export function buildCodexGoalInstruction(goal, plan) {
     if (codexGoalMode(plan) === 'aggregate')
@@ -546,7 +1125,8 @@ function buildPerStoryCodexGoalInstruction(goal, plan) {
         'Codex goal integration constraints:',
         '- First call get_goal. If no active goal exists, call create_goal with the payload below.',
         '- If a different active Codex goal exists, finish/checkpoint that goal before starting this ultragoal.',
-        '- If get_goal returns a different completed legacy/thread goal and create_goal rejects because this thread already has a completed goal, continue this ultragoal in a fresh Codex thread (same repo/worktree) and create the payload there.',
+        '- Ultragoal cannot call /goal clear from the model/shell tool surface. For another per-story goal in the same session/thread after a completed Codex goal, manually run /goal clear in the Codex UI before creating the next goal.',
+        '- If get_goal returns a different completed legacy/thread goal and create_goal rejects because this thread already has a completed goal, continue only from a Codex goal context with no active/completed conflicting goal in the same repo/worktree and create the payload there.',
         `- To preserve the durable ledger before switching threads, record the non-terminal blocker without failing this goal: omx ultragoal checkpoint --goal-id ${goal.id} --status blocked --evidence "<completed legacy Codex goal blocks create_goal in this thread>" --codex-goal-json "<get_goal JSON or path>"`,
         '- Work only this goal until its completion audit passes.',
         finalStory
@@ -559,7 +1139,7 @@ function buildPerStoryCodexGoalInstruction(goal, plan) {
             ? `  omx ultragoal record-review-blockers --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>"`
             : `  omx ultragoal checkpoint --goal-id ${goal.id} --status complete --evidence "<tests/files/PR evidence>" --codex-goal-json "<fresh get_goal JSON or path>"`,
         finalStory
-            ? '- In legacy per-story mode, the blocker story may require a fresh/available Codex goal context because this story remains an active incomplete Codex goal; do not claim it is complete.'
+            ? '- In legacy per-story mode, the blocker story may require an available Codex goal context because this story remains an active incomplete Codex goal; do not claim it is complete.'
             : null,
         finalStory
             ? '- If final $code-review is clean (APPROVE + CLEAR), call update_goal({status: "complete"}), call get_goal again, then checkpoint with --quality-gate-json:'
@@ -592,6 +1172,7 @@ function buildAggregateCodexGoalInstruction(goal, plan) {
         '- First call get_goal. If no active goal exists, call create_goal with the aggregate payload below.',
         '- If get_goal reports the same aggregate objective as active, continue this OMX story without creating a new Codex goal.',
         '- If a different active or incomplete Codex goal exists, finish/checkpoint that goal before starting this ultragoal; do not replace hidden Codex state from the shell.',
+        '- Ultragoal does not call /goal clear. After a completed aggregate run, manually run /goal clear in the Codex UI before starting another ultragoal run in the same session/thread.',
         finalStory
             ? '- This is the final pending story: run the mandatory final ai-slop-cleaner pass, rerun verification, and run $code-review before any update_goal call.'
             : '- This is not the final story: do not call update_goal yet; the aggregate Codex goal must remain active while later OMX stories remain.',