portlist kill, cleanup and report; agent adapters; README leads with the answer

[Mr-hunt-007]

portlist kill 3000

• Shows what the listener is, who started it, whether the network can reach it, and how it should be stopped, then asks.
• It stops through the listener's manager when one was measured:
  • docker stop for a port a container publishes
  • brew services stop for a Homebrew service
  • launchctl bootout for a launchd job
  • systemctl stop for a systemd unit, read from the process's cgroup
  • a PM2 app is named and left to PM2
• Otherwise it sends SIGTERM.
• Afterwards it scans again and reports if something brought the port straight back.
• A pipe is never asked a question, so a script must pass --yes.
• --force sends SIGKILL after 5 seconds. --dry-run stops nothing.
• The harbour's stop button now goes through the same guard.

portlist cleanup

• Walks every leftover, the one the network can reach first, with the evidence: how long unused, started by which agent, whether that session has exited.
• Answers: y stop, n keep, k keep and stop calling it a leftover, a stop the rest, q quit.
• --idle HOURS also offers anything unused that long. --dry-run and --json stop nothing.

portlist report

• One self-contained HTML page: no scripts, nothing fetched.
• Contents: a verdict, what needs a look and why, everything listening, who started what, containers, and how each thing was measured.
• Secrets in command lines are masked, including flags and passwords in URLs.
• --redact removes host and user names, addresses, project names, paths and command lines.

Agent adapters

• Each agent is one file in plcore/adapters/.
• The ancestry patterns, environment variable names, agent processes and transcript readers are all built from these files. The resulting tables are identical and in the same order.
• Gemini CLI and OpenCode are new.
• CONTRIBUTING has a one-file example.

Docs

• The README leads with the question, then the list, then portlist 8787, then kill, cleanup and report.
• The site gets a new chapter.
• The claims about stopping in SECURITY, FEATURES, the FAQ and llms.txt are updated.

Playground

• Runs all three commands, with plans from the real supervisor detection and real report pages.

Harness

• The jump check skips frame pairs from a stalled runner.
• The sandbox train check waits for the train instead of a fixed 5 frames.
• Both of those failed on a runner that froze for 5 minutes.

Tests

• Unit tests: 85, 17 of them new. Every stop is faked.
• Harbour harness: 45 of 45.
• Playground checks: 21 of 21.
• flake8 is clean.
• Verified on a real machine: kill declines when stdin is a pipe, stops with --yes, and confirms the port is free.
• The playground output is byte-identical across timezones.