@join-pantheon/cli 0.31.2-rc.1 → 0.32.0-rc.1

package/dist/relay.js

@@ -6,6 +6,8 @@ import { join } from "node:path";
 import { WebSocketServer } from "ws";
 import { badRemote, Inbound, isContinuationFor, LIMITS, newId, PROTOCOL_VERSION, RELAY_FEATURES, SENDABLE, shouldDeferToHuman, } from "./protocol.js";
 import { VERSION } from "./version.js";
+import { installerScript, InstallerGate } from "./installer.js";
+import { installerLine } from "./managed.js";
 import { Ledger, SpaceFull } from "./ledger.js";
 import { fingerprint, newNonce, verifyChallenge, verifyActivity, verifyAccount, verifyRead, actPayload, goalPayload, verifyBytes, verifyDelegate, canonicalJson } from "./identity.js";
 import { Accounts, normalizeUsername, validEmail, validUsername } from "./accounts.js";
@@ -434,6 +436,7 @@ export class Relay {
     authEpoch = 0;
     rotateOnRemove;
     backupTimer;
+    installerGate;
     get features() { return this.opts.features ?? RELAY_FEATURES; }
     constructor(opts = {}) {
         this.opts = opts;
@@ -471,6 +474,7 @@ export class Relay {
             spaceMinAgeMs: opts.spaceLimits?.spaceMinAgeMs ?? LIMITS.spaceMinAgeMs,
         };
         this.rotateOnRemove = opts.rotateOnRemove ?? process.env.PANTHEON_ROTATE_ON_REMOVE === "1";
+        this.installerGate = opts.installerGate ?? new InstallerGate({ log: this.log });
         this.busyTtlMs = opts.activityBusyTtlMs ?? LIMITS.activityBusyTtlMs;
         this.pruneMs = opts.activityPruneMs ?? LIMITS.activityPruneMs;
         const readsEnv = (process.env.PANTHEON_READS ?? "").trim().toLowerCase();
@@ -510,6 +514,7 @@ export class Relay {
         }
         if (this.backupTimer)
             clearInterval(this.backupTimer);
+        this.installerGate.close();
         if (this.accounts && !this.opts.accounts)
             this.accounts.close();
         if (this.heartbeat)
@@ -596,6 +601,12 @@ export class Relay {
                         : {}),
             });
         }
