dsh-autorestart 0.6.1 → 0.7.0

package/lib/node-runtime.js

@@ -0,0 +1,144 @@
+/**
+ * dsh-autorestart — the NODE INTERPRETER the supervisor is started with.
+ *
+ * WHY THIS FILE EXISTS:
+ *
+ * The supervisor is a plain node script. The record that starts it at login
+ * must therefore name a REAL node interpreter. `process.execPath` is NOT
+ * always node:
+ *
+ *   - in the hosted web host it is node (`/usr/bin/node`, `node.exe`);
+ *   - in the DESKTOP APP it is the Electron client
+ *     (`…\DeepSeek Harness.exe`).
+ *
+ * A login record that starts the Electron client would open a SECOND copy of
+ * the client at every login (the login record inherits the environment of the
+ * user, which does NOT carry `ELECTRON_RUN_AS_NODE=1`, so the exe starts the
+ * full application instead of running the script as node).
+ *
+ * So the interpreter is RESOLVED, never guessed:
+ *
+ *   1. the process itself IS node (the file name starts with `node`);
+ *   2. the runtime that ships with the installation
+ *      (`resources/runtime/primary-runtime/dependencies/node/bin/node.exe`);
+ *   3. the `node` of the PATH.
+ *
+ * When none of them is there the answer is "no interpreter": the caller
+ * refuses the installation and says why. The application executable is NEVER
+ * used as a stand-in for node.
+ *
+ * ESM only, Node builtins only.
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+/**
+ * The node interpreter inside the runtime that ships with the installation.
+ *
+ * It is relative to the directory of the application executable.
+ */
+export const BUNDLED_NODE_RELATIVE_PATH = Object.freeze([
+  'resources',
+  'runtime',
+  'primary-runtime',
+  'dependencies',
+  'node',
+  'bin',
+  'node.exe',
+])
+
+/**
+ * Is this file name the name of a node interpreter?
+ *
+ * `node`, `node.exe`, `node22.exe` and `nodejs` are interpreters; a directory
+ * called `node_modules` is not.
+ *
+ * @param {string} execPath
+ * @returns {boolean}
+ */
+export function isNodeExecutable(execPath) {
+  const text = String(execPath ?? '').trim()
+  if (text === '') return false
+  const base = path.basename(text).toLowerCase()
+  if (!base.startsWith('node')) return false
+  return !base.includes('node_modules')
+}
+
+/**
+ * The directories of the PATH (Windows spells it `Path` as well).
+ *
+ * @param {object} env
+ * @returns {string[]}
+ */
+function pathDirectories(env) {
+  const raw = typeof env.PATH === 'string' && env.PATH !== ''
+    ? env.PATH
+    : (typeof env.Path === 'string' ? env.Path : '')
+  if (raw === '') return []
+  return raw.split(path.delimiter).map((part) => part.trim()).filter((part) => part !== '')
+}
+
+/**
+ * Find a real node interpreter on this machine.
+ *
+ * @param {{
+ *   execPath?: string,
+ *   platform?: string,
+ *   env?: object,
+ *   existsSyncFn?: Function,
+ * }} [options]
+ * @returns {{
+ *   ok: boolean,
+ *   path: string,
+ *   source: 'process'|'install-dir'|'path'|'',
+ *   reason: string,
+ *   tried: string[],
+ * }}
+ */
+export function resolveNodeInterpreter(options = {}) {
+  const platform = typeof options.platform === 'string' ? options.platform : process.platform
+  const execPath = String(options.execPath ?? '')
+  const env = options.env && typeof options.env === 'object' ? options.env : process.env
+  const exists = typeof options.existsSyncFn === 'function' ? options.existsSyncFn : fs.existsSync
+  const tried = []
+
+  // (1) The process IS node.
+  if (isNodeExecutable(execPath)) {
+    return { ok: true, path: execPath, source: 'process', reason: '', tried }
+  }
+
+  // (2) The runtime that ships with the installation.
+  if (execPath !== '') {
+    const directory = path.dirname(execPath)
+    const candidates = platform === 'win32'
+      ? [path.join(directory, ...BUNDLED_NODE_RELATIVE_PATH)]
+      : []
+    for (const candidate of candidates) {
+      tried.push(candidate)
+      if (exists(candidate)) {
+        return { ok: true, path: candidate, source: 'install-dir', reason: '', tried }
+      }
+    }
+  }
+
+  // (3) The PATH.
+  const names = platform === 'win32' ? ['node.exe'] : ['node']
+  for (const directory of pathDirectories(env)) {
+    for (const name of names) {
+      const candidate = path.join(directory, name)
+      tried.push(candidate)
+      if (exists(candidate)) {
+        return { ok: true, path: candidate, source: 'path', reason: '', tried }
+      }
+    }
+  }
+
+  return {
+    ok: false,
+    path: '',
+    source: '',
+    reason: 'no node interpreter was found: the executable of this process is not node, the installation carries no bundled node, and the PATH has none either — the application executable is never used as a stand-in for node',
+    tried,
+  }
+}

