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

restored_hud_split_topology_reconciliation_failed

Error message

restored_hud_split_topology_reconciliation_failed

What it means

Thrown by restoreStandaloneHudPane during fallback reconciliation: the split-window -P -F '#{pane_id}' output could not be parsed (parseSplitWindowPaneId returned null), so the code re-reads the pane topology to identify the new pane by its split receipt — and that second listPanesResult call itself failed. The new HUD pane may exist, but the library can neither confirm nor record cleanup debt for it, so it throws.

Source

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

      '-P',
      '-F',
      '#{pane_id}',
      '-c',
      translatePathForMsys(restoreCwd.rawPath),
      hudCmd,
    ], true);
    if (candidateResult.ok) {
      hudResult = candidateResult;
      break;
    }
  }
  if (!hudResult?.ok) return null;

  const paneId = parseSplitWindowPaneId(hudResult.stdout);
  if (!paneId) {
    const afterTopology = listPanesResult(normalizedLeaderPaneId);
    if (afterTopology.error) {
      throw new Error('restored_hud_split_topology_reconciliation_failed');
    }
    const newlyObservedPaneIds = afterTopology.panes
      .filter((pane) => !beforeSplitPaneIds.has(pane.paneId) && pane.startCommand.includes(splitReceipt))
      .map((pane) => pane.paneId);
    if (newlyObservedPaneIds.length === 1) {
      const reconciledPaneId = newlyObservedPaneIds[0]!;
      persistRestoredHudCleanupDebtSync(cwd, {
        schema_version: 1,
        operation: 'restored_hud_cleanup',
        pane_id: reconciledPaneId,
        pane_pid: null,
        leader_pane_id: normalizedLeaderPaneId,
        leader_pane_pid: options.expectedLeaderPanePid ?? leaderPanePid,
        leader_pane_owner_id: options.expectedLeaderPaneOwnerId?.trim() || null,
        hud_owner_leader_pane_id: normalizedLeaderPaneId,
      }, options.stateRoot);
      const reconciledProof = readExactPaneProofSync(reconciledPaneId);
      if (reconciledProof.status === 'unavailable') throw new ExactPaneProofUnavailableError(reconciledProof);

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Inspect tmux state manually (tmux list-panes -a) to see if the HUD pane was actually created; if so, kill it or register cleanup manually before retrying
2. Retry the restore — most causes are transient topology-read races
3. Check tmux version supports -P -F on split-window (older builds silently omit output)
4. Ensure nothing else kills the session while restore runs

try { restoreStandaloneHudPane(id, cwd, opts); } catch (e) { if (e instanceof Error && e.message === 'restored_hud_split_topology_reconciliation_failed') { /* check list-panes for an orphan receipt-tagged pane; clean up; retry */ } else throw e; }

When it happens

Trigger: runTmux split-window succeeded but stdout had no parseable pane id, and the subsequent tmux list-panes query errored (dead server, session destroyed mid-call, malformed output).

Common situations: tmux server/session torn down concurrently with the restore; tmux build that ignores -P/-F output; output parsing broken by locale/format changes; flaky tmux socket under load.

Related errors

• restored_hud_split_output_ambiguous
• invalid auth slot path
• ${label} is not a file: ${path}
• Refusing to overwrite existing ${repoRelative(cwd, missionPa
• shutdown_${scope}_${kind.replaceAll(' ', '_')}_identity_chan

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