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

failed to persist HUD authority invalid-state diagnostic

Error message

failed to persist HUD authority invalid-state diagnostic

What it means

During a HUD authority tick, the previously persisted authority state failed validation, and the library attempted to write an invalid-state diagnostic but that write also failed. This is a compound failure: corrupt input state plus an unwritable diagnostic path. The tick aborts so the failure is visible rather than silently ignored.

Source

Thrown at src/hud/authority.ts:385

  const random = deps.random ?? Math.random;
  const jitterMs = jitterMaxMs > 0 ? Math.floor(random() * (jitterMaxMs + 1)) : 0;
  const mergedEnv = { ...process.env, ...options.env };
  const watcherScript = resolveHudWatcherScript(packageRoot, 'notify-fallback-watcher.js', cwd, mergedEnv);
  const notifyScript = resolveHudWatcherScript(packageRoot, 'notify-hook.js', cwd, mergedEnv);
  const authorityStateDir = join(cwd, '.omx', 'state');
  const authorityOwnerPath = join(authorityStateDir, 'notify-fallback-authority-owner.json');
  const authorityStatePath = join(authorityStateDir, 'notify-fallback-authority-state.json');
  const authorityLockPath = join(authorityStateDir, 'notify-fallback-authority.lock');
  const runProcess = deps.runProcess ?? defaultRunProcess;

  await mkdir(authorityStateDir, { recursive: true }).catch(() => {});

  let previousState: HudAuthorityState | null;
  try {
    previousState = await readAuthorityState(authorityStatePath);
  } catch (error) {
    if (!(await writeInvalidStateDiagnostic(authorityStatePath, authorityOwnerPath, cwd, nowMs, minIntervalMs, jitterMs, error))) {
      throw new Error('failed to persist HUD authority invalid-state diagnostic');
    }
    return;
  }
  const previousNextAllowedMs = parseIsoMs(previousState?.next_allowed_at);
  if (previousState && previousNextAllowedMs !== null && nowMs < previousNextAllowedMs) {
    await writeRateLimitSkipState(
      authorityStatePath,
      authorityOwnerPath,
      cwd,
      nowMs,
      minIntervalMs,
      jitterMs,
      previousState,
      'rate_limited',
    );
    return;
  }

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Check permissions/ownership of the .omx state directory and fix with chown/chmod
2. Free disk space or remount the filesystem read-write
3. Delete or fix the corrupt authority state file that triggered the diagnostic
4. Verify no other process holds an exclusive lock on the diagnostic path

import fs from 'node:fs';
fs.accessSync(dirname(diagnosticPath), fs.constants.W_OK); // preflight writability

catch (e) { if ((e as Error).message === 'failed to persist HUD authority invalid-state diagnostic') { /* log state path, check perms/disk, surface to operator */ } }

When it happens

Trigger: runHudAuthorityTick calls readAuthorityState which throws (invalid state), then writeInvalidStateDiagnostic returns false because the diagnostic file path is unwritable (permissions, read-only FS, missing parent dir), so the wrapper error is thrown.

Common situations: State directory owned by another user, read-only mount or sandboxed filesystem, disk full, or a stray lock/permission change after a crash. Often follows an initial state corruption event.

Related errors

• failed to persist HUD authority rate-limit state
• [omx] warning: failed to create notify fallback watcher stat
• ${label} not found: ${path}
• Missing ${field}.
• autoresearch_candidate_missing:${candidateFile}

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