dsh-autorestart 0.3.3 → 0.3.4

package/README.md

@@ -29,13 +29,34 @@ round starts, so the session goes idle and the restart can proceed. The goal is
 restart and continues.
 
 The browser shows the state: a compact "pending restart" pill on the left side of the input toolbar
-and a small dot next to the session title in the sidebar. The pill can be clicked for details, and
-the dot breathes when the restart is about to fire.
+and a small dot next to the session title in the sidebar. The pill's text reports how many
+conversations are still in the way (counted once per conversation, and the tooltip explains that a
+conversation with queued-but-not-started work counts too); it does not open a details panel. The dot
+breathes when the restart is about to fire.
+
+Before every restart the plugin snapshots the profile, so a restart that leaves the host unable to
+boot is rolled back automatically — see
+[Pre-restart backup and automatic rollback](#pre-restart-backup-and-automatic-rollback).
 
 Two safety gates protect the restart. The host checks that no conversation is busy, and the detached
 helper checks the same gate over loopback immediately before it kills the process, so a turn that
 starts in between is never killed.
 
+## What it occupies in DSH
+
+Nothing here is hidden: this is the complete list of where the plugin attaches itself, so you can see
+what it adds before you install it.
+
+| Kind | What it adds |
+| --- | --- |
+| Agent tools (6) | `continuum_restart`, `continuum_status`, `continuum_cancel_restart`, `continuum_park_goal`, `continuum_recover_now`, `continuum_handoff` |
+| HTTP routes (4) | Under `<healthPath>` (default `/__dsh_autorestart`): `GET /health` (also `?state=1`, `?gate=1`, `?probeIndex=1`), `POST /park`, `POST /recover`, `POST /handoff`. Loopback or an authenticated browser only |
+| Client slots (2) | `conversation.input.left` — the pending-restart pill (`autorestart-restart-pill`); `sidebar.session.row.leading` — the session status dot (`autorestart-restart-dot`) |
+| System prompt | One "Restart policy" section that tells the agent how to ask for a restart and what the plugin will do |
+| Harness hooks | `agent/status` (tracks which conversations are busy), `tools/pre-execute` (blocks a shell command that would kill or relaunch DSH by hand), and the boot pass that resumes interrupted sessions |
+| Profile row | One bundle row, `dsh-autorestart` |
+| Writes | Only under `<DSH_HOME>/storages/dsh-autorestart/` — `state.json` (checkpoint), `backups/` (pre-restart snapshots), `restart-<gen>.cmd` / `restart-<gen>-watch.ps1` (the detached helper), `last-rollback.json` (rollback report). The only time it writes into the profile itself is a rollback, which copies that snapshot's `cordis.patch.yml`, `package.json`, `pnpm-lock.yaml` and `node_modules` back |
+
 ## Why
 
 | Situation | Without it | With it |
@@ -116,6 +137,10 @@ show up in the Plugin Manager and in the config editor.
 | `blockManualRestart` | `true` | Hard-block an agent that tries to kill or restart DSH with a shell command, and point it at `continuum_restart` instead. |
 | `healthPath` | `/__dsh_autorestart/health` | Health check route. Returns the boot id, the pid, the phase and the self-check flags. |
 | `continuationText` | `''` | Overrides the default continuation prompt text. |
+| `backupOnRestart` | `true` | Snapshot the profile before every restart, so a restart that leaves the host unable to boot can be rolled back. |
+| `backupIncludePlugins` | `true` | Include the installed plugin tree in that snapshot (about 117 MB here, ~3 s). `false` keeps only the configuration files. |
+| `maxBackups` | `2` | How many snapshots are kept; older ones are deleted when a new one is written. |
+| `rollbackTimeoutMs` | `90000` | How long the detached watcher waits for the relaunched host before it restores the snapshot and launches the host again. |
 
 The two waits are independent of each other, and both default to two seconds:
 
@@ -141,6 +166,35 @@ restart command of its own:
 
 Remember that this replaces the whole config instead of merging into it.
 
+## Pre-restart backup and automatic rollback
+
+A restart is only safe if the host comes back. Before every restart the plugin snapshots the profile
+it was started from, so a restart that leaves the host unable to boot can be undone automatically.
+
+- **What is backed up:** `cordis.patch.yml`, `package.json` and `pnpm-lock.yaml`, plus — unless
+  `backupIncludePlugins` is turned off — the installed plugin tree (`node_modules`). Snapshots live in
+  `<storage>/dsh-autorestart/backups/<timestamp>/` with a `manifest.json` next to them. On a profile
+  like this one the full snapshot measures about 117 MB and takes under three seconds.
+- **How many are kept:** the newest `maxBackups` snapshots (default `2`); older ones are deleted when
+  a new one is written.
+- **How a failed boot is detected:** the detached helper that kills and relaunches the host also runs
+  a small PowerShell watcher. It polls the health route for `rollbackTimeoutMs` (default `90000`). A
+  healthy answer ends the watch and nothing is touched.
+- **What happens when the host never answers:** the watcher copies the snapshot back over the profile
+  (configuration files, and the plugin tree when the snapshot holds one), writes
+  `last-rollback.json` next to the checkpoint — including the tail of the newest crash log written
+  *after* this restart — and launches the host again with the restored configuration.
+- **How you learn about it:** the next boot reports it. `continuum_status` gains a `lastRollback`
+  object (`at`, `waitedMs`, `rolledBack`, `backupDir`, `crashLog`, `crashTail`), and the next restart
+  clears the report so it is never mistaken for a fresh one.
+- **Turning it off:** `backupOnRestart: false` skips the snapshot entirely (no rollback point, and no
+  watcher), which is what a user who keeps their own backups may prefer. `backupIncludePlugins:
+  false` keeps the snapshot but limits it to the configuration files.
+
+The rollback is deliberately conservative: it only runs when the relaunched host never answers its
+own health route. A slow start inside `rollbackTimeoutMs` is never treated as a failure, and a
+healthy host is never touched.
+
 ## Requirements and limits
 
 - **Windows desktop.** `restartMode: app` restarts the DSH desktop app on Windows. Any other

package/cordis.patch.yml

@@ -31,3 +31,14 @@
         blockManualRestart: true
         healthPath: /__dsh_autorestart/health
         continuationText: ''
+        # Take a snapshot of the profile before every restart, so a restart that
+        # leaves the host unable to boot can be rolled back automatically.
+        backupOnRestart: true
+        # Include the installed plugin tree in that snapshot (bigger: ~120 MB here,
+        # but it is what lets a rollback undo "a plugin upgrade broke the boot").
+        backupIncludePlugins: true
+        # Keep at most this many snapshots; older ones are deleted automatically.
+        maxBackups: 2
+        # How long the detached watcher waits for the relaunched host (ms) before
+        # it restores the snapshot and launches the host again.
+        rollbackTimeoutMs: 90000

package/docs/README.zh.md

@@ -48,6 +48,29 @@ session resume on boot, durable-goal re-arm, and an agent-callable idle-aware gr
 
 ---
 
+## 占用 DSH 的哪些位置（安装前请先看一眼）
+
+下面就是它动到的全部位置，没有别的：
+
+| 类型 | 具体占用 |
+| --- | --- |
+| Agent 工具（6 个） | `continuum_restart`、`continuum_status`、`continuum_cancel_restart`、`continuum_park_goal`、`continuum_recover_now`、`continuum_handoff` |
+| HTTP 路由（4 条） | `<healthPath>`（默认 `/__dsh_autorestart`）下的 `GET /health`（另有 `?state=1`、`?gate=1`、`?probeIndex=1`）、`POST /park`、`POST /recover`、`POST /handoff`；只接受本机回环或已认证的浏览器 |
+| 前端槽位（2 个） | `conversation.input.left`（待重启小胶囊，id `autorestart-restart-pill`）、`sidebar.session.row.leading`（侧栏状态圆点，id `autorestart-restart-dot`） |
+| 系统提示词 | 一段「重启政策」说明，告诉 agent 怎么请求重启、插件会做什么 |
+| 宿主事件 | `agent/status`（跟踪哪些会话在忙）、`tools/pre-execute`（拦下"手动杀/重启 DSH"的 shell 命令）、启动时的恢复流程 |
+| profile 行 | 一条 bundle 行：`dsh-autorestart` |
+| 写文件 | 只在 `<DSH_HOME>/storages/dsh-autorestart/` 下写：`state.json`（检查点）、`backups/`（重启前快照）、`restart-<代次>.cmd` / `restart-<代次>-watch.ps1`（脱离进程的重启 helper）、`last-rollback.json`（回退报告）。唯一会写进 profile 的时机是**回退**：把快照里的 `cordis.patch.yml`、`package.json`、`pnpm-lock.yaml` 和 `node_modules` 拷回去 |
+
+## 重启前备份与自动回退
+
+- **每次重启前**先给 profile 拍快照：`cordis.patch.yml`、`package.json`、`pnpm-lock.yaml`，以及（默认开启）已安装插件目录 `node_modules`。本机实测：**2.76 秒 / 117.6 MB / 5,562 个文件**。
+- 快照放在 `storages/dsh-autorestart/backups/<时间戳>/`，带 `manifest.json`；**只保留最新 2 份**，写新快照时自动删旧的。
+- 重启后 helper 会跑一个隐藏的看护脚本，轮询健康端点 **90 秒**（`rollbackTimeoutMs`）：正常回答就静默退出，**什么都不动**。
+- 宿主**一直不回应**时：把快照拷回去 → 写 `last-rollback.json`（含"本次重启之后"的崩溃日志尾部，旧日志不会被误当证据）→ **自动再拉起一次**。
+- 下次启动时 `continuum_status` 会报 `lastRollback`（时间、等了多久、是否回滚、快照路径、崩溃日志名与尾部摘要）。
+- 开关：`backupOnRestart`（默认 `true`）、`backupIncludePlugins`（默认 `true`，关掉就只备配置文件）、`maxBackups`（默认 `2`）、`rollbackTimeoutMs`（默认 `90000`）。
+
 ## 工作方式
 
 ```

package/index.js

@@ -19,6 +19,7 @@
  */
 
 import crypto from 'node:crypto'
+import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 
@@ -57,8 +58,17 @@ import {
   restartGate,
   selectGoalDisarms,
 } from './lib/lifecycle.js'
+import {
+  backupsRoot,
+  clearRollbackReport,
+  createBackup,
+  readRollbackReport,
+  ROLLBACK_REPORT_NAME,
+} from './lib/backup.js'
 import {
   buildCustomCommand,
+  buildWatchScript,
+  DEFAULT_ROLLBACK_TIMEOUT_MS,
   detectEnvironment,
   runCommandNow,
   scheduleDetachedRestart,
@@ -196,6 +206,13 @@ function buildConfigSchema() {
       recoveryBatchDelayMs: schemastery.number().min(0).default(1200),
       // pause between two resolveAgent attempts inside one boot
       resumeRetryDelayMs: schemastery.number().min(0).default(1000),
+      // pre-restart snapshot + automatic rollback when the host never comes back
+      backupOnRestart: schemastery.boolean().default(true),
+      // include the installed plugin tree in the snapshot (bigger, but it makes a
+      // rollback of "a plugin upgrade broke the boot" possible)
+      backupIncludePlugins: schemastery.boolean().default(true),
+      maxBackups: schemastery.number().step(1).min(1).default(2),
+      rollbackTimeoutMs: schemastery.number().min(1000).default(90000),
     })
   } catch (error) {
     schemasterySource = `construction-failed: ${String(error)}`
@@ -227,6 +244,14 @@ const DEFAULTS = {
   blockManualRestart: true,
   healthPath: '/__dsh_autorestart/health',
   continuationText: '',
+  // Pre-restart snapshot + automatic rollback. The plugin copies the profile
+  // configuration (and, unless disabled, the installed plugin tree) before every
+  // restart; when the relaunched host never answers its health route, the
+  // detached watcher puts the snapshot back and launches the host again.
+  backupOnRestart: true,
+  backupIncludePlugins: true,
+  maxBackups: 2,
+  rollbackTimeoutMs: 90000,
 }
 
 /** Merge a loader row config over {@link DEFAULTS}, dropping wrong-typed values. */
@@ -246,6 +271,11 @@ 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
+  const rollbackTimeout = Number(config.rollbackTimeoutMs)
+  config.rollbackTimeoutMs =
+    Number.isFinite(rollbackTimeout) && rollbackTimeout >= 1000 ? Math.trunc(rollbackTimeout) : 90000
   return config
 }
 
@@ -454,6 +484,75 @@ function resolveStateFile(config) {
   return path.join(home, 'storages', 'dsh-autorestart', 'state.json')
 }
 
+/**
+ * Resolve the profile directory the running host was started from.
+ *
+ * The host process does NOT necessarily carry `DSH_PROFILE_DIR` / `DSH_PROFILE`
+ * (those are injected into shell commands, not into the host environment), so this
+ * walks four independent sources and reports which one answered:
+ *
+ *   1. `DSH_PROFILE_DIR` — the host exported it.
+ *   2. `DSH_HOME` + `DSH_PROFILE`.
+ *   3. `--profile <name>` / `--profile=<name>` on the host command line.
+ *   4. the only profile whose `dsh.profile.bundles` lists this plugin.
+ *
+ * @returns {{ dir: string|null, source: string }}
+ */
+function resolveProfileDirDetailed() {
+  const explicit = process.env.DSH_PROFILE_DIR
+  if (typeof explicit === 'string' && explicit.trim() !== '') {
+    const dir = path.resolve(explicit.trim())
+    if (fs.existsSync(dir)) return { dir, source: 'DSH_PROFILE_DIR' }
+  }
+  const home = process.env.DSH_HOME && process.env.DSH_HOME.trim() !== ''
+    ? process.env.DSH_HOME.trim()
+    : ''
+  const profile = process.env.DSH_PROFILE && process.env.DSH_PROFILE.trim() !== ''
+    ? process.env.DSH_PROFILE.trim()
+    : ''
+  if (home !== '' && profile !== '') {
+    const dir = path.join(home, 'profiles', profile)
+    if (fs.existsSync(dir)) return { dir, source: 'DSH_HOME/DSH_PROFILE' }
+  }
+  // The host may have been started with an explicit --profile flag instead.
+  const argv = Array.isArray(process.argv) ? process.argv : []
+  let fromArgv = ''
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = String(argv[index] ?? '')
+    if (arg === '--profile' && index + 1 < argv.length) fromArgv = String(argv[index + 1] ?? '')
+    else if (arg.startsWith('--profile=')) fromArgv = arg.slice('--profile='.length)
+  }
+  const root = home !== '' ? home : path.join(os.homedir(), '.dsh')
+  if (fromArgv.trim() !== '') {
+    const dir = path.join(root, 'profiles', fromArgv.trim())
+    if (fs.existsSync(dir)) return { dir, source: 'host --profile flag' }
+  }
+  // Last resort: the only profile that lists this plugin as a bundle.
+  try {
+    const profilesDir = path.join(root, 'profiles')
+    const matches = []
+    for (const entry of fs.readdirSync(profilesDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue
+      const candidate = path.join(profilesDir, entry.name)
+      try {
+        const manifest = JSON.parse(fs.readFileSync(path.join(candidate, 'package.json'), 'utf8'))
+        const bundles = manifest && manifest.dsh && manifest.dsh.profile
+          && Array.isArray(manifest.dsh.profile.bundles)
+          ? manifest.dsh.profile.bundles
+          : []
+        if (bundles.includes(name)) matches.push(candidate)
+      } catch {}
+    }
+    if (matches.length === 1) return { dir: matches[0], source: 'profile bundles scan' }
+  } catch {}
+  return { dir: null, source: 'unknown' }
+}
+
+/** The profile directory, or null when it cannot be resolved. */
+function resolveProfileDir() {
+  return resolveProfileDirDetailed().dir
+}
+
 /** A logger that never throws and never requires a particular Cordis logger shape. */
 function createLogger(ctx) {
   const logger = ctx.logger
@@ -1105,6 +1204,13 @@ function createRuntime(ctx, config) {
     return 'http://127.0.0.1:' + port + resolveHealthPath(config) + '?gate=1'
   }
 
+  /** The plain health URL the rollback watcher polls after the relaunch. */
+  const restartHealthUrl = () => {
+    const port = runtime.webPort
+    if (!Number.isFinite(port) || port <= 0) return null
+    return 'http://127.0.0.1:' + port + resolveHealthPath(config)
+  }
+
   /** Execute the restart now; the detached helper survives our own death. */
   const executeRestart = async () => {
     stopPolling()
@@ -1158,11 +1264,60 @@ function createRuntime(ctx, config) {
         } else if (url === null) {
           log.warn('the web server port is unknown; scheduling an UNGATED restart (the helper cannot re-check the idle gate)')
         }
+        // Snapshot the profile BEFORE anything is killed: the configuration files
+        // decide whether every bundle loads, so a snapshot is what makes a
+        // "the host does not come back" rollback possible at all.
+        const stateDir = path.dirname(stateFile)
+        const profileInfo = resolveProfileDirDetailed()
+        const profileDir = profileInfo.dir
+        let backup = null
+        if (config.backupOnRestart === true && profileDir !== null) {
+          backup = createBackup({
+            profileDir,
+            backupsDir: backupsRoot(stateDir),
+            includePlugins: config.backupIncludePlugins !== false,
+            maxBackups: config.maxBackups,
+          })
+          if (backup.ok === true) {
+            log.warn('pre-restart backup written', {
+              dir: backup.dir,
+              bytes: backup.bytes,
+              includePlugins: backup.includePlugins,
+              pruned: backup.pruned,
+              profileDirSource: profileInfo.source,
+            })
+            // A report from an older boot must not be mistaken for this one.
+            clearRollbackReport(stateDir)
+          } else {
+            log.warn('the pre-restart backup failed; continuing without a rollback point', { error: backup.error })
+          }
+        } else if (config.backupOnRestart === true) {
+          log.warn('no profile directory is known; skipping the pre-restart backup', { source: profileInfo.source })
+        }
+
+        const healthUrl = restartHealthUrl()
+        const watchScriptPath = backup && backup.ok === true && healthUrl !== null && profileDir !== null
+          ? path.join(stateDir, 'restart-' + state.generation + '-watch.ps1')
+          : null
+        const watchScript = watchScriptPath === null
+          ? null
+          : buildWatchScript({
+            healthUrl,
+            backupDir: backup.dir,
+            profileDir,
+            reportPath: path.join(stateDir, ROLLBACK_REPORT_NAME),
+            appExePath: env.appExePath,
+            timeoutMs: config.rollbackTimeoutMs,
+            // Only a crash log written after this point belongs to this restart.
+            since: new Date().toISOString(),
+          })
         const result = scheduleDetachedRestart({
           appExePath: env.appExePath,
           relaunchDelaySeconds: config.relaunchDelaySeconds,
           gateUrl: url,
-          scriptPath: url === null ? null : path.join(path.dirname(stateFile), 'restart-' + state.generation + '.cmd'),
+          scriptPath: url === null ? null : path.join(stateDir, 'restart-' + state.generation + '.cmd'),
+          watchScriptPath,
+          watchScript,
         })
         log.warn('scheduled detached restart:', result)
         if (!result || result.ok !== true) rollbackRestart((result && result.error) || 'detached restart refused')
@@ -1244,6 +1399,33 @@ function createRuntime(ctx, config) {
     get isNewBoot() {
       return boot.isNewBoot
     },
+    /**
+     * Where the pre-restart backup will be taken from, and which source answered.
+     * `dir` is null when no source could resolve it (the backup is then skipped).
+     */
+    get profileDir() {
+      return resolveProfileDirDetailed()
+    },
+    /**
+     * The rollback report the detached watcher left behind, or null.
+     *
+     * It means the previous restart never brought the host back and the snapshot
+     * taken before that restart was restored. Read once per process: the next
+     * restart clears it.
+     */
+    get lastRollback() {
+      const report = readRollbackReport(path.dirname(stateFile))
+      if (!report || report.ok !== false) return null
+      const tail = typeof report.crashTail === 'string' ? report.crashTail : ''
+      return {
+        at: typeof report.at === 'string' ? report.at : null,
+        waitedMs: Number.isFinite(report.waitedMs) ? report.waitedMs : null,
+        rolledBack: report.rolledBack === true,
+        backupDir: typeof report.backupDir === 'string' ? report.backupDir : null,
+        crashLog: typeof report.crashLog === 'string' ? report.crashLog : null,
+        crashTail: tail.length > 4000 ? tail.slice(-4000) : tail,
+      }
+    },
     env,
     stateFile,
     log,
@@ -1990,6 +2172,9 @@ function registerTools(ctx, runtime, config) {
           parkedGoals: { type: 'array', items: { type: 'object' } },
           recovery: { type: 'array', items: { type: 'object' } },
           handoffs: { type: 'array', items: { type: 'object' } },
+          profileDir: { type: 'string' },
+          profileDirSource: { type: 'string' },
+          lastRollback: { type: 'object' },
           environment: { type: 'object' },
           sessions: { type: 'array', items: { type: 'object' } },
         },
@@ -2013,6 +2198,11 @@ function registerTools(ctx, runtime, config) {
         parkedGoals: parkedGoalDetails(),
         recovery: recoveryList(state),
         handoffs: diagnosticSessions(state),
+        // Where the pre-restart backup comes from (null dir = it would be skipped).
+        profileDirSource: runtime.profileDir.source,
+        ...(runtime.profileDir.dir ? { profileDir: runtime.profileDir.dir } : {}),
+        // Present only when the previous restart had to be rolled back.
+        ...(runtime.lastRollback ? { lastRollback: runtime.lastRollback } : {}),
         environment: {
           platform: runtime.env.platform,
           isDesktopApp: runtime.env.isDesktopApp,

package/lib/backup.js

@@ -0,0 +1,350 @@
+/**
+ * dsh-autorestart — pre-restart backups.
+ *
+ * A restart can leave the host unable to boot: the profile configuration is what
+ * decides whether every installed bundle loads, and the host's own rescue path
+ * rewrites exactly those files when a boot fails. So the restart helper keeps a
+ * snapshot of the profile (its configuration files, and — when enabled — the
+ * installed plugin tree) and can put it back when the host does not come up.
+ *
+ * Everything here is synchronous and bounded: a backup is taken right before the
+ * detached restart is scheduled, and only the newest `maxBackups` snapshots are
+ * kept (older ones are removed so the disk never grows without a limit).
+ *
+ * The restore path used by the detached helper lives in the generated PowerShell
+ * watcher (lib/restart.js); `restoreBackup` here is the same operation for tests
+ * and for a manual recovery from inside the host.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** The profile files that decide whether the host can boot. */
+export const CONFIG_FILES = Object.freeze(['cordis.patch.yml', 'package.json', 'pnpm-lock.yaml']);
+
+/** The directory inside one backup that holds the configuration files. */
+export const CONFIG_DIR = 'config';
+
+/** The directory inside one backup that holds the installed plugin tree. */
+export const PLUGINS_DIR = 'node_modules';
+
+/** The manifest written into every backup. */
+export const MANIFEST_NAME = 'manifest.json';
+
+/** How many backups are kept by default. */
+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';
+
+/**
+ * A filesystem-safe timestamp for a backup directory name.
+ *
+ * @param {number} [now]
+ * @returns {string}
+ */
+export function backupStamp(now = Date.now()) {
+  const date = new Date(Number.isFinite(Number(now)) ? Number(now) : Date.now());
+  return date.toISOString().replace(/[:.]/g, '-');
+}
+
+/**
+ * The backups directory that belongs to a state directory.
+ *
+ * @param {string} stateDir
+ * @returns {string}
+ */
+export function backupsRoot(stateDir) {
+  return path.join(String(stateDir ?? ''), 'backups');
+}
+
+/** Recursively measure a directory; never throws. */
+function directorySize(target) {
+  let bytes = 0;
+  let files = 0;
+  let entries;
+  try {
+    entries = fs.readdirSync(target, { withFileTypes: true });
+  } catch {
+    return { bytes, files };
+  }
+  for (const entry of entries) {
+    const child = path.join(target, entry.name);
+    if (entry.isDirectory()) {
+      const nested = directorySize(child);
+      bytes += nested.bytes;
+      files += nested.files;
+      continue;
+    }
+    try {
+      bytes += fs.statSync(child).size;
+      files += 1;
+    } catch {
+      // A file that vanished between readdir and stat is simply not counted.
+    }
+  }
+  return { bytes, files };
+}
+
+/**
+ * Copy one entry (file or directory) into a destination directory.
+ *
+ * @returns {boolean} whether anything was copied
+ */
+function copyEntry(source, destination) {
+  try {
+    const stat = fs.statSync(source);
+    if (stat.isDirectory()) {
+      fs.cpSync(source, destination, { recursive: true, force: true });
+      return true;
+    }
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
+    fs.copyFileSync(source, destination);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Keep only the newest `maxBackups` backup directories.
+ *
+ * @param {string} backupsDir
+ * @param {number} [maxBackups]
+ * @returns {string[]} the names that were removed
+ */
+export function pruneBackups(backupsDir, maxBackups = DEFAULT_MAX_BACKUPS) {
+  const limit = Number.isFinite(Number(maxBackups)) && Number(maxBackups) >= 1
+    ? Math.trunc(Number(maxBackups))
+    : DEFAULT_MAX_BACKUPS;
+  let names;
+  try {
+    names = fs.readdirSync(backupsDir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort();
+  } catch {
+    return [];
+  }
+  const removed = [];
+  for (const name of names.slice(0, Math.max(0, names.length - limit))) {
+    const target = path.join(backupsDir, name);
+    try {
+      fs.rmSync(target, { recursive: true, force: true });
+      removed.push(name);
+    } catch {
+      // A backup that cannot be removed must not fail the restart.
+    }
+  }
+  return removed;
+}
+
+/**
+ * List the backups, newest first.
+ *
+ * @param {string} backupsDir
+ * @returns {Array<{name: string, dir: string, at: number|null, bytes: number|null, includePlugins: boolean}>}
+ */
+export function listBackups(backupsDir) {
+  let names;
+  try {
+    names = fs.readdirSync(backupsDir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const name of names.sort().reverse()) {
+    const dir = path.join(backupsDir, name);
+    const manifest = readManifest(dir);
+    out.push({
+      name,
+      dir,
+      at: manifest && Number.isFinite(manifest.at) ? manifest.at : null,
+      bytes: manifest && Number.isFinite(manifest.bytes) ? manifest.bytes : null,
+      includePlugins: Boolean(manifest && manifest.includePlugins === true),
+    });
+  }
+  return out;
+}
+
+/**
+ * Read one backup manifest.
+ *
+ * @param {string} backupDir
+ * @returns {object|null}
+ */
+export function readManifest(backupDir) {
+  try {
+    const text = fs.readFileSync(path.join(String(backupDir ?? ''), MANIFEST_NAME), 'utf8');
+    const parsed = JSON.parse(text);
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Take one backup of the profile.
+ *
+ * `includePlugins` copies the whole installed plugin tree, which is what makes a
+ * rollback of "a plugin upgrade broke the boot" actually possible; without it only
+ * the configuration files are copied.
+ *
+ * Never throws: a backup that cannot be written is reported as `{ ok: false }` so
+ * the caller can decide whether the restart may still proceed.
+ *
+ * @param {{
+ *   profileDir: string,
+ *   backupsDir: string,
+ *   includePlugins?: boolean,
+ *   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 }}
+ */
+export function createBackup({
+  profileDir,
+  backupsDir,
+  includePlugins = true,
+  maxBackups = DEFAULT_MAX_BACKUPS,
+  now = Date.now(),
+} = {}) {
+  const profile = typeof profileDir === 'string' ? profileDir.trim() : '';
+  const root = typeof backupsDir === 'string' ? backupsDir.trim() : '';
+  const base = {
+    ok: false,
+    dir: null,
+    stamp: null,
+    bytes: 0,
+    files: [],
+    includePlugins: includePlugins === true,
+    pruned: [],
+    error: null,
+  };
+  if (profile === '') return { ...base, error: 'createBackup requires profileDir' };
+  if (root === '') return { ...base, error: 'createBackup requires backupsDir' };
+  if (!fs.existsSync(profile)) return { ...base, error: 'the profile directory does not exist' };
+
+  const stamp = backupStamp(now);
+  const dir = path.join(root, stamp);
+  const files = [];
+  let bytes = 0;
+  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)) };
+  }
+
+  for (const name of CONFIG_FILES) {
+    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));
+      try {
+        bytes += fs.statSync(path.join(dir, CONFIG_DIR, name)).size;
+      } catch {
+        // Size reporting is advisory only.
+      }
+    }
+  }
+
+  if (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;
+    }
+  }
+
+  const manifest = {
+    stamp,
+    at: Number(now),
+    profileDir: profile,
+    includePlugins: includePlugins === true,
+    files,
+    bytes,
+  };
+  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)) };
+  }
+
+  const pruned = pruneBackups(root, maxBackups);
+  return { ...base, ok: true, dir, stamp, bytes, files, pruned };
+}
+
+/**
+ * Put a backup back over the live profile.
+ *
+ * The configuration files are copied over the existing ones; the plugin tree is
+ * copied with `force` so the snapshot wins file by file. The caller decides what
+ * to do with the host afterwards (the detached helper relaunches it).
+ *
+ * @param {{ backupDir: string, profileDir: string }} options
+ * @returns {{ ok: boolean, restored: string[], error: string|null }}
+ */
+export function restoreBackup({ backupDir, profileDir } = {}) {
+  const backup = typeof backupDir === 'string' ? backupDir.trim() : '';
+  const profile = typeof profileDir === 'string' ? profileDir.trim() : '';
+  const restored = [];
+  if (backup === '') return { ok: false, restored, error: 'restoreBackup requires backupDir' };
+  if (profile === '') return { ok: false, restored, error: 'restoreBackup requires profileDir' };
+  if (!fs.existsSync(backup)) return { ok: false, restored, error: 'the backup directory does not exist' };
+
+  const configDir = path.join(backup, CONFIG_DIR);
+  if (fs.existsSync(configDir)) {
+    for (const name of CONFIG_FILES) {
+      const source = path.join(configDir, name);
+      if (!fs.existsSync(source)) continue;
+      if (copyEntry(source, path.join(profile, name))) restored.push(name);
+    }
+  }
+  const plugins = path.join(backup, PLUGINS_DIR);
+  if (fs.existsSync(plugins) && copyEntry(plugins, path.join(profile, PLUGINS_DIR))) {
+    restored.push(PLUGINS_DIR);
+  }
+  if (restored.length === 0) {
+    return { ok: false, restored, error: 'the backup holds nothing that could be restored' };
+  }
+  return { ok: true, restored, error: null };
+}
+
+/**
+ * Read the report the detached helper writes after a rolled-back boot.
+ *
+ * @param {string} stateDir
+ * @returns {object|null}
+ */
+export function readRollbackReport(stateDir) {
+  const dir = typeof stateDir === 'string' ? stateDir.trim() : '';
+  if (dir === '') return null;
+  try {
+    let text = fs.readFileSync(path.join(dir, ROLLBACK_REPORT_NAME), 'utf8');
+    // Windows PowerShell 5.1 writes UTF-8 files with a BOM; JSON.parse rejects it.
+    if (text.charCodeAt(0) === 0xfeff) text = text.slice(1);
+    const parsed = JSON.parse(text);
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Remove the rollback report once it has been reported.
+ *
+ * @param {string} stateDir
+ * @returns {boolean} whether a report was removed
+ */
+export function clearRollbackReport(stateDir) {
+  const dir = typeof stateDir === 'string' ? stateDir.trim() : '';
+  if (dir === '') return false;
+  try {
+    fs.rmSync(path.join(dir, ROLLBACK_REPORT_NAME), { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/lib/restart.js

@@ -158,6 +158,7 @@ export function buildGateScript({
   relaunchDelaySeconds = DEFAULT_RELAUNCH_DELAY_SECONDS,
   gateUrl = '',
   taskkillImageName = DEFAULT_IMAGE_NAME,
+  watchScriptPath = null,
 } = {}) {
   const seconds =
     typeof relaunchDelaySeconds === 'number' && Number.isFinite(relaunchDelaySeconds) && relaunchDelaySeconds >= 0
@@ -171,6 +172,7 @@ export function buildGateScript({
     + '"try { $r = Invoke-RestMethod -Uri '
     + gateArgument
     + ' -TimeoutSec 5; if ($r.allowRestart -ne $true) { exit 3 } } catch { exit 4 }"';
+  const watch = nonEmptyString(watchScriptPath);
   const lines = [
     '@echo off',
     'rem dsh-autorestart: wait, re-check the idle gate, then kill + relaunch DeepSeek Harness.',
@@ -180,6 +182,103 @@ export function buildGateScript({
     'taskkill /IM "' + image + '" /T /F',
     'ping -n 3 127.0.0.1 >nul',
     'start "" "' + exe + '"',
+  ];
+  if (watch !== null) {
+    lines.push('rem dsh-autorestart: wait for the host to come back; roll the backup back when it does not.');
+    // Launched as its own hidden process so the .cmd can end immediately: the
+    // helper console must close as soon as the relaunch is issued (a visible
+    // console window parked in front of the app is not acceptable), and the
+    // watcher must survive that console closing.
+    lines.push('start "" powershell.exe -WindowStyle Hidden -NoProfile -ExecutionPolicy Bypass -File "' + watch + '"');
+  }
+  lines.push('');
+  return lines.join('\r\n');
+}
+
+/** How long the watcher waits for the relaunched host before it rolls back. */
+export const DEFAULT_ROLLBACK_TIMEOUT_MS = 90000;
+
+/**
+ * Build the PowerShell watcher the `.cmd` helper runs right after the relaunch.
+ *
+ * It polls the health route for `timeoutMs`; a healthy answer ends the watch. When
+ * the host does not come back, the snapshot taken before the restart is copied back
+ * over the profile (configuration files, and the plugin tree when the backup holds
+ * one), a report is written next to the checkpoint, and the host is launched again
+ * with the restored configuration.
+ *
+ * The report is written WITHOUT a BOM even on PowerShell 5.1, because the plugin
+ * parses it with JSON.parse.
+ *
+ * @param {{
+ *   healthUrl?: string,
+ *   backupDir?: string,
+ *   profileDir?: string,
+ *   reportPath?: string,
+ *   appExePath?: string|null,
+ *   timeoutMs?: number,
+ * }} [options]
+ * @returns {string} script text (CRLF line endings)
+ */
+export function buildWatchScript({
+  healthUrl = '',
+  backupDir = '',
+  profileDir = '',
+  reportPath = '',
+  appExePath = null,
+  timeoutMs = DEFAULT_ROLLBACK_TIMEOUT_MS,
+  since = null,
+} = {}) {
+  const timeout =
+    typeof timeoutMs === 'number' && Number.isFinite(timeoutMs) && timeoutMs >= 1000
+      ? Math.trunc(timeoutMs)
+      : DEFAULT_ROLLBACK_TIMEOUT_MS;
+  // Only a crash log written AFTER the restart is evidence about it: an older one
+  // would blame last week's failure for this one.
+  const sinceText = typeof since === 'string' && since.trim() !== ''
+    ? since.trim()
+    : (Number.isFinite(Number(since)) ? new Date(Number(since)).toISOString() : '');
+  const quote = (value) => "'" + psSingle(typeof value === 'string' ? value : '') + "'";
+  const lines = [
+    '# dsh-autorestart: wait for the relaunched host; roll the pre-restart backup back when it never answers.',
+    "$ErrorActionPreference = 'SilentlyContinue'",
+    '$health = ' + quote(nonEmptyString(healthUrl) ?? ''),
+    '$backup = ' + quote(nonEmptyString(backupDir) ?? ''),
+    '$profile = ' + quote(nonEmptyString(profileDir) ?? ''),
+    '$report = ' + quote(nonEmptyString(reportPath) ?? ''),
+    '$exe = ' + quote(nonEmptyString(appExePath) ?? ''),
+    '$deadline = (Get-Date).AddMilliseconds(' + timeout + ')',
+    '$healthy = $false',
+    'while ((Get-Date) -lt $deadline) {',
+    '  try { $r = Invoke-RestMethod -Uri $health -TimeoutSec 5; if ($r.ok -eq $true) { $healthy = $true; break } } catch { }',
+    '  Start-Sleep -Seconds 2',
+    '}',
+    'if ($healthy) { exit 0 }',
+    '$crashDir = Join-Path $env:APPDATA \'@deepseek-ai\\dsh-desktop\\logs\'',
+    '$since = ' + quote(sinceText),
+    '$crash = $null',
+    'if ($since -ne \'\') { $crash = Get-ChildItem $crashDir -Filter \'crash-*.log\' | Where-Object { $_.LastWriteTime -gt ([datetime]$since) } | Sort-Object LastWriteTime -Descending | Select-Object -First 1 }',
+    'if (-not $crash) { $crash = Get-ChildItem $crashDir -Filter \'crash-*.log\' | Sort-Object LastWriteTime -Descending | Select-Object -First 1 }',
+    "$tail = ''",
+    'if ($crash) { $tail = ((Get-Content $crash.FullName -Tail 60) -join [char]10) }',
+    '$rolledBack = $false',
+    '$configBackup = Join-Path $backup \'config\'',
+    'if (Test-Path $configBackup) {',
+    '  robocopy $configBackup $profile /E /NFL /NDL /NJH /NJS /NP | Out-Null',
+    '  $rolledBack = $true',
+    '}',
+    '$pluginsBackup = Join-Path $backup \'node_modules\'',
+    'if (Test-Path $pluginsBackup) {',
+    '  robocopy $pluginsBackup (Join-Path $profile \'node_modules\') /MIR /NFL /NDL /NJH /NJS /NP | Out-Null',
+    '  $rolledBack = $true',
+    '}',
+    '$crashName = $null',
+    'if ($crash) { $crashName = $crash.Name }',
+    '$payload = [ordered]@{ ok = $false; at = (Get-Date).ToString(\'o\'); waitedMs = ' + timeout + '; rolledBack = $rolledBack; backupDir = $backup; crashLog = $crashName; crashTail = $tail }',
+    '$json = $payload | ConvertTo-Json -Depth 4',
+    '[System.IO.File]::WriteAllText($report, $json, (New-Object System.Text.UTF8Encoding($false)))',
+    'Start-Process -FilePath $exe',
+    'exit 0',
     '',
   ];
   return lines.join('\r\n');
@@ -226,15 +325,25 @@ export function scheduleDetachedRestart({
   dryRun = false,
   gateUrl = null,
   scriptPath = null,
+  watchScriptPath = null,
+  watchScript = null,
 } = {}) {
   const task = nonEmptyString(taskName) ?? DEFAULT_TASK_NAME;
   const gate = nonEmptyString(gateUrl);
   const scriptFile = nonEmptyString(scriptPath);
+  const watchFile = nonEmptyString(watchScriptPath);
+  const watchText = typeof watchScript === 'string' ? watchScript : null;
   const gated = gate !== null;
   let script = null;
   let command;
   if (gated) {
-    script = buildGateScript({ appExePath, relaunchDelaySeconds, gateUrl: gate, taskkillImageName });
+    script = buildGateScript({
+      appExePath,
+      relaunchDelaySeconds,
+      gateUrl: gate,
+      taskkillImageName,
+      watchScriptPath: watchFile,
+    });
     command = scriptFile === null ? '' : 'cmd.exe /c "' + scriptFile + '"';
   } else {
     command = buildRestartCommand({ appExePath, relaunchDelaySeconds, taskkillImageName });
@@ -260,6 +369,8 @@ export function scheduleDetachedRestart({
     gated,
     scriptPath: scriptFile,
     script,
+    watchScriptPath: watchFile,
+    watchScript: watchText,
   };
 
   if (!nonEmptyString(appExePath)) {
@@ -270,10 +381,27 @@ export function scheduleDetachedRestart({
     return { ...base, error: 'scheduleDetachedRestart requires scriptPath when gateUrl is set' };
   }
 
+  if (watchFile !== null && watchText === null) {
+    return { ...base, error: 'scheduleDetachedRestart requires watchScript when watchScriptPath is set' };
+  }
+
   if (dryRun === true) {
     return { ...base, ok: true, dryRun: true };
   }
 
+  if (watchFile !== null && watchText !== null) {
+    // The watcher must exist before the .cmd runs it: same atomic write as the
+    // gate script, so a half-written .ps1 can never be executed.
+    try {
+      mkdirSync(path.dirname(watchFile), { recursive: true });
+      const temporary = watchFile + '.tmp';
+      writeFileSync(temporary, String(watchText), { encoding: 'utf8' });
+      renameSync(temporary, watchFile);
+    } catch (error) {
+      return { ...base, error: 'could not write the rollback watcher: ' + errorText(error) };
+    }
+  }
+
   if (gated) {
     // The helper must exist before the scheduler runs it: write it atomically
     // (tmp file + rename) so a half-written .cmd can never be executed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-autorestart",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "type": "module",
   "description": "DeepSeek Harness plugin: restart without losing work. Waits until every conversation is idle, restarts the host, then automatically resumes the interrupted sessions. AI-generated, not human-reviewed: use with caution.",
   "license": "MIT",