@songsid/agend 2.3.5-alpha.3 → 2.3.5-alpha.5

package/launcher/launchd-session-type.cjs

@@ -0,0 +1,14 @@
+"use strict";
+/** Read only root-level plist entries; comments and environment keys never select a manager domain. */
+function sessionType(definition) {
+  if (typeof definition !== "string") return undefined;
+  var text = definition.replace(/<!--[\s\S]*?-->/g, ""), depth = 0, values = [];
+  var token = /<(\/?)(dict|array)\b[^>]*>|<key>([^<]*)<\/key>\s*<string>([^<]*)<\/string>/g, match;
+  while ((match = token.exec(text))) {
+    if (match[2]) depth += match[1] ? -1 : 1;
+    else if (depth === 1 && match[3] === "LimitLoadToSessionType") values.push(match[4]);
+  }
+  if (values.length > 1) throw Error("Ambiguous launchd session type; no domain was selected");
+  return values[0] === "Background" ? "Background" : undefined;
+}
+module.exports = { sessionType: sessionType };

package/launcher/postinstall.cjs

@@ -14,6 +14,7 @@ var crypto = require("crypto");
 var childProcess = require("child_process");
 var platform = require("./runtime-platform.cjs");
 var select = require("./runtime-select.cjs");
+var tmuxBundle = require("./tmux-bundle.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 = [
@@ -44,13 +45,36 @@ function sha256(file) {
 /** #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.";
 
+/**
+ * M-2457 §6.1: verify the bundled tmux for this host, if this release pins one, and write its receipt; refuse the
+ * install when it fails. No pin for the host (none published yet): nothing to do. Pinned but not installed
+ * (--omit=optional, a mirror without it): a warning here; AgEnD itself refuses to start without it (§8).
+ */
+function checkBundledTmux(pkg, host, log, d) {
+  var pin = tmuxBundle.pinnedTmux(pkg.manifest, host);
+  if (!pin) return;
+  var candidate = tmuxBundle.tmuxCandidate(pkg.dir, pin);
+  if (!candidate.exists) {
+    log("  ⚠ AgEnD's bundled tmux (" + pin.name + ") was not installed (--omit=optional, or a registry mirror without it); AgEnD will not start until it is.");
+    return;
+  }
+  var proved = tmuxBundle.verifyTmux(candidate, pin, d.tmuxDeps);
+  if (!proved.ok) refuse(proved.reason, "npm install -g @songsid/agend@" + pkg.manifest.version + " (if it fails again, report it: the tmux package did not pass its check here)");
+  try {
+    tmuxBundle.writeReceipt(pkg.dir, pin, proved, host);
+  } catch (e) {
+    refuse(String(e && e.message || e), "install it under a plain path");
+  }
+  log("  ✓ AgEnD's bundled tmux " + proved.tmux + " verified (sha256, -V, a private-socket start and kill)");
+}
+
 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) {
+  [select.KEY, select.RECEIPT, tmuxBundle.RECEIPT].forEach(function (name) {
     var file = path.join(pkg.dir, name);
     if (select.absent(file)) return;
     try { fs.unlinkSync(file); } catch (e) { /* checked below */ }
@@ -64,7 +88,8 @@ function main(deps) {
   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; };
+  // M-2457: the bundled tmux is proved before the install is accepted (a refusal keeps the previous version).
+  var installed = function () { checkBundledTmux(pkg, host, log, d); log(NEXT_STEP); return 0; };
   // #2264: `npm exec --package @songsid/agend@<v> -- agend-install` fetches a release only to run its installer. npm
   // hoists the bundled Node out of <pkg>/node_modules there, and nothing runs `agend` from that copy: the installer's own
   // `npm install -g` proves the bundled Node where AgEnD is installed. Refusing here (an old Node running npm, the

package/launcher/private-home.cjs

@@ -32,7 +32,7 @@ function ensurePrivateHome(dir, options) {
     if (opts.afterOpen) opts.afterOpen(); // test seam: replacement at the check/change boundary
     var info = io.fstatSync(fd), current = checkedPath(dir, io, false, message);
     if (!info.isDirectory() || info.uid !== uid || current.dev !== info.dev || current.ino !== info.ino) throw new Error(message);
-    if (info.mode & 18) { // 0022: repair affected 0775/0777 homes; existing non-writable roots keep their mode
+    if (info.mode & 63) { // 0077: an owned home is private: repair legacy 0755/0775/0777 homes to 0700
       io.fchmodSync(fd, 448);
       if ((io.fstatSync(fd).mode & 511) !== 448) throw new Error(message);
       (opts.log || function (line) { console.warn(line); })("AgEnD: tightened owned AGEND_HOME permissions to 0700.");

package/launcher/tmux-bundle.cjs

@@ -0,0 +1,247 @@
+"use strict";
+// M-2457 (docs/design/bundled-tmux.md §6.1, §8): AgEnD's bundled tmux, @songsid/agend-tmux-<os>-<cpu>, pinned exactly in
+// @songsid/agend's optionalDependencies. postinstall proves it BEFORE anything stops the running version: the files are
+// the ones the package declares (sha256, size), `tmux -V` names the pinned release, and a throwaway server on a private
+// socket starts, answers, captures and is killed. A failure refuses the install, and npm keeps the previous version.
+// Then the receipt, `.agend-tmux.json` next to the package, records what was proved.
+// Like postinstall, this runs under whatever Node runs npm: plain ES5-style CommonJS, built-ins only.
+var fs = require("fs");
+var path = require("path");
+var crypto = require("crypto");
+var childProcess = require("child_process");
+
+var RECEIPT = ".agend-tmux.json";
+var RECEIPT_KEYS = ["receipt", "pinnedVersion", "tmuxPath", "tmux", "size", "mtime", "sha256", "platform", "arch", "verifiedAt"];
+var PLAIN = /^[^"\\\u0000-\u001f]*$/;
+var SEMVER = /^\d+\.\d+\.\d+(-agend\.\d+)?$/;
+var SMOKE_TIMEOUT_MS = 10000;
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch (e) { return null; }
+}
+
+function absent(file) {
+  try { fs.lstatSync(file); return false; } catch (e) { return e && e.code === "ENOENT"; }
+}
+
+function packageName(host) {
+  return "@songsid/agend-tmux-" + host.id;
+}
+
+/** The exact pin for this host from @songsid/agend's optionalDependencies, or null (none published for it yet). */
+function pinnedTmux(manifest, host) {
+  var name = packageName(host);
+  var version = manifest && manifest.optionalDependencies && manifest.optionalDependencies[name];
+  return typeof version === "string" && SEMVER.test(version) ? { name: name, version: version } : null;
+}
+
+/** Exactly <pkgDir>/node_modules/<name>, never require.resolve (it can walk up to an ancestor's copy). */
+function tmuxCandidate(pkgDir, pin) {
+  var dir = path.join(pkgDir, "node_modules", pin.name);
+  var exists = !absent(dir);
+  return { dir: dir, exists: exists, manifest: exists ? readJson(path.join(dir, "package.json")) : null, tmux: path.join(dir, "bin", "tmux"), terminfo: path.join(dir, "share", "terminfo") };
+}
+
+function sha256(file) {
+  return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+}
+
+/**
+ * The environment the bundled tmux runs with: its own terminfo first, a UTF-8 locale, never a caller's $TMUX, and no
+ * shell startup hooks (the proof's pane runs /bin/sh directly; ENV/BASH_ENV would still make a shell read a file).
+ */
+function tmuxEnv(candidate, base) {
+  var env = {};
+  var from = base || process.env;
+  Object.keys(from).forEach(function (k) { if (k !== "TMUX" && k !== "TMUX_PANE" && k !== "ENV" && k !== "BASH_ENV") env[k] = from[k]; });
+  env.SHELL = "/bin/sh";
+  env.TERMINFO_DIRS = candidate.terminfo + (from.TERMINFO_DIRS ? ":" + from.TERMINFO_DIRS : ":/usr/share/terminfo:/lib/terminfo:/usr/lib/terminfo");
+  if (!/UTF-?8/i.test(String(from.LC_ALL || from.LC_CTYPE || from.LANG || ""))) env.LC_CTYPE = "C.UTF-8";
+  return env;
+}
+
+/** The proof's pane program: tmux execs this argv directly (more than one argument: no shell, no login shell). */
+var PANE_MARK = "agend-verify-ok";
+var PANE_ARGV = ["/bin/sh", "-c", "printf '%s\\n' " + PANE_MARK + "; exec sleep 60"];
+
+function sleepMs(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * Has process `pid` exited? true only on positive evidence: no such process (ESRCH), or a zombie (it has exited and
+ * waits for a parent that may never reap it, e.g. a container whose PID 1 is not an init). Anything else is false.
+ */
+function processGone(pid, platform) {
+  try { process.kill(pid, 0); } catch (e) { return !!e && e.code === "ESRCH"; }
+  try {
+    if ((platform || process.platform) === "linux") {
+      var stat = fs.readFileSync("/proc/" + pid + "/stat", "utf8");
+      return stat.slice(stat.lastIndexOf(")") + 2, stat.lastIndexOf(")") + 3) === "Z";
+    }
+    var ps = childProcess.spawnSync("ps", ["-o", "stat=", "-p", String(pid)], { encoding: "utf8", timeout: 2000 });
+    return ps.status === 0 && /^\s*Z/.test(String(ps.stdout));
+  } catch (e) { return false; }
+}
+
+/**
+ * Prove the bundled tmux. Returns { ok: true, tmux, sha256, size, mtime, real } or { ok: false, reason }.
+ * The private-socket proof records the server it creates (pid, socket path and identity) and accepts its end only on
+ * positive evidence: that pid gone and a clean "no server" answer on the socket. An unknown observation (a timeout, a
+ * signal, an error) fails the proof, and then nothing is unlinked: the reason names what may still be running.
+ * Seams for tests: deps.spawnSync, deps.pid, deps.socket, deps.processGone, deps.exitWaitMs.
+ */
+function verifyTmux(candidate, pin, deps) {
+  var d = deps || {};
+  var spawn = d.spawnSync || childProcess.spawnSync;
+  var gone = d.processGone || processGone;
+  var exitWaitMs = d.exitWaitMs || 5000;
+  var m = candidate.manifest;
+  if (!m || m.name !== pin.name || m.version !== pin.version) return { ok: false, reason: "the bundled tmux package is not " + pin.name + "@" + pin.version };
+  var want = m.agendTmux;
+  if (!want || typeof want.tmux !== "string" || !/^\d+\.\d+[a-z]?$/.test(want.tmux) || !/^[0-9a-f]{64}$/.test(String(want.sha256)) || !(want.size > 0)) {
+    return { ok: false, reason: "the bundled tmux package does not say which binary it holds (agendTmux)" };
+  }
+  var st;
+  try { st = fs.lstatSync(candidate.tmux); } catch (e) { st = null; }
+  if (!st || !st.isFile()) return { ok: false, reason: "the bundled tmux binary is missing or not a regular file" };
+  if (st.size !== want.size) return { ok: false, reason: "the bundled tmux binary is " + st.size + " bytes, not the " + want.size + " its package declares" };
+  var sum = sha256(candidate.tmux);
+  if (sum !== want.sha256) return { ok: false, reason: "the bundled tmux binary's sha256 is not the one its package declares" };
+  var env = tmuxEnv(candidate, d.env);
+  var run = function (args) {
+    var r = spawn(candidate.tmux, args, { encoding: "utf8", timeout: SMOKE_TIMEOUT_MS, env: env, stdio: ["ignore", "pipe", "pipe"] });
+    return { status: r.status, stdout: String(r.stdout || ""), stderr: String(r.stderr || ""), error: r.error || null, signal: r.signal || null };
+  };
+  var clean = function (r) { return !r.error && !r.signal && typeof r.status === "number"; };
+  var why = function (r) { return r.error ? String(r.error.code || r.error.message || r.error) : r.signal ? "signal " + r.signal : "exit " + r.status + (r.stderr.trim() ? ": " + r.stderr.trim().split("\n").pop() : ""); };
+  // Every call names the throwaway socket, -V included: nothing here can reach the default or AgEnD's server.
+  var sock = d.socket || "agend-verify-" + (d.pid || process.pid);
+  var v = run(["-L", sock, "-V"]);
+  if (!clean(v) || v.status !== 0) return { ok: false, reason: "the bundled tmux did not run (" + why(v) + ")" };
+  if (v.stdout.trim() !== "tmux " + want.tmux) return { ok: false, reason: "the bundled tmux says '" + v.stdout.trim() + "', not 'tmux " + want.tmux + "'" };
+
+  // A throwaway server on that socket of its own: never the default socket, never AgEnD's `agend` socket.
+  var failed = null;
+  var server = null;      // { pid, path, id } once known
+  var step = function (label, args) {
+    var r = run(args);
+    if (!clean(r) || r.status !== 0) failed = label + " failed (" + why(r) + ")";
+    return r;
+  };
+  try {
+    step("new-session", ["-L", sock, "-f", "/dev/null", "new-session", "-d", "-s", "verify", "-x", "80", "-y", "10"].concat(PANE_ARGV));
+    if (!failed) {
+      var idr = step("display-message", ["-L", sock, "display-message", "-p", "-t", "verify", "#{pid} #{socket_path}"]);
+      var mm = failed ? null : /^(\d+) (\/.+)$/.exec(idr.stdout.trim());
+      if (!failed && (!mm || path.basename(mm[2]) !== sock)) failed = "the server did not say which process and socket it is ('" + idr.stdout.trim() + "')";
+      if (!failed) {
+        var sst = socketIdentity(mm[2]);
+        if (!sst) failed = "the server's socket " + mm[2] + " is not a socket";
+        else server = { pid: Number(mm[1]), path: mm[2], id: sst };
+      }
+    }
+    if (!failed) step("has-session", ["-L", sock, "has-session", "-t", "verify"]);
+    if (!failed) {
+      // The pane program ran: its mark is on the screen (it may take a moment to paint).
+      var seen = false;
+      for (var k = 0; k < 20 && !failed && !seen; k++) {
+        var cap = step("capture-pane", ["-L", sock, "capture-pane", "-p", "-t", "verify"]);
+        seen = !failed && cap.stdout.indexOf(PANE_MARK) >= 0;
+        if (!seen && !failed) sleepMs(100);
+      }
+      if (!failed && !seen) failed = "capture-pane never showed the pane program's output";
+    }
+    if (!failed) step("kill-server", ["-L", sock, "kill-server"]);
+    if (!failed) {
+      // Gone, positively: the recorded pid has exited, and the socket answers a clean "no server".
+      var deadline = Date.now() + exitWaitMs;
+      while (!gone(server.pid) && Date.now() < deadline) sleepMs(50);
+      if (!gone(server.pid)) failed = "its server (pid " + server.pid + ") was still running after kill-server";
+      else {
+        var after = run(["-L", sock, "has-session"]);
+        if (!clean(after)) failed = "whether its server ended could not be confirmed (has-session: " + why(after) + ")";
+        else if (after.status === 0) failed = "its server was still answering after kill-server";
+        // Only tmux's own "no server" answer (exit 1) is proof; any other code is an unknown observation.
+        else if (after.status !== 1) failed = "whether its server ended could not be confirmed (has-session: " + why(after) + ")";
+      }
+    }
+  } finally {
+    // Cleanup that needs no proof: ask the server to go. Unlinking needs the proof above.
+    if (failed) run(["-L", sock, "kill-server"]);
+  }
+  if (failed) {
+    var left = server ? " (server pid " + server.pid + ", socket " + server.path + " left in place)" : " (socket -L " + sock + ")";
+    return { ok: false, reason: "the bundled tmux's private-socket check failed: " + failed + left };
+  }
+  // Reached only with the server's exit proved above.
+  removeStaleSocket(server);
+  var real = fs.realpathSync(candidate.tmux);
+  var fin = fs.statSync(real);
+  return { ok: true, tmux: want.tmux, sha256: sum, size: fin.size, mtime: Math.floor(fin.mtimeMs / 1000), real: real };
+}
+
+/**
+ * Remove the socket file tmux leaves behind after kill-server — only the one this proof created and saw exit: the same
+ * path, still a socket, the same identity (inode and change time). Anything else stays where it is.
+ */
+function removeStaleSocket(server) {
+  try {
+    if (socketIdentity(server.path) !== server.id) return;
+    fs.unlinkSync(server.path);
+  } catch (e) { /* already gone */ }
+}
+
+/**
+ * A socket file's identity: its inode and its change time to the nanosecond (an inode number alone can be reused at
+ * once by a file created where a removed one was). null when it is not a socket.
+ */
+function socketIdentity(file) {
+  try {
+    var st = fs.lstatSync(file, { bigint: true });
+    return st.isSocket() ? st.ino + ":" + st.ctimeNs : null;
+  } catch (e) { return null; }
+}
+
+function receiptText(r) {
+  var o = {};
+  RECEIPT_KEYS.forEach(function (k) { o[k] = r[k]; });
+  return JSON.stringify(o, null, 2) + "\n";
+}
+
+function receiptShapeOk(r) {
+  return !!r && r.receipt === 1 && typeof r.pinnedVersion === "string" && SEMVER.test(r.pinnedVersion)
+    && typeof r.tmuxPath === "string" && PLAIN.test(r.tmuxPath) && path.isAbsolute(r.tmuxPath)
+    && typeof r.tmux === "string" && /^\d+\.\d+[a-z]?$/.test(r.tmux)
+    && typeof r.sha256 === "string" && /^[0-9a-f]{64}$/.test(r.sha256)
+    && Number.isInteger(r.size) && r.size > 0 && Number.isInteger(r.mtime);
+}
+
+/** Write the receipt atomically next to the package (same rename-into-place as the runtime receipt). */
+function writeReceipt(pkgDir, pin, proved, host) {
+  if (!PLAIN.test(proved.real)) throw new Error("AgEnD's install path " + JSON.stringify(proved.real) + " contains a quote, backslash or control character");
+  var receipt = { receipt: 1, pinnedVersion: pin.version, tmuxPath: proved.real, tmux: proved.tmux, size: proved.size, mtime: proved.mtime, sha256: proved.sha256, platform: host.platform, arch: host.arch, verifiedAt: new Date().toISOString() };
+  var file = path.join(pkgDir, RECEIPT);
+  var tmp = file + "." + process.pid + ".tmp";
+  fs.writeFileSync(tmp, receiptText(receipt));
+  fs.renameSync(tmp, file);
+  return receipt;
+}
+
+/**
+ * The receipt, if it still describes the file on disk (size and mtime; the sha256 once per start is the caller's,
+ * PR B). null otherwise: a missing, malformed or stale receipt is never trusted.
+ */
+function readReceipt(pkgDir, pin) {
+  var r = readJson(path.join(pkgDir, RECEIPT));
+  if (!receiptShapeOk(r) || (pin && r.pinnedVersion !== pin.version)) return null;
+  var st;
+  try { st = fs.statSync(r.tmuxPath); } catch (e) { return null; }
+  return st.isFile() && st.size === r.size && Math.floor(st.mtimeMs / 1000) === r.mtime ? r : null;
+}
+
+module.exports = {
+  RECEIPT: RECEIPT, RECEIPT_KEYS: RECEIPT_KEYS, SEMVER: SEMVER,
+  packageName: packageName, pinnedTmux: pinnedTmux, tmuxCandidate: tmuxCandidate, tmuxEnv: tmuxEnv,
+  verifyTmux: verifyTmux, processGone: processGone, PANE_ARGV: PANE_ARGV, writeReceipt: writeReceipt, readReceipt: readReceipt, receiptShapeOk: receiptShapeOk, receiptText: receiptText,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@songsid/agend",
-  "version": "2.3.5-alpha.3",
+  "version": "2.3.5-alpha.5",
   "description": "Multi-agent fleet daemon — run coding CLIs (Claude, Muse, Codex, OpenCode) from Discord or Telegram",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
   },
   "scripts": {
     "build": "tsc",
-    "postbuild": "node scripts/build-runtime-assets.mjs && node scripts/generate-tips-html.mjs && cp -r src/plugin dist/ && cp -r src/workflow-templates dist/ && cp src/agent-cli-instructions.md dist/ && cp -r src/ui dist/ && cp -r src/general-knowledge dist/ && chmod +x dist/cli.js && cd dist/plugin/agend && ln -sf ../../channel/mcp-server.js server.js",
+    "postbuild": "node scripts/write-build-provenance.mjs && node scripts/build-runtime-assets.mjs && node scripts/generate-tips-html.mjs && cp -r src/plugin dist/ && cp -r src/workflow-templates dist/ && cp src/agent-cli-instructions.md dist/ && cp -r src/ui dist/ && cp -r src/general-knowledge dist/ && chmod +x dist/cli.js && cd dist/plugin/agend && ln -sf ../../channel/mcp-server.js server.js",
     "start": "tsx src/cli.ts start",
     "dev": "tsx src/cli.ts",
     "test": "vitest run",
@@ -70,6 +70,7 @@
     "ejs": "^5.0.1",
     "grammy": "^1.44.0",
     "js-yaml": "^4.3.2",
+    "ldapts": "9.2.0",
     "libavoid-js": "0.4.5",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",

package/templates/launchd.plist.ejs

@@ -25,7 +25,9 @@
     <true/>
     <key>KeepAlive</key>
     <true/>
-    <key>StandardOutPath</key>
+<% if (launchdSessionType) { %>    <key>LimitLoadToSessionType</key>
+    <string><%= launchdSessionType %></string>
+<% } %>    <key>StandardOutPath</key>
     <string><%= logPath %></string>
     <key>StandardErrorPath</key>
     <string><%= logPath %></string>

package/templates/runtime-install/install.ps1

@@ -0,0 +1,270 @@
+# AgEnD Runtime for Windows: installs the runner that lets this PC work for an AgEnD fleet.
+#
+# Do not type this file's address by hand. The AgEnD page (Settings -> Runtime -> Connect a computer) shows the command to
+# copy, with your fleet's address and THIS file's SHA-256 filled in. The command downloads this file, checks the hash shown on
+# the page and only then runs it, so what runs is exactly what the page vouches for, whatever the TLS trust decision was.
+# The server address is the one the command put in $agend (the reviewed address, never the Host that happened to serve this
+# file); nothing here is looked up from the network, and nothing here is a secret. This file is the same bytes for everyone
+# and for every request.
+#
+# It is run by the page's command (`iex` of the downloaded text), so it is kept safe for that: ASCII only (Windows
+# PowerShell 5.1 may decode a download as the wrong code page), no param block, and no `exit` (under iex it would close the
+# window). Windows PowerShell 5.1 and PowerShell 7 both run it. It needs no administrator rights and never changes your
+# execution policy. Under Constrained Language Mode or AppLocker the page's command stops before this script is ever run (it cannot compute the hash there): use the ZIP from the same page instead.
+#
+# What it does, in order:
+#   1. Checks that Node.js 22.14 or newer is installed (it never installs software for you).
+#   2. Downloads the Runtime archive from $agend, checks its SHA-256 against the value pinned inside this script and, if it
+#      does not match, stops before anything is unpacked.
+#   3. Unpacks it into %LOCALAPPDATA%\agend-runtime\<version>+<build>, NEXT TO any version already there (the folder names the build,
+#      the first 8 characters of the archive's SHA-256, because one version number can cover more than one build). An existing folder
+#      is never deleted or replaced: it may be the Runtime that is running right now.
+#   4. Points agend-runtime at the new version: bin\agend-runtime.cmd never changes, and bin\current.txt (the version it
+#      starts) is swapped in with an atomic file replace. A Runtime that is already running keeps running its own version.
+#   5. Adds the bin folder to YOUR user PATH (not the system PATH).
+#   6. Prints the command that connects this PC. It does NOT connect and does NOT pair: pairing still needs the one-time
+#      code from AgEnD Settings, which you type in the terminal, and your approval in AgEnD.
+#
+# Optional, set in the same PowerShell window before running it:
+#   $env:AGEND_RUNTIME_NO_PATH = '1'              leave PATH alone (the final message then shows the full path to run)
+#   $env:AGEND_RUNTIME_INSTALL_DIR = 'D:\agend'   install somewhere other than %LOCALAPPDATA%\agend-runtime
+# If it fails it says why, leaves what was installed before untouched, and sets $LASTEXITCODE to 1.
+& {
+    $ErrorActionPreference = 'Stop'
+
+    # Pinned by the AgEnD server that serves this file: the version and the SHA-256 of the one archive it serves.
+    $pinnedVersion = '@@AGEND_RUNTIME_VERSION@@'
+    $pinnedSha256 = '@@AGEND_RUNTIME_SHA256@@'
+    $maxArchiveBytes = 16MB
+
+    function Write-Step([string]$text) { Write-Host ('AgEnD Runtime: ' + $text) }
+    function Write-Problem([string]$text) { Write-Host ('AgEnD Runtime: ' + $text) -ForegroundColor Red }
+
+    # Only an origin: https, or http for this computer itself (an SSH-forwarded port). No path, credentials, query or fragment.
+    function Resolve-AgendOrigin($value) {
+        if (-not ($value -is [string]) -or $value.Length -eq 0 -or $value.Length -gt 2048 -or $value -match '[\s\x00-\x1f\x7f]') { return '' }
+        $uri = $null
+        if (-not [Uri]::TryCreate($value, [UriKind]::Absolute, [ref]$uri)) { return '' }
+        $local = $uri.Host -in 'localhost', '127.0.0.1', '[::1]', '::1'
+        if (-not ($uri.Scheme -eq 'https' -or ($uri.Scheme -eq 'http' -and $local))) { return '' }
+        if ($uri.UserInfo -ne '' -or $uri.Query -ne '' -or $uri.Fragment -ne '' -or $uri.AbsolutePath -ne '/') { return '' }
+        return $uri.GetLeftPart([UriPartial]::Authority)
+    }
+    # Node.js satisfying the Runtime's engines: ^22.14.0 || ^23.6.0 || >=24.
+    function Test-NodeVersion([string]$text) {
+        $m = [regex]::Match($text, '\Av?(\d+)\.(\d+)\.(\d+)')
+        if (-not $m.Success) { return $false }
+        $major = [int]$m.Groups[1].Value; $minor = [int]$m.Groups[2].Value
+        return ($major -ge 24) -or ($major -eq 23 -and $minor -ge 6) -or ($major -eq 22 -and $minor -ge 14)
+    }
+    # One bounded download: no redirect is followed, and neither the wait nor the size can run on.
+    function Save-AgendArchive([string]$Uri, [string]$OutFile, [long]$MaxBytes) {
+        $request = [Net.HttpWebRequest]::Create($Uri)
+        $request.AllowAutoRedirect = $false; $request.Timeout = 120000; $request.ReadWriteTimeout = 60000; $request.UserAgent = 'agend-runtime-install'
+        $response = $null; $bodyStream = $null; $output = $null; $done = $false
+        try {
+            $response = $request.GetResponse()
+            if ([int]$response.StatusCode -ne 200) { throw ('The AgEnD server answered ' + [int]$response.StatusCode + ' for the Runtime archive.') }
+            if ($response.ContentLength -gt $MaxBytes) { throw 'The Runtime archive is larger than expected; refusing to download it.' }
+            $bodyStream = $response.GetResponseStream()
+            $output = [IO.File]::Open($OutFile, [IO.FileMode]::Create, [IO.FileAccess]::Write, [IO.FileShare]::None)
+            $buffer = New-Object byte[] 65536; $total = 0
+            while (($count = $bodyStream.Read($buffer, 0, $buffer.Length)) -gt 0) {
+                $total += $count
+                if ($total -gt $MaxBytes) { throw 'The Runtime archive is larger than expected; stopped downloading it.' }
+                $output.Write($buffer, 0, $count)
+            }
+            $done = $true
+        } finally {
+            if ($output) { $output.Dispose() }; if ($bodyStream) { $bodyStream.Dispose() }; if ($response) { $response.Close() }
+            if (-not $done) { Remove-Item -LiteralPath $OutFile -Force -ErrorAction SilentlyContinue }
+        }
+    }
+    # .NET directly, not Get-FileHash: a PowerShell started from another one can inherit a module path that hides that cmdlet.
+    function Get-AgendSha256([string]$Path) {
+        $stream = [IO.File]::OpenRead($Path)
+        try {
+            $sha = [Security.Cryptography.SHA256]::Create()
+            try { return ([BitConverter]::ToString($sha.ComputeHash($stream)) -replace '-', '').ToLowerInvariant() } finally { $sha.Dispose() }
+        } finally { $stream.Dispose() }
+    }
+    # Writes a small file by writing a sibling and swapping it in, so a reader (a shim that is starting right now) sees the old or the
+    # new content, never half of it. Nothing happens when the file already says this.
+    function Set-AgendFile([string]$Path, [string]$Text) {
+        if ((Test-Path -LiteralPath $Path) -and ([IO.File]::ReadAllText($Path) -ceq $Text)) { return }
+        $new = $Path + '.new'
+        [IO.File]::WriteAllText($new, $Text, [Text.Encoding]::ASCII)
+        try {
+            # [NullString]::Value, not $null: PowerShell turns $null into an empty string for a string parameter, and Replace refuses that.
+            if (Test-Path -LiteralPath $Path) { [IO.File]::Replace($new, $Path, [NullString]::Value) } else { [IO.File]::Move($new, $Path) }
+        } catch {
+            Remove-Item -LiteralPath $new -Force -ErrorAction SilentlyContinue
+            throw ('Could not update ' + $Path + ' (' + $_.Exception.Message + '). Close any agend-runtime window that is starting, then run the install command again.')
+        }
+    }
+    # Adds a folder to the USER PATH in the registry, keeping its value kind: [Environment]::SetEnvironmentVariable would turn a
+    # REG_EXPAND_SZ PATH into plain REG_SZ and stop its %VARIABLES% entries expanding, and setx truncates at 1024 characters, so
+    # neither is used. An entry already there (written out or with %VARIABLES%) is not added again.
+    function Add-UserPathEntry([string]$Folder) {
+        $key = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment', $true)
+        try {
+            $raw = [string]$key.GetValue('Path', '', [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames)
+            $kind = [Microsoft.Win32.RegistryValueKind]::ExpandString
+            if ($key.GetValueNames() -contains 'Path') { $kind = $key.GetValueKind('Path') }
+            $want = $Folder.TrimEnd('\')
+            foreach ($entry in $raw.Split(';')) {
+                $e = $entry.Trim().TrimEnd('\')
+                if ($e -ieq $want -or [Environment]::ExpandEnvironmentVariables($e).TrimEnd('\') -ieq $want) { return $false }
+            }
+            $next = $Folder
+            if ($raw.Trim().Length -gt 0) { $next = $raw.TrimEnd(';') + ';' + $Folder }
+            $key.SetValue('Path', $next, $kind)
+        } finally { $key.Close() }
+        # Tell running programs the environment changed: setting and clearing a throwaway user variable makes Windows broadcast it. The PATH is
+        # already written, so a failure here is only a warning (open terminals learn of it later), never "install failed".
+        try {
+            [Environment]::SetEnvironmentVariable('AGEND_RUNTIME_ENV_REFRESH', '1', 'User')
+            [Environment]::SetEnvironmentVariable('AGEND_RUNTIME_ENV_REFRESH', $null, 'User')
+        } catch {
+            try { [Environment]::SetEnvironmentVariable('AGEND_RUNTIME_ENV_REFRESH', $null, 'User') } catch { }
+            Write-Host ('AgEnD Runtime: warning: your PATH was updated, but running programs could not be told (' + $_.Exception.Message + '). Open a new terminal to see the change.') -ForegroundColor Yellow
+        }
+        return $true
+    }
+    # The shim never changes from one version to the next, so replacing a version cannot disturb a batch file that is running.
+    # It starts the version named in current.txt, next to it; that one small file is what an install swaps.
+    # `setlocal DisableDelayedExpansion` comes before any line that expands a path or an argument: with cmd /V:ON (or the DelayedExpansion registry setting)
+    # an unmatched `!` in the install folder, which an accepted AGEND_RUNTIME_INSTALL_DIR can hold, would otherwise be eaten out of %~dp0 and the shim would
+    # look in another folder and report an incomplete install. (Changed once for that reason: see the change notice below.)
+    # DO NOT CHANGE $shimText unless a bug in it makes installs unusable. cmd.exe reads a batch file as it runs it, a piece at a time, not all at
+    # once, so rewriting the agend-runtime.cmd of a Runtime that is running (Set-AgendFile does that whenever this text differs from what is on
+    # disk) can make that Runtime's window misbehave when it ends. The text names no version for exactly that reason. If it must change, update the
+    # pinned hash in tests/runtime-install-script.test.ts in the same commit, and say in the docs and the changelog that running Runtimes should be
+    # stopped before the install command is run again.
+    $shimText = ('@echo off', 'setlocal DisableDelayedExpansion', 'set "AGEND_RT_VERSION="', 'if not exist "%~dp0current.txt" goto :agend_rt_missing', 'set /p AGEND_RT_VERSION=<"%~dp0current.txt"', 'if not defined AGEND_RT_VERSION goto :agend_rt_missing',
+        'if not exist "%~dp0..\%AGEND_RT_VERSION%\dist\runtime-cli.js" goto :agend_rt_missing', 'node.exe "%~dp0..\%AGEND_RT_VERSION%\dist\runtime-cli.js" %*',
+        'exit /b %errorlevel%', ':agend_rt_missing', 'echo AgEnD Runtime is not installed correctly. Run the install command shown in AgEnD Settings - Runtime - Connect a computer again.>&2',
+        'exit /b 1', '') -join "`r`n"
+
+    $tmp = $null
+    try {
+        try { [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor 3072 } catch { }
+
+        $origin = Resolve-AgendOrigin $agend
+        if ($origin -eq '') {
+            Write-Problem 'This installer needs $agend set to your AgEnD address (https, or http only for this computer).'
+            Write-Host 'Do not run this file by hand: copy the install command from AgEnD (Settings -> Runtime -> Connect a computer -> Windows (PowerShell)).'
+            Write-Host 'It sets $agend to your address and checks this installer''s SHA-256 against the one the page shows before it runs anything.'
+            $global:LASTEXITCODE = 1
+            return
+        }
+
+        $nodeText = ''
+        $node = Get-Command node -ErrorAction SilentlyContinue
+        if ($node) { try { $nodeText = ((& $node.Source -v) | Out-String).Trim() } catch { $nodeText = '' } }
+        if (-not (Test-NodeVersion $nodeText)) {
+            if ($nodeText) { Write-Problem ('Node.js ' + $nodeText + ' is too old. The AgEnD Runtime needs Node.js 22.14 or newer (22.14+, 23.6+ or 24+).') }
+            else { Write-Problem 'Node.js was not found. The AgEnD Runtime needs Node.js 22.14 or newer (22.14+, 23.6+ or 24+).' }
+            Write-Host 'This installer does not install software for you. Install Node.js yourself, open a new PowerShell window, set $agend and run the command again:'
+            Write-Host '  winget install OpenJS.NodeJS.LTS'
+            Write-Host 'or download it from https://nodejs.org/'
+            $global:LASTEXITCODE = 1
+            return
+        }
+
+        $root = [string]$env:AGEND_RUNTIME_INSTALL_DIR
+        if ($root -ne '') {
+            # A folder you chose: it must be a full path on a drive, never a relative, UNC or control-character path.
+            if ($root -notmatch '\A[A-Za-z]:[\\/]' -or $root -match '[\x00-\x1f\x7f]') { throw 'AGEND_RUNTIME_INSTALL_DIR must be a full path on a drive, for example D:\agend.' }
+        } else {
+            if (-not $env:LOCALAPPDATA) { throw 'LOCALAPPDATA is not set; set AGEND_RUNTIME_INSTALL_DIR to a folder for the Runtime.' }
+            $root = Join-Path $env:LOCALAPPDATA 'agend-runtime'
+        }
+        $root = [IO.Path]::GetFullPath($root).TrimEnd('\')
+        # The folder names the build as well as the version: one version number often covers more than one build, and a different build must land
+        # beside the old one, not on it. The same build finds its own folder again and only repoints agend-runtime.
+        $folder = $pinnedVersion + '+' + $pinnedSha256.Substring(0, 8)
+        $target = Join-Path $root $folder
+        $bin = Join-Path $root 'bin'
+        $marker = Join-Path $target '.agend-install-sha256'
+        $createdRoot = -not (Test-Path -LiteralPath $root)
+        $null = New-Item -ItemType Directory -Path $root -Force
+
+        # An existing folder is never deleted or replaced: it may be the Runtime that is running right now. A folder with this build's own name that does
+        # not hold this build can only be one that was changed by hand or left incomplete, and is left alone too.
+        $installed = $false
+        if (Test-Path -LiteralPath $target) {
+            $existing = ''
+            if (Test-Path -LiteralPath $marker) { $existing = ([IO.File]::ReadAllText($marker)).Trim() }
+            if ($existing -eq $pinnedSha256 -and (Test-Path -LiteralPath (Join-Path $target 'dist\runtime-cli.js'))) { $installed = $true }
+            else { throw ('The folder ' + $target + ' exists but does not hold this build (it was changed or is incomplete). It was left untouched because it may be running. Close any agend-runtime window, move that folder away yourself, and run the install command again.') }
+        }
+        if ($installed) {
+            Write-Step ('version ' + $pinnedVersion + ' (build ' + $pinnedSha256.Substring(0, 8) + ') is already installed in ' + $target + '.')
+        } else {
+            $tmp = Join-Path $root ('.install-' + [Guid]::NewGuid().ToString('N'))
+            $null = New-Item -ItemType Directory -Path $tmp
+            $archive = Join-Path $tmp 'runtime.zip'
+            Write-Step ('downloading version ' + $pinnedVersion + ' (build ' + $pinnedSha256.Substring(0, 8) + ') from ' + $origin)
+            Save-AgendArchive ($origin + '/runtime/v1/bundle/windows.zip') $archive $maxArchiveBytes
+            $actual = Get-AgendSha256 $archive
+            if ($actual -ne $pinnedSha256) {
+                throw ('The downloaded Runtime does not match the checksum pinned in this installer, so nothing was unpacked. Expected ' + $pinnedSha256 + ' but received ' + $actual + '. If AgEnD was just updated, reload the AgEnD page and copy the install command again.')
+            }
+            Write-Step 'checksum verified; unpacking.'
+            Add-Type -AssemblyName System.IO.Compression.FileSystem
+            $stage = Join-Path $tmp 'unpacked'
+            [IO.Compression.ZipFile]::ExtractToDirectory($archive, $stage)
+            $unpacked = Join-Path $stage 'agend-runtime'
+            if (-not (Test-Path -LiteralPath (Join-Path $unpacked 'dist\runtime-cli.js')) -or -not (Test-Path -LiteralPath (Join-Path $unpacked 'bundle-manifest.json'))) {
+                throw 'The Runtime archive does not contain the expected files, so nothing was installed.'
+            }
+            [IO.File]::WriteAllText((Join-Path $unpacked '.agend-install-sha256'), $pinnedSha256)
+            # A rename inside the install folder: the version folder appears whole or not at all, beside the versions already there.
+            Move-Item -LiteralPath $unpacked -Destination $target
+            Write-Step ('installed version ' + $pinnedVersion + ' (build ' + $pinnedSha256.Substring(0, 8) + ') in ' + $target + '.')
+        }
+
+        # Repoint agend-runtime. The shim file is written once and then left alone; current.txt is the atomic switch.
+        $null = New-Item -ItemType Directory -Path $bin -Force
+        $shim = Join-Path $bin 'agend-runtime.cmd'
+        $current = Join-Path $bin 'current.txt'
+        $was = ''
+        if (Test-Path -LiteralPath $current) { $was = ([IO.File]::ReadAllText($current)).Trim() }
+        Set-AgendFile $shim $shimText
+        Set-AgendFile $current $folder
+        if ($was -ne '' -and $was -ne $folder) {
+            Write-Step ('agend-runtime now starts ' + $folder + ' (it was ' + $was + '). A Runtime that is already running keeps its own version until you stop it with Ctrl+C and start it again with agend-runtime run.')
+        }
+        $others = @(Get-ChildItem -LiteralPath $root -Directory -ErrorAction SilentlyContinue | Where-Object { $_.Name -ne $folder -and $_.Name -match '\A\d+\.\d+\.\d+([-+][A-Za-z0-9.+-]+)?\z' } | ForEach-Object { $_.Name })
+        # Earlier folders are not removed here: one of them may be running. Cleaning them up comes with the update and uninstall commands (phase 2).
+        if ($others.Count -gt 0) { Write-Step ('earlier versions are kept where they are (' + ($others -join ', ') + '). This installer never removes a version; clearing old ones comes later, with the update and uninstall commands.') }
+
+        $onPath = $false
+        if ([string]$env:AGEND_RUNTIME_NO_PATH -eq '1') {
+            Write-Step 'AGEND_RUNTIME_NO_PATH is set; your PATH was not changed.'
+        } else {
+            if (Add-UserPathEntry $bin) { Write-Step ('added ' + $bin + ' to your user PATH.') } else { Write-Step ($bin + ' is already on your user PATH.') }
+            $sessionHas = $false
+            foreach ($entry in ([string]$env:Path).Split(';')) { if ($entry.Trim().TrimEnd('\') -ieq $bin) { $sessionHas = $true } }
+            if (-not $sessionHas) { $env:Path = ([string]$env:Path).TrimEnd(';') + ';' + $bin }
+            $onPath = $true
+        }
+
+        Write-Host ''
+        Write-Host 'AgEnD Runtime is installed. This computer is not connected yet and nothing has been paired.'
+        Write-Host 'Next, connect it. Open Settings -> Runtime -> Connect a computer in AgEnD for the one-time pairing code, then run:'
+        Write-Host ''
+        if ($onPath) { Write-Host ('  agend-runtime connect --server "' + $origin + '"') }
+        else { Write-Host ('  & "' + $shim + '" connect --server "' + $origin + '"') }
+        Write-Host ''
+        Write-Host 'Type the pairing code when asked, compare the fingerprint with the one AgEnD shows, then approve this computer in AgEnD.'
+    } catch {
+        Write-Problem ('install failed: ' + $_.Exception.Message)
+        $global:LASTEXITCODE = 1
+    } finally {
+        if ($tmp -and (Test-Path -LiteralPath $tmp)) { Remove-Item -LiteralPath $tmp -Recurse -Force -ErrorAction SilentlyContinue }
+        # A run that installed nothing leaves nothing: the install folder this run created is removed again, but only while it is still empty.
+        if ($createdRoot -and $root -and (Test-Path -LiteralPath $root) -and -not (Get-ChildItem -LiteralPath $root -Force | Select-Object -First 1)) { Remove-Item -LiteralPath $root -Force -ErrorAction SilentlyContinue }
+    }
+}