dsh-autorestart 0.3.6 → 0.6.0

package/README.md

@@ -29,15 +29,24 @@ round starts, so the session goes idle and the restart can proceed. The goal is
 restart and continues.
 
 The browser shows the state: a compact "pending restart" pill on the left side of the input toolbar
-and a small dot next to the session title in the sidebar. The pill's text reports how many
-conversations are still in the way (counted once per conversation, and the tooltip explains that a
-conversation with queued-but-not-started work counts too); it does not open a details panel. The dot
-breathes when the restart is about to fire.
+and a small dot next to the session title in the sidebar. The pill's text reports how many **tasks**
+are still in the way — a conversation, a subagent or a teammate counts as one task each, and the
+tooltip explains that queued-but-not-started work counts too; it does not open a details panel. The
+dot breathes when the restart is about to fire.
+
+Every blocker says **what it is**: a conversation is named by its own title, and a **subagent** is
+named after the conversation that created it ("Subagent of *that* conversation"). A raw session id is
+never shown to the user.
 
 Before every restart the plugin snapshots the profile, so a restart that leaves the host unable to
 boot is rolled back automatically — see
 [Pre-restart backup and automatic rollback](#pre-restart-backup-and-automatic-rollback).
 
+The same "wait until everything is quiet" idea is also available as a **graceful shutdown**: a moon
+button at the very bottom of the left sidebar (right next to Settings) waits for every conversation
+to be idle, counts down on screen (a floating card with a huge number and a small whale) and then
+switches the **real host machine** off — see [Graceful shutdown](#graceful-shutdown-收工关机).
+
 Two safety gates protect the restart. The host checks that no conversation is busy, and the detached
 helper checks the same gate over loopback immediately before it kills the process, so a turn that
 starts in between is never killed.
@@ -50,8 +59,8 @@ what it adds before you install it.
 | Kind | What it adds |
 | --- | --- |
 | Agent tools (6) | `continuum_restart`, `continuum_status`, `continuum_cancel_restart`, `continuum_park_goal`, `continuum_recover_now`, `continuum_handoff` |
-| HTTP routes (4) | Under `<healthPath>` (default `/__dsh_autorestart`): `GET /health` (also `?state=1`, `?gate=1`, `?probeIndex=1`), `POST /park`, `POST /recover`, `POST /handoff`. Loopback or an authenticated browser only |
-| Client slots (2) | `conversation.input.left` — the pending-restart pill (`autorestart-restart-pill`); `sidebar.session.row.leading` — the session status dot (`autorestart-restart-dot`) |
+| HTTP routes (7) | Under `<healthPath>` (default `/__dsh_autorestart`): `GET /health` (also `?state=1`, `?gate=1`, `?probeIndex=1`), `POST /park`, `POST /recover`, `POST /handoff`, `GET /sleep` and `POST /sleep` (the graceful shutdown — the desktop client and the hosted web client drive the very same route), `GET /announcements` and `POST /announcements` (the one-time new-feature announcement). Loopback or an authenticated browser only |
+| Client slots (6) | `conversation.input.left` — the pending-restart pill (`autorestart-restart-pill`); `sidebar.session.row.leading` — the session status dot (`autorestart-restart-dot`); `conversation.input.dock` — the one-time install question (`autorestart-backup-choice`) and the one-time new-feature announcement (`autorestart-feature-announcement`); `sidebar.footer.action` — the moon button of the graceful shutdown (`autorestart-sleep-button`); `shell.overlay` — its countdown card; `settings.section` — the section "Auto-restart & shut down" in the settings page (`dsh-autorestart`) |
 | 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` |
@@ -67,6 +76,8 @@ what it adds before you install it.
 
 ## Install
 
+Current version: **0.6.0**.
+
 From npm — the package is published under the name `dsh-autorestart`:
 
 ```sh
@@ -133,6 +144,7 @@ show up in the Plugin Manager and in the config editor.
 | `restartCommand` | `''` | Custom restart command. Supports the `{pid}`, `{ppid}` and `{app}` placeholders. |
 | `relaunchDelaySeconds` | `2` | How long the detached helper waits before it kills the app (`ping -n 3`, roughly 2 seconds). |
 | `settleMs` | `2000` | Quiet window in milliseconds: the host must stay silent this long after the last conversation activity before a restart may start. |
+| `restartGraceMs` | `10000` | Grace window in milliseconds: how long the host waits after the last conversation finished before it is really restarted or switched off — a dropdown: `0` / `3` / `5` / `10` / `20` / `30` seconds. `0` means "no extra wait". |
 | `autoReloadPage` | `true` | `dsh web`: reload the page automatically when the host boot token changes. |
 | `blockManualRestart` | `true` | Hard-block an agent that tries to kill or restart DSH with a shell command, and point it at `continuum_restart` instead. |
 | `healthPath` | `/__dsh_autorestart/health` | Health check route. Returns the boot id, the pid, the phase and the self-check flags. |
@@ -141,6 +153,9 @@ show up in the Plugin Manager and in the config editor.
 | `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. |
+| `showSleepButton` | `true` | Whether the moon button of the graceful shutdown is shown at the foot of the left sidebar, next to Settings. |
+| `sleepCountdownSeconds` | `20` | How many seconds the graceful shutdown counts down before the machine goes down — a dropdown: `0` / `10` / `20` / `30` / `60` seconds. `0` means "switch off right away" (still waiting for the conversations to be idle). |
+| `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). |
 
 The two waits are independent of each other, and both default to two seconds:
 
@@ -151,6 +166,30 @@ The two waits are independent of each other, and both default to two seconds:
 Both can be overridden separately in the profile config. A larger `settleMs` is the more
 conservative choice, because it is less likely to cut a session short that has just started.
 
+### Why the host waits a few more seconds after the work is done
+
+**The blind spot.** This plugin can only see the **DSH agents**: it knows whether a conversation is
+running, whether it has queued inbox work, and when the last of them went idle. It cannot see the
+work other plugins queue with a timer of their own — a memory plugin that writes its notes a few
+seconds after the conversation ended, a summary, an MCP callback, a log flush. That work is
+invisible here, so "every agent is idle" does not mean "nothing is happening any more".
+
+**The grace window.** `restartGraceMs` (default **10 seconds**) is the extra wait for exactly
+that: after the LAST conversation finished, the host waits this long before it is really restarted
+or switched off. It is a plain, configurable insurance — not a special case for any particular
+plugin.
+
+- **Both paths use it.** The restart gate waits `max(settleMs, restartGraceMs)` of quiet, and the
+  graceful shutdown waits the same grace **before** its countdown starts (so the grace never pushes
+  a countdown that is already running back by a round).
+- **New activity restarts the timer.** If a conversation starts working again while the host is
+  waiting, the grace starts over — the wait always follows the last activity.
+- **`0` means "as before".** With `restartGraceMs: 0` the behaviour is exactly the one of 0.4.0.
+- **Where to change it.** Settings → Auto-restart & shut down → *Wait a few more seconds after the
+  work is done*. The status interfaces report it too: `GET /health?state=1`, `GET /health?gate=1`,
+  `continuum_status` and `GET /sleep` all carry `graceMs` (the configured window) and `quietForMs`
+  (how long the host has actually been quiet).
+
 ### Platform note
 
 `restartMode: app` only applies to the DeepSeek Harness desktop app. A hosted `dsh web`
@@ -218,16 +257,218 @@ addition to it, never a rival of it.
   stays usable, nothing is modal, and the panel does not disappear on its own. It is keyboard
   reachable and `Esc` closes it.
 - **Where the answer goes.** The host writes it into the profile configuration with the official
-  `configEditor` service — the same `backupIncludePlugins` key the settings page edits, so there is
+  `configEditor` service — the same `backupIncludePlugins` key the settings section edits, so there is
   one source of truth. If that service is unavailable the answer degrades to
   `<DSH_HOME>/storages/dsh-autorestart/install-choice.json` and a warning is logged. The same fallback
   happens in a hosted profile that declares no `dsh-autorestart` row of its own: there is no row for the
   editor to write, so the answer lands in that file instead of the profile. Declare the row (see
   *Hosted `dsh web` deployments* below) to keep the profile configuration as the single source of truth.
-- **How to change your mind later:** Settings → Plugins → dsh-autorestart → `backupIncludePlugins`.
+- **How to change your mind later:** Settings → Auto-restart & shut down → `backupIncludePlugins`.
   `continuum_status` always reports the value that is in effect right now
   (`backupIncludePlugins: true | false`).
 
+### The one-time new-feature announcement (upgrades)
+
+**The gap it closes.** The install question above is asked exactly once — on the *first* install. An
+installation that already existed therefore never hears of a feature that was added later: for an
+upgrade the new moon button would simply not exist. Since **0.5.0** every new feature is announced
+once, in the same composer dock, as a small card:
+
+> **New feature: graceful shutdown**
+> There is a new 🌙 "Shut down" button at the very bottom of the left sidebar.
+> Click it → once every conversation is done it counts down **N** seconds and powers the machine off.
+> To change that, go to "Settings → Auto-restart & shut down".
+> **Got it**
+
+- **Only after an upgrade.** The host compares the version of the feature with the version it has
+  already shown (`seenFeatureVersions` in the checkpoint file). A fresh installation never sees the
+  card: the install question already explains the features, and answering it marks the announcement
+  as seen.
+- **Once per version, for ever.** "Got it" records the version, the card disappears at once, and it
+  never comes back — not with the next restart of the host, and not with the next version of the
+  plugin (a *new* version of a feature is announced again, of course).
+- **An unanswered card is not swallowed.** The card stays until it is answered, and it comes back with
+  the next start of DSH.
+- **The countdown is read, not written.** The seconds in the card are the ones that are really in
+  effect (`sleepCountdownSeconds`), and when the moon button is switched off the card says so
+  ("The button is currently switched off; you can turn it on in the settings").
+- **Where the state lives.** `<DSH_HOME>/storages/dsh-autorestart/state.json`, next to the checkpoint
+  of the plugin. The host serves it on `GET /announcements` (`{ ok, pending: [{ feature, version }] }`)
+  and records it on `POST /announcements` (`{ feature }`).
+
+## Graceful shutdown (收工关机)
+
+**What it does.** One moon button at the very bottom of the left sidebar: press it and the plugin
+waits until **every** conversation is idle, the screen counts down (a huge number and a small blue
+whale, one line of text per second), and then the machine is switched off. The countdown can always
+be cancelled — the card has a button, and the moon button itself becomes a toggle while the shutdown
+is armed. If a conversation starts working again during the countdown, the countdown goes back to
+"waiting" and nothing is switched off.
+
+### Shutdown and restart: who goes first
+
+**The short version.** Pressing the moon button means "switch the machine off when the work is
+done" — **not** "switch it off right now, whatever else is running". So:
+
+1. **A pending restart wins.** If a restart is still on the list, the shutdown does **not** happen.
+   The card says *"Waiting for the pending restart to finish before shutting down"*. The restart
+   goes first, the sessions come back with it and keep working, and only then does the machine
+   go off.
+2. **The work keeps running after the restart.** The sessions that resume with the restart are
+   running work: while any of them is busy, the shutdown waits. The machine only goes off when
+   **every** session is idle again.
+3. **The shutdown intent survives the restart.** You pressed the button **once**. The restart does
+   not swallow that request: it is written into the checkpoint file, and the new boot picks it up
+   and keeps waiting for the work. You do **not** have to press the button a second time.
+4. **You can cancel at any time.** The waiting card has a *"Keep it on"* button; pressing it (or the
+   moon button again) forgets the intent for good.
+
+**Where the intent lives.** In the checkpoint file
+(`<DSH_HOME>/storages/dsh-autorestart/state.json`) as `sleep: { armed, armedAt, countdownSeconds }`.
+It is cleared as soon as the machine went off, when the shutdown failed, and when you cancel. A
+record that cannot be read is dropped — asking once more is much better than a machine that switches
+itself off for ever because of a half-written file.
+
+**For the troubleshooting.** `GET /sleep` reports `armedAt` (when the shutdown was armed) next to
+`phase`, `blockers` and `graceMs`.
+
+### Troubleshooting: the machine did not switch off
+
+**These are the real answers of a running host** (the copy of the host is Chinese, the fields are
+not):
+
+```
+POST /__dsh_autorestart/sleep {"action":"arm"}   # three conversations are working
+→ phase=waiting  armed=true  remainingMs=20000   (the full value: the countdown has NOT started)
+  message: 等 3 个任务收工，收工后开始倒数。
+
+# after a restart was requested:
+GET /__dsh_autorestart/sleep
+→ phase=waiting  armed=true  remainingMs=20000
+  message: 等这次重启完成后再关机……
+  blockers: [{"sessionId":"restart-pending","kind":"restart-pending",
+              "label":"待执行的重启","name":"待执行的重启"}]
+```
+
+`remainingMs` at its full value is the tell: **the countdown has not started**, so the machine is
+waiting for something. Here is what it can be, and what to do about it:
+
+1. **Some tasks are still working.** `blockers[]` lists them; look at `kind`:
+   `session` is a conversation, `subagent` is a child agent of one. A subagent counts as work on
+   purpose — otherwise a restart would cut it off. **What to do:** let it finish, or stop that
+   conversation. The list shrinks on its own.
+2. **A restart is still pending.** `kind` is `restart-pending` (`label`/`name` are
+   `待执行的重启`). That is normal queueing, not a fault: the restart runs first, the sessions
+   come back with it, and the countdown continues afterwards. **What to do:** nothing — wait for
+   the restart. (You can also cancel the restart with `continuum_cancel_restart`.)
+3. **The work just ended and the grace window is still running** (default 10 seconds, so that a
+   memory or summary plugin can still write its notes). **What you see:** `graceMs` is the
+   configured window, `quietForMs` is how long the host has actually been quiet. **What to do:**
+   wait; if another conversation starts working during the wait, the timer starts over (that is
+   the point of the window). Set it to `0` in the settings if you do not want the extra wait.
+4. **Somebody started working during the countdown.** The countdown goes back to "waiting" and
+   `remainingMs` returns to its full value. **What you see:** the message says that somebody
+   started working again, and `blockers[]` lists who. **What to do:** let them finish.
+5. **You want to know who it is waiting for.** `continuum_status` → `blockedBy[]` and
+   `GET /sleep` → `blockers[]` are the **same data**: the first is for agents, the second for
+   scripts. Each entry has `kind` (what it is), `label` (the title of the session) and `name`
+   (the whole name, e.g. "the subagent of the coding session"). A session whose title could not
+   be resolved reports `label: null` and an empty `name` — that is why the waiting line then
+   only says "等 3 个任务收工" without a list of names.
+6. **You do not want it at all.** The cancel button on the waiting card (or the moon button
+   again, or `POST /sleep {"action":"cancel"}`) clears the intent for good: `armed` becomes
+   `false` and `armedAt` becomes `null`.
+
+**Where the button is.** The moon button sits at the **very bottom of the left sidebar, right next
+to the Settings row** (`sidebar.footer.action`). That seat is a **root** slot, so the button is
+there even when no conversation is open — on any page. When the sidebar is collapsed into its narrow
+rail, the button shows its icon only (the tooltip and the accessible name still say what it does),
+so the rail keeps its width.
+
+**The countdown does not cover the interface.** The countdown is a **floating card** in the corner,
+not a full-screen mask: it never dims the page, never locks the scrolling and never swallows a
+click. You can keep reading the conversation, keep scrolling and keep switching conversations while
+it counts down; only the card's own cancel button takes clicks. Switching a conversation or a page
+does not interrupt the countdown either — the seconds come from the host, not from the view that
+happens to be open.
+
+**What gets switched off: the real host.** Not a subsystem — the whole machine:
+
+| Host | Command |
+| --- | --- |
+| Windows | `shutdown.exe /s /f /t 0` |
+| WSL (the DSH itself runs inside a distribution) | `/mnt/c/Windows/System32/shutdown.exe /s /f /t 0` — the Windows binary through the mounted `C:` drive, so **Windows itself** goes down. The WSL subsystem is never shut down. |
+| A real Linux host | `systemctl poweroff` (fallback `shutdown -h now`) |
+| macOS | `osascript -e 'tell application "System Events" to shut down'` |
+| Anything else | **Nothing is executed at all.** The button stays hidden and the route reports `phase: "unsupported"`. |
+
+A WSL host is recognised through `WSL_DISTRO_NAME`, `WSL_INTEROP`, a `/proc/version` that mentions
+Microsoft, or the mounted Windows binary. The countdown belongs to the plugin, so the operating
+system is asked to shut down immediately (`/t 0`) instead of counting down a second time.
+
+**Configuration.** `showSleepButton` (default `true`) decides whether the button is shown,
+`sleepCountdownSeconds` (a **dropdown**: `0` / `10` / `20` / `30` / `60` seconds, default `20`) how
+long the countdown runs, and `sleepCommand` (default `''`) replaces the detected command with one of
+your own — empty means "detect the host automatically". `0` means **no countdown at all**: the machine
+is switched off as soon as every conversation is idle (a busy conversation still blocks it), and no
+countdown card appears. A profile that still carries a value the dropdown does not offer (`15`,
+`45`, …) is snapped onto the nearest offered one instead of breaking.
+
+**One click is all it takes.** The moon button arms the shutdown: the host waits for every busy
+conversation, counts down **20 seconds** in a floating card (it never covers the interface), and then
+switches the machine off. Clicking the button again — or the cancel button on the card — takes it
+back. Nothing else is asked of the user: no confirmation dialog, no second click.
+
+**The desktop client and the hosted web client behave exactly the same.** There is no ticket, no
+extra header and no hidden mode: `POST /__dsh_autorestart/sleep` takes nothing but the action, and
+the same route serves both. A script (or an agent) can therefore drive the shutdown as well:
+
+```bash
+# arm it (the machine counts down and goes off)
+curl -s -X POST http://127.0.0.1:<port>/__dsh_autorestart/sleep \
+  -H 'content-type: application/json' -d '{"action":"arm"}'
+# take it back
+curl -s -X POST http://127.0.0.1:<port>/__dsh_autorestart/sleep \
+  -H 'content-type: application/json' -d '{"action":"cancel"}'
+```
+
+**The one-time install question.** The first time the plugin is used, the composer dock asks once
+more whether the button should stay. The answer is written into the profile configuration
+(`showSleepButton`) through the same `configEditor` service the backup question uses, so the
+settings section and the prompt always show the same value.
+
+**The settings section.** *Settings → Auto-restart & shut down* is a section of its own in the
+settings sidebar (right below the Agent presets). It carries the three settings that matter:
+
+- **Countdown seconds** — the dropdown `0` / `10` / `20` / `30` / `60`. `0` means "no countdown":
+  the machine is switched off as soon as every conversation is idle.
+- **Backup before a restart** (`backupOnRestart`) — whether the pre-restart snapshot is taken at all.
+- **Include the installed plugins in the backup** (`backupIncludePlugins`) — whether that snapshot
+  also contains the plugin directory of the profile. It is greyed out when the backup itself is off.
+
+A change is written into the profile configuration at once (through the plugin's own choice route)
+and is read back from the host, so the section never shows a value the host did not take. A malformed
+value is refused with a **400** and **nothing** is written.
+
+**Trying it without switching anything off.** Set `DSH_AUTORESTART_SLEEP_DRYRUN=1` in the host
+environment: the plugin then reports the command it *would* run and never runs it.
+
+**The machine-readable state.** `GET <healthPath 前缀>/sleep` (default
+`/__dsh_autorestart/sleep`) answers with the phase, the countdown and the host that is about to be
+closed. A few of its fields are meant to be read by code rather than by a human: `host.kind` is the
+kind of machine (`windows`, `wsl`, `linux`, `macos`, `unsupported`, or `custom` when the platform
+could not be recognised but a `sleepCommand` was configured); `host.suspect` is `true` when the host
+was only recognised as WSL because the Windows drive is mounted — a hint, not a proof;
+`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.
+
+**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
+(…), the computer is still on, press the moon button again"), and the machine stays on. On screen
+the "shutting down" card never locks the interface: after at most eight seconds it offers a button
+that closes the card.
+
 ## Requirements and limits
 
 - **Windows desktop.** `restartMode: app` restarts the DSH desktop app on Windows. Any other
@@ -279,7 +520,7 @@ when the host is started by hand. `continuum_status` keeps reporting the pending
 The same profile row is what the one-time install question writes into: a hosted profile that declares no
 `dsh-autorestart` row has no row for the `configEditor` service to edit, so the answer falls back to
 `<DSH_HOME>/storages/dsh-autorestart/install-choice.json` instead of the profile configuration. Declaring the
-row keeps the profile (and therefore the settings page) as the single source of truth.
+row keeps the profile (and therefore the settings section) as the single source of truth.
 
 ## Verify
 
@@ -288,7 +529,7 @@ The health route tells you whether the plugin is alive and what it has done:
 ```sh
 curl http://127.0.0.1:<gui port>/__dsh_autorestart/health
 # {"ok":true,"plugin":"dsh-autorestart","bootId":"…","pid":17884,"phase":"running",
-#  "pageHeartbeat":true,"systemPrompt":true,"configSchema":true,"indexTaps":2,…}
+#  "pageHeartbeat":true,"systemPrompt":true,"configSchema":true,"indexTaps":1,…}
 ```
 
 `bootId` and `pid` change with every new process, so a restart is visible right away.
@@ -301,9 +542,11 @@ curl http://127.0.0.1:<gui port>/__dsh_autorestart/health
   anything.
 - `POST /__dsh_autorestart/park` disarms a goal, `POST /__dsh_autorestart/recover` re-runs the
   recovery immediately. Both use the same authentication rules as the health route.
+- `GET /__dsh_autorestart/sleep` reports the state of the graceful shutdown, `POST
+  /__dsh_autorestart/sleep` arms (`{ "action": "arm" }`) or cancels (`{ "action": "cancel" }`) it.
 - Inside a session, `continuum_status` reports the same lifecycle.
 
-The plugin ships its own test suite: **129 test cases** in `plugins/dsh-autorestart/test/`, all
+The plugin ships its own test suite: **250 test cases** in `plugins/dsh-autorestart/test/`, all
 green. Run it with the bundled Node, from the workspace root:
 
 ```sh