dsh-autorestart 0.6.1 → 0.7.0

package/index.js

@@ -26,6 +26,7 @@ import path from 'node:path'
 import {
   armSleep,
   beginBoot,
+  cancelOwnRestart,
   cancelRestart,
   clearSleep,
   disarmedRecord,
@@ -37,6 +38,7 @@ import {
   parkedRecord,
   pruneSessions,
   readState,
+  recordOnboarding,
   recoverableSessions,
   requestRestart,
   setContextOverflow,
@@ -62,20 +64,78 @@ import {
 } from './lib/lifecycle.js'
 import {
   backupsRoot,
+  claimRollbackLock,
   clearRollbackReport,
   createBackup,
+  listBackups,
   readRollbackReport,
+  releaseRollbackLock,
+  restoreBackup,
+  ROLLBACK_LOCK_NAME,
   ROLLBACK_REPORT_NAME,
 } from './lib/backup.js'
+import {
+  accessFilePath,
+  readAccessRecord,
+  resolveAccessUrl,
+  writeAccessRecord,
+} from './lib/access.js'
+import {
+  detectSupervisor,
+  installSupervisor,
+  planSupervisorInstall,
+  readSupervisorConfig,
+  requestSupervisorAction,
+  supervisorPaths,
+  supervisorStatus,
+  uninstallSupervisor,
+  writeRollbackRequest,
+} from './lib/supervisor.js'
+import { composeFragment, detectInitSystems } from './lib/supervisor-install.js'
+import { classifyStartup } from './lib/startup-mode.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'
+import { countBlockerTasks } from './lib/blockers.js'
+import {
+  buildDryRunPlan,
+  composeRestartFragment,
+  deriveStartCommand,
+  detectContainer,
+  detectExternalSupervisor,
+  inspectExternalSupervisor,
+  pickFreePort,
+} from './lib/supervisor-config.js'
+import {
+  buildRestartVerdict,
+  buildSnapshotRecord,
+  evaluateRestartChecks,
+  readRestartVerdict,
+  RESTART_RESULTS,
+  summarizeRestartVerdict,
+  writeRestartVerdict,
+} from './lib/restart-verdict.js'
+import { waitForHealthyInstance } from './lib/health.js'
 import {
   buildCustomCommand,
   buildWatchScript,
+  DEFAULT_COMMAND_TIMEOUT_MS,
+  DEFAULT_ROLLBACK_COPY_TIMEOUT_MS,
   DEFAULT_ROLLBACK_TIMEOUT_MS,
   detectEnvironment,
+  launchDetachedWatcher,
+  readProcessChain,
   runCommandNow,
   scheduleDetachedRestart,
+  writeTextFileAtomic,
 } from './lib/restart.js'
 import { compareSemver } from './lib/semver.js'
+import { isWorkSessionEvent } from './lib/activity.js'
+import {
+  createQueuedTracker,
+  DEFAULT_QUEUED_GRACE_MS,
+  normalizeQueuedGraceMs,
+} from './lib/queued.js'
 import {
   createSleepController,
   COUNTDOWN_CHOICES,
@@ -87,34 +147,160 @@ import {
 } from './lib/sleep.js'
 
 /**
- * The grace window: how long the host waits after the LAST conversation
- * finished before it is really restarted or switched off.
+ * The RESTART reserve: how long the host waits after the LAST conversation
+ * finished before it is really restarted.
  *
  * This plugin can only see the DSH agents. Other plugins (a memory plugin
  * that writes its notes a few seconds after the conversation ended, a summary,
  * an MCP callback) queue their work with a timer of their own — work that is
- * invisible here. A short, configurable grace window is left for it.
+ * invisible here. A short, configurable reserve window is left for it.
+ *
+ * The reserve belongs to the RESTART only: a restart is a daily operation, so
+ * it should happen as soon as the conversations are done. Default: none.
+ *
+ * The graceful shutdown has NO reserve of its own: it has a VISIBLE countdown
+ * (`sleepCountdownSeconds`), and that countdown IS the wait before the
+ * machine goes off. A second, invisible window next to it would only say the
+ * same thing twice — so there is none.
  *
  * The values are the ones the settings page offers (in milliseconds).
  */
-const GRACE_CHOICES_MS = Object.freeze([0, 3000, 5000, 10000, 20000, 30000])
+const GRACE_CHOICES_MS = Object.freeze([0, 5000, 10000, 20000, 30000, 60000])
+
+/** The RESTART reserve that is used when nothing was configured. */
+const DEFAULT_RESTART_GRACE_MS = 0
+
+/**
+ * How often the "the restart is waiting for a long time" line may be logged.
+ *
+ * The restart gate polls every few seconds, so an unthrottled line would
+ * flood the log with the same sentence. Once a minute is enough to say that
+ * the wait is still going on.
+ */
+const LONG_WAIT_LOG_INTERVAL_MS = 60000
+
+/**
+ * The marker the plugin writes when it has decided the restart ITSELF.
+ *
+ * The rollback watcher is the fallback for the case that the plugin dies
+ * with the host (a hosted restart kills the very process the plugin runs in).
+ * When the plugin survives the restart command, it decides alone — and writes
+ * this marker, so the watcher stands down instead of rolling back a restart
+ * that was fine.
+ */
+const RESTART_OUTCOME_FILE = 'restart-outcome.json'
 
-/** The grace window that is used when nothing was configured. */
-const DEFAULT_GRACE_MS = 10000
+/**
+ * The name of the rollback report of a restart that the plugin decided itself.
+ *
+ * It is the same file the detached watcher writes (`last-rollback.json`), so
+ * the interface shows the rollback either way.
+ */
+const RESTART_REPORT_NAME = ROLLBACK_REPORT_NAME
 
 /**
- * Snap a grace value onto the nearest offered choice.
+ * Resolve the connection service of the host, when it provides one.
+ *
+ * The connection service signs the access URL of the running host (the boot
+ * token). It is optional: a host without it still gets the plain origin.
+ *
+ * @param {any} ctx
+ * @returns {any|null}
+ */
+function resolveConnectionService(ctx) {
+  try {
+    if (ctx && ctx.connection && typeof ctx.connection.authenticatedUrl === 'function') return ctx.connection
+  } catch {}
+  try {
+    if (ctx && typeof ctx.get === 'function') {
+      const service = ctx.get('connection')
+      if (service && typeof service.authenticatedUrl === 'function') return service
+    }
+  } catch {}
+  return null
+}
+
+/**
+ * The access link of the running instance, or null.
+ *
+ * @param {any} runtime
+ * @returns {string|null}
+ */
+function accessUrlOf(runtime) {
+  try {
+    const record = runtime.accessRecord
+    if (record && typeof record.url === 'string' && record.url !== '') return record.url
+  } catch {}
+  return null
+}
+
+/**
+ * Publish the instance record of the running host.
+ *
+ * The record carries three things that nobody else knows:
+ *
+ *   - the PORT this instance listens on (the desktop app uses a random one,
+ *     so the port of the previous instance is worthless);
+ *   - the BOOT ID of this instance, so a watcher can tell "the new instance"
+ *     from "the old one";
+ *   - the ACCESS LINK with the boot token, so the user finds the working link
+ *     after a restart instead of being locked out by a 401.
+ *
+ * The file is written with the mode 0600: it holds a secret.
+ *
+ * @param {any} ctx the plugin context
+ * @param {any} runtime the runtime of this plugin
+ * @param {object} config the normalized config
+ * @param {string} origin the origin of the web server (`protocol//host:port`)
+ * @returns {{ ok: boolean, path: string|null, url: string|null, error: string|null }}
+ */
+function publishInstanceRecord(ctx, runtime, config, origin) {
+  const stateDir = path.dirname(runtime.stateFile)
+  try {
+    const { url, token } = resolveAccessUrl({
+      origin,
+      connection: resolveConnectionService(ctx),
+    })
+    const written = writeAccessRecord({
+      stateDir,
+      bootId: runtime.bootId,
+      pid: process.pid,
+      port: runtime.webPort,
+      url,
+      token,
+    })
+    if (!written.ok) {
+      runtime.log.warn('could not publish the instance record:', written.error)
+      return { ok: false, path: written.path, url, error: written.error }
+    }
+    runtime.log.info('the instance record was published', {
+      path: written.path,
+      port: runtime.webPort,
+      // The token itself is a secret: the record carries it, the log only
+      // says that there is one.
+      hasToken: Boolean(token),
+    })
+    return { ok: true, path: written.path, url, error: null }
+  } catch (error) {
+    runtime.log.warn('could not publish the instance record:', String(error))
+    return { ok: false, path: null, url: null, error: String(error) }
+  }
+}
+
+/**
+ * Snap a reserve value onto the nearest offered choice.
  *
  * A profile that carries a value that is not offered (a hand-edited row, an
  * older build) must not break the boot: the value is snapped onto the
  * nearest choice, exactly like the countdown length is.
  *
  * @param {unknown} value
+ * @param {number} [fallback] the value used when the input is not a number
  * @returns {number} one of {@link GRACE_CHOICES_MS}
  */
-function snapGraceChoice(value) {
+function snapGraceChoice(value, fallback = DEFAULT_RESTART_GRACE_MS) {
   const raw = Number(value)
-  if (!Number.isFinite(raw) || raw < 0) return DEFAULT_GRACE_MS
+  if (!Number.isFinite(raw) || raw < 0) return fallback
   let best = GRACE_CHOICES_MS[0]
   let bestDistance = Math.abs(raw - best)
   for (const choice of GRACE_CHOICES_MS) {
@@ -134,7 +320,7 @@ function snapGraceChoice(value) {
  * `pluginVersion()`), but a bundled installation may not ship that file — so
  * the constant below is the last resort. A test keeps the two in sync.
  */
-const PLUGIN_VERSION_FALLBACK = '0.6.1'
+const PLUGIN_VERSION_FALLBACK = '0.7.0'
 
 /**
  * The version of the graceful-shutdown FEATURE, not the version of the package.
@@ -155,6 +341,14 @@ const PLUGIN_VERSION_FALLBACK = '0.6.1'
  */
 const SLEEP_FEATURE_VERSION = '0.5.0'
 
+/**
+ * The version of the self-starting supervisor ("开机自启守护").
+ *
+ * The one-time question about it is bound to this version: a release never
+ * brings an answered question back.
+ */
+const SUPERVISOR_FEATURE_VERSION = '0.7.0'
+
 /** The cached version of this plugin (read once per process). */
 let pluginVersionCache = null
 
@@ -202,6 +396,8 @@ function featureAnnouncements() {
   return [
     // The graceful shutdown ("收工关机") and its moon button.
     { feature: 'sleep', version: SLEEP_FEATURE_VERSION },
+    // The self-starting supervisor ("开机自启守护").
+    { feature: 'supervisor', version: SUPERVISOR_FEATURE_VERSION },
   ]
 }
 
@@ -380,8 +576,19 @@ function buildConfigSchema() {
       // Other plugins queue work with timers of their own (a memory plugin
       // writing its notes, a summary, an MCP callback) and that work is
       // invisible here — so a short, configurable grace window is left for it.
-      restartGraceMs: schemastery.number().min(0).default(DEFAULT_GRACE_MS)
-        .description('Milliseconds to wait after the last conversation finished before the host is really restarted or switched off: the grace window for work other plugins queue with a timer (0 / 3 / 5 / 10 / 20 / 30 seconds, default 10).'),
+      // The RESTART reserve: the extra wait after the last conversation
+      // finished, before the host is really restarted. A restart is a daily
+      // operation, so the default is none (0 / 5 / 10 / 20 / 30 / 60 seconds).
+      restartGraceMs: schemastery.number().min(0).default(DEFAULT_RESTART_GRACE_MS)
+        .description('Milliseconds to wait after the last conversation finished before the host is really RESTARTED: the reserve for work other plugins queue with a timer (0 / 5 / 10 / 20 / 30 / 60 seconds, default 0 = no extra wait).'),
+      // The graceful shutdown has no reserve of its own: the visible countdown
+      // (sleepCountdownSeconds) IS the wait before the machine goes off.
+      // The upper bound of a QUEUED inbox message: a message that nobody
+      // claims within this window is stuck, and it stops blocking the restart.
+      // Without it a single unclaimed message kept the restart pending for
+      // ever (the "the restart never happens" defect).
+      queuedGraceMs: schemastery.number().min(0).default(DEFAULT_QUEUED_GRACE_MS)
+        .description('Milliseconds an unclaimed (queued) inbox message may block the restart: a message that is still unclaimed after this window is treated as stuck and no longer blocks the restart (0 = no upper bound, the old behaviour; default 60000).'),
       autoReloadPage: schemastery.boolean().default(true)
         .description('Reload the web page automatically when the host boot token changes.'),
       blockManualRestart: schemastery.boolean().default(true)
@@ -407,6 +614,30 @@ 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 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')
+        .description('Who starts this host: auto = nobody decided yet, installed = the supervisor of this plugin, external = your own way, off = no automatic start.'),
+      supervisorKind: schemastery.union([
+        schemastery.const(''),
+        schemastery.const('windows-schtasks'),
+        schemastery.const('windows-startup'),
+        schemastery.const('systemd-user'),
+        schemastery.const('systemd-system'),
+      ]).default('')
+        .description('Which form of the self-start record was installed (empty = the default of this platform).'),
+      supervisorRestartDelayMs: schemastery.number().min(0).default(3000)
+        .description('Milliseconds the supervisor waits before it starts the host again after it died.'),
+      supervisorRestartDelayMaxMs: schemastery.number().min(0).default(30000)
+        .description('The upper bound of that delay: the supervisor backs off further with every failed start, but never longer than this.'),
+      supervisorStartTimeoutMs: schemastery.number().min(1000).default(90000)
+        .description('Milliseconds the supervisor waits for the host to answer its health route before it restores the snapshot.'),
+      supervisorKillGraceMs: schemastery.number().min(0).default(15000)
+        .description('Milliseconds the supervisor waits between asking the host to stop and killing it.'),
+      supervisorPort: schemastery.number().min(0).default(0)
+        .description('The port the supervisor waits for to become free before it starts the host (0 = the port of the current instance).'),
+      supervisorAutoInstall: schemastery.boolean().default(false)
+        .description('Whether the one-time question may install the supervisor without asking again.'),
       // 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)
@@ -448,7 +679,11 @@ const DEFAULTS = {
   restartCommand: '',
   relaunchDelaySeconds: 2,
   settleMs: 2000,
-  restartGraceMs: DEFAULT_GRACE_MS,
+  restartGraceMs: DEFAULT_RESTART_GRACE_MS,
+  // The upper bound of a queued (unclaimed) inbox message: after this time it
+  // is treated as stuck and stops blocking the restart. 0 switches the
+  // protection off (the old behaviour: a queued message blocks for ever).
+  queuedGraceMs: DEFAULT_QUEUED_GRACE_MS,
   autoReloadPage: true,
   blockManualRestart: true,
   healthPath: '/__dsh_autorestart/health',
@@ -461,6 +696,19 @@ const DEFAULTS = {
   backupIncludePlugins: true,
   maxBackups: 2,
   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.
+  restartCommandTimeoutMs: DEFAULT_COMMAND_TIMEOUT_MS,
+  rollbackCopyTimeoutMs: DEFAULT_ROLLBACK_COPY_TIMEOUT_MS,
+  // The self-starting supervisor.
+  supervisorMode: 'auto',
+  supervisorKind: '',
+  supervisorRestartDelayMs: 3000,
+  supervisorRestartDelayMaxMs: 30000,
+  supervisorStartTimeoutMs: 90000,
+  supervisorKillGraceMs: 15000,
+  supervisorPort: 0,
+  supervisorAutoInstall: false,
   // 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).
@@ -491,13 +739,45 @@ function normalizeConfig(raw) {
   const rollbackTimeout = Number(config.rollbackTimeoutMs)
   config.rollbackTimeoutMs =
     Number.isFinite(rollbackTimeout) && rollbackTimeout >= 1000 ? Math.trunc(rollbackTimeout) : 90000
+  // How long the restart command may run, and how long ONE restore step may
+  // take. Both are bounded, so neither a hung command nor a hung `robocopy`
+  // can hold the restart for ever.
+  const commandTimeout = Number(config.restartCommandTimeoutMs)
+  config.restartCommandTimeoutMs =
+    Number.isFinite(commandTimeout) && commandTimeout >= 1000 ? Math.trunc(commandTimeout) : DEFAULT_COMMAND_TIMEOUT_MS
+  const copyTimeout = Number(config.rollbackCopyTimeoutMs)
+  config.rollbackCopyTimeoutMs =
+    Number.isFinite(copyTimeout) && copyTimeout >= 1000 ? Math.trunc(copyTimeout) : DEFAULT_ROLLBACK_COPY_TIMEOUT_MS
+  // The supervisor knobs: a wrong value must not break the boot, it falls back
+  // to the documented default.
+  if (!['auto', 'installed', 'external', 'off'].includes(config.supervisorMode)) config.supervisorMode = 'auto'
+  if (!['', 'windows-schtasks', 'windows-startup', 'systemd-user', 'systemd-system'].includes(config.supervisorKind)) {
+    config.supervisorKind = ''
+  }
+  const supervisorDelay = Number(config.supervisorRestartDelayMs)
+  config.supervisorRestartDelayMs = Number.isFinite(supervisorDelay) && supervisorDelay >= 0 ? Math.trunc(supervisorDelay) : 3000
+  const supervisorDelayMax = Number(config.supervisorRestartDelayMaxMs)
+  config.supervisorRestartDelayMaxMs =
+    Number.isFinite(supervisorDelayMax) && supervisorDelayMax >= 0 ? Math.trunc(supervisorDelayMax) : 30000
+  const supervisorStartTimeout = Number(config.supervisorStartTimeoutMs)
+  config.supervisorStartTimeoutMs =
+    Number.isFinite(supervisorStartTimeout) && supervisorStartTimeout >= 1000 ? Math.trunc(supervisorStartTimeout) : 90000
+  const supervisorKillGrace = Number(config.supervisorKillGraceMs)
+  config.supervisorKillGraceMs =
+    Number.isFinite(supervisorKillGrace) && supervisorKillGrace >= 0 ? Math.trunc(supervisorKillGrace) : 15000
+  const supervisorPort = Number(config.supervisorPort)
+  config.supervisorPort = Number.isFinite(supervisorPort) && supervisorPort >= 0 ? Math.trunc(supervisorPort) : 0
+  if (typeof config.supervisorAutoInstall !== 'boolean') config.supervisorAutoInstall = false
   // The countdown of the graceful shutdown is one of the offered choices: a
   // profile that still carries an old value (15, 45, …) is snapped onto the
   // nearest one instead of breaking, and 0 means "no countdown at all".
   config.sleepCountdownSeconds = snapCountdownChoice(config.sleepCountdownSeconds)
-  // The grace window is one of the offered choices as well: a hand-edited
+  // The restart reserve is one of the offered choices as well: a hand-edited
   // profile value is snapped onto the nearest one instead of breaking.
-  config.restartGraceMs = snapGraceChoice(config.restartGraceMs)
+  config.restartGraceMs = snapGraceChoice(config.restartGraceMs, DEFAULT_RESTART_GRACE_MS)
+  // The upper bound of a queued message is a plain number: a wrong or negative
+  // value falls back to the default, and 0 switches the protection off.
+  config.queuedGraceMs = normalizeQueuedGraceMs(config.queuedGraceMs)
   if (typeof config.sleepCommand !== 'string') config.sleepCommand = ''
   if (typeof config.showSleepButton !== 'boolean') config.showSleepButton = true
   return config
@@ -566,6 +846,21 @@ function resolveChoicePath(config) {
   return `${prefix}/choice`
 }
 
+/**
+ * Resolve the supervisor-route path: a sibling of the health route, under the
+ * same prefix (`POST /supervisor` installs, uninstalls and reports the
+ * self-starting supervisor).
+ *
+ * @param {object} config
+ * @returns {string}
+ */
+function resolveSupervisorPath(config) {
+  const healthPath = resolveHealthPath(config)
+  const index = healthPath.lastIndexOf('/')
+  const prefix = index > 0 ? healthPath.slice(0, index) : '/__dsh_autorestart'
+  return `${prefix}/supervisor`
+}
+
 /**
  * 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`
@@ -581,6 +876,20 @@ function resolveSleepPath(config) {
   return `${prefix}/sleep`
 }
 
+/**
+ * Resolve the cancel-route path: a sibling of the health route, under the same
+ * prefix (`POST /cancel` withdraws ONE session's own restart request).
+ *
+ * @param {object} config
+ * @returns {string}
+ */
+function resolveCancelPath(config) {
+  const healthPath = resolveHealthPath(config)
+  const index = healthPath.lastIndexOf('/')
+  const prefix = index > 0 ? healthPath.slice(0, index) : '/__dsh_autorestart'
+  return `${prefix}/cancel`
+}
+
 /**
  * Resolve the announcements-route path: a sibling of the health route, under
  * the same prefix (`GET /announcements` reports the feature announcements the
@@ -977,6 +1286,20 @@ function resolveProfileDir() {
   return resolveProfileDirDetailed().dir
 }
 
+/**
+ * THE BACKUPS DIRECTORY.
+ *
+ * It is built in exactly ONE place: the snapshot writes here, and the
+ * settings page reads here. Two places would mean two answers to "where do
+ * the backups live".
+ *
+ * @param {string} dir the state directory
+ * @returns {string}
+ */
+function backupsDirFor(dir) {
+  return backupsRoot(typeof dir === 'string' ? dir : '')
+}
+
 /**
  * The pre-restart snapshot: copy the profile into `<stateDir>/backups/<stamp>/`
  * and clear the rollback report an older boot may have left behind.
@@ -989,7 +1312,10 @@ function resolveProfileDir() {
  * rollback possible at all.
  *
  * A failing backup never blocks the restart: the reason is logged and the
- * caller continues without a rollback point.
+ * caller continues without a rollback point. It is NOT silent though: the
+ * facts of the snapshot (was one asked for, was one taken, which directory,
+ * how long it took, which older snapshots were pruned) travel with the answer,
+ * so the restart record can tell the operator what the rollback net is.
  *
  * @param {{
  *   config?: object,
@@ -998,7 +1324,14 @@ function resolveProfileDir() {
  *   profile?: { dir?: string|null, source?: string },
  *   createBackup?: Function,
  * }} [options]
- * @returns {{ backup: object|null, profileDir: string|null, profile: { dir: string|null, source: string } }}
+ * @returns {{
+ *   backup: object|null,
+ *   profileDir: string|null,
+ *   profile: { dir: string|null, source: string },
+ *   requested: boolean,
+ *   durationMs: number,
+ *   error: string|null,
+ * }}
  */
 export function takePreRestartSnapshot({
   config = {},
@@ -1007,21 +1340,31 @@ export function takePreRestartSnapshot({
   profile = null,
   createBackup: createBackupFn = createBackup,
 } = {}) {
+  const startedAt = Date.now()
   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 (config.backupOnRestart !== true) {
+    return { backup: null, profileDir, profile: info, requested: false, durationMs: 0, error: null }
+  }
   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 }
+    return {
+      backup: null,
+      profileDir: null,
+      profile: info,
+      requested: true,
+      durationMs: Math.max(0, Date.now() - startedAt),
+      error: 'no profile directory is known',
+    }
   }
   let backup = null
   try {
     backup = createBackupFn({
       profileDir,
-      backupsDir: backupsRoot(stateDir),
+      backupsDir: backupsDirFor(stateDir),
       includePlugins: config.backupIncludePlugins !== false,
       maxBackups: config.maxBackups,
     })
@@ -1029,9 +1372,14 @@ export function takePreRestartSnapshot({
     // A backup that throws must not take the restart down with it.
     backup = { ok: false, error: String(error) }
   }
+  const durationMs = Math.max(0, Date.now() - startedAt)
   if (backup && backup.ok === true) {
     log.warn('pre-restart backup written', {
       dir: backup.dir,
+      stamp: backup.stamp,
+      at: backup.at,
+      atLocal: backup.atLocal,
+      durationMs,
       bytes: backup.bytes,
       includePlugins: backup.includePlugins,
       pruned: backup.pruned,
@@ -1044,7 +1392,14 @@ export function takePreRestartSnapshot({
       error: backup && backup.error ? backup.error : 'unknown error',
     })
   }
-  return { backup, profileDir, profile: info }
+  return {
+    backup,
+    profileDir,
+    profile: info,
+    requested: true,
+    durationMs,
+    error: backup && backup.ok === true ? null : (backup && backup.error ? backup.error : 'unknown error'),
+  }
 }
 
 /** A logger that never throws and never requires a particular Cordis logger shape. */
@@ -1158,7 +1513,9 @@ function findOwnEntry(editor) {
  *   snapshot?: Function,
  *   runCommand?: Function,
  *   scheduleDetached?: Function,
- * }} [options] `env` replaces parts of the detected environment and the three
+ *   launchWatcher?: Function,
+ *   probeInstance?: Function,
+ * }} [options] `env` replaces parts of the detected environment and the
  *   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.
@@ -1175,6 +1532,16 @@ export function createRuntime(ctx, config, options = {}) {
   const scheduleDetachedFn = typeof options.scheduleDetached === 'function'
     ? options.scheduleDetached
     : scheduleDetachedRestart
+  // The rollback watcher is started OUTSIDE the host process, so it survives the
+  // death of the host — which is what a hosted restart does.
+  const launchWatcherFn = typeof options.launchWatcher === 'function'
+    ? options.launchWatcher
+    : launchDetachedWatcher
+  // The health confirmation of the new instance (in-process; the detached
+  // watcher has its own, outside the host).
+  const probeInstanceFn = typeof options.probeInstance === 'function'
+    ? options.probeInstance
+    : waitForHealthyInstance
   const stateFile = resolveStateFile(config)
 
   const loaded = readState(stateFile, Date.now())
@@ -1188,6 +1555,20 @@ export function createRuntime(ctx, config, options = {}) {
   state = boot.state
   const bootId = state.bootId
 
+  // THE INSTANCE RECORD exists from the first moment of this boot: it carries
+  // the boot id (which tells the rollback watcher that this instance is the
+  // one being replaced). As soon as the web server is known, the record is
+  // written again — with the port of this instance and its access link.
+  try {
+    writeAccessRecord({
+      stateDir: path.dirname(stateFile),
+      bootId,
+      pid: process.pid,
+    })
+  } catch (error) {
+    log.warn('could not write the instance record:', String(error))
+  }
+
   let pollTimer
   let recoverTimer
   let disposed = false
@@ -1197,6 +1578,12 @@ export function createRuntime(ctx, config, options = {}) {
    * logged, never thrown: the plugin still loads and the other tools still work.
    */
   const toolErrors = []
+  /**
+   * The routes of this plugin that the web server accepted, and the ones it
+   * refused. The boot check of the restart record reports them.
+   */
+  const registeredRoutes = []
+  const routeErrors = []
 
   const persist = () => {
     try {
@@ -1233,7 +1620,43 @@ export function createRuntime(ctx, config, options = {}) {
   /** When the last conversation activity was observed; the settle window starts here. */
   let lastActivityAt = Date.now()
 
-  /** Record conversation activity (any agent turn, session event or queued message). */
+  /**
+   * When a busy conversation was seen for the last time.
+   *
+   * The quiet window measures the time since the last REAL work: a running
+   * turn or a queued message. The host polls the agent list every few
+   * seconds, so this marker follows the work exactly — and it is NOT reset by
+   * the routine session events the interface produces while it synchronises
+   * (those used to reset the window every 2-3 seconds, so a window longer
+   * than that interval could never fill and the restart never fired).
+   */
+  let lastBusyAt = 0
+
+  /**
+   * When the "the restart is waiting for a long time" line was logged last.
+   *
+   * The gate polls every few seconds, so the line is rate limited: at most one
+   * per minute for the SAME restart request. A new request (`requestedAt`
+   * changed) logs right away.
+   */
+  let longWaitLog = { at: 0, requestedAt: 0 }
+
+  /**
+   * When the diagnostic line of the restart gate was logged last.
+   *
+   * The gate is evaluated every few seconds, so the line is rate limited to
+   * once a minute: it says what the gate decided and why, which is the first
+   * thing to look at when "the restart never happens" is reported.
+   */
+  let lastDecisionLogAt = 0
+
+  /**
+   * Record REAL conversation activity (an agent turn that started or ended, a
+   * message that was queued, a session event that says work happened).
+   *
+   * The routine session events of the interface do NOT go through here: they
+   * would keep the quiet window from ever filling.
+   */
   const noteActivity = () => {
     lastActivityAt = Date.now()
   }
@@ -1253,6 +1676,53 @@ export function createRuntime(ctx, config, options = {}) {
     return count
   }
 
+  /**
+   * A short human-readable duration for the log ("45s", "2m 5s", "1h 3m").
+   *
+   * @param {number} ms
+   * @returns {string}
+   */
+  const describeWait = (ms) => {
+    const total = Math.max(0, Math.round(Number(ms) || 0))
+    const seconds = Math.floor(total / 1000)
+    if (seconds < 60) return `${seconds}s`
+    const minutes = Math.floor(seconds / 60)
+    if (minutes < 60) {
+      const rest = seconds % 60
+      return rest === 0 ? `${minutes}m` : `${minutes}m ${rest}s`
+    }
+    const hours = Math.floor(minutes / 60)
+    const restMinutes = minutes % 60
+    return restMinutes === 0 ? `${hours}h` : `${hours}h ${restMinutes}m`
+  }
+
+  /**
+   * The readable names of the sessions that hold the restart.
+   *
+   * A session without a title falls back to its id: the log has to say WHO
+   * holds the restart, and an empty name would say nothing.
+   *
+   * @param {any[]} blockedBy
+   * @returns {string}
+   */
+  const describeBlockers = (blockedBy) => {
+    const list = Array.isArray(blockedBy) ? blockedBy : []
+    const names = []
+    for (const entry of list) {
+      if (!entry || typeof entry !== 'object') continue
+      const name = typeof entry.name === 'string' && entry.name.trim() !== ''
+        ? entry.name.trim()
+        : (typeof entry.label === 'string' && entry.label.trim() !== ''
+          ? entry.label.trim()
+          : String(entry.sessionId || ''))
+      if (name === '') continue
+      names.push(name)
+    }
+    if (names.length === 0) return 'another conversation'
+    if (names.length === 1) return names[0]
+    return names.join(', ')
+  }
+
   /**
    * Whether this agent is a subagent (a delegated child), and which session
    * created it.
@@ -1329,10 +1799,28 @@ export function createRuntime(ctx, config, options = {}) {
     }
   }
 
+  /**
+   * The tracker of the QUEUED messages.
+   *
+   * It remembers for how long a session has had an unclaimed inbox message, so
+   * a message that nobody claims stops blocking the restart instead of
+   * blocking it for ever. A session that is RUNNING is never judged here: a
+   * live turn always blocks, under every grace setting.
+   */
+  const queuedTracker = createQueuedTracker()
+
+  /** The sessions the tracker saw in the last round (for the cleanup). */
+  const queuedSessions = new Set()
+
   /**
    * Every conversation that is still working, subagents and teammates included.
    * 'running' is a live turn; 'queued' is inbox work that has not started yet.
    *
+   * A queued message only blocks the restart until the grace window
+   * (`queuedGraceMs`) is over: after that it is stuck — nobody will ever claim
+   * it — so it stops blocking the restart and is named in the log. A running
+   * conversation ALWAYS blocks.
+   *
    * Every entry carries the kind of the blocker and a readable name, so the
    * interface can tell a session from a subagent and never has to show a raw
    * session id.
@@ -1345,15 +1833,52 @@ export function createRuntime(ctx, config, options = {}) {
     } catch {
       agents = []
     }
+    const seen = new Set()
     for (const agent of agents) {
       try {
         if (!agent || !agent.id) continue
         const sessionId = String(agent.id)
+        seen.add(sessionId)
         const described = describeBlocker(sessionId, agent)
-        if (agent.status === 'running') out.push({ sessionId, reason: 'running', ...described })
-        else if (pendingInboxCount(agent) > 0) out.push({ sessionId, reason: 'queued', ...described })
+        if (agent.status === 'running') {
+          // A live turn ALWAYS blocks the restart — under every grace
+          // setting. The queued timer of that session is dropped: the work is
+          // being done, so it is not a stuck queue.
+          queuedTracker.forget(sessionId)
+          out.push({ sessionId, reason: 'running', ...described })
+        } else if (pendingInboxCount(agent) > 0) {
+          const observed = queuedTracker.observe(sessionId, true, config.queuedGraceMs)
+          if (observed.becameStale) {
+            // The message has been waiting longer than the grace window and
+            // nobody claimed it: it is stuck. The session is named here, so
+            // the user can see WHICH conversation holds the queue.
+            log.warn(
+              `the queued message of session ${sessionId} has been waiting ${describeWait(observed.ageMs)} and nobody claimed it; it no longer blocks the restart`,
+              {
+                sessionId,
+                ageMs: observed.ageMs,
+                queuedGraceMs: config.queuedGraceMs,
+              },
+            )
+          }
+          if (observed.blocking) out.push({ sessionId, reason: 'queued', ...described })
+        } else {
+          // No queued work any more: the timer of that session is dropped, so
+          // a NEW queue starts counting from zero.
+          queuedTracker.observe(sessionId, false, config.queuedGraceMs)
+        }
       } catch {}
     }
+    // A session that is gone (closed) drops its record as well.
+    for (const sessionId of queuedSessions) {
+      if (!seen.has(sessionId)) queuedTracker.forget(sessionId)
+    }
+    queuedSessions.clear()
+    for (const sessionId of seen) queuedSessions.add(sessionId)
+    // Real work is still going on: the quiet window starts over. This is the
+    // marker that makes the quiet window measure "since the last real work"
+    // instead of "since the last session event of any kind".
+    if (out.length > 0) lastBusyAt = Date.now()
     return out
   }
 
@@ -1695,13 +2220,33 @@ export function createRuntime(ctx, config, options = {}) {
    */
   const pendingRestart = () => state.restart !== null && state.restart !== undefined
 
-  /** How long the host has been quiet (no conversation activity at all). */
-  const quietForMs = () => Math.max(0, Date.now() - lastActivityAt)
+  /**
+   * The moment the quiet window started.
+   *
+   * It is the LATER of the two markers:
+   *   - `lastActivityAt`: the last real activity signal (a turn that started
+   *     or ended, a message that was queued);
+   *   - `lastBusyAt`: the last moment a conversation was seen working (a
+   *     running turn or a queued message).
+   *
+   * The routine session events of the interface (a title, a projection, a
+   * context request) are NOT activity: they arrive every two to three
+   * seconds, so counting them would keep the quiet window from ever filling
+   * — and the restart would never fire.
+   *
+   * @returns {number} a timestamp in milliseconds
+   */
+  const quietSince = () => Math.max(lastActivityAt, lastBusyAt)
+
+  /** How long the host has been quiet (no real conversation activity at all). */
+  const quietForMs = () => Math.max(0, Date.now() - quietSince())
 
   /**
-   * The grace window: how much longer the host waits after the last
-   * conversation finished, so that work other plugins queue with a timer (a
-   * memory plugin writing its notes, a summary) still gets its chance.
+   * The RESTART reserve: how much longer the host waits after the last
+   * conversation finished before it is really restarted.
+   *
+   * A restart is a daily operation, so the default is none: the host restarts
+   * as soon as the conversations are done and the settle window has passed.
    */
   const graceMs = () => config.restartGraceMs
 
@@ -1716,11 +2261,45 @@ export function createRuntime(ctx, config, options = {}) {
   /** The two-layer restart gate: no busy conversation AND a quiet window. */
   const gate = () => restartGate(state, {
     busyAgents: busyAgents(),
-    lastActivityAt,
+    lastActivityAt: quietSince(),
     now: Date.now(),
     settleMs: effectiveSettleMs(),
   })
 
+  /**
+   * The description of a LONG wait, or null when the restart is not waiting
+   * for the long time yet.
+   *
+   * A pending restart that passed the hard deadline while a conversation was
+   * still running is not "just a little longer": it is a long wait, and the
+   * user has to SEE it — how long it has been waiting, why, and who holds it.
+   * The request itself is never dropped: the restart stays pending and fires
+   * as soon as the gate is quiet again.
+   *
+   * @param {number} [now]
+   * @returns {{ since: number, reason: string, waitedMs: number, blockedBy: any[] }|null}
+   */
+  const longWaitInfo = (now = Date.now()) => {
+    const restart = state.restart
+    if (!restart || typeof restart !== 'object') return null
+    const requestedAt = Number.isFinite(restart.requestedAt) ? restart.requestedAt : 0
+    if (requestedAt <= 0) return null
+    const hardMs = Number.isFinite(config.deferHardMs) ? config.deferHardMs : 0
+    // The long wait begins when the hard deadline is reached.
+    const since = requestedAt + hardMs
+    if (now < since) return null
+    const verdict = gate()
+    if (verdict.allow) return null
+    const blockedBy = goalAwareBlockingDetails(runtime, verdict.blockedBy)
+    if (blockedBy.length === 0) return null
+    return {
+      since,
+      reason: 'hard-deadline-waiting-for-conversations',
+      waitedMs: Math.max(0, now - requestedAt),
+      blockedBy,
+    }
+  }
+
   /**
    * Cached session titles, used to label the blocking sessions in the
    * client's "pending restart" details panel.
@@ -1853,20 +2432,31 @@ const titleOfSummary = (item) => {
   }
 
   /**
-   * Release the continuation request of EVERY session that asked for the current
+   * Release the continuation request of the sessions that asked for the current
    * restart (cancel / give-up paths). Requests are coalesced into ONE restart, so
    * releasing only the last requester would leave the others pinned as pending.
+   *
+   * `only` releases EXACTLY those sessions — that is how one session withdraws
+   * its own request without touching the requests of the other sessions.
+   *
+   * @param {string[]|null} [only] the sessions to release; null = every requester
    */
-  const releaseRequesters = () => {
-    const restart = state.restart
-    if (!restart) return
+  const releaseRequesters = (only = null) => {
     const ids = new Set()
-    if (Array.isArray(restart.requesters)) {
-      for (const requester of restart.requesters) {
-        if (requester && typeof requester.sessionId === 'string' && requester.sessionId) ids.add(requester.sessionId)
+    if (Array.isArray(only)) {
+      for (const sessionId of only) {
+        if (typeof sessionId === 'string' && sessionId) ids.add(sessionId)
       }
+    } else {
+      const restart = state.restart
+      if (!restart) return
+      if (Array.isArray(restart.requesters)) {
+        for (const requester of restart.requesters) {
+          if (requester && typeof requester.sessionId === 'string' && requester.sessionId) ids.add(requester.sessionId)
+        }
+      }
+      if (typeof restart.bySessionId === 'string' && restart.bySessionId) ids.add(restart.bySessionId)
     }
-    if (typeof restart.bySessionId === 'string' && restart.bySessionId) ids.add(restart.bySessionId)
     for (const sessionId of ids) {
       const entry = state.sessions ? state.sessions[sessionId] : undefined
       if (!entry) continue
@@ -1937,6 +2527,644 @@ const titleOfSummary = (item) => {
     return 'http://127.0.0.1:' + port + resolveHealthPath(config)
   }
 
+  /**
+   * The state directory of this plugin (the checkpoint, the backups, the
+   * instance record and the helper scripts live next to each other).
+   */
+  const stateDirOf = () => path.dirname(stateFile)
+
+  /**
+   * The durable record of the last restart: the snapshot that was taken, the
+   * verdict of the new instance and its four boot checks.
+   *
+   * @returns {object|null} the summary (null when no restart happened yet)
+   */
+  const lastRestartVerdict = () => summarizeRestartVerdict(readRestartVerdict(stateDirOf()))
+
+  /**
+   * The version of THIS plugin (the one the user runs).
+   *
+   * @returns {string}
+   */
+  const pluginVersion = () => {
+    try {
+      const raw = fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')
+      const parsed = JSON.parse(raw)
+      return typeof parsed.version === 'string' && parsed.version !== '' ? parsed.version : 'unknown'
+    } catch {
+      return 'unknown'
+    }
+  }
+
+  /**
+   * Write (or update) the durable record of the restart.
+   *
+   * The record is written by BOTH halves of a restart: the instance that is
+   * replaced writes the `pending` half (with the snapshot), the instance that
+   * replaces it writes the final verdict. `skipIfFinalized` keeps the older
+   * instance from overwriting a verdict that the new one already wrote.
+   *
+   * @param {object} [patch] the fields to change
+   * @param {{ skipIfFinalized?: boolean }} [options]
+   * @returns {object|null} the record that is on disk now
+   */
+  const recordRestartVerdict = (patch = {}, options = {}) => {
+    const dir = stateDirOf()
+    let current = null
+    try {
+      current = readRestartVerdict(dir)
+    } catch {
+      current = null
+    }
+    if (options.skipIfFinalized === true
+      && current !== null
+      && current.bootId !== null
+      && current.result !== RESTART_RESULTS.PENDING) {
+      return current
+    }
+    const merged = buildRestartVerdict({ ...(current ?? {}), ...patch })
+    const written = writeRestartVerdict(dir, merged)
+    if (!written.ok) log.warn('could not write the restart record:', written.error)
+    return merged
+  }
+
+  /**
+   * WHICH MACHINE IS THIS?
+   *
+   * The same answer the graceful shutdown uses (`lib/host-kind.js`): Windows,
+   * WSL, a real Linux, a macOS. It matters for the autostart: inside WSL the
+   * "start at login" is a different thing (a systemd user unit + the linger,
+   * or a task on the Windows side), and the Docker/Compose answer of a
+   * container is simply wrong there.
+   *
+   * @returns {object} the host (kind, evidence, suspect, distro)
+   */
+  const hostKindOf = () => detectHostKind({ platform: env.platform, env: process.env })
+
+  /**
+   * THE PLATFORM GUIDE: how "start at login" works on THIS machine.
+   *
+   * Windows (a scheduled task, with the startup folder as the fallback),
+   * Linux (a systemd user unit + the linger hint), WSL (the same, or the two
+   * ways out when there is no systemd), a container (the orchestrator) and the
+   * unknown host (nothing, and no guessing). The answer is computed ONCE
+   * (the machine does not change while the host runs) and the settings page
+   * reads it.
+   *
+   * @returns {object} the advice (kind, reason, notes, commands, options)
+   */
+  let cachedAutostart = null
+  const autostartAdviceOf = () => {
+    if (cachedAutostart !== null) return cachedAutostart
+    const host = hostKindOf()
+    const init = detectInitSystems({ platform: env.platform, homeDir: os.homedir() })
+    cachedAutostart = planAutostartAdvice({
+      host,
+      platform: env.platform,
+      hasSystemd: init.systemdUser,
+      container: detectContainer({ env: process.env }).container,
+      user: typeof process.env.USER === 'string' ? process.env.USER : '',
+      distro: host.distro,
+    })
+    return cachedAutostart
+  }
+
+  /**
+   * WHAT IS ON DISK RIGHT NOW: the backups of this host.
+   *
+   * The settings page shows it ("what is backed up right now"), so the facts
+   * have to come from the disk and not from the browser: the browser may not
+   * even see the disk. Only the DIRECTORY is read — the manifest of every
+   * copy — because one copy can be 150 MB and its contents are never walked.
+   *
+   * @returns {{ dir: string, max: number, count: number, items: Array<object> }}
+   */
+  const backupsInfo = () => {
+    const dir = backupsDirFor(stateDirOf())
+    const items = listBackups(dir).map((item) => ({
+      name: item.name,
+      dir: item.dir,
+      at: item.at,
+      atLocal: item.atLocal,
+      bytes: item.bytes,
+      files: item.files,
+      includePlugins: item.includePlugins,
+    }))
+    return {
+      dir,
+      max: config.maxBackups,
+      count: items.length,
+      items,
+    }
+  }
+
+  /**
+   * THE DIAGNOSTICS of "report a problem".
+   *
+   * One generator, on the host: the browser copies the text it gets, so the
+   * two can never drift. It carries the facts a bug report needs — and NOT
+   * the access token of this instance (the generator only copies the fields
+   * it knows, and everything it copies is redacted again).
+   *
+   * @returns {string}
+   */
+  const diagnosticsText = () => buildDiagnostics({
+    version: pluginVersion(),
+    platform: env.platform,
+    hostKind: hostKindOf().kind,
+    isDesktopApp: env.isDesktopApp === true,
+    startup: startupModeOf(),
+    supervisor: supervisorStatusOf(),
+    restartMode: config.restartMode,
+    lastRestart: lastRestartVerdict(),
+    stateDir: stateDirOf(),
+  })
+
+  /**
+   * HOW THIS HOST WAS STARTED (the startup matrix).
+   *
+   * The answer decides what the plugin may do: only a `bare` host (nobody
+   * manages it) may get the supervisor of this plugin or a self-replay
+   * command. Everything else — an external supervisor, a container, the
+   * desktop app, or a host whose starter cannot be established — must not
+   * lead to a second host.
+   *
+   * @returns {object} the classification (mode, kind, evidence, …)
+   */
+  const startupModeOf = () => classifyStartup({
+    platform: env.platform,
+    env: process.env,
+    ppid: process.ppid,
+    isDesktopApp: env.isDesktopApp === true,
+    supervised: detectSupervisor({ env: process.env, stateDir: stateDirOf() }).supervised,
+    container: detectContainer({ env: process.env }).container,
+    argv: process.argv,
+    execPath: process.execPath,
+    readChain: readProcessChain,
+  })
+
+  /**
+   * What the plugin knows about the supervisor.
+   *
+   * The parent chain of this very process is part of the answer: a host that
+   * somebody ELSE supervises (systemd, pm2, a `supervise-*.sh` script) must
+   * not be restarted by a self-replay — the supervisor starts it again, and a
+   * second host on the same port is a double start.
+   *
+   * @returns {object} the status (mode, kind, installed, running, restartCapable)
+   */
+  const supervisorStatusOf = () => supervisorStatus({
+    stateDir: stateDirOf(),
+    env: process.env,
+    platform: env.platform,
+    mode: config.supervisorMode,
+    ppid: process.ppid,
+    // The desktop app brings ITSELF back up (`restartMode: app`): it is not
+    // "nobody knows", and the restart is available.
+    isDesktopApp: env.isDesktopApp === true,
+    // HOW this host was started (the startup matrix), with its evidence.
+    startup: startupModeOf(),
+    // THE PLATFORM GUIDE: how "start at login" works here (Windows / Linux /
+    // WSL / container), with the commands the user can copy.
+    autostart: autostartAdviceOf(),
+  })
+
+  /**
+   * The start command the supervisor would use.
+   *
+   * This is the PLAIN command line of this very process: the interpreter, its
+   * own arguments and the script it runs. The full derivation (with the
+   * refusal rules) belongs to the "E" step; this is the honest minimum the
+   * supervisor needs to be able to start the host again.
+   *
+   * @returns {{ execPath: string, execArgv: string[], argv: string[], cwd: string }}
+   */
+  const supervisorStartCommand = () => ({
+    execPath: process.execPath,
+    execArgv: Array.isArray(process.execArgv) ? process.execArgv.map(String) : [],
+    argv: Array.isArray(process.argv) ? process.argv.slice(1).map(String) : [],
+    cwd: process.cwd(),
+  })
+
+  /**
+   * The environment the supervisor hands to the host it starts.
+   *
+   * Only a WHITELIST is inherited (the daemon does that too): the host's own
+   * internal variables must not leak into the next start, or the profile would
+   * drift.
+   *
+   * @returns {Record<string, string>}
+   */
+  const supervisorEnv = () => {
+    const env = {}
+    const source = process.env || {}
+    for (const key of [
+      'PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'LANG', 'LC_ALL', 'SystemRoot',
+      'TEMP', 'TMP', 'APPDATA', 'LOCALAPPDATA', 'ProgramData',
+      'NUMBER_OF_PROCESSORS', 'WSLENV', 'WSL_DISTRO_NAME', 'WSL_INTEROP',
+    ]) {
+      const value = source[key]
+      if (typeof value === 'string' && value !== '') env[key] = value
+    }
+    // The two variables that say WHICH profile this host belongs to.
+    if (typeof source.DSH_HOME === 'string' && source.DSH_HOME !== '') env.DSH_HOME = source.DSH_HOME
+    if (typeof source.DSH_PROFILE === 'string' && source.DSH_PROFILE !== '') env.DSH_PROFILE = source.DSH_PROFILE
+    return env
+  }
+
+  /**
+   * Install the supervisor.
+   *
+   * @param {{ confirmed?: boolean, dryRun?: boolean }} [options]
+   * @returns {object} the outcome (ok, kind, steps, error, plan)
+   */
+  const installSupervisorNow = (options = {}) => {
+    const stateDir = stateDirOf()
+    const profile = resolveProfileDirDetailed()
+    const start = supervisorStartCommand()
+    const result = installSupervisor({
+      stateDir,
+      profileDir: profile.dir,
+      platform: env.platform,
+      confirmed: options.confirmed === true,
+      dryRun: options.dryRun === true,
+      // The desktop app manages itself: a login record would start a SECOND
+      // client at every login, so the installation is refused there.
+      isDesktopApp: env.isDesktopApp === true,
+      // The startup matrix: only a `bare` host (nobody manages it) may get
+      // the supervisor of this plugin.
+      startup: startupModeOf(),
+      // WHICH MACHINE IS THIS? (WSL is not a Linux: the autostart there is a
+      // different thing, and the Docker/Compose answer is a wrong one.)
+      host: hostKindOf(),
+      nodePath: process.execPath,
+      execPath: start.execPath,
+      execArgv: start.execArgv,
+      argv: start.argv,
+      cwd: start.cwd,
+      env: supervisorEnv(),
+      profileEnv: {
+        ...(process.env.DSH_HOME ? { DSH_HOME: process.env.DSH_HOME } : {}),
+        ...(process.env.DSH_PROFILE ? { DSH_PROFILE: process.env.DSH_PROFILE } : {}),
+      },
+      port: config.supervisorPort > 0 ? config.supervisorPort : (runtime.webPort || 0),
+      healthUrl: restartHealthUrl() ?? '',
+      ownerUser: typeof process.env.USER === 'string' ? process.env.USER : (typeof process.env.LOGNAME === 'string' ? process.env.LOGNAME : ''),
+      timings: {
+        restartDelayMs: config.supervisorRestartDelayMs,
+        restartDelayMaxMs: config.supervisorRestartDelayMaxMs,
+        startTimeoutMs: config.supervisorStartTimeoutMs,
+        killGraceMs: config.supervisorKillGraceMs,
+      },
+      kind: config.supervisorKind,
+      // The previous way of starting the host: the uninstall puts it back.
+      previous: { restartMode: config.restartMode, restartCommand: config.restartCommand },
+      log: (message) => log.warn(message),
+    })
+    if (result.ok) {
+      log.warn('the supervisor was installed', { kind: result.kind, degraded: result.degraded })
+    } else {
+      log.error('the supervisor was not installed:', result.error)
+    }
+    return result
+  }
+
+  /**
+   * Uninstall the supervisor and give the machine back to the user.
+   *
+   * @returns {Promise<object>} the outcome (ok, steps, error, pending, previous)
+   */
+  const uninstallSupervisorNow = async () => {
+    const result = await uninstallSupervisor({
+      stateDir: stateDirOf(),
+      platform: env.platform,
+      log: (message) => log.warn(message),
+    })
+    if (result.ok) {
+      log.warn('the supervisor was uninstalled', { previous: result.previous })
+    } else {
+      log.error('the supervisor could not be removed completely:', result.error)
+    }
+    return result
+  }
+
+  /**
+   * Record the answer of the one-time question about the supervisor.
+   *
+   * @param {string} choice 'install' | 'external' | 'dismissed'
+   * @param {object} [previous] the values that were in effect before
+   * @returns {object} the recorded answer
+   */
+  const recordSupervisorChoice = (choice, previous = null) => {
+    const record = recordOnboarding(state, {
+      feature: 'supervisor',
+      version: SUPERVISOR_FEATURE_VERSION,
+      choice,
+      previous,
+      now: Date.now(),
+    })
+    persist()
+    return record
+  }
+
+  /**
+   * Derive the command that starts this host again — or say why there is
+   * none. Nothing is written: this is the dry run (B).
+   *
+   * @param {{ fixedPort?: number }} [options]
+   * @returns {Promise<object>} the derivation (the plan of what WOULD be written)
+   */
+  const deriveStartCommandNow = async (options = {}) => {
+    const detected = detectSupervisor({ env: process.env, stateDir: stateDirOf() })
+    const external = detectExternalSupervisor({
+      ppid: process.ppid,
+      env: process.env,
+      platform: env.platform,
+    })
+    const container = detectContainer({ env: process.env })
+    const init = detectInitSystems({ platform: env.platform, homeDir: os.homedir() })
+    // A random port has to be FIXED, or the cookie of the browser dies with
+    // every restart. The port is picked once and then written down.
+    let fixedPort = Number(options.fixedPort) > 0 ? Number(options.fixedPort) : 0
+    if (fixedPort === 0 && config.supervisorPort > 0) fixedPort = config.supervisorPort
+    if (fixedPort === 0 && Number(runtime.webPort) > 0 && config.supervisorPort === 0) {
+      // The port of the running instance is the best candidate: it is the one
+      // the browser knows.
+      fixedPort = Number(runtime.webPort)
+    }
+    const derivation = deriveStartCommand({
+      execPath: process.execPath,
+      execArgv: process.execArgv,
+      argv: process.argv,
+      cwd: process.cwd(),
+      platform: env.platform,
+      env: process.env,
+      pid: process.pid,
+      isDesktopApp: env.isDesktopApp === true,
+      webPort: runtime.webPort || 0,
+      supervised: detected.supervised === true,
+      externalSupervisor: external,
+      container: container.container,
+      // THE STARTUP MATRIX: it decides whether a self-replay is possible at
+      // all (and whether the command must be detached from its session).
+      startup: startupModeOf(),
+      hasInit: env.platform === 'win32' ? true : init.systemdUser,
+      fixedPort,
+      currentRestartMode: config.restartMode,
+      currentRestartCommand: config.restartCommand,
+      healthPath: resolveHealthPath(config),
+    })
+    const plan = buildDryRunPlan(derivation)
+    return {
+      ...plan,
+      derivation,
+      externalSupervisor: external,
+      container: container.container,
+      initReason: init.reason,
+      // The fragment a container needs (there is no "at login" there).
+      compose: derivation.reason === 'container-no-init' && derivation.argv
+        ? composeRestartFragment(derivation.argv)
+        : null,
+    }
+  }
+
+  /**
+   * Write the derived command into the profile configuration — only after the
+   * user confirmed the dry run.
+   *
+   * @param {{ derivation?: object }} [options]
+   * @returns {Promise<object>} the outcome
+   */
+  const applyDerivedCommand = async (options = {}) => {
+    const derivation = options.derivation && typeof options.derivation === 'object'
+      ? options.derivation
+      : await deriveStartCommandNow()
+    if (!derivation || derivation.ok !== true || !derivation.writes) {
+      return {
+        ok: false,
+        error: 'nothing-to-write',
+        reason: derivation ? derivation.reason : 'unknown',
+      }
+    }
+    const previous = {
+      restartMode: config.restartMode,
+      restartCommand: config.restartCommand,
+    }
+    try {
+      await runtime.applyConfigChoice({
+        restartMode: derivation.writes.restartMode,
+        restartCommand: derivation.writes.restartCommand,
+      })
+    } catch (error) {
+      return { ok: false, error: describeError(error), reason: derivation.reason }
+    }
+    // The values that were in effect are kept, so the undo can put them back.
+    recordSupervisorChoice('external', previous)
+    log.warn('the derived restart command was written', {
+      mode: derivation.writes.restartMode,
+      reason: derivation.reason,
+    })
+    return { ok: true, writes: derivation.writes, previous, reason: derivation.reason }
+  }
+
+  /**
+   * Put the previous start command back (the undo).
+   *
+   * @returns {Promise<object>} the outcome
+   */
+  const revertDerivedCommand = async () => {
+    const record = state.onboarding
+    const previous = record && typeof record === 'object' ? record.previous : null
+    if (!previous || typeof previous.restartMode !== 'string') {
+      return { ok: false, error: 'nothing-to-revert' }
+    }
+    try {
+      await runtime.applyConfigChoice({
+        restartMode: previous.restartMode,
+        restartCommand: previous.restartCommand === null ? '' : previous.restartCommand,
+      })
+    } catch (error) {
+      return { ok: false, error: describeError(error) }
+    }
+    log.warn('the previous restart command was put back', previous)
+    return { ok: true, previous }
+  }
+
+  /**
+   * Write the marker that tells the rollback watcher "the plugin has decided
+   * on its own — stand down".
+   *
+   * The watcher is the fallback for the case that the plugin dies with the
+   * host. When the plugin SURVIVES the restart command it decides alone, and
+   * this marker keeps the watcher from rolling back a restart that was fine.
+   *
+   * @param {{ decided: boolean, ok?: boolean, reason?: string }} outcome
+   * @returns {boolean} whether the marker was written
+   */
+  const writeRestartOutcome = (outcome) => {
+    const file = path.join(stateDirOf(), RESTART_OUTCOME_FILE)
+    try {
+      fs.writeFileSync(file, JSON.stringify({
+        decided: true,
+        ok: outcome && outcome.ok === true,
+        reason: outcome && typeof outcome.reason === 'string' ? outcome.reason : '',
+        at: new Date().toISOString(),
+        bootId,
+      }, null, 2), 'utf8')
+      return true
+    } catch (error) {
+      log.warn('could not write the restart outcome marker:', String(error))
+      return false
+    }
+  }
+
+  /**
+   * Write the rollback report of a restart that FAILED, so the interface can
+   * say what happened.
+   *
+   * The report has the same shape as the one the detached watcher writes, so
+   * there is exactly ONE place that reads it.
+   *
+   * @param {{ rolledBack: boolean, reason: string, backupDir?: string|null, restored?: string[] }} details
+   * @returns {boolean} whether the report was written
+   */
+  const writeRestartReport = (details) => {
+    const file = path.join(stateDirOf(), RESTART_REPORT_NAME)
+    try {
+      fs.writeFileSync(file, JSON.stringify({
+        ok: false,
+        at: new Date().toISOString(),
+        waitedMs: 0,
+        rolledBack: details.rolledBack === true,
+        rollbackError: details.rolledBack === true ? null : details.reason,
+        reason: details.reason,
+        backupDir: details.backupDir ?? null,
+        restored: Array.isArray(details.restored) ? details.restored : [],
+        // The plugin restores the files; it never starts a second host.
+        appStarted: false,
+      }, null, 2), 'utf8')
+      return true
+    } catch (error) {
+      log.warn('could not write the rollback report:', String(error))
+      return false
+    }
+  }
+
+  /**
+   * Put the pre-restart snapshot back over the live profile.
+   *
+   * This is the in-process half of the rollback: it runs when the plugin
+   * itself can see that the restart failed (the restart command did not
+   * start, or the new instance never answered). The detached watcher does
+   * the same thing when the plugin died with the host.
+   *
+   * @param {{ backup: any, profileDir: string|null, reason: string }} details
+   * @returns {{ rolledBack: boolean, restored: string[], error: string|null }}
+   */
+  const rollbackInProcess = ({ backup, profileDir, reason }) => {
+    const restored = []
+    if (!backup || backup.ok !== true || typeof backup.dir !== 'string' || backup.dir === '') {
+      log.error('the restart failed and there is no snapshot to roll back to:', reason)
+      writeRestartReport({ rolledBack: false, reason, backupDir: null, restored })
+      return { rolledBack: false, restored, error: 'no snapshot to roll back to' }
+    }
+    if (typeof profileDir !== 'string' || profileDir === '') {
+      log.error('the restart failed and the profile directory is unknown:', reason)
+      writeRestartReport({ rolledBack: false, reason, backupDir: backup.dir, restored })
+      return { rolledBack: false, restored, error: 'the profile directory is unknown' }
+    }
+    // THE LOCK: the detached watcher may be restoring the snapshot at the same
+    // time. Exactly ONE of them copies the files — two copies at once would
+    // write the same files (117 MB of plugin tree) at the same time.
+    const lock = claimRollbackLock(stateDirOf())
+    if (!lock.ok) {
+      log.warn('another rollback is already running; this one stands down:', lock.error)
+      return { rolledBack: false, restored, error: lock.error }
+    }
+    let result = null
+    try {
+      result = restoreBackup({ backupDir: backup.dir, profileDir })
+    } catch (error) {
+      result = { ok: false, restored: [], error: String(error) }
+    } finally {
+      releaseRollbackLock(stateDirOf())
+    }
+    if (result && result.ok === true) {
+      log.warn('the pre-restart snapshot was restored:', {
+        reason,
+        restored: result.restored,
+        backupDir: backup.dir,
+      })
+      writeRestartReport({ rolledBack: true, reason, backupDir: backup.dir, restored: result.restored })
+      return { rolledBack: true, restored: result.restored, error: null }
+    }
+    const error = (result && result.error) || 'the restore failed'
+    log.error('the pre-restart snapshot could not be restored:', reason, error)
+    writeRestartReport({ rolledBack: false, reason, backupDir: backup.dir, restored })
+    return { rolledBack: false, restored, error }
+  }
+
+  /**
+   * Arm the rollback watcher: the process that confirms the new instance and
+   * puts the snapshot back when it never comes.
+   *
+   * The watcher is started OUTSIDE the host process, because the restart
+   * command usually kills the host itself — in that case the plugin cannot
+   * confirm anything any more, and the watcher is the only safety net left.
+   *
+   * @param {{ backup: any, profileDir: string|null, gateScriptPath?: string|null }} details
+   * @returns {{ ok: boolean, method: string, error: string|null, scriptPath: string|null }}
+   */
+  const armRollbackWatcher = ({ backup, profileDir, gateScriptPath = null }) => {
+    if (!backup || backup.ok !== true || typeof backup.dir !== 'string' || backup.dir === '') {
+      log.warn('no pre-restart snapshot: the automatic rollback is not armed')
+      return { ok: false, method: 'none', error: 'no snapshot', scriptPath: null }
+    }
+    if (typeof profileDir !== 'string' || profileDir === '') {
+      log.warn('the profile directory is unknown: the automatic rollback is not armed')
+      return { ok: false, method: 'none', error: 'the profile directory is unknown', scriptPath: null }
+    }
+    const stateDir = stateDirOf()
+    const scriptPath = path.join(stateDir, 'restart-' + state.generation + '-watch.ps1')
+    const script = buildWatchScript({
+      // The fallback health URL (the port of the OLD instance). It is only
+      // used when the host publishes no instance record at all.
+      healthUrl: restartHealthUrl() ?? '',
+      healthPath: resolveHealthPath(config),
+      // The instance record: the port of the NEW instance and its boot id.
+      portFile: accessFilePath(stateDir),
+      expectedBootId: bootId,
+      outcomeFile: path.join(stateDir, RESTART_OUTCOME_FILE),
+      backupDir: backup.dir,
+      profileDir,
+      reportPath: path.join(stateDir, ROLLBACK_REPORT_NAME),
+      lockFile: path.join(stateDir, ROLLBACK_LOCK_NAME),
+      timeoutMs: config.rollbackTimeoutMs,
+      rollbackTimeoutMs: config.rollbackCopyTimeoutMs,
+      since: new Date().toISOString(),
+      selfCleanPaths: [scriptPath, gateScriptPath].filter(Boolean),
+    })
+    const written = writeTextFileAtomic(scriptPath, script)
+    if (!written.ok) {
+      log.error('could not write the rollback watcher:', written.error)
+      return { ok: false, method: 'none', error: written.error, scriptPath }
+    }
+    const result = launchWatcherFn({
+      watchScriptPath: scriptPath,
+      platform: env.platform,
+    })
+    if (!result || result.ok !== true) {
+      log.error('could not start the rollback watcher:', (result && result.error) || 'unknown error')
+      return { ok: false, method: (result && result.method) || 'none', error: (result && result.error) || null, scriptPath }
+    }
+    log.warn('the rollback watcher is armed', {
+      scriptPath,
+      method: result.method,
+      timeoutMs: config.rollbackTimeoutMs,
+    })
+    return { ok: true, method: result.method, error: null, scriptPath }
+  }
+
   /** Execute the restart now; the detached helper survives our own death. */
   const executeRestart = async () => {
     stopPolling()
@@ -1996,8 +3224,70 @@ const titleOfSummary = (item) => {
         log,
         profile: resolveProfileDirDetailed(),
       })
+      // The snapshot is the rollback point of BOTH branches.
+      const backup = snapshot && snapshot.backup ? snapshot.backup : null
+      const profileDir = snapshot && snapshot.profileDir ? snapshot.profileDir : 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
+      // snapshots were pruned) and the generation. The instance that replaces
+      // it rewrites the record as `ok` / `failed` after it has checked itself
+      // (see `verifyRestartBoot`). If the new instance never comes up, the
+      // record stays `pending` — which is exactly what has to be visible.
+      recordRestartVerdict({
+        result: RESTART_RESULTS.PENDING,
+        mode: useCustomCommand ? 'command' : 'app',
+        generation: state.generation,
+        requestedAt: state.restart && Number.isFinite(state.restart.requestedAt)
+          ? state.restart.requestedAt
+          : null,
+        startedAt: Date.now(),
+        previousBootId: bootId,
+        bootId: null,
+        reason: state.restart && typeof state.restart.reason === 'string' ? state.restart.reason : null,
+        snapshot: buildSnapshotRecord({
+          requested: snapshot && snapshot.requested === true,
+          backup,
+          profileDir,
+          durationMs: snapshot && Number.isFinite(snapshot.durationMs) ? snapshot.durationMs : null,
+          error: snapshot && snapshot.error ? snapshot.error : null,
+        }),
+        checks: [],
+      })
+      // The marker of an EARLIER decision must not confuse this restart's
+      // watcher: it would stand down before it even looked at the new
+      // instance. It is removed BEFORE the watcher is armed.
+      try {
+        fs.rmSync(path.join(stateDir, RESTART_OUTCOME_FILE), { force: true })
+      } catch {}
 
       if (useCustomCommand) {
+        // (0) THE C ROUTE. When the supervisor of this plugin started this
+        // instance, the restart is asked of the SUPERVISOR (over its control
+        // channel) — not of a command. The supervisor kills the host, starts
+        // it again and puts the snapshot back if it does not come.
+        const detected = detectSupervisor({ env: process.env, stateDir })
+        if (detected.supervised) {
+          if (backup && backup.ok === true) {
+            writeRollbackRequest(stateDir, {
+              backupDir: backup.dir,
+              profileDir: profileDir ?? '',
+              generation: state.generation,
+              reason: 'plugin-restart',
+            })
+          }
+          const asked = await requestSupervisorAction({ stateDir, action: 'restart' })
+          if (asked && asked.ok === true) {
+            log.warn('the restart was handed to the supervisor of this plugin')
+            return
+          }
+          log.error(
+            'the supervisor did not accept the restart request; falling back to the restart command:',
+            asked ? asked.error : 'unknown error',
+          )
+        }
+
         const command = buildCustomCommand({
           template: config.restartCommand,
           pid: process.pid,
@@ -2005,9 +3295,95 @@ const titleOfSummary = (item) => {
           appExePath: env.appExePath || '',
         })
         log.warn('running custom restart command:', 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')
+
+        // (1) THE SAFETY NET. The restart command usually kills THIS process
+        // (that is what restarting the host means), so the plugin cannot
+        // confirm anything once the command runs. The watcher is started
+        // BEFORE the command: it waits for the new instance outside the host
+        // and puts the snapshot back when the new instance never comes.
+        //
+        // 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 })
+
+        try {
+          // (2) THE COMMAND, with a real success judgement. The old code only
+          // looked at "the spawn did not throw", so a command that does not
+          // exist or that exits with an error was reported as a successful
+          // restart.
+          const outcome = await runCommandFn({
+            command,
+            timeoutMs: config.restartCommandTimeoutMs,
+          })
+          if (!outcome || outcome.ok !== true) {
+            const reason = (outcome && outcome.error) || 'the restart command failed'
+            log.error('the restart command failed; the pre-restart snapshot is restored:', reason)
+            rollbackInProcess({ backup, profileDir, reason })
+            writeRestartOutcome({ decided: true, ok: false, reason })
+            recordRestartVerdict({
+              result: RESTART_RESULTS.FAILED,
+              verifiedAt: Date.now(),
+              reason,
+              checks: [{ name: 'command', ok: false, detail: reason }],
+            })
+            return
+          }
+          if (outcome.timedOut === true) {
+            log.warn(
+              `the restart command is still running after ${config.restartCommandTimeoutMs}ms; `
+              + 'the new instance is confirmed by the rollback watcher',
+              { command, timeoutMs: config.restartCommandTimeoutMs },
+            )
+          } else {
+            log.warn('the restart command finished', { command, exitCode: outcome.exitCode ?? null })
+          }
+
+          // (3) THE HEALTH CONFIRMATION — only possible when this process
+          // survived the command. The new instance publishes its own port and
+          // its own boot id; the confirmation waits for THAT instance and not
+          // for the one that is being replaced.
+          const confirmed = await probeInstanceFn({
+            accessFile: accessFilePath(stateDir),
+            expectedBootId: bootId,
+            healthPath: resolveHealthPath(config),
+            timeoutMs: config.rollbackTimeoutMs,
+          })
+          if (confirmed && confirmed.ok === true) {
+            log.warn('the new instance answered its health route:', confirmed)
+            writeRestartOutcome({ decided: true, ok: true, reason: 'the new instance answered' })
+            recordRestartVerdict({
+              result: RESTART_RESULTS.OK,
+              verifiedAt: Date.now(),
+              reason: 'the new instance answered',
+              checks: [{ name: 'command', ok: true, detail: 'the new instance answered its health route' }],
+            }, { skipIfFinalized: true })
+            return
+          }
+          const reason = (confirmed && confirmed.reason) || 'the new instance never answered'
+          log.error('the new instance did not come up; the pre-restart snapshot is restored:', reason)
+          rollbackInProcess({ backup, profileDir, reason })
+          writeRestartOutcome({ decided: true, ok: false, reason })
+          recordRestartVerdict({
+            result: RESTART_RESULTS.FAILED,
+            verifiedAt: Date.now(),
+            reason,
+            checks: [{ name: 'command', ok: false, detail: reason }],
+          })
+        } catch (error) {
+          // The command has already run: a retry would restart the host a
+          // SECOND time. The snapshot is restored and the reason is reported.
+          const reason = 'the hosted restart failed: ' + String(error)
+          log.error(reason)
+          rollbackInProcess({ backup, profileDir, reason })
+          writeRestartOutcome({ decided: true, ok: false, reason })
+          recordRestartVerdict({
+            result: RESTART_RESULTS.FAILED,
+            verifiedAt: Date.now(),
+            reason,
+            checks: [{ name: 'command', ok: false, detail: reason }],
+          })
+        }
       } else {
         const aborts = Number(state.restart.gateAborts) || 0
         const url = aborts > 20 ? null : restartGateUrl()
@@ -2017,29 +3393,41 @@ const titleOfSummary = (item) => {
           log.warn('the web server port is unknown; scheduling an UNGATED restart (the helper cannot re-check the idle gate)')
         }
         // 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
+        const gateScriptPath = url === null ? null : path.join(stateDir, 'restart-' + state.generation + '.cmd')
+        // 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
           ? path.join(stateDir, 'restart-' + state.generation + '-watch.ps1')
           : null
         const watchScript = watchScriptPath === null
           ? null
           : buildWatchScript({
+            // The fallback URL of the OLD instance. The watcher uses the port
+            // of the NEW instance (from the instance record) — the desktop
+            // app listens on a random port, so the old one is worthless.
             healthUrl,
+            healthPath: resolveHealthPath(config),
+            portFile: accessFilePath(stateDir),
+            expectedBootId: bootId,
+            outcomeFile: path.join(stateDir, RESTART_OUTCOME_FILE),
             backupDir: backup.dir,
             profileDir,
             reportPath: path.join(stateDir, ROLLBACK_REPORT_NAME),
-            appExePath: env.appExePath,
+            lockFile: path.join(stateDir, ROLLBACK_LOCK_NAME),
             timeoutMs: config.rollbackTimeoutMs,
+            rollbackTimeoutMs: config.rollbackCopyTimeoutMs,
             // Only a crash log written after this point belongs to this restart.
             since: new Date().toISOString(),
+            // The watcher removes the helper scripts when it ends.
+            selfCleanPaths: [watchScriptPath, gateScriptPath].filter(Boolean),
           })
         const result = scheduleDetachedFn({
           appExePath: env.appExePath,
           relaunchDelaySeconds: config.relaunchDelaySeconds,
           gateUrl: url,
-          scriptPath: url === null ? null : path.join(stateDir, 'restart-' + state.generation + '.cmd'),
+          scriptPath: gateScriptPath,
           watchScriptPath,
           watchScript,
         })
@@ -2073,7 +3461,7 @@ const titleOfSummary = (item) => {
     const decision = restartDecision(state, {
       anyAgentRunning: busy.length > 0,
       busyAgents: busy,
-      lastActivityAt,
+      lastActivityAt: quietSince(),
       settleMs: effectiveSettleMs(),
       now,
       softMs: config.deferSoftMs,
@@ -2082,6 +3470,23 @@ const titleOfSummary = (item) => {
       forceRestartWhenBusy: config.forceRestartWhenBusy,
     })
     if (decision.log) log.info(decision.log)
+    // The diagnostic line of the pending restart: what the gate decided and
+    // why. It is rate limited (once a minute) so the 3s poll does not flood
+    // the log, and it is the first thing to look at when "the restart never
+    // happens" is reported.
+    if (now - lastDecisionLogAt >= LONG_WAIT_LOG_INTERVAL_MS) {
+      lastDecisionLogAt = now
+      log.info(
+        `restart gate: action=${decision.action} reason=${decision.reason} busyCount=${busy.length} quietForMs=${Math.max(0, now - quietSince())} effectiveSettleMs=${effectiveSettleMs()}`,
+        {
+          action: decision.action,
+          reason: decision.reason,
+          busyCount: busy.length,
+          quietForMs: Math.max(0, now - quietSince()),
+          effectiveSettleMs: effectiveSettleMs(),
+        },
+      )
+    }
     switch (decision.action) {
       case 'wait':
         return
@@ -2092,6 +3497,28 @@ const titleOfSummary = (item) => {
         }
         return
       }
+      case 'long-wait': {
+        // The hard deadline is over and a conversation still holds the
+        // restart. The request is KEPT — the user asked for a restart, it must
+        // never be dropped silently — and the wait becomes VISIBLE: a clear
+        // log line (rate limited, so the 3s poll does not flood the log) and
+        // the `longWait` block of the state payload.
+        const requestedAt = Number.isFinite(state.restart.requestedAt) ? state.restart.requestedAt : now
+        const waitedMs = Math.max(0, now - requestedAt)
+        const lastAt = longWaitLog.requestedAt === requestedAt ? longWaitLog.at : 0
+        if (now - lastAt >= LONG_WAIT_LOG_INTERVAL_MS) {
+          longWaitLog = { at: now, requestedAt }
+          log.warn(
+            `the restart has been waiting for ${describeWait(waitedMs)}; ${describeBlockers(decision.blockedBy)} still holds it — cancel the restart or wait for that work to finish`,
+            {
+              waitedMs,
+              blockedBy: decision.blockedBy,
+              reason: decision.reason,
+            },
+          )
+        }
+        return
+      }
       case 'restart':
       case 'force-restart': {
         void executeRestart()
@@ -2284,10 +3711,114 @@ const titleOfSummary = (item) => {
         waitedMs: Number.isFinite(report.waitedMs) ? report.waitedMs : null,
         rolledBack: report.rolledBack === true,
         backupDir: typeof report.backupDir === 'string' ? report.backupDir : null,
+        // WHY the restart failed. Without it the interface can only say "it was
+        // rolled back", which is the half of the story the user needs most.
+        reason: typeof report.reason === 'string'
+          ? report.reason
+          : (typeof report.rollbackError === 'string' ? report.rollbackError : ''),
         crashLog: typeof report.crashLog === 'string' ? report.crashLog : null,
         crashTail: tail.length > 4000 ? tail.slice(-4000) : tail,
       }
     },
+    /**
+     * The instance record of the running host: the port it listens on and the
+     * access link (with the boot token) that still works.
+     *
+     * After a restart the OLD link answers 401 — the boot token is created per
+     * process — so this is the link the user needs to get back into the
+     * interface.
+     */
+    get accessRecord() {
+      const read = readAccessRecord(path.dirname(stateFile))
+      return read && read.ok === true ? read.record : null
+    },
+    /**
+     * What the plugin knows about the self-starting supervisor: who starts
+     * this host (the supervisor of this plugin / the user's own way / nobody)
+     * and whether the restart can actually work.
+     */
+    supervisorStatus: supervisorStatusOf,
+    /**
+     * HOW this host was started (the startup matrix): the mode, the evidence
+     * and what the plugin may do about it.
+     */
+    startupMode: startupModeOf,
+    /**
+     * WHAT IS ON DISK RIGHT NOW: the backups of this host.
+     */
+    backupsInfo,
+    /**
+     * THE DIAGNOSTICS of "report a problem" (the text the user copies).
+     */
+    diagnostics: diagnosticsText,
+    /**
+     * WHICH MACHINE IS THIS? (Windows / WSL / Linux / macOS) — the same
+     * answer the graceful shutdown uses.
+     */
+    hostKind: hostKindOf,
+    /**
+     * Install the supervisor. `confirmed` must be true: the confirmation card
+     * is what says "yes".
+     */
+    installSupervisor: installSupervisorNow,
+    /**
+     * Remove the supervisor and give the machine back to the user.
+     */
+    uninstallSupervisor: uninstallSupervisorNow,
+    /**
+     * Record the answer of the one-time question about the supervisor.
+     */
+    recordSupervisorChoice: recordSupervisorChoice,
+    /**
+     * Derive the command that starts this host again (the dry run: nothing is
+     * written).
+     */
+    deriveStartCommand: deriveStartCommandNow,
+    /**
+     * Write the derived command into the profile configuration (only after
+     * the user confirmed it).
+     */
+    applyDerivedCommand: applyDerivedCommand,
+    /**
+     * Put the previous start command back (the undo).
+     */
+    revertDerivedCommand: revertDerivedCommand,
+    /**
+     * The answer of the one-time question about the supervisor (null when it
+     * was never answered).
+     */
+    get onboardingChoice() {
+      const record = state.onboarding
+      if (!record || typeof record !== 'object') return null
+      if (record.feature !== 'supervisor') return null
+      return {
+        feature: record.feature,
+        version: record.version,
+        choice: record.choice,
+        answeredAt: record.answeredAt,
+      }
+    },
+    /**
+     * Whether the one-time question about the supervisor may be asked.
+     *
+     * ONLY for the HOSTED hosts: the desktop app brings itself back up
+     * (`restartMode: app`), so asking a hosted user "shall I install a
+     * supervisor?" would be noise there.
+     *
+     * And NEVER when somebody else is already in charge: a second supervisor
+     * would fight over the port with the first one — that is the double start
+     * the whole external-supervisor detection exists to prevent.
+     */
+    get supervisorOffer() {
+      if (env.isDesktopApp) return false
+      const record = state.onboarding
+      if (record && typeof record === 'object' && record.feature === 'supervisor') return false
+      try {
+        const status = supervisorStatusOf()
+        if (status && status.mode === 'external') return false
+      } catch {}
+      return true
+    },
     env,
     stateFile,
     log,
@@ -2340,6 +3871,24 @@ const titleOfSummary = (item) => {
       return { applied: result.applied, showSleepButton: showSleepButton === true }
     },
     toolErrors,
+    /**
+     * The routes of this plugin that the web server accepted, and the ones it
+     * refused. The boot check reports them: a host that came up without its
+     * routes is NOT a healthy host.
+     */
+    registeredRoutes,
+    routeErrors,
+    /**
+     * The outcome of the boot recovery pass of THIS boot:
+     * `{ ran, ok, detail }`. `ran` is false when the recovery is switched off.
+     */
+    recovery: null,
+    /**
+     * The durable record of the last restart (the snapshot that was taken and
+     * the verdict of the instance that came up).
+     */
+    lastRestartVerdict,
+    recordRestartVerdict,
     startPolling,
     stopPolling,
     tick,
@@ -2351,13 +3900,23 @@ const titleOfSummary = (item) => {
      */
     pendingRestart,
     /**
-     * How long the host has been quiet (no conversation activity at all).
+     * How long the host has been quiet (no REAL conversation activity: a
+     * running turn, a queued message, a turn that started or ended).
+     *
+     * The routine session events of the interface do not count.
      *
      * @returns {number}
      */
     quietForMs,
     /**
-     * The grace window: the extra wait after the last conversation finished.
+     * The moment the quiet window started.
+     *
+     * @returns {number} a timestamp in milliseconds
+     */
+    quietSince,
+    /**
+     * The RESTART reserve: the extra wait after the last conversation
+     * finished, before the host is really restarted.
      *
      * @returns {number} milliseconds
      */
@@ -2378,6 +3937,19 @@ const titleOfSummary = (item) => {
     noteActivity,
     busyAgents,
     gate,
+    /**
+     * The description of a long wait (null when there is none).
+     *
+     * @param {number} [now]
+     * @returns {{ since: number, reason: string, waitedMs: number, blockedBy: any[] }|null}
+     */
+    longWaitInfo,
+    /**
+     * The upper bound of a queued (unclaimed) inbox message.
+     *
+     * @returns {number} milliseconds
+     */
+    queuedGraceMs: () => config.queuedGraceMs,
     sessionTitle,
     disarmGoal,
     disarmBlockingGoals,
@@ -2929,6 +4501,137 @@ async function recoverAfterRestart(ctx, runtime, config) {
   return { recovered: results, phase: 'running' }
 }
 
+/**
+ * How long a pending restart record stays fresh enough to be finished by
+ * THIS boot. A record that is older belongs to a restart of another day — it
+ * stays `pending`, because that restart really was never confirmed.
+ */
+export const RESTART_VERDICT_FRESH_MS = 30 * 60 * 1000
+
+/**
+ * The four checks the instance that replaced the old one runs on itself.
+ *
+ * They answer the question the operator actually has after a restart: "did
+ * the new host really come up?" — and each of them is a fact about THIS boot,
+ * not about the old one:
+ *
+ *   - `listener` — the host listens on a known port;
+ *   - `routes`  — the routes of this plugin were accepted by the web server;
+ *   - `plugin`  — the plugin itself is alive in this boot;
+ *   - `recovery`— the boot recovery pass finished (or was not needed).
+ *
+ * @param {object} runtime
+ * @returns {Array<{ name: string, ok: boolean, detail: string }>}
+ */
+export function collectBootChecks(runtime) {
+  const checks = []
+
+  const port = Number(runtime && runtime.webPort)
+  checks.push({
+    name: 'listener',
+    ok: Number.isFinite(port) && port > 0,
+    detail: Number.isFinite(port) && port > 0
+      ? 'the host listens on port ' + port
+      : 'the host does not listen on a known port',
+  })
+
+  const registered = Array.isArray(runtime && runtime.registeredRoutes) ? runtime.registeredRoutes : []
+  const routeErrors = Array.isArray(runtime && runtime.routeErrors) ? runtime.routeErrors : []
+  checks.push({
+    name: 'routes',
+    ok: registered.length > 0 && routeErrors.length === 0,
+    detail: registered.length === 0
+      ? 'no route of this plugin was registered'
+      : registered.length + ' route(s) registered'
+        + (routeErrors.length > 0 ? ', ' + routeErrors.length + ' refused' : ''),
+  })
+
+  const bootId = runtime && typeof runtime.bootId === 'string' ? runtime.bootId : ''
+  const toolErrors = Array.isArray(runtime && runtime.toolErrors) ? runtime.toolErrors : []
+  checks.push({
+    name: 'plugin',
+    ok: bootId !== '' && toolErrors.length === 0,
+    detail: bootId === ''
+      ? 'the plugin did not register a boot id'
+      : 'the plugin is alive (boot ' + bootId + ')'
+        + (toolErrors.length > 0 ? ', ' + toolErrors.length + ' tool(s) failed' : ''),
+  })
+
+  const recovery = runtime && runtime.recovery && typeof runtime.recovery === 'object'
+    ? runtime.recovery
+    : null
+  checks.push({
+    name: 'recovery',
+    ok: recovery === null ? false : recovery.ok === true,
+    detail: recovery === null
+      ? 'the boot recovery did not report anything'
+      : (typeof recovery.detail === 'string' && recovery.detail !== '' ? recovery.detail : 'the boot recovery finished'),
+  })
+
+  return checks
+}
+
+/**
+ * Finish the durable restart record.
+ *
+ * The instance that replaced the old one reads the `pending` record, runs the
+ * four boot checks and writes the final verdict (`ok` / `failed`) with the
+ * time it verified itself and how long the whole restart took.
+ *
+ * Nothing is written when there is no pending record (this boot was not the
+ * result of a restart) or when the pending record belongs to another day.
+ *
+ * @param {object} runtime
+ * @param {{ timeoutMs?: number, now?: number, sleep?: Function }} [options]
+ * @returns {Promise<object|null>} the record that is on disk now
+ */
+export async function verifyRestartBoot(runtime, options = {}) {
+  const log = runtime.log
+  const stateDir = path.dirname(runtime.stateFile)
+  const pending = readRestartVerdict(stateDir)
+  if (pending === null) return null
+  if (pending.result !== RESTART_RESULTS.PENDING) return pending
+  const now = typeof options.now === 'function' ? options.now : () => Date.now()
+  const timeoutMs = Number.isFinite(Number(options.timeoutMs)) && Number(options.timeoutMs) > 0
+    ? Math.trunc(Number(options.timeoutMs))
+    : 15000
+  const sleep = typeof options.sleep === 'function' ? options.sleep : recoveryDelay
+  const started = now()
+  // The web server may still be coming up: the checks need its port and its
+  // routes, so they wait — but only for a bounded while.
+  while (now() - started < timeoutMs) {
+    const port = Number(runtime.webPort)
+    const registered = Array.isArray(runtime.registeredRoutes) ? runtime.registeredRoutes.length : 0
+    if (Number.isFinite(port) && port > 0 && registered > 0) break
+    await sleep(250)
+  }
+  const checks = collectBootChecks(runtime)
+  const evaluated = evaluateRestartChecks(checks)
+  const verifiedAt = now()
+  const record = runtime.recordRestartVerdict({
+    result: evaluated.ok ? RESTART_RESULTS.OK : RESTART_RESULTS.FAILED,
+    verifiedAt,
+    durationMs: pending.startedAt !== null ? Math.max(0, verifiedAt - pending.startedAt) : null,
+    bootId: runtime.bootId,
+    checks,
+    reason: evaluated.ok
+      ? 'the new instance came up and every check passed'
+      : 'the new instance came up, but ' + evaluated.failed.join(', ') + ' failed',
+  })
+  if (record !== null) {
+    if (evaluated.ok) {
+      log.warn('the new instance verified itself:', { durationMs: record.durationMs, checks })
+    } else {
+      log.error('the new instance did NOT come up cleanly:', {
+        durationMs: record.durationMs,
+        failed: evaluated.failed,
+        checks,
+      })
+    }
+  }
+  return record
+}
+
 /** Promise-based pause used by boot recovery (batching + resolveAgent retries). */
 function recoveryDelay(ms) {
   const wait = Number.isFinite(ms) && ms > 0 ? ms : 0
@@ -3107,6 +4810,7 @@ function registerTools(ctx, runtime, config) {
           quietForMs: { type: 'number' },
           graceMs: { type: 'number' },
           effectiveSettleMs: { type: 'number' },
+          queuedGraceMs: { type: 'number' },
           blockedBy: {
             type: 'array',
             items: {
@@ -3139,6 +4843,11 @@ function registerTools(ctx, runtime, config) {
           profileDirSource: { type: 'string' },
           backupIncludePlugins: { type: 'boolean' },
           lastRollback: { type: 'object' },
+          // The last restart: the snapshot that was taken before it and the
+          // verdict of the instance that came up.
+          lastRestart: { type: 'object' },
+          // The access link of the running instance (with the boot token).
+          accessUrl: { type: 'string' },
           environment: { type: 'object' },
           sessions: { type: 'array', items: { type: 'object' } },
         },
@@ -3158,10 +4867,12 @@ function registerTools(ctx, runtime, config) {
         pendingRestart: state.restart !== null,
         gateAllow: verdict.allow,
         quietForMs: Math.round(verdict.quietForMs),
-        // The grace window (the extra wait after the last conversation
+        // The RESTART reserve (the extra wait after the last conversation
         // finished) and the quiet window the gate really uses.
         graceMs: runtime.graceMs(),
         effectiveSettleMs: runtime.effectiveSettleMs(),
+        // The upper bound of a queued (unclaimed) inbox message.
+        queuedGraceMs: runtime.queuedGraceMs(),
         blockedBy: blockingDetails(verdict.blockedBy),
         parkedGoals: parkedGoalDetails(),
         recovery: recoveryList(state),
@@ -3173,6 +4884,15 @@ function registerTools(ctx, runtime, config) {
         backupIncludePlugins: config.backupIncludePlugins !== false,
         // Present only when the previous restart had to be rolled back.
         ...(runtime.lastRollback ? { lastRollback: runtime.lastRollback } : {}),
+        // THE LAST RESTART: the snapshot that was taken before it (directory,
+        // LOCAL time, duration, pruned) and the verdict of the instance that
+        // came up (the four boot checks). Present only when a restart
+        // happened — otherwise there is nothing to report.
+        ...(runtime.lastRestartVerdict() ? { lastRestart: runtime.lastRestartVerdict() } : {}),
+        // The access link of THIS instance (with the boot token). The boot
+        // token is created per process, so the link the browser holds answers
+        // 401 after a restart — this is the link that still works.
+        ...(accessUrlOf(runtime) ? { accessUrl: accessUrlOf(runtime) } : {}),
         environment: {
           platform: runtime.env.platform,
           isDesktopApp: runtime.env.isDesktopApp,
@@ -3348,11 +5068,19 @@ function registerTools(ctx, runtime, config) {
 
   tool({
     name: 'continuum_cancel_restart',
-    description: 'Cancel a restart previously requested through continuum_restart. Does nothing when no restart is pending.',
+    description:
+      'Cancel a restart requested through continuum_restart. By default ONLY the calling session\'s own request is '
+      + 'withdrawn (scope "mine"): the other sessions that asked for the same restart keep it. Use scope "all" to '
+      + 'cancel the request for EVERYONE ("nobody restarts any more"). Does nothing when no restart is pending.',
     parameters: {
       type: 'object',
       additionalProperties: false,
       properties: {
+        scope: {
+          type: 'string',
+          enum: ['mine', 'all'],
+          description: 'Whose request to cancel: "mine" (the default) withdraws only the calling session\'s own request and leaves the requests of the other sessions alone; "all" cancels the request for every session.',
+        },
         reason: { type: 'string', description: 'Optional note recorded in the log.' },
       },
     },
@@ -3364,20 +5092,248 @@ function registerTools(ctx, runtime, config) {
         properties: {
           ok: { type: 'boolean' },
           cancelled: { type: 'boolean' },
+          scope: { type: 'string' },
+          remainingRequesters: { type: 'integer' },
+          sessionId: { type: 'string' },
           phase: { type: 'string' },
+          error: { type: 'string' },
         },
       },
       (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
     ),
-    execute(args = {}) {
+    execute(args = {}, exec) {
       const state = runtime.state
-      const hadPending = state.restart !== null
-      runtime.releaseRequesters()
-      cancelRestart(state, { now: Date.now() })
-      runtime.stopPolling()
+      const now = Date.now()
+      const scope = args.scope === 'all' ? 'all' : 'mine'
+      const agent = exec && exec.agent
+      const sessionId = agent && agent.id ? String(agent.id) : ''
+      const reason = typeof args.reason === 'string' && args.reason.trim() !== '' ? args.reason.trim() : ''
+
+      // How many sessions are waiting for the pending restart.
+      const requesterCount = () => {
+        const restart = state.restart
+        if (!restart) return 0
+        const ids = new Set()
+        if (Array.isArray(restart.requesters)) {
+          for (const requester of restart.requesters) {
+            if (requester && typeof requester.sessionId === 'string' && requester.sessionId) ids.add(requester.sessionId)
+          }
+        }
+        if (typeof restart.bySessionId === 'string' && restart.bySessionId) ids.add(restart.bySessionId)
+        return ids.size
+      }
+
+      if (scope === 'all') {
+        // The explicit "nobody restarts any more": the whole request goes.
+        const hadPending = state.restart !== null
+        runtime.releaseRequesters()
+        cancelRestart(state, { now })
+        runtime.stopPolling()
+        runtime.persist()
+        if (hadPending) log.info('pending restart cancelled for EVERYONE:', reason || '(no reason)')
+        return { ok: true, cancelled: hadPending, scope: 'all', remainingRequesters: 0, phase: state.phase }
+      }
+
+      // scope "mine": withdraw ONLY the calling session's request.
+      if (state.restart === null) {
+        // Nothing is pending: the tool does nothing, as before.
+        return { ok: true, cancelled: false, scope: 'mine', remainingRequesters: 0, phase: state.phase }
+      }
+      if (sessionId === '') {
+        // The calling session is unknown: refuse instead of guessing. A
+        // silent "cancel everything" is exactly the accident this scope
+        // exists to prevent.
+        log.warn('the restart request of the calling session could not be withdrawn: the calling session is unknown; nothing was cancelled')
+        return {
+          ok: false,
+          cancelled: false,
+          scope: 'mine',
+          remainingRequesters: requesterCount(),
+          phase: state.phase,
+          error: 'The calling session is unknown, so its own request cannot be identified. Nothing was cancelled. Call this tool from the session that requested the restart, or pass scope "all" to cancel the request for everyone.',
+        }
+      }
+      const outcome = cancelOwnRestart(state, { sessionId, now })
+      if (!outcome.removed) {
+        log.warn(`session ${sessionId} did not request the pending restart; nothing was cancelled`)
+        return {
+          ok: false,
+          cancelled: false,
+          scope: 'mine',
+          remainingRequesters: outcome.remaining,
+          sessionId,
+          phase: state.phase,
+          error: 'This session did not request the pending restart, so nothing was cancelled. Pass scope "all" to cancel the request for every session.',
+        }
+      }
+      // Release ONLY this session's continuation request: the other sessions
+      // stay pinned for the restart they asked for.
+      runtime.releaseRequesters([sessionId])
+      if (outcome.cancelled) {
+        // The last requester left: the restart is really over.
+        runtime.stopPolling()
+        log.info(`session ${sessionId} withdrew the last restart request; the pending restart is cancelled`, reason || '')
+      } else {
+        log.info(`session ${sessionId} withdrew its restart request; ${outcome.remaining} requester(s) remain`)
+      }
       runtime.persist()
-      if (hadPending) log.info('pending restart cancelled:', typeof args.reason === 'string' ? args.reason : '(no reason)')
-      return { ok: true, cancelled: hadPending, phase: state.phase }
+      return {
+        ok: true,
+        cancelled: outcome.cancelled,
+        scope: 'mine',
+        remainingRequesters: outcome.remaining,
+        sessionId,
+        phase: state.phase,
+      }
+    },
+  })
+
+  tool({
+    name: 'continuum_supervisor',
+    description:
+      'Inspect and manage the self-starting supervisor of this plugin (the process that brings the host back when it '
+      + 'dies). action "status" reports who starts this host (the supervisor of this plugin / your own way / nobody) '
+      + 'and whether the restart can work at all; action "plan" reports what an installation WOULD change without '
+      + 'touching anything; action "install" and action "uninstall" need confirmed: true, because they really change '
+      + 'the machine (a scheduled task or a systemd user unit that starts the supervisor at login).',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['status', 'plan', 'dry-run', 'install', 'uninstall', 'apply', 'revert'],
+          description: 'What to do: "status" (read-only), "plan" (what the installation would change), "dry-run" (the command this host would be restarted with, and why it may not be derivable), "install"/"uninstall" (the real thing, they need confirmed: true), "apply" (write the derived restart command after the user confirmed the dry run) and "revert" (put the previous command back).',
+        },
+        confirmed: {
+          type: 'boolean',
+          description: 'Required for "install" and "uninstall": the user confirmed the card that says what would change.',
+        },
+        choice: {
+          type: 'string',
+          enum: ['install', 'external', 'dismissed'],
+          description: 'The answer of the one-time question about the supervisor (recorded so the question is never asked twice).',
+        },
+      },
+    },
+    output: textOutput(
+      {
+        type: 'object',
+        additionalProperties: false,
+        required: ['ok', 'action'],
+        properties: {
+          ok: { type: 'boolean' },
+          action: { type: 'string' },
+          kind: { type: 'string' },
+          degraded: { type: 'boolean' },
+          reason: { type: 'string' },
+          error: { type: 'string' },
+          supervisor: { type: 'object' },
+          steps: { type: 'array', items: { type: 'object' } },
+          previous: { type: 'object' },
+          pending: { type: 'object' },
+        },
+      },
+      (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+    ),
+    async execute(args = {}) {
+      const action = typeof args.action === 'string' ? args.action.trim() : 'status'
+      const supervisor = runtime.supervisorStatus()
+      if (action === 'status') {
+        return { ok: true, action, supervisor }
+      }
+      if (action === 'dry-run' || action === 'derive') {
+        // B: the dry run. It reports what WOULD be written; it writes nothing.
+        const plan = await runtime.deriveStartCommand()
+        return {
+          ok: plan.ok === true,
+          action,
+          level: plan.level,
+          mode: plan.mode,
+          reason: plan.reason,
+          command: plan.command,
+          plan: plan.plan,
+          needsConfirmation: plan.needsConfirmation !== false,
+          writes: plan.writes,
+          compose: plan.compose,
+          supervisor,
+        }
+      }
+      if (action === 'plan') {
+        const plan = planSupervisorInstall({
+          platform: runtime.env.platform,
+          // The desktop app manages itself: the plan is refused there, and no
+          // step is generated that could be run by accident.
+          isDesktopApp: runtime.env.isDesktopApp === true,
+          // The startup matrix: only a `bare` host may get a supervisor.
+          startup: runtime.startupMode(),
+          // WHICH MACHINE IS THIS? (WSL is not a Linux.)
+          host: runtime.hostKind(),
+          nodePath: process.execPath,
+          execPath: process.execPath,
+          supervisorPath: supervisorPaths(path.dirname(runtime.stateFile)).script,
+          configPath: supervisorPaths(path.dirname(runtime.stateFile)).config,
+          kind: config.supervisorKind,
+        })
+        return {
+          ok: plan.error ? false : true,
+          action,
+          kind: plan.kind,
+          reason: plan.reason,
+          error: plan.error ?? undefined,
+          steps: plan.steps,
+          supervisor,
+        }
+      }
+      if (action === 'install' && runtime.env.isDesktopApp === true) {
+        // The desktop app manages itself: a login record would open a SECOND
+        // client at every login. The refusal comes BEFORE the confirmation, so
+        // the user is never asked to confirm something that cannot happen.
+        return {
+          ok: false,
+          action,
+          error: 'desktop-manages-itself',
+          reason: 'the desktop app relaunches itself; a supervisor would start a second copy',
+          steps: [],
+          supervisor,
+        }
+      }
+      if (args.confirmed !== true) {
+        // The card is what says "yes": without it the machine is not touched.
+        return {
+          ok: false,
+          action,
+          error: 'confirmation-required',
+          reason: 'the installation and the uninstallation change the machine, so the user has to confirm the card first',
+          supervisor,
+        }
+      }
+      if (action === 'install') {
+        const choice = typeof args.choice === 'string' ? args.choice : ''
+        if (choice !== '') runtime.recordSupervisorChoice(choice)
+        const result = runtime.installSupervisor({ confirmed: true })
+        return {
+          ok: result.ok === true,
+          action,
+          kind: result.kind,
+          degraded: result.degraded,
+          reason: result.reason,
+          error: result.error ?? undefined,
+          steps: result.steps,
+          supervisor: runtime.supervisorStatus(),
+        }
+      }
+      const result = await runtime.uninstallSupervisor()
+      return {
+        ok: result.ok === true,
+        action,
+        reason: result.ok === true ? 'the supervisor was removed' : undefined,
+        error: result.error ?? undefined,
+        steps: result.steps,
+        previous: result.previous ?? undefined,
+        pending: result.pending ?? undefined,
+        supervisor: runtime.supervisorStatus(),
+      }
     },
   })
 }
@@ -3417,10 +5373,10 @@ function injectPageHeartbeat(html, bootId, routePath) {
 const AUTORESTART_PROMPT = [
   '## Restart policy (dsh-autorestart)',
   '- When DeepSeek Harness itself must restart (for example to load an installed or updated plugin bundle), do NOT kill or relaunch the app yourself with pwsh/taskkill/Stop-Process/npm scripts. A hard guard blocks such commands anyway (denials mention `blockManualRestart`).',
-  '- Call the `continuum_restart` tool instead (optional arguments: `reason`, `resume`, `defer_seconds`, `parkGoals`). It waits until every conversation is idle (no running turn, no queued inbox work) AND the host has been quiet for `settleMs` (default 2000 ms); the detached helper re-checks that gate immediately before killing, so other conversations are never killed mid-turn. It then relaunches the app, and after boot this plugin resumes the session and continues the work automatically.',
+  '- Call the `continuum_restart` tool instead (optional arguments: `reason`, `resume`, `defer_seconds`, `parkGoals`). It waits until every conversation is idle (no running turn — a running turn ALWAYS blocks; an inbox message nobody claimed blocks only until `queuedGraceMs`, default 60000 ms, after which it is treated as stuck and no longer blocks) AND the host has been quiet for `settleMs` (default 2000 ms); the detached helper re-checks that gate immediately before killing, so other conversations are never killed mid-turn. It then relaunches the app, and after boot this plugin resumes the session and continues the work automatically.',
   '- A goal-driven session is DISARMED automatically before the restart (its current round still finishes, nothing is lost), because such a session would otherwise keep the restart waiting forever: disarming only removes the process-local continuation authority, so no new round starts and the session goes idle. After the restart the goal is re-armed and continues. A goal whose round budget is spent cannot be continued and is reported instead. You can disarm your own goal on demand with `continuum_park_goal`, and retry a stuck recovery with `continuum_recover_now`.',
   '- Persist anything the next turn needs before restarting (workspace files, `todo_write`, goal state); do not rely on in-memory state.',
-  '- Inspect the lifecycle with `continuum_status`; cancel a pending restart with `continuum_cancel_restart`.',
+  '- Inspect the lifecycle with `continuum_status`; cancel a pending restart with `continuum_cancel_restart`. Its default scope is `mine`: it withdraws ONLY the calling session\'s own request and leaves the requests of the other sessions alone (a restart request is coalesced, so several sessions can wait for the same restart). Use `scope: "all"` to cancel the request for EVERYONE.',
   '- A session whose context exceeds the model window can be handed off to a fresh session with `continuum_handoff` (it carries the goal objective, the recorded reasons and a bounded tail of the conversation); this plugin refuses to auto-resume such a session, so hand it off instead of retrying it.',
   '- For multi-turn objectives prefer a durable goal (`create_goal`): after a restart the plugin re-arms it and the goal round driver keeps producing rounds. No goal is required for restart continuation — without one the plugin injects a single continuation message that continues the work in a fresh turn.',
 ].join('\n')
@@ -3753,6 +5709,124 @@ function buildParkRoute(ctx, runtime, config) {
   }
 }
 
+/**
+ * Build the POST `/cancel` route: withdraw ONE session's own restart request.
+ *
+ * It is the sibling of the `/park` route next to the health route and uses the
+ * same authentication rule (loopback OR a request the connection service
+ * admits). Body: `{ "sessionId": string, "scope"?: "mine" }`.
+ *
+ * The route NEVER cancels the request of everybody: `scope: "all"` is
+ * refused, that operation belongs to the tool (where the caller says it out
+ * loud). The answer reports what happened: `{ ok, cancelled, reason,
+ * remainingRequesters, sessionId }`.
+ *
+ * @param {object} ctx
+ * @param {object} runtime
+ * @param {object} config
+ */
+function buildCancelRoute(ctx, runtime, config) {
+  const routePath = resolveCancelPath(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 sessionId = typeof body.sessionId === 'string' ? body.sessionId.trim() : ''
+        const scope = typeof body.scope === 'string' && body.scope.trim() !== '' ? body.scope.trim() : 'mine'
+        const answer = (statusCode, value) => {
+          res.statusCode = statusCode
+          res.setHeader('content-type', 'application/json; charset=utf-8')
+          res.setHeader('cache-control', 'no-store')
+          res.end(JSON.stringify(value))
+        }
+        if (scope !== 'mine') {
+          // "Cancel everybody" is a tool operation: the route says no.
+          answer(400, {
+            ok: false,
+            cancelled: false,
+            reason: 'scope-not-allowed',
+            error: 'This route can only withdraw one session\'s own request (scope "mine").',
+            remainingRequesters: 0,
+            sessionId,
+          })
+          return
+        }
+        if (sessionId === '') {
+          answer(400, {
+            ok: false,
+            cancelled: false,
+            reason: 'session-id-required',
+            error: 'The session id is required: without it the own request cannot be identified.',
+            remainingRequesters: 0,
+            sessionId: '',
+          })
+          return
+        }
+        const outcome = cancelOwnRestart(runtime.state, { sessionId, now: Date.now() })
+        if (!outcome.removed) {
+          // Nothing was changed: the caller is not a requester (or the
+          // request is already gone). The reason says which.
+          const error = outcome.reason === 'not-a-requester'
+            ? 'This session did not request the pending restart, so nothing was cancelled.'
+            : outcome.reason === 'no-restart-pending'
+              ? 'There is no pending restart to cancel.'
+              : 'The own request could not be identified, so nothing was cancelled.'
+          runtime.log.warn(`the cancel route refused the request of session ${sessionId}: ${outcome.reason}`)
+          answer(200, {
+            ok: false,
+            cancelled: false,
+            reason: outcome.reason,
+            error,
+            remainingRequesters: outcome.remaining,
+            sessionId,
+          })
+          return
+        }
+        // Release ONLY this session's continuation request.
+        runtime.releaseRequesters([sessionId])
+        if (outcome.cancelled) runtime.stopPolling()
+        runtime.persist()
+        runtime.log.info(
+          outcome.cancelled
+            ? `session ${sessionId} withdrew the last restart request through the cancel route; the pending restart is cancelled`
+            : `session ${sessionId} withdrew its restart request through the cancel route; ${outcome.remaining} requester(s) remain`,
+        )
+        answer(200, {
+          ok: true,
+          cancelled: outcome.cancelled,
+          reason: outcome.reason,
+          remainingRequesters: outcome.remaining,
+          sessionId,
+        })
+      }).catch((error) => {
+        res.statusCode = 400
+        res.setHeader('content-type', 'application/json; charset=utf-8')
+        res.end(JSON.stringify({ ok: false, error: describeError(error) }))
+      })
+    },
+  }
+}
+
 /**
  * Build the POST `/recover` route: retry the post-restart recovery for the
  * still-pending sessions right now.
@@ -4019,7 +6093,7 @@ function buildChoiceRoute(ctx, runtime, config) {
           res.end(JSON.stringify({
             ok: false,
             error: 'no-choice',
-            instruction: 'Send { "includePlugins": true | false } and/or { "backupIncludePlugins": true | false } and/or { "backupOnRestart": true | false } and/or { "showSleepButton": true | false } and/or { "sleepCountdownSeconds": 0 | 10 | 20 | 30 | 60 } and/or { "restartGraceMs": 0 | 3000 | 5000 | 10000 | 20000 | 30000 }.',
+            instruction: 'Send { "includePlugins": true | false } and/or { "backupIncludePlugins": true | false } and/or { "backupOnRestart": true | false } and/or { "showSleepButton": true | false } and/or { "sleepCountdownSeconds": 0 | 10 | 20 | 30 | 60 } and/or { "restartGraceMs": 0 | 5000 | 10000 | 20000 | 30000 | 60000 }.',
           }))
           return
         }
@@ -4134,6 +6208,223 @@ function buildChoiceRoute(ctx, runtime, config) {
   }
 }
 
+/**
+ * The route of the self-starting supervisor.
+ *
+ * Three actions, and NOTHING happens without the confirmation:
+ *
+ *   - `status` — who starts this host and whether the restart can work;
+ *   - `plan` — what the installation WOULD change (the dry run: it writes
+ *     nothing and runs nothing);
+ *   - `install` / `uninstall` — the real thing, and they need `confirmed: true`
+ *     (the confirmation card is what says "yes").
+ *
+ * @param {object} ctx the plugin context
+ * @param {any} runtime the runtime of this plugin
+ * @param {object} config the normalized config
+ * @returns {object} the route
+ */
+function buildSupervisorRoute(ctx, runtime, config) {
+  const routePath = resolveSupervisorPath(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 action = typeof body.action === 'string' ? body.action.trim() : ''
+        if (action === 'status') {
+          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, supervisor: runtime.supervisorStatus() }))
+          return
+        }
+        if (action === 'plan' || action === 'install-plan') {
+          // The installation plan: what the registration WOULD do. Nothing is
+          // written and nothing is run.
+          const plan = planSupervisorInstall({
+            platform: runtime.env.platform,
+            // The desktop app manages itself: there is no plan there.
+            isDesktopApp: runtime.env.isDesktopApp === true,
+            // The startup matrix: only a `bare` host may get a supervisor.
+            startup: runtime.startupMode(),
+            // WHICH MACHINE IS THIS? (WSL is not a Linux.)
+            host: runtime.hostKind(),
+            nodePath: process.execPath,
+            execPath: process.execPath,
+            supervisorPath: supervisorPaths(path.dirname(runtime.stateFile)).script,
+            configPath: supervisorPaths(path.dirname(runtime.stateFile)).config,
+            kind: config.supervisorKind,
+          })
+          res.statusCode = 200
+          res.setHeader('content-type', 'application/json; charset=utf-8')
+          res.setHeader('cache-control', 'no-store')
+          res.end(JSON.stringify({
+            ok: plan.error ? false : true,
+            action,
+            plan,
+            error: plan.error ?? null,
+            reason: plan.reason,
+            supervisor: runtime.supervisorStatus(),
+          }))
+          return
+        }
+        if (action === 'dry-run' || action === 'derive') {
+          // B: the dry run. It shows what WOULD be written and runs nothing.
+          const plan = await runtime.deriveStartCommand()
+          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, plan, supervisor: runtime.supervisorStatus() }))
+          return
+        }
+        if (action === 'apply' || action === 'revert') {
+          if (body.confirmed !== true) {
+            // The dry run is the confirmation: without it nothing is written.
+            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: 'confirmation-required',
+              instruction: 'Send { "action": "' + action + '", "confirmed": true } after the user confirmed the dry run.',
+            }))
+            return
+          }
+          const result = action === 'apply'
+            ? await runtime.applyDerivedCommand()
+            : await runtime.revertDerivedCommand()
+          res.statusCode = result.ok === true ? 200 : 500
+          res.setHeader('content-type', 'application/json; charset=utf-8')
+          res.setHeader('cache-control', 'no-store')
+          res.end(JSON.stringify({
+            ok: result.ok === true,
+            action,
+            error: result.error ?? null,
+            writes: result.writes ?? null,
+            previous: result.previous ?? null,
+            reason: result.reason ?? null,
+            supervisor: runtime.supervisorStatus(),
+          }))
+          return
+        }
+        if (action === 'external') {
+          // "I keep my own way": nothing is installed, but the answer is
+          // recorded — so the plugin knows that a supervisor is already there
+          // and never installs a second one.
+          runtime.recordSupervisorChoice('external')
+          try {
+            await runtime.applyConfigChoice({ supervisorMode: 'external' })
+          } catch (error) {
+            runtime.log.warn('the supervisor mode could not be written:', String(error))
+          }
+          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, supervisor: runtime.supervisorStatus() }))
+          return
+        }
+        if (action === 'install' || action === 'uninstall') {
+          if (action === 'install' && runtime.env.isDesktopApp === true) {
+            // The desktop app manages itself: a login record would open a
+            // SECOND client at every login. The refusal comes BEFORE the
+            // confirmation, so nothing is asked of the user.
+            res.statusCode = 400
+            res.setHeader('content-type', 'application/json; charset=utf-8')
+            res.setHeader('cache-control', 'no-store')
+            res.end(JSON.stringify({
+              ok: false,
+              action,
+              error: 'desktop-manages-itself',
+              reason: 'the desktop app relaunches itself; a supervisor would start a second copy',
+              steps: [],
+              supervisor: runtime.supervisorStatus(),
+            }))
+            return
+          }
+          if (body.confirmed !== true) {
+            // The confirmation card is what says "yes": without it nothing is
+            // changed on the machine.
+            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: 'confirmation-required',
+              instruction: 'Send { "action": "' + action + '", "confirmed": true } after the user confirmed the card.',
+            }))
+            return
+          }
+          if (action === 'install') {
+            const choice = typeof body.choice === 'string' ? body.choice : ''
+            if (choice !== '') runtime.recordSupervisorChoice(choice)
+            const result = runtime.installSupervisor({ confirmed: true })
+            res.statusCode = result.ok ? 200 : 500
+            res.setHeader('content-type', 'application/json; charset=utf-8')
+            res.setHeader('cache-control', 'no-store')
+            res.end(JSON.stringify({
+              ok: result.ok === true,
+              action,
+              kind: result.kind,
+              degraded: result.degraded,
+              steps: result.steps,
+              error: result.error,
+              reason: result.reason,
+              supervisor: runtime.supervisorStatus(),
+            }))
+            return
+          }
+          const result = await runtime.uninstallSupervisor()
+          res.statusCode = result.ok ? 200 : 500
+          res.setHeader('content-type', 'application/json; charset=utf-8')
+          res.setHeader('cache-control', 'no-store')
+          res.end(JSON.stringify({
+            ok: result.ok === true,
+            action,
+            steps: result.steps,
+            error: result.error,
+            pending: result.pending,
+            previous: result.previous,
+            supervisor: runtime.supervisorStatus(),
+          }))
+          return
+        }
+        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: 'unknown-action',
+          instruction: 'Send { "action": "status" | "plan" | "install" | "uninstall" }.',
+        }))
+      }).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?
  *
@@ -4158,16 +6449,16 @@ function sleepDryRun() {
  * happened). The sleep feature counts down on screen itself, so it only needs
  * the busy check — and it keeps `settleMs` out of the picture entirely.
  *
- * The GRACE window is the exception: it is not a settle window but the extra
- * wait for work this plugin cannot see (a memory plugin writing its notes a
- * few seconds after the conversation ended). It is honoured BEFORE the
- * countdown starts, so the countdown is never pushed back by it.
+ * The shutdown has NO invisible reserve of its own: the visible countdown
+ * (`sleepCountdownSeconds`) IS the wait before the machine goes off, and it is
+ * on screen, so the user can see it and cancel it. A second, hidden window
+ * next to it would only say the same thing twice.
  *
  * The restart gate itself is untouched: the restart feature keeps its quiet
- * window exactly as it was (plus the same grace).
+ * window exactly as it was (plus its own restart reserve).
  *
  * @param {object} runtime
- * @returns {{ allow: boolean, reason: 'busy'|'grace'|'quiet', blockedBy: any[] }}
+ * @returns {{ allow: boolean, reason: 'busy'|'quiet', blockedBy: any[] }}
  */
 function sleepGate(runtime) {
   // A pending restart goes FIRST: the shutdown waits for it — and for the
@@ -4199,16 +6490,8 @@ function sleepGate(runtime) {
   }
   const list = Array.isArray(busy) ? busy : []
   if (list.length > 0) return { allow: false, reason: 'busy', blockedBy: list }
-  // The grace window: the last conversation may have finished a moment ago,
-  // and other plugins still have work queued that this plugin cannot see.
-  let quiet = 0
-  let grace = 0
-  try { quiet = Number(runtime.quietForMs()) } catch { quiet = 0 }
-  try { grace = Number(runtime.graceMs()) } catch { grace = 0 }
-  if (!Number.isFinite(quiet) || quiet < 0) quiet = 0
-  if (Number.isFinite(grace) && grace > 0 && quiet < grace) {
-    return { allow: false, reason: 'grace', blockedBy: [] }
-  }
+  // Nobody is busy and no restart is pending: the countdown may run. There is
+  // no invisible reserve — the countdown on screen is the wait.
   return { allow: true, reason: 'quiet', blockedBy: [] }
 }
 
@@ -4290,11 +6573,11 @@ function createSleepService(ctx, runtime, config, options = {}) {
     busyAgents: () => runtime.busyAgents(),
     gate,
     titleOf: (sessionId) => runtime.sessionTitle(sessionId),
-    // The grace window: after the last conversation finished the machine
-    // waits a little longer, so that work this plugin cannot see (a memory
-    // plugin writing its notes, a summary) still gets its chance.
-    quietForMs: () => runtime.quietForMs(),
-    graceMs: () => runtime.graceMs(),
+    // The shutdown has NO invisible reserve: the countdown on screen IS the
+    // wait before the machine goes off. The controller keeps the parameter for
+    // compatibility, but the plugin never injects a window — and it never
+    // injects the RESTART reserve either.
+    graceMs: () => 0,
     // A pending restart goes first: the shutdown waits for it.
     restartPending: () => {
       const pending = runtime.pendingRestart()
@@ -4429,9 +6712,10 @@ function sleepStatusPayload(sleep, config, runtime) {
     armed: status.armed,
     showSleepButton: config.showSleepButton !== false,
     countdownSeconds: status.countdownSeconds,
-    // The grace window and how long the host has been quiet: both are needed
-    // to tell "the machine is waiting for the grace" from "somebody is busy".
-    graceMs: config.restartGraceMs,
+    // The RESTART reserve is reported next to the countdown, so the settings
+    // page can show it. The shutdown itself has NO invisible reserve: the
+    // visible countdown is the wait before the machine goes off.
+    restartGraceMs: config.restartGraceMs,
     quietForMs: runtime && typeof runtime.quietForMs === 'function' ? runtime.quietForMs() : 0,
     // When the shutdown was armed: the intent has to survive a restart, so the
     // time is reported for the troubleshooting.
@@ -4573,12 +6857,18 @@ function registerHealthRoute(ctx, runtime, config, sleep) {
           generation: state.generation,
           pendingRestart: state.restart !== null,
           settleMs: config.settleMs,
-          // The grace window and the quiet window the gate really uses: both
-          // are needed to tell "waiting for the grace" from "somebody is busy".
+          // The RESTART reserve and the quiet window the gate really uses:
+          // both are needed to tell "waiting for the reserve" from "somebody
+          // is busy".
           graceMs: config.restartGraceMs,
           effectiveSettleMs: runtime.effectiveSettleMs(),
+          // The upper bound of a queued (unclaimed) inbox message: after this
+          // window it stops blocking the restart.
+          queuedGraceMs: config.queuedGraceMs,
           quietForMs: typeof verdict.quietForMs === 'number' ? verdict.quietForMs : 0,
-          busyCount: verdict.blockedBy.length,
+          // The number of TASKS the restart waits for: a session and its own
+          // subagents are ONE task, exactly as the left sidebar counts them.
+          busyCount: countBlockerTasks(verdict.blockedBy),
           agentCount,
         })
         res.statusCode = 200
@@ -4639,17 +6929,32 @@ function registerHealthRoute(ctx, runtime, config, sleep) {
             waiters,
             blockedBy,
             allowRestart: verdict.allow === true,
+            // WHY the gate says what it says. Without this, "allowRestart is
+            // false and blockedBy is empty" looks like a contradiction: the
+            // reason tells the two apart (an empty blocker list with the
+            // reason "settling" means the quiet window is not full yet).
+            reason: typeof verdict.reason === 'string' ? verdict.reason : 'unknown',
             quietForMs: typeof verdict.quietForMs === 'number' ? verdict.quietForMs : 0,
             settleMs: config.settleMs,
-            // The grace window and the quiet window the gate really uses.
+            // The RESTART reserve and the quiet window the gate really uses.
             graceMs: config.restartGraceMs,
             effectiveSettleMs: runtime.effectiveSettleMs(),
+            // The upper bound of a queued (unclaimed) inbox message.
+            queuedGraceMs: config.queuedGraceMs,
+            // The long wait: present only when the restart passed the hard
+            // deadline while a conversation was still running. It says how
+            // long the restart has been waiting, why, and who holds it — the
+            // request itself is never dropped.
+            longWait: runtime.longWaitInfo(),
             updatedAt: live.updatedAt,
             // The park route, so the client never has to guess the prefix, and
             // the goals this plugin already disarmed (they are re-armed after
             // the restart).
             parkUrl: resolveParkPath(config),
             recoverUrl: resolveRecoverPath(config),
+            // The route that withdraws ONE session's own restart request (the
+            // manual "cancel my restart" of the pill).
+            cancelUrl: resolveCancelPath(config),
             // The route that persists the one-time install choice, plus the
             // value that is effective right now.
             choiceUrl: resolveChoicePath(config),
@@ -4658,8 +6963,67 @@ function registerHealthRoute(ctx, runtime, config, sleep) {
             announcementsUrl: resolveAnnouncementsPath(config),
             backupOnRestart: config.backupOnRestart !== false,
             backupIncludePlugins: config.backupIncludePlugins !== false,
+            // WHAT IS ON DISK RIGHT NOW: the backups of this host (the count,
+            // the local time, the size, whether the plugins are in it and
+            // where it lives). The browser cannot read the disk, so the Host
+            // reads it — only the directory, never the contents.
+            backups: runtime.backupsInfo(),
+            // 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.
+            restart: {
+              mode: config.restartMode,
+              command: typeof config.restartCommand === 'string' ? config.restartCommand : '',
+              written: typeof config.restartCommand === 'string' && config.restartCommand !== '',
+              canRevert: Boolean(
+                live.onboarding
+                && typeof live.onboarding === 'object'
+                && live.onboarding.previous
+                && typeof live.onboarding.previous.restartMode === 'string',
+              ),
+              previous: live.onboarding && typeof live.onboarding === 'object' && live.onboarding.previous
+                ? live.onboarding.previous
+                : null,
+            },
             parkedGoals: parkedGoalList(runtime),
             recovery: recoveryList(live),
+            // THE ACCESS LINK of this instance (with the boot token). The boot
+            // token is created per process, so the link the browser holds
+            // answers 401 after a restart. The client needs the new link to
+            // get the user back into the interface.
+            accessUrl: accessUrlOf(runtime),
+            // The supervisor: who starts this host, and whether the restart
+            // can work at all.
+            supervisor: runtime.supervisorStatus(),
+            // WHICH END this is. The browser side serves the desktop app AND
+            // the hosted web host, so it may not assume one of them: the
+            // desktop app brings itself back up (there is nothing to install
+            // there), while the hosted host may ask for a supervisor.
+            instance: {
+              isDesktopApp: runtime.env.isDesktopApp === true,
+              platform: runtime.env.platform,
+            },
+            // THE LAST RESTART: the snapshot that was taken before it (the
+            // directory, its LOCAL time, how long it took, which older
+            // snapshots were pruned) and the verdict of the instance that came
+            // up (the four checks). Without it a restart has no visible
+            // result at all.
+            lastRestart: runtime.lastRestartVerdict(),
+            // Whether the one-time question about the supervisor may be asked.
+            supervisorOffer: runtime.supervisorOffer,
+            // The answer of the one-time question about the supervisor (null
+            // while it was never answered).
+            onboarding: runtime.onboardingChoice,
+            // The route that installs, uninstalls and reports the supervisor.
+            supervisorUrl: resolveSupervisorPath(config),
+            // "REPORT A PROBLEM": the diagnostic text (built by ONE generator on
+            // the host, so the browser and the host can never drift) and the
+            // two places a report can go.
+            diagnostics: runtime.diagnostics(),
+            report: {
+              email: SUPPORT_EMAIL,
+              issueUrlBase: ISSUE_URL_BASE,
+            },
           })
         } catch {
           // The banner must never break the health route: fall back to "no restart".
@@ -4669,9 +7033,13 @@ function registerHealthRoute(ctx, runtime, config, sleep) {
             waiters: [],
             blockedBy: [],
             allowRestart: false,
+            reason: 'unknown',
             quietForMs: 0,
+            queuedGraceMs: config.queuedGraceMs,
+            longWait: null,
             parkUrl: resolveParkPath(config),
             recoverUrl: resolveRecoverPath(config),
+            cancelUrl: resolveCancelPath(config),
             choiceUrl: resolveChoicePath(config),
             announcementsUrl: resolveAnnouncementsPath(config),
             backupOnRestart: config.backupOnRestart !== false,
@@ -4733,49 +7101,44 @@ function registerHealthRoute(ctx, runtime, config, sleep) {
     const recoverRoute = buildRecoverRoute(ctx, runtime, config)
     const handoffRoute = buildHandoffRoute(ctx, runtime, config)
     const choiceRoute = buildChoiceRoute(ctx, runtime, config)
+    const cancelRoute = buildCancelRoute(ctx, runtime, config)
     const announcementsRoute = buildAnnouncementsRoute(ctx, runtime, config)
+    const supervisorRoute = buildSupervisorRoute(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)
       if (portMatch) runtime.webPort = Number(portMatch[1])
+      // THE INSTANCE RECORD. The new instance publishes its own port and its
+      // own access link (with the boot token), so:
+      //   - the rollback watcher learns the port of the NEW instance instead
+      //     of guessing the (random) port of the old one;
+      //   - the user finds the access link of the new instance after a
+      //     restart, instead of being locked out by a 401.
+      publishInstanceRecord(ctx, runtime, config, origin)
     } catch {}
-    try {
-      target.effect(() => webServer.register(route), 'dsh-autorestart: health route')
-    } catch (error) {
-      // A duplicate registration means another load of this plugin already owns it.
-      runtime.log.warn('could not register the health route:', String(error))
-    }
-    try {
-      target.effect(() => webServer.register(parkRoute), 'dsh-autorestart: park route')
-    } catch (error) {
-      runtime.log.warn('could not register the park route:', String(error))
-    }
-    try {
-      target.effect(() => webServer.register(recoverRoute), 'dsh-autorestart: recover route')
-    } catch (error) {
-      runtime.log.warn('could not register the recover route:', String(error))
-    }
-    try {
-      target.effect(() => webServer.register(handoffRoute), 'dsh-autorestart: handoff route')
-    } 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) {
+    // The routes of this plugin. Every one of them is remembered: the boot
+    // check of the restart record reports "the routes are there" — a host
+    // that came up without them is not a healthy host.
+    const routes = [
+      { name: 'health', route },
+      { name: 'park', route: parkRoute },
+      { name: 'recover', route: recoverRoute },
+      { name: 'handoff', route: handoffRoute },
+      { name: 'choice', route: choiceRoute },
+      { name: 'cancel', route: cancelRoute },
+      { name: 'announcements', route: announcementsRoute },
+      { name: 'supervisor', route: supervisorRoute },
+    ]
+    if (sleepRoute !== null) routes.push({ name: 'sleep', route: sleepRoute })
+    for (const entry of routes) {
       try {
-        target.effect(() => webServer.register(sleepRoute), 'dsh-autorestart: sleep route')
+        target.effect(() => webServer.register(entry.route), 'dsh-autorestart: ' + entry.name + ' route')
+        runtime.registeredRoutes.push(entry.name)
       } catch (error) {
-        runtime.log.warn('could not register the sleep route:', String(error))
+        // A duplicate registration means another load of this plugin already owns it.
+        runtime.log.warn('could not register the ' + entry.name + ' route:', String(error))
+        runtime.routeErrors.push({ route: entry.name, error: String(error) })
       }
     }
     if (config.autoReloadPage !== false && typeof webServer.tapIndex === 'function') {
@@ -4838,9 +7201,20 @@ function trackAgents(ctx, runtime, config) {
     }
   })
 
-  // Any session event or newly queued inbox message restarts the settle window.
-  ctx.on('session/event', () => {
+  // A session event only restarts the settle window when it says that WORK
+  // happened (a message, a tool, a turn). The host produces session events
+  // every two to three seconds while the interface polls and synchronises —
+  // counting those as activity kept the quiet window from ever filling, so a
+  // restart with a grace window of ten seconds NEVER fired. When the type of
+  // an event cannot be read, it is not activity: the plugin would rather
+  // restart a little early than never restart at all.
+  //
+  // The hard guarantee is elsewhere and untouched: a conversation that is
+  // really running blocks the restart through `busyAgents()`, which is never
+  // relaxed.
+  ctx.on('session/event', (payload) => {
     try {
+      if (!isWorkSessionEvent(payload)) return
       runtime.noteActivity()
     } catch {}
   })
@@ -4989,15 +7363,35 @@ export function apply(ctx, rawConfig, options = {}) {
   if (runtime.isNewBoot && config.resumeOnBoot) {
     runtime.recoverTimer = ctx.timeout(() => {
       recoverAfterRestart(ctx, runtime, config)
-        .then(() => { restoreSleepIntent() })
+        .then(() => {
+          runtime.recovery = { ran: true, ok: true, detail: 'the boot recovery finished' }
+          restoreSleepIntent()
+        })
         .catch((error) => {
           log.warn('boot recovery failed:', String(error))
+          runtime.recovery = { ran: true, ok: false, detail: 'the boot recovery failed: ' + String(error) }
           restoreSleepIntent()
         })
+        // THE VERDICT OF THE RESTART. The instance that replaced the old one
+        // checks itself (listener / routes / plugin / recovery) and writes the
+        // result into the durable restart record. Without this the four
+        // checks would live nowhere and a failed restart would look like a
+        // successful one.
+        .then(() => verifyRestartBoot(runtime))
+        .catch((error) => {
+          log.warn('the boot verification failed:', String(error))
+        })
     }, Math.max(0, config.recoveryDelayMs))
   } else {
     // No recovery pass: the intent is restored right away (a hot reload must
     // not lose it either).
+    runtime.recovery = {
+      ran: false,
+      ok: true,
+      detail: runtime.isNewBoot
+        ? 'the boot recovery is switched off'
+        : 'this is not a new boot',
+    }
     restoreSleepIntent()
   }
 
@@ -5027,4 +7421,5 @@ export {
   pluginVersion,
   PLUGIN_VERSION_FALLBACK,
   SLEEP_FEATURE_VERSION,
+  SUPERVISOR_FEATURE_VERSION,
 }