oh-my-codex 0.20.3 → 0.21.0

package/dist/ultragoal/artifacts.js

@@ -1,8 +1,10 @@
 import { existsSync } from 'node:fs';
 import { appendFile, mkdir, open, readFile, rename, rm, writeFile } from 'node:fs/promises';
-import { join, relative } from 'node:path';
+import { isAbsolute, join, relative } from 'node:path';
+import { normalizeSessionId, resolveWritableStateScope, WRITABLE_STATE_SCOPE_ERRORS } from '../mcp/state-paths.js';
 import { formatCodexGoalReconciliation, buildCompletedCodexGoalRemediation, parseCodexGoalSnapshot, reconcileCodexGoalSnapshot, } from '../goal-workflows/codex-goal-snapshot.js';
 import { LEADER_CONDUCTOR_BLOCK, buildRoleRoutingUnavailableGuidance, buildUnsupportedNativeSubagentGuidance, } from '../leader/contract.js';
+import { findGitLayout } from '../utils/git-layout.js';
 export const ULTRAGOAL_DIR = '.omx/ultragoal';
 export const ULTRAGOAL_BRIEF = 'brief.md';
 export const ULTRAGOAL_GOALS = 'goals.json';
@@ -41,6 +43,25 @@ export function ultragoalLedgerPath(cwd) {
 function repoRelative(cwd, path) {
     return relative(cwd, path).split('\\').join('/');
 }
+/**
+ * Repo-root-relative prefix for the Ultragoal state directory selected by `cwd`.
+ *
+ * Returns `''` for repository-root launches and for any cwd we cannot bind to a
+ * git worktree root, so root-level behavior stays byte-identical to a plain
+ * `.omx/ultragoal` reference.
+ */
+export function ultragoalStatePathPrefix(cwd) {
+    const worktreeRoot = findGitLayout(cwd)?.worktreeRoot;
+    if (!worktreeRoot)
+        return '';
+    const prefix = repoRelative(worktreeRoot, cwd);
+    if (!prefix || prefix.startsWith('../') || prefix === '..' || isAbsolute(prefix))
+        return '';
+    return prefix;
+}
+function prefixedStatePath(prefix, artifact) {
+    return `${prefix ? `${prefix}/` : ''}${ULTRAGOAL_DIR}/${artifact}`;
+}
 function cleanLine(line) {
     return line.replace(/^\s*(?:[-*+]\s+|\d+[.)]\s+)/, '').trim();
 }
@@ -284,6 +305,7 @@ function unresolvedReviewBlockedGoals(plan) {
 }
 function isDesignatedReviewBlockerResolver(goal, parent) {
     return parent?.status === 'review_blocked'
+        && parent.id !== goal.id
         && goal.resolvesReviewBlockedGoalId === parent.id
         && parent.reviewBlockerResolution?.resolverGoalId === goal.id;
 }
@@ -295,6 +317,31 @@ function canUseCleanFinalResolverPathForReviewBlockedParent(plan, goal, finalRun
         && !allowActiveFinalCodexGoal
         && isDesignatedReviewBlockerResolver(goal, unresolvedReviewBlocked[0]);
 }
