dsh-autorestart 0.6.2 → 0.7.0

package/lib/access.js

@@ -0,0 +1,212 @@
+/**
+ * dsh-autorestart — the instance record: how the running host can be reached.
+ *
+ * TWO facts make this file necessary:
+ *
+ *   1. The web server of the desktop app listens on a RANDOM port (`--port 0`),
+ *      so the port of the PREVIOUS instance is worthless for the next one. The
+ *      port of the new instance is only known to the new instance itself — so
+ *      the new instance has to publish it, and the rollback watcher has to read
+ *      it instead of guessing.
+ *   2. The boot token of `dsh web` is created PER PROCESS. After a restart the
+ *      old access link answers 401, so the user is locked out of their own
+ *      interface until somebody hands them the new link. The new instance knows
+ *      its own link (the host's connection service signs it), so the new
+ *      instance writes it down — into a file only the user can read.
+ *
+ * The record is ONE small JSON file in the state directory:
+ *
+ *   { "bootId": "…", "pid": 1234, "port": 55537, "url": "http://…/?token=…",
+ *     "token": "…", "at": 1730000000000 }
+ *
+ * `bootId` is what tells "the new instance" from "the old one": the plugin
+ * generates a new one on every boot, so a watcher can wait for the change
+ * instead of guessing from a port.
+ *
+ * The file holds a SECRET (the boot token), so it is written with the
+ * restrictive mode 0600. On POSIX that is enforced by the kernel; on Windows
+ * the mode is advisory, so the file inherits the ACL of the (per-user) state
+ * directory — which is why the token is never written anywhere else in
+ * readable form.
+ *
+ * ESM only, Node builtins only. No DSH / npm imports.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** The name of the instance record inside the state directory. */
+export const ACCESS_FILE_NAME = 'access.json';
+
+/** The mode the instance record is written with: readable by its owner only. */
+export const ACCESS_FILE_MODE = 0o600;
+
+/** @param {unknown} value */
+function errorText(value) {
+  if (value && typeof value.message === 'string' && value.message) return value.message;
+  return String(value);
+}
+
+/**
+ * The path of the instance record that belongs to a state directory.
+ *
+ * @param {string} stateDir
+ * @returns {string}
+ */
+export function accessFilePath(stateDir) {
+  return path.join(String(stateDir ?? ''), ACCESS_FILE_NAME);
+}
+
+/**
+ * The access link of the running instance, with its boot token when the host's
+ * connection service can sign one.
+ *
+ * The connection service is optional: a host that does not provide it still
+ * gets the plain origin, so the record is always written.
+ *
+ * @param {{ origin?: string, connection?: any }} options
+ * @returns {{ url: string|null, token: string|null }}
+ */
+export function resolveAccessUrl({ origin = '', connection = null } = {}) {
+  const base = typeof origin === 'string' ? origin.trim().replace(/\/+$/, '') : '';
+  if (base === '') return { url: null, token: null };
+  let url = base + '/';
+  let token = null;
+  try {
+    if (connection && typeof connection.authenticatedUrl === 'function') {
+      const signed = connection.authenticatedUrl(base);
+      if (typeof signed === 'string' && signed.trim() !== '') {
+        url = signed.trim();
+        try {
+          const parsed = new URL(url);
+          token = parsed.searchParams.get('token');
+        } catch {
+          token = null;
+        }
+      }
+    }
+  } catch {
+    // A connection service that throws must not cost us the plain origin.
+    url = base + '/';
+    token = null;
+  }
+  return { url, token };
+}
+
+/**
+ * Write the instance record.
+ *
+ * The write is atomic (a temporary file + a rename), so a reader never sees a
+ * half-written record, and the mode is restricted to the owner.
+ *
+ * @param {{
+ *   stateDir?: string,
+ *   bootId?: string|null,
+ *   pid?: number|null,
+ *   port?: number|null,
+ *   url?: string|null,
+ *   token?: string|null,
+ *   now?: number,
+ * }} [options]
+ * @returns {{ ok: boolean, path: string|null, record: object|null, error: string|null }}
+ */
+export function writeAccessRecord({
+  stateDir = '',
+  bootId = null,
+  pid = null,
+  port = null,
+  url = null,
+  token = null,
+  now = Date.now(),
+} = {}) {
+  const dir = typeof stateDir === 'string' ? stateDir.trim() : '';
+  if (dir === '') {
+    return { ok: false, path: null, record: null, error: 'writeAccessRecord requires stateDir' };
+  }
+  const file = accessFilePath(dir);
+  const record = {
+    bootId: typeof bootId === 'string' && bootId !== '' ? bootId : null,
+    pid: Number.isFinite(Number(pid)) ? Number(pid) : null,
+    port: Number.isFinite(Number(port)) ? Number(port) : null,
+    url: typeof url === 'string' && url !== '' ? url : null,
+    token: typeof token === 'string' && token !== '' ? token : null,
+    at: Number.isFinite(Number(now)) ? Number(now) : Date.now(),
+  };
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    const temporary = file + '.tmp';
+    fs.writeFileSync(temporary, JSON.stringify(record, null, 2) + '\n', {
+      encoding: 'utf8',
+      mode: ACCESS_FILE_MODE,
+    });
+    // `writeFileSync` only applies the mode when it CREATES the file, so the
+    // permission is set explicitly as well (and after the rename, because the
+    // rename keeps the mode of the source anyway).
+    try {
+      fs.chmodSync(temporary, ACCESS_FILE_MODE);
+    } catch {
+      /* the mode is advisory on some platforms */
+    }
+    fs.renameSync(temporary, file);
+    try {
+      fs.chmodSync(file, ACCESS_FILE_MODE);
+    } catch {
+      /* the mode is advisory on some platforms */
+    }
+    return { ok: true, path: file, record, error: null };
+  } catch (error) {
+    return { ok: false, path: file, record, error: 'could not write the instance record: ' + errorText(error) };
+  }
+}
+
+/**
+ * Read the instance record from a file path.
+ *
+ * @param {string} file
+ * @returns {{ ok: boolean, record: object|null, error: string|null }}
+ */
+export function readAccessRecordFile(file) {
+  const target = typeof file === 'string' ? file.trim() : '';
+  if (target === '') return { ok: false, record: null, error: 'readAccessRecordFile requires a path' };
+  try {
+    const text = fs.readFileSync(target, 'utf8');
+    if (text.charCodeAt(0) === 0xfeff) {
+      const parsed = JSON.parse(text.slice(1));
+      return { ok: true, record: parsed && typeof parsed === 'object' ? parsed : null, error: null };
+    }
+    const parsed = JSON.parse(text);
+    return { ok: true, record: parsed && typeof parsed === 'object' ? parsed : null, error: null };
+  } catch (error) {
+    return { ok: false, record: null, error: errorText(error) };
+  }
+}
+
+/**
+ * Read the instance record of a state directory.
+ *
+ * @param {string} stateDir
+ * @returns {{ ok: boolean, record: object|null, error: string|null }}
+ */
+export function readAccessRecord(stateDir) {
+  const dir = typeof stateDir === 'string' ? stateDir.trim() : '';
+  if (dir === '') return { ok: false, record: null, error: 'readAccessRecord requires stateDir' };
+  return readAccessRecordFile(accessFilePath(dir));
+}
+
+/**
+ * Remove the instance record (used when a restart is armed, so a stale record
+ * of a dead instance is never mistaken for a live one).
+ *
+ * @param {string} stateDir
+ * @returns {boolean} whether a record was removed
+ */
+export function clearAccessRecord(stateDir) {
+  const dir = typeof stateDir === 'string' ? stateDir.trim() : '';
+  if (dir === '') return false;
+  try {
+    fs.rmSync(accessFilePath(dir), { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/lib/autostart-advice.js

@@ -0,0 +1,198 @@
+/**
+ * dsh-autorestart — THE "START AT LOGIN" GUIDE OF EVERY PLATFORM.
+ *
+ * A hosted web host can be started in a dozen ways, and "start at login" means
+ * something different on every platform. The plugin therefore hands out ONE
+ * piece of advice per platform, and it always says what the record really is:
+ *
+ *   | platform              | what the plugin does                                      |
+ *   |-----------------------|----------------------------------------------------------|
+ *   | Windows               | a scheduled task (`/SC ONLOGON /RL LIMITED`, no admin); when the machine refuses it, a `.cmd` in the startup folder. The command is a REAL node + supervisor.js — never the app executable. |
+ *   | Linux (not WSL)       | a systemd USER service (`systemctl --user`, no admin) — plus the `loginctl enable-linger` hint, because without the linger it only starts after a login. |
+ *   | WSL with systemd      | the same systemd user unit, plus the linger hint.         |
+ *   | WSL without systemd   | NO "at login" at all: two ways out (turn systemd on inside WSL, or let Windows start the distribution). NEVER Docker/Compose. |
+ *   | container / k8s       | no promise at all: the orchestrator brings it back (compose `restart: always`). |
+ *   | unknown               | nothing is installed and nothing is guessed: the user is told why and asked to choose. |
+ *
+ * The advice is a pure function of its input, so every branch is testable
+ * without a machine.
+ *
+ * ESM only, Node builtins only.
+ */
+
+import { HOST_KINDS } from './host-kind.js'
+
+/** The kinds of the advice (one per platform). */
+export const AUTOSTART_ADVICE_KINDS = Object.freeze({
+  /** Windows: a scheduled task (with the startup folder as the fallback). */
+  WINDOWS: 'windows-task',
+  /** Linux: a systemd user service (+ the linger hint). */
+  LINUX: 'linux-systemd',
+  /** WSL with systemd: the same, and the linger is the missing piece. */
+  WSL_SYSTEMD: 'wsl-systemd',
+  /** WSL without systemd: the user has to pick one of two ways. */
+  WSL_MANUAL: 'wsl-manual',
+  /** A container: the orchestrator decides. */
+  CONTAINER: 'container',
+  /** Nobody can tell: nothing is installed, nothing is guessed. */
+  UNKNOWN: 'unknown',
+})
+
+/** @param {unknown} value */
+function text(value) {
+  return typeof value === 'string' ? value.trim() : ''
+}
+
+/**
+ * The advice of one platform.
+ *
+ * @param {{
+ *   host?: { kind?: string, suspect?: boolean, distro?: string, evidence?: string },
+ *   platform?: string,
+ *   hasSystemd?: boolean,
+ *   container?: boolean,
+ *   user?: string,
+ *   distro?: string,
+ *   startCommand?: string,
+ *   command?: string,
+ * }} [options]
+ * @returns {{
+ *   kind: string,
+ *   reason: string,
+ *   notes: string[],
+ *   commands: string[],
+ *   options: Array<{ id: string, label: string, command: string, cost: string, recommended: boolean }>,
+ *   canInstall: boolean,
+ * }}
+ */
+export function planAutostartAdvice(options = {}) {
+  const host = options.host && typeof options.host === 'object' ? options.host : {}
+  const platform = text(options.platform) || text(host.platform) || process.platform
+  const kind = text(host.kind)
+  const suspect = host.suspect === true
+  const user = text(options.user) || text(process.env.USER) || text(process.env.LOGNAME) || '你的用户名'
+  const distro = text(options.distro) || text(host.distro) || '你的发行版'
+  const startCommand = text(options.startCommand)
+  const command = text(options.command)
+  const hasSystemd = options.hasSystemd === true
+  const isContainer = options.container === true
+
+  // A host that is only GUESSED to be WSL (the mounted Windows drive is the
+  // only evidence) gets no automatic anything: the plugin says so and leaves
+  // the choice to the user.
+  const suspectNote = suspect
+    ? '没把握：这台机器只是「挂载了 Windows 盘」才被猜成 WSL，插件不会替你改任何系统配置，建议你手动选一条。'
+    : ''
+
+  const linger = 'loginctl enable-linger ' + user
+
+  // (1) A CONTAINER. The orchestrator brings it back — there is no "at login".
+  if (isContainer) {
+    return {
+      kind: AUTOSTART_ADVICE_KINDS.CONTAINER,
+      reason: '容器里没有「开机自启」这回事：由编排器负责（compose 的 restart: always / k8s 的 restartPolicy）。',
+      notes: [
+        '容器里没有「开机自启」这回事：由编排器负责（compose 的 restart: always / k8s 的 restartPolicy）。',
+        '插件不会在容器里装 systemd —— 容器里也没有 systemd 可装。',
+      ],
+      commands: [],
+      options: [],
+      canInstall: false,
+    }
+  }
+
+  // (2) WINDOWS. The scheduled task first, the startup folder as the fallback.
+  if (kind === HOST_KINDS.WINDOWS || platform === 'win32') {
+    return {
+      kind: AUTOSTART_ADVICE_KINDS.WINDOWS,
+      reason: 'Windows 托管端：登录时自启用**计划任务**（/SC ONLOGON /RL LIMITED，不需要管理员）；这台机器若不允许普通用户建计划任务，会自动降级到「启动文件夹」里的一个 .cmd（同样不需要管理员）。注册的命令是**真正的 node + supervisor.js**，不是 DSH 客户端本体。',
+      notes: [
+        '登录时自启：计划任务（/SC ONLOGON /RL LIMITED，零管理员权限）。',
+        '这台机器拒绝计划任务时自动降级为「启动文件夹」里的 .cmd（同样零权限）。',
+        '注册的命令是真正的 node + supervisor.js —— 绝不会用 DSH 客户端本体去跑守护脚本（那会在每次登录时再开一个 DSH）。',
+      ],
+      commands: command === '' ? [] : [command],
+      options: [],
+      canInstall: true,
+    }
+  }
+
+  // (3) WSL. With systemd it is a user unit (+ the linger); without it there
+  // is no "at login" at all — and NEVER a Docker answer.
+  if (kind === HOST_KINDS.WSL) {
+    if (hasSystemd) {
+      return {
+        kind: AUTOSTART_ADVICE_KINDS.WSL_SYSTEMD,
+        reason: 'WSL 里有 systemd：守护装成 systemd 用户单元（登录后自启）。'
+          + '若要「开机自启」（不必先登录），在 WSL 里运行一次：' + linger
+          + (suspectNote !== '' ? suspectNote : ''),
+        notes: [
+          'WSL 里有 systemd：守护装成 systemd 用户单元（登录后自启）。',
+          '若要「开机自启」（不必先登录），在 WSL 里运行一次：' + linger
+            + '（只需一次；linger 让 systemd 在你没登录时也把这个用户的服务拉起来）。',
+        ],
+        commands: [linger],
+        options: [],
+        canInstall: true,
+      }
+    }
+    const systemdOption = {
+      id: 'wsl-systemd-enable',
+      label: '① 在 WSL 内部开启 systemd',
+      command: '在 /etc/wsl.conf 里加上 [boot] systemd=true，然后在 Windows 侧运行 wsl --shutdown 重启子系统',
+      cost: '这是系统配置改动：要改发行版里的 /etc/wsl.conf，并且要重启整个 WSL 子系统（别的发行版和正在跑的进程会一起停）。',
+      recommended: false,
+    }
+    const windowsOption = {
+      id: 'wsl-windows-task',
+      label: '② 在 Windows 侧用计划任务 / 启动文件夹拉起 WSL',
+      command: 'wsl.exe -d ' + distro + ' -e ' + (startCommand !== '' ? startCommand : '<启动命令>'),
+      cost: '需要 Windows 侧操作（新建一条计划任务，或往启动文件夹放一个快捷方式），但更接近真正的开机自启。',
+      recommended: true,
+    }
+    return {
+      kind: AUTOSTART_ADVICE_KINDS.WSL_MANUAL,
+      reason: 'WSL 里没有 systemd：这里没有「登录时自启」这回事。'
+        + '两条路（插件不会替你改任何系统配置）：① 在 WSL 内部开启 systemd；② 在 Windows 侧用计划任务/启动文件夹拉起 WSL（推荐）。'
+        + (suspectNote !== '' ? suspectNote : ''),
+      notes: [
+        'WSL 里没有 systemd：这里没有「登录时自启」这回事，所以插件不装任何东西。',
+        suspectNote !== '' ? suspectNote : '插件不会替你改任何系统配置，两条路都需要你自己动手。',
+        '① 在 WSL 内部开启 systemd —— 这是系统配置改动（改 /etc/wsl.conf + 重启子系统）。',
+        '② 在 Windows 侧用计划任务 / 启动文件夹拉起 WSL（推荐）—— 需要 Windows 侧操作，但更接近真正的开机自启。',
+      ],
+      commands: [windowsOption.command],
+      options: [systemdOption, windowsOption],
+      canInstall: false,
+    }
+  }
+
+  // (4) LINUX (and every other real Linux): a systemd user service, and the
+  // linger that turns "after a login" into "at boot".
+  if (kind === HOST_KINDS.LINUX || platform === 'linux') {
+    return {
+      kind: AUTOSTART_ADVICE_KINDS.LINUX,
+      reason: 'Linux 托管端：用 systemd 用户服务（systemctl --user，不需要管理员）。这是「登录后自启」；若要「开机自启」（不必先登录），运行一次 ' + linger + '。',
+      notes: [
+        'systemd 用户服务：登录后自启（零管理员权限）。',
+        '若要「开机自启」（不必先登录），运行一次：' + linger + '（只需一次；没有 linger 就只是登录后自启）。',
+      ],
+      commands: [linger],
+      options: [],
+      canInstall: true,
+    }
+  }
+
+  // (5) UNKNOWN. Nothing is installed, nothing is guessed.
+  return {
+    kind: AUTOSTART_ADVICE_KINDS.UNKNOWN,
+    reason: '认不出这个宿主是怎么被拉起来的：插件不装任何东西，也不猜命令。请你手动选一条（或告诉插件该怎么拉起它）。',
+    notes: [
+      '认不出这个宿主是怎么被拉起来的：插件不装任何东西，也不猜命令。',
+      '这是「宁可说不知道，也不双开」的保守做法 —— 请你手动选一条。',
+    ],
+    commands: [],
+    options: [],
+    canInstall: false,
+  }
+}

package/lib/backup.js

@@ -37,9 +37,87 @@ export const DEFAULT_MAX_BACKUPS = 2;
 /** The report the detached helper writes when it rolls a backup back. */
 export const ROLLBACK_REPORT_NAME = 'last-rollback.json';
 
+/** The lock that makes sure a snapshot is restored ONCE. */
+export const ROLLBACK_LOCK_NAME = 'rollback.lock';
+
+/**
+ * Claim the right to restore the snapshot.
+ *
+ * TWO parties can want to restore the snapshot at the same time: the plugin
+ * itself (it saw that the restart failed) and the detached watcher (the host
+ * never came back). Both copy the same files over the profile — two copies at
+ * once would write the same files at the same time, and the plugin tree is
+ * 117 MB.
+ *
+ * The claim is atomic: the file is CREATED, never opened, so exactly ONE
+ * caller gets it. The loser stands down.
+ *
+ * @param {string} stateDir
+ * @returns {{ ok: boolean, path: string, error: string|null }}
+ */
+export function claimRollbackLock(stateDir) {
+  const dir = typeof stateDir === 'string' ? stateDir.trim() : '';
+  if (dir === '') return { ok: false, path: '', error: 'claimRollbackLock requires stateDir' };
+  const file = path.join(dir, ROLLBACK_LOCK_NAME);
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch {
+    /* the directory may already be there */
+  }
+  // A lock that is older than 10 minutes belongs to a process that died in the
+  // middle of its restore: it must not block the rollback for ever.
+  try {
+    const stat = fs.statSync(file);
+    if (Date.now() - stat.mtimeMs > 10 * 60 * 1000) {
+      fs.rmSync(file, { force: true });
+    }
+  } catch {
+    /* no lock there: nothing to clean up */
+  }
+  try {
+    const handle = fs.openSync(file, 'wx');
+    try {
+      fs.writeFileSync(handle, String(process.pid ?? ''), 'utf8');
+    } catch {
+      /* the owner is what matters, not the note inside the file */
+    }
+    try {
+      fs.closeSync(handle);
+    } catch {
+      /* nothing else to do */
+    }
+    return { ok: true, path: file, error: null };
+  } catch {
+    return { ok: false, path: file, error: 'another rollback is already running' };
+  }
+}
+
+/**
+ * Release the rollback lock.
+ *
+ * @param {string} stateDir
+ * @returns {boolean} whether a lock was removed
+ */
+export function releaseRollbackLock(stateDir) {
+  const dir = typeof stateDir === 'string' ? stateDir.trim() : '';
+  if (dir === '') return false;
+  try {
+    fs.rmSync(path.join(dir, ROLLBACK_LOCK_NAME), { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * A filesystem-safe timestamp for a backup directory name.
  *
+ * The name is in UTC on purpose: it sorts chronologically and it does not
+ * depend on the timezone of the machine. The price is that it does NOT look
+ * like the wall clock the operator reads (`2026-10-29T00-25-20-779Z` is
+ * 08:25 in Shanghai) — so the manifest and the restart record carry the local
+ * time as well, and a fresh snapshot can never be mistaken for an old one.
+ *
  * @param {number} [now]
  * @returns {string}
  */
@@ -48,6 +126,26 @@ export function backupStamp(now = Date.now()) {
   return date.toISOString().replace(/[:.]/g, '-');
 }
 
+/**
+ * The local time of an epoch, with the UTC offset (`2026-10-29T08:25:20+08:00`).
+ *
+ * @param {number|null|undefined} at
+ * @returns {string|null}
+ */
+export function backupLocalTime(at) {
+  const value = Number(at);
+  if (!Number.isFinite(value)) return null;
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return null;
+  const offsetMinutes = -date.getTimezoneOffset();
+  const sign = offsetMinutes >= 0 ? '+' : '-';
+  const absolute = Math.abs(offsetMinutes);
+  const hours = String(Math.floor(absolute / 60)).padStart(2, '0');
+  const minutes = String(absolute % 60).padStart(2, '0');
+  const local = new Date(value + offsetMinutes * 60000).toISOString();
+  return `${local.slice(0, 19)}${sign}${hours}:${minutes}`;
+}
+
 /**
  * The backups directory that belongs to a state directory.
  *
@@ -142,8 +240,12 @@ export function pruneBackups(backupsDir, maxBackups = DEFAULT_MAX_BACKUPS) {
 /**
  * List the backups, newest first.
  *
+ * Only the DIRECTORY is read: the name, the manifest and nothing else. The
+ * backup tree can be 150 MB per copy, so its contents are never walked — the
+ * manifest already carries the size, the file count and the local time.
+ *
  * @param {string} backupsDir
- * @returns {Array<{name: string, dir: string, at: number|null, bytes: number|null, includePlugins: boolean}>}
+ * @returns {Array<{name: string, dir: string, at: number|null, atLocal: string|null, bytes: number|null, files: number|null, includePlugins: boolean}>}
  */
 export function listBackups(backupsDir) {
   let names;
@@ -158,11 +260,18 @@ export function listBackups(backupsDir) {
   for (const name of names.sort().reverse()) {
     const dir = path.join(backupsDir, name);
     const manifest = readManifest(dir);
+    const at = manifest && Number.isFinite(manifest.at) ? manifest.at : null;
     out.push({
       name,
       dir,
-      at: manifest && Number.isFinite(manifest.at) ? manifest.at : null,
+      at,
+      // The local time of the snapshot. The directory name is UTC on purpose,
+      // so a fresh snapshot must never look like an old one.
+      atLocal: manifest && typeof manifest.atLocal === 'string' && manifest.atLocal !== ''
+        ? manifest.atLocal
+        : (at === null ? null : backupLocalTime(at)),
       bytes: manifest && Number.isFinite(manifest.bytes) ? manifest.bytes : null,
+      files: manifest && Array.isArray(manifest.files) ? manifest.files.length : null,
       includePlugins: Boolean(manifest && manifest.includePlugins === true),
     });
   }
@@ -202,7 +311,7 @@ export function readManifest(backupDir) {
  *   maxBackups?: number,
  *   now?: number,
  * }} options
- * @returns {{ ok: boolean, dir: string|null, stamp: string|null, bytes: number, files: string[], includePlugins: boolean, pruned: string[], error: string|null }}
+ * @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 }}
  */
 export function createBackup({
   profileDir,
@@ -213,10 +322,14 @@ export function createBackup({
 } = {}) {
   const profile = typeof profileDir === 'string' ? profileDir.trim() : '';
   const root = typeof backupsDir === 'string' ? backupsDir.trim() : '';
+  const startedAt = Date.now();
   const base = {
     ok: false,
     dir: null,
     stamp: null,
+    at: null,
+    atLocal: null,
+    durationMs: 0,
     bytes: 0,
     files: [],
     includePlugins: includePlugins === true,
@@ -261,6 +374,9 @@ export function createBackup({
   const manifest = {
     stamp,
     at: Number(now),
+    // The wall clock of the machine: the directory name above is UTC, and
+    // without this line a fresh snapshot looks like an old leftover.
+    atLocal: backupLocalTime(Number(now)),
     profileDir: profile,
     includePlugins: includePlugins === true,
     files,
@@ -273,7 +389,18 @@ export function createBackup({
   }
 
   const pruned = pruneBackups(root, maxBackups);
-  return { ...base, ok: true, dir, stamp, bytes, files, pruned };
+  return {
+    ...base,
+    ok: true,
+    dir,
+    stamp,
+    at: Number(now),
+    atLocal: manifest.atLocal,
+    durationMs: Math.max(0, Date.now() - startedAt),
+    bytes,
+    files,
+    pruned,
+  };
 }
 
 /**