dsh-autorestart 0.6.2 → 0.8.0

package/README.md

@@ -13,6 +13,13 @@ Chinese version: [README.zh.md](docs/README.zh.md)
 
 `dsh-autorestart` turns a DeepSeek Harness restart into a resumable event instead of a dead end.
 
+**New in 0.7.0** — it now also knows *how it was started*: the desktop client, somebody else's
+supervisor (a shell script, systemd, a container, pm2, a Windows scheduled task), or a bare process
+nobody manages. It never starts a second DSH next to a running one, and when it cannot tell it does
+nothing instead of guessing a command. The settings page shows what is really inside the
+pre-restart backups (count, local time, size, path), and carries a **Report a problem** entry that
+copies the diagnostics and opens a pre-filled GitHub issue.
+
 An agent can request a graceful restart. The plugin waits until every conversation is idle and the
 host has been quiet for the settle window, then it restarts the host. Once the host is back, the
 interrupted sessions resume automatically: a session that owns a durable goal gets that goal
@@ -51,6 +58,121 @@ Two safety gates protect the restart. The host checks that no conversation is bu
 helper checks the same gate over loopback immediately before it kills the process, so a turn that
 starts in between is never killed.
 
+## The whole thing in one page (ordinary users can stop here)
+
+### Why a restart does not lose your work
+
+The plugin turns a restart into a **resumable** event, and the order never changes:
+
+1. **The session state is written to disk first** — what every conversation was doing and which
+   goals were still armed goes into a checkpoint on disk;
+2. **It queues until every conversation is idle** — whoever is still running is waited for;
+3. **The process is replaced** — the old one exits, a new one comes up (the desktop app relaunches
+   itself; the hosted web client is covered below);
+4. **The new process checks itself** — four things: is the port up, are the routes there, did the
+   plugin load, did the sessions resume;
+5. **If it did not come up, it rolls back** — the pre-restart snapshot (configuration + installed
+   plugins) is put back, and the verdict of that restart is written down honestly.
+
+So "the restart lost my work" becomes "the restart carried on": you do not have to type "continue".
+
+### Two shapes of DSH, each minding its own business
+
+| | Desktop client | Hosted web client (`dsh web`) |
+|---|---|---|
+| Who brings it back | **the app itself** (it closes itself and opens itself again) | it first asks "who started me?" |
+| Should a system service be installed | **no** — installing one makes it start **twice**: one more DSH at every login | only when *nobody* manages it |
+| Somebody else already manages it (a supervisor script / systemd / a container / pm2 / a Windows scheduled task…) | n/a | **it only exits gracefully** and lets that supervisor bring it back (it does not start a second one) |
+| It cannot tell who started it | n/a | **it does nothing and guesses no command** — "I cannot tell" beats starting a second copy next to the first |
+
+### "Start at login": the plugin gives advice, it does not change your system
+
+The plugin **never** changes your system configuration and **never** registers a startup entry for
+you. It explains in the settings page how "start at login" works on *this* machine; the commands can
+be copied, and whether you use them is your call.
+
+| Your situation | What it recommends | Note |
+|---|---|---|
+| `dsh web` on Windows | start at login: a scheduled task first (no administrator rights); if this machine refuses that, a `.cmd` in the startup folder | the record runs a **real node** + the supervisor script, not the DSH client itself (that would open a second DSH at every login) |
+| Linux (not WSL) | a systemd user service | that is **start after login**; **start at boot** (without a login) needs the linger enabled once |
+| WSL with systemd | the same: a systemd user unit + the linger | same |
+| WSL without systemd | there is no "start at login" at all. Two ways out: ① turn systemd on inside WSL (change the distribution's configuration and restart the subsystem); ② let the Windows side start the distribution with a scheduled task or a startup-folder entry (much closer to a real boot autostart) | the plugin **never** changes your distribution's configuration for you, and it never recommends a container-orchestration setup inside WSL (the orchestrator of WSL is Windows itself) |
+| container / k8s | the orchestrator does it (`restart: always` and friends) | there is no "start at login" inside a container |
+
+**"Start after login" and "start at boot" are not the same thing**: the first waits for you to log
+in, the second happens when the machine comes up (and needs the linger enabled once). The plugin
+writes that sentence and the matching command into the settings page.
+
+### If DSH does not come up
+
+**First work out which situation you are in**: if the whole environment is broken (a changed
+configuration, another plugin, a bad upgrade) → go back to the last good state; if **only this
+plugin** is suspect → take this plugin out instead.
+
+**And use the scripts of YOUR platform** — a Linux machine has no `.cmd` file, and a Windows
+machine has no `.sh`:
+
+| Your machine | back to the last good state | take this plugin out |
+|---|---|---|
+| **Windows** (the desktop app, `dsh web` on Windows) | double-click `scripts/restore-profile.cmd` | double-click `scripts/emergency-disable.cmd` |
+| **Linux / WSL / macOS** (`dsh web`) | `sh scripts/restore-profile.sh` | `sh scripts/emergency-disable.sh` |
+
+Two scripts per platform, and they do different jobs:
+
+- **`restore-profile.cmd` / `restore-profile.sh` — back to the last good state.** It puts the
+  newest snapshot that carries a manifest back over the profile, and leaves the broken one behind
+  as `profile.broken-<timestamp>` (moved aside, not deleted). It does not restart DSH for you.
+- **`emergency-disable.cmd` / `emergency-disable.sh` — take this plugin out and change nothing
+  else.** It removes only `dsh-autorestart` from the profile's bundle list and keeps a backup of
+  the file.
+
+**Which one:** "back to the last good state" → `restore-profile`; "I only suspect this plugin" →
+`emergency-disable`. The boundaries (the profile directory has to exist, a snapshot with a
+manifest is required, DSH is never restarted for you, the `broken-` folder stays) are written down
+in [`scripts/README.md`](scripts/README.md).
+
+**What each platform can do** (and what it cannot) is spelled out in
+[`docs/platform-matrix.md`](docs/platform-matrix.md) — the settings page shows the paths of the
+scripts that really exist on the machine you are on.
+
+### What has really been tested
+
+| How it was started | Tested on a real machine? | Evidence |
+| --- | --- | --- |
+| started by a shell supervisor script (`supervise-*.sh` and friends) | **yes** | recognised on a real machine as external, the evidence points at that script process, and **installing a second supervisor was refused** |
+| started by hand in a terminal (foreground) | **partly** | on a real machine it recognised itself as "nobody manages it" (mode `bare`, the evidence is the parent being bash) and handed out an installation plan; the real "install → run → uninstall" was done on an instance that was **already managed by a supervisor**, so the bare instance never had the full install/uninstall cycle |
+| started in the background (`nohup` / `setsid`) | **partly** | on a real machine it was recognised as a bare background start; **"the re-launch command outlives its shell" is pinned by unit tests only** (the machine did not report the detached flag back then) |
+| WSL with systemd | **yes** | really installed and really removed |
+| a Windows login task | **partly** | on a real machine one login-triggered task was created → queried (State=Ready, the logon trigger) → deleted (no leftovers) with the system's own tools, which proves that no administrator rights are needed; **"the fallback into the startup folder when the task is refused" is pinned by unit tests only** |
+| the desktop client | **yes** | on a real machine it comes back by itself (there is a snapshot and a self-check record, no rollback was triggered, and it does not start twice); that is the client's own business, it is not part of the hosted matrix |
+| pm2 / forever | no, unit tests only | the recognition and the behaviour are pinned by unit tests |
+| container / compose | no, unit tests only | same |
+| `npx` / `pnpm dlx` wrapper | no, unit tests only | same |
+| started by another DSH plugin | no, unit tests only | same |
+| tmux / screen / an SSH session | no, unit tests only | same |
+| WSL started by a Windows-side process | no, unit tests only | same (it is recognised as "cannot tell", so nothing happens) |
+
+**Not tested on a real machine does not mean unsupported**: those paths are pinned by unit tests, and
+"no full install/uninstall cycle" or "unit tests only" does not mean unsupported either. If your
+environment is recognised wrongly, please send us the "startup mode + the evidence" block from the
+settings page.
+
+### Report a problem
+
+The settings page has a "**Report a problem**" group at the bottom:
+
+- The main button "**Copy the diagnostics and open a GitHub issue**": one click puts the diagnostics
+  on the clipboard and opens a **pre-filled** issue page (title and outline) — paste the clipboard
+  text into it.
+- The diagnostics carry **no access token and no secrets**: only the plugin version, the platform,
+  whether this is the desktop client, how the host was started (with the evidence), the supervisor,
+  the restart mode, and the verdict of the last restart (with the checks that failed).
+- When the browser refuses the clipboard (an insecure context, or no permission), the plugin shows
+  the diagnostics in a **selectable** box and says so — a report never dies because the browser said
+  no.
+- No GitHub account? The same group shows the mailbox (252170229@qq.com) as plain text, plus a
+  "Copy the diagnostics" button.
+
 ## What it occupies in DSH
 
 Nothing here is hidden: this is the complete list of where the plugin attaches itself, so you can see
@@ -64,7 +186,7 @@ what it adds before you install it.
 | System prompt | One "Restart policy" section that tells the agent how to ask for a restart and what the plugin will do |
 | Harness hooks | `agent/status` (tracks which conversations are busy), `tools/pre-execute` (blocks a shell command that would kill or relaunch DSH by hand), and the boot pass that resumes interrupted sessions |
 | Profile row | One bundle row, `dsh-autorestart` |
-| Writes | Only under `<DSH_HOME>/storages/dsh-autorestart/` — `state.json` (checkpoint), `backups/` (pre-restart snapshots), `restart-<gen>.cmd` / `restart-<gen>-watch.ps1` (the detached helper), `last-rollback.json` (rollback report). The only time it writes into the profile itself is a rollback, which copies that snapshot's `cordis.patch.yml`, `package.json`, `pnpm-lock.yaml` and `node_modules` back |
+| Writes | Only under `<DSH_HOME>/storages/dsh-autorestart/` — `state.json` (checkpoint), `backups/` (pre-restart snapshots), `restart-<gen>.cmd` / `restart-<gen>-watch.ps1` (the detached helper), `last-rollback.json` (rollback report), `restart-outcome.json` (the decision of a restart the plugin judged itself), `access.json` (the access link of the running instance, mode `0600`). The only time it writes into the profile itself is a rollback, which copies that snapshot's `cordis.patch.yml`, `package.json`, `pnpm-lock.yaml` and `node_modules` back |
 
 ## Why
 
@@ -76,7 +198,7 @@ what it adds before you install it.
 
 ## Install
 
-Current version: **0.6.2**.
+Current version: **0.8.0**.
 
 From npm — the package is published under the name `dsh-autorestart`:
 
@@ -111,7 +233,7 @@ so you can call them yourself.
 | --- | --- | --- |
 | `continuum_restart` | Requests a graceful restart. The restart waits until every conversation is idle and the host has been quiet for `settleMs`, then the app is relaunched and this session resumes automatically. | `reason` (string, recorded in the checkpoint and the log), `resume` (boolean, default `true`), `defer_seconds` (number, extra seconds to wait before the first idle check), `parkGoals` (boolean, default `true`) — disarm a goal-driven session before the restart |
 | `continuum_status` | Read-only snapshot of the lifecycle: whether a restart is pending, which sessions were checkpointed, why each blocking session blocks, the goals this plugin disarmed, the last recovery action per session, the handoffs, the state file path and the detected restart environment. | `include_sessions` (boolean, default `true`) — include the per-session checkpoint entries |
-| `continuum_cancel_restart` | Cancels a pending restart and releases the continuation request of every requester. Does nothing when no restart is pending. | none |
+| `continuum_cancel_restart` | Withdraws a pending restart request. By default it withdraws **only the calling session's own request** (`scope: "mine"`); the other sessions that asked for the same restart keep it. `scope: "all"` cancels the request for everyone. Does nothing when no restart is pending. | `scope` (string, `mine` (default) or `all`), `reason` (string, recorded in the log) |
 | `continuum_park_goal` | Disarms the goal of a session so that it no longer blocks the restart. The current round still finishes and the goal is re-armed after the restart. | `sessionId` (string, optional) — defaults to the calling session |
 | `continuum_recover_now` | Re-runs the recovery immediately instead of waiting for the next restart, and reports the action and the reason for each session. | `sessionId` (string, optional) — defaults to all sessions pending recovery |
 | `continuum_handoff` | Hands a session whose conversation exceeded the model context window over to a fresh session, carrying the goal objective, the recorded reasons and a bounded tail of the conversation. | `sessionId` (string, optional) — defaults to the calling session, `maxChars` (number, default `20000`) — character budget for the conversation tail |
@@ -119,8 +241,66 @@ so you can call them yourself.
 A goal is an enhancement, not a requirement: without one, the plugin injects a single continuation
 message instead of re-arming a goal.
 
+### Cancelling a restart: only your own request, or everybody's
+
+A restart request is **coalesced**: several sessions may ask for the same restart, and the plugin
+keeps every requester in `restart.requesters` so that all of them are resumed after that one
+restart. That is why "cancel" has to say **whose** request it cancels:
+
+| Scope | What happens |
+| --- | --- |
+| `mine` (the default) | Only the **calling session's** request is withdrawn. The restart stays pending while other requesters remain, and `restart.bySessionId` is re-pointed at one of them. When the calling session was the **last** requester, the restart really goes away: the phase returns to `idle` and the session is released. |
+| `all` | The request is cancelled for **everybody**: every requester is released and the pending restart is gone. This is "nobody restarts any more". |
+
+Two calls are refused, and both leave the state untouched — a silent "cancel everything" is never
+the fallback:
+
+- the calling session is unknown (the tool was called without a session) → refused;
+- the calling session did **not** ask for the pending restart → refused.
+
+The tool reports what happened: `cancelled` (whether the restart request itself is gone),
+`remainingRequesters` (how many sessions still wait for it), `scope` and `phase`.
+
+```json
+{ "ok": true, "cancelled": false, "scope": "mine", "remainingRequesters": 1, "sessionId": "sess-a", "phase": "deferred" }
+```
+
+### The capsule: click it for the details and for the way out
+
+The capsule in the composer row is 22px high and ONE line wide, so it carries numbers only
+(`待重启 · 已等 16 分钟 · 3 项任务在跑`) — never a name and never a hint. Clicking it (or pressing
+Enter/Space on it) opens a small panel above it:
+
+- how many tasks the restart is waiting for;
+- how many OTHER sessions wait for the same restart;
+- one button: **Cancel my restart**.
+
+The button opens a confirmation (no timeout, nothing counts down): *Cancel your restart?* — and what
+cancelling means right now (only you, or you while the others still get their restart). Only the
+confirmation sends the request; `Esc`, a click outside the panel or **Never mind** closes it without
+doing anything.
+
+The request withdraws ONLY this session's restart request (`POST /__dsh_autorestart/cancel` with
+`{ "sessionId": "…", "scope": "mine" }`): the other sessions keep theirs, and the restart still
+happens for them. There is no "cancel everybody" in the panel — that stays an explicit tool call
+(`continuum_cancel_restart` with `scope: "all"`).
+
 ## Configuration
 
