@sema-agent/core 7.23.4 → 7.23.5

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## 7.23.5 — 2026-09-19
+
+### `ListAgents` states what a row IS, instead of calling every non-live agent `finished` (#917; P2; widening; @server @cli @client-core)
+- **Before.** Both agent lanes of the listing read `status === "running" || status === "pending" ? "running" : "finished"`, so a `parked`, `failed`, `killed` or `cancelled` agent was reported to the model as **finished** — the word the tool's own note attaches the continuable rule to. The roster lane answered `unknown` only when there was NO local row at all; a row in a non-successful terminal was folded like the rest. The model-facing twin of the "an absent answer folds into a successful terminal" family.
+- **After.** One table over the task-status union, shared by both lanes (`AGENT_ROW_STATE`): two folds about LIVENESS — `pending` is queued and certainly not finished, `completed` is the one status that earns `finished` — and passthrough for everything else, so `parked` / `failed` / `killed` / `cancelled` travel as themselves. It is a `Record` over the whole union, so a new task status reds `tsc` here instead of quietly inheriting the old else-arm. The registry's status is an OPEN enum on the wire, so a word this engine does not know now answers `unknown`, never `finished`. The `(N finished agent(s): …)` note counts only real completions.
+- **Reach — widening.** `ListAgentsRow.state` gains `parked` / `failed` / `killed` / `cancelled`; nothing is removed or renamed. A consumer switching exhaustively over the union gains four arms; a consumer testing `state === "finished"` was being told the wrong thing for four of the seven statuses and is now correct. The peer-session lane (`busy` / `idle` / `offline`) is untouched. `test/backlog917-list-agents-state.test.ts` pins one row per task status on both lanes, the unknown-word arm, and the peer lane as a negative control.
+
+### Every inspector of a thrown value reads through the one guarded reader (#935; P2; no wire key)
+- **Before.** `readMember` (`src/core/thrown-value.ts`) is already the engine's rule for reading ONE member of an untrusted value, but six inspectors had not taken it. `classifyConnectFailure` read `.code` / `.cause` / `.errors` bare — from inside the connect loop's catch block, so a throwing accessor raised there; `isAbortError` tested `instanceof` and read `.name` bare **inside a promise rejection handler nobody awaits**, which is the unhandled-rejection shape that takes the process down; the loop's `createErrorToolResult` and `defineTool`'s rewrap read a thrown value's `details` / `errorKind` bare (and the former SPREAD the bag, evaluating every getter behind it); `describeNetworkError` / `hasStaleConnectionCode` / `isAbortSemanticsError` wrapped their whole walk in ONE coarse `try`, where a single hostile link cost every layer below it; `tool-model-gate`'s rebrand hand-built its own guard and kept a dead second one around the already-total `thrownText`.
+- **After.** All of them read through `readMember`, plus two new shared primitives rather than a seventh hand-built guard: `readOwnMembers` (the plural — copies a bag member by member instead of spreading it, and answers `undefined` for anything that is not one) and the now-exported `isErrorLike` (the realm-independent error brand test, so an error minted in a vm context or an injected transport is still walked). Rules: −4 coarse `try` walks, −2 hand-built guards, and two frozen rows leave the `src/brain` silent-arm ratchet (banked, not held as headroom).
+- **The class, swept, not the six reported points.** An independent review found the same read hand-rolled in four more places — `circuit-breaker.ts`, `failover.ts` and `degrading.ts` (twice) each spelled `e instanceof Error && e.name === "AbortError"` on a value an injected brain threw, inside an async IIFE with **no `.catch`**, where a raise is an unhandled rejection. They now share one guarded reader, `abortLikeName`; WHICH names count stays at each site, because that is policy and it differs (the breaker deliberately excludes `TimeoutError`). Its sibling `brainErrorCodeOf` replaces the one `instanceof BrainError` in the same IIFE. Side effect, measured by the same review: a cancellation minted in another realm used to fail `instanceof` and be counted by the circuit breaker as provider ill-health.
+- **Finer, not just safer.** A member that refuses to be read now costs THAT member: a hostile `code` no longer loses the deterministic verdict sitting on `cause`, and a hostile `details` no longer loses the `errorKind` beside it. The aggregate leg list is read the same way, down to its LENGTH and each index — `Array.isArray` answers true for a Proxy over an array, so the bare `.length` behind it ran that proxy's trap and threw out of the classifier, on the path that decides how many times a connect failure is retried (measured; the call ended at one attempt where the budget said three). Values that will not say what they are still answer the fail-safe verdict — indeterminate for the connect classifier, "not a cancellation" for the abort tests.
+- **Reach.** No wire key, no code word, no text change for any readable value (each site's negative control pins the previous bytes). One text change where the value was hostile: a transport rejection whose `name` accessor throws used to surface at the terminal as the ACCESSOR's words, unclassified (measured: `"hostile name"` in place of the rejection); it now surfaces as the rejection's own message with its brain code. `test/backlog935-guarded-inspectors.test.ts` drives the three hostile shapes (null prototype / throwing getter / revoked proxy) through every site.
+
+### A request the runtime refused to BUILD is no longer a retryable network failure (#933; P2; @server @cli @client-core)
+- **Before.** `fetch` answers with a `TypeError` for two unrelated things — a network error, and arguments it will not build a request from — and the connect loop folded both onto one arm. A gateway base URL carrying userinfo (`https://user:pass@host`) makes the runtime throw `TypeError("Request cannot be constructed from a URL that includes credentials: …")` with no `code` and no `cause`; the connect classifier read that empty error graph as "nothing I can judge", answered indeterminate, and the call then spent its entire backoff ladder re-failing identically before a packet was ever sent (measured downstream at ~3 minutes per call, every call).
+- **After — one rule, and a STRUCTURAL one.** `classifyFetchThrow` says whether a throw out of `fetch` was about the NETWORK or about the REQUEST, by the same law the neighbouring connect classifier states (never by message text): a throw that reached the network carries the transport's own error as `cause`, while one the runtime refused to BUILD has no cause at all or nests only a parse code. Measured over ten shapes — userinfo / unparseable URL / unsupported method / invalid header name / GET-with-body on one side, refused / DNS / pre-header reset / TLS-onto-plaintext / mid-body destroy on the other. An argument refusal leaves through the same door a pre-flight refusal does: `BrainError("invalid_request")`, no retry, the runtime's own sentence carried (it names the defect) with every authority's userinfo removed WHOLE first — it quotes a URL, and the general redactor keeps a short or unprefixed username. No `apiError` mark — nothing reached the wire, so an operator is not pointed at the provider. Every non-`TypeError` rejection (an injected transport's own class, the engine's connect-timeout `Error`) stays on the transport arm and still climbs the ladder.
+- **And the bad value is refused where it ARRIVES.** One assertion on the request root, at the seats that accept one: it must be an ABSOLUTE http(s) URL and it may not carry the credential. `createOpenAIBrain` / `createAnthropicBrain` / `createOpenResponsesBrain` refuse a bad `config.baseUrl` synchronously at construction, and `Model.baseUrl` — which no factory can see — is refused at request build, before the transport is entered and before the pairing law speaks (so an unservable root is diagnosed as one, not as a credential mismatch). The scheme half earns its place by measurement: `file:` and `ftp:` reject with `TypeError("fetch failed")` over a causeless "unknown scheme" — the exact shell a refused connection uses — so nothing downstream can tell that settled defect from an outage, and it bought the whole ladder. Refusing is the only honest answer for the credential half too: silently stripping the userinfo would send an UNAUTHENTICATED request to the host the operator thought they had authenticated to. Rules: the three brains' copies of the coalesce-and-strip root line fold into one `resolveRequestRoot` (−2), and the two bad-root refusals are one assertion at one seat (+0).
+- **Reach.** No wire key added, removed or re-typed. One class of failure changes code (`network` → `invalid_request`) and arrival time (one attempt instead of a ladder); a host that constructs brains from operator-supplied config must be ready for a synchronous throw. Stated cost in `docs/KNOWN-LIMITS.md` (KL-933a). `test/backlog933-unbuildable-request.test.ts` pins both halves against the real runtime, with the real-socket `ECONNREFUSED` negative control.
+
+### Workflow list rows state WHY a failed run failed (#932; P2; additive; @server @cli @client-core)
+- **Before.** `WorkflowRunSummary` — the shared projection every `WorkflowRunStore` backend hands back from `listByScope` — already carried the three disclosures that qualify a row which LOOKS clean (`agentFailures`, `budgetOvershoot`, `timeoutInterruption`), but not the run's own `errorCode`. So a `/workflows` panel reading rows saw one word, `failed`, for a refused spawn, a blown token ceiling, a stalled run and a body that simply threw — and had to `get` the full run per failed row (or detour through a `TaskOutput` card) to say which.
+- **After.** `WorkflowRunSummary.errorCode?: string` is projected VERBATIM from `WorkflowRun.errorCode`: same word, same vocabulary, no second attribution rule (the thrown-code → first-failed-agent → absent ladder still runs once, where the run is written). Present exactly when the run carries one; absent reads "no code on the record", never "the run succeeded". Because the projection is shared, every backend answers alike — the importable `workflowRunStoreContract` now asserts the round-trip, the absent key on a codeless failure, and the absent key on a completed run, so a service-side store that keeps rows in columns is told it needs one.
+- **Reach.** Additive: no key removed, none re-typed, every pre-existing member byte-identical. Consuming is optional. `test/backlog932-workflow-summary-error-code.test.ts` pins the projection on both in-tree backends.
+### Permission rules — the rule lane reads a quoted shell operator as argument text (#931; P2; @cli @server)
+- **Before.** `parseRuleText("Bash(awk '{print $1}' f)", "allow")` answered `invalid.not_simple_command`, and so did `Bash(grep 'x$' f)`, `Bash(cat '$F')` and `Bash(grep "a|b" f.log)`. The card OFFERED those rules and the store refused them: the offer round trip is fail-closed, so the "don't ask again" option simply vanished. #921 gave the whole-string classify gate a quote mask; the rule lane's own per-segment floor (`parseLeadingCommandName`) stayed quote-BLIND and refused every operator character wherever it stood.
+- **After.** The lane calls that floor through ONE option set (`RULE_LANE_FLOOR`) carrying `quotedOperatorsAreText: true` — the same `quoteMask` sieve, not a second reading of quoting. The per-reader `quotedOperatorsAreText` axis on the lane's `LaneReading` is gone (both readings always took the same answer): rules −1.
+- **The matcher's fail-closed claim is now asked out loud.** `admitsUnder` refuses a stored BODY whose quoting is unbalanced, which its own contract already claimed ("a body this lane cannot read matches nothing"). While the floor refused a quoted operator that was true by accident — an unbalanced body could not reach a command that parsed. Reachable only through corrupted or foreign store bytes (no entrance mints one), so behaviour is unchanged for every rule this engine wrote.
+- **REACH, and it is wider than the exact form (@cli @server).** A PREFIX rule widens with the floor: `Bash(grep:*)` now admits `grep 'x|y' f`, `grep 'a;b' f`, `grep '$x' f` and `grep 'x&y' f`, each of which asked before. A stored prefix that names a program therefore reaches every quoted-operator spelling of that program's arguments. Still refused, quoted or not: `"$x"` (double quotes do not suppress expansion), `'$(id)'`, a backtick, a line break, a redirection, and `'x'|'y'` (the pipe is unquoted). A deployment that audits stored rules should re-read its prefix rows against this reach.
+- **What did NOT move.** The whole-string gate one step above is untouched and is what keeps this exact: an unquoted or double-quoted `$`, a backtick, a subshell, an escape, a line break and (on the matching/minting reading) a redirection still refuse the WHOLE text, quoted or not, so the only operator characters that can reach a segment are ones bash itself reads as literal text. Unbalanced quoting turns the mask off for the whole string (fail-closed). The interpreter-prefix refusal (`Bash(awk:*)`) and the DENY/ASK direction (its own lexer, `programRunReachOf`) are unmoved — the "deny reads more commands than allow, never fewer" asymmetry still runs the safe way.
+
+### Closed sets — both shell-decline SEAT TABLES declare a row per member, behind a fence (#924; P3)
+- **Before.** Which {@link ShellScanDecline} a seat reads as read evidence was a `Set`, twice: the read-boundary seat's was DERIVED from the closed set (`new Set(SHELL_SCAN_DECLINES)`) and the classify seat's was an empty literal (`new Set()`). A THIRD member added to the set would be picked up by one seat automatically and missed by the other — silently, and in the WIDENING direction (a MANDATED card becoming an ordinary one). No fence, no gate and no reviewer had a handle on it.
+- **After.** Both are row-per-member `as const` tables beside the set they range over (`bash-program-position.ts`), each with an `AssertAllKeysHandled` fence, registered in `docs/CLOSED-SETS.md` so the scan leg (`npm run gate:closed-sets`) reads their keys against the set's members in both directions. The two `Set`s the seats' readers take are DERIVED from the rows, so neither can say what its table does not. "Empty by the argument" is now a row saying `false`. Zero behaviour change: the derived sets are byte-for-byte what they were.
+- `QuoteOpen` (`bash-lexer.ts`, the quote mask's per-character word) is registered in the same change — the release's wire-change manifest saw it as a closed set and the registry did not.
+
+### Approval cards — a deny-hit card names the sensitive-path deny list and the pattern (#939 ①; P2; @cli @server)
+- **Before.** On the full Bash face, `cat .env` under `readDenyPatterns:["**/.env"]` raised a card reading, in full, `tool "Bash" performs an irreversible action — explicit approval required`, `origin:"shell_gate_tighten"`, and nothing else. Nothing said a deny row was what raised it; nothing named the pattern. The SAME table on the structured read faces refuses and names the pattern (#937), so an approver on the shell face answered YES about credential-class bytes with no clue what they were releasing.
+- **After — the read faces' own sentence, all FIVE parts.** The card carries `probeReason` = `reading "<absolute target>" matches the sensitive-path read deny list (pattern "<pattern>"). This list guards credential-class paths and applies regardless of the containment roots.` — the ACTION, the resolved ABSOLUTE target, the deny table by name, the PATTERN verbatim, and one sentence of why. It composes the SAME two pieces the refusing faces compose (`sensitivePathDenyList` + `SENSITIVE_PATH_DENY_SCOPE`, `read-deny.ts`), now the ONE naming for all four composers; every existing refusal text is byte-unchanged. Only the disposition differs, and it must: this card is approvable, so "is refused" would be a lie on it.
+- **The finding is the SEGMENT's, not the command's.** A compound whose one dirty segment is the hit (`head inside.txt && cat .env`) names THAT segment's path and pattern, in either segment order — a card saying only "this command hits the deny list" leaves the approver reading two segments with no way to tell which half is the problem.
+- **Where it rides, and why.** `probeReason`, never the ask's `message`: the message is what the auto-mode classifier is shown, and a probe must not own an input to the decider that can clear its own ask. The gate caps that string at `PROBE_REASON_MAX` by truncating the TAIL, so the mint elides a long operand in its MIDDLE instead — every part survives and the elision is visible. (`PROBE_REASON_MAX` moves to the leaf neutralizer module beside its `PROBE_CAUSE_PATH_MAX` sibling, re-exported from `checkpoint-store` so the public spelling is unchanged: the mint, the gate and the persist boundary now read one constant.) The account is minted ONCE (`probeAccountOf`) and spread at every arm a shell seat answers a verdict from — including the backgrounded arm and the poll-loop arm, which carried no account at all. The recursive-reach `cause` rides the same mint, unchanged.
+- **@cli @server** — `AskRequest.probeReason` / `RiskDescriptor.probeReason` now carry a value on this family where they carried none. No new field, no new code, no wire key. Consumers already rendering `probeReason` get the sentence for free; a consumer that renders nothing is unchanged.
+- **The finding is read from whichever pass found it.** When the walk cannot NAME the program (`env --`, `nice -x 5`, `watch`, `sudo -u`), when the operands arrive on a STREAM (`… | xargs …`), or when the grammar gate refused the command whole (`{ cat <deny row>; }`, `ca''t <deny row>`), the compound verdict carries no deny fields at all — the row is found by the containment gate's second pass, which computed the path and the pattern and threw both away. `OutOfRootReadGateVerdict.denied` now carries the finding, and the card reads it from there: the shapes an approver can least read for themselves are no longer the silent ones. A shape whose row NO pass could read stays bare — its mandate is the honest weaker one, and a card naming a pattern there would assert what nothing measured.
+- **The TRAVERSAL mandate names its table too.** `recursiveReadPaths` (`grep -r`, `diff -r`) is minted only beside a wired judge WITH entries, so it is a deny-table mandate as much as a match is — and it carried no sentence at all. It cannot name a matched row (the walk is zero-I/O and does not enumerate the subtree, so claiming a hit would be false for the same command in a tree that holds none), so it names what IS true: the ACTION, the resolved ABSOLUTE root, the table by name, the PATTERNS in force, and the clause that makes it a mandate. Rows are dropped whole and counted, never cut into a pattern nobody wrote. A match beside a traversal reports the match.
+- **The table's REACH clause leaves the capped sentence.** It is the same 88 characters on every card of this family — fixed text, not a finding — and inside the 200-character cap it was spending more than half the budget: with the engine's OWN built-in deny table (eight rows longer than 22 characters, the longest 47) and a real project root, BOTH variable parts were elided and "the pattern verbatim" stopped being true of the engine's own rows. Composing two pieces instead of three takes the room for them from 45 characters to 133. The REFUSING faces are uncapped and keep the full sentence.
+- **Not moved:** who may answer the card. The ask is still MANDATED and still approvable, a YES still runs the command, a NO still refuses, and the read-only face still REFUSES outright. Whether the full face should refuse rather than ask (#939 ②) is a separate ruling.
+
+### Read boundary — `Monitor` runs the same execute-time canonical recheck the two `bash` faces run (#938; P2; @server @cli)
+- **Before.** `Monitor` carried an approval-time shell seat like every other shell face (`installShellSeat("Monitor")`), and that seat judges the WRITTEN spelling. Nothing re-judged where the KERNEL would take those words: `env.spawnBackground` was reached directly. With a read boundary declared, `cat <symlink out of the roots>` and `cat <glob whose expansion is denied>` were refused on `Bash` and UNJUDGED on `Monitor` — and a Monitor command runs unattended for as long as the watch lasts, streaming what it reads into the conversation.
+- **After — a MOUNT, not a second leg.** The closure `createBashTool` built inline is now `createShellCanonicalRecheck`, built ONCE at the hands phase (the one place the boundary declaration lives) and handed to the Monitor mount two phases later. Its contract, scope, over-fires and blind spots are the leg's own and unchanged. A refusal is the whole call result: a watch that must not read is a watch that must not START, so nothing registers, nothing streams, and there is no task to stop.
+- **The card names the tool that refused.** The leg is shared; the refusal is not anonymous. `Monitor`'s canonical refusals say `Error (Monitor):` where the `bash` faces say `Error (Bash):` — a model told the wrong tool refused retries on that tool, the one repair the refusal must not suggest. Both `bash` faces' text is byte-unchanged.
+- **`Monitor` takes the same option `createBashTool` takes** (`readBoundary`) and BUILDS the leg itself, so a direct library mount cannot be fail-open on one face and fail-closed on the other.
+- **The leg gets the operands the two read faces hand nobody (SECURITY; @server @cli).** Measured: `cat <in-root symlink out of the roots>` is refused at execution on both shell faces — and `env -- cat <the same symlink>` RAN, after an approval, on `Bash` and on `Monitor`. When the walk cannot NAME the program (`env --`, `sudo -u`) or the operands arrive on a stream, both read faces hand this leg NOTHING, so there was nothing to canonicalize. The containment gate's reader scan DOES read those shapes — same operands, same judge — and now publishes them (`OutOfRootReadGateVerdict.checked` / `.undecided`, which it already computed and discarded). The leg's exclusion grew with it and is the load-bearing half: it skips what the boundary RAISED in BOTH voices (an operand outside the roots, and one the deny judge MATCHED lexically), because both were on the card the approver answered and a yes on either runs — the ruled disposition is untouched.
+- **The leg's exemption is PER HALF, not per path (SECURITY).** A yes runs the read the card DESCRIBED and nothing else. Keyed on the path alone, either voice's release silenced BOTH halves and the direction inverted: an in-root name a deny row matches, whose TARGET is outside the roots, raised a DENY card and the yes then ran the out-of-root read — while the same command with the deny row REMOVED was refused, so adding a deny row turned a refusal off. The mirror: `cat <outside>/link` whose target is a deny row raised a CONTAINMENT card and the yes read the guarded file with the deny half never consulted. Each half now carries its own `answered` set, out-of-root operands ride the candidate list like every other (so the deny half sees them), and no candidate is dropped.
+- **Absent boundary ⇒ no recheck and no I/O**, exactly as on the shell faces. The leg REFUSES an escape and never rescues a refusal, so an in-root watch starts exactly as before.
+
 ## 7.23.4 — 2026-09-19
 
 ### Read boundary — one deny judge for every read face: the `bash_readonly` shell wires the same seat (#937; P1; design/199 v1 exception retired; @server @cli)

package/dist/agents/list-agents-tool.d.ts

@@ -50,6 +50,10 @@ export interface ListAgentsRow {
     /** Peer rows only: the listing-minted ref. */
     ref?: string;
     address: string;
-    state: "busy" | "idle" | "offline" | "running" | "finished" | "unknown";
+    /** What the row IS, right now. The peer lane has its own three words (`busy`/`idle`/`offline`), the
+     *  agent lanes carry the task record's own status word (see {@link AGENT_ROW_STATE}), and `unknown`
+     *  is the honest answer where no record can be read. `finished` means COMPLETED and nothing else —
+     *  a model reads it as "the work is done" and applies the continuable rule to it. */
+    state: "busy" | "idle" | "offline" | "running" | "parked" | "finished" | "failed" | "killed" | "cancelled" | "unknown";
 }
 export declare function createListAgentsTool(opts: ListAgentsToolOptions): import("../internal/harness-types.js").AgentTool<Type.TObject<{}>, unknown>;

package/dist/agents/list-agents-tool.js

@@ -9,6 +9,18 @@ import { thrownText } from "../core/thrown-value.js";
 export const LIST_AGENTS_TOOL_NAME = "ListAgents";
 export const LIST_AGENTS_TOOL_ALIAS = "ListPeers";
 export const LIST_AGENTS_MAX_RESULT_CHARS = 10_000;
+const AGENT_ROW_STATE = {
+    pending: "running",
+    running: "running",
+    parked: "parked",
+    completed: "finished",
+    failed: "failed",
+    killed: "killed",
+    cancelled: "cancelled",
+};
+function agentRowState(status) {
+    return Object.hasOwn(AGENT_ROW_STATE, status) ? AGENT_ROW_STATE[status] : "unknown";
+}
 export function createListAgentsTool(opts) {
     return defineTool({
         name: LIST_AGENTS_TOOL_NAME,
@@ -58,7 +70,7 @@ export function createListAgentsTool(opts) {
                             continue;
                         seenIds.add(t.task_id);
                         const full = opts.registry.getAccessibleTask(t.task_id, view);
-                        rows.push({ kind: "background_agent", name: full?.name ?? t.description ?? t.task_id, address: t.task_id, state: t.status === "running" || t.status === "pending" ? "running" : "finished" });
+                        rows.push({ kind: "background_agent", name: full?.name ?? t.description ?? t.task_id, address: t.task_id, state: agentRowState(t.status) });
                     }
                 }
             }
@@ -70,7 +82,7 @@ export function createListAgentsTool(opts) {
                             continue;
                         seenIds.add(e.agentId);
                         const live = opts.registry?.getAccessibleTask(e.agentId, view);
-                        rows.push({ kind: "roster", name: e.name, address: e.agentId, state: live === undefined ? "unknown" : live.status === "running" || live.status === "pending" ? "running" : "finished" });
+                        rows.push({ kind: "roster", name: e.name, address: e.agentId, state: live === undefined ? "unknown" : agentRowState(live.status) });
                     }
                 }
                 catch {

package/dist/brain/anthropic.js

@@ -7,7 +7,7 @@ import { mintFallbackToolCallId } from "./tool-call-id.js";
 import { emitBrainTelemetry, reportReasoningWireFacts } from "./status-sink.js";
 import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, modelSupportsVision, sendableImages } from "./media-degrade.js";
 import { ANTHROPIC_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders, takeHeaderCasefold } from "./request-params.js";
-import { adjudicateModelRoute, applyRouteCredentialHeaders, createBrainRouteJudge, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
+import { adjudicateModelRoute, applyRouteCredentialHeaders, assertServableRequestRoot, createBrainRouteJudge, resolveRequestRoot, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
 import { MIN_THINKING_TOKENS, budgetCapSkipsThinking, declaredEffortLevels, reasoningBudgetShare, reasoningRequestCarried, resolveEffort } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
 function thinkingBudget(maxTokens, share, fixed, hardCap = false) {
@@ -224,6 +224,7 @@ function closeToolUseBlock(acc) {
     return acc.closedTc;
 }
 export function createAnthropicBrain(config = {}) {
+    assertServableRequestRoot(config.baseUrl, "config.baseUrl");
     const doFetch = config.fetchImpl ?? fetch;
     const cacheBreakpoints = config.cacheBreakpoints !== false;
     const stream = (model, context, options) => {
@@ -238,6 +239,7 @@ export function createAnthropicBrain(config = {}) {
             httpLabel: "anthropic",
             stallTimeouts: options?.stallTimeouts,
             buildRequest: (overrides) => {
+                const root = resolveRequestRoot(model.baseUrl, config.baseUrl, "https://api.anthropic.com");
                 const routeCredential = resolveRouteCredential({
                     optionsApiKey: options?.apiKey,
                     optionsHeaders: options?.headers,
@@ -249,7 +251,6 @@ export function createAnthropicBrain(config = {}) {
                 if (!routeVerdict.ok)
                     throw new BrainError("invalid_request", routeRefusalText(routeVerdict));
                 const apiKey = routeCredential.apiKey;
-                const root = (model.baseUrl || config.baseUrl || "https://api.anthropic.com").replace(/\/+$/, "");
                 const nonEmptyBlocks = context.systemBlocks?.filter((b) => b.text.length > 0);
                 const system = nonEmptyBlocks?.length
                     ? nonEmptyBlocks.map((b) => ({

package/dist/brain/circuit-breaker.js

@@ -1,5 +1,5 @@
 import { createAssistantMessageEventStream } from "../internal/llm.js";
-import { BrainError, IN_BAND_OUTPUT_CODES, ZERO_USAGE, extractErrorCode } from "./errors.js";
+import { abortLikeName, brainErrorCodeOf, IN_BAND_OUTPUT_CODES, ZERO_USAGE, extractErrorCode } from "./errors.js";
 import { emitBrainStatus, emitBrainTelemetry } from "./status-sink.js";
 import { thrownText } from "../core/thrown-value.js";
 export const CIRCUIT_OPEN_MARKER = "circuit open for ";
@@ -142,8 +142,8 @@ export function createCircuitBreakerBrain(inner, opts = {}) {
                 }
             }
             catch (e) {
-                const aborted = options?.signal?.aborted === true || (e instanceof Error && e.name === "AbortError");
-                const code = e instanceof BrainError ? e.code : "network";
+                const aborted = options?.signal?.aborted === true || abortLikeName(e) === "AbortError";
+                const code = brainErrorCodeOf(e) ?? "network";
                 record(key, aborted ? "http" : code, !bypass);
                 out.push({
                     type: "error",

package/dist/brain/degrading.js

@@ -1,5 +1,5 @@
 import { createAssistantMessageEventStream, } from "../internal/llm.js";
-import { ZERO_USAGE, extractErrorCode } from "./errors.js";
+import { abortLikeName, ZERO_USAGE, extractErrorCode } from "./errors.js";
 import { CIRCUIT_OPEN_MARKER } from "./circuit-breaker.js";
 import { thrownText } from "../core/thrown-value.js";
 export const DEGRADED_DIAGNOSTIC_TYPE = "degraded";
@@ -108,8 +108,7 @@ export function passthroughStream(brain, model, context, options) {
             }
         }
         catch (e) {
-            const aborted = options?.signal?.aborted === true ||
-                (e instanceof Error && (e.name === "AbortError" || e.name === "TimeoutError"));
+            const aborted = options?.signal?.aborted === true || abortLikeName(e) !== undefined;
             out.push({ type: "error", reason: "error", error: errorMessageOf(model, e, aborted) });
         }
     })();
@@ -175,8 +174,7 @@ export function createDegradingBrain(opts) {
                 out.push(current.terminal ?? terminalOf(current.message));
             }
             catch (e) {
-                const aborted = options?.signal?.aborted === true ||
-                    (e instanceof Error && (e.name === "AbortError" || e.name === "TimeoutError"));
+                const aborted = options?.signal?.aborted === true || abortLikeName(e) !== undefined;
                 const errMsg = errorMessageOf(lastAttempted, e, aborted);
                 if (degradeInfo)
                     tagDegraded(errMsg, degradeInfo);

package/dist/brain/errors.d.ts

@@ -112,31 +112,48 @@ export declare function stripErrorCodePrefix(errorMessage: string): string;
 /**
  * Whether a transport-level connect failure is DETERMINISTIC (see {@link DETERMINISTIC_CONNECT_CODES})
  * or gives no such verdict. Classification is by `code` along the error graph — never by message text,
- * which providers and runtimes reword freely.
+ * which providers and runtimes reword freely. (Distinct question from {@link classifyFetchThrow}, which
+ * does not classify a failure at all: it reads the runtime's own fixed shell to tell whether a request
+ * was ever built.)
  *
  * The graph, not just the chain: undici nests the actionable error under `cause`, and a dual-stack
  * connect nests one `AggregateError` whose `errors[]` hold the per-family results. A code outside the
  * set ANYWHERE in the graph returns `"indeterminate"`, and every AGGREGATE LEG must reach a
- * deterministic verdict of its own — so a hostname whose IPv4 leg is refused while its IPv6 leg timed
- * out, or whose second leg says nothing this classifier can read, keeps the full ladder. Position
- * decides how silence is read: a WRAPPER with no code (the `TypeError("fetch failed")` shell, an
- * `AbortSignal.timeout` DOMException whose `code` is a number) is structural and defers to what it
- * wraps, while a LEG with nothing readable is an outcome nobody accounted for and blocks the verdict.
- *
- * Fail-safe by construction — every uncertain outcome (empty aggregate, an unreadable leg, a graph
- * larger than the node budget, no deterministic code found at all) answers `"indeterminate"`, i.e. the
+ * deterministic verdict of its own. Position decides how silence is read: a WRAPPER with no code (the
+ * `fetch failed` shell, an `AbortSignal.timeout` DOMException whose `code` is a number) is structural
+ * and defers to what it wraps, while a LEG with nothing readable is an outcome nobody accounted for and
+ * blocks the verdict. Fail-safe by construction — every uncertain outcome (empty aggregate, unreadable
+ * leg, a graph past the node budget, no deterministic code at all) answers `"indeterminate"`, i.e. the
  * pre-existing behavior.
  */
 export type ConnectFailureClass = "deterministic" | "indeterminate";
 export declare function classifyConnectFailure(e: unknown): ConnectFailureClass;
-/** RB-386③ — render a transport-level error WITHOUT folding away its cause chain. undici's
- *  `fetch` rejects with `TypeError("fetch failed", { cause })` where the CAUSE carries the actually
- *  actionable fact (`connect ECONNREFUSED …` / `getaddrinfo ENOTFOUND …` / `SocketError: other side
- *  closed` with a `code`); `String(e)` / `e.message` alone collapsed ALL THREE network-failure shapes
- *  (refused / DNS / mid-stream disconnect) into the same opaque "fetch failed", end to end (BrainError
- *  detail → TaskResult.errorMessage → bg-agent terminal notification / poll error). Walks the cause
- *  chain (bounded), appending each layer's `code:`-prefixed message; layers whose message the parent
- *  already contains are skipped (no duplicate noise). Falls back to the plain message for causeless
- *  errors — those call sites' output is byte-identical to before. */
+/** What a throw out of `fetch` was about: the NETWORK (retryable — the historic reading of every throw
+ *  here), or the REQUEST ITSELF, which is deterministic: identical arguments reproduce it every time. */
+export type FetchThrowClass = "transport" | "request_unbuildable";
+/** Classify a throw out of `fetch` — the fold point where a request-shaped defect used to be laundered into
+ *  a transient network failure and handed to the retry ladder (founding case: a base URL with userinfo
+ *  throws a `TypeError` with no `code` and no `cause`, so the connect classifier answered indeterminate and
+ *  the call spent its whole backoff budget on a request the runtime never built).
+ *
+ *  ONE question — is there TRANSPORT EVIDENCE? — in its two forms: the runtime's own shell sentence, or a
+ *  `cause` that is a transport fact rather than a parse verdict. A `TypeError` with neither was never built.
+ *  Measured over ten real shapes; non-`TypeError` stays on the transport arm and an unreadable value answers
+ *  `transport`, the pre-existing behavior. Stated cost: KL-933a. */
+export declare function classifyFetchThrow(e: unknown): FetchThrowClass;
+/** The cancellation NAME an untrusted rejection states, or `undefined`. Five sites hand-rolled
+ *  `e instanceof Error && e.name === "AbortError"` on a value an injected brain threw, each able to
+ *  raise inside an async IIFE with no `.catch`. One guarded, realm-independent read here; WHICH names
+ *  count stays at each site, because that is policy and it differs (the breaker excludes `TimeoutError`). */
+export declare function abortLikeName(err: unknown): "AbortError" | "TimeoutError" | undefined;
+/** The brain code an untrusted rejection carries, or `undefined`. Reads the WORD against the code list
+ *  rather than testing `instanceof BrainError`, which walks a chain a revoked proxy traps — and the one
+ *  site that did so sits in an async IIFE with no `.catch`. */
+export declare function brainErrorCodeOf(e: unknown): BrainErrorCode | undefined;
+/** Render a transport-level error WITHOUT folding away its cause chain: undici rejects with
+ *  `TypeError("fetch failed", { cause })` where the CAUSE carries the actionable fact, and the shell
+ *  alone reads the same for refused / DNS / mid-stream disconnect. Walks the chain (bounded), appending
+ *  each layer's `code:`-prefixed message and skipping layers the parent's message already contains;
+ *  a causeless error renders as its plain message. */
 export declare function describeNetworkError(e: unknown): string;
 export {};

package/dist/brain/errors.js

@@ -1,4 +1,4 @@
-import { thrownText } from "../core/thrown-value.js";
+import { isErrorLike, readMember, thrownText } from "../core/thrown-value.js";
 export const ZERO_USAGE = {
     input: 0,
     output: 0,
@@ -82,16 +82,12 @@ const STALE_CONNECTION_CODES = new Set([
     "StreamSuspended",
 ]);
 function hasStaleConnectionCode(e) {
-    try {
-        let cur = e;
-        for (let depth = 0; depth < 5 && cur !== undefined && cur !== null; depth++) {
-            const code = typeof cur.code === "string" ? cur.code : undefined;
-            if (code !== undefined && STALE_CONNECTION_CODES.has(code))
-                return true;
-            cur = cur instanceof Error ? cur.cause : undefined;
-        }
-    }
-    catch {
+    let cur = e;
+    for (let depth = 0; depth < 5 && cur !== undefined && cur !== null; depth++) {
+        const code = readMember(cur, "code");
+        if (typeof code === "string" && STALE_CONNECTION_CODES.has(code))
+            return true;
+        cur = isErrorLike(cur) ? readMember(cur, "cause") : undefined;
     }
     return false;
 }
@@ -104,25 +100,26 @@ function walkConnectFailure(node, budget) {
     if (node === undefined || node === null)
         return "silent";
     let verdict = "silent";
-    const code = node.code;
+    const code = readMember(node, "code");
     if (typeof code === "string") {
         if (!DETERMINISTIC_CONNECT_CODES.has(code))
             return "indeterminate";
         verdict = "deterministic";
     }
-    if (!(node instanceof Error))
+    if (!isErrorLike(node))
         return verdict;
-    const members = node.errors;
-    if (Array.isArray(members)) {
-        if (members.length === 0)
+    const members = readMember(node, "errors");
+    const legCount = readMember(members, "length");
+    if (members !== undefined) {
+        if (typeof legCount !== "number" || !Number.isInteger(legCount) || legCount <= 0)
             return "indeterminate";
-        for (const member of members) {
-            if (walkConnectFailure(member, budget) !== "deterministic")
+        for (let i = 0; i < legCount; i++) {
+            if (walkConnectFailure(readMember(members, String(i)), budget) !== "deterministic")
                 return "indeterminate";
         }
         verdict = "deterministic";
     }
-    const cause = node.cause;
+    const cause = readMember(node, "cause");
     if (cause !== undefined && cause !== null) {
         const below = walkConnectFailure(cause, budget);
         if (below === "indeterminate")
@@ -135,21 +132,42 @@ function walkConnectFailure(node, budget) {
 export function classifyConnectFailure(e) {
     return walkConnectFailure(e, { left: CONNECT_GRAPH_NODE_BUDGET }) === "deterministic" ? "deterministic" : "indeterminate";
 }
+const FETCH_TRANSPORT_SHELLS = new Set(["fetch failed", "terminated"]);
+const REQUEST_ARGUMENT_CODES = new Set(["ERR_INVALID_URL"]);
+export function classifyFetchThrow(e) {
+    if (readMember(e, "name") !== "TypeError")
+        return "transport";
+    const message = readMember(e, "message");
+    if (typeof message === "string" && FETCH_TRANSPORT_SHELLS.has(message))
+        return "transport";
+    const cause = readMember(e, "cause");
+    if (cause === undefined || cause === null)
+        return "request_unbuildable";
+    const code = readMember(cause, "code");
+    return typeof code === "string" && REQUEST_ARGUMENT_CODES.has(code) ? "request_unbuildable" : "transport";
+}
+export function abortLikeName(err) {
+    if (!isErrorLike(err))
+        return undefined;
+    const name = readMember(err, "name");
+    return name === "AbortError" || name === "TimeoutError" ? name : undefined;
+}
+export function brainErrorCodeOf(e) {
+    const code = readMember(e, "code");
+    return typeof code === "string" && BRAIN_ERROR_CODES.includes(code) ? code : undefined;
+}
 export function describeNetworkError(e) {
     const top = thrownText(e);
     const parts = [];
-    try {
-        let cur = e instanceof Error ? e.cause : undefined;
-        for (let depth = 0; depth < 4 && cur !== undefined && cur !== null; depth++) {
-            const code = typeof cur.code === "string" ? cur.code : undefined;
-            const msg = thrownText(cur);
-            const piece = code !== undefined && !msg.includes(code) ? `${code}: ${msg}` : msg;
-            if (piece.length > 0 && piece !== top && !parts.includes(piece))
-                parts.push(piece);
-            cur = cur instanceof Error ? cur.cause : undefined;
-        }
-    }
-    catch {
+    let cur = isErrorLike(e) ? readMember(e, "cause") : undefined;
+    for (let depth = 0; depth < 4 && cur !== undefined && cur !== null; depth++) {
+        const rawCode = readMember(cur, "code");
+        const code = typeof rawCode === "string" ? rawCode : undefined;
+        const msg = thrownText(cur);
+        const piece = code !== undefined && !msg.includes(code) ? `${code}: ${msg}` : msg;
+        if (piece.length > 0 && piece !== top && !parts.includes(piece))
+            parts.push(piece);
+        cur = isErrorLike(cur) ? readMember(cur, "cause") : undefined;
     }
     const body = parts.length > 0 ? `${top} (${parts.join(" ← ")})` : top;
     return hasStaleConnectionCode(e) ? `${body} — possibly a stale connection; a fresh one may succeed` : body;

package/dist/brain/failover.js

@@ -1,5 +1,5 @@
 import { createAssistantMessageEventStream, } from "../internal/llm.js";
-import { extractErrorCode } from "./errors.js";
+import { abortLikeName, extractErrorCode } from "./errors.js";
 import { emitBrainTelemetry } from "./status-sink.js";
 import { passthroughStream } from "./degrading.js";
 import { thrownText } from "../core/thrown-value.js";
@@ -65,8 +65,7 @@ export function createFailoverBrain(brains) {
                 }
             }
             catch (e) {
-                const aborted = options?.signal?.aborted === true ||
-                    (e instanceof Error && (e.name === "AbortError" || e.name === "TimeoutError"));
+                const aborted = options?.signal?.aborted === true || abortLikeName(e) !== undefined;
                 const errorMsg = {
                     role: "assistant",
                     content: [{ type: "text", text: "" }],

package/dist/brain/open-responses.js

@@ -6,7 +6,7 @@ import { mintFallbackToolCallId } from "./tool-call-id.js";
 import { emitBrainTelemetry } from "./status-sink.js";
 import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imagesOmittedNoVisionNote, modelSupportsVision, sendableImages } from "./media-degrade.js";
 import { OUTPUT_CAP_KEYS, RESPONSES_RESERVED, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders } from "./request-params.js";
-import { adjudicateModelRoute, applyRouteCredentialHeaders, createBrainRouteJudge, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
+import { adjudicateModelRoute, applyRouteCredentialHeaders, assertServableRequestRoot, createBrainRouteJudge, resolveRequestRoot, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
 import { declaredOffSpelling, mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
 const DEGENERATE_POLL_CHARS = 64;
@@ -217,6 +217,7 @@ function mapTerminalStopReason(incompleteReason, hadToolCalls) {
     return "stop";
 }
 export function createOpenResponsesBrain(config = {}) {
+    assertServableRequestRoot(config.baseUrl, "config.baseUrl");
     const doFetch = config.fetchImpl ?? fetch;
     const stream = (model, context, options) => {
         let sentMaxTokens;
@@ -232,6 +233,10 @@ export function createOpenResponsesBrain(config = {}) {
             httpLabel: "responses",
             stallTimeouts: options?.stallTimeouts,
             buildRequest: (overrides) => {
+                const root = resolveRequestRoot(model.baseUrl, config.baseUrl);
+                if (!root) {
+                    throw new Error("createOpenResponsesBrain: no baseUrl configured (set config.baseUrl or model.baseUrl)");
+                }
                 const routeCredential = resolveRouteCredential({
                     optionsApiKey: options?.apiKey,
                     optionsHeaders: options?.headers,
@@ -243,10 +248,6 @@ export function createOpenResponsesBrain(config = {}) {
                 if (!routeVerdict.ok)
                     throw new BrainError("invalid_request", routeRefusalText(routeVerdict));
                 const apiKey = routeCredential.apiKey;
-                const root = (model.baseUrl || config.baseUrl || "").replace(/\/+$/, "");
-                if (!root) {
-                    throw new Error("createOpenResponsesBrain: no baseUrl configured (set config.baseUrl or model.baseUrl)");
-                }
                 if (options?.stop !== undefined && options.stop.length > 0) {
                     throw new Error("createOpenResponsesBrain: options.stop is not expressible in the Open Responses request (the wire form has no stop-sequence field); " +
                         "remove it, or serve this model through the chat-completions lane, which does support it");

package/dist/brain/openai.js

@@ -7,7 +7,7 @@ import { emitBrainTelemetry } from "./status-sink.js";
 import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imagesOmittedNoVisionNote, modelSupportsVision, sendableImages } from "./media-degrade.js";
 import { OPENAI_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders } from "./request-params.js";
 import { BrainError } from "./errors.js";
-import { adjudicateModelRoute, applyRouteCredentialHeaders, createBrainRouteJudge, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
+import { adjudicateModelRoute, applyRouteCredentialHeaders, assertServableRequestRoot, createBrainRouteJudge, resolveRequestRoot, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
 import { declaredOffSpelling, mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
 function closeToolCallAccum(acc) {
@@ -281,6 +281,7 @@ export function inferMaxTokensField(modelId) {
     return "max_tokens";
 }
 export function createOpenAIBrain(config = {}) {
+    assertServableRequestRoot(config.baseUrl, "config.baseUrl");
     const doFetch = config.fetchImpl ?? fetch;
     const stream = (model, context, options) => {
         let sentMaxTokens;
@@ -295,6 +296,10 @@ export function createOpenAIBrain(config = {}) {
             httpLabel: "gateway",
             stallTimeouts: options?.stallTimeouts,
             buildRequest: (overrides) => {
+                const root = resolveRequestRoot(model.baseUrl, config.baseUrl);
+                if (!root) {
+                    throw new Error("createOpenAIBrain: no baseUrl configured (set config.baseUrl or model.baseUrl)");
+                }
                 const routeCredential = resolveRouteCredential({
                     optionsApiKey: options?.apiKey,
                     optionsHeaders: options?.headers,
@@ -306,10 +311,6 @@ export function createOpenAIBrain(config = {}) {
                 if (!routeVerdict.ok)
                     throw new BrainError("invalid_request", routeRefusalText(routeVerdict));
                 const apiKey = routeCredential.apiKey;
-                const root = (model.baseUrl || config.baseUrl || "").replace(/\/+$/, "");
-                if (!root) {
-                    throw new Error("createOpenAIBrain: no baseUrl configured (set config.baseUrl or model.baseUrl)");
-                }
                 const body = {
                     model: model.id,
                     messages: toOpenAIMessages(context, config.replayThinking, model),

package/dist/brain/route-adjudicator.d.ts

@@ -27,15 +27,15 @@
  *    deployment root — a distinct endpoint with no credential route is a configuration hole, and a
  *    loud refusal with a fix hint beats an unauthenticated request to a third-party host.
  *
- * Fail-closed direction: "no credential leak" outranks "silently works". A deployment that only
- * worked because the gateway key HAPPENED to be valid at another entry's host now refuses loudly,
- * and every refusal names the entry, both URL halves, and a one-line fix.
+ * Fail-closed direction: "no credential leak" outranks "silently works", and every refusal names the
+ * entry, both URL halves, and a one-line fix.
  *
- * Bad-value loudness (garbage / contradiction / absence):
+ * Bad-value loudness (garbage / contradiction / absence / misplacement):
  *  - garbage — non-string URL/credential inputs throw a `TypeError` here (a programmer error must
  *    not be laundered into a polite verdict); whitespace-only URLs normalize to "" (undeclared).
  *  - contradiction — the torn pair refuses with `route.credential_mismatch` + both halves named.
  *  - absence — `route.credential_missing` with the fix hint, exactly where absence is a hole.
+ *  - misplacement — a credential in the URL, or a non-http(s) root: {@link assertServableRequestRoot}.
  */
 import type { Model } from "../internal/llm.js";
 import type { RouteAdjudication, RouteCredential, RoutePairingConfig, RoutePairingPosture } from "../internal/llm.js";
@@ -50,6 +50,28 @@ import type { Brain, EngineNotice } from "../core/types.js";
  *  not parse as a URL keeps the raw trimmed spelling — the same fail-closed raw comparison as
  *  before. Non-string input throws — see the module note on garbage. */
 export declare function normalizeBaseUrl(url: string | undefined): string;
+/**
+ * The bad-value refusal every base-URL seat owes: **a request root must be an absolute http(s) URL, and
+ * it may not carry the credential itself.**
+ *
+ * Both halves fail the same way if they are not caught here — as a TRANSPORT failure, indistinguishable
+ * from an outage, retried for the whole backoff ladder. Measured: `file:`/`ftp:` reject with
+ * `TypeError("fetch failed")` over a causeless "unknown scheme", the exact shell a refused connection uses.
+ * Stripping userinfo instead of refusing would send an UNAUTHENTICATED request to the host the operator
+ * thought they had authenticated to. Refused where the value ARRIVES — construction for `config.baseUrl`,
+ * request build for `Model.baseUrl`. An undeclared root is not this rule's question; the PAIRING law keeps
+ * its tolerance for an unparseable spelling ({@link normalizeBaseUrl}). Answers the value it judged.
+ */
+export declare function assertServableRequestRoot(url: string | undefined, seat: string): string | undefined;
+/** Remove the userinfo from every authority in free text, WHOLE — the general redactor keeps a short or
+ *  unprefixed username, and `TOKEN@host` / `TOKEN:x-oauth-basic@host` are the canonical PAT spellings. */
+export declare function stripUrlCredentials(text: string): string;
+/** The request ROOT a brain targets — `Model.baseUrl` else `config.baseUrl` else the lane's default,
+ *  trailing slashes stripped — with {@link assertServableRequestRoot} applied to both declared
+ *  halves on the way. The three brains each carried a copy of this coalesce-and-strip line, so a rule
+ *  about base URLs had three homes; now it has one. Answers `""` when nothing is declared and the lane
+ *  has no default — whether that is a refusal is the caller's. */
+export declare function resolveRequestRoot(modelBaseUrl: string | undefined, configBaseUrl: string | undefined, laneDefault?: string): string;
 /** Whether a header bag carries an auth-bearing header (any case). */
 export declare function hasAuthCarrier(headers: Record<string, string> | undefined): boolean;
 /**

package/dist/brain/route-adjudicator.js

@@ -1,4 +1,5 @@
 import { AUTH_CARRIER_NAMES } from "./request-params.js";
+import { BrainError } from "./errors.js";
 export function normalizeBaseUrl(url) {
     if (url === undefined)
         return "";
@@ -16,6 +17,31 @@ export function normalizeBaseUrl(url) {
         return raw;
     }
 }
+export function assertServableRequestRoot(url, seat) {
+    if (typeof url !== "string" || url.trim() === "")
+        return undefined;
+    const trimmed = url.trim();
+    const parsed = URL.canParse(trimmed) ? new URL(trimmed) : undefined;
+    if (parsed === undefined || (parsed.protocol !== "http:" && parsed.protocol !== "https:")) {
+        const named = parsed === undefined ? "it did not parse as a URL" : `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
+        throw new BrainError("invalid_request", `${seat} is not a servable request root (${named}) — it must be an ABSOLUTE http(s) URL. Another scheme, ` +
+            `or a spelling that is not a URL at all, fails at the transport in a shape indistinguishable from an ` +
+            `outage, so it would be retried for the whole backoff ladder instead of refused here.`);
+    }
+    if (parsed.username === "" && parsed.password === "")
+        return trimmed;
+    throw new BrainError("invalid_request", `${seat} carries credentials in its authority (${parsed.protocol}//[redacted-credentials]@${parsed.host}${parsed.pathname}) — ` +
+        `a request cannot be built from a URL with userinfo, so every call through this brain would fail: put the ` +
+        `credential on the apiKey knob or an auth header and leave the URL bare`);
+}
+export function stripUrlCredentials(text) {
+    return text.replace(/([A-Za-z][A-Za-z0-9+.\-]*:\/\/)[^/\s"'@]*@/g, "$1[redacted-credentials]@");
+}
+export function resolveRequestRoot(modelBaseUrl, configBaseUrl, laneDefault = "") {
+    const entry = assertServableRequestRoot(modelBaseUrl, "Model.baseUrl");
+    const declared = assertServableRequestRoot(configBaseUrl, "config.baseUrl");
+    return (entry ?? declared ?? laneDefault).replace(/\/+$/, "");
+}
 export function hasAuthCarrier(headers) {
     if (!headers)
         return false;