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

tmux pane is not proven live: ${normalizedLeaderPaneId}

Error message

tmux pane is not proven live: ${normalizedLeaderPaneId}

What it means

Thrown by restoreStandaloneHudPane when the tmux leader pane cannot be proven live. The library calls readExactPaneProofSync(normalizedLeaderPaneId) and refuses to act when the proof comes back with status 'gone' — meaning tmux no longer reports a pane with that exact pane_id. Because pane splits are irreversible without durable cleanup state, the function aborts before creating any HUD pane.

Source

Thrown at src/team/tmux-session.ts:3004

export function restoreStandaloneHudPane(
  leaderPaneId: string | null | undefined,
  cwd: string,
  options: RestoreStandaloneHudPaneOptions = {},
): string | null {
  const normalizedLeaderPaneId = normalizePaneTarget(leaderPaneId);
  if (!normalizedLeaderPaneId) return null;
  // The split is irreversible without a durable cleanup obligation. Validate
  // its canonical Team-root location before authorizing any pane effect.
  restoredHudCleanupDebtPath(cwd, options.stateRoot);

  const omxEntry = resolveOmxCliEntryPath();
  if (!omxEntry || omxEntry.trim() === '') return null;

  const leaderPanePid = (() => {
    const proof = readExactPaneProofSync(normalizedLeaderPaneId);
    if (proof.status === 'unavailable') throw new ExactPaneProofUnavailableError(proof);
    if (proof.status === 'gone') throw new Error(`tmux pane is not proven live: ${normalizedLeaderPaneId}`);
    if (options.expectedLeaderPanePid !== undefined && proof.pid !== options.expectedLeaderPanePid) {
      throw new Error(`tmux pane identity changed: ${normalizedLeaderPaneId}`);
    }
    return proof.pid;
  })();
  const requireAuthorizedLeaderPane = (): string => {
    options.assertLeaderPaneAuthorization?.();
    return requireLiveExactPaneSync(normalizedLeaderPaneId, options.expectedLeaderPanePid ?? leaderPanePid);
  };
  requireAuthorizedLeaderPane();

  const paneListResult = listPanesResult(normalizedLeaderPaneId);
  if (paneListResult.error) throw new Error(`failed to read tmux pane topology: ${paneListResult.error}`);
  const [existingHudPaneId, ...duplicateHudPaneIds] = findHudWatchPaneIds(
    paneListResult.panes,
    normalizedLeaderPaneId,
    { leaderPaneId: normalizedLeaderPaneId },
  );

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Verify the pane still exists before calling: tmux list-panes -a -F '#{pane_id}' and confirm the id
2. Re-discover the current leader pane id and pass that instead of a stale one
3. If tmux was restarted, re-run session bootstrap to get fresh pane ids
4. Pass options.expectedLeaderPanePid and handle identity errors so races surface deterministically

Example fix

// before
restoreStandaloneHudPane('%5', cwd, {});
// after
const live = runTmux(['display-message', '-p', '-t', '%5', '#{pane_id}']);
if (!live.ok) throw new Error('leader pane gone; re-discover pane id');
restoreStandaloneHudPane('%5', cwd, {});

import { execSync } from 'node:child_process';
function leaderPaneExists(paneId: string): boolean {
  try {
    execSync(`tmux display-message -p -t ${paneId} '#{pane_id}'`, { stdio: 'pipe' });
    return true;
  } catch { return false; }
}

function isLivePaneId(v: string | null | undefined): v is string {
  return typeof v === 'string' && /^%\d+$/.test(v) && leaderPaneExists(v);
}

try { restoreStandaloneHudPane(leaderPaneId, cwd, opts); } catch (e) { if (e instanceof Error && e.message.startsWith('tmux pane is not proven live')) { /* re-discover leader pane and retry once */ } else throw e; }

When it happens

Trigger: Calling restoreStandaloneHudPane(leaderPaneId, cwd, options) where the supplied leader pane id (after normalizePaneTarget) no longer exists — e.g. the pane or its window/session was closed, tmux was restarted, or a stale pane id from a previous session was reused.

Common situations: Leader pane exited or was killed between discovery and restore; tmux server killed/restarted so all pane ids are invalid; leaderPaneId captured from an old session file or environment variable; race with another tool that reorganized windows ('break-pane', 'kill-window').

Related errors

• shutdown_${scope}_${kind.replaceAll(' ', '_')}_identity_chan
• failed to capture tmux source authority: ${result.stderr}
• invalid auth slot path
• ${label} is not a file: ${path}
• ${label} not found: ${path}

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