dsh-autorestart 0.6.0 → 0.6.2

package/README.md

@@ -76,7 +76,7 @@ what it adds before you install it.
 
 ## Install
 
-Current version: **0.6.0**.
+Current version: **0.6.2**.
 
 From npm — the package is published under the name `dsh-autorestart`:
 
@@ -144,7 +144,9 @@ 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". |
+| `restartGraceMs` | `0` | The **restart reserve** in milliseconds: how long the host waits after the last conversation finished before it is really RESTARTED — a dropdown: `0` / `5` / `10` / `20` / `30` / `60` seconds. `0` means "no extra wait". A restart is a daily operation, so the default is none. The settings page calls it *Wait before the restart*. |
+| `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). **This visible countdown IS the wait before the machine goes off** — the shutdown has no second, invisible reserve. The settings page calls it *Shutdown countdown seconds*. |
+| `queuedGraceMs` | `60000` | Upper bound in milliseconds for a **queued** (unclaimed) inbox message: how long it may hold the restart back before it is treated as stuck. `0` means "no upper bound" (the behaviour before 0.6.2). A **running** conversation always blocks, under every setting. |
 | `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. |
@@ -154,7 +156,6 @@ show up in the Plugin Manager and in the config editor.
 | `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:
@@ -174,21 +175,110 @@ work other plugins queue with a timer of their own — a memory plugin that writ
 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).
+**One reserve window, for the restart.** A restart has no countdown of its own: the host restarts
+as soon as the conversations are done. `restartGraceMs` is the extra wait that leaves room for the
+delayed work of the other plugins — and it is the **only** such window:
+
+| Window | Governs | Default | Offered |
+| --- | --- | --- | --- |
+| `restartGraceMs` | the **restart** | `0` (no extra wait) | `0` / `5` / `10` / `20` / `30` / `60` seconds |
+| `sleepCountdownSeconds` | the **shutdown** (visible!) | `20` (twenty seconds) | `0` / `10` / `20` / `30` / `60` seconds |
+
+- **The restart gate waits `max(settleMs, restartGraceMs)`** of quiet. With the default (`0`) the
+  gate waits for the settle window alone — a restart happens as soon as the conversations are done.
+- **The graceful shutdown has no invisible reserve.** Its **visible countdown** is the wait before
+  the machine goes off: the seconds are on the screen, the user can watch them and cancel them.
+  A second, hidden window next to it would only say the same thing twice — so there is none. The
+  shutdown starts counting down as soon as every conversation is idle.
 - **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).
+  waiting, the reserve starts over — the wait always follows the last activity.
+- **Where to change them.** Settings → Auto-restart & shut down, in two titled groups:
+  *Restart settings* (the wait before the restart, the two backup switches) and *Shutdown settings*
+  (the countdown of the shutdown). The status interfaces report the restart reserve:
+  `GET /health?state=1`, `GET /health?gate=1` and `continuum_status` carry `graceMs` (the restart
+  reserve) and `effectiveSettleMs` (the window the gate really uses); `GET /sleep` carries
+  `restartGraceMs` and `countdownSeconds` (the countdown that is really running). All of them carry
+  `quietForMs` (how long the host has actually been quiet).
+
+### Why a queued message cannot block the restart for ever
+
+**The deadlock.** A conversation whose inbox holds a message nobody claimed yet counts as "busy"
+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.
+
+**The upper bound.** `queuedGraceMs` (default **60000** ms) is how long an unclaimed message may
+hold the restart back:
+
+- **A message claimed inside the window still blocks.** The normal case is unchanged: the agent
+  picks the message up and the restart waits for it.
+- **A message that is still unclaimed after the window is stuck.** It stops blocking the restart,
+  and the log names the session that holds the queue (`the queued message of session <id> has been
+  waiting 61s and nobody claimed it; it no longer blocks the restart`). The restart goes on.
+- **A running conversation always blocks — under every setting.** The bound only ever judges
+  *queued* work; a live turn is never relaxed, and no configuration can make the plugin kill one.
+- **The timer follows the work.** A session that starts working drops its queue timer, and a new
+  queue counts from zero again.
+- **`0` means "as before".** With `queuedGraceMs: 0` an unclaimed message blocks the restart for
+  ever, exactly like it did before this bound existed.
+- **Where to look:** `GET /health?state=1`, `GET /health?gate=1` and `continuum_status` all report
+  `queuedGraceMs`.
+
+### What you see while the restart waits a long time
+
+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:
+
+- **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.
+- **The wait becomes visible.** The log says it once a minute — "the restart has been waiting for
+  17m; `<session>` still holds it — cancel the restart or wait for that work to finish" — and
+  `GET /health?state=1` carries a `longWait` object (`since`, `reason`, `blockedBy`).
+- **The bubble says it too.** The pending-restart pill shows one more line: "waiting for 17m:
+  `<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.
+
+### What the quiet window measures
+
+The restart gate has two layers: **no busy conversation** and **a quiet window**
+(`max(settleMs, restartGraceMs)`).
+
+The quiet window answers one question: *how long ago did the last real work happen?* It is measured
+from the LATER of two markers:
+
+- **the last real activity signal** — a turn that started or ended (`agent/status`), a message that
+  was queued (`agent/inbox/inserted`), or a session event that says work happened (a message, a tool,
+  a turn);
+- **the last moment a conversation was seen working** — a running turn or a queued message
+  (`busyAgents()`).
+
+**A routine session event is not activity.** The host emits session events every two to three seconds
+while the interface polls and synchronises (a title, a projection, a context request, a job that
+settled). Counting those as activity reset the quiet window every couple of seconds, so a window
+longer than the event interval could never fill: the restart never fired, however long the user
+waited. That is why a grace window of ten seconds used to make the restart impossible.
+
+The rule is one-sided: **an event whose type cannot be read is not activity.** When in doubt the
+plugin restarts a little early rather than never.
+
+**A running conversation always blocks.** The quiet window only decides *when* the restart may fire;
+the busy check is the hard guarantee, and it is never relaxed by any setting.
+
+**Where to look when the restart does not happen.** The status interfaces report the reason of the
+gate next to the blockers (`GET /health?state=1` carries `reason`: `conversation-active` when a
+conversation blocks, `settling` when only the quiet window is not full yet, `quiet` when it may go),
+and the pending restart writes one diagnostic line into the log per minute:
+
+```
+restart gate: action=wait reason=agents-busy-within-soft-window busyCount=1 quietForMs=1432 effectiveSettleMs=10000
+```
+
+`action` is what the restart decision did (`wait`, `restart`, `long-wait`, …), `reason` why,
+`busyCount` how many conversations block, `quietForMs` how long the host has been quiet, and
+`effectiveSettleMs` the window it has to fill.
 
 ### Platform note
 
