dsh-autorestart 0.6.1 → 0.7.0

package/lib/sleep.js

@@ -30,11 +30,17 @@
 import { spawn as spawnProcess } from 'node:child_process';
 import fs from 'node:fs';
 
-/** The Windows shutdown binary as it is reachable from WSL. */
-export const WSL_SHUTDOWN_EXE = '/mnt/c/Windows/System32/shutdown.exe';
+import { blockerTaskKeys, countBlockerTasks } from './blockers.js';
+import { detectHostKind, detectWslEvidence, HOST_KINDS, WSL_PROC_VERSION, WSL_SHUTDOWN_EXE } from './host-kind.js';
 
-/** The file that tells a WSL kernel from a real Linux kernel. */
-export const WSL_PROC_VERSION = '/proc/version';
+/**
+ * The Windows shutdown binary as it is reachable from WSL.
+ *
+ * The detection itself lives in `host-kind.js` (the shutdown and the autostart
+ * halves of the plugin must agree on what machine this is); it is re-exported
+ * here so the old import path keeps working.
+ */
+export { WSL_SHUTDOWN_EXE, WSL_PROC_VERSION, detectWslEvidence };
 
 /** How many seconds the countdown lasts by default. */
 export const DEFAULT_COUNTDOWN_SECONDS = 20;
@@ -119,41 +125,6 @@ export function snapCountdownChoice(value) {
   return best;
 }
 
