dsh-autorestart 0.8.5 → 0.8.6

package/README.md

@@ -61,6 +61,42 @@ 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.
 
+## Supported platforms
+
+One question decides everything: **which environment below are you in, and has anybody actually run it there?**
+
+| Your machine | Run on a real machine | What you must know |
+| --- | --- | --- |
+| **Windows desktop** (the DeepSeek Harness client) | **yes — verified** | nothing to configure — `restartMode: app` is the default |
+| **`dsh web` on WSL, with `systemd --user`** | **yes — verified** | you must set `restartMode: command` **and** a `restartCommand` that really restarts this host; remember the shutdown button switches off the **whole Windows machine**, not the distro |
+| **`dsh web` on WSL, without `systemd --user`** | **not yet** | the same configuration as the row above; the automatic rollback falls back to a detached process of the plugin's own |
+| **`dsh web` on Windows** | **not yet** | the same configuration as the row above |
+| **`dsh web` on Linux** (not WSL) | **not yet — there is no such machine here** | the same configuration as the row above |
+
+The last three rows are **implemented and covered by unit tests, but no one has run them on a real host**;
+they take the same code path as the verified WSL row (`restartMode: command` plus your own restart
+command), yet "it should work that way" is not "it was verified there", so it is not claimed. The
+**with/without `systemd --user`** split changes only *how* the automatic rollback is triggered (a systemd
+user timer versus a detached background process of the plugin's own); everything else is the same. The
+settings page always says which one your machine got, and it never promises a rollback it cannot deliver.
+
+### Out of scope — not tested, not supported
+
+These three are **not** in the supported set. The plugin may appear to run there, but nothing is
+promised: no real-machine test exists, and some abilities simply cannot be delivered.
+
+| Environment | Status | What you lose |
+| --- | --- | --- |
+| **macOS** | **not tested / not supported** | no desktop rescue shortcut; the automatic rollback degrades to a background process of the plugin's own (and on a machine without `setsid` it degrades further to *no rollback at all*); the shutdown countdown has never been verified on a real Mac |
+| **Remote SSH with no graphical session** | **not tested / not supported** | no desktop and no desktop rescue entry, so the only way back in is a `.sh` script — which means you must already be able to SSH in; the "start at login" advice starts the **host**, not your SSH session; the session resume only happens once *somebody* starts the host again |
+| **Containers** (Docker / Compose / Kubernetes) | **not tested / not supported** | no "start at login" at all (the orchestrator owns that); the automatic rollback degrades to a background process of the plugin's own (often no `setsid` in a slim image → *no rollback*); the shutdown countdown is **not** container-aware — it really tries to power off the host, so do not press it in a container; a rebuilt container may take the checkpoint and the backups with it |
+
+If you are on one of those three, install it as an experiment at your own risk, and use
+`scripts/restore-profile.sh` / `scripts/emergency-disable.sh` as your way out.
+
+The complete per-capability matrix — every ability × every environment, each cell with the
+`file:line` it rests on — is in [docs/platform-matrix.md](docs/platform-matrix.md).
+
 ## The whole thing in one page (ordinary users can stop here)
 
 ### Why a restart does not lose your work
@@ -74,8 +110,11 @@ The plugin turns a restart into a **resumable** event, and the order never chang
    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.
+5. **If it did not come up, it rolls back** — a snapshot (configuration + installed plugins) whose
+   identity is `known-good` (it was taken before a restart that then came up) is put back, and the
+   verdict of that restart is written down honestly.
+   **When there is not a single copy with that identity**, it does not put "the newest one" in its
+   place: it reports plainly that there is no restore point carrying an identity.
 
 So "the restart lost my work" becomes "the restart carried on": you do not have to type "continue".
 
@@ -112,13 +151,17 @@ writes that sentence and the matching command into the settings page.
 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`:
+**And use the scripts of YOUR host** — a Linux machine has no `.cmd` file, and a Windows machine has
+no `.sh`. Pick by the host you are sitting in front of, not by a platform list:
 
-| Your machine | back to the last good state | take this plugin out |
+| Your host | 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` |
+| **WSL / Linux** (`dsh web`) | `sh scripts/restore-profile.sh` | `sh scripts/emergency-disable.sh` |
+| **macOS** | `sh scripts/restore-profile.sh` | `sh scripts/emergency-disable.sh` |
+
+On macOS the same two POSIX `sh` scripts apply; they have never been run on a real Mac, so they are
+untested and nothing is promised.
 
 Two scripts per platform, and they do different jobs:
 
@@ -138,6 +181,15 @@ in [`scripts/README.md`](scripts/README.md).
 [`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.
 
+**The desktop rescue shortcut (Windows only).** The settings page can put a rescue shortcut on the
+desktop; double-clicking it runs `restore-profile.cmd`. **Its icon is the plugin's own
+`assets/icon.ico` — not DSH's executable.** That is deliberate: on a desktop where DSH will not
+start, a shortcut wearing DSH's face reads as "this is the program", which is exactly the thing
+that is broken. When an install ships no icon file, the `.lnk` is still created — it simply gets no
+`IconLocation` instead of borrowing some other program's face, and nothing is generated at runtime.
+Every other platform gets no desktop shortcut at all; the settings page gives a copyable
+restore-script command instead.
+
 ### What has really been tested
 
 | How it was started | Tested on a real machine? | Evidence |
@@ -149,16 +201,19 @@ scripts that really exist on the machine you are on.
 | 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 |
+| container / compose | **no — out of scope** | see [Supported platforms](#supported-platforms): containers are **not** a supported environment |
 | `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 |
+| tmux / screen / an SSH session | **no — out of scope** | see [Supported platforms](#supported-platforms): a remote SSH session without a GUI is **not** a supported environment |
 | 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.
+**"Unit tests only" means "not verified on a real machine", not "unsupported"** — on the four
+supported platforms those paths are pinned by unit tests, and "no full install/uninstall cycle" does
+not mean unsupported either. The three environments listed under
+[Supported platforms](#supported-platforms) (macOS, a remote SSH session without a GUI, containers)
+are a different case: they are **outside** the supported set, and the table above says so.
+If your environment is recognised wrongly, please send us the "startup mode + the evidence" block
+from the settings page.
 
 ### Report a problem
 
@@ -199,9 +254,22 @@ what it adds before you install it.
 | An agent owns a durable goal (`create_goal`) that should survive a restart | The goal activation lives in the process, so after the restart it is `disarmed` and the automatic continuation stops | The plugin re-arms the goal at boot and the goal round driver starts the next round right away |
 | An agent wants to install or upgrade a plugin, but a restart would cut the work short | You either wait or take the risk | Call `continuum_restart`: it waits until every agent is idle and the session continues by itself afterwards |
 
+## Host version requirement
+
+**Requires DSH ≥ `0.1.6-alpha.2`.**
+
+Since `0.1.6-alpha.2` the host handles "a plugin did not come up" in two different ways:
+
+- **Ordinary plugins** (your own, or installed from npm) that fail to load **do not block startup**: the host boots anyway, logs `warning: N entry did not activate`, and leaves the other plugins running. That log line is exactly what this plugin reads to show "these features did not come up this time".
+- **Required plugins** (the host's own parts, e.g. the web server) that fail **still fail the startup**: the log says `startup failed: N required plugins did not activate`. That is the case the watchdog handles — restore a verified backup, then bring the host back up.
+
+On `0.1.6-alpha.1` and older there is no such distinction: any failing plugin throws and the host does not come up at all, so the signal this plugin depends on does not exist there.
+
+**How this was established (stated plainly)**: by reading DSH's official `@deepseek-ai/dsh-app-boot` package release by release (`0.1.0-rc.2` / `0.1.3-alpha.2` / `0.1.5-rc.3` / `0.1.6-alpha.1` / `0.1.6-alpha.2` / `0.1.7-rc.2` / `0.2.0-rc.1` / `0.2.1-rc.3` / `0.2.2-alpha.2`); the boundary falls at `0.1.6-alpha.2`. The official DSH release notes do **not** state this: the `0.1.6-alpha.2` entry only says "Group startup errors and pending services, and save full diagnostics to a log file". So this is a source-level finding plus a local measurement, not an official declaration.
+
 ## Install
 
-Current version: **0.8.5**.
+Current version: **0.8.6**.
 
 From npm — the package is published under the name `dsh-autorestart`:
 
@@ -297,32 +365,45 @@ Two blocks of the settings page are worth a word, because they show facts instea
 
 - **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, 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."
-  Every copy leads with **what it is** — its identity — so the list answers the only question that
-  matters ("may this one be restored?"), then two labelled rows, so nothing runs into anything else:
+  one, how much disk they take together and where the folder 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."
+  Every row is one copy and carries two things: its backup **time**, and the one action that applies
+  to it ("Roll back to this copy"). A row carries **no size** — the total sits once, above the list,
+  as "Using 156 MB on disk, 2 copies right now". The list does **not** say which copy is the safe
+  one — the plugin no longer makes that call (user decision, 2026-11-02): a row is a time and a
+  button, and the judgement is the reader's:
 
   ```
-  Identity  Known good · version 0.8.5
-  Backup time 2026-10-29 22:08
-  Backup size 156 MB (plugins included)
+  Using 156 MB on disk, 2 copies right now
+
+  Backup time 2026-10-29 22:08   [Roll back to this copy]
+  Backup time 2026-10-29 21:44   [Roll back to this copy]
   ```
 
-  The identity is one of **known good** (a copy a boot has already proven — the only kind an automatic
-  rollback may restore), **this restart's snapshot** (taken right before a restart and not proven yet)
-  or **old backup (unverified)** (written before the identity layer existed, or without an identity
-  file — shown, never rolled back automatically). A short paragraph above the list says the same in
-  plain words, plus the rules behind it (only a known-good copy is rolled back, the first install
-  seeds one, at most three copies are kept, a manual rollback asks for confirmation and then
-  restarts). The identity and the version it was proven with come from the Host
-  (`backups.items[].kind` / `backups.items[].version`) — the browser cannot read `meta.json`.
+  One row can carry one more neutral sentence, and it is not a verdict: the copy the host last
+  started from says "This is the state at the most recent startup. DSH starting does not mean every
+  plugin is healthy — a broken plugin is excluded and the host still boots. Which copy to roll back
+  to is your call." It is attached by the copy's own record, never by its position in the list.
+
+  The identity still exists, but **it is not on disk**. `meta.json` next to each copy records FACTS
+  only — when the copy was taken (`takenAt` / `at`), what put it there (`trigger`: `first-install` /
+  `pre-restart` / `manual-rollback`), `version`, the content fingerprint, and what the boot that
+  followed reported (`boot`: did the host come up, was it running this content, which plugin load
+  failures it listed). The three names are **derived from those facts when the copy is read** —
+  `known-good` (a boot is on record after it, or it is the first-install copy), `snapshot` (no boot
+  after it yet) or `unknown` (no readable `meta.json`, or no usable boot record on an old copy). Being
+  restorable is a **second, narrower check** on top of that name: an automatic rollback only restores
+  a copy whose recorded boot both started and ran this exact content. The value records what happened
+  after the copy was taken; it is not an evaluation of whether the plugins
+  inside it work. The browser cannot read `meta.json`, and no identity is printed on a row.
 
   The time is the local clock of the machine that took the copy, **to the minute and with no
-  timezone offset** (a `+08:00` only adds noise — the reader is looking at their own clock). The
-  size picks its own unit (`92 KB` / `156 MB`), keeps the tenth only when it says something
-  (`117.7 MB`, never `156.0 MB`), and the plugin scope sits in brackets right after it, because it
-  is the reason the copy is that big. Two copies are two groups with air between them.
+  timezone offset** (a `+08:00` only adds noise — the reader is looking at their own clock). The size
+  of the whole folder picks its own unit (`92 KB` / `156 MB`) and keeps the tenth only when it says
+  something (`117.7 MB`, never `156.0 MB`); it is printed once in the summary line above the rows,
+  never on a row, and it carries no "(plugins included)" bracket. Two copies are two groups with air
+  between them.
 - **A setting that was saved says so.** Every control writes itself the moment it is changed, so the
   panel has to say whether the write landed: once the HOST answers `ok: true`, a green strip at the
   **top of the settings panel itself** (inside the panel — a `sticky` row, so it stays visible while
@@ -352,9 +433,9 @@ show up in the Plugin Manager and in the config editor.
 | `maxSessions` | `4` | Maximum number of sessions resumed per boot. |
 | `maxResumeAttempts` | `2` | Maximum resume attempts per session, counted across boots, so a bad session cannot loop forever. |
 | `deferPollMs` | `3000` | Poll interval while waiting for the conversations to go idle. |
-| `deferSoftMs` | `300000` | Soft deadline: warn when the conversations are still busy after this long. |
-| `deferHardMs` | `900000` | Hard deadline: warn after this long. The restart is only forced when `forceRestartWhenBusy` is enabled. |
-| `deferPolicy` | `auto` | `auto` = after the hard deadline, follow `forceRestartWhenBusy` (by default keep waiting). `wait` = wait forever. |
+| `deferSoftMs` | `300000` | **Deprecated — read but completely ignored.** A pending restart has no deadline. Kept only so existing configuration files stay valid. |
+| `deferHardMs` | `900000` | **Deprecated — read but completely ignored.** A pending restart never gives up. Kept only so existing configuration files stay valid. |
+| `deferPolicy` | `auto` | Kept for configuration compatibility. Waiting is the same under every value: a pending restart waits for the idle gate, with no deadline. |
 | `forceRestartWhenBusy` | `false` | Whether a restart may be forced while a conversation is still running. The default `false` never interrupts a session: the plugin waits until the other conversations finish. |
 | `restartMode` | `app` | `app` = restart the DeepSeek Harness desktop app. `command` = run `restartCommand`. |
 | `restartCommand` | `''` | Custom restart command. Supports the `{pid}`, `{ppid}` and `{app}` placeholders. |
@@ -369,7 +450,7 @@ show up in the Plugin Manager and in the config editor.
 | `continuationText` | `''` | Overrides the default continuation prompt text. |
 | `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` | `3` | How many snapshots are kept (the current one plus the two before it); older ones are deleted when a new one is written — **except the newest known-good copy, which is never deleted**. |
+| `maxBackups` | `3` | How many snapshots are kept (the current one plus the two before it); older ones are deleted when a new one is written — **except the newest copy whose identity is `known-good`, which is never deleted**. |
 | `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. |
@@ -424,7 +505,7 @@ delayed work of the other plugins — and it is the **only** such window:
 for the restart gate. That is right while the message is about to be picked up — the agent claims
 it within a second or two — but it is a deadlock when nobody ever claims it. The real case was a
 fresh, empty conversation in the UI with one unclaimed message in its inbox: the gate stayed
-closed, the hard deadline only logged a warning, and the restart never happened.
+closed and the restart never happened.
 
 **The upper bound.** `queuedGraceMs` (default **60000** ms) is how long an unclaimed message may
 hold the restart back:
@@ -484,10 +565,13 @@ Both `…/health` and `…/health?state=1` carry `restartPhase` (stage, bilingua
 line next to the restart settings — the pill is only there while a restart is pending, the settings
 line is always there.
 
-### What you see while the restart waits a long time
+### What you see while the restart waits
 
-When the hard deadline (`deferHardMs`) is over and a conversation is still running, the plugin does
-not pretend that everything is fine — and it does not give up either:
+A restart waits for one thing only: **every conversation finishing its work**. There is no deadline
+and nothing expires — it keeps waiting for as long as that takes, and only two things end it: the
+gate opens (the restart runs) or you withdraw the request.
+
+The wait is visible from the first second, not after some threshold:
 
 - **The request is kept.** The pending restart stays pending, the requester stays checkpointed, and
   the restart fires as soon as the gate is quiet again. Nothing is cancelled behind your back.
@@ -498,7 +582,8 @@ not pretend that everything is fine — and it does not give up either:
   `<session>` keeps holding it" (「已等 17 分：`<会话>`一直占着」).
 
 A conversation is never killed to make the restart happen: `forceRestartWhenBusy` stays off by
-default, and this plugin never turns it on.
+default, and this plugin never turns it on. When it IS turned on, it restarts over a running
+conversation — it interrupts it. That is a choice about interrupting work, not a deadline.
 
 ### What the quiet window measures
 
@@ -563,20 +648,39 @@ it was started from, so a restart that leaves the host unable to boot can be und
   `backupIncludePlugins` is turned off — the installed plugin tree (`node_modules`). Snapshots live in
   `<storage>/dsh-autorestart/backups/<timestamp>/` with a `manifest.json` next to them. On a profile
   like this one the full snapshot measures about 117 MB and takes under three seconds.
-- **The rollback target is the newest PROVEN copy, not the newest copy** (user decision,
-  2026-10-30). Every copy carries its identity in a `meta.json`: `known-good` (a copy a boot has
-  already survived), `snapshot` (taken right before a restart, not proven yet) or `unknown` (written
-  before the identity layer). The snapshot taken right before THIS restart is never the rollback
-  target — it may be the broken state itself (that is exactly the "I edited a plugin and clicked
-  restart" case). The first install seeds one known-good copy, and every boot that passes its health
-  check promotes the snapshot of that restart to known-good.
-- **No known-good copy, no restore at all.** When nothing has been proven yet, the plugin restores
-  nothing and says why: the report carries `no-known-good: <reason>`, the profile is left exactly as
-  the failed restart left it, and no watcher is armed (a watcher with nothing to restore would only
-  write the broken state back).
+- **PLUGINS INSTALLED WITH `link:` ARE BACKED UP TOO** (2026-10-30, measured gap). Five plugins on
+  this machine were installed as links/junctions (`dsh-autorestart` itself among them), and the tree
+  copy recorded the LINK and not one byte behind it — so the plugin that does the rescuing could not
+  be put back. The manifest now carries `links: [{name, target, kind, exists, readable, copied, files,
+  bytes}]` (+ `linkFiles` / `linkBytes`) and the CONTENTS of every enabled linked plugin are kept in
+  `node_modules-link/<name>/` (1 216 files / 69.5 MB for these five). On restore each link gets one
+  decision, printed as its own line — `kept` (target still there: the development directory keeps
+  working), `replaced` (the copy takes its place), `target-missing`, `no-backup`. The restore script
+  has `-ForceLinkPlugins` for "replace them all"; the watchdog uses the same rules
+  (`decideLinkRestore`) and does not give a link a second chance (`attempts >= 2` ⇒ replaced).
+- **The rollback target is the copy taken before an earlier restart that came up, not the newest
+  copy** (user decision, 2026-10-30). Every copy carries a `meta.json`, and **it records facts
+  only**: when it was taken, what put it there (`trigger`), `version`, the content fingerprint, and
+  what the boot that followed reported (did the host come up, was it this content, which plugin load
+  failures). The three identity names — `known-good`, `snapshot`, `unknown` — are **derived from
+  those facts when the copy is read, never written to disk**: a copy with a boot on record after it
+  (or the first-install copy) is `known-good`; a copy with no boot after it yet is `snapshot`; a copy
+  with no readable `meta.json`, or an old one with no usable boot record, is `unknown`. That name is
+  not the same question as "can it be restored": the automatic rollback additionally requires the
+  recorded boot to have started and to have run this exact content. The identity records what
+  happened after the copy was taken; it is not an
+  evaluation of whether the plugins inside it work. The snapshot taken right before THIS restart is
+  never the rollback target — it may be the broken state itself (that is exactly the "I edited a
+  plugin and clicked restart" case). The first install seeds one copy with `trigger: first-install`,
+  and every boot whose checks pass on this exact content records a `boot` on that restart's snapshot.
+- **No `known-good` copy, no restore at all.** When no copy has a boot recorded after it yet, the
+  plugin restores nothing and says why: the report carries `no-known-good: <reason>`, the profile is
+  left exactly as the failed restart left it, and no watcher is armed (a watcher with nothing to
+  restore would only write the broken state back).
 - **How many are kept:** the newest `maxBackups` snapshots (default `3`: the current one plus the two
-  before it); older ones are deleted when a new one is written. The newest **known-good** copy is
-  never deleted, whatever the limit says — it is the only thing a failed boot can roll back to.
+  before it); older ones are deleted when a new one is written. The newest copy whose identity is
+  `known-good` is never deleted, whatever the limit says — it is the only kind an automatic rollback
+  restores.
 - **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
@@ -593,8 +697,8 @@ it was started from, so a restart that leaves the host unable to boot can be und
   The watcher is therefore started **before** the command runs, and it is the one that decides
   whether the new instance came up.
 - **A manual rollback to ANY copy** (user decision, 2026-10-30): the settings page offers
-  "roll back to this copy" on every row, so a copy from last week — even an unverified one — can be
-  restored on purpose. It asks first (which copy, that the current state is replaced, that a restart
+  "roll back to this copy" on every row, so a copy from last week — even one with no boot recorded
+  after it — can be restored on purpose. It asks first (which copy, that the current state is replaced, that a restart
   follows); the Host saves the current state as a fresh snapshot BEFORE it restores anything, writes
   `last-manual-rollback.json`, and only then requests a normal restart (the plugin never kills the
   host itself). The route (`POST /__dsh_autorestart/rollback-to`) takes a backup NAME only — a path
@@ -669,10 +773,166 @@ instance alive? (then there is nothing to restore) → **ask the health route of
 the host itself** (only a host that does not answer may be rolled back; when
 there is no port to ask, one more round is waited and the markers are looked at
 again) → 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, `healthCheck`, and why).
+and then, **in this order**: restore the snapshot → **remove the stale
+`dsh-auth-*` handshake cookies** → start the host again → wait for the ready
+marker.
+
+Each pass tries up to **`maxAttempts`** times (3 by default, with a hard ceiling
+— never endless): a pass that did not come up backs off (5s / 10s / 20s, capped)
+and the three questions above are asked AGAIN before the next start, because the
+world changed in between (a slow boot is `not-needed`, an instance that came up
+is `abandoned`). The snapshot is restored on the **first** try only (copying the
+same tree twice changes nothing), **but the cookies are cleared before every
+single start**: starting the host with 71 stale cookies is starting it to die
+again (the Cookie header overflows 16 KB and the host answers 431).
+
+**A failure always leaves a report.** Whatever the outcome — recovered,
+not-needed, abandoned, decided, failed, or out of attempts — every pass writes
+`<stateDir>/last-watchdog-report.json`: which tier it used, `healthCheck`, how
+many attempts, and per attempt `restored` / `cookieClear` / `relaunched` /
+`ready` / the backoff, plus why it stopped. A report that never reaches the disk
+is a report that never happened; that was one of the three defects 0.8.6 fixes.
+
+### What the watchdog does NOT cover
+
+Be clear about the window, because the whole thing is a **window**:
+
+- the watchdog is armed **only while this plugin is restarting the host** — it is
+  a one-off item scheduled just before the kill, and the host disarms it at boot
+  (`watchdog-pending.json` gone, ready marker written, the scheduling item
+  deleted);
+- **outside that window nobody is watching.** A host that is killed by the system
+  at 03:00, a client that is start-and-die on a manual double-click, or a machine
+  that is found with 0 processes in the morning has **no watchdog to bring it
+  back**: the plugin is not running (it died with the host) and no one-off item
+  was ever registered. What is left in that case is `scripts/restore-profile.cmd`
+  (double-click it) and, when the profile itself was emptied, nothing at all;
+- the watchdog restores **one snapshot** and starts the host — it repairs no bug
+  of the host. A host that dies for the same reason every time ends as `failed`
+  with a report that names the attempts;
+- `watchdogEnabled: false` (and a machine whose tier is `none`) means no
+  automatic rollback at all, and the settings page says so.
+
+### A plugin that did not load: the REPORTED kind of failure
+
+Not every plugin failure keeps the host from booting. The other one is quieter: the
+host comes up, one entry **never activates**, and the feature behind it simply 404s.
+The startup log says so (`<plugin>: failed to import: <error>`, `<plugin>: import
+failed …`, `- <plugin>: loading`, or the aggregate `dsh: warning: N entry did not
+activate`) and, without this pass, nobody reads it.
+
+The two failures are handled by two different mechanisms, and they never overlap:
+
+| failure | who handles it |
+|---|---|
+| **process level** — the host does not come up at all | the pre-restart snapshot + the watchdog: one snapshot is restored and the host is started again |
+| **reported** — the host is up, one plugin silently did not activate | **a report and a popup, nothing else** — the user decides, and one button puts ONE plugin back |
+
+**THE BOOT PASS DOES NOT FIX ANYTHING** (user decision, 2026-11-01). It used to
+put the backup whose identity is `known-good` back and ask for one restart;
+measurement showed that was redundant work on top of what the host already does:
+
+- the host **already survives** a broken plugin — measured at **22 s** on the
+  desktop (normal boot, the broken plugin's route 404s, the configuration is not
+  touched) and at **2.0–2.6 s** on a hosted `dsh web` instance (the profile's
+  `package.json` was byte-identical across five samples, and `supervise-web.sh`
+  started the host **once** in 62.9 s);
+- so an automatic restore only added a second writer into the profile at boot,
+  and an automatic restart on top of it.
+
+What the boot pass does now: **read the previous boot's log, recognise the
+failed plugins, write `<stateDir>/last-plugin-recovery.json`.** It never calls
+the restore, it never asks for a restart — both facts are pinned by tests (every
+file in the profile keeps its sha256, no `<plugin>.broken-<ts>` evidence is
+created, `state.restart` stays empty).
+
+**The popup is the half that was missing.** A card in the composer dock says
+which plugin did not load and what error it reported, and offers exactly one
+action: *"Restore `<plugin>` only"*.
+
+**`POST /__dsh_autorestart/plugin-restore`** with `{ "plugin": "<name>" }` is
+the ONLY remaining writer into the profile, and it only runs because a human
+pressed the button:
+
+- **`overwrite`** — the newest backup whose identity is `known-good` holds a real copy: the live
+  directory is renamed to `<name>.broken-<ts>` (**evidence — nothing is ever
+  deleted**) and the backup copy takes its place;
+- **`replace-link`** — the backup only holds the CONTENTS of a `link:` install
+  (`node_modules-link/<name>`): the live link is moved aside the same way and the
+  copied contents take its place;
+- **`already-consistent`** — the live plugin already equals the backup: no file
+  is written and no restart is asked for (pressing twice is harmless);
+- **`no-backup` / a copy that fails** — `ok:false` with a `reason` **and HTTP
+  200**: "there is no backup for this plugin" is an answer, not a server error.
+
+A restore touches **that one plugin**: every other plugin, and the profile's
+`package.json` / `cordis.patch.yml`, are byte-identical afterwards (asserted
+file by file). Each attempt is appended to
+`<stateDir>/plugin-restore-history.json` (newest 20) and the newest one is
+carried by the health route as `pluginRestore`, so the card can say "already put
+back — restart to load it".
+
+The loop guards of the old automatic pass (`duplicate` / `needs-human`) are
+**not** applied to a button press: "should the machine act on its own" is a
+different question from "a person asked again", and the idempotency check still
+protects the disk.
+
+Two loops are possible, and both are stopped:
+
+1. **the same old log line read again.** Every boot would "find" the line the
+   previous boot left behind. The pass only reads the log of the **previous** boot,
+   drops lines older than that boot, and gives every failure a **fingerprint**
+   (plugin + first error line + log time) that is recorded as handled once — the
+   second time it is a `duplicate` and nothing happens;
+2. **the cause is not in the plugin** (a missing peer dependency, a missing host
+   capability). Swapping the copy back cannot fix that, so one plugin is restored
+   once per cycle: a second failure reports `needs-human`, touches nothing and asks
+   for no restart. One boot without any plugin failure resets the cycle.
+
+It is also **idempotent**: before copying, the live directory is compared with the
+backup copy (relative path + size + sha256). When they already match, nothing is
+copied and no restart is asked for (`already-consistent`).
+
+**A restart is requested only when files really changed.** `no-backup`,
+`duplicate`, `already-consistent` and `needs-human` all leave `restartRequested:
+false` — a restart that cannot change the outcome only costs another boot. The
+restart goes through the **existing** entry (`requestRestart`, the same gate,
+snapshot and resume path); there is no second restart mechanism.
+
+Everything is written to `<stateDir>/last-plugin-recovery.json`:
+
+```json
+{
+  "at": 1761000900000,
+  "atIso": "2026-11-01T01:00:05.000Z",
+  "log": "…/logs/startup-…log",
+  "backupDir": "…/backups/20261101T000000Z",
+  "backupKind": "known-good",
+  "restoredAt": 1761000000000,
+  "failures": [{ "plugin": "broken-plugin", "error": "Error: Cannot find module 'x'" }],
+  "actions": [{
+    "plugin": "broken-plugin",
+    "mode": "overwrite",
+    "restoredFrom": "…/backups/…/node_modules/broken-plugin",
+    "restoredAt": 1761000000000,
+    "backupKind": "known-good",
+    "evidence": { "renamedTo": "…/node_modules/broken-plugin.broken-20261101T010005" }
+  }],
+  "restartRequested": true,
+  "needsHuman": false
+}
+```
+
+`restoredAt` and `backupKind` come from the **backup's own `meta.json`**, so the
+answer to "restored to which point in time" is that copy's own record and not
+the moment the clock was read. The file holds facts (when the copy was taken, what
+triggered it, `version`, the content fingerprint, what the boot after it reported);
+`backupKind` is the identity the Host **derives** from those facts — the file does
+not carry a `kind` field any more. The same object is exposed as `pluginRecovery` on
+the health route and by `continuum_status` (`null` / omitted when this machine
+never had such an incident). The reading of the report is not part of this
+change: the interface part is a separate task.
+
 
 **The disarming is the host's job, and it does it at boot.** As soon as this
 plugin is loaded, it writes the ready marker, removes `watchdog-pending.json` and
@@ -914,6 +1174,135 @@ once, in the same composer dock, as a small card:
   and records it on `POST /announcements` (`{ feature }`). The `version` in that answer is the feature
   version — the same number that `SLEEP_FEATURE_VERSION` holds.
 
+## 0.8.6: what is backed up, the three signals, and the edge of the watchdog
+
+> This chapter covers the 0.8.6 release notes. The Chinese original of the same chapter is in
+> [docs/README.zh.md](docs/README.zh.md). It only answers the four questions an ordinary user asks:
+> **what is backed up, how many signal layers there are, what the watchdog can save, and what to do in
+> which order when something is off.** Implementation details live in the sections above.
+
+### 1. What is backed up, and what is not
+
+| | In the backup | Why |
+|---|---|---|
+| **Backed up** | the profile configuration (`cordis.patch.yml`, `package.json`, `pnpm-lock.yaml`) **plus the plugins you wrote yourself and installed as a link (`link:`)** — their contents are kept separately in `node_modules-link/<name>/` — **never their `.git`** (history is rebuildable from its remote, and it was the bulk of every copy: one linked plugin, 962 files / ~74 MB). A sweep also removes directories holding neither a manifest nor a configuration file, at most 32 dirs / 2 GB per pass, and reports every removal. An incomplete copy never carries a backup's name at all: it is written as `.staging-<stamp>` and renamed only once its manifest and configuration are on disk, so an interruption leaves a staging directory instead of something that looks restorable. **The boot sweep does not remove those `.staging-*` leftovers** (it skips every dot-named directory on purpose, so it never deletes a copy that is being written right now) — they are simply never listed and never restored from, and removing them by hand is safe | the plugins you write have **no definite source and no definite version**: delete one and nothing can fetch it again, so a backup is the only way |
+| **Not backed up** | **third-party plugins** (installed from npm) | they **do have a definite source and version**: `pnpm-lock.yaml` pins every package's version and integrity hash, so reinstalling brings back **the version from the backup, not the latest one** — a backup would be redundant, and reinstalling is more reliable than a copy |
+
+- Measured (from 2026-11-01 the slim backup is the default): one backup went from 308 MB to about 100 MB.
+- `backupIncludePlugins: false` → configuration only (about 66 KB, finished instantly). With that setting
+  **a plugin problem cannot be rolled back, it has to be reinstalled by hand**, and the settings page says so.
+- The old full-copy behaviour is still there: `slimBackup: false`.
+
+### 2. The three signal layers: two are certain, one is only a clue
+
+On every boot the plugin compares three layers against the list the previous boot recorded
+(`plugin-watch.json`):
+
+- **tool names** (`tools`) — plugins that provide tools (codekg, vault, release-board and the like);
+- **interface modules** (`clientModules`) — plugins that draw something in the interface;
+- **registered packages** (`packages`) — packages that register a schema.
+
+| Signal | Strength | What it proves | What it does not prove |
+|---|---|---|---|
+| **a tool name disappeared** | **certain** | these features really did not come up this time | which plugin caused it |
+| **a registered package disappeared** | **certain** | this package did not load this time | whether the files are wrong or the configuration disabled it |
+| **a plugin's files differ from the backup** | **clue** | this plugin may have been changed (it may also be your own edit, or an upgrade) | **not the same as broken** — a plugin whose files are all correct and that fails while loading is invisible to this layer |
+
+Three more limits belong right here:
+
+- **interface modules that map to no installed plugin** are counted and reported separately
+  ("also N interface module(s) did not appear this time"); they are **never attributed to a plugin** —
+  when the owner cannot be identified, no owner is guessed.
+- **a layer that cannot be read means "no news", never "gone"**: when a host upgrade changes the shape of
+  some API, the only possible answer is "this layer could not be seen this time", never "your plugin is gone".
+- **the file comparison uses the set of relative paths plus each file's size**, it never hashes a whole tree
+  (a real profile is about 150 MB). So it does find "a file was changed / deleted / is absent from the backup",
+  and it **does not find** a plugin whose files are all correct but which fails while loading (a missing peer
+  dependency, a throwing initialiser, a version the host refuses).
+
+### 3. "Inconsistent" is not the same as "broken" — the hard wording rule
+
+The popup and the settings page may only say two things:
+
+- "**these features did not come up this time**" (a certain fact — it already happened, it is not a guess);
+- "**these plugins differ from the backup**" (a difference list, with no conclusion drawn from it).
+
+**Never write "the plugin is broken"**: differing from the backup may simply mean you edited it, or upgraded
+it. The status word of a row in the settings page is only
+`fine` / `differs from the backup` / `not in the backup` / `not installed` / `cannot tell (no backup to compare
+against)` — there is no "broken" state.
+
+### 4. The watchdog: what it does
+
+- **Configurable**: `watchdogEnabled`, **on by default**; with it off, a new version that does not start has
+  to be handled by hand.
+- **It only stands watch inside one window**: a restart that **this plugin** started. After the host is
+  replaced it waits for the new instance and asks **that instance's own** health route (never the old
+  instance, never the old port), then works in a fixed order: **restore the newest backup whose
+  identity is `known-good` → clear the stale `dsh-auth-*` handshake cookies → start the host again →
+  wait for the ready marker**.
+- **Three possible triggers, one chosen from what this machine can do and reported honestly**: a Windows
+  scheduled task / a systemd user timer / a background process of its own; **with none of the three this
+  machine has no automatic rollback** and the settings page says exactly that.
+- **Bounded retries**: 3 by default (hard ceiling 10), with a backoff between passes, and the three questions
+  (is it up / is an instance alive / does health answer) are asked again before every start.
+- **Every attempt reaches the disk**: `<stateDir>/last-watchdog-report.json` — which tier, how many attempts,
+  and per attempt the restore / cookie clear / relaunch / ready, plus why it stopped. A report that never
+  reaches the disk is a report that never happened.
+- **A restart that goes FINE writes its ending too**: when the new host comes up and the watchdog stands
+  down, the report is updated to say so (`result`/`stage`/`outcome: 'disarmed'`, `hostReady`, `disarmed`,
+  `disarmedAt`, and a `disarm` block). Before that, the file stayed at `armed` forever for a restart that
+  had already finished — while `health` correctly answered `ready:true`. The old fields are kept
+  untouched, and `previousResult` still says what the file said before (usually `armed`).
+- **The capability probe's tasks are cleaned up**: proving that this machine can create a one-off task
+  means creating one — and deleting it as the probe's last step, which a crash leaves behind (two were
+  found on a real machine). The boot disarm now removes every leftover task whose name starts with this
+  plugin's own probe prefix (`dsh-autorestart-capability-probe-`) and **never** matches anything else;
+  the name reported for a root-folder task carries a leading `\` (`schtasks` prints `\task-name`), so one
+  leading backslash is stripped before comparing — and a name that still contains a `\` afterwards is a task
+  inside a folder and is refused, never deleted;
+  what it removed (and what it could not) is written into the disarm record and the log, and a refusal
+  never prevents the host from coming up.
+
+### 5. The watchdog's blind spots (say them out loud)
+
+**What it can save**: **a plugin problem of its own making that keeps DSH from booting** — one snapshot is
+restored and the host is started again.
+
+**What it cannot save** (this list matters more than the line above):
+
+- **the DSH binary itself or the system environment** (a broken host upgrade, missing environment
+  dependencies). It repairs no bug of the host: a host that dies for the same reason every time only ends as
+  `failed`, with a report that names the attempts;
+- **third-party plugin problems** — it only looks at its own snapshot: it neither diagnoses which plugin
+  caused the failure nor fixes a third-party plugin's bug;
+- **a full disk, permission problems, changes made by a system update** — restoring a snapshot does not solve
+  any of those;
+- **everything outside the restart window** — a host killed by the system at 03:00, a client that is
+  start-and-die on a manual double-click, a morning with 0 processes: at that moment **nobody is on watch**
+  (the plugin died with the host and no one-off item was ever registered), and all that is left is
+  `scripts/restore-profile.cmd`, double-clicked by hand;
+- **`watchdogEnabled: false`, or a machine whose tier is `none`** → no automatic rollback, and the settings
+  page says so.
+
+### 6. The four steps after something went wrong
+
+1. **look at the popup** — it appears by itself after a restart and says two things separately: which
+   features did not come up this time, and which plugins' files differ from the backup;
+2. **or open the "plugins" section in the settings page and press "check now"** — every installed plugin is
+   listed with its current status (`fine` / `differs from the backup` / `not in the backup` / `not installed`
+   / `cannot tell`);
+3. **a plugin you wrote yourself → press "restore"** — only **that one** named plugin is put back to the
+   version in the backup: the live directory is renamed to `<name>.broken-<ts>` as evidence (`broken` is just
+   the name of that evidence directory, not a conclusion) and **nothing is ever deleted**; every other plugin
+   and `package.json` / `cordis.patch.yml` stay byte-identical;
+4. **a third-party plugin → reinstall the version the popup names** — the panel gives the command, and what
+   comes back is **the version recorded in the backup (not the latest one)**; when the backup does not record
+   the version, the panel says so plainly ("it can only be reinstalled by name").
+
+One precondition behind all four steps: **when there is no usable backup the plugin changes nothing for
+you** — it says "it has to be handled by hand" instead of pretending it restored something.
+
 ## Graceful shutdown (收工关机)
 
 **What it does.** One moon button at the very bottom of the left sidebar: press it and the plugin