@aragon-agent/cli 0.5.6 → 0.5.9

package/dist/ui/overlays/SettingsScreen.d.ts

@@ -9,6 +9,7 @@
  */
 import React from 'react';
 import { type ThinkingLevel } from '@aragon-agent/core';
+import { type FastConfig } from '../../config/schema.js';
 import { type LogLevelName } from '../../logging/levels.js';
 import type { Theme } from '../theme.js';
 import type { TermCapabilities } from '../capabilities.js';
@@ -17,6 +18,22 @@ export interface SettingsValues {
     model: string;
     baseUrl: string;
     thinkingLevel: ThinkingLevel;
+    /**
+     * Whether the transcript draws the reasoning (agent-activity-presentation
+     * §4.3). `'on' | 'off'` rather than a boolean because this screen edits an
+     * enum row and reads it back as one; `App` converts at both ends.
+     */
+    showThinking: 'on' | 'off';
+    /**
+     * Whether a running tool card draws a live output tail
+     * (agent-activity-presentation-live §4.1). `'on' | 'off'` for the reason its
+     * neighbour records: this screen edits an enum row and reads it back as one.
+     *
+     * PERSIST-ONLY, unlike `showThinking`. The store is allocated in
+     * `AgentController`'s constructor and there is no setter, so this row takes
+     * effect on the next launch -- which is also what manual row 8 asks for.
+     */
+    liveToolOutput: 'on' | 'off';
     maxTokens: string;
     apiKey: string;
     /**
@@ -25,6 +42,21 @@ export interface SettingsValues {
      * credentials on disk cannot be flipped by a stray arrow key.
      */
     logLevel: LogLevelName;
+    /**
+     * The fast tier (fast-model-tier §4.5, extended by the hardening round §4.4).
+     *
+     * FIVE ROWS, and only the first is always meaningful — the other four
+     * describe a tier that may not be on. They are `string` rather than their
+     * config types because this screen edits TEXT: `fastReview` accepts a number
+     * or `off`, and a typo must change nothing rather than resolve to a default
+     * (the discipline `maxTokens` already follows here).
+     */
+    fastEnabled: 'on' | 'off';
+    fastModel: string;
+    fastProvider: string;
+    fastReview: string;
+    /** The session review budget. `fastReview` is the PACE, this is the TOTAL. */
+    fastReviewBudget: string;
 }
 interface SettingsScreenProps {
     initial: SettingsValues;
@@ -39,7 +71,56 @@ interface SettingsScreenProps {
     theme: Theme;
     caps: TermCapabilities;
     onSave: (values: SettingsValues) => void;
+    /**
+     * `API retries` READ-ONLY row (llm-api-retry-backoff §6.9), e.g. `10` or `off`.
+     *
+     * A STRING FROM `App`, NOT A `SettingsValues` FIELD, and that distinction is the
+     * whole design: `SettingsValues` is what Enter WRITES, and routing retry through
+     * it would mean nine more editable rows (or one row whose Enter silently
+     * rewrote a section it does not own). `/retry` is the discoverable control;
+     * this row exists so "is it on, and how many" is answerable without leaving the
+     * screen. Absent = omit the row entirely.
+     */
+    retrySummary?: string;
 }
+/**
+ * The derived, non-editable line under the five fast rows — the sibling of
+ * `effectiveCapLine`, and it exists for the same reason (§4.5).
+ *
+ * A SETTINGS SCREEN THAT LETS A USER SWITCH A TIER ON AND GIVES NO SIGNAL THAT
+ * IT CANNOT RESOLVE is the failure `effectiveCapLine` was added to fix for
+ * `maxTokens`, one screen later. `keyFor` is the same resolver the controller
+ * uses, so this line and the runtime cannot disagree.
+ *
+ * IT DOES NOT TAKE `fastReviewBudget` AND MUST NOT (§4.4 part 5): this line
+ * describes what the tier IS, not what it is allowed to spend.
+ */
+export declare function fastTierLine(values: Pick<SettingsValues, 'provider' | 'fastEnabled' | 'fastModel' | 'fastProvider' | 'fastReview'>, hasKey: (providerId: string) => boolean): string;
+/**
+ * The five editable fast rows, as a config patch (§4.5 / hardening §4.4).
+ *
+ * PURE AND EXPORTED so `App`'s save handler holds no parsing of its own, and so
+ * the round trip `fastSettingsFrom(config)` -> edit -> `readFastSettings` can be
+ * tested without a terminal.
+ *
+ * A TYPO IN `fastReview` CHANGES NOTHING — the `review` / `reviewEveryTurns`
+ * keys are simply omitted from the patch, so `clampFastConfig`'s merge keeps
+ * whatever was there. That is the `Max tokens` discipline this screen already
+ * follows, and the alternative (resolving a typo to the default) silently
+ * discards the cadence the user actually set. `fastReviewBudget` follows the
+ * same rule; an out-of-range NUMBER is passed through to `clampFastConfig`'s
+ * `REVIEW_SESSION_RANGE` rather than being validated a second time here, so a
+ * row edit and a hand-edited `config.json` land on the same value.
+ */
+export declare function readFastSettings(values: Pick<SettingsValues, 'fastEnabled' | 'fastModel' | 'fastProvider' | 'fastReview' | 'fastReviewBudget'>): Partial<FastConfig>;
+/**
+ * The inverse: seed the five rows from a resolved config.
+ *
+ * OMITTING A KEY HERE IS THE SILENT HALF OF ADDING A ROW (§4.4 part 4): the row
+ * renders empty, `readFastSettings` sees an unparseable value, and an untouched
+ * save writes the clamp's default over whatever the user had.
+ */
+export declare function fastSettingsFrom(fast: FastConfig): Pick<SettingsValues, 'fastEnabled' | 'fastModel' | 'fastProvider' | 'fastReview' | 'fastReviewBudget'>;
 /**
  * The cap this setting will ACTUALLY produce against the selected model.
  *
@@ -51,5 +132,5 @@ interface SettingsScreenProps {
  * "I set 64000 but answers still stop early" has no answer anywhere in the UI.
  */
 export declare function effectiveCapLine(values: Pick<SettingsValues, 'provider' | 'model' | 'maxTokens'>): string;
-export declare function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset, onScrollClamp, theme, caps, onSave, }: SettingsScreenProps): React.ReactElement;
+export declare function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset, onScrollClamp, theme, caps, onSave, retrySummary, }: SettingsScreenProps): React.ReactElement;
 export {};

