@aragon-agent/cli 0.5.6 → 0.5.8

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;

package/dist/ui/render-governor.js

@@ -0,0 +1,78 @@
+/**
+ * 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 const GOVERNOR_LADDER = [33, 50, 80, 125, 200, 320];
+/** Step up when a commit costs more than this fraction of the current interval. */
+export 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 const GOVERNOR_DOWN_STREAK = 8;
+export function initialGovernor() {
+    return { rung: 0, cheapStreak: 0 };
+}
+/** Highest rung reachable under `maxIntervalMs`. Always at least 0. */
+function topRung(maxIntervalMs) {
+    let top = 0;
+    for (let i = 1; i < GOVERNOR_LADDER.length; i += 1) {
+        if (GOVERNOR_LADDER[i] <= maxIntervalMs)
+            top = i;
+    }
+    return top;
+}
+/**
+ * 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 function intervalOf(state, maxIntervalMs) {
+    const ceiling = Number.isFinite(maxIntervalMs) ? maxIntervalMs : GOVERNOR_LADDER[0];
+    const rung = Math.min(Math.max(0, Math.floor(state.rung)), topRung(ceiling));
+    return Math.min(ceiling, GOVERNOR_LADDER[rung] ?? GOVERNOR_LADDER[0]);
+}
+/**
+ * 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 function stepGovernor(state, lastCommitMs, maxIntervalMs) {
+    const top = topRung(Number.isFinite(maxIntervalMs) ? maxIntervalMs : GOVERNOR_LADDER[0]);
+    const rung = Math.min(Math.max(0, Math.floor(state.rung)), top);
+    const interval = intervalOf({ rung, cheapStreak: state.cheapStreak }, maxIntervalMs);
+    const cost = Number.isFinite(lastCommitMs) ? lastCommitMs : 0;
+    if (cost > interval * GOVERNOR_UP_RATIO) {
+        return { rung: Math.min(top, rung + 1), cheapStreak: 0 };
+    }
+    const streak = state.cheapStreak + 1;
+    if (streak >= GOVERNOR_DOWN_STREAK) {
+        return { rung: Math.max(0, rung - 1), cheapStreak: 0 };
+    }
+    return { rung, cheapStreak: streak };
+}

package/dist/ui/transcript-text.d.ts

@@ -22,6 +22,17 @@ export interface TranscriptTextOptions {
     elapsedMs: number;
     /** Entries beyond this count collapse into a single "… N omitted" line. */
     maxEntries?: number;
+    /**
+     * Entries the retain ring already removed from `ViewState`
+     * (tui-render-performance L1 / K-6).
+     *
+     * A DIFFERENT LOSS FROM `maxEntries`, and both have to be reported: that one
+     * omits the middle of a transcript this replay still holds in full, while this
+     * one names entries the process no longer has. A replay that silently starts
+     * mid-session is exactly the failure the retain ring would otherwise
+     * introduce.
+     */
+    droppedEntries?: number;
 }
 /** Render the whole session (summary line + entries) as plain text. */
 export declare function renderTranscriptText(entries: Entry[], opts: TranscriptTextOptions): string;

package/dist/ui/transcript-text.js

@@ -111,6 +111,11 @@ export function renderTranscriptText(entries, opts) {
     ].join(` ${g.midDot} `);
     const max = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
     const lines = [summary];
