chore(scripts): let seeding establish its own port-forwards

[ericfitz]

Seeding needs localhost:8080 and localhost:5432, but nothing established either — they
were a documented manual prerequisite.

Why the manual approach could never work

This isn't a lapse in developer diligence. stop_port_forward()'s legacy reaper matches any
-n tmi-platform port-forward svc/ command, so a hand-started forward is killed as an
"orphan" by the next dev-up/dev-restart/dev-down. It then resurfaces as a confusing
failure inside the seed rather than as a missing prerequisite.

The change

ensure_port_forward(name), modelled on tmi_common.ensure_oauth_stub: probe → return
quietly if healthy → otherwise start and wait. Generic over the three named dev forwards;
only seeding is wired to it for now, per the agreed scope.

A forward whose recorded kube context is no longer the current one counts as unhealthy and
is replaced rather than reused — a live supervisor pointing localhost at another cluster is
the #580 failure mode.

scripts/run-dbtool.py is the single wiring point, which covers every way seeding is invoked:
make cats-seed, make e2e-seed, and the cats plugin's seed hook (hence make cats-fuzz).
Skipped for --oci (external ADB, no Service to forward) and when --server isn't loopback.

Postgres gets a first-class supervised forward, pidfile-tracked so stop_port_forward() tears
it down deliberately. It is not started by dev-up — 5432 collides with a locally
installed PostgreSQL, and a developer who never runs CATS shouldn't have to care. On a
collision _preflight_port already hard-fails naming the squatter; the message now adds that
a local PostgreSQL commonly holds that port, and why seeding must not silently use it.

Two bugs found while doing this

1. start_redis_port_forward() called the blanket stop_port_forward(), clearing every
   pidfile. That forced the server forward to start afterwards to survive — an ordering
   constraint that would silently extend to any third forward — and destroyed the postgres
   forward on every dev-up/dev-restart. Each starter now stops only its own pidfile.
2. ensure returned ~3s before the port was bound, so the contract was "started" rather
   than "usable" and an immediate connect could race it. It now waits for the bind, as
   ensure_oauth_stub does.

Test change, called out explicitly

test_server_port_forward_is_k3s_only is widened for the one new call site — the by-name
dispatch inside ensure_port_forward, whose callers know the server URL is loopback rather
than knowing cluster_target. Any other unguarded call site still fails. The campaign still
hits the NodePort directly; this path only ever carries low-volume seeding traffic, which is
what #463/#578 actually protect.

Verification

make test-dev-scripts — 164 tests, OK (10 new). make lint — 0 issues. Only Python changed,
so the Go gates don't apply.

Against the live k3s cluster:

check	result
make cats-seed with 5432 down	starts the forward, waits for bind, seeds successfully
second ensure call	Port-forward already running — no churn
forward survives make dev-restart	survived (previously killed as an orphan)
stop_port_forward()	tears down all three deliberately, by pidfile
connect immediately after ensure returns	connects — race gone

🤖 Generated with Claude Code

https://claude.ai/code/session_01WnrVyySuyJFqcMxB8q3pNc