oh-my-codex 0.20.2 → 0.20.5

package/dist/ultragoal/__tests__/artifacts.test.js

@@ -1,11 +1,14 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
 import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { existsSync, realpathSync } from 'node:fs';
 import { join } from 'node:path';
-import { tmpdir } from 'node:os';
-import { addUltragoalGoal, buildCodexGoalInstruction, checkpointUltragoal, createUltragoalPlan, isFinalRunCompletionCandidate, isUltragoalDone, readUltragoalPlan, recordFinalReviewBlockers, steerUltragoal, startNextUltragoal, summarizeUltragoalPlan, ULTRAGOAL_AGGREGATE_CODEX_OBJECTIVE, validateUltragoalSteeringProposal, } from '../artifacts.js';
+import { tmpdir as osTmpdir } from 'node:os';
+import { __resetSessionPointerTransactionDependenciesForTests, __setSessionPointerTransactionDependenciesForTests, } from '../../hooks/session.js';
+import { addUltragoalGoal, assertUltragoalWritableLifecycleAuthority, buildCodexGoalInstruction, checkpointUltragoal, createUltragoalPlan, isFinalRunCompletionCandidate, isUltragoalDone, readUltragoalPlan, recordFinalReviewBlockers, steerUltragoal, startNextUltragoal, summarizeUltragoalPlan, ULTRAGOAL_AGGREGATE_CODEX_OBJECTIVE, UltragoalError, validateUltragoalSteeringProposal, } from '../artifacts.js';
 import { LEADER_CONDUCTOR_BLOCK, buildUnsupportedNativeSubagentGuidance } from '../../leader/contract.js';
 import { steeringFixtures } from './steering-fixtures.js';
