@genesislcap/ai-assistant 15.23.3 → 15.24.0

package/dist/dts/main/main.d.ts

@@ -1,23 +1,18 @@
-import type { AggregateUsage, AIProviderRegistryStatusEntry, AIProviderType, ChatAttachment, ChatConfig, ChatDriverResult, ChatInputDuringExecutionMode, ChatMessage } from '@genesislcap/foundation-ai';
+import type { AggregateUsage, AIProviderRegistryStatusEntry, AIProviderType, ChatAttachment, ChatConfig, ChatInputDuringExecutionMode, ChatMessage } from '@genesislcap/foundation-ai';
 import { AIProviderRegistry } from '@genesislcap/foundation-ai';
 import type { Modal } from '@genesislcap/rapid-design-system';
 import { GenesisElement } from '@genesislcap/web-core';
-import type { SettingsModalTab } from '../components/settings-modal';
+import { type SettingsModalTab, type SettingsModalTabsElement } from '../components/settings-modal';
 import type { AgentConfig } from '../config/config';
 import { AssistantAppSettingsProvider, type AssistantAppSettingsHeading, type AssistantAppSettingsToggle } from '../provider/assistant-app-settings';
-import type { VendorBudgetFigures } from '../state/ai-assistant-slice';
 import type { DebugLog } from '../state/persistence/diagnostics';
 import type { SessionPersistenceConfig } from '../state/persistence/session-persistence-provider';
 import type { InteractionContext } from '../types/interaction-context';
 import { type CompactionProjection } from '../utils/context-tokens';
-import { type CostSessionModelEntry, type CostSessionRecord } from '../utils/cost-session-history';
-import { type ResolvedContextBudget } from '../utils/resolve-context-budget';
-import { type ResolvedCostHistoryConfig } from '../utils/resolve-cost-history-config';
-import type { AgentPickerMode, AiAssistantAnimation, AiAssistantState, PopoutMode, SettingsBudgetRow, SubmitMessageResult, SuggestionsState } from './main.types';
-/** Design-system tabs element bound to the settings modal tab bar. */
-type SettingsModalTabsElement = HTMLElement & {
-    activeid?: string;
-};
+import type { CostSessionModelEntry, CostSessionRecord } from '../utils/cost-session-history';
+import type { ResolvedContextBudget } from '../utils/resolve-context-budget';
+import type { ResolvedCostHistoryConfig } from '../utils/resolve-cost-history-config';
+import type { AgentPickerMode, AiAssistantAnimation, AiAssistantState, PopoutMode, SettingsBudgetRow, SettingsContextUsage, SubmitMessageResult, SuggestionsState } from './main.types';
 /** Context window sizes (in tokens) for known models. */
 /** Three-star AI "sparkle" mark — the conventional AI signifier; default assistant avatar. */
 export declare const sparkleIconSvg = "<svg viewBox=\"0 0 24 24\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\"><path d=\"M9.5 5 C9.5 11.4 11.1 13 17.5 13 C11.1 13 9.5 14.6 9.5 21 C9.5 14.6 7.9 13 1.5 13 C7.9 13 9.5 11.4 9.5 5 Z\" fill=\"currentColor\"/><path d=\"M17 2.5 C17 5.7 17.8 6.5 21 6.5 C17.8 6.5 17 7.3 17 10.5 C17 7.3 16.2 6.5 13 6.5 C16.2 6.5 17 5.7 17 2.5 Z\" fill=\"currentColor\"/><path d=\"M17.5 15 C17.5 17 18 17.5 20 17.5 C18 17.5 17.5 18 17.5 20 C17.5 18 17 17.5 15 17.5 C17 17.5 17.5 17 17.5 15 Z\" fill=\"currentColor\"/></svg>";
