@songsid/agend 2.1.12 → 2.2.0-alpha.2

package/launcher/agend

@@ -0,0 +1,110 @@
+#!/bin/sh
+# #1450: the `agend` and `agend-agent` npm bins (this file and launcher/agend-agent are identical). POSIX sh, so AgEnD
+# starts with no Node on PATH at all: it execs this release's bundled Node on the JS launcher, which is the one place
+# that decides and verifies the interpreter (launcher/runtime-select.cjs). A `node` on PATH is used only when the
+# bundled Node is not installed; the JS launcher then decides whether that Node qualifies. Native Windows is not
+# supported (WSL is), as with tmux.
+
+# This file's real location: npm's global bin is a symlink, possibly relative, possibly to another link. A readlink
+# loop, not `readlink -f` (older macOS lacks it; GNU is not assumed).
+self=$0
+while [ -L "$self" ]; do
+  link=$(readlink "$self") || break
+  case $link in
+    /*) self=$link ;;
+    *) self=$(dirname "$self")/$link ;;
+  esac
+done
+dir=$(cd "$(dirname "$self")" && pwd -P) || exit 1
+pkg=$(dirname "$dir")
+launcher=$dir/$(basename "$self").cjs
+
+sys=$(uname -s) || sys=unknown
+mach=$(uname -m) || mach=unknown
+case $sys in
+  Linux) os=linux ;;
+  Darwin) os=darwin ;;
+  *) os=unsupported ;;
+esac
+case $mach in
+  x86_64 | amd64) cpu=x64 ;;
+  aarch64 | arm64) cpu=arm64 ;;
+  *) cpu=unsupported ;;
+esac
+node_pkg=$pkg/node_modules/@songsid/agend-node-$os-$cpu
+node=$node_pkg/bin/node
+receipt=$pkg/.agend-runtime.json
+repair="npm install -g @songsid/agend"
+refuse() { echo "AgEnD cannot start: $1." >&2; echo "To repair: $2" >&2; exit "${3:-1}"; }
+
+# 1. AGEND_NODE, the operator's explicit choice: absolute and executable, then it runs the JS launcher, whose probe
+#    refuses one that does not qualify. Never a silent fallback to another Node.
+if [ -n "${AGEND_NODE:-}" ]; then
+  case $AGEND_NODE in
+    /*) ;;
+    *) refuse "AGEND_NODE must be an absolute path (got $AGEND_NODE)" "unset AGEND_NODE, or point it at a Node 22.14+" ;;
+  esac
+  [ -f "$AGEND_NODE" ] && [ -x "$AGEND_NODE" ] || refuse "AGEND_NODE ($AGEND_NODE) is not an executable file" "unset AGEND_NODE, or point it at a Node 22.14+"
+  exec "$AGEND_NODE" "$launcher" "$@"
+fi
+
+# 2. The bundled Node, only when its ADMISSION KEY (launcher/runtime-select.cjs, "THE ADMISSION KEY") is exactly what
+#    this shell measures now — nothing parsed, the bytes rebuilt and compared: the host's os and cpu (never its
+#    version: an OS update must not lock AgEnD out), the Node's realpath, size and mtime, and the POSIX cksum of both
+#    manifests and of the receipt. The JS selection requires the same key, so a
+#    change to any bound file keeps BOTH from running the candidate.
+# Every measurement must itself complete: a value printed by a command that then fails is no measurement (#1460 r4).
+admissible() {
+  [ -f "$pkg/.agend-runtime.key" ] && [ -f "$node" ] && [ ! -L "$node" ] && [ -x "$node" ] || return 1
+  case $os in linux | darwin) ;; *) return 1 ;; esac
+  real=$(cd "${node%/*}" 2>/dev/null && pwd -P) || return 1
+  real=$real/node
+  size=$(wc -c < "$node") || return 1
+  set -- $size
+  size=${1:-}
+  case $size in '' | *[!0-9]*) return 1 ;; esac
+  if mtime=$(stat -c %Y "$node" 2>/dev/null); then :; elif mtime=$(stat -f %m "$node" 2>/dev/null); then :; else return 1; fi
+  case $mtime in '' | *[!0-9]*) return 1 ;; esac
+  sum_package=$(cksum < "$pkg/package.json") || return 1
+  sum_runtime=$(cksum < "$node_pkg/package.json") || return 1
+  sum_receipt=$(cksum < "$receipt") || return 1
+  printf 'agend-runtime-key 2\nos %s\ncpu %s\nnode %s\nsize %s\nmtime %s\npackage %s\nruntime %s\nreceipt %s\n' \
+    "$os" "$cpu" "$real" "$size" "$mtime" "$sum_package" "$sum_runtime" "$sum_receipt" | cmp -s - "$pkg/.agend-runtime.key"
+}
+# This host, measured fresh, must still be one the bundled Node supports (launcher/runtime-platform.cjs
+# runtimeSupport: glibc >= 2.28 on Linux, Darwin kernel >= 20) — minimums, never a pinned version. A stored or copied
+# runtime on a host that no longer qualifies never runs; the JS launcher then picks a system Node or refuses.
+supported() {
+  case $os in
+    linux)
+      v=$(getconf GNU_LIBC_VERSION 2>/dev/null) || return 1
+      case $v in "glibc "*) v=${v#glibc } ;; *) return 1 ;; esac
+      major=${v%%.*}
+      minor=${v#*.}
+      minor=${minor%%.*}
+      case $major in '' | *[!0-9]*) return 1 ;; esac
+      case $minor in '' | *[!0-9]*) return 1 ;; esac
+      [ "$major" -gt 2 ] || { [ "$major" -eq 2 ] && [ "$minor" -ge 28 ]; }
+      ;;
+    darwin)
+      r=$(uname -r) || return 1
+      kernel=${r%%.*}
+      case $kernel in '' | *[!0-9]*) return 1 ;; esac
+      [ "$kernel" -ge 20 ]
+      ;;
+    *) return 1 ;;
+  esac
+}
+if supported && admissible; then
+  exec "$node" "$launcher" "$@"
+fi
+
+# 3. Not admitted here, so that candidate never runs. A node on PATH runs the JS launcher: it explains a refusal, or
+#    is itself the choice when the runtime was skipped altogether (and it qualifies).
+if command -v node >/dev/null 2>&1; then
+  exec node "$launcher" "$@"
+fi
+if [ -e "$receipt" ] || [ -e "$node" ] || [ -L "$node" ]; then
+  refuse "its bundled Node ($node) is missing, incomplete or changed since it was verified, and there is no node on PATH" "$repair"
+fi
+refuse "its bundled Node is not installed and there is no node on PATH" "$repair" 127

package/launcher/agend-agent

@@ -0,0 +1,110 @@
+#!/bin/sh
+# #1450: the `agend` and `agend-agent` npm bins (this file and launcher/agend-agent are identical). POSIX sh, so AgEnD
+# starts with no Node on PATH at all: it execs this release's bundled Node on the JS launcher, which is the one place
+# that decides and verifies the interpreter (launcher/runtime-select.cjs). A `node` on PATH is used only when the
+# bundled Node is not installed; the JS launcher then decides whether that Node qualifies. Native Windows is not
+# supported (WSL is), as with tmux.
+
+# This file's real location: npm's global bin is a symlink, possibly relative, possibly to another link. A readlink
+# loop, not `readlink -f` (older macOS lacks it; GNU is not assumed).
+self=$0
+while [ -L "$self" ]; do
+  link=$(readlink "$self") || break
+  case $link in
+    /*) self=$link ;;
+    *) self=$(dirname "$self")/$link ;;
+  esac
+done
+dir=$(cd "$(dirname "$self")" && pwd -P) || exit 1
+pkg=$(dirname "$dir")
+launcher=$dir/$(basename "$self").cjs
+
+sys=$(uname -s) || sys=unknown
+mach=$(uname -m) || mach=unknown
+case $sys in
+  Linux) os=linux ;;
+  Darwin) os=darwin ;;
+  *) os=unsupported ;;
+esac
+case $mach in
+  x86_64 | amd64) cpu=x64 ;;
+  aarch64 | arm64) cpu=arm64 ;;
+  *) cpu=unsupported ;;
+esac
+node_pkg=$pkg/node_modules/@songsid/agend-node-$os-$cpu
+node=$node_pkg/bin/node
+receipt=$pkg/.agend-runtime.json
+repair="npm install -g @songsid/agend"
+refuse() { echo "AgEnD cannot start: $1." >&2; echo "To repair: $2" >&2; exit "${3:-1}"; }
+
+# 1. AGEND_NODE, the operator's explicit choice: absolute and executable, then it runs the JS launcher, whose probe
+#    refuses one that does not qualify. Never a silent fallback to another Node.
+if [ -n "${AGEND_NODE:-}" ]; then
+  case $AGEND_NODE in
+    /*) ;;
+    *) refuse "AGEND_NODE must be an absolute path (got $AGEND_NODE)" "unset AGEND_NODE, or point it at a Node 22.14+" ;;
+  esac
+  [ -f "$AGEND_NODE" ] && [ -x "$AGEND_NODE" ] || refuse "AGEND_NODE ($AGEND_NODE) is not an executable file" "unset AGEND_NODE, or point it at a Node 22.14+"
+  exec "$AGEND_NODE" "$launcher" "$@"
+fi
+
+# 2. The bundled Node, only when its ADMISSION KEY (launcher/runtime-select.cjs, "THE ADMISSION KEY") is exactly what
+#    this shell measures now — nothing parsed, the bytes rebuilt and compared: the host's os and cpu (never its
+#    version: an OS update must not lock AgEnD out), the Node's realpath, size and mtime, and the POSIX cksum of both
+#    manifests and of the receipt. The JS selection requires the same key, so a
+#    change to any bound file keeps BOTH from running the candidate.
+# Every measurement must itself complete: a value printed by a command that then fails is no measurement (#1460 r4).
+admissible() {
+  [ -f "$pkg/.agend-runtime.key" ] && [ -f "$node" ] && [ ! -L "$node" ] && [ -x "$node" ] || return 1
+  case $os in linux | darwin) ;; *) return 1 ;; esac
+  real=$(cd "${node%/*}" 2>/dev/null && pwd -P) || return 1
+  real=$real/node
+  size=$(wc -c < "$node") || return 1
+  set -- $size
+  size=${1:-}
+  case $size in '' | *[!0-9]*) return 1 ;; esac
+  if mtime=$(stat -c %Y "$node" 2>/dev/null); then :; elif mtime=$(stat -f %m "$node" 2>/dev/null); then :; else return 1; fi
+  case $mtime in '' | *[!0-9]*) return 1 ;; esac
+  sum_package=$(cksum < "$pkg/package.json") || return 1
+  sum_runtime=$(cksum < "$node_pkg/package.json") || return 1
+  sum_receipt=$(cksum < "$receipt") || return 1
+  printf 'agend-runtime-key 2\nos %s\ncpu %s\nnode %s\nsize %s\nmtime %s\npackage %s\nruntime %s\nreceipt %s\n' \
+    "$os" "$cpu" "$real" "$size" "$mtime" "$sum_package" "$sum_runtime" "$sum_receipt" | cmp -s - "$pkg/.agend-runtime.key"
+}
+# This host, measured fresh, must still be one the bundled Node supports (launcher/runtime-platform.cjs
+# runtimeSupport: glibc >= 2.28 on Linux, Darwin kernel >= 20) — minimums, never a pinned version. A stored or copied
+# runtime on a host that no longer qualifies never runs; the JS launcher then picks a system Node or refuses.
+supported() {
+  case $os in
+    linux)
+      v=$(getconf GNU_LIBC_VERSION 2>/dev/null) || return 1
+      case $v in "glibc "*) v=${v#glibc } ;; *) return 1 ;; esac
+      major=${v%%.*}
+      minor=${v#*.}
+      minor=${minor%%.*}
+      case $major in '' | *[!0-9]*) return 1 ;; esac
+      case $minor in '' | *[!0-9]*) return 1 ;; esac
+      [ "$major" -gt 2 ] || { [ "$major" -eq 2 ] && [ "$minor" -ge 28 ]; }
+      ;;
+    darwin)
+      r=$(uname -r) || return 1
+      kernel=${r%%.*}
+      case $kernel in '' | *[!0-9]*) return 1 ;; esac
+      [ "$kernel" -ge 20 ]
+      ;;
+    *) return 1 ;;
+  esac
+}
+if supported && admissible; then
+  exec "$node" "$launcher" "$@"
+fi
+
+# 3. Not admitted here, so that candidate never runs. A node on PATH runs the JS launcher: it explains a refusal, or
+#    is itself the choice when the runtime was skipped altogether (and it qualifies).
+if command -v node >/dev/null 2>&1; then
+  exec node "$launcher" "$@"
+fi
+if [ -e "$receipt" ] || [ -e "$node" ] || [ -L "$node" ]; then
+  refuse "its bundled Node ($node) is missing, incomplete or changed since it was verified, and there is no node on PATH" "$repair"
+fi
+refuse "its bundled Node is not installed and there is no node on PATH" "$repair" 127

package/launcher/agend-agent.cjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+"use strict";
+// The `agend-agent` bin (#1450): selects AgEnD's Node, then runs dist/agent-cli.js on it.
+require("./launch.cjs")("dist/agent-cli.js", __dirname);

package/launcher/agend.cjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+"use strict";
+// The `agend` bin (#1450): selects AgEnD's Node, then runs dist/cli.js on it.
+require("./launch.cjs")("dist/cli.js", __dirname);

package/launcher/install-admission.cjs

@@ -0,0 +1,105 @@
+"use strict";
+// #1450 C1: may this install of @songsid/agend proceed? Called by the postinstall, inside npm's transaction (a refusal
+// makes npm roll the install back). The lock is the updater's (src/install-lock.ts): `<prefix>/.agend-install.lock`,
+// next to the package it guards. The prefix comes from WHERE this package is — never from the environment.
+//   - no lock, no token            → a plain external install: proceed (the documented restriction covers the rest);
+//   - a live lock, its own token   → the updater's own npm child: proceed;
+//   - a live lock, other/no token  → a foreign install while AgEnD owns the prefix: refuse;
+//   - a token, but no live lock    → late or stale (it cannot authorise a successor): refuse;
+//   - a lock that cannot be read   → refuse, naming the file (unknown ownership blocks).
+// Same syntax constraints as runtime-platform.cjs: this may run on an old Node.
+var fs = require("fs");
+var path = require("path");
+var childProcess = require("child_process");
+
+var LOCK = ".agend-install.lock";
+var TOKEN_ENV = "AGEND_INSTALL_TOKEN";
+
+/** `<prefix>/lib/node_modules/@songsid/agend` → `<prefix>`; null for any other layout (a local install, a checkout). */
+function globalPrefix(pkgDir) {
+  var scope = path.dirname(pkgDir);
+  var nodeModules = path.dirname(scope);
+  var lib = path.dirname(nodeModules);
+  if (path.basename(pkgDir) !== "agend" || path.basename(scope) !== "@songsid" || path.basename(nodeModules) !== "node_modules" || path.basename(lib) !== "lib") return null;
+  return path.dirname(lib);
+}
+
+/** ps by absolute path when it is where the OS keeps it: a service's or a test's PATH may not reach it. */
+var PS = ["/bin/ps", "/usr/bin/ps"].filter(function (p) { try { fs.accessSync(p, fs.constants.X_OK); return true; } catch (e) { return false; } })[0] || "ps";
+
+/**
+ * A process's start time as one canonical text: `ps -o lstart=` under LC_ALL=C and TZ=UTC, so every caller — whatever
+ * its own locale or time zone — reads the same text for the same process. null: it could not be read.
+ */
+function processStart(pid) {
+  try {
+    var env = {};
+    Object.keys(process.env).forEach(function (k) { env[k] = process.env[k]; });
+    env.LC_ALL = "C";
+    env.TZ = "UTC";
+    var r = childProcess.spawnSync(PS, ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8", timeout: 5000, env: env, stdio: ["ignore", "pipe", "ignore"] });
+    var text = String(r.stdout || "").trim();
+    return r.status === 0 && text ? text : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+/** The record, exactly as the updater validates it (src/install-lock.ts parseInstallLock), or null. */
+/** Does `pid` exist? Only a definite "no such process" is no. */
+function exists(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code !== "ESRCH"; }
+}
+
+/**
+ * The lock holder's state: "live" (that very process), "stale" (PROVEN gone: no such pid, or the pid is now a process
+ * that started at another time), or "unknown" (it exists but its start time cannot be read) — which blocks, never
+ * counts as stale. deps (tests): exists, processStart.
+ */
+function holderState(lock, deps) {
+  var d = deps || {};
+  if (!(d.exists || exists)(lock.pid)) return "stale";
+  var seen = (d.processStart || processStart)(lock.pid);
+  if (seen === null || seen === undefined) return "unknown";
+  return seen === lock.processStart ? "live" : "stale";
+}
+
+function parse(text) {
+  var r;
+  try { r = JSON.parse(text); } catch (e) { return null; }
+  return r && typeof r === "object" && Number.isSafeInteger(r.pid) && r.pid > 0 && typeof r.processStart === "string" && r.processStart
+    && typeof r.prefix === "string" && typeof r.token === "string" && /^[0-9a-f]{32,}$/.test(r.token)
+    && typeof r.targetSpec === "string" && typeof r.agendHome === "string" && typeof r.createdAt === "string" ? r : null;
+}
+
+/** { ok: true, why } or { ok: false, reason }. deps (tests): env, processStart. */
+function admit(pkgDir, deps) {
+  var d = deps || {};
+  var env = d.env || process.env;
+  var token = env[TOKEN_ENV] || "";
+  var real;
+  try { real = fs.realpathSync(pkgDir); } catch (e) { real = pkgDir; }
+  var prefix = globalPrefix(real);
+  if (!prefix) return token ? { ok: false, reason: "an AgEnD install token was presented, but this is not a global install it could belong to" } : { ok: true, why: "not a global install" };
+  try { prefix = fs.realpathSync(prefix); } catch (e) { /* as derived */ }
+  var lockPath = path.join(prefix, LOCK);
+  var text = null;
+  try { text = fs.readFileSync(lockPath, "utf8"); } catch (e) {
+    if (e.code !== "ENOENT") return { ok: false, reason: "the install lock " + lockPath + " cannot be read (" + e.code + ")" };
+  }
+  if (text === null) {
+    return token ? { ok: false, reason: "an AgEnD install token was presented, but no update holds " + lockPath + " (a late or stale token)" } : { ok: true, why: "no lock: an external install" };
+  }
+  var lock = parse(text);
+  if (!lock) return { ok: false, reason: "the install lock " + lockPath + " cannot be read as a lock; if no `agend update` is running, remove it and retry" };
+  var state = holderState(lock, d);
+  if (state === "unknown") return { ok: false, reason: "whether the AgEnD update that holds " + lockPath + " (pid " + lock.pid + ") is still running cannot be told; retry" };
+  if (state === "stale") {
+    return token ? { ok: false, reason: "the AgEnD update that held " + lockPath + " is gone, so its token cannot authorise this install" } : { ok: true, why: "a stale lock and no token: an external install" };
+  }
+  if (lock.prefix !== prefix) return { ok: false, reason: "the install lock " + lockPath + " names another prefix (" + lock.prefix + ")" };
+  if (token && token === lock.token) return { ok: true, why: "the updater's own install" };
+  return { ok: false, reason: "an `agend update` (pid " + lock.pid + ") is installing into " + prefix + " right now; wait for it, then retry" };
+}
+
+module.exports = { LOCK: LOCK, TOKEN_ENV: TOKEN_ENV, admit: admit, globalPrefix: globalPrefix, processStart: processStart, exists: exists, holderState: holderState, parse: parse };

package/launcher/launch.cjs

@@ -0,0 +1,64 @@
+"use strict";
+// #1450 C2: the launcher body shared by the `agend` and `agend-agent` bins. It picks the interpreter BEFORE any module
+// of the CLI's import graph loads, never downloads, and never changes PATH. Syntax old Nodes still parse.
+var fs = require("fs");
+var path = require("path");
+var childProcess = require("child_process");
+var select = require("./runtime-select.cjs");
+
+var FORWARDED = ["SIGTERM", "SIGHUP", "SIGUSR1", "SIGUSR2"];
+
+function realpath(file) {
+  try { return fs.realpathSync(file); } catch (e) { return null; }
+}
+
+/** `entryRelative`: the CLI inside the package, e.g. "dist/cli.js". */
+module.exports = function launch(entryRelative, launcherDir) {
+  var args = process.argv.slice(2);
+  var chosen = select.selectRuntime(launcherDir);
+
+  // For the updater (C4): which Node and package would this install run on? Printed, nothing started.
+  if (args[0] === "--agend-select-json") {
+    process.stdout.write(JSON.stringify(chosen.ok
+      ? { node: chosen.node, source: chosen.source, pkgDir: chosen.pkgDir, entry: path.join(chosen.pkgDir, entryRelative), warning: chosen.warning || null }
+      : { error: chosen.reason, recovery: chosen.recovery }) + "\n");
+    process.exit(chosen.ok ? 0 : 1);
+  }
+  if (!chosen.ok) {
+    process.stderr.write("\n  AgEnD cannot start: " + chosen.reason + ".\n  To repair: " + chosen.recovery + "\n\n");
+    process.exit(1);
+  }
+  if (chosen.warning) process.stderr.write("  ⚠ AgEnD: " + chosen.warning + "\n");
+
+  var entry = path.join(chosen.pkgDir, entryRelative);
+  if (chosen.node === realpath(process.execPath)) {
+    require("./run-in-process.cjs")(entry);
+    return;
+  }
+
+  var env = {};
+  Object.keys(process.env).forEach(function (key) { env[key] = process.env[key]; });
+  env.AGEND_NODE_SELECTED = "1";
+  // The handlers are in place BEFORE the spawn: a signal delivered between spawn() and their registration would kill
+  // this launcher by default and orphan the CLI. (JS handlers cannot run during this synchronous block, so `child` is
+  // always set by the time one does.)
+  var child = null;
+  FORWARDED.forEach(function (signal) {
+    process.on(signal, function () { try { child.kill(signal); } catch (e) { /* gone */ } });
+  });
+  // A terminal's Ctrl+C reaches the whole process group, the child included: the child decides, this waits.
+  process.on("SIGINT", function () {});
+  child = childProcess.spawn(chosen.node, [entry].concat(args), { stdio: "inherit", env: env });
+  child.on("error", function (err) {
+    process.stderr.write("\n  AgEnD cannot start " + chosen.node + ": " + err.message + "\n\n");
+    process.exit(1);
+  });
+  child.on("exit", function (code, signal) {
+    if (signal) {
+      process.removeAllListeners(signal);
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code === null ? 1 : code);
+  });
+};

package/launcher/postinstall.cjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+"use strict";
+// #1450: npm's `postinstall` for @songsid/agend. It runs under whatever Node runs npm (possibly an old one) and
+// decides, inside the install transaction, whether this install can run at all — refusing (exit 1) makes npm roll the
+// install back (proven by the npm-rollback-proof gate, #1455):
+//   - this release's bundled Node is present (supported host): prove it — exact version, N-API ≥ 10, platform/arch,
+//     and a better-sqlite3 database opened in the main thread AND in a worker — then write the receipt the launcher
+//     checks on every start;
+//   - no bundled Node (unsupported host, none pinned yet, optional dependencies omitted): the Node running npm must
+//     qualify itself.
+var fs = require("fs");
+var path = require("path");
+var crypto = require("crypto");
+var childProcess = require("child_process");
+var platform = require("./runtime-platform.cjs");
+var select = require("./runtime-select.cjs");
+var admission = require("./install-admission.cjs");
+
+/** Runs on the candidate Node with argv[1] = the package dir: version, N-API, and a real DB open in both threads. */
+var PROOF = [
+  "const { createRequire } = require('node:module');",
+  "const { Worker } = require('node:worker_threads');",
+  "const dir = process.argv[1];",
+  "const open = () => { const D = createRequire(require('node:path').join(dir, 'package.json'))('better-sqlite3'); const db = new D(':memory:'); const one = db.prepare('select 1 as one').get().one; db.close(); return one; };",
+  "if (open() !== 1) process.exit(3);",
+  "const w = new Worker(`const { createRequire } = require('node:module'); const D = createRequire(require('node:path').join(${JSON.stringify(dir)}, 'package.json'))('better-sqlite3'); const db = new D(':memory:'); const one = db.prepare('select 1 as one').get().one; db.close(); require('node:worker_threads').parentPort.postMessage(one);`, { eval: true });",
+  // The worker's answer AND its clean exit (the database closed inside it): any other end fails the proof.
+  "let answer = null;",
+  "w.on('message', one => { answer = one; });",
+  "w.on('error', () => process.exit(5));",
+  "w.on('exit', code => { if (code !== 0 || answer !== 1) process.exit(4); process.stdout.write(JSON.stringify({ node: process.versions.node, napi: Number(process.versions.napi), platform: process.platform, arch: process.arch })); process.exit(0); });",
+].join("\n");
+
+function refuse(reason, recovery) {
+  process.stderr.write("\n  AgEnD cannot be installed here: " + reason + ".\n  npm is rolling this install back; the previous install, if any, stays.\n  " + recovery + "\n\n");
+  process.exit(1);
+}
+
+function sha256(file) {
+  return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+}
+
+function main(deps) {
+  var d = deps || {};
+  var pkg = select.packageDir(d.launcherDir || __dirname);
+  if (!pkg) refuse("the installed package is not @songsid/agend", "npm install -g @songsid/agend");
+  // A receipt describes THIS install's verification and nothing else: whatever is there now (one npm left behind, one
+  // copied in) goes first, so selection and installation see the same state (runtime-select.cjs).
+  [select.KEY, select.RECEIPT].forEach(function (name) {
+    var file = path.join(pkg.dir, name);
+    if (select.absent(file)) return;
+    try { fs.unlinkSync(file); } catch (e) { /* checked below */ }
+    if (!select.absent(file)) refuse("an old runtime receipt at " + file + " cannot be removed", "remove it, then: npm install -g @songsid/agend@" + pkg.manifest.version);
+  });
+  // C1: an `agend update` owns this prefix right now → only its own npm child may install (install-admission.cjs).
+  var admitted = admission.admit(pkg.dir, { env: d.env, processStart: d.processStart });
+  if (!admitted.ok) refuse(admitted.reason, "Never run two installs of @songsid/agend into one prefix at once, or one while `agend update` runs.");
+  var host = d.host || platform.hostPlatform();
+  var running = d.versions || { node: process.versions.node, napi: Number(process.versions.napi) };
+  var engines = (pkg.manifest.engines && pkg.manifest.engines.node) || ">=22.14.0";
+  var pin = select.pinnedRuntime(pkg.manifest, host);
+  var support = platform.runtimeSupport(host);
+  var log = d.log || function (line) { process.stdout.write(line + "\n"); };
+
+  if (pin && support.supported) {
+    var candidate = select.runtimeCandidate(pkg.dir, pin);
+    if (candidate.exists) {
+      if (!candidate.manifest || candidate.manifest.name !== pin.name || candidate.manifest.version !== pin.version) {
+        refuse("the bundled Node package is not " + pin.name + "@" + pin.version, "npm install -g @songsid/agend@" + pkg.manifest.version);
+      }
+      var st;
+      try { st = fs.lstatSync(candidate.node); } catch (e) { st = null; }
+      if (!st || !st.isFile()) refuse("the bundled Node binary is missing or not a regular file", "npm install -g @songsid/agend@" + pkg.manifest.version);
+      var r = childProcess.spawnSync(candidate.node, ["-e", PROOF, pkg.dir], { encoding: "utf8", timeout: 30000, stdio: ["ignore", "pipe", "pipe"] });
+      var seen = null;
+      try { seen = r.status === 0 ? JSON.parse(String(r.stdout).trim()) : null; } catch (e) { seen = null; }
+      var wantNode = pin.version.replace(/-agend\.\d+$/, "");
+      if (!seen || seen.node !== wantNode || !(seen.napi >= select.MIN_NAPI) || seen.platform !== host.platform || seen.arch !== host.arch) {
+        refuse("the bundled Node did not pass its check (" + (seen ? "Node " + seen.node + ", N-API " + seen.napi + ", " + seen.platform + "-" + seen.arch : "exit " + (r.status === null ? r.signal : r.status) + ": " + String(r.stderr || "").trim().split("\n").pop()) + ")", "npm install -g @songsid/agend@" + pkg.manifest.version);
+      }
+      var real = fs.realpathSync(candidate.node);
+      // The receipt contract (runtime-select.cjs) keeps every string plain, so a shell can check it exactly too.
+      if (!select.PLAIN.test(real)) refuse("AgEnD's install path " + JSON.stringify(real) + " contains a quote, backslash or control character", "install it under a plain path");
+      var finalStat = fs.statSync(real);
+      var receipt = {
+        receipt: 2, pinnedVersion: pin.version, nodePath: real, size: finalStat.size, mtime: Math.floor(finalStat.mtimeMs / 1000), sha256: sha256(real),
+        napi: seen.napi, platform: host.platform, arch: host.arch, libc: host.glibc ? "glibc" : null, verifiedAt: new Date().toISOString(),
+      };
+      var tmp = path.join(pkg.dir, select.RECEIPT + "." + process.pid + ".tmp");
+      fs.writeFileSync(tmp, select.receiptText(receipt));
+      fs.renameSync(tmp, path.join(pkg.dir, select.RECEIPT));
+      // The admission key goes LAST: it binds the receipt just written (runtime-select.cjs).
+      var key = select.runtimeKey(pkg.dir, candidate, host);
+      if (key === null) refuse("the bundled Node's admission key cannot be computed", "npm install -g @songsid/agend@" + pkg.manifest.version);
+      var keyTmp = path.join(pkg.dir, select.KEY + "." + process.pid + ".tmp");
+      fs.writeFileSync(keyTmp, key);
+      fs.renameSync(keyTmp, path.join(pkg.dir, select.KEY));
+      log("  ✓ AgEnD will run on its bundled Node " + seen.node + " (verified: N-API " + seen.napi + ", a database opened in the main thread and a worker)");
+      return 0;
+    }
+    if (select.qualifies(running, engines)) {
+      log("  ⚠ AgEnD's bundled Node was not installed (--omit=optional?); it will run on this Node " + running.node);
+      return 0;
+    }
+    refuse("its bundled Node (" + pin.name + ") was not installed, and this Node " + running.node + " is older than AgEnD needs (" + engines + ")",
+      "If optional dependencies were omitted or a registry mirror blocks " + pin.name + ", allow it and retry; or install Node " + engines + " first.");
+  }
+  if (select.qualifies(running, engines)) return 0;
+  refuse((pin ? support.reason : "this release bundles no Node") + ", and this Node " + running.node + " is older than AgEnD needs (" + engines + ")",
+    "Install Node " + engines + ", then: npm install -g @songsid/agend@" + pkg.manifest.version);
+}
+
+module.exports = { main: main, PROOF: PROOF };
+if (require.main === module) process.exit(main() || 0);

package/launcher/run-in-process.cjs

@@ -0,0 +1,13 @@
+"use strict";
+// Loaded only when the running Node is the selected one — a Node new enough to parse `import()`; older Nodes never
+// load this file, so their parse of the launcher stays clean. process.argv[1] becomes the inner entry, as when the
+// CLI is run directly (service install, completion and restart read it).
+var url = require("url");
+
+module.exports = function runInProcess(entry) {
+  process.argv[1] = entry;
+  return import(url.pathToFileURL(entry).href).catch(function (err) {
+    process.stderr.write(String((err && err.stack) || err) + "\n");
+    process.exit(1);
+  });
+};

package/launcher/runtime-platform.cjs

@@ -0,0 +1,86 @@
+"use strict";
+// #1450 C3: the one answer to "can this host run AgEnD's bundled Node?", shared by preinstall, postinstall and the
+// launcher. CommonJS that very old Nodes still parse (var, function, no optional chaining): it may run on the host's
+// own old Node, before anything decides which Node AgEnD itself will use.
+var os = require("os");
+
+/** The runtime packages AgEnD ships: official glibc Linux builds and macOS builds (no musl, #1450). */
+var SHIPPED = ["linux-x64", "linux-arm64", "darwin-x64", "darwin-arm64"];
+/** The official Node 22 builds need glibc ≥ 2.28 on Linux and macOS 11 (Darwin kernel 20) or newer. */
+var MIN_GLIBC = [2, 28];
+var MIN_DARWIN_KERNEL = 20;
+
+function numbers(text) {
+  return String(text).split(".").map(function (part) { return parseInt(part, 10); });
+}
+
+function atLeast(have, want) {
+  for (var i = 0; i < want.length; i++) {
+    var h = have[i] || 0;
+    if (h > want[i]) return true;
+    if (h < want[i]) return false;
+  }
+  return true;
+}
+
+/** glibc's version when this Node runs on glibc; null on musl or when it cannot be told. */
+function glibcVersion(report) {
+  try {
+    var r = report || (process.report && process.report.getReport && process.report.getReport());
+    var v = r && r.header && r.header.glibcVersionRuntime;
+    return typeof v === "string" && v ? v : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * The host as the runtime packages see it. `probe` is injectable for tests:
+ * { platform, arch, glibc (string|null), darwinRelease (string|null) }.
+ */
+function hostPlatform(probe) {
+  var p = probe || {};
+  var platform = p.platform || process.platform;
+  var arch = p.arch || process.arch;
+  return {
+    platform: platform,
+    arch: arch,
+    id: platform + "-" + arch,
+    glibc: "glibc" in p ? p.glibc : (platform === "linux" ? glibcVersion() : null),
+    darwinRelease: "darwinRelease" in p ? p.darwinRelease : (platform === "darwin" ? os.release() : null),
+  };
+}
+
+/** Whether a bundled runtime can run here, and why not. */
+function runtimeSupport(host) {
+  if (SHIPPED.indexOf(host.id) < 0) return { supported: false, reason: "no AgEnD runtime is published for " + host.id };
+  if (host.platform === "linux") {
+    if (!host.glibc) return { supported: false, reason: "this Linux is not glibc-based (musl?), and the bundled Node needs glibc" };
+    if (!atLeast(numbers(host.glibc), MIN_GLIBC)) return { supported: false, reason: "glibc " + host.glibc + " is older than the 2.28 the bundled Node needs" };
+  }
+  if (host.platform === "darwin") {
+    var kernel = numbers(host.darwinRelease || "0")[0];
+    if (!(kernel >= MIN_DARWIN_KERNEL)) return { supported: false, reason: "macOS older than 11 (Darwin " + host.darwinRelease + ") cannot run the bundled Node" };
+  }
+  return { supported: true, reason: null };
+}
+
+/**
+ * Does a Node version satisfy an `engines.node` range? Only the forms AgEnD uses: alternatives joined by `||`, each
+ * `^x.y.z` (same major, at least x.y.z) or `>=x[.y[.z]]`. The version must be a full stable `x.y.z`: as in npm's
+ * semver, a prerelease (`24.0.0-nightly…`, `22.14.0-rc.1`) satisfies no stable alternative.
+ */
+function satisfiesEngines(version, range) {
+  var full = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(version));
+  if (!full) return false;
+  var v = [+full[1], +full[2], +full[3]];
+  return String(range).split("||").some(function (alt) {
+    var a = alt.trim();
+    var m;
+    if ((m = /^\^(\d+)\.(\d+)\.(\d+)$/.exec(a))) return v[0] === +m[1] && atLeast(v, [+m[1], +m[2], +m[3]]);
+    if ((m = /^>=\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(a))) return atLeast(v, [+m[1], +(m[2] || 0), +(m[3] || 0)]);
+    return false;
+  });
+}
+
+module.exports = { SHIPPED: SHIPPED, hostPlatform: hostPlatform, runtimeSupport: runtimeSupport, satisfiesEngines: satisfiesEngines, glibcVersion: glibcVersion };