@genesislcap/ai-assistant 15.6.2 → 15.7.0

package/src/state/ai-assistant-slice.test.ts

@@ -2,6 +2,7 @@ import type { ChatMessage } from '@genesislcap/foundation-ai';
 import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
 import {
   aiAssistantSlice,
+  type AiAssistantSessionState,
   createDefaultSessionState,
   type LoadSessionPayload,
 } from './ai-assistant-slice';
@@ -11,6 +12,10 @@ import {
 const {
   loadSession,
   resetSession,
+  setBlocked,
+  setBlockedReason,
+  setVendorBlocked,
+  setInputValue,
   setMessages,
   setState,
   setSessionMenuOpen,
@@ -118,4 +123,214 @@ Suite('setSessionMenuOpen toggles the lifecycle-menu flag; resetSession clears i
   assert.is(cleared.sessionMenuOpen, false);
 });
 
+// GENC-1464: the backend-blocked latch (exhausted AI budget).
+Suite('setBlocked latches the flag and its reason', () => {
+  let state = createDefaultSessionState();
+  assert.is(state.blocked, false);
+  assert.is(state.blockedReason, null);
+
+  state = reduce(state, setBlocked({ blocked: true }));
+  assert.is(state.blocked, true);
+  assert.is(state.blockedReason, null, 'no reason given → null, so the element uses its default');
+
+  state = reduce(
+    state,
+    setBlocked({ blocked: true, reason: 'Budget exhausted — contact billing' }),
+  );
+  assert.is(state.blockedReason, 'Budget exhausted — contact billing');
+});
+
+Suite('unblocking always clears the reason', () => {
+  // A stale explanation must never outlive the condition it described.
+  let state = reduce(createDefaultSessionState(), setBlocked({ blocked: true, reason: 'gone' }));
+  state = reduce(state, setBlocked({ blocked: false }));
+  assert.is(state.blocked, false);
+  assert.is(state.blockedReason, null);
+});
+
+Suite('resetSession preserves the block — "New chat" does not refill the budget', () => {
+  // Deliberately unlike sessionMenuOpen/compacting above: this is a backend
+  // condition, not conversation state, so Clear must not hand the user a
+  // working-looking composer that fails on the next send.
+  let state = reduce(
+    createDefaultSessionState(),
+    setBlocked({ blocked: true, reason: 'no funds' }),
+  );
+  state = reduce(state, setMessages([{ role: 'user', content: 'x' }] as ChatMessage[]));
+
+  const cleared = reduce(state, resetSession());
+
+  assert.is(cleared.messages.length, 0, 'the transcript is still cleared');
+  assert.is(cleared.blocked, true, 'the block survives Clear');
+  assert.is(cleared.blockedReason, 'no funds', 'and so does its reason');
+});
+
+Suite('re-latching without a reason preserves the host explanation', () => {
+  // The race this fixes is deterministic, not theoretical: `tool-loop-end` is
+  // published from the driver's `finally`, i.e. BEFORE `sendMessage()` resolves.
+  // So a bus-subscribed host (what the migration guide's Option C recommends)
+  // writes its detailed copy first, and the element's own latch — which may have
+  // no figures to offer — lands a moment later. Treating an OMITTED reason as
+  // "clear it" replaced the host's copy with generic copy every single time.
+  let state = reduce(
+    createDefaultSessionState(),
+    setBlocked({ blocked: true, reason: 'contact ops@acme.com' }),
+  );
+
+  state = reduce(state, setBlocked({ blocked: true }));
+
+  assert.is(state.blocked, true);
+  assert.is(state.blockedReason, 'contact ops@acme.com', 'the host copy survives the re-latch');
+});
+
+Suite('reason:null clears the explanation while staying blocked', () => {
+  // The explicit escape hatch the omitted case gives up: `null` still clears.
+  let state = reduce(
+    createDefaultSessionState(),
+    setBlocked({ blocked: true, reason: 'stale copy' }),
+  );
+
+  state = reduce(state, setBlocked({ blocked: true, reason: null }));
+
+  assert.is(state.blocked, true);
+  assert.is(state.blockedReason, null, 'the banner falls back to the default copy');
+});
+
+Suite('resetSession still resets everything NOT on the preserved list', () => {
+  // Pins the boundary from the other side, so the preserved list cannot quietly
+  // grow: these are conversation/UI state and Clear must wipe them.
+  let state = reduce(createDefaultSessionState(), setBlocked({ blocked: true, reason: 'r' }));
+  state = reduce(state, setSessionMenuOpen(true));
+  state = reduce(state, setInputValue('half-typed message'));
+
+  const cleared = reduce(state, resetSession());
+
+  assert.is(cleared.inputValue, '', 'the composer draft is reset');
+  assert.is(cleared.sessionMenuOpen, false, 'the panel flag is reset');
+  assert.is(cleared.blocked, true, '…while the block is still preserved');
+});
+
+// ── Per-vendor latches (GENC-1464 per-vendor budgets) ──────────────────────────
+
+Suite('setVendorBlocked walls one vendor and keeps the wall order', () => {
+  let state = reduce(
+    createDefaultSessionState(),
+    setVendorBlocked({ vendor: 'anthropic', blocked: true, reason: 'anthropic copy' }),
+  );
+  assert.equal(state.blockedVendors, ['anthropic']);
+  assert.equal(state.blockedVendorReasons, { anthropic: 'anthropic copy' });
+  assert.is(state.blocked, false, 'the vendor-agnostic flag is untouched');
+
+  state = reduce(state, setVendorBlocked({ vendor: 'gemini', blocked: true }));
+  assert.equal(
+    state.blockedVendors,
+    ['anthropic', 'gemini'],
+    'order is the order they were walled',
+  );
+});
+
+Suite('walling an already-walled vendor is idempotent', () => {
+  let state = reduce(
+    createDefaultSessionState(),
+    setVendorBlocked({ vendor: 'gemini', blocked: true, reason: 'first' }),
+  );
+  state = reduce(state, setVendorBlocked({ vendor: 'gemini', blocked: true, reason: 'second' }));
+  assert.equal(state.blockedVendors, ['gemini'], 'no duplicate entry');
+  assert.is(state.blockedVendorReasons.gemini, 'second');
+});
+
+Suite('the per-vendor reason honours the same three cases as setBlocked', () => {
+  // The same two-writer race (driver latch landing after a bus-subscribed host)
+  // applies per vendor, so "omitted keeps" has to hold here too.
+  let state = reduce(
+    createDefaultSessionState(),
+    setVendorBlocked({ vendor: 'anthropic', blocked: true, reason: 'host copy' }),
+  );
+
+  state = reduce(state, setVendorBlocked({ vendor: 'anthropic', blocked: true }));
+  assert.is(state.blockedVendorReasons.anthropic, 'host copy', 'omitted keeps');
+
+  state = reduce(state, setVendorBlocked({ vendor: 'anthropic', blocked: true, reason: null }));
+  assert.is(state.blockedVendorReasons.anthropic, undefined, 'null clears');
+});
+
+Suite('releasing a vendor drops it and its copy', () => {
+  let state = reduce(
+    createDefaultSessionState(),
+    setVendorBlocked({ vendor: 'anthropic', blocked: true, reason: 'r' }),
+  );
+  state = reduce(state, setVendorBlocked({ vendor: 'gemini', blocked: true }));
+
+  state = reduce(state, setVendorBlocked({ vendor: 'anthropic', blocked: false }));
+
+  assert.equal(state.blockedVendors, ['gemini']);
+  assert.is(state.blockedVendorReasons.anthropic, undefined);
+});
+
+Suite('setBlocked(false) also clears every per-vendor latch', () => {
+  // THE back-compat rule. A host asserting "the wall is gone" after its own
+  // pre-flight (migration-GENC-1464 Option B) must not be overruled by a driver
+  // latch it cannot see — without this, per-vendor would silently make the
+  // documented unblock stop working.
+  let state = reduce(
+    createDefaultSessionState(),
+    setVendorBlocked({ vendor: 'anthropic', blocked: true, reason: 'r' }),
+  );
+  state = reduce(state, setBlocked({ blocked: true, reason: 'global' }));
+
+  state = reduce(state, setBlocked({ blocked: false }));
+
+  assert.is(state.blocked, false);
+  assert.is(state.blockedReason, null);
+  assert.equal(state.blockedVendors, []);
+  assert.equal(state.blockedVendorReasons, {});
+});
+
+Suite('setBlockedReason writes the copy without disturbing any latch', () => {
+  // It exists precisely so the element's `blockedReason` setter cannot route
+  // through `setBlocked(false, …)` — which would now clear the vendor latches.
+  let state = reduce(
+    createDefaultSessionState(),
+    setVendorBlocked({ vendor: 'gemini', blocked: true }),
+  );
+
+  state = reduce(state, setBlockedReason('host copy'));
+
+  assert.is(state.blockedReason, 'host copy');
+  assert.is(state.blocked, false, 'the vendor-agnostic flag is untouched');
+  assert.equal(state.blockedVendors, ['gemini'], 'and so are the per-vendor latches');
+});
+
+Suite('resetSession preserves the per-vendor latches too', () => {
+  let state = reduce(
+    createDefaultSessionState(),
+    setVendorBlocked({ vendor: 'anthropic', blocked: true, reason: 'no funds' }),
+  );
+  state = reduce(state, setMessages([{ role: 'user', content: 'hi' }] as ChatMessage[]));
+
+  const cleared = reduce(state, resetSession());
+
+  assert.equal(cleared.messages, [], 'the conversation is wiped');
+  assert.equal(cleared.blockedVendors, ['anthropic'], 'Clear does not refill a vendor budget');
+  assert.equal(cleared.blockedVendorReasons, { anthropic: 'no funds' });
+});
+
+// `resetSession` preserves its keys through `Object.assign`, whose source parameter
+// is structurally permissive: a typo like `blockedResaon` would compile clean,
+// silently stop preserving the real key, AND leak a junk key into serialised state.
+// The reducer therefore annotates its literal `satisfies
+// Partial<AiAssistantSessionState>`, which is a COMPILE-time guarantee — so the
+// durable proof is a type fixture, not a runtime assertion.
+//
+// This mirrors the reducer's clause on the same typo. If `satisfies` ever stopped
+// rejecting excess properties (a TS behaviour change, or someone widening the
+// annotated type), the `@ts-expect-error` below becomes unused and the BUILD fails
+// — which is exactly the signal wanted. The runtime suites above are its
+// behavioural companions: they pin the preserved list from both sides.
+const _typoIsRejectedAtCompileTime = {
+  // @ts-expect-error — an excess/misspelled key must be rejected by `satisfies`
+  blockedResaon: null,
+} satisfies Partial<AiAssistantSessionState>;
+void _typoIsRejectedAtCompileTime;
+
 Suite.run();

package/src/state/ai-assistant-slice.ts

@@ -1,6 +1,7 @@
 import type {
   AggregateUsage,
   AIProviderRegistryStatusEntry,
+  AIProviderType,
   ChatInputDuringExecutionMode,
   ChatMessage,
 } from '@genesislcap/foundation-ai';
@@ -62,6 +63,10 @@ export interface AiAssistantSessionState {
    * Snapshot of every registered provider's status, in registration order.
    * Populated on connect (or on settings-open if not yet loaded) and reused
    * for the lifetime of the session — provider registration is static.
+   *
+   * Describes the registry rather than the conversation, so it survives
+   * {@link resetSession} ("Clear" / "New chat"); see the reasoning there. Only
+   * a registry change (via the observable-registry subscription) rewrites it.
    */
   providerStatuses: AIProviderRegistryStatusEntry[];
   activeAgent: Omit<AgentConfig, 'toolHandlers'> | undefined;
@@ -117,6 +122,66 @@ export interface AiAssistantSessionState {
    * being clobbered** when the restored history loads.
    */
   restoring: boolean;
+  /**
+   * Whether the assistant is **blocked by a backend condition** and cannot send
+   * at all — today, an exhausted AI-spend budget (GENC-1464). Unlike `compacting`
+   * and `restoring`, which are short-lived in-flight flags that clear
+   * themselves, this is a **latched** state: nothing the user or the element
+   * does clears it, because nothing they can do fixes it. It stays set until the
+   * host writes `blocked = false` (typically after a fresh pre-flight shows
+   * budget available again).
+   *
+   * Also unlike those two, it does **not** replace the transcript — the user
+   * keeps their conversation and gets a banner above a disabled composer.
+   *
+   * In the slice so the banner + input-disable stay in sync across pop-in/out.
+   * Preserved across `resetSession` ("Clear" / "New chat"): starting a new chat
+   * does not refill the budget.
+   *
+   * **Vendor-agnostic.** Under per-vendor budgets this means "blocked whatever
+   * vendor you use" — a host-set block, or a wall that could not be attributed
+   * to a vendor. A wall that WAS attributed lands in
+   * {@link AiAssistantSessionState.blockedVendors} instead, and the element
+   * derives its public `blocked` from the two together.
+   */
+  blocked: boolean;
+  /**
+   * Host- or driver-supplied explanation shown in the blocked banner. `null`
+   * falls back to the element's default copy. Meaningless while
+   * {@link AiAssistantSessionState.blocked} is false.
+   */
+  blockedReason: string | null;
+  /**
+   * Vendors walled by the AI-spend budget (GENC-1464 per-vendor), in the order they
+   * were walled.
+   *
+   * An **array**, not a `Set` and not one `Record<AIProviderType, {...}>`:
+   * a `Set` is neither plain JSON for the redux store nor structured-cloneable
+   * across the tab channel; the order is what the multi-vendor banner copy
+   * ("Anthropic and Gemini") reads; and a combined record would conflate "not
+   * walled" with "walled, no reason".
+   *
+   * Empty for every host that never adopts the per-vendor API — which is what
+   * makes the element's derived `blocked` byte-identical to the old stored one.
+   */
+  blockedVendors: AIProviderType[];
+  /**
+   * The subset of {@link AiAssistantSessionState.blockedVendors} walled by the
+   * `otherVendorAvailable: false` SWEEP rather than by a refusal of their own.
+   * Provenance, not a second wall list: for locking, `blockedVendors` remains
+   * the whole truth. The distinction exists for the banner's unknown-reachability
+   * fallback — a refusal is a fact about a vendor the user just used and is
+   * nameable anywhere; a sweep entry is a headroom fact about the PROXY, and
+   * naming it before the statuses reveal whether the host even ships that vendor
+   * put a vendor in front of the user that may not be theirs.
+   */
+  sweptVendors: AIProviderType[];
+  /**
+   * Per-vendor banner copy, keyed by a member of
+   * {@link AiAssistantSessionState.blockedVendors}. A missing entry falls back to
+   * copy composed from the vendor's display name.
+   */
+  blockedVendorReasons: Partial<Record<AIProviderType, string>>;
   /** Draft text in the input box — preserved across pop-in/pop-out cycles. */
   inputValue: string;
   /** Live trace from a currently-executing sub-agent. Cleared on sub-agent-stop. */
@@ -179,6 +244,11 @@ export function createDefaultSessionState(): AiAssistantSessionState {
     sessionMenuOpen: false,
     compacting: false,
     restoring: false,
+    blocked: false,
+    blockedReason: null,
+    blockedVendors: [],
+    sweptVendors: [],
+    blockedVendorReasons: {},
     inputValue: '',
     liveSubAgentTrace: [],
     liveSubAgentName: null,
@@ -258,6 +328,105 @@ export const aiAssistantSlice = createSlice({
     setRestoring(state, action: PayloadAction<boolean>) {
       state.restoring = action.payload;
     },
+    /**
+     * Latch (or release) the backend-blocked state.
+     *
+     * `reason` is only meaningful while blocking, and it distinguishes three
+     * cases rather than two:
+     *
+     * - **omitted** — a re-latch that leaves the existing explanation intact.
+     *   Load-bearing: the block has two writers (the host, and the driver's
+     *   automatic latch), and the driver's write lands AFTER a bus-subscribed
+     *   host has already set its own detailed copy. Treating "no reason" as
+     *   "clear the reason" made that sequence replace the host's figures with
+     *   generic copy every time, deterministically.
+     * - **a string** — replaces the explanation.
+     * - **`null`** — explicitly clears the explanation while staying blocked;
+     *   the banner falls back to the element's default copy.
+     *
+     * Unblocking always clears it, so a stale explanation can never outlive the
+     * condition it described.
+     *
+     * Unblocking **also clears every per-vendor latch**, and that is the single
+     * rule that keeps per-vendor budgets non-breaking. A host asserting "the wall
+     * is gone" (the documented pre-flight, migration-GENC-1464 Option B) must not be
+     * silently overruled by a driver latch it cannot see; without this, the same
+     * `setBlocked(false)` that used to unblock would leave the composer locked.
+     */
+    setBlocked(state, action: PayloadAction<{ blocked: boolean; reason?: string | null }>) {
+      state.blocked = action.payload.blocked;
+      if (!action.payload.blocked) {
+        state.blockedReason = null;
+        state.blockedVendors = [];
+        state.sweptVendors = [];
+        state.blockedVendorReasons = {};
+      } else if (action.payload.reason !== undefined) {
+        state.blockedReason = action.payload.reason;
+      }
+    },
+    /**
+     * Write the banner explanation without touching the flag.
+     *
+     * Separate from {@link setBlocked} rather than expressed as
+     * `setBlocked({ blocked: current, reason })`, because the element's public
+     * `blocked` is now DERIVED: re-latching with the derived value would pass
+     * `false` for a partially-walled session and so clear every per-vendor latch
+     * as a side effect of setting a string.
+     */
+    setBlockedReason(state, action: PayloadAction<string | null>) {
+      state.blockedReason = action.payload;
+    },
+    /**
+     * Wall (or release) a single vendor's budget.
+     *
+     * The `reason` trichotomy mirrors {@link setBlocked}'s exactly, and for the
+     * same reason: the same two-writer race (the driver's latch landing after a
+     * bus-subscribed host has written its own copy) applies per vendor.
+     *
+     * Adding an already-walled vendor is idempotent — the array is a set with an
+     * order, so the vendor keeps the position it was first walled at.
+     */
+    setVendorBlocked(
+      state,
+      action: PayloadAction<{
+        vendor: AIProviderType;
+        blocked: boolean;
+        reason?: string | null;
+        /**
+         * Marks the wall as SWEEP-derived (see `sweptVendors`). Only the
+         * element's `otherVendorAvailable: false` sweep passes `true`; a host
+         * call or a refusal latch leaves it unset, which also UPGRADES a
+         * previously swept vendor — a refusal (or an explicit host statement)
+         * is nameable evidence, and first-hand evidence beats the verdict.
+         */
+        swept?: boolean;
+      }>,
+    ) {
+      const { vendor, blocked, reason, swept } = action.payload;
+      const index = state.blockedVendors.indexOf(vendor);
+      const sweptIndex = state.sweptVendors.indexOf(vendor);
+      if (blocked) {
+        if (index < 0) state.blockedVendors.push(vendor);
+        if (swept) {
+          // Provenance is FIRST-writer-wins: marking swept only records a wall
+          // this call itself created. The sweep site already skips walled
+          // vendors, so this guard is belt-and-braces against a future caller
+          // downgrading a refused wall to "just the proxy's word".
+          if (index < 0 && sweptIndex < 0) state.sweptVendors.push(vendor);
+        } else if (sweptIndex >= 0) {
+          state.sweptVendors.splice(sweptIndex, 1);
+        }
+        if (reason === null) {
+          delete state.blockedVendorReasons[vendor];
+        } else if (reason !== undefined) {
+          state.blockedVendorReasons[vendor] = reason;
+        }
+      } else {
+        if (index >= 0) state.blockedVendors.splice(index, 1);
+        if (sweptIndex >= 0) state.sweptVendors.splice(sweptIndex, 1);
+        delete state.blockedVendorReasons[vendor];
+      }
+    },
     setInputValue(state, action: PayloadAction<string>) {
       state.inputValue = action.payload;
     },
@@ -299,21 +468,62 @@ export const aiAssistantSlice = createSlice({
     },
     /**
      * Wipe the session back to a fresh default — the "Clear" / "New chat" action.
-     * The user's **display preferences** (tool-call / thinking / narration / agent-switch
-     * visibility + animations) are deliberately preserved across Clear: they are settings,
-     * not conversation state, and are persisted independently of the snapshot (GENC-1351).
-     * Without this they'd flip to their all-off defaults in the live store on Clear, since
-     * `clearSession` re-applies no baseline and the idempotent setters suppress a re-apply.
+     *
+     * Three categories survive, for three different reasons — keep them distinct:
+     *
+     * 1. The user's **display preferences** (tool-call / thinking / narration /
+     *    agent-switch visibility + animations). They are settings, not
+     *    conversation state, and are persisted independently of the snapshot
+     *    (GENC-1351). Without this they'd flip to their all-off defaults in the
+     *    live store on Clear, since `clearSession` re-applies no baseline and the
+     *    idempotent setters suppress a re-apply.
+     * 2. The **backend block** (`blocked` / `blockedReason`, and the per-vendor
+     *    latches beside them). Not a preference at
+     *    all — a standing backend condition that Clear cannot change. It is here
+     *    because starting a new chat does not refill the AI budget, so clearing
+     *    it would hand the user a working-looking composer that fails on the very
+     *    next send.
+     * 3. The **provider statuses**. They describe the REGISTRY, not the
+     *    conversation — provider registration is static for the store's lifetime
+     *    and this snapshot is refreshed from the registry, never from a turn. They
+     *    are session state only because that is where the element's store lives.
+     *
+     *    Dropping them on Clear is not cosmetic: the element derives `blocked`
+     *    from "every REACHABLE vendor is walled", and an empty reachable set fails
+     *    safe to "blocked". So wiping the statuses while keeping the per-vendor
+     *    latches (category 2) escalated one walled vendor out of two into a fully
+     *    locked composer, and nothing reloads them — `loadProviderStatuses()` runs
+     *    only on connect/session-switch and from the observable-registry
+     *    subscription, so a host with a static registry stayed locked until a
+     *    remount. Preserving is the fix rather than re-loading after reset,
+     *    because the reload is async: it would still flash a fully locked composer
+     *    for a turn of the event loop, and would break a host whose registry is
+     *    immutable (nothing to re-listen to) or whose `listStatuses()` rejects.
+     *
+     * Stated separately so a future contributor deciding what belongs in this
+     * list does not "tidy" the block out on the grounds that it is not a display
+     * preference.
      */
     resetSession(state) {
-      const preservedPrefs = {
+      // `satisfies` gives this literal excess-property checking and per-field type
+      // checking, neither of which `Object.assign` provides — its source parameter
+      // is structurally permissive, so a typo (`blockedResaon`) would compile
+      // clean, silently stop preserving the real key, AND add a junk key to the
+      // draft that then leaks into serialised state.
+      const preservedAcrossReset = {
         showToolCalls: state.showToolCalls,
         showThinkingSteps: state.showThinkingSteps,
         showNarration: state.showNarration,
         showAgentSwitchIndicator: state.showAgentSwitchIndicator,
         enabledAnimations: state.enabledAnimations,
-      };
-      Object.assign(state, createDefaultSessionState(), preservedPrefs);
+        providerStatuses: state.providerStatuses,
+        blocked: state.blocked,
+        blockedReason: state.blockedReason,
+        blockedVendors: state.blockedVendors,
+        sweptVendors: state.sweptVendors,
+        blockedVendorReasons: state.blockedVendorReasons,
+      } satisfies Partial<AiAssistantSessionState>;
+      Object.assign(state, createDefaultSessionState(), preservedAcrossReset);
     },
   },
   selectors: {},

package/src/state/debug-event-log.test.ts

@@ -1,7 +1,9 @@
+import type { SubAgentFailureReason, TurnFailureReason } from '@genesislcap/foundation-ai';
 import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
 import {
   clearMetaEventRegistry,
   clearSession,
+  DEBUG_LOG_README,
   getMetaEvents,
   type MetaEvent,
   mergeMetaEvents,
@@ -86,4 +88,65 @@ suite('clearSession drops one key without touching others', () => {
   assert.is(getMetaEvents('parent').length, 1);
 });
 
+// ── README ↔ taxonomy sync (GENC-1464) ─────────────────────────────────────────
+// DEBUG_LOG_README is emitted as the FIRST key of the exported debug log
+// specifically so an agent reading the JSON does not have to reverse-engineer it.
+// Its reason enumerations therefore read as exhaustive and will be trusted — but
+// they had already drifted twice (`refusal` was missing from both) before anyone
+// noticed, because "the doc lives next to the catalogue" is not enforcement.
+//
+// The `Record<..., true>` below is the enforcement: adding a union member without
+// listing it here is a COMPILE error, and listing it without documenting it is a
+// test failure. So the next added reason fails in the one place the drift keeps
+// happening.
+
+const ALL_TURN_FAILURE_REASONS = Object.keys({
+  exception: true,
+  'malformed-function-call': true,
+  'empty-response': true,
+  'unknown-tool-limit': true,
+  'max-iterations': true,
+  'response-truncated': true,
+  refusal: true,
+  'budget-exhausted': true,
+} satisfies Record<TurnFailureReason, true>) as TurnFailureReason[];
+
+const ALL_SUB_AGENT_FAILURE_REASONS = Object.keys({
+  max_iterations: true,
+  malformed_tool_call: true,
+  empty_response: true,
+  unknown_tool_limit: true,
+  timeout: true,
+  response_truncated: true,
+  refusal: true,
+  budget_exhausted: true,
+} satisfies Record<SubAgentFailureReason, true>) as SubAgentFailureReason[];
+
+const README_TEXT = DEBUG_LOG_README.join('\n');
+
+suite('DEBUG_LOG_README enumerates every TurnFailureReason', () => {
+  for (const reason of ALL_TURN_FAILURE_REASONS) {
+    assert.ok(
+      README_TEXT.includes(reason),
+      `turn.error reason '${reason}' is missing from DEBUG_LOG_README`,
+    );
+  }
+});
+
+suite('DEBUG_LOG_README enumerates every SubAgentFailureReason', () => {
+  for (const reason of ALL_SUB_AGENT_FAILURE_REASONS) {
+    assert.ok(
+      README_TEXT.includes(reason),
+      `subagent.failed reason '${reason}' is missing from DEBUG_LOG_README`,
+    );
+  }
+});
+
+suite('DEBUG_LOG_README documents the budget diagnostics that ride turn.error', () => {
+  // `recordTurnError('budget-exhausted', …)` attaches these; an agent triaging a
+  // support ticket needs to know to look for them.
+  assert.ok(README_TEXT.includes('budgetUsd'));
+  assert.ok(README_TEXT.includes('spentUsd'));
+});
+
 suite.run();

package/src/state/debug-event-log.ts

@@ -307,7 +307,12 @@ export function clearSession(key: string): void {
  * Human/agent-facing guide emitted as the first key of the exported debug log,
  * so whoever opens the JSON (often an AI agent) knows how to read it without
  * reverse-engineering the shape. Kept here next to the event catalogue it
- * describes so the two stay in sync.
+ * describes — but proximity alone demonstrably did NOT keep the two in sync
+ * (`refusal` was missing from both reason lists for a whole release), so
+ * `debug-event-log.test.ts` now asserts that every `TurnFailureReason` and every
+ * `SubAgentFailureReason` is named here, and fails the build when one is added
+ * without a matching sentence. Enumerations below read as exhaustive and WILL be
+ * trusted by an agent reading the JSON — keep them so.
  */
 export const DEBUG_LOG_README: readonly string[] = [
   'This is an exported debug log for the Genesis AI assistant. Read it top-to-bottom.',
@@ -319,7 +324,7 @@ export const DEBUG_LOG_README: readonly string[] = [
   "kind:'turn'.`agentSnapshot` — the active agent's own view of its internal state, captured at that turn. An agent opts into this by exposing a `getDebugSnapshot()` that returns JSON-serializable per-state info; stateful/flow agents wire it automatically, so you can watch a flow advance turn-by-turn (e.g. current step, cursor, collected fields, pending changes). Absent for agents that don't expose one.",
   "kind:'event' — a meta/lifecycle event. `type` names it (see below); `detail` carries structured data. `detail.placement` is the emitting UI instance: 'bubble' (collapsed), 'panel' (popped-out), or 'standalone'.",
   "Each 'event' also has an `importance`: 'high' (failures/limits — turn.error, tool.failed, subagent.failed, file.read-failed, suggestions.failed, context.threshold-crossed), 'normal' (session flow — connects, turns, retries, handoffs, agent/provider changes, interactions, sub-agent start/complete), or 'low' (skippable UI/bookkeeping noise — panel.toggled, attachment.added, driver.wired/unwired, context.updated, context.condensed). To skim, ignore importance:'low'; to triage a failure, filter to importance:'high' then read the nearby messages and turns. A 'high' turn.error is often preceded by one or more 'normal' turn.retry events for the same reason — read them together to see how many attempts were made before bailing. 'message' and 'turn' entries carry no importance — they are the substance, always read them.",
-  'Event types: assistant.connected/disconnected (mount + placement + whether the session was created or restored), assistant.popout/popin (window placement), driver.created/wired/unwired (which driver is live and why it stops/starts responding across a popout), state.changed (idle↔loading), turn.start/turn.end (turn boundary; turn.end carries durationMs), turn.retry (a recoverable in-turn retry — detail.reason plus attempt/maxAttempts; for malformed calls also finishMessage; for empty responses also the provider finishReason + thoughtsTokens + parts breakdown), turn.error (a turn failed or hit a guardrail — detail.reason is one of exception/malformed-function-call/empty-response/unknown-tool-limit/max-iterations/response-truncated, plus reason-specific diagnostics: attempts (for empty-response also finishReason + thoughtsTokens + a parts breakdown, distinguishing a thinking-only STOP from a truly empty turn), finishMessage, for response-truncated the model + maxTokens + outputTokens + tools, unknownTools (split into staleTools — real earlier this activation but retired by the current state or hidden behind an open exclusive fold — and hallucinatedTools — never advertised) + availableTools, iterations + limit, or name + message for exceptions), tool.failed (a tool threw), tool.unresolved (the model called a tool that could not be dispatched — detail.kind is folded/fold-hidden/stale/unknown, plus tool + agent and, for the counted kinds, the consecutive streak; the recurring lead-up to an unknown-tool-limit turn.error), subagent.started/completed/failed (the lifecycle of a `requestSubAgent` delegation — detail.agent names the sub-agent; these bracket the sub-agent turns that appear as kind:turn entries with an N-M `turnIndex`; subagent.failed also carries detail.reason, one of max_iterations/malformed_tool_call/empty_response/unknown_tool_limit/timeout/response_truncated), agent.handoff (routing; from=null is the initial activation), agent.pinned/unpinned (forced routing), provider.selected (model/provider for the upcoming turns), interaction.requested/resolved (blocking user widgets — explain quiet gaps; note that when a sub-agent opens a widget, detail.agent — and the agentName on the interaction message — is the HOST agent that owns the widget, NOT the sub-agent that asked, because widgets render and resolve on the host driver), context.updated/threshold-crossed (token + cost), context.condensed (a stale tool payload was collapsed out of the model-bound history by a `condenseWhen` declaration on the tool — detail.tool + toolCallId, target args|response, trigger (superseded:<key> or age:<n>), stubLen, and an estimated tokensSaved; stored history and this log keep the FULL payload, so the model-visible slice at any point is the full history minus the condensations recorded up to then), panel.toggled, attachment.added, file.read-failed, suggestions.failed.',
+  'Event types: assistant.connected/disconnected (mount + placement + whether the session was created or restored), assistant.popout/popin (window placement), driver.created/wired/unwired (which driver is live and why it stops/starts responding across a popout), state.changed (idle↔loading), turn.start/turn.end (turn boundary; turn.end carries durationMs), turn.retry (a recoverable in-turn retry — detail.reason plus attempt/maxAttempts; for malformed calls also finishMessage; for empty responses also the provider finishReason + thoughtsTokens + parts breakdown), turn.error (a turn failed or hit a guardrail — detail.reason is one of exception/malformed-function-call/empty-response/unknown-tool-limit/max-iterations/response-truncated/refusal/budget-exhausted, plus reason-specific diagnostics: attempts (for empty-response also finishReason + thoughtsTokens + a parts breakdown, distinguishing a thinking-only STOP from a truly empty turn), finishMessage, for response-truncated the model + maxTokens + outputTokens + tools, unknownTools (split into staleTools — real earlier this activation but retired by the current state or hidden behind an open exclusive fold — and hallucinatedTools — never advertised) + availableTools, iterations + limit, for budget-exhausted the budgetUsd + spentUsd figures reported by the proxy plus the resolved vendor, or name + message for exceptions), tool.failed (a tool threw), tool.unresolved (the model called a tool that could not be dispatched — detail.kind is folded/fold-hidden/stale/unknown, plus tool + agent and, for the counted kinds, the consecutive streak; the recurring lead-up to an unknown-tool-limit turn.error), subagent.started/completed/failed (the lifecycle of a `requestSubAgent` delegation — detail.agent names the sub-agent; these bracket the sub-agent turns that appear as kind:turn entries with an N-M `turnIndex`; subagent.failed also carries detail.reason, one of max_iterations/malformed_tool_call/empty_response/unknown_tool_limit/timeout/response_truncated/refusal/budget_exhausted; budget_exhausted is terminal for the PARENT turn too — the parent stops rather than calling the model again into the same wall), agent.handoff (routing; from=null is the initial activation), agent.pinned/unpinned (forced routing), provider.selected (model/provider for the upcoming turns), interaction.requested/resolved (blocking user widgets — explain quiet gaps; note that when a sub-agent opens a widget, detail.agent — and the agentName on the interaction message — is the HOST agent that owns the widget, NOT the sub-agent that asked, because widgets render and resolve on the host driver), context.updated/threshold-crossed (token + cost), context.condensed (a stale tool payload was collapsed out of the model-bound history by a `condenseWhen` declaration on the tool — detail.tool + toolCallId, target args|response, trigger (superseded:<key> or age:<n>), stubLen, and an estimated tokensSaved; stored history and this log keep the FULL payload, so the model-visible slice at any point is the full history minus the condensations recorded up to then), panel.toggled, attachment.added, file.read-failed, suggestions.failed.',
   'Sub-agent meta events: a sub-agent\'s own turn.retry/turn.error/tool.failed/tool.unresolved events are merged into this same timeline, tagged with `detail.subAgent` — a `"<parent> › <sub-agent>"` breadcrumb that composes when nested (e.g. `"UI Builder › Planner › Grounding"`) — and interleaved by their original timestamps within the subagent.started→completed/failed bracket. These are the per-attempt/per-failure signals that do NOT appear among the sub-agent\'s (hoisted) messages: a malformed/empty attempt that gets retried produces no message, and the stale-vs-hallucinated split and streak counts live only on the event. A sub-agent\'s high-volume, message-derivable events (turn.start/turn.end, provider.selected, context.updated) are intentionally NOT merged — read its hoisted messages for model/tokens/cost and turn-by-turn activity, and the bracketing subagent.* events for the run\'s span.',
   "`meta` holds context captured at export time: agentSummary (full agent configs), context (active model, token usage, session cost), activeDebugSnapshot (the active agent's `getDebugSnapshot()` taken fresh at export — reflects state NOW, which may have advanced beyond the last turn's agentSnapshot), debug (optional host-supplied debug state), host, and the export timestamp.",
   'To debug a failure: find the last turn.error or tool.failed, then read upward for the user message, the turn(s), and the agent/provider/state events that led into it.',

package/src/state/persistence/session-snapshot.test.ts

@@ -44,6 +44,28 @@ Suite('createPersistedSession stamps version + savedAt and keeps agentSnapshots'
   assert.equal(s.agentSnapshots, { A: { machine: { state: 'x', context: {} } } });
 });
 
+// GENC-1464 — the blocked latch is deliberately NOT persisted. The snapshot is
+// per-stateKey and long-lived, so a persisted latch would survive an out-of-band
+// budget raise with no in-element way to clear it: the user would return to a
+// permanently dead composer against a budget that has headroom. Re-deriving the
+// state (host pre-flight on mount, or the next 402) is strictly safer than
+// remembering it. This test exists so a future "helpful" addition trips here and
+// has to read that reasoning first — see `FoundationAiAssistant.blocked`'s
+// Lifetime paragraph and docs/migration-GENC-1464.md §Scope.
+Suite('the blocked latch is deliberately not persisted', () => {
+  const s = base() as unknown as Record<string, unknown>;
+  assert.not.ok('blocked' in s, 'blocked must not enter the persisted snapshot');
+  assert.not.ok('blockedReason' in s, 'blockedReason must not enter the persisted snapshot');
+  // The per-vendor latches inherit the same lifetime, so they inherit the same
+  // rule — a persisted per-vendor wall is exactly as stale as a persisted global
+  // one, just harder to notice because only one vendor looks broken.
+  assert.not.ok('blockedVendors' in s, 'blockedVendors must not enter the persisted snapshot');
+  assert.not.ok(
+    'blockedVendorReasons' in s,
+    'blockedVendorReasons must not enter the persisted snapshot',
+  );
+});
+
 Suite('createPersistedSession defaults agentSnapshots to {}', () => {
   const s = createPersistedSession({
     sessionKey: 'k',