@songsid/agend 2.2.0-alpha.1 → 2.2.0-alpha.3

package/launcher/postinstall.cjs

@@ -0,0 +1,118 @@
+#!/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");
+}
+
+/** #1519 P7: the last line of a successful install (npm shows it with --foreground-scripts; install.sh says the same). */
+var NEXT_STEP = "  Next: run `agend quickstart` to set up AgEnD.";
+
+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"); };
+  var installed = function () { log(NEXT_STEP); return 0; };
+
+  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 installed();
+    }
+    if (select.qualifies(running, engines)) {
+      log("  ⚠ AgEnD's bundled Node was not installed (--omit=optional?); it will run on this Node " + running.node);
+      return installed();
+    }
+    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 installed();
+  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, NEXT_STEP: NEXT_STEP };
+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 };

package/launcher/runtime-select.cjs

@@ -0,0 +1,217 @@
+"use strict";
+// #1450 C2: one verified interpreter-selection protocol, shared by the launchers, the postinstall and the updater's
+// probe of a target package. Same syntax constraints as runtime-platform.cjs. It never touches the network and does
+// at most one bounded probe.
+var fs = require("fs");
+var path = require("path");
+var childProcess = require("child_process");
+var platform = require("./runtime-platform.cjs");
+
+var RECEIPT = ".agend-runtime.json";
+var KEY = ".agend-runtime.key";
+var MIN_NAPI = 10;
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch (e) { return null; }
+}
+
+/** Physically absent (lstat: ENOENT/ENOTDIR)? A dangling symlink, or a path that cannot be inspected, is PRESENT. */
+function absent(file) {
+  try { fs.lstatSync(file); return false; } catch (e) { return e.code === "ENOENT" || e.code === "ENOTDIR"; }
+}
+
+/**
+ * THE RECEIPT CONTRACT (#1460 review), shared word for word with the sh bins (launcher/agend), which check it before
+ * they exec anything: the receipt is exactly `JSON.stringify(receipt, null, 2) + "\n"` of these keys in this order —
+ * strings plain (no `"`, `\` or control characters), numbers non-negative integers, `libc` "glibc" or null. Anything
+ * else — unreadable, not JSON, valid JSON in another shape or layout — is "invalid". `mtime` is whole seconds (what
+ * `stat` gives a shell, and what survives a copy that preserves timestamps).
+ */
+var RECEIPT_KEYS = ["receipt", "pinnedVersion", "nodePath", "size", "mtime", "sha256", "napi", "platform", "arch", "libc", "verifiedAt"];
+var PLAIN = /^[^"\\\u0000-\u001f]*$/;
+function receiptText(r) {
+  var ordered = {};
+  RECEIPT_KEYS.forEach(function (k) { ordered[k] = r[k]; });
+  return JSON.stringify(ordered, null, 2) + "\n";
+}
+function receiptShapeOk(r) {
+  var int = function (n) { return typeof n === "number" && Number.isSafeInteger(n) && n >= 0; };
+  var str = function (s) { return typeof s === "string" && PLAIN.test(s); };
+  return r.receipt === 2 && str(r.pinnedVersion) && /^\d+\.\d+\.\d+(-agend\.\d+)?$/.test(r.pinnedVersion)
+    && str(r.nodePath) && r.nodePath.charAt(0) === "/" && int(r.size) && int(r.mtime) && typeof r.sha256 === "string" && /^[0-9a-f]{64}$/.test(r.sha256)
+    && int(r.napi) && str(r.platform) && r.platform !== "" && str(r.arch) && r.arch !== "" && (r.libc === "glibc" || r.libc === null) && str(r.verifiedAt) && r.verifiedAt !== "";
+}
+
+/** The receipt, by state: "absent" only when no file is there; "valid" only in the contract's exact form; else "invalid". */
+function readReceipt(file) {
+  if (absent(file)) return { state: "absent" };
+  var text, value;
+  try { text = fs.readFileSync(file, "utf8"); value = JSON.parse(text); } catch (e) { return { state: "invalid" }; }
+  if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).join(",") !== RECEIPT_KEYS.join(",")) return { state: "invalid" };
+  return receiptShapeOk(value) && text === receiptText(value) ? { state: "valid", value: value } : { state: "invalid" };
+}
+
+function realpath(file) {
+  try { return fs.realpathSync(file); } catch (e) { return null; }
+}
+
+/** The package that contains this launcher: realpath(launcher/..), and it must be @songsid/agend. */
+function packageDir(launcherDir) {
+  var dir = realpath(path.join(launcherDir, ".."));
+  var manifest = dir && readJson(path.join(dir, "package.json"));
+  return manifest && manifest.name === "@songsid/agend" ? { dir: dir, manifest: manifest } : null;
+}
+
+/** This release's runtime package name and exact pinned version, or null when none is pinned yet. */
+function pinnedRuntime(manifest, host) {
+  var name = "@songsid/agend-node-" + host.id;
+  var version = manifest.optionalDependencies && manifest.optionalDependencies[name];
+  return typeof version === "string" && /^\d+\.\d+\.\d+(-agend\.\d+)?$/.test(version) ? { name: name, version: version } : null;
+}
+
+/** The candidate is exactly <pkgDir>/node_modules/<name> — never require.resolve, which can walk up to an ancestor. */
+function runtimeCandidate(pkgDir, pin) {
+  var dir = path.join(pkgDir, "node_modules", pin.name);
+  var exists = !absent(dir);
+  var manifest = exists ? readJson(path.join(dir, "package.json")) : null;
+  return { dir: dir, exists: exists, manifest: manifest, node: path.join(dir, "bin", "node") };
+}
+
+/** Run `node` once, bounded, to read its version and N-API level. */
+function probeNode(node, timeoutMs) {
+  try {
+    var r = childProcess.spawnSync(node, ["-p", "JSON.stringify({ node: process.versions.node, napi: Number(process.versions.napi) })"], { encoding: "utf8", timeout: timeoutMs || 1000, stdio: ["ignore", "pipe", "ignore"] });
+    if (r.status !== 0) return null;
+    var v = JSON.parse(String(r.stdout).trim());
+    return typeof v.node === "string" && typeof v.napi === "number" ? v : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+function qualifies(versions, engines) {
+  return versions && platform.satisfiesEngines(versions.node, engines) && Number(versions.napi) >= MIN_NAPI;
+}
+
+/** POSIX `cksum`: CRC-32 (0x04C11DB7, MSB first), then the byte length (LSB first), complemented; "<crc> <length>". */
+var CRC_TABLE = (function () {
+  var t = [];
+  for (var i = 0; i < 256; i++) { var c = i << 24; for (var j = 0; j < 8; j++) c = c & 0x80000000 ? (c << 1) ^ 0x04C11DB7 : c << 1; t.push(c >>> 0); }
+  return t;
+})();
+function cksum(buf) {
+  var crc = 0;
+  var step = function (b) { crc = ((crc << 8) ^ CRC_TABLE[((crc >>> 24) ^ b) & 0xff]) >>> 0; };
+  for (var i = 0; i < buf.length; i++) step(buf[i]);
+  for (var n = buf.length; n > 0; n = Math.floor(n / 256)) step(n & 0xff);
+  return ((~crc) >>> 0) + " " + buf.length;
+}
+
+/**
+ * THE ADMISSION KEY (#1460 r3), the one thing the sh bins check before they exec the bundled Node — byte for byte, by
+ * rebuilding it from their own measurements (launcher/agend) — and that this selection requires as well. One fact per
+ * line: the host's os and cpu, the Node's realpath, size and mtime (whole seconds), and the POSIX `cksum` of both
+ * manifests and of the receipt. NO host VERSION (glibc, Darwin kernel): an OS update must never lock AgEnD out of
+ * the Node it verified (#1450 leader review) — whether the host can still run it is runtimeSupport()'s minimums, judged
+ * fresh on every start, and the libc family is fixed by the package's own `libc` field at install. The postinstall writes it LAST, after everything it binds is
+ * final and verified; any later change to a manifest or the receipt changes its CRC, any change to the binary its
+ * size or mtime — and then neither side runs it. null when a bound file cannot be read.
+ */
+function runtimeKey(pkgDir, candidate, host) {
+  try {
+    // Bytes, never decoded text: a path is whatever bytes the filesystem has (#1460 r4), exactly as the shell prints it.
+    var real = fs.realpathSync(candidate.node, { encoding: "buffer" });
+    var st = fs.lstatSync(real);
+    if (!st.isFile()) return null;
+    var line = function (text) { return Buffer.from(text + "\n", "utf8"); };
+    return Buffer.concat([
+      line("agend-runtime-key 2"),
+      line("os " + host.platform),
+      line("cpu " + host.arch),
+      Buffer.from("node ", "utf8"), real, Buffer.from("\n", "utf8"),
+      line("size " + st.size),
+      line("mtime " + Math.floor(st.mtimeMs / 1000)),
+      line("package " + cksum(fs.readFileSync(path.join(pkgDir, "package.json")))),
+      line("runtime " + cksum(fs.readFileSync(path.join(candidate.dir, "package.json")))),
+      line("receipt " + cksum(fs.readFileSync(path.join(pkgDir, RECEIPT)))),
+    ]);
+  } catch (e) {
+    return null;
+  }
+}
+function keyMatches(pkgDir, candidate, host) {
+  var want = runtimeKey(pkgDir, candidate, host);
+  var have;
+  try { have = fs.readFileSync(path.join(pkgDir, KEY)); } catch (e) { return false; }
+  return want !== null && Buffer.compare(have, want) === 0;
+}
+
+/** Does the receipt the postinstall wrote still describe this exact binary? (cheap: no hashing at run time) */
+function receiptMatches(receipt, candidate, pin) {
+  if (!receipt || receipt.pinnedVersion !== pin.version) return false;
+  var real = realpath(candidate.node);
+  if (!real || real !== receipt.nodePath) return false;
+  try {
+    var st = fs.lstatSync(real);
+    return st.isFile() && st.size === receipt.size && Math.floor(st.mtimeMs / 1000) === receipt.mtime;
+  } catch (e) {
+    return false;
+  }
+}
+
+/**
+ * Choose the Node that runs AgEnD. Result:
+ *   { ok: true, node, source: "override"|"runtime"|"system", pkgDir, warning? }
+ *   { ok: false, reason, recovery }
+ * deps (injectable for tests): env, execPath, versions ({node, napi}), host (hostPlatform() result), probe(node).
+ */
+function selectRuntime(launcherDir, deps) {
+  var d = deps || {};
+  var env = d.env || process.env;
+  var execPath = d.execPath || process.execPath;
+  var running = d.versions || { node: process.versions.node, napi: Number(process.versions.napi) };
+  var host = d.host || platform.hostPlatform();
+  var probe = d.probe || probeNode;
+  var pkg = packageDir(launcherDir);
+  if (!pkg) return { ok: false, reason: "this launcher is not inside an @songsid/agend package", recovery: "npm install -g @songsid/agend" };
+  var engines = (pkg.manifest.engines && pkg.manifest.engines.node) || ">=22.14.0";
+  var recovery = "npm install -g @songsid/agend@" + pkg.manifest.version;
+
+  // 1. An explicit override: absolute, executable, and passes the probe — or a clear failure, never a fallback.
+  if (env.AGEND_NODE) {
+    var override = env.AGEND_NODE;
+    if (!path.isAbsolute(override)) return { ok: false, reason: "AGEND_NODE must be an absolute path (got " + JSON.stringify(override) + ")", recovery: "unset AGEND_NODE, or point it at a Node " + engines };
+    try { fs.accessSync(override, fs.constants.X_OK); } catch (e) { return { ok: false, reason: "AGEND_NODE (" + override + ") is not an executable file", recovery: "unset AGEND_NODE, or point it at a Node " + engines }; }
+    var seen = probe(override, 1000);
+    if (!qualifies(seen, engines)) return { ok: false, reason: "AGEND_NODE (" + override + ") is Node " + (seen ? seen.node + " with N-API " + seen.napi : "that did not answer") + "; AgEnD needs " + engines + " with N-API " + MIN_NAPI, recovery: "unset AGEND_NODE, or point it at a Node " + engines };
+    return { ok: true, node: realpath(override) || override, source: "override", pkgDir: pkg.dir };
+  }
+
+  var pin = pinnedRuntime(pkg.manifest, host);
+  var support = platform.runtimeSupport(host);
+  if (pin && support.supported) {
+    var candidate = runtimeCandidate(pkg.dir, pin);
+    var receipt = readReceipt(path.join(pkg.dir, RECEIPT));
+    // 2. The verified runtime of this release — and its admission key, exactly what the sh bins check (see above).
+    if (candidate.exists && candidate.manifest && candidate.manifest.name === pin.name && candidate.manifest.version === pin.version && receipt.state === "valid" && receiptMatches(receipt.value, candidate, pin) && keyMatches(pkg.dir, candidate, host)) {
+      return { ok: true, node: realpath(candidate.node), source: "runtime", pkgDir: pkg.dir };   // the binary checked, never a path the receipt names
+    }
+    // 3. Supported platform, runtime missing/partial/corrupt: refuse — never a silent fallback. The one exception is
+    //    an install where the runtime was skipped altogether — PHYSICALLY nothing there, no directory (not even a
+    //    dangling link) and no receipt file (--ignore-scripts or --omit=optional) — which may use a qualifying system
+    //    Node, with a warning.
+    if (candidate.exists || receipt.state !== "absent" || !absent(path.join(pkg.dir, KEY))) {
+      return { ok: false, reason: "the bundled Node (" + pin.name + "@" + pin.version + ") is missing, incomplete or changed since it was verified", recovery: recovery };
+    }
+    if (qualifies(running, engines)) {
+      return { ok: true, node: realpath(execPath) || execPath, source: "system", pkgDir: pkg.dir, warning: "the bundled Node was not installed (--ignore-scripts or --omit=optional?); using this Node " + running.node };
+    }
+    return { ok: false, reason: "the bundled Node was not installed, and this Node " + running.node + " is older than AgEnD needs (" + engines + ")", recovery: recovery };
+  }
+
+  // 4. No runtime for this host (unsupported, or none pinned in this release): the running Node, if it qualifies.
+  if (qualifies(running, engines)) return { ok: true, node: realpath(execPath) || execPath, source: "system", pkgDir: pkg.dir };
+  return { ok: false, reason: (pin ? support.reason : "this release bundles no Node") + "; this Node " + running.node + " is older than AgEnD needs (" + engines + ")", recovery: "install Node " + engines + ", then " + recovery };
+}
+
+module.exports = { KEY: KEY, cksum: cksum, runtimeKey: runtimeKey, keyMatches: keyMatches, RECEIPT: RECEIPT, MIN_NAPI: MIN_NAPI, selectRuntime: selectRuntime, packageDir: packageDir, pinnedRuntime: pinnedRuntime, runtimeCandidate: runtimeCandidate, probeNode: probeNode, qualifies: qualifies, receiptMatches: receiptMatches, readReceipt: readReceipt, absent: absent, receiptText: receiptText, RECEIPT_KEYS: RECEIPT_KEYS, PLAIN: PLAIN };

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@songsid/agend",
-  "version": "2.2.0-alpha.1",
+  "version": "2.2.0-alpha.3",
   "description": "Multi-agent fleet daemon — run any coding CLI (Claude, Gemini, Codex, OpenCode) from Telegram",
   "type": "module",
   "bin": {
-    "agend": "./dist/cli.js",
-    "agend-agent": "./dist/agent-cli.js"
+    "agend": "./launcher/agend",
+    "agend-agent": "./launcher/agend-agent"
   },
   "exports": {
     ".": "./dist/cli.js",
@@ -27,7 +27,8 @@
     "typecheck": "tsc --noEmit",
     "typecheck:tests": "tsc --noEmit -p tsconfig.test.json",
     "prepublishOnly": "npm run build",
-    "preinstall": "node scripts/preinstall-guard.cjs"
+    "preinstall": "node scripts/preinstall-guard.cjs",
+    "postinstall": "node launcher/postinstall.cjs"
   },
   "engines": {
     "node": "^22.14.0 || ^23.6.0 || >=24"
@@ -54,6 +55,7 @@
     "templates/",
     "README.md",
     "README.zh-TW.md",
+    "launcher/",
     "scripts/preinstall-guard.cjs"
   ],
   "dependencies": {
@@ -72,6 +74,12 @@
     "yaml": "^2.9.0",
     "zod": "^4.3.6"
   },
+  "optionalDependencies": {
+    "@songsid/agend-node-darwin-arm64": "22.23.3",
+    "@songsid/agend-node-darwin-x64": "22.23.3",
+    "@songsid/agend-node-linux-arm64": "22.23.3",
+    "@songsid/agend-node-linux-x64": "22.23.3"
+  },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
     "@types/ejs": "^3.1.5",

package/scripts/preinstall-guard.cjs

@@ -1,36 +1,55 @@
 #!/usr/bin/env node
 // preinstall-guard.cjs — runs as npm's `preinstall` lifecycle hook.
-// No dependencies: only built-in Node.js APIs.
+// No dependencies: only built-in Node.js APIs and the package's own launcher/ helpers.
 //
 // better-sqlite3 v13 requires Node-API 10, available from:
 //   Node 22.14.0 LTS   (released 2025-02-06)
 //   Node 23.6.0        (released 2025-01-13)
 //   Node 24+
 //
-// This guard exits 1 when the running Node does not support N-API 10 so
-// npm aborts the install and keeps the previously installed version intact.
+// #1450: where this release pins a bundled Node for a supported host (Linux glibc >= 2.28 or macOS 11+, x64/arm64),
+// the system Node's version is NEVER a reason to refuse — 20, 18, 16, any Node whose npm can run the install: AgEnD
+// will not run on it. preinstall cannot verify the bundled Node (it is not on disk yet); launcher/postinstall.cjs
+// proves it inside the same npm transaction and refuses (npm rolls back, the previous install stays) if it cannot.
+// The one refusal here: a host no bundled Node covers (musl, 32-bit, another OS, older glibc/macOS, or a release that
+// pins none) AND a system Node older than ENGINES — AgEnD would install and then not start.
+// Old syntax only (var, no ?. ??, no trailing call commas): this runs under whatever Node runs npm.
 //
+// Exiting 1 aborts the install and keeps the previously installed version intact.
 // --ignore-scripts bypasses this check; see Upgrade Notes in the changelog.
 
 "use strict";
 
-const [maj, min] = process.versions.node.split(".").map(Number);
-const ok =
-  maj >= 24 ||
-  (maj === 23 && min >= 6) ||
-  (maj === 22 && min >= 14);
+var path = require("path");
+var fs = require("fs");
+var platform = require(path.join(__dirname, "..", "launcher", "runtime-platform.cjs"));
 
-if (!ok) {
-  process.stderr.write(
-    "\n" +
-    "  AgEnD 2.2 needs Node >=22.14; npm is aborting this install.\n" +
-    "\n" +
-    "  Running: Node " + process.versions.node + "\n" +
-    "  Required: ^22.14.0 || ^23.6.0 || >=24\n" +
-    "\n" +
-    "  Update Node to a compatible version, then retry:\n" +
-    "    npm install -g @songsid/agend\n" +
-    "\n",
-  );
-  process.exit(1);
+var ENGINES = "^22.14.0 || ^23.6.0 || >=24";
+var running = process.versions.node;
+var napi = Number(process.versions.napi);
+
+if (platform.satisfiesEngines(running, ENGINES) && napi >= 10) process.exit(0);
+
+var manifest = {};
+try { manifest = JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8")); } catch (e) { /* none */ }
+var host = platform.hostPlatform();
+var pinned = manifest.optionalDependencies && manifest.optionalDependencies["@songsid/agend-node-" + host.id];
+var support = platform.runtimeSupport(host);
+if (pinned && support.supported) {
+  // The bundled Node is pinned and fits this host: postinstall verifies it before the install can complete.
+  process.exit(0);
 }
+
+process.stderr.write(
+  "\n" +
+  "  AgEnD 2.2 needs Node >=22.14; npm is aborting this install.\n" +
+  "\n" +
+  "  Running: Node " + running + "\n" +
+  "  Required: " + ENGINES + "\n" +
+  (pinned ? "  " + support.reason + ", so AgEnD's bundled Node cannot be used here either.\n" : "") +
+  "\n" +
+  "  Update Node to a compatible version, then retry:\n" +
+  "    npm install -g @songsid/agend\n" +
+  "\n"
+);
+process.exit(1);

package/templates/launchd.plist.ejs

@@ -6,8 +6,8 @@
     <string><%= label %></string>
     <key>ProgramArguments</key>
     <array>
-        <string><%= execPath %></string>
-        <string>fleet</string>
+<% for (const word of program) { %>        <string><%= word %></string>
+<% } %>        <string>fleet</string>
         <string>start</string>
     </array>
     <key>EnvironmentVariables</key>

package/templates/systemd.service.ejs

@@ -22,16 +22,16 @@ NotifyAccess=all
 # Bounded so a start that hangs before READY is noticed (#1113).
 TimeoutStartSec=15min
 WatchdogSec=60
-ExecStart=<%= execPath %> fleet start
+ExecStart=<%- program.map(systemdQuote).join(" ") %> fleet start
 Environment=PATH=<%= path %>
 Environment=TERM=xterm-256color
 <% if (isRoot) { %>Environment=IS_SANDBOX=1
 <% } %>WorkingDirectory=<%= workingDirectory %>
 Restart=on-failure
 RestartSec=5
-# Daemon shutdown is bounded per batch; do not let an uncooperative backend
-# hold systemctl stop/update for the previous five-minute default.
-TimeoutStopSec=60
+# Busy Kiro instances need 15s to drain + 5s quit + 2s signal grace in each
+# sequential batch. Keep an outer bound, but allow several batches (#1071).
+TimeoutStopSec=<%= stopTimeoutSec %>
 # Stop by signalling the fleet process only (#908). The tmux server and every
 # CLI inside it live in this unit's cgroup, and the default control-group mode
 # SIGTERMs all of them at once: kiro-cli aborted (SIGABRT, a ~1 GB core dump on