package/dist/ui/overlays/SettingsScreen.js

@@ -15,12 +15,137 @@ import { ADAPTER_PROVIDERS, THINKING_LEVELS, maskSecret, parseMaxTokensInput, }
 import { LOG_LEVEL_NAMES } from '../../logging/levels.js';
 import { pickGlyphs } from '../glyphs.js';
 import { OverlayFrame } from '../layout/OverlayFrame.js';
+const SHOW_THINKING_OPTIONS = ['off', 'on'];
+const LIVE_OUTPUT_OPTIONS = ['off', 'on'];
+const FAST_ENABLED_OPTIONS = ['off', 'on'];
+/**
+ * `(inherit)` IS THE EMPTY STRING, rendered as a word.
+ *
+ * An empty enum cell would read as "unset and therefore broken"; the truth is
+ * that an empty `fast.provider` INHERITS the main provider, which is the setting
+ * most users want and the one they should not have to type (§3.2 rule 2).
+ */
+const FAST_INHERIT_PROVIDER = '(inherit)';
+const FAST_PROVIDER_OPTIONS = [FAST_INHERIT_PROVIDER, ...ADAPTER_PROVIDERS];
+/**
+ * The derived, non-editable line under the five fast rows — the sibling of
+ * `effectiveCapLine`, and it exists for the same reason (§4.5).
+ *
+ * A SETTINGS SCREEN THAT LETS A USER SWITCH A TIER ON AND GIVES NO SIGNAL THAT
+ * IT CANNOT RESOLVE is the failure `effectiveCapLine` was added to fix for
+ * `maxTokens`, one screen later. `keyFor` is the same resolver the controller
+ * uses, so this line and the runtime cannot disagree.
+ *
+ * IT DOES NOT TAKE `fastReviewBudget` AND MUST NOT (§4.4 part 5): this line
+ * describes what the tier IS, not what it is allowed to spend.
+ */
+export function fastTierLine(values, hasKey) {
+    if (values.fastEnabled !== 'on')
+        return 'Fast tier: off';
+    const model = values.fastModel.trim();
+    if (model.length === 0)
+        return 'Fast tier: off  (fast.model is not set)';
+    const provider = values.fastProvider === FAST_INHERIT_PROVIDER || values.fastProvider.trim().length === 0
+        ? values.provider
+        : values.fastProvider;
+    if (!hasKey(provider)) {
+        return `Fast tier: ${provider}:${model}  (no API key for ${provider} - the tier will stay off)`;
+    }
+    const review = values.fastReview.trim().toLowerCase();
+    const cadence = review === 'off'
+        ? 'review off'
+        : /^\d+$/.test(review)
+            ? `review every ${review} turns`
+            : 'review every 5 turns';
+    return `Fast tier: ${provider}:${model}  (key set)  ${cadence}`;
+}
+/**
+ * The five editable fast rows, as a config patch (§4.5 / hardening §4.4).
+ *
+ * PURE AND EXPORTED so `App`'s save handler holds no parsing of its own, and so
+ * the round trip `fastSettingsFrom(config)` -> edit -> `readFastSettings` can be
+ * tested without a terminal.
+ *
+ * A TYPO IN `fastReview` CHANGES NOTHING — the `review` / `reviewEveryTurns`
+ * keys are simply omitted from the patch, so `clampFastConfig`'s merge keeps
+ * whatever was there. That is the `Max tokens` discipline this screen already
+ * follows, and the alternative (resolving a typo to the default) silently
+ * discards the cadence the user actually set. `fastReviewBudget` follows the
+ * same rule; an out-of-range NUMBER is passed through to `clampFastConfig`'s
+ * `REVIEW_SESSION_RANGE` rather than being validated a second time here, so a
+ * row edit and a hand-edited `config.json` land on the same value.
+ */
+export function readFastSettings(values) {
+    const review = values.fastReview.trim().toLowerCase();
+    const parsed = /^\d+$/.test(review) ? Number.parseInt(review, 10) : Number.NaN;
+    const budget = values.fastReviewBudget.trim();
+    const parsedBudget = /^\d+$/.test(budget) ? Number.parseInt(budget, 10) : Number.NaN;
+    return {
+        enabled: values.fastEnabled === 'on',
+        model: values.fastModel.trim(),
+        provider: values.fastProvider === FAST_INHERIT_PROVIDER ? '' : values.fastProvider.trim(),
+        ...(review === 'off' ? { review: false } : {}),
+        ...(Number.isFinite(parsed) && parsed > 0
+            ? { review: true, reviewEveryTurns: parsed }
+            : {}),
+        ...(Number.isFinite(parsedBudget) ? { reviewMaxPerSession: parsedBudget } : {}),
+    };
+}
+/**
+ * The inverse: seed the five rows from a resolved config.
+ *
+ * OMITTING A KEY HERE IS THE SILENT HALF OF ADDING A ROW (§4.4 part 4): the row
+ * renders empty, `readFastSettings` sees an unparseable value, and an untouched
+ * save writes the clamp's default over whatever the user had.
+ */
+export function fastSettingsFrom(fast) {
+    return {
+        fastEnabled: fast.enabled ? 'on' : 'off',
+        fastModel: fast.model,
+        fastProvider: fast.provider.trim().length > 0 ? fast.provider : FAST_INHERIT_PROVIDER,
+        fastReview: fast.review ? String(fast.reviewEveryTurns) : 'off',
+        fastReviewBudget: String(fast.reviewMaxPerSession),
+    };
+}
 const FIELDS = [
     { key: 'provider', label: 'Provider', kind: 'enum', options: ADAPTER_PROVIDERS },
     { key: 'model', label: 'Model', kind: 'text' },
     { key: 'baseUrl', label: 'Base URL', kind: 'text' },
     { key: 'thinkingLevel', label: 'Thinking', kind: 'enum', options: THINKING_LEVELS },
+    // Directly under `Thinking`, so the effort setting and the display setting are
+    // read together. `Show thinking` is 13 characters, inside the 18-column label
+    // budget `.padEnd(18)` enforces below and that IF-H7 records as silently
+    // overflowing.
+    { key: 'showThinking', label: 'Show thinking', kind: 'enum', options: SHOW_THINKING_OPTIONS },
+    // Beside `Show thinking`, because the two are the transcript's only display
+    // switches. `Live output` is 11 characters, inside the 18-column label budget
+    // `.padEnd(18)` enforces below and that IF-H7 records as silently overflowing.
+    { key: 'liveToolOutput', label: 'Live output', kind: 'enum', options: LIVE_OUTPUT_OPTIONS },
     { key: 'maxTokens', label: 'Max tokens', kind: 'text' },
+    // The fast tier sits AFTER `Max tokens` and BEFORE `API key`, because the key
+    // row is the one a user scrolls to deliberately and putting five rows past it
+    // would bury it (fast-model-tier §4.5). The rationale survives a fifth row;
+    // the count in it did not.
+    //
+    // `Fast review budget` is a `'text'` row, NOT a new numeric kind (D-H12):
+    // `SettingsRow.kind` is `'enum' | 'text' | 'secret'`, and `Max tokens` and
+    // `Fast review` are both bounded numbers already living as text plus an
+    // adapter parse. A fourth kind for one row would be a new interaction pattern
+    // in a screen whose whole design is that it edits text.
+    //
+    // ITS LABEL IS SHORT BECAUSE THE LABEL COLUMN IS A BUDGET, NOT A HINT SLOT.
+    // Labels render `.padEnd(18)` below, so one that reaches 18 does not truncate
+    // and does not wrap - it pushes ITS OWN value right (or butts against it at
+    // exactly 18) while every other row's value stays put, and the column stops
+    // being a column. So no `(1-500)` here: no other bounded row carries its range
+    // either (`Max tokens`, `Fast review`), `clampFastConfig` is the enforcement,
+    // and `/fast budget` states the range in the one place a user meets it - when
+    // it refuses a bad one. The name matches that command for the same reason.
+    { key: 'fastEnabled', label: 'Fast tier', kind: 'enum', options: FAST_ENABLED_OPTIONS },
+    { key: 'fastModel', label: 'Fast model', kind: 'text' },
+    { key: 'fastProvider', label: 'Fast provider', kind: 'enum', options: FAST_PROVIDER_OPTIONS },
+    { key: 'fastReview', label: 'Fast review', kind: 'text' },
+    { key: 'fastReviewBudget', label: 'Fast budget', kind: 'text' },
     { key: 'apiKey', label: 'API key', kind: 'secret' },
     { key: 'logLevel', label: 'Log level', kind: 'enum', options: LOG_LEVEL_NAMES },
 ];