@@ -284,9 +374,25 @@ once, in the same composer dock, as a small card:
   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).
+- **"Seen" means "not older", not "equal".** The card counts as answered as soon as the recorded
+  version is **not older** than the current feature version — a record of `0.6.0` counts as seen
+  while the feature itself stands at `0.5.0`. Why not equality? Because the record does not say
+  *which* release the user answered on (until 0.6.0 the card carried the version of the package),
+  so an equality check would tell a user who already dismissed the card that they never saw it. A
+  record that is not a version at all counts as seen as well: a broken record must not make the
+  card come back for ever.
+- **Once per feature 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 release of
+  the plugin (a *newer version of the feature* is announced again, of course).
+- **The announcement follows the FEATURE, not the release.** The version it carries is a constant in
+  the source (`SLEEP_FEATURE_VERSION` in `index.js`), **not** the version of the package: a release
+  never brings the card back. Until 0.6.0 the card carried the package version, and every release
+  (0.5.0 → 0.6.0) brought "graceful shutdown" back to the users who had already answered it.
+- **How to announce it again on purpose.** Raise `SLEEP_FEATURE_VERSION` to a version **newer** than
+  the one that was recorded last: the card is then shown exactly once more. Do that **only** when
+  the feature itself changed so much that the user has to hear about it again (the shutdown became a
+  completely different thing, the button moved somewhere else, …). A release, a bug fix or a small
+  addition must **not** touch it — that is exactly the bug this constant exists to prevent.
 - **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
@@ -294,7 +400,8 @@ once, in the same composer dock, as a small card:
   ("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 }`).
+  and records it on `POST /announcements` (`{ feature }`). The `version` in that answer is the feature
+  version — the same number that `SLEEP_FEATURE_VERSION` holds.
 
 ## Graceful shutdown (收工关机)
 
@@ -330,7 +437,8 @@ record that cannot be read is dropped — asking once more is much better than a
 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`.
+`phase`, `blockers`, `countdownSeconds` (the countdown that is really running) and
+`restartGraceMs` (the restart reserve).
 
 ### Troubleshooting: the machine did not switch off
 
@@ -361,11 +469,13 @@ waiting for something. Here is what it can be, and what to do about it:
    `待执行的重启`). 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.
+3. **The work just ended and the countdown has not started yet.** The shutdown has **no invisible
+   reserve**: as soon as every conversation is idle the countdown starts. **What you see:**
+   `phase` is `waiting` while `blockers[]` is empty and `remainingMs` is at its full value only
+   while the conversations are still busy — with an empty list the countdown is already running.
+   **What to do:** nothing; the countdown is on the screen and it can be cancelled there. (The
+   restart has its own window — `restartGraceMs`, default none — and the two never influence each
+   other.)
 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.
@@ -438,13 +548,19 @@ more whether the button should stay. The answer is written into the profile conf
 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.
+settings sidebar (right below the Agent presets). It is split into two titled groups — the restart
+settings first, the shutdown settings after them:
+
+- **Restart settings**
+  - **Wait before the restart** (`restartGraceMs`) — the dropdown `0` / `5` / `10` / `20` / `30` /
+    `60` seconds. `0` (the default) means "no extra wait": the host restarts as soon as the
+    conversations are done.
+  - **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.
+- **Shutdown settings**
+  - **Shutdown countdown seconds** (`sleepCountdownSeconds`) — the dropdown `0` / `10` / `20` / `30` /
+    `60`. `0` means "no countdown": the machine is switched off as soon as every conversation is idle.
 
 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