{"record":{"id":"6a055b5b4ffa5919","repo":"Yeachan-Heo/oh-my-codex","slug":"restored-hud-split-output-ambiguous","errorCode":null,"errorMessage":"restored_hud_split_output_ambiguous","messagePattern":"restored_hud_split_output_ambiguous","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/team/tmux-session.ts","lineNumber":3132,"sourceCode":"        leader_pane_pid: options.expectedLeaderPanePid ?? leaderPanePid,\n        leader_pane_owner_id: options.expectedLeaderPaneOwnerId?.trim() || null,\n        hud_owner_leader_pane_id: normalizedLeaderPaneId,\n      }, options.stateRoot);\n      const reconciledProof = readExactPaneProofSync(reconciledPaneId);\n      if (reconciledProof.status === 'unavailable') throw new ExactPaneProofUnavailableError(reconciledProof);\n      if (reconciledProof.status === 'gone') throw new Error(`tmux pane is not proven live: ${reconciledPaneId}`);\n      persistRestoredHudCleanupDebtSync(cwd, {\n        schema_version: 1,\n        operation: 'restored_hud_cleanup',\n        pane_id: reconciledPaneId,\n        pane_pid: reconciledProof.pid,\n        leader_pane_id: normalizedLeaderPaneId,\n        leader_pane_pid: options.expectedLeaderPanePid ?? leaderPanePid,\n        leader_pane_owner_id: options.expectedLeaderPaneOwnerId?.trim() || null,\n        hud_owner_leader_pane_id: normalizedLeaderPaneId,\n      }, options.stateRoot);\n    }\n    throw new Error('restored_hud_split_output_ambiguous');\n  }\n  persistRestoredHudCleanupDebtSync(cwd, {\n    schema_version: 1,\n    operation: 'restored_hud_cleanup',\n    pane_id: paneId,\n    pane_pid: null,\n    leader_pane_id: normalizedLeaderPaneId,\n    leader_pane_pid: options.expectedLeaderPanePid ?? leaderPanePid,\n    leader_pane_owner_id: options.expectedLeaderPaneOwnerId?.trim() || null,\n    hud_owner_leader_pane_id: normalizedLeaderPaneId,\n  }, options.stateRoot);\n\n  const hudPanePid = (() => {\n    const proof = readExactPaneProofSync(paneId);\n    if (proof.status === 'unavailable') throw new ExactPaneProofUnavailableError(proof);\n    if (proof.status === 'gone') throw new Error(`tmux pane is not proven live: ${paneId}`);\n    return proof.pid;\n  })();","sourceCodeStart":3114,"sourceCodeEnd":3150,"githubUrl":"https://github.com/Yeachan-Heo/oh-my-codex/blob/3ad79a8a6fe6e95fdbb8c00e40716fffe4011ce2/src/team/tmux-session.ts#L3114-L3150","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Manually inspect tmux list-panes -a -F '#{pane_id} #{pane_start_command}' and kill any orphaned receipt-tagged HUD pane","Verify the tmux version emits pane ids with split-window -P -F","Ensure the HUD command actually starts (test node <entry> hud --watch by hand)","Reduce concurrent pane churn during restore, then retry"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"// Reduce ambiguity: capture topology immediately before split and avoid other pane churn\nconst before = execSync(`tmux list-panes -a -F '#{pane_id} #{pane_start_command}'`).toString();","typeGuard":null,"tryCatchPattern":"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; }","preventionTips":["Do not spawn other panes while a restore is in flight","Use a tmux version that prints pane ids from split-window -P -F","Guarantee the HUD command starts so exactly one receipt-tagged pane exists"],"tags":["tmux","split-window","ambiguity","reconciliation"],"backgroundTag":"ambiguous-subprocess-output","analyzedSha":"3ad79a8a6fe6e95fdbb8c00e40716fffe4011ce2","analyzedAt":"2026-08-27T22:18:39.783Z","schemaVersion":2},"datasetVersion":"2026-08-28T00:17:15.603Z"}