@@ -52,7 +177,7 @@ export function effectiveCapLine(values) {
         return `Effective: ${resolution.value}  (auto)`;
     return `Effective: ${resolution.value}`;
 }
-export function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset, onScrollClamp, theme, caps, onSave, }) {
+export function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset, onScrollClamp, theme, caps, onSave, retrySummary, }) {
     const [values, setValues] = useState(initial);
     const [index, setIndex] = useState(0);
     const glyphs = pickGlyphs(caps);
@@ -132,6 +257,15 @@ export function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset,
         // setting, which is the one thing this field can never be.
         if (f.key === 'maxTokens' && raw.length === 0)
             return 'auto';
+        // `(not set)` and NOT `(same as main)`, which is the honest reading of §3.2
+        // rule 3: an empty `fast.model` does not inherit, it means the tier is
+        // unconfigured. `(same as main)` is a fact the derived line below states
+        // when the value literally equals the main model — never a placeholder.
+        if (f.key === 'fastModel' && raw.length === 0) {
+            return selected ? '(type a model id)' : '(not set)';
+        }
+        if (f.key === 'fastReview' && raw.length === 0)
+            return 'every 5 turns';
         return raw.length > 0 ? raw : selected ? '(type to set)' : '(none)';
     };
     // One element per row, each `wrap="truncate"` — the contract for OverlayFrame's
