@tiens.nguyen/gu-cli 1.0.686

package/poll-errors.mjs

@@ -0,0 +1,141 @@
+// Friendly poll-failure reporting for the worker daemon.
+//
+// The poll loop runs every ~500ms, so a failure that lasts (an API outage, a rotated key)
+// used to fill ~/.gonext/worker.log with THOUSANDS of identical 4-line stack traces — which
+// says nothing about what's wrong or whether the user can fix it. This turns each failure
+// into ONE plain sentence plus an actionable hint, and collapses repeats of the same failure
+// into a periodic "still failing" line.
+//
+// Kept in its own module (not inside gu-cli.mjs, which starts the daemon on import) so
+// the classification is unit-testable.
+
+/** How often to re-log an UNCHANGED failure while it persists. */
+export const REPEAT_MS = 60_000;
+
+/**
+ * Classify a poll failure. Pure — takes the error, returns what to say about it.
+ * `key` identifies the KIND of failure, so repeats can be collapsed;
+ * `line` is the one-sentence description; `hint` is what the user can do about it;
+ * `unexpected` marks errors we have no explanation for (those keep their stack trace).
+ */
+export function describePollError(err, { apiBase = "the API" } = {}) {
+  const status = Number(err?.status) || 0;
+  const body = String(err?.body ?? "");
+  const msg = String(err?.message ?? err ?? "");
+
+  // The API reached its auth middleware but the worker_keys lookup THREW — i.e. the API is
+  // up and the key never even got checked. Worth its own message: the natural reading of
+  // "worker key ... failed" is "my key is bad", and that is exactly what it is NOT.
+  if (/worker key lookup failed/i.test(body)) {
+    return {
+      key: "api-db-down",
+      line: `${apiBase} is up but cannot reach its database, so it can't verify ANY worker key.`,
+      hint:
+        "Nothing is wrong with this machine or your key — check the API's MongoDB " +
+        "(cluster paused? IP allow-list? rotated credentials?) and the API logs. Retrying.",
+    };
+  }
+  if (status === 401) {
+    return {
+      key: "auth-missing",
+      line: "this worker isn't sending a key, so the API rejected it.",
+      hint: "Run `gu-cli login` (or `gu-cli set <workerKey>`) to configure this machine.",
+    };
+  }
+  if (status === 403) {
+    return {
+      key: "auth-invalid",
+      line: "the API rejected this worker key — it isn't registered to any account.",
+      hint: "The key was probably rotated or the account reset. Run `gu-cli login` to pair this machine again.",
+    };
+  }
+  if (status === 404) {
+    return {
+      key: "api-404",
+      line: `${apiBase} has no /api/worker/jobs/next endpoint (404).`,
+      hint: "The API base URL may point at the wrong deployment — check GONEXT_API_BASE in ~/.gonext/worker.env.",
+    };
+  }
+  if (status >= 500) {
+    return {
+      key: `api-${status}`,
+      line: `${apiBase} returned ${status}.`,
+      hint: `Server-side problem, not this machine. Retrying.${body ? ` API said: ${trim(body)}` : ""}`,
+    };
+  }
+  if (status) {
+    return {
+      key: `http-${status}`,
+      line: `${apiBase} returned ${status}.`,
+      hint: body ? `API said: ${trim(body)}` : "",
+    };
+  }
+  // No HTTP status ⇒ the request never completed: DNS, offline, TLS, timeout.
+  if (/fetch failed|ECONN|ENOTFOUND|ETIMEDOUT|EAI_AGAIN|socket hang up|network|terminated|abort/i.test(msg)) {
+    return {
+      key: "network",
+      line: `can't reach ${apiBase}.`,
+      hint: "Check your internet connection and that the API base URL is right. Retrying.",
+    };
+  }
+  return { key: `unexpected:${msg.slice(0, 60)}`, line: msg || String(err), hint: "", unexpected: true };
+}
+
+function trim(s) {
+  const one = String(s).replace(/\s+/g, " ").trim();
+  return one.length > 160 ? `${one.slice(0, 159)}…` : one;
+}
+
+/**
+ * Stateful reporter: prints the first occurrence in full, then stays quiet until the same
+ * failure has been going for REPEAT_MS, and announces recovery with how long it was down.
+ * `log`/`err` are injectable so tests can capture the output.
+ */
+export function createPollErrorReporter({
+  apiBase = "the API",
+  log = console.log,
+  err = console.error,
+  now = () => Date.now(),
+  repeatMs = REPEAT_MS,
+} = {}) {
+  let key = "";
+  let streak = 0;
+  let since = 0;
+  let loggedAt = 0;
+  const tag = "[gu-worker]";
+
+  return {
+    /** Report a failed poll. */
+    fail(e) {
+      const d = describePollError(e, { apiBase });
+      const t = now();
+      if (d.key === key) {
+        streak += 1;
+        if (t - loggedAt < repeatMs) return; // same failure, already explained
+        loggedAt = t;
+        err(`${tag} still failing — ${d.line} (${streak}× over ${Math.round((t - since) / 1000)}s)`);
+        return;
+      }
+      key = d.key;
+      streak = 1;
+      since = t;
+      loggedAt = t;
+      err(`${tag} ⚠ ${d.line}`);
+      if (d.hint) err(`${tag}   ${d.hint}`);
+      // Only something we can't explain is worth a stack trace.
+      if (d.unexpected) err(e);
+    },
+    /** Report a successful poll — announces recovery only if we were failing. */
+    ok() {
+      if (!key) return;
+      const secs = Math.round((now() - since) / 1000);
+      log(`${tag} ✓ recovered — polling again after ${streak} failure(s) over ${secs}s.`);
+      key = "";
+      streak = 0;
+    },
+    /** Current failure key ("" when healthy) — exposed for tests/diagnostics. */
+    get failingSince() {
+      return key ? since : 0;
+    },
+  };
+}

