home-hosted 0.7.17 → 0.7.18

package/README.md

@@ -269,8 +269,8 @@ can be told what to be: *"Help me build a UI for home-hosted: nostalgic game the
 | 📝 **Hand edits welcome** | Change a workspace's `servers.config.json` in an editor, a `git checkout` or a config tool: the panel notices within seconds, no restart. A file it cannot read is reported in the panel, and the running servers are left alone. |
 | ♻️ **Auto-restart** | Exponential backoff on crash, with the counter reset once a process stays up. |
 | 🩺 **Health that acts** | TCP or HTTP probes per server: warn on the card, force a restart after a timeout, check ports before starting — and [follow or replace](./docs/SERVERS.md#when-a-program-restarts-itself) a program that restarts itself. |
-| 🔗 **Ordered startup** | `dependsOn` waits for a dependency to be *healthy* — not merely spawned — and stops in reverse. |
-| 📜 **Logs** | Live per-server stream, buffer plus rotated files on disk, search, download, one click to clear. |
+| 🔗 **Ordered startup** | `dependsOn` waits for a dependency to be *healthy* — not merely spawned. `stop-all`/`down` stop dependents before their dependencies; stopping one server names the dependents it leaves running. [SERVERS.md](./docs/SERVERS.md#field-reference) |
+| 📜 **Logs** | Live per-server stream, buffer plus rotated files on disk, search, filter to one stream, download, one click to clear. |
 | 📈 **Resources** | CPU and RSS of the whole process tree, with an optional memory ceiling that triggers a restart. |
 | 🌡️ **Host vitals** | Load, memory, swap, disk and CPU temperature, with thresholds that notify once and again on recovery. |
 | 🤖 **Token API** | Scripts and agents drive it with `Authorization: Bearer` — no browser, no session. [↑](#-agents-scripts-and-tools) |
@@ -341,7 +341,7 @@ restarts itself), and how hand-edits are validated: [SERVERS.md](./docs/SERVERS.
 | `home-hosted up` | start the panel detached, and keep it alive in the background |
 | `home-hosted down` | stop it cleanly — supervised processes included, persistent entries left running |
 | `home-hosted restart` | `down`, then `up` — or `restart <id>` to restart one server, leaving the panel up |
-| `home-hosted status` | pid, URL, health, uptime, state and log paths (`--json` for scripts) |
+| `home-hosted status` | pid, URL, health, uptime, state and log paths — the panel's console *and* the per-server directory, naming the `<id>.log` convention once logs exist (`--json` for scripts; stopped answers `{ running: false, initialised }`, where `initialised: false` means nothing was ever set up here) |
 | `home-hosted start <id>` | start one server in the default workspace — and anything it `dependsOn` (`--workspace <id>`) |
 | `home-hosted stop <id>` | stop one server, nothing else (`--workspace <id>`) |
 | `home-hosted restart <id>` | restart one server, nothing else (`--workspace <id>`) — the same as the panel's per-server Restart |
@@ -385,6 +385,10 @@ given. Given a server id — `restart web` — it restarts only that entry, and
 for a launcher that pins one; a workspace picked in the UI keeps its own. `start`/`stop` omit
 `--workspace` to act in the panel's default workspace.
 
+A misspelled command or option names the one you meant — `home-hosted restar` answers
+`did you mean \`restart\`?`, and `up --prt 4000` answers `did you mean \`--port\`?`. Both stay quiet
+when nothing is close, rather than guessing.
+
 </details>
 
 <details>
@@ -420,7 +424,7 @@ Everything binds `127.0.0.1` until you say otherwise.
 - **A password is required to expose the panel.** Replace the default, then bind to `lan` — in the
   UI, in the config, or with `--host lan`. The same guard applies in all three places.
 - **Sessions** live in memory only; the cookie is `HttpOnly` and `SameSite=Strict`, and the login
-  route locks out repeated failures per IP.
+  route locks out repeated failures per IP — see the `trustProxy` note below for when that is advisory.
 - **API tokens** for scripts and agents: `home-hosted set-token --generate` prints one once, and a
   request proves itself with `Authorization: Bearer …` — the same access as a signed-in browser,
   stored as a SHA-256 hash, revoked with `set-token --clear`.
@@ -433,8 +437,16 @@ Everything binds `127.0.0.1` until you say otherwise.
   `.hh/.control-secrets.json`, each workspace's Telegram bot token and DDNS credentials in its own
   `.hh/<workspace>/.secrets.json`, all mode `0600`; the TLS pair sits in `.hh/.tls/`. DDNS credentials
   are sealed with AES-256-GCM under `HHOSTED_DDNS_SECRET` (default `hh` — set your own).
-- **Behind a proxy** turn on `trustProxy` and let `cookieSecure: auto` add `Secure` on https, or
+- **Behind a proxy** pick how far to trust it, and let `cookieSecure: auto` add `Secure` on https — or
   upload a PEM pair and let home-hosted terminate TLS itself.
+  - **`loopback`** trusts `x-forwarded-*` only when the request really came from this machine. That is the
+    right choice for a proxy on the same host: the panel gets the real client address for its lockout and
+    the logs, and a forged header from anywhere else is ignored.
+  - **on** trusts the header from *any* peer. Only when the proxy is the only way in: the client address
+    then comes from the caller's own header, so the per-IP lockout counts per *forged* address and stops
+    throttling brute force. The panel warns at startup when that combination is exposed.
+  - **off** ignores the header entirely. Use it when nothing sits in front, or when the proxy does not set
+    one.
 
 ---
 
@@ -522,6 +534,7 @@ doing and anything it could not finish:
 home-hosted logs              # the last 50 lines
 home-hosted logs --follow     # keep printing, like tail -f
 home-hosted logs --lines all  # the whole thing, including the rotation
+home-hosted logs --json       # { path, lines } — or one object per line with --follow
 ```
 
 It is the same file `status` names, and reading it needs no session or API token — a panel that
@@ -574,12 +587,13 @@ workspaces.json              the registry: ids and labels, in selector order
 .ui/                         an installed custom UI
 .backups/                    zip archives
 .logs/                       the panel's own console log
+.proxy/                      the reverse proxy's engine, its config and state
 run.json                     the running panel (pid, url, token, mode 0600)
 
 <workspace>/settings.json    server defaults, log retention, notifications, DDNS
 <workspace>/servers.config.json  your servers, plus meta: which release and schema wrote it
 <workspace>/.secrets.json    Telegram token + DDNS credentials (mode 0600)
-<workspace>/.logs/           rotated per-server logs + history
+<workspace>/.logs/           per-server logs: <id>.log, rotated to <id>.log.1 … (newest first)
 <workspace>/.state/          persistent entries' nanny state
 ```
 
@@ -595,6 +609,11 @@ proxy is the one panel-wide listener, and only when you switch it on: `80`/`443`
 or `4480`/`4443` unprivileged with your router forwarding to them
 ([REVERSE_PROXY.md](./docs/REVERSE_PROXY.md#ports)).
 
+**If that port is taken, `up` names who holds it** — the pid and the command line, when the OS will
+tell it — rather than only reporting the number. A `follow` entry adopts the process that replaced it;
+an unrelated listener is never signalled
+([SERVERS.md](./docs/SERVERS.md#a-busy-port)).
+
 </details>
 
 <details>