[hefgi]

Why

ecluse assigns ports (port = base_port + slot × stride) and treats state.json as truth. What it couldn't do was tell you where a service actually ended up. When something bound the wrong port, ecluse status reported a bare ✗ down — technically correct, but it gives an agent nothing to act on.

That gap has a cost on record. In the 2026-06-09 cross-agent kill spiral, three parallel agents each saw "a process on a port near mine", inferred a stale leftover, and ran lsof -ti | xargs kill against a sibling's working service. Seven kills in seven minutes. whose-pid was added afterwards so ownership could be checked — but nothing surfaced the mismatch unprompted, so no one thought to check.

This adds the missing signal.

What

ecluse ls gains a LISTENING column; ecluse status gains ACTUAL beside EXPECTED.

$ ecluse ls
SLUG     MODE  SLOT  PORTS      LISTENING
feat-a   host  1     api=4010   4020 !
feat-b   host  2     api=4020   -
feat-c   host  3     api=4030   4030 24678

$ ecluse status feat-a
SERVICE  TYPE     EXPECTED  ACTUAL  STATUS
api      native   4010      4020    ✗ wrong port 4020 (slot 2)

warning: service 'api' is listening on 4020 but ecluse assigned 4010; 4020 belongs
to slot 2 (session 'feat-b') — do not kill it, run: ecluse down feat-a
--keep-worktree && ecluse up feat-a

Because ports derive from the slot, the formula inverts — a discovered port maps back to the slot that owns it. When the wrong port is another slot's territory, ecluse names that slot and its session, and says not to kill it. That's the one fact whose absence started the spiral.

Design decisions

No daemon. Discovery runs when a command is invoked. There's no sidebar to keep live and no PTY to scrape, so a resident scanner would burn lsof every few seconds to populate a view nobody's looking at.

One snapshot. lsof -iTCP -sTCP:LISTEN + ps -axo pid=,ppid=, then the process-tree join happens in memory, so the scan doesn't grow with session count. Identifying each session's root processes still costs a few cheap pid-file checks and tmux lookups per session; status now uses the same snapshot instead of its per-service lsof/pgrep calls. The per-PID approach already in sync.rs forks lsof -p once per process and pgrep -P once per tree level (30+ forks for 4 sessions, ~20-400ms each). Measured ~25ms per fork locally, which is what makes always-on affordable.

Read-only — assignment stays truth. A discovered port is never written back over the assigned one. Auto-adopting would make expected == actual and turn the row green, erasing the evidence that something bound the wrong port; it also wouldn't move the already-running process. This is the same trap as fix #4 in the incident (status used to report a child's discovered port and hid a wrong-slot spawn behind a green check). Lesson #1 there: "State files are truth. Process trees lie."

Only a missing assigned port counts as a mismatch. Dev servers open extra sockets (HMR, debug, inspector); those show up in LISTENING/ACTUAL without flagging anything, in both ls and status.

Per-service attribution. status blames a port only on the tmux window or pid file of the service that holds it (never a sibling pane), and drops pid files whose pid was recycled (start-time token check). If lsof is missing, discovery is off with a one-time warning.

Docker excluded. The daemon publishes container ports, not a host process tree — find_docker_services already reports the real mapping. Only natively spawned services are compared, so hybrid sessions' Docker ports never trigger a !.

Verified end-to-end

Reproduced the incident on a scratch repo (slot_stride = 10, so slot 1 → 4010, slot 2 → 4020), bound feat-a's service to 4020, and confirmed the output above plus exit 1.

Tests

65 new unit tests. Covers the stateful lsof -F pn record format, ports listed once per file descriptor, bracketed IPv6 ([::1]:27017), IGNORED_PORTS (22/80/443), grandchild attribution (sh → pnpm → node → vite), sibling non-attribution, ppid-cycle tolerance, the owning_slot inversion incl. off-stride ports that belong to nobody, that mismatch_hint never contains the word kill, hybrid Docker-port exclusion, sibling-pane non-blame, and recycled-pid rejection.

cargo fmt --check and cargo clippy --all-targets -- -D warnings are clean at every commit.

Also included

test(process): fixes a genuine flake in kill_nohup_kills_whole_process_group. It waited on child_pid_file.exists() then immediately parsed — the shell creates the file on redirect and writes the pid a moment later, so it could read empty and panic with ParseIntError { kind: Empty }. Always passed in isolation, only failed under full-suite load. Now waits on a successful parse.

Docs

README, docs/src/commands.md, docs/src/ports.md, skills/ecluse/SKILL.md (under the existing cross-agent-collision troubleshooting entry, since that's the failure this defuses), and a CHANGELOG entry.