@@ -145,6 +279,18 @@ export function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset,
     // controlled mode slices by ELEMENT, so a row that wraps desynchronises the
     // position indicator.
     rows.push(_jsx(Text, { wrap: "truncate", color: theme.muted, children: effectiveCapLine(values) }, "__effective"));
+    rows.push(_jsx(Text, { wrap: "truncate", color: theme.muted, children: fastTierLine(values, (id) => (apiKeys[id] ?? '').length > 0) }, "__fast"));
+    /**
+     * ONE ROW, NOT NINE (llm-api-retry-backoff §6.9).
+     *
+     * READ-ONLY, and deliberately so: the nine `retry.*` keys belong to `config set`
+     * and `config.json`, and a settings screen that exposed a jitter checkbox is a
+     * settings screen nobody reads. What a user needs HERE is the answer to "is it
+     * on, and how many" — the discoverable control is `/retry`, which this row names.
+     */
+    if (retrySummary) {
+        rows.push(_jsxs(Text, { wrap: "truncate", color: theme.muted, children: ['  ', 'API retries'.padEnd(18), retrySummary] }, "__retry"));
+    }
     rows.push(_jsx(Text, { wrap: "truncate", color: theme.muted, children: "Enter saves. Keys persist to the config file (0600)." }, "__save"));
     return (_jsx(OverlayFrame, { title: "Settings", hint: `${glyphs.arrowUp}${glyphs.arrowDown} field ${glyphs.midDot} ${glyphs.arrowLeft}${glyphs.arrowRight} change ${glyphs.midDot} Enter save ${glyphs.midDot} Esc close`, maxRows: maxRows, cols: cols, rows: rows, scrollOffset: scrollOffset, onScrollClamp: onScrollClamp, theme: theme, caps: caps }));
 }

