dsh-autorestart 0.8.0 → 0.8.2

package/index.js

@@ -49,9 +49,17 @@ import {
   setHandoff,
   setRecoveryOutcome,
   setPhase,
+  setRestartPhase,
+  setRestartProgress,
+  clearRestartPhase,
   stampResumedGoal,
   writeState,
 } from './lib/checkpoint.js'
+import {
+  cancelRefusalReason,
+  describeRestartPhase,
+  RESTART_PHASES,
+} from './lib/restart-phase.js'
 import {
   bootPlan,
   composeHandoff,
@@ -117,13 +125,18 @@ import {
 } from './lib/watchdog-tier.js'
 import {
   buildPending,
+  clearPending,
   clearReady,
-  readReady,
+  readPending,
   readReport,
   writePending,
-  writeReady,
   writeReport,
 } from './lib/watchdog.js'
+import {
+  disarmWatchdog as runDisarmWatchdog,
+  markReady,
+  readDisarmRecord,
+} from './lib/watchdog-disarm.js'
 import {
   ARBITERS,
   planWatchdogArbiter,
@@ -374,7 +387,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.0'
+const PLUGIN_VERSION_FALLBACK = '0.8.2'
 
 /**
  * The version of the graceful-shutdown FEATURE, not the version of the package.
@@ -1398,12 +1411,16 @@ function backupsDirFor(dir) {
  *   error: string|null,
  * }}
  */
-export function takePreRestartSnapshot({
+export async function takePreRestartSnapshot({
   config = {},
   stateDir = '',
   log = console,
   profile = null,
   createBackup: createBackupFn = createBackup,
+  // The REAL progress of the copy, and the way out of it: both are handed to
+  // the backup itself, so the numbers on screen are the numbers on disk.
+  onProgress = null,
+  shouldCancel = null,
 } = {}) {
   const startedAt = Date.now()
   const info = profile && typeof profile === 'object'
@@ -1427,17 +1444,33 @@ export function takePreRestartSnapshot({
   }
   let backup = null
   try {
-    backup = createBackupFn({
+    backup = await createBackupFn({
       profileDir,
       backupsDir: backupsDirFor(stateDir),
       includePlugins: config.backupIncludePlugins !== false,
       maxBackups: config.maxBackups,
+      onProgress: typeof onProgress === 'function' ? onProgress : null,
+      shouldCancel: typeof shouldCancel === 'function' ? shouldCancel : null,
     })
   } catch (error) {
     // 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.cancelled === true) {
+    // The user called it off: the half-written snapshot was already removed by
+    // the copy loop, and there is nothing to report as a rollback point.
+    log.warn('the pre-restart backup was cancelled by the user', { durationMs })
+    return {
+      backup,
+      profileDir,
+      profile: info,
+      requested: true,
+      durationMs,
+      cancelled: true,
+      error: null,
+    }
+  }
   if (backup && backup.ok === true) {
     log.warn('pre-restart backup written', {
       dir: backup.dir,
@@ -1645,6 +1678,17 @@ export function createRuntime(ctx, config, options = {}) {
   let recoverTimer
   let disposed = false
   let lastPersistError
+  /**
+   * THE LAST DISARM of the watchdog: the record of "the host is up, so nothing
+   * may roll it back" (see lib/watchdog-disarm.js). It is kept on `runtime` so
+   * the settings page and the diagnostics can show a FAILED disarm instead of
+   * the silence that caused the 0.8.2 incident.
+   */
+  let watchdogDisarm = readDisarmRecord(path.dirname(stateFile))
+  /** The disarm that is currently running (one at a time; null when idle). */
+  let disarmInFlight = null
+  /** A disarm was asked for while one was running: run once more afterwards. */
+  let disarmPendingAgain = false
   /**
    * The tool registrations that failed. A failed registration is recorded and
    * logged, never thrown: the plugin still loads and the other tools still work.
@@ -2605,6 +2649,93 @@ const titleOfSummary = (item) => {
    */
   const stateDirOf = () => path.dirname(stateFile)
 
+  /**
+   * THE STAGE LINE of a restart ("waiting / backing up / restarting / back").
+   *
+   * It is written ONCE per stage change and persisted IMMEDIATELY, because the
+   * whole point of it is the first second after the click: a stage that reaches
+   * the interface only after the 156 MB snapshot would tell the user nothing
+   * about the ten seconds they spent wondering whether the button worked.
+   *
+   * @param {string} phase one of RESTART_PHASES
+   * @param {{ blocked?: number, now?: number }} [options]
+   * @returns {object|null} the recorded stage
+   */
+  const markRestartStage = (phase, { blocked = 0, now = Date.now() } = {}) => {
+    if (!RESTART_PHASES.includes(phase)) return null
+    const record = setRestartPhase(state, { phase, blocked, now })
+    persist()
+    return record
+  }
+
+  /**
+   * Record the REAL progress of the running snapshot (files and bytes).
+   *
+   * The copy loop calls this between files; the checkpoint is written with a
+   * small throttle, because a state write per copied file would slow the copy
+   * down for no gain. The in-memory record is always current, so a `state=1`
+   * poll that arrives between two writes still sees the newest numbers.
+   *
+   * @param {{ files?: number, bytes?: number, total?: number, filesTotal?: number, now?: number }} progress
+   */
+  let lastProgressPersist = 0
+  const recordSnapshotProgress = (progress) => {
+    const now = Date.now()
+    const record = setRestartProgress(state, { ...progress, now })
+    if (now - lastProgressPersist >= 250) {
+      lastProgressPersist = now
+      persist()
+    }
+    return record
+  }
+
+  /** Forget the stage (cancel, or a restart that could not be started). */
+  const clearRestartStage = () => {
+    if (clearRestartPhase(state)) persist()
+  }
+
+  /**
+   * The stage as every surface shows it (state route, health route, client).
+   *
+   * @returns {object} the described stage (always an object, never null)
+   */
+  const restartStageInfo = () => {
+    const record = state.restartPhase
+    const blocked = (() => {
+      try {
+        return countBlockerTasks(gate().blockedBy)
+      } catch {
+        return 0
+      }
+    })()
+    return describeRestartPhase({
+      phase: record && typeof record === 'object' ? record.phase : 'idle',
+      startedAt: record && typeof record === 'object' ? record.startedAt : null,
+      at: record && typeof record === 'object' ? record.at : null,
+      progress: record && typeof record === 'object' ? record.progress : null,
+      blocking: record && typeof record === 'object' && Number.isFinite(record.blocked) ? record.blocked : blocked,
+      now: Date.now(),
+    })
+  }
+
+  /**
+   * A cancel request that arrived while the snapshot was being written.
+   *
+   * The backup loop asks this between files: the copy stops, its half-written
+   * directory is removed, and the host never restarts. A flag (not a thrown
+   * error) because the loop is synchronous and must finish its bookkeeping.
+   */
+  let snapshotCancelRequested = false
+  const requestSnapshotCancel = () => {
+    snapshotCancelRequested = true
+    return true
+  }
+  const snapshotCancelled = () => snapshotCancelRequested === true
+  const resetSnapshotCancel = () => {
+    snapshotCancelRequested = false
+  }
+
+
   /**
    * The durable record of the last restart: the snapshot that was taken, the
    * verdict of the new instance and its four boot checks.
@@ -2616,17 +2747,14 @@ const titleOfSummary = (item) => {
   /**
    * The version of THIS plugin (the one the user runs).
    *
+   * It delegates to the module-level reader ON PURPOSE: a local copy used to
+   * look for `../package.json`, which is one directory ABOVE the plugin, so
+   * every answer was `unknown` — and the health route reported that instead of
+   * the version that is really loaded.
+   *
    * @returns {string}
    */
-  const pluginVersion = () => {
-    try {
-      const raw = fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')
-      const parsed = JSON.parse(raw)
-      return typeof parsed.version === 'string' && parsed.version !== '' ? parsed.version : 'unknown'
-    } catch {
-      return 'unknown'
-    }
-  }
+  const ownVersion = () => pluginVersion()
 
   /**
    * Write (or update) the durable record of the restart.
@@ -2960,7 +3088,7 @@ const titleOfSummary = (item) => {
    * @returns {string}
    */
   const diagnosticsText = () => buildDiagnostics({
-    version: pluginVersion(),
+    version: ownVersion(),
     platform: env.platform,
     hostKind: hostKindOf().kind,
     isDesktopApp: env.isDesktopApp === true,
@@ -2970,6 +3098,9 @@ const titleOfSummary = (item) => {
     lastRestart: lastRestartVerdict(),
     stateDir: stateDirOf(),
     watchdog: watchdogInfo(),
+    // DID THE DISARM WORK? A failed disarm leaves an armed watchdog behind,
+    // and that is the first thing a bug report has to show.
+    watchdogDisarm: summarizeDisarm(watchdogDisarm),
   })
 
   /**
@@ -3540,13 +3671,50 @@ const titleOfSummary = (item) => {
       // 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.
+      //
+      // THE STAGE IS ON SCREEN BEFORE THE COPY STARTS, and the copy reports the
+      // files and bytes it really writes. That is the fix of "I clicked restart
+      // and nothing happened for ten seconds": the ten seconds ARE the snapshot,
+      // and now they say so.
       const stateDir = path.dirname(stateFile)
-      const snapshot = snapshotFn({
-        config,
-        stateDir,
-        log,
-        profile: resolveProfileDirDetailed(),
-      })
+      resetSnapshotCancel()
+      markRestartStage('snapshotting')
+      let cancelled = false
+      let snapshot
+      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)
+      }
+      if (cancelled) {
+        // The user called it off while the files were being copied: the
+        // half-written snapshot is already gone (createBackup removes it), the
+        // host does not restart, and the request is WITHDRAWN — a restart the
+        // user cancelled must not be retried five seconds later.
+        log.warn('the restart was cancelled while the snapshot was being written')
+        clearRestartStage()
+        releaseRequesters()
+        cancelRestart(state, { now: Date.now() })
+        persist()
+        stopPolling()
+        return
+      }
       // 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
@@ -3677,6 +3845,10 @@ const titleOfSummary = (item) => {
           // 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.
+          //
+          // FROM HERE ON THE RESTART CANNOT BE CANCELLED, and the interface says
+          // so: the host is on its way out.
+          markRestartStage('restarting')
           const outcome = await runCommandFn({
             command,
             timeoutMs: config.restartCommandTimeoutMs,
@@ -3814,8 +3986,15 @@ const titleOfSummary = (item) => {
           watchScript,
         })
         log.warn('scheduled detached restart:', result)
-        if (!result || result.ok !== true) rollbackRestart((result && result.error) || 'detached restart refused')
-        else armGateWatchdog()
+        if (!result || result.ok !== true) {
+          markRestartStage('waiting', { blocked: 0 })
+          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')
+          armGateWatchdog()
+        }
       }
     } catch (error) {
       rollbackRestart(String(error))
@@ -4059,6 +4238,157 @@ const titleOfSummary = (item) => {
     get bootId() {
       return bootId
     },
+    /**
+     * THE STATE DIRECTORY of this boot — the checkpoint, the watchdog markers
+     * and the scheduling-item leftovers all live in it.
+     *
+     * It is exposed ON PURPOSE: the health route is a module-level function
+     * and used to read the directory from a variable that only existed inside
+     * this factory. The lookup threw `ReferenceError: stateDirOf is not
+     * defined` on every request, an empty `catch {}` ate it, and a healthy
+     * host left an armed watchdog behind (the 0.8.2 incident). Anything a
+     * route needs must be reachable through `runtime`, never through a
+     * closure it cannot see.
+     */
+    get stateDir() {
+      return path.dirname(stateFile)
+    },
+    /**
+     * The version of the plugin that is actually LOADED in this process.
+     *
+     * The health route reports it so a real-machine check can tell "the new
+     * code is running" from "the old code is still loaded".
+     */
+    get pluginVersion() {
+      return ownVersion()
+    },
+    /**
+     * DISARM THE WATCHDOG: "this host is up, so nothing may roll it back".
+     *
+     * The ready marker is written on the FIRST tick of the first attempt (so a
+     * caller inside an HTTP route has it on disk before it answers), the
+     * pending marker and the scheduling item are cleaned with retries, and the
+     * record is kept on `runtime` and written next to the markers.
+     *
+     * One run at a time: a second call while one is running returns the same
+     * promise instead of starting a second `schtasks` dance.
+     *
+     * @param {string} [source] where the call came from ('boot', 'health-route', …)
+     * @returns {Promise<object>} the record
+     */
+    disarmWatchdog(source = 'boot') {
+      if (disarmInFlight !== null) {
+        // One run at a time (two `schtasks /Delete` calls fight each other),
+        // but a request that arrives DURING a run is remembered: a pending
+        // marker written in the meantime must still be cleaned, not lost.
+        disarmPendingAgain = true
+        return disarmInFlight
+      }
+      const one = (where) => {
+        const port = Number(runtime.webPort)
+        return runDisarmWatchdog({
+          stateDir: stateDirOf(),
+          bootId,
+          port: Number.isFinite(port) && port > 0 ? port : null,
+          source: where,
+          log,
+        })
+          .then((record) => {
+            watchdogDisarm = record
+            if (record.ok === true) {
+              log.info('the watchdog is disarmed (' + where + ')', {
+                attempts: record.attempts,
+                tier: record.tier,
+              })
+            }
+            return record
+          })
+          .catch((error) => {
+            // The disarm must never reject: the health route and the boot path
+            // both call it without a `catch`.
+            watchdogDisarm = {
+              at: new Date().toISOString(),
+              source: String(where),
+              bootId,
+              attempts: 0,
+              ok: false,
+              ready: false,
+              pending: null,
+              tier: null,
+              scheduleRemoved: null,
+              scheduleError: null,
+              errors: [{
+                attempt: 0,
+                step: 'disarm',
+                name: error && error.name ? String(error.name) : 'Error',
+                message: error && error.message ? String(error.message) : String(error),
+              }],
+            }
+            log.warn('the watchdog could not be disarmed:', String(error))
+            return watchdogDisarm
+          })
+      }
+      const drive = async () => {
+        let record = await one(source)
+        while (disarmPendingAgain === true) {
+          disarmPendingAgain = false
+          record = await one(String(source) + '+again')
+        }
+        return record
+      }
+      const running = drive().then(
+        (record) => {
+          disarmInFlight = null
+          disarmPendingAgain = false
+          return record
+        },
+        (error) => {
+          disarmInFlight = null
+          disarmPendingAgain = false
+          throw error
+        },
+      )
+      disarmInFlight = running
+      return running
+    },
+    /**
+     * The record of the last disarm (null when this host never disarmed one).
+     */
+    get watchdogDisarm() {
+      return watchdogDisarm
+    },
+    // THE STAGE OF A RESTART, as every surface reads it. `markRestartStage`
+    // writes it and persists immediately (that is what makes the first stage
+    // appear within the first second after the click), `recordSnapshotProgress`
+    // carries the REAL bytes of the running copy, and `restartStageInfo` is the
+    // single description (text included) that the state route, the health route
+    // and the settings page share.
+    markRestartStage,
+    recordSnapshotProgress,
+    clearRestartStage,
+    restartStageInfo,
+    requestSnapshotCancel,
+    snapshotCancelled,
+    resetSnapshotCancel,
+    /**
+     * The stage of a restart, cut down for the health route (no long texts).
+     *
+     * @returns {object} `{ phase, at, progress, slow, cancellable }`
+     */
+    restartStageBrief() {
+      const info = restartStageInfo()
+      return {
+        phase: info.phase,
+        at: info.at,
+        elapsedMs: info.elapsedMs,
+        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 },
+        slow: info.slow,
+        cancellable: info.cancellable,
+        cancelReason: info.cancelReason,
+      }
+    },
     /**
      * Where the effective `backupIncludePlugins` value came from:
      * `config` (the profile row), `fallback-file` (the degraded path) or
@@ -5149,6 +5479,10 @@ function registerTools(ctx, runtime, config) {
       if (typeof args.defer_seconds === 'number' && Number.isFinite(args.defer_seconds) && args.defer_seconds > 0) {
         state.restart.requestedAt = now + Math.min(args.defer_seconds, 3600) * 1000
       }
+      // THE FIRST STAGE, RIGHT NOW — not when the backup starts. The interface
+      // polls this out of the state route, so the click produces a visible
+      // answer in well under a second.
+      runtime.markRestartStage('waiting', { blocked: countBlockerTasks(runtime.gate().blockedBy) })
       runtime.persist()
       runtime.startPolling()
       log.info('restart requested', { generation: state.generation, sessionId, resume, parkGoals })
@@ -6077,6 +6411,9 @@ function buildParkRoute(ctx, runtime, config) {
             resume: true,
             now: Date.now(),
           })
+          // The first stage, in the same breath as the request: the answer to
+          // this POST is already "waiting for the sessions", never silence.
+          runtime.markRestartStage('waiting', { blocked: blockingSessionIds(runtime).length })
           runtime.persist()
           runtime.startPolling()
         }
@@ -6172,6 +6509,28 @@ function buildCancelRoute(ctx, runtime, config) {
           })
           return
         }
+        // THE STAGE DECIDES WHETHER A CANCEL IS HONEST.
+        //
+        // While the snapshot is being written the copy is stopped between two
+        // files and its half-written directory is removed — the host never
+        // restarts. Once the host is on its way out (`restarting`) a cancel
+        // would be a promise this plugin cannot keep, so it is REFUSED with the
+        // reason, and the button is greyed out on the same answer.
+        const stage = runtime.restartStageInfo()
+        if (stage.cancellable !== true) {
+          const reason = cancelRefusalReason(stage.phase) || 'the host is already restarting'
+          runtime.log.warn(`the cancel route refused the request of session ${sessionId}: ${reason}`)
+          answer(409, {
+            ok: false,
+            cancelled: false,
+            reason: 'not-cancellable',
+            stage: stage.phase,
+            error: reason,
+            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
@@ -6194,7 +6553,14 @@ function buildCancelRoute(ctx, runtime, config) {
         }
         // Release ONLY this session's continuation request.
         runtime.releaseRequesters([sessionId])
-        if (outcome.cancelled) runtime.stopPolling()
+        if (outcome.cancelled) {
+          // The whole restart is off. If the snapshot is being written right
+          // now, the copy stops at the next file and removes its half-written
+          // directory (the host never restarts); otherwise the stage just goes.
+          if (stage.phase === 'snapshotting') runtime.requestSnapshotCancel()
+          runtime.clearRestartStage()
+          runtime.stopPolling()
+        }
         runtime.persist()
         runtime.log.info(
           outcome.cancelled
@@ -7377,6 +7743,39 @@ function buildSleepRoute(ctx, runtime, config, sleep) {
 }
 
 /** Expose a tiny read-only health route for humans and verification scripts. */
+/**
+ * The disarm record, cut down to what a reader outside the process needs.
+ *
+ * The health route answers with it, so a real-machine check can tell "the
+ * watchdog was stood down" from "it is still armed" without reading a log.
+ *
+ * @param {object|null} record
+ * @returns {object|null}
+ */
+function summarizeDisarm(record) {
+  if (!record || typeof record !== 'object') return null
+  const errors = Array.isArray(record.errors) ? record.errors : []
+  return {
+    ok: record.ok === true,
+    at: typeof record.at === 'string' ? record.at : null,
+    source: typeof record.source === 'string' ? record.source : null,
+    attempts: Number.isFinite(Number(record.attempts)) ? Number(record.attempts) : 0,
+    ready: record.ready === true,
+    pending: record.pending === true,
+    tier: typeof record.tier === 'string' ? record.tier : null,
+    scheduleRemoved: record.scheduleRemoved === true ? true : (record.scheduleRemoved === false ? false : null),
+    // Only the first failure: the route answer must stay small, and one named
+    // error is what makes the failure diagnosable.
+    error: errors.length > 0
+      ? {
+        step: typeof errors[0].step === 'string' ? errors[0].step : null,
+        name: typeof errors[0].name === 'string' ? errors[0].name : null,
+        message: typeof errors[0].message === 'string' ? errors[0].message : null,
+      }
+      : null,
+  }
+}
+
 function registerHealthRoute(ctx, runtime, config, sleep) {
   const routePath = typeof config.healthPath === 'string' && config.healthPath.startsWith('/')
     ? config.healthPath
@@ -7471,6 +7870,10 @@ function registerHealthRoute(ctx, runtime, config, sleep) {
             }
           }
           const verdict = runtime.gate()
+          // The restart stage (waiting / snapshotting / restarting / back), the
+          // real snapshot progress and the "is a cancel still honest" answer —
+          // computed ONCE per answer so every field of the payload agrees.
+          const stage = runtime.restartStageInfo()
           // Best effort: label the blocking sessions with their titles when the
           // session controller knows them. The title is optional, so an entry
           // without one is sent exactly as the gate produced it. The goal
@@ -7506,6 +7909,14 @@ function registerHealthRoute(ctx, runtime, config, sleep) {
             // long the restart has been waiting, why, and who holds it — the
             // request itself is never dropped.
             longWait: runtime.longWaitInfo(),
+            // THE STAGE OF THE RESTART, for the pill and the settings page:
+            // which of the four stages is on screen, the real copy progress of
+            // the snapshot, whether it is going slower than expected, and
+            // whether a cancel would still be honest (`cancellable`).
+            restartPhase: stage,
+            // 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,
             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
@@ -7630,27 +8041,64 @@ function registerHealthRoute(ctx, runtime, config, sleep) {
       // THE READY MARKER: this host answers its own health route, so it is
       // up. The watchdog (which waits for the relaunched host) sees the
       // marker and stands down — no rollback of a host that is fine.
+      //
+      // THE STATE DIRECTORY COMES FROM `runtime`, NEVER FROM A CLOSURE:
+      // 0.8.2 read it through a variable that only existed inside the runtime
+      // factory, so every request threw `ReferenceError: stateDirOf is not
+      // defined`, the `catch {}` swallowed it, and a healthy host left the
+      // pending marker AND the scheduled task behind (the watchdog would have
+      // rolled a healthy profile back). The failure is recorded now, and the
+      // marker is written first because the marker alone is what stops a
+      // rollback.
       try {
-        const marker = readReady(stateDirOf())
-        if (!marker || marker.bootId !== runtime.bootId) {
-          writeReady(stateDirOf(), { bootId: runtime.bootId, port: runtime.port ?? null })
-          // The host is up: the watchdog has nothing to do. Its scheduling
-          // item and its pending marker go NOW — nothing may be left behind.
-          if (readPending(stateDirOf()) !== null) {
-            clearPending(stateDirOf())
-            try {
-              removeScheduledTask({ taskName: 'dsh-autorestart-watchdog' })
-            } catch {
-              // The watchdog removes it itself when it runs.
+        const stateDir = typeof runtime.stateDir === 'string' ? runtime.stateDir : ''
+        if (stateDir !== '') {
+          const marked = markReady({
+            stateDir,
+            bootId: runtime.bootId,
+            port: runtime.webPort ?? null,
+          })
+          if (marked.ok !== true) {
+            runtime.watchdogReadyError = {
+              at: Date.now(),
+              message: marked.detail,
+              name: marked.error && marked.error.name ? String(marked.error.name) : null,
             }
           }
+          // The marker alone stands the watchdog down; the pending marker and
+          // the scheduling item are cleaned with retries in the background, so
+          // `schtasks` never delays this answer.
+          runtime.disarmWatchdog('health-route')
+        }
+      } catch (error) {
+        // NEVER silent: a swallowed error here leaves an armed watchdog behind.
+        // It is recorded on `runtime` (this scope has no logger) so the settings
+        // page and the diagnostics can show it instead of pretending all is well.
+        runtime.watchdogReadyError = {
+          at: Date.now(),
+          name: error && error.name ? String(error.name) : 'Error',
+          message: String(error && error.message ? error.message : error),
+        }
+        // One retry with the bare minimum: the marker alone is what the
+        // watchdog actually waits for.
+        try {
+          markReady({
+            stateDir: typeof runtime.stateDir === 'string' ? runtime.stateDir : '',
+            bootId: runtime.bootId,
+            port: runtime.webPort ?? null,
+          })
+          runtime.watchdogReadyError.retry = 'ok'
+        } catch (again) {
+          runtime.watchdogReadyError.retry = String(again && again.message ? again.message : again)
         }
-      } catch {
-        // The marker is a convenience: the watchdog also asks the health route.
       }
       const body = JSON.stringify({
         ok: true,
         plugin: name,
+        // The version of the code that is LOADED (not the fallback constant):
+        // a real-machine check can tell "the new build is running" from "the
+        // old one is still in memory".
+        version: runtime.pluginVersion ?? PLUGIN_VERSION_FALLBACK,
         bootId: runtime.bootId,
         pid: process.pid,
         phase: state.phase,
@@ -7662,6 +8110,15 @@ function registerHealthRoute(ctx, runtime, config, sleep) {
         manualRestartBlocks: runtime.manualRestartBlocks ?? 0,
         indexTaps: runtime.indexTaps ?? 0,
         configSchema: Config !== undefined,
+        // DID THE DISARM WORK? A failed disarm means an armed watchdog is still
+        // out there; it must be visible from outside the process, not only in
+        // a log line nobody reads.
+        watchdog: summarizeDisarm(runtime.watchdogDisarm),
+        // 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.
+        restartPhase: runtime.restartStageBrief(),
+        progress: runtime.restartStageBrief().progress,
         schemastery: Config === undefined
           ? (schemastery === undefined ? 'unresolved' : 'construction-failed')
           : (schemasterySource === 'bare-specifier' ? 'bare' : 'asar-fallback'),
@@ -7938,6 +8395,12 @@ export function apply(ctx, rawConfig, options = {}) {
   // Record this boot in the checkpoint even when there is nothing to recover.
   persistSafely(runtime)
 
+  // THE LAST STAGE OF THE RESTART: this host IS the new one, so the interface
+  // 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')
+
   trackAgents(ctx, runtime, config)
 
   // The boot recovery pass is the plugin's primary boot duty, so it is scheduled
@@ -7955,8 +8418,7 @@ export function apply(ctx, rawConfig, options = {}) {
     })
     sleep.restore()
   }
-  if (runtime.isNewBoot && config.resumeOnBoot) {
-    runtime.recoverTimer = ctx.timeout(() => {
+  if (runtime.isNewBoot && config.resumeOnBoot) {    runtime.recoverTimer = ctx.timeout(() => {
       recoverAfterRestart(ctx, runtime, config)
         .then(() => {
           runtime.recovery = { ran: true, ok: true, detail: 'the boot recovery finished' }
@@ -7995,6 +8457,19 @@ export function apply(ctx, rawConfig, options = {}) {
   registerSystemPrompt(ctx, runtime)
   registerHealthRoute(ctx, runtime, config, sleep)
 
+  // DISARM THE WATCHDOG AT BOOT — WITHOUT WAITING FOR ANYBODY TO ASK.
+  //
+  // This is the fix of the 0.8.2 incident: the ready marker and the cleanup of
+  // the pending marker / scheduled task hung on the health route being hit.
+  // The plugin is fully loaded at this point (every route is registered, the
+  // boot recovery is scheduled), so this instance is "up" in the only sense
+  // the watchdog cares about: it must not be rolled back.
+  //
+  // The call never rejects (see runtime.disarmWatchdog) and never blocks the
+  // load: the marker is written synchronously on its first tick, the
+  // `schtasks` cleanup runs with retries behind it.
+  runtime.disarmWatchdog('boot')
+
   ctx.effect(() => () => {
     runtime.markDisposed()
     runtime.stopPolling()