dsh-autorestart 0.6.1 → 0.7.0

package/lib/restart.js

@@ -15,12 +15,26 @@
  * ESM only, Node builtins only. No DSH / npm imports.
  */
 import { execFileSync, spawn } from 'node:child_process';
-import { mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, readlinkSync, renameSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 
 /** Default name of the one-shot scheduled-task fallback. */
 export const DEFAULT_TASK_NAME = 'dsh-autorestart-restart';
 
+/** Default name of the one-shot scheduled task that runs the rollback watcher. */
+export const DEFAULT_WATCH_TASK_NAME = 'dsh-autorestart-watch';
+
+/**
+ * How long the restart command may run before the plugin stops waiting for it.
+ *
+ * The command is the user's own: it usually returns in a second or two
+ * (`systemctl --user restart …`, a small shell script). A command that starts
+ * the host in the FOREGROUND never returns — that is not a failure, but the
+ * plugin must not wait for it for ever, so the window is bounded and the
+ * outcome is reported as "still running" instead of "failed".
+ */
+export const DEFAULT_COMMAND_TIMEOUT_MS = 30000;
+
 /** Default image name that `taskkill` matches on Windows. */
 export const DEFAULT_IMAGE_NAME = 'DeepSeek Harness.exe';
 
@@ -43,14 +57,360 @@ function nonEmptyString(value) {
   return typeof value === 'string' && value.trim() ? value.trim() : null;
 }
 
+/**
+ * The FILE NAMES of the desktop app's executable.
+ *
+ * The verdict is about the FILE NAME, never about the whole path: the desktop
+ * app ships its own node INSIDE its installation directory
+ * (`…\DeepSeek Harness\resources\runtime\…\node\bin\node.exe`), and a HOSTED
+ * deployment that runs with that node is NOT the desktop app. The old rule (a
+ * regex over the whole path) called every such host the desktop app, so the
+ * derivation refused to write a restart command for it (`desktop-app`, nothing
+ * to write) even though the host was a perfectly ordinary hosted one.
+ */
+const DESKTOP_EXE_NAMES = new Set(['deepseek harness']);
+
+/**
+ * The images that BREAK the parent chain.
+ *
+ * A shell between this process and the Electron shell means that SOMEBODY ELSE
+ * started it (a terminal, a service, a scheduled task): the desktop app is not
+ * in charge of this host, whatever the environment says.
+ */
+const SHELL_IMAGE_NAMES = new Set([
+  'cmd',
+  'powershell',
+  'pwsh',
+  'bash',
+  'sh',
+  'zsh',
+  'fish',
+  'dash',
+  'conhost',
+  'terminal',
+  'windowsterminal',
+  'wt',
+  'nu',
+  'alacritty',
+  'wezterm-gui',
+  'hyper',
+]);
+
+/** How far up the parent chain the plugin looks for the Electron shell. */
+const MAX_ANCESTOR_DEPTH = 4;
+
+/**
+ * The FILE NAME of an executable — the last segment, whatever the separator.
+ *
+ * @param {unknown} execPath
+ * @returns {string}
+ */
+export function executableBasename(execPath) {
+  const text = typeof execPath === 'string' ? execPath.trim() : '';
+  if (text === '') return '';
+  const parts = text.split(/[\\/]/);
+  return parts[parts.length - 1] ?? '';
+}
+
+/**
+ * The name of an executable, normalized for comparison: lower case, without
+ * the `.exe` suffix, and the separators (` `, `-`, `_`) folded into one space.
+ *
+ * @param {unknown} name
+ * @returns {string}
+ */
+export function normalizedExecutableName(name) {
+  return String(name ?? '')
+    .toLowerCase()
+    .replace(/\.exe$/i, '')
+    .replace(/[-_\s]+/g, ' ')
+    .trim();
+}
+
+/**
+ * Is this the file name of the desktop app?
+ *
+ * `DeepSeek Harness.exe` and `deepseek-harness.exe` are the same app; a
+ * `node.exe` that happens to live inside the app's directory is not.
+ *
+ * @param {unknown} execPath
+ * @returns {boolean}
+ */
+export function isDesktopExecutableName(execPath) {
+  return DESKTOP_EXE_NAMES.has(normalizedExecutableName(executableBasename(execPath)));
+}
+
+/**
+ * What is known about one process (POSIX: /proc).
+ *
+ * @param {number} pid
+ * @returns {{ pid: number, ppid: number, imageName: string, commandLine: string }|null}
+ */
+function readPosixProcessInfo(pid) {
+  const number = Number(pid);
+  if (!Number.isFinite(number) || number <= 0) return null;
+  const base = '/proc/' + number;
+  let status = '';
+  try {
+    status = readFileSync(base + '/status', 'utf8');
+  } catch {
+    return null;
+  }
+  const parent = /PPid:\s*(\d+)/.exec(status);
+  let commandLine = '';
+  try {
+    const raw = readFileSync(base + '/cmdline');
+    commandLine = (Buffer.isBuffer(raw) ? raw.toString('utf8') : String(raw))
+      .split('\0')
+      .filter((part) => part !== '')
+      .join(' ');
+  } catch {
+    commandLine = '';
+  }
+  let imageName = '';
+  try {
+    imageName = path.basename(readlinkSync(base + '/exe'));
+  } catch {
+    imageName = '';
+  }
+  if (imageName === '') {
+    const first = commandLine.split(' ')[0] ?? '';
+    imageName = executableBasename(first);
+  }
+  return {
+    pid: number,
+    ppid: parent ? Number(parent[1]) : 0,
+    imageName,
+    commandLine,
+  };
+}
+
+/**
+ * Parse the CSV table of `wmic process get …`.
+ *
+ * @param {string} text
+ * @returns {Array<{ pid: number, ppid: number, imageName: string }>}
+ */
+function parseWmicProcessTable(text) {
+  const lines = String(text ?? '')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line !== '');
+  if (lines.length < 2) return [];
+  const header = lines[0].split(',').map((part) => part.trim().toLowerCase());
+  const nameIndex = header.indexOf('name');
+  const ppidIndex = header.indexOf('parentprocessid');
+  const pidIndex = header.indexOf('processid');
+  if (nameIndex < 0 || ppidIndex < 0 || pidIndex < 0) return [];
+  const last = Math.max(nameIndex, ppidIndex, pidIndex);
+  const rows = [];
+  for (const line of lines.slice(1)) {
+    const cells = line.split(',').map((cell) => cell.trim().replace(/^"(.*)"$/, '$1'));
+    if (cells.length <= last) continue;
+    const pid = Number(cells[pidIndex]);
+    if (!Number.isFinite(pid) || pid <= 0) continue;
+    rows.push({ pid, ppid: Number(cells[ppidIndex]) || 0, imageName: cells[nameIndex] });
+  }
+  return rows;
+}
+
+/**
+ * Parse the JSON table of the CIM query.
+ *
+ * @param {string} text
+ * @returns {Array<{ pid: number, ppid: number, imageName: string }>}
+ */
+function parseCimProcessTable(text) {
+  const trimmed = String(text ?? '').trim();
+  if (trimmed === '') return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return [];
+  }
+  const list = Array.isArray(parsed) ? parsed : [parsed];
+  const rows = [];
+  for (const entry of list) {
+    if (!entry || typeof entry !== 'object') continue;
+    const pid = Number(entry.ProcessId);
+    if (!Number.isFinite(pid) || pid <= 0) continue;
+    rows.push({
+      pid,
+      ppid: Number(entry.ParentProcessId) || 0,
+      imageName: String(entry.Name ?? ''),
+    });
+  }
+  return rows;
+}
+
+/**
+ * Ask Windows for its processes: `wmic` first (it answers in ~150 ms), the CIM
+ * query of PowerShell as the fallback for the versions that removed `wmic`.
+ *
+ * @returns {Array<{ pid: number, ppid: number, imageName: string }>}
+ */
+function queryWindowsProcesses() {
+  try {
+    const stdout = execFileSync(
+      'wmic',
+      ['process', 'get', 'Name,ParentProcessId,ProcessId', '/FORMAT:CSV'],
+      { windowsHide: true, timeout: 4000, stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8' },
+    );
+    const rows = parseWmicProcessTable(String(stdout ?? ''));
+    if (rows.length > 0) return rows;
+  } catch {
+    // `wmic` is gone on the newer Windows versions: the CIM query below.
+  }
+  try {
+    const stdout = execFileSync(
+      'powershell.exe',
+      [
+        '-NoProfile',
+        '-NonInteractive',
+        '-Command',
+        'Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,Name | ConvertTo-Json -Compress',
+      ],
+      { windowsHide: true, timeout: 8000, stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8' },
+    );
+    return parseCimProcessTable(String(stdout ?? ''));
+  } catch {
+    // No process table: the parent chain stays unavailable (and silent).
+  }
+  return [];
+}
+
+/** The Windows process table — read once per process, then remembered. */
+let windowsProcessTable = null;
+
+/**
+ * The whole Windows process table: the image name and the parent of every
+ * process.
+ *
+ * @returns {Map<number, { pid: number, ppid: number, imageName: string }>}
+ */
+function readWindowsProcessTable() {
+  if (windowsProcessTable !== null) return windowsProcessTable;
+  const table = new Map();
+  for (const row of queryWindowsProcesses()) {
+    table.set(row.pid, row);
+  }
+  windowsProcessTable = table;
+  return table;
+}
+
+/**
+ * The parent chain of a process, nearest ancestor first.
+ *
+ * POSIX reads /proc (free); Windows reads the process table once. When the
+ * platform offers neither, the chain is EMPTY — an unknown chain is not
+ * evidence, it only means the chain cannot be used.
+ *
+ * @param {number} rootPid the pid to start from (the parent of this process)
+ * @param {{ platform?: string }} [options]
+ * @returns {Array<{ pid: number, ppid: number, imageName: string, commandLine?: string }>}
+ */
+export function readProcessChain(rootPid, { platform = process.platform } = {}) {
+  const start = Number(rootPid);
+  if (!Number.isFinite(start) || start <= 0) return [];
+  const chain = [];
+  const seen = new Set();
+  let pid = start;
+  while (pid > 0 && chain.length < MAX_ANCESTOR_DEPTH && !seen.has(pid)) {
+    seen.add(pid);
+    const info = platform === 'win32'
+      ? readWindowsProcessTable().get(pid) ?? null
+      : readPosixProcessInfo(pid);
+    if (info === null) break;
+    chain.push(info);
+    pid = Number(info.ppid) || 0;
+  }
+  return chain;
+}
+
+/**
+ * Is this process the child of the Electron shell of the desktop app?
+ *
+ * The desktop host is started by the Electron MAIN process, which runs the
+ * Electron binary as node: the host therefore carries `ELECTRON_RUN_AS_NODE=1`
+ * AND its parent is the Electron shell.
+ *
+ * The marker ALONE is not enough: a host that was started from a shell the
+ * desktop app spawned inherits it too. The parent chain decides — and a chain
+ * that cannot be read is simply not used (it never denies the desktop verdict,
+ * it only stays silent).
+ *
+ * @param {{
+ *   env?: object,
+ *   ppid?: number,
+ *   platform?: string,
+ *   readChain?: Function,
+ * }} [options]
+ * @returns {{ isElectronShell: boolean, evidence: string }}
+ */
+export function detectElectronShell({
+  env = process.env,
+  ppid = process.ppid,
+  platform = process.platform,
+  readChain = readProcessChain,
+} = {}) {
+  const marker = String((env && typeof env === 'object' ? env.ELECTRON_RUN_AS_NODE : '') ?? '')
+    .trim()
+    .toLowerCase();
+  if (marker !== '1' && marker !== 'true') return { isElectronShell: false, evidence: '' };
+  let chain = [];
+  try {
+    chain = readChain(ppid, { platform });
+  } catch {
+    chain = [];
+  }
+  if (!Array.isArray(chain) || chain.length === 0) {
+    // The chain could not be read: this signal stays silent.
+    return { isElectronShell: false, evidence: '' };
+  }
+  for (const ancestor of chain) {
+    const image = normalizedExecutableName(ancestor && ancestor.imageName);
+    if (image === '') continue;
+    if (SHELL_IMAGE_NAMES.has(image)) break; // somebody else started this host
+    if (DESKTOP_EXE_NAMES.has(image) || image === 'electron') {
+      return {
+        isElectronShell: true,
+        evidence: 'ancestor ' + ancestor.pid + ': ' + ancestor.imageName,
+      };
+    }
+  }
+  return { isElectronShell: false, evidence: '' };
+}
+
 /**
  * Describe the runtime we are executing in.
  *
+ * THE DESKTOP APP IS RECOGNISED BY THE FILE NAME OF THE EXECUTABLE.
+ *
  * Verified: when the Host runs inside the desktop app, `process.execPath` is the
- * app launcher itself (`...\DeepSeek Harness\DeepSeek Harness.exe`, no CLI args
+ * app launcher itself (`…\DeepSeek Harness\DeepSeek Harness.exe`, no CLI args
  * needed). Any other runtime is not a desktop app and has no app exe to launch.
  *
- * @param {{ env?: object, execPath?: string, pid?: number, ppid?: number, platform?: string }} [overrides]
+ * The whole PATH is never used: the desktop app ships its own node inside its
+ * installation directory, and a hosted deployment that runs with that node
+ * (`…\DeepSeek Harness\resources\runtime\…\node.exe`) is a hosted host, not the
+ * desktop app. Judging it by the path sent every such host into the
+ * "desktop app, nothing to do" branch — it never got a restart command.
+ *
+ * When the file name cannot answer the question, the harder evidence is used:
+ * the desktop host is the child of the Electron main process (it runs the
+ * Electron binary as node, so it carries `ELECTRON_RUN_AS_NODE=1` and its
+ * parent is the Electron shell). A process tree that cannot be read never
+ * denies the desktop verdict — it only stays silent.
+ *
+ * @param {{
+ *   env?: object,
+ *   execPath?: string,
+ *   pid?: number,
+ *   ppid?: number,
+ *   platform?: string,
+ *   readChain?: Function,
+ * }} [overrides]
  * @returns {{
  *   platform: string,
  *   pid: number,
@@ -69,17 +429,25 @@ export function detectEnvironment({
   pid = process.pid,
   ppid = process.ppid,
   platform = process.platform,
+  readChain = readProcessChain,
 } = {}) {
-  void env; // accepted for signature compatibility / future overrides
   const exe = typeof execPath === 'string' ? execPath : '';
-  const isDesktopApp = /deepseek[ -]harness/i.test(exe);
+  const nameIsDesktop = isDesktopExecutableName(exe);
+  // The process tree is only consulted when the file name does not answer.
+  const electron = nameIsDesktop
+    ? { isElectronShell: false, evidence: '' }
+    : detectElectronShell({ env, ppid, platform, readChain });
+  const isDesktopApp = nameIsDesktop || electron.isElectronShell;
   return {
     platform,
     pid,
     ppid,
     execPath: exe,
     isDesktopApp,
-    appExePath: isDesktopApp ? exe : null,
+    // The exe the plugin may launch again is the app launcher ITSELF. When
+    // only the process tree says "desktop app", the binary is unknown — and
+    // an unknown binary is never started again by the plugin.
+    appExePath: nameIsDesktop ? exe : null,
     hostPid: pid,
     mainPid: ppid,
     killPid: ppid,
@@ -230,62 +598,132 @@ export function buildGateScript({
 /** How long the watcher waits for the relaunched host before it rolls back. */
 export const DEFAULT_ROLLBACK_TIMEOUT_MS = 90000;
 
+/**
+ * How long ONE restore step (the configuration files, the plugin tree) may take
+ * before the watcher gives it up.
+ *
+ * A `robocopy` of a 117 MB plugin tree can take a while, but it must never
+ * hang the watcher for ever: a restore that does not finish in time is
+ * abandoned and the reason is written into the rollback report.
+ */
+export const DEFAULT_ROLLBACK_COPY_TIMEOUT_MS = 120000;
+
 /**
  * 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.
+ * WHAT IT DOES NOW (and what it did wrong before):
+ *
+ *   - It does NOT poll the health route of the OLD instance any more. The
+ *     desktop app listens on a RANDOM port (`--port 0`), so the port of the
+ *     instance that is being replaced is worthless: the watcher waited for an
+ *     answer that could never come, and then rolled back a perfectly healthy
+ *     restart. The port of the NEW instance is read from the instance record
+ *     (lib/access.js), which also carries the boot id — so the watcher knows
+ *     that the answer comes from the instance that replaced the old one.
+ *   - The restore runs with a TIME LIMIT. A `robocopy` that hangs is stopped,
+ *     and the report says so.
+ *   - The restore does NOT start a second copy of the host. The old behaviour
+ *     (`Start-Process -FilePath $exe`) launched a SECOND app next to the one
+ *     that was already starting up — two web servers, two ports, and a
+ *     confusing window. The watcher only restores the files and writes the
+ *     report; the host that was launched is left alone.
+ *   - The watcher cleans up after itself: the helper script and the marker
+ *     file are removed when it ends.
  *
- * The report is written WITHOUT a BOM even on PowerShell 5.1, because the plugin
- * parses it with JSON.parse.
+ * The report is written WITHOUT a BOM even on PowerShell 5.1, because the
+ * plugin parses it with JSON.parse.
  *
  * @param {{
  *   healthUrl?: string,
+ *   healthPath?: string,
+ *   portFile?: string,
+ *   expectedBootId?: string|null,
+ *   outcomeFile?: string,
  *   backupDir?: string,
  *   profileDir?: string,
  *   reportPath?: string,
+ *   lockFile?: string,
  *   appExePath?: string|null,
  *   timeoutMs?: number,
+ *   rollbackTimeoutMs?: number,
+ *   since?: string|number|null,
+ *   selfCleanPaths?: string[],
  * }} [options]
  * @returns {string} script text (CRLF line endings)
  */
 export function buildWatchScript({
   healthUrl = '',
+  healthPath = '/__dsh_autorestart/health',
+  portFile = '',
+  expectedBootId = null,
+  outcomeFile = '',
   backupDir = '',
   profileDir = '',
   reportPath = '',
+  lockFile = '',
   appExePath = null,
   timeoutMs = DEFAULT_ROLLBACK_TIMEOUT_MS,
+  rollbackTimeoutMs = DEFAULT_ROLLBACK_COPY_TIMEOUT_MS,
   since = null,
+  selfCleanPaths = [],
 } = {}) {
   const timeout =
     typeof timeoutMs === 'number' && Number.isFinite(timeoutMs) && timeoutMs >= 1000
       ? Math.trunc(timeoutMs)
       : DEFAULT_ROLLBACK_TIMEOUT_MS;
+  const copyTimeout =
+    typeof rollbackTimeoutMs === 'number' && Number.isFinite(rollbackTimeoutMs) && rollbackTimeoutMs >= 1000
+      ? Math.trunc(rollbackTimeoutMs)
+      : DEFAULT_ROLLBACK_COPY_TIMEOUT_MS;
+  // `Wait-Job -Timeout` counts SECONDS.
+  const copyTimeoutSeconds = Math.max(1, Math.ceil(copyTimeout / 1000));
   // 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 expected = typeof expectedBootId === 'string' && expectedBootId !== '' ? expectedBootId : '';
+  const cleanPaths = (Array.isArray(selfCleanPaths) ? selfCleanPaths : [])
+    .filter((entry) => typeof entry === 'string' && entry !== '')
+    .map((entry) => quote(entry));
   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) ?? ''),
+    '$healthPath = ' + quote(nonEmptyString(healthPath) ?? '/__dsh_autorestart/health'),
+    '$portFile = ' + quote(nonEmptyString(portFile) ?? ''),
+    '$expected = ' + quote(expected),
+    '$outcome = ' + quote(nonEmptyString(outcomeFile) ?? ''),
     '$backup = ' + quote(nonEmptyString(backupDir) ?? ''),
     '$profile = ' + quote(nonEmptyString(profileDir) ?? ''),
     '$report = ' + quote(nonEmptyString(reportPath) ?? ''),
-    '$exe = ' + quote(nonEmptyString(appExePath) ?? ''),
     '$deadline = (Get-Date).AddMilliseconds(' + timeout + ')',
     '$healthy = $false',
+    '$decided = $false',
+    '$newPort = 0',
     'while ((Get-Date) -lt $deadline) {',
-    '  try { $r = Invoke-RestMethod -Uri $health -TimeoutSec 5; if ($r.ok -eq $true) { $healthy = $true; break } } catch { }',
+    '  # The plugin may have decided on its own (the restart command failed): stand down.',
+    "  if ($outcome -ne '' -and (Test-Path -LiteralPath $outcome)) {",
+    '    $marker = $null',
+    '    try { $marker = Get-Content -LiteralPath $outcome -Raw | ConvertFrom-Json } catch { $marker = $null }',
+    '    if ($marker -and $marker.decided -eq $true) { $decided = $true; break }',
+    '  }',
+    '  # The NEW instance publishes its own port; the port of the old one is worthless.',
+    "  if ($portFile -ne '' -and (Test-Path -LiteralPath $portFile)) {",
+    '    $record = $null',
+    '    try { $record = Get-Content -LiteralPath $portFile -Raw | ConvertFrom-Json } catch { $record = $null }',
+    '    if ($record -and $record.bootId -and $record.bootId -ne $expected -and $record.port) {',
+    "      $url = 'http://127.0.0.1:' + $record.port + $healthPath",
+    '      try { $h = Invoke-RestMethod -Uri $url -TimeoutSec 5; if ($h.ok -eq $true) { $healthy = $true; $newPort = $record.port; break } } catch { }',
+    '    }',
+    '  } elseif ($health -ne \'\') {',
+    '    # No instance record at all (a Host that does not publish one): the old URL.',
+    '    try { $h = Invoke-RestMethod -Uri $health -TimeoutSec 5; if ($h.ok -eq $true) { $healthy = $true; break } } catch { }',
+    '  }',
     '  Start-Sleep -Seconds 2',
     '}',
-    'if ($healthy) { exit 0 }',
+    'if ($decided -or $healthy) { exit 0 }',
     '$crashDir = Join-Path $env:APPDATA \'@deepseek-ai\\dsh-desktop\\logs\'',
     '$since = ' + quote(sinceText),
     '$crash = $null',
@@ -293,29 +731,218 @@ export function buildWatchScript({
     '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',
+    '# THE LOCK: the plugin may be restoring the snapshot at the same time (it',
+    '# saw that the restart failed). Exactly ONE of them restores the files.',
+    '$lock = ' + quote(nonEmptyString(lockFile) ?? ''),
+    '$locked = $false',
+    'if ($lock -ne \'\') {',
+    '  # 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.',
+    '  if (Test-Path -LiteralPath $lock) {',
+    '    $age = (Get-Date) - (Get-Item -LiteralPath $lock).LastWriteTime',
+    '    if ($age.TotalMinutes -gt 10) { Remove-Item -LiteralPath $lock -Force -ErrorAction SilentlyContinue }',
+    '  }',
+    '  try { $handle = [System.IO.File]::Open($lock, [System.IO.FileMode]::CreateNew, [System.IO.FileAccess]::Write, [System.IO.FileShare]::None); $handle.Close(); $locked = $true } catch { $locked = $false }',
     '}',
-    '$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',
+    '$rolledBack = $false',
+    '$rollbackError = $null',
+    'if (-not $locked) {',
+    '  $rollbackError = \'another rollback is already running\'',
+    '} else {',
+    '  $configBackup = Join-Path $backup \'config\'',
+    '  if (Test-Path $configBackup) {',
+    '    $job = Start-Job -ScriptBlock { param($src, $dst) & robocopy $src $dst /E /NFL /NDL /NJH /NJS /NP | Out-Null } -ArgumentList $configBackup, $profile',
+    '    if (Wait-Job $job -Timeout ' + copyTimeoutSeconds + ') { Receive-Job $job | Out-Null; $rolledBack = $true } else { Stop-Job $job; $rollbackError = \'the configuration restore did not finish within ' + copyTimeout + ' ms\' }',
+    '    Remove-Job $job -Force',
+    '  }',
+    '  $pluginsBackup = Join-Path $backup \'node_modules\'',
+    '  if (Test-Path $pluginsBackup) {',
+    '    $job = Start-Job -ScriptBlock { param($src, $dst) & robocopy $src $dst /MIR /NFL /NDL /NJH /NJS /NP | Out-Null } -ArgumentList $pluginsBackup, (Join-Path $profile \'node_modules\')',
+    '    if (Wait-Job $job -Timeout ' + copyTimeoutSeconds + ') { Receive-Job $job | Out-Null; $rolledBack = $true } else { Stop-Job $job; $rollbackError = \'the plugin tree restore did not finish within ' + copyTimeout + ' ms\' }',
+    '    Remove-Job $job -Force',
+    '  }',
     '}',
     '$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 }',
+    '# `appStarted` is always false: the rollback branch restores the files and',
+    '# writes the report, it never launches a SECOND copy of the host.',
+    '$payload = [ordered]@{ ok = $false; at = (Get-Date).ToString(\'o\'); waitedMs = ' + timeout + '; rolledBack = $rolledBack; rollbackError = $rollbackError; backupDir = $backup; newPort = $newPort; appStarted = $false; 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',
+    '# The watcher cleans up after itself (and releases the lock it holds).',
+    'foreach ($p in @(' + cleanPaths.join(', ') + ')) {',
+    '  if ($p -and (Test-Path -LiteralPath $p)) { Remove-Item -LiteralPath $p -Force -ErrorAction SilentlyContinue }',
+    '}',
+    '# The lock is released by the party that HOLDS it — the one that stood',
+    '# down must not take it away from the one that is restoring.',
+    'if ($locked -and $lock -ne \'\') { Remove-Item -LiteralPath $lock -Force -ErrorAction SilentlyContinue }',
+    'exit 1',
     '',
   ];
   return lines.join('\r\n');
 }
 
+/**
+ * The command line that runs the rollback watcher as its own hidden process.
+ *
+ * @param {string} scriptPath
+ * @param {{ executable?: string }} [options]
+ * @returns {string}
+ */
+export function buildWatcherCommandLine(scriptPath, { executable = 'powershell.exe' } = {}) {
+  const file = nonEmptyString(scriptPath);
+  if (file === null) return '';
+  return executable
+    + ' -NoProfile -NonInteractive -WindowStyle Hidden -ExecutionPolicy Bypass -File "'
+    + file
+    + '"';
+}
+
+/**
+ * Write a helper script atomically: a temporary file + a rename, so a
+ * half-written script can never be executed.
+ *
+ * @param {string} file
+ * @param {string} text
+ * @returns {{ ok: boolean, error: string|null }}
+ */
+export function writeTextFileAtomic(file, text) {
+  const target = nonEmptyString(file);
+  if (target === null) return { ok: false, error: 'writeTextFileAtomic requires a path' };
+  try {
+    mkdirSync(path.dirname(target), { recursive: true });
+    const temporary = target + '.tmp';
+    writeFileSync(temporary, String(text), { encoding: 'utf8' });
+    renameSync(temporary, target);
+    return { ok: true, error: null };
+  } catch (error) {
+    return { ok: false, error: 'could not write ' + target + ': ' + errorText(error) };
+  }
+}
+
+/**
+ * Start the rollback watcher as a process that survives the death of the host.
+ *
+ * The watcher is the only thing that can confirm the new instance when the
+ * restart command kills the host itself — which is exactly what a hosted
+ * restart does. It is therefore started OUTSIDE the process tree of the host:
+ *
+ *   - on Windows through WMI (the same mechanism the detached restart uses),
+ *     with a one-shot scheduled task as the fallback;
+ *   - everywhere else through a detached child (POSIX `setsid`), which is in
+ *     its own session and therefore immune to a kill of the host's process
+ *     group.
+ *
+ * @param {{
+ *   watchScriptPath?: string|null,
+ *   watchCommand?: string|null,
+ *   taskName?: string,
+ *   timeoutMs?: number,
+ *   dryRun?: boolean,
+ *   platform?: string,
+ *   spawnFn?: Function,
+ *   execFileSyncFn?: Function,
+ * }} [options]
+ * @returns {{
+ *   ok: boolean,
+ *   method: 'wmi'|'schtasks'|'spawn'|'none',
+ *   command: string,
+ *   error: string|null,
+ *   dryRun: boolean,
+ * }}
+ */
+export function launchDetachedWatcher({
+  watchScriptPath = null,
+  watchCommand = null,
+  taskName = DEFAULT_WATCH_TASK_NAME,
+  timeoutMs = 20000,
+  dryRun = false,
+  platform = process.platform,
+  spawnFn = spawn,
+  execFileSyncFn = execFileSync,
+} = {}) {
+  const command = nonEmptyString(watchCommand) ?? buildWatcherCommandLine(watchScriptPath);
+  const task = nonEmptyString(taskName) ?? DEFAULT_WATCH_TASK_NAME;
+  const base = {
+    ok: false,
+    method: /** @type {'wmi'|'schtasks'|'spawn'|'none'} */ ('none'),
+    command,
+    error: null,
+    dryRun: dryRun === true,
+  };
+  if (command === '') {
+    return { ...base, error: 'launchDetachedWatcher requires a watcher command' };
+  }
+  if (dryRun === true) {
+    return { ...base, ok: true, method: 'none' };
+  }
+
+  if (platform === 'win32') {
+    const wmiCommand = buildWmiRestartCommand(command);
+    const schtasksCreate = ['/Create', '/SC', 'ONCE', '/ST', '23:59', '/TN', task, '/TR', command, '/F'];
+    const schtasksRun = ['/Run', '/TN', task];
+    const execOptions = { windowsHide: true, timeout: timeoutMs, stdio: 'ignore' };
+    let lastError = null;
+    try {
+      const stdout = execFileSyncFn(wmiCommand.file, wmiCommand.args, {
+        ...execOptions,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        encoding: 'utf8',
+      });
+      const match = /"ReturnValue"\s*:\s*(\d+)/.exec(String(stdout ?? ''));
+      if (match !== null && Number(match[1]) !== 0) {
+        throw new Error(`WMI Win32_Process.Create returned ReturnValue=${match[1]}`);
+      }
+      return { ...base, ok: true, method: 'wmi' };
+    } catch (error) {
+      lastError = errorText(error);
+    }
+    try {
+      execFileSyncFn('schtasks', schtasksCreate, execOptions);
+      execFileSyncFn('schtasks', schtasksRun, execOptions);
+      return { ...base, ok: true, method: 'schtasks', error: lastError };
+    } catch (error) {
+      lastError = `${lastError ? `${lastError}; ` : ''}${errorText(error)}`;
+    }
+    // The last resort: a detached child. On Windows it shares the job object
+    // of the host, so it may die with it — but a watcher that dies with the
+    // host is better than no watcher at all.
+    try {
+      const child = spawnFn(command, { shell: true, detached: true, windowsHide: true, stdio: 'ignore' });
+      if (typeof child.on === 'function') child.on('error', () => {});
+      try {
+        child.unref();
+      } catch {
+        /* nothing else to do */
+      }
+      if (typeof child.pid !== 'number') {
+        return { ...base, method: 'spawn', error: lastError || 'the watcher could not be started' };
+      }
+      return { ...base, ok: true, method: 'spawn', error: lastError };
+    } catch (error) {
+      return { ...base, method: 'spawn', error: `${lastError ? `${lastError}; ` : ''}${errorText(error)}` };
+    }
+  }
+
+  // POSIX: a detached child is its own session leader (setsid), so it survives
+  // the death of the host — even when the host is killed as a process group.
+  try {
+    const child = spawnFn(command, { shell: true, detached: true, stdio: 'ignore' });
+    if (typeof child.on === 'function') child.on('error', () => {});
+    try {
+      child.unref();
+    } catch {
+      /* nothing else to do */
+    }
+    if (typeof child.pid !== 'number') {
+      return { ...base, method: 'spawn', error: 'the watcher could not be started' };
+    }
+    return { ...base, ok: true, method: 'spawn' };
+  } catch (error) {
+    return { ...base, method: 'spawn', error: errorText(error) };
+  }
+}
+
 /**
  * Execute the detached restart. Primary method: WMI process creation. Fallback:
  * a one-shot scheduled task. Never throws.
@@ -424,26 +1051,18 @@ export function scheduleDetachedRestart({
   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) };
+    const written = writeTextFileAtomic(watchFile, watchText);
+    if (!written.ok) {
+      return { ...base, error: 'could not write the rollback watcher: ' + written.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.
-    try {
-      mkdirSync(path.dirname(scriptFile), { recursive: true });
-      const temporary = scriptFile + '.tmp';
-      writeFileSync(temporary, String(script), { encoding: 'utf8' });
-      renameSync(temporary, scriptFile);
-    } catch (error) {
-      return { ...base, error: 'could not write the gate script: ' + errorText(error) };
+    const written = writeTextFileAtomic(scriptFile, script);
+    if (!written.ok) {
+      return { ...base, error: 'could not write the gate script: ' + written.error };
     }
   }
 
@@ -496,29 +1115,177 @@ export function scheduleDetachedRestart({
  * Run a command string detached, or (with `dryRun`) just report it. Tests use
  * `dryRun` exclusively so they never kill or relaunch anything.
  *
- * @param {{ command?: string, dryRun?: boolean }} [options]
- * @returns {{ ok: boolean, command: string|null, dryRun: boolean, pid?: number|null, error?: string }}
+ * THE SUCCESS OF THE RESTART IS NOT "THE COMMAND STARTED".
+ *
+ * The old implementation spawned the command with `stdio: 'ignore'`, threw
+ * the `error` event away and answered `ok: true` as soon as the spawn
+ * succeeded. A command that does not exist (`command not found`), a command
+ * that exits with a non-zero code and a command that dies immediately were
+ * all reported as a successful restart. The host was then "restarted" into
+ * nothing, and nobody was told.
+ *
+ * This implementation answers with what actually happened:
+ *
+ *   - `exitCode` — the code the command ended with;
+ *   - `timedOut` — the command was still running when the window closed
+ *     (a command that starts the host in the foreground never returns, so this
+ *     is NOT a failure — but it is not a success either);
+ *   - `error` — the reason a failure happened (the command could not be
+ *     started at all, or it exited with a non-zero code);
+ *   - `output` — what the command printed (the tail of it), so the reason of a
+ *     failure is readable in the log.
+ *
+ * @param {{
+ *   command?: string,
+ *   dryRun?: boolean,
+ *   timeoutMs?: number,
+ *   spawnFn?: Function,
+ * }} [options]
+ * @returns {Promise<{
+ *   ok: boolean,
+ *   command: string|null,
+ *   dryRun: boolean,
+ *   pid: number|null,
+ *   exitCode: number|null,
+ *   signal: string|null,
+ *   timedOut: boolean,
+ *   error: string|null,
+ *   output: string,
+ * }>}
  */
-export function runCommandNow({ command, dryRun = false } = {}) {
+export function runCommandNow({
+  command,
+  dryRun = false,
+  timeoutMs = DEFAULT_COMMAND_TIMEOUT_MS,
+  spawnFn = spawn,
+} = {}) {
   const text = typeof command === 'string' ? command : '';
-  try {
-    if (!text.trim()) {
-      return { ok: false, command: null, dryRun: dryRun === true, error: 'runCommandNow requires a command' };
+  if (!text.trim()) {
+    return Promise.resolve({
+      ok: false,
+      command: null,
+      dryRun: dryRun === true,
+      pid: null,
+      exitCode: null,
+      signal: null,
+      timedOut: false,
+      error: 'runCommandNow requires a command',
+      output: '',
+    });
+  }
+  if (dryRun === true) {
+    return Promise.resolve({
+      ok: true,
+      command: text,
+      dryRun: true,
+      pid: null,
+      exitCode: null,
+      signal: null,
+      timedOut: false,
+      error: null,
+      output: '',
+    });
+  }
+  const budget = Number.isFinite(Number(timeoutMs)) && Number(timeoutMs) > 0
+    ? Math.trunc(Number(timeoutMs))
+    : DEFAULT_COMMAND_TIMEOUT_MS;
+
+  return new Promise((resolve) => {
+    let settled = false;
+    let output = '';
+    let timer = null;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      if (timer !== null) {
+        try {
+          clearTimeout(timer);
+        } catch {
+          /* nothing else to do */
+        }
+        timer = null;
+      }
+      resolve({
+        ok: false,
+        command: text,
+        dryRun: false,
+        pid: null,
+        exitCode: null,
+        signal: null,
+        timedOut: false,
+        error: 'the restart command did not run',
+        output,
+        ...result,
+      });
+    };
+
+    let child;
+    try {
+      child = spawnFn(text, {
+        shell: true,
+        detached: true,
+        windowsHide: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch (error) {
+      finish({ error: 'the restart command could not be started: ' + errorText(error) });
+      return;
     }
-    if (dryRun === true) {
-      return { ok: true, command: text, dryRun: true, pid: null };
+    if (!child) {
+      finish({ error: 'the restart command could not be started' });
+      return;
     }
-    const child = spawn(text, { shell: true, detached: true, windowsHide: true, stdio: 'ignore' });
-    child.on('error', () => {});
+
+    const collect = (chunk) => {
+      output = (output + String(chunk ?? '')).slice(-4096);
+    };
+    if (child.stdout && typeof child.stdout.on === 'function') child.stdout.on('data', collect);
+    if (child.stderr && typeof child.stderr.on === 'function') child.stderr.on('data', collect);
+
+    // A spawn that fails (the command does not exist) is reported — never
+    // swallowed. This is the defect the old implementation hid.
+    if (typeof child.on === 'function') {
+      child.on('error', (error) => {
+        finish({ error: 'the restart command could not be started: ' + errorText(error) });
+      });
+      child.on('exit', (code, signal) => {
+        const exitCode = Number.isFinite(Number(code)) ? Number(code) : null;
+        if (exitCode === 0) {
+          finish({ ok: true, pid: child.pid ?? null, exitCode: 0, signal: signal ?? null, error: null });
+          return;
+        }
+        const tail = output.trim();
+        finish({
+          ok: false,
+          pid: child.pid ?? null,
+          exitCode,
+          signal: signal ?? null,
+          error: 'the restart command exited with code ' + String(exitCode)
+            + (tail === '' ? '' : ': ' + tail),
+        });
+      });
+    }
+
+    // The window: the command is given this long to finish. A command that
+    // outlives it is NOT killed (it may be the host itself, running in the
+    // foreground) — it is reported as "still running", and the caller decides.
+    timer = setTimeout(() => {
+      finish({
+        ok: true,
+        pid: child.pid ?? null,
+        exitCode: null,
+        signal: null,
+        timedOut: true,
+        error: null,
+      });
+    }, budget);
+
     try {
       child.unref();
     } catch {
       /* nothing else to do */
     }
-    return { ok: true, command: text, dryRun: false, pid: child.pid ?? null };
-  } catch (error) {
-    return { ok: false, command: text || null, dryRun: dryRun === true, error: errorText(error) };
-  }
+  });
 }
 
 /**