{"record":{"id":"f4f8c870ff755c16","repo":"Yeachan-Heo/oh-my-codex","slug":"tmux-pane-is-not-proven-live-normalizedleaderpa","errorCode":null,"errorMessage":"tmux pane is not proven live: ${normalizedLeaderPaneId}","messagePattern":"tmux pane is not proven live: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/team/tmux-session.ts","lineNumber":3004,"sourceCode":"\nexport function restoreStandaloneHudPane(\n  leaderPaneId: string | null | undefined,\n  cwd: string,\n  options: RestoreStandaloneHudPaneOptions = {},\n): string | null {\n  const normalizedLeaderPaneId = normalizePaneTarget(leaderPaneId);\n  if (!normalizedLeaderPaneId) return null;\n  // The split is irreversible without a durable cleanup obligation. Validate\n  // its canonical Team-root location before authorizing any pane effect.\n  restoredHudCleanupDebtPath(cwd, options.stateRoot);\n\n  const omxEntry = resolveOmxCliEntryPath();\n  if (!omxEntry || omxEntry.trim() === '') return null;\n\n  const leaderPanePid = (() => {\n    const proof = readExactPaneProofSync(normalizedLeaderPaneId);\n    if (proof.status === 'unavailable') throw new ExactPaneProofUnavailableError(proof);\n    if (proof.status === 'gone') throw new Error(`tmux pane is not proven live: ${normalizedLeaderPaneId}`);\n    if (options.expectedLeaderPanePid !== undefined && proof.pid !== options.expectedLeaderPanePid) {\n      throw new Error(`tmux pane identity changed: ${normalizedLeaderPaneId}`);\n    }\n    return proof.pid;\n  })();\n  const requireAuthorizedLeaderPane = (): string => {\n    options.assertLeaderPaneAuthorization?.();\n    return requireLiveExactPaneSync(normalizedLeaderPaneId, options.expectedLeaderPanePid ?? leaderPanePid);\n  };\n  requireAuthorizedLeaderPane();\n\n  const paneListResult = listPanesResult(normalizedLeaderPaneId);\n  if (paneListResult.error) throw new Error(`failed to read tmux pane topology: ${paneListResult.error}`);\n  const [existingHudPaneId, ...duplicateHudPaneIds] = findHudWatchPaneIds(\n    paneListResult.panes,\n    normalizedLeaderPaneId,\n    { leaderPaneId: normalizedLeaderPaneId },\n  );","sourceCodeStart":2986,"sourceCodeEnd":3022,"githubUrl":"https://github.com/Yeachan-Heo/oh-my-codex/blob/3ad79a8a6fe6e95fdbb8c00e40716fffe4011ce2/src/team/tmux-session.ts#L2986-L3022","documentation":"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.","triggerScenarios":"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.","commonSituations":"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').","solutions":["Verify the pane still exists before calling: tmux list-panes -a -F '#{pane_id}' and confirm the id","Re-discover the current leader pane id and pass that instead of a stale one","If tmux was restarted, re-run session bootstrap to get fresh pane ids","Pass options.expectedLeaderPanePid and handle identity errors so races surface deterministically"],"exampleFix":"// before\nrestoreStandaloneHudPane('%5', cwd, {});\n// after\nconst live = runTmux(['display-message', '-p', '-t', '%5', '#{pane_id}']);\nif (!live.ok) throw new Error('leader pane gone; re-discover pane id');\nrestoreStandaloneHudPane('%5', cwd, {});","handlingStrategy":"validation","validationCode":"import { execSync } from 'node:child_process';\nfunction leaderPaneExists(paneId: string): boolean {\n  try {\n    execSync(`tmux display-message -p -t ${paneId} '#{pane_id}'`, { stdio: 'pipe' });\n    return true;\n  } catch { return false; }\n}","typeGuard":"function isLivePaneId(v: string | null | undefined): v is string {\n  return typeof v === 'string' && /^%\\d+$/.test(v) && leaderPaneExists(v);\n}","tryCatchPattern":"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; }","preventionTips":["Capture the leader pane id immediately before restore, never from long-lived persisted state","Treat pane ids as invalid after any tmux server restart","Handle the gone case by re-running session discovery instead of retrying the same id"],"tags":["tmux","pane-lifecycle","stale-id","race-condition"],"backgroundTag":"tmux-pane-not-found","analyzedSha":"3ad79a8a6fe6e95fdbb8c00e40716fffe4011ce2","analyzedAt":"2026-08-27T22:18:39.783Z","schemaVersion":2},"datasetVersion":"2026-08-28T00:17:15.603Z"}