+function hasReciprocalReviewBlockerResolver(goal, plan) {
+    const resolverId = goal.reviewBlockerResolution?.resolverGoalId;
+    if (!resolverId)
+        return false;
+    const resolvers = plan.goals.filter((candidate) => candidate.id === resolverId);
+    if (resolvers.length !== 1)
+        return false;
+    return resolvers[0].resolvesReviewBlockedGoalId === goal.id;
+}
+function hasUniqueGoalIds(plan) {
+    return new Set(plan.goals.map((candidate) => candidate.id)).size === plan.goals.length;
+}
+function canPersistNormalFinalAggregateCompletion(plan, goal, finalRunCheckpoint, allowActiveFinalCodexGoal) {
+    if (!finalRunCheckpoint || allowActiveFinalCodexGoal)
+        return false;
+    if (!hasUniqueGoalIds(plan))
+        return false;
+    if (!isScheduleEligible(goal))
+        return false;
+    if (goal.status !== 'in_progress' || plan.activeGoalId !== goal.id)
+        return false;
+    if (unresolvedReviewBlockedGoals(plan).length === 0)
+        return true;
+    return canUseCleanFinalResolverPathForReviewBlockedParent(plan, goal, finalRunCheckpoint, allowActiveFinalCodexGoal);
+}
 async function canReconcileCompletedTaskScopedAggregateSnapshot(cwd, plan, goal, snapshotObjective, evidence) {
     if (codexGoalMode(plan) !== 'aggregate')
         return false;
@@ -351,10 +398,14 @@ function isResolvedStatus(status) {
 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;
+export const ULTRAGOAL_AGGREGATE_CODEX_OBJECTIVE = buildAggregateCodexObjective('');
+function buildAggregateCodexObjective(statePathPrefix) {
+    return `Complete the durable ultragoal plan in ${prefixedStatePath(statePathPrefix, ULTRAGOAL_GOALS)}, including later accepted/appended stories, under the original brief constraints; use ${prefixedStatePath(statePathPrefix, ULTRAGOAL_LEDGER)} as the audit trail.`;
+}
+function aggregateCodexObjective(statePathPrefix) {
+    const objective = buildAggregateCodexObjective(statePathPrefix);
+    if (objective.length <= 4000)
+        return objective;
     throw new UltragoalError('Generated aggregate Codex objective exceeds the 4,000 character goal limit.');
 }
 function isLegacyEnumeratedAggregateObjective(objective) {
@@ -365,11 +416,12 @@ function isLegacyEnumeratedAggregateObjective(objective) {
 }
 function compatibleCodexObjectives(plan) {
     return (plan.codexObjectiveAliases ?? [])
-        .filter((objective) => isLegacyEnumeratedAggregateObjective(objective));
+        .filter((objective) => isLegacyEnumeratedAggregateObjective(objective)
+        || objective === ULTRAGOAL_AGGREGATE_CODEX_OBJECTIVE);
 }
 function expectedCodexObjective(plan, goal) {
     return codexGoalMode(plan) === 'aggregate'
-        ? (plan.codexObjective ?? aggregateCodexObjective(plan.goals))
+        ? (plan.codexObjective ?? aggregateCodexObjective(plan.statePathPrefix ?? ''))
         : goal.objective;
 }
 function isSupersededResolved(goal, plan) {
@@ -389,6 +441,8 @@ function isReviewBlockedResolved(goal, plan) {
     const resolverId = goal.reviewBlockerResolution?.resolverGoalId;
     if (!resolverId || goal.reviewBlockerResolution?.status !== 'complete')
         return false;
+    if (!hasReciprocalReviewBlockerResolver(goal, plan))
+        return false;
     const resolver = plan.goals.find((candidate) => candidate.id === resolverId);
     return resolver?.status === 'complete';
 }
@@ -479,7 +533,61 @@ function normalizeGoalId(title, index) {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-async function withUltragoalMutationLock(cwd, operation) {
+/**
+ * Mutation entry and post-lock acquisition each perform a point-in-time
+ * writable-authority check. A SessionStart publication can still occur after
+ * the second check and before a filesystem write; unrelated resolver failures
+ * propagate and block the mutation.
+ */
+export async function assertUltragoalWritableLifecycleAuthority(cwd, options = {}) {
+    try {
+        const suppliedEnvironmentSessionId = process.env.OMX_SESSION_ID?.trim();
+        const scope = await resolveWritableStateScope(cwd);
+        if (options.allowUnboundEnvironment === false
+            && suppliedEnvironmentSessionId
+            && !normalizeSessionId(suppliedEnvironmentSessionId)) {
+            throw new Error(WRITABLE_STATE_SCOPE_ERRORS.unboundEnvironment);
+        }
+        return {
+            kind: 'resolved',
+            source: scope.source,
+            sessionId: scope.sessionId,
+            stateDir: scope.stateDir,
+        };
+    }
+    catch (error) {
+        // Existing-plan mutators keep the documented unbound compatibility path.
+        // Bootstrap callers opt out so failed state activation cannot create a new durable plan.
+        if (error instanceof Error
+            && error.message === WRITABLE_STATE_SCOPE_ERRORS.unboundEnvironment
+            && options.allowUnboundEnvironment !== false) {
+            return { kind: 'no-pointer-compat' };
+        }
+        if (error instanceof Error
+            && (error.message === WRITABLE_STATE_SCOPE_ERRORS.unusableSession
+                || error.message === WRITABLE_STATE_SCOPE_ERRORS.unboundEnvironment)) {
+            throw new UltragoalError(`Refusing a durable ultragoal mutation before writable lifecycle authority is restored: ${error.message} Restore the authoritative session binding so OMX_SESSION_ID matches the current session.json before retrying; see docs/troubleshooting.md (stale session pointer recovery).`);
+        }
+        throw error;
+    }
+}
+function writableAuthorityEquals(beforeLock, afterLock) {
+    if (beforeLock.kind !== afterLock.kind)
+        return false;
+    if (beforeLock.kind === 'no-pointer-compat')
+        return true;
+    const resolvedAfterLock = afterLock;
+    return beforeLock.source === resolvedAfterLock.source
+        && beforeLock.sessionId === resolvedAfterLock.sessionId
+        && beforeLock.stateDir === resolvedAfterLock.stateDir;
+}
+function describeWritableAuthority(authority) {
+    return authority.kind === 'no-pointer-compat'
+        ? 'no-pointer-compat'
+        : `resolved(source=${authority.source}, sessionId=${authority.sessionId ?? 'undefined'}, stateDir=${authority.stateDir})`;
+}
+async function withUltragoalMutationLock(cwd, operation, options = {}) {
+    const beforeLock = await assertUltragoalWritableLifecycleAuthority(cwd, options);
     await mkdir(ultragoalDir(cwd), { recursive: true });
     const lockPath = join(ultragoalDir(cwd), ULTRAGOAL_MUTATION_LOCK);
     let handle;
@@ -500,6 +608,13 @@ async function withUltragoalMutationLock(cwd, operation) {
         throw new UltragoalError(`Timed out waiting for ultragoal mutation lock at ${repoRelative(cwd, lockPath)}.`);
     }
     try {
+        // The post-lock comparison addresses pointer changes while waiting for this
+        // lock only. A SessionStart publication can still land after it and before
+        // the operation's filesystem writes.
+        const afterLock = await assertUltragoalWritableLifecycleAuthority(cwd, options);
+        if (!writableAuthorityEquals(beforeLock, afterLock)) {
+            throw new UltragoalError(`Refusing durable ultragoal mutation after writable lifecycle authority drift while waiting for the mutation lock: before lock ${describeWritableAuthority(beforeLock)}; after lock ${describeWritableAuthority(afterLock)}.`);
+        }
         return await operation();
     }
     finally {
@@ -512,7 +627,8 @@ async function appendLedger(cwd, entry) {
     const path = ultragoalLedgerPath(cwd);
     await appendFile(path, `${JSON.stringify(entry)}\n`);
 }
-export async function readUltragoalPlan(cwd) {
+/** Pure plan read: no durable writes, no migration. */
+async function readUltragoalPlanFile(cwd) {
     const path = ultragoalGoalsPath(cwd);
     let raw;
     try {
@@ -525,23 +641,63 @@ 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;
 }
+/**
+ * Pure, lock-free plan read for read-only surfaces such as
+ * `omx ultragoal status`: never migrates, never writes, and is therefore safe
+ * for Team workers. Durable legacy migration only happens through
+ * readUltragoalPlan or the mutators, under the mutation lock and authority gate.
+ */
+export async function readUltragoalPlanSnapshot(cwd) {
+    return readUltragoalPlanFile(cwd);
+}
+function requiresCanonicalStatePathMigration(plan, statePathPrefix) {
+    return statePathPrefix !== '' && plan.codexObjective === ULTRAGOAL_AGGREGATE_CODEX_OBJECTIVE;
+}
+function requiresAggregateObjectiveMigration(plan, statePathPrefix) {
+    if (codexGoalMode(plan) !== 'aggregate')
+        return false;
+    return isLegacyEnumeratedAggregateObjective(plan.codexObjective)
+        || requiresCanonicalStatePathMigration(plan, statePathPrefix);
+}
+/** Durable legacy-objective migration; caller MUST hold the mutation lock. */
+async function migrateAggregateObjectiveUnderLock(cwd, parsed) {
+    const statePathPrefix = ultragoalStatePathPrefix(cwd);
+    if (!requiresAggregateObjectiveMigration(parsed, statePathPrefix))
+        return parsed;
+    const canonicalStatePathMigration = requiresCanonicalStatePathMigration(parsed, statePathPrefix);
+    const previousObjective = parsed.codexObjective;
+    const now = iso();
+    parsed.codexObjective = aggregateCodexObjective(statePathPrefix);
+    parsed.statePathPrefix = statePathPrefix === '' ? undefined : statePathPrefix;
+    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: canonicalStatePathMigration
+            ? 'Migrated the cwd-relative aggregate Codex objective to canonical repo-root-relative state paths.'
+            : 'Migrated legacy enumerated aggregate Codex objective to the stable pointer objective.',
+        before: { codexObjective: previousObjective },
+        after: { codexObjective: parsed.codexObjective },
+    });
+    return parsed;
+}
+/** Locked plan read for mutators that already hold the mutation lock. */
+async function readUltragoalPlanUnderLock(cwd) {
+    return migrateAggregateObjectiveUnderLock(cwd, await readUltragoalPlanFile(cwd));
+}
+export async function readUltragoalPlan(cwd) {
+    const parsed = await readUltragoalPlanFile(cwd);
+    if (!requiresAggregateObjectiveMigration(parsed, ultragoalStatePathPrefix(cwd)))
+        return parsed;
+    // The legacy objective migration is a durable story transition: it requires
+    // writable lifecycle authority and the mutation lock, and re-reads the plan
+    // under the lock so a concurrent mutator cannot be clobbered or duplicated.
+    return withUltragoalMutationLock(cwd, async () => readUltragoalPlanUnderLock(cwd));
+}
 async function writePlan(cwd, plan) {
     await mkdir(ultragoalDir(cwd), { recursive: true });
     const path = ultragoalGoalsPath(cwd);
@@ -579,15 +735,19 @@ export async function createUltragoalPlan(cwd, options) {
             codexGoalMode: options.codexGoalMode ?? 'aggregate',
             goals: candidates,
         };
-        if (plan.codexGoalMode === 'aggregate')
-            plan.codexObjective = aggregateCodexObjective(candidates);
+        if (plan.codexGoalMode === 'aggregate') {
+            const statePathPrefix = ultragoalStatePathPrefix(cwd);
+            if (statePathPrefix !== '')
+                plan.statePathPrefix = statePathPrefix;
+            plan.codexObjective = aggregateCodexObjective(statePathPrefix);
+        }
         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;
-    });
+    }, { allowUnboundEnvironment: false });
 }
 export function summarizeUltragoalPlan(plan) {
     const activeReviewBlocked = plan.goals.filter((goal) => goal.status === 'review_blocked' && !isReviewBlockedResolved(goal, plan)).length;
@@ -660,7 +820,10 @@ function appendGoalToPlan(plan, options, nowOverride) {
 }
 export async function addUltragoalGoal(cwd, options) {
     return withUltragoalMutationLock(cwd, async () => {
-        const plan = await readUltragoalPlan(cwd);
+        const plan = await readUltragoalPlanUnderLock(cwd);
+        if (plan.aggregateCompletion?.status === 'complete') {
+            throw new UltragoalError('Cannot add a goal to an already completed aggregate ultragoal plan; start a new plan for post-terminal work.');
+        }
         const now = iso(options.now);
         const goal = appendGoalToPlan(plan, options);
         await writePlan(cwd, plan);
@@ -701,6 +864,7 @@ function hasProtectedSteeringPayload(value) {
         'codexObjective',
         'constraints',
         'completedAt',
+        'statePathPrefix',
         'qualityGate',
         'status',
     ]);
@@ -958,7 +1122,7 @@ function applySteeringMutation(plan, proposal, now) {
 }
 export async function steerUltragoal(cwd, proposal, options = {}) {
     return withUltragoalMutationLock(cwd, async () => {
-        const plan = await readUltragoalPlan(cwd);
+        const plan = await readUltragoalPlanUnderLock(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;
@@ -1165,9 +1329,34 @@ function validateArchitectureInvariantGate(gate, requiredInvariants) {
         }
     }
 }
-function validateQualityGate(value, requiredInvariants = []) {
+function validateQualityGate(value, requiredInvariants = [], opts = {}) {
+    const strict = opts.strict === true;
+    if (!strict) {
+        // Ordinary mode: targeted verification only, advisory review lanes.
+        // Accepts missing gate (returns undefined) or any gate that at least has passing verification.
+        // Full cohort fields are advisory and not enforced.
+        if (!value || typeof value !== 'object')
+            return undefined;
+        const gate = value;
+        const verification = gate.verification;
+        // If gate provided without verification, treat as advisory-only and allow.
+        if (!verification || typeof verification !== 'object')
+            return undefined;
+        // Require targeted verification when present, but don't fail closed on cohort fields.
+        if (verification.status === 'passed' && Array.isArray(verification.commands) && verification.commands.length > 0) {
+            try {
+                assertNonEmpty(verification.evidence, 'verification.evidence');
+            }
+            catch {
+                return undefined;
+            }
+            // Return advisory gate without strict validation of cleaner/codeReview/invariants.
+            return gate;
+        }
+        return undefined;
+    }
     if (!value || typeof value !== 'object') {
-        throw new UltragoalError('Final ultragoal completion requires --quality-gate-json with ai-slop-cleaner, verification, code-review, and architecture-invariant evidence.');
+        throw new UltragoalError('Final ultragoal completion requires --quality-gate-json with ai-slop-cleaner, verification, code-review, and architecture-invariant evidence. Pass --strict to enforce the cohort gate; ordinary completes with targeted verification only.');
     }
     const gate = value;
     const cleaner = gate.aiSlopCleaner;
@@ -1221,7 +1410,7 @@ function validateQualityGate(value, requiredInvariants = []) {
 }
 export async function startNextUltragoal(cwd, options = {}) {
     return withUltragoalMutationLock(cwd, async () => {
-        const plan = await readUltragoalPlan(cwd);
+        const plan = await readUltragoalPlanUnderLock(cwd);
         const now = iso(options.now);
         if (plan.aggregateCompletion?.status === 'complete')
             return { plan, goal: null, resumed: false, done: true };
@@ -1254,10 +1443,13 @@ export async function startNextUltragoal(cwd, options = {}) {
 }
 export async function checkpointUltragoal(cwd, options) {
     return withUltragoalMutationLock(cwd, async () => {
-        const plan = await readUltragoalPlan(cwd);
+        const plan = await readUltragoalPlanUnderLock(cwd);
         const goal = plan.goals.find((candidate) => candidate.id === options.goalId);
         if (!goal)
             throw new UltragoalError(`Unknown ultragoal id: ${options.goalId}`);
+        if (plan.aggregateCompletion?.status === 'complete' && options.status !== 'complete') {
+            throw new UltragoalError(`Cannot record a ${options.status} checkpoint for ${goal.id} after the aggregate ultragoal plan is complete; the terminal aggregate receipt is immutable.`);
+        }
         const now = iso(options.now);
         if (options.status === 'blocked') {
             if (goal.status !== 'in_progress') {
@@ -1282,17 +1474,37 @@ export async function checkpointUltragoal(cwd, options) {
                 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.`);
+                throw new UltragoalError('Blocked ultragoal checkpoints require either a get_goal snapshot for the completed legacy Codex goal that blocked create_goal, an unavailable get_goal error JSON for a Codex DB/schema/context failure, or a matching native blocked snapshot; pass --codex-goal-json.');
             }
             if (!snapshot.objective) {
                 throw new UltragoalError('Blocked ultragoal checkpoint Codex snapshot is missing objective text.');
             }
-            const safeCompletedAggregateBlocker = isSafeCompletedAggregateBlockerSnapshot(plan, goal, snapshot, options.evidence);
             const blockedSnapshotMatchesExpected = [expectedCodexObjective(plan, goal), ...compatibleCodexObjectives(plan)]
                 .some((objective) => normalizeObjective(objective) === normalizeObjective(snapshot.objective ?? ''));
+            if (snapshot.status === 'blocked') {
+                if (!blockedSnapshotMatchesExpected) {
+                    throw new UltragoalError(`Blocked ultragoal checkpoint objective mismatch: expected one of [${[expectedCodexObjective(plan, goal), ...compatibleCodexObjectives(plan)].join(' | ')}], got ${snapshot.objective}. Matching native blocked checkpoints require the expected/compatible Codex objective; finish or clear the foreign goal, or pass a matching blocked get_goal snapshot with --evidence.`);
+                }
+                const evidence = assertNonEmpty(options.evidence, '--evidence');
+                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,
+                    codexGoal: options.codexGoal,
+                    message: 'Native Codex goal status is blocked for the matching objective; recorded a non-terminal goal_blocked checkpoint. Continue work without treating this as complete or failed; re-check get_goal when the blocker clears.',
+                });
+                return plan;
+            }
+            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 safeCompletedAggregateBlocker = isSafeCompletedAggregateBlockerSnapshot(plan, goal, snapshot, options.evidence);
             if (!safeCompletedAggregateBlocker && blockedSnapshotMatchesExpected) {
                 throw new UltragoalError('Blocked ultragoal checkpoint is only for a different completed legacy Codex goal unless an aggregate Codex goal is already complete and unreconcilable while the active repo-native microgoal remains in progress.');
             }
@@ -1367,10 +1579,8 @@ export async function checkpointUltragoal(cwd, options) {
                     throw new UltragoalError(`${formatCodexGoalReconciliation(reconciliation)}${taskScopedRequirement}${remediation}`);
                 }
             }
-            const designatedReviewBlockerResolver = goal.resolvesReviewBlockedGoalId
-                ? isDesignatedReviewBlockerResolver(goal, plan.goals.find((candidate) => candidate.id === goal.resolvesReviewBlockedGoalId))
-                : false;
-            if (aggregateMode && finalRunCheckpoint && !options.allowActiveFinalCodexGoal && designatedReviewBlockerResolver) {
+            if (aggregateMode
+                && canPersistNormalFinalAggregateCompletion(plan, goal, finalRunCheckpoint, options.allowActiveFinalCodexGoal)) {
                 normalFinalAggregateCompletion = {
                     status: 'complete',
                     completedAt: now,
@@ -1381,12 +1591,17 @@ export async function checkpointUltragoal(cwd, options) {
             if (finalRunCheckpoint && !options.allowActiveFinalCodexGoal)
                 goal.evidence = options.evidence;
         }
-        const requiredArchitectureInvariants = options.status === 'complete' && (aggregateCompletion !== undefined || (isFinalRunCompletionCandidate(plan, goal) && !options.allowActiveFinalCodexGoal))
+        const isStrict = options.strict === true;
+        const isFinalGateCandidate = options.status === 'complete' && (aggregateCompletion !== undefined || (isFinalRunCompletionCandidate(plan, goal) && !options.allowActiveFinalCodexGoal));
+        const requiredArchitectureInvariants = isFinalGateCandidate
             ? await collectRequiredArchitectureInvariants(cwd)
             : [];
-        const qualityGate = options.status === 'complete' && (aggregateCompletion !== undefined || (isFinalRunCompletionCandidate(plan, goal) && !options.allowActiveFinalCodexGoal))
-            ? validateQualityGate(options.qualityGate, requiredArchitectureInvariants)
+        const qualityGate = isFinalGateCandidate
+            ? validateQualityGate(options.qualityGate, requiredArchitectureInvariants, { strict: isStrict })
             : undefined;
+        if (isFinalGateCandidate && isStrict && !qualityGate) {
+            throw new UltragoalError('Final ultragoal completion requires --quality-gate-json with ai-slop-cleaner, verification, code-review, and architecture-invariant evidence. Pass --strict to enforce the cohort gate; ordinary completes with targeted verification only.');
+        }
         if (aggregateCompletion) {
             goal.status = 'complete';
             goal.completedAt = now;
@@ -1518,7 +1733,7 @@ export async function checkpointUltragoal(cwd, options) {
 }
 export async function recordFinalReviewBlockers(cwd, options) {
     return withUltragoalMutationLock(cwd, async () => {
-        const plan = await readUltragoalPlan(cwd);
+        const plan = await readUltragoalPlanUnderLock(cwd);
         const goal = plan.goals.find((candidate) => candidate.id === options.goalId);
         if (!goal)
             throw new UltragoalError(`Unknown ultragoal id: ${options.goalId}`);
@@ -1651,7 +1866,7 @@ function buildPerStoryCodexGoalInstruction(goal, plan, options) {
         finalStory
             ? '- After the final checkpoint command succeeds, treat `/goal clear` as the explicit terminal cleanup step before another same-thread goal.'
             : null,
-        '- If blocked or failed, checkpoint with --status failed and the failure evidence; rerun complete-goals --retry-failed to resume.',
+        '- If blocked on a matching native Codex goal status, record a non-terminal blocker with: omx ultragoal checkpoint --goal-id ' + goal.id + ' --status blocked --evidence "<blocker evidence>" --codex-goal-json "<matching blocked get_goal JSON or path>". If failed, checkpoint with --status failed and the failure evidence; rerun complete-goals --retry-failed to resume.',
         '',
         'create_goal payload:',
         JSON.stringify(createPayload, null, 2),
@@ -1661,7 +1876,8 @@ function buildPerStoryCodexGoalInstruction(goal, plan, options) {
     ].filter((line) => line !== null).join('\n');
 }
 function buildAggregateCodexGoalInstruction(goal, plan, options) {
-    const objective = plan.codexObjective ?? aggregateCodexObjective(plan.goals);
+    const statePathPrefix = plan.statePathPrefix ?? '';
+    const objective = plan.codexObjective ?? aggregateCodexObjective(statePathPrefix);
     const finalStory = isFinalRunCompletionCandidate(plan, goal);
     const createPayload = { objective };
     const checkpointStatus = finalStory ? 'complete' : 'active';
@@ -1669,8 +1885,8 @@ function buildAggregateCodexGoalInstruction(goal, plan, options) {
         codexGoalConductorGuidance(options),
         '',
         'Ultragoal aggregate-goal handoff',
-        `Plan: ${plan.goalsPath}`,
-        `Ledger: ${plan.ledgerPath}`,
+        `Plan: ${prefixedStatePath(statePathPrefix, ULTRAGOAL_GOALS)}`,
+        `Ledger: ${prefixedStatePath(statePathPrefix, ULTRAGOAL_LEDGER)}`,
         `Goal: ${goal.id} — ${goal.title}`,
         '',
         'Codex goal integration constraints:',
@@ -1702,7 +1918,7 @@ function buildAggregateCodexGoalInstruction(goal, plan, options) {
         finalStory
             ? `  omx ultragoal checkpoint --goal-id ${goal.id} --status complete --evidence "<tests/files/PR evidence>" --codex-goal-json "<fresh complete get_goal JSON or path>" --quality-gate-json "<quality gate 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>"`,
-        '- If blocked or failed, checkpoint with --status failed and the failure evidence; rerun complete-goals --retry-failed to resume.',
+        '- If blocked on a matching native Codex goal status, record a non-terminal blocker with: omx ultragoal checkpoint --goal-id ' + goal.id + ' --status blocked --evidence "<blocker evidence>" --codex-goal-json "<matching blocked get_goal JSON or path>". If failed, checkpoint with --status failed and the failure evidence; rerun complete-goals --retry-failed to resume.',
         '',
         'create_goal payload:',
         JSON.stringify(createPayload, null, 2),