[zumbrunn]

Refs #42

Draft, stacked on three open PRs. This branch contains #37 (dune ps/dune stop), #51 (watchdog) and #52 (registry) via merge commits; review only feat(cli): dune ps probes health and reads the instance registry and fix(cli): dune ps probes more carefully. I'll retarget to main and rebase once those land.

What

• Health probe. Every listening instance is sent a GET /health/live (it shows up in the instance's access log). A blocked event loop still lets the kernel accept the TCP connection but never answers it, so the instance is shown as NOT RESPONDING and counted separately: the case lsof can't see.
  • It probes the port the instance registered when it did (any HTTP answer counts); otherwise every listening port, counting only dune's own answer (2xx JSON with a status field). A debugger's inspector port (9229) can't make a hung server look healthy.
  • It takes three failed probes in a row (3 s each, ~10 s in all). One slow answer from a busy server proves nothing. A port that speaks HTTP but not like dune yields "unknown", never a hung verdict.
  • Probes 127.0.0.1, not localhost.
• Registry. dune ps reads the records from feat(runtime): instance registry written by dev and serve #52. A registered process is attached to its instance (adding its @dune/core version) and counts as confirmed (the process itself says it is a dune site, stronger evidence than anything on its command line); one the command-line matching misses is added from its record. Stale records are pruned as a side effect of listing.
• dune stop --idle also takes confirmed instances that are listening but not responding, once they are at least 2 minutes old (a server that just bound its port may still be indexing synchronously).

Why a probe rather than a registry marker

(Plan change noted on #52.) Marking "hung" from the watchdog only helps in warn/off mode: in the default mode a hung process is killed within seconds, so NOT RESPONDING mostly matters there. A probe needs no cooperation from the stuck process and also works for unregistered ones.

Verification

• deno lint src/; deno test -A --unstable-kv tests/cli: 417 passed
• probePort tells dune's answer, another HTTP service and silence apart; judgeResponsive needs every attempt to fail, prefers the registered port, and treats the inspector case as "unknown"; real processes for a responding instance, a listener that accepts but never answers, a not-listening instance (not probed), a process found only via the registry (version, root, title, port), one found both ways (listed once), a registered process confirmed even though its command line says nothing about a site, and a stale record (adds nothing).
• Live (earlier revision): DUNE_WATCHDOG=off dune serve with a page that spins forever; dune ps showed NOT RESPONDING; dune stop <pid> left it alive (a blocked loop can't handle SIGTERM) and printed the --force hint; --force SIGKILLed the tree.

Known limits

• A very busy server that stays silent for ~10 s is flagged; the wording says "may be hung" and --idle lists what it would stop and asks first.
• A multi-site instance without a registry record and without a dune-style /health/live answer reads as "unknown" or "not responding" depending on what its ports say.
• Docs: dune-docs#12.

🤖 Generated with Claude Code