dsh-autorestart 0.7.0 → 0.8.1

package/lib/watchdog.js

@@ -0,0 +1,479 @@
+/**
+ * THE WATCHDOG — one flow, three ways to trigger it.
+ *
+ * The flow is the same everywhere; only the way the watchdog is made to run
+ * differs (see lib/watchdog-tier.js and lib/watchdog-schedule.js). This file
+ * is that flow:
+ *
+ *   1. wait for the READY marker (the new host wrote it after its health
+ *      check passed);
+ *   2. no marker? Wait a bit and ASK AGAIN — a host that is slow to start is
+ *      not a host that is dead (the misjudgement protection);
+ *   3. still nothing? Is an instance ALIVE? If one is listening, the rollback
+ *      is not needed: stand down (the no-double-start protection);
+ *   4. take the shared lock (`rollback.lock`) — exactly ONE of us restores;
+ *   5. restore the snapshot, then START THE HOST AGAIN;
+ *   6. wait for the ready marker once more: it came → `recovered`, it did not
+ *      → `failed` — and then we STOP (at most one restore and one start).
+ *
+ * Whatever happens, the scheduling item and the pending marker go; the report
+ * stays.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** The marker that says "a restart is coming, a watchdog is watching". */
+export const PENDING_NAME = 'watchdog-pending.json';
+/** The marker that says "the new host is up and healthy". */
+export const READY_NAME = 'watchdog-ready.json';
+/** The report of the last watchdog run. */
+export const REPORT_NAME = 'last-watchdog-report.json';
+/** The lock that both the plugin and the watchdog take before a restore. */
+export const LOCK_NAME = 'rollback.lock';
+
+/** How long the watchdog waits for the new host. */
+export const DEFAULT_TIMEOUT_MS = 180000;
+/** How long it waits before it asks again (the misjudgement protection). */
+export const DEFAULT_RECHECK_MS = 20000;
+/** How often it looks at the ready marker. */
+export const DEFAULT_POLL_MS = 2000;
+/** How long it waits for the host after the restore. */
+export const DEFAULT_READY_TIMEOUT_MS = 90000;
+
+/**
+ * Write a JSON file (no BOM, so every reader can parse it).
+ *
+ * @param {string} file
+ * @param {object} value
+ */
+function writeJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(value, null, 2), 'utf8');
+}
+
+/**
+ * Read a JSON file (a file that cannot be read is a file that is not there).
+ *
+ * @param {string} file
+ * @returns {object|null}
+ */
+function readJson(file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The pending marker: what the watchdog has to know.
+ *
+ * @param {{
+ *   tier?: string,
+ *   tierReason?: string,
+ *   taskName?: string,
+ *   unitId?: string,
+ *   pidPath?: string,
+ *   snapshotDir?: string,
+ *   profileDir?: string,
+ *   restoreCommand?: object|null,
+ *   relaunchCommand?: object|null,
+ *   healthUrl?: string,
+ *   healthPath?: string,
+ *   portFile?: string,
+ *   expectedBootId?: string|null,
+ *   timeoutMs?: number,
+ *   recheckMs?: number,
+ *   readyTimeoutMs?: number,
+ *   hostKind?: string,
+ *   attempts?: number,
+ *   now?: number,
+ * }} options
+ * @returns {object}
+ */
+export function buildPending({
+  tier = 'none',
+  tierReason = '',
+  arbiter = 'v2',
+  taskName = '',
+  unitId = '',
+  pidPath = '',
+  snapshotDir = '',
+  profileDir = '',
+  restoreCommand = null,
+  relaunchCommand = null,
+  healthUrl = '',
+  healthPath = '/__dsh_autorestart/health',
+  portFile = '',
+  expectedBootId = null,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  recheckMs = DEFAULT_RECHECK_MS,
+  readyTimeoutMs = DEFAULT_READY_TIMEOUT_MS,
+  hostKind = '',
+  attempts = 1,
+  now = Date.now(),
+} = {}) {
+  return {
+    version: 1,
+    at: new Date(now).toISOString(),
+    tier,
+    tierReason,
+    arbiter,
+    taskName,
+    unitId,
+    pidPath,
+    snapshotDir,
+    profileDir,
+    restoreCommand,
+    relaunchCommand,
+    healthUrl,
+    healthPath,
+    portFile,
+    expectedBootId,
+    timeoutMs,
+    recheckMs,
+    readyTimeoutMs,
+    hostKind,
+    attempts,
+  };
+}
+
+/**
+ * @param {string} stateDir
+ * @returns {string}
+ */
+export function pendingPath(stateDir) {
+  return path.join(stateDir, PENDING_NAME);
+}
+
+/**
+ * @param {string} stateDir
+ * @returns {string}
+ */
+export function readyPath(stateDir) {
+  return path.join(stateDir, READY_NAME);
+}
+
+/**
+ * @param {string} stateDir
+ * @returns {string}
+ */
+export function reportPath(stateDir) {
+  return path.join(stateDir, REPORT_NAME);
+}
+
+/**
+ * Write the pending marker.
+ *
+ * @param {string} stateDir
+ * @param {object} pending
+ */
+export function writePending(stateDir, pending) {
+  writeJson(pendingPath(stateDir), pending);
+}
+
+/**
+ * @param {string} stateDir
+ * @returns {object|null}
+ */
+export function readPending(stateDir) {
+  return readJson(pendingPath(stateDir));
+}
+
+/**
+ * Remove the pending marker (the watchdog is over).
+ *
+ * @param {string} stateDir
+ */
+export function clearPending(stateDir) {
+  try {
+    fs.rmSync(pendingPath(stateDir), { force: true });
+  } catch {
+    // It is gone either way.
+  }
+}
+
+/**
+ * Write the ready marker: "the new host is up".
+ *
+ * @param {string} stateDir
+ * @param {{ bootId?: string, port?: number, at?: number }} [info]
+ */
+export function writeReady(stateDir, info = {}) {
+  writeJson(readyPath(stateDir), {
+    at: new Date(info.at ?? Date.now()).toISOString(),
+    bootId: info.bootId ?? null,
+    port: info.port ?? null,
+  });
+}
+
+/**
+ * @param {string} stateDir
+ * @returns {object|null}
+ */
+export function readReady(stateDir) {
+  return readJson(readyPath(stateDir));
+}
+
+/**
+ * Remove the ready marker (it belongs to one restart).
+ *
+ * @param {string} stateDir
+ */
+export function clearReady(stateDir) {
+  try {
+    fs.rmSync(readyPath(stateDir), { force: true });
+  } catch {
+    // It is gone either way.
+  }
+}
+
+/**
+ * Write the report of the last watchdog run.
+ *
+ * @param {string} stateDir
+ * @param {object} report
+ */
+export function writeReport(stateDir, report) {
+  writeJson(reportPath(stateDir), report);
+}
+
+/**
+ * @param {string} stateDir
+ * @returns {object|null}
+ */
+export function readReport(stateDir) {
+  return readJson(reportPath(stateDir));
+}
+
+/**
+ * Take the lock (exactly one restore at a time).
+ *
+ * @param {string} lockFile
+ * @param {{ now?: number, exists?: Function, mkdir?: Function, open?: Function }} [deps]
+ * @returns {boolean}
+ */
+export function acquireLock(lockFile, { now = Date.now(), exists = fs.existsSync, mkdir = (dir) => fs.mkdirSync(dir, { recursive: true }), open = null } = {}) {
+  try {
+    mkdir(path.dirname(lockFile));
+    if (exists(lockFile)) {
+      // 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.
+      let age = 0;
+      try {
+        age = now - fs.statSync(lockFile).mtimeMs;
+      } catch {
+        age = 0;
+      }
+      if (age > 10 * 60 * 1000) fs.rmSync(lockFile, { force: true });
+      else return false;
+    }
+    const handle = open === null
+      ? fs.openSync(lockFile, 'wx')
+      : open(lockFile);
+    if (handle !== null && handle !== undefined && typeof handle.close === 'function') handle.close();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Give the lock back.
+ *
+ * @param {string} lockFile
+ */
+export function releaseLock(lockFile) {
+  try {
+    fs.rmSync(lockFile, { force: true });
+  } catch {
+    // It is gone either way.
+  }
+}
+
+/**
+ * Put the snapshot back.
+ *
+ * The same for every platform: the configuration files and the plugin tree
+ * are copied out of the snapshot into the profile. (The profile is NOT
+ * deleted first — the broken files are overwritten, so a half-restored
+ * profile is never worse than the broken one.)
+ *
+ * @param {{ snapshotDir?: string, profileDir?: string, copy?: Function }} options
+ * @returns {{ ok: boolean, error: string|null, copied: string[] }}
+ */
+export function restoreFromSnapshot({ snapshotDir = '', profileDir = '', copy = null } = {}) {
+  const from = String(snapshotDir ?? '');
+  const into = String(profileDir ?? '');
+  if (from === '' || into === '') {
+    return { ok: false, error: 'the snapshot or the profile directory is unknown', copied: [] };
+  }
+  const copied = [];
+  const copyInto = copy === null
+    ? (source, target) => { fs.cpSync(source, target, { recursive: true, force: true }); }
+    : copy;
+  try {
+    for (const [part, target] of [['config', into], ['node_modules', path.join(into, 'node_modules')]]) {
+      const source = path.join(from, part);
+      if (!fs.existsSync(source)) continue;
+      copyInto(source, target);
+      copied.push(part);
+    }
+  } catch (error) {
+    return {
+      ok: false,
+      error: error && error.message ? error.message : String(error),
+      copied,
+    };
+  }
+  return { ok: copied.length > 0, error: copied.length > 0 ? null : 'the snapshot carries nothing to restore', copied };
+}
+
+/**
+ * Wait for the ready marker.
+ *
+ * @param {object} deps
+ * @param {number} timeoutMs
+ * @returns {Promise<boolean>}
+ */
+async function waitForReady(deps, timeoutMs) {
+  const deadline = deps.now() + Math.max(0, timeoutMs);
+  while (deps.now() < deadline) {
+    if (deps.readReady()) return true;
+    // The plugin may have decided on its own (the restart failed): stand down.
+    if (deps.isWithdrawn && deps.isWithdrawn()) return false;
+    await deps.sleep(Math.min(deps.pollMs, Math.max(0, deadline - deps.now())));
+  }
+  return deps.readReady() === true;
+}
+
+/**
+ * THE FLOW.
+ *
+ * @param {{
+ *   pending: object,
+ *   stateDir?: string,
+ *   deps?: object,
+ * }} options
+ * @returns {Promise<object>} the report
+ */
+export async function runWatchdogFlow({ pending, stateDir = '', deps = {} }) {
+  const d = {
+    sleep: async (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    now: () => Date.now(),
+    pollMs: DEFAULT_POLL_MS,
+    readReady: () => readReady(stateDir),
+    isWithdrawn: () => readPending(stateDir) === null,
+    probeAlive: () => false,
+    runRestore: () => ({ ok: false, error: 'no restore command' }),
+    runRelaunch: () => ({ ok: false, error: 'no relaunch command' }),
+    acquireLock: () => true,
+    releaseLock: () => {},
+    removeSchedule: () => {},
+    writeReport: (report) => writeReport(stateDir, report),
+    ...deps,
+  };
+  const startedAt = d.now();
+  const report = {
+    at: new Date(startedAt).toISOString(),
+    result: 'unknown',
+    tier: pending && pending.tier ? pending.tier : 'none',
+    tierReason: pending && pending.tierReason ? pending.tierReason : '',
+    // WHO watched this restart. There is only ever one watchdog at a time
+    // (see lib/watchdog-arbiter.js), and the report says which one it was.
+    arbiter: pending && pending.arbiter ? pending.arbiter : 'v2',
+    waitedMs: 0,
+    rechecked: false,
+    restored: false,
+    relaunched: false,
+    ready: false,
+    error: null,
+  };
+  try {
+    // (1) The new host writes the ready marker after its health check.
+    const ready = await waitForReady(d, pending.timeoutMs);
+    if (ready) {
+      report.result = 'not-needed';
+      report.ready = true;
+      return report;
+    }
+    if (d.isWithdrawn()) {
+      report.result = 'decided';
+      report.error = 'the plugin decided on its own: the watchdog stood down';
+      return report;
+    }
+
+    // (2) ASK AGAIN. A host that is slow to start is not a host that is dead.
+    report.rechecked = true;
+    await d.sleep(Math.max(0, pending.recheckMs));
+    if (d.readReady()) {
+      report.result = 'not-needed';
+      report.ready = true;
+      return report;
+    }
+    if (d.isWithdrawn()) {
+      report.result = 'decided';
+      report.error = 'the plugin decided on its own: the watchdog stood down';
+      return report;
+    }
+
+    // (3) Is an instance ALIVE? Then there is nothing to restore.
+    if (await d.probeAlive()) {
+      report.result = 'abandoned';
+      report.error = 'an instance is alive: the snapshot was not restored';
+      return report;
+    }
+
+    // (4) The lock: exactly ONE of us restores.
+    if (!d.acquireLock()) {
+      report.result = 'abandoned';
+      report.error = 'another rollback is already running';
+      return report;
+    }
+    try {
+      // (5) Restore the snapshot.
+      const restored = d.runRestore();
+      report.restored = restored !== null && restored !== undefined && restored.ok === true;
+      if (!report.restored) {
+        report.result = 'failed';
+        report.error = restored && restored.error ? restored.error : 'the restore failed';
+        return report;
+      }
+      // (6) Start the host again.
+      const relaunched = d.runRelaunch();
+      report.relaunched = relaunched !== null && relaunched !== undefined && relaunched.ok === true;
+      if (!report.relaunched) {
+        report.result = 'failed';
+        report.error = relaunched && relaunched.error ? relaunched.error : 'the host could not be started again';
+        return report;
+      }
+      // (7) Did it come up this time?
+      const readyAgain = await waitForReady(d, pending.readyTimeoutMs);
+      report.ready = readyAgain;
+      report.result = readyAgain ? 'recovered' : 'failed';
+      if (!readyAgain) report.error = 'the host did not come up after the restore';
+    } finally {
+      d.releaseLock();
+    }
+  } catch (error) {
+    report.result = 'failed';
+    report.error = error && error.message ? error.message : String(error);
+  } finally {
+    report.waitedMs = d.now() - startedAt;
+    // The scheduling item and the pending marker go; the report stays.
+    try {
+      d.removeSchedule();
+    } catch {
+      // The scheduling item is cleaned up by the next run if this fails.
+    }
+    try {
+      if (stateDir !== '') clearPending(stateDir);
+    } catch {
+      // It is gone either way.
+    }
+    d.writeReport(report);
+  }
+  return report;
+}

package/locale/en.json

@@ -174,7 +174,8 @@
       "restart": "Restart settings",
       "shutdown": "Shutdown settings",
       "supervisor": "Start at login",
-      "report": "Report a problem"
+      "report": "Report a problem",
+      "rescue": "If DSH will not start"
     },
     "seconds": {
       "label": "Shutdown countdown seconds",
@@ -270,6 +271,32 @@
       "issueTitle": "A problem with the restart / start at login",
       "issueBody": "Please paste the diagnostics you just copied below.\n\n## What happened\n\n\n## What you expected\n\n\n## How to reproduce\n"
     },
+    "rescue": {
+      "hint": "When DSH does not come up, these two scripts rescue it for you (neither of them needs DSH running).",
+      "restoreProfile": "Back to the last good state",
+      "emergencyDisable": "Take this plugin out only",
+      "path": "Path",
+      "copyPath": "Copy the path",
+      "copied": "The path is on the clipboard",
+      "copyFailed": "The copy failed — please select the path above by hand",
+      "reveal": "Open the folder",
+      "which": "Which one: the whole environment is broken (a changed configuration, another plugin, a bad upgrade) → \"Back to the last good state\"; only this plugin is suspect → \"Take this plugin out only\".",
+      "warning": "Important: these two scripts are for when DSH does not come up. Using \"Back to the last good state\" while DSH is running overwrites the configuration you are working with right now.",
+      "shortcut": "Put a shortcut on the desktop",
+      "shortcutDone": "It is on the desktop",
+      "noDesktop": "This machine has no desktop directory, so no shortcut can be placed (the paths are above — copy them by hand).",
+      "shortcutFailed": "The shortcut was not placed: {message}",
+      "revealFailed": "The folder did not open: {message}",
+      "rollbackOk": "Automatic rollback: available (a host that does not come up after a restart goes back to the last good state)",
+      "rollbackBlocked": "Automatic rollback: **not available** — this computer does not allow creating scheduled tasks. **What you lose: DSH will NOT recover by itself when it does not come up after a restart**; when it breaks, double-click the restore script in \"If DSH will not start\".",
+      "rollbackUnknown": "Automatic rollback: not known yet (this machine has not been checked)",
+      "watchdogTier": "How the watchdog is triggered: {tier}",
+      "watchdogLast": "The last watchdog run: {result}",
+      "tierScheduledTask": "a Windows scheduled task",
+      "tierSystemdRun": "a systemd timer",
+      "tierDetachedProcess": "a detached background process",
+      "tierNone": "(this machine has no way to run it)"
+    },
     "error": "Could not save the settings: {message}",
     "autostartKind": {
       "other": "something else",

package/locale/zh.json

@@ -174,7 +174,8 @@
       "restart": "重启相关设置",
       "shutdown": "关机相关设置",
       "supervisor": "开机自启",
-      "report": "报告问题"
+      "report": "报告问题",
+      "rescue": "出事了怎么办"
     },
     "seconds": {
       "label": "关机倒数秒数",
@@ -270,6 +271,32 @@
       "issueTitle": "重启 / 开机自启相关的问题",
       "issueBody": "请把刚才复制的诊断信息粘贴到下面。\n\n## 发生了什么\n\n\n## 期望什么\n\n\n## 怎么复现\n"
     },
+    "rescue": {
+      "hint": "DSH 打不开的时候，用下面这两个脚本救自己（都不用 DSH 跑起来）。",
+      "restoreProfile": "回到上一次好状态",
+      "emergencyDisable": "只把这个插件摘掉",
+      "path": "路径",
+      "copyPath": "复制路径",
+      "copied": "路径已复制",
+      "copyFailed": "复制失败，请手动选中上面的路径",
+      "reveal": "打开所在文件夹",
+      "which": "怎么选：整个环境坏了（改了配置、装了别的插件、升级崩了）→ 用「回到上一次好状态」；只怀疑这个插件 → 用「只把这个插件摘掉」。",
+      "warning": "重要：这两个脚本是在 DSH 打不开的时候用的。DSH 正开着的时候用「回到上一次好状态」，会把你现在正在用的配置覆盖掉。",
+      "shortcut": "在桌面放一个快捷方式",
+      "shortcutDone": "已在桌面",
+      "noDesktop": "这台机器上没有桌面目录，所以放不了快捷方式（脚本的路径在上面，可以手动复制过去）。",
+      "shortcutFailed": "快捷方式没放成：{message}",
+      "revealFailed": "文件夹没打开：{message}",
+      "rollbackOk": "自动回滚：可用（重启后起不来会自动回到上一个好状态）",
+      "rollbackBlocked": "自动回滚：**不可用** —— 这台电脑不允许创建计划任务。**会丢失：重启后 DSH 起不来时不会自动恢复**；出问题时请双击「出事了怎么办」里的还原脚本。",
+      "rollbackUnknown": "自动回滚：还不知道（这台机器的能力还没检查过）",
+      "watchdogTier": "看门狗的触发方式：{tier}",
+      "watchdogLast": "上一次看门狗的结果：{result}",
+      "tierScheduledTask": "Windows 计划任务",
+      "tierSystemdRun": "systemd 定时器",
+      "tierDetachedProcess": "自建后台进程",
+      "tierNone": "（这台机器没有可用机制）"
+    },
     "error": "没能保存设置：{message}",
     "autostartKind": {
       "other": "其他方式",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-autorestart",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "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",
@@ -34,12 +34,17 @@
     "supervisor/supervisor.js",
     "scripts/*.ps1",
     "scripts/*.cmd",
+    "scripts/*.sh",
+    "scripts/*.mjs",
+    "scripts/README.md",
+    "scripts/rescue-strings.zh.json",
     "cordis.patch.yml",
     "locale/*.json",
     "icon.svg",
     "assets/*.png",
     "screenshots.json",
     "README.md",
+    "CHANGELOG.md",
     "docs/*.md"
   ],
   "dsh": {

package/scripts/README.md

@@ -0,0 +1,65 @@
+# 自救包（scripts）
+
+DSH 起不来的时候，这个文件夹里的东西**不用 DSH 自己**就能救自己。
+
+## 按平台挑文件（**别拿错平台的**）
+
+| 你的机器 | 还原 profile | 摘掉本插件 |
+|---|---|---|
+| **Windows**（桌面客户端 / Windows 上的 `dsh web`） | 双击 `restore-profile.cmd` | 双击 `emergency-disable.cmd` |
+| **Linux / WSL / macOS**（托管端） | `sh scripts/restore-profile.sh` | `sh scripts/emergency-disable.sh` |
+
+Linux/WSL 的机器上**没有** `.cmd` 文件，Windows 的机器上**没有** `.sh` —— 设置页的
+「出事了怎么办」只显示**这台机器上真有的**那两个路径，不会给你一条走不通的死路。
+每个平台到底有什么能力，看 [平台能力矩阵](../docs/platform-matrix.md)。
+
+- **双击哪个**：DSH 起不来（插件升级把 profile 弄坏了）→ 还原；只是想把本插件摘掉 → 摘插件。
+- **找不到它们？**：设置页里有一组「出事了怎么办」，上面写着这两个脚本的**绝对路径**（可以一键复制、可以一键打开所在文件夹；Windows 上还能放一个桌面快捷方式）—— DSH 真打不开、连 README 都打不开的时候，那一栏就是给你指路的。
+- **它会做什么**：`restore-profile.cmd` / `restore-profile.sh` 把最新的那份快照（`<stateDir>/backups/` 里带 manifest 的）放回 profile —— 先把现在的 profile 整份挪到 `<profile>.broken-<时间戳>`，再复制快照里的配置和插件树，最后回读校验（package.json 能解析、`dsh.profile.bundles` 有内容、插件版本号读得到）；校验不过就如实报错，并告诉你原来那份还在哪个目录。**它不会替你重启 DSH**（重启由你自己来，免得"救一次挂一次"）。
+- **会留下什么**：一个 `<profile>.broken-<yyyyMMdd-HHmmss>` 目录（出事之前的那份 profile 原封不动地留着，确认没问题后可以自己删掉），加上最后一行"已还原到 …… 现在可以重新打开 DSH"的结论。
+
+## 两条硬规矩（有意收紧，不是 bug）
+
+- **目标 profile 目录必须已经存在**：还原器把快照放回一个**已经存在**的 profile，**不会凭空新建**一个 profile（也不会替你建 `profiles` 目录）。路径写错的时候，宁可报错，也不留一个空壳 profile 在那儿。
+- **插件版本号的校验看配置说话**：profile 的 `dsh.profile.bundles` 里**没有** `dsh-autorestart` → 这一项**跳过**；**声明了**、但 `node_modules/dsh-autorestart` 不在 → **必须失败**（配置说一套、磁盘是另一套，这是真坏，不能放过）。
+
+## 演练（不碰你正在用的 profile）
+
+| 平台 | 命令 |
+|---|---|
+| Windows | `powershell -NoProfile -ExecutionPolicy Bypass -File .\drill-rescue.ps1` |
+| Linux / WSL | `sh scripts/drill-rescue.sh` |
+
+两个演练是**同一套断言**（Windows 的 `.ps1` 与 POSIX 的 `.sh`）：在临时目录里造一个假 profile → 故意把 `package.json` 写坏、删掉插件目录 → 调还原脚本救回来 → 断言（能解析、插件版本读得到、`broken-*` 目录存在、非 profile 目录被拒绝、目标目录不存在时被拒绝、"配置说装了却没装"时必须失败、**还原脚本的输出里真的有中文**）→ 清理临时目录。全绿时退出码是 0。
+
+演练的目录纪律（**并发跑也互不干扰**）：每次跑用一个带完整 GUID 的**唯一**目录，目录由本次演练自己创建（已存在就报错退出），目录里放一个独占的锁文件 `.lock`；清理**只删自己那一个绝对路径**，**绝不按前缀/通配符扫临时目录** —— 那会踩到同时在跑的另一个演练。成功、断言不过、抛错中断，走的都是同一个 `finally`，一定会清理；清理不干净就把残留路径打印出来。
+
+`restore-profile.ps1` 的参数：`-DryRun`（只打印将要做什么）、`-Snapshot <目录>`（指定某一份快照）、`-ProfileDir <路径>`（演练用的隔离目录）、`-StateDir <路径>`（插件状态目录，默认 `<DSH_HOME>/storages/dsh-autorestart`）。
+`restore-profile.sh` 的参数：`--dry-run`、`--snapshot <目录>`、`--profile <路径>`、`--state-dir <路径>`。`DSH_HOME` 可以用环境变量覆盖，但目标 profile 目录必须已经在那儿。
+
+> 编码规矩（为什么脚本是英文的）：这台机器只有 Windows PowerShell 5.1，它按 ANSI 读**不带 BOM 的 UTF-8** —— 脚本里只要有一个中文字符，整份文件就变乱码、直接 ParserError，脚本连第一步都走不到。POSIX 那边同理（`/bin/sh` 也按字节读，而且中文注释会让不同的 shell 表现不一致）。这个坑一天之内踩了三次，所以现在是**根治**而不是"记得加 BOM"：**所有 `.ps1` / `.sh` / `.cmd` / `.mjs` 必须是纯 ASCII（所有字节 < 128、不带 BOM）**。面向用户的中文全部放在**一个文件**里：`scripts/rescue-strings.zh.json`（UTF-8、**不带 BOM**，带 BOM 会让 `JSON.parse` 直接失败），脚本运行时读它；读不到或读坏了，脚本会用**英文兜底**继续跑，并明确打印一行英文说明（不会崩成乱码）。
+>
+> **以后要改文案，改 `rescue-strings.zh.json`，不要往脚本里塞中文。** 键名是语义化的（`restore.title`、`restore.brokenKept`、`drill.passed`、`emergency.failed` …），值里可以用 `{0}`、`{1}` 这类占位符。这条规矩由 `test/scripts-encoding.test.mjs` 天天盯着：它会扫目录（不是写死文件名）、断言每个 `.ps1` / `.sh` / `.mjs` 都是纯 ASCII、断言 `.sh` 以 `#!/bin/sh` 开头并开着 `set -eu`、断言 JSON 无 BOM 且能被 `JSON.parse`、断言每个脚本里用到的键在 JSON 里都存在、断言 `.cmd` 调的是 `powershell.exe` 而不是 `pwsh`。
+
+## 写 POSIX 脚本时踩过的三个坑（别再踩一次）
+
+这三个都是**真跑出来的**（不是猜的），症状和原因都写在这儿：
+
+1. **`/bin/sh`（dash）会数单引号里的括号。**
+   一段 `$( ... )` 里如果有一段**单引号包起来的英文兜底文案**，而那个文案里有一个
+   没配平的 `)`，整份脚本会直接语法报错（`Syntax error: ")" unexpected` / `expecting ")"`），
+   **而且报错的位置在后面很远的地方**，很难看出是哪一行害的。
+   → **兜底文案里不要出现括号**。要写就写成 `-` 或 `:`。
+2. **双引号包起来的 sed 表达式会被 shell 吃掉转义。**
+   `sed -n "s/.*\"$key\".../\1/p"` 里的 `\"` 会被 shell 先处理掉，表达式在引号那里被截断，
+   sed 报 `unterminated 's' command`（而且报错只给 char N，看不出是引号的问题）。
+   → **sed 表达式要么全单引号，要么用 `'...'"$var"'...'` 的拼接写法**。
+3. **文案 JSON 是嵌套的**（`restore.title` 是一条路径，不是文件里的键）。
+   用一条平铺的 sed 去找 `"restore.title"` 永远找不到 → 脚本会静悄悄地退回英文，
+   **功能全对、只是没有中文**，特别难发现。
+   → **按路径取值**：用 node 读 JSON（`process.argv[2].split(".")` 一层层取），
+   顺便把 `{0}`/`{1}` 的占位符替换也交给 node —— 中文是 UTF-8，**按字节的 sed 会把它弄坏**。
+
+这三个坑的共同点：**症状离原因很远**（语法错在后面、或者干脆不报错只是少了中文），
+所以每个脚本都尽量把"取值"和"拼字符串"这两件事交给 node，只在 node 不在时才退回
+那一小段 ASCII 兜底逻辑。