+const tmpdir = () => realpathSync(osTmpdir());
 async function withTempRepo(run) {
     const cwd = await mkdtemp(join(tmpdir(), 'omx-ultragoal-'));
     try {
@@ -39,6 +42,35 @@ function cleanQualityGate() {
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
+function aggregateFixtureGoal(id, status, extra = {}) {
+    return {
+        id,
+        title: id,
+        objective: `${id} work.`,
+        status,
+        attempt: 1,
+        createdAt: '2026-01-01T00:00:00.000Z',
+        updatedAt: '2026-01-01T00:00:00.000Z',
+        ...extra,
+    };
+}
+async function writeAggregateFixturePlan(cwd, activeGoalId, goals) {
+    await mkdir(join(cwd, '.omx/ultragoal'), { recursive: true });
+    await writeFile(join(cwd, '.omx/ultragoal/brief.md'), 'aggregate terminalization fixture\n');
+    await writeFile(join(cwd, '.omx/ultragoal/goals.json'), `${JSON.stringify({
+        version: 1,
+        createdAt: '2026-01-01T00:00:00.000Z',
+        updatedAt: '2026-01-01T00:00:00.000Z',
+        briefPath: '.omx/ultragoal/brief.md',
+        goalsPath: '.omx/ultragoal/goals.json',
+        ledgerPath: '.omx/ultragoal/ledger.jsonl',
+        codexGoalMode: 'aggregate',
+        codexObjective: ULTRAGOAL_AGGREGATE_CODEX_OBJECTIVE,
+        activeGoalId,
+        goals,
+    }, null, 2)}\n`);
+    await writeFile(join(cwd, '.omx/ultragoal/ledger.jsonl'), '');
+}
 async function writeFixturePlan(cwd, plan) {
     await mkdir(join(cwd, '.omx/ultragoal'), { recursive: true });
     await writeFile(join(cwd, '.omx/ultragoal/brief.md'), 'G001-core-steering-model fixture for .omx/ultragoal steering behavior.\n');
@@ -491,6 +523,11 @@ describe('ultragoal artifacts', () => {
                 evidence: 'first audit passed',
                 codexGoal: { goal: { objective: aggregateObjective, status: 'active' } },
             });
+            const midRunPlan = await readUltragoalPlan(cwd);
+            assert.equal(midRunPlan.goals.find((goal) => goal.id === 'G001-first')?.status, 'complete');
+            assert.equal(midRunPlan.goals.find((goal) => goal.id === 'G002-second')?.status, 'pending');
+            assert.equal(midRunPlan.aggregateCompletion, undefined);
+            assert.equal(summarizeUltragoalPlan(midRunPlan).aggregateComplete, false);
             const second = await startNextUltragoal(cwd);
             await checkpointUltragoal(cwd, {
                 goalId: second.goal.id,
@@ -500,8 +537,16 @@ describe('ultragoal artifacts', () => {
                 qualityGate: cleanQualityGate(),
             });
             const plan = await readUltragoalPlan(cwd);
+            assert.equal(plan.goals.find((goal) => goal.id === second.goal.id)?.status, 'complete');
             assert.equal(plan.goals.every((goal) => goal.status === 'complete'), true);
             assert.equal(plan.activeGoalId, undefined);
+            assert.equal(plan.aggregateCompletion?.status, 'complete');
+            const summary = summarizeUltragoalPlan(plan);
+            assert.equal(summary.aggregateComplete, true);
+            assert.equal(summary.artifactComplete, true);
+            const ledger = await readFile(join(cwd, '.omx/ultragoal/ledger.jsonl'), 'utf-8');
+            assert.equal((ledger.match(/"event":"goal_completed"/g) ?? []).length, 2);
+            assert.equal((ledger.match(/"event":"aggregate_completed"/g) ?? []).length, 1);
         });
     });
     it('treats existing v1 plans without mode metadata as legacy per-story plans', async () => {
@@ -740,6 +785,437 @@ describe('ultragoal artifacts', () => {
             assert.match(ledger, /"event":"aggregate_completed"/);
         });
     });
+    it('does not terminalize through a one-way designated resolver pointer', async () => {
+        await withTempRepo(async (cwd) => {
+            await createUltragoalPlan(cwd, {
+                brief: 'brief',
+                goals: [{ title: 'Final', objective: 'Complete final milestone.' }],
+            });
+            const started = await startNextUltragoal(cwd);
+            const objective = started.plan.codexObjective;
+            const blocked = await recordFinalReviewBlockers(cwd, {
+                goalId: started.goal.id,
+                title: 'Resolve final code-review blockers',
+                objective: 'Fix final code-review blockers and rerun final gates.',
+                evidence: 'code-reviewer REQUEST CHANGES before resolver',
+                codexGoal: { goal: { objective, status: 'active' } },
+            });
+            const resolver = await startNextUltragoal(cwd);
+            assert.equal(resolver.goal?.id, blocked.addedGoal.id);
+            const planPath = join(cwd, '.omx/ultragoal/goals.json');
+            const tampered = JSON.parse(await readFile(planPath, 'utf-8'));
+            const resolverGoal = tampered.goals.find((goal) => goal.id === resolver.goal.id);
+            delete resolverGoal.resolvesReviewBlockedGoalId;
+            await writeFile(planPath, `${JSON.stringify(tampered, null, 2)}\n`);
+            const parentBeforeCheckpoint = tampered.goals.find((goal) => goal.id === blocked.blockedGoal.id);
+            assert.equal(isFinalRunCompletionCandidate(tampered, resolverGoal), true);
+            assert.equal(parentBeforeCheckpoint?.reviewBlockerResolution?.resolverGoalId, resolverGoal.id);
+            const completed = await checkpointUltragoal(cwd, {
+                goalId: resolverGoal.id,
+                status: 'complete',
+                evidence: `${resolverGoal.id} fixed blockers; final gate passed for .omx/ultragoal/goals.json`,
+                codexGoal: { goal: { objective, status: 'complete' } },
+                qualityGate: cleanQualityGate(),
+            });
+            const parent = completed.goals.find((goal) => goal.id === blocked.blockedGoal.id);
+            const completedResolver = completed.goals.find((goal) => goal.id === resolverGoal.id);
+            const summary = summarizeUltragoalPlan(completed);
+            assert.equal(completedResolver?.status, 'complete');
+            assert.equal(parent?.status, 'review_blocked');
+            assert.equal(parent?.reviewBlockerResolution?.resolverGoalId, resolverGoal.id);
+            assert.equal(completed.aggregateCompletion, undefined);
+            assert.equal(summary.reviewBlocked, 1);
+            assert.equal(summary.aggregateComplete, false);
+            assert.equal(summary.artifactComplete, false);
+            assert.equal(isUltragoalDone(completed), false);
+            const ledger = await readFile(join(cwd, '.omx/ultragoal/ledger.jsonl'), 'utf-8');
+            assert.equal((ledger.match(/"event":"aggregate_completed"/g) ?? []).length, 0);
+        });
+    });
+    it('does not terminalize when two unresolved review-blocked parents point at one resolver', async () => {
+        await withTempRepo(async (cwd) => {
+            await createUltragoalPlan(cwd, {
+                brief: 'brief',
+                goals: [{ title: 'Final', objective: 'Complete final milestone.' }],
+            });
+            const started = await startNextUltragoal(cwd);
+            const objective = started.plan.codexObjective;
+            const blocked = await recordFinalReviewBlockers(cwd, {
+                goalId: started.goal.id,
+                title: 'Resolve final code-review blockers',
+                objective: 'Fix final code-review blockers and rerun final gates.',
+                evidence: 'code-reviewer REQUEST CHANGES before resolver',
+                codexGoal: { goal: { objective, status: 'active' } },
+            });
+            const resolver = await startNextUltragoal(cwd);
+            assert.equal(resolver.goal?.id, blocked.addedGoal.id);
+            const planPath = join(cwd, '.omx/ultragoal/goals.json');
+            const tampered = JSON.parse(await readFile(planPath, 'utf-8'));
+            const resolverGoal = tampered.goals.find((goal) => goal.id === resolver.goal.id);
+            const originalParent = tampered.goals.find((goal) => goal.id === blocked.blockedGoal.id);
+            tampered.goals.push({
+                ...originalParent,
+                id: 'G999-forged-second-parent',
+                title: 'Forged second review-blocked parent',
+                objective: 'Forge a second unresolved review-blocked parent.',
+                status: 'review_blocked',
+                reviewBlockerResolution: {
+                    resolverGoalId: resolverGoal.id,
+                    status: 'pending',
+                    evidence: 'forged second parent',
+                },
+            });
+            await writeFile(planPath, `${JSON.stringify(tampered, null, 2)}\n`);
+            assert.equal(tampered.goals.filter((goal) => goal.status === 'review_blocked').length, 2);
+            assert.equal(isFinalRunCompletionCandidate(tampered, resolverGoal), true);
+            const completed = await checkpointUltragoal(cwd, {
+                goalId: resolverGoal.id,
+                status: 'complete',
+                evidence: `${resolverGoal.id} fixed blockers; final gate passed for .omx/ultragoal/goals.json`,
+                codexGoal: { goal: { objective, status: 'complete' } },
+                qualityGate: cleanQualityGate(),
+            });
+            const originalParentAfter = completed.goals.find((goal) => goal.id === originalParent.id);
+            const secondParentAfter = completed.goals.find((goal) => goal.id === 'G999-forged-second-parent');
+            const completedResolver = completed.goals.find((goal) => goal.id === resolverGoal.id);
+            const summary = summarizeUltragoalPlan(completed);
+            assert.equal(completedResolver?.status, 'complete');
+            assert.equal(originalParentAfter?.status, 'complete');
+            assert.equal(originalParentAfter?.reviewBlockerResolution?.status, 'complete');
+            assert.equal(secondParentAfter?.status, 'review_blocked');
+            assert.equal(secondParentAfter?.reviewBlockerResolution?.status, 'pending');
+            assert.equal(completed.aggregateCompletion, undefined);
+            assert.equal(summary.reviewBlocked, 1);
+            assert.equal(summary.aggregateComplete, false);
+            assert.equal(summary.artifactComplete, false);
+            assert.equal(isUltragoalDone(completed), false);
+            const ledger = await readFile(join(cwd, '.omx/ultragoal/ledger.jsonl'), 'utf-8');
+            assert.equal((ledger.match(/"event":"aggregate_completed"/g) ?? []).length, 0);
+        });
+    });
+    it('does not terminalize when a review-blocked parent names a resolver whose back-pointer targets another parent', async () => {
+        await withTempRepo(async (cwd) => {
+            const objective = ULTRAGOAL_AGGREGATE_CODEX_OBJECTIVE;
+            await writeAggregateFixturePlan(cwd, 'G004-final', [
+                aggregateFixtureGoal('G001-parent', 'review_blocked', {
+                    reviewBlockerResolution: {
+                        resolverGoalId: 'G002-resolver',
+                        status: 'complete',
+                        resolvedAt: '2026-01-01T00:00:00.000Z',
+                        evidence: 'forged resolution metadata',
+                    },
+                }),
+                aggregateFixtureGoal('G002-resolver', 'complete', {
+                    completedAt: '2026-01-01T00:00:00.000Z',
+                    evidence: 'resolver done',
+                    resolvesReviewBlockedGoalId: 'G003-other',
+                }),
+                aggregateFixtureGoal('G003-other', 'complete', { completedAt: '2026-01-01T00:00:00.000Z', evidence: 'other done' }),
+                aggregateFixtureGoal('G004-final', 'in_progress', { startedAt: '2026-01-01T00:00:00.000Z' }),
+            ]);
+            const tampered = await readUltragoalPlan(cwd);
+            assert.equal(isFinalRunCompletionCandidate(tampered, tampered.goals.find((goal) => goal.id === 'G004-final')), false);
+            await assert.rejects(() => checkpointUltragoal(cwd, {
+                goalId: 'G004-final',
+                status: 'complete',
+                evidence: 'G004-final completed planned work for .omx/ultragoal/goals.json; validation complete; reviews clean.',
+                codexGoal: { goal: { objective, status: 'complete' } },
+                qualityGate: cleanQualityGate(),
+            }), /not complete|objective mismatch|Completed task-scoped aggregate reconciliation/);
+            const plan = await readUltragoalPlan(cwd);
+            assert.equal(plan.goals.find((goal) => goal.id === 'G001-parent')?.status, 'review_blocked');
+            assert.equal(plan.aggregateCompletion, undefined);
+            assert.equal(summarizeUltragoalPlan(plan).aggregateComplete, false);
+            assert.equal(isUltragoalDone(plan), false);
+            const ledger = await readFile(join(cwd, '.omx/ultragoal/ledger.jsonl'), 'utf-8');
+            assert.equal((ledger.match(/"event":"aggregate_completed"/g) ?? []).length, 0);
+        });
+    });
+    it('does not terminalize when a falsely-resolved parent coexists with a legitimate designated resolver', async () => {
+        await withTempRepo(async (cwd) => {
+            const objective = ULTRAGOAL_AGGREGATE_CODEX_OBJECTIVE;
+            await writeAggregateFixturePlan(cwd, 'G004-resolver-b', [
+                aggregateFixtureGoal('G001-parent-a', 'review_blocked', {
+                    reviewBlockerResolution: {
+                        resolverGoalId: 'G002-resolver-a',
+                        status: 'complete',
+                        resolvedAt: '2026-01-01T00:00:00.000Z',
+                        evidence: 'forged resolution metadata for parent A',
+                    },
+                }),
+                aggregateFixtureGoal('G002-resolver-a', 'complete', {
+                    completedAt: '2026-01-01T00:00:00.000Z',
+                    evidence: 'resolver A done',
+                    resolvesReviewBlockedGoalId: 'G009-elsewhere',
+                }),
+                aggregateFixtureGoal('G003-parent-b', 'review_blocked', {
+                    reviewBlockerResolution: {
+                        resolverGoalId: 'G004-resolver-b',
+                        status: 'pending',
+                        evidence: 'legitimate blocker for parent B',
+                    },
+                }),
+                aggregateFixtureGoal('G004-resolver-b', 'in_progress', {
+                    startedAt: '2026-01-01T00:00:00.000Z',
+                    resolvesReviewBlockedGoalId: 'G003-parent-b',
+                }),
+            ]);
+            await assert.rejects(() => checkpointUltragoal(cwd, {
+                goalId: 'G004-resolver-b',
+                status: 'complete',
+                evidence: 'G004-resolver-b completed planned work for .omx/ultragoal/goals.json; validation complete; reviews clean.',
+                codexGoal: { goal: { objective, status: 'complete' } },
+                qualityGate: cleanQualityGate(),
+            }), /not complete|objective mismatch|Completed task-scoped aggregate reconciliation/);
+            const plan = await readUltragoalPlan(cwd);
+            assert.equal(plan.goals.find((goal) => goal.id === 'G001-parent-a')?.status, 'review_blocked');
+            assert.equal(plan.aggregateCompletion, undefined);
+            assert.equal(summarizeUltragoalPlan(plan).aggregateComplete, false);
+            assert.equal(isUltragoalDone(plan), false);
+            const ledger = await readFile(join(cwd, '.omx/ultragoal/ledger.jsonl'), 'utf-8');
+            assert.equal((ledger.match(/"event":"aggregate_completed"/g) ?? []).length, 0);
+        });
+    });
+    it('does not treat a self-referential review-blocker resolver as a designated resolver', async () => {
+        await withTempRepo(async (cwd) => {
+            const objective = ULTRAGOAL_AGGREGATE_CODEX_OBJECTIVE;
+            await writeAggregateFixturePlan(cwd, 'G001-self', [
+                aggregateFixtureGoal('G001-self', 'review_blocked', {
+                    reviewBlockerResolution: {
+                        resolverGoalId: 'G001-self',
+                        status: 'pending',
+                        evidence: 'self-referential resolver metadata',
+                    },
+                    resolvesReviewBlockedGoalId: 'G001-self',
+                }),
+            ]);
+            const completed = await checkpointUltragoal(cwd, {
+                goalId: 'G001-self',
+                status: 'complete',
+                evidence: 'G001-self completed planned work for .omx/ultragoal/goals.json; validation complete; reviews clean.',
+                codexGoal: { goal: { objective, status: 'complete' } },
+                qualityGate: cleanQualityGate(),
+            });
+            assert.equal(completed.aggregateCompletion, undefined);
+            assert.equal(summarizeUltragoalPlan(completed).aggregateComplete, false);
+            const ledger = await readFile(join(cwd, '.omx/ultragoal/ledger.jsonl'), 'utf-8');
+            assert.equal((ledger.match(/"event":"aggregate_completed"/g) ?? []).length, 0);
+        });
+    });
+    it('does not terminalize when the final aggregate candidate is steering-blocked', async () => {
+        await withTempRepo(async (cwd) => {
+            const objective = ULTRAGOAL_AGGREGATE_CODEX_OBJECTIVE;
+            await writeAggregateFixturePlan(cwd, 'G002-target', [
+                aggregateFixtureGoal('G001-first', 'complete', { completedAt: '2026-01-01T00:00:00.000Z', evidence: 'first done' }),
+                aggregateFixtureGoal('G002-target', 'in_progress', { startedAt: '2026-01-01T00:00:00.000Z', steeringStatus: 'blocked' }),
+            ]);
+            const tampered = await readUltragoalPlan(cwd);
+            assert.equal(isFinalRunCompletionCandidate(tampered, tampered.goals.find((goal) => goal.id === 'G002-target')), true);
+            const completed = await checkpointUltragoal(cwd, {
+                goalId: 'G002-target',
+                status: 'complete',
+                evidence: 'G002-target completed planned work for .omx/ultragoal/goals.json; validation complete; reviews clean.',
+                codexGoal: { goal: { objective, status: 'complete' } },
+                qualityGate: cleanQualityGate(),
+            });
+            assert.equal(completed.goals.find((goal) => goal.id === 'G002-target')?.steeringStatus, 'blocked');
+            assert.equal(completed.aggregateCompletion, undefined);
+            assert.equal(summarizeUltragoalPlan(completed).aggregateComplete, false);
+            assert.equal(isUltragoalDone(completed), false);
+            const ledger = await readFile(join(cwd, '.omx/ultragoal/ledger.jsonl'), 'utf-8');
+            assert.equal((ledger.match(/"event":"aggregate_completed"/g) ?? []).length, 0);
+        });
+    });
+    it('does not terminalize when duplicate goal ids hide an unresolved row', async () => {
+        await withTempRepo(async (cwd) => {
+            const objective = ULTRAGOAL_AGGREGATE_CODEX_OBJECTIVE;
+            await writeAggregateFixturePlan(cwd, 'G002-dup', [
+                aggregateFixtureGoal('G001-first', 'complete', { completedAt: '2026-01-01T00:00:00.000Z', evidence: 'first done' }),
+                aggregateFixtureGoal('G002-dup', 'in_progress', { startedAt: '2026-01-01T00:00:00.000Z' }),
+                aggregateFixtureGoal('G002-dup', 'pending'),
+            ]);
+            const tampered = await readUltragoalPlan(cwd);
+            assert.equal(isFinalRunCompletionCandidate(tampered, tampered.goals.find((goal) => goal.id === 'G002-dup')), true);
+            const completed = await checkpointUltragoal(cwd, {
+                goalId: 'G002-dup',
+                status: 'complete',
+                evidence: 'G002-dup completed planned work for .omx/ultragoal/goals.json; validation complete; reviews clean.',
+                codexGoal: { goal: { objective, status: 'complete' } },
+                qualityGate: cleanQualityGate(),
+            });
+            assert.equal(completed.goals.filter((goal) => goal.id === 'G002-dup' && goal.status === 'pending').length, 1);
+            assert.equal(completed.aggregateCompletion, undefined);
+            assert.equal(summarizeUltragoalPlan(completed).aggregateComplete, false);
+            assert.equal(isUltragoalDone(completed), false);
+            const ledger = await readFile(join(cwd, '.omx/ultragoal/ledger.jsonl'), 'utf-8');
+            assert.equal((ledger.match(/"event":"aggregate_completed"/g) ?? []).length, 0);
+        });
+    });
+    it('does not terminalize a final aggregate candidate that is not the active in-progress goal', async () => {
+        const objective = ULTRAGOAL_AGGREGATE_CODEX_OBJECTIVE;
+        for (const unowned of ['pending', 'failed', 'needs_user_decision']) {
+            await withTempRepo(async (cwd) => {
+                await writeAggregateFixturePlan(cwd, 'G002-target', [
+                    aggregateFixtureGoal('G001-first', 'complete', { completedAt: '2026-01-01T00:00:00.000Z', evidence: 'first done' }),
+                    aggregateFixtureGoal('G002-target', unowned),
+                ]);
+                const tampered = await readUltragoalPlan(cwd);
+                assert.equal(isFinalRunCompletionCandidate(tampered, tampered.goals.find((goal) => goal.id === 'G002-target')), true);
+                const completed = await checkpointUltragoal(cwd, {
+                    goalId: 'G002-target',
+                    status: 'complete',
+                    evidence: 'G002-target completed planned work for .omx/ultragoal/goals.json; validation complete; reviews clean.',
+                    codexGoal: { goal: { objective, status: 'complete' } },
+                    qualityGate: cleanQualityGate(),
+                });
+                assert.equal(completed.aggregateCompletion, undefined, unowned);
+                assert.equal(summarizeUltragoalPlan(completed).aggregateComplete, false, unowned);
+                const ledger = await readFile(join(cwd, '.omx/ultragoal/ledger.jsonl'), 'utf-8');
+                assert.equal((ledger.match(/"event":"aggregate_completed"/g) ?? []).length, 0, unowned);
+            });
+        }
+    });
+    it('keeps terminal aggregate completion idempotent under repeated and concurrent final checkpoints', async () => {
+        await withTempRepo(async (cwd) => {
+            await createUltragoalPlan(cwd, {
+                brief: 'brief',
+                goals: [
+                    { title: 'First', objective: 'Complete first milestone.' },
+                    { title: 'Second', objective: 'Complete second milestone.' },
+                ],
+            });
+            const first = await startNextUltragoal(cwd);
+            const aggregateObjective = first.plan.codexObjective;
+            await checkpointUltragoal(cwd, {
+                goalId: first.goal.id,
+                status: 'complete',
+                evidence: 'first audit passed',
+                codexGoal: { goal: { objective: aggregateObjective, status: 'active' } },
+            });
+            const second = await startNextUltragoal(cwd);
+            const terminal = await checkpointUltragoal(cwd, {
+                goalId: second.goal.id,
+                status: 'complete',
+                evidence: 'final audit passed',
+                codexGoal: { goal: { objective: aggregateObjective, status: 'complete' } },
+                qualityGate: cleanQualityGate(),
+            });
+            const firstCompletedAt = terminal.aggregateCompletion?.completedAt;
+            assert.equal(terminal.aggregateCompletion?.status, 'complete');
+            assert.ok(firstCompletedAt);
+            for (let attempt = 0; attempt < 3; attempt += 1) {
+                await checkpointUltragoal(cwd, {
+                    goalId: second.goal.id,
+                    status: 'complete',
+                    evidence: `repeated terminal checkpoint ${attempt}`,
+                    codexGoal: { goal: { objective: aggregateObjective, status: 'complete' } },
+                    qualityGate: cleanQualityGate(),
+                }).catch(() => undefined);
+            }
+            await Promise.allSettled(Array.from({ length: 5 }, (_, index) => checkpointUltragoal(cwd, {
+                goalId: second.goal.id,
+                status: 'complete',
+                evidence: `concurrent terminal checkpoint ${index}`,
+                codexGoal: { goal: { objective: aggregateObjective, status: 'complete' } },
+                qualityGate: cleanQualityGate(),
+            })));
+            const plan = await readUltragoalPlan(cwd);
+            assert.equal(plan.aggregateCompletion?.status, 'complete');
+            assert.equal(plan.aggregateCompletion?.completedAt, firstCompletedAt);
+            assert.equal(summarizeUltragoalPlan(plan).aggregateComplete, true);
+            const ledger = await readFile(join(cwd, '.omx/ultragoal/ledger.jsonl'), 'utf-8');
+            assert.equal((ledger.match(/"event":"aggregate_completed"/g) ?? []).length, 1);
+        });
+    });
+    it('pins allowActiveFinalCodexGoal as a required negative condition for terminal aggregate completion', async () => {
+        await withTempRepo(async (cwd) => {
+            await createUltragoalPlan(cwd, {
+                brief: 'brief',
+                goals: [
+                    { title: 'First', objective: 'Complete first milestone.' },
+                    { title: 'Second', objective: 'Complete second milestone.' },
+                ],
+            });
+            const first = await startNextUltragoal(cwd);
+            const aggregateObjective = first.plan.codexObjective;
+            await checkpointUltragoal(cwd, {
+                goalId: first.goal.id,
+                status: 'complete',
+                evidence: 'first audit passed',
+                codexGoal: { goal: { objective: aggregateObjective, status: 'active' } },
+            });
+            const second = await startNextUltragoal(cwd);
+            const completed = await checkpointUltragoal(cwd, {
+                goalId: second.goal.id,
+                status: 'complete',
+                evidence: 'final story completed while the aggregate Codex goal stays active',
+                codexGoal: { goal: { objective: aggregateObjective, status: 'active' } },
+                allowActiveFinalCodexGoal: true,
+            });
+            assert.equal(completed.goals.find((goal) => goal.id === second.goal.id)?.status, 'complete');
+            assert.equal(completed.aggregateCompletion, undefined);
+            assert.equal(summarizeUltragoalPlan(completed).aggregateComplete, false);
+            const ledger = await readFile(join(cwd, '.omx/ultragoal/ledger.jsonl'), 'utf-8');
+            assert.equal((ledger.match(/"event":"aggregate_completed"/g) ?? []).length, 0);
+        });
+    });
+    it('does not terminalize an in-progress final candidate whose activeGoalId pointer does not match', async () => {
+        const objective = ULTRAGOAL_AGGREGATE_CODEX_OBJECTIVE;
+        for (const activePointer of ['G001-first', undefined]) {
+            await withTempRepo(async (cwd) => {
+                await writeAggregateFixturePlan(cwd, activePointer, [
+                    aggregateFixtureGoal('G001-first', 'complete', { completedAt: '2026-01-01T00:00:00.000Z', evidence: 'first done' }),
+                    aggregateFixtureGoal('G002-target', 'in_progress', { startedAt: '2026-01-01T00:00:00.000Z' }),
+                ]);
+                const tampered = await readUltragoalPlan(cwd);
+                const target = tampered.goals.find((goal) => goal.id === 'G002-target');
+                assert.equal(target.status, 'in_progress');
+                assert.equal(isFinalRunCompletionCandidate(tampered, target), true);
+                const completed = await checkpointUltragoal(cwd, {
+                    goalId: 'G002-target',
+                    status: 'complete',
+                    evidence: 'G002-target completed planned work for .omx/ultragoal/goals.json; validation complete; reviews clean.',
+                    codexGoal: { goal: { objective, status: 'complete' } },
+                    qualityGate: cleanQualityGate(),
+                });
+                assert.equal(completed.aggregateCompletion, undefined, String(activePointer));
+                assert.equal(summarizeUltragoalPlan(completed).aggregateComplete, false, String(activePointer));
+                const ledger = await readFile(join(cwd, '.omx/ultragoal/ledger.jsonl'), 'utf-8');
+                assert.equal((ledger.match(/"event":"aggregate_completed"/g) ?? []).length, 0, String(activePointer));
+            });
+        }
+    });
+    it('freezes a completed aggregate plan against post-terminal failure checkpoints and goal additions', async () => {
+        await withTempRepo(async (cwd) => {
+            await createUltragoalPlan(cwd, {
+                brief: 'brief',
+                goals: [{ title: 'Only', objective: 'Complete the only milestone.' }],
+            });
+            const started = await startNextUltragoal(cwd);
+            const terminal = await checkpointUltragoal(cwd, {
+                goalId: started.goal.id,
+                status: 'complete',
+                evidence: 'terminal aggregate checkpoint',
+                codexGoal: { goal: { objective: started.plan.codexObjective, status: 'complete' } },
+                qualityGate: cleanQualityGate(),
+            });
+            assert.equal(terminal.aggregateCompletion?.status, 'complete');
+            await assert.rejects(() => checkpointUltragoal(cwd, {
+                goalId: started.goal.id,
+                status: 'failed',
+                evidence: 'post-terminal failure attempt',
+            }), /after the aggregate ultragoal plan is complete/);
+            await assert.rejects(() => addUltragoalGoal(cwd, { title: 'Post terminal', objective: 'Added after completion.' }), /already completed aggregate ultragoal plan/);
+            const plan = await readUltragoalPlan(cwd);
+            assert.equal(plan.goals.length, 1);
+            assert.equal(plan.goals[0]?.status, 'complete');
+            assert.equal(plan.aggregateCompletion?.status, 'complete');
+            assert.equal(summarizeUltragoalPlan(plan).aggregateComplete, true);
+            const ledger = await readFile(join(cwd, '.omx/ultragoal/ledger.jsonl'), 'utf-8');
+            assert.equal((ledger.match(/"event":"aggregate_completed"/g) ?? []).length, 1);
+            assert.equal((ledger.match(/"event":"goal_failed"/g) ?? []).length, 0);
+        });
+    });
     it('does not reconcile a review-blocked parent from a non-designated resolver goal', async () => {
         await withTempRepo(async (cwd) => {
             await createUltragoalPlan(cwd, {
@@ -1757,6 +2233,41 @@ describe('ultragoal artifacts', () => {
             }), /different completed legacy Codex goal/);
         });
     });
+    it('records matching native blocked Codex goal checkpoints as non-terminal', async () => {
+        await withTempRepo(async (cwd) => {
+            await createUltragoalPlan(cwd, {
+                brief: 'brief',
+                goals: [
+                    { title: 'First', objective: 'Complete first milestone.' },
+                ],
+            });
+            const first = await startNextUltragoal(cwd);
+            const objective = first.plan.codexObjective ?? first.goal.objective;
+            const plan = await checkpointUltragoal(cwd, {
+                goalId: first.goal.id,
+                status: 'blocked',
+                evidence: 'native matching blocked needs attention',
+                codexGoal: { goal: { objective, status: 'blocked' } },
+            });
+            const goal = plan.goals.find((item) => item.id === first.goal.id);
+            assert.equal(goal?.status, 'in_progress');
+            assert.equal(plan.activeGoalId, first.goal.id);
+            const ledger = await readFile(join(cwd, '.omx/ultragoal/ledger.jsonl'), 'utf-8');
+            assert.match(ledger, /"event":"goal_blocked"/);
+            assert.match(ledger, /Native Codex goal status is blocked/);
+            await assert.rejects(() => checkpointUltragoal(cwd, {
+                goalId: first.goal.id,
+                status: 'blocked',
+                codexGoal: { goal: { objective, status: 'blocked' } },
+            }), /--evidence/);
+            await assert.rejects(() => checkpointUltragoal(cwd, {
+                goalId: first.goal.id,
+                status: 'blocked',
+                evidence: 'foreign blocked goal',
+                codexGoal: { goal: { objective: 'Different blocked work', status: 'blocked' } },
+            }), /objective mismatch/);
+        });
+    });
     it('steers a split pending goal through superseded lifecycle without weakening completion gates', async () => {
         await withTempRepo(async (cwd) => {
             await createUltragoalPlan(cwd, {
@@ -1891,5 +2402,442 @@ describe('ultragoal artifacts', () => {
             assert.equal((ledger.match(/"event":"steering_accepted"/g) ?? []).length, 1);
         });
     });
+    it('preserves root-mode bootstrap when OMX_SESSION_ID is absent', async () => {
+        await withTempRepo(async (cwd) => {
+            const previousEnv = process.env.OMX_SESSION_ID;
+            delete process.env.OMX_SESSION_ID;
+            try {
+                const plan = await createUltragoalPlan(cwd, { brief: '- Root-mode goal' });
+                assert.equal(plan.goals.length, 1);
+                assert.equal(existsSync(join(cwd, '.omx/ultragoal/brief.md')), true);
+                assert.equal(existsSync(join(cwd, '.omx/ultragoal/goals.json')), true);
+                assert.equal(existsSync(join(cwd, '.omx/ultragoal/ledger.jsonl')), true);
+            }
+            finally {
+                if (typeof previousEnv === 'string')
+                    process.env.OMX_SESSION_ID = previousEnv;
+                else
+                    delete process.env.OMX_SESSION_ID;
+            }
+        });
+    });
+    for (const [label, malformedSessionId] of [
+        ['path separator', 'bad/session'],
+        ['overlong value', 'x'.repeat(65)],
+    ]) {
+        it(`rejects root-mode bootstrap for a nonempty OMX_SESSION_ID with ${label}`, async () => {
+            await withTempRepo(async (cwd) => {
+                const previousEnv = process.env.OMX_SESSION_ID;
+                process.env.OMX_SESSION_ID = malformedSessionId;
+                try {
+                    await assert.rejects(() => createUltragoalPlan(cwd, { brief: '- Must not persist' }), /OMX_SESSION_ID/);
+                    assert.equal(existsSync(join(cwd, '.omx/ultragoal')), false);
+                }
+                finally {
+                    if (typeof previousEnv === 'string')
+                        process.env.OMX_SESSION_ID = previousEnv;
+                    else
+                        delete process.env.OMX_SESSION_ID;
+                }
+            });
+        });
+    }
+    it('rejects a malformed OMX_SESSION_ID even when a live selected session exists', async () => {
+        await withTempRepo(async (cwd) => {
+            const previousEnv = process.env.OMX_SESSION_ID;
+            process.env.OMX_SESSION_ID = 'bad/session';
+            try {
+                const stateDir = join(cwd, '.omx', 'state');
+                await mkdir(stateDir, { recursive: true });
+                await writeFile(join(stateDir, 'session.json'), JSON.stringify({ session_id: 'sess-live', cwd }));
+                await assert.rejects(() => createUltragoalPlan(cwd, { brief: '- Must not persist' }), /OMX_SESSION_ID/);
+                assert.equal(existsSync(join(cwd, '.omx/ultragoal')), false);
+            }
+            finally {
+                if (typeof previousEnv === 'string')
+                    process.env.OMX_SESSION_ID = previousEnv;
+                else
+                    delete process.env.OMX_SESSION_ID;
+            }
+        });
+    });
+    it('preserves unbound compatibility for mutations of an existing plan', async () => {
+        await withTempRepo(async (cwd) => {
+            const previousEnv = process.env.OMX_SESSION_ID;
+            delete process.env.OMX_SESSION_ID;
+            try {
+                await createUltragoalPlan(cwd, { brief: '- Initial goal' });
+                process.env.OMX_SESSION_ID = 'sess-compat';
+                const added = await addUltragoalGoal(cwd, {
+                    title: 'Compatibility goal',
+                    objective: 'Preserve the existing-plan compatibility path.',
+                });
+                assert.equal(added.plan.goals.length, 2);
+                assert.equal(added.goal.title, 'Compatibility goal');
+                const ledger = await readFile(join(cwd, '.omx/ultragoal/ledger.jsonl'), 'utf-8');
+                assert.match(ledger, /"event":"goal_added"/);
+            }
+            finally {
+                if (typeof previousEnv === 'string')
+                    process.env.OMX_SESSION_ID = previousEnv;
+                else
+                    delete process.env.OMX_SESSION_ID;
+            }
+        });
+    });
+    it('blocks durable ultragoal mutations while the selected pointer is stale-dead and no exact session is bound', async () => {
+        await withTempRepo(async (cwd) => {
+            const previousEnv = process.env.OMX_SESSION_ID;
+            delete process.env.OMX_SESSION_ID;
+            __setSessionPointerTransactionDependenciesForTests({ probePid: () => 'dead' });
+            try {
+                const stateDir = join(cwd, '.omx', 'state');
+                await mkdir(stateDir, { recursive: true });
+                await writeFile(join(stateDir, 'session.json'), JSON.stringify({ session_id: 'sess-stale-dead', cwd, pid: 8388607 }));
+                await assert.rejects(() => createUltragoalPlan(cwd, { brief: '- Ship the fix' }), (error) => {
+                    assert.match(String(error), /writable lifecycle authority/);
+                    assert.match(String(error), /OMX_SESSION_ID/);
+                    return true;
+                });
+                assert.equal(existsSync(join(cwd, '.omx', 'ultragoal', 'goals.json')), false);
+            }
+            finally {
+                if (typeof previousEnv === 'string')
+                    process.env.OMX_SESSION_ID = previousEnv;
+                __resetSessionPointerTransactionDependenciesForTests();
+            }
+        });
+    });
+    it('allows durable ultragoal mutations after exact-session reconciliation of a stale-dead pointer', async () => {
+        await withTempRepo(async (cwd) => {
+            const previousEnv = process.env.OMX_SESSION_ID;
+            process.env.OMX_SESSION_ID = 'sess-current';
+            __setSessionPointerTransactionDependenciesForTests({ probePid: () => 'dead' });
+            try {
+                const stateDir = join(cwd, '.omx', 'state');
+                await mkdir(stateDir, { recursive: true });
+                await writeFile(join(stateDir, 'session.json'), JSON.stringify({ session_id: 'sess-stale-dead', cwd, pid: 8388607 }));
+                const plan = await createUltragoalPlan(cwd, { brief: '- Ship the fix' });
+                assert.equal(plan.goals.length, 1);
+                assert.equal(existsSync(join(cwd, '.omx', 'ultragoal', 'goals.json')), true);
+            }
+            finally {
+                if (typeof previousEnv === 'string')
+                    process.env.OMX_SESSION_ID = previousEnv;
+                else
+                    delete process.env.OMX_SESSION_ID;
+                __resetSessionPointerTransactionDependenciesForTests();
+            }
+        });
+    });
+    it('gates every durable ultragoal mutator while the selected pointer is stale-dead and no exact session is bound', async () => {
+        await withTempRepo(async (cwd) => {
+            const previousEnv = process.env.OMX_SESSION_ID;
+            delete process.env.OMX_SESSION_ID;
+            __setSessionPointerTransactionDependenciesForTests({ probePid: () => 'dead' });
+            try {
+                const stateDir = join(cwd, '.omx', 'state');
+                await mkdir(stateDir, { recursive: true });
+                await writeFile(join(stateDir, 'session.json'), JSON.stringify({ session_id: 'sess-stale-dead', cwd, pid: 8388607 }));
+                const attempts = [
+                    ['createUltragoalPlan', () => createUltragoalPlan(cwd, { brief: '- Ship the fix' })],
+                    ['addUltragoalGoal', () => addUltragoalGoal(cwd, { title: 'Later', objective: 'Later objective.' })],
+                    ['steerUltragoal', () => steerUltragoal(cwd, {
+                            kind: 'add_subgoal',
+                            source: 'user_prompt_submit',
+                            title: 'Later',
+                            objective: 'Later objective.',
+                            evidence: 'prompt-submit evidence',
+                            rationale: 'bounded explicit directive requires one follow-up only',
+                            idempotencyKey: 'gate-check',
+                        })],
+                    ['startNextUltragoal', () => startNextUltragoal(cwd)],
+                    ['checkpointUltragoal', () => checkpointUltragoal(cwd, { goalId: 'G001-ship-the-fix', status: 'complete', evidence: 'done' })],
+                    ['recordFinalReviewBlockers', () => recordFinalReviewBlockers(cwd, { goalId: 'G001-ship-the-fix', title: 'Blocker', objective: 'Resolve blocker.' })],
+                ];
+                for (const [name, attempt] of attempts) {
+                    await assert.rejects(attempt, (error) => {
+                        assert.match(String(error), /writable lifecycle authority/, name);
+                        return true;
+                    });
+                }
+                assert.equal(existsSync(join(cwd, '.omx', 'ultragoal', 'goals.json')), false);
+            }
+            finally {
+                if (typeof previousEnv === 'string')
+                    process.env.OMX_SESSION_ID = previousEnv;
+                __resetSessionPointerTransactionDependenciesForTests();
+            }
+        });
+    });
+    it('propagates non-compatibility resolver failures instead of permitting durable mutation', async () => {
+        await withTempRepo(async (cwd) => {
+            const allowedRoot = await mkdtemp(join(tmpdir(), 'omx-ultragoal-allowlist-'));
+            const prevAllowlist = process.env.OMX_MCP_WORKDIR_ROOTS;
+            const previousEnv = process.env.OMX_SESSION_ID;
+            delete process.env.OMX_SESSION_ID;
+            process.env.OMX_MCP_WORKDIR_ROOTS = allowedRoot;
+            try {
+                await assert.rejects(() => createUltragoalPlan(cwd, { brief: '- Ship the fix' }), /outside allowed roots/);
+                assert.equal(existsSync(join(cwd, '.omx', 'ultragoal', 'goals.json')), false);
+            }
+            finally {
+                if (typeof prevAllowlist === 'string')
+                    process.env.OMX_MCP_WORKDIR_ROOTS = prevAllowlist;
+                else
+                    delete process.env.OMX_MCP_WORKDIR_ROOTS;
+                if (typeof previousEnv === 'string')
+                    process.env.OMX_SESSION_ID = previousEnv;
+                await rm(allowedRoot, { recursive: true, force: true });
+            }
+        });
+    });
+    it('fails closed when a live selected pointer does not match OMX_SESSION_ID', async () => {
+        await withTempRepo(async (cwd) => {
+            const previousEnv = process.env.OMX_SESSION_ID;
+            process.env.OMX_SESSION_ID = 'sess-unmatched';
+            try {
+                const stateDir = join(cwd, '.omx', 'state');
+                await mkdir(stateDir, { recursive: true });
+                await writeFile(join(stateDir, 'session.json'), JSON.stringify({ session_id: 'sess-live', cwd }));
+                await assert.rejects(() => createUltragoalPlan(cwd, { brief: '- Ship the fix' }), /does not match the live session/);
+                assert.equal(existsSync(join(cwd, '.omx', 'ultragoal', 'goals.json')), false);
+            }
+            finally {
+                if (typeof previousEnv === 'string')
+                    process.env.OMX_SESSION_ID = previousEnv;
+                else
+                    delete process.env.OMX_SESSION_ID;
+            }
+        });
+    });
+    it('refuses read-path legacy objective migration while writable lifecycle authority is unrestored', async () => {
+        await withTempRepo(async (cwd) => {
+            const previousEnv = process.env.OMX_SESSION_ID;
+            delete process.env.OMX_SESSION_ID;
+            __setSessionPointerTransactionDependenciesForTests({ probePid: () => 'dead' });
+            try {
+                const stateDir = join(cwd, '.omx', 'state');
+                await mkdir(stateDir, { recursive: true });
+                await writeFile(join(stateDir, 'session.json'), JSON.stringify({ session_id: 'sess-stale-dead', cwd, pid: 8388607 }));
+                await mkdir(join(cwd, '.omx/ultragoal'), { recursive: true });
+                const legacyObjective = 'Complete all ultragoal stories in .omx/ultragoal/goals.json: G001-first First';
+                const legacyPlan = `${JSON.stringify({
+                    version: 1,
+                    createdAt: '2026-05-04T10:00:00.000Z',
+                    updatedAt: '2026-05-04T10:00:00.000Z',
+                    briefPath: '.omx/ultragoal/brief.md',
+                    goalsPath: '.omx/ultragoal/goals.json',
+                    ledgerPath: '.omx/ultragoal/ledger.jsonl',
+                    codexGoalMode: 'aggregate',
+                    codexObjective: legacyObjective,
+                    goals: [
+                        { id: 'G001-first', title: 'First', objective: 'Complete first.', status: 'pending', attempt: 0, createdAt: '2026-05-04T10:00:00.000Z', updatedAt: '2026-05-04T10:00:00.000Z' },
+                    ],
+                }, null, 2)}\n`;
+                await writeFile(join(cwd, '.omx/ultragoal/goals.json'), legacyPlan);
+                await writeFile(join(cwd, '.omx/ultragoal/ledger.jsonl'), '');
+                await assert.rejects(() => readUltragoalPlan(cwd), /writable lifecycle authority/);
+                // No durable transition happened: the plan bytes and ledger are untouched.
+                assert.equal(await readFile(join(cwd, '.omx/ultragoal/goals.json'), 'utf-8'), legacyPlan);
+                assert.equal(await readFile(join(cwd, '.omx/ultragoal/ledger.jsonl'), 'utf-8'), '');
+            }
+            finally {
+                if (typeof previousEnv === 'string')
+                    process.env.OMX_SESSION_ID = previousEnv;
+                __resetSessionPointerTransactionDependenciesForTests();
+            }
+        });
+    });
+    it('T16 compares the full writable authority token around ultragoal mutation locks', async () => {
+        await withTempRepo(async (cwd) => {
+            const previousEnv = process.env.OMX_SESSION_ID;
+            const stateDir = join(cwd, '.omx/state');
+            const pointerPath = join(stateDir, 'session.json');
+            const pointer = (sessionId) => JSON.stringify({ session_id: sessionId, cwd, state_root: stateDir });
+            const goalsPath = join(cwd, '.omx/ultragoal/goals.json');
+            const ledgerPath = join(cwd, '.omx/ultragoal/ledger.jsonl');
+            const lockPath = join(cwd, '.omx/ultragoal/.mutation.lock');
+            delete process.env.OMX_SESSION_ID;
+            try {
+                await mkdir(stateDir, { recursive: true });
+                await createUltragoalPlan(cwd, { brief: '- Initial goal' });
+                process.env.OMX_SESSION_ID = 'sess-compat';
+                await writeFile(lockPath, 'held');
+                setTimeout(() => { void rm(lockPath, { force: true }); }, 25);
+                await addUltragoalGoal(cwd, { title: 'Stable compatibility authority', objective: 'Mutation proceeds.' });
+                await writeFile(pointerPath, pointer('sess-compat'));
+                await addUltragoalGoal(cwd, { title: 'Stable resolved authority', objective: 'Mutation proceeds.' });
+                for (const [kind, beforeLock, change] of [
+                    ['resolved to different live session', async () => writeFile(pointerPath, pointer('sess-compat')), async () => { process.env.OMX_SESSION_ID = 'sess-replacement'; await writeFile(pointerPath, pointer('sess-replacement')); }],
+                    ['resolved to compatibility', async () => writeFile(pointerPath, pointer('sess-compat')), async () => rm(pointerPath)],
+                    ['compatibility to resolved', async () => rm(pointerPath, { force: true }), async () => writeFile(pointerPath, pointer('sess-compat'))],
+                ]) {
+                    process.env.OMX_SESSION_ID = 'sess-compat';
+                    await beforeLock();
+                    const beforeGoals = await readFile(goalsPath, 'utf-8');
+                    const beforeLedger = await readFile(ledgerPath, 'utf-8');
+                    await writeFile(lockPath, 'held');
+                    setTimeout(() => { void change(); }, 20);
+                    setTimeout(() => { void rm(lockPath, { force: true }); }, 45);
+                    await assert.rejects(() => addUltragoalGoal(cwd, { title: kind, objective: 'Must not persist.' }), UltragoalError);
+                    assert.equal(await readFile(goalsPath, 'utf-8'), beforeGoals);
+                    assert.equal(await readFile(ledgerPath, 'utf-8'), beforeLedger);
+                }
+            }
+            finally {
+                await rm(lockPath, { force: true });
+                if (typeof previousEnv === 'string')
+                    process.env.OMX_SESSION_ID = previousEnv;
+                else
+                    delete process.env.OMX_SESSION_ID;
+            }
+        });
+    });
+    describe('canonical state paths in nested projects', () => {
+        async function withNestedRepo(run) {
+            const repo = await mkdtemp(join(tmpdir(), 'omx-ultragoal-nested-'));
+            try {
+                // A real git worktree root plus pre-existing root-level state that must never be selected.
+                await mkdir(join(repo, '.git'), { recursive: true });
+                await mkdir(join(repo, '.omx/ultragoal'), { recursive: true });
+                await writeFile(join(repo, '.omx/ultragoal/goals.json'), '{"version":1,"goals":[]}\n');
+                await writeFile(join(repo, '.omx/ultragoal/ledger.jsonl'), '');
+                const subproject = join(repo, 'subproject');
+                await mkdir(subproject, { recursive: true });
+                return await run({ repo, subproject });
+            }
+            finally {
+                await rm(repo, { recursive: true, force: true });
+            }
+        }
+        it('binds the aggregate objective to the subtree state root', async () => {
+            await withNestedRepo(async ({ subproject }) => {
+                const plan = await createUltragoalPlan(subproject, { brief: 'Ship the nested feature' });
+                assert.equal(plan.statePathPrefix, 'subproject');
+                assert.match(plan.codexObjective ?? '', /subproject\/\.omx\/ultragoal\/goals\.json/);
+                assert.match(plan.codexObjective ?? '', /subproject\/\.omx\/ultragoal\/ledger\.jsonl/);
+                assert.notEqual(plan.codexObjective, ULTRAGOAL_AGGREGATE_CODEX_OBJECTIVE);
+            });
+        });
+        it('keeps repository-root launches byte-identical to the root objective', async () => {
+            await withNestedRepo(async ({ repo }) => {
+                const plan = await createUltragoalPlan(repo, { brief: 'Ship the root feature', force: true });
+                assert.equal(plan.statePathPrefix, undefined);
+                assert.equal(plan.codexObjective, ULTRAGOAL_AGGREGATE_CODEX_OBJECTIVE);
+            });
+        });
+        it('renders the aggregate handoff header with canonical state paths', async () => {
+            await withNestedRepo(async ({ subproject }) => {
+                await createUltragoalPlan(subproject, { brief: 'Ship the nested feature' });
+                const started = await startNextUltragoal(subproject);
+                const instruction = buildCodexGoalInstruction(started.goal, started.plan);
+                assert.match(instruction, /Plan: subproject\/\.omx\/ultragoal\/goals\.json/);
+                assert.match(instruction, /Ledger: subproject\/\.omx\/ultragoal\/ledger\.jsonl/);
+            });
+        });
+        it('reconciles the prefixed objective and rejects the ambiguous bare objective', async () => {
+            await withNestedRepo(async ({ subproject }) => {
+                const created = await createUltragoalPlan(subproject, { brief: 'Ship the nested feature' });
+                const started = await startNextUltragoal(subproject);
+                const checkpointed = await checkpointUltragoal(subproject, {
+                    goalId: started.goal.id,
+                    status: 'complete',
+                    evidence: 'tests passed',
+                    codexGoal: { goal: { objective: created.codexObjective, status: 'complete' } },
+                    qualityGate: cleanQualityGate(),
+                });
+                assert.equal(checkpointed.goals[0]?.status, 'complete');
+                // A reader that resolved the bare `.omx/...` reference from the repo root must not match.
+                await assert.rejects(checkpointUltragoal(subproject, {
+                    goalId: started.goal.id,
+                    status: 'complete',
+                    evidence: 'tests passed',
+                    codexGoal: { goal: { objective: ULTRAGOAL_AGGREGATE_CODEX_OBJECTIVE, status: 'complete' } },
+                    qualityGate: cleanQualityGate(),
+                }));
+            });
+        });
+        it('migrates a pre-existing nested plan and leaves root plans untouched', async () => {
+            await withNestedRepo(async ({ repo, subproject }) => {
+                await createUltragoalPlan(subproject, { brief: 'Ship the nested feature' });
+                const planPath = join(subproject, '.omx/ultragoal/goals.json');
+                const stale = JSON.parse(await readFile(planPath, 'utf-8'));
+                stale.codexObjective = ULTRAGOAL_AGGREGATE_CODEX_OBJECTIVE;
+                delete stale.statePathPrefix;
+                await writeFile(planPath, `${JSON.stringify(stale, null, 2)}\n`);
+                const migrated = await readUltragoalPlan(subproject);
+                assert.equal(migrated.statePathPrefix, 'subproject');
+                assert.match(migrated.codexObjective ?? '', /subproject\/\.omx\/ultragoal\/goals\.json/);
+                assert.deepEqual(migrated.codexObjectiveAliases, [ULTRAGOAL_AGGREGATE_CODEX_OBJECTIVE]);
+                const ledger = await readFile(join(subproject, '.omx/ultragoal/ledger.jsonl'), 'utf-8');
+                assert.match(ledger, /"event":"aggregate_objective_migrated"/);
+                assert.match(ledger, /canonical repo-root-relative state paths/);
+                // The already-active hidden Codex goal keeps reconciling through the retained alias.
+                const started = await startNextUltragoal(subproject);
+                const checkpointed = await checkpointUltragoal(subproject, {
+                    goalId: started.goal.id,
+                    status: 'complete',
+                    evidence: 'tests passed',
+                    codexGoal: { goal: { objective: ULTRAGOAL_AGGREGATE_CODEX_OBJECTIVE, status: 'complete' } },
+                    qualityGate: cleanQualityGate(),
+                });
+                assert.equal(checkpointed.goals[0]?.status, 'complete');
+                const rootPlan = await createUltragoalPlan(repo, { brief: 'Ship the root feature', force: true });
+                const rootLedgerBefore = await readFile(join(repo, '.omx/ultragoal/ledger.jsonl'), 'utf-8');
+                const reread = await readUltragoalPlan(repo);
+                const rootLedgerAfter = await readFile(join(repo, '.omx/ultragoal/ledger.jsonl'), 'utf-8');
+                assert.equal(reread.codexObjective, rootPlan.codexObjective);
+                assert.equal(reread.codexObjectiveAliases, undefined);
+                assert.equal(rootLedgerAfter, rootLedgerBefore);
+            });
+        });
+    });
+    it('allows durable Ultragoal mutations for an exact-match identity-indeterminate pointer and rejects mismatches', async () => {
+        await withTempRepo(async (cwd) => {
+            const previousEnv = process.env.OMX_SESSION_ID;
+            const sessionId = 'sess-indeterminate';
+            const stateDir = join(cwd, '.omx', 'state');
+            try {
+                await mkdir(stateDir, { recursive: true });
+                await writeFile(join(stateDir, 'session.json'), JSON.stringify({
+                    session_id: sessionId,
+                    cwd,
+                    state_root: stateDir,
+                    pid: 8388607,
+                }));
+                __setSessionPointerTransactionDependenciesForTests({ probePid: () => 'indeterminate' });
+                process.env.OMX_SESSION_ID = sessionId;
+                const plan = await createUltragoalPlan(cwd, { brief: '- Ship the indeterminate recovery' });
+                assert.equal(plan.goals.length, 1);
+                assert.equal(existsSync(join(cwd, '.omx', 'ultragoal', 'goals.json')), true);
+                const authority = await assertUltragoalWritableLifecycleAuthority(cwd);
+                assert.deepEqual(authority, {
+                    kind: 'resolved',
+                    source: 'session',
+                    sessionId,
+                    stateDir: join(stateDir, 'sessions', sessionId),
+                });
+                const goalsPath = join(cwd, '.omx', 'ultragoal', 'goals.json');
+                const beforeMismatch = await readFile(goalsPath, 'utf-8');
+                process.env.OMX_SESSION_ID = 'sess-foreign';
+                // withUltragoalMutationLock calls assertUltragoalWritableLifecycleAuthority before and after lock
+                // acquisition, and that helper calls resolveWritableStateScope, so its point-in-time revalidation
+                // inherits this exact-match branch for free with no separate production-code change needed.
+                await assert.rejects(() => addUltragoalGoal(cwd, { title: 'Must not persist', objective: 'Foreign session mutation.' }), (error) => {
+                    assert.match(String(error), /writable lifecycle authority/);
+                    return true;
+                });
+                assert.equal(await readFile(goalsPath, 'utf-8'), beforeMismatch);
+            }
+            finally {
+                if (typeof previousEnv === 'string')
+                    process.env.OMX_SESSION_ID = previousEnv;
+                else
+                    delete process.env.OMX_SESSION_ID;
+                __resetSessionPointerTransactionDependenciesForTests();
+            }
+        });
+    });
 });
 //# sourceMappingURL=artifacts.test.js.map