+Two blocks of the settings page are worth a word, because they show facts instead of guesses:
+
+- **What is backed up right now** (right under the two backup switches): the HOST reads
+  `<DSH_HOME>/storages/dsh-autorestart/backups/`, so the number of copies, the **local time** of each
+  one, its size (MB), whether the installed plugins are in it and where it lives are all real. Only
+  the directory metadata is read — the contents are never walked (one copy can be 150 MB). With no
+  backup at all it says: "No backup yet; one is written before every restart."
+- **How this host was started** (hosted web only): one plain line ("How I remember you were started:
+  by your own script (the restart is its job — I stay out of it)") plus two small actions (detect
+  again / undo); the command itself is folded away under **"Technical details"** and stays closed
+  until somebody opens it. The **desktop client does not render that block at all** — it brings
+  itself back up and must never write a `restartCommand`. When the Host cannot say which kind of
+  host this is, the whole block stays away.
+
 Every key has a default, written in the `insert` row of `cordis.patch.yml`. To override a key, add
 an `- id: dsh-autorestart` row with the same key to the `cordis.patch.yml` of the profile at
 `~/.dsh/profiles/<profile>/cordis.patch.yml` (it replaces the whole config, it is not merged). The
@@ -154,7 +334,9 @@ show up in the Plugin Manager and in the config editor.
 | `backupOnRestart` | `true` | Snapshot the profile before every restart, so a restart that leaves the host unable to boot can be rolled back. |
 | `backupIncludePlugins` | `true` | Include the installed plugin tree in that snapshot (about 117 MB here, ~3 s). `false` keeps only the configuration files. |
 | `maxBackups` | `2` | How many snapshots are kept; older ones are deleted when a new one is written. |
