dsh-autorestart 0.5.0 → 0.6.0

package/README.md

@@ -29,10 +29,14 @@ 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
@@ -72,7 +76,7 @@ what it adds before you install it.
 
 ## Install
 
-Current version: **0.5.0**.
+Current version: **0.6.0**.
 
 From npm — the package is published under the name `dsh-autorestart`:
 
@@ -140,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. |
@@ -161,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`
@@ -276,6 +305,80 @@ be cancelled — the card has a button, and the moon button itself becomes a tog
 is armed. If a conversation starts working again during the countdown, the countdown goes back to
 "waiting" and nothing is switched off.
 
+### 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

package/client.js

@@ -114,20 +114,33 @@ const SLEEP_DEFAULT_COUNTDOWN_SECONDS = 20
 /** How long the note of a finished rehearsal stays on screen (ms). */
 const SLEEP_DRY_RUN_NOTICE_MS = 8_000
 
+/**
+ * The grace window the settings page offers (a dropdown, in seconds).
+ *
+ * It is the extra wait after the last conversation finished, so that work
+ * other plugins queue with a timer (a memory plugin writing its notes, a
+ * summary) still gets its chance — this plugin cannot see that work.
+ */
+const GRACE_CHOICES_SECONDS = Object.freeze([0, 3, 5, 10, 20, 30])
+
+/** The grace window used when the Host did not report one (ms / seconds). */
+const GRACE_DEFAULT_MS = 10_000
+const GRACE_DEFAULT_SECONDS = 10
+
 const ZH = {
   label: '待重启',
-  busyPrefix: ' · 被 ',
-  busySuffix: ' 个会话占用',
+  busyPrefix: ' · 等待 ',
+  busySuffix: ' 个任务结束',
   idle: ' · 空闲后自动重启',
-  goalActive: ' · 被某个会话自动续跑的 goal 占着',
-  goalExhausted: ' · 某个会话的 goal 轮次额度已用完，无法续跑',
+  goalActive: ' · 被某个自动续跑的 goal 占着',
+  goalExhausted: ' · 某个任务的 goal 轮次额度已用完，无法续跑',
   parkedGoals: ' · 已停泊 {n} 个 goal，重启后自动继续',
   parkButton: '停泊并重启',
   parkButtonAria: '停泊该会话的 goal，并立即请求重启',
   parkBusy: '停泊中…',
   parkError: '停泊失败：{message}',
   tooltip: '等待其他会话空闲后自动重启；重启后会自动继续本会话进度',
-  tooltipBusy: '等待其他会话空闲后自动重启（计数含“排队但还没开始”的任务）；重启后本会话会自动继续进度',
+  tooltipBusy: '等待其他任务结束（计数含“排队但还没开始”的任务）后自动重启；重启后本会话会自动继续进度',
   tooltipWithError: '等待其他会话空闲后自动重启；重启后本会话会自动继续进度。{message}',
   dotAria: '待重启',
   panelHeading: '待重启',
@@ -136,7 +149,13 @@ const ZH = {
   panelStateGoalActive: '等待其他会话停泊它自动续跑的 goal',
   panelStateGoalExhausted: '等待其他会话的 goal（轮次额度已用完）',
   panelBlockedTitle: '占用会话：{title}',
-  panelBlockedGeneric: '有一个会话正在运行',
+  panelBlockedGeneric: '有一个任务正在运行',
+  // One line per blocker: a session and a subagent are told apart, and
+  // neither of them is ever shown as a raw session id.
+  panelBlockedSession: '会话「{label}」正在运行',
+  panelBlockedSubagent: '{name}正在运行',
+  panelBlockedSubagentGeneric: '有一个子智能体正在运行',
+  panelBlockedRestartPending: '等这次重启完成后再关机',
   panelGoalActiveLine: '占用会话「{title}」：goal 正在自动续跑（goal-active）',
   panelGoalExhaustedLine: '占用会话「{title}」：goal 轮次额度已用完，无法继续（goal-exhausted）',
   panelParkedTitle: '已停泊的 goal（重启后自动继续）：',
@@ -177,6 +196,10 @@ const ZH = {
   'settings.seconds.immediate': '不倒数（立即关机）',
   'settings.seconds.value': '{n} 秒',
   'settings.seconds.hint': '按下按钮后，等所有会话收工，再倒数这么多秒才关机；「不倒数」表示会话一收工就关机。',
+  'settings.grace.label': '收工后再等几秒（给记忆/总结类插件留时间）',
+  'settings.grace.hint': '最后一个会话收工后，再等这么久才真正重启或关机——我们只看得见 DSH 的会话，看不见别的插件用定时器排队的活。等待期间如果又有会话开始干活，会重新计时。',
+  'settings.grace.value': '{n} 秒',
+  'settings.grace.immediate': '不等（立即重启/关机）',
   'settings.backup.label': '重启前备份',
   'settings.backup.hint': '每次重启前先快照一次当前配置；万一重启后起不来，能自动回退。',
   'settings.backupPlugins.label': '备份包含已安装插件',
@@ -212,7 +235,8 @@ const ZH = {
   'sleep.countdown.hint': '再过 {n} 秒就关机，点「算了，别关」可以留下。',
   'sleep.waiting.title': '还在等大家收工',
   'sleep.waiting.body': '等这些会话忙完，就轮到关机啦：',
-  'sleep.waiting.count': '还有 {n} 个会话在干活',
+  'sleep.waiting.count': '还有 {n} 个任务在干活',
+  'sleep.waiting.subagents': '其中 {k} 个是子智能体',
   'sleep.waiting.blocker': '· {title}',
   'sleep.waiting.none': '（正在确认还有谁在忙）',
   'sleep.waiting.cancel': '不关了',
@@ -246,8 +270,8 @@ const ZH = {
 
 const EN = {
   label: 'Pending restart',
-  busyPrefix: ' · blocked by ',
-  busySuffix: ' session(s)',
+  busyPrefix: ' · waiting for ',
+  busySuffix: ' task(s) to finish',
   idle: ' · restarts once idle',
   goalActive: ' · held by a self-continuing goal',
   goalExhausted: ' · a goal ran out of rounds',
@@ -259,7 +283,7 @@ const EN = {
   tooltip:
     'Waits for the other sessions to become idle, then restarts automatically; this session resumes its progress after the restart.',
   tooltipBusy:
-    'Waits for the other sessions to become idle, then restarts automatically (the count includes work that is queued but not started yet); this session resumes its progress after the restart.',
+    'Waits for the other tasks to finish (the count includes work that is queued but not started yet), then restarts automatically; this session resumes its progress after the restart.',
   tooltipWithError:
     'Waits for the other sessions to become idle, then restarts automatically; this session resumes its progress after the restart. {message}',
   dotAria: 'Pending restart',
@@ -269,7 +293,13 @@ const EN = {
   panelStateGoalActive: 'Waiting for the other sessions to park their self-continuing goal',
   panelStateGoalExhausted: 'Waiting for the other sessions\' goal (its round budget is used up)',
   panelBlockedTitle: 'Blocking session: {title}',
-  panelBlockedGeneric: 'One session is running',
+  panelBlockedGeneric: 'One task is running',
+  // One line per blocker: a session and a subagent are told apart, and
+  // neither of them is ever shown as a raw session id.
+  panelBlockedSession: 'Session "{label}" is running',
+  panelBlockedSubagent: '{name} is running',
+  panelBlockedSubagentGeneric: 'One subagent is running',
+  panelBlockedRestartPending: 'Waiting for the pending restart to finish before shutting down',
   panelGoalActiveLine: 'Blocking session "{title}": the goal keeps driving rounds by itself (goal-active)',
   panelGoalExhaustedLine: 'Blocking session "{title}": the goal ran out of rounds and cannot continue (goal-exhausted)',
   panelParkedTitle: 'Parked goals (they continue after the restart):',
@@ -310,6 +340,10 @@ const EN = {
   'settings.seconds.immediate': 'No countdown (switch off right away)',
   'settings.seconds.value': '{n} seconds',
   'settings.seconds.hint': 'After the button: wait for every conversation to be done, count down this many seconds and switch off. "No countdown" switches off as soon as the conversations are done.',
+  'settings.grace.label': 'Wait a few more seconds after the work is done',
+  'settings.grace.hint': 'After the last conversation finished, wait this long before the host is really restarted or switched off — this plugin only sees the DSH conversations, not the work other plugins queue with a timer. If a conversation starts working again while waiting, the timer starts over.',
+  'settings.grace.value': '{n} seconds',
+  'settings.grace.immediate': 'Do not wait (restart/switch off right away)',
   'settings.backup.label': 'Backup before a restart',
   'settings.backup.hint': 'Take a snapshot of the current configuration before every restart, so a host that cannot boot again is rolled back automatically.',
   'settings.backupPlugins.label': 'Include the installed plugins in the backup',
@@ -345,7 +379,8 @@ const EN = {
   'sleep.countdown.hint': 'Powering off in {n} seconds — pick "Never mind, keep it on" to stay.',
   'sleep.waiting.title': 'Waiting for everyone to finish',
   'sleep.waiting.body': 'Once these sessions are done, the machine powers off:',
-  'sleep.waiting.count': '{n} session(s) still working',
+  'sleep.waiting.count': '{n} task(s) still working',
+  'sleep.waiting.subagents': '{k} of them are subagents',
   'sleep.waiting.blocker': '· {title}',
   'sleep.waiting.none': '(checking who is still busy)',
   'sleep.waiting.cancel': 'Keep it on',
@@ -731,6 +766,53 @@ if (moduleLoader) moduleLoader.load({
       ))
     }
 
+    /**
+     * The line of one blocker: a session and a subagent are told apart, and
+     * neither of them is ever shown as a raw session id.
+     *
+     * The Host says WHAT the blocker is (`kind`) and HOW it is called: a
+     * session by its own title (`label`), a subagent by the whole phrase
+     * (`name`: "写代码的会话的子智能体"). The phrase is used as it is — it
+     * reads as a sentence, while a bracketed label would read like an
+     * annotation. A subagent whose parent title is unknown has no name of its
+     * own, so it gets the generic line instead of an empty bracket.
+     *
+     * @param {any} entry the blocker the Host reported
+     * @returns {string}
+     */
+    function blockerLine(entry) {
+      const t = translate ?? ((name) => name)
+      const kind = entry && entry.kind === 'subagent'
+        ? 'subagent'
+        : (entry && entry.kind === 'restart-pending' ? 'restart-pending' : 'session')
+      const label = entry && typeof entry.label === 'string' ? entry.label.trim() : ''
+      if (kind === 'restart-pending') {
+        // A pending restart goes first: the shutdown waits for it.
+        return t('panelBlockedRestartPending')
+      }
+      if (kind === 'subagent') {
+        const name = entry && typeof entry.name === 'string' ? entry.name.trim() : ''
+        if (name === '' || label === '') return t('panelBlockedSubagentGeneric')
+        return fill(t('panelBlockedSubagent'), { name })
+      }
+      return label === ''
+        ? t('panelBlockedGeneric')
+        : fill(t('panelBlockedSession'), { label })
+    }
+
+    /**
+     * Whether a blocker is a pending RESTART (and not a task that is running).
+     *
+     * The restart is not a task: it is the thing the shutdown waits for, so it
+     * is never counted as one.
+     *
+     * @param {any} entry
+     * @returns {boolean}
+     */
+    function isRestartPending(entry) {
+      return Boolean(entry) && entry.kind === 'restart-pending'
+    }
+
     /** How long the pending restart has been waiting, as a locale string. */
     function formatWaiting(ms, t) {
       const totalSeconds = Math.max(0, Math.floor((ms || 0) / 1000))
@@ -2296,6 +2378,15 @@ if (moduleLoader) moduleLoader.load({
       const backupIncludePlugins = status && typeof status === 'object' && typeof status.backupIncludePlugins === 'boolean'
         ? status.backupIncludePlugins
         : true
+      // The grace window: how long the host waits after the last conversation
+      // finished. The Host reports it in milliseconds; the dropdown works in
+      // seconds.
+      const reportedGraceMs = status && typeof status === 'object' && typeof status.graceMs === 'number'
+        ? status.graceMs
+        : GRACE_DEFAULT_MS
+      const graceSeconds = GRACE_CHOICES_SECONDS.indexOf(Math.round(reportedGraceMs / 1000)) === -1
+        ? GRACE_DEFAULT_SECONDS
+        : Math.round(reportedGraceMs / 1000)
 
       /**
        * Write one change into the profile configuration.
@@ -2363,6 +2454,33 @@ if (moduleLoader) moduleLoader.load({
           ),
           h('span', { className: 'dsh-autorestart-settings__hint' }, t('settings.seconds.hint')),
         ),
+        h(
+          'label',
+          { className: 'dsh-autorestart-settings__field' },
+          h('span', { className: 'dsh-autorestart-settings__label' }, t('settings.grace.label')),
+          h(
+            'select',
+            {
+              className: 'dsh-autorestart-settings__select',
+              value: String(graceSeconds),
+              disabled: busy,
+              'data-dsh-autorestart-setting': 'restartGraceMs',
+              onChange: (event) => {
+                const value = Number(event && event.target ? event.target.value : NaN)
+                if (!Number.isFinite(value) || value === graceSeconds) return
+                void save({ restartGraceMs: value * 1000 })
+              },
+            },
+            GRACE_CHOICES_SECONDS.map((choice) => h(
+              'option',
+              { key: String(choice), value: String(choice) },
+              choice === 0
+                ? t('settings.grace.immediate')
+                : fill(t('settings.grace.value'), { n: choice }),
+            )),
+          ),
+          h('span', { className: 'dsh-autorestart-settings__hint' }, t('settings.grace.hint')),
+        ),
         h(
           'label',
           { className: 'dsh-autorestart-settings__field' },
@@ -2873,6 +2991,14 @@ if (moduleLoader) moduleLoader.load({
       if (phase === 'waiting') {
         ensureSleepStyle()
         const blockers = status && Array.isArray(status.blockers) ? status.blockers : []
+        // A pending restart is not a task: it is what the shutdown waits for,
+        // so it is never counted as one.
+        const tasks = blockers.filter((entry) => !isRestartPending(entry))
+        // How many of the blockers are subagents: the card says so, so the
+        // count is not read as "that many conversations".
+        const subagentCount = tasks.filter(
+          (entry) => entry && entry.kind === 'subagent',
+        ).length
         return h(
           'div',
           {
@@ -2886,23 +3012,35 @@ if (moduleLoader) moduleLoader.load({
           h('p', { className: 'dsh-autorestart-sleep-waiting__title' }, t('sleep.waiting.title')),
           h('p', { className: 'dsh-autorestart-sleep-waiting__body' }, t('sleep.waiting.body')),
           blockers.length === 0
-            ? h('p', { className: 'dsh-autorestart-sleep-waiting__none' }, t('sleep.waiting.none'))
+            ? h(
+              'p',
+              { className: 'dsh-autorestart-sleep-waiting__none' },
+              // The Host's own message explains WHY the machine waits (the
+              // grace window for work this plugin cannot see); the generic
+              // line is only the fallback.
+              typeof status.message === 'string' && status.message !== ''
+                ? status.message
+                : t('sleep.waiting.none'),
+            )
             : h(
               'ul',
               { className: 'dsh-autorestart-sleep-waiting__list' },
               blockers.map((entry, index) => h(
                 'li',
                 { key: 'blocker-' + index },
-                fill(t('sleep.waiting.blocker'), {
-                  title: entry && typeof entry.title === 'string' && entry.title !== ''
-                    ? entry.title
-                    : t('panelBlockedGeneric'),
-                }),
+                blockerLine(entry),
               )),
             ),
-          h('p', { className: 'dsh-autorestart-sleep-waiting__count' }, blockers.length === 0
+          h('p', { className: 'dsh-autorestart-sleep-waiting__count' }, tasks.length === 0
+            ? null
+            : fill(t('sleep.waiting.count'), { n: tasks.length })),
+          subagentCount === 0
             ? null
-            : fill(t('sleep.waiting.count'), { n: blockers.length })),
+            : h(
+              'p',
+              { className: 'dsh-autorestart-sleep-waiting__subagents' },
+              fill(t('sleep.waiting.subagents'), { k: subagentCount }),
+            ),
           errorLine(),
           h(
             'button',

package/cordis.patch.yml

@@ -25,6 +25,14 @@
         relaunchDelaySeconds: 2
         # quiet window (ms) after the last conversation activity before a restart may fire
         settleMs: 2000
+        # Grace window (ms): the extra wait after the LAST conversation finished,
+        # before the host is really restarted or switched off. This plugin can
+        # only see the DSH agents — other plugins (a memory plugin that writes
+        # its notes a few seconds later, a summary, an MCP callback) queue
+        # their work with a timer of their own, and that work is invisible
+        # here. A DROPDOWN in the settings page: 0 / 3 / 5 / 10 / 20 / 30
+        # seconds. `0` means "no extra wait" (the behaviour of 0.4.0).
+        restartGraceMs: 10000
         # dsh web: reload the page when the host boot token changes
         autoReloadPage: true
         # hard-block shell commands that would kill/relaunch DSH by hand

package/docs/README.zh.md

@@ -18,7 +18,7 @@
 - 多个会话同时要求重启时合并成一次，且每个请求者都会被唤醒；
 - 带 goal 的会话不会把重启卡死：重启前自动**解除（disarm）**它的 goal（当前那一轮照常跑完，什么都不丢），重启之后自动重新上链；
 - 重启前有两道检查：宿主侧查一次，独立 helper 在杀进程前再查一次；
-- 界面上能看到状态：输入框工具行左侧的"待重启 · 被 N 个会话占用"小胶囊、左侧栏会话标题旁的圆点；快重启时圆点呼吸，点胶囊看详情；
+- 界面上能看到状态：输入框工具行左侧的"待重启 · 等待 N 个任务结束"小胶囊、左侧栏会话标题旁的圆点；快重启时圆点呼吸，点胶囊看详情；
 - 可配置：静默窗口（默认 2 秒）、杀进程前等待（默认 2 秒）、忙碌时是否允许强制重启等。
 - 同一套"等到大家都安静"的想法还做成了**收工关机**：左侧栏最底部（设置按钮旁边）一个月亮按钮 → 等所有会话收工 → 屏幕上倒数（一张浮动卡片：大字 + 鲸鱼娘）→ **关掉整台电脑**（见「收工关机」）。
 
@@ -134,7 +134,7 @@ agent/status(running) ──► 写 checkpoint（<DSH_HOME>\storages\dsh-autores
 
 ## 安装
 
-当前版本：**0.5.0**。
+当前版本：**0.6.0**。
 
 ```powershell
 # 在 dsh 里（或对 Agent 说）：把工作区里的这个包安装为 profile bundle
