@genesislcap/ai-assistant 15.23.2 → 15.24.0-FUI-2603.10

package/dist/ai-assistant.d.ts

@@ -2,12 +2,12 @@ import { AgentPickerMode } from '@genesislcap/foundation-ai';
 import type { AggregateUsage } from '@genesislcap/foundation-ai';
 import { AIProviderRegistry } from '@genesislcap/foundation-ai';
 import type { AIProviderRegistryStatusEntry } from '@genesislcap/foundation-ai';
-import type { AIProviderType } from '@genesislcap/foundation-ai';
+import { AIProviderType } from '@genesislcap/foundation-ai';
 import { BudgetExhaustedError } from '@genesislcap/foundation-ai';
 import type { CachePolicy } from '@genesislcap/foundation-ai';
 import type { ChatAttachment } from '@genesislcap/foundation-ai';
 import type { ChatConfig } from '@genesislcap/foundation-ai';
-import type { ChatDriverResult } from '@genesislcap/foundation-ai';
+import { ChatDriverResult } from '@genesislcap/foundation-ai';
 import type { ChatFallback } from '@genesislcap/foundation-ai';
 import type { ChatInputDuringExecutionMode } from '@genesislcap/foundation-ai';
 import type { ChatMessage } from '@genesislcap/foundation-ai';
@@ -1719,6 +1719,26 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * the historical `{ reason: 'done' }`.
      */
     private turnDone;
+    /**
+     * End the turn on a terminal failure: fail upward when this driver is a sub-agent, speak
+     * to the user when it is not, and hand the reason to the caller either way.
+     *
+     * Only that fork lives here. Each exit keeps its own `recordTurnError` call, because the
+     * telemetry payload is what legitimately differs between them — attempt counts, token
+     * figures, tool names — and folding it in would mean one optional field per condition.
+     *
+     * `overrides.copy` serves the two walls whose prose is composed per occurrence:
+     * `budgetExhaustedBubble` names the vendor and can offer another, `providerRefusedBubble`
+     * prefers a host-supplied message. Every other exit reads its copy from the table.
+     *
+     * One exit stays out: the `BudgetExhaustedError` catch. Not because its shape differs —
+     * its two telemetry payloads are field-for-field identical — but because its main-turn
+     * branch calls `reportBudgetExhausted`, which is public and also serves
+     * `OrchestratingDriver`'s classification phase, where no tool loop is running. That
+     * method has to survive either way, so routing the catch through here would relocate the
+     * duplication rather than remove it.
+     */
+    private endTurnWithFailure;
     /**
      * Terminal budget outcome for a wall hit **outside** the tool loop — today,
      * `OrchestratingDriver`'s classification phase, which calls the provider
@@ -1756,15 +1776,6 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * has gone unpaid — so there is nothing here to compose. A host override wins verbatim.
      */
     private providerRefusedBubble;
