@genesislcap/ai-assistant 15.14.0 → 15.14.2

package/docs/migration-GENC-1506.md

@@ -0,0 +1,209 @@
+# Migration Guide — GENC-1506 (the provider refused: a named, non-retried failure)
+
+> **Additive — no migration required.** Nothing was removed, renamed, or given a new meaning. Every
+> existing event name, public member, template `part` and failure reason behaves exactly as before.
+> Upgrade, and the visible change is that a provider refusing your account produces one clear
+> sentence instead of a generic apology — and stops costing doomed requests to discover.
+>
+> **There is deliberately no new UI.** Unlike GENC-1464 this adds no banner, no blocked state and no
+> latch. See [Why no banner](#why-no-banner).
+>
+> All surfaces below are `@beta`.
+
+---
+
+## Why
+
+When Anthropic refuses a request because the **account** cannot be served — its credit is gone, a
+usage cap is reached, or the key is dead — nothing in the stack knew what that meant. The refusal fell
+out of the transport as an untyped `Error`, landed in the chat driver's transient-retry catch, was
+re-issued up to `MAX_SETUP_TRANSPORT_RETRIES` times against a wall no retry can clear, and the user
+finally got:
+
+> Sorry, something went wrong on my end. Please try again in a moment.
+
+Wrong twice over: nothing went wrong on our end, and trying again will not help.
+
+This is **not** the AI-spend budget wall (GENC-1464). That one is *us* declining to spend more on a
+caller's behalf, and an administrator can raise the cap. This one is the *vendor* declining to serve
+us at all, and nothing in our own system can clear it. The two were being conflated in code — see
+[The 402 collision](#the-402-collision).
+
+---
+
+## What was added
+
+### `@genesislcap/foundation-ai`
+
+| Addition | Kind | Notes |
+| --- | --- | --- |
+| `ProviderRefusedError` | exported class | Fields: `vendorLabel`, `kind`, `upstreamStatus?`, `upstreamType?`, `detail?` |
+| `ProviderRefusalKind` | exported type | `'spend' \| 'auth'` |
+| `DEFAULT_PROVIDER_REFUSED_MESSAGE` | exported const | The one sentence shown to the user |
+| `PROVIDER_REFUSED_CODE` | exported const | `'PROVIDER_REFUSED'` — the proxy's wire code |
+| `'provider-refused'` | new `TurnFailureReason` member | Rides `ChatDriverResult.failureReason` and the `tool-loop-end` detail |
+| `'provider_refused'` | new `SubAgentFailureReason` member | Terminal for the parent turn too |
+| `ChatDriverResult.providerRefused` | new optional field on the `done` arm | `{ vendorLabel, kind, upstreamStatus?, upstreamType? }` |
+
+### `@genesislcap/ai-assistant`
+
+| Addition | Kind |
+| --- | --- |
+| `ChatDriverConfig.providerRefusedMessage` | new optional field — overrides the sentence |
+| `DEFAULT_PROVIDER_REFUSED_MESSAGE`, `PROVIDER_REFUSED_CODE`, `ProviderRefusedError` | re-exported from the `./chat-driver` (Node) entry |
+
+The chat driver gained a typed branch that sits **before** the transient-retry catch. It does not
+retry; it appends the sentence to the transcript (or calls `failSubAgent('provider_refused')` when
+running as a sub-agent) and ends the turn with `failureReason: 'provider-refused'`.
+
+### Across the sub-agent boundary
+
+`getSubAgentFailure()` now carries a `providerRefused` payload alongside the existing `budget` one, and
+`invokeSubAgent()` latches the parent's terminal state from it.
+
+Both halves are needed for a reason that is easy to miss: **a sub-agent is a separate driver instance**,
+so anything the child sets on itself is invisible to the parent. The refusal reaches the parent only as a
+tool result. Without the latch that result is ordinary, the parent issues another model call straight into
+the same wall, and — if that call happens to succeed — the turn can finish with no `failureReason` at all,
+reporting a clean turn over a dead account. Without the payload the parent can report `provider-refused`
+but not which vendor or which kind, which is the only signal distinguishing "top up" from "rotate the
+key".
+
+First attribution wins (`??=`), matching `budgetWallDetail`: batched delegations can pair an attributable
+child refusal with an unattributable one, and a plain assignment would let the later `undefined` erase
+what the earlier child knew.
+
+---
+
+## One error, two kinds
+
+`kind` distinguishes the operator's fix while the user's experience stays identical:
+
+- **`spend`** — the account cannot pay: credit balance at zero, a workspace/organisation usage cap, or
+  a billing/payment-information problem. Someone must top up or raise a cap.
+- **`auth`** — the credential cannot be used: revoked, expired or malformed key (`401`), or a key
+  without access to the requested model (`403`). Someone must rotate a key or grant access.
+
+Both produce the **same sentence**. The kind reaches `ChatDriverResult.providerRefused.kind`, the
+`turn.error` debug entry, and the transport error — never the transcript. That is deliberate: the copy
+is cause-free (see below), so `kind` is the only place the distinction survives, and a host's own
+alerting is what it exists for.
+
+Two designs were rejected. A type named for spend would *lie* about an expired key, and a debug
+timeline reading `provider-spend-refused` for an auth fault misleads the next engineer. Two separate
+error types would duplicate a branch, a message and a wire code to express one outcome.
+
+---
+
+## The copy, and the constraints on it
+
+> AI requests are currently being refused by the provider. This isn't related to your account or your
+> usage and needs no action from you — please contact your support team so it can be restored.
+
+It names **no cause**, and a rewrite has to keep it that way. Three constraints:
+
+1. **It must not sound like a cap.** Users can often see their remaining AI spend in the same UI, so
+   *allowance / limit / quota / budget / usage / credit / balance* risk a visible self-contradiction —
+   a message saying there is nothing left, beside a figure showing there is. "or your usage" goes
+   further than avoiding the words: it pre-empts the user checking that figure and concluding the
+   message is wrong.
+2. **It must not imply the bill went unpaid.** *Billing / payment / funds / top up* all read that way.
+3. **It must not promise self-healing.** Clearing this needs a human, so "currently" not
+   "temporarily", and "so it can be restored" signals that someone must act.
+
+Vendor-neutral and deployment-neutral, so it is already safe for a white-labelled host. Override with
+`ChatDriverConfig.providerRefusedMessage` if you want your own wording.
+
+---
+
+## Why no banner
+
+GENC-1464 gave the budget wall a latched banner, a locked composer and per-vendor blocking state. This
+deliberately reuses **none** of it (Matt, 2026-08-18): a provider refusal is a distinctly separate
+condition from a user's own spend allowance and must not borrow its UI.
+
+Consequences, both accepted:
+
+- **The composer stays live.** A user can send again straight into the same wall. With the
+  classification in place that costs exactly **one** refused request per send rather than the 3–18 it
+  cost before, and the sentence is self-explanatory.
+- **Nothing survives a reload**, because there is no latched state — and nothing needs to. There is
+  also no pre-flight available even in principle: a refused account rejects `count_tokens` with the
+  same error, so there is no free way to ask "can this account spend?".
+
+---
+
+## The 402 collision
+
+`isBudgetRejection` treats **any** `402` as our own budget verdict, and `402` is also Anthropic's
+documented `billing_error` status. A relayed upstream billing failure was therefore reported as the
+*user's* spend cap — locking their composer and sending them to an administrator to raise a limit that
+had headroom.
+
+Closed by **ordering plus positive detection**, not by loosening the budget predicate:
+`providerRefusalOf` runs first in `postWithRetry`, and every trigger in it is a positive signal, so a
+bare `402` with no provider envelope still falls through to the budget branch exactly as before. Both
+directions are pinned by tests in `post-with-retry.test.ts`.
+
+---
+
+## Detection: measured, not assumed
+
+The classifier is built from **verbatim captures** of the real Anthropic API (2026-08-18), and the
+fixtures in `provider-refused.test.ts` are those responses. This matters because the obvious design —
+classify on the documented `402 billing_error` — would have fixed **nothing**:
+
+| Condition | Actual response |
+| --- | --- |
+| Credit balance at zero | `400` + `invalid_request_error` + "Your credit balance is too low to access the Anthropic API…" |
+| Workspace usage cap | `400` + `invalid_request_error` + "You have reached your specified workspace API usage limits…" |
+| Invalid key | `401` + `authentication_error` + "API key is invalid." (`request_id` is **null**) |
+
+**Reading the `kind` off an explicit-code response.** When the proxy stamps `PROVIDER_REFUSED`, the kind
+is resolved from a stated `kind` in **either** wire position (top level on a JSON body, under `details` on
+an err frame), then from the relayed provider envelope's own type, and only then defaults to `spend`.
+Reading the top level alone reported every auth refusal through our own proxy as `spend` — it stamps the
+code with the envelope in `details` and no top-level `kind` — which sends an operator to top up an account
+when the fix is a credential rotation. Invisible on screen, since the copy is identical either way.
+
+Both spend refusals arrive in the **generic** bucket with no distinct type, no dedicated header and
+nothing structural — so a small list of independent phrase signals (`credit balance`, `usage limit`, …)
+is the only handle available. `auth` needs no prose: status plus `error.type` is enough.
+
+False positives are near-impossible for a non-obvious reason: on a refused account the spend check runs
+*before* request validation, so a genuine schema `400` is only observable on a healthy account, where
+its message quotes field paths and matches nothing in the list.
+
+**Gemini is deliberately not classified.** Google surfaces a spend cap as `429 RESOURCE_EXHAUSTED` —
+the same status *and message* as an ordinary rate limit, and `429` is retryable — so a prose probe
+there would break the ladder. The structural discriminator that would work
+(`details[].QuotaFailure.violations[].quotaId`) is only partly observed. `providerRefusalOf` dispatches
+on vendor, so adding Gemini later is a branch, not a rewrite.
+
+---
+
+## Also in this change: the retry ladder honours the server
+
+Found while measuring the Gemini rate limit, and folded in because it lives in the same function.
+
+`postWithRetry`'s ladder was `base * 2^attempt` — 31s across five retries — and read neither
+`Retry-After` nor Google's in-body `RetryInfo`. A real rate-limited key asked for **53s**, so a
+*legitimate* rate limit burned every retry inside the window we had been told to wait, then failed
+opaquely.
+
+Now: the wait is `max(our ladder, what the server asked)`, bounded twice — `MAX_SERVER_REQUESTED_BACKOFF_MS`
+(60s) per attempt, and `MAX_TOTAL_SERVER_REQUESTED_BACKOFF_MS` (120s) across the whole sequence. An
+explicit `x-should-retry: false` stops the ladder even on a retryable status. An **absent**
+`x-should-retry` means "no opinion" and changes nothing — never read as `false`.
+
+The sequence bound is not belt-and-braces. The per-attempt cap alone is no bound at all: the ladder
+tops out at 16s, so a 60s hint wins on *every* attempt, and five of them park a turn for five minutes
+with no timer running through any of them (the attempt's own timeout is cleared before each backoff, so
+a caller abort is the only way out). Past the budget we stop honouring hints and fall back to the
+ladder — declining a hint never stops the retrying. Only the *excess over the ladder* is charged, so
+the ladder's own growth cannot exhaust the allowance on time we were always going to spend. Worst case
+is now ~151s rather than 300s, and the 53s case the module was written for still fits twice over.
+
+> **This is the one part of the change that affects healthy traffic.** Some failures that used to give
+> up after 31s will now wait longer before succeeding or failing. That is correct and it is what the
+> server asked for, but it is a timing change on a shared path, so review it on its own terms.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/ai-assistant",
   "description": "Genesis AI Assistant micro-frontend",
-  "version": "15.14.0",
+  "version": "15.14.2",
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
   "types": "dist/ai-assistant.d.ts",
@@ -73,26 +73,26 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "15.14.0",
-    "@genesislcap/genx": "15.14.0",
-    "@genesislcap/rollup-builder": "15.14.0",
-    "@genesislcap/ts-builder": "15.14.0",
-    "@genesislcap/uvu-playwright-builder": "15.14.0",
-    "@genesislcap/vite-builder": "15.14.0",
-    "@genesislcap/webpack-builder": "15.14.0",
+    "@genesislcap/foundation-testing": "15.14.2",
+    "@genesislcap/genx": "15.14.2",
+    "@genesislcap/rollup-builder": "15.14.2",
+    "@genesislcap/ts-builder": "15.14.2",
+    "@genesislcap/uvu-playwright-builder": "15.14.2",
+    "@genesislcap/vite-builder": "15.14.2",
+    "@genesislcap/webpack-builder": "15.14.2",
     "@types/dompurify": "^3.0.5",
     "@types/marked": "^5.0.2",
     "esbuild": "0.25.12"
   },
   "dependencies": {
-    "@genesislcap/foundation-ai": "15.14.0",
-    "@genesislcap/foundation-logger": "15.14.0",
-    "@genesislcap/foundation-notifications": "15.14.0",
-    "@genesislcap/foundation-redux": "15.14.0",
-    "@genesislcap/foundation-ui": "15.14.0",
-    "@genesislcap/foundation-utils": "15.14.0",
-    "@genesislcap/rapid-design-system": "15.14.0",
-    "@genesislcap/web-core": "15.14.0",
+    "@genesislcap/foundation-ai": "15.14.2",
+    "@genesislcap/foundation-logger": "15.14.2",
+    "@genesislcap/foundation-notifications": "15.14.2",
+    "@genesislcap/foundation-redux": "15.14.2",
+    "@genesislcap/foundation-ui": "15.14.2",
+    "@genesislcap/foundation-utils": "15.14.2",
+    "@genesislcap/rapid-design-system": "15.14.2",
+    "@genesislcap/web-core": "15.14.2",
     "dompurify": "^3.3.1",
     "marked": "^17.0.3"
   },
@@ -105,5 +105,5 @@
     "access": "public"
   },
   "customElements": "dist/custom-elements.json",
