dsh-autorestart 0.8.4 → 0.8.5

package/index.js

@@ -77,7 +77,14 @@ import {
   claimRollbackLock,
   clearRollbackReport,
   createBackup,
+  DEFAULT_MAX_BACKUPS,
+  KIND_KNOWN_GOOD,
+  KIND_SNAPSHOT,
+  latestKnownGood,
+  listBackupIdentities,
   listBackups,
+  markKnownGood,
+  readManifest,
   readRollbackReport,
   releaseRollbackLock,
   restoreBackup,
@@ -387,7 +394,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.8.4'
+const PLUGIN_VERSION_FALLBACK = '0.8.5'
 
 /**
  * The version of the graceful-shutdown FEATURE, not the version of the package.
@@ -677,8 +684,8 @@ function buildConfigSchema() {
       // rollback of "a plugin upgrade broke the boot" possible)
       backupIncludePlugins: schemastery.boolean().default(true)
         .description('Include the installed plugin tree in that snapshot: about 117 MB and roughly 3 extra seconds, but it is what makes a rollback of a broken plugin upgrade possible.'),
-      maxBackups: schemastery.number().step(1).min(1).default(2)
-        .description('How many snapshots are kept; older ones are deleted automatically.'),
+      maxBackups: schemastery.number().step(1).min(1).default(DEFAULT_MAX_BACKUPS)
+        .description('How many snapshots are kept (default 3: the current one plus the two before it); older ones are deleted automatically, except the newest known-good one, which is never removed.'),
       rollbackTimeoutMs: schemastery.number().min(1000).default(90000)
         .description('Milliseconds the detached watcher waits for the relaunched host before it restores the snapshot.'),
       // The watchdog: the process that waits for the relaunched host and puts
@@ -767,7 +774,7 @@ const DEFAULTS = {
   // detached watcher puts the snapshot back and launches the host again.
   backupOnRestart: true,
   backupIncludePlugins: true,
-  maxBackups: 2,
+  maxBackups: DEFAULT_MAX_BACKUPS,
   // The WATCHDOG: the process that waits for the relaunched host and puts the
   // snapshot back when it never answers. It needs a way to be triggered
   // later (a scheduled task, a systemd timer, a detached process) — the
@@ -813,7 +820,7 @@ function normalizeConfig(raw) {
   if (config.deferPolicy !== 'auto' && config.deferPolicy !== 'wait') config.deferPolicy = 'auto'
   if (config.restartMode !== 'app' && config.restartMode !== 'command') config.restartMode = 'app'
   const maxBackups = Number(config.maxBackups)
-  config.maxBackups = Number.isFinite(maxBackups) && maxBackups >= 1 ? Math.trunc(maxBackups) : 2
+  config.maxBackups = Number.isFinite(maxBackups) && maxBackups >= 1 ? Math.trunc(maxBackups) : DEFAULT_MAX_BACKUPS
   const rollbackTimeout = Number(config.rollbackTimeoutMs)
   config.rollbackTimeoutMs =
     Number.isFinite(rollbackTimeout) && rollbackTimeout >= 1000 ? Math.trunc(rollbackTimeout) : 90000
@@ -910,6 +917,20 @@ function resolveHandoffPath(config) {
   return `${prefix}/handoff`
 }
 
+/**
+ * Resolve the manual-rollback route path: a sibling of the health route, under
+ * the same prefix (`POST /rollback-to` restores ONE backup the user picked).
+ *
+ * @param {object} config
+ * @returns {string}
+ */
+function resolveManualRollbackPath(config) {
+  const healthPath = resolveHealthPath(config)
+  const index = healthPath.lastIndexOf('/')
+  const prefix = index > 0 ? healthPath.slice(0, index) : '/__dsh_autorestart'
+  return `${prefix}/rollback-to`
+}
+
 /**
  * Resolve the choice-route path: a sibling of the health route, under the same
  * prefix (`POST /choice` persists the one-time install choice of the user).
@@ -1378,6 +1399,101 @@ function backupsDirFor(dir) {
   return backupsRoot(typeof dir === 'string' ? dir : '')
 }
 
+/**
+ * THE FIRST SAFE COPY (user decision, 2026-10-30).
+ *
+ * A machine that has never restarted has no backup at all, so a boot that fails
+ * after the plugin is installed has nothing to roll back to. The FIRST boot of a
+ * NEW host process therefore seeds one known-good copy of the profile.
+ *
+ * Two rules keep it honest:
+ *   - a plugin RELOAD is not an installation: `runtime.isNewBoot` must be true,
+ *     and nothing is written on a reload;
+ *   - a machine that already has a known-good copy gets no second seed.
+ *
+ * A failure is NOT silent: it is recorded on `runtime.firstInstallBackup` (and
+ * in the checkpoint, so it survives the next boot) and the health route reports
+ * it, because a machine with no safe copy must be able to say so.
+ *
+ * @param {object} runtime
+ * @param {object} [config]
+ * @param {{ profileDir?: string }} [overrides] the profile to copy (tests pass it)
+ * @returns {Promise<object|null>} the record that was written (null = nothing to do)
+ */
+export async function seedFirstInstallBackup(runtime, config = {}, overrides = {}) {
+  const state = runtime && runtime.state && typeof runtime.state === 'object' ? runtime.state : null
+  if (state === null) return null
+  if (runtime.isNewBoot !== true) return null
+  // NO BACKUPS AT ALL: the user switched the pre-restart snapshot off, so a
+  // safe copy is not wanted either.
+  if (config.backupOnRestart === false) return null
+  const stateDir = path.dirname(String(runtime.stateFile ?? ''))
+  const backupsDir = backupsDirFor(stateDir)
+  /**
+   * Record the outcome where the interface can see it.
+   *
+   * @param {object} value
+   * @returns {object}
+   */
+  const record = (value) => {
+    state.firstInstallBackup = value
+    runtime.firstInstallBackup = value
+    persistSafely(runtime)
+    return value
+  }
+  const existing = latestKnownGood(backupsDir)
+  if (existing !== null) {
+    return record({ result: 'present', at: Date.now(), dir: existing.dir, bytes: null, error: null })
+  }
+  /**
+   * Report that this machine has NO safe copy, with the reason.
+   *
+   * @param {string} error
+   * @returns {object}
+   */
+  const failed = (error) => {
+    const value = { result: 'no-known-good', at: Date.now(), dir: null, bytes: null, error: String(error) }
+    try {
+      runtime.log.warn('the first safe copy could not be written: this machine has nothing to roll back to', { error: String(error) })
+    } catch {}
+    return record(value)
+  }
+  const profileDir = typeof overrides.profileDir === 'string' && overrides.profileDir !== ''
+    ? overrides.profileDir
+    : resolveProfileDir()
+  if (profileDir === null) return failed('the profile directory could not be resolved')
+  const maxBackups = Number(config.maxBackups)
+  let result = null
+  try {
+    result = await createBackup({
+      profileDir,
+      backupsDir,
+      // CONFIGURATION ONLY. The seed exists so a fresh installation has
+      // something to roll back to at once; the plugin tree (the 117 MB part)
+      // comes with the snapshot of the first restart, which is promoted to
+      // known-good as soon as that restart proves it boots.
+      includePlugins: false,
+      maxBackups: Number.isFinite(maxBackups) && maxBackups >= 1 ? Math.trunc(maxBackups) : DEFAULT_MAX_BACKUPS,
+      kind: KIND_KNOWN_GOOD,
+      reason: 'first-install',
+      version: runtime.pluginVersion ?? PLUGIN_VERSION_FALLBACK,
+      bootId: runtime.bootId ?? null,
+    })
+  } catch (error) {
+    return failed(error && error.message ? error.message : String(error))
+  }
+  if (!result || result.ok !== true || typeof result.dir !== 'string' || result.dir === '') {
+    return failed(result && result.error ? result.error : 'the safe copy was not written')
+  }
+  return record({
+    result: 'seeded',
+    at: Date.now(),
+    dir: result.dir,
+    bytes: Number.isFinite(result.bytes) ? result.bytes : null,
+    error: null,
+  })
+}
+
 /**
  * The pre-restart snapshot: copy the profile into `<stateDir>/backups/<stamp>/`
  * and clear the rollback report an older boot may have left behind.
@@ -2588,12 +2704,18 @@ const titleOfSummary = (item) => {
     state.restart.failedAttempts = (Number(state.restart.failedAttempts) || 0) + 1
     if (state.restart.failedAttempts >= 2) {
       log.error('restart could not be scheduled twice; cancelling the pending restart instead of retrying forever:', reason)
+      // The restart is gone: so is its stage (a stage without a restart would
+      // draw a card for nothing).
+      clearRestartStage()
       releaseRequesters()
       cancelRestart(state, { now: Date.now() })
       persist()
       stopPolling()
       return
     }
+    // A retry is scheduled: the stage goes back to waiting, WITH the reason, so
+    // no surface keeps showing the step that already ended.
+    deferRestartStage(String(reason))
     setPhase(state, 'deferred')
     if (state.restart.attempt > 0) state.restart.attempt -= 1
     // Back off before the next attempt: no tight retry loop on a broken scheduler.
@@ -2615,6 +2737,12 @@ const titleOfSummary = (item) => {
         const aborts = (Number(state.restart.gateAborts) || 0) + 1
         state.restart.gateAborts = aborts
         if (state.restart.attempt > 0) state.restart.attempt -= 1
+        // The helper refused to kill this process (a conversation is active): the
+        // restart is postponed, so the stage must say 'waiting' — this is the
+        // exact path that left the backup card on screen for ever.
+        deferRestartStage('detached helper denied the idle gate', {
+          blocked: countBlockerTasks(gate().blockedBy),
+        })
         setPhase(state, 'deferred')
         if (aborts > 20) {
           log.error('the detached helper aborted on the idle gate more than 20 times; the next attempt is scheduled UNGATED:', { gateAborts: aborts })
@@ -2661,13 +2789,170 @@ const titleOfSummary = (item) => {
    * @param {{ blocked?: number, now?: number }} [options]
    * @returns {object|null} the recorded stage
    */
-  const markRestartStage = (phase, { blocked = 0, now = Date.now() } = {}) => {
+  /**
+   * HOW OFTEN THE IDLE GATE IS RE-CHECKED WHILE THE HOST WAITS TO BE KILLED.
+   *
+   * THE REPORT (user, 2026-10-30): after the backup the card said "正在重启…" for
+   * 25 s while nothing was restarting — the helper was still waiting for its own
+   * idle re-check, and only THEN did the stage go back to 'waiting'. 300–500 ms
+   * is the window the owner asked for: a restart that is not going to happen must
+   * be downgraded before anybody reads the old word.
+   */
+  const RESTART_BUSY_CHECK_MS = 350
+  let restartBusyTimer = null
+
+  /** Stop the re-check of the idle gate (idempotent). */
+  const stopRestartBusyWatch = () => {
+    if (restartBusyTimer === null) return
+    try {
+      restartBusyTimer()
+    } catch {
+      // The timer belongs to a disposed fiber already.
+    }
+    restartBusyTimer = null
+  }
+
+  /**
+   * WHILE THE STAGE SAYS 'restarting', NOBODY MAY BECOME BUSY UNNOTICED.
+   *
+   * 'restarting' is a CLAIM: from here on the only thing left is the process
+   * being killed. A conversation that starts while the helper waits makes that
+   * claim false, so it is withdrawn at once (the gate is re-checked four times a
+   * second) instead of being discovered by the helper half a minute later.
+   */
+  const armRestartBusyWatch = () => {
+    stopRestartBusyWatch()
+    restartBusyTimer = ctx.interval(() => {
+      if (disposed) return stopRestartBusyWatch()
+      const record = state.restartPhase
+      // Only a stage that still claims 'restarting' is watched: every other
+      // stage already says the truth.
+      if (!record || typeof record !== 'object' || record.phase !== 'restarting') {
+        return stopRestartBusyWatch()
+      }
+      if (!state.restart) return stopRestartBusyWatch()
+      let verdict
+      try {
+        verdict = gate()
+      } catch {
+        return undefined
+      }
+      if (verdict && verdict.allow === true) return undefined
+      log.warn('a conversation became active while the restart was being carried out; the stage goes back to waiting', {
+        reason: verdict ? verdict.reason : null,
+        blockedBy: verdict ? verdict.blockedBy : null,
+      })
+      deferRestartStage('conversation-active while restarting', {
+        blocked: verdict && Array.isArray(verdict.blockedBy) ? countBlockerTasks(verdict.blockedBy) : 0,
+      })
+      setPhase(state, 'deferred')
+      persist()
+      startPolling()
+      return stopRestartBusyWatch()
+    }, RESTART_BUSY_CHECK_MS)
+    return restartBusyTimer
+  }
+
+  const markRestartStage = (phase, { blocked = 0, now = Date.now(), reason = null, snapshotBytes } = {}) => {
     if (!RESTART_PHASES.includes(phase)) return null
-    const record = setRestartPhase(state, { phase, blocked, now })
+    const record = setRestartPhase(state, { phase, blocked, now, reason, snapshotBytes })
     persist()
     return record
   }
 
+  /**
+   * REMEMBER THE SNAPSHOT THIS REQUEST ALREADY TOOK.
+   *
+   * THE REPORT (user, 2026-10-30): the copy finished, a conversation postponed the
+   * restart, and the retry started copying the whole 205 MB again. The snapshot is
+   * the rollback point of THIS restart; it does not get stale because the restart
+   * had to wait. It is stored on the request, so withdrawing or carrying out the
+   * request throws it away by itself.
+   *
+   * @param {object} snapshot the value the snapshot entry returned
+   */
+  const rememberSnapshot = (snapshot) => {
+    if (!state.restart || typeof state.restart !== 'object') return
+    const backup = snapshot && typeof snapshot === 'object' && snapshot.backup && typeof snapshot.backup === 'object'
+      ? snapshot.backup
+      : null
+    if (!backup || backup.ok !== true || typeof backup.dir !== 'string' || backup.dir === '') return
+    const number = (value) => (Number.isFinite(value) ? Math.max(0, Math.trunc(value)) : 0)
+    state.restart.snapshot = {
+      // The request this copy belongs to: a different request must start over.
+      requestedAt: Number.isFinite(state.restart.requestedAt) ? state.restart.requestedAt : 0,
+      dir: backup.dir,
+      profileDir: typeof snapshot.profileDir === 'string' && snapshot.profileDir !== '' ? snapshot.profileDir : null,
+      files: number(backup.files),
+      bytes: number(backup.bytes),
+      total: number(backup.totalBytes) || number(backup.bytes),
+      at: Date.now(),
+    }
+    persist()
+    log.info('the pre-restart snapshot of this request is remembered; a retry reuses it', {
+      dir: backup.dir,
+      bytes: state.restart.snapshot.bytes,
+    })
+  }
+
+  /**
+   * THE SNAPSHOT THIS REQUEST ALREADY PAID FOR, if it is still usable.
+   *
+   * All three conditions must hold, or the restart copies again:
+   *   1. it belongs to THE SAME request (same `requestedAt`),
+   *   2. the backup directory is still there,
+   *   3. its manifest is readable and reports the size that was recorded — a
+   *      half-deleted or replaced directory never passes for a rollback point.
+   *
+   * @returns {object|null}
+   */
+  const reusableSnapshot = () => {
+    const request = state.restart
+    if (!request || typeof request !== 'object') return null
+    const saved = request.snapshot
+    if (!saved || typeof saved !== 'object') return null
+    if (!Number.isFinite(saved.requestedAt) || !Number.isFinite(request.requestedAt)) return null
+    if (saved.requestedAt !== request.requestedAt) return null
+    if (typeof saved.dir !== 'string' || saved.dir === '') return null
+    try {
+      if (!fs.existsSync(saved.dir)) return null
+      const manifest = readManifest(saved.dir)
+      if (!manifest || typeof manifest !== 'object') return null
+      if (Number.isFinite(manifest.bytes) && Number.isFinite(saved.bytes) && manifest.bytes !== saved.bytes) return null
+    } catch {
+      return null
+    }
+    return saved
+  }
+
+  /** The size this request's snapshot already has, for the stage record. */
+  const knownSnapshotBytes = () => {
+    const saved = state.restart && state.restart.snapshot
+    return saved && typeof saved === 'object' && Number.isFinite(saved.bytes) ? saved.bytes : null
+  }
+
+  /**
+   * Send the stage BACK TO WAITING — the one way a postponed restart is recorded.
+   *
+   * WHY (user report, 2026-10-29): a restart that had already written
+   * 'snapshotting' and was then postponed (a conversation became active again,
+   * the detached helper refused to kill this process, a retry was scheduled)
+   * left that stage on disk. The interface drew a card for a copy that had long
+   * finished, and the card never went away. Every deferral now goes through
+   * here, so the stage always says the truth: waiting.
+   *
+   * @param {string} reason why the restart was postponed
+   * @param {{ blocked?: number }} [options]
+   * @returns {object|null} the recorded stage
+   */
+  const deferRestartStage = (reason, { blocked = 0 } = {}) => {
+    const text = typeof reason === 'string' && reason !== '' ? 'deferred: ' + reason : 'deferred'
+    const count = Number.isFinite(blocked) ? blocked : 0
+    // A request that already took its snapshot keeps saying how big it is: the
+    // number is a fact of this restart and does not expire while it waits.
+    return markRestartStage('waiting', { blocked: count, reason: text, snapshotBytes: knownSnapshotBytes() })
+  }
+
   /**
    * Record the REAL progress of the running snapshot (files and bytes).
    *
@@ -2717,6 +3002,9 @@ const titleOfSummary = (item) => {
       // The measured size of the pre-restart snapshot: it survives the stage
       // change, so a page that missed the copy can still report it.
       snapshotBytes: record && typeof record === 'object' ? record.snapshotBytes : null,
+      // WHY the stage is what it is ("deferred: conversation-active", "snapshot
+      // done", …), so a postponed restart can be told from a running one.
+      reason: record && typeof record === 'object' ? record.reason : null,
       now: Date.now(),
     })
   }
@@ -2840,11 +3128,17 @@ const titleOfSummary = (item) => {
    * 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.
    *
+   * WHAT EACH COPY IS travels with it (user decision, 2026-10-30): only a copy
+   * a boot has proven is a rollback target (`known-good`), the snapshot of a
+   * restart is not (`snapshot`), and a copy without an identity file was never
+   * proven (`unknown`). The browser cannot read `meta.json`, so the identity is
+   * resolved HERE and handed to the interface with the numbers.
+   *
    * @returns {{ dir: string, max: number, count: number, items: Array<object> }}
    */
   const backupsInfo = () => {
     const dir = backupsDirFor(stateDirOf())
-    const items = listBackups(dir).map((item) => ({
+    const items = listBackupIdentities(dir).map((item) => ({
       name: item.name,
       dir: item.dir,
       at: item.at,
@@ -2852,6 +3146,10 @@ const titleOfSummary = (item) => {
       bytes: item.bytes,
       files: item.files,
       includePlugins: item.includePlugins,
+      // 'known-good' | 'snapshot' | 'unknown' — never a guess: it is the
+      // identity the copy itself carries.
+      kind: item.kind,
+      version: item.version,
     }))
     return {
       dir,
@@ -2861,6 +3159,149 @@ const titleOfSummary = (item) => {
     }
   }
 
+  /** The receipt of the last manual rollback, next to the checkpoint. */
+  const MANUAL_ROLLBACK_RECEIPT = 'last-manual-rollback.json'
+
+  /**
+   * RESTORE ONE BACKUP THE USER PICKED (user decision, 2026-10-30).
+   *
+   * The automatic rollback only ever restores the newest PROVEN copy — but the
+   * user may know better ("the version from last week worked"). So they may pick
+   * any copy in the list, and the plugin restores exactly that one. Three rules
+   * keep that safe:
+   *
+   *   1. THE INPUT IS A NAME, NOT A PATH. It has to match a name this host
+   *      reports from `listBackupIdentities()`, so `../`, a drive letter or any
+   *      separator is refused before anything is read — a traversal never even
+   *      becomes a lookup.
+   *   2. THE CURRENT STATE IS SAVED FIRST. A snapshot of the profile as it is
+   *      right now is written before anything is overwritten, so a manual
+   *      rollback is itself undoable. Without that snapshot nothing is restored.
+   *   3. THE RESTART IS THE NORMAL ONE. The plugin never kills the host itself:
+   *      it writes the receipt and requests a restart, exactly like the pill.
+   *
+   * @param {{ name?: string }} [request]
+   * @returns {Promise<{ ok: boolean, status: number, error?: string|null, receipt?: object }>}
+   */
+  const manualRollback = async ({ name } = {}) => {
+    const requested = typeof name === 'string' ? name.trim() : ''
+    if (requested === '') {
+      return { ok: false, status: 400, error: 'a backup name is required' }
+    }
+    // ① A PLAIN NAME, on purpose: the list is the allow-list.
+    if (
+      requested.includes('/')
+      || requested.includes('\\')
+      || requested.includes('..')
+      || path.isAbsolute(requested)
+      || requested !== path.basename(requested)
+    ) {
+      log.warn('the manual rollback was refused: the name is not a plain backup name:', requested)
+      return { ok: false, status: 400, error: 'the name is not a backup name' }
+    }
+    const backupsDir = backupsDirFor(stateDirOf())
+    const target = listBackupIdentities(backupsDir).find((entry) => entry.name === requested)
+    if (!target || typeof target.dir !== 'string' || target.dir === '') {
+      log.warn('the manual rollback was refused: there is no such backup:', requested)
+      return { ok: false, status: 404, error: 'there is no such backup' }
+    }
+    const profile = resolveProfileDirDetailed()
+    const profileDir = typeof profile.dir === 'string' ? profile.dir : ''
+    if (profileDir === '') {
+      log.warn('the manual rollback was refused: the profile directory is unknown')
+      return { ok: false, status: 409, error: 'the profile directory is unknown' }
+    }
+    // ② THE WAY BACK, taken first. A manual rollback that cannot save the
+    // current state is not offered at all.
+    let safety = null
+    try {
+      safety = await createBackup({
+        profileDir,
+        backupsDir,
+        includePlugins: config.backupIncludePlugins !== false,
+        maxBackups: config.maxBackups,
+        kind: KIND_SNAPSHOT,
+        reason: 'before-manual-rollback',
+        version: ownVersion(),
+        bootId,
+      })
+    } catch (error) {
+      safety = { ok: false, error: String(error) }
+    }
+    if (!safety || safety.ok !== true) {
+      const reason = safety && safety.error ? safety.error : 'unknown error'
+      log.error('the manual rollback was refused: the current state could not be saved first:', reason)
+      return { ok: false, status: 409, error: 'the current state could not be saved first: ' + reason }
+    }
+    // ONE restore at a time: the detached watchdog takes the same lock.
+    const lock = claimRollbackLock(stateDirOf())
+    if (!lock.ok) {
+      log.warn('the manual rollback stands down: another rollback is already running:', lock.error)
+      return { ok: false, status: 409, error: 'another rollback is already running' }
+    }
+    let restored = null
+    try {
+      // ③ THE COPY THE USER PICKED — not the newest, not the proven one.
+      restored = restoreBackup({ backupDir: target.dir, profileDir })
+    } catch (error) {
+      restored = { ok: false, restored: [], error: String(error) }
+    } finally {
+      releaseRollbackLock(stateDirOf())
+    }
+    const ok = Boolean(restored && restored.ok === true)
+    const receipt = {
+      at: new Date().toISOString(),
+      name: target.name,
+      dir: target.dir,
+      kind: target.kind,
+      version: target.version ?? null,
+      restored: restored && Array.isArray(restored.restored) ? restored.restored : [],
+      ok,
+      error: ok ? null : ((restored && restored.error) || 'the restore failed'),
+      // The copy taken right before the restore: the manual rollback can be
+      // undone with it, even if the picked one was older than the hardware.
+      safetySnapshot: typeof safety.dir === 'string' ? safety.dir : null,
+      restartRequested: false,
+    }
+    const writeReceipt = () => {
+      try {
+        fs.writeFileSync(
+          path.join(stateDirOf(), MANUAL_ROLLBACK_RECEIPT),
+          JSON.stringify(receipt, null, 2),
+          'utf8',
+        )
+      } catch (error) {
+        log.warn('could not write the manual rollback receipt:', String(error))
+      }
+    }
+    // ④ THE RECEIPT, before anything else happens: the next boot reads it.
+    writeReceipt()
+    if (!ok) {
+      log.error('the manual rollback could not restore the copy:', receipt.error)
+      return { ok: false, status: 500, error: receipt.error, receipt }
+    }
+    // ⑤ A NORMAL RESTART (the same request the pill makes). The plugin does not
+    // kill anything itself; the restored profile is what comes back up.
+    requestRestart(state, {
+      reason: 'manual rollback to ' + target.name,
+      bySessionId: 'settings',
+      resume: false,
+      now: Date.now(),
+    })
+    markRestartStage('waiting')
+    persist()
+    startPolling()
+    receipt.restartRequested = true
+    writeReceipt()
+    log.warn('the manual rollback was done; a restart was requested', {
+      name: target.name,
+      kind: target.kind,
+      restored: receipt.restored,
+      safetySnapshot: receipt.safetySnapshot,
+    })
+    return { ok: true, status: 200, receipt }
+  }
+
   /**
    * WHERE THE RESCUE SCRIPTS ARE.
    *
@@ -3489,10 +3930,15 @@ const titleOfSummary = (item) => {
    */
   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' }
+    // ONLY a backup that a boot has already proven may be rolled back to. The
+    // snapshot taken right before THIS restart may be the broken state itself
+    // (the user edited a plugin and then restarted), so it is never the target.
+    const knownGood = latestKnownGood(backupsDirFor(stateDirOf()))
+    const targetDir = knownGood && typeof knownGood.dir === 'string' ? knownGood.dir : ''
+    if (targetDir === '') {
+      log.error('the restart failed and there is no known-good backup to roll back to:', reason)
+      writeRestartReport({ rolledBack: false, reason: 'no-known-good: ' + reason, backupDir: null, restored })
+      return { rolledBack: false, restored, error: 'no-known-good' }
     }
     if (typeof profileDir !== 'string' || profileDir === '') {
       log.error('the restart failed and the profile directory is unknown:', reason)
@@ -3509,24 +3955,24 @@ const titleOfSummary = (item) => {
     }
     let result = null
     try {
-      result = restoreBackup({ backupDir: backup.dir, profileDir })
+      result = restoreBackup({ backupDir: targetDir, 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:', {
+      log.warn('the known-good backup was restored:', {
         reason,
         restored: result.restored,
-        backupDir: backup.dir,
+        backupDir: targetDir,
       })
-      writeRestartReport({ rolledBack: true, reason, backupDir: backup.dir, restored: result.restored })
+      writeRestartReport({ rolledBack: true, reason, backupDir: targetDir, 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 })
+    log.error('the known-good backup could not be restored:', reason, error)
+    writeRestartReport({ rolledBack: false, reason, backupDir: targetDir, restored })
     return { rolledBack: false, restored, error }
   }
 
@@ -3542,9 +3988,13 @@ const titleOfSummary = (item) => {
    * @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 }
+    // The watcher must restore a state a boot has already proven. The snapshot
+    // of the restart it is guarding may be the broken state itself.
+    const knownGood = latestKnownGood(backupsDirFor(stateDirOf()))
+    const targetDir = knownGood && typeof knownGood.dir === 'string' ? knownGood.dir : ''
+    if (targetDir === '') {
+      log.warn('no known-good backup: the automatic rollback is not armed')
+      return { ok: false, method: 'none', error: 'no-known-good', scriptPath: null }
     }
     if (typeof profileDir !== 'string' || profileDir === '') {
       log.warn('the profile directory is unknown: the automatic rollback is not armed')
@@ -3561,7 +4011,7 @@ const titleOfSummary = (item) => {
       portFile: accessFilePath(stateDir),
       expectedBootId: bootId,
       outcomeFile: path.join(stateDir, RESTART_OUTCOME_FILE),
-      backupDir: backup.dir,
+      backupDir: targetDir,
       profileDir,
       reportPath: path.join(stateDir, ROLLBACK_REPORT_NAME),
       lockFile: path.join(stateDir, ROLLBACK_LOCK_NAME),
@@ -3648,6 +4098,11 @@ const titleOfSummary = (item) => {
         blockedBy: verdict.blockedBy,
         quietForMs: verdict.quietForMs,
       })
+      // Postponed BEFORE the copy: the stage goes back to waiting (with the
+      // reason and a fresh timestamp), so no card survives the deferral.
+      deferRestartStage(verdict.reason || 'conversation-active', {
+        blocked: countBlockerTasks(verdict.blockedBy),
+      })
       persist()
       startPolling()
       return
@@ -3681,29 +4136,60 @@ const titleOfSummary = (item) => {
       // and now they say so.
       const stateDir = path.dirname(stateFile)
       resetSnapshotCancel()
-      markRestartStage('snapshotting')
+      // HAS THIS REQUEST ALREADY PAID FOR ITS SNAPSHOT? (user report, 2026-10-30:
+      // the copy finished, a conversation postponed the restart, and the retry
+      // copied all 205 MB again.) Then it is reused as it is: same request, same
+      // directory, same manifest.
+      const paid = reusableSnapshot()
       let cancelled = false
-      let snapshot
-      try {
-        snapshot = await snapshotFn({
-          config,
-          stateDir,
-          log,
-          profile: resolveProfileDirDetailed(),
-          onProgress: (progress) => {
-            recordSnapshotProgress(progress)
-          },
-          shouldCancel: () => snapshotCancelled(),
+      let snapshot = null
+      if (paid !== null) {
+        log.warn('reusing the snapshot this restart already took; not copying the profile again', {
+          dir: paid.dir,
+          bytes: paid.bytes,
         })
-      } finally {
-        // The flag belongs to ONE snapshot; a stale `true` would cancel the
-        // next restart before it began.
-        const wasCancelled = snapshotCancelled()
-        resetSnapshotCancel()
-        // Two ways a copy can be called off: the flag this process set (the
-        // cancel route) or the snapshot reporting it itself. Both mean the same
-        // thing, and both must stop the restart.
-        cancelled = wasCancelled || (snapshot !== null && typeof snapshot === 'object' && snapshot.cancelled === true)
+        snapshot = {
+          backup: {
+            ok: true,
+            dir: paid.dir,
+            bytes: paid.bytes,
+            totalBytes: paid.total,
+            fileCount: paid.files,
+            reused: true,
+          },
+          profileDir: paid.profileDir,
+          profile: { dir: paid.profileDir, source: 'reused' },
+          requested: true,
+          durationMs: 0,
+          error: null,
+          reused: true,
+        }
+      } else {
+        markRestartStage('snapshotting')
+        try {
+          snapshot = await snapshotFn({
+            config,
+            stateDir,
+            log,
+            profile: resolveProfileDirDetailed(),
+            onProgress: (progress) => {
+              recordSnapshotProgress(progress)
+            },
+            shouldCancel: () => snapshotCancelled(),
+          })
+        } finally {
+          // The flag belongs to ONE snapshot; a stale `true` would cancel the
+          // next restart before it began.
+          const wasCancelled = snapshotCancelled()
+          resetSnapshotCancel()
+          // Two ways a copy can be called off: the flag this process set (the
+          // cancel route) or the snapshot reporting it itself. Both mean the same
+          // thing, and both must stop the restart.
+          cancelled = wasCancelled || (snapshot !== null && typeof snapshot === 'object' && snapshot.cancelled === true)
+        }
+        // Remember it: if this restart is postponed now, the retry must not copy
+        // the profile a second time.
+        if (!cancelled) rememberSnapshot(snapshot)
       }
       if (cancelled) {
         // The user called it off while the files were being copied: the
@@ -3718,6 +4204,34 @@ const titleOfSummary = (item) => {
         stopPolling()
         return
       }
+      // A COPY THAT IS DONE IS NOT A RESTART YET (user report, 2026-10-30): "the
+      // backup finished, and then the card said 正在重启 for 25 s while nothing was
+      // restarting". The gate is re-checked HERE, in the same tick, so a
+      // conversation that started during the copy postpones the restart at once
+      // instead of being discovered by the helper half a minute later.
+      const afterCopy = gate()
+      if (!afterCopy || afterCopy.allow !== true) {
+        const why = afterCopy && typeof afterCopy.reason === 'string' && afterCopy.reason !== ''
+          ? afterCopy.reason
+          : 'conversation-active'
+        log.info('restart deferred right after the snapshot: a conversation is active again', {
+          reason: why,
+          blockedBy: afterCopy ? afterCopy.blockedBy : null,
+        })
+        deferRestartStage('conversation-active after snapshot: ' + why, {
+          blocked: afterCopy && Array.isArray(afterCopy.blockedBy) ? countBlockerTasks(afterCopy.blockedBy) : 0,
+        })
+        setPhase(state, 'deferred')
+        persist()
+        startPolling()
+        return
+      }
+      // THE INVARIANT (user report, 2026-10-29): 'snapshotting' exists ONLY while
+      // files are being copied. The moment the copy returns — copied, cancelled
+      // or thrown — the stage leaves it. Everything after this point (arming the
+      // watchdog, the supervisor hand-off, the command) is "the restart is being
+      // executed", and a deferral from here on goes back to 'waiting'.
+      markRestartStage('restarting', { reason: 'snapshot done' })
       // 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
@@ -3730,9 +4244,14 @@ const titleOfSummary = (item) => {
       // old one (v1) is NOT started next to it — they take the same lock, and
       // the one that loses it gives up. If v2 lost, the profile would be
       // restored but nothing would be running any more.
-      const watchdogArm = backup && backup.ok === true && profileDir !== null
+      // The watchdog restores a state a boot has already proven, NOT the
+      // snapshot of this restart (which may be the broken state itself).
+      const knownGoodForWatchdog = backup && backup.ok === true && profileDir !== null
+        ? latestKnownGood(backupsDirFor(stateDirOf()))
+        : null
+      const watchdogArm = knownGoodForWatchdog && typeof knownGoodForWatchdog.dir === 'string' && profileDir !== null
         ? armWatchdogFn({
-          snapshotDir: backup.dir,
+          snapshotDir: knownGoodForWatchdog.dir,
           profileDir,
           relaunchCommand: useCustomCommand && typeof config.restartCommand === 'string' && config.restartCommand.trim() !== ''
             ? {
@@ -3852,6 +4371,10 @@ const titleOfSummary = (item) => {
           // FROM HERE ON THE RESTART CANNOT BE CANCELLED, and the interface says
           // so: the host is on its way out.
           markRestartStage('restarting')
+          // A command that takes a while must not keep claiming "restarting" once
+          // a conversation is active again (the reason is remembered and the card
+          // turns into "restart postponed").
+          armRestartBusyWatch()
           const outcome = await runCommandFn({
             command,
             timeoutMs: config.restartCommandTimeoutMs,
@@ -3891,6 +4414,13 @@ const titleOfSummary = (item) => {
           })
           if (confirmed && confirmed.ok === true) {
             log.warn('the new instance answered its health route:', confirmed)
+            // THE SNAPSHOT HAS PROVEN ITSELF: this restart came up, so the copy
+            // taken before it is the one a failed boot may be rolled back to
+            // (user decision, 2026-10-30).
+            if (backup && typeof backup.dir === 'string' && backup.dir !== '') {
+              const promoted = markKnownGood(backup.dir, { reason: 'boot-ok' })
+              log.info('the snapshot of this restart is now known-good', { dir: backup.dir, promoted })
+            }
             writeRestartOutcome({ decided: true, ok: true, reason: 'the new instance answered' })
             recordRestartVerdict({
               result: RESTART_RESULTS.OK,
@@ -3990,12 +4520,16 @@ const titleOfSummary = (item) => {
         })
         log.warn('scheduled detached restart:', result)
         if (!result || result.ok !== true) {
-          markRestartStage('waiting', { blocked: 0 })
+          deferRestartStage((result && result.error) || 'detached restart refused')
           rollbackRestart((result && result.error) || 'detached restart refused')
         } else {
           // The helper is scheduled: the host is going down, and from here on a
           // cancel would be a promise this plugin cannot keep.
           markRestartStage('restarting')
+          // THE 25-SECOND LIE (user report, 2026-10-30): the helper waits for its
+          // own idle re-check, so this is exactly the window in which a
+          // conversation can start. Watch it every 350 ms.
+          armRestartBusyWatch()
           armGateWatchdog()
         }
       }
@@ -4367,6 +4901,34 @@ const titleOfSummary = (item) => {
     // single description (text included) that the state route, the health route
     // and the settings page share.
     markRestartStage,
+    /**
+     * Reset a stage that cannot be true in THIS process (boot / plugin reload).
+     *
+     * WHY (user report, 2026-10-29): the stage lives in the checkpoint, so a
+     * 'snapshotting' or 'restarting' written by an earlier attempt can be read
+     * back by a process in which nothing is being copied and nothing is going
+     * down. The interface would then draw a card for an action that is not
+     * happening — the card that never went away. A stage that describes an
+     * action must not outlive the process that performed it.
+     *
+     * @param {string} reason why it is being reset ("boot", "plugin reload", …)
+     * @returns {object|null} the recorded stage, or null when nothing was stale
+     */
+    resetStaleStage(reason) {
+      const record = state.restartPhase
+      const phase = record && typeof record === 'object' ? record.phase : null
+      if (phase !== 'snapshotting' && phase !== 'restarting') return null
+      let blocked = 0
+      try {
+        blocked = countBlockerTasks(gate().blockedBy)
+      } catch {
+        blocked = 0
+      }
+      return markRestartStage('waiting', {
+        blocked,
+        reason: reason ? 'boot: ' + reason : 'boot',
+      })
+    },
     recordSnapshotProgress,
     clearRestartStage,
     restartStageInfo,
@@ -4389,6 +4951,8 @@ const titleOfSummary = (item) => {
         blocking: info.blocking,
         // The size of the pre-restart snapshot, on every stage (bytes).
         snapshotBytes: info.snapshotBytes,
+        // Why this stage ("deferred: …" = the restart went back to waiting).
+        reason: info.reason,
         progress: info.progress === null
           ? null
           : { files: info.progress.files, bytes: info.progress.bytes, total: info.progress.total, percent: info.progress.percent, ageMs: info.progress.ageMs },
@@ -4467,6 +5031,10 @@ const titleOfSummary = (item) => {
      * WHAT IS ON DISK RIGHT NOW: the backups of this host.
      */
     backupsInfo,
+    // RESTORE ONE COPY THE USER PICKED (they may know better than "the newest
+    // proven one"): save the current state, restore the picked copy, request a
+    // normal restart.
+    manualRollback,
     // Where the rescue scripts are, and whether the desktop shortcut exists.
     rescueKitInfo,
     // What this machine can do: can it create a one-off scheduled task? (The
@@ -4660,6 +5228,7 @@ const titleOfSummary = (item) => {
     flushSessions,
     releaseRequesters,
     markDisposed: () => {
+    stopRestartBusyWatch()
       disposed = true
     },
     noteActivity,
@@ -5349,6 +5918,16 @@ export async function verifyRestartBoot(runtime, options = {}) {
   if (record !== null) {
     if (evaluated.ok) {
       log.warn('the new instance verified itself:', { durationMs: record.durationMs, checks })
+      // THIS SNAPSHOT HAS NOW PROVEN IT BOOTS: the restart it belongs to came
+      // up, so it is the copy a failed boot may be rolled back to (user
+      // decision, 2026-10-30). A FAILED boot never promotes anything.
+      const snapshotDir = pending && pending.snapshot && typeof pending.snapshot.dir === 'string'
+        ? pending.snapshot.dir
+        : ''
+      if (snapshotDir !== '') {
+        const promoted = markKnownGood(snapshotDir, { reason: 'boot-ok' })
+        log.info('the snapshot of this restart is now known-good', { dir: snapshotDir, promoted })
+      }
     } else {
       log.error('the new instance did NOT come up cleanly:', {
         durationMs: record.durationMs,
@@ -6714,6 +7293,70 @@ function buildHandoffRoute(ctx, runtime, config) {
   }
 }
 
+/**
+ * Build the POST `/rollback-to` route: restore ONE backup the user picked.
+ *
+ * It sits next to the health route and uses the same authentication rule
+ * (loopback OR a request the connection service admits). Body:
+ * `{ "name": "<backup directory name>" }`. The name has to be one this host
+ * reports from the backup list — the route never takes a path, so `../` and
+ * absolute paths are refused before anything is read. The answer carries the
+ * receipt (what was restored, and the snapshot taken right before it):
+ *
+ *   - 400 when no name / not a plain backup name was given,
+ *   - 404 when there is no such backup,
+ *   - 409 when the current state could not be saved first, or when another
+ *     rollback (the detached watchdog) holds the lock,
+ *   - 500 when the restore itself failed,
+ *   - 200 with `{ ok: true, receipt }` when the copy is back AND a normal
+ *     restart has been requested.
+ */
+function buildManualRollbackRoute(ctx, runtime, config) {
+  const routePath = resolveManualRollbackPath(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 result = await runtime.manualRollback({ name: body.name })
+        const status = result && Number.isFinite(result.status) ? result.status : 400
+        res.statusCode = status
+        res.setHeader('content-type', 'application/json; charset=utf-8')
+        res.setHeader('cache-control', 'no-store')
+        res.end(JSON.stringify({
+          ok: result ? result.ok === true : false,
+          error: result && result.error ? result.error : null,
+          receipt: result && result.receipt ? result.receipt : null,
+          restartRequested: Boolean(result && result.receipt && result.receipt.restartRequested),
+        }))
+      }).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 announcements route: the one-time announcement of a new feature.
  *
@@ -7936,6 +8579,10 @@ function registerHealthRoute(ctx, runtime, config, sleep) {
             // The copy progress on its own as well, so a client that only wants
             // the numbers does not have to walk the stage object.
             progress: stage.progress,
+            // THE FIRST SAFE COPY: what happened when this machine looked for a
+            // known-good backup and found none (user decision, 2026-10-30).
+            // Absent when nothing was ever tried, so an old client sees no change.
+            ...(live.firstInstallBackup ? { firstInstallBackup: live.firstInstallBackup } : {}),
             updatedAt: live.updatedAt,
             // The park route, so the client never has to guess the prefix, and
             // the goals this plugin already disarmed (they are re-armed after
@@ -7945,6 +8592,9 @@ function registerHealthRoute(ctx, runtime, config, sleep) {
             // The route that withdraws ONE session's own restart request (the
             // manual "cancel my restart" of the pill).
             cancelUrl: resolveCancelPath(config),
+            // THE ROUTE OF THE MANUAL ROLLBACK: POST a backup NAME and this
+            // host saves the current state, restores that copy and restarts.
+            rollbackUrl: resolveManualRollbackPath(config),
             // The route that persists the one-time install choice, plus the
             // value that is effective right now.
             choiceUrl: resolveChoicePath(config),
@@ -8042,6 +8692,9 @@ function registerHealthRoute(ctx, runtime, config, sleep) {
             parkUrl: resolveParkPath(config),
             recoverUrl: resolveRecoverPath(config),
             cancelUrl: resolveCancelPath(config),
+            // THE ROUTE OF THE MANUAL ROLLBACK: POST a backup NAME and this
+            // host saves the current state, restores that copy and restarts.
+            rollbackUrl: resolveManualRollbackPath(config),
             choiceUrl: resolveChoicePath(config),
             announcementsUrl: resolveAnnouncementsPath(config),
             backupOnRestart: config.backupOnRestart !== false,
@@ -8133,6 +8786,10 @@ function registerHealthRoute(ctx, runtime, config, sleep) {
         // out there; it must be visible from outside the process, not only in
         // a log line nobody reads.
         watchdog: summarizeDisarm(runtime.watchdogDisarm),
+        // THE FIRST SAFE COPY: what happened when this machine looked for a
+        // known-good backup and found none (user decision, 2026-10-30). Absent
+        // when nothing was ever tried.
+        ...(state.firstInstallBackup ? { firstInstallBackup: state.firstInstallBackup } : {}),
         // THE RESTART STAGE, read from the health route as well: a script (or a
         // user watching the console) can tell "waiting" from "backing up 120 MB
         // of 156 MB" without opening the interface.
@@ -8171,6 +8828,7 @@ function registerHealthRoute(ctx, runtime, config, sleep) {
     const handoffRoute = buildHandoffRoute(ctx, runtime, config)
     const choiceRoute = buildChoiceRoute(ctx, runtime, config)
     const cancelRoute = buildCancelRoute(ctx, runtime, config)
+    const manualRollbackRoute = buildManualRollbackRoute(ctx, runtime, config)
     const announcementsRoute = buildAnnouncementsRoute(ctx, runtime, config)
     const supervisorRoute = buildSupervisorRoute(ctx, runtime, config)
     const rescueRoute = buildRescueRoute(ctx, runtime, config)
@@ -8197,6 +8855,7 @@ function registerHealthRoute(ctx, runtime, config, sleep) {
       { name: 'handoff', route: handoffRoute },
       { name: 'choice', route: choiceRoute },
       { name: 'cancel', route: cancelRoute },
+      { name: 'manual-rollback', route: manualRollbackRoute },
       { name: 'announcements', route: announcementsRoute },
       { name: 'supervisor', route: supervisorRoute },
       { name: 'rescue', route: rescueRoute },
@@ -8418,7 +9077,23 @@ export function apply(ctx, rawConfig, options = {}) {
   // says "back — carrying on". Written here (not after the recovery) so a boot
   // that finds nothing to resume still shows the end of the story instead of a
   // spinner left over from the old process.
-  if (runtime.isNewBoot) runtime.markRestartStage('back')
+  if (runtime.isNewBoot) {
+    runtime.markRestartStage('back')
+  } else {
+    // The SAME process is loading the plugin again: a stage left on disk by an
+    // earlier attempt ('snapshotting' / 'restarting') describes an action that is
+    // not running in this process, so it is reset instead of being inherited
+    // (user report, 2026-10-29: a card that never went away).
+    runtime.resetStaleStage('plugin reload')
+  }
+
+  // THE FIRST SAFE COPY (user decision, 2026-10-30): a machine that has never
+  // restarted has nothing a failed boot could roll back to, so a NEW host
+  // process seeds one known-good copy. A reload seeds nothing, and the seed is
+  // fire-and-forget: the boot path never waits for a 117 MB copy.
+  void seedFirstInstallBackup(runtime, config).catch((error) => {
+    log.warn('the first-install safe copy failed:', String(error))
+  })
 
   trackAgents(ctx, runtime, config)
 
@@ -8496,6 +9171,11 @@ export function apply(ctx, rawConfig, options = {}) {
     sleep.controller.dispose()
     persistSafely(runtime)
   }, 'dsh-autorestart lifecycle')
+
+  // The runtime is handed back so a test can look at — and drive — the very
+  // object the routes use (the cancel route is decided by ITS stage). Nothing in
+  // the plugin system reads this value.
+  return runtime
 }
 
 export {