package/dist/ui/render-cache.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Render caches (tui-render-performance L2 / R2 + R3).
+ *
+ * Ink has no output caching: every frame re-walks the whole mounted tree,
+ * re-measures every text node and re-serialises the frame. The two most
+ * expensive PURE computations in that walk were being redone from scratch on
+ * every one of them:
+ *
+ *   - `cli-highlight`'s `highlight()` ran INSIDE `CodeBlock`'s render body, so a
+ *     200-line fenced block was a complete highlight.js tokenise, 30 times a
+ *     second, for as long as it stayed mounted;
+ *   - `Markdown` re-split and re-regexed the whole answer into one React element
+ *     per line on every render.
+ *
+ * Everything cached here is a function of its INPUT STRING ALONE. Theme and
+ * glyphs are applied at render time and are never cached, because a themed
+ * React element in a cache makes `/theme` a no-op until the entry evicts (K-5) —
+ * exactly the class of silent bug this package writes comments to avoid.
+ *
+ * Caches are MODULE-LEVEL on purpose: settled transcript text is identical
+ * across component instances and across mount/unmount cycles, so per-instance
+ * caches would miss precisely when a scroll brings an old entry back.
+ */
+import { type MdBlock } from './markdown-blocks.js';
+import { type Glyphs } from './glyphs.js';
+import type { TermCapabilities } from './capabilities.js';
+export declare const RENDER_CACHE_LIMITS: {
+    readonly highlightEntries: 128;
+    readonly highlightBytes: number;
+    /**
+     * Above this, skip highlighting entirely.
+     *
+     * highlight.js is superlinear in the length of a single block, and a
+     * multi-megabyte "code block" is almost always a pasted log rather than
+     * source. Rendering it plain costs the user nothing they would have been able
+     * to read; tokenising it costs the whole frame budget.
+     */
+    readonly highlightMaxChars: 20000;
+    readonly markdownEntries: 256;
+    readonly markdownBytes: number;
+    readonly linesEntries: 512;
+};
+export interface RenderCacheStats {
+    markdownEntries: number;
+    markdownBytes: number;
+    highlightEntries: number;
+    highlightBytes: number;
+    lineEntries: number;
+    hits: number;
+    misses: number;
+}
+/**
+ * Syntax-highlight `code`, memoised on `(lang, code)`.
+ *
+ * `cli-highlight` emits chalk-level ANSI that does not depend on `theme.*`, so
+ * unlike a rendered element this string IS safe to cache across a `/theme`
+ * switch — the same property it has had since before this cache existed.
+ */
+export declare function highlightCached(code: string, lang: string): string;
+/** Parse a markdown document into blocks, memoised on the whole text. */
+export declare function parseMarkdownCached(text: string): MdBlock[];
+/**
+ * `text.split('\n')`, memoised.
+ *
+ * READ-ONLY BY CONTRACT. The returned array is shared with every other holder of
+ * the same string, so a caller that sorts or splices it in place corrupts an
+ * unrelated card. The `readonly string[]` return type is the enforcement.
+ */
+export declare function splitLinesCached(text: string): readonly string[];
+/**
+ * The glyph set for a terminal.
+ *
+ * `pickGlyphs` already returns one of two module constants, so this adds no
+ * caching of its own — it exists so that every render-layer memoisation the
+ * transcript depends on is reachable from one module, and so the components can
+ * stop calling `pickGlyphs` once per entry per frame through six import paths.
+ */
+export declare function glyphsFor(caps: TermCapabilities): Glyphs;
+/** Drop everything. `/perf reset`, and the test suite between cases. */
+export declare function clearRenderCaches(): void;
+export declare function renderCacheStats(): RenderCacheStats;

