Yeachan-Heo/oh-my-codex · error · UltragoalError

${formatCodexGoalReconciliation(reconciliation)}${taskScoped

Error message

${formatCodexGoalReconciliation(reconciliation)}${taskScopedRequirement}${remediation}

What it means

The Codex goal reconciliation for a completion checkpoint failed; the thrown message concatenates formatCodexGoalReconciliation(reconciliation), a task-scoped requirement note, and remediation guidance (completed-legacy-goal remediation or db_schema_context_error remediation) explaining what mismatched and how to fix it.

Source

Thrown at src/ultragoal/artifacts.ts:1926

            status: 'complete',
            completedAt: now,
            evidence: assertNonEmpty(options.evidence, '--evidence'),
            codexGoal: options.codexGoal,
          };
        }
      } else {
        const taskScopedRequirement = aggregateMode && snapshot?.status === 'complete' && Boolean(snapshot.objective)
          ? ' Completed task-scoped aggregate reconciliation requires the checkpoint goal to be the active in-progress OMX goal, evidence that names that active OMX goal id, names .omx/ultragoal/goals.json or ledger.jsonl, includes completed implementation plus validation/review evidence, and a get_goal objective that maps to the ultragoal brief.'
          : '';
        const remediation = reconciliation.snapshot.available
          && reconciliation.snapshot.status === 'complete'
          && Boolean(reconciliation.snapshot.objective)
          && normalizeObjective(reconciliation.snapshot.objective ?? '') !== normalizeObjective(expectedObjective)
          ? ` ${buildCompletedLegacyGoalRemediation(goal)}`
          : reconciliation.snapshot.unavailableReason === 'db_schema_context_error'
            ? ` ${buildUnavailableCodexGoalRemediation(goal)}`
          : '';
        throw new UltragoalError(`${formatCodexGoalReconciliation(reconciliation)}${taskScopedRequirement}${remediation}`);
      }
    }
    if (
      aggregateMode
      && canPersistNormalFinalAggregateCompletion(
        plan,
        goal,
        finalRunCheckpoint,
        options.allowActiveFinalCodexGoal,
      )
    ) {
      normalFinalAggregateCompletion = {
        status: 'complete',
        completedAt: now,
        evidence: assertNonEmpty(options.evidence, '--evidence'),
        codexGoal: options.codexGoal,
      };
    }

View on GitHub (pinned to 3ad79a8a6f)

Solutions

Read the embedded reconciliation detail: it states the actual snapshot status/objective vs what was required
Bring the Codex goal to the required state (finish it, or re-align objectives) and re-run get_goal before completing
If get_goal is failing with a DB/schema/context error, follow the included buildUnavailableCodexGoalRemediation guidance for that goal

Defensive patterns

Strategy: try-catch

Try / catch

catch (e) { if (e instanceof UltragoalError) { const rec = formatCodexGoalReconciliation?.(null); console.error(e.message); /* message contains remediation steps */ await reconcileCodexAndRetry(); } }

Prevention

Run get_goal and satisfy the required statuses before completing
Read the embedded remediation text — it names the exact next action for both legacy-goal and db_schema_context_error cases

When it happens

Trigger: A completion checkpoint where reconcileCodexGoalSnapshot returns ok: false — e.g. the Codex goal status/objective doesn't satisfy the required allowedStatuses/requireSnapshot/requireComplete options for final or aggregate completion.

Common situations: Completing a goal while the Codex goal is still active or has a mismatched objective; legacy completed goals blocking create_goal; get_goal unavailable due to DB/schema/context errors during final completion.

Related errors

AI-assisted analysis of Yeachan-Heo/oh-my-codex@3ad79a8a6f (2026-08-27). Data as JSON: /api/errors/c6561445c8d994c1. Report an issue: GitHub.