dsh-autorestart 0.3.5 → 0.5.0

package/index.js

@@ -73,6 +73,71 @@ import {
   runCommandNow,
   scheduleDetachedRestart,
 } from './lib/restart.js'
+import {
+  createSleepController,
+  COUNTDOWN_CHOICES,
+  DEFAULT_COUNTDOWN_SECONDS,
+  detectShutdownPlan,
+  planInvocation,
+  runShutdown,
+  snapCountdownChoice,
+} from './lib/sleep.js'
+
+/**
+ * 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.5.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,
@@ -173,6 +238,9 @@ export const inject = ['agents', 'goals', 'tools', 'timer', 'systemPrompt', 'ses
  * the real schema and project defaults; `normalizeConfig` still re-applies the same
  * defaults for direct `apply()` calls in tests.
  *
+ * Every key carries a one-sentence description, so the settings page explains what
+ * each knob does instead of showing a bare name.
+ *
  * Construction is guarded: a wrong/foreign schemastery fallback must never turn a
  * missing schema into a failed plugin activation, and the coarsened `schemasterySource`
  * is reported by the health route instead of an absolute install path.
@@ -181,38 +249,77 @@ function buildConfigSchema() {
   if (schemastery === undefined) return undefined
   try {
     return schemastery.object({
-      enabled: schemastery.boolean().default(true),
-      stateFile: schemastery.string().default(''),
-      resumeOnBoot: schemastery.boolean().default(true),
-      recoveryDelayMs: schemastery.number().min(0).default(6000),
-      maxSessions: schemastery.number().step(1).min(1).default(4),
-      maxResumeAttempts: schemastery.number().step(1).min(1).default(2),
-      deferPollMs: schemastery.number().min(250).default(3000),
-      deferSoftMs: schemastery.number().min(0).default(300000),
-      deferHardMs: schemastery.number().min(0).default(900000),
-      deferPolicy: schemastery.union(['auto', 'wait']).default('auto'),
+      enabled: schemastery.boolean().default(true)
+        .description('Master switch: when false the plugin loads but does nothing.'),
+      stateFile: schemastery.string().default('')
+        .description('Absolute path of the durable checkpoint file; empty means <DSH_HOME>/storages/dsh-autorestart/state.json.'),
+      resumeOnBoot: schemastery.boolean().default(true)
+        .description('Resume interrupted sessions automatically after the host starts again.'),
+      recoveryDelayMs: schemastery.number().min(0).default(6000)
+        .description('Milliseconds the plugin waits after boot before it recovers interrupted sessions.'),
+      maxSessions: schemastery.number().step(1).min(1).default(4)
+        .description('How many interrupted sessions one recovery pass resumes.'),
+      maxResumeAttempts: schemastery.number().step(1).min(1).default(2)
+        .description('How often a single session is retried before the recovery gives up on it.'),
+      deferPollMs: schemastery.number().min(250).default(3000)
+        .description('Milliseconds between two restart-gate checks.'),
+      deferSoftMs: schemastery.number().min(0).default(300000)
+        .description('Milliseconds after which a pending restart is announced as waiting for a long time.'),
+      deferHardMs: schemastery.number().min(0).default(900000)
+        .description('Milliseconds after which a pending restart gives up, unless forceRestartWhenBusy is enabled.'),
+      deferPolicy: schemastery.union(['auto', 'wait']).default('auto')
+        .description('How a pending restart treats a busy conversation: auto waits for it, wait blocks until every conversation is idle.'),
       // hard deadline only forces a restart over a running conversation when enabled
-      forceRestartWhenBusy: schemastery.boolean().default(false),
-      restartMode: schemastery.union(['app', 'command']).default('app'),
-      restartCommand: schemastery.string().default(''),
-      relaunchDelaySeconds: schemastery.number().min(0).default(2),
+      forceRestartWhenBusy: schemastery.boolean().default(false)
+        .description('Let the hard deadline restart the host even while a conversation is still running.'),
+      restartMode: schemastery.union(['app', 'command']).default('app')
+        .description('How the host is restarted: app relaunches the desktop app, command runs restartCommand.'),
+      restartCommand: schemastery.string().default('')
+        .description('Shell command used when restartMode is "command"; empty means there is no custom command.'),
+      relaunchDelaySeconds: schemastery.number().min(0).default(2)
+        .description('Seconds between the kill of the old host and the relaunch of the new one.'),
       // quiet window that must pass after the last conversation activity
-      settleMs: schemastery.number().min(0).default(2000),
-      autoReloadPage: schemastery.boolean().default(true),
-      blockManualRestart: schemastery.boolean().default(true),
-      healthPath: schemastery.string().default('/__dsh_autorestart/health'),
-      continuationText: schemastery.string().default(''),
+      settleMs: schemastery.number().min(0).default(2000)
+        .description('Milliseconds the host must stay quiet after the last conversation activity before a restart may fire.'),
+      autoReloadPage: schemastery.boolean().default(true)
+        .description('Reload the web page automatically when the host boot token changes.'),
+      blockManualRestart: schemastery.boolean().default(true)
+        .description('Block shell commands that would kill or relaunch DeepSeek Harness by hand.'),
+      healthPath: schemastery.string().default('/__dsh_autorestart/health')
+        .description('HTTP path of the read-only health route used by the client UI and by verification scripts.'),
+      continuationText: schemastery.string().default('')
+        .description('Custom text injected as the continuation message; empty means the built-in notice.'),
       // pause between two recovery batches (each batch resumes maxSessions sessions)
-      recoveryBatchDelayMs: schemastery.number().min(0).default(1200),
+      recoveryBatchDelayMs: schemastery.number().min(0).default(1200)
+        .description('Milliseconds between two recovery batches.'),
       // pause between two resolveAgent attempts inside one boot
-      resumeRetryDelayMs: schemastery.number().min(0).default(1000),
+      resumeRetryDelayMs: schemastery.number().min(0).default(1000)
+        .description('Milliseconds between two resolveAgent attempts inside one boot.'),
       // pre-restart snapshot + automatic rollback when the host never comes back
-      backupOnRestart: schemastery.boolean().default(true),
+      backupOnRestart: schemastery.boolean().default(true)
+        .description('Take a snapshot of the profile before every restart, so a host that cannot boot again is rolled back automatically.'),
       // include the installed plugin tree in the snapshot (bigger, but it makes a
       // rollback of "a plugin upgrade broke the boot" possible)
-      backupIncludePlugins: schemastery.boolean().default(true),
-      maxBackups: schemastery.number().step(1).min(1).default(2),
-      rollbackTimeoutMs: schemastery.number().min(1000).default(90000),
+      backupIncludePlugins: schemastery.boolean().default(true)
+        .description('Include the installed plugin tree in that snapshot: about 117 MB and roughly 3 extra seconds, but it is what makes a rollback of a broken plugin upgrade possible.'),
+      maxBackups: schemastery.number().step(1).min(1).default(2)
+        .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)}`
@@ -252,6 +359,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. */
@@ -276,6 +389,12 @@ 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)
+  if (typeof config.sleepCommand !== 'string') config.sleepCommand = ''
+  if (typeof config.showSleepButton !== 'boolean') config.showSleepButton = true
   return config
 }
 
