@aragon-agent/cli 0.5.6 → 0.5.8

package/dist/cli.js

@@ -27,7 +27,7 @@ import { LOG_CONFIG_SET_KEYS, TEAM_CONFIG_SET_KEYS, applyLogConfigSet, applyTeam
 import { attachAgentEvents, attachTeamEvents, installLogging, setScreenRestore, setSignalTerminator, } from './logging/install.js';
 import { getLogger } from './logging/logger.js';
 import { runLogsCommand } from './logging/cli-commands.js';
-import { ADAPTER_PROVIDERS, clampDensity, clampTheme, clampThinkingLevel, clampAskRounds, clampHumanTimeout, clampSkillsIntegrity, clampSkillsToolPolicy, clampTranscriptWindow, coercePositiveInt, isAdapterProvider, parseMaxTokensInput, DEFAULT_MAX_TOKENS, DEFAULT_PLAN_HUMAN_TIMEOUT_MS, DEFAULT_PLAN_MAX_ASK_ROUNDS, DEFAULT_SKILLS_CONFIG, } from './config/schema.js';
+import { ADAPTER_PROVIDERS, clampDensity, clampTheme, clampThinkingLevel, clampAskRounds, clampHumanTimeout, clampSkillsIntegrity, clampSkillsToolPolicy, clampMaxRenderInterval, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAdapterProvider, parseMaxTokensInput, DEFAULT_MAX_RENDER_INTERVAL_MS, DEFAULT_MAX_TOKENS, DEFAULT_PLAN_HUMAN_TIMEOUT_MS, DEFAULT_PLAN_MAX_ASK_ROUNDS, DEFAULT_SKILLS_CONFIG, DEFAULT_TRANSCRIPT_RETAIN, DEFAULT_TRANSCRIPT_WINDOW, } from './config/schema.js';
 import { makeGetApiKey } from './config/load.js';
 import { AgentController, DENY_ALL_APPROVAL } from './agent/controller.js';
 import { runSkillsCommand } from './skills/cli-commands.js';
@@ -102,6 +102,13 @@ function toFlags(opts) {
         logLevel: opts.logLevel ?? (opts.verbose ? 'debug' : undefined),
         logFile: opts.logFile,
         logDir: opts.logDir,
+        // Site three of three for the render-performance flags. A flag needs the
+        // `.option()` declaration below, a field on `CliFlags`, AND a line here;
+        // miss this one and it is inert with no compile error and no runtime error
+        // (`mouse` P1-2, `team` P1-4, `todo` C-9 -- four features, same trap).
+        transcriptRetain: opts.transcriptRetain,
+        renderGovernor: opts.renderGovernor,
+        maxRenderInterval: opts.maxRenderInterval,
     };
 }
 // ---------------------------------------------------------------------------