package/proxy-command.mjs

@@ -0,0 +1,165 @@
+/**
+ * `/proxy` — the whole lifecycle, as decisions rather than IO (task #160).
+ *
+ * SEPARATE FROM THE REPL BECAUSE THE REPL IS UNTESTABLE. Everything here is a pure function of
+ * its arguments: what the user typed, what is stored, what the network answered. The REPL keeps
+ * only the parts that genuinely need a terminal — asking, masking the password, printing. That
+ * split is what lets the interesting cases (a wrong password, a proxy that is up but blocks the
+ * model host, a machine with no models configured yet) be tested without any of them being true.
+ *
+ * A PROXY THAT CAN ONLY BE ADDED IS USELESS the first time a password rotates, so every verb
+ * exists: show, set, on, off, clear. `off` deliberately keeps the credentials — a proxy that has
+ * to be retyped whenever it is switched off is one people leave on, which is exactly the state
+ * that breaks a laptop the moment it leaves the office.
+ */
+import {
+  normalizeProxy,
+  isUsableProxy,
+  describeProxy,
+  modelOrigins,
+  classifyProxyFailure,
+  proxyFailureAdvice,
+} from "./proxy-config.mjs";
+
+/**
+ * What did the user mean?
+ *
+ * A bare `/proxy` SHOWS rather than starting an interrogation: the commonest reason to type it
+ * is to find out what is currently set, and a command that immediately demands a hostname is one
+ * people stop typing. Setting is an explicit verb.
+ */
+export function parseProxyCommand(line) {
+  const parts = String(line ?? "").trim().split(/\s+/).filter(Boolean);
+  if (parts[0] !== "/proxy") return { action: "none" };
+  const verb = (parts[1] ?? "").toLowerCase();
+  if (!verb || verb === "show" || verb === "status") return { action: "show" };
+  if (verb === "set" || verb === "add" || verb === "edit") return { action: "set" };
+  if (verb === "on" || verb === "enable") return { action: "on" };
+  if (verb === "off" || verb === "disable") return { action: "off" };
+  if (verb === "clear" || verb === "remove" || verb === "forget") return { action: "clear" };
+  if (verb === "test" || verb === "check") return { action: "test" };
+  return { action: "unknown", verb };
+}
+
+/** The one-line help shown for an unrecognised verb — every verb, so nothing is undiscoverable. */
+export const PROXY_USAGE =
+  "/proxy [show|set|on|off|clear|test] — show is the default";
+
+/**
+ * Is this a usable host/port before anything is stored?
+ *
+ * Rejecting at the prompt matters more than it looks: a bad port stored now fails much later, in
+ * the middle of a turn, as a connection error that names neither the proxy nor the typo.
+ * Returns "" when fine, else the reason.
+ */
+export function validateHostPort({ host, port }) {
+  const h = String(host ?? "").trim();
+  if (!h) return "a proxy needs a host";
+  if (/^https?:\/\//i.test(h)) return "just the host, without http:// — the scheme is asked separately";
+  if (/\s/.test(h)) return "a host cannot contain spaces";
+  if (h.includes("@")) return "credentials go in the username/password prompts, not the host";
+  const p = Number.parseInt(String(port ?? "").trim(), 10);
+  if (!Number.isInteger(p) || p <= 0 || p > 65535) return "the port must be a number between 1 and 65535";
+  return "";
+}
+
+/**
+ * What `/proxy` prints when asked to show itself.
+ *
+ * Plain strings, no colour — the caller owns presentation, and a test that asserts on ANSI is
+ * asserting on the wrong layer. It names WHICH endpoints are covered, because the scope is an
+ * allowlist and "the proxy is on" is not enough to predict what happens: someone debugging a
+ * blocked `npm install` needs to see that this setting has nothing to do with it.
+ */
+export function proxySummary(proxy, settings) {
+  const p = normalizeProxy(proxy);
+  const lines = [];
+  if (!p.host) {
+    lines.push("no proxy configured — model calls go out directly");
+    lines.push("`/proxy set` to add one");
+    return lines;
+  }
+  lines.push(`proxy ${describeProxy(p)}`);
+  const origins = modelOrigins(settings).filter((o) => !/^https?:\/\/(localhost|127\.|\[::1\])/.test(o));
+  if (!isUsableProxy(p)) {
+    lines.push(
+      p.enabled
+        ? "incomplete — it has no usable host/port, so nothing is being routed"
+        : "disabled — model calls go out directly (`/proxy on` to use it again)"
+    );
+  } else if (origins.length === 0) {
+    // Enabled, complete, and doing nothing — worth saying, or it looks broken later.
+    lines.push("enabled, but no REMOTE model is configured, so there is nothing to route");
+  } else {
+    lines.push(`routing ${origins.length} model endpoint(s): ${origins.join(", ")}`);
+  }
+  lines.push("local calls (127.0.0.1, localhost) always go direct");
+  return lines;
+}
+
+/** The startup-banner row, or "" when there is nothing worth a line. Host only — never the password. */
+export function bannerProxyRow(proxy) {
+  const p = normalizeProxy(proxy);
+  if (!isUsableProxy(p)) return "";
+  return `${p.host}:${p.port}${p.username ? ` (as ${p.username})` : ""} · model calls only`;
+}
+
+/**
+ * Reach a configured model endpoint THROUGH the proxy and report what happened.
+ *
+ * AT THE PROMPT, NOT AT FIRST USE. Credentials that are merely stored fail later, inside a turn,
+ * as a network error the model cannot act on and the user cannot read. Failing here — while they
+ * still have the password in their head — is the difference between a typo and an outage.
+ *
+ * The verdicts are separated because they imply DIFFERENT fixes: retype the password, check the
+ * proxy is up, or talk to whoever runs it about the model host. A single "network error" sends
+ * the user nowhere.
+ */
+export async function verifyProxy({ proxy, settings, fetchImpl, timeoutMs = 15000 } = {}) {
+  const p = normalizeProxy(proxy);
+  if (!isUsableProxy(p)) {
+    return { ok: false, kind: "not-configured", detail: "no usable proxy to test" };
+  }
+  const target = modelOrigins(settings).find(
+    (o) => !/^https?:\/\/(localhost|127\.|0\.0\.0\.0|\[::1\])/.test(o)
+  );
+  if (!target) {
+    // Not a failure OF the proxy — there is simply nothing it would carry. Saying "ok" here
+    // would be a lie, and saying "failed" would send someone hunting a working proxy.
+    return {
+      ok: false,
+      kind: "no-models",
+      detail: "no remote model is configured, so there is nothing to test the proxy against",
+    };
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    // GET the endpoint root: every OpenAI-compatible server answers SOMETHING there, and we only
+    // care whether bytes crossed the proxy — a 404 from the model host is a complete success for
+    // this question, which is why the classifier treats any 2xx/3xx/4xx-that-is-not-407 as ok.
+    const res = await fetchImpl(
+      `${target}/v1/models`,
+      { method: "GET", signal: controller.signal },
+      { proxy: p, settings }
+    );
+    const kind = res.status === 407 ? "proxy-auth" : classifyProxyFailure({ status: res.status });
+    // A 404 or 401 FROM THE MODEL HOST means the tunnel worked — that is what is being tested.
+    const reached = res.status !== 407 && !(res.status === 403 || res.status === 502 || res.status === 503);
+    return {
+      ok: reached,
+      kind: reached ? "ok" : kind,
+      target,
+      status: res.status,
+      detail: reached
+        ? `reached ${target} through the proxy (HTTP ${res.status})`
+        : proxyFailureAdvice(kind, p),
+    };
+  } catch (err) {
+    const kind = classifyProxyFailure({ code: err?.code || "", message: err?.message || "" });
+    return { ok: false, kind, target, detail: proxyFailureAdvice(kind, p) };
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/proxy-config.mjs

@@ -0,0 +1,255 @@
+/**
+ * The outbound proxy: which calls go through it, how it is addressed, and how it is described
+ * without leaking the password (task #160).
+ *
+ * WHY A PROXY AT ALL. Client Expert moves the API and the database onto the user's machine but
+ * not the models — the banner says "client expert (API + database here · models remote)". So the
+ * only traffic still leaving the machine is exactly what a corporate network blocks: the three
+ * configured models. Without this, Client Expert cannot run on such a network, and it fails
+ * looking like a dead model rather than a blocked one.
+ *
+ * AN ALLOWLIST, NOT A BYPASS LIST — the single most important decision here (user, 2026-08-09:
+ * "only proxy if proxy is enable and after that proxy all the request to agent model and agent
+ * code model", then "yes, proxy the embed model too, so 3 models"). The obvious build proxies
+ * everything and subtracts loopback; this one proxies only the three configured model URLs and
+ * leaves everything else alone. That is safer by construction: a URL nobody thought about goes
+ * direct, which is today's behaviour, so the worst case of a mistake here is "the proxy did not
+ * apply" rather than "the terminal stopped working".
+ *
+ * THE DECISION FOLLOWS THE URL, NOT THE ROLE AND NOT THE MODE. The same code path serves a local
+ * and a remote model; only the configured host differs. So nothing here asks "is this the embed
+ * model" or "are we in Client Expert" — it asks "is this resolved URL one of the configured
+ * model endpoints, and is it actually remote". A user who points the embed model back at a local
+ * Ollama stops being proxied automatically, and a hosted-mode user behind a corporate proxy is
+ * covered without a mode change (#154's "configuration, not a second code path").
+ *
+ * PURE. No sockets, no dispatcher, no environment. The transports that consume these decisions
+ * live at the call sites — an httpx/OpenAI transport in Python, an undici dispatcher in Node —
+ * because those differ per stack while the decision must not.
+ */
+
+/**
+ * A proxy the user has configured. `enabled` is separate from "is it filled in" on purpose:
+ * turning the proxy off must not throw the credentials away, or every toggle costs a retype.
+ */
+export function normalizeProxy(raw) {
+  // `raw = {}` as a default parameter is NOT enough: a default fills only `undefined`, so an
+  // explicit null — which is exactly what "no proxy configured" looks like coming out of a
+  // loader or a settings row — reached the property reads and threw. That crash would take down
+  // the model call it was meant to leave alone, on the machines least involved with proxies.
+  const input = raw || {};
+  const host = String(input.host ?? "").trim();
+  const rawPort = input.port;
+  const port = Number.parseInt(String(rawPort ?? "").trim(), 10);
+  return {
+    enabled: input.enabled === true,
+    host,
+    // 0 is not a usable port and NaN is not a value worth carrying forward; both become null so
+    // isUsableProxy() has one thing to check rather than three.
+    port: Number.isInteger(port) && port > 0 && port <= 65535 ? port : null,
+    username: String(input.username ?? "").trim(),
+    password: String(input.password ?? ""),
+    // http by default: a corporate proxy is almost always plain HTTP even when the traffic it
+    // carries is HTTPS (the client sends CONNECT). Assuming https here would fail on most.
+    protocol: input.protocol === "https" ? "https" : "http",
+  };
+}
+
+/** Enabled AND complete enough to dial. An enabled proxy with no host must not silently do nothing. */
+export function isUsableProxy(proxy) {
+  const p = normalizeProxy(proxy);
+  return p.enabled && p.host.length > 0 && p.port !== null;
+}
+
+/**
+ * The dial string for the transport.
+ *
+ * Credentials are percent-encoded because a password containing @ : / or # would otherwise
+ * reshape the URL — a password ending in "@" would make the parser read the wrong host, which
+ * fails as a DNS error and sends the user looking in the wrong place entirely.
+ *
+ * Returns "" when the proxy is not usable, so a caller that forgets to check gets no proxy
+ * rather than a malformed one.
+ */
+export function proxyUrl(proxy) {
+  const p = normalizeProxy(proxy);
+  if (!isUsableProxy(p)) return "";
+  const auth = p.username
+    ? `${encodeURIComponent(p.username)}:${encodeURIComponent(p.password)}@`
+    : "";
+  return `${p.protocol}://${auth}${p.host}:${p.port}`;
+}
+
+/**
+ * The whole 127.0.0.0/8 range, as an ADDRESS rather than a prefix.
+ *
+ * `/^127\./` was the first version and it is wrong in a way worth remembering: it matches the
+ * HOSTNAME "127.0.0.1.evil.com", which is a perfectly ordinary remote domain. Anyone who can
+ * name a host that way could opt themselves out of the proxy, and more mundanely a real host in
+ * a nip.io-style scheme would silently skip it. Each octet is range-checked so "127.999.0.1" —
+ * not an address — is not treated as one either.
+ */
+const IPV4_LOOPBACK = /^127(?:\.(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/;
+
+/** Loopback: never remote, so never proxied even if a model is configured there. */
+export function isLoopbackUrl(url) {
+  try {
+    let h = new URL(url).hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    // IPv4-mapped IPv6 (::ffff:127.0.0.1) is the same machine by another spelling, and undici
+    // will happily connect to it — so it has to be recognised, not just look unfamiliar.
+    //
+    // AND IT ARRIVES IN HEX. `new URL("http://[::ffff:127.0.0.1]/")` normalises the hostname to
+    // "[::ffff:7f00:1]", so a string comparison against the dotted form matches nothing — the
+    // two 16-bit groups have to be expanded back into an address before the range test.
+    const mapped = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(h);
+    if (mapped) {
+      const n = (parseInt(mapped[1], 16) << 16) | parseInt(mapped[2], 16);
+      h = [(n >>> 24) & 255, (n >>> 16) & 255, (n >>> 8) & 255, n & 255].join(".");
+    } else {
+      h = h.replace(/^::ffff:/, "");
+    }
+    return (
+      h === "localhost" ||
+      h === "::1" ||
+      h === "0.0.0.0" ||
+      h === "::" ||
+      // A real subdomain of the reserved .localhost TLD (RFC 6761), not merely a name ENDING in
+      // the text — "localhost.evil.com" is remote and must stay proxied.
+      h.endsWith(".localhost") ||
+      IPV4_LOOPBACK.test(h)
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The origin (scheme + host + port) of a URL, which is what "the same endpoint" means here.
+ *
+ * A configured model is https://ollama1.gomarsic.cc/v1 while the actual call is
+ * https://ollama1.gomarsic.cc/v1/chat/completions — comparing full URLs would match neither, and
+ * comparing hostnames alone would proxy a DIFFERENT service that happens to share the host.
+ * Origin is the level that means "this endpoint", and URL normalizes the default port for us.
+ */
+export function originOf(url) {
+  try {
+    return new URL(url).origin.toLowerCase();
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * The three model endpoints, read from the settings row rather than hardcoded — the user can
+ * change any of them at any time (/model, the web app), and a hardcoded ollama1.gomarsic.cc
+ * would keep proxying an endpoint they have already moved away from.
+ */
+export function modelOrigins(settings = {}) {
+  const s = settings || {};
+  const urls = [
+    s.agentModelUrl,
+    s.agentCodingModelUrl,
+    s.ragEmbedUrl,
+    // THE FALLBACKS COUNT TOO. resolveConfiguredModels() (model-doctor.mjs) uses agentModelUrl
+    // when set and otherwise falls back to the account's MLX base URL — so on a machine that
+    // configures the agent that way, reading only the three explicit fields would leave the
+    // agent model OFF the allowlist and unproxied, which on a restricted network is the exact
+    // failure this feature exists to prevent. The third fallback in that chain is a port on
+    // 127.0.0.1, which is loopback and excluded anyway, so it needs nothing here.
+    s.mlxOpenAiBaseUrl,
+    s.hosts?.[0]?.mlxOpenAiBaseUrl,
+  ];
+  return [...new Set(urls.map(originOf).filter(Boolean))];
+}
+
+/**
+ * THE DECISION. Does this specific request go through the proxy?
+ *
+ * Three conditions, and all of them are the point:
+ *   · the proxy is enabled and usable — "only proxy if proxy is enable" is the first clause of
+ *     the requirement and the easiest to lose by installing a dispatcher and forgetting it;
+ *   · the URL is one of the configured model endpoints — the allowlist;
+ *   · the URL is not loopback — a locally served model needs no proxy, and the local API at
+ *     127.0.0.1:4100 must never be routed through a corporate proxy, which would break every
+ *     turn while looking like the proxy is down.
+ */
+export function shouldProxy(url, { proxy, settings } = {}) {
+  if (!isUsableProxy(proxy)) return false;
+  if (isLoopbackUrl(url)) return false;
+  // No guard against an empty origin here, deliberately: modelOrigins() drops unparseable URLs,
+  // so "" can never be IN the allowlist and an unparseable request URL therefore cannot match.
+  // An extra `origin !== ""` check reads as prudent but is unreachable — a branch no test can
+  // reach is a branch nobody can trust, so the invariant is pinned in modelOrigins instead
+  // ("a malformed configured URL is ignored rather than matching everything").
+  return modelOrigins(settings).includes(originOf(url));
+}
+
+/**
+ * The proxy as it may be shown to a human — host, port, and WHETHER it authenticates, never the
+ * password and never a credential-bearing URL.
+ *
+ * Formatting is centralised here rather than trusting each call site to remember, because the
+ * leak this prevents is the easy one to ship: proxyUrl() embeds user:pass@, and that string
+ * otherwise reaches exception text, `gu status`, a doctor dump and the worker log verbatim.
+ */
+export function describeProxy(proxy) {
+  const p = normalizeProxy(proxy);
+  if (!p.host) return "not configured";
+  const where = `${p.host}${p.port ? `:${p.port}` : ""}`;
+  const auth = p.username ? ` (as ${p.username})` : "";
+  return `${p.enabled ? "" : "disabled — "}${where}${auth}`;
+}
+
+/**
+ * Strip credentials out of any URL inside an arbitrary string.
+ *
+ * A LAST LINE OF DEFENCE, not the primary one: exception text from a transport routinely
+ * contains the dial URL, and that text flows into logs and into the model's context. Applied to
+ * anything about to be printed or stored. The password is replaced rather than removed so the
+ * reader can still see that credentials WERE configured — "the proxy has no password" and "the
+ * password was redacted" are different diagnoses.
+ */
+export function redactSecrets(text) {
+  return String(text ?? "").replace(
+    /\b([a-z][a-z0-9+.-]*:\/\/)([^/\s:@]+)(?::([^/\s@]*))?@/gi,
+    (_m, scheme, user, pass) => `${scheme}${user}${pass === undefined ? "" : ":***"}@`
+  );
+}
+
+/**
+ * What went wrong, in terms that imply different fixes.
+ *
+ * The point of separating these is that "retype your password", "the proxy is down" and "the
+ * proxy works but will not let you reach this host" send the user to three different places, and
+ * a single "network error" sends them nowhere. 407 in particular is unambiguous and must never
+ * be reported as the model being offline — which is how it looks if this is skipped.
+ */
+export function classifyProxyFailure({ status = 0, code = "", message = "" } = {}) {
+  const text = `${code} ${message}`.toLowerCase();
+  if (status === 407) return "proxy-auth";
+  // A CONNECT refused BY the proxy is the proxy talking; a refused connection TO the proxy is the
+  // proxy being down. Both surface as ECONNREFUSED, so the status code is what separates them.
+  if (status === 403 || status === 502 || status === 503) return "destination-blocked";
+  if (/econnrefused|ehostunreach|enetunreach|enotfound|eai_again|timeout|etimedout/.test(text)) {
+    return "proxy-unreachable";
+  }
+  if (status >= 200 && status < 400) return "ok";
+  return "unknown";
+}
+
+/** One line the user can act on, per failure kind. A diagnosis without a next move is just noise. */
+export function proxyFailureAdvice(kind, proxy) {
+  const where = describeProxy(proxy);
+  switch (kind) {
+    case "proxy-auth":
+      return `the proxy rejected the credentials (407) — check the username and password with \`/proxy\` (${where})`;
+    case "proxy-unreachable":
+      return `could not reach the proxy itself at ${where} — check the host and port, and that it is running`;
+    case "destination-blocked":
+      return `the proxy is reachable but refused to connect to the model endpoint — the host may not be allowed through ${where}`;
+    case "ok":
+      return `the proxy works — model calls will go through ${where}`;
+    default:
+      return `the proxy check failed for an unrecognised reason (${where})`;
+  }
+}