[BUG] find_available_port probe-then-rebind races; create_server has no retry → EADDRINUSE with parallel Neovim instances (regression in #282)

[PMassicotte]

Summary

Since 9ecf9f3 (merge of #282), running a second Neovim instance can fail to start the WebSocket server with:

[ClaudeCode] [init] [ERROR] Failed to start Claude Code server: Failed to listen on port 48811: EADDRINUSE: address already in use
[ClaudeCode] [command] [ERROR] ClaudeCodeAdd: Claude Code integration is not running.

This is a regression. Running multiple Neovim instances in parallel (each with its own integration) worked reliably before this commit.

Root cause

lua/claudecode/server/tcp.lua was rewritten in #282. find_available_port now probes a candidate port by binding a throwaway test socket, closing it, and returning the port:

local test_server = vim.loop.new_tcp()
local success = test_server:bind("127.0.0.1", port)
test_server:close()
if success then
    return port
end

create_server then creates a new TCP handle and binds + listen()s on that same port. Two problems:

1. TOCTOU race / unreliable probe. The check and the use are separate sockets. Because libuv sets SO_REUSEADDR, the throwaway bind() can succeed even when another process is already listening on the port, so the real listen() is what fails with EADDRINUSE — matching the error text ("Failed to listen on port ...", the listen step, not bind).
2. No retry/fallback. The port is selected once at server/init.lua:95; on bind/listen failure create_server returns an error and gives up rather than trying the next port. So a single collision is a hard failure.

Reproduction

1. Open Neovim instance A; the integration claims a port (e.g. 48811).
2. Open Neovim instance B; if its scan lands on a port already held by another listener, B fails with EADDRINUSE and the integration never starts.

Suggested fix

Either:

• Hold the probe socket open through to listen() (don't close-and-rebind), or
• Loop in create_server: on bind/listen EADDRINUSE, advance to the next candidate from find_available_port and retry across the range before giving up.

Environment

• claudecode.nvim at 9ecf9f3
• Neovim 0.12.2
• Linux

[ThomasK33]

Note

This triage report is AI-generated using Claude Code

Summary

This was reproduced and confirmed as a regression introduced in #282. A second Neovim instance fails to start the WebSocket server, and the reproduction matches the report exactly — including the specific port 48811 and the verbatim error Failed to listen on port 48811: EADDRINUSE: address already in use.

The report's analysis is largely accurate. One refinement emerged during investigation (covered below): the false-positive probe is better explained by libuv's deferred-error handling than by SO_REUSEADDR.

What was reproduced

Two fresh Neovim processes were started against the real plugin (create_server) with the default port range {min=10000, max=65535}:

INSTANCE_A: LISTENING port=48811
INSTANCE_B: [ClaudeCode] [init] [ERROR] Failed to start Claude Code server: Failed to listen on port 48811: EADDRINUSE: address already in use

Notably, the exact port 48811 reproduces on a different OS than the one in the report (the reproduction ran on macOS; the report is on Linux). This cross-platform match is itself a clue — it points at a platform-independent PRNG, not at OS socket semantics.

Root cause

The failure is the intersection of one regression (#282) and two pre-existing latent defects.

The chain on :ClaudeCodeStart:

1. init.start → server.start → tcp.create_server (tcp.lua:57) → find_available_port (tcp.lua:20) → math.random(port_count) (tcp.lua:29).
2. Nothing seeds math.random on this path. The only math.randomseed(os.time()) in production code lives in utils.lua inside shuffle_array, which Speed up coverage test runtime #282 orphaned (it now has zero callers). The only other RNG draw before selection is module_instance_id = math.random(10000, 99999) at server/init.lua:225, which consumes a value but does not seed.
3. Under LuaJIT (Neovim's runtime), math.random's default seed is fixed — unlike PUC Lua 5.4, LuaJIT does not auto-seed. So every fresh process draws the identical offset and selects the identical port. With the module_instance_id draw consumed first, that port is 48811 deterministically; without that prior draw it would be 54107. Either way, all parallel instances land on the same port.
4. Instance B's find_available_port probe — new_tcp():bind() then close(), returning the port if bind "succeeded" (tcp.lua:36-44) — cannot detect that instance A is already listening there. libuv's uv__tcp_bind specifically defers EADDRINUSE into tcp->delayed_error and returns success; the error only replays at listen()/connect(). So the probe returns a false positive.
5. create_server selects that one port, bind() succeeds (the deferred error is swallowed, tcp.lua:79), and listen() surfaces EADDRINUSE (tcp.lua:86), producing the Failed to listen on port … text (tcp.lua:95-98). There is no retry at any layer, so it is a hard failure.

Which defect is which

• New in Speed up coverage test runtime #282 (the regression trigger): find_available_port was rewritten from build-range → utils.shuffle_array(ports) into a direct, unseeded math.random offset. shuffle_array's lazy math.randomseed(os.time()) previously ran as a side effect on the start path and varied selection per process. Removing it made the first probed port deterministic and identical across processes.
• Pre-existing (latent, merely exposed by Speed up coverage test runtime #282): both the false-positive probe and the no-retry create_server predate Speed up coverage test runtime #282 — git show 9ecf9f3^:lua/claudecode/server/tcp.lua shows create_server byte-identical to today. They were simply masked while selection was randomized. In other words, the old code could also collide when two instances launched within the same os.time() second; Speed up coverage test runtime #282 turned that rare race into an every-time failure.

A note on the SO_REUSEADDR explanation

The report attributes the false-positive bind to SO_REUSEADDR. libuv does set SO_REUSEADDR, but on Linux/macOS that does not permit a second socket to bind an (addr, port) already in LISTEN state (that would require SO_REUSEPORT). A discriminating test showed bind() returning success followed by EADDRINUSE at listen() on the same handle — which is only consistent with the OS bind() having returned EADDRINUSE and libuv masking it via delayed_error. The relevant libuv source (src/unix/tcp.c, and src/win/tcp.c for Windows) defers EADDRINUSE specifically, which is why the mechanism is cross-platform and why the user-visible error says "listen", not "bind".

Suggested direction for a fix

A listen()-gated retry loop in create_server over a candidate-port iterator — binding and listening on the same handle the server keeps, rather than probing a throwaway socket — addresses the broken-probe and no-retry defects together, and removes the TOCTOU window. Pairing that with restored once-per-process RNG seeding (using sub-second jitter so two instances launched in the same second still diverge) keeps port selection well-spread.

Seeding alone would not be sufficient: it lowers collision probability but still hard-fails on any genuine collision (same-second launches, or any third-party listener on the chosen port), because the probe still cannot see a live listener and create_server still has no retry. The retry loop is what makes parallel startup robust rather than merely less likely to collide. Keeping find_available_port as a cheap bind-only pre-filter preserves its public signature and existing unit tests; the authoritative check moves to listen() inside the loop.

A condensed sketch of this approach is included in the collapsible section below for discussion.

How this was verified

• A standalone reproduction harness (scripts/repro_issue_283.sh) drives the real plugin and exits non-zero while the bug is present. It checks three things: that port selection is deterministic across fresh processes, that the probe gives a false positive on a busy port while listen() raises EADDRINUSE, and that two real instances collide on the same port. After a fix, Part 1 should vary across processes and Part 3's second instance should start on a different port.
• An interactive run inside a real Neovim TUI surfaced the plugin's own error banner and the Press ENTER prompt, matching what an end user sees in a second instance; a control run with the port free started cleanly on 48811.
• The libuv delayed_error behavior was confirmed against the shipped libuv source (1.52.1) for both the unix and Windows backends.

The reproduction files are included below for review. They contain no secrets, credentials, or machine-specific paths (paths are resolved dynamically at runtime).

scripts/repro_issue_283.sh — automated 3-part reproduction (exits 1 while the bug is present)

#!/usr/bin/env bash
# Reproduction / verification for issue #283:
#   "find_available_port probe-then-rebind races; create_server has no retry ->
#    EADDRINUSE with parallel Neovim instances (regression in #282)"
#   https://github.com/coder/claudecode.nvim/issues/283
#
# Drives three checks against the REAL plugin code:
#
#   Part 1 - REGRESSION TRIGGER (lost RNG seeding): runs the port selector in
#            several fresh Neovim processes and asserts they ALL pick the same
#            port. Pre-#282 this varied per process (shuffle_array seeded the
#            PRNG via os.time()); post-#282 it is deterministic, so every
#            instance collides.
#
#   Part 2 - MECHANISM (broken probe + listen-time EADDRINUSE): the in-process
#            proof from repro_issue_283.lua (mechanism mode).
#
#   Part 3 - END-TO-END: two real plugin servers (create_server). Instance A
#            listens; Instance B fails with the user's exact error,
#            "Failed to listen on port <P>: EADDRINUSE", on the SAME port.
#
# Usage (from repo root):
#   scripts/repro_issue_283.sh
#   NVIM=/path/to/nvim scripts/repro_issue_283.sh   # to pin a Neovim binary
#
# Exit code: 1 if #283 reproduces (deterministic collision + B fails), else 0.

set -uo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
LUA="$SCRIPT_DIR/repro_issue_283.lua"
NVIM="${NVIM:-nvim}"

if ! command -v "$NVIM" >/dev/null 2>&1; then
  echo "ERROR: nvim not found (set NVIM=/path/to/nvim)" >&2
  exit 2
fi

WORK="$(mktemp -d)"
A_OUT="$WORK/a.out"
A_PID=""
# shellcheck disable=SC2329  # invoked indirectly via `trap cleanup EXIT` below
cleanup() {
  [ -n "$A_PID" ] && kill "$A_PID" 2>/dev/null
  rm -rf "$WORK"
}
trap cleanup EXIT

run_port() {
  REPRO283_MODE=port "$NVIM" --headless -u NONE -l "$LUA" 2>/dev/null |
    tr -d '\r' | sed -n 's/^SELECTED_PORT=//p'
}

echo "############################################################"
echo "# issue #283 reproduction"
echo "# nvim: $("$NVIM" --version | head -1)"
echo "############################################################"

#############################################
# Part 1: cross-process determinism
#############################################
echo
echo "=== Part 1: is port selection deterministic across fresh processes? ==="
P1="$(run_port)"
P2="$(run_port)"
P3="$(run_port)"
echo "  fresh process #1 -> $P1"
echo "  fresh process #2 -> $P2"
echo "  fresh process #3 -> $P3"
DETERMINISTIC=0
if [ -n "$P1" ] && [ "$P1" = "$P2" ] && [ "$P2" = "$P3" ]; then
  DETERMINISTIC=1
  echo "  RESULT: DETERMINISTIC -- every fresh Neovim picks port $P1 (regression: lost RNG seeding)"
else
  echo "  RESULT: varies across processes (RNG appears seeded)"
fi

#############################################
# Part 2: in-process mechanism proof
#############################################
echo
echo "=== Part 2: broken probe + listen-time EADDRINUSE (in-process) ==="
"$NVIM" --headless -u NONE -l "$LUA"
MECH_RC=$?
echo "  (mechanism script exit code: $MECH_RC; 1 = reproduced)"

#############################################
# Part 3: two real instances, end-to-end
#############################################
echo
echo "=== Part 3: two real plugin servers in parallel ==="
REPRO283_MODE=serve REPRO283_LABEL=A REPRO283_WAIT_MS=8000 \
  "$NVIM" --headless -u NONE -l "$LUA" >"$A_OUT" 2>&1 &
A_PID=$!

# Wait until A reports its listening port.
A_LINE=""
for _ in $(seq 1 80); do
  A_LINE="$(tr -d '\r' <"$A_OUT" | sed -n 's/.*\(INSTANCE_A: .*\)/\1/p')"
  [ -n "$A_LINE" ] && break
  sleep 0.1
done
echo "  A: ${A_LINE:-<no output>}"

B_OUT="$(REPRO283_MODE=serve REPRO283_LABEL=B REPRO283_WAIT_MS=200 \
  "$NVIM" --headless -u NONE -l "$LUA" 2>&1 | tr -d '\r' | sed -n 's/.*\(INSTANCE_B: .*\)/\1/p')"
echo "  B: ${B_OUT:-<no output>}"

A_PORT="$(printf '%s' "$A_LINE" | sed -n 's/.*LISTENING port=\([0-9]*\).*/\1/p')"
E2E=0
if printf '%s' "$B_OUT" | grep -q "Failed to listen on port .*EADDRINUSE"; then
  B_PORT="$(printf '%s' "$B_OUT" | sed -n 's/.*Failed to listen on port \([0-9]*\).*/\1/p')"
  if [ -n "$A_PORT" ] && [ "$A_PORT" = "$B_PORT" ]; then
    E2E=1
    echo "  RESULT: B failed with EADDRINUSE on the SAME port A holds ($A_PORT)"
  else
    echo "  RESULT: B failed with EADDRINUSE but on port $B_PORT (A holds $A_PORT)"
    E2E=1
  fi
else
  echo "  RESULT: B did NOT collide (started on a different port)"
fi

#############################################
# Verdict
#############################################
echo
echo "=== VERDICT ==="
if [ "$DETERMINISTIC" -eq 1 ] && [ "$MECH_RC" -eq 1 ] && [ "$E2E" -eq 1 ]; then
  echo "#283 REPRODUCED: parallel Neovim instances deterministically pick the same"
  echo "port ($P1); the probe cannot detect the active listener; create_server fails"
  echo "at listen() with EADDRINUSE and no retry."
  exit 1
else
  echo "#283 NOT fully reproduced on this environment:"
  echo "  deterministic port = $DETERMINISTIC, mechanism = $((MECH_RC == 1 ? 1 : 0)), end-to-end = $E2E"
  echo "(After a fix that seeds the RNG + retries on EADDRINUSE, Part 1 should vary"
  echo " and Part 3's instance B should start on a different port.)"
  exit 0
fi

scripts/repro_issue_283.lua — mechanism proof + port/serve helper modes

-- Reproduction / verification for issue #283:
--   "find_available_port probe-then-rebind races; create_server has no retry ->
--    EADDRINUSE with parallel Neovim instances (regression in #282)"
--   https://github.com/coder/claudecode.nvim/issues/283
--
-- WHAT ACTUALLY BROKE (more than the issue's own analysis):
--
--   1. LOST RNG SEEDING (the regression trigger, NEW in #282).
--      Before #282, find_available_port shuffled the port list via
--      utils.shuffle_array, which calls `math.randomseed(os.time())` the first
--      time it runs. So every Neovim process seeded its PRNG and picked a
--      different starting port (as long as two instances did not start in the
--      same wall-clock second).
--      #282 replaced the shuffle with a direct, UNSEEDED `math.random(port_count)`
--      and dropped the `require("claudecode.server.utils")` line, so nothing
--      seeds the PRNG anymore. LuaJIT's math.random has a FIXED default seed, so
--      EVERY fresh Neovim process computes the IDENTICAL start_offset -> the
--      IDENTICAL port (48811 with the default 10000-65535 range). Two instances
--      therefore ALWAYS collide, deterministically, regardless of timing.
--
--   2. BROKEN PROBE (pre-existing, but now always hit). find_available_port
--      probes a candidate by binding a THROWAWAY socket, closing it, and
--      returning the port. libuv's uv_tcp_bind SWALLOWS EADDRINUSE: instead of
--      failing, it stores the error as a `delayed_error` and returns success,
--      deferring the failure to listen()/connect(). The probe never listens, so
--      its bind "succeeds" even when another process is actively LISTENING on the
--      port -> the probe reports a taken port as available.
--
--   3. NO RETRY (pre-existing, but now always hit). create_server selects the
--      port once; the deferred EADDRINUSE then surfaces at listen() (hence the
--      user's error text "Failed to listen on port ...", NOT "Failed to bind"),
--      and create_server gives up instead of advancing to the next port.
--
-- This script proves mechanism (2)+(3) deterministically in a single process,
-- and exposes the deterministic port (1) for the cross-process check driven by
-- scripts/repro_issue_283.sh.
--
-- Run from the repo root:
--   nvim --headless -u NONE -l scripts/repro_issue_283.lua            # mechanism proof
--   REPRO283_MODE=port  nvim --headless -u NONE -l scripts/repro_issue_283.lua
--   REPRO283_MODE=serve REPRO283_LABEL=A nvim --headless -u NONE -l scripts/repro_issue_283.lua
--
-- Exit code (mechanism mode): 1 if the broken probe + listen-time EADDRINUSE
-- reproduce (#283 confirmed), 0 if the probe correctly rejects a busy port.

local script_path = debug.getinfo(1, "S").source:sub(2)
local repo_root = vim.fn.fnamemodify(script_path, ":h:h")
vim.opt.rtp:prepend(repo_root)

local function out(msg)
  io.stdout:write(msg .. "\n")
  io.stdout:flush()
end

-- luv returns 0 (or a handle) on success and nil+err on failure. 0 is TRUTHY in
-- Lua, which is exactly why find_available_port's `if success then` accepts it.
local function ok_truthy(v)
  return v and true or false
end

local uv = vim.loop
local mode = vim.env.REPRO283_MODE or "mechanism"

-- Match a real startup's PRNG draw order: requiring server/init.lua performs the
-- module-load draw `module_instance_id = math.random(10000, 99999)` BEFORE
-- find_available_port's own draw, so the port we compute equals what a real
-- :ClaudeCodeStart selects (48811 with the default range).
require("claudecode.server.init")
local tcp = require("claudecode.server.tcp")
local config = { port_range = { min = 10000, max = 65535 } }

-------------------------------------------------------------------------------
-- MODE: port  -- print the deterministically-selected port, then exit.
-- The harness runs this in several fresh processes and asserts they all match.
-------------------------------------------------------------------------------
if mode == "port" then
  local port = tcp.find_available_port(config.port_range.min, config.port_range.max)
  out("SELECTED_PORT=" .. tostring(port))
  vim.cmd("qa!")
  return
end

-------------------------------------------------------------------------------
-- MODE: serve -- start the REAL server (create_server) and stay alive, exactly
-- as lua/claudecode/server/init.lua does. Used for the two-instance end-to-end
-- reproduction.
-------------------------------------------------------------------------------
if mode == "serve" then
  local label = vim.env.REPRO283_LABEL or "?"
  local wait_ms = tonumber(vim.env.REPRO283_WAIT_MS or "") or 6000
  local server, err = tcp.create_server(config, {}, nil)
  if server then
    out(("INSTANCE_%s: LISTENING port=%d"):format(label, server.port))
  else
    -- Mirror the exact init.lua user-facing wording.
    out(("INSTANCE_%s: [ClaudeCode] [init] [ERROR] Failed to start Claude Code server: %s"):format(label, tostring(err)))
  end
  vim.wait(wait_ms, function()
    return false
  end)
  if server then
    tcp.stop_server(server)
  end
  vim.cmd("qa!")
  return
end

-------------------------------------------------------------------------------
-- MODE: mechanism (default) -- in-process, deterministic proof that the probe
-- cannot detect an active listener and that EADDRINUSE surfaces at listen().
-------------------------------------------------------------------------------
out("== issue #283 reproduction (broken probe + listen-time EADDRINUSE) ==")
out(("Neovim: %s"):format(tostring(vim.version())))

-- Stand up a real, actively-LISTENING socket on an OS-assigned free port.
local listener = uv.new_tcp()
listener:bind("127.0.0.1", 0)
local listen_ok = listener:listen(128, function() end)
assert(ok_truthy(listen_ok), "harness: could not start listener")
local P = listener:getsockname().port
out(("\nA real server is now LISTENING on 127.0.0.1:%d"):format(P))

-- STEP 1: run find_available_port's exact probe against the busy port.
local probe = uv.new_tcp()
local probe_bind = probe:bind("127.0.0.1", P)
probe:close()
local probe_says_available = ok_truthy(probe_bind)
out(
  ("\n[probe] throwaway bind to busy port %d -> %s  => find_available_port would treat it as %s"):format(
    P,
    tostring(probe_bind),
    probe_says_available and "AVAILABLE (FALSE POSITIVE)" or "taken (correct)"
  )
)

-- STEP 2: reproduce create_server's bind-then-listen on that same busy port.
local real = uv.new_tcp()
local bind_ok, bind_err = real:bind("127.0.0.1", P)
out(("[create_server] bind   to busy port %d -> ok=%s err=%s"):format(P, tostring(bind_ok), tostring(bind_err)))
local lst_ok, lst_err = real:listen(128, function() end)
out(("[create_server] listen on busy port %d -> ok=%s err=%s"):format(P, tostring(lst_ok), tostring(lst_err)))

local listen_failed_eaddrinuse = (not ok_truthy(lst_ok)) and (tostring(lst_err):match("EADDRINUSE") ~= nil)

-- Cleanup
if not real:is_closing() then
  real:close()
end
if not listener:is_closing() then
  listener:close()
end

out("\n== verdict ==")
out(
  ("  probe false-positive : %s"):format(
    probe_says_available and "YES -- probe says a LISTENING port is available" or "no"
  )
)
out(("  bind swallowed error : %s"):format(ok_truthy(bind_ok) and "YES -- bind() returned success on a busy port" or "no"))
out(
  ("  listen() EADDRINUSE   : %s"):format(
    listen_failed_eaddrinuse and "YES -- error surfaces at listen(), matching the user's report" or "no"
  )
)

local reproduced = probe_says_available and listen_failed_eaddrinuse
if reproduced then
  out(
    "\n=> #283 confirmed: the probe cannot detect an active listener (libuv defers EADDRINUSE\n"
      .. "   to listen()), so find_available_port returns a busy port and create_server fails\n"
      .. "   at listen() with no retry. Combined with the lost RNG seeding (see repro .sh),\n"
      .. "   every parallel Neovim instance deterministically collides on the same port."
  )
else
  out("\n=> NOT reproduced: the probe correctly rejected the busy port on this platform/libuv build.")
end

io.stdout:flush()
vim.cmd("cquit " .. (reproduced and 1 or 0))

fixtures/issue-283/init.lua — interactive fixture (open in two terminals)

-- Fixture for issue #283:
--   "find_available_port probe-then-rebind races; create_server has no retry ->
--    EADDRINUSE with parallel Neovim instances (regression in #282)"
--   https://github.com/coder/claudecode.nvim/issues/283
--
-- This fixture starts the REAL claudecode WebSocket server on launch and prints
-- a big banner showing whether THIS instance got a listening port or failed.
--
-- Reproduction (from repo root), in TWO terminals:
--   source fixtures/nvim-aliases.sh
--   vv issue-283      # terminal 1 -> "LISTENING on port 48811"
--   vv issue-283      # terminal 2 -> "FAILED ... Failed to listen on port 48811: EADDRINUSE"
--
-- Because #282 dropped the per-process RNG seeding, every fresh Neovim picks the
-- SAME port (48811 with the default 10000-65535 range), so the second instance
-- always collides. The probe in find_available_port cannot notice the first
-- instance's listener (libuv defers EADDRINUSE to listen()), and create_server
-- does not retry, so the integration never starts in instance 2.
--
-- :ReproStatus  re-print this instance's server status
-- :ReproStop    stop this instance's server (frees the port / lockfile)

local config_dir = vim.fn.stdpath("config")
local repo_root = vim.fn.fnamemodify(config_dir, ":h:h")
vim.opt.rtp:prepend(repo_root)

vim.g.mapleader = " "
vim.g.maplocalleader = "\\"
vim.o.showtabline = 0
vim.o.laststatus = 2

local ok, claudecode = pcall(require, "claudecode")
assert(ok, "Failed to load claudecode.nvim from repo root: " .. tostring(claudecode))

-- auto_start = false so we can call start() ourselves and capture its result.
claudecode.setup({
  auto_start = false,
  log_level = "info",
  terminal = {
    provider = "native",
    auto_close = false,
  },
})

local started_ok, started_info = claudecode.start(false)

local function status_lines()
  local running = claudecode.state and claudecode.state.server ~= nil
  local port = claudecode.state and claudecode.state.port or nil
  local lines = {
    "claudecode.nvim -- issue #283 reproduction fixture",
    "",
    "Run `vv issue-283` in a SECOND terminal while this one is open.",
    "",
  }
  if started_ok and running then
    lines[#lines + 1] = "THIS INSTANCE: server LISTENING on port " .. tostring(port)
    lines[#lines + 1] = ""
    lines[#lines + 1] = "Now open a second instance: it should FAIL on the same port"
    lines[#lines + 1] = "with EADDRINUSE, because every fresh Neovim deterministically"
    lines[#lines + 1] = "selects this same port (lost RNG seeding in #282)."
  else
    lines[#lines + 1] = "THIS INSTANCE: server FAILED to start"
    lines[#lines + 1] = ""
    lines[#lines + 1] = "  " .. tostring(started_info)
    lines[#lines + 1] = ""
    lines[#lines + 1] = "This is #283: another Neovim already holds this port, the probe"
    lines[#lines + 1] = "could not detect it, and create_server did not retry."
  end
  lines[#lines + 1] = ""
  lines[#lines + 1] = ":ReproStatus  re-print status     :ReproStop  stop this server"
  return lines, (started_ok and running)
end

local function show_banner()
  local lines, good = status_lines()
  vim.bo.modifiable = true
  vim.api.nvim_buf_set_lines(0, 0, -1, false, lines)
  vim.bo.modifiable = false
  vim.bo.modified = false
  -- Keep the echo SHORT (port only) so it stays below the hit-enter threshold;
  -- the full error text lives in the banner buffer above.
  local msg = good and ("issue283: LISTENING on port " .. tostring(claudecode.state.port))
    or "issue283: FAILED -- port in use (EADDRINUSE); see buffer above"
  vim.api.nvim_echo({ { msg, good and "MoreMsg" or "ErrorMsg" } }, false, {})
end

vim.api.nvim_create_user_command("ReproStatus", show_banner, { desc = "Re-print #283 server status" })
vim.api.nvim_create_user_command("ReproStop", function()
  claudecode.stop()
  vim.api.nvim_echo({ { "issue283: server stopped", "MoreMsg" } }, false, {})
end, { desc = "Stop this instance's server (#283)" })

-- Populate the buffer synchronously at load time so it is already non-empty when
-- startup finishes -- this suppresses Neovim's intro screen without depending on
-- a deferred redraw (a hit-enter prompt from the plugin's own error log can
-- otherwise block a scheduled callback). The plugin's native error message still
-- appears in the message area, exactly as a real user sees it.
show_banner()

Suggested fix sketch (for discussion — not yet applied)

-- (A) Own the RNG seed here (#282 removed the utils.shuffle_array side effect
--     that used to seed the start path). Guard hrtime: the test mock lacks it.
--     Sub-second jitter avoids same-second collisions that os.time()-only
--     seeding would cause.
local rng_seeded = false
local function ensure_seeded()
  if rng_seeded then return end
  local jitter
  local ok, hr = pcall(function()
    return vim.loop and vim.loop.hrtime and vim.loop.hrtime()
  end)
  if ok and type(hr) == "number" then
    jitter = hr % 1000000
  else
    jitter = math.floor((os.clock() % 1) * 1000000)
  end
  math.randomseed((os.time() * 1000000) + jitter)
  rng_seeded = true
end

-- (B) Shared candidate ordering: random start + single wrap-scan (no 55k table).
local function candidate_ports(min_port, max_port)
  if min_port > max_port then return {} end
  ensure_seeded()
  local n = max_port - min_port + 1
  local start = math.random(n) - 1
  local ports = {}
  for i = 0, n - 1 do
    ports[#ports + 1] = min_port + ((start + i) % n)
  end
  return ports
end

-- find_available_port keeps its public contract; stays a cheap bind-only
-- pre-filter. bind() CANNOT detect an active listener (libuv defers EADDRINUSE
-- to listen()), so this is best-effort; create_server's listen() is the arbiter.
function M.find_available_port(min_port, max_port)
  assert(type(min_port) == "number", "min_port must be a number")
  assert(type(max_port) == "number", "max_port must be a number")
  for _, port in ipairs(candidate_ports(min_port, max_port)) do
    local test = vim.loop.new_tcp()
    if test then
      local ok = test:bind("127.0.0.1", port)
      test:close()
      if ok then return port end
    end
  end
  return nil
end

-- (C) bind+listen on ONE fresh handle = the handle the server keeps (no TOCTOU).
local function try_listen(server, port)
  local h = vim.loop.new_tcp()
  if not h then return nil, "Failed to create TCP server" end
  local bok, berr = h:bind("127.0.0.1", port)
  if not bok then
    h:close()
    return nil, "Failed to bind to port " .. port .. ": " .. (berr or "unknown error")
  end
  local lok, lerr = h:listen(128, function(err)
    if err then server.on_error("Listen error: " .. err) return end
    M._handle_new_connection(server)
  end)
  if not lok then
    h:close()  -- discard; advance to next candidate
    return nil, "Failed to listen on port " .. port .. ": " .. (lerr or "unknown error")
  end
  return h, nil
end

-- (D) create_server: loop candidates, retry on per-port listen() failure.
function M.create_server(config, callbacks, auth_token)
  local ports = candidate_ports(config.port_range.min, config.port_range.max)
  if #ports == 0 then
    return nil, "No available ports in range " .. config.port_range.min .. "-" .. config.port_range.max
  end
  local server = {
    server = nil, port = nil, auth_token = auth_token, clients = {},
    on_message = callbacks.on_message or function() end,
    on_connect = callbacks.on_connect or function() end,
    on_disconnect = callbacks.on_disconnect or function() end,
    on_error = callbacks.on_error or function() end,
  }
  local last_err
  for _, port in ipairs(ports) do
    local h, err = try_listen(server, port)
    if h then
      server.server, server.port = h, port
      return server, nil
    end
    last_err = err
  end
  return nil, "Failed to bind to any port in range "
    .. config.port_range.min .. "-" .. config.port_range.max
    .. " (" .. (last_err or "unknown error") .. ")"
end

Suggested regression tests (against tests/unit/server/tcp_spec.lua, which already mocks vim.loop.new_tcp and math.random): retry past a busy candidate; range exhaustion returns a clear error with all handles closed; bind-success-but-listen-EADDRINUSE on the same handle is treated as unavailable; and the stored server.server is the same handle whose listen() succeeded. The existing tests continue to pass because find_available_port stays bind-only. The scripts/repro_issue_283.sh harness serves as the end-to-end gate (it should flip from exit 1 to exit 0).