-| `rollbackTimeoutMs` | `90000` | How long the detached watcher waits for the relaunched host before it restores the snapshot and launches the host again. |
+| `rollbackTimeoutMs` | `90000` | How long the detached watcher waits for the new host before it restores the snapshot. |
+| `restartCommandTimeoutMs` | `30000` | How long the restart command may run before the plugin stops waiting for it. A command that starts the host in the foreground never returns — that is reported as "still running", not as a failure. |
+| `rollbackCopyTimeoutMs` | `120000` | How long ONE restore step (the configuration files, then the plugin tree) may take. A restore that does not finish in time is given up and the reason is written into the rollback report. |
 | `showSleepButton` | `true` | Whether the moon button of the graceful shutdown is shown at the foot of the left sidebar, next to Settings. |
 | `sleepCommand` | `''` | A custom shutdown command for the graceful shutdown. Empty = the host is detected automatically; a value replaces the detected command (`cmd.exe /c …` on Windows, `/bin/sh -c …` everywhere else). |
 
@@ -306,23 +488,242 @@ it was started from, so a restart that leaves the host unable to boot can be und
   like this one the full snapshot measures about 117 MB and takes under three seconds.
 - **How many are kept:** the newest `maxBackups` snapshots (default `2`); older ones are deleted when
   a new one is written.