package/dist/ui/render-cache.js

@@ -0,0 +1,195 @@
+/**
+ * Render caches (tui-render-performance L2 / R2 + R3).
+ *
+ * Ink has no output caching: every frame re-walks the whole mounted tree,
+ * re-measures every text node and re-serialises the frame. The two most
+ * expensive PURE computations in that walk were being redone from scratch on
+ * every one of them:
+ *
+ *   - `cli-highlight`'s `highlight()` ran INSIDE `CodeBlock`'s render body, so a
+ *     200-line fenced block was a complete highlight.js tokenise, 30 times a
+ *     second, for as long as it stayed mounted;
+ *   - `Markdown` re-split and re-regexed the whole answer into one React element
+ *     per line on every render.
+ *
+ * Everything cached here is a function of its INPUT STRING ALONE. Theme and
+ * glyphs are applied at render time and are never cached, because a themed
+ * React element in a cache makes `/theme` a no-op until the entry evicts (K-5) —
+ * exactly the class of silent bug this package writes comments to avoid.
+ *
+ * Caches are MODULE-LEVEL on purpose: settled transcript text is identical
+ * across component instances and across mount/unmount cycles, so per-instance
+ * caches would miss precisely when a scroll brings an old entry back.
+ */
+import { highlight } from 'cli-highlight';
+import { parseMarkdownBlocks } from './markdown-blocks.js';
+import { pickGlyphs } from './glyphs.js';
+export const RENDER_CACHE_LIMITS = {
+    highlightEntries: 128,
+    highlightBytes: 2 * 1024 * 1024,
+    /**
+     * Above this, skip highlighting entirely.
+     *
+     * highlight.js is superlinear in the length of a single block, and a
+     * multi-megabyte "code block" is almost always a pasted log rather than
+     * source. Rendering it plain costs the user nothing they would have been able
+     * to read; tokenising it costs the whole frame budget.
+     */
+    highlightMaxChars: 20_000,
+    markdownEntries: 256,
+    markdownBytes: 4 * 1024 * 1024,
+    linesEntries: 512,
+};
+/**
+ * Insertion-ordered LRU with both an entry-count and an approximate byte budget.
+ *
+ * TWO BUDGETS, NOT ONE. An entry count alone is unbounded in memory (one 5 MB
+ * answer), and a byte budget alone is unbounded in Map overhead (a hundred
+ * thousand one-character keys). Every cache here can be fed by the model, so
+ * both directions have to be closed.
+ */
+class LruCache {
+    maxEntries;
+    maxBytes;
+    map = new Map();
+    total = 0;
+    hits = 0;
+    misses = 0;
+    constructor(maxEntries, maxBytes) {
+        this.maxEntries = maxEntries;
+        this.maxBytes = maxBytes;
+    }
+    get(key) {
+        const hit = this.map.get(key);
+        if (hit === undefined) {
+            this.misses += 1;
+            return undefined;
+        }
+        // Re-insert to move the key to the young end of the insertion order.
+        this.map.delete(key);
+        this.map.set(key, hit);
+        this.hits += 1;
+        return hit.value;
+    }
+    set(key, value, bytes) {
+        const existing = this.map.get(key);
+        if (existing)
+            this.total -= existing.bytes;
+        this.map.delete(key);
+        this.map.set(key, { value, bytes });
+        this.total += bytes;
+        while (this.map.size > this.maxEntries || this.total > this.maxBytes) {
+            const oldest = this.map.keys().next();
+            if (oldest.done)
+                break;
+            const entry = this.map.get(oldest.value);
+            if (entry)
+                this.total -= entry.bytes;
+            this.map.delete(oldest.value);
+        }
+        return value;
+    }
+    clear() {
+        this.map.clear();
+        this.total = 0;
+        this.hits = 0;
+        this.misses = 0;
+    }
+    get size() {
+        return this.map.size;
+    }
+    get bytes() {
+        return this.total;
+    }
+}
+const highlightCache = new LruCache(RENDER_CACHE_LIMITS.highlightEntries, RENDER_CACHE_LIMITS.highlightBytes);
+const markdownCache = new LruCache(RENDER_CACHE_LIMITS.markdownEntries, RENDER_CACHE_LIMITS.markdownBytes);
+/**
+ * `text.split('\n')` results.
+ *
+ * Bounded by ENTRY COUNT ONLY, and the byte budget is set to the markdown one
+ * because the arrays are views over strings the transcript already holds — they
+ * add pointer overhead, not a second copy of the text.
+ */
+const lineCache = new LruCache(RENDER_CACHE_LIMITS.linesEntries, RENDER_CACHE_LIMITS.markdownBytes);
+/**
+ * Syntax-highlight `code`, memoised on `(lang, code)`.
+ *
+ * `cli-highlight` emits chalk-level ANSI that does not depend on `theme.*`, so
+ * unlike a rendered element this string IS safe to cache across a `/theme`
+ * switch — the same property it has had since before this cache existed.
+ */
+export function highlightCached(code, lang) {
+    if (code.length === 0)
+        return code;
+    if (code.length > RENDER_CACHE_LIMITS.highlightMaxChars)
+        return code;
+    // The delimiter is written as an ESCAPE and never as a literal control
+    // character: a raw NUL byte makes the whole file "binary" to grep and
+    // ripgrep, which silently hides every definition in it from the tool this
+    // codebase navigates itself with. NUL rather than a space because a space
+    // still lets ("a b", "ts") and ("b", "ts a") collide on one key.
+    const key = `${lang}\u0000${code}`;
+    const hit = highlightCache.get(key);
+    if (hit !== undefined)
+        return hit;
+    let rendered = code;
+    try {
+        rendered = highlight(code, { language: lang || undefined, ignoreIllegals: true });
+    }
+    catch {
+        rendered = code;
+    }
+    return highlightCache.set(key, rendered, key.length + rendered.length);
+}
+/** Parse a markdown document into blocks, memoised on the whole text. */
+export function parseMarkdownCached(text) {
+    const hit = markdownCache.get(text);
+    if (hit !== undefined)
+        return hit;
+    return markdownCache.set(text, parseMarkdownBlocks(text), text.length * 2);
+}
+/**
+ * `text.split('\n')`, memoised.
+ *
+ * READ-ONLY BY CONTRACT. The returned array is shared with every other holder of
+ * the same string, so a caller that sorts or splices it in place corrupts an
+ * unrelated card. The `readonly string[]` return type is the enforcement.
+ */
+export function splitLinesCached(text) {
+    if (text.length === 0)
+        return EMPTY_LINES;
+    const hit = lineCache.get(text);
+    if (hit !== undefined)
+        return hit;
+    return lineCache.set(text, text.split('\n'), text.length);
+}
+const EMPTY_LINES = [];
+/**
+ * The glyph set for a terminal.
+ *
+ * `pickGlyphs` already returns one of two module constants, so this adds no
+ * caching of its own — it exists so that every render-layer memoisation the
+ * transcript depends on is reachable from one module, and so the components can
+ * stop calling `pickGlyphs` once per entry per frame through six import paths.
+ */
+export function glyphsFor(caps) {
+    return pickGlyphs(caps);
+}
+/** Drop everything. `/perf reset`, and the test suite between cases. */
+export function clearRenderCaches() {
+    highlightCache.clear();
+    markdownCache.clear();
+    lineCache.clear();
+}
+export function renderCacheStats() {
+    return {
+        markdownEntries: markdownCache.size,
+        markdownBytes: markdownCache.bytes,
+        highlightEntries: highlightCache.size,
+        highlightBytes: highlightCache.bytes,
+        lineEntries: lineCache.size,
+        hits: markdownCache.hits + highlightCache.hits + lineCache.hits,
+        misses: markdownCache.misses + highlightCache.misses + lineCache.misses,
+    };
+}

