{"record":{"id":"e1740ce8d2a91453","repo":"Yeachan-Heo/oh-my-codex","slug":"bound-setup-finalization-denied-finalization-cl","errorCode":null,"errorMessage":"bound setup finalization denied: ${finalization.cleanup.comparison?.reason ?? \"unknown reason\"}","messagePattern":"bound setup finalization denied: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"src/cli/index.ts","lineNumber":7065,"sourceCode":"  const nonce = payload.readyPath?.split(\".\").at(-2) || payload.sessionId;\n  const contextKey = process.env[OMX_MADMAX_DETACHED_CONTEXT_ENV]?.trim();\n  const activeRecordPath = contextKey\n    ? madmaxDetachedActiveRecordPath(resolveMadmaxRunsRoot(process.env), contextKey)\n    : join(omxRoot(payload.cwd), \"state\", \"detached-active-record.json\");\n  let externalInterrupt: NodeJS.Signals | undefined;\n\n  try {\n    const completion = await completePreLaunchSetup(\n      payload.cwd,\n      payload.sessionId,\n      payload.preLaunchOptions.notifyTempContract,\n      payload.codexHomeOverride,\n      payload.preLaunchOptions.enableNotifyFallbackAuthority,\n      payload.preLaunchOptions.worktreeDirty,\n    );\n    if (completion.kind === \"failure\") {\n      const finalization = await finalizeBoundOnce(binding, \"setup-failure\", payload.cwd);\n      if (!finalization.finalized) throw new Error(`bound setup finalization denied: ${finalization.cleanup.comparison?.reason ?? \"unknown reason\"}`);\n      throw completion.error;\n    }\n    const record: MadmaxDetachedActiveRecord = {\n      version: 1, context_key: contextKey ?? payload.sessionId!, created_at: new Date().toISOString(),\n      source_cwd: payload.cwd, argv: [payload.codexCmd], run_dir: process.env.OMX_ROOT ?? payload.cwd,\n      tmux_session_name: payload.sessionName, session_id: payload.sessionId, tmux_pane_id: pane,\n      launch_nonce: nonce, leader_pid: process.pid, base_state_root: binding.context.baseStateDir,\n      lifecycle_phase: \"ready\",\n    };\n    const runtimeBinding = queryMadmaxDetachedRuntimeBinding(record);\n    ownedRecord = writeMadmaxDetachedActiveRecord(activeRecordPath, {\n      ...record,\n      ...(runtimeBinding ? {\n        tmux_internal_session_id: runtimeBinding.internalSessionId,\n        tmux_session_created: runtimeBinding.sessionCreated,\n        tmux_pane_pid: runtimeBinding.panePid,\n      } : {}),\n    });","sourceCodeStart":7047,"sourceCodeEnd":7083,"githubUrl":"https://github.com/Yeachan-Heo/oh-my-codex/blob/3ad79a8a6fe6e95fdbb8c00e40716fffe4011ce2/src/cli/index.ts#L7047-L7083","documentation":"When bound setup fails, the leader attempts to finalize/close the launch binding once; if finalization is denied (binding state comparison mismatch), this wrapped error is thrown instead of the underlying failure.","triggerScenarios":"completeBoundSetup returns kind 'failure' AND finalizeBoundOnce(binding, 'setup-failure', cwd) reports finalized=false, i.e. the binding's expected state no longer matches (already finalized, taken over, or mutated by another process).","commonSituations":"Two CLI processes racing over the same session binding, a leftover binding file from a previous crashed run, or clock/state version skew after an upgrade.","solutions":["Inspect the binding file/state to see why the comparison failed (the reason is embedded in the message)","Remove the stale binding / active record for that session and retry the launch","Ensure only one parent CLI orchestrates a given session at a time"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { await runBoundSetup(...); } catch (e) {\n  if ((e as Error).message.startsWith('bound setup finalization denied')) {\n    // binding state conflicted: inspect/clear the binding, then re-launch\n  } else throw e;\n}","preventionTips":["Run one orchestration process per session","Clean up active records after crashes","Avoid downgrading CLI versions mid-session"],"tags":["state-machine","race-condition","detached-session"],"backgroundTag":"invalid-state-transition","analyzedSha":"3ad79a8a6fe6e95fdbb8c00e40716fffe4011ce2","analyzedAt":"2026-08-27T22:18:39.783Z","schemaVersion":2},"datasetVersion":"2026-08-28T00:17:15.603Z"}