-- **How a failed boot is detected:** the detached helper that kills and relaunches the host also runs
-  a small PowerShell watcher. It polls the health route for `rollbackTimeoutMs` (default `90000`). A
-  healthy answer ends the watch and nothing is touched.
+- **How a failed boot is detected:** a small watcher runs **outside** the host process (so it survives
+  the host being killed). It waits for the **new** instance and probes **its** health route for
+  `rollbackTimeoutMs` (default `90000`). The new instance publishes its own port and its own boot id
+  in `<storage>/dsh-autorestart/access.json`, so the watcher never mistakes the old instance (or the
+  old port) for the new one. A healthy answer ends the watch and nothing is touched.
 - **What happens when the host never answers:** the watcher copies the snapshot back over the profile
-  (configuration files, and the plugin tree when the snapshot holds one), writes
+  (configuration files, and the plugin tree when the snapshot holds one) and writes
   `last-rollback.json` next to the checkpoint — including the tail of the newest crash log written
-  *after* this restart — and launches the host again with the restored configuration.
+  *after* this restart and the reason the restore failed, if it did. It does **not** start a second
+  copy of the host: the instance that was launched is left alone, so there is never a second window
+  or a second web server.
+- **The hosted mode has the same safety net.** With `restartMode: command` the restart command
+  usually kills the very process the plugin runs in, so the plugin cannot confirm anything itself.
+  The watcher is therefore started **before** the command runs, and it is the one that decides
+  whether the new instance came up.
+- **The command is judged, not assumed.** A restart command that cannot be started, or that exits
+  with an error, is reported as a failure (with its exit code and output) and the snapshot is
+  restored — it is never reported as a successful restart.
 - **How you learn about it:** the next boot reports it. `continuum_status` gains a `lastRollback`
