unitbob 0.6.0 → 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/verbs/validateWorkerCheckpoints.js

@@ -52,6 +52,7 @@ export async function validateWorkerCheckpoints(config, _args = [], deps = { std
             errors.push(`${label}: written path ${pathValue} is not an owned path`);
         }
         validateCompactFacts(checkpoint.facts, label, errors);
+        validateSurfaceCoverage(checkpoint.surface_coverage, item, label, errors);
         stringArray(checkpoint.decisions, `${label}: decisions`, errors);
         stringArray(checkpoint.known_problems, `${label}: known_problems`, errors);
     }
@@ -68,6 +69,16 @@ function stringArray(value, label, errors) {
     }
     return value;
 }
+// A fact says how it was established, and the vocabulary is two words wide:
+// `read` when the `source_refs` are what establishes it, `ran: <command>` when
+// something was executed and its result observed.
+//
+// a2time, 2026-08-17. A seeded fact claimed a dismissed employee cannot sign in.
+// It came from reading one method and remembering another, it reached sixteen
+// workers marked as verified, and it was false. Every fact that run established
+// by running the application held; the one that was not, did not — and nothing in
+// the checkpoint told the two apart, so no reader could weigh them differently.
+const ESTABLISHED_BY = /^(read|ran: \S.*)$/;
 function validateCompactFacts(value, label, errors) {
     if (!Array.isArray(value)) {
         errors.push(`${label}: facts must be an array`);
@@ -75,7 +86,7 @@ function validateCompactFacts(value, label, errors) {
     }
     for (const [index, entry] of value.entries()) {
         if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
-            errors.push(`${label}: $.facts[${index}] must be an object with fact and source_refs; got ${jsonType(entry)}`);
+            errors.push(`${label}: $.facts[${index}] must be an object with fact, source_refs and established_by; got ${jsonType(entry)}`);
             continue;
         }
         const fact = entry;
@@ -84,11 +95,50 @@ function validateCompactFacts(value, label, errors) {
         if (!Array.isArray(fact.source_refs) || fact.source_refs.some((ref) => typeof ref !== 'string' || !ref.trim())) {
             errors.push(`${label}: facts[${index}].source_refs must be compact source references`);
         }
+        if (typeof fact.established_by !== 'string' || !ESTABLISHED_BY.test(fact.established_by)) {
+            errors.push(`${label}: facts[${index}].established_by must be "read" or "ran: <command>"`);
+        }
         if ('source' in fact || 'transcript' in fact || 'suite' in fact) {
             errors.push(`${label}: facts[${index}] may not embed source, transcript, or suite copies`);
         }
     }
 }
+// Which addresses a Scenario drives is knowable in one place — the step file the
+// worker just wrote — and until now it travelled nowhere. The coordinator owes
+// the server one `surface_coverage` entry per Scenario, so on a2time, 2026-08-17,
+// it assembled that join out of the workers' closing prose and its own plan. The
+// independent reviewer read the step code instead, the two disagreed on six
+// Scenarios, and the server refused the publication. The join now rides with the
+// work that produced it, and the coordinator copies it instead of interpreting.
+//
+// Behavioral only: this is a join between Gherkin Scenarios and surfaces, and the
+// structural branch has neither. Requiring the key there would refuse honest
+// slices over a field that would mean nothing if they filled it in.
+function validateSurfaceCoverage(value, item, label, errors) {
+    if (value === undefined && item.branch !== 'behavioral')
+        return;
+    if (!Array.isArray(value)) {
+        errors.push(`${label}: surface_coverage must be an array of {capability_id, scenario, surfaces} entries, one per Scenario written`);
+        return;
+    }
+    for (const [index, entry] of value.entries()) {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            errors.push(`${label}: surface_coverage[${index}] must be an object with capability_id, scenario and surfaces; got ${jsonType(entry)}`);
+            continue;
+        }
+        const record = entry;
+        if (typeof record.capability_id !== 'string' || !item.capability_ids.includes(record.capability_id)) {
+            errors.push(`${label}: surface_coverage[${index}].capability_id ${String(record.capability_id)} is not in this plan item`);
+        }
+        if (typeof record.scenario !== 'string' || !record.scenario.trim()) {
+            errors.push(`${label}: surface_coverage[${index}].scenario must name the exact Scenario it covers`);
+        }
+        if (!Array.isArray(record.surfaces) || record.surfaces.length === 0
+            || record.surfaces.some((surface) => typeof surface !== 'string' || !surface.trim())) {
+            errors.push(`${label}: surface_coverage[${index}].surfaces must name at least one surface the Scenario drives`);
+        }
+    }
+}
 function jsonType(value) {
     if (value === null)
         return 'null';

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.0",
+  "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.0 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
@@ -48,9 +48,13 @@ No strict JSON handoff is required.
 Update the same checkpoint as promises complete. Keep facts compact and
 source-referenced. The normative JSON shape of one facts entry is:
 ```json
-{"fact":"The route creates an order.","source_refs":["app/orders.rb:12"]}
+{"fact":"The route creates an order.","source_refs":["app/orders.rb:12"],"established_by":"read"}
 ```
-Every facts entry is an object in that shape, never a string. Before handoff,
+Every facts entry is an object in that shape, never a string; `established_by` is
+`read` or `ran: <command>`, and a failure you reproduced is the second kind. On
+the behavioral branch, when you rename a Scenario or change what its steps drive,
+update that Scenario's `surface_coverage` entry in the same breath — the
+coordinator publishes those entries and does not reread your steps. Before handoff,
 make one final read of the checkpoint and confirm every `facts` entry is an
 object in the normative shape above. Do not delegate repair or auto-resume after
 the fuse. Preserve files and checkpoint for the coordinator's existing

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

@@ -21,21 +21,46 @@ nothing to put in them: `written_paths` (only your own `owned_paths`),
 unresolved harness problems). A missing array is not an empty one — the gate
 that reads this checkpoint refuses it either way.
 
