unitbob 0.6.1 → 0.6.2

package/dist/proxyHint.js

@@ -0,0 +1,133 @@
+// What to say when a wire call fails on a machine that reaches the network
+// through a proxy.
+//
+// a2time, 2026-08-17. The Unitbob host was added to the sandbox's allowlist,
+// `curl` started answering 200, and the connector went on failing with 403 for
+// another round of debugging. Both facts were true at once: `curl` reads
+// `HTTPS_PROXY` from the environment, and Node's `fetch` does not, so the two
+// were not talking to the same place. Nothing in the failure said so — the
+// connector printed the status it got and left the reader to guess that the
+// variable sitting in their own environment was being ignored.
+//
+// This module is one sentence, and deliberately not a fix. Routing our requests
+// through the proxy ourselves would mean either a runtime dependency (this
+// package has none, on purpose — `npx unitbob` installs in a second) or
+// re-spawning ourselves with the variable set, which works on some Node versions
+// and silently does not on others. Naming the cause costs nothing and cannot
+// break a working machine.
+//
+// What it *can* do is send somebody to break one, which is why so much of this
+// file is about staying quiet. Measured on Node 25.2.1 against a CONNECT-logging
+// proxy: with `NODE_USE_ENV_PROXY=1` set, Node tunnels `http://127.0.0.1:19999`
+// through the proxy too — it does not exempt loopback. So this sentence, said to
+// somebody whose brain runs on `http://localhost:3000` and is merely down, would
+// talk them into breaking the one setup that works.
+// The variables that mean "this machine has a proxy", in the order they answer
+// for an `https://` server. The lowercase spellings are not a nicety: on Unix
+// they are the older convention and plenty of environments still set only those.
+const PROXY_VARS = ['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy'];
+// The first Node that can be told to use the environment's proxy for `fetch`.
+// Below it the variable is inert, so naming it would be a second round of the
+// exact confusion this file exists to end. Held at major-version granularity on
+// purpose: 18 and 20 plainly have nothing, 22 has it (a2time ran 22.22.3 and the
+// variable cured it), and pinning a patch number this file cannot verify would
+// be a guess dressed as a fact.
+const FIRST_NODE_WITH_ENV_PROXY = 22;
+// The sentence to add to a message that has already failed, or null when there
+// is nothing worth saying: no proxy configured, one Node is already using, or a
+// target that would not go through it anyway.
+//
+// `target` is the server the failed call was aimed at. It is required rather
+// than optional because every rule below that keeps this quiet needs it, and an
+// optional argument here would be a hint that is silently louder at half its
+// call sites.
+export function proxyHint(target, options = {}) {
+    const env = options.env ?? process.env;
+    const nodeVersion = options.nodeVersion ?? process.version;
+    if (nodeAlreadyUsesTheProxy(env))
+        return null;
+    const found = PROXY_VARS.map((name) => ({ name, value: (env[name] ?? '').trim() })).find((candidate) => candidate.value.length > 0);
+    if (!found)
+        return null;
+    if (!goesThroughTheProxy(target, env))
+        return null;
+    const shown = withoutCredentials(found.value);
+    const where = shown ? `\`${found.name}=${shown}\`` : `\`${found.name}\``;
+    const cause = `This machine reaches the network through a proxy (${where}), and Node does not send its own ` +
+        'requests through it unless it is told to — which is why `curl` can reach a host that this command cannot.';
+    return majorVersion(nodeVersion) < FIRST_NODE_WITH_ENV_PROXY
+        ? `${cause} This Node (${nodeVersion}) has no way to be told: run the command under Node ` +
+            `${FIRST_NODE_WITH_ENV_PROXY} or newer.`
+        : `${cause} Re-run the same command with \`NODE_USE_ENV_PROXY=1\` in front of it.`;
+}
+// Whether Node is already routing `fetch` through the environment's proxy, in
+// either of the two ways it can be asked to. The words that mean "off" are
+// spelled out rather than "anything but 0", so that `NODE_USE_ENV_PROXY=false`
+// does not quietly buy silence from a machine that needs the sentence.
+function nodeAlreadyUsesTheProxy(env) {
+    const flag = (env.NODE_USE_ENV_PROXY ?? '').trim().toLowerCase();
+    if (flag.length > 0 && flag !== '0' && flag !== 'false' && flag !== 'no')
+        return true;
+    return (env.NODE_OPTIONS ?? '').includes('--use-env-proxy');
+}
+// Whether this target would travel through the proxy at all — the two exemptions
+// Node itself applies, checked here so the advice matches what setting the
+// variable would actually do.
+//
+// `NO_PROXY` is matched the way every tool that reads it matches: `*` exempts
+// everything, and an entry is a host or a domain suffix, with an optional
+// leading dot that means the same thing.
+function goesThroughTheProxy(target, env) {
+    let host;
+    try {
+        host = new URL(target).hostname.toLowerCase();
+    }
+    catch {
+        // A server we cannot parse is one we cannot reason about. Silence is the
+        // safe half of that, since the message it would join is already printed.
+        return false;
+    }
+    // Measured, not assumed: Node tunnels loopback through the proxy like anything
+    // else. Nobody's proxy has a route back to their own machine, so this is the
+    // one place where following the advice makes a working setup fail.
+    if (host === 'localhost' || host === '::1' || host === '[::1]' || /^127\./.test(host))
+        return false;
+    const noProxy = (env.NO_PROXY ?? env.no_proxy ?? '').trim();
+    if (noProxy === '*')
+        return false;
+    return !noProxy
+        .split(',')
+        .map((entry) => entry.trim().toLowerCase().replace(/^\./, ''))
+        .filter((entry) => entry.length > 0)
+        .some((entry) => host === entry || host.endsWith(`.${entry}`));
+}
+// The major of a `v25.2.1`, or 0 when it is not a version string we can read —
+// which reports "too old" and sends nobody to set a variable that may be inert.
+function majorVersion(version) {
+    const major = /^v?(\d+)\./.exec(version.trim());
+    return major ? Number(major[1]) : 0;
+}
+// The proxy as it is safe to print: the address, never the credentials.
+//
+// A proxy URL is one of the last places a password is still written in plain
+// text, and this sentence ends up in terminals, transcripts and bug reports. The
+// address is the part that helps somebody recognise which proxy this is; the
+// credentials never are.
+//
+// Null when the value does not parse as a URL. Then it still means "this machine
+// has a proxy" — worth saying — but nothing in it can be echoed, because a
+// password cannot be found in a string whose shape we could not read.
+function withoutCredentials(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return null;
+    }
+    if (url.username.length === 0 && url.password.length === 0)
+        return value;
+    url.username = '';
+    url.password = '';
+    return url.toString();
+}

