dsh-autorestart 0.6.2 → 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,18 +64,70 @@ 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'
@@ -125,6 +179,114 @@ const DEFAULT_RESTART_GRACE_MS = 0
  */
 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 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
+
+/**
+ * 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.
  *
@@ -158,7 +320,7 @@ function snapGraceChoice(value, fallback = DEFAULT_RESTART_GRACE_MS) {
  * `pluginVersion()`), but a bundled installation may not ship that file — so
  * the constant below is the last resort. A test keeps the two in sync.
  */
-const PLUGIN_VERSION_FALLBACK = '0.6.2'
+const PLUGIN_VERSION_FALLBACK = '0.7.0'
 
 /**
  * The version of the graceful-shutdown FEATURE, not the version of the package.
@@ -179,6 +341,14 @@ const PLUGIN_VERSION_FALLBACK = '0.6.2'
  */
 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
 
@@ -226,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 },
   ]
 }
 
@@ -442,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)
@@ -500,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).
@@ -530,6 +739,35 @@ 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".
@@ -608,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`
@@ -623,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
@@ -1019,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.
@@ -1031,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,
@@ -1040,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 = {},
@@ -1049,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,
     })
@@ -1071,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,
@@ -1086,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. */
@@ -1200,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.
@@ -1217,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())
@@ -1230,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
@@ -1239,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 {
@@ -2087,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
@@ -2171,144 +2527,942 @@ const titleOfSummary = (item) => {
     return 'http://127.0.0.1:' + port + resolveHealthPath(config)
   }
 
-  /** Execute the restart now; the detached helper survives our own death. */
-  const executeRestart = async () => {
-    stopPolling()
-    if (!state.restart) return
+  /**
+   * 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 {
-      await flushSessions()
-    } catch {}
-    // Re-check the gate AFTER the flush and BEFORE anything is killed or scheduled:
-    // another conversation may have started while the sessions were being written.
-    // This re-check also protects the ungated fallback (>20 gate aborts) and the
-    // forceRestartWhenBusy path: even when the detached helper cannot re-check the
-    // gate itself, a busy conversation is never killed here.
-    // Last chance to park a goal-driven session: without it the detached
-    // helper would refuse to kill the process and the restart would wait.
+      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 {
-      disarmBlockingGoals(busyAgents())
-    } catch (error) {
-      log.warn('could not disarm the goals of the blocking sessions:', String(error))
+      current = readRestartVerdict(dir)
+    } catch {
+      current = null
     }
-    const verdict = gate()
-    if (!verdict.allow) {
-      log.info('restart deferred: a conversation is still active or the host is settling', {
-        reason: verdict.reason,
-        blockedBy: verdict.blockedBy,
-        quietForMs: verdict.quietForMs,
-      })
-      persist()
-      startPolling()
-      return
+    if (options.skipIfFinalized === true
+      && current !== null
+      && current.bootId !== null
+      && current.result !== RESTART_RESULTS.PENDING) {
+      return current
     }
-    setPhase(state, 'restarting')
-    state.restart.attempt += 1
-    persist()
-    log.warn('executing graceful restart', { generation: state.generation, pid: process.pid })
-    try {
-      // How the host is restarted: the custom command, or the desktop app.
-      const useCustomCommand = config.restartMode === 'command' && config.restartCommand.trim() !== ''
-      const canRelaunchDesktop = Boolean(env.isDesktopApp && env.appExePath)
-      if (!useCustomCommand && !canRelaunchDesktop) {
-        // No restart method at all (the host is not the desktop app and there is
-        // no custom command): nothing is restarted, so nothing is snapshotted
-        // either — there is no rollback point for a restart that never happens.
-        log.warn('no restart method available (not the desktop app and restartCommand is empty); leaving the checkpoint in place')
-        rollbackRestart('no restart method available')
-        return
-      }
+    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
+  }
 
-      // ONE snapshot for EVERY restart mode: the profile is copied BEFORE
-      // anything is killed, no matter how the host is restarted. The desktop
-      // app relaunch and the custom restart command share this single entry, so
-      // a hosted host that is restarted by a command is just as recoverable as
-      // the desktop app.
-      const stateDir = path.dirname(stateFile)
-      const snapshot = snapshotFn({
-        config,
-        stateDir,
-        log,
-        profile: resolveProfileDirDetailed(),
-      })
+  /**
+   * 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 })
 
-      if (useCustomCommand) {
-        const command = buildCustomCommand({
-          template: config.restartCommand,
-          pid: process.pid,
-          ppid: process.ppid,
-          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')
-      } else {
-        const aborts = Number(state.restart.gateAborts) || 0
-        const url = aborts > 20 ? null : restartGateUrl()
-        if (aborts > 20) {
-          log.error('falling back to an UNGATED restart after repeated idle-gate aborts', { gateAborts: aborts })
-        } else if (url === null) {
-          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
-          ? path.join(stateDir, 'restart-' + state.generation + '-watch.ps1')
-          : null
-        const watchScript = watchScriptPath === null
-          ? null
-          : buildWatchScript({
-            healthUrl,
-            backupDir: backup.dir,
-            profileDir,
-            reportPath: path.join(stateDir, ROLLBACK_REPORT_NAME),
-            appExePath: env.appExePath,
-            timeoutMs: config.rollbackTimeoutMs,
-            // Only a crash log written after this point belongs to this restart.
-            since: new Date().toISOString(),
-          })
-        const result = scheduleDetachedFn({
-          appExePath: env.appExePath,
-          relaunchDelaySeconds: config.relaunchDelaySeconds,
-          gateUrl: url,
-          scriptPath: url === null ? null : path.join(stateDir, 'restart-' + state.generation + '.cmd'),
-          watchScriptPath,
-          watchScript,
-        })
-        log.warn('scheduled detached restart:', result)
-        if (!result || result.ok !== true) rollbackRestart((result && result.error) || 'detached restart refused')
-        else armGateWatchdog()
-      }
-    } catch (error) {
-      rollbackRestart(String(error))
-    }
+  /**
+   * 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
   }
 
-  /** One decision tick while a restart is pending. */
-  const tick = () => {
-    if (disposed) return
-    if (!state.restart) {
-      stopPolling()
-      return
-    }
-    const now = Date.now()
-    const busy = busyAgents()
-    // A goal-driven session blocks the restart forever: park its goal BEFORE the
-    // gate decides that it is blocked, so the next poll sees an idle session.
-    if (busy.length > 0) {
-      try {
-        disarmBlockingGoals(busy)
-      } catch (error) {
-        log.warn('could not disarm the goals of the blocking sessions:', String(error))
-      }
+  /**
+   * 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,
     }
-    const decision = restartDecision(state, {
-      anyAgentRunning: busy.length > 0,
-      busyAgents: busy,
-      lastActivityAt: quietSince(),
-      settleMs: effectiveSettleMs(),
+  }
+
+  /**
+   * 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()
+    if (!state.restart) return
+    try {
+      await flushSessions()
+    } catch {}
+    // Re-check the gate AFTER the flush and BEFORE anything is killed or scheduled:
+    // another conversation may have started while the sessions were being written.
+    // This re-check also protects the ungated fallback (>20 gate aborts) and the
+    // forceRestartWhenBusy path: even when the detached helper cannot re-check the
+    // gate itself, a busy conversation is never killed here.
+    // Last chance to park a goal-driven session: without it the detached
+    // helper would refuse to kill the process and the restart would wait.
+    try {
+      disarmBlockingGoals(busyAgents())
+    } catch (error) {
+      log.warn('could not disarm the goals of the blocking sessions:', String(error))
+    }
+    const verdict = gate()
+    if (!verdict.allow) {
+      log.info('restart deferred: a conversation is still active or the host is settling', {
+        reason: verdict.reason,
+        blockedBy: verdict.blockedBy,
+        quietForMs: verdict.quietForMs,
+      })
+      persist()
+      startPolling()
+      return
+    }
+    setPhase(state, 'restarting')
+    state.restart.attempt += 1
+    persist()
+    log.warn('executing graceful restart', { generation: state.generation, pid: process.pid })
+    try {
+      // How the host is restarted: the custom command, or the desktop app.
+      const useCustomCommand = config.restartMode === 'command' && config.restartCommand.trim() !== ''
+      const canRelaunchDesktop = Boolean(env.isDesktopApp && env.appExePath)
+      if (!useCustomCommand && !canRelaunchDesktop) {
+        // No restart method at all (the host is not the desktop app and there is
+        // no custom command): nothing is restarted, so nothing is snapshotted
+        // either — there is no rollback point for a restart that never happens.
+        log.warn('no restart method available (not the desktop app and restartCommand is empty); leaving the checkpoint in place')
+        rollbackRestart('no restart method available')
+        return
+      }
+
+      // ONE snapshot for EVERY restart mode: the profile is copied BEFORE
+      // anything is killed, no matter how the host is restarted. The desktop
+      // app relaunch and the custom restart command share this single entry, so
+      // a hosted host that is restarted by a command is just as recoverable as
+      // the desktop app.
+      const stateDir = path.dirname(stateFile)
+      const snapshot = snapshotFn({
+        config,
+        stateDir,
+        log,
+        profile: resolveProfileDirDetailed(),
+      })
+      // 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,
+          ppid: process.ppid,
+          appExePath: env.appExePath || '',
+        })
+        log.warn('running custom restart command:', command)
+
+        // (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()
+        if (aborts > 20) {
+          log.error('falling back to an UNGATED restart after repeated idle-gate aborts', { gateAborts: aborts })
+        } else if (url === null) {
+          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 healthUrl = restartHealthUrl()
+        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),
+            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: gateScriptPath,
+          watchScriptPath,
+          watchScript,
+        })
+        log.warn('scheduled detached restart:', result)
+        if (!result || result.ok !== true) rollbackRestart((result && result.error) || 'detached restart refused')
+        else armGateWatchdog()
+      }
+    } catch (error) {
+      rollbackRestart(String(error))
+    }
+  }
+
+  /** One decision tick while a restart is pending. */
+  const tick = () => {
+    if (disposed) return
+    if (!state.restart) {
+      stopPolling()
+      return
+    }
+    const now = Date.now()
+    const busy = busyAgents()
+    // A goal-driven session blocks the restart forever: park its goal BEFORE the
+    // gate decides that it is blocked, so the next poll sees an idle session.
+    if (busy.length > 0) {
+      try {
+        disarmBlockingGoals(busy)
+      } catch (error) {
+        log.warn('could not disarm the goals of the blocking sessions:', String(error))
+      }
+    }
+    const decision = restartDecision(state, {
+      anyAgentRunning: busy.length > 0,
+      busyAgents: busy,
+      lastActivityAt: quietSince(),
+      settleMs: effectiveSettleMs(),
       now,
       softMs: config.deferSoftMs,
       hardMs: config.deferHardMs,
@@ -2557,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,
@@ -2613,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,
@@ -3220,9 +4496,140 @@ async function recoverAfterRestart(ctx, runtime, config) {
       maxSessions: config.maxSessions,
     })
   }
-  persistSafely(runtime)
-  log.info('recovery finished:', results)
-  return { recovered: results, phase: 'running' }
+  persistSafely(runtime)
+  log.info('recovery finished:', results)
+  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). */
@@ -3436,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' } },
         },
@@ -3472,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,
@@ -3647,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.' },
       },
     },
@@ -3663,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(),
+      }
     },
   })
 }
@@ -3719,7 +5376,7 @@ const AUTORESTART_PROMPT = [
   '- 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')
@@ -4052,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.
@@ -4433,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?
  *
@@ -4874,7 +6866,9 @@ function registerHealthRoute(ctx, runtime, config, sleep) {
           // 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
@@ -4958,6 +6952,9 @@ function registerHealthRoute(ctx, runtime, config, sleep) {
             // 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),
@@ -4966,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".
@@ -4983,6 +7039,7 @@ function registerHealthRoute(ctx, runtime, config, sleep) {
             longWait: null,
             parkUrl: resolveParkPath(config),
             recoverUrl: resolveRecoverPath(config),
+            cancelUrl: resolveCancelPath(config),
             choiceUrl: resolveChoicePath(config),
             announcementsUrl: resolveAnnouncementsPath(config),
             backupOnRestart: config.backupOnRestart !== false,
@@ -5044,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') {
@@ -5311,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()
   }
 
@@ -5349,4 +7421,5 @@ export {
   pluginVersion,
   PLUGIN_VERSION_FALLBACK,
   SLEEP_FEATURE_VERSION,
+  SUPERVISOR_FEATURE_VERSION,
 }