-  "gitHead": "d84656a0872b2274be6f6b20a87a28504b48ed2a"
+  "gitHead": "bd1cb4a789548d9c7c6777f8adb7bce3f43c3317"
 }

package/src/chat-driver-node.ts

@@ -43,6 +43,16 @@ export {
   // GENC-1461, create PR #1644 review.
   SUPPORTED_ANTHROPIC_MODEL_IDS,
   SUPPORTED_GEMINI_MODEL_IDS,
+  // The provider wall (GENC-1506). Re-exported for the same anti-drift reason as the model lists
+  // above, and it matters more here because the other end of this contract is in ANOTHER REPO:
+  // genesis-create's ai-service stamps `PROVIDER_REFUSED_CODE` onto its proxy responses and shows
+  // `DEFAULT_PROVIDER_REFUSED_MESSAGE` on its own generation surfaces. Hand-copying either would
+  // drift silently — a renamed code stops classifying, and a second copy of the sentence survives
+  // the first reword. `ProviderRefusedError` is here so a headless caller can `instanceof` it
+  // against the same bundled instance the driver throws from.
+  DEFAULT_PROVIDER_REFUSED_MESSAGE,
+  PROVIDER_REFUSED_CODE,
+  ProviderRefusedError,
   isObservableAIProviderRegistry,
   // Request pricing. Re-exported HERE, not left to a direct `@genesislcap/foundation-ai`
   // import, for the same reason as everything above it: a headless host that adds its own

package/src/components/chat-driver/chat-driver.test.ts

@@ -13,6 +13,8 @@ import type {
 } from '@genesislcap/foundation-ai';
 import {
   BudgetExhaustedError,
+  DEFAULT_PROVIDER_REFUSED_MESSAGE,
+  ProviderRefusedError,
   DEFAULT_BUDGET_EXHAUSTED_MESSAGE,
   isChatToolCallUnknown,
   MalformedFunctionCallError,
@@ -2504,6 +2506,29 @@ const budgetExhaustedProvider = (): AIProvider => ({
   },
 });
 
+/** A provider the vendor refused outright (GENC-1506 — terminal, must not retry). */
+const providerRefusedProvider = (kind: 'spend' | 'auth' = 'spend'): AIProvider => ({
+  chat: async (): Promise<ChatMessage> => {
+    // Both fixtures are the real captured shapes (2026-08-18), matched to their kind — an `auth`
+    // fixture carrying a credit-balance message would read as a classification bug to the next person.
+    throw kind === 'auth'
+      ? new ProviderRefusedError(
+          'Anthropic',
+          'auth',
+          401,
+          'authentication_error',
+          'API key is invalid.',
+        )
+      : new ProviderRefusedError(
+          'Anthropic',
+          'spend',
+          400,
+          'invalid_request_error',
+          'Your credit balance is too low to access the Anthropic API.',
+        );
+  },
+});
+
 /** A provider that throws a generic error (the sendMessage catch-all → 'exception'). */
 const throwingProvider = (): AIProvider => ({
   chat: async (): Promise<ChatMessage> => {
@@ -2628,6 +2653,121 @@ outcome('a clean turn leaves the legacy shape byte-unchanged (no failureReason)'
 
 // ── Budget exhaustion (GENC-1464) ──────────────────────────────────────────────
 
+outcome('provider-refused surfaces at both seams', async () => {
+  await assertSurfacesReason('provider-refused', providerRefusedProvider(), 'provider-refused');
+});
+
+outcome('a provider refusal is terminal — no retry, cause-free copy, kind in the log', async () => {
+  // GENC-1506. The measured bug this pins: the refusal used to arrive as an untyped transport error,
+  // get re-issued MAX_SETUP_TRANSPORT_RETRIES times against a wall that cannot move, and then surface
+  // as "something went wrong on my end" — wrong twice over, since nothing went wrong on our end and
+  // trying again cannot help.
+  clearMetaEventRegistry();
+  let calls = 0;
+  const provider: AIProvider = {
+    chat: async (): Promise<ChatMessage> => {
+      calls += 1;
+      throw new ProviderRefusedError(
+        'Anthropic',
+        'spend',
+        400,
+        'invalid_request_error',
+        'credit too low',
+      );
+    },
+    getStatus: async () => ({ provider: 'anthropic', model: 'test-model' }),
+  };
+  const config = agent({
+    name: 'Static',
+    toolDefinitions: [def('noop')],
+    toolHandlers: { noop: async () => 'ok' },
+  });
+  const driver = makeDriver(config, provider, 'outcome-provider-refused', outcomeBus);
+
+  const result: ChatDriverResult = await driver.sendMessage('go');
+
+  assert.is(calls, 1, 'a provider refusal is not retried — exactly one model call');
+  assert.is(
+    result.reason === 'done' ? result.failureReason : undefined,
+    'provider-refused',
+    'the turn ends with the provider-refused failure reason',
+  );
+
+  // The kind reaches the CALLER, which is what lets ai-service's Sentry alert say whether an operator
+  // must top up an account or rotate a key. It is the only place that distinction survives, because
+  // the user-facing sentence is deliberately cause-free.
+  const refused = result.reason === 'done' ? result.providerRefused : undefined;
+  assert.is(refused?.kind, 'spend');
+  assert.is(refused?.vendorLabel, 'Anthropic');
+  assert.is(refused?.upstreamStatus, 400);
+  assert.is(refused?.upstreamType, 'invalid_request_error');
+
+  const last = driver.getHistory().at(-1);
+  assert.ok(last?.role === 'assistant', 'turn ends with an assistant message');
+  // Identity, not a substring: the sentence is provisional copy shared with ai-service via one
+  // exported const, and this is what stops a second copy drifting in.
+  assert.is(last!.content, DEFAULT_PROVIDER_REFUSED_MESSAGE);
+  assert.not.ok(
+    last!.content.includes('something went wrong'),
+    'must not fall through to the generic apology',
+  );
+  // The copy must not leak the cause, whatever the kind — a user who can see remaining spend must not
+  // be told about a limit, and we must not imply the bill went unpaid.
+  for (const banned of ['credit', 'billing', 'balance', 'quota', 'limit']) {
+    assert.not.ok(
+      last!.content.toLowerCase().includes(banned),
+      `copy must not mention "${banned}"`,
+    );
+  }
+
+  const err = getMetaEvents('outcome-provider-refused').find((e) => e.type === 'turn.error');
+  assert.is((err?.detail as { reason?: string })?.reason, 'provider-refused');
+  assert.is((err?.detail as { kind?: string })?.kind, 'spend');
+});
+
+outcome('an auth refusal shows the SAME sentence but logs a different kind', async () => {
+  // The whole justification for one type with two kinds: identical user experience, distinct
+  // diagnostics. If these ever diverge in the transcript, the copy decision has been undone.
+  clearMetaEventRegistry();
+  const config = agent({
+    name: 'Static',
+    toolDefinitions: [def('noop')],
+    toolHandlers: { noop: async () => 'ok' },
+  });
+  const driver = makeDriver(
+    config,
+    providerRefusedProvider('auth'),
+    'outcome-refused-auth',
+    outcomeBus,
+  );
+
+  const result: ChatDriverResult = await driver.sendMessage('go');
+
+  assert.is(result.reason === 'done' ? result.failureReason : undefined, 'provider-refused');
+  assert.is(result.reason === 'done' ? result.providerRefused?.kind : undefined, 'auth');
+  assert.is(driver.getHistory().at(-1)!.content, DEFAULT_PROVIDER_REFUSED_MESSAGE);
+});
+
+outcome('a host override replaces the provider-refusal sentence verbatim', async () => {
+  const config = agent({
+    name: 'Static',
+    toolDefinitions: [def('noop')],
+    toolHandlers: { noop: async () => 'ok' },
+  });
+  const driver = new ChatDriver(makeRegistry(providerRefusedProvider()), {
+    maxToolIterations: 50,
+    maxFoldOperations: 5,
+    sessionKey: 'outcome-refused-override',
+    providerRefusedMessage: 'Bespoke wording for a white-labelled host.',
+  });
+  driver.applyAgent(config);
+
+  await driver.sendMessage('go');
+
+  assert.is(driver.getHistory().at(-1)!.content, 'Bespoke wording for a white-labelled host.');
+  driver.dispose();
+});
+
 outcome('budget-exhausted surfaces at both seams', async () => {
   await assertSurfacesReason('budget', budgetExhaustedProvider(), 'budget-exhausted');
 });
@@ -3005,6 +3145,160 @@ const walledWorker = (): AgentConfig =>
     toolHandlers: { finish: async () => 'x' },
   });
 
+/**
+ * The child-refused / parent-fine provider, mirroring `parentOkChildWalled` — the parent's turn call
+ * succeeds and delegates, and only the child's provider refuses.
+ */
+const parentOkChildRefused = (
+  kind: 'spend' | 'auth' = 'spend',
+): { parentCalls: () => number; provider: AIProvider } => {
+  let parentCalls = 0;
+  return {
+    parentCalls: () => parentCalls,
+    provider: {
+      chat: async (
+        _h: ChatMessage[],
+        _u: string,
+        options?: ChatRequestOptions,
+      ): Promise<ChatMessage> => {
+        const names = (options?.tools ?? []).map((t) => t.name);
+        if (names.includes('delegate')) {
+          parentCalls += 1;
+          return callsTool('delegate', `d${parentCalls}`);
+        }
+        throw kind === 'auth'
+          ? new ProviderRefusedError(
+              'Anthropic',
+              'auth',
+              401,
+              'authentication_error',
+              'API key is invalid.',
+            )
+          : new ProviderRefusedError(
+              'Anthropic',
+              'spend',
+              400,
+              'invalid_request_error',
+              'credit too low',
+            );
+      },
+    },
+  };
+};
+
+outcome(
+  'a sub-agent provider refusal ends the parent turn without another model call',
+  async () => {
+    /*
+     * The seam a review caught, and it is genuinely counter-intuitive: the child is a SEPARATE driver
+     * instance, so the flag it sets on itself is invisible to the parent. The refusal reaches the parent
+     * only as a tool result, and without an `invokeSubAgent` branch that result was ordinary — so the
+     * parent issued another model call straight into the same wall, and if that call had happened to
+     * succeed the turn could have finished with no `failureReason` at all, reporting a clean turn over a
+     * dead account. `parentCalls() === 1` is the assertion that pins it.
+     */
+    clearMetaEventRegistry();
+    const { parentCalls, provider } = parentOkChildRefused();
+    const parent = delegatingParent(walledWorker(), () => undefined);
+    const driver = makeDriver(parent, provider, 'outcome-subagent-refused', outcomeBus);
+
+    const result: ChatDriverResult = await driver.sendMessage('go');
+
+    assert.is(parentCalls(), 1, 'the parent never calls the model again after the refusal');
+    assert.is(result.reason === 'done' ? result.failureReason : undefined, 'provider-refused');
+    assert.is(driver.getHistory().at(-1)!.content, DEFAULT_PROVIDER_REFUSED_MESSAGE);
+  },
+);
+
+outcome("a sub-agent refusal carries the CHILD's kind and vendor to the parent", async () => {
+  // The other half of the same finding. The parent can only report what the child bubbled, so without a
+  // payload on the failure the `providerRefused` diagnostic promised on `ChatDriverResult` would be
+  // absent — and with cause-free user copy that payload is the ONLY place an operator learns whether to
+  // top up an account or rotate a credential.
+  clearMetaEventRegistry();
+  const { provider } = parentOkChildRefused('auth');
+  const parent = delegatingParent(walledWorker(), () => undefined);
+  const driver = makeDriver(parent, provider, 'outcome-subagent-refused-kind', outcomeBus);
+
+  const result: ChatDriverResult = await driver.sendMessage('go');
+
+  const refused = result.reason === 'done' ? result.providerRefused : undefined;
+  assert.is(refused?.kind, 'auth', "the child's kind survives the hop");
+  assert.is(refused?.vendorLabel, 'Anthropic');
+  assert.is(refused?.upstreamStatus, 401);
+});
+
+outcome("a GRANDCHILD's refusal keeps its kind and vendor across two hops", async () => {
+  /*
+   * The third finding, and the one a single-hop test cannot reach. An INTERMEDIATE sub-agent latches its
+   * grandchild's payload correctly via `invokeSubAgent`, but then has to hand it on through
+   * `failSubAgent` — and passing only the reason there still stopped the top-level turn (the reason
+   * travels) while arriving with no vendor and no kind. The turn looked handled and the diagnostics were
+   * gone, which is the failure mode this payload exists to prevent.
+   *
+   * Three tiers: boss -> middle -> worker. Only the worker's turn is refused; every other model call
+   * succeeds, so nothing but the forwarding can carry the detail to the top.
+   */
+  clearMetaEventRegistry();
+  const worker = agent({
+    name: 'worker',
+    toolDefinitions: [def('finish')],
+    toolHandlers: { finish: async () => 'x' },
+  });
+  const middle = agent({
+    name: 'middle',
+    subAgents: [worker],
+    toolDefinitions: [def('sub_delegate')],
+    toolHandlers: {
+      sub_delegate: async (_args, ctx) => {
+        const o = await ctx.requestSubAgent!('worker', { task: 'deeper' });
+        return o.ok ? 'ok' : `failed: ${o.reason}`;
+      },
+    },
+  });
+  const boss = agent({
+    name: 'boss',
+    subAgents: [middle],
+    toolDefinitions: [def('delegate')],
+    toolHandlers: {
+      delegate: async (_args, ctx) => {
+        const o = await ctx.requestSubAgent!('middle', { task: 'do it' });
+        return o.ok ? 'ok' : `failed: ${o.reason}`;
+      },
+    },
+  });
+
+  // Routed by the tool surface each tier is given, so only the deepest turn throws.
+  const provider: AIProvider = {
+    chat: async (
+      _h: ChatMessage[],
+      _u: string,
+      options?: ChatRequestOptions,
+    ): Promise<ChatMessage> => {
+      const names = (options?.tools ?? []).map((t) => t.name);
+      if (names.includes('delegate')) return callsTool('delegate', 'd1');
+      if (names.includes('sub_delegate')) return callsTool('sub_delegate', 's1');
+      throw new ProviderRefusedError(
+        'Anthropic',
+        'auth',
+        401,
+        'authentication_error',
+        'API key is invalid.',
+      );
+    },
+  };
+  const driver = makeDriver(boss, provider, 'outcome-refused-grandchild', outcomeBus);
+
+  const result: ChatDriverResult = await driver.sendMessage('go');
+
+  assert.is(result.reason === 'done' ? result.failureReason : undefined, 'provider-refused');
+  const refused = result.reason === 'done' ? result.providerRefused : undefined;
+  assert.is(refused?.kind, 'auth', "the grandchild's kind survives BOTH hops");
+  assert.is(refused?.vendorLabel, 'Anthropic');
+  assert.is(refused?.upstreamStatus, 401);
+  assert.is(driver.getHistory().at(-1)!.content, DEFAULT_PROVIDER_REFUSED_MESSAGE);
+});
+
 outcome('a sub-agent budget wall ends the parent turn without another model call', async () => {
   clearMetaEventRegistry();
   const { parentCalls, provider } = parentOkChildWalled();