dsh-autorestart 0.3.6 → 0.5.0

package/README.md

@@ -38,6 +38,11 @@ Before every restart the plugin snapshots the profile, so a restart that leaves
 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 +55,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 +72,8 @@ what it adds before you install it.
 
 ## Install
 
+Current version: **0.5.0**.
+
 From npm — the package is published under the name `dsh-autorestart`:
 
 ```sh
@@ -141,6 +148,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:
 
@@ -218,16 +228,144 @@ 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.
+
+**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 +417,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 +426,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 +439,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