-    /**
-     * Terminal provider-refusal outcome. Mirrors `reportBudgetExhausted` so the two walls behave
-     * identically from the caller's side, while keeping their diagnostics distinct.
-     *
-     * `kind` reaches the debug log and the result but never the transcript: it is what lets an operator
-     * tell "top up the account" from "rotate the key", and with cause-free user copy this is the only
-     * place that distinction survives.
-     */
-    private reportProviderRefused;
     /** The typed failure reason on a loop result, or `undefined` for a clean turn / handoff. */
     private static failureReasonOf;
     /**
@@ -2209,7 +2220,7 @@ export declare interface ChatDriverConfig {
      * Transcript copy appended when the AI-spend budget wall is hit (GENC-1464),
      * used VERBATIM — set it only to own the copy entirely (white-labelling).
      * When unset, the driver composes the bubble per wall: the neutral
-     * `DEFAULT_BUDGET_EXHAUSTED_MESSAGE`, upgraded with "switch to another AI
+     * `TURN_FAILURE_EXITS.budgetExhausted.copy`, upgraded with "switch to another AI
      * provider" advice only when the 402's `otherVendorAvailable` positively says
      * another metered vendor still has headroom — the same rule the blocked
      * banner applies, so the two surfaces can no longer contradict each other.
@@ -2228,7 +2239,7 @@ export declare interface ChatDriverConfig {
     budgetExhaustedMessage?: string;
     /**
      * Overrides the transcript sentence shown when the upstream PROVIDER refuses the account
-     * (GENC-1506) — see `DEFAULT_PROVIDER_REFUSED_MESSAGE`.
+     * (GENC-1506) — see `TURN_FAILURE_EXITS.providerRefused.copy`.
      *
      * Separate from `budgetExhaustedMessage` because the two conditions are separate: ours is a spend
      * cap a host administrator can raise, this is the vendor declining to serve us at all. A host that
@@ -2761,6 +2772,35 @@ export declare function formatBlockedReason(budget?: Partial<Extract<ChatDriverR
  * @beta
  */
 export declare class FoundationAiAssistant extends GenesisElement {
+    private readonly composerResize;
+    private readonly composerMenus;
+    private readonly attachmentCtrl;
+    /**
+     * Pure derivation — owns no state. Reaches the driver only through the two
+     * callbacks below, so it stays clear of the stateful-agent surface (§11.2
+     * constraint 2) and of redux entirely.
+     */
+    private readonly contextGateCtrl;
+    /**
+     * Cost accounting and the persisted build-history ledger (GENC-1475). Reads the live
+     * session through callbacks and owns the rows, the load/write latches and the debounce
+     * timer — the element keeps only the names the settings modal binds.
+     */
+    private readonly costLedger;
+    /**
+     * The AI-spend budget: vendor walls, the derived composer lock, the banner copy
+     * and the settings meter (GENC-1464).
+     *
+     * Takes the session store itself rather than a callback per field — see
+     * `BudgetDeps` for why this one differs from its siblings.
+     */
+    private readonly budget;
+    /**
+     * The settings modal (`docs/code-health.md` §3). Reaches the two design-system
+     * refs through callbacks, because the template writes them by name — see
+     * `SettingsModalDeps`.
+     */
+    private readonly settings;
     providerRegistry: AIProviderRegistry;
     appSettingsProvider: AssistantAppSettingsProvider;
     designSystemPrefix: string;
@@ -3050,22 +3090,10 @@ export declare class FoundationAiAssistant extends GenesisElement {
     /**
      * The distinct vendors the registry can currently reach, from the provider
      * statuses this element already loads on connect and refreshes on every
-     * observable-registry change.
-     *
-     * This is the element's answer to "which vendor would the next turn use" — a
-     * question that has **no** correct answer and deliberately gets no API. The
-     * provider is resolved per turn AND per agent: `activeProviderInput` may be an
-     * async function of the turn's context, an orchestrated turn picks its agent
-     * with an LLM `classify()` call, and sub-agents resolve their own providers.
-     * Any pre-turn "peek" would therefore be a guess that is wrong precisely on the
-     * multi-agent hosts per-vendor budgets exist for.
-     *
-     * Asking instead which vendors are REACHABLE is answerable, synchronous, and
-     * free — and it is enough: the composer must stay live while any reachable
-     * vendor has headroom, and must lock when none does. It also makes vendor-switch
-     * recovery a derivation rather than a mutation: a host that swaps its registry
-     * to another vendor fires the observable, the statuses reload, the walled vendor
-     * drops out of this set, and `blocked` goes false with every latch left intact.
+     * observable-registry change — this element's answer to "which vendor would the
+     * next turn use", a question that has no correct answer and deliberately gets
+     * no API. See `BudgetController.reachableVendors` for why reachability is
+     * the answerable question and what deriving from it buys.
      *
      * @beta
      */
@@ -3076,13 +3104,11 @@ export declare class FoundationAiAssistant extends GenesisElement {
      *
      * May include a vendor this registry cannot reach — either because the registry
      * moved on after the wall was latched, or because a 402's
-     * `otherVendorAvailable: false` walls every vendor the proxy meters (which is
-     * what that verdict is a statement about; see
-     * {@link FoundationAiAssistant.latchBlockedFrom}). Neither costs anything
-     * internally — {@link FoundationAiAssistant.blocked} asks only about the
-     * reachable set, and the banner reads the reachability-filtered
-     * {@link FoundationAiAssistant.relevantBlockedVendors} — but a host rendering
-     * this list itself should filter it against its own registry.
+     * `otherVendorAvailable: false` walls every vendor the proxy meters. Neither
+     * costs anything internally — {@link FoundationAiAssistant.blocked} asks only
+     * about the reachable set, and the banner reads the reachability-filtered
+     * `BudgetController.relevantBlockedVendors` — but a host rendering this
+     * list itself should filter it against its own registry.
      *
      * Read-only on purpose: a settable array would let a host write a partial list
      * and silently orphan the per-vendor banner copy.
@@ -3108,30 +3134,20 @@ export declare class FoundationAiAssistant extends GenesisElement {
      * become true.
      *
      * `reason` is composed into the banner sentence for that vendor, **however many
-     * vendors are walled** — see {@link FoundationAiAssistant.effectiveBlockedReason}.
-     * It is per-vendor copy, not a whole-banner override; {@link FoundationAiAssistant.blockedReason}
-     * is the override. Omitting it keeps whatever explanation that vendor already
-     * carried, so a driver latch landing after a host one cannot blank it.
-     *
-     * `'none'` is rejected with a warning rather than accepted: it is the "no
-     * provider configured" sentinel, not a vendor. Latching it would put the raw
-     * sentinel in the banner ("none's AI usage limit is reached") and could never
-     * be undone by derivation, because `'none'` never appears in
-     * {@link FoundationAiAssistant.reachableVendors} — so `blocked` could never
-     * become derivable from it either. Use {@link FoundationAiAssistant.setBlocked}
-     * for a vendor-agnostic block.
+     * vendors are walled** — see `BudgetController.effectiveBlockedReason`.
+     * It is per-vendor copy, not a whole-banner override;
+     * {@link FoundationAiAssistant.blockedReason} is the override. Omitting it keeps
+     * whatever explanation that vendor already carried, so a driver latch landing
+     * after a host one cannot blank it.
+     *
+     * `'none'` is rejected with a warning rather than accepted — it is the "no
+     * provider configured" sentinel, not a vendor, and a wall on it could never be
+     * undone by derivation. Use {@link FoundationAiAssistant.setBlocked} for a
+     * vendor-agnostic block.
      *
      * @beta
      */
     setVendorBlocked(vendor: AIProviderType, blocked: boolean, reason?: string | null): void;
-    /**
-     * One warning per element for garbage fed to
-     * {@link FoundationAiAssistant.setVendorBudget}. Once, not per call, because
-     * the documented feed re-runs after every turn — a host bug would otherwise
-     * repeat the same warning on every send for the life of the page.
-     */
-    private vendorBudgetWarningIssued;
-    private warnVendorBudgetOnce;
     /**
      * Feed (or clear) one vendor's AI-spend figures for the settings-modal budget
      * meter — the numeric companion to
@@ -3194,8 +3210,9 @@ export declare class FoundationAiAssistant extends GenesisElement {
         spentUsd: number;
     } | null): boolean;
     /**
-     * When budget figures last arrived — from the host's {@link FoundationAiAssistant.setVendorBudget}
-     * or the wall latch's own feed — as epoch ms; `null` until the first feed.
+     * When budget figures last arrived — from the host's
+     * {@link FoundationAiAssistant.setVendorBudget} or the wall latch's own feed —
+     * as epoch ms; `null` until the first feed.
      *
      * ELEMENT state, not slice state, on purpose: the reducer is idempotent by
      * value (an unchanged re-feed must not re-render the meter rows), but "when
@@ -3203,7 +3220,8 @@ export declare class FoundationAiAssistant extends GenesisElement {
      * refresh that confirms the same dollars is still a refresh. Only the
      * toolbar label observes this, so a stamp re-renders one span, not the rows.
      */
-    budgetMeterLastFedAt: number | null;
+    get budgetMeterLastFedAt(): number | null;
+    set budgetMeterLastFedAt(value: number | null);
     /** "Updated HH:MM:SS" for the meter toolbar, or `undefined` before any feed. */
     get settingsBudgetUpdatedLabel(): string | undefined;
     /**
@@ -3218,83 +3236,24 @@ export declare class FoundationAiAssistant extends GenesisElement {
      * listener simply keeps the per-turn cadence.
      */
     requestBudgetRefresh(): void;
-    /** Whether this vendor's wall came from the sweep alone — see the slice's `sweptVendors`. */
-    private isVendorSwept;
-    /**
-     * The walled vendors the user can still be routed to — i.e.
-     * {@link FoundationAiAssistant.blockedVendors} narrowed to the reachable set,
-     * which is the only set the banner may name.
-     *
-     * A wall the registry can no longer reach is not news: it cannot be hit, and
-     * naming it puts a vendor in front of the user that is not theirs. The concrete
-     * failure this exists to stop: a host ships Anthropic-only, Anthropic walls, the
-     * host swaps its registry to Gemini, Gemini walls — and the banner reads "AI
-     * usage limits are reached for Anthropic and Gemini" to a user who has never
-     * had an Anthropic key. The spurious second name also flips the copy onto the
-     * plural branch, so even the closing sentence is wrong.
-     *
-     * When nothing is reachable YET (the statuses are still loading — the exact
-     * window the pre-flight and the cross-tab bus latch into), the fallback keeps
-     * every wall for LOCKING (`blocked` still derives true) but names only the
-     * vendors walled by a REFUSAL, dropping the ones the `otherVendorAvailable`
-     * sweep added. A refusal is a fact about a vendor this user just used; a sweep
-     * entry is the proxy's headroom verdict about a vendor the host may not even
-     * ship — naming it here reproduced the exact failure above from the other
-     * direction ("Gemini's AI usage limit is reached" to an Anthropic-only user),
-     * and flipped the copy onto the plural branch with it. Self-corrects when the
-     * statuses land: from then on reachability, not provenance, decides.
-     *
-     * @internal
-     */
-    private get relevantBlockedVendors();
     /**
      * Whether the blocked banner has anything to say — a vendor-agnostic block, or
-     * a partial wall that the NEXT send would actually hit.
-     *
-     * Partial exhaustion is announced only while the ACTIVE vendor (the registry
-     * default the next send resolves to) is among the walled ones. A user who has
-     * switched to a vendor with headroom has already acted on the advice —
-     * keeping the banner up past that point nagged about a vendor they just left
-     * (GENC-1464 tester feedback), while switching BACK to the walled vendor
-     * brings the banner straight back. Two conservative fallbacks keep it
-     * fail-informative: while the statuses are still loading the active vendor is
-     * unknowable, so any reachable-and-walled vendor still announces; and a
-     * vendor-agnostic block announces always, exactly as before.
-     *
-     * Reads the reachability-filtered list for the same reason the copy does — a
-     * host that has swapped its registry away from the walled vendor has nothing
-     * left to announce, and would otherwise get a banner that falls through to the
-     * generic default copy over a perfectly usable composer.
+     * a partial wall that the NEXT send would actually hit. See
+     * `BudgetController.bannerVisible` for why partial exhaustion is
+     * announced only while the active vendor is among the walled ones.
      *
      * @internal
      */
     get bannerVisible(): boolean;
     /**
-     * Whether a suggestions fetch would hit a wall.
-     *
-     * Unlike a chat turn, this one CAN be resolved exactly: both suggestion paths
-     * go to the registry **default** and never to a per-agent override
-     * (`ChatDriver.getSuggestions` calls `providerRegistry.default()`, and
-     * `OrchestratingDriver.getSuggestions` just delegates to it). So the vendor a
-     * suggestions call would use is knowable, and this is the one place in the
-     * feature where that is true.
-     *
-     * Same rationale as the guard it replaces: a doomed suggestions call burns a
-     * `suggestions.failed` meta event and parks a raw transport error in
-     * `suggestionsState` for hosts to find.
+     * Whether a suggestions fetch would hit a wall — the one place in this feature
+     * where the vendor a call would use is exactly knowable, because both
+     * suggestion paths go to the registry default. See
+     * `BudgetController.suggestionsBlocked`.
      *
      * @internal
      */
     get suggestionsBlocked(): boolean;
-    /**
-     * The vendor the NEXT send resolves to — the registry default's provider, as
-     * reported through `providerStatuses`. `undefined` while the statuses are
-     * still loading (or when the default reports the `'none'` sentinel), which
-     * every consumer treats conservatively.
-     *
-     * @internal
-     */
-    private get activeVendor();
     /**
      * Explanation shown in the blocked banner, or `null` for the element's default
      * copy. Only meaningful while {@link FoundationAiAssistant.blocked} is true;
@@ -3311,96 +3270,6 @@ export declare class FoundationAiAssistant extends GenesisElement {
      */
     get blockedReason(): string | null;
     set blockedReason(value: string | null);
-    /**
-     * Latch the backend block off a turn outcome. The single decision point for
-     * both latch sites (the `tool-loop-end` bus subscription and `send()`'s
-     * return-value check), so the rule cannot diverge between them.
-     *
-     * Idempotent and one-way **per vendor**: it never unblocks, and it never
-     * re-writes an existing wall. That guard is load-bearing, not just an
-     * optimisation — the bus fires from the driver's `finally`, i.e. BEFORE
-     * `sendMessage()` resolves, so a host subscribed to `tool-loop-end` (what the
-     * migration guide's Option C recommends) sets its own detailed reason and the
-     * return-value latch would otherwise land a moment later and blank it.
-     *
-     * The guard being per-vendor rather than global is the whole difference. A
-     * single global "already blocked, do nothing" would swallow a second vendor's
-     * wall — so a session walled on Anthropic could never record that Gemini went
-     * too, and under a mixed registry an Anthropic-only wall would lock a composer
-     * that Gemini could still serve.
-     *
-     * **Which field is authoritative**, in order:
-     *
-     * 1. `budget.vendorLabel` — stamped by the transport that was actually refused,
-     *    so it can never be stale. But it is a static per-transport string, so a
-     *    white-labelled or multiplexing gateway fronting several upstreams leaves
-     *    it unclaimed by any vendor.
-     * 2. `budget.vendor` — which the driver resolved from the label where it could,
-     *    and otherwise from the proxy's own `vendor` field on the 402. It is
-     *    therefore NOT simply `vendorLabel` normalised, and the two can disagree;
-     *    that fallback is the only attribution on offer for the gateway case above.
-     * 3. `vendorHint` — the bus detail's top-level vendor, i.e. the driver's
-     *    last-resolved provider. Last resort because it CAN be stale: an
-     *    orchestrated turn classifies against the registry default, a provider the
-     *    chat driver may never have resolved, so its last-resolved provider there is
-     *    the previous turn's vendor or nothing at all.
-     *
-     * A wall that names no recognised vendor falls back to the vendor-agnostic
-     * block — fail-safe, and identical to the pre-per-vendor behaviour.
-     *
-     * **`otherVendorAvailable: false` is server-known truth and outranks every
-     * inference made here.** The proxy meters the pots, so only it can say whether
-     * anything else has headroom; this element can only observe which vendors the
-     * registry can REACH, which says nothing about their remaining spend. So when
-     * the proxy says no, every other *budgeted* vendor is walled in the same pass.
-     * That is what makes `blocked` derive true — locking the composer on the first
-     * response instead of after a second doomed turn — and what empties the "free"
-     * set the banner would otherwise have advised switching to.
-     *
-     * The sweep runs over `BUDGETED_VENDORS`, deliberately **not** over
-     * {@link FoundationAiAssistant.reachableVendors}. Reachability is loaded
-     * asynchronously (`activateSession` kicks off `loadProviderStatuses()` and does
-     * not await it), so a wall landing before the statuses resolve would have swept
-     * an empty set — silently discarding the one fact on the 402 the client cannot
-     * re-derive, with nothing to re-run it when the statuses arrived. Worse, it let
-     * the verdict effectively un-latch: the single wall derived `blocked` only
-     * while the reachable set was empty, so the moment the statuses landed the
-     * composer came back to life against a budget the proxy had already said was
-     * gone. Sweeping the metered vendor list instead makes the verdict independent
-     * of load order and of registry membership, which is exactly what it is: a
-     * statement about the proxy's pots, not about this user's registry.
-     *
-     * Walling a vendor the registry cannot reach costs nothing: `blocked` only asks
-     * whether every REACHABLE vendor is walled, and the banner reads
-     * {@link FoundationAiAssistant.relevantBlockedVendors}, which filters the walls
-     * back down to the reachable set before naming any of them.
-     *
-     * One boundary remains on the sweep: it walls only vendors the proxy meters,
-     * enforced structurally by iterating `BUDGETED_VENDORS` itself rather than
-     * filtering a wider set through a predicate. Chrome runs on-device with no pot
-     * to exhaust, so "no other vendor has budget" is not a statement about it, and
-     * "Switch to Chrome to keep going." stays honest advice.
-     *
-     * The sweep runs last but sits OUTSIDE the per-vendor idempotence guard, and
-     * both halves of that matter. Last, so the vendor that actually refused this
-     * turn heads the wall order the multi-vendor banner reads. Outside the guard,
-     * because the verdict can arrive on a LATER 402 for a vendor that is already
-     * walled — turn 1 walls Anthropic while Gemini still has headroom, turn 2 walls
-     * it again and reports that Gemini has since gone too — and an early return
-     * would drop exactly the news the second turn was there to deliver.
-     *
-     * @param reason - the turn's failure reason; anything but `'budget-exhausted'` is ignored.
-     * @param ref - session store to write through; defaults to the live one. `send()`
-     *   passes the ref it captured before its awaits, since a lifecycle event during the
-     *   turn may already have cleared `_sessionRef`.
-     * @param budget - what the 402 reported: figures when the proxy sent any, the
-     *   refusing vendor, and its `otherVendorAvailable` verdict.
-     * @param vendorHint - the `tool-loop-end` detail's top-level vendor, used only
-     *   when the budget payload names none.
-     *
-     * @internal
-     */
-    private latchBlockedFrom;
     /**
      * Block or unblock the assistant, optionally with custom banner copy.
      * Equivalent to the {@link FoundationAiAssistant.blocked} setter, plus the
@@ -3416,66 +3285,18 @@ export declare class FoundationAiAssistant extends GenesisElement {
      */
     setBlocked(blocked: boolean, reason?: string | null): void;
     /**
-     * Copy shown in the blocked banner, in ascending specificity:
-     *
-     * 1. the host's `blockedReason` — a whole-banner override, unchanged;
-     * 2. copy composed from the walled vendors (their per-vendor reasons when set,
-     *    otherwise their names) plus the action that is actually available;
-     * 3. the default budget-exhaustion message.
-     *
-     * The action clause is computed here rather than stored, because whether
-     * "switch vendor" or "contact your administrator" is honest depends on whether
-     * another reachable vendor still has headroom — which changes when the registry
-     * changes, long after the wall was latched. Telling a user to switch to a
-     * vendor that is also exhausted is worse than saying nothing.
-     *
-     * The `free` set is a client-side inference — "reachable and not known to be
-     * walled" — and it is only ever allowed to be one. Where the proxy has told us
-     * otherwise (`otherVendorAvailable: false`) the latch has already walled those
-     * vendors, so they are not in `free` here and no "switch to X" clause can be
-     * composed from them. Both lists are filtered by reachability, so the copy
-     * names only vendors this user's registry can actually route to.
-     *
-     * **Per-vendor copy is composed however many vendors are walled**, which is
-     * what {@link FoundationAiAssistant.setVendorBlocked} and
-     * `docs/migration-GENC-1464.md` both promise. It previously reached only the
-     * single-vendor branch, so a host that had carefully set copy for each of its
-     * vendors watched all of it vanish the moment a second one walled — replaced by
-     * generic copy, at the exact moment the situation got worse.
-     *
-     * The compact list is the DEFAULT shape for several walls, now carrying each
-     * vendor's figures: "AI usage limits are reached for Gemini ($62.34 of $50.00)
-     * and Anthropic ($31.10 of $30.00)." A driver latch stores no copy of its own
-     * (it stores the figures, which this composes from), so that shape is what the
-     * real budget flow produces. As soon as any walled vendor carries HOST copy,
-     * which cannot be folded into a list item, the branch lists one statement per
-     * vendor instead — falling back to composed copy for the ones that have none, so
-     * the sentence set stays complete rather than silently naming a subset.
+     * Copy shown in the blocked banner — the host's override, else copy composed
+     * from the walled vendors, else the default. See
+     * `BudgetController.effectiveBlockedReason`, which explains why the
+     * action clause is composed on read rather than stored at latch time.
      *
      * @internal
      */
     get effectiveBlockedReason(): string;
     /**
      * Copy the driver writes into the TRANSCRIPT when a turn hits the budget wall,
-     * or `undefined` to let the driver compose it per wall.
-     *
-     * A set `blockedReason` still wins — a white-labelled host must not read its
-     * own explanation in the banner and shipped copy directly below it, and the
-     * vendor-agnostic latch's `formatBlockedReason(budget)` form stays advice-free
-     * exactly as before.
-     *
-     * `undefined` (the usual case) is NOT the old `DEFAULT_BUDGET_EXHAUSTED_MESSAGE`
-     * fallback: it hands composition to the driver, which builds the bubble from
-     * EACH wall's own 402 — naming the exhausted vendor and advising a switch only
-     * when that refusal's `otherVendorAvailable` positively vouched for headroom
-     * elsewhere. That is immune to the staleness this getter used to guard against
-     * by freezing the copy: construction-time advice could outlive its truth
-     * (`getOrCreateDriver` re-runs on an agents swap and would have baked the
-     * sentence into every later bubble), but per-wall advice is derived from the
-     * refusal it annotates and dies with the turn. Forcing the default here was
-     * also what made the driver's composed bubble unreachable in every real
-     * mount — the banner advised switching while the bubble under it never did
-     * (the GENC-1464 tester finding, root cause).
+     * or `undefined` to let the driver compose it per wall — see
+     * `BudgetController.transcriptMessage`.
      */
     private get transcriptBudgetExhaustedMessage();
     /**
@@ -3537,49 +3358,32 @@ export declare class FoundationAiAssistant extends GenesisElement {
      */
     get sessionCostUsd(): number;
     /**
-     * Distinct models the registry currently resolves to — the live session's model chips.
-     *
-     * `providerStatuses` carries one entry per registry SLOT, so a vendor configured across several
-     * tiers that happen to resolve to the same model reports it once per tier, and the chips
-     * rendered it once per tier too. Which tier a model came from is not what these chips are for.
+     * The cost ledger's derived surface (GENC-1475). Every member below delegates to
+     * `CostLedgerController` — the names are this element's public API and the
+     * settings modal's bindings, so they stay put while the accounting moves.
      *
-     * Deduped on the label actually displayed, not on `status.model`: a slot whose provider reports
-     * no model falls back to the slot's own name, and those are distinct per slot, so keying on the
-     * label keeps them from collapsing into one another.
+     * None carries `@volatile`: the decorators live on the controller's getters, and they
+     * reach the binding observer from there — see `docs/code-health.md` §11.4.
      */
     get uniqueProviderModels(): CostSessionModelEntry[];
-    /**
-     * Build history for display: most recently worked on first.
-     *
-     * The stored order is insertion order (see `upsertRecord`), which leaves a project returned to
-     * sitting wherever it was first seen — so ordering is applied here, on read, where it also
-     * covers rows a host provider supplied.
-     */
+    /** Build history for display: most recently worked on first. */
     get sortedCostSessionHistory(): CostSessionRecord[];
-    /**
-     * Lifetime usage across every project in the history scope — cost and all four token
-     * buckets. What the Usage tab's lifetime section renders.
-     *
-     * Rows ONLY — deliberately not rows + live session. Each row holds a project's lifetime
-     * usage and the active project's row is kept current on every transcript change, so
-     * adding the live total would count this project's spend twice. That double-count is what
-     * made the figure grow on every refresh: a page-hide banked a row while the restored
-     * session still carried the same spend.
-     */
+    /** Lifetime usage across every project in the history scope — rows only, never plus live. */
     get cumulativeUsage(): AggregateUsage;
     /** Lifetime USD across every project in the history scope. */
     get cumulativeCostUsd(): number;
-    /**
-     * Whether the live session figures amount to this project's whole history, which is true
-     * exactly when the transcript is restored on load. Drives the Usage tab's live labels
-     * ("Project cost" vs "Session cost") so they state the scope rather than imply one.
-     *
-     * Note this is NOT what makes the *rows* lifetime — those bank their pre-transcript spend
-     * (see `CostSessionRecord.banked`) and are lifetime either way.
-     */
+    /** Whether the live session figures amount to this project's whole history. */
     get liveUsageIsProjectLifetime(): boolean;
     /** Resolved cost tab and build-history settings from `chatConfig.costHistory`. */
     get resolvedCostHistory(): ResolvedCostHistoryConfig;
+    /**
+     * Persisted finalized cost sessions shown on the Usage tab build history list.
+     *
+     * A get/set pair rather than a read-only projection: the banking tests seed rows to
+     * model a page load that found some, and a host provider's rows arrive the same way.
+     */
+    get costSessionHistory(): CostSessionRecord[];
+    set costSessionHistory(value: CostSessionRecord[]);
     /**
      * Total tokens across every chat turn in this session — all four buckets added up.
      * Read-only; the per-bucket split is on `sessionUsage`.
@@ -3588,56 +3392,20 @@ export declare class FoundationAiAssistant extends GenesisElement {
     /** Label shown on the Usage tab for the in-flight session (app title or first user phrase). */
     get liveCostSessionTitle(): string | undefined;
     /**
-     * Write this session's usage into persisted build history (`localStorage`) as a single
-     * row keyed by the session key, replacing any existing row for that key.
-     *
-     * **Idempotent** — safe to call per turn, on tab close, and on a title change alike.
-     * The name is historical: it does NOT end the session or reset the running totals.
-     * Resetting them is what used to double-count spend, since the row was banked while the
-     * persisted transcript still carried the same usage, so a reload restored it and the
-     * Usage tab counted both.
+     * Write this session's usage into persisted build history as a single row keyed by the
+     * session key, replacing any existing row for that key.
      *
-     * No-op unless `chatConfig.costHistory.enabled` is `true`, when the live session has no
-     * usage yet, or when the session has no key to upsert against. Gating on the *live*
-     * figures (not the banked total) means a reload that restores nothing rewrites nothing.
+     * **Idempotent** — safe to call per turn, on tab close, and on a title change alike. The
+     * name is historical: it does NOT end the session or reset the running totals. See
+     * `CostLedgerController.finalize` for the full contract and the no-op cases.
      */
     finalizeCostSession(options?: {
         title?: string;
     }): void;
     /**
-     * Spend for `projectKey` that predates the current transcript, resolved once per SESSION and
-     * shared by every element instance wired to it (see `banked-usage-baselines`), so it cannot
-     * drift as the row it came from is rewritten by our own upserts.
-     *
-     * The two cases turn on whether the transcript is authoritative for this project:
-     *
-     * - **Transcript restored** (`persistenceActive`): it already accounts for everything after
-     *   the previous row's own banked figure, so carry that figure forward unchanged. Re-banking
-     *   `usage` here would add the restored history to itself on every reload.
-     * - **Transcript starts empty**: nothing on screen accounts for the previous total, so the
-     *   whole of it becomes banked. Without this the next turn would rewrite the row downwards
-     *   to just that turn, losing the project's earlier spend.
-     *
-     * The baseline is deliberately NOT element state. This element is remounted repeatedly inside
-     * a single session (the host re-rendering its layout, popping out, docking) and a fresh
-     * instance re-deriving would take the second branch against rows that already hold the live
-     * transcript — banking the session as its own baseline. Keying on the session instead means a
-     * remount inherits the baseline that transcript was paired with.
-     */
-    private bankedUsageFor;
-    /**
-     * Re-baseline this session against an emptied transcript: what came before, plus what the
-     * transcript being discarded proved. `discarded` must be read BEFORE the live figures are
-     * reset, since that is the only record of the latter.
-     *
-     * Not the same as dropping the baseline. Dropping it re-derives through `persistenceActive`,
-     * and with persistence ON that carries the row's *old* banked figure forward — discarding
-     * every turn between the last baseline and the clear. The transcript is gone either way, so
-     * the branch that reads it as authoritative no longer applies.
-     *
-     * Derived from the memoised baseline and the live figure rather than from the project's row,
-     * because a row is only as current as the last `finalizeCostSession` — which skips its write
-     * while the ledger is unloaded, and while the session has no usage yet.
+     * Re-baseline this session against an emptied transcript — see
+     * `CostLedgerController.rebaselineOnClearedTranscript`. `discarded` must be read
+     * BEFORE the live figures are reset, since that is the only record of the latter.
      */
     private rebaselineOnClearedTranscript;
     showConfirmationDialog(confirmationMessage: string, modalParent: HTMLElement, onConfirm: () => void, onCancel?: () => void): void;
@@ -3645,48 +3413,6 @@ export declare class FoundationAiAssistant extends GenesisElement {
     removeCostSessionFromHistory(id: string): void;
     /** Clear all persisted build history for this assistant scope. */
     clearCostSessionHistory(): void;
-    private getCostHistoryScope;
-    private reloadCostSessionHistory;
-    /**
-     * The persistence provider, but only when it implements BOTH cost-history methods.
-     *
-     * Both or neither: a provider that can save but not load would silently accumulate a
-     * ledger nobody ever reads back, so a partial implementation is treated as absent and
-     * falls back to `localStorage`.
-     */
-    private costHistoryProvider;
-    /**
-     * Adopt `records` as the live list, and schedule a write to whichever backend owns cost
-     * history — the provider when the host implements it, else `localStorage`.
-     *
-     * The list is adopted synchronously because that is what the Usage tab renders; only the
-     * *write* is deferred. This runs on every usage change (about once per LLM call, plus once
-     * per sub-agent turn) and each write serialises the whole ledger, so coalescing cuts a
-     * per-turn `localStorage.setItem` or network round-trip down to one per quiet period. Safe
-     * because the write is a full replace of idempotent state: the newest call wins and no
-     * intermediate state is meaningful. Flushed on `pagehide` and disconnect so nothing is lost.
-     */
-    private persistCostHistory;
-    /**
-     * Write the pending ledger now. Safe to call when nothing is pending.
-     *
-     * Provider writes are fire-and-forget and best-effort: the ledger is accounting, not
-     * conversation content, so a failed write is logged and never surfaced into the chat. On
-     * `pagehide` the `localStorage` path completes synchronously; a provider write is subject to
-     * the same unload race as every other network save the assistant makes.
-     */
-    private flushCostHistory;
-    /**
-     * Finalize the previous session when the host-provided title changes — a rename should land on
-     * the row under its old name rather than silently relabelling accrued spend.
-     *
-     * Only when the session key still matches the one that title accrued under. Hosts change
-     * `costHistory.title` on project SWITCH too, and if the key has already flipped, this would
-     * upsert the outgoing project's live usage onto the incoming project's row as
-     * `banked + old live`, inflating it. Under the old append model a mis-keyed write left a stray
-     * row; with the upsert it overwrites a real one.
-     */
-    private syncActiveCostSessionTitle;
     /** Active model id resolved from the AIProvider, if exposed. */
     get activeModel(): string | undefined;
     set activeModel(value: string | undefined);
@@ -3699,14 +3425,20 @@ export declare class FoundationAiAssistant extends GenesisElement {
     private _suggestionsGeneration;
     get inputValue(): string;
     set inputValue(value: string);
-    attachments: ChatAttachment[];
-    attachmentErrors: string[];
+    /** Attachments pending on the next message. */
+    get attachments(): ChatAttachment[];
+    set attachments(value: ChatAttachment[]);
+    /** Rejection messages for files the last pick refused. */
+    get attachmentErrors(): string[];
+    set attachmentErrors(value: string[]);
     /** Whether the loading spinner is currently visible. Controlled by the loading delay timer. */
     showLoadingIndicator: boolean;
     /** Bump to re-render app settings toggles when the host provider notifies a change. */
-    appSettingsRevision: number;
+    get appSettingsRevision(): number;
+    set appSettingsRevision(value: number);
     /** Whether the settings modal is open. */
-    settingsOpen: boolean;
+    get settingsOpen(): boolean;
+    set settingsOpen(value: boolean);
     /**
      * True while `downloadDebugLog` is building the log (GENC-1351 §5.8). Drives the
      * download button's disabled + spinner state — the lifetime-stitch path is async
@@ -3716,7 +3448,8 @@ export declare class FoundationAiAssistant extends GenesisElement {
      */
     downloadingDebugLog: boolean;
     /** Active tab inside the settings modal. */
-    settingsModalTab: SettingsModalTab;
+    get settingsModalTab(): SettingsModalTab;
+    set settingsModalTab(value: SettingsModalTab);
     /** Bound to the design-system modal via the template ref. */
     settingsModal?: Modal;
     /**
@@ -3795,16 +3528,33 @@ export declare class FoundationAiAssistant extends GenesisElement {
     persistenceModal?: Modal;
     /** Bound to the settings modal tab bar — used to resync selection after reopen. */
     settingsTabsEl?: SettingsModalTabsElement;
-    /** Light-DOM nodes assigned to settings modal slots (via `slotted()` bindings). */
-    settingsModelSlotted: HTMLElement[];
-    settingsAppSlotted: HTMLElement[];
-    settingsCostCurrentSlotted: HTMLElement[];
-    settingsCostHistorySlotted: HTMLElement[];
-    /** Persisted finalized cost sessions shown on the Usage tab build history list. */
-    costSessionHistory: CostSessionRecord[];
+    /**
+     * Light-DOM nodes assigned to settings modal slots. The template's `slotted()`
+     * bindings write these by property NAME, so each needs a real setter here even
+     * though the controller owns the arrays.
+     */
+    get settingsModelSlotted(): HTMLElement[];
+    set settingsModelSlotted(value: HTMLElement[]);
+    get settingsAppSlotted(): HTMLElement[];
+    set settingsAppSlotted(value: HTMLElement[]);
+    get settingsCostCurrentSlotted(): HTMLElement[];
+    set settingsCostCurrentSlotted(value: HTMLElement[]);
+    get settingsCostHistorySlotted(): HTMLElement[];
+    set settingsCostHistorySlotted(value: HTMLElement[]);
     /** Whether the splash overlay is currently showing (no messages and showSplash is enabled). Reflected as a boolean attribute on the host. */
     showingSplash: boolean;
     private driver?;
+    /**
+     * This element's driver as an orchestrator, or `undefined` when the session is
+     * running a bare `ChatDriver`.
+     *
+     * The five call sites that used to test the type themselves now read this
+     * (§11.2 constraint 3 of `docs/code-health.md`): the agent pin, the flow-owner
+     * lock, the wire-up in `wireDriver`, and the two `driverKind` diagnostics. The
+     * type test itself lives in `asOrchestrator`, shared with the session
+     * persister.
+     */
+    private get orchestrator();
     private driverCleanup?;
     private loadingTimer;
     private unsubBus?;
@@ -3812,29 +3562,6 @@ export declare class FoundationAiAssistant extends GenesisElement {
     private _unsubBudgetLatch?;
     /** Unsubscribe handle for the provider-registry change listener (observable registries only). */
     private unsubProviderRegistry?;
-    /** Unsubscribe handle for {@link (AssistantAppSettingsProvider:interface).subscribe}. */
-    private unsubAppSettingsProvider?;
-    /** Title tracked for the in-flight cost session (used when `header-title` changes). */
-    private _activeCostSessionTitle;
-    /**
-     * Session key `_activeCostSessionTitle` was captured under, so a title change can tell a rename
-     * (same key) from a project switch (key already flipped) — see `syncActiveCostSessionTitle`.
-     */
-    private _activeCostSessionKey?;
-    /**
-     * Whether the row list reflects storage yet. Gates cost writes so a project's banked
-     * spend is never derived from a ledger that simply hasn't arrived.
-     */
-    private _costHistoryLoaded;
-    /**
-     * Set when a provider read failed. Latches writes off for this page-load: `saveCostHistory`
-     * replaces the whole stored list, so writing anything derived from the empty list we fell back
-     * to would destroy rows we never managed to read.
-     */
-    private _ledgerUnreadable;
-    /** Pending (adopted but unwritten) ledger changes — see `persistCostHistory`. */
-    private _ledgerDirty;
-    private _ledgerFlushTimer?;
     private _handlePageHide;
     private haloStartPublished;
     /** Fingerprint of the agents array used to build the current driver. Used by agentsChanged to skip spurious rebuilds. */
@@ -3844,20 +3571,15 @@ export declare class FoundationAiAssistant extends GenesisElement {
     /** Bound to the rapid-text-area chat input via the template ref. */
     chatInputEl?: HTMLElement;
     /**
-     * Explicit composer height (px) once the user has dragged the resize handle;
-     * `null` keeps the default auto-grow behaviour. Written into the
-     * `--composer-height` custom property via the `composerHeightStyle` getter.
-     */
-    composerHeightPx: number | null;
-    /** Pointer Y and composer height captured at the start of a resize drag. */
-    private _resizeStartY;
-    private _resizeStartHeight;
-    /** The composer's natural (un-resized) height, measured on first drag — used
-     * as the lower bound so the box can't be dragged smaller than it started. */
-    private _composerNaturalHeight;
-    /** Upper bound for the current drag — capped to the headroom above so growing
-     * the composer never pushes the input row's buttons off the bottom. */
-    private _resizeMaxHeight;
+     * A get/set pair over one of this element's own properties, for a controller
+     * that drives state it does not own. Written as a helper rather than two inline
+     * closures per call: a pair of same-typed closures is easy to transpose by
+     * accident, and a single object cannot be.
+     */
+    private accessor;
+    /** Explicit composer height once dragged; `null` keeps the default auto-grow. */
+    get composerHeightPx(): number | null;
+    set composerHeightPx(value: number | null);
     /**
      * True when the user's last interaction (pointer or keyboard focus) was inside
      * the assistant. Defaults to true so the assistant claims focus on first mount.
@@ -4048,18 +3770,6 @@ export declare class FoundationAiAssistant extends GenesisElement {
      * window is known.
      */
     private syncContextGuard;
-    /**
-     * Guard policy pushed to the driver, or `undefined` when the host has switched
-     * the gate off — so `enabled: false` really does mean no local blocking of any
-     * kind, UI or mid-loop.
-     *
-     * A MARGIN, not a threshold: the driver resolves the window of the provider
-     * each call actually goes to. The fallback window rides along because the
-     * driver cannot learn it any other way — without it, a host that knows its
-     * window while its provider does not report one had `fallbackContextLimit`
-     * protecting the composer and nothing else.
-     */
-    private get contextGuardPolicy();
     private loadProviderStatuses;
     chatConfigChanged(): void;
     /**
@@ -4141,46 +3851,10 @@ export declare class FoundationAiAssistant extends GenesisElement {
      * `contains()` check cannot tell "clicked the menu" from "clicked the
      * transcript". The path crosses the boundary and carries both.
      */
-    private _dismissPointerHandler?;
-    private _dismissKeyHandler?;
-    private _dismissResizeHandler?;
-    private closeOpenComposerMenus;
-    /**
-     * Places an open composer menu directly above the control that opened it.
-     *
-     * CSS alone cannot: the menu is a child of `.composer` — which is what lets its
-     * width be capped against the composer rather than against a button — while its
-     * anchor is a button several levels down the bar, and no selector can read a
-     * sibling's offset. So the left edge is measured on open and written as a
-     * custom property.
-     *
-     * Clamped to the composer, so a menu opened from a control near the right edge
-     * of a narrow panel slides back inside instead of overhanging. The animation
-     * origin is written separately and keeps pointing at the button's centre even
-     * after such a shift — the menu still grows out of the thing that opened it,
-     * which is the whole point of anchoring it there.
-     */
-    private positionComposerMenu;
-    /** Re-place whichever menu is open. Cheap enough to run from a resize. */
-    private repositionOpenComposerMenu;
-    private syncComposerMenuDismissal;
-    private teardownComposerMenuDismissal;
-    /**
-     * Vertical space an open menu must leave free above the button, covering BOTH
-     * the gap the menu sits off the button by (8px, declared in design units in
-     * main.styles.ts) and the breathing room wanted above it. The two are lumped
-     * together because only the second half is a free choice: the first is fixed by
-     * the stylesheet and simply has to be subtracted from the headroom, and a
-     * constant named for only one of them invites someone to "fix" a gap that is
-     * doing exactly what it should.
-     */
-    private static readonly MENU_HEADROOM_RESERVE;
-    private readonly _agentPickerToggle;
     toggleAgentPicker(): void;
     /** Two-step confirm for the destructive Clear action; reset whenever the menu toggles. */
     confirmingClear: boolean;
     confirmingCompact: boolean;
-    private readonly _sessionMenuToggle;
     /**
      * Whether the lifecycle-menu button shows. It occupies the stop-button slot,
      * so it only appears when idle (mutually exclusive with Stop). Gated on
@@ -4218,20 +3892,18 @@ export declare class FoundationAiAssistant extends GenesisElement {
     /** Whether persistence is currently active (on + a provider) for this session. */
     get persistenceActive(): boolean;
     /**
-     * Context-headroom thresholds for the active model (GENC-1567) — the warning
-     * and block lines, plus the tail budget compaction aims at.
+     * The context gate's derived surface (GENC-1567). Every member below delegates to
+     * `ContextGateController` — the names are this element's public API and the
+     * template's bindings, so they stay put while the derivation moves.
      *
      * The per-agent `contextReserve` IS folded in, via the driver (GENC-1582). It
      * used to be described here as a separate, later check made when an agent took
      * ownership of a flow — but there is no such check, and by flow entry the send
-     * has already been allowed. Resolving it here, before the send, is what makes it
-     * a gate rather than a label.
+     * has already been allowed. Resolving it before the send is what makes it a gate
+     * rather than a label.
      *
-     * Overhead is read off `messages` (the Redux mirror) rather than the driver's
-     * own history, which the compaction plan uses. That is safe rather than sloppy:
-     * `estimateSystemOverhead` only looks at messages BEFORE the first usage-bearing
-     * one, and the two lists agree completely that early — the drift between mirror
-     * and driver history is only ever at the tail.
+     * None carries `@volatile`: the decorators live on the controller's getters, and
+     * they reach the binding observer from there — see `docs/code-health.md` §11.4.
      */
     get contextBudget(): ResolvedContextBudget;
     /**
@@ -4252,150 +3924,31 @@ export declare class FoundationAiAssistant extends GenesisElement {
      * `contextReserve` is a plain number by design — see `ContextReserveInput` for
      * why a resolver form was dropped rather than accepted and ignored.
      *
+     * Stays on the element rather than moving into `ContextGateController` because it
+     * reaches the driver, which no extracted controller may do (`docs/code-health.md`
+     * §11.2 constraint 2). The controller receives the resolved value as a callback.
+     *
      * @internal
      */
     private get contextReserve();
-    /**
-     * What compacting right now would reclaim, or `null` when it would not be
-     * worth it (GENC-1567). Sized against {@link FoundationAiAssistant.contextBudget},
-     * so the plan aims at this model's window rather than a fixed default.
-     *
-     * Reads `messages` to stay reactive as the conversation grows: the driver's
-     * history is not a tracked observable, so every consumer of this keys its
-     * re-evaluation off the Redux mirror.
-     */
     get compactionPlan(): CompactionProjection | null;
-    /**
-     * Tooltip and hint for the Compact row — why it is or is not available.
-     *
-     * Replaces a fixed "Not enough conversation yet to be worth compacting", which
-     * since GENC-1567 could be flatly wrong: a long conversation whose tail is one
-     * indivisible tool result has plenty of conversation and still cannot be
-     * compacted. Reading the plan means the hint states the actual reason.
-     *
-     * @internal
-     */
-    get compactHint(): string;
-    /**
-     * How close this conversation is to the model's context window (GENC-1567).
-     *
-     * **Derived, never latched** — the opposite of {@link FoundationAiAssistant.blocked}.
-     * A budget wall stays set because nothing the user does fixes it; this clears
-     * itself the moment the conversation shrinks, which is precisely what the user
-     * is being asked to do. The two must not be conflated: `blocked` is also
-     * deliberately preserved across `resetSession`, and a context gate obviously
-     * must not survive starting a new chat.
-     *
-     * **A flow in progress is never blocked, only warned.** Machine state lives
-     * outside the transcript, so a stateful flow is not desynced by compaction —
-     * but the summary can still drop detail the flow's own prompt leans on, and
-     * blocking mid-journey would strand the user between a flow they cannot finish
-     * and a compaction that is a poor idea right there. Letting the flow complete
-     * and gating on the way out is the lesser harm; the headroom reserve exists so
-     * this is rare rather than routine.
-     */
     /**
      * WHY the composer is blocked, when it is (GENC-1582). `undefined` unless
-     * {@link FoundationAiAssistant.contextGate} is `'blocked'`.
-     *
-     * A cause rather than a fourth gate level: the severity is identical — sends are
-     * refused either way — and every consumer switches on the three levels. What
-     * differs is what the user can do about it, which is worth splitting because the
-     * two answers have no remedy in common.
-     *
-     * - `'transcript'` — the conversation has grown into the reserve. Compacting or
-     *   clearing helps, and the copy says so.
-     * - `'model'` — the active agent's reserve meets or exceeds the whole window, so
-     *   `blockAt` is 0 and EVERY message is refused, including the first of an empty
-     *   chat. Neither compacting nor clearing can help: the constraint is the model,
-     *   not the transcript. Before this existed the user was told to clear the chat,
-     *   did, and hit the identical block with no way to understand why.
-     *
-     * Keyed off `blockAt === 0`, deliberately NOT off whether a compaction plan
-     * exists. A null plan has two unrelated causes — nothing left worth summarizing,
-     * versus a window that cannot host the agent at all — and conflating them is what
-     * produced the misleading copy.
-     *
-     * Note the block itself is correct in both cases and must stay: an agent that
-     * measurably cannot complete a turn in this window would otherwise start one and
-     * die mid-loop on a provider context error, with partial writes and no clean
-     * exit. Refusing up front is the better failure.
+     * {@link FoundationAiAssistant.contextGate} is `'blocked'`. See
+     * `ContextGateController.blockCause` for the `'transcript'` / `'model'` split
+     * and why it is a cause rather than a fourth gate level.
      *
      * @internal
      */
     get contextBlockCause(): 'transcript' | 'model' | undefined;
     get contextGate(): 'ok' | 'warn' | 'blocked';
-    /**
-     * What the composer notice says about the context gate.
-     *
-     * The copy is a function of whether compaction can actually clear the gate,
-     * which is why it reads {@link FoundationAiAssistant.compactionPlan} rather
-     * than assuming. Telling someone to compact when the projection says it would
-     * not free enough — a tail that is one indivisible tool result, say — sends
-     * them into a summarizer call that leaves them exactly where they were.
-     *
-     * @internal
-     */
     get contextGateReason(): string;
-    /**
-     * Short label the session-menu pill wears while the gate is active — the
-     * primary visible signal, in place of a banner.
-     *
-     * Borrowed from the agent pin, which is the established way this composer says
-     * "a mode is in force": a pill that grows a label rather than a strip of prose
-     * above the input. It states the CONDITION only; the remedy lives in the
-     * placeholder once the composer is actually blocked, which is the moment the
-     * user needs to be told what to do rather than merely warned.
-     *
-     * @internal
-     */
     get contextGateLabel(): string;
-    /**
-     * Whether the composer notice has anything to show — a budget wall or the
-     * context gate. One region for both, so the live region stays single and
-     * registered (see the banner template's accessibility note).
-     *
-     * @internal
-     */
+    get compactHint(): string;
+    get compactable(): boolean;
     get composerNoticeVisible(): boolean;
-    /**
-     * Text for that region. A budget wall outranks the context gate: it is the
-     * condition the user cannot clear, so it must not be hidden behind advice
-     * about compacting that would not restore sending anyway.
-     *
-     * For the context gate the region is present and announced but not drawn — see
-     * {@link FoundationAiAssistant.composerNoticeSrOnly}.
-     *
-     * @internal
-     */
     get composerNoticeText(): string;
-    /**
-     * Whether the notice region should be announced but not drawn.
-     *
-     * The context gate shows itself visually through the pill's label, the
-     * composer outline and the placeholder — a strip of prose on top of those
-     * would be a fourth statement of the same thing. But dropping the region
-     * outright would be an accessibility regression, and a documented one: a
-     * `role="status"` region announces MUTATIONS to a region already being
-     * observed, and it is the only announcement available here, because the
-     * composer flips to `disabled` at the same moment and a disabled control is out
-     * of the tab order — so neither the placeholder nor an `aria-label` on it is
-     * ever voiced.
-     *
-     * So the region stays mounted, keeps its text and keeps announcing; only the
-     * visual treatment is withheld. A budget wall still draws its banner, because
-     * that condition has no other visible expression.
-     *
-     * @internal
-     */
     get composerNoticeSrOnly(): boolean;
-    /**
-     * Whether the menu's "Compact" action would do anything (GENC-1351 §5.7,
-     * GENC-1567). Delegates to the driver's plan so the gate uses the exact same
-     * history `compact()` acts on, judged against the same budget — one source of
-     * truth for both whether a cut is legal and whether it reclaims enough.
-     */
-    get compactable(): boolean;
     toggleSessionMenu(): void;
     /**
      * Set persistence on/off for this session (the menu switch). Reassigns the
@@ -4480,33 +4033,40 @@ export declare class FoundationAiAssistant extends GenesisElement {
     }): boolean;
     /** Whether the picker toggle button should appear. Mirrors the picker's own visibility rule. */
     get agentPickerEnabled(): boolean;
-    /** Whether the settings modal AI Model section has slotted app content, context usage or budget figures. */
+    /**
+     * The settings modal's derived surface. Every member below delegates to
+     * `SettingsModalController` — the names are this element's public API and the
+     * 943-line template's bindings, so they stay put while the logic moves into the
+     * `settings-modal.ts` that folder never had (`docs/code-health.md` §3).
+     *
+     * None carries `@volatile`: the decorators live on the controller's getters, and
+     * they reach the binding observer from there — see `docs/code-health.md` §11.4.
+     */
     get settingsModelSectionVisible(): boolean;
     /** Built-in context window indicator (generic platform concern). */
     get settingsContextUsageVisible(): boolean;
+    /**
+     * The context indicator's figures, pre-formatted, or `undefined` when there is
+     * nothing measurable to show — see {@link SettingsContextUsage}.
+     *
+     * @internal
+     */
+    get settingsContextUsage(): SettingsContextUsage | undefined;
     /**
      * Built-in per-vendor budget meter (GENC-1464) — the money sibling of
      * {@link FoundationAiAssistant.settingsContextUsageVisible}, with the same
-     * shape of gate: not configured off, and there is data to show. "Data" here
-     * is "at least one vendor has figures", so a host that feeds nothing (or only
-     * unlimited vendors) gets no meter and no empty container — exactly the
-     * context indicator's absent case.
-     *
-     * Answered from the RAW slice state rather than from
-     * {@link FoundationAiAssistant.settingsBudgetRows}, whose `.length` would
-     * format every row (a `formatUsd` pair and a `budgetPercentOf` each) only to
-     * ask whether any exist. This is read several times per render pass — the
-     * getter, the section gate, the template's `when` — so it stays as cheap as
-     * the context sibling's `!= null`.
+     * shape of gate: not configured off, and there is data to show. See
+     * `BudgetController.settingsUsageVisible` for why it reads the raw slice
+     * rather than counting the rows.
      *
      * @internal
      */
     get settingsBudgetUsageVisible(): boolean;
     /**
      * The meter's rows — one per vendor that currently has figures, in
-     * `BUDGETED_VENDORS` order (the proxy's own metered list) so the rendering is
-     * stable however the host ordered its feed calls. Pre-formatted; see
-     * {@link SettingsBudgetRow} for why the text is unclamped while the bar is.
+     * `BUDGETED_VENDORS` order so the rendering is stable however the host ordered
+     * its feed calls. Pre-formatted; see {@link SettingsBudgetRow} for why the text
+     * is unclamped while the bar is.
      *
      * @internal
      */
@@ -4523,38 +4083,25 @@ export declare class FoundationAiAssistant extends GenesisElement {
     get appSettingsTogglesHeading(): AssistantAppSettingsHeading | undefined;
     getAppSettingValue(id: string): boolean;
     setAppSettingValue(id: string, value: boolean): void;
-    private wireAppSettingsProvider;
-    private unwireAppSettingsProvider;
     get settingsCostCurrentSectionVisible(): boolean;
     /**
      * Whether the build-history section has anything in it — the built-in row list, or a host's own
-     * markup in the `settings-cost-history` slot.
-     *
-     * Slotted content is checked FIRST, ahead of `enabled`. That flag governs the *built-in* ledger:
-     * it gates the row writes, the reload, and the lifetime sum — and it defaults to `false`
-     * (`cost?.enabled === true`), while the Usage tab itself shows for `showCost`/`showTokens`, which
-     * default true. So a host can legitimately render its own build history into the slot and never
-     * opt into our `localStorage` ledger. Short-circuiting on `enabled` above the slot check hid that
-     * host's markup outright, since the slot is the only thing in the container.
+     * markup in the `settings-cost-history` slot. See
+     * `SettingsModalController.costHistorySectionVisible` for why slotted content is
+     * checked ahead of `enabled`.
      */
     get settingsCostHistorySectionVisible(): boolean;
     /**
-     * Whether the "Build history" heading has anything under it.
-     *
-     * Broader than {@link FoundationAiAssistant.settingsCostHistorySectionVisible} because the
-     * heading also covers the lifetime total, which renders before the first row exists (rows are
-     * written as spend accrues, the lifetime section only needs history switched on). Gating the
-     * heading on the rows alone left that total sitting under nothing.
+     * Whether the "Build history" heading has anything under it — broader than
+     * {@link FoundationAiAssistant.settingsCostHistorySectionVisible}, because the
+     * heading also covers the lifetime total, which renders before the first row exists.
      */
     get settingsCostHistoryHeadingVisible(): boolean;
     /** Whether the built-in Usage tab summary block has anything to show. */
     get settingsCostSummaryVisible(): boolean;
     /**
-     * Whether the lifetime-usage section has anything to say.
-     *
-     * Requires build history: with it off there are no rows, so `cumulativeUsage` falls back to
-     * the live session and the section would restate the block directly below it under a
-     * "lifetime" heading it hasn't earned.
+     * Whether the lifetime-usage section has anything to say. Requires build history
+     * AND a resolvable state key — see `SettingsModalController.costLifetimeVisible`.
      */
     get settingsCostLifetimeVisible(): boolean;
     /** Whether the Usage tab should appear in the settings modal. */
@@ -4569,15 +4116,6 @@ export declare class FoundationAiAssistant extends GenesisElement {
     setSettingsModalTab(tab: SettingsModalTab): void;
     /** Sync the active settings modal tab when the design-system tab bar changes. */
     onSettingsModalTabsChange(event: Event): void;
-    /** Ensure the settings tab is selected when the modal opens. */
-    private resetSettingsModalTabsOnOpen;
-    /** Return to the settings tab when the modal closes on Cost. */
-    private resetSettingsModalTabsOnClose;
-    /**
-     * Snap the tab underline to the settings tab without animating from Cost.
-     * Used after hide/show when aria state is correct but the indicator drifted.
-     */
-    private snapSettingsModalTabIndicator;
     /** Hint text for the currently pinned agent, if any. Used in the toggle button tooltip. */
     get pinnedAgentHint(): string | undefined;
     /**
@@ -4630,14 +4168,13 @@ export declare class FoundationAiAssistant extends GenesisElement {
      */
     private buildDiagnosticEntries;
     /**
-     * The single `meta-snapshot` entry for right now — the export-time `meta` block
-     * (agent summary, active prompt/state, context + cost) plus the `dedupSignature`
-     * the forward-capture delta keys on.
+     * The `meta-snapshot` entry for right now. The assembly is a pure transformation
+     * in `buildMetaSnapshot`; this gathers what it reports.
      *
-     * Separate from `buildDiagnosticEntries` because the download path needs a
-     * FRESH one on its own: the persisted stream only re-appends this block when the
-     * near-static config changes, so the newest stored snapshot's volatile half — the
-     * `context` figures especially — is typically frozen at the session's first flush.
+     * The live agent comes from the DRIVER, not `this.activeAgent` (the redux-stripped
+     * projection, no functions) and not a lookup in `this.agents` (which may mint
+     * fresh, never-activated configs) — only the driver holds the instance whose
+     * `onActivate` ran, so only its `getDebugSnapshot` closure holds state.
      */
     private buildMetaSnapshot;
     downloadDebugLog(): Promise<void>;
@@ -4743,13 +4280,6 @@ export declare class FoundationAiAssistant extends GenesisElement {
     handleFileSelect(e: Event): void;
     removeAttachment(attachment: ChatAttachment): void;
     removeAttachmentError(message: string): void;
-    private isAcceptedFile;
-    private readFileAsText;
-    /** The base64 payload of a file, without any `data:` prefix — the raw form
-     *  `ChatImageAttachment.data` specifies (transports add their own framing). */
-    private readFileAsBase64;
-    private processFiles;
-    private loadSelectedFiles;
     handleSendClick(): void;
     /**
      * User clicked Stop. Cancels the current turn via the driver and flips the
@@ -4826,23 +4356,12 @@ export declare class FoundationAiAssistant extends GenesisElement {
      * mid-turn.
      */
     get sendButtonVisible(): boolean;
-    /** Whether the message input shows a drag handle to resize its height.
-     * On by default; hosts opt out via `chatConfig.ui.resizableInput: false`. */
+    /** Whether the message input shows a drag handle to resize its height. */
     get isComposerResizable(): boolean;
-    /** Inline style for the chat input: writes the chosen height into the
-     * `--composer-height` custom property (read by `.chat-input` + its control in
-     * `main.styles.ts`). Empty until the user drags (or when resizing is disabled),
-     * so the default applies. */
+    /** Inline style carrying the dragged height into `--composer-height`. */
     get composerHeightStyle(): string;
-    /** Begin a composer resize drag. Captures the pointer so move/up keep firing
-     * on the handle even when the cursor leaves its 7px band. */
     onComposerResizeStart(e: PointerEvent): void;
-    /** Resize while dragging. Dragging up (clientY decreases) grows the composer;
-     * the result is clamped between the natural height (lower) and the available
-     * headroom/max (upper). No-op unless a drag is active (the handle holds pointer
-     * capture), so plain hover-moves are ignored. */
     onComposerResizeMove(e: PointerEvent): void;
-    /** End a resize drag and release the pointer capture. */
     onComposerResizeEnd(e: PointerEvent): void;
 }
 
@@ -5704,6 +5223,32 @@ export declare interface SettingsBudgetRow {
     barValue: number;
 }
 
+/**
+ * The settings-modal context-window indicator, pre-formatted — the context
+ * sibling of {@link SettingsBudgetRow}, and pre-formatted for the same reason:
+ * the template stays a pure binding layer, and a test can pin the exact text.
+ *
+ * `undefined` when there is nothing measurable to show, which is what keeps the
+ * template free of non-null assertions. It used to read
+ * `x.contextTokens!.toLocaleString()`, and the assertion was not merely untidy:
+ * those bindings sit inside a `when(...)` block and re-evaluate in the SAME
+ * notify batch as the guard that unmounts them, so a session Clear with the
+ * modal open on the Usage tab threw two `TypeError`s per render. A shape that
+ * can be absent cannot have that bug.
+ *
+ * @beta
+ */
+export declare interface SettingsContextUsage {
+    /** Prompt tokens on the last call, e.g. `12,480`. */
+    used: string;
+    /** The model's context window, e.g. `200,000`. */
+    limit: string;
+    /** Whole-number percent consumed. Unclamped, like the budget row's text. */
+    percent: number;
+    /** The bar's value, clamped to `0..100` — only the bar clamps. */
+    barValue: number;
+}
+
 /**
  * Tab identifiers for the modal tab bar.
  *