+        if (url.pathname === "/install.sh" || url.pathname === "/install.ps1") {
+            if (req.method !== "GET" && req.method !== "HEAD")
+                return this.json(res, 405, { error: "GET only" });
+            void this.serveInstaller(req, res, url.pathname.slice(1));
+            return;
+        }
         if (url.pathname === "/join") {
             if (!this.authRateOk(ip))
                 return this.json(res, 429, { error: "too many lookups from your network — wait a minute" });
@@ -730,7 +741,7 @@ export class Relay {
     }
     onAuthHttp(req, res, url, ip) {
         if (url.pathname === "/")
-            return this.landingPage(res);
+            return this.landingPage(req, res);
         if (url.pathname === "/admin" || url.pathname === "/admin/space" || url.pathname === "/admin/export" || url.pathname === "/admin/backup" || url.pathname === "/admin/action" || url.pathname === "/admin/login" || url.pathname === "/admin/logout" || url.pathname === "/admin/report") {
             const A0 = this.accounts;
             if (!A0 || !this.adminToken)
@@ -2318,16 +2329,66 @@ ${url.searchParams.get("done") ? `<div class=done role=status>${esc(url.searchPa
         }
         catch { } });
     }
-    landingPage(res) {
+    landingPage(req, res) {
+        const host = String(req.headers.host ?? "").replace(/[^A-Za-z0-9.:\[\]-]/g, "");
+        const proto = String(req.headers["x-forwarded-proto"] ?? "").split(",")[0].trim() === "https" ? "https" : "http";
+        const base = host ? `${proto}://${host}` : null;
+        const sh = installerLine(base, "sh", ["start"]), win = installerLine(base, "windows", ["start"]);
+        const esc = (t) => t.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
         res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
         res.end(`<!doctype html><meta charset=utf-8><title>pantheon</title>
-<style>body{font:16px/1.5 system-ui,sans-serif;max-width:34rem;margin:12vh auto;padding:0 1.2rem;color:#222}code{background:#f4f4f5;padding:2px 6px;border-radius:5px}h1{font-size:1.6rem}</style>
+<style>body{font:16px/1.5 system-ui,sans-serif;max-width:40rem;margin:12vh auto;padding:0 1.2rem;color:#222}code,pre{background:#f4f4f5;border-radius:5px}code{padding:2px 6px}pre{padding:.6rem .8rem;overflow-x:auto}h1{font-size:1.6rem}</style>
 <h1>pantheon</h1>
 <p>Your coding agent and your teammates' agents, coordinating across machines.</p>
-<p>This is a relay endpoint, not a website. To join, install the CLI and sign up:</p>
+${sh && win ? `<p>This is a relay endpoint, not a website. To start a team, paste one line into a terminal on your own computer. It brings its own Node, needs no admin rights, and asks for your email and a 6-digit code.</p>
+<p>Mac or Linux (Terminal):</p>
+<pre><code>${esc(sh)}</code></pre>
+<p>Windows (Command Prompt or PowerShell):</p>
+<pre><code>${esc(win)}</code></pre>
+<p>Invited to a team? Use the line in your invite instead. Already have Node.js 22.13 or newer: <code>npm install -g @join-pantheon/cli</code>, then <code>pantheon start</code>.</p>` : `<p>This is a relay endpoint, not a website. With Node.js 22.13 or newer, install the CLI and start a team:</p>
 <pre><code>npm install -g @join-pantheon/cli
-pantheon signup --email you@work.com --username you</code></pre>
-<p>You'll get a 6-digit code by email, then <code>pantheon verify &lt;code&gt;</code>.</p>`);
+pantheon start</code></pre>
+<p>It asks for your email and sends you a 6-digit code. Invited to a team? Use the line in your invite.</p>`}`);
+    }
+    startInstallerCheck() { this.installerGate.start(); }
+    async serveInstaller(req, res, name) {
+        const plain = (code, body, extra = {}) => {
+            res.writeHead(code, {
+                "content-type": "text/plain; charset=utf-8",
+                "content-length": Buffer.byteLength(body),
+                "cache-control": "no-store",
+                "x-content-type-options": "nosniff",
+                ...extra,
+            });
+            res.end(req.method === "HEAD" ? undefined : body);
+        };
+        try {
+            const choice = await this.installerGate.choose();
+            if (res.writableEnded || res.destroyed)
+                return;
+            if ("unavailable" in choice) {
+                const sentence = `pantheon install failed: ${choice.unavailable}`.replace(/'/g, "");
+                return plain(200, name === "install.sh"
+                    ? `#!/bin/sh\nprintf '%s\\n' '${sentence}' >&2\nexit 1\n`
+                    : `Write-Host '${sentence}' -ForegroundColor Red\nthrow 'Pantheon was not installed.'\n`, { "retry-after": "120", "x-pantheon-installer": "unavailable" });
+            }
+            const body = installerScript(name, undefined, choice.version);
+            if (body === null) {
+                const sentence = "pantheon install failed: this relay cannot serve the installer (its installer files or version are missing). Install with npm instead: npm install -g @join-pantheon/cli";
+                return plain(200, name === "install.sh" ? `#!/bin/sh\nprintf '%s\\n' '${sentence}' >&2\nexit 1\n` : `Write-Host '${sentence}' -ForegroundColor Red\nthrow 'Pantheon was not installed.'\n`, { "x-pantheon-installer": "unavailable" });
+            }
+            plain(200, body, { "x-pantheon-installs": choice.version });
+        }
+        catch (e) {
+            this.log(`! ${name} failed: ${e?.message ?? e}`);
+            try {
+                if (!res.headersSent)
+                    this.json(res, 500, { error: "the relay could not handle that request" });
+                else
+                    res.end();
+            }
+            catch { }
+        }
     }
     json(res, code, body) {
         const s = JSON.stringify(body);

package/dist/service.js

@@ -2,9 +2,10 @@ import { writeFileSync, mkdirSync, existsSync, unlinkSync, readFileSync } from "
 import { execFileSync } from "node:child_process";
 import { homedir, platform, userInfo } from "node:os";
 import { which } from "./which.js";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, posix, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { launcher } from "./install.js";
+import { childNodeFlags, managedLauncher, managedLayout } from "./managed.js";
 import { CONFIG_DIR } from "./config.js";
 const HERE = dirname(fileURLToPath(import.meta.url));
 const LABEL = (kind) => `dev.pantheon.${kind}`;
@@ -45,8 +46,10 @@ export const serviceLogFile = (kind) => join(serviceLogDir(), `${kind}.log`);
 const SERVICE_BASE_PATH = [
     "/usr/local/bin", "/opt/homebrew/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin",
 ];
-export function servicePath(envPath = process.env.PATH ?? "") {
-    return [...new Set([...envPath.split(":"), ...SERVICE_BASE_PATH].filter(Boolean))].join(":");
+export function servicePath(envPath = process.env.PATH ?? "", managed = managedLayout()) {
+    const first = managed ? [managed.binDir] : [];
+    const last = managed ? [posix.dirname(managed.node)] : [];
+    return [...new Set([...first, ...envPath.split(":"), ...SERVICE_BASE_PATH, ...last].filter(Boolean))].join(":");
 }
 export function servicesUnavailable(plat = platform()) {
     if (plat !== "win32")
@@ -99,14 +102,19 @@ export function existingUnitPath(kind, env = systemdUserEnv(), shellEnv = proces
 function xml(s) {
     return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
-function argvFor(kind, args) {
+function argvFor(kind, args, managed = managedLauncher()) {
+    if (managed)
+        return [managed, kind, ...args];
     const l = launcher();
     if (!l.portable)
         return [l.command, ...l.args.slice(0, -1), kind, ...args];
     const abs = whichPantheon();
-    return abs ? [abs, kind, ...args] : [process.execPath, resolve(HERE, "cli.js"), kind, ...args];
+    return abs ? [abs, kind, ...args] : [process.execPath, ...childNodeFlags(), resolve(HERE, "cli.js"), kind, ...args];
 }
-export function whichPantheon(find = which) {
+export const serviceArgv = (kind, args, managed) => argvFor(kind, args, managed);
+export function whichPantheon(find = which, managed = managedLauncher()) {
+    if (managed)
+        return managed;
     const p = find("pantheon");
     if (!p)
         return null;

package/dist/tray.js

@@ -1,14 +1,12 @@
 import { loadPolicy } from "./worker-policy.js";
-import { execFileSync } from "node:child_process";
-import { helperStale, recordHelperBuild } from "./helpers-build.js";
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { helperStale, installHelper } from "./helpers-build.js";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { platform } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CONFIG_DIR, load, loadAll, configFor } from "./config.js";
 import { workerProc, notifierProc } from "./machine.js";
 import { agentHookStates } from "./notify.js";
-import { requireDeveloperTools } from "./notifier.js";
 import { plistPath, serviceInstalled, whichPantheon } from "./service.js";
 import { VERSION } from "./version.js";
 import { LIMITS } from "./protocol.js";
@@ -18,7 +16,8 @@ import { loadProfile, SURFACE_BUNDLE_IDS } from "./profile.js";
 const HERE = dirname(fileURLToPath(import.meta.url));
 export const trayBinaryPath = (home = CONFIG_DIR) => join(home, "bin", "pantheon-tray");
 export const traySourcePath = () => resolve(HERE, "..", "helper", "macos", "menubar.swift");
-export function ensureTrayBinary(home = CONFIG_DIR) {
+export const TRAY_PREBUILT = "pantheon-tray";
+export function ensureTrayBinary(home = CONFIG_DIR, deps = {}) {
     if (platform() !== "darwin")
         throw new Error("the pantheon menu bar is currently macOS-only");
     const source = traySourcePath();
@@ -26,11 +25,7 @@ export function ensureTrayBinary(home = CONFIG_DIR) {
         throw new Error(`menu bar source is missing: ${source}`);
     const binary = trayBinaryPath(home);
     mkdirSync(dirname(binary), { recursive: true });
-    requireDeveloperTools("the menu bar", "menubar");
-    execFileSync("/usr/bin/swiftc", ["-O", source, "-o", binary], { stdio: "pipe" });
-    chmodSync(binary, 0o755);
-    recordHelperBuild(binary, source);
-    return binary;
+    return installHelper({ name: TRAY_PREBUILT, source, binary, what: "the menu bar", service: "menubar" }, deps).binary;
 }
 export function trayStale(home = CONFIG_DIR) { return helperStale(trayBinaryPath(home), traySourcePath()); }
 export function writeTrayCommands(home = CONFIG_DIR) {

package/dist/uninstall.js

@@ -0,0 +1,194 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, lstatSync, readFileSync, readdirSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
+import { platform } from "node:os";
+import { posix, win32 } from "node:path";
+import { expectedLauncher } from "./managed.js";
+export const BEGIN_MARK = "# >>> pantheon >>>";
+export const END_MARK = "# <<< pantheon <<<";
+export const PROFILES = [".profile", ".bash_profile", ".bashrc", ".zshrc", ".zprofile"];
+export const FISH_CONF = ".config/fish/conf.d/pantheon.fish";
+export function withoutPathBlock(text) {
+    const lines = text.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+    const bare = (l) => l.replace(/\n$/, "").replace(/\r$/, "");
+    const out = [];
+    let blocks = 0;
+    for (let i = 0; i < lines.length; i++) {
+        if (bare(lines[i]) !== BEGIN_MARK) {
+            out.push(lines[i]);
+            continue;
+        }
+        let end = i + 1;
+        while (end < lines.length && bare(lines[end]) !== END_MARK)
+            end++;
+        if (end >= lines.length)
+            return { error: `a "${BEGIN_MARK}" line with no "${END_MARK}" after it` };
+        if (out.length && bare(out[out.length - 1]) === "")
+            out.pop();
+        blocks++;
+        i = end;
+    }
+    return blocks ? { text: out.join(""), blocks } : null;
+}
+export function expandWindows(s, env) {
+    const keys = Object.keys(env);
+    return s.replace(/%([^%;]+)%/g, (all, name) => {
+        const k = keys.find((x) => x.toLowerCase() === name.toLowerCase());
+        return k !== undefined && env[k] !== undefined ? env[k] : all;
+    });
+}
+export function withoutPathEntry(raw, binDir, env) {
+    const norm = (p) => expandWindows(p, env).trim().replace(/\\+$/, "").toLowerCase();
+    const want = norm(binDir);
+    const parts = raw.split(";");
+    const kept = parts.filter((p) => p === "" || norm(p) !== want);
+    return kept.length === parts.length ? null : kept.join(";");
+}
+export function registryUserPath(run = (script, env) => execFileSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", script], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 60_000, windowsHide: true, env })) {
+    return {
+        read: () => {
+            const out = run("$k = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment'); " +
+                "if ($null -eq $k) { 'NONE'; exit 0 }; " +
+                "try { $v = $k.GetValue('Path', $null, [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames) } finally { $k.Close() }; " +
+                "if ($null -eq $v) { 'NONE' } else { 'B64:' + [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes([string]$v)) }", process.env).trim();
+            if (out === "NONE")
+                return null;
+            const m = /B64:([A-Za-z0-9+/=]*)/.exec(out);
+            if (!m)
+                throw new Error(`the user PATH could not be read (${out.split("\n")[0] || "no answer"})`);
+            return Buffer.from(m[1], "base64").toString("utf8");
+        },
+        write: (value) => {
+            run("$v = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($env:PANTHEON_USER_PATH_B64)); " +
+                "$k = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey('Environment'); " +
+                "try { if ($v -eq '') { $k.DeleteValue('Path', $false) } else { $k.SetValue('Path', $v, [Microsoft.Win32.RegistryValueKind]::ExpandString) } } finally { $k.Close() }; " +
+                "[Environment]::SetEnvironmentVariable('PANTHEON_PATH_UPDATED', '1', 'User'); " +
+                "[Environment]::SetEnvironmentVariable('PANTHEON_PATH_UPDATED', $null, 'User')", { ...process.env, PANTHEON_USER_PATH_B64: Buffer.from(value, "utf8").toString("base64") });
+        },
+    };
+}
+export const realUninstallFs = {
+    exists: (p) => existsSync(p),
+    isSymlink: (p) => { try {
+        return lstatSync(p).isSymbolicLink();
+    }
+    catch {
+        return false;
+    } },
+    read: (p) => readFileSync(p, "utf8"),
+    write: (p, text) => writeFileSync(p, text),
+    remove: (p) => rmSync(p, { recursive: true, force: true }),
+    removeIfEmpty: (p) => { try {
+        if (!readdirSync(p).length)
+            rmdirSync(p);
+    }
+    catch { } },
+};
+export function managedInstall(home, os = platform(), env = process.env, fs = realUninstallFs) {
+    const launcher = expectedLauncher(home, os, env);
+    if (!launcher)
+        return null;
+    const p = os === "win32" ? win32 : posix;
+    const binDir = p.dirname(launcher);
+    const root = p.dirname(binDir);
+    const runtime = p.join(root, "runtime");
+    const log = os === "win32" ? p.join(root, "install.log") : p.join(root, "logs", "install.log");
+    return { os, root, runtime, binDir, launcher, log, present: fs.exists(runtime) || fs.exists(launcher) };
+}
+export function removeManagedInstall(o) {
+    const fs = o.fs ?? realUninstallFs;
+    const env = o.env ?? process.env;
+    const { install: m } = o;
+    const removed = [], left = [];
+    const p = m.os === "win32" ? win32 : posix;
+    if (m.os === "win32") {
+        try {
+            const io = o.userPath ?? registryUserPath();
+            const raw = io.read();
+            const next = raw === null ? null : withoutPathEntry(raw, m.binDir, env);
+            if (next !== null) {
+                io.write(next);
+                removed.push(`${m.binDir} from your user PATH (the other entries as they were)`);
+            }
+        }
+        catch (e) {
+            left.push(`${m.binDir} in your user PATH — could not change it (${e.message.split("\n")[0]}); remove it in Settings > System > About > Advanced system settings > Environment Variables`);
+        }
+    }
+    else {
+        for (const name of PROFILES) {
+            const f = p.join(o.home, name);
+            if (!fs.exists(f))
+                continue;
+            let text;
+            try {
+                text = fs.read(f);
+            }
+            catch (e) {
+                left.push(`the PATH block in ${f} — could not read it (${e.message.split("\n")[0]})`);
+                continue;
+            }
+            const r = withoutPathBlock(text);
+            if (!r)
+                continue;
+            if ("error" in r) {
+                left.push(`${f} — ${r.error}, so it was left as it is; delete the pantheon lines yourself`);
+                continue;
+            }
+            try {
+                if (r.text === "" && !fs.isSymlink(f)) {
+                    fs.remove(f);
+                    removed.push(`${f} (it held only Pantheon's PATH lines)`);
+                }
+                else {
+                    fs.write(f, r.text);
+                    removed.push(`the PATH lines in ${f}`);
+                }
+            }
+            catch (e) {
+                left.push(`the PATH block in ${f} — could not write it (${e.message.split("\n")[0]}); delete the lines from "${BEGIN_MARK}" to "${END_MARK}" yourself`);
+            }
+        }
+        const fish = p.join(o.home, FISH_CONF);
+        if (fs.exists(fish)) {
+            let ours = false;
+            try {
+                ours = fs.read(fish).includes(".pantheon/bin");
+            }
+            catch { }
+            if (ours) {
+                try {
+                    fs.remove(fish);
+                    removed.push(fish);
+                }
+                catch (e) {
+                    left.push(`${fish} — could not remove (${e.message.split("\n")[0]})`);
+                }
+            }
+            else
+                left.push(`${fish} — it does not look like the installer's, so it was left`);
+        }
+    }
+    const lockedHere = m.os === "win32" && !!o.running && o.running.root.toLowerCase() === m.root.toLowerCase();
+    if (lockedHere) {
+        left.push(`${m.root} — Windows keeps Pantheon's node.exe locked while this command runs. Close your agent windows and this one, then in a new PowerShell: Remove-Item -Recurse -Force "$env:LOCALAPPDATA\\Pantheon"`);
+        return { removed, left };
+    }
+    for (const [path, what] of [[m.launcher, "the pantheon command"], [m.log, "the installer's log"], [m.runtime, "Pantheon's own Node and the CLI in it"]]) {
+        if (!fs.exists(path))
+            continue;
+        try {
+            fs.remove(path);
+            removed.push(`${what} (${path})`);
+        }
+        catch (e) {
+            const busy = /EBUSY|EPERM|EACCES/.test(String(e.code ?? e.message));
+            left.push(`${what}, ${path} — could not remove (${e.message.split("\n")[0]})` +
+                (m.os === "win32" && busy ? `; an agent window is still running it. Close them, then in PowerShell: Remove-Item -Recurse -Force "${path}"` : `; remove it with: rm -rf '${path.replace(/'/g, "'\\''")}'`));
+        }
+    }
+    for (const dir of [m.binDir, ...(m.os === "win32" ? [] : [p.dirname(m.log)]), m.root])
+        fs.removeIfEmpty(dir);
+    return { removed, left };
+}
+export const NPM_UNINSTALL = "npm uninstall -g @join-pantheon/cli";
+//# sourceMappingURL=uninstall.js.map

package/dist/upgrade.js

@@ -1,11 +1,13 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, posix, win32 } from "node:path";
 import { fileURLToPath } from "node:url";
 import { installForUser } from "./install.js";
 import { npmSpawn } from "./which.js";
 import { proxyEnvFor } from "./network.js";
 import { relayProc, workerProc, notifierProc, menubarProc } from "./machine.js";
+import { load } from "./config.js";
+import { childNodeFlags, installerLineHere, managedLayout, nodeSatisfies, nodeTooOldSentence, runtimeNodeVersion } from "./managed.js";
 export function repoRoot() {
     return join(dirname(fileURLToPath(import.meta.url)), "..");
 }
@@ -18,7 +20,20 @@ function pkgVersion(root) {
     }
 }
 export const PKG_NAME = "@join-pantheon/cli";
-export function rewireVia(root, fallback, run = (file, args) => execFileSync(process.execPath, [file, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 120_000 })) {
+export function npmInstallArgs(version, managed = managedLayout()) {
+    const P = /\.exe$/i.test(managed?.node ?? "") ? win32 : posix;
+    const own = managed ? ["--prefix", managed.nodeDir, "--cache", P.join(managed.root, "runtime", "npm-cache"), "--fetch-timeout=60000", "--fetch-retries=2"] : [];
+    return ["install", "-g", ...own, `${PKG_NAME}@${version ?? "latest"}`, "--no-audit", "--no-fund"];
+}
+export function npmFailed(spec, e, managed, os = process.platform, relay) {
+    const first = String(e?.message ?? e).split("\n")[0];
+    if (managed) {
+        return `\`${managed.npm} install -g ${PKG_NAME}@${spec}\` failed: ${first}. Run the installer again to repair it: ${installerLineHere(relay, os)}`;
+    }
+    return `\`npm install -g ${PKG_NAME}@${spec}\` failed: ${first}. `
+        + `You may need to re-run it with the right permissions (or your Node version manager's global scope).`;
+}
+export function rewireVia(root, fallback, run = (file, args) => execFileSync(process.execPath, [...childNodeFlags(), file, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 120_000 })) {
     try {
         const out = JSON.parse(run(join(root, "dist", "cli.js"), ["rewire", "--json"]));
         if (Array.isArray(out) && out.every((o) => o && typeof o.tool === "string" && typeof o.status === "string")) {
@@ -70,7 +85,7 @@ export function defaultDeps() {
             catch { }
             return up;
         },
-        npmUpgrade: (version) => npm(["install", "-g", `${PKG_NAME}@${version ?? "latest"}`, "--no-audit", "--no-fund"], { stdio: ["ignore", "pipe", "pipe"] }),
+        npmUpgrade: (version) => npm(npmInstallArgs(version), { stdio: ["ignore", "pipe", "pipe"] }),
         npmLatest: () => {
             try {
                 return npm(["view", `${PKG_NAME}`, "version"], { stdio: ["ignore", "pipe", "ignore"], timeout: 4000 }).trim() || null;
@@ -79,6 +94,22 @@ export function defaultDeps() {
                 return null;
             }
         },
+        engines: (spec) => {
+            try {
+                const out = npm(["view", `${PKG_NAME}@${spec}`, "engines.node"], { stdio: ["ignore", "pipe", "ignore"], timeout: 20_000 }).trim();
+                return out.split("\n").at(-1).trim().replace(/^['"]|['"]$/g, "") || null;
+            }
+            catch {
+                return null;
+            }
+        },
+        runtimeNode: () => runtimeNodeVersion(),
+        relay: (() => { try {
+            return load()?.relay ?? null;
+        }
+        catch {
+            return null;
+        } })(),
     };
 }
 export function upgrade(deps = defaultDeps(), opts = {}) {
@@ -88,6 +119,15 @@ export function upgrade(deps = defaultDeps(), opts = {}) {
     const steps = [];
     const stop = (name, detail) => ({ root, from, to: from, steps: [...steps, { name, ok: false, detail }], ok: false, alreadyCurrent: false, restart: [] });
     if (!deps.isGit(root)) {
+        const managed = deps.managed === undefined ? managedLayout() : deps.managed;
+        if (managed && deps.engines) {
+            const range = deps.engines(spec);
+            const node = deps.runtimeNode ? deps.runtimeNode() : runtimeNodeVersion(managed);
+            if (range && nodeSatisfies(node, range) === false) {
+                const why = nodeTooOldSentence(spec === "latest" ? null : spec, range, node, deps.relay);
+                return { ...stop("node", why), needsPerson: why };
+            }
+        }
         try {
             deps.npmUpgrade(spec === "latest" ? undefined : spec);
             steps.push({ name: "npm", ok: true, detail: `installed ${PKG_NAME}@${spec}` });
@@ -96,8 +136,7 @@ export function upgrade(deps = defaultDeps(), opts = {}) {
             if (spec !== "latest" && /ETARGET|No matching version|notarget/i.test(String(e.stderr ?? "") + e.message)) {
                 return { root, from, to: from, steps: [...steps, { name: "npm", ok: true, detail: `${PKG_NAME}@${spec} is not on npm yet` }], ok: true, alreadyCurrent: true, restart: [] };
             }
-            return stop("npm", `\`npm install -g ${PKG_NAME}@${spec}\` failed: ${e.message.split("\n")[0]}. ` +
-                `You may need to re-run it with the right permissions (or your Node version manager's global scope).`);
+            return stop("npm", npmFailed(spec, e, managed, process.platform, deps.relay));
         }
         let wired = [];
         try {

package/dist/which.js

@@ -3,6 +3,7 @@ import { randomBytes } from "node:crypto";
 import { accessSync, constants, existsSync, readFileSync, statSync } from "node:fs";
 import { dirname, join, posix, resolve, win32 } from "node:path";
 import { platform } from "node:os";
+import { managedLayout } from "./managed.js";
 export const DEFAULT_PATHEXT = ".COM;.EXE;.BAT;.CMD;.VBS;.JS;.PS1";
 const isWindows = (os = platform()) => os === "win32";
 function runnable(file) {
@@ -124,11 +125,18 @@ export function spawnShape(binary, os = platform()) {
         return { command: binary, shell: false };
     return { command: binary, shell: /\.(cmd|bat)$/i.test(binary) };
 }
-export function npmSpawn(args, os = platform(), resolveNpm = () => which("npm", os), proxyEnv = {}) {
-    const env = Object.keys(proxyEnv).length ? { env: { ...process.env, ...proxyEnv } } : {};
+export function npmSpawn(args, os = platform(), resolveNpm, proxyEnv = {}, managed = managedLayout(process.execPath, os)) {
+    const extra = { ...proxyEnv };
+    if (managed && !resolveNpm) {
+        const dir = isWindows(os) ? win32.dirname(managed.node) : posix.dirname(managed.node);
+        const key = isWindows(os) ? Object.keys(process.env).find((k) => k.toUpperCase() === "PATH") ?? "Path" : "PATH";
+        extra[key] = [dir, process.env[key] ?? ""].filter(Boolean).join(isWindows(os) ? ";" : ":");
+        return { command: managed.node, args: ["--use-system-ca", managed.npmCli, ...args], options: { env: { ...process.env, ...extra } } };
+    }
+    const env = Object.keys(extra).length ? { env: { ...process.env, ...extra } } : {};
     if (!isWindows(os))
         return { command: "npm", args: [...args], options: { ...env } };
-    const s = agentSpawn(resolveNpm() ?? "npm.cmd", args, os);
+    const s = agentSpawn((resolveNpm ?? (() => which("npm", os)))() ?? "npm.cmd", args, os);
     return { ...s, options: { ...s.options, ...env } };
 }
 const CMD_UNSAFE = /["%!^&|<>\r\n\0]/;

package/dist/worker-policy.js

@@ -68,6 +68,8 @@ export function loadPolicy(home) {
             ...(isRecord(raw.wakeOnce) ? { wakeOnce: Object.fromEntries(Object.entries(raw.wakeOnce).filter(([, v]) => typeof v === "number" && v > 0 && v < 100)) } : {}),
             ...(isRecord(raw.wakeNo) ? { wakeNo: Object.fromEntries(Object.entries(raw.wakeNo).filter(([, v]) => typeof v === "number")) } : {}),
             ...(isRecord(raw.wakeTeamFlag) ? { wakeTeamFlag: Object.fromEntries(Object.entries(raw.wakeTeamFlag).filter(([, v]) => typeof v === "number")) } : {}),
+            ...(isRecord(raw.upgradeHeld) && typeof raw.upgradeHeld.version === "string" && typeof raw.upgradeHeld.node === "string"
+                ? { upgradeHeld: { version: raw.upgradeHeld.version, node: raw.upgradeHeld.node, at: Number(raw.upgradeHeld.at) || 0, why: String(raw.upgradeHeld.why ?? "") } } : {}),
         };
     }
     catch {

package/dist/worker.js

@@ -18,7 +18,8 @@ import { headlessSpawn, materializeSpawnFiles, chooseAgent, agentById, describeC
 import { activeOutages, detectOutage, earliest, whenAgain } from "./agent-outage.js";
 import { agentSpawn, CmdLineUnsafe } from "./which.js";
 import { VERSION } from "./version.js";
-import { applyAnswer, CAPABILITY_ARGS, CARRY_REASON, carryOverWakers, dropLedgerGrants, hasWakeOnce, isApprovedWaker, mayAskWake, takeWakeOnce, OLD_RELAY_WAKE, relayKnowsAdmitters, loadPolicy, mayAsk, needsSelfUpgrade, parseGrantAnswer, recordAsk, savePolicy, useGrant, WOKEN_RUN_ENV, takeTeamFlagOnYes, unsandboxedAllowed, policyPath, } from "./worker-policy.js";
+import { applyAnswer, CAPABILITY_ARGS, CARRY_REASON, carryOverWakers, dropLedgerGrants, hasWakeOnce, isApprovedWaker, mayAskWake, takeWakeOnce, OLD_RELAY_WAKE, relayKnowsAdmitters, loadPolicy, mayAsk, needsSelfUpgrade, parseGrantAnswer, recordAsk, savePolicy, useGrant, WOKEN_RUN_ENV, takeTeamFlagOnYes, unsandboxedAllowed, policyPath, isNewer, } from "./worker-policy.js";
+import { runtimeNodeVersion } from "./managed.js";
 import { agentHookStates, repairHook } from "./notify.js";
 import { fence, assess } from "./untrusted.js";
 import { allowed, closeStartedRun, finishRun, recordRun, startRun } from "./spend.js";
@@ -3143,13 +3144,19 @@ export class Worker {
         const lastAttempt = policy.attempts.self_upgrade ?? null;
         if (!needsSelfUpgrade(VERSION, relayPkg, lastAttempt))
             return;
+        const nodeNow = this.opts.selfUpgrade?.node ?? (() => runtimeNodeVersion());
+        const held = policy.upgradeHeld;
+        if (held && held.version === relayPkg && held.node === nodeNow())
+            return;
         if (policy.grants.self_upgrade) {
             const slot = this.takeSlot();
             if ("held" in slot)
                 return;
             try {
+                const grantBefore = policy.grants.self_upgrade;
                 useGrant(policy, "self_upgrade");
                 policy.attempts.self_upgrade = Date.now();
+                delete policy.upgradeHeld;
                 savePolicy(policy, home);
                 this.writeState("upgrading", `pantheon ${VERSION} -> ${relayPkg} (relay is ahead)`);
                 this.opts.log(`* self-upgrade: relay runs ${relayPkg}, this machine runs ${VERSION} — upgrading (granted by this machine's human)`);
@@ -3161,20 +3168,36 @@ export class Worker {
                     result = { ok: false, alreadyCurrent: false, from: VERSION, to: relayPkg ?? "?" };
                     this.opts.log(`! self-upgrade failed: ${e.message}`);
                 }
-                if (result.ok && result.to === result.from) {
+                if (result.needsPerson) {
+                    if (grantBefore)
+                        policy.grants.self_upgrade = grantBefore;
+                    delete policy.attempts.self_upgrade;
+                    policy.upgradeHeld = { version: relayPkg ?? result.to, node: nodeNow(), at: Date.now(), why: result.needsPerson };
+                    savePolicy(policy, home);
+                    this.writeState("needs you", result.needsPerson);
+                    this.opts.log(`! self-upgrade needs you: ${result.needsPerson}`);
+                    try {
+                        this.opts.notify?.({ kind: "worker", who: "Your worker", heading: "Pantheon needs a newer Node", context: this.cfg.space, body: result.needsPerson, ttl: 0, sound: false });
+                    }
+                    catch { }
+                    return;
+                }
+                const behindDisk = result.ok && result.to === result.from && isNewer(result.to, VERSION);
+                if (result.ok && result.to === result.from && !behindDisk) {
                     delete policy.attempts.self_upgrade;
                     savePolicy(policy, home);
                     this.opts.log(`* self-upgrade: nothing newer than ${result.to} to install yet (the relay runs ${relayPkg}); will check again`);
                     return;
                 }
-                if (result.ok && !result.alreadyCurrent) {
+                if (result.ok && (!result.alreadyCurrent || behindDisk)) {
+                    const from = behindDisk ? VERSION : result.from;
                     await client.send({
                         act: "NOTE", goal: null, after_seq: Math.max(client.readSeq, client.seq),
-                        summary: `self-upgraded pantheon ${result.from} -> ${result.to}; worker restarting on the new build`,
-                        body: `This machine's worker upgraded pantheon ${result.from} -> ${result.to} (fast-forward pull + rebuild, granted by its human) and is restarting on the new build. Agent windows on this machine opened on 0.24 or later switch to the new version by themselves; a window opened on an older pantheon needs one reconnect (/mcp → pantheon → Reconnect, or reopen it).`,
+                        summary: `self-upgraded pantheon ${from} -> ${result.to}; worker restarting on the new build`,
+                        body: `This machine's worker upgraded pantheon ${from} -> ${result.to} (fast-forward pull + rebuild, granted by its human) and is restarting on the new build. Agent windows on this machine opened on 0.24 or later switch to the new version by themselves; a window opened on an older pantheon needs one reconnect (/mcp → pantheon → Reconnect, or reopen it).`,
                     }).catch((e) => this.opts.log(`! could not report the upgrade on the ledger: ${e.message}`));
                     await this.bringMachineAlong();
-                    this.opts.log(`* self-upgrade done: ${result.from} -> ${result.to}; restarting worker to load it`);
+                    this.opts.log(`* self-upgrade done: ${from} -> ${result.to}; restarting worker to load it`);
                     (this.opts.selfUpgrade?.restart ?? (() => process.exit(0)))();
                 }
                 else if (!result.ok) {
@@ -3512,7 +3535,7 @@ export class Worker {
     async runRealUpgrade(version) {
         const { upgrade } = await import("./upgrade.js");
         const r = upgrade(undefined, version ? { version } : {});
-        return { ok: r.ok, alreadyCurrent: r.alreadyCurrent, from: r.from, to: r.to };
+        return { ok: r.ok, alreadyCurrent: r.alreadyCurrent, from: r.from, to: r.to, ...(r.needsPerson ? { needsPerson: r.needsPerson } : {}) };
     }
     writeState(state, detail) {
         const line = `${state}|${detail}`;