-/**
- * The evidence that this Linux is really a WSL distribution.
- *
- * Any ONE of them is enough:
- *   1. `WSL_DISTRO_NAME` is set (WSL exports it into every process),
- *   2. `WSL_INTEROP` is set (WSL exports it into every process),
- *   3. `/proc/version` mentions "microsoft" (the WSL kernel says so),
- *   4. the Windows shutdown binary is reachable under `/mnt/c`.
- *
- * @param {object} env
- * @param {(file: string) => string} readFile
- * @param {(file: string) => boolean} exists
- * @returns {string|null} the name of the evidence, or null
- */
-export function detectWslEvidence(env, readFile, exists) {
-  const environ = env && typeof env === 'object' ? env : {};
-  if (nonEmptyString(environ.WSL_DISTRO_NAME) !== '') return 'WSL_DISTRO_NAME';
-  if (nonEmptyString(environ.WSL_INTEROP) !== '') return 'WSL_INTEROP';
-  let version = '';
-  try {
-    version = String(readFile(WSL_PROC_VERSION) || '');
-  } catch {
-    version = '';
-  }
-  if (version.toLowerCase().includes('microsoft')) return WSL_PROC_VERSION;
-  let found = false;
-  try {
-    found = exists(WSL_SHUTDOWN_EXE) === true;
-  } catch {
-    found = false;
-  }
-  if (found) return WSL_SHUTDOWN_EXE;
-  return null;
-}
-
 /**
  * Detect the host and build the command that switches the physical machine off.
  *
@@ -203,12 +174,12 @@ export function detectShutdownPlan({
   }
 
   if (plat === 'linux') {
-    const evidence = detectWslEvidence(env, readFileSafe, existsSafe);
-    if (evidence !== null) {
+    const host = detectHostKind({ platform: plat, env, readFile: readFileSafe, exists: existsSafe });
+    if (host.kind === HOST_KINDS.WSL) {
       // The mounted Windows binary is only a HINT: a real Linux with a
       // manually mounted C: drive looks exactly the same. When that is the
       // only evidence, the plan says so instead of pretending to be sure.
-      const suspect = evidence === WSL_SHUTDOWN_EXE;
+      const suspect = host.suspect === true;
       return {
         kind: 'wsl',
         label: suspect
@@ -216,7 +187,7 @@ export function detectShutdownPlan({
           : 'WSL 里的 DSH → 关掉整台 Windows',
         source: suspect
           ? `${WSL_SHUTDOWN_EXE}（疑似 WSL，仅凭 /mnt/c 探测）`
-          : evidence,
+          : host.evidence,
         // The Windows binary, reached through the mounted C: drive: this shuts
         // the whole machine down, not the WSL distribution.
         command: WSL_SHUTDOWN_EXE,
@@ -550,9 +521,14 @@ export function createSleepController({
    * that created the subagent). A raw session id never reaches the
    * interface: an unknown name is a generic one.
    *
+   * `parentSessionId` is kept: it is the exact identity of the session that
+   * created a subagent, so the card can count a parent and its subagents as
+   * ONE task (the rule of `lib/blockers.js`). It is null when the Host did
+   * not report one — the title is then the fallback.
+   *
    * @param {any} entry the entry the Host produced
    * @param {string} sessionId
-   * @returns {{ sessionId: string, kind: string, label: string|null, name: string, parentTitle: string|null, title: string }}
+   * @returns {{ sessionId: string, kind: string, label: string|null, name: string, parentTitle: string|null, parentSessionId: string|null, title: string }}
    */
   const blockerEntry = (entry, sessionId) => {
     const kind = entry.kind === 'subagent' ? 'subagent' : 'session';
@@ -569,12 +545,17 @@ export function createSleepController({
     // writes the generic line when the name is empty.
     if (name === '') name = label;
     const parentTitle = typeof entry.parentTitle === 'string' ? entry.parentTitle.trim() : '';
+    const parentSessionId = typeof entry.parentSessionId === 'string' ? entry.parentSessionId.trim() : '';
     return {
       sessionId,
       kind,
       label: label !== '' ? label : null,
       name,
       parentTitle: parentTitle !== '' ? parentTitle : null,
+      // The identity of the session that created the subagent: it is what lets
+      // the card count a parent and its subagents as ONE task. It is only
+      // there when the Host knows it — a plain session keeps its old shape.
+      ...(parentSessionId !== '' ? { parentSessionId } : {}),
       // `title` is the old name of `label`: it stays, so an older client
       // keeps working.
       title: label !== '' ? label : name,
@@ -686,18 +667,31 @@ export function createSleepController({
    * bug, so a list with a nameless entry in it is left out entirely: the
    * caller then writes the line without the parenthetical.
    *
+   * The names are the names of the TASKS: a session and its own subagents are
+   * ONE task, and it is named after the session itself (after its subagent
+   * when the session is idle and only the subagent works). So the list has as
+   * many names as the count has tasks.
+   *
    * @param {any[]} list
    * @returns {string} the joined names, or '' when the list cannot be named
    */
   const names = (list) => {
-    const out = [];
-    for (const entry of Array.isArray(list) ? list : []) {
+    const entries = Array.isArray(list) ? list : [];
+    const keys = blockerTaskKeys(entries);
+    const byTask = new Map();
+    for (let index = 0; index < entries.length; index += 1) {
+      const entry = entries[index];
       const label = entry && typeof entry.label === 'string' ? entry.label.trim() : '';
       const name = entry && typeof entry.name === 'string' ? entry.name.trim() : '';
       if (label === '' || name === '') return '';
-      out.push(name);
+      const key = keys[index] !== '' ? keys[index] : ('entry:' + index);
+      const isSubagent = entry.kind === 'subagent';
+      const known = byTask.get(key);
+      if (!known || (known.isSubagent && !isSubagent)) {
+        byTask.set(key, { name, isSubagent });
+      }
     }
-    return out.join('、');
+    return Array.from(byTask.values()).map((item) => item.name).join('、');
   };
 
   /**
@@ -707,12 +701,15 @@ export function createSleepController({
    * - one blocker with a title → the singular form ("等「甲」收工");
    * - otherwise → the plain count, without a parenthetical.
    *
+   * The count is about TASKS: a session and its own subagents are ONE task
+   * (the rule of `lib/blockers.js`), the same number the left sidebar shows.
+   *
    * @param {any[]} list the blockers
    * @param {{ immediate?: boolean }} options `immediate` = no countdown at all
    * @returns {string}
    */
   const waitingFor = (list, { immediate = false } = {}) => {
-    const count = Array.isArray(list) ? list.length : 0;
+    const count = countBlockerTasks(list);
     const tail = immediate ? '收工后立即关机。' : '收工后开始倒数。';
     const named = names(list);
     if (count === 1 && named !== '') return `等「${named}」收工，${tail}`;

package/lib/startup-mode.js

@@ -0,0 +1,491 @@
+/**
+ * dsh-autorestart — HOW THIS HOST WAS STARTED.
+ *
+ * A hosted web host can be started in a dozen ways, and the plugin has to
+ * behave correctly in EVERY one of them:
+ *
+ *   | # | how it was started                          | what the plugin does            |
+ *   |---|---------------------------------------------|---------------------------------|
+ *   | 1 | a plain terminal (`dsh web`)                | own supervisor MAY be installed |
+ *   | 2 | `nohup … &` / `setsid` (detached)          | same, but the replay is detached|
+ *   | 3 | a supervisor script (`supervise-*.sh`)      | external → graceful exit only   |
+ *   | 4 | a systemd unit                              | external                        |
+ *   | 5 | pm2 / forever                               | external                        |
+ *   | 6 | docker / compose / kubernetes                | no "at login"; compose fragment |
+ *   | 7 | a Windows scheduled task / NSSM service     | external                        |
+ *   | 8 | WSL, started by a Windows process           | unknown (the parent is invisible)|
+ *   | 9 | `npx` / `pnpm dlx`                          | usable if the argv can be restored|
+ *   |10 | another DSH plugin spawned it               | external/unknown → never a second|
+ *   |11 | tmux / screen / an SSH session              | replay, but detached from the session |
+ *
+ * THE TWO RULES THAT MATTER MORE THAN THE TABLE:
+ *
+ *   1. **NEVER START A SECOND HOST.** Only a `bare` host may get a
+ *      self-replay command, and only a `bare` host may get the supervisor of
+ *      this plugin. Everything else is somebody else's business.
+ *   2. **WHEN IN DOUBT, BE CONSERVATIVE.** An `unknown` host gets
+ *      `selfReplay: 'unknown'` and NO supervisor: the plugin would rather
+ *      say "I cannot tell" than start a second host next to the first.
+ *
+ * The classifier is a PURE function: the process chain, the environment and
+ * the container markers are injected, so every row of the table can be
+ * tested without a machine.
+ *
+ * ESM only, Node builtins only.
+ */
+
+/** The modes the classifier can answer. */
+export const STARTUP_MODES = Object.freeze({
+  /** The desktop app: it relaunches itself. */
+  DESKTOP: 'desktop',
+  /** The supervisor of THIS plugin started the instance. */
+  SELF_SUPERVISED: 'self-supervised',
+  /** Somebody else (systemd, pm2, a script, a service, another plugin). */
+  EXTERNAL: 'external',
+  /** Nobody manages it: a terminal, a detached process, a session. */
+  BARE: 'bare',
+  /** A container: the orchestrator decides, not the machine. */
+  CONTAINER: 'container',
+  /** It could not be established. */
+  UNKNOWN: 'unknown',
+})
+
+/** The kinds of a startup mode (the finer answer). */
+export const STARTUP_KINDS = Object.freeze({
+  DESKTOP_APP: 'desktop-app',
+  OWN_SUPERVISOR: 'dsh-autorestart-supervisor',
+  SYSTEMD: 'systemd',
+  PM2: 'pm2',
+  FOREVER: 'forever',
+  SCRIPT: 'script',
+  WINDOWS_TASK: 'windows-task',
+  WINDOWS_SERVICE: 'windows-service',
+  DSH_PLUGIN: 'dsh-plugin',
+  DOCKER: 'docker',
+  KUBERNETES: 'kubernetes',
+  TERMINAL: 'terminal',
+  DETACHED: 'detached',
+  SESSION: 'session',
+  PACKAGE_RUNNER: 'package-runner',
+  WSL_FROM_WINDOWS: 'wsl-from-windows',
+  OPAQUE_WRAPPER: 'opaque-wrapper',
+  UNREADABLE_CHAIN: 'unreadable-chain',
+})
+
+/** The reason codes of the derivation that follow from a startup mode. */
+export const STARTUP_REASONS = Object.freeze({
+  DESKTOP: 'desktop-app',
+  OWN_SUPERVISOR: 'supervised',
+  EXTERNAL: 'external-supervisor',
+  BARE: 'ok',
+  CONTAINER: 'container-no-init',
+  UNKNOWN: 'unknown-startup',
+})
+
+/**
+ * The environment markers of the common supervisors.
+ *
+ * They are cheap, exact and need no process tree.
+ */
+const SUPERVISOR_ENV_MARKERS = Object.freeze([
+  { key: 'INVOCATION_ID', kind: STARTUP_KINDS.SYSTEMD, label: 'a systemd unit' },
+  { key: 'pm_id', kind: STARTUP_KINDS.PM2, label: 'pm2' },
+  { key: 'PM2_HOME', kind: STARTUP_KINDS.PM2, label: 'pm2' },
+])
+
+/**
+ * The ancestors that mean "somebody else is in charge".
+ *
+ * The ORDER does not matter here: an external match ANYWHERE in the chain
+ * wins, because the nearest ancestor may be a plain shell that a supervisor
+ * started (`systemd → bash → dsh web`).
+ */
+const EXTERNAL_ANCESTORS = Object.freeze([
+  { kind: STARTUP_KINDS.SYSTEMD, pattern: /systemd/i, label: 'a systemd unit' },
+  { kind: STARTUP_KINDS.PM2, pattern: /\bpm2\b/i, label: 'pm2' },
+  { kind: STARTUP_KINDS.FOREVER, pattern: /\bforever\b/i, label: 'forever' },
+  {
+    kind: STARTUP_KINDS.SCRIPT,
+    pattern: /supervise[-_][\w.-]*\.(sh|bash|py|js)|supervisord|\brunsv\b|\bs6-supervise\b|\bmonit\b/i,
+    label: 'a supervisor script',
+  },
+  { kind: STARTUP_KINDS.WINDOWS_SERVICE, pattern: /\bnssm(\.exe)?\b/i, label: 'a Windows service (NSSM)' },
+  {
+    kind: STARTUP_KINDS.WINDOWS_TASK,
+    pattern: /\bsvchost(\.exe)?\b|\btaskhostw(\.exe)?\b/i,
+    label: 'the Windows side (a scheduled task or a service)',
+  },
+  {
+    kind: STARTUP_KINDS.DSH_PLUGIN,
+    pattern: /[\\/]plugins[\\/][^\\/]+[\\/]/i,
+    label: 'another DSH plugin',
+  },
+])
+
+/** The ancestors that mean "a session" (not a supervisor, but not free either). */
+const SESSION_ANCESTORS = Object.freeze([
+  { pattern: /\btmux\b/i, label: 'a tmux session' },
+  { pattern: /\bscreen\b/i, label: 'a screen session' },
+  { pattern: /\bsshd\b|\bssh\b/i, label: 'an SSH session' },
+])
+
+/** The ancestors that mean "the command was detached from its shell". */
+const DETACHED_ANCESTORS = Object.freeze([
+  { pattern: /\bnohup\b/i, label: 'a nohup command' },
+  { pattern: /\bsetsid\b/i, label: 'a setsid command' },
+])
+
+/** The ancestors that mean "a human started it in a terminal". */
+const TERMINAL_ANCESTORS = Object.freeze([
+  { pattern: /\b(bash|sh|zsh|fish|dash|ksh|csh|tcsh)\b/i, label: 'a shell' },
+  { pattern: /\b(cmd(\.exe)?|powershell(\.exe)?|pwsh(\.exe)?|conhost(\.exe)?|WindowsTerminal(\.exe)?)\b/i, label: 'a Windows terminal' },
+])
+
+/** The package runners that may hide the real command line. */
+const PACKAGE_RUNNERS = Object.freeze([
+  { pattern: /^(npx|pnpm|npm|yarn|bunx|dlx)(\.cmd|\.exe|\.ps1)?$/i, label: 'a package runner' },
+])
+
+/** The places in a path that say "a package runner was here". */
+const PACKAGE_RUNNER_PATHS = Object.freeze([
+  /[\\/]_npx[\\/]/i,
+  /[\\/]\.pnpm[\\/]/i,
+  /[\\/]node_modules[\\/]\.bin[\\/]/i,
+  /[\\/]node_modules[\\/][^\\/]+[\\/]bin[\\/]/i,
+])
+
+/**
+ * The text of one ancestor (the image name and the command line).
+ *
+ * @param {{ imageName?: string, commandLine?: string }} entry
+ * @returns {string}
+ */
+function ancestorText(entry) {
+  if (!entry || typeof entry !== 'object') return ''
+  return [entry.imageName ?? '', entry.commandLine ?? ''].filter(Boolean).join(' ')
+}
+
+/**
+ * The evidence of one ancestor: what it is and how it was found.
+ *
+ * @param {{ pid?: number, imageName?: string, commandLine?: string }} entry
+ * @returns {string}
+ */
+function ancestorEvidence(entry) {
+  const pid = Number(entry?.pid)
+  const text = ancestorText(entry).trim()
+  return 'ancestor:' + (Number.isFinite(pid) ? pid : '?') + ': ' + (text === '' ? '?' : text)
+}
+
+/**
+ * The first ancestor that matches one of the patterns.
+ *
+ * @param {Array<object>} chain
+ * @param {Array<{ pattern: RegExp, label: string, kind?: string }>} patterns
+ * @returns {{ entry: object, label: string, kind: string }|null}
+ */
+function firstMatch(chain, patterns) {
+  for (const entry of chain) {
+    const text = ancestorText(entry)
+    if (text === '') continue
+    for (const rule of patterns) {
+      if (rule.pattern.test(text)) {
+        return { entry, label: rule.label, kind: rule.kind ?? '' }
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * Is this a WSL instance?
+ *
+ * @param {object} env
+ * @returns {boolean}
+ */
+export function isWsl(env) {
+  if (!env || typeof env !== 'object') return false
+  if (typeof env.WSL_DISTRO_NAME === 'string' && env.WSL_DISTRO_NAME !== '') return true
+  if (typeof env.WSL_INTEROP === 'string' && env.WSL_INTEROP !== '') return true
+  return false
+}
+
+/**
+ * Can the real command line be restored?
+ *
+ * A package runner (`npx dsh web`) starts the host with the RESOLVED script
+ * path in `argv[1]` — that is replayable. A wrapper that erased the command
+ * line is not: the plugin must not guess which script it was.
+ *
+ * @param {{ argv?: string[], execPath?: string }} options
+ * @returns {{ ok: boolean, kind: string, label: string, reason: string }}
+ */
+export function inspectCommandLine(options = {}) {
+  const argv = Array.isArray(options.argv) ? options.argv.map(String) : []
+  const execPath = String(options.execPath ?? '')
+  const script = String(argv[1] ?? '').trim()
+  const runner = PACKAGE_RUNNERS.find((rule) => (
+    rule.pattern.test(argv[0] ?? '') || rule.pattern.test(execPath.split(/[\\/]/).pop() ?? '')
+  ))
+  const runnerInPath = PACKAGE_RUNNER_PATHS.some((rule) => rule.test(script))
+  if (runner === undefined && !runnerInPath) {
+    // Not a package runner: the command line is used as it is.
+    if (script === '') {
+      return { ok: false, kind: STARTUP_KINDS.OPAQUE_WRAPPER, label: 'an unreadable command line', reason: 'the command line of this host cannot be read back' }
+    }
+    return { ok: true, kind: '', label: '', reason: '' }
+  }
+  const label = runner !== undefined ? runner.label : 'a package runner'
+  // A package runner: the resolved script path must be there, or nothing can
+  // be replayed.
+  if (script !== '' && (/[\\/]/.test(script) || /\.(mjs|cjs|js)$/i.test(script))) {
+    return { ok: true, kind: STARTUP_KINDS.PACKAGE_RUNNER, label, reason: '' }
+  }
+  return {
+    ok: false,
+    kind: STARTUP_KINDS.OPAQUE_WRAPPER,
+    label,
+    reason: 'this host was started through ' + label + ', and the real command line cannot be restored: nothing is guessed',
+  }
+}
+
+/**
+ * The command that starts the host again, DETACHED from the shell that runs
+ * it.
+ *
+ * A host that was started with `nohup … &` (or inside a tmux/ssh session)
+ * must not die with the shell that runs the command: the new host has to
+ * outlive it.
+ *
+ * @param {string} command
+ * @param {string} platform
+ * @returns {string}
+ */
+export function detachCommand(command, platform) {
+  const text = String(command ?? '').trim()
+  if (text === '') return ''
+  if (platform === 'win32') return 'start "" /B ' + text
+  return 'setsid nohup ' + text + ' >/dev/null 2>&1 &'
+}
+
+/**
+ * Classify HOW this host was started.
+ *
+ * @param {{
+ *   platform?: string,
+ *   env?: object,
+ *   ppid?: number,
+ *   isDesktopApp?: boolean,
+ *   supervised?: boolean,
+ *   container?: boolean,
+ *   argv?: string[],
+ *   execPath?: string,
+ *   chain?: Array<object>,
+ *   readChain?: Function,
+ * }} [options]
+ * @returns {{
+ *   mode: string,
+ *   kind: string,
+ *   evidence: string,
+ *   selfReplay: 'allowed'|'refused'|'unknown'|'n/a',
+ *   canInstallSupervisor: boolean,
+ *   detachCommand: boolean,
+ *   suggestion: string,
+ *   chain: Array<object>,
+ * }}
+ */
+export function classifyStartup(options = {}) {
+  const platform = typeof options.platform === 'string' ? options.platform : process.platform
+  const env = options.env && typeof options.env === 'object' ? options.env : process.env
+  const chain = Array.isArray(options.chain)
+    ? options.chain
+    : readChainSafely(options)
+  const wsl = options.wsl === true || (options.wsl === undefined && isWsl(env))
+
+  const answer = (mode, kind, evidence, selfReplay, canInstallSupervisor, suggestion, extra = {}) => ({
+    mode,
+    kind,
+    evidence,
+    selfReplay,
+    canInstallSupervisor,
+    detachCommand: extra.detachCommand === true,
+    suggestion,
+    chain,
+  })
+
+  // (1) THE DESKTOP APP. It relaunches itself; nobody may install anything.
+  if (options.isDesktopApp === true) {
+    return answer(
+      STARTUP_MODES.DESKTOP,
+      STARTUP_KINDS.DESKTOP_APP,
+      'the executable of this process is the desktop client',
+      'n/a',
+      false,
+      'the desktop app relaunches itself (restartMode: app) — there is no supervisor to install and no command to write',
+    )
+  }
+
+  // (2) OUR OWN SUPERVISOR started this instance: the restart is asked of it.
+  if (options.supervised === true) {
+    return answer(
+      STARTUP_MODES.SELF_SUPERVISED,
+      STARTUP_KINDS.OWN_SUPERVISOR,
+      'the environment marker DSH_AUTORESTART_SUPERVISED says who started this instance',
+      'n/a',
+      false,
+      'the supervisor of this plugin is in charge: the restart is handed to it',
+    )
+  }
+
+  // (3) A CONTAINER. There is no "at login" inside a container; the
+  // orchestrator decides (compose: restart: always).
+  if (options.container === true) {
+    const kubernetes = typeof env.KUBERNETES_SERVICE_HOST === 'string' && env.KUBERNETES_SERVICE_HOST !== ''
+    return answer(
+      STARTUP_MODES.CONTAINER,
+      kubernetes ? STARTUP_KINDS.KUBERNETES : STARTUP_KINDS.DOCKER,
+      kubernetes ? 'the environment marker KUBERNETES_SERVICE_HOST' : 'the container markers of this process',
+      'refused',
+      false,
+      'this host runs in a container: there is no "at login" here — the orchestrator brings it back (compose: restart: always)',
+    )
+  }
+
+  // (4) THE ENVIRONMENT MARKERS of the common supervisors.
+  for (const marker of SUPERVISOR_ENV_MARKERS) {
+    const value = env[marker.key]
+    if (typeof value === 'string' && value !== '') {
+      return answer(
+        STARTUP_MODES.EXTERNAL,
+        marker.kind,
+        'env:' + marker.key,
+        'refused',
+        false,
+        'this host is started by ' + marker.label + ' — it brings the host back, so the plugin only exits gracefully',
+      )
+    }
+  }
+
+  // (5) THE PROCESS CHAIN. An external match ANYWHERE in the chain wins: the
+  // nearest ancestor may be a plain shell that a supervisor started.
+  const external = firstMatch(chain, EXTERNAL_ANCESTORS)
+  if (external !== null) {
+    return answer(
+      STARTUP_MODES.EXTERNAL,
+      external.kind === '' ? STARTUP_KINDS.SCRIPT : external.kind,
+      ancestorEvidence(external.entry),
+      'refused',
+      false,
+      'this host is started by ' + external.label + ' — it brings the host back, so the plugin only exits gracefully',
+    )
+  }
+
+  // (6) WSL: a host that the WINDOWS side started has no visible parent
+  // here. It must NOT be treated as a bare host.
+  if (wsl && (chain.length === 0 || chain.every((entry) => Number(entry.pid) <= 1))) {
+    return answer(
+      STARTUP_MODES.UNKNOWN,
+      STARTUP_KINDS.WSL_FROM_WINDOWS,
+      chain.length === 0
+        ? 'the parent chain cannot be read (in WSL the Windows side is invisible)'
+        : 'the nearest ancestor is the WSL init — the Windows side that started it is invisible',
+      'unknown',
+      false,
+      'this host runs in WSL and was started by a Windows process: the parent is invisible here — pick the plain terminal (install your own supervisor) or configure the start command yourself',
+    )
+  }
+
+  // (7) THE COMMAND LINE. A package runner that hid the real command line
+  // cannot be replayed — and must not be guessed.
+  const command = inspectCommandLine({ argv: options.argv, execPath: options.execPath })
+  if (!command.ok) {
+    return answer(
+      STARTUP_MODES.UNKNOWN,
+      command.kind,
+      command.reason,
+      'unknown',
+      false,
+      'this host was started through ' + command.label + ' and the real command line cannot be restored: nothing is guessed, and no supervisor is installed',
+    )
+  }
+
+  // (8) A SESSION (tmux / screen / ssh): nobody restarts the host, so a
+  // replay is possible — but it must be detached from the session.
+  const session = firstMatch(chain, SESSION_ANCESTORS)
+  if (session !== null) {
+    return answer(
+      STARTUP_MODES.BARE,
+      STARTUP_KINDS.SESSION,
+      ancestorEvidence(session.entry),
+      'allowed',
+      true,
+      'this host runs in ' + session.label + ': nobody brings it back, so the restart command must be detached from the session (setsid/nohup) and needs your confirmation',
+      { detachCommand: true },
+    )
+  }
+
+  // (9) A DETACHED start (`nohup … &`): nobody brings it back either, but
+  // the replay must not die with the shell that runs it.
+  const detached = firstMatch(chain, DETACHED_ANCESTORS)
+  if (detached !== null) {
+    return answer(
+      STARTUP_MODES.BARE,
+      STARTUP_KINDS.DETACHED,
+      ancestorEvidence(detached.entry),
+      'allowed',
+      true,
+      'this host was started detached (' + detached.label + '): the restart command must outlive the shell that runs it (setsid/nohup)',
+      { detachCommand: true },
+    )
+  }
+
+  // (10) A PLAIN TERMINAL: nobody manages it. This is the only case in
+  // which the plugin may install its own supervisor.
+  if (chain.length > 0) {
+    const nearest = chain[0]
+    const terminal = firstMatch(chain, TERMINAL_ANCESTORS)
+    const label = terminal !== null ? terminal.label : 'the process that started it'
+    return answer(
+      STARTUP_MODES.BARE,
+      command.kind === STARTUP_KINDS.PACKAGE_RUNNER ? STARTUP_KINDS.PACKAGE_RUNNER : STARTUP_KINDS.TERMINAL,
+      'parent:' + (Number.isFinite(Number(nearest.pid)) ? nearest.pid : '?') + ': '
+        + (nearest.imageName !== '' ? nearest.imageName : label)
+        + (command.kind === STARTUP_KINDS.PACKAGE_RUNNER ? ' (' + command.label + ')' : ''),
+      'allowed',
+      true,
+      'this host was started by hand in ' + label + ': nobody brings it back, so the plugin may install its own supervisor — or write down the command that starts it again (after your confirmation)',
+    )
+  }
+
+  // (11) NOTHING COULD BE READ. Say so, and stay conservative.
+  return answer(
+    STARTUP_MODES.UNKNOWN,
+    STARTUP_KINDS.UNREADABLE_CHAIN,
+    platform === 'win32'
+      ? 'the process table of Windows could not be read: who starts this host is unknown'
+      : 'the parent chain cannot be read: who starts this host is unknown',
+    'unknown',
+    false,
+    'it could not be established who starts this host: nothing is written and no supervisor is installed',
+  )
+}
+
+/**
+ * Read the parent chain without ever throwing.
+ *
+ * @param {{ ppid?: number, platform?: string, readChain?: Function }} options
+ * @returns {Array<object>}
+ */
+function readChainSafely(options) {
+  const platform = typeof options.platform === 'string' ? options.platform : process.platform
+  const ppid = Number(options.ppid)
+  if (!Number.isFinite(ppid) || ppid <= 0) return []
+  const read = typeof options.readChain === 'function' ? options.readChain : null
+  if (read === null) return []
+  try {
+    const chain = read(ppid, { platform })
+    return Array.isArray(chain) ? chain : []
+  } catch {
+    return []
+  }
+}