-Facts are short statements with source references.
-The normative JSON shape of one facts entry is:
+Facts are short statements with source references, and each one says how it was
+established. The normative JSON shape of one facts entry is:
 ```json
-{"fact":"The route creates an order.","source_refs":["app/orders.rb:12"]}
+{"fact":"The route creates an order.","source_refs":["app/orders.rb:12"],"established_by":"read"}
 ```
-Every facts entry is an object in that shape, never a string. Never embed source
-files, suite copies, or transcript.
+Every facts entry is an object in that shape, never a string. `established_by` is
+`read` when the references are what establishes it, or `ran: <command>` when
+something was executed and its result observed. You run nothing, so every fact
+you add yourself is `read`; a `ran:` fact is one the coordinator established
+before fan-out, and that is exactly what makes it worth more than a fact anybody
+read. Never embed source files, suite copies, or transcript.
+
+On the behavioral branch your checkpoint also carries `surface_coverage`: one
+entry per Scenario you write, recorded as you write it.
+```json
+{"capability_id":"<one of your plan item's ids>","scenario":"<exact Scenario name>","surfaces":["POST /orders"]}
+```
+`surfaces` names the addresses and jobs the Scenario's `When` really reaches — not
+the ones its capability was assigned, and not the ones you meant to reach. Only
+you can know this: the coordinator publishes this join and never reopens your step
+files. On a2time, 2026-08-17, it had to reconstruct the join from what the workers
+said about their work; the independent reviewer read the steps instead, six
+Scenarios claimed addresses their steps never drove, and the server refused the
+publication.
 
 Write first, then find out. Start with the planned cases your seeded facts
 already support and get them onto disk; go reading only for what you still lack
 after that. The opposite order — survey the sources, then write — is what spent
 seven of eight workers' entire ceilings on a2time, 2026-08-10, and produced no
-file at all. A fact already in your checkpoint is settled: do not establish it a
-second time. Nothing mechanical enforces that rule; it holds because you keep
-it.
+file at all.
+
+A fact already in your checkpoint is settled: do not establish it a second time.
+A `read` fact is settled the same way — until a file you had to open anyway says
+otherwise. Then check that one fact against its own `source_refs`, which is two
+or three lines and not a fresh survey; if it is wrong, correct the entry and say
+so in `known_problems`. On a2time, 2026-08-17, a seeded fact said a dismissed
+employee cannot sign in — one method read, another remembered — and sixteen
+workers got it as verified. One of them looked, disagreed, and kept its scenario
+honest, which is the only reason that access hole came back red instead of green.
+Nothing mechanical enforces any of this; it holds because you keep it.
 
 Read only the `source_paths` and dependencies your finite planned cases need.
 Ask closed questions with the files to look in. For a closed missing fact, use