home-hosted 0.5.0 → 0.6.0

package/docs/SERVERS.md

@@ -26,7 +26,7 @@ servers and its state together.
 | `command`, `args`, `cwd` | what to run, with `{placeholders}` resolved per entry |
 | `env`, `dataEnvs`, `envFile` | environment; `dataEnvs` also marks data directories for backups, `envFile` keeps secrets out of the config |
 | `port`, `bind` | enables the readiness wait, health checks and the conflict preflight; `local` keeps it on `127.0.0.1` |
-| `onPortConflict` | `block` (default), `warn`, `follow`, or `reclaim` — see below |
+| `onPortConflict` | `block` (default), `warn`, `follow`, `reclaim`, or `kill` — see below |
 | `health.mode` | `port` (TCP connect) or `http` (path, expected status, expected body) |
 | `health.unhealthyThreshold`, `forceRestartAfterMs` | how many failed probes before the card warns, and when to restart anyway |
 | `restart.*` | backoff: `maxRetries`, `baseDelayMs`, `factor`, `maxDelayMs`, `resetAfterMs` |
@@ -66,6 +66,7 @@ Preflight runs before every start, so two servers cannot silently fight over one
 | `warn` | it starts anyway — useful when the listener is a leftover you are replacing |
 | `follow` | if the listener is a **detached restart of this same entry**, the panel adopts it as-is; anything else blocks, exactly like `block` |
 | `reclaim` | same detection, but it stops that successor and starts a fully supervised process of its own |
+| `kill` | stops **whatever holds the port** — no ownership test — then starts. The blunt one: see below |
 
 ### When a program restarts itself
 
@@ -74,14 +75,32 @@ update, a `re-exec` on config change. The panel used to see the successor's port
 there blocked while the service was actually up.
 
 Every process gets `HHOSTED_SERVER_ID` in its environment and a successor inherits it, so the preflight
-can tell a successor from a stranger (Linux `/proc`, macOS `ps -E`; Windows has no per-process
-environment, so there you get the conflict banner and the free-port button). Two policies act on that:
+can tell a successor from a stranger — read from `/proc` on Linux and `ps -E` on macOS. **Windows
+cannot read another process's environment**, so there the entry's own argv answers instead: a process
+holding the port is the successor when its image and its arguments are both the entry's own. That
+fallback also covers a Linux or macOS program that restarted itself in a way that dropped the marker.
+Two policies act on the result:
 
 | policy | what it does | trade-off |
 | --- | --- | --- |
 | `follow` | adopts the successor: pid, health probe, CPU/RSS, stop, and it starts its own process again when the successor exits | **keeps exactly what the program set up**, but its output is not captured — the pipe belongs to whoever spawned it, so that entry's log in the panel goes quiet |
 | `reclaim` | stops the successor, then starts a fully supervised process of its own | **full features** — live logs, resources, stop semantics all behave like any other entry — at the cost of one restart |
 
+Identification is deliberately strict, because `reclaim` kills what it identifies: the image has to be
+the entry's resolved command **and** the arguments have to be the entry's own, compared literally — an
+argument sharing a basename with another program's is not a match. When **more than one** holder
+matches, the panel refuses to guess and blocks, naming the pids. These are the cases that still block
+rather than being identified:
+
+- a successor that re-execs under a **different image**, or rewrites its own arguments;
+- an argument read back ambiguously — on macOS `ps` joins argv with spaces, so an argument that itself
+  contains a space cannot be told from two arguments;
+- a Windows entry launched through an `npm`/`pnpm` **`.cmd` shim**: the shim runs under `cmd.exe`, so
+  the process actually holding the port is `node.exe` and its argv never mentions the shim;
+- a Windows entry whose `CommandLine` PowerShell cannot read.
+
+`kill` exists precisely for those cases: it does not need to identify anything.
+
 Both are shown as **detached** in the panel while adopted, both can be stopped and restarted like any
 other entry, and neither will ever start a second copy on top of a **stranger**: that still blocks,
 exactly like `block`.
@@ -91,9 +110,32 @@ is discovered:
 
 ```text
 port 4374 is already in use (pid 912) — pid 912 is a detached restart of this entry:
-set onPortConflict to "follow" to adopt it, or "reclaim" to replace it with a supervised process
+set onPortConflict to "follow" to adopt it, "reclaim" to replace it with a supervised process,
+or "kill" to stop whatever holds the port
 ```
 
+### The `kill` policy
+
+`follow` and `reclaim` need to know *whose* port it is. When they cannot answer that — a program that
+re-execs under a different image, or two holders that both look like the entry — `kill` skips the
+question:
+
+1. SIGTERM every listener on the port, escalating to SIGKILL after `stop.graceMs`.
+2. Wait for the port to actually accept nothing, then start as usual.
+3. If the port is somehow still held, the entry goes to **conflict** with the pids it tried —
+   it does **not** retry in a loop.
+
+It is the one policy that will stop a **stranger** whose port you have configured, so the log says
+which pids it stopped and why. It will not touch the panel itself or any process the panel
+supervises: a port held by a sibling entry is a config mistake and still blocks, exactly as it does
+under `block`. If it is a stray leftover you would rather inspect first, the **Free port** button on
+the server card does the same thing on demand.
+
+Because a detached successor is not something the panel supervises, `kill` ends up doing what
+`reclaim` does for your own restarted process — stops it and starts a supervised child — without ever
+asking whether it was yours. Only `follow` ever adopts, and only `reclaim` will refuse to act on a
+holder it cannot prove is yours.
+
 ## Editing fields
 
 Changes from the panel are atomic and validated before they are written. Editing the file by hand —

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "home-hosted",
   "type": "module",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "packageManager": "pnpm@12.5.1",
   "description": "A self-hosted control panel that keeps your home server processes alive - with a UI you can replace.",
   "author": "NamesMT <dangquoctrung123@gmail.com>",
@@ -33,7 +33,8 @@
   },
   "main": "./dist/cli.js",
   "bin": {
-    "home-hosted": "bin/home-hosted.mjs"
+    "home-hosted": "bin/home-hosted.mjs",
+    "hh": "bin/home-hosted.mjs"
   },
   "files": [
     "AGENTS.md",