Hmbown/CodeWhale · error · anyhow::Error

running tmux lane `{}` has incomplete pinned session metadat

Error message

running tmux lane `{}` has incomplete pinned session metadata; refusing unsafe stop

What it means

TmuxRuntime::stop runs inside the fenced Stopped transition: for a Running lane it must kill the pinned tmux session, so it requires both tmux_socket and tmux_session on the record. A Running record missing either field bails here — the runtime refuses to guess which session to kill, trading a hard error for the risk of terminating an unrelated session.

Source

Thrown at crates/lane/src/runtime.rs:852

        &self,
        registry: &LaneRegistry,
        record: &mut LaneRecord,
        fence: Option<u64>,
    ) -> Result<TerminalTransition> {
        let dry_run = std::env::var_os("CODEWHALE_LANE_TMUX_DRY_RUN").is_some();
        let transition = registry.mark_terminal_if_active_fenced(
            record,
            LaneStatus::Stopped,
            fence,
            |current| {
                if !dry_run {
                    match (
                        current.tmux_socket.as_deref(),
                        current.tmux_session.as_deref(),
                    ) {
                        (Some(socket), Some(session)) => stop_tmux_session(socket, session)?,
                        _ if current.status == LaneStatus::Running => {
                            bail!(
                                "running tmux lane `{}` has incomplete pinned session metadata; refusing unsafe stop",
                                current.id
                            );
                        }
                        _ => {}
                    }
                }
                Ok(())
            },
        )?;
        if transition.transitioned() {
            append_log_event(
                &record.log_path,
                serde_json::json!({
                    "type": "lane_stopped",
                    "lane_id": record.id,
                    "session": record.tmux_session,
                }),

View on GitHub (pinned to 0c42157ee5)

Solutions

1. Find the real session manually (tmux -S <socket> list-sessions across candidate sockets) and kill-session it yourself, then let reconciliation finalize the lane state
2. Repair the record: restore tmux_socket/tmux_session values if recoverable, then retry the stop
3. If the lane is obsolete, remove its registry entry through supported paths rather than forcing the transition
4. Going forward, ensure records are only produced by current runtime versions so metadata stays pinned

fn lane_safe_to_stop(record: &LaneRecord) -> bool {
    match record.status {
        LaneStatus::Running => record.tmux_socket.is_some() && record.tmux_session.is_some(),
        _ => true,
    }
}

if !lane_safe_to_stop(&record) {
    // repair metadata or stop the session manually before calling stop()
}

fn lane_has_pinned_session(record: &LaneRecord) -> bool {
    record.tmux_socket.is_some() && record.tmux_session.is_some()
}

When it happens

Trigger: Stopping a Running tmux lane whose record lacks tmux_socket/tmux_session: records written by an older version before metadata pinning, hand-edited registry files, or a migration that dropped fields.

Common situations: Upgrading the tool over an old lane registry; state files edited or partially restored from backup; external code writing lane records without the pinned fields.

Related errors

• running tmux lane `{}` lacks pinned socket/session metadata;
• tmux runtime is unavailable: `tmux -V` failed with {}: {}
• tmux has-session for {session} failed with {}: {}
• tmux session {session} remains active after kill-session ({s
• tmux runtime requires a non-empty command

AI-assisted analysis of Hmbown/CodeWhale@0c42157ee5 (2026-08-20). Data as JSON: /api/errors/f95db5ebd7925fac. Report an issue: GitHub.