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

shutdown_shared_session_topology_unavailable:${sharedSession

Error message

shutdown_shared_session_topology_unavailable:${sharedSessionTopology.detail}

What it means

In interactive worker_launch_mode with a shared tmux session name (containing ':'), shutdown resolves a shared-session topology; if that resolution returns status 'unavailable' the shutdown aborts, embedding the detail reason.

Source

Thrown at src/team/runtime.ts:4999

        : `allowed=${gate.allowed} total=${gate.total} pending=${gate.pending} blocked=${gate.blocked} in_progress=${gate.in_progress} completed=${gate.completed} failed=${gate.failed} cleanup_requires_all_workers_inactive=${governance.cleanup_requires_all_workers_inactive} dirty_workers=${dirtyWorkers.join('|') || 'none'} confirm_issues=${confirmIssues} clean_fast_path=${useCleanFastPath}`,
    },
    cwd,
  ).catch(() => {});

  if (force) {
    // Explicit force means teardown now. Do not spend the graceful ack window
    // waiting for interactive panes or prompt workers that will be killed below.
    skipWorkerAcks = true;
  } else {
    skipWorkerAcks = useCleanFastPath;
  }

  const sessionName = config.tmux_session;
  const sharedSessionTopology = config.worker_launch_mode === 'interactive' && sessionName.includes(':')
    ? resolveSharedSessionShutdownTopology(sessionName, config.leader_pane_id, sanitized)
    : null;
  if (sharedSessionTopology?.status === 'unavailable') {
    throw new Error(`shutdown_shared_session_topology_unavailable:${sharedSessionTopology.detail}`);
  }
  if (typeof config.hud_pane_id === 'string' && /^%[0-9]+$/.test(config.hud_pane_id)
    && typeof config.hud_pane_pid === 'number' && Number.isSafeInteger(config.hud_pane_pid) && config.hud_pane_pid > 0) {
    const persistedHudProof = readExactPaneProofSync(config.hud_pane_id);
    if (persistedHudProof.status === 'live' && persistedHudProof.pid !== config.hud_pane_pid) {
      throw new Error(`shutdown_shared_session_HUD_pane_identity_changed:${config.hud_pane_id}`);
    }
  }
  const dispatchPolicy = resolveDispatchPolicy(manifest?.policy, config.worker_launch_mode);
  const shutdownRequestTimes = new Map<string, string>();

  if (!skipWorkerAcks) {
    // 1. Send shutdown inbox to each worker
    for (const w of config.workers) {
      try {
        const requestedAt = new Date().toISOString();
        await writeShutdownRequest(sanitized, w.name, 'leader-fixed', cwd);
        shutdownRequestTimes.set(w.name, requestedAt);

View on GitHub (pinned to 3ad79a8a6f)

Solutions

Verify the tmux session exists and its panes match the team config (list-panes) before shutdown
Repair the recorded leader_pane_id / session name in team config to match reality, then retry
If the session is already gone, clean up residual team state manually or recreate the team

Example fix

# before
omx team shutdown myteam

# after
tmux list-panes -t 'myteam:0' -F '#{pane_id}'
omx team shutdown myteam

Defensive patterns

Strategy: validation

Validate before calling

const topology = resolveSharedSessionShutdownTopology(config.tmux_session, config.leader_pane_id, teamName);
if (topology?.status === 'unavailable') throw new Error(topology.detail);

Try / catch

try { await shutdownTeam(t, cwd, {}); } catch (e) { if (/^shutdown_shared_session_topology_unavailable:/.test((e as Error).message)) { await repairSessionTopology(t); await shutdownTeam(t, cwd, {}); } else throw e; }

Prevention

Do not rename or restructure team tmux sessions manually
Verify session and leader pane exist before shutdown
Keep config.tmux_session / leader_pane_id in sync with reality

When it happens

Trigger: Shutting down a team in interactive/shared-session mode where resolveSharedSessionShutdownTopology cannot resolve the topology — e.g. the tmux session/pane structure does not match the recorded leader pane, or the session no longer exists in the expected form.

Common situations: tmux session renamed or destroyed out-of-band; leader pane ID recorded in config no longer present; shared-session naming convention violated by manual tmux edits.

Related errors

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