dsh-autorestart 0.3.6 → 0.6.0

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,112 @@ import {
   runCommandNow,
   scheduleDetachedRestart,
 } from './lib/restart.js'
+import {
+  createSleepController,
+  COUNTDOWN_CHOICES,
+  DEFAULT_COUNTDOWN_SECONDS,
+  detectShutdownPlan,
+  planInvocation,
+  runShutdown,
+  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.
+ *
+ * The real version is read from the plugin's own package.json (see
+ * `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.6.0'
+
+/** The cached version of this plugin (read once per process). */
+let pluginVersionCache = null
+
+/**
+ * The version of this plugin.
+ *
+ * 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).
+ *
+ * @returns {string}
+ */
+function pluginVersion() {
+  if (pluginVersionCache !== null) return pluginVersionCache
+  let version = PLUGIN_VERSION_FALLBACK
+  try {
+    const raw = fs.readFileSync(new URL('./package.json', import.meta.url), 'utf8')
+    const parsed = JSON.parse(raw)
+    if (parsed && typeof parsed.version === 'string' && parsed.version.trim() !== '') {
+      version = parsed.version.trim()
+    }
+  } catch {
+    // The package.json is not readable (a bundled build): the fallback is the
+    // version that was shipped with this build.
+  }
+  pluginVersionCache = version
+  return version
+}
+
+/**
+ * The features that are announced ONCE, after an upgrade.
+ *
+ * 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.
+ *
+ * @returns {{ feature: string, version: string }[]}
+ */
+function featureAnnouncements() {
+  return [
+    // The graceful shutdown ("收工关机") and its moon button.
+    { feature: 'sleep', version: pluginVersion() },
+  ]
+}
 
 /**
  * `@deepseek-ai/schemastery` resolves inside modules that live in the dsh installation,
@@ -216,6 +324,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)
@@ -241,6 +355,20 @@ function buildConfigSchema() {
         .description('How many snapshots are kept; older ones are deleted automatically.'),
       rollbackTimeoutMs: schemastery.number().min(1000).default(90000)
         .description('Milliseconds the detached watcher waits for the relaunched host before it restores the snapshot.'),
+      // graceful shutdown ("收工关机"): wait for every conversation, count down, then
+      // switch the REAL host machine off (a WSL host shuts Windows down, not the distro)
+      showSleepButton: schemastery.boolean().default(true)
+        .description('是否在左侧栏最底部、设置按钮旁边显示「收工关机」按钮：关掉之后界面上不再有这个按钮，关机接口也不再被界面调用。'),
+      // The countdown length is a DROPDOWN: a union of the offered choices
+      // projects into an enum (the settings page renders a select, not a
+      // number field). `loose()` keeps an old profile value from breaking
+      // the boot — the value is snapped onto a choice in normalizeConfig.
+      sleepCountdownSeconds: schemastery.union(COUNTDOWN_CHOICES.map((value) => schemastery.const(value)))
+        .default(DEFAULT_COUNTDOWN_SECONDS)
+        .loose()
+        .description('收工关机的倒计时秒数（下拉框：0 / 10 / 20 / 30 / 60 秒，默认 20；0 表示不倒数、立即关机，但仍会先等所有会话收工）。'),
+      sleepCommand: schemastery.string().default('')
+        .description('自定义关机命令：留空表示按系统自动识别（Windows / WSL / Linux / macOS），填了就用这条命令代替自动识别。'),
     })
   } catch (error) {
     schemasterySource = `construction-failed: ${String(error)}`
@@ -268,6 +396,7 @@ const DEFAULTS = {
   restartCommand: '',
   relaunchDelaySeconds: 2,
   settleMs: 2000,
+  restartGraceMs: DEFAULT_GRACE_MS,
   autoReloadPage: true,
   blockManualRestart: true,
   healthPath: '/__dsh_autorestart/health',
@@ -280,6 +409,12 @@ const DEFAULTS = {
   backupIncludePlugins: true,
   maxBackups: 2,
   rollbackTimeoutMs: 90000,
+  // Graceful shutdown ("收工关机"): the button at the foot of the left sidebar,
+  // the countdown before the machine is switched off and the optional custom
+  // shutdown command (empty = the host is detected automatically).
+  showSleepButton: true,
+  sleepCountdownSeconds: DEFAULT_COUNTDOWN_SECONDS,
+  sleepCommand: '',
 }
 
 /** Merge a loader row config over {@link DEFAULTS}, dropping wrong-typed values. */
@@ -304,6 +439,15 @@ function normalizeConfig(raw) {
   const rollbackTimeout = Number(config.rollbackTimeoutMs)
   config.rollbackTimeoutMs =
     Number.isFinite(rollbackTimeout) && rollbackTimeout >= 1000 ? Math.trunc(rollbackTimeout) : 90000
+  // The countdown of the graceful shutdown is one of the offered choices: a
+  // 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
 }
 
@@ -370,6 +514,36 @@ function resolveChoicePath(config) {
   return `${prefix}/choice`
 }
 
+/**
+ * Resolve the sleep-route path: a sibling of the health route, under the same
+ * prefix (`GET /sleep` reports the state of the graceful sleep, `POST /sleep`
+ * arms or cancels it).
+ *
+ * @param {object} config
+ * @returns {string}
+ */
+function resolveSleepPath(config) {
+  const healthPath = resolveHealthPath(config)
+  const index = healthPath.lastIndexOf('/')
+  const prefix = index > 0 ? healthPath.slice(0, index) : '/__dsh_autorestart'
+  return `${prefix}/sleep`
+}
+
+/**
+ * Resolve the announcements-route path: a sibling of the health route, under
+ * the same prefix (`GET /announcements` reports the feature announcements the
+ * user has not seen yet, `POST /announcements` records that it saw one).
+ *
+ * @param {object} config
+ * @returns {string}
+ */
+function resolveAnnouncementsPath(config) {
+  const healthPath = resolveHealthPath(config)
+  const index = healthPath.lastIndexOf('/')
+  const prefix = index > 0 ? healthPath.slice(0, index) : '/__dsh_autorestart'
+  return `${prefix}/announcements`
+}
+
 /**
  * The blocking sessions with the reason each one blocks: a session that is
  * held by an armed goal reports `goal-active` (that goal can be disarmed), a
@@ -552,14 +726,22 @@ const INSTALL_CHOICE_FILE = 'install-choice.json'
  * Read the recorded install choice from the fallback file.
  *
  * @param {string} stateDir
- * @returns {boolean|null} the recorded value, or null when there is none
+ * @returns {{ includePlugins: boolean|null, backupOnRestart: boolean|null, showSleepButton: boolean|null, sleepCountdownSeconds: number|null, restartGraceMs: number|null }|null}
  */
 function readInstallChoice(stateDir) {
   try {
     const raw = fs.readFileSync(path.join(stateDir, INSTALL_CHOICE_FILE), 'utf8')
     const parsed = JSON.parse(raw)
     if (!parsed || typeof parsed !== 'object') return null
-    return typeof parsed.includePlugins === 'boolean' ? parsed.includePlugins : null
+    return {
+      includePlugins: typeof parsed.includePlugins === 'boolean' ? parsed.includePlugins : null,
+      backupOnRestart: typeof parsed.backupOnRestart === 'boolean' ? parsed.backupOnRestart : null,
+      showSleepButton: typeof parsed.showSleepButton === 'boolean' ? parsed.showSleepButton : null,
+      sleepCountdownSeconds: typeof parsed.sleepCountdownSeconds === 'number'
+        ? parsed.sleepCountdownSeconds
+        : null,
+      restartGraceMs: typeof parsed.restartGraceMs === 'number' ? parsed.restartGraceMs : null,
+    }
   } catch {
     return null
   }
@@ -568,18 +750,36 @@ function readInstallChoice(stateDir) {
 /**
  * Write the install choice into the fallback file.
  *
+ * The file is written ADDITIVELY: a choice about the sleep button must not
+ * erase the recorded backup scope (and the other way round).
+ *
  * @param {string} stateDir
- * @param {boolean} includePlugins
+ * @param {{ includePlugins?: boolean, backupOnRestart?: boolean, showSleepButton?: boolean, sleepCountdownSeconds?: number, restartGraceMs?: number }} values
  * @returns {string} the file that was written
  */
-function writeInstallChoice(stateDir, includePlugins) {
+function writeInstallChoice(stateDir, values) {
   const file = path.join(stateDir, INSTALL_CHOICE_FILE)
+  const current = readInstallChoice(stateDir) || {
+    includePlugins: null,
+    backupOnRestart: null,
+    showSleepButton: null,
+    sleepCountdownSeconds: null,
+    restartGraceMs: null,
+  }
+  const payload = {
+    includePlugins: typeof values.includePlugins === 'boolean' ? values.includePlugins : current.includePlugins,
+    backupOnRestart: typeof values.backupOnRestart === 'boolean' ? values.backupOnRestart : current.backupOnRestart,
+    showSleepButton: typeof values.showSleepButton === 'boolean' ? values.showSleepButton : current.showSleepButton,
+    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 })
-  fs.writeFileSync(
-    file,
-    JSON.stringify({ includePlugins: includePlugins === true, at: new Date().toISOString() }, null, 2),
-    'utf8',
-  )
+  fs.writeFileSync(file, JSON.stringify(payload, null, 2), 'utf8')
   return file
 }
 
@@ -602,10 +802,60 @@ export function resolveBackupIncludePlugins(rawConfig, stateDir) {
     return { includePlugins: rawConfig.backupIncludePlugins, source: 'config' }
   }
   const fallback = typeof stateDir === 'string' && stateDir !== '' ? readInstallChoice(stateDir) : null
-  if (fallback !== null) return { includePlugins: fallback, source: 'fallback-file' }
+  if (fallback !== null && fallback.includePlugins !== null) {
+    return { includePlugins: fallback.includePlugins, source: 'fallback-file' }
+  }
   return { includePlugins: DEFAULTS.backupIncludePlugins, source: 'default' }
 }
 
+/**
+ * Resolve the effective `backupOnRestart` value and where it came from.
+ *
+ * The same rule as the backup scope: the profile row config wins, the degraded
+ * fallback file fills the gap, and the built-in default applies when neither
+ * says anything.
+ *
+ * @param {object|null|undefined} rawConfig the loader row config, as received
+ * @param {string} stateDir
+ * @returns {{ backupOnRestart: boolean, source: 'config'|'fallback-file'|'default' }}
+ */
+export function resolveBackupOnRestart(rawConfig, stateDir) {
+  if (rawConfig && typeof rawConfig === 'object'
+    && Object.prototype.hasOwnProperty.call(rawConfig, 'backupOnRestart')
+    && typeof rawConfig.backupOnRestart === 'boolean') {
+    return { backupOnRestart: rawConfig.backupOnRestart, source: 'config' }
+  }
+  const fallback = typeof stateDir === 'string' && stateDir !== '' ? readInstallChoice(stateDir) : null
+  if (fallback !== null && fallback.backupOnRestart !== null) {
+    return { backupOnRestart: fallback.backupOnRestart, source: 'fallback-file' }
+  }
+  return { backupOnRestart: DEFAULTS.backupOnRestart, source: 'default' }
+}
+
+/**
+ * Resolve the effective `showSleepButton` value and where it came from.
+ *
+ * The same rule as the backup scope: the profile row config wins, the degraded
+ * fallback file fills the gap, and the built-in default applies when neither
+ * says anything.
+ *
+ * @param {object|null|undefined} rawConfig the loader row config, as received
+ * @param {string} stateDir
+ * @returns {{ showSleepButton: boolean, source: 'config'|'fallback-file'|'default' }}
+ */
+export function resolveShowSleepButton(rawConfig, stateDir) {
+  if (rawConfig && typeof rawConfig === 'object'
+    && Object.prototype.hasOwnProperty.call(rawConfig, 'showSleepButton')
+    && typeof rawConfig.showSleepButton === 'boolean') {
+    return { showSleepButton: rawConfig.showSleepButton, source: 'config' }
+  }
+  const fallback = typeof stateDir === 'string' && stateDir !== '' ? readInstallChoice(stateDir) : null
+  if (fallback !== null && fallback.showSleepButton !== null) {
+    return { showSleepButton: fallback.showSleepButton, source: 'fallback-file' }
+  }
+  return { showSleepButton: DEFAULTS.showSleepButton, source: 'default' }
+}
+
 /**
  * Resolve the profile directory the running host was started from.
  *
@@ -951,9 +1201,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 = []
@@ -966,8 +1296,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
@@ -1300,12 +1632,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(),
   })
 
   /**
@@ -1320,7 +1681,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
@@ -1328,9 +1725,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
@@ -1621,7 +2022,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,
@@ -1657,6 +2058,134 @@ export function createRuntime(ctx, config, options = {}) {
     }
   }
 
+  /**
+   * Persist one or more user choices into the profile row of this plugin.
+   *
+   * The official `configEditor` service is the primary path: the choice goes
+   * into the profile row of this plugin, so the settings page and the one-time
+   * prompts read and write the same key (one source of truth). When the service
+   * 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, restartGraceMs?: number }} changes
+   * @returns {Promise<{ applied: 'config'|'fallback-file' }>}
+   */
+  const persistConfigChoice = async (changes) => {
+    // The profile row and the degraded fallback file use different key names for
+    // the backup scope: the row carries the plugin's own key
+    // (`backupIncludePlugins`), the file the short one (`includePlugins`).
+    const wanted = {}
+    const fallback = {}
+    if (typeof changes.backupIncludePlugins === 'boolean') {
+      wanted.backupIncludePlugins = changes.backupIncludePlugins
+      fallback.includePlugins = changes.backupIncludePlugins
+    }
+    if (typeof changes.backupOnRestart === 'boolean') {
+      wanted.backupOnRestart = changes.backupOnRestart
+      fallback.backupOnRestart = changes.backupOnRestart
+    }
+    if (typeof changes.showSleepButton === 'boolean') {
+      wanted.showSleepButton = changes.showSleepButton
+      fallback.showSleepButton = changes.showSleepButton
+    }
+    if (typeof changes.sleepCountdownSeconds === 'number') {
+      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 {
+        const entry = findOwnEntry(editor)
+        if (entry !== null) {
+          await editor.edit(entry, (current) => {
+            const base = current && typeof current === 'object' ? { ...current } : {}
+            return { ...base, ...wanted }
+          })
+          // The Loader reconciles the row, but the running instance must not
+          // keep the old value until that happens.
+          for (const [key, value] of Object.entries(wanted)) config[key] = value
+          log.info(`the choice was written into the profile configuration: ${JSON.stringify(wanted)}`)
+          return { applied: 'config' }
+        }
+        log.warn(`the configEditor service has no profile row for ${name}; the choice degrades to ${INSTALL_CHOICE_FILE}`)
+      } catch (error) {
+        log.warn(`could not write the choice into the profile configuration: ${describeError(error)}`)
+      }
+    } else {
+      log.warn(`the configEditor service is unavailable; the choice degrades to ${INSTALL_CHOICE_FILE}`)
+    }
+    const file = path.join(path.dirname(stateFile), INSTALL_CHOICE_FILE)
+    try {
+      writeInstallChoice(path.dirname(stateFile), fallback)
+    } catch (error) {
+      throw new Error(`could not write the choice to ${file}: ${describeError(error)}`)
+    }
+    for (const [key, value] of Object.entries(wanted)) config[key] = value
+    log.warn(`the choice was written to ${file} instead of the profile configuration`)
+    return { applied: 'fallback-file' }
+  }
+
+  /**
+   * 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.6.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.
+   *
+   * @returns {{ feature: string, version: string }[]}
+   */
+  const pendingAnnouncements = () => {
+    const seen = state.seenFeatureVersions && typeof state.seenFeatureVersions === 'object'
+      ? state.seenFeatureVersions
+      : {}
+    return featureAnnouncements().filter((entry) => seen[entry.feature] !== entry.version)
+  }
+
+  /**
+   * Record that the user has seen the announcement of one feature.
+   *
+   * The record lives in the checkpoint file, so it survives a restart of the
+   * Host: an announcement that was shown once does not come back with the
+   * next boot.
+   *
+   * @param {string} feature the id of the feature
+   * @returns {string[]} the features that are recorded now
+   */
+  const markFeatureSeen = (feature) => {
+    const id = typeof feature === 'string' ? feature.trim() : ''
+    if (id === '') return []
+    const known = featureAnnouncements().find((entry) => entry.feature === id)
+    if (!known) return []
+    if (!state.seenFeatureVersions || typeof state.seenFeatureVersions !== 'object') {
+      state.seenFeatureVersions = {}
+    }
+    state.seenFeatureVersions[id] = known.version
+    persist()
+    return Object.keys(state.seenFeatureVersions).sort()
+  }
+
+  /**
+   * Record that the user has seen the announcement of EVERY feature.
+   *
+   * This is what the one-time install prompt does: it already explains the
+   * features to a fresh installation, so no announcement may follow it.
+   *
+   * @returns {string[]} the features that are recorded now
+   */
+  const markAllFeaturesSeen = () => {
+    const seen = new Set()
+    for (const entry of featureAnnouncements()) {
+      for (const id of markFeatureSeen(entry.feature)) seen.add(id)
+    }
+    return Array.from(seen).sort()
+  }
+
   const runtime = {
     get state() {
       return state
@@ -1706,58 +2235,83 @@ export function createRuntime(ctx, config, options = {}) {
     stateFile,
     log,
     persist,
+    /**
+     * Persist one or more user choices into the profile row of this plugin.
+     *
+     * @param {{ backupOnRestart?: boolean, backupIncludePlugins?: boolean, showSleepButton?: boolean, sleepCountdownSeconds?: number }} changes
+     * @returns {Promise<{ applied: 'config'|'fallback-file' }>}
+     */
+    applyConfigChoice: (changes) => persistConfigChoice(changes),
+    /**
+     * The feature announcements the user has not seen yet.
+     *
+     * @returns {{ feature: string, version: string }[]}
+     */
+    pendingAnnouncements,
+    /**
+     * Record that the user has seen the announcement of one feature.
+     *
+     * @param {string} feature
+     * @returns {string[]} the features that are recorded now
+     */
+    markFeatureSeen,
+    /**
+     * Record that the user has seen the announcement of every feature.
+     *
+     * @returns {string[]} the features that are recorded now
+     */
+    markAllFeaturesSeen,
     /**
      * Persist the user's one-time install choice: whether the pre-restart
      * backup also snapshots the installed plugin tree.
      *
-     * The official `configEditor` service is the primary path: the choice goes
-     * into the profile row of this plugin, so the settings page and this prompt
-     * read and write the same key (one source of truth). When the service 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 {boolean} includePlugins
      * @returns {Promise<{ applied: 'config'|'fallback-file', includePlugins: boolean }>}
      */
     async applyBackupChoice(includePlugins) {
-      const value = includePlugins === true
-      const editor = resolveConfigEditor(ctx)
-      if (editor !== null) {
-        try {
-          const entry = findOwnEntry(editor)
-          if (entry !== null) {
-            await editor.edit(entry, (current) => {
-              const base = current && typeof current === 'object' ? { ...current } : {}
-              return { ...base, backupIncludePlugins: value }
-            })
-            // The Loader reconciles the row, but the running instance must not
-            // keep the old value until that happens.
-            config.backupIncludePlugins = value
-            log.info(`the install choice was written into the profile configuration: backupIncludePlugins=${value}`)
-            return { applied: 'config', includePlugins: value }
-          }
-          log.warn(`the configEditor service has no profile row for ${name}; the install choice degrades to ${INSTALL_CHOICE_FILE}`)
-        } catch (error) {
-          log.warn(`could not write the install choice into the profile configuration: ${describeError(error)}`)
-        }
-      } else {
-        log.warn(`the configEditor service is unavailable; the install choice degrades to ${INSTALL_CHOICE_FILE}`)
-      }
-      const file = path.join(path.dirname(stateFile), INSTALL_CHOICE_FILE)
-      try {
-        writeInstallChoice(path.dirname(stateFile), value)
-      } catch (error) {
-        throw new Error(`could not write the install choice to ${file}: ${describeError(error)}`)
-      }
-      config.backupIncludePlugins = value
-      log.warn(`the install choice was written to ${file} instead of the profile configuration`)
-      return { applied: 'fallback-file', includePlugins: value }
+      const result = await persistConfigChoice({ backupIncludePlugins: includePlugins === true })
+      return { applied: result.applied, includePlugins: includePlugins === true }
+    },
+    /**
+     * Persist whether the graceful-sleep button is shown in the main UI.
+     *
+     * @param {boolean} showSleepButton
+     * @returns {Promise<{ applied: 'config'|'fallback-file', showSleepButton: boolean }>}
+     */
+    async applySleepButtonChoice(showSleepButton) {
+      const result = await persistConfigChoice({ showSleepButton: showSleepButton === true })
+      return { applied: result.applied, showSleepButton: showSleepButton === true }
     },
     toolErrors,
     startPolling,
     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,
@@ -2466,7 +3020,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 '
@@ -2492,7 +3048,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' } },
@@ -2519,6 +3101,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),
@@ -3233,18 +3819,107 @@ function buildHandoffRoute(ctx, runtime, config) {
   }
 }
 
+/**
+ * Build the announcements route: the one-time announcement of a new feature.
+ *
+ * It sits next to the health route and uses the same authentication rule
+ * (loopback OR a request the connection service admits).
+ *
+ *   - `GET` answers `{ ok: true, pending: [{ feature, version }] }`: the
+ *     announcements the user has not seen yet (an empty list when there is
+ *     nothing new — a fresh installation is asked at the install prompt, so
+ *     it never gets an announcement);
+ *   - `POST` with `{ "feature": "sleep" }` records that the user has seen
+ *     that announcement and answers `{ ok: true, seen: [...] }`.
+ *
+ * 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.
+ */
+function buildAnnouncementsRoute(ctx, runtime, config) {
+  const routePath = resolveAnnouncementsPath(config)
+  return {
+    kind: 'exact',
+    path: routePath,
+    handler: (req, res) => {
+      const remote = req && req.socket ? req.socket.remoteAddress : undefined
+      const loopback = remote === undefined
+        || remote === '127.0.0.1'
+        || remote === '::1'
+        || remote === '::ffff:127.0.0.1'
+      if (!loopback && !admittedByConnection(ctx, req)) {
+        res.statusCode = 403
+        res.setHeader('content-type', 'application/json; charset=utf-8')
+        res.end('{"ok":false,"error":"loopback-only"}')
+        return
+      }
+      const answer = (payload, status = 200) => {
+        res.statusCode = status
+        res.setHeader('content-type', 'application/json; charset=utf-8')
+        res.setHeader('cache-control', 'no-store')
+        res.end(JSON.stringify(payload))
+      }
+      const method = req && typeof req.method === 'string' ? req.method.toUpperCase() : 'GET'
+      if (method === 'GET') {
+        answer({ ok: true, pending: runtime.pendingAnnouncements() })
+        return
+      }
+      if (method !== 'POST') {
+        res.statusCode = 405
+        res.setHeader('content-type', 'application/json; charset=utf-8')
+        res.setHeader('allow', 'GET, POST')
+        res.end('{"ok":false,"error":"method-not-allowed"}')
+        return
+      }
+      void readJsonBody(req).then((payload) => {
+        const body = payload && typeof payload === 'object' ? payload : {}
+        const feature = typeof body.feature === 'string' ? body.feature.trim() : ''
+        if (feature === '') {
+          answer({
+            ok: false,
+            error: 'feature-required',
+            instruction: 'Send { "feature": "sleep" }.',
+          }, 400)
+          return
+        }
+        const known = featureAnnouncements().some((entry) => entry.feature === feature)
+        if (!known) {
+          answer({
+            ok: false,
+            error: 'unknown-feature',
+            instruction: `Send { "feature": ${featureAnnouncements().map((entry) => `"${entry.feature}"`).join(' | ')} }.`,
+          }, 400)
+          return
+        }
+        answer({ ok: true, seen: runtime.markFeatureSeen(feature) })
+      }).catch((error) => {
+        answer({ ok: false, error: describeError(error) }, 400)
+      })
+    },
+  }
+}
+
 /**
  * Build the POST `/choice` route: persist the one-time install choice of the
- * user (whether the pre-restart backup also snapshots the installed plugins).
+ * user (whether the pre-restart backup also snapshots the installed plugins),
+ * the answer to the one-time question whether the graceful-sleep button is
+ * shown, and the settings of the configuration page (how long the countdown
+ * runs, whether the pre-restart backup is taken at all and whether that
+ * backup includes the installed plugins).
  *
  * It sits next to the health route and uses the same authentication rule
  * (loopback OR a request the connection service admits). Body:
- * `{ "includePlugins": boolean }`; anything that is not a boolean is refused
- * with a 400 and NOTHING is written.
+ * `{ "includePlugins"?: boolean, "backupIncludePlugins"?: boolean,
+ *   "backupOnRestart"?: boolean, "showSleepButton"?: boolean,
+ *   "sleepCountdownSeconds"?: 0 | 10 | 20 | 30 | 60 }` — at least one
+ * of the keys must be present, and a key that IS present must carry a valid
+ * value. Anything else is refused with a 400 and NOTHING is written.
  *
- * The answer is `{ ok: true, applied: 'config' | 'fallback-file', includePlugins }`:
+ * The answer is `{ ok: true, applied: 'config' | 'fallback-file', ... }`:
  * `applied` says where the choice landed — the profile configuration (the
- * official path) or the degraded fallback file.
+ * official path) or the degraded fallback file. Only the keys that were asked
+ * for are echoed back, plus the effective `countdownSeconds` so the settings
+ * page can read them back at once.
  */
 function buildChoiceRoute(ctx, runtime, config) {
   const routePath = resolveChoicePath(config)
@@ -3272,8 +3947,25 @@ function buildChoiceRoute(ctx, runtime, config) {
       }
       void readJsonBody(req).then(async (payload) => {
         const body = payload && typeof payload === 'object' ? payload : {}
-        const includePlugins = body.includePlugins
-        if (typeof includePlugins !== 'boolean') {
+        const hasInclude = Object.prototype.hasOwnProperty.call(body, 'includePlugins')
+        const hasBackupInclude = Object.prototype.hasOwnProperty.call(body, 'backupIncludePlugins')
+        const hasBackup = Object.prototype.hasOwnProperty.call(body, 'backupOnRestart')
+        const hasShow = Object.prototype.hasOwnProperty.call(body, 'showSleepButton')
+        const hasSeconds = Object.prototype.hasOwnProperty.call(body, 'sleepCountdownSeconds')
+        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')
+          res.setHeader('cache-control', 'no-store')
+          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 } and/or { "restartGraceMs": 0 | 3000 | 5000 | 10000 | 20000 | 30000 }.',
+          }))
+          return
+        }
+        if (hasInclude && typeof body.includePlugins !== 'boolean') {
           // Nothing is written for a malformed choice: the caller's answer
           // must not change the profile configuration.
           res.statusCode = 400
@@ -3286,15 +3978,95 @@ function buildChoiceRoute(ctx, runtime, config) {
           }))
           return
         }
-        const result = await runtime.applyBackupChoice(includePlugins)
+        if (hasBackupInclude && typeof body.backupIncludePlugins !== 'boolean') {
+          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: 'backupIncludePlugins-must-be-boolean',
+            instruction: 'Send { "backupIncludePlugins": true | false }.',
+          }))
+          return
+        }
+        if (hasBackup && typeof body.backupOnRestart !== 'boolean') {
+          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: 'backupOnRestart-must-be-boolean',
+            instruction: 'Send { "backupOnRestart": true | false }.',
+          }))
+          return
+        }
+        if (hasShow && typeof body.showSleepButton !== 'boolean') {
+          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: 'showSleepButton-must-be-boolean',
+            instruction: 'Send { "showSleepButton": true | false }.',
+          }))
+          return
+        }
+        if (hasSeconds && COUNTDOWN_CHOICES.indexOf(body.sleepCountdownSeconds) === -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: 'sleepCountdownSeconds-must-be-offered',
+            instruction: `Send { "sleepCountdownSeconds": ${COUNTDOWN_CHOICES.join(' | ')} }.`,
+          }))
+          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).
+        if (hasInclude) changes.backupIncludePlugins = body.includePlugins === true
+        if (hasBackupInclude) changes.backupIncludePlugins = body.backupIncludePlugins === true
+        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.
+        //
+        // Only the install prompt sends `includePlugins` and `showSleepButton`
+        // (the settings page writes `backupIncludePlugins`,
+        // `backupOnRestart` and `sleepCountdownSeconds`), so these two keys
+        // are exactly the "the install question was answered" moment.
+        if (hasInclude || hasShow) {
+          const seen = runtime.markAllFeaturesSeen()
+          if (seen.length > 0) {
+            runtime.log.info(`the install question marked the feature announcements as seen: ${seen.join(', ')}`)
+          }
+        }
+        const answer = { ok: true, applied: result.applied }
+        if (hasInclude) answer.includePlugins = body.includePlugins === true
+        if (hasBackupInclude) answer.backupIncludePlugins = body.backupIncludePlugins === true
+        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')
-        res.end(JSON.stringify({
-          ok: true,
-          applied: result.applied,
-          includePlugins: result.includePlugins === true,
-        }))
+        res.end(JSON.stringify(answer))
       }).catch((error) => {
         res.statusCode = 500
         res.setHeader('content-type', 'application/json; charset=utf-8')
@@ -3304,8 +4076,406 @@ function buildChoiceRoute(ctx, runtime, config) {
   }
 }
 
+/**
+ * Is the graceful sleep a dry run?
+ *
+ * With `DSH_AUTORESTART_SLEEP_DRYRUN=1` the plugin reports the command it
+ * WOULD run and never runs it. That is what makes the feature testable on a
+ * live machine.
+ *
+ * @returns {boolean}
+ */
+function sleepDryRun() {
+  return process.env.DSH_AUTORESTART_SLEEP_DRYRUN === '1'
+}
+
+/**
+ * The gate of the graceful sleep: the ONE question is "is any conversation
+ * still working?".
+ *
+ * It is deliberately NOT the restart gate: that one also demands a quiet
+ * settle window, and a settle window longer than the countdown would push the
+ * power-off back by whole countdown periods (every restart of the countdown
+ * would also claim that somebody started working again, which is not what
+ * 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 (plus the same grace).
+ *
+ * @param {object} runtime
+ * @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()
+  } catch {
+    busy = []
+  }
+  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: [] }
+}
+
+/**
+ * The FINAL plan of the graceful sleep: what will really be executed, and how
+ * the host describes itself in the status JSON.
+ *
+ * Two rules:
+ *   1. `supported` follows the plan that will be executed, NOT the detected
+ *      one: a machine whose platform could not be detected is still perfectly
+ *      usable when the operator configured a command of their own.
+ *   2. the reported `kind`/`label` belong to that same plan, so the status
+ *      never says "this machine has no reliable way to switch off" while a
+ *      command is about to run.
+ *
+ * @param {object} plan the detected plan
+ * @param {object} config
+ * @returns {object} the effective plan
+ */
+function effectiveSleepPlan(plan, config) {
+  const invocation = planInvocation(plan, {
+    sleepCommand: config.sleepCommand,
+    platform: plan.platform,
+  })
+  const custom = invocation.source === 'sleepCommand'
+  const detectedKind = typeof plan.kind === 'string' ? plan.kind : 'unsupported'
+  const detected = detectedKind !== 'unsupported'
+  const command = typeof invocation.command === 'string' && invocation.command !== '' ? invocation.command : null
+  const label = custom
+    ? (detected ? `执行你指定的关机命令（${plan.label}）` : '执行你指定的关机命令')
+    : plan.label
+  const kind = custom
+    // A custom command on a platform we could not classify: the machine is
+    // real, the mechanism is the operator's own — it is NOT "unsupported".
+    ? (detected ? detectedKind : 'custom')
+    : detectedKind
+  return {
+    ...invocation,
+    kind,
+    label,
+    // The short phrase the countdown message talks about.
+    shortLabel: custom ? '执行你指定的关机命令' : plan.label,
+    // The final plan decides whether the feature may run at all.
+    supported: command !== null,
+  }
+}
+
+/**
+ * Build the graceful-sleep service: the detected host plan plus the state
+ * machine that waits for the conversations, counts down and switches the
+ * machine off.
+ *
+ * The busy check is the runtime's own `busyAgents()`, so the sleep feature and
+ * the restart feature agree on what "every conversation is idle" means. The
+ * gate itself is the sleep-specific one (no settle window): the sleep feature
+ * counts down on screen itself.
+ *
+ * `options.sleepNow` and `options.sleepSpawn` replace the clock and the
+ * process spawner, so the whole flow can be driven without waiting and
+ * without ever touching the machine. Production never passes them.
+ *
+ * @param {object} ctx
+ * @param {object} runtime
+ * @param {object} config
+ * @param {{ sleepNow?: () => number, sleepSpawn?: Function }} [options]
+ * @returns {{ plan: object, controller: object, invocation: () => object }}
+ */
+function createSleepService(ctx, runtime, config, options = {}) {
+  const plan = detectShutdownPlan({ platform: process.platform, env: process.env })
+  // The configured command (if any) replaces the detected one; the final plan
+  // is what decides whether the feature may run and what the UI is told.
+  const invocation = () => effectiveSleepPlan(plan, config)
+  const gate = () => sleepGate(runtime)
+  const final = invocation()
+  const now = typeof options.sleepNow === 'function' ? options.sleepNow : () => Date.now()
+  const spawn = typeof options.sleepSpawn === 'function' ? options.sleepSpawn : undefined
+  const buildController = (seconds) => createSleepController({
+    now,
+    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,
+    log: runtime.log,
+    // The timer belongs to the plugin: `ctx.interval` is disposed with it.
+    setInterval: (fn, ms) => ctx.interval(fn, ms),
+    clearInterval: (handle) => {
+      try {
+        if (typeof handle === 'function') handle()
+      } catch {}
+    },
+    shutdown: () => runShutdown(invocation(), {
+      spawn,
+      dryRun: sleepDryRun(),
+      log: runtime.log,
+      // The gate is checked ONE more time right before the machine is closed —
+      // with the SAME sleep gate (a busy conversation still stops it).
+      gate,
+    }),
+  })
+  // The countdown length belongs to the CONFIGURATION, and the configuration
+  // page can change it while the plugin runs. The controller is rebuilt as
+  // soon as the new length is known — but never while a countdown is running:
+  // that one keeps the length it was started with.
+  let active = buildController(config.sleepCountdownSeconds)
+  let activeSeconds = config.sleepCountdownSeconds
+  const current = () => {
+    const seconds = config.sleepCountdownSeconds
+    if (seconds === activeSeconds) return active
+    if (active.status().armed) return active
+    active.dispose()
+    active = buildController(seconds)
+    activeSeconds = seconds
+    return active
+  }
+  const liveController = {
+    arm: (...args) => current().arm(...args),
+    cancel: (...args) => current().cancel(...args),
+    tick: (...args) => current().tick(...args),
+    status: (...args) => current().status(...args),
+    dispose: (...args) => current().dispose(...args),
+  }
+  return {
+    plan,
+    get controller() {
+      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(),
+  }
+}
+
+/**
+ * The state of the graceful sleep, in the shape the client renders it.
+ *
+ * @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, 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.
+     */
+    backupOnRestart: config.backupOnRestart !== false,
+    backupIncludePlugins: config.backupIncludePlugins !== false,
+    remainingMs: status.remainingMs,
+    blockers: status.blockers,
+    host: {
+      platform: invocation.platform || process.platform,
+      kind: invocation.kind,
+      label: invocation.label,
+      source: invocation.source,
+      // Machine-readable: the host was only recognized as WSL because the
+      // Windows drive is mounted (a hint, not a proof). The UI and the tests
+      // read this instead of guessing from the Chinese label.
+      suspect: invocation.suspect === true,
+    },
+    dryRun: sleepDryRun(),
+    message: status.message,
+    lastRun: status.lastRun,
+  }
+}
+
+/**
+ * Build the `/sleep` route: `GET` reports the state of the graceful sleep,
+ * `POST` arms or cancels it.
+ *
+ * It sits next to the health route and uses the same authentication rule
+ * (loopback OR a request the connection service admits). Body:
+ * `{ "action": "arm" | "cancel" }`; anything else is refused with a 400.
+ *
+ * There is NO ticket and no extra header: the desktop client and the hosted
+ * web client drive the very same route, so a request carries nothing but the
+ * action itself.
+ */
+function buildSleepRoute(ctx, runtime, config, sleep) {
+  const routePath = resolveSleepPath(config)
+  return {
+    kind: 'exact',
+    path: routePath,
+    handler: (req, res) => {
+      const remote = req && req.socket ? req.socket.remoteAddress : undefined
+      const loopback = remote === undefined
+        || remote === '127.0.0.1'
+        || remote === '::1'
+        || remote === '::ffff:127.0.0.1'
+      if (!loopback && !admittedByConnection(ctx, req)) {
+        res.statusCode = 403
+        res.setHeader('content-type', 'application/json; charset=utf-8')
+        res.end('{"ok":false,"error":"loopback-only"}')
+        return
+      }
+      const answer = (payload, status = 200) => {
+        res.statusCode = status
+        res.setHeader('content-type', 'application/json; charset=utf-8')
+        res.setHeader('cache-control', 'no-store')
+        res.end(JSON.stringify(payload))
+      }
+      const method = req && typeof req.method === 'string' ? req.method.toUpperCase() : 'GET'
+      if (method === 'GET') {
+        answer(sleepStatusPayload(sleep, config, runtime))
+        return
+      }
+      if (method !== 'POST') {
+        res.statusCode = 405
+        res.setHeader('content-type', 'application/json; charset=utf-8')
+        res.setHeader('allow', 'GET, POST')
+        res.end('{"ok":false,"error":"method-not-allowed"}')
+        return
+      }
+      void readJsonBody(req).then((payload) => {
+        const body = payload && typeof payload === 'object' ? payload : {}
+        const action = typeof body.action === 'string' ? body.action.trim() : ''
+        if (action !== 'arm' && action !== 'cancel') {
+          answer({
+            ok: false,
+            error: 'unknown-action',
+            instruction: 'Send { "action": "arm" | "cancel" }.',
+          }, 400)
+          return
+        }
+        if (action === 'arm') {
+          // The intent is recorded too: it survives a restart.
+          sleep.arm()
+        } else {
+          sleep.cancel()
+        }
+        answer(sleepStatusPayload(sleep, config, runtime))
+      }).catch((error) => {
+        answer({ ok: false, error: describeError(error) }, 400)
+      })
+    },
+  }
+}
+
 /** Expose a tiny read-only health route for humans and verification scripts. */
-function registerHealthRoute(ctx, runtime, config) {
+function registerHealthRoute(ctx, runtime, config, sleep) {
   const routePath = typeof config.healthPath === 'string' && config.healthPath.startsWith('/')
     ? config.healthPath
     : '/__dsh_autorestart/health'
@@ -3345,6 +4515,11 @@ function registerHealthRoute(ctx, runtime, config) {
           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,
         })
@@ -3408,6 +4583,9 @@ function registerHealthRoute(ctx, runtime, config) {
             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
@@ -3417,6 +4595,10 @@ function registerHealthRoute(ctx, runtime, config) {
             // The route that persists the one-time install choice, plus the
             // value that is effective right now.
             choiceUrl: resolveChoicePath(config),
+            // The route that reports (and records) the one-time feature
+            // announcements, so the client never has to guess the prefix.
+            announcementsUrl: resolveAnnouncementsPath(config),
+            backupOnRestart: config.backupOnRestart !== false,
             backupIncludePlugins: config.backupIncludePlugins !== false,
             parkedGoals: parkedGoalList(runtime),
             recovery: recoveryList(live),
@@ -3433,6 +4615,8 @@ function registerHealthRoute(ctx, runtime, config) {
             parkUrl: resolveParkPath(config),
             recoverUrl: resolveRecoverPath(config),
             choiceUrl: resolveChoicePath(config),
+            announcementsUrl: resolveAnnouncementsPath(config),
+            backupOnRestart: config.backupOnRestart !== false,
             backupIncludePlugins: config.backupIncludePlugins !== false,
             parkedGoals: [],
             recovery: [],
@@ -3491,6 +4675,8 @@ function registerHealthRoute(ctx, runtime, config) {
     const recoverRoute = buildRecoverRoute(ctx, runtime, config)
     const handoffRoute = buildHandoffRoute(ctx, runtime, config)
     const choiceRoute = buildChoiceRoute(ctx, runtime, config)
+    const announcementsRoute = buildAnnouncementsRoute(ctx, runtime, config)
+    const sleepRoute = sleep ? buildSleepRoute(ctx, runtime, config, sleep) : null
     try {
       const origin = typeof webServer.getOrigin === 'function' ? String(webServer.getOrigin()) : ''
       const portMatch = /:(\d+)\/?$/.exec(origin)
@@ -3522,6 +4708,18 @@ function registerHealthRoute(ctx, runtime, config) {
     } catch (error) {
       runtime.log.warn('could not register the choice route:', String(error))
     }
+    try {
+      target.effect(() => webServer.register(announcementsRoute), 'dsh-autorestart: announcements route')
+    } catch (error) {
+      runtime.log.warn('could not register the announcements route:', String(error))
+    }
+    if (sleepRoute !== null) {
+      try {
+        target.effect(() => webServer.register(sleepRoute), 'dsh-autorestart: sleep route')
+      } catch (error) {
+        runtime.log.warn('could not register the sleep route:', String(error))
+      }
+    }
     if (config.autoReloadPage !== false && typeof webServer.tapIndex === 'function') {
       try {
         target.effect(
@@ -3652,16 +4850,36 @@ function trackAgents(ctx, runtime, config) {
  * Plugin entry point.
  * @param ctx - Cordis plugin context.
  * @param rawConfig - the loader row config (merged over the built-in defaults).
+ * @param {{
+ *   sleepNow?: () => number,
+ *   sleepSpawn?: Function,
+ * }} [options] - the injectable primitives of the graceful sleep: they replace
+ *   the clock and the process spawner, so the whole flow can be driven without
+ *   waiting and without ever touching the machine. Production never passes them.
  */
-export function apply(ctx, rawConfig) {
+export function apply(ctx, rawConfig, options = {}) {
   const config = normalizeConfig(rawConfig)
   // The one-time install choice lives in the profile row config (the single
   // source of truth). Only when the row does not set the key at all does the
   // degraded fallback file get a say.
-  const choice = resolveBackupIncludePlugins(rawConfig, resolveStateDir(config))
+  const stateDir = resolveStateDir(config)
+  const choice = resolveBackupIncludePlugins(rawConfig, stateDir)
   config.backupIncludePlugins = choice.includePlugins
-  const runtime = createRuntime(ctx, config, { backupChoiceSource: choice.source })
+  // The same rule for the pre-restart backup itself: the profile row decides,
+  // the fallback file fills the gap, the built-in default applies otherwise.
+  const backupChoice = resolveBackupOnRestart(rawConfig, stateDir)
+  config.backupOnRestart = backupChoice.backupOnRestart
+  // The same rule for the graceful-sleep button: the profile row decides, the
+  // fallback file fills the gap, the built-in default applies otherwise.
+  const sleepChoice = resolveShowSleepButton(rawConfig, stateDir)
+  config.showSleepButton = sleepChoice.showSleepButton
+  const runtime = createRuntime(ctx, config, {
+    backupChoiceSource: choice.source,
+  })
   const log = runtime.log
+  // The graceful sleep: the host plan and the state machine that waits for the
+  // conversations, counts down and switches the machine off.
+  const sleep = createSleepService(ctx, runtime, config, options)
 
   log.info('activated', {
     stateFile: runtime.stateFile,
@@ -3671,8 +4889,15 @@ export function apply(ctx, rawConfig) {
     desktopApp: runtime.env.isDesktopApp,
     appExePath: runtime.env.appExePath,
     configSchema: Config !== undefined,
+    backupOnRestart: config.backupOnRestart,
     backupIncludePlugins: config.backupIncludePlugins,
     backupChoiceSource: choice.source,
+    showSleepButton: config.showSleepButton,
+    sleepChoiceSource: sleepChoice.source,
+    // The FINAL plan: what the sleep feature would really do.
+    sleepHost: sleep.invocation().kind,
+    sleepSource: sleep.invocation().source,
+    sleepSupported: sleep.invocation().supported,
   })
   if (Config === undefined) {
     log.warn('Config schema is unavailable in this build (schemastery could not be loaded); configuration still works through cordis.patch.yml and the built-in defaults')
@@ -3691,24 +4916,55 @@ export function apply(ctx, rawConfig) {
   // 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)
   registerManualRestartGuard(ctx, runtime, config)
   registerSystemPrompt(ctx, runtime)
-  registerHealthRoute(ctx, runtime, config)
+  registerHealthRoute(ctx, runtime, config, sleep)
 
   ctx.effect(() => () => {
     runtime.markDisposed()
     runtime.stopPolling()
+    // The countdown timer belongs to the plugin: it must not survive it.
+    sleep.controller.dispose()
     persistSafely(runtime)
   }, 'dsh-autorestart lifecycle')
 }
 
-export { DEFAULTS, normalizeConfig, resolveStateFile, resolveStateDir, resolveChoicePath }
+export {
+  DEFAULTS,
+  normalizeConfig,
+  resolveStateFile,
+  resolveStateDir,
+  resolveChoicePath,
+  resolveSleepPath,
+  resolveAnnouncementsPath,
+  featureAnnouncements,
+  pluginVersion,
+}