{"record":{"id":"9b40b4aed96e4952","repo":"Yeachan-Heo/oh-my-codex","slug":"restored-hud-cleanup-debt-unresolved-debt-pane-i","errorCode":null,"errorMessage":"restored_hud_cleanup_debt_unresolved:${debt.pane_id}","messagePattern":"restored_hud_cleanup_debt_unresolved:(.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/team/tmux-session.ts","lineNumber":534,"sourceCode":"  syncRestoredHudDebtParentSync(path);\n}\n\n/**\n * Replays a prior restored-HUD obligation. A live pane is killable only when\n * its recorded PID, HUD command identity, and tagged leader identity all\n * still match; PID-less and ambiguous records remain durable debt.\n */\nexport function reconcileRestoredHudCleanupDebtSync(cwd: string, stateRoot?: string | null): void {\n  const record = parseRestoredHudCleanupDebtSync(cwd, stateRoot);\n  if (!record) return;\n  const { path, debt } = record;\n  const proof = readExactPaneProofSync(debt.pane_id);\n  if (proof.status === 'gone') {\n    removeRestoredHudCleanupDebtSync(path);\n    return;\n  }\n  if (proof.status !== 'live' || debt.pane_pid === null || proof.pid !== debt.pane_pid || !debt.leader_pane_owner_id) {\n    throw new Error(`restored_hud_cleanup_debt_unresolved:${debt.pane_id}`);\n  }\n  const leader = requireLiveTeamOwnedPaneSync(debt.leader_pane_id, debt.leader_pane_pid, debt.leader_pane_owner_id);\n  const topology = listPanesResult(leader);\n  const hudMatches = !topology.error && topology.panes.filter((pane) => pane.paneId === proof.paneId\n    && hudPaneMatchesOwner(pane, { leaderPaneId: debt.hud_owner_leader_pane_id })).length === 1;\n  if (!hudMatches) throw new Error(`restored_hud_cleanup_debt_unresolved:${debt.pane_id}`);\n  killExactPaneSync(proof.paneId, debt.pane_pid, () => {\n    requireLiveTeamOwnedPaneSync(debt.leader_pane_id, debt.leader_pane_pid, debt.leader_pane_owner_id!);\n  });\n  removeRestoredHudCleanupDebtSync(path);\n}\n\n/** Remove restored-HUD debt only after the canonical config transaction commits the same frozen identity. */\nexport function finalizeRestoredHudCleanupDebtSync(\n  cwd: string,\n  paneId: string,\n  panePid: number,\n  stateRoot?: string | null,","sourceCodeStart":516,"sourceCodeEnd":552,"githubUrl":"https://github.com/Yeachan-Heo/oh-my-codex/blob/3ad79a8a6fe6e95fdbb8c00e40716fffe4011ce2/src/team/tmux-session.ts#L516-L552","documentation":"While replaying a persisted 'HUD cleanup debt' (a HUD pane that had to be killed on shutdown but could not be verified then), the recorded HUD pane is proven live with the right PID but the debt record lacks a leader_pane_owner_id — so authorization for the kill cannot be established and the debt is left unresolved (fail-closed).","triggerScenarios":"Restoring a team session whose persisted cleanup-debt JSON has leader_pane_owner_id missing/null (old format or truncated write), while the HUD pane still exists and matches its recorded PID.","commonSituations":"Upgrading between versions that changed the debt record schema; state file corrupted by a crash mid-write; leftover debt from an experimentally modified session.","solutions":["Inspect the debt record under the team state root and manually kill the leftover HUD pane (`tmux kill-pane -t <pane_id>`) once verified","Delete the stale debt record only after confirming the HUD pane is gone","Regenerate the session state by recreating the team session"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"const debt = readDebt(stateRoot); if (debt && !debt.leader_pane_owner_id) flagForManualCleanup(debt.pane_id);","typeGuard":null,"tryCatchPattern":"catch (e) { if (/restored_hud_cleanup_debt_unresolved/.test(e.message)) { queueManualCleanup(e.message.split(':').pop()); return; } throw e; }","preventionTips":["Back up state-root files before upgrades","Let shutdown complete fully so debts are resolved synchronously when possible"],"tags":["tmux","state-recovery","hud","shutdown-debt"],"backgroundTag":"stale-persisted-state","analyzedSha":"3ad79a8a6fe6e95fdbb8c00e40716fffe4011ce2","analyzedAt":"2026-08-27T22:18:39.783Z","schemaVersion":2},"datasetVersion":"2026-08-28T00:17:15.603Z"}