-  object (`at`, `waitedMs`, `rolledBack`, `backupDir`, `crashLog`, `crashTail`), and the next restart
-  clears the report so it is never mistaken for a fresh one.
+  object (`at`, `waitedMs`, `rolledBack`, `reason`, `backupDir`, `crashLog`, `crashTail`), and the
+  next restart clears the report so it is never mistaken for a fresh one.
 - **Turning it off:** `backupOnRestart: false` skips the snapshot entirely (no rollback point, and no
   watcher), which is what a user who keeps their own backups may prefer. `backupIncludePlugins:
   false` keeps the snapshot but limits it to the configuration files.
 
 The rollback is deliberately conservative: it only runs when the relaunched host never answers its
 own health route. A slow start inside `rollbackTimeoutMs` is never treated as a failure, and a
-healthy host is never touched.
+healthy host is never touched. The restore itself is bounded as well: every copy step gives up after
+`rollbackCopyTimeoutMs` (default `120000`) and says so in the report.
+
+### When the machine refuses a scheduled task (the automatic rollback is gone)
+
+The safety net above hangs on a **one-off scheduled task**: the helper that brings the host back
+after a restart is a task that fires a minute later. On a machine where such a task cannot be
+created (a corporate policy, a locked-down account, a machine without the rights) the net is
+silently missing.
+
+So the plugin **checks the machine once** — the first time it runs there — and tells the truth in
+the settings page:
+
+- `Automatic rollback: available` — the net is there.
+- `Automatic rollback: **not available**` — and exactly what is lost: *DSH will not recover by
+  itself when it does not come up after a restart*. The line points at the restore script in
+  "If DSH will not start", which is the way out.
+
+**What this deliberately does NOT do:**
+
+- **No fallback chain.** There is no "use the startup folder instead", no "use a systemd timer
+  instead", no second mechanism that is tried when the first one is refused.
+- **No bypassing the policy.** The plugin does not look for a way around a machine that says no.
+  If the machine refuses, the answer is "not available" — and only that is reported.
+
+A refused check is **never** a failed installation: the plugin works exactly as before, only the
+safety net is missing. The check itself is harmless by construction — it registers a task that
+fires in two minutes and does nothing (`cmd /c exit 0`), reads it back, deletes it, and reads it
+back once more to prove that it is gone. It runs **once**, not on every visit of the settings page,
+and it never leaves a task behind (not even when a step of it fails).
+
+### The watchdog: the three ways it can be triggered
+
+The rollback above needs somebody to *wait*: the host is restarted, and a
+one-off thing has to notice that the new host never came up. That thing is the
+**watchdog** (`scripts/watchdog.mjs`), and how it is triggered is the part
+that differs between the machines — so the plugin picks the best way the
+machine has and says which one it picked:
+
+| Tier | Mechanism | Where |
+|---|---|---|
+| `scheduled-task` | a one-off Windows scheduled task (read back after it was registered, deleted completely afterwards) | the desktop app and `dsh web` on Windows |
+| `systemd-run` | a systemd user timer (`systemd-run --user --on-active=…`), reset when it is over | `dsh web` on Linux, WSL with systemd |
+| `detached-process` | a background process of our own (`setsid nohup sh -c 'sleep …; …'`), its pid in the state directory | containers, WSL without systemd |
+| `none` | nothing on this machine | then there is **no automatic rollback**, and the settings page says so |
+
+**One function decides it** (`lib/watchdog-tier.js`), and the settings page, the
+diagnostics and the watchdog itself all ask that one function — so the warning
+("this machine has no automatic rollback") can never drift away from what the
+plugin actually does.
+
+The flow is the same for every tier (`lib/watchdog.js`): wait for the new host
+to write the ready marker → ask again (a slow host is not a dead host) → is an
+instance alive? (then there is nothing to restore) → take the shared lock
+(`rollback.lock`, so exactly one of us restores) → restore the snapshot → start
+the host again → wait for the ready marker once more. At most **one** restore
+and **one** start; then the watchdog stops and writes what happened into
+`<stateDir>/last-watchdog-report.json` (which tier it used, and why).
+
+**Only one watchdog at a time.** There is an older watcher in this plugin as
+well (it restores the snapshot but does **not** start the host again). Both take
+the same lock, so running them together is worse than running one: the one that
+loses the lock gives up — and if the new one lost, the profile would be restored
+and **nothing would be running**. So the plugin decides once, in one place
+(`lib/watchdog-arbiter.js`): the new watchdog takes over whenever it can be
+armed at all, and the old one only runs when the new one cannot (no tier on this
+machine, the watchdog is switched off, or the registration failed). The report
+names the arbiter (`arbiter: "v2"` or `"v1"`), so it is visible at a glance who
+was watching.
+
+`watchdogEnabled: false` switches it off entirely.
+
+### The access link after a restart
+
+The boot token of `dsh web` is created **per process**, so the link the browser holds answers `401`
+after a restart — the user would be locked out of their own interface. The plugin therefore writes
+the access link of the running instance into `<storage>/dsh-autorestart/access.json` (mode `0600`:
+the file holds a secret), and reports it in `continuum_status` and in the log. The browser half
+follows that link when the one it holds is stale, so the session comes back on its own.
+
+### Start at login: the supervisor of this plugin
+
+A hosted host (`dsh web`) that was started by hand does not come back when it dies — and a restart
+that nobody brings back is a restart the user has to do themselves. The plugin can install a
+**supervisor**: a small standalone process that starts the host, watches it, and starts it again when
+it is gone.
+
+- **It is a separate process.** The plugin lives inside the host, so it can never be the thing that
+  brings the host back. The supervisor is a zero-dependency Node script (`supervisor/supervisor.js`,
+  shipped with the package) that the plugin copies into `<storage>/dsh-autorestart/supervisor/` when
+  it is installed.
+- **What it does:** start the host with the command from `supervisor.json`, wait for it to exit, back
+  off (1 s → 30 s; the delay is only reset after a start that actually worked) and start it again.
+  When the host does not come back at all, the snapshot of the last restart is restored.
+- **How it is registered (no administrator rights):**
+  - **Windows:** a scheduled task `dsh-autorestart-web` (`/SC ONLOGON /RL LIMITED`). If the machine
+    forbids ordinary users from creating scheduled tasks, the plugin falls back to a `.cmd` in the
+    startup folder (same zero rights, same "at login" semantics).
+  - **Linux / WSL:** a systemd **user** unit
+    (`~/.config/systemd/user/dsh-autorestart-web.service`). A machine without a service manager (a
+    container, a WSL without systemd) has no "at login" at all — there the plugin says so and leaves
+    the start command to the user.
+- **The guide of every platform.** "Start at login" means something different everywhere, so the
+  plugin hands out one piece of advice per platform (the settings page shows it, with the commands
+  you can copy):
+
+  | platform | what the plugin does |
+  |---|---|
+  | **Windows** | a scheduled task (`/SC ONLOGON /RL LIMITED`, no administrator); when the machine refuses it, a `.cmd` in the startup folder. The command names a **real node** + `supervisor.js` — never the application executable. |
+  | **Linux** | a systemd **user** service — plus the `loginctl enable-linger <user>` hint, because without the linger it only starts *after* a login, not at boot. |
+  | **WSL with systemd** | the same user unit, plus the linger hint. |
+  | **WSL without systemd** | no "at login" at all: two ways out — ① turn systemd on inside WSL (`/etc/wsl.conf` → `[boot] systemd=true` + `wsl --shutdown`; **a system configuration change**) or ② let Windows start the distribution (`wsl.exe -d <distro> -e <command>`; **needs a Windows-side action, but it is much closer to a real boot autostart**). Inside WSL the plugin **never** recommends a container-orchestration setup — the orchestrator of WSL is Windows. |
+  | **container / k8s** | no promise at all: the orchestrator brings it back (`restart: always`). |
+  | **unknown** | nothing is installed and nothing is guessed: the plugin says why and asks the user to choose. |
+
+  A host that is only **guessed** to be WSL (the mounted Windows drive is the only evidence) gets no
+  automatic anything: the plugin says "not sure, pick one yourself" and changes nothing.
+- **It is idempotent:** installing twice leaves exactly ONE record (the task/unit name is fixed, the
+  task is created with `/F`, and the daemon takes an exclusive lock — two supervisors are impossible).
+- **A failed installation leaves nothing behind:** when a step fails half way, the unit (or the task)
+  that was already written is taken away again and the rollback is reported in the step list — a
+  half-installed supervisor would start a stale one at the next login.
+- **The program is never repeated:** a step carries the program in `file` and the arguments in `args`,
+  so the record runs `systemctl --user enable --now …` and never `systemctl systemctl …` (which every
+  systemd answers with "Unknown command verb systemctl").
+- **It is reversible:** the previous `restartMode` / `restartCommand` are saved before anything
+  changes and put back by the uninstall. The settings page has one button for it ("Settings →
+  Auto-restart & shut down → Start at login"), and the manual way out is printed in the card and in
+  the log. When a step of the uninstall fails, the pending cleanup is written down instead of being
+  dropped silently — but only when something is really left, and it lives next to the supervisor
+  directory (`<stateDir>/UNINSTALL-PENDING.json`), so writing it cannot bring that directory back.
+- **The first-run card:** a hosted host is asked ONCE whether the supervisor may be installed. The
+  card says what it would change, which rights it needs, and how to remove it again. Choosing "keep
+  the way I start it" changes nothing — the plugin only records that a supervisor of your own is
+  already there (so it never installs a second one).
+
+The desktop app is **not** asked: it brings itself back up on its own (`restartMode: app`), so the
+question would be noise there. It is also **refused** the installation itself — a login record that
+starts the supervisor would start the Electron client, and that would open a **second** copy of the
+app at every login. `plan` / `install` answer `ok: false` with `error: "desktop-manages-itself"` and
+an empty step list there, and the settings page shows `mode: "app"` (`restartCapable: true`) instead
+of the scary "restart not available".
+
+The record that starts the supervisor always names a **real Node interpreter**: the process itself
+when it is node, otherwise the runtime that ships with the installation
+(`resources/runtime/primary-runtime/dependencies/node/bin/node.exe`), otherwise the `node` of the
+PATH. The application executable is never used as a stand-in for node, and when no interpreter is
+found the installation is refused with the reason.
+
+### How this host was started (the startup matrix)
+
+A hosted web host can be started in a dozen ways, and the plugin has to behave correctly in every
+one of them. The classification is a **pure function** (`lib/startup-mode.js`): it takes the parent
+chain, the environment markers, the container markers and the platform, and answers
+`{ mode, kind, evidence, selfReplay, canInstallSupervisor, suggestion }`.
+
+| How it was started | `mode` | What the plugin does |
+|---|---|---|
+| a plain terminal (`dsh web`) | `bare` | the supervisor of this plugin MAY be installed; otherwise the derived command (after your confirmation) |
+| `nohup … &` / `setsid` | `bare` | the same — but the restart command is **detached** (`setsid nohup …`), so it does not die with the shell that started it |
+| a supervisor script (`supervise-*.sh`) | `external` | graceful exit only (`selfReplay: refused`) — the script brings the host back |
+| a systemd unit | `external` | graceful exit only (evidence: `INVOCATION_ID` or the parent chain) |
+| pm2 / forever | `external` | graceful exit only |
+| docker / compose / kubernetes | `container` | no "at login" at all: the compose fragment (`restart: always`) is the answer, and no supervisor is installed inside a container |
+| a Windows scheduled task / an NSSM service | `external` | graceful exit only |
+| WSL, started by a Windows process | `unknown` | nothing is written: the parent is invisible in WSL — pick the plain terminal (install your own supervisor) or write your own start command (optional) |
+| `npx` / `pnpm dlx` | `bare` (usable) or `unknown` | usable when the resolved script path is in `argv[1]`; otherwise nothing is guessed |
+| another DSH plugin spawned it | `external` | graceful exit only — never a second host |
+| tmux / screen / an SSH session | `bare` | the command is replayed, but **detached from the session** (a graceful exit would break the session) |
+
+**The two rules that matter more than the table:** only a `bare` host may get a self-replay command
+or the supervisor of this plugin, and an `unknown` host gets `selfReplay: 'unknown'` and nothing
+else — the plugin would rather say "I cannot tell" than start a second host next to the first.
+
+The settings page shows the verdict **with its evidence** ("Started by … — ancestor:1234: systemd"),
+so it is visible WHY the plugin says what it says.
+
+### "Keep the way I start it": the derived restart command (E) and the dry run (B)
+
+When the user keeps their own way of starting the host, the plugin can still write down a command
+that starts it again — but only if it can be derived **without guessing**. A wrong command is worse
+than no command: it looks like a restart and leaves the user with a dead host.
+
+The candidate is built from what the process itself knows: `[process.execPath, ...process.execArgv,
+...process.argv.slice(1)]` plus the working directory. The **priority** decides what happens next:
+
+| Level | Situation | What is written |
+|---|---|---|
+| **E0** | The supervisor of this plugin started this instance | Nothing — the restart is asked of the supervisor over its control channel (the plugin writes the rollback request and lets the supervisor kill and start the host). |
+| **E1** | An **external** supervisor is in charge (systemd, a user script, pm2) | **Not** a self-replay command: `restartCommand` becomes a graceful exit (`kill -TERM <pid>` / `taskkill /PID <pid>`), because the other supervisor starts the host again. A second supervisor would fight over the port. |
+| **E2** | No supervisor and no init (a container) | The command is handed out together with a compose fragment (`restart: always`); no automatic start is promised. |
+| **E3** | No supervisor, an init is available | The derived command — after the user confirmed the dry run. |
+
+The **refusals** (each one has a code, and each one names the way out): the desktop app (it restarts
+itself), a host without a web server, a command line that cannot be read back, an external
+supervisor, a container without an init, and a port that changes on every start (the cookie of the
+browser would die with it — the port has to be fixed).
+
+The **dry run** (B) is the promise: the command, the working directory, the port and the health URL
+are shown **before** anything is written. Only an explicit confirmation writes the command into the
+profile configuration; the values that were in effect before are kept, so the settings page can put
+them back with one click.
+
+- The dry run: `POST /__dsh_autorestart/supervisor` with `{ "action": "dry-run" }` (or the tool
+  `continuum_supervisor` with `action: "dry-run"`) — it writes nothing.
+- The confirmation: `{ "action": "apply", "confirmed": true }` — without `confirmed` the Host
+  answers `400 confirmation-required` and writes nothing.
+- The undo: `{ "action": "revert", "confirmed": true }` — the previous `restartMode` /
+  `restartCommand` are written back.
 
 ### The one-time install question
 
@@ -412,6 +813,35 @@ be cancelled — the card has a button, and the moon button itself becomes a tog
 is armed. If a conversation starts working again during the countdown, the countdown goes back to
 "waiting" and nothing is switched off.
 
+### Which machine gets switched off?
+
+The plugin works out where it runs and switches off **that machine** — and the label in the
+settings says which one, so there is no guessing:
+
+| Where DSH runs | What the shutdown switches off | The label you see |
+|---|---|---|
+| The Windows desktop app | that Windows computer | "Switch off this Windows computer" |
+| `dsh web` on Windows | that Windows computer | "Switch off this Windows computer" |
+| `dsh web` on a Linux host | that Linux host | "Shut down this Linux host" |
+| **`dsh web` inside WSL** | **the whole Windows machine** (not the little WSL box!) | "The DSH inside WSL → switches off the whole Windows" |
+| A container | nothing at all (there is no command) | "This machine has no reliable way to switch off" |
+
+> ⚠️ **A shutdown countdown inside WSL means your whole machine goes down** — not just that
+> web service. WSL is a small Linux environment *inside* Windows; shutting that environment
+> down would only stop the distribution. To switch off the **host**, the plugin goes through
+> the mounted drive: `shutdown.exe` (`/mnt/c/Windows/System32/shutdown.exe /s /f /t 0`), with
+> `powershell.exe -Command "Stop-Computer -Force"` and `cmd.exe /c shutdown.exe /s /f /t 0`
+> as the fallbacks. In other words: **the host goes off.**
+
+**How far this is verified.** The *plan* is verified for every platform
+(`test/sleep-plan-posix.test.mjs`: inside WSL the plan must take the "switch off the whole
+Windows" branch, a plain Linux plan must not contain a single Windows command, and a machine
+without a way to switch off has an empty command and **executes nothing**). The real power-off
+is verified on **Windows**; on POSIX it is deliberately **not** switched off for real — a
+common-sense fact is not worth ending every session on the machine for.
+
+The full picture per platform is in [`docs/platform-matrix.md`](docs/platform-matrix.md).
+
 ### Shutdown and restart: who goes first
 
 **The short version.** Pressing the moon button means "switch the machine off when the work is
@@ -578,6 +1008,24 @@ was only recognised as WSL because the Windows drive is mounted — a hint, not
 `lastRun.dryRun` marks the last run as a rehearsal that switched nothing off; and
 `backupOnRestart` / `backupIncludePlugins` report the effective scope of the pre-restart backup.
 
+**The record of the last restart.** `GET <healthPath>?state=1` and the `continuum_status` tool both
+report `lastRestart`: the snapshot that was taken before the restart (`snapshot.dir`,
+`snapshot.stamp`, `snapshot.atLocal` — the local time, because the directory name is UTC —,
+`snapshot.durationMs`, `snapshot.pruned`) and the verdict of the instance that came up
+(`result` is `pending`, `ok` or `failed`, plus `verifiedAt`, `durationMs` and the four boot checks
+`listener` / `routes` / `plugin` / `recovery`). A restart whose new instance never came up stays
+`pending` — that is visible too. The file behind it is
+`<stateDir>/last-restart-verdict.json`.
+
+**Who starts this host.** The `supervisor` block of the same payload says `mode`
+(`app` / `installed` / `external` / `unknown` / `off`), `restartCapable`, and — since a second supervisor
+would fight over the port — `selfReplay` (`allowed` / `refused` / `unknown` / `n/a`) plus the `external`
+evidence (`kind`, `evidence`, `commandLine`) when somebody else is in charge. On Linux the parent
+chain of the host is read (`/proc/<pid>/cmdline`), so a `supervise-*.sh` script of the user is
+recognised. When nobody can be identified the mode is `unknown`, never a silent "bare host": the
+plugin then refuses to replay its own command. The **desktop app** is never `unknown`: it brings
+itself back up, so it reports `mode: "app"` with `restartCapable: true` and `selfReplay: "n/a"`.
+
 **When the shutdown command does not start.** The host waits for the real answer of the process. If
 the command cannot start (missing binary, denied permission), the shutdown does **not** pretend it
 worked: the phase goes back to `idle`, the reason is reported ("the shutdown command did not start