@@ -169,6 +169,7 @@ dsh plugin --profile desktop add C:\path\to\dsh-autorestart
 | `restartCommand` | `''` | 自定义重启命令，支持 `{pid}` `{ppid}` `{app}` 占位符 |
 | `relaunchDelaySeconds` | `2` | 脱离的 helper 在杀掉应用**之前**等几秒（`ping -n 3`，约 2 秒） |
 | `settleMs` | `2000` | 静默窗口（ms）：最后一次会话活动之后，宿主要安静这么久，重启才允许开始 |
+| `restartGraceMs` | `10000` | 宽限期（ms）：最后一个会话收工后，再等这么久才真正重启/关机——**下拉框：0 / 3 / 5 / 10 / 20 / 30 秒**，默认 10；`0` = 不额外等 |
 | `autoReloadPage` | `true` | `dsh web`：host 重启（bootId 变化）后让页面自动 reload |
 | `blockManualRestart` | `true` | 硬拦截 agent 用 shell 命令手动杀掉/重启 DSH，并引导到 `continuum_restart` |
 | `healthPath` | `/__dsh_autorestart/health` | 健康检查路由（返回 bootId/pid/phase/自检标志） |
@@ -181,6 +182,18 @@ dsh plugin --profile desktop add C:\path\to\dsh-autorestart
 | `sleepCountdownSeconds` | `20` | 收工关机在真正关机前倒数几秒——**下拉框：0 / 10 / 20 / 30 / 60 秒**，默认 20；`0` 表示**不倒数、立即关机**（仍会先等所有会话收工） |
 | `sleepCommand` | `''` | 收工关机的自定义关机命令；留空 = 自动识别宿主（Windows 用 `cmd.exe /c …`，其它平台用 `/bin/sh -c …`） |
 
