dsh-autorestart 0.5.0 → 0.6.1

package/index.js

@@ -24,8 +24,10 @@ import os from 'node:os'
 import path from 'node:path'
 
 import {
+  armSleep,
   beginBoot,
   cancelRestart,
+  clearSleep,
   disarmedRecord,
   entryFor,
   handoffRecord,
@@ -73,6 +75,7 @@ import {
   runCommandNow,
   scheduleDetachedRestart,
 } from './lib/restart.js'
+import { compareSemver } from './lib/semver.js'
 import {
   createSleepController,
   COUNTDOWN_CHOICES,
@@ -83,6 +86,47 @@ import {
   snapCountdownChoice,
 } from './lib/sleep.js'
 
+/**
+ * The grace window: how long the host waits after the LAST conversation
+ * finished before it 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 after the conversation ended, a summary,
+ * an MCP callback) queue their work with a timer of their own — work that is
+ * invisible here. A short, configurable grace window is left for it.
+ *
+ * The values are the ones the settings page offers (in milliseconds).
+ */
+const GRACE_CHOICES_MS = Object.freeze([0, 3000, 5000, 10000, 20000, 30000])
+
+/** The grace window that is used when nothing was configured. */
+const DEFAULT_GRACE_MS = 10000
+
+/**
+ * Snap a grace value onto the nearest offered choice.
+ *
+ * A profile that carries a value that is not offered (a hand-edited row, an
+ * older build) must not break the boot: the value is snapped onto the
+ * nearest choice, exactly like the countdown length is.
+ *
+ * @param {unknown} value
+ * @returns {number} one of {@link GRACE_CHOICES_MS}
+ */
+function snapGraceChoice(value) {
+  const raw = Number(value)
+  if (!Number.isFinite(raw) || raw < 0) return DEFAULT_GRACE_MS
+  let best = GRACE_CHOICES_MS[0]
+  let bestDistance = Math.abs(raw - best)
+  for (const choice of GRACE_CHOICES_MS) {
+    const distance = Math.abs(raw - choice)
+    if (distance < bestDistance) {
+      best = choice
+      bestDistance = distance
+    }
+  }
+  return best
+}
+
 /**
  * The version of this plugin, as a fallback.
  *
@@ -90,17 +134,36 @@ import {
  * `pluginVersion()`), but a bundled installation may not ship that file — so
  * the constant below is the last resort. A test keeps the two in sync.
  */
-const PLUGIN_VERSION_FALLBACK = '0.5.0'
+const PLUGIN_VERSION_FALLBACK = '0.6.1'
+
+/**
+ * The version of the graceful-shutdown FEATURE, not the version of the package.
+ *
+ * The one-time announcement is bound to this constant. It used to follow the
+ * version in package.json, and that made every release resurrect the card the
+ * user had already answered (0.5.0 -> 0.6.1 brought "收工关机" back). A release
+ * is not news about the feature, so the two are decoupled.
+ *
+ * WHEN TO RAISE IT: 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 to another place, ...). Any new value works: the
+ * recorded version no longer matches, so the announcement is shown once more.
+ *
+ * WHEN NOT TO RAISE IT: a release, a bug fix, a small addition, a new option
+ * that the documentation explains. None of those deserve a card that
+ * interrupts the user a second time.
+ */
+const SLEEP_FEATURE_VERSION = '0.5.0'
 
 /** The cached version of this plugin (read once per process). */
 let pluginVersionCache = null
 
 /**
- * The version of this plugin.
+ * The version of this plugin (the PACKAGE version).
  *
- * It is the version of the package itself: the feature announcements are
- * bound to it, so a new version of the plugin can announce a new feature (and
- * the announcement of an old version never comes back).
+ * It says which release is installed - not what the user has been told about.
+ * The feature announcements are bound to `SLEEP_FEATURE_VERSION`, so a release
+ * never brings an answered announcement back.
  *
  * @returns {string}
  */
@@ -126,19 +189,51 @@ function pluginVersion() {
  *
  * The install prompt only ever reaches a fresh installation, so an
  * installation that already existed would never learn about a new feature.
- * Every entry of this list is therefore announced once per version: the
- * announcement is shown until the user presses "知道了", and the Host records
- * the version it has shown, so it never comes back.
+ * Every entry of this list is therefore announced once per FEATURE version:
+ * the announcement is shown until the user presses "知道了", and the Host
+ * records the feature version it has shown, so it never comes back.
+ *
+ * The version of an entry is the version of the FEATURE, never the version of
+ * the package - see `SLEEP_FEATURE_VERSION`.
  *
  * @returns {{ feature: string, version: string }[]}
  */
 function featureAnnouncements() {
   return [
     // The graceful shutdown ("收工关机") and its moon button.
-    { feature: 'sleep', version: pluginVersion() },
+    { feature: 'sleep', version: SLEEP_FEATURE_VERSION },
   ]
 }
 
+/**
+ * Whether the user has already seen the announcement of one feature.
+ *
+ * The record is the version that was announced when the user answered. It
+ * counts as seen as soon as it is NOT OLDER than the current feature version
+ * - not only when it is exactly that version:
+ *
+ *   - the announcement used to carry the version of the PACKAGE, so a user
+ *     who answered it on the release 0.6.1 recorded "0.6.1" while the feature
+ *     itself stands at "0.5.0". With an equality check that record would
+ *     look stale, and the very same card would be shown to a user who already
+ *     dismissed 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.
+ *
+ * A missing record counts as NOT seen: a missing record must never swallow an
+ * announcement.
+ *
+ * @param {unknown} recorded the version in the state file
+ * @param {string} current the current feature version
+ * @returns {boolean} true when the user has seen it
+ */
+function isFeatureSeen(recorded, current) {
+  if (typeof recorded !== 'string' || recorded.trim() === '') return false
+  const order = compareSemver(recorded, current)
+  if (order === null) return true
+  return order >= 0
+}
+
 /**
  * `@deepseek-ai/schemastery` resolves inside modules that live in the dsh installation,
  * but NOT from this bundle: a profile-installed bundle is a symlink into the user's
@@ -281,6 +376,12 @@ function buildConfigSchema() {
       // quiet window that must pass after the last conversation activity
       settleMs: schemastery.number().min(0).default(2000)
         .description('Milliseconds the host must stay quiet after the last conversation activity before a restart may fire.'),
+      // The grace window: the extra wait after the last conversation finished.
+      // Other plugins queue work with timers of their own (a memory plugin
+      // writing its notes, a summary, an MCP callback) and that work is
+      // invisible here — so a short, configurable grace window is left for it.
+      restartGraceMs: schemastery.number().min(0).default(DEFAULT_GRACE_MS)
+        .description('Milliseconds to wait after the last conversation finished before the host is really restarted or switched off: the grace window for work other plugins queue with a timer (0 / 3 / 5 / 10 / 20 / 30 seconds, default 10).'),
       autoReloadPage: schemastery.boolean().default(true)
         .description('Reload the web page automatically when the host boot token changes.'),
       blockManualRestart: schemastery.boolean().default(true)
@@ -347,6 +448,7 @@ const DEFAULTS = {
   restartCommand: '',
   relaunchDelaySeconds: 2,
   settleMs: 2000,
+  restartGraceMs: DEFAULT_GRACE_MS,
   autoReloadPage: true,
   blockManualRestart: true,
   healthPath: '/__dsh_autorestart/health',
@@ -393,6 +495,9 @@ function normalizeConfig(raw) {
   // profile that still carries an old value (15, 45, …) is snapped onto the
   // nearest one instead of breaking, and 0 means "no countdown at all".
   config.sleepCountdownSeconds = snapCountdownChoice(config.sleepCountdownSeconds)
+  // The grace window is one of the offered choices as well: a hand-edited
+  // profile value is snapped onto the nearest one instead of breaking.
+  config.restartGraceMs = snapGraceChoice(config.restartGraceMs)
   if (typeof config.sleepCommand !== 'string') config.sleepCommand = ''
   if (typeof config.showSleepButton !== 'boolean') config.showSleepButton = true
   return config
@@ -673,7 +778,7 @@ const INSTALL_CHOICE_FILE = 'install-choice.json'
  * Read the recorded install choice from the fallback file.
  *
  * @param {string} stateDir
- * @returns {{ includePlugins: boolean|null, backupOnRestart: boolean|null, showSleepButton: boolean|null, sleepCountdownSeconds: number|null }|null}
+ * @returns {{ includePlugins: boolean|null, backupOnRestart: boolean|null, showSleepButton: boolean|null, sleepCountdownSeconds: number|null, restartGraceMs: number|null }|null}
  */
 function readInstallChoice(stateDir) {
   try {
@@ -687,6 +792,7 @@ function readInstallChoice(stateDir) {
       sleepCountdownSeconds: typeof parsed.sleepCountdownSeconds === 'number'
         ? parsed.sleepCountdownSeconds
         : null,
+      restartGraceMs: typeof parsed.restartGraceMs === 'number' ? parsed.restartGraceMs : null,
     }
   } catch {
     return null
@@ -700,7 +806,7 @@ function readInstallChoice(stateDir) {
  * erase the recorded backup scope (and the other way round).
  *
  * @param {string} stateDir
- * @param {{ includePlugins?: boolean, backupOnRestart?: boolean, showSleepButton?: boolean, sleepCountdownSeconds?: number }} values
+ * @param {{ includePlugins?: boolean, backupOnRestart?: boolean, showSleepButton?: boolean, sleepCountdownSeconds?: number, restartGraceMs?: number }} values
  * @returns {string} the file that was written
  */
 function writeInstallChoice(stateDir, values) {
@@ -710,6 +816,7 @@ function writeInstallChoice(stateDir, values) {
     backupOnRestart: null,
     showSleepButton: null,
     sleepCountdownSeconds: null,
+    restartGraceMs: null,
   }
   const payload = {
     includePlugins: typeof values.includePlugins === 'boolean' ? values.includePlugins : current.includePlugins,
@@ -718,6 +825,9 @@ function writeInstallChoice(stateDir, values) {
     sleepCountdownSeconds: typeof values.sleepCountdownSeconds === 'number'
       ? values.sleepCountdownSeconds
       : current.sleepCountdownSeconds,
+    restartGraceMs: typeof values.restartGraceMs === 'number'
+      ? values.restartGraceMs
+      : current.restartGraceMs,
     at: new Date().toISOString(),
   }
   fs.mkdirSync(stateDir, { recursive: true })
@@ -1143,9 +1253,89 @@ export function createRuntime(ctx, config, options = {}) {
     return count
   }
 
+  /**
+   * Whether this agent is a subagent (a delegated child), and which session
+   * created it.
+   *
+   * The origin is the ONLY reliable marker: a forked session also carries a
+   * parent session, but it is a top-level conversation, not a subagent.
+   *
+   * @param {any} agent
+   * @returns {string|null} the parent session id, or null when this is not a
+   *   subagent
+   */
+  const subagentParentOf = (agent) => {
+    try {
+      if (!agent || typeof agent !== 'object') return null
+      const session = agent.session && typeof agent.session === 'object' ? agent.session : null
+      const header = session && session.header && typeof session.header === 'object' ? session.header : null
+      const origin = agent.origin != null ? agent.origin : (header ? header.origin : undefined)
+      if (origin !== 'subagent') return null
+      const parent = agent.parentId != null
+        ? agent.parentId
+        : agent.parentSessionId != null
+          ? agent.parentSessionId
+          : (header ? header.parentSession : undefined)
+      if (parent == null || parent === '') return null
+      return String(parent)
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * The readable identity of one blocker: WHAT it is (a session or a
+   * subagent) and HOW it is called.
+   *
+   * A subagent has no title of its own, so it is named after the session that
+   * created it ("<that session>'s subagent"). A raw session id never reaches
+   * the interface: an unknown name is a generic one.
+   *
+   * @param {string} sessionId
+   * @param {any} agent
+   * @returns {{ kind: 'session'|'subagent', label: string|null, name: string, parentTitle: string|null, parentSessionId: string|null }}
+   */
+  const describeBlocker = (sessionId, agent) => {
+    const parent = agent ? subagentParentOf(agent) : null
+    if (parent === null) {
+      let title = null
+      try { title = sessionTitle(sessionId) } catch { /* a missing title is not a problem */ }
+      const label = title ? String(title) : null
+      return {
+        kind: 'session',
+        // The label is the title of the session itself.
+        label,
+        // The full name of the blocker: its title — or NOTHING when it has no
+        // title. A generic name ("会话") says nothing and would end up in the
+        // interface as "会话「会话」" or as a list of three identical
+        // entries; the client decides what to write when the name is empty.
+        name: label || '',
+        parentTitle: null,
+        parentSessionId: null,
+      }
+    }
+    let parentTitle = null
+    try { parentTitle = sessionTitle(parent) } catch { /* a missing title is not a problem */ }
+    const title = parentTitle ? String(parentTitle) : null
+    return {
+      kind: 'subagent',
+      // The label is the title of the session that created it: the UI shows
+      // "子智能体（<that title>）".
+      label: title,
+      // The full name of the blocker: "<that session>'s subagent".
+      name: title ? `${title}的子智能体` : '子智能体',
+      parentTitle: title,
+      parentSessionId: parent,
+    }
+  }
+
   /**
    * Every conversation that is still working, subagents and teammates included.
    * 'running' is a live turn; 'queued' is inbox work that has not started yet.
+   *
+   * Every entry carries the kind of the blocker and a readable name, so the
+   * interface can tell a session from a subagent and never has to show a raw
+   * session id.
    */
   const busyAgents = () => {
     const out = []
@@ -1158,8 +1348,10 @@ export function createRuntime(ctx, config, options = {}) {
     for (const agent of agents) {
       try {
         if (!agent || !agent.id) continue
-        if (agent.status === 'running') out.push({ sessionId: String(agent.id), reason: 'running' })
-        else if (pendingInboxCount(agent) > 0) out.push({ sessionId: String(agent.id), reason: 'queued' })
+        const sessionId = String(agent.id)
+        const described = describeBlocker(sessionId, agent)
+        if (agent.status === 'running') out.push({ sessionId, reason: 'running', ...described })
+        else if (pendingInboxCount(agent) > 0) out.push({ sessionId, reason: 'queued', ...described })
       } catch {}
     }
     return out
@@ -1492,12 +1684,41 @@ export function createRuntime(ctx, config, options = {}) {
 
   const anyAgentRunning = () => busyAgents().length > 0
 
-  /** The two-layer restart gate: no busy conversation AND a quiet settle window. */
+  /**
+   * Whether a restart is still pending.
+   *
+   * A pending restart goes FIRST: the graceful shutdown waits for it — and for
+   * the sessions that resume with it. The shutdown intent survives the
+   * restart, so the machine goes off after everything is done.
+   *
+   * @returns {boolean}
+   */
+  const pendingRestart = () => state.restart !== null && state.restart !== undefined
+
+  /** How long the host has been quiet (no conversation activity at all). */
+  const quietForMs = () => Math.max(0, Date.now() - lastActivityAt)
+
+  /**
+   * The grace window: how much longer the host waits 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.
+   */
+  const graceMs = () => config.restartGraceMs
+
+  /**
+   * The quiet window the restart gate really uses.
+   *
+   * It is the settle window, but never shorter than the grace window: the
+   * grace is the *extra* wait on top of the settle, not a replacement.
+   */
+  const effectiveSettleMs = () => Math.max(config.settleMs, config.restartGraceMs)
+
+  /** The two-layer restart gate: no busy conversation AND a quiet window. */
   const gate = () => restartGate(state, {
     busyAgents: busyAgents(),
     lastActivityAt,
     now: Date.now(),
-    settleMs: config.settleMs,
+    settleMs: effectiveSettleMs(),
   })
 
   /**
@@ -1512,7 +1733,43 @@ export function createRuntime(ctx, config, options = {}) {
    */
   const titleCache = { at: 0, titles: new Map(), inFlight: false }
 
-  /** Store the titles of one session-list answer. Never throws. */
+  /**
+ * The title of one row of the session list.
+ *
+ * The title is a PROJECTION: the summary row carries it under
+ * `projections.values.title` (the same place `dsh-session-reference` reads it
+ * from), not under a `title` field of its own. A plain `title`/`name` is
+ * accepted too, so a list with a different shape still works.
+ *
+ * @param {any} item one row of the session list
+ * @returns {string} the title, or '' when the row carries none
+ */
+const titleOfSummary = (item) => {
+  try {
+    if (!item || typeof item !== 'object') return ''
+    const projections = item.projections && typeof item.projections === 'object'
+      ? item.projections
+      : null
+    const values = projections && projections.values && typeof projections.values === 'object'
+      ? projections.values
+      : null
+    const candidates = [
+      values ? values.title : undefined,
+      item.title,
+      item.name,
+    ]
+    for (const candidate of candidates) {
+      if (typeof candidate !== 'string') continue
+      const title = candidate.trim()
+      if (title !== '') return title
+    }
+    return ''
+  } catch {
+    return ''
+  }
+}
+
+/** Store the titles of one session-list answer. Never throws. */
   const applySessionTitles = (payload) => {
     const items = payload && Array.isArray(payload.items)
       ? payload.items
@@ -1520,9 +1777,13 @@ export function createRuntime(ctx, config, options = {}) {
     const titles = new Map()
     for (const item of items) {
       if (!item || typeof item !== 'object') continue
-      const id = item.id === undefined || item.id === null ? '' : String(item.id)
+      // The session list names its rows `sessionId` (`id` is an older shape).
+      const rawId = item.sessionId !== undefined && item.sessionId !== null
+        ? item.sessionId
+        : item.id
+      const id = rawId === undefined || rawId === null ? '' : String(rawId)
       if (!id) continue
-      const title = typeof item.title === 'string' ? item.title.trim() : ''
+      const title = titleOfSummary(item)
       if (title) titles.set(id, title)
     }
     titleCache.titles = titles
@@ -1813,7 +2074,7 @@ export function createRuntime(ctx, config, options = {}) {
       anyAgentRunning: busy.length > 0,
       busyAgents: busy,
       lastActivityAt,
-      settleMs: config.settleMs,
+      settleMs: effectiveSettleMs(),
       now,
       softMs: config.deferSoftMs,
       hardMs: config.deferHardMs,
@@ -1858,7 +2119,7 @@ export function createRuntime(ctx, config, options = {}) {
    * is unavailable the choice degrades to a file in the plugin's state
    * directory and a warning is logged, so the choice is never silently lost.
    *
-   * @param {{ backupOnRestart?: boolean, backupIncludePlugins?: boolean, showSleepButton?: boolean, sleepCountdownSeconds?: number }} changes
+   * @param {{ backupOnRestart?: boolean, backupIncludePlugins?: boolean, showSleepButton?: boolean, sleepCountdownSeconds?: number, restartGraceMs?: number }} changes
    * @returns {Promise<{ applied: 'config'|'fallback-file' }>}
    */
   const persistConfigChoice = async (changes) => {
@@ -1883,6 +2144,10 @@ export function createRuntime(ctx, config, options = {}) {
       wanted.sleepCountdownSeconds = changes.sleepCountdownSeconds
       fallback.sleepCountdownSeconds = changes.sleepCountdownSeconds
     }
+    if (typeof changes.restartGraceMs === 'number') {
+      wanted.restartGraceMs = changes.restartGraceMs
+      fallback.restartGraceMs = changes.restartGraceMs
+    }
     const editor = resolveConfigEditor(ctx)
     if (editor !== null) {
       try {
@@ -1919,11 +2184,16 @@ export function createRuntime(ctx, config, options = {}) {
   /**
    * The feature announcements the user has not seen yet.
    *
-   * A feature is pending when the recorded version is not the current one: a
-   * user who has seen the announcement of version 0.5.0 never sees it again,
-   * and a user who upgrades to a newer version sees the announcement of that
-   * version. A feature without a record is always pending — a missing record
-   * must never swallow an announcement.
+   * A feature is pending when the recorded version is OLDER than the current
+   * one: a user who has seen the announcement of the feature version 0.5.0
+   * never sees it again - not with the next release of the plugin, because
+   * the announcement follows the FEATURE and not the package. A user who
+   * answered the card on an intermediate release (the announcement used to
+   * carry the package version) has seen it as well: a record that is not
+   * older than the current version never brings the card back.
+   *
+   * A feature without a record is always pending - a missing record must
+   * never swallow an announcement.
    *
    * @returns {{ feature: string, version: string }[]}
    */
@@ -1931,7 +2201,7 @@ export function createRuntime(ctx, config, options = {}) {
     const seen = state.seenFeatureVersions && typeof state.seenFeatureVersions === 'object'
       ? state.seenFeatureVersions
       : {}
-    return featureAnnouncements().filter((entry) => seen[entry.feature] !== entry.version)
+    return featureAnnouncements().filter((entry) => !isFeatureSeen(seen[entry.feature], entry.version))
   }
 
   /**
@@ -2074,6 +2344,31 @@ export function createRuntime(ctx, config, options = {}) {
     stopPolling,
     tick,
     anyAgentRunning,
+    /**
+     * Whether a restart is still pending (the graceful shutdown waits for it).
+     *
+     * @returns {boolean}
+     */
+    pendingRestart,
+    /**
+     * How long the host has been quiet (no conversation activity at all).
+     *
+     * @returns {number}
+     */
+    quietForMs,
+    /**
+     * The grace window: the extra wait after the last conversation finished.
+     *
+     * @returns {number} milliseconds
+     */
+    graceMs,
+    /**
+     * The quiet window the restart gate really uses: the settle window, but
+     * never shorter than the grace window.
+     *
+     * @returns {number} milliseconds
+     */
+    effectiveSettleMs,
     executeRestart,
     flushSessions,
     releaseRequesters,
@@ -2782,7 +3077,9 @@ function registerTools(ctx, runtime, config) {
       'Report the dsh-autorestart lifecycle: whether a restart is pending, which sessions were '
       + 'checkpointed as interrupted or continuation-pending, why each blocking session blocks '
       + '("goal-active" = an armed goal keeps it busy, "goal-exhausted" = its goal can no longer be '
-      + 'resumed), the goals this plugin disarmed, the last recovery action/detail per session, '
+      + 'resumed), the goals this plugin disarmed, how long the host has been quiet and how long '
+      + 'the grace window is (the extra wait after the last conversation finished, for work other '
+      + 'plugins queue with a timer), the last recovery action/detail per session, '
       + 'whether a session was handed off to a fresh session (target session id and time) or is over '
       + 'the model context window (such a session is never auto-resumed), whether the pre-restart '
       + 'backup also snapshots the installed plugins (backupIncludePlugins), the '
@@ -2808,7 +3105,33 @@ function registerTools(ctx, runtime, config) {
           pendingRestart: { type: 'boolean' },
           gateAllow: { type: 'boolean' },
           quietForMs: { type: 'number' },
-          blockedBy: { type: 'array', items: { type: 'object' } },
+          graceMs: { type: 'number' },
+          effectiveSettleMs: { type: 'number' },
+          blockedBy: {
+            type: 'array',
+            items: {
+              type: 'object',
+              // Every blocker says WHAT it is (`session` or `subagent`) and
+              // HOW it is called (`label`: the title of the session, or of the
+              // session that created the subagent).
+              //
+              // The title fields are NULLABLE: a session whose title could not
+              // be resolved reports `null`, and a strict schema would reject
+              // the whole tool output for it. The tool schema has no type
+              // arrays, so "string or null" is declared as a `oneOf`.
+              properties: {
+                sessionId: { type: 'string' },
+                reason: { type: 'string' },
+                busyReason: { type: 'string' },
+                kind: { type: 'string', enum: ['session', 'subagent', 'restart-pending'] },
+                label: { oneOf: [{ type: 'string' }, { type: 'null' }] },
+                name: { type: 'string' },
+                parentTitle: { oneOf: [{ type: 'string' }, { type: 'null' }] },
+                parentSessionId: { oneOf: [{ type: 'string' }, { type: 'null' }] },
+                title: { oneOf: [{ type: 'string' }, { type: 'null' }] },
+              },
+            },
+          },
           parkedGoals: { type: 'array', items: { type: 'object' } },
           recovery: { type: 'array', items: { type: 'object' } },
           handoffs: { type: 'array', items: { type: 'object' } },
@@ -2835,6 +3158,10 @@ function registerTools(ctx, runtime, config) {
         pendingRestart: state.restart !== null,
         gateAllow: verdict.allow,
         quietForMs: Math.round(verdict.quietForMs),
+        // The grace window (the extra wait after the last conversation
+        // finished) and the quiet window the gate really uses.
+        graceMs: runtime.graceMs(),
+        effectiveSettleMs: runtime.effectiveSettleMs(),
         blockedBy: blockingDetails(verdict.blockedBy),
         parkedGoals: parkedGoalDetails(),
         recovery: recoveryList(state),
@@ -3564,7 +3891,8 @@ function buildHandoffRoute(ctx, runtime, config) {
  *
  * The record lives in the checkpoint file, so an announcement that was shown
  * once never comes back — not with the next boot and not with the next
- * version of the plugin.
+ * release of the plugin. Only a new FEATURE version (see
+ * `SLEEP_FEATURE_VERSION`) brings it back, on purpose.
  */
 function buildAnnouncementsRoute(ctx, runtime, config) {
   const routePath = resolveAnnouncementsPath(config)
@@ -3682,7 +4010,8 @@ function buildChoiceRoute(ctx, runtime, config) {
         const hasBackup = Object.prototype.hasOwnProperty.call(body, 'backupOnRestart')
         const hasShow = Object.prototype.hasOwnProperty.call(body, 'showSleepButton')
         const hasSeconds = Object.prototype.hasOwnProperty.call(body, 'sleepCountdownSeconds')
-        if (!hasInclude && !hasBackupInclude && !hasBackup && !hasShow && !hasSeconds) {
+        const hasGrace = Object.prototype.hasOwnProperty.call(body, 'restartGraceMs')
+        if (!hasInclude && !hasBackupInclude && !hasBackup && !hasShow && !hasSeconds && !hasGrace) {
           // No key was asked for: there is nothing to persist.
           res.statusCode = 400
           res.setHeader('content-type', 'application/json; charset=utf-8')
@@ -3690,7 +4019,7 @@ function buildChoiceRoute(ctx, runtime, config) {
           res.end(JSON.stringify({
             ok: false,
             error: 'no-choice',
-            instruction: 'Send { "includePlugins": true | false } and/or { "backupIncludePlugins": true | false } and/or { "backupOnRestart": true | false } and/or { "showSleepButton": true | false } and/or { "sleepCountdownSeconds": 0 | 10 | 20 | 30 | 60 }.',
+            instruction: 'Send { "includePlugins": true | false } and/or { "backupIncludePlugins": true | false } and/or { "backupOnRestart": true | false } and/or { "showSleepButton": true | false } and/or { "sleepCountdownSeconds": 0 | 10 | 20 | 30 | 60 } and/or { "restartGraceMs": 0 | 3000 | 5000 | 10000 | 20000 | 30000 }.',
           }))
           return
         }
@@ -3751,6 +4080,17 @@ function buildChoiceRoute(ctx, runtime, config) {
           }))
           return
         }
+        if (hasGrace && GRACE_CHOICES_MS.indexOf(body.restartGraceMs) === -1) {
+          res.statusCode = 400
+          res.setHeader('content-type', 'application/json; charset=utf-8')
+          res.setHeader('cache-control', 'no-store')
+          res.end(JSON.stringify({
+            ok: false,
+            error: 'restartGraceMs-must-be-offered',
+            instruction: `Send { "restartGraceMs": ${GRACE_CHOICES_MS.join(' | ')} }.`,
+          }))
+          return
+        }
         const changes = {}
         // The route field is `includePlugins`, the configuration key is
         // `backupIncludePlugins` (the profile row keeps the plugin's own name).
@@ -3759,6 +4099,7 @@ function buildChoiceRoute(ctx, runtime, config) {
         if (hasBackup) changes.backupOnRestart = body.backupOnRestart === true
         if (hasShow) changes.showSleepButton = body.showSleepButton === true
         if (hasSeconds) changes.sleepCountdownSeconds = body.sleepCountdownSeconds
+        if (hasGrace) changes.restartGraceMs = body.restartGraceMs
         const result = await runtime.applyConfigChoice(changes)
         // The one-time install prompt explained the features to the user, so
         // the announcement of a fresh installation must not follow it.
@@ -3779,6 +4120,7 @@ function buildChoiceRoute(ctx, runtime, config) {
         if (hasBackup) answer.backupOnRestart = body.backupOnRestart === true
         if (hasShow) answer.showSleepButton = body.showSleepButton === true
         if (hasSeconds) answer.sleepCountdownSeconds = body.sleepCountdownSeconds
+        if (hasGrace) answer.restartGraceMs = body.restartGraceMs
         res.statusCode = 200
         res.setHeader('content-type', 'application/json; charset=utf-8')
         res.setHeader('cache-control', 'no-store')
@@ -3816,13 +4158,39 @@ function sleepDryRun() {
  * happened). The sleep feature counts down on screen itself, so it only needs
  * the busy check — and it keeps `settleMs` out of the picture entirely.
  *
+ * The GRACE window is the exception: it is not a settle window but the extra
+ * wait for work this plugin cannot see (a memory plugin writing its notes a
+ * few seconds after the conversation ended). It is honoured BEFORE the
+ * countdown starts, so the countdown is never pushed back by it.
+ *
  * The restart gate itself is untouched: the restart feature keeps its quiet
- * window exactly as it was.
+ * window exactly as it was (plus the same grace).
  *
  * @param {object} runtime
- * @returns {{ allow: boolean, reason: 'busy'|'quiet', blockedBy: any[] }}
+ * @returns {{ allow: boolean, reason: 'busy'|'grace'|'quiet', blockedBy: any[] }}
  */
 function sleepGate(runtime) {
+  // A pending restart goes FIRST: the shutdown waits for it — and for the
+  // sessions that resume with it. The intent survives the restart, so the
+  // machine goes off after everything is done, not before.
+  let pending = false
+  try {
+    pending = typeof runtime.pendingRestart === 'function' && runtime.pendingRestart() === true
+  } catch {
+    pending = false
+  }
+  if (pending) {
+    return {
+      allow: false,
+      reason: 'restart-pending',
+      blockedBy: [{
+        sessionId: 'restart-pending',
+        kind: 'restart-pending',
+        label: '待执行的重启',
+        name: '待执行的重启',
+      }],
+    }
+  }
   let busy = []
   try {
     busy = runtime.busyAgents()
@@ -3831,6 +4199,16 @@ function sleepGate(runtime) {
   }
   const list = Array.isArray(busy) ? busy : []
   if (list.length > 0) return { allow: false, reason: 'busy', blockedBy: list }
+  // The grace window: the last conversation may have finished a moment ago,
+  // and other plugins still have work queued that this plugin cannot see.
+  let quiet = 0
+  let grace = 0
+  try { quiet = Number(runtime.quietForMs()) } catch { quiet = 0 }
+  try { grace = Number(runtime.graceMs()) } catch { grace = 0 }
+  if (!Number.isFinite(quiet) || quiet < 0) quiet = 0
+  if (Number.isFinite(grace) && grace > 0 && quiet < grace) {
+    return { allow: false, reason: 'grace', blockedBy: [] }
+  }
   return { allow: true, reason: 'quiet', blockedBy: [] }
 }
 
@@ -3912,6 +4290,36 @@ function createSleepService(ctx, runtime, config, options = {}) {
     busyAgents: () => runtime.busyAgents(),
     gate,
     titleOf: (sessionId) => runtime.sessionTitle(sessionId),
+    // The grace window: after the last conversation finished the machine
+    // waits a little longer, so that work this plugin cannot see (a memory
+    // plugin writing its notes, a summary) still gets its chance.
+    quietForMs: () => runtime.quietForMs(),
+    graceMs: () => runtime.graceMs(),
+    // A pending restart goes first: the shutdown waits for it.
+    restartPending: () => {
+      const pending = runtime.pendingRestart()
+      if (!pending) return { pending: false, blockers: [] }
+      return {
+        pending: true,
+        blockers: [{
+          sessionId: 'restart-pending',
+          kind: 'restart-pending',
+          label: '待执行的重启',
+          name: '待执行的重启',
+        }],
+      }
+    },
+    // The intent is spent when the machine went off, when the shutdown failed
+    // and when the user cancelled it: the checkpoint must not keep it.
+    onDisarm: (reason) => {
+      try {
+        clearSleep(runtime.state)
+        runtime.persist()
+        runtime.log.info('the shutdown intent was cleared:', reason)
+      } catch (error) {
+        runtime.log.warn('could not clear the shutdown intent:', String(error))
+      }
+    },
     countdownSeconds: seconds,
     hostLabel: final.shortLabel,
     supported: final.supported,
@@ -3960,6 +4368,46 @@ function createSleepService(ctx, runtime, config, options = {}) {
       return liveController
     },
     invocation,
+    /**
+     * Arm the shutdown AND remember the intent.
+     *
+     * The intent lives in the checkpoint file, so it survives a restart: a
+     * shutdown asked for while a restart is pending waits for that restart —
+     * and for the sessions that resume with it.
+     *
+     * @returns {object} the sleep status
+     */
+    arm: () => {
+      try {
+        armSleep(runtime.state, {
+          armedAt: Date.now(),
+          countdownSeconds: config.sleepCountdownSeconds,
+        })
+        runtime.persist()
+      } catch (error) {
+        runtime.log.warn('could not record the shutdown intent:', String(error))
+      }
+      return liveController.arm()
+    },
+    /**
+     * Cancel the shutdown: the intent is gone for good (the disarm hook of
+     * the controller clears the checkpoint).
+     *
+     * @returns {object} the sleep status
+     */
+    cancel: () => liveController.cancel(),
+    /**
+     * The recorded shutdown intent, if there is one.
+     *
+     * @returns {{ armed: true, armedAt: number, countdownSeconds: number|null }|null}
+     */
+    intent: () => runtime.state.sleep,
+    /**
+     * Arm the shutdown from a recorded intent (the boot restore).
+     *
+     * @returns {object} the sleep status
+     */
+    restore: () => liveController.arm(),
   }
 }
 
@@ -3968,17 +4416,26 @@ function createSleepService(ctx, runtime, config, options = {}) {
  *
  * @param {{ plan: object, controller: object, invocation: () => object }} sleep
  * @param {object} config
+ * @param {object} [runtime] the runtime (for the quiet window)
  * @returns {object}
  */
-function sleepStatusPayload(sleep, config) {
+function sleepStatusPayload(sleep, config, runtime) {
   const status = sleep.controller.status()
   const invocation = sleep.invocation()
+  const intent = typeof sleep.intent === 'function' ? sleep.intent() : null
   return {
     ok: true,
     phase: status.phase,
     armed: status.armed,
     showSleepButton: config.showSleepButton !== false,
     countdownSeconds: status.countdownSeconds,
+    // The grace window and how long the host has been quiet: both are needed
+    // to tell "the machine is waiting for the grace" from "somebody is busy".
+    graceMs: config.restartGraceMs,
+    quietForMs: runtime && typeof runtime.quietForMs === 'function' ? runtime.quietForMs() : 0,
+    // When the shutdown was armed: the intent has to survive a restart, so the
+    // time is reported for the troubleshooting.
+    armedAt: intent && typeof intent.armedAt === 'number' ? intent.armedAt : null,
     /**
      * The pre-restart backup scope, straight from the effective configuration:
      * the settings page reads its two switches from here.
@@ -4040,7 +4497,7 @@ function buildSleepRoute(ctx, runtime, config, sleep) {
       }
       const method = req && typeof req.method === 'string' ? req.method.toUpperCase() : 'GET'
       if (method === 'GET') {
-        answer(sleepStatusPayload(sleep, config))
+        answer(sleepStatusPayload(sleep, config, runtime))
         return
       }
       if (method !== 'POST') {
@@ -4062,11 +4519,12 @@ function buildSleepRoute(ctx, runtime, config, sleep) {
           return
         }
         if (action === 'arm') {
-          sleep.controller.arm()
+          // The intent is recorded too: it survives a restart.
+          sleep.arm()
         } else {
-          sleep.controller.cancel()
+          sleep.cancel()
         }
-        answer(sleepStatusPayload(sleep, config))
+        answer(sleepStatusPayload(sleep, config, runtime))
       }).catch((error) => {
         answer({ ok: false, error: describeError(error) }, 400)
       })
@@ -4115,6 +4573,11 @@ function registerHealthRoute(ctx, runtime, config, sleep) {
           generation: state.generation,
           pendingRestart: state.restart !== null,
           settleMs: config.settleMs,
+          // The grace window and the quiet window the gate really uses: both
+          // are needed to tell "waiting for the grace" from "somebody is busy".
+          graceMs: config.restartGraceMs,
+          effectiveSettleMs: runtime.effectiveSettleMs(),
+          quietForMs: typeof verdict.quietForMs === 'number' ? verdict.quietForMs : 0,
           busyCount: verdict.blockedBy.length,
           agentCount,
         })
@@ -4178,6 +4641,9 @@ function registerHealthRoute(ctx, runtime, config, sleep) {
             allowRestart: verdict.allow === true,
             quietForMs: typeof verdict.quietForMs === 'number' ? verdict.quietForMs : 0,
             settleMs: config.settleMs,
+            // The grace window and the quiet window the gate really uses.
+            graceMs: config.restartGraceMs,
+            effectiveSettleMs: runtime.effectiveSettleMs(),
             updatedAt: live.updatedAt,
             // The park route, so the client never has to guess the prefix, and
             // the goals this plugin already disarmed (they are re-armed after
@@ -4508,12 +4974,31 @@ export function apply(ctx, rawConfig, options = {}) {
   // The boot recovery pass is the plugin's primary boot duty, so it is scheduled
   // BEFORE the auxiliary timers (the health-route registration retry below): a
   // fallback registered later must never shadow or postpone the recovery pass.
+  //
+  // The recorded shutdown intent is restored AFTER the recovery: a shutdown
+  // that was asked for before the restart must wait for the work that resumes
+  // with it — the machine goes off after everything is done, not before.
+  const restoreSleepIntent = () => {
+    const intent = sleep.intent()
+    if (!intent || intent.armed !== true) return
+    log.info('the shutdown intent survived the restart; the machine goes off after the work is done', {
+      armedAt: intent.armedAt,
+    })
+    sleep.restore()
+  }
   if (runtime.isNewBoot && config.resumeOnBoot) {
     runtime.recoverTimer = ctx.timeout(() => {
-      recoverAfterRestart(ctx, runtime, config).catch((error) => {
-        log.warn('boot recovery failed:', String(error))
-      })
+      recoverAfterRestart(ctx, runtime, config)
+        .then(() => { restoreSleepIntent() })
+        .catch((error) => {
+          log.warn('boot recovery failed:', String(error))
+          restoreSleepIntent()
+        })
     }, Math.max(0, config.recoveryDelayMs))
+  } else {
+    // No recovery pass: the intent is restored right away (a hot reload must
+    // not lose it either).
+    restoreSleepIntent()
   }
 
   registerTools(ctx, runtime, config)
@@ -4540,4 +5025,6 @@ export {
   resolveAnnouncementsPath,
   featureAnnouncements,
   pluginVersion,
+  PLUGIN_VERSION_FALLBACK,
+  SLEEP_FEATURE_VERSION,
 }