unitbob 0.6.1 → 0.6.3

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/runner/provision.js

@@ -295,6 +295,92 @@ async function provisionVitest(projectRoot, deps) {
 // project's own bundler settings are never touched, and no other bundler
 // invocation carries this.
 const UNFROZEN_SIDECAR = { BUNDLE_FROZEN: 'false', BUNDLE_DEPLOYMENT: 'false' };
+// One gem line for the sidecar, asked for only if the project has not asked for
+// it already.
+//
+// `eval_gemfile` runs the project's own Gemfile inside *this* Dsl object — that
+// is the whole point of it, and it is also the trap. Every `gem` line we add
+// afterwards lands in the same dependency list the project just filled, so a gem
+// the project already names is declared twice, and bundler's rules for that are
+// strict: identical requirements warn, differing ones raise `GemfileError` while
+// the Gemfile is still being parsed.
+//
+// Measured on bundler 2.4.22 and 4.0.1 after A2.Time (Rails 5.0, Ruby 2.7.8)
+// could not generate a behavioral suite at all, 2026-08-20. It pins
+// `webmock "~> 3.23"`; we asked for `webmock (>= 0)`:
+//
+//   You cannot specify the same gem twice with different version requirements.
+//   You specified: webmock (~> 3.23) and webmock (>= 0). Bundler cannot continue.
+//
+// Parsing fails before resolution begins, so there is no lock and no versions to
+// negotiate — and `suite-prepare` rewrote the same conflicting file on every
+// retry, which left the vibecoder with nothing to patch either. The comment that
+// used to sit on the webmock line had this exactly backwards: it promised the
+// project's own version would win "because bundler starts from the project's own
+// resolution". True of resolution. Parsing never reached it.
+//
+// `dependencies` is Bundler::Dsl's own reader and the Gemfile is instance_eval'd
+// on the Dsl, so the list is in scope and already holds everything the project
+// declared. Checked in the dsl.rb of 2.1.4, 2.2.33, 2.3.27, 2.4.22 and 4.0.1 —
+// 2.1.4 because it is what Ruby 2.7.8 ships, and Ruby 2.7.8 is what the
+// application that found this bug runs.
+//
+// What we would have added is dropped rather than merged, version and all: a
+// project pinning `cucumber "~> 8.0"` gets a sidecar on cucumber 8 instead of a
+// hard failure. The suite then runs on the version that project already trusts,
+// which is the bargain the rest of this sidecar strikes anyway — it inherits the
+// project's Gemfile precisely so the two cannot drift apart.
+//
+// One thing this does give up, measured on 2.1.4 and 4.0.1 rather than assumed.
+// Where the requirements happened to match, bundler used to keep *both*
+// declarations — the project's and ours — so a gem the project had confined to
+// `group :test` also arrived ungrouped through us, and no `BUNDLE_WITHOUT` could
+// drop it. Skipping our line leaves only the project's, groups and all. That is
+// the honest arrangement, and it is not silent: the World probe of spec 35-1
+// asserts against a live `WebMock::NetConnectNotAllowedError`, so a webmock that
+// did not come along stops `suite-prepare` with a fixable probe failure instead
+// of letting a suite run with the block it advertises quietly missing.
+function gemLineUnlessTheProjectHasIt(name, requirement) {
+    const pin = requirement ? `, "${requirement}"` : '';
+    return `gem "${name}"${pin}, require: false unless dependencies.any? { |d| d.name == "${name}" }\n`;
+}
+const BUNDLER_OUTPUT_LINES = 20;
+const BUNDLER_OUTPUT_CHARS = 2000;
+// What bundler said, kept instead of thrown away. Reads as the sentence after
+// "Bundler failed to ...", whichever of its three shapes it takes.
+//
+// Both Ruby sidecars used to capture `result` and then return a fixed line, so a
+// provisioning failure reached the vibecoder as "Bundler failed to provision ..."
+// and nothing else. On A2.Time that hid the `GemfileError` above completely: the
+// run reported a blocked behavioral branch, the reason was already in this
+// process's memory, and it still took a round trip through the user — run bundler
+// by hand, paste the output — to find out what it was. An error we have been told
+// is not one to make somebody fetch again.
+//
+// The tail, because bundler puts the reason last on failures long enough to
+// scroll (a resolution conflict prints its whole search first), and a Gemfile
+// that will not parse is short enough that the tail is all of it. Not
+// `installerComplaint`, which is next door and does the opposite on purpose: it
+// picks the single line pip labelled an error out of hundreds of lines of
+// compiler noise. Bundler's verdict carries no such label — the one that matters
+// here opens with `[!]` and runs over three lines — so filtering by line would
+// drop exactly the sentence worth keeping.
+function whatBundlerSaid(result) {
+    const text = [result.stdout, result.stderr].map((part) => part.trim()).filter(Boolean).join('\n');
+    // A null code is a process this connector killed, not one that decided
+    // anything. No number is named with it: the two callers run under different
+    // budgets — `provisionRspec` asks for `DEPENDENCY_INSTALL_TIMEOUT_MS`,
+    // `provisionRuby` takes the `PROVISION_TIMEOUT_MS` default — and a message
+    // that states the wrong one is worse than a message that states none.
+    if (!text) {
+        return result.code === null
+            ? 'It said nothing: it was stopped before it could, having run past its timeout or lost the place it was running in.'
+            : `It said nothing, and exited ${result.code}.`;
+    }
+    const lines = text.split('\n');
+    const tail = lines.slice(-BUNDLER_OUTPUT_LINES).join('\n').slice(-BUNDLER_OUTPUT_CHARS);
+    return `It said:\n${tail.length < text.length ? `...\n${tail}` : tail}`;
+}
 // A sidecar Gemfile that inherits the project's own, plus rspec-rails. Bundler
 // resolves the two together, so the application's gems come with it — the same
 // arrangement the Cucumber sidecar has used since spec 32-1, and the reason the
@@ -303,6 +389,20 @@ async function provisionRspec(projectRoot, deps) {
     const sidecarGemfile = sidecarPath(projectRoot, 'Gemfile');
     writeIfChanged(sidecarGemfile, '# Sidecar Gemfile written by the unitbob connector — do not edit.\n' +
         'eval_gemfile File.expand_path("../../../Gemfile", __FILE__)\n' +
+        // Deliberately *not* guarded the way the Cucumber sidecar below is.
+        // `ensureStructuralRunner` only reaches here when the project does not
+        // supply rspec itself, so the duplicate that stopped A2.Time has almost no
+        // way in — and the guard would cost something real where it does. Measured
+        // 2026-08-20 on a gem project that carries rspec-rails as a gemspec
+        // development dependency: bundler replaces a `:development` dependency with
+        // ours rather than refusing it, so today the runner lands in `:default` and
+        // is always installed. Guarded, we would skip our line and leave it in
+        // `:development`, where a `BUNDLE_WITHOUT=development` would take the
+        // structural runner away from a project that had it working.
+        //
+        // That leaves one narrow hole: rspec-rails reached through an eval'd
+        // sub-Gemfile does raise the duplicate error here. It is now a legible one
+        // — see the message below, which no longer swallows what bundler said.
         'gem "rspec-rails", require: false\n');
     // Start from the project's own resolution for the reason spelled out on the
     // Cucumber sidecar below: without it bundler re-resolves the whole graph and
@@ -320,7 +420,7 @@ async function provisionRspec(projectRoot, deps) {
         return { status: 'provisioned' };
     return {
         status: 'fixable',
-        message: `Bundler failed to provision rspec-rails under ${SIDECAR_DIR}.`,
+        message: `Bundler failed to provision rspec-rails under ${SIDECAR_DIR}. ${whatBundlerSaid(result)}`,
         checklist: [
             'Ensure bundler is installed (`gem install bundler`), then run ' +
                 `\`BUNDLE_GEMFILE=${SIDECAR_DIR}/Gemfile bundle install\` from the project root.`,
@@ -352,13 +452,14 @@ async function provisionRuby(projectRoot, behavioralDir, deps) {
     const sidecarGemfile = join(behavioralDir, 'Gemfile');
     const sidecarContent = '# Sidecar Gemfile generated by Unitbob (Spec 32-1)\n' +
         'eval_gemfile File.expand_path("../../../Gemfile", __FILE__)\n' +
-        'gem "cucumber", "~> 9.0", require: false\n' +
+        gemLineUnlessTheProjectHasIt('cucumber', '~> 9.0') +
         // The connector-owned World blocks outgoing HTTP (spec 35-1), and it can only
-        // do that if webmock resolves here. A project that already carries the gem
-        // keeps its own version, because bundler starts from the project's own
-        // resolution. A project that does not would otherwise get a World promising a
-        // block it silently never performs — the exact shape of failure 35-1 closes.
-        'gem "webmock", require: false\n';
+        // do that if webmock resolves here. A project that does not carry the gem
+        // would otherwise get a World promising a block it silently never performs —
+        // the exact shape of failure 35-1 closes. A project that does carry it keeps
+        // its own version, and now actually gets to: see the comment on the helper
+        // for what asking twice cost A2.Time.
+        gemLineUnlessTheProjectHasIt('webmock');
     if (!existsSync(sidecarGemfile) || readFileSync(sidecarGemfile, 'utf8') !== sidecarContent) {
         writeFileSync(sidecarGemfile, sidecarContent);
     }
@@ -399,7 +500,7 @@ async function provisionRuby(projectRoot, behavioralDir, deps) {
     }
     return {
         status: 'fixable',
-        message: 'Bundler failed to provision Cucumber sidecar gem.',
+        message: `Bundler failed to provision Cucumber sidecar gem. ${whatBundlerSaid(result)}`,
         checklist: ['Ensure bundler is installed (`gem install bundler`) and run `bundle install` manually inside `.unitbob/behavioral/`.'],
     };
 }

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.3",
   "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.3 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