+### 为什么收工后还要多等几秒
+
+**我们只看得到 DSH 的会话。** 这个插件知道的是：某个会话还在不在跑、有没有排队的 inbox 消息、最后一个是什么时候闲下来的。它**看不到别的插件用定时器排队的活** —— 比如记忆插件在会话结束后过几秒才把这次对话写进记忆、比如一次总结、一次 MCP 回调、一次日志落盘。对我们来说这些活是不存在的，所以「所有 agent 都闲了」并不等于「现在真的没有事情在发生」。
+
+**宽限期就是为这件事留的。** `restartGraceMs`（默认 **10 秒**）的意思是：**最后一个会话收工后，再额外等这么久，才真正重启 / 关机**。这是一层普通的、可配置的保险，**不针对任何具体插件**。
+
+- **两条路都守它**：重启闸门等的是 `max(settleMs, restartGraceMs)` 的安静；收工关机也在**开始倒数之前**先等满这个宽限期（所以宽限期不会把已经在走的倒计时顶回去一轮）。
+- **等待期间又有活，重新计时**：宽限期永远跟着「最后一次活动」走 —— 会话又开始干活，就从那一刻重新等。
+- **`0` 就是「和以前一样」**：`restartGraceMs: 0` 时行为与 0.4.0 完全一致。
+- **在哪改**：设置 → 自动重启与关机 → 「收工后再等几秒（给记忆/总结类插件留时间）」。
+- **怎么排障**：状态接口都带着它 —— `GET /health?state=1`、`GET /health?gate=1`、`continuum_status`、`GET /sleep` 都会报 `graceMs`（配了多宽限期）和 `quietForMs`（已经安静了多久）。
+
 ## Agent 工具与"它怎么知道该用插件"
 
 | 工具 | 作用 |