package/dist/wire.js

@@ -1,3 +1,4 @@
+import { proxyHint } from "./proxyHint.js";
 // Raised when the server cannot be reached or answers with an error status.
 // Verbs surface its message and exit non-zero; they never fabricate a result.
 //
@@ -32,8 +33,8 @@ export async function registerRepo(server, name) {
         });
     }
     catch (err) {
-        throw new WireError(`Cannot reach the Unitbob server at ${server} (${err.message}). ` +
-            'Check that the server is running.');
+        throw new WireError(withProxyHint(`Cannot reach the Unitbob server at ${server} (${err.message}). ` +
+            'Check that the server is running.', server));
     }
     if (!res.ok) {
         let detail = '';
@@ -43,7 +44,7 @@ export async function registerRepo(server, name) {
         catch {
             // ignore — the status alone is actionable enough
         }
-        throw new WireError(`POST ${url} failed: ${res.status} ${res.statusText}${detail ? ` — ${detail}` : ''}`);
+        throw new WireError(statusRefusal(`POST ${url}`, res, detail, server));
     }
     const payload = (await res.json());
     if (typeof payload.id !== 'number' || !Number.isInteger(payload.id)) {
@@ -229,9 +230,9 @@ export class Wire {
             });
         }
         catch (err) {
-            throw new WireError(`Cannot reach the Unitbob server at ${this.config.server} ` +
+            throw new WireError(withProxyHint(`Cannot reach the Unitbob server at ${this.config.server} ` +
                 `(${err.message}). Check that the server is running and that ` +
-                `"server" in .unitbob.json is correct.`, { unreachable: true });
+                `"server" in .unitbob.json is correct.`, this.config.server), { unreachable: true });
         }
     }
     async ensureOk(res, what) {
@@ -252,6 +253,44 @@ export class Wire {
         catch {
             // ignore — the status alone is actionable enough
         }
-        throw new WireError(`${what} failed: ${res.status} ${res.statusText}${detail ? ` — ${detail}` : ''}`);
+        throw new WireError(statusRefusal(what, res, detail, this.config.server));
     }
 }
