@songsid/agend 2.3.0-beta.2 → 2.3.0-beta.21

package/launcher/agend-install.cjs

@@ -0,0 +1,553 @@
+#!/usr/bin/env node
+"use strict";
+// #2264: AgEnD's one installer. Install, upgrade and repair are this file, always run from the TARGET release itself:
+//
+//   npm exec --yes --package @songsid/agend@<version> -- agend-install [--upgrade]
+//
+// install.sh (and so the Windows installer) and `agend update` both end here, so the newest install logic runs on every
+// install — never an old updater that happens to be on the host. It installs exactly the version it ships in, and:
+//   1. owns the npm prefix first (admit(): a live installer's lock → stop, nothing changed) and keeps it to the end;
+//   2. repairs what an interrupted install left in the prefix (repair(): only while no npm changes packages; the only
+//      copy of AgEnD put back, anything else moved to quarantine, never deleted);
+//   3. `npm install -g @songsid/agend@<this version>` (once more only if repairing moved something npm itself left);
+//   4. proves `<prefix>/bin/agend --version` is this version; otherwise says what runs now — the previous version that
+//      npm kept is left as it is, and only an `agend` that does not run is reinstalled;
+//   5. on a host with a service: `agend install --no-activate` under the manager it has, then the fleet is restarted
+//      (or started, when its service is stopped); a hand-started fleet is restarted by an upgrade only;
+//   6. records each step in the update marker the fleet edits its chat message from — only a marker it owns.
+// Nothing here refuses a manual `npm install -g`: the lock only keeps two of THESE installers from running at once.
+// Old syntax only (var, no ?. ??): this runs on whatever Node runs npm.
+var fs = require("fs");
+var path = require("path");
+var os = require("os");
+var childProcess = require("child_process");
+
+var LOCK = ".agend-install.lock";
+var MARKER = "update-in-progress.json";
+
+function defaultDeps() {
+  return {
+    run: function (cmd, args, opts) {
+      var o = opts || {};
+      var r = childProcess.spawnSync(cmd, args, { encoding: "utf8", stdio: o.inherit ? "inherit" : ["ignore", "pipe", "pipe"], env: o.env || process.env, timeout: o.timeoutMs });
+      return { status: r.status, signal: r.signal, stdout: r.stdout || "", stderr: r.stderr || "", error: r.error ? String(r.error.code || r.error.message) : null };
+    },
+    log: function (line) { process.stdout.write(line + "\n"); },
+    pid: process.pid,
+    alive: function (pid) { try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; } },
+    uid: typeof process.getuid === "function" ? process.getuid() : -1,
+    env: process.env,
+    now: function () { return Date.now(); },
+  };
+}
+
+function readJson(file) { try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch (e) { return null; } }
+function last(text) { var lines = String(text || "").trim().split("\n"); return (lines[lines.length - 1] || "").trim(); }
+/** A whole AgEnD package in `dir` — its package.json and every bin it names — gives its version; a partial one, null. */
+function isAgendPackage(dir) {
+  var p = readJson(path.join(dir, "package.json"));
+  if (!p || p.name !== "@songsid/agend" || typeof p.version !== "string" || !p.bin || typeof p.bin !== "object") return null;
+  var bins = Object.keys(p.bin).map(function (k) { return p.bin[k]; });
+  return bins.length && bins.every(function (b) { return typeof b === "string" && fs.existsSync(path.join(dir, b)); }) ? p.version : null;
+}
+
+/**
+ * The update marker the fleet edits its chat message from (src/update-marker.ts) — written only while this installer
+ * owns it (#2264 review). It is claimed once this installer holds the prefix: when the `agend update` that started it
+ * wrote it (AGEND_UPDATE_OWNER_PID), or when its writer is gone (an update that died: the user's stuck "downloading").
+ * A marker another live process writes — a running update's, a new fleet's — is never changed. Every write re-reads it
+ * and writes only while this installer is still its writer (a new update or a new fleet that took it over keeps it).
+ */
+function claimMarker(home, deps, opts) {
+  var marker = readJson(path.join(home, MARKER));
+  if (!marker || !marker.progress || typeof marker.pid !== "number") return null;
+  var owner = Number(deps.env.AGEND_UPDATE_OWNER_PID) || 0;
+  var ours = marker.pid === deps.pid || (owner > 0 && marker.pid === owner);
+  if (!ours && (opts.ownOnly || deps.alive(marker.pid))) return null;
+  return writeMarker(home, marker, deps);
+}
+function writeMarker(home, marker, deps) {
+  var file = path.join(home, MARKER);
+  marker.pid = deps.pid;
+  var tmp = file + "." + deps.pid + ".tmp";
+  try { fs.writeFileSync(tmp, JSON.stringify(marker), { mode: 384 }); fs.renameSync(tmp, file); return true; } catch (e) { return false; }
+}
+function setStage(home, claimed, stage, details, deps) {
+  if (!claimed) return false;
+  var marker = readJson(path.join(home, MARKER));
+  if (!marker || !marker.progress || marker.pid !== deps.pid) return false;
+  var previous = marker.progress.stage;
+  marker.progress.stage = stage;
+  if (details.version) marker.progress.version = details.version;
+  if (details.error) marker.progress.error = String(details.error).replace(/\s+/g, " ").trim().slice(0, 300);
+  if (stage === "failed") marker.progress.failedStage = previous;
+  return writeMarker(home, marker, deps);
+}
+
+/**
+ * Is npm provably idle on this host — is no npm process changing installed packages? Only an npm that installs,
+ * uninstalls, updates, links or rebuilds can be reifying this prefix. `npm exec` (this installer's own ancestor; AgEnD
+ * fleets run their MCP servers that way, for hours), `npm view`, `npm run` cannot, so they do not count. npm rewrites its
+ * process title to `npm <command> <args>` without its flags, but argv as started shows them, and a flag is read the way
+ * npm reads it (Prism r2): one that takes a value consumes the next word whatever it is (`npm --prefix run install` is an
+ * install); one that takes none consumes nothing; an unknown one may be either, and both readings are kept. The npm
+ * counts as idle only if every reading's command is one that cannot reify; an unknown word as the command is busy. A
+ * process list that cannot be read (ps failed, a row that does not parse, this process missing from it) is not idle.
+ */
+var NPM_CHANGES = /^(?:install|i|in|ins|inst|insta|instal|isnt|isnta|isntal|isntall|add|uninstall|un|unlink|remove|rm|r|update|up|upgrade|udpate|link|ln|ci|clean-install|install-clean|ic|isntall-clean|install-ci-test|cit|install-test|it|dedupe|ddp|find-dupes|prune|rebuild|rb)$/;
+var NPM_READS = /^(?:exec|x|access|adduser|add-user|login|logout|audit|bugs|issues|cache|completion|config|c|get|set|deprecate|diff|dist-tag|dist-tags|docs|home|doctor|edit|explain|why|explore|fund|help|help-search|hook|init|create|innit|ls|list|la|ll|org|ogr|outdated|owner|author|pack|ping|pkg|prefix|profile|publish|query|repo|restart|root|run|run-script|rum|urn|sbom|search|find|s|se|shrinkwrap|star|stars|start|stop|team|test|tst|t|token|unpublish|unstar|version|verison|view|v|info|show|whoami)$/;
+// npm's flags that take a value (npm 10 config definitions) and the common ones that take none.
+var NPM_VALUE_FLAGS = /^(?:--(?:prefix|userconfig|globalconfig|cache|registry|loglevel|workspace|tag|otp|package|call|omit|include|before|access|scope|script-shell|shell|node-options|location|install-strategy|depth|auth-type|cafile|cert|key|proxy|https-proxy|noproxy|local-address|fetch-retries|fetch-timeout|maxsockets|user-agent|editor|browser|viewer|init-module|tag-version-prefix|preid|message|logs-dir|logs-max|replace-registry-host|cidr|expect-results|expect-result-count|sbom-format|sbom-type|lockfile-version|os|cpu|libc)|-w|-C|-c|-m)$/;
+var NPM_BOOLEAN_FLAGS = /^(?:-g|-y|-f|-s|-q|-d|-dd|-ddd|-S|-D|-O|-E|-B|-P|-l|-a|-h|-H|-v|--(?:no-[a-z0-9-]+|global|yes|force|silent|quiet|dry-run|json|offline|prefer-offline|prefer-online|ignore-scripts|foreground-scripts|legacy-peer-deps|strict-peer-deps|package-lock-only|save|save-dev|save-optional|save-exact|save-prod|save-peer|save-bundle|global-style|install-links|link|verbose|long|parseable|audit|fund|workspaces|include-workspace-root|if-present|production|usage|help|version|all|unicode|progress|update-notifier|bin-links|rebuild-bundle|engine-strict|prefer-dedupe|read-only|provenance|timing|umask))$/;
+function isNpmCommand(word) { return NPM_CHANGES.test(word) || NPM_READS.test(word); }
+function npmCommands(args) {
+  var words = args.split(/\s+/).filter(function (w) { return w !== ""; });
+  var at = -1;
+  for (var k = 0; k < words.length && k < 3; k++) {
+    if (/(?:^|\/)(?:npm|npx)$/.test(words[k]) || /(?:^|\/)(?:npm|npx)-cli\.js$/.test(words[k])) { at = k; break; }
+  }
+  if (at < 0) return null;
+  if (/npx(?:-cli\.js)?$/.test(words[at])) return ["exec"];
+  // Every command this argv can mean: `pending` = the next word may be an unknown flag's value.
+  var readings = function (from, pending) {
+    for (var w = from; w < words.length; w++) {
+      var word = words[w];
+      if (word.charAt(0) === "-") {
+        if (word.indexOf("=") >= 0 || NPM_BOOLEAN_FLAGS.test(word)) { pending = false; continue; }
+        if (NPM_VALUE_FLAGS.test(word)) { w++; pending = false; continue; }   // its value, whatever it says
+        pending = true;   // unknown: a value may follow, or not
+        continue;
+      }
+      var asCommand = isNpmCommand(word) ? [word] : ["?"];
+      return pending ? asCommand.concat(readings(w + 1, false)) : asCommand;
+    }
+    return pending ? [] : ["?"];
+  };
+  var all = readings(at + 1, false);
+  return all.length ? all : ["?"];
+}
+function npmIdleFromProcessList(output, ownPid) {
+  var rows = String(output).trim().split("\n").map(function (line) {
+    var m = /^\s*(\d+)\s+(\d+)\s+(.+)$/.exec(line);
+    return m ? { pid: Number(m[1]), parent: Number(m[2]), args: m[3] } : null;
+  });
+  if (!rows.length || rows.some(function (row) { return !row; })) return false;
+  if (!rows.some(function (row) { return row.pid === ownPid; })) return false;
+  return !rows.some(function (row) {
+    var commands = npmCommands(row.args);
+    return commands !== null && !commands.every(function (c) { return NPM_READS.test(c); });
+  });
+}
+function npmIdle(deps) {
+  var r = deps.run("ps", ["-A", "-o", "pid=,ppid=,args="], { timeoutMs: 5000 });
+  return r.status === 0 && npmIdleFromProcessList(r.stdout, deps.pid);
+}
+
+/** Move a leftover into `<prefix>/.agend-quarantine/<time>-<pid>/` — kept as evidence, never deleted here. */
+function quarantine(prefix, source, deps, name) {
+  var dir = path.join(prefix, ".agend-quarantine", new Date(deps.now()).toISOString().replace(/[:.]/g, "-") + "-" + deps.pid);
+  fs.mkdirSync(dir, { recursive: true });
+  var to = path.join(dir, name || path.basename(source));
+  fs.renameSync(source, to);
+  return to;
+}
+
+function readText(file) { try { return fs.readFileSync(file, "utf8"); } catch (e) { return null; } }
+/** Create `file` holding `text` only if it does not exist: written aside, then linked into place (whole or not at all). */
+function createWhole(file, text, deps) {
+  var tmp = file + "." + deps.pid + ".tmp";
+  fs.writeFileSync(tmp, text, { mode: 384 });
+  try { fs.linkSync(tmp, file); return true; } catch (e) { return false; } finally { try { fs.unlinkSync(tmp); } catch (e) { /* gone */ } }
+}
+
+/**
+ * The lock of updaters from before #2264 (src/install-lock.ts acquireInstallLock), which they alone understand — so it is
+ * kept by their own rules (Prism r3): a record in their format (pid + start time, read by install-admission.cjs, so a
+ * running old updater sees this installer as a live holder and waits); a holder judged as they judge it (live, stale or
+ * unknown — unknown blocks); and a stale lock moved only by the holder of `<lock>.reclaim` (claimed whole), under which
+ * the lock can change only by its own holder — proven gone. Nothing is ever moved aside to be judged afterwards. One
+ * thing more than they do: a lock that cannot be read (created, never filled: the user's, cut short) — their
+ * create-then-write keeps the file open from the create to the write, and no one else can open it to write it (theirs is
+ * open(wx)). So it counts as stale only when it is proven that no process has it open (openedBy); its age is no evidence
+ * (Prism r4: an old writer paused between open and write for a minute is still admitted when it resumes).
+ */
+var lockReaders = require("./install-admission.cjs");
+/**
+ * Does any process have `file` open? true / false, or null when that cannot be told — which blocks. Only processes of the
+ * file's owner can have created it and hold it open to write (its creator is its owner). Linux: every such process's
+ * /proc/<pid>/fd, matched by device and inode. A process of the same user whose descriptors cannot be read is one that
+ * made itself non-dumpable (sd-pam, ssh-agent, gpg-agent); Node never does, so it is an old updater only if its command
+ * line names node or agend — then, and when even that cannot be read, null. macOS: lsof (exit 1 with no output = none).
+ * Elsewhere: null.
+ */
+/** What a descriptor's link names when it is no file on disk: it cannot be the lock. */
+var NOT_A_FILE = /^(?:(?:pipe|socket):\[\d+\]|anon_inode:.*|\/dev\/(?:null|zero|u?random|full|tty\w*|console|ptmx|pts\/\d+))$/;
+/** Why the last openedBy answered as it did (a refusal names it, so a stuck host says exactly what could not be read). */
+var openedWhy = "";
+function openedBy(file, deps) {
+  openedWhy = "";
+  var unknown = function (why) { openedWhy = why; return null; };
+  var because = function (e, what) { return (e && e.code ? e.code : String(e)) + " on " + what; };
+  if (deps.openedBy) return deps.openedBy(file);
+  // Only a definite "it is gone" (ENOENT) may be skipped; a permission, I/O or any other error proves nothing (Prism r5:
+  // /proc/<pid>/fd is behind ptrace checks) → unknown, which blocks.
+  var stat = deps.procStat || fs.statSync;
+  var readdir = deps.procReaddir || fs.readdirSync;
+  var gone = function (e) { return e && e.code === "ENOENT"; };
+  var st;
+  try { st = stat(file); } catch (e) { return gone(e) ? false : unknown(because(e, file)); }
+  if (process.platform === "linux") {
+    var pids;
+    try { pids = fs.readdirSync("/proc").filter(function (n) { return /^\d+$/.test(n); }); } catch (e) { return unknown(because(e, "/proc")); }
+    for (var k = 0; k < pids.length; k++) {
+      var owner;
+      try { owner = stat("/proc/" + pids[k]).uid; } catch (e) { if (gone(e)) continue; return unknown(because(e, "/proc/" + pids[k])); }   // gone meanwhile, or unknown
+      if (owner !== st.uid) continue;
+      var fds;
+      // A process this one may not inspect (EACCES: non-dumpable, or other credentials — the kernel's ptrace check on
+      // its descriptors) is not an old updater, a plain node process of this user, unless its command line says so.
+      var notInspectable = function (pid, what) {
+        var cmdline = null;
+        try { cmdline = fs.readFileSync("/proc/" + pid + "/cmdline", "utf8"); } catch (e2) { if (gone(e2)) return "gone"; }
+        if (cmdline === null || /node|agend/i.test(cmdline)) return "EACCES on " + what + " (" + (cmdline === null ? "its command line unreadable" : JSON.stringify(cmdline.replace(/\0/g, " ").trim().slice(0, 80))) + ")";
+        return "skip";
+      };
+      try { fds = readdir("/proc/" + pids[k] + "/fd"); } catch (e) {
+        if (gone(e)) continue;
+        if (e.code !== "EACCES") return unknown(because(e, "/proc/" + pids[k] + "/fd"));
+        var verdict = notInspectable(pids[k], "/proc/" + pids[k] + "/fd");
+        if (verdict === "gone" || verdict === "skip") continue;
+        return unknown(verdict);
+      }
+      for (var f = 0; f < fds.length; f++) {
+        var seen;
+        var fdPath = "/proc/" + pids[k] + "/fd/" + fds[f];
+        try { seen = stat(fdPath); } catch (e) {
+          if (gone(e)) continue;   // closed meanwhile
+          // Its target cannot be stat'ed (a security module, as on CI runners): the link itself still names it. A pipe,
+          // a socket, an anonymous inode or a terminal/null device is not the lock (a regular file in the prefix).
+          var target = null, linkError = null;
+          try { target = (deps.procReadlink || fs.readlinkSync)(fdPath); } catch (e2) { if (gone(e2)) continue; linkError = e2; }
+          if (target !== null && NOT_A_FILE.test(target)) continue;
+          if (target === null && e.code === "EACCES" && linkError && linkError.code === "EACCES") {
+            // Neither its target nor its link may be read: the process is not inspectable at all (CI runners have one).
+            var seenAs = notInspectable(pids[k], fdPath);
+            if (seenAs === "gone" || seenAs === "skip") break;
+            return unknown(seenAs);
+          }
+          return unknown(because(e, fdPath) + (target !== null ? " → " + target : ""));
+        }
+        if (seen.dev === st.dev && seen.ino === st.ino) { openedWhy = "pid " + pids[k] + " has it open"; return true; }
+      }
+    }
+    return false;
+  }
+  if (process.platform === "darwin") {
+    var r = deps.run(fs.existsSync("/usr/sbin/lsof") ? "/usr/sbin/lsof" : "lsof", ["-nP", "-t", "--", file], { timeoutMs: 15000 });
+    if (r.status === 0 && String(r.stdout).trim()) { openedWhy = "pid " + String(r.stdout).trim().split("\n").join(", ") + " has it open"; return true; }
+    if (r.status === 1 && !String(r.stdout).trim() && !String(r.stderr).trim()) return false;
+    return unknown("lsof exited " + (r.status === null ? r.error || r.signal : r.status) + (String(r.stderr).trim() ? ": " + String(r.stderr).trim().slice(0, 120) : ""));
+  }
+  return unknown("no way to see open files on " + process.platform);
+}
+/** An unreadable lock that may still be being written: refused, saying what was seen. */
+function beingWritten(lock, why) {
+  return "the install lock " + lock + " is being written by another AgEnD install, or whether it still is cannot be told" + (why ? " (" + why + ")" : "") + "; run this again in a moment";
+}
+function legacyRecord(prefix, deps, spec, home) {
+  var r = deps.lockReaders || lockReaders;
+  var ticks = r.startTicks(deps.pid), boot = r.bootId();
+  var record = { pid: deps.pid, processStart: r.processStart(deps.pid) || "" };
+  if (ticks !== null && boot !== null) { record.startTicks = ticks; record.bootId = boot; }
+  record.prefix = prefix; record.targetSpec = spec; record.agendHome = home;
+  record.token = require("crypto").randomBytes(16).toString("hex");
+  record.createdAt = new Date(deps.now()).toISOString();
+  return JSON.stringify(record) + "\n";
+}
+function legacyState(text, file, deps) {
+  var r = deps.lockReaders || lockReaders;
+  var holder = r.parse(text);
+  if (holder) return { state: holder.pid === deps.pid ? "stale" : r.holderState(holder, { exists: deps.alive, processStart: r.processStart, startTicks: r.startTicks, bootId: r.bootId }), pid: holder.pid };
+  if (!fs.existsSync(file)) return { state: "gone" };
+  var open = openedBy(file, deps);
+  return { state: open === false ? "stale" : "unknown", unreadable: true, why: openedWhy };
+}
+/** Move a stale legacy lock away by their rule: only under `<lock>.reclaim`, and only the bytes judged. */
+function reclaimLegacy(prefix, lock, judged, judgedState, record, deps) {
+  var marker = lock + ".reclaim";
+  if (!createWhole(marker, record, deps)) {
+    var other = (deps.lockReaders || lockReaders).parse(readText(marker) || "");
+    var otherState = other ? legacyState(readText(marker) || "", marker, deps).state : "unknown";
+    return otherState === "live" ? { refuse: "another install is replacing the stale lock on " + prefix + "; run this again in a moment" }
+      : { refuse: "a reclaim marker " + marker + " was left behind (pid " + (other ? other.pid : "unknown") + "); if no `agend update` runs, remove it and run this again" };
+  }
+  try {
+    if (deps.onStep) deps.onStep("legacy-reclaimed");
+    // Under the marker the lock changes only by its own (gone) holder: still the one judged, else nothing is moved.
+    if (readText(lock) !== judged) return { changed: true };
+    // An unreadable one: still not open anywhere (no writer can open it again: theirs is open(wx) on a new file).
+    if (judgedState.unreadable && openedBy(lock, deps) !== false) return { refuse: beingWritten(lock, openedWhy) };
+    quarantine(prefix, lock, deps);
+    return { moved: true };
+  } finally {
+    if (readText(marker) === record) { try { fs.unlinkSync(marker); } catch (e) { /* gone */ } }
+  }
+}
+
+var ENTRIES = ".agend-install.d";
+function holderOf(text) {
+  var holder = null;
+  try { holder = JSON.parse(text); } catch (e) { holder = null; }
+  return holder && typeof holder.pid === "number" ? holder : null;
+}
+
+/**
+ * Admission (#2264 review): this installer owns the prefix before anything in it is touched, and keeps it through the
+ * repair, the install, its retry and the rollback.
+ *
+ * Between these installers it is announce-then-check — nothing of another installer is ever moved to decide it (Prism
+ * r2: a takeover of a shared lock path can always move a newer owner's lock by a stale reader). Each installer writes an
+ * entry of its own, `<prefix>/.agend-install.d/<pid>-<random>` (whole, written aside and linked), and only then lists the
+ * others: one whose writer runs → it withdraws its own entry and refuses (75). Of two that race, at least the later one
+ * sees the earlier's entry, so two are never admitted (both may refuse: run again). An entry whose writer is gone has a
+ * name no one else will ever write, so it is moved to quarantine without a race.
+ *
+ * The admitted installer then also holds `<prefix>/.agend-install.lock`, the lock updaters from before #2264 take, by
+ * their rules (above): one of theirs that runs, or whose holder cannot be told → refuse; a stale one is moved to
+ * quarantine under their `.reclaim` marker. Its token is this installer's: every npm install it runs presents it
+ * (AGEND_INSTALL_TOKEN), because a release from before #2264 — a target installed by --spec, the previous version put
+ * back — admits its own postinstall only for the token of the live lock (#2286 review).
+ * Returns { release, notes, token } or { refuse }.
+ */
+function admit(prefix, deps, opts) {
+  opts = opts || {};
+  // The prefix as old updaters name it (realpath): one lock however the prefix was reached.
+  try { prefix = fs.realpathSync(prefix); } catch (e) { /* the writes below say */ }
+  var dir = path.join(prefix, ENTRIES);
+  var name = deps.pid + "-" + (deps.nonce ? deps.nonce() : require("crypto").randomBytes(8).toString("hex"));
+  var mine = path.join(dir, name);
+  var record = JSON.stringify({ pid: deps.pid, by: "agend-install", createdAt: new Date(deps.now()).toISOString() }) + "\n";
+  var notes = [];
+  try { fs.mkdirSync(dir, { recursive: true }); } catch (e) { /* the create below says */ }
+  if (!createWhole(mine, record, deps)) return { refuse: "cannot write an install entry in " + dir };
+  var withdraw = function () { if (readText(mine) === record) { try { fs.unlinkSync(mine); } catch (e) { /* gone */ } } };
+  if (deps.onStep) deps.onStep("announced");
+  var others = [];
+  try { others = fs.readdirSync(dir).filter(function (n) { return n !== name && !/\.tmp$/.test(n); }); } catch (e) { withdraw(); return { refuse: "cannot list " + dir }; }
+  for (var k = 0; k < others.length; k++) {
+    var holder = holderOf(readText(path.join(dir, others[k])));
+    if (holder && holder.pid !== deps.pid && deps.alive(holder.pid)) {
+      withdraw();
+      return { refuse: "another AgEnD install (pid " + holder.pid + ") is running in " + prefix + "; let it finish, then run this again" };
+    }
+  }
+  others.forEach(function (n) {
+    // Gone (or written by no installer): its name is its writer's alone.
+    try { quarantine(prefix, path.join(dir, n), deps); notes.push("moved aside an install entry left by an installer that is no longer running"); } catch (e) { /* gone */ }
+  });
+
+  var lock = path.join(prefix, LOCK);
+  var legacy = legacyRecord(prefix, deps, opts.spec || "", opts.home || "");
+  for (var attempt = 0; attempt < 3; attempt++) {
+    if (createWhole(lock, legacy, deps)) {
+      return { notes: notes, token: JSON.parse(legacy).token, release: function () {
+        if (readText(lock) === legacy) { try { fs.unlinkSync(lock); } catch (e) { /* gone */ } }
+        withdraw();
+      } };
+    }
+    var text = readText(lock);
+    if (text === null) continue;
+    var judged = legacyState(text, lock, deps);
+    if (judged.state === "gone") continue;
+    if (judged.state !== "stale") {
+      withdraw();
+      return { refuse: judged.unreadable
+        ? beingWritten(lock, judged.why)
+        : "another AgEnD install (pid " + judged.pid + ") is running in " + prefix + "; let it finish, then run this again" };
+    }
+    if (deps.onStep) deps.onStep("legacy-judged");
+    var taken = reclaimLegacy(prefix, lock, text, judged, legacy, deps);
+    if (taken.refuse) { withdraw(); return { refuse: taken.refuse }; }
+    if (taken.moved) notes.push(judged.unreadable ? "moved aside an install lock that could not be read" : "moved aside an install lock left by pid " + judged.pid + " (no longer running)");
+  }
+  withdraw();
+  return { refuse: "another AgEnD install keeps claiming " + lock + "; let it finish, then run this again" };
+}
+
+/**
+ * What an interrupted install leaves, put right — only by the installer that owns the prefix (admit), and only while
+ * npm is provably idle (above); otherwise npm's leftovers are left alone. npm's retire sibling `@songsid/.agend-<hash>`
+ * (npm moves the installed package there before it writes the new one; killed in between, every later `npm install -g`
+ * fails ENOTEMPTY on it): the only whole copy of AgEnD is put back (a partial new package in its place goes to
+ * quarantine); any other sibling, and npm's retired bin links `bin/.agend-<hash>`, go to quarantine. The lock is not
+ * this function's: it never reads or moves one.
+ */
+function repair(root, prefix, deps) {
+  var notes = [];
+  var scope = path.join(root, "@songsid");
+  var current = path.join(scope, "agend");
+  var siblings = [];
+  try { siblings = fs.readdirSync(scope).filter(function (n) { return /^\.agend-/.test(n); }); } catch (e) { siblings = []; }
+  var binDir = path.join(prefix, "bin");
+  var binSiblings = [];
+  try { binSiblings = fs.readdirSync(binDir).filter(function (n) { return /^\.agend(-agent|-install)?-[A-Za-z0-9]{8}$/.test(n); }); } catch (e) { binSiblings = []; }
+  if (!siblings.length && !binSiblings.length) return { notes: notes, changed: false };
+  if (!(deps.npmIdle || npmIdle)(deps)) {
+    notes.push("another npm is running on this host, so what an earlier install left in " + scope + " was not touched");
+    return { notes: notes, changed: false };
+  }
+  siblings.forEach(function (name) {
+    var dir = path.join(scope, name);
+    var version = isAgendPackage(dir);
+    if (version && !isAgendPackage(current)) {
+      if (fs.existsSync(current)) quarantine(prefix, current, deps);
+      fs.renameSync(dir, current);
+      notes.push("put back AgEnD v" + version + " that an interrupted install had moved aside (" + name + ")");
+      return;
+    }
+    notes.push("moved " + name + ", left by an interrupted install, to " + quarantine(prefix, dir, deps));
+  });
+  binSiblings.forEach(function (name) {
+    try { quarantine(prefix, path.join(binDir, name), deps); notes.push("moved bin/" + name + ", left by an interrupted install, to quarantine"); } catch (e) { /* gone */ }
+  });
+  return { notes: notes, changed: true };
+}
+
+/**
+ * The service AgEnD installed, as `agend restart` picks its authority: the legacy system unit first, then the user unit
+ * or the launchd job. null: a hand-started fleet, or none.
+ */
+function serviceKind(deps) {
+  var home = deps.env.HOME || os.homedir();
+  if (fs.existsSync(deps.systemUnit || "/etc/systemd/system/agend.service")) return "system";
+  if (fs.existsSync(path.join(home, ".config", "systemd", "user", "com.agend.fleet.service"))) return "user";
+  if (fs.existsSync(path.join(home, "Library", "LaunchAgents", "com.agend.fleet.plist"))) return "launchd";
+  return null;
+}
+/** A fleet runs now: fleet.pid names a live process. */
+function fleetRunning(home, deps) {
+  var pid = Number(String(readText(path.join(home, "fleet.pid")) || "").trim());
+  return pid > 0 && deps.alive(pid);
+}
+
+function versionOf(agendBin, deps) {
+  var r = deps.run(agendBin, ["--version"], { timeoutMs: 60000 });
+  return r.status === 0 ? last(r.stdout).replace(/^v/i, "") : null;
+}
+
+function main(argv, injected) {
+  var deps = injected || defaultDeps();
+  var args = argv || [];
+  var upgrade = args.indexOf("--upgrade") >= 0;
+  var specAt = args.indexOf("--spec");
+  var targetAt = args.indexOf("--target");
+  // Where the previous version is reinstalled from when the new one does not prove itself (tests and mirrors).
+  var previousAt = args.indexOf("--previous-spec");
+  var own = readJson(path.join(__dirname, "..", "package.json")) || {};
+  var version = own.version;
+  var log = deps.log;
+  // `agend update` names the release it chose: this must be that release's own installer, never another one npm found
+  // on PATH (a target without agend-install makes `npm exec` run whatever agend-install PATH has; #2264 review).
+  if (targetAt >= 0 && args[targetAt + 1] !== version) {
+    log("  ✗ this is the installer of AgEnD v" + version + ", not of v" + args[targetAt + 1] + " — nothing was changed");
+    return 1;
+  }
+  // The package this installer ships in, unless a test or a mirror names another source of the same version.
+  var spec = specAt >= 0 ? args[specAt + 1] : "@songsid/agend@" + version;
+  // An exact `@songsid/agend@<version>` spec names the version to prove; anything else (a tarball, a tag) is this one.
+  var exact = /^@songsid\/agend@(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)$/.exec(spec);
+  if (exact) version = exact[1];
+  var home = deps.env.AGEND_HOME || path.join(os.homedir(), ".agend");
+  var claimed = false;
+  var fail = function (stage, message) {
+    log("  ✗ " + message);
+    setStage(home, claimed, "failed", { error: message }, deps);
+    return stage === "lock" ? 75 : 1;
+  };
+
+  log("  AgEnD installer v" + version + (upgrade ? " (upgrade)" : ""));
+  var root = last(deps.run("npm", ["root", "-g"], { timeoutMs: 30000 }).stdout);
+  var prefix = last(deps.run("npm", ["prefix", "-g"], { timeoutMs: 30000 }).stdout);
+  if (!root || !prefix) {
+    claimed = claimMarker(home, deps, { ownOnly: true });
+    return fail("install", "npm did not say where it installs global packages (npm root -g / npm prefix -g)");
+  }
+  var admitted = admit(prefix, deps, { spec: spec, home: home });
+  admitted.notes && admitted.notes.forEach(function (n) { log("  ↺ " + n); });
+  if (admitted.refuse) {
+    // Refused: another installer owns the prefix. Only the marker of the `agend update` that started THIS installer
+    // says so; anyone else's (the running update's) is left exactly as it is.
+    claimed = claimMarker(home, deps, { ownOnly: true });
+    return fail("lock", admitted.refuse);
+  }
+  try {
+    claimed = claimMarker(home, deps, {});
+    setStage(home, claimed, "downloading", { version: version }, deps);
+    var fixed = repair(root, prefix, deps);
+    fixed.notes.forEach(function (n) { log("  ↺ " + n); });
+    var previous = isAgendPackage(path.join(root, "@songsid", "agend"));
+    var bin = path.join(prefix, "bin", "agend");
+    // #2286 review: the lock's token, for a release from before #2264 (its postinstall refuses any other install).
+    var npmEnv = Object.assign({}, deps.env);
+    npmEnv[lockReaders.TOKEN_ENV] = admitted.token;
+    var install = function () { return deps.run("npm", ["install", "-g", spec], { inherit: true, env: npmEnv }); };
+    var done = install();
+    if (done.status !== 0) {
+      // npm itself can leave its sibling behind (a failure inside its own move): once more, only if repairing moved one.
+      var again = repair(root, prefix, deps);
+      again.notes.forEach(function (n) { log("  ↺ " + n); });
+      if (again.changed) done = install();
+    }
+    var got = done.status === 0 ? versionOf(bin, deps) : null;
+    if (got !== version) {
+      var why = done.status !== 0 ? "npm install -g " + spec + " failed (exit " + (done.status === null ? done.signal : done.status) + ")"
+        : "after npm install, " + bin + " reports " + (got || "nothing") + ", not v" + version;
+      // What actually runs now. npm rolls a failed install back itself: when the previous version still runs, nothing
+      // else is done and that is what is said. Only an `agend` that does not run is reinstalled.
+      var running = versionOf(bin, deps);
+      if (running && done.status !== 0) return fail("install", why + "; v" + running + " is still installed and runs — nothing was changed");
+      if (previous && previous !== version) {
+        repair(root, prefix, deps);
+        var back = deps.run("npm", ["install", "-g", previousAt >= 0 ? args[previousAt + 1] : "@songsid/agend@" + previous], { inherit: true, env: npmEnv });
+        if (back.status === 0 && versionOf(bin, deps) === previous) return fail("install", why + "; v" + previous + " was reinstalled and runs");
+      }
+      return fail("install", why + (previous ? "; v" + previous + " could not be put back — run the installer again" : ""));
+    }
+    log("  ✓ AgEnD v" + version + " is installed (" + bin + ")");
+    // Root under nvm: the service, cron and non-login shells do not source nvm — give them the same agend and node.
+    if (deps.uid === 0 && prefix.indexOf("/.nvm/") >= 0) {
+      [["agend", bin], ["node", path.join(prefix, "bin", "node")]].forEach(function (pair) {
+        deps.run("ln", ["-sf", pair[1], "/usr/local/bin/" + pair[0]], {});
+      });
+    }
+    setStage(home, claimed, "installed", { version: version }, deps);
+
+    // A fresh install (no fleet set up, not an upgrade): the next step is the setup wizard.
+    var kind = serviceKind(deps);
+    var configured = fs.existsSync(path.join(home, "fleet.yaml")) || fs.existsSync(path.join(home, "fleet.pid"));
+    if (!configured && !upgrade && !kind) { log("  Next: run `agend quickstart` to set up AgEnD."); return 0; }
+    // The service stays under the manager it has (`agend restart` picks the same one: system unit, else user unit or
+    // launchd job): the new release's `agend install --no-activate` refreshes that definition without starting anything
+    // (a legacy system unit is refreshed in place — never a second, user unit), then the fleet moves onto the new release:
+    // restarted when it runs, started when its service is installed but stopped (the user's: the session that ran it
+    // ended). A hand-started fleet gets no unit (#1631) and is restarted only by an upgrade.
+    if (kind) {
+      var service = deps.run(bin, ["install", "--no-activate"], { inherit: true });
+      if (service.status !== 0) return fail("starting", "`agend install --no-activate` could not refresh the " + kind + " service (exit " + service.status + "); AgEnD v" + version + " is installed — run `agend install --no-activate`, then `agend restart`");
+    }
+    var env = Object.assign({}, deps.env, { AGEND_RESTART_ORIGIN: upgrade ? "agend-update" : "agend-install" });
+    if (fleetRunning(home, deps) && (kind || upgrade)) {
+      var restarted = deps.run(bin, ["restart", "--yes"], { inherit: true, env: env });
+      if (restarted.status !== 0 && restarted.status !== 75) return fail("stopping", "the fleet did not restart onto v" + version + " (exit " + restarted.status + "); run `agend restart`");
+    } else if (kind) {
+      var started = deps.run(bin, ["start"], { inherit: true, env: env });
+      if (started.status !== 0) return fail("starting", "the " + kind + " service did not start (exit " + started.status + "); AgEnD v" + version + " is installed — run `agend start`");
+    }
+    return 0;
+  } finally {
+    admitted.release();
+  }
+}
+
+module.exports = { main: main, repair: repair, admit: admit, openedBy: openedBy, setStage: setStage, claimMarker: claimMarker, npmIdleFromProcessList: npmIdleFromProcessList, npmCommands: npmCommands, LOCK: LOCK };
+if (require.main === module) process.exit(main(process.argv.slice(2)));

package/launcher/install-admission.cjs

@@ -1,12 +1,7 @@
 "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).
+// #1450 C1, reduced by #2264: the install lock's process readers (start time, start ticks, boot id), shared by the
+// updater's lock (src/install-lock.ts). Nothing here decides whether an install may run any more — a manual
+// `npm install -g` is never refused because of a lock (#2264: one that could not be read blocked every install).
 // Same syntax constraints as runtime-platform.cjs: this may run on an old Node.
 var fs = require("fs");
 var path = require("path");
@@ -124,37 +119,7 @@ function parse(text) {
       || (typeof r.startTicks === "string" && /^\d+$/.test(r.startTicks) && typeof r.bootId === "string" && /^[0-9a-f-]{36}$/.test(r.bootId))) ? 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, startTicks: startTicks, bootId: bootId,
+  LOCK: LOCK, TOKEN_ENV: TOKEN_ENV, globalPrefix: globalPrefix, processStart: processStart, startTicks: startTicks, bootId: bootId,
   sameStartText: sameStartText, START_TOLERANCE_MS: START_TOLERANCE_MS, exists: exists, holderState: holderState, parse: parse,
 };