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

Refusing mutating ultragoal command "${command}" from Team w

Error message

Refusing mutating ultragoal command "${command}" from Team worker ${workerIdentity}. Ultragoal state is leader-owned; workers must report checkpoint evidence upward instead of mutating .omx/ultragoal.

What it means

A hard safety guard: when the process is identified as a Team worker (readTeamWorkerIdentity returns an identity), mutating ultragoal subcommands (those in ULTRAGOAL_MUTATING_COMMANDS, e.g. steer, add-goal, record-review-blockers) are refused. Ultragoal plan state is leader-owned; workers must surface evidence upward instead of editing .omx/ultragoal directly.

Source

Thrown at src/cli/ultragoal.ts:354

  'complete',
  'complete-goals',
  'next',
  'start-next',
  'checkpoint',
]);

function readTeamWorkerIdentity(env: NodeJS.ProcessEnv = process.env): string | null {
  const publicIdentity = typeof env.OMX_TEAM_WORKER === 'string' ? env.OMX_TEAM_WORKER.trim() : '';
  if (publicIdentity) return publicIdentity;
  const internalIdentity = typeof env.OMX_TEAM_INTERNAL_WORKER === 'string' ? env.OMX_TEAM_INTERNAL_WORKER.trim() : '';
  return internalIdentity || null;
}

function assertUltragoalMutationAllowedFromCurrentProcess(command: string): void {
  if (!ULTRAGOAL_MUTATING_COMMANDS.has(command)) return;
  const workerIdentity = readTeamWorkerIdentity();
  if (!workerIdentity) return;
  throw new UltragoalError(
    `Refusing mutating ultragoal command "${command}" from Team worker ${workerIdentity}. `
    + 'Ultragoal state is leader-owned; workers must report checkpoint evidence upward instead of mutating .omx/ultragoal.',
  );
}

export interface UltragoalCommandDependencies {
  buildCodexGoalInstruction?: typeof buildCodexGoalInstruction;
}

export async function ultragoalCommand(args: string[], deps: UltragoalCommandDependencies = {}): Promise<void> {
  const command = args[0] ?? 'help';
  const rest = args.slice(1);
  const json = hasFlag(rest, '--json');
  const cwd = process.cwd();
  const buildGoalInstruction = deps.buildCodexGoalInstruction ?? buildCodexGoalInstruction;

  try {
    if (command === 'help' || command === '--help' || command === '-h') {

View on GitHub (pinned to 3ad79a8a6f)

Solutions

  1. Run mutating commands from the leader process/agent only; from workers, emit checkpoint evidence reports instead
  2. If this is a local machine wrongly flagged, remove/clear the stale Team worker identity (check readTeamWorkerIdentity's source for the marker location) and re-run
  3. Use read-only commands (status/next) from workers — those are not blocked

Example fix

# before (inside Team worker)
omx ultragoal steer --kind update_goal ...
# Error: Refusing mutating ultragoal command "steer" from Team worker ...

# after
# worker reports evidence upward; leader runs:
omx ultragoal record-review-blockers --goal-id g1 --title t --objective o --evidence e
Defensive patterns

Strategy: validation

Validate before calling

import { readTeamWorkerIdentity } from './team';
const MUTATING = new Set(['steer','add-goal','record-review-blockers' /* ULTRAGOAL_MUTATING_COMMANDS */]);
if (MUTATING.has(cmd) && readTeamWorkerIdentity()) {
  console.error('worker detected: emit checkpoint evidence instead of mutating ultragoal');
  process.exit(3);
}

Type guard

function isMutatingUltragoalCommand(cmd: string, mutating: ReadonlySet<string>): boolean {
  return mutating.has(cmd);
}

Prevention

When it happens

Trigger: A Team worker environment (worker identity file/env present) invoking any mutating command, e.g. `omx ultragoal steer ...` or `omx ultragoal add-goal ...`, from within a worker process.

Common situations: Worker scripts copied from leader playbooks; local dev machine accidentally carrying a worker identity file in .omx; orchestrator misrouting steering calls to worker nodes.

Related errors

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