dsh-autorestart 0.7.0 → 0.8.1

package/index.js

@@ -19,9 +19,11 @@
  */
 
 import crypto from 'node:crypto'
+import { spawn } from 'node:child_process'
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
+import { fileURLToPath } from 'node:url'
 
 import {
   armSleep,
@@ -93,6 +95,48 @@ import {
 } from './lib/supervisor.js'
 import { composeFragment, detectInitSystems } from './lib/supervisor-install.js'
 import { classifyStartup } from './lib/startup-mode.js'
+import {
+  createDesktopShortcut,
+  desktopDir,
+  rescueInfo,
+  rescueScriptPaths,
+} from './lib/rescue-paths.js'
+import {
+  emptyCapabilities,
+  isCapabilities,
+  markSchedulerWarned,
+  probeSchedulerCapability,
+  SCHEDULER_UNKNOWN,
+  shouldWarnScheduler,
+} from './lib/scheduler-capability.js'
+import {
+  detectWatchdogCapabilities,
+  tierProvidesRollback,
+  tierWithProof,
+  TIERS,
+} from './lib/watchdog-tier.js'
+import {
+  buildPending,
+  clearReady,
+  readReady,
+  readReport,
+  writePending,
+  writeReady,
+  writeReport,
+} from './lib/watchdog.js'
+import {
+  ARBITERS,
+  planWatchdogArbiter,
+} from './lib/watchdog-arbiter.js'
+import {
+  cleanupSystemdUnit,
+  detachedPidPath,
+  localIso,
+  registerDetachedProcess,
+  registerScheduledTask,
+  registerSystemdRun,
+  removeScheduledTask,
+} from './lib/watchdog-schedule.js'
 import { detectHostKind } from './lib/host-kind.js'
 import { planAutostartAdvice } from './lib/autostart-advice.js'
 import { buildDiagnostics, ISSUE_URL_BASE, SUPPORT_EMAIL } from './lib/diagnostics.js'
@@ -146,6 +190,16 @@ import {
   snapCountdownChoice,
 } from './lib/sleep.js'
 
+/**
+ * THE PLUGIN DIRECTORY — where this very file lives.
+ *
+ * The rescue scripts (restore-profile.cmd, emergency-disable.cmd) sit next to
+ * it. The settings page shows the user that REAL path, so the path is taken
+ * from here and never guessed: nothing assumes `node_modules/dsh-autorestart`
+ * and nothing assumes a profile layout.
+ */
+const PLUGIN_DIR = path.dirname(fileURLToPath(import.meta.url))
+
 /**
  * The RESTART reserve: how long the host waits after the LAST conversation
  * finished before it is really restarted.
@@ -320,7 +374,7 @@ function snapGraceChoice(value, fallback = DEFAULT_RESTART_GRACE_MS) {
  * `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.7.0'
+const PLUGIN_VERSION_FALLBACK = '0.8.1'
 
 /**
  * The version of the graceful-shutdown FEATURE, not the version of the package.
@@ -614,6 +668,12 @@ 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.'),
+      // The watchdog: the process that waits for the relaunched host and puts
+      // the snapshot back when it never answers. It has to be triggered
+      // LATER, and the machine decides how (a one-off scheduled task, a
+      // systemd timer, or a detached process of our own).
+      watchdogEnabled: schemastery.boolean().default(true)
+        .description('Whether the watchdog may be armed before a restart: it waits for the new host and puts the snapshot back when it never answers. With it off there is no automatic rollback at all.'),
       // The self-starting supervisor: a separate process that brings the host
       // back when it dies. See the "开机自启" section of the settings.
       supervisorMode: schemastery.union(['auto', 'installed', 'external', 'off']).default('auto')
@@ -695,6 +755,11 @@ const DEFAULTS = {
   backupOnRestart: true,
   backupIncludePlugins: true,
   maxBackups: 2,
+  // The WATCHDOG: the process that waits for the relaunched host and puts the
+  // snapshot back when it never answers. It needs a way to be triggered
+  // later (a scheduled task, a systemd timer, a detached process) — the
+  // machine decides which one, and the settings page says which.
+  watchdogEnabled: true,
   rollbackTimeoutMs: 90000,
   // How long the restart command may run before the plugin stops waiting for
   // it, and how long ONE restore step may take before the watcher gives up.
@@ -1542,6 +1607,13 @@ export function createRuntime(ctx, config, options = {}) {
   const probeInstanceFn = typeof options.probeInstance === 'function'
     ? options.probeInstance
     : waitForHealthyInstance
+  // The NEW watchdog (v2). It is injected so a test can decide who is the
+  // arbiter of the restart WITHOUT registering anything on the machine.
+  // (The fallback is a wrapper: `armWatchdog` is declared further down, so it
+  // must not be READ here.)
+  const armWatchdogFn = typeof options.armWatchdog === 'function'
+    ? options.armWatchdog
+    : (...args) => armWatchdog(...args)
   const stateFile = resolveStateFile(config)
 
   const loaded = readState(stateFile, Date.now())
@@ -2658,6 +2730,225 @@ const titleOfSummary = (item) => {
     }
   }
 
+  /**
+   * WHERE THE RESCUE SCRIPTS ARE.
+   *
+   * The rescue kit is for everybody who installed the plugin: when DSH does
+   * not come up, the user cannot read a README — they need the path, and they
+   * need to be able to copy it. The browser cannot read the disk, so the Host
+   * resolves it: the plugin directory is where THIS file lives, and the
+   * scripts sit next to it.
+   *
+   * @returns {object}
+   */
+  const rescueKitInfo = () => rescueInfo({
+    pluginDir: PLUGIN_DIR,
+    env: process.env,
+    platform: env.platform,
+    exists: (target) => fs.existsSync(target),
+  })
+
+  /**
+   * THE CAPABILITIES of this machine: can it create a one-off scheduled
+   * task?
+   *
+   * The automatic rollback hangs on that answer: the host is restarted and a
+   * task that fires a minute later brings it back if it did not come up. On a
+   * machine where such a task cannot be created the safety net is silently
+   * missing — so the user is told what they lose.
+   *
+   * The answer is checked ONCE — the first time the plugin runs here — and
+   * then kept in a file of its own next to the state. It is NOT checked when
+   * the settings page opens: that would register a task every time somebody
+   * looks at the page.
+   *
+   * A failure of the probe is NEVER a failure of the plugin: the plugin
+   * works, only the safety net may be missing.
+   *
+   * @returns {object} the capabilities record
+   */
+  const capabilitiesInfo = () => {
+    const file = path.join(stateDirOf(), 'capabilities.json')
+    const stored = readCapabilitiesRecord(file)
+    if (stored) return stored
+    let checked
+    try {
+      checked = probeSchedulerCapability({ platform: env.platform })
+    } catch (error) {
+      checked = { scheduler: SCHEDULER_UNKNOWN, checkedAt: Date.now(), evidence: { error: String(error) } }
+    }
+    // The tier is decided by ONE function (lib/watchdog-tier.js), so the
+    // warning in the settings page and the watchdog that is really registered
+    // cannot drift apart.
+    let picked = { tier: TIERS.NONE, reason: 'this machine was not checked yet' }
+    try {
+      const caps = detectWatchdogCapabilities({ platform: env.platform })
+      picked = tierWithProof({
+        platform: env.platform,
+        probeOk: checked.scheduler === 'ok',
+        hasSystemdRun: caps.hasSystemdRun,
+        hasAt: caps.hasAt,
+        canDetach: caps.canDetach,
+      })
+    } catch (error) {
+      picked = { tier: TIERS.NONE, reason: 'the machine could not be checked: ' + String(error) }
+    }
+    const record = { ...emptyCapabilities(), ...checked, tier: picked.tier, tierReason: picked.reason }
+    // The warning is only for the TRANSITION into blocked: a machine that was
+    // blocked and stays blocked does not nag.
+    if (shouldWarnScheduler(emptyCapabilities(), record) && !tierProvidesRollback(picked.tier)) {
+      runtime.log.warn('this machine cannot run the watchdog: the automatic rollback is not available')
+    }
+    writeCapabilitiesRecord(file, record)
+    return record
+  }
+
+  /**
+   * THE WATCHDOG: which tier this machine uses, and what the last run did.
+   *
+   * @returns {{ enabled: boolean, tier: string, tierReason: string, available: boolean, report: object|null }}
+   */
+  const watchdogInfo = () => {
+    const capabilities = capabilitiesInfo()
+    const tier = typeof capabilities.tier === 'string' && capabilities.tier !== ''
+      ? capabilities.tier
+      : TIERS.NONE
+    const report = readReport(stateDirOf())
+    return {
+      enabled: config.watchdogEnabled !== false,
+      tier,
+      tierReason: typeof capabilities.tierReason === 'string' ? capabilities.tierReason : '',
+      available: tierProvidesRollback(tier),
+      report,
+    }
+  }
+
+  /**
+   * The capabilities with the warning marked as seen (the user read it).
+   *
+   * @returns {object}
+   */
+  const acknowledgeSchedulerWarning = () => {
+    const file = path.join(stateDirOf(), 'capabilities.json')
+    const stored = readCapabilitiesRecord(file) || { ...emptyCapabilities() }
+    const marked = markSchedulerWarned(stored)
+    writeCapabilitiesRecord(file, marked)
+    return marked
+  }
+
+  /**
+   * ARM THE WATCHDOG: the one-off thing that waits for the relaunched host.
+   *
+   * The tier is decided by ONE function (lib/watchdog-tier.js) — the same one
+   * that the settings page and the diagnostics ask — so the warning and the
+   * behaviour cannot drift apart. When no tier is available NOTHING is
+   * registered: there is no watchdog, and the report says so.
+   *
+   * @param {{
+   *   snapshotDir?: string,
+   *   profileDir?: string|null,
+   *   relaunchCommand?: object|null,
+   *   healthUrl?: string,
+   *   portFile?: string,
+   *   expectedBootId?: string|null,
+   * }} options
+   * @returns {{ ok: boolean, tier: string, reason: string, error: string|null }}
+   */
+  const armWatchdog = ({
+    snapshotDir = '',
+    profileDir = null,
+    relaunchCommand = null,
+    healthUrl = '',
+    portFile = '',
+    expectedBootId = null,
+  } = {}) => {
+    const stateDir = stateDirOf()
+    if (config.watchdogEnabled === false) {
+      return { ok: false, tier: TIERS.NONE, reason: 'the watchdog is switched off', error: null }
+    }
+    if (profileDir === null || snapshotDir === '') {
+      return { ok: false, tier: TIERS.NONE, reason: 'there is no snapshot to watch', error: null }
+    }
+    const info = watchdogInfo()
+    if (info.tier === TIERS.NONE) {
+      return { ok: false, tier: TIERS.NONE, reason: info.tierReason || 'this machine cannot run the watchdog', error: null }
+    }
+    const timeoutMs = Number(config.rollbackTimeoutMs) > 0 ? Number(config.rollbackTimeoutMs) : 180000
+    // ONE name for the scheduling item: a new registration replaces the old
+    // one, and there is never more than one of them on the machine.
+    const taskName = 'dsh-autorestart-watchdog'
+    const unitId = 'dsh-autorestart-watchdog'
+    const pidPath = detachedPidPath(stateDir)
+    const watchdogCommand = '"' + process.execPath + '" "' + path.join(PLUGIN_DIR, 'scripts', 'watchdog.mjs') + '" --state-dir "' + stateDir + '"'
+    const pending = buildPending({
+      tier: info.tier,
+      tierReason: info.tierReason,
+      taskName,
+      unitId,
+      pidPath,
+      snapshotDir,
+      profileDir,
+      relaunchCommand,
+      healthUrl,
+      healthPath: resolveHealthPath(config),
+      portFile,
+      expectedBootId,
+      timeoutMs,
+      recheckMs: 20000,
+      readyTimeoutMs: 90000,
+      hostKind: hostKindOf().kind,
+      now: Date.now(),
+    })
+    writePending(stateDir, pending)
+
+    let registered = { ok: false, error: 'the watchdog was not registered' }
+    try {
+      if (info.tier === TIERS.SCHEDULED_TASK) {
+        const start = new Date(Date.now() + Math.ceil(timeoutMs / 1000) * 1000);
+        const end = new Date(start.getTime() + 30 * 60 * 1000);
+        registered = registerScheduledTask({
+          taskName,
+          startIso: localIso(start),
+          endIso: localIso(end),
+          command: watchdogCommand,
+          xmlPath: path.join(stateDir, 'watchdog-task.xml'),
+        });
+      } else if (info.tier === TIERS.SYSTEMD_RUN) {
+        // The unit of an earlier run must be gone before a new one can take
+        // the name.
+        cleanupSystemdUnit({ unitId });
+        registered = registerSystemdRun({
+          unitId,
+          delaySeconds: Math.ceil(timeoutMs / 1000),
+          command: [process.execPath, path.join(PLUGIN_DIR, 'scripts', 'watchdog.mjs'), '--state-dir', stateDir],
+        });
+      } else if (info.tier === TIERS.DETACHED_PROCESS) {
+        registered = registerDetachedProcess({
+          delaySeconds: Math.ceil(timeoutMs / 1000),
+          command: process.execPath + ' "' + path.join(PLUGIN_DIR, 'scripts', 'watchdog.mjs') + '" --state-dir "' + stateDir + '"',
+          pidPath,
+        });
+      }
+    } catch (error) {
+      registered = { ok: false, error: error && error.message ? error.message : String(error) };
+    }
+    if (!registered || registered.ok !== true) {
+      // Nothing half-armed: the marker goes, and so does the scheduling item.
+      clearPending(stateDir);
+      try {
+        if (info.tier === TIERS.SCHEDULED_TASK) removeScheduledTask({ taskName });
+        else if (info.tier === TIERS.SYSTEMD_RUN) cleanupSystemdUnit({ unitId });
+      } catch {
+        // The next run cleans up.
+      }
+      const reason = (registered && registered.error) || 'the watchdog could not be registered';
+      log.warn('the watchdog was not armed: ' + reason);
+      return { ok: false, tier: info.tier, reason: info.tierReason, error: reason };
+    }
+    log.warn('the watchdog is armed (' + info.tier + '): ' + info.tierReason);
+    return { ok: true, tier: info.tier, reason: info.tierReason, error: null };
+  }
+
   /**
    * THE DIAGNOSTICS of "report a problem".
    *
@@ -2678,6 +2969,7 @@ const titleOfSummary = (item) => {
     restartMode: config.restartMode,
     lastRestart: lastRestartVerdict(),
     stateDir: stateDirOf(),
+    watchdog: watchdogInfo(),
   })
 
   /**
@@ -3165,6 +3457,37 @@ const titleOfSummary = (item) => {
     return { ok: true, method: result.method, error: null, scriptPath }
   }
 
+  /**
+   * Say in the report WHO is watching this restart.
+   *
+   * The v2 watchdog writes its own report when it acts. When v1 is the
+   * arbiter (v2 could not be armed), the host writes it right away — so
+   * `last-watchdog-report.json` always names the arbiter, and a problem can
+   * be read at a glance.
+   *
+   * @param {string} arbiter
+   * @param {string} reason
+   */
+  const writeArbiterReport = (arbiter, reason, tier = 'none') => {
+    try {
+      writeReport(stateDirOf(), {
+        at: new Date().toISOString(),
+        result: 'armed',
+        tier,
+        tierReason: reason || '',
+        arbiter,
+        waitedMs: 0,
+        rechecked: false,
+        restored: false,
+        relaunched: false,
+        ready: false,
+        error: null,
+      })
+    } catch (error) {
+      log.warn('could not write the arbiter report:', String(error))
+    }
+  }
+
   /** Execute the restart now; the detached helper survives our own death. */
   const executeRestart = async () => {
     stopPolling()
@@ -3228,6 +3551,30 @@ const titleOfSummary = (item) => {
       const backup = snapshot && snapshot.backup ? snapshot.backup : null
       const profileDir = snapshot && snapshot.profileDir ? snapshot.profileDir : null
 
+      // ARM THE WATCHDOG: it waits for the relaunched host, and when that
+      // host never answers, it puts the snapshot back and starts it again.
+      // Which way it is triggered is decided by the machine (the tier).
+      //
+      // The result matters: when v2 is armed, it is the ONLY watchdog. The
+      // old one (v1) is NOT started next to it — they take the same lock, and
+      // the one that loses it gives up. If v2 lost, the profile would be
+      // restored but nothing would be running any more.
+      const watchdogArm = backup && backup.ok === true && profileDir !== null
+        ? armWatchdogFn({
+          snapshotDir: backup.dir,
+          profileDir,
+          relaunchCommand: useCustomCommand && typeof config.restartCommand === 'string' && config.restartCommand.trim() !== ''
+            ? {
+              file: config.restartCommand.trim().split(/\s+/)[0],
+              args: config.restartCommand.trim().split(/\s+/).slice(1),
+            }
+            : (env.appExePath ? { file: env.appExePath, args: [] } : null),
+          healthUrl: restartHealthUrl(),
+          portFile: accessFilePath(stateDir),
+          expectedBootId: bootId,
+        })
+        : { ok: false, tier: TIERS.NONE, reason: 'there is no snapshot to watch', error: null }
+
       // THE DURABLE RESTART RECORD. The instance that is being replaced
       // writes the "pending" half BEFORE it runs the restart command: the
       // snapshot it took (directory, local time, duration, which older
@@ -3305,7 +3652,25 @@ const titleOfSummary = (item) => {
         // It is NOT armed when the supervisor of this plugin is in charge:
         // that one restores the snapshot itself, and two of them would write
         // the same files at the same time.
-        if (!detected.supervised) armRollbackWatcher({ backup, profileDir })
+        //
+        // It is NOT armed when the watchdog v2 is armed either: v2 does the
+        // same job AND starts the host again. Two watchdogs take the same
+        // lock, and the one that loses it gives up — if v2 lost, the profile
+        // would be restored but nothing would be running any more.
+        const arbiter = planWatchdogArbiter({
+          v2Armed: watchdogArm !== null && watchdogArm.ok === true,
+          supervised: detected.supervised,
+        })
+        if (arbiter.startV1 === true) {
+          armRollbackWatcher({ backup, profileDir })
+          writeArbiterReport(ARBITERS.V1, arbiter.reason, 'none')
+        } else if (arbiter.arbiter === ARBITERS.V2) {
+          writeArbiterReport(ARBITERS.V2, arbiter.reason, watchdogArm.tier)
+          log.warn('the watchdog v2 takes over: the old rollback watcher is NOT started', {
+            tier: watchdogArm.tier,
+            tierReason: watchdogArm.tierReason || '',
+          })
+        }
 
         try {
           // (2) THE COMMAND, with a real success judgement. The old code only
@@ -3398,9 +3763,26 @@ const titleOfSummary = (item) => {
         // The watcher does NOT need the port of the old instance (it reads the
         // port of the NEW one from the instance record), so it is armed as
         // soon as there is a snapshot and a profile directory.
-        const watchScriptPath = backup && backup.ok === true && profileDir !== null
+        //
+        // ONLY when the watchdog v2 could not be armed: v2 is the better
+        // watcher (it starts the host again), and two watchers take the same
+        // lock — the loser gives up.
+        const arbiter = planWatchdogArbiter({
+          v2Armed: watchdogArm !== null && watchdogArm.ok === true,
+          supervised: false,
+        })
+        const watchScriptPath = arbiter.startV1 === true && backup && backup.ok === true && profileDir !== null
           ? path.join(stateDir, 'restart-' + state.generation + '-watch.ps1')
           : null
+        if (arbiter.startV1 === true) {
+          writeArbiterReport(ARBITERS.V1, arbiter.reason, 'none')
+        } else if (arbiter.arbiter === ARBITERS.V2) {
+          writeArbiterReport(ARBITERS.V2, arbiter.reason, watchdogArm.tier)
+          log.warn('the watchdog v2 takes over: the old rollback watcher is NOT started', {
+            tier: watchdogArm.tier,
+            tierReason: watchdogArm.tierReason || '',
+          })
+        }
         const watchScript = watchScriptPath === null
           ? null
           : buildWatchScript({
@@ -3747,6 +4129,14 @@ const titleOfSummary = (item) => {
      * WHAT IS ON DISK RIGHT NOW: the backups of this host.
      */
     backupsInfo,
+    // Where the rescue scripts are, and whether the desktop shortcut exists.
+    rescueKitInfo,
+    // What this machine can do: can it create a one-off scheduled task? (The
+    // automatic rollback hangs on that answer.)
+    capabilitiesInfo,
+    acknowledgeSchedulerWarning,
+    // The watchdog: which tier this machine uses, and what the last run did.
+    watchdogInfo,
     /**
      * THE DIAGNOSTICS of "report a problem" (the text the user copies).
      */
@@ -6224,6 +6614,176 @@ function buildChoiceRoute(ctx, runtime, config) {
  * @param {object} config the normalized config
  * @returns {object} the route
  */
+/**
+ * Read the capabilities record of this machine.
+ *
+ * It lives in a file of its own next to the state: the checkpoint has a
+ * versioned shape, and a capability that is checked once does not belong in
+ * the record of the running sessions.
+ *
+ * @param {string} file
+ * @returns {object|null}
+ */
+function readCapabilitiesRecord(file) {
+  try {
+    const raw = fs.readFileSync(file, 'utf8')
+    const parsed = JSON.parse(raw)
+    if (!isCapabilities(parsed)) return null
+    return {
+      scheduler: parsed.scheduler,
+      checkedAt: typeof parsed.checkedAt === 'number' ? parsed.checkedAt : null,
+      evidence: parsed.evidence && typeof parsed.evidence === 'object' ? parsed.evidence : null,
+      warnedAt: typeof parsed.warnedAt === 'number' ? parsed.warnedAt : null,
+      tier: typeof parsed.tier === 'string' ? parsed.tier : '',
+      tierReason: typeof parsed.tierReason === 'string' ? parsed.tierReason : '',
+    }
+  } catch {
+    // A record that cannot be read is a record that does not exist yet.
+    return null
+  }
+}
+
+/**
+ * Write the capabilities record of this machine.
+ *
+ * @param {string} file
+ * @param {object} record
+ */
+function writeCapabilitiesRecord(file, record) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    fs.writeFileSync(file, JSON.stringify(record, null, 2), 'utf8')
+  } catch {
+    // A capability that cannot be written is a capability that is checked
+    // again next time — not a reason to break the plugin.
+  }
+}
+
+/**
+ * Resolve the rescue-route path: a sibling of the health route, under the same
+ * prefix.
+ *
+ * @param {object} config
+ * @returns {string}
+ */
+function resolveRescuePath(config) {
+  const healthPath = resolveHealthPath(config)
+  const index = healthPath.lastIndexOf('/')
+  const prefix = index > 0 ? healthPath.slice(0, index) : '/__dsh_autorestart'
+  return `${prefix}/rescue`
+}
+
+/**
+ * The rescue route: the two scripts, and the desktop shortcut.
+ *
+ * It does three things, all of them on behalf of the USER:
+ *
+ *   - `status`   : where the scripts are (the paths and the state of the
+ *                  desktop shortcut) — nothing is written;
+ *   - `shortcut` : write the desktop shortcut. This happens ONLY because the
+ *                  user pressed the button: loading the settings page never
+ *                  writes anything to the desktop;
+ *   - `reveal`   : open the folder of a script in the file manager.
+ *
+ * Like every other route of this plugin it only answers the loopback.
+ *
+ * @param {object} ctx
+ * @param {object} runtime
+ * @param {object} config
+ * @returns {{ kind: string, path: string, handler: Function }}
+ */
+function buildRescueRoute(ctx, runtime, config) {
+  const routePath = resolveRescuePath(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((payload) => {
+        const body = payload && typeof payload === 'object' ? payload : {}
+        const action = typeof body.action === 'string' ? body.action.trim() : 'status'
+        const info = runtime.rescueKitInfo()
+        if (action === 'shortcut') {
+          // The user pressed the button: NOW the shortcut may be written.
+          const written = createDesktopShortcut({
+            desktop: info.desktopDir,
+            restoreProfilePath: info.restoreProfile,
+            home: os.homedir(),
+            writeFile: (target, content) => fs.writeFileSync(target, content, 'ascii'),
+            exists: (target) => fs.existsSync(target),
+          })
+          res.statusCode = written.ok ? 200 : 400
+          res.setHeader('content-type', 'application/json; charset=utf-8')
+          res.setHeader('cache-control', 'no-store')
+          res.end(JSON.stringify({
+            ok: written.ok,
+            action,
+            path: written.path,
+            error: written.error ?? null,
+            rescue: runtime.rescueKitInfo(),
+          }))
+          return
+        }
+        if (action === 'ack-scheduler') {
+          // The user has read the warning about the missing automatic
+          // rollback: it is not shown again.
+          const marked = runtime.acknowledgeSchedulerWarning()
+          res.statusCode = 200
+          res.setHeader('content-type', 'application/json; charset=utf-8')
+          res.setHeader('cache-control', 'no-store')
+          res.end(JSON.stringify({ ok: true, action, capabilities: marked }))
+          return
+        }
+        if (action === 'reveal') {
+          const wanted = typeof body.path === 'string' ? body.path.trim() : ''
+          // Only a directory of the plugin may be opened — never anything the
+          // caller names.
+          const allowed = [info.scriptsDir].filter((entry) => entry !== '')
+          const folder = allowed.includes(wanted) ? wanted : info.scriptsDir
+          let opened = false
+          try {
+            const child = spawn(process.platform === 'win32' ? 'explorer.exe' : 'xdg-open', [folder], {
+              detached: true,
+              stdio: 'ignore',
+              windowsHide: true,
+            })
+            child.unref()
+            opened = true
+          } catch (error) {
+            opened = false
+          }
+          res.statusCode = opened ? 200 : 500
+          res.setHeader('content-type', 'application/json; charset=utf-8')
+          res.setHeader('cache-control', 'no-store')
+          res.end(JSON.stringify({ ok: opened, action, path: folder, error: opened ? null : 'the file manager could not be opened' }))
+          return
+        }
+        res.statusCode = 200
+        res.setHeader('content-type', 'application/json; charset=utf-8')
+        res.setHeader('cache-control', 'no-store')
+        res.end(JSON.stringify({ ok: true, action, rescue: info }))
+      })
+    },
+  }
+}
+
 function buildSupervisorRoute(ctx, runtime, config) {
   const routePath = resolveSupervisorPath(config)
   return {
@@ -6968,6 +7528,18 @@ function registerHealthRoute(ctx, runtime, config, sleep) {
             // where it lives). The browser cannot read the disk, so the Host
             // reads it — only the directory, never the contents.
             backups: runtime.backupsInfo(),
+            // THE RESCUE KIT: where the two scripts are, so a user whose DSH
+            // does not come up can find them (and copy the path) even though
+            // they cannot open a README.
+            rescue: runtime.rescueKitInfo(),
+            rescueUrl: resolveRescuePath(config),
+            // What this machine can do (the automatic rollback needs a
+            // one-off scheduled task; when that is refused the user is told
+            // what they lose).
+            capabilities: runtime.capabilitiesInfo(),
+            // The watchdog: which tier this machine uses to trigger it, and
+            // what the last run did.
+            watchdog: runtime.watchdogInfo(),
             // THE RESTART COMMAND that is in effect: what is written, and what
             // an undo would restore. The settings page shows it in a folded
             // "for a technical colleague" section.
@@ -7055,6 +7627,27 @@ function registerHealthRoute(ctx, runtime, config, sleep) {
         return
       }
       const probeIndex = typeof req.url === 'string' && req.url.includes('probeIndex=1')
+      // THE READY MARKER: this host answers its own health route, so it is
+      // up. The watchdog (which waits for the relaunched host) sees the
+      // marker and stands down — no rollback of a host that is fine.
+      try {
+        const marker = readReady(stateDirOf())
+        if (!marker || marker.bootId !== runtime.bootId) {
+          writeReady(stateDirOf(), { bootId: runtime.bootId, port: runtime.port ?? null })
+          // The host is up: the watchdog has nothing to do. Its scheduling
+          // item and its pending marker go NOW — nothing may be left behind.
+          if (readPending(stateDirOf()) !== null) {
+            clearPending(stateDirOf())
+            try {
+              removeScheduledTask({ taskName: 'dsh-autorestart-watchdog' })
+            } catch {
+              // The watchdog removes it itself when it runs.
+            }
+          }
+        }
+      } catch {
+        // The marker is a convenience: the watchdog also asks the health route.
+      }
       const body = JSON.stringify({
         ok: true,
         plugin: name,
@@ -7104,6 +7697,7 @@ function registerHealthRoute(ctx, runtime, config, sleep) {
     const cancelRoute = buildCancelRoute(ctx, runtime, config)
     const announcementsRoute = buildAnnouncementsRoute(ctx, runtime, config)
     const supervisorRoute = buildSupervisorRoute(ctx, runtime, config)
+    const rescueRoute = buildRescueRoute(ctx, runtime, config)
     const sleepRoute = sleep ? buildSleepRoute(ctx, runtime, config, sleep) : null
     try {
       const origin = typeof webServer.getOrigin === 'function' ? String(webServer.getOrigin()) : ''
@@ -7129,6 +7723,7 @@ function registerHealthRoute(ctx, runtime, config, sleep) {
       { name: 'cancel', route: cancelRoute },
       { name: 'announcements', route: announcementsRoute },
       { name: 'supervisor', route: supervisorRoute },
+      { name: 'rescue', route: rescueRoute },
     ]
     if (sleepRoute !== null) routes.push({ name: 'sleep', route: sleepRoute })
     for (const entry of routes) {