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

restored_hud_split_output_ambiguous

Error message

restored_hud_split_output_ambiguous

What it means

Thrown by restoreStandaloneHudPane when split-window reported success but parseSplitWindowPaneId(hudResult.stdout) returned null AND topology reconciliation could not identify exactly one new pane — either zero or multiple new panes matched the receipt filter, or none matched at all. The library deliberately throws rather than guess which pane is the HUD, because a wrong guess would orphan an untracked irreversible split.

Source

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

        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);
      if (reconciledProof.status === 'gone') throw new Error(`tmux pane is not proven live: ${reconciledPaneId}`);
      persistRestoredHudCleanupDebtSync(cwd, {
        schema_version: 1,
        operation: 'restored_hud_cleanup',
        pane_id: reconciledPaneId,
        pane_pid: reconciledProof.pid,
        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);
    }
    throw new Error('restored_hud_split_output_ambiguous');
  }
  persistRestoredHudCleanupDebtSync(cwd, {
    schema_version: 1,
    operation: 'restored_hud_cleanup',
    pane_id: paneId,
    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 hudPanePid = (() => {
    const proof = readExactPaneProofSync(paneId);
    if (proof.status === 'unavailable') throw new ExactPaneProofUnavailableError(proof);
    if (proof.status === 'gone') throw new Error(`tmux pane is not proven live: ${paneId}`);
    return proof.pid;
  })();

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Manually inspect tmux list-panes -a -F '#{pane_id} #{pane_start_command}' and kill any orphaned receipt-tagged HUD pane
2. Verify the tmux version emits pane ids with split-window -P -F
3. Ensure the HUD command actually starts (test node <entry> hud --watch by hand)
4. Reduce concurrent pane churn during restore, then retry

// Reduce ambiguity: capture topology immediately before split and avoid other pane churn
const before = execSync(`tmux list-panes -a -F '#{pane_id} #{pane_start_command}'`).toString();

try { restoreStandaloneHudPane(id, cwd, opts); } catch (e) { if (e instanceof Error && e.message === 'restored_hud_split_output_ambiguous') { /* list panes, kill any receipt-tagged orphans manually, then retry */ } else throw e; }

When it happens

Trigger: split-window -P -F '#{pane_id}' succeeded but printed no usable pane id, and the before/after list-panes diff filtered by splitReceipt yields != 1 candidate: HUD died instantly (0), an unrelated pane appeared concurrently (2+), or the receipt string is absent from pane_start_command.

Common situations: tmux builds/options that suppress -P output; panes spawned by other tooling during the restore window; HUD command failing to launch so no receipt-tagged pane exists; start_command truncation hiding the receipt.

Related errors

• restored_hud_split_topology_reconciliation_failed
• invalid auth slot path
• auth directory must not be a symlink: ${dir}
• auth path is not a directory: ${dir}
• ${label} is not a file: ${path}

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