package/lib/queued.js

@@ -0,0 +1,146 @@
+/**
+ * dsh-autorestart — the upper bound of a QUEUED inbox message.
+ *
+ * THE DEFECT THIS MODULE FIXES
+ *
+ * A queued message (an inbox entry that nobody has claimed yet) used to block
+ * the restart FOR EVER. The idle gate counted "this session has a queued
+ * message" as "this session is busy", and the hard deadline only WARNED, so a
+ * session that never ran its turn (the real case: a fresh, empty conversation
+ * in the UI with one unclaimed message in its inbox) kept the pending restart
+ * pending until the user gave up.
+ *
+ * THE POLICY
+ *
+ *   - a message that is claimed inside the grace window keeps blocking the
+ *     restart (that is the normal case: the agent picks it up in a second);
+ *   - a message that is still unclaimed after the grace window is STUCK: it
+ *     stops blocking the restart and is named in the log, so the user can see
+ *     WHICH session holds the queue;
+ *   - a message that is being worked on (the session is `running`) always
+ *     blocks, under EVERY grace setting. This module only ever judges queued
+ *     work — it never relaxes the rule that a live turn is never interrupted.
+ *
+ * The tracker knows nothing about the host: it is a map of session id to the
+ * moment the session was FIRST seen with a queued message, so it can be unit
+ * tested with a fake clock.
+ *
+ * ESM only, Node builtins only. No DSH / npm imports.
+ */
+
+/** The default upper bound of a queued message: one minute. */
+export const DEFAULT_QUEUED_GRACE_MS = 60000
+
+/** @param {unknown} value */
+function isFiniteNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value)
+}
+
+/**
+ * Normalise a grace window.
+ *
+ * A negative or non-numeric value falls back to the default; `0` is a LEGAL
+ * value — it switches the protection off and restores the old behaviour (a
+ * queued message blocks the restart for ever).
+ *
+ * @param {unknown} value
+ * @returns {number} milliseconds, never negative
+ */
+export function normalizeQueuedGraceMs(value) {
+  if (!isFiniteNumber(value) || value < 0) return DEFAULT_QUEUED_GRACE_MS
+  return Math.trunc(value)
+}
+
+/**
+ * Create the tracker.
+ *
+ * @param {{ now?: () => number }} [options] the clock (injectable for tests)
+ * @returns {{
+ *   observe: (agentId: string, queued: boolean, graceMs?: number) => { blocking: boolean, firstSeenAt: number|null, ageMs: number, becameStale: boolean },
+ *   forget: (agentId: string) => boolean,
+ *   size: () => number,
+ *   ids: () => string[],
+ * }}
+ */
+export function createQueuedTracker({ now = () => Date.now() } = {}) {
+  /** @type {Map<string, { firstSeenAt: number, stale: boolean }>} */
+  const records = new Map()
+
+  /** The current time of the injected clock (never throws). */
+  const clock = () => {
+    try {
+      const value = now()
+      return isFiniteNumber(value) ? value : 0
+    } catch {
+      return 0
+    }
+  }
+
+  /**
+   * Observe one session.
+   *
+   * @param {string} agentId the session id
+   * @param {boolean} queued does the session have an unclaimed message?
+   * @param {number} [graceMs] the upper bound (0 = no upper bound)
+   * @returns {{ blocking: boolean, firstSeenAt: number|null, ageMs: number, becameStale: boolean }}
+   */
+  const observe = (agentId, queued, graceMs) => {
+    const id = agentId == null ? '' : String(agentId)
+    if (id === '') return { blocking: false, firstSeenAt: null, ageMs: 0, becameStale: false }
+
+    // The session has no queued work any more: its record is dropped, so a
+    // NEW queue starts counting from zero.
+    if (queued !== true) {
+      records.delete(id)
+      return { blocking: false, firstSeenAt: null, ageMs: 0, becameStale: false }
+    }
+
+    const at = clock()
+    let record = records.get(id)
+    if (record === undefined) {
+      record = { firstSeenAt: at, stale: false }
+      records.set(id, record)
+    }
+    const ageMs = Math.max(0, at - record.firstSeenAt)
+    const grace = normalizeQueuedGraceMs(graceMs)
+
+    // The protection is off (grace 0): a queued message blocks the restart for
+    // ever — exactly the behaviour before this module existed.
+    if (grace === 0) {
+      return { blocking: true, firstSeenAt: record.firstSeenAt, ageMs, becameStale: false }
+    }
+
+    // Still inside the grace window: the agent may claim the message any
+    // moment, so the restart keeps waiting for it.
+    if (ageMs < grace) {
+      return { blocking: true, firstSeenAt: record.firstSeenAt, ageMs, becameStale: false }
+    }
+
+    // The message is STUCK: it stops blocking the restart. `becameStale` is
+    // true only on the tick where it turned stale, so the caller can log it
+    // exactly once.
+    const becameStale = record.stale !== true
+    record.stale = true
+    return { blocking: false, firstSeenAt: record.firstSeenAt, ageMs, becameStale }
+  }
+
+  /**
+   * Drop the record of one session (it is running, or it is gone).
+   *
+   * @param {string} agentId
+   * @returns {boolean} whether a record was dropped
+   */
+  const forget = (agentId) => {
+    const id = agentId == null ? '' : String(agentId)
+    if (id === '') return false
+    return records.delete(id)
+  }
+
+  /** How many sessions are tracked right now. */
+  const size = () => records.size
+
+  /** The ids of the tracked sessions. */
+  const ids = () => Array.from(records.keys())
+
+  return { observe, forget, size, ids }
+}

