dsh-home-hosted 0.8.1 → 0.9.0

package/README.md

@@ -16,7 +16,7 @@ Ask for a Gitea, a Jellyfin, an FTP server; `dsh-home-hosted` sets up the entrie
 [![CI](https://github.com/NamesMT/dsh-home-hosted/actions/workflows/ci.yml/badge.svg)](https://github.com/NamesMT/dsh-home-hosted/actions/workflows/ci.yml)
 [![license](https://img.shields.io/npm/l/dsh-home-hosted?color=green)](./LICENSE)
 [![node](https://img.shields.io/badge/node-%3E%3D24-339933?logo=node.js&logoColor=white)](https://nodejs.org)
-[![dsh](https://img.shields.io/badge/dsh-%3E%3D0.2.0--rc.1-5b21b6)](https://github.com/deepseek-ai/dsh)
+[![dsh](https://img.shields.io/badge/dsh-0.2.0--rc.1%20%7C%7C%200.2.1--rc.2-5b21b6)](https://github.com/deepseek-ai/dsh)
 
 [🚀 Quick start](#-quick-start) · [🎛️ What the plugin does](#-what-the-plugin-does) · [🤖 Agent tools](#-agent-tools) · [🧩 Depth](#-depth)
 

package/docs/BOOT.md

@@ -92,6 +92,33 @@ stays `available` and its install reports "loads at the next login" instead of r
 `bootstrap`/`enable`/`print` steps need the domain, and they are skipped when it is unreachable. The
 daemon scope still needs root for `/Library/LaunchDaemons`.
 
+## Windows: logon, or boot as SYSTEM (opt-in)
+
+Windows gets three mechanisms, because "starts at login" and "starts before login" are genuinely
+different trades on that platform:
+
+| mechanism | starts | who it runs as | needs |
+| --- | --- | --- | --- |
+| `windows-run` | at login | you, in your session | nothing |
+| `windows-task` | at login | you, in your session | admin |
+| `windows-boot` | at boot, before any login | `SYSTEM` | admin |
+
+`windows-boot` is **never chosen by Automatic**, even though it is the only one that comes up without a
+login. It runs in **session 0**, which has no interactive desktop and no loaded user profile — so a
+supervised server that wants a display, a GUI, or the user's own environment breaks there. The panel
+itself is fine (server rows are launched with `--no-open`, so nothing tries to open a browser), which is
+exactly why this is a per-machine decision rather than a default. Measured on Windows 11: a
+`BootTrigger` task with the SYSTEM SID really does run in session 0, and the Task Scheduler accepts the
+generated XML.
+
+The two task mechanisms register under **different names** — `home-hosted` and `home-hosted-boot` — so
+installing one does not replace the other and you can switch back. Only the boot task carries a boot
+trigger, and only it uses the SYSTEM SID; neither stores a password, because a task that needs a named
+account's credentials would be a credential store, not a boot entry.
+
+Neither mechanism offers a stop: `/End` was measured to deliver no shutdown request and to leave
+orphans behind, so the CLI's `down` remains the only stop that runs the supervised stop policy.
+
 ## Escaping is per setting, not per file
 
 A unit file is read by systemd, not by a shell, and its settings do not share one
@@ -137,6 +164,21 @@ keys (`Path=`, `Name=`, `Comment=`), and `Exec=` applies it on top of its shell
 Every ownership check reads the escaped marker too, or a marker carrying a backslash would
 be written escaped and searched for raw — and the plugin would call its own entry foreign.
 
+## Once an entry is installed, it owns the panel's start and stop
+
+The page's Start and Stop buttons drive that entry, not the CLI. On systemd that is
+`systemctl restart|stop` — a restart rather than a start, because the button appears when `/healthz`
+does not answer and a wedged panel is still active to systemd, where a plain `start` is a no-op; a `Restart=always` unit restarts a process that dies *outside* systemd, so
+the CLI's `down` brought the panel back seconds later and the page reported a stop the machine had
+already undone. systemd's own manual is explicit: "When the death of the process is a result of
+systemd operation (e.g. service stop or restart), the service will not be restarted." On launchd it
+is `kickstart -k`/`kill` for the same reason (`KeepAlive`). A Windows scheduled task offers the start
+only — `schtasks /End` kills the process tree rather than shutting the panel down.
+
+The wait after each action is for the same reason: a `Type=exec` unit reports started once `execve`
+returned, before the panel bound its port, so the call polls `/healthz` and returns as soon as it
+answers (~1.2 s measured here). The 20 s ceiling only bounds a panel that never answers.
+
 ## Enabling autostart hands the panel over
 
 An install alone proves nothing. The panel the plugin started keeps running, so nothing shows whether
@@ -161,10 +203,11 @@ whole design:
 4. start the entry;
 5. only then remove the other mechanisms' entries.
 
-The stop is always the CLI's `down`, never the new mechanism's own `restart`: the entry would then be
-starting a *second* panel, which home-hosted refuses while `run.json` names a live pid, so a
+In a handover the stop is the CLI's `down`, never the new mechanism's own `restart`: the entry would
+then be starting a *second* panel, which home-hosted refuses while `run.json` names a live pid, so a
 restart-in-place over an orphan only produces a failed unit. Waiting on the pid matters for the same
-reason.
+reason. This is the one place the CLI is the right stop for a supervised panel — it is the path that
+retires the old entry, so nothing is left to restart it.
 
 Retirement is last, and deliberately not part of `install()`. Switching mechanism has to uninstall the
 old one, but the old entry is often what is currently running the panel: removing it during the install
@@ -202,7 +245,7 @@ Each mechanism sends it somewhere different, and the status line now names where
 | `systemd-user` / `systemd-system` | the journal — the unit sets no `StandardOutput=`, so the detail names `journalctl --user -u <unit>` or `journalctl -u <unit>` |
 | `launchd-agent` / `launchd-daemon` | `<logDir>/<label>.out.log` and `<label>.err.log`, the two paths the generated plist carries |
 | `xdg-autostart` | nowhere persistent: a `.desktop` entry with `Terminal=false` has its output discarded by the session |
-| `windows-run` / `windows-task` | nowhere persistent either |
+| `windows-run` / `windows-task` / `windows-boot` | nowhere persistent either |
 
 So the hint appears only where a file or a query actually exists — and only once the entry is
 installed, because naming a log for an entry that was never written sends someone to a

package/docs/DESIGN.md

@@ -38,11 +38,12 @@ its page.
 `onPortConflict: kill` (0.6.0), `persistent` (0.6.3), `restart <id>` (0.7.13) and the nullable-`label`
 patch (0.7.21) all predate the release this plugin pins. The plugin used to consult the answering
 panel's version and refuse or drop those keys (`KILL_UNSUPPORTED`), and later to retry a `restart` as a
-stop-then-start pair. Both are gone: it pins `home-hosted@^0.8.0`, which refuses an older panel
+stop-then-start pair. Both are gone: it pins `home-hosted@^0.9.0`, which refuses an older panel
 outright, so neither check could ever fire again.
 
 An old state root is upgraded by running the latest 0.7.x **once, before installing 0.8** — its first
-run moves the state into `.hh/`.
+run moves the state into `.hh/`. A root a 0.8-era panel left on config schema 1 needs
+`home-hosted migrate` before this plugin will write it; see [PANEL](PANEL.md#upgrading-an-existing-state-root).
 
 ## Tests
 

package/docs/PANEL.md

@@ -56,10 +56,40 @@ plus its `.1`, and the 5 MB rotation — is unchanged too, and this plugin's rea
 **0.8.0 stopped relocating an old state root, and this plugin follows it.** A 0.6.x root used to be
 moved into `.hh/` on 0.7's first run; 0.8 refuses it instead, before any command resolves a path into
 it, so a config at the old paths is never read as an empty panel. **Upgrading from 0.7 or earlier? Run
-the latest 0.7.x once first — that release moves the state — then install 0.8.** The plugin's floor is
-`0.8.0` for the same reason, so a 0.7.x panel is reported as unsupported rather than driven. That
-removed the last version-conditional code here: a stop-then-start fallback for a panel without
-`restart <id>`, and `panel.migrate`, whose CLI no longer performs the move.
+the latest 0.7.x once first — that release moves the state — then install 0.8.** That removed the last
+version-conditional code here: a stop-then-start fallback for a panel without `restart <id>`, and
+`panel.migrate`, whose CLI no longer performs the move.
+
+**0.9.0 raised the config schema to 2, and it changed what an unstamped file means.** Schema 2 folds
+the Telegram singleton and the webhook list into one `notifications.destinations` list. The part that
+bites here is the stamp: a file with no `meta.schema` is read as the **oldest** shape, so 0.9's `up`
+refuses to start it — `config schema 1 needs 1 migration`. This plugin writes workspace configs
+directly whenever the panel does not answer, and it used to stamp them with `meta.writtenBy` alone, so
+a config it created before any panel had run was unstartable on 0.9. It now stamps `meta.schema` on
+every file it **creates**, reading the number from the pinned release rather than hard-coding it — a
+fixed `2` would break again at the next bump, from the other side.
+
+A file that already exists **without** a stamp is refused instead of stamped: its content may still
+need lifting, and stamping it would claim a migration that never ran and silently strand what the step
+rewrites. Measured: a schema-2 stamp over an old `notifications.telegram` block makes 0.9 report the
+key as unrecognized and ignore it, so the person's notifications end up silently off. Lifting a config
+is `home-hosted migrate`'s job, and the refusal names it.
+
+The floor is `0.9.0` for the same reason the pin is: a 0.8.x panel reads a schema-2 stamp as a *newer*
+release's file and refuses that in turn, so no stamp satisfies both and there is no version-conditional
+path. A 0.8.x panel is not a lesser-supported copy — it is one this plugin cannot drive.
+
+### Upgrading an existing state root
+
+A root a 0.8-era panel wrote is on config schema 1. Run the panel's own migration once, before letting
+0.9 — or this plugin — write it:
+
+```sh
+home-hosted migrate --dry-run   # print the steps, write nothing
+home-hosted migrate --yes       # keep a .bak beside each rewritten file
+```
+
+Both sides are then on schema 2, and every write stays readable by the release that pinned it.
 
 **0.7.21 widens that nullable set by one field, and it closed a bug here.** Clearing a server's label
 sent an empty string, which the panel accepts and saves — so the entry kept a blank label instead of
@@ -104,10 +134,43 @@ exact stock body, guards every assignment, and replaces the response's `end` for
 authentication plugin's own page (or an exotic response) is passed through untouched rather than fought
 over. `authNotice` turns it off; `{url}` is read per 401.
 
-## Starting and replacing the panel
-
-`panel.start` runs the preferred CLI's `up`, which detaches itself and returns once the panel answers —
-that is the whole out-of-the-box path when nothing is running.
+## Starting and stopping the panel
+
+`panel.start` and `panel.stop` ask the *installed* autostart entry first, and fall back to the CLI's
+`up`/`down` only when nothing supervises the panel. That fallback is the out-of-the-box path: with no
+entry, the CLI is the only thing that can start one.
+
+It cannot be the other way round. An entry that carries a restart policy — `Restart=always` for
+systemd, `KeepAlive` for launchd — reads the CLI's `down` as an unexpected death and starts the panel
+again seconds later, so "Stop the panel" came back on its own: a stop the page reported and the machine
+did not honour. The mirror is just as wrong: a CLI `up` starts a panel *outside* the entry, which then
+cannot be stopped or observed by it either. Whoever supervises the panel is who may change its state.
+
+So an installed `systemd-user`/`systemd-system` entry answers with `systemctl start|restart` and
+`stop`, and a `launchd-agent`/`launchd-daemon` with `kickstart`/`kickstart -k` and `kill`. The verb
+follows the entry's own state, read before acting: `start` when the unit is not running, `restart`
+when it is — the Start button appears when `/healthz` is silent, and a wedged panel is still active,
+where a plain start would be a no-op. Probing matters, because that trigger is a 2 s health probe: a
+merely slow panel must not be restarted, and restarting it would stop the servers it supervises.
+
+Mechanisms that start the panel from outside their own control — a `.desktop` file, a `Run` value, a
+container restart policy — have no stop to offer, so those fall back to the CLI.
+
+A Windows scheduled task is a partial case, and the one place Start may not recover a wedged panel: it
+offers `schtasks /Run` and no stop. Measured on Windows 11: `/End` asks the task to shut down in no
+form a program can observe (a PowerShell `trap` never ran) and, while reporting success, leaves child
+processes alive — so the CLI's `down` is the only stop that runs the panel's own stop policy. The task is registered `MultipleInstancesPolicy=IgnoreNew`, so `/Run` on a running
+instance does nothing, and `schtasks` has no graceful restart — pressing Start on a wedged Windows
+panel therefore reports that the panel did not answer, rather than recovering it. Stopping still goes
+through the CLI's `down`, which is graceful.
+
+The entry's command returns as soon as the service manager accepted it, which is not the same as the
+panel answering: a `Type=exec` unit counts as started once the binary was executed, before it binds
+its port. So the call then polls `/healthz`, and stops as soon as the panel answers — about a second
+on the development machine this was measured on. The 20 s is only the ceiling for a panel that never
+answers, matching the CLI's own startup budget. A stop follows the same rule with a 5 s ceiling: if
+the entry's stop ran but the panel still answers, it was not the panel that entry supervises, and the
+CLI's `down` finishes the job.
 
 `panel.takeover` replaces an answering panel with the preferred copy. Stopping the old panel also stops
 the non-persistent servers it supervises — this dsh only if it is one, which an entry this plugin