+// The two statuses that prove somebody else answered.
+//
+// a2time, 2026-08-17: a sandbox refused the host with `403 Forbidden — Host not
+// in allowlist`, and the run read the 403 as Unitbob's own verdict. It cannot be
+// one. The brain answers 404 even to a caller holding the wrong token — a 403
+// would confirm the project exists — so 403 never comes from it, and 407 is a
+// proxy demanding credentials, which the brain has never heard of.
+const NOT_FROM_THE_BRAIN = {
+    403: 'The Unitbob server never answers 403 — it answers 404 even to a caller holding the wrong token — so ' +
+        'this was written by something between this machine and it: a proxy, a gateway, or a sandbox that has ' +
+        'not been told this host is allowed.',
+    407: 'A 407 is a proxy asking this machine to authenticate. It did not come from the Unitbob server.',
+};
+// One failing status, written the same way wherever it was collected.
+//
+// Registration and every tokened call compose this identically on purpose: they
+// used to disagree, and the disagreement was invisible — a 422 from `register`
+// carried network advice while the same 422 from a repo call did not, so which
+// sentence a person got depended on which endpoint they happened to hit.
+function statusRefusal(what, res, detail, server) {
+    const line = `${what} failed: ${res.status} ${res.statusText}${detail ? ` — ${detail}` : ''}`;
+    // A status the brain cannot have written. Relaying it as it stands reads as
+    // "Unitbob refused you" and sends the reader to their token; the refusal came
+    // from the network in between, and only they can clear it. Every other status
+    // is the server's own verdict and keeps the message it has always had — a
+    // proxy sentence on a 422 sends somebody to their network settings over a
+    // validation error.
+    const notOurs = NOT_FROM_THE_BRAIN[res.status];
+    return notOurs ? withProxyHint(`${line}\n${notOurs}`, server) : line;
+}
+// Every wire failure that the network could explain ends with the same sentence
+// about it — see `proxyHint`, which decides whether there is one to say. Here
+// rather than inside `WireError` so that a message composed for some other
+// reason never picks it up by accident.
+function withProxyHint(message, server) {
+    const hint = proxyHint(server);
+    return hint ? `${message}\n${hint}` : message;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitbob",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "Unitbob connector — thin local hands for the Unitbob Rails brain. Owns no domain logic: it runs tools, relays bytes over the wire, and prints what the server returns.",
   "type": "module",
   "bin": {

package/plugin/codex/agents/suite-repair-worker.toml

@@ -21,7 +21,7 @@ markers, or paths. Do not edit production code, host-owned shared files, the
 connector-owned harness, or another slice.
 
 After every owned edit, run
-`npx -y --loglevel=error unitbob@0.6.1 run-local <branch>` and inspect the machine
+`npx -y --loglevel=error unitbob@0.6.2 run-local <branch>` and inspect the machine
 report. Look only at examples or scenarios matching your owned paths or case
 markers. Do not require a green exit code from the whole branch: foreign failures
 and an already-confirmed product red do not widen your scope. Repeat the bounded