{"record":{"id":"ee0b14e5e919b376","repo":"Yeachan-Heo/oh-my-codex","slug":"prelaunch-setup-finalization-failed","errorCode":null,"errorMessage":"preLaunch setup finalization failed","messagePattern":"preLaunch setup finalization failed","errorType":"exception","errorClass":"AggregateError","httpStatus":null,"severity":"error","filePath":"src/cli/index.ts","lineNumber":6183,"sourceCode":"  Object.assign(error, { establishmentCleanup: established.cleanup });\n  throw error;\n}\n\nasync function failPreLaunchSetup(binding: LaunchSessionBinding): Promise<void> {\n  const failures: unknown[] = [];\n  try {\n    await finalizeBoundOnce(binding, \"setup-failure\");\n  } catch (error) {\n    failures.push(error);\n  } finally {\n    try {\n      const close = await closeLaunchSessionBindingOnce(binding);\n      if (close.status === \"failed\") failures.push(close.error ?? new Error(\"bound session close failed\"));\n    } catch (error) {\n      failures.push(error);\n    }\n  }\n  if (failures.length > 0) throw new AggregateError(failures, \"preLaunch setup finalization failed\");\n}\n\nasync function completePreLaunchSetup(\n  cwd: string,\n  sessionId: string,\n  notifyTempContract: NotifyTempContract | undefined,\n  codexHomeOverride: string | undefined,\n  enableNotifyFallbackAuthority: boolean,\n  worktreeDirty: boolean,\n): Promise<CompletionResult> {\n  const degraded: DegradedSetupOperation[] = [];\n  try {\n    const cleanup = await cleanupLaunchOrphanedMcpProcesses();\n    if (cleanup.terminatedCount > 0) console.log(`[omx] Reaped ${cleanup.terminatedCount} orphaned OMX MCP process(es) before launch.`);\n    if (cleanup.failedPids.length > 0) console.warn(`[omx] Failed to reap ${cleanup.failedPids.length} orphaned OMX MCP process(es); continuing launch.`);\n  } catch (error) {\n    degraded.push(\"orphan-reaping\");\n    logCliOperationFailure(error);","sourceCodeStart":6165,"sourceCodeEnd":6201,"githubUrl":"https://github.com/Yeachan-Heo/oh-my-codex/blob/3ad79a8a6fe6e95fdbb8c00e40716fffe4011ce2/src/cli/index.ts#L6165-L6201","documentation":"During pre-launch setup finalization, one or more cleanup/close steps failed; the individual errors are collected and rethrown as an AggregateError with the message 'preLaunch setup finalization failed'. It signals that teardown of launch artifacts (e.g. bound session close) partially failed, not that the original launch setup itself failed.","triggerScenarios":"The finalization loop runs closeLaunchSessionBindingOnce over bound sessions and collects failures; any throw (IPC close error, missing state file during teardown, tmux command failure while closing) lands in the failures array and triggers the aggregate throw.","commonSituations":"The tmux session died mid-setup so close commands target a dead session; filesystem permission problems removing state files; races where another OMX process already cleaned the binding; disk-full conditions during teardown writes.","solutions":["Inspect the AggregateError's errors array — each entry names the actual failing finalization step and root cause","Verify the tmux session and state files still exist at teardown time; stale references are the usual culprit","Retry the launch once transient races clear; then clean state (remove stale session binding files) if it persists","Check permissions and disk space in the OMX state directory"],"exampleFix":"try {\n  await finalizePreLaunch(binding);\n} catch (e) {\n  if (e instanceof AggregateError) console.error(e.errors); // inspect each underlying failure\n  throw e;\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"function isAggregateFinalizationError(e: unknown): e is AggregateError {\n  return e instanceof AggregateError && e.message === \"preLaunch setup finalization failed\";\n}","tryCatchPattern":"try { await finalize(); } catch (e) { if (isAggregateFinalizationError(e)) { for (const inner of e.errors) log(inner); /* state is partially cleaned; safe to relaunch */ } }","preventionTips":["Inspect AggregateError.errors individually before deciding on remediation","After a failed finalize, verify no orphan tmux session remains before relaunching","Keep the OMX state directory writable and on a fast disk"],"tags":["aggregate-error","cleanup","launch","tmux"],"backgroundTag":"cleanup-step-failed","analyzedSha":"3ad79a8a6fe6e95fdbb8c00e40716fffe4011ce2","analyzedAt":"2026-08-27T22:18:39.783Z","schemaVersion":2},"datasetVersion":"2026-08-28T00:17:15.603Z"}