@@ -328,6 +447,50 @@ function resolveHandoffPath(config) {
   return `${prefix}/handoff`
 }
 
+/**
+ * Resolve the choice-route path: a sibling of the health route, under the same
+ * prefix (`POST /choice` persists the one-time install choice of the user).
+ *
+ * @param {object} config
+ * @returns {string}
+ */
+function resolveChoicePath(config) {
+  const healthPath = resolveHealthPath(config)
+  const index = healthPath.lastIndexOf('/')
+  const prefix = index > 0 ? healthPath.slice(0, index) : '/__dsh_autorestart'
+  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
@@ -484,6 +647,157 @@ function resolveStateFile(config) {
   return path.join(home, 'storages', 'dsh-autorestart', 'state.json')
 }
 
+/**
+ * The directory the plugin owns its durable state in.
+ *
+ * It is the directory of the checkpoint file, so a custom `stateFile` moves the
+ * whole state directory with it (the backups live next to it as well).
+ *
+ * @param {object} config
+ * @returns {string}
+ */
+function resolveStateDir(config) {
+  return path.dirname(resolveStateFile(config))
+}
+
+/**
+ * The file the DEGRADED choice path writes to.
+ *
+ * It is only used when the official `configEditor` service is unavailable: the
+ * profile configuration stays the single source of truth, and this file is the
+ * last-resort record of a choice the Host could not persist yet.
+ */
+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}
+ */
+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 {
+      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,
+    }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 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 {{ includePlugins?: boolean, backupOnRestart?: boolean, showSleepButton?: boolean, sleepCountdownSeconds?: number }} values
+ * @returns {string} the file that was written
+ */
+function writeInstallChoice(stateDir, values) {
+  const file = path.join(stateDir, INSTALL_CHOICE_FILE)
+  const current = readInstallChoice(stateDir) || {
+    includePlugins: null,
+    backupOnRestart: null,
+    showSleepButton: null,
+    sleepCountdownSeconds: 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,
+    at: new Date().toISOString(),
+  }
+  fs.mkdirSync(stateDir, { recursive: true })
+  fs.writeFileSync(file, JSON.stringify(payload, null, 2), 'utf8')
+  return file
+}
+
+/**
+ * Resolve the effective `backupIncludePlugins` value and where it came from.
+ *
+ * The profile row config always wins: it is the single source of truth (the
+ * settings page and the one-time install prompt write the same key). Only when
+ * the row config does not set the key at all does the degraded fallback file
+ * get a say, and only when it does not exist does the built-in default apply.
+ *
+ * @param {object|null|undefined} rawConfig the loader row config, as received
+ * @param {string} stateDir
+ * @returns {{ includePlugins: boolean, source: 'config'|'fallback-file'|'default' }}
+ */
+export function resolveBackupIncludePlugins(rawConfig, stateDir) {
+  if (rawConfig && typeof rawConfig === 'object'
+    && Object.prototype.hasOwnProperty.call(rawConfig, 'backupIncludePlugins')
+    && typeof rawConfig.backupIncludePlugins === 'boolean') {
+    return { includePlugins: rawConfig.backupIncludePlugins, source: 'config' }
+  }
+  const fallback = typeof stateDir === 'string' && stateDir !== '' ? readInstallChoice(stateDir) : null
+  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.
  *
@@ -553,6 +867,76 @@ function resolveProfileDir() {
   return resolveProfileDirDetailed().dir
 }
 
+/**
+ * The pre-restart snapshot: copy the profile into `<stateDir>/backups/<stamp>/`
+ * and clear the rollback report an older boot may have left behind.
+ *
+ * This is the ONE backup entry of the plugin. EVERY restart mode takes its
+ * snapshot through this function — the desktop app relaunch AND the custom
+ * restart command — so a hosted host that is restarted by a command is just as
+ * recoverable as the desktop app. The configuration files decide whether every
+ * bundle loads, so a snapshot is what makes a "the host does not come back"
+ * rollback possible at all.
+ *
+ * A failing backup never blocks the restart: the reason is logged and the
+ * caller continues without a rollback point.
+ *
+ * @param {{
+ *   config?: object,
+ *   stateDir?: string,
+ *   log?: { warn: Function },
+ *   profile?: { dir?: string|null, source?: string },
+ *   createBackup?: Function,
+ * }} [options]
+ * @returns {{ backup: object|null, profileDir: string|null, profile: { dir: string|null, source: string } }}
+ */
+export function takePreRestartSnapshot({
+  config = {},
+  stateDir = '',
+  log = console,
+  profile = null,
+  createBackup: createBackupFn = createBackup,
+} = {}) {
+  const info = profile && typeof profile === 'object'
+    ? { dir: profile.dir ?? null, source: profile.source ?? 'unknown' }
+    : { dir: null, source: 'unknown' }
+  const profileDir = typeof info.dir === 'string' && info.dir.trim() !== '' ? info.dir : null
+  // The snapshot is optional: the operator can turn it off entirely.
+  if (config.backupOnRestart !== true) return { backup: null, profileDir, profile: info }
+  if (profileDir === null) {
+    log.warn('no profile directory is known; skipping the pre-restart backup', { source: info.source })
+    return { backup: null, profileDir: null, profile: info }
+  }
+  let backup = null
+  try {
+    backup = createBackupFn({
+      profileDir,
+      backupsDir: backupsRoot(stateDir),
+      includePlugins: config.backupIncludePlugins !== false,
+      maxBackups: config.maxBackups,
+    })
+  } catch (error) {
+    // A backup that throws must not take the restart down with it.
+    backup = { ok: false, error: String(error) }
+  }
+  if (backup && backup.ok === true) {
+    log.warn('pre-restart backup written', {
+      dir: backup.dir,
+      bytes: backup.bytes,
+      includePlugins: backup.includePlugins,
+      pruned: backup.pruned,
+      profileDirSource: info.source,
+    })
+    // A report from an older boot must not be mistaken for this one.
+    clearRollbackReport(stateDir)
+  } else {
+    log.warn('the pre-restart backup failed; continuing without a rollback point', {
+      error: backup && backup.error ? backup.error : 'unknown error',
+    })
+  }
+  return { backup, profileDir, profile: info }
+}
+
 /** A logger that never throws and never requires a particular Cordis logger shape. */
 function createLogger(ctx) {
   const logger = ctx.logger
@@ -596,10 +980,91 @@ function isRootAgent(ctx, agent) {
   }
 }
 
-/** The plugin's whole runtime state. */
-function createRuntime(ctx, config) {
+/**
+ * Resolve the official `configEditor` service, or null when it is unavailable.
+ *
+ * The service is optional: the plugin must load in a composition that does not
+ * provide it, and the one-time install choice then falls back to a file.
+ *
+ * @param {object} ctx
+ * @returns {any|null}
+ */
+function resolveConfigEditor(ctx) {
+  try {
+    if (ctx && ctx.configEditor && typeof ctx.configEditor.edit === 'function') return ctx.configEditor
+  } catch {}
+  try {
+    if (ctx && typeof ctx.get === 'function') {
+      const service = ctx.get('configEditor')
+      if (service && typeof service.edit === 'function') return service
+    }
+  } catch {}
+  return null
+}
+
+/**
+ * Find this plugin's own row among the profile entries.
+ *
+ * The service hands out the LOADER's own entries, so the row id lives in
+ * `entry.options.id` (the id the bundle layer inserts: `dsh-autorestart`).
+ * A projected entry (the shape the settings UI shows) carries the same id as
+ * `patchId` or `id`, so both are accepted as well.
+ *
+ * @param {any} editor the configEditor service
+ * @returns {any|null} the entry, or null when this plugin has no row
+ */
+function findOwnEntry(editor) {
+  let entries = []
+  try {
+    entries = typeof editor.entries === 'function' ? editor.entries() : []
+  } catch {
+    return null
+  }
+  if (!Array.isArray(entries)) return null
+  for (const entry of entries) {
+    if (!entry || typeof entry !== 'object') continue
+    const options = entry.options && typeof entry.options === 'object' ? entry.options : null
+    const candidates = [
+      options ? options.id : undefined,
+      entry.patchId,
+      entry.id,
+    ]
+    for (const candidate of candidates) {
+      if (candidate === undefined || candidate === null) continue
+      if (String(candidate) === name) return entry
+    }
+  }
+  return null
+}
+
+/**
+ * The plugin's whole runtime state.
+ *
+ * @param {object} ctx
+ * @param {object} config the normalized config
+ * @param {{
+ *   backupChoiceSource?: string,
+ *   env?: object,
+ *   snapshot?: Function,
+ *   runCommand?: Function,
+ *   scheduleDetached?: Function,
+ * }} [options] `env` replaces parts of the detected environment and the three
+ *   functions replace the side-effecting primitives of the restart path. They
+ *   exist so a restart can be exercised without spawning a process or touching
+ *   the real profile; production never passes them.
+ */
+export function createRuntime(ctx, config, options = {}) {
   const log = createLogger(ctx)
-  const env = detectEnvironment()
+  const env = {
+    ...detectEnvironment(),
+    ...(options.env && typeof options.env === 'object' ? options.env : {}),
+  }
+  // The ONE pre-restart snapshot entry: every restart mode uses it.
+  const snapshotFn = typeof options.snapshot === 'function' ? options.snapshot : takePreRestartSnapshot
+  const runCommandFn = typeof options.runCommand === 'function' ? options.runCommand : runCommandNow
+  const scheduleDetachedFn = typeof options.scheduleDetached === 'function'
+    ? options.scheduleDetached
+    : scheduleDetachedRestart
   const stateFile = resolveStateFile(config)
 
   const loaded = readState(stateFile, Date.now())
@@ -1246,7 +1711,32 @@ function createRuntime(ctx, config) {
     persist()
     log.warn('executing graceful restart', { generation: state.generation, pid: process.pid })
     try {
-      if (config.restartMode === 'command' && config.restartCommand.trim() !== '') {
+      // How the host is restarted: the custom command, or the desktop app.
+      const useCustomCommand = config.restartMode === 'command' && config.restartCommand.trim() !== ''
+      const canRelaunchDesktop = Boolean(env.isDesktopApp && env.appExePath)
+      if (!useCustomCommand && !canRelaunchDesktop) {
+        // No restart method at all (the host is not the desktop app and there is
+        // no custom command): nothing is restarted, so nothing is snapshotted
+        // either — there is no rollback point for a restart that never happens.
+        log.warn('no restart method available (not the desktop app and restartCommand is empty); leaving the checkpoint in place')
+        rollbackRestart('no restart method available')
+        return
+      }
+
+      // ONE snapshot for EVERY restart mode: the profile is copied BEFORE
+      // anything is killed, no matter how the host is restarted. The desktop
+      // app relaunch and the custom restart command share this single entry, so
+      // a hosted host that is restarted by a command is just as recoverable as
+      // the desktop app.
+      const stateDir = path.dirname(stateFile)
+      const snapshot = snapshotFn({
+        config,
+        stateDir,
+        log,
+        profile: resolveProfileDirDetailed(),
+      })
+
+      if (useCustomCommand) {
         const command = buildCustomCommand({
           template: config.restartCommand,
           pid: process.pid,
@@ -1254,9 +1744,10 @@ function createRuntime(ctx, config) {
           appExePath: env.appExePath || '',
         })
         log.warn('running custom restart command:', command)
-        const outcome = runCommandNow({ command })
+        // A failed snapshot never blocks the restart: the command runs anyway.
+        const outcome = runCommandFn({ command })
         if (outcome && outcome.ok === false) rollbackRestart(outcome.error || 'custom command failed')
-      } else if (env.isDesktopApp && env.appExePath) {
+      } else {
         const aborts = Number(state.restart.gateAborts) || 0
         const url = aborts > 20 ? null : restartGateUrl()
         if (aborts > 20) {
@@ -1264,37 +1755,9 @@ function createRuntime(ctx, config) {
         } else if (url === null) {
           log.warn('the web server port is unknown; scheduling an UNGATED restart (the helper cannot re-check the idle gate)')
         }
-        // Snapshot the profile BEFORE anything is killed: the configuration files
-        // decide whether every bundle loads, so a snapshot is what makes a
-        // "the host does not come back" rollback possible at all.
-        const stateDir = path.dirname(stateFile)
-        const profileInfo = resolveProfileDirDetailed()
-        const profileDir = profileInfo.dir
-        let backup = null
-        if (config.backupOnRestart === true && profileDir !== null) {
-          backup = createBackup({
-            profileDir,
-            backupsDir: backupsRoot(stateDir),
-            includePlugins: config.backupIncludePlugins !== false,
-            maxBackups: config.maxBackups,
-          })
-          if (backup.ok === true) {
-            log.warn('pre-restart backup written', {
-              dir: backup.dir,
-              bytes: backup.bytes,
-              includePlugins: backup.includePlugins,
-              pruned: backup.pruned,
-              profileDirSource: profileInfo.source,
-            })
-            // A report from an older boot must not be mistaken for this one.
-            clearRollbackReport(stateDir)
-          } else {
-            log.warn('the pre-restart backup failed; continuing without a rollback point', { error: backup.error })
-          }
-        } else if (config.backupOnRestart === true) {
-          log.warn('no profile directory is known; skipping the pre-restart backup', { source: profileInfo.source })
-        }
-
+        // The snapshot was already taken above (the shared entry).
+        const backup = snapshot && snapshot.backup ? snapshot.backup : null
+        const profileDir = snapshot && snapshot.profileDir ? snapshot.profileDir : null
         const healthUrl = restartHealthUrl()
         const watchScriptPath = backup && backup.ok === true && healthUrl !== null && profileDir !== null
           ? path.join(stateDir, 'restart-' + state.generation + '-watch.ps1')
@@ -1311,7 +1774,7 @@ function createRuntime(ctx, config) {
             // Only a crash log written after this point belongs to this restart.
             since: new Date().toISOString(),
           })
-        const result = scheduleDetachedRestart({
+        const result = scheduleDetachedFn({
           appExePath: env.appExePath,
           relaunchDelaySeconds: config.relaunchDelaySeconds,
           gateUrl: url,
@@ -1322,9 +1785,6 @@ function createRuntime(ctx, config) {
         log.warn('scheduled detached restart:', result)
         if (!result || result.ok !== true) rollbackRestart((result && result.error) || 'detached restart refused')
         else armGateWatchdog()
-      } else {
-        log.warn('no restart method available (not the desktop app and restartCommand is empty); leaving the checkpoint in place')
-        rollbackRestart('no restart method available')
       }
     } catch (error) {
       rollbackRestart(String(error))
@@ -1389,6 +1849,130 @@ function createRuntime(ctx, config) {
     }
   }
 
+  /**
+   * 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 }} 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
+    }
+    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.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.
+   *
+   * @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
@@ -1396,6 +1980,14 @@ function createRuntime(ctx, config) {
     get bootId() {
       return bootId
     },
+    /**
+     * Where the effective `backupIncludePlugins` value came from:
+     * `config` (the profile row), `fallback-file` (the degraded path) or
+     * `default` (nothing was ever chosen).
+     */
+    get backupChoiceSource() {
+      return options.backupChoiceSource || 'default'
+    },
     get isNewBoot() {
       return boot.isNewBoot
     },
@@ -1430,6 +2022,53 @@ function createRuntime(ctx, config) {
     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.
+     *
+     * @param {boolean} includePlugins
+     * @returns {Promise<{ applied: 'config'|'fallback-file', includePlugins: boolean }>}
+     */
+    async applyBackupChoice(includePlugins) {
+      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,
@@ -2145,7 +2784,8 @@ function registerTools(ctx, runtime, config) {
       + '("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, '
       + '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), the '
+      + 'the model context window (such a session is never auto-resumed), whether the pre-restart '
+      + 'backup also snapshots the installed plugins (backupIncludePlugins), the '
       + 'resolved state-file path, and the detected restart environment. Read-only.',
     parameters: {
       type: 'object',
@@ -2174,6 +2814,7 @@ function registerTools(ctx, runtime, config) {
           handoffs: { type: 'array', items: { type: 'object' } },
           profileDir: { type: 'string' },
           profileDirSource: { type: 'string' },
+          backupIncludePlugins: { type: 'boolean' },
           lastRollback: { type: 'object' },
           environment: { type: 'object' },
           sessions: { type: 'array', items: { type: 'object' } },
@@ -2201,6 +2842,8 @@ function registerTools(ctx, runtime, config) {
         // Where the pre-restart backup comes from (null dir = it would be skipped).
         profileDirSource: runtime.profileDir.source,
         ...(runtime.profileDir.dir ? { profileDir: runtime.profileDir.dir } : {}),
+        // Whether the pre-restart backup also snapshots the installed plugins.
+        backupIncludePlugins: config.backupIncludePlugins !== false,
         // Present only when the previous restart had to be rolled back.
         ...(runtime.lastRollback ? { lastRollback: runtime.lastRollback } : {}),
         environment: {
@@ -2906,8 +3549,533 @@ 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),
+ * 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, "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', ... }`:
+ * `applied` says where the choice landed — the profile configuration (the
+ * 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)
+  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
+      }
+      if (!req || req.method !== 'POST') {
+        res.statusCode = 405
+        res.setHeader('content-type', 'application/json; charset=utf-8')
+        res.setHeader('allow', 'POST')
+        res.end('{"ok":false,"error":"method-not-allowed"}')
+        return
+      }
+      void readJsonBody(req).then(async (payload) => {
+        const body = payload && typeof payload === 'object' ? payload : {}
+        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')
+        if (!hasInclude && !hasBackupInclude && !hasBackup && !hasShow && !hasSeconds) {
+          // 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 }.',
+          }))
+          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
+          res.setHeader('content-type', 'application/json; charset=utf-8')
+          res.setHeader('cache-control', 'no-store')
+          res.end(JSON.stringify({
+            ok: false,
+            error: 'includePlugins-must-be-boolean',
+            instruction: 'Send { "includePlugins": true | false }.',
+          }))
+          return
+        }
+        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
+        }
+        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
+        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
+        res.statusCode = 200
+        res.setHeader('content-type', 'application/json; charset=utf-8')
+        res.setHeader('cache-control', 'no-store')
+        res.end(JSON.stringify(answer))
+      }).catch((error) => {
+        res.statusCode = 500
+        res.setHeader('content-type', 'application/json; charset=utf-8')
+        res.end(JSON.stringify({ ok: false, error: describeError(error) }))
+      })
+    },
+  }
+}
+
+/**
+ * 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 restart gate itself is untouched: the restart feature keeps its quiet
+ * window exactly as it was.
+ *
+ * @param {object} runtime
+ * @returns {{ allow: boolean, reason: 'busy'|'quiet', blockedBy: any[] }}
+ */
+function sleepGate(runtime) {
+  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 }
+  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),
+    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,
+  }
+}
+
+/**
+ * The state of the graceful sleep, in the shape the client renders it.
+ *
+ * @param {{ plan: object, controller: object, invocation: () => object }} sleep
+ * @param {object} config
+ * @returns {object}
+ */
+function sleepStatusPayload(sleep, config) {
+  const status = sleep.controller.status()
+  const invocation = sleep.invocation()
+  return {
+    ok: true,
+    phase: status.phase,
+    armed: status.armed,
+    showSleepButton: config.showSleepButton !== false,
+    countdownSeconds: status.countdownSeconds,
+    /**
+     * 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))
+        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') {
+          sleep.controller.arm()
+        } else {
+          sleep.controller.cancel()
+        }
+        answer(sleepStatusPayload(sleep, config))
+      }).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'
@@ -3016,6 +4184,14 @@ function registerHealthRoute(ctx, runtime, config) {
             // the restart).
             parkUrl: resolveParkPath(config),
             recoverUrl: resolveRecoverPath(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),
           })
@@ -3030,6 +4206,10 @@ function registerHealthRoute(ctx, runtime, config) {
             quietForMs: 0,
             parkUrl: resolveParkPath(config),
             recoverUrl: resolveRecoverPath(config),
+            choiceUrl: resolveChoicePath(config),
+            announcementsUrl: resolveAnnouncementsPath(config),
+            backupOnRestart: config.backupOnRestart !== false,
+            backupIncludePlugins: config.backupIncludePlugins !== false,
             parkedGoals: [],
             recovery: [],
           })
@@ -3086,6 +4266,9 @@ function registerHealthRoute(ctx, runtime, config) {
     const parkRoute = buildParkRoute(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)
@@ -3112,6 +4295,23 @@ function registerHealthRoute(ctx, runtime, config) {
     } catch (error) {
       runtime.log.warn('could not register the handoff route:', String(error))
     }
+    try {
+      target.effect(() => webServer.register(choiceRoute), 'dsh-autorestart: choice route')
+    } 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(
@@ -3242,11 +4442,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)
-  const runtime = createRuntime(ctx, config)
+  // 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 stateDir = resolveStateDir(config)
+  const choice = resolveBackupIncludePlugins(rawConfig, stateDir)
+  config.backupIncludePlugins = choice.includePlugins
+  // 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,
@@ -3256,6 +4481,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')
@@ -3285,13 +4519,25 @@ export function apply(ctx, rawConfig) {
   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 }
+export {
+  DEFAULTS,
+  normalizeConfig,
+  resolveStateFile,
+  resolveStateDir,
+  resolveChoicePath,
+  resolveSleepPath,
+  resolveAnnouncementsPath,
+  featureAnnouncements,
+  pluginVersion,
+}