@join-pantheon/cli 0.27.0 → 0.28.0

package/dist/cli.js

@@ -29,7 +29,8 @@ import { menubarProc, notifierProc, relayProc, workerProc, wiring, logFileFor, d
 import { assess } from "./untrusted.js";
 import { report as spendReport, recentRuns } from "./spend.js";
 import { renderBrief, renderTeam } from "./brief.js";
-import { resolveDataDir } from "./config.js";
+import { resolveDataDir, saveAll } from "./config.js";
+import { currentPlan, installNetwork, redactProxy, normalizeProxy, usedSystemFallback } from "./network.js";
 import { createInterface } from "node:readline";
 import { homedir } from "node:os";
 import { removeHook, decideStop, writeIntent, clearIntent, readIntent, installHooks, agentHookStates } from "./notify.js";
@@ -521,6 +522,7 @@ ${B("control")}
   pantheon leave              remove what pantheon put on this machine
   pantheon panic              cut off all unattended work on this machine, now
   pantheon doctor [--share]   check this machine end to end; --share prints it without names or paths, to paste to us
+  pantheon network [--proxy <url> | --direct | --clear]   how this machine reaches the relay; save a proxy for every Pantheon process here
   pantheon setup              three questions — your name, your role, may a woken run execute commands —
                               then one screen of defaults to keep or change: who may wake this machine,
                               alerts, what you personally decide, playbook, base branch. Re-run any time.
@@ -549,7 +551,26 @@ ${B("less common")}
   pantheon version            the pantheon version this machine is running
 `;
 const QUIET = new Set(["mcp", "hook", "pending", "version", "tray-status"]);
+function rememberWorkingProxy() {
+    try {
+        const plan = currentPlan();
+        const via = plan.https ?? plan.http;
+        if (!via || (plan.source !== "env" && !(plan.fallbackOnly && usedSystemFallback())))
+            return;
+        const all = loadAll();
+        if (!all || all.network?.source === "pantheon network" || all.network?.proxy === via)
+            return;
+        const custom = plan.noProxy.filter((h) => !["localhost", "127.0.0.1", "::1", "[::1]"].includes(h));
+        saveAll({ ...all, network: { proxy: via, ...(custom.length ? { no_proxy: custom.join(",") } : {}), source: plan.source, saved_at: Date.now() } });
+        console.error(D(`  saved the proxy ${redactProxy(via)} for this machine's other Pantheon processes (worker, editors) — change it with pantheon network`));
+    }
+    catch { }
+}
 async function main() {
+    try {
+        await installNetwork();
+    }
+    catch { }
     if (!QUIET.has(cmd)) {
         try {
             console.error(D(updateBanner(VERSION)));
@@ -565,6 +586,35 @@ async function main() {
         return interactiveOnboard();
     }
     switch (cmd) {
+        case "network": {
+            const all = loadAll() ?? die("not configured — sign up or join a team first");
+            const set = flag("proxy");
+            if (set !== undefined) {
+                const p = normalizeProxy(set) ?? die(`"${set}" is not a proxy address — use http://host:port (add user:password@ if it needs a login)`);
+                saveAll({ ...all, network: { proxy: p, ...(flag("no-proxy") ? { no_proxy: flag("no-proxy") } : {}), source: "pantheon network", saved_at: Date.now() } });
+                console.error(`${B("saved")} every Pantheon process on this machine now reaches the relay through ${redactProxy(p)}`);
+                return;
+            }
+            if (argv.includes("--direct")) {
+                saveAll({ ...all, network: { proxy: "", source: "pantheon network --direct", saved_at: Date.now() } });
+                console.error(`${B("saved")} direct — set PANTHEON_PROXY=none in a shell to do the same for one command`);
+                return;
+            }
+            if (argv.includes("--clear")) {
+                const { network: _drop, ...rest } = all;
+                saveAll(rest);
+                console.error(`${B("cleared")} — Pantheon follows HTTPS_PROXY / NO_PROXY and the system settings again`);
+                return;
+            }
+            const plan = currentPlan();
+            const via = plan.https ?? plan.http;
+            console.log(`${B("network")}  ${via ? `through ${redactProxy(via)}` : "direct"}${plan.source !== "none" ? D(`   from ${plan.source}${plan.fallbackOnly ? ", used only if a direct connection fails" : ""}`) : ""}`);
+            if (via)
+                console.log(D(`  not for: ${plan.noProxy.join(", ")}`));
+            if (plan.pac)
+                console.log(D(`  this machine uses an auto-config script (${plan.pac}), which Pantheon cannot read — if the relay is unreachable, save the proxy it points to: pantheon network --proxy http://host:port`));
+            return;
+        }
         case "start": {
             const port = Number(flag("port", "8787"));
             const setupFlags = parseSetupFlags(argv);
@@ -595,6 +645,7 @@ async function main() {
             for (const w of r.warnings)
                 console.error(`\x1b[33m  ! ${w}\x1b[0m`);
             printGranted(r.granted);
+            rememberWorkingProxy();
             if (!r.claimed) {
                 console.error(`\n\x1b[31m  No team was created.\x1b[0m ${D("Fix the warning above, then run `pantheon start` again.")}`);
                 if (r.relay)
@@ -794,6 +845,7 @@ async function main() {
             for (const w of r.warnings)
                 console.error(`\x1b[33m  ! ${w}\x1b[0m`);
             printGranted(r.granted);
+            rememberWorkingProxy();
             printReady(r.tools);
             {
                 const joined = load();

package/dist/client.js

@@ -2,6 +2,7 @@ import WebSocket from "ws";
 import { signChallenge } from "./identity.js";
 import { newId } from "./protocol.js";
 import { VERSION } from "./version.js";
+import { describeNetError, explainNetError, trySystemFallback, wsOptions } from "./network.js";
 export class PantheonClient {
     cfg;
     onEvent;
@@ -74,7 +75,28 @@ export class PantheonClient {
     connect() {
         if (!this.everConnected)
             this.closed = false;
-        return this.attempt(this.localOverride ?? this.cfg.relay).catch(async (e) => {
+        const first = this.localOverride ?? this.cfg.relay;
+        return this.attempt(first).catch(async (e) => {
+            if (!this.localOverride && trySystemFallback(first, e)) {
+                this.closed = false;
+                try {
+                    return await this.attempt(first);
+                }
+                catch (e2) {
+                    e = e2;
+                }
+            }
+            return this.afterFailure(e);
+        }).catch((e) => {
+            if (!explainNetError(e))
+                throw e;
+            const out = new Error(describeNetError(e));
+            out.code = e.code;
+            throw out;
+        });
+    }
+    async afterFailure(e) {
+        {
             if (this.localOverride)
                 throw e;
             const transport = /ETIMEDOUT|ECONNREFUSED|ENOTFOUND|EHOSTUNREACH|ENETUNREACH|handshake has timed out|socket hang up/i
@@ -88,13 +110,13 @@ export class PantheonClient {
             this.localOverride = local;
             this.usingLoopback = true;
             return this.attempt(local);
-        });
+        }
     }
     attempt(address) {
         return new Promise((resolve, reject) => {
             let settled = false;
             this.ws?.terminate();
-            const ws = new WebSocket(address, { handshakeTimeout: 6000 });
+            const ws = new WebSocket(address, { handshakeTimeout: 6000, ...wsOptions(address) });
             this.ws = ws;
             ws.on("open", () => { });
             ws.on("message", (raw) => {

package/dist/doctor.js

@@ -20,6 +20,7 @@ import { onPathNamed } from "./which.js";
 import { VERSION } from "./version.js";
 import { serviceInstalled, servicesUnavailable } from "./service.js";
 import { hostEnv, platformName } from "./host-env.js";
+import { currentPlan, explainNetError, proxyFor, redactProxy } from "./network.js";
 const HOSTED_RELAY = "relay.joinpantheon.network";
 const git = (args, cwd) => {
     try {
@@ -222,6 +223,20 @@ export async function doctor(projectDir) {
     else {
         add("pass", "transport", url.protocol === "wss:" ? "wss:// (TLS)" : `ws:// on a private address (${url.host})`, undefined, url.protocol === "wss:" ? "wss:// (TLS)" : "ws:// on a private address");
     }
+    const plan = currentPlan();
+    const via = proxyFor(cfg.relay, plan);
+    if (via) {
+        add("pass", "network", `through the proxy ${redactProxy(via)} (from ${plan.source})`, undefined, `through a proxy (${plan.source})`);
+    }
+    else if (plan.fallbackOnly && (plan.https || plan.http)) {
+        add("pass", "network", `direct; the ${plan.source === "macos" ? "macOS" : "Windows"} proxy ${redactProxy(plan.https ?? plan.http)} is used only if a direct connection fails`, undefined, `direct, system proxy as fallback`);
+    }
+    else if (plan.pac) {
+        add("warn", "network", `direct, but this machine uses a proxy auto-config script, which Pantheon cannot read`, "if the relay turns out unreachable below, save the proxy that script points to: pantheon network --proxy http://host:port", "direct; PAC script present");
+    }
+    else {
+        add("pass", "network", "direct — no proxy set", undefined, "direct");
+    }
     const health = `${cfg.relay.replace(/^ws/, "http")}/health`;
     const where = hosted ? "hosted" : "self-hosted";
     try {
@@ -245,6 +260,11 @@ export async function doctor(projectDir) {
     }
     catch (e) {
         const msg = e.message;
+        const nx = explainNetError(e);
+        if (nx) {
+            add("fail", "relay", `cannot reach ${health} — ${nx.why}`, nx.fix, `unreachable (${where}): ${nx.share}`);
+            return out;
+        }
         add("fail", "relay", `cannot reach ${health} — ${msg}`, "start it with `pantheon relay`, or check the tunnel/tailnet. Your teammate must be able to reach the SAME address.", `unreachable (${where}): ${/abort|timeout/i.test(msg) ? "timed out" : /ECONNREFUSED/.test(msg) ? "connection refused" : /ENOTFOUND|EAI_AGAIN/.test(msg) ? "name did not resolve" : "fetch failed"}`);
         return out;
     }
@@ -252,6 +272,12 @@ export async function doctor(projectDir) {
     let joined = false;
     await client.connect().then(() => { joined = true; }).catch(() => { });
     if (!joined) {
+        const nx = client.pending ? null : explainNetError(new Error(client.lastError ?? ""));
+        if (nx) {
+            add("fail", "live link", `the health check got through but the live connection did not — ${nx.why}`, nx.fix, `live connection failed: ${nx.share}`);
+            client.close();
+            return out;
+        }
         client.pending
             ? add("fail", "membership", "registered but not admitted", `ask an admitted member to run: pantheon admit ${cfg.member} --may-wake   (confirm fingerprint ${fingerprint(cfg.publicKey)} with them by voice first)`, "registered, not admitted")
             : add("fail", "membership", `refused: ${client.lastError ?? "unknown"}`, "if this is KEY_MISMATCH, someone else already registered your member name — pick another with --me, or have them revoke it", `refused: ${String(client.lastError ?? "unknown").split(/[\s:]/)[0]}`);

package/dist/network.js

@@ -0,0 +1,394 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import http from "node:http";
+import https from "node:https";
+import net from "node:net";
+import tls from "node:tls";
+import { platform } from "node:os";
+import { join } from "node:path";
+const LOOPBACK = ["localhost", "127.0.0.1", "::1", "[::1]"];
+const NONE = { https: null, http: null, noProxy: LOOPBACK, source: "none", fallbackOnly: false };
+const pick = (env, ...names) => {
+    for (const n of names) {
+        const v = env[n]?.trim();
+        if (v)
+            return v;
+    }
+    return undefined;
+};
+export function normalizeProxy(raw) {
+    const v = raw.trim();
+    if (!v)
+        return null;
+    try {
+        const u = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(v) ? v : `http://${v}`);
+        if (u.protocol !== "http:" && u.protocol !== "https:")
+            return null;
+        if (!u.hostname)
+            return null;
+        return u.toString().replace(/\/$/, "");
+    }
+    catch {
+        return null;
+    }
+}
+export function redactProxy(url) {
+    if (!url)
+        return "direct";
+    try {
+        const u = new URL(url);
+        if (u.username || u.password) {
+            u.username = u.username ? "***" : "";
+            u.password = "";
+        }
+        return u.toString().replace(/\/$/, "");
+    }
+    catch {
+        return "(unparseable)";
+    }
+}
+export function splitNoProxy(raw) {
+    return [...new Set([...(raw ?? "").split(/[,\s]+/).map((s) => s.trim().toLowerCase()).filter(Boolean), ...LOOPBACK])];
+}
+export function bypassesProxy(host, port, noProxy) {
+    const h = host.toLowerCase().replace(/^\[|\]$/g, "");
+    for (const raw of noProxy) {
+        if (raw === "*")
+            return true;
+        let entry = raw.replace(/^\[|\]$/g, "");
+        let entryPort;
+        const m = /^(.*):(\d+)$/.exec(entry);
+        if (m && !entry.includes("::")) {
+            entry = m[1];
+            entryPort = m[2];
+        }
+        if (entryPort && entryPort !== port)
+            continue;
+        if (entry.includes("/") && net.isIP(h)) {
+            if (inCidr(h, entry))
+                return true;
+            continue;
+        }
+        const bare = entry.replace(/^\*?\./, "");
+        if (h === bare || h.endsWith(`.${bare}`))
+            return true;
+    }
+    return false;
+}
+function inCidr(ip, cidr) {
+    const [base, bitsRaw] = cidr.split("/");
+    const bits = Number(bitsRaw);
+    if (!base || net.isIPv4(ip) !== net.isIPv4(base) || !net.isIPv4(ip) || !(bits >= 0 && bits <= 32))
+        return false;
+    const n = (s) => s.split(".").reduce((a, o) => (a << 8) + Number(o), 0) >>> 0;
+    const mask = bits === 0 ? 0 : (~0 << (32 - bits)) >>> 0;
+    return (n(ip) & mask) === (n(base) & mask);
+}
+export function parseScutil(out) {
+    const val = (k) => new RegExp(`^\\s*${k}\\s*:\\s*(.+?)\\s*$`, "m").exec(out)?.[1];
+    const on = (k) => val(k) === "1";
+    const hp = (host, port) => (host ? normalizeProxy(`${host}${port ? `:${port}` : ""}`) : null);
+    const exceptions = [];
+    const block = /ExceptionsList\s*:\s*<array>\s*\{([\s\S]*?)\}/.exec(out)?.[1] ?? "";
+    for (const line of block.split("\n")) {
+        const m = /:\s*(\S+)\s*$/.exec(line);
+        if (m)
+            exceptions.push(m[1]);
+    }
+    const pac = on("ProxyAutoConfigEnable") ? val("ProxyAutoConfigURLString") : undefined;
+    return {
+        https: on("HTTPSEnable") ? hp(val("HTTPSProxy"), val("HTTPSPort")) : null,
+        http: on("HTTPEnable") ? hp(val("HTTPProxy"), val("HTTPPort")) : null,
+        noProxy: exceptions,
+        ...(pac ? { pac } : {}),
+    };
+}
+export function parseWindowsReg(out) {
+    const val = (k) => new RegExp(`^\\s*${k}\\s+REG_\\w+\\s+(.*?)\\s*$`, "mi").exec(out)?.[1];
+    const pac = val("AutoConfigURL") || undefined;
+    const enabled = /^0x0*1$/i.test(val("ProxyEnable") ?? "");
+    const server = enabled ? val("ProxyServer") ?? "" : "";
+    let httpsP = null, httpP = null;
+    if (server.includes("=")) {
+        for (const part of server.split(";")) {
+            const [k, v] = part.split("=");
+            if (k?.trim().toLowerCase() === "https" && v)
+                httpsP = normalizeProxy(v);
+            if (k?.trim().toLowerCase() === "http" && v)
+                httpP = normalizeProxy(v);
+        }
+        httpsP ??= httpP;
+    }
+    else if (server) {
+        httpsP = httpP = normalizeProxy(server);
+    }
+    const override = (val("ProxyOverride") ?? "").split(";").map((s) => s.trim()).filter((s) => s && s !== "<local>");
+    return { https: httpsP, http: httpP, noProxy: override, ...(pac ? { pac } : {}) };
+}
+const run = (cmd, args) => {
+    try {
+        return execFileSync(cmd, args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 3000 });
+    }
+    catch {
+        return null;
+    }
+};
+function savedFromConfig(env) {
+    try {
+        const home = env.PANTHEON_HOME ?? join(env.HOME ?? env.USERPROFILE ?? "", ".pantheon");
+        const f = join(home, "config.json");
+        if (!existsSync(f))
+            return null;
+        return JSON.parse(readFileSync(f, "utf8")).network ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export const defaultNetworkDeps = () => ({
+    env: process.env,
+    os: platform(),
+    saved: () => savedFromConfig(process.env),
+    scutil: () => run("/usr/sbin/scutil", ["--proxy"]),
+    winReg: () => run("reg", ["query", "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Internet Settings"]),
+});
+export function resolveProxyPlan(d = defaultNetworkDeps()) {
+    const noProxy = splitNoProxy(pick(d.env, "no_proxy", "NO_PROXY"));
+    const forced = d.env.PANTHEON_PROXY?.trim();
+    if (forced) {
+        if (/^(none|direct|off|false|0)$/i.test(forced))
+            return { ...NONE, noProxy };
+        const p = normalizeProxy(forced);
+        if (p)
+            return { https: p, http: p, noProxy, source: "PANTHEON_PROXY", fallbackOnly: false };
+    }
+    const envHttps = pick(d.env, "https_proxy", "HTTPS_PROXY", "all_proxy", "ALL_PROXY");
+    const envHttp = pick(d.env, "http_proxy", "HTTP_PROXY", "all_proxy", "ALL_PROXY");
+    if (envHttps || envHttp) {
+        const hs = envHttps ? normalizeProxy(envHttps) : null;
+        const h = envHttp ? normalizeProxy(envHttp) : null;
+        if (hs || h)
+            return { https: hs, http: h, noProxy, source: "env", fallbackOnly: false };
+    }
+    const saved = d.saved();
+    if (saved && saved.proxy === "")
+        return { ...NONE, noProxy };
+    const sp = saved?.proxy ? normalizeProxy(saved.proxy) : null;
+    if (sp)
+        return { https: sp, http: sp, noProxy: splitNoProxy([saved?.no_proxy, ...noProxy].filter(Boolean).join(",")), source: "config", fallbackOnly: false };
+    const sys = d.os === "darwin" ? (() => { const o = d.scutil(); return o ? parseScutil(o) : null; })()
+        : d.os === "win32" ? (() => { const o = d.winReg(); return o ? parseWindowsReg(o) : null; })()
+            : null;
+    if (sys && (sys.https || sys.http)) {
+        return { https: sys.https ?? sys.http, http: sys.http ?? sys.https, noProxy: splitNoProxy([...sys.noProxy, ...noProxy].join(",")),
+            source: d.os === "darwin" ? "macos" : "windows", fallbackOnly: true, ...(sys.pac ? { pac: sys.pac } : {}) };
+    }
+    return { ...NONE, noProxy, ...(sys?.pac ? { pac: sys.pac } : {}) };
+}
+export function proxyFor(target, plan) {
+    let u;
+    try {
+        u = new URL(target);
+    }
+    catch {
+        return null;
+    }
+    const secure = u.protocol === "https:" || u.protocol === "wss:";
+    const port = u.port || (secure ? "443" : "80");
+    const p = secure ? plan.https : plan.http;
+    if (!p || bypassesProxy(u.hostname, port, plan.noProxy))
+        return null;
+    return p;
+}
+export function tunnelAgent(proxyUrl, secure) {
+    const proxy = new URL(proxyUrl);
+    const auth = proxy.username || proxy.password
+        ? `Basic ${Buffer.from(`${decodeURIComponent(proxy.username)}:${decodeURIComponent(proxy.password)}`).toString("base64")}`
+        : undefined;
+    const Base = secure ? https.Agent : http.Agent;
+    class Tunnel extends Base {
+        createConnection(options, callback) {
+            const cb = (err, s) => callback?.(err, s);
+            const host = String(options.hostname ?? options.host ?? "");
+            const port = Number(options.port ?? (secure ? 443 : 80));
+            const req = (proxy.protocol === "https:" ? https : http).request({
+                host: proxy.hostname, port: Number(proxy.port || (proxy.protocol === "https:" ? 443 : 80)),
+                method: "CONNECT", path: `${host.includes(":") ? `[${host}]` : host}:${port}`,
+                headers: { host: `${host}:${port}`, ...(auth ? { "proxy-authorization": auth } : {}) },
+                timeout: 10_000,
+            });
+            let done = false;
+            const fail = (e) => { if (!done) {
+                done = true;
+                cb(e);
+            } };
+            req.once("connect", (res, socket) => {
+                if (res.statusCode !== 200) {
+                    socket.destroy();
+                    const err = new Error(`the proxy ${redactProxy(proxyUrl)} answered ${res.statusCode} ${res.statusMessage ?? ""} to a tunnel request for ${host}:${port}`.trim());
+                    err.code = res.statusCode === 407 ? "PROXY_AUTH_REQUIRED" : "PROXY_REFUSED";
+                    return fail(err);
+                }
+                if (!secure) {
+                    done = true;
+                    return cb(null, socket);
+                }
+                const t = tls.connect({ ...options, socket, servername: net.isIP(host) ? undefined : host });
+                t.once("secureConnect", () => { if (!done) {
+                    done = true;
+                    cb(null, t);
+                } });
+                t.once("error", fail);
+            });
+            req.once("timeout", () => { req.destroy(Object.assign(new Error(`the proxy ${redactProxy(proxyUrl)} did not answer within 10s`), { code: "ETIMEDOUT" })); });
+            req.once("error", fail);
+            req.end();
+            return undefined;
+        }
+    }
+    return new Tunnel({ keepAlive: false });
+}
+let installed = null;
+let fallbackUsed = false;
+export function wsOptions(address) {
+    const plan = currentPlan();
+    if (plan.fallbackOnly && !fallbackUsed)
+        return {};
+    const p = proxyFor(address, plan);
+    if (!p)
+        return {};
+    return { agent: tunnelAgent(p, /^wss:/.test(address)) };
+}
+export function currentPlan() {
+    if (!installed)
+        installed = { plan: resolveProxyPlan(), active: null };
+    return installed.plan;
+}
+export async function installNetwork() {
+    const plan = currentPlan();
+    if (plan.https || plan.http) {
+        if (!plan.fallbackOnly)
+            await useProxyForFetch(plan);
+        else
+            wrapFetchWithFallback(plan);
+    }
+    return plan;
+}
+async function useProxyForFetch(plan) {
+    if (installed?.active)
+        return;
+    const { EnvHttpProxyAgent, setGlobalDispatcher } = await import("undici");
+    setGlobalDispatcher(new EnvHttpProxyAgent({
+        ...(plan.https ? { httpsProxy: plan.https } : {}),
+        ...(plan.http ? { httpProxy: plan.http } : {}),
+        noProxy: plan.noProxy.join(","),
+    }));
+    if (installed)
+        installed.active = plan.https ?? plan.http;
+}
+const BLOCKED = /ENOTFOUND|EAI_AGAIN|ECONNREFUSED|ETIMEDOUT|EHOSTUNREACH|ENETUNREACH|EPROTO|wrong version number|UND_ERR_CONNECT_TIMEOUT|UND_ERR_SOCKET|handshake has timed out|socket hang up/i;
+export const isBlockedPath = (e) => {
+    const err = e;
+    return BLOCKED.test(`${err?.code ?? ""} ${err?.message ?? ""} ${err?.cause?.code ?? ""} ${err?.cause?.message ?? ""}`);
+};
+function wrapFetchWithFallback(plan) {
+    const g = globalThis;
+    if (g.__pantheonFetch)
+        return;
+    g.__pantheonFetch = true;
+    const direct = g.fetch.bind(globalThis);
+    g.fetch = (async (input, init) => {
+        if (fallbackUsed)
+            return direct(input, init);
+        try {
+            return await direct(input, init);
+        }
+        catch (e) {
+            const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+            if (!isBlockedPath(e) || !proxyFor(url, plan))
+                throw e;
+            await useProxyForFetch(plan);
+            fallbackUsed = true;
+            return direct(input, init);
+        }
+    });
+}
+export function trySystemFallback(address, e) {
+    const plan = currentPlan();
+    if (!plan.fallbackOnly || fallbackUsed || !isBlockedPath(e) || !proxyFor(address, plan))
+        return false;
+    fallbackUsed = true;
+    void useProxyForFetch(plan);
+    return true;
+}
+export const usedSystemFallback = () => fallbackUsed;
+export function proxyEnvFor(plan = currentPlan()) {
+    if (!(plan.https || plan.http) || plan.source === "env")
+        return {};
+    if (plan.fallbackOnly && !fallbackUsed)
+        return {};
+    return {
+        ...(plan.https ? { HTTPS_PROXY: plan.https, https_proxy: plan.https } : {}),
+        ...(plan.http ? { HTTP_PROXY: plan.http, http_proxy: plan.http } : {}),
+        NO_PROXY: plan.noProxy.join(","), no_proxy: plan.noProxy.join(","),
+    };
+}
+export function resetNetworkForTests(plan) {
+    installed = plan ? { plan, active: null } : null;
+    fallbackUsed = false;
+    const g = globalThis;
+    delete g.__pantheonFetch;
+}
+export function explainNetError(e, plan = currentPlan()) {
+    const err = e;
+    const text = `${err?.code ?? ""} ${err?.message ?? ""} ${err?.cause?.code ?? ""} ${err?.cause?.message ?? ""}`;
+    const proxy = plan.https ?? plan.http;
+    const shown = proxy ? redactProxy(proxy) : "";
+    const orProxy = "Behind a company proxy? pantheon network --proxy http://host:port";
+    if (/PROXY_AUTH_REQUIRED|\b407\b/.test(text)) {
+        return { why: `the proxy ${shown} asked for a login`, fix: "put it in the proxy address: http://user:password@host:port", share: "proxy requires authentication" };
+    }
+    if (/PROXY_REFUSED/.test(text)) {
+        return { why: `the proxy ${shown} would not open a connection to the relay`, fix: "ask whoever runs it to allow HTTPS to relay.joinpantheon.network", share: "proxy refused the tunnel" };
+    }
+    if (/wrong version number|EPROTO|packet length too long|unknown protocol/i.test(text)) {
+        return proxy
+            ? { why: `the proxy ${shown} answered in plain text where a secure connection was expected`, fix: "check its address: company proxies are usually http://host:port, even for secure traffic", share: "TLS answered in plain text (via proxy)" }
+            : { why: "this network answered the relay's secure connection in plain text, which is what a network that requires a proxy does", fix: "set the proxy and run it again: export HTTPS_PROXY=http://host:port (or save it: pantheon network --proxy http://host:port)", share: "TLS answered in plain text (direct) — likely a required proxy" };
+    }
+    if (/SELF_SIGNED_CERT_IN_CHAIN|UNABLE_TO_GET_ISSUER_CERT_LOCALLY|UNABLE_TO_VERIFY_LEAF_SIGNATURE|self[- ]signed certificate|unable to get local issuer/i.test(text)) {
+        return { why: "the relay's certificate was swapped for one this machine does not trust, which happens on networks that inspect secure traffic", fix: "point Node at your company's root certificate: export NODE_EXTRA_CA_CERTS=/path/to/root.pem (or on Node 22.15+: NODE_USE_SYSTEM_CA=1)", share: "certificate not trusted — TLS inspection" };
+    }
+    if (/CERT_HAS_EXPIRED|certificate has expired|ERR_TLS_CERT_ALTNAME_INVALID|Hostname\/IP does not match/i.test(text)) {
+        return { why: "the relay's certificate looks expired or belongs to another name", fix: "check this machine's date and time, then try another network", share: "certificate expired or for another name" };
+    }
+    if (/ENOTFOUND|EAI_AGAIN|getaddrinfo/i.test(text)) {
+        return proxy
+            ? { why: `the proxy ${shown} could not find the relay's address`, fix: "check the relay address with pantheon doctor", share: "name did not resolve" }
+            : { why: "the relay's address did not resolve — this machine may be offline", fix: `check the connection and try again. ${orProxy}`, share: "name did not resolve" };
+    }
+    if (/ECONNREFUSED/i.test(text)) {
+        return proxy
+            ? { why: `nothing is accepting connections at the proxy ${shown}`, fix: "check the proxy address and port, or clear it: pantheon network --clear", share: "proxy refused the connection" }
+            : { why: "nothing is accepting connections at the relay's address — it may be down or restarting", fix: "try again in a minute; pantheon doctor shows more", share: "connection refused" };
+    }
+    if (/ETIMEDOUT|UND_ERR_CONNECT_TIMEOUT|handshake has timed out|timed out|EHOSTUNREACH|ENETUNREACH/i.test(text)) {
+        return proxy
+            ? { why: `the proxy ${shown} did not answer in time`, fix: "check it is reachable from this machine, or clear it: pantheon network --clear", share: "connection timed out" }
+            : { why: "the relay did not answer in time", fix: `check this machine is online and try again. ${orProxy}`, share: "connection timed out" };
+    }
+    if (/ECONNRESET|socket hang up/i.test(text)) {
+        return proxy
+            ? { why: `the connection through the proxy ${shown} was cut`, fix: "the proxy may not allow WebSockets; ask for relay.joinpantheon.network to be allowed", share: "connection reset" }
+            : { why: "the connection dropped before the relay answered", fix: "try again", share: "connection reset" };
+    }
+    return null;
+}
+export function describeNetError(e, plan) {
+    const raw = e?.message ?? String(e);
+    const x = explainNetError(e, plan);
+    const first = (raw.split("\n")[0] ?? "").slice(0, 120);
+    const fix = x ? x.fix.charAt(0).toUpperCase() + x.fix.slice(1) : "";
+    return x ? `${x.why}. ${fix}.  (${first})`.replace(/\.\.  \(/, ".  (").replace(/\?\.  \(/, "?  (") : raw;
+}
+//# sourceMappingURL=network.js.map

package/dist/update-check.js

@@ -5,6 +5,7 @@ import { CONFIG_DIR } from "./config.js";
 import { repoRoot, PKG_NAME } from "./upgrade.js";
 import { VERSION } from "./version.js";
 import { npmSpawn } from "./which.js";
+import { proxyEnvFor } from "./network.js";
 export function semverGt(x, y) {
     const p = (s) => s.split(".").map((n) => Number(n) || 0);
     const [a, b] = [p(x), p(y)];
@@ -81,7 +82,7 @@ export function defaultDeps(home) {
         },
         npmLatest: () => {
             try {
-                const s = npmSpawn(["view", PKG_NAME, "version"]);
+                const s = npmSpawn(["view", PKG_NAME, "version"], undefined, undefined, proxyEnvFor());
                 return execFileSync(s.command, s.args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 4000, ...s.options }).trim() || null;
             }
             catch {

package/dist/upgrade.js

@@ -4,6 +4,7 @@ import { dirname, join } 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";
 export function repoRoot() {
     return join(dirname(fileURLToPath(import.meta.url)), "..");
@@ -30,7 +31,7 @@ export function rewireVia(root, fallback, run = (file, args) => execFileSync(pro
 export function defaultDeps() {
     const git = (root, ...args) => execFileSync("git", ["-C", root, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
     const npm = (args, opts) => {
-        const s = npmSpawn(args);
+        const s = npmSpawn(args, undefined, undefined, proxyEnvFor());
         return execFileSync(s.command, s.args, { encoding: "utf8", ...opts, ...s.options });
     };
     return {

package/dist/which.js

@@ -76,10 +76,12 @@ 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)) {
+export function npmSpawn(args, os = platform(), resolveNpm = () => which("npm", os), proxyEnv = {}) {
+    const env = Object.keys(proxyEnv).length ? { env: { ...process.env, ...proxyEnv } } : {};
     if (!isWindows(os))
-        return { command: "npm", args: [...args], options: {} };
-    return agentSpawn(resolveNpm() ?? "npm.cmd", args, os);
+        return { command: "npm", args: [...args], options: { ...env } };
+    const s = agentSpawn(resolveNpm() ?? "npm.cmd", args, os);
+    return { ...s, options: { ...s.options, ...env } };
 }
 const cmdQuote = (a) => (/[\s"&|<>^()]/.test(a) || a === "" ? `"${a.replace(/"/g, '\\"')}"` : a);
 export function agentSpawn(binary, args, os = platform()) {

package/dist/worker.js

@@ -19,7 +19,11 @@ import { diagnoseRun, gitProbe } from "./run-failure.js";
 import { installedTools, preferredTool } from "./notifier.js";
 import { loadPersonas, matchPersona, personaByName, personaMatches, effectivePolicy, personaBrief, describePersona, } from "./persona.js";
 import { isContinuationFor, LIMITS, shouldDeferToHuman } from "./protocol.js";
-const git = (cwd, ...args) => execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+import { proxyEnvFor } from "./network.js";
+const git = (cwd, ...args) => {
+    const px = proxyEnvFor();
+    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], ...(Object.keys(px).length ? { env: { ...process.env, ...px } } : {}) }).trim();
+};
 const CLOCK_SKEW_MS = 5_000;
 const isRepo = (cwd) => {
     try {
@@ -583,7 +587,7 @@ export class Worker {
         let command;
         let agentId;
         let args;
-        let env = { ...process.env };
+        let env = { ...process.env, ...proxyEnvFor() };
         try {
             const runHome = this.runHome();
             agentId = this.opts.agentCmd ? "claude-code" : undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@join-pantheon/cli",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Let your coding agent collaborate directly with your teammates' agents — ask, agree an interface, and deliver, without a human relaying messages.",
   "type": "module",
   "bin": {
@@ -22,6 +22,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
+    "undici": "^7.29.1",
     "ws": "^8.18.0",
     "zod": "^3.23.8"
   },