@@ -228,6 +241,45 @@ dsh plugin --profile desktop add C:\path\to\dsh-autorestart
 
 **点一下就够了。** 月亮按钮按下就武装：宿主等所有忙会话收工，在角落里倒数 **20 秒**（浮动卡片，不遮挡界面），然后关掉整台机器。**再点一下**（或点卡片上的「算了，别关」）就取消。除此之外什么都不用用户做：没有确认框、不用点第二次。
 
+### 关机和重启谁先谁后
+
+**一句话版本。** 点月亮按钮的意思是「**等活干完了再关电脑**」，不是「现在就算还有别的在跑也关掉」。所以：
+
+1. **有待重启时，关机先让路。** 队列里还有一次重启没执行时，**不会关机** —— 卡片上写的是「等这次重启完成后再关机」。先重启，会话跟着回来继续干活，等它们都收工了，机器才关。
+2. **重启之后活还在继续。** 跟着重启回来的会话是在干活的：只要还有会话在忙，关机就一直等；**所有**会话都空了才关。
+3. **关机的意图跨重启保留。** 你只按了**一次**按钮。重启不会把这个请求吃掉：它被写进检查点文件，新进程启动后接着等那些活 —— **你不需要再点一次**。
+4. **随时可以反悔。** 等待卡片上有「不关了」按钮（再点一次月亮按钮也行）：一按，这个意图就彻底没了。
+
+**意图存在哪。** 检查点文件（`<DSH_HOME>/storages/dsh-autorestart/state.json`）里的 `sleep: { armed, armedAt, countdownSeconds }`。机器关掉、关机命令没跑起来、或者你点了「不关了」，它都会被清掉。**记录坏掉就直接丢弃** —— 宁可让你再点一次，也不能因为半截文件让机器永远自己关自己。
+
+**排障用。** `GET /sleep` 会报 `armedAt`（什么时候点的关机），旁边还有 `phase`、`blockers`、`graceMs`。
+
+### 故障排查：点了没关机
+
+**下面是真实宿主返回的东西**（文案是中文，字段名不是）：
+
+```
+POST /__dsh_autorestart/sleep {"action":"arm"}   # 有 3 个会话在干活
+→ phase=waiting  armed=true  remainingMs=20000（满值＝没开始倒数）
+  message: 等 3 个任务收工，收工后开始倒数。
+
+# 制造一个待执行的重启之后：
+GET /__dsh_autorestart/sleep
+→ phase=waiting  armed=true  remainingMs=20000
+  message: 等这次重启完成后再关机……
+  blockers: [{"sessionId":"restart-pending","kind":"restart-pending",
+              "label":"待执行的重启","name":"待执行的重启"}]
+```
+
+**`remainingMs` 是满值 = 倒数还没开始**，也就是机器在等什么东西。下面是可能的原因，以及该怎么办：
+
+1. **还有任务在跑。** `blockers[]` 列的就是它们，看 `kind`：`session` 是会话，`subagent` 是某个会话派出去的子智能体。**子智能体也算在干活，这是故意的** —— 否则重启会把它掐断。**怎么办：** 等它干完，或者把那个会话停掉；列表会自己变短。
+2. **有待执行的重启。** `kind` 是 `restart-pending`（`label`/`name` 都是 `待执行的重启`）。这是正常排队，不是故障：先重启，会话跟着回来，完事之后倒数自动接着走。**怎么办：** 不用管，等重启完即可（也可以用 `continuum_cancel_restart` 把这次重启取消掉）。
+3. **刚收工，还在宽限期里**（默认 10 秒，给记忆/总结类插件留落盘时间）。**你会看到：** `graceMs` 是配的窗口，`quietForMs` 是宿主已经安静了多久。**怎么办：** 等着；等待期间又有会话开始干活，计时会重新开始（这就是这个窗口的意义）。不想要这段等待就在设置里把它调成 `0`。
+4. **倒数期间又有会话开始干活。** 倒数退回「等待」，`remainingMs` 变回满值。**你会看到：** 消息里说又有谁开始干活了，`blockers[]` 列着是谁。**怎么办：** 等他们干完。
+5. **想看「到底等谁」。** `continuum_status` 的 `blockedBy[]` 和 `GET /sleep` 的 `blockers[]` 是**同一份数据**（前者给 agent 看，后者给脚本看）。每条都有 `kind`（它是什么）、`label`（会话标题）、`name`（完整称呼，比如「写代码的会话的子智能体」）。标题解析不到时 `label` 是 `null`、`name` 是空字符串 —— 这时候等待那句话就只说「等 3 个任务收工」，不带名字列表。
+6. **彻底不想关了。** 等待卡片上的取消按钮（或者再点一次月亮按钮，或者 `POST /sleep {"action":"cancel"}`）会把这个意图彻底清掉：`armed` 变回 `false`，`armedAt` 变回 `null`。
+
 **桌面端和 web 端行为完全一致。** 没有票据、没有额外请求头、没有隐藏模式：`POST /__dsh_autorestart/sleep` 只带一个动作，两端走的是同一条路由。脚本（或者 agent）同样可以驱动它：
 
 ```bash
@@ -519,8 +571,9 @@ or by requesting the health path with ?gate=1.
 
 - 胶囊渲染在**输入框工具行左侧**（`conversation.input.left` 槽位），是一个高度约 22px 的小胶囊，**不额外占一行**（不再是输入框上方的一整行）。
 - 只有当健康路由 `/__dsh_autorestart/health?state=1` 返回 `pendingRestart: true` **且**本会话 id 出现在 `waiters` 列表里时才会出现；别的会话等待重启时你看不到它。
-- 文案有多种状态：还有别的会话占着时显示「待重启 · 被 N 个会话占用」；都空闲时显示「待重启 · 空闲后自动重启」；被某个会话**自动续跑的 goal** 占着时显示「待重启 · 被某个会话自动续跑的 goal 占着」（见下面的升级 3）。
-- 悬停提示（原生 `title`）：「等待其他会话空闲后自动重启；重启后会自动继续本会话进度」。
+- 文案有多种状态：还有别的**任务**占着时显示「待重启 · 等待 N 个任务结束」；都空闲时显示「待重启 · 空闲后自动重启」；被某个**自动续跑的 goal** 占着时显示「待重启 · 被某个自动续跑的 goal 占着」（见下面的升级 3）。
+- 悬停提示（原生 `title`）：「等待其他任务结束（计数含"排队但还没开始"的任务）后自动重启；重启后会自动继续本会话进度」。
+- **每个占用者都说清自己是什么**：普通会话用它自己的标题；**子智能体**用"创建它的那个会话"的标题来称呼（显示成「子智能体（那个会话）」）。**原始的 `session-xxxx` 永远不会推给界面** —— 取不到标题时用一个通用说法。
 - 颜色走**品牌色（蓝紫）** `var(--dsw-alias-brand-primary, #5b8def)`，**不再用告警黄（warning）色**：胶囊里的小圆点和侧边栏圆点都是品牌色，胶囊边框保持中性（`--dsw-alias-border-l1`），文字保持中性。
 - 左侧边栏会话行的**行首 16px 状态格**里也会出现一个同款 8px 圆点（`sidebar.session.row.leading` 槽位，id `autorestart-restart-dot`，order 20）：纯图标，完整说明放在悬停 `title` 里，aria-label 为「待重启」/「Pending restart」。
 - 那个 16px 状态格会被**优先级更高的行状态**（ask / 未读 / 运行中）替换，所以圆点只在该行**空闲**时出现。
@@ -572,8 +625,12 @@ or by requesting the health path with ?gate=1.
 }
 ```
 
-- `blockedBy[]` 的每一项在原有字段（`sessionId`、`reason`）之外，可能多一个**可选的 `title`**：Host 会尽力从会话控制器（`ctx.get('sessionController').list({})`）里读出该会话的标题。
-- 这是**尽力而为**：查不到标题就**不带 `title` 字段**，原有字段和行为完全不变；会话控制器缺失、抛错或没有标题都**不会**让这条路由失败。
+- `blockedBy[]` 的每一项在原有字段（`sessionId`、`reason`）之外，还带两个字段：
+  - `kind`：`"session"` 或 `"subagent"` —— 这个占用者是普通会话还是**子智能体**（子智能体用 `agent.origin === 'subagent'` 判定；分叉会话的 `origin` 为空，仍然是普通会话）。
+  - `label`：**它该被怎么称呼** —— 普通会话用自己的标题；子智能体用「创建它的那个会话」的标题（所以界面显示成「子智能体（那个会话）」）。取不到就是 `null`，界面改用通用说法。
+  - 另外还有 `name`（完整的称呼，如「写代码的会话的子智能体」）、`parentTitle` / `parentSessionId`（子智能体的父会话）、`title`（`label` 的旧名字，保留给老客户端）。
+- 这些字段是**尽力而为**：会话控制器缺失、抛错或没有标题都**不会**让这条路由失败，只是 `label` 为 `null`；**原始的 `session-xxxx` 永远不会被当成名字推给界面**。
+- 标题查询结果会缓存约 **5 秒**（客户端每 2 秒轮询一次，不会把会话列表打成风暴）。
 - 标题查询结果会缓存约 **5 秒**（客户端每 2 秒轮询一次，不会把会话列表打成风暴）。
 - `blockedBy[]` 里的 `reason` 可能是 **goal 相关**的：`goal-active`（持有一个会自动续跑的已武装 goal）、`goal-exhausted`（goal 的轮次额度用完，无法继续）等；此时原本的占用原因保留在 `busyReason` 里。
 - `parkUrl` 是停泊路由的绝对路径（由配置的 `healthPath` 前缀推导），客户端优先用它，而不是自己猜路径。