+    const dropped = opts.droppedEntries ?? 0;
+    if (dropped > 0) {
+        lines.push(`${g.ellipsis} ${dropped} earlier ${dropped === 1 ? 'entry' : 'entries'} dropped by ` +
+            `transcriptRetain ${g.midDot} raise it or /save sooner`);
+    }
     if (entries.length > max && max > 1) {
         const head = Math.ceil(max / 2);
         const tail = max - head;

package/dist/ui/use-height-store.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The transcript height cache (tui-render-performance L3).
+ *
+ * Virtualisation needs a height for entries it is NOT mounting. Measured
+ * heights are authoritative; entries that have never been on screen fall back to
+ * `estimateEntryRows`, and both are memoised on the same `heightKey` so a
+ * `cols` change or a content change invalidates them together (V-5).
+ *
+ * THE MAP LIVES IN A REF, NOT IN STATE, and the version counter is bumped at
+ * most once per frame through a microtask and ONLY when a value actually
+ * changed. K-2 is the failure this shape exists to prevent: a naive
+ * measure -> setState -> re-measure store never converges, and the symptom is a
+ * hung terminal rather than an error. In steady state — settled entries at a
+ * fixed width — this produces zero extra renders.
+ */
+import { type HeightKey } from './layout/virtual-window.js';
+export interface HeightStoreStats {
+    measured: number;
+    estimated: number;
+}
+export interface HeightStore {
+    /** Bumped at most once per frame, and only when a measurement changed. */
+    version: number;
+    /** Measured rows, else the memoised estimate, computing it once if needed. */
+    resolve: (key: HeightKey, estimate: () => number) => number;
+    /** Called from `MeasuredEntry`'s layout effect. Idempotent per (key, value). */
+    report: (key: HeightKey, rows: number) => void;
+    stats: () => HeightStoreStats;
+    clear: () => void;
+}
+export declare function useHeightStore(): HeightStore;

package/dist/ui/use-height-store.js

@@ -0,0 +1,76 @@
+/**
+ * The transcript height cache (tui-render-performance L3).
+ *
+ * Virtualisation needs a height for entries it is NOT mounting. Measured
+ * heights are authoritative; entries that have never been on screen fall back to
+ * `estimateEntryRows`, and both are memoised on the same `heightKey` so a
+ * `cols` change or a content change invalidates them together (V-5).
+ *
+ * THE MAP LIVES IN A REF, NOT IN STATE, and the version counter is bumped at
+ * most once per frame through a microtask and ONLY when a value actually
+ * changed. K-2 is the failure this shape exists to prevent: a naive
+ * measure -> setState -> re-measure store never converges, and the symptom is a
+ * hung terminal rather than an error. In steady state — settled entries at a
+ * fixed width — this produces zero extra renders.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { VIRTUAL_LIMITS } from './layout/virtual-window.js';
+/** Drop the oldest keys once a map passes the ceiling (insertion-ordered LRU). */
+function trim(map) {
+    while (map.size > VIRTUAL_LIMITS.heightEntries) {
+        const oldest = map.keys().next();
+        if (oldest.done)
+            break;
+        map.delete(oldest.value);
+    }
+}
+export function useHeightStore() {
+    const measured = useRef(new Map());
+    const estimated = useRef(new Map());
+    const [version, setVersion] = useState(0);
+    const scheduled = useRef(false);
+    const mounted = useRef(true);
+    useEffect(() => () => {
+        mounted.current = false;
+    }, []);
+    const report = useCallback((key, rows) => {
+        const value = Number.isFinite(rows) && rows > 0 ? Math.floor(rows) : 0;
+        if (value <= 0)
+            return;
+        if (measured.current.get(key) === value)
+            return;
+        measured.current.set(key, value);
+        trim(measured.current);
+        // An estimate that has been superseded is dead weight; dropping it here is
+        // what keeps `stats()` honest for `/perf`.
+        estimated.current.delete(key);
+        if (scheduled.current)
+            return;
+        scheduled.current = true;
+        queueMicrotask(() => {
+            scheduled.current = false;
+            if (mounted.current)
+                setVersion((v) => v + 1);
+        });
+    }, []);
+    const resolve = useCallback((key, estimate) => {
+        const hit = measured.current.get(key);
+        if (hit !== undefined)
+            return hit;
+        const cached = estimated.current.get(key);
+        if (cached !== undefined)
+            return cached;
+        const value = Math.max(1, Math.floor(estimate()));
+        estimated.current.set(key, value);
+        trim(estimated.current);
+        return value;
+    }, []);
+    const stats = useCallback(() => ({ measured: measured.current.size, estimated: estimated.current.size }), []);
+    const clear = useCallback(() => {
+        measured.current.clear();
+        estimated.current.clear();
+        if (mounted.current)
+            setVersion((v) => v + 1);
+    }, []);
+    return { version, resolve, report, stats, clear };
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Commit-cost timing for the render governor (tui-render-performance L4).
+ *
+ * `performance.now()` is taken at the TOP of the `App` render body (this hook
+ * must therefore be called early, before any other work) and again in a layout
+ * effect. Ink computes yoga layout in `onRender`, which React runs BEFORE layout
+ * effects, so that span covers React reconciliation AND the Ink layout pass —
+ * the same mechanism `ScrollViewport.tsx:87-88` and `AppShell.tsx:100-102`
+ * already document and rely on.
+ *
+ * ONLY THE RUNG IS REACT STATE. The measured cost and the resolved interval live
+ * in refs: putting a millisecond count in state would re-render the whole tree
+ * on every frame to record how expensive rendering the whole tree was.
+ */
+export interface RenderGovernorOptions {
+    /** `false` pins rung 0 forever (`--no-render-governor`, `ARAGON_RENDER_GOVERNOR=0`). */
+    enabled: boolean;
+    /** Ceiling of the ladder; `33` flattens it. */
+    maxIntervalMs: number;
+}
+export interface RenderGovernorHandle {
+    /**
+     * The coalescing interval to arm the next flush timer with.
+     *
+     * A REF, read at `setTimeout` time. The coalescer's callbacks are `useCallback`d
+     * with stable deps and must stay that way (the controller subscription effect
+     * never re-runs), so a plain value would be pinned to the mount render.
+     */
+    intervalMs: {
+        current: number;
+    };
+    /** Rendered as the `eco` chip when > 0 (I-L4-2). */
+    rung: number;
+    /** Most recent commit cost in ms, for `/perf`. Not state. */
+    lastCommitMs: () => number;
+    /** `/perf reset` — back to rung 0. */
+    reset: () => void;
+}
+export declare function useRenderGovernor(opts: RenderGovernorOptions): RenderGovernorHandle;

package/dist/ui/use-render-governor.js

@@ -0,0 +1,57 @@
+/**
+ * Commit-cost timing for the render governor (tui-render-performance L4).
+ *
+ * `performance.now()` is taken at the TOP of the `App` render body (this hook
+ * must therefore be called early, before any other work) and again in a layout
+ * effect. Ink computes yoga layout in `onRender`, which React runs BEFORE layout
+ * effects, so that span covers React reconciliation AND the Ink layout pass —
+ * the same mechanism `ScrollViewport.tsx:87-88` and `AppShell.tsx:100-102`
+ * already document and rely on.
+ *
+ * ONLY THE RUNG IS REACT STATE. The measured cost and the resolved interval live
+ * in refs: putting a millisecond count in state would re-render the whole tree
+ * on every frame to record how expensive rendering the whole tree was.
+ */
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { performance } from 'node:perf_hooks';
+import { GOVERNOR_LADDER, initialGovernor, intervalOf, stepGovernor, } from './render-governor.js';
+export function useRenderGovernor(opts) {
+    const { enabled, maxIntervalMs } = opts;
+    const stateRef = useRef(initialGovernor());
+    const intervalMs = useRef(GOVERNOR_LADDER[0]);
+    const lastCommit = useRef(0);
+    const startedAt = useRef(0);
+    const mounted = useRef(true);
+    const [rung, setRung] = useState(0);
+    // Stamped during render, which is the whole point of calling this hook first.
+    startedAt.current = performance.now();
+    useEffect(() => () => {
+        mounted.current = false;
+    }, []);
+    useLayoutEffect(() => {
+        const cost = performance.now() - startedAt.current;
+        lastCommit.current = cost;
+        if (!enabled) {
+            stateRef.current = initialGovernor();
+            intervalMs.current = Math.min(maxIntervalMs, GOVERNOR_LADDER[0]);
+            if (rung !== 0)
+                setRung(0);
+            return;
+        }
+        const next = stepGovernor(stateRef.current, cost, maxIntervalMs);
+        stateRef.current = next;
+        intervalMs.current = intervalOf(next, maxIntervalMs);
+        // React bails out when the value is unchanged, so this is a no-op on every
+        // frame that did not move the ladder — which is almost all of them.
+        if (mounted.current && next.rung !== rung)
+            setRung(next.rung);
+    });
+    const reset = useCallback(() => {
+        stateRef.current = initialGovernor();
+        intervalMs.current = Math.min(maxIntervalMs, GOVERNOR_LADDER[0]);
+        if (mounted.current)
+            setRung(0);
+    }, [maxIntervalMs]);
+    const lastCommitMs = useCallback(() => lastCommit.current, []);
+    return { intervalMs, rung, lastCommitMs, reset };
+}

package/dist/ui/use-startup-notices.d.ts

@@ -12,6 +12,14 @@
  * not otherwise see — rather than belonging to the view.
  */
 import type { ViewAction } from '../agent/reducer.js';
+/**
+ * `{ requested, resolved }` when the raise happened, `undefined` otherwise —
+ * i.e. `cfg.transcriptRetainRequested` and `cfg.transcriptRetain`.
+ */
+export interface RetainNoticeOptions {
+    requested: number;
+    resolved: number;
+}
 export interface MouseNoticeOptions {
     /**
      * Whether reporting is ACTUALLY in effect — i.e. a filter was installed, not
@@ -22,4 +30,4 @@ export interface MouseNoticeOptions {
     /** Record that it was shown (`state.json`). Called once, after dispatch. */
     onSeen: () => void;
 }
-export declare function useStartupNotices(dispatch: (action: ViewAction) => void, mouseNotice?: MouseNoticeOptions): void;
+export declare function useStartupNotices(dispatch: (action: ViewAction) => void, mouseNotice?: MouseNoticeOptions, retainNotice?: RetainNoticeOptions): void;

package/dist/ui/use-startup-notices.js

@@ -25,7 +25,21 @@ import { getLogger } from '../logging/logger.js';
  */
 const MOUSE_SELECTION_NOTICE = 'Mouse wheel scrolls the transcript. Hold Shift to select text, ' +
     'or turn it off with `aragon config set mouse false`.';
-export function useStartupNotices(dispatch, mouseNotice) {
+/**
+ * The §5.1 notice (tui-render-performance). Shown once per run, and only when
+ * the user's own `transcriptRetain` was below `transcriptWindow`.
+ *
+ * The raise itself is not negotiable — retaining fewer entries than the horizon
+ * can scroll to makes part of that horizon permanently unreachable — but doing
+ * it in silence would leave a user staring at a `/perf` line that disagrees with
+ * the number in their own config file and no way to connect the two.
+ */
+function retainRaisedNotice(requested, resolved) {
+    return (`transcriptRetain ${requested} is below transcriptWindow ${resolved}; using ${resolved} ` +
+        'so the whole scroll horizon stays reachable. Lower transcriptWindow too if you meant ' +
+        'to cap memory.');
+}
+export function useStartupNotices(dispatch, mouseNotice, retainNotice) {
     // The sink gives up after repeated write failures (a read-only log directory,
     // a full disk). Silently logging nothing is exactly the state a user must not
     // discover later, from an empty file, while trying to explain a bug.
@@ -62,4 +76,24 @@ export function useStartupNotices(dispatch, mouseNotice) {
         dispatch({ type: 'notice', level: 'info', text: MOUSE_SELECTION_NOTICE });
         noticeRef.current?.onSeen();
     }, [mouseEnabled, dispatch]);
+    // A `warn` notice rather than a toast: it is about a value the user typed, so
+    // it belongs in the transcript where it can be scrolled back to, not in a row
+    // that expires. DEPENDS ON THE TWO SCALARS, never on the options object —
+    // `App` builds that literal during render, and depending on it would re-run
+    // this effect on every frame of the session.
+    const retainRequested = retainNotice?.requested;
+    const retainResolved = retainNotice?.resolved;
+    const retainNoticeShown = useRef(false);
+    useEffect(() => {
+        if (retainRequested === undefined || retainResolved === undefined)
+            return;
+        if (retainNoticeShown.current)
+            return;
+        retainNoticeShown.current = true;
+        dispatch({
+            type: 'notice',
+            level: 'warn',
+            text: retainRaisedNotice(retainRequested, retainResolved),
+        });
+    }, [retainRequested, retainResolved, dispatch]);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aragon-agent/cli",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "description": "AragonAgent CLI — a Claude-Code / Codex-style interactive terminal UI (TUI) on top of the @aragon-agent/core engine. Installable and runnable via npm / npx.",
   "license": "MIT",
   "author": "AragonAgent contributors",
@@ -52,7 +52,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@aragon-agent/core": "^0.2.6",
+    "@aragon-agent/core": "^0.2.8",
     "chalk": "^5.6.2",
     "cli-highlight": "^2.0.0",
     "commander": "^12.1.0",