package/lib/restart-verdict.js

@@ -0,0 +1,327 @@
+/**
+ * dsh-autorestart — the durable record of ONE restart.
+ *
+ * A restart has TWO halves that live in two different processes:
+ *
+ *   - the instance that is being replaced takes the pre-restart snapshot and
+ *     then dies (the restart command kills it — that IS what restarting the
+ *     host means);
+ *   - the instance that replaces it has to prove that it really came up.
+ *
+ * Neither half can write the whole truth on its own, so the record lives in a
+ * FILE that both halves touch:
+ *
+ *   1. the OLD instance writes `result: 'pending'` BEFORE it runs the restart
+ *      command — together with the snapshot it took (directory name, how long
+ *      it took, which older snapshots were pruned);
+ *   2. the NEW instance reads that record on boot, runs the four boot checks
+ *      (listener / routes / plugin / recovery) and rewrites it as `ok` or
+ *      `failed`, with the time it verified itself and how long the whole
+ *      restart took.
+ *
+ * If the new instance never comes up, the file stays `pending` — which is
+ * exactly what the operator has to see: a restart that was started and never
+ * finished. A record that says nothing is worse than no record at all, so the
+ * verdict is ALSO exposed by `/__dsh_autorestart/health?state=1` and by the
+ * `continuum_status` tool.
+ *
+ * The time is reported in BOTH zones: the snapshot directory is named in UTC
+ * (`2026-10-29T00-25-20-779Z`), while the operator reads the wall clock of
+ * the machine (`08:25`). Comparing the two without a conversion is how a
+ * perfectly fresh snapshot looks like an eight-hour-old leftover — so the
+ * record carries the local time of the snapshot as well.
+ *
+ * ESM only, Node builtins only. No DSH / npm imports.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+/** The file the verdict lives in (inside the state directory). */
+export const RESTART_VERDICT_FILE = 'last-restart-verdict.json';
+
+/** The three results a restart can have. */
+export const RESTART_RESULTS = Object.freeze({
+  /** The restart was started; nobody confirmed it yet. */
+  PENDING: 'pending',
+  /** The new instance came up and every check passed. */
+  OK: 'ok',
+  /** The new instance came up but something did not work. */
+  FAILED: 'failed',
+});
+
+/** The four checks the new instance runs on itself. */
+export const RESTART_CHECK_NAMES = Object.freeze(['listener', 'routes', 'plugin', 'recovery']);
+
+/** @param {unknown} value */
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** @param {unknown} value */
+function isFiniteNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+/** @param {unknown} value @param {string|null} fallback */
+function nullableString(value, fallback = null) {
+  return typeof value === 'string' && value !== '' ? value : fallback;
+}
+
+/** @param {unknown} value */
+function nullableNumber(value) {
+  return isFiniteNumber(value) ? value : null;
+}
+
+/**
+ * The local time of an epoch, with the UTC offset — the time the operator
+ * sees on the machine (`2026-10-29T08:25:20+08:00`).
+ *
+ * @param {number|null|undefined} at
+ * @returns {string|null}
+ */
+export function localIsoTime(at) {
+  if (!isFiniteNumber(at)) return null;
+  const date = new Date(Number(at));
+  if (Number.isNaN(date.getTime())) return null;
+  const offsetMinutes = -date.getTimezoneOffset();
+  const sign = offsetMinutes >= 0 ? '+' : '-';
+  const absolute = Math.abs(offsetMinutes);
+  const hours = String(Math.floor(absolute / 60)).padStart(2, '0');
+  const minutes = String(absolute % 60).padStart(2, '0');
+  const local = new Date(Number(at) + offsetMinutes * 60000).toISOString();
+  return `${local.slice(0, 19)}${sign}${hours}:${minutes}`;
+}
+
+/**
+ * The snapshot part of the verdict: WHICH snapshot was taken, how long it
+ * took and which older snapshots were pruned.
+ *
+ * @param {{
+ *   requested?: boolean,
+ *   backup?: object|null,
+ *   profileDir?: string|null,
+ *   durationMs?: number|null,
+ *   error?: string|null,
+ * }} [input]
+ * @returns {object}
+ */
+export function buildSnapshotRecord({
+  requested = false,
+  backup = null,
+  profileDir = null,
+  durationMs = null,
+  error = null,
+} = {}) {
+  const taken = isObject(backup) && backup.ok === true;
+  const stamp = taken ? nullableString(backup.stamp) : null;
+  const at = taken ? nullableNumber(backup.at) : null;
+  return {
+    requested: requested === true,
+    taken,
+    dir: taken ? nullableString(backup.dir) : null,
+    stamp,
+    at,
+    // The human-readable time of the snapshot: the directory name is UTC.
+    atLocal: at === null ? null : localIsoTime(at),
+    durationMs: isFiniteNumber(durationMs) ? Math.trunc(durationMs) : null,
+    bytes: taken ? nullableNumber(backup.bytes) : null,
+    files: taken && Array.isArray(backup.files) ? backup.files.map(String) : [],
+    pruned: taken && Array.isArray(backup.pruned) ? backup.pruned.map(String) : [],
+    profileDir: nullableString(profileDir),
+    error: nullableString(error) ?? (taken ? null : (nullableString(isObject(backup) ? backup.error : null) ?? 'the snapshot was not taken')),
+  };
+}
+
+/**
+ * Normalize one boot check.
+ *
+ * @param {unknown} raw
+ * @returns {{ name: string, ok: boolean, detail: string|null }}
+ */
+function normalizeCheck(raw) {
+  if (!isObject(raw)) return { name: 'unknown', ok: false, detail: null };
+  return {
+    name: typeof raw.name === 'string' && raw.name !== '' ? raw.name : 'unknown',
+    ok: raw.ok === true,
+    detail: nullableString(raw.detail),
+  };
+}
+
+/**
+ * Build a verdict record from a loose input.
+ *
+ * @param {{
+ *   result?: string,
+ *   mode?: string|null,
+ *   generation?: number|null,
+ *   requestedAt?: number|null,
+ *   startedAt?: number|null,
+ *   verifiedAt?: number|null,
+ *   durationMs?: number|null,
+ *   bootId?: string|null,
+ *   previousBootId?: string|null,
+ *   snapshot?: object|null,
+ *   checks?: any[],
+ *   reason?: string|null,
+ *   now?: number,
+ * }} [input]
+ * @returns {object}
+ */
+export function buildRestartVerdict(input = {}) {
+  const now = isFiniteNumber(input.now) ? Number(input.now) : Date.now();
+  const result = input.result === RESTART_RESULTS.OK
+    ? RESTART_RESULTS.OK
+    : input.result === RESTART_RESULTS.FAILED
+      ? RESTART_RESULTS.FAILED
+      : RESTART_RESULTS.PENDING;
+  const startedAt = nullableNumber(input.startedAt);
+  const verifiedAt = nullableNumber(input.verifiedAt);
+  const durationMs = isFiniteNumber(input.durationMs)
+    ? Math.trunc(Number(input.durationMs))
+    : (startedAt !== null && verifiedAt !== null ? Math.max(0, verifiedAt - startedAt) : null);
+  const snapshot = isObject(input.snapshot) ? input.snapshot : buildSnapshotRecord({ requested: false });
+  return {
+    result,
+    mode: nullableString(input.mode),
+    generation: nullableNumber(input.generation),
+    requestedAt: nullableNumber(input.requestedAt),
+    startedAt,
+    verifiedAt,
+    durationMs,
+    bootId: nullableString(input.bootId),
+    previousBootId: nullableString(input.previousBootId),
+    snapshot: {
+      requested: snapshot.requested === true,
+      taken: snapshot.taken === true,
+      dir: nullableString(snapshot.dir),
+      stamp: nullableString(snapshot.stamp),
+      at: nullableNumber(snapshot.at),
+      atLocal: nullableString(snapshot.atLocal),
+      durationMs: nullableNumber(snapshot.durationMs),
+      bytes: nullableNumber(snapshot.bytes),
+      files: Array.isArray(snapshot.files) ? snapshot.files.map(String) : [],
+      pruned: Array.isArray(snapshot.pruned) ? snapshot.pruned.map(String) : [],
+      profileDir: nullableString(snapshot.profileDir),
+      error: nullableString(snapshot.error),
+    },
+    checks: Array.isArray(input.checks) ? input.checks.map(normalizeCheck) : [],
+    reason: nullableString(input.reason),
+    updatedAt: now,
+  };
+}
+
+/**
+ * The verdict of a set of checks: `ok` only when EVERY check passed.
+ *
+ * @param {any[]} checks
+ * @returns {{ ok: boolean, failed: string[], passed: string[] }}
+ */
+export function evaluateRestartChecks(checks) {
+  const list = Array.isArray(checks) ? checks : [];
+  const failed = []
+  const passed = []
+  for (const check of list) {
+    const normalized = normalizeCheck(check)
+    if (normalized.ok) passed.push(normalized.name)
+    else failed.push(normalized.name)
+  }
+  return { ok: failed.length === 0 && list.length > 0, failed, passed }
+}
+
+/**
+ * Write the verdict into the state directory (atomically: a temporary file
+ * plus a rename, so a half-written record can never be read).
+ *
+ * @param {string} stateDir
+ * @param {object} verdict
+ * @returns {{ ok: boolean, path: string, error: string|null }}
+ */
+export function writeRestartVerdict(stateDir, verdict) {
+  const dir = typeof stateDir === 'string' ? stateDir.trim() : '';
+  if (dir === '') return { ok: false, path: '', error: 'writeRestartVerdict requires stateDir' };
+  const target = path.join(dir, RESTART_VERDICT_FILE);
+  const record = buildRestartVerdict(verdict)
+  try {
+    fs.mkdirSync(dir, { recursive: true })
+    const temporary = `${target}.tmp-${randomBytes(6).toString('hex')}`
+    fs.writeFileSync(temporary, `${JSON.stringify(record, null, 2)}\n`, 'utf8')
+    fs.renameSync(temporary, target)
+    return { ok: true, path: target, error: null }
+  } catch (error) {
+    return {
+      ok: false,
+      path: target,
+      error: String(error && error.message ? error.message : error),
+    }
+  }
+}
+
+/**
+ * Read the verdict of the last restart. Never throws: an unreadable or
+ * corrupt record is reported as `null` (there is nothing to show).
+ *
+ * @param {string} stateDir
+ * @returns {object|null}
+ */
+export function readRestartVerdict(stateDir) {
+  const dir = typeof stateDir === 'string' ? stateDir.trim() : '';
+  if (dir === '') return null;
+  try {
+    let text = fs.readFileSync(path.join(dir, RESTART_VERDICT_FILE), 'utf8')
+    if (text.charCodeAt(0) === 0xfeff) text = text.slice(1)
+    const parsed = JSON.parse(text)
+    if (!isObject(parsed)) return null
+    return buildRestartVerdict(parsed)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Remove the verdict (used when a fresh restart cycle starts).
+ *
+ * @param {string} stateDir
+ * @returns {boolean} whether a record was removed
+ */
+export function clearRestartVerdict(stateDir) {
+  const dir = typeof stateDir === 'string' ? stateDir.trim() : '';
+  if (dir === '') return false;
+  try {
+    fs.rmSync(path.join(dir, RESTART_VERDICT_FILE), { force: true })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * The compact shape of the verdict that the health route and the status tool
+ * report. It is deliberately flat: a UI (or a human with `curl`) has to read
+ * it without knowing the internals.
+ *
+ * @param {object|null} verdict
+ * @returns {object|null}
+ */
+export function summarizeRestartVerdict(verdict) {
+  if (!isObject(verdict)) return null
+  const record = buildRestartVerdict(verdict)
+  const failed = record.checks.filter((check) => !check.ok).map((check) => check.name)
+  return {
+    result: record.result,
+    mode: record.mode,
+    generation: record.generation,
+    requestedAt: record.requestedAt,
+    startedAt: record.startedAt,
+    verifiedAt: record.verifiedAt,
+    durationMs: record.durationMs,
+    bootId: record.bootId,
+    previousBootId: record.previousBootId,
+    snapshot: record.snapshot,
+    checks: record.checks,
+    failedChecks: failed,
+    reason: record.reason,
+    updatedAt: record.updatedAt,
+  }
+}