@@ -26,36 +21,13 @@ export declare const userIconSvg = "<svg viewBox=\"0 0 24 24\" fill=\"none\" xml
 /** Genesis G-mark — opt-in assistant avatar (the default before the sparkle mark). */
 export declare const genesisIconSvg = "<svg viewBox=\"-4 0 30 26\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\"><path d=\"M18.7702 23.0437C18.7702 22.4675 18.8526 21.8089 19.0995 21.3149C19.3465 20.7386 19.6758 20.2447 20.0874 19.833C20.4991 19.4214 20.993 19.0921 21.5693 18.8451C22.1456 18.5982 22.7219 18.5158 23.2981 18.5158H25.9326V11.6828H19.1819V14.3172C19.1819 15.5521 18.6879 16.7047 17.8647 17.5279C17.0414 18.3512 15.8888 18.8451 14.7363 18.9275H6.7507V6.99025H16.4651V0.157227H3.54C2.63442 0.157227 1.72884 0.568855 1.07023 1.22746C0.411628 1.88606 0 2.79165 0 3.77955V22.2205C0 23.1261 0.411628 24.0316 1.07023 24.7726C1.72884 25.4312 2.63442 25.8428 3.54 25.8428H18.7702V23.0437Z\" fill=\"currentColor\"/></svg>";
 /**
- * Banner copy built from the figures a 402 actually reported, or `undefined`
- * when the proxy sent none.
- *
- * `undefined` is the meaningful return, not a fallback: paired with the
- * slice's "a re-latch without a reason keeps the existing explanation" rule, it
- * makes a figureless driver latch leave a host-supplied reason intact rather
- * than blanking it back to the default at the exact moment the wall is hit.
- *
- * Exported for the unit test that pins the formatting; not part of the element
- * API.
- *
- * @internal
+ * Budget formatting helpers, re-exported so they stay on this module's public
+ * surface (`src/index.ts` does `export * from './main/main'`). They live in
+ * `budget-controller.ts` with the code that composes them; moving them without
+ * this line would have quietly dropped two `@internal` exports from the package
+ * entry point, and broken the two test files that import them from here.
  */
-export declare function formatBlockedReason(budget?: Partial<Extract<ChatDriverResult, {
-    reason: 'done';
-}>['budget']>, vendor?: AIProviderType): string | undefined;
-/**
- * Whole-number percentage of a budget consumed, for the meter (GENC-1464).
- *
- * Deliberately unclamped — spend can genuinely overshoot the cap (the last
- * allowed call may cross it), and the meter's TEXT shows the truth; only the
- * bar clamps, at the render site. The one special case is a `$0` cap, which the
- * platform treats as "no spend allowed" (not "unlimited"): it has no headroom
- * by definition, so the meter reads full rather than dividing by zero.
- *
- * Exported for the unit test that pins the arithmetic; not element API.
- *
- * @internal
- */
-export declare function budgetPercentOf(figures: VendorBudgetFigures): number;
+export { budgetPercentOf, formatBlockedReason } from './budget-controller';
 /**
  * Foundation AI Assistant component.
  *
@@ -83,6 +55,35 @@ export declare function budgetPercentOf(figures: VendorBudgetFigures): number;
  * @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;
@@ -372,22 +373,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
      */
@@ -398,13 +387,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.
@@ -430,30 +417,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
@@ -516,8 +493,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
@@ -525,7 +503,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;
     /**
@@ -540,83 +519,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;
@@ -633,96 +553,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
@@ -738,66 +568,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();
     /**
@@ -859,49 +641,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`.
@@ -910,56 +675,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;
@@ -967,48 +696,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);
@@ -1021,14 +708,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
@@ -1038,7 +731,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;
     /**
@@ -1117,16 +811,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?;
@@ -1134,29 +845,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. */
@@ -1166,20 +854,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.
@@ -1370,18 +1053,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;
     /**
@@ -1463,46 +1134,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
@@ -1540,20 +1175,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;
     /**
@@ -1574,150 +1207,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
@@ -1802,33 +1316,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
      */
@@ -1845,38 +1366,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. */
@@ -1891,15 +1399,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;
     /**
@@ -1952,14 +1451,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>;
@@ -2065,13 +1563,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
@@ -2148,24 +1639,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;
 }
-export {};
 //# sourceMappingURL=main.d.ts.map