package/dist/ui/render-governor.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Adaptive render governor (tui-render-performance L4 / R7). Pure, React-free.
+ *
+ * Neither the streaming coalescer nor Ink adapts when a frame overruns its
+ * budget: the coalescer keeps its 33 ms timer, Ink keeps its 32 ms throttle, and
+ * the event loop saturates. Renders then queue behind each other on Node's
+ * single thread and KEYSTROKES QUEUE BEHIND THE RENDERS — which is what turns a
+ * slow frame into an unresponsive terminal.
+ *
+ * The ladder is the safety net under L1/L2/L3, not a substitute for them: it
+ * cannot make a frame cheaper, only rarer. Its job is to turn any residual
+ * pathology from a freeze into a visibly slower but still interactive UI.
+ *
+ * I-L4-1 — the governor changes only HOW OFTEN the view updates. Never what is
+ * dispatched, never the order, never the final state. `mergeDeltas` already
+ * guarantees that a longer window is simply a larger merge and that any
+ * non-delta action flushes the pending run first, so the same event sequence
+ * must produce the same final `ViewState` at every rung
+ * (`render-governor.test.ts`).
+ */
+/** Coalescing intervals, in ms. Rung 0 is the pre-feature `COALESCE_MS`. */
+export declare const GOVERNOR_LADDER: readonly [33, 50, 80, 125, 200, 320];
+/** Step up when a commit costs more than this fraction of the current interval. */
+export declare const GOVERNOR_UP_RATIO = 0.7;
+/**
+ * Consecutive cheap frames required before stepping back down.
+ *
+ * Hysteresis, and it has to be asymmetric: stepping up on one expensive frame
+ * and down on one cheap one would oscillate through the whole ladder while a
+ * long answer streams past a couple of code blocks.
+ */
+export declare const GOVERNOR_DOWN_STREAK = 8;
+export interface GovernorState {
+    rung: number;
+    cheapStreak: number;
+}
+export declare function initialGovernor(): GovernorState;
+/**
+ * The coalescing interval for a state.
+ *
+ * Clamped to `maxIntervalMs` in BOTH directions: `maxRenderIntervalMs = 33`
+ * flattens the ladder to one rung, which is the documented way to get the
+ * pre-feature cadence without reaching for the kill switch.
+ */
+export declare function intervalOf(state: GovernorState, maxIntervalMs: number): number;
+/**
+ * Fold one commit's cost into the ladder.
+ *
+ * `lastCommitMs` covers React reconciliation AND Ink's yoga layout, because Ink
+ * computes layout in `onRender`, which React runs before layout effects. It does
+ * NOT cover Ink's serialisation and the stdout write, which happen after. In
+ * practice layout dominates, and the ladder's job is DIRECTION, not accuracy.
+ */
+export declare function stepGovernor(state: GovernorState, lastCommitMs: number, maxIntervalMs: number): GovernorState;