dsh-autorestart 0.8.1 → 0.8.3

package/lib/backup.js

@@ -204,6 +204,164 @@ function copyEntry(source, destination) {
   }
 }
 
+/**
+ * Measure a tree so the copy can report a REAL total (files and bytes).
+ *
+ * The plugin tree of a desktop profile is ~150 MB; walking it costs a few tens
+ * of milliseconds and it is the only way to say "154 MB of 156 MB done" instead
+ * of making a number up.
+ *
+ * @param {string} target
+ * @returns {{ files: number, bytes: number }}
+ */
+export function measureTree(target) {
+  return directorySize(target);
+}
+
+/**
+ * Copy a directory tree FILE BY FILE, reporting real progress and honouring a
+ * cancel request.
+ *
+ * `fs.cpSync` (what this used to be) copies 150 MB in one call: no progress, no
+ * cancel, and no way to tell a busy disk from a dead host. The loop below copies
+ * one file at a time, adds up the bytes that really landed and asks the caller
+ * between files whether it should stop.
+ *
+ * IT YIELDS TO THE EVENT LOOP on purpose: the copy runs inside the host
+ * process, and a copy that never yields blocks the very route the "cancel"
+ * button posts to — the user could not call it off even though the code says
+ * they can. Every `yieldEveryFiles` files (and every `yieldEveryMs`
+ * milliseconds) the loop waits one tick, so the server stays answerable and the
+ * progress reaches the interface while the copy is running.
+ *
+ * @param {{
+ *   source: string,
+ *   destination: string,
+ *   onProgress?: Function|null,
+ *   shouldCancel?: Function|null,
+ *   progressEveryFiles?: number,
+ *   yieldEveryFiles?: number,
+ *   yieldEveryMs?: number,
+ *   yieldToEventLoop?: Function|null,
+ *   now?: Function,
+ * }} options
+ * @returns {Promise<{ ok: boolean, files: number, bytes: number, cancelled: boolean, error: string|null }>}
+ */
+export async function copyTreeWithProgress({
+  source,
+  destination,
+  onProgress = null,
+  shouldCancel = null,
+  progressEveryFiles = 25,
+  yieldEveryFiles = 40,
+  yieldEveryMs = 120,
+  yieldToEventLoop = null,
+  now = Date.now,
+} = {}) {
+  const from = typeof source === 'string' ? source : '';
+  const into = typeof destination === 'string' ? destination : '';
+  if (from === '' || into === '') {
+    return { ok: false, files: 0, bytes: 0, cancelled: false, error: 'copyTreeWithProgress requires a source and a destination' };
+  }
+  const pause = typeof yieldToEventLoop === 'function'
+    ? yieldToEventLoop
+    : () => new Promise((resolve) => { setImmediate(resolve); });
+  const clock = typeof now === 'function' ? now : Date.now;
+  let files = 0;
+  let bytes = 0;
+  let cancelled = false;
+  let error = null;
+  const tick = { files: 0, at: clock(), yielded: clock() };
+  const report = () => {
+    if (typeof onProgress !== 'function') return;
+    tick.at = clock();
+    try {
+      onProgress({ files, bytes });
+    } catch {
+      // A broken progress callback must never fail the backup itself.
+    }
+  };
+
+  const walk = async (sourceDir, targetDir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(sourceDir, { withFileTypes: true });
+    } catch (failure) {
+      // A directory that cannot be read is skipped, exactly like before: a
+      // single unreadable plugin directory must not break the whole snapshot.
+      error = error === null ? (failure && failure.message ? failure.message : String(failure)) : error;
+      return;
+    }
+    try {
+      fs.mkdirSync(targetDir, { recursive: true });
+    } catch {
+      /* it may already exist */
+    }
+    for (const entry of entries) {
+      if (typeof shouldCancel === 'function' && shouldCancel() === true) {
+        cancelled = true;
+        return;
+      }
+      const childSource = path.join(sourceDir, entry.name);
+      const childTarget = path.join(targetDir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(childSource, childTarget);
+        if (cancelled) return;
+        continue;
+      }
+      try {
+        fs.copyFileSync(childSource, childTarget);
+        files += 1;
+        try {
+          bytes += fs.statSync(childTarget).size;
+        } catch {
+          /* the size is advisory */
+        }
+      } catch (failure) {
+        error = error === null ? (failure && failure.message ? failure.message : String(failure)) : error;
+        continue;
+      }
+      tick.files += 1;
+      const moment = clock();
+      if (tick.files >= progressEveryFiles || moment - tick.at >= 150) {
+        tick.files = 0;
+        report();
+      }
+      if (moment - tick.yielded >= yieldEveryMs || tick.files >= yieldEveryFiles) {
+        tick.yielded = moment;
+        // eslint-disable-next-line no-await-in-loop
+        await pause();
+        if (typeof shouldCancel === 'function' && shouldCancel() === true) {
+          cancelled = true;
+          return;
+        }
+      }
+    }
+  };
+
+  await walk(from, into);
+  report();
+  if (cancelled) return { ok: false, files, bytes, cancelled: true, error: null };
+  return { ok: true, files, bytes, cancelled: false, error };
+}
+
+/**
+ * Remove a half-written backup (a cancelled copy must not look like a snapshot).
+ *
+ * @param {string} dir
+ * @returns {boolean}
+ */
+export function removeBackupDir(dir) {
+  const target = typeof dir === 'string' ? dir.trim() : '';
+  if (target === '') return false;
+  try {
+    fs.rmSync(target, { recursive: true, force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Keep only the newest `maxBackups` backup directories.
  *
@@ -301,6 +459,11 @@ export function readManifest(backupDir) {
  * rollback of "a plugin upgrade broke the boot" actually possible; without it only
  * the configuration files are copied.
  *
+ * THE COPY IS INTERRUPTIBLE AND MEASURED: `onProgress` is called with the files
+ * and bytes that really landed (plus the measured total), and `shouldCancel` is
+ * asked between files. A cancelled copy removes its own half-written snapshot,
+ * so a cancel never leaves something that looks like a usable backup.
+ *
  * Never throws: a backup that cannot be written is reported as `{ ok: false }` so
  * the caller can decide whether the restart may still proceed.
  *
@@ -310,27 +473,36 @@ export function readManifest(backupDir) {
  *   includePlugins?: boolean,
  *   maxBackups?: number,
  *   now?: number,
+ *   onProgress?: ((progress: { files: number, bytes: number, total: number, filesTotal: number }) => void)|null,
+ *   shouldCancel?: (() => boolean)|null,
+ *   measure?: ((profileDir: string, includePlugins: boolean) => { files: number, bytes: number })|null,
  * }} options
- * @returns {{ ok: boolean, dir: string|null, stamp: string|null, at: number|null, atLocal: string|null, durationMs: number, bytes: number, files: string[], includePlugins: boolean, pruned: string[], error: string|null }}
+ * @returns {{ ok: boolean, cancelled: boolean, dir: string|null, stamp: string|null, at: number|null, atLocal: string|null, durationMs: number, bytes: number, totalBytes: number, fileCount: number, files: string[], includePlugins: boolean, pruned: string[], error: string|null }}
  */
-export function createBackup({
+export async function createBackup({
   profileDir,
   backupsDir,
   includePlugins = true,
   maxBackups = DEFAULT_MAX_BACKUPS,
   now = Date.now(),
+  onProgress = null,
+  shouldCancel = null,
+  measure = null,
 } = {}) {
   const profile = typeof profileDir === 'string' ? profileDir.trim() : '';
   const root = typeof backupsDir === 'string' ? backupsDir.trim() : '';
   const startedAt = Date.now();
   const base = {
     ok: false,
+    cancelled: false,
     dir: null,
     stamp: null,
     at: null,
     atLocal: null,
     durationMs: 0,
     bytes: 0,
+    totalBytes: 0,
+    fileCount: 0,
     files: [],
     includePlugins: includePlugins === true,
     pruned: [],
@@ -340,37 +512,131 @@ export function createBackup({
   if (root === '') return { ...base, error: 'createBackup requires backupsDir' };
   if (!fs.existsSync(profile)) return { ...base, error: 'the profile directory does not exist' };
 
+  // MEASURE FIRST: the progress report needs a denominator that is not made up.
+  const measured = (() => {
+    try {
+      if (typeof measure === 'function') {
+        const answer = measure(profile, includePlugins === true);
+        return {
+          files: Math.max(0, Number(answer && answer.files) || 0),
+          bytes: Math.max(0, Number(answer && answer.bytes) || 0),
+        };
+      }
+      const total = { files: 0, bytes: 0 };
+      for (const name of CONFIG_FILES) {
+        try {
+          total.bytes += fs.statSync(path.join(profile, name)).size;
+          total.files += 1;
+        } catch {
+          /* a missing config file is not a problem */
+        }
+      }
+      if (includePlugins === true) {
+        const tree = directorySize(path.join(profile, PLUGINS_DIR));
+        total.bytes += tree.bytes;
+        total.files += tree.files;
+      }
+      return total;
+    } catch {
+      return { files: 0, bytes: 0 };
+    }
+  })();
+
   const stamp = backupStamp(now);
   const dir = path.join(root, stamp);
   const files = [];
   let bytes = 0;
+  let fileCount = 0;
+  let cancelled = false;
+  const isCancelled = () => {
+    if (cancelled === true) return true;
+    if (typeof shouldCancel !== 'function') return false;
+    try {
+      if (shouldCancel() === true) {
+        cancelled = true;
+        return true;
+      }
+    } catch {
+      // A broken cancel callback must not abort anything.
+    }
+    return false;
+  };
+  const report = (approx) => {
+    if (typeof onProgress !== 'function') return;
+    try {
+      onProgress({
+        files: fileCount,
+        bytes,
+        total: measured.bytes,
+        filesTotal: measured.files,
+        // The estimate is passed along so the caller does not have to redo the
+        // arithmetic; it is null until there is a real measurement to divide.
+        ...(approx ? { approximate: true } : {}),
+      });
+    } catch {
+      // Progress reporting never fails a backup.
+    }
+  };
+
   try {
     fs.mkdirSync(path.join(dir, CONFIG_DIR), { recursive: true });
   } catch (error) {
-    return { ...base, stamp, error: 'could not create the backup directory: ' + (error && error.message ? error.message : String(error)) };
+    return { ...base, stamp, totalBytes: measured.bytes, error: 'could not create the backup directory: ' + (error && error.message ? error.message : String(error)) };
   }
 
+  let configBytes = 0;
   for (const name of CONFIG_FILES) {
+    if (isCancelled()) break;
     const source = path.join(profile, name);
     if (!fs.existsSync(source)) continue;
     if (copyEntry(source, path.join(dir, CONFIG_DIR, name))) {
       files.push(path.join(CONFIG_DIR, name));
+      fileCount += 1;
       try {
-        bytes += fs.statSync(path.join(dir, CONFIG_DIR, name)).size;
+        configBytes += fs.statSync(path.join(dir, CONFIG_DIR, name)).size;
+        bytes = configBytes;
       } catch {
         // Size reporting is advisory only.
       }
+      report(false);
     }
   }
 
-  if (includePlugins === true) {
+  if (!cancelled && includePlugins === true) {
     const source = path.join(profile, PLUGINS_DIR);
-    if (fs.existsSync(source) && copyEntry(source, path.join(dir, PLUGINS_DIR))) {
-      files.push(PLUGINS_DIR);
-      bytes += directorySize(path.join(dir, PLUGINS_DIR)).bytes;
+    if (fs.existsSync(source)) {
+      const copied = await copyTreeWithProgress({
+        source,
+        destination: path.join(dir, PLUGINS_DIR),
+        shouldCancel: isCancelled,
+        onProgress: (progress) => {
+          fileCount = files.length + progress.files;
+          bytes = configBytes + progress.bytes;
+          report(false);
+        },
+      });
+      if (copied.cancelled) {
+        cancelled = true;
+      } else if (copied.ok || copied.files > 0) {
+        files.push(PLUGINS_DIR);
+        fileCount = files.length + copied.files;
+        bytes = configBytes + copied.bytes;
+      }
     }
   }
 
+  if (cancelled) {
+    removeBackupDir(dir);
+    return {
+      ...base,
+      cancelled: true,
+      stamp,
+      totalBytes: measured.bytes,
+      durationMs: Math.max(0, Date.now() - startedAt),
+      error: 'the backup was cancelled',
+    };
+  }
+
   const manifest = {
     stamp,
     at: Number(now),
@@ -381,11 +647,13 @@ export function createBackup({
     includePlugins: includePlugins === true,
     files,
     bytes,
+    totalBytes: measured.bytes,
+    fileCount,
   };
   try {
     fs.writeFileSync(path.join(dir, MANIFEST_NAME), JSON.stringify(manifest, null, 2), 'utf8');
   } catch (error) {
-    return { ...base, stamp, files, bytes, error: 'could not write the backup manifest: ' + (error && error.message ? error.message : String(error)) };
+    return { ...base, stamp, files, bytes, totalBytes: measured.bytes, fileCount, error: 'could not write the backup manifest: ' + (error && error.message ? error.message : String(error)) };
   }
 
   const pruned = pruneBackups(root, maxBackups);
@@ -398,6 +666,8 @@ export function createBackup({
     atLocal: manifest.atLocal,
     durationMs: Math.max(0, Date.now() - startedAt),
     bytes,
+    totalBytes: measured.bytes,
+    fileCount,
     files,
     pruned,
   };

package/lib/checkpoint.js

@@ -30,6 +30,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { randomBytes, randomUUID } from 'node:crypto';
 import { PHASES, selectRecoverableSessions } from './lifecycle.js';
+import { RESTART_PHASES } from './restart-phase.js';
 
 /** Current on-disk schema version. */
 export const STATE_VERSION = 1;
@@ -101,6 +102,7 @@ const TOP_LEVEL_KEYS = new Set([
   'bootStartedAt',
   'generation',
   'phase',
+  'restartPhase',
   'restart',
   'sessions',
   'parkedGoals',
@@ -173,6 +175,11 @@ export function createEmptyState(now = Date.now()) {
     bootStartedAt: null,
     generation: 0,
     phase: 'idle',
+    // WHICH STAGE THE RESTART IS IN (see lib/restart-phase.js): null when no
+    // restart is under way, otherwise `{ phase, startedAt, at, progress }`.
+    // It lives in the checkpoint (not in memory) so the interface can read it
+    // out of the state route from the very first moment after the click.
+    restartPhase: null,
     restart: null,
     sessions: {},
     seenFeatureVersions: {},
@@ -182,6 +189,146 @@ export function createEmptyState(now = Date.now()) {
   };
 }
 
+/**
+ * Coerce the recorded restart stage into the documented shape.
+ *
+ * A record that does not describe one of the four stages is dropped: a broken
+ * stage must never leave a spinner on screen for ever.
+ *
+ * @param {unknown} raw
+ * @param {number} now
+ * @returns {{ record: object|null, changed: boolean }}
+ */
+function normalizeRestartPhase(raw, now) {
+  if (raw == null) return { record: null, changed: false };
+  if (!isObject(raw)) return { record: null, changed: true };
+  if (!RESTART_PHASES.includes(raw.phase)) return { record: null, changed: true };
+  const startedAt = isFiniteNumber(raw.startedAt) ? raw.startedAt : now;
+  const at = isFiniteNumber(raw.at) ? raw.at : startedAt;
+  let progress = null;
+  let changed = !isFiniteNumber(raw.startedAt) || !isFiniteNumber(raw.at);
+  if (isObject(raw.progress)) {
+    progress = {
+      files: isFiniteNumber(raw.progress.files) ? Math.max(0, Math.trunc(raw.progress.files)) : 0,
+      bytes: isFiniteNumber(raw.progress.bytes) ? Math.max(0, Math.trunc(raw.progress.bytes)) : 0,
+      total: isFiniteNumber(raw.progress.total) ? Math.max(0, Math.trunc(raw.progress.total)) : 0,
+      filesTotal: isFiniteNumber(raw.progress.filesTotal) ? Math.max(0, Math.trunc(raw.progress.filesTotal)) : 0,
+      at: isFiniteNumber(raw.progress.at) ? raw.progress.at : at,
+    };
+  } else if (raw.progress != null) {
+    changed = true;
+  }
+  const record = {
+    phase: raw.phase,
+    startedAt,
+    at,
+    progress,
+    // HOW BIG THE PRE-RESTART BACKUP WAS. It is kept across the stage change on
+    // purpose: a hosted profile can be 92 KB and the copy takes ~5 ms, so a page
+    // that polls every 2 s would otherwise never learn that a backup happened
+    // (user report, 2026-10-29). null = nothing was measured.
+    snapshotBytes: isFiniteNumber(raw.snapshotBytes) ? Math.max(0, Math.trunc(raw.snapshotBytes)) : null,
+    blocked: isFiniteNumber(raw.blocked) ? Math.max(0, Math.trunc(raw.blocked)) : 0,
+  };
+  return { record, changed };
+}
+
+/**
+ * Record the stage the restart is in — the ONE thing the interface reads.
+ *
+ * Writing it is deliberately cheap and synchronous: it is called the moment the
+ * user clicks, before any backup starts, so the first stage is on disk in
+ * milliseconds rather than after ten seconds of copying.
+ *
+ * @param {object} state the checkpoint state (mutated in place)
+ * @param {{ phase: string, now?: number, blocked?: number, restartStage?: boolean }} options
+ * @returns {object|null} the recorded stage
+ */
+export function setRestartPhase(state, { phase, now = Date.now(), blocked = 0, restartStage = true } = {}) {
+  if (!isObject(state)) return null;
+  if (!RESTART_PHASES.includes(phase)) return state.restartPhase ?? null;
+  const moment = isFiniteNumber(now) ? now : Date.now();
+  const previous = isObject(state.restartPhase) ? state.restartPhase : null;
+  // A new restart starts its own clock; a stage change inside the same restart
+  // keeps the start time, so "elapsed" is the whole restart and not one stage.
+  const sameRestart = restartStage && previous !== null && RESTART_PHASES.includes(previous.phase)
+    && !(phase === 'waiting' && previous.phase !== 'waiting');
+  const startedAt = sameRestart ? previous.startedAt : moment;
+  // THE SIZE OF THE SNAPSHOT, measured once and then CARRIED: the live byte
+  // counter while the copy runs, the final size afterwards. A 92 KB profile is
+  // copied in ~5 ms, so this number is the only thing a polling interface can
+  // still say about a backup that really happened (user report, 2026-10-29).
+  const measuredBytes = previous !== null && isFiniteNumber(previous.snapshotBytes)
+    ? Math.max(0, Math.trunc(previous.snapshotBytes))
+    : (previous !== null && isObject(previous.progress) && isFiniteNumber(previous.progress.bytes)
+      ? Math.max(0, Math.trunc(previous.progress.bytes))
+      : null);
+  const record = {
+    phase,
+    startedAt,
+    at: moment,
+    // The progress of a previous stage is meaningless in the next one: the
+    // snapshot numbers must not be shown while the host is restarting.
+    progress: phase === 'snapshotting' && previous !== null && previous.phase === 'snapshotting'
+      ? previous.progress
+      : null,
+    // A NEW restart starts with nothing measured; a stage change inside one
+    // restart keeps the size it already has.
+    snapshotBytes: sameRestart ? measuredBytes : null,
+    blocked: isFiniteNumber(blocked) ? Math.max(0, Math.trunc(blocked)) : 0,
+  };
+  state.restartPhase = record;
+  state.updatedAt = moment;
+  return record;
+}
+
+/**
+ * Update the REAL snapshot progress (files and bytes that were copied).
+ *
+ * @param {object} state the checkpoint state (mutated in place)
+ * @param {{ files?: number, bytes?: number, total?: number, filesTotal?: number, now?: number }} progress
+ * @returns {object|null} the recorded stage
+ */
+export function setRestartProgress(state, { files = 0, bytes = 0, total = 0, filesTotal = 0, now = Date.now() } = {}) {
+  if (!isObject(state)) return null;
+  const moment = isFiniteNumber(now) ? now : Date.now();
+  const previous = isObject(state.restartPhase) ? state.restartPhase : null;
+  const number = (value) => (isFiniteNumber(value) ? Math.max(0, Math.trunc(value)) : 0);
+  state.restartPhase = {
+    phase: 'snapshotting',
+    startedAt: previous !== null && isFiniteNumber(previous.startedAt) ? previous.startedAt : moment,
+    at: moment,
+    progress: {
+      files: number(files),
+      bytes: number(bytes),
+      total: number(total),
+      filesTotal: number(filesTotal),
+      at: moment,
+    },
+    // The live byte counter IS the size of the snapshot so far: keeping it here
+    // means the number survives the moment the copy ends.
+    snapshotBytes: number(bytes),
+    blocked: previous !== null && isFiniteNumber(previous.blocked) ? previous.blocked : 0,
+  };
+  state.updatedAt = moment;
+  return state.restartPhase;
+}
+
+/**
+ * Forget the stage (the restart was cancelled, or it failed before exiting).
+ *
+ * @param {object} state
+ * @param {{ now?: number }} [options]
+ * @returns {boolean} whether a stage was cleared
+ */
+export function clearRestartPhase(state, { now = Date.now() } = {}) {
+  if (!isObject(state)) return false;
+  if (state.restartPhase == null) return false;
+  state.restartPhase = null;
+  state.updatedAt = isFiniteNumber(now) ? now : Date.now();
+  return true;
+}
+
 /**
  * Normalize the record of the one-time questions.
  *
@@ -634,6 +781,12 @@ export function normalizeState(raw, now = Date.now()) {
   if (typeof raw.phase === 'string' && PHASES.includes(raw.phase)) state.phase = raw.phase;
   else if (raw.phase != null) repaired = true;
 
+  if (raw.restartPhase != null) {
+    const recorded = normalizeRestartPhase(raw.restartPhase, now);
+    state.restartPhase = recorded.record;
+    if (recorded.changed) repaired = true;
+  }
+
   if (isFiniteNumber(raw.updatedAt)) state.updatedAt = raw.updatedAt;
   else if (raw.updatedAt != null) repaired = true;
 

package/lib/diagnostics.js

@@ -181,6 +181,24 @@ export function buildDiagnostics(payload = {}) {
   lines.push('watchdog available: ' + (field(watchdog, 'available', false) === true ? 'yes' : 'no'))
   lines.push('watchdog last result: ' + redactSecrets(field(watchdogReport, 'result', 'never ran')))
   lines.push('watchdog last tier: ' + redactSecrets(field(watchdogReport, 'tier', 'unknown')))
+  // THE DISARM: did the host stand the watchdog down? A failed disarm leaves an
+  // armed one behind (the 0.8.1 incident), so its outcome and the first error
+  // belong in the text the user can hand to us.
+  const disarm = field(source, 'watchdogDisarm', null)
+  if (disarm && typeof disarm === 'object') {
+    lines.push('watchdog disarm: ' + (field(disarm, 'ok', false) === true ? 'ok' : 'FAILED'))
+    lines.push('watchdog disarm source: ' + redactSecrets(field(disarm, 'source', 'unknown')))
+    lines.push('watchdog disarm attempts: ' + redactSecrets(String(field(disarm, 'attempts', 0))))
+    lines.push('watchdog disarm pending left: ' + (field(disarm, 'pending', false) === true ? 'yes' : 'no'))
+    const disarmError = field(disarm, 'error', null)
+    if (disarmError && typeof disarmError === 'object') {
+      lines.push('watchdog disarm error: '
+        + redactSecrets(field(disarmError, 'name', 'error'))
+        + ': ' + redactSecrets(field(disarmError, 'message', '')))
+    }
+  } else {
+    lines.push('watchdog disarm: never ran')
+  }
   const stateDir = truncatePath(field(source, 'stateDir', ''))
   if (stateDir !== '') lines.push('dsh home: ' + redactSecrets(stateDir))
   lines.push('--- end ---')