@@ -239,6 +246,10 @@ function runInteractive(flags, extras = {}) {
             provider: snapshot.provider,
             model: snapshot.model,
             elapsedMs: Date.now() - snapshot.startedAt,
+            // Names what the retain ring removed, so a long session's replay never
+            // starts mid-conversation without saying why (tui-render-performance
+            // L1 / K-6).
+            ...(snapshot.droppedEntries ? { droppedEntries: snapshot.droppedEntries } : {}),
         }));
     };
     if (mode === 'fullscreen') {
@@ -393,6 +404,12 @@ const CONFIG_SET_KEYS = new Set([
     'fullscreen',
     'exitTranscript',
     'transcriptWindow',
+    // tui-render-performance L1 / L4. Listed here AND cased in the switch
+    // below: a key present here but absent there falls through, writes
+    // nothing, and still prints `Set <key> = <value>` (P1-2).
+    'transcriptRetain',
+    'renderGovernor',
+    'maxRenderIntervalMs',
     // Without these two, `density` and `hints` would be settable only as one-shot
     // flags and never persist -- inconsistent with every other config field.
     'density',
@@ -509,7 +526,16 @@ function runConfigSet(key, value) {
             patch.exitTranscript = value === 'true' || value === '1';
             break;
         case 'transcriptWindow':
-            patch.transcriptWindow = clampTranscriptWindow(value, 300);
+            patch.transcriptWindow = clampTranscriptWindow(value, DEFAULT_TRANSCRIPT_WINDOW);
+            break;
+        case 'transcriptRetain':
+            patch.transcriptRetain = clampTranscriptRetain(value, DEFAULT_TRANSCRIPT_RETAIN);
+            break;
+        case 'renderGovernor':
+            patch.renderGovernor = value === 'true' || value === '1';
+            break;
+        case 'maxRenderIntervalMs':
+            patch.maxRenderIntervalMs = clampMaxRenderInterval(value, DEFAULT_MAX_RENDER_INTERVAL_MS);
             break;
         case 'density':
             patch.density = clampDensity(value, 'comfortable');
@@ -654,6 +680,14 @@ function buildProgram() {
         // No short form: `-v` is already `--version`.
         .option('--verbose', 'Shorthand for --log-level debug')
         .option('--log-dir <dir>', 'Absolute log directory for this run')
+        // Render performance (tui-render-performance §5.2). `--render-governor` is
+        // declared BEFORE its negative form for the tri-state reason recorded four
+        // times above: `renderGovernor` is persisted, so negative-only would default
+        // `opts.renderGovernor` to `true` and silently overwrite a stored `false`.
+        .option('--transcript-retain <n>', 'Entries kept in memory (200-20000, default 1000)')
+        .option('--render-governor', 'Adapt the frame interval under load (the default)')
+        .option('--no-render-governor', 'Pin the frame interval at 33ms however expensive a frame is')
+        .option('--max-render-interval <ms>', 'Governor ceiling in ms (33-1000, default 320)')
         .option('--no-color', 'Disable ANSI color')
         .option('--quiet', '(print mode) suppress tool/usage lines on stderr')
         .action(async (prompt, opts) => {

package/dist/commands/builtins.js

@@ -15,6 +15,7 @@ import { MODE_LABEL, nextMode } from '../agent/agent-mode.js';
 import { loadConfig } from '../config/load.js';
 import { loadSession, resolveSessionPath, saveSession } from '../session/persist.js';
 import { getLogger } from '../logging/logger.js';
+import { perfCommand } from './perf.js';
 const COMMANDS = [
     {
         name: 'help',
@@ -535,6 +536,10 @@ const COMMANDS = [
             ctx.toast('success', `Reloaded config: ${config.provider}:${config.model}.`);
         },
     },
+    // Lives in its own module because it is the ONLY built-in that reads the
+    // render layer, and threading `ui/render-cache.js` into this file would make
+    // every other command's import graph pull the renderer in with it.
+    perfCommand,
     {
         name: 'exit',
         aliases: ['quit'],

package/dist/commands/perf.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `/perf` — what the renderer is actually doing (tui-render-performance §5.4).
+ *
+ * SILENT DEGRADATION IS THE ONE THING A "robust" CLAIM CANNOT AFFORD. The
+ * governor makes the stream chunkier under load, the retain ring drops old
+ * entries, and virtualisation mounts a fraction of the transcript. Every one of
+ * those is invisible by design, so there has to be one place that names them.
+ *
+ * The snapshot crosses the React boundary through a module-level single slot,
+ * the shape `ui/exit-snapshot.ts` already uses and for the same reason: a
+ * command runs outside the render pass and has no other way to reach `App`'s
+ * refs.
+ *
+ * READ-ONLY AND ALLOCATION-LIGHT. It renders as a NOTICE ENTRY rather than a
+ * live panel, because a performance readout that costs a repaint per second to
+ * display would be self-defeating.
+ */
+import type { SlashCommand } from './registry.js';
+export interface PerfSnapshot {
+    /** Governor rung, its resolved interval, and the last measured commit cost. */
+    rung: number;
+    intervalMs: number;
+    lastCommitMs: number;
+    governorEnabled: boolean;
+    /** Transcript accounting. */
+    totalEntries: number;
+    retain: number;
+    droppedEntries: number;
+    mountedEntries: number;
+    /** Height cache. */
+    heightsMeasured: number;
+    heightsEstimated: number;
+    cols: number;
+    /** Geometry. */
+    mode: 'fullscreen' | 'inline';
+    viewportRows: number;
+    offset: number;
+}
+/** Called by `App`. Passing `null` detaches. */
+export declare function setPerfSnapshotProvider(fn: (() => PerfSnapshot | null) | null): void;
+export declare function readPerfSnapshot(): PerfSnapshot | null;
+export declare function setPerfResetHook(fn: (() => void) | null): void;
+/** Format a snapshot as the five-line block documented in §5.4. */
+export declare function formatPerfReport(snap: PerfSnapshot): string;
+export declare const perfCommand: SlashCommand;

package/dist/commands/perf.js

@@ -0,0 +1,78 @@
+/**
+ * `/perf` — what the renderer is actually doing (tui-render-performance §5.4).
+ *
+ * SILENT DEGRADATION IS THE ONE THING A "robust" CLAIM CANNOT AFFORD. The
+ * governor makes the stream chunkier under load, the retain ring drops old
+ * entries, and virtualisation mounts a fraction of the transcript. Every one of
+ * those is invisible by design, so there has to be one place that names them.
+ *
+ * The snapshot crosses the React boundary through a module-level single slot,
+ * the shape `ui/exit-snapshot.ts` already uses and for the same reason: a
+ * command runs outside the render pass and has no other way to reach `App`'s
+ * refs.
+ *
+ * READ-ONLY AND ALLOCATION-LIGHT. It renders as a NOTICE ENTRY rather than a
+ * live panel, because a performance readout that costs a repaint per second to
+ * display would be self-defeating.
+ */
+import { clearRenderCaches, renderCacheStats } from '../ui/render-cache.js';
+/** Cleared on unmount, so `/perf` in a torn-down tree says so instead of lying. */
+let provider = null;
+/** Called by `App`. Passing `null` detaches. */
+export function setPerfSnapshotProvider(fn) {
+    provider = fn;
+}
+export function readPerfSnapshot() {
+    return provider ? provider() : null;
+}
+/** Reset hooks the App registers alongside the snapshot provider. */
+let resetGovernor = null;
+export function setPerfResetHook(fn) {
+    resetGovernor = fn;
+}
+function mb(bytes) {
+    return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+/** Format a snapshot as the five-line block documented in §5.4. */
+export function formatPerfReport(snap) {
+    const caches = renderCacheStats();
+    const eco = snap.rung > 0 ? '  -  eco' : '';
+    const governor = snap.governorEnabled ? '' : '  -  governor off';
+    return [
+        `render     rung ${snap.rung}  -  interval ${snap.intervalMs}ms  -  last commit ` +
+            `${Math.round(snap.lastCommitMs)}ms${eco}${governor}`,
+        `transcript ${snap.totalEntries} entries  -  ${snap.retain} retained  -  ` +
+            `${snap.droppedEntries} dropped  -  ${snap.mountedEntries} mounted`,
+        `heights    ${snap.heightsMeasured} cached  -  ${snap.heightsEstimated} estimated  -  ` +
+            `cols ${snap.cols}`,
+        `caches     md ${caches.markdownEntries} (${mb(caches.markdownBytes)})  -  ` +
+            `hl ${caches.highlightEntries} (${mb(caches.highlightBytes)})  -  ` +
+            `lines ${caches.lineEntries}`,
+        `mode       ${snap.mode}  -  viewport ${snap.viewportRows} rows  -  offset ${snap.offset}`,
+    ].join('\n');
+}
+export const perfCommand = {
+    name: 'perf',
+    description: 'Render statistics (/perf reset clears the caches and the governor)',
+    run: (ctx) => {
+        const arg = ctx.args.trim().toLowerCase();
+        if (arg === 'reset') {
+            clearRenderCaches();
+            resetGovernor?.();
+            ctx.toast('success', 'Render caches cleared, governor reset.');
+            return;
+        }
+        if (arg.length > 0) {
+            ctx.notify('warn', `Unknown argument "${arg}" - use /perf [reset].`);
+            return;
+        }
+        const snap = readPerfSnapshot();
+        if (!snap) {
+            // Reachable from a headless / detached tree. Saying so beats printing a
+            // block of zeroes that reads like a renderer doing nothing.
+            ctx.notify('info', 'No render statistics: the TUI is not mounted.');
+            return;
+        }
+        ctx.notify('info', formatPerfReport(snap));
+    },
+};

package/dist/config/env.d.ts

@@ -7,7 +7,9 @@
  *   - Overrides: ARAGON_PROVIDER, ARAGON_MODEL, ARAGON_BASE_URL, ARAGON_THINKING,
  *     ARAGON_MAX_TOKENS (a number, or `auto` / `0` for the per-model ceiling),
  *     ARAGON_THEME, ARAGON_MOUSE, ARAGON_PLAN, ARAGON_TEAM,
- *     ARAGON_TEAM_MAX, ARAGON_LOG_LEVEL, ARAGON_LOG_FILE, ARAGON_LOG_DIR.
+ *     ARAGON_TEAM_MAX, ARAGON_LOG_LEVEL, ARAGON_LOG_FILE, ARAGON_LOG_DIR,
+ *     ARAGON_TRANSCRIPT_RETAIN, ARAGON_RENDER_GOVERNOR,
+ *     ARAGON_MAX_RENDER_INTERVAL_MS.
  *
  * NOT here: `ARAGON_HOME`. It is read when `config/app-paths.ts` is first
  * evaluated, which is long before `loadDotenv()` runs, so a `.env` can never

package/dist/config/env.js

@@ -7,7 +7,9 @@
  *   - Overrides: ARAGON_PROVIDER, ARAGON_MODEL, ARAGON_BASE_URL, ARAGON_THINKING,
  *     ARAGON_MAX_TOKENS (a number, or `auto` / `0` for the per-model ceiling),
  *     ARAGON_THEME, ARAGON_MOUSE, ARAGON_PLAN, ARAGON_TEAM,
- *     ARAGON_TEAM_MAX, ARAGON_LOG_LEVEL, ARAGON_LOG_FILE, ARAGON_LOG_DIR.
+ *     ARAGON_TEAM_MAX, ARAGON_LOG_LEVEL, ARAGON_LOG_FILE, ARAGON_LOG_DIR,
+ *     ARAGON_TRANSCRIPT_RETAIN, ARAGON_RENDER_GOVERNOR,
+ *     ARAGON_MAX_RENDER_INTERVAL_MS.
  *
  * NOT here: `ARAGON_HOME`. It is read when `config/app-paths.ts` is first
  * evaluated, which is long before `loadDotenv()` runs, so a `.env` can never
@@ -177,6 +179,34 @@ export function readEnvConfig() {
         if (Object.keys(section).length > 0)
             partial.todo = section;
     }
+    // Render bounds (tui-render-performance §5.3). Same channel story as
+    // ARAGON_FULLSCREEN: a container or a wrapper that owns argv can reach neither
+    // a flag nor a config file, and a session that freezes is exactly the case
+    // where the user needs a knob they can turn from the outside.
+    //
+    // ARAGON_TRANSCRIPT_RETAIN / ARAGON_MAX_RENDER_INTERVAL_MS are left ABSENT
+    // when unparseable rather than written as a default, so the config file can
+    // still win — the rule `ARAGON_TEAM_MAX` above records.
+    const retain = process.env.ARAGON_TRANSCRIPT_RETAIN?.trim();
+    if (retain !== undefined && retain.length > 0) {
+        const parsed = Number.parseInt(retain, 10);
+        if (Number.isFinite(parsed) && parsed > 0)
+            partial.transcriptRetain = parsed;
+    }
+    // Parsed by the POSITIVE list, exactly as ARAGON_FULLSCREEN / ARAGON_MOUSE /
+    // ARAGON_PLAN / ARAGON_TEAM / ARAGON_TODO are — NOT by `envBool` below, which
+    // uses a negative list. The two readers disagree on `ARAGON_RENDER_GOVERNOR=disable`.
+    const governor = process.env.ARAGON_RENDER_GOVERNOR?.trim().toLowerCase();
+    if (governor !== undefined && governor.length > 0) {
+        partial.renderGovernor =
+            governor === '1' || governor === 'true' || governor === 'on' || governor === 'yes';
+    }
+    const renderInterval = process.env.ARAGON_MAX_RENDER_INTERVAL_MS?.trim();
+    if (renderInterval !== undefined && renderInterval.length > 0) {
+        const parsed = Number.parseInt(renderInterval, 10);
+        if (Number.isFinite(parsed) && parsed > 0)
+            partial.maxRenderIntervalMs = parsed;
+    }
     const log = readEnvLogConfig();
     if (log)
         partial.log = log;

package/dist/config/load.d.ts

@@ -85,6 +85,20 @@ export interface CliFlags {
     logFile?: boolean;
     /** `--log-dir <dir>` — this run only. */
     logDir?: string;
+    /** `--transcript-retain <n>` — the `ViewState` ring cap for this run (L1). */
+    transcriptRetain?: string | number;
+    /**
+     * `--render-governor` ⇒ true, `--no-render-governor` ⇒ false, absent ⇒
+     * undefined (L4).
+     *
+     * DECLARED AS A PAIR for the reason `--todo-panel` records: `renderGovernor`
+     * is PERSISTED, so a lone `--no-render-governor` would make commander default
+     * `opts.renderGovernor` to `true` and silently overwrite a stored `false` on
+     * every run that passed no flag at all.
+     */
+    renderGovernor?: boolean;
+    /** `--max-render-interval <ms>` — the governor ceiling for this run (L4). */
+    maxRenderInterval?: string | number;
 }
 /**
  * Resolve the effective config by merging all layers, then derive the runtime

package/dist/config/load.js

@@ -6,11 +6,12 @@
  * legitimately long single tool run can never be watchdog-killed.
  */
 import process from 'node:process';
-import { DEFAULT_CONFIG, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampLogConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampTheme, clampThinkingLevel, clampMaxTokens, clampTranscriptWindow, coercePositiveInt, isAutoToken, isSkillsToolPolicyMode, } from './schema.js';
+import { DEFAULT_CONFIG, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampLogConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampTheme, clampThinkingLevel, clampMaxTokens, clampMaxRenderInterval, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAutoToken, isSkillsToolPolicyMode, } from './schema.js';
 import { loadDotenv, readEnvConfig, readEnvDisabledSkills } from './env.js';
 import { readConfigFile } from './store.js';
 import { getConfigPath } from './app-paths.js';
 import { setHistoryEnabled } from './prompt-history.js';
+import { setEntryRetain } from '../agent/entry-limits.js';
 import { readSubmitCount } from './ui-state.js';
 import { getLogger } from '../logging/logger.js';
 import { registerSecret, registerSecretsFrom } from '../logging/secret-registry.js';
@@ -120,6 +121,25 @@ function resolveTodoConfig(flags, env, file) {
         ...(flags.todoFollow !== undefined ? { followThrough: flags.todoFollow } : {}),
     });
 }
+/**
+ * Resolve the adaptive render governor: flag › env › file › default `true`
+ * (tui-render-performance L4).
+ *
+ * Shaped like `resolveMouse` rather than like `resolveFullscreen`: there are no
+ * heuristics for an explicit `true` to override, so a persisted `true` is just a
+ * value and not an opinion that has to be told apart from silence. `!==
+ * undefined` on the flag is what makes `--no-render-governor` beat a config file
+ * that turned it on (P1-4's rule, one feature later).
+ */
+function resolveRenderGovernor(flags, env, file) {
+    if (flags.renderGovernor !== undefined)
+        return flags.renderGovernor;
+    if (env.renderGovernor !== undefined)
+        return env.renderGovernor;
+    if (file.renderGovernor !== undefined)
+        return file.renderGovernor;
+    return DEFAULT_CONFIG.renderGovernor;
+}
 /** Merge the `log` section across all four layers (defaults › file › env › flags). */
 function resolveLogConfig(flags, env, file) {
     const merged = clampLogConfig({
@@ -268,6 +288,23 @@ export function loadConfig(flags = {}) {
     // The prompt-history store is a module-level singleton, so the resolved value
     // has to be pushed into it — this is the ONLY place that happens.
     setHistoryEnabled(historyEnabled);
+    // Transcript bounds (tui-render-performance L1 / L3).
+    //
+    // `transcriptRetain` is RAISED TO `transcriptWindow` when the two conflict:
+    // retaining fewer entries than the window can scroll to would silently make
+    // part of the window unreachable, and the user would see a horizon they can
+    // never actually reach.
+    //
+    // The raise is REPORTED, not just performed (§5.1). Overriding a value the
+    // user typed and saying nothing is the one thing this feature is not allowed
+    // to add — every other adjustment it makes is announced somewhere, and a
+    // config key is the last place to start making exceptions.
+    const transcriptWindow = clampTranscriptWindow(pick(env.partial.transcriptWindow, file.transcriptWindow), DEFAULT_CONFIG.transcriptWindow);
+    const requestedRetain = clampTranscriptRetain(pick(flags.transcriptRetain, env.partial.transcriptRetain, file.transcriptRetain), DEFAULT_CONFIG.transcriptRetain);
+    const transcriptRetain = Math.max(transcriptWindow, requestedRetain);
+    // `viewReducer` is pure and takes no config, so the resolved ring cap reaches
+    // it through the same module-singleton channel `setHistoryEnabled` uses.
+    setEntryRetain(transcriptRetain);
     const config = {
         provider,
         model,
@@ -280,7 +317,11 @@ export function loadConfig(flags = {}) {
         exitTranscript: flags.exitTranscript !== undefined
             ? flags.exitTranscript
             : file.exitTranscript ?? DEFAULT_CONFIG.exitTranscript,
-        transcriptWindow: clampTranscriptWindow(file.transcriptWindow, DEFAULT_CONFIG.transcriptWindow),
+        transcriptWindow,
+        transcriptRetain,
+        ...(requestedRetain < transcriptRetain ? { transcriptRetainRequested: requestedRetain } : {}),
+        renderGovernor: resolveRenderGovernor(flags, env.partial, file),
+        maxRenderIntervalMs: clampMaxRenderInterval(pick(flags.maxRenderInterval, env.partial.maxRenderIntervalMs, file.maxRenderIntervalMs), DEFAULT_CONFIG.maxRenderIntervalMs),
         confirmTools,
         toolTimeoutMs,
         idleTimeoutMs,

package/dist/config/schema.d.ts

@@ -64,15 +64,40 @@ export declare const DEFAULT_IDLE_TIMEOUT_MS: number;
  */
 export declare const PROMPT_HISTORY_CAP = 100;
 /**
- * How many trailing entries the full-screen viewport renders (invariant I-3).
- * Yoga lays out every child even when `overflow: hidden` clips it, so the cost
- * of a long session is linear in the entry count regardless of visibility. The
- * reducer and `/save` keep the full history — this is a render-layer bound only.
+ * The SCROLL HORIZON: entries older than this are not reachable inside the app
+ * and render as the "N earlier entries collapsed" line instead (invariant I-3).
+ *
+ * It used to be a rendering budget as well, because yoga laid out every child
+ * even when `overflow: hidden` clipped it. The viewport is virtualised now
+ * (tui-render-performance L3) — off-screen entries are not mounted at all — so
+ * the horizon costs O(entries) of arithmetic rather than O(characters) of layout
+ * and the default rises 300 -> 1000 with a 20000 ceiling. An existing persisted
+ * `300` is still valid and still clamps; no config migration is required.
  */
-export declare const DEFAULT_TRANSCRIPT_WINDOW = 300;
+export declare const DEFAULT_TRANSCRIPT_WINDOW = 1000;
 export declare const MIN_TRANSCRIPT_WINDOW = 50;
-export declare const MAX_TRANSCRIPT_WINDOW = 2000;
+export declare const MAX_TRANSCRIPT_WINDOW = 20000;
 export declare function clampTranscriptWindow(v: unknown, fallback: number): number;
+/**
+ * Entries kept in `ViewState` at all (tui-render-performance L1 / R5).
+ *
+ * A DIFFERENT BOUND FROM `transcriptWindow`, and the two must not be merged:
+ * the window is what the user can scroll to, this is what the process keeps in
+ * memory and what `/save` can export. Dropped entries are COUNTED and reported
+ * (`/perf`, and a leading line in the exported transcript) — never silent.
+ */
+export declare const DEFAULT_TRANSCRIPT_RETAIN = 1000;
+export declare const MIN_TRANSCRIPT_RETAIN = 200;
+export declare const MAX_TRANSCRIPT_RETAIN = 20000;
+export declare function clampTranscriptRetain(v: unknown, fallback: number): number;
+/** Adaptive coalescing under load. On by default; `--no-render-governor` kills it. */
+export declare const DEFAULT_RENDER_GOVERNOR = true;
+/**
+ * Ceiling of the governor ladder, in ms. `33` flattens the ladder to a single
+ * rung, which is the pre-feature behaviour without needing the kill switch.
+ */
+export declare const DEFAULT_MAX_RENDER_INTERVAL_MS = 320;
+export declare function clampMaxRenderInterval(v: unknown, fallback: number): number;
 /** `ask_user` calls allowed per user turn. */
 export declare const DEFAULT_PLAN_MAX_ASK_ROUNDS = 4;
 /**
@@ -300,8 +325,14 @@ export interface PersistedConfig {
     fullscreen: boolean;
     /** Replay a plain-text session summary after leaving the alternate screen. */
     exitTranscript: boolean;
-    /** Trailing entries the full-screen viewport renders (I-3). */
+    /** Entries reachable by scrolling; older ones show the "collapsed" line (I-3). */
     transcriptWindow: number;
+    /** Entries kept in `ViewState`; older ones are dropped and counted (L1). */
+    transcriptRetain: number;
+    /** Adaptive coalescing under load (L4). */
+    renderGovernor: boolean;
+    /** Ceiling of the governor ladder in ms; `33` flattens it (L4). */
+    maxRenderIntervalMs: number;
     confirmTools: boolean;
     toolTimeoutMs: number;
     idleTimeoutMs: number;
@@ -390,8 +421,30 @@ export interface CliConfig {
     fullscreen?: boolean;
     /** Replay a plain-text summary on exit (full-screen only — see §4.4). */
     exitTranscript: boolean;
-    /** Trailing entries the full-screen viewport renders (I-3). */
+    /** Entries reachable by scrolling; older ones show the "collapsed" line (I-3). */
     transcriptWindow: number;
+    /**
+     * Entries kept in `ViewState` (L1).
+     *
+     * Resolved to be `>= transcriptWindow`: retaining fewer entries than the
+     * window can scroll to would silently make part of the window unreachable.
+     */
+    transcriptRetain: number;
+    /**
+     * What the user actually asked `transcriptRetain` to be, present ONLY when
+     * that value had to be raised (§5.1).
+     *
+     * A setting ignored without a word is the one failure mode this feature is
+     * not allowed to add: the eco chip, `/perf` and the dropped-entry line all
+     * exist so that nothing it does happens unannounced, and a config key
+     * overwritten in silence would be the exception. `undefined` means nothing
+     * was overridden, which is every default session.
+     */
+    transcriptRetainRequested?: number;
+    /** Adaptive coalescing under load (L4). */
+    renderGovernor: boolean;
+    /** Ceiling of the governor ladder in ms; `33` flattens it (L4). */
+    maxRenderIntervalMs: number;
     confirmTools: boolean;
     toolTimeoutMs: number;
     idleTimeoutMs: number;

package/dist/config/schema.js

@@ -98,18 +98,52 @@ export const DEFAULT_IDLE_TIMEOUT_MS = DEFAULT_TOOL_TIMEOUT_MS + IDLE_TIMEOUT_MA
  */
 export const PROMPT_HISTORY_CAP = 100;
 /**
- * How many trailing entries the full-screen viewport renders (invariant I-3).
- * Yoga lays out every child even when `overflow: hidden` clips it, so the cost
- * of a long session is linear in the entry count regardless of visibility. The
- * reducer and `/save` keep the full history — this is a render-layer bound only.
+ * The SCROLL HORIZON: entries older than this are not reachable inside the app
+ * and render as the "N earlier entries collapsed" line instead (invariant I-3).
+ *
+ * It used to be a rendering budget as well, because yoga laid out every child
+ * even when `overflow: hidden` clipped it. The viewport is virtualised now
+ * (tui-render-performance L3) — off-screen entries are not mounted at all — so
+ * the horizon costs O(entries) of arithmetic rather than O(characters) of layout
+ * and the default rises 300 -> 1000 with a 20000 ceiling. An existing persisted
+ * `300` is still valid and still clamps; no config migration is required.
  */
-export const DEFAULT_TRANSCRIPT_WINDOW = 300;
+export const DEFAULT_TRANSCRIPT_WINDOW = 1000;
 export const MIN_TRANSCRIPT_WINDOW = 50;
-export const MAX_TRANSCRIPT_WINDOW = 2000;
+export const MAX_TRANSCRIPT_WINDOW = 20_000;
 export function clampTranscriptWindow(v, fallback) {
     const n = coercePositiveInt(v, fallback);
     return Math.min(MAX_TRANSCRIPT_WINDOW, Math.max(MIN_TRANSCRIPT_WINDOW, n));
 }
+/**
+ * Entries kept in `ViewState` at all (tui-render-performance L1 / R5).
+ *
+ * A DIFFERENT BOUND FROM `transcriptWindow`, and the two must not be merged:
+ * the window is what the user can scroll to, this is what the process keeps in
+ * memory and what `/save` can export. Dropped entries are COUNTED and reported
+ * (`/perf`, and a leading line in the exported transcript) — never silent.
+ */
+export const DEFAULT_TRANSCRIPT_RETAIN = 1000;
+export const MIN_TRANSCRIPT_RETAIN = 200;
+export const MAX_TRANSCRIPT_RETAIN = 20_000;
+export function clampTranscriptRetain(v, fallback) {
+    const n = coercePositiveInt(v, fallback);
+    return Math.min(MAX_TRANSCRIPT_RETAIN, Math.max(MIN_TRANSCRIPT_RETAIN, n));
+}
+// ---------------------------------------------------------------------------
+// Adaptive render governor (tui-render-performance L4 / R7)
+// ---------------------------------------------------------------------------
+/** Adaptive coalescing under load. On by default; `--no-render-governor` kills it. */
+export const DEFAULT_RENDER_GOVERNOR = true;
+/**
+ * Ceiling of the governor ladder, in ms. `33` flattens the ladder to a single
+ * rung, which is the pre-feature behaviour without needing the kill switch.
+ */
+export const DEFAULT_MAX_RENDER_INTERVAL_MS = 320;
+const RENDER_INTERVAL_RANGE = { min: 33, max: 1000 };
+export function clampMaxRenderInterval(v, fallback) {
+    return clampInt(v, fallback, RENDER_INTERVAL_RANGE);
+}
 // ---------------------------------------------------------------------------
 // Plan mode (plan-mode §4.4)
 //
@@ -360,6 +394,9 @@ export const DEFAULT_CONFIG = {
     fullscreen: true,
     exitTranscript: true,
     transcriptWindow: DEFAULT_TRANSCRIPT_WINDOW,
+    transcriptRetain: DEFAULT_TRANSCRIPT_RETAIN,
+    renderGovernor: DEFAULT_RENDER_GOVERNOR,
+    maxRenderIntervalMs: DEFAULT_MAX_RENDER_INTERVAL_MS,
     confirmTools: false,
     toolTimeoutMs: DEFAULT_TOOL_TIMEOUT_MS,
     idleTimeoutMs: DEFAULT_IDLE_TIMEOUT_MS,