@@ -385,7 +385,7 @@ Written by `checkpoint.sh` at every phase boundary; read by coordinators. Never
 
 Main `jetpack_dev` uses: WP 80, phpMyAdmin 8181, Mailpit inbox 1080, Mailpit SMTP 25, SFTP 1022. The seeder allocates the first free value at or above a per-service base — WP `8080`, phpMyAdmin `8282`, inbox `1180`, SMTP `2525`, SFTP `2222` — so a first worktree usually lands exactly on those, and later ones step up from there. Values are persisted in the worktree's `tools/docker/.env` and stay stable across restarts.
 
-The seeder reserves ports recorded in other worktrees' `.env` files, but does not probe for live-bound host ports and does not lock against two worktrees seeding at the same instant. A genuine clash surfaces as `address already in use` from `jp docker up` — edit the port in `tools/docker/.env` and retry, then update `.work-on/env.json` to match. See `tools/docker/README.md` § "Parallel development environments" for the authoritative rules.
+The seeder skips ports recorded in other worktrees' `.env` files and ports that already have a listener on localhost, but does not lock against two worktrees seeding at the same instant. A genuine clash surfaces as `address already in use` from `jp docker up` — edit the port in `tools/docker/.env` and retry, then update `.work-on/env.json` to match. See `tools/docker/README.md` § "Parallel development environments" for the authoritative rules.
 
 ## Docker instance tracking
 
 
@@ -169,7 +169,7 @@ This writes a unique `COMPOSE_PROJECT_NAME` (derived from git's worktree id —
 - **idempotent** — it only fills in the keys that are missing (so it also backfills ports for a name-only `.env` left by `up --name`) and is a no-op once fully configured, so it's safe to run before every `up`;
 - **a no-op in the primary checkout** — that always stays `jetpack_dev` on the default ports.
 
-It reserves ports already recorded in other worktrees' `.env` files and the primary defaults, but does not probe for live-bound host ports, and does not lock against another worktree seeding at the same instant — so two worktrees seeded in parallel can, in principle, pick the same port. Either way a genuine clash surfaces when `jetpack docker up` reports `address already in use`; edit the port in `.env` and retry.
+When it picks a new port, it skips ports already recorded in other worktrees' `.env` files, the primary defaults, and any port that already has a listener on localhost (`127.0.0.1` or `::1`). A port already in this worktree's `.env` is kept as is. It does not lock against another worktree seeding at the same instant, so two worktrees seeded in parallel can, in principle, pick the same port. A genuine clash surfaces when `jetpack docker up` reports `address already in use`; edit the port in `.env` and retry.
 
 To undo it, delete the seeded lines from `tools/docker/.env` (the file is git-ignored and removed with the worktree). To set the name/ports yourself instead, edit `.env` by hand or use the manual flags below.
 
 
@@ -15,10 +15,10 @@
 #   - idempotent (it only fills the keys that are missing; a no-op once fully configured), and
 #   - a no-op in the primary checkout, which keeps using `jetpack_dev`.
 #
-# Known limitations (acceptable for a manual dev helper): it reserves ports recorded in other
-# worktrees' .env files and the primary defaults, but does NOT probe for live-bound host ports,
-# and does not lock against another worktree seeding at the same instant. A genuine clash
-# surfaces as a `jp docker up` "address already in use" error; re-run after editing .env.
+# It skips ports recorded in other worktrees' .env files, the primary defaults, and any port that
+# already has a listener on localhost. Known limitation (acceptable for a manual dev helper): it
+# does not lock against another worktree seeding at the same instant. A genuine clash surfaces as
+# a `jp docker up` "address already in use" error; re-run after editing .env.
 #
 # Written for portability down to the bash 3.2 that ships with macOS — no associative arrays.
 #
@@ -57,13 +57,38 @@ is_claimed() {
 	esac
 }
 
+# Is something already listening on localhost port $1, such as another app or an SSH tunnel?
+# A closed port refuses at once. A probe still waiting after about a second (a listener whose
+# accept queue is full can drop the connect) counts as busy rather than stalling the script.
+port_in_use() {
+	local host pid waited
+	for host in 127.0.0.1 ::1; do
+		( : < "/dev/tcp/$host/$1" ) 2>/dev/null &
+		pid=$!
+		waited=0
+		while kill -0 "$pid" 2>/dev/null; do
+			if [ "$waited" -ge 20 ]; then
+				kill "$pid" 2>/dev/null || true
+				wait "$pid" 2>/dev/null || true
+				return 0
+			fi
+			sleep 0.05
+			waited=$(( waited + 1 ))
+		done
+		if wait "$pid"; then
+			return 0
+		fi
+	done
+	return 1
+}
+
 # Reserve the first free port at or above $1 into CLAIMED and return it via ALLOCATED. Writing
 # to a global (rather than echoing via command substitution, which runs in a subshell and would
 # discard the CLAIMED reservation) keeps the five services from ever landing on the same number.
 ALLOCATED=""
 alloc_port() {
 	local port="$1"
-	while is_claimed "$port"; do
+	while is_claimed "$port" || port_in_use "$port"; do
 		port=$(( port + 1 ))
 	done
 	CLAIMED="${CLAIMED}${port} "
 
@@ -50,16 +50,49 @@ run() {
 	RUN_OUT="$( cd "$1" && ./tools/docker/bin/seed-worktree-env.sh 2>&1 )" && RUN_RC=0 || RUN_RC=$?
 }
 
-# --- a primary repo with the script committed at tools/docker/bin ----------
+# listening PORT — is localhost:PORT taken? Same rules as the script's port_in_use (a connect
+# still pending after about a second counts as taken), defined here so expectations don't come from it.
+listening() {
+	local host pid waited
+	for host in 127.0.0.1 ::1; do
+		( : < "/dev/tcp/$host/$1" ) 2>/dev/null &
+		pid=$!
+		waited=0
+		while kill -0 "$pid" 2>/dev/null; do
+			if [ "$waited" -ge 20 ]; then
+				kill "$pid" 2>/dev/null || true
+				wait "$pid" 2>/dev/null || true
+				return 0
+			fi
+			sleep 0.05
+			waited=$(( waited + 1 ))
+		done
+		if wait "$pid"; then return 0; fi
+	done
+	return 1
+}
+# first_free PORT — the first port at or above PORT with no listener. The script skips busy
+# ports, so on a dev machine with 8080 taken the expected values move up with it.
+first_free() {
+	local p="$1"
+	while listening "$p"; do p=$(( p + 1 )); done
+	printf '%s' "$p"
+}
+
+# new_primary DIR — a primary repo with the script committed at tools/docker/bin.
+new_primary() {
+	mkdir -p "$1/tools/docker/bin"
+	git -C "$1" init -q
+	git -C "$1" config user.email test@example.test
+	git -C "$1" config user.name  seed-test
+	cp "$SUT" "$1/tools/docker/bin/seed-worktree-env.sh"
+	chmod +x "$1/tools/docker/bin/seed-worktree-env.sh"
+	git -C "$1" add -A
+	git -C "$1" commit -qm init
+}
+
 PRIMARY="$TMP/primary"
-mkdir -p "$PRIMARY/tools/docker/bin"
-git -C "$PRIMARY" init -q
-git -C "$PRIMARY" config user.email test@example.test
-git -C "$PRIMARY" config user.name  seed-test
-cp "$SUT" "$PRIMARY/tools/docker/bin/seed-worktree-env.sh"
-chmod +x "$PRIMARY/tools/docker/bin/seed-worktree-env.sh"
-git -C "$PRIMARY" add -A
-git -C "$PRIMARY" commit -qm init
+new_primary "$PRIMARY"
 
 add_wt() { git -C "$PRIMARY" worktree add -q "$TMP/$1" -b "br-$1"; }
 env_of() { printf '%s/tools/docker/.env' "$TMP/$1"; }
@@ -71,10 +104,11 @@ assert_absent "$PRIMARY/tools/docker/.env" 'COMPOSE_PROJECT_NAME' "primary .env
 
 # --- a linked worktree seeds a unique name + base ports --------------------
 add_wt wt-a
+WP_A="$( first_free 8080 )"
 run "$TMP/wt-a"
 assert_rc zero "linked worktree seeds (exit 0)"
 assert_grep "$( env_of wt-a )" '^COMPOSE_PROJECT_NAME=jetpack_wt-a$' "name derives from the git worktree id"
-assert_grep "$( env_of wt-a )" '^PORT_WORDPRESS=8080$'               "base WordPress port lands at 8080"
+assert_grep "$( env_of wt-a )" "^PORT_WORDPRESS=${WP_A}\$"           "WordPress port lands on the first free port from 8080"
 
 # --- re-running is idempotent ----------------------------------------------
 run "$TMP/wt-a"
@@ -84,10 +118,11 @@ if [ "$( grep -c '^COMPOSE_PROJECT_NAME=' "$( env_of wt-a )" )" = 1 ]; then pass
 # --- name-only .env gets its ports backfilled around the sibling -----------
 add_wt wt-b
 printf 'COMPOSE_PROJECT_NAME=jetpack_beta\n' > "$( env_of wt-b )"
+WP_B="$( first_free $(( WP_A + 1 )) )"
 run "$TMP/wt-b"
 assert_rc zero "name-only .env backfills (exit 0)"
 assert_grep "$( env_of wt-b )" '^COMPOSE_PROJECT_NAME=jetpack_beta$' "hand-set name is kept"
-assert_grep "$( env_of wt-b )" '^PORT_WORDPRESS=8081$'              "backfilled port avoids the sibling's 8080"
+assert_grep "$( env_of wt-b )" "^PORT_WORDPRESS=${WP_B}\$"           "backfilled port avoids the sibling's port"
 
 # --- a name a sibling already uses is refused (concern 1) ------------------
 add_wt wt-c
@@ -206,14 +241,7 @@ assert_rc nonzero "an unbalanced-quote name is rejected (Compose-invalid)"
 # sibling pins base ports via a colon-space and an export form; without the lenient sibling reader
 # the fresh worktree would reuse them, colliding at `up`.
 PRIMARY2="$TMP/primary2"
-mkdir -p "$PRIMARY2/tools/docker/bin"
-git -C "$PRIMARY2" init -q
-git -C "$PRIMARY2" config user.email test@example.test
-git -C "$PRIMARY2" config user.name  seed-test
-cp "$SUT" "$PRIMARY2/tools/docker/bin/seed-worktree-env.sh"
-chmod +x "$PRIMARY2/tools/docker/bin/seed-worktree-env.sh"
-git -C "$PRIMARY2" add -A
-git -C "$PRIMARY2" commit -qm init
+new_primary "$PRIMARY2"
 git -C "$PRIMARY2" worktree add -q "$TMP/p2-sib"   -b br-p2-sib
 git -C "$PRIMARY2" worktree add -q "$TMP/p2-fresh" -b br-p2-fresh
 printf 'COMPOSE_PROJECT_NAME: jetpack_p2sib\nPORT_WORDPRESS: 8080\nexport PORT_PHPMY=8282\n' > "$TMP/p2-sib/tools/docker/.env"
@@ -228,6 +256,94 @@ printf 'COMPOSE_PROJECT_NAME=jetpack_p2sib\n' > "$TMP/p2-dupe/tools/docker/.env"
 run "$TMP/p2-dupe"
 assert_rc nonzero "a name duplicating a colon-space sibling is rejected"
 
+# --- a port something is already listening on is skipped -------------------
+# A fresh repo, so no sibling claims anything; hold the port the script would otherwise pick.
+PRIMARY3="$TMP/primary3"
+new_primary "$PRIMARY3"
+git -C "$PRIMARY3" worktree add -q "$TMP/p3-wt" -b br-p3-wt
+BUSY="$( first_free 8080 )"
+if command -v python3 >/dev/null 2>&1; then
+	# Bounded sleep, so the listener exits on its own even if this script dies before the kill.
+	python3 -c 'import socket, sys, time
+s = socket.socket()
+s.bind(("127.0.0.1", int(sys.argv[1])))
+s.listen(16)
+time.sleep(30)' "$BUSY" &
+	LISTENER=$!
+	for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20; do
+		listening "$BUSY" && break
+		sleep 0.25
+	done
+	if listening "$BUSY"; then
+		EXPECTED="$( first_free $(( BUSY + 1 )) )"
+		run "$TMP/p3-wt"
+		assert_rc zero "seeds beside a busy port (exit 0)"
+		assert_grep "$TMP/p3-wt/tools/docker/.env" "^PORT_WORDPRESS=${EXPECTED}\$" "busy port ${BUSY} is skipped for the next free one"
+	else
+		bad "test listener never came up on port ${BUSY}, so the busy-port case could not run"
+	fi
+	kill "$LISTENER" 2>/dev/null || true
+	wait "$LISTENER" 2>/dev/null || true
+
+	# A listener whose accept queue is full drops new connects instead of refusing them. Fresh repo
+	# again, so the port the previous case wrote to .env is not claimed.
+	PRIMARY4="$TMP/primary4"
+	new_primary "$PRIMARY4"
+	git -C "$PRIMARY4" worktree add -q "$TMP/p4-wt" -b br-p4-wt
+	FULL="$( first_free 8080 )"
+	READY="$TMP/full-queue-ready"
+	# Writes "full" to READY only once a fresh connect really times out, so the probe's bound is
+	# what this case exercises (an OS that still accepts it writes "open" and the case is skipped).
+	python3 -c 'import socket, sys, time
+port, ready = int(sys.argv[1]), sys.argv[2]
+s = socket.socket()
+s.bind(("127.0.0.1", port))
+s.listen(1)
+held = []
+for _ in range(16):
+    c = socket.socket()
+    c.setblocking(False)
+    try:
+        c.connect(("127.0.0.1", port))
+    except BlockingIOError:
+        pass
+    held.append(c)
+probe = socket.socket()
+probe.settimeout(0.5)
+try:
+    probe.connect(("127.0.0.1", port))
+    state = "open"
+except OSError:
+    state = "full"
+with open(ready, "w") as f:
+    f.write(state)
+time.sleep(30)' "$FULL" "$READY" &
+	LISTENER=$!
+	for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20; do
+		[ -s "$READY" ] && break
+		sleep 0.25
+	done
+	case "$( cat "$READY" 2>/dev/null )" in
+		full )
+			EXPECTED="$( first_free $(( FULL + 1 )) )"
+			START=$SECONDS
+			run "$TMP/p4-wt"
+			if [ $(( SECONDS - START )) -le 10 ]; then
+				pass "a full accept queue does not stall the seeder"
+			else
+				bad "a full accept queue does not stall the seeder (took $(( SECONDS - START ))s)"
+			fi
+			assert_grep "$TMP/p4-wt/tools/docker/.env" "^PORT_WORDPRESS=${EXPECTED}\$" "port ${FULL} with a full accept queue is skipped"
+			;;
+		open ) echo "  skip - this OS accepted a connect past the full queue, so the timeout case did not run" ;;
+		* )    bad "full-queue test listener never came up on port ${FULL}" ;;
+	esac
+	kill "$LISTENER" 2>/dev/null || true
+	wait "$LISTENER" 2>/dev/null || true
+else
+	echo "  skip - python3 not found, so the busy-port cases did not run"
+fi
+
 # --- reaching the primary through a symlinked path is still a no-op ---------
 # (Guards the pwd -P handling that resolves --absolute-git-dir's symlink resolution.)
 ln -s "$PRIMARY" "$TMP/primary-link"