{"record":{"id":"53af192af6dc3a54","repo":"Yeachan-Heo/oh-my-codex","slug":"unknown-ultragoal-id-options-goalid","errorCode":null,"errorMessage":"Unknown ultragoal id: ${options.goalId}","messagePattern":"Unknown ultragoal id: (.+?)","errorType":"exception","errorClass":"UltragoalError","httpStatus":null,"severity":"error","filePath":"src/ultragoal/artifacts.ts","lineNumber":1788,"sourceCode":"  next.attempt += 1;\n  next.startedAt = now;\n  next.failedAt = undefined;\n  next.failureReason = undefined;\n  clearGoalBlockerFields(next);\n  next.updatedAt = now;\n  plan.activeGoalId = next.id;\n  plan.updatedAt = now;\n  await writePlan(cwd, plan);\n  await appendLedger(cwd, { ts: now, event: 'goal_started', goalId: next.id, status: next.status, message: `Attempt ${next.attempt}` });\n  return { plan, goal: next, resumed: false, done: false };\n  });\n}\n\nexport async function checkpointUltragoal(cwd: string, options: CheckpointOptions): Promise<UltragoalPlan> {\n  return withUltragoalMutationLock(cwd, async () => {\n  const plan = await readUltragoalPlanUnderLock(cwd);\n  const goal = plan.goals.find((candidate) => candidate.id === options.goalId);\n  if (!goal) throw new UltragoalError(`Unknown ultragoal id: ${options.goalId}`);\n  if (plan.aggregateCompletion?.status === 'complete' && options.status !== 'complete') {\n    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.`);\n  }\n  const now = iso(options.now);\n  if (options.status === 'blocked') {\n    if (goal.status !== 'in_progress') {\n      throw new UltragoalError(`Cannot record a blocked checkpoint for ${goal.id} while it is ${goal.status}; start or resume the ultragoal before recording a non-terminal blocker.`);\n    }\n    const snapshot = options.codexGoal === undefined ? null : parseCodexGoalSnapshot(options.codexGoal);\n    if (snapshot?.unavailableReason === 'db_schema_context_error') {\n      goal.updatedAt = now;\n      goal.failureReason = assertNonEmpty(options.evidence, '--evidence');\n      plan.activeGoalId = goal.id;\n      plan.updatedAt = now;\n      await writePlan(cwd, plan);\n      await appendLedger(cwd, {\n        ts: now,\n        event: 'goal_blocked',","sourceCodeStart":1770,"sourceCodeEnd":1806,"githubUrl":"https://github.com/Yeachan-Heo/oh-my-codex/blob/3ad79a8a6fe6e95fdbb8c00e40716fffe4011ce2/src/ultragoal/artifacts.ts#L1770-L1806","documentation":"checkpointUltragoal could not find any goal in the plan whose id equals options.goalId. Every checkpoint mutation must target an existing goal id in the ultragoal plan for this repo.","triggerScenarios":"Calling checkpointUltragoal with a goalId that is not in plan.goals — typo'd id, stale id from a previous plan, or an id belonging to a different repo's plan.","commonSituations":"Scripts hard-coding goal ids after the plan was recreated; referencing a goal id from an earlier session or from the plan file before it was rewritten; copy-paste of ids between repositories.","solutions":["List the plan goals (read the ultragoal plan artifact) and use the exact id string","If the plan was recreated, update your script/config to the new goal ids","Ensure you run the checkpoint in the repo whose plan contains the goal"],"exampleFix":"// before\nawait checkpointUltragoal(cwd, { goalId: 'goal-42', status: 'in_progress' });\n// after\nconst plan = await readUltragoalPlan(cwd);\nconst goal = plan.goals.find(g => g.title.includes('migrate'))!;\nawait checkpointUltragoal(cwd, { goalId: goal.id, status: 'in_progress' });","handlingStrategy":"type-guard","validationCode":"const plan = await readUltragoalPlan(cwd);\nif (!plan.goals.some(g => g.id === options.goalId)) throw new Error(`goalId ${options.goalId} not in plan`);","typeGuard":"const goalExists = (plan: UltragoalPlan, id: string) => plan.goals.some(g => g.id === id);","tryCatchPattern":"catch (e) { if (e instanceof UltragoalError && /Unknown ultragoal id/.test(e.message)) { await refreshPlanAndRetry(); } else throw e; }","preventionTips":["Always resolve goal ids from a freshly-read plan instead of hard-coding","Pass plan/goal ids through config reviewed on plan recreation"],"tags":["ultragoal","checkpoint","unknown-id","plan"],"backgroundTag":"entity-not-found","analyzedSha":"3ad79a8a6fe6e95fdbb8c00e40716fffe4011ce2","analyzedAt":"2026-08-27T22:18:39.783Z","schemaVersion":2},"datasetVersion":"2026-08-28T00:17:15.603Z"}