@sema-agent/core 7.23.5 → 7.24.0

package/CHANGELOG.md

@@ -1,5 +1,82 @@
 # Changelog
 
+## 7.24.0 — 2026-09-19
+
+### The stream engine's last two `instanceof BrainError` reads (#935, follow-on; P2; no wire key)
+- **Before.** `src/brain/stream-engine.ts` kept two bare `e instanceof BrainError` tests after #935 swept the rest. Site A is in the `.catch` of a FLOATING promise (`void run().catch(...)`) — the one place a stream is ever told it failed — reading a value that a handed seat (`buildRequest` / `makeParser` / `doFetch`) may have raised. `instanceof` walks a prototype chain a revoked proxy traps, so a raise there costs the terminal frame entirely. **Measured**: with the old reading the probe never settles — no `error` event, an unhandled rejection, and a consumer waiting on `result()` forever (15 s test timeout). Site B is the in-band overload downgrade.
+- **After.** Both read the BRAND — `brainErrorCodeOf`, the code word against the closed list — and site A reads the four disclosure members through `readMember`. Site B loses a condition (the brand IS the code) and gains realm-independence: a server-coded error minted outside the class (a vm context, a transport that lost the prototype) used to answer `false` there and kill a turn that should have finalized the text it had already streamed. Rules: −1 condition, −2 unguarded prototype walks.
+- **Reach.** No wire key; the disclosure members ride exactly as before for a real `BrainError` (pinned). `test/backlog935b-stream-engine-guarded-brand.test.ts` drives a revoked proxy through both seats and pins the realm-independent downgrade.
+- **Sibling site (merge-tree review).** `degrading.ts` `terminalOf` recognised only `"error"` as an error terminal: a bare stream whose `result()` resolved an ABORTED message became `{ type: "done", reason: "aborted" }` — a done frame with a non-done reason. It now routes `"aborted"` through the one `errorFrameOf`. Wire-visible only for that shape (error frame, reason aborted); pinned in `test/backlog935c-degrading-abort-frame.test.ts`.
+
+### A request root that COMPARES and a request root that RENDERS are two different values (#950; P2; BREAKING export rename; no wire key)
+- **Before.** `normalizeBaseUrl` had one reading serving two jobs. The pairing law needs the query (it selects the endpoint), so the function kept `u.search` byte-identical — and every seat that RENDERS a root took the same function. `?api_key=<secret>` therefore rode the refusal `fixHint`, the exported `routeRefusalText`, all three `RouteRefusalDetail` URL fields, and the `route.base_url_changed_key_unchanged` catalog-swap notice, into whatever a host logs. The name is what licensed it: "normalize" reads as fit-for-anything.
+- **After.** Two functions, each with one job. `routeKeyOf` is the comparison value (query byte-preserved, never to be rendered — the doc says so). `displayUrlOf` is the only spelling allowed into text: composed from the parse, userinfo dropped, and **every** query value replaced with `«redacted»` — no secret-name list, because a list has a blind spot at exactly the name nobody thought of (measured, test 2026-09-19: a downstream name-list redactor passes `?x_vendor_key=<secret>` through verbatim — the one secret-shaped name of twelve that its list did not carry). Query NAMES ride, because dropping the query whole would render two roots that differ only in their query as one string, and the refusal about that very pair would read "targets X … paired with X". When the names match too, the refusal names the parameters whose values diverged instead. Rules: two names for two jobs replace one name for two jobs; both refusal mints and the catalog-swap mint went from "whatever normalize returned" to the same one-line rule (compare the key, render the display).
+- **Three repairs from the adversarial rounds, each reproduced first — one of them undoing a regression this change had introduced.** (a) The unparseable-spelling arm anchored its redaction on the LEADING run, so it only fired on a bare `user@host`; it now withholds by POSITION, and covers all THREE credential positions — userinfo, query, and FRAGMENT (implicit-OAuth puts a bearer token exactly there, and the parse arm drops fragments outright). (b) A first attempt moved the trailing-slash fold from the serialized URL to `u.pathname`, which **was wrong in the common case**: the fold is not this function's to choose — `resolveRequestRoot` strips trailing slashes off the SERIALIZED root and the brains append their endpoint suffix to that. Measured through the real builder, the path-level fold made `…/v1/?tenant=a` and `…/v1?tenant=a` compare EQUAL while their requests differ (a false `paired`, a credential authorized onto another path) and `…?tenant=a/` and `…?tenant=a` compare UNEQUAL while their requests are byte-identical (a refusal over a difference the wire cannot see). The fold is back where the resolver has it, and the invariant — **two roots share a key iff their requests are the same request** — is now pinned as a table with its one registered exception (a root CARRYING a fragment defeats the resolver's own strip; that is the request-construction defect below, not this fold's). (c) The residual note claimed "query" for every collapse, including two unparseable roots differing only in withheld userinfo — where there is no query at all; it now names the query parameters when it can and says only that the difference is in a withheld or folded part when it cannot.
+- **A fourth repair, from the main session's own counterexample sweep.** A BARE query token (`?<token>`, no `=`) was rendered with its payload in the NAME position: `URLSearchParams` reports it as a name with an empty value, so "every value is withheld" protected nothing and the token reached `fixHint`, all three detail members and `routeRefusalText`. What rides is now judged on the RAW segment — a segment with no `=` renders as one placeholder with no name, and the explanation sentence will not name it either. Reading raw segments also retired the decode-then-re-encode step the previous shape needed. Positions this deliberately does NOT withhold — path segments, matrix parameters, subdomains, and the NAME of a `name=value` parameter — are the endpoint's identity, and redacting them would leave a refusal nobody can act on; that is `KL-950a`, with the deployment rule that a credential belongs on the `apiKey` knob or an auth header.
+- **Registered, not fixed here.** `assertServableRequestRoot` returns the RAW trimmed spelling, so `resolveRequestRoot` can hand the brains a root carrying a query and/or fragment, which they then append `/chat/completions` after (`https://h/v1?tenant=a/#note/chat/completions`). That is a defect about request CONSTRUCTION, and what a base URL may carry is a contract decision above this change.
+- **The example that teaches this got the law too.** `src/examples/custom-brain-provider.ts` hand-rolled `${(cfg.baseUrl ?? model.baseUrl).replace(/\/$/, "")}/chat/completions` — no request-root check, a one-slash strip where the engine strips all of them, and the precedence backwards (the ENTRY's `model.baseUrl` wins over the deployment's, which is what the pairing law assumes). `resolveRequestRoot` is therefore now **exported**: a custom brain is a seat that builds a request root and owes the same question, and an example cannot teach a law it has to deep-import to reach.
+- **Reach — BREAKING.** The export `normalizeBaseUrl` is **removed**; `routeKeyOf` is the same function under the name that says what it is, and `displayUrlOf` + `resolveRequestRoot` are new (net −1/+3, count 2395 → 2397). `@sema-agent/server` imports `normalizeBaseUrl` (`src/hooks/hook-llm.ts`) and must rename the import; its behavior is unchanged. `RouteRefusalDetail.{entryBaseUrl, requestBaseUrl, configBaseUrl}` now carry the DISPLAY spelling — they were never route-identity values to compare against a catalog, and now they say so. A consumer that needs identity computes it with `routeKeyOf`. One conformance vector added (`deployment-mismatch-query-differs`): an implementation comparing origin+path only pairs a credential with someone else's tenant.
+- **Sibling site (merge-tree review).** `primaryActivityArg` (`src/core/arg-summary.ts`) composed `origin + pathname`; an OPAQUE scheme (`weird:`/`blob:`/`mailto:` — `host` empty) rendered `nullu:<secret>@h/v1`. Same rule as the renderer: no authority ⇒ withhold by position. Narrowing on the activity line for opaque URLs only; `test/backlog950b-activity-arg-opaque-scheme.test.ts`.
+
+### The memory-distillation chat seat asks the request-root question the brains ask (#943; P2; no wire key)
+- **Before.** `openAiCompatChatSeat` screened its `baseUrl` for emptiness and nothing else, then built `${baseUrl}/chat/completions` by hand. A root carrying userinfo, a `file:`/`ftp:` scheme, or a spelling that is not a URL at all constructed cleanly and failed at `fetch` — as a transport error indistinguishable from an outage, so the consolidation driver retried it for the whole backoff ladder. #933 ② closed the same three shapes at the three brain factories; the distillation seat builds a request root too and was not asked.
+- **After.** The root goes through `assertServableRequestRoot`, the same law, judged at CONSTRUCTION. The ENVELOPE stays this seat's (`config.memory_consolidation_driver`, like its sibling api-key / alias-model screens) because a host screens on that code and the driver routes config-class throws differently from transport ones; only the envelope is local, the question and its wording are the adjudicator's. The trailing-slash strip moves to construction with it, so the root is read once instead of once per call.
+- **Reach.** `RunnerDeps.memoryConsolidationDriver.chat = { baseUrl, apiKey, model }` with one of the three bad roots now refuses where it is configured instead of on the first distillation run; a userinfo root is named as `[redacted-credentials]@host`, never echoed. Servable roots are untouched.
+
+### The `compacted` event publishes the delta the engine MEASURED (#946; P2; additive wire key `freedTokens`; @cli @server @client-core)
+- **Before.** The event carried `triggerTokensBefore` and `tokensAfter` and documented them as a matching pair to subtract. They are not one: the trigger gate reads a usage-ANCHORED figure whenever the provider's last usage is fresh, while the post size is always structural + the fixed prompt overhead (`promptOverheadTokens`, added unconditionally). Subtracting across them mixes coordinates and goes NEGATIVE on ordinary runs — **measured on the plain auto lane: `3037 − 4591 = −1554`**, and again on a short-session `/compact` (`4237 − 4987 = −750`), with no error anywhere in the pass. `force` / `forceUnderThreshold` remove the floor that used to hide it. The engine's own self-consistent delta, `freedTokens`, existed inside the compaction all along and never rode the wire.
+- **After.** `freedTokens` is on the `compacted` event from all three mint points (turn boundary, PTL recovery lane, end-of-task settle) — one structural sum minus the same structural sum, clamped ≥ 0 at the mint. The two raw sizes stay, un-clamped and un-deleted, retyped as DIAGNOSTICS with "not subtractable" said at the type and in `docs/INTEGRATION-CORE.md`: they answer *what tripped the trigger* and *how big is it now*, which are different questions from *how much was freed*.
+- **No fabricated numbers.** When the post measurement fails, `freedTokens` is now ABSENT rather than `preChars` ("fully effective" — never true of a landing that leaves a summary behind). The two floor sites dropped their `postTriggerTokens ?? (triggerTokens − freedTokens)` fallback, which re-assembled the very mixed-coordinate subtraction and only ever ran when BOTH of its inputs were unmeasured. No measurement ⇒ the anti-thrash floor does not move, which is the same non-suppressing direction the fabricated value was chosen for, without the claim.
+- **One mint, not three copies.** The `compacted` frame was spelled out verbatim in all three lanes, so adding this key meant editing three identical literals and guarding them with a test that grepped their SOURCE TEXT for a matching line. They now call one `mintCompactedEvent(comp, trigger, identity)` (`src/core/auto-compaction.ts`) — `trigger` and the identity envelope are the only things that differed. Rules: −2 copies of the frame, and the drift guard becomes a real invariant (`type: "compacted"` appears exactly once in `src/`, and one `comp` through all three triggers yields the same key set). Both module ceilings that the first shape had raised are banked back down, 18 lines each.
+- **The hook seat had the same pair, and took the same fix.** `Hooks.postCompact`'s `PostCompactContext` carried `tokensBefore` + `tokensAfter` with no warning at all — and its pair is worse than the frame's, because `tokensBefore` there is prepareCompaction's coordinate, which lacks the overhead term the post size always carries. It gains the same `freedTokens?`, read from the same `freedTokens` the pass computed (one source, not a second mint), and both old members now say "DIAGNOSTIC, NOT subtractable" at the type. Pinned by equality: the hook's delta and the `compacted` frame's are the same number for the same pass.
+- **Reach.** Additive on the wire. `RunnerDeps.onCompaction`'s `freedTokens` becomes optional in TypeScript (it can now be absent, and was previously a fabricated number in exactly that case) — a consumer doing arithmetic on it should handle absence. **@cli**: `/context`'s compaction line should read `freedTokens` instead of drawing its arrow from the two diagnostics. **@server @client-core**: forward the new key. `test/backlog946-compaction-freed-delta.test.ts` measures both negative deltas, pins the three mint points as a SET, and drives the failed-measurement arm.
+
+### An unwired — or inert — file-history store says so, once (#947; P2; no wire key)
+- **Before.** `RunnerDeps.fileHistoryStore` needs two halves to do anything: the store, and a filesystem-capable `ExecutionEnv`. When they disagreed, core said NOTHING. The capture-side note retired with the capture REQUEST it disappointed, leaving exactly one loud moment — somebody asks for a restore and gets `rewind.store_unconfigured`. Until then a deployment edits files believing the engine records them (`trackFileEdit` is simply absent: zero verbs, zero notes, zero words), and a host that wired a store into a stub-env shape holds a store nothing will ever write to.
+- **After.** One predicate over the disagreement, announced on the config channel the sibling prepare phases already use (`deps.onError`, `phase: "config"`, advisory, never a refusal). The ARM names the half that is missing, because the fix differs: no store ⇒ "nothing is recorded, and a later `restoreFiles`/`rewindFilesTo` will refuse"; no env ⇒ "the store is INERT". Both halves absent is NOT a disagreement — no tree, no store, no expectation — and stays silent on purpose; that arm is pinned as a negative control so the silence is a decision rather than a gap.
+- **Said once per Runner, per arm.** A parent plus N same-tree delegated children run through one Runner and would otherwise hear the same configuration fact N+1 times. The memo is keyed on the `onError` seat object, and a Runner wraps that seat exactly once at its deps boundary, so every run through one Runner shares one identity — **three Runners handed the same raw sink are three wrappers and therefore three sentences** (measured). It is not once per deployment. The seat is also the only key available: the no-store arm has no store, and with the machinery off the coordinate resolver answers the run's own session id and never the lineage's, so a parent and a same-tree child do not share a history scope.
+- **Reach.** A Runner with hands and no store gains ONE operator line, on its first run. Nothing refuses, no note reaches `TaskResult`, no model-facing text changes, no wire key. `test/backlog947-file-history-unwired-disclosure.test.ts` pins both arms, both controls, one sentence across three runs of one Runner, a second Runner hearing it on its own, and the two arms deduplicating apart.
+
+### A peer row with no activity word reads `unknown`, instead of being called `idle` (#940; P2; no wire key; @cli)
+- **Before.** The peer lane's state was a ternary — `dead ? "offline" : tempo === "active" || tempo === "blocked" ? "busy" : "idle"` (`src/agents/list-agents-tool.ts`). `tempo` is a member a HOST writes, and neither sema host writes one, so the else-arm was the COMMON path: every live peer session on the machine was reported to the model as `idle` — "that session is doing nothing" — about sessions nobody had asked.
+- **After.** The peer half of #917's rule: one table (`PEER_ROW_STATE`: `active`/`blocked` → `busy`, `idle` → `idle`), an OWN-key lookup for the same reason `agentRowState` uses one (a directory seat is a host face, and a row that never passed `readPeerSessionRecord` can carry `constructor` as its tempo), and `unknown` for anything the table cannot answer — including the absent word. Liveness still pre-empts: a dead row is `offline` whatever it last wrote. Rules: the two lanes now state ONE rule ("a row's state is a table lookup over the word the row carries; anything else is `unknown`") instead of a table on one side and a hand-written ternary on the other.
+- **The key STAYS.** `PeerSessionRecord.tempo` was proposed for retirement as a dead key (no sema writer). It is not dead: CC 2.1.259 writes it from its own session-activity classifier, with the identical word set `active | idle | blocked` (`blueprints/cc-decoded/cli259.js` offset 22754933, through the export `updateSessionActivity` — export table at offset 30739365). The engine owns the row SCHEMA and a host owns the VALUE, so the missing writer is a host-side gap, not a dead abstraction — **the CC-parity writer is pending on the shell side (@cli)**. Retiring the key would have been a divergence from an answered CC question, and the shell would have had to re-add it.
+- **Reach.** No wire key added or removed; `ListAgentsRow.state` keeps its exact union. One value change on one lane: a live peer row whose host wrote no `tempo` now reads `unknown` instead of `idle` (rendered line: `name [ref]  ·  unknown  ·  peer session  ·  session.<id>`). Consumers that render the word are unaffected in shape; a consumer branching on `idle` to mean "free to take work" was being told that about every peer. `test/backlog940-peer-row-state.test.ts` pins the absent word, the table, the liveness pre-empt, five prototype-key tempos and an agent-lane negative control.
+
+### A member turn is re-dispatched only where a second attempt could come out differently (#941; P2; no wire key)
+- **Before.** `runTurn` (`src/agents/team.ts`) retried every turn that did not settle `completed`-with-text, once, with the identical objective, prompt, model and toolset — including terminals that cannot come out differently. A `blocked` cause waits for nobody by its own definition, and a code the governance table adjudicated TERMINAL is a policy question the control plane has already answered: each cost a whole extra member run to reproduce the same word, and the governance family re-asked an answered question of the control plane.
+- **After.** The retry is refused only for the two terminals the engine can POSITIVELY identify as deterministic: a `blocked` cause, and a `failed` whose code the governance table adjudicated TERMINAL (read off `classifySubagentError`, the classifier the delegation faces already answer with — no second opinion about any code). Everything else keeps its second attempt, INCLUDING the classifier's `logic` bucket: that bucket is an else-arm — every code with no row of its own lands in it — so hanging "never retry" on it would make each future brain code silently non-retryable here. An independent review measured exactly that: `stream_torn` (a response lost before any content or finish reason, the textbook re-issuable failure) lives in that bucket and lost its retry under a first draft of this change. Rules ±0.
+- **Reach.** No wire key, no text change: a blocked or policy-refused member still renders the same `[unavailable: <status>/<code>]` marker, and the discussion, transcript and budget accounting are unchanged in shape. What changes is spend — such a turn now costs one child run instead of two (measured on a scripted runner: 3 runs instead of 6 for a two-member, one-round discussion). `test/backlog941-deterministic-terminal-no-redispatch.test.ts` pins the blocked arm and four terminal governance codes, with six retryable codes, the whole `logic` else-arm (`stream_torn` / `refusal` / `length_empty` / a code this engine has never seen), the code-less failure and the empty-completed turn as positive controls.
+
+### The last bare reads of a value the engine did not construct (#942; P2; no wire key)
+- **Before.** #926 and #935 made `src/core/thrown-value.ts` the engine's one rule for reading an untrusted value; nine sites had not taken it, and two of them were the load-bearing kind. A third-party `execute`'s RETURN value was read bare (`ret.content` / `.details` / `.terminate` / `.isError`) by a `normalizeContent` that ran OUTSIDE `defineTool`'s own try — so a member behind a throwing getter, a revoked proxy handed back as `content` (`Array.isArray` traps one), or a single hostile content BLOCK raised a raw `TypeError` past the tool wrapper. The `prepare()`-throw walk in `stream-settle-backstop.ts` had no guard at all, inside the backstop whose entire job is to make a thrown prepare land as a result. `errorCodeOf` wrapped its whole `cause` walk in ONE coarse `try`, where a hostile `code` at depth 1 lost every code beneath it. The card projector, the exec-gate step's catch and the MCP failure-copy read `details` / `name` / `code` bare, all three ON a failure path. And four workflow rows read a thrown cause through `instanceof Error` — the test a genuine Error minted in the script's `vm` realm fails, so the row went anonymous exactly where the cause came from the script.
+- **After.** All of them read through `readMember` / `isErrorLike`. Two structural changes rather than more guards: `defineTool`'s whole result-building path — normalize, empty-output guard, the returned object — now runs inside the ONE try it already had, so every read of the returned value leaves through the formatted-tool-error door instead of escaping the wrapper (measured: an `AbortError`-named raise from a content block now reads `Interrupted`; it used to escape with the thrower's own words); and `errorCodeOf`'s coarse `try` is gone in favour of per-member reads, so an unreadable link costs THAT link and the walk continues (measured: `{ code: <throws>, cause: { code: "x" } }` answers `x`, and used to answer nothing). Rules: −1 coarse `try`, and the two class-level rules this sweep needed now have ONE home each beside the other readers — `thrownIs` (a total `instanceof`) and `thrownName` — with the four private copies that existed or were first written locally (`tool-errors`'s `isErrorInstance`, `auto-mode`'s timeout test, `exec-gate`'s, `workflow`'s) folded into them.
+- **Two of the nine were NOT bare, and stay as they are.** `run-harness-handlers.ts:390` reads `.details` off an object the engine mints at `defineTool`'s exit (the one adaptation point every first-party, caller and MCP tool passes through), and the deeper `filePath` read below it is gated to three first-party tool names. Stated rather than silently skipped.
+- **Four more sites, found by an independent adversarial review of this change and verified against the code before being taken.** The `retryAfterMs` read TWO statements below the walk that was just guarded, inside the very object literal that becomes the result — unconditional, ahead of the code test beside it, so the backstop that exists to make a thrown prepare LAND would itself have been the throw. `thrownErrorCode` (`subagent.ts`), one helper feeding three REJECT legs that run before registry settlement and the terminal notification, the background one inside the final catch handler. The exec-gate's class-POSITIVE arm, which still read `e.code` bare — recognizing a class does not make its accessor safe. And all thirteen `instanceof WorkflowXError` tests in `workflow.ts`, whose FIRST act on a failed leg is the class test. One of those is reached by a PUBLIC primitive: `ctx.parallel` / `ctx.pipeline` build their settled list from a script-supplied thunk, so whatever the script throws — and the script runs in its own vm realm with fresh intrinsics — lands verbatim on the fan-out fold's class test. Spelled `instanceof`, a revoked proxy raised out of the fold and rejected the whole batch, breaking the contract stated four lines above the call site ("a fan-out slot NEVER rejects the batch — every failure folds to null"). Measured both ways: the new pin folds the hostile thunk to `null` and reds on the bare spelling. On the two CATCH LADDERS the same guard is reasoned rather than reproduced — no construction staged from a test reaches them with a hostile value — and the control test there says so in as many words.
+- **The shared rule, not a fifth copy.** The guarded class test now lives beside the other readers as `thrownIs` (`src/core/thrown-value.ts`), and the three private copies that already existed or would have been added — `tool-errors.ts`'s `isErrorInstance`, `auto-mode.ts`'s `isAutoModeTimeout`, and the two this change first wrote locally — are gone or now delegate. Net implementations of that rule: −2, where a first draft was +2. Three more same-class sites were swept with it: `observer.ts`'s `errorName` (compared against name CONSTANTS precisely because the value crosses a host seam, yet gated on this realm's `Error`), `session.ts`'s `isSessionConflict` and `session-store.ts`'s `isNotFound` (an `in` test — a `has` trap — plus the getter behind it), and the ten twin renders in the in-memory `FileHistoryStore`, whose own containment comment promises that a misbehaving host `ExecutionEnv` costs only the file it threw on.
+- **The TENTH station, found on the real lane, not in the diff.** `reduceToolEnd` (`turn-attachments.ts`) reads a third-party `details` inside the harness's tool_end handler — outside the tool wrapper's try, and a SECOND time after the result store already walked the card. Measured end to end with a Runner, a scripted brain and a third-party `ToolSpec`: a `type` getter that answered once and raised on the second read ended the whole run as `failed` / `provider.error` on turn one, and the model never reached turn two. Every read in the reducer is now guarded, lists COUNTED and INDEXED rather than `Array.isArray`-ed and iterated (all three are proxy traps), the scan clamped rather than refused, and an unreadable card leaves the state exactly as it was. Both task cards now build their projected item through one `readTaskEntry` instead of two copies. The module ceiling moves 2221 → 2234 with that reason on the table line; the previously reported `run-harness-handlers.ts:390` is NOT itself a bare read — it reads an engine-minted result — which is what the earlier pass said, having stopped at the line instead of following the value into this reducer.
+- **The ELEVENTH station, same shape, the ERROR arm.** `toolEndBodyFrom` (`tool-end-body.ts`) lifts three discriminators — `code`, `errorKind`, `delivered` — off the same third-party `details`, in the same handler, outside the same try. Measured: a `code` getter raising on its SECOND read ended the run on turn one. All three reads are guarded; unreadable is absent, which is the arm the string filters already had. A TWELFTH candidate was investigated and is NOT reachable, measured both ways: the LSP nudge's `details.filePath` read needs the lane wired (which needs hands) AND one of three tool names — and with hands mounted those names belong to the first-party fs tools, whose details this engine mints (a caller tool offering the name is shadowed; measured), while without hands the lane is closed. Both halves are pinned as negative controls so a change to either is visible.
+- **The snapshot bag is DEFINED, not assigned.** `readOwnMembers` copied member by member with `out[key] = …`, and `__proto__` is an accessor on `Object.prototype` — so a value carrying an OWN `__proto__`, which is exactly what `JSON.parse` yields for `{"__proto__":{…}}` and exactly how a provider's error body arrives, swapped the bag's prototype instead of being copied: measured, `bag.errorKind` then read `"forged"` off the injected object, the key that did it vanished from `Object.keys`, and the bag was no longer an ordinary object. The copy now defines each key, so `__proto__` lands as an ordinary own data key and the bag stays on `Object.prototype`. It reaches a frame through `thrownMarksOf`, whose whole job is to carry a thrown value's `details` onto a tool result — and `errorKind` is the key that result's discriminator lift reads.
+- **The abort word is decided by the NAME.** `formatToolError` folded a cancellation to `Interrupted` behind a realm-bound class test, so an `AbortError` minted elsewhere rendered as its own text and read like a failure; it now asks `thrownName`, and the file's remaining brand tests are `isErrorLike` — one brand rule where there were two.
+- **Reach.** No wire key, no code word, no text change for any readable value. Three text changes where the value was hostile, each named above. One unannounced narrowing, stated: a tool result's `terminate` is now read `=== true` rather than `?? false`, so a BYOM tool returning a truthy non-`true` no longer terminates the batch — every in-tree consumer already tested `=== true`, so nothing observable moves. `test/backlog942-guarded-reads-residue.test.ts` drives the three shapes (null prototype / throwing getter / revoked proxy) through the tool wrapper, both `cause` walks, the card projector and the exec-gate step (both arms), with a positive control on each arm.
+- **Regression caught at review, fixed before the tag.** The guarded list reader accepted anything with an integer `length`, so a STRING `newTodos` (`"bad card"`) cleared the todo snapshot where the base ignored it. A list is an object with a length; strings and numbers are not lists (pinned). A card with unreadable ITEMS still ingests the readable subset (KL-942e).
+
+### The two identities of a background delegation child are written down (#948; P2; docs only; @client-core @cli)
+- **Before.** A background child carries a registry HANDLE (`a…`) and a session/run id (uuidv7), on different faces, and nothing stated which face carries which or what joins them. A consumer folding them into one address is wrong on one of the two faces — the question client-core asked, and the anchor cli's verification needs.
+- **After.** `docs/INTEGRATION-CORE.md` §1.6a: one table (fleet row frame / `task_progress` / roster row × handle / session id / join key) plus three contract sentences — ① the registry id is a handle (`TaskOutput` / `TaskStop` / `SendMessage`) and a session id is a transcript/run id (`AgentTranscript`, resume), neither derived from the other, anchored once at spawn by `bindBackgroundAgentSession`; ② `task_progress.taskId === BackgroundChildEvent.transcriptId`, because a run's task id is `spec.taskId ?? sessionId` and all three background lanes set no `spec.taskId` (each says so at its own launch site); ③ roster / fleet `address` is the registry `task_id` verbatim. Every claim carries its coordinate, each one re-verified against the tree. One sentence each on the `task_progress` and `ListAgentsRow.address` JSDoc points at the table.
+- **Reach.** Documentation only — no code path, no wire key, no text. Nothing to consume; it states what was already true.
+### The two credential vocabularies name the same vendors (#954; P2; narrowing; @server @cli @test)
+- **Before.** This engine carries two credential-shape tables with two different head risks — the REFUSE-WRITE table (`detectSecret`, whose hit fail-closed rejects a durable memory write, so its head risk is the false positive) and the REDACTION table (`scrubSecrets`, spread into `redactSecrets` and `redactHostLeaks`, whose miss puts a credential in persisted and forwarded text). Neither had ever been pinned against the other, and four vendors had drifted apart. Measured on synthetic shapes: `github_pat_<60+>` (a fine-grained PAT) and `AccountKey=<base64 40+>` (an Azure connection-string key) were confident enough to REJECT a memory write and rode all three redaction faces **verbatim**; a PGP private-key block — banner `-----BEGIN PGP PRIVATE KEY BLOCK-----`, the exact form a write-gate bypass was once fixed for on the other table — rode them verbatim **header, body and footer**; and `hf_<20+>` was stripped from every egress text while being **accepted** into durable memory.
+- **After.** Four rows, no new mechanism. The fine-grained PAT prefix joins the existing prefixed-token row's vendor list (widening its `gh[opsur]` class cannot reach it — the character after `gh?` is `t`, not the separator the row requires — and would pull every `gh?_` identifier in). The private-key row's banner takes the optional ` BLOCK` suffix on BOTH ends: widening only the opening banner leaves the closing one unmatched and the row's end-of-input fallback then eats every byte after the block. Azure gets its own high-confidence row mirroring the refuse-write shape exactly, because the keyword-value arm's lookbehind deliberately refuses a keyword glued to a preceding letter (`Key` behind `Accoun`) and dropping that would flag every `…key=` word in prose; the field name is preserved and only the value replaced, as that arm already does. And `hf_` joins the refuse-write table with that table's word boundaries AND a digit requirement — the same second discriminator its bearer row carries, and the narrower of the two spellings, which is the correct direction for the face whose head risk is the false positive. The first cut of that row had only the separator-free body and flagged plausible identifiers (`hf_HubApiListModelsPaginated`, `hf_ModelCardMetadataParser`, `hf_datasetsloadingscriptcachedirectory` — all measured as rejected memory writes); an adversarial round caught it before this shipped. A real token is a random base62 body and carries a digit; a camel-cased or lowercase symbol name does not.
+- **Pinned in both directions.** `test/backlog954-credential-vocabulary-parity.test.ts` claims **every live row of both tables by identity** — the refuse-write table's label plus its regex source (parsed out of the module text, since that table is deliberately not exported), the redaction table's regex source off the exported passes — and asserts claims and live rows are the same set both ways, so a row added to or edited in one table alone reds by name. On top of that: every shape the narrow table names is stripped by all three redaction faces; every vendor row of the broad table is recognized by the narrow one **or** carries its own written reason (four are deliberate and are pinned as such: the publishable `pk_` class, a bare `Bearer` word with no `Authorization:` anchor, the two faces' different body floors, and the hyphenated word slug that is the refuse-write face's named head false positive — class-wide waivers are not accepted); fourteen false-positive neighbours stay clean on both faces; the composed tiers are shown to inherit by spread, not by copy, on shapes only the new rows catch; each credential is asserted stripped at EVERY occurrence, not just the first; and the two tiers' own four rows (URL credentials, signed-URL parameters, whole URLs, filesystem paths) are pinned by name so a new one there reds too. A row's identity is its regex text TOGETHER WITH its flags — dropping a `g` leaves the text byte-identical while turning a redaction into a first-occurrence-only one.
+- **Reach — narrowing, two faces.** Egress text: `github_pat_…`, `AccountKey=…` and a PGP private-key block now leave as `[redacted]` where they previously left verbatim. Two extent changes come with that, both measured: the new prefix creates matches that start EARLIER, so `see github_pat_docs-2024-release-notes-here for details` is now redacted whole rather than untouched (over-redaction, the direction this face declares cheap — the same class as the hyphenated word slug it already accepts); and the widened closing banner BOUNDS a match that previously ran to end-of-input, so a mismatched banner pair no longer eats the rest of the argument after the block. Every consumer of activity summaries, MCP error text, checkpoint command summaries and repetition segments sees the marker instead of the value; a consumer matching on those values in engine-produced text will stop matching, which is the point. Durable memory: a note carrying `hf_<20+>` now throws `MemoryGateError("memory.secret_detected")` at the write door — the `remember` tool, consolidation ADD and consolidation UPDATE alike — where it was previously stored. No wire key, no export, no code word added.
+- **Refuse ⊆ redact, one more row (merge-tree review).** The PEM banner qualifier admitted digits on the refuse-write face (`RSA2 PRIVATE KEY`) but only letters on the redaction face; the redaction row reads the same alphabet now (`test/backlog954b-pem-qualifier-digits.test.ts`). A Google key whose 35-char body ends in `-` is redacted but not refused (KL-954f).
+
+### A failed workflow run's machine code is on BOTH poll faces (#932 follow-on; P2; additive key; @server @cli)
+- **Before.** `formatWorkflowRun` put `errorCode` on the structural `details` face and not in the `content` JSON, while the comment beside the structural one asserted the code "reached the `content` JSON text" — it never did. A consumer reading the JSON face had only the fenced human text to classify a failed run, and the code told it otherwise.
+- **After.** The same key, the same absence rule, on both faces; the comment states what the code does. `test/backlog932-workflow-summary-error-code.test.ts` pins both faces equal on a coded failure and the key absent on both for a codeless failure and a completed run.
+- **Reach — additive.** A new optional key on the `content` JSON of a failed workflow `TaskOutput`; nothing is removed or renamed, and a run with no code carries it on neither face.
+
 ## 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)

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

@@ -49,11 +49,14 @@ export interface ListAgentsRow {
     name: string;
     /** Peer rows only: the listing-minted ref. */
     ref?: string;
+    /** What SendMessage accepts: on both AGENT lanes the registry `task_id` VERBATIM (no prefixing or
+     *  re-minting), never the child's session id — a different domain, tabled in INTEGRATION-CORE §1.6a.
+     *  Peer rows carry the `session.<id>` box handle instead. */
     address: string;
-    /** 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. */
+    /** What the row IS, right now. Both lanes are a table lookup over the word the row carries
+     *  ({@link PEER_ROW_STATE} / {@link AGENT_ROW_STATE}), and `unknown` answers whatever the table cannot
+     *  — on the peer lane the common case, since no host writes the activity word. `finished` means
+     *  COMPLETED and nothing else: a model applies the continuable rule to that word. */
     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

@@ -21,6 +21,17 @@ const AGENT_ROW_STATE = {
 function agentRowState(status) {
     return Object.hasOwn(AGENT_ROW_STATE, status) ? AGENT_ROW_STATE[status] : "unknown";
 }
+const PEER_ROW_STATE = {
+    active: "busy",
+    blocked: "busy",
+    idle: "idle",
+};
+function peerRowState(r) {
+    if (r.liveness === "dead")
+        return "offline";
+    const tempo = r.tempo;
+    return tempo !== undefined && Object.hasOwn(PEER_ROW_STATE, tempo) ? PEER_ROW_STATE[tempo] : "unknown";
+}
 export function createListAgentsTool(opts) {
     return defineTool({
         name: LIST_AGENTS_TOOL_NAME,
@@ -55,7 +66,7 @@ export function createListAgentsTool(opts) {
                     name: r.name,
                     ref: c.ref,
                     address: peerSessionBoxHandle(r.sessionId),
-                    state: r.liveness === "dead" ? "offline" : r.tempo === "active" || r.tempo === "blocked" ? "busy" : "idle",
+                    state: peerRowState(r),
                 });
             }
             let registryCapped = false;

package/dist/agents/observer.js

@@ -3,7 +3,7 @@ import { defineTool } from "../core/tools.js";
 import { createSafeNotifier } from "../core/safe-notify.js";
 import { escapeEnvelopeTag } from "../core/untrusted-text.js";
 import { toolFace } from "../core/tool-catalog-entries.js";
-import { thrownText } from "../core/thrown-value.js";
+import { isErrorLike, thrownName, thrownText } from "../core/thrown-value.js";
 export const OBSERVER_EVENT_TAGS = ["tool-call", "user-message", "tool-result", "turn-ended"];
 const TAG_ESCAPE_RE = new RegExp(`<(?=/?(?:${OBSERVER_EVENT_TAGS.join("|")})(?:[>\\s/]|$))`, "gi");
 export function escapeObserverTags(text) {
@@ -224,9 +224,6 @@ export class ObserverResumeStateError extends Error {
         this.name = OBSERVER_RESUME_STATE_ERROR_NAME;
     }
 }
-function errorName(err) {
-    return err instanceof Error ? err.name : undefined;
-}
 export const OBSERVER_FRESH_START_NOTE = "[Note: your previous observation context was lost; this is a fresh start mid-task.]";
 export class ObserverPairing {
     state = "armed";
@@ -300,7 +297,7 @@ export class ObserverPairing {
                     await this.deliverBatch(digest);
                 }
                 catch (err) {
-                    if (errorName(err) === OBSERVER_STOPPED_BY_USER_ERROR_NAME) {
+                    if (thrownName(err) === OBSERVER_STOPPED_BY_USER_ERROR_NAME) {
                         this.state = "stopped";
                         this.buffer = [];
                         this.safeOnError(err);
@@ -330,7 +327,7 @@ export class ObserverPairing {
             await this.spawner.deliver({ digest });
         }
         catch (err) {
-            if (errorName(err) !== OBSERVER_RESUME_STATE_ERROR_NAME)
+            if (thrownName(err) !== OBSERVER_RESUME_STATE_ERROR_NAME)
                 throw err;
             const restart = this.spawner.restartFresh?.bind(this.spawner);
             if (restart === undefined)
@@ -341,8 +338,8 @@ export class ObserverPairing {
             }
             catch (restartErr) {
                 this.firstRunDone = false;
-                throw restartErr instanceof Error
-                    ? new Error(`${restartErr.message} (after resume-state loss: ${thrownText(err)})`, { cause: restartErr })
+                throw isErrorLike(restartErr)
+                    ? new Error(`${thrownText(restartErr)} (after resume-state loss: ${thrownText(err)})`, { cause: restartErr })
                     : restartErr;
             }
         }

package/dist/agents/subagent.js

@@ -67,7 +67,7 @@ import { LAUNCH_RECEIPT_OWN_WORDS_CLAUSE, launchReceiptNoQuoteClause } from "./l
 import { ObserverDigestTap, ObserverPairing, createObserverReportToolSpec, markObserverTaskId, unmarkObserverTaskId, isObserverTaskId, ObserverResumeStateError, ObserverStoppedByUserError, observerFramingPrompt, observerSlug, resolveObserverDeclaration, } from "./observer.js";
 import { SubagentStepRecorder } from "./subagent-steps.js";
 import { toolFace } from "../core/tool-catalog-entries.js";
-import { thrownText } from "../core/thrown-value.js";
+import { readMember, thrownText } from "../core/thrown-value.js";
 const BG_AGENT_RESULT_MAX = 4_000;
 const BG_AGENT_RESULT_FULL_MAX = 200_000;
 function resultSettleFields(result) {
@@ -386,7 +386,7 @@ export function classifySubagentError(terminal) {
     return { errorKind: "logic", retryable: SUBAGENT_RETRYABLE.logic };
 }
 function thrownErrorCode(e) {
-    const code = e !== null && typeof e === "object" ? e.code : undefined;
+    const code = readMember(e, "code");
     return typeof code === "string" ? code : undefined;
 }
 export function completedAgentCard(child, extras) {

package/dist/agents/team.js

@@ -1,5 +1,6 @@
 import { resolveToolSubset } from "./tool-filter.js";
 import { mapNestedSuspend, isDurablePause } from "./suspend-guard.js";
+import { classifySubagentError } from "./subagent.js";
 import { terminalProjection } from "../core/runner/terminal-projection.js";
 import { sanitizeUntrustedText } from "../core/untrusted-text.js";
 const DISCUSSION_WRAPPER_TAGS = ["statement", "discussion", "discussion-final", "earlier-discussion-summary", "previous-summary", "topic"];
@@ -101,6 +102,12 @@ export async function runTeamDiscussion(opts) {
             checkpointGate: p.terminal.gate,
         };
     };
+    const canDifferOnRetry = (terminal) => {
+        if (terminal.kind === "blocked")
+            return false;
+        const err = classifySubagentError(terminal);
+        return !(err?.errorKind === "governance" && err.retryable === false);
+    };
     const runTurn = async (objective, systemPrompt, modelRef, role, tools, mcp) => {
         let last = "";
         for (let attempt = 0; attempt < 2; attempt++) {
@@ -134,6 +141,8 @@ export async function runTeamDiscussion(opts) {
             }
             const face = terminalProjection(res.terminal);
             last = `[unavailable: ${face.status}${face.errorCode ? `/${face.errorCode}` : ""}${face.errorMessage ? ` — ${face.errorMessage}` : ""}]`;
+            if (!canDifferOnRetry(res.terminal))
+                break;
         }
         return { text: last || "[unavailable]", ok: false };
     };

package/dist/brain/degrading.js

@@ -59,9 +59,12 @@ function errorMessageOf(model, e, aborted) {
         timestamp: Date.now(),
     };
 }
+function errorFrameOf(message) {
+    return { type: "error", reason: message.stopReason === "aborted" ? "aborted" : "error", error: message };
+}
 function terminalOf(message) {
-    return message.stopReason === "error"
-        ? { type: "error", reason: "error", error: message }
+    return message.stopReason === "error" || message.stopReason === "aborted"
+        ? errorFrameOf(message)
         : { type: "done", reason: message.stopReason, message };
 }
 async function forward(stream, sink) {
@@ -100,16 +103,12 @@ export function passthroughStream(brain, model, context, options) {
             }
             if (!sawTerminal) {
                 await inner.result();
-                out.push({
-                    type: "error",
-                    reason: "error",
-                    error: errorMessageOf(model, new Error("brain stream ended without a terminal event"), false),
-                });
+                out.push(errorFrameOf(errorMessageOf(model, new Error("brain stream ended without a terminal event"), false)));
             }
         }
         catch (e) {
             const aborted = options?.signal?.aborted === true || abortLikeName(e) !== undefined;
-            out.push({ type: "error", reason: "error", error: errorMessageOf(model, e, aborted) });
+            out.push(errorFrameOf(errorMessageOf(model, e, aborted)));
         }
     })();
     return out;
@@ -178,7 +177,7 @@ export function createDegradingBrain(opts) {
                 const errMsg = errorMessageOf(lastAttempted, e, aborted);
                 if (degradeInfo)
                     tagDegraded(errMsg, degradeInfo);
-                out.push({ type: "error", reason: aborted ? "aborted" : "error", error: errMsg });
+                out.push(errorFrameOf(errMsg));
             }
         })();
         return out;

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

@@ -40,16 +40,29 @@
 import type { Model } from "../internal/llm.js";
 import type { RouteAdjudication, RouteCredential, RoutePairingConfig, RoutePairingPosture } from "../internal/llm.js";
 import type { Brain, EngineNotice } from "../core/types.js";
-/** Normalize a base URL for pairing comparison, to WIRE equivalence: trim + strip trailing
- *  slashes, then — for a string that parses as a URL — fold the halves the wire itself treats as
- *  case-insensitive (scheme and host, RFC 9110) and elide the scheme's default port, while keeping
- *  the PATH byte-preserved (paths are case-sensitive; folding them would compare two genuinely
- *  different endpoints equal — a widening of exactly the leak this module exists to stop). Two
- *  spellings that resolve to the same origin+path on the wire therefore compare equal, and a
- *  refusal can never be minted over a spelling difference the wire cannot see. A value that does
- *  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;
+/** A base URL's ROUTE KEY — the value the pairing law COMPARES, folded to WIRE equivalence: the
+ *  halves the wire itself treats as case-insensitive (scheme and host, RFC 9110) fold, the scheme's
+ *  default port elides, and PATH and QUERY ride byte-preserved (a query selects the endpoint as
+ *  surely as a path does; folding either would compare two different endpoints equal — the widening
+ *  this module exists to stop). An unparseable value keeps its raw trimmed spelling: fail-closed raw
+ *  comparison. Non-string input throws — see the module note on garbage.
+ *
+ *  **Never render this.** Byte-preserving on the query means `?api_key=<secret>` rides it verbatim;
+ *  {@link displayUrlOf} is the one spelling allowed into text. */
+export declare function routeKeyOf(url: string | undefined): string;
+/** A base URL's DISPLAY spelling — the only rendering of a request root allowed into text a human,
+ *  a log or a consumer sees. Composed from the PARSE (never edited out of raw bytes): userinfo
+ *  drops, EVERY query value becomes {@link REDACTED_VALUE}, and a query NAME rides only where it
+ *  really is a name.
+ *   - no secret-name list: a list has a blind spot at the name nobody listed.
+ *   - names ride because dropping the query WHOLE renders two roots differing only in query as one
+ *     string — exactly the pairs the law refuses, so its refusal would read "targets X … paired
+ *     with X". {@link queryDifferenceNote} closes the case where the names match too.
+ *   - a BARE token (`?<token>`) renders as one placeholder with NO name: `URLSearchParams` calls it a
+ *     name with an empty value, and that reading put the payload itself on screen. "Every value is
+ *     withheld" protects only what IS a value, so the raw segment decides what rides.
+ *  Answers `""` for an undeclared root, like its key twin. */
+export declare function displayUrlOf(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.**
@@ -60,7 +73,7 @@ export declare function normalizeBaseUrl(url: string | undefined): string;
  * 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.
+ * its tolerance for an unparseable spelling ({@link routeKeyOf}). 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
@@ -190,7 +203,7 @@ export declare function adjudicateDerivedRoute(args: {
 }): Promise<RouteAdjudication | undefined>;
 /**
  * Whether two resolved models denote the SAME route for pre-flight purposes: identical wire id AND
- * identical normalized entry URL. `Model.id` alone is NOT route identity — two catalog entries can
+ * identical entry ROUTE KEY. `Model.id` alone is NOT route identity — two catalog entries can
  * legitimately share a wire id (the same model served from two endpoints), and a same-id guard
  * would silently skip the pre-flight for exactly the split the pairing law exists to judge.
  */

package/dist/brain/route-adjudicator.js

@@ -1,6 +1,28 @@
 import { AUTH_CARRIER_NAMES } from "./request-params.js";
 import { BrainError } from "./errors.js";
-export function normalizeBaseUrl(url) {
+const REDACTED_VALUE = "«redacted»";
+const REDACTED_CREDENTIALS = "[redacted-credentials]";
+function servableParse(raw) {
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        return undefined;
+    }
+    return u.protocol === "http:" || u.protocol === "https:" ? u : undefined;
+}
+function composableParse(raw) {
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        return undefined;
+    }
+    return u.host !== "" || u.pathname.startsWith("/") ? u : undefined;
+}
+export function routeKeyOf(url) {
     if (url === undefined)
         return "";
     if (typeof url !== "string") {
@@ -9,13 +31,53 @@ export function normalizeBaseUrl(url) {
     const raw = url.trim().replace(/\/+$/, "");
     if (raw === "")
         return "";
-    try {
-        const u = new URL(raw);
-        return `${u.protocol}//${u.host}${u.pathname}${u.search}`.replace(/\/+$/, "");
-    }
-    catch {
+    const u = servableParse(raw);
+    if (u === undefined)
         return raw;
+    return `${u.protocol}//${u.host}${u.pathname}${u.search}`.replace(/\/+$/, "");
+}
+function querySegments(search) {
+    if (search === "" || search === "?")
+        return [];
+    return search.replace(/^\?/, "").split("&").map((raw) => {
+        const eq = raw.indexOf("=");
+        return eq === -1 ? { raw } : { raw, name: raw.slice(0, eq), value: raw.slice(eq + 1) };
+    });
+}
+export function displayUrlOf(url) {
+    const key = routeKeyOf(url);
+    if (key === "")
+        return "";
+    const u = composableParse(key);
+    if (u === undefined) {
+        const cut = key.search(/[?#]/);
+        const head = cut === -1 ? key : key.slice(0, cut);
+        const at = head.lastIndexOf("@");
+        const shown = at === -1 ? head : `${REDACTED_VALUE}@${head.slice(at + 1)}`;
+        return cut === -1 ? shown : `${shown}${key[cut]}${REDACTED_VALUE}`;
+    }
+    const segs = querySegments(u.search);
+    const query = segs.length === 0 ? "" : `?${segs.map((sg) => (sg.raw === "" ? "" : sg.name === undefined ? REDACTED_VALUE : `${sg.name}=${REDACTED_VALUE}`)).join("&")}`;
+    return `${u.protocol}//${u.host}${u.pathname}${query}`.replace(/\/+$/, "");
+}
+function queryDifferenceNote(requestKey, declaredKey) {
+    if (displayUrlOf(requestKey) !== displayUrlOf(declaredKey))
+        return "";
+    const names = new Set();
+    const ua = composableParse(requestKey);
+    const ub = composableParse(declaredKey);
+    if (ua !== undefined && ub !== undefined) {
+        const a = querySegments(ua.search);
+        const b = querySegments(ub.search);
+        const valuesOf = (segs, n) => segs.filter((sg) => sg.name === n).map((sg) => sg.value).join("\u0000");
+        for (const n of new Set([...a, ...b].flatMap((sg) => (sg.name === undefined ? [] : [sg.name])))) {
+            if (valuesOf(a, n) !== valuesOf(b, n))
+                names.add(n);
+        }
     }
+    return names.size > 0
+        ? ` (same rendering — the query values differ under: ${[...names].sort().join(", ")})`
+        : ` (same rendering — the difference is in a part this line withholds or folds)`;
 }
 export function assertServableRequestRoot(url, seat) {
     if (typeof url !== "string" || url.trim() === "")
@@ -23,19 +85,19 @@ export function assertServableRequestRoot(url, seat) {
     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}`;
+        const named = parsed === undefined ? "it did not parse as a URL" : displayUrlOf(trimmed);
         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}) — ` +
+    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]@");
+    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");
@@ -76,9 +138,12 @@ export function resolveRouteCredential(input) {
     return { source: "absent" };
 }
 export function adjudicateModelRoute(model, credential, config) {
-    const entry = normalizeBaseUrl(model.baseUrl);
-    const declared = normalizeBaseUrl(config.baseUrl);
+    const entry = routeKeyOf(model.baseUrl);
+    const declared = routeKeyOf(config.baseUrl);
     const request = entry || declared;
+    const entryShown = displayUrlOf(entry);
+    const declaredShown = displayUrlOf(declared);
+    const requestShown = displayUrlOf(request);
     if (credential.source === "per-model")
         return { ok: true, posture: "per-model" };
     if (credential.source === "deployment-config") {
@@ -91,12 +156,13 @@ export function adjudicateModelRoute(model, credential, config) {
             code: "route.credential_mismatch",
             detail: {
                 modelId: model.id,
-                entryBaseUrl: entry,
-                requestBaseUrl: request,
-                configBaseUrl: declared,
-                fixHint: `model "${model.id}" targets ${request} but the deployment credential is paired with ${declared}: ` +
+                entryBaseUrl: entryShown,
+                requestBaseUrl: requestShown,
+                configBaseUrl: declaredShown,
+                fixHint: `model "${model.id}" targets ${requestShown} but the deployment credential is paired with ${declaredShown}` +
+                    `${queryDifferenceNote(request, declared)}: ` +
                     `give the model its own credential (a per-model key via getApiKeyAndHeaders, or an auth header on Model.headers), ` +
-                    `or serve it through a brain whose config.baseUrl is ${request}`,
+                    `or serve it through a brain whose config.baseUrl is the model's own root`,
             },
         };
     }
@@ -107,12 +173,12 @@ export function adjudicateModelRoute(model, credential, config) {
         code: "route.credential_missing",
         detail: {
             modelId: model.id,
-            entryBaseUrl: entry,
-            requestBaseUrl: request,
-            configBaseUrl: declared,
-            fixHint: `model "${model.id}" targets ${request} but no credential is configured for that endpoint ` +
-                `(the deployment credential root is ${declared}): supply a per-model credential ` +
-                `(getApiKeyAndHeaders, or an auth header on Model.headers), or serve it through a brain constructed for ${request}`,
+            entryBaseUrl: entryShown,
+            requestBaseUrl: requestShown,
+            configBaseUrl: declaredShown,
+            fixHint: `model "${model.id}" targets ${requestShown} but no credential is configured for that endpoint ` +
+                `(the deployment credential root is ${declaredShown})${queryDifferenceNote(request, declared)}: supply a per-model credential ` +
+                `(getApiKeyAndHeaders, or an auth header on Model.headers), or serve it through a brain constructed for that root`,
         },
     };
 }
@@ -192,7 +258,7 @@ export async function adjudicateDerivedRoute(args) {
     }
 }
 export function sameRouteIdentity(a, b) {
-    return a.id === b.id && normalizeBaseUrl(a.baseUrl) === normalizeBaseUrl(b.baseUrl);
+    return a.id === b.id && routeKeyOf(a.baseUrl) === routeKeyOf(b.baseUrl);
 }
 export function fallbackToPrimaryNotice(args) {
     return {

package/dist/brain/route-conformance.js

@@ -73,6 +73,15 @@ export const ROUTE_ADJUDICATION_CONFORMANCE_CORPUS = [
         expect: { ok: false, code: "route.credential_mismatch" },
         leg: "named",
     },
+    {
+        name: "deployment-mismatch-query-differs",
+        intent: "two roots differing only in a QUERY parameter are two routes — the deployment credential is not paired with the second",
+        model: { id: "m-tenant", baseUrl: "https://gw.example.com/v1?tenant=b-corp" },
+        credential: { source: "deployment-config", apiKey: "k-boot" },
+        config: { baseUrl: "https://gw.example.com/v1?tenant=a-corp" },
+        expect: { ok: false, code: "route.credential_mismatch" },
+        leg: "named",
+    },
     {
         name: "deployment-mismatch-derived-leg",
         intent: "the same torn pair on a DERIVED model: